@metalntwx/metal-pay 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nexus Networks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,115 @@
-# Temporary Holding Version
+# @metalntwx/metal-pay
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+
+```bash
+npm install @metalntwx/metal-pay @x402/core viem
+```
+
+**Payers.** `createMetalPaymentClient` gives an agent a one-call payment
+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
+`{ network, asset: USDZ.address }` to `setSpendControls({ allowedAssets })`.
+
+```typescript
+import { privateKeyToAccount } from "viem/accounts";
+import { createMetalPaymentClient } from "@metalntwx/metal-pay";
+
+const { fetchWithPayment } = createMetalPaymentClient({
+  account: privateKeyToAccount("0x…"),
+  network: "devnet",
+});
+const response = await fetchWithPayment("http://127.0.0.1:4021/quote");
+```
+
+**Payees.** `registerMetalScheme(server, { networks? })` registers the
+stock `exact` scheme on an `x402ResourceServer` with `metalUsd`, the money
+parser that prices dollar amounts in `*USDZ` and names the ERC-3009
+message the payer signs (`primaryType: "TransferWithAuthorization"`); mount it with the official
+x402 middleware (`@x402/hono`, `@x402/express`). On a server that already
+registers `ExactEvmScheme` for other networks, add
+`registerMoneyParser(metalUsd(network))` to it instead. Each network's
+`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.
+
+```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 server = registerMetalScheme(new x402ResourceServer(facilitator));
+app.use(
+  paymentMiddleware(
+    { "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.
+
+**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
+chain. `createCredential` writes the limits (payees, the most per payment, a
+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 with its existing weighted
+quorum. 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.
+`readCheck` names the limit behind a refusal, `readMandateState` reads the
+spend, and `pullCall` builds a direct payment with no seller. Amounts are
+whole cents. `verifyMandate` and `verifyMandatePayment` trust the
+MetalAccountFactory `METAL_NETWORKS` names for the chain, or the
+`accountFactory` given, authenticate clone code at the binding and settlement
+blocks, and match the successful token transfer to the seller's requirements.
+The module runs on Node only.
+
+**RPC.** Neither payers nor payees need one. Each network's `rpc` is its
+default JSON-RPC endpoint, `{ url }` on devnet, or `{ consoleUrl }` on
+testnet, where each user signs up in the console and creates an endpoint of
+their own. `rpcUrlFor(network, override, how)` returns the override or the
+default, and otherwise throws one line saying how to get an endpoint from the
+console and `how` to pass it.
+
+`viem` is a peer dependency. Run `pnpm test` and `pnpm typecheck`.

package/dist/clearing-client.d.ts

@@ -0,0 +1,168 @@
+import type { PaymentPayloadResult, PaymentRequirements, SchemeClientHooks, SchemeNetworkClient } from "@x402/core/types";
+import { type Address, type Hex, type LocalAccount } from "viem";
+/** What signs: a viem local account, or anything with an address and
+ * EIP-712 `signTypedData`. */
+export interface ClearingSigner {
+    readonly address: Address;
+    signTypedData(args: {
+        domain: Record<string, unknown>;
+        types: Record<string, unknown>;
+        primaryType: string;
+        message: Record<string, unknown>;
+    }): Promise<Hex>;
+}
+export interface ClearingDebitSchemeOptions {
+    /** The facilitator this payer trusts to report its position: Metal's,
+     * `https://<facilitator host>/x402/facilitator`. */
+    facilitator: string;
+    /** Where the highest total signed each epoch is remembered. Default: in
+     * memory, which does not survive a restart. */
+    storage?: ClearingPositionStorage;
+    fetch?: typeof globalThis.fetch;
+    /** Clock, in milliseconds. Default: wall time. */
+    now?: () => number;
+}
+/** The payer's position as stored: the epoch, the next debit index and the
+ * running total it last signed. Decimal strings, so any store can hold it. */
+export interface StoredClearingPosition {
+    epoch: string;
+    /** The next debit index, after the debit signed last. */
+    index: string;
+    /** The running total of the debit signed last. */
+    cumulativeDebit: string;
+    /** The highest running total ever signed in this epoch. It never goes
+     * down, so a stale or low report cannot weaken the check made against it. */
+    highestSigned: string;
+}
+/** Where positions are kept: one record per network, Clearing contract,
+ * payer and epoch. */
+export interface ClearingPositionStorage {
+    get(key: string): Promise<StoredClearingPosition | undefined>;
+    /** Store the position. An implementation MUST keep the larger of the
+     * stored and the new `highestSigned`, atomically with the write: two
+     * clients sharing a store sign in between each other's reads and writes,
+     * and the mark must never move down. `keepHighest` does the merge. */
+    set(key: string, position: StoredClearingPosition): Promise<void>;
+}
+/** `next`, with `highestSigned` no lower than the one already stored. */
+export declare function keepHighest(existing: StoredClearingPosition | undefined, next: StoredClearingPosition): StoredClearingPosition;
+/** The default store: positions do not survive a process restart. */
+export declare class InMemoryClearingPositionStorage implements ClearingPositionStorage {
+    private readonly positions;
+    get(key: string): Promise<StoredClearingPosition | undefined>;
+    set(key: string, position: StoredClearingPosition): Promise<void>;
+}
+export declare class ClearingDebitScheme implements SchemeNetworkClient {
+    private readonly signer;
+    readonly scheme = "clearing-debit";
+    readonly schemeHooks: SchemeClientHooks;
+    private readonly facilitator;
+    private readonly storage;
+    private readonly doFetch;
+    private readonly now;
+    /** Per payer and contract: the facilitator's last answer, adjusted for
+     * what this client has signed since. */
+    private readonly positions;
+    /** Per payer and contract: until when to pay the standard way. */
+    private readonly shortUntil;
+    /** Sellers the facilitator settles no clearing for, by network, contract
+     * and payee: a seller without Metal's seller token. That holds for as long
+     * as the client runs, so they are paid the standard way from then on. */
+    private readonly standardOnly;
+    /** Per payer and contract: the Debits whose outcome is in doubt, each to
+     * be presented again for its own offer. Only an answer about that Debit
+     * clears it. */
+    private readonly unresolved;
+    constructor(signer: ClearingSigner, options: ClearingDebitSchemeOptions);
+    /** The selector to give `new x402Client(...)`: the clearing offer, unless
+     * custody was lately found short or the seller cannot take clearing, in
+     * which case the standard one. A Debit whose outcome is in doubt is always
+     * presented again by clearing. */
+    readonly prefer: (_x402Version: number, accepts: PaymentRequirements[]) => PaymentRequirements;
+    /** One payment at a time per payer and contract: reading the position,
+     * signing and recording it must not interleave, or two payments would sign
+     * the same index. */
+    private readonly queues;
+    private exclusive;
+    private key;
+    private sellerOf;
+    /** The fetch to give `wrapFetchWithPayment`. A request carrying a Debit
+     * that fails without an answer, or ends in a server error that says
+     * nothing about the Debit (a proxy's 502 or 504), may still have been
+     * admitted, so its Debit is held in doubt: the next payment for that offer
+     * presents it again. It is held in memory, for as long as the client
+     * runs. */
+    wrapFetch(fetch: typeof globalThis.fetch): typeof globalThis.fetch;
+    /** Holds the Debit a request carried, if it carried one of this client's. */
+    private holdSent;
+    private hold;
+    /** Clears a Debit once a seller has answered about it. */
+    private release;
+    /** What makes two offers the same payment: a Debit signed for one can be
+     * presented again for the other. */
+    private offerId;
+    /** Where the next Debit starts: the facilitator's answer while it is
+     * fresh, else a new one. */
+    private position;
+    createPaymentPayload(x402Version: number, requirements: PaymentRequirements): Promise<PaymentPayloadResult>;
+    private sign;
+}
+/** Put funds into clearing custody. `from` pays and sends the transactions:
+ * the agent's own wallet, or anyone funding it, in which case `account` is
+ * the agent's address. The tokens go from `from` straight into custody under
+ * `account`; only `account`'s signature can spend or withdraw them.
+ *
+ * Two transactions (an approval for exactly this amount, unless that much
+ * is already approved, then the deposit), paid for in the network's fee token by `from`. Gas and
+ * fees are set here because a Metal node cannot be asked to estimate them.
+ *
+ * The operator counts a deposit some seconds after its receipt, and refuses
+ * clearing payments against it until then. Given `facilitator`, this waits
+ * until the facilitator reports the deposit in the payer's position, so the
+ * next payment can draw on it. */
+export declare function depositToClearing(opts: {
+    rpcUrl: string;
+    chainId: number;
+    from: LocalAccount;
+    /** The Clearing contract and the token it holds, as the 402 names them:
+     * `extra.clearing.contract` and `asset`. */
+    contract: Address;
+    asset: Address;
+    /** Whose custody is credited. Default: `from` itself. */
+    account?: Address;
+    amount: bigint;
+    /** The facilitator to wait on until it counts the deposit, as for
+     * `ClearingDebitScheme`. Only `from`'s own custody can be waited on: the
+     * position request is signed by the account it is about. */
+    facilitator?: string;
+    /** How long to wait for the facilitator to count it. Default: 60 s. */
+    timeoutMs?: number;
+    /** How often to ask. Default: every second. */
+    pollMs?: number;
+    fetch?: typeof globalThis.fetch;
+}): Promise<{
+    approveTx: Hex | null;
+    depositTx: Hex;
+    available?: bigint;
+}>;
+/** Take funds out of clearing custody: a payer's unused deposit, or what a
+ * seller has been paid. It asks the facilitator what can be withdrawn, signs
+ * an Exit for that amount, and submits it; Metal's operator sends the two
+ * transactions (request, then release) and pays their gas.
+ *
+ * Only this wallet's signature moves its funds, and only to the destination
+ * it names, which defaults to the wallet itself. */
+export declare function withdrawFromClearing(signer: ClearingSigner, facilitator: string, options: {
+    network: string;
+    /** Where the funds go. Default: the wallet itself. */
+    destination?: Address;
+    /** How much to withdraw, in base units. Default: everything available. */
+    amount?: bigint;
+    fetch?: typeof globalThis.fetch;
+    /** Clock, in milliseconds. Default: wall time. */
+    now?: () => number;
+}): Promise<{
+    amount: bigint;
+    requestTx: string;
+    releaseTx: string | null;
+}>;