uvd-x402-sdk 2.62.0 → 2.64.0

package/README.md

@@ -1280,3 +1280,92 @@ const isHealthy = await client.healthCheck();
 ## License
 
 MIT
+
+## DX402 — evidence that outlives the session
+
+x402 settles payment on-chain forever but delivers the resource **once** and
+keeps nothing. DX402 seals a copy of the response to the payer's own public key
+— recovered from the payment signature itself — and anchors it. No registration,
+no extra round trip: paying *is* publishing your encryption key.
+
+### Seller: one call
+
+```ts
+import { anchorEvidence, evidenceHeader } from 'uvd-x402-sdk';
+
+const result = await anchorEvidence(body, {
+  paymentId, network: 'base', txHash,
+  payer: payerAddr, payee: myAddr, payerKey: payerPubkey,
+  sign: (digest) => myCustodian.sign(digest),   // a callable, not a key
+});
+res.setHeader('X-Durable-Evidence', evidenceHeader(result));
+```
+
+**It never throws.** Every failure resolves to `result.skipped`, because
+evidence is an addition to the payment path and must never be a gate in front of
+it. An unreachable facilitator costs the receipt, never the sale.
+
+`sign` takes a **callable rather than a private key** so a custodian can sign:
+it receives the 32-byte digest and returns a signature without the seed ever
+leaving it.
+
+### Buyer: come back months later
+
+```ts
+import { recoverEvidence, evidenceFromHeaders } from 'uvd-x402-sdk';
+
+const evidence = evidenceFromHeaders(res.headers);
+const body = await recoverEvidence(evidence, myPrivateKey);
+```
+
+This needs permission from nobody. The ciphertext was sealed to the wallet that
+paid, so recovery is arithmetic rather than an access-control decision anyone
+could refuse. The `contentHash` check runs automatically and throws
+`ContentHashMismatch` — it is what catches a seller who anchored something other
+than what it served.
+
+### `verified` vs `signed` — read this before you branch on either
+
+Since facilitator **1.87.0** a signature alone does not make an anchor final:
+
+| field | means | supersedable by |
+|---|---|---|
+| `verified: true` | the **chain** confirmed this address is the payee | nothing — final |
+| `signed: true` | the claimant controls the address it *declared* | a verified anchor |
+| neither | anyone could have written it | either of the above |
+
+To reach `verified` you must send `proofOfPayment`. Without it the facilitator
+has checked no chain and answers `notVerifiedReason: "dx402_proof_missing"` —
+your signature was still accepted (`signed: true`), authorship simply was not
+certified.
+
+Why the split: `verified` was previously decided against the `payee` field *in
+the request*, which the caller supplies. Proving "I control the address I typed
+into my own request" was enough to own a stranger's evidence permanently.
+
+### Choosing where evidence is stored
+
+```ts
+import { availableBackends } from 'uvd-x402-sdk';
+
+for (const b of await availableBackends()) {
+  console.log(b.id, b.retention, b.revocable ? 'deletable' : 'IRREVERSIBLE');
+}
+
+await anchorEvidence(body, { ...opts, storage: 'ipfs-private' });
+```
+
+Ask rather than assume: what exists depends on the deployment, and you may be
+pointed at a facilitator that is not ours. `revocable: false` means the
+`retentionUntil` in the **signed** receipt cannot be honoured — on public IPFS,
+unpinning removes the facilitator's copy, not the network's.
+
+### Limits
+
+- Inline anchors cap at **64 KiB of request** (~47 KB of plaintext); the SDK
+  returns `skipped: 'too_large'` before touching the network.
+- Anchoring with `retention: 'permanent'` is **irrevocable**.
+- On Solana, `verified` is not reachable yet — the on-chain gate cannot read
+  that payment, so `signed: true` is the honest maximum.
+
+Full guide: [DX402.md](https://github.com/UltravioletaDAO/x402-rs/blob/main/docs/DX402.md)

package/dist/backend/index.d.mts

@@ -2342,7 +2342,10 @@ declare class AdvancedEscrowClient {
      * @param tier - Task tier determines timing parameters
      * @param salt - Random salt (auto-generated if not provided)
      */
-    buildPaymentInfo(receiver: string, amount: string, tier?: AdvancedEscrowTaskTier, salt?: string): AdvancedPaymentInfo;
+    buildPaymentInfo(receiver: string, amount: string, tier?: AdvancedEscrowTaskTier, salt?: string, opts?: {
+        deadline?: number;
+        reviewWindowSec?: number;
+    }): AdvancedPaymentInfo;
     /**
      * Compute the correct nonce (with PAYMENT_INFO_TYPEHASH).
      * Matches the on-chain AuthCaptureEscrow nonce derivation.

package/dist/backend/index.d.ts

@@ -2342,7 +2342,10 @@ declare class AdvancedEscrowClient {
      * @param tier - Task tier determines timing parameters
      * @param salt - Random salt (auto-generated if not provided)
      */
-    buildPaymentInfo(receiver: string, amount: string, tier?: AdvancedEscrowTaskTier, salt?: string): AdvancedPaymentInfo;
+    buildPaymentInfo(receiver: string, amount: string, tier?: AdvancedEscrowTaskTier, salt?: string, opts?: {
+        deadline?: number;
+        reviewWindowSec?: number;
+    }): AdvancedPaymentInfo;
     /**
      * Compute the correct nonce (with PAYMENT_INFO_TYPEHASH).
      * Matches the on-chain AuthCaptureEscrow nonce derivation.

package/dist/backend/index.js

@@ -1,5 +1,7 @@
 'use strict';
 
+require('ethers');
+
 var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
   get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
 }) : x)(function(x) {
@@ -1088,6 +1090,8 @@ function decodeX402Header(encoded) {
   const json = decodeBase64Utf8(encoded);
   return JSON.parse(json);
 }
+var REVIEW_WINDOW_SEC = 7 * 24 * 3600;
+var REFUND_WINDOW_SEC = 7 * 24 * 3600;
 
 // src/backend/index.ts
 function parsePaymentHeader(headerValue) {
@@ -3504,9 +3508,13 @@ var AdvancedEscrowClient = class {
    * @param tier - Task tier determines timing parameters
    * @param salt - Random salt (auto-generated if not provided)
    */
-  buildPaymentInfo(receiver, amount, tier = "standard", salt) {
+  buildPaymentInfo(receiver, amount, tier = "standard", salt, opts) {
     const now = Math.floor(Date.now() / 1e3);
     const t = TIER_TIMINGS[tier];
+    const reviewWindow = opts?.reviewWindowSec ?? REVIEW_WINDOW_SEC;
+    const reviewBase = Math.max(now, opts?.deadline ?? now);
+    const authorizationExpiry = Math.max(now + t.auth, reviewBase + reviewWindow);
+    const refundExpiry = Math.max(now + t.refund, authorizationExpiry + REFUND_WINDOW_SEC);
     let generatedSalt = salt;
     if (!generatedSalt) {
       const bytes = new Uint8Array(32);
@@ -3525,8 +3533,8 @@ var AdvancedEscrowClient = class {
       token: this.contracts.usdc,
       maxAmount: amount,
       preApprovalExpiry: now + t.pre,
-      authorizationExpiry: now + t.auth,
-      refundExpiry: now + t.refund,
+      authorizationExpiry,
+      refundExpiry,
       minFeeBps: 0,
       maxFeeBps: 800,
       feeReceiver: this.contracts.operator,
@@ -3538,8 +3546,8 @@ var AdvancedEscrowClient = class {
    * Matches the on-chain AuthCaptureEscrow nonce derivation.
    */
   async computeNonce(paymentInfo) {
-    const { ethers } = await import('ethers');
-    const piTuple = ethers.AbiCoder.defaultAbiCoder().encode(
+    const { ethers: ethers2 } = await import('ethers');
+    const piTuple = ethers2.AbiCoder.defaultAbiCoder().encode(
       ["bytes32", "tuple(address,address,address,address,uint120,uint48,uint48,uint48,uint16,uint16,address,uint256)"],
       [
         PAYMENT_INFO_TYPEHASH,
@@ -3560,12 +3568,12 @@ var AdvancedEscrowClient = class {
         ]
       ]
     );
-    const piHash = ethers.keccak256(piTuple);
-    const finalEncoded = ethers.AbiCoder.defaultAbiCoder().encode(
+    const piHash = ethers2.keccak256(piTuple);
+    const finalEncoded = ethers2.AbiCoder.defaultAbiCoder().encode(
       ["uint256", "address", "bytes32"],
       [this.chainId, this.contracts.escrow, piHash]
     );
-    return ethers.keccak256(finalEncoded);
+    return ethers2.keccak256(finalEncoded);
   }
   /**
    * Sign ReceiveWithAuthorization for ERC-3009.
@@ -3722,17 +3730,17 @@ var AdvancedEscrowClient = class {
   async release(paymentInfo, amount) {
     if (!this.payerAddress) await this.init();
     try {
-      const { ethers } = await import('ethers');
+      const { ethers: ethers2 } = await import('ethers');
       const isCreate3 = CREATE3_CHAIN_IDS.has(this.chainId);
       const abi = isCreate3 ? OPERATOR_ABI_CREATE3 : OPERATOR_ABI;
       const amt = amount || paymentInfo.maxAmount;
       const tuple = this.buildTuple(paymentInfo);
       if (this.walletAdapter) {
-        return this.sendViaAdapter(ethers, abi, (iface) => {
+        return this.sendViaAdapter(ethers2, abi, (iface) => {
           return isCreate3 ? iface.encodeFunctionData("release", [tuple, amt, "0x"]) : iface.encodeFunctionData("release", [tuple, amt]);
         });
       }
-      const contract = new ethers.Contract(this.contracts.operator, abi, this.signer);
+      const contract = new ethers2.Contract(this.contracts.operator, abi, this.signer);
       const tx = isCreate3 ? await contract.release(tuple, amt, "0x", { gasLimit: this.gasLimit }) : await contract.release(tuple, amt, { gasLimit: this.gasLimit });
       const receipt = await tx.wait();
       return {
@@ -3756,17 +3764,17 @@ var AdvancedEscrowClient = class {
   async refundInEscrow(paymentInfo, amount) {
     if (!this.payerAddress) await this.init();
     try {
-      const { ethers } = await import('ethers');
+      const { ethers: ethers2 } = await import('ethers');
       const isCreate3 = CREATE3_CHAIN_IDS.has(this.chainId);
       const abi = isCreate3 ? OPERATOR_ABI_CREATE3 : OPERATOR_ABI;
       const amt = amount || paymentInfo.maxAmount;
       const tuple = this.buildTuple(paymentInfo);
       if (this.walletAdapter) {
-        return this.sendViaAdapter(ethers, abi, (iface) => {
+        return this.sendViaAdapter(ethers2, abi, (iface) => {
           return isCreate3 ? iface.encodeFunctionData("refundInEscrow", [tuple, amt, "0x"]) : iface.encodeFunctionData("refundInEscrow", [tuple, amt]);
         });
       }
-      const contract = new ethers.Contract(this.contracts.operator, abi, this.signer);
+      const contract = new ethers2.Contract(this.contracts.operator, abi, this.signer);
       const tx = isCreate3 ? await contract.refundInEscrow(tuple, amt, "0x", { gasLimit: this.gasLimit }) : await contract.refundInEscrow(tuple, amt, { gasLimit: this.gasLimit });
       const receipt = await tx.wait();
       return {
@@ -4029,7 +4037,7 @@ var AdvancedEscrowClient = class {
   async charge(paymentInfo, amount) {
     if (!this.payerAddress) await this.init();
     try {
-      const { ethers } = await import('ethers');
+      const { ethers: ethers2 } = await import('ethers');
       const nonce = await this.computeNonce(paymentInfo);
       const amt = amount || paymentInfo.maxAmount;
       const auth = {
@@ -4041,10 +4049,10 @@ var AdvancedEscrowClient = class {
         nonce
       };
       const signature = await this.signErc3009(auth);
-      const collectorData = ethers.getBytes(signature);
+      const collectorData = ethers2.getBytes(signature);
       const tuple = this.buildTuple(paymentInfo);
       if (this.walletAdapter) {
-        return this.sendViaAdapter(ethers, OPERATOR_ABI, (iface) => {
+        return this.sendViaAdapter(ethers2, OPERATOR_ABI, (iface) => {
           return iface.encodeFunctionData("charge", [
             tuple,
             amt,
@@ -4053,7 +4061,7 @@ var AdvancedEscrowClient = class {
           ]);
         });
       }
-      const contract = new ethers.Contract(this.contracts.operator, OPERATOR_ABI, this.signer);
+      const contract = new ethers2.Contract(this.contracts.operator, OPERATOR_ABI, this.signer);
       const tx = await contract.charge(
         tuple,
         amt,
@@ -4095,11 +4103,11 @@ var AdvancedEscrowClient = class {
   async refundPostEscrow(paymentInfo, amount, tokenCollector, collectorData) {
     if (!this.payerAddress) await this.init();
     try {
-      const { ethers } = await import('ethers');
+      const { ethers: ethers2 } = await import('ethers');
       const amt = amount || paymentInfo.maxAmount;
       const tuple = this.buildTuple(paymentInfo);
       if (this.walletAdapter) {
-        return this.sendViaAdapter(ethers, OPERATOR_ABI, (iface) => {
+        return this.sendViaAdapter(ethers2, OPERATOR_ABI, (iface) => {
           return iface.encodeFunctionData("refundPostEscrow", [
             tuple,
             amt,
@@ -4108,7 +4116,7 @@ var AdvancedEscrowClient = class {
           ]);
         });
       }
-      const contract = new ethers.Contract(this.contracts.operator, OPERATOR_ABI, this.signer);
+      const contract = new ethers2.Contract(this.contracts.operator, OPERATOR_ABI, this.signer);
       const tx = await contract.refundPostEscrow(
         tuple,
         amt,