@bananapus/nana-sdk-core 2.38.2 → 2.40.0

package/dist/esm/review/writeHold.d.ts

@@ -1,14 +1,22 @@
 import { type Address, type Hex, type PublicClient, type TransactionReceipt } from "viem";
 import { type SafeQueuedTransaction, type SafeServiceOptions } from "../safeService.js";
 import { type HeldWriteStorage, type ReviewedWriteRecoveryInput, type ReviewedWriteRecoveryRecord } from "./writeRecovery.js";
+/** A saved success the user hasn't acknowledged: it blocks sending the action again. */
+export type UnacknowledgedSuccess = {
+    result: "success";
+    hash: Hex;
+    /** The reservation it settled. */
+    reservation?: string;
+};
 /** The reads a write hold makes on the call's chain; a viem PublicClient satisfies it. */
 export type WriteHoldClient = Pick<PublicClient, "getBlock" | "getBlockNumber" | "getChainId" | "getTransaction" | "getTransactionCount" | "getTransactionReceipt" | "request">;
 /** How a held write ended, when the hold saw it end. */
 export type WriteHoldSettled = 
-/** Its verified receipt (a revert only once final). */
+/** Its verified receipt (a revert only once final); `acknowledged` once the user saw it. */
 {
     result: "success" | "failed";
     hash: Hex;
+    acknowledged?: true;
 }
 /** A Safe proposal's expiry before it ran is proven. */
  | {
@@ -230,13 +238,97 @@ export declare function createWriteHold(options?: {
             safe?: {
                 safeTxHash: Hex;
             };
-        } | undefined, client?: WriteHoldClient | undefined) => Promise<WriteHoldState>;
+        } | undefined, client?: WriteHoldClient | undefined) => Promise<WriteHoldState | (WriteHoldState & {
+            declined?: "refused" | "unreadable";
+        })>;
         /**
          * Every state this controller reads or makes for the call, and other
          * tabs' changes. The latest one, if any, is replayed at once.
          */
         subscribe(listener: (state: WriteHoldState) => void): () => void;
+        /**
+         * The send gate's evidence for this key: its saved success, while no
+         * record is held and the user hasn't acknowledged it. Pure, from storage.
+         */
+        unacknowledgedSuccess(skip?: (hash: Hex) => boolean): UnacknowledgedSuccess | undefined;
+        /** How `reservation` settled, if it is this key's latest and settled. */
+        settlementOf(reservation: string): WriteHoldSettled | undefined;
+        /**
+         * The user acknowledged a success the hold settled while they were
+         * away (or a view saw it settle): its saved settlement is marked
+         * acknowledged, keeping its result for every reader, so it blocks no
+         * send. Under the call's lock; nothing is sent.
+         */
+        acknowledge(settled: {
+            result: "success" | "failed";
+            hash: Hex;
+        }): Promise<WriteHoldState>;
     };
+    list: ({ account, chainId }: {
+        account: Address;
+        chainId: number;
+    }) => {
+        key: string;
+        record: ReviewedWriteRecoveryRecord;
+        handle: {
+            peek: () => WriteHoldState;
+            state(client: WriteHoldClient, checks?: {
+                effect?: (chainId: number) => Promise<boolean>;
+            }): Promise<WriteHoldState>;
+            send<T>(client: WriteHoldClient, run: (gate: WriteHoldGate) => Promise<T>): Promise<T>;
+            exit(snapshot: WriteHoldState, acknowledgement: {
+                checkedWallet: true;
+            }, client: WriteHoldClient): Promise<{
+                released: boolean;
+                state: WriteHoldState;
+            }>;
+            onReceipt: (receipt: TransactionReceipt, client: WriteHoldClient, proof?: {
+                calls: readonly ReviewedWriteRecoveryInput["call"][];
+                batch?: boolean;
+            } | undefined) => Promise<WriteHoldState>;
+            onUnproven: (client: WriteHoldClient, proposalHash?: `0x${string}` | undefined) => Promise<WriteHoldState>;
+            onExecuted: (client: WriteHoldClient, executionHash?: `0x${string}` | undefined) => Promise<WriteHoldState>;
+            attachHash: (client: WriteHoldClient, hash: `0x${string}`) => Promise<WriteHoldState>;
+            attachSafeNonce: (client: WriteHoldClient, args_1: {
+                safeTxHash: Hex;
+                nonce: number;
+            }) => Promise<WriteHoldState>;
+            adopt: (snapshot: WriteHoldState, evidence?: {
+                nonce?: number | bigint;
+                sentNonce?: number | bigint;
+                fromBlock?: bigint;
+                submittedAt?: number;
+                hash?: Hex;
+                safe?: {
+                    safeTxHash: Hex;
+                };
+            } | undefined, client?: WriteHoldClient | undefined) => Promise<WriteHoldState | (WriteHoldState & {
+                declined?: "refused" | "unreadable";
+            })>;
+            /**
+             * Every state this controller reads or makes for the call, and other
+             * tabs' changes. The latest one, if any, is replayed at once.
+             */
+            subscribe(listener: (state: WriteHoldState) => void): () => void;
+            /**
+             * The send gate's evidence for this key: its saved success, while no
+             * record is held and the user hasn't acknowledged it. Pure, from storage.
+             */
+            unacknowledgedSuccess(skip?: (hash: Hex) => boolean): UnacknowledgedSuccess | undefined;
+            /** How `reservation` settled, if it is this key's latest and settled. */
+            settlementOf(reservation: string): WriteHoldSettled | undefined;
+            /**
+             * The user acknowledged a success the hold settled while they were
+             * away (or a view saw it settle): its saved settlement is marked
+             * acknowledged, keeping its result for every reader, so it blocks no
+             * send. Under the call's lock; nothing is sent.
+             */
+            acknowledge(settled: {
+                result: "success" | "failed";
+                hash: Hex;
+            }): Promise<WriteHoldState>;
+        };
+    }[];
     /** Whether holds outlive this tab right now. */
     durable: () => boolean;
     /** The review's line while holds last only in this tab, or null. */

package/dist/esm/review/writeHold.d.ts.map

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

package/dist/esm/review/writeHold.js

@@ -1,7 +1,7 @@
 import { isAddress, toEventSelector, } from "viem";
 import { canonicalSafeTxHash, lookAtSafeProposalEnd, provenSafeProposalEnd, readSafeTransaction, SAFE_PROPOSAL_AWAITING, safeTransactionMessage, } from "../safeService.js";
 import { SAFE_PROPOSAL_EXECUTED_LINE, WRITE_HOLD_HASHED_EXIT_LINE, WRITE_HOLD_IN_TAB_LINE, WRITE_HOLD_LOOKS_DONE_LINE, WRITE_HOLD_MINED_LINE, WRITE_HOLD_NONCE_LINE, WRITE_HOLD_PENDING_LINE, WRITE_HOLD_UNCHECKED_LINE, WRITE_HOLD_REVERTED_LINE, WRITE_HOLD_SAFE_REPLACED_LINE, WRITE_HOLD_SAFE_UNPROVEN_LINE, WRITE_HOLD_STALE_REVIEW_LINE, writeHeldMessage, } from "./messages.js";
-import { createBrowserWriteRecovery, createHeldWriteStorage, findReviewedWrites, heldSafeProposal, findTransactionAtNonce, readReviewedWriteNonce, safeProposalIsHeldCall, SubmittedWritePersistenceError, verifyReviewedWriteExpiry, verifyReviewedWriteReceipt, } from "./writeRecovery.js";
+import { createBrowserWriteRecovery, createHeldWriteStorage, findReviewedWrites, heldSafeProposal, findTransactionAtNonce, listReviewedWrites, readReviewedWriteNonce, safeProposalIsHeldCall, SubmittedWritePersistenceError, verifyReviewedWriteExpiry, verifyReviewedWriteReceipt, } from "./writeRecovery.js";
 import { isBytes32 } from "../untrusted.js";
 import { atCanonicalFinalizedBlock } from "./relayr.js";
 import { TAB, tabShared } from "./tabState.js";
@@ -74,8 +74,10 @@ const UNSEEN_HASH_MS = 30 * 60_000;
 /** The longest one request to Safe's service may take inside the hold. */
 const SAFE_SERVICE_READ_MS = 8_000;
 /** The 30 minutes have passed since the wallet returned the hash, or since it was first read. A clock that couldn't be saved (NaN) never runs out. */
-function unseenTooLong(record) {
-    return (Date.now() - Number(record.submittedAt ?? record.firstSeenAt) >=
+function unseenTooLong(record, 
+/** A later authenticated sighting, when there is one: the clock runs from it. */
+seen) {
+    return (Date.now() - Number(seen ?? record.submittedAt ?? record.firstSeenAt) >=
         UNSEEN_HASH_MS);
 }
 /** Whether a canonical finalized block shows the account's nonce still at or below the sent nonce; false when it can't say. */
@@ -380,10 +382,14 @@ export function createWriteHold(options = {}) {
          * exactly this call. One that can't be read is unknown, not refused.
          */
         async function adoptable(hash, client) {
-            if (!isBytes32(hash) ||
-                !client ||
-                (await client.getChainId().catch(() => null)) !== call.chainId)
-                return false;
+            if (!isBytes32(hash))
+                return "refused";
+            if (!client)
+                return "unreadable";
+            const chainId = await client.getChainId().catch(() => null);
+            // A client on another chain can't check this chain's transaction.
+            if (chainId !== call.chainId)
+                return "unreadable";
             const reviewed = {
                 account: call.account.toLowerCase(),
                 chainId: call.chainId,
@@ -393,22 +399,35 @@ export function createWriteHold(options = {}) {
                     value: String(call.call.value ?? 0),
                 },
             };
+            // One the chain or the service can't show is this call's, held.
             if (call.safe) {
                 const proposal = await readSafeTransaction(call.chainId, call.account, hash, service).catch(() => null);
-                return !proposal || safeProposalIsHeldCall(proposal, call);
+                return !proposal || safeProposalIsHeldCall(proposal, call)
+                    ? "yes"
+                    : "refused";
             }
             const sent = await client.getTransaction({ hash }).catch(() => null);
-            return !sent || sentIsCall(sent, hash, reviewed);
+            return !sent || sentIsCall(sent, hash, reviewed) ? "yes" : "refused";
         }
-        /** The authenticated nonce of a Safe proposal, from Safe's service. */
-        async function proposalNonceOf(record) {
-            try {
-                const proposal = await readSafeTransaction(record.chainId, record.account, record.hash, service);
-                return safeTransactionMessage(proposal).nonce;
-            }
-            catch {
-                return null;
-            }
+        /**
+         * Safe's authenticated record of the held proposal, or null while the
+         * service can't return it (down, or it has none).
+         */
+        async function proposalOf(record) {
+            return readSafeTransaction(record.chainId, record.account, record.hash, service).catch(() => null);
+        }
+        /**
+         * A Safe write unseen too long: not proven run, not ended unproven (that
+         * has its own exit), and not listed unexecuted by the service for 30
+         * minutes since it was sent, adopted, or last listed.
+         */
+        function unboundedSafe(record) {
+            return (record.safe &&
+                !!record.hash &&
+                !record.executed &&
+                !record.unproven &&
+                !record.replaced &&
+                unseenTooLong(record, record.pendingSeenAt));
         }
         /** Follow a saved execution's receipt; null while the node has none. */
         async function execution(record, client) {
@@ -607,13 +626,18 @@ export function createWriteHold(options = {}) {
                     return settled ?? ranExecuted(record);
                 }
             }
-            // The chain's proof, from the proposal's nonce: Safe's service is asked
-            // only for the nonce, once, and for an expiry.
-            if (record.safeNonce === undefined) {
-                const nonce = await proposalNonceOf(record);
-                if (nonce !== null)
-                    record = recovery.proposalNonce(record, nonce);
-            }
+            // The chain's proof, from the proposal's nonce, saved once. Only the
+            // service returning this proposal unexecuted shows it truly pending:
+            // that read restarts its unseen clock. A Safe nonce still waiting shows
+            // only that nothing ran there.
+            const proposal = await proposalOf(record);
+            const listed = !!proposal && proposal.isExecuted !== true;
+            if (proposal && record.safeNonce === undefined)
+                record = recovery.proposalNonce(record, safeTransactionMessage(proposal).nonce);
+            // Listed: truly pending, an unproven end included. The fresh record
+            // carries the new stamp, so the checked answer below removes any exit.
+            if (listed)
+                record = recovery.listedAgain(record);
             const end = (record.safeNonce !== undefined &&
                 (await provenSafeProposalEnd(client, record.account, hash, BigInt(record.safeNonce)))) ||
                 (await lookAtSafeProposalEnd(client, record.chainId, record.account, hash, service));
@@ -649,10 +673,9 @@ export function createWriteHold(options = {}) {
                     return clear(settled, record.id);
                 }
             }
-            if (!record.executed &&
-                !record.unproven &&
-                record.safeNonce === undefined &&
-                unseenTooLong(record))
+            // Its wait is bounded like any unchecked write, the clock restarted by
+            // each listing (an unproven end has its own exit).
+            if (unboundedSafe(record))
                 return unchecked(record);
             if (record.executed)
                 follow(client, record.id);
@@ -690,9 +713,13 @@ export function createWriteHold(options = {}) {
             // A mirror carries no evidence of its own: its source attempt does.
             if (record.mirrorOf)
                 return classify(record);
-            // No evidence from another chain.
-            if ((await client.getChainId().catch(() => null)) !== record.chainId)
-                return classify(record);
+            // No evidence from another chain. Unreadable chain identity still
+            // bounds a Safe write's unchecked wait.
+            const chainId = await client.getChainId().catch(() => null);
+            if (chainId !== record.chainId)
+                return chainId === null && unboundedSafe(record)
+                    ? unchecked(record)
+                    : classify(record);
             if (record.safe)
                 return safeState(record, client);
             const check = await recovery
@@ -1037,10 +1064,13 @@ export function createWriteHold(options = {}) {
                 if (hooks.across) {
                     // Under an intent: the same atomic reserve as a send, under every
                     // legacy key's lock, mirrored at each so older versions see it.
-                    if (!free() ||
-                        (hash !== undefined && !(await adoptable(hash, client))))
+                    if (!free())
                         return shown(peek());
+                    const verdict = hash === undefined ? "yes" : await adoptable(hash, client);
+                    if (verdict !== "yes")
+                        return { ...shown(peek()), declined: verdict };
                     let adopted = false;
+                    let busy = false;
                     try {
                         const { released } = await hooks.across((work) => recovery.withLock(work), () => {
                             if (!free())
@@ -1050,21 +1080,34 @@ export function createWriteHold(options = {}) {
                         }, recovery.rejected, Promise.resolve(), hooks.generations());
                         await released;
                     }
-                    catch {
-                        /* Held elsewhere, busy, or no longer free: nothing adopted. */
+                    catch (error) {
+                        // Held elsewhere or no longer free: what the hold shows. Busy: unread.
+                        busy = error instanceof WriteHoldBusyError;
                     }
                     // A mined hash settles on its verified receipt, through the gate.
-                    return adopted && hash && client ? state(client) : shown(peek());
+                    if (adopted && hash && client)
+                        return state(client);
+                    const now = shown(peek());
+                    return busy && now.status === "clear"
+                        ? { ...now, declined: "unreadable" }
+                        : now;
                 }
                 const result = await locked(async () => {
                     if (!free())
                         return peek();
-                    if (hash !== undefined && !(await adoptable(hash, client)))
-                        return peek();
+                    const verdict = hash === undefined ? "yes" : await adoptable(hash, client);
+                    if (verdict !== "yes")
+                        return { ...peek(), declined: verdict };
                     reserve();
                     return hash && client ? inspect(client) : peek();
                 }, true);
-                return shown(result?.value ?? peek());
+                if (!result)
+                    return { ...shown(peek()), declined: "unreadable" };
+                const { declined, ...answer } = result.value;
+                return {
+                    ...shown(answer),
+                    ...(declined ? { declined } : {}),
+                };
             },
             /**
              * Save the Safe nonce of a held Safe proposal adopted before it was
@@ -1091,6 +1134,46 @@ export function createWriteHold(options = {}) {
                 }, true);
                 return shown(result?.value ?? peek());
             },
+            /**
+             * The send gate's evidence for this key: its saved success, while no
+             * record is held and the user hasn't acknowledged it. Pure, from storage.
+             */
+            unacknowledgedSuccess(
+            /** A success to look past (one a view already told, its acknowledgement under way). */
+            skip) {
+                if (recovery.read())
+                    return undefined;
+                const settled = recovery.settled();
+                return settled?.result === "success" &&
+                    !settled.acknowledged &&
+                    !skip?.(settled.hash)
+                    ? {
+                        result: "success",
+                        hash: settled.hash,
+                        reservation: recovery.latestReservation(),
+                    }
+                    : undefined;
+            },
+            /** How `reservation` settled, if it is this key's latest and settled. */
+            settlementOf(reservation) {
+                const now = peek();
+                return now.status === "clear" && now.reservation === reservation
+                    ? now.settled
+                    : undefined;
+            },
+            /**
+             * The user acknowledged a success the hold settled while they were
+             * away (or a view saw it settle): its saved settlement is marked
+             * acknowledged, keeping its result for every reader, so it blocks no
+             * send. Under the call's lock; nothing is sent.
+             */
+            async acknowledge(settled) {
+                const result = await locked(async () => {
+                    recovery.acknowledgeSettled(settled);
+                    return peek();
+                }, true);
+                return shown(result?.value ?? peek());
+            },
             async attachHash(client, hash) {
                 const result = await locked(async () => {
                     const record = recovery.read();
@@ -1253,10 +1336,20 @@ export function createWriteHold(options = {}) {
                 ? [{ input: { ...exact, call: source.call } }]
                 : []));
         rescan();
+        /** The legacy hold this intent last stood for, with its reservation. */
+        let routed;
         /** A legacy key holding anything but this intent's own mirror. */
         const foreign = (index) => holds(journals[index]) && delegates[index].peek().status !== "clear";
         /** The legacy hold the intent stands for right now, from storage alone. */
-        const active = () => delegates.find((_, index) => foreign(index));
+        const active = () => {
+            const index = delegates.findIndex((_, at) => foreign(at));
+            if (index < 0)
+                return undefined;
+            const now = delegates[index].peek();
+            if (now.status !== "clear")
+                routed = { handle: delegates[index], reservation: now.record.id };
+            return delegates[index];
+        };
         /** The first legacy key holding an unresolved write, through its own gate. */
         async function delegated(client) {
             rescan();
@@ -1264,11 +1357,83 @@ export function createWriteHold(options = {}) {
                 if (!foreign(index))
                     continue;
                 const state = await handle.state(client);
-                if (state.status !== "clear")
+                if (state.status !== "clear") {
+                    routed = { handle, reservation: state.record.id };
                     return state;
+                }
             }
             return null;
         }
+        /**
+         * How a legacy hold this intent stood for ended, while the intent itself
+         * never reserved: its settlement (acknowledged or not) is the intent's,
+         * so a view that saw it held shows its result, and an unacknowledged
+         * success still blocks a fresh one.
+         */
+        /**
+         * Every legacy settlement that may be the intent's: the reservation it
+         * was seen standing for (first), and any reserved after (or not provably
+         * before) its own latest reservation. Times that can't be compared count
+         * as newer: a false block is the safe side.
+         */
+        function eligibleLegacy() {
+            const eligible = [];
+            if (routed) {
+                const now = routed.handle.peek();
+                if (now.status === "clear" &&
+                    now.settled &&
+                    now.reservation === routed.reservation)
+                    eligible.push({ handle: routed.handle, state: now });
+            }
+            const ownReserved = ownJournal.latestReservation() !== undefined;
+            const ownAt = ownJournal.latestReservedAt();
+            for (const [index, handle] of delegates.entries()) {
+                if (eligible.some((entry) => entry.handle === handle))
+                    continue;
+                const now = handle.peek();
+                if (now.status !== "clear" || !now.settled)
+                    continue;
+                const legacyAt = journals[index].latestReservedAt() ?? journals[index].settledAt();
+                if (!ownReserved ||
+                    ownAt === undefined ||
+                    legacyAt === undefined ||
+                    // The same moment is no proof of order: counted as newer.
+                    legacyAt >= ownAt)
+                    eligible.push({ handle, state: now });
+            }
+            return eligible;
+        }
+        /**
+         * What the intent shows of its legacy holds: the settlement of the one
+         * it was seen standing for (so it is delivered), else an unacknowledged
+         * success, else any eligible one. Blocking is the send gate's
+         * (unacknowledgedSuccess), never this choice.
+         */
+        function legacySettled() {
+            const eligible = eligibleLegacy();
+            return (eligible.find(({ handle, state }) => handle === routed?.handle &&
+                state.reservation === routed.reservation) ??
+                eligible.find(({ state }) => state.settled.result === "success" &&
+                    !("acknowledged" in state.settled && state.settled.acknowledged)) ??
+                eligible[0]);
+        }
+        /**
+         * `state`, or, when it is a clear, the legacy settlement that owns the
+         * intent's result instead: the one it was seen standing for, or one
+         * reserved after its own latest reservation, whatever the intent's own
+         * (older) settlement says. One choice for reads, events and the guard.
+         */
+        function withLegacy(state) {
+            if (state.status !== "clear")
+                return state;
+            const legacy = legacySettled();
+            return legacy
+                ? {
+                    ...legacy.state,
+                    ...(state.checked === undefined ? {} : { checked: state.checked }),
+                }
+                : state;
+        }
         /**
          * The final check and reservation, under every legacy key's lock taken
          * in one sorted order (the intent's own is held by its send), each
@@ -1395,9 +1560,64 @@ export function createWriteHold(options = {}) {
         };
         return {
             ...own,
-            peek: () => active()?.peek() ?? own.peek(),
+            peek: () => active()?.peek() ?? withLegacy(own.peek()),
+            /**
+             * The intent's events, through the same owner as its state(): while a
+             * legacy hold stands for it, its own empty clear is that hold's state
+             * (or its settlement), never a release.
+             */
+            subscribe: (listener) => own.subscribe((state) => listener(state.status === "clear"
+                ? (active()?.peek() ?? withLegacy(state))
+                : state)),
             async state(client, checks) {
-                return ((await delegated(client)) ?? after(await own.state(client, checks)));
+                return ((await delegated(client)) ??
+                    withLegacy(await after(await own.state(client, checks))));
+            },
+            /**
+             * The send gate: any unacknowledged success, the intent's own or an
+             * eligible legacy hold's. Pure, from storage, whatever a view shows.
+             */
+            unacknowledgedSuccess(skip) {
+                // Every eligible success is considered: one looked past never hides
+                // another.
+                const mine = own.unacknowledgedSuccess(skip);
+                if (mine)
+                    return mine;
+                for (const { state } of eligibleLegacy()) {
+                    const settled = state.settled;
+                    if (settled.result === "success" &&
+                        "hash" in settled &&
+                        !settled.acknowledged &&
+                        !skip?.(settled.hash))
+                        return {
+                            result: "success",
+                            hash: settled.hash,
+                            reservation: state.reservation,
+                        };
+                }
+                return undefined;
+            },
+            /**
+             * How a reservation this intent stood for settled, on its own key or a
+             * legacy one, whichever hold is shown now.
+             */
+            settlementOf(reservation) {
+                for (const handle of [own, ...delegates]) {
+                    const settled = handle.settlementOf(reservation);
+                    if (settled)
+                        return settled;
+                }
+                return undefined;
+            },
+            /** A settlement is acknowledged where it was saved, found by its hash. */
+            async acknowledge(settled) {
+                const hash = settled.hash.toLowerCase();
+                const legacy = eligibleLegacy().find(({ state }) => state.settled !== undefined &&
+                    "hash" in state.settled &&
+                    state.settled.hash === hash);
+                return legacy
+                    ? withLegacy(await legacy.handle.acknowledge(settled))
+                    : own.acknowledge(settled);
             },
             async send(client, run) {
                 const held = await delegated(client);
@@ -1513,8 +1733,29 @@ export function createWriteHold(options = {}) {
             adopt: async (...args) => route()?.peek() ?? own.adopt(...args),
         };
     }
+    /**
+     * Every write held for `account` on `chainId`, with a handle to each at
+     * the key it was saved under: for an app-wide notice of everything held,
+     * whatever action made it. Read from storage alone; each handle's state()
+     * is the gated answer.
+     */
+    function list({ account, chainId }) {
+        return listReviewedWrites({ account, chainId }, { storage }).map(({ key, record }) => {
+            const input = {
+                chainId: record.chainId,
+                account: record.account,
+                safe: record.safe,
+                call: record.call,
+            };
+            const handle = record.namespace === undefined
+                ? openExact(input, key)
+                : open({ ...input, namespace: record.namespace });
+            return { key, record, handle };
+        });
+    }
     return {
         open,
+        list,
         /** Whether holds outlive this tab right now. */
         durable: () => storage.durable(),
         /** The review's line while holds last only in this tab, or null. */