uvd-x402-sdk 2.105.0 → 2.107.0

package/README.md

@@ -10,7 +10,7 @@ Users sign a message or transaction, and the Ultravioleta facilitator handles on
 
 ## Features
 
-- **29 Networks**: EVM (17 including Arc, Scroll, SKALE Base, Robinhood Chain), Solana, Fogo, Stellar, NEAR, Algorand, Sui, XRP Ledger, Hedera (mainnet + testnet)
+- **31 Networks**: EVM (19 including HashKey Chain, Arc, Scroll, SKALE Base, Robinhood Chain), Solana, Fogo, Stellar, NEAR, Algorand, Sui, XRP Ledger, Hedera (mainnet + testnet)
 - **Multi-Stablecoin**: USDC, EURC, AUSD, PYUSD, USDT, USDG (Robinhood Chain)
 - **x402 v1 & v2**: Protocol auto-detection; native Hedera supports v2/exact only
 - **Gasless**: Facilitator pays all network fees
@@ -24,6 +24,7 @@ Users sign a message or transaction, and the Ultravioleta facilitator handles on
 - **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
 - **Batch Settlement (buyer)**: `uvd-x402-sdk/batch-settlement` — one ERC-3009 deposit opens a channel, each later request pays with a cumulative voucher; capped deposits, vector-pinned parity with the Python SDK
+- **Reputation (rater-authored ERC-8004)**: `uvd-x402-sdk/reputation` — anchor payment, checked prepare, low-s signatures, a persistent outbox that never prepares twice, caps and a circuit breaker, evidence without chat text; vector-pinned parity with the Python SDK
 - **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
@@ -707,6 +708,23 @@ if (res.ok) await client.confirm(prepared, settleResponse.extra); // from the PA
 
 A deposit is never above `maxDeposit`: the seller's `extra.minDeposit` is a target, and a deposit the next voucher needs above the cap throws `BatchSettlementError` with nothing signed. Only `eip155:*` networks and the ERC-3009 deposit are signed (`assetTransferMethod: 'permit2'` throws). `confirm` records previous cumulative + `chargedAmount` and never copies the seller's `channelState`; a mismatch leaves the local state untouched and resolves to `false`. If the payer may be an EIP-7702 delegated account (a Paybox wallet), pass `delegationResolver` (e.g. `rpcDelegationResolver(rpcUrl)`): the deposit authorization is then wrapped for ERC-1271 when the delegate needs it, and an unreadable chain refuses instead of signing plain. Not included: Permit2 deposits, the cooperative refund and the corrective-402 resync.
 
+## Reputation (rater-authored ERC-8004)
+
+Ratings the chain records as authored by your program's own rater wallet, relayed by the facilitator, each anchored by a small USDC payment from the rater to the rated wallet. One module for every program, the same contract and shared vectors as the Python SDK's `uvd_x402_sdk.reputation`. Integration in fifteen lines, the money rules, the outbox states and `!forgetme`: [`src/reputation/README.md`](src/reputation/README.md).
+
+```typescript
+import { Erc8004Client } from 'uvd-x402-sdk/backend';
+import { Governor, SqliteRatingOutbox, describeNetHealth, messageRef, processRating } from 'uvd-x402-sdk/reputation';
+
+const outbox = new SqliteRatingOutbox(db); // a better-sqlite3 Database (optional peer dependency), synchronous = FULL
+const governor = new Governor(caps, describeNetHealth(), { store: outbox }); // caps: eight parameters, no defaults
+const ref = messageRef('my-app:v1', streamId, messageId);
+await outbox.enqueue({ ref, network: 'base', subject: wallet, streamId, value: 90, amount: 1000, viewerId });
+await processRating(ref, { outbox, governor, client: new Erc8004Client(), rpc, signer, resolveAgent, buildFeedback });
+```
+
+The module never reads a key (it signs through the `signer` you pass), never pays a wallet whose agent it has not resolved and checked, refuses to sign any prepare that is not the exact rating asked for, stores the signed payment before broadcasting it and the signed rating before sending it, and once a rating is signed it only reads the chain until the deadline, and the delegate's own spent-nonce cell in the rater's storage, prove it did not land.
+
 ## Multi-Stablecoin (EVM)
 
 ```typescript
@@ -795,6 +813,8 @@ const header = svm.encodePaymentHeader(payload, chainConfig);
 | Scroll | 534352 | USDC |
 | SKALE Base | 1187947933 | USDC.e |
 | SKALE Base Sepolia | 324705682 | USDC.e |
+| HashKey Chain | 177 | USDC |
+| HashKey Chain Testnet | 133 | USDC |
 | Robinhood Chain | 4663 | USDG |
 | Robinhood Chain Testnet | 46630 | USDG |
 | Arc | 5042 | USDC, EURC |
@@ -802,6 +822,8 @@ const header = svm.encodePaymentHeader(payload, chainConfig);
 
 > **Arc mainnet and testnet:** payment amounts use 6 decimals. USDC signs with the `USDC` / `2` domain; EURC (`0xbEf5…21c1` mainnet, `0x89B5…D72a` testnet) signs with `EURC` / `2` and its amounts are **euros**, not dollars (`tokenType: 'eurc'`, `usdPegged: false`). Native gas uses 18 decimals on the same balance. Use `arc` / `eip155:5042` for mainnet and `arc-testnet` / `eip155:5042002` for testnet. See [Arc usage and validation](docs/networks/arc.md).
 
+> **HashKey Chain / USDC:** Use `hashkey` (177) or `hashkey-testnet` (133). Gas is HSK; payments use 6-decimal USDC. Mainnet's EIP-712 name is `Bridged USDC` and testnet's is `USD Coin`, both version `2`. HashKey USDT is unsupported because it has no EIP-3009. [Network configuration and measured domains](docs/networks/hashkey.md).
+
 > **Robinhood Chain / USDG:** Robinhood Chain has no USDC — the settlement stablecoin is Paxos **USDG** (Global Dollar, 6 decimals, EIP-3009). Its on-chain `version()` getter reverts, so the EIP-712 domain `{ name: "Global Dollar", version: "1" }` can never be resolved on-chain. The SDK carries this domain in the chain config; when constructing `PaymentRequirements` yourself, send it in `extra`: `{ "name": "Global Dollar", "version": "1" }`. Use `tokenType: 'usdg'` (or the default, which resolves to USDG on these networks).
 
 ### SVM (2)
@@ -864,6 +886,8 @@ getFacilitatorAddress('xrpl-mainnet'); // rfADKk...
 
 ## Backend
 
+Payment headers follow one rule in Express, Hono and `createFetchPaywall`: send `X-PAYMENT`, `PAYMENT-SIGNATURE`, or both with the same value. Names are case-insensitive and surrounding HTTP spaces/tabs are ignored. Distinct values return **400** (`Conflicting payment headers`) before verification or settlement. Empty or malformed payment headers, including payments with no network in either `network` or `accepted.network`, return **400**; absent payment headers return **402**. The extractor returns `null` for invalid or conflicting headers. Standard v2 payments carry their network in `accepted.network`; a top-level string `network` takes precedence when present. Empty or whitespace-padded networks are invalid. Verification and settlement use the same parsed payment, including manual settlement.
+
 ```typescript
 import {
   FacilitatorClient,

package/dist/adapters/index.js

@@ -36,7 +36,7 @@ var SUPPORTED_CHAINS = {
     x402: { facilitatorUrl: DEFAULT_FACILITATOR_URL, enabled: true }
   },
   // ============================================================================
-  // EVM CHAINS (16 enabled + BSC, disabled)
+  // EVM CHAINS (19 enabled + BSC, disabled)
   // ============================================================================
   base: {
     chainId: 8453,
@@ -441,8 +441,8 @@ var SUPPORTED_CHAINS = {
       usdt: {
         address: "0xe7cd86e13AC4309349F30B3435a9d337750fC82D",
         decimals: 6,
-        name: "USD\u20AE0",
-        // USD₮0 (USDT0 omnichain via LayerZero)
+        name: "USDT0",
+        // ASCII on Monad, unlike USD₮0 on Arbitrum/Optimism (src/usdt-domains.test.ts)
         version: "1"
       }
     },
@@ -594,6 +594,57 @@ var SUPPORTED_CHAINS = {
       enabled: true
     }
   },
+  // HashKey Chain: USDC supports EIP-3009; HashKey USDT does not.
+  hashkey: {
+    chainId: 177,
+    chainIdHex: "0xb1",
+    name: "hashkey",
+    displayName: "HashKey Chain",
+    networkType: "evm",
+    rpcUrl: "https://mainnet.hsk.xyz",
+    explorerUrl: "https://hsk.blockscout.com",
+    nativeCurrency: { name: "HashKey", symbol: "HSK", decimals: 18 },
+    usdc: {
+      address: "0x054ed45810DbBAb8B27668922D110669c9D88D0a",
+      decimals: 6,
+      name: "Bridged USDC",
+      version: "2"
+    },
+    tokens: {
+      usdc: {
+        address: "0x054ed45810DbBAb8B27668922D110669c9D88D0a",
+        decimals: 6,
+        name: "Bridged USDC",
+        version: "2"
+      }
+    },
+    x402: { facilitatorUrl: DEFAULT_FACILITATOR_URL, enabled: true }
+  },
+  "hashkey-testnet": {
+    chainId: 133,
+    chainIdHex: "0x85",
+    name: "hashkey-testnet",
+    displayName: "HashKey Chain Testnet",
+    networkType: "evm",
+    rpcUrl: "https://testnet.hsk.xyz",
+    explorerUrl: "https://testnet-explorer.hskchain.net",
+    nativeCurrency: { name: "HashKey", symbol: "HSK", decimals: 18 },
+    usdc: {
+      address: "0x8FE3cB719Ee4410E236Cd6b72ab1fCDC06eF53c6",
+      decimals: 6,
+      name: "USD Coin",
+      version: "2"
+    },
+    tokens: {
+      usdc: {
+        address: "0x8FE3cB719Ee4410E236Cd6b72ab1fCDC06eF53c6",
+        decimals: 6,
+        name: "USD Coin",
+        version: "2"
+      }
+    },
+    x402: { facilitatorUrl: DEFAULT_FACILITATOR_URL, enabled: true }
+  },
   // Robinhood Chain (Arbitrum Orbit L2). NOTE: there is NO USDC on this chain -
   // the settlement stablecoin is Paxos USDG (Global Dollar). The `usdc` field
   // below carries USDG for interface compatibility (same pattern as XRPL's native
@@ -1156,6 +1207,8 @@ var CAIP2_IDENTIFIERS = {
   scroll: "eip155:534352",
   "skale-base": "eip155:1187947933",
   "skale-base-sepolia": "eip155:324705682",
+  hashkey: "eip155:177",
+  "hashkey-testnet": "eip155:133",
   robinhood: "eip155:4663",
   "robinhood-testnet": "eip155:46630",
   arc: "eip155:5042",