@opendatalabs/vana-sdk 3.13.4 → 3.14.0

package/dist/direct/escrow-payment.cjs

@@ -18,17 +18,22 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var escrow_payment_exports = {};
 __export(escrow_payment_exports, {
+  DATA_ACCESS_OP_TYPE: () => DATA_ACCESS_OP_TYPE,
   GRANT_OP_TYPE: () => GRANT_OP_TYPE,
+  authorizeEscrowPayment: () => authorizeEscrowPayment,
   authorizeGrantPayment: () => authorizeGrantPayment,
+  buildEscrowPaymentHeader: () => buildEscrowPaymentHeader,
   buildGrantPaymentHeader: () => buildGrantPaymentHeader,
   createDefaultNonceSource: () => createDefaultNonceSource,
   paymentReceiptFromHeader: () => paymentReceiptFromHeader,
+  paymentResponseMetadataFromHeader: () => paymentResponseMetadataFromHeader,
   toDirectFeeBreakdown: () => toDirectFeeBreakdown,
   toDirectPaymentReceipt: () => toDirectPaymentReceipt
 });
 module.exports = __toCommonJS(escrow_payment_exports);
 var import_escrow = require("../protocol/escrow");
 const GRANT_OP_TYPE = "grant";
+const DATA_ACCESS_OP_TYPE = "data_access";
 function toDirectFeeBreakdown(breakdown) {
   return {
     registrationFee: breakdown.registrationFee,
@@ -57,6 +62,58 @@ function createDefaultNonceSource() {
   };
 }
 const processLocalNonceSource = createDefaultNonceSource();
+const UINT256_MAX = (1n << 256n) - 1n;
+const ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
+const BYTES32_RE = /^0x[0-9a-fA-F]{64}$/;
+const SIGNATURE_RE = /^0x[0-9a-fA-F]{130}$/;
+function isUint256Decimal(value, allowZero) {
+  const pattern = allowZero ? /^(0|[1-9]\d*)$/ : /^[1-9]\d*$/;
+  return value.length <= UINT256_MAX.toString().length && pattern.test(value) && BigInt(value) <= UINT256_MAX;
+}
+function isValidAccessRecord(record) {
+  return BYTES32_RE.test(record.dataPointId) && isUint256Decimal(record.version, false) && ADDRESS_RE.test(record.accessor) && BYTES32_RE.test(record.recordId) && SIGNATURE_RE.test(record.signature);
+}
+function validateSigningOperation(payerAddress, required) {
+  if (!ADDRESS_RE.test(payerAddress)) {
+    throw new Error("Payment payer must be a 20-byte EVM address");
+  }
+  if (!BYTES32_RE.test(required.opId)) {
+    throw new Error("Payment operation id must be a 32-byte hex value");
+  }
+  if (!ADDRESS_RE.test(required.asset || import_escrow.NATIVE_ASSET_ADDRESS)) {
+    throw new Error("Payment asset must be a 20-byte EVM address");
+  }
+  if (!isUint256Decimal(required.amount, true)) {
+    throw new Error("Payment amount must be a canonical uint256 decimal");
+  }
+  if (required.paymentNonce !== void 0 && !isUint256Decimal(required.paymentNonce, false)) {
+    throw new Error("Payment nonce must be a positive uint256 decimal");
+  }
+  const accessRecord = required.accessRecord;
+  if (required.opType === DATA_ACCESS_OP_TYPE) {
+    if (!accessRecord || !isValidAccessRecord(accessRecord)) {
+      throw new Error("Data-access payment requires a valid access record");
+    }
+    if (required.opId.toLowerCase() !== accessRecord.recordId.toLowerCase()) {
+      throw new Error(
+        "Data-access payment operation id must equal the access record id"
+      );
+    }
+    if (accessRecord.accessor.toLowerCase() !== payerAddress.toLowerCase()) {
+      throw new Error(
+        "Data-access payment accessor must equal the payment payer address"
+      );
+    }
+    return;
+  }
+  if (required.amount === "0") {
+    if (!accessRecord || !isValidAccessRecord(accessRecord) || accessRecord.accessor.toLowerCase() !== payerAddress.toLowerCase()) {
+      throw new Error(
+        "Zero-amount grant payments require a valid access record for the payer"
+      );
+    }
+  }
+}
 function base64EncodeJson(value) {
   const bytes = new TextEncoder().encode(JSON.stringify(value));
   let binary = "";
@@ -68,18 +125,25 @@ function base64DecodeJson(value) {
   const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));
   return JSON.parse(new TextDecoder().decode(bytes));
 }
-async function signGrantPayment(params) {
+async function signEscrowPayment(params) {
   const { payerAddress, required, config } = params;
+  validateSigningOperation(payerAddress, required);
   const nonceSource = config.nonceSource ?? processLocalNonceSource;
   const paymentNonce = BigInt(
     required.paymentNonce ?? await nonceSource(payerAddress)
   );
   const asset = required.asset || import_escrow.NATIVE_ASSET_ADDRESS;
-  const opId = required.grantId;
+  const opId = required.opId;
   const amount = BigInt(required.amount);
+  if (amount < 0n || amount > UINT256_MAX) {
+    throw new Error("Payment amount must be a uint256");
+  }
+  if (paymentNonce <= 0n || paymentNonce > UINT256_MAX) {
+    throw new Error("Payment nonce must be a positive uint256");
+  }
   const message = {
     payerAddress,
-    opType: GRANT_OP_TYPE,
+    opType: required.opType,
     opId,
     asset,
     amount,
@@ -101,46 +165,117 @@ async function signGrantPayment(params) {
     ...required.accessRecord ? { accessRecord: required.accessRecord } : {}
   };
 }
-async function buildGrantPaymentHeader(params) {
-  const signed = await signGrantPayment(params);
+async function buildEscrowPaymentHeader(params) {
+  const network = params.required.network ?? `vana:${params.config.chainId}`;
+  if (network !== `vana:${params.config.chainId}`) {
+    throw new Error("Payment network must match the configured chain");
+  }
+  const signed = await signEscrowPayment(params);
   const payment = {
     x402Version: 1,
     scheme: "vana-escrow-grant",
-    network: params.required.network ?? `vana:${params.config.chainId}`,
+    network,
     payload: signed
   };
   return base64EncodeJson(payment);
 }
-function paymentReceiptFromHeader(header) {
+async function buildGrantPaymentHeader(params) {
+  return buildEscrowPaymentHeader({
+    ...params,
+    required: {
+      ...params.required,
+      opType: GRANT_OP_TYPE,
+      opId: params.required.grantId
+    }
+  });
+}
+function asRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+function stringField(value, key) {
+  const field = value?.[key];
+  return typeof field === "string" ? field : void 0;
+}
+function isCanonicalIsoTimestamp(value) {
+  try {
+    return new Date(value).toISOString() === value;
+  } catch {
+    return false;
+  }
+}
+function paymentResponseMetadataFromHeader(header) {
   if (!header) return void 0;
   try {
-    return toDirectPaymentReceipt(base64DecodeJson(header));
+    const result = asRecord(base64DecodeJson(header));
+    const breakdown = asRecord(result?.breakdown);
+    const opType = stringField(result, "opType");
+    const opId = stringField(result, "opId");
+    const payerAddress = stringField(result, "payerAddress");
+    const asset = stringField(result, "asset");
+    const amount = stringField(result, "amount");
+    const paymentNonce = stringField(result, "paymentNonce");
+    const registrationFee = stringField(breakdown, "registrationFee");
+    const dataAccessFee = stringField(breakdown, "dataAccessFee");
+    const paidAt = stringField(result, "paidAt");
+    if (result?.success !== true || !opType || !opId || !BYTES32_RE.test(opId) || !payerAddress || !ADDRESS_RE.test(payerAddress) || !asset || !ADDRESS_RE.test(asset) || !amount || !isUint256Decimal(amount, true) || !paymentNonce || !isUint256Decimal(paymentNonce, false) || !registrationFee || !isUint256Decimal(registrationFee, true) || !dataAccessFee || !isUint256Decimal(dataAccessFee, true) || typeof breakdown?.registrationPaid !== "boolean" || !paidAt || !isCanonicalIsoTimestamp(paidAt)) {
+      return void 0;
+    }
+    return {
+      opType,
+      opId,
+      asset,
+      amount,
+      paymentNonce,
+      breakdown: {
+        registrationFee,
+        dataAccessFee,
+        registrationPaid: breakdown.registrationPaid
+      },
+      paidAt
+    };
   } catch {
     return void 0;
   }
 }
+function paymentReceiptFromHeader(header) {
+  return paymentResponseMetadataFromHeader(header);
+}
 async function authorizeGrantPayment(params) {
-  const { payerAddress, required, config } = params;
-  const signed = await signGrantPayment(params);
+  return authorizeEscrowPayment({
+    ...params,
+    required: {
+      ...params.required,
+      opType: GRANT_OP_TYPE,
+      opId: params.required.grantId
+    }
+  });
+}
+async function authorizeEscrowPayment(params) {
+  const { payerAddress, config } = params;
+  const signed = await signEscrowPayment(params);
   const result = await config.client.payForOp({
     payerAddress,
-    opType: GRANT_OP_TYPE,
+    opType: signed.message.opType,
     opId: signed.message.opId,
     asset: signed.message.asset,
     amount: signed.message.amount,
     paymentNonce: signed.message.paymentNonce,
     signature: signed.signature,
-    accessRecord: required.accessRecord
+    accessRecord: signed.accessRecord
   });
   return toDirectPaymentReceipt(result);
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  DATA_ACCESS_OP_TYPE,
   GRANT_OP_TYPE,
+  authorizeEscrowPayment,
   authorizeGrantPayment,
+  buildEscrowPaymentHeader,
   buildGrantPaymentHeader,
   createDefaultNonceSource,
   paymentReceiptFromHeader,
+  paymentResponseMetadataFromHeader,
   toDirectFeeBreakdown,
   toDirectPaymentReceipt
 });

package/dist/direct/escrow-payment.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/direct/escrow-payment.ts"],"sourcesContent":["/**\n * Escrow-backed payment authorization for the Direct Data Controller.\n *\n * @remarks\n * Builds on the DPv2 escrow surface added in `protocol/escrow`. When a Personal\n * Server read returns `402 Payment Required`, the controller settles the\n * grant's data-access fee through the escrow gateway:\n *\n *  1. Sign a `GenericPayment` EIP-712 message (op `\"grant\"`, opId = grantId)\n *     with the app key.\n *  2. POST it to the gateway's `/v1/escrow/pay` via {@link EscrowGatewayClient}.\n *  3. Map the gateway's {@link EscrowPayResult} into a typed\n *     {@link DirectPaymentReceipt} for the caller to inspect.\n *\n * This module adapts the escrow `payForOp` flow to the direct-read use case; it\n * does not define its own payment scheme.\n *\n * @category Direct\n * @module direct/escrow-payment\n */\n\nimport {\n  GENERIC_PAYMENT_TYPES,\n  NATIVE_ASSET_ADDRESS,\n  genericPaymentDomain,\n  type EscrowAccessRecord,\n  type EscrowGatewayClient,\n  type EscrowPayResult,\n  type PaymentBreakdown,\n} from \"../protocol/escrow\";\nimport type {\n  DirectFeeBreakdown,\n  DirectPaymentReceipt,\n  PersonalServerPaymentRequired,\n} from \"./types\";\n\n/** The escrow `GenericPayment.opType` used for grant-lifecycle payments. */\nexport const GRANT_OP_TYPE = \"grant\" as const;\n\n/**\n * EIP-712 typed-data signer (e.g. viem `account.signTypedData`).\n *\n * @remarks\n * Kept structurally minimal so any viem account/wallet client satisfies it\n * without the SDK depending on viem's exact `signTypedData` overload set.\n */\nexport type SignTypedDataFn = (args: {\n  domain: ReturnType<typeof genericPaymentDomain>;\n  types: typeof GENERIC_PAYMENT_TYPES;\n  primaryType: \"GenericPayment\";\n  message: {\n    payerAddress: `0x${string}`;\n    opType: string;\n    opId: `0x${string}`;\n    asset: `0x${string}`;\n    amount: bigint;\n    paymentNonce: bigint;\n  };\n}) => Promise<`0x${string}`>;\n\n/** Supplies a monotonically-increasing payment nonce per payer. */\nexport type PaymentNonceSource = (\n  payerAddress: string,\n) => Promise<bigint> | bigint;\n\ninterface GrantPaymentMessage {\n  payerAddress: `0x${string}`;\n  opType: typeof GRANT_OP_TYPE;\n  opId: `0x${string}`;\n  asset: `0x${string}`;\n  amount: string;\n  paymentNonce: string;\n}\n\ninterface SignedGrantPayment {\n  message: GrantPaymentMessage;\n  signature: `0x${string}`;\n  accessRecord?: EscrowAccessRecord;\n}\n\ninterface X402PaymentHeader {\n  x402Version: 1;\n  scheme: \"vana-escrow-grant\";\n  network: string;\n  payload: SignedGrantPayment;\n}\n\n/** Escrow settlement configuration for the controller. */\nexport interface EscrowPaymentConfig {\n  /** Client for the gateway escrow endpoints (`/v1/escrow/*`). */\n  client: EscrowGatewayClient;\n  /** Deployed `DataPortabilityEscrow` contract address. */\n  escrowContract: `0x${string}`;\n  /** Chain id for the EIP-712 domain (1480 mainnet, 14800 moksha). */\n  chainId: number;\n  /** App EIP-712 signer. */\n  signTypedData: SignTypedDataFn;\n  /**\n   * Supplies the next payment nonce for a payer. Defaults to a process-local\n   * monotonic counter seeded at 1. Provide a durable source in production so\n   * nonces survive restarts (the gateway rejects reused (payer, nonce) pairs).\n   */\n  nonceSource?: PaymentNonceSource;\n}\n\n/** Map the gateway {@link PaymentBreakdown} into the public {@link DirectFeeBreakdown}. */\nexport function toDirectFeeBreakdown(\n  breakdown: PaymentBreakdown,\n): DirectFeeBreakdown {\n  return {\n    registrationFee: breakdown.registrationFee,\n    dataAccessFee: breakdown.dataAccessFee,\n    registrationPaid: breakdown.registrationPaid,\n  };\n}\n\n/** Map a gateway {@link EscrowPayResult} into the public {@link DirectPaymentReceipt}. */\nexport function toDirectPaymentReceipt(\n  result: EscrowPayResult,\n): DirectPaymentReceipt {\n  return {\n    opType: result.opType,\n    opId: result.opId,\n    asset: result.asset,\n    amount: result.amount,\n    paymentNonce: result.paymentNonce,\n    breakdown: toDirectFeeBreakdown(result.breakdown),\n    paidAt: result.paidAt,\n  };\n}\n\n/** Default in-process monotonic nonce counter (seeded at 1 per payer). */\nexport function createDefaultNonceSource(): PaymentNonceSource {\n  const counters = new Map<string, bigint>();\n  return (payerAddress: string): bigint => {\n    const key = payerAddress.toLowerCase();\n    const next = (counters.get(key) ?? 0n) + 1n;\n    counters.set(key, next);\n    return next;\n  };\n}\n\nconst processLocalNonceSource = createDefaultNonceSource();\n\nfunction base64EncodeJson(value: unknown): string {\n  const bytes = new TextEncoder().encode(JSON.stringify(value));\n  let binary = \"\";\n  for (const byte of bytes) binary += String.fromCharCode(byte);\n  return btoa(binary);\n}\n\nfunction base64DecodeJson(value: string): unknown {\n  const binary = atob(value);\n  const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));\n  return JSON.parse(new TextDecoder().decode(bytes));\n}\n\nasync function signGrantPayment(params: {\n  payerAddress: `0x${string}`;\n  required: PersonalServerPaymentRequired;\n  config: EscrowPaymentConfig;\n}): Promise<SignedGrantPayment> {\n  const { payerAddress, required, config } = params;\n  const nonceSource = config.nonceSource ?? processLocalNonceSource;\n  const paymentNonce = BigInt(\n    required.paymentNonce ?? (await nonceSource(payerAddress)),\n  );\n  const asset = (required.asset || NATIVE_ASSET_ADDRESS) as `0x${string}`;\n  const opId = required.grantId as `0x${string}`;\n  const amount = BigInt(required.amount);\n\n  const message = {\n    payerAddress,\n    opType: GRANT_OP_TYPE,\n    opId,\n    asset,\n    amount,\n    paymentNonce,\n  };\n\n  const signature = await config.signTypedData({\n    domain: genericPaymentDomain(config.chainId, config.escrowContract),\n    types: GENERIC_PAYMENT_TYPES,\n    primaryType: \"GenericPayment\",\n    message,\n  });\n\n  return {\n    message: {\n      ...message,\n      amount: amount.toString(),\n      paymentNonce: paymentNonce.toString(),\n    },\n    signature,\n    ...(required.accessRecord ? { accessRecord: required.accessRecord } : {}),\n  };\n}\n\nexport async function buildGrantPaymentHeader(params: {\n  payerAddress: `0x${string}`;\n  required: PersonalServerPaymentRequired;\n  config: EscrowPaymentConfig;\n}): Promise<string> {\n  const signed = await signGrantPayment(params);\n  const payment: X402PaymentHeader = {\n    x402Version: 1,\n    scheme: \"vana-escrow-grant\",\n    network: params.required.network ?? `vana:${params.config.chainId}`,\n    payload: signed,\n  };\n  return base64EncodeJson(payment);\n}\n\nexport function paymentReceiptFromHeader(\n  header: string | null | undefined,\n): DirectPaymentReceipt | undefined {\n  if (!header) return undefined;\n  try {\n    return toDirectPaymentReceipt(base64DecodeJson(header) as EscrowPayResult);\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * Authorize an escrow payment for a grant data-access fee.\n *\n * @param params - The payment requirement, the payer address, and escrow config.\n * @returns The gateway's {@link EscrowPayResult} as a typed\n * {@link DirectPaymentReceipt}.\n */\nexport async function authorizeGrantPayment(params: {\n  payerAddress: `0x${string}`;\n  required: PersonalServerPaymentRequired;\n  config: EscrowPaymentConfig;\n}): Promise<DirectPaymentReceipt> {\n  const { payerAddress, required, config } = params;\n  const signed = await signGrantPayment(params);\n\n  const result = await config.client.payForOp({\n    payerAddress,\n    opType: GRANT_OP_TYPE,\n    opId: signed.message.opId,\n    asset: signed.message.asset,\n    amount: signed.message.amount,\n    paymentNonce: signed.message.paymentNonce,\n    signature: signed.signature,\n    accessRecord: required.accessRecord,\n  });\n\n  return toDirectPaymentReceipt(result);\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/direct/escrow-payment.ts"],"sourcesContent":["/**\n * Escrow-backed payment authorization for the Direct Data Controller.\n *\n * @remarks\n * Builds on the DPv2 escrow surface added in `protocol/escrow`. When a Personal\n * Server read returns `402 Payment Required`, the controller settles the\n * challenged operation through the escrow gateway:\n *\n *  1. Sign the challenge's `GenericPayment` EIP-712 message with the app key.\n *  2. POST it to the gateway's `/v1/escrow/pay` via {@link EscrowGatewayClient}.\n *  3. Map the gateway's {@link EscrowPayResult} into a typed\n *     {@link DirectPaymentReceipt} for the caller to inspect.\n *\n * This module supports legacy `\"grant\"` operations and receipt-bound\n * `\"data_access\"` operations. It adapts the escrow `payForOp` flow to the\n * direct-read use case; it does not define its own payment scheme.\n *\n * @category Direct\n * @module direct/escrow-payment\n */\n\nimport {\n  GENERIC_PAYMENT_TYPES,\n  NATIVE_ASSET_ADDRESS,\n  genericPaymentDomain,\n  type EscrowAccessRecord,\n  type EscrowGatewayClient,\n  type EscrowPayResult,\n  type PaymentBreakdown,\n} from \"../protocol/escrow\";\nimport type {\n  DirectFeeBreakdown,\n  DirectPaymentReceipt,\n  DirectPaymentResponseMetadata,\n  PersonalServerPaymentOperation,\n  PersonalServerPaymentRequired,\n} from \"./types\";\n\n/** The escrow `GenericPayment.opType` used for grant-lifecycle payments. */\nexport const GRANT_OP_TYPE = \"grant\" as const;\n/** The escrow `GenericPayment.opType` used for receipt-bound data access. */\nexport const DATA_ACCESS_OP_TYPE = \"data_access\" as const;\n\n/**\n * EIP-712 typed-data signer (e.g. viem `account.signTypedData`).\n *\n * @remarks\n * Kept structurally minimal so any viem account/wallet client satisfies it\n * without the SDK depending on viem's exact `signTypedData` overload set.\n */\nexport type SignTypedDataFn = (args: {\n  domain: ReturnType<typeof genericPaymentDomain>;\n  types: typeof GENERIC_PAYMENT_TYPES;\n  primaryType: \"GenericPayment\";\n  message: {\n    payerAddress: `0x${string}`;\n    opType: string;\n    opId: `0x${string}`;\n    asset: `0x${string}`;\n    amount: bigint;\n    paymentNonce: bigint;\n  };\n}) => Promise<`0x${string}`>;\n\n/** Supplies a monotonically-increasing payment nonce per payer. */\nexport type PaymentNonceSource = (\n  payerAddress: string,\n) => Promise<bigint> | bigint;\n\ninterface EscrowPaymentMessage {\n  payerAddress: `0x${string}`;\n  opType: typeof GRANT_OP_TYPE | typeof DATA_ACCESS_OP_TYPE;\n  opId: `0x${string}`;\n  asset: `0x${string}`;\n  amount: string;\n  paymentNonce: string;\n}\n\ninterface SignedEscrowPayment {\n  message: EscrowPaymentMessage;\n  signature: `0x${string}`;\n  accessRecord?: EscrowAccessRecord;\n}\n\ninterface X402PaymentHeader {\n  x402Version: 1;\n  scheme: \"vana-escrow-grant\";\n  network: string;\n  payload: SignedEscrowPayment;\n}\n\n/** Configuration required to sign an escrow X-PAYMENT header. */\nexport interface EscrowPaymentHeaderConfig {\n  /** Deployed `DataPortabilityEscrow` contract address. */\n  escrowContract: `0x${string}`;\n  /** Chain id for the EIP-712 domain (1480 mainnet, 14800 moksha). */\n  chainId: number;\n  /** App EIP-712 signer. */\n  signTypedData: SignTypedDataFn;\n  /**\n   * Supplies the next payment nonce for a payer. Defaults to a process-local\n   * monotonic counter seeded at 1. Provide a durable source in production so\n   * nonces survive restarts (the gateway rejects reused (payer, nonce) pairs).\n   */\n  nonceSource?: PaymentNonceSource;\n}\n\n/**\n * Escrow settlement configuration for gateway authorization.\n *\n * @remarks\n * Extends the header-signing boundary with the gateway client used by\n * {@link authorizeEscrowPayment}. Existing controller and legacy wrapper\n * callers can continue to provide this full configuration.\n */\nexport interface EscrowPaymentConfig extends EscrowPaymentHeaderConfig {\n  /** Client for the gateway escrow endpoints (`/v1/escrow/*`). */\n  client: EscrowGatewayClient;\n}\n\n/** Map the gateway {@link PaymentBreakdown} into the public {@link DirectFeeBreakdown}. */\nexport function toDirectFeeBreakdown(\n  breakdown: PaymentBreakdown,\n): DirectFeeBreakdown {\n  return {\n    registrationFee: breakdown.registrationFee,\n    dataAccessFee: breakdown.dataAccessFee,\n    registrationPaid: breakdown.registrationPaid,\n  };\n}\n\n/** Map a gateway {@link EscrowPayResult} into the public {@link DirectPaymentReceipt}. */\nexport function toDirectPaymentReceipt(\n  result: EscrowPayResult,\n): DirectPaymentReceipt {\n  return {\n    opType: result.opType,\n    opId: result.opId,\n    asset: result.asset,\n    amount: result.amount,\n    paymentNonce: result.paymentNonce,\n    breakdown: toDirectFeeBreakdown(result.breakdown),\n    paidAt: result.paidAt,\n  };\n}\n\n/** Default in-process monotonic nonce counter (seeded at 1 per payer). */\nexport function createDefaultNonceSource(): PaymentNonceSource {\n  const counters = new Map<string, bigint>();\n  return (payerAddress: string): bigint => {\n    const key = payerAddress.toLowerCase();\n    const next = (counters.get(key) ?? 0n) + 1n;\n    counters.set(key, next);\n    return next;\n  };\n}\n\nconst processLocalNonceSource = createDefaultNonceSource();\nconst UINT256_MAX = (1n << 256n) - 1n;\nconst ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;\nconst BYTES32_RE = /^0x[0-9a-fA-F]{64}$/;\nconst SIGNATURE_RE = /^0x[0-9a-fA-F]{130}$/;\n\nfunction isUint256Decimal(value: string, allowZero: boolean): boolean {\n  const pattern = allowZero ? /^(0|[1-9]\\d*)$/ : /^[1-9]\\d*$/;\n  return (\n    value.length <= UINT256_MAX.toString().length &&\n    pattern.test(value) &&\n    BigInt(value) <= UINT256_MAX\n  );\n}\n\nfunction isValidAccessRecord(record: EscrowAccessRecord): boolean {\n  return (\n    BYTES32_RE.test(record.dataPointId) &&\n    isUint256Decimal(record.version, false) &&\n    ADDRESS_RE.test(record.accessor) &&\n    BYTES32_RE.test(record.recordId) &&\n    SIGNATURE_RE.test(record.signature)\n  );\n}\n\nfunction validateSigningOperation(\n  payerAddress: `0x${string}`,\n  required: PersonalServerPaymentOperation,\n): void {\n  if (!ADDRESS_RE.test(payerAddress)) {\n    throw new Error(\"Payment payer must be a 20-byte EVM address\");\n  }\n  if (!BYTES32_RE.test(required.opId)) {\n    throw new Error(\"Payment operation id must be a 32-byte hex value\");\n  }\n  if (!ADDRESS_RE.test(required.asset || NATIVE_ASSET_ADDRESS)) {\n    throw new Error(\"Payment asset must be a 20-byte EVM address\");\n  }\n  if (!isUint256Decimal(required.amount, true)) {\n    throw new Error(\"Payment amount must be a canonical uint256 decimal\");\n  }\n  if (\n    required.paymentNonce !== undefined &&\n    !isUint256Decimal(required.paymentNonce, false)\n  ) {\n    throw new Error(\"Payment nonce must be a positive uint256 decimal\");\n  }\n\n  const accessRecord = required.accessRecord;\n  if (required.opType === DATA_ACCESS_OP_TYPE) {\n    if (!accessRecord || !isValidAccessRecord(accessRecord)) {\n      throw new Error(\"Data-access payment requires a valid access record\");\n    }\n    if (required.opId.toLowerCase() !== accessRecord.recordId.toLowerCase()) {\n      throw new Error(\n        \"Data-access payment operation id must equal the access record id\",\n      );\n    }\n    if (accessRecord.accessor.toLowerCase() !== payerAddress.toLowerCase()) {\n      throw new Error(\n        \"Data-access payment accessor must equal the payment payer address\",\n      );\n    }\n    return;\n  }\n\n  if (required.amount === \"0\") {\n    if (\n      !accessRecord ||\n      !isValidAccessRecord(accessRecord) ||\n      accessRecord.accessor.toLowerCase() !== payerAddress.toLowerCase()\n    ) {\n      throw new Error(\n        \"Zero-amount grant payments require a valid access record for the payer\",\n      );\n    }\n  }\n}\n\nfunction base64EncodeJson(value: unknown): string {\n  const bytes = new TextEncoder().encode(JSON.stringify(value));\n  let binary = \"\";\n  for (const byte of bytes) binary += String.fromCharCode(byte);\n  return btoa(binary);\n}\n\nfunction base64DecodeJson(value: string): unknown {\n  const binary = atob(value);\n  const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));\n  return JSON.parse(new TextDecoder().decode(bytes));\n}\n\nasync function signEscrowPayment(params: {\n  payerAddress: `0x${string}`;\n  required: PersonalServerPaymentOperation;\n  config: EscrowPaymentHeaderConfig;\n}): Promise<SignedEscrowPayment> {\n  const { payerAddress, required, config } = params;\n  validateSigningOperation(payerAddress, required);\n  const nonceSource = config.nonceSource ?? processLocalNonceSource;\n  const paymentNonce = BigInt(\n    required.paymentNonce ?? (await nonceSource(payerAddress)),\n  );\n  const asset = (required.asset || NATIVE_ASSET_ADDRESS) as `0x${string}`;\n  const opId = required.opId as `0x${string}`;\n  const amount = BigInt(required.amount);\n  if (amount < 0n || amount > UINT256_MAX) {\n    throw new Error(\"Payment amount must be a uint256\");\n  }\n  if (paymentNonce <= 0n || paymentNonce > UINT256_MAX) {\n    throw new Error(\"Payment nonce must be a positive uint256\");\n  }\n\n  const message = {\n    payerAddress,\n    opType: required.opType,\n    opId,\n    asset,\n    amount,\n    paymentNonce,\n  };\n\n  const signature = await config.signTypedData({\n    domain: genericPaymentDomain(config.chainId, config.escrowContract),\n    types: GENERIC_PAYMENT_TYPES,\n    primaryType: \"GenericPayment\",\n    message,\n  });\n\n  return {\n    message: {\n      ...message,\n      amount: amount.toString(),\n      paymentNonce: paymentNonce.toString(),\n    },\n    signature,\n    ...(required.accessRecord ? { accessRecord: required.accessRecord } : {}),\n  };\n}\n\n/**\n * Build the canonical X-PAYMENT header for a validated escrow operation.\n *\n * @remarks\n * Supports both legacy grant payments and receipt-bound data-access payments.\n * Signing is injected through {@link EscrowPaymentHeaderConfig.signTypedData}.\n */\nexport async function buildEscrowPaymentHeader(params: {\n  /** Address whose escrow balance pays for the operation. */\n  payerAddress: `0x${string}`;\n  /** Validated operation parsed from the Personal Server challenge. */\n  required: PersonalServerPaymentOperation;\n  /** Escrow contract, chain, signer, and nonce configuration. */\n  config: EscrowPaymentHeaderConfig;\n}): Promise<string> {\n  const network = params.required.network ?? `vana:${params.config.chainId}`;\n  if (network !== `vana:${params.config.chainId}`) {\n    throw new Error(\"Payment network must match the configured chain\");\n  }\n\n  const signed = await signEscrowPayment(params);\n  const payment: X402PaymentHeader = {\n    x402Version: 1,\n    scheme: \"vana-escrow-grant\",\n    network,\n    payload: signed,\n  };\n  return base64EncodeJson(payment);\n}\n\n/** Build a legacy grant X-PAYMENT header. */\nexport async function buildGrantPaymentHeader(params: {\n  payerAddress: `0x${string}`;\n  required: PersonalServerPaymentRequired;\n  config: EscrowPaymentConfig;\n}): Promise<string> {\n  return buildEscrowPaymentHeader({\n    ...params,\n    required: {\n      ...params.required,\n      opType: GRANT_OP_TYPE,\n      opId: params.required.grantId,\n    },\n  });\n}\n\nfunction asRecord(value: unknown): Record<string, unknown> | undefined {\n  return value && typeof value === \"object\" && !Array.isArray(value)\n    ? (value as Record<string, unknown>)\n    : undefined;\n}\n\nfunction stringField(\n  value: Record<string, unknown> | undefined,\n  key: string,\n): string | undefined {\n  const field = value?.[key];\n  return typeof field === \"string\" ? field : undefined;\n}\n\nfunction isCanonicalIsoTimestamp(value: string): boolean {\n  try {\n    return new Date(value).toISOString() === value;\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Parse shape-validated payment response metadata echoed by a Personal Server.\n *\n * @remarks\n * This metadata is not authenticated by the gateway. It is suitable for\n * display and debugging, not as proof that a payment occurred.\n */\nexport function paymentResponseMetadataFromHeader(\n  header: string | null | undefined,\n): DirectPaymentResponseMetadata | undefined {\n  if (!header) return undefined;\n  try {\n    const result = asRecord(base64DecodeJson(header));\n    const breakdown = asRecord(result?.breakdown);\n    const opType = stringField(result, \"opType\");\n    const opId = stringField(result, \"opId\");\n    const payerAddress = stringField(result, \"payerAddress\");\n    const asset = stringField(result, \"asset\");\n    const amount = stringField(result, \"amount\");\n    const paymentNonce = stringField(result, \"paymentNonce\");\n    const registrationFee = stringField(breakdown, \"registrationFee\");\n    const dataAccessFee = stringField(breakdown, \"dataAccessFee\");\n    const paidAt = stringField(result, \"paidAt\");\n    if (\n      result?.success !== true ||\n      !opType ||\n      !opId ||\n      !BYTES32_RE.test(opId) ||\n      !payerAddress ||\n      !ADDRESS_RE.test(payerAddress) ||\n      !asset ||\n      !ADDRESS_RE.test(asset) ||\n      !amount ||\n      !isUint256Decimal(amount, true) ||\n      !paymentNonce ||\n      !isUint256Decimal(paymentNonce, false) ||\n      !registrationFee ||\n      !isUint256Decimal(registrationFee, true) ||\n      !dataAccessFee ||\n      !isUint256Decimal(dataAccessFee, true) ||\n      typeof breakdown?.registrationPaid !== \"boolean\" ||\n      !paidAt ||\n      !isCanonicalIsoTimestamp(paidAt)\n    ) {\n      return undefined;\n    }\n    return {\n      opType,\n      opId,\n      asset,\n      amount,\n      paymentNonce,\n      breakdown: {\n        registrationFee,\n        dataAccessFee,\n        registrationPaid: breakdown.registrationPaid,\n      },\n      paidAt,\n    };\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * @deprecated Use {@link paymentResponseMetadataFromHeader}. A Personal\n * Server response header is untrusted metadata, not a gateway-authenticated\n * receipt.\n */\nexport function paymentReceiptFromHeader(\n  header: string | null | undefined,\n): DirectPaymentResponseMetadata | undefined {\n  return paymentResponseMetadataFromHeader(header);\n}\n\n/**\n * Authorize an escrow payment for a grant data-access fee.\n *\n * @param params - The payment requirement, the payer address, and escrow config.\n * @returns The gateway's {@link EscrowPayResult} as a typed\n * {@link DirectPaymentReceipt}.\n */\nexport async function authorizeGrantPayment(params: {\n  payerAddress: `0x${string}`;\n  required: PersonalServerPaymentRequired;\n  config: EscrowPaymentConfig;\n}): Promise<DirectPaymentReceipt> {\n  return authorizeEscrowPayment({\n    ...params,\n    required: {\n      ...params.required,\n      opType: GRANT_OP_TYPE,\n      opId: params.required.grantId,\n    },\n  });\n}\n\n/**\n * Authorize a validated grant or data-access operation through the escrow\n * gateway.\n */\nexport async function authorizeEscrowPayment(params: {\n  /** Address whose escrow balance pays for the operation. */\n  payerAddress: `0x${string}`;\n  /** Validated operation to authorize. */\n  required: PersonalServerPaymentOperation;\n  /** Escrow gateway and signing configuration. */\n  config: EscrowPaymentConfig;\n}): Promise<DirectPaymentReceipt> {\n  const { payerAddress, config } = params;\n  const signed = await signEscrowPayment(params);\n\n  const result = await config.client.payForOp({\n    payerAddress,\n    opType: signed.message.opType,\n    opId: signed.message.opId,\n    asset: signed.message.asset,\n    amount: signed.message.amount,\n    paymentNonce: signed.message.paymentNonce,\n    signature: signed.signature,\n    accessRecord: signed.accessRecord,\n  });\n\n  return toDirectPaymentReceipt(result);\n}\n"],"mappings":"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","names":[]}

package/dist/direct/escrow-payment.d.ts

@@ -4,24 +4,26 @@
  * @remarks
  * Builds on the DPv2 escrow surface added in `protocol/escrow`. When a Personal
  * Server read returns `402 Payment Required`, the controller settles the
- * grant's data-access fee through the escrow gateway:
+ * challenged operation through the escrow gateway:
  *
- *  1. Sign a `GenericPayment` EIP-712 message (op `"grant"`, opId = grantId)
- *     with the app key.
+ *  1. Sign the challenge's `GenericPayment` EIP-712 message with the app key.
  *  2. POST it to the gateway's `/v1/escrow/pay` via {@link EscrowGatewayClient}.
  *  3. Map the gateway's {@link EscrowPayResult} into a typed
  *     {@link DirectPaymentReceipt} for the caller to inspect.
  *
- * This module adapts the escrow `payForOp` flow to the direct-read use case; it
- * does not define its own payment scheme.
+ * This module supports legacy `"grant"` operations and receipt-bound
+ * `"data_access"` operations. It adapts the escrow `payForOp` flow to the
+ * direct-read use case; it does not define its own payment scheme.
  *
  * @category Direct
  * @module direct/escrow-payment
  */
-import { GENERIC_PAYMENT_TYPES, genericPaymentDomain, type EscrowGatewayClient, type EscrowPayResult, type PaymentBreakdown } from "../protocol/escrow";
-import type { DirectFeeBreakdown, DirectPaymentReceipt, PersonalServerPaymentRequired } from "./types";
+import { GENERIC_PAYMENT_TYPES, genericPaymentDomain, type EscrowGatewayClient, type EscrowPayResult, type PaymentBreakdown } from "../protocol/escrow.js";
+import type { DirectFeeBreakdown, DirectPaymentReceipt, DirectPaymentResponseMetadata, PersonalServerPaymentOperation, PersonalServerPaymentRequired } from "./types.js";
 /** The escrow `GenericPayment.opType` used for grant-lifecycle payments. */
 export declare const GRANT_OP_TYPE: "grant";
+/** The escrow `GenericPayment.opType` used for receipt-bound data access. */
+export declare const DATA_ACCESS_OP_TYPE: "data_access";
 /**
  * EIP-712 typed-data signer (e.g. viem `account.signTypedData`).
  *
@@ -44,10 +46,8 @@ export type SignTypedDataFn = (args: {
 }) => Promise<`0x${string}`>;
 /** Supplies a monotonically-increasing payment nonce per payer. */
 export type PaymentNonceSource = (payerAddress: string) => Promise<bigint> | bigint;
-/** Escrow settlement configuration for the controller. */
-export interface EscrowPaymentConfig {
-    /** Client for the gateway escrow endpoints (`/v1/escrow/*`). */
-    client: EscrowGatewayClient;
+/** Configuration required to sign an escrow X-PAYMENT header. */
+export interface EscrowPaymentHeaderConfig {
     /** Deployed `DataPortabilityEscrow` contract address. */
     escrowContract: `0x${string}`;
     /** Chain id for the EIP-712 domain (1480 mainnet, 14800 moksha). */
@@ -61,18 +61,59 @@ export interface EscrowPaymentConfig {
      */
     nonceSource?: PaymentNonceSource;
 }
+/**
+ * Escrow settlement configuration for gateway authorization.
+ *
+ * @remarks
+ * Extends the header-signing boundary with the gateway client used by
+ * {@link authorizeEscrowPayment}. Existing controller and legacy wrapper
+ * callers can continue to provide this full configuration.
+ */
+export interface EscrowPaymentConfig extends EscrowPaymentHeaderConfig {
+    /** Client for the gateway escrow endpoints (`/v1/escrow/*`). */
+    client: EscrowGatewayClient;
+}
 /** Map the gateway {@link PaymentBreakdown} into the public {@link DirectFeeBreakdown}. */
 export declare function toDirectFeeBreakdown(breakdown: PaymentBreakdown): DirectFeeBreakdown;
 /** Map a gateway {@link EscrowPayResult} into the public {@link DirectPaymentReceipt}. */
 export declare function toDirectPaymentReceipt(result: EscrowPayResult): DirectPaymentReceipt;
 /** Default in-process monotonic nonce counter (seeded at 1 per payer). */
 export declare function createDefaultNonceSource(): PaymentNonceSource;
+/**
+ * Build the canonical X-PAYMENT header for a validated escrow operation.
+ *
+ * @remarks
+ * Supports both legacy grant payments and receipt-bound data-access payments.
+ * Signing is injected through {@link EscrowPaymentHeaderConfig.signTypedData}.
+ */
+export declare function buildEscrowPaymentHeader(params: {
+    /** Address whose escrow balance pays for the operation. */
+    payerAddress: `0x${string}`;
+    /** Validated operation parsed from the Personal Server challenge. */
+    required: PersonalServerPaymentOperation;
+    /** Escrow contract, chain, signer, and nonce configuration. */
+    config: EscrowPaymentHeaderConfig;
+}): Promise<string>;
+/** Build a legacy grant X-PAYMENT header. */
 export declare function buildGrantPaymentHeader(params: {
     payerAddress: `0x${string}`;
     required: PersonalServerPaymentRequired;
     config: EscrowPaymentConfig;
 }): Promise<string>;
-export declare function paymentReceiptFromHeader(header: string | null | undefined): DirectPaymentReceipt | undefined;
+/**
+ * Parse shape-validated payment response metadata echoed by a Personal Server.
+ *
+ * @remarks
+ * This metadata is not authenticated by the gateway. It is suitable for
+ * display and debugging, not as proof that a payment occurred.
+ */
+export declare function paymentResponseMetadataFromHeader(header: string | null | undefined): DirectPaymentResponseMetadata | undefined;
+/**
+ * @deprecated Use {@link paymentResponseMetadataFromHeader}. A Personal
+ * Server response header is untrusted metadata, not a gateway-authenticated
+ * receipt.
+ */
+export declare function paymentReceiptFromHeader(header: string | null | undefined): DirectPaymentResponseMetadata | undefined;
 /**
  * Authorize an escrow payment for a grant data-access fee.
  *
@@ -85,3 +126,15 @@ export declare function authorizeGrantPayment(params: {
     required: PersonalServerPaymentRequired;
     config: EscrowPaymentConfig;
 }): Promise<DirectPaymentReceipt>;
+/**
+ * Authorize a validated grant or data-access operation through the escrow
+ * gateway.
+ */
+export declare function authorizeEscrowPayment(params: {
+    /** Address whose escrow balance pays for the operation. */
+    payerAddress: `0x${string}`;
+    /** Validated operation to authorize. */
+    required: PersonalServerPaymentOperation;
+    /** Escrow gateway and signing configuration. */
+    config: EscrowPaymentConfig;
+}): Promise<DirectPaymentReceipt>;

package/dist/direct/escrow-payment.js

@@ -4,6 +4,7 @@ import {
   genericPaymentDomain
 } from "../protocol/escrow.js";
 const GRANT_OP_TYPE = "grant";
+const DATA_ACCESS_OP_TYPE = "data_access";
 function toDirectFeeBreakdown(breakdown) {
   return {
     registrationFee: breakdown.registrationFee,
@@ -32,6 +33,58 @@ function createDefaultNonceSource() {
   };
 }
 const processLocalNonceSource = createDefaultNonceSource();
+const UINT256_MAX = (1n << 256n) - 1n;
+const ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
+const BYTES32_RE = /^0x[0-9a-fA-F]{64}$/;
+const SIGNATURE_RE = /^0x[0-9a-fA-F]{130}$/;
+function isUint256Decimal(value, allowZero) {
+  const pattern = allowZero ? /^(0|[1-9]\d*)$/ : /^[1-9]\d*$/;
+  return value.length <= UINT256_MAX.toString().length && pattern.test(value) && BigInt(value) <= UINT256_MAX;
+}
+function isValidAccessRecord(record) {
+  return BYTES32_RE.test(record.dataPointId) && isUint256Decimal(record.version, false) && ADDRESS_RE.test(record.accessor) && BYTES32_RE.test(record.recordId) && SIGNATURE_RE.test(record.signature);
+}
+function validateSigningOperation(payerAddress, required) {
+  if (!ADDRESS_RE.test(payerAddress)) {
+    throw new Error("Payment payer must be a 20-byte EVM address");
+  }
+  if (!BYTES32_RE.test(required.opId)) {
+    throw new Error("Payment operation id must be a 32-byte hex value");
+  }
+  if (!ADDRESS_RE.test(required.asset || NATIVE_ASSET_ADDRESS)) {
+    throw new Error("Payment asset must be a 20-byte EVM address");
+  }
+  if (!isUint256Decimal(required.amount, true)) {
+    throw new Error("Payment amount must be a canonical uint256 decimal");
+  }
+  if (required.paymentNonce !== void 0 && !isUint256Decimal(required.paymentNonce, false)) {
+    throw new Error("Payment nonce must be a positive uint256 decimal");
+  }
+  const accessRecord = required.accessRecord;
+  if (required.opType === DATA_ACCESS_OP_TYPE) {
+    if (!accessRecord || !isValidAccessRecord(accessRecord)) {
+      throw new Error("Data-access payment requires a valid access record");
+    }
+    if (required.opId.toLowerCase() !== accessRecord.recordId.toLowerCase()) {
+      throw new Error(
+        "Data-access payment operation id must equal the access record id"
+      );
+    }
+    if (accessRecord.accessor.toLowerCase() !== payerAddress.toLowerCase()) {
+      throw new Error(
+        "Data-access payment accessor must equal the payment payer address"
+      );
+    }
+    return;
+  }
+  if (required.amount === "0") {
+    if (!accessRecord || !isValidAccessRecord(accessRecord) || accessRecord.accessor.toLowerCase() !== payerAddress.toLowerCase()) {
+      throw new Error(
+        "Zero-amount grant payments require a valid access record for the payer"
+      );
+    }
+  }
+}
 function base64EncodeJson(value) {
   const bytes = new TextEncoder().encode(JSON.stringify(value));
   let binary = "";
@@ -43,18 +96,25 @@ function base64DecodeJson(value) {
   const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));
   return JSON.parse(new TextDecoder().decode(bytes));
 }
-async function signGrantPayment(params) {
+async function signEscrowPayment(params) {
   const { payerAddress, required, config } = params;
+  validateSigningOperation(payerAddress, required);
   const nonceSource = config.nonceSource ?? processLocalNonceSource;
   const paymentNonce = BigInt(
     required.paymentNonce ?? await nonceSource(payerAddress)
   );
   const asset = required.asset || NATIVE_ASSET_ADDRESS;
-  const opId = required.grantId;
+  const opId = required.opId;
   const amount = BigInt(required.amount);
+  if (amount < 0n || amount > UINT256_MAX) {
+    throw new Error("Payment amount must be a uint256");
+  }
+  if (paymentNonce <= 0n || paymentNonce > UINT256_MAX) {
+    throw new Error("Payment nonce must be a positive uint256");
+  }
   const message = {
     payerAddress,
-    opType: GRANT_OP_TYPE,
+    opType: required.opType,
     opId,
     asset,
     amount,
@@ -76,45 +136,116 @@ async function signGrantPayment(params) {
     ...required.accessRecord ? { accessRecord: required.accessRecord } : {}
   };
 }
-async function buildGrantPaymentHeader(params) {
-  const signed = await signGrantPayment(params);
+async function buildEscrowPaymentHeader(params) {
+  const network = params.required.network ?? `vana:${params.config.chainId}`;
+  if (network !== `vana:${params.config.chainId}`) {
+    throw new Error("Payment network must match the configured chain");
+  }
+  const signed = await signEscrowPayment(params);
   const payment = {
     x402Version: 1,
     scheme: "vana-escrow-grant",
-    network: params.required.network ?? `vana:${params.config.chainId}`,
+    network,
     payload: signed
   };
   return base64EncodeJson(payment);
 }
-function paymentReceiptFromHeader(header) {
+async function buildGrantPaymentHeader(params) {
+  return buildEscrowPaymentHeader({
+    ...params,
+    required: {
+      ...params.required,
+      opType: GRANT_OP_TYPE,
+      opId: params.required.grantId
+    }
+  });
+}
+function asRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+function stringField(value, key) {
+  const field = value?.[key];
+  return typeof field === "string" ? field : void 0;
+}
+function isCanonicalIsoTimestamp(value) {
+  try {
+    return new Date(value).toISOString() === value;
+  } catch {
+    return false;
+  }
+}
+function paymentResponseMetadataFromHeader(header) {
   if (!header) return void 0;
   try {
-    return toDirectPaymentReceipt(base64DecodeJson(header));
+    const result = asRecord(base64DecodeJson(header));
+    const breakdown = asRecord(result?.breakdown);
+    const opType = stringField(result, "opType");
+    const opId = stringField(result, "opId");
+    const payerAddress = stringField(result, "payerAddress");
+    const asset = stringField(result, "asset");
+    const amount = stringField(result, "amount");
+    const paymentNonce = stringField(result, "paymentNonce");
+    const registrationFee = stringField(breakdown, "registrationFee");
+    const dataAccessFee = stringField(breakdown, "dataAccessFee");
+    const paidAt = stringField(result, "paidAt");
+    if (result?.success !== true || !opType || !opId || !BYTES32_RE.test(opId) || !payerAddress || !ADDRESS_RE.test(payerAddress) || !asset || !ADDRESS_RE.test(asset) || !amount || !isUint256Decimal(amount, true) || !paymentNonce || !isUint256Decimal(paymentNonce, false) || !registrationFee || !isUint256Decimal(registrationFee, true) || !dataAccessFee || !isUint256Decimal(dataAccessFee, true) || typeof breakdown?.registrationPaid !== "boolean" || !paidAt || !isCanonicalIsoTimestamp(paidAt)) {
+      return void 0;
+    }
+    return {
+      opType,
+      opId,
+      asset,
+      amount,
+      paymentNonce,
+      breakdown: {
+        registrationFee,
+        dataAccessFee,
+        registrationPaid: breakdown.registrationPaid
+      },
+      paidAt
+    };
   } catch {
     return void 0;
   }
 }
+function paymentReceiptFromHeader(header) {
+  return paymentResponseMetadataFromHeader(header);
+}
 async function authorizeGrantPayment(params) {
-  const { payerAddress, required, config } = params;
-  const signed = await signGrantPayment(params);
+  return authorizeEscrowPayment({
+    ...params,
+    required: {
+      ...params.required,
+      opType: GRANT_OP_TYPE,
+      opId: params.required.grantId
+    }
+  });
+}
+async function authorizeEscrowPayment(params) {
+  const { payerAddress, config } = params;
+  const signed = await signEscrowPayment(params);
   const result = await config.client.payForOp({
     payerAddress,
-    opType: GRANT_OP_TYPE,
+    opType: signed.message.opType,
     opId: signed.message.opId,
     asset: signed.message.asset,
     amount: signed.message.amount,
     paymentNonce: signed.message.paymentNonce,
     signature: signed.signature,
-    accessRecord: required.accessRecord
+    accessRecord: signed.accessRecord
   });
   return toDirectPaymentReceipt(result);
 }
 export {
+  DATA_ACCESS_OP_TYPE,
   GRANT_OP_TYPE,
+  authorizeEscrowPayment,
   authorizeGrantPayment,
+  buildEscrowPaymentHeader,
   buildGrantPaymentHeader,
   createDefaultNonceSource,
   paymentReceiptFromHeader,
+  paymentResponseMetadataFromHeader,
   toDirectFeeBreakdown,
   toDirectPaymentReceipt
 };