@metalntwx/metal-agent 0.2.0 → 0.3.1

package/README.md

@@ -2,7 +2,8 @@
 
 The `metal-agent` CLI an agent pays x402 payees on Metal with: create or
 import a key, fund it, pay a URL, look up a settlement, or serve `pay`,
-`fund` and `status` as MCP tools.
+`fund` and `status` as MCP tools, and under a mandate its payouts, status
+and verification.
 
 ```bash
 npm install -g @metalntwx/metal-agent
@@ -25,7 +26,8 @@ endpoints) and the `*USDZ` address come from `@metalntwx/metal-pay`, and
 `networks.json` holds its demo payee URL and, on testnet, its faucet and
 explorer URLs.
 `METAL_RPC_URL` and `METAL_FAUCET_URL` override those defaults, and
-`--rpc-url` and `--faucet-url` override both.
+`--rpc-url` and `--faucet-url` override both; `METAL_FACILITATOR_URL` and
+`--facilitator-url` do the same for `mandate pull`.
 
 On testnet, `pay` and `fund` need no RPC. `status`, `account create` and
 every `mandate` command but `credential create` need an endpoint of your
@@ -51,8 +53,11 @@ which the devnet funds at genesis.
 offer above `--max`, 1 `*USDZ` per payment by default. A refusal at
 verification, by the facilitator or the seller's own check, prints
 `payment refused: <reason>`.
-A refusal at settlement prints `payment refused at settlement: <reason>`,
-with the transaction hash when there is one.
+A refusal at settlement for a reason that moves nothing prints
+`payment refused at settlement: <reason>`, with the transaction hash when
+there is one; both refusals end `nothing was paid`. Any other failed
+settlement, such as one whose answer the seller lost, prints
+`payment in doubt at settlement: <reason>`: it may have settled.
 
 `pay` sends `--method` (GET by default, POST with a body), `--body` (as `application/json`
 unless a `--header` names a content type) and each repeated
@@ -93,34 +98,36 @@ metal-agent mandate revoke --credential ./wider.json --key <owner key file> --ne
 ```
 
 `credential create` writes the limits into a credential file, a Verifiable
-Intent mandate, and the agent's keys beside it: its mandate key in
-`mandate.agent-key.json`, and in `mandate.gas-key.json` the key that pays
-for its pulls. `--agent-key <file>` names a mandate key the agent already
-has instead, with its gas key beside that. The keys that sign the
-credential are the owner's: they live beside the owner's key file, created
+Intent mandate, and beside it the mandate key the agent signs with:
+`mandate.key.json` for `mandate.json`. `--mandate-key-file <file>` names a
+mandate key that exists instead, as a replacement does. The keys
+that sign the credential are the owner's: they live beside the owner's key file, created
 on first use (`owner-key.issuer.json`, with its public half in
 `owner-key.issuer.public.json`), unless `--issuer-key` names their file.
 `--description` says what the mandate is for, and `--payee` takes a name
 and a website after the address. Every other command takes
-that credential file: the owner's account, the mandate's reference, its
-terms and the agent's key files derive from it. Amounts are in `*USDZ`, to the cent; a
+that credential file: the owner's account, the mandate's id and its
+terms derive from it. Amounts are in `*USDZ`, to the cent; a
 mandate lasts 30 days unless `--expires-in` says otherwise, and its budget
 never resets.
 
-`account create --out <owner key file>` writes the owner's key and names the
-owner's Metal account, a smart account that key controls with threshold one,
-which the owner's first `bind` creates on chain; `--key <file>` uses a key
-that exists. Fund the account and name it as the credential's `--principal`.
+`account create --out <owner key file>` writes the owner's key and creates the
+owner's Metal account on chain, a smart account that key controls with
+threshold one; `--key <file>` uses a key that exists. The owner's key pays the
+gas, and one that holds too little is funded first. When a later step
+fails, such as a faucet refusal, the error says why and names the key file; the same command continues from it. Fund the account and name it as
+the credential's `--principal`; `bind` refuses an address with no account.
 The account factory is the one `@metalntwx/metal-pay` names for the network;
 on a devnet `just deploy` deploys it there, and `--factory <address>` names
 another. `@metalntwx/metal-pay` names the testnet's.
 
-`bind`, `replace` and `revoke` execute self-calls through the account's weighted
-quorum. `--key` names the gas sponsor and defaults as the sole signer; repeat
-`--signer-key <file>` to supply the EOA signers of an existing multisig instead.
-The SDK's `authorizeMandateCall` accepts a quorum-signing callback for mixed
-keys and passkeys. Keep owner keys outside the agent's reach: quorum-approved
-transfers remain independent of mandates. `replace` revokes the mandate
+`bind`, `replace` and `revoke` are signed by the account's owners, as many as
+its threshold needs. `--key` names the gas sponsor and defaults as the sole
+signer; repeat `--signer-key <file>` to supply the owners' keys of an account
+with several instead. The SDK's `authorizeMandateCall` accepts a signing
+callback for mixed keys and passkeys; the CLI's signatures expire fifteen
+minutes after signing. Keep owner keys outside the agent's reach: an owner key
+moves the account's funds outside any mandate's limits. `replace` revokes the mandate
 `--replaces` names and carries its spend into the new one; `renew` binds the
 new one and revokes the old in one batch, starting its spend at nothing, which
 is how a budget starts over.
@@ -132,29 +139,40 @@ account's immutable clone code against the factory's current
 implementation, and checks successful token-transfer receipts.
 
 `pay --mandate <credential>` pays from the owner's account, signed by the
-agent's mandate key, and takes neither `--key` nor `--max`. A payment
+mandate key beside the credential, or the one `--mandate-key-file` names.
+It takes neither `--key` nor `--max`. A payment
 outside the mandate is refused and moves nothing, usually with a
 `mandate_*` reason: `payment refused: mandate_cap_exceeded (…)`. `pay` prints the
 payment's `nonce` as soon as it signs; the facilitator's
 `/settlements?payTo=<payee>` lists a settled payment by an id ending in it.
 
 `mandate pull` pays an address the mandate allows directly, with no seller:
-the agent's mandate key signs, and the `--key` account, the agent's gas key
-by default, submits the transaction and pays its gas, so fund it with a
-little `*USDZ`. A pull the mandate refuses when checked is not sent: it reports the
-reason and exits 1. `--record-refusal` sends it, so the refusal is recorded
-on chain in a transaction that succeeds and moves nothing. A pull prints
-`transaction <hash>` as soon as it is sent; if its receipt never arrives,
-check that transaction with `metal-agent status <hash>` before pulling again.
+the agent's mandate key signs, and the facilitator submits the transaction
+and pays its gas; `--key` names a funded key to submit it instead. A pull
+the mandate refuses when checked is not sent: it reports the reason and
+exits 1. With `--key`, `--record-refusal` sends it, so the refusal is
+recorded on chain in a transaction that succeeds and moves nothing. The
+outcome is read from the chain: `paid` (exit 0), `refused` (exit 1), `held`
+(exit 4) when the payee's receive policy sends it to escrow, or `pending`
+(exit 3); an `error:` line also exits 1. Each pull is kept under `~/.metal-agent/pulls/<mandate>/`, and
+running the same command again sends a pending pull again, which pays at
+most once. `--payment-id <id>` names the payment: two payouts of one amount
+to one payee are two payments under two ids, an id whose payout was paid or
+held reports it again, after an `already paid` or `already held` line, and
+sends nothing, and one the account refused may be sent with other values.
+Without it, a payout is known by its payee and amount. A retry from another
+home directory, or under a credential that renewed or replaced this one,
+signs a new payout.
 
 `mandate verify` checks the mandate and every payment under it from the
 chain alone, through any RPC endpoint: the binding on the owner's account,
 the credential against it and under its issuer, and each payment and
-refusal as the agent key's own signed per-payment mandate, rebuilt from its
+refusal as the mandate key's own signed per-payment mandate, rebuilt from its
 transaction. Anyone holding the credential and the issuer's public file,
 passed as `--issuer`, can run it; `--tx <hash>`
 verifies one transaction, with `--signed-offer <text>` the offer the agent
-signed for it, and a check that fails exits 1. A seller that asks for the
+signed for it, and a check that fails exits 1, as does an event under the
+mandate that the SDK does not decode, as an account of another version emits. A seller that asks for the
 agent's signed order (`requireSignedOffer` in `@metalntwx/metal-pay/mandates`,
 with `extra.signedOffer: "required"` on the route) is paid with it, and
 `pay` prints it. From code, `verifyMandate` and `verifyMandatePayment` do
@@ -165,21 +183,29 @@ an agent, then the commands.
 
 `metal-agent mcp` serves `pay`, `fund` and `status` over stdio, each taking
 a `network`, and `pay` the request as optional `method`, `body` and
-`headers`. What `pay` spends is fixed when the server starts: its key and
-`--max` (the default key file and 1 `*USDZ` when omitted), or one mandate
-with `--mandate <credential>`. The model calling the tools chooses no key,
-no mandate and no higher limit; under a key, a `max` it passes can only
-lower the server's. The mandate commands enter only through the CLI. An MCP host
-starts it with:
+`headers`. What `pay` spends is set when the server starts, by whoever
+starts it: a key file and `--max` (the default key file and 1 `*USDZ` when
+omitted), or one mandate's credential file with `--mandate <credential>`,
+which each call reads. Under a mandate it also serves `mandate_pull`,
+`mandate_status` and `mandate_verify`, which run those commands on the
+server's mandate and read the chain through its `METAL_RPC_URL`, or devnet's
+default endpoint. The model calling the tools chooses no key, no mandate and
+no higher limit; under a key, a `max` it passes can only lower the server's.
+The other mandate commands enter only through the CLI. An MCP host starts it
+with:
 
 ```json
 { "command": "npx", "args": ["-y", "@metalntwx/metal-agent", "mcp"] }
 ```
 
-or, under one mandate:
+or, under one mandate, with the endpoint the mandate tools read on testnet:
 
 ```json
-{ "command": "npx", "args": ["-y", "@metalntwx/metal-agent", "mcp", "--mandate", "/path/to/mandate.json"] }
+{
+  "command": "npx",
+  "args": ["-y", "@metalntwx/metal-agent", "mcp", "--mandate", "/path/to/mandate.json"],
+  "env": { "METAL_RPC_URL": "<endpoint>" }
+}
 ```
 
 ## Develop

package/dist/chain.js

@@ -22,7 +22,7 @@ export function resolveSettings(network, file, flags, env) {
     const faucetUrl = flags.faucetUrl ?? env["METAL_FAUCET_URL"] ?? file.faucetUrl;
     return {
         ...(rpcUrl !== undefined && { rpcUrl }),
-        facilitatorUrl: env["METAL_FACILITATOR_URL"] ?? network.facilitatorUrl,
+        facilitatorUrl: flags.facilitatorUrl ?? env["METAL_FACILITATOR_URL"] ?? network.facilitatorUrl,
         demoPayeeUrl: env["METAL_DEMO_PAYEE_URL"] ?? file.demoPayeeUrl,
         ...(faucetUrl !== undefined && { faucetUrl }),
         ...(file.explorerUrl !== undefined && { explorerUrl: file.explorerUrl }),

package/dist/commands/fund.js

@@ -8,7 +8,7 @@ const DEVNET_PRINCIPAL_KEY = "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efc
 // Gas and the 1-per-gas fee are explicit for the reason
 // `buildSubmitAuthorizationTx` gives.
 const FUND_GAS_LIMIT = 200000n;
-export async function fund(target, addressArg, amountArg, print, fetchImpl = fetch) {
+export async function fund(target, addressArg, amountArg, print, fetchImpl = fetch, keyImport = true) {
     if (!addressArg || !isAddress(addressArg))
         throw new Error("fund needs the agent's address");
     const to = getAddress(addressArg);
@@ -16,7 +16,7 @@ export async function fund(target, addressArg, amountArg, print, fetchImpl = fet
         if (amountArg !== undefined) {
             throw new Error("on testnet the faucet sets the amount; run fund without --amount");
         }
-        await fundFromFaucet(target, to, print, fetchImpl);
+        await fundFromFaucet(target, to, print, fetchImpl, keyImport);
         return;
     }
     const publicClient = rpcClient(target);
@@ -29,20 +29,24 @@ export async function fund(target, addressArg, amountArg, print, fetchImpl = fet
     });
     print(`balance ${formatUsdz(balance)} ${USDZ.symbol}`);
 }
-async function fundFromFaucet(target, to, print, fetchImpl) {
+async function fundFromFaucet(target, to, print, fetchImpl, keyImport) {
     if (!target.faucetUrl)
         throw new Error(`no faucet is configured for ${target.network.name}`);
     const url = new URL("/api/fund", target.faucetUrl);
+    // The Metal console funds through the same faucet, so an unreachable one is not sent there.
     const response = await fetchImpl(url, {
         method: "POST",
         headers: { "content-type": "application/json" },
         body: JSON.stringify({ address: to, symbol: "USDZ" }),
+    }).catch((error) => {
+        const cause = error.cause;
+        throw new Error(`the faucet at ${url} could not be reached (${typeof cause?.code === "string" ? cause.code : error instanceof Error ? error.message : String(error)}); retry shortly`);
     });
     const text = await response.text();
     if (response.ok) {
         const grant = safeJson(text);
         if (!grant?.txHash || !grant.amount)
-            throw new Error(unexpectedAnswer(url, response, "a transaction"));
+            throw new Error(`${unexpectedAnswer(url, response)} without a transaction`);
         // The faucet answers 200 only once the grant's receipt shows success.
         print(`funded ${to} with ${formatUsdz(grant.amount)} ${USDZ.symbol} from the testnet faucet`);
         print(`transaction ${grant.txHash}`);
@@ -56,27 +60,37 @@ async function fundFromFaucet(target, to, print, fetchImpl) {
         return;
     }
     if (!error && response.status === 429) {
-        throw new Error("faucet answered 429: the faucet's edge rate limit refused this client; retry shortly");
+        throw new Error(`faucet answered 429: the faucet's edge rate limit refused this client; retry shortly${consoleFaucet(target)}`);
     }
+    if (!error && response.status >= 500)
+        throw new Error(`${unexpectedAnswer(url, response)}: the faucet could not be reached; retry shortly`);
     if (!error)
-        throw new Error(unexpectedAnswer(url, response, "an error code"));
-    throw new Error(`faucet answered ${response.status} ${error.code}: ${faucetRefusal(error)}`);
+        throw new Error(`${unexpectedAnswer(url, response)} without an error code`);
+    throw new Error(`faucet answered ${response.status} ${error.code}: ${faucetRefusal(error, consoleFaucet(target), keyImport ? ", or load a funded key with `metal-agent key import`" : "")}`);
+}
+// The public faucet limits every client behind one IP address together; the
+// Metal console's faucet grants per signed-in user, so a refused client is sent there.
+function consoleFaucet(target) {
+    if (!("consoleUrl" in target.network.rpc))
+        return "";
+    // The console's host alone, so a URL redacted to its host still reads.
+    return `, or fund it from the Faucet page of the Metal console at ${target.network.rpc.consoleUrl}, which grants per signed-in user`;
 }
 // Describes the response instead of quoting it, because a proxy in front of
 // the faucet answers with a full HTML document.
-function unexpectedAnswer(url, response, missing) {
+function unexpectedAnswer(url, response) {
     const mediaType = response.headers.get("content-type")?.split(";")[0]?.trim() || "no content type";
-    return `faucet answered ${response.status} ${mediaType} from ${url} without ${missing}`;
+    return `faucet answered ${response.status} ${mediaType} from ${url}`;
 }
-function faucetRefusal(error) {
-    const keyImport = "or load a funded key with `metal-agent key import`";
+function faucetRefusal(error, console, orKeyImport) {
     switch (error.code) {
         case "client_rate_limited":
-            return `this client asked the faucet too recently; ${error.retryAfter === undefined ? "retry shortly" : `retry in ${error.retryAfter} s`}`;
+            return `this client asked the faucet too recently; ${error.retryAfter === undefined ? "retry shortly" : `retry in ${error.retryAfter} s`}${console}`;
         case "client_daily_limit_reached":
-            return `this client reached its daily faucet limit; try tomorrow, ${keyImport}`;
+            return `this client reached its daily faucet limit; try tomorrow${console}${orKeyImport}`;
         case "daily_limit_reached":
-            return `the faucet reached its daily grant limit for every client; try tomorrow, ${keyImport}`;
+            // The Metal console's faucet counts against the same daily limit.
+            return `the faucet reached its daily grant limit for every client; try tomorrow${orKeyImport}`;
         default:
             return error.message;
     }

package/dist/commands/key.js

@@ -1,6 +1,6 @@
 import { readFile } from "node:fs/promises";
 import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
-import { DEFAULT_KEY_PATH, isPrivateKey, writeKey } from "../keystore.js";
+import { defaultKeyPath, isPrivateKey, writeKey } from "../keystore.js";
 export async function keyCreate(out, print) {
     await store(generatePrivateKey(), out, print);
 }
@@ -13,7 +13,7 @@ export async function keyImport(source, out, print) {
     await store(privateKey, out, print);
 }
 async function store(privateKey, out, print) {
-    const path = out ?? DEFAULT_KEY_PATH;
+    const path = out ?? defaultKeyPath();
     const { address } = privateKeyToAccount(privateKey);
     await writeKey(path, { address, privateKey });
     print(`address ${address}`);