@metalntwx/metal-agent 0.2.0 → 0.3.0

package/README.md

@@ -25,7 +25,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
@@ -93,34 +94,34 @@ 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 none is funded first. 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. 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,25 +133,28 @@ 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`, `refused`, `held` when the payee's
+receive policy sends it to escrow, or `pending`. A pending pull is kept in
+the directory beside the credential, `mandate.pulls` for `mandate.json`, and
+running the same command again sends that same pull, which pays at most once.
 
 `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

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 }),