@bananapus/nana-sdk-core 2.38.2 → 2.39.0

package/dist/cjs/review/heldWrite.d.ts

@@ -0,0 +1,113 @@
+import type { Hex, TransactionReceipt } from "viem";
+import { type WriteHoldClient, type WriteHoldGate, type WriteHoldHandle, type WriteHoldSettled, type WriteHoldState } from "./writeHold.js";
+/**
+ * Where one held write stands, for the one way every app shows it:
+ *
+ * - `clear`: nothing held (a failure or expiry from an earlier visit is in
+ *   `settled`);
+ * - `succeeded`: a success the hold settled while the user was away: every
+ *   send refuses until they acknowledge it (`acknowledge`, "Send it again"),
+ *   since sending again may pay twice;
+ * - `awaiting`: a Safe proposal waiting for its signers;
+ * - `confirming`: sent, being confirmed; once a write is confirming it never
+ *   goes back to awaiting;
+ * - `held`: held with the hold's own line (its exit when `exit`);
+ * - `settled`: the hold settled what this view saw held, on authenticated
+ *   evidence;
+ * - `released`: the user's exit released it (`releasedBy: "user"`), or another
+ *   window did (`"other-tab"`, neutral copy).
+ */
+export type HeldWritePhase = "clear" | "succeeded" | "awaiting" | "confirming" | "held" | "settled" | "released";
+export type HeldWriteView = {
+    phase: HeldWritePhase;
+    /** The last hold state this view accepted. */
+    state: WriteHoldState | null;
+    /** The one line to show, or null. */
+    line: string | null;
+    /** A second line for an exit that can run the write twice. */
+    warning?: string;
+    /** While holds last only in this tab. */
+    notice?: string;
+    /** Whether the gated hold offers its exit right now. */
+    exit: boolean;
+    settled?: WriteHoldSettled;
+    releasedBy?: "user" | "other-tab";
+    /** A previous deploy's record is being moved into the hold: sends wait. */
+    adopting: boolean;
+};
+/** What a previous deploy saved of a write: the evidence `hold.adopt` takes. */
+export type HeldWriteEvidence = NonNullable<Parameters<WriteHoldHandle["adopt"]>[1]>;
+/** How often a held write is asked again: 30 s by default, kept between 15 s and 60 s. */
+export declare const HELD_POLL_MS = 30000;
+/**
+ * Follow one held write to its end, whatever becomes of the flow that sent
+ * it: a direct transaction by its hold's own reads, a Safe proposal also by
+ * Safe's service, whose execution goes to the hold (`onExecuted`) and whose
+ * loss ends it unproven (`onUnproven`). It ends only when the hold is clear
+ * (an authenticated settlement or an exit) or `signal` aborts: never on its
+ * own reading of a receipt, a replacement or an expiry. The hold decides.
+ */
+export declare function followHeldWrite(handle: WriteHoldHandle, client: WriteHoldClient, { signal, pollMs, fastMs, }: {
+    signal: AbortSignal;
+    pollMs?: number;
+    fastMs?: number;
+}): Promise<WriteHoldState | null>;
+/**
+ * Whether `next` would hide an exit `shown` offers without the chain having
+ * been checked: an emission, a replay or a contended read
+ * (`checked: false`). Only a checked answer removes it.
+ */
+export declare function hidesShownExit(shown: WriteHoldState | null | undefined, next: WriteHoldState): boolean;
+/** The line for a settlement. */
+export declare function settledLine(settled: WriteHoldSettled): string;
+/**
+ * One held write's view, framework-free: its phase and line, the watch
+ * (the hold's own events, and a checked read on start, on focus and every
+ * poll while held), a shared follower for its hash, its exit, its send and
+ * the adoption of a previous deploy's record. Every app binds the same one
+ * (useHeldWrite in React), so the same action behaves the same everywhere.
+ *
+ * - A read the chain didn't check never hides an exit already shown.
+ * - Once confirming, a write never goes back to awaiting.
+ * - `onSettled` fires once, only for a settlement of what this view saw held.
+ * - A hold released without a settlement is `released`: by the user's exit
+ *   here, or neutrally by another window.
+ */
+export declare function createHeldWriteView(handle: WriteHoldHandle, options: {
+    client: WriteHoldClient;
+    pollMs?: number;
+    /** Follow a held hash to its end (default true). */
+    follow?: boolean;
+    onSettled?: (settled: WriteHoldSettled, receipt: TransactionReceipt | null) => void;
+    onReleased?: (by: "user" | "other-tab") => void;
+    /** A previous deploy's saved evidence of this write, if any: adopted before any send. */
+    adopt?: () => Promise<HeldWriteEvidence | null | undefined>;
+    /** The state the hold took the adopted record into (held, or settled). */
+    onAdopted?: (state: WriteHoldState) => void;
+}): {
+    get: () => HeldWriteView;
+    subscribe(listener: () => void): () => void;
+    check: () => Promise<HeldWriteView>;
+    /**
+     * Start watching: the hold's events, a checked read now (after adoption),
+     * on focus and every poll while held. Returns the stop.
+     */
+    start(): () => void;
+    /**
+     * The user checked their wallet: the exit the shown state offers, asked
+     * of the chain once more. True when released: the app reopens its review.
+     */
+    exit(): Promise<boolean>;
+    /**
+     * Send under the hold, once any adoption is done. A held write refuses
+     * with the hold's checked state shown.
+     */
+    send(run: (gate: WriteHoldGate) => Promise<Hex>): Promise<Hex>;
+    /**
+     * The user saw a success that settled while away and chose to send again:
+     * the hold marks it acknowledged, for every reader, and sends are allowed.
+     */
+    acknowledge(): Promise<void>;
+};
+export type HeldWriteViewController = ReturnType<typeof createHeldWriteView>;
+//# sourceMappingURL=heldWrite.d.ts.map

package/dist/cjs/review/heldWrite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heldWrite.d.ts","sourceRoot":"","sources":["../../../src/review/heldWrite.ts"],"names":[],"mappings":"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"}

package/dist/cjs/review/heldWrite.js

@@ -0,0 +1,551 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HELD_POLL_MS = void 0;
+exports.followHeldWrite = followHeldWrite;
+exports.hidesShownExit = hidesShownExit;
+exports.settledLine = settledLine;
+exports.createHeldWriteView = createHeldWriteView;
+const safeService_js_1 = require("../safeService.js");
+const messages_js_1 = require("./messages.js");
+const writeHold_js_1 = require("./writeHold.js");
+/** How often a held write is asked again: 30 s by default, kept between 15 s and 60 s. */
+exports.HELD_POLL_MS = 30_000;
+const MIN_POLL_MS = 15_000;
+const MAX_POLL_MS = 60_000;
+/** A follower's first looks, a few seconds apart, before it slows to the poll. */
+const FAST_MS = 4_000;
+const FAST_LOOKS = 15;
+/** A direct write's confirming line gives way to the wallet's pending line after this long. */
+const CONFIRMING_MS = 120_000;
+const pollOf = (ms) => Math.min(MAX_POLL_MS, Math.max(MIN_POLL_MS, ms ?? exports.HELD_POLL_MS));
+function pause(ms, signal) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(done, ms);
+        signal.addEventListener("abort", done, { once: true });
+        function done() {
+            clearTimeout(timer);
+            signal.removeEventListener("abort", done);
+            resolve();
+        }
+    });
+}
+/**
+ * Follow one held write to its end, whatever becomes of the flow that sent
+ * it: a direct transaction by its hold's own reads, a Safe proposal also by
+ * Safe's service, whose execution goes to the hold (`onExecuted`) and whose
+ * loss ends it unproven (`onUnproven`). It ends only when the hold is clear
+ * (an authenticated settlement or an exit) or `signal` aborts: never on its
+ * own reading of a receipt, a replacement or an expiry. The hold decides.
+ */
+async function followHeldWrite(handle, client, { signal, pollMs, fastMs = FAST_MS, }) {
+    const now = handle.peek();
+    if (now.status !== "clear" &&
+        now.record.safe &&
+        now.record.hash &&
+        !now.record.executed &&
+        (0, safeService_js_1.hasSafeService)(now.record.chainId)) {
+        const proposal = now.record.hash;
+        void (0, safeService_js_1.waitForSafeExecutionHash)(now.record.chainId, proposal, {
+            signal,
+            client: client,
+        })
+            .then((execution) => handle.onExecuted(client, execution), () => (signal.aborted ? null : handle.onUnproven(client, proposal)))
+            .catch(() => null);
+    }
+    for (let look = 0; !signal.aborted; look += 1) {
+        const state = await handle.state(client).catch(() => null);
+        if (state?.status === "clear")
+            return state;
+        await pause(look < FAST_LOOKS ? fastMs : pollOf(pollMs), signal);
+    }
+    return null;
+}
+/** Reservations seen confirming in this tab: a new view of one never shows it awaiting. */
+const confirmed = new Set();
+/** One follower per reservation in this tab, however many views show it. */
+const followers = new Map();
+function followShared(reservation, handle, client, pollMs) {
+    let shared = followers.get(reservation);
+    // A follower stopped by its last view, still ending, is never rejoined.
+    if (!shared || shared.stop.signal.aborted) {
+        const stop = new AbortController();
+        const ended = followHeldWrite(handle, client, {
+            signal: stop.signal,
+            pollMs,
+        }).finally(() => {
+            if (followers.get(reservation)?.stop === stop)
+                followers.delete(reservation);
+        });
+        shared = { views: 0, stop, ended };
+        followers.set(reservation, shared);
+    }
+    shared.views += 1;
+    const joined = shared;
+    return {
+        ended: joined.ended,
+        leave() {
+            joined.views -= 1;
+            if (joined.views === 0)
+                joined.stop.abort();
+        },
+    };
+}
+/**
+ * Whether `next` would hide an exit `shown` offers without the chain having
+ * been checked: an emission, a replay or a contended read
+ * (`checked: false`). Only a checked answer removes it.
+ */
+function hidesShownExit(shown, next) {
+    return (!!shown &&
+        shown.status !== "clear" &&
+        shown.exit &&
+        next.status !== "clear" &&
+        !next.exit &&
+        next.checked !== true);
+}
+/** The line for a settlement. */
+function settledLine(settled) {
+    return settled.result === "success"
+        ? messages_js_1.HELD_SUCCESS_LINE
+        : settled.result === "expired"
+            ? messages_js_1.HELD_EXPIRED_LINE
+            : messages_js_1.WRITE_HOLD_REVERTED_LINE;
+}
+/**
+ * One held write's view, framework-free: its phase and line, the watch
+ * (the hold's own events, and a checked read on start, on focus and every
+ * poll while held), a shared follower for its hash, its exit, its send and
+ * the adoption of a previous deploy's record. Every app binds the same one
+ * (useHeldWrite in React), so the same action behaves the same everywhere.
+ *
+ * - A read the chain didn't check never hides an exit already shown.
+ * - Once confirming, a write never goes back to awaiting.
+ * - `onSettled` fires once, only for a settlement of what this view saw held.
+ * - A hold released without a settlement is `released`: by the user's exit
+ *   here, or neutrally by another window.
+ */
+function createHeldWriteView(handle, options) {
+    const { client } = options;
+    let view = {
+        phase: "clear",
+        state: null,
+        line: null,
+        exit: false,
+        adopting: !!options.adopt,
+    };
+    const listeners = new Set();
+    /** The reservation this view saw held, and whether its exit here released it. */
+    let observed;
+    let wasHeld = false;
+    let exitedHere;
+    const delivered = new Set();
+    /** Every reservation this view saw held and hasn't delivered: each is delivered once, whatever is shown. */
+    const seen = new Set();
+    let following;
+    let running = false;
+    /** Each start and stop begins a new lifecycle: a read or receipt from an earlier one is dropped. */
+    let epoch = 0;
+    let live = true;
+    let adoption;
+    function set(next) {
+        view = { ...view, ...next };
+        for (const listener of listeners)
+            listener();
+    }
+    function stopFollowing() {
+        following?.leave();
+        following = undefined;
+    }
+    function follow(reservation) {
+        if (options.follow === false ||
+            !running ||
+            following?.reservation === reservation)
+            return;
+        stopFollowing();
+        const shared = followShared(reservation, handle, client, options.pollMs);
+        const mine = { reservation, leave: shared.leave };
+        following = mine;
+        const at = epoch;
+        void shared.ended.then((end) => {
+            if (following === mine)
+                following = undefined;
+            if (end && at === epoch)
+                apply(end);
+        });
+    }
+    /** Settlements this view saw, still to tell the app, by reservation: kept across a restart. */
+    const undelivered = new Map();
+    /**
+     * Tell the app of a settlement it saw held, once, while live. Only once its
+     * callback ran is it done, and a success acknowledged: a lifecycle change
+     * before then leaves it to the next start.
+     */
+    function deliver(settled, key) {
+        undelivered.set(key, settled);
+        if (!live)
+            return;
+        const at = epoch;
+        const done = (receipt) => {
+            if (at !== epoch || delivered.has(key))
+                return;
+            delivered.add(key);
+            undelivered.delete(key);
+            if ("hash" in settled)
+                told.add(settled.hash.toLowerCase());
+            options.onSettled?.(settled, receipt);
+            present();
+            // Told: the hold marks it acknowledged, so no later visit asks again.
+            if ("hash" in settled &&
+                settled.result === "success" &&
+                !settled.acknowledged)
+                void handle.acknowledge(settled).catch(() => null);
+        };
+        if (!options.onSettled || !("hash" in settled)) {
+            done(null);
+            return;
+        }
+        void client.getTransactionReceipt({ hash: settled.hash }).then((receipt) => done(receipt), () => done(null));
+    }
+    /** The phase and line a held state shows, monotonic once confirming. */
+    function heldView(next) {
+        // A held state's reservation is its record's id.
+        const reservation = next.record.id;
+        const record = next.record;
+        if (next.status === "ran-executed" ||
+            (record.safe &&
+                (record.executed ||
+                    record.executionHash !== undefined ||
+                    (record.candidates?.length ?? 0) > 0)))
+            confirmed.add(reservation);
+        const base = {
+            state: next,
+            exit: next.exit,
+            warning: "warning" in next ? next.warning : undefined,
+            notice: next.notice,
+            settled: undefined,
+            releasedBy: undefined,
+        };
+        if (next.exit)
+            return { ...base, phase: "held", line: next.line };
+        if (next.status === "ran-executed")
+            return {
+                ...base,
+                phase: "confirming",
+                line: messages_js_1.HELD_CONFIRMING_LINE,
+            };
+        if (next.status === "pending-known-hash") {
+            if (record.safe)
+                return confirmed.has(reservation)
+                    ? {
+                        ...base,
+                        phase: "confirming",
+                        line: messages_js_1.HELD_CONFIRMING_LINE,
+                    }
+                    : {
+                        ...base,
+                        phase: "awaiting",
+                        line: safeService_js_1.SAFE_PROPOSAL_AWAITING,
+                    };
+            // A direct write: confirming, until the wallet has held it a while.
+            const since = Number(record.submittedAt ?? record.firstSeenAt);
+            const line = next.line === messages_js_1.WRITE_HOLD_PENDING_LINE &&
+                !(Date.now() - since >= CONFIRMING_MS)
+                ? messages_js_1.HELD_CONFIRMING_LINE
+                : next.line;
+            return { ...base, phase: "confirming", line };
+        }
+        return { ...base, phase: "held", line: next.line };
+    }
+    /** Take a hold state, through the one guard every source goes through. */
+    function apply(next) {
+        if (!next || hidesShownExit(view.state, next))
+            return;
+        if (next.status === "clear") {
+            const reservation = next.reservation;
+            const mine = wasHeld && (!reservation || reservation === observed);
+            stopFollowing();
+            if (next.settled && mine) {
+                seen.delete(observed);
+                deliver(next.settled, observed);
+                set({
+                    phase: "settled",
+                    state: next,
+                    line: settledLine(next.settled),
+                    warning: undefined,
+                    notice: undefined,
+                    exit: false,
+                    settled: next.settled,
+                    releasedBy: undefined,
+                });
+            }
+            else if (mine) {
+                const by = exitedHere === observed ? "user" : "other-tab";
+                set({
+                    phase: "released",
+                    state: next,
+                    line: by === "user" ? messages_js_1.HELD_RELEASED_LINE : messages_js_1.HELD_RELEASED_ELSEWHERE_LINE,
+                    warning: undefined,
+                    notice: undefined,
+                    exit: false,
+                    settled: undefined,
+                    releasedBy: by,
+                });
+                options.onReleased?.(by);
+            }
+            else if (view.phase === "settled" || view.phase === "released") {
+                // Already shown: kept, unless the gate below has another success.
+            }
+            else
+                set({
+                    phase: "clear",
+                    state: next,
+                    line: null,
+                    warning: undefined,
+                    notice: undefined,
+                    exit: false,
+                    settled: next.settled,
+                });
+            if (mine)
+                seen.delete(observed);
+            wasHeld = false;
+            observed = undefined;
+            exitedHere = undefined;
+            collect();
+            present();
+            return;
+        }
+        const reservation = next.record.id;
+        if (observed !== reservation) {
+            observed = reservation;
+            exitedHere = undefined;
+        }
+        wasHeld = true;
+        seen.add(reservation);
+        set(heldView(next));
+        if (next.record.hash)
+            follow(reservation);
+        collect();
+    }
+    /** Deliver the settlement of every other reservation this view saw held. */
+    function collect() {
+        for (const reservation of [...seen]) {
+            if (reservation === observed)
+                continue;
+            const settled = handle.settlementOf(reservation);
+            if (!settled)
+                continue;
+            seen.delete(reservation);
+            deliver(settled, reservation);
+        }
+    }
+    /**
+     * The send gate, from current evidence alone: any unacknowledged success
+     * of the intent or an eligible legacy hold. It holds whatever is shown.
+     */
+    function unacknowledged() {
+        if (gate())
+            throw new Error(messages_js_1.HELD_AWAY_SUCCESS_LINE);
+    }
+    /** Successes this view told the app of: their acknowledgement is under way. */
+    const told = new Set();
+    /** The gate's success, but for one this view already told the app of. */
+    function gate() {
+        return handle.unacknowledgedSuccess((hash) => told.has(hash.toLowerCase()));
+    }
+    /**
+     * Show the gate's success as `succeeded` ("Send it again") once nothing is
+     * left to deliver, unless a hold is shown.
+     */
+    function present() {
+        const success = gate();
+        if (!success || undelivered.size)
+            return;
+        if (view.phase === "awaiting" ||
+            view.phase === "confirming" ||
+            view.phase === "held")
+            return;
+        // A success this view saw settle was told, so the gate never names it.
+        set({
+            phase: "succeeded",
+            state: view.state,
+            line: messages_js_1.HELD_AWAY_SUCCESS_LINE,
+            warning: undefined,
+            notice: undefined,
+            exit: false,
+            settled: { result: "success", hash: success.hash },
+            releasedBy: undefined,
+        });
+    }
+    /** The gated answer, now. */
+    async function check() {
+        const at = epoch;
+        const next = await handle.state(client).catch(() => null);
+        if (at === epoch)
+            apply(next);
+        return view;
+    }
+    /** Move a previous deploy's record into the hold, once, before any send. */
+    function adopt() {
+        const provider = options.adopt;
+        if (!provider)
+            return Promise.resolve(true);
+        adoption ??= (async () => {
+            set({ adopting: true });
+            // Each answer is this lifecycle's only: a stopped view's late read
+            // applies nothing and acknowledges nothing.
+            const at = epoch;
+            const current = () => {
+                if (at !== epoch)
+                    throw new Error("Stopped while adopting.");
+            };
+            const snapshot = await handle.state(client);
+            current();
+            apply(snapshot);
+            if (snapshot.status === "clear") {
+                const evidence = await provider();
+                current();
+                if (evidence) {
+                    const state = await handle.adopt(snapshot, evidence, client);
+                    current();
+                    // Unread (the chain, or a lock another writer held): no send until it is.
+                    if (state.declined === "unreadable")
+                        throw new Error("The saved write couldn't be checked.");
+                    apply(state);
+                    if (state.status !== "clear" || state.settled)
+                        options.onAdopted?.(state);
+                }
+            }
+            set({ adopting: false });
+            return true;
+        })().catch(() => {
+            // Unchecked: asked again on the next send.
+            adoption = undefined;
+            set({ adopting: false });
+            return false;
+        });
+        return adoption;
+    }
+    return {
+        get: () => view,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => void listeners.delete(listener);
+        },
+        check,
+        /**
+         * Start watching: the hold's events, a checked read now (after adoption),
+         * on focus and every poll while held. Returns the stop.
+         */
+        start() {
+            running = true;
+            live = true;
+            epoch += 1;
+            // Every settlement a stopped lifecycle never told is told now.
+            for (const [key, settled] of [...undelivered])
+                deliver(settled, key);
+            const unsubscribe = handle.subscribe(apply);
+            // An adoption a stopped lifecycle left unfinished runs again here.
+            void adopt()
+                .then((done) => (done || !running ? done : adopt()))
+                .then(() => (running ? check() : view));
+            const timer = setInterval(() => {
+                const held = view.phase === "awaiting" ||
+                    view.phase === "confirming" ||
+                    view.phase === "held";
+                const hidden = globalThis.document?.visibilityState === "hidden";
+                if (held && !hidden)
+                    void check();
+            }, pollOf(options.pollMs));
+            const onFocus = () => void check();
+            globalThis.addEventListener?.("focus", onFocus);
+            return () => {
+                running = false;
+                live = false;
+                epoch += 1;
+                unsubscribe();
+                clearInterval(timer);
+                globalThis.removeEventListener?.("focus", onFocus);
+                stopFollowing();
+            };
+        },
+        /**
+         * The user checked their wallet: the exit the shown state offers, asked
+         * of the chain once more. True when released: the app reopens its review.
+         */
+        async exit() {
+            const shown = view.state;
+            if (!shown || shown.status === "clear" || !view.exit)
+                return false;
+            exitedHere = shown.record.id;
+            const ended = await handle.exit(shown, { checkedWallet: true }, client);
+            if (!ended.released)
+                exitedHere = undefined;
+            apply(ended.state);
+            return ended.released;
+        },
+        /**
+         * Send under the hold, once any adoption is done. A held write refuses
+         * with the hold's checked state shown.
+         */
+        async send(run) {
+            if (!(await adopt()))
+                throw new Error("Saved transactions are still being checked. Try again in a moment.");
+            unacknowledged();
+            // The send's own check may find one too: it says so before the wallet.
+            const unsubscribe = handle.subscribe(apply);
+            try {
+                const hash = await handle.send(client, async (gate) => {
+                    unacknowledged();
+                    return run({
+                        ...gate,
+                        // Asked again at the reservation itself, after any lock retries.
+                        async beforeSend(actualCall) {
+                            unacknowledged();
+                            await gate.beforeSend(actualCall);
+                            try {
+                                unacknowledged();
+                            }
+                            catch (error) {
+                                gate.onRejected();
+                                throw error;
+                            }
+                        },
+                    });
+                });
+                unsubscribe();
+                apply(handle.peek());
+                return hash;
+            }
+            catch (error) {
+                unsubscribe();
+                // Its own evidence, checked or not: a contended refusal hides no exit.
+                if (error instanceof writeHold_js_1.WriteHeldError)
+                    apply(error.state);
+                else if (view.phase !== "succeeded")
+                    await check();
+                throw error;
+            }
+        },
+        /**
+         * The user saw a success that settled while away and chose to send again:
+         * the hold marks it acknowledged, for every reader, and sends are allowed.
+         */
+        async acknowledge() {
+            const success = gate();
+            if (view.phase !== "succeeded" || !success)
+                return;
+            const at = epoch;
+            await handle.acknowledge({ result: success.result, hash: success.hash });
+            // Only that success's presentation ends: never a newer hold or its exit.
+            if (at === epoch &&
+                view.phase === "succeeded" &&
+                view.settled !== undefined &&
+                "hash" in view.settled &&
+                view.settled.hash === success.hash)
+                set({ phase: "clear", line: null, settled: undefined, state: null });
+            // Another success still unacknowledged is shown next.
+            present();
+        },
+    };
+}
+//# sourceMappingURL=heldWrite.js.map