@escro/sdk 0.2.0 → 0.4.0

package/dist/index.cjs

@@ -40,6 +40,7 @@ __export(index_exports, {
   ApiClient: () => ApiClient,
   ENABLED_RAILS: () => ENABLED_RAILS,
   Escro: () => Escro,
+  EscroConfirmError: () => EscroConfirmError,
   EscroError: () => EscroError,
   EscroRailNotEnabledError: () => EscroRailNotEnabledError,
   EscrowNotFoundError: () => EscrowNotFoundError,
@@ -133,7 +134,7 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/client.ts
-var import_web32 = require("@solana/web3.js");
+var import_web33 = require("@solana/web3.js");
 
 // ../shared/dist/index.js
 var import_crypto = require("crypto");
@@ -152,20 +153,10 @@ var EscrowState = /* @__PURE__ */ ((EscrowState2) => {
   EscrowState2["REFUNDED"] = "REFUNDED";
   return EscrowState2;
 })(EscrowState || {});
-function canonicalize(value) {
-  if (value === null) return "null";
-  if (Array.isArray(value)) {
-    return "[" + value.map((v) => v === void 0 ? "null" : canonicalize(v)).join(",") + "]";
-  }
-  if (typeof value === "object") {
-    const obj = value;
-    const keys = Object.keys(obj).filter((k) => obj[k] !== void 0).sort();
-    return "{" + keys.map((k) => JSON.stringify(k) + ":" + canonicalize(obj[k])).join(",") + "}";
-  }
-  return JSON.stringify(value);
-}
 var PROGRAM_ID_DEVNET = "EjLpJ3obUYk1f2KDensU7UdGBZTxSdxufm7CSnMA3H5C";
 var PROGRAM_ID_MAINNET = "4CwLNRF4mFXutiBGjtMHQBxh8whW8T8EyvJXdRhY1rvr";
+var CURRENT_ACCOUNT_VERSION = 1;
+var MAX_DISPUTE_REASON_BYTES = 200;
 var ONCHAIN_REFUND_GRACE_SECONDS = 900;
 var ONCHAIN_TIMEOUT_SECONDS = 86400;
 var CLOCK_SKEW_SECONDS = 60;
@@ -185,6 +176,26 @@ function assertProgramIdNotPlaceholder(id, cluster) {
     );
   }
 }
+function canonicalize(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) {
+    return "[" + value.map((v) => v === void 0 ? "null" : canonicalize(v)).join(",") + "]";
+  }
+  if (typeof value === "object") {
+    const obj = value;
+    const keys = Object.keys(obj).filter((k) => obj[k] !== void 0).sort();
+    return "{" + keys.map((k) => JSON.stringify(k) + ":" + canonicalize(obj[k])).join(",") + "}";
+  }
+  return JSON.stringify(value);
+}
+function disputeReasonError(reason) {
+  if (reason.length === 0) return "reason must not be empty";
+  const bytes = new TextEncoder().encode(reason).length;
+  if (bytes > MAX_DISPUTE_REASON_BYTES) {
+    return `reason is ${String(bytes)} bytes in UTF-8; the program accepts at most ${String(MAX_DISPUTE_REASON_BYTES)}`;
+  }
+  return null;
+}
 function hashBody(rawBody) {
   return (0, import_crypto.createHash)("sha256").update(rawBody, "utf8").digest("hex");
 }
@@ -230,6 +241,26 @@ function verifyBotDescriptorSignature(descriptor) {
     return false;
   }
 }
+function spec(discriminator, escrowAccountIndex, cause) {
+  return {
+    discriminator: Uint8Array.from(discriminator),
+    escrowAccountIndex,
+    signerAccountIndex: 0,
+    cause
+  };
+}
+var ESCROW_INSTRUCTIONS = {
+  create_escrow: spec([253, 215, 165, 116, 36, 108, 68, 80], 4, null),
+  claim_task: spec([49, 222, 219, 238, 155, 68, 221, 136], 1, null),
+  submit_deliverable: spec([38, 137, 64, 44, 237, 11, 125, 101], 1, null),
+  raise_dispute: spec([41, 243, 1, 51, 150, 95, 246, 73], 1, null),
+  cancel_escrow: spec([156, 203, 54, 179, 38, 72, 33, 21], 3, "CANCELLED"),
+  release_payment: spec([24, 34, 191, 86, 145, 160, 183, 233], 3, "EXPLICIT_RELEASE"),
+  timeout_release: spec([98, 176, 26, 12, 83, 105, 154, 68], 3, "TIMEOUT_RELEASE"),
+  refund_buyer: spec([199, 139, 203, 146, 192, 150, 53, 218], 3, "DEADLINE_REFUND"),
+  arbitration_release: spec([118, 157, 141, 26, 104, 117, 94, 229], 4, "ARBITRATION_RELEASE"),
+  arbitration_refund: spec([255, 194, 84, 248, 185, 249, 120, 122], 4, "ARBITRATION_REFUND")
+};
 
 // src/payments.ts
 var RAILS = ["escrow", "x402"];
@@ -244,9 +275,10 @@ var EscrowPaymentRouter = class {
 
 // src/errors.ts
 var EscroError = class extends Error {
-  constructor(message, code = "ESCRO_ERROR") {
+  constructor(message, code = "ESCRO_ERROR", retryAfterMs2) {
     super(message);
     __publicField(this, "code", code);
+    __publicField(this, "retryAfterMs", retryAfterMs2);
     this.name = "EscroError";
   }
 };
@@ -277,6 +309,18 @@ var EscrowTimeoutError = class extends EscroError {
     this.name = "EscrowTimeoutError";
   }
 };
+var EscroConfirmError = class extends EscroError {
+  constructor(address, signature, code, message, retryAfterMs2) {
+    super(
+      `Confirm failed for escrow ${address} (signature ${signature}): ${message}`,
+      code,
+      retryAfterMs2
+    );
+    __publicField(this, "address", address);
+    __publicField(this, "signature", signature);
+    this.name = "EscroConfirmError";
+  }
+};
 var UnauthorizedError = class extends EscroError {
   constructor(message = "Unauthorized") {
     super(message, "UNAUTHORIZED");
@@ -307,7 +351,10 @@ async function handleError(res, address) {
   if (res.status === 404) throw new EscrowNotFoundError(address ?? msg);
   if (res.status === 409) throw new EscrowStateError(msg);
   if (res.status === 401 || res.status === 403) throw new UnauthorizedError(msg);
-  throw new EscroError(msg, body.code ?? "UNKNOWN");
+  throw new EscroError(msg, body.code ?? "UNKNOWN", retryAfterMs(res.headers.get("retry-after")));
+}
+function retryAfterMs(header) {
+  return header !== null && /^\d+$/.test(header.trim()) ? Number(header.trim()) * 1e3 : void 0;
 }
 var ApiClient = class {
   constructor(baseUrl, wallet) {
@@ -383,6 +430,22 @@ var ApiClient = class {
     const body = await res.json();
     return body.wallets;
   }
+  /**
+   * GET /rep/:wallet : one wallet's EscroRep RAW components (ARCHITECTURE §9).
+   * Unauthenticated public read (no auth headers). Unknown wallets return zeroed
+   * components, never 404; a 404 means the deployment mounted no reputation
+   * source and surfaces as {@link ReputationUnavailableError}. Shares the public
+   * per-wallet rate budget with every other caller, so fan-outs should use
+   * {@link listReputations} instead.
+   */
+  async getReputation(wallet) {
+    const res = await fetch(this.url(`/rep/${encodeURIComponent(wallet)}`));
+    if (!res.ok) {
+      if (res.status === 404) throw new ReputationUnavailableError();
+      await handleError(res);
+    }
+    return await res.json();
+  }
   /**
    * POST /v1/escrows — create escrow, returns unsigned tx + ids.
    * Requires auth.
@@ -442,8 +505,11 @@ var ApiClient = class {
     return res.json();
   }
   /**
-   * POST /v1/escrows/:address/release — DB-only state update.
-   * Requires auth (buyer). No on-chain tx returned.
+   * POST /v1/escrows/:address/release: records the landed release once the API's RPC shows
+   * the escrow closed. Requires auth (buyer). No on-chain tx returned. A 409
+   * `ESCROW_NOT_SETTLED`, a 5xx or a 429 throws an {@link EscroError} with the server's code,
+   * or `HTTP_<status>` when the answer carries none; {@link Escro.releasePaymentWithOutcome}
+   * decides which to retry. Other refusals throw as every route does.
    */
   async releasePaymentDb(address) {
     const path = `/v1/escrows/${address}/release`;
@@ -451,7 +517,19 @@ var ApiClient = class {
       method: "POST",
       headers: authHeaders(this.wallet, "POST", path)
     });
-    if (!res.ok) await handleError(res, address);
+    if (res.ok) return;
+    if (res.status !== 409 && res.status !== 429 && res.status < 500) {
+      await handleError(res, address);
+    }
+    const body = await res.json().catch(() => ({}));
+    if (res.status === 409 && body.code !== "ESCROW_NOT_SETTLED") {
+      throw new EscrowStateError(body.error ?? `HTTP ${String(res.status)}`);
+    }
+    throw new EscroError(
+      body.error ?? `HTTP ${String(res.status)}`,
+      body.code ?? `HTTP_${String(res.status)}`,
+      retryAfterMs(res.headers.get("retry-after"))
+    );
   }
   /**
    * POST /v1/escrows/:address/cancel — returns unsigned tx.
@@ -472,7 +550,7 @@ var ApiClient = class {
    */
   async raiseDispute(address, params) {
     const path = `/v1/escrows/${address}/dispute`;
-    const rawBody = JSON.stringify({ reason: params.reason, evidence: params.evidence });
+    const rawBody = JSON.stringify({ reason: params.reason });
     const res = await fetch(this.url(path), {
       method: "POST",
       headers: {
@@ -484,6 +562,35 @@ var ApiClient = class {
     if (!res.ok) await handleError(res, address);
     return res.json();
   }
+  /**
+   * POST /v1/escrows/:address/confirm: the API records the create, claim, submit,
+   * cancel or dispute the landed `signature` carries, after verifying it on chain.
+   * A non-2xx answer throws an {@link EscroError} with the server's code, or
+   * `HTTP_<status>` when the answer carries none; a network failure rejects with
+   * fetch's own error. {@link Escro.confirm} decides which to retry.
+   */
+  async confirm(address, signature, evidence) {
+    const path = `/v1/escrows/${address}/confirm`;
+    const rawBody = JSON.stringify({ signature, evidence });
+    const res = await fetch(this.url(path), {
+      method: "POST",
+      headers: {
+        ...authHeaders(this.wallet, "POST", path, rawBody),
+        "content-type": "application/json"
+      },
+      body: rawBody
+    });
+    if (!res.ok) {
+      const body2 = await res.json().catch(() => ({}));
+      throw new EscroError(
+        body2.error ?? `HTTP ${String(res.status)}`,
+        body2.code ?? `HTTP_${String(res.status)}`,
+        retryAfterMs(res.headers.get("retry-after"))
+      );
+    }
+    const body = await res.json();
+    return deserialize(body.escrow);
+  }
   /**
    * GET /v1/stats — public protocol-wide stats.
    * No auth required. Upstream typing in {@link Escro.getStats} narrows the
@@ -529,8 +636,61 @@ async function pollUntil(address, fetcher, predicate, timeoutMs = MS_24_H) {
 
 // src/solana.ts
 var import_node_crypto = require("crypto");
-var import_web3 = require("@solana/web3.js");
+var import_web32 = require("@solana/web3.js");
 var import_spl_token = require("@solana/spl-token");
+
+// ../shared/dist/solana.js
+var import_web3 = require("@solana/web3.js");
+var import_bs583 = __toESM(require("bs58"), 1);
+var utf8 = (s) => new TextEncoder().encode(s);
+function findPlatformConfigPda(programId) {
+  return import_web3.PublicKey.findProgramAddressSync([utf8("config")], programId);
+}
+function derivePlatformConfigPda(programId) {
+  return findPlatformConfigPda(programId)[0];
+}
+var PLATFORM_CONFIG_LAYOUT = {
+  version: 8,
+  fee_bps: 9,
+  oracle_authority: 11,
+  usdc_mint: 43,
+  treasury: 75,
+  bump: 107,
+  length: 108
+};
+var PLATFORM_CONFIG_DISCRIMINATOR = [
+  160,
+  78,
+  128,
+  0,
+  248,
+  83,
+  230,
+  160
+];
+function decodePlatformConfig(data) {
+  const L = PLATFORM_CONFIG_LAYOUT;
+  if (data.length !== L.length) {
+    throw new Error(
+      `PlatformConfig account is ${String(data.length)} bytes, expected ${String(L.length)}`
+    );
+  }
+  if (PLATFORM_CONFIG_DISCRIMINATOR.some((byte2, i) => data[i] !== byte2)) {
+    throw new Error("PlatformConfig discriminator mismatch: not a PlatformConfig account");
+  }
+  const byte = (at) => data[at] ?? 0;
+  const key = (at) => import_bs583.default.encode(data.subarray(at, at + 32));
+  return {
+    version: byte(L.version),
+    feeBps: byte(L.fee_bps) | byte(L.fee_bps + 1) << 8,
+    oracleAuthority: key(L.oracle_authority),
+    usdcMint: key(L.usdc_mint),
+    treasury: key(L.treasury),
+    bump: byte(L.bump)
+  };
+}
+
+// src/solana.ts
 function disc(name) {
   return Buffer.from((0, import_node_crypto.createHash)("sha256").update(`global:${name}`).digest()).subarray(0, 8);
 }
@@ -538,14 +698,14 @@ var DISC_RELEASE_PAYMENT = disc("release_payment");
 function resolveProgramId(cluster) {
   const id = getProgramId(cluster);
   assertProgramIdNotPlaceholder(id, cluster);
-  return new import_web3.PublicKey(id);
+  return new import_web32.PublicKey(id);
 }
 function allowedProgramIds(programId) {
   return /* @__PURE__ */ new Set([
     programId.toBase58(),
     import_spl_token.TOKEN_PROGRAM_ID.toBase58(),
     import_spl_token.ASSOCIATED_TOKEN_PROGRAM_ID.toBase58(),
-    import_web3.ComputeBudgetProgram.programId.toBase58()
+    import_web32.ComputeBudgetProgram.programId.toBase58()
   ]);
 }
 var MAX_INSTRUCTIONS = 6;
@@ -571,25 +731,17 @@ var FORBIDDEN_TOKEN_IX_TAGS = /* @__PURE__ */ new Set([
   15
   // BurnChecked
 ]);
-var EXPECTED_PLATFORM_CONFIG_VERSION = 1;
-var VERSION_OFFSET = 8;
-var MINT_OFFSET = 43;
-var TREASURY_OFFSET = 75;
 async function fetchPlatformConfig(connection, cluster) {
-  const programId = resolveProgramId(cluster);
-  const [pda] = import_web3.PublicKey.findProgramAddressSync([Buffer.from("config")], programId);
+  const pda = derivePlatformConfigPda(resolveProgramId(cluster));
   const info = await connection.getAccountInfo(pda);
   if (!info) throw new Error("PlatformConfig account not found on-chain");
-  const version = info.data[VERSION_OFFSET];
-  if (version !== EXPECTED_PLATFORM_CONFIG_VERSION) {
+  const config = decodePlatformConfig(info.data);
+  if (config.version !== CURRENT_ACCOUNT_VERSION) {
     throw new Error(
-      `PlatformConfig version mismatch: expected ${String(EXPECTED_PLATFORM_CONFIG_VERSION)}, got ${String(version)}`
+      `PlatformConfig version mismatch: expected ${String(CURRENT_ACCOUNT_VERSION)}, got ${String(config.version)}`
     );
   }
-  return {
-    mint: new import_web3.PublicKey(info.data.subarray(MINT_OFFSET, MINT_OFFSET + 32)),
-    treasury: new import_web3.PublicKey(info.data.subarray(TREASURY_OFFSET, TREASURY_OFFSET + 32))
-  };
+  return { mint: new import_web32.PublicKey(config.usdcMint), treasury: new import_web32.PublicKey(config.treasury) };
 }
 function validateTransaction(tx, cluster) {
   const programId = resolveProgramId(cluster);
@@ -619,7 +771,7 @@ function validateTransaction(tx, cluster) {
 }
 async function signAndSend(base64Tx, wallet, connection, cluster) {
   const buf = Buffer.from(base64Tx, "base64");
-  const tx = import_web3.Transaction.from(buf);
+  const tx = import_web32.Transaction.from(buf);
   validateTransaction(tx, cluster);
   tx.partialSign(wallet);
   const raw = tx.serialize();
@@ -633,7 +785,7 @@ async function signAndSend(base64Tx, wallet, connection, cluster) {
 async function buildReleasePaymentTx(params) {
   const { buyer, escrowPda, worker, mint, treasury, connection, cluster } = params;
   const programId = resolveProgramId(cluster);
-  const [platformConfig] = import_web3.PublicKey.findProgramAddressSync([Buffer.from("config")], programId);
+  const platformConfig = derivePlatformConfigPda(programId);
   const vault = (0, import_spl_token.getAssociatedTokenAddressSync)(
     mint,
     escrowPda,
@@ -655,7 +807,7 @@ async function buildReleasePaymentTx(params) {
     import_spl_token.TOKEN_PROGRAM_ID,
     import_spl_token.ASSOCIATED_TOKEN_PROGRAM_ID
   );
-  const ix = new import_web3.TransactionInstruction({
+  const ix = new import_web32.TransactionInstruction({
     programId,
     keys: [
       { pubkey: buyer, isSigner: true, isWritable: true },
@@ -673,7 +825,7 @@ async function buildReleasePaymentTx(params) {
     data: DISC_RELEASE_PAYMENT
   });
   const { blockhash } = await connection.getLatestBlockhash("confirmed");
-  const tx = new import_web3.Transaction();
+  const tx = new import_web32.Transaction();
   tx.recentBlockhash = blockhash;
   tx.feePayer = buyer;
   tx.add((0, import_spl_token.createAssociatedTokenAccountIdempotentInstruction)(buyer, workerAta, worker, mint));
@@ -683,6 +835,33 @@ async function buildReleasePaymentTx(params) {
 }
 
 // src/client.ts
+var CONFIRM_WINDOW_MS = 3e4;
+var CONFIRM_FIRST_DELAY_MS = 500;
+var CONFIRM_MAX_DELAY_MS = 4e3;
+var RETRYABLE_CONFIRM_CODES = [
+  "TX_NOT_FOUND",
+  "RPC_UNAVAILABLE",
+  "HTTP_502",
+  "HTTP_503",
+  "HTTP_504",
+  "RATE_LIMITED",
+  "HTTP_429"
+];
+function isRetryableConfirmCode(code) {
+  return RETRYABLE_CONFIRM_CODES.includes(code);
+}
+function isRetryableReleaseCode(code) {
+  return code === "ESCROW_NOT_SETTLED" || isRetryableConfirmCode(code);
+}
+function isUrl(value) {
+  try {
+    new URL(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+var sleep2 = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 var Escro = class {
   constructor(options) {
     __publicField(this, "connection");
@@ -692,35 +871,46 @@ var Escro = class {
     __publicField(this, "router", new EscrowPaymentRouter());
     this.options = options;
     this.cluster = options.cluster;
-    this.connection = new import_web32.Connection(options.rpcUrl, "confirmed");
+    this.connection = new import_web33.Connection(options.rpcUrl, "confirmed");
     this.api = new ApiClient(options.apiUrl, options.wallet);
   }
   // ── Buyer Bot ────────────────────────────────────────────────────────────────
   /**
    * Create a new escrow: registers with the API, signs and submits the
-   * on-chain `create_escrow` transaction.
+   * on-chain `create_escrow` transaction, then confirms it with the API.
    *
    * @returns `{ escrowId, escrowPda, signature }` — use `escrowPda` for all subsequent calls.
    */
   async createEscrow(params) {
     const { escrowId, escrowPda, unsignedTx } = await this.api.createEscrow(params);
-    const signature = await signAndSend(
-      unsignedTx,
-      this.options.wallet,
-      this.connection,
-      this.cluster
-    );
+    const signature = await this.send(unsignedTx);
+    await this.confirm(escrowPda, signature);
     return { escrowId, escrowPda, signature };
   }
   /**
    * Release payment to the worker. Buyer must be the wallet in the constructor.
    * Builds and submits the `release_payment` on-chain tx FIRST (the chain is the
-   * source of truth), then confirms DB state. The DB confirmation is best-effort:
-   * the oracle sweep reconciles it if it fails.
+   * source of truth), then has the API record it, retrying as
+   * {@link Escro.releasePaymentWithOutcome} does. Use that method to see whether the
+   * API recorded the release.
    *
    * @returns Solana transaction signature.
    */
   async releasePayment(address) {
+    const { signature } = await this.releasePaymentWithOutcome(address);
+    return signature;
+  }
+  /**
+   * {@link Escro.releasePayment}, reporting whether the API recorded the release.
+   * `ESCROW_NOT_SETTLED` (the API's RPC does not yet show the escrow closed), the codes
+   * {@link Escro.confirm} retries and a network failure are retried for about 30 s. A
+   * failure never throws: the release already landed, so the signature is returned with
+   * `confirm.landed: false` and an `EscroConfirmError` (the API's code, or
+   * `NETWORK_ERROR` when the last call never reached it).
+   *
+   * @returns `{ signature, confirm }`.
+   */
+  async releasePaymentWithOutcome(address) {
     const escrow = await this.api.getEscrow(address);
     if (!escrow.taker) {
       throw new EscrowNotFoundError(`Escrow ${address} has no assigned worker`);
@@ -728,8 +918,8 @@ var Escro = class {
     const { treasury, mint } = await fetchPlatformConfig(this.connection, this.cluster);
     const unsignedTx = await buildReleasePaymentTx({
       buyer: this.options.wallet.publicKey,
-      escrowPda: new import_web32.PublicKey(address),
-      worker: new import_web32.PublicKey(escrow.taker),
+      escrowPda: new import_web33.PublicKey(address),
+      worker: new import_web33.PublicKey(escrow.taker),
       mint,
       treasury,
       connection: this.connection,
@@ -742,31 +932,47 @@ var Escro = class {
       this.cluster
     );
     try {
-      await this.api.releasePaymentDb(address);
-    } catch {
+      await this.retryRecord(
+        address,
+        signature,
+        () => this.api.releasePaymentDb(address),
+        isRetryableReleaseCode
+      );
+    } catch (err) {
+      if (!(err instanceof EscroConfirmError)) throw err;
+      return { signature, confirm: { landed: false, error: err } };
     }
-    return signature;
+    return { signature, confirm: { landed: true } };
   }
   /**
    * Raise a dispute for an escrow. Either the buyer or the assigned worker
-   * may call this. Signs and submits the `raise_dispute` on-chain tx.
+   * may call this. Signs and submits the `raise_dispute` on-chain tx, then confirms it with the API.
    *
    * @returns Solana transaction signature.
    */
   async raiseDispute(address, params) {
-    const { unsignedTx } = await this.api.raiseDispute(address, params);
-    return signAndSend(unsignedTx, this.options.wallet, this.connection, this.cluster);
+    const reasonError = disputeReasonError(params.reason);
+    if (reasonError !== null) throw new EscroError(reasonError, "VALIDATION_ERROR");
+    if (params.evidence !== void 0 && !isUrl(params.evidence)) {
+      throw new EscroError(`evidence must be a URL: ${params.evidence}`, "VALIDATION_ERROR");
+    }
+    const { unsignedTx } = await this.api.raiseDispute(address, { reason: params.reason });
+    const signature = await this.send(unsignedTx);
+    await this.confirm(address, signature, {
+      ...params.evidence !== void 0 && { evidence: params.evidence }
+    });
+    return signature;
   }
   /**
    * Cancel a funded escrow before any worker has claimed it.
    * Buyer must be the wallet in the constructor. Only valid when state is `FUNDED`.
-   * Signs and submits the `cancel_escrow` on-chain tx; full USDC refund to buyer.
+   * Signs and submits the `cancel_escrow` on-chain tx, then confirms it with the API; full USDC refund to buyer.
    *
    * @returns Solana transaction signature.
    */
   async cancelEscrow(address) {
     const { unsignedTx } = await this.api.cancelEscrow(address);
-    return signAndSend(unsignedTx, this.options.wallet, this.connection, this.cluster);
+    return this.sendAndConfirm(address, unsignedTx);
   }
   // ── Payments (dual-path; x402 reserved) ───────────────────────────────────────
   /**
@@ -791,23 +997,23 @@ var Escro = class {
   // ── Worker Bot ───────────────────────────────────────────────────────────────
   /**
    * Claim an assigned task. Worker must be the wallet in the constructor.
-   * Signs and submits the `claim_task` on-chain tx.
+   * Signs and submits the `claim_task` on-chain tx, then confirms it with the API.
    *
    * @returns Solana transaction signature.
    */
   async claimTask(address) {
     const { unsignedTx } = await this.api.claimTask(address);
-    return signAndSend(unsignedTx, this.options.wallet, this.connection, this.cluster);
+    return this.sendAndConfirm(address, unsignedTx);
   }
   /**
    * Submit a deliverable for the buyer to review. Worker must be the wallet.
-   * Signs and submits the `submit_deliverable` on-chain tx.
+   * Signs and submits the `submit_deliverable` on-chain tx, then confirms it with the API.
    *
    * @returns Solana transaction signature.
    */
   async submitDeliverable(address, params) {
     const { unsignedTx } = await this.api.submitDeliverable(address, params);
-    return signAndSend(unsignedTx, this.options.wallet, this.connection, this.cluster);
+    return this.sendAndConfirm(address, unsignedTx);
   }
   /**
    * List tasks assigned to the wallet's public key.
@@ -917,6 +1123,70 @@ var Escro = class {
     return data;
   }
   // ── Shared ───────────────────────────────────────────────────────────────────
+  /**
+   * Ask the API to record the create, claim, submit, cancel or dispute that the
+   * landed `signature` carries; the API verifies it on chain first. Retries a
+   * not-yet-visible transaction, an RPC failure, a gateway error or a rate limit
+   * for about 30 s (waiting at least a sent Retry-After), never a rejection. Throws
+   * {@link EscroConfirmError}; calling again is safe (a replay of a recorded
+   * transition succeeds).
+   */
+  async confirm(address, signature, opts = {}) {
+    return this.retryRecord(
+      address,
+      signature,
+      () => this.api.confirm(address, signature, opts.evidence),
+      isRetryableConfirmCode
+    );
+  }
+  // Calls `record` until the API records the landed `signature`: a code `retryable` accepts or
+  // a network failure is retried for about 30 s (waiting at least a sent Retry-After), any
+  // other refusal is not. Throws EscroConfirmError.
+  async retryRecord(address, signature, record, retryable) {
+    const deadline = Date.now() + CONFIRM_WINDOW_MS;
+    let delay = CONFIRM_FIRST_DELAY_MS;
+    for (; ; ) {
+      let code;
+      let message;
+      let retryAfterMs2;
+      let wait = delay;
+      try {
+        return await record();
+      } catch (err) {
+        if (err instanceof EscroError) {
+          if (!retryable(err.code)) {
+            throw new EscroConfirmError(
+              address,
+              signature,
+              err.code,
+              err.message,
+              err.retryAfterMs
+            );
+          }
+          code = err.code;
+          message = err.message;
+          retryAfterMs2 = err.retryAfterMs;
+          wait = Math.max(delay, err.retryAfterMs ?? 0);
+        } else {
+          code = "NETWORK_ERROR";
+          message = err instanceof Error ? err.message : String(err);
+        }
+      }
+      if (Date.now() + wait > deadline) {
+        throw new EscroConfirmError(address, signature, code, message, retryAfterMs2);
+      }
+      await sleep2(wait);
+      delay = Math.min(delay * 2, CONFIRM_MAX_DELAY_MS);
+    }
+  }
+  send(unsignedTx) {
+    return signAndSend(unsignedTx, this.options.wallet, this.connection, this.cluster);
+  }
+  async sendAndConfirm(address, unsignedTx) {
+    const signature = await this.send(unsignedTx);
+    await this.confirm(address, signature);
+    return signature;
+  }
   /**
    * Fetch an escrow by its PDA address.
    * If `options.poll` is true, polls with exponential backoff until the escrow
@@ -1050,9 +1320,9 @@ function createBittensorSubnetAdapter(config) {
     id,
     capabilities: config.capabilities,
     healthCheck: config.checkHealth,
-    async execute(spec) {
+    async execute(spec2) {
       const budgetTao = await config.swap(config.taskBudgetMicroUsdc);
-      const content = await config.callSubnet(spec, budgetTao);
+      const content = await config.callSubnet(spec2, budgetTao);
       const contentHash = sha256Hex2(content);
       const proofUri = await config.pin(content);
       return {
@@ -1135,16 +1405,16 @@ function scoreGradientsDemoDeliverable(content) {
   }
   return matches / expected.length;
 }
-function referencePlaceholder(spec) {
+function referencePlaceholder(spec2) {
   return canonicalize({
     checkpoint: "reference-sn56-checkpoint",
     eval: { metric: "accuracy", score: 0 },
     note: "reference stub - replace the callSubnet port with a real SN56 miner call.",
-    taskType: spec.taskType
+    taskType: spec2.taskType
   });
 }
-var defaultCallSubnet = (spec) => Promise.resolve(
-  spec.metadata.demo === GRADIENTS_DEMO_MARKER ? solveGradientsDemo() : referencePlaceholder(spec)
+var defaultCallSubnet = (spec2) => Promise.resolve(
+  spec2.metadata.demo === GRADIENTS_DEMO_MARKER ? solveGradientsDemo() : referencePlaceholder(spec2)
 );
 function createGradientsAdapter(config = {}) {
   return createBittensorSubnetAdapter({
@@ -1256,17 +1526,17 @@ function scoreRidgesDemoDeliverable(content) {
   }
   return coveredInputs.size / DEMO_INPUTS.length;
 }
-function referencePlaceholder2(spec) {
+function referencePlaceholder2(spec2) {
   return canonicalize({
     language: "typescript",
     solution: "// reference stub - replace the runAgent port with a real Ridges agent call.",
     passed: false,
     tests: [],
-    taskType: spec.taskType
+    taskType: spec2.taskType
   });
 }
-var defaultRunAgent = (spec) => Promise.resolve(
-  spec.metadata.demo === RIDGES_DEMO_MARKER ? solveRidgesDemo() : referencePlaceholder2(spec)
+var defaultRunAgent = (spec2) => Promise.resolve(
+  spec2.metadata.demo === RIDGES_DEMO_MARKER ? solveRidgesDemo() : referencePlaceholder2(spec2)
 );
 var defaultPin2 = (content) => Promise.resolve(`ipfs://placeholder-${sha256Hex3(content).slice(0, 16)}`);
 function createRidgesAdapter(config = {}) {
@@ -1279,8 +1549,8 @@ function createRidgesAdapter(config = {}) {
     id: service,
     capabilities,
     healthCheck: checkHealth,
-    async execute(spec) {
-      const content = await runAgent(spec);
+    async execute(spec2) {
+      const content = await runAgent(spec2);
       const contentHash = sha256Hex3(content);
       const proofUri = await pin(content);
       return {
@@ -1389,15 +1659,15 @@ function score404genDemoDeliverable(content) {
   }
   return Math.min(batch.assets.length / DEMO_EXPECTATION.requestedAssets, 1);
 }
-function referencePlaceholder3(spec) {
+function referencePlaceholder3(spec2) {
   return canonicalize({
     assets: [{ format: "GLB", polygonCount: 0, uri: "ipfs://placeholder" }],
     note: "reference stub - replace the callSubnet port with a real SN17 miner call.",
-    taskType: spec.taskType
+    taskType: spec2.taskType
   });
 }
-var defaultCallSubnet2 = (spec) => Promise.resolve(
-  spec.metadata.demo === GEN404_DEMO_MARKER ? solveGen404Demo() : referencePlaceholder3(spec)
+var defaultCallSubnet2 = (spec2) => Promise.resolve(
+  spec2.metadata.demo === GEN404_DEMO_MARKER ? solveGen404Demo() : referencePlaceholder3(spec2)
 );
 function create404genAdapter(config = {}) {
   return createBittensorSubnetAdapter({
@@ -1497,17 +1767,17 @@ function scoreLiumDemoDeliverable(content) {
   }
   return parsed.artifact === computeLiumDemoArtifact() ? 1 : 0;
 }
-function referencePlaceholder4(spec) {
+function referencePlaceholder4(spec2) {
   return canonicalize({
     job: "lium-sn51-generic",
     status: "completed",
     artifact: null,
     note: "reference stub - replace the runJob port with a real SN51 GPU-rental call.",
-    taskType: spec.taskType
+    taskType: spec2.taskType
   });
 }
-var defaultRunJob = (spec) => Promise.resolve(
-  spec.metadata.demo === LIUM_DEMO_MARKER ? solveLiumDemo() : referencePlaceholder4(spec)
+var defaultRunJob = (spec2) => Promise.resolve(
+  spec2.metadata.demo === LIUM_DEMO_MARKER ? solveLiumDemo() : referencePlaceholder4(spec2)
 );
 function createLiumAdapter(config = {}) {
   return createBittensorSubnetAdapter({
@@ -1616,17 +1886,17 @@ function scoreAkashDemoDeliverable(content) {
   }
   return parsed.artifact === computeAkashDemoArtifact() ? 1 : 0;
 }
-function referencePlaceholder5(spec) {
+function referencePlaceholder5(spec2) {
   return canonicalize({
     job: "akash-generic",
     status: "completed",
     artifact: null,
     note: "reference stub - replace the runDeployment port with a real Akash deployment call.",
-    taskType: spec.taskType
+    taskType: spec2.taskType
   });
 }
-var defaultRunDeployment = (spec) => Promise.resolve(
-  spec.metadata.demo === AKASH_DEMO_MARKER ? solveAkashDemo() : referencePlaceholder5(spec)
+var defaultRunDeployment = (spec2) => Promise.resolve(
+  spec2.metadata.demo === AKASH_DEMO_MARKER ? solveAkashDemo() : referencePlaceholder5(spec2)
 );
 function createAkashAdapter(config = {}) {
   const capabilities = config.capabilities ?? [...AKASH_CAPABILITIES];
@@ -1639,9 +1909,9 @@ function createAkashAdapter(config = {}) {
     id: AKASH_ADAPTER_ID,
     capabilities,
     healthCheck: checkHealth,
-    async execute(spec) {
+    async execute(spec2) {
       const budgetAkt = await swap(taskBudgetMicroUsdc);
-      const content = await runDeployment(spec, budgetAkt);
+      const content = await runDeployment(spec2, budgetAkt);
       const contentHash = sha256Hex4(content);
       const proofUri = await pin(content);
       return {
@@ -1758,17 +2028,17 @@ function scoreRenderDemoDeliverable(content) {
   }
   return parsed.frame === computeRenderDemoArtifact() ? 1 : 0;
 }
-function referencePlaceholder6(spec) {
+function referencePlaceholder6(spec2) {
   return canonicalize({
     job: "render-generic",
     status: "completed",
     frame: null,
     note: "reference stub - replace the runJob port with a real Render Network job submission.",
-    taskType: spec.taskType
+    taskType: spec2.taskType
   });
 }
-var defaultRunJob2 = (spec) => Promise.resolve(
-  spec.metadata.demo === RENDER_DEMO_MARKER ? solveRenderDemo() : referencePlaceholder6(spec)
+var defaultRunJob2 = (spec2) => Promise.resolve(
+  spec2.metadata.demo === RENDER_DEMO_MARKER ? solveRenderDemo() : referencePlaceholder6(spec2)
 );
 function createRenderAdapter(config = {}) {
   const service = config.service ?? DEFAULT_SERVICE2;
@@ -1782,9 +2052,9 @@ function createRenderAdapter(config = {}) {
     id: service,
     capabilities,
     healthCheck: checkHealth,
-    async execute(spec) {
+    async execute(spec2) {
       const budgetRender = await swap(taskBudgetMicroUsdc);
-      const content = await runJob(spec, budgetRender);
+      const content = await runJob(spec2, budgetRender);
       const contentHash = sha256Hex5(content);
       const proofUri = await pin(content);
       return {
@@ -1811,15 +2081,15 @@ function sha256Hex6(content) {
 var LCG_MULT = 1103515245n;
 var LCG_INC = 12345n;
 var LCG_MOD = 1n << 31n;
-function readComputeParams(spec) {
-  const rawSeed = spec.metadata.seed;
-  const rawSteps = spec.metadata.steps;
+function readComputeParams(spec2) {
+  const rawSeed = spec2.metadata.seed;
+  const rawSteps = spec2.metadata.steps;
   const seed = typeof rawSeed === "number" && Number.isInteger(rawSeed) ? rawSeed : GENSYN_DEMO_SEED;
   const steps = typeof rawSteps === "number" && Number.isInteger(rawSteps) && rawSteps > 0 ? rawSteps : GENSYN_DEMO_STEPS;
   return { seed, steps };
 }
-var reproduceGensynCompute = (spec) => {
-  const { seed, steps } = readComputeParams(spec);
+var reproduceGensynCompute = (spec2) => {
+  const { seed, steps } = readComputeParams(spec2);
   const states = [];
   let x = BigInt(seed) % LCG_MOD;
   if (x < 0n) {
@@ -1841,10 +2111,10 @@ function commitmentOf(base) {
     )
   );
 }
-function buildReeProof(spec, exec, content) {
+function buildReeProof(spec2, exec, content) {
   const base = {
     scheme: GENSYN_REE_SCHEME,
-    specHash: sha256Hex6(canonicalize(spec)),
+    specHash: sha256Hex6(canonicalize(spec2)),
     outputHash: sha256Hex6(content),
     steps: exec.steps,
     transcriptHash: sha256Hex6(canonicalize(exec.states))
@@ -1951,11 +2221,11 @@ function createGensynAdapter(config = {}) {
     id: GENSYN_ADAPTER_ID,
     capabilities,
     healthCheck: checkHealth,
-    async execute(spec) {
-      const exec = runCompute(spec);
+    async execute(spec2) {
+      const exec = runCompute(spec2);
       const content = gensynDeliverable(exec);
       const contentHash = sha256Hex6(content);
-      const proof = buildReeProof(spec, exec, content);
+      const proof = buildReeProof(spec2, exec, content);
       const proofUri = await pin(content);
       return {
         content,
@@ -2130,21 +2400,21 @@ function solveZkmlDemo() {
     output: { label: "cat", confidence: 0.98 }
   });
 }
-function referencePlaceholderOutput(spec) {
+function referencePlaceholderOutput(spec2) {
   return {
     content: canonicalize({
       note: "reference stub - replace the runInference port with a real zk-verified inference call.",
-      taskType: spec.taskType
+      taskType: spec2.taskType
     }),
     modelCommitment: sha256Hex7("zkml-reference-stub-model"),
-    inputCommitment: sha256Hex7(canonicalize(spec))
+    inputCommitment: sha256Hex7(canonicalize(spec2))
   };
 }
-var defaultRunInference = (spec) => spec.metadata.demo === ZKML_DEMO_MARKER ? {
+var defaultRunInference = (spec2) => spec2.metadata.demo === ZKML_DEMO_MARKER ? {
   content: solveZkmlDemo(),
   modelCommitment: DEMO_MODEL_COMMITMENT,
   inputCommitment: DEMO_INPUT_COMMITMENT
-} : referencePlaceholderOutput(spec);
+} : referencePlaceholderOutput(spec2);
 function createZkmlAdapter(config = {}) {
   const id = config.id ?? ZKML_ADAPTER_ID;
   const capabilities = config.capabilities ?? [...ZKML_CAPABILITIES];
@@ -2159,10 +2429,10 @@ function createZkmlAdapter(config = {}) {
   return {
     id,
     capabilities,
-    async execute(spec) {
-      const output = await runInference(spec);
+    async execute(spec2) {
+      const output = await runInference(spec2);
       const contentHash = sha256Hex7(output.content);
-      const proof = await prove({ spec, output, outputHash: contentHash });
+      const proof = await prove({ spec: spec2, output, outputHash: contentHash });
       const proofUri = await pin(proof);
       return {
         content: output.content,
@@ -2190,6 +2460,7 @@ function createZkmlAdapter(config = {}) {
   ApiClient,
   ENABLED_RAILS,
   Escro,
+  EscroConfirmError,
   EscroError,
   EscroRailNotEnabledError,
   EscrowNotFoundError,