@escro/sdk 0.3.0 → 0.4.1

package/dist/index.js

@@ -3,7 +3,7 @@ var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { en
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
 
 // src/client.ts
-import { Connection as Connection2, PublicKey as PublicKey2 } from "@solana/web3.js";
+import { Connection as Connection2, PublicKey as PublicKey3 } from "@solana/web3.js";
 
 // ../shared/dist/index.js
 import { createHash } from "crypto";
@@ -22,20 +22,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;
@@ -55,6 +45,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 createHash("sha256").update(rawBody, "utf8").digest("hex");
 }
@@ -169,8 +179,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";
@@ -360,8 +374,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`;
@@ -369,7 +386,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.
@@ -478,7 +507,7 @@ async function pollUntil(address, fetcher, predicate, timeoutMs = MS_24_H) {
 import { createHash as createHash2 } from "crypto";
 import {
   ComputeBudgetProgram,
-  PublicKey,
+  PublicKey as PublicKey2,
   Transaction,
   TransactionInstruction
 } from "@solana/web3.js";
@@ -488,6 +517,59 @@ import {
   getAssociatedTokenAddressSync,
   createAssociatedTokenAccountIdempotentInstruction
 } from "@solana/spl-token";
+
+// ../shared/dist/solana.js
+import { PublicKey } from "@solana/web3.js";
+import bs583 from "bs58";
+var utf8 = (s) => new TextEncoder().encode(s);
+function findPlatformConfigPda(programId) {
+  return 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) => bs583.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(createHash2("sha256").update(`global:${name}`).digest()).subarray(0, 8);
 }
@@ -495,7 +577,7 @@ var DISC_RELEASE_PAYMENT = disc("release_payment");
 function resolveProgramId(cluster) {
   const id = getProgramId(cluster);
   assertProgramIdNotPlaceholder(id, cluster);
-  return new PublicKey(id);
+  return new PublicKey2(id);
 }
 function allowedProgramIds(programId) {
   return /* @__PURE__ */ new Set([
@@ -528,25 +610,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] = 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 PublicKey(info.data.subarray(MINT_OFFSET, MINT_OFFSET + 32)),
-    treasury: new PublicKey(info.data.subarray(TREASURY_OFFSET, TREASURY_OFFSET + 32))
-  };
+  return { mint: new PublicKey2(config.usdcMint), treasury: new PublicKey2(config.treasury) };
 }
 function validateTransaction(tx, cluster) {
   const programId = resolveProgramId(cluster);
@@ -584,13 +658,22 @@ async function signAndSend(base64Tx, wallet, connection, cluster) {
   const signature = await connection.sendRawTransaction(raw, {
     skipPreflight: false
   });
-  await connection.confirmTransaction({ signature, blockhash, lastValidBlockHeight }, "confirmed");
+  const { value } = await connection.confirmTransaction(
+    { signature, blockhash, lastValidBlockHeight },
+    "confirmed"
+  );
+  if (value.err !== null) {
+    throw new EscroError(
+      `Transaction ${signature} failed at execution: ${JSON.stringify(value.err)}`,
+      "TX_FAILED"
+    );
+  }
   return signature;
 }
 async function buildReleasePaymentTx(params) {
   const { buyer, escrowPda, worker, mint, treasury, connection, cluster } = params;
   const programId = resolveProgramId(cluster);
-  const [platformConfig] = PublicKey.findProgramAddressSync([Buffer.from("config")], programId);
+  const platformConfig = derivePlatformConfigPda(programId);
   const vault = getAssociatedTokenAddressSync(
     mint,
     escrowPda,
@@ -655,6 +738,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);
@@ -692,12 +778,29 @@ 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
+   * failed record 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). A release that failed at
+   * execution on chain throws an {@link EscroError} with code `TX_FAILED`, and the API is
+   * never asked to record 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`);
@@ -705,8 +808,8 @@ var Escro = class {
     const { treasury, mint } = await fetchPlatformConfig(this.connection, this.cluster);
     const unsignedTx = await buildReleasePaymentTx({
       buyer: this.options.wallet.publicKey,
-      escrowPda: new PublicKey2(address),
-      worker: new PublicKey2(escrow.taker),
+      escrowPda: new PublicKey3(address),
+      worker: new PublicKey3(escrow.taker),
       mint,
       treasury,
       connection: this.connection,
@@ -719,10 +822,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
@@ -731,6 +841,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");
     }
@@ -910,21 +1022,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";
@@ -932,7 +1063,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);