Deployment

Deploy Reserve Folio contracts to Ethereum, Base, and other networks

Overview

Reserve Folio uses Foundry’s scripting system for deterministic, reproducible deployments. The deployment process handles both genesis deployments (protocol infrastructure) and follow-up deployments (Folio instances).

Deployment Architecture

Deployments occur in two phases:

1. Genesis Deployment

   Deploy core protocol infrastructure:

   • FolioDAOFeeRegistry: DAO fee management
   • FolioVersionRegistry: Version control for upgrades
   • TrustedFillerRegistry: Whitelisted auction fillers
2. Protocol Deployment

   Deploy protocol contracts:

   • FolioDeployer: Factory for creating Folios
   • GovernanceDeployer: Factory for governance systems
   • Implementation contracts (Governor, Timelock, StakingVault)
   • Periphery contracts (Fillers, Lens)

Deployment Script

The main deployment script is located at script/Deploy.s.sol:

Deploy.s.sol

contract DeployScript is Script {
    // Deployment modes
    enum DeploymentMode {
        Production,
        Testing
    }
    
    // Set deployment mode before running
    DeploymentMode public deploymentMode = DeploymentMode.Production;
    
    function run() external {
        DeploymentParams memory params = deploymentParams[block.chainid];
        runGenesisDeployment(params);
    }
}

Supported Networks

Production Networks

Ethereum Mainnet

Chain ID: 1

Base

Chain ID: 8453

BNB Chain

Chain ID: 56

Network Configuration

Each network has predefined deployment parameters:

// Ethereum Mainnet
deploymentParams[1] = DeploymentParams({
    roleRegistry: 0xE1eC57C8EE970280f237863910B606059e9641C9,
    folioFeeRegistry: 0x0262E3e15cCFD2221b35D05909222f1f5FCdcd80,
    feeRecipient: 0xcBCa96091f43C024730a020E57515A18b5dC633B,
    folioVersionRegistry: 0xA665b273997F70b647B66fa7Ed021287544849dB,
    trustedFillerRegistry: 0x279ccF56441fC74f1aAC39E7faC165Dec5A88B3A
});

Deployment Process

Prerequisites

1. Private Key Setup

   Create a .seed file containing your mnemonic phrase:

   echo "your twelve word mnemonic phrase here" > .seed
   

   Never commit .seed to version control. It’s already in .gitignore.

2. Environment Variables

   Set required environment variables:

   .env

   ETHERSCAN_KEY=your_etherscan_api_key
   
3. Fund Deployer Address

   The deployer address (derived from your seed phrase) must have sufficient ETH for:

   • Gas fees (estimated: 0.1-0.5 ETH depending on network)
   • Contract creation costs

Deployment Commands

Deploy to Ethereum Mainnet

yarn deploy --rpc-url mainnet --verify --verifier etherscan --broadcast

Deploy to Base

yarn deploy --rpc-url base --verify --verifier etherscan --broadcast

Deploy to BNB Chain

yarn deploy --rpc-url bsc --verify --verifier etherscan --broadcast

The --verify flag automatically verifies contracts on block explorers. The API key is read from ETHERSCAN_KEY environment variable and works for all explorers (Etherscan, Basescan, BscScan).

Custom RPC Endpoint

Use a custom RPC URL:

yarn deploy --rpc-url https://your-custom-rpc-url.com --verify --broadcast

Deployment Modes

The deployment script supports two modes:

Production Mode

DeploymentMode public deploymentMode = DeploymentMode.Production;

Uses canonical production parameters for:

• Role registries
• Fee recipients (DAO multisig)
• Version registries
• Trusted filler registries

Testing Mode

DeploymentMode public deploymentMode = DeploymentMode.Testing;

Uses test parameters for:

• Development testing
• Integration testing
• Staging environments

Always verify the deployment mode is set correctly before deploying to mainnet!

Local Deployment

Deploy to Local Anvil

1. Start Local Node

   yarn anvil
   
2. Deploy Contracts

   In a new terminal:

   yarn deploy --rpc-url http://127.0.0.1:8545 --broadcast
   

Local deployments automatically use mock contracts for:

• MockRoleRegistry: Simplified role management
• Burn address for fees (address(1))

Deployment Output

Successful deployment outputs contract addresses:

----- INFO -----
Deployer: 0x1234567890123456789012345678901234567890
Chain: 1
Mode: Production

----- GENESIS -----
Running Genesis Deployment...
Folio Fee Registry: 0x0262E3e15cCFD2221b35D05909222f1f5FCdcd80
Folio Version Registry: 0xA665b273997F70b647B66fa7Ed021287544849dB
Trusted Filler Registry: 0x279ccF56441fC74f1aAC39E7faC165Dec5A88B3A

----- PROTOCOL -----
Running Followup Deployment...
Governance Deployer: 0xabcdef0123456789abcdef0123456789abcdef01
Folio Deployer: 0xfedcba9876543210fedcba9876543210fedcba98
CowSwap Filler: 0x1111111111111111111111111111111111111111
Folio Lens: 0x2222222222222222222222222222222222222222

----- DONE -----

Save these addresses for future reference and verification.

Contract Verification

Contracts are automatically verified when using the --verify flag. Manual verification:

forge verify-contract \
  --chain-id 1 \
  --num-of-optimizations 200 \
  --watch \
  --compiler-version 0.8.28 \
  --etherscan-api-key $ETHERSCAN_KEY \
  <CONTRACT_ADDRESS> \
  contracts/Folio.sol:Folio

Post-Deployment

Verify Deployment

1. Check Contract Addresses

   Verify all contracts deployed successfully and addresses are non-zero.

2. Verify Registry Configuration

   cast call <FOLIO_DEPLOYER_ADDRESS> "daoFeeRegistry()" --rpc-url mainnet
   cast call <FOLIO_DEPLOYER_ADDRESS> "versionRegistry()" --rpc-url mainnet
   
3. Verify Role Configuration

   Ensure the role registry is correctly configured for the network.

4. Test Basic Functionality

   Deploy a test Folio instance to verify the system works end-to-end.

Register Version

After deployment, register the new Folio version:

// Called by DAO governance
folioVersionRegistry.registerVersion(
    address(folioDeployer),
    "5.0.0",
    true // deprecated
);

Deployment Checklist

Troubleshooting

Deployment fails with 'insufficient funds'

Ensure the deployer address has enough ETH for gas fees. Check your balance:

cast balance <DEPLOYER_ADDRESS> --rpc-url mainnet

Verification fails

• Verify the ETHERSCAN_KEY is correct
• Check that the contract bytecode matches
• Wait a few minutes and retry verification
• Use the --watch flag for automatic retries

Wrong network parameters

The script automatically selects parameters based on block.chainid. Verify you’re connected to the correct network:

cast chain-id --rpc-url <RPC_URL>

Nonce too low error

Another transaction may be pending. Wait for it to complete or increase the nonce manually.

Security Considerations

• Never commit private keys or seed phrases
• Use hardware wallets for mainnet deployments when possible
• Verify all addresses and parameters before broadcasting
• Test thoroughly on testnets before mainnet deployment
• Use multisig wallets for protocol ownership

Next Steps

Testing

Run comprehensive tests

Contributing

Contribute to the protocol