@metalntwx/metal-pay 0.2.0 → 0.3.1

package/dist/clearing.js

@@ -1,151 +0,0 @@
-// Metal clearing's signed messages: the EIP-712 types and digests that a
-// payer, a seller, the facilitator and the clearing operator must agree on
-// field for field. They mirror contracts/src/clearing/ClearingTypes.sol and
-// the operator's local API (apps/clearing-operator).
-//
-// - A Debit is a payer's signed running total, naming who it pays.
-// - A Receipt is the operator's signature crediting a recipient's shard.
-// - An Exit is an account's signed withdrawal, naming where funds go.
-// - An AccountRequest is an account asking the facilitator about itself.
-//
-// All are signed under the Clearing contract's domain ("MetalClearing", "1",
-// chainId, contract). Pure: no I/O.
-import { hashTypedData, recoverTypedDataAddress, } from "viem";
-/** The x402 scheme name of Metal's clearing lane. */
-export const CLEARING_DEBIT = "clearing-debit";
-export const CLEARING_DOMAIN_NAME = "MetalClearing";
-export const DEBIT_TYPES = {
-    Debit: [
-        { name: "payer", type: "address" },
-        { name: "recipient", type: "address" },
-        { name: "epoch", type: "uint64" },
-        { name: "index", type: "uint64" },
-        { name: "cumulativeDebit", type: "uint256" },
-        { name: "ref", type: "bytes32" },
-    ],
-};
-export const RECEIPT_TYPES = {
-    Receipt: [
-        { name: "recipient", type: "address" },
-        { name: "epoch", type: "uint64" },
-        { name: "shard", type: "uint64" },
-        { name: "index", type: "uint64" },
-        { name: "cumulativeCredit", type: "uint256" },
-        { name: "prevReceiptDigest", type: "bytes32" },
-        { name: "debitDigest", type: "bytes32" },
-    ],
-};
-export function clearingDomain(chainId, contract) {
-    return {
-        name: CLEARING_DOMAIN_NAME,
-        version: "1",
-        chainId,
-        verifyingContract: contract,
-    };
-}
-export function debitFromWire(wire) {
-    return {
-        payer: wire.payer,
-        recipient: wire.recipient,
-        epoch: BigInt(wire.epoch),
-        index: BigInt(wire.index),
-        cumulativeDebit: BigInt(wire.cumulativeDebit),
-        ref: wire.ref,
-    };
-}
-export function debitTypedData(domain, debit) {
-    return {
-        domain,
-        types: DEBIT_TYPES,
-        primaryType: "Debit",
-        message: debit,
-    };
-}
-export function receiptTypedData(domain, receipt) {
-    return {
-        domain,
-        types: RECEIPT_TYPES,
-        primaryType: "Receipt",
-        message: receipt,
-    };
-}
-export function debitDigest(domain, debit) {
-    return hashTypedData(debitTypedData(domain, debit));
-}
-export function receiptDigest(domain, receipt) {
-    return hashTypedData(receiptTypedData(domain, receipt));
-}
-/** An account's request to take funds out of clearing custody. Only the
- * account can sign it, and it names where the funds go. */
-export const EXIT_TYPES = {
-    Exit: [
-        { name: "account", type: "address" },
-        { name: "destination", type: "address" },
-        { name: "amount", type: "uint256" },
-        { name: "deadline", type: "uint64" },
-    ],
-};
-export function exitTypedData(domain, exit) {
-    return {
-        domain,
-        types: EXIT_TYPES,
-        primaryType: "Exit",
-        message: exit,
-    };
-}
-export function exitDigest(domain, exit) {
-    return hashTypedData(exitTypedData(domain, exit));
-}
-export async function recoverExitSigner(domain, exit, signature) {
-    try {
-        return await recoverTypedDataAddress({
-            ...exitTypedData(domain, exit),
-            signature,
-        });
-    }
-    catch {
-        return null;
-    }
-}
-/** An account asking the facilitator about itself: where its next Debit
- * starts, or what it can withdraw. Signed under the clearing domain so that
- * only the account can read its own position; the deadline keeps a request
- * someone else has seen from being used for long. Never sent on chain. */
-export const ACCOUNT_REQUEST_TYPES = {
-    AccountRequest: [
-        { name: "account", type: "address" },
-        { name: "deadline", type: "uint64" },
-    ],
-};
-export async function recoverAccountRequestSigner(domain, request, signature) {
-    try {
-        return await recoverTypedDataAddress({
-            domain,
-            types: ACCOUNT_REQUEST_TYPES,
-            primaryType: "AccountRequest",
-            message: request,
-            signature,
-        });
-    }
-    catch {
-        return null;
-    }
-}
-export async function recoverDebitSigner(domain, debit, signature) {
-    try {
-        return await recoverTypedDataAddress({
-            ...debitTypedData(domain, debit),
-            signature,
-        });
-    }
-    catch {
-        return null;
-    }
-}
-/** Receive shards spread a hot recipient over parallel credit lanes. The
- * shard is a pure function of `ref`, so a replayed debit lands on the same
- * one. Same formula as the café's. */
-export const REVENUE_SHARDS = 8n;
-export function shardFor(ref) {
-    return BigInt(`0x${ref.slice(-2)}`) % REVENUE_SHARDS;
-}

package/dist/file-storage.d.ts

@@ -1,39 +0,0 @@
-import { type ClearingPositionStorage, type StoredClearingPosition } from "./clearing-client.js";
-export interface FileClearingPositionStorageOptions {
-    /** How long a writer waits for the lock before giving up. Default 5s. */
-    lockWaitMs?: number;
-    /** A lock this old was left by a writer that died or hung. Default 30s;
-     * a write holds the lock for milliseconds. */
-    lockStaleMs?: number;
-}
-export declare class FileClearingPositionStorage implements ClearingPositionStorage {
-    private readonly path;
-    private readonly lockPath;
-    private readonly takeoverPath;
-    private readonly lockWaitMs;
-    private readonly lockStaleMs;
-    constructor(path: string, options?: FileClearingPositionStorageOptions);
-    private read;
-    /** Hold the lock file while `job` runs. The whole file is read, changed
-     * and rewritten, so two writers (two instances, or two processes) must
-     * not overlap or one would drop the other's record.
-     *
-     * The lock is a file created exclusively, holding a token unique to its
-     * holder. A lock left by a writer that died is taken over, and that is
-     * the delicate part: two waiters must not both conclude it is abandoned
-     * and both remove it, or the second would delete the first one's fresh
-     * lock. So removal itself is guarded (see `takeOver`), and a writer whose
-     * lock was taken over finds out before it writes (`stillHeld`). */
-    private locked;
-    private inspect;
-    /** Remove `path` only while it still holds `token`. */
-    private removeIfHolds;
-    /** Remove an abandoned lock, at most one waiter at a time. The takeover
-     * file is itself created exclusively, so only one waiter is ever inside;
-     * it removes the lock only if it is still the abandoned one it saw. A
-     * waiter that arrives later finds either no lock or a fresh one from a
-     * new holder, and leaves it alone. */
-    private takeOver;
-    get(key: string): Promise<StoredClearingPosition | undefined>;
-    set(key: string, position: StoredClearingPosition): Promise<void>;
-}

package/dist/file-storage.js

@@ -1,195 +0,0 @@
-// Durable storage for the clearing client's position: one JSON file. Give
-// every process that signs with the same key the same file, so each sees
-// what the others signed.
-//
-// Kept apart from `clearing-client.ts` so the plug-in itself has no
-// filesystem dependency, the way the official batch-settlement client ships
-// its file storage as a separate entry point.
-import { randomUUID } from "node:crypto";
-import { mkdir, open, readFile, rename, rm, writeFile } from "node:fs/promises";
-import { dirname } from "node:path";
-import { keepHighest, } from "./clearing-client.js";
-/** Thrown inside a write whose lock was taken over while it was working. */
-class LostLock extends Error {
-}
-const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-/** Whether the process that wrote a lock is gone. Only meaningful for a
- * holder on this machine; an unparsable pid is not treated as dead. */
-function holderIsDead(token) {
-    const pid = Number(token.split(":")[0]);
-    if (!Number.isInteger(pid) || pid <= 0)
-        return false;
-    try {
-        process.kill(pid, 0);
-        return false;
-    }
-    catch (error) {
-        return error.code === "ESRCH";
-    }
-}
-export class FileClearingPositionStorage {
-    path;
-    lockPath;
-    takeoverPath;
-    lockWaitMs;
-    lockStaleMs;
-    constructor(path, options = {}) {
-        this.path = path;
-        this.lockPath = `${path}.lock`;
-        this.takeoverPath = `${path}.lock.takeover`;
-        this.lockWaitMs = options.lockWaitMs ?? 5_000;
-        this.lockStaleMs = options.lockStaleMs ?? 30_000;
-    }
-    async read() {
-        let text;
-        try {
-            text = await readFile(this.path, "utf8");
-        }
-        catch (error) {
-            if (error.code === "ENOENT")
-                return {};
-            throw new Error(`clearing position file ${this.path} is unreadable`, {
-                cause: error,
-            });
-        }
-        // A file that exists but does not parse is not "no record": treating it
-        // as empty would drop the protection the record gives.
-        try {
-            const parsed = JSON.parse(text);
-            if (typeof parsed !== "object" ||
-                parsed === null ||
-                Array.isArray(parsed))
-                throw new Error("not an object");
-            return parsed;
-        }
-        catch (error) {
-            throw new Error(`clearing position file ${this.path} is unreadable`, {
-                cause: error,
-            });
-        }
-    }
-    /** Hold the lock file while `job` runs. The whole file is read, changed
-     * and rewritten, so two writers (two instances, or two processes) must
-     * not overlap or one would drop the other's record.
-     *
-     * The lock is a file created exclusively, holding a token unique to its
-     * holder. A lock left by a writer that died is taken over, and that is
-     * the delicate part: two waiters must not both conclude it is abandoned
-     * and both remove it, or the second would delete the first one's fresh
-     * lock. So removal itself is guarded (see `takeOver`), and a writer whose
-     * lock was taken over finds out before it writes (`stillHeld`). */
-    async locked(job) {
-        await mkdir(dirname(this.path), { recursive: true, mode: 0o700 });
-        const deadline = Date.now() + this.lockWaitMs;
-        const token = `${process.pid}:${randomUUID()}`;
-        for (;;) {
-            try {
-                await writeFile(this.lockPath, token, { flag: "wx" });
-                break;
-            }
-            catch (error) {
-                if (error.code !== "EEXIST")
-                    throw error;
-                // Every way round this loop is bounded by the wait.
-                if (Date.now() > deadline)
-                    throw new Error(`timed out waiting for the clearing position lock ${this.lockPath}`, { cause: error });
-                const seen = await this.inspect(this.lockPath);
-                if (seen && (holderIsDead(seen.token) || seen.age > this.lockStaleMs))
-                    await this.takeOver(seen.token);
-                // Held by a live writer, unreadable, or already gone: wait and retry.
-                else
-                    await sleep(10);
-            }
-        }
-        const stillHeld = async () => {
-            if ((await this.inspect(this.lockPath))?.token !== token)
-                throw new LostLock(`the clearing position lock ${this.lockPath} was taken over mid-write`);
-        };
-        try {
-            return await job(stillHeld);
-        }
-        finally {
-            // Release only our own lock: if it was taken over, it is not ours.
-            if ((await this.inspect(this.lockPath))?.token === token)
-                await rm(this.lockPath, { force: true });
-        }
-    }
-    async inspect(path) {
-        // One open file for both reads, so the token and the age always belong
-        // to the same lock even if it is replaced meanwhile.
-        let handle;
-        try {
-            handle = await open(path, "r");
-            const info = await handle.stat();
-            const token = await handle.readFile("utf8");
-            return { token, age: Date.now() - info.mtimeMs };
-        }
-        catch {
-            return null;
-        }
-        finally {
-            await handle?.close();
-        }
-    }
-    /** Remove `path` only while it still holds `token`. */
-    async removeIfHolds(path, token) {
-        if ((await this.inspect(path))?.token === token)
-            await rm(path, { force: true });
-    }
-    /** Remove an abandoned lock, at most one waiter at a time. The takeover
-     * file is itself created exclusively, so only one waiter is ever inside;
-     * it removes the lock only if it is still the abandoned one it saw. A
-     * waiter that arrives later finds either no lock or a fresh one from a
-     * new holder, and leaves it alone. */
-    async takeOver(abandoned) {
-        const mine = `${process.pid}:${randomUUID()}`;
-        try {
-            await writeFile(this.takeoverPath, mine, { flag: "wx" });
-        }
-        catch (error) {
-            if (error.code !== "EEXIST")
-                throw error;
-            // Another waiter is doing it. If that waiter itself died here, clear
-            // its marker so takeovers are not blocked for good.
-            const other = await this.inspect(this.takeoverPath);
-            if (other && (holderIsDead(other.token) || other.age > this.lockStaleMs))
-                await this.removeIfHolds(this.takeoverPath, other.token);
-            await sleep(10);
-            return;
-        }
-        try {
-            if ((await this.inspect(this.lockPath))?.token === abandoned)
-                await rm(this.lockPath, { force: true });
-        }
-        finally {
-            await this.removeIfHolds(this.takeoverPath, mine);
-        }
-    }
-    async get(key) {
-        return (await this.read())[key];
-    }
-    set(key, position) {
-        return this.locked(async (stillHeld) => {
-            const all = await this.read();
-            // Merged under the lock: another client may have signed since the
-            // caller read its position, and the high-water mark must not go down.
-            all[key] = keepHighest(all[key], position);
-            // Write beside the file under a name no other writer shares, then swap
-            // it in, so a crash mid-write cannot leave a truncated record.
-            const next = `${this.path}.${randomUUID()}.tmp`;
-            try {
-                await writeFile(next, `${JSON.stringify(all, null, 2)}\n`, {
-                    mode: 0o600,
-                });
-                // A writer that hung long enough to be taken over must not swap in
-                // what it read before the newer writer's change.
-                await stillHeld();
-                await rename(next, this.path);
-            }
-            catch (error) {
-                await rm(next, { force: true });
-                throw error;
-            }
-        });
-    }
-}