Reference implementation of ERC-8183 — a Job primitive for trustless agent commerce. Its core features are a job escrow protocol with evaluator attestation and an optional hook system for extensibility.
npm install
npx hardhat compile
npx hardhat testERC-8183 defines a minimal on-chain job escrow between three roles:
- Client — creates and funds jobs
- Provider — delivers work
- Evaluator — attests to completion or rejects
The core state machine:
Open → Funded → Submitted → Completed | Rejected | Expired
Each transition enforces role-based access control, and funds are held in escrow until the evaluator completes or the job is rejected/expired.
Jobs can optionally attach a hook contract (IACPHook) to extend behavior without modifying the core:
beforeAction— called before state changes, can revert to gate transitionsafterAction— called after state changes, for bookkeeping and side effects
When hook == address(0), the contract operates as a standalone job escrow with no callbacks. See docs/02-hook-system.md for the full design.
contracts/
├── AgenticCommerce.sol # Core state machine, escrow, fees, hooks
├── IACPHook.sol # Hook interface (beforeAction/afterAction)
└── mocks/
├── MockUSDC.sol # Test ERC20, 6 decimals
└── MockCBBTC.sol # Test ERC20, 8 decimals
- Upgradeable — UUPS proxy pattern via OpenZeppelin
- Access control — role-based admin for fees and hook whitelisting
- CEI pattern — checks, effects, interactions throughout
- Reentrancy protection — transient storage guard on all state-changing functions
- Hook safety —
claimRefundis intentionally not hookable so refunds cannot be blocked
See docs/01-architecture.md for state machine and sequence diagrams.
- Architecture & Diagrams — state machine, sequence flows
- Hook System Design — IACPHook interface, safety model, invocation pattern
- Demo Flows — end-to-end example scenarios
This is the reference implementation for ERC-8183. Contributions, feedback, and discussion are welcome - please see CONTRIBUTING.md for guidelines on how to get started.
MIT