@metalntwx/metal-pay 0.2.0 → 0.3.1

package/dist/clearing-custody.js

@@ -0,0 +1,552 @@
+import { BaseError, ContractFunctionRevertedError, concatHex, createPublicClient, createWalletClient, encodeFunctionData, erc20Abi, FeeCapTooHighError, FeeCapTooLowError, InsufficientFundsError, IntrinsicGasTooHighError, IntrinsicGasTooLowError, keccak256, NonceMaxValueError, NonceTooHighError, parseEventLogs, sha256, stringToHex, TipAboveFeeCapError, TransactionTypeNotSupportedError, } from "viem";
+import { getNodeError } from "viem/utils";
+import { clearingAbi } from "./clearing-abi.js";
+import { clearingUint64, clearingUnits } from "./clearing-codec.js";
+import { formatUsdz, rpcTransport, USDZ } from "./networks.js";
+export function clearingLogProof(proof) {
+    return {
+        ...proof,
+        location: BigInt(proof.location),
+        leaves: BigInt(proof.leaves),
+        inactivePeaks: BigInt(proof.inactivePeaks),
+    };
+}
+/** Authorize an epoch-tail close to a fixed EVM destination. */
+export async function clearingClose(signer, deployment, balance, destination, deadline) {
+    if (!balance.opening)
+        throw new Error("no retained balance proof");
+    const body = concatHex([
+        deployment,
+        balance.state,
+        "0x14",
+        destination,
+        "0x02",
+        clearingUint64(deadline),
+    ]);
+    const { amount, nextKey, ...proof } = balance.opening;
+    return {
+        withdrawal: {
+            account: signer.publicKey,
+            deployment,
+            state: balance.state,
+            destination,
+            amount: 0n,
+            deadline,
+            signature: await signer.sign("_COMMONWARE_CLEARING_BOUNDARY_WITHDRAWAL", body),
+        },
+        opening: {
+            amount: BigInt(amount),
+            nextKey,
+            proof: clearingLogProof(proof),
+        },
+    };
+}
+/** The most the Clearing contract holds in all, in clearing units: it
+ * counts `uint64` units of `Clearing.unit()` token base units each, a
+ * millionth of the token (its base unit at six decimals or fewer). */
+export const CLEARING_MAX_AMOUNT = 2n ** 64n - 1n;
+/** A clearing service that gave no answer, or a 5xx. */
+class ServiceUnreachable extends Error {
+}
+async function serviceGet(serviceUrl, path, fetcher) {
+    const response = await fetcher(new URL(path, serviceUrl), {
+        signal: AbortSignal.timeout(30_000),
+    }).catch((error) => {
+        throw new ServiceUnreachable(`clearing service gave no answer for ${path} (${error instanceof Error ? error.message : String(error)})`, { cause: error });
+    });
+    if (!response.ok)
+        throw new (response.status >= 500 ? ServiceUnreachable : Error)(`clearing service returned ${response.status} for ${path}`);
+    return (await response.json());
+}
+/** What `account` can still spend in the open epoch, in the token's base
+ * units: the operator's estimate from the balance and deposits it has
+ * counted and the payments it has acknowledged. */
+export async function clearingSpendable(opts) {
+    const pub = createPublicClient({ transport: rpcTransport(opts.rpcUrl) });
+    const [{ amount }, unit] = await Promise.all([
+        serviceGet(opts.serviceUrl, `/spendable/${opts.account}`, opts.fetch ?? globalThis.fetch),
+        pub.readContract({ address: opts.settlement, abi: clearingAbi, functionName: "unit" }),
+    ]);
+    // The service counts clearing units.
+    return BigInt(amount) * unit;
+}
+/** `account`'s finalized balance in clearing units and, when the service
+ * retains one, the proof `withdrawFromClearing` closes it with. */
+export function clearingBalance(serviceUrl, account, fetcher = globalThis.fetch) {
+    return serviceGet(serviceUrl, `/balance/${account}`, fetcher);
+}
+/** What a node answers when it refuses a transaction outright, leaving
+ * nothing in its pool. */
+const REFUSALS = [
+    InsufficientFundsError,
+    FeeCapTooLowError,
+    FeeCapTooHighError,
+    TipAboveFeeCapError,
+    IntrinsicGasTooLowError,
+    IntrinsicGasTooHighError,
+    NonceTooHighError,
+    NonceMaxValueError,
+    TransactionTypeNotSupportedError,
+];
+/** Gas and fees are set here: on Metal, a fee-carrying `eth_estimateGas`
+ * from an account with no native balance fails. */
+function chainClients({ rpcUrl, chainId, from, timeoutMs = 60_000, pollMs = 500 }) {
+    const transport = rpcTransport(rpcUrl);
+    const pub = createPublicClient({ transport });
+    const wallet = createWalletClient({ account: from, transport });
+    // The dry run first, under the gas the transaction is sent with, so a
+    // refusal comes back with its reason. The transaction is signed here, so
+    // its hash is known before it is broadcast: once broadcast, any failure to
+    // learn its outcome leaves it in doubt, named, and never sent again here.
+    const send = async (call, gas) => {
+        await pub.simulateContract({ ...call, account: from.address, gas });
+        const [block, nonce] = await Promise.all([
+            pub.getBlock({ blockTag: "latest" }),
+            pub.getTransactionCount({ address: from.address, blockTag: "pending" }),
+        ]);
+        const raw = await wallet.signTransaction({
+            chain: null,
+            chainId,
+            to: call.address,
+            data: encodeFunctionData(call),
+            value: 0n,
+            gas,
+            maxFeePerGas: (block.baseFeePerGas ?? 0n) * 2n + 1n,
+            maxPriorityFeePerGas: 1n,
+            nonce,
+            type: "eip1559",
+        });
+        const hash = keccak256(raw);
+        // The node's error, if any, rides along: a refusal its hash cannot show.
+        const inDoubt = (cause) => new Error(`${call.functionName} ${hash} with nonce ${nonce} was sent and its outcome is unknown: look it up before sending it again`, {
+            cause,
+        });
+        await pub.sendRawTransaction({ serializedTransaction: raw }).catch((error) => {
+            const refusal = error instanceof BaseError ? getNodeError(error, {}) : undefined;
+            if (REFUSALS.some((type) => refusal instanceof type))
+                throw new Error(`the node refused ${call.functionName}: ${refusal.shortMessage}`, { cause: error });
+            throw inDoubt(error);
+        });
+        // A failed read of the receipt is not yet, until the deadline.
+        const deadline = Date.now() + timeoutMs;
+        let unread;
+        for (;;) {
+            const receipt = await pub.getTransactionReceipt({ hash }).catch((error) => {
+                unread = error;
+                return null;
+            });
+            if (receipt)
+                return receipt;
+            if (Date.now() >= deadline)
+                throw inDoubt(unread);
+            await new Promise((resolve) => setTimeout(resolve, pollMs));
+        }
+    };
+    return { pub, send };
+}
+function succeeded(functionName, receipt) {
+    if (receipt.status !== "success")
+        throw new Error(`${functionName} reverted: ${receipt.transactionHash}`);
+    return receipt.transactionHash;
+}
+/** A withdrawal's queue or claim refused, by its dry run or as a mined
+ * revert (`tx`), because an epoch finalized after the service proved it:
+ * the contract checks a proof against its finalized state alone. */
+function finalizedUnder(functionName, tx, cause) {
+    return new Error(`${tx ? `${functionName} ${tx} reverted` : `${functionName} was refused`} because an epoch finalized under it, so the service's proof is for the state before; nothing was lost${tx ? " but its gas" : ""}: make the same call again after the next epoch`, cause === undefined ? {} : { cause });
+}
+/** Put `amount` token base units into clearing custody under `account`, a
+ * clearing key; it must be a whole number of the contract's clearing
+ * units. `from` pays: an approval for the amount unless one that covers it
+ * stands, then the deposit. The contract takes deposits only between
+ * registrations, so the deposit waits for that window and is sent again
+ * if the window closes under it, up to `timeoutMs` (default 60 s). It
+ * refuses at once a contract that holds another token, and a deposit past
+ * what the contract holds in all. A deposit the token refuses because
+ * `from` holds less fails naming what `from` holds and what the deposit
+ * needs. A deposit whose outcome is unknown is not sent again: the error
+ * names it. */
+export async function depositToClearing(opts) {
+    if (opts.amount <= 0n)
+        throw new Error("deposit amount must be positive");
+    const { pub, send } = chainClients(opts);
+    const contract = { address: opts.settlement, abi: clearingAbi };
+    const [token, unit] = await Promise.all([
+        pub.readContract({ ...contract, functionName: "token" }),
+        pub.readContract({ ...contract, functionName: "unit" }),
+    ]);
+    if (token.toLowerCase() !== opts.asset.toLowerCase())
+        throw new Error(`this Clearing contract holds ${token}, not ${opts.asset}`);
+    // The contract counts clearing units; the approval moves base units.
+    const units = clearingUnits(opts.amount, unit);
+    // The contract refuses a deposit past this, with the same error as a closed window.
+    const assertRoom = async () => {
+        const [active, reserve] = await Promise.all([
+            pub.readContract({ ...contract, functionName: "activeCustody" }),
+            pub.readContract({ ...contract, functionName: "claimReserve" }),
+        ]);
+        const room = CLEARING_MAX_AMOUNT - active - reserve;
+        if (units > room)
+            throw new Error(`this Clearing contract holds at most ${CLEARING_MAX_AMOUNT * unit} base units in all, and has room for ${room * unit} more`);
+    };
+    await assertRoom();
+    const allowance = await pub.readContract({
+        address: opts.asset,
+        abi: erc20Abi,
+        functionName: "allowance",
+        args: [opts.from.address, opts.settlement],
+    });
+    const approveTx = allowance >= opts.amount
+        ? null
+        : succeeded("approve", await send({ address: opts.asset, abi: erc20Abi, functionName: "approve", args: [opts.settlement, opts.amount] }, 100000n));
+    const deposit = { ...contract, functionName: "deposit", args: [opts.account, units] };
+    // About 450k on Metal, which charges 64 times Ethereum's gas for the modexp
+    // that decompresses the account's key.
+    const depositGas = 1000000n;
+    const deadline = Date.now() + (opts.timeoutMs ?? 60_000);
+    // Only the closed window is waited out; any other refusal is the caller's.
+    // A full contract reverts the same way, and `assertRoom` tells them apart.
+    const windowClosed = (error) => error instanceof BaseError &&
+        error.walk((e) => e instanceof ContractFunctionRevertedError && e.data?.errorName === "InvalidBoundary") !== null;
+    // The token refuses a transfer past what `from` holds with the reason
+    // "balance"; what it holds is read after the refusal.
+    const shortOf = async (error) => {
+        if (!(error instanceof BaseError && error.walk((e) => e instanceof ContractFunctionRevertedError && e.reason === "balance")))
+            return undefined;
+        const held = await pub.readContract({ address: opts.asset, abi: erc20Abi, functionName: "balanceOf", args: [opts.from.address] });
+        return `${opts.from.address} holds ${formatUsdz(held)} ${USDZ.symbol} and the deposit needs ${formatUsdz(opts.amount)} ${USDZ.symbol}; fund it or deposit less`;
+    };
+    for (;;) {
+        // A deposit that reverts deposited nothing, and the next dry run says
+        // why: if the window closed under it, the next round waits for the next
+        // one; any other reason is named with the reverted deposit.
+        try {
+            const receipt = await send(deposit, depositGas);
+            if (receipt.status === "success")
+                return { approveTx, depositTx: receipt.transactionHash };
+            const why = await pub
+                .simulateContract({ ...deposit, account: opts.from.address, gas: depositGas })
+                .then(() => undefined, (error) => error);
+            if (!windowClosed(why)) {
+                const short = await shortOf(why);
+                throw new Error(`deposit ${receipt.transactionHash} reverted${short ? `: ${short}` : why instanceof BaseError ? `: ${why.shortMessage}` : ", and its dry run now passes"}`);
+            }
+        }
+        catch (error) {
+            if (!windowClosed(error)) {
+                const short = await shortOf(error);
+                throw short ? new Error(`the deposit was refused, and nothing was deposited: ${short}`, { cause: error }) : error;
+            }
+        }
+        await assertRoom();
+        if (Date.now() >= deadline)
+            throw new Error("the Clearing contract took no deposits before the timeout");
+        await new Promise((resolve) => setTimeout(resolve, opts.pollMs ?? 500));
+    }
+}
+const accountKey = (account) => sha256(concatHex([stringToHex("_COMMONWARE_CLEARING_ACCOUNT_KEY"), account]));
+/** `account`'s payout of its withdrawal in the finalized epoch `epoch` to
+ * `destination`, the one the withdrawal named, from the first of
+ * `serviceUrls` that proves it. */
+async function lookupPayout(serviceUrls, fetcher, epoch, account, destination) {
+    const failures = [];
+    const unreachable = [];
+    for (const serviceUrl of serviceUrls) {
+        try {
+            const payout = await serviceGet(serviceUrl, `/payout/${epoch}/${account}`, fetcher);
+            if (!payout)
+                failures.push(`${serviceUrl} has none`);
+            else if (payout.destination.toLowerCase() !== destination.toLowerCase())
+                failures.push(`${serviceUrl} names ${payout.destination}, not ${destination}, the destination the withdrawal named`);
+            else
+                return payout;
+        }
+        catch (error) {
+            if (error instanceof ServiceUnreachable)
+                unreachable.push(error);
+            failures.push(`${serviceUrl}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    throw new Error(`no clearing service named proves the payout of this account's withdrawal in epoch ${epoch}; a validator proves it once it has retained that epoch (${failures.join("; ")})`, 
+    // None of them answered.
+    unreachable.length === serviceUrls.length ? { cause: unreachable[0] } : {});
+}
+/** Claims `payout` to `destination` unless it is 0 or claimed already. The
+ * claim is pushed to `claimed` as it lands. */
+async function claimPayout({ pub, send, settlement, unit }, payout, destination, claimed) {
+    const contract = { address: settlement, abi: clearingAbi };
+    if (BigInt(payout.amount) === 0n)
+        return;
+    const position = BigInt(payout.proof.location);
+    const consumed = await pub.readContract({ ...contract, functionName: "claimedPayouts", args: [position >> 8n] });
+    if (consumed & (1n << (position & 255n)))
+        return;
+    // The proof is for the payouts log the service read as finalized; once a
+    // later epoch finalizes, the contract's log is longer and refuses it.
+    const moved = async () => (await pub.readContract({ ...contract, functionName: "finalizedPayouts" }))[1] !== BigInt(payout.proof.leaves);
+    const receipt = await send({ ...contract, functionName: "claim", args: [destination, BigInt(payout.amount), clearingLogProof(payout.proof)] }, 1000000n).catch(async (error) => {
+        throw revertOf(error) === "InvalidProof" && (await moved()) ? finalizedUnder("claim", undefined, error) : error;
+    });
+    if (receipt.status !== "success" && (await moved()))
+        throw finalizedUnder("claim", receipt.transactionHash);
+    const tx = succeeded("claim", receipt);
+    const deferred = parseEventLogs({ abi: clearingAbi, eventName: "PayoutDeferred", logs: receipt.logs }).length > 0;
+    claimed.push({ amount: BigInt(payout.amount) * unit, tx, deferred });
+}
+/** Take `signer`'s funds out of clearing: claim the account's payout of a
+ * withdrawal that has finalized, to the destination it named, then queue a
+ * withdrawal of whatever finalized balance remains, to `destination` (`from` itself
+ * unless given). A payer's unused deposit and a seller's earnings leave the
+ * same way. Call again after the queued withdrawal's epoch finalizes. A
+ * failure after a claim names the claims made before it. A queue or claim
+ * refused because an epoch finalized under its proof moved nothing: the
+ * error says to call again after the next epoch. */
+export async function withdrawFromClearing(opts) {
+    const { pub, send } = chainClients(opts);
+    const fetcher = opts.fetch ?? globalThis.fetch;
+    const destination = opts.destination ?? opts.from.address;
+    const contract = { address: opts.settlement, abi: clearingAbi };
+    const key = accountKey(opts.signer.publicKey);
+    if ((await pub.readContract({ ...contract, functionName: "fault" })) !== 0)
+        throw new Error("this Clearing deployment has faulted and takes no withdrawals: take the account's funds out with recoverFromClearing");
+    const [status, finalized, unit] = await Promise.all([
+        pub.readContract({ ...contract, functionName: "withdrawals", args: [key] }),
+        pub.readContract({ ...contract, functionName: "finalizedCount" }),
+        pub.readContract({ ...contract, functionName: "unit" }),
+    ]);
+    const [encodedHash, epochPlusOne, , , queuedTo] = status;
+    if (encodedHash !== `0x${"00".repeat(32)}` && (epochPlusOne === 0n || epochPlusOne > finalized)) {
+        const [registered, admitted] = await Promise.all([
+            pub.readContract({ ...contract, functionName: "registered" }),
+            pub.readContract({ ...contract, functionName: "admittedCount" }),
+        ]);
+        // A service that has missed a deadline may never finalize the epoch.
+        for (const call of faultCalls(admitted, opts.signer.publicKey)) {
+            const missed = await pub.simulateContract({ ...contract, ...call, account: opts.from.address }).then(() => true, (error) => {
+                if (revertOf(error) !== "InvalidDeadline")
+                    throw error;
+                return false;
+            });
+            if (missed)
+                throw new Error(`the clearing service has missed a deadline (${call.functionName} would fault the deployment), so the withdrawal may never finalize: take the account's funds out with recoverFromClearing`);
+        }
+        if (epochPlusOne > 0n)
+            return { status: "waiting", epoch: epochPlusOne - 1n };
+        // Not yet registered: the next registration carries it.
+        return { status: "waiting", epoch: registered ? admitted + 1n : admitted };
+    }
+    const claimed = [];
+    try {
+        return await claimThenQueue().catch((error) => {
+            const gone = error instanceof ServiceUnreachable ? error : error instanceof Error && error.cause instanceof ServiceUnreachable ? error.cause : undefined;
+            if (!gone)
+                throw error;
+            throw new Error(`the clearing service could not be reached (${gone.message}): call withdrawFromClearing again once it answers; if it has stopped, pass a validator's URL from the facilitator's /supported extra.validatorUrls as serviceUrl`, { cause: error });
+        });
+    }
+    catch (error) {
+        if (claimed.length === 0)
+            throw error;
+        const made = claimed.map((c) => `${c.amount} in ${c.tx}`).join(", ");
+        throw new Error(`${error instanceof Error ? error.message : String(error)}; claimed before it: ${made}`, { cause: error });
+    }
+    async function claimThenQueue() {
+        if (epochPlusOne > 0n)
+            await claimPayout({ pub, send, settlement: opts.settlement, unit }, await lookupPayout([opts.serviceUrl], fetcher, epochPlusOne - 1n, opts.signer.publicKey, queuedTo), queuedTo, claimed);
+        const unqueued = () => (claimed.length > 0 ? { status: "sent", claimed, queued: null } : { status: "empty" });
+        // The service proves balances only against a finalized epoch.
+        if (finalized === 0n)
+            return unqueued();
+        const balance = await clearingBalance(opts.serviceUrl, opts.signer.publicKey, fetcher);
+        if (BigInt(balance.amount) === 0n)
+            return unqueued();
+        if (!balance.opening)
+            return { status: "sent", claimed, queued: null };
+        const [deployment, policy, block] = await Promise.all([
+            pub.readContract({ ...contract, functionName: "deployment" }),
+            pub.readContract({ ...contract, functionName: "policy" }),
+            pub.getBlock(),
+        ]);
+        const close = await clearingClose(opts.signer, deployment, balance, destination, block.timestamp + policy[5]);
+        // The balance is proven against the finalized state: an epoch that
+        // finalizes before the withdrawal lands moves it, and the contract
+        // refuses the withdrawal with `InvalidBoundary`.
+        const moved = async () => (await pub.readContract({ ...contract, functionName: "finalizedState" })).toLowerCase() !== close.withdrawal.state.toLowerCase();
+        const receipt = await send({ ...contract, functionName: "queueWithdrawal", args: [close.withdrawal, close.opening] }, 2000000n).catch(async (error) => {
+            throw revertOf(error) === "InvalidBoundary" && (await moved()) ? finalizedUnder("queueWithdrawal", undefined, error) : error;
+        });
+        if (receipt.status !== "success" && (await moved()))
+            throw finalizedUnder("queueWithdrawal", receipt.transactionHash);
+        return { status: "sent", claimed, queued: { tx: succeeded("queueWithdrawal", receipt) } };
+    }
+}
+/** The calls that fault a deployment whose service has missed a deadline:
+ * to admit the epoch it registered, `account`'s queued withdrawal, or its
+ * deposit. Each reverts `InvalidDeadline` until its deadline passes. */
+const faultCalls = (admitted, account) => [
+    { functionName: "faultRegistration", args: [] },
+    { functionName: "faultWithdrawal", args: [account] },
+    { functionName: "faultDeposit", args: [admitted, account] },
+];
+const revertOf = (error) => {
+    if (!(error instanceof BaseError))
+        return undefined;
+    const reverted = error.walk((e) => e instanceof ContractFunctionRevertedError);
+    return reverted instanceof ContractFunctionRevertedError ? (reverted.data?.errorName ?? "reverted") : undefined;
+};
+/** Take `signer`'s funds out of a Clearing deployment whose service has
+ * stopped. Once the service has missed a deadline, to admit an epoch it
+ * registered, a deposit, or the account's queued withdrawal, this faults
+ * the deployment, finalizes the epochs it admitted, starts recovery, and
+ * takes the payout of the account's finalized withdrawal, its last
+ * finalized balance and every deposit no final epoch counted, to
+ * `destination` (`from` itself unless given) or, for a withdrawal, to the
+ * destination it named. The payout and balance proofs come from
+ * `serviceUrl`, the clearing service or any of its validators, or the
+ * first of several that proves each. A proof none of them gives does not
+ * stop the steps that need none: they are taken, and then the error names
+ * what is left and what was sent. Each step already taken is skipped, so
+ * call it again after `waiting` or such an error. `from` pays the gas. */
+export async function recoverFromClearing(opts) {
+    const serviceUrls = typeof opts.serviceUrl === "string" ? [opts.serviceUrl] : opts.serviceUrl;
+    if (serviceUrls.length === 0)
+        throw new Error("recoverFromClearing needs a clearing service URL");
+    // A proof no service gives does not stop the steps that need none; the
+    // answer then names it, and what was sent.
+    let unclaimed;
+    let unproven;
+    const finish = (result) => {
+        const missed = [unclaimed, unproven].filter((error) => error !== undefined);
+        if (missed.length === 0)
+            return result;
+        const sent = [
+            result.status === "recovered" && result.faulted && `fault ${result.faulted}`,
+            ...result.claimed.map((c) => `claim ${c.tx}${c.deferred ? " (deferred: the destination calls withdrawUnclaimed)" : ""}`),
+            ...(result.status === "recovered"
+                ? [result.recovered && `recover ${result.recovered.tx}`, ...result.refunded.map((r) => `refundDeposit ${r.tx}`)]
+                : []),
+        ].filter(Boolean);
+        throw new Error(`${missed.map((error) => (error instanceof Error ? error.message : String(error))).join("; ")}. ${result.status === "waiting" ? `Epoch ${result.epoch} is still in its challenge window. ` : ""}This call sent ${sent.length > 0 ? sent.join(", ") : "nothing"}: call recoverFromClearing again to take the rest`, { cause: missed[0] });
+    };
+    const { pub, send } = chainClients(opts);
+    const fetcher = opts.fetch ?? globalThis.fetch;
+    const destination = opts.destination ?? opts.from.address;
+    const contract = { address: opts.settlement, abi: clearingAbi };
+    const account = opts.signer.publicKey;
+    const key = accountKey(account);
+    const unit = await pub.readContract({ ...contract, functionName: "unit" });
+    let faulted = null;
+    if ((await pub.readContract({ ...contract, functionName: "fault" })) === 0) {
+        const admitted = await pub.readContract({ ...contract, functionName: "admittedCount" });
+        for (const call of faultCalls(admitted, account)) {
+            try {
+                faulted = succeeded(call.functionName, await send({ ...contract, ...call }, 200000n));
+                break;
+            }
+            catch (error) {
+                // Each fault reverts `InvalidDeadline` until its deadline passes; any
+                // other refusal, running out of gas among them, is an error.
+                if (revertOf(error) !== "InvalidDeadline")
+                    throw error;
+            }
+        }
+        if (!faulted)
+            return { status: "operating" };
+    }
+    // A withdrawal whose epoch finalized is paid by `claim`, not `recover`,
+    // and needs no recovery: it is claimed first, and again once this call
+    // finalizes the epoch that carries it.
+    const claimed = [];
+    const claimFinalized = async () => {
+        const [[, epochPlusOne, , , queuedTo], finalized] = await Promise.all([
+            pub.readContract({ ...contract, functionName: "withdrawals", args: [key] }),
+            pub.readContract({ ...contract, functionName: "finalizedCount" }),
+        ]);
+        unclaimed = undefined;
+        if (epochPlusOne === 0n || epochPlusOne > finalized)
+            return;
+        // `recover` does not pay a finalized withdrawal, so a later call claims it.
+        const payout = await lookupPayout(serviceUrls, fetcher, epochPlusOne - 1n, account, queuedTo).catch((error) => {
+            unclaimed = error;
+        });
+        if (payout)
+            await claimPayout({ pub, send, settlement: opts.settlement, unit }, payout, queuedTo, claimed);
+    };
+    await claimFinalized();
+    if (!(await pub.readContract({ ...contract, functionName: "recovering" }))) {
+        for (;;) {
+            const [finalized, admitted, invalidFrom] = await Promise.all([
+                pub.readContract({ ...contract, functionName: "finalizedCount" }),
+                pub.readContract({ ...contract, functionName: "admittedCount" }),
+                pub.readContract({ ...contract, functionName: "invalidFrom" }),
+            ]);
+            if (finalized >= admitted || finalized >= invalidFrom)
+                break;
+            try {
+                succeeded("finalize", await send({ ...contract, functionName: "finalize", args: [] }, 2000000n));
+            }
+            catch (error) {
+                if (revertOf(error) === "InvalidDeadline")
+                    return finish({ status: "waiting", epoch: finalized, claimed });
+                throw error;
+            }
+        }
+        try {
+            succeeded("beginRecovery", await send({ ...contract, functionName: "beginRecovery", args: [] }, 200000n));
+        }
+        catch (error) {
+            // Someone else started it between the read and the dry run.
+            if (revertOf(error) === undefined || !(await pub.readContract({ ...contract, functionName: "recovering" })))
+                throw error;
+        }
+    }
+    await claimFinalized();
+    const [deployment, state, finalized, admitted, done] = await Promise.all([
+        pub.readContract({ ...contract, functionName: "deployment" }),
+        pub.readContract({ ...contract, functionName: "finalizedState" }),
+        pub.readContract({ ...contract, functionName: "finalizedCount" }),
+        pub.readContract({ ...contract, functionName: "admittedCount" }),
+        pub.readContract({ ...contract, functionName: "recoveredAccounts", args: [key] }),
+    ]);
+    let recovered = null;
+    const balance = !done && finalized > 0n ? await provenBalance(state).catch((error) => void (unproven = error)) : undefined;
+    if (balance) {
+        if (BigInt(balance.amount) > 0n && balance.opening) {
+            const { amount, nextKey, ...proof } = balance.opening;
+            const signature = await opts.signer.sign("_METAL_CLEARING_RECOVERY", concatHex([deployment, state, destination]));
+            const receipt = await send({
+                ...contract,
+                functionName: "recover",
+                args: [account, destination, signature, { amount: BigInt(amount), nextKey, proof: clearingLogProof(proof) }],
+            }, 2000000n);
+            recovered = { amount: BigInt(balance.amount) * unit, tx: succeeded("recover", receipt) };
+        }
+    }
+    const refunded = [];
+    for (let epoch = finalized; epoch <= admitted; epoch++) {
+        const amount = await pub.readContract({ ...contract, functionName: "depositAmounts", args: [epoch, key] });
+        if (amount === 0n)
+            continue;
+        const signature = await opts.signer.sign("_METAL_CLEARING_DEPOSIT_REFUND", concatHex([deployment, clearingUint64(epoch), clearingUint64(amount), destination]));
+        // About 760k on Metal, which charges 64 times Ethereum's gas for P-256 and modexp.
+        const receipt = await send({ ...contract, functionName: "refundDeposit", args: [epoch, account, destination, signature] }, 1200000n);
+        refunded.push({ epoch, amount: amount * unit, tx: succeeded("refundDeposit", receipt) });
+    }
+    return finish({ status: "recovered", faulted, claimed, recovered, refunded });
+    /** The account's balance as of `state`, from the first service that proves it there. */
+    async function provenBalance(state) {
+        const failures = [];
+        for (const serviceUrl of serviceUrls) {
+            try {
+                const balance = await clearingBalance(serviceUrl, account, fetcher);
+                if (balance.state.toLowerCase() === state.toLowerCase())
+                    return balance;
+                failures.push(`${serviceUrl} proves balances against ${balance.state}`);
+            }
+            catch (error) {
+                failures.push(`${serviceUrl}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        throw new Error(`no clearing service named proves this account's balance at the contract's finalized state ${state}; a validator proves it once it has retained the last finalized epoch (${failures.join("; ")})`);
+    }
+}

package/dist/clearing-server.d.ts

@@ -1,56 +1,37 @@
-import type { AssetAmount, PaymentRequirements, Price, SchemeNetworkServer, SchemeServerHooks, SettleResponse, SupportedKind } from "@x402/core/types";
+import type { AssetAmount, PaymentRequirements, Price, SchemeNetworkServer, SchemePaymentRequiredContext, SupportedKind } from "@x402/core/types";
 import { type DollarToken } from "./networks.js";
-/** Metal clearing operator's signed receipt for one payment, as the
- * facilitator returns it in `extra.receipt` of a settle response. Keep it:
- * it is the seller's own proof of what it is owed, which can be used on
- * chain if an epoch close leaves the credit out, without trusting Metal.
- * uint values are decimal strings; the digest and signature are EIP-712
- * under the Clearing contract's domain ("MetalClearing", "1") on `network`. */
-export interface ClearingReceipt {
-    network: string;
-    contract: string;
-    operator: string;
-    receipt: {
-        recipient: string;
-        epoch: string;
-        shard: string;
-        index: string;
-        cumulativeCredit: string;
-        prevReceiptDigest: string;
-        debitDigest: string;
-    };
-    receiptDigest: string;
-    receiptSignature: string;
-}
-/** The clearing receipt in a settle response, or null when it has none. */
-export declare function clearingReceiptOf(response: Pick<SettleResponse, "extra">): ClearingReceipt | null;
-/** Metal's clearing lane on the seller's side. Register it next to the
- * standard scheme, and list both in a route's `accepts`:
- *
- *     server
- *       .register(network, new ExactEvmScheme().registerMoneyParser(metalUsd(network)))
- *       .register(network, new ClearingDebitServerScheme());
- *     accepts: [
- *       { scheme: "exact", network, payTo, price: "$0.01" },
- *       { scheme: "clearing-debit", network, payTo, price: "$0.001" },
- *     ]
+/**
+ * The `bajillion` scheme for an `x402ResourceServer`, registered beside
+ * `exact` on `network`. A route's `payTo` is the seller's clearing key,
+ * `signer.publicKey` of a wallet from `openClearingWallet`, and its `price`
+ * is dollars in `token`. The offer names the Clearing deployment the
+ * facilitator lists for the network in `/supported`, so a seller takes only
+ * payments its facilitator settles.
  *
- * A payer pays by signing a running total; the facilitator has Metal's
- * clearing operator admit it, and the seller is credited in clearing, from
- * which it withdraws whenever it likes. The Clearing contract comes from the
- * facilitator's list of what it supports.
- *
- * `onReceipt` is handed the operator's signed receipt for every payment
- * settled, and again with any later answer for the same payment; store it
- * by its `receiptDigest`. */
-export declare class ClearingDebitServerScheme implements SchemeNetworkServer {
+ *     server.register(network, new ClearingServerScheme(network));
+ */
+export declare class ClearingServerScheme implements SchemeNetworkServer {
+    private readonly network;
     private readonly token;
-    readonly scheme = "clearing-debit";
-    readonly schemeHooks: SchemeServerHooks;
-    constructor(token?: DollarToken, options?: {
-        onReceipt?: (receipt: ClearingReceipt) => Promise<void>;
-    });
+    readonly scheme = "bajillion";
+    readonly defaultAssetTransferMethod = "default";
+    readonly paymentFlows: {
+        readonly default: {
+            readonly supported: readonly ["upfront"];
+            readonly default: "upfront";
+        };
+    };
+    constructor(network: `eip155:${number}`, token?: DollarToken);
     parsePrice(price: Price): Promise<AssetAmount>;
+    /** Clearing counts whole clearing units, at most 2^64 - 1 of them in all.
+     * The unit is the one `Clearing.unit()` derives from the token's decimals
+     * at deploy: a millionth of the token, or its base unit at six decimals or
+     * fewer. */
+    private payable;
     getAssetDecimals(): number;
     enhancePaymentRequirements(requirements: PaymentRequirements, supportedKind: SupportedKind): Promise<PaymentRequirements>;
+    /** Binds this network's offers' invoices to the resource asked for, at
+     * the challenge and again when a payment for it is verified. A route that
+     * sets its own `invoicePrefix` keeps it. */
+    enrichPaymentRequiredResponse(ctx: SchemePaymentRequiredContext): Promise<PaymentRequirements[]>;
 }