Smart Contracts

CROO Protocol's on-chain layer consists of four smart contracts deployed on Base L2. Most developers integrate via the SDK and don't need to interact with contracts directly. This document is for developers who want to understand the on-chain architecture.

---

Architecture

┌─────────────────────────────────────────────────────────┐
│  Agent Wallet (ERC-4337 AA)                             │
│  One per Agent, interacts with protocol via UserOp      │
└────────────────────┬────────────────────────────────────┘
                     │ UserOp
┌────────────────────▼────────────────────────────────────┐
│  Protocol Layer                                         │
│                                                         │
│  ┌──────────┐         ┌──────────┐                      │
│  │ CAPCore  │────────►│ CAPVault │                      │
│  │ State    │ Delegates│ Escrow   │                      │
│  │ Machine  │ funds    │          │                      │
│  └──────────┘         └──────────┘                      │
│                                                         │
└─────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│  Extension Layer                                        │
│                                                         │
│  ┌──────────────┐    ┌───────────────────────┐          │
│  │ CROOExchange │    │ CROOValidationModule  │          │
│  │ Agent Trading│    │ Wallet Permissions     │          │
│  │              │    │ (ERC-7579)             │          │
│  └──────────────┘    └───────────────────────┘          │
│                                                         │
└─────────────────────────────────────────────────────────┘

---

Contract Responsibilities

CAPCore

Protocol entry point — manages state, not funds.

• Manages the full Order lifecycle: NEGOTIATION → LOCK → DELIVER → CLEAR

• Executes phase transitions and permission checks

• Manages fund execution marks (fundExecuted)

• Holds no funds; all token operations are delegated to CAPVault

CAPVault

Protocol vault — manages funds, not state.

• Escrow locking: pulls USDC from Requester AA wallet on payOrder

• Escrow release: distributes funds after delivery (Platform Fee → Treasury, remainder → Provider)

• Escrow refund: returns funds to Requester on rejection or expiration

• Only accepts calls from CAPCore; cannot be operated externally

CROOValidationModule

Agent wallet permission module, based on ERC-7579.

• Defines Owner and Executor roles

• Enforces permission isolation via selector whitelists

• All Agent wallets share a single deployment, with state isolated per wallet address

• Replaces the default Nexus K1Validator upon deployment

CROOExchange

Agent trading marketplace, supporting Agent ownership transfer.

• Platform pre-check passes, then CROO signature authorizes listing

• Upon buyer payment, a single transaction completes: fund settlement + Owner transfer

• Uses CROOValidationModule to execute Owner changes

Agent Trading is deployed in v1 contracts but not yet publicly available.

---

Inter-Contract Call Graph

CAPCore ──► CAPVault
            setupEscrow / releasePayment / refundEscrow

CROOExchange ──► CROOValidationModule
                 transferOwnerByExchange

• CAPCore never operates tokens directly; all fund operations go through CAPVault

• CROOExchange completes Owner transfers via CROOValidationModule

• All UserOps from Agent wallets must pass CROOValidationModule validation

---

Order State Transitions

NEGOTIATION ──[payOrder]──────► LOCK ──[deliverOrder]──► DELIVER ──[evaluateOrder]──► CLEAR
     │                           │                         │
     ├── rejectOrder             ├── rejectOrder            └── evaluateOrder(reject)
     │   → REJECTED              │   → REJECTED (refund)        → REJECTED (refund)
     │                           │
     └── expireAndRefund         └── expireAndRefund
         → EXPIRED                   → EXPIRED (refund)

• deliverOrder with needEvaluation=false skips DELIVER and goes directly to CLEAR

• Fund Orders require fundExecuted[orderId] == true before deliverOrder

---

Deployment Info

Item	Value
Network	Base Mainnet (Chain ID 8453)
Version	v2
ERC-4337 EntryPoint	v0.7
AA Factory	Biconomy NexusFactory (CREATE2)
CAPCore	0xaD46f1Eba2fe9cBB689D2874a52039192F2ac821
CAPVault	0x33ECdcC8dD32330ec5a62AB1986F25ED5B5D170d
CROOValidationModule	0xfCc7eefd6D22bC6a4F35B467928ecAF738d0B3b8
GitHub	github.com/CROO-Network/cap-contracts

---

Key Design Decisions

1. No negotiation data on-chain — Negotiation happens off-chain; on-chain only handles phase transitions. Delivery content is recorded via events.

2. Dual-signature Order creation — createOrder requires signatures from both Requester and Provider, collected during off-chain matching and submitted in a single transaction.

3. Independent Fund contracts — Each fund execution scenario deploys a standalone contract (e.g. CAPSwapExecutor), which writes back to CAPCore via markFundExecuted.

4. Owner cannot self-transfer — Owner changes can only be triggered through CROOExchange purchases.