@metalntwx/metal-pay 0.3.0 → 0.3.2

package/dist/mandates/verify.js

@@ -8,12 +8,12 @@
 // 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, 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, mandateNonce, serializeL3a, transactionIdOf, verifyL3aSignature } from "./l3a.js";
 import { extractTerms, hashCredential, issuerKeyId, verifyCredential } from "./vi/credential.js";
@@ -134,6 +134,50 @@ function carriedL3a(input, chainId, m, o) {
         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
@@ -143,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;
         }
@@ -157,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
@@ -167,21 +213,21 @@ 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 = [];
@@ -206,6 +252,7 @@ async function boundMandate(client, principal, ref, factory, toBlock) {
             ...(successor === undefined ? {} : { successor }),
         },
         events,
+        unknown,
         problems,
     };
 }
@@ -259,7 +306,12 @@ async function verifyOutcome(client, chainId, m, o, one) {
             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, {
@@ -305,13 +357,34 @@ 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");
@@ -371,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 mandate 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. */
@@ -418,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/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: "0x3dbED5DebA965A639bB0Fd40BE96b97922070FA8",
     },
 };
 /** 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metalntwx/metal-pay",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Agent payments on Metal for the official x402 packages: native Bajillion clearing, on-chain exact payments, durable payer wallets, seller integration, and mandates, which let an agent pay from its owner's account within limits Metal enforces.",
   "license": "MIT",
   "repository": {