@wafermapxyz/cli 0.4.6 → 0.4.7

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.4.7 (4 Nov 2026)
+
+**`history --verify` checks Solana payments.** Until now they showed `unknown`.
+
+- Each Solana payment now logs what it can be found by later: the wallet's own signature (the second one in the transaction; the first, which names it on explorers, is the facilitator's), the memo, the blockhash and the slot it was read at.
+- `wafermap history --verify` reads a Solana RPC, the public one by default (`WAFERMAP_RPC_SOLANA` for another), never Wafermap's, and takes no number from the server that was paid:
+  - The payment is anchored to the block its blockhash names: the block at the logged slot must carry exactly that hash, or the check stops with `error`. The payment can land only after that block, and only until the chain is 150 blocks past it.
+  - `used`: a transaction carrying our signature landed and succeeded (the one the server named, or one found in the wallet's USDC account history).
+  - `unused`: the finalized chain is past the blockhash's last valid height (read first), and the history, read from a node at least that far along and back to the blockhash's block, has no transaction with our signature. Such a payment can never execute. A transaction that landed with our signature and failed moved nothing: also `unused`.
+  - `pending`: not found, and still able to land.
+  - `error`: anything the RPC could not establish for sure (a block or history it cannot return, a time-out). Never `unused` on a doubtful read.
+  - Solana lines logged before 0.4.7 have no signature: they are `used` when the server's transaction shows this wallet signing and its USDC going down by exactly the signed amount (and no other line was given the same transaction), otherwise `unknown`.
+- Reviewed adversarially twice before release. The fixes that came out of it: the expiry is read before the search; the cut-off is a block checked on-chain, not the local clock or a slot from Wafermap's RPC; a fresh blockhash the finalized chain has not reached yet reads `pending`, not `unused`.
+- Solana RPC reads have a 15-second limit and back off on rate limits.
+- SDK: `checkSolanaPayment()` and `SOLANA_PUBLIC_RPC` are exported; `checkPayment()` routes Solana lines to it. `SolanaPayer` gains an optional `blockhashInfo()`; `blockhash()` still returns a string.
+
 ## 0.4.6 (3 Nov 2026)
 
 **`history --verify` tells an executed payment from a cancelled one.** Thank you @GBLIN_Protocol for the catch.

package/README.md

@@ -94,7 +94,7 @@ The caps sit with the key, on your machine. Before the wallet signs anything it
 
 **The daily cap counts what the wallet signed, not what a server says it charged.** Every payment is written to `spend.jsonl` at its full signed amount the moment it is signed, before it is sent, and stays counted whatever the server answers: an error, a receipt saying $0, no receipt, or no answer at all. Check, sign and record run one payment at a time within a process, so calls started together cannot share the same remaining budget. Across processes on the same wallet (two MCP clients, or the CLI next to the MCP server), the wallet re-reads the shared log right after recording a signed payment and, if the cap is now passed, drops that payment before it is sent. (Before 0.3.3 the cap trusted the server's receipt; see [CHANGELOG.md](CHANGELOG.md).)
 
-**What the wallet cannot enforce.** An x402 `exact` payment is a signed authorization (EIP-3009 on EVM chains, a partially signed transaction on Solana). Whoever receives it can execute it once until it expires. The wallet signs EVM authorizations for at most 90 seconds, or less when the server asks for less (300 before 0.4.0). "A failed call costs $0" is therefore a promise of the server you pay: Wafermap's server settles only after the resource worked and otherwise lets the authorization expire unused. You do not have to take that on trust: `wafermap history --verify` asks each token contract (`authorizationState`) whether every signed payment was executed, and shows the ones that expired unused (`error` means the RPC did not answer). Because `authorizationState` is also true after `cancelAuthorization`, a payment only shows as `used` once the contract's `AuthorizationUsed` event for that nonce is found (in the settlement transaction, or in the blocks between signing and expiry); a nonce that is spent but never executed shows as `cancelled`. The search needs `eth_getLogs`, which Base's public RPC refuses; set `WAFERMAP_RPC_BASE` to your own RPC if a Base payment without a transaction on record shows `error`. Solana payments are not checked yet. The caps bound the worst case either way.
+**What the wallet cannot enforce.** An x402 `exact` payment is a signed authorization (EIP-3009 on EVM chains, a partially signed transaction on Solana). Whoever receives it can execute it once until it expires. The wallet signs EVM authorizations for at most 90 seconds, or less when the server asks for less (300 before 0.4.0). "A failed call costs $0" is therefore a promise of the server you pay: Wafermap's server settles only after the resource worked and otherwise lets the authorization expire unused. You do not have to take that on trust: `wafermap history --verify` asks each token contract (`authorizationState`) whether every signed payment was executed, and shows the ones that expired unused (`error` means the RPC did not answer). Because `authorizationState` is also true after `cancelAuthorization`, a payment only shows as `used` once the contract's `AuthorizationUsed` event for that nonce is found (in the settlement transaction, or in the blocks between signing and expiry); a nonce that is spent but never executed shows as `cancelled`. The search needs `eth_getLogs`, which Base's public RPC refuses; set `WAFERMAP_RPC_BASE` to your own RPC if a Base payment without a transaction on record shows `error`. Solana payments are checked too, on the public Solana RPC by default (`WAFERMAP_RPC_SOLANA` to use another), not on Wafermap's: from 0.4.7 the wallet logs its own signature, the memo, the blockhash and its slot for each Solana payment. The check anchors the payment to the block its blockhash names (verified on-chain), and shows `used` when a transaction carrying the wallet's signature landed and succeeded, `unused` when the chain is past the blockhash's last valid height and the wallet's USDC history back to that block has no such transaction, and `pending` otherwise. Anything the RPC cannot establish for sure shows `error`, never `unused`. Solana payments logged before 0.4.7 can only be confirmed through the transaction the server named; otherwise they show `unknown`. The caps bound the worst case either way.
 
 **Time limits.** Requests to paid resources and services, to Wafermap's API, to the swap API and to Solana RPC give up after 60 seconds (`timeoutMs` in the SDK); EVM RPC calls keep viem's own time-outs. `wafermap resources` uses the same limit. Set `WAFERMAP_TIMEOUT_MS` to change it for the CLI and the MCP server. A paid call that times out after the payment was signed says so: the payment stays counted, and for EVM payments the message says until when it can be executed.
 

package/dist/cli.js

@@ -202,7 +202,7 @@ function ataOf(owner, mint = SOLANA_USDC) {
   }
   throw new Error("No associated token account address.");
 }
-async function solanaPayment(payer, q) {
+async function solanaPaymentSigned(payer, q) {
   if (q.asset !== SOLANA_USDC) throw new Error("Only USDC is paid on Solana.");
   if (!isSolanaAddress(q.feePayer) || !isSolanaAddress(q.payTo)) throw new Error("The quote has no valid Solana fee payer or recipient.");
   if (q.feePayer === payer.address) throw new Error("The fee payer cannot be the paying wallet.");
@@ -219,19 +219,26 @@ async function solanaPayment(payer, q) {
     { program: TOKEN_PROGRAM, accounts: [source, q.asset, dest, payer.address], data: concat(Uint8Array.of(12), le(BigInt(q.amount), 8), Uint8Array.of(USDC_DECIMALS)) },
     { program: MEMO_PROGRAM, accounts: [], data: memo }
   ];
+  const bh = payer.blockhashInfo ? await payer.blockhashInfo() : { blockhash: await payer.blockhash() };
   const message = concat(
     Uint8Array.of(128, 2, 1, 4),
     // v0; 2 signatures, 1 of them readonly; 4 readonly non-signers
     shortvec(keys.length),
     ...keys.map((k) => base58.decode(k)),
-    base58.decode(await payer.blockhash()),
+    base58.decode(bh.blockhash),
     shortvec(ixs.length),
     ...ixs.map((ix) => concat(Uint8Array.of(at(ix.program)), shortvec(ix.accounts.length), Uint8Array.from(ix.accounts.map(at)), shortvec(ix.data.length), ix.data)),
     shortvec(0)
     // no address lookup tables
   );
   const signature = await payer.sign(message);
-  return base64.encode(concat(shortvec(2), new Uint8Array(64), signature, message));
+  return {
+    transaction: base64.encode(concat(shortvec(2), new Uint8Array(64), signature, message)),
+    signature: base58.encode(signature),
+    memo: new TextDecoder().decode(memo),
+    blockhash: bh.blockhash,
+    ..."slot" in bh && Number.isFinite(bh.slot) ? { slot: bh.slot } : {}
+  };
 }
 async function solanaRpc(url, method, params, f = fetch) {
   const r = await f(url, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }) });
@@ -240,6 +247,70 @@ async function solanaRpc(url, method, params, f = fetch) {
   if (j.error) throw new Error(j.error.message ?? "Solana RPC error.");
   return j.result;
 }
+async function solanaRead(url, method, params, f = fetch) {
+  const timed = (input, init) => f(input, { ...init, signal: AbortSignal.timeout(READ_TIMEOUT_MS) });
+  for (let attempt = 0; ; attempt++) {
+    try {
+      return await solanaRpc(url, method, params, timed);
+    } catch (e) {
+      if (attempt >= 6 || !/429|rate|too many/i.test(String(e?.message))) throw e;
+      await new Promise((r) => setTimeout(r, 1e3 * 2 ** attempt * (0.75 + Math.random() / 2)));
+    }
+  }
+}
+async function txOutcome(url, tx, e, f) {
+  const t = await solanaRead(url, "getTransaction", [tx, { encoding: "json", maxSupportedTransactionVersion: 0, commitment: "confirmed" }], f);
+  if (!t) return null;
+  const sigs = t.transaction?.signatures ?? [];
+  const keys = t.transaction?.message?.accountKeys ?? [];
+  if (e.sig ? !sigs.includes(e.sig) : keys[1] !== e.payer) return "other";
+  if (t.meta?.err) return "failed";
+  if (!e.sig) {
+    const bal = (list) => BigInt(list?.find((b) => b.owner === e.payer && b.mint === SOLANA_USDC)?.uiTokenAmount?.amount ?? "0");
+    const drop = bal(t.meta?.preTokenBalances) - bal(t.meta?.postTokenBalances);
+    if (drop <= 0n || e.usd !== void 0 && drop !== BigInt(Math.round(e.usd * 1e6))) return "other";
+  }
+  return "ok";
+}
+async function checkSolanaPayment(e, url = SOLANA_PUBLIC_RPC, f) {
+  if (e.tx) {
+    const o = await txOutcome(url, e.tx, e, f).catch(() => null);
+    if (o === "ok") return "used";
+    if (o === "failed" && e.sig) return "unused";
+  }
+  if (!e.sig || !e.blockhash || !Number.isSafeInteger(e.slot) || e.slot <= 0) return "unknown";
+  const slot = e.slot;
+  const block = await solanaRead(url, "getBlock", [slot, { commitment: "confirmed", transactionDetails: "none", rewards: false, maxSupportedTransactionVersion: 0 }], f);
+  if (!block || block.blockhash !== e.blockhash || !Number.isSafeInteger(block.blockHeight)) throw new Error("The chain has no block with this payment's blockhash at the logged slot.");
+  const lastValidHeight = block.blockHeight + BLOCKHASH_MAX_AGE;
+  const fin = await solanaRead(url, "getEpochInfo", [{ commitment: "finalized" }], f);
+  const S = Number(fin?.absoluteSlot);
+  const H = Number(fin?.blockHeight);
+  if (!Number.isSafeInteger(S) || !Number.isSafeInteger(H)) throw new Error("The RPC did not give the finalized height.");
+  const expired = H > lastValidHeight;
+  let before;
+  let reached = false;
+  search: for (let page = 0; page < 20; page++) {
+    const list = await solanaRead(url, "getSignaturesForAddress", [ataOf(e.payer), { limit: 1e3, commitment: "confirmed", minContextSlot: S, ...before ? { before } : {} }], f);
+    if (!Array.isArray(list)) throw new Error("The RPC did not return the wallet's history.");
+    for (const x of list) {
+      if (!Number.isSafeInteger(x.slot)) throw new Error("The RPC returned history without slots.");
+      if (x.slot <= slot) {
+        reached = true;
+        break search;
+      }
+      if (e.memo && typeof x.memo === "string" && x.memo && !x.memo.includes(e.memo)) continue;
+      const o = await txOutcome(url, x.signature, e, f);
+      if (o === "ok") return "used";
+      if (o === "failed") return "unused";
+      if (o === null) throw new Error("The RPC lists a transaction it cannot return.");
+    }
+    if (list.length < 1e3) break;
+    before = list[list.length - 1].signature;
+  }
+  if (!reached) throw new Error("Could not read the wallet's history back to this payment.");
+  return expired ? "unused" : "pending";
+}
 async function solanaBalances(url, owner, f) {
   const [usdc, lamports] = await Promise.all([
     solanaRpc(url, "getAccountInfo", [ataOf(owner), { commitment: "confirmed", encoding: "jsonParsed" }], f).then((r) => String(r.value?.data?.parsed?.info?.tokenAmount?.uiAmountString ?? "0")),
@@ -247,7 +318,7 @@ async function solanaBalances(url, owner, f) {
   ]);
   return { usdc, sol: String(lamports / 1e9) };
 }
-var SOLANA_CAIP, SOLANA_USDC, USDC_DECIMALS, TOKEN_PROGRAM, ATA_PROGRAM, COMPUTE_BUDGET, MEMO_PROGRAM, CU_LIMIT, CU_PRICE_MICROLAMPORTS, MAX_MEMO_BYTES, utf8, concat, hexBytes, le, shortvec, onCurve, latestBlockhash;
+var SOLANA_CAIP, SOLANA_USDC, USDC_DECIMALS, TOKEN_PROGRAM, ATA_PROGRAM, COMPUTE_BUDGET, MEMO_PROGRAM, CU_LIMIT, CU_PRICE_MICROLAMPORTS, MAX_MEMO_BYTES, utf8, concat, hexBytes, le, shortvec, onCurve, latestBlockhash, latestBlockhashInfo, SOLANA_PUBLIC_RPC, READ_TIMEOUT_MS, BLOCKHASH_MAX_AGE;
 var init_solana = __esm({
   "shared/solana.ts"() {
     "use strict";
@@ -291,7 +362,14 @@ var init_solana = __esm({
         return false;
       }
     };
-    latestBlockhash = async (url, f) => (await solanaRpc(url, "getLatestBlockhash", [{ commitment: "confirmed" }], f)).value.blockhash;
+    latestBlockhash = async (url, f) => (await latestBlockhashInfo(url, f)).blockhash;
+    latestBlockhashInfo = async (url, f) => {
+      const r = await solanaRpc(url, "getLatestBlockhash", [{ commitment: "confirmed" }], f);
+      return { blockhash: r.value.blockhash, slot: Number(r.context?.slot) };
+    };
+    SOLANA_PUBLIC_RPC = "https://api.mainnet-beta.solana.com";
+    READ_TIMEOUT_MS = 15e3;
+    BLOCKHASH_MAX_AGE = 150;
   }
 });
 
@@ -375,14 +453,17 @@ async function signPayment(signer, req, resource, solana) {
   if (req.chain.vm === "svm") {
     if (!solana) throw new X402Error("no_solana_wallet", "This payment is on Solana and no Solana wallet was given.");
     let transaction;
+    let sol;
     try {
-      transaction = await solanaPayment(solana, { amount: req.amount, payTo: req.payTo, asset: req.asset, feePayer: req.extra.feePayer, memo: req.extra.memo });
+      const s = await solanaPaymentSigned(solana, { amount: req.amount, payTo: req.payTo, asset: req.asset, feePayer: req.extra.feePayer, memo: req.extra.memo });
+      transaction = s.transaction;
+      sol = { sig: s.signature, memo: s.memo, blockhash: s.blockhash, ...s.slot !== void 0 ? { slot: s.slot } : {} };
     } catch (e) {
       if (e?.name === "TimeoutError" || e?.cause?.name === "TimeoutError") throw e;
       throw new X402Error("sign_failed", e?.message ?? "Could not build the Solana payment.");
     }
-    if (req.version === 1) return { name: "X-PAYMENT", value: b64encode(JSON.stringify({ x402Version: 1, scheme: "exact", network: req.raw.network, payload: { transaction } })) };
-    return { name: "PAYMENT-SIGNATURE", value: b64encode(JSON.stringify({ x402Version: 2, resource, accepted: req.raw, payload: { transaction } })) };
+    if (req.version === 1) return { name: "X-PAYMENT", value: b64encode(JSON.stringify({ x402Version: 1, scheme: "exact", network: req.raw.network, payload: { transaction } })), sol };
+    return { name: "PAYMENT-SIGNATURE", value: b64encode(JSON.stringify({ x402Version: 2, resource, accepted: req.raw, payload: { transaction } })), sol };
   }
   const nonce = randomNonce();
   const validBefore = BigInt(Math.floor(Date.now() / 1e3) + Math.min(req.maxTimeoutSeconds, MAX_VALIDITY_SECONDS));
@@ -436,7 +517,7 @@ async function x402fetch(url, init, opts) {
   const svm = req.chain.vm === "svm";
   const signer = svm ? null : typeof opts.signer === "function" ? await opts.signer() : opts.signer;
   const header = await signPayment(signer, req, quote.resource, opts.solana);
-  const signed = { req, from: svm ? opts.solana.address : signer.address, ...header.auth ? { auth: header.auth } : {} };
+  const signed = { req, from: svm ? opts.solana.address : signer.address, ...header.auth ? { auth: header.auth } : {}, ...header.sol ? { sol: header.sol } : {} };
   opts.onSigned?.(signed);
   const headers = new Headers(init.headers);
   headers.set(header.name, header.value);
@@ -592,7 +673,8 @@ async function blockAt(client, ts, side, latest) {
   return side === "from" ? lo.number : hi.number;
 }
 async function checkPayment(e, rpc) {
-  if (e.network === "solana" || !e.nonce || !(e.network in CHAINS)) return "unknown";
+  if (e.network === "solana") return checkSolanaPayment(e, rpc).catch(() => "error");
+  if (!e.nonce || !(e.network in CHAINS)) return "unknown";
   const chain = PAY_CHAINS.find((c) => c.key === e.network);
   try {
     const client = createPublicClient({ chain: CHAINS[e.network], transport: http(rpc) });
@@ -703,7 +785,7 @@ var init_core = __esm({
         this.fetch = (input, init) => fetch(input, { ...init, signal: init?.signal ?? AbortSignal.timeout(this.timeoutMs) });
         const sol = o.solana ?? (o.privateKey ? solanaKeyFromEvm(o.privateKey) : null);
         const solRpc = this.rpc.solana ?? `${this.baseUrl}/api/solana`;
-        this.solana = sol ? { address: sol.address, sign: sol.sign, blockhash: () => latestBlockhash(solRpc, this.fetch) } : null;
+        this.solana = sol ? { address: sol.address, sign: sol.sign, blockhash: () => latestBlockhash(solRpc, this.fetch), blockhashInfo: () => latestBlockhashInfo(solRpc, this.fetch) } : null;
         this.solanaAddress = sol?.address ?? o.solanaAddress ?? null;
       }
       get address() {
@@ -742,7 +824,7 @@ var init_core = __esm({
       /** Write the signed payment to the ledger before it leaves the machine. */
       booked(kind, what, s) {
         const id = crypto.randomUUID();
-        this.ledger.record({ at: Date.now(), kind, what, usd: s.req.usd, network: s.req.chain.key, tx: null, payer: s.from, id, status: "signed", ...s.auth ? { nonce: s.auth.nonce, validBefore: s.auth.validBefore } : {} });
+        this.ledger.record({ at: Date.now(), kind, what, usd: s.req.usd, network: s.req.chain.key, tx: null, payer: s.from, id, status: "signed", ...s.auth ? { nonce: s.auth.nonce, validBefore: s.auth.validBefore } : {}, ...s.sol ? { sig: s.sol.sig, memo: s.sol.memo, blockhash: s.sol.blockhash, ...s.sol.slot !== void 0 ? { slot: s.sol.slot } : {} } : {} });
         return id;
       }
       /** The outcome line for a booked payment. It adds nothing to the daily total. */
@@ -1162,7 +1244,7 @@ var VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    VERSION = "0.4.6";
+    VERSION = "0.4.7";
   }
 });
 
@@ -1912,14 +1994,18 @@ async function main() {
       const rows = mergeLog(spendLog()).filter((e) => e.at >= since).reverse();
       if (!rows.length) return console.log(`Nothing in the last ${days} days.`);
       const verify = a.flags.verify !== void 0;
-      const RPC = { robinhood: process.env.WAFERMAP_RPC_ROBINHOOD, base: process.env.WAFERMAP_RPC_BASE, arbitrum: process.env.WAFERMAP_RPC_ARBITRUM, polygon: process.env.WAFERMAP_RPC_POLYGON };
+      const RPC = { robinhood: process.env.WAFERMAP_RPC_ROBINHOOD, base: process.env.WAFERMAP_RPC_BASE, arbitrum: process.env.WAFERMAP_RPC_ARBITRUM, polygon: process.env.WAFERMAP_RPC_POLYGON, solana: process.env.WAFERMAP_RPC_SOLANA };
       const chain = [];
       if (verify) {
+        const txCount = /* @__PURE__ */ new Map();
+        for (const e of rows) if (e.network === "solana" && e.tx) txCount.set(e.tx, (txCount.get(e.tx) ?? 0) + 1);
         let next = 0;
         await Promise.all(Array.from({ length: 4 }, async () => {
           while (next < rows.length) {
             const i = next++;
-            chain[i] = rows[i].kind === "swap" ? null : await checkPayment(rows[i], RPC[rows[i].network]);
+            const e = rows[i];
+            const shared = e.network === "solana" && !e.sig && !!e.tx && (txCount.get(e.tx) ?? 0) > 1;
+            chain[i] = e.kind === "swap" ? null : await checkPayment(shared ? { ...e, tx: null } : e, RPC[e.network]);
           }
         }));
       }
@@ -1934,7 +2020,7 @@ Total $${total.toFixed(4)} in ${pays.length} payments. From 0.3.3 every payment
       if (verify) {
         const never = rows.filter((e, i) => e.kind !== "swap" && chain[i] === "unused").reduce((s, e) => s + e.usd, 0);
         const cancelled = rows.filter((e, i) => e.kind !== "swap" && chain[i] === "cancelled").reduce((s, e) => s + e.usd, 0);
-        console.log(`On-chain: $${never.toFixed(4)} of that was signed but never executed and has expired${cancelled ? `, and $${cancelled.toFixed(4)} was cancelled by this wallet before it executed` : ""}. "used" = the token contract logged the transfer (AuthorizationUsed); "cancelled" = the nonce is spent but never executed (cancelAuthorization); "unknown" = Solana or an older log line; "error" = the RPC did not answer, try again (Base's public RPC refuses log searches: for a payment with no transaction on record, set WAFERMAP_RPC_BASE to your own RPC).`);
+        console.log(`On-chain: $${never.toFixed(4)} of that was signed but never executed and has expired${cancelled ? `, and $${cancelled.toFixed(4)} was cancelled by this wallet before it executed` : ""}. "used" = the token contract logged the transfer (AuthorizationUsed); "cancelled" = the nonce is spent but never executed (cancelAuthorization); "unknown" = an older log line with nothing to check by; "error" = the RPC did not answer, try again (Base's public RPC refuses log searches: for a payment with no transaction on record, set WAFERMAP_RPC_BASE to your own RPC).`);
       } else console.log("Add --verify to check on-chain which signed payments were executed.");
       return;
     }

package/dist/index.js

@@ -225,7 +225,7 @@ function ataOf(owner, mint = SOLANA_USDC) {
   }
   throw new Error("No associated token account address.");
 }
-async function solanaPayment(payer, q) {
+async function solanaPaymentSigned(payer, q) {
   if (q.asset !== SOLANA_USDC) throw new Error("Only USDC is paid on Solana.");
   if (!isSolanaAddress(q.feePayer) || !isSolanaAddress(q.payTo)) throw new Error("The quote has no valid Solana fee payer or recipient.");
   if (q.feePayer === payer.address) throw new Error("The fee payer cannot be the paying wallet.");
@@ -242,19 +242,26 @@ async function solanaPayment(payer, q) {
     { program: TOKEN_PROGRAM, accounts: [source, q.asset, dest, payer.address], data: concat(Uint8Array.of(12), le(BigInt(q.amount), 8), Uint8Array.of(USDC_DECIMALS)) },
     { program: MEMO_PROGRAM, accounts: [], data: memo }
   ];
+  const bh = payer.blockhashInfo ? await payer.blockhashInfo() : { blockhash: await payer.blockhash() };
   const message = concat(
     Uint8Array.of(128, 2, 1, 4),
     // v0; 2 signatures, 1 of them readonly; 4 readonly non-signers
     shortvec(keys.length),
     ...keys.map((k) => base58.decode(k)),
-    base58.decode(await payer.blockhash()),
+    base58.decode(bh.blockhash),
     shortvec(ixs.length),
     ...ixs.map((ix) => concat(Uint8Array.of(at(ix.program)), shortvec(ix.accounts.length), Uint8Array.from(ix.accounts.map(at)), shortvec(ix.data.length), ix.data)),
     shortvec(0)
     // no address lookup tables
   );
   const signature = await payer.sign(message);
-  return base64.encode(concat(shortvec(2), new Uint8Array(64), signature, message));
+  return {
+    transaction: base64.encode(concat(shortvec(2), new Uint8Array(64), signature, message)),
+    signature: base58.encode(signature),
+    memo: new TextDecoder().decode(memo),
+    blockhash: bh.blockhash,
+    ..."slot" in bh && Number.isFinite(bh.slot) ? { slot: bh.slot } : {}
+  };
 }
 async function solanaRpc(url, method, params, f = fetch) {
   const r = await f(url, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }) });
@@ -263,7 +270,78 @@ async function solanaRpc(url, method, params, f = fetch) {
   if (j.error) throw new Error(j.error.message ?? "Solana RPC error.");
   return j.result;
 }
-var latestBlockhash = async (url, f) => (await solanaRpc(url, "getLatestBlockhash", [{ commitment: "confirmed" }], f)).value.blockhash;
+var latestBlockhash = async (url, f) => (await latestBlockhashInfo(url, f)).blockhash;
+var latestBlockhashInfo = async (url, f) => {
+  const r = await solanaRpc(url, "getLatestBlockhash", [{ commitment: "confirmed" }], f);
+  return { blockhash: r.value.blockhash, slot: Number(r.context?.slot) };
+};
+var SOLANA_PUBLIC_RPC = "https://api.mainnet-beta.solana.com";
+var READ_TIMEOUT_MS = 15e3;
+async function solanaRead(url, method, params, f = fetch) {
+  const timed = (input, init) => f(input, { ...init, signal: AbortSignal.timeout(READ_TIMEOUT_MS) });
+  for (let attempt = 0; ; attempt++) {
+    try {
+      return await solanaRpc(url, method, params, timed);
+    } catch (e) {
+      if (attempt >= 6 || !/429|rate|too many/i.test(String(e?.message))) throw e;
+      await new Promise((r) => setTimeout(r, 1e3 * 2 ** attempt * (0.75 + Math.random() / 2)));
+    }
+  }
+}
+async function txOutcome(url, tx, e, f) {
+  const t = await solanaRead(url, "getTransaction", [tx, { encoding: "json", maxSupportedTransactionVersion: 0, commitment: "confirmed" }], f);
+  if (!t) return null;
+  const sigs = t.transaction?.signatures ?? [];
+  const keys = t.transaction?.message?.accountKeys ?? [];
+  if (e.sig ? !sigs.includes(e.sig) : keys[1] !== e.payer) return "other";
+  if (t.meta?.err) return "failed";
+  if (!e.sig) {
+    const bal = (list) => BigInt(list?.find((b) => b.owner === e.payer && b.mint === SOLANA_USDC)?.uiTokenAmount?.amount ?? "0");
+    const drop = bal(t.meta?.preTokenBalances) - bal(t.meta?.postTokenBalances);
+    if (drop <= 0n || e.usd !== void 0 && drop !== BigInt(Math.round(e.usd * 1e6))) return "other";
+  }
+  return "ok";
+}
+var BLOCKHASH_MAX_AGE = 150;
+async function checkSolanaPayment(e, url = SOLANA_PUBLIC_RPC, f) {
+  if (e.tx) {
+    const o = await txOutcome(url, e.tx, e, f).catch(() => null);
+    if (o === "ok") return "used";
+    if (o === "failed" && e.sig) return "unused";
+  }
+  if (!e.sig || !e.blockhash || !Number.isSafeInteger(e.slot) || e.slot <= 0) return "unknown";
+  const slot = e.slot;
+  const block = await solanaRead(url, "getBlock", [slot, { commitment: "confirmed", transactionDetails: "none", rewards: false, maxSupportedTransactionVersion: 0 }], f);
+  if (!block || block.blockhash !== e.blockhash || !Number.isSafeInteger(block.blockHeight)) throw new Error("The chain has no block with this payment's blockhash at the logged slot.");
+  const lastValidHeight = block.blockHeight + BLOCKHASH_MAX_AGE;
+  const fin = await solanaRead(url, "getEpochInfo", [{ commitment: "finalized" }], f);
+  const S = Number(fin?.absoluteSlot);
+  const H = Number(fin?.blockHeight);
+  if (!Number.isSafeInteger(S) || !Number.isSafeInteger(H)) throw new Error("The RPC did not give the finalized height.");
+  const expired = H > lastValidHeight;
+  let before;
+  let reached = false;
+  search: for (let page = 0; page < 20; page++) {
+    const list = await solanaRead(url, "getSignaturesForAddress", [ataOf(e.payer), { limit: 1e3, commitment: "confirmed", minContextSlot: S, ...before ? { before } : {} }], f);
+    if (!Array.isArray(list)) throw new Error("The RPC did not return the wallet's history.");
+    for (const x of list) {
+      if (!Number.isSafeInteger(x.slot)) throw new Error("The RPC returned history without slots.");
+      if (x.slot <= slot) {
+        reached = true;
+        break search;
+      }
+      if (e.memo && typeof x.memo === "string" && x.memo && !x.memo.includes(e.memo)) continue;
+      const o = await txOutcome(url, x.signature, e, f);
+      if (o === "ok") return "used";
+      if (o === "failed") return "unused";
+      if (o === null) throw new Error("The RPC lists a transaction it cannot return.");
+    }
+    if (list.length < 1e3) break;
+    before = list[list.length - 1].signature;
+  }
+  if (!reached) throw new Error("Could not read the wallet's history back to this payment.");
+  return expired ? "unused" : "pending";
+}
 async function solanaBalances(url, owner, f) {
   const [usdc, lamports] = await Promise.all([
     solanaRpc(url, "getAccountInfo", [ataOf(owner), { commitment: "confirmed", encoding: "jsonParsed" }], f).then((r) => String(r.value?.data?.parsed?.info?.tokenAmount?.uiAmountString ?? "0")),
@@ -406,14 +484,17 @@ async function signPayment(signer, req, resource, solana) {
   if (req.chain.vm === "svm") {
     if (!solana) throw new X402Error("no_solana_wallet", "This payment is on Solana and no Solana wallet was given.");
     let transaction;
+    let sol;
     try {
-      transaction = await solanaPayment(solana, { amount: req.amount, payTo: req.payTo, asset: req.asset, feePayer: req.extra.feePayer, memo: req.extra.memo });
+      const s = await solanaPaymentSigned(solana, { amount: req.amount, payTo: req.payTo, asset: req.asset, feePayer: req.extra.feePayer, memo: req.extra.memo });
+      transaction = s.transaction;
+      sol = { sig: s.signature, memo: s.memo, blockhash: s.blockhash, ...s.slot !== void 0 ? { slot: s.slot } : {} };
     } catch (e) {
       if (e?.name === "TimeoutError" || e?.cause?.name === "TimeoutError") throw e;
       throw new X402Error("sign_failed", e?.message ?? "Could not build the Solana payment.");
     }
-    if (req.version === 1) return { name: "X-PAYMENT", value: b64encode(JSON.stringify({ x402Version: 1, scheme: "exact", network: req.raw.network, payload: { transaction } })) };
-    return { name: "PAYMENT-SIGNATURE", value: b64encode(JSON.stringify({ x402Version: 2, resource, accepted: req.raw, payload: { transaction } })) };
+    if (req.version === 1) return { name: "X-PAYMENT", value: b64encode(JSON.stringify({ x402Version: 1, scheme: "exact", network: req.raw.network, payload: { transaction } })), sol };
+    return { name: "PAYMENT-SIGNATURE", value: b64encode(JSON.stringify({ x402Version: 2, resource, accepted: req.raw, payload: { transaction } })), sol };
   }
   const nonce = randomNonce();
   const validBefore = BigInt(Math.floor(Date.now() / 1e3) + Math.min(req.maxTimeoutSeconds, MAX_VALIDITY_SECONDS));
@@ -467,7 +548,7 @@ async function x402fetch(url, init, opts) {
   const svm = req.chain.vm === "svm";
   const signer = svm ? null : typeof opts.signer === "function" ? await opts.signer() : opts.signer;
   const header = await signPayment(signer, req, quote.resource, opts.solana);
-  const signed = { req, from: svm ? opts.solana.address : signer.address, ...header.auth ? { auth: header.auth } : {} };
+  const signed = { req, from: svm ? opts.solana.address : signer.address, ...header.auth ? { auth: header.auth } : {}, ...header.sol ? { sol: header.sol } : {} };
   opts.onSigned?.(signed);
   const headers = new Headers(init.headers);
   headers.set(header.name, header.value);
@@ -552,7 +633,8 @@ async function blockAt(client, ts, side, latest) {
 }
 var AUTH_USED = parseAbiItem("event AuthorizationUsed(address indexed authorizer, bytes32 indexed nonce)");
 async function checkPayment(e, rpc) {
-  if (e.network === "solana" || !e.nonce || !(e.network in CHAINS)) return "unknown";
+  if (e.network === "solana") return checkSolanaPayment(e, rpc).catch(() => "error");
+  if (!e.nonce || !(e.network in CHAINS)) return "unknown";
   const chain = PAY_CHAINS.find((c) => c.key === e.network);
   try {
     const client = createPublicClient({ chain: CHAINS[e.network], transport: http(rpc) });
@@ -642,7 +724,7 @@ var Wafermap = class {
     this.fetch = (input, init) => fetch(input, { ...init, signal: init?.signal ?? AbortSignal.timeout(this.timeoutMs) });
     const sol = o.solana ?? (o.privateKey ? solanaKeyFromEvm(o.privateKey) : null);
     const solRpc = this.rpc.solana ?? `${this.baseUrl}/api/solana`;
-    this.solana = sol ? { address: sol.address, sign: sol.sign, blockhash: () => latestBlockhash(solRpc, this.fetch) } : null;
+    this.solana = sol ? { address: sol.address, sign: sol.sign, blockhash: () => latestBlockhash(solRpc, this.fetch), blockhashInfo: () => latestBlockhashInfo(solRpc, this.fetch) } : null;
     this.solanaAddress = sol?.address ?? o.solanaAddress ?? null;
   }
   get address() {
@@ -681,7 +763,7 @@ var Wafermap = class {
   /** Write the signed payment to the ledger before it leaves the machine. */
   booked(kind, what, s) {
     const id = crypto.randomUUID();
-    this.ledger.record({ at: Date.now(), kind, what, usd: s.req.usd, network: s.req.chain.key, tx: null, payer: s.from, id, status: "signed", ...s.auth ? { nonce: s.auth.nonce, validBefore: s.auth.validBefore } : {} });
+    this.ledger.record({ at: Date.now(), kind, what, usd: s.req.usd, network: s.req.chain.key, tx: null, payer: s.from, id, status: "signed", ...s.auth ? { nonce: s.auth.nonce, validBefore: s.auth.validBefore } : {}, ...s.sol ? { sig: s.sol.sig, memo: s.sol.memo, blockhash: s.sol.blockhash, ...s.sol.slot !== void 0 ? { slot: s.sol.slot } : {} } : {} });
     return id;
   }
   /** The outcome line for a booked payment. It adds nothing to the daily total. */
@@ -908,6 +990,7 @@ export {
   PASS_HEADER,
   PAY_CHAINS,
   PERMIT2,
+  SOLANA_PUBLIC_RPC,
   SwapError,
   WAFERMAP_RELAYERS,
   WAFERMAP_TOKEN,
@@ -915,6 +998,7 @@ export {
   WafermapError,
   X402Error,
   checkPayment,
+  checkSolanaPayment,
   choose,
   decodePass,
   decodeSwap,

package/dist/types/shared/solana.d.ts

@@ -1,10 +1,16 @@
 export declare const SOLANA_CAIP = "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
 export declare const SOLANA_USDC = "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
-/** Signs as one Solana address. `blockhash` returns a recent blockhash from any mainnet RPC. */
+/** Signs as one Solana address. `blockhash` returns a recent blockhash from any mainnet RPC. When
+ *  `blockhashInfo` is given it is used instead, and the slot the blockhash was read at is kept with
+ *  the payment: the payment cannot land before it, which bounds the search for it later. */
 export type SolanaPayer = {
     address: string;
     sign: (message: Uint8Array) => Uint8Array | Promise<Uint8Array>;
     blockhash: () => Promise<string>;
+    blockhashInfo?: () => Promise<{
+        blockhash: string;
+        slot: number;
+    }>;
 };
 export declare function isSolanaAddress(v: string): boolean;
 /** The agent's Solana keypair, derived from its EVM private key. */
@@ -25,8 +31,53 @@ export type SolanaQuote = {
 };
 /** The base64 wire transaction for an x402 `exact` payment on Solana, signed by `payer` only. */
 export declare function solanaPayment(payer: SolanaPayer, q: SolanaQuote): Promise<string>;
+/** What a signed Solana payment leaves to check it by later: our signature (the second one in the
+ *  transaction; the first, which names it on explorers, is the facilitator's and unknown until it
+ *  submits), its memo, its blockhash (once that is no longer valid the payment can never execute)
+ *  and, when known, the slot the blockhash was read at. */
+export type SolanaSigned = {
+    transaction: string;
+    signature: string;
+    memo: string;
+    blockhash: string;
+    slot?: number;
+};
+export declare function solanaPaymentSigned(payer: SolanaPayer, q: SolanaQuote): Promise<SolanaSigned>;
 export declare function solanaRpc(url: string, method: string, params: unknown[], f?: typeof fetch): Promise<any>;
 export declare const latestBlockhash: (url: string, f?: typeof fetch) => Promise<string>;
+export declare const latestBlockhashInfo: (url: string, f?: typeof fetch) => Promise<{
+    blockhash: string;
+    slot: number;
+}>;
+/** The public Solana RPC that `checkSolanaPayment` reads by default: not Wafermap's, so the answer
+ *  does not depend on the server that was paid. */
+export declare const SOLANA_PUBLIC_RPC = "https://api.mainnet-beta.solana.com";
+export type SolanaCheck = {
+    payer: string;
+    usd?: number;
+    tx?: string | null;
+    sig?: string;
+    memo?: string;
+    blockhash?: string;
+    slot?: number;
+};
+/**
+ * Was a signed Solana payment ever executed? Read from a Solana RPC (by default the public one, not
+ * Wafermap's), and every number it rests on is checked on that RPC, not taken from the server
+ * that was paid.
+ *  - The transaction the server named, if it carries our signature: "used" when it succeeded.
+ *  - Otherwise the payment is anchored to the block its blockhash names: the block at the logged
+ *    slot must have exactly that hash. The payment can only land after that slot, and only until
+ *    the chain is BLOCKHASH_MAX_AGE blocks past it. Then, with the finalized height H at slot S:
+ *    the wallet's USDC account history, read from a node at slot S or later, back to that slot,
+ *    is searched for our signature. Found: "used" (or "unused" if it landed and failed: nothing
+ *    moved, and it cannot land again). Not found: "unused" when H is past the last valid height
+ *    (any landing would then be final and in that history), else "pending".
+ *  - Anything that cannot be established that way throws (the CLI shows "error"); it is never
+ *    "unused". Lines from before 0.4.7 have no signature: only the server's transaction can prove
+ *    them ("used"), else "unknown".
+ */
+export declare function checkSolanaPayment(e: SolanaCheck, url?: string, f?: typeof fetch): Promise<"used" | "unused" | "pending" | "unknown">;
 /** USDC (6 decimals) and SOL balances of a wallet. A wallet that never held USDC has no token
  *  account: 0. Read with getAccountInfo, which free public RPCs serve (getTokenAccountBalance is
  *  an "indexed" call some of them reserve for paid keys). */

package/dist/types/shared/x402client.d.ts

@@ -98,6 +98,7 @@ export declare function signPayment(signer: Signer, req: Requirement, resource:
     name: string;
     value: string;
     auth?: SignedAuth;
+    sol?: SignedSol;
 }>;
 /** Settlement details a server returns after a paid call, when it sends them. */
 export declare function readSettlement(res: Response): {
@@ -111,10 +112,19 @@ export type SignedAuth = {
     nonce: Hex;
     validBefore: number;
 };
+/** What a Solana payment can be found by on-chain later (see checkSolanaPayment): our signature, its
+ *  memo, its blockhash and the slot that blockhash was read at. */
+export type SignedSol = {
+    sig: string;
+    memo: string;
+    blockhash: string;
+    slot?: number;
+};
 export type Signed = {
     req: Requirement;
     from: string;
     auth?: SignedAuth;
+    sol?: SignedSol;
     token?: {
         amount: string;
     };

package/dist/types/src/core.d.ts

@@ -31,6 +31,11 @@ export type SpendEntry = {
     /** EVM payments: the EIP-3009 nonce and expiry, to check on-chain whether it was ever used. */
     nonce?: string;
     validBefore?: number;
+    /** Solana payments (from 0.4.7): our signature, the memo, the blockhash and the slot it was read at. */
+    sig?: string;
+    memo?: string;
+    blockhash?: string;
+    slot?: number;
     /** What the server said it charged, for the record only. */
     reported?: number | null;
 };
@@ -87,10 +92,11 @@ export declare function mergeLog(entries: SpendEntry[]): SpendEntry[];
  * can never be charged. authorizationState is also true after cancelAuthorization, so a true is
  * confirmed by the AuthorizationUsed event: first in the receipt of the transaction the server
  * named, else in the blocks between signing and expiry, the only time it could have executed.
- * None there means the nonce was cancelled, never executed ("cancelled"). Solana payments and old
- * log lines without a nonce come back "unknown"; an RPC failure comes back "error".
+ * None there means the nonce was cancelled, never executed ("cancelled"). Solana payments are
+ * checked by checkSolanaPayment (shared/solana.ts), by default on the public Solana RPC. Old log
+ * lines with nothing to check by come back "unknown"; an RPC failure comes back "error".
  */
-export declare function checkPayment(e: Pick<SpendEntry, "network" | "payer" | "nonce" | "validBefore"> & {
+export declare function checkPayment(e: Pick<SpendEntry, "network" | "payer" | "nonce" | "validBefore"> & Partial<Pick<SpendEntry, "sig" | "memo" | "blockhash" | "slot" | "usd">> & {
     at?: number;
     tx?: string | null;
 }, rpc?: string): Promise<"used" | "cancelled" | "unused" | "pending" | "unknown" | "error">;

package/dist/types/src/index.d.ts

@@ -3,4 +3,6 @@ export { PASS_HEADER, passMessage, encodePass, decodePass, makePass } from "../s
 export type { Approval, Limits, Net, PaymentStatus, SpendEntry, SwapQuote, Token, WafermapOptions } from "./core.js";
 export { x402fetch, readQuote, choose, signPayment, signTokenPayment, wafermapPriceUsd, PAY_CHAINS, MAX_VALIDITY_SECONDS, WAFERMAP_RELAYERS, WAFERMAP_TOKEN, PERMIT2, X402Error } from "../shared/x402client";
 export { quoteSwap, executeSwap, decodeSwap, KYBER_ROUTER, SwapError } from "../shared/swap";
-export type { Requirement, Quote, Signed, SignedAuth, Signer } from "../shared/x402client";
+export type { Requirement, Quote, Signed, SignedAuth, SignedSol, Signer } from "../shared/x402client";
+export { checkSolanaPayment, SOLANA_PUBLIC_RPC } from "../shared/solana";
+export type { SolanaCheck } from "../shared/solana";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wafermapxyz/cli",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "description": "Wafermap for agents: an encrypted local wallet that pays x402 resources, discovers and pays third-party x402 services (USDG on Robinhood Chain; USDC on Solana, Base, Arbitrum, Polygon), and swaps on Robinhood Chain and Base. CLI, SDK and MCP server.",
   "type": "module",
   "bin": {