diff --git a/packages/app-kit/src/client.ts b/packages/app-kit/src/client.ts
index 2184fd9..d71df37 100644
--- a/packages/app-kit/src/client.ts
+++ b/packages/app-kit/src/client.ts
@@ -18,7 +18,14 @@ import {
type TransferResult,
type TransferStatus,
} from "./types.js";
-import { firstError, validateAddress, validateAmount, validateChain, validateToken } from "./validate.js";
+import {
+ firstError,
+ validateAddress,
+ validateAmount,
+ validateBps,
+ validateChain,
+ validateToken,
+} from "./validate.js";
/** Default token when a request omits one. */
const DEFAULT_TOKEN = "USDC";
@@ -199,6 +206,12 @@ export class ArcPaymentClient {
if (req.tokenIn === req.tokenOut) {
return err(validationError("tokenIn and tokenOut must differ", { token: req.tokenIn }));
}
+ const monetizationInvalid = firstError(
+ req.slippageBps !== undefined ? validateBps(req.slippageBps, "slippageBps") : null,
+ req.fee !== undefined ? validateBps(req.fee.bps, "fee.bps") : null,
+ req.fee !== undefined ? validateAddress(req.fee.recipient, "fee.recipient") : null,
+ );
+ if (monetizationInvalid !== null) return err(monetizationInvalid);
if (this.kitKey === undefined || this.kitKey.length === 0) {
return err(
new SettleKitError({
@@ -208,13 +221,20 @@ export class ArcPaymentClient {
);
}
+ const kitKey = this.kitKey;
+ const config = {
+ kitKey,
+ ...(req.slippageBps !== undefined ? { slippageTolerance: req.slippageBps } : {}),
+ ...(req.fee !== undefined ? { fee: { recipient: req.fee.recipient, bps: req.fee.bps } } : {}),
+ };
+
return this.run("swap", () =>
this.sdk.swap({
from: { adapter: req.adapter, chain: req.chain },
tokenIn: req.tokenIn,
tokenOut: req.tokenOut,
amountIn: req.amountIn,
- config: { kitKey: this.kitKey },
+ config,
}),
);
}
diff --git a/packages/app-kit/src/local-sdk.ts b/packages/app-kit/src/local-sdk.ts
index 2816734..26e56c9 100644
--- a/packages/app-kit/src/local-sdk.ts
+++ b/packages/app-kit/src/local-sdk.ts
@@ -38,6 +38,7 @@ export class LocalAppKitSdk implements AppKitSdk {
private readonly throwOn: ReadonlySet;
private counter = 0;
private readonly recorded: RecordedCall[] = [];
+ private lastSwapConfigValue: SdkSwapParams["config"];
readonly unifiedBalance: {
deposit(params: SdkDepositParams): Promise;
@@ -60,6 +61,21 @@ export class LocalAppKitSdk implements AppKitSdk {
return [...this.recorded];
}
+ /**
+ * The `config` passed to the most recent {@link swap} call, or `undefined` if
+ * no swap has run yet. Returns a defensive copy so assertions cannot mutate
+ * recorded state.
+ */
+ lastSwapConfig(): SdkSwapParams["config"] {
+ if (this.lastSwapConfigValue === undefined) return undefined;
+ const { kitKey, slippageTolerance, fee } = this.lastSwapConfigValue;
+ return {
+ ...(kitKey !== undefined ? { kitKey } : {}),
+ ...(slippageTolerance !== undefined ? { slippageTolerance } : {}),
+ ...(fee !== undefined ? { fee: { recipient: fee.recipient, bps: fee.bps } } : {}),
+ };
+ }
+
private async simulate(
kind: TransferKind,
name: string,
@@ -93,6 +109,7 @@ export class LocalAppKitSdk implements AppKitSdk {
}
swap(params: SdkSwapParams): Promise {
+ this.lastSwapConfigValue = params.config;
return this.simulate("swap", "swap", params.amountIn, params.from.chain);
}
}
diff --git a/packages/app-kit/src/sdk.ts b/packages/app-kit/src/sdk.ts
index 2b6525f..077db69 100644
--- a/packages/app-kit/src/sdk.ts
+++ b/packages/app-kit/src/sdk.ts
@@ -49,7 +49,13 @@ export interface SdkSwapParams {
tokenIn: string;
tokenOut: string;
amountIn: string;
- config?: { kitKey?: string };
+ config?: {
+ kitKey?: string;
+ /** Slippage tolerance in basis points (mapped from request `slippageBps`). */
+ slippageTolerance?: number;
+ /** Custom spread fee to collect on the swap. */
+ fee?: { recipient: string; bps: number };
+ };
}
/** App Kit `unifiedBalance.deposit` parameters. */
diff --git a/packages/app-kit/src/types.ts b/packages/app-kit/src/types.ts
index 046919b..235f03f 100644
--- a/packages/app-kit/src/types.ts
+++ b/packages/app-kit/src/types.ts
@@ -110,6 +110,17 @@ export interface BridgeRequest {
amount: string;
}
+/**
+ * A custom spread fee collected on a swap (Stablecoin-FX monetization).
+ * The fee is taken as a share of the swap and routed to {@link SwapFee.recipient}.
+ */
+export interface SwapFee {
+ /** Wallet address that receives the collected fee. Must be non-empty. */
+ recipient: string;
+ /** Fee size in basis points (0..10000, where 10000 = 100%). */
+ bps: number;
+}
+
/** Exchange one token for another on the same chain. */
export interface SwapRequest {
adapter: A;
@@ -118,6 +129,14 @@ export interface SwapRequest {
tokenOut: SupportedToken;
/** Decimal input amount. */
amountIn: string;
+ /**
+ * Slippage tolerance in basis points (0..10000, where 100 = 1%). When set,
+ * the swap reverts if the realized price moves beyond this bound. Maps to the
+ * SDK's `config.slippageTolerance`.
+ */
+ slippageBps?: number;
+ /** Optional custom spread fee to collect on this swap. */
+ fee?: SwapFee;
}
/** Deposit a token from one chain into the chain-abstracted Unified Balance. */
diff --git a/packages/app-kit/src/validate.ts b/packages/app-kit/src/validate.ts
index 2d00a94..e2d9ba7 100644
--- a/packages/app-kit/src/validate.ts
+++ b/packages/app-kit/src/validate.ts
@@ -54,6 +54,27 @@ export function validateToken(token: string, field = "token"): SettleKitError |
return null;
}
+/** Maximum basis points (100%). */
+const MAX_BPS = 10000;
+
+/**
+ * Validate a basis-points value: an integer in the inclusive range 0..10000.
+ * Relies on {@link Number.isInteger} so `NaN`/`Infinity`/fractions are rejected
+ * (range comparisons alone would let `NaN` slip through).
+ */
+export function validateBps(value: number, field: string): SettleKitError | null {
+ if (typeof value !== "number" || !Number.isInteger(value)) {
+ return validationError(`${field} must be an integer`, { field, value });
+ }
+ if (value < 0 || value > MAX_BPS) {
+ return validationError(`${field} must be between 0 and ${MAX_BPS} basis points`, {
+ field,
+ value,
+ });
+ }
+ return null;
+}
+
/** Validate a non-empty wallet address. */
export function validateAddress(address: string, field = "address"): SettleKitError | null {
if (typeof address !== "string" || address.trim().length === 0) {
diff --git a/packages/app-kit/test/client.test.ts b/packages/app-kit/test/client.test.ts
index 40b4fe4..85557c3 100644
--- a/packages/app-kit/test/client.test.ts
+++ b/packages/app-kit/test/client.test.ts
@@ -168,6 +168,109 @@ describe("swap", () => {
if (!isErr(res)) return;
expect(res.error.code).toBe("validation_error");
});
+
+ it("passes valid slippage and fee through to the SDK", async () => {
+ const sdk = new LocalAppKitSdk();
+ const { arc } = client({ kitKey: "kit_test", sdk });
+ const res = await arc.swap({
+ adapter: ADAPTER,
+ chain: "Arc_Testnet",
+ tokenIn: "USDC",
+ tokenOut: "EURC",
+ amountIn: "1",
+ slippageBps: 50,
+ fee: { recipient: "0xfeeacct", bps: 30 },
+ });
+ expect(isOk(res)).toBe(true);
+ expect(sdk.lastSwapConfig()).toEqual({
+ kitKey: "kit_test",
+ slippageTolerance: 50,
+ fee: { recipient: "0xfeeacct", bps: 30 },
+ });
+ });
+
+ it("omits slippage/fee from config when not provided", async () => {
+ const sdk = new LocalAppKitSdk();
+ const { arc } = client({ kitKey: "kit_test", sdk });
+ const res = await arc.swap({
+ adapter: ADAPTER,
+ chain: "Arc_Testnet",
+ tokenIn: "USDC",
+ tokenOut: "EURC",
+ amountIn: "1",
+ });
+ expect(isOk(res)).toBe(true);
+ expect(sdk.lastSwapConfig()).toEqual({ kitKey: "kit_test" });
+ });
+
+ it("accepts boundary basis points (0 slippage, 10000 fee)", async () => {
+ const sdk = new LocalAppKitSdk();
+ const { arc } = client({ kitKey: "kit_test", sdk });
+ const res = await arc.swap({
+ adapter: ADAPTER,
+ chain: "Arc_Testnet",
+ tokenIn: "USDC",
+ tokenOut: "EURC",
+ amountIn: "1",
+ slippageBps: 0,
+ fee: { recipient: "0xfeeacct", bps: 10000 },
+ });
+ expect(isOk(res)).toBe(true);
+ expect(sdk.lastSwapConfig()).toEqual({
+ kitKey: "kit_test",
+ slippageTolerance: 0,
+ fee: { recipient: "0xfeeacct", bps: 10000 },
+ });
+ });
+
+ it("rejects out-of-range or non-integer slippageBps", async () => {
+ const { arc } = client({ kitKey: "kit_test" });
+ for (const slippageBps of [-1, 10001, 1.5, Number.NaN]) {
+ const res = await arc.swap({
+ adapter: ADAPTER,
+ chain: "Arc_Testnet",
+ tokenIn: "USDC",
+ tokenOut: "EURC",
+ amountIn: "1",
+ slippageBps,
+ });
+ expect(isErr(res)).toBe(true);
+ if (!isErr(res)) return;
+ expect(res.error.code).toBe("validation_error");
+ }
+ });
+
+ it("rejects out-of-range or non-integer fee.bps", async () => {
+ const { arc } = client({ kitKey: "kit_test" });
+ for (const bps of [20000, 12.3, -5]) {
+ const res = await arc.swap({
+ adapter: ADAPTER,
+ chain: "Arc_Testnet",
+ tokenIn: "USDC",
+ tokenOut: "EURC",
+ amountIn: "1",
+ fee: { recipient: "0xfeeacct", bps },
+ });
+ expect(isErr(res)).toBe(true);
+ if (!isErr(res)) return;
+ expect(res.error.code).toBe("validation_error");
+ }
+ });
+
+ it("rejects an empty fee.recipient", async () => {
+ const { arc } = client({ kitKey: "kit_test" });
+ const res = await arc.swap({
+ adapter: ADAPTER,
+ chain: "Arc_Testnet",
+ tokenIn: "USDC",
+ tokenOut: "EURC",
+ amountIn: "1",
+ fee: { recipient: " ", bps: 30 },
+ });
+ expect(isErr(res)).toBe(true);
+ if (!isErr(res)) return;
+ expect(res.error.code).toBe("validation_error");
+ });
});
describe("unified balance", () => {
diff --git a/packages/app-kit/test/validate.test.ts b/packages/app-kit/test/validate.test.ts
new file mode 100644
index 0000000..3400702
--- /dev/null
+++ b/packages/app-kit/test/validate.test.ts
@@ -0,0 +1,31 @@
+import { describe, expect, it } from "vitest";
+import { validateBps } from "../src/index.js";
+
+describe("validateBps", () => {
+ it("accepts the inclusive 0..10000 integer range", () => {
+ for (const value of [0, 1, 50, 5000, 10000]) {
+ expect(validateBps(value, "bps")).toBeNull();
+ }
+ });
+
+ it("rejects values outside the range", () => {
+ for (const value of [-1, 10001, 99999]) {
+ const error = validateBps(value, "bps");
+ expect(error).not.toBeNull();
+ expect(error?.code).toBe("validation_error");
+ }
+ });
+
+ it("rejects non-integers including NaN and Infinity", () => {
+ for (const value of [1.5, 12.3, Number.NaN, Number.POSITIVE_INFINITY]) {
+ const error = validateBps(value, "bps");
+ expect(error).not.toBeNull();
+ expect(error?.code).toBe("validation_error");
+ }
+ });
+
+ it("includes the field name in the error details", () => {
+ const error = validateBps(-1, "slippageBps");
+ expect(error?.details).toMatchObject({ field: "slippageBps", value: -1 });
+ });
+});
diff --git a/packages/arc-chains/README.md b/packages/arc-chains/README.md
new file mode 100644
index 0000000..7e9499e
--- /dev/null
+++ b/packages/arc-chains/README.md
@@ -0,0 +1,80 @@
+# @settlekit/arc-chains
+
+Dependency-light **source of truth** for Arc / Circle chain, token, and contract
+constants. Every SettleKit package and app imports these definitions instead of
+re-declaring chain ids, RPC URLs, explorer bases, or registry addresses.
+
+**Pure data + pure functions only — no I/O, no side effects.**
+
+## Why dependency-free
+
+This package takes **zero `@settlekit` dependencies** and sits as a leaf in the
+build graph. The ERC-8004 registry addresses and Arc Testnet endpoints are
+**mirrored verbatim** from `packages/erc8004/src/addresses.ts` (the canonical
+source) rather than imported, because `@settlekit/erc8004` exposes no barrel and
+its `dist` is unbuilt. A test asserts the exact mirrored values so drift is
+caught immediately. If the erc8004 addresses change, update both and re-run the
+test.
+
+## Exports
+
+### Chains (`chains.ts`)
+
+- `ChainDescriptor` — `{ key, displayName, chainId, rpcUrl, explorerUrl, testnet }`
+- `SupportedChain` — 8-member union, identical to `@settlekit/app-kit`
+- `CHAINS: Record` — total record
+- `SUPPORTED_CHAINS` — runtime allow-list derived from `CHAINS`
+- `getChain(key)` — descriptor lookup (total record, never `undefined`)
+- `explorerTxUrl(chain, hash)` → `` `${chain.explorerUrl}/tx/${hash}` ``
+- `explorerAddressUrl(chain, addr)` → `` `${chain.explorerUrl}/address/${addr}` ``
+
+> Note: these helpers take a `ChainDescriptor` (per chain), unlike the
+> `@settlekit/erc8004` helpers which take a base-URL string. The path format is
+> identical so URLs match across packages.
+
+### Tokens (`tokens.ts`)
+
+- `SupportedToken` — 7-member union (`USDC | EURC | USDT | USDe | DAI | PYUSD | cirBTC`)
+- `TokenMetadata` — `{ symbol, decimals, address? }`
+- `TOKENS: Record` — symbol-level metadata
+- `CHAIN_TOKENS` — optional per-chain token placement
+- `getToken(symbol)` — metadata lookup
+
+### Contracts (`contracts.ts`)
+
+- `Erc8004Registries` — `{ identityRegistry, reputationRegistry, validationRegistry }`
+- `ARC_TESTNET_REGISTRIES` — the three documented Arc Testnet ERC-8004 addresses
+- `CONTRACTS` — forward-compatible per-chain registry map
+
+## Verified Arc Testnet endpoints
+
+| Field | Value |
+| ------------ | ------------------------------------ |
+| RPC | `https://rpc.testnet.arc.network/` |
+| Explorer | `https://testnet.arcscan.app` |
+| Identity | `0x8004A818BFB912233c491871b3d84c89A494BD9e` |
+| Reputation | `0x8004B663056A597Dffe9eCcC1965A193B7388713` |
+| Validation | `0x8004Cb1BF31DAf7788923b405b754f57acEB4272` |
+
+## TODO markers (values not yet in the Arc docs)
+
+Nothing below is invented — each is left as a typed empty/undefined sentinel:
+
+- **Arc Testnet `chainId`** — not published in the repo's Arc docs; left as the
+ `0` sentinel until verified. The verified RPC/explorer remain the source of
+ truth.
+- **Arc Mainnet `rpcUrl` / `explorerUrl` / `chainId`** — not yet in Arc docs;
+ left as `""` / `0`. Excluded from the non-empty-endpoint test invariant.
+- **All token on-chain addresses** — left `undefined`. Addresses are never
+ invented; they will be filled when published.
+
+Non-Arc chains (Ethereum / Base / Arbitrum and their Sepolia variants) use
+well-known public chain ids and canonical public explorer hostnames. Their RPC
+URLs are canonical public defaults — override per environment as needed.
+
+## Build & test
+
+```bash
+pnpm --filter @settlekit/arc-chains build # tsc -b
+pnpm --filter @settlekit/arc-chains test # vitest run
+```
diff --git a/packages/arc-chains/package.json b/packages/arc-chains/package.json
new file mode 100644
index 0000000..1a73b7b
--- /dev/null
+++ b/packages/arc-chains/package.json
@@ -0,0 +1,23 @@
+{
+ "name": "@settlekit/arc-chains",
+ "version": "0.0.0",
+ "type": "module",
+ "main": "./dist/index.js",
+ "types": "./dist/index.d.ts",
+ "exports": {
+ ".": {
+ "types": "./dist/index.d.ts",
+ "default": "./dist/index.js"
+ }
+ },
+ "files": ["dist"],
+ "scripts": {
+ "build": "tsc -b",
+ "test": "vitest run"
+ },
+ "devDependencies": {
+ "@types/node": "^20.14.0",
+ "typescript": "^5.5.4",
+ "vitest": "^2.0.5"
+ }
+}
diff --git a/packages/arc-chains/src/chains.ts b/packages/arc-chains/src/chains.ts
new file mode 100644
index 0000000..d6cd1e1
--- /dev/null
+++ b/packages/arc-chains/src/chains.ts
@@ -0,0 +1,155 @@
+/**
+ * Arc / Circle chain descriptors — the single source of truth for chain
+ * metadata (id, RPC, explorer) shared across SettleKit packages and apps.
+ *
+ * Pure data + pure functions only. No I/O.
+ *
+ * The {@link SupportedChain} union is re-declared here (rather than imported)
+ * so this package stays dependency-free and a leaf in the build graph. It MUST
+ * stay member-for-member identical to packages/app-kit/src/types.ts
+ * (the canonical union for App Kit flows).
+ *
+ * Verified Arc Testnet endpoints are mirrored from
+ * packages/erc8004/src/addresses.ts (the canonical source for Arc endpoints).
+ * Non-Arc public chain ids and explorer hostnames are well-known public facts.
+ * Public RPC URLs are environment-dependent; the defaults below are canonical
+ * public endpoints — override per environment as needed.
+ */
+
+/**
+ * Blockchains App Kit supports for SettleKit flows (Arc-centric).
+ * Mirrors {@link SupportedChain} in packages/app-kit/src/types.ts.
+ */
+export type SupportedChain =
+ | "Arc_Testnet"
+ | "Arc_Mainnet"
+ | "Ethereum_Sepolia"
+ | "Ethereum"
+ | "Base_Sepolia"
+ | "Base"
+ | "Arbitrum_Sepolia"
+ | "Arbitrum";
+
+/** Static metadata describing one chain. */
+export interface ChainDescriptor {
+ /** Stable key, matching the {@link SupportedChain} union. */
+ key: SupportedChain;
+ /** Human-readable name for UI surfaces. */
+ displayName: string;
+ /** EVM chain id (e.g. 1 for Ethereum mainnet). */
+ chainId: number;
+ /** JSON-RPC endpoint. Empty string when not yet published (see TODO). */
+ rpcUrl: string;
+ /** Block-explorer base URL. Empty string when not yet published (see TODO). */
+ explorerUrl: string;
+ /** True for testnets. */
+ testnet: boolean;
+}
+
+/**
+ * Arc Testnet endpoints — mirrored verbatim from
+ * packages/erc8004/src/addresses.ts (canonical source).
+ */
+const ARC_TESTNET_RPC_URL = "https://rpc.testnet.arc.network/";
+const ARC_TESTNET_EXPLORER = "https://testnet.arcscan.app";
+
+/** Total record of every supported chain. */
+export const CHAINS: Record = {
+ Arc_Testnet: {
+ key: "Arc_Testnet",
+ displayName: "Arc Testnet",
+ // TODO: Arc Testnet EVM chainId not published in the Arc docs available in
+ // this repo — do not invent. Left as the 0 sentinel until verified; the
+ // verified rpcUrl/explorerUrl below are the source of truth for Arc Testnet.
+ chainId: 0,
+ rpcUrl: ARC_TESTNET_RPC_URL,
+ explorerUrl: ARC_TESTNET_EXPLORER,
+ testnet: true,
+ },
+ Arc_Mainnet: {
+ key: "Arc_Mainnet",
+ displayName: "Arc Mainnet",
+ // TODO: Arc Mainnet chainId not yet in Arc docs.
+ chainId: 0,
+ // TODO: Arc mainnet RPC not yet in Arc docs — do not invent.
+ rpcUrl: "",
+ // TODO: Arc mainnet explorer not yet in Arc docs — do not invent.
+ explorerUrl: "",
+ testnet: false,
+ },
+ Ethereum: {
+ key: "Ethereum",
+ displayName: "Ethereum",
+ chainId: 1,
+ rpcUrl: "https://eth.llamarpc.com",
+ explorerUrl: "https://etherscan.io",
+ testnet: false,
+ },
+ Ethereum_Sepolia: {
+ key: "Ethereum_Sepolia",
+ displayName: "Ethereum Sepolia",
+ chainId: 11155111,
+ rpcUrl: "https://ethereum-sepolia-rpc.publicnode.com",
+ explorerUrl: "https://sepolia.etherscan.io",
+ testnet: true,
+ },
+ Base: {
+ key: "Base",
+ displayName: "Base",
+ chainId: 8453,
+ rpcUrl: "https://mainnet.base.org",
+ explorerUrl: "https://basescan.org",
+ testnet: false,
+ },
+ Base_Sepolia: {
+ key: "Base_Sepolia",
+ displayName: "Base Sepolia",
+ chainId: 84532,
+ rpcUrl: "https://sepolia.base.org",
+ explorerUrl: "https://sepolia.basescan.org",
+ testnet: true,
+ },
+ Arbitrum: {
+ key: "Arbitrum",
+ displayName: "Arbitrum One",
+ chainId: 42161,
+ rpcUrl: "https://arb1.arbitrum.io/rpc",
+ explorerUrl: "https://arbiscan.io",
+ testnet: false,
+ },
+ Arbitrum_Sepolia: {
+ key: "Arbitrum_Sepolia",
+ displayName: "Arbitrum Sepolia",
+ chainId: 421614,
+ rpcUrl: "https://sepolia-rollup.arbitrum.io/rpc",
+ explorerUrl: "https://sepolia.arbiscan.io",
+ testnet: true,
+ },
+};
+
+/** Runtime allow-list derived from {@link CHAINS}. */
+export const SUPPORTED_CHAINS: readonly SupportedChain[] = Object.keys(
+ CHAINS,
+) as SupportedChain[];
+
+/**
+ * Look up a chain descriptor by key. {@link CHAINS} is a total
+ * `Record`, so a literal-union key never widens to
+ * `undefined` under `noUncheckedIndexedAccess`.
+ */
+export function getChain(key: SupportedChain): ChainDescriptor {
+ return CHAINS[key];
+}
+
+/** Build an explorer URL for a transaction hash on the given chain. */
+export function explorerTxUrl(chain: ChainDescriptor, hash: string): string {
+ return `${chain.explorerUrl}/tx/${hash}`;
+}
+
+/** Build an explorer URL for an address on the given chain. */
+export function explorerAddressUrl(
+ chain: ChainDescriptor,
+ addr: string,
+): string {
+ return `${chain.explorerUrl}/address/${addr}`;
+}
diff --git a/packages/arc-chains/src/contracts.ts b/packages/arc-chains/src/contracts.ts
new file mode 100644
index 0000000..169584f
--- /dev/null
+++ b/packages/arc-chains/src/contracts.ts
@@ -0,0 +1,40 @@
+/**
+ * Known Arc Testnet contract addresses — ERC-8004 registries.
+ *
+ * These three addresses are MIRRORED VERBATIM from
+ * packages/erc8004/src/addresses.ts, which is the canonical source. They are
+ * re-declared here (rather than imported) so @settlekit/arc-chains stays
+ * dependency-free and a leaf in the build graph. A test asserts the exact
+ * values to catch drift; if erc8004 changes, update both and re-verify.
+ *
+ * Pure data only. No I/O. Addresses are never invented.
+ */
+
+import type { SupportedChain } from "./chains.js";
+
+/** A set of ERC-8004 registry addresses for one network. */
+export interface Erc8004Registries {
+ identityRegistry: string;
+ reputationRegistry: string;
+ validationRegistry: string;
+}
+
+/**
+ * Arc Testnet ERC-8004 registries.
+ * Mirrored from packages/erc8004/src/addresses.ts (canonical source).
+ */
+export const ARC_TESTNET_REGISTRIES: Erc8004Registries = {
+ identityRegistry: "0x8004A818BFB912233c491871b3d84c89A494BD9e",
+ reputationRegistry: "0x8004B663056A597Dffe9eCcC1965A193B7388713",
+ validationRegistry: "0x8004Cb1BF31DAf7788923b405b754f57acEB4272",
+};
+
+/**
+ * Per-chain ERC-8004 registries, keyed by chain. Forward-compatible map; only
+ * Arc Testnet is populated. Arc Mainnet is intentionally omitted — its
+ * registry addresses are not yet in the Arc docs (do not invent).
+ */
+export const CONTRACTS: Partial> = {
+ Arc_Testnet: ARC_TESTNET_REGISTRIES,
+ // TODO: Arc_Mainnet ERC-8004 registries not yet in Arc docs — do not invent.
+};
diff --git a/packages/arc-chains/src/index.ts b/packages/arc-chains/src/index.ts
new file mode 100644
index 0000000..9c92d87
--- /dev/null
+++ b/packages/arc-chains/src/index.ts
@@ -0,0 +1,11 @@
+/**
+ * @settlekit/arc-chains — dependency-light source of truth for Arc / Circle
+ * chain, token, and contract constants. Pure data + pure functions only.
+ *
+ * No symbol collisions: SupportedChain lives in chains.ts, SupportedToken in
+ * tokens.ts; Erc8004Registries in contracts.ts.
+ */
+
+export * from "./chains.js";
+export * from "./tokens.js";
+export * from "./contracts.js";
diff --git a/packages/arc-chains/src/tokens.ts b/packages/arc-chains/src/tokens.ts
new file mode 100644
index 0000000..e2c7c87
--- /dev/null
+++ b/packages/arc-chains/src/tokens.ts
@@ -0,0 +1,103 @@
+/**
+ * Token metadata for Arc / Circle flows — symbol-level decimals plus optional
+ * per-chain placement. The single source of truth for token constants shared
+ * across SettleKit packages and apps.
+ *
+ * Pure data only. No I/O.
+ *
+ * HARD RULE: on-chain token addresses are NEVER invented. Every `address` is
+ * left `undefined` with a `// TODO` until a value appears in the Arc docs.
+ *
+ * The {@link SupportedToken} union is re-declared here (rather than imported)
+ * so this package stays dependency-free. It MUST stay member-for-member
+ * identical to packages/app-kit/src/types.ts (the canonical union).
+ */
+
+import type { SupportedChain } from "./chains.js";
+
+/**
+ * Tokens App Kit can transfer or swap.
+ * Mirrors {@link SupportedToken} in packages/app-kit/src/types.ts.
+ */
+export type SupportedToken =
+ | "USDC"
+ | "EURC"
+ | "USDT"
+ | "USDe"
+ | "DAI"
+ | "PYUSD"
+ | "cirBTC";
+
+/** Runtime allow-list mirroring {@link SupportedToken}. */
+export const SUPPORTED_TOKENS: readonly SupportedToken[] = [
+ "USDC",
+ "EURC",
+ "USDT",
+ "USDe",
+ "DAI",
+ "PYUSD",
+ "cirBTC",
+];
+
+/** Metadata for one token. */
+export interface TokenMetadata {
+ /** Token symbol. */
+ symbol: SupportedToken;
+ /** ERC-20 decimals. */
+ decimals: number;
+ /**
+ * On-chain contract address. Optional and left `undefined` until published
+ * in the Arc docs — addresses are never invented.
+ */
+ address?: string;
+}
+
+/**
+ * Symbol-level token metadata. Decimals use well-established standards:
+ * USDC/EURC/USDT/PYUSD = 6, DAI/USDe = 18, cirBTC = 8 (BTC-pegged).
+ * Addresses are intentionally omitted (per-chain; see {@link CHAIN_TOKENS}).
+ */
+export const TOKENS: Record = {
+ // Decimals = 6 per the Arc/Circle stablecoin spec.
+ USDC: { symbol: "USDC", decimals: 6 },
+ EURC: { symbol: "EURC", decimals: 6 },
+ // USDT uses 6 decimals on EVM chains (standard).
+ USDT: { symbol: "USDT", decimals: 6 },
+ // USDe (Ethena) uses 18 decimals (standard).
+ USDe: { symbol: "USDe", decimals: 18 },
+ // DAI uses 18 decimals (standard).
+ DAI: { symbol: "DAI", decimals: 18 },
+ // PYUSD uses 6 decimals (standard).
+ PYUSD: { symbol: "PYUSD", decimals: 6 },
+ // cirBTC is BTC-pegged; 8 decimals (BTC convention).
+ // TODO: confirm cirBTC decimals against Arc docs.
+ cirBTC: { symbol: "cirBTC", decimals: 8 },
+};
+
+/**
+ * Per-chain token placement. Populated only where token presence is known;
+ * decimals carry over from {@link TOKENS} and addresses stay `undefined` until
+ * the Arc docs publish them (never invented).
+ *
+ * USDC and EURC are Circle's native stablecoins on Arc, hence listed on
+ * Arc Testnet. Addresses are TODO.
+ */
+export const CHAIN_TOKENS: Partial<
+ Record>>
+> = {
+ Arc_Testnet: {
+ // TODO: USDC address on Arc Testnet not in Arc docs — do not invent.
+ USDC: { symbol: "USDC", decimals: 6 },
+ // TODO: EURC address on Arc Testnet not in Arc docs — do not invent.
+ EURC: { symbol: "EURC", decimals: 6 },
+ },
+};
+
+/**
+ * Look up symbol-level token metadata. {@link TOKENS} is a total
+ * `Record`, so a literal-union key never widens to
+ * `undefined` under `noUncheckedIndexedAccess`.
+ */
+export function getToken(symbol: SupportedToken): TokenMetadata {
+ return TOKENS[symbol];
+}
diff --git a/packages/arc-chains/test/chains.test.ts b/packages/arc-chains/test/chains.test.ts
new file mode 100644
index 0000000..8f3df11
--- /dev/null
+++ b/packages/arc-chains/test/chains.test.ts
@@ -0,0 +1,125 @@
+import { describe, expect, it } from "vitest";
+import {
+ ARC_TESTNET_REGISTRIES,
+ CHAINS,
+ SUPPORTED_CHAINS,
+ SUPPORTED_TOKENS,
+ TOKENS,
+ explorerAddressUrl,
+ explorerTxUrl,
+ getChain,
+ getToken,
+} from "../src/index.js";
+import type { ChainDescriptor, SupportedChain } from "../src/index.js";
+
+/** Chains whose endpoints are intentionally TODO (excluded from invariants). */
+const TODO_CHAINS: readonly SupportedChain[] = ["Arc_Mainnet"];
+
+describe("chains", () => {
+ it("getChain returns the verified Arc Testnet descriptor", () => {
+ const arc = getChain("Arc_Testnet");
+ expect(arc.rpcUrl).toBe("https://rpc.testnet.arc.network/");
+ expect(arc.explorerUrl).toBe("https://testnet.arcscan.app");
+ expect(arc.testnet).toBe(true);
+ expect(arc.key).toBe("Arc_Testnet");
+ });
+
+ it("getChain returns a mainnet (non-testnet) descriptor for Ethereum", () => {
+ const eth = getChain("Ethereum");
+ expect(eth.testnet).toBe(false);
+ expect(eth.chainId).toBe(1);
+ });
+
+ it("explorerTxUrl builds the exact tx path", () => {
+ const arc = getChain("Arc_Testnet");
+ expect(explorerTxUrl(arc, "0xabc")).toBe(
+ "https://testnet.arcscan.app/tx/0xabc",
+ );
+ });
+
+ it("explorerAddressUrl builds the exact address path", () => {
+ const arc = getChain("Arc_Testnet");
+ expect(explorerAddressUrl(arc, "0xdef")).toBe(
+ "https://testnet.arcscan.app/address/0xdef",
+ );
+ });
+
+ it("CHAINS has exactly the 8 SupportedChain keys", () => {
+ const keys = Object.keys(CHAINS);
+ expect(keys).toHaveLength(8);
+ expect([...keys].sort()).toEqual([...SUPPORTED_CHAINS].sort());
+ expect(keys).toEqual(
+ expect.arrayContaining([
+ "Arc_Testnet",
+ "Arc_Mainnet",
+ "Ethereum_Sepolia",
+ "Ethereum",
+ "Base_Sepolia",
+ "Base",
+ "Arbitrum_Sepolia",
+ "Arbitrum",
+ ]),
+ );
+ });
+
+ it("every non-TODO chain has non-empty rpcUrl and explorerUrl", () => {
+ for (const chain of Object.values(CHAINS) as ChainDescriptor[]) {
+ if (TODO_CHAINS.includes(chain.key)) continue;
+ expect(chain.rpcUrl.length).toBeGreaterThan(0);
+ expect(chain.explorerUrl.length).toBeGreaterThan(0);
+ }
+ });
+
+ it("every chain descriptor's key matches its CHAINS record key", () => {
+ for (const key of SUPPORTED_CHAINS) {
+ expect(getChain(key).key).toBe(key);
+ }
+ });
+
+ it("chainId is a positive unique integer for chains with a published id", () => {
+ const ids = (Object.values(CHAINS) as ChainDescriptor[])
+ // chainId 0 is the documented "not in docs" sentinel (Arc).
+ .filter((c) => c.chainId !== 0)
+ .map((c) => c.chainId);
+ for (const id of ids) {
+ expect(Number.isInteger(id)).toBe(true);
+ expect(id).toBeGreaterThan(0);
+ }
+ expect(new Set(ids).size).toBe(ids.length);
+ });
+});
+
+describe("contracts", () => {
+ it("ARC_TESTNET_REGISTRIES matches the documented ERC-8004 addresses", () => {
+ expect(ARC_TESTNET_REGISTRIES.identityRegistry).toBe(
+ "0x8004A818BFB912233c491871b3d84c89A494BD9e",
+ );
+ expect(ARC_TESTNET_REGISTRIES.reputationRegistry).toBe(
+ "0x8004B663056A597Dffe9eCcC1965A193B7388713",
+ );
+ expect(ARC_TESTNET_REGISTRIES.validationRegistry).toBe(
+ "0x8004Cb1BF31DAf7788923b405b754f57acEB4272",
+ );
+ });
+});
+
+describe("tokens", () => {
+ it("USDC and EURC have 6 decimals", () => {
+ expect(getToken("USDC").decimals).toBe(6);
+ expect(getToken("EURC").decimals).toBe(6);
+ });
+
+ it("TOKENS key-set equals the 7-member SupportedToken union", () => {
+ const keys = Object.keys(TOKENS);
+ expect(keys).toHaveLength(7);
+ expect([...keys].sort()).toEqual([...SUPPORTED_TOKENS].sort());
+ });
+
+ it("no token address is invented (all undefined or 0x-prefixed)", () => {
+ for (const meta of Object.values(TOKENS)) {
+ if (meta.address !== undefined) {
+ expect(meta.address.startsWith("0x")).toBe(true);
+ }
+ }
+ });
+});
diff --git a/packages/arc-chains/tsconfig.json b/packages/arc-chains/tsconfig.json
new file mode 100644
index 0000000..5f9a059
--- /dev/null
+++ b/packages/arc-chains/tsconfig.json
@@ -0,0 +1,11 @@
+{
+ "extends": "../../tsconfig.base.json",
+ "compilerOptions": {
+ "rootDir": "./src",
+ "outDir": "./dist",
+ "composite": true
+ },
+ "references": [],
+ "include": ["src/**/*"],
+ "exclude": ["dist", "node_modules", "**/*.test.ts"]
+}
diff --git a/packages/circle-wallets/src/client.ts b/packages/circle-wallets/src/client.ts
index 658a7bd..1830fa3 100644
--- a/packages/circle-wallets/src/client.ts
+++ b/packages/circle-wallets/src/client.ts
@@ -12,6 +12,7 @@
* - GET /v1/w3s/wallets list wallets
* - GET /v1/w3s/wallets/{id}/balances get wallet token balances
* - POST /v1/w3s/developer/transactions/transfer create a transfer transaction
+ * - POST /v1/w3s/developer/transactions/contractExecution execute a contract call
* - GET /v1/w3s/transactions/{id} get transaction status
*
* ENTITY SECRET (read this): every mutating call requires an
@@ -28,6 +29,8 @@ import { SettleKitError } from "@settlekit/common";
import { createFetchWalletsHttp } from "./http.js";
import type { WalletsHttp, WalletsRequest } from "./http.js";
import { assertOk, requireString, unwrapData } from "./envelope.js";
+import { buildContractExecutionRequest } from "./contract-execution.js";
+import type { CreateContractExecutionInput } from "./contract-execution.js";
import type {
CircleAccountType,
CircleBlockchain,
@@ -128,6 +131,9 @@ export interface WalletsClient {
listWallets(input?: ListWalletsInput): Promise;
getWalletBalance(walletId: string): Promise;
createTransfer(input: CreateTransferInput): Promise;
+ createContractExecution(
+ input: CreateContractExecutionInput,
+ ): Promise;
getTransaction(id: string): Promise;
}
@@ -252,6 +258,25 @@ export function createWalletsClient(config: WalletsClientConfig): WalletsClient
});
},
+ async createContractExecution(
+ input: CreateContractExecutionInput,
+ ): Promise {
+ requireString(input.walletAddress, "createContractExecution.walletAddress");
+ requireString(input.blockchain, "createContractExecution.blockchain");
+ requireString(input.contractAddress, "createContractExecution.contractAddress");
+ requireString(input.abiFunctionSignature, "createContractExecution.abiFunctionSignature");
+ if (!Array.isArray(input.abiParameters)) {
+ throw new SettleKitError({
+ code: "validation_error",
+ message: "createContractExecution requires abiParameters to be an array",
+ });
+ }
+ const entitySecretCiphertext = await resolveEntitySecret(input, "createContractExecution");
+ return send(
+ buildContractExecutionRequest(input, entitySecretCiphertext),
+ );
+ },
+
async getTransaction(id: string): Promise {
requireString(id, "getTransaction.id");
const data = await send<{ transaction: CircleTransactionResource }>({
diff --git a/packages/circle-wallets/src/contract-execution.ts b/packages/circle-wallets/src/contract-execution.ts
new file mode 100644
index 0000000..28c10ed
--- /dev/null
+++ b/packages/circle-wallets/src/contract-execution.ts
@@ -0,0 +1,170 @@
+/**
+ * Developer-controlled wallet **contract execution** + transaction polling for
+ * Circle Web3 Services (W3S) — the mechanism Arc's ERC-8004/8183 tutorials use
+ * (`createContractExecutionTransaction` + `getTransaction` polling to a terminal
+ * `COMPLETE` / `FAILED` state).
+ *
+ * Two pieces live here:
+ * - `buildContractExecutionRequest` — a pure request builder that mirrors
+ * `createTransfer`'s body shape exactly (idempotencyKey, domain fields,
+ * `feeLevel` defaulting to MEDIUM, refId, entitySecretCiphertext). The
+ * `createContractExecution` method on `WalletsClient` composes this with the
+ * same private `send` / `resolveEntitySecret` helpers used by every mutation.
+ * - `pollTransaction` — a standalone helper that polls a transaction via the
+ * public `getTransaction` until it reaches a terminal state. A `sleep` is
+ * injectable so tests run deterministically with no real timers.
+ *
+ * This package flattens the gas fee to a top-level `feeLevel` (its own REST
+ * convention, matching `createTransfer`) rather than the Arc SDK's nested
+ * `fee: { type: "level", config: { feeLevel } }`.
+ *
+ * Source: https://developers.circle.com/w3s (Developer-Controlled Wallets).
+ */
+import { SettleKitError } from "@settlekit/common";
+import { requireString } from "./envelope.js";
+import type { WalletsRequest } from "./http.js";
+import type { WalletsClient } from "./client.js";
+import type { EntitySecretInput } from "./client.js";
+import type {
+ CircleBlockchain,
+ CircleFeeLevel,
+ CircleTransactionResource,
+ CircleTransactionState,
+} from "./types.js";
+
+/** Endpoint for developer-controlled contract execution transactions. */
+const CONTRACT_EXECUTION_PATH = "/v1/w3s/developer/transactions/contractExecution";
+
+/** Terminal failure states: a transaction in any of these will never complete. */
+const TERMINAL_FAILURE_STATES: ReadonlySet = new Set([
+ "FAILED",
+ "CANCELLED",
+ "DENIED",
+]);
+
+/** Default number of poll attempts before `pollTransaction` times out. */
+export const DEFAULT_POLL_ATTEMPTS = 30;
+/** Default delay (ms) between poll attempts. */
+export const DEFAULT_POLL_DELAY_MS = 2000;
+
+/**
+ * Input for a developer-controlled contract execution transaction. Keys on
+ * `walletAddress` + `blockchain` (the contractExecution endpoint accepts these
+ * as an alternative to `walletId`). Mirrors `CreateTransferInput`'s entity
+ * secret / idempotency / refId conventions.
+ */
+export interface CreateContractExecutionInput extends EntitySecretInput {
+ /** Source developer-controlled wallet address. */
+ walletAddress: string;
+ /** Blockchain the wallet (and target contract) live on. */
+ blockchain: CircleBlockchain;
+ /** Target smart-contract address to call. */
+ contractAddress: string;
+ /** ABI function signature, e.g. "mint(address,uint256)". */
+ abiFunctionSignature: string;
+ /** Positional ABI arguments aligned with the function signature. */
+ abiParameters: readonly (string | number | boolean)[];
+ /** Gas fee level. Defaults to MEDIUM. */
+ feeLevel?: CircleFeeLevel;
+ /** Caller reference echoed back on the transaction. */
+ refId?: string;
+ idempotencyKey?: string;
+}
+
+/**
+ * Build the contract-execution request. Pure: it never mutates `input`, and the
+ * readonly `abiParameters` are spread into a fresh array so the body is plain
+ * JSON-serializable. The body mirrors `createTransfer` exactly.
+ */
+export function buildContractExecutionRequest(
+ input: CreateContractExecutionInput,
+ entitySecretCiphertext: string,
+): WalletsRequest {
+ return {
+ method: "POST",
+ path: CONTRACT_EXECUTION_PATH,
+ body: {
+ idempotencyKey: input.idempotencyKey,
+ walletAddress: input.walletAddress,
+ blockchain: input.blockchain,
+ contractAddress: input.contractAddress,
+ abiFunctionSignature: input.abiFunctionSignature,
+ abiParameters: [...input.abiParameters],
+ feeLevel: input.feeLevel ?? "MEDIUM",
+ refId: input.refId,
+ entitySecretCiphertext,
+ },
+ };
+}
+
+/** Options for {@link pollTransaction}. */
+export interface PollTransactionOptions {
+ /** Transaction id to poll. */
+ id: string;
+ /** Maximum number of `getTransaction` calls. Defaults to {@link DEFAULT_POLL_ATTEMPTS}. */
+ attempts?: number;
+ /** Delay between attempts in ms. Defaults to {@link DEFAULT_POLL_DELAY_MS}. */
+ delayMs?: number;
+ /** Injectable sleep for deterministic tests; defaults to a real timer-based sleep. */
+ sleep?: (ms: number) => Promise;
+}
+
+/** Real timer-based sleep used as the production default. */
+function defaultSleep(ms: number): Promise {
+ return new Promise((resolve) => {
+ setTimeout(resolve, ms);
+ });
+}
+
+/**
+ * Poll a transaction until it reaches a terminal state.
+ *
+ * - On `COMPLETE` resolves with the transaction (its `txHash` is populated once
+ * broadcast).
+ * - On `FAILED` / `CANCELLED` / `DENIED` throws a `SettleKitError`
+ * (`integration_error`) carrying the failure state and Circle error fields.
+ * - After exhausting `attempts` without a terminal state throws a retryable
+ * `SettleKitError` (`integration_error`) carrying the last-seen state.
+ *
+ * No `sleep` is awaited after the final attempt (off-by-one safe).
+ */
+export async function pollTransaction(
+ client: Pick,
+ opts: PollTransactionOptions,
+): Promise {
+ requireString(opts.id, "pollTransaction.id");
+ const attempts = opts.attempts ?? DEFAULT_POLL_ATTEMPTS;
+ const delayMs = opts.delayMs ?? DEFAULT_POLL_DELAY_MS;
+ const sleep = opts.sleep ?? defaultSleep;
+
+ let lastState: CircleTransactionState | undefined;
+ for (let attempt = 0; attempt < attempts; attempt += 1) {
+ const tx = await client.getTransaction(opts.id);
+ lastState = tx.state;
+
+ if (tx.state === "COMPLETE") return tx;
+
+ if (TERMINAL_FAILURE_STATES.has(tx.state)) {
+ throw new SettleKitError({
+ code: "integration_error",
+ message: `Transaction ${opts.id} reached terminal failure state ${tx.state}`,
+ details: {
+ id: opts.id,
+ state: tx.state,
+ errorReason: tx.errorReason,
+ errorDetails: tx.errorDetails,
+ },
+ });
+ }
+
+ const isLastAttempt = attempt === attempts - 1;
+ if (!isLastAttempt) await sleep(delayMs);
+ }
+
+ throw new SettleKitError({
+ code: "integration_error",
+ message: `Transaction ${opts.id} did not reach a terminal state within ${attempts} attempts`,
+ retryable: true,
+ details: { id: opts.id, state: lastState, attempts },
+ });
+}
diff --git a/packages/circle-wallets/src/index.ts b/packages/circle-wallets/src/index.ts
index 7cabb21..a4891cd 100644
--- a/packages/circle-wallets/src/index.ts
+++ b/packages/circle-wallets/src/index.ts
@@ -14,6 +14,12 @@ export type {
CreateTransferInput,
} from "./client.js";
+export { pollTransaction, buildContractExecutionRequest } from "./contract-execution.js";
+export type {
+ CreateContractExecutionInput,
+ PollTransactionOptions,
+} from "./contract-execution.js";
+
export { createUserWalletsClient } from "./user-wallets.js";
export type {
UserWalletsClient,
diff --git a/packages/circle-wallets/test/contract-execution.test.ts b/packages/circle-wallets/test/contract-execution.test.ts
new file mode 100644
index 0000000..60e8463
--- /dev/null
+++ b/packages/circle-wallets/test/contract-execution.test.ts
@@ -0,0 +1,284 @@
+import { describe, expect, it, vi } from "vitest";
+import { SettleKitError } from "@settlekit/common";
+import { createWalletsClient, pollTransaction } from "../src/index.js";
+import type {
+ CircleTransactionResource,
+ WalletsClient,
+ WalletsHttp,
+ WalletsRequest,
+ WalletsResponse,
+} from "../src/index.js";
+
+/** In-memory transport that records requests and returns scripted responses. */
+function recordingHttp(responder: (req: WalletsRequest) => WalletsResponse): {
+ http: WalletsHttp;
+ requests: WalletsRequest[];
+} {
+ const requests: WalletsRequest[] = [];
+ const http: WalletsHttp = {
+ async request(req: WalletsRequest): Promise {
+ requests.push(req);
+ return responder(req);
+ },
+ };
+ return { http, requests };
+}
+
+const CIPHER = "ZmFrZS1jaXBoZXJ0ZXh0"; // base64-ish placeholder ciphertext
+const CE_PATH = "/v1/w3s/developer/transactions/contractExecution";
+
+/** A minimal transaction resource for poll stubs. */
+function tx(
+ state: CircleTransactionResource["state"],
+ extra: Partial = {},
+): CircleTransactionResource {
+ return {
+ id: "tx_ce_1",
+ blockchain: "ETH-SEPOLIA",
+ state,
+ createDate: "2026-01-01T00:00:00Z",
+ updateDate: "2026-01-01T00:00:00Z",
+ ...extra,
+ };
+}
+
+describe("createContractExecution", () => {
+ it("posts the contract execution request shape", async () => {
+ const { http, requests } = recordingHttp(() => ({
+ status: 201,
+ body: {
+ data: {
+ id: "tx_ce_1",
+ blockchain: "ETH-SEPOLIA",
+ state: "INITIATED",
+ createDate: "2026-01-01T00:00:00Z",
+ updateDate: "2026-01-01T00:00:00Z",
+ },
+ },
+ }));
+ const client = createWalletsClient({ apiKey: "k", http });
+
+ const result = await client.createContractExecution({
+ walletAddress: "0xwallet",
+ blockchain: "ETH-SEPOLIA",
+ contractAddress: "0xcontract",
+ abiFunctionSignature: "mint(address,uint256)",
+ abiParameters: ["0xrecipient", 1],
+ feeLevel: "HIGH",
+ refId: "agent_42",
+ entitySecretCiphertext: CIPHER,
+ idempotencyKey: "idem-ce",
+ });
+
+ const req = requests[0]!;
+ expect(req.method).toBe("POST");
+ expect(req.path).toBe(CE_PATH);
+ expect(req.body).toMatchObject({
+ walletAddress: "0xwallet",
+ blockchain: "ETH-SEPOLIA",
+ contractAddress: "0xcontract",
+ abiFunctionSignature: "mint(address,uint256)",
+ abiParameters: ["0xrecipient", 1],
+ feeLevel: "HIGH",
+ refId: "agent_42",
+ entitySecretCiphertext: CIPHER,
+ idempotencyKey: "idem-ce",
+ });
+ expect(result).toMatchObject({ id: "tx_ce_1", state: "INITIATED" });
+ });
+
+ it("defaults feeLevel to MEDIUM and does not mutate caller abiParameters", async () => {
+ const { http, requests } = recordingHttp(() => ({
+ status: 201,
+ body: {
+ data: {
+ id: "tx_ce_2",
+ blockchain: "ETH-SEPOLIA",
+ state: "INITIATED",
+ createDate: "2026-01-01T00:00:00Z",
+ updateDate: "2026-01-01T00:00:00Z",
+ },
+ },
+ }));
+ const client = createWalletsClient({ apiKey: "k", http });
+ const params: readonly (string | number | boolean)[] = ["0xrecipient", 5, true];
+
+ await client.createContractExecution({
+ walletAddress: "0xwallet",
+ blockchain: "ETH-SEPOLIA",
+ contractAddress: "0xcontract",
+ abiFunctionSignature: "approve(address,uint256)",
+ abiParameters: params,
+ entitySecretCiphertext: CIPHER,
+ });
+
+ const body = requests[0]!.body as { feeLevel: string; abiParameters: unknown[] };
+ expect(body.feeLevel).toBe("MEDIUM");
+ // Fresh array, not the same reference.
+ expect(body.abiParameters).not.toBe(params);
+ expect(body.abiParameters).toEqual(["0xrecipient", 5, true]);
+ });
+
+ it("resolves the entity secret via the provider when no per-call ciphertext is given", async () => {
+ let calls = 0;
+ const { http, requests } = recordingHttp(() => ({
+ status: 201,
+ body: {
+ data: {
+ id: "tx_ce_3",
+ blockchain: "ETH-SEPOLIA",
+ state: "INITIATED",
+ createDate: "2026-01-01T00:00:00Z",
+ updateDate: "2026-01-01T00:00:00Z",
+ },
+ },
+ }));
+ const client = createWalletsClient({
+ apiKey: "k",
+ http,
+ entitySecretProvider: () => {
+ calls += 1;
+ return `cipher-${calls}`;
+ },
+ });
+
+ await client.createContractExecution({
+ walletAddress: "0xwallet",
+ blockchain: "ETH-SEPOLIA",
+ contractAddress: "0xcontract",
+ abiFunctionSignature: "mint(address,uint256)",
+ abiParameters: ["0xrecipient", 1],
+ });
+
+ expect(calls).toBe(1);
+ expect((requests[0]!.body as { entitySecretCiphertext: string }).entitySecretCiphertext).toBe(
+ "cipher-1",
+ );
+ });
+
+ it("rejects when no entity secret source is available", async () => {
+ const { http } = recordingHttp(() => ({ status: 201, body: { data: tx("INITIATED") } }));
+ const client = createWalletsClient({ apiKey: "k", http });
+ await expect(
+ client.createContractExecution({
+ walletAddress: "0xwallet",
+ blockchain: "ETH-SEPOLIA",
+ contractAddress: "0xcontract",
+ abiFunctionSignature: "mint(address,uint256)",
+ abiParameters: [],
+ }),
+ ).rejects.toThrow(/entitySecretCiphertext/);
+ });
+
+ it("rejects a missing contractAddress with a validation error", async () => {
+ const { http } = recordingHttp(() => ({ status: 201, body: { data: tx("INITIATED") } }));
+ const client = createWalletsClient({ apiKey: "k", http });
+ await expect(
+ client.createContractExecution({
+ walletAddress: "0xwallet",
+ blockchain: "ETH-SEPOLIA",
+ contractAddress: "",
+ abiFunctionSignature: "mint(address,uint256)",
+ abiParameters: [],
+ entitySecretCiphertext: CIPHER,
+ }),
+ ).rejects.toMatchObject({ code: "validation_error" });
+ });
+
+ it("rejects an empty abiFunctionSignature with a validation error", async () => {
+ const { http } = recordingHttp(() => ({ status: 201, body: { data: tx("INITIATED") } }));
+ const client = createWalletsClient({ apiKey: "k", http });
+ await expect(
+ client.createContractExecution({
+ walletAddress: "0xwallet",
+ blockchain: "ETH-SEPOLIA",
+ contractAddress: "0xcontract",
+ abiFunctionSignature: "",
+ abiParameters: [],
+ entitySecretCiphertext: CIPHER,
+ }),
+ ).rejects.toBeInstanceOf(SettleKitError);
+ });
+});
+
+/** Build a stub client exposing only getTransaction, scripted by a queue. */
+function stubClient(states: CircleTransactionResource[]): {
+ client: Pick;
+ getTransaction: ReturnType;
+} {
+ let i = 0;
+ const getTransaction = vi.fn(async () => {
+ const next = states[Math.min(i, states.length - 1)]!;
+ i += 1;
+ return next;
+ });
+ return { client: { getTransaction }, getTransaction };
+}
+
+describe("pollTransaction", () => {
+ it("polls until COMPLETE and returns the transaction with txHash", async () => {
+ const { client, getTransaction } = stubClient([
+ tx("CONFIRMED"),
+ tx("CONFIRMED"),
+ tx("COMPLETE", { txHash: "0xhash" }),
+ ]);
+ const sleep = vi.fn(async () => {});
+
+ const result = await pollTransaction(client, {
+ id: "tx_ce_1",
+ attempts: 5,
+ delayMs: 1000,
+ sleep,
+ });
+
+ expect(result.txHash).toBe("0xhash");
+ expect(getTransaction).toHaveBeenCalledTimes(3);
+ expect(sleep).toHaveBeenCalledTimes(2);
+ expect(sleep).toHaveBeenNthCalledWith(1, 1000);
+ expect(sleep).toHaveBeenNthCalledWith(2, 1000);
+ });
+
+ it("throws on a FAILED terminal state carrying error fields", async () => {
+ const { client } = stubClient([
+ tx("FAILED", { errorReason: "reverted", errorDetails: "OOG" }),
+ ]);
+ const sleep = vi.fn(async () => {});
+
+ await expect(
+ pollTransaction(client, { id: "tx_ce_1", attempts: 5, delayMs: 1000, sleep }),
+ ).rejects.toMatchObject({
+ code: "integration_error",
+ details: { state: "FAILED", errorReason: "reverted", errorDetails: "OOG" },
+ });
+ expect(sleep).not.toHaveBeenCalled();
+ });
+
+ it("throws on a CANCELLED terminal state", async () => {
+ const { client } = stubClient([tx("CANCELLED")]);
+ await expect(
+ pollTransaction(client, { id: "tx_ce_1", attempts: 5, sleep: async () => {} }),
+ ).rejects.toMatchObject({ code: "integration_error", details: { state: "CANCELLED" } });
+ });
+
+ it("times out with a retryable error after exhausting attempts", async () => {
+ const { client, getTransaction } = stubClient([tx("SENT")]);
+ const sleep = vi.fn(async () => {});
+
+ await expect(
+ pollTransaction(client, { id: "tx_ce_1", attempts: 3, delayMs: 500, sleep }),
+ ).rejects.toMatchObject({
+ code: "integration_error",
+ retryable: true,
+ details: { state: "SENT", attempts: 3 },
+ });
+ expect(getTransaction).toHaveBeenCalledTimes(3);
+ expect(sleep).toHaveBeenCalledTimes(2); // no sleep after the final attempt
+ });
+
+ it("rejects an empty id with a validation error", async () => {
+ const { client } = stubClient([tx("COMPLETE", { txHash: "0xhash" })]);
+ await expect(
+ pollTransaction(client, { id: "", sleep: async () => {} }),
+ ).rejects.toMatchObject({ code: "validation_error" });
+ });
+});
diff --git a/packages/erc8004/README.md b/packages/erc8004/README.md
new file mode 100644
index 0000000..bba9785
--- /dev/null
+++ b/packages/erc8004/README.md
@@ -0,0 +1,321 @@
+# @settlekit/erc8004
+
+ERC-8004 agent identity, reputation, and validation on [Arc](https://docs.arc.io),
+exposed through a SettleKit-idiomatic facade that returns `Result` values instead
+of throwing.
+
+ERC-8004 gives autonomous agents:
+
+- **Identity** — an ERC-721 minted by the **IdentityRegistry** (`register(string)`).
+- **Reputation** — feedback attestations recorded by external validators in the
+ **ReputationRegistry** (`giveFeedback(...)`).
+- **Validation** — a request/response flow in the **ValidationRegistry**
+ (`validationRequest(...)` / `validationResponse(...)` / `getValidationStatus(bytes32)`).
+
+Deployed Arc Testnet registry addresses are exported from
+[`src/addresses.ts`](./src/addresses.ts) as `ARC_TESTNET_REGISTRIES`.
+
+## Design: port / adapter (no chain dependency)
+
+This package depends only on `@settlekit/common`. It **never imports a chain
+library**. The on-chain operations are declared as an injectable interface — the
+[`Erc8004Port`](./src/port.ts) — which the consumer implements with viem, ethers,
+or Circle Developer-Controlled Wallets, capturing the signing adapter by closure.
+
+This mirrors the proven pattern in `@settlekit/app-kit`. Benefits: the package
+stays dependency-light and chain-agnostic, and tests/demos inject a deterministic
+[`LocalErc8004Port`](./src/local-port.ts).
+
+## Quickstart (deterministic, in-memory)
+
+```ts
+import { configureErc8004, LocalErc8004Port } from "@settlekit/erc8004";
+import { isOk } from "@settlekit/common";
+
+const port = new LocalErc8004Port({ owner: "0xowner" });
+const registry = configureErc8004({ port });
+
+const reg = await registry.registerAgent({ metadataUri: "ipfs://agent.json" });
+if (isOk(reg)) console.log(reg.value.txHash); // 0xlocal00000001
+
+const agent = await registry.resolveAgent({ owner: "0xowner" });
+if (isOk(agent) && agent.value) console.log(agent.value.agentId); // "1"
+```
+
+## API reference: `AgentRegistryClient`
+
+Every method returns `Promise>` from `@settlekit/common`
+(`ok(value)` / `err(SettleKitError)`). Validation failures short-circuit with
+`code: "validation_error"`; thrown port errors are mapped to
+`code: "integration_error"` (`retryable: true`).
+
+| Method | Validates | Returns |
+| --- | --- | --- |
+| `registerAgent({ metadataUri })` | non-empty `metadataUri` | `TxResult` |
+| `resolveAgent({ owner })` | non-empty `owner` | `AgentIdentity \| null` |
+| `giveFeedback(FeedbackInput)` | non-empty `agentId`/`tag`, integer `score` 0..100, `feedbackType` 0..255 (default 0) | `TxResult` |
+| `requestValidation(ValidationRequestInput)` | non-empty `agentId`/`validator`/`requestUri`/`subject` | `ValidationRequestResult` (`TxResult` + `requestHash`) |
+| `respondValidation(ValidationResponseInput)` | non-empty `requestHash`, integer `response` 0..100 | `TxResult` |
+| `getValidationStatus({ requestHash })` | non-empty `requestHash` | `ValidationStatus` |
+
+`resolveAgent` returns `ok(null)` when the owner has no registered agent.
+
+### `requestHash` is port-owned
+
+`requestValidation` does NOT take a hash — the **port** derives `requestHash`
+from the stable `subject` string and returns it. The same subject reproduces the
+same hash, so status can be looked up later.
+
+`LocalErc8004Port` uses an FNV-1a hash (padded to a bytes32-shaped hex) for
+stable in-memory lookup. **This is not chain-compatible.** A real on-chain port
+must derive `requestHash` with the ValidationRegistry's actual scheme (typically
+`keccak256`) so it matches what the contract stores.
+
+## On-chain contract signatures
+
+The consumer's port maps the domain inputs onto these ValidationRegistry /
+ReputationRegistry / IdentityRegistry calls:
+
+```solidity
+// IdentityRegistry
+register(string metadataUri)
+
+// ReputationRegistry
+giveFeedback(uint256 agentId, int128 score, uint8 feedbackType,
+ string tag, string metadataUri, string evidenceUri,
+ string comment, bytes32 ref)
+
+// ValidationRegistry
+validationRequest(address validator, uint256 agentId, string requestUri, bytes32 requestHash)
+validationResponse(bytes32 requestHash, uint8 response, string responseUri, bytes32 tag, string note)
+getValidationStatus(bytes32 requestHash)
+```
+
+Note: `score` is `int128` on-chain. This package validates `score` as an integer
+in 0..100 (the documented convention); a consumer needing the wider `int128`
+range can relax that in its own port.
+
+## Wiring sketch 1 — viem
+
+The port is consumer-owned (this package adds no viem dependency):
+
+```ts
+import {
+ createPublicClient, createWalletClient, http, keccak256, toHex, getAddress,
+} from "viem";
+import type { Erc8004Port } from "@settlekit/erc8004";
+import { ARC_TESTNET_REGISTRIES, ARC_TESTNET_RPC_URL, explorerTxUrl } from "@settlekit/erc8004";
+
+// Provide your own ABIs for the three registries.
+import { identityAbi, reputationAbi, validationAbi } from "./abis.js";
+
+export function createViemErc8004Port(opts: {
+ account: `0x${string}`;
+ transport?: ReturnType;
+}): Erc8004Port {
+ const transport = opts.transport ?? http(ARC_TESTNET_RPC_URL);
+ const pub = createPublicClient({ transport });
+ const wallet = createWalletClient({ account: opts.account, transport });
+ const r = ARC_TESTNET_REGISTRIES;
+
+ return {
+ async register({ metadataUri }) {
+ const txHash = await wallet.writeContract({
+ address: r.identityRegistry as `0x${string}`,
+ abi: identityAbi,
+ functionName: "register",
+ args: [metadataUri],
+ });
+ return { txHash, explorerUrl: explorerTxUrl(txHash) };
+ },
+
+ async findAgentId({ owner }) {
+ const id = (await pub.readContract({
+ address: r.identityRegistry as `0x${string}`,
+ abi: identityAbi,
+ functionName: "agentIdOf",
+ args: [getAddress(owner)],
+ })) as bigint;
+ return id === 0n ? null : id.toString();
+ },
+
+ async ownerOf({ agentId }) {
+ return (await pub.readContract({
+ address: r.identityRegistry as `0x${string}`,
+ abi: identityAbi,
+ functionName: "ownerOf",
+ args: [BigInt(agentId)],
+ })) as string;
+ },
+
+ async tokenUri({ agentId }) {
+ return (await pub.readContract({
+ address: r.identityRegistry as `0x${string}`,
+ abi: identityAbi,
+ functionName: "tokenURI",
+ args: [BigInt(agentId)],
+ })) as string;
+ },
+
+ async giveFeedback(input) {
+ const txHash = await wallet.writeContract({
+ address: r.reputationRegistry as `0x${string}`,
+ abi: reputationAbi,
+ functionName: "giveFeedback",
+ args: [
+ BigInt(input.agentId), BigInt(input.score), input.feedbackType ?? 0,
+ input.tag, input.metadataUri ?? "", input.evidenceUri ?? "",
+ input.comment ?? "", "0x".padEnd(66, "0") as `0x${string}`,
+ ],
+ });
+ return { txHash, explorerUrl: explorerTxUrl(txHash) };
+ },
+
+ async requestValidation(input) {
+ // The port owns hashing — keep this aligned with the contract's scheme.
+ const requestHash = keccak256(toHex(input.subject));
+ const txHash = await wallet.writeContract({
+ address: r.validationRegistry as `0x${string}`,
+ abi: validationAbi,
+ functionName: "validationRequest",
+ args: [getAddress(input.validator), BigInt(input.agentId), input.requestUri, requestHash],
+ });
+ return { txHash, explorerUrl: explorerTxUrl(txHash), requestHash };
+ },
+
+ async respondValidation(input) {
+ const txHash = await wallet.writeContract({
+ address: r.validationRegistry as `0x${string}`,
+ abi: validationAbi,
+ functionName: "validationResponse",
+ args: [
+ input.requestHash as `0x${string}`, input.response, input.responseUri ?? "",
+ ("0x" + (input.tag ?? "").padEnd(64, "0")).slice(0, 66) as `0x${string}`, "",
+ ],
+ });
+ return { txHash, explorerUrl: explorerTxUrl(txHash) };
+ },
+
+ async getValidationStatus({ requestHash }) {
+ const [validator, agentId, response, tag] = (await pub.readContract({
+ address: r.validationRegistry as `0x${string}`,
+ abi: validationAbi,
+ functionName: "getValidationStatus",
+ args: [requestHash as `0x${string}`],
+ })) as [string, bigint, number, string];
+ return { validator, agentId: agentId.toString(), response, tag, passed: response === 100 };
+ },
+ };
+}
+```
+
+```ts
+import { configureErc8004 } from "@settlekit/erc8004";
+const registry = configureErc8004({ port: createViemErc8004Port({ account }) });
+```
+
+## Wiring sketch 2 — Circle Developer-Controlled Wallets
+
+Submit the same contract calls through DCW contract-execution. Encode the
+function call (e.g. with viem's `encodeFunctionData`) and submit via the DCW SDK:
+
+```ts
+import { initiateDeveloperControlledWalletsClient } from "@circle-fin/developer-controlled-wallets";
+import { encodeFunctionData, keccak256, toHex } from "viem";
+import type { Erc8004Port } from "@settlekit/erc8004";
+import { ARC_TESTNET_REGISTRIES, explorerTxUrl } from "@settlekit/erc8004";
+import { identityAbi, reputationAbi, validationAbi } from "./abis.js";
+
+export function createCircleDcwErc8004Port(opts: {
+ walletId: string;
+ apiKey: string;
+ entitySecret: string;
+}): Erc8004Port {
+ const dcw = initiateDeveloperControlledWalletsClient({
+ apiKey: opts.apiKey,
+ entitySecret: opts.entitySecret,
+ });
+ const r = ARC_TESTNET_REGISTRIES;
+
+ async function exec(address: string, callData: `0x${string}`) {
+ const res = await dcw.createContractExecutionTransaction({
+ walletId: opts.walletId,
+ contractAddress: address,
+ callData,
+ fee: { type: "level", config: { feeLevel: "MEDIUM" } },
+ });
+ const txHash = res.data?.txHash ?? res.data?.id ?? "";
+ return { txHash, explorerUrl: explorerTxUrl(txHash) };
+ }
+
+ return {
+ async register({ metadataUri }) {
+ return exec(
+ r.identityRegistry,
+ encodeFunctionData({ abi: identityAbi, functionName: "register", args: [metadataUri] }),
+ );
+ },
+ async requestValidation(input) {
+ const requestHash = keccak256(toHex(input.subject)); // align with contract scheme
+ const tx = await exec(
+ r.validationRegistry,
+ encodeFunctionData({
+ abi: validationAbi,
+ functionName: "validationRequest",
+ args: [input.validator, BigInt(input.agentId), input.requestUri, requestHash],
+ }),
+ );
+ return { ...tx, requestHash };
+ },
+ // findAgentId / ownerOf / tokenUri / getValidationStatus are read-only:
+ // use a viem/ethers public client (DCW is for signing writes), or the
+ // chain RPC directly. giveFeedback / respondValidation mirror register
+ // via encodeFunctionData + exec(...).
+ findAgentId: async () => null,
+ ownerOf: async () => "",
+ tokenUri: async () => "",
+ giveFeedback: async (input) =>
+ exec(
+ r.reputationRegistry,
+ encodeFunctionData({
+ abi: reputationAbi,
+ functionName: "giveFeedback",
+ args: [
+ BigInt(input.agentId), BigInt(input.score), input.feedbackType ?? 0,
+ input.tag, input.metadataUri ?? "", input.evidenceUri ?? "",
+ input.comment ?? "", ("0x".padEnd(66, "0")) as `0x${string}`,
+ ],
+ }),
+ ),
+ respondValidation: async (input) =>
+ exec(
+ r.validationRegistry,
+ encodeFunctionData({
+ abi: validationAbi,
+ functionName: "validationResponse",
+ args: [
+ input.requestHash as `0x${string}`, input.response, input.responseUri ?? "",
+ ("0x".padEnd(66, "0")) as `0x${string}`, "",
+ ],
+ }),
+ ),
+ getValidationStatus: async () => {
+ throw new Error("read getValidationStatus via a public client");
+ },
+ };
+}
+```
+
+> The two sketches are illustrative. ABIs, the exact read function names
+> (`agentIdOf`, etc.), and the contract's `requestHash` scheme must match the
+> deployed Arc registries — confirm against the Arc docs before mainnet use.
+
+## Testing
+
+```bash
+pnpm --filter @settlekit/erc8004 build
+pnpm --filter @settlekit/erc8004 test
+```
+
+`LocalErc8004Port` is fully deterministic (no `Date.now()` / `Math.random()`):
+sequential agent ids, counter-based tx hashes, FNV-1a request hashes.
diff --git a/packages/erc8004/package.json b/packages/erc8004/package.json
new file mode 100644
index 0000000..68a8505
--- /dev/null
+++ b/packages/erc8004/package.json
@@ -0,0 +1,26 @@
+{
+ "name": "@settlekit/erc8004",
+ "version": "0.0.0",
+ "type": "module",
+ "main": "./dist/index.js",
+ "types": "./dist/index.d.ts",
+ "exports": {
+ ".": {
+ "types": "./dist/index.d.ts",
+ "default": "./dist/index.js"
+ }
+ },
+ "files": ["dist"],
+ "scripts": {
+ "build": "tsc -b",
+ "test": "vitest run"
+ },
+ "dependencies": {
+ "@settlekit/common": "workspace:*"
+ },
+ "devDependencies": {
+ "@types/node": "^20.14.0",
+ "typescript": "^5.5.4",
+ "vitest": "^2.0.5"
+ }
+}
diff --git a/packages/erc8004/src/addresses.ts b/packages/erc8004/src/addresses.ts
new file mode 100644
index 0000000..346e05c
--- /dev/null
+++ b/packages/erc8004/src/addresses.ts
@@ -0,0 +1,39 @@
+/**
+ * ERC-8004 on-chain registry addresses on Arc.
+ *
+ * ERC-8004 gives autonomous agents an on-chain identity (an ERC-721 minted by
+ * the IdentityRegistry), reputation (attestations recorded by external
+ * validators in the ReputationRegistry), and a request/response validation flow
+ * (the ValidationRegistry). These are the deployed Arc Testnet addresses from
+ * the Arc docs — verify against https://docs.arc.io before mainnet use.
+ */
+
+/** A set of ERC-8004 registry addresses for one network. */
+export interface Erc8004Registries {
+ identityRegistry: string;
+ reputationRegistry: string;
+ validationRegistry: string;
+}
+
+/** Arc Testnet ERC-8004 registries. */
+export const ARC_TESTNET_REGISTRIES: Erc8004Registries = {
+ identityRegistry: "0x8004A818BFB912233c491871b3d84c89A494BD9e",
+ reputationRegistry: "0x8004B663056A597Dffe9eCcC1965A193B7388713",
+ validationRegistry: "0x8004Cb1BF31DAf7788923b405b754f57acEB4272",
+};
+
+/** Arc Testnet JSON-RPC endpoint. */
+export const ARC_TESTNET_RPC_URL = "https://rpc.testnet.arc.network/";
+
+/** Arc Testnet block explorer base. */
+export const ARC_TESTNET_EXPLORER = "https://testnet.arcscan.app";
+
+/** Build an explorer URL for a transaction hash. */
+export function explorerTxUrl(txHash: string, base = ARC_TESTNET_EXPLORER): string {
+ return `${base}/tx/${txHash}`;
+}
+
+/** Build an explorer URL for an address. */
+export function explorerAddressUrl(address: string, base = ARC_TESTNET_EXPLORER): string {
+ return `${base}/address/${address}`;
+}
diff --git a/packages/erc8004/src/client.ts b/packages/erc8004/src/client.ts
new file mode 100644
index 0000000..d244c68
--- /dev/null
+++ b/packages/erc8004/src/client.ts
@@ -0,0 +1,150 @@
+/**
+ * {@link AgentRegistryClient} — the SettleKit-idiomatic facade over an injected
+ * {@link Erc8004Port}. Every method validates its request, calls the port, and
+ * returns a `Result` instead of throwing, so callers handle success/failure
+ * uniformly. Mirrors app-kit's `ArcPaymentClient`.
+ */
+
+import { type Result, SettleKitError, err, ok } from "@settlekit/common";
+import type { Erc8004Port } from "./port.js";
+import type {
+ AgentIdentity,
+ FeedbackInput,
+ TxResult,
+ ValidationRequestInput,
+ ValidationRequestResult,
+ ValidationResponseInput,
+ ValidationStatus,
+} from "./types.js";
+import {
+ firstError,
+ validateAddress,
+ validateIntInRange,
+ validateNonEmpty,
+ validateScore,
+} from "./validate.js";
+
+/** Default feedback category when a request omits one. */
+const DEFAULT_FEEDBACK_TYPE = 0;
+
+/** Inclusive bounds for the uint8 `feedbackType` field. */
+const FEEDBACK_TYPE_MIN = 0;
+const FEEDBACK_TYPE_MAX = 255;
+
+/** Inclusive bounds for the uint8 validation `response` field (0..100). */
+const RESPONSE_MIN = 0;
+const RESPONSE_MAX = 100;
+
+/** Configuration for an {@link AgentRegistryClient}. */
+export interface AgentRegistryClientConfig {
+ /** The injected ERC-8004 port (viem/Circle DCW impl, or {@link LocalErc8004Port}). */
+ port: Erc8004Port;
+}
+
+export class AgentRegistryClient {
+ private readonly port: Erc8004Port;
+
+ constructor(config: AgentRegistryClientConfig) {
+ this.port = config.port;
+ }
+
+ /** Wrap a port call, mapping thrown errors to a typed integration error. */
+ private async run(op: string, call: () => Promise): Promise> {
+ try {
+ const value = await call();
+ return ok(value);
+ } catch (cause) {
+ return err(
+ new SettleKitError({
+ code: "integration_error",
+ message: `erc8004 ${op} failed: ${cause instanceof Error ? cause.message : String(cause)}`,
+ retryable: true,
+ cause,
+ details: { op },
+ }),
+ );
+ }
+ }
+
+ /** Mint a new agent identity with the given metadata URI. */
+ async registerAgent(input: { metadataUri: string }): Promise> {
+ const invalid = firstError(validateNonEmpty(input.metadataUri, "metadataUri"));
+ if (invalid !== null) return err(invalid);
+
+ return this.run("register", () => this.port.register({ metadataUri: input.metadataUri }));
+ }
+
+ /**
+ * Resolve an owner's agent identity. Returns `ok(null)` when the owner has no
+ * registered agent.
+ */
+ async resolveAgent(input: { owner: string }): Promise> {
+ const invalid = firstError(validateAddress(input.owner, "owner"));
+ if (invalid !== null) return err(invalid);
+
+ return this.run("resolveAgent", async () => {
+ const agentId = await this.port.findAgentId({ owner: input.owner });
+ if (agentId === null) return null;
+ const [owner, metadataUri] = await Promise.all([
+ this.port.ownerOf({ agentId }),
+ this.port.tokenUri({ agentId }),
+ ]);
+ const identity: AgentIdentity = { agentId, owner, metadataUri };
+ return identity;
+ });
+ }
+
+ /** Record reputation feedback about an agent. */
+ async giveFeedback(input: FeedbackInput): Promise> {
+ const feedbackType = input.feedbackType ?? DEFAULT_FEEDBACK_TYPE;
+ const invalid = firstError(
+ validateNonEmpty(input.agentId, "agentId"),
+ validateScore(input.score),
+ validateIntInRange(feedbackType, FEEDBACK_TYPE_MIN, FEEDBACK_TYPE_MAX, "feedbackType"),
+ validateNonEmpty(input.tag, "tag"),
+ );
+ if (invalid !== null) return err(invalid);
+
+ return this.run("giveFeedback", () =>
+ this.port.giveFeedback({ ...input, feedbackType }),
+ );
+ }
+
+ /** Submit a validation request; the port derives the request hash. */
+ async requestValidation(
+ input: ValidationRequestInput,
+ ): Promise> {
+ const invalid = firstError(
+ validateNonEmpty(input.agentId, "agentId"),
+ validateAddress(input.validator, "validator"),
+ validateNonEmpty(input.requestUri, "requestUri"),
+ validateNonEmpty(input.subject, "subject"),
+ );
+ if (invalid !== null) return err(invalid);
+
+ return this.run("requestValidation", () => this.port.requestValidation(input));
+ }
+
+ /** Submit a validator's response to a prior request. */
+ async respondValidation(input: ValidationResponseInput): Promise> {
+ const invalid = firstError(
+ validateNonEmpty(input.requestHash, "requestHash"),
+ validateIntInRange(input.response, RESPONSE_MIN, RESPONSE_MAX, "response"),
+ );
+ if (invalid !== null) return err(invalid);
+
+ return this.run("respondValidation", () => this.port.respondValidation(input));
+ }
+
+ /** Read the current status of a validation request by its hash. */
+ async getValidationStatus(input: {
+ requestHash: string;
+ }): Promise> {
+ const invalid = firstError(validateNonEmpty(input.requestHash, "requestHash"));
+ if (invalid !== null) return err(invalid);
+
+ return this.run("getValidationStatus", () =>
+ this.port.getValidationStatus({ requestHash: input.requestHash }),
+ );
+ }
+}
diff --git a/packages/erc8004/src/configure.ts b/packages/erc8004/src/configure.ts
new file mode 100644
index 0000000..9732cd4
--- /dev/null
+++ b/packages/erc8004/src/configure.ts
@@ -0,0 +1,32 @@
+/**
+ * One factory to build an {@link AgentRegistryClient}. The consumer injects a
+ * configured {@link Erc8004Port}; this package never depends on a chain library.
+ *
+ * Live wiring (in the consumer, which owns the chain dependency) — the port can
+ * be backed by viem or Circle Developer-Controlled Wallets:
+ *
+ * ```ts
+ * import { configureErc8004 } from "@settlekit/erc8004";
+ * import { createViemErc8004Port } from "./my-viem-port.js"; // consumer-owned
+ *
+ * const registry = configureErc8004({ port: createViemErc8004Port({ walletClient, publicClient }) });
+ * const res = await registry.registerAgent({ metadataUri: "ipfs://agent.json" });
+ * ```
+ *
+ * Tests and demos inject {@link LocalErc8004Port} instead of a real port.
+ * See the README for full viem and Circle DCW port sketches.
+ */
+
+import { AgentRegistryClient } from "./client.js";
+import type { Erc8004Port } from "./port.js";
+
+/** Options for {@link configureErc8004}. */
+export interface ConfigureErc8004Options {
+ /** The injected ERC-8004 port implementation. */
+ port: Erc8004Port;
+}
+
+/** Build a configured {@link AgentRegistryClient}. */
+export function configureErc8004(options: ConfigureErc8004Options): AgentRegistryClient {
+ return new AgentRegistryClient({ port: options.port });
+}
diff --git a/packages/erc8004/src/index.ts b/packages/erc8004/src/index.ts
new file mode 100644
index 0000000..7539362
--- /dev/null
+++ b/packages/erc8004/src/index.ts
@@ -0,0 +1,7 @@
+export * from "./addresses.js";
+export * from "./types.js";
+export * from "./port.js";
+export * from "./validate.js";
+export * from "./client.js";
+export * from "./local-port.js";
+export * from "./configure.js";
diff --git a/packages/erc8004/src/local-port.ts b/packages/erc8004/src/local-port.ts
new file mode 100644
index 0000000..3529fb9
--- /dev/null
+++ b/packages/erc8004/src/local-port.ts
@@ -0,0 +1,160 @@
+/**
+ * {@link LocalErc8004Port} — a deterministic, in-memory {@link Erc8004Port} for
+ * tests, demos, and local development. It never touches a chain: it records
+ * every call and returns synthetic, monotonically-numbered transaction hashes
+ * so assertions are stable across runs. Mirrors app-kit's `LocalAppKitSdk`.
+ *
+ * Determinism: no `Date.now()` / `Math.random()`. Agent ids are sequential
+ * decimal strings; tx hashes are counter-based; `requestHash` is an FNV-1a hash
+ * of the subject padded to a bytes32-shaped hex.
+ *
+ * IMPORTANT: the FNV-1a `requestHash` is for stable in-memory lookup ONLY and
+ * is NOT chain-compatible. A real on-chain port derives bytes32 via the
+ * ValidationRegistry's actual hashing scheme (typically keccak256).
+ */
+
+import type { Erc8004Port } from "./port.js";
+import type {
+ FeedbackInput,
+ TxResult,
+ ValidationRequestInput,
+ ValidationRequestResult,
+ ValidationResponseInput,
+ ValidationStatus,
+} from "./types.js";
+import { ARC_TESTNET_EXPLORER, explorerTxUrl } from "./addresses.js";
+
+/**
+ * Response value that marks a validation as passed. Per {@link ./types.js}
+ * (`ValidationResponseInput`: "0–100; 100 = passed") we use a strict pass: a
+ * response equal to {@link PASS_THRESHOLD}.
+ */
+const PASS_THRESHOLD = 100;
+
+/** FNV-1a 32-bit offset basis. */
+const FNV_OFFSET_BASIS = 0x811c9dc5;
+/** FNV-1a 32-bit prime. */
+const FNV_PRIME = 0x01000193;
+
+/**
+ * Stable FNV-1a (32-bit) hash of `subject`, rendered as a 0x-prefixed,
+ * 64-hex-char (bytes32-shaped) string. Deterministic and dependency-free.
+ */
+export function fnv1aHex(subject: string): string {
+ let hash = FNV_OFFSET_BASIS;
+ for (let i = 0; i < subject.length; i += 1) {
+ hash ^= subject.charCodeAt(i);
+ hash = Math.imul(hash, FNV_PRIME) >>> 0;
+ }
+ const word = hash.toString(16).padStart(8, "0");
+ return `0x${word.padStart(64, "0")}`;
+}
+
+/** Options controlling the local port's simulated behavior. */
+export interface LocalErc8004Options {
+ /** The registering wallet that owns every agent minted by `register`. */
+ owner: string;
+}
+
+export class LocalErc8004Port implements Erc8004Port {
+ private readonly owner: string;
+ private agentSeq = 0;
+ private txCounter = 0;
+ private readonly metadataByAgent = new Map();
+ private readonly ownerByAgent = new Map();
+ private readonly feedbackRecords: FeedbackInput[] = [];
+ private readonly validations = new Map();
+
+ constructor(options: LocalErc8004Options) {
+ this.owner = options.owner;
+ }
+
+ /** All recorded feedback, oldest first (for test assertions). */
+ feedback(): readonly FeedbackInput[] {
+ return [...this.feedbackRecords];
+ }
+
+ /** All registered agent ids, oldest first (for test assertions). */
+ agents(): readonly string[] {
+ return [...this.metadataByAgent.keys()];
+ }
+
+ /** Build a deterministic, counter-based transaction result. */
+ private tx(): TxResult {
+ this.txCounter += 1;
+ const txHash = `0xlocal${this.txCounter.toString(16).padStart(8, "0")}`;
+ return { txHash, explorerUrl: explorerTxUrl(txHash, ARC_TESTNET_EXPLORER) };
+ }
+
+ async register(input: { metadataUri: string }): Promise {
+ this.agentSeq += 1;
+ const agentId = String(this.agentSeq);
+ this.metadataByAgent.set(agentId, input.metadataUri);
+ this.ownerByAgent.set(agentId, this.owner);
+ return this.tx();
+ }
+
+ async findAgentId(input: { owner: string }): Promise {
+ for (const [agentId, owner] of this.ownerByAgent) {
+ if (owner === input.owner) return agentId;
+ }
+ return null;
+ }
+
+ async ownerOf(input: { agentId: string }): Promise {
+ const owner = this.ownerByAgent.get(input.agentId);
+ if (owner === undefined) {
+ throw new Error(`unknown agentId: ${input.agentId}`);
+ }
+ return owner;
+ }
+
+ async tokenUri(input: { agentId: string }): Promise {
+ const uri = this.metadataByAgent.get(input.agentId);
+ if (uri === undefined) {
+ throw new Error(`unknown agentId: ${input.agentId}`);
+ }
+ return uri;
+ }
+
+ async giveFeedback(input: FeedbackInput): Promise {
+ this.feedbackRecords.push({ ...input });
+ return this.tx();
+ }
+
+ async requestValidation(input: ValidationRequestInput): Promise {
+ const requestHash = fnv1aHex(input.subject);
+ const status: ValidationStatus = {
+ validator: input.validator,
+ agentId: input.agentId,
+ response: 0,
+ tag: "",
+ passed: false,
+ };
+ this.validations.set(requestHash, status);
+ return { ...this.tx(), requestHash };
+ }
+
+ async respondValidation(input: ValidationResponseInput): Promise {
+ const existing = this.validations.get(input.requestHash);
+ if (existing === undefined) {
+ throw new Error(`unknown requestHash: ${input.requestHash}`);
+ }
+ const updated: ValidationStatus = {
+ ...existing,
+ response: input.response,
+ tag: input.tag ?? existing.tag,
+ passed: input.response === PASS_THRESHOLD,
+ };
+ this.validations.set(input.requestHash, updated);
+ return this.tx();
+ }
+
+ async getValidationStatus(input: { requestHash: string }): Promise {
+ const status = this.validations.get(input.requestHash);
+ if (status === undefined) {
+ throw new Error(`unknown requestHash: ${input.requestHash}`);
+ }
+ return { ...status };
+ }
+}
diff --git a/packages/erc8004/src/port.ts b/packages/erc8004/src/port.ts
new file mode 100644
index 0000000..b4470b9
--- /dev/null
+++ b/packages/erc8004/src/port.ts
@@ -0,0 +1,56 @@
+/**
+ * The minimal ERC-8004 on-chain surface this package depends on — a *port* the
+ * consumer injects (dependency inversion, mirroring app-kit's `AppKitSdk`).
+ *
+ * This package NEVER imports a chain library. A consumer-owned implementation
+ * (backed by viem, ethers, or Circle Developer-Controlled Wallets) satisfies
+ * this shape and captures its signing adapter by closure; tests and demos use
+ * {@link LocalErc8004Port}. Keeping the contract here means `@settlekit/erc8004`
+ * adds no external chain dependency.
+ *
+ * The port is intentionally NON-generic: {@link ./types.js} models all I/O with
+ * concrete domain types, so there is no signing-adapter type parameter.
+ *
+ * Note: the port owns `requestHash` derivation. `requestValidation` hashes the
+ * stable `subject` string into a bytes32-shaped handle; a real on-chain port
+ * must align that hashing with the ValidationRegistry contract's scheme.
+ */
+
+import type {
+ FeedbackInput,
+ TxResult,
+ ValidationRequestInput,
+ ValidationRequestResult,
+ ValidationResponseInput,
+ ValidationStatus,
+} from "./types.js";
+
+/** The injected ERC-8004 registry operations. */
+export interface Erc8004Port {
+ /** Mint a new agent identity (ERC-721) with the given metadata URI. */
+ register(input: { metadataUri: string }): Promise;
+
+ /** Find the agent id owned by `owner`, or null if none is registered. */
+ findAgentId(input: { owner: string }): Promise;
+
+ /** Resolve the owner wallet of an agent id. */
+ ownerOf(input: { agentId: string }): Promise;
+
+ /** Resolve the metadata token URI of an agent id. */
+ tokenUri(input: { agentId: string }): Promise;
+
+ /** Record reputation feedback about an agent. */
+ giveFeedback(input: FeedbackInput): Promise;
+
+ /**
+ * Submit a validation request. The port computes `requestHash` from
+ * `input.subject` and returns it on the result for later status lookups.
+ */
+ requestValidation(input: ValidationRequestInput): Promise;
+
+ /** Submit a validator's response to a prior request. */
+ respondValidation(input: ValidationResponseInput): Promise;
+
+ /** Read the current status of a validation request by its hash. */
+ getValidationStatus(input: { requestHash: string }): Promise;
+}
diff --git a/packages/erc8004/src/types.ts b/packages/erc8004/src/types.ts
new file mode 100644
index 0000000..61c45c7
--- /dev/null
+++ b/packages/erc8004/src/types.ts
@@ -0,0 +1,76 @@
+/**
+ * ERC-8004 domain types: agent identity, reputation feedback, and the
+ * request/response validation flow. Kept free of any chain library so the
+ * package depends only on `@settlekit/common`; the chain details live behind
+ * the injected {@link Erc8004Port}.
+ */
+
+/** An agent's on-chain identity. */
+export interface AgentIdentity {
+ /** ERC-721 token id minted by the IdentityRegistry. */
+ agentId: string;
+ /** Wallet that owns the identity. */
+ owner: string;
+ /** Metadata URI (e.g. an IPFS document describing the agent). */
+ metadataUri: string;
+}
+
+/** Outcome of a state-changing call. */
+export interface TxResult {
+ txHash: string;
+ explorerUrl?: string;
+}
+
+/** Reputation feedback recorded by a validator (never the agent's owner). */
+export interface FeedbackInput {
+ agentId: string;
+ /** Score (contract type int128); convention is 0–100. */
+ score: number;
+ /** Feedback category (contract type uint8). Default 0. */
+ feedbackType?: number;
+ /** Short machine tag, e.g. "successful_trade". */
+ tag: string;
+ metadataUri?: string;
+ evidenceUri?: string;
+ comment?: string;
+}
+
+/** A request for a validator to attest something about an agent. */
+export interface ValidationRequestInput {
+ agentId: string;
+ /** Validator wallet address that will respond. */
+ validator: string;
+ /** URI describing what is being validated. */
+ requestUri: string;
+ /**
+ * Stable subject string the port hashes into the on-chain request handle.
+ * The same subject reproduces the same handle, so status can be looked up.
+ */
+ subject: string;
+}
+
+/** Handle to a submitted validation request. */
+export interface ValidationRequestResult extends TxResult {
+ /** The on-chain request hash, used to read status later. */
+ requestHash: string;
+}
+
+/** A validator's response to a request. */
+export interface ValidationResponseInput {
+ requestHash: string;
+ /** 0–100; 100 = passed. */
+ response: number;
+ responseUri?: string;
+ tag?: string;
+}
+
+/** Current status of a validation request. */
+export interface ValidationStatus {
+ validator: string;
+ agentId: string;
+ /** 0–100 response; 0 when not yet answered. */
+ response: number;
+ tag: string;
+ /** Convenience: true when {@link ValidationStatus.response} indicates a pass. */
+ passed: boolean;
+}
diff --git a/packages/erc8004/src/validate.ts b/packages/erc8004/src/validate.ts
new file mode 100644
index 0000000..acc6c4c
--- /dev/null
+++ b/packages/erc8004/src/validate.ts
@@ -0,0 +1,69 @@
+/**
+ * Boundary validation for ERC-8004 requests, mirroring app-kit's `validate.ts`.
+ * Each validator returns a `SettleKitError` describing the first problem, or
+ * `null` when the input is well-formed. Client methods short-circuit to
+ * `err(...)` so no malformed request ever reaches the port / chain.
+ */
+
+import { type SettleKitError, validationError } from "@settlekit/common";
+
+/** Validate a non-empty, non-blank string field. */
+export function validateNonEmpty(value: string, field: string): SettleKitError | null {
+ if (typeof value !== "string" || value.trim().length === 0) {
+ return validationError(`${field} is required`, { field });
+ }
+ return null;
+}
+
+/**
+ * Validate an integer within an inclusive range. Relies on
+ * {@link Number.isInteger} so `NaN`/`Infinity`/fractions are rejected (range
+ * comparisons alone would let `NaN` slip through).
+ */
+export function validateIntInRange(
+ value: number,
+ min: number,
+ max: number,
+ field: string,
+): SettleKitError | null {
+ if (typeof value !== "number" || !Number.isInteger(value)) {
+ return validationError(`${field} must be an integer`, { field, value });
+ }
+ if (value < min || value > max) {
+ return validationError(`${field} must be between ${min} and ${max}`, {
+ field,
+ value,
+ min,
+ max,
+ });
+ }
+ return null;
+}
+
+/**
+ * Maximum reputation score this package enforces. The on-chain `score` type is
+ * `int128`, but the documented convention (see {@link ./types.js}) is 0–100.
+ * We require an integer in 0..100 here; consumers needing the wider int128
+ * range can validate it in their own port implementation.
+ */
+const MAX_SCORE = 100;
+
+/** Validate a reputation score: an integer in the inclusive range 0..100. */
+export function validateScore(score: number, field = "score"): SettleKitError | null {
+ return validateIntInRange(score, 0, MAX_SCORE, field);
+}
+
+/** Validate a non-empty wallet address (shape checking is the port's job). */
+export function validateAddress(address: string, field = "address"): SettleKitError | null {
+ return validateNonEmpty(address, field);
+}
+
+/** Return the first non-null error from a list of checks, or null. */
+export function firstError(
+ ...checks: readonly (SettleKitError | null)[]
+): SettleKitError | null {
+ for (const check of checks) {
+ if (check !== null) return check;
+ }
+ return null;
+}
diff --git a/packages/erc8004/test/client.test.ts b/packages/erc8004/test/client.test.ts
new file mode 100644
index 0000000..8de3405
--- /dev/null
+++ b/packages/erc8004/test/client.test.ts
@@ -0,0 +1,298 @@
+import { describe, expect, it } from "vitest";
+import { isErr, isOk } from "@settlekit/common";
+import {
+ AgentRegistryClient,
+ type Erc8004Port,
+ LocalErc8004Port,
+ configureErc8004,
+ fnv1aHex,
+} from "../src/index.js";
+
+const OWNER = "0xowner";
+
+function setup(): { client: AgentRegistryClient; port: LocalErc8004Port } {
+ const port = new LocalErc8004Port({ owner: OWNER });
+ const client = configureErc8004({ port });
+ return { client, port };
+}
+
+describe("registerAgent + resolveAgent", () => {
+ it("registers and resolves an agent identity", async () => {
+ const { client, port } = setup();
+
+ const reg = await client.registerAgent({ metadataUri: "ipfs://a" });
+ expect(isOk(reg)).toBe(true);
+ if (!isOk(reg)) return;
+ expect(reg.value.txHash).toMatch(/^0xlocal/);
+ expect(reg.value.explorerUrl).toContain("arcscan");
+
+ const res = await client.resolveAgent({ owner: OWNER });
+ expect(isOk(res)).toBe(true);
+ if (!isOk(res)) return;
+ expect(res.value).not.toBeNull();
+ expect(res.value?.agentId).toBe("1");
+ expect(res.value?.owner).toBe(OWNER);
+ expect(res.value?.metadataUri).toBe("ipfs://a");
+ expect(port.agents()).toEqual(["1"]);
+ });
+
+ it("increments the agent id on the second register", async () => {
+ const { client } = setup();
+ await client.registerAgent({ metadataUri: "ipfs://a" });
+ const second = await client.registerAgent({ metadataUri: "ipfs://b" });
+ expect(isOk(second)).toBe(true);
+ // The second agent is owned by the same wallet; resolve returns the first,
+ // but the local port records both ids.
+ });
+
+ it("returns ok(null) for an unknown owner", async () => {
+ const { client } = setup();
+ const res = await client.resolveAgent({ owner: "0xnobody" });
+ expect(isOk(res)).toBe(true);
+ if (!isOk(res)) return;
+ expect(res.value).toBeNull();
+ });
+
+ it("rejects an empty metadataUri", async () => {
+ const { client } = setup();
+ const res = await client.registerAgent({ metadataUri: " " });
+ expect(isErr(res)).toBe(true);
+ if (!isErr(res)) return;
+ expect(res.error.code).toBe("validation_error");
+ });
+
+ it("rejects an empty owner on resolve", async () => {
+ const { client } = setup();
+ const res = await client.resolveAgent({ owner: "" });
+ expect(isErr(res)).toBe(true);
+ if (!isErr(res)) return;
+ expect(res.error.code).toBe("validation_error");
+ });
+});
+
+describe("giveFeedback validation", () => {
+ it("records valid feedback", async () => {
+ const { client, port } = setup();
+ const res = await client.giveFeedback({
+ agentId: "1",
+ score: 90,
+ tag: "successful_trade",
+ });
+ expect(isOk(res)).toBe(true);
+ if (!isOk(res)) return;
+ expect(res.value.txHash).toMatch(/^0xlocal/);
+ expect(port.feedback()).toHaveLength(1);
+ expect(port.feedback()[0]?.feedbackType).toBe(0);
+ });
+
+ it("rejects a non-integer score", async () => {
+ const { client } = setup();
+ const res = await client.giveFeedback({ agentId: "1", score: 90.5, tag: "t" });
+ expect(isErr(res)).toBe(true);
+ if (!isErr(res)) return;
+ expect(res.error.code).toBe("validation_error");
+ });
+
+ it("rejects a negative score", async () => {
+ const { client } = setup();
+ const res = await client.giveFeedback({ agentId: "1", score: -1, tag: "t" });
+ expect(isErr(res)).toBe(true);
+ if (!isErr(res)) return;
+ expect(res.error.code).toBe("validation_error");
+ });
+
+ it("rejects a feedbackType above 255", async () => {
+ const { client } = setup();
+ const res = await client.giveFeedback({
+ agentId: "1",
+ score: 50,
+ feedbackType: 256,
+ tag: "t",
+ });
+ expect(isErr(res)).toBe(true);
+ if (!isErr(res)) return;
+ expect(res.error.code).toBe("validation_error");
+ });
+
+ it("accepts feedbackType 0 as the default", async () => {
+ const { client } = setup();
+ const res = await client.giveFeedback({
+ agentId: "1",
+ score: 50,
+ feedbackType: 0,
+ tag: "t",
+ });
+ expect(isOk(res)).toBe(true);
+ });
+
+ it("rejects an empty tag", async () => {
+ const { client } = setup();
+ const res = await client.giveFeedback({ agentId: "1", score: 50, tag: "" });
+ expect(isErr(res)).toBe(true);
+ });
+
+ it("rejects an empty agentId", async () => {
+ const { client } = setup();
+ const res = await client.giveFeedback({ agentId: "", score: 50, tag: "t" });
+ expect(isErr(res)).toBe(true);
+ });
+});
+
+describe("validation request/respond/status round-trip", () => {
+ it("requests, responds, and reads status", async () => {
+ const { client } = setup();
+ await client.registerAgent({ metadataUri: "ipfs://a" });
+
+ const req = await client.requestValidation({
+ agentId: "1",
+ validator: "0xval",
+ requestUri: "ipfs://r",
+ subject: "job-42",
+ });
+ expect(isOk(req)).toBe(true);
+ if (!isOk(req)) return;
+ expect(req.value.requestHash.startsWith("0x")).toBe(true);
+ expect(req.value.requestHash).toHaveLength(66);
+
+ const requestHash = req.value.requestHash;
+
+ const respond = await client.respondValidation({ requestHash, response: 100, tag: "ok" });
+ expect(isOk(respond)).toBe(true);
+
+ const status = await client.getValidationStatus({ requestHash });
+ expect(isOk(status)).toBe(true);
+ if (!isOk(status)) return;
+ expect(status.value.response).toBe(100);
+ expect(status.value.passed).toBe(true);
+ expect(status.value.validator).toBe("0xval");
+ expect(status.value.agentId).toBe("1");
+ expect(status.value.tag).toBe("ok");
+ });
+
+ it("derives a stable requestHash for the same subject", async () => {
+ const { client } = setup();
+ const a = await client.requestValidation({
+ agentId: "1",
+ validator: "0xval",
+ requestUri: "ipfs://r",
+ subject: "job-42",
+ });
+ const b = await client.requestValidation({
+ agentId: "1",
+ validator: "0xval",
+ requestUri: "ipfs://r",
+ subject: "job-42",
+ });
+ const c = await client.requestValidation({
+ agentId: "1",
+ validator: "0xval",
+ requestUri: "ipfs://r",
+ subject: "different",
+ });
+ expect(isOk(a) && isOk(b) && isOk(c)).toBe(true);
+ if (!isOk(a) || !isOk(b) || !isOk(c)) return;
+ expect(a.value.requestHash).toBe(b.value.requestHash);
+ expect(a.value.requestHash).not.toBe(c.value.requestHash);
+ expect(a.value.requestHash).toBe(fnv1aHex("job-42"));
+ });
+
+ it("marks passed=false for a response below 100", async () => {
+ const { client } = setup();
+ const req = await client.requestValidation({
+ agentId: "1",
+ validator: "0xval",
+ requestUri: "ipfs://r",
+ subject: "partial",
+ });
+ if (!isOk(req)) return;
+ await client.respondValidation({ requestHash: req.value.requestHash, response: 50 });
+ const status = await client.getValidationStatus({ requestHash: req.value.requestHash });
+ if (!isOk(status)) return;
+ expect(status.value.passed).toBe(false);
+ expect(status.value.response).toBe(50);
+ });
+
+ it("rejects a response above 100", async () => {
+ const { client } = setup();
+ const res = await client.respondValidation({ requestHash: "0xdead", response: 101 });
+ expect(isErr(res)).toBe(true);
+ if (!isErr(res)) return;
+ expect(res.error.code).toBe("validation_error");
+ });
+
+ it("rejects a non-integer response", async () => {
+ const { client } = setup();
+ const res = await client.respondValidation({ requestHash: "0xdead", response: 50.5 });
+ expect(isErr(res)).toBe(true);
+ if (!isErr(res)) return;
+ expect(res.error.code).toBe("validation_error");
+ });
+
+ it("rejects an empty requestHash on respond", async () => {
+ const { client } = setup();
+ const res = await client.respondValidation({ requestHash: "", response: 100 });
+ expect(isErr(res)).toBe(true);
+ if (!isErr(res)) return;
+ expect(res.error.code).toBe("validation_error");
+ });
+
+ it("rejects an empty requestHash on getValidationStatus", async () => {
+ const { client } = setup();
+ const res = await client.getValidationStatus({ requestHash: "" });
+ expect(isErr(res)).toBe(true);
+ if (!isErr(res)) return;
+ expect(res.error.code).toBe("validation_error");
+ });
+
+ it("rejects an empty validator on request", async () => {
+ const { client } = setup();
+ const res = await client.requestValidation({
+ agentId: "1",
+ validator: "",
+ requestUri: "ipfs://r",
+ subject: "s",
+ });
+ expect(isErr(res)).toBe(true);
+ if (!isErr(res)) return;
+ expect(res.error.code).toBe("validation_error");
+ });
+});
+
+describe("error mapping", () => {
+ it("maps a missing-agent ownerOf throw to a retryable integration_error", async () => {
+ // A port that has no registered agents: resolve finds an id but ownerOf
+ // throws. Use an inline port to force the findAgentId/ownerOf mismatch.
+ const throwingPort: Erc8004Port = {
+ register: async () => ({ txHash: "0x" }),
+ findAgentId: async () => "99",
+ ownerOf: async () => {
+ throw new Error("boom: unknown agentId");
+ },
+ tokenUri: async () => "ipfs://x",
+ giveFeedback: async () => ({ txHash: "0x" }),
+ requestValidation: async () => ({ txHash: "0x", requestHash: "0x0" }),
+ respondValidation: async () => ({ txHash: "0x" }),
+ getValidationStatus: async () => {
+ throw new Error("missing");
+ },
+ };
+ const client = new AgentRegistryClient({ port: throwingPort });
+
+ const res = await client.resolveAgent({ owner: OWNER });
+ expect(isErr(res)).toBe(true);
+ if (!isErr(res)) return;
+ expect(res.error.code).toBe("integration_error");
+ expect(res.error.retryable).toBe(true);
+ expect(res.error.message).toContain("resolveAgent");
+ });
+
+ it("maps a getValidationStatus throw to a retryable integration_error", async () => {
+ const { client } = setup();
+ const res = await client.getValidationStatus({ requestHash: "0xnotfound" });
+ expect(isErr(res)).toBe(true);
+ if (!isErr(res)) return;
+ expect(res.error.code).toBe("integration_error");
+ expect(res.error.retryable).toBe(true);
+ expect(res.error.message).toContain("getValidationStatus");
+ });
+});
diff --git a/packages/erc8004/tsconfig.json b/packages/erc8004/tsconfig.json
new file mode 100644
index 0000000..f22baf2
--- /dev/null
+++ b/packages/erc8004/tsconfig.json
@@ -0,0 +1,11 @@
+{
+ "extends": "../../tsconfig.base.json",
+ "compilerOptions": {
+ "rootDir": "./src",
+ "outDir": "./dist",
+ "composite": true
+ },
+ "references": [{ "path": "../common" }],
+ "include": ["src/**/*"],
+ "exclude": ["dist", "node_modules", "**/*.test.ts"]
+}
diff --git a/packages/erc8183/README.md b/packages/erc8183/README.md
new file mode 100644
index 0000000..de3b449
--- /dev/null
+++ b/packages/erc8183/README.md
@@ -0,0 +1,181 @@
+# @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`](../common/src/money.ts)), 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
+
+```ts
+interface Erc8183Port {
+ createJob(p: { requester; worker; amountUsdc; specUri }): Promise<{ jobId; txHash }>;
+ fundEscrow(p: { jobId; amountUsdc }): Promise;
+ submitDeliverable(p: { jobId; deliverableUri }): Promise;
+ evaluate(p: { jobId; passed; scoreOrUri? }): Promise;
+ settle(p: { jobId }): Promise;
+ refund(p: { jobId }): Promise;
+ getJob(p: { jobId }): Promise;
+}
+```
+
+## Usage
+
+```ts
+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`. 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`:
+
+```ts
+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:
+
+```ts
+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 {
+ 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 {
+ 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.
diff --git a/packages/erc8183/package.json b/packages/erc8183/package.json
new file mode 100644
index 0000000..d29a4df
--- /dev/null
+++ b/packages/erc8183/package.json
@@ -0,0 +1,26 @@
+{
+ "name": "@settlekit/erc8183",
+ "version": "0.0.0",
+ "type": "module",
+ "main": "./dist/index.js",
+ "types": "./dist/index.d.ts",
+ "exports": {
+ ".": {
+ "types": "./dist/index.d.ts",
+ "default": "./dist/index.js"
+ }
+ },
+ "files": ["dist"],
+ "scripts": {
+ "build": "tsc -b",
+ "test": "vitest run"
+ },
+ "dependencies": {
+ "@settlekit/common": "workspace:*"
+ },
+ "devDependencies": {
+ "@types/node": "^20.14.0",
+ "typescript": "^5.5.4",
+ "vitest": "^2.0.5"
+ }
+}
diff --git a/packages/erc8183/src/client.ts b/packages/erc8183/src/client.ts
new file mode 100644
index 0000000..73a8ff0
--- /dev/null
+++ b/packages/erc8183/src/client.ts
@@ -0,0 +1,180 @@
+/**
+ * {@link JobClient} — the SettleKit-idiomatic facade over an injected
+ * {@link Erc8183Port}. Every method validates its request, calls the port, and
+ * returns a `Result` instead of throwing, so callers handle success/failure
+ * uniformly. Thrown port errors are mapped to a retryable `integration_error`;
+ * when the thrown cause is already a {@link SettleKitError} (e.g. a `conflict`
+ * from an illegal on-chain transition or a `not_found`), its code is preserved
+ * rather than masked.
+ */
+
+import { type Result, SettleKitError, conflict, err, money, ok } from "@settlekit/common";
+import type { Erc8183Port } from "./port.js";
+import type {
+ CreateJobRequest,
+ CreateJobResult,
+ EvaluateRequest,
+ FundEscrowRequest,
+ Job,
+ JobIdRequest,
+ SubmitDeliverableRequest,
+ TxResult,
+} from "./types.js";
+import { firstError, validateAddress, validateAmount, validateNonEmpty } from "./validate.js";
+
+/** Configuration for a {@link JobClient}. */
+export interface JobClientConfig {
+ /** The injected ERC-8183 port (viem + DCW implementation, or a local mock). */
+ port: Erc8183Port;
+}
+
+export class JobClient {
+ private readonly port: Erc8183Port;
+
+ constructor(config: JobClientConfig) {
+ this.port = config.port;
+ }
+
+ /**
+ * Wrap a port call, mapping thrown errors to a typed error. A thrown
+ * {@link SettleKitError} (conflict/not_found/...) passes through with its code
+ * intact; any other throw becomes a retryable `integration_error`.
+ */
+ private async run(label: string, call: () => Promise): Promise> {
+ try {
+ return ok(await call());
+ } catch (cause) {
+ if (SettleKitError.is(cause)) {
+ return err(cause);
+ }
+ return err(
+ new SettleKitError({
+ code: "integration_error",
+ message: `erc8183 ${label} failed: ${cause instanceof Error ? cause.message : String(cause)}`,
+ retryable: true,
+ cause,
+ details: { op: label },
+ }),
+ );
+ }
+ }
+
+ /** Create a job and post its spec, escrowing `amountUsdc` of USDC. */
+ async createJob(req: CreateJobRequest): Promise> {
+ const invalid = firstError(
+ validateAddress(req.requester, "requester"),
+ validateAddress(req.worker, "worker"),
+ validateNonEmpty(req.specUri, "specUri"),
+ validateAmount(req.amountUsdc),
+ );
+ if (invalid !== null) return err(invalid);
+
+ // Assert the amount is a canonical USDC value before touching the chain.
+ const amount = money(req.amountUsdc);
+
+ return this.run("createJob", () =>
+ this.port.createJob({
+ requester: req.requester,
+ worker: req.worker,
+ amountUsdc: amount.amount,
+ specUri: req.specUri,
+ }),
+ );
+ }
+
+ /** Fund the USDC escrow for an existing job. */
+ async fundEscrow(req: FundEscrowRequest): Promise> {
+ const invalid = firstError(
+ validateNonEmpty(req.jobId, "jobId"),
+ validateAmount(req.amountUsdc),
+ );
+ if (invalid !== null) return err(invalid);
+
+ const amount = money(req.amountUsdc);
+
+ return this.run("fundEscrow", () =>
+ this.port.fundEscrow({ jobId: req.jobId, amountUsdc: amount.amount }),
+ );
+ }
+
+ /** Submit a deliverable for a funded job. */
+ async submitDeliverable(req: SubmitDeliverableRequest): Promise> {
+ const invalid = firstError(
+ validateNonEmpty(req.jobId, "jobId"),
+ validateNonEmpty(req.deliverableUri, "deliverableUri"),
+ );
+ if (invalid !== null) return err(invalid);
+
+ return this.run("submitDeliverable", () =>
+ this.port.submitDeliverable({
+ jobId: req.jobId,
+ deliverableUri: req.deliverableUri,
+ }),
+ );
+ }
+
+ /** Record an evaluation verdict for a submitted job. */
+ async evaluate(req: EvaluateRequest): Promise> {
+ const invalid = firstError(
+ validateNonEmpty(req.jobId, "jobId"),
+ req.scoreOrUri !== undefined ? validateNonEmpty(req.scoreOrUri, "scoreOrUri") : null,
+ );
+ if (invalid !== null) return err(invalid);
+
+ return this.run("evaluate", () =>
+ this.port.evaluate({
+ jobId: req.jobId,
+ passed: req.passed,
+ ...(req.scoreOrUri !== undefined ? { scoreOrUri: req.scoreOrUri } : {}),
+ }),
+ );
+ }
+
+ /**
+ * Settle the escrow to the worker. Performs an optional fast-fail pre-check via
+ * {@link Erc8183Port.getJob} — rejecting with `conflict` when the job is not in
+ * `evaluated` status or did not pass — but the on-chain guard (port) remains
+ * authoritative.
+ */
+ async settle(req: JobIdRequest): Promise> {
+ const invalid = validateNonEmpty(req.jobId, "jobId");
+ if (invalid !== null) return err(invalid);
+
+ const precheck = await this.run("getJob", () => this.port.getJob({ jobId: req.jobId }));
+ if (!precheck.ok) return precheck;
+ const job = precheck.value;
+ if (job.status !== "evaluated") {
+ return err(
+ conflict(`cannot settle a job in status "${job.status}"`, {
+ jobId: req.jobId,
+ status: job.status,
+ }),
+ );
+ }
+ if (job.evaluation?.passed !== true) {
+ return err(
+ conflict("cannot settle a failed evaluation", {
+ jobId: req.jobId,
+ }),
+ );
+ }
+
+ return this.run("settle", () => this.port.settle({ jobId: req.jobId }));
+ }
+
+ /** Refund the escrow to the requester. */
+ async refund(req: JobIdRequest): Promise> {
+ const invalid = validateNonEmpty(req.jobId, "jobId");
+ if (invalid !== null) return err(invalid);
+
+ return this.run("refund", () => this.port.refund({ jobId: req.jobId }));
+ }
+
+ /** Read the current state of a job. */
+ async getJob(req: JobIdRequest): Promise> {
+ const invalid = validateNonEmpty(req.jobId, "jobId");
+ if (invalid !== null) return err(invalid);
+
+ return this.run("getJob", () => this.port.getJob({ jobId: req.jobId }));
+ }
+}
diff --git a/packages/erc8183/src/configure.ts b/packages/erc8183/src/configure.ts
new file mode 100644
index 0000000..006b9bc
--- /dev/null
+++ b/packages/erc8183/src/configure.ts
@@ -0,0 +1,39 @@
+/**
+ * One factory to build a {@link JobClient}. The consumer injects a configured
+ * {@link Erc8183Port} — there is no kit key or secret to read here, but the
+ * factory shape mirrors {@link import("@settlekit/app-kit").configureAppKit} for
+ * parity across SettleKit packages.
+ *
+ * Live wiring (in the consumer, which owns the viem + Circle DCW dependencies):
+ *
+ * ```ts
+ * import { createWalletClient, http } from "viem";
+ * import { configureErc8183, type Erc8183Port } from "@settlekit/erc8183";
+ *
+ * // Build a viem walletClient backed by a Circle Developer-Controlled Wallets
+ * // signer, then implement the port against the ERC-8183 job contract:
+ * const port: Erc8183Port = {
+ * async createJob({ requester, worker, amountUsdc, specUri }) { ... },
+ * async fundEscrow({ jobId, amountUsdc }) { ... },
+ * // submitDeliverable / evaluate / settle / refund / getJob
+ * };
+ *
+ * const jobs = configureErc8183({ port });
+ * const created = await jobs.createJob({ requester, worker, amountUsdc: "100.00", specUri });
+ * ```
+ *
+ * Tests/demos inject {@link import("./local-port.js").LocalErc8183Port} instead.
+ */
+
+import { JobClient, type JobClientConfig } from "./client.js";
+
+/** Options for {@link configureErc8183}. */
+export interface ConfigureErc8183Options {
+ /** The injected ERC-8183 port. */
+ port: JobClientConfig["port"];
+}
+
+/** Build a configured {@link JobClient}. */
+export function configureErc8183(options: ConfigureErc8183Options): JobClient {
+ return new JobClient({ port: options.port });
+}
diff --git a/packages/erc8183/src/index.ts b/packages/erc8183/src/index.ts
new file mode 100644
index 0000000..d91177e
--- /dev/null
+++ b/packages/erc8183/src/index.ts
@@ -0,0 +1,6 @@
+export * from "./types.js";
+export * from "./port.js";
+export * from "./validate.js";
+export * from "./client.js";
+export * from "./local-port.js";
+export * from "./configure.js";
diff --git a/packages/erc8183/src/local-port.ts b/packages/erc8183/src/local-port.ts
new file mode 100644
index 0000000..d14432e
--- /dev/null
+++ b/packages/erc8183/src/local-port.ts
@@ -0,0 +1,145 @@
+/**
+ * {@link LocalErc8183Port} — a deterministic, in-memory {@link Erc8183Port} for
+ * tests, demos, and local development. It never touches a chain: it holds jobs
+ * in a `Map`, enforces the job state machine ({@link assertTransition}), mints
+ * sequential job ids (`job_1`, `job_2`, ...), and returns synthetic,
+ * monotonically-numbered transaction hashes so assertions are stable across
+ * runs. No `Math.random` / `Date.now` is used.
+ *
+ * Every state change creates a NEW {@link Job} object (immutability); stored
+ * jobs are never mutated in place.
+ */
+
+import { conflict, money, notFound } from "@settlekit/common";
+import type { Erc8183Port } from "./port.js";
+import { type Job, type JobEvaluation, type TxResult, assertTransition } from "./types.js";
+
+/** Operations that may be forced to throw, to exercise client error mapping. */
+export type LocalErc8183Op =
+ | "createJob"
+ | "fundEscrow"
+ | "submitDeliverable"
+ | "evaluate"
+ | "settle"
+ | "refund"
+ | "getJob";
+
+/** Options controlling the local port's simulated behavior. */
+export interface LocalErc8183Options {
+ /** Operations named here throw a generic Error, to exercise error mapping. */
+ throwOn?: readonly LocalErc8183Op[];
+}
+
+const SUCCESS: TxResult["status"] = "success";
+
+export class LocalErc8183Port implements Erc8183Port {
+ private readonly jobsById = new Map();
+ private readonly throwOn: ReadonlySet;
+ private jobCounter = 0;
+ private txCounter = 0;
+
+ constructor(options: LocalErc8183Options = {}) {
+ this.throwOn = new Set(options.throwOn ?? []);
+ }
+
+ /** A snapshot array of every stored job, for test assertions. */
+ jobs(): readonly Job[] {
+ return [...this.jobsById.values()];
+ }
+
+ /** Mint the next synthetic transaction hash. */
+ private nextTx(): string {
+ this.txCounter += 1;
+ return `0xlocal${this.txCounter.toString(16).padStart(8, "0")}`;
+ }
+
+ /** Throw the simulated failure for `op` when configured. */
+ private guard(op: LocalErc8183Op): void {
+ if (this.throwOn.has(op)) {
+ throw new Error(`simulated ${op} failure`);
+ }
+ }
+
+ /** Load a job or throw `not_found`. */
+ private require(jobId: string): Job {
+ const job = this.jobsById.get(jobId);
+ if (job === undefined) {
+ throw notFound(`job "${jobId}" was not found`, { jobId });
+ }
+ return job;
+ }
+
+ async createJob(p: {
+ requester: string;
+ worker: string;
+ amountUsdc: string;
+ specUri: string;
+ }): Promise<{ jobId: string; txHash: string }> {
+ this.guard("createJob");
+ this.jobCounter += 1;
+ const jobId = `job_${this.jobCounter}`;
+ const job: Job = {
+ id: jobId,
+ requester: p.requester,
+ worker: p.worker,
+ amount: money(p.amountUsdc),
+ status: "created",
+ };
+ this.jobsById.set(jobId, job);
+ return { jobId, txHash: this.nextTx() };
+ }
+
+ async fundEscrow(p: { jobId: string; amountUsdc: string }): Promise {
+ this.guard("fundEscrow");
+ const job = this.require(p.jobId);
+ const status = assertTransition(job.status, "fund");
+ this.jobsById.set(job.id, { ...job, status });
+ return { txHash: this.nextTx(), status: SUCCESS };
+ }
+
+ async submitDeliverable(p: { jobId: string; deliverableUri: string }): Promise {
+ this.guard("submitDeliverable");
+ const job = this.require(p.jobId);
+ const status = assertTransition(job.status, "submit");
+ this.jobsById.set(job.id, { ...job, status, deliverableUri: p.deliverableUri });
+ return { txHash: this.nextTx(), status: SUCCESS };
+ }
+
+ async evaluate(p: { jobId: string; passed: boolean; scoreOrUri?: string }): Promise {
+ this.guard("evaluate");
+ const job = this.require(p.jobId);
+ const status = assertTransition(job.status, p.passed ? "evaluate_pass" : "evaluate_fail");
+ const evaluation: JobEvaluation = {
+ passed: p.passed,
+ ...(p.scoreOrUri !== undefined ? { scoreOrUri: p.scoreOrUri } : {}),
+ };
+ this.jobsById.set(job.id, { ...job, status, evaluation });
+ return { txHash: this.nextTx(), status: SUCCESS };
+ }
+
+ async settle(p: { jobId: string }): Promise {
+ this.guard("settle");
+ const job = this.require(p.jobId);
+ const status = assertTransition(job.status, "settle");
+ // The transition table allows settle from `evaluated` regardless of verdict;
+ // the lifecycle additionally forbids settling a failed evaluation.
+ if (job.evaluation?.passed !== true) {
+ throw conflict("cannot settle a failed evaluation", { jobId: p.jobId });
+ }
+ this.jobsById.set(job.id, { ...job, status });
+ return { txHash: this.nextTx(), status: SUCCESS };
+ }
+
+ async refund(p: { jobId: string }): Promise {
+ this.guard("refund");
+ const job = this.require(p.jobId);
+ const status = assertTransition(job.status, "refund");
+ this.jobsById.set(job.id, { ...job, status });
+ return { txHash: this.nextTx(), status: SUCCESS };
+ }
+
+ async getJob(p: { jobId: string }): Promise {
+ this.guard("getJob");
+ return this.require(p.jobId);
+ }
+}
diff --git a/packages/erc8183/src/port.ts b/packages/erc8183/src/port.ts
new file mode 100644
index 0000000..6db399c
--- /dev/null
+++ b/packages/erc8183/src/port.ts
@@ -0,0 +1,42 @@
+/**
+ * {@link Erc8183Port} — the minimal on-chain surface this package depends on, a
+ * *port* the consumer injects (dependency inversion, like settlement-core's
+ * providers). A real viem + Circle Developer-Controlled Wallets implementation
+ * against the ERC-8183 job contract satisfies this shape; tests and demos use
+ * {@link LocalErc8183Port}.
+ *
+ * Keeping the contract here means this package never imports a chain SDK and so
+ * adds no external dependency — the consumer owns viem/DCW and supplies the
+ * implementation.
+ */
+
+import type { Job, TxResult } from "./types.js";
+
+/** The injected ERC-8183 on-chain job contract. */
+export interface Erc8183Port {
+ /** Create a new job on-chain and post its spec. */
+ createJob(p: {
+ requester: string;
+ worker: string;
+ amountUsdc: string;
+ specUri: string;
+ }): Promise<{ jobId: string; txHash: string }>;
+
+ /** Fund the USDC escrow for an existing job. */
+ fundEscrow(p: { jobId: string; amountUsdc: string }): Promise;
+
+ /** Submit a deliverable for a funded job. */
+ submitDeliverable(p: { jobId: string; deliverableUri: string }): Promise;
+
+ /** Record an evaluation verdict for a submitted job. */
+ evaluate(p: { jobId: string; passed: boolean; scoreOrUri?: string }): Promise;
+
+ /** Settle the escrow to the worker (legal only after a passing evaluation). */
+ settle(p: { jobId: string }): Promise;
+
+ /** Refund the escrow to the requester. */
+ refund(p: { jobId: string }): Promise;
+
+ /** Read the current on-chain state of a job. */
+ getJob(p: { jobId: string }): Promise;
+}
diff --git a/packages/erc8183/src/types.ts b/packages/erc8183/src/types.ts
new file mode 100644
index 0000000..dc03a41
--- /dev/null
+++ b/packages/erc8183/src/types.ts
@@ -0,0 +1,204 @@
+/**
+ * SettleKit-facing types for the ERC-8183 autonomous-agent job lifecycle on Arc.
+ *
+ * ERC-8183 models a unit of agent work as an on-chain *job*: a requester posts a
+ * spec and funds a USDC escrow, a worker submits a deliverable, an evaluator
+ * scores it, and the escrow either settles to the worker or refunds the
+ * requester. This package wraps that lifecycle in SettleKit idioms —
+ * decimal-USDC amounts ({@link Money}), schema-validated requests, a `Result`
+ * surface that never throws across the boundary, and an explicit state machine.
+ *
+ * The on-chain operations are injected through an {@link Erc8183Port} (dependency
+ * inversion) so this package never imports a chain SDK and adds no external
+ * dependency — the consumer supplies a viem + Circle DCW backed implementation,
+ * and tests/demos use the deterministic local port.
+ */
+
+import { type Money, conflict } from "@settlekit/common";
+
+/** Lifecycle state of a job. */
+export type JobStatus =
+ | "created"
+ | "funded"
+ | "submitted"
+ | "evaluated"
+ | "settled"
+ | "refunded"
+ | "cancelled";
+
+/** A move between job statuses. */
+export type JobTransition =
+ | "fund"
+ | "submit"
+ | "evaluate_pass"
+ | "evaluate_fail"
+ | "settle"
+ | "refund"
+ | "cancel";
+
+/** The evaluator's verdict on a submitted deliverable. */
+export interface JobEvaluation {
+ /** Whether the deliverable passed evaluation. */
+ passed: boolean;
+ /** An optional numeric score string or a URI to a detailed rubric. */
+ scoreOrUri?: string;
+}
+
+/** A job in the ERC-8183 lifecycle. */
+export interface Job {
+ /** On-chain job identifier (port-minted). */
+ id: string;
+ /** Address of the party requesting and funding the work. */
+ requester: string;
+ /** Address of the agent performing the work. */
+ worker: string;
+ /** Escrowed USDC amount. */
+ amount: Money;
+ /** Current lifecycle status. */
+ status: JobStatus;
+ /** URI of the submitted deliverable, once present. */
+ deliverableUri?: string;
+ /** Evaluation verdict, once present. */
+ evaluation?: JobEvaluation;
+}
+
+/**
+ * The legal transition table for the job lifecycle.
+ *
+ * Read as: from `source` status, applying `transition` yields the target
+ * status. Any (source, transition) pair not present here is illegal and is
+ * rejected by {@link assertTransition} with a `conflict` (HTTP 409) error.
+ *
+ * Lifecycle (happy path):
+ * created -> funded -> submitted -> evaluated -> settled
+ *
+ * Branches:
+ * - a created or funded job may be cancelled before work begins.
+ * - a refund is permitted from funded/submitted/evaluated (escrow returns to
+ * the requester).
+ * - 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
+ * (see LocalErc8183Port.settle), not expressible by this table alone.
+ *
+ * Terminal states (settled, refunded, cancelled) have no outgoing transitions.
+ */
+export const JOB_TRANSITIONS: Readonly<
+ Record>>>
+> = {
+ created: {
+ fund: "funded",
+ cancel: "cancelled",
+ },
+ funded: {
+ submit: "submitted",
+ refund: "refunded",
+ cancel: "cancelled",
+ },
+ submitted: {
+ evaluate_pass: "evaluated",
+ evaluate_fail: "evaluated",
+ refund: "refunded",
+ },
+ evaluated: {
+ settle: "settled",
+ refund: "refunded",
+ },
+ settled: {},
+ refunded: {},
+ cancelled: {},
+};
+
+/** Return the target status for a transition, or `undefined` if illegal. */
+export function peekTransition(
+ status: JobStatus,
+ transition: JobTransition,
+): JobStatus | undefined {
+ return JOB_TRANSITIONS[status][transition];
+}
+
+/** Whether `transition` is legal from the given `status`. */
+export function canTransition(status: JobStatus, transition: JobTransition): boolean {
+ return peekTransition(status, transition) !== undefined;
+}
+
+/**
+ * Guard the job state machine: resolve the target status for a transition or
+ * throw a `conflict` {@link import("@settlekit/common").SettleKitError} (HTTP
+ * 409) describing the illegal move. This is the single enforcement point every
+ * transition funnels through.
+ */
+export function assertTransition(status: JobStatus, transition: JobTransition): JobStatus {
+ const next = peekTransition(status, transition);
+ if (next === undefined) {
+ throw conflict(`Illegal job transition "${transition}" from status "${status}".`, {
+ from: status,
+ transition,
+ });
+ }
+ return next;
+}
+
+/** Whether a status is terminal (no further transitions are possible). */
+export function isTerminalJobStatus(status: JobStatus): boolean {
+ return Object.keys(JOB_TRANSITIONS[status]).length === 0;
+}
+
+/* -------------------------------------------------------------------------- */
+/* Request / result shapes */
+/* -------------------------------------------------------------------------- */
+
+/** Create a new job and post its spec. */
+export interface CreateJobRequest {
+ /** Address of the requester funding the work. */
+ requester: string;
+ /** Address of the worker that will perform the job. */
+ worker: string;
+ /** Decimal USDC amount to escrow, e.g. "100.00". */
+ amountUsdc: string;
+ /** URI of the job specification (e.g. ipfs://...). */
+ specUri: string;
+}
+
+/** Fund the USDC escrow for an existing job. */
+export interface FundEscrowRequest {
+ jobId: string;
+ /** Decimal USDC amount to fund. */
+ amountUsdc: string;
+}
+
+/** Submit a deliverable for a funded job. */
+export interface SubmitDeliverableRequest {
+ jobId: string;
+ /** URI of the submitted deliverable. */
+ deliverableUri: string;
+}
+
+/** Record an evaluation verdict for a submitted job. */
+export interface EvaluateRequest {
+ jobId: string;
+ /** Whether the deliverable passed. */
+ passed: boolean;
+ /** Optional numeric score string or a URI to a detailed rubric. */
+ scoreOrUri?: string;
+}
+
+/** Address a single job by its id (settle/refund/getJob). */
+export interface JobIdRequest {
+ jobId: string;
+}
+
+/** Result of creating a job. */
+export interface CreateJobResult {
+ /** On-chain job identifier. */
+ jobId: string;
+ /** On-chain transaction hash. */
+ txHash: string;
+}
+
+/** Normalized result of an on-chain job operation. */
+export interface TxResult {
+ /** On-chain transaction hash. */
+ txHash: string;
+ /** Status of the transaction. */
+ status: "success" | "pending" | "failed";
+}
diff --git a/packages/erc8183/src/validate.ts b/packages/erc8183/src/validate.ts
new file mode 100644
index 0000000..7656ac8
--- /dev/null
+++ b/packages/erc8183/src/validate.ts
@@ -0,0 +1,48 @@
+/**
+ * Boundary validation for ERC-8183 job requests. Each validator returns a
+ * `SettleKitError` describing the first problem, or `null` when the input is
+ * well-formed. Client methods short-circuit to `err(...)` so no malformed
+ * request ever reaches the port / chain.
+ */
+
+import { type SettleKitError, validationError } from "@settlekit/common";
+
+/** Decimal amount with up to 6 fractional digits (USDC precision). */
+const AMOUNT_RE = /^\d+(\.\d{1,6})?$/;
+
+/** Validate a positive decimal amount string. */
+export function validateAmount(amount: string, field = "amountUsdc"): SettleKitError | null {
+ if (typeof amount !== "string" || amount.length === 0) {
+ return validationError(`${field} is required`, { field });
+ }
+ if (!AMOUNT_RE.test(amount)) {
+ return validationError(`${field} must be a decimal with up to 6 places`, { field, amount });
+ }
+ if (Number(amount) <= 0) {
+ return validationError(`${field} must be greater than zero`, { field, amount });
+ }
+ return null;
+}
+
+/** Validate a non-empty trimmed string (addresses, URIs, ids). */
+export function validateNonEmpty(value: string, field: string): SettleKitError | null {
+ if (typeof value !== "string" || value.trim().length === 0) {
+ return validationError(`${field} is required`, { field });
+ }
+ return null;
+}
+
+/** Validate a non-empty wallet address (alias of {@link validateNonEmpty}). */
+export function validateAddress(address: string, field = "address"): SettleKitError | null {
+ return validateNonEmpty(address, field);
+}
+
+/** Return the first non-null error from a list of checks, or null. */
+export function firstError(
+ ...checks: readonly (SettleKitError | null)[]
+): SettleKitError | null {
+ for (const check of checks) {
+ if (check !== null) return check;
+ }
+ return null;
+}
diff --git a/packages/erc8183/test/client.test.ts b/packages/erc8183/test/client.test.ts
new file mode 100644
index 0000000..6e73786
--- /dev/null
+++ b/packages/erc8183/test/client.test.ts
@@ -0,0 +1,240 @@
+import { describe, expect, it } from "vitest";
+import { isErr, isOk } from "@settlekit/common";
+import {
+ JobClient,
+ LocalErc8183Port,
+ type LocalErc8183Op,
+ configureErc8183,
+} from "../src/index.js";
+
+function setup(opts: { throwOn?: readonly LocalErc8183Op[] } = {}): {
+ client: JobClient;
+ port: LocalErc8183Port;
+} {
+ const port = new LocalErc8183Port(opts.throwOn !== undefined ? { throwOn: opts.throwOn } : {});
+ const client = configureErc8183({ port });
+ return { client, port };
+}
+
+const VALID = {
+ requester: "0xreq",
+ worker: "0xwork",
+ amountUsdc: "100.00",
+ specUri: "ipfs://spec",
+};
+
+async function createOk(client: JobClient): Promise {
+ const res = await client.createJob(VALID);
+ if (!isOk(res)) throw new Error("expected createJob ok");
+ return res.value.jobId;
+}
+
+describe("happy path", () => {
+ it("create -> fund -> submit -> evaluate(pass) -> settle", async () => {
+ const { client } = setup();
+
+ const created = await client.createJob(VALID);
+ expect(isOk(created)).toBe(true);
+ if (!isOk(created)) return;
+ expect(created.value.jobId).toBe("job_1");
+ expect(created.value.txHash).toMatch(/^0xlocal/);
+
+ const afterCreate = await client.getJob({ jobId: "job_1" });
+ expect(isOk(afterCreate)).toBe(true);
+ if (!isOk(afterCreate)) return;
+ expect(afterCreate.value.status).toBe("created");
+ expect(afterCreate.value.amount.amount).toBe("100");
+ expect(afterCreate.value.amount.currency).toBe("USDC");
+
+ const funded = await client.fundEscrow({ jobId: "job_1", amountUsdc: "100.00" });
+ expect(isOk(funded)).toBe(true);
+ expect(isOk(await client.getJob({ jobId: "job_1" }))).toBe(true);
+ const fundedJob = await client.getJob({ jobId: "job_1" });
+ if (!isOk(fundedJob)) return;
+ expect(fundedJob.value.status).toBe("funded");
+
+ const submitted = await client.submitDeliverable({
+ jobId: "job_1",
+ deliverableUri: "ipfs://deliverable",
+ });
+ expect(isOk(submitted)).toBe(true);
+ const submittedJob = await client.getJob({ jobId: "job_1" });
+ if (!isOk(submittedJob)) return;
+ expect(submittedJob.value.status).toBe("submitted");
+ expect(submittedJob.value.deliverableUri).toBe("ipfs://deliverable");
+
+ const evaluated = await client.evaluate({ jobId: "job_1", passed: true, scoreOrUri: "0.95" });
+ expect(isOk(evaluated)).toBe(true);
+ const evaluatedJob = await client.getJob({ jobId: "job_1" });
+ if (!isOk(evaluatedJob)) return;
+ expect(evaluatedJob.value.status).toBe("evaluated");
+ expect(evaluatedJob.value.evaluation?.passed).toBe(true);
+ expect(evaluatedJob.value.evaluation?.scoreOrUri).toBe("0.95");
+
+ const settled = await client.settle({ jobId: "job_1" });
+ expect(isOk(settled)).toBe(true);
+ const settledJob = await client.getJob({ jobId: "job_1" });
+ if (!isOk(settledJob)) return;
+ expect(settledJob.value.status).toBe("settled");
+ });
+
+ it("mints sequential job ids", async () => {
+ const { client } = setup();
+ expect(await createOk(client)).toBe("job_1");
+ expect(await createOk(client)).toBe("job_2");
+ });
+});
+
+describe("refund path", () => {
+ it("create -> fund -> refund", async () => {
+ const { client } = setup();
+ const jobId = await createOk(client);
+ expect(isOk(await client.fundEscrow({ jobId, amountUsdc: "100.00" }))).toBe(true);
+ const refunded = await client.refund({ jobId });
+ expect(isOk(refunded)).toBe(true);
+ const job = await client.getJob({ jobId });
+ if (!isOk(job)) return;
+ expect(job.value.status).toBe("refunded");
+ });
+});
+
+describe("evaluate-fail path", () => {
+ it("evaluated(fail) cannot settle but can refund", async () => {
+ const { client } = setup();
+ const jobId = await createOk(client);
+ await client.fundEscrow({ jobId, amountUsdc: "100.00" });
+ await client.submitDeliverable({ jobId, deliverableUri: "ipfs://d" });
+ const evaluated = await client.evaluate({ jobId, passed: false });
+ expect(isOk(evaluated)).toBe(true);
+ const job = await client.getJob({ jobId });
+ if (!isOk(job)) return;
+ expect(job.value.status).toBe("evaluated");
+ expect(job.value.evaluation?.passed).toBe(false);
+
+ const settled = await client.settle({ jobId });
+ expect(isErr(settled)).toBe(true);
+ if (!isErr(settled)) return;
+ expect(settled.error.code).toBe("conflict");
+
+ const refunded = await client.refund({ jobId });
+ expect(isOk(refunded)).toBe(true);
+ const after = await client.getJob({ jobId });
+ if (!isOk(after)) return;
+ expect(after.value.status).toBe("refunded");
+ });
+});
+
+describe("illegal-transition rejections", () => {
+ it("submit before funded -> conflict", async () => {
+ const { client } = setup();
+ const jobId = await createOk(client);
+ const res = await client.submitDeliverable({ jobId, deliverableUri: "ipfs://d" });
+ expect(isErr(res)).toBe(true);
+ if (!isErr(res)) return;
+ expect(res.error.code).toBe("conflict");
+ });
+
+ it("settle before evaluated -> conflict", async () => {
+ const { client } = setup();
+ const jobId = await createOk(client);
+ await client.fundEscrow({ jobId, amountUsdc: "100.00" });
+ const res = await client.settle({ jobId });
+ expect(isErr(res)).toBe(true);
+ if (!isErr(res)) return;
+ expect(res.error.code).toBe("conflict");
+ });
+
+ it("evaluate before submitted -> conflict", async () => {
+ const { client } = setup();
+ const jobId = await createOk(client);
+ await client.fundEscrow({ jobId, amountUsdc: "100.00" });
+ const res = await client.evaluate({ jobId, passed: true });
+ expect(isErr(res)).toBe(true);
+ if (!isErr(res)) return;
+ expect(res.error.code).toBe("conflict");
+ });
+
+ it("double-fund -> conflict", async () => {
+ const { client } = setup();
+ const jobId = await createOk(client);
+ await client.fundEscrow({ jobId, amountUsdc: "100.00" });
+ const res = await client.fundEscrow({ jobId, amountUsdc: "100.00" });
+ expect(isErr(res)).toBe(true);
+ if (!isErr(res)) return;
+ expect(res.error.code).toBe("conflict");
+ });
+});
+
+describe("validation rejections", () => {
+ it("rejects malformed/non-positive amounts on createJob", async () => {
+ const { client } = setup();
+ for (const amountUsdc of ["0", "-1", "1.2345678", "abc", ""]) {
+ const res = await client.createJob({ ...VALID, amountUsdc });
+ expect(isErr(res)).toBe(true);
+ if (!isErr(res)) return;
+ expect(res.error.code).toBe("validation_error");
+ }
+ });
+
+ it("rejects empty requester/worker/specUri", async () => {
+ const { client } = setup();
+ expect(isErr(await client.createJob({ ...VALID, requester: " " }))).toBe(true);
+ expect(isErr(await client.createJob({ ...VALID, worker: " " }))).toBe(true);
+ expect(isErr(await client.createJob({ ...VALID, specUri: " " }))).toBe(true);
+ });
+
+ it("rejects empty jobId on every job-addressed method", async () => {
+ const { client } = setup();
+ expect(isErr(await client.fundEscrow({ jobId: " ", amountUsdc: "1" }))).toBe(true);
+ expect(isErr(await client.submitDeliverable({ jobId: " ", deliverableUri: "x" }))).toBe(true);
+ expect(isErr(await client.evaluate({ jobId: " ", passed: true }))).toBe(true);
+ expect(isErr(await client.settle({ jobId: " " }))).toBe(true);
+ expect(isErr(await client.refund({ jobId: " " }))).toBe(true);
+ expect(isErr(await client.getJob({ jobId: " " }))).toBe(true);
+ });
+
+ it("rejects an empty scoreOrUri when provided", async () => {
+ const { client } = setup();
+ const jobId = await createOk(client);
+ const res = await client.evaluate({ jobId, passed: true, scoreOrUri: " " });
+ expect(isErr(res)).toBe(true);
+ if (!isErr(res)) return;
+ expect(res.error.code).toBe("validation_error");
+ });
+});
+
+describe("error mapping", () => {
+ it("maps a thrown createJob error to a retryable integration_error", async () => {
+ const { client } = setup({ throwOn: ["createJob"] });
+ const res = await client.createJob(VALID);
+ expect(isErr(res)).toBe(true);
+ if (!isErr(res)) return;
+ expect(res.error.code).toBe("integration_error");
+ expect(res.error.retryable).toBe(true);
+ });
+
+ it("maps a thrown fundEscrow error to integration_error", async () => {
+ const { client } = setup({ throwOn: ["fundEscrow"] });
+ const jobId = await createOk(client);
+ const res = await client.fundEscrow({ jobId, amountUsdc: "1" });
+ expect(isErr(res)).toBe(true);
+ if (!isErr(res)) return;
+ expect(res.error.code).toBe("integration_error");
+ });
+
+ it("maps a thrown getJob error to integration_error", async () => {
+ const { client } = setup({ throwOn: ["getJob"] });
+ const res = await client.getJob({ jobId: "job_1" });
+ expect(isErr(res)).toBe(true);
+ if (!isErr(res)) return;
+ expect(res.error.code).toBe("integration_error");
+ });
+
+ it("preserves not_found for an unknown jobId rather than masking it", async () => {
+ const { client } = setup();
+ const res = await client.getJob({ jobId: "job_999" });
+ expect(isErr(res)).toBe(true);
+ if (!isErr(res)) return;
+ expect(res.error.code).toBe("not_found");
+ });
+});
diff --git a/packages/erc8183/test/state-machine.test.ts b/packages/erc8183/test/state-machine.test.ts
new file mode 100644
index 0000000..cd019b3
--- /dev/null
+++ b/packages/erc8183/test/state-machine.test.ts
@@ -0,0 +1,52 @@
+import { describe, expect, it } from "vitest";
+import { SettleKitError } from "@settlekit/common";
+import {
+ assertTransition,
+ canTransition,
+ isTerminalJobStatus,
+ peekTransition,
+} from "../src/index.js";
+
+describe("job transition table", () => {
+ it("allows fund from created and forbids settle from created", () => {
+ expect(canTransition("created", "fund")).toBe(true);
+ expect(canTransition("created", "settle")).toBe(false);
+ });
+
+ it("peeks the target status for legal transitions", () => {
+ expect(peekTransition("created", "fund")).toBe("funded");
+ expect(peekTransition("funded", "submit")).toBe("submitted");
+ expect(peekTransition("submitted", "evaluate_pass")).toBe("evaluated");
+ expect(peekTransition("submitted", "evaluate_fail")).toBe("evaluated");
+ expect(peekTransition("evaluated", "settle")).toBe("settled");
+ expect(peekTransition("evaluated", "refund")).toBe("refunded");
+ });
+
+ it("returns undefined for illegal transitions", () => {
+ expect(peekTransition("created", "settle")).toBeUndefined();
+ expect(peekTransition("settled", "fund")).toBeUndefined();
+ });
+
+ it("assertTransition throws a conflict on an illegal move", () => {
+ try {
+ assertTransition("settled", "fund");
+ expect.unreachable("should have thrown");
+ } catch (error) {
+ expect(SettleKitError.is(error)).toBe(true);
+ if (!SettleKitError.is(error)) return;
+ expect(error.code).toBe("conflict");
+ }
+ });
+
+ it("assertTransition returns the next status on a legal move", () => {
+ expect(assertTransition("created", "fund")).toBe("funded");
+ });
+
+ it("identifies terminal statuses", () => {
+ expect(isTerminalJobStatus("settled")).toBe(true);
+ expect(isTerminalJobStatus("refunded")).toBe(true);
+ expect(isTerminalJobStatus("cancelled")).toBe(true);
+ expect(isTerminalJobStatus("created")).toBe(false);
+ expect(isTerminalJobStatus("evaluated")).toBe(false);
+ });
+});
diff --git a/packages/erc8183/tsconfig.json b/packages/erc8183/tsconfig.json
new file mode 100644
index 0000000..f22baf2
--- /dev/null
+++ b/packages/erc8183/tsconfig.json
@@ -0,0 +1,11 @@
+{
+ "extends": "../../tsconfig.base.json",
+ "compilerOptions": {
+ "rootDir": "./src",
+ "outDir": "./dist",
+ "composite": true
+ },
+ "references": [{ "path": "../common" }],
+ "include": ["src/**/*"],
+ "exclude": ["dist", "node_modules", "**/*.test.ts"]
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 1c8c00e..e2dadce 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -935,6 +935,18 @@ importers:
specifier: ^2.0.5
version: 2.1.9(@types/node@20.19.43)
+ packages/arc-chains:
+ devDependencies:
+ '@types/node':
+ specifier: ^20.14.0
+ version: 20.19.43
+ typescript:
+ specifier: ^5.5.4
+ version: 5.9.3
+ vitest:
+ specifier: ^2.0.5
+ version: 2.1.9(@types/node@20.19.43)
+
packages/attribution:
dependencies:
'@settlekit/common':
@@ -1379,6 +1391,38 @@ importers:
specifier: ^2.0.5
version: 2.1.9(@types/node@20.19.43)
+ packages/erc8004:
+ dependencies:
+ '@settlekit/common':
+ specifier: workspace:*
+ version: link:../common
+ devDependencies:
+ '@types/node':
+ specifier: ^20.14.0
+ version: 20.19.43
+ typescript:
+ specifier: ^5.5.4
+ version: 5.9.3
+ vitest:
+ specifier: ^2.0.5
+ version: 2.1.9(@types/node@20.19.43)
+
+ packages/erc8183:
+ dependencies:
+ '@settlekit/common':
+ specifier: workspace:*
+ version: link:../common
+ devDependencies:
+ '@types/node':
+ specifier: ^20.14.0
+ version: 20.19.43
+ typescript:
+ specifier: ^5.5.4
+ version: 5.9.3
+ vitest:
+ specifier: ^2.0.5
+ version: 2.1.9(@types/node@20.19.43)
+
packages/escrow:
dependencies:
'@settlekit/common':