caelum0x 9d2bc4eae0 feat(arc/circle): ERC-8004 + ERC-8183 + arc-chains, swap-fee + DCW contract-exec
New packages (port/adapter pattern, zero new external deps, deterministic local impls + tests):
- @settlekit/erc8004: agent identity / reputation / validation on Arc (real Arc Testnet registry addresses); AgentRegistryClient + LocalErc8004Port.
- @settlekit/erc8183: autonomous-agent job lifecycle (create→fund→submit→evaluate→settle/refund) as a validated state machine; JobClient + LocalErc8183Port.
- @settlekit/arc-chains: single source of truth for Arc/Circle chain + token + contract constants.

Extensions:
- app-kit swap: slippage tolerance + custom swap-fee collection (Stablecoin-FX monetization), validateBps, LocalAppKitSdk.lastSwapConfig().
- circle-wallets: Developer-Controlled-Wallet contract execution + transaction polling (drives ERC-8004/8183 on-chain).

1130 tests across 192 suites, typecheck + full build green.
2026-06-20 19:08:41 +03:00
..

@settlekit/erc8183

ERC-8183 autonomous-agent job lifecycle on Arc — create a job, fund a USDC escrow, submit a deliverable, evaluate it, then settle to the worker or refund the requester — wrapped in SettleKit idioms.

ERC-8183 models a unit of agent work as an on-chain job with an escrowed USDC payout. This package wraps that lifecycle with decimal-USDC amounts (Money), boundary validation, an explicit state machine, and Result-typed outcomes that never throw across the boundary.

Job state machine

            cancel                 cancel
   created ───────► cancelled   funded ───────► cancelled
      │                            │
 fund │                     submit │       refund
      ▼                            ▼      ───────► refunded
   funded ──────────────────► submitted
      │                            │
refund│                  evaluate_ │ evaluate_
      ▼                  pass/fail ▼
  refunded                    evaluated ──────► refunded (refund)
                                   │
                            settle │ (only when evaluation.passed)
                                   ▼
                                settled

Happy path: created → funded → submitted → evaluated → settled. Terminal states (settled, refunded, cancelled) have no outgoing transitions.

evaluate maps both a pass and a fail to the single evaluated status. The "cannot settle a failed evaluation" rule is therefore enforced by the port (and a fast-fail client pre-check), not by the transition table alone.

Design: inject the port, take no dependency

Following the app-kit / settlement-core provider pattern, this package defines the on-chain surface it needs (Erc8183Port) and the consumer injects an implementation. So @settlekit/erc8183 depends only on @settlekit/common — it never imports a chain SDK, builds offline, and bundles anywhere. The consumer owns viem + Circle Developer-Controlled Wallets (DCW).

The port the consumer implements

interface Erc8183Port {
  createJob(p: { requester; worker; amountUsdc; specUri }): Promise<{ jobId; txHash }>;
  fundEscrow(p: { jobId; amountUsdc }): Promise<TxResult>;
  submitDeliverable(p: { jobId; deliverableUri }): Promise<TxResult>;
  evaluate(p: { jobId; passed; scoreOrUri? }): Promise<TxResult>;
  settle(p: { jobId }): Promise<TxResult>;
  refund(p: { jobId }): Promise<TxResult>;
  getJob(p: { jobId }): Promise<Job>;
}

Usage

import { configureErc8183, type Erc8183Port } from "@settlekit/erc8183";

const port: Erc8183Port = /* viem + Circle DCW implementation, see below */;
const jobs = configureErc8183({ port });

const created = await jobs.createJob({
  requester: "0xreq",
  worker: "0xworker",
  amountUsdc: "100.00",
  specUri: "ipfs://spec",
});
if (!created.ok) throw created.error;
const { jobId } = created.value;

await jobs.fundEscrow({ jobId, amountUsdc: "100.00" });
await jobs.submitDeliverable({ jobId, deliverableUri: "ipfs://deliverable" });
await jobs.evaluate({ jobId, passed: true, scoreOrUri: "0.95" });
const settled = await jobs.settle({ jobId });
if (settled.ok) console.log(settled.value.txHash);

Every method returns Result<T>. Validation failures surface as validation_error, illegal state transitions as conflict, missing jobs as not_found, and any other thrown port error as a retryable integration_error. A SettleKitError thrown by the port (conflict/not_found) passes through with its code preserved rather than being masked.

Testing & demos

Inject LocalErc8183Port — a deterministic, in-memory port that enforces the state machine, mints sequential job_N ids, and returns synthetic monotonically-numbered tx hashes (0xlocal…). No chain, no network, no Date.now/Math.random:

import { configureErc8183, LocalErc8183Port } from "@settlekit/erc8183";

const port = new LocalErc8183Port(); // or { throwOn: ["createJob"] } to exercise error mapping
const jobs = configureErc8183({ port });

Wiring sketch: viem + Circle Developer-Controlled Wallets

This package does not depend on viem — the consumer implements Erc8183Port against the ERC-8183 job contract. A typical implementation backs a viem walletClient with a Circle DCW signer:

import { createPublicClient, createWalletClient, http, parseUnits } from "viem";
import { configureErc8183, type Erc8183Port, type Job, type TxResult } from "@settlekit/erc8183";
import { money } from "@settlekit/common";
// import a Circle DCW -> viem account adapter from your own wiring layer

const ERC8183_ABI = [/* createJob / fundEscrow / submitDeliverable / evaluate / settle / refund / jobs(...) */] as const;
const CONTRACT = "0xJobContract" as const;
const USDC_DECIMALS = 6;

const account = /* viem Account backed by a Circle Developer-Controlled Wallet */;
const walletClient = createWalletClient({ account, chain: arc, transport: http(RPC_URL) });
const publicClient = createPublicClient({ chain: arc, transport: http(RPC_URL) });

async function wait(hash: `0x${string}`): Promise<TxResult> {
  const receipt = await publicClient.waitForTransactionReceipt({ hash });
  return { txHash: hash, status: receipt.status === "success" ? "success" : "failed" };
}

const port: Erc8183Port = {
  async createJob({ requester, worker, amountUsdc, specUri }) {
    const hash = await walletClient.writeContract({
      address: CONTRACT,
      abi: ERC8183_ABI,
      functionName: "createJob",
      args: [requester, worker, parseUnits(amountUsdc, USDC_DECIMALS), specUri],
    });
    const receipt = await publicClient.waitForTransactionReceipt({ hash });
    const jobId = decodeJobIdFromLogs(receipt.logs); // contract emits the on-chain job id
    return { jobId, txHash: hash };
  },

  async fundEscrow({ jobId, amountUsdc }) {
    // USDC approve(CONTRACT, amount) first, then:
    const hash = await walletClient.writeContract({
      address: CONTRACT,
      abi: ERC8183_ABI,
      functionName: "fundEscrow",
      args: [BigInt(jobId), parseUnits(amountUsdc, USDC_DECIMALS)],
    });
    return wait(hash);
  },

  async submitDeliverable({ jobId, deliverableUri }) {
    const hash = await walletClient.writeContract({
      address: CONTRACT, abi: ERC8183_ABI, functionName: "submitDeliverable",
      args: [BigInt(jobId), deliverableUri],
    });
    return wait(hash);
  },

  async evaluate({ jobId, passed, scoreOrUri }) {
    const hash = await walletClient.writeContract({
      address: CONTRACT, abi: ERC8183_ABI, functionName: "evaluate",
      args: [BigInt(jobId), passed, scoreOrUri ?? ""],
    });
    return wait(hash);
  },

  async settle({ jobId }) {
    const hash = await walletClient.writeContract({
      address: CONTRACT, abi: ERC8183_ABI, functionName: "settle", args: [BigInt(jobId)],
    });
    return wait(hash);
  },

  async refund({ jobId }) {
    const hash = await walletClient.writeContract({
      address: CONTRACT, abi: ERC8183_ABI, functionName: "refund", args: [BigInt(jobId)],
    });
    return wait(hash);
  },

  async getJob({ jobId }): Promise<Job> {
    const raw = await publicClient.readContract({
      address: CONTRACT, abi: ERC8183_ABI, functionName: "jobs", args: [BigInt(jobId)],
    });
    return {
      id: jobId,
      requester: raw.requester,
      worker: raw.worker,
      amount: money(formatUnits(raw.amount, USDC_DECIMALS)),
      status: mapOnchainStatus(raw.status),
      ...(raw.deliverableUri ? { deliverableUri: raw.deliverableUri } : {}),
      ...(raw.hasEvaluation ? { evaluation: { passed: raw.passed, scoreOrUri: raw.scoreOrUri } } : {}),
    };
  },
};

const jobs = configureErc8183({ port });

The on-chain contract remains the authority on legal transitions; the SettleKit layer adds validation, a fast-fail pre-check, and uniform Result error handling.