@bananapus/nana-sdk-core 2.28.0 → 2.30.0

package/dist/esm/review/writeRecovery.js

@@ -1,7 +1,7 @@
-import { isAddress, } from "viem";
+import { isAddress, keccak256, } from "viem";
 import { lookAtSafeProposal, readSafeAppExecution, readSafeTransaction, safeTransactionMatchesCall, } from "../safeService.js";
 import { isBytes32, isHexBytes, uint256 } from "../untrusted.js";
-import { atCanonicalFinalizedBlock } from "./relayr.js";
+import { atCanonicalFinalizedBlock, } from "./relayr.js";
 // A returned hash must survive a component remount even when its durable update
 // failed. It is visible only while the exact durable reservation still exists.
 const unpersistedSubmissions = new WeakMap();
@@ -14,20 +14,28 @@ export class SubmittedWritePersistenceError extends Error {
         Object.defineProperty(this, "cause", { value: cause, configurable: true });
     }
 }
-function normalized(input) {
-    const value = uint256(input?.call?.value ?? 0n);
+function normalizedIdentity(input) {
     if (!Number.isSafeInteger(input?.chainId) ||
         input.chainId <= 0 ||
-        !isAddress(input?.account, { strict: false }) ||
-        typeof input?.safe !== "boolean" ||
+        !isAddress(input?.account, { strict: false }))
+        throw new Error("Invalid reviewed write recovery evidence.");
+    return {
+        chainId: input.chainId,
+        account: input.account.toLowerCase(),
+    };
+}
+function normalized(input) {
+    const value = uint256(input?.call?.value ?? 0n);
+    const namespace = namespaceOf(input?.namespace);
+    if (typeof input?.safe !== "boolean" ||
         !isAddress(input?.call?.to, { strict: false }) ||
         !isHexBytes(input?.call?.data) ||
         value === null)
         throw new Error("Invalid reviewed write recovery evidence.");
     return {
-        chainId: input.chainId,
-        account: input.account.toLowerCase(),
+        ...normalizedIdentity(input),
         safe: input.safe,
+        ...(namespace === undefined ? {} : { namespace }),
         call: {
             to: input.call.to.toLowerCase(),
             data: input.call.data.toLowerCase(),
@@ -42,7 +50,10 @@ function recordOf(value) {
         !record.id ||
         typeof record.call?.value !== "string" ||
         !/^(0|[1-9]\d*)$/.test(record.call.value) ||
-        (record.hash !== undefined && !isBytes32(record.hash)))
+        (record.hash !== undefined && !isBytes32(record.hash)) ||
+        !optionalDecimal(record.nonce) ||
+        !optionalDecimal(record.fromBlock) ||
+        !optionalDecimal(record.sentNonce))
         throw new Error("Invalid saved write recovery record. Keep this action pending.");
     return {
         version: 1,
@@ -51,44 +62,284 @@ function recordOf(value) {
         ...(record.hash === undefined
             ? {}
             : { hash: record.hash.toLowerCase() }),
+        ...(record.nonce === undefined ? {} : { nonce: record.nonce }),
+        ...(record.fromBlock === undefined ? {} : { fromBlock: record.fromBlock }),
+        ...(record.sentNonce === undefined ? {} : { sentNonce: record.sentNonce }),
     };
 }
+function optionalDecimal(value) {
+    return (value === undefined ||
+        (typeof value === "string" && /^(0|[1-9]\d*)$/.test(value)));
+}
 /** Validate an existing domain journal's recovered record with the shared storage rules. */
 export { recordOf as parseReviewedWriteRecoveryRecord };
-/** Amounts and quote changes must not evade an unresolved action. */
-function scope(input) {
+/**
+ * An ordinary write holds only its exact call: a changed amount or quote is a
+ * different call. A namespace holds a whole action instead.
+ */
+function callScope(input) {
+    return `nana-sdk:reviewed-write:v2:${input.chainId}:${input.account}:${input.call.to}:${input.call.value ?? 0}:${keccak256(input.call.data)}`;
+}
+/** Before 2.30, an ordinary write held its target and selector. Read only, for its exact call. */
+function legacyScope(input) {
     return `nana-sdk:reviewed-write:v1:${input.chainId}:${input.account}:${input.call.to}:${input.call.data.slice(0, 10)}`;
 }
+function namespaceOf(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string" ||
+        !/^[a-z0-9][a-z0-9:._/-]{0,127}$/.test(value))
+        throw new Error("Invalid write recovery namespace.");
+    return value;
+}
+function namespaceScope(input) {
+    return `nana-sdk:reviewed-write:v1:namespace:${input.chainId}:${input.account}:${input.namespace}`;
+}
+function scope(input) {
+    return input.namespace === undefined
+        ? callScope(input)
+        : namespaceScope({ ...input, namespace: input.namespace });
+}
+function recoveryStorage(store) {
+    const result = store ?? globalThis.localStorage;
+    if (!result)
+        throw new Error("Write recovery storage is unavailable.");
+    return result;
+}
+/**
+ * Open the original namespaced action before fresh quotation or phase checks.
+ * No call is invented to locate evidence. Legacy actions retain factory.read().
+ * A namespace must stay stable across amount, target and quote changes.
+ */
+export function readBrowserWriteRecovery(input, options = {}) {
+    const identity = normalizedIdentity(input);
+    const namespace = namespaceOf(input?.namespace);
+    if (namespace === undefined)
+        throw new Error("Provide a write recovery namespace.");
+    return readRecovery(recoveryStorage(options.storage), namespaceScope({ ...identity, namespace }));
+}
+/**
+ * The key that marks the record `id` saved at `key` as released by the user.
+ * An exit writes this instead of removing `key`, so it can never remove a
+ * newer record another tab saved there.
+ */
+function releasedKey(key, id) {
+    return `${key}:released:${id}`;
+}
+function readStored(raw, key, scopeOf = scope, store) {
+    if (raw === null)
+        return null;
+    const record = recordOf(JSON.parse(raw));
+    if (scopeOf(record) !== key)
+        throw new Error("Saved write recovery scope does not match.");
+    if (store && store.getItem(releasedKey(key, record.id)) !== null)
+        return null;
+    return record;
+}
+function readRecovery(store, key, raw = store.getItem(key), scopeOf = scope) {
+    const record = readStored(raw, key, scopeOf, store);
+    const memory = unpersistedSubmissions.get(store)?.get(key);
+    if (!record ||
+        !memory ||
+        JSON.stringify({ ...record, hash: undefined }) !==
+            JSON.stringify({ ...memory, hash: undefined }) ||
+        (record.hash && record.hash !== memory.hash)) {
+        // A readable durable snapshot also proves whether cached evidence is stale.
+        unpersistedSubmissions.get(store)?.delete(key);
+        return record;
+    }
+    if (record.hash)
+        unpersistedSubmissions.get(store)?.delete(key);
+    return recordOf(memory);
+}
 /** Exact reviewed evidence, independent of the reservation and submission identities. */
 export function sameReviewedWrite(record, input) {
     return (JSON.stringify(normalized(record)) === JSON.stringify(normalized(input)));
 }
+// Without Web Locks, writes in this tab still run one at a time per action.
+const tabQueues = new Map();
+let tabLocksNoted = false;
+const tabLocks = {
+    async request(name, options, work) {
+        const held = tabQueues.get(name);
+        if (held && options.ifAvailable)
+            return work(null);
+        let release;
+        const mine = new Promise((resolve) => (release = resolve));
+        const queue = (held ?? Promise.resolve()).then(() => mine);
+        tabQueues.set(name, queue);
+        await held;
+        try {
+            return await work({ name, mode: "exclusive" });
+        }
+        finally {
+            release();
+            if (tabQueues.get(name) === queue)
+                tabQueues.delete(name);
+        }
+    },
+};
+// Without Web Locks, tabs share an IndexedDB lease per action. A readwrite
+// transaction is atomic across the origin's tabs, so claiming a lease is a
+// compare-and-set. The holder renews it while it works; a tab that closed or
+// froze loses it once it lapses.
+const LEASE_DB = "nana-sdk-write-locks";
+const LEASE_STORE = "leases";
+const LEASE_MS = 15_000;
+const LEASE_RENEW_MS = 5_000;
+const LEASE_POLL_MS = 50;
+function leaseTransaction(db, run) {
+    return new Promise((resolve, reject) => {
+        const transaction = db.transaction(LEASE_STORE, "readwrite");
+        let result;
+        run(transaction.objectStore(LEASE_STORE), (value) => (result = value));
+        transaction.oncomplete = () => resolve(result);
+        transaction.onerror = transaction.onabort = () => reject(transaction.error);
+    });
+}
+/** Take or renew `name`'s lease for `owner`; false while another tab holds it. */
+function claimLease(db, name, owner) {
+    return leaseTransaction(db, (store, done) => {
+        done(false);
+        const read = store.get(name);
+        read.onsuccess = () => {
+            const lease = read.result;
+            const now = Date.now();
+            if (lease && lease.owner !== owner && lease.expires > now)
+                return;
+            store.put({ owner, expires: now + LEASE_MS }, name);
+            done(true);
+        };
+    });
+}
+function dropLease(db, name, owner) {
+    return leaseTransaction(db, (store) => {
+        const read = store.get(name);
+        read.onsuccess = () => {
+            if (read.result?.owner === owner)
+                store.delete(name);
+        };
+    });
+}
+function leaseLocks(factory) {
+    let opened;
+    const database = () => (opened ??= new Promise((resolve, reject) => {
+        const request = factory.open(LEASE_DB, 1);
+        request.onupgradeneeded = () => request.result.createObjectStore(LEASE_STORE);
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => reject(request.error);
+    }).catch((error) => {
+        opened = undefined;
+        throw error;
+    }));
+    return {
+        request: (name, options, work) => tabLocks.request(name, options, async (tabLock) => {
+            if (!tabLock)
+                return work(null);
+            let db;
+            try {
+                db = await database();
+            }
+            catch {
+                // IndexedDB refused (as in some private windows): this tab only.
+                return work(tabLock);
+            }
+            const owner = globalThis.crypto.randomUUID();
+            while (!(await claimLease(db, name, owner))) {
+                if (options.ifAvailable)
+                    return work(null);
+                await new Promise((resolve) => setTimeout(resolve, LEASE_POLL_MS));
+            }
+            const renew = setInterval(() => void claimLease(db, name, owner).catch(() => { }), LEASE_RENEW_MS);
+            try {
+                return await work(tabLock);
+            }
+            finally {
+                clearInterval(renew);
+                await dropLease(db, name, owner).catch(() => { });
+            }
+        }),
+    };
+}
+let fallbackLocks;
 /**
- * One ordinary-write reservation per account/chain/target/selector. Use the
- * existing domain journal instead when an action already has one. There is no
- * expiry or nonce-based release: an unknown broadcast remains unknown.
+ * The browser's Web Locks. Where a browser or wallet webview has none, an
+ * IndexedDB lease shared by the origin's tabs (one transaction, no visible
+ * delay; it waits only while another tab holds the action), with a one-time
+ * console note. With neither, a lock within this tab. Never refuses.
+ */
+export function browserLocks() {
+    const native = globalThis.navigator?.locks;
+    if (native)
+        return native;
+    if (!tabLocksNoted) {
+        tabLocksNoted = true;
+        console.info(globalThis.indexedDB
+            ? "Web Locks are unavailable, so wallet writes are coordinated across tabs through IndexedDB."
+            : "Web Locks are unavailable, so wallet writes are coordinated within this tab only.");
+    }
+    if (!globalThis.indexedDB)
+        return tabLocks;
+    return (fallbackLocks ??= leaseLocks(globalThis.indexedDB));
+}
+/**
+ * One ordinary-write reservation per exact call (account, chain, target,
+ * value and calldata) by default, or per account/chain/explicit stable
+ * namespace when provided. Use the existing domain journal instead when an
+ * action already has one. A hold ends on proof ({@link checkReviewedWrite} via
+ * `resolve`) or when the user confirms they checked their wallet (`abandon`).
  *
  * Every mutation must run inside withLock, including receipt-based clearing.
- * Storage and native cross-tab exclusion are mandatory before opening a wallet.
+ * Storage is mandatory before opening a wallet; without Web Locks the lock
+ * is an IndexedDB lease across tabs ({@link browserLocks}).
  */
 export function createBrowserWriteRecovery(input, options = {}) {
     const reviewed = normalized(input);
     const key = scope(reviewed);
+    const legacyKey = reviewed.namespace === undefined ? legacyScope(reviewed) : undefined;
     let owned;
     let locked = false;
     let lastStorage;
+    /** An adopted call (a reused Safe proposal) is kept under its reviewed call's key. */
+    function keyOf(record) {
+        return record.namespace === undefined &&
+            legacyKey !== undefined &&
+            legacyScope(record) === legacyKey
+            ? key
+            : scope(record);
+    }
+    /**
+     * Where this call's record lives, with its raw value: its own key, or an
+     * exact match saved under the old key. Reads its own key exactly once.
+     */
+    function locate(store) {
+        const raw = store.getItem(key);
+        if (raw !== null || !legacyKey)
+            return { at: key, raw };
+        try {
+            const old = store.getItem(legacyKey);
+            const legacy = readStored(old, legacyKey, legacyScope, store);
+            if (legacy && sameReviewedWrite(legacy, reviewed))
+                return { at: legacyKey, raw: old };
+        }
+        catch {
+            // An unreadable old record names no call, so it holds none.
+        }
+        return { at: key, raw };
+    }
+    function scopeAt(at) {
+        return at === key ? keyOf : legacyScope;
+    }
     function storage() {
-        const store = options.storage ?? globalThis.localStorage;
-        if (!store)
-            throw new Error("Write recovery storage is unavailable.");
+        const store = recoveryStorage(options.storage);
         lastStorage = store;
         return store;
     }
-    function rememberSubmission(record, verifiedReservation = false) {
+    function rememberSubmission(record, at, verifiedReservation = false) {
         if (!lastStorage)
             return;
         let pending = unpersistedSubmissions.get(lastStorage);
-        const previous = pending?.get(key);
+        const previous = pending?.get(at);
         // An unreadable stale callback cannot replace another attempt's only hash.
         if (previous &&
             !verifiedReservation &&
@@ -96,59 +347,44 @@ export function createBrowserWriteRecovery(input, options = {}) {
             return;
         if (!pending)
             unpersistedSubmissions.set(lastStorage, (pending = new Map()));
-        pending.set(key, recordOf(record));
+        pending.set(at, recordOf(record));
     }
     function requireLock() {
         if (!locked)
             throw new Error("Write recovery changes require the browser lock.");
     }
-    function readStored(raw) {
-        if (raw === null)
-            return null;
-        const record = recordOf(JSON.parse(raw));
-        if (scope(record) !== key)
-            throw new Error("Saved write recovery scope does not match.");
-        return record;
-    }
     function read() {
         const store = storage();
-        const record = readStored(store.getItem(key));
-        const memory = unpersistedSubmissions.get(store)?.get(key);
-        if (!record ||
-            !memory ||
-            JSON.stringify({ ...record, hash: undefined }) !==
-                JSON.stringify({ ...memory, hash: undefined }) ||
-            (record.hash && record.hash !== memory.hash)) {
-            // A readable durable snapshot also proves whether cached evidence is stale.
-            unpersistedSubmissions.get(store)?.delete(key);
-            return record;
-        }
-        if (record.hash)
-            unpersistedSubmissions.get(store)?.delete(key);
-        return recordOf(memory);
+        const { at, raw } = locate(store);
+        return readRecovery(store, at, raw, scopeAt(at));
     }
-    function persist(record) {
+    function persist(record, at) {
         const raw = JSON.stringify(record);
         const store = storage();
-        store.setItem(key, raw);
-        if (store.getItem(key) !== raw)
+        store.setItem(at, raw);
+        if (store.getItem(at) !== raw)
             throw new Error("Write recovery storage did not retain the action.");
     }
     function clear(expected) {
         requireLock();
+        release(expected);
+    }
+    /** Remove exactly `expected`, refusing any other saved record. */
+    function release(expected) {
         // A volatile returned hash is useful for tracking, but is not a successful
         // durable commit. submitted(hash, record) must retry that commit first.
-        const current = readStored(storage().getItem(key));
+        const store = storage();
+        const { at, raw } = locate(store);
+        const current = readStored(raw, at, scopeAt(at), store);
         if (!current)
             return;
         if (JSON.stringify(current) !== JSON.stringify(recordOf(expected))) {
             throw new Error("Write recovery changed. Keep the current action pending.");
         }
-        const store = storage();
-        store.removeItem(key);
-        if (store.getItem(key) !== null)
+        store.removeItem(at);
+        if (store.getItem(at) !== null)
             throw new Error("Write recovery storage did not clear the action.");
-        unpersistedSubmissions.get(store)?.delete(key);
+        unpersistedSubmissions.get(store)?.delete(at);
     }
     function rejected() {
         requireLock();
@@ -161,27 +397,113 @@ export function createBrowserWriteRecovery(input, options = {}) {
         clear(owned);
         owned = undefined;
     }
+    /**
+     * Save the nonce the chain showed for the saved hash. It is extra evidence:
+     * a failed save keeps the record as it was.
+     */
+    function bind(saved, sentNonce) {
+        const bound = recordOf({ ...saved, sentNonce });
+        try {
+            const store = storage();
+            const { at, raw } = locate(store);
+            const current = readStored(raw, at, scopeAt(at));
+            if (JSON.stringify(current) !== JSON.stringify(recordOf(saved)))
+                return saved;
+            persist(bound, at);
+            return bound;
+        }
+        catch {
+            return saved;
+        }
+    }
+    /** `replace`: the exact call was found at its nonce under another hash, as after a wallet speed-up. */
+    function record(hash, expected, replace) {
+        requireLock();
+        if (!isBytes32(hash))
+            throw new Error("The wallet returned an invalid transaction identity.");
+        const previous = expected && recordOf(expected);
+        const submittedHash = hash.toLowerCase();
+        if (!previous ||
+            keyOf(previous) !== key ||
+            (!replace && previous.hash && previous.hash !== submittedHash)) {
+            throw new Error("Write recovery changed before submission was recorded.");
+        }
+        const submitted = { ...previous, hash: submittedHash };
+        let raw;
+        let at = key;
+        try {
+            ({ at, raw } = locate(storage()));
+        }
+        catch (cause) {
+            owned = submitted;
+            rememberSubmission(submitted, at);
+            throw new SubmittedWritePersistenceError(submitted, cause);
+        }
+        // A record the user released keeps its marker: a late hash leaves it released.
+        const current = readStored(raw, at, scopeAt(at));
+        if (!current ||
+            JSON.stringify({ ...current, hash: undefined }) !==
+                JSON.stringify({ ...previous, hash: undefined }) ||
+            (!replace && current.hash && current.hash !== submittedHash)) {
+            throw new Error("Write recovery changed before submission was recorded.");
+        }
+        owned = recordOf(submitted);
+        if (current.hash !== submittedHash) {
+            try {
+                persist(submitted, at);
+            }
+            catch (cause) {
+                rememberSubmission(submitted, at, true);
+                throw new SubmittedWritePersistenceError(submitted, cause);
+            }
+        }
+        if (lastStorage)
+            unpersistedSubmissions.get(lastStorage)?.delete(at);
+        return submitted;
+    }
     return {
         read,
-        reserve(actualCall) {
+        /**
+         * Save the attempt before the wallet opens. `evidence`, the account's next
+         * nonce from {@link readReviewedWriteNonce}, lets `resolve` release it
+         * on proof from the chain.
+         */
+        reserve(actualCall, evidence) {
             requireLock();
             // A reused Safe proposal may have a different, already verified deadline.
             // Retain its actual call, without widening the unresolved-action scope.
             const actual = actualCall
                 ? normalized({ ...reviewed, call: actualCall })
                 : reviewed;
-            if (scope(actual) !== key)
+            if (legacyScope(actual) !== legacyScope(reviewed))
                 throw new Error("The adopted write has a different recovery scope.");
-            if (read())
+            const nonce = evidence && uint256(evidence.nonce);
+            const fromBlock = evidence && uint256(evidence.blockNumber);
+            if (evidence && (nonce === null || fromBlock === null))
+                throw new Error("Invalid write recovery nonce evidence.");
+            const store = storage();
+            const { at, raw } = locate(store);
+            if (readRecovery(store, at, raw, scopeAt(at)))
                 throw new Error("An earlier wallet write is still unresolved. Check it before trying again.");
+            // The record this one replaces, if the user released it: its marker goes too.
+            let replaced;
+            try {
+                replaced = at === key && raw !== null ? JSON.parse(raw)?.id : undefined;
+            }
+            catch {
+                /* An unreadable record leaves no marker to clean. */
+            }
             const record = {
                 version: 1,
                 id: globalThis.crypto.randomUUID(),
                 ...actual,
+                ...(evidence
+                    ? { nonce: nonce.toString(), fromBlock: fromBlock.toString() }
+                    : {}),
             };
             owned = recordOf(record);
             try {
-                persist(record);
+                persist(record, key);
             }
             catch (error) {
                 // The wallet has not been invoked. A failed readback may still have
@@ -194,56 +516,74 @@ export function createBrowserWriteRecovery(input, options = {}) {
                 }
                 throw error;
             }
-            return recordOf(record);
-        },
-        submitted(hash, expected = owned) {
-            requireLock();
-            if (!isBytes32(hash))
-                throw new Error("The wallet returned an invalid transaction identity.");
-            const previous = expected && recordOf(expected);
-            const submittedHash = hash.toLowerCase();
-            if (!previous ||
-                scope(previous) !== key ||
-                (previous.hash && previous.hash !== submittedHash)) {
-                throw new Error("Write recovery changed before submission was recorded.");
-            }
-            const submitted = { ...previous, hash: submittedHash };
-            let raw;
-            try {
-                raw = storage().getItem(key);
-            }
-            catch (cause) {
-                owned = submitted;
-                rememberSubmission(submitted);
-                throw new SubmittedWritePersistenceError(submitted, cause);
-            }
-            const current = readStored(raw);
-            if (!current ||
-                JSON.stringify({ ...current, hash: undefined }) !==
-                    JSON.stringify({ ...previous, hash: undefined }) ||
-                (current.hash && current.hash !== submittedHash)) {
-                throw new Error("Write recovery changed before submission was recorded.");
-            }
-            owned = recordOf(submitted);
-            if (!current.hash) {
+            if (typeof replaced === "string" && replaced !== record.id)
                 try {
-                    persist(submitted);
+                    store.removeItem(releasedKey(key, replaced));
                 }
-                catch (cause) {
-                    rememberSubmission(submitted, true);
-                    throw new SubmittedWritePersistenceError(submitted, cause);
+                catch {
+                    /* A leftover marker names only the old record. */
                 }
-            }
-            if (lastStorage)
-                unpersistedSubmissions.get(lastStorage)?.delete(key);
-            return submitted;
+            return recordOf(record);
+        },
+        submitted(hash, expected = owned) {
+            return record(hash, expected, false);
         },
         rejected,
         clear,
+        /**
+         * Check the saved write against the chain ({@link checkReviewedWrite}) and
+         * apply the finding: `sent` records the hash to track, `ran` releases it.
+         * Null when nothing is saved.
+         */
+        async resolve(client, checkOptions) {
+            requireLock();
+            let saved = read();
+            if (!saved)
+                return null;
+            const { check, sentNonce } = await inspectWrite(client, saved, checkOptions?.effect);
+            if (sentNonce !== undefined && saved.sentNonce !== sentNonce)
+                saved = bind(saved, sentNonce);
+            if (check.status === "sent") {
+                if (check.hash !== saved.hash)
+                    record(check.hash, saved, true);
+            }
+            else if (check.status !== "pending")
+                clear(saved);
+            return check;
+        },
+        /**
+         * The user confirmed they checked their wallet; release the write. It
+         * marks only the record `expected` names (by its ID) as released and never
+         * removes the saved key, so a stale exit can't erase a newer write another
+         * tab saved there. It needs no lock and still works when the cross-tab lock
+         * can't be taken; new sends still need `withLock`. `expected` may be what
+         * `read()` showed, including a returned hash kept only in memory.
+         */
+        abandon(expected, acknowledgement) {
+            if (acknowledgement?.checkedWallet !== true)
+                throw new Error("Release a held write only after the user confirms they checked their wallet.");
+            const wanted = JSON.stringify(recordOf(expected));
+            const store = storage();
+            const { at, raw } = locate(store);
+            const durable = readStored(raw, at, scopeAt(at), store);
+            if (!durable)
+                return;
+            const shown = readRecovery(store, at, raw, scopeAt(at));
+            if (JSON.stringify(durable) !== wanted &&
+                JSON.stringify(shown) !== wanted)
+                throw new Error("Write recovery changed. Keep the current action pending.");
+            const marker = releasedKey(at, durable.id);
+            store.setItem(marker, "1");
+            if (store.getItem(marker) !== "1")
+                throw new Error("Write recovery storage did not release the action.");
+            const memory = unpersistedSubmissions.get(store);
+            if (memory?.get(at)?.id === durable.id)
+                memory.delete(at);
+            if (owned?.id === durable.id)
+                owned = undefined;
+        },
         async withLock(work, wait = false) {
-            const locks = options.locks ?? globalThis.navigator?.locks;
-            if (!locks)
-                throw new Error("This browser cannot safely coordinate wallet writes.");
+            const locks = options.locks ?? browserLocks();
             return locks.request(key, { mode: "exclusive", ...(!wait && { ifAvailable: true }) }, async (lock) => {
                 if (!lock)
                     throw new Error("This wallet action is already open in another tab.");
@@ -258,6 +598,109 @@ export function createBrowserWriteRecovery(input, options = {}) {
         },
     };
 }
+/** The account's next nonce, counting its pending transactions, and the block it was read at. Read it right before `reserve`. */
+export async function readReviewedWriteNonce(client, account) {
+    const blockNumber = await client.getBlockNumber();
+    const nonce = await client.getTransactionCount({
+        address: account,
+        blockTag: "pending",
+    });
+    return { nonce, blockNumber };
+}
+/**
+ * What the chain shows of a saved ordinary write. Every read is on the
+ * record's chain, at or below a canonical finalized block where it matters.
+ *
+ * - The saved hash, when the node knows it, is the transaction: `sent` once
+ *   mined (its receipt decides, wallet wrappers included), `pending` while in
+ *   the mempool. Its nonce is the nonce it was sent at (`sentNonce`).
+ * - Otherwise, once the account's nonce is past the nonce to look at, the
+ *   block where it moved holds the transaction that used it. The saved hash or
+ *   the exact call there is `sent`. Any other transaction there may have run
+ *   the call inside it (a wrapper, or an EIP-7702 wallet that ran code and
+ *   cleared its delegation in the same block), so it stays `pending` and the
+ *   user's exit (`abandon`) ends it.
+ * - `effect`, the app's read of the call's result on the saved chain, ends it
+ *   as `ran` when true. The client's chain is checked first.
+ *
+ * Anything else stays `pending`: a Safe write, a record without nonce
+ * evidence, another chain, or a node without the history to answer.
+ */
+export async function checkReviewedWrite(client, saved, { effect } = {}) {
+    return (await inspectWrite(client, saved, effect)).check;
+}
+async function inspectWrite(client, saved, effect) {
+    const record = recordOf(saved);
+    const pending = { check: { status: "pending" } };
+    // No proof, the app's effect read included, from another chain.
+    if ((await client.getChainId().catch(() => null)) !== record.chainId)
+        return pending;
+    if (effect && (await effect(record.chainId).catch(() => false)))
+        return { check: { status: "ran" } };
+    if (record.safe)
+        return pending;
+    if (record.hash) {
+        const sent = await client.getTransaction({ hash: record.hash }).then((tx) => tx, (error) => error?.name === "TransactionNotFoundError" ? null : undefined);
+        if (sent === undefined)
+            return pending;
+        if (sent) {
+            if (sent.from?.toLowerCase() !== record.account)
+                return pending;
+            return {
+                check: sent.blockNumber !== null && sent.blockNumber !== undefined
+                    ? { status: "sent", hash: record.hash }
+                    : { status: "pending" },
+                sentNonce: BigInt(sent.nonce).toString(),
+            };
+        }
+    }
+    const bound = record.hash !== undefined && record.sentNonce !== undefined;
+    const target = bound ? record.sentNonce : record.nonce;
+    if (target === undefined || record.fromBlock === undefined)
+        return pending;
+    const nonce = BigInt(target);
+    const count = async (blockNumber) => BigInt(await client.getTransactionCount({
+        address: record.account,
+        blockNumber,
+    }));
+    const proof = await atCanonicalFinalizedBlock(client, async (finalized) => {
+        let low = BigInt(record.fromBlock);
+        let high = finalized;
+        if (high <= low ||
+            (await count(high)) <= nonce ||
+            (await count(low)) > nonce)
+            return null;
+        while (high - low > 1n) {
+            const middle = (low + high) / 2n;
+            if ((await count(middle)) > nonce)
+                high = middle;
+            else
+                low = middle;
+        }
+        const block = await client.getBlock({
+            blockNumber: high,
+            includeTransactions: true,
+        });
+        const used = block.number === high
+            ? block.transactions.find((tx) => tx.from?.toLowerCase() === record.account &&
+                BigInt(tx.nonce) === nonce)
+            : undefined;
+        if (!used || !isBytes32(used.hash))
+            return null;
+        const hash = used.hash.toLowerCase();
+        if (hash === record.hash)
+            return { status: "sent", hash };
+        if (used.to?.toLowerCase() === record.call.to &&
+            used.input?.toLowerCase() === record.call.data &&
+            BigInt(used.value ?? 0) === BigInt(record.call.value))
+            return { status: "sent", hash };
+        // Another transaction at that nonce may have run the call inside it
+        // (a wrapper, or an EIP-7702 wallet that ran code and then cleared its
+        // delegation), so it proves nothing. The user's exit ends it.
+        return null;
+    });
+    return { check: proof?.value ?? pending.check };
+}
 /**
  * Authenticate the saved wallet identity, canonical inclusion and Safe effect.
  * Ordinary wallet wrappers are allowed: the wallet's returned hash binds their