uvd-x402-sdk 2.63.0 → 2.64.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uvd-x402-sdk",
-  "version": "2.63.0",
+  "version": "2.64.0",
   "description": "x402 Payment SDK - Gasless crypto payments across 25 blockchains via Ultravioleta facilitator. Supports EVM (including Scroll, SKALE Base, Robinhood Chain), Solana, Fogo, Stellar, NEAR, Algorand, Sui, and XRP Ledger. Features: ERC-8004 Trustless Agents, Escrow/Refunds, multi-stablecoin (USDC, EURC, AUSD, PYUSD, USDT, USDG).",
   "author": "Ultravioleta DAO <ultravioletadao@gmail.com>",
   "license": "MIT",

package/src/dx402.ts

@@ -836,6 +836,17 @@ export interface AnchorOptions {
    * proves more may supersede it.
    */
   proofOfPayment?: Record<string, unknown>;
+  /**
+   * Which backend to anchor to (`"s3"`, `"ipfs-private"`, `"ipfs-public"`).
+   * Omit to take the facilitator's default.
+   *
+   * Ask {@link availableBackends} what a given facilitator offers rather than
+   * assuming — it depends on the deployment, and you may be pointed at one that
+   * is not ours. **`ipfs-public` is irreversible**: the bytes become permanently
+   * resolvable by anyone, and nobody, the facilitator included, can take them
+   * down.
+   */
+  storage?: string;
   /**
    * `(digest) => "0x..."`. A callable rather than a private key is what lets a
    * custodian sign: it receives the digest and returns the signature without the
@@ -969,6 +980,10 @@ export async function anchorEvidence(
       payload.proofOfPayment = opts.proofOfPayment;
     }
 
+    if (opts.storage) {
+      payload.storage = opts.storage;
+    }
+
     if (opts.sign) {
       const digest = sellerDigestFor(opts.paymentId, hash, opts.payee, opts.network);
       if (digest === undefined) {
@@ -1020,6 +1035,50 @@ export async function anchorEvidence(
   }
 }
 
+/** One storage option a facilitator offers, from `GET /dx402/stats`. */
+export interface BackendOffer {
+  id: string;
+  retention: string;
+  /**
+   * Whether the bytes can actually be removed when retention expires.
+   *
+   * `false` means the `retentionUntil` in the signed receipt **cannot be
+   * honoured**: on public IPFS, unpinning removes the facilitator's copy, not
+   * the network's.
+   */
+  revocable: boolean;
+  /** Whether anyone resolves the bytes without going through the facilitator. */
+  public: boolean;
+  enabled: boolean;
+  disabledReason?: string;
+}
+
+/**
+ * Ask a facilitator which storage backends it actually offers.
+ *
+ * Ask instead of assuming. What exists depends on the deployment — one without
+ * a Pinata credential offers only `s3` — and an integrator may be pointed at a
+ * facilitator that is not ours. A hardcoded list in your code is a promise
+ * somebody else has to keep.
+ *
+ * Resolves to `[]` rather than rejecting when the facilitator is unreachable or
+ * does not run DX402 — same discipline as {@link anchorEvidence}.
+ */
+export async function availableBackends(
+  facilitator = 'https://facilitator.ultravioletadao.xyz',
+  opts: { fetch?: typeof fetch } = {},
+): Promise<BackendOffer[]> {
+  try {
+    const doFetch = opts.fetch ?? fetch;
+    const res = await doFetch(`${facilitator.replace(/\/+$/, '')}/dx402/stats`);
+    if (!res.ok) return [];
+    const body = (await res.json()) as { backends?: BackendOffer[] };
+    return body.backends ?? [];
+  } catch {
+    return [];
+  }
+}
+
 /** Encode an anchor result for the `X-Durable-Evidence` response header. */
 export function evidenceHeader(evidence: unknown): string {
   // Encode to UTF-8 first. `btoa` takes a *binary* string: any code point above

package/src/index.ts

@@ -144,6 +144,8 @@ export {
   sealEvidenceTo,
   payerKeyFromSolanaAddress,
   anchorEvidence,
+  availableBackends,
+  type BackendOffer,
   // Reachable only via a deep import before this: the helper that exists so
   // nobody hand-builds a digest was the one you had to already know about.
   sellerDigestFor,