uvd-x402-sdk 2.46.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

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

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

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) {