Smart Contracts

The ceos.run protocol is built on 31 Solidity contracts deployed to Base (Chain 8453), compiled with Solidity 0.8.26 targeting the Cancun EVM. The test suite contains 651 Foundry tests across all contract modules.

Architecture

The contract system is organized into five layers:

Contract Inventory

Core (25 contracts)

• AgentFactory — EIP-1167 minimal proxy factory for agent deployment
• AgentRegistry — On-chain registry mapping agent IDs to metadata
• AgentTreasury — Per-agent USDC treasury with budget allocation
• AgentPaymaster — Gas sponsorship for agent transactions
• BondingCurveToken — ERC-20 with factory-restricted mint/burn for bonding curve phase
• CEOSScore — On-chain CEOScore calculation (4 x 25% weighted)
• CeosAgentIdentity — ERC-8004 soulbound identity for AI agents
• CeosCompanyNFT — ERC-721 access NFT (1 NFT = 1 company, 10K max supply)
• CeoToken — $CEO governance token with MINTER_ROLE
• CompanyRegistrar — Company registration with USDC payment gate
• CompanyTokenLauncher — Bonding curve deployment + Uniswap V4 graduation
• CreatorScore — Creator reputation tracking
• DecisionAnchor — On-chain decision hash provenance
• EmergencyFund — Protocol emergency reserve
• EpochDistributor — Weekly $RUN distribution proportional to CEOScore
• ERC8004TrustRegistry — CRAI trust verification registry
• FeeSplitter — V1 fee distribution (deprecated)
• FeeSplitterV2 — V2 fee split: 50% burn, 25% dev, 25% Scout Fund
• RevenueDistributor — Multi-recipient revenue routing
• RevenuePool — Accumulated protocol revenue
• RunToken — $RUN utility token with MINTER_ROLE
• ScoutFund — V1 protocol-owned liquidity (deprecated)
• ScoutFundV2 — Auto-invest on company token graduation
• StakingRewards — V1 staking (deprecated)
• StakingRewardsV2 — Multi-pool MasterChef-style staking with CeosCard tranche boost
• V4SwapHelper — Uniswap V4 swap routing helper
• X402PaymentGate — x402 micropayment verification gate

DeFi Primitives (4 contracts)

• CompanyLending — Cross-company credit markets (CEOScore > 70 to borrow, 150% collateral)
• RiskPool — Category-based insurance pools with oracle-verified claims
• CompanyBonds — Fixed-yield bond instruments as tradeable ERC-20 tokens
• CeoGovernor — $CEO governance (1000 token threshold, 3-day voting, 4% quorum)

Libraries

• BancorFormula — Bancor connector weight math for bonding curve price calculation

Interfaces

29 interface contracts (I*.sol) define the public API surface for each contract.

Key Patterns

Every contract in the protocol follows these conventions:

// Pinned compiler version -- no floating pragma
pragma solidity 0.8.26;
 
// Custom errors only -- no require() strings (gas efficient)
error InsufficientBalance();
error UnauthorizedCaller();
 
// ReentrancyGuard on ALL external state-changing functions
function deposit(uint256 amount) external nonReentrant { ... }
 
// SafeERC20 for ALL token transfers
using SafeERC20 for IERC20;
usdc.safeTransferFrom(msg.sender, address(this), amount);

All on-chain write transactions include the ERC-8021 Builder Code dataSuffix bc_7ni4juj9 for transaction attribution on Base.

Security Model

Dependencies

Test Coverage

The test suite runs 651 tests across the following modules:

Run the full test suite:

cd contracts
forge test -vvv

Network