@escro/sdk 0.4.0 → 0.4.2

package/dist/index.d.cts

@@ -1,5 +1,7 @@
 import { Keypair } from '@solana/web3.js';
 
+type SolanaCluster = "devnet" | "mainnet";
+
 /**
  * All possible lifecycle states of an AgentEscrow account on-chain.
  *
@@ -132,6 +134,10 @@ interface ProtocolStatsFigures {
 }
 /** Protocol-wide aggregate statistics: public, unauthenticated. */
 interface ProtocolStats extends ProtocolStatsFigures {
+    /** The Solana cluster this API serves (its `CLUSTER`). */
+    cluster: SolanaCluster;
+    /** That cluster's one USDC mint (`getUsdcMint`): every figure here is in this token. */
+    usdcMint: string;
     /**
      * Escro-operated fleet figures (ARCHITECTURE section 9): the same fields over
      * escrows whose buyer and assigned worker are both in the API's operator
@@ -378,8 +384,6 @@ interface ReviewPolicy {
     evaluate(deliverable: ReviewDeliverable): ReviewResult | Promise<ReviewResult>;
 }
 
-type SolanaCluster = "devnet" | "mainnet";
-
 /** Dispute tally with its outcome split (from the wallet's perspective). */
 interface DisputeRecord {
     /** Total disputes this wallet was party to (raised by either side). */
@@ -747,9 +751,11 @@ declare class Escro {
      * {@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).
+     * 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 }`.
      */

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 import { Keypair } from '@solana/web3.js';
 
+type SolanaCluster = "devnet" | "mainnet";
+
 /**
  * All possible lifecycle states of an AgentEscrow account on-chain.
  *
@@ -132,6 +134,10 @@ interface ProtocolStatsFigures {
 }
 /** Protocol-wide aggregate statistics: public, unauthenticated. */
 interface ProtocolStats extends ProtocolStatsFigures {
+    /** The Solana cluster this API serves (its `CLUSTER`). */
+    cluster: SolanaCluster;
+    /** That cluster's one USDC mint (`getUsdcMint`): every figure here is in this token. */
+    usdcMint: string;
     /**
      * Escro-operated fleet figures (ARCHITECTURE section 9): the same fields over
      * escrows whose buyer and assigned worker are both in the API's operator
@@ -378,8 +384,6 @@ interface ReviewPolicy {
     evaluate(deliverable: ReviewDeliverable): ReviewResult | Promise<ReviewResult>;
 }
 
-type SolanaCluster = "devnet" | "mainnet";
-
 /** Dispute tally with its outcome split (from the wallet's perspective). */
 interface DisputeRecord {
     /** Total disputes this wallet was party to (raised by either side). */
@@ -747,9 +751,11 @@ declare class Escro {
      * {@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).
+     * 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 }`.
      */

package/dist/index.js

@@ -7,10 +7,12 @@ import { Connection as Connection2, PublicKey as PublicKey3 } from "@solana/web3
 
 // ../shared/dist/index.js
 import { createHash } from "crypto";
+import { createHash as createHash2 } from "crypto";
 import nacl from "tweetnacl";
 import bs58 from "bs58";
 import nacl2 from "tweetnacl";
 import bs582 from "bs58";
+import bs583 from "bs58";
 var EscrowState = /* @__PURE__ */ ((EscrowState2) => {
   EscrowState2["CREATED"] = "CREATED";
   EscrowState2["FUNDED"] = "FUNDED";
@@ -57,6 +59,33 @@ function canonicalize(value) {
   }
   return JSON.stringify(value);
 }
+var SPEC_KEYS = [
+  "version",
+  "taskType",
+  "description",
+  "acceptanceCriteria",
+  "deliverableFormat",
+  "metadata"
+];
+var CRITERION_KEYS = ["id", "description", "weight", "required"];
+var FORMAT_KEYS = ["type", "schema", "mimeType", "maxSizeBytes", "language"];
+function pick(value, keys) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return value;
+  const source = value;
+  return Object.fromEntries(keys.filter((k) => k in source).map((k) => [k, source[k]]));
+}
+function normalizeTaskSpec(spec2) {
+  const top = pick(spec2, SPEC_KEYS);
+  const criteria = top.acceptanceCriteria;
+  return {
+    ...top,
+    acceptanceCriteria: Array.isArray(criteria) ? criteria.map((c) => pick(c, CRITERION_KEYS)) : criteria,
+    deliverableFormat: pick(top.deliverableFormat, FORMAT_KEYS)
+  };
+}
+function computeTaskSpecHash(spec2) {
+  return createHash("sha256").update(canonicalize(normalizeTaskSpec(spec2)), "utf8").digest("hex");
+}
 function disputeReasonError(reason) {
   if (reason.length === 0) return "reason must not be empty";
   const bytes = new TextEncoder().encode(reason).length;
@@ -65,8 +94,16 @@ function disputeReasonError(reason) {
   }
   return null;
 }
+var SAFE_URL_SCHEMES = ["http:", "https:", "ipfs:", "ar:"];
+function isSafeUrl(value) {
+  try {
+    return SAFE_URL_SCHEMES.includes(new URL(value).protocol);
+  } catch {
+    return false;
+  }
+}
 function hashBody(rawBody) {
-  return createHash("sha256").update(rawBody, "utf8").digest("hex");
+  return createHash2("sha256").update(rawBody, "utf8").digest("hex");
 }
 function buildSignedMessage(timestamp, method, fullPath, bodyHash) {
   return `escro:${String(timestamp)}:${method}:${fullPath}:${bodyHash}`;
@@ -110,6 +147,18 @@ function verifyBotDescriptorSignature(descriptor) {
     return false;
   }
 }
+var ESCROW_INSTRUCTION_NAMES = [
+  "create_escrow",
+  "claim_task",
+  "submit_deliverable",
+  "raise_dispute",
+  "cancel_escrow",
+  "release_payment",
+  "timeout_release",
+  "refund_buyer",
+  "arbitration_release",
+  "arbitration_refund"
+];
 function spec(discriminator, escrowAccountIndex, cause) {
   return {
     discriminator: Uint8Array.from(discriminator),
@@ -130,6 +179,66 @@ var ESCROW_INSTRUCTIONS = {
   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")
 };
+function escrowInstructionName(data) {
+  for (const name of ESCROW_INSTRUCTION_NAMES) {
+    const disc2 = ESCROW_INSTRUCTIONS[name].discriminator;
+    if (disc2.every((b, i) => data[i] === b)) return name;
+  }
+  return null;
+}
+var Reader = class {
+  constructor(buf) {
+    __publicField(this, "buf");
+    __publicField(this, "offset", 8);
+    this.buf = buf;
+  }
+  take(n) {
+    if (this.offset + n > this.buf.length) {
+      throw new Error(
+        `instruction data truncated: need ${String(n)} bytes at offset ${String(this.offset)}, have ${String(this.buf.length)}`
+      );
+    }
+    const out = this.buf.subarray(this.offset, this.offset + n);
+    this.offset += n;
+    return out;
+  }
+  u8() {
+    return this.take(1).readUInt8(0);
+  }
+  u64() {
+    return this.take(8).readBigUInt64LE(0);
+  }
+  i64() {
+    return this.take(8).readBigInt64LE(0);
+  }
+  string() {
+    const len = this.take(4).readUInt32LE(0);
+    return this.take(len).toString("utf8");
+  }
+  option(read) {
+    return this.u8() === 0 ? null : read();
+  }
+  bytes(n) {
+    return this.take(n);
+  }
+};
+function decodeCreateEscrowArgs(data) {
+  const r = new Reader(Buffer.from(data));
+  return {
+    taskId: r.string(),
+    amount: r.u64(),
+    deadline: r.i64(),
+    specHash: r.string(),
+    assignedWorker: r.option(() => bs583.encode(r.bytes(32)))
+  };
+}
+function decodeSubmitDeliverableArgs(data) {
+  const r = new Reader(Buffer.from(data));
+  return { deliverableHash: r.string(), proofUri: r.option(() => r.string()) };
+}
+function decodeRaiseDisputeArgs(data) {
+  return { reason: new Reader(Buffer.from(data)).string() };
+}
 
 // src/payments.ts
 var RAILS = ["escrow", "x402"];
@@ -504,9 +613,7 @@ async function pollUntil(address, fetcher, predicate, timeoutMs = MS_24_H) {
 }
 
 // src/solana.ts
-import { createHash as createHash2 } from "crypto";
 import {
-  ComputeBudgetProgram,
   PublicKey as PublicKey2,
   Transaction,
   TransactionInstruction
@@ -520,8 +627,14 @@ import {
 
 // ../shared/dist/solana.js
 import { PublicKey } from "@solana/web3.js";
-import bs583 from "bs58";
+import bs584 from "bs58";
 var utf8 = (s) => new TextEncoder().encode(s);
+function deriveEscrowPda(programId, buyer, taskId) {
+  return PublicKey.findProgramAddressSync(
+    [utf8("escrow"), buyer.toBytes(), utf8(taskId)],
+    programId
+  )[0];
+}
 function findPlatformConfigPda(programId) {
   return PublicKey.findProgramAddressSync([utf8("config")], programId);
 }
@@ -558,7 +671,7 @@ function decodePlatformConfig(data) {
     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));
+  const key = (at) => bs584.encode(data.subarray(at, at + 32));
   return {
     version: byte(L.version),
     feeBps: byte(L.fee_bps) | byte(L.fee_bps + 1) << 8,
@@ -570,10 +683,6 @@ function decodePlatformConfig(data) {
 }
 
 // src/solana.ts
-function disc(name) {
-  return Buffer.from(createHash2("sha256").update(`global:${name}`).digest()).subarray(0, 8);
-}
-var DISC_RELEASE_PAYMENT = disc("release_payment");
 function resolveProgramId(cluster) {
   const id = getProgramId(cluster);
   assertProgramIdNotPlaceholder(id, cluster);
@@ -583,8 +692,7 @@ function allowedProgramIds(programId) {
   return /* @__PURE__ */ new Set([
     programId.toBase58(),
     TOKEN_PROGRAM_ID.toBase58(),
-    ASSOCIATED_TOKEN_PROGRAM_ID.toBase58(),
-    ComputeBudgetProgram.programId.toBase58()
+    ASSOCIATED_TOKEN_PROGRAM_ID.toBase58()
   ]);
 }
 var MAX_INSTRUCTIONS = 6;
@@ -622,6 +730,12 @@ async function fetchPlatformConfig(connection, cluster) {
   }
   return { mint: new PublicKey2(config.usdcMint), treasury: new PublicKey2(config.treasury) };
 }
+function refuse(reason) {
+  throw new EscroError(
+    `Refusing to sign a server-built transaction: ${reason}`,
+    "UNEXPECTED_TRANSACTION"
+  );
+}
 function validateTransaction(tx, cluster) {
   const programId = resolveProgramId(cluster);
   const allowed = allowedProgramIds(programId);
@@ -629,36 +743,103 @@ function validateTransaction(tx, cluster) {
   for (const ix of tx.instructions) {
     const id = ix.programId.toBase58();
     if (!allowed.has(id)) {
-      throw new Error(
-        `Unexpected program in transaction: ${id}. Allowed: ${[...allowed].join(", ")}`
-      );
+      refuse(`Unexpected program in transaction: ${id}. Allowed: ${[...allowed].join(", ")}`);
     }
     if (id === tokenProgram) {
       const tag = ix.data.length > 0 ? ix.data[0] : void 0;
       if (tag !== void 0 && FORBIDDEN_TOKEN_IX_TAGS.has(tag)) {
-        throw new Error(
-          `Refusing to sign a fund-moving SPL Token instruction (tag ${String(tag)}) in a server-built transaction. Escro never requires the wallet to directly sign a token transfer/approve/burn/close; all token movement is a CPI inside the escro program.`
+        throw new EscroError(
+          `Refusing to sign a fund-moving SPL Token instruction (tag ${String(tag)}) in a server-built transaction`,
+          "UNEXPECTED_TRANSACTION"
         );
       }
     }
   }
   if (tx.instructions.length > MAX_INSTRUCTIONS) {
-    throw new Error(
+    refuse(
       `Too many instructions (${String(tx.instructions.length)}). Max allowed: ${String(MAX_INSTRUCTIONS)}`
     );
   }
 }
-async function signAndSend(base64Tx, wallet, connection, cluster) {
-  const buf = Buffer.from(base64Tx, "base64");
-  const tx = Transaction.from(buf);
+var ATA_CREATE_IDEMPOTENT = 1;
+function verifyServerTransaction(tx, cluster, wallet, expected) {
   validateTransaction(tx, cluster);
+  const programId = resolveProgramId(cluster);
+  if (!tx.feePayer?.equals(wallet)) refuse("the fee payer is not the wallet");
+  const escro = tx.instructions.filter((ix2) => ix2.programId.equals(programId));
+  const others = tx.instructions.filter((ix2) => !ix2.programId.equals(programId));
+  for (const ix2 of others) {
+    const ataCreate = expected.name === "release_payment" && ix2.programId.equals(ASSOCIATED_TOKEN_PROGRAM_ID) && ix2.data.length === 1 && ix2.data[0] === ATA_CREATE_IDEMPOTENT;
+    if (!ataCreate) refuse(`unexpected ${ix2.programId.toBase58()} instruction`);
+  }
+  if (escro.length !== 1) refuse(`${String(escro.length)} escro instructions, expected 1`);
+  const [ix] = escro;
+  if (ix === void 0) refuse("no escro instruction");
+  const name = escrowInstructionName(ix.data);
+  if (name !== expected.name)
+    refuse(`${name ?? "an unknown instruction"}, expected ${expected.name}`);
+  const spec2 = ESCROW_INSTRUCTIONS[name];
+  const actor = ix.keys[spec2.signerAccountIndex];
+  if (actor === void 0 || !actor.pubkey.equals(wallet) || !actor.isSigner) {
+    refuse("the acting signer is not the wallet");
+  }
+  if (ix.keys[spec2.escrowAccountIndex]?.pubkey.toBase58() !== expected.escrowPda) {
+    refuse(`the escrow is not ${expected.escrowPda}`);
+  }
+  try {
+    switch (expected.name) {
+      case "create_escrow": {
+        const args = decodeCreateEscrowArgs(ix.data);
+        if (args.taskId !== expected.taskId) refuse("the task id differs");
+        if (deriveEscrowPda(programId, wallet, args.taskId).toBase58() !== expected.escrowPda) {
+          refuse("the escrow is not derived from the wallet and task id");
+        }
+        if (args.amount !== expected.amount) refuse("the amount differs");
+        if (args.deadline !== expected.deadline) refuse("the deadline differs");
+        if (args.specHash !== expected.specHash) refuse("the spec hash differs");
+        if (args.assignedWorker !== expected.assignedWorker) refuse("the assigned worker differs");
+        break;
+      }
+      case "submit_deliverable": {
+        const args = decodeSubmitDeliverableArgs(ix.data);
+        if (args.deliverableHash !== expected.deliverableHash)
+          refuse("the deliverable hash differs");
+        if (args.proofUri !== expected.proofUri) refuse("the proof URI differs");
+        break;
+      }
+      case "raise_dispute":
+        if (decodeRaiseDisputeArgs(ix.data).reason !== expected.reason)
+          refuse("the reason differs");
+        break;
+      default:
+        if (ix.data.length !== ESCROW_INSTRUCTIONS[name].discriminator.length) {
+          refuse(`${name} carries unexpected arguments`);
+        }
+    }
+  } catch (err) {
+    if (err instanceof EscroError) throw err;
+    refuse(`malformed ${name} arguments`);
+  }
+}
+async function signAndSend(base64Tx, wallet, connection, cluster, expected) {
+  const tx = Transaction.from(Buffer.from(base64Tx, "base64"));
+  verifyServerTransaction(tx, cluster, wallet.publicKey, expected);
   tx.partialSign(wallet);
   const raw = tx.serialize();
   const { blockhash, lastValidBlockHeight } = await connection.getLatestBlockhash("confirmed");
   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) {
@@ -701,7 +882,7 @@ async function buildReleasePaymentTx(params) {
       { pubkey: TOKEN_PROGRAM_ID, isSigner: false, isWritable: false },
       { pubkey: ASSOCIATED_TOKEN_PROGRAM_ID, isSigner: false, isWritable: false }
     ],
-    data: DISC_RELEASE_PAYMENT
+    data: Buffer.from(ESCROW_INSTRUCTIONS.release_payment.discriminator)
   });
   const { blockhash } = await connection.getLatestBlockhash("confirmed");
   const tx = new Transaction();
@@ -732,14 +913,6 @@ function isRetryableConfirmCode(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) {
@@ -762,7 +935,15 @@ var Escro = class {
    */
   async createEscrow(params) {
     const { escrowId, escrowPda, unsignedTx } = await this.api.createEscrow(params);
-    const signature = await this.send(unsignedTx);
+    const signature = await this.send(unsignedTx, {
+      name: "create_escrow",
+      escrowPda,
+      taskId: escrowId,
+      amount: BigInt(params.amountUsdc),
+      deadline: BigInt(params.deadlineUnix),
+      specHash: computeTaskSpecHash(params.taskSpec),
+      assignedWorker: params.assignedWorker
+    });
     await this.confirm(escrowPda, signature);
     return { escrowId, escrowPda, signature };
   }
@@ -783,9 +964,11 @@ var Escro = class {
    * {@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).
+   * 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 }`.
    */
@@ -804,12 +987,7 @@ var Escro = class {
       connection: this.connection,
       cluster: this.cluster
     });
-    const signature = await signAndSend(
-      unsignedTx,
-      this.options.wallet,
-      this.connection,
-      this.cluster
-    );
+    const signature = await this.send(unsignedTx, { name: "release_payment", escrowPda: address });
     try {
       await this.retryRecord(
         address,
@@ -832,11 +1010,18 @@ var Escro = class {
   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");
+    if (params.evidence !== void 0 && !isSafeUrl(params.evidence)) {
+      throw new EscroError(
+        `evidence must be an http(s), ipfs or ar URL: ${params.evidence}`,
+        "VALIDATION_ERROR"
+      );
     }
     const { unsignedTx } = await this.api.raiseDispute(address, { reason: params.reason });
-    const signature = await this.send(unsignedTx);
+    const signature = await this.send(unsignedTx, {
+      name: "raise_dispute",
+      escrowPda: address,
+      reason: params.reason
+    });
     await this.confirm(address, signature, {
       ...params.evidence !== void 0 && { evidence: params.evidence }
     });
@@ -851,7 +1036,7 @@ var Escro = class {
    */
   async cancelEscrow(address) {
     const { unsignedTx } = await this.api.cancelEscrow(address);
-    return this.sendAndConfirm(address, unsignedTx);
+    return this.sendAndConfirm(address, unsignedTx, { name: "cancel_escrow", escrowPda: address });
   }
   // ── Payments (dual-path; x402 reserved) ───────────────────────────────────────
   /**
@@ -882,7 +1067,7 @@ var Escro = class {
    */
   async claimTask(address) {
     const { unsignedTx } = await this.api.claimTask(address);
-    return this.sendAndConfirm(address, unsignedTx);
+    return this.sendAndConfirm(address, unsignedTx, { name: "claim_task", escrowPda: address });
   }
   /**
    * Submit a deliverable for the buyer to review. Worker must be the wallet.
@@ -892,7 +1077,12 @@ var Escro = class {
    */
   async submitDeliverable(address, params) {
     const { unsignedTx } = await this.api.submitDeliverable(address, params);
-    return this.sendAndConfirm(address, unsignedTx);
+    return this.sendAndConfirm(address, unsignedTx, {
+      name: "submit_deliverable",
+      escrowPda: address,
+      deliverableHash: params.contentHash,
+      proofUri: params.proofUri ?? null
+    });
   }
   /**
    * List tasks assigned to the wallet's public key.
@@ -1058,11 +1248,11 @@ var Escro = class {
       delay = Math.min(delay * 2, CONFIRM_MAX_DELAY_MS);
     }
   }
-  send(unsignedTx) {
-    return signAndSend(unsignedTx, this.options.wallet, this.connection, this.cluster);
+  send(unsignedTx, expected) {
+    return signAndSend(unsignedTx, this.options.wallet, this.connection, this.cluster, expected);
   }
-  async sendAndConfirm(address, unsignedTx) {
-    const signature = await this.send(unsignedTx);
+  async sendAndConfirm(address, unsignedTx, expected) {
+    const signature = await this.send(unsignedTx, expected);
     await this.confirm(address, signature);
     return signature;
   }