uvd-x402-sdk 2.99.1 → 2.101.0

package/README.md

@@ -17,7 +17,7 @@ Users sign a message or transaction, and the Ultravioleta facilitator handles on
 - **Buyer Policy**: Per-payment and cumulative budgets, payee allowlist and offer expiry, evaluated against the offer in hand **before signing** — six closed refusal codes in a fixed order
 - **Type-Safe**: Full TypeScript support
 - **React & Wagmi**: First-class integrations
-- **Signing Wallet Adapters**: EnvKeyAdapter (server/CLI), OWSWalletAdapter (Open Wallet Standard), or bring your own
+- **Signing Wallet Adapters**: EnvKeyAdapter (server/CLI), OWSWalletAdapter (Open Wallet Standard vault, Node), 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 23 networks (21 EVM + 2 Solana)
 - **Escrow & Refunds**: Hold payments with dispute resolution
@@ -560,16 +560,22 @@ const result = await wallet.signTypedData(JSON.stringify({
 
 ### OWSWalletAdapter (Open Wallet Standard)
 
-Delegates signing to any wallet that implements the [Open Wallet Standard](https://github.com/open-wallet-standard/open-wallet-standard). Works with browser wallets, agent vaults, and hardware-backed signers.
+Signs with a wallet kept in an [Open Wallet Standard](https://github.com/open-wallet-standard/core) vault. OWS stores the keys encrypted on disk and signs inside the library, so the key never reaches your process. Node only: `@open-wallet-standard/core` is a native module with prebuilt binaries for Linux (glibc) and macOS, x64 and arm64.
 
 ```bash
-npm install @open-wallet-standard/core  # optional peer dependency
+npm install @open-wallet-standard/core  # optional peer dependency, 1.4.2 or later 1.x
 ```
 
 ```typescript
+import * as ows from '@open-wallet-standard/core';
 import { OWSWalletAdapter } from 'uvd-x402-sdk';
 
-const wallet = new OWSWalletAdapter(owsWalletInstance);
+const wallet = new OWSWalletAdapter(ows, {
+  wallet: 'agent-treasury',               // name or id of the wallet in the vault
+  passphrase: process.env.OWS_PASSPHRASE,  // or an OWS API key; this is also the default
+  network: 'base',                         // chain used when the payload names none
+  // vaultPath: '/path/to/vault',          // default: the OWS default (~/.ows)
+});
 
 const auth = await wallet.signEIP3009({
   to: '0xRecipient...',
@@ -578,6 +584,29 @@ const auth = await wallet.signEIP3009({
 });
 ```
 
+What it guarantees, tested against `@open-wallet-standard/core` 1.4.2 with an ephemeral key imported into a temporary vault:
+
+- For inputs `EnvKeyAdapter` signs, it signs the same bytes: messages, EIP-3009 on every EVM network of the registry, typed data with uint256 up to `2**256 - 1` given as numbers, decimal strings or hex (the lifecycle order's `salt` included), and EIP-1559, EIP-2930 and legacy transactions (EIP-155 or not).
+- Integers are checked against their EIP-712 type before anything is signed. OWS itself signs `2**256` as a uint256 as if it were `0`; the adapter throws `INVALID_AMOUNT` instead.
+- Every signature is recovered with ethers over the digest `EnvKeyAdapter` signs. One that does not recover to `getAddress()` is not returned.
+- `signTransaction` takes the hex ethers serializes, an `ethers.Transaction`, or a transaction object with `from`. A `from` that is not this wallet is refused before signing. A transaction without a `chainId` is signed pre-EIP-155, as `EnvKeyAdapter` signs it.
+- The passphrase is never in the adapter's `JSON.stringify` / `util.inspect` output nor in its errors.
+
+It refuses (`INVALID_CONFIG`, nothing signed) some inputs that ethers signs:
+
+- Typed data: an integer string with spaces; a bool that is not a boolean (`1`, `0`, `"true"`, `"false"`; ethers signs `"false"` as true); `uint` / `int` without a width; a `primaryType` that is not the root struct (ethers ignores `primaryType` and signs the root).
+- Transaction objects (`ethers.Wallet` signs these): a `type` given as `'0x2'`, `'2'` or a bigint; `to: ''`; `data: ''`; and any key ethers' `Transaction.from` does not read, other than `from` and `hash`. The error names the key, and for `input` / `gas` it names the ethers field (`data` / `gasLimit`).
+
+A `vaultPath` that does not exist is created by OWS, so a typo gives "wallet not found".
+
+**Migrating from the old form.** Up to 2.100.0 the adapter took a wallet object with `accounts` (the `OWSWallet` type). That shape never worked with `@open-wallet-standard/core` 1.x. It still compiles but is deprecated, and `new OWSWalletAdapter(wallet)` now throws `INVALID_CONFIG`. If you wrapped the library in such an object, drop the wrapper and pass the module and the wallet:
+
+```typescript
+// before: new OWSWalletAdapter(createOWSWalletBridge(walletName, passphrase))
+import * as ows from '@open-wallet-standard/core';
+const wallet = new OWSWalletAdapter(ows, { wallet: walletName, passphrase });
+```
+
 ### Custom Adapter
 
 Implement the `SigningWalletAdapter` interface for your own signer:
@@ -861,6 +890,16 @@ app.post('/api/premium', async (req, res) => {
 
 `createPaymentMiddleware()` and `createHonoMiddleware()` verify and settle automatically by default (`before-handler`). Use `settlementStrategy: 'manual'` if you need to control when settlement happens (e.g., settle only after confirming you can fulfill the request).
 
+### Stack key (services run by Ultravioleta DAO)
+
+Services run by Ultravioleta DAO carry a per-service credential, the stack key, so that the facilitator's rate-limit policy does not answer them `429`. Everything in this SDK that calls the facilitator sends it as `X-UVD-Stack-Key`: the clients `FacilitatorClient` (and the two middlewares), `Erc8004Client`, `BazaarClient`, `EscrowClient` and `AdvancedEscrowClient`, and the functions `anchorEvidence`, `availableBackends`, `streamTrafficEvents` and `getFacilitatorReceipt`, which take the same `stackKey` / `stackKeyHosts` options. It changes nothing else about a payment, and a facilitator that does not know the header ignores it.
+
+- **Where it comes from:** the facilitator's operator issues one per service: `uvdsk_` followed by 43-128 base64url characters. The process receives it as `UVD_STACK_KEY` (read by default) or as the `stackKey` option, from a secret store, never from code.
+- **Not for third parties:** if you integrate this SDK in your own product you have no key and need none. Leave both unset and no header is sent.
+- **Only to a house facilitator:** the key goes over `https://` to `facilitator.ultravioletadao.xyz` and nowhere else, checked on the URL of every request. A request to any other host, or over plain `http://`, carries no header, whether the key came from the option or from `UVD_STACK_KEY`, and warns once, naming the host and never the key. `stackKeyHosts: ['facilitator-staging.example']` ADDS hosts (hostnames only, matched exactly); `facilitator.ultravioletadao.xyz` stays in. Plain `http://` is accepted only for `127.0.0.1` or `localhost`, and only when listed there. `EscrowClient`'s default base URL, `escrow.ultravioletadao.xyz`, is not the facilitator and gets the key only if listed.
+- **The key does not follow redirects:** a redirect answered to a request that carries it fails with `StackKeyRedirectError` (exported), and the key is not sent again. Point the client at the facilitator's final URL.
+- **A bad key never breaks a payment:** one leading BOM (U+FEFF), then spaces, tabs, CR and LF at both ends, are removed, and nothing else. A value that still does not match is not sent: the client warns once, without the value, and pays like any other client. The key never appears in a result, an error, a log line or a printed client.
+
 ## React
 
 ```tsx
@@ -1528,10 +1567,11 @@ const state = await client.queryEscrowState(paymentInfo);
 ### With SigningWalletAdapter (OWS)
 
 ```typescript
+import * as ows from '@open-wallet-standard/core';
 import { AdvancedEscrowClient } from 'uvd-x402-sdk/backend';
 import { OWSWalletAdapter } from 'uvd-x402-sdk';
 
-const wallet = new OWSWalletAdapter(owsWalletInstance);
+const wallet = new OWSWalletAdapter(ows, { wallet: 'agent-treasury', network: 'base' });
 const client = new AdvancedEscrowClient(null, {
   wallet,
   rpcUrl: 'https://mainnet.base.org',
@@ -1625,7 +1665,7 @@ Register and discover paid x402 resources across the network.
 The Bazaar is served by the facilitator itself under `/discovery/*`. No API key, no separate host.
 
 ```typescript
-import { BazaarClient, isAlive } from 'uvd-x402-sdk/backend';
+import { BazaarClient, bazaarExtension, isAlive } from 'uvd-x402-sdk/backend';
 
 const bazaar = new BazaarClient();
 
@@ -1647,6 +1687,16 @@ console.log(`${page.items.length} of ${page.pagination.total}`);
 // Free-text search. The parameter is `q`; anything else is rejected with a 400.
 const hits = await bazaar.listResources({ q: 'logs' });
 
+// Routing filters. Each one is sent only when you pass it.
+const posts = await bazaar.listResources({
+  q: 'look up who owns a phone number, callable by an agent with a POST',
+  method: 'POST',            // GET | POST | PUT | PATCH, sent uppercased
+  maxPriceUsd: 0.05,         // price at most 5 cents
+  hasInputSchema: true,      // only resources that declare their input
+  kind: 'api',               // 'api' | 'content'
+  excludeHost: 'tenjin.blog' // host names, comma-separated; not a URL, no port
+});
+
 // Walk the whole filtered catalog, one page at a time
 for await (const r of bazaar.iterateResources({ health: 'alive' })) {
   if (isAlive(r)) console.log(r.url);
@@ -1665,6 +1715,9 @@ await bazaar.registerResource({
     maxTimeoutSeconds: 60,
   }],
   metadata: { category: 'ai', tags: ['image'] },
+  // How to call it (see bazaarExtension below). Without it the listing
+  // says hasInputSchema: false.
+  extensions: bazaarExtension({ method: 'POST', body: { prompt: 'a red fox' } }),
 });
 
 // Aggregate catalog metrics
@@ -1674,6 +1727,52 @@ console.log(stats.total, stats.visible, stats.byHealth.alive);
 
 Timestamps (`firstSeen`, `lastSeen`, `lastUpdated`, `health.lastChecked`) are Unix epoch **seconds**. Use `epochToDate()` to get a `Date`.
 
+**Search length.** `q` can be up to 400 characters (`DEFAULT_MAX_SEARCH_LEN`), long enough for a request in natural language. Characters are counted as the facilitator counts them (code points: an emoji is one, not two). A longer `q` is refused before the request. Change the cap with `new BazaarClient({ maxSearchLen })`; against an older facilitator whose substring search takes at most 128 (up to 2.46.1, and some 2.47.0 builds), pass `maxSearchLen: MAX_SEARCH_LEN` to fail before the request instead of getting its 400. `getResourceByUrl()` searches with the URL's first 128 characters, which every facilitator accepts.
+
+**Routing filters** (`maxPriceUsd`, `method`, `hasInputSchema`, `kind`, `excludeHost`) need facilitator 2.48.0 or later (some 2.47.0 builds have them and some do not). A facilitator without them (every one up to 2.46.1) answers each, as any query parameter it does not know, with a 400 that names it, so the client sends each of these only when you pass it: a call that sets none of them sends exactly what it sent before. A value you pass is sent or refused before the request, never dropped, by the rules the facilitator reads it with: `maxPriceUsd` is a number `>= 0`, sent in decimal (`1e-7` goes out as `0.0000001`) and refused if that takes more than 32 characters; `method` is `GET`, `POST`, `PUT` or `PATCH` in any case; `kind` is `api` or `content`; `excludeHost` is a host name, or up to 20 separated by commas, each matched with its subdomains, with no scheme, path or port. `null` counts as not passed.
+
+**Registering with `extensions`.** `registerResource({ ..., extensions })` sends the object as the body's `extensions`, which the facilitator keeps as it comes: from `extensions.bazaar.info.input` the listing gets `hasInputSchema: true`, and it is found by `method: 'POST'` when that is what it declares. Pass the same `bazaarExtension(...)` you put in your 402. It must be a plain object of at most 16 KiB as JSON and 64 levels deep (the facilitator drops a bigger one without an error, so the client refuses it before the request). Without `extensions` the request body is exactly what it was. `extensions` only counts on a URL's first registration: registering a URL that is already in the catalog is answered with a 409 (`registerResource` throws) and leaves its record as it was, and the facilitator serves no public route that updates one. A URL listed without `extensions` does not gain them by registering again, so pass them the first time.
+
+### Declaring your endpoint to the Bazaar (`bazaarExtension`)
+
+A seller can tell the facilitator how its endpoint is called inside the 402 itself, with the `bazaar` extension of x402 v2 ([spec](https://github.com/coinbase/x402/blob/main/specs/extensions/bazaar.md)). The facilitator catalogs the endpoint from it. The method travels in `info.input.method` and the example body in `info.input.body`: that is what a facilitator needs to probe a POST endpoint with a POST instead of a GET. Pass the same object as `extensions` to `BazaarClient.registerResource()` (above) when you register the endpoint yourself.
+
+```typescript
+import { bazaarExtension, create402Response } from 'uvd-x402-sdk';
+
+// POST (or PUT / PATCH) with a JSON body
+const { status, headers, body } = create402Response(
+  {
+    amount: '0.05',
+    recipient: '0xYourWallet...',
+    resource: 'https://api.example.com/phone-lookup',
+    chainName: 'base',
+    x402Version: 2,
+  },
+  {
+    extensions: bazaarExtension({
+      method: 'POST',
+      body: { phone: '+573001234567' },          // example body, required for POST/PUT/PATCH
+      bodySchema: {                              // optional JSON Schema of the body
+        type: 'object',
+        properties: { phone: { type: 'string' } },
+        required: ['phone'],
+      },
+      output: { example: { owner: 'ACME S.A.S.', carrier: 'Claro' } },
+    }),
+  }
+);
+
+// GET (or HEAD / DELETE) with query parameters
+bazaarExtension({
+  method: 'GET',
+  queryParams: { city: 'Bogota' },
+  output: { example: { city: 'Bogota', temperature: 18 } },
+});
+```
+
+The result is `{ bazaar: { info, schema } }`: `info.input` (`type: "http"`, `method`, then `bodyType` and `body` for a body method, or `queryParams` for a query method, plus optional `headers`), `info.output` (`type`, default `json`, and `example`), and `schema`, the JSON Schema (draft 2020-12) that `info` validates against. `bodyType` is `json` (default), `form-data` or `text` (then `body` is a string). A body method without `body`, a query method with one, or a method the spec does not name (`CONNECT`, `OPTIONS`, ...) throws. `extensions` is a v2 field: `create402Response` throws if the response would be v1 rather than dropping it, and without `extensions` it returns exactly what it returned before.
+
 ## x402 v2 requests (`buildVerifyRequestV2` / `buildSettleRequestV2`)
 
 If your 402 advertises CAIP-2 networks (`eip155:8453`), you are speaking v2 and

package/dist/adapters/index.d.mts

@@ -1,6 +1,7 @@
-import { X as X402Version, a as PaymentResult } from '../index-D8JpL_D5.mjs';
-export { E as EnvKeyAdapter, O as OWSWallet, a as OWSWalletAdapter } from '../ows-Z9v4GxOZ.mjs';
-import '../wallet-w7BnImDG.mjs';
+import { X as X402Version, a as PaymentResult } from '../index-DagQ74ZQ.mjs';
+export { E as EnvKeyAdapter, O as OWSAccountInfo, a as OWSCore, b as OWSSignResult, c as OWSWallet, d as OWSWalletAdapter, e as OWSWalletAdapterOptions } from '../ows-9uNT7ZSZ.mjs';
+import '../wallet-T0NFUUkT.mjs';
+import 'ethers';
 
 /**
  * uvd-x402-sdk - Wagmi/Viem Adapter

package/dist/adapters/index.d.ts

@@ -1,6 +1,7 @@
-import { X as X402Version, a as PaymentResult } from '../index-D8JpL_D5.js';
-export { E as EnvKeyAdapter, O as OWSWallet, a as OWSWalletAdapter } from '../ows-C-KmORG9.js';
-import '../wallet-w7BnImDG.js';
+import { X as X402Version, a as PaymentResult } from '../index-DagQ74ZQ.js';
+export { E as EnvKeyAdapter, O as OWSAccountInfo, a as OWSCore, b as OWSSignResult, c as OWSWallet, d as OWSWalletAdapter, e as OWSWalletAdapterOptions } from '../ows-Tt33WE0s.js';
+import '../wallet-T0NFUUkT.js';
+import 'ethers';
 
 /**
  * uvd-x402-sdk - Wagmi/Viem Adapter