@metalntwx/metal-pay 0.2.0 → 0.3.0

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
@@ -17,10 +16,12 @@ 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
+`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 +47,78 @@ 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. Retry an unknown outcome using the same invoice before another payment.
+
+`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. 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, 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.
+`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
+[service README](../../apps/clearing-service/README.md) 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
@@ -98,9 +135,11 @@ 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