@metalntwx/metal-pay 0.2.0 → 0.3.0

package/src/client.test.ts

@@ -0,0 +1,325 @@
+import { describe, expect, it, vi } from "vitest";
+import { x402Client } from "@x402/core/client";
+import type { PaymentRequired, SchemeNetworkClient } from "@x402/core/types";
+import { getAddress, verifyTypedData } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { buildTransferAuthorizationTypedData } from "@metalntwx/metal-ts/erc3009";
+import {
+  DEFAULT_MAX_PAYMENT,
+  createMetalPaymentClient,
+  registerMetalNetworks,
+} from "./client.js";
+import { METAL_NETWORKS, USDZ, formatUsdz, usdzBaseUnits } from "./networks.js";
+
+const payer = privateKeyToAccount(
+  "0x963db81757846cd99b9b9a49274b334da9ad1384f2b41cae53730986da94d039",
+);
+const PAY_TO = "0x000000000000000000000000000000000000b22b";
+
+const OTHER_TOKEN = "0x000000000000000000000000000000000000c0de";
+
+function offer(
+  network: string,
+  amount = usdzBaseUnits("0.01"),
+  token: { asset: string; extra: { name: string; version: string } } = {
+    asset: USDZ.address,
+    extra: { name: USDZ.name, version: USDZ.version },
+  },
+): PaymentRequired {
+  return {
+    x402Version: 2,
+    resource: {
+      url: "http://seller.local/quote",
+      description: "a quote",
+      mimeType: "application/json",
+    },
+    accepts: [
+      {
+        scheme: "exact",
+        network: network as `${string}:${string}`,
+        asset: token.asset,
+        amount,
+        payTo: PAY_TO,
+        maxTimeoutSeconds: 60,
+        extra: token.extra,
+      },
+    ],
+  };
+}
+
+describe("registerMetalNetworks", () => {
+  // A stock client pays only assets in its own table; *USDZ is not in it.
+  const allowing = () => new x402Client().setSpendControls({ allowedAssets: true });
+
+  it("leaves the spend controls the payer set on its client", async () => {
+    const client = registerMetalNetworks(
+      new x402Client().setSpendControls({
+        allowedAssets: [{ network: "eip155:1337", asset: USDZ.address, maxAmountPerPayment: "5" }],
+      }),
+      { signer: payer },
+    );
+    await expect(client.createPaymentPayload(offer("eip155:1337"))).rejects.toThrow(/maxAmountPerPayment/);
+  });
+
+  it("signs an eip155:1337 offer as the ERC-3009 authorization MIP20 verifies", async () => {
+    const client = registerMetalNetworks(allowing(), { signer: payer });
+    const payload = await client.createPaymentPayload(offer("eip155:1337"));
+    expect(payload.accepted.network).toBe("eip155:1337");
+    const { authorization, signature } = payload.payload as {
+      authorization: {
+        from: `0x${string}`;
+        to: `0x${string}`;
+        value: string;
+        validAfter: string;
+        validBefore: string;
+        nonce: `0x${string}`;
+      };
+      signature: `0x${string}`;
+    };
+    expect(getAddress(authorization.from)).toBe(payer.address);
+    expect(getAddress(authorization.to)).toBe(getAddress(PAY_TO));
+    expect(authorization.value).toBe(usdzBaseUnits("0.01"));
+
+    const typedData = buildTransferAuthorizationTypedData(
+      { tokenName: USDZ.name, chainId: 1337n, verifyingContract: USDZ.address },
+      {
+        from: authorization.from,
+        to: authorization.to,
+        value: BigInt(authorization.value),
+        validAfter: BigInt(authorization.validAfter),
+        validBefore: BigInt(authorization.validBefore),
+        nonce: authorization.nonce,
+      },
+    );
+    const ok = await verifyTypedData({
+      address: payer.address,
+      domain: typedData.domain,
+      types: {
+        TransferWithAuthorization: typedData.types.TransferWithAuthorization,
+      },
+      primaryType: "TransferWithAuthorization",
+      message: typedData.message,
+      signature,
+    });
+    expect(ok).toBe(true);
+  });
+
+  it("registers testnet too", async () => {
+    const client = registerMetalNetworks(allowing(), { signer: payer });
+    const payload = await client.createPaymentPayload(offer("eip155:63825"));
+    expect(payload.accepted.network).toBe(METAL_NETWORKS.testnet.network);
+  });
+
+  it("refuses an offer in any token but *USDZ before anything is signed", async () => {
+    const signTypedData = vi.fn(payer.signTypedData);
+    const client = registerMetalNetworks(allowing(), {
+      signer: { address: payer.address, signTypedData },
+    });
+    const other = {
+      asset: OTHER_TOKEN,
+      extra: { name: "Other USD", version: "1" },
+    };
+    await expect(
+      client.createPaymentPayload(offer("eip155:1337", "1", other)),
+    ).rejects.toThrow(
+      `Payment creation aborted: offer is in ${OTHER_TOKEN}, not *USDZ (${USDZ.address})`,
+    );
+    expect(signTypedData).not.toHaveBeenCalled();
+  });
+
+  it("refuses a *USDZ offer under any signing domain but USDZ's before anything is signed", async () => {
+    const signTypedData = vi.fn(payer.signTypedData);
+    const client = registerMetalNetworks(allowing(), {
+      signer: { address: payer.address, signTypedData },
+    });
+    const renamed = {
+      asset: USDZ.address,
+      extra: { name: "Other USD", version: "2" },
+    };
+    await expect(
+      client.createPaymentPayload(offer("eip155:1337", "1", renamed)),
+    ).rejects.toThrow(
+      'Payment creation aborted: offer signs for the EIP-712 domain "Other USD" version "2", not "USD Zero" version "1"',
+    );
+    expect(signTypedData).not.toHaveBeenCalled();
+  });
+
+  it('refuses a testnet offer signing for the pre-rename "Metal USD" domain before anything is signed', async () => {
+    const signTypedData = vi.fn(payer.signTypedData);
+    const client = registerMetalNetworks(allowing(), {
+      signer: { address: payer.address, signTypedData },
+    });
+    const legacy = {
+      asset: USDZ.address,
+      extra: { name: "Metal USD", version: "1" },
+    };
+    await expect(
+      client.createPaymentPayload(offer("eip155:63825", "1", legacy)),
+    ).rejects.toThrow(
+      'offer signs for the EIP-712 domain "Metal USD" version "1", not "USD Zero" version "1"',
+    );
+    expect(signTypedData).not.toHaveBeenCalled();
+  });
+
+  it("leaves offers in other schemes, such as a custom scheme, to the scheme registered for them", async () => {
+    const custom: SchemeNetworkClient = {
+      scheme: "custom-payment",
+      createPaymentPayload: async (x402Version) => ({
+        x402Version,
+        payload: { debit: "signed" },
+      }),
+    };
+    const client = registerMetalNetworks(allowing(), {
+      signer: payer,
+    }).register("eip155:1337", custom);
+    const customDomain = {
+      asset: USDZ.address,
+      extra: { name: "CustomPayment", version: "1" },
+    };
+    const debit = offer("eip155:1337", "1", customDomain);
+    debit.accepts[0] = { ...debit.accepts[0]!, scheme: "custom-payment" };
+    const payload = await client.createPaymentPayload(debit);
+    expect(payload.payload).toEqual({ debit: "signed" });
+    await expect(
+      client.createPaymentPayload(offer("eip155:1337", "1", customDomain)),
+    ).rejects.toThrow(
+      'offer signs for the EIP-712 domain "CustomPayment" version "1"',
+    );
+  });
+
+  it("accepts the *USDZ address in any letter case", async () => {
+    const client = registerMetalNetworks(allowing(), { signer: payer });
+    const lower = {
+      asset: USDZ.address.toLowerCase(),
+      extra: { name: USDZ.name, version: USDZ.version },
+    };
+    const payload = await client.createPaymentPayload(
+      offer("eip155:1337", "1", lower),
+    );
+    expect(payload.accepted.asset).toBe(lower.asset);
+  });
+});
+
+describe("createMetalPaymentClient", () => {
+  it("pays only on the network it was created for", async () => {
+    const { client, network } = createMetalPaymentClient({
+      account: payer,
+      network: "devnet",
+    });
+    expect(network.chainId).toBe(1337);
+    await expect(
+      client.createPaymentPayload(offer("eip155:63825")),
+    ).rejects.toThrow();
+    const payload = await client.createPaymentPayload(offer("eip155:1337"));
+    expect(payload.accepted.network).toBe("eip155:1337");
+  });
+
+  it("refuses an offer above the limit per payment before anything is signed", async () => {
+    const signTypedData = vi.fn(payer.signTypedData);
+    const { client } = createMetalPaymentClient({
+      account: { address: payer.address, signTypedData },
+      network: "devnet",
+    });
+    await expect(
+      client.createPaymentPayload(offer("eip155:1337", usdzBaseUnits("2"))),
+    ).rejects.toThrow(
+      "Payment creation aborted: offer of 2 *USDZ is above the 1 *USDZ limit per payment",
+    );
+    expect(signTypedData).not.toHaveBeenCalled();
+  });
+
+  it("pays an offer equal to the limit", async () => {
+    const signTypedData = vi.fn(payer.signTypedData);
+    const { client } = createMetalPaymentClient({
+      account: { address: payer.address, signTypedData },
+      network: "devnet",
+    });
+    const payload = await client.createPaymentPayload(
+      offer("eip155:1337", usdzBaseUnits("1")),
+    );
+    expect(payload.accepted.amount).toBe(usdzBaseUnits("1"));
+    expect(signTypedData).toHaveBeenCalledOnce();
+  });
+
+  it("applies a custom maxAmount", async () => {
+    const strict = createMetalPaymentClient({
+      account: payer,
+      network: "devnet",
+      maxAmount: BigInt(usdzBaseUnits("0.005")),
+    });
+    await expect(
+      strict.client.createPaymentPayload(offer("eip155:1337")),
+    ).rejects.toThrow(
+      "offer of 0.01 *USDZ is above the 0.005 *USDZ limit per payment",
+    );
+    const generous = createMetalPaymentClient({
+      account: payer,
+      network: "devnet",
+      maxAmount: BigInt(usdzBaseUnits("5")),
+    });
+    const payload = await generous.client.createPaymentPayload(
+      offer("eip155:1337", usdzBaseUnits("2")),
+    );
+    expect(payload.accepted.amount).toBe(usdzBaseUnits("2"));
+  });
+
+  it("refuses an offer in another token before checking its amount", async () => {
+    const { client } = createMetalPaymentClient({
+      account: payer,
+      network: "devnet",
+    });
+    const other = {
+      asset: OTHER_TOKEN,
+      extra: { name: "Other USD", version: "1" },
+    };
+    await expect(
+      client.createPaymentPayload(
+        offer("eip155:1337", usdzBaseUnits("2"), other),
+      ),
+    ).rejects.toThrow(`offer is in ${OTHER_TOKEN}, not *USDZ`);
+  });
+
+  it("limits each payment to 1 *USDZ by default", () => {
+    expect(DEFAULT_MAX_PAYMENT).toBe(10n ** 18n);
+  });
+
+  it("refuses an unknown network name", () => {
+    expect(() =>
+      createMetalPaymentClient({ account: payer, network: "mainnet" as never }),
+    ).toThrow(/unknown Metal network/);
+  });
+
+  it("keeps its own refusals by standing the client's spend controls aside", () => {
+    const prototype = x402Client.prototype;
+    const original = prototype.setSpendControls;
+    const setSpendControls = vi.fn(function (this: x402Client) {
+      return this;
+    });
+    prototype.setSpendControls = setSpendControls as typeof original;
+    try {
+      createMetalPaymentClient({
+        account: payer,
+        network: "testnet",
+        maxAmount: BigInt(usdzBaseUnits("0.05")),
+      });
+    } finally {
+      prototype.setSpendControls = original;
+    }
+    expect(setSpendControls).toHaveBeenLastCalledWith({ allowedAssets: true });
+  });
+});
+
+describe("usdz amounts", () => {
+  it("converts decimals to 18-digit base units and back", () => {
+    expect(usdzBaseUnits("0.01")).toBe("10000000000000000");
+    expect(usdzBaseUnits("$1.50")).toBe("1500000000000000000");
+    expect(usdzBaseUnits(2)).toBe("2000000000000000000");
+    expect(formatUsdz(10000000000000000n)).toBe("0.01");
+    expect(formatUsdz("2000000000000000000")).toBe("2");
+  });
+
+  it("rejects malformed and over-precise amounts", () => {
+    expect(() => usdzBaseUnits("1e3")).toThrow();
+    expect(() => usdzBaseUnits("0." + "1".repeat(19))).toThrow(/decimals/);
+  });
+});

package/src/client.ts

@@ -0,0 +1,156 @@
+import { x402Client } from "@x402/core/client";
+import { wrapFetchWithPayment } from "@x402/fetch";
+import type { ClientEvmSigner } from "@x402/evm";
+import type { Network } from "@x402/core/types";
+import { ExactEvmScheme } from "@x402/evm/exact/client";
+import {
+  METAL_NETWORKS,
+  USDZ,
+  formatUsdz,
+  usdzBaseUnits,
+  resolveNetwork,
+  type MetalNetwork,
+  type MetalNetworkName,
+} from "./networks.js";
+
+/**
+ * What signs a payment: a viem local account (`privateKeyToAccount`) or
+ * anything with an address and EIP-712 `signTypedData`.
+ */
+export type MetalPaymentSigner = Pick<
+  ClientEvmSigner,
+  "address" | "signTypedData"
+>;
+
+export interface RegisterMetalNetworksConfig {
+  signer: MetalPaymentSigner;
+  /** Which Metal networks to accept offers on; both by default. */
+  networks?: readonly (MetalNetworkName | MetalNetwork)[];
+}
+
+/**
+ * Register Metal's devnet and testnet with an `@x402/core` client for the
+ * `exact` scheme. The client signs an `exact` offer on `eip155:1337` or
+ * `eip155:63825` only when it is in `*USDZ` under USDZ's EIP-712 domain, and
+ * refuses any other before signing. Offers in other schemes are left to
+ * the schemes explicitly registered for them.
+ */
+export function registerMetalNetworks(
+  client: x402Client,
+  { signer, networks }: RegisterMetalNetworksConfig,
+): x402Client {
+  const scheme = new ExactEvmScheme(signer);
+  const registered = (networks ?? Object.values(METAL_NETWORKS)).map(
+    (entry) => resolveNetwork(entry).network,
+  );
+  for (const network of registered) client.register(network, scheme);
+  // ExactEvmScheme signs for whatever token an offer names, and that token redeems the signature without the facilitator.
+  client.onBeforePaymentCreation(
+    async ({ selectedRequirements: { scheme, network, asset, extra } }) => {
+      if (scheme !== "exact" || !registered.includes(network)) return;
+      if (asset.toLowerCase() !== USDZ.address.toLowerCase()) {
+        return {
+          abort: true,
+          reason: `offer is in ${asset}, not ${USDZ.symbol} (${USDZ.address})`,
+        };
+      }
+      if (extra?.name !== USDZ.name || extra?.version !== USDZ.version) {
+        return {
+          abort: true,
+          reason: `offer signs for the EIP-712 domain "${extra?.name}" version "${extra?.version}", not "${USDZ.name}" version "${USDZ.version}"`,
+        };
+      }
+    },
+  );
+  return client;
+}
+
+/** The most a payment client pays for one offer unless told otherwise: 1 `*USDZ`, in base units. */
+export const DEFAULT_MAX_PAYMENT = BigInt(usdzBaseUnits("1"));
+
+export interface MetalPaymentClientConfig {
+  account: MetalPaymentSigner;
+  /** The one network this client pays on; offers for any other are refused. */
+  network: MetalNetworkName | MetalNetwork;
+  /** The fetch to wrap; `globalThis.fetch` by default. */
+  fetch?: typeof globalThis.fetch;
+  /**
+   * The most one payment may cost, in `*USDZ` base units; `DEFAULT_MAX_PAYMENT`
+   * by default. An offer above it is refused before anything is signed.
+   */
+  maxAmount?: bigint;
+}
+
+/**
+ * The stock client pays only assets in its own table unless its spend
+ * controls list others. This lists `asset` on `network`.
+ */
+export function allowAsset(client: x402Client, network: Network, asset: string): void {
+  client.setSpendControls({ allowedAssets: [{ network, asset }] });
+}
+
+const REDIRECTS = new Set([301, 302, 303, 307, 308]);
+
+/**
+ * `fetch` that follows the redirects of a request carrying a payment only
+ * within the origin it was made for, and answers a redirect to any other
+ * origin as it is, so no other origin receives the payment.
+ */
+export function keepPaymentOnOrigin(fetch: typeof globalThis.fetch): typeof globalThis.fetch {
+  return async (input, init) => {
+    const request = new Request(input, init);
+    if (!request.headers.has("PAYMENT-SIGNATURE") && !request.headers.has("X-PAYMENT")) return fetch(request);
+    const body = request.body === null ? undefined : await request.arrayBuffer();
+    let url = new URL(request.url);
+    let method = request.method;
+    for (let hops = 0; ; hops++) {
+      const sendsBody = method !== "GET" && method !== "HEAD";
+      const response = await fetch(new Request(url, { method, headers: request.headers, ...(sendsBody && body !== undefined && { body }), signal: request.signal, redirect: "manual" }));
+      const location = response.headers.get("location");
+      if (!REDIRECTS.has(response.status) || location === null || hops === 20) return response;
+      const next = new URL(location, url);
+      if (next.origin !== url.origin) return response;
+      if (response.status === 303 || (response.status <= 302 && method === "POST")) method = "GET";
+      url = next;
+    }
+  };
+}
+
+export interface MetalPaymentClient {
+  /** `fetch` that answers a 402 by paying and retrying, once. */
+  fetchWithPayment: ReturnType<typeof wrapFetchWithPayment>;
+  client: x402Client;
+  network: MetalNetwork;
+}
+
+/** One call to pay: `const { fetchWithPayment } = createMetalPaymentClient({ account, network: "devnet" })`. */
+export function createMetalPaymentClient({
+  account,
+  network,
+  fetch = globalThis.fetch,
+  maxAmount = DEFAULT_MAX_PAYMENT,
+}: MetalPaymentClientConfig): MetalPaymentClient {
+  const resolved = resolveNetwork(network);
+  const client = registerMetalNetworks(new x402Client(), {
+    signer: account,
+    networks: [resolved],
+  });
+  // The hooks are the guard: the client's own spend controls would refuse
+  // first, naming nothing of the offer, so they stand aside on this client.
+  client.setSpendControls({ allowedAssets: true });
+  // @x402/fetch signs whatever amount an offer asks; this hook is the payer's spending guard.
+  client.onBeforePaymentCreation(
+    async ({ selectedRequirements: { amount } }) => {
+      if (BigInt(amount) <= maxAmount) return;
+      return {
+        abort: true,
+        reason: `offer of ${formatUsdz(amount)} ${USDZ.symbol} is above the ${formatUsdz(maxAmount)} ${USDZ.symbol} limit per payment`,
+      };
+    },
+  );
+  return {
+    fetchWithPayment: wrapFetchWithPayment(keepPaymentOnOrigin(fetch), client),
+    client,
+    network: resolved,
+  };
+}

package/src/index.ts

@@ -0,0 +1,33 @@
+export {
+  METAL_NETWORKS,
+  USDZ,
+  formatUsdz,
+  metalNetwork,
+  usdzBaseUnits,
+  accountFactoryFor,
+  rpcUrlFor,
+  type DollarToken,
+  type MetalNetwork,
+  type MetalNetworkName,
+} from "./networks.js";
+export {
+  DEFAULT_MAX_PAYMENT,
+  createMetalPaymentClient,
+  registerMetalNetworks,
+  type MetalPaymentClient,
+  type MetalPaymentClientConfig,
+  type MetalPaymentSigner,
+  type RegisterMetalNetworksConfig,
+} from "./client.js";
+export {
+  metalUsd,
+  registerMetalScheme,
+  sellerToken,
+  type RegisterMetalSchemeConfig,
+} from "./server.js";
+export * from "./clearing-codec.js";
+export { clearingAbi } from "./clearing-abi.js";
+export * from "./clearing-client.js";
+export * from "./clearing-x402.js";
+export * from "./clearing-server.js";
+export * from "./clearing-custody.js";

package/src/mandates/account.ts

@@ -0,0 +1,91 @@
+import { type Address, type Hex, type PublicClient, concat, decodeAbiParameters, encodeAbiParameters, encodeFunctionData, bytesToHex, hashTypedData, hexToBigInt, isAddressEqual, parseAbi, parseAbiParameters, size } from "viem";
+import type { MandateCall } from "./binding.js";
+
+export const metalAccountFactoryAbi = parseAbi([
+  "function implementation() view returns (address)",
+  "function createAccount(bytes[] signers, uint64[] weights, uint64 threshold) returns (address)",
+  "function predictAccount(bytes[] signers, uint64[] weights, uint64 threshold) view returns (address)",
+]);
+export const metalAccountAbi = parseAbi([
+  "function nonces(address owner, uint192 key) view returns (uint256)",
+  "function executeSigned(bytes32 mode, bytes executionData, uint256 nonce, bytes signature)",
+]);
+export const ACCOUNT_BATCH_MODE = "0x0100000000000000000000000000000000000000000000000000000000000000";
+
+/** Exact immutable ERC-1167 clone emitted by MetalAccountFactory. */
+export function metalAccountCode(implementation: Address): Hex {
+  return concat(["0x363d3d373d3d3d363d73", implementation, "0x5af43d82803e903d91602b57fd5bf3"]).toLowerCase() as Hex;
+}
+
+/** The factory is a caller-selected trust anchor, never inferred from payer-controlled data. */
+export async function assertMetalAccount(client: PublicClient, account: Address, factory: Address, blockNumber?: bigint): Promise<void> {
+  const at = blockNumber === undefined ? {} : { blockNumber };
+  const implementation = await client.readContract({ address: factory, abi: metalAccountFactoryAbi, functionName: "implementation", ...at });
+  const code = await client.getCode({ address: account, ...at });
+  const when = blockNumber === undefined ? "" : ` at block ${blockNumber}`;
+  if (code === undefined || code === "0x") throw new Error(`${account} has no code${when}: no account is deployed there`);
+  if (code.toLowerCase() !== metalAccountCode(implementation)) throw new Error(`${account} is not a MetalAccount clone of the trusted factory ${factory}`);
+}
+
+/** The account's own execution, with a quorum of keys. */
+const EXECUTION_GAS = 500_000n;
+/**
+ * What one signature beyond an EOA's 65-byte ECDSA costs the account to
+ * verify, per started 512 bytes of it: a P-256 key or a passkey runs the
+ * P-256 precompile (441,600 gas on Metal), and a nested account's signature
+ * may carry several. A 1-of-1 passkey account's executeSigned of a token
+ * transfer measured 620,302 gas.
+ */
+const SIGNATURE_GAS = 700_000n;
+
+/** The gas an executeSigned adds to the call it carries, by the quorum signature's signers. */
+export function quorumGas(signature: Hex): bigint {
+  const perStarted512 = (bytes: bigint) => SIGNATURE_GAS * ((bytes + 511n) / 512n || 1n);
+  let signers: readonly Hex[];
+  let signatures: readonly Hex[];
+  try {
+    [signers, signatures] = decodeAbiParameters(parseAbiParameters("bytes[], bytes[]"), signature);
+  } catch {
+    // Not the (signers, signatures) form the account reads: size it by its length.
+    return EXECUTION_GAS + perStarted512(BigInt(size(signature)));
+  }
+  let gas = EXECUTION_GAS;
+  signers.forEach((signer, i) => {
+    const bytes = BigInt(size(signatures[i] ?? "0x"));
+    if (size(signer) === 20 && bytes === 65n) return;
+    gas += perStarted512(bytes);
+  });
+  return gas;
+}
+
+/** Self-calls approved by the account's existing ERC-7913 quorum, in one batch
+ * that runs whole or not at all. The signing callback may collect mixed keys,
+ * weights and passkeys; it returns the normal abi.encode(bytes[] signers,
+ * bytes[] signatures) account signature. */
+export async function authorizeMandateCall(client: PublicClient, factory: Address, call: MandateCall | readonly MandateCall[], signQuorum: (digest: Hex) => Promise<Hex>): Promise<MandateCall> {
+  const chainId = client.chain?.id;
+  if (chainId === undefined) throw new Error("the RPC client names no chain");
+  const calls = Array.isArray(call) ? (call as readonly MandateCall[]) : [call as MandateCall];
+  const [first] = calls;
+  if (first === undefined) throw new Error("no call to authorize");
+  const account = first.to;
+  if (calls.some((c) => !isAddressEqual(c.to, account))) throw new Error("every call in one batch goes to the same account");
+  await assertMetalAccount(client, account, factory);
+  // A fresh 192-bit nonce lane per call: two administration calls in flight,
+  // or one beside the owner's own operations on lane 0, never claim one nonce.
+  const lane = hexToBigInt(bytesToHex(crypto.getRandomValues(new Uint8Array(24))));
+  const sequence = await client.readContract({ address: account, abi: metalAccountAbi, functionName: "nonces", args: [account, lane] });
+  const nonce = (lane << 64n) | sequence;
+  const executionData = encodeAbiParameters(parseAbiParameters("(address target, uint256 value, bytes callData)[]"), [calls.map((c) => ({ target: account, value: 0n, callData: c.data }))]);
+  // The account's executeDigest, computed here: an RPC endpoint that answered
+  // it could have the quorum sign a batch of its own choosing.
+  const digest = hashTypedData({
+    domain: { name: "MetalAccount", version: "1", chainId, verifyingContract: account },
+    types: { Execute: [{ name: "mode", type: "bytes32" }, { name: "executionData", type: "bytes" }, { name: "nonce", type: "uint256" }] },
+    primaryType: "Execute",
+    message: { mode: ACCOUNT_BATCH_MODE, executionData, nonce },
+  });
+  const signature = await signQuorum(digest);
+  const gas = calls.reduce((sum, c) => sum + c.gas, 0n) + quorumGas(signature);
+  return { ...first, gas, data: encodeFunctionData({ abi: metalAccountAbi, functionName: "executeSigned", args: [ACCOUNT_BATCH_MODE, executionData, nonce, signature] }) };
+}