@metalntwx/metal-pay 0.2.0 → 0.3.0

package/dist/mandates/binding.js

@@ -1,4 +1,4 @@
-// MetalAccount mandate ABI, typed agent keys, references, self-calls and direct pulls.
+// MetalAccount mandate ABI, typed agent keys, references, self-calls and pulls.
 import { concat, encodeFunctionData, encodePacked, keccak256, parseAbi, size, slice } from "viem";
 /** Domain tag for the payment-only ERC-1271 path on MetalAccount. */
 export const MANDATE_SIGNATURE_TAG = "0x4d4e4454";
@@ -10,7 +10,6 @@ export const mandateBindingAbi = parseAbi([
     "struct Terms { string kid; string instrument; string currency; uint256 unitsPerMinor; Payee[] payees; bytes32 openSdHash; }",
     "struct PayeeTerms { bytes32 sdHash; string object; }",
     "struct MandateState { address principal; bool revoked; bytes32 agentX; bytes32 agentY; string kid; bytes32 openSdHash; uint64 boundBlock; uint64 occurrences; uint128 spent; }",
-    "function mip20TransferHandler() pure returns (bytes4)",
     "function mandateReference(address principal, bytes agentKey, bytes32 hashC) pure returns (bytes32)",
     "function mandates(bytes32 ref) view returns (MandateState)",
     "function payee(bytes32 ref, address account) view returns (PayeeTerms)",
@@ -21,9 +20,9 @@ export const mandateBindingAbi = parseAbi([
     "function revoke(bytes32 ref)",
     "function isValidSignature(bytes32 hash, bytes blob) view returns (bytes4)",
     "function check(Pull p, L3a l) view returns (uint8)",
-    "function pull(Pull p, L3a l)",
+    "function pull(Pull p, L3a l) returns (bool paid)",
     "event MandateBound(bytes32 indexed ref, bytes32 hashC, bytes32 issuerKey, bytes agentKey, Constraints constraints, Terms terms)",
-    "event MandatePayment(bytes32 indexed ref, address indexed to, bytes20 l3aDigest, bytes agentKey, uint256 amount, uint256 spent, uint256 occurrences, bool direct)",
+    "event MandatePayment(bytes32 indexed ref, address indexed to, bytes20 l3aDigest, bytes agentKey, uint256 amount, uint256 spent, uint256 occurrences)",
     "event MandateRefused(bytes32 indexed ref, address indexed to, bytes20 l3aDigest, bytes agentKey, uint256 amount, uint8 reason)",
     "event MandateRevoked(bytes32 indexed ref)",
     "event MandateReplaced(bytes32 indexed predecessor, bytes32 indexed successor)",
@@ -44,9 +43,6 @@ export const mandateBindingAbi = parseAbi([
     "error NonceAlreadyUsed()",
     "error NotYetValid()",
     "error RefusalLimitReached()",
-    "error NotApproved()",
-    "error MandateBreach(uint8 reason)",
-    "error UnauthorizedHookCaller()",
 ]);
 /** `MandateTypes.Reason` in declaration order, which is the order Mandate Binding checks them in; `None` is a pass. */
 export const REASONS = [
@@ -74,13 +70,13 @@ export const REFUSALS = {
     NoMandate: { reason: "mandate_not_bound", meaning: "no such mandate is bound on the account" },
     Revoked: { reason: "mandate_revoked", meaning: "the mandate is revoked, or replaced: the agent pays under the credential that replaced it" },
     Expired: { reason: "mandate_expired", meaning: "the mandate has expired" },
-    BadSignature: { reason: "mandate_bad_signature", meaning: "the payment is not signed by the mandate's agent key" },
+    BadSignature: { reason: "mandate_bad_signature", meaning: "the payment is not signed by the mandate key" },
     NonceUsed: { reason: "mandate_nonce_used", meaning: "this payment was already made or refused" },
     OutsideWindow: { reason: "mandate_outside_window", meaning: "the payment's validity window is not open" },
     PayeeNotAllowed: { reason: "mandate_payee_not_listed", meaning: "the payee is not one the mandate allows" },
     OverPerPaymentCap: { reason: "mandate_cap_exceeded", meaning: "the amount is above the mandate's per-payment cap" },
     OverBudget: { reason: "mandate_budget_spent", meaning: "the amount would take the mandate past its budget" },
-    OutsideRecurrence: { reason: "mandate_outside_recurrence", meaning: "today is outside the mandate's dates" },
+    OutsideRecurrence: { reason: "mandate_outside_recurrence", meaning: "the mandate has not started yet, or its dates have ended" },
     OverOccurrences: { reason: "mandate_occurrences_used", meaning: "the mandate's payment count is used up" },
 };
 /** `mandate_cap_exceeded (the amount is above the mandate's per-payment cap)`: a refusal as a person reads it. */

package/dist/mandates/checkout.js

@@ -61,7 +61,7 @@ export function readCheckoutJwt(jwt) {
     const [h, p, sig] = segments;
     const header = JSON.parse(Buffer.from(fromB64url(h)).toString("utf8"));
     if (header.alg !== "ES256" || header.typ !== "JWT" || typeof header.kid !== "string")
-        throw new Error("a checkout JWT is an ES256 JWT naming the agent key");
+        throw new Error("a checkout JWT is an ES256 JWT naming the mandate key");
     const offer = JSON.parse(Buffer.from(fromB64url(p)).toString("utf8"));
     if (offer === null || typeof offer !== "object" || Array.isArray(offer))
         throw new Error("a checkout JWT's payload is an object");
@@ -126,7 +126,7 @@ export function readL3b(serialized) {
     const payload = JSON.parse(Buffer.from(fromB64url(p)).toString("utf8"));
     const [, final] = JSON.parse(Buffer.from(fromB64url(checkoutDisclosure)).toString("utf8"));
     if (typeof header.kid !== "string")
-        throw new Error("an L3b names the agent key");
+        throw new Error("an L3b names the mandate key");
     if (final.vct !== CHECKOUT_VCT || typeof final.checkout_jwt !== "string")
         throw new Error(`the disclosure is not a ${CHECKOUT_VCT} with a checkout JWT`);
     const signature = fromB64url(sig);
@@ -183,9 +183,9 @@ function checkCheckoutMandate(serialized, expect) {
     if (l3b.typ !== "kb-sd-jwt")
         problems.push("the checkout mandate's typ is not kb-sd-jwt");
     if (l3b.kid !== expect.kid)
-        problems.push("the checkout mandate names another agent key");
+        problems.push("the checkout mandate names another mandate key");
     if (!verifyL3aSignature(expect.agent, sha256Hex(Buffer.from(l3b.signingInput, "ascii")), l3b.r, l3b.s))
-        problems.push("the checkout mandate is not signed by the mandate's agent key");
+        problems.push("the checkout mandate is not signed by the mandate key");
     if (typeof l3b.aud !== "string" || !/^0x[0-9a-fA-F]{40}$/.test(l3b.aud) || !isAddressEqual(l3b.aud, expect.payee))
         problems.push("the checkout mandate is for another payee");
     const now = expect.now ?? Math.floor(Date.now() / 1000);
@@ -215,7 +215,7 @@ function checkCheckoutMandate(serialized, expect) {
     let lineItemId = expect.lineItemId;
     if (jwt !== undefined) {
         if (jwt.kid !== expect.kid || !verifyL3aSignature(expect.agent, sha256Hex(Buffer.from(jwt.signingInput, "ascii")), jwt.r, jwt.s))
-            problems.push("the checkout JWT is not signed by the mandate's agent key");
+            problems.push("the checkout JWT is not signed by the mandate key");
         if (expect.offer !== undefined && jwt.signingInput !== buildCheckoutJwt(expect.kid, expect.offer).signingInput)
             problems.push("the checkout JWT is not over the offer the payee served");
         const offer = expect.offer ?? jwt.offer;

package/dist/mandates/client.js

@@ -5,9 +5,10 @@
 // `TransferWithAuthorization` whose `from` is the principal's account, whose
 // nonce is `bytes12(mandate reference) ‖ bytes20(SHA-256(L3a signing input))`,
 // whose window is the L3a's `iat` and `exp`, and whose signature is
-// `abi.encode(Pull, L3a fields)`, which the account's Mandate Binding accepts
-// or refuses through ERC-1271. Sellers and facilitators see an ordinary
-// `exact` payment; a seller that asks for the agent's signed order gets it in
+// `MNDT || abi.encode(Pull, L3a fields)`, the arguments of `pull` on the
+// principal's account. Sellers see an ordinary `exact` payment; Metal's
+// facilitator submits it as that `pull`, where Mandate Binding accepts or
+// refuses it. A seller that asks for the agent's signed order gets it in
 // the payload's `extensions`, and the per-payment mandate names its hash.
 //
 // `@x402/evm`'s `exact` client draws its own nonce and signs EIP-712 as

package/dist/mandates/l3a.d.ts

@@ -64,9 +64,9 @@ export declare function signL3a(args: {
     iss: string;
     signDigest: SignDigest;
 }): Promise<SignedL3a>;
-/** The relayed authorisation's signature: `MNDT || abi.encode(Pull, L3a fields)`. */
+/** The x402 payload's signature: `MNDT || abi.encode(Pull, L3a fields)`, the arguments of `pull`. */
 export declare function encodeMandateBlob(pull: Pull, fields: L3aFields): Hex;
-/** The Pull and L3a fields a relayed authorisation's signature carries, as Mandate Binding's `check` and `pull` take them. */
+/** The Pull and L3a fields an x402 payload's signature carries, as Mandate Binding's `check` and `pull` take them. */
 export declare function decodeMandateBlob(blob: Hex): {
     pull: Pull;
     fields: L3aFields;

package/dist/mandates/l3a.js

@@ -4,8 +4,9 @@
 // verbatim), with `aud` the chain as `eip155:<chainId>`, `iat`/`exp` the
 // ERC-3009 window, and `transaction_id` the SHA-256 of the RFC 8785 form of
 // the seller's x402 payment requirements. The ERC-3009 nonce is
-// `bytes12(mandate reference) ‖ bytes20(SHA-256(signing input))`; the relayed
-// signature is `MNDT || abi.encode(Pull, L3a fields)`.
+// `bytes12(mandate reference) ‖ bytes20(SHA-256(signing input))`; the x402
+// payload's signature is `MNDT || abi.encode(Pull, L3a fields)`, which the
+// facilitator decodes into `pull`'s arguments.
 import { p256 } from "@noble/curves/nist";
 import { bytesToHex, concat, decodeAbiParameters, encodeAbiParameters, getAbiItem, hexToBigInt, hexToBytes, isAddressEqual, numberToHex, size, slice, zeroAddress, } from "viem";
 import { mandateBindingAbi, referencePrefix } from "./binding.js";
@@ -145,11 +146,11 @@ export async function signL3a(args) {
     return { pull, fields: { ...unsigned, r, s }, serialized: serializeL3a(l3a, r, s), digest: l3a.digest };
 }
 const pullInputs = getAbiItem({ abi: mandateBindingAbi, name: "pull" }).inputs;
-/** The relayed authorisation's signature: `MNDT || abi.encode(Pull, L3a fields)`. */
+/** The x402 payload's signature: `MNDT || abi.encode(Pull, L3a fields)`, the arguments of `pull`. */
 export function encodeMandateBlob(pull, fields) {
     return concat([MANDATE_SIGNATURE_TAG, encodeAbiParameters(pullInputs, [pull, fields])]);
 }
-/** The Pull and L3a fields a relayed authorisation's signature carries, as Mandate Binding's `check` and `pull` take them. */
+/** The Pull and L3a fields an x402 payload's signature carries, as Mandate Binding's `check` and `pull` take them. */
 export function decodeMandateBlob(blob) {
     if (size(blob) < 4 || slice(blob, 0, 4) !== MANDATE_SIGNATURE_TAG)
         throw new Error("not a MetalAccount mandate signature");

package/dist/mandates/seller.d.ts

@@ -17,7 +17,7 @@ export type RequireSignedOfferConfig = {
  * On a route whose offer asks for it (`extra.signedOffer: "required"`), a
  * payment under a mandate must carry the agent's signed order, checked before
  * the facilitator is asked: the payer's account binds the mandate the payment
- * names, and the signed order is that mandate's agent key over the offer the
+ * names, and the signed order is that mandate's key over the offer the
  * server served, for this payee, buying its one line item (`extra.resource`
  * when the route names one, else the payee). A refusal is a 402 whose reason
  * names the check that failed, a payment that names no mandate included. A

package/dist/mandates/seller.js

@@ -13,7 +13,7 @@ import { asksSignedOffer, mandateRefOf, signedOfferOf } from "./extension.js";
  * On a route whose offer asks for it (`extra.signedOffer: "required"`), a
  * payment under a mandate must carry the agent's signed order, checked before
  * the facilitator is asked: the payer's account binds the mandate the payment
- * names, and the signed order is that mandate's agent key over the offer the
+ * names, and the signed order is that mandate's key over the offer the
  * server served, for this payee, buying its one line item (`extra.resource`
  * when the route names one, else the payee). A refusal is a 402 whose reason
  * names the check that failed, a payment that names no mandate included. A

package/dist/mandates/verify.d.ts

@@ -14,10 +14,10 @@ export interface VerifyStep {
     detail: string;
 }
 export declare const STEP_TITLES: {
-    readonly 1: "The mandate is bound on the principal's account: hash(C), the limits, the payees, the agent key and the issuer key are on chain";
-    readonly 2: "The credential in hand hashes to the bound hash(C) and states the bound limits, payees and agent key";
+    readonly 1: "The mandate is bound on the principal's account: hash(C), the limits, the payees, the mandate key and the issuer key are on chain";
+    readonly 2: "The credential in hand hashes to the bound hash(C) and states the bound limits, payees and mandate key";
     readonly 3: "The credential's signatures: the issuer's under a trusted key that is the one recorded at binding, the owner's under the key the issuer bound";
-    readonly 4: "Each payment and refusal is the agent key's per-payment mandate, rebuilt from its transaction, inside the mandate at its block";
+    readonly 4: "Each payment and refusal is the mandate key's per-payment mandate, rebuilt from its transaction, inside the mandate at its block";
 };
 /** A mandate as its `MandateBound` event records it. */
 export interface BoundMandate {
@@ -40,11 +40,9 @@ export interface VerifiedPayment {
     kind: "payment" | "refusal";
     txHash: Hash;
     block: bigint;
-    /** Whether `pull` submitted it, with no seller; otherwise a relayer submitted the ERC-3009 authorisation to the token. */
-    direct: boolean;
     to: Address;
     amount: bigint;
-    /** The ERC-3009 nonce the token recorded; a seller's `/settlements` row carries it for a relayed payment. */
+    /** The ERC-3009 nonce the token recorded; a seller's `/settlements` row carries it for a payment the facilitator settled. */
     nonce?: Hex;
     reason?: ReasonName;
     /** The L3a SD-JWT, as the VI reference serialises it, when the transaction carried one. */

package/dist/mandates/verify.js

@@ -8,14 +8,14 @@
 // changes, so what it is now it was when it bound and paid. What a verifier
 // cannot rebuild (the budget's running total, the nonce's single use) is read
 // as the contract recorded it in the event and checked against the limits.
-import { decodeFunctionData, formatLog, getAbiItem, hexToBigInt, isAddressEqual, numberToHex, parseAbi, erc20Abi, parseEventLogs, slice, toFunctionSelector, } from "viem";
+import { decodeFunctionData, formatLog, getAbiItem, hexToBigInt, isAddressEqual, numberToHex, erc20Abi, parseEventLogs, slice, 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 { jcs } from "./jcs.js";
-import { buildL3a, decodeMandateBlob, mandateNonce, serializeL3a, transactionIdOf, verifyL3aSignature } from "./l3a.js";
+import { buildL3a, mandateNonce, serializeL3a, transactionIdOf, verifyL3aSignature } from "./l3a.js";
 import { extractTerms, hashCredential, issuerKeyId, verifyCredential } from "./vi/credential.js";
 function before(a, b) {
     return a.block < b.block || (a.block === b.block && (a.transactionIndex < b.transactionIndex || (a.transactionIndex === b.transactionIndex && a.logIndex < b.logIndex)));
@@ -26,17 +26,11 @@ function position(log) {
     return { block: log.blockNumber, transactionIndex: log.transactionIndex, logIndex: log.logIndex };
 }
 export const STEP_TITLES = {
-    1: "The mandate is bound on the principal's account: hash(C), the limits, the payees, the agent key and the issuer key are on chain",
-    2: "The credential in hand hashes to the bound hash(C) and states the bound limits, payees and agent key",
+    1: "The mandate is bound on the principal's account: hash(C), the limits, the payees, the mandate key and the issuer key are on chain",
+    2: "The credential in hand hashes to the bound hash(C) and states the bound limits, payees and mandate key",
     3: "The credential's signatures: the issuer's under a trusted key that is the one recorded at binding, the owner's under the key the issuer bound",
-    4: "Each payment and refusal is the agent key's per-payment mandate, rebuilt from its transaction, inside the mandate at its block",
+    4: "Each payment and refusal is the mandate key's per-payment mandate, rebuilt from its transaction, inside the mandate at its block",
 };
-const erc3009Abi = parseAbi([
-    "function transferWithAuthorization(address from, address to, uint256 value, uint256 validAfter, uint256 validBefore, bytes32 nonce, bytes signature)",
-    "function transferWithAuthorizationWithPolicy(address from, address to, uint256 value, uint256 validAfter, uint256 validBefore, bytes32 nonce, bytes signature, bytes policyData)",
-    "function receiveWithAuthorization(address from, address to, uint256 value, uint256 validAfter, uint256 validBefore, bytes32 nonce, bytes signature)",
-    "function receiveWithAuthorizationWithPolicy(address from, address to, uint256 value, uint256 validAfter, uint256 validBefore, bytes32 nonce, bytes signature, bytes policyData)",
-]);
 const short = (hex) => `${hex.slice(0, 10)}…`;
 /** A reason as the facilitator names it to a payer. */
 const named = (reason) => (reason === "None" ? "none" : REFUSALS[reason].reason);
@@ -77,45 +71,30 @@ function reasonContradiction(reason, pull, m, at) {
         return `it breaks the mandate: ${named(first)}`;
     return REASONS.indexOf(first) < REASONS.indexOf(reason) ? `${named(first)} holds, and Mandate Binding checks it before ${named(reason)}` : undefined;
 }
-/** The selectors a payment's calldata carries: `pull` on the principal, or an ERC-3009 authorisation on the token. */
+/** The selector a payment's calldata carries: `pull` on the principal, whoever submitted it. */
 const PULL_SELECTOR = toFunctionSelector(getAbiItem({ abi: mandateBindingAbi, name: "pull" }));
-const ERC3009_SELECTORS = erc3009Abi.map((item) => toFunctionSelector(item));
 /**
- * Every pull of the principal's and every ERC-3009 authorisation from it that
- * `input` carries: at the top level, or inside whatever wrapped the call (a
- * multicall, a sponsor's batch, the quorum's own execute). Each selector in
- * the calldata is tried as a call's start; the one the event's digest names
- * is the payment's, and a forged candidate rebuilds to another digest.
+ * Every pull that `input` carries: at the top level, or inside whatever
+ * wrapped the call (a multicall, a sponsor's batch, the quorum's own
+ * execute). Each occurrence of the selector in the calldata is tried as a
+ * call's start; the one the event's digest names is the payment's, and a
+ * forged candidate rebuilds to another digest.
  */
-function carriedL3as(input, m) {
+function carriedL3as(input) {
     const found = [];
     const body = input.slice(2);
-    for (const selector of [PULL_SELECTOR, ...ERC3009_SELECTORS]) {
-        for (let at = body.indexOf(selector.slice(2)); at !== -1; at = body.indexOf(selector.slice(2), at + 2)) {
-            if (at % 2 !== 0)
+    for (let at = body.indexOf(PULL_SELECTOR.slice(2)); at !== -1; at = body.indexOf(PULL_SELECTOR.slice(2), at + 2)) {
+        if (at % 2 !== 0)
+            continue;
+        try {
+            const call = decodeFunctionData({ abi: mandateBindingAbi, data: `0x${body.slice(at)}` });
+            if (call.functionName !== "pull")
                 continue;
-            const data = `0x${body.slice(at)}`;
-            try {
-                if (selector === PULL_SELECTOR) {
-                    const call = decodeFunctionData({ abi: mandateBindingAbi, data });
-                    if (call.functionName !== "pull")
-                        continue;
-                    const [pull, fields] = call.args;
-                    found.push({ pull: { ...pull }, fields: { ...fields }, direct: true });
-                }
-                else {
-                    const [from, payee, value, validAfter, validBefore, nonce, signature] = decodeFunctionData({ abi: erc3009Abi, data }).args;
-                    if (!isAddressEqual(from, m.principal))
-                        continue;
-                    const { pull, fields } = decodeMandateBlob(signature);
-                    const same = isAddressEqual(pull.to, payee) && pull.value === value && pull.validAfter === validAfter && pull.validBefore === validBefore && pull.nonce.toLowerCase() === nonce.toLowerCase();
-                    if (same)
-                        found.push({ pull, fields, direct: false });
-                }
-            }
-            catch {
-                // Not a call that starts here.
-            }
+            const [pull, fields] = call.args;
+            found.push({ pull: { ...pull }, fields: { ...fields } });
+        }
+        catch {
+            // Not a call that starts here.
         }
     }
     return found;
@@ -124,11 +103,10 @@ function carriedL3as(input, m) {
  * The candidate that is the outcome the event records: it rebuilds to the
  * recorded digest, moves the mandate's token, and its nonce commits to the
  * mandate and that digest (the L3a hashes neither the token nor the nonce,
- * so a copy with either changed is not it); among those, one carried the way
- * the event says (a pull, or a relayed authorisation) and signed by the agent
- * key comes first, so unrelated calldata with the same L3a (a no-op pull to
- * another address, a copy under another signature) cannot stand in for the
- * payment. One another mandate's terms cannot rebuild is not a candidate.
+ * so a copy with either changed is not it); among those, one signed by the
+ * agent key comes first, so unrelated calldata with the same L3a (a copy
+ * under another signature) cannot stand in for the payment. One another
+ * mandate's terms cannot rebuild is not a candidate.
  */
 function carriedL3a(input, chainId, m, o) {
     const rank = (c) => {
@@ -138,13 +116,13 @@ function carriedL3a(input, chainId, m, o) {
                 return 0;
             if (!isAddressEqual(c.pull.token, m.constraints.token) || mandateNonce(m.ref, l3a.digest) !== c.pull.nonce.toLowerCase())
                 return 0;
-            return 1 + (c.direct === o.direct ? 2 : 0) + (verifyL3aSignature(m.agentKey, l3a.digest, c.fields.r, c.fields.s) ? 1 : 0);
+            return 1 + (verifyL3aSignature(m.agentKey, l3a.digest, c.fields.r, c.fields.s) ? 1 : 0);
         }
         catch {
             return 0;
         }
     };
-    const candidates = carriedL3as(input, m);
+    const candidates = carriedL3as(input);
     let carried;
     let best = 0;
     for (const c of candidates) {
@@ -153,7 +131,7 @@ function carriedL3a(input, chainId, m, o) {
             [carried, best] = [c, r];
     }
     if (carried === undefined)
-        throw new Error(candidates.length === 0 ? "the transaction carries no pull on the principal and no ERC-3009 authorisation from it" : "no call the transaction carries rebuilds to the per-payment mandate the event records");
+        throw new Error(candidates.length === 0 ? "the transaction carries no pull on the principal" : "no pull the transaction carries rebuilds to the per-payment mandate the event records");
     return carried;
 }
 /**
@@ -208,7 +186,7 @@ async function boundMandate(client, principal, ref, factory, toBlock) {
     const agentKey = decodeAgentKey(log.args.agentKey);
     const problems = [];
     if (mandateReference(principal, agentKey, log.args.hashC).toLowerCase() !== ref.toLowerCase())
-        problems.push("the reference does not derive from the principal, the agent key and hash(C)");
+        problems.push("the reference does not derive from the principal, the mandate key and hash(C)");
     const revoked = events.find((e) => e.eventName === "MandateRevoked");
     const replaced = events.find((e) => e.eventName === "MandateReplaced");
     const revokedBlock = revoked?.blockNumber ?? undefined;
@@ -238,28 +216,26 @@ function outcomesOf(events, only) {
         if (log.blockNumber === null || log.transactionHash === null)
             continue;
         if (log.eventName === "MandatePayment") {
-            const { to, amount, l3aDigest, agentKey, direct, spent, occurrences } = log.args;
-            outcomes.push({ ...position(log), kind: "payment", txHash: log.transactionHash, block: log.blockNumber, to, amount, l3aDigest, agentKey, direct, spent, occurrences });
+            const { to, amount, l3aDigest, agentKey, spent, occurrences } = log.args;
+            outcomes.push({ ...position(log), kind: "payment", txHash: log.transactionHash, block: log.blockNumber, to, amount, l3aDigest, agentKey, spent, occurrences });
         }
         else if (log.eventName === "MandateRefused") {
             const { to, amount, l3aDigest, agentKey, reason } = log.args;
-            outcomes.push({ ...position(log), kind: "refusal", txHash: log.transactionHash, block: log.blockNumber, to, amount, l3aDigest, agentKey, direct: true, reason: reasonName(reason) });
+            outcomes.push({ ...position(log), kind: "refusal", txHash: log.transactionHash, block: log.blockNumber, to, amount, l3aDigest, agentKey, reason: reasonName(reason) });
         }
     }
     outcomes.sort((a, b) => before(a, b) ? -1 : before(b, a) ? 1 : 0);
     return only === undefined ? outcomes : outcomes.filter((o) => o.txHash.toLowerCase() === only.toLowerCase());
 }
 async function verifyOutcome(client, chainId, m, o, one) {
-    const verified = { kind: o.kind, txHash: o.txHash, block: o.block, direct: o.direct, to: o.to, amount: o.amount, ...(o.reason === undefined ? {} : { reason: o.reason }), problems: [] };
+    const verified = { kind: o.kind, txHash: o.txHash, block: o.block, to: o.to, amount: o.amount, ...(o.reason === undefined ? {} : { reason: o.reason }), problems: [] };
     const found = verified.problems;
     const agentKey = decodeAgentKey(o.agentKey);
     if (!sameAgentKey(agentKey, m.agentKey))
-        found.push("not the bound agent key");
+        found.push("not the bound mandate key");
     try {
         const [tx, block] = await Promise.all([client.getTransaction({ hash: o.txHash }), client.getBlock({ blockNumber: o.block })]);
-        const { pull, fields, direct } = carriedL3a(tx.input, chainId, m, o);
-        if (direct !== o.direct)
-            found.push(direct ? "recorded as relayed, carried as a pull" : "recorded as a pull, carried as a relayed authorisation");
+        const { pull, fields } = carriedL3a(tx.input, chainId, m, o);
         if (!isAddressEqual(pull.token, m.constraints.token))
             found.push("another token than the mandate's");
         const receipt = await client.getTransactionReceipt({ hash: o.txHash });
@@ -278,7 +254,7 @@ async function verifyOutcome(client, chainId, m, o, one) {
         if (mandateNonce(m.ref, l3a.digest) !== pull.nonce.toLowerCase())
             found.push("its nonce does not commit to the mandate and the per-payment mandate");
         if (!verifyL3aSignature(m.agentKey, l3a.digest, fields.r, fields.s))
-            found.push("not the bound agent key's signature");
+            found.push("not the bound mandate key's signature");
         if (!isAddressEqual(pull.to, o.to))
             found.push("another payee than the event records");
         if (pull.value !== o.amount)
@@ -341,7 +317,7 @@ async function verify(client, found, opts, only) {
         skip(4, "no binding to check against");
         return { ok: false, steps, payments: [] };
     }
-    record(1, found.problems, `${short(m.ref)} bound in block ${m.block} by ${m.principal}: hash(C) ${m.hashC}, issuer key ${m.issuerKey}, agent key ${short(encodeAgentKey(m.agentKey))}, ${m.terms.payees.length} payee(s)` +
+    record(1, found.problems, `${short(m.ref)} bound in block ${m.block} by ${m.principal}: hash(C) ${m.hashC}, issuer key ${m.issuerKey}, mandate key ${short(encodeAgentKey(m.agentKey))}, ${m.terms.payees.length} payee(s)` +
         `${m.revokedBlock === undefined ? "" : `, revoked in block ${m.revokedBlock}`}${m.successor === undefined ? "" : `, replaced by ${short(m.successor)}`}`);
     const c = opts.credential;
     let credentialIsBound = false;
@@ -357,7 +333,7 @@ async function verify(client, found, opts, only) {
                 const stated = extractTerms(c);
                 const differs = [
                     ["principal", isAddressEqual(stated.principal, m.principal)],
-                    ["agent key", sameAgentKey(stated.agentKey, m.agentKey)],
+                    ["mandate key", sameAgentKey(stated.agentKey, m.agentKey)],
                     ["limits", jcs(toJson(stated.constraints)) === jcs(toJson(m.constraints))],
                     ["payees", jcs(toJson(stated.terms)) === jcs(toJson(m.terms))],
                 ].filter(([, same]) => !same);
@@ -369,7 +345,7 @@ async function verify(client, found, opts, only) {
             }
         }
         credentialIsBound = problems.length === 0;
-        record(2, problems, "the credential hashes to the bound hash(C), and binds exactly the limits, payees and agent key it states");
+        record(2, problems, "the credential hashes to the bound hash(C), and binds exactly the limits, payees and mandate key it states");
     }
     if (c === undefined || !credentialIsBound)
         skip(3, c === undefined ? "no credential in hand" : "the credential in hand is not the bound one");
@@ -401,7 +377,7 @@ async function verify(client, found, opts, only) {
     if ((opts.requirements !== undefined || opts.checkoutMandate !== undefined) && outcomes.length > 1)
         problems.push("requirements or a signed offer given, but more than one payment to check them against");
     const paid = payments.filter((p) => p.kind === "payment").length;
-    record(4, problems, `${paid} payment(s) and ${payments.length - paid} refusal(s), each the bound agent key's per-payment mandate rebuilt byte for byte from its transaction, inside the mandate at its block`);
+    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`);
     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. */

package/dist/mandates/vi/credential.js

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

package/dist/node.d.ts

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

package/dist/node.js

@@ -0,0 +1,97 @@
+import { DatabaseSync } from "node:sqlite";
+import { mkdir, open, readFile, rename } from "node:fs/promises";
+import { join } from "node:path";
+import { randomBytes } from "node:crypto";
+import { createClearingSigner } from "./clearing-codec.js";
+/** A persistent P-256 account and receipt journal for a single server process. */
+export async function openClearingWallet(directory) {
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    // SQLite holds an OS lock for the wallet lifetime and releases it on crash.
+    const owner = new DatabaseSync(join(directory, "owner.sqlite"));
+    try {
+        owner.exec("PRAGMA locking_mode=EXCLUSIVE; BEGIN EXCLUSIVE; CREATE TABLE IF NOT EXISTS owner (id INTEGER)");
+    }
+    catch (error) {
+        owner.close();
+        throw new Error("clearing wallet is already in use", { cause: error });
+    }
+    try {
+        const keyPath = join(directory, "account.key");
+        let key;
+        try {
+            key = (await readFile(keyPath, "utf8")).trim();
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            for (;;) {
+                key = `0x${randomBytes(32).toString("hex")}`;
+                try {
+                    createClearingSigner(key);
+                    break;
+                }
+                catch {
+                    /* Rejection sample the scalar. */
+                }
+            }
+            const file = await open(keyPath, "wx", 0o600);
+            try {
+                await file.writeFile(key);
+                await file.sync();
+            }
+            finally {
+                await file.close();
+            }
+        }
+        const parent = await open(directory, "r");
+        try {
+            await parent.sync();
+        }
+        finally {
+            await parent.close();
+        }
+        const signer = createClearingSigner(key);
+        const statePath = join(directory, "payments.json");
+        const store = {
+            async load() {
+                try {
+                    return JSON.parse(await readFile(statePath, "utf8"));
+                }
+                catch (error) {
+                    if (error.code === "ENOENT")
+                        return null;
+                    throw error;
+                }
+            },
+            async save(state) {
+                const file = await open(statePath + ".next", "w", 0o600);
+                try {
+                    await file.writeFile(JSON.stringify(state));
+                    await file.sync();
+                }
+                finally {
+                    await file.close();
+                }
+                await rename(statePath + ".next", statePath);
+                const parent = await open(directory, "r");
+                try {
+                    await parent.sync();
+                }
+                finally {
+                    await parent.close();
+                }
+            },
+        };
+        return {
+            signer,
+            store,
+            async close() {
+                owner.close();
+            },
+        };
+    }
+    catch (error) {
+        owner.close();
+        throw error;
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@metalntwx/metal-pay",
-  "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.",
+  "version": "0.3.0",
+  "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": {
     "type": "git",
@@ -9,6 +9,9 @@
     "directory": "sdks/metal-pay"
   },
   "type": "module",
+  "engines": {
+    "node": "^22.13.0 || >=23.4.0"
+  },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -16,9 +19,9 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
-    "./file-storage": {
-      "types": "./dist/file-storage.d.ts",
-      "default": "./dist/file-storage.js"
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "default": "./dist/node.js"
     },
     "./mandates": {
       "types": "./dist/mandates/index.d.ts",
@@ -26,21 +29,25 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "dependencies": {
-    "@noble/curves": "^1.9.1",
-    "@x402/core": "^2.21.0",
-    "@x402/evm": "^2.21.0",
-    "@x402/fetch": "^2.21.0"
+    "@noble/curves": "1.9.7"
   },
   "peerDependencies": {
+    "@x402/core": ">=2.28.0 <3",
+    "@x402/evm": ">=2.28.0 <3",
+    "@x402/fetch": ">=2.28.0 <3",
     "viem": "^2"
   },
   "devDependencies": {
     "@metalntwx/metal-ts": "0.3.2",
     "@types/node": "^24.13.2",
-    "@x402/hono": "2.21.0",
+    "@x402/core": "2.28.0",
+    "@x402/evm": "2.28.0",
+    "@x402/fetch": "2.28.0",
+    "@x402/hono": "2.28.0",
     "hono": "4.13.7",
     "tsx": "^4.23.0",
     "typescript": "~6.0.2",