@metalntwx/metal-pay 0.2.0 → 0.3.1

package/dist/mandates/verify.js

@@ -8,14 +8,14 @@
 // changes, so what it is now it was when it bound and paid. What a verifier
 // cannot rebuild (the budget's running total, the nonce's single use) is read
 // as the contract recorded it in the event and checked against the limits.
-import { decodeFunctionData, formatLog, getAbiItem, hexToBigInt, isAddressEqual, numberToHex, parseAbi, erc20Abi, parseEventLogs, slice, toFunctionSelector, } from "viem";
+import { decodeFunctionData, formatLog, getAbiItem, getAddress, hexToBigInt, isAddressEqual, numberToHex, erc20Abi, parseAbi, parseEventLogs, slice, toEventSelector, toFunctionSelector, } from "viem";
 import { REASONS, REFUSALS, decodeAgentKey, encodeAgentKey, mandateBindingAbi, mandateReference, reasonName, sameAgentKey, } from "./binding.js";
 import { accountFactoryFor, metalNetwork } from "../networks.js";
 import { assertMetalAccount, metalAccountCode, metalAccountFactoryAbi } from "./account.js";
 import { publicMessage } from "./chain.js";
-import { verifyCheckoutMandate, x402Offer, lineItemOf } from "./checkout.js";
+import { checkoutHash, readL3b, verifyCheckoutMandate, x402Offer, lineItemOf } from "./checkout.js";
 import { jcs } from "./jcs.js";
-import { buildL3a, decodeMandateBlob, mandateNonce, serializeL3a, transactionIdOf, verifyL3aSignature } from "./l3a.js";
+import { buildL3a, mandateNonce, serializeL3a, transactionIdOf, verifyL3aSignature } from "./l3a.js";
 import { extractTerms, hashCredential, issuerKeyId, verifyCredential } from "./vi/credential.js";
 function before(a, b) {
     return a.block < b.block || (a.block === b.block && (a.transactionIndex < b.transactionIndex || (a.transactionIndex === b.transactionIndex && a.logIndex < b.logIndex)));
@@ -26,17 +26,11 @@ function position(log) {
     return { block: log.blockNumber, transactionIndex: log.transactionIndex, logIndex: log.logIndex };
 }
 export const STEP_TITLES = {
-    1: "The mandate is bound on the principal's account: hash(C), the limits, the payees, the agent key and the issuer key are on chain",
-    2: "The credential in hand hashes to the bound hash(C) and states the bound limits, payees and agent key",
+    1: "The mandate is bound on the principal's account: hash(C), the limits, the payees, the mandate key and the issuer key are on chain",
+    2: "The credential in hand hashes to the bound hash(C) and states the bound limits, payees and mandate key",
     3: "The credential's signatures: the issuer's under a trusted key that is the one recorded at binding, the owner's under the key the issuer bound",
-    4: "Each payment and refusal is the agent key's per-payment mandate, rebuilt from its transaction, inside the mandate at its block",
+    4: "Each payment and refusal is the mandate key's per-payment mandate, rebuilt from its transaction, inside the mandate at its block",
 };
-const erc3009Abi = parseAbi([
-    "function transferWithAuthorization(address from, address to, uint256 value, uint256 validAfter, uint256 validBefore, bytes32 nonce, bytes signature)",
-    "function transferWithAuthorizationWithPolicy(address from, address to, uint256 value, uint256 validAfter, uint256 validBefore, bytes32 nonce, bytes signature, bytes policyData)",
-    "function receiveWithAuthorization(address from, address to, uint256 value, uint256 validAfter, uint256 validBefore, bytes32 nonce, bytes signature)",
-    "function receiveWithAuthorizationWithPolicy(address from, address to, uint256 value, uint256 validAfter, uint256 validBefore, bytes32 nonce, bytes signature, bytes policyData)",
-]);
 const short = (hex) => `${hex.slice(0, 10)}…`;
 /** A reason as the facilitator names it to a payer. */
 const named = (reason) => (reason === "None" ? "none" : REFUSALS[reason].reason);
@@ -77,45 +71,30 @@ function reasonContradiction(reason, pull, m, at) {
         return `it breaks the mandate: ${named(first)}`;
     return REASONS.indexOf(first) < REASONS.indexOf(reason) ? `${named(first)} holds, and Mandate Binding checks it before ${named(reason)}` : undefined;
 }
-/** The selectors a payment's calldata carries: `pull` on the principal, or an ERC-3009 authorisation on the token. */
+/** The selector a payment's calldata carries: `pull` on the principal, whoever submitted it. */
 const PULL_SELECTOR = toFunctionSelector(getAbiItem({ abi: mandateBindingAbi, name: "pull" }));
-const ERC3009_SELECTORS = erc3009Abi.map((item) => toFunctionSelector(item));
 /**
- * Every pull of the principal's and every ERC-3009 authorisation from it that
- * `input` carries: at the top level, or inside whatever wrapped the call (a
- * multicall, a sponsor's batch, the quorum's own execute). Each selector in
- * the calldata is tried as a call's start; the one the event's digest names
- * is the payment's, and a forged candidate rebuilds to another digest.
+ * Every pull that `input` carries: at the top level, or inside whatever
+ * wrapped the call (a multicall, a sponsor's batch, the quorum's own
+ * execute). Each occurrence of the selector in the calldata is tried as a
+ * call's start; the one the event's digest names is the payment's, and a
+ * forged candidate rebuilds to another digest.
  */
-function carriedL3as(input, m) {
+function carriedL3as(input) {
     const found = [];
     const body = input.slice(2);
-    for (const selector of [PULL_SELECTOR, ...ERC3009_SELECTORS]) {
-        for (let at = body.indexOf(selector.slice(2)); at !== -1; at = body.indexOf(selector.slice(2), at + 2)) {
-            if (at % 2 !== 0)
+    for (let at = body.indexOf(PULL_SELECTOR.slice(2)); at !== -1; at = body.indexOf(PULL_SELECTOR.slice(2), at + 2)) {
+        if (at % 2 !== 0)
+            continue;
+        try {
+            const call = decodeFunctionData({ abi: mandateBindingAbi, data: `0x${body.slice(at)}` });
+            if (call.functionName !== "pull")
                 continue;
-            const data = `0x${body.slice(at)}`;
-            try {
-                if (selector === PULL_SELECTOR) {
-                    const call = decodeFunctionData({ abi: mandateBindingAbi, data });
-                    if (call.functionName !== "pull")
-                        continue;
-                    const [pull, fields] = call.args;
-                    found.push({ pull: { ...pull }, fields: { ...fields }, direct: true });
-                }
-                else {
-                    const [from, payee, value, validAfter, validBefore, nonce, signature] = decodeFunctionData({ abi: erc3009Abi, data }).args;
-                    if (!isAddressEqual(from, m.principal))
-                        continue;
-                    const { pull, fields } = decodeMandateBlob(signature);
-                    const same = isAddressEqual(pull.to, payee) && pull.value === value && pull.validAfter === validAfter && pull.validBefore === validBefore && pull.nonce.toLowerCase() === nonce.toLowerCase();
-                    if (same)
-                        found.push({ pull, fields, direct: false });
-                }
-            }
-            catch {
-                // Not a call that starts here.
-            }
+            const [pull, fields] = call.args;
+            found.push({ pull: { ...pull }, fields: { ...fields } });
+        }
+        catch {
+            // Not a call that starts here.
         }
     }
     return found;
@@ -124,11 +103,10 @@ function carriedL3as(input, m) {
  * The candidate that is the outcome the event records: it rebuilds to the
  * recorded digest, moves the mandate's token, and its nonce commits to the
  * mandate and that digest (the L3a hashes neither the token nor the nonce,
- * so a copy with either changed is not it); among those, one carried the way
- * the event says (a pull, or a relayed authorisation) and signed by the agent
- * key comes first, so unrelated calldata with the same L3a (a no-op pull to
- * another address, a copy under another signature) cannot stand in for the
- * payment. One another mandate's terms cannot rebuild is not a candidate.
+ * so a copy with either changed is not it); among those, one signed by the
+ * agent key comes first, so unrelated calldata with the same L3a (a copy
+ * under another signature) cannot stand in for the payment. One another
+ * mandate's terms cannot rebuild is not a candidate.
  */
 function carriedL3a(input, chainId, m, o) {
     const rank = (c) => {
@@ -138,13 +116,13 @@ function carriedL3a(input, chainId, m, o) {
                 return 0;
             if (!isAddressEqual(c.pull.token, m.constraints.token) || mandateNonce(m.ref, l3a.digest) !== c.pull.nonce.toLowerCase())
                 return 0;
-            return 1 + (c.direct === o.direct ? 2 : 0) + (verifyL3aSignature(m.agentKey, l3a.digest, c.fields.r, c.fields.s) ? 1 : 0);
+            return 1 + (verifyL3aSignature(m.agentKey, l3a.digest, c.fields.r, c.fields.s) ? 1 : 0);
         }
         catch {
             return 0;
         }
     };
-    const candidates = carriedL3as(input, m);
+    const candidates = carriedL3as(input);
     let carried;
     let best = 0;
     for (const c of candidates) {
@@ -153,9 +131,53 @@ function carriedL3a(input, chainId, m, o) {
             [carried, best] = [c, r];
     }
     if (carried === undefined)
-        throw new Error(candidates.length === 0 ? "the transaction carries no pull on the principal and no ERC-3009 authorisation from it" : "no call the transaction carries rebuilds to the per-payment mandate the event records");
+        throw new Error(candidates.length === 0 ? "the transaction carries no pull on the principal" : "no pull the transaction carries rebuilds to the per-payment mandate the event records");
     return carried;
 }
+const MANDATE_EVENTS = new Set(mandateBindingAbi.filter((item) => item.type === "event").map((item) => toEventSelector(item)));
+/** The events a MetalAccount emits besides Mandate Binding's: its quorum, scheduling, sessions and OpenZeppelin bases. */
+const ACCOUNT_EVENTS = new Set([
+    ...MANDATE_EVENTS,
+    ...parseAbi([
+        "event EIP712DomainChanged()",
+        "event ERC7579TryExecuteFail(uint256 batchExecutionIndex, bytes returndata)",
+        "event ERC7913SignerAdded(bytes indexed signers)",
+        "event ERC7913SignerRemoved(bytes indexed signers)",
+        "event ERC7913SignerWeightChanged(bytes indexed signer, uint64 weight)",
+        "event ERC7913ThresholdSet(uint64 threshold)",
+        "event Executed(uint256 indexed nonce)",
+        "event Initialized(uint64 version)",
+        "event ScheduleCanceled(bytes32 indexed operationId)",
+        "event ScheduleConfigured(uint64 threshold, uint32 delay)",
+        "event Scheduled(bytes32 indexed operationId, uint256 indexed nonce, bytes32 mode, bytes executionData, uint48 readyAt)",
+        "event ScheduledExecuted(bytes32 indexed operationId)",
+        "event SessionGranted(address indexed agent, address indexed token, uint64 expiresAt, uint256 perTransferCap, uint256 periodBudget, uint32 period)",
+        "event SessionRevoked(address indexed agent, address indexed token)",
+        "event SessionTransfer(address indexed agent, address indexed token, address indexed to, uint256 amount)",
+    ]).map((item) => toEventSelector(item)),
+]);
+/** What a verifier that cannot decode an account's events says: a deployed account of another version than the SDK's can emit them. */
+const OTHER_VERSIONS = "the SDK and the deployed account may be different versions";
+/** A log's place in the chain: its transaction and its index there. */
+const placeOf = (log) => `${log.transactionHash}:${log.logIndex}`;
+/**
+ * The account's events under `ref` that Mandate Binding's ABI does not
+ * decode, by topic. Each puts the reference in its first topic, so an
+ * account of another version emits its outcomes there under another topic,
+ * or under the same topic in another layout, and a scan that dropped them
+ * would see a mandate with no payments. Each log is matched to its decoding
+ * by its place.
+ */
+function undecoded(principal, ref, logs, decoded) {
+    const read = new Set(decoded.map(placeOf));
+    const counts = new Map();
+    for (const log of logs.map((raw) => formatLog(raw))) {
+        const topic = log.topics[0];
+        if (topic !== undefined && !read.has(placeOf(log)))
+            counts.set(topic, (counts.get(topic) ?? 0) + 1);
+    }
+    return [...counts].map(([topic, count]) => `the account ${getAddress(principal)} emitted ${count} event${count === 1 ? "" : "s"} under ${short(ref)} that this SDK does not decode, under topic ${topic}; ${OTHER_VERSIONS}`);
+}
 /**
  * The mandate's events on the principal between two blocks, oldest first: one
  * `eth_getLogs` for every event kind, since each puts the reference in its
@@ -165,11 +187,13 @@ function carriedL3a(input, chainId, m, o) {
  */
 async function mandateEvents(client, principal, ref, fromBlock, toBlock) {
     const out = [];
+    const raw = [];
     let span = toBlock - fromBlock + 1n;
     for (let start = fromBlock; start <= toBlock;) {
         const end = start + span - 1n > toBlock ? toBlock : start + span - 1n;
         try {
-            const logs = await client.request({ method: "eth_getLogs", params: [{ address: principal, fromBlock: numberToHex(start), toBlock: numberToHex(end), topics: [null, ref] }] });
+            const logs = (await client.request({ method: "eth_getLogs", params: [{ address: principal, fromBlock: numberToHex(start), toBlock: numberToHex(end), topics: [null, ref] }] }));
+            raw.push(...logs);
             out.push(...parseEventLogs({ abi: mandateBindingAbi, logs: logs.map((log) => formatLog(log)), strict: true }));
             start = end + 1n;
         }
@@ -179,7 +203,7 @@ async function mandateEvents(client, principal, ref, fromBlock, toBlock) {
             span /= 2n;
         }
     }
-    return out;
+    return { events: out, unknown: undecoded(principal, ref, raw, out) };
 }
 /**
  * The mandate `ref` as the principal's account bound it: its state names the
@@ -189,26 +213,26 @@ async function mandateEvents(client, principal, ref, fromBlock, toBlock) {
 async function boundMandate(client, principal, ref, factory, toBlock) {
     const state = await client.readContract({ address: principal, abi: mandateBindingAbi, functionName: "mandates", args: [ref] });
     if (!isAddressEqual(state.principal, principal))
-        return { events: [], problems: [`no mandate ${short(ref)} is bound on ${principal}`] };
+        return { events: [], unknown: [], problems: [`no mandate ${short(ref)} is bound on ${principal}`] };
     const from = state.boundBlock;
     const to = toBlock ?? (await client.getBlockNumber());
-    const events = await mandateEvents(client, principal, ref, from, to);
+    const { events, unknown } = await mandateEvents(client, principal, ref, from, to);
     const bound = events.filter((e) => e.eventName === "MandateBound");
     if (bound.length !== 1)
-        return { events, problems: [bound.length === 0 ? `no MandateBound for ${short(ref)} on ${principal} in block ${from}, where its state says it was bound` : `${bound.length} MandateBound events for ${short(ref)}`] };
+        return { events, unknown, problems: [bound.length === 0 ? `no MandateBound for ${short(ref)} on ${principal} in block ${from}, where its state says it was bound` : `${bound.length} MandateBound events for ${short(ref)}`] };
     const [log] = bound;
     if (log === undefined || log.eventName !== "MandateBound" || log.blockNumber === null || log.transactionHash === null)
-        return { events, problems: ["the MandateBound event is pending"] };
+        return { events, unknown, problems: ["the MandateBound event is pending"] };
     try {
         await assertMetalAccount(client, principal, factory);
     }
     catch (error) {
-        return { events, problems: [message(error)] };
+        return { events, unknown, problems: [message(error)] };
     }
     const agentKey = decodeAgentKey(log.args.agentKey);
     const problems = [];
     if (mandateReference(principal, agentKey, log.args.hashC).toLowerCase() !== ref.toLowerCase())
-        problems.push("the reference does not derive from the principal, the agent key and hash(C)");
+        problems.push("the reference does not derive from the principal, the mandate key and hash(C)");
     const revoked = events.find((e) => e.eventName === "MandateRevoked");
     const replaced = events.find((e) => e.eventName === "MandateReplaced");
     const revokedBlock = revoked?.blockNumber ?? undefined;
@@ -228,6 +252,7 @@ async function boundMandate(client, principal, ref, factory, toBlock) {
             ...(successor === undefined ? {} : { successor }),
         },
         events,
+        unknown,
         problems,
     };
 }
@@ -238,28 +263,26 @@ function outcomesOf(events, only) {
         if (log.blockNumber === null || log.transactionHash === null)
             continue;
         if (log.eventName === "MandatePayment") {
-            const { to, amount, l3aDigest, agentKey, direct, spent, occurrences } = log.args;
-            outcomes.push({ ...position(log), kind: "payment", txHash: log.transactionHash, block: log.blockNumber, to, amount, l3aDigest, agentKey, direct, spent, occurrences });
+            const { to, amount, l3aDigest, agentKey, spent, occurrences } = log.args;
+            outcomes.push({ ...position(log), kind: "payment", txHash: log.transactionHash, block: log.blockNumber, to, amount, l3aDigest, agentKey, spent, occurrences });
         }
         else if (log.eventName === "MandateRefused") {
             const { to, amount, l3aDigest, agentKey, reason } = log.args;
-            outcomes.push({ ...position(log), kind: "refusal", txHash: log.transactionHash, block: log.blockNumber, to, amount, l3aDigest, agentKey, direct: true, reason: reasonName(reason) });
+            outcomes.push({ ...position(log), kind: "refusal", txHash: log.transactionHash, block: log.blockNumber, to, amount, l3aDigest, agentKey, reason: reasonName(reason) });
         }
     }
     outcomes.sort((a, b) => before(a, b) ? -1 : before(b, a) ? 1 : 0);
     return only === undefined ? outcomes : outcomes.filter((o) => o.txHash.toLowerCase() === only.toLowerCase());
 }
 async function verifyOutcome(client, chainId, m, o, one) {
-    const verified = { kind: o.kind, txHash: o.txHash, block: o.block, direct: o.direct, to: o.to, amount: o.amount, ...(o.reason === undefined ? {} : { reason: o.reason }), problems: [] };
+    const verified = { kind: o.kind, txHash: o.txHash, block: o.block, to: o.to, amount: o.amount, ...(o.reason === undefined ? {} : { reason: o.reason }), problems: [] };
     const found = verified.problems;
     const agentKey = decodeAgentKey(o.agentKey);
     if (!sameAgentKey(agentKey, m.agentKey))
-        found.push("not the bound agent key");
+        found.push("not the bound mandate key");
     try {
         const [tx, block] = await Promise.all([client.getTransaction({ hash: o.txHash }), client.getBlock({ blockNumber: o.block })]);
-        const { pull, fields, direct } = carriedL3a(tx.input, chainId, m, o);
-        if (direct !== o.direct)
-            found.push(direct ? "recorded as relayed, carried as a pull" : "recorded as a pull, carried as a relayed authorisation");
+        const { pull, fields } = carriedL3a(tx.input, chainId, m, o);
         if (!isAddressEqual(pull.token, m.constraints.token))
             found.push("another token than the mandate's");
         const receipt = await client.getTransactionReceipt({ hash: o.txHash });
@@ -278,12 +301,17 @@ async function verifyOutcome(client, chainId, m, o, one) {
         if (mandateNonce(m.ref, l3a.digest) !== pull.nonce.toLowerCase())
             found.push("its nonce does not commit to the mandate and the per-payment mandate");
         if (!verifyL3aSignature(m.agentKey, l3a.digest, fields.r, fields.s))
-            found.push("not the bound agent key's signature");
+            found.push("not the bound mandate key's signature");
         if (!isAddressEqual(pull.to, o.to))
             found.push("another payee than the event records");
         if (pull.value !== o.amount)
             found.push("another amount than the event records");
-        if (one.checkoutMandate !== undefined) {
+        const other = one.checkoutMandate === undefined ? undefined : othersOrder(one.checkoutMandate, fields.transactionId, pull);
+        if (other !== undefined) {
+            // Its other checks would only list how that other payment differs.
+            found.push(`the checkout mandate belongs to another payment: ${other}`);
+        }
+        else if (one.checkoutMandate !== undefined) {
             // The offer served, when the verifier served it; the signed order's own otherwise.
             const offer = one.requirements !== null && typeof one.requirements === "object" && !Array.isArray(one.requirements) ? x402Offer(one.requirements) : undefined;
             found.push(...verifyCheckoutMandate(one.checkoutMandate, {
@@ -329,19 +357,40 @@ async function verifyOutcome(client, chainId, m, o, one) {
     }
     return verified;
 }
+/**
+ * How a checkout mandate that parses is another payment's: a checkout hash
+ * other than the per-payment mandate's `transaction_id`, or another window,
+ * as both are signed together for one payment. Undefined when it is this
+ * payment's, or does not parse, which its own check names.
+ */
+function othersOrder(checkoutMandate, transactionId, pull) {
+    try {
+        const l3b = readL3b(checkoutMandate);
+        if (!Number.isSafeInteger(l3b.iat) || !Number.isSafeInteger(l3b.exp))
+            return undefined;
+        const differs = [
+            ...(checkoutHash(l3b.checkoutJwt) === transactionId.toLowerCase() ? [] : ["its checkout hash is not the transaction_id this payment's per-payment mandate signed"]),
+            ...(BigInt(l3b.iat) === pull.validAfter && BigInt(l3b.exp) === pull.validBefore ? [] : ["its window is not this payment's"]),
+        ];
+        return differs.length === 0 ? undefined : differs.join(", and ");
+    }
+    catch {
+        return undefined;
+    }
+}
 async function verify(client, found, opts, only) {
     const steps = [];
     const record = (step, problems, passed) => steps.push({ step, title: STEP_TITLES[step], outcome: problems.length > 0 ? "fail" : "pass", detail: problems.length > 0 ? problems.join("; ") : passed });
     const skip = (step, why) => steps.push({ step, title: STEP_TITLES[step], outcome: "skipped", detail: why });
     const m = found.mandate;
     if (m === undefined) {
-        record(1, found.problems, "");
+        record(1, [...found.problems, ...found.unknown], "");
         skip(2, "no binding to check against");
         skip(3, "no binding to check against");
         skip(4, "no binding to check against");
         return { ok: false, steps, payments: [] };
     }
-    record(1, found.problems, `${short(m.ref)} bound in block ${m.block} by ${m.principal}: hash(C) ${m.hashC}, issuer key ${m.issuerKey}, agent key ${short(encodeAgentKey(m.agentKey))}, ${m.terms.payees.length} payee(s)` +
+    record(1, found.problems, `${short(m.ref)} bound in block ${m.block} by ${m.principal}: hash(C) ${m.hashC}, issuer key ${m.issuerKey}, mandate key ${short(encodeAgentKey(m.agentKey))}, ${m.terms.payees.length} payee(s)` +
         `${m.revokedBlock === undefined ? "" : `, revoked in block ${m.revokedBlock}`}${m.successor === undefined ? "" : `, replaced by ${short(m.successor)}`}`);
     const c = opts.credential;
     let credentialIsBound = false;
@@ -357,7 +406,7 @@ async function verify(client, found, opts, only) {
                 const stated = extractTerms(c);
                 const differs = [
                     ["principal", isAddressEqual(stated.principal, m.principal)],
-                    ["agent key", sameAgentKey(stated.agentKey, m.agentKey)],
+                    ["mandate key", sameAgentKey(stated.agentKey, m.agentKey)],
                     ["limits", jcs(toJson(stated.constraints)) === jcs(toJson(m.constraints))],
                     ["payees", jcs(toJson(stated.terms)) === jcs(toJson(m.terms))],
                 ].filter(([, same]) => !same);
@@ -369,7 +418,7 @@ async function verify(client, found, opts, only) {
             }
         }
         credentialIsBound = problems.length === 0;
-        record(2, problems, "the credential hashes to the bound hash(C), and binds exactly the limits, payees and agent key it states");
+        record(2, problems, "the credential hashes to the bound hash(C), and binds exactly the limits, payees and mandate key it states");
     }
     if (c === undefined || !credentialIsBound)
         skip(3, c === undefined ? "no credential in hand" : "the credential in hand is not the bound one");
@@ -395,13 +444,15 @@ async function verify(client, found, opts, only) {
     const one = outcomes.length === 1 ? { ...opts, ...(checkoutSdHash === undefined ? {} : { checkoutSdHash }) } : {};
     for (const o of outcomes)
         payments.push(await verifyOutcome(client, chainId, m, o, one));
-    const problems = payments.filter((p) => p.problems.length > 0).map((p) => `${p.kind} in ${short(p.txHash)}: ${p.problems.join(", ")}`);
+    const problems = [...found.unknown, ...payments.filter((p) => p.problems.length > 0).map((p) => `${p.kind} in ${short(p.txHash)}: ${p.problems.join(", ")}`)];
     if (only !== undefined && outcomes.length === 0)
         problems.push(`transaction ${only.tx} carries no payment or refusal under ${short(m.ref)}`);
     if ((opts.requirements !== undefined || opts.checkoutMandate !== undefined) && outcomes.length > 1)
         problems.push("requirements or a signed offer given, but more than one payment to check them against");
     const paid = payments.filter((p) => p.kind === "payment").length;
-    record(4, problems, `${paid} payment(s) and ${payments.length - paid} refusal(s), each the bound agent key's per-payment mandate rebuilt byte for byte from its transaction, inside the mandate at its block`);
+    // One payment's check says whether it covered the signed order.
+    const order = only === undefined ? "" : opts.checkoutMandate === undefined ? "; no checkout mandate was given, so the order was not checked" : "; the checkout mandate is this payment's signed order";
+    record(4, problems, `${paid} payment(s) and ${payments.length - paid} refusal(s), each the bound mandate key's per-payment mandate rebuilt byte for byte from its transaction, inside the mandate at its block${order}`);
     return { ok: steps.every((s) => s.outcome !== "fail"), steps, mandate: m, payments };
 }
 /** The factory the verifier trusts on `client`'s chain: the caller's, else the one the network table names. */
@@ -442,12 +493,26 @@ export async function verifyMandatePayment(client, opts) {
     // passes on part of a transaction's outcomes.
     const clone = metalAccountCode(await client.readContract({ address: accountFactory, abi: metalAccountFactoryAbi, functionName: "implementation" }));
     const emitters = new Map();
-    for (const address of new Set(logs.map((log) => log.address.toLowerCase()))) {
-        emitters.set(address, (await client.getCode({ address }))?.toLowerCase() === clone);
-    }
+    const trusted = async (address) => {
+        if (!emitters.has(address))
+            emitters.set(address, (await client.getCode({ address: address }))?.toLowerCase() === clone);
+        return emitters.get(address) === true;
+    };
+    for (const address of new Set(logs.map((log) => log.address.toLowerCase())))
+        await trusted(address);
     const carried = logs.filter((log) => emitters.get(log.address.toLowerCase()) === true);
-    if (carried.length === 0)
-        throw new Error(logs.length === 0 ? `transaction ${opts.tx} carries no payment or refusal under a mandate` : `transaction ${opts.tx} carries mandate outcomes only from ${[...emitters.keys()].join(", ")}, no account of the trusted factory ${accountFactory}`);
+    if (carried.length === 0) {
+        // An account of another version than the SDK's emits its outcomes under
+        // topics the ABI does not decode, or under its topics in another layout.
+        const read = new Set(parseEventLogs({ abi: mandateBindingAbi, logs: receipt.logs, strict: true }).map(placeOf));
+        for (const log of receipt.logs) {
+            const topic = log.topics[0]?.toLowerCase();
+            if (topic === undefined || (MANDATE_EVENTS.has(topic) ? read.has(placeOf(log)) : ACCOUNT_EVENTS.has(topic)) || !(await trusted(log.address.toLowerCase())))
+                continue;
+            throw new Error(`transaction ${opts.tx} carries no payment or refusal this SDK decodes: the account ${getAddress(log.address)} emitted an event under topic ${topic}, which this SDK does not decode; ${OTHER_VERSIONS}`);
+        }
+        throw new Error(logs.length === 0 ? `transaction ${opts.tx} carries no payment or refusal under a mandate` : `transaction ${opts.tx} carries mandate outcomes only from ${[...new Set(logs.map((log) => log.address.toLowerCase()))].join(", ")}, no account of the trusted factory ${accountFactory}`);
+    }
     // One transaction may settle payments under several mandates (a sponsor's
     // batch). `ref` or the credential in hand names the one to verify; a
     // credential that names none of them is still checked against a single

package/dist/mandates/vi/credential.js

@@ -273,13 +273,13 @@ function resolveTerms({ l1, l2 }, c) {
     const paymentJwk = obj(obj(paymentMandate.cnf, "payment cnf").jwk, "payment cnf.jwk");
     const agentJwk = { ...p256Jwk(paymentJwk, "payment cnf.jwk", "MalformedMandate"), kid: str(paymentJwk, "kid") };
     if (agentJwk.kid !== jwkThumbprint(agentJwk))
-        fail("MalformedMandate", "the agent key's kid is not its RFC 7638 thumbprint");
+        fail("MalformedMandate", "the mandate key's kid is not its RFC 7638 thumbprint");
     if (jcs(checkoutJwk) !== jcs(paymentJwk))
-        fail("MalformedMandate", "the checkout and payment mandates name different agent keys");
+        fail("MalformedMandate", "the checkout and payment mandates name different mandate keys");
     if (l2.payload.aud !== agentJwk.kid)
-        fail("MalformedMandate", "layer2 aud is not the agent key's kid");
+        fail("MalformedMandate", "layer2 aud is not the mandate key's kid");
     if (/["\\]|[^\x20-\x7e]/.test(agentJwk.kid))
-        fail("MalformedMandate", "the agent key's kid is not printable ASCII");
+        fail("MalformedMandate", "the mandate key's kid is not printable ASCII");
     const instrumentObject = obj(paymentMandate.payment_instrument, "payment_instrument");
     if (instrumentObject.type !== INSTRUMENT_TYPE)
         fail("MalformedMandate", `payment_instrument.type must be ${INSTRUMENT_TYPE}`);

package/dist/networks.d.ts

@@ -1,5 +1,5 @@
 import type { Network } from "@x402/core/types";
-import type { Address } from "viem";
+import { type Address, type HttpTransport } from "viem";
 export type MetalNetworkName = "devnet" | "testnet";
 export interface MetalNetwork {
     name: MetalNetworkName;
@@ -55,6 +55,14 @@ export declare function resolveNetwork(entry: MetalNetworkName | MetalNetwork):
  * METAL_RPC_URL"), how the caller passes it.
  */
 export declare function rpcUrlFor(network: MetalNetwork, override: string | undefined, how: string): string;
+/**
+ * viem's `http` transport to `rpcUrl`, whose errors do not carry the URL: it
+ * can hold the endpoint's credential, so each error it throws, and each of
+ * that error's causes, names it as `[RPC URL hidden]`. An endpoint that
+ * gives no answer, or a server error, is named as one that could not be
+ * reached.
+ */
+export declare function rpcTransport(rpcUrl: string): HttpTransport;
 /** A dollar token payers authorize ERC-3009 transfers of. */
 export interface DollarToken {
     address: `0x${string}`;

package/dist/networks.js

@@ -1,3 +1,4 @@
+import { HttpRequestError, TimeoutError, http } from "viem";
 /**
  * The MetalAccountFactory to trust on `network`: `override` when given, else
  * the network's own. On a network with neither it throws, saying how the
@@ -32,7 +33,7 @@ export const METAL_NETWORKS = {
         facilitatorUrl: "https://x402-testnet.metalntwx.com/x402/facilitator",
         // What `just estate-deploy-account-factory testnet` recorded in
         // deploy/estate/environments/testnet/account-factory.json for this chain.
-        accountFactory: "0x4D188AC7815a9EAEa219a49D687B71898A487578",
+        accountFactory: "0xcEc6e13AC50078AE3f1e163d5fbd257DAcED8023",
     },
 };
 /** Resolve a name or a CAIP-2 identifier to a Metal network; undefined for any other chain. */
@@ -61,6 +62,105 @@ export function rpcUrlFor(network, override, how) {
         return network.rpc.url;
     throw new Error(`${network.name} needs an RPC endpoint of your own: sign up at ${network.rpc.consoleUrl}, create an endpoint, then ${how}`);
 }
+/** What an RPC URL reads as in an error. */
+const HIDDEN_RPC_URL = "[RPC URL hidden]";
+/**
+ * viem's `http` transport to `rpcUrl`, whose errors do not carry the URL: it
+ * can hold the endpoint's credential, so each error it throws, and each of
+ * that error's causes, names it as `[RPC URL hidden]`. An endpoint that
+ * gives no answer, or a server error, is named as one that could not be
+ * reached.
+ */
+export function rpcTransport(rpcUrl) {
+    const transport = http(rpcUrl);
+    const parsed = URL.canParse(rpcUrl) ? new URL(rpcUrl) : undefined;
+    const host = parsed?.host;
+    // What an endpoint can echo of the URL without its host: the path and
+    // query, which can hold a key, and the user and password.
+    const decoded = (text) => {
+        try {
+            return decodeURIComponent(text);
+        }
+        catch {
+            return text;
+        }
+    };
+    const path = parsed ? parsed.pathname + parsed.search : "";
+    const secrets = [rpcUrl];
+    if (path.length > 1)
+        secrets.push(path);
+    // A key is often echoed alone: each path segment and query value long enough to be one.
+    if (parsed) {
+        const parts = [...decoded(parsed.pathname).split("/"), ...[...parsed.searchParams.values()]];
+        for (const part of parts)
+            if (part.length >= 8)
+                secrets.push(part);
+    }
+    if (parsed?.username || parsed?.password) {
+        const [user, password] = [decoded(parsed.username), decoded(parsed.password)];
+        secrets.push(`${user}:${password}`);
+        if (password.length >= 4)
+            secrets.push(password);
+    }
+    // viem prints the URL as given, or without its user and password.
+    const hide = (text) => secrets
+        .reduce((hidden, secret) => hidden.replaceAll(secret, HIDDEN_RPC_URL), text)
+        .replace(/https?:\/\/[^\s"'<>]+/g, (url) => (URL.canParse(url) && new URL(url).host === host ? HIDDEN_RPC_URL : url));
+    // Every string the error holds, in its fields, its causes, its arrays and
+    // its response headers, as viem or the endpoint put it there: the fields
+    // that name the URL are not a list to keep.
+    const scrub = (value, seen) => {
+        if (value === null || typeof value !== "object" || seen.has(value))
+            return;
+        seen.add(value);
+        for (const key of Object.getOwnPropertyNames(value)) {
+            const fields = value;
+            let field;
+            try {
+                field = fields[key];
+            }
+            catch {
+                continue;
+            }
+            let hidden = field;
+            if (typeof field === "string")
+                hidden = hide(field);
+            else if (field instanceof Headers) {
+                const entries = [...field].map(([name, text]) => [name, hide(text)]);
+                if (entries.some(([name, text]) => field.get(name) !== text))
+                    hidden = new Headers(entries);
+            }
+            else
+                scrub(field, seen);
+            if (hidden !== field)
+                try {
+                    fields[key] = hidden;
+                }
+                catch {
+                    // A property that cannot be written holds what it held.
+                }
+        }
+    };
+    return ((options) => {
+        const made = transport(options);
+        return {
+            ...made,
+            request: (async (args, requestOptions) => {
+                try {
+                    return await made.request(args, requestOptions);
+                }
+                catch (error) {
+                    if (error instanceof TimeoutError || (error instanceof HttpRequestError && (error.status === undefined || error.status >= 500))) {
+                        error.shortMessage = `the RPC endpoint could not be reached: ${error.shortMessage}`;
+                        error.message = `the RPC endpoint could not be reached: ${error.message}`;
+                    }
+                    scrub(error, new Set());
+                    throw error;
+                }
+            }),
+        };
+    });
+}
 /** The default gas token and the asset every offer here is priced in. */
 export const USDZ = {
     address: "0x000000000000000000000000000000000000B5d5",
@@ -95,8 +195,9 @@ export function usdzBaseUnits(amount) {
 /** Format base units back to a decimal `*USDZ` string for humans, trailing zeros trimmed. */
 export function formatUsdz(amount) {
     const units = BigInt(amount);
+    const magnitude = units < 0n ? -units : units;
     const scale = 10n ** BigInt(USDZ.decimals);
-    const whole = units / scale;
-    const fraction = (units % scale).toString().padStart(USDZ.decimals, "0").replace(/0+$/, "");
-    return fraction ? `${whole}.${fraction}` : whole.toString();
+    const whole = magnitude / scale;
+    const fraction = (magnitude % scale).toString().padStart(USDZ.decimals, "0").replace(/0+$/, "");
+    return `${units < 0n ? "-" : ""}${fraction ? `${whole}.${fraction}` : whole}`;
 }

package/dist/node.d.ts

@@ -0,0 +1,11 @@
+import type { ClearingClientStore } from "./clearing-client.js";
+import type { Hex } from "viem";
+/** A persistent P-256 account and receipt journal for a single server process. */
+export declare function openClearingWallet(directory: string): Promise<{
+    signer: {
+        publicKey: `0x${string}`;
+        sign(namespace: string, message: Hex): Hex;
+    };
+    store: ClearingClientStore;
+    close(): Promise<void>;
+}>;