FundMakerFDN EVM Contracts - Cross-Chain CA Management System

A comprehensive system for managing Custody Agreements (CA) across multiple EVM chains with secure proof of possession verification.

Architecture Overview

The system consists of three main components:

1. OTCCustody: Core contract for CA (Proof of Possession Management) operations and actions including Custody Agreement (CA) management, deployment and whitelisting of various Connectors, calling various actions on Connectors including cross-chain interactions, and funds management between custodies.
2. Connector: User-centric smart manager accounts that can be used to manage CA operations integrated with multiple DeFi protocols including Across, CCIP, AAVE, Uniswap V3, and more.
3. CA (Custody Agreement): A data structure representing the custody relationship between parties, including:
   • Proof of possession verification
   • Token custody details
   • Cross-chain state management

Key Components

Smart Contracts

• OTCCustody.sol: Main contract for core business logic including CA management, Connector whitelisting, and other actions on custodies.
• CCIPConnector.sol: Handles cross-chain message passing for cross-chain CA updates
• CCIPReceiver.sol: Receives and processes cross-chain messages
• UniswapV3Connector.sol: Uniswap V3 Connector implementation
• AcrossConnector.sol: Across Protocol Connector implementation (V3)

Test Suite

• 01-otcCustody.test.ts: Core OTCCustody functionality tests
• 02-etf-operations.test.ts: ETF-specific operations
• 03-settlement.test.ts: Settlement system tests
• 04-ca-helper.test.ts: CAHelper utility tests
• 05-uniswap-v3-connector.test.ts: Uniswap V3 Connector integration tests
• 06-ccip-connector.test.ts: CCIP Connector integration tests
• 08-across-connector.test.ts: Across Connector integration tests

Scripts

• 06-ccip-ca-update.ts: Cross-chain CA update script (Currently working on SepoliaBase testnet)
• 07-across-deposit.ts: Script for Across's deposit and relay functions (Currently working on SepoliaBase testnet and handled by MockSpokePool)

Utils

• CAHelper.ts: Helper class for CA operations including Merkle proof generation and verification.

Important Terminologies

OTCCustody

The core contract that:

• Manages CA lifecycle
• Verifies proof of possession
• Handles token custody
• Coordinates with Connectors

Connector

A bridge adapter that handles cross-chain operations:

• Message passing between chains
• Token bridging
• State synchronization

CA (Custody Agreement)

A data structure representing the custody relationship between parties, including:

• Proof of possession verification
• Token custody details
• Cross-chain state management

Development Setup

Prerequisites

• Node.js >= 18
• pnpm (recommended) or npm
• Hardhat
• Solidity ^0.8.28

Installation

# Clone the repository
git clone https://github.com/FundMakerFdn/evm-contracts.git
cd evm-contracts

# Install dependencies
pnpm install

# Compile contracts
pnpm compile

Environment Setup

Create a .env file:

PRIVATE_KEY=your_private_key
ARBITRUM_RPC_URL=your_arbitrum_rpc
BASE_RPC_URL=your_base_rpc
ETHERSCAN_API_KEY=your_etherscan_key

Testing

# Run all tests
pnpm test

# Run specific test file
pnpm test tests/01-otcCustody.test.ts

# Run with gas reporting
REPORT_GAS=true pnpm test

Deployment

# Deploy to Arbitrum
pnpm hardhat run scripts/03-deploy-arbi.ts --network arbitrum

# Deploy to Base
pnpm hardhat run scripts/04-deploy-base.ts --network base

CA Update Flow

1. User calls sendUpdateCA on OTCCustody source with Merkle proof
2. OTCCustody runs Merkle proof verification
3. OTCCustody updates CA locally on source chain
4. Bot listens to updateCA event
5. Prepares call data for source Connector's sendUpdateCA function
6. Call data includes _verificationData with Merkle proof
7. Bot calls sendUpdateCA of Connector with prepared call data
8. Connector calls getCA(custodyId) of OTCCustody and fetches the latest CA
9. Connector calls sendMessage of CCIP Helper
10. Message contains: New CA, Verification data
11. CCIP Router receives message
12. Forwards to destination CCIP Receiver
13. Calls ccipReceive with encoded message containing: New CA, Verification data
14. Destination CCIP Receiver receives message
15. Calls handleCCIPMessage of Connector destination
16. Passes decoded message with: New CA, Verification data
17. Connector destination receives message
18. Calls updateCA of OTCCustody destination
19. Destination OTCCustody runs Merkle proof verification
20. Updates CA locally on destination chain

Development Guidelines

Adding New Connectors

1. Create new Connector contract implementing IConnector interface
2. Add Connector-specific tests in tests folder (e.g. tests/07-across-connector.test.ts)
3. Update production deployment scripts in scripts/07-deploy-across.ts to

Testing New Features

1. Write unit tests for core functionality
2. Add integration tests for cross-chain operations
3. Test with different token types
4. Verify gas optimization

Security Considerations

• Always verify Merkle proofs
• Check Connector whitelist
• Validate cross-chain messages
• Use secure random number generation
• Implement proper access control

Contributing

1. Fork the repository
2. Create feature branch
3. Commit changes
4. Push to branch
5. Create Pull Request

Important Notes

• Currently working on SepoliaBase testnet
• Using MockSpokePool for Across's deposit and relay functions
• All Connectors are deployed using Factory pattern via deployConnector function in OTCCustody.sol except for AcrossConnector and CCIPConnector which are deployed independently.
• All actions on Connectors are performed via callConnector function in OTCCustody.sol except for Across and CCIP which are handled by the Connectors themselves.
• All of the off-chain actions related to CA (Custody Agreement) are handled by the CAHelper.ts utility class. This includes Merkle proof generation and verification, CA management, and other actions on CA.
• Whenever a custody is created in OTCCustody, a new CA is created locally using the CAHelper.ts utility class. This CA has a unique ID which is used to identify the CA called custodyId.
• At the current implementation, the custodyId is the first ever merkle root of the CA which can be fetched via getCustodyID() function in CAHelper.
• When you add any action to the CA using CAHelper.ts, you can fetch the latest merkle root of the CA using getCARoot() function in CAHelper.

License

MIT

(Note for later), Voting power of Index is not made crosschain, votes snapshot needs to be bridgeable.