@escro/sdk 0.3.0 → 0.4.0

package/README.md

@@ -15,8 +15,9 @@ import { Escro, EscrowState } from "@escro/sdk";
 import { Keypair } from "@solana/web3.js";
 
 const client = new Escro({
+  cluster: "devnet",
   rpcUrl: "https://api.devnet.solana.com",
-  apiUrl: "https://api.escro.ai",
+  apiUrl: "https://api-devnet.escro.ai",
   wallet: Keypair.fromSecretKey(/* ... */),
 });
 
@@ -43,22 +44,13 @@ await client.cancelEscrow(escrowPda);  // only if FUNDED, before worker claims
 
 ## API
 
-| Method | Role | Description |
-|---|---|---|
-| `createEscrow(params)` | Buyer | Create + fund escrow atomically |
-| `releasePayment(address)` | Buyer | Approve payment to worker |
-| `cancelEscrow(address)` | Buyer | Cancel funded escrow, full refund |
-| `claimTask(address)` | Worker | Claim an assigned task |
-| `submitDeliverable(address, params)` | Worker | Submit work for review |
-| `getMyTasks(state?, options?)` | Worker | List assigned tasks (paginated) |
-| `getEscrow(address, options?)` | Both | Fetch escrow by PDA address |
-| `raiseDispute(address, params)` | Both | Escalate to dispute |
+Every method, its parameters and its errors are in the generated
+[SDK reference](https://escro.ai/docs/sdk-reference).
 
 ## Docs
 
-- [Buyer Bot Guide](https://escro.ai/docs/buyer-bot)
-- [Worker Bot Guide](https://escro.ai/docs/worker-bot)
-- [SDK Reference](https://escro.ai/docs/sdk-reference)
+- [Buyer Bot guide](https://escro.ai/docs/buyer-bot)
+- [Worker Bot guide](https://escro.ai/docs/worker-bot)
 
 ## License
 

package/dist/index.cjs

@@ -134,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");
@@ -153,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;
@@ -186,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");
 }
@@ -300,8 +310,12 @@ var EscrowTimeoutError = class extends EscroError {
   }
 };
 var EscroConfirmError = class extends EscroError {
-  constructor(address, signature, code, message) {
-    super(`Confirm failed for escrow ${address} (signature ${signature}): ${message}`, code);
+  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";
@@ -491,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`;
@@ -500,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.
@@ -607,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);
 }
@@ -616,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;
@@ -649,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);
@@ -697,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();
@@ -711,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,
@@ -733,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 },
@@ -751,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));
@@ -776,6 +850,9 @@ var RETRYABLE_CONFIRM_CODES = [
 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);
@@ -794,7 +871,7 @@ 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 ────────────────────────────────────────────────────────────────
@@ -813,12 +890,27 @@ var Escro = class {
   /**
    * 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`);
@@ -826,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,
@@ -840,10 +932,17 @@ 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
@@ -852,6 +951,8 @@ var Escro = class {
    * @returns Solana transaction signature.
    */
   async raiseDispute(address, params) {
+    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");
     }
@@ -1031,21 +1132,40 @@ var Escro = class {
    * 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 this.api.confirm(address, signature, opts.evidence);
+        return await record();
       } catch (err) {
         if (err instanceof EscroError) {
-          if (!isRetryableConfirmCode(err.code)) {
-            throw new EscroConfirmError(address, signature, err.code, err.message);
+          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";
@@ -1053,7 +1173,7 @@ var Escro = class {
         }
       }
       if (Date.now() + wait > deadline) {
-        throw new EscroConfirmError(address, signature, code, message);
+        throw new EscroConfirmError(address, signature, code, message, retryAfterMs2);
       }
       await sleep2(wait);
       delay = Math.min(delay * 2, CONFIRM_MAX_DELAY_MS);