@metalntwx/metal-pay 0.2.0 → 0.3.1

package/README.md

@@ -2,10 +2,9 @@
 
 Agent payments on Metal for the official x402 packages: registers the Metal
 devnet (`eip155:1337`) and testnet (`eip155:63825`) for the `exact` scheme,
-priced in `*USDZ`, for both sides of a payment, and adds Metal's clearing
-lane for payers who pay per call without a transaction each time, and
-mandates, which let an agent pay from its owner's account within limits
-Metal enforces.
+priced in `*USDZ`, for both sides of an on-chain payment, and mandates,
+which let an agent pay from its owner's account within limits Metal
+enforces.
 
 ```bash
 npm install @metalntwx/metal-pay @x402/core viem
@@ -16,11 +15,14 @@ client; `registerMetalNetworks(client, { signer, networks? })`
 registers the scheme on an `x402Client` you already have. Both refuse,
 before signing, a Metal `exact` offer in any token but `*USDZ` or under any
 EIP-712 domain but USDZ's. `createMetalPaymentClient` also refuses any offer
-above `maxAmount`, a `bigint` in `*USDZ` base units. The default is
-`DEFAULT_MAX_PAYMENT`, 1 `*USDZ`. It works with `@x402/*` 2.21 and later.
-From 2.23 the stock client pays only tokens in its own table unless its spend
-controls list others; `createMetalPaymentClient` lists `*USDZ` there, capped
-at `maxAmount`. On a client of your own, add
+above `maxAmount`, a `bigint` in `*USDZ` base units, except a clearing
+offer, which its wallet's own `maxAmount` caps. The default is
+`DEFAULT_MAX_PAYMENT`, 1 `*USDZ`. It works with `@x402/core`, `@x402/evm`
+and `@x402/fetch` from 2.28 up to the next major, installed as its peers
+(npm 7+ and pnpm do that themselves). The stock client pays only tokens in
+its own table unless its spend controls list others;
+`createMetalPaymentClient` turns them off on its client, so its own refusals
+name the offer. On a client of your own, add
 `{ network, asset: USDZ.address }` to `setSpendControls({ allowedAssets })`.
 A paid request is never redirected to another origin, so no other site
 receives the payment. `createMandatePaymentClient` does the same.
@@ -46,42 +48,98 @@ registers `ExactEvmScheme` for other networks, add
 `facilitatorUrl` is Metal's x402 facilitator for it:
 `https://x402-testnet.metalntwx.com/x402/facilitator` on testnet, and
 `http://127.0.0.1:7090/x402/facilitator` on devnet, where
-`just x402-facilitator` runs it. It settles `exact` payments for any
-seller; a seller Metal issued a token to sends it with `sellerToken(token)`,
-the `createAuthHeaders` option, and clearing settlement needs one.
+`just x402-facilitator` runs it. It settles payments for any seller, in
+either scheme; a seller Metal issued a token to sends it with
+`sellerToken(token)`, the `createAuthHeaders` option, and `GET
+/settlements` then lists its payments under that label. To also take
+clearing, register `new ClearingServerScheme(network)` on that network
+beside `exact` and list a `bajillion` offer whose `payTo` is the seller's
+clearing key; the offer names the Clearing deployment the facilitator lists
+in `/supported` and binds its invoices to the resource.
 
 ```typescript
 import { HTTPFacilitatorClient, x402ResourceServer } from "@x402/core/server";
 import { paymentMiddleware } from "@x402/hono";
 import { METAL_NETWORKS, registerMetalScheme } from "@metalntwx/metal-pay";
 
-const facilitator = new HTTPFacilitatorClient({ url: METAL_NETWORKS.devnet.facilitatorUrl });
+const facilitator = new HTTPFacilitatorClient({
+  url: METAL_NETWORKS.devnet.facilitatorUrl,
+});
 const server = registerMetalScheme(new x402ResourceServer(facilitator));
 app.use(
   paymentMiddleware(
-    { "GET /quote": { accepts: { scheme: "exact", network: "eip155:1337", payTo: "0x…", price: "0.01" } } },
+    {
+      "GET /quote": {
+        accepts: {
+          scheme: "exact",
+          network: "eip155:1337",
+          payTo: "0x…",
+          price: "0.01",
+        },
+      },
+    },
     server,
   ),
 );
 ```
 
-**Clearing.** Sellers register `ClearingDebitServerScheme` next to the `exact`
-scheme and list a `clearing-debit` offer in a route's `accepts`; payers pass a
-`ClearingDebitScheme` as `createMetalPaymentClient`'s `clearing`, which pays
-by clearing, and by `exact` while custody is short or when the seller cannot
-take clearing (the facilitator settles clearing only for sellers Metal issued
-a token), and fund custody with `depositToClearing`. Given the facilitator, it
-waits until the facilitator counts the deposit, so the next payment can draw
-on it. On an x402 client of your own, give it the scheme's selector,
-`new x402Client(clearing.prefer)`, and its fetch,
-`wrapFetchWithPayment(clearing.wrapFetch(fetch), client)`, so a Debit whose
-answer never arrived, or arrived as a bare server error, is presented again
-rather than paid twice, for as long as the client runs. `withdrawFromClearing` takes custody out
-once the epoch holding it has closed and passed its challenge window, and says so
-when that has not happened yet. `@metalntwx/metal-pay/file-storage` keeps a
-clearing payer's record across restarts (Node only). The facilitator's
-[README](https://github.com/mx56db/metal/tree/main/apps/x402-facilitator)
-covers the lane.
+## Native Bajillion payments
+
+`createClearingClient` signs cumulative P-256 payments and retains the exact
+pending authorization across transport errors. Supply trusted `serviceUrl`,
+`rpcUrl`, `network`, `settlement`, `asset`, a signer, an atomic store and a
+`maxAmount` limit. In Node 22.13 or later (23.4 or later on Node 23),
+`openClearingWallet(directory)` from `@metalntwx/metal-pay/node` supplies a
+persistent signer and store with exclusive
+process ownership. Preserve that directory across restarts; call `close()` on
+shutdown. A payment the service does not take throws a `ClearingRefusal`,
+whose `reason` is `between_epochs`, `insufficient_deposit`, `answer_lost`
+or `payment_held` and whose `retry` says what to do: wait `retry.ms`
+(again after each further `between_epochs`), deposit, or send the held
+request, `retry.url` at `retry.amount`, again after `retry.ms` before any
+other. If that URL no longer offers clearing at that price, pass the
+client's `pendingInvoice()` to its `pay`. A held payment sent again is
+settled from the service's receipt when it kept one, and released when it
+has none and its epoch has closed or is no longer the service's live one.
+A wallet's record is for one Clearing deployment: open a new wallet for a
+replacement. Through `createMetalPaymentClient`'s `fetchWithPayment` it is
+the thrown error's `cause`.
+
+`clearingRequirements` and `clearingInvoice` bind an invoice to a resource,
+recipient, amount and deployment. `registerClearingClient` adds the `bajillion`
+scheme to an official x402 client, which then pays by clearing wherever its
+wallet can pay the offer and refuses any other request on that
+registration's network, unless given `{ exactFallback: true }` to pay it by
+`exact`. Behind the stock middleware,
+Metal's facilitator verifies and deduplicates clearing payments before the
+handler runs. A seller that verifies them itself calls
+`verifyClearingPayment` with its own trusted
+RPC/service configuration and deduplicates `clearingPaymentId` in durable
+storage before delivering. The returned receipt is **preconfirmed**;
+watch `Clearing.finalizedCount` before labeling its epoch finalized. It is not
+an EVM transaction hash.
+
+`depositToClearing` funds a clearing account from an EVM account, waiting
+for the contract's deposit window; `clearingSpendable` reads the service's
+estimate of what the account can spend, in token base units, which counts
+a deposit from the epoch after it lands and can read low around an
+epoch's close, and
+`clearingBalance` the finalized balance and its proof, in clearing units
+(`Clearing.unit()` base units each, a millionth of `*USDZ`);
+`withdrawFromClearing` queues a withdrawal of the finalized balance and,
+once its epoch has finalized, claims it, for payer and seller alike; it
+answers `empty` when there is nothing finalized to claim or queue. A
+queue or claim refused because an epoch finalized under its proof moved
+nothing, and its error says to call again after the next epoch.
+`clearingClose` and `clearingLogProof` are the pieces it is built from.
+`recoverFromClearing` takes an account's funds out of a deployment whose
+service has missed a deadline: it faults the deployment, starts recovery,
+and takes the payout of the account's finalized withdrawal, its last
+finalized balance and its uncounted deposits, with proofs from the service
+or the first of several validators that retained the epoch. The clearing
+service's README, `apps/clearing-service/README.md` in the Metal
+repository, describes operator/validator setup, receipt retention and proof
+endpoints.
 
 **Mandates.** `@metalntwx/metal-pay/mandates` lets an agent pay from its
 owner's account with a P-256 key of its own, within limits Metal enforces on
@@ -90,23 +148,31 @@ budget, how many payments, an expiry) as a Verifiable Intent mandate;
 `ingestCredential` verifies one against the issuers the owner trusts, and
 `bindCall`, `replaceCall` and `revokeCall` build the owner's transactions to its own
 MetalAccount. Wrap those calls with `authorizeMandateCall(client, trustedFactory,
-call, signQuorum)` to authorize an account self-call, or a list of them as one
+call, validUntil, signQuorum)` to authorize an account self-call, or a list of them as one
 batch that runs whole or not at all, with its existing weighted quorum. The
-client must name its chain: the digest the quorum signs is computed from it,
-never read from the RPC endpoint. The callback supports the same EOA, P-256 and passkey signatures as
-ordinary account execution. Factory-created clones share an immutable VI
+account refuses the signed batch after `validUntil` (unix seconds, a `bigint`), so
+give it a short deadline. The client must name its chain: the digest the quorum
+signs is computed from it, never read from the RPC endpoint. The callback
+supports the same EOA, P-256 and passkey signatures as ordinary account
+execution. Factory-created clones share an immutable VI
 verifier; budgets and replay protection live in each account. `createMandatePaymentClient({ credential, signDigest, network })`
 is the payer, and `MandateExactScheme` the same payer as a scheme for an
 `x402Client` of your own: each payment is an ERC-3009 authorization from the
-owner's account whose signature is the agent's per-payment mandate, which
-the account accepts or refuses through ERC-1271. Sellers and facilitators
-see an ordinary `exact` payment. The client sets no limit of its own.
+owner's account whose signature is the agent's per-payment mandate; Metal's
+facilitator submits it as `pull` on the owner's account, which checks it
+against the mandate, spends the budget and hands the token the
+authorization. Sellers see an ordinary `exact` payment. The client sets no
+limit of its own.
 `readCheck` names the limit behind a refusal, `readMandateState` reads the
 spend, and `pullCall` builds a direct payment with no seller. A credential's amounts
 are decimal, to the cent. `verifyMandate` and `verifyMandatePayment` trust the
 MetalAccountFactory `METAL_NETWORKS` names for the chain, or the
 `accountFactory` given, check the account's clone code against the
 factory's current implementation, and match the successful token transfer to the seller's requirements.
+`verifyMandatePayment` checks a `checkoutMandate` against the payment, failing one of another
+payment as such; its step 4 says when none was given, so no order was checked.
+An event under the mandate that the SDK does not decode, as an account of
+another version emits, fails the verification with its topic and the account.
 The module runs on Node only.
 
 **RPC.** Neither payers nor payees need one. Each network's `rpc` is its