@metalntwx/metal-pay 0.3.0 → 0.3.2

package/src/mandates/verify.ts

@@ -19,12 +19,15 @@ import {
   decodeFunctionData,
   formatLog,
   getAbiItem,
+  getAddress,
   hexToBigInt,
   isAddressEqual,
   numberToHex,
   erc20Abi,
+  parseAbi,
   parseEventLogs,
   slice,
+  toEventSelector,
   toFunctionSelector,
 } from "viem";
 import {
@@ -46,7 +49,7 @@ import {
 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 { type Json, jcs } from "./jcs.js";
 import { buildL3a, mandateNonce, serializeL3a, transactionIdOf, verifyL3aSignature } from "./l3a.js";
 import { type Credential, type TrustedIssuer, extractTerms, hashCredential, issuerKeyId, verifyCredential } from "./vi/credential.js";
@@ -230,6 +233,54 @@ function carriedL3a(input: Hex, chainId: number, m: BoundMandate, o: Pick<Outcom
 
 type MandateEvent = ParseEventLogsReturnType<typeof mandateBindingAbi, undefined, true>[number];
 
+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: { transactionHash: Hash | null; logIndex: number | null }): string => `${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: Address, ref: Hex, logs: readonly RpcLog[], decoded: readonly MandateEvent[]): string[] {
+  const read = new Set(decoded.map(placeOf));
+  const counts = new Map<Hex, number>();
+  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
@@ -237,21 +288,23 @@ type MandateEvent = ParseEventLogsReturnType<typeof mandateBindingAbi, undefined
  * rule and in its own words, so a refused range is halved until the node
  * answers; an error that holds for a single block is the node's.
  */
-async function mandateEvents(client: PublicClient, principal: Address, ref: Hex, fromBlock: bigint, toBlock: bigint): Promise<MandateEvent[]> {
+async function mandateEvents(client: PublicClient, principal: Address, ref: Hex, fromBlock: bigint, toBlock: bigint): Promise<{ events: MandateEvent[]; unknown: string[] }> {
   const out: MandateEvent[] = [];
+  const raw: RpcLog[] = [];
   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] }] });
-      out.push(...parseEventLogs({ abi: mandateBindingAbi, logs: (logs as RpcLog[]).map((log) => formatLog(log)), strict: true }));
+      const logs = (await client.request({ method: "eth_getLogs", params: [{ address: principal, fromBlock: numberToHex(start), toBlock: numberToHex(end), topics: [null, ref] }] })) as RpcLog[];
+      raw.push(...logs);
+      out.push(...parseEventLogs({ abi: mandateBindingAbi, logs: logs.map((log) => formatLog(log)), strict: true }));
       start = end + 1n;
     } catch (error) {
       if (span <= 1n) throw error;
       span /= 2n;
     }
   }
-  return out;
+  return { events: out, unknown: undecoded(principal, ref, raw, out) };
 }
 
 /**
@@ -259,18 +312,18 @@ async function mandateEvents(client: PublicClient, principal: Address, ref: Hex,
  * block, so the scan for its events starts there and never at genesis.
  * `toBlock` bounds the scan when only the events up to one block matter.
  */
-async function boundMandate(client: PublicClient, principal: Address, ref: Hex, factory: Address, toBlock?: bigint): Promise<{ mandate?: BoundMandate; events: MandateEvent[]; problems: string[] }> {
+async function boundMandate(client: PublicClient, principal: Address, ref: Hex, factory: Address, toBlock?: bigint): Promise<Found> {
   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}`] };
+  if (!isAddressEqual(state.principal, 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)}`] };
+  if (bound.length !== 1) 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"] };
+  if (log === undefined || log.eventName !== "MandateBound" || log.blockNumber === null || log.transactionHash === null) return { events, unknown, problems: ["the MandateBound event is pending"] };
   try { await assertMetalAccount(client, principal, factory); }
-  catch (error) { return { events, problems: [message(error)] }; }
+  catch (error) { return { events, unknown, problems: [message(error)] }; }
   const agentKey = decodeAgentKey(log.args.agentKey);
   const problems: string[] = [];
   if (mandateReference(principal, agentKey, log.args.hashC).toLowerCase() !== ref.toLowerCase()) problems.push("the reference does not derive from the principal, the mandate key and hash(C)");
@@ -293,6 +346,7 @@ async function boundMandate(client: PublicClient, principal: Address, ref: Hex,
       ...(successor === undefined ? {} : { successor }),
     },
     events,
+    unknown,
     problems,
   };
 }
@@ -350,7 +404,11 @@ async function verifyOutcome(client: PublicClient, chainId: number, m: BoundMand
     if (!verifyL3aSignature(m.agentKey, l3a.digest, fields.r, fields.s)) 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, {
@@ -389,7 +447,28 @@ async function verifyOutcome(client: PublicClient, chainId: number, m: BoundMand
   return verified;
 }
 
-type Found = { mandate?: BoundMandate; events: readonly MandateEvent[]; problems: string[] };
+/**
+ * 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: string, transactionId: Hex, pull: Pull): string | undefined {
+  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 as number) === pull.validAfter && BigInt(l3b.exp as number) === pull.validBefore ? [] : ["its window is not this payment's"]),
+    ];
+    return differs.length === 0 ? undefined : differs.join(", and ");
+  } catch {
+    return undefined;
+  }
+}
+
+/** The mandate's binding and events, with what the binding's checks found and, apart, the events under it that did not decode. */
+type Found = { mandate?: BoundMandate; events: readonly MandateEvent[]; unknown: string[]; problems: string[] };
 
 async function verify(client: PublicClient, found: Found, opts: VerifyMandateOptions & { accountFactory: Address }, only: { tx: Hash; events: readonly MandateEvent[] } | undefined): Promise<MandateVerification> {
   const steps: VerifyStep[] = [];
@@ -399,7 +478,7 @@ async function verify(client: PublicClient, found: Found, opts: VerifyMandateOpt
 
   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");
@@ -457,11 +536,13 @@ async function verify(client: PublicClient, found: Found, opts: VerifyMandateOpt
   const checkoutSdHash = c !== undefined && credentialIsBound ? extractTerms(c).checkoutSdHash : undefined;
   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 };
 }
@@ -505,11 +586,23 @@ export async function verifyMandatePayment(client: PublicClient, opts: VerifyMan
   // passes on part of a transaction's outcomes.
   const clone = metalAccountCode(await client.readContract({ address: accountFactory, abi: metalAccountFactoryAbi, functionName: "implementation" }));
   const emitters = new Map<string, boolean>();
-  for (const address of new Set(logs.map((log) => log.address.toLowerCase() as Address))) {
-    emitters.set(address, (await client.getCode({ address }))?.toLowerCase() === clone);
-  }
+  const trusted = async (address: string): Promise<boolean> => {
+    if (!emitters.has(address)) emitters.set(address, (await client.getCode({ address: address as 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() as Hex | undefined;
+      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/src/networks.test.ts

@@ -1,5 +1,8 @@
-import { describe, expect, it } from "vitest";
-import { METAL_NETWORKS, rpcUrlFor } from "./networks.js";
+import { createServer } from "node:http";
+import { inspect } from "node:util";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { createPublicClient, erc20Abi, http, type HttpTransport } from "viem";
+import { METAL_NETWORKS, rpcTransport, rpcUrlFor } from "./networks.js";
 
 describe("rpcUrlFor", () => {
   it("prefers the override, then the network's default RPC", () => {
@@ -14,3 +17,161 @@ describe("rpcUrlFor", () => {
     );
   });
 });
+
+const PASSWORD_ECHO = "ops:s3cr3t-pass";
+const PASSWORD = "s3cr3t-pass";
+
+describe("rpcTransport", () => {
+  /** An endpoint that fails each request over HTTP, never answers it, or answers it with a JSON-RPC error. */
+  const node = createServer((req, res) => {
+    let body = "";
+    req.on("data", (c) => (body += c));
+    req.on("end", () => {
+      const { id } = JSON.parse(body);
+      if (req.url?.startsWith("/http-error/")) return res.writeHead(502).end("bad gateway");
+      if (req.url?.startsWith("/hang/")) return;
+      res.setHeader("content-type", "application/json");
+      // An endpoint whose error names a different path on its own host than the one requested,
+      // as an Express-style 404 or a proxy's own error page can.
+      // A server error that echoes the request path alone, or a header that names it, or the credentials it was given.
+      if (req.url?.startsWith("/echoes-path-only/"))
+        return res.end(JSON.stringify({ jsonrpc: "2.0", id, error: { code: -32000, message: `Cannot POST ${req.url}` } }));
+      if (req.url?.startsWith("/echoes-header/")) return res.writeHead(502, { "content-type": "text/plain", location: req.url, "x-upstream": req.url }).end("bad gateway");
+      // A provider that names the key alone, a percent-encoded path as it decodes it, or the password alone.
+      if (req.url?.startsWith("/echoes-segment/"))
+        return res.end(JSON.stringify({ jsonrpc: "2.0", id, error: { code: -32000, message: `Unauthorized: invalid project id ${req.url.split("?")[0]!.slice("/echoes-segment/".length)}` } }));
+      if (req.url?.startsWith("/echoes-query/"))
+        return res.end(JSON.stringify({ jsonrpc: "2.0", id, error: { code: -32000, message: `Unauthorized: invalid api key ${new URL(req.url, "http://x").searchParams.get("key")}` } }));
+      if (req.url?.startsWith("/echoes-decoded/"))
+        return res.end(JSON.stringify({ jsonrpc: "2.0", id, error: { code: -32000, message: `Unauthorized: ${decodeURIComponent(req.url.slice("/echoes-decoded/".length))}` } }));
+      if (req.url?.startsWith("/echoes-password/"))
+        return res.end(JSON.stringify({ jsonrpc: "2.0", id, error: { code: -32000, message: `bad password ${PASSWORD}` } }));
+      if (req.url?.startsWith("/echoes-in-data/"))
+        return res.end(JSON.stringify({ jsonrpc: "2.0", id, error: { code: -32000, message: "upstream failed", data: { reason: `Cannot POST ${req.url}`, trace: [`at ${req.url}`] } } }));
+      if (req.url?.startsWith("/echoes-userinfo/"))
+        return res.end(JSON.stringify({ jsonrpc: "2.0", id, error: { code: -32000, message: `bad credentials ${PASSWORD_ECHO}` } }));
+      if (req.url?.startsWith("/echoes-another-path/"))
+        return res.end(JSON.stringify({ jsonrpc: "2.0", id, error: { code: -32000, message: `Cannot POST ${origin}/leaked-key-in-another-path/${req.url.slice("/echoes-another-path/".length)}` } }));
+      res.end(JSON.stringify({ jsonrpc: "2.0", id, error: { code: -32000, message: "header not found" } }));
+    });
+  });
+  let origin: string;
+  beforeAll(async () => {
+    origin = await new Promise<string>((resolve) =>
+      node.listen(0, "127.0.0.1", () => resolve(`http://127.0.0.1:${(node.address() as { port: number }).port}`)),
+    );
+  });
+  afterAll(() => new Promise<void>((resolve) => node.close(() => resolve()) && node.closeAllConnections()));
+  const CREDENTIAL = "k3y-0f-the-endpoint";
+  /** The error, its causes and their fields, as a log prints them. */
+  const printed = (error: unknown) => inspect(error, { depth: Infinity });
+  const failures = (url: string, transport = rpcTransport) => {
+    const client = createPublicClient({ transport: transport(url) });
+    return Promise.all([
+      client.getChainId().catch((e: unknown) => e),
+      client.readContract({ address: `0x${"33".repeat(20)}`, abi: erc20Abi, functionName: "totalSupply" }).catch((e: unknown) => e),
+    ]);
+  };
+
+  it("throws viem's errors without the RPC URL, in them or their causes", async () => {
+    const urls = [`${origin}/http-error/${CREDENTIAL}`, `${origin}/rpc-error/${CREDENTIAL}`, `${origin}/q?key=${CREDENTIAL}`, `http://127.0.0.1:1/${CREDENTIAL}`];
+    for (const url of urls) {
+      for (const error of await failures(url)) {
+        expect(error).toBeInstanceOf(Error);
+        expect(printed(error)).toContain("[RPC URL hidden]");
+        expect(printed(error)).not.toContain(CREDENTIAL);
+        expect(printed(error)).not.toMatch(/https?:\/\/127\.0\.0\.1/);
+      }
+    }
+  });
+
+  it("names an RPC endpoint that gives no answer, or a server error, as unreachable, and one that answers with an RPC error as answering", async () => {
+    // A short timeout and no retries, so a request that hangs fails at once.
+    const quick = (url: string) => ((options) => rpcTransport(url)({ ...options, timeout: 300, retryCount: 0 })) as HttpTransport;
+    for (const url of [`${origin}/hang/${CREDENTIAL}`, `${origin}/http-error/${CREDENTIAL}`, `http://127.0.0.1:1/${CREDENTIAL}`]) {
+      for (const error of await failures(url, quick)) {
+        expect(String(error)).toMatch(/^\w+: the RPC endpoint could not be reached: /);
+        expect(printed(error)).not.toContain(CREDENTIAL);
+      }
+    }
+    for (const error of await failures(`${origin}/rpc-error/${CREDENTIAL}`, quick)) expect(String(error)).not.toMatch(/could not be reached/);
+  });
+
+  it("is the check that fails: viem's own transport prints the URL", async () => {
+    for (const error of await failures(`${origin}/http-error/${CREDENTIAL}`, (url) => http(url))) expect(printed(error)).toContain(CREDENTIAL);
+  });
+
+  /** Every string an error carries, in its fields, its causes and its headers, as a log or a catch block could read them. */
+  const strings = (value: unknown, seen = new Set<unknown>()): string[] => {
+    if (typeof value === "string") return [value];
+    if (value === null || typeof value !== "object" || seen.has(value)) return [];
+    seen.add(value);
+    if (value instanceof Headers) return [...value].flat();
+    const fields = Object.getOwnPropertyNames(value).map((key) => (value as Record<string, unknown>)[key]);
+    return fields.flatMap((field) => strings(field, seen));
+  };
+
+  it("hides the path and query of the RPC URL where the endpoint echoes them without the host", async () => {
+    for (const url of [`${origin}/echoes-path-only/${CREDENTIAL}`, `${origin}/echoes-path-only/v1?key=${CREDENTIAL}`]) {
+      for (const error of await failures(url)) {
+        expect(error).toBeInstanceOf(Error);
+        expect(strings(error).join("\n")).not.toContain(CREDENTIAL);
+      }
+    }
+  });
+
+  it("hides the RPC URL where the endpoint names it in a response header", async () => {
+    for (const error of await failures(`${origin}/echoes-header/${CREDENTIAL}`)) {
+      expect(error).toBeInstanceOf(Error);
+      expect(strings(error).join("\n")).not.toContain(CREDENTIAL);
+    }
+  });
+
+  it("hides the RPC URL wherever the endpoint puts it in its error, nested objects and lists included", async () => {
+    for (const error of await failures(`${origin}/echoes-in-data/${CREDENTIAL}`)) {
+      expect(error).toBeInstanceOf(Error);
+      expect(strings(error).join("\n")).not.toContain(CREDENTIAL);
+    }
+  });
+
+  it("hides a key the endpoint echoes alone: a path segment, a query value, or a percent-encoded segment as it decodes it", async () => {
+    for (const url of [
+      `${origin}/echoes-segment/${CREDENTIAL}`,
+      `${origin}/echoes-segment/v1/${CREDENTIAL}/rpc?x=1`,
+      `${origin}/echoes-query/v1?key=${CREDENTIAL}`,
+      `${origin}/echoes-decoded/${encodeURIComponent("key with space and more")}`,
+    ]) {
+      for (const error of await failures(url)) {
+        expect(error).toBeInstanceOf(Error);
+        const text = strings(error).join("\n");
+        expect(text).not.toContain(CREDENTIAL);
+        expect(text).not.toContain("key with space and more");
+      }
+    }
+  });
+
+  it("hides a password the endpoint echoes alone", async () => {
+    const [user] = PASSWORD_ECHO.split(":");
+    for (const error of await failures(`http://${user}:${PASSWORD}@${origin.slice("http://".length)}/echoes-password/x`)) {
+      expect(error).toBeInstanceOf(Error);
+      expect(strings(error).join("\n")).not.toContain(PASSWORD);
+    }
+  });
+
+  it("hides the user and password of the RPC URL where the endpoint echoes them", async () => {
+    const [user, password] = PASSWORD_ECHO.split(":");
+    for (const error of await failures(`http://${user}:${password}@${origin.slice("http://".length)}/echoes-userinfo/x`)) {
+      expect(error).toBeInstanceOf(Error);
+      expect(strings(error).join("\n")).not.toContain(PASSWORD_ECHO);
+      expect(strings(error).join("\n")).not.toContain(password);
+    }
+  });
+
+  it("hides a same-host URL that differs from rpcUrl, which only the same-host check catches", async () => {
+    for (const error of await failures(`${origin}/echoes-another-path/${CREDENTIAL}`)) {
+      expect(printed(error)).toContain("[RPC URL hidden]");
+      expect(printed(error)).not.toContain(CREDENTIAL);
+      expect(printed(error)).not.toMatch(/https?:\/\/127\.0\.0\.1/);
+    }
+  });
+});

package/src/networks.ts

@@ -1,5 +1,5 @@
 import type { Network } from "@x402/core/types";
-import type { Address } from "viem";
+import { HttpRequestError, TimeoutError, http, type Address, type HttpTransport } from "viem";
 
 export type MetalNetworkName = "devnet" | "testnet";
 
@@ -65,7 +65,7 @@ export const METAL_NETWORKS: Record<MetalNetworkName, MetalNetwork> = {
     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",
   },
 };
 
@@ -98,6 +98,95 @@ export function rpcUrlFor(network: MetalNetwork, override: string | undefined, h
   );
 }
 
+/** 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: string): HttpTransport {
+  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: string) => {
+    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: string) =>
+    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: unknown, seen: Set<unknown>) => {
+    if (value === null || typeof value !== "object" || seen.has(value)) return;
+    seen.add(value);
+    for (const key of Object.getOwnPropertyNames(value)) {
+      const fields = value as Record<string, unknown>;
+      let field: unknown;
+      try {
+        field = fields[key];
+      } catch {
+        continue;
+      }
+      let hidden: unknown = field;
+      if (typeof field === "string") hidden = hide(field);
+      else if (field instanceof Headers) {
+        const entries = [...field].map(([name, text]) => [name, hide(text)] as [string, string]);
+        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;
+        }
+      }) as typeof made.request,
+    };
+  }) as HttpTransport;
+}
+
 /** A dollar token payers authorize ERC-3009 transfers of. */
 export interface DollarToken {
   address: `0x${string}`;
@@ -145,8 +234,9 @@ export function usdzBaseUnits(amount: string | number): string {
 /** Format base units back to a decimal `*USDZ` string for humans, trailing zeros trimmed. */
 export function formatUsdz(amount: bigint | string): string {
   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}`;
 }