@blindmarket/sdk 0.1.4

package/src/storage/ZgStorage.ts

@@ -0,0 +1,124 @@
+import { Indexer, MemData } from '@0gfoundation/0g-ts-sdk';
+import type { ethers } from 'ethers';
+import { StorageError } from '../errors/index.js';
+import type { RootHash, UploadResult } from '../types.js';
+import type { Storage } from './Storage.js';
+
+export interface ZgStorageOptions {
+  /** 0G Storage indexer URL, e.g. 'https://indexer-storage-testnet-turbo.0g.ai'. */
+  indexerUrl: string;
+  /** 0G chain RPC URL — passed to the indexer for upload fee submission. */
+  rpcUrl: string;
+  /** Wallet used to pay for uploads. Reads don't require a signer. */
+  signer?: ethers.Signer;
+}
+
+/**
+ * Node-only adapter over @0gfoundation/0g-ts-sdk. Browser consumers must
+ * provide their own Storage adapter (IPFS, custom server-side proxy, etc.)
+ * because the 0G TS SDK uses Node-specific filesystem APIs for downloads.
+ */
+export class ZgStorage implements Storage {
+  private readonly indexer: Indexer;
+  private readonly opts: ZgStorageOptions;
+
+  constructor(opts: ZgStorageOptions) {
+    this.opts = opts;
+    this.indexer = new Indexer(opts.indexerUrl);
+  }
+
+  async upload(bytes: Uint8Array): Promise<UploadResult> {
+    if (!this.opts.signer) {
+      throw new StorageError('STORAGE/UPLOAD_FAILED', 'signer required for uploads');
+    }
+    const memData = new MemData(copy(bytes));
+    const [tree, treeErr] = await memData.merkleTree();
+    if (treeErr !== null || !tree) {
+      throw new StorageError('STORAGE/UPLOAD_FAILED', 'merkle tree computation failed', { cause: treeErr ?? undefined });
+    }
+    const rootHash = tree.rootHash() as RootHash;
+
+    let txHash: string | undefined;
+    try {
+      // The 0G SDK's Signer types are pinned to a specific ethers minor version
+      // that may not match the host project's. Runtime is compatible; the cast
+      // avoids false-negative type errors across ethers versions.
+      // biome-ignore lint/suspicious/noExplicitAny: see comment above
+      const [tx, uploadErr] = await this.indexer.upload(memData, this.opts.rpcUrl, this.opts.signer as any);
+      if (uploadErr !== null) {
+        throw new StorageError('STORAGE/UPLOAD_FAILED', 'indexer upload failed', {
+          cause: uploadErr,
+          retriable: true,
+        });
+      }
+      const maybe = tx as { txHash?: string } | null;
+      txHash = maybe?.txHash;
+    } catch (err) {
+      if (err instanceof StorageError) throw err;
+      throw new StorageError('STORAGE/UPLOAD_FAILED', 'unexpected upload error', {
+        cause: err,
+        retriable: true,
+      });
+    }
+
+    return {
+      rootHash,
+      ...(txHash ? { txHash: txHash as `0x${string}` } : {}),
+      size: bytes.byteLength,
+    };
+  }
+
+  async download(rootHash: RootHash): Promise<Uint8Array> {
+    // 0G SDK downloads to a filesystem path. We write to a tmp file, read bytes back,
+    // and delete the tmp file regardless of success/failure.
+    const [nodeFs, nodePath, nodeOs, nodeCrypto] = await loadNodeFs();
+    const rand = nodeCrypto.randomBytes(8).toString('hex');
+    const tmp = nodePath.join(nodeOs.tmpdir(), `0g-${rootHash.replace(/^0x/, '')}-${rand}`);
+    try {
+      const err = await this.indexer.download(rootHash, tmp, true);
+      if (err !== null) {
+        throw new StorageError('STORAGE/NOT_FOUND', `no blob at ${rootHash}`, {
+          cause: err,
+          retriable: true,
+        });
+      }
+      return new Uint8Array(nodeFs.readFileSync(tmp));
+    } finally {
+      try {
+        nodeFs.unlinkSync(tmp);
+      } catch {
+        // ignore cleanup errors
+      }
+    }
+  }
+
+  async hash(bytes: Uint8Array): Promise<RootHash> {
+    const memData = new MemData(copy(bytes));
+    const [tree, err] = await memData.merkleTree();
+    if (err !== null || !tree) {
+      throw new StorageError('STORAGE/UPLOAD_FAILED', 'merkle tree computation failed', { cause: err ?? undefined });
+    }
+    return tree.rootHash() as RootHash;
+  }
+}
+
+function copy(u: Uint8Array): Uint8Array {
+  const c = new Uint8Array(u.byteLength);
+  c.set(u);
+  return c;
+}
+
+type NodeFs = { readFileSync: (p: string) => Buffer; unlinkSync: (p: string) => void };
+type NodePath = { join: (...p: string[]) => string };
+type NodeOs = { tmpdir: () => string };
+type NodeCrypto = { randomBytes: (n: number) => { toString: (enc: 'hex') => string } };
+
+async function loadNodeFs(): Promise<[NodeFs, NodePath, NodeOs, NodeCrypto]> {
+  const [fs, path, os, crypto] = await Promise.all([
+    import('node:fs'),
+    import('node:path'),
+    import('node:os'),
+    import('node:crypto'),
+  ]);
+  return [fs as unknown as NodeFs, path as unknown as NodePath, os as unknown as NodeOs, crypto as unknown as NodeCrypto];
+}

package/src/storage/index.ts

@@ -0,0 +1,3 @@
+export * from './Storage.js';
+export * from './MemoryStorage.js';
+export * from './ZgStorage.js';

package/src/testing/index.ts

@@ -0,0 +1 @@
+export {};

package/src/types.ts

@@ -0,0 +1,76 @@
+export type Address = `0x${string}`;
+export type Hex = `0x${string}`;
+export type TaskId = bigint;
+export type RootHash = Hex;
+
+export type TokenSymbol = 'USDC' | 'A0GI' | string;
+
+export interface TokenRef {
+  address: Address;
+  symbol?: TokenSymbol;
+  decimals?: number;
+}
+
+export interface Reward {
+  token: Address | TokenSymbol;
+  amount: bigint;
+}
+
+export type TaskStatus =
+  | 'funded'
+  | 'assigned'
+  | 'submitted'
+  | 'verified'
+  | 'completed'
+  | 'cancelled';
+
+export interface TaskMetadata {
+  category: string;
+  locationZone: string;
+  reward: Reward;
+  deadline?: Date;
+  extra?: Record<string, string>;
+}
+
+export interface TaskRecord extends TaskMetadata {
+  taskId: TaskId;
+  agent: Address;
+  worker?: Address;
+  taskHash: RootHash;
+  evidenceHash?: RootHash;
+  status: TaskStatus;
+  createdAt: Date;
+}
+
+export interface TaskKey {
+  /** AES-256 symmetric key (32 bytes) used to encrypt task content. */
+  aesKey: Uint8Array;
+  createdAt: Date;
+}
+
+export interface TaskKeyRef {
+  taskId: TaskId;
+  createdAt: Date;
+}
+
+export interface UploadResult {
+  rootHash: RootHash;
+  txHash?: Hex;
+  size: number;
+}
+
+export interface VerificationResult {
+  passed: boolean;
+  confidence: number;
+  model: string;
+  attestation?: Hex;
+  completedAt: Date;
+}
+
+export interface TxReceiptLike {
+  hash: Hex;
+  blockNumber: number;
+  gasUsed: bigint;
+}
+
+export type Awaitable<T> = T | Promise<T>;

package/src/verifier/index.ts

@@ -0,0 +1 @@
+export {};

package/src/worker/Worker.ts

@@ -0,0 +1,98 @@
+import type { BlindEscrowClient, OnChainTask, TaskRegistryClient } from '../chain/index.js';
+import { aesDecrypt, eciesDecrypt, sealEvidence } from '../crypto/index.js';
+import type { EventBus, SdkEvents } from '../events/index.js';
+import type { Signer } from '../signer/index.js';
+import type { Storage } from '../storage/index.js';
+import type { Hex, RootHash, TaskId, TxReceiptLike } from '../types.js';
+
+export interface WorkerDeps {
+  escrow: BlindEscrowClient;
+  registry: TaskRegistryClient;
+  storage: Storage;
+  signer: Signer;
+  events?: EventBus<SdkEvents>;
+}
+
+export interface DecryptInstructionsInput {
+  /** ECIES-wrapped AES key delivered out-of-band by the agent (e.g. via the backend API). */
+  wrappedKey: Uint8Array;
+  /** Worker's private key, hex with or without 0x prefix. */
+  workerPrivKey: string;
+  /** Storage root hash from the on-chain task metadata. */
+  taskHash: RootHash;
+}
+
+export interface SubmitEvidenceInput {
+  taskId: TaskId;
+  evidence: string | Uint8Array;
+  /** Agent's uncompressed secp256k1 pubkey (retrieved via the backend or chain). */
+  agentPubKey: string;
+  /** TEE enclave pubkey for Sealed Inference (from 0G Compute broker). */
+  enclavePubKey: string;
+}
+
+export interface SubmitEvidenceResult {
+  rootHash: RootHash;
+  txHash: Hex;
+  receipt: TxReceiptLike;
+}
+
+/**
+ * Worker-side flows: browse open tasks, decrypt assigned instructions, seal
+ * evidence for agent + TEE, and claim payment after the deadline if
+ * verification stalls. Peer pubkeys and wrapped keys are passed explicitly;
+ * the SDK does not assume a specific message-passing substrate.
+ */
+export class Worker {
+  constructor(private readonly deps: WorkerDeps) {}
+
+  async browse(offset: bigint, limit: bigint): Promise<TaskId[]> {
+    return this.deps.registry.getOpenTasks(offset, limit);
+  }
+
+  async getTaskDetail(taskId: TaskId): Promise<OnChainTask> {
+    return this.deps.escrow.getTask(taskId);
+  }
+
+  async decryptInstructions(input: DecryptInstructionsInput): Promise<Uint8Array> {
+    const aesKey = await eciesDecrypt(input.wrappedKey, input.workerPrivKey);
+    const ciphertext = await this.deps.storage.download(input.taskHash);
+    return aesDecrypt(ciphertext, aesKey);
+  }
+
+  async submitEvidence(input: SubmitEvidenceInput): Promise<SubmitEvidenceResult> {
+    const evidenceBytes = typeof input.evidence === 'string'
+      ? new TextEncoder().encode(input.evidence)
+      : input.evidence;
+
+    const { envelope } = await sealEvidence({
+      evidence: evidenceBytes,
+      agentPubKey: input.agentPubKey,
+      enclavePubKey: input.enclavePubKey,
+    });
+
+    const uploaded = await this.deps.storage.upload(envelope);
+    const rootHash = uploaded.rootHash;
+
+    const receipt = await this.deps.escrow.submitEvidence(input.taskId, rootHash);
+
+    this.deps.events?.emit('evidence.submitted', {
+      taskId: input.taskId,
+      rootHash,
+      txHash: receipt.hash,
+    });
+
+    return { rootHash, txHash: receipt.hash, receipt };
+  }
+
+  /**
+   * Worker escape hatch: reclaim escrow after the deadline if completeVerification
+   * was never called. Payment released per contract logic (85% worker, 15% treasury
+   * or full refund depending on submission state — see BlindEscrow.claimTimeout).
+   */
+  async claimTimeout(taskId: TaskId): Promise<TxReceiptLike> {
+    const receipt = await this.deps.escrow.claimTimeout(taskId);
+    this.deps.events?.emit('payment.claimed', { taskId, txHash: receipt.hash, amount: 0n });
+    return receipt;
+  }
+}

package/src/worker/index.ts

@@ -0,0 +1 @@
+export * from './Worker.js';

package/test/agent.test.ts

@@ -0,0 +1,193 @@
+import { describe, expect, it } from 'vitest';
+import { Agent } from '../src/agent/index.js';
+import type { BlindEscrowClient, CreateTaskArgs } from '../src/chain/index.js';
+import { aesDecrypt, eciesDecrypt, generateKeyPair, sealEvidence } from '../src/crypto/index.js';
+import { EventBus, type SdkEvents } from '../src/events/index.js';
+import { InMemoryKeyStore } from '../src/keystore/index.js';
+import { PrivateKeySigner } from '../src/signer/index.js';
+import { MemoryStorage } from '../src/storage/index.js';
+import type { Address, Hex, TaskId, TxReceiptLike } from '../src/types.js';
+
+const AGENT_PK = '0x0123456789012345678901234567890123456789012345678901234567890123';
+const WORKER_PK = '0x1000000000000000000000000000000000000000000000000000000000000001';
+const FAKE_USDC = '0x317227efcA18D004E12CA8046AEf7E1597458F25' as Address;
+const FAKE_WORKER = '0x2000000000000000000000000000000000000002' as Address;
+
+interface EscrowCall<M extends string> {
+  method: M;
+  args: unknown;
+}
+
+/**
+ * In-memory BlindEscrow mock. Records every call for assertions and hands back
+ * deterministic task ids / receipts so the Agent flow can be exercised without
+ * a real chain.
+ */
+class MockEscrow {
+  readonly calls: EscrowCall<'createTask' | 'assignWorker' | 'cancelTask'>[] = [];
+  private nextId = 1n;
+
+  async createTask(args: CreateTaskArgs) {
+    this.calls.push({ method: 'createTask', args });
+    const taskId = this.nextId++;
+    const receipt: TxReceiptLike = { hash: `0x${'a'.repeat(64)}` as Hex, blockNumber: 1, gasUsed: 21000n };
+    return { taskId, receipt };
+  }
+
+  async assignWorker(taskId: TaskId, worker: Address): Promise<TxReceiptLike> {
+    this.calls.push({ method: 'assignWorker', args: { taskId, worker } });
+    return { hash: `0x${'b'.repeat(64)}` as Hex, blockNumber: 2, gasUsed: 21000n };
+  }
+
+  async cancelTask(taskId: TaskId): Promise<TxReceiptLike> {
+    this.calls.push({ method: 'cancelTask', args: { taskId } });
+    return { hash: `0x${'c'.repeat(64)}` as Hex, blockNumber: 3, gasUsed: 21000n };
+  }
+}
+
+function mkDeps() {
+  const storage = new MemoryStorage();
+  const keystore = new InMemoryKeyStore();
+  const signer = new PrivateKeySigner(AGENT_PK);
+  const events = new EventBus<SdkEvents>();
+  const escrow = new MockEscrow();
+  return {
+    storage,
+    keystore,
+    signer,
+    events,
+    escrow,
+    agent: new Agent({
+      // biome-ignore lint/suspicious/noExplicitAny: MockEscrow matches the subset the Agent uses
+      escrow: escrow as any as BlindEscrowClient,
+      storage,
+      keystore,
+      signer,
+      events,
+    }),
+  };
+}
+
+describe('Agent.createTask', () => {
+  it('encrypts + uploads + calls chain + stashes key + emits event', async () => {
+    const { agent, escrow, storage, keystore, events } = mkDeps();
+
+    const emitted: SdkEvents['task.created'][] = [];
+    events.on('task.created', (p) => {
+      emitted.push(p);
+    });
+
+    const deadline = new Date(Date.now() + 3600_000);
+    const res = await agent.createTask({
+      instructions: 'Take 3 photos of the storefront',
+      category: 'photography',
+      locationZone: 'Lagos, NG',
+      reward: { token: FAKE_USDC, amount: 5_000000n },
+      deadline,
+    });
+
+    expect(res.taskId).toBe(1n);
+    expect(res.rootHash).toMatch(/^0x[0-9a-f]{64}$/);
+    expect(escrow.calls).toHaveLength(1);
+    expect(escrow.calls[0]?.method).toBe('createTask');
+
+    // Keystore now holds the task key for this id
+    const stored = await keystore.getTaskKey(1n);
+    expect(stored).not.toBeNull();
+    expect(stored?.aesKey).toEqual(res.taskKey.aesKey);
+
+    // The uploaded blob decrypts back to the original instructions
+    const blob = await storage.download(res.rootHash);
+    const pt = await aesDecrypt(blob, res.taskKey.aesKey);
+    expect(new TextDecoder().decode(pt)).toBe('Take 3 photos of the storefront');
+
+    // Event fired
+    expect(emitted).toHaveLength(1);
+    expect(emitted[0]?.taskId).toBe(1n);
+    expect(emitted[0]?.rootHash).toBe(res.rootHash);
+  });
+
+  it('accepts Uint8Array instructions as well as strings', async () => {
+    const { agent, storage } = mkDeps();
+    const res = await agent.createTask({
+      instructions: new Uint8Array([0xde, 0xad, 0xbe, 0xef]),
+      category: 'x',
+      locationZone: 'y',
+      reward: { token: FAKE_USDC, amount: 1n },
+      deadline: new Date(Date.now() + 3600_000),
+    });
+    const blob = await storage.download(res.rootHash);
+    const pt = await aesDecrypt(blob, res.taskKey.aesKey);
+    expect(Array.from(pt)).toEqual([0xde, 0xad, 0xbe, 0xef]);
+  });
+});
+
+describe('Agent.assignWorker', () => {
+  it('wraps the task AES key to the worker pubkey and calls chain', async () => {
+    const { agent } = mkDeps();
+    const created = await agent.createTask({
+      instructions: 'hello',
+      category: 'c',
+      locationZone: 'z',
+      reward: { token: FAKE_USDC, amount: 1n },
+      deadline: new Date(Date.now() + 3600_000),
+    });
+    const worker = generateKeyPair();
+    const result = await agent.assignWorker(created.taskId, FAKE_WORKER, worker.publicKey);
+
+    // Worker can recover the AES key from the wrapped blob
+    const recoveredKey = await eciesDecrypt(result.wrappedKey, worker.privateKey);
+    expect(recoveredKey).toEqual(created.taskKey.aesKey);
+  });
+
+  it('throws LIFECYCLE/TASK_NOT_FOUND when task key is missing', async () => {
+    const { agent } = mkDeps();
+    const worker = generateKeyPair();
+    await expect(agent.assignWorker(999n, FAKE_WORKER, worker.publicKey)).rejects.toMatchObject({
+      code: 'LIFECYCLE/TASK_NOT_FOUND',
+    });
+  });
+});
+
+describe('Agent.cancelTask', () => {
+  it('calls chain and removes the task key from keystore', async () => {
+    const { agent, keystore, events } = mkDeps();
+    const created = await agent.createTask({
+      instructions: 'hello',
+      category: 'c',
+      locationZone: 'z',
+      reward: { token: FAKE_USDC, amount: 1n },
+      deadline: new Date(Date.now() + 3600_000),
+    });
+    expect(await keystore.getTaskKey(created.taskId)).not.toBeNull();
+
+    const cancelled: SdkEvents['task.cancelled'][] = [];
+    events.on('task.cancelled', (p) => cancelled.push(p));
+
+    await agent.cancelTask(created.taskId);
+    expect(await keystore.getTaskKey(created.taskId)).toBeNull();
+    expect(cancelled).toHaveLength(1);
+  });
+});
+
+describe('Agent.fetchAndDecryptEvidence', () => {
+  it('downloads the envelope from storage and unwraps with agent privkey', async () => {
+    const { agent, storage, signer } = mkDeps();
+    const agentPub = await signer.getPublicKey();
+    const enclave = generateKeyPair();
+
+    const evidence = new TextEncoder().encode('photos + timestamps');
+    const sealed = await sealEvidence({
+      evidence,
+      agentPubKey: agentPub,
+      enclavePubKey: enclave.publicKey,
+    });
+    const { rootHash } = await storage.upload(sealed.envelope);
+
+    const recovered = await agent.fetchAndDecryptEvidence(rootHash, AGENT_PK);
+    expect(new TextDecoder().decode(recovered)).toBe('photos + timestamps');
+  });
+});
+
+// silence unused-import warning for the imported pk
+void WORKER_PK;

package/test/chain.test.ts

@@ -0,0 +1,145 @@
+import { ethers } from 'ethers';
+import { describe, expect, it } from 'vitest';
+import {
+  BlindEscrowAbi,
+  BlindEscrowClient,
+  BlindReputationAbi,
+  BlindReputationClient,
+  ChainClient,
+  TaskRegistryAbi,
+  TaskRegistryClient,
+  wrapChainError,
+} from '../src/chain/index.js';
+import { networks } from '../src/network/index.js';
+import { PrivateKeySigner } from '../src/signer/index.js';
+import type { Address } from '../src/types.js';
+
+const FIXED_PK = '0x0123456789012345678901234567890123456789012345678901234567890123';
+const RAND_ADDR = '0xFd4F93F5A7BE144c405D1D8fbEC63Fb776207681' as Address;
+
+describe('ABIs', () => {
+  it('BlindEscrow ABI exposes the expected surface', () => {
+    const iface = new ethers.Interface(BlindEscrowAbi);
+    for (const name of [
+      'createTask',
+      'assignWorker',
+      'submitEvidence',
+      'completeVerification',
+      'cancelTask',
+      'getTask',
+      'nextTaskId',
+    ]) {
+      expect(iface.getFunction(name), `missing ${name}`).not.toBeNull();
+    }
+  });
+
+  it('TaskRegistry ABI exposes the expected surface', () => {
+    const iface = new ethers.Interface(TaskRegistryAbi);
+    for (const name of ['getOpenTasks', 'getTaskMeta', 'totalTasks', 'openTaskCount']) {
+      expect(iface.getFunction(name), `missing ${name}`).not.toBeNull();
+    }
+  });
+
+  it('BlindReputation ABI exposes the expected surface', () => {
+    const iface = new ethers.Interface(BlindReputationAbi);
+    for (const name of ['rate', 'getReputation', 'hasBeenRated']) {
+      expect(iface.getFunction(name), `missing ${name}`).not.toBeNull();
+    }
+  });
+});
+
+describe('encoding round-trips (Interface level, no live RPC)', () => {
+  it('BlindEscrow.createTask encodes to a call-data blob matching the ABI', () => {
+    const iface = new ethers.Interface(BlindEscrowAbi);
+    const data = iface.encodeFunctionData('createTask', [
+      '0x' + '11'.repeat(32),
+      RAND_ADDR,
+      1_000000n,
+      'photography',
+      'Lagos, NG',
+      3600n,
+    ]);
+    const decoded = iface.decodeFunctionData('createTask', data);
+    expect(decoded[0]).toBe('0x' + '11'.repeat(32));
+    expect((decoded[1] as string).toLowerCase()).toBe(RAND_ADDR.toLowerCase());
+    expect(decoded[2]).toBe(1_000000n);
+    expect(decoded[3]).toBe('photography');
+    expect(decoded[4]).toBe('Lagos, NG');
+    expect(decoded[5]).toBe(3600n);
+  });
+
+  it('BlindReputation.rate encodes args correctly', () => {
+    const iface = new ethers.Interface(BlindReputationAbi);
+    const data = iface.encodeFunctionData('rate', [RAND_ADDR, 5, 42n]);
+    const decoded = iface.decodeFunctionData('rate', data);
+    expect((decoded[0] as string).toLowerCase()).toBe(RAND_ADDR.toLowerCase());
+    expect(Number(decoded[1])).toBe(5);
+    expect(decoded[2]).toBe(42n);
+  });
+});
+
+describe('ChainClient wiring', () => {
+  it('constructs with a signer and exposes typed sub-clients at the testnet addresses', () => {
+    const signer = new PrivateKeySigner(FIXED_PK);
+    // No provider attached — reads will fail, but construction should succeed
+    // because EthersSigner exposes .provider = null and we fall through to
+    // defaultProvider(network) for the RPC runner.
+    const c = new ChainClient({ network: networks.testnet, signer });
+    expect(c.escrow).toBeInstanceOf(BlindEscrowClient);
+    expect(c.registry).toBeInstanceOf(TaskRegistryClient);
+    expect(c.reputation).toBeInstanceOf(BlindReputationClient);
+    expect(c.escrow.address.toLowerCase()).toBe(networks.testnet.contracts.escrow.toLowerCase());
+    expect(c.registry.address.toLowerCase()).toBe(networks.testnet.contracts.registry.toLowerCase());
+    expect(c.reputation.address.toLowerCase()).toBe(networks.testnet.contracts.reputation.toLowerCase());
+  });
+
+  it('constructs read-only with only a provider', () => {
+    const provider = new ethers.JsonRpcProvider(networks.testnet.rpc[0], {
+      chainId: Number(networks.testnet.chainId),
+      name: networks.testnet.name,
+    });
+    const c = new ChainClient({ network: networks.testnet, provider });
+    expect(c.escrow).toBeInstanceOf(BlindEscrowClient);
+  });
+});
+
+describe('wrapChainError', () => {
+  it('maps INSUFFICIENT_FUNDS to CHAIN/INSUFFICIENT_BALANCE', () => {
+    const err = wrapChainError({ code: 'INSUFFICIENT_FUNDS', message: 'no funds' });
+    expect(err.code).toBe('CHAIN/INSUFFICIENT_BALANCE');
+    expect(err.retriable).toBe(false);
+  });
+
+  it('maps NONCE_EXPIRED to CHAIN/NONCE_CONFLICT (retriable)', () => {
+    const err = wrapChainError({ code: 'NONCE_EXPIRED', message: 'nonce' });
+    expect(err.code).toBe('CHAIN/NONCE_CONFLICT');
+    expect(err.retriable).toBe(true);
+  });
+
+  it('maps TIMEOUT to CHAIN/TX_TIMED_OUT (retriable)', () => {
+    const err = wrapChainError({ code: 'TIMEOUT', message: 't' });
+    expect(err.code).toBe('CHAIN/TX_TIMED_OUT');
+    expect(err.retriable).toBe(true);
+  });
+
+  it('maps CALL_EXCEPTION to CHAIN/TX_REVERTED and surfaces revert data', () => {
+    const err = wrapChainError({
+      code: 'CALL_EXCEPTION',
+      shortMessage: 'reverted',
+      data: '0xdeadbeef',
+    });
+    expect(err.code).toBe('CHAIN/TX_REVERTED');
+    expect(err.context).toEqual({ data: '0xdeadbeef' });
+  });
+
+  it('defaults unknown errors to CHAIN/TX_REVERTED', () => {
+    const err = wrapChainError(new Error('boom'));
+    expect(err.code).toBe('CHAIN/TX_REVERTED');
+    expect(err.retriable).toBe(false);
+  });
+
+  it('prefixes the hint', () => {
+    const err = wrapChainError({ message: 'x' }, 'createTask');
+    expect(err.message).toMatch(/^createTask:/);
+  });
+});