ERC-8183: Agentic Commerce — Minimal Implementation

First open-source Solidity implementation of ERC-8183 (Draft).

ERC-8183 defines a trustless escrow protocol for AI agent commerce. A client creates a job, funds it with ERC-20 tokens, a provider (human or AI agent) submits a deliverable, and a trusted evaluator attests completion — releasing payment — or rejects — refunding the client.

State Machine

                        ERC-8183 Job Lifecycle
                        ═════════════════════

  ┌──────────┐  fund()   ┌──────────┐  submit()  ┌───────────┐
  │   Open   │ ────────► │  Funded  │ ─────────► │ Submitted │
  └──────────┘           └──────────┘            └───────────┘
       │                      │  │                    │  │
       │ reject()             │  │ reject()           │  │ reject()
       │ (client)             │  │ (evaluator)        │  │ (evaluator)
       ▼                      │  ▼                    │  ▼
  ┌──────────┐               │  ┌──────────┐         │  ┌──────────┐
  │ Rejected │               │  │ Rejected │         │  │ Rejected │
  └──────────┘               │  │ + Refund │         │  │ + Refund │
                              │  └──────────┘         │  └──────────┘
                              │                       │
                              │ claimRefund()         │  complete()
                              │ (after expiry)        │  (evaluator)
                              ▼                       ▼
                         ┌──────────┐           ┌───────────┐
                         │ Expired  │           │ Completed │
                         │ + Refund │           │ + Payment │
                         └──────────┘           └───────────┘

  Roles
  ─────
  Client    — creates jobs, sets budget, funds escrow
  Provider  — submits deliverables (can be an AI agent)
  Evaluator — attests completion (pays provider) or rejection (refunds client)

Quick Start

# Clone
git clone https://github.com/YOUR_USERNAME/agentic-escrow.git
cd agentic-escrow

# Install dependencies
forge install

# Build
forge build

# Test
forge test -vvv

Tests

14 tests covering every state transition and access-control path:

[PASS] test_CreateJob()              — job creation with provider
[PASS] test_CreateJobWithoutProvider() — deferred provider assignment
[PASS] test_SetBudgetByClient()      — client sets price
[PASS] test_SetBudgetByProvider()    — provider negotiates price
[PASS] test_FundJob()                — client funds escrow
[PASS] test_FundJobBudgetMismatch()  — front-running protection
[PASS] test_SubmitWork()             — provider submits deliverable
[PASS] test_CompleteJob()            — evaluator approves, provider paid
[PASS] test_RejectOpenJob()          — client cancels before funding
[PASS] test_RejectFundedJob()        — evaluator rejects, client refunded
[PASS] test_RejectSubmittedJob()     — evaluator rejects after submission
[PASS] test_ClaimRefundAfterExpiry() — expired job refunded
[PASS] test_FullHappyPath()          — end-to-end lifecycle
[PASS] test_AIAgentBountyScenario()  — real-world: AI audit agent bounty

Demo: AI Code Review Agent

The demo script deploys the contracts and runs a full scenario where a developer hires an AI agent to audit a Solidity contract:

# Start local node
anvil &

# Run demo
forge script script/DeployAndDemo.s.sol \
  --rpc-url http://127.0.0.1:8545 \
  --broadcast -vvvv

=== ERC-8183 Agentic Commerce Demo ===

1. Developer creates job: "Audit my ERC-20 for reentrancy bugs"
2. Budget set: 100 USDC
3. Job funded — tokens escrowed
4. AI agent submits audit report (IPFS hash)
5. Evaluator approves — payment released to agent

=== Final State ===
  Job status: Completed
  Provider balance: 100 USDC
  Escrow balance: 0

Deploy to Testnet

cp .env.example .env
# Edit .env with your keys

source .env
forge script script/DeployAndDemo.s.sol \
  --rpc-url $SEPOLIA_RPC_URL \
  --private-key $PRIVATE_KEY \
  --broadcast \
  --verify \
  --etherscan-api-key $ETHERSCAN_API_KEY \
  -vvvv

Project Structure

src/
  IAgenticEscrow.sol   — ERC-8183 interface (events, errors, structs, functions)
  AgenticEscrow.sol    — Core escrow implementation (SafeERC20, ReentrancyGuard)
  MockERC20.sol        — Mintable ERC-20 for testing
test/
  AgenticEscrow.t.sol  — Full test suite (14 tests)
script/
  DeployAndDemo.s.sol  — Deploy + end-to-end demo scenario

Design Decisions

• No hooks — Intentionally minimal. The spec defines optional IACPHook for extensibility; this implementation covers the core escrow only.
• Single ERC-20 per contract — Matches the spec's minimum. Deploy one instance per payment token.
• Front-running protection — fund(jobId, expectedBudget) reverts if budget changed between tx submission and execution.
• ReentrancyGuard — All token-transferring functions are protected.

Disclaimer

This implementation targets ERC-8183 Draft (2026-02-25). The spec may change. This code is unaudited and intended for educational and testnet use only. Do not use with real funds without a professional audit.

Links

• ERC-8183: Agentic Commerce — Official Spec
• Discussion Thread — Ethereum Magicians
• OpenZeppelin Contracts — SafeERC20, ReentrancyGuard

License

MIT