uvd-x402-sdk 2.45.0 → 2.47.0

package/README.md

@@ -13,9 +13,11 @@ Users sign a message or transaction, and the Ultravioleta facilitator handles on
 - **Type-Safe**: Full TypeScript support
 - **React & Wagmi**: First-class integrations
 - **Signing Wallet Adapters**: EnvKeyAdapter (server/CLI), OWSWalletAdapter (Open Wallet Standard), or bring your own
+- **ERC-8128 Signed Requests**: Authenticate HTTP requests with a wallet (RFC 9421 + EIP-191) — no API keys
 - **ERC-8004 Trustless Agents**: On-chain reputation and identity across 20 networks (18 EVM + 2 Solana)
 - **Escrow & Refunds**: Hold payments with dispute resolution
 - **Advanced Escrow**: Full escrow lifecycle (authorize, release, refund, charge) with SigningWalletAdapter support
+- **Escrow Pre-Auth**: Sign-on-assignment `X-Payment-Auth` builder (`buildEscrowPreAuth`) — vector-pinned parity with the Python SDK and Execution Market
 - **Commerce Scheme**: `'commerce'` scheme alias for marketplace integrations (identical to `'escrow'` on-chain)
 - **`/accepts` Negotiation**: Discover facilitator capabilities before constructing payments
 - **Bazaar Discovery**: Register and discover paid resources across the x402 network
@@ -586,6 +588,69 @@ class MyAdapter implements SigningWalletAdapter {
 }
 ```
 
+## ERC-8128 Signed Requests
+
+Authenticate HTTP requests with a wallet instead of an API key. The SDK builds the RFC 9421 signature base, signs it with EIP-191 personal_sign, and produces the `Signature`, `Signature-Input`, and (for bodies) `Content-Digest` headers. Used by APIs that only accept wallet signing, like [Execution Market](https://execution.market).
+
+Wire format is pinned by golden vectors (`src/erc8128.vectors.json`): `alg="eip191"`, keyid always lowercase (`erc8128:{chainId}:{address}`), params in the order `created;expires;nonce;keyid;alg`.
+
+```typescript
+import { createSignedFetch, EnvKeyAdapter } from 'uvd-x402-sdk';
+
+// Auto-signing fetch: fetches a fresh nonce and signs every request
+const signedFetch = createSignedFetch({
+  wallet: new EnvKeyAdapter(),           // or privateKey: process.env.KEY!
+  apiBase: 'https://api.execution.market',
+  chainId: 8453,                          // Base (default)
+});
+
+const resp = await signedFetch('/api/v1/tasks', {
+  method: 'POST',
+  body: JSON.stringify({ title: 'test' }),
+});
+```
+
+For manual control, sign a single request (the nonce is single-use — fetch one per request):
+
+```typescript
+import { fetchNonce, signRequestWithWallet, EnvKeyAdapter } from 'uvd-x402-sdk';
+
+const wallet = new EnvKeyAdapter();
+const nonce = await fetchNonce('https://api.execution.market');
+const headers = await signRequestWithWallet(wallet, {
+  method: 'POST',
+  url: 'https://api.execution.market/api/v1/tasks',
+  body: '{"title":"test"}',
+  nonce,
+});
+// headers = { Signature, 'Signature-Input', 'Content-Digest' } — merge into your request
+```
+
+Also available: `signRequest` (raw private key) and `signRequestWithSigner` (callback-based, for browser wallets / out-of-process signers where the key never leaves the signer), plus `buildSignatureBase` / `buildSignatureParams` to reproduce the exact signed bytes externally.
+
+## Escrow Pre-Auth (sign-on-assignment)
+
+Build and sign the EIP-3009 `ReceiveWithAuthorization` that locks a bounty in the x402r AuthCaptureEscrow, packed as the raw-JSON `X-Payment-Auth` wrapper the facilitator's `/settle` expects. Used by marketplaces on the escrow rail (e.g. [Execution Market](https://execution.market)'s universal escrow).
+
+The EIP-3009 nonce is `AuthCaptureEscrow.getHash(paymentInfo)`, which **includes the receiver** — the signature cryptographically commits to the chosen worker, so it can only be created AT ASSIGNMENT. The wire format is pinned by golden vectors (`src/escrow-preauth.vectors.json`) shared with the Python SDK and Execution Market's dashboard/mobile suites.
+
+```typescript
+import { buildEscrowPreAuth, EnvKeyAdapter } from 'uvd-x402-sdk';
+
+// Escrow config as published by the marketplace server
+// (e.g. Execution Market's GET /api/v1/h2a/payment-config).
+const paymentAuth = await buildEscrowPreAuth(new EnvKeyAdapter(), {
+  networkConfig: config.escrow.networks.base,
+  payerWallet: '0xPublisher...',
+  workerWallet: '0xWorker...',        // escrow receiver — committed by the nonce
+  bountyAtomic: '100000',             // $0.10 in 6-decimal USDC
+  reviewDeadlineSec: taskDeadline,    // release window outlasts it
+});
+// Send as the X-Payment-Auth header (raw JSON, NOT base64).
+```
+
+Any `SigningWalletAdapter` works as the signer (only `signTypedData` is used); browser wallets can pass a minimal `{ signTypedData }` wrapper. Validation fails loud instead of falling back: incomplete network config, unknown tier, bounty outside the on-chain deposit limit ($100), or a `maxFeeBps` below the operator's 1300 bps all throw before anything is signed. `computeEscrowNonce` is exported to reproduce `AuthCaptureEscrow.getHash` externally.
+
 ## Multi-Stablecoin (EVM)
 
 ```typescript
@@ -1098,6 +1163,29 @@ const body = buildVerifyRequestV2(
 > error that names no field. If you see it, check the envelope shape first, not
 > the fields inside it.
 
+## Metrics and history (`getStats` / `getTransactions`)
+
+```typescript
+const stats = await client.getStats();
+for (const row of stats.byNetworkAndAsset) {
+  // Use the row's OWN decimals. USDC is 6 nearly everywhere and 18 on BSC —
+  // scaling by a constant 6 overstates BSC volume by 10^12.
+  console.log(row.network, row.settlesOk, row.volumeAtomic, row.decimals);
+}
+
+const recent = await client.getTransactions({ limit: 20, network: 'base' });
+```
+
+> **An index, not a ledger.** Records are written best-effort *after*
+> settlement, so an outage loses rows while payments proceed — verify anything
+> that matters against the transaction hash. Counting starts when the operator
+> enabled the store, so earlier operations are **unknown, not zero**. And unless
+> failure publishing is on, operations that error are not recorded at all, so a
+> 100% success rate means "no failures were recorded".
+>
+> `getTransactions` has **no pagination**: it returns the newest N (capped at
+> 200), walking back at most 30 days.
+
 ## Live Traffic Stream (`GET /events`)
 
 The facilitator emits one Server-Sent Event per operation it handles, so you can

package/dist/adapters/index.d.mts

@@ -1,6 +1,6 @@
-import { X as X402Version, b as PaymentResult } from '../index-DgChnK_c.mjs';
-export { E as EnvKeyAdapter, O as OWSWallet, a as OWSWalletAdapter } from '../ows-CYIVd4xO.mjs';
-import '../wallet-0cX9Pw2F.mjs';
+import { X as X402Version, b as PaymentResult } from '../index-CVW8AhRX.mjs';
+export { E as EnvKeyAdapter, O as OWSWallet, a as OWSWalletAdapter } from '../ows-Z9v4GxOZ.mjs';
+import '../wallet-w7BnImDG.mjs';
 
 /**
  * uvd-x402-sdk - Wagmi/Viem Adapter

package/dist/adapters/index.d.ts

@@ -1,6 +1,6 @@
-import { X as X402Version, b as PaymentResult } from '../index-DgChnK_c.js';
-export { E as EnvKeyAdapter, O as OWSWallet, a as OWSWalletAdapter } from '../ows-DTDixPzO.js';
-import '../wallet-0cX9Pw2F.js';
+import { X as X402Version, b as PaymentResult } from '../index-CVW8AhRX.js';
+export { E as EnvKeyAdapter, O as OWSWallet, a as OWSWalletAdapter } from '../ows-C-KmORG9.js';
+import '../wallet-w7BnImDG.js';
 
 /**
  * uvd-x402-sdk - Wagmi/Viem Adapter

package/dist/backend/index.d.mts

@@ -1,5 +1,5 @@
-import { S as SigningWalletAdapter } from '../wallet-0cX9Pw2F.mjs';
-import { e as X402Header, X as X402Version, f as X402PayloadData } from '../index-DgChnK_c.mjs';
+import { S as SigningWalletAdapter } from '../wallet-w7BnImDG.mjs';
+import { e as X402Header, X as X402Version, f as X402PayloadData } from '../index-CVW8AhRX.mjs';
 
 /**
  * Payment requirements sent to the facilitator
@@ -442,6 +442,61 @@ declare class FacilitatorClient {
         }>;
         [key: string]: unknown;
     }>;
+    /**
+     * Aggregated totals per network and asset (`GET /api/stats`).
+     *
+     * **An index, not a ledger.** Records are written best-effort AFTER
+     * settlement, so an outage loses rows while payments proceed — verify
+     * anything that matters against the transaction hash. Counting starts when
+     * the operator enabled the store, so earlier operations are UNKNOWN, not
+     * zero. And unless `X402_EVENTS_PUBLISH_FAILURES=true`, operations that ERROR
+     * are not recorded at all: a 100% success rate means "no failures were
+     * recorded".
+     *
+     * `volumeAtomic` is a STRING (u256-shaped; a JS number loses precision above
+     * 2^53) and each row carries its own `decimals`. **Use that, never a
+     * constant** — USDC is 6 decimals nearly everywhere and 18 on BSC, so scaling
+     * by 6 there overstates volume by 10^12. `decimals` is null when the asset is
+     * unrecognised; render the atomic value rather than guessing a scale.
+     */
+    getStats(): Promise<{
+        totals: {
+            settlesOk: number;
+            settlesFailed: number;
+            verifies: number;
+            networks: number;
+        };
+        byNetworkAndAsset: Array<{
+            network: string;
+            asset: string;
+            settlesOk: number;
+            settlesFailed: number;
+            verifies: number;
+            volumeAtomic: string;
+            decimals: number | null;
+            lastTs: number;
+        }>;
+        [key: string]: unknown;
+    }>;
+    /**
+     * Recent recorded operations, newest first (`GET /transactions`).
+     *
+     * There is **no pagination and no cursor**: this returns the newest N,
+     * walking back at most 30 days. With 10,000 rows you get the newest 200, not
+     * page one of fifty. `limit` is clamped to 200 by the facilitator.
+     *
+     * `network` matches the canonical slug `/supported` uses, which is not always
+     * the alias you may send — `skale` is accepted inbound but records say
+     * `skale-base`.
+     */
+    getTransactions(options?: {
+        limit?: number;
+        network?: string;
+    }): Promise<{
+        transactions: Array<Record<string, unknown>>;
+        count: number;
+        [key: string]: unknown;
+    }>;
     /**
      * Get the facilitator's blocked/sanctioned addresses
      *

package/dist/backend/index.d.ts

@@ -1,5 +1,5 @@
-import { S as SigningWalletAdapter } from '../wallet-0cX9Pw2F.js';
-import { e as X402Header, X as X402Version, f as X402PayloadData } from '../index-DgChnK_c.js';
+import { S as SigningWalletAdapter } from '../wallet-w7BnImDG.js';
+import { e as X402Header, X as X402Version, f as X402PayloadData } from '../index-CVW8AhRX.js';
 
 /**
  * Payment requirements sent to the facilitator
@@ -442,6 +442,61 @@ declare class FacilitatorClient {
         }>;
         [key: string]: unknown;
     }>;
+    /**
+     * Aggregated totals per network and asset (`GET /api/stats`).
+     *
+     * **An index, not a ledger.** Records are written best-effort AFTER
+     * settlement, so an outage loses rows while payments proceed — verify
+     * anything that matters against the transaction hash. Counting starts when
+     * the operator enabled the store, so earlier operations are UNKNOWN, not
+     * zero. And unless `X402_EVENTS_PUBLISH_FAILURES=true`, operations that ERROR
+     * are not recorded at all: a 100% success rate means "no failures were
+     * recorded".
+     *
+     * `volumeAtomic` is a STRING (u256-shaped; a JS number loses precision above
+     * 2^53) and each row carries its own `decimals`. **Use that, never a
+     * constant** — USDC is 6 decimals nearly everywhere and 18 on BSC, so scaling
+     * by 6 there overstates volume by 10^12. `decimals` is null when the asset is
+     * unrecognised; render the atomic value rather than guessing a scale.
+     */
+    getStats(): Promise<{
+        totals: {
+            settlesOk: number;
+            settlesFailed: number;
+            verifies: number;
+            networks: number;
+        };
+        byNetworkAndAsset: Array<{
+            network: string;
+            asset: string;
+            settlesOk: number;
+            settlesFailed: number;
+            verifies: number;
+            volumeAtomic: string;
+            decimals: number | null;
+            lastTs: number;
+        }>;
+        [key: string]: unknown;
+    }>;
+    /**
+     * Recent recorded operations, newest first (`GET /transactions`).
+     *
+     * There is **no pagination and no cursor**: this returns the newest N,
+     * walking back at most 30 days. With 10,000 rows you get the newest 200, not
+     * page one of fifty. `limit` is clamped to 200 by the facilitator.
+     *
+     * `network` matches the canonical slug `/supported` uses, which is not always
+     * the alias you may send — `skale` is accepted inbound but records say
+     * `skale-base`.
+     */
+    getTransactions(options?: {
+        limit?: number;
+        network?: string;
+    }): Promise<{
+        transactions: Array<Record<string, unknown>>;
+        count: number;
+        [key: string]: unknown;
+    }>;
     /**
      * Get the facilitator's blocked/sanctioned addresses
      *

package/dist/backend/index.js

@@ -1227,9 +1227,15 @@ var FacilitatorClient = class {
         };
       }
       const result = await response.json();
+      const transactionHash = result.transaction ?? result.transactionHash ?? result.transaction_hash;
+      if (result.success && !transactionHash) {
+        console.warn(
+          "[x402] settle reported success but carried no transaction hash under transaction/transactionHash/transaction_hash \u2014 treat delivery as unconfirmed"
+        );
+      }
       return {
         success: true,
-        transactionHash: result.transactionHash || result.transaction_hash,
+        transactionHash,
         network: result.network
       };
     } catch (error) {
@@ -1320,6 +1326,57 @@ var FacilitatorClient = class {
     }
     return await response.json();
   }
+  /**
+   * Aggregated totals per network and asset (`GET /api/stats`).
+   *
+   * **An index, not a ledger.** Records are written best-effort AFTER
+   * settlement, so an outage loses rows while payments proceed — verify
+   * anything that matters against the transaction hash. Counting starts when
+   * the operator enabled the store, so earlier operations are UNKNOWN, not
+   * zero. And unless `X402_EVENTS_PUBLISH_FAILURES=true`, operations that ERROR
+   * are not recorded at all: a 100% success rate means "no failures were
+   * recorded".
+   *
+   * `volumeAtomic` is a STRING (u256-shaped; a JS number loses precision above
+   * 2^53) and each row carries its own `decimals`. **Use that, never a
+   * constant** — USDC is 6 decimals nearly everywhere and 18 on BSC, so scaling
+   * by 6 there overstates volume by 10^12. `decimals` is null when the asset is
+   * unrecognised; render the atomic value rather than guessing a scale.
+   */
+  async getStats() {
+    const response = await fetch(`${this.baseUrl}/api/stats`, { method: "GET" });
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(`GET /api/stats failed: ${response.status} - ${errorText}`);
+    }
+    return await response.json();
+  }
+  /**
+   * Recent recorded operations, newest first (`GET /transactions`).
+   *
+   * There is **no pagination and no cursor**: this returns the newest N,
+   * walking back at most 30 days. With 10,000 rows you get the newest 200, not
+   * page one of fifty. `limit` is clamped to 200 by the facilitator.
+   *
+   * `network` matches the canonical slug `/supported` uses, which is not always
+   * the alias you may send — `skale` is accepted inbound but records say
+   * `skale-base`.
+   */
+  async getTransactions(options = {}) {
+    const params = new URLSearchParams();
+    if (options.limit !== void 0) params.set("limit", String(options.limit));
+    if (options.network) params.set("network", options.network);
+    const query = params.toString();
+    const response = await fetch(
+      `${this.baseUrl}/transactions${query ? `?${query}` : ""}`,
+      { method: "GET" }
+    );
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(`GET /transactions failed: ${response.status} - ${errorText}`);
+    }
+    return await response.json();
+  }
   /**
    * Get the facilitator's blocked/sanctioned addresses
    *