uvd-x402-sdk 2.63.0 → 2.65.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)