@metalntwx/metal-pay 0.2.0 → 0.3.0

package/dist/clearing-codec.d.ts

@@ -0,0 +1,57 @@
+import { type Hex } from "viem";
+export declare const CLEARING_REFERENCE = "3134e902ccf619987e2731a0c1e63114bcc0b060";
+export declare const CLEARING_SCHEME = "bajillion";
+export interface OutgoingEntry {
+    recipient: Hex;
+    cumulative: bigint;
+    count: bigint;
+}
+export interface ClearingSend {
+    anchor: Hex;
+    epoch: bigint;
+    payer: Hex;
+    sequence: bigint;
+    debit: bigint;
+    vector: Hex;
+}
+export interface ClearingReceipt {
+    body: Hex;
+    payerSignature: Hex;
+    operatorSignature: Hex;
+}
+/** The clearing units `amount` token base units make, where `unit` is the
+ * deployment's `Clearing.unit()`: Clearing counts whole units, so a fraction
+ * of one is refused rather than rounded. */
+export declare function clearingUnits(amount: bigint, unit: bigint): bigint;
+export declare function clearingUint64(value: bigint): Hex;
+export declare function clearingAccount(value: Hex): Hex;
+/** The exact typed BMT root used by commonware-clearing at CLEARING_REFERENCE. */
+export declare function outgoingRoot(entries: readonly OutgoingEntry[]): Hex;
+export declare function encodeSend(body: ClearingSend): Hex;
+export declare function decodeSend(encoded: Hex): ClearingSend;
+export declare function clearingSignatureDigest(namespace: string, message: Hex): Hex;
+export declare function verifyClearingSignature(key: Hex, namespace: string, message: Hex, signature: Hex): boolean;
+export declare function verifyReceipt(receipt: ClearingReceipt, operator: Hex): boolean;
+export interface ClearingInvoice {
+    id: string;
+    network: string;
+    settlement: Hex;
+    asset: Hex;
+    recipient: Hex;
+    amount: string;
+}
+/** The HTTP invoice is separately signed; it does not alter Bajillion's wire format. */
+export declare function invoiceMessage(invoice: ClearingInvoice, body: Hex): Hex;
+export declare function createClearingSigner(privateKey: Hex): {
+    publicKey: `0x${string}`;
+    sign(namespace: string, message: Hex): Hex;
+};
+export declare function decodeWithdrawal(encoded: Hex): {
+    account: `0x${string}`;
+    deployment: `0x${string}`;
+    state: `0x${string}`;
+    destination: `0x${string}`;
+    amount: bigint;
+    deadline: bigint;
+    signature: `0x${string}`;
+};

package/dist/clearing-codec.js

@@ -0,0 +1,173 @@
+import { p256 } from "@noble/curves/p256";
+import { concatHex, hexToBytes, sha256, stringToHex, toHex, } from "viem";
+export const CLEARING_REFERENCE = "3134e902ccf619987e2731a0c1e63114bcc0b060";
+export const CLEARING_SCHEME = "bajillion";
+const U64_MAX = (1n << 64n) - 1n;
+/** The clearing units `amount` token base units make, where `unit` is the
+ * deployment's `Clearing.unit()`: Clearing counts whole units, so a fraction
+ * of one is refused rather than rounded. */
+export function clearingUnits(amount, unit) {
+    if (unit <= 0n || amount % unit !== 0n)
+        throw new Error(`${amount} base units is not a whole number of clearing units of ${unit}`);
+    return amount / unit;
+}
+export function clearingUint64(value) {
+    if (value < 0n || value > U64_MAX)
+        throw new Error("clearing amount exceeds uint64");
+    return toHex(value, { size: 8 });
+}
+function fixed(value, length) {
+    if (!new RegExp(`^0x[0-9a-fA-F]{${length * 2}}$`).test(value))
+        throw new Error("invalid clearing wire length");
+    return value.toLowerCase();
+}
+export function clearingAccount(value) {
+    fixed(value, 33);
+    const point = p256.ProjectivePoint.fromHex(hexToBytes(value));
+    point.assertValidity();
+    // The canonical compressed encoding of the parsed point, not the wire
+    // string: what reaches a receipt URL or a signature check is what the
+    // curve produced, so no byte of the input passes through untouched.
+    return toHex(point.toRawBytes(true));
+}
+function hash(...values) {
+    return sha256(concatHex(values));
+}
+const domain = (name) => stringToHex(`_COMMONWARE_CLEARING_${name}`);
+/** The exact typed BMT root used by commonware-clearing at CLEARING_REFERENCE. */
+export function outgoingRoot(entries) {
+    if (entries.length > 1 << 24)
+        throw new Error("too many clearing entries");
+    const length = toHex(entries.length, { size: 4 });
+    let previous = "";
+    let total = 0n;
+    let count = 0n;
+    let level = entries.map((entry, position) => {
+        const recipient = clearingAccount(entry.recipient);
+        if (recipient <= previous ||
+            entry.count <= 0n ||
+            entry.cumulative < entry.count)
+            throw new Error("noncanonical clearing vector");
+        previous = recipient;
+        total += entry.cumulative;
+        count += entry.count;
+        clearingUint64(total);
+        clearingUint64(count);
+        const encoded = concatHex([
+            recipient,
+            clearingUint64(entry.cumulative),
+            clearingUint64(entry.count),
+        ]);
+        const index = toHex(position, { size: 4 });
+        const leaf = hash(domain("OUT_ENTRY_LEAF"), length, index, clearingUint64(49n), encoded);
+        return hash(index, leaf);
+    });
+    if (level.length === 0)
+        level = [hash("0x")];
+    while (level.length > 1) {
+        const next = [];
+        for (let i = 0; i < level.length; i += 2)
+            next.push(hash(level[i], level[i + 1] ?? level[i]));
+        level = next;
+    }
+    return hash(domain("OUT_ENTRY_ROOT"), length, hash(length, level[0]));
+}
+export function encodeSend(body) {
+    return concatHex([
+        fixed(body.anchor, 32),
+        clearingUint64(body.epoch),
+        clearingAccount(body.payer),
+        clearingUint64(body.sequence),
+        clearingUint64(body.debit),
+        fixed(body.vector, 32),
+    ]);
+}
+export function decodeSend(encoded) {
+    fixed(encoded, 121);
+    const part = (start, length) => `0x${encoded.slice(2 + start * 2, 2 + (start + length) * 2)}`;
+    return {
+        anchor: part(0, 32),
+        epoch: BigInt(part(32, 8)),
+        payer: clearingAccount(part(40, 33)),
+        sequence: BigInt(part(73, 8)),
+        debit: BigInt(part(81, 8)),
+        vector: part(89, 32),
+    };
+}
+export function clearingSignatureDigest(namespace, message) {
+    const bytes = stringToHex(namespace);
+    const length = (bytes.length - 2) / 2;
+    if (length >= 128)
+        throw new Error("unsupported signature namespace length");
+    return hash(toHex(length, { size: 1 }), bytes, message);
+}
+export function verifyClearingSignature(key, namespace, message, signature) {
+    try {
+        clearingAccount(key);
+        fixed(signature, 64);
+        return p256.verify(hexToBytes(signature), hexToBytes(clearingSignatureDigest(namespace, message)), hexToBytes(key), { lowS: true, prehash: false });
+    }
+    catch {
+        return false;
+    }
+}
+export function verifyReceipt(receipt, operator) {
+    try {
+        const body = decodeSend(receipt.body);
+        return (verifyClearingSignature(body.payer, "_COMMONWARE_CLEARING_VECTOR_SEND", receipt.body, receipt.payerSignature) &&
+            verifyClearingSignature(operator, "_COMMONWARE_CLEARING_VECTOR_ACK", receipt.body, receipt.operatorSignature));
+    }
+    catch {
+        return false;
+    }
+}
+/** The HTTP invoice is separately signed; it does not alter Bajillion's wire format. */
+export function invoiceMessage(invoice, body) {
+    if (!/^[a-zA-Z0-9:_./-]{1,256}$/.test(invoice.id))
+        throw new Error("invalid clearing invoice id");
+    if (!/^eip155:[1-9][0-9]*$/.test(invoice.network))
+        throw new Error("invalid clearing network");
+    return stringToHex(JSON.stringify([
+        invoice.id,
+        invoice.network,
+        fixed(invoice.settlement, 20),
+        fixed(invoice.asset, 20),
+        clearingAccount(invoice.recipient),
+        // Invoices count ERC-20 base units; only clearing balances use uint64.
+        toHex(BigInt(invoice.amount), { size: 32 }),
+        sha256(body),
+    ]));
+}
+export function createClearingSigner(privateKey) {
+    const key = hexToBytes(fixed(privateKey, 32));
+    const publicKey = toHex(p256.getPublicKey(key, true));
+    return {
+        publicKey,
+        sign(namespace, message) {
+            return toHex(p256
+                .sign(hexToBytes(clearingSignatureDigest(namespace, message)), key, {
+                lowS: true,
+                prehash: false,
+            })
+                .toCompactRawBytes());
+        },
+    };
+}
+export function decodeWithdrawal(encoded) {
+    const raw = hexToBytes(encoded);
+    if ((raw.length !== 199 && raw.length !== 191) || raw[97] !== 20)
+        throw new Error("invalid native withdrawal");
+    const part = (offset, length) => toHex(raw.slice(offset, offset + length));
+    const close = raw[118] === 2;
+    if ((!close && raw[118] !== 1) || raw.length !== (close ? 191 : 199))
+        throw new Error("invalid withdrawal action");
+    return {
+        account: clearingAccount(part(0, 33)),
+        deployment: part(33, 32),
+        state: part(65, 32),
+        destination: part(98, 20),
+        amount: close ? 0n : BigInt(part(119, 8)),
+        deadline: BigInt(part(close ? 119 : 127, 8)),
+        signature: part(close ? 127 : 135, 64),
+    };
+}

package/dist/clearing-custody.d.ts

@@ -0,0 +1,191 @@
+import { type Address, type Hex, type LocalAccount } from "viem";
+import type { ClearingSigner } from "./clearing-client.js";
+export interface ClearingLogProof {
+    location: string;
+    leaves: string;
+    inactivePeaks: number;
+    digests: Hex[];
+}
+export interface ClearingBalance {
+    state: Hex;
+    amount: string;
+    opening: null | (ClearingLogProof & {
+        amount: string;
+        nextKey: Hex;
+        chunk: Hex;
+        opsRoot: Hex;
+        pending: Hex;
+        partialDigest: Hex;
+    });
+}
+export declare function clearingLogProof<T extends ClearingLogProof>(proof: T): T & {
+    location: bigint;
+    leaves: bigint;
+    inactivePeaks: bigint;
+};
+/** Authorize an epoch-tail close to a fixed EVM destination. */
+export declare function clearingClose(signer: ClearingSigner, deployment: Hex, balance: ClearingBalance, destination: Hex, deadline: bigint): Promise<{
+    withdrawal: {
+        account: `0x${string}`;
+        deployment: `0x${string}`;
+        state: `0x${string}`;
+        destination: `0x${string}`;
+        amount: bigint;
+        deadline: bigint;
+        signature: `0x${string}`;
+    };
+    opening: {
+        amount: bigint;
+        nextKey: `0x${string}`;
+        proof: {
+            location: string;
+            leaves: string;
+            inactivePeaks: number;
+            digests: Hex[];
+            chunk: Hex;
+            opsRoot: Hex;
+            pending: Hex;
+            partialDigest: Hex;
+        } & {
+            location: bigint;
+            leaves: bigint;
+            inactivePeaks: bigint;
+        };
+    };
+}>;
+/** 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 declare const CLEARING_MAX_AMOUNT: bigint;
+/** 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 declare function clearingSpendable(opts: {
+    rpcUrl: string;
+    settlement: Address;
+    serviceUrl: string;
+    account: Hex;
+    fetch?: typeof globalThis.fetch;
+}): Promise<bigint>;
+/** `account`'s finalized balance in clearing units and, when the service
+ * retains one, the proof `withdrawFromClearing` closes it with. */
+export declare function clearingBalance(serviceUrl: string, account: Hex, fetcher?: typeof globalThis.fetch): Promise<ClearingBalance>;
+export interface ClearingChain {
+    rpcUrl: string;
+    chainId: number;
+    /** The EVM account that sends the transactions and pays their gas. */
+    from: LocalAccount;
+    settlement: Address;
+}
+/** 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 whose outcome is unknown is not
+ * sent again: the error names it. */
+export declare function depositToClearing(opts: ClearingChain & {
+    asset: Address;
+    account: Hex;
+    amount: bigint;
+    timeoutMs?: number;
+    pollMs?: number;
+}): Promise<{
+    approveTx: Hex | null;
+    depositTx: Hex;
+}>;
+/** A payout claimed, `amount` in token base units. */
+type ClearingClaim = {
+    amount: bigint;
+    tx: Hex;
+    deferred: boolean;
+};
+export type ClearingWithdrawal = 
+/** A withdrawal is queued and `epoch`, the one that carries it, has not
+ * finalized; nothing can be sent until it does. */
+{
+    status: "waiting";
+    epoch: bigint;
+}
+/** What this call sent: the account's payout it claimed, to the
+ * destination the finalized withdrawal named, and the withdrawal it
+ * queued for the account's finalized balance, or `null` when that balance
+ * is zero. A
+ * deferred payout is one the destination refused: it waits in the
+ * contract's `unclaimedPayout` until the destination calls
+ * `withdrawUnclaimed`. */
+ | {
+    status: "sent";
+    claimed: ClearingClaim[];
+    queued: {
+        tx: Hex;
+    } | null;
+};
+/** 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. */
+export declare function withdrawFromClearing(opts: ClearingChain & {
+    signer: ClearingSigner;
+    serviceUrl: string;
+    destination?: Address;
+    fetch?: typeof globalThis.fetch;
+}): Promise<ClearingWithdrawal>;
+export type ClearingRecovery = 
+/** The deployment has missed no deadline: withdraw with `withdrawFromClearing`. */
+{
+    status: "operating";
+}
+/** Faulted, and `epoch`, admitted before the fault, is still in its
+ * challenge window; recovery starts once it is final. `claimed` is the
+ * payout of the account's finalized withdrawal, claimed meanwhile. */
+ | {
+    status: "waiting";
+    epoch: bigint;
+    claimed: ClearingClaim[];
+}
+/** What this call sent: the fault it raised, if it raised one, the
+ * payout of the account's finalized withdrawal, claimed to the
+ * destination it named, the account's last finalized balance, and each
+ * deposit no final epoch counted. `recover` pays a withdrawal still in
+ * flight to the destination it named and the rest to `destination`. A
+ * deferred payout waits in `unclaimedPayout` for `withdrawUnclaimed`.
+ * Every amount is in token base units. */
+ | {
+    status: "recovered";
+    faulted: Hex | null;
+    claimed: ClearingClaim[];
+    recovered: {
+        amount: bigint;
+        tx: Hex;
+    } | null;
+    refunded: {
+        epoch: bigint;
+        amount: bigint;
+        tx: Hex;
+    }[];
+};
+/** 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 declare function recoverFromClearing(opts: ClearingChain & {
+    signer: ClearingSigner;
+    serviceUrl: string | readonly string[];
+    destination?: Address;
+    fetch?: typeof globalThis.fetch;
+}): Promise<ClearingRecovery>;
+export {};