erc8183

Type-safe Rust SDK for the ERC-8183 Agentic Commerce Protocol — on-chain job escrow with evaluator attestation for AI agent commerce.

ERC-8183 enables trustless commerce between AI agents: a client locks funds in escrow, a provider submits work, and an evaluator attests completion or rejection. This SDK provides ergonomic, alloy-native bindings for the full job lifecycle with strict type safety and comprehensive documentation.

Note: ERC-8183 is currently a Draft EIP with no official contract deployments yet. Once deployed, update the contract address and the SDK is ready to use.

See SECURITY.md before using in production.

Quick Start

Create a Job (Write)

use alloy::{
    network::EthereumWallet,
    primitives::{Address, U256},
    providers::ProviderBuilder,
    signers::local::PrivateKeySigner,
};
use erc8183::{Erc8183, types::CreateJobParams};

let signer: PrivateKeySigner = std::env::var("PRIVATE_KEY")?.parse()?;
let wallet = EthereumWallet::from(signer);

let provider = ProviderBuilder::new()
    .wallet(wallet)
    .connect_http("https://eth.llamarpc.com".parse()?);

// Replace with actual deployed contract address
let client = Erc8183::new(provider)
    .with_address("0x1234...".parse()?);

let job_handle = client.job()?;

// Create a job with deferred provider assignment
let params = CreateJobParams::new(
    Address::ZERO,                  // provider (deferred)
    "0xEvaluator...".parse()?,      // evaluator
    U256::from(1_900_000_000u64),   // expiredAt (Unix timestamp)
    "Build a REST API for payments",
);

let job_id = job_handle.create_job(&params).await?;
println!("Created job: {job_id}");

Full Job Lifecycle

// 1. Client creates job (see above)
let job_id = job_handle.create_job(&params).await?;

// 2. Client assigns provider
job_handle.set_provider(job_id, provider_address, None).await?;

// 3. Client or provider sets budget
job_handle.set_budget(job_id, U256::from(1000), None).await?;

// 4. Client funds escrow (requires ERC-20 approval)
job_handle.fund(job_id, U256::from(1000), None).await?;

// 5. Provider submits work
let deliverable = FixedBytes::from_slice(&ipfs_cid_hash);
job_handle.submit(job_id, deliverable, None).await?;

// 6. Evaluator completes (releases escrow to provider)
job_handle.complete(job_id, FixedBytes::ZERO, None).await?;

// Or: Evaluator rejects (refunds client)
// job_handle.reject(job_id, reason_hash, None).await?;

Query Job Data (Read-Only)

use alloy::providers::ProviderBuilder;
use erc8183::Erc8183;

let provider = ProviderBuilder::new()
    .connect_http("https://eth.llamarpc.com".parse()?);

let client = Erc8183::new(provider)
    .with_address("0x1234...".parse()?);

let job = client.job()?.get_job(U256::from(1)).await?;
println!("Status: {}", job.status);
println!("Client: {}", job.client);
println!("Provider: {}", job.provider);
println!("Budget: {}", job.budget);

Architecture

ERC-8183 Protocol

State Machine

Open ──────► Funded ──────► Submitted ──────► Completed
  │            │               │
  ▼            ▼               ▼
Rejected    Rejected        Rejected
            Expired         Expired

Roles

Core Functions (EIP-8183 Spec)

Events (EIP-8183 Recommended Minimum)

Hooks (Optional)

The IACPHook interface — the only normative Solidity interface in EIP-8183 — allows extending the protocol with custom logic:

interface IACPHook {
    function beforeAction(uint256 jobId, bytes4 selector, bytes calldata data) external;
    function afterAction(uint256 jobId, bytes4 selector, bytes calldata data) external;
}

Hooks are called before and after core functions (except claimRefund). Use cases include:

• Bidding/auction mechanisms
• Two-phase token transfers
• Reputation integration (ERC-8004)
• Custom validation logic

Design

• Zero async_trait — pure RPITIT, no trait-object overhead
• Inline Solidity bindings — sol! macro preserves struct names, enums, and visibility; no JSON ABI files
• Provider-generic — works with any alloy transport (HTTP, WebSocket, IPC) and any signer configuration
• Strict linting — pedantic + nursery + correctness (deny), see clippy.toml
• Spec-compliant — all 8 core functions and 10 recommended events strictly match EIP-8183 specification

Workspace

Examples

cargo run --example basic

Related Standards

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
• MIT License (LICENSE-MIT or https://opensource.org/licenses/MIT)

at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project shall be dual-licensed as above, without any additional terms or conditions.

A QNTX open-source project.

Code is law. We write both.