## **Contract Secured Revenue (CSR) SDK Technical Specification** (WIP)

*TODO:*
- Accounting logic (Lagrange) ✅
- User opt-in logic (EAS)
- Analytics (Dune)

### **1. Introduction**

The CSR SDK provides a mechanism for smart contract developers to claim a percentage of transaction fees when users interact with their contracts on EVM-based L2s. This specification outlines the architecture, components, and workflow of the SDK, integrating the Ethereum Attestation Service (EAS), Lagrange Labs' Recproofs and NFTs for payments. The architecture presented in this document does not present any changes to the consensus layer and is intended for implementation on the application layer. The architecture is designed to have identical security to a consensus layer implementation.

### **2. System Architecture**

#### **2.1 Core Components**

- **SequencerFeeVault**:
- **Description**: [This contract](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/SequencerFeeVault.sol) acts as a repository for all the fees accrued by the sequencer during transaction processing and block production.
- **Attributes**:
- `totalFees`: Total fees collected by the sequencer.
- `pendingPayouts`: Mapping of NFT addresses to their pending payout amounts.
- `gasUsedByAddress`: Mapping of contract addresses to the amount of gas they consumed.
- **Methods**:
- `depositFees(uint256 amount)`: Allows the sequencer to deposit fees.
- `optInToCSR()`: Allows the sequencer to opt into the CSR system.
- `setCSRPercentage(uint256 percentage)`: Sets the CSR percentage. Arbitrary value determined by sequencer or DAO.
- `calculatePayout(address contractAddress)`: Calculates the payout for a specific contract based on its gas consumption.
- `distributeFees(Proof memory proof, uint256 amount)`: Distributes the fees to the NFT holders.
- `withdrawFees(address nftAddress, Proof memory proof, uint256 amount)`: Allows NFT holders to withdraw their share of the fees. Calls the verifyProof function within the Lagrange verification contract.
- `trackGasUsage(address contractAddress, uint256 gasUsed)`: Tracks the gas used by each contract.

- **CSR Manager**:
- **Description**: Central component responsible for the overall management of the CSR system.
- **Methods**:
- `initiatePayout()`: Triggers a manual payout using the SequencerFeeVault's `distributeFees` method.

- <strike>**Accounting Ledger**:
- **Description**: Maintains records of transaction fees and CSR allocations.
- **Methods**:
- `updateFees(uint256 fee)`: Updates the total fees collected.
- `getTotalFees()`: Returns the total fees collected.
- `getCSRAmount()`: Returns the total CSR amount.</strike>

- **EAS Interface**:
- **Description**: Enables interactions with the Ethereum Attestation Service.
- **Methods**:
- `verifyAttestation(address user)`: Verifies a user's attestation, I guess. Idk, Steve, why don't you help out here for a change. Jfc.

- **Lagrange Interface**:
- **Description**: Enables verification of Lagrange Recproofs to trigger a payout.
- **Methods**:
- `verifyProof(address user, uint256 amount, uint256 startBlock, uint256 endBlock, Proof memory proof)`: Verifies a proof that a contract is entitled to receive a payment of `amount` based on usage between `startBlock` and `endBlock`,

- **NFT Payment Distributor**:
- **Description**: Manages NFTs and their associated payments. This allows for composability. NFT holder receives CSR reward. NFT can then be fractionalized or used as collateral within other systems.
- **Methods**:
- `issueNFT(address user)`: Issues an NFT to a user and returns the NFT address.
- `getNFTBalance(address nftAddress)`: Returns the balance of an NFT.

### **3. Workflow**

1. **Opt-In via Attestation**:
- Users emit an attestation via the EAS to opt into CSR.
- The Attestation Verifier checks the attestation's validity.

2. **NFT Issuance**:
- Verified users receive an NFT issued by the NFT Payment Distributor.

3. **Transaction Processing**:
- For each transaction, the CSR Manager computes the CSR amount.
- <strike>The Accounting Ledger updates its records</strike>.
- The Sequencer deposits the fees into the SequencerFeeVault.

4. **Sequencer Opt-In**:
- The sequencer opts into the CSR system using the `optInToCSR()` method in the SequencerFeeVault.

5. **Scheduled Payouts**:
- <strike> The CSR Manager checks conditions and triggers payouts when necessary</strike>.
- <strike>The SequencerFeeVault calculates the payout for each contract and distributes the CSR amount to the NFT Payment Distributor</strike>.
- <strike>The NFT Payment Distributor distributes payments to NFTs</strike>.
- ( **Suggested flow**) A user submits a proof to SequencerFeeVault proving that between a range of blocks they are entitled to a specific amount of fees
- ( **Suggested flow**) If the proof is verified by the Lagrange Verifier contract than the NFT Payment Distributor distributes payments to NFT.

### **4. Interfaces**

- **ISequencerFeeVault**: Interface for the SequencerFeeVault.
- **ICSRManager**: Interface for the CSR Manager.
- <strike>**IAccountingLedger**: Interface for the Accounting Ledger.</strike>
- **IEASInterface**: Interface for the Ethereum Attestation Service.
- **ILagrangeVerifier**: Interface for verifying Lagrange Recproofs.
- **INFTPaymentDistributor**: Interface for the NFT Payment Distributor.

### **5. Considerations**

- **Transparency**: Ensure on-chain transparency for all CSR-related transactions.
- **Security**: Implement robust security using measures to prevent unauthorized access and changes. Fees should only be distributed based on zero-knowledge proofs of onchain activity.
- **Efficiency**: Optimize for minimal overhead during transaction processing. Transaction processing can be done offchain and proven back onchain with zero-knowledge proofs.
- **Flexibility**: Allow for easy updates and modifications to the CSR percentage.

### **6. Future Enhancements**

- **Reporting & Analytics**: Implement tools for detailed CSR statistics and historical data.(Dune)
- ( **Suggested flow**) **Trustless Computation**: Continually leverage zero-knowledge proofs for reward distribution so that application level CSR can inherit consensus level security.
- <strike>**Threshold-based Payouts**: Enhance the Payout Scheduler to trigger payouts based on thresholds.</strike>
- **EAS Enhancements**: Continuously integrate updates and features from the Ethereum Attestation Service.

### **7. Conclusion**

The CSR SDK offers a comprehensive solution for smart contract developers to benefit from transaction fees on EVM-based L2s. By integrating the Ethereum Attestation Service, Lagrange Labs' Recproofs and utilizing NFTs for payments, the system offers a unique, transparent, and efficient mechanism for revenue distribution. The sequencer's ability to opt into the system and manage payouts directly from the SequencerFeeVault adds flexibility and control to the revenue distribution process.