@escro/sdk 0.4.1 → 0.4.2

package/dist/index.cjs

@@ -138,10 +138,12 @@ var import_web33 = require("@solana/web3.js");
 
 // ../shared/dist/index.js
 var import_crypto = require("crypto");
+var import_crypto2 = require("crypto");
 var import_tweetnacl = __toESM(require("tweetnacl"), 1);
 var import_bs58 = __toESM(require("bs58"), 1);
 var import_tweetnacl2 = __toESM(require("tweetnacl"), 1);
 var import_bs582 = __toESM(require("bs58"), 1);
+var import_bs583 = __toESM(require("bs58"), 1);
 var EscrowState = /* @__PURE__ */ ((EscrowState2) => {
   EscrowState2["CREATED"] = "CREATED";
   EscrowState2["FUNDED"] = "FUNDED";
@@ -188,6 +190,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 (0, import_crypto.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;
@@ -196,8 +225,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 (0, import_crypto.createHash)("sha256").update(rawBody, "utf8").digest("hex");
+  return (0, import_crypto2.createHash)("sha256").update(rawBody, "utf8").digest("hex");
 }
 function buildSignedMessage(timestamp, method, fullPath, bodyHash) {
   return `escro:${String(timestamp)}:${method}:${fullPath}:${bodyHash}`;
@@ -241,6 +278,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),
@@ -261,6 +310,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(() => import_bs583.default.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"];
@@ -635,14 +744,19 @@ async function pollUntil(address, fetcher, predicate, timeoutMs = MS_24_H) {
 }
 
 // src/solana.ts
-var import_node_crypto = require("crypto");
 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 import_bs584 = __toESM(require("bs58"), 1);
 var utf8 = (s) => new TextEncoder().encode(s);
+function deriveEscrowPda(programId, buyer, taskId) {
+  return import_web3.PublicKey.findProgramAddressSync(
+    [utf8("escrow"), buyer.toBytes(), utf8(taskId)],
+    programId
+  )[0];
+}
 function findPlatformConfigPda(programId) {
   return import_web3.PublicKey.findProgramAddressSync([utf8("config")], programId);
 }
@@ -679,7 +793,7 @@ function decodePlatformConfig(data) {
     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));
+  const key = (at) => import_bs584.default.encode(data.subarray(at, at + 32));
   return {
     version: byte(L.version),
     feeBps: byte(L.fee_bps) | byte(L.fee_bps + 1) << 8,
@@ -691,10 +805,6 @@ function decodePlatformConfig(data) {
 }
 
 // src/solana.ts
-function disc(name) {
-  return Buffer.from((0, import_node_crypto.createHash)("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);
@@ -704,8 +814,7 @@ 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_web32.ComputeBudgetProgram.programId.toBase58()
+    import_spl_token.ASSOCIATED_TOKEN_PROGRAM_ID.toBase58()
   ]);
 }
 var MAX_INSTRUCTIONS = 6;
@@ -743,6 +852,12 @@ async function fetchPlatformConfig(connection, cluster) {
   }
   return { mint: new import_web32.PublicKey(config.usdcMint), treasury: new import_web32.PublicKey(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);
@@ -750,29 +865,87 @@ 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 = import_web32.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(import_spl_token.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 = import_web32.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");
@@ -831,7 +1004,7 @@ async function buildReleasePaymentTx(params) {
       { pubkey: import_spl_token.TOKEN_PROGRAM_ID, isSigner: false, isWritable: false },
       { pubkey: import_spl_token.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 import_web32.Transaction();
@@ -862,14 +1035,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) {
@@ -892,7 +1057,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 };
   }
@@ -936,12 +1109,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,
@@ -964,11 +1132,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 }
     });
@@ -983,7 +1158,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) ───────────────────────────────────────
   /**
@@ -1014,7 +1189,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.
@@ -1024,7 +1199,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.
@@ -1190,11 +1370,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;
   }
@@ -1228,7 +1408,7 @@ function serviceResultToSubmitParams(result) {
 }
 
 // src/adapter-contract.ts
-var import_crypto2 = require("crypto");
+var import_crypto3 = require("crypto");
 var AdapterContractError = class extends EscroError {
   constructor(adapterId, violations) {
     super(
@@ -1244,7 +1424,7 @@ function errMessage(err) {
   return err instanceof Error ? err.message : String(err);
 }
 function sha256Hex(content) {
-  return (0, import_crypto2.createHash)("sha256").update(content).digest("hex");
+  return (0, import_crypto3.createHash)("sha256").update(content).digest("hex");
 }
 function validateServiceResult(result) {
   if (typeof result !== "object" || result === null) {
@@ -1315,12 +1495,12 @@ async function assertServiceAdapterContract(adapter, options) {
 }
 
 // src/adapters/bittensor/index.ts
-var import_crypto3 = require("crypto");
+var import_crypto4 = require("crypto");
 function tao(amount) {
   return amount;
 }
 function sha256Hex2(content) {
-  return (0, import_crypto3.createHash)("sha256").update(content).digest("hex");
+  return (0, import_crypto4.createHash)("sha256").update(content).digest("hex");
 }
 var REFERENCE_MICRO_USDC_PER_TAO = 3e8;
 var defaultSwap = (microUsdc) => Promise.resolve(tao(microUsdc / REFERENCE_MICRO_USDC_PER_TAO));
@@ -1440,12 +1620,12 @@ function createGradientsAdapter(config = {}) {
 }
 
 // src/adapters/ridges/index.ts
-var import_crypto4 = require("crypto");
+var import_crypto5 = require("crypto");
 var RIDGES_ADAPTER_ID = "ridges";
 var RIDGES_CAPABILITIES = ["code-generation"];
 var DEFAULT_SERVICE = "ridges";
 function sha256Hex3(content) {
-  return (0, import_crypto4.createHash)("sha256").update(content).digest("hex");
+  return (0, import_crypto5.createHash)("sha256").update(content).digest("hex");
 }
 var RIDGES_DEMO_MARKER = "ridges-demo-v1";
 var RIDGES_DEMO_COVERAGE_TARGET = 0.8;
@@ -1803,12 +1983,12 @@ function createLiumAdapter(config = {}) {
 }
 
 // src/adapters/akash/index.ts
-var import_crypto5 = require("crypto");
+var import_crypto6 = require("crypto");
 function akt(amount) {
   return amount;
 }
 function sha256Hex4(content) {
-  return (0, import_crypto5.createHash)("sha256").update(content).digest("hex");
+  return (0, import_crypto6.createHash)("sha256").update(content).digest("hex");
 }
 var AKASH_ADAPTER_ID = "akash";
 var AKASH_CAPABILITIES = ["cloud-compute"];
@@ -1936,7 +2116,7 @@ function createAkashAdapter(config = {}) {
 }
 
 // src/adapters/render/index.ts
-var import_crypto6 = require("crypto");
+var import_crypto7 = require("crypto");
 function renderAmount(amount) {
   return amount;
 }
@@ -1945,7 +2125,7 @@ var RENDER_CAPABILITIES = ["3d-rendering", "video-rendering", "gpu-inference"];
 var DEFAULT_SERVICE2 = "render";
 var DEFAULT_TASK_BUDGET_MICRO_USDC5 = 15e6;
 function sha256Hex5(content) {
-  return (0, import_crypto6.createHash)("sha256").update(content).digest("hex");
+  return (0, import_crypto7.createHash)("sha256").update(content).digest("hex");
 }
 var REFERENCE_MICRO_USDC_PER_RENDER = 2e6;
 var defaultSwap3 = (microUsdc) => Promise.resolve(renderAmount(microUsdc / REFERENCE_MICRO_USDC_PER_RENDER));
@@ -2079,7 +2259,7 @@ function createRenderAdapter(config = {}) {
 }
 
 // src/adapters/gensyn/index.ts
-var import_crypto7 = require("crypto");
+var import_crypto8 = require("crypto");
 var GENSYN_ADAPTER_ID = "gensyn";
 var GENSYN_CAPABILITIES = ["verifiable-compute"];
 var GENSYN_REE_SCHEME = "gensyn-ree-v1";
@@ -2087,7 +2267,7 @@ var GENSYN_DEMO_MARKER = "gensyn-ree-demo-v1";
 var GENSYN_DEMO_SEED = 12345;
 var GENSYN_DEMO_STEPS = 16;
 function sha256Hex6(content) {
-  return (0, import_crypto7.createHash)("sha256").update(content).digest("hex");
+  return (0, import_crypto8.createHash)("sha256").update(content).digest("hex");
 }
 var LCG_MULT = 1103515245n;
 var LCG_INC = 12345n;
@@ -2249,14 +2429,14 @@ function createGensynAdapter(config = {}) {
 }
 
 // src/adapters/zkml/index.ts
-var import_crypto8 = require("crypto");
+var import_crypto9 = require("crypto");
 var ZKML_ADAPTER_ID = "zkml";
 var ZKML_CAPABILITIES = ["zk-verified-inference"];
 var ZKML_DEMO_MARKER = "zkml-demo-v1";
 var ZKML_PROOF_SCHEME = "escro-zkml-ref-v1";
 var ZKML_PROOF_URI_PREFIX = "zkml-proof:";
 function sha256Hex7(content) {
-  return (0, import_crypto8.createHash)("sha256").update(content).digest("hex");
+  return (0, import_crypto9.createHash)("sha256").update(content).digest("hex");
 }
 function computeZkmlVerificationTag(publicInputs) {
   return sha256Hex7(