@metalntwx/metal-agent 0.3.0 → 0.3.1

package/dist/commands/mandate.js

@@ -6,12 +6,12 @@
 // 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 { randomUUID } from "node:crypto";
+import { createHash, 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, 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 { 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, 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, erc20Abi, getAbiItem, parseAbi, parseAbiItem, HttpRequestError, TimeoutError, createWalletClient, custom, decodeErrorResult, encodeFunctionData, encodeAbiParameters, parseAbiParameters, getAddress, isAddress, isAddressEqual, isHash, parseEventLogs, slice, } from "viem";
+import { BaseError, erc20Abi, formatLog, parseAbi, parseAbiItem, HttpRequestError, TimeoutError, createWalletClient, custom, decodeErrorResult, encodeFunctionData, encodeAbiParameters, parseAbiParameters, getAddress, isAddress, isAddressEqual, isHash, numberToHex, parseEventLogs, slice, } from "viem";
 import { rpcClient } from "../chain.js";
 import { fund } from "./fund.js";
 import { exists, mandateKeyPath, pendingPullsPath, publicKeyPath, readKey, readOrCreateIssuerKeys, readOrCreateKey, readOrCreateP256Key, readP256Key, readTrustedIssuer, writePublicKeyFile, } from "../keystore.js";
@@ -199,14 +199,20 @@ async function ownerAccount(client, factory, owner) {
 /** 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
+ * owner with too little 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);
+    // The owner key is written before anything is read from the chain: a failure names it, and the same command continues.
+    await deployAccount(target, args.accountFactory, keyPath, created, owner, print).catch((error) => {
+        throw new Error(`${error instanceof BaseError || !(error instanceof Error) ? publicMessage(error) : error.message}. The owner key is in ${keyPath}; the same command continues from it`);
+    });
+}
+async function deployAccount(target, accountFactory, keyPath, created, owner, print) {
     const client = rpcClient(target);
-    const { config, address } = await ownerAccount(client, args.accountFactory, owner.address);
+    const { config, address } = await ownerAccount(client, accountFactory, owner.address);
     print(`account ${address}`);
     print(`owner ${owner.address}`);
     print(`keyfile ${keyPath}${created ? " (created)" : ""}`);
@@ -214,14 +220,30 @@ export async function accountCreate(target, args, print) {
         print("deployed yes");
         return;
     }
-    if ((await client.getBalance({ address: owner.address })) === 0n) {
+    const call = { to: accountFactory, data: encodeFunctionData({ abi: metalAccountFactoryAbi, functionName: "createAccount", args: config }), gas: 600000n, maxFeePerGas: FEE_PER_GAS, maxPriorityFeePerGas: FEE_PER_GAS };
+    const needed = call.gas * FEE_PER_GAS;
+    if ((await client.getBalance({ address: owner.address })) < needed) {
         // 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));
+        // `key import` loads the agent's key, which account create never reads.
+        const refused = await fund(target, owner.address, undefined, (line) => funding.push(line), fetch, false).then(() => undefined, (error) => error);
         if (funding[0] !== undefined)
             print(funding[0]);
+        // A grant the faucet could not confirm can have reached the owner all the same.
+        if (refused !== undefined) {
+            const held = await client.getBalance({ address: owner.address });
+            if (held < needed)
+                throw new Error(`the owner ${owner.address} holds ${usdz(held)}, and deploying the account needs ${usdz(needed)}, so it is not deployed: ${refused instanceof Error ? refused.message : String(refused)}`);
+        }
     }
-    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 });
+    const hash = await sendMandateCall(client, walletFor(client, owner), call).catch((error) => {
+        throw new Error(`the account is not deployed: ${publicMessage(error)}`);
+    });
+    const receipt = await client.waitForTransactionReceipt({ hash, pollingInterval: 250 }).catch((error) => {
+        throw new Error(`the account's deployment was sent in transaction ${hash}, and its receipt could not be read: ${publicMessage(error)}; the same command reports the account once it is deployed`);
+    });
+    if (receipt.status !== "success")
+        throw new Error(`the account is not deployed: transaction ${hash} reverted`);
     print("deployed yes");
     printSent(target, receipt, print);
 }
@@ -244,7 +266,9 @@ async function sendOwnerCall(client, args, call) {
             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 })))]));
+    // The quorum's signature is good for fifteen minutes: long enough to send, not to hold.
+    const validUntil = BigInt(Math.floor(Date.now() / 1000)) + 900n;
+    const authorized = await authorizeMandateCall(client, args.accountFactory, call, validUntil, 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);
 }
 export async function mandateBind(target, args, print) {
@@ -317,18 +341,19 @@ export async function mandateStatus(target, credentialPath, accountFactory, prin
     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;
+        return "unbound";
     }
     await assertMetalAccount(publicClient, terms.principal, accountFactory);
     print("account-type MetalAccount");
     const bound = (await publicClient.readContract({ address: terms.principal, abi: mandateBindingAbi, functionName: "mandates", args: [reference] })).principal.toLowerCase() === terms.principal.toLowerCase();
     print(`bound ${bound ? "yes" : "no"}`);
     if (!bound)
-        return;
+        return "unbound";
     const state = await readMandateState(publicClient, terms.principal, reference);
     print(`revoked ${state.revoked ? "yes" : "no"}`);
     print(`spent ${usdz(state.spent)} of ${usdz(terms.constraints.budget)}`);
     print(`payments ${state.occurrences}`);
+    return state.revoked ? "revoked" : "live";
 }
 /**
  * Verifies the mandate and its payments from the chain alone: the binding on
@@ -411,10 +436,12 @@ function revertName(error) {
  * 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.
+ * facilitator answers, so its outcome is read from the chain alone. Each is
+ * kept under `~/.metal-agent/pulls/<mandate>/`, per payment id when one is
+ * given and per payee and amount otherwise, and the same command sends the
+ * pull with no outcome yet again, which the account pays at most once; once
+ * it can no longer land, the command signs a new one. Under a payment id, a
+ * payout that was paid or held is reported again and nothing is sent.
  */
 export async function mandatePull(target, args, print) {
     const mandate = await loadMandate(args.credentialPath);
@@ -422,10 +449,6 @@ export async function mandatePull(target, args, print) {
     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) => {
@@ -438,44 +461,89 @@ export async function mandatePull(target, args, print) {
     // 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([
-        hasCode(publicClient, terms.principal).then((deployed) => (deployed ? readBoundAgentKey(publicClient, terms.principal, reference) : undefined)),
+        hasCode(publicClient, terms.principal).then((deployed) => (deployed ? publicClient.readContract({ address: terms.principal, abi: mandateBindingAbi, functionName: "mandates", args: [reference] }) : undefined)),
         publicClient.getBlock(),
         sender === undefined ? undefined : publicClient.getBalance({ address: sender.address }),
     ]);
     if (bound === undefined)
+        throw new Error(`the mandate's account ${terms.principal} does not exist: the owner creates it with metal-agent account create, then binds the mandate with mandate bind`);
+    if (!isAddressEqual(bound.principal, terms.principal))
         throw new Error(`the mandate ${reference} is not bound on ${terms.principal}; the owner binds it with mandate bind`);
     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}`);
+    // A hash names a payment id's directory: any text is one path segment, and ids that differ only in case stay apart.
+    const keptPath = join(pendingPullsPath(reference), args.paymentId === undefined ? `${args.to.toLowerCase()}-${args.amount}` : `payment-${createHash("sha256").update(args.paymentId).digest("hex")}`);
     const end = await chainEnd(keptPath);
+    if (end !== undefined) {
+        const { pull } = end;
+        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)) {
+            if (args.paymentId === undefined || 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 recorded = join(keptPath, `${pull.nonce}.done`);
+            const ended = (await exists(recorded)) ? (await readReported(recorded)).outcome : undefined;
+            // A payout the account refused paid nothing: the payment id is sent with these values, as a new pull after it.
+            if (ended !== "refused") {
+                const named = `the payout under payment id ${JSON.stringify(args.paymentId)} is ${usdz(pull.value)} to ${getAddress(pull.to)}`;
+                if (ended !== undefined)
+                    throw new Error(`${named}: send it again with those values; another payment id is another payment`);
+                // One with no outcome yet can still land: another id would pay a second time.
+                throw new Error(`${named}, signed to land until ${utc(pull.validBefore)}: send it again with those values, to send it or learn how it ended; another payment id is another payment`);
+            }
+        }
+    }
+    // What a run prints from the outcome on, kept with the outcome for a payment id's later runs.
+    const shown = [];
+    const show = (line) => {
+        shown.push(line);
+        print(line);
+    };
     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.
+    const done = end === undefined ? undefined : join(keptPath, `${end.pull.nonce}.done`);
+    if (end !== undefined && done !== undefined && (await exists(done))) {
+        // A payment id's payout that moved money is that payment: it is reported again, and nothing is sent.
+        const reported = args.paymentId === undefined ? undefined : await readReported(done);
+        if (reported?.outcome === "paid" || reported?.outcome === "held") {
+            // The token records the authorization the pull spent; a chain reset since holds none.
+            const spent = await publicClient.readContract({ address: end.pull.token, abi: AUTHORIZATION_STATE, functionName: "authorizationState", args: [terms.principal, end.pull.nonce] });
+            if (!spent)
+                throw new Error(`payment id ${JSON.stringify(args.paymentId)} is recorded as ${reported.outcome} in a transaction this chain does not hold, as after a chain reset; nothing was sent`);
+            print(`already ${reported.outcome}, nothing sent`);
+            // The spend is the mandate's now, which later payments have added to.
+            for (const line of reported.lines)
+                print(line.startsWith("spent ") ? `spent ${usdz(bound.spent)} of ${usdz(terms.constraints.budget)}` : line);
+            return reported.outcome;
+        }
+        // Its outcome is reported: this is a new payment, or under a payment id one more try at it.
         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);
+        const found = await outcomeOnChain(publicClient, terms, reference, attempt);
+        if (found.kind === "undecoded")
+            throw undecodedPull(terms, found);
         if (found.kind === "landed")
-            return settle(keptPath, attempt, printPull(target, terms, attempt.pull, found.receipt, print));
+            return settle(keptPath, attempt, printPull(target, terms, attempt.pull, found.receipt, show), shown, args, print);
         if (found.kind === "open" && found.landed)
-            return printPending(print, "it has landed, and its log cannot be read yet", attempt, keptPath);
+            return printPending(print, "it has landed, and its log cannot be read yet", attempt, args);
         // 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;
         }
     }
+    const facilitatorProtocol = URL.canParse(target.facilitatorUrl) ? new URL(target.facilitatorUrl).protocol : "";
+    if (keyPath === undefined && facilitatorProtocol !== "http:" && facilitatorProtocol !== "https:") {
+        const sentNothing = `the facilitator URL ${target.facilitatorUrl} is not an http or https URL, so`;
+        throw new Error(attempt === undefined ? `${sentNothing} the pull was not sent` : `${sentNothing} this run sent nothing; ${keptBefore(attempt)}`);
+    }
     if (attempt === undefined) {
+        // Mandate Binding names the mandate's state before its dates; one that has not started cannot have expired.
         if (block.timestamp < terms.constraints.recurrenceStart && !args.recordRefusal)
-            return printUnsent("OutsideRecurrence", print);
+            return printUnsent(bound.revoked ? "Revoked" : "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 = {
@@ -505,7 +573,7 @@ export async function mandatePull(target, args, print) {
             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.
+        // Kept before it leaves: from here on it can land, and the same pull 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);
     }
@@ -513,47 +581,97 @@ export async function mandatePull(target, args, print) {
         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);
+            const found = await outcomeOnChain(publicClient, terms, reference, attempt);
+            if (found.kind === "undecoded")
+                throw undecodedPull(terms, found);
             if (found.kind === "landed") {
-                return settle(keptPath, attempt, printPull(target, terms, attempt.pull, found.receipt, print));
+                return settle(keptPath, attempt, printPull(target, terms, attempt.pull, found.receipt, show), shown, args, print);
             }
             if (found.kind === "open" && found.landed)
-                return printPending(print, "it has landed, and its log cannot be read yet", attempt, keptPath);
-            throw rejected;
+                return printPending(print, "it has landed, and its log cannot be read yet", attempt, args);
+            throw new Error(`${rejected instanceof Error ? rejected.message : String(rejected)}; ${keptBefore(attempt)}`);
         }
     }
     const call = pullCall(terms.principal, attempt.pull, attempt.fields);
     const sent = sender === undefined ? await sendToFacilitator(target, terms, attempt) : await sendFromKey(publicClient, sender, call);
+    // A pull kept before this run may have left then, and can land whatever this run's send meets.
+    const before = attempt.pull.nonce === checked ? undefined : keptBefore(attempt);
     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);
+        throw new Error(before === undefined ? `the pull was not sent: ${sent.cause}; it is kept ${keptAs(args)}, and the same pull sends it` : `this run did not send the pull: ${sent.cause}; ${before}`);
+    const found = await outcomeOnChain(publicClient, terms, reference, attempt, sent.kind === "sent" ? sent.transaction : undefined);
+    if (found.kind === "undecoded")
+        throw undecodedPull(terms, found);
     if (found.kind === "landed") {
-        return settle(keptPath, attempt, printPull(target, terms, attempt.pull, found.receipt, print));
+        return settle(keptPath, attempt, printPull(target, terms, attempt.pull, found.receipt, show), shown, args, print);
     }
     if (found.kind === "never") {
-        print("outcome refused, not paid");
-        print(`reason ${describeRefusal(found.reason)}`);
-        return settle(keptPath, attempt, "refused");
+        show("outcome refused, not paid");
+        show(`reason ${describeRefusal(found.reason)}`);
+        return settle(keptPath, attempt, "refused", shown, args, print);
     }
     // A transaction whose receipt was read and does not carry this pull is not named as its.
-    if (sent.transaction !== undefined && found.unreadReceipt)
+    if (sent.kind === "sent" && 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);
+        return printPending(print, "it has landed, and its log cannot be read yet", attempt, args);
+    // A refusal that names no transaction sent none, and the chain read shows the pull not on it: waiting changes nothing for a pull no earlier run kept.
+    if (sent.kind === "refused" && found.unread === undefined) {
+        throw new Error(before === undefined
+            ? `the pull was not sent: ${sent.cause}; it is kept ${keptAs(args)}: the same pull sends it again, and it is refused again until what the reason names changes`
+            : `this run did not send the pull: ${sent.cause}; ${before}`);
+    }
+    const why = sent.kind === "refused" ? sent.cause : sent.why;
+    return printPending(print, found.unread === undefined ? why : `${why}; the chain could not be read: ${found.unread}`, attempt, args);
 }
+/** How a payout is kept, as its retry names it: by its payment id, or else by its amount and payee. */
+function keptAs({ paymentId, amount, to }) {
+    return paymentId === undefined ? `for ${usdz(amount)} to ${to}` : `under payment id ${JSON.stringify(paymentId)}`;
+}
+/** What a run that sends nothing says of a pull kept before it, which may have left then and can land until its window ends. */
+function keptBefore(kept) {
+    return `the pull kept before may have been sent and can land until ${utc(kept.pull.validBefore)}; the same pull sends it again`;
+}
+const PULL_OUTCOMES = ["paid", "refused", "held", "pending"];
 /**
- * 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
+ * Marks a kept pull's outcome reported once it is printed, with the outcome
+ * and its lines, so the same command makes a new payment next, or under a
+ * payment id reports that one again; 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;
+async function settle(keptPath, kept, outcome, lines, args, print) {
+    // The outcome is the chain's: a record that cannot be written leaves the next run to read it there again.
+    await record(join(keptPath, `${kept.pull.nonce}.done`), { outcome, lines }).catch((error) => {
+        print(`kept ${keptAs(args)}: the outcome was not recorded (${error instanceof Error ? error.message : String(error)}); the same pull reports it again`);
     });
     return outcome;
 }
+/** Writes the record whole beside `path` and links it into place, as a pull is kept, so no run reads a part-written record. */
+async function record(path, outcome) {
+    const draft = `${path}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(draft, `${JSON.stringify(outcome)}\n`, { mode: 0o600 });
+        await link(draft, path).catch((error) => {
+            if (error.code !== "EEXIST")
+                throw error;
+        });
+    }
+    finally {
+        await rm(draft, { force: true });
+    }
+}
+/** The outcome `settle` recorded at `path`, and the lines it printed. */
+async function readReported(path) {
+    const text = await readFile(path, "utf8");
+    try {
+        const record = JSON.parse(text);
+        if (!PULL_OUTCOMES.includes(record.outcome) || !Array.isArray(record.lines))
+            throw new Error("not an outcome record");
+        return record;
+    }
+    catch (error) {
+        throw new Error(`${path} cannot be read: ${error instanceof Error ? error.message : String(error)}; it records how this payment id's payout ended: tell the user; deleting it lets the same pull report the payout from the chain`);
+    }
+}
 /**
  * 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
@@ -565,11 +683,11 @@ async function chainEnd(keptPath) {
         kept = next;
     return kept;
 }
-function printPending(print, reason, kept, keptPath) {
+function printPending(print, reason, kept, args) {
     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`);
+    print(`kept ${keptAs(args)}: the same pull sends it again, which pays at most once`);
     return "pending";
 }
 const BIGINTS = ["value", "validAfter", "validBefore", "fromBlock"];
@@ -585,7 +703,7 @@ async function readKept(path) {
         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`);
+        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, about when the file was last modified: tell the user; once that has passed, deleting it lets the same pull sign a new one`);
     }
 }
 /**
@@ -633,6 +751,8 @@ async function simulatePull(publicClient, terms, kept, sender) {
 }
 /** 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 facilitator's reasons for an answer with no transaction that leave open whether the pull, or a payment, is on its way. */
+const IN_DOUBT = new Set(["settlement_in_doubt", "payment_in_flight"]);
 /**
  * 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
@@ -649,7 +769,10 @@ function neverReached(error) {
  * 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.
+ * reason for not settling; whether the pull paid is the chain's to say. One
+ * with no transaction and a reason other than doubt or a revert sent none,
+ * as did a 4xx answer that names no reason, such as from a URL it does not
+ * serve.
  */
 async function sendToFacilitator(target, terms, kept) {
     const paymentPayload = {
@@ -686,6 +809,14 @@ async function sendToFacilitator(target, terms, kept) {
     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 reason = typeof settled.errorReason === "string" ? settled.errorReason : "";
+    // It sent this pull before, and that transaction reverted; it never sends it again.
+    if (transaction === undefined && reason === "payment_reverted")
+        return { kind: "sent", transaction: undefined, why: "the facilitator sent this pull and it reverted" };
+    if (transaction === undefined && !IN_DOUBT.has(reason) && (reason !== "" || (response.status >= 400 && response.status < 500))) {
+        const cause = said === "" ? `the facilitator answered HTTP ${response.status}, sending no transaction` : `the facilitator refused it, sending no transaction: ${said}`;
+        return { kind: "refused", cause: cause.replace(UNSHOWN, "?").slice(0, 300) };
+    }
     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) };
 }
@@ -697,7 +828,22 @@ async function sendToFacilitator(target, terms, kept) {
 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" })];
+/**
+ * The topic of an event the account emitted under the mandate, its reference
+ * in the first topic, that Mandate Binding's ABI does not decode: an account
+ * of another version than the SDK's. Each log is matched to its decoding by
+ * transaction and position, so one under a known topic in another layout is
+ * seen too.
+ */
+function undecodedTopic(principal, reference, logs) {
+    const under = logs.filter((log) => isAddressEqual(log.address, principal) && log.topics[1]?.toLowerCase() === reference.toLowerCase());
+    const decoded = new Set(parseEventLogs({ abi: mandateBindingAbi, logs: under, strict: true }).map((log) => `${log.transactionHash}:${log.logIndex}`));
+    return under.find((log) => !decoded.has(`${log.transactionHash}:${log.logIndex}`))?.topics[0];
+}
+function undecodedPull(terms, found) {
+    return new Error(`the account ${terms.principal} emitted an event under the mandate under topic ${found.topic}, which this SDK does not decode, so the pull may have paid: do not pay it under another payment id; the SDK must be the account's version to read it. ` +
+        `${found.transaction === undefined ? "" : `Transaction ${found.transaction} carries it. `}The same pull sends nothing while that event is under the mandate`);
+}
 /** Blocks per log search, under the node's own limit on one filter's range. */
 const LOG_CHUNK = 10000n;
 /**
@@ -711,9 +857,10 @@ const FINAL = ["Revoked", "Expired", "BadSignature", "PayeeNotAllowed", "OverPer
  * 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.
+ * leaves it open. An event under the mandate that does not decode leaves the
+ * outcome unreadable by this SDK.
  */
-async function outcomeOnChain(publicClient, terms, kept, transaction) {
+async function outcomeOnChain(publicClient, terms, reference, kept, transaction) {
     const digest = slice(kept.pull.nonce, 12);
     let unreadReceipt = transaction !== undefined;
     try {
@@ -722,15 +869,24 @@ async function outcomeOnChain(publicClient, terms, kept, transaction) {
             unreadReceipt = false;
             if (pullEventOf(terms, digest, receipt) !== undefined)
                 return { kind: "landed", receipt };
+            const topic = undecodedTopic(terms.principal, reference, receipt.logs);
+            if (topic !== undefined)
+                return { kind: "undecoded", topic, transaction };
         }
         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 });
+            // Every event under the mandate, so one this SDK does not decode is seen rather than dropped.
+            const raw = (await publicClient.request({ method: "eth_getLogs", params: [{ address: terms.principal, fromBlock: numberToHex(from), toBlock: numberToHex(to), topics: [null, reference] }] }));
+            const formatted = raw.map((log) => formatLog(log));
+            const logs = parseEventLogs({ abi: mandateBindingAbi, eventName: ["MandatePayment", "MandateRefused"], logs: formatted });
             const log = logs.find((entry) => entry.args.l3aDigest === digest);
             if (log !== undefined)
                 return { kind: "landed", receipt: await publicClient.getTransactionReceipt({ hash: log.transactionHash }) };
+            const topic = undecodedTopic(terms.principal, reference, formatted);
+            if (topic !== undefined)
+                return { kind: "undecoded", topic, transaction };
             if (to === head.number || (await publicClient.getBlock({ blockNumber: to })).timestamp >= kept.pull.validBefore)
                 break;
         }
@@ -804,3 +960,9 @@ function printPull(target, terms, pull, receipt, print) {
 export function parsePullAmount(text, option) {
     return BigInt(usdzBaseUnits(parseCents(text, option)));
 }
+/** A payment id as `--payment-id` takes it: any text but none, or `undefined` when the option is absent. */
+export function parsePaymentId(text, option) {
+    if (text === "")
+        throw new Error(`${option} must not be empty; leave it out to key the payout by its payee and amount`);
+    return text;
+}

package/dist/commands/pay.js

@@ -1,5 +1,5 @@
 import { decodePaymentRequiredHeader, decodePaymentResponseHeader } from "@x402/core/http";
-import { DEFAULT_MAX_PAYMENT, createMetalPaymentClient, formatUsdz, USDZ, usdzBaseUnits, } from "@metalntwx/metal-pay";
+import { DEFAULT_MAX_PAYMENT, createMetalPaymentClient, formatUsdz, metalNetwork, USDZ, usdzBaseUnits, } from "@metalntwx/metal-pay";
 import { createMandatePaymentClient, describeRefusal, refusalOf, signedOfferOf } from "@metalntwx/metal-pay/mandates";
 import { loadMandate, mandateAgentSigner } from "./mandate.js";
 /** A decimal `*USDZ` limit per payment, `DEFAULT_MAX_PAYMENT` when absent. */
@@ -64,6 +64,71 @@ export async function payUnderMandate(target, payer, url, print, request = {}) {
     print(`mandate ${paying.reference}`);
     await paidRequest(target, { ...paying, payer: paying.principal }, url, print, request);
 }
+/** A payment refused with nothing paid, before settlement or at it; `reason` is the facilitator's or the seller's, when it gave one. */
+export class PaymentRefused extends Error {
+    reason;
+    constructor(message, reason) {
+        super(message);
+        this.reason = reason;
+    }
+}
+/** A payment that was signed and may have settled: paying again can pay twice. */
+export class PaymentInDoubt extends Error {
+}
+/**
+ * The facilitator's settlement reasons that mean nothing moved
+ * (apps/x402-facilitator/src/facilitator.ts `check`, `settle`, `failed` and
+ * routes.ts): the payment was never sent, was refused or reverted. Any other
+ * answer, such as a seller's own `fetch failed` when the facilitator's answer
+ * to it was lost, or `already_settled`, `nonce_already_used` or
+ * `payment_quarantined`, which name a transaction that moved it, leaves open
+ * whether it settled.
+ */
+const NOTHING_SETTLED = new Set([
+    "unsupported_x402_version",
+    "unsupported_network",
+    "unsupported_scheme",
+    "unsupported_asset",
+    "settlement_unavailable",
+    "invalid_payload",
+    "bad_signature",
+    "rpc_unreachable",
+    "authorization_window",
+    "rate_limited",
+    "daily_limit_reached",
+    "recipient_refuses",
+    "payment_failed",
+    "payment_reverted",
+]);
+function nothingSettled(reason) {
+    if (reason === undefined)
+        return false;
+    const mandate = refusalOf(reason);
+    // A used digest is a payment that was made, or refused, already.
+    if (mandate !== undefined)
+        return mandate !== "NonceUsed";
+    return NOTHING_SETTLED.has(reason) || reason.startsWith("payment_mismatch:");
+}
+/** The networks an offer named when none is the one paid on, read from @x402/core's error for an offer with no option it can sign. */
+function offeredElsewhere(message, target) {
+    const marker = "Failed to create payment payload: No network/scheme registered";
+    if (!message.startsWith(marker) || !message.includes("{"))
+        return undefined;
+    try {
+        const { paymentRequirements } = JSON.parse(message.slice(message.indexOf("{")));
+        const networks = [...new Set((paymentRequirements ?? []).map(({ network }) => network).filter((network) => typeof network === "string"))];
+        if (networks.length === 0 || networks.includes(target.network.network))
+            return undefined;
+        const named = networks.map((network) => {
+            const metal = metalNetwork(network);
+            return metal === undefined ? network : `${metal.name} (${network})`;
+        });
+        return `the offer is on ${named.join(", ")}, not ${target.network.name} (${target.network.network})`;
+    }
+    catch {
+        return undefined;
+    }
+}
 /** A refusal's reason as `pay` prints it: a mandate's with what it means, any other as the facilitator named it. */
 function describeRefusalReason(reason) {
     if (reason === undefined)
@@ -102,10 +167,10 @@ async function paidRequest(target, { fetchWithPayment, client, payer, raise }, u
             const how = raise !== undefined && aborted[1].endsWith("limit per payment") ? `; ${raise}` : "";
             throw new Error(`payment refused before signing: ${aborted[1]}${how}`);
         }
-        if (signed !== undefined) {
-            throw new Error(`${error instanceof Error ? error.message : String(error)}; a payment was signed and may have settled; look it up by its nonce before paying again`);
-        }
-        throw error;
+        const message = error instanceof Error ? error.message : String(error);
+        if (signed !== undefined)
+            throw new PaymentInDoubt(`${message}; a payment was signed and may have settled; look it up by its nonce before paying again`);
+        throw new Error(`${offeredElsewhere(message, target) ?? message}; nothing was signed`);
     });
     const body = await response.text();
     const paymentRequired = response.headers.get("payment-required");
@@ -114,16 +179,24 @@ async function paidRequest(target, { fetchWithPayment, client, payer, raise }, u
         const required = decodePaymentRequiredHeader(paymentRequired);
         const offer = required.accepts[0];
         const priced = offer ? `${formatUsdz(offer.amount)} ${USDZ.symbol} on ${offer.network}` : "no offer";
-        throw new Error(`payment refused: ${describeRefusalReason(required.error)} (offer: ${priced})`);
+        // Refused before settlement: the seller settles only a payment its check passed.
+        throw new PaymentRefused(`payment refused: ${describeRefusalReason(required.error)} (offer: ${priced}); nothing was paid`, required.error);
     }
     const settlement = paymentResponse ? decodePaymentResponseHeader(paymentResponse) : undefined;
-    if (settlement !== undefined && !settlement.success)
-        throw new Error(`payment refused at settlement: ${settleRefusal(settlement)}`);
+    if (settlement !== undefined && !settlement.success) {
+        // A settlement that is not known to have moved nothing can land all the same, so paying again can pay twice.
+        if (!nothingSettled(settlement.errorReason))
+            throw new PaymentInDoubt(`payment in doubt at settlement: ${settleRefusal(settlement)}; it may have settled: do not pay again; look it up by its nonce`);
+        throw new PaymentRefused(`payment refused at settlement: ${settleRefusal(settlement)}; nothing was paid`, settlement.errorReason);
+    }
     // A redirect is reported, not an error: the payment may have settled, and `location` says where it points.
-    if (response.status >= 400) {
-        // A seller that fails after the payment was signed may have settled it first.
-        const doubt = signed !== undefined && response.status >= 500 ? "; a payment was signed and may have settled; look it up by its nonce before paying again" : "";
-        throw new Error(`${url} answered ${response.status}: ${body}${doubt}`);
+    // A settled payment is reported paid, whatever status the seller answers with.
+    if (response.status >= 400 && settlement?.success !== true) {
+        // A seller that fails after the payment was signed, or answers that another request holds it, may have settled it first.
+        const answered = `${url} answered ${response.status}: ${body}`;
+        if (signed !== undefined && (response.status >= 500 || response.status === 409))
+            throw new PaymentInDoubt(`${answered}; a payment was signed and may have settled; look it up by its nonce before paying again`);
+        throw new Error(answered);
     }
     print(`status ${response.status}`);
     if (settlement !== undefined) {