mppx 0.17.1 → 0.17.4

package/dist/cloudflare/ChannelStore.js

@@ -0,0 +1,304 @@
+import { Json } from 'ox';
+import * as Store from '../Store.js';
+import { pendingCloseClockSkewSeconds, pendingCloseValiditySeconds, resolveSettleableVoucher, } from '../tempo/session/server/ChannelStore.js';
+/** Storage key of a channel object's settlement bookkeeping, beside the channel state. */
+const settlementKey = 'mppx:channel-store:settlement';
+/**
+ * Durable Object class that stores Tempo session channels, as {@link Store.durableObject}
+ * does, and settles them on-chain without a request in flight.
+ *
+ * Every channel lives in its own object. After each write of a channel state, the object
+ * checks how much a settlement could capture ({@link unsettledAmount}): from
+ * `max(10% of deposit, minUnsettledAmount)` it sends `{ channelId }` to the settlement
+ * queue at once; below that it sets an alarm that sends it once the channel has had no
+ * write for `staleAfterMs`. The Worker's `queue()` handler settles it with
+ * {@link settle}. After each send, a watchdog alarm sends it again while the channel
+ * stays unsettled (a dropped, dead-lettered or failed job), waiting twice as long each
+ * time, up to `maxAttempts` sends; settling more on-chain restarts the count. A close request,
+ * or a threshold's worth of new vouchers since the last send, sends it again at once and
+ * restarts the count, so a failed job never leaves them waiting on a long watchdog.
+ *
+ * Export a subclass from your Worker, bind it with a `new_sqlite_classes` migration and
+ * bind the queue as `MPPX_SETTLEMENT_QUEUE`, or override
+ * {@link ChannelStore.settlement} to change the queue or thresholds.
+ *
+ * @example
+ * ```ts
+ * import { DurableObject } from 'cloudflare:workers'
+ * import { ChannelStore } from 'mppx/cloudflare'
+ *
+ * export class MppxChannels extends ChannelStore.rpc(DurableObject) {}
+ * ```
+ */
+export class ChannelStore extends Store.DurableObjectStore {
+    /**
+     * The settlement queue and thresholds. Reads the `MPPX_SETTLEMENT_QUEUE` binding by
+     * default; a subclass overrides it to use another binding or other thresholds.
+     */
+    settlement() {
+        const env = this.env;
+        return { queue: env?.MPPX_SETTLEMENT_QUEUE };
+    }
+    /** Schedules settlement of a written channel state, and drops it for a closed or deleted one. */
+    async onWrite(key, _previous, next, transaction) {
+        // Writing through the store's transaction, when it has one, commits or rolls back with the write.
+        const storage = transaction ?? this.storage;
+        const pending = (await storage.get(settlementKey));
+        const settlement = resolveSettlement(this.settlement());
+        const due = isChannelState(next) ? settlementDue(next, settlement) : undefined;
+        if (!due || !isChannelState(next)) {
+            if (pending?.key === key)
+                await storage.delete(settlementKey);
+            return;
+        }
+        // A job settled more on-chain since it was sent: the job is done, so restart the count.
+        const progressed = pending?.settledAtSend !== undefined && next.settledOnChain > pending.settledAtSend;
+        // Work the last send did not cover: a close request (once the escrow's grace period ends,
+        // the payer can withdraw what is unsettled) or a threshold's worth of new vouchers. Send it
+        // at once and restart the count instead of waiting for a watchdog that may be far off.
+        const renewed = !!pending?.sends &&
+            ((closing(next) && closeRequest(next) !== pending.closeRequestAtSend) ||
+                (pending.capturedAtSend !== undefined &&
+                    settleableAmount(next) - pending.capturedAtSend >= threshold(next, settlement)));
+        const sending = progressed || renewed ? undefined : pending?.sends ? pending : undefined;
+        const updated = {
+            channelId: next.channelId,
+            key,
+            sends: sending?.sends ?? 0,
+            updatedAt: Date.now(),
+            ...(sending
+                ? {
+                    capturedAtSend: sending.capturedAtSend,
+                    closeRequestAtSend: sending.closeRequestAtSend,
+                    settledAtSend: sending.settledAtSend,
+                    watchdogAt: sending.watchdogAt,
+                }
+                : {}),
+        };
+        await storage.put(settlementKey, updated);
+        // A job is in flight: it settles the latest voucher, and its watchdog alarm stays, waking no
+        // later than the end of the server's close marker, after which a payer close request it hid shows.
+        if (sending)
+            return wakeBy(storage, pendingCloseEnd(next) ?? Infinity);
+        // Sent from an alarm that fires at once: a queue send here would let another write in before this one commits.
+        const at = due === 'threshold' || closing(next)
+            ? Date.now()
+            : Math.min(updated.updatedAt + settlement.staleAfterMs, pendingCloseEnd(next) ?? Infinity);
+        await wakeBy(storage, at);
+    }
+    /** Sends a channel over the threshold or gone stale to the queue, or sends it again from the watchdog while unsettled. */
+    async alarm() {
+        await super.alarm();
+        let pending = (await this.storage.get(settlementKey));
+        if (!pending)
+            return;
+        const raw = await this.storage.get(pending.key);
+        // The store writes JSON text, or native values with `encoding: 'native'`.
+        const state = typeof raw === 'string' ? Json.parse(raw) : (raw ?? null);
+        const settlement = resolveSettlement(this.settlement());
+        const due = isChannelState(state) ? settlementDue(state, settlement) : undefined;
+        if (!due) {
+            await this.storage.delete(settlementKey);
+            return;
+        }
+        // The channel had a write since this alarm was set: wait until it has been idle long enough.
+        const staleAt = pending.updatedAt + settlement.staleAfterMs;
+        if (!pending.sends && due === 'stale' && !closing(state) && Date.now() < staleAt)
+            return this.storage.setAlarm(Math.min(staleAt, pendingCloseEnd(state) ?? Infinity));
+        // A close request the last send did not cover, such as one the server's close marker hid until
+        // it expired, restarts the count as a write would.
+        if (pending.sends &&
+            closing(state) &&
+            closeRequest(state) !== pending.closeRequestAtSend) {
+            pending = { ...pending, sends: 0 };
+            await this.storage.put(settlementKey, pending);
+        }
+        // An alarm set for something that no longer needs a send, such as the end of a close marker a
+        // failed close then cleared: wait for the watchdog rather than spend an attempt early.
+        // A threshold's worth of vouchers the last send did not capture, such as ones written while
+        // it was in flight, still goes at once.
+        const uncaptured = pending.capturedAtSend !== undefined &&
+            settleableAmount(state) - pending.capturedAtSend >=
+                threshold(state, settlement);
+        if (pending.sends &&
+            !uncaptured &&
+            pending.watchdogAt !== undefined &&
+            Date.now() < pending.watchdogAt)
+            return this.storage.setAlarm(Math.min(pending.watchdogAt, pendingCloseEnd(state) ?? Infinity));
+        await this.send(pending, state, settlement, this.storage);
+    }
+    /**
+     * Sends the channel to the settlement queue and sets the watchdog alarm, or gives up after
+     * `maxAttempts` sends. A send that fails leaves the count alone and tries again from an
+     * alarm, since the write that scheduled it has already committed.
+     */
+    async send(pending, state, settlement, storage) {
+        const sends = pending.sends + 1;
+        if (sends > settlement.maxAttempts) {
+            // A live close marker may hide a payer close request merged into it: wake when it ends,
+            // when a close request restarts the count, rather than giving up for good now.
+            const markerEnd = pendingCloseEnd(state);
+            if (markerEnd !== undefined)
+                return wakeBy(storage, markerEnd);
+            await storage.delete(settlementKey);
+            return;
+        }
+        // A missing binding is a configuration error: fail the alarm so it shows in the Worker's
+        // logs and Cloudflare retries it with backoff, rather than waking every minute in silence.
+        if (!settlement.queue)
+            throw new Error('ChannelStore: no settlement queue (bind MPPX_SETTLEMENT_QUEUE).');
+        try {
+            await settlement.queue.send({ channelId: pending.channelId });
+        }
+        catch {
+            // Retry from the alarm without waiting for the last watchdog. Keep a sooner alarm that a
+            // write during the send set, such as for a close request.
+            const current = (await storage.get(settlementKey));
+            if (current?.key === pending.key && current.watchdogAt !== undefined)
+                await storage.put(settlementKey, { ...current, watchdogAt: undefined });
+            await wakeBy(storage, Date.now() + settlement.retryMs);
+            return;
+        }
+        // The send awaited the queue, so a channel write may have changed the bookkeeping since
+        // (such as restarting the count after progress): count this send against what is there now.
+        const current = (await storage.get(settlementKey));
+        if (current?.key !== pending.key)
+            return;
+        const counted = current.sends + 1;
+        const watchdog = settlement.watchdogMs * 2 ** (counted - 1);
+        // Once the escrow's grace period ends, the payer can withdraw what is unsettled: resend a
+        // closing channel often enough that every attempt fits inside it.
+        const watchdogAt = Date.now() + (closing(state) ? Math.min(watchdog, closingWatchdogMs) : watchdog);
+        await storage.put(settlementKey, {
+            ...current,
+            capturedAtSend: settleableAmount(state),
+            closeRequestAtSend: closeRequest(state),
+            sends: counted,
+            settledAtSend: state.settledOnChain,
+            watchdogAt,
+        });
+        // A write during the send (such as a close request) may have set a sooner alarm from a newer
+        // state: keep it.
+        await wakeBy(storage, Math.min(watchdogAt, pendingCloseEnd(state) ?? Infinity));
+    }
+}
+/**
+ * Longest wait before sending a closing channel again: its default six sends then span 10
+ * minutes, inside the escrow's 15-minute close grace period.
+ */
+const closingWatchdogMs = 2 * 60_000;
+/** Fills in the defaults of a {@link ChannelStore.Settlement}. */
+function resolveSettlement(settlement) {
+    const resolved = {
+        maxAttempts: settlement.maxAttempts ?? 6,
+        minUnsettledAmount: settlement.minUnsettledAmount ?? 100000n,
+        queue: settlement.queue,
+        retryMs: settlement.retryMs ?? 60_000,
+        staleAfterMs: settlement.staleAfterMs ?? 300_000,
+        watchdogMs: settlement.watchdogMs ?? 5 * 60_000,
+    };
+    // A non-finite delay would schedule no alarm at all, silently never settling.
+    for (const name of ['retryMs', 'staleAfterMs', 'watchdogMs'])
+        if (!(Number.isFinite(resolved[name]) && resolved[name] >= 0))
+            throw new Error(`ChannelStore: \`${name}\` must be a finite, non-negative number.`);
+    if (!(Number.isSafeInteger(resolved.maxAttempts) && resolved.maxAttempts > 0))
+        throw new Error('ChannelStore: `maxAttempts` must be a positive integer.');
+    return resolved;
+}
+/** Whether a stored value is a precompile-backed session channel state. */
+export function isChannelState(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const state = value;
+    return (state.backend === 'precompile' &&
+        typeof state.channelId === 'string' &&
+        typeof state.chainId === 'number' &&
+        typeof state.deposit === 'bigint' &&
+        typeof state.settledOnChain === 'bigint' &&
+        typeof state.spent === 'bigint');
+}
+/**
+ * The raw amount a settlement of the channel would capture now: the largest accepted voucher
+ * within `spent` (as mppx's `settle` picks it) above `settledOnChain`.
+ */
+export function unsettledAmount(state) {
+    return settleableAmount(state) - state.settledOnChain;
+}
+/** The cumulative amount a settlement of the channel would bring it to: its settleable voucher's, or `settledOnChain`. */
+function settleableAmount(state) {
+    return resolveSettleableVoucher(state)?.cumulativeAmount ?? state.settledOnChain;
+}
+/** Whether the payer requested a close, after which the escrow's grace period runs. */
+function closing(state) {
+    return closeRequest(state) !== 0n;
+}
+/**
+ * The payer's close request: `closeRequestedAt`, or `0n` without one. The server's own
+ * cooperative-close marker ({@link State.pendingCloseAt}) is not one while that close may still
+ * land ({@link pendingClose}): it captures the vouchers itself. An on-chain close request merged
+ * into the marker keeps its timestamp when the payer's is not later, so once the marker can no
+ * longer land, it counts as one.
+ */
+function closeRequest(state) {
+    if (pendingClose(state))
+        return 0n;
+    return BigInt(state.closeRequestedAt ?? 0n);
+}
+/**
+ * Unix milliseconds at which the server's close marker stops counting as {@link pendingClose},
+ * or `undefined` when it does not count now.
+ */
+function pendingCloseEnd(state) {
+    if (!pendingClose(state))
+        return undefined;
+    return ((Number(state.closeRequestedAt) +
+        pendingCloseValiditySeconds +
+        pendingCloseClockSkewSeconds +
+        1) *
+        1000);
+}
+/** Sets the alarm to `at`, unless it already fires sooner. */
+async function wakeBy(storage, at) {
+    if (!Number.isFinite(at))
+        return;
+    const alarm = await storage.getAlarm();
+    if (alarm === null || at < alarm)
+        await storage.setAlarm(at);
+}
+/**
+ * Whether the server's own cooperative close may still land: its marker stands in
+ * `closeRequestedAt` and its transaction has not expired. That close captures every voucher a
+ * settlement could, so settling meanwhile only spends gas.
+ */
+export function pendingClose(state, now = Date.now()) {
+    if (state.pendingCloseAt === undefined || state.finalized)
+        return false;
+    const requestedAt = BigInt(state.closeRequestedAt ?? 0n);
+    if (requestedAt === 0n || requestedAt !== BigInt(state.pendingCloseAt))
+        return false;
+    const expiresAt = Number(requestedAt) + pendingCloseValiditySeconds + pendingCloseClockSkewSeconds;
+    return Math.floor(now / 1000) <= expiresAt;
+}
+/** The unsettled amount that sends a channel at once: `max(10% of deposit, minUnsettledAmount)`. */
+function threshold(state, settlement) {
+    const minimum = settlement.minUnsettledAmount ?? 100000n;
+    const tenth = state.deposit / 10n;
+    const amount = tenth > minimum ? tenth : minimum;
+    // At least 1: a zero threshold would count every write as a threshold's worth of new vouchers
+    // and restart the send count forever, past `maxAttempts`.
+    return amount > 0n ? amount : 1n;
+}
+/**
+ * When the channel needs settling: `threshold` (now) once the unsettled amount reaches
+ * `max(10% of deposit, minUnsettledAmount)`, `stale` (once idle) below it, or
+ * `undefined` when it is finalized or has nothing to settle.
+ */
+export function settlementDue(state, settlement = {}) {
+    if (state.finalized)
+        return undefined;
+    const unsettled = unsettledAmount(state);
+    if (unsettled <= 0n)
+        return undefined;
+    return unsettled >= threshold(state, settlement) ? 'threshold' : 'stale';
+}
+//# sourceMappingURL=ChannelStore.js.map

package/dist/cloudflare/Channels.d.ts

@@ -0,0 +1,92 @@
+import { type Address } from 'viem';
+import type { MaybePromise } from '../internal/types.js';
+import * as Store from '../Store.js';
+import type { TransactionClient } from '../tempo/session/precompile/Chain.js';
+import type { ResolveSessionChannelId } from '../tempo/session/server/RequestState.js';
+import { settle as settleChannel, type SettlementTransactionOptions } from '../tempo/session/server/Settlement.js';
+/**
+ * Tempo session channel storage on a {@link ChannelStore} Durable Object namespace, to spread
+ * into `tempo.session()`: `store` keeps each channel in its own object, which schedules its
+ * settlement, and `resolveChannelId` finds the payer's open channel to the same payee, token,
+ * escrow, operator and chain, so a client that lost its state resumes it instead of opening another.
+ * The lookup needs the payer's identity, which only a `bootstrap` HEAD proof supplies: enable
+ * `bootstrap` on the session and in the client's session manager, or it never resolves.
+ *
+ * The store keeps that lookup current: after a write opens, closes or finalizes a channel,
+ * it adds or removes the channel under its payer and authorized signer. Each lookup entry is
+ * its own key holding the payer's open channels there, most recent first, so closing one leaves
+ * the others findable. The lookup returns the first whose channel still resumes, so a delayed
+ * write for a channel that has since closed cannot hide an open one, and mppx validates any
+ * channel it resolves before reusing it.
+ *
+ * @example
+ * ```ts
+ * import { channels } from 'mppx/cloudflare'
+ * import { tempo } from 'mppx/server'
+ *
+ * tempo.session({ account, bootstrap: true, currency, getClient, ...channels(env.MPPX_CHANNELS) })
+ * ```
+ */
+export declare function channels(namespace: channels.Namespace, options?: channels.Options): channels.ReturnType;
+export declare namespace channels {
+    /** The Durable Object namespace binding of a {@link ChannelStore} class. */
+    type Namespace = Store.durableObject.Namespace;
+    /** Options of {@link channels}: those of {@link Store.durableObject}, and the escrow. */
+    type Options = Store.durableObject.Options & {
+        /** Escrow the lookup assumes when a challenge names none. @default the TIP20EscrowChannel precompile */
+        escrowContract?: Address | undefined;
+    };
+    /** What `tempo.session()` takes from {@link channels}. */
+    type ReturnType = {
+        /** Finds the payer's open channel for a challenge's payee, token, escrow and chain. */
+        resolveChannelId: ResolveSessionChannelId;
+        /** Channel store that schedules settlement and keeps the channel lookup current. */
+        store: Store.AtomicStore;
+    };
+}
+/**
+ * Settles the channels of a settlement queue batch on-chain, from the Worker's `queue()`
+ * handler. Each message is acknowledged once its channel settled or has nothing left to
+ * settle, and when settlement cannot succeed (the channel is gone or has no voucher); any
+ * other failure, such as a fee over the fee payer's cap, retries it after 30 s, doubling up
+ * to 10 minutes. The {@link ChannelStore} watchdog sends a channel again if its job never settles it.
+ *
+ * @example
+ * ```ts
+ * import { channels, settle } from 'mppx/cloudflare'
+ *
+ * export default {
+ *   async queue(batch, env) {
+ *     await settle(batch, { account, getClient, store: channels(env.MPPX_CHANNELS).store })
+ *   },
+ * }
+ * ```
+ */
+export declare function settle(batch: settle.Batch, parameters: settle.Parameters): Promise<void>;
+export declare namespace settle {
+    /** Parameters of {@link settle}: the channel store, a client, and the settlement transaction's options. */
+    type Parameters = SettlementTransactionOptions & {
+        /** Returns an account-bearing client for the channel's chain. */
+        getClient: (parameters: {
+            chainId: number;
+        }) => MaybePromise<TransactionClient>;
+        /** Settles one channel. @default mppx's `Session.Server.settle` */
+        settle?: typeof settleChannel | undefined;
+        /** The channel store, such as {@link channels}' `store`. */
+        store: Store.AtomicStore;
+    };
+    /** The subset of a Cloudflare `MessageBatch` that {@link settle} uses. */
+    type Batch = {
+        readonly messages: readonly Message[];
+    };
+    /** The subset of a Cloudflare queue `Message` that {@link settle} uses. */
+    type Message = {
+        readonly attempts: number;
+        readonly body: unknown;
+        ack(): void;
+        retry(options?: {
+            delaySeconds?: number;
+        }): void;
+    };
+}
+//# sourceMappingURL=Channels.d.ts.map