@metalntwx/metal-pay 0.1.0 → 0.2.0

package/README.md

@@ -22,6 +22,8 @@ From 2.23 the stock client pays only tokens in its own table unless its spend
 controls list others; `createMetalPaymentClient` lists `*USDZ` there, capped
 at `maxAmount`. On a client of your own, add
 `{ network, asset: USDZ.address }` to `setSpendControls({ allowedAssets })`.
+A paid request is never redirected to another origin, so no other site
+receives the payment. `createMandatePaymentClient` does the same.
 
 ```typescript
 import { privateKeyToAccount } from "viem/accounts";
@@ -88,8 +90,10 @@ budget, how many payments, an expiry) as a Verifiable Intent mandate;
 `ingestCredential` verifies one against the issuers the owner trusts, and
 `bindCall`, `replaceCall` and `revokeCall` build the owner's transactions to its own
 MetalAccount. Wrap those calls with `authorizeMandateCall(client, trustedFactory,
-call, signQuorum)` to authorize an account self-call with its existing weighted
-quorum. The callback supports the same EOA, P-256 and passkey signatures as
+call, signQuorum)` to authorize an account self-call, or a list of them as one
+batch that runs whole or not at all, with its existing weighted quorum. The
+client must name its chain: the digest the quorum signs is computed from it,
+never read from the RPC endpoint. The callback supports the same EOA, P-256 and passkey signatures as
 ordinary account execution. Factory-created clones share an immutable VI
 verifier; budgets and replay protection live in each account. `createMandatePaymentClient({ credential, signDigest, network })`
 is the payer, and `MandateExactScheme` the same payer as a scheme for an
@@ -98,11 +102,11 @@ owner's account whose signature is the agent's per-payment mandate, which
 the account accepts or refuses through ERC-1271. Sellers and facilitators
 see an ordinary `exact` payment. The client sets no limit of its own.
 `readCheck` names the limit behind a refusal, `readMandateState` reads the
-spend, and `pullCall` builds a direct payment with no seller. Amounts are
-whole cents. `verifyMandate` and `verifyMandatePayment` trust the
+spend, and `pullCall` builds a direct payment with no seller. A credential's amounts
+are decimal, to the cent. `verifyMandate` and `verifyMandatePayment` trust the
 MetalAccountFactory `METAL_NETWORKS` names for the chain, or the
-`accountFactory` given, authenticate clone code at the binding and settlement
-blocks, and match the successful token transfer to the seller's requirements.
+`accountFactory` given, check the account's clone code against the
+factory's current implementation, and match the successful token transfer to the seller's requirements.
 The module runs on Node only.
 
 **RPC.** Neither payers nor payees need one. Each network's `rpc` is its

package/dist/client.d.ts

@@ -46,6 +46,12 @@ export interface MetalPaymentClientConfig {
  * `maxAmountPerPayment` base units when one is given.
  */
 export declare function allowAsset(client: x402Client, network: string, asset: string, maxAmountPerPayment?: bigint): void;
+/**
+ * `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 declare function keepPaymentOnOrigin(fetch: typeof globalThis.fetch): typeof globalThis.fetch;
 export interface MetalPaymentClient {
     /** `fetch` that answers a 402 by paying and retrying, once. */
     fetchWithPayment: ReturnType<typeof wrapFetchWithPayment>;

package/dist/client.js

@@ -43,6 +43,35 @@ export function allowAsset(client, network, asset, maxAmountPerPayment) {
         allowedAssets: [{ network, asset, ...(maxAmountPerPayment !== undefined && { maxAmountPerPayment: maxAmountPerPayment.toString() }) }],
     });
 }
+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) {
+    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;
+        }
+    };
+}
 /** One call to pay: `const { fetchWithPayment } = createMetalPaymentClient({ account, network: "devnet" })`. */
 export function createMetalPaymentClient({ account, network, fetch = globalThis.fetch, maxAmount = DEFAULT_MAX_PAYMENT, clearing, }) {
     const resolved = resolveNetwork(network);
@@ -64,7 +93,7 @@ export function createMetalPaymentClient({ account, network, fetch = globalThis.
         };
     });
     return {
-        fetchWithPayment: wrapFetchWithPayment(clearing ? clearing.wrapFetch(fetch) : fetch, client),
+        fetchWithPayment: wrapFetchWithPayment(clearing ? clearing.wrapFetch(keepPaymentOnOrigin(fetch)) : keepPaymentOnOrigin(fetch), client),
         client,
         network: resolved,
     };

package/dist/mandates/account.d.ts

@@ -57,23 +57,6 @@ export declare const metalAccountAbi: readonly [{
     readonly outputs: readonly [{
         readonly type: "uint256";
     }];
-}, {
-    readonly name: "executeDigest";
-    readonly type: "function";
-    readonly stateMutability: "view";
-    readonly inputs: readonly [{
-        readonly type: "bytes32";
-        readonly name: "mode";
-    }, {
-        readonly type: "bytes";
-        readonly name: "executionData";
-    }, {
-        readonly type: "uint256";
-        readonly name: "nonce";
-    }];
-    readonly outputs: readonly [{
-        readonly type: "bytes32";
-    }];
 }, {
     readonly name: "executeSigned";
     readonly type: "function";
@@ -100,7 +83,8 @@ export declare function metalAccountCode(implementation: Address): Hex;
 export declare function assertMetalAccount(client: PublicClient, account: Address, factory: Address, blockNumber?: bigint): Promise<void>;
 /** The gas an executeSigned adds to the call it carries, by the quorum signature's signers. */
 export declare function quorumGas(signature: Hex): bigint;
-/** One self-call approved by the account's existing ERC-7913 quorum. The signing
- * callback may collect mixed keys, weights and passkeys; it returns the normal
- * abi.encode(bytes[] signers, bytes[] signatures) account signature. */
-export declare function authorizeMandateCall(client: PublicClient, factory: Address, call: MandateCall, signQuorum: (digest: Hex) => Promise<Hex>): Promise<MandateCall>;
+/** 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 declare function authorizeMandateCall(client: PublicClient, factory: Address, call: MandateCall | readonly MandateCall[], signQuorum: (digest: Hex) => Promise<Hex>): Promise<MandateCall>;

package/dist/mandates/account.js

@@ -1,4 +1,4 @@
-import { concat, decodeAbiParameters, encodeAbiParameters, encodeFunctionData, bytesToHex, hexToBigInt, parseAbi, parseAbiParameters, size } from "viem";
+import { concat, decodeAbiParameters, encodeAbiParameters, encodeFunctionData, bytesToHex, hashTypedData, hexToBigInt, isAddressEqual, parseAbi, parseAbiParameters, size } from "viem";
 export const metalAccountFactoryAbi = parseAbi([
     "function implementation() view returns (address)",
     "function createAccount(bytes[] signers, uint64[] weights, uint64 threshold) returns (address)",
@@ -6,7 +6,6 @@ export const metalAccountFactoryAbi = parseAbi([
 ]);
 export const metalAccountAbi = parseAbi([
     "function nonces(address owner, uint192 key) view returns (uint256)",
-    "function executeDigest(bytes32 mode, bytes executionData, uint256 nonce) view returns (bytes32)",
     "function executeSigned(bytes32 mode, bytes executionData, uint256 nonce, bytes signature)",
 ]);
 export const ACCOUNT_BATCH_MODE = "0x0100000000000000000000000000000000000000000000000000000000000000";
@@ -56,18 +55,37 @@ export function quorumGas(signature) {
     });
     return gas;
 }
-/** One self-call approved by the account's existing ERC-7913 quorum. The signing
- * callback may collect mixed keys, weights and passkeys; it returns the normal
- * abi.encode(bytes[] signers, bytes[] signatures) account signature. */
+/** 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, factory, call, signQuorum) {
-    await assertMetalAccount(client, call.to, factory);
+    const chainId = client.chain?.id;
+    if (chainId === undefined)
+        throw new Error("the RPC client names no chain");
+    const calls = Array.isArray(call) ? call : [call];
+    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: call.to, abi: metalAccountAbi, functionName: "nonces", args: [call.to, lane] });
+    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)[]"), [[{ target: call.to, value: 0n, callData: call.data }]]);
-    const digest = await client.readContract({ address: call.to, abi: metalAccountAbi, functionName: "executeDigest", args: [ACCOUNT_BATCH_MODE, executionData, nonce] });
+    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);
-    return { ...call, gas: call.gas + quorumGas(signature), data: encodeFunctionData({ abi: metalAccountAbi, functionName: "executeSigned", args: [ACCOUNT_BATCH_MODE, executionData, nonce, signature] }) };
+    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] }) };
 }

package/dist/mandates/client.js

@@ -16,8 +16,8 @@
 import { x402Client } from "@x402/core/client";
 import { wrapFetchWithPayment } from "@x402/fetch";
 import { getAddress } from "viem";
-import { allowAsset } from "../client.js";
-import { resolveNetwork } from "../networks.js";
+import { allowAsset, keepPaymentOnOrigin } from "../client.js";
+import { USDZ, formatUsdz, resolveNetwork } from "../networks.js";
 import { mandateReference } from "./binding.js";
 import { lineItemOf, signPayment, x402Offer } from "./checkout.js";
 import { asksSignedOffer, mandateExtension } from "./extension.js";
@@ -63,6 +63,9 @@ export class MandateExactScheme {
             throw new Error(`a mandate pays by ERC-3009 only, not ${String(method)}`);
         if (getAddress(requirements.asset) !== this.token)
             throw new Error(`asset ${requirements.asset} is not the mandate's token ${this.token}`);
+        if (BigInt(requirements.amount) % this.mandate.terms.unitsPerMinor !== 0n) {
+            throw new Error(`offer of ${formatUsdz(requirements.amount)} ${USDZ.symbol} is not a whole number of cents, which is all a mandate pays`);
+        }
         const now = BigInt(Math.floor(Date.now() / 1000));
         const transfer = {
             chainId: chainIdOf(requirements.network),
@@ -115,7 +118,7 @@ export function createMandatePaymentClient({ network, fetch = globalThis.fetch,
     const client = new x402Client().register(resolved.network, scheme);
     allowAsset(client, resolved.network, scheme.token);
     return {
-        fetchWithPayment: wrapFetchWithPayment(fetch, client),
+        fetchWithPayment: wrapFetchWithPayment(keepPaymentOnOrigin(fetch), client),
         client,
         network: resolved,
         principal: scheme.principal,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metalntwx/metal-pay",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Agent payments on Metal for the official x402 packages: the Metal devnet and testnet as `exact`-scheme networks priced in `*USDZ` for payers and sellers, a one-call payment client with a spending limit, Metal's seller token, the clearing lane for payers who pay per call without a transaction each time, and mandates, which let an agent pay from its owner's account within limits Metal enforces.",
   "license": "MIT",
   "repository": {
@@ -38,7 +38,7 @@
     "viem": "^2"
   },
   "devDependencies": {
-    "@metalntwx/metal-ts": "0.3.0",
+    "@metalntwx/metal-ts": "0.3.2",
     "@types/node": "^24.13.2",
     "@x402/hono": "2.21.0",
     "hono": "4.13.7",