agent402-tollbooth 0.9.1 → 0.9.3

package/README.md

@@ -10,17 +10,12 @@ The first self-hostable pay-per-crawl gate that speaks both wires on one 402 -
 the sell side of [Agentic Finance](https://agent402.tools/agentic-finance),
 where agents pay and sites get paid, per request, with no account in between.
 
-The big platforms are converging on the same model: Cloudflare's
-[pay-per-crawl](https://stackoverflow.blog/2026/02/26/how-pay-per-crawl-is-reshaping-data-monetization/)
-and now its [Monetization Gateway](https://blog.cloudflare.com/monetization-gateway/)
-(launched July 2026 - x402 charging in USDC on Base for anything behind Cloudflare:
-pages, APIs, datasets, MCP tools) confirm that pay-per-request is the business model
-of the agentic web. Tollbooth is the **open-source monetization gateway**: the same
-idea, but MIT-licensed and live today, running in
-front of *any* origin (even a Cloudflare Worker), non-custodial (you hold the wallet,
-no signup or Merchant-of-Record), and - the wedge the platform gateways don't offer -
-with a **proof-of-work free tier** so a walletless agent still has a path through.
-Built on the same hardened 402 + proof-of-work machinery as
+Tollbooth is an **open-source monetization gateway**: MIT-licensed, running in
+front of *any* origin (Express, a reverse proxy, Next.js, a Cloudflare Worker),
+non-custodial (you hold the wallet, no signup or Merchant-of-Record), settling
+over x402 and MPP on one 402 - including native MPP on Tempo with split
+payments - and with a **proof-of-work free tier** so a walletless agent still
+has a path through. Built on the same hardened 402 + proof-of-work machinery as
 [Agent402](https://github.com/MikeyPetrillo/Agent402).
 
 ## See it work (one command)
@@ -123,8 +118,7 @@ must pay, or `null` to let it through.
 **Ready-to-deploy templates** (copy a folder, don't assemble from docs):
 
 - **Cloudflare Workers** → [`deploy/cloudflare/`](deploy/cloudflare/) - a ready
-  `wrangler.toml` + a 3-step deploy guide (the open pay-per-crawl, on the
-  incumbent's own platform).
+  `wrangler.toml` + a 3-step deploy guide.
 - **Next.js / Vercel** → [`deploy/nextjs/`](deploy/nextjs/) - a drop-in
   `middleware.js` + a 3-step deploy guide.
 - **Docker** → [`deploy/docker/`](deploy/docker/) - a `Dockerfile` +
@@ -162,8 +156,8 @@ export const config = { matcher: ["/((?!_next/static|_next/image|favicon.ico).*)
 > On the edge, pass a stable `secret` (PoW tokens are HMAC-signed). For
 > single-use replay protection across stateless invocations, supply a `store`
 > (e.g. a Cloudflare KV wrapper - the Worker entry wires this for you).
-> The `x402:` middleware mode and MPP are Node/Express features today; the
-> edge gate offers proof-of-work plus the `verifyX402` callback.
+> The `x402:` middleware mode, MPP and the native Tempo rail are Node/Express
+> features today; the edge gate offers proof-of-work plus the `verifyX402` callback.
 
 ## Accepting USDC: x402 and MPP on the same 402
 
@@ -240,9 +234,21 @@ app.use(createTollbooth({
 }));
 ```
 
+The `tempo` object takes `apiKey` (required), `recipient` (required, your
+Tempo payTo), `currency` or `currencies` (TIP-20 token addresses; default USDC.e
+`0x20C000000000000000000000b9537d11c60E8b50`, one challenge minted per currency,
+first = preferred), `splits` (up to 10, total below the price, same transaction),
+`chainId` (default 4217, Tempo mainnet), `apiBaseUrl` (relay, default
+`https://api.tempo.xyz`), `decimals` (6), `timeoutSeconds` (300), plus the
+confirm knobs below. A bad config throws at construction - the gate never boots
+minting unpayable challenges.
+
 Or from env on the CLI: `TOLLBOOTH_TEMPO_API_KEY`, `TOLLBOOTH_TEMPO_RECIPIENT`
-(defaults to `TOLLBOOTH_PAYTO`), optional `TOLLBOOTH_TEMPO_CURRENCY`,
-`TOLLBOOTH_TEMPO_SPLITS="0xabc:0.0002,0xdef:0.0001"`.
+(defaults to `TOLLBOOTH_PAYTO`), optional `TOLLBOOTH_TEMPO_CURRENCY` (CSV of
+token addresses), `TOLLBOOTH_TEMPO_SPLITS="0xabc:0.0002,0xdef:0.0001"`,
+`TOLLBOOTH_TEMPO_API_BASE` (relay override), `TOLLBOOTH_TEMPO_RPC_URL` (confirm
+RPC override). Tempo works with NO x402 middleware at all (a Tempo-only
+tollbooth) and next to one.
 
 Every 402 then carries a `WWW-Authenticate: Payment` tempo/charge challenge
 (next to any evm challenges from the x402 rail, if you run both); a stock
@@ -256,6 +262,23 @@ body. Challenges are HMAC-bound to your `TOLLBOOTH_SECRET`; each credential is
 single-use (share a `replayStore` across workers). No new dependency: the
 relay is spoken to over plain `fetch`.
 
+**Chain-truth confirm (0.9.2):** a relay can report settlement failure for a
+payment that actually landed - measured live: a buyer whose packed signature
+ends with a yParity-style v byte (0x00/0x01) gets normalized by the Tempo
+node, so the canonical txid stops matching the hash of the submitted bytes
+and the relay's post-broadcast check refuses a settled payment; the buyer is
+told 402 and retries into a double charge. On any broadcast failure the gate
+now derives the only txids the credential's own signed bytes could have
+landed under (submitted form + v-swapped twin - the txid commits to the
+bytes, so the binding is exact) and, if one of them succeeded on-chain paying
+your recipient at least the challenge amount in the challenge currency,
+serves the response as paid. Verification only - nothing is re-broadcast, so
+it can never double-charge; every uncertainty fails closed to the 402.
+Options: `confirm: false` disables, `confirmRpcUrl` overrides the Tempo RPC
+(default `https://rpc.tempo.xyz`, env `TOLLBOOTH_TEMPO_RPC_URL`). Still
+dependency-free (keccak-256 is implemented in-package and pinned against the
+live incident transaction in the tests).
+
 ## Configuration
 
 | Option | Default | What |
@@ -276,6 +299,9 @@ relay is spoken to over plain `fetch`.
 | `mpp` | `true` when `x402` set | Accept MPP (`WWW-Authenticate: Payment` / `Authorization: Payment`) through the `x402` middleware |
 | `mppSecret` | `powSecret` / `TOLLBOOTH_SECRET` | HMAC secret binding MPP challenge ids (stable across workers) |
 | `mppNetworks` | `[8453, 42220]` | EVM chain ids to offer as MPP challenges (`"all"` = every EVM chain the middleware advertises) |
+| `tempo` | env (`TOLLBOOTH_TEMPO_*`) or off | Native MPP on Tempo (0.9.0): `{ apiKey, recipient, currency \| currencies, splits, chainId, apiBaseUrl, decimals, timeoutSeconds, confirm, confirmRpcUrl }` - mints `tempo/charge` challenges, validates with Tempo's relay before the handler, broadcasts after a <400 response. Works with or without `x402` |
+| `tempo.confirm` | `true` | Chain-truth confirm (0.9.2): on a relay broadcast failure, check the chain for the credential's own txid before answering 402; `false` disables |
+| `tempo.confirmRpcUrl` | `https://rpc.tempo.xyz` (`TOLLBOOTH_TEMPO_RPC_URL`) | Tempo JSON-RPC used by the confirm step |
 | `verifyX402(req, opts)` | – | Legacy verify-only USDC check (deprecated for settle-after-handler middlewares; see above) |
 | `resourceBaseUrl` | `""` | Absolute base used for the `resource` field / PoW binding |
 | `observe` | `false` | Observe-only: classify and count, but never 402. For pre-launch traffic measurement. |
@@ -292,11 +318,18 @@ Read by the bundled proxy / Express entry point (`index.js`):
 | `TOLLBOOTH_PAYTO` | – | Wallet address; advertises a USDC x402 quote (and, with `TOLLBOOTH_FACILITATOR_URL`, settles it) |
 | `TOLLBOOTH_FACILITATOR_URL` | – | x402 facilitator that settles your network. With `TOLLBOOTH_PAYTO` the CLI builds a real `@x402/express` middleware and takes payment over x402 **and** MPP (0.8.0). Needs `@x402/express @x402/core @x402/evm` installed; refuses to start without them |
 | `TOLLBOOTH_FACILITATOR_HEADERS` | – | Optional JSON object of auth headers sent on the facilitator's `/verify`, `/settle`, `/supported` (e.g. `{"X-API-Key":"…"}`) |
+| `TOLLBOOTH_CDP_API_KEY_ID` + `TOLLBOOTH_CDP_API_KEY_SECRET` | – | Settle through Coinbase's facilitator (CDP) instead of a URL: fee-free on Base, and the endpoint is indexed in Coinbase's x402 Bazaar. Needs `npm i @coinbase/x402`. This is how a Coinbase Business account gets paid by agents: `TOLLBOOTH_PAYTO` = the account's USDC (Base) receive address. |
 | `TOLLBOOTH_PRICE` | `"$0.001"` | Advertised price per request |
 | `TOLLBOOTH_NETWORK` | `"base"` | x402 network. CLI settlement mode accepts `base`, `base-sepolia`, `polygon`, `arbitrum`, `optimism`, `avalanche`, `celo`, `sei`, `monad`, or a raw `eip155:<id>` |
 | `TOLLBOOTH_MPP` | on when `x402` set | `false` to switch MPP off |
 | `TOLLBOOTH_MPP_SECRET` | `TOLLBOOTH_SECRET` | HMAC secret for MPP challenge ids |
 | `TOLLBOOTH_MPP_NETWORKS` | `8453,42220` | CSV of EVM chain ids to offer as MPP challenges, or `all` |
+| `TOLLBOOTH_TEMPO_API_KEY` | – | Tempo API key (`mpp:write` scope). Presence switches on the native Tempo rail (0.9.0) |
+| `TOLLBOOTH_TEMPO_RECIPIENT` | `TOLLBOOTH_PAYTO` | Tempo payTo (0x address) |
+| `TOLLBOOTH_TEMPO_CURRENCY` | USDC.e on Tempo | CSV of TIP-20 token addresses to offer (one challenge each, first = preferred) |
+| `TOLLBOOTH_TEMPO_SPLITS` | – | `0xabc:0.0002,0xdef:0.0001` - split recipients + USD amounts paid in the same transaction (≤10, total below the price) |
+| `TOLLBOOTH_TEMPO_API_BASE` | `https://api.tempo.xyz` | Tempo relay base URL override |
+| `TOLLBOOTH_TEMPO_RPC_URL` | `https://rpc.tempo.xyz` | Tempo JSON-RPC for the chain-truth confirm step (0.9.2) |
 | `TOLLBOOTH_ASSET` | `"USDC"` | Asset symbol in the quote (`USDG` charges in USDG on Robinhood Chain) |
 | `TOLLBOOTH_POW_BITS` | `18` | Proof-of-work difficulty in leading zero bits |
 | `TOLLBOOTH_MODE` | `"bots"` | Who pays: `bots` · `all` · `strict` |
@@ -364,7 +397,7 @@ changes. Bots see a `X-Tollbooth-Observed: would-charge` header in observe mode
 ## Analytics
 
 The middleware keeps aggregate counters (no per-request data):
-- `gate.stats()` → sync, in-process mirror: `{ requests, freeAllowed, wouldCharge, charged, powSolved, x402Paid, mppPaid, difficultyNow, observe }`.
+- `gate.stats()` → sync, in-process mirror: `{ requests, freeAllowed, wouldCharge, charged, powSolved, x402Paid, mppPaid, tempoPaid, difficultyNow, observe }`.
 - `gate.snapshot()` → async, reads from the configured durable sink (defaults to memory).
 - `gate.flush()` → flush any buffered deltas to the durable sink (call inside `ctx.waitUntil` on edge runtimes).
 
@@ -568,3 +601,23 @@ Celo by default - what a stock mppx client can sign); add `4663` there or pass
 ## Legal
 
 Use of the hosted instance at agent402.tools is subject to its [Terms of Service](https://agent402.tools/terms) (acceptable-use policy included) and [Privacy Policy](https://agent402.tools/privacy). This package is MIT-licensed; the hosted server is AGPL-3.0. Both are provided as-is without warranty, and self-hosted deployments are their operator's responsibility.
+
+## Get paid into a Coinbase Business account
+
+Coinbase Business accounts receive x402 payments from AI agents directly. The
+tollbooth is the "integrate x402 into your API" step: point `TOLLBOOTH_PAYTO`
+at the account's USDC receive address on Base and settle through Coinbase's
+facilitator with a CDP API key.
+
+```bash
+npm i agent402-tollbooth @x402/express @x402/core @x402/evm @coinbase/x402
+TOLLBOOTH_PAYTO=0xYourCoinbaseBusinessBaseAddress \
+TOLLBOOTH_CDP_API_KEY_ID=... TOLLBOOTH_CDP_API_KEY_SECRET=... \
+TOLLBOOTH_PRICE='$0.005' TOLLBOOTH_UPSTREAM=http://localhost:8080 \
+npx agent402-tollbooth
+```
+
+Every paid request settles as USDC into the Coinbase Business account; humans
+browse your site normally. Full walkthrough with an Express example:
+https://agent402.tools/guides/coinbase-business-get-paid-by-agents
+

package/index.js

@@ -19,7 +19,7 @@ import { createPow } from "./pow.js";
 import { makeBotMatcher, AI_BOTS } from "./bots.js";
 import { memorySink } from "./sinks.js";
 import { challengesFromPaymentRequired, translateCredential, receiptFromPaymentResponse, isMppCredential, DEFAULT_MPP_CHAIN_IDS } from "./mpp.js";
-import { tempoConfig, mintTempoChallenges, parseTempoCredential, checkTempoBinding, tempoRelay, relayInput, broadcastIdempotencyKey, tempoReceiptHeader, tempoProblem } from "./tempo.js";
+import { tempoConfig, mintTempoChallenges, parseTempoCredential, checkTempoBinding, tempoRelay, relayInput, broadcastIdempotencyKey, tempoReceiptHeader, tempoProblem, confirmTempoSettlement } from "./tempo.js";
 
 export { AI_BOTS, makeBotMatcher } from "./bots.js";
 export { createPow, leadingZeroBits } from "./pow.js";
@@ -387,7 +387,22 @@ export function createTollbooth(config = {}) {
       try { next(); } catch (err) { restore(); return next(err); }
       await endPromise;
       if (res.statusCode >= 400) { restore(); replay(); return; } // handler failed: never broadcast, nobody charged
-      const b = await tempoRelayClient.broadcast(input, { idempotencyKey: broadcastIdempotencyKey(input) }).catch((e) => ({ ok: false, error: String(e?.message || e) }));
+      let b = await tempoRelayClient.broadcast(input, { idempotencyKey: broadcastIdempotencyKey(input) }).catch((e) => ({ ok: false, error: String(e?.message || e) }));
+      if (!b.ok && tempoCfg.confirm) {
+        // The relay's verdict and the chain's truth can diverge (measured
+        // live 2026-08-20: a yParity-style v byte the node normalizes makes
+        // the relay's post-broadcast hash check fail a payment that SETTLED;
+        // the buyer retried into a double charge). Ask the chain whether this
+        // credential's own transaction landed before discarding the response —
+        // exact txid derivation from the signed bytes, verification never a
+        // re-broadcast, fails closed to the 402. See tempo.js.
+        const check = tempoCfg.confirmSettlement || ((c) => confirmTempoSettlement(c, { rpcUrl: tempoCfg.confirmRpcUrl, fetchImpl: tempoCfg.fetch }));
+        const confirmed = await Promise.resolve(check(cred)).catch(() => null);
+        if (confirmed?.txId) {
+          console.warn(`[agent402-tollbooth] tempo relay reported settlement failure but the credential's transaction SETTLED on-chain (${req.method} ${req.url} tx=${confirmed.txId}) - honouring the settlement (verified from the chain, nothing re-broadcast). Relay said: ${b.detail || b.error}`);
+          b = { ok: true, receipt: { method: "tempo", reference: confirmed.txId } };
+        }
+      }
       if (!b.ok) {
         // Broadcast failed AFTER a successful handler: discard the body, 402
         // (mirrors @x402/express's settle-failure path). Loud - this is the
@@ -671,9 +686,16 @@ export const CLI_NETWORKS = {
 export async function buildCliX402Middleware(env = process.env) {
   const payTo = env.TOLLBOOTH_PAYTO || "";
   const facilitatorUrl = env.TOLLBOOTH_FACILITATOR_URL || "";
+  // Coinbase's facilitator (CDP) authenticates every verify/settle call with
+  // a short-lived JWT signed by a CDP API key, so a static header cannot
+  // reach it; @coinbase/x402's createFacilitatorConfig mints them. With the
+  // two keys set the CLI settles through CDP (fee-free on Base, and the
+  // endpoint is indexed in Coinbase's x402 Bazaar), no URL needed. This is
+  // the path a Coinbase Business account uses to get paid by agents.
+  const cdpKeys = env.TOLLBOOTH_CDP_API_KEY_ID && env.TOLLBOOTH_CDP_API_KEY_SECRET;
   if (!payTo) return null;
-  if (!facilitatorUrl) {
-    console.warn("⚠ TOLLBOOTH_PAYTO is set without TOLLBOOTH_FACILITATOR_URL: the 402 advertises a USDC quote but nothing here can verify or settle a payment, so every paid request is refused. Set TOLLBOOTH_FACILITATOR_URL (a public x402 facilitator that settles your network - keyless free tiers exist; https://x402.org/facilitator for base-sepolia) to actually charge, over x402 and MPP.");
+  if (!facilitatorUrl && !cdpKeys) {
+    console.warn("⚠ TOLLBOOTH_PAYTO is set without TOLLBOOTH_FACILITATOR_URL (or TOLLBOOTH_CDP_API_KEY_ID/SECRET): the 402 advertises a USDC quote but nothing here can verify or settle a payment, so every paid request is refused. Set TOLLBOOTH_FACILITATOR_URL (a public x402 facilitator that settles your network - keyless free tiers exist; https://x402.org/facilitator for base-sepolia) to actually charge, over x402 and MPP.");
     return null;
   }
   const asset = (env.TOLLBOOTH_ASSET || "USDC").toUpperCase();
@@ -702,7 +724,17 @@ export async function buildCliX402Middleware(env = process.env) {
   if (env.TOLLBOOTH_FACILITATOR_HEADERS) {
     try { authHeaders = JSON.parse(env.TOLLBOOTH_FACILITATOR_HEADERS); } catch { console.error("✖ TOLLBOOTH_FACILITATOR_HEADERS must be a JSON object of header name -> value. Refusing to start."); process.exit(1); }
   }
-  const client = new HTTPFacilitatorClient({
+  let cdpConfig = null;
+  if (cdpKeys) {
+    try {
+      const { createFacilitatorConfig } = await import("@coinbase/x402");
+      cdpConfig = createFacilitatorConfig(env.TOLLBOOTH_CDP_API_KEY_ID, env.TOLLBOOTH_CDP_API_KEY_SECRET);
+    } catch (e) {
+      console.error(`✖ TOLLBOOTH_CDP_API_KEY_ID/SECRET are set, so this gate must settle through Coinbase's facilitator, but @coinbase/x402 is not installed (${String(e?.message || e).slice(0, 120)}). Install it: npm install @coinbase/x402`);
+      process.exit(1);
+    }
+  }
+  const client = new HTTPFacilitatorClient(cdpConfig || {
     url: facilitatorUrl,
     ...(authHeaders ? { createAuthHeaders: async () => ({ verify: authHeaders, settle: authHeaders, supported: authHeaders }) } : {}),
   });
@@ -842,7 +874,7 @@ async function startCli() {
     app.use((_req, res) => res.json({ ok: true, note: "Bare tollbooth gate (no TOLLBOOTH_UPSTREAM set). Clients that reach here paid or solved a proof-of-work." }));
   }
   app.listen(port, () => {
-    const paidLabel = x402mw ? `x402 + MPP (${process.env.TOLLBOOTH_ASSET || "USDC"}, settling via ${process.env.TOLLBOOTH_FACILITATOR_URL})` : (process.env.TOLLBOOTH_PAYTO ? `x402 quote only (${process.env.TOLLBOOTH_ASSET || "USDC"}, NOT settling - set TOLLBOOTH_FACILITATOR_URL)` : "");
+    const paidLabel = x402mw ? `x402 + MPP (${process.env.TOLLBOOTH_ASSET || "USDC"}, settling via ${process.env.TOLLBOOTH_CDP_API_KEY_ID && process.env.TOLLBOOTH_CDP_API_KEY_SECRET ? "Coinbase CDP" : process.env.TOLLBOOTH_FACILITATOR_URL})` : (process.env.TOLLBOOTH_PAYTO ? `x402 quote only (${process.env.TOLLBOOTH_ASSET || "USDC"}, NOT settling - set TOLLBOOTH_FACILITATOR_URL)` : "");
     const rails = [gate.pow ? "proof-of-work" : "", paidLabel].filter(Boolean).join(" + ");
     console.log(`agent402-tollbooth listening on :${port} — charging AI bots via ${rails || "proof-of-work"}`);
     if (upstream) console.log(`  proxying → ${upstream}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent402-tollbooth",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "description": "Agent402 tollbooth: open-source, self-hostable pay-per-crawl for x402 AND MPP (the sell side of Agentic Finance): charge AI bots per request (USDC via x402, or MPP - the Machine Payments Protocol - through the same settlement, or USDG on Robinhood Chain, or free proof-of-work) while humans browse free. Drop-in Express middleware or reverse proxy that settles both wires from env alone - no Cloudflare, no Stripe, no signup.",
   "type": "module",
   "main": "index.js",
@@ -47,11 +47,15 @@
     "express": "^5.0.0"
   },
   "peerDependencies": {
+    "@coinbase/x402": ">=2.0.0",
     "@x402/core": ">=2.0.0",
     "@x402/evm": ">=2.0.0",
     "@x402/express": ">=2.0.0"
   },
   "peerDependenciesMeta": {
+    "@coinbase/x402": {
+      "optional": true
+    },
     "@x402/core": {
       "optional": true
     },

package/tempo.js

@@ -93,6 +93,12 @@ export function tempoConfig(cfg = {}) {
     fetch: cfg.fetch || globalThis.fetch,
     relay: cfg.relay || null, // { validate(input) -> {ok, error?}, broadcast(input, {idempotencyKey}) -> {ok, receipt?, error?} } (tests)
     relayTimeoutMs: Number.isFinite(cfg.relayTimeoutMs) ? cfg.relayTimeoutMs : 20_000,
+    // Chain-truth confirm on broadcast failure (see confirmTempoSettlement):
+    // `confirm: false` disables; `confirmRpcUrl` overrides the Tempo RPC;
+    // `confirmSettlement` injects the whole check (tests).
+    confirm: cfg.confirm !== false,
+    confirmRpcUrl: String(cfg.confirmRpcUrl || process.env.TOLLBOOTH_TEMPO_RPC_URL || "https://rpc.tempo.xyz").replace(/\/$/, ""),
+    confirmSettlement: typeof cfg.confirmSettlement === "function" ? cfg.confirmSettlement : null,
   };
 }
 
@@ -240,3 +246,127 @@ export function tempoProblem(kind, detail) {
   const titles = { "invalid-challenge": "Invalid Challenge", "verification-failed": "Verification Failed", "malformed-credential": "Malformed Credential", "payment-insufficient": "Payment Insufficient" };
   return { type: `https://paymentauth.org/problems/${kind}`, title: titles[kind] || kind, status: 402, detail };
 }
+
+// ---------------------------------------------------------------------------
+// Chain-truth confirm on broadcast failure (2026-08-20) — the relay's verdict
+// and the chain's truth can diverge: a buyer whose packed signature ends with
+// a yParity-style v byte (0x00/0x01) gets normalized to 27/28 by the Tempo
+// node, so the canonical txid stops matching keccak(submitted bytes) and the
+// relay's post-broadcast hash check reports `invalid_payment` for a payment
+// that SETTLED (measured live: two double charges in one buy attempt).
+// Before answering 402, ask the chain whether this credential's OWN
+// transaction landed. The txid commits to the signed bytes, so the candidates
+// are exact — the submitted form and its v-swapped twin — never a time-window
+// or payer heuristic. Fails closed on every uncertainty. Dependency-free like
+// the rest of this file: keccak-256 is implemented below (BigInt lanes — it
+// runs at most once per FAILED broadcast, so speed is irrelevant) and pinned
+// against standard vectors plus the live incident transaction in the tests.
+// ---------------------------------------------------------------------------
+
+const KECCAK_RC = [
+  "0x0000000000000001", "0x0000000000008082", "0x800000000000808a", "0x8000000080008000",
+  "0x000000000000808b", "0x0000000080000001", "0x8000000080008081", "0x8000000000008009",
+  "0x000000000000008a", "0x0000000000000088", "0x0000000080008009", "0x000000008000000a",
+  "0x000000008000808b", "0x800000000000008b", "0x8000000000008089", "0x8000000000008003",
+  "0x8000000000008002", "0x8000000000000080", "0x000000000000800a", "0x800000008000000a",
+  "0x8000000080008081", "0x8000000000008080", "0x0000000080000001", "0x8000000080008008",
+].map(BigInt);
+const KECCAK_RHO = [0, 1, 62, 28, 27, 36, 44, 6, 55, 20, 3, 10, 43, 25, 39, 41, 45, 15, 21, 8, 18, 2, 61, 56, 14];
+const U64 = (1n << 64n) - 1n;
+
+function keccakF(A) {
+  const rotl = (v, n) => n === 0n ? v : (((v << n) & U64) | (v >> (64n - n)));
+  for (let round = 0; round < 24; round++) {
+    const C = [0, 1, 2, 3, 4].map((x) => A[x] ^ A[x + 5] ^ A[x + 10] ^ A[x + 15] ^ A[x + 20]);
+    for (let x = 0; x < 5; x++) {
+      const D = C[(x + 4) % 5] ^ rotl(C[(x + 1) % 5], 1n);
+      for (let y = 0; y < 5; y++) A[x + 5 * y] ^= D;
+    }
+    const B = new Array(25);
+    for (let x = 0; x < 5; x++) for (let y = 0; y < 5; y++) B[y + 5 * ((2 * x + 3 * y) % 5)] = rotl(A[x + 5 * y], BigInt(KECCAK_RHO[x + 5 * y]));
+    for (let x = 0; x < 5; x++) for (let y = 0; y < 5; y++) A[x + 5 * y] = B[x + 5 * y] ^ ((~B[((x + 1) % 5) + 5 * y] & U64) & B[((x + 2) % 5) + 5 * y]);
+    A[0] ^= KECCAK_RC[round];
+  }
+}
+
+/** keccak-256 of a Buffer, as a 0x hex string. Original Keccak padding
+ *  (0x01 … 0x80), NOT SHA-3's 0x06 — Ethereum txids use the former. */
+export function keccak256Hex(buf) {
+  const rate = 136;
+  const padded = Buffer.alloc(Math.ceil((buf.length + 1) / rate) * rate);
+  buf.copy(padded);
+  padded[buf.length] = 0x01;
+  padded[padded.length - 1] |= 0x80;
+  const A = new Array(25).fill(0n);
+  for (let off = 0; off < padded.length; off += rate) {
+    for (let i = 0; i < rate / 8; i++) A[i] ^= padded.readBigUInt64LE(off + i * 8);
+    keccakF(A);
+  }
+  const out = Buffer.alloc(32);
+  for (let i = 0; i < 4; i++) out.writeBigUInt64LE(A[i], i * 8);
+  return `0x${out.toString("hex")}`;
+}
+
+/** The txids this signed Tempo transaction could have landed under: the
+ *  submitted bytes, plus (when the envelope verifiably ends with the 65-byte
+ *  packed signature — RLP string header 0xb841 at the right offset) the
+ *  v-swapped twin: yParity (0/1) <-> legacy (27/28). */
+export function candidateTxIds(signedTx) {
+  const hex = String(signedTx || "").toLowerCase();
+  if (!/^0x76[0-9a-f]{2,}$/.test(hex) || hex.length % 2 !== 0) return [];
+  const out = [keccak256Hex(Buffer.from(hex.slice(2), "hex"))];
+  // b841 = RLP header for a 65-byte string; 134 hex chars = header + 65 bytes.
+  const sigIsLast = hex.length >= 138 && hex.slice(-134, -130) === "b841";
+  if (!sigIsLast) return out;
+  const swap = { "00": "1b", "01": "1c", "1b": "00", "1c": "01" }[hex.slice(-2)];
+  if (swap) out.push(keccak256Hex(Buffer.from(hex.slice(2, -2) + swap, "hex")));
+  return out;
+}
+
+const TRANSFER_TOPIC = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef";
+
+/** Did this credential's transaction settle despite the relay's verdict?
+ *  Returns { txId } when a candidate receipt exists, succeeded (status 0x1),
+ *  and carries the challenge's transfer (currency + recipient + >= amount) —
+ *  else null. Polls briefly (a just-mined tx may not be indexed when the
+ *  relay answers). Never throws. */
+export async function confirmTempoSettlement(credential, { rpcUrl, fetchImpl = globalThis.fetch, attempts = 4, delayMs = 2000 } = {}) {
+  try {
+    const payload = credential?.payload;
+    if (payload?.type !== "transaction" || typeof payload.signature !== "string") return null;
+    let request = credential?.challenge?.request;
+    if (typeof request === "string") { try { request = JSON.parse(unb64url(request)); } catch { return null; } }
+    const currency = String(request?.currency || "").toLowerCase();
+    const recipient = String(request?.recipient || "").toLowerCase();
+    let minAmount;
+    try { minAmount = BigInt(String(request?.amount)); } catch { return null; }
+    if (!currency.startsWith("0x") || !recipient.startsWith("0x") || !(minAmount > 0n)) return null;
+    const candidates = candidateTxIds(payload.signature);
+    if (!candidates.length) return null;
+    for (let i = 0; i < attempts; i++) {
+      if (i > 0) await new Promise((resolve) => setTimeout(resolve, delayMs));
+      for (const txId of candidates) {
+        let receipt;
+        try {
+          const res = await fetchImpl(rpcUrl, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "eth_getTransactionReceipt", params: [txId] }) });
+          if (!res.ok) continue;
+          const body = await res.json();
+          if (body.error) continue;
+          receipt = body.result;
+        } catch { continue; }
+        if (!receipt || receipt.status !== "0x1") continue;
+        for (const log of receipt.logs || []) {
+          if (String(log.address || "").toLowerCase() !== currency) continue;
+          if ((log.topics || [])[0] !== TRANSFER_TOPIC) continue;
+          if (`0x${String(log.topics[2] || "").slice(-40)}`.toLowerCase() !== recipient) continue;
+          let value;
+          try { value = BigInt(log.data); } catch { continue; }
+          if (value >= minAmount) return { txId };
+        }
+      }
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}