@bananapus/nana-sdk-core 6.1.0 → 6.3.0

package/dist/esm/review/send.js

@@ -1,3 +1,5 @@
+import { assertLocksHeld, keepOutcome } from "./locks.js";
+import { CONFIRMING_RENEW_MS } from "./confirming.js";
 import { ReviewedCallRevertedError, ReviewedReceiptUnverifiedError, ReviewLineError, WalletNotInvokedError, } from "./lineError.js";
 import { encodeFunctionData, formatEther, } from "viem";
 import { failedSimulation, promptReview, } from "./confirm.js";
@@ -14,7 +16,7 @@ import { mintPlan, relayrStandInSender, REVIEWED_PLAN_REFUSED_LINE, spendPlan, }
 import { heldBlock, heldReceipt, tell, waitForTrackedReceipt, } from "./receipt.js";
 import { relayrPaymentChains } from "./relayr.js";
 import { relayrFeeCap } from "./relayrSend.js";
-import { assertSavableCalls, readReviewedSequence, removeReviewedSequence, REVIEWED_SEQUENCE_MOVED_LINE, REVIEWED_SEQUENCE_UNCERTAIN_LINE, REVIEWED_SEQUENCE_UNFINISHED_LINE, saveReviewedSequence, } from "./sequence.js";
+import { assertSavableCalls, decodeOutcome, encodeOutcome, readReviewedSequence, removeReviewedSequence, REVIEWED_SEQUENCE_MOVED_LINE, REVIEWED_SEQUENCE_UNCERTAIN_LINE, REVIEWED_SEQUENCE_UNFINISHED_LINE, saveReviewedSequence, } from "./sequence.js";
 import { plannedCallsOf, prepareSignature, signPrepared, } from "./sign.js";
 import { isRevert, REVERT_UNKNOWN_LINE, revertDetail, revertReason, simulateCallSequence, simulateStateChangingTransaction, simulationFailure, } from "./simulation.js";
 import { unsupportedWalletRequest, walletReady, } from "./wallet.js";
@@ -382,16 +384,38 @@ export async function resumeReviewed(record, action, deps) {
         const { settled } = state;
         // Read before anything advances: a failed read leaves the step to resume again.
         const receipt = await confirmedReceipt(settled, deps.clientFor(call.chainId));
-        // This sequence's own step: it is recorded, told, and only then
-        // acknowledged, so it is never offered again.
-        const kept = await recordSending(saved, settled, storage, expected);
-        await tellConfirmed(action, handle, call, step, settled, receipt);
+        // This sequence's own step: told, recorded, and only then acknowledged,
+        // so it is never offered again. Its notice not delivered yet, it stays
+        // held at its receipt, acknowledged by none, for a completion to tell.
+        let kept = expected;
+        const outcome = outcomeOf(handle, reservation, {
+            account: saved.account,
+            step,
+            call,
+            prior: [...saved.completed],
+            ...(saved.signatures ? { signatures: saved.signatures } : {}),
+        });
+        const ended = await endStep(action, handle, outcome, settled, receipt, async () => {
+            kept = await recordSending(saved, settled, storage, expected);
+        });
+        if (!ended)
+            throw new ReviewedReceiptUnverifiedError(step, settled.hash, undefined, {
+                call: outcome.call,
+                reservation,
+                hashes: [...outcome.prior],
+                ...signedBy(outcome),
+            });
         if (settled?.result === "success")
             await handle.acknowledge(settled);
         if (kept === null) {
             const total = saved.calls.length;
             tell(deps.onProgress, { step: total - 1, total, phase: "done" });
-            return { status: "done", hashes: saved.completed, receipts: [] };
+            return {
+                status: "done",
+                hashes: hashesThrough(outcome, settled),
+                receipts: [],
+                ...signedBy(outcome),
+            };
         }
         expected = kept;
     }
@@ -430,14 +454,87 @@ async function confirmedReceipt(settled, client, given) {
 /**
  * Tells `onConfirmed` of a step's verified success, once per settlement:
  * only the completion (a run, `completeReviewedStep`, `resumeReviewed`, in
- * any tab) that claims its notice on the hold tells it.
+ * any tab) that claims its notice on the hold tells it. The claim is made
+ * for good once told, and given back if the site never gets it, so a later
+ * completion tells it.
  */
 async function tellConfirmed(action, handle, call, step, settled, receipt) {
-    if (settled?.result === "success" &&
-        receipt &&
-        (await handle.claimConfirmed(settled)))
-        await tell(action.onConfirmed, call, step, receipt);
+    if (settled?.result !== "success" || !receipt)
+        return "delivered";
+    const claimant = globalThis.crypto.randomUUID();
+    if (!(await handle.claimConfirmed(settled, claimant)))
+        // Another completion's: delivered, or not yet.
+        return (await handle.confirmation(settled)) === "delivered"
+            ? "delivered"
+            : "pending";
+    // Renewed while this delivery runs (kept for a lock too), so only a claim
+    // whose tab closed or crashed lapses; ended only by this claimant.
+    const renewal = setInterval(() => void handle.claimConfirmed(settled, claimant).catch(() => undefined), CONFIRMING_RENEW_MS);
+    let delivery = "pending";
+    const end = async (delivered) => {
+        clearInterval(renewal);
+        await handle.settleConfirmed(settled, delivered, claimant);
+    };
+    try {
+        const told = await tellKept(action, () => action.onConfirmed?.(call, step, receipt), async (applied) => {
+            delivery = applied ? "delivered" : "undelivered";
+            await end(applied);
+        });
+        if (!told)
+            return delivery;
+        await end(true);
+        return "delivered";
+    }
+    catch (error) {
+        clearInterval(renewal);
+        throw error;
+    }
 }
+/**
+ * Ends a settled step, the one way every completion does (a run, a resume,
+ * `completeReviewedStep`): its `onConfirmed` told with its outcome's call
+ * and step, and only once delivered is it recorded done (`record`, its
+ * reservation leaving the sequence's journal). Until then the step stays
+ * held there, so a later completion or resume tells it before any step
+ * after it is sent. False while undelivered.
+ */
+async function endStep(action, handle, outcome, settled, receipt, record) {
+    if ((await tellConfirmed(action, handle, outcome.call, outcome.step, settled, receipt)) !== "delivered")
+        return false;
+    await record();
+    return true;
+}
+/**
+ * A sent step's outcome as its run saved it on the hold with `reservation`
+ * ({@link ReviewedOutcome}), else `handed` (what its caller has: a hold
+ * that saved none, or an older version's).
+ */
+const outcomeOf = (handle, reservation, handed) => (reservation === undefined
+    ? undefined
+    : decodeOutcome(handle.outcomeOf(reservation))) ?? handed;
+/** The action's hashes through `outcome`'s step, as `settled` ended it. */
+const hashesThrough = (outcome, settled) => settled?.result === "success" && "hash" in settled
+    ? [...outcome.prior, settled.hash]
+    : [...outcome.prior];
+/** The outcome's signatures, as a result spreads them. */
+const signedBy = ({ signatures }) => signatures ? { signatures: [...signatures] } : {};
+/**
+ * Tells a site what the wallet answered, under its `locks`: refused for a
+ * lost one, kept for a fresh lock ({@link keepOutcome}, `settled` told
+ * whether it was applied in the end), or dropped when it can't be kept
+ * (`settled` told false). Any other failure is logged and never changes
+ * what was sent. False when the outcome was only kept, not told.
+ */
+const tellKept = async ({ locks, attemptScoped }, run, settled) => {
+    let kept = false;
+    await tell(() => keepOutcome(locks, run, attemptScoped ? run : undefined, settled).then((applied) => void (kept = !applied), async (error) => {
+        if (error?.code !== "LOCK_LOST")
+            throw error;
+        kept = true;
+        await settled?.(false);
+    }));
+    return !kept;
+};
 /**
  * A sent step's settlement by its own reservation, and the receipt its hold
  * verified ({@link heldReceipt}), read again until it reads. Null on `follow`'s
@@ -456,7 +553,10 @@ async function followSent(handle, client, reserved, follow) {
     const read = (work) => Promise.race([work, ended]);
     try {
         while (!signal.aborted) {
-            const state = await read(followHeldWrite(handle, client, { signal }));
+            const state = await read(followHeldWrite(handle, client, {
+                signal,
+                ...(reserved ? { reservation: reserved } : {}),
+            }));
             if (signal.aborted)
                 return null;
             if (state?.status !== "clear" ||
@@ -489,33 +589,72 @@ async function followSent(handle, client, reserved, follow) {
  * one acknowledgement of a followed step. Returns the settlement and that
  * checked receipt (a failure's too); null until then. A read that fails or disagrees with the hold throws with
  * nothing advanced: call it again. Call it once per settlement:
- * `onConfirmed` is told each time.
+ * `onConfirmed` is told each time. Its reservation's own saved settlement
+ * completes it after a later reservation of the call replaced it. Once
+ * `signal` aborts (the run that showed it is gone) it returns null, leaving
+ * the journal and `onConfirmed` to the run that resumes it. With
+ * `acknowledge` false it acknowledges nothing: the caller acknowledges the
+ * success once it has shown it (`handle.acknowledge`), so a success it
+ * never showed still warns the next run. `undelivered` says `onConfirmed`
+ * was kept for a lost lock and dropped: nothing is acknowledged, and a later
+ * completion (under the same or a fresh lock) tells it once.
  */
-export async function completeReviewedStep(unverified, action, deps, receipt) {
+export async function completeReviewedStep(unverified, action, deps, receipt, signal, acknowledge = true) {
     const { step, held } = unverified;
-    if (!held)
+    if (!held || signal?.aborted)
         return null;
     const { call, reservation } = held;
     const client = deps.clientFor(call.chainId);
     const handle = openStepHold(deps.hold, action.account, false, call);
     const state = await handle.state(client);
-    if (state.status !== "clear" ||
-        state.reservation !== reservation ||
-        !state.settled)
+    const settled = (state.status === "clear" && state.reservation === reservation
+        ? state.settled
+        : undefined) ??
+        (reservation === undefined ? undefined : handle.settlementOf(reservation));
+    if (!settled)
         return null;
-    const { settled } = state;
     const confirmed = await confirmedReceipt(settled, client, receipt);
-    if (action.scope !== undefined) {
+    if (signal?.aborted)
+        return null;
+    const outcome = outcomeOf(handle, reservation, {
+        account: action.account,
+        step,
+        call,
+        prior: [...(held.hashes ?? [])],
+        ...(held.signatures ? { signatures: held.signatures } : {}),
+    });
+    const ended = await endStep(action, handle, outcome, settled, confirmed, async () => {
+        if (action.scope === undefined)
+            return;
         const storage = deps.storage ?? createHeldWriteStorage();
-        const { raw, record } = readReviewedSequence(action.scope, action.account, storage);
-        if (record?.sending?.step === step &&
-            record.sending.reservation === reservation)
-            await recordSending(record, settled, storage, raw);
-    }
-    await tellConfirmed(action, handle, call, step, settled, confirmed);
-    if (settled.result === "success")
+        const scope = action.scope;
+        // Its journal entry by the reservation it saved (by the step its
+        // outcome saved, without one), never by the index of the action that
+        // completes it: a refreshed action's calls may be fewer.
+        const sending = () => {
+            const read = readReviewedSequence(scope, action.account, storage);
+            const saved = read.record?.sending;
+            return saved &&
+                saved.reservation === reservation &&
+                (reservation !== undefined || saved.step === outcome.step)
+                ? read
+                : null;
+        };
+        const read = sending();
+        if (!read)
+            return;
+        // Another completion recording it first leaves nothing to record.
+        await recordSending(read.record, settled, storage, read.raw).catch((error) => {
+            if (sending())
+                throw error;
+        });
+    });
+    const done = { settled, receipt: confirmed, ...signedBy(outcome) };
+    if (!ended)
+        return { ...done, undelivered: true, hashes: [] };
+    if (acknowledge && settled.result === "success")
         await handle.acknowledge(settled);
-    return { settled, receipt: confirmed };
+    return { ...done, hashes: hashesThrough(outcome, settled) };
 }
 /**
  * The hash a wallet returned, even when the site's record of it failed
@@ -538,8 +677,21 @@ async function send(action, deps, resuming) {
     const sent = snapshots.map(({ sent }) => sent);
     /** Each step's simulation block, read once; a resumed run's prerequisites are long confirmed. */
     const blocks = calls.map((call) => resuming ? undefined : call.simulationBlockNumber);
-    /** A site's release callback never stops core's own release. */
-    const tellUnsent = (call, step) => tell(action.onUnsent, call, step);
+    /**
+     * Tell the site its steps from `from` were not sent, each only while every
+     * one of its locks is still this tab's, read fresh right before that
+     * step's callback (an earlier callback's await may have outlived the
+     * lease): once one was lost, the lock's new owner owns the site's journal,
+     * whatever ended the attempt. A site's release callback never stops core's
+     * own release.
+     */
+    const tellUnsent = async (steps, from) => {
+        for (const [index, call] of steps.entries())
+            await tellKept(action, async () => {
+                await assertLocksHeld(action.locks);
+                await action.onUnsent?.(call, from + index);
+            });
+    };
     const connected = adapter.account();
     if (!connected)
         throw new ReviewLineError("Connect a wallet first.");
@@ -574,32 +726,34 @@ async function send(action, deps, resuming) {
         try {
             for (const [step, call] of calls.entries()) {
                 began += 1;
+                // The site's own record before the wallet: never under a lost lock.
+                await assertLocksHeld(action.locks);
                 await action.beforeWallet?.(call, step);
             }
+            await assertLocksHeld(action.locks);
             // The site's hooks may have awaited: the gates once more, right before the wallet.
             action.guard?.();
             action.assertWriteState?.();
             if (adapter.account()?.toLowerCase() !== account.toLowerCase())
                 throw new ReviewLineError(ACCOUNT_CHANGED);
             submitting = true;
-            hash = await adapter.submitToReviewer({
-                account,
-                calls: sent.map((call) => ({ ...call })),
-            });
+            hash = await adapter.submitToReviewer({ account, calls: sent.map((call) => ({ ...call })) }, { fence: () => assertLocksHeld(action.locks) });
         }
         catch (error) {
-            // Only the site's own refusal or an explicit rejection proves nothing was sent.
-            if (!submitting || isDefiniteWalletRejection(error))
-                for (const [step, call] of calls.slice(0, began).entries())
-                    await tellUnsent(call, step);
+            // Only the site's own refusal, the adapter's or an explicit rejection
+            // proves nothing was sent.
+            if (!submitting ||
+                error instanceof WalletNotInvokedError ||
+                isDefiniteWalletRejection(error))
+                await tellUnsent(calls.slice(0, began), 0);
             throw error;
         }
         // Every step is told; a site's failure to record it never changes what was sent.
         for (const [step, call] of calls.entries())
-            await tell(action.onSubmitted, call, step, hash, {
+            await tellKept(action, () => action.onSubmitted?.(call, step, hash, {
                 safe: false,
                 adopted: false,
-            });
+            }));
         return { status: "done", hashes: [hash], receipts: [] };
     }
     const { scope } = action;
@@ -700,7 +854,7 @@ async function send(action, deps, resuming) {
             });
         };
         signed = {
-            signatures: await signPrepared(prepared, account, adapter, stillReviewed),
+            signatures: await signPrepared(prepared, account, adapter, stillReviewed, () => assertLocksHeld(action.locks), () => assertLocksHeld(action.locks)),
         };
     }
     if (batched) {
@@ -731,9 +885,10 @@ async function send(action, deps, resuming) {
             }
             const released = async () => {
                 gate.onRejected();
-                for (const [step, call] of calls.slice(0, began).entries())
-                    await tellUnsent(call, step);
+                await tellUnsent(calls.slice(0, began), 0);
             };
+            /** Every lock is still this tab's: the hold's and the site's. */
+            const fence = () => assertLocksHeld([gate, ...(action.locks ?? [])]);
             return submitReviewedContractWrite({
                 request: batched,
                 expectedAccount: account,
@@ -761,12 +916,23 @@ async function send(action, deps, resuming) {
                     return sending;
                 },
                 beforeWrite: async () => {
-                    await gate.beforeSend();
+                    await gate.beforeSend(undefined, encodeOutcome({
+                        account,
+                        step: calls.length - 1,
+                        call: batched,
+                        prior: [],
+                        ...signed,
+                    }));
                     try {
                         for (const [step, call] of calls.entries()) {
                             began = step + 1;
+                            // The site's own record before the wallet: never under a lost lock.
+                            await assertLocksHeld(action.locks);
                             await action.beforeWallet?.(call, step);
                         }
+                        // Core's own check before the adapter, which fences again as
+                        // the last await before the wallet.
+                        await fence();
                     }
                     catch (error) {
                         await released();
@@ -789,13 +955,13 @@ async function send(action, deps, resuming) {
                     gate.afterSubmit(submitted);
                     // Every step went: each is told, whatever an earlier callback does.
                     for (const [step, call] of calls.entries())
-                        await tell(action.onSubmitted, call, step, submitted, {
+                        await tellKept(action, () => action.onSubmitted?.(call, step, submitted, {
                             safe: true,
                             adopted: false,
-                        });
+                        }));
                 },
                 write: async () => {
-                    const id = await adapter.sendCalls(batched.chainId, sent.map(({ to, data, value }) => ({ to, data, value })));
+                    const id = await adapter.sendCalls(batched.chainId, sent.map(({ to, data, value }) => ({ to, data, value })), { fence });
                     // A Safe app answers with the proposal's safeTxHash; anything else can't be followed.
                     if (typeof id !== "string" || !/^0x[0-9a-fA-F]{64}$/.test(id))
                         throw new ReviewLineError(SAFE_BATCH_UNFOLLOWABLE_LINE);
@@ -828,6 +994,7 @@ async function send(action, deps, resuming) {
                     ...snapshots[step].sent,
                 })),
                 completed: [],
+                ...signed,
             };
         // Refused when another window changed it meanwhile.
         expected = await saveReviewedSequence(journal, storage, expected);
@@ -848,6 +1015,11 @@ async function send(action, deps, resuming) {
         }
     };
     const hashes = [];
+    // A resumed run shows the signatures its first run signed.
+    if (journal?.signatures)
+        signed = { signatures: journal.signatures };
+    /** The last step's outcome, as its hold keeps it, and its hashes: the done result's source. */
+    let last;
     const receipts = [];
     const total = offset + calls.length;
     for (const [step, call] of calls.entries()) {
@@ -909,6 +1081,14 @@ async function send(action, deps, resuming) {
         const runEnd = hashes.length ? action.follow?.signal : undefined;
         /** The site's failed record of this step's hash: the step was sent, and is held unverified. */
         let unrecorded;
+        /** What this step's run shows, saved with its reservation. */
+        const outcome = {
+            account,
+            step: at,
+            call,
+            prior: journal ? [...journal.completed] : [...hashes],
+            ...signed,
+        };
         const hash = await handles[step]
             .send(client, (gate) => {
             // Under the hold's own check of the call, before anything reserves.
@@ -922,8 +1102,10 @@ async function send(action, deps, resuming) {
                     delete journal.sending;
                     await keep();
                 }
-                await tellUnsent(call, at);
+                await tellUnsent([call], at);
             };
+            /** Every lock is still this tab's: the hold's and the site's. */
+            const fence = () => assertLocksHeld([gate, ...(action.locks ?? [])]);
             return submitReviewedContractWrite({
                 request: reviewed,
                 expectedAccount: account,
@@ -976,7 +1158,7 @@ async function send(action, deps, resuming) {
                 },
                 beforeWrite: async () => {
                     // An adopted proposal is held as the call it runs.
-                    await gate.beforeSend(queued?.call);
+                    await gate.beforeSend(queued?.call, encodeOutcome(outcome));
                     reserved = handles[step].peek().reservation;
                     if (journal)
                         try {
@@ -993,7 +1175,12 @@ async function send(action, deps, resuming) {
                             throw error;
                         }
                     try {
+                        // The site's own record before the wallet: never under a lost lock.
+                        await assertLocksHeld(action.locks);
                         await action.beforeWallet?.(call, at);
+                        // Core's own check before the adapter, which fences again as
+                        // the last await before the wallet.
+                        await fence();
                     }
                     catch (error) {
                         await released();
@@ -1023,10 +1210,10 @@ async function send(action, deps, resuming) {
                 // An adopted proposal's nonce lets the hold prove its execution onchain.
                 onWriteSubmitted: async (submitted) => {
                     gate.afterSubmit(submitted, queued?.tx);
-                    await tell(action.onSubmitted, call, at, submitted, {
+                    await tellKept(action, () => action.onSubmitted?.(call, at, submitted, {
                         safe,
                         adopted: !!queued,
-                    });
+                    }));
                 },
                 write: async ({ chainId, to, data, value, gas }) => queued?.proposalHash ??
                     adapter.sendTransaction({
@@ -1038,6 +1225,7 @@ async function send(action, deps, resuming) {
                         // After a step was sent, the run's end refuses this one, unsent,
                         // as late as the wallet's own last check.
                         ...(runEnd ? { signal: runEnd } : {}),
+                        fence,
                     }),
                 onPhase: (phase) => progress(phase),
                 guard: action.guard,
@@ -1072,14 +1260,14 @@ async function send(action, deps, resuming) {
         }
         // From here the step was sent: it ends done, failed as its hold
         // verified, or unverified with what resumes it, never any other way.
+        /** `completed`: this step's hash already recorded as completed. */
         const unverified = (cause) => new ReviewedReceiptUnverifiedError(at, hash, isSafeExecTransaction(reviewed.data)
             ? WRITE_HOLD_SAFE_UNCONFIRMED_LINE
             : undefined, {
             call,
             reservation: reserved,
-            // This run's sends, its own last: only the steps before it completed.
-            hashes: journal ? [...journal.completed] : hashes.slice(0, -1),
-            ...signed,
+            hashes: [...outcome.prior],
+            ...signedBy(outcome),
         }, cause === undefined ? {} : { cause });
         // The site could not record the hash: held as sent, for it to resume.
         if (unrecorded !== undefined)
@@ -1138,19 +1326,24 @@ async function send(action, deps, resuming) {
             throw new ReviewedCallRevertedError(at, mined, receipt);
         }
         receipts.push(receipt);
-        if (journal) {
+        // Its notice not delivered yet: held at its receipt for its completion.
+        const ended = await endStep(action, handles[step], outcome, settled, receipt, async () => {
+            if (!journal)
+                return;
             delete journal.sending;
             journal.completed.push(mined);
             await keep();
-        }
-        await tellConfirmed(action, handles[step], call, at, settled, receipt);
+        });
+        if (!ended)
+            throw unverified();
+        last = { outcome, hashes: hashesThrough(outcome, settled) };
     }
     onProgress({ step: total - 1, total, phase: "done" });
     return {
         status: "done",
-        hashes: journal ? [...journal.completed] : hashes,
+        hashes: last.hashes,
         receipts,
-        ...signed,
+        ...signedBy(last.outcome),
     };
 }
 //# sourceMappingURL=send.js.map