@metalntwx/metal-agent 0.2.0 → 0.3.0

package/dist/commands/mandate.js

@@ -1,18 +1,20 @@
 // `mandate …`: the limits an account's owner sets for an agent, enforced by
-// Metal. The owner (the principal) issues a credential naming the agent's
-// P-256 key, the most per payment, a budget, an expiry and any payees, then
+// Metal. The owner (the principal) issues a credential naming the mandate
+// key, the most per payment, a budget, an expiry and any payees, then
 // binds it through the weighted quorum of its MetalAccount.
-// From then on the agent pays from that account with its own key alone, and
+// From then on the agent pays from that account with its mandate key alone, and
 // Mandate Binding refuses anything outside the mandate. Every command takes
 // the credential file: the account, the mandate's reference and its terms all
 // derive from it.
-import { readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { link, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
-import { FEE_PER_GAS, assertMetalAccount, authorizeMandateCall, metalAccountFactoryAbi, MANDATE_MAX_VALIDITY_SECONDS, MANDATE_VALID_AFTER_LEAD_SECONDS, REFUSALS, UNCAPPED_OCCURRENCES, agentKeyOfJwk, bindCall, createCredential, describeRefusal, encodeAgentKey, extractTerms, hashCredential, ingestCredential, mandateBindingAbi, mandateReference, p256DigestSigner, parseCredential, privateKeyHex, publicMessage, pullCall, readBoundAgentKey, readCheck, readMandateState, reasonName, replaceCall, revokeCall, sameAgentKey, sendMandateCall, signL3a, transactionIdOf, trustedIssuer, verifyMandate, verifyMandatePayment, } from "@metalntwx/metal-pay/mandates";
+import { FEE_PER_GAS, assertMetalAccount, authorizeMandateCall, metalAccountFactoryAbi, MANDATE_MAX_VALIDITY_SECONDS, MANDATE_VALID_AFTER_LEAD_SECONDS, REFUSALS, UNCAPPED_OCCURRENCES, agentKeyOfJwk, bindCall, createCredential, encodeMandateBlob, describeRefusal, encodeAgentKey, extractTerms, hashCredential, ingestCredential, mandateBindingAbi, mandateReference, p256DigestSigner, parseCredential, privateKeyHex, publicMessage, pullCall, readBoundAgentKey, readCheck, readMandateState, reasonName, replaceCall, revokeCall, sameAgentKey, sendMandateCall, signL3a, transactionIdOf, trustedIssuer, verifyMandate, verifyMandatePayment, } from "@metalntwx/metal-pay/mandates";
 import { USDZ, formatUsdz, usdzBaseUnits } from "@metalntwx/metal-pay";
-import { BaseError, HttpRequestError, TimeoutError, createWalletClient, custom, decodeErrorResult, encodeFunctionData, encodeAbiParameters, parseAbiParameters, getAddress, isAddress, isAddressEqual, isHash, parseEventLogs, slice, } from "viem";
+import { BaseError, erc20Abi, getAbiItem, parseAbi, parseAbiItem, HttpRequestError, TimeoutError, createWalletClient, custom, decodeErrorResult, encodeFunctionData, encodeAbiParameters, parseAbiParameters, getAddress, isAddress, isAddressEqual, isHash, parseEventLogs, slice, } from "viem";
 import { rpcClient } from "../chain.js";
-import { agentKeyPath, exists, gasKeyPath, publicKeyPath, readKey, readOrCreateIssuerKeys, readOrCreateKey, readOrCreateP256Key, readP256Key, readTrustedIssuer, writePublicKeyFile, } from "../keystore.js";
+import { fund } from "./fund.js";
+import { exists, mandateKeyPath, pendingPullsPath, publicKeyPath, readKey, readOrCreateIssuerKeys, readOrCreateKey, readOrCreateP256Key, readP256Key, readTrustedIssuer, writePublicKeyFile, } from "../keystore.js";
 export async function loadMandate(credentialPath) {
     const credential = parseCredential(JSON.parse(await readFile(credentialPath, "utf8")));
     const terms = extractTerms(credential);
@@ -60,16 +62,20 @@ export function parseCount(text, option) {
 const usdz = (units) => `${formatUsdz(units)} ${USDZ.symbol}`;
 const utc = (seconds) => new Date(Number(seconds) * 1000).toISOString();
 const day = (seconds) => new Date(seconds * 1000).toISOString().slice(0, 10);
+/**
+ * Text from a credential or a facilitator is shown with control, line-separator, bidi and invisible characters replaced, so it cannot
+ * start a line, reorder one or hide text; the joiners scripts and emoji need are kept.
+ */
+const UNSHOWN = /[\p{Cc}\p{Zl}\p{Zp}\u061c\u200b\u200e\u200f\u202a-\u202e\u2060\u2066-\u2069\ufeff\u{e0000}-\u{e007f}]/gu;
 function printTerms({ principal, agentKey, constraints: c, terms, descriptive }, print) {
-    // The credential's own text is shown with control, line-separator, bidi and invisible characters replaced, so it cannot start a line,
-    // reorder one or hide text; the joiners scripts and emoji need are kept.
     if (typeof descriptive.promptSummary === "string")
-        print(`description ${descriptive.promptSummary.replace(/[\p{Cc}\p{Zl}\p{Zp}\u061c\u200b\u200e\u200f\u202a-\u202e\u2060\u2066-\u2069\ufeff\u{e0000}-\u{e007f}]/gu, "?")}`);
+        print(`description ${descriptive.promptSummary.replace(UNSHOWN, "?")}`);
     print(`principal ${principal}`);
-    print(`agent-key ${encodeAgentKey(agentKey)} (P-256)`);
+    print(`mandate-key ${encodeAgentKey(agentKey)} (P-256)`);
     print(`token ${c.token}`);
     print(`per-payment-cap ${usdz(c.perPaymentCap)}`);
     print(`budget ${usdz(c.budget)} until expiry`);
+    print(`starts ${c.recurrenceStart} (${utc(c.recurrenceStart)})`);
     print(`expiry ${c.expiry} (${utc(c.expiry)})`);
     if (c.maxOccurrences !== UNCAPPED_OCCURRENCES)
         print(`max-occurrences ${c.maxOccurrences}`);
@@ -80,7 +86,7 @@ function printTerms({ principal, agentKey, constraints: c, terms, descriptive },
         const object = shown.find((o) => typeof o.id === "string" && o.id.toLowerCase() === payee.account.toLowerCase());
         const name = typeof object?.name === "string" && object.name.toLowerCase() !== payee.account.toLowerCase() ? ` ${object.name}` : "";
         const website = typeof object?.website === "string" && /^https?:/.test(object.website) ? ` ${object.website}` : "";
-        print(`payee ${payee.account}${name}${website}`.replace(/[\p{Cc}\p{Zl}\p{Zp}\u061c\u200b\u200e\u200f\u202a-\u202e\u2060\u2066-\u2069\ufeff\u{e0000}-\u{e007f}]/gu, "?"));
+        print(`payee ${payee.account}${name}${website}`.replace(UNSHOWN, "?"));
     }
 }
 function walletFor(publicClient, account) {
@@ -105,25 +111,27 @@ function printSent(target, receipt, print) {
 }
 /**
  * Issues the credential a mandate is bound from, the developer signing it as
- * its own issuer; with no payees it lets the agent pay any address within
- * the other limits. The agent's keys are written beside the credential unless
- * `--agent-key` names a mandate key it already has: the mandate key, and the
- * key that pays for its pulls beside that. The issuer's keys are created on
- * first use. The budget covers the credential's whole life, from now to its
- * expiry.
+ * its own issuer; with no payees it lets the agent pay any address within the
+ * other limits. The mandate key it names is written beside the credential,
+ * unless `mandateKeyFile` names one that exists. The issuer's keys are
+ * created on first use. The budget covers the credential's whole life, from
+ * now to its expiry.
  */
 export async function credentialCreate(target, args, print) {
     if (await exists(args.out))
         throw new Error(`${args.out} already exists; pass another --out`);
-    const agentPath = args.agentKeyPath ?? agentKeyPath(args.out);
-    if (args.agentKeyPath === undefined && (await exists(agentPath))) {
-        throw new Error(`${agentPath} already holds a key; pass --agent-key ${agentPath} to name it, or another --out`);
+    if (args.startsIn !== undefined && args.startsIn >= args.expiresIn)
+        throw new Error(`--starts-in must be less than --expires-in, ${args.expiresIn} seconds`);
+    const keyPath = args.mandateKeyFile ?? mandateKeyPath(args.out);
+    if (args.mandateKeyFile === undefined && (await exists(keyPath))) {
+        throw new Error(`${keyPath} already holds a key; pass --mandate-key-file ${keyPath} to name it, or another --out`);
     }
-    const agent = await readOrCreateP256Key(agentPath);
-    const gasPath = gasKeyPath(agentPath);
-    const gas = await readOrCreateKey(gasPath);
+    if (args.mandateKeyFile !== undefined && !(await exists(keyPath)))
+        throw new Error(`no mandate key at ${keyPath}; pass --mandate-key-file with a mandate-key-file credential create printed`);
+    const mandateKey = await readOrCreateP256Key(keyPath);
     const { keys, created } = await readOrCreateIssuerKeys(args.issuerKeyPath).catch(async (error) => {
-        await Promise.all([agent.created && rm(agentPath), gas.created && rm(gasPath)]);
+        if (mandateKey.created)
+            await rm(keyPath);
         throw error;
     });
     const now = Math.floor(Date.now() / 1000);
@@ -135,13 +143,13 @@ export async function credentialCreate(target, args, print) {
             issuer: keys.issuer,
             principal: args.principal,
             principalKey: keys.principalKey,
-            agentKey: agent.key.publicJwk,
+            agentKey: mandateKey.key.publicJwk,
             perPaymentCap: args.cap,
             budget: args.budget,
             payees: args.payees.map(({ address, name, website }) => ({ address, name: name ?? address, website: website ?? `eip155:${target.network.chainId}:${address}` })),
             recurrence: {
                 frequency: "ADHO",
-                startDate: day(now),
+                startDate: args.startsIn === undefined ? day(now) : new Date((now + args.startsIn) * 1000).toISOString().replace(".000Z", "Z"),
                 endDate: day(expiresAt),
                 ...(args.maxOccurrences !== undefined && { maxOccurrences: args.maxOccurrences }),
             },
@@ -153,18 +161,16 @@ export async function credentialCreate(target, args, print) {
     }
     catch (error) {
         // The keys this run created name nothing yet; removing them lets the corrected command run again.
-        await Promise.all([agent.created && rm(agentPath), gas.created && rm(gasPath), created && rm(args.issuerKeyPath)]);
+        await Promise.all([mandateKey.created && rm(keyPath), created && rm(args.issuerKeyPath)]);
         throw error;
     }
     await writeFile(args.out, `${JSON.stringify(credential, null, 2)}\n`, { flag: "wx" });
     const issuerPublicPath = publicKeyPath(args.issuerKeyPath);
     await writePublicKeyFile(issuerPublicPath, trustedIssuer(keys.issuer));
     print(`credential ${args.out}`);
-    print(`reference ${ingested.reference}`);
+    print(`mandate ${ingested.reference}`);
     printTerms(ingested.extracted, print);
-    print(`agent-key-file ${agentPath}${agent.created ? " (created)" : ""}`);
-    print(`gas-key-file ${gasPath}${gas.created ? " (created)" : ""}`);
-    print(`gas-key-address ${gas.address}`);
+    print(`mandate-key-file ${keyPath}${mandateKey.created ? " (created)" : ""}`);
     print(`issuer-key-file ${args.issuerKeyPath}${created ? " (created)" : ""}`);
     print(`issuer-public-file ${issuerPublicPath}`);
 }
@@ -185,29 +191,45 @@ async function ingestFor(args) {
 /** The one-owner account `owner` controls: its config for the factory, and the address the factory gives it. */
 async function ownerAccount(client, factory, owner) {
     const config = [[owner], [1n], 1n];
-    const factoryCode = await client.getCode({ address: factory });
-    if (factoryCode === undefined || factoryCode === "0x")
+    if (!(await hasCode(client, factory)))
         throw new Error(`no MetalAccountFactory at ${factory}; on a devnet run just deploy, or pass --factory`);
     const address = await client.readContract({ address: factory, abi: metalAccountFactoryAbi, functionName: "predictAccount", args: config });
     return { config, address };
 }
-/** Names the owner's one-owner MetalAccount, writing the owner's key first when
- * `out` names a file to create; the factory gives each owner one address, and
- * the account is created on chain by the owner's first `bind`. Mixed-key and
- * weighted accounts use the same factory through the SDK. */
+/** Creates the owner's one-owner MetalAccount on chain, writing the owner's
+ * key first when `out` names a file to create. The factory gives each owner
+ * one address, so an account that exists is named and nothing is sent. An
+ * owner with no gas is funded first, from the faucet on testnet. Mixed-key
+ * and weighted accounts use the same factory through the SDK. */
 export async function accountCreate(target, args, print) {
     const keyPath = "keyPath" in args ? args.keyPath : args.out;
     const created = "out" in args ? (await readOrCreateKey(args.out)).created : false;
     const owner = await readKey(keyPath);
     const client = rpcClient(target);
-    const { address } = await ownerAccount(client, args.accountFactory, owner.address);
-    const code = await client.getCode({ address });
+    const { config, address } = await ownerAccount(client, args.accountFactory, owner.address);
     print(`account ${address}`);
-    print(`deployed ${code === undefined || code === "0x" ? "no, the first bind creates it" : "yes"}`);
     print(`owner ${owner.address}`);
     print(`keyfile ${keyPath}${created ? " (created)" : ""}`);
+    if (await hasCode(client, address)) {
+        print("deployed yes");
+        return;
+    }
+    if ((await client.getBalance({ address: owner.address })) === 0n) {
+        // Only the grant's summary: its transaction lines would read as the account's.
+        const funding = [];
+        await fund(target, owner.address, undefined, (line) => funding.push(line));
+        if (funding[0] !== undefined)
+            print(funding[0]);
+    }
+    const receipt = await send(client, owner, { to: args.accountFactory, data: encodeFunctionData({ abi: metalAccountFactoryAbi, functionName: "createAccount", args: config }), gas: 600000n, maxFeePerGas: FEE_PER_GAS, maxPriorityFeePerGas: FEE_PER_GAS });
+    print("deployed yes");
+    printSent(target, receipt, print);
+}
+async function hasCode(client, address) {
+    const code = await client.getCode({ address });
+    return code !== undefined && code !== "0x";
 }
-async function sendOwnerCall(client, args, call, createAccount = false) {
+async function sendOwnerCall(client, args, call) {
     const account = (Array.isArray(call) ? call[0] : call)?.to;
     if (account === undefined)
         throw new Error("no account call to send");
@@ -216,18 +238,11 @@ async function sendOwnerCall(client, args, call, createAccount = false) {
     signers.sort((a, b) => a.address.toLowerCase().localeCompare(b.address.toLowerCase()));
     if (new Set(signers.map(s => s.address.toLowerCase())).size !== signers.length)
         throw new Error("duplicate account signer");
-    // A one-owner account is created by its owner's first bind; the sponsor pays.
-    // One with several signers is created by the factory beforehand, with its
-    // signers, weights and threshold, which these key files alone do not name.
-    const code = createAccount ? await client.getCode({ address: account }) : "0x01";
-    if ((code === undefined || code === "0x") && args.signerPaths.length > 0) {
-        throw new Error(`${account} has no code: create the account first, through MetalAccountFactory.createAccount with its signers, weights and threshold; only a one-owner account is created by its owner's first bind`);
-    }
-    if (code === undefined || code === "0x") {
-        const { config, address } = await ownerAccount(client, args.accountFactory, sponsor.address);
-        if (address.toLowerCase() !== account.toLowerCase())
-            throw new Error(`${account} is not the account of ${sponsor.address}; it has no code, and only its owner's first bind creates it`);
-        await send(client, sponsor, { to: args.accountFactory, data: encodeFunctionData({ abi: metalAccountFactoryAbi, functionName: "createAccount", args: config }), gas: 600000n, maxFeePerGas: FEE_PER_GAS, maxPriorityFeePerGas: FEE_PER_GAS });
+    if (!(await hasCode(client, account))) {
+        const own = signers.length === 1 && isAddressEqual(signers[0].address, sponsor.address) && isAddressEqual((await ownerAccount(client, args.accountFactory, sponsor.address)).address, account);
+        if (own)
+            throw new Error(`${account} has no account: create it with metal-agent account create`);
+        throw new Error(`${account} has no account, and is not ${sponsor.address}'s one-owner account: create it through MetalAccountFactory.createAccount with its owners, weights and threshold`);
     }
     const authorized = await authorizeMandateCall(client, args.accountFactory, call, async (digest) => encodeAbiParameters(parseAbiParameters("bytes[], bytes[]"), [signers.map(s => s.address), await Promise.all(signers.map(s => s.sign({ hash: digest })))]));
     return send(client, sponsor, authorized);
@@ -235,7 +250,7 @@ async function sendOwnerCall(client, args, call, createAccount = false) {
 export async function mandateBind(target, args, print) {
     const { ingested } = await ingestFor(args);
     const publicClient = rpcClient(target);
-    const receipt = await sendOwnerCall(publicClient, args, bindCall(ingested), true);
+    const receipt = await sendOwnerCall(publicClient, args, bindCall(ingested));
     print(`bound ${ingested.reference}`);
     printSent(target, receipt, print);
 }
@@ -297,11 +312,10 @@ export async function mandateRevoke(target, args, print) {
 export async function mandateStatus(target, credentialPath, accountFactory, print) {
     const { terms, reference } = await loadMandate(credentialPath);
     const publicClient = rpcClient(target);
-    print(`reference ${reference}`);
+    print(`mandate ${reference}`);
     printTerms(terms, print);
-    const code = await publicClient.getCode({ address: terms.principal });
-    if (code === undefined || code === "0x") {
-        print("account-type none yet; the owner's first bind creates it");
+    if (!(await hasCode(publicClient, terms.principal))) {
+        print("account-type none; create the account before binding: metal-agent account create for one owner");
         print("bound no");
         return;
     }
@@ -319,7 +333,7 @@ export async function mandateStatus(target, credentialPath, accountFactory, prin
 /**
  * Verifies the mandate and its payments from the chain alone: the binding on
  * the principal's account, the credential against it and under its issuer,
- * and each payment and refusal as the agent key's own per-payment mandate,
+ * and each payment and refusal as the mandate key's own per-payment mandate,
  * rebuilt from the transaction that carried it. Any party holding the
  * credential can run it; Metal is not asked.
  */
@@ -332,36 +346,47 @@ export async function mandateVerify(target, args, print) {
     const v = args.tx === undefined
         ? await verifyMandate(publicClient, opts)
         : await verifyMandatePayment(publicClient, { ...opts, tx: args.tx, ...(args.signedOffer === undefined ? {} : { checkoutMandate: args.signedOffer }) });
-    print(`reference ${reference}`);
+    print(`mandate ${reference}`);
     for (const step of v.steps) {
         print(`step ${step.step} ${step.outcome}: ${step.title}`);
         print(`  ${step.detail}`);
     }
     for (const p of v.payments) {
         const what = p.kind === "payment" ? "payment" : `refusal (${p.reason === undefined || p.reason === "None" ? "?" : REFUSALS[p.reason].reason})`;
-        const how = p.direct ? "pull" : `nonce ${p.nonce ?? "?"}`;
-        print(`${what} ${p.txHash} block ${p.block}: ${usdz(p.amount)} to ${p.to}, ${how}${p.problems.length === 0 ? "" : `: ${p.problems.join(", ")}`}`);
+        print(`${what} ${p.txHash} block ${p.block}: ${usdz(p.amount)} to ${p.to}, nonce ${p.nonce ?? "?"}${p.problems.length === 0 ? "" : `: ${p.problems.join(", ")}`}`);
     }
     print(`verified ${v.ok ? "yes" : "no"}`);
     return v.ok ? "verified" : "failed";
 }
-/** The agent's P-256 key, checked to be the one the mandate names. */
-export async function mandateAgentSigner(mandate, agentKeyPath) {
-    const agent = await readP256Key(agentKeyPath).catch(async (error) => {
-        if (error.code !== "ENOENT")
-            throw error;
-        // A replacement credential names the agent key it was made with, which sits beside the first credential.
-        const dir = dirname(agentKeyPath);
-        for (const file of (await readdir(dir)).filter((name) => name.endsWith(".agent-key.json"))) {
-            const key = await readP256Key(join(dir, file)).catch(() => undefined);
-            if (key && sameAgentKey(agentKeyOfJwk(key.publicJwk), mandate.terms.agentKey))
-                throw new Error(`no agent key at ${agentKeyPath}; this mandate's agent key is ${join(dir, file)}: pass --agent-key ${join(dir, file)}`);
-        }
-        throw new Error(`no agent key at ${agentKeyPath}; pass --agent-key with the agent-key-file that credential create printed for it`);
-    });
-    if (!sameAgentKey(agentKeyOfJwk(agent.publicJwk), mandate.terms.agentKey))
-        throw new Error(`${agentKeyPath} is not the mandate's agent key`);
-    return p256DigestSigner(privateKeyHex(agent));
+/**
+ * Signs with the mandate's key: `keyFile` when given, or else the key file in
+ * the credential's directory that the credential names, so a replacement
+ * written beside its predecessor signs with the predecessor's key.
+ */
+export async function mandateAgentSigner(mandate, credentialPath, keyFile) {
+    const names = (key) => sameAgentKey(agentKeyOfJwk(key.publicJwk), mandate.terms.agentKey);
+    if (keyFile !== undefined) {
+        const key = await readP256Key(keyFile).catch((error) => {
+            throw error.code === "ENOENT" ? new Error(`no mandate key at ${keyFile}; pass --mandate-key-file with the mandate-key-file credential create printed`) : error;
+        });
+        if (!names(key))
+            throw new Error(`${keyFile} is not this mandate's key`);
+        return p256DigestSigner(privateKeyHex(key));
+    }
+    const dir = dirname(credentialPath);
+    const own = mandateKeyPath(credentialPath);
+    const beside = (await readdir(dir).catch(() => [])).filter((name) => name.endsWith(".key.json")).map((name) => join(dir, name));
+    for (const path of [own, ...beside.filter((path) => path !== own)]) {
+        // The credential's own key file must read; another file that is not a P-256 key is not this mandate's.
+        const key = await readP256Key(path).catch((error) => {
+            if (path === own && error.code !== "ENOENT")
+                throw error;
+            return undefined;
+        });
+        if (key && names(key))
+            return p256DigestSigner(privateKeyHex(key));
+    }
+    throw new Error(`no key beside ${credentialPath} is this mandate's; pass --mandate-key-file with the mandate-key-file credential create printed`);
 }
 /** A revert's Mandate Binding error name (`NonceAlreadyUsed`, `BadAgentSignature`, …), or the node's message. */
 function revertName(error) {
@@ -379,81 +404,355 @@ function revertName(error) {
     return error.shortMessage;
 }
 /**
- * A direct payment under the mandate, with no seller: the agent signs it and
- * the `--key` account submits it to `pull` on the principal's account and
- * pays the gas. One the mandate refuses when checked is reported and not
- * sent, as an x402 payment is refused before anything is sent, unless
- * `recordRefusal` asks for Mandate Binding to record the refusal on chain.
- * The transaction is printed as soon as it is sent, so a pull whose receipt
- * is lost is still found. The outcome is returned so a refusal can fail the
- * command.
+ * A direct payment under the mandate, with no seller: the agent signs it, and
+ * the facilitator, or the `--key` account, submits it to `pull` on the
+ * principal's account and pays the gas. One the mandate refuses when checked
+ * is reported and not sent, unless `recordRefusal` asks for Mandate Binding to
+ * record the refusal on chain.
+ *
+ * A pull that has left can land until its window ends, whatever the
+ * facilitator answers, so its outcome is read from the chain alone. One with
+ * no outcome yet is kept beside the credential, and the same command sends
+ * that same pull again, which the account pays at most once; once it can no
+ * longer land, the command signs a new one.
  */
 export async function mandatePull(target, args, print) {
     const mandate = await loadMandate(args.credentialPath);
-    const signDigest = await mandateAgentSigner(mandate, args.agentKeyPath);
-    const sender = await readKey(args.keyPath).catch((error) => {
-        if (error.code === "ENOENT")
-            throw new Error(`no key at ${args.keyPath} to submit the pull and pay its gas; pass --key <funded key file>`);
-        throw error;
-    });
+    const signDigest = await mandateAgentSigner(mandate, args.credentialPath, args.mandateKeyFile);
+    const keyPath = args.keyPath;
+    if (args.recordRefusal && keyPath === undefined)
+        throw new Error("--record-refusal sends the refused pull itself: pass --key <funded key file> to submit it and pay its gas");
+    const facilitatorProtocol = URL.canParse(target.facilitatorUrl) ? new URL(target.facilitatorUrl).protocol : "";
+    if (keyPath === undefined && facilitatorProtocol !== "http:" && facilitatorProtocol !== "https:") {
+        throw new Error(`the facilitator URL ${target.facilitatorUrl} is not an http or https URL, so the pull was not sent`);
+    }
+    const sender = keyPath === undefined
+        ? undefined
+        : await readKey(keyPath).catch((error) => {
+            if (error.code === "ENOENT")
+                throw new Error(`no key at ${keyPath} to submit the pull and pay its gas; pass --key <funded key file>, or leave it out and the facilitator submits the pull`);
+            throw error;
+        });
     const { terms, reference } = mandate;
     const publicClient = rpcClient(target);
     // A mandate not yet bound, or before its dates, can stop refusing; these are
     // checked before the agent signs, so a pull reported unsent can never pay later.
     const [bound, block, gas] = await Promise.all([
-        publicClient.getCode({ address: terms.principal }).then((code) => (code === undefined || code === "0x" ? undefined : readBoundAgentKey(publicClient, terms.principal, reference))),
+        hasCode(publicClient, terms.principal).then((deployed) => (deployed ? readBoundAgentKey(publicClient, terms.principal, reference) : undefined)),
         publicClient.getBlock(),
-        publicClient.getBalance({ address: sender.address }),
+        sender === undefined ? undefined : publicClient.getBalance({ address: sender.address }),
     ]);
     if (bound === undefined)
         throw new Error(`the mandate ${reference} is not bound on ${terms.principal}; the owner binds it with mandate bind`);
-    if (block.timestamp < terms.constraints.recurrenceStart && !args.recordRefusal)
-        return printUnsent("OutsideRecurrence", print);
-    if (gas === 0n)
-        throw new Error(`${sender.address}, which submits the pull, holds no gas: fund it, the gas-key-address credential create printed, and run the pull again`);
-    const chainId = target.network.chainId;
-    const now = BigInt(Math.floor(Date.now() / 1000));
-    const signed = await signL3a({
-        chainId,
-        ref: reference,
-        token: terms.constraints.token,
-        terms: terms.terms,
-        to: args.to,
-        value: args.amount,
-        validAfter: now - BigInt(MANDATE_VALID_AFTER_LEAD_SECONDS),
-        validBefore: now + BigInt(MANDATE_MAX_VALIDITY_SECONDS),
-        transactionId: transactionIdOf({
+    if (sender !== undefined && gas === 0n)
+        throw new Error(`${sender.address}, which submits the pull, holds no gas: fund it, or leave out --key and the facilitator submits the pull`);
+    const keptPath = join(pendingPullsPath(args.credentialPath), `${reference}-${args.to.toLowerCase()}-${args.amount}`);
+    const end = await chainEnd(keptPath);
+    let attempt;
+    // The pull a new one follows in the chain; the chain's first when there is none.
+    let follows;
+    let checked;
+    if (end !== undefined && (await exists(join(keptPath, `${end.pull.nonce}.done`)))) {
+        // Its outcome is reported: this is a new payment.
+        follows = end.pull.nonce;
+    }
+    else if (end !== undefined) {
+        attempt = end;
+        const { pull } = attempt;
+        if (!isAddressEqual(pull.to, args.to) || pull.value !== args.amount || !isAddressEqual(pull.token, terms.constraints.token) || slice(pull.nonce, 0, 12) !== slice(reference, 0, 12)) {
+            throw new Error(`${keptPath} holds a pull for another payment than this mandate's ${usdz(args.amount)} to ${args.to}`);
+        }
+        const found = await outcomeOnChain(publicClient, terms, attempt);
+        if (found.kind === "landed")
+            return settle(keptPath, attempt, printPull(target, terms, attempt.pull, found.receipt, print));
+        if (found.kind === "open" && found.landed)
+            return printPending(print, "it has landed, and its log cannot be read yet", attempt, keptPath);
+        // One that can never land is followed by a new pull, signed and checked below.
+        if (found.kind === "never") {
+            follows = attempt.pull.nonce;
+            attempt = undefined;
+        }
+    }
+    if (attempt === undefined) {
+        if (block.timestamp < terms.constraints.recurrenceStart && !args.recordRefusal)
+            return printUnsent("OutsideRecurrence", print);
+        const now = BigInt(Math.floor(Date.now() / 1000));
+        // What a seller's offer would be; the facilitator settles the pull against it.
+        const requirements = {
             scheme: "exact",
-            network: `eip155:${chainId}`,
+            network: `eip155:${target.network.chainId}`,
             amount: args.amount.toString(),
             asset: terms.constraints.token,
             payTo: args.to,
             maxTimeoutSeconds: MANDATE_MAX_VALIDITY_SECONDS,
-        }),
-        iss: terms.terms.kid,
-        signDigest,
+        };
+        const signed = await signL3a({
+            chainId: target.network.chainId,
+            ref: reference,
+            token: terms.constraints.token,
+            terms: terms.terms,
+            to: args.to,
+            value: args.amount,
+            validAfter: now - BigInt(MANDATE_VALID_AFTER_LEAD_SECONDS),
+            validBefore: now + BigInt(MANDATE_MAX_VALIDITY_SECONDS),
+            transactionId: transactionIdOf(requirements),
+            iss: terms.terms.kid,
+            signDigest,
+        });
+        const fresh = { pull: signed.pull, fields: signed.fields, requirements, fromBlock: block.number };
+        const reason = await readCheck(publicClient, terms.principal, fresh.pull, fresh.fields);
+        if (reason !== "None" && !args.recordRefusal)
+            return printUnsent(reason, print);
+        await simulatePull(publicClient, terms, fresh, sender);
+        checked = fresh.pull.nonce;
+        // Kept before it leaves: from here on it can land, and the same command sends it again.
+        // A run that kept one first wins, and this run sends that one.
+        attempt = await keepFirst(join(keptPath, follows === undefined ? "first.json" : `${follows}.next.json`), fresh);
+    }
+    if (attempt.pull.nonce !== checked) {
+        const rejected = await simulatePull(publicClient, terms, attempt, sender).then(() => undefined, (error) => error);
+        if (rejected !== undefined) {
+            // A pull another run kept, or one kept before, can have landed since it was read.
+            const found = await outcomeOnChain(publicClient, terms, attempt);
+            if (found.kind === "landed") {
+                return settle(keptPath, attempt, printPull(target, terms, attempt.pull, found.receipt, print));
+            }
+            if (found.kind === "open" && found.landed)
+                return printPending(print, "it has landed, and its log cannot be read yet", attempt, keptPath);
+            throw rejected;
+        }
+    }
+    const call = pullCall(terms.principal, attempt.pull, attempt.fields);
+    const sent = sender === undefined ? await sendToFacilitator(target, terms, attempt) : await sendFromKey(publicClient, sender, call);
+    if (sent.kind === "unsent")
+        throw new Error(`the pull was not sent: ${sent.cause}; it is kept at ${keptPath}, and the same command sends it`);
+    const found = await outcomeOnChain(publicClient, terms, attempt, sent.transaction);
+    if (found.kind === "landed") {
+        return settle(keptPath, attempt, printPull(target, terms, attempt.pull, found.receipt, print));
+    }
+    if (found.kind === "never") {
+        print("outcome refused, not paid");
+        print(`reason ${describeRefusal(found.reason)}`);
+        return settle(keptPath, attempt, "refused");
+    }
+    // A transaction whose receipt was read and does not carry this pull is not named as its.
+    if (sent.transaction !== undefined && found.unreadReceipt)
+        print(`transaction ${sent.transaction}`);
+    if (found.landed)
+        return printPending(print, "it has landed, and its log cannot be read yet", attempt, keptPath);
+    return printPending(print, found.unread === undefined ? sent.why : `${sent.why}; the chain could not be read: ${found.unread}`, attempt, keptPath);
+}
+/**
+ * Marks a kept pull's outcome reported once it is printed, so the same
+ * command makes a new payment next; a run killed between the two leaves it
+ * for the next run to report.
+ */
+async function settle(keptPath, kept, outcome) {
+    await writeFile(join(keptPath, `${kept.pull.nonce}.done`), "", { flag: "wx", mode: 0o600 }).catch((error) => {
+        if (error.code !== "EEXIST")
+            throw error;
+    });
+    return outcome;
+}
+/**
+ * The last pull in a payee and amount's chain: its first, then each pull kept
+ * after one that can never land or whose outcome is reported. Pulls are only
+ * ever added to a chain, each once, so runs at once read the same end.
+ */
+async function chainEnd(keptPath) {
+    let kept = await readKept(join(keptPath, "first.json"));
+    for (let next = kept; next !== undefined; next = await readKept(join(keptPath, `${next.pull.nonce}.next.json`)))
+        kept = next;
+    return kept;
+}
+function printPending(print, reason, kept, keptPath) {
+    print("outcome pending");
+    print(`reason ${reason.replace(UNSHOWN, "?").slice(0, 300)}`);
+    print(`can-land-until ${utc(kept.pull.validBefore)}`);
+    print(`kept ${keptPath}: run the same command again to send the same pull, which pays at most once`);
+    return "pending";
+}
+const BIGINTS = ["value", "validAfter", "validBefore", "fromBlock"];
+async function readKept(path) {
+    const text = await readFile(path, "utf8").catch((error) => {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
     });
-    const call = pullCall(terms.principal, signed.pull, signed.fields);
+    if (text === undefined)
+        return undefined;
     try {
-        // At the node's own gas ceiling: what the pull costs is sendMandateCall's to estimate.
-        await publicClient.call({ account: sender.address, to: call.to, data: call.data });
+        return JSON.parse(text, (key, value) => (BIGINTS.includes(key) && typeof value === "string" ? BigInt(value) : value));
+    }
+    catch (error) {
+        throw new Error(`${path} cannot be read: ${error instanceof Error ? error.message : String(error)}; it holds a pull that can land until ten minutes after it was signed`);
+    }
+}
+/**
+ * Keeps `pull` at `path` unless a pull is kept there already, and returns the
+ * one kept. The whole file is written beside it and linked into place, which
+ * fails when the path exists, so two runs at once keep and send one pull.
+ */
+async function keepFirst(path, pull) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const draft = await writeDraft(path, pull);
+    try {
+        for (;;) {
+            const linked = await link(draft, path).then(() => true, (error) => {
+                if (error.code !== "EEXIST")
+                    throw error;
+                return false;
+            });
+            if (linked)
+                return pull;
+            const kept = await readKept(path);
+            if (kept !== undefined)
+                return kept;
+        }
+    }
+    finally {
+        await rm(draft, { force: true });
+    }
+}
+async function writeDraft(path, pull) {
+    const draft = `${path}.${randomUUID()}.tmp`;
+    await writeFile(draft, `${JSON.stringify(pull, (_, value) => (typeof value === "bigint" ? value.toString() : value), 2)}\n`, { mode: 0o600 });
+    return draft;
+}
+/** The pull's own call at the node's gas ceiling; what it costs is sendMandateCall's to estimate. */
+async function simulatePull(publicClient, terms, kept, sender) {
+    const call = pullCall(terms.principal, kept.pull, kept.fields);
+    try {
+        await publicClient.call({ ...(sender && { account: sender.address }), to: call.to, data: call.data });
     }
     catch (error) {
         if (lostInTransport(error))
             throw new Error(`the pull could not be checked: ${publicMessage(error)}`);
         throw new Error(`Mandate Binding rejects the pull and records nothing: ${revertName(error)}`);
     }
-    const reason = await readCheck(publicClient, terms.principal, signed.pull, signed.fields);
-    if (reason !== "None" && !args.recordRefusal)
-        return printUnsent(reason, print);
-    const hash = await sendMandateCall(publicClient, walletFor(publicClient, sender), call);
-    // Printed before the wait: a pull whose receipt never arrives is still found by its transaction.
-    print(`transaction ${hash}`);
-    const receipt = await confirm(publicClient, hash).catch((error) => {
-        throw new Error(`${error instanceof Error ? error.message : String(error)}; the pull was sent in transaction ${hash}: check it with metal-agent status ${hash} before pulling again`);
-    });
-    return printPull(target, terms, slice(signed.pull.nonce, 12), receipt, print);
 }
+/** Above the facilitator's own 60 s wait for a receipt, so its answer is not cut short. */
+const FACILITATOR_TIMEOUT_MS = 120_000;
+/**
+ * The codes a connection fails with before any request is sent: the host is
+ * not there, or is not who its certificate says. A failure after that, or a
+ * timeout, leaves open whether the request arrived.
+ */
+const NEVER_REACHED = new Set(["ECONNREFUSED", "ENOTFOUND", "EAI_AGAIN", "EHOSTUNREACH", "ENETUNREACH", "ERR_TLS_CERT_ALTNAME_INVALID", "UNABLE_TO_VERIFY_LEAF_SIGNATURE", "CERT_HAS_EXPIRED", "DEPTH_ZERO_SELF_SIGNED_CERT", "SELF_SIGNED_CERT_IN_CHAIN"]);
+/** The code under which `fetch` never reached its host, or undefined when the request may have arrived. */
+function neverReached(error) {
+    const cause = error.cause;
+    const code = typeof cause?.code === "string" ? cause.code : undefined;
+    return code !== undefined && NEVER_REACHED.has(code) ? code : undefined;
+}
+/**
+ * Hands the pull to the facilitator as the payment a seller would settle,
+ * `exact` to the payee; it checks the pull against the mandate, submits it and
+ * pays the gas. Its answer gives the transaction it sent, if any, and its
+ * reason for not settling; whether the pull paid is the chain's to say.
+ */
+async function sendToFacilitator(target, terms, kept) {
+    const paymentPayload = {
+        x402Version: 2,
+        accepted: kept.requirements,
+        payload: {
+            authorization: {
+                from: terms.principal,
+                to: kept.pull.to,
+                value: kept.pull.value.toString(),
+                validAfter: kept.pull.validAfter.toString(),
+                validBefore: kept.pull.validBefore.toString(),
+                nonce: kept.pull.nonce,
+            },
+            signature: encodeMandateBlob(kept.pull, kept.fields),
+        },
+    };
+    let response;
+    try {
+        response = await fetch(`${target.facilitatorUrl}/settle`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ x402Version: 2, paymentPayload, paymentRequirements: kept.requirements }),
+            signal: AbortSignal.timeout(FACILITATOR_TIMEOUT_MS),
+        });
+    }
+    catch (error) {
+        const code = neverReached(error);
+        if (code !== undefined)
+            return { kind: "unsent", cause: `the facilitator at ${new URL(target.facilitatorUrl).host} could not be reached (${code})` };
+        return { kind: "sent", transaction: undefined, why: "the facilitator did not answer" };
+    }
+    const answer = await response.json().catch(() => undefined);
+    const settled = (typeof answer === "object" && answer !== null ? answer : {});
+    const transaction = typeof settled.transaction === "string" && isHash(settled.transaction) ? settled.transaction : undefined;
+    const said = [settled.errorReason, settled.errorMessage].filter((part) => typeof part === "string" && part !== "").join(": ");
+    const why = said !== "" ? `the facilitator says ${said}` : settled.success === true ? "the facilitator says it settled" : `the facilitator answered HTTP ${response.status}`;
+    return { kind: "sent", transaction, why: why.replace(UNSHOWN, "?").slice(0, 300) };
+}
+/**
+ * Submits the pull from the `--key` account, which pays the gas. A node that
+ * refuses the transaction, or an estimate that fails, sent nothing; a request
+ * lost on its way to the node may have.
+ */
+async function sendFromKey(publicClient, sender, call) {
+    return sendMandateCall(publicClient, walletFor(publicClient, sender), call).then((transaction) => ({ kind: "sent", transaction, why: "its transaction has no receipt" }), (error) => (lostInTransport(error) ? { kind: "sent", transaction: undefined, why: `sending it failed: ${publicMessage(error)}` } : { kind: "unsent", cause: `sending it failed: ${publicMessage(error)}` }));
+}
+const PULL_OUTCOMES = [getAbiItem({ abi: mandateBindingAbi, name: "MandatePayment" }), getAbiItem({ abi: mandateBindingAbi, name: "MandateRefused" })];
+/** Blocks per log search, under the node's own limit on one filter's range. */
+const LOG_CHUNK = 10000n;
+/**
+ * The reasons a bound mandate refuses a pull for good: none of them can turn
+ * into a payment later. A closed window is read from the block itself; a
+ * window or mandate this node has not reached yet is not final.
+ */
+const FINAL = ["Revoked", "Expired", "BadSignature", "PayeeNotAllowed", "OverPerPaymentCap", "OverBudget", "OverOccurrences"];
+/**
+ * Where a pull stands on chain, read at one block: landed, in `transaction`
+ * when one is named or in the account's own log between the block it was
+ * signed at and the end of its window; never to land, once its window has
+ * closed or the mandate refuses it for good; or still open. A read that fails
+ * leaves it open.
+ */
+async function outcomeOnChain(publicClient, terms, kept, transaction) {
+    const digest = slice(kept.pull.nonce, 12);
+    let unreadReceipt = transaction !== undefined;
+    try {
+        if (transaction !== undefined) {
+            const receipt = await publicClient.waitForTransactionReceipt({ hash: transaction, pollingInterval: 250 });
+            unreadReceipt = false;
+            if (pullEventOf(terms, digest, receipt) !== undefined)
+                return { kind: "landed", receipt };
+        }
+        const head = await publicClient.getBlock();
+        // A pull lands only before its window ends, so the search stops at the first range that reaches it.
+        for (let from = kept.fromBlock; from <= head.number; from += LOG_CHUNK) {
+            const to = from + LOG_CHUNK - 1n < head.number ? from + LOG_CHUNK - 1n : head.number;
+            const logs = await publicClient.getLogs({ address: terms.principal, events: PULL_OUTCOMES, fromBlock: from, toBlock: to });
+            const log = logs.find((entry) => entry.args.l3aDigest === digest);
+            if (log !== undefined)
+                return { kind: "landed", receipt: await publicClient.getTransactionReceipt({ hash: log.transactionHash }) };
+            if (to === head.number || (await publicClient.getBlock({ blockNumber: to })).timestamp >= kept.pull.validBefore)
+                break;
+        }
+        // The token records the authorization a paid pull spends, whatever the mandate's state is since.
+        const spent = await publicClient.readContract({ address: kept.pull.token, abi: AUTHORIZATION_STATE, functionName: "authorizationState", args: [terms.principal, kept.pull.nonce], blockNumber: head.number });
+        if (spent)
+            return { kind: "open", landed: true };
+        if (head.timestamp >= kept.pull.validBefore)
+            return { kind: "never", reason: "OutsideWindow" };
+        const reason = await readCheck(publicClient, terms.principal, kept.pull, kept.fields, head.number);
+        // After its end a mandate refuses for good; before its start it does only until then.
+        // A used digest with no log for it is a pull that landed, as a payment or a recorded refusal.
+        if (reason === "NonceUsed")
+            return { kind: "open", landed: true };
+        const final = FINAL.includes(reason) || (reason === "OutsideRecurrence" && head.timestamp >= terms.constraints.recurrenceStart);
+        return final ? { kind: "never", reason: reason } : { kind: "open" };
+    }
+    catch (error) {
+        return { kind: "open", unread: publicMessage(error), unreadReceipt };
+    }
+}
+const AUTHORIZATION_STATE = parseAbi(["function authorizationState(address authorizer, bytes32 nonce) view returns (bool)"]);
 /** Whether the request failed on its way, so the node may or may not have acted on it. */
 function lostInTransport(error) {
     return error instanceof BaseError && error.walk((e) => e instanceof HttpRequestError || e instanceof TimeoutError) !== null;
@@ -464,29 +763,42 @@ function printUnsent(reason, print) {
     print("recorded no");
     return "refused";
 }
-function printPull(target, terms, l3aDigest, receipt, print) {
-    const outcome = parseEventLogs({ abi: mandateBindingAbi, logs: receipt.logs, eventName: ["MandatePayment", "MandateRefused"] }).find((log) => log.address.toLowerCase() === terms.principal.toLowerCase() && log.args.l3aDigest === l3aDigest);
-    if (outcome?.eventName === "MandatePayment") {
-        print("outcome paid");
+function pullEventOf(terms, l3aDigest, receipt) {
+    return parseEventLogs({ abi: mandateBindingAbi, logs: receipt.logs, eventName: ["MandatePayment", "MandateRefused"] }).find((log) => isAddressEqual(log.address, terms.principal) && log.args.l3aDigest === l3aDigest);
+}
+/** Where a token sends a credit the payee's receive policy refuses: its escrow (IMIP20.sol). */
+const RECEIVE_POLICY = "0x0000000000000000000000000000000000000f4d";
+const AUTHORIZATION_USED = parseAbiItem("event AuthorizationUsed(address indexed authorizer, bytes32 indexed nonce)");
+function printPull(target, terms, pull, receipt, print) {
+    const outcome = pullEventOf(terms, slice(pull.nonce, 12), receipt);
+    if (outcome === undefined)
+        throw new Error(`transaction ${receipt.transactionHash} carries neither a payment nor a refusal for the pull`);
+    let result = "refused";
+    print(`transaction ${receipt.transactionHash}`);
+    if (outcome.eventName === "MandatePayment") {
+        // The transfer the pull's authorization makes is the token's next one from the account after it.
+        const used = parseEventLogs({ abi: [AUTHORIZATION_USED], logs: receipt.logs }).find((log) => isAddressEqual(log.address, pull.token) && isAddressEqual(log.args.authorizer, terms.principal) && log.args.nonce === pull.nonce);
+        const moved = used && parseEventLogs({ abi: erc20Abi, eventName: "Transfer", logs: receipt.logs }).find((log) => isAddressEqual(log.address, pull.token) && log.logIndex > used.logIndex && isAddressEqual(log.args.from, terms.principal) && !isAddressEqual(log.args.to, pull.token));
+        result = moved !== undefined && isAddressEqual(moved.args.to, RECEIVE_POLICY) ? "held" : "paid";
+        print(`outcome ${result}`);
+        if (result === "held")
+            print("reason the payee's receive policy refused the payment, and the token holds it in escrow");
         print(`spent ${usdz(outcome.args.spent)} of ${usdz(terms.constraints.budget)}`);
     }
-    else if (outcome?.eventName === "MandateRefused") {
+    else {
         print("outcome refused");
         const reason = reasonName(outcome.args.reason);
         if (reason === "None")
             throw new Error(`transaction ${receipt.transactionHash} records a refusal with no reason`);
         print(`reason ${describeRefusal(reason)}`);
     }
-    else {
-        throw new Error(`transaction ${receipt.transactionHash} carries neither a payment nor a refusal for the pull`);
-    }
     print(`payer ${terms.principal}`);
     print(`payee ${outcome.args.to}`);
     print(`amount ${usdz(outcome.args.amount)}`);
     if (target.explorerUrl)
         print(`explorer ${target.explorerUrl}/tx/${receipt.transactionHash}`);
     print(`gas ${receipt.gasUsed}`);
-    return outcome.eventName === "MandatePayment" ? "paid" : "refused";
+    return result;
 }
 /** A decimal `*USDZ` amount a mandate can pay: positive, to the cent. */
 export function parsePullAmount(text, option) {