@opendatalabs/vana-sdk 3.4.1 → 3.5.1-pr.159.12a6f39

package/dist/protocol/escrow.cjs

@@ -0,0 +1,146 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var escrow_exports = {};
+__export(escrow_exports, {
+  ESCROW_DEPOSIT_ABI: () => ESCROW_DEPOSIT_ABI,
+  GENERIC_PAYMENT_TYPES: () => GENERIC_PAYMENT_TYPES,
+  NATIVE_ASSET_ADDRESS: () => NATIVE_ASSET_ADDRESS,
+  createEscrowGatewayClient: () => createEscrowGatewayClient,
+  genericPaymentDomain: () => genericPaymentDomain
+});
+module.exports = __toCommonJS(escrow_exports);
+const GENERIC_PAYMENT_TYPES = {
+  GenericPayment: [
+    { name: "payerAddress", type: "address" },
+    { name: "opType", type: "string" },
+    { name: "opId", type: "bytes32" },
+    { name: "asset", type: "address" },
+    { name: "amount", type: "uint256" },
+    { name: "paymentNonce", type: "uint256" }
+  ]
+};
+function genericPaymentDomain(chainId, escrowContract) {
+  return {
+    name: "Vana Data Portability",
+    version: "1",
+    chainId,
+    verifyingContract: escrowContract
+  };
+}
+const ESCROW_DEPOSIT_ABI = [
+  {
+    type: "function",
+    name: "depositNative",
+    stateMutability: "payable",
+    inputs: [{ name: "account", type: "address" }],
+    outputs: []
+  },
+  {
+    type: "function",
+    name: "depositToken",
+    stateMutability: "nonpayable",
+    inputs: [
+      { name: "account", type: "address" },
+      { name: "token", type: "address" },
+      { name: "amount", type: "uint256" }
+    ],
+    outputs: []
+  }
+];
+const NATIVE_ASSET_ADDRESS = "0x0000000000000000000000000000000000000000";
+function createEscrowGatewayClient(baseUrl) {
+  const base = baseUrl.replace(/\/+$/, "");
+  async function throwOnError(res, context) {
+    if (!res.ok) {
+      let detail = "";
+      try {
+        const body = await res.json();
+        if (body.error) detail = `: ${body.error}`;
+      } catch {
+      }
+      throw new Error(
+        `Escrow gateway error (${context}): ${res.status} ${res.statusText}${detail}`
+      );
+    }
+  }
+  return {
+    async submitDeposit({ txHash }) {
+      const res = await fetch(`${base}/v1/escrow/deposit`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ txHash })
+      });
+      if (res.status !== 200 && res.status !== 202) {
+        await throwOnError(res, "POST /v1/escrow/deposit");
+      }
+      return res.json();
+    },
+    async getEscrowBalance(account) {
+      const res = await fetch(
+        `${base}/v1/escrow/balance?account=${encodeURIComponent(account)}`
+      );
+      await throwOnError(res, "GET /v1/escrow/balance");
+      return res.json();
+    },
+    async syncEscrowBalance(account) {
+      const res = await fetch(
+        `${base}/v1/escrow/balance/sync?account=${encodeURIComponent(account)}`,
+        { method: "POST" }
+      );
+      await throwOnError(res, "POST /v1/escrow/balance/sync");
+      return res.json();
+    },
+    async payForOp({
+      payerAddress,
+      opType,
+      opId,
+      asset,
+      amount,
+      paymentNonce,
+      signature
+    }) {
+      const res = await fetch(`${base}/v1/escrow/pay`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Web3Signed ${signature}`
+        },
+        body: JSON.stringify({
+          payerAddress,
+          opType,
+          opId,
+          asset,
+          amount,
+          paymentNonce
+        })
+      });
+      await throwOnError(res, "POST /v1/escrow/pay");
+      return res.json();
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ESCROW_DEPOSIT_ABI,
+  GENERIC_PAYMENT_TYPES,
+  NATIVE_ASSET_ADDRESS,
+  createEscrowGatewayClient,
+  genericPaymentDomain
+});
+//# sourceMappingURL=escrow.cjs.map

package/dist/protocol/escrow.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/protocol/escrow.ts"],"sourcesContent":["/**\n * DPv2 escrow payment helpers.\n *\n * Covers the three-phase flow used by builders to pay for data access:\n *\n *  1. **Deposit** — call `depositNative` or `depositToken` on the\n *     DataPortabilityEscrow contract, then notify the gateway.\n *  2. **Balance** — read or force-sync the gateway's off-chain credit view.\n *  3. **Pay** — sign a `GenericPayment` EIP-712 message and POST it to the\n *     gateway's `/v1/escrow/pay` endpoint.\n *\n * The gateway is the authority on balances; the on-chain contract is the\n * authority on what has been settled. Nothing in this module touches the\n * chain directly — signing is done by the caller's wallet.\n *\n * @category Protocol\n * @module escrow\n */\n\nimport type { TypedDataDomain } from \"viem\";\n\n// ---------------------------------------------------------------------------\n// EIP-712 — GenericPayment\n// ---------------------------------------------------------------------------\n\n/**\n * EIP-712 typed-data types for a generic op payment.\n *\n * The gateway verifies that the recovered signer == `payerAddress` and that\n * the (payer, paymentNonce) pair has not been seen before. Use a\n * monotonically-increasing nonce; the first payment for any payer should\n * start at 1.\n */\nexport const GENERIC_PAYMENT_TYPES = {\n  GenericPayment: [\n    { name: \"payerAddress\", type: \"address\" },\n    { name: \"opType\", type: \"string\" },\n    { name: \"opId\", type: \"bytes32\" },\n    { name: \"asset\", type: \"address\" },\n    { name: \"amount\", type: \"uint256\" },\n    { name: \"paymentNonce\", type: \"uint256\" },\n  ],\n} as const;\n\n/**\n * EIP-712 message payload for a generic op payment.\n *\n * - `opType` is currently `\"grant\"`. Additional types (file, builder, schema)\n *   may be added in future protocol versions.\n * - `opId` is the bytes32 id of the operation being paid for (e.g. `grantId`).\n * - `asset` is the ERC-20 token address, or the zero address for native VANA.\n * - `amount` is the total amount in base units (wei for VANA). Must match the\n *   sum the gateway expects for the current lifecycle of the op.\n * - `paymentNonce` must be a positive integer unique per `payerAddress`. Use 1\n *   for the first payment; increment by at least 1 for each subsequent call.\n */\nexport interface GenericPaymentMessage {\n  payerAddress: `0x${string}`;\n  opType: string;\n  opId: `0x${string}`;\n  asset: `0x${string}`;\n  amount: bigint;\n  paymentNonce: bigint;\n}\n\n/**\n * Returns the EIP-712 domain for signing a `GenericPayment` message.\n *\n * The verifying contract is the `DataPortabilityEscrow` contract; all gateway\n * deployments share the same domain name and version.\n *\n * @param chainId - Chain ID of the Vana network (e.g. 1480 mainnet, 14800 testnet).\n * @param escrowContract - Deployed address of DataPortabilityEscrow.\n */\nexport function genericPaymentDomain(\n  chainId: number,\n  escrowContract: `0x${string}`,\n): TypedDataDomain {\n  return {\n    name: \"Vana Data Portability\",\n    version: \"1\",\n    chainId,\n    verifyingContract: escrowContract,\n  };\n}\n\n// ---------------------------------------------------------------------------\n// On-chain deposit ABI fragments\n// ---------------------------------------------------------------------------\n\n/**\n * Minimal ABI for the two deposit entry points on `DataPortabilityEscrow`.\n *\n * - `depositNative(address account)` payable — credits native VANA.\n * - `depositToken(address account, address token, uint256 amount)` — credits\n *   an ERC-20 token (caller must have pre-approved the escrow contract).\n *\n * Pass this to viem's `writeContract` or encode it manually.\n */\nexport const ESCROW_DEPOSIT_ABI = [\n  {\n    type: \"function\",\n    name: \"depositNative\",\n    stateMutability: \"payable\",\n    inputs: [{ name: \"account\", type: \"address\" }],\n    outputs: [],\n  },\n  {\n    type: \"function\",\n    name: \"depositToken\",\n    stateMutability: \"nonpayable\",\n    inputs: [\n      { name: \"account\", type: \"address\" },\n      { name: \"token\", type: \"address\" },\n      { name: \"amount\", type: \"uint256\" },\n    ],\n    outputs: [],\n  },\n] as const;\n\n/**\n * The zero address used by the DataPortabilityEscrow contract to represent\n * native VANA in `asset` fields of events and balance responses.\n */\nexport const NATIVE_ASSET_ADDRESS =\n  \"0x0000000000000000000000000000000000000000\" as const;\n\n// ---------------------------------------------------------------------------\n// Gateway API client\n// ---------------------------------------------------------------------------\n\n/**\n * Per-asset balance entry returned by the gateway's escrow balance endpoints.\n *\n * - `balance` — gross finalized credit (deposits credited so far).\n * - `pendingAmount` — sum of submitted deposits not yet confirmed.\n * - `authorizedAmount` — sum of all in-flight payments authorized by\n *   `/v1/escrow/pay` (soft-lock). May include payments not yet settled\n *   on-chain.\n * - `availableAmount` — `max(balance − authorizedAmount, 0)`. This is what\n *   the payer can authorize before the gateway rejects with 402.\n */\nexport interface EscrowBalanceEntry {\n  asset: string;\n  balance: string;\n  pendingAmount: string;\n  authorizedAmount: string;\n  availableAmount: string;\n  updatedAt: string | null;\n}\n\nexport interface SubmittedDepositEntry {\n  txHash: string;\n  submittedAt: string;\n  claimedAsset: string;\n  claimedAmount: string;\n}\n\nexport interface FinalizedDepositEntry {\n  txHash: string;\n  finalizedAt: string | null;\n  blockNumber: string | null;\n  claimedAsset: string;\n  claimedAmount: string;\n}\n\nexport interface FailedDepositEntry {\n  txHash: string;\n  submittedAt: string;\n  claimedAsset: string;\n  claimedAmount: string;\n  lastError: string | null;\n}\n\n/** Full balance read response from `GET /v1/escrow/balance`. */\nexport interface EscrowBalanceResult {\n  account: string;\n  balances: EscrowBalanceEntry[];\n  deposits: {\n    submitted: SubmittedDepositEntry[];\n    finalized: FinalizedDepositEntry[];\n    failed: FailedDepositEntry[];\n  };\n}\n\n/**\n * Response from `POST /v1/escrow/balance/sync`.\n *\n * Extends {@link EscrowBalanceResult} with a `sync` summary of what the\n * lazy-confirmation pass did.\n */\nexport interface EscrowBalanceSyncResult extends EscrowBalanceResult {\n  sync:\n    | { scanned: number; finalized: number; stillPending: number; failed: number }\n    | { skipped: true };\n}\n\n/** Response from `POST /v1/escrow/deposit`. */\nexport interface DepositSubmissionResult {\n  success: true;\n  txHash: string;\n  account: string;\n  status: \"submitted\" | \"finalized\" | \"failed\";\n  blockNumber?: string | null;\n  submittedAt: string;\n  finalizedAt?: string | null;\n  lastError?: string | null;\n}\n\n/** Breakdown returned by a successful `POST /v1/escrow/pay`. */\nexport interface PaymentBreakdown {\n  registrationFee: string;\n  dataAccessFee: string;\n  /** True when this call settled the registration fee for the op. */\n  registrationPaid: boolean;\n}\n\n/** Response from `POST /v1/escrow/pay`. */\nexport interface EscrowPayResult {\n  success: true;\n  opType: string;\n  opId: string;\n  payerAddress: string;\n  asset: string;\n  amount: string;\n  breakdown: PaymentBreakdown;\n  paymentNonce: string;\n  paidAt: string;\n}\n\n/**\n * Parameters for submitting a deposit tx hash to the gateway.\n *\n * The gateway will decode the `account` from the tx's calldata and\n * credit the identified account once the tx reaches the configured\n * confirmation depth.\n */\nexport interface SubmitDepositParams {\n  /** 0x-prefixed 32-byte transaction hash. */\n  txHash: `0x${string}`;\n}\n\n/**\n * Parameters for the generic op payment endpoint (`POST /v1/escrow/pay`).\n *\n * The `signature` is an EIP-712 signature over a `GenericPayment` message\n * (see {@link GENERIC_PAYMENT_TYPES} and {@link genericPaymentDomain}).\n * Build and sign the typed data with your wallet before calling\n * {@link EscrowGatewayClient.payForOp}.\n */\nexport interface PayForOpParams {\n  payerAddress: `0x${string}`;\n  opType: string;\n  opId: `0x${string}`;\n  asset: `0x${string}`;\n  /** Decimal string representation of the uint256 amount. */\n  amount: string;\n  /** Decimal string representation of the uint256 nonce. */\n  paymentNonce: string;\n  /** 0x-prefixed 65-byte EIP-712 signature hex string. */\n  signature: `0x${string}`;\n}\n\n/**\n * Minimal client for the gateway's escrow endpoints.\n *\n * Construct with {@link createEscrowGatewayClient}.\n */\nexport interface EscrowGatewayClient {\n  /**\n   * Notify the gateway of a submitted deposit transaction.\n   *\n   * The gateway decodes the credited account from the on-chain tx calldata\n   * and starts tracking the deposit. Call this immediately after your\n   * `depositNative` or `depositToken` tx is broadcast (it accepts pending\n   * mempool txs). Returns `202` while the tx awaits confirmation.\n   */\n  submitDeposit(params: SubmitDepositParams): Promise<DepositSubmissionResult>;\n\n  /**\n   * Read the current escrow balance for an account.\n   *\n   * Pure read — no chain calls. To force a reconciliation pass first,\n   * use {@link syncEscrowBalance}.\n   */\n  getEscrowBalance(account: `0x${string}`): Promise<EscrowBalanceResult>;\n\n  /**\n   * Force a reconciliation pass then return the updated balance.\n   *\n   * Triggers the gateway's lazy-confirmation worker for the account — any\n   * submitted deposits that have reached the configured confirmation level\n   * are credited before the balance is returned. Prefer this over\n   * {@link getEscrowBalance} when you need a fresh view after a deposit.\n   */\n  syncEscrowBalance(account: `0x${string}`): Promise<EscrowBalanceSyncResult>;\n\n  /**\n   * Authorize a payment against the payer's escrow balance.\n   *\n   * The caller must:\n   *  1. Assemble a {@link GenericPaymentMessage}.\n   *  2. Sign it with `signTypedData` using {@link GENERIC_PAYMENT_TYPES} and\n   *     the domain from {@link genericPaymentDomain}.\n   *  3. Pass the message fields + signature here.\n   *\n   * The gateway verifies the signature, checks the soft-lock balance, and\n   * records the payment. Returns 402 if the payer has insufficient balance.\n   */\n  payForOp(params: PayForOpParams): Promise<EscrowPayResult>;\n}\n\n/**\n * Creates a client for the gateway escrow endpoints.\n *\n * @param baseUrl - Base URL of the DP RPC gateway\n *   (e.g. `\"https://dp.vana.org\"`). Trailing slashes are trimmed.\n *\n * @example\n * ```typescript\n * import {\n *   createEscrowGatewayClient,\n *   genericPaymentDomain,\n *   GENERIC_PAYMENT_TYPES,\n * } from \"@opendatalabs/vana-sdk/node\";\n *\n * const escrow = createEscrowGatewayClient(\"https://dp.vana.org\");\n *\n * // 1. Submit your deposit tx hash after broadcasting depositNative on-chain\n * const deposit = await escrow.submitDeposit({ txHash: \"0xabc…\" });\n *\n * // 2. Force-sync and read the updated balance\n * const { balances } = await escrow.syncEscrowBalance(\"0xpayerAddress\");\n *\n * // 3. Sign and authorize a grant payment\n * const sig = await walletClient.signTypedData({\n *   domain: genericPaymentDomain(1480, \"0xEscrowContract\"),\n *   types: GENERIC_PAYMENT_TYPES,\n *   primaryType: \"GenericPayment\",\n *   message: {\n *     payerAddress: \"0xpayerAddress\",\n *     opType: \"grant\",\n *     opId: \"0xgrantId\",\n *     asset: \"0x0000000000000000000000000000000000000000\",\n *     amount: 1000000000000000000n,\n *     paymentNonce: 1n,\n *   },\n * });\n * const result = await escrow.payForOp({\n *   payerAddress: \"0xpayerAddress\",\n *   opType: \"grant\",\n *   opId: \"0xgrantId\",\n *   asset: \"0x0000000000000000000000000000000000000000\",\n *   amount: \"1000000000000000000\",\n *   paymentNonce: \"1\",\n *   signature: sig,\n * });\n * ```\n */\nexport function createEscrowGatewayClient(\n  baseUrl: string,\n): EscrowGatewayClient {\n  const base = baseUrl.replace(/\\/+$/, \"\");\n\n  async function throwOnError(res: Response, context: string): Promise<void> {\n    if (!res.ok) {\n      let detail = \"\";\n      try {\n        const body = (await res.json()) as { error?: string };\n        if (body.error) detail = `: ${body.error}`;\n      } catch {\n        // Ignore JSON parse errors; use status text only.\n      }\n      throw new Error(\n        `Escrow gateway error (${context}): ${res.status} ${res.statusText}${detail}`,\n      );\n    }\n  }\n\n  return {\n    async submitDeposit({ txHash }) {\n      const res = await fetch(`${base}/v1/escrow/deposit`, {\n        method: \"POST\",\n        headers: { \"Content-Type\": \"application/json\" },\n        body: JSON.stringify({ txHash }),\n      });\n      // 202 Accepted and 200 OK are both success states for deposit submission.\n      if (res.status !== 200 && res.status !== 202) {\n        await throwOnError(res, \"POST /v1/escrow/deposit\");\n      }\n      return res.json() as Promise<DepositSubmissionResult>;\n    },\n\n    async getEscrowBalance(account) {\n      const res = await fetch(\n        `${base}/v1/escrow/balance?account=${encodeURIComponent(account)}`,\n      );\n      await throwOnError(res, \"GET /v1/escrow/balance\");\n      return res.json() as Promise<EscrowBalanceResult>;\n    },\n\n    async syncEscrowBalance(account) {\n      const res = await fetch(\n        `${base}/v1/escrow/balance/sync?account=${encodeURIComponent(account)}`,\n        { method: \"POST\" },\n      );\n      await throwOnError(res, \"POST /v1/escrow/balance/sync\");\n      return res.json() as Promise<EscrowBalanceSyncResult>;\n    },\n\n    async payForOp({\n      payerAddress,\n      opType,\n      opId,\n      asset,\n      amount,\n      paymentNonce,\n      signature,\n    }) {\n      const res = await fetch(`${base}/v1/escrow/pay`, {\n        method: \"POST\",\n        headers: {\n          \"Content-Type\": \"application/json\",\n          Authorization: `Web3Signed ${signature}`,\n        },\n        body: JSON.stringify({\n          payerAddress,\n          opType,\n          opId,\n          asset,\n          amount,\n          paymentNonce,\n        }),\n      });\n      await throwOnError(res, \"POST /v1/escrow/pay\");\n      return res.json() as Promise<EscrowPayResult>;\n    },\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/protocol/escrow.d.ts

@@ -0,0 +1,336 @@
+/**
+ * DPv2 escrow payment helpers.
+ *
+ * Covers the three-phase flow used by builders to pay for data access:
+ *
+ *  1. **Deposit** — call `depositNative` or `depositToken` on the
+ *     DataPortabilityEscrow contract, then notify the gateway.
+ *  2. **Balance** — read or force-sync the gateway's off-chain credit view.
+ *  3. **Pay** — sign a `GenericPayment` EIP-712 message and POST it to the
+ *     gateway's `/v1/escrow/pay` endpoint.
+ *
+ * The gateway is the authority on balances; the on-chain contract is the
+ * authority on what has been settled. Nothing in this module touches the
+ * chain directly — signing is done by the caller's wallet.
+ *
+ * @category Protocol
+ * @module escrow
+ */
+import type { TypedDataDomain } from "viem";
+/**
+ * EIP-712 typed-data types for a generic op payment.
+ *
+ * The gateway verifies that the recovered signer == `payerAddress` and that
+ * the (payer, paymentNonce) pair has not been seen before. Use a
+ * monotonically-increasing nonce; the first payment for any payer should
+ * start at 1.
+ */
+export declare const GENERIC_PAYMENT_TYPES: {
+    readonly GenericPayment: readonly [{
+        readonly name: "payerAddress";
+        readonly type: "address";
+    }, {
+        readonly name: "opType";
+        readonly type: "string";
+    }, {
+        readonly name: "opId";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "asset";
+        readonly type: "address";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+    }, {
+        readonly name: "paymentNonce";
+        readonly type: "uint256";
+    }];
+};
+/**
+ * EIP-712 message payload for a generic op payment.
+ *
+ * - `opType` is currently `"grant"`. Additional types (file, builder, schema)
+ *   may be added in future protocol versions.
+ * - `opId` is the bytes32 id of the operation being paid for (e.g. `grantId`).
+ * - `asset` is the ERC-20 token address, or the zero address for native VANA.
+ * - `amount` is the total amount in base units (wei for VANA). Must match the
+ *   sum the gateway expects for the current lifecycle of the op.
+ * - `paymentNonce` must be a positive integer unique per `payerAddress`. Use 1
+ *   for the first payment; increment by at least 1 for each subsequent call.
+ */
+export interface GenericPaymentMessage {
+    payerAddress: `0x${string}`;
+    opType: string;
+    opId: `0x${string}`;
+    asset: `0x${string}`;
+    amount: bigint;
+    paymentNonce: bigint;
+}
+/**
+ * Returns the EIP-712 domain for signing a `GenericPayment` message.
+ *
+ * The verifying contract is the `DataPortabilityEscrow` contract; all gateway
+ * deployments share the same domain name and version.
+ *
+ * @param chainId - Chain ID of the Vana network (e.g. 1480 mainnet, 14800 testnet).
+ * @param escrowContract - Deployed address of DataPortabilityEscrow.
+ */
+export declare function genericPaymentDomain(chainId: number, escrowContract: `0x${string}`): TypedDataDomain;
+/**
+ * Minimal ABI for the two deposit entry points on `DataPortabilityEscrow`.
+ *
+ * - `depositNative(address account)` payable — credits native VANA.
+ * - `depositToken(address account, address token, uint256 amount)` — credits
+ *   an ERC-20 token (caller must have pre-approved the escrow contract).
+ *
+ * Pass this to viem's `writeContract` or encode it manually.
+ */
+export declare const ESCROW_DEPOSIT_ABI: readonly [{
+    readonly type: "function";
+    readonly name: "depositNative";
+    readonly stateMutability: "payable";
+    readonly inputs: readonly [{
+        readonly name: "account";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "function";
+    readonly name: "depositToken";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "account";
+        readonly type: "address";
+    }, {
+        readonly name: "token";
+        readonly type: "address";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [];
+}];
+/**
+ * The zero address used by the DataPortabilityEscrow contract to represent
+ * native VANA in `asset` fields of events and balance responses.
+ */
+export declare const NATIVE_ASSET_ADDRESS: "0x0000000000000000000000000000000000000000";
+/**
+ * Per-asset balance entry returned by the gateway's escrow balance endpoints.
+ *
+ * - `balance` — gross finalized credit (deposits credited so far).
+ * - `pendingAmount` — sum of submitted deposits not yet confirmed.
+ * - `authorizedAmount` — sum of all in-flight payments authorized by
+ *   `/v1/escrow/pay` (soft-lock). May include payments not yet settled
+ *   on-chain.
+ * - `availableAmount` — `max(balance − authorizedAmount, 0)`. This is what
+ *   the payer can authorize before the gateway rejects with 402.
+ */
+export interface EscrowBalanceEntry {
+    asset: string;
+    balance: string;
+    pendingAmount: string;
+    authorizedAmount: string;
+    availableAmount: string;
+    updatedAt: string | null;
+}
+export interface SubmittedDepositEntry {
+    txHash: string;
+    submittedAt: string;
+    claimedAsset: string;
+    claimedAmount: string;
+}
+export interface FinalizedDepositEntry {
+    txHash: string;
+    finalizedAt: string | null;
+    blockNumber: string | null;
+    claimedAsset: string;
+    claimedAmount: string;
+}
+export interface FailedDepositEntry {
+    txHash: string;
+    submittedAt: string;
+    claimedAsset: string;
+    claimedAmount: string;
+    lastError: string | null;
+}
+/** Full balance read response from `GET /v1/escrow/balance`. */
+export interface EscrowBalanceResult {
+    account: string;
+    balances: EscrowBalanceEntry[];
+    deposits: {
+        submitted: SubmittedDepositEntry[];
+        finalized: FinalizedDepositEntry[];
+        failed: FailedDepositEntry[];
+    };
+}
+/**
+ * Response from `POST /v1/escrow/balance/sync`.
+ *
+ * Extends {@link EscrowBalanceResult} with a `sync` summary of what the
+ * lazy-confirmation pass did.
+ */
+export interface EscrowBalanceSyncResult extends EscrowBalanceResult {
+    sync: {
+        scanned: number;
+        finalized: number;
+        stillPending: number;
+        failed: number;
+    } | {
+        skipped: true;
+    };
+}
+/** Response from `POST /v1/escrow/deposit`. */
+export interface DepositSubmissionResult {
+    success: true;
+    txHash: string;
+    account: string;
+    status: "submitted" | "finalized" | "failed";
+    blockNumber?: string | null;
+    submittedAt: string;
+    finalizedAt?: string | null;
+    lastError?: string | null;
+}
+/** Breakdown returned by a successful `POST /v1/escrow/pay`. */
+export interface PaymentBreakdown {
+    registrationFee: string;
+    dataAccessFee: string;
+    /** True when this call settled the registration fee for the op. */
+    registrationPaid: boolean;
+}
+/** Response from `POST /v1/escrow/pay`. */
+export interface EscrowPayResult {
+    success: true;
+    opType: string;
+    opId: string;
+    payerAddress: string;
+    asset: string;
+    amount: string;
+    breakdown: PaymentBreakdown;
+    paymentNonce: string;
+    paidAt: string;
+}
+/**
+ * Parameters for submitting a deposit tx hash to the gateway.
+ *
+ * The gateway will decode the `account` from the tx's calldata and
+ * credit the identified account once the tx reaches the configured
+ * confirmation depth.
+ */
+export interface SubmitDepositParams {
+    /** 0x-prefixed 32-byte transaction hash. */
+    txHash: `0x${string}`;
+}
+/**
+ * Parameters for the generic op payment endpoint (`POST /v1/escrow/pay`).
+ *
+ * The `signature` is an EIP-712 signature over a `GenericPayment` message
+ * (see {@link GENERIC_PAYMENT_TYPES} and {@link genericPaymentDomain}).
+ * Build and sign the typed data with your wallet before calling
+ * {@link EscrowGatewayClient.payForOp}.
+ */
+export interface PayForOpParams {
+    payerAddress: `0x${string}`;
+    opType: string;
+    opId: `0x${string}`;
+    asset: `0x${string}`;
+    /** Decimal string representation of the uint256 amount. */
+    amount: string;
+    /** Decimal string representation of the uint256 nonce. */
+    paymentNonce: string;
+    /** 0x-prefixed 65-byte EIP-712 signature hex string. */
+    signature: `0x${string}`;
+}
+/**
+ * Minimal client for the gateway's escrow endpoints.
+ *
+ * Construct with {@link createEscrowGatewayClient}.
+ */
+export interface EscrowGatewayClient {
+    /**
+     * Notify the gateway of a submitted deposit transaction.
+     *
+     * The gateway decodes the credited account from the on-chain tx calldata
+     * and starts tracking the deposit. Call this immediately after your
+     * `depositNative` or `depositToken` tx is broadcast (it accepts pending
+     * mempool txs). Returns `202` while the tx awaits confirmation.
+     */
+    submitDeposit(params: SubmitDepositParams): Promise<DepositSubmissionResult>;
+    /**
+     * Read the current escrow balance for an account.
+     *
+     * Pure read — no chain calls. To force a reconciliation pass first,
+     * use {@link syncEscrowBalance}.
+     */
+    getEscrowBalance(account: `0x${string}`): Promise<EscrowBalanceResult>;
+    /**
+     * Force a reconciliation pass then return the updated balance.
+     *
+     * Triggers the gateway's lazy-confirmation worker for the account — any
+     * submitted deposits that have reached the configured confirmation level
+     * are credited before the balance is returned. Prefer this over
+     * {@link getEscrowBalance} when you need a fresh view after a deposit.
+     */
+    syncEscrowBalance(account: `0x${string}`): Promise<EscrowBalanceSyncResult>;
+    /**
+     * Authorize a payment against the payer's escrow balance.
+     *
+     * The caller must:
+     *  1. Assemble a {@link GenericPaymentMessage}.
+     *  2. Sign it with `signTypedData` using {@link GENERIC_PAYMENT_TYPES} and
+     *     the domain from {@link genericPaymentDomain}.
+     *  3. Pass the message fields + signature here.
+     *
+     * The gateway verifies the signature, checks the soft-lock balance, and
+     * records the payment. Returns 402 if the payer has insufficient balance.
+     */
+    payForOp(params: PayForOpParams): Promise<EscrowPayResult>;
+}
+/**
+ * Creates a client for the gateway escrow endpoints.
+ *
+ * @param baseUrl - Base URL of the DP RPC gateway
+ *   (e.g. `"https://dp.vana.org"`). Trailing slashes are trimmed.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   createEscrowGatewayClient,
+ *   genericPaymentDomain,
+ *   GENERIC_PAYMENT_TYPES,
+ * } from "@opendatalabs/vana-sdk/node";
+ *
+ * const escrow = createEscrowGatewayClient("https://dp.vana.org");
+ *
+ * // 1. Submit your deposit tx hash after broadcasting depositNative on-chain
+ * const deposit = await escrow.submitDeposit({ txHash: "0xabc…" });
+ *
+ * // 2. Force-sync and read the updated balance
+ * const { balances } = await escrow.syncEscrowBalance("0xpayerAddress");
+ *
+ * // 3. Sign and authorize a grant payment
+ * const sig = await walletClient.signTypedData({
+ *   domain: genericPaymentDomain(1480, "0xEscrowContract"),
+ *   types: GENERIC_PAYMENT_TYPES,
+ *   primaryType: "GenericPayment",
+ *   message: {
+ *     payerAddress: "0xpayerAddress",
+ *     opType: "grant",
+ *     opId: "0xgrantId",
+ *     asset: "0x0000000000000000000000000000000000000000",
+ *     amount: 1000000000000000000n,
+ *     paymentNonce: 1n,
+ *   },
+ * });
+ * const result = await escrow.payForOp({
+ *   payerAddress: "0xpayerAddress",
+ *   opType: "grant",
+ *   opId: "0xgrantId",
+ *   asset: "0x0000000000000000000000000000000000000000",
+ *   amount: "1000000000000000000",
+ *   paymentNonce: "1",
+ *   signature: sig,
+ * });
+ * ```
+ */
+export declare function createEscrowGatewayClient(baseUrl: string): EscrowGatewayClient;

package/dist/protocol/escrow.js

@@ -0,0 +1,118 @@
+const GENERIC_PAYMENT_TYPES = {
+  GenericPayment: [
+    { name: "payerAddress", type: "address" },
+    { name: "opType", type: "string" },
+    { name: "opId", type: "bytes32" },
+    { name: "asset", type: "address" },
+    { name: "amount", type: "uint256" },
+    { name: "paymentNonce", type: "uint256" }
+  ]
+};
+function genericPaymentDomain(chainId, escrowContract) {
+  return {
+    name: "Vana Data Portability",
+    version: "1",
+    chainId,
+    verifyingContract: escrowContract
+  };
+}
+const ESCROW_DEPOSIT_ABI = [
+  {
+    type: "function",
+    name: "depositNative",
+    stateMutability: "payable",
+    inputs: [{ name: "account", type: "address" }],
+    outputs: []
+  },
+  {
+    type: "function",
+    name: "depositToken",
+    stateMutability: "nonpayable",
+    inputs: [
+      { name: "account", type: "address" },
+      { name: "token", type: "address" },
+      { name: "amount", type: "uint256" }
+    ],
+    outputs: []
+  }
+];
+const NATIVE_ASSET_ADDRESS = "0x0000000000000000000000000000000000000000";
+function createEscrowGatewayClient(baseUrl) {
+  const base = baseUrl.replace(/\/+$/, "");
+  async function throwOnError(res, context) {
+    if (!res.ok) {
+      let detail = "";
+      try {
+        const body = await res.json();
+        if (body.error) detail = `: ${body.error}`;
+      } catch {
+      }
+      throw new Error(
+        `Escrow gateway error (${context}): ${res.status} ${res.statusText}${detail}`
+      );
+    }
+  }
+  return {
+    async submitDeposit({ txHash }) {
+      const res = await fetch(`${base}/v1/escrow/deposit`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ txHash })
+      });
+      if (res.status !== 200 && res.status !== 202) {
+        await throwOnError(res, "POST /v1/escrow/deposit");
+      }
+      return res.json();
+    },
+    async getEscrowBalance(account) {
+      const res = await fetch(
+        `${base}/v1/escrow/balance?account=${encodeURIComponent(account)}`
+      );
+      await throwOnError(res, "GET /v1/escrow/balance");
+      return res.json();
+    },
+    async syncEscrowBalance(account) {
+      const res = await fetch(
+        `${base}/v1/escrow/balance/sync?account=${encodeURIComponent(account)}`,
+        { method: "POST" }
+      );
+      await throwOnError(res, "POST /v1/escrow/balance/sync");
+      return res.json();
+    },
+    async payForOp({
+      payerAddress,
+      opType,
+      opId,
+      asset,
+      amount,
+      paymentNonce,
+      signature
+    }) {
+      const res = await fetch(`${base}/v1/escrow/pay`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Web3Signed ${signature}`
+        },
+        body: JSON.stringify({
+          payerAddress,
+          opType,
+          opId,
+          asset,
+          amount,
+          paymentNonce
+        })
+      });
+      await throwOnError(res, "POST /v1/escrow/pay");
+      return res.json();
+    }
+  };
+}
+export {
+  ESCROW_DEPOSIT_ABI,
+  GENERIC_PAYMENT_TYPES,
+  NATIVE_ASSET_ADDRESS,
+  createEscrowGatewayClient,
+  genericPaymentDomain
+};
+//# sourceMappingURL=escrow.js.map

package/dist/protocol/escrow.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/protocol/escrow.ts"],"sourcesContent":["/**\n * DPv2 escrow payment helpers.\n *\n * Covers the three-phase flow used by builders to pay for data access:\n *\n *  1. **Deposit** — call `depositNative` or `depositToken` on the\n *     DataPortabilityEscrow contract, then notify the gateway.\n *  2. **Balance** — read or force-sync the gateway's off-chain credit view.\n *  3. **Pay** — sign a `GenericPayment` EIP-712 message and POST it to the\n *     gateway's `/v1/escrow/pay` endpoint.\n *\n * The gateway is the authority on balances; the on-chain contract is the\n * authority on what has been settled. Nothing in this module touches the\n * chain directly — signing is done by the caller's wallet.\n *\n * @category Protocol\n * @module escrow\n */\n\nimport type { TypedDataDomain } from \"viem\";\n\n// ---------------------------------------------------------------------------\n// EIP-712 — GenericPayment\n// ---------------------------------------------------------------------------\n\n/**\n * EIP-712 typed-data types for a generic op payment.\n *\n * The gateway verifies that the recovered signer == `payerAddress` and that\n * the (payer, paymentNonce) pair has not been seen before. Use a\n * monotonically-increasing nonce; the first payment for any payer should\n * start at 1.\n */\nexport const GENERIC_PAYMENT_TYPES = {\n  GenericPayment: [\n    { name: \"payerAddress\", type: \"address\" },\n    { name: \"opType\", type: \"string\" },\n    { name: \"opId\", type: \"bytes32\" },\n    { name: \"asset\", type: \"address\" },\n    { name: \"amount\", type: \"uint256\" },\n    { name: \"paymentNonce\", type: \"uint256\" },\n  ],\n} as const;\n\n/**\n * EIP-712 message payload for a generic op payment.\n *\n * - `opType` is currently `\"grant\"`. Additional types (file, builder, schema)\n *   may be added in future protocol versions.\n * - `opId` is the bytes32 id of the operation being paid for (e.g. `grantId`).\n * - `asset` is the ERC-20 token address, or the zero address for native VANA.\n * - `amount` is the total amount in base units (wei for VANA). Must match the\n *   sum the gateway expects for the current lifecycle of the op.\n * - `paymentNonce` must be a positive integer unique per `payerAddress`. Use 1\n *   for the first payment; increment by at least 1 for each subsequent call.\n */\nexport interface GenericPaymentMessage {\n  payerAddress: `0x${string}`;\n  opType: string;\n  opId: `0x${string}`;\n  asset: `0x${string}`;\n  amount: bigint;\n  paymentNonce: bigint;\n}\n\n/**\n * Returns the EIP-712 domain for signing a `GenericPayment` message.\n *\n * The verifying contract is the `DataPortabilityEscrow` contract; all gateway\n * deployments share the same domain name and version.\n *\n * @param chainId - Chain ID of the Vana network (e.g. 1480 mainnet, 14800 testnet).\n * @param escrowContract - Deployed address of DataPortabilityEscrow.\n */\nexport function genericPaymentDomain(\n  chainId: number,\n  escrowContract: `0x${string}`,\n): TypedDataDomain {\n  return {\n    name: \"Vana Data Portability\",\n    version: \"1\",\n    chainId,\n    verifyingContract: escrowContract,\n  };\n}\n\n// ---------------------------------------------------------------------------\n// On-chain deposit ABI fragments\n// ---------------------------------------------------------------------------\n\n/**\n * Minimal ABI for the two deposit entry points on `DataPortabilityEscrow`.\n *\n * - `depositNative(address account)` payable — credits native VANA.\n * - `depositToken(address account, address token, uint256 amount)` — credits\n *   an ERC-20 token (caller must have pre-approved the escrow contract).\n *\n * Pass this to viem's `writeContract` or encode it manually.\n */\nexport const ESCROW_DEPOSIT_ABI = [\n  {\n    type: \"function\",\n    name: \"depositNative\",\n    stateMutability: \"payable\",\n    inputs: [{ name: \"account\", type: \"address\" }],\n    outputs: [],\n  },\n  {\n    type: \"function\",\n    name: \"depositToken\",\n    stateMutability: \"nonpayable\",\n    inputs: [\n      { name: \"account\", type: \"address\" },\n      { name: \"token\", type: \"address\" },\n      { name: \"amount\", type: \"uint256\" },\n    ],\n    outputs: [],\n  },\n] as const;\n\n/**\n * The zero address used by the DataPortabilityEscrow contract to represent\n * native VANA in `asset` fields of events and balance responses.\n */\nexport const NATIVE_ASSET_ADDRESS =\n  \"0x0000000000000000000000000000000000000000\" as const;\n\n// ---------------------------------------------------------------------------\n// Gateway API client\n// ---------------------------------------------------------------------------\n\n/**\n * Per-asset balance entry returned by the gateway's escrow balance endpoints.\n *\n * - `balance` — gross finalized credit (deposits credited so far).\n * - `pendingAmount` — sum of submitted deposits not yet confirmed.\n * - `authorizedAmount` — sum of all in-flight payments authorized by\n *   `/v1/escrow/pay` (soft-lock). May include payments not yet settled\n *   on-chain.\n * - `availableAmount` — `max(balance − authorizedAmount, 0)`. This is what\n *   the payer can authorize before the gateway rejects with 402.\n */\nexport interface EscrowBalanceEntry {\n  asset: string;\n  balance: string;\n  pendingAmount: string;\n  authorizedAmount: string;\n  availableAmount: string;\n  updatedAt: string | null;\n}\n\nexport interface SubmittedDepositEntry {\n  txHash: string;\n  submittedAt: string;\n  claimedAsset: string;\n  claimedAmount: string;\n}\n\nexport interface FinalizedDepositEntry {\n  txHash: string;\n  finalizedAt: string | null;\n  blockNumber: string | null;\n  claimedAsset: string;\n  claimedAmount: string;\n}\n\nexport interface FailedDepositEntry {\n  txHash: string;\n  submittedAt: string;\n  claimedAsset: string;\n  claimedAmount: string;\n  lastError: string | null;\n}\n\n/** Full balance read response from `GET /v1/escrow/balance`. */\nexport interface EscrowBalanceResult {\n  account: string;\n  balances: EscrowBalanceEntry[];\n  deposits: {\n    submitted: SubmittedDepositEntry[];\n    finalized: FinalizedDepositEntry[];\n    failed: FailedDepositEntry[];\n  };\n}\n\n/**\n * Response from `POST /v1/escrow/balance/sync`.\n *\n * Extends {@link EscrowBalanceResult} with a `sync` summary of what the\n * lazy-confirmation pass did.\n */\nexport interface EscrowBalanceSyncResult extends EscrowBalanceResult {\n  sync:\n    | { scanned: number; finalized: number; stillPending: number; failed: number }\n    | { skipped: true };\n}\n\n/** Response from `POST /v1/escrow/deposit`. */\nexport interface DepositSubmissionResult {\n  success: true;\n  txHash: string;\n  account: string;\n  status: \"submitted\" | \"finalized\" | \"failed\";\n  blockNumber?: string | null;\n  submittedAt: string;\n  finalizedAt?: string | null;\n  lastError?: string | null;\n}\n\n/** Breakdown returned by a successful `POST /v1/escrow/pay`. */\nexport interface PaymentBreakdown {\n  registrationFee: string;\n  dataAccessFee: string;\n  /** True when this call settled the registration fee for the op. */\n  registrationPaid: boolean;\n}\n\n/** Response from `POST /v1/escrow/pay`. */\nexport interface EscrowPayResult {\n  success: true;\n  opType: string;\n  opId: string;\n  payerAddress: string;\n  asset: string;\n  amount: string;\n  breakdown: PaymentBreakdown;\n  paymentNonce: string;\n  paidAt: string;\n}\n\n/**\n * Parameters for submitting a deposit tx hash to the gateway.\n *\n * The gateway will decode the `account` from the tx's calldata and\n * credit the identified account once the tx reaches the configured\n * confirmation depth.\n */\nexport interface SubmitDepositParams {\n  /** 0x-prefixed 32-byte transaction hash. */\n  txHash: `0x${string}`;\n}\n\n/**\n * Parameters for the generic op payment endpoint (`POST /v1/escrow/pay`).\n *\n * The `signature` is an EIP-712 signature over a `GenericPayment` message\n * (see {@link GENERIC_PAYMENT_TYPES} and {@link genericPaymentDomain}).\n * Build and sign the typed data with your wallet before calling\n * {@link EscrowGatewayClient.payForOp}.\n */\nexport interface PayForOpParams {\n  payerAddress: `0x${string}`;\n  opType: string;\n  opId: `0x${string}`;\n  asset: `0x${string}`;\n  /** Decimal string representation of the uint256 amount. */\n  amount: string;\n  /** Decimal string representation of the uint256 nonce. */\n  paymentNonce: string;\n  /** 0x-prefixed 65-byte EIP-712 signature hex string. */\n  signature: `0x${string}`;\n}\n\n/**\n * Minimal client for the gateway's escrow endpoints.\n *\n * Construct with {@link createEscrowGatewayClient}.\n */\nexport interface EscrowGatewayClient {\n  /**\n   * Notify the gateway of a submitted deposit transaction.\n   *\n   * The gateway decodes the credited account from the on-chain tx calldata\n   * and starts tracking the deposit. Call this immediately after your\n   * `depositNative` or `depositToken` tx is broadcast (it accepts pending\n   * mempool txs). Returns `202` while the tx awaits confirmation.\n   */\n  submitDeposit(params: SubmitDepositParams): Promise<DepositSubmissionResult>;\n\n  /**\n   * Read the current escrow balance for an account.\n   *\n   * Pure read — no chain calls. To force a reconciliation pass first,\n   * use {@link syncEscrowBalance}.\n   */\n  getEscrowBalance(account: `0x${string}`): Promise<EscrowBalanceResult>;\n\n  /**\n   * Force a reconciliation pass then return the updated balance.\n   *\n   * Triggers the gateway's lazy-confirmation worker for the account — any\n   * submitted deposits that have reached the configured confirmation level\n   * are credited before the balance is returned. Prefer this over\n   * {@link getEscrowBalance} when you need a fresh view after a deposit.\n   */\n  syncEscrowBalance(account: `0x${string}`): Promise<EscrowBalanceSyncResult>;\n\n  /**\n   * Authorize a payment against the payer's escrow balance.\n   *\n   * The caller must:\n   *  1. Assemble a {@link GenericPaymentMessage}.\n   *  2. Sign it with `signTypedData` using {@link GENERIC_PAYMENT_TYPES} and\n   *     the domain from {@link genericPaymentDomain}.\n   *  3. Pass the message fields + signature here.\n   *\n   * The gateway verifies the signature, checks the soft-lock balance, and\n   * records the payment. Returns 402 if the payer has insufficient balance.\n   */\n  payForOp(params: PayForOpParams): Promise<EscrowPayResult>;\n}\n\n/**\n * Creates a client for the gateway escrow endpoints.\n *\n * @param baseUrl - Base URL of the DP RPC gateway\n *   (e.g. `\"https://dp.vana.org\"`). Trailing slashes are trimmed.\n *\n * @example\n * ```typescript\n * import {\n *   createEscrowGatewayClient,\n *   genericPaymentDomain,\n *   GENERIC_PAYMENT_TYPES,\n * } from \"@opendatalabs/vana-sdk/node\";\n *\n * const escrow = createEscrowGatewayClient(\"https://dp.vana.org\");\n *\n * // 1. Submit your deposit tx hash after broadcasting depositNative on-chain\n * const deposit = await escrow.submitDeposit({ txHash: \"0xabc…\" });\n *\n * // 2. Force-sync and read the updated balance\n * const { balances } = await escrow.syncEscrowBalance(\"0xpayerAddress\");\n *\n * // 3. Sign and authorize a grant payment\n * const sig = await walletClient.signTypedData({\n *   domain: genericPaymentDomain(1480, \"0xEscrowContract\"),\n *   types: GENERIC_PAYMENT_TYPES,\n *   primaryType: \"GenericPayment\",\n *   message: {\n *     payerAddress: \"0xpayerAddress\",\n *     opType: \"grant\",\n *     opId: \"0xgrantId\",\n *     asset: \"0x0000000000000000000000000000000000000000\",\n *     amount: 1000000000000000000n,\n *     paymentNonce: 1n,\n *   },\n * });\n * const result = await escrow.payForOp({\n *   payerAddress: \"0xpayerAddress\",\n *   opType: \"grant\",\n *   opId: \"0xgrantId\",\n *   asset: \"0x0000000000000000000000000000000000000000\",\n *   amount: \"1000000000000000000\",\n *   paymentNonce: \"1\",\n *   signature: sig,\n * });\n * ```\n */\nexport function createEscrowGatewayClient(\n  baseUrl: string,\n): EscrowGatewayClient {\n  const base = baseUrl.replace(/\\/+$/, \"\");\n\n  async function throwOnError(res: Response, context: string): Promise<void> {\n    if (!res.ok) {\n      let detail = \"\";\n      try {\n        const body = (await res.json()) as { error?: string };\n        if (body.error) detail = `: ${body.error}`;\n      } catch {\n        // Ignore JSON parse errors; use status text only.\n      }\n      throw new Error(\n        `Escrow gateway error (${context}): ${res.status} ${res.statusText}${detail}`,\n      );\n    }\n  }\n\n  return {\n    async submitDeposit({ txHash }) {\n      const res = await fetch(`${base}/v1/escrow/deposit`, {\n        method: \"POST\",\n        headers: { \"Content-Type\": \"application/json\" },\n        body: JSON.stringify({ txHash }),\n      });\n      // 202 Accepted and 200 OK are both success states for deposit submission.\n      if (res.status !== 200 && res.status !== 202) {\n        await throwOnError(res, \"POST /v1/escrow/deposit\");\n      }\n      return res.json() as Promise<DepositSubmissionResult>;\n    },\n\n    async getEscrowBalance(account) {\n      const res = await fetch(\n        `${base}/v1/escrow/balance?account=${encodeURIComponent(account)}`,\n      );\n      await throwOnError(res, \"GET /v1/escrow/balance\");\n      return res.json() as Promise<EscrowBalanceResult>;\n    },\n\n    async syncEscrowBalance(account) {\n      const res = await fetch(\n        `${base}/v1/escrow/balance/sync?account=${encodeURIComponent(account)}`,\n        { method: \"POST\" },\n      );\n      await throwOnError(res, \"POST /v1/escrow/balance/sync\");\n      return res.json() as Promise<EscrowBalanceSyncResult>;\n    },\n\n    async payForOp({\n      payerAddress,\n      opType,\n      opId,\n      asset,\n      amount,\n      paymentNonce,\n      signature,\n    }) {\n      const res = await fetch(`${base}/v1/escrow/pay`, {\n        method: \"POST\",\n        headers: {\n          \"Content-Type\": \"application/json\",\n          Authorization: `Web3Signed ${signature}`,\n        },\n        body: JSON.stringify({\n          payerAddress,\n          opType,\n          opId,\n          asset,\n          amount,\n          paymentNonce,\n        }),\n      });\n      await throwOnError(res, \"POST /v1/escrow/pay\");\n      return res.json() as Promise<EscrowPayResult>;\n    },\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/protocol/escrow.test.d.ts

@@ -0,0 +1 @@
+export {};