@bananapus/nana-sdk-core 2.31.0 → 2.33.0

package/dist/esm/review/writeRecovery.js

@@ -2,6 +2,9 @@ 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";
+const TAB_MEMORY = Symbol.for("nana-sdk:held-writes");
+const TAB_QUEUES = Symbol.for("nana-sdk:write-lock-queues");
+const TAB_SEEN = Symbol.for("nana-sdk:held-writes-seen");
 // 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();
@@ -53,7 +56,17 @@ function recordOf(value) {
         (record.hash !== undefined && !isBytes32(record.hash)) ||
         !optionalDecimal(record.nonce) ||
         !optionalDecimal(record.fromBlock) ||
-        !optionalDecimal(record.sentNonce))
+        !optionalDecimal(record.sentNonce) ||
+        !optionalDecimal(record.submittedAt) ||
+        !optionalDecimal(record.firstSeenAt) ||
+        !optionalDecimal(record.safeNonce) ||
+        (record.replaced !== undefined && record.replaced !== true) ||
+        (record.unproven !== undefined && record.unproven !== true) ||
+        (record.sentFrom !== undefined &&
+            !isAddress(record.sentFrom, { strict: false })) ||
+        (record.executed !== undefined && record.executed !== true) ||
+        (record.executionHash !== undefined &&
+            (record.executed !== true || !isBytes32(record.executionHash))))
         throw new Error("Invalid saved write recovery record. Keep this action pending.");
     return {
         version: 1,
@@ -65,6 +78,22 @@ function recordOf(value) {
         ...(record.nonce === undefined ? {} : { nonce: record.nonce }),
         ...(record.fromBlock === undefined ? {} : { fromBlock: record.fromBlock }),
         ...(record.sentNonce === undefined ? {} : { sentNonce: record.sentNonce }),
+        ...(record.submittedAt === undefined
+            ? {}
+            : { submittedAt: record.submittedAt }),
+        ...(record.firstSeenAt === undefined
+            ? {}
+            : { firstSeenAt: record.firstSeenAt }),
+        ...(record.safeNonce === undefined ? {} : { safeNonce: record.safeNonce }),
+        ...(record.sentFrom === undefined
+            ? {}
+            : { sentFrom: record.sentFrom.toLowerCase() }),
+        ...(record.replaced ? { replaced: true } : {}),
+        ...(record.unproven ? { unproven: true } : {}),
+        ...(record.executed ? { executed: true } : {}),
+        ...(record.executionHash === undefined
+            ? {}
+            : { executionHash: record.executionHash.toLowerCase() }),
     };
 }
 function optionalDecimal(value) {
@@ -106,6 +135,136 @@ function recoveryStorage(store) {
         throw new Error("Write recovery storage is unavailable.");
     return result;
 }
+const PROBE_KEY = "nana-sdk:reviewed-write:probe";
+function idOf(raw) {
+    try {
+        const id = JSON.parse(raw)?.id;
+        return typeof id === "string" ? id : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The browser's storage, shared by its tabs and kept across reloads, while it
+ * can be written; this tab's memory while it can't (private browsing, a
+ * sandboxed frame, some wallet webviews), so a write is held either way and
+ * never refused. Every read looks at both. A record kept in memory moves into
+ * the browser's storage as soon as it can be written there, after any other
+ * live record saved at the same key ends. While the browser's storage can't
+ * be read, what this tab last read or wrote there still holds.
+ *
+ * `memory` defaults to one map per tab, shared by every copy of this module
+ * loaded there.
+ */
+export function createHeldWriteStorage(options = {}) {
+    const durable = options.durable ??
+        (() => globalThis.localStorage);
+    const tab = globalThis;
+    const memory = options.memory ?? (tab[TAB_MEMORY] ??= new Map());
+    /**
+     * What this tab last saw in, or wrote to, durable storage (records,
+     * releases and deletions), shared by every controller and copy of this
+     * module using the same tab memory.
+     */
+    const registry = (globalThis[TAB_SEEN] ??= new WeakMap());
+    let seen = registry.get(memory);
+    if (!seen)
+        registry.set(memory, (seen = new Map()));
+    const read = (key) => {
+        try {
+            const store = durable();
+            if (!store)
+                return undefined;
+            const value = store.getItem(key);
+            if (value === null)
+                seen.delete(key);
+            else
+                seen.set(key, value);
+            return value;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const write = (key, value) => {
+        try {
+            const store = durable();
+            if (!store)
+                return false;
+            store.setItem(key, value);
+            if (store.getItem(key) !== value)
+                return false;
+            seen.set(key, value);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    const getItem = (key) => {
+        const saved = read(key);
+        const kept = memory.get(key);
+        if (saved === undefined)
+            return kept ?? seen.get(key) ?? null;
+        if (kept === undefined)
+            return saved;
+        if (saved === kept) {
+            memory.delete(key);
+            return saved;
+        }
+        const savedId = saved === null ? undefined : idOf(saved);
+        // Another live record saved there first is held first; this one waits.
+        if (saved !== null &&
+            savedId !== idOf(kept) &&
+            !(savedId !== undefined && getItem(releasedKey(key, savedId)) !== null))
+            return saved;
+        if (write(key, kept))
+            memory.delete(key);
+        return kept;
+    };
+    return {
+        getItem,
+        setItem(key, value) {
+            const kept = memory.get(key);
+            if (write(key, value)) {
+                if (kept === value || (kept && idOf(kept) === idOf(value)))
+                    memory.delete(key);
+            }
+            else
+                memory.set(key, value);
+        },
+        removeItem(key) {
+            const shown = getItem(key);
+            if (shown !== null && memory.get(key) === shown) {
+                memory.delete(key);
+                if (read(key) !== shown)
+                    return;
+            }
+            try {
+                durable()?.removeItem(key);
+            }
+            catch {
+                /* The readback below decides. */
+            }
+            if (read(key) === null)
+                seen.delete(key);
+        },
+        durable() {
+            const probe = String(Date.now());
+            if (!write(PROBE_KEY, probe))
+                return false;
+            try {
+                durable().removeItem(PROBE_KEY);
+            }
+            catch {
+                /* A leftover probe names no write. */
+            }
+            seen.delete(PROBE_KEY);
+            return true;
+        },
+    };
+}
 /**
  * Open the original namespaced action before fresh quotation or phase checks.
  * No call is invented to locate evidence. Legacy actions retain factory.read().
@@ -141,8 +300,8 @@ function readRecovery(store, key, raw = store.getItem(key), scopeOf = scope) {
     const memory = unpersistedSubmissions.get(store)?.get(key);
     if (!record ||
         !memory ||
-        JSON.stringify({ ...record, hash: undefined }) !==
-            JSON.stringify({ ...memory, hash: undefined }) ||
+        JSON.stringify({ ...record, hash: undefined, submittedAt: undefined }) !==
+            JSON.stringify({ ...memory, hash: undefined, submittedAt: undefined }) ||
         (record.hash && record.hash !== memory.hash)) {
         // A readable durable snapshot also proves whether cached evidence is stale.
         unpersistedSubmissions.get(store)?.delete(key);
@@ -156,8 +315,9 @@ function readRecovery(store, key, raw = store.getItem(key), scopeOf = scope) {
 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();
+// Without Web Locks, writes in this tab still run one at a time per action,
+// across every copy of this module loaded in the tab.
+const tabQueues = (globalThis[TAB_QUEUES] ??= new Map());
 let tabLocksNoted = false;
 const tabLocks = {
     async request(name, options, work) {
@@ -386,6 +546,23 @@ export function createBrowserWriteRecovery(input, options = {}) {
             throw new Error("Write recovery storage did not clear the action.");
         unpersistedSubmissions.get(store)?.delete(at);
     }
+    /** Add `fields` to exactly `expected`, a hashed record `when` allows; extra evidence only. */
+    function amend(expected, when, fields) {
+        requireLock();
+        const current = read();
+        if (!current?.hash ||
+            !when(current) ||
+            JSON.stringify(current) !== JSON.stringify(recordOf(expected)))
+            return current ?? recordOf(expected);
+        const next = recordOf({ ...current, ...fields });
+        try {
+            persist(next, locate(storage()).at);
+            return next;
+        }
+        catch {
+            return current;
+        }
+    }
     function rejected() {
         requireLock();
         // A rejection callback from another attempt must never release this one.
@@ -428,7 +605,15 @@ export function createBrowserWriteRecovery(input, options = {}) {
             (!replace && previous.hash && previous.hash !== submittedHash)) {
             throw new Error("Write recovery changed before submission was recorded.");
         }
-        const submitted = { ...previous, hash: submittedHash };
+        // A hash the wallet returns now starts its clock; a speed-up found at its nonce keeps it.
+        const submittedAt = replace || previous.hash === submittedHash
+            ? previous.submittedAt
+            : String(Date.now());
+        const submitted = recordOf({
+            ...previous,
+            hash: submittedHash,
+            ...(submittedAt === undefined ? {} : { submittedAt }),
+        });
         let raw;
         let at = key;
         try {
@@ -442,8 +627,16 @@ export function createBrowserWriteRecovery(input, options = {}) {
         // 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 }) ||
+            JSON.stringify({
+                ...current,
+                hash: undefined,
+                submittedAt: undefined,
+            }) !==
+                JSON.stringify({
+                    ...previous,
+                    hash: undefined,
+                    submittedAt: undefined,
+                }) ||
             (!replace && current.hash && current.hash !== submittedHash)) {
             throw new Error("Write recovery changed before submission was recorded.");
         }
@@ -530,10 +723,93 @@ export function createBrowserWriteRecovery(input, options = {}) {
         },
         rejected,
         clear,
+        /**
+         * Start the clock of a hash saved before `submittedAt` existed: save now
+         * as its `firstSeenAt`, once. Extra evidence: a stale snapshot or a failed
+         * save keeps the record as it was.
+         */
+        firstSeen(expected) {
+            return amend(expected, (current) => current.submittedAt === undefined &&
+                current.firstSeenAt === undefined, { firstSeenAt: String(Date.now()) });
+        },
+        /**
+         * Save who sent a Safe execution the wallet returned at once, and at which
+         * nonce, from its authenticated transaction, once: its canonical
+         * replacement can then be proven. Extra evidence only.
+         */
+        sentBy(expected, from, nonce) {
+            return amend(expected, (current) => current.safe && current.sentFrom === undefined, { sentFrom: from, sentNonce: nonce.toString() });
+        },
+        /**
+         * Drop the proof that `expected` ran, once its execution is gone from the
+         * chain: it is held again as an unproven write. Extra evidence only.
+         */
+        unexecuted(expected) {
+            return amend(expected, (current) => current.executed === true, {
+                executed: undefined,
+                executionHash: undefined,
+            });
+        },
+        /**
+         * Save that another Safe transaction used this Safe write's nonce. Any
+         * saved execution goes: the user's exit, not the chain, ends it.
+         */
+        replacedOnChain(expected) {
+            return amend(expected, (current) => current.safe && !current.replaced, {
+                executed: undefined,
+                executionHash: undefined,
+                replaced: true,
+            });
+        },
+        /**
+         * Save that the app's follower of this Safe write ended without proof.
+         * A proven execution or replacement keeps its own state.
+         */
+        unprovenEnd(expected) {
+            return amend(expected, (current) => current.safe &&
+                !current.executed &&
+                !current.replaced &&
+                !current.unproven, { unproven: true });
+        },
+        /**
+         * Save a Safe proposal's nonce from its authenticated record, once. Extra
+         * evidence: a stale snapshot or a failed save keeps the record as it was.
+         */
+        proposalNonce(expected, nonce) {
+            return amend(expected, (current) => current.safe && current.safeNonce === undefined, { safeNonce: nonce.toString() });
+        },
+        /**
+         * Save the chain's proof that `expected` ran, with the transaction it ran
+         * in when known. From then on the user's exit refuses it: only its result
+         * ({@link verifyReviewedWriteReceipt}) releases it.
+         */
+        executed(expected, executionHash) {
+            requireLock();
+            if (executionHash !== undefined && !isBytes32(executionHash))
+                throw new Error("Invalid execution transaction identity.");
+            const store = storage();
+            const { at, raw } = locate(store);
+            const current = readRecovery(store, at, raw, scopeAt(at));
+            const wanted = recordOf(expected);
+            if (!current?.hash ||
+                current.id !== wanted.id ||
+                current.hash !== wanted.hash)
+                throw new Error("Write recovery changed. Keep the current action pending.");
+            const next = recordOf({
+                ...current,
+                executed: true,
+                ...((executionHash ?? current.executionHash)
+                    ? { executionHash: executionHash ?? current.executionHash }
+                    : {}),
+            });
+            persist(next, at);
+            unpersistedSubmissions.get(store)?.delete(at);
+            return next;
+        },
         /**
          * 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.
+         * apply the finding: `sent` records the hash to track. Nothing here
+         * releases a write; null when nothing is saved.
          */
         async resolve(client, checkOptions) {
             requireLock();
@@ -543,12 +819,8 @@ export function createBrowserWriteRecovery(input, options = {}) {
             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);
+            if (check.status === "sent" && check.hash !== saved.hash)
+                record(check.hash, saved, true);
             return check;
         },
         /**
@@ -568,6 +840,8 @@ export function createBrowserWriteRecovery(input, options = {}) {
             const durable = readStored(raw, at, scopeAt(at), store);
             if (!durable)
                 return;
+            if (durable.executed)
+                throw new Error("This write ran onchain. Keep it held until its result is known.");
             const shown = readRecovery(store, at, raw, scopeAt(at));
             if (JSON.stringify(durable) !== wanted &&
                 JSON.stringify(shown) !== wanted)
@@ -631,20 +905,29 @@ export async function checkReviewedWrite(client, saved, { effect } = {}) {
 }
 async function inspectWrite(client, saved, effect) {
     const record = recordOf(saved);
+    // No proof, the app's effect read included, from another chain, and none
+    // here for a Safe write.
+    if (record.safe ||
+        (await client.getChainId().catch(() => null)) !== record.chainId)
+        return { check: { status: "pending" } };
+    const found = await inspectOrdinary(client, record);
+    if (found.check.status === "pending" &&
+        effect &&
+        (await effect(record.chainId).catch(() => false)))
+        return { ...found, check: { ...found.check, effect: true } };
+    return found;
+}
+async function inspectOrdinary(client, record) {
     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)
+            // Only the saved hash's own transaction, on the saved chain, is evidence.
+            if (sent.from?.toLowerCase() !== record.account ||
+                sent.hash?.toLowerCase() !== record.hash ||
+                (sent.chainId !== undefined && sent.chainId !== record.chainId))
                 return pending;
             return {
                 check: sent.blockNumber !== null && sent.blockNumber !== undefined
@@ -656,15 +939,39 @@ async function inspectWrite(client, saved, effect) {
     }
     const bound = record.hash !== undefined && record.sentNonce !== undefined;
     const target = bound ? record.sentNonce : record.nonce;
-    if (target === undefined || record.fromBlock === undefined)
+    // The nonce a hash was sent at is authenticated by its own transaction, so
+    // a record saved without a starting block searches from genesis instead.
+    const from = record.fromBlock ?? (bound ? "0" : undefined);
+    if (target === undefined || from === undefined)
         return pending;
-    const nonce = BigInt(target);
-    const count = async (blockNumber) => BigInt(await client.getTransactionCount({
-        address: record.account,
-        blockNumber,
-    }));
+    const used = await findTransactionAtNonce(client, record.account, BigInt(target), BigInt(from));
+    if (!used)
+        return pending;
+    if (used.hash === record.hash)
+        return { check: { status: "sent", hash: used.hash } };
+    const sameCall = used.to?.toLowerCase() === record.call.to &&
+        used.input?.toLowerCase() === record.call.data &&
+        BigInt(used.value ?? 0) === BigInt(record.call.value);
+    // Another hash is adopted only at the nonce the saved hash's own
+    // transaction was sent at; the pre-wallet nonce only locates the call.
+    if (sameCall)
+        return bound ? { check: { status: "sent", hash: used.hash } } : pending;
+    // 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 { check: { status: "pending", usedBy: used.hash } };
+}
+/**
+ * The transaction `account` sent at `nonce`, once the account's nonce is past
+ * it at a canonical finalized block: a search of its nonce from `fromBlock`
+ * finds the block where it moved. Null while that is unproven or the node
+ * can't say (no history, a reorganized answer).
+ */
+export async function findTransactionAtNonce(client, account, nonce, fromBlock = 0n) {
+    const from = account.toLowerCase();
+    const count = async (blockNumber) => BigInt(await client.getTransactionCount({ address: account, blockNumber }));
     const proof = await atCanonicalFinalizedBlock(client, async (finalized) => {
-        let low = BigInt(record.fromBlock);
+        let low = fromBlock;
         let high = finalized;
         if (high <= low ||
             (await count(high)) <= nonce ||
@@ -682,34 +989,24 @@ async function inspectWrite(client, saved, effect) {
             includeTransactions: true,
         });
         const used = block.number === high
-            ? block.transactions.find((tx) => tx.from?.toLowerCase() === record.account &&
-                BigInt(tx.nonce) === nonce)
+            ? block.transactions.find((tx) => tx.from?.toLowerCase() === from && 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 { ...used, hash: used.hash.toLowerCase() };
     });
-    return { check: proof?.value ?? pending.check };
+    return proof?.value ?? null;
 }
 /**
  * Authenticate the saved wallet identity, canonical inclusion and Safe effect.
  * Ordinary wallet wrappers are allowed: the wallet's returned hash binds their
  * execution. A wallet-returned Safe proposal hash authenticates its execution
  * event even through a wrapper; an immediate execution hash additionally needs
- * exact reviewed calldata. A failure releases only after finality.
+ * exact reviewed calldata. A failure releases only after finality;
+ * `finality: false` authenticates a canonical failure before it is final.
  * Throws on missing or inconsistent evidence; the caller retains its record.
  */
-export async function verifyReviewedWriteReceipt(client, saved, receipt, proof) {
+export async function verifyReviewedWriteReceipt(client, saved, receipt, proof, { finality = true } = {}) {
     const record = recordOf(saved);
     const pending = () => new Error("The saved wallet write is not yet proven. Keep this action pending.");
     let calls = [record.call];
@@ -756,7 +1053,16 @@ export async function verifyReviewedWriteReceipt(client, saved, receipt, proof)
         (canonical.status !== "success" && canonical.status !== "reverted"))
         throw pending();
     let status = canonical.status === "success" ? "success" : "failed";
-    if (record.safe) {
+    // An execution the wallet returned at once whose own transaction reverted
+    // ran nothing on the Safe: a failure, once final, when it was sent to it.
+    const atOnceReverted = record.safe &&
+        canonical.status === "reverted" &&
+        hash.toLowerCase() === record.hash;
+    if (atOnceReverted) {
+        if (transaction.to?.toLowerCase() !== record.account)
+            throw pending();
+    }
+    else if (record.safe) {
         if (!Array.isArray(canonical.logs) ||
             canonical.logs.some((log) => log.removed !== false ||
                 log.transactionHash?.toLowerCase() !== hash.toLowerCase() ||
@@ -782,7 +1088,7 @@ export async function verifyReviewedWriteReceipt(client, saved, receipt, proof)
         return (block.number === canonical.blockNumber &&
             block.hash?.toLowerCase() === canonical.blockHash.toLowerCase());
     };
-    if (status === "failed") {
+    if (status === "failed" && finality) {
         const finalized = await atCanonicalFinalizedBlock(client, async (number) => number >= canonical.blockNumber && (await isCanonical()));
         if (!finalized?.value)
             throw pending();