# Fil+ Programmable Allocator & Possible Smart Contract Architecture

This document outlines a possible modular smart contract architecture for a Programmable Datacap Allocator on Filecoin. Each component plays a distinct role in facilitating secure and programmable datacap distribution via auctions.

---

## Overview: Core Idea

The allocator runs in discrete time rounds and distributes datacap proportionally to the **reported on-chain deal revenue** by each SP.

### Key Features

- **Revenue-based rewards** — More deal revenue → more datacap
- **Competition-based mechanism** — SPs compete for a fixed datacap pool
- **Fee burn to resist wash trading** — A fraction of revenue is burnt to add cost to fake deals

#### Datacap Allocation Mechanism
The Allocator distributes datacap to Storage Providers (SPs) proportionally to their declared deal revenue using a competitive auction mechanism. The mathematical model that powers this allocation is designed to:
1. Reward SPs who generate real economic value through storage deals
2. Create incentives for honest revenue reporting
3. Balance short-term and long-term participation benefits

#### Core Allocation Formula
For each auction round datacap is issued to the SPs:

$$D_i(r_i) = d \cdot \frac{r_i}{\sum_j r_j}$$

Where:
- $D_i$ is the amount of datacap issued to the i-th SP
- $r_i$ is the declared deal revenue by the i-th SP
- $d$ is the total datacap issued each round
- $\sum_j r_j$ is the total declared deal revenue from all participating SPs

#### Fee Mechanism
Each SP pays a fee proportional to their declared revenue:
$$Fee_i = \gamma \cdot r_i$$

Where $\gamma$ is the fee rate parameter. A portion of this fee is burned, while the remainder is redirected to a protocol-owned wallet designated for ecosystem sustainability, ongoing development, and governance operations.

This fee structure serves as a critical economic deterrent against wash trading. Since higher declared revenues result in more datacap allocation but also incur larger fees, only SPs with genuine revenue from real user deals can sustainably participate. This creates a natural equilibrium where:

- SPs with legitimate deals can afford the fee because they receive actual payment from users
- SPs attempting to game the system through fake deals face diminishing returns as their costs increase
- The protocol captures value that is reinvested into the ecosystem

---
## Overview: Possible Smart Contracts Architecture
### Key components
- **`RevenueWallet`**: Multisig wallet that receives FIL from Storage Providers (SPs).
- **`DatacapWallet`**: Multisig wallet holding datacap provided by root key holders.
- **`ProtocolWallet`**: Wallet controlled by the protocol; receives a portion of the fees from each auction.
- **`VerifiedSPList`**: Verifies and registers eligible SPs through zero-FIL transactions.
- **`MasterBot`**: Coordinates auction rounds every 24 hours (triggered externally by **Gelato Web3 Functions**). Gathers auction data from RevenueBot, calculates rewards, fees, and initiates execution of transactions via multisig wallets.
- **`RevenueBot`**: Monitors the RevenueWallet for incoming SP contributions. Verifies SPs against VerifiedSPList. Maintains auctionInfo state containing declared revenues by SPs. Crafts and signs refund transactions from the RevenueWallet.
- **`DatacapBot`**: Tracks available datacap in DatacapWallet. Crafts and signs datacap reward transactions.

### Global Workflow
1. A Storage Provider (SP) registers via `VerifiedSPList`.
2. SP sends a revenue declaration tx in FIL to `RevenueWallet`.
3. `RevenueWallet` signals `RevenueBot`, which:
- Checks if the sender is a verified SP by querying `VerifiedSPList`;
- Stores the SP contribution (address, FIL) in `auctionInfo`.
5. External Automation (e.g., [Gelato Web3 Functions](https://docs.gelato.network/web3-services/web3-functions)) triggers `MasterBot.clearAuction` e.g. every 24 hours.
8. At each trigger, `MasterBot`:
- Checks if sufficient datacap is available in `DatacapWallet` via `DatacapBot`;
- Collects the current auction state from `RevenueBot` obtaining SP addresses and declared deal revenues;
- Computes Datacap to be issued per SP based on relative contribution;
- Computes the refund in FIL that need to be issued to each SP;
- Computes the fee amount that has to be burned and the fee amount that has to be sent to `ProtocolWallet`;
- Instructs `RevenueBot` and `DatacapBot` to craft and sign the transactions providing them SP adresses with associated FIL refund and datacap rewards.
11. `DatacapBot` and `RevenueBot` prepare and sign transactions.
12. `MasterBot` checks, signs and executes them via the multisig wallets.
13. Rewards are distributed; protocol fee goes to `ProtocolWallet`; remaining fee burned.

### Optional Offchain Application (Frontend)
An optional offchain application may be provided to offer visibility into the system:
- Displays current auction pool state (`auctionInfo` from `RevenueBot`);
- Shows countdown to the next auction round (e.g. based on last round timestamp + 24h);
- Allows SPs to assess whether it is strategic to declare their revenue at a given moment.

### Timing and Automation
The system could rely on [Gelato Web3 Functions](https://docs.gelato.network/web3-services/web3-functions) to:
- Trigger `MasterBot.clearAuction` on a daily schedule (e.g., every 24h);
- Ensure fully automated and trust-minimized operation.
- This decouples SP participation from the auction clearing logic and ensures a predictable rhythm of datacap distribution.

---
## Components
### 💰 DatacapWallet
**Type:** Smart contract multisig wallet
**Purpose:** Custodian of datacap tokens to be distributed to SPs after each auction round

#### Key Characteristics:
- Holds datacap tokens.
- Requires two signatures for outgoing transfers:
- `DatacapBot`;
- `MasterBot`.
- Exposes balance to `DatacapBot` for availability checks.

#### Core Functions:

function getBalance() external view returns (uint256);
  // Returns current datacap token balance held in the wallet.

function proposeTransaction(address to, uint256 amount, bytes calldata data) external returns (uint256);
  // Creates a new transaction proposal to transfer datacap.

function approveTransaction(uint256 txId) external;
  // Signs approval for a previously proposed transaction.

function executeTransaction(uint256 txId) external;
  // Executes a transaction after the required number of approvals.

#### Workflow:
1. `DatacapBot` proposes a transfer.
2. `MasterBot` approves and executes it.

---

### 💰 RevenueWallet
**Type:** Smart contract multisig wallet
**Purpose:** Receives FIL contributions from SPs and issues refunds post-auction

#### Key Characteristics:
- Receives FIL from Storage Providers.
- Requires two signatures for outgoing transfers:
- `RevenueBot`;
- `MasterBot`.
- Notifies `RevenueBot` upon receiving new contributions.

#### Core Functions:

function receiveContribution(address sp) external payable;
  // Receives FIL contribution and notifies RevenueBot.
  
function proposeTransaction(address to, uint256 amount, bytes calldata data) external returns (uint256);
  // Creates a new transaction proposal to refund FIL after auction completion.

function approveTransaction(uint256 txId) external;
  // Signs approval for the refund transaction.

function executeTransaction(uint256 txId) external;
  // Executes the transaction after required approvals.

#### Workflow:
1. SP sends FIL to `RevenueWallet`.
2. `RevenueWallet` notifies `RevenueBot` that a contribution has been made.
3. `RevenueBot` proposes a transfer.
4. `MasterBot` approves and executes it.

---

### 💼 ProtocolWallet
**Type:** Simple smart contract wallet
**Purpose:** Receives a portion of fees collected in each auction round

#### Key Characteristics:
- Receives a portion of FIL fees.
- Target destination for protocol-level revenue.

#### Core Functions:

function receiveFee() external payable;
  // Receives protocol fee.

function withdraw(address to, uint256 amount) external onlyOwner;
  // Allows withdrawal by the protocol's authorized owner.

---

### 🤖 MasterBot
**Type:** Smart contract orchestrator
**Purpose:** Clears the auction round on a fixed schedule. Computes datacap issuance and refunds based on declared SP contributions. Coordinates with `RevenueBot` and `DatacapBot` to prepare, approve, and execute reward and refund transactions.

#### Key Responsibilities:
- Manages timed auction rounds (e.g., every 24 hours).
- Coordinates with `RevenueBot` to fetch current `auctionInfo`.
- Coordinates with `DatacapBot` to verify available datacap.
- Computes:
- Datacap issuance per SP (proportional to declared revenue).
- Refunds in FIL per SP.
- Protocol fees and burn amounts.
- Instructs `RevenueBot` and `DatacapBot` to prepare and sign transactions.
- Validates and co-signs multisig transactions.
- Executes the transactions via the wallets.

#### Core Functions:

function clearAuction() external;
  // Called periodically by an external automation service (e.g., Gelato).
  // Performs the full auction clear logic.

function validateAndApproveRevenueTx(bytes32 txHash) external;
  // Approves and signs the RevenueBot-prepared refund transaction.

function validateAndApproveDatacapTx(bytes32 txHash) external;
  // Approves and signs the DatacapBot-prepared datacap grant transaction.

function executeTransaction(uint256 txId) external;
  // Executes a previously approved transaction (refund or grant).

#### State Variables:

uint64 public auctionDuration;       // Duration of each auction round in epochs or seconds.
uint64 public lastAuctionEpoch;      // Epoch of last cleared auction round.

address public revenueBot;
address public datacapBot;
address public revenueWallet;
address public datacapWallet;
address public protocolWallet;
address public burnAddress;

uint256 public minRequiredDatacap;   // Threshold below which no auction clearing occurs.

#### External Automation (e.g., Gelato Web3 Functions):
- Triggers `clearAuction()` every 24 hours.

---

---

### 🤖 RevenueBot
**Type:** Smart contract actor
**Purpose:** Manages SP contributions, proposes FIL refunds, co-signs transactions on `RevenueWallet`.

#### Key Responsibilities:
- Receives SP contribution information from `RevenueWallet`.
- Verify through `VerifiedSPList` that SP is verified.
- Maintains SP contribution records in `auctionInfo`.
- Co-signs `RevenueWallet` transactions.

#### Core Functions:

function receiveContribution(address sp) external payable;
  // Called by RevenueWallet to store SP's FIL contribution.

function proposeRefundTransactions(address[] sps, uint256[] amounts) external;
  // Proposes refund transactions to RevenueWallet.

function getAuctionInfo() external view returns (address[] memory sps, uint256[] memory contributions);
// Called by MasterBot to retrieve all SPs and their respective contributions.

function clearAuctionInfo() external;
// Called by MasterBot after clearAuction() to reset internal contribution records.

#### State Variables:

mapping(address => uint256) public auctionInfo;
address public revenueWallet;
address public masterBot;

---

### 🤖 DatacapBot
**Type:** Smart contract actor
**Purpose:** Crafts datacap issuance transactions based on instructions from `MasterBot`. Co-signs transactions on `DatacapWallet`

#### Key Functions:
- Provides datacap balance to `MasterBot`.
- Crafts datacap issuance transactions.
- Co-signs transactions from `DatacapWallet`.

#### Core Functions:

function getDatacapBalance() external view returns (uint256);
  // Queries current datacap balance from DatacapWallet.

function proposeGrantTransactions(address[] sps, uint256[] amounts) external;
  // Prepares datacap issuance proposals to SPs.

---

### 📜 VerifiedSPList
**Type:** Smart contract actor
**Purpose:** Maintains registry of Storage Providers (SPs) eligible to participate in auctions

#### Key Responsibilities:
- Registers and verifies SPs via on-chain interactions.
- Stores verification metadata.
- Ensures only verified SPs receive refund by `RevenueWallet` at the end of the auction.

#### Core Functions:

function registerSP(address sp) external;
  // Verifies SPs via a zero-value transaction.

function isVerified(address sp) external view returns (bool);
  // Checks verification status of an SP.

function getVerifiedSPs() external view returns (address[] memory);
  // Returns list of all verified SPs.

#### State Variables:

mapping(address => bool) public verifiedSPs;
address public masterBot;

---

# Architecture Evaluation: Programmable Datacap Allocator on Filecoin

## ✅ Pros

### 1. Modularity & Clear Separation of Concerns
- Each smart contract (bot or wallet) has a distinct role (e.g., `RevenueBot` handles SP contributions, `MasterBot` orchestrates auction logic).
- Promotes maintainability, reusability, and auditability.

### 2. Multisig Wallets Improve Security
- `DatacapWallet` and `RevenueWallet` require two signatures (from a bot and `MasterBot`) to approve and execute transactions.
- Reduces risk of unilateral fund movement from one contract.

### 3. Transparent and Verifiable On-Chain State
- Storage Provider (SP) registration and contributions are stored directly on-chain.
- Facilitates trustless audits, internal reporting, and contract composability.

### 4. Extensibility
- Architecture is designed to easily integrate new logic: SP slashing, tokenized auction shares, governance, etc.
- Each component can evolve independently.

### 5. Protocol-Level Enforcement
- SPs must be registered in `VerifiedSPList` before interacting with `RevenueBot`, enforcing protocol rules at the contract level.

---

## ⚠️ Cons / Challenges

### 1. Transactional Complexity & Gas Usage
- Multisig model introduces 3-step flows (propose, approve, execute).
- Auction rounds with many SPs may be gas-intensive.

### 2. Tooling and Ecosystem Maturity
- FVM is relatively young; dev tooling, SDKs, and dApp infrastructure are still evolving.
- Some actor-based patterns (like inter-contract calls with state updates) require extra care.

### 3. Upgradeability Coordination
- Modular architecture complicates upgrades: changing one bot might require coordination with other contracts.
- Requires proxy pattern or governance-controlled upgrade strategy.

---

## 🔐 Security Considerations

### 1. Multisig Governance Risks
- If either bot or `MasterBot` becomes compromised or buggy, funds may be frozen or misrouted.

### 2. Replay or Double-Execution of Transactions
- All transaction execution should validate unique identifiers (e.g., nonce or hash) to prevent replays.

### 3. Sybil Attack on SP Registration
- `VerifiedSPList` relies on zero-value registration transactions: risk of mass fake SPs.

### 4. Untrusted Bots
- Bots proposing transactions must be fully deterministic and verifiable.

---

## Summary

This architecture leverages modularity, multisig safety, and on-chain state visibility to deliver a secure and extensible auction mechanism for datacap distribution. While it introduces complexity and reliance on timing logic and transaction orchestration, the benefits in terms of control, flexibility, and protocol enforcement might justify the design trade-offs.