@bananapus/nana-sdk-core 4.0.0 → 5.0.0

package/dist/esm/review/send.js

@@ -1,21 +1,24 @@
-import { ReviewedCallRevertedError, ReviewLineError } from "./lineError.js";
+import { ReviewedCallRevertedError, ReviewedReceiptUnverifiedError, ReviewLineError, WalletNotInvokedError, } from "./lineError.js";
 import { encodeFunctionData, formatEther, } from "viem";
-import { promptReview } from "./confirm.js";
+import { failedSimulation, promptReview, } from "./confirm.js";
 import { isDefiniteWalletRejection, SubmittedContractWriteError, submitReviewedContractWrite, } from "./contractWrite.js";
 import { JB_CHAINS } from "../constants.js";
 import { gasWithHeadroom } from "./gas.js";
+import { FOLLOW_MS, followHeldWrite, RECEIPT_RETRY_MS } from "./heldWrite.js";
+import { TransactionReviewCancelledError } from "./reviewQueue.js";
+import { pause } from "../pause.js";
 import { findPendingSafeAppProposal, hasSafeService, isSafeExecTransaction, } from "../safeService.js";
 import { REVIEWED_ACCOUNT_CHANGED_LINE, WRITE_HOLD_CALL_FAILED_LINE, WRITE_HOLD_SAFE_UNCONFIRMED_LINE, } from "./messages.js";
 import { buildReviewModel, enrichReviewModel, } from "./model.js";
 import { mintPlan, relayrStandInSender, REVIEWED_PLAN_REFUSED_LINE, spendPlan, } from "./plan.js";
-import { waitForTrackedReceipt } from "./receipt.js";
+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 { 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";
-import { openStepHold, safeBatchCall, WriteHeldError, WriteHoldStaleReviewError, } from "./writeHold.js";
+import { openStepHold, safeBatchCall, WriteHeldError, WriteHoldStaleReviewError, WriteHoldUnacknowledgedSuccessError, } from "./writeHold.js";
 import { createHeldWriteStorage, } from "./writeRecovery.js";
 const CHANGED = "Transaction data changed after review. Nothing was sent; review it again.";
 const MISMATCHED = "This call's data does not match its arguments. Nothing was sent.";
@@ -188,14 +191,15 @@ funded) {
             if (!isRevert(error))
                 return { status: "unavailable", message: SIMULATION_UNAVAILABLE };
             const reason = revertReason(error);
-            return {
+            // A sequence's failure is the SDK's line naming its call.
+            const failure = error instanceof ReviewLineError
+                ? error
+                : simulationFailure(`${labelOf(calls[steps[0]], steps[0])} cannot run on ${chainName}: ${reason ?? REVERT_UNKNOWN_LINE}`, error);
+            return failedSimulation({
                 status: "failed",
-                // A sequence's failure is the SDK's line naming its call.
-                message: error instanceof ReviewLineError
-                    ? error.message
-                    : `${labelOf(calls[steps[0]], steps[0])} cannot run on ${chainName}: ${reason ?? REVERT_UNKNOWN_LINE}`,
+                message: failure.message,
                 explained: reason !== null,
-            };
+            }, failure);
         }
     });
     // A revert on one chain is reported at once, whatever the others still wait on.
@@ -237,8 +241,8 @@ async function promptSimulated(model, fromOf, calls, run, blocks, clientFor, sig
  * One review of calls an app then sends one by one, across chains and
  * paths: core's prompt over exactly `action.calls`, simulated as their
  * senders, and nothing else. The plan it returns lets {@link sendReviewed},
- * `signReviewed`, `proposeReviewedSafeTransaction`, `payRelayrReviewed` and
- * `runRelayrReviewed` skip their prompt for a call identical to one of its
+ * `signReviewed`, `proposeReviewedSafeTransaction` and `payRelayrReviewed`
+ * skip their prompt for a call identical to one of its
  * calls (account, chain, sender, target, data, value and gas: a call's
  * exact gas limit, or a forward request's signed gas, is set before the
  * review), each spent once, for {@link REVIEWED_PLAN_TTL_MS} after confirm.
@@ -375,38 +379,21 @@ export async function resumeReviewed(record, action, deps) {
         // wallet") or nothing was sent: then the step is reviewed and sent again.
         if (!state.settled && !handle.released(reservation))
             throw new ReviewLineError(REVIEWED_SEQUENCE_UNCERTAIN_LINE);
-        delete saved.sending;
-        delete saved.proposed;
         const { settled } = state;
-        if (settled?.result === "success") {
-            // This sequence's own step: it is recorded, never offered again.
+        // 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);
+        if (settled?.result === "success")
             await handle.acknowledge(settled);
-            saved.completed.push(settled.hash);
-        }
-        /** Tells the site of the step that went through while away, once saved and when its receipt reads. */
-        const told = async () => {
-            if (settled?.result !== "success" || !action.onConfirmed)
-                return;
-            try {
-                const receipt = await deps
-                    .clientFor(call.chainId)
-                    .getTransactionReceipt({ hash: settled.hash });
-                if (receipt.status === "success")
-                    await action.onConfirmed(call, step, receipt);
-            }
-            catch {
-                /* The step went through whatever the read or the site's callback does. */
-            }
-        };
-        if (saved.completed.length === saved.calls.length) {
-            await removeReviewedSequence(saved, storage, expected);
-            await told();
+        if (kept === null) {
             const total = saved.calls.length;
-            deps.onProgress?.({ step: total - 1, total, phase: "done" });
+            tell(deps.onProgress, { step: total - 1, total, phase: "done" });
             return { status: "done", hashes: saved.completed, receipts: [] };
         }
-        expected = await saveReviewedSequence(saved, storage, expected);
-        await told();
+        expected = kept;
     }
     return send({
         ...action,
@@ -415,8 +402,133 @@ export async function resumeReviewed(record, action, deps) {
         scope: saved.scope,
     }, deps, { record: saved, storage, raw: expected });
 }
+/**
+ * Ends `saved`'s step in flight as its hold settled it: a success is
+ * recorded as completed. Removes a finished sequence (null) or saves it over
+ * `expected`, returning the value written.
+ */
+async function recordSending(saved, settled, storage, expected) {
+    delete saved.sending;
+    delete saved.proposed;
+    if (settled?.result === "success")
+        saved.completed.push(settled.hash);
+    if (saved.completed.length < saved.calls.length)
+        return saveReviewedSequence(saved, storage, expected);
+    await removeReviewedSequence(saved, storage, expected);
+    return null;
+}
+/**
+ * The receipt of a step its hold settled ({@link heldReceipt}), checked
+ * before anything advances: a read that fails or disagrees with the hold
+ * throws. Null when the settlement has no transaction (an expiry).
+ */
+async function confirmedReceipt(settled, client, given) {
+    return settled && "hash" in settled
+        ? heldReceipt(settled, client, given)
+        : null;
+}
+/**
+ * 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.
+ */
+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);
+}
+/**
+ * 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
+ * timeout or signal, or when the hold cleared without settling it (its exit).
+ */
+async function followSent(handle, client, reserved, follow) {
+    const stop = new AbortController();
+    const timer = setTimeout(() => stop.abort(), follow.timeoutMs ?? FOLLOW_MS);
+    const signal = follow.signal
+        ? AbortSignal.any([stop.signal, follow.signal])
+        : stop.signal;
+    // Every read races the follow's end: a read that answers after it is ignored.
+    const ended = new Promise((resolve) => {
+        signal.addEventListener("abort", () => resolve(null), { once: true });
+    });
+    const read = (work) => Promise.race([work, ended]);
+    try {
+        while (!signal.aborted) {
+            const state = await read(followHeldWrite(handle, client, { signal }));
+            if (signal.aborted)
+                return null;
+            if (state?.status !== "clear" ||
+                state.reservation !== reserved ||
+                !state.settled ||
+                !("hash" in state.settled))
+                return null;
+            const { settled } = state;
+            try {
+                const receipt = await read(heldReceipt(settled, client));
+                return signal.aborted || !receipt ? null : { settled, receipt };
+            }
+            catch {
+                await pause(RECEIPT_RETRY_MS, signal, () => null).catch(() => null);
+            }
+        }
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Completes a sent step (one a run left at its receipt,
+ * {@link ReviewedReceiptUnverifiedError}, or a proposal: its step and its
+ * `held` call and reservation) once its hold settled that send, as the run
+ * itself would have: the saved sequence under `scope` records it, a success
+ * is told to `onConfirmed` with the receipt its hold verified (`receipt`,
+ * the hold view's, say, when it is that one) and only then acknowledged, the
+ * 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.
+ */
+export async function completeReviewedStep(unverified, action, deps, receipt) {
+    const { step, held } = unverified;
+    if (!held)
+        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)
+        return null;
+    const { settled } = state;
+    const confirmed = await confirmedReceipt(settled, client, receipt);
+    if (action.scope !== undefined) {
+        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")
+        await handle.acknowledge(settled);
+    return { settled, receipt: confirmed };
+}
+/**
+ * The hash a wallet returned, even when the site's record of it failed
+ * afterwards: the step was sent.
+ */
+function sentHash(error) {
+    if (error instanceof SubmittedContractWriteError)
+        return error.hash;
+    throw error;
+}
 async function send(action, deps, resuming) {
-    const { adapter, clientFor, hold, onProgress } = deps;
+    const { adapter, clientFor, hold } = deps;
+    const onProgress = (progress) => tell(deps.onProgress, progress);
     action.guard?.();
     const { account } = action;
     const calls = [...action.calls];
@@ -427,14 +539,7 @@ async function send(action, deps, resuming) {
     /** 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 = async (call, step) => {
-        try {
-            await action.onUnsent?.(call, step);
-        }
-        catch {
-            /* The step is released whatever the site's callback does. */
-        }
-    };
+    const tellUnsent = (call, step) => tell(action.onUnsent, call, step);
     const connected = adapter.account();
     if (!connected)
         throw new ReviewLineError("Connect a wallet first.");
@@ -489,20 +594,12 @@ async function send(action, deps, resuming) {
                     await tellUnsent(call, step);
             throw error;
         }
-        // Every step is told; a site's failure to record it never reads as unsent.
-        const failures = [];
+        // Every step is told; a site's failure to record it never changes what was sent.
         for (const [step, call] of calls.entries())
-            try {
-                await action.onSubmitted?.(call, step, hash, {
-                    safe: false,
-                    adopted: false,
-                });
-            }
-            catch (error) {
-                failures.push(error);
-            }
-        if (failures.length)
-            throw new SubmittedContractWriteError(hash, failures[0]);
+            await tell(action.onSubmitted, call, step, hash, {
+                safe: false,
+                adopted: false,
+            });
         return { status: "done", hashes: [hash], receipts: [] };
     }
     const { scope } = action;
@@ -543,6 +640,10 @@ async function send(action, deps, resuming) {
         if (state.status !== "clear")
             throw new WriteHeldError(state);
     }
+    // So is one whose last success nothing showed: a resend may pay twice.
+    const away = handles[handles.length - 1].unacknowledgedSuccess();
+    if (away)
+        throw new WriteHoldUnacknowledgedSuccessError(away);
     /**
      * Each step's latest reservation as the review opened. Another prompt of
      * the same action that reserved meanwhile, whether or not it has settled,
@@ -615,7 +716,7 @@ async function send(action, deps, resuming) {
             if (!sameCall(now, sent[step]))
                 throw new ReviewLineError(CHANGED);
         });
-        const progress = (phase, hash) => onProgress?.({
+        const progress = (phase, hash) => onProgress({
             step: 0,
             total: calls.length,
             phase,
@@ -623,7 +724,8 @@ async function send(action, deps, resuming) {
         });
         /** The steps whose `beforeWallet` began. */
         let began = 0;
-        const hash = await handles[0].send(client, (gate) => {
+        const hash = await handles[0]
+            .send(client, (gate) => {
             if (generation(handles[0]) !== reviewedGenerations[0]) {
                 throw new WriteHoldStaleReviewError();
             }
@@ -686,19 +788,11 @@ async function send(action, deps, resuming) {
                 onWriteSubmitted: async (submitted) => {
                     gate.afterSubmit(submitted);
                     // Every step went: each is told, whatever an earlier callback does.
-                    const failures = [];
                     for (const [step, call] of calls.entries())
-                        try {
-                            await action.onSubmitted?.(call, step, submitted, {
-                                safe: true,
-                                adopted: false,
-                            });
-                        }
-                        catch (error) {
-                            failures.push(error);
-                        }
-                    if (failures.length)
-                        throw failures[0];
+                        await tell(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 })));
@@ -710,7 +804,8 @@ async function send(action, deps, resuming) {
                 onPhase: (phase) => progress(phase),
                 guard: action.guard,
             });
-        });
+        })
+            .catch(sentHash);
         progress("proposed", hash);
         return { status: "proposed", step: 0, safeTxHash: hash, ...signed };
     }
@@ -759,7 +854,7 @@ async function send(action, deps, resuming) {
         const reviewed = sent[step];
         /** This step's index in the whole action. */
         const at = offset + step;
-        const progress = (phase, hash) => onProgress?.({ step: at, total, phase, ...(hash ? { hash } : {}) });
+        const progress = (phase, hash) => onProgress({ step: at, total, phase, ...(hash ? { hash } : {}) });
         const unchanged = () => {
             let now;
             try {
@@ -786,20 +881,20 @@ async function send(action, deps, resuming) {
             const done = resuming?.record;
             if (step > 0 || !done?.completed.length)
                 return undefined;
-            const { chainId } = done.calls[done.completed.length - 1];
-            // One read: a receipt that can't be read now (a repriced original) is no block.
-            const receipt = await clientFor(chainId)
-                .getTransactionReceipt({
-                hash: done.completed[done.completed.length - 1],
-            })
-                .catch(() => undefined);
-            return receipt
-                ? {
-                    chainId,
-                    blockNumber: receipt.blockNumber,
-                    blockHash: receipt.blockHash,
-                }
-                : undefined;
+            const last = done.calls[done.completed.length - 1];
+            const hash = done.completed[done.completed.length - 1];
+            // Its hold's settlement, while it is still the call's latest, kept
+            // the block it verified; else the hash's receipt, canonical and final.
+            const held = openStepHold(hold, account, adapter.isSafe(), last).peek();
+            const settled = held.status === "clear" &&
+                held.settled &&
+                "hash" in held.settled &&
+                held.settled.hash.toLowerCase() === hash.toLowerCase()
+                ? held.settled
+                : { result: "success", hash };
+            // One try: a block that can't be read or verified now is no block.
+            const block = await heldBlock(settled, clientFor(last.chainId)).catch(() => undefined);
+            return block && { chainId: last.chainId, ...block };
         };
         const priorBlock = call.dependsOnPrior &&
             prior &&
@@ -810,7 +905,12 @@ async function send(action, deps, resuming) {
         let reserved;
         /** A proposal of exactly this call its Safe already queued, sent in its place. */
         let queued;
-        const hash = await handles[step].send(client, (gate) => {
+        /** The caller's end of the run, once this run sent a step. */
+        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;
+        const hash = await handles[step]
+            .send(client, (gate) => {
             // Under the hold's own check of the call, before anything reserves.
             if (generation(handles[step]) !== reviewedGenerations[step]) {
                 throw new WriteHoldStaleReviewError();
@@ -901,6 +1001,10 @@ async function send(action, deps, resuming) {
                     }
                 },
                 beforeSend: () => {
+                    // The caller ended the run (a reset, an unmount) after it sent a
+                    // step: nothing more is sent.
+                    if (hashes.length && action.follow?.signal?.aborted)
+                        throw new TransactionReviewCancelledError();
                     action.assertWriteState?.();
                     unchanged();
                     if (adapter.isSafe() !== safe) {
@@ -919,16 +1023,32 @@ 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 action.onSubmitted?.(call, at, submitted, {
+                    await tell(action.onSubmitted, call, at, submitted, {
                         safe,
                         adopted: !!queued,
                     });
                 },
                 write: async ({ chainId, to, data, value, gas }) => queued?.proposalHash ??
-                    adapter.sendTransaction({ chainId, to, data, value, gas }),
+                    adapter.sendTransaction({
+                        chainId,
+                        to,
+                        data,
+                        value,
+                        gas,
+                        // 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 } : {}),
+                    }),
                 onPhase: (phase) => progress(phase),
                 guard: action.guard,
             });
+        })
+            .catch((error) => {
+            // Refused unsent because the caller ended the run: a cancel, not a failure.
+            if (runEnd?.aborted && error instanceof WalletNotInvokedError)
+                throw new TransactionReviewCancelledError();
+            unrecorded = error;
+            return sentHash(error);
         });
         hashes.push(hash);
         // A later step held under this step's key (the same call, or the same
@@ -950,21 +1070,56 @@ async function send(action, deps, resuming) {
             progress("proposed", hash);
             return { status: "proposed", step: at, safeTxHash: hash, ...signed };
         }
-        progress("receipt", hash);
-        const receipt = await waitForTrackedReceipt(client, hash);
-        // The hold checks the receipt itself and settles, so the same call (or
-        // intent) can be reviewed and sent again without waiting on a view.
-        // Only this send's own reservation's settlement speaks for it: a later
-        // send of the same call or intent may have settled since.
-        const settled = await handles[step]
-            .state(client)
-            .then((state) => state.status === "clear" &&
-            reserved !== undefined &&
-            state.reservation === reserved
-            ? state.settled
-            : undefined)
-            .catch(() => undefined);
-        if (receipt.status === "success" && settled?.result === "failed") {
+        // From here the step was sent: it ends done, failed as its hold
+        // verified, or unverified with what resumes it, never any other way.
+        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,
+        }, cause === undefined ? {} : { cause });
+        // The site could not record the hash: held as sent, for it to resume.
+        if (unrecorded !== undefined)
+            throw unverified(unrecorded);
+        // Its hold's verified settlement is the only word on how it ended: its
+        // result, its transaction (a speed-up's, when the wallet replaced the
+        // send) and that transaction's receipt in the block the hold verified.
+        // A watcher's receipt only says when to ask.
+        let receipt;
+        let settled;
+        try {
+            progress("receipt", hash);
+            const seen = await waitForTrackedReceipt(client, hash);
+            // Only this send's own reservation's settlement speaks for it: a later
+            // send of the same call or intent may have settled since.
+            settled = await handles[step]
+                .state(client)
+                .then((state) => state.status === "clear" &&
+                reserved !== undefined &&
+                state.reservation === reserved &&
+                state.settled &&
+                "hash" in state.settled
+                ? state.settled
+                : undefined)
+                .catch(() => undefined);
+            receipt = settled
+                ? await heldReceipt(settled, client, seen).catch(() => undefined)
+                : undefined;
+            if (!receipt && action.follow) {
+                tell(action.follow.onConfirming, at);
+                const ended = await followSent(handles[step], client, reserved, action.follow);
+                ({ settled, receipt } = ended ?? { settled, receipt });
+            }
+        }
+        catch (error) {
+            throw unverified(error);
+        }
+        if (!settled || !receipt)
+            throw unverified();
+        if (settled.result === "failed" && receipt.status === "success") {
             // It ran, and the hold proved it failed: a Safe's call that failed.
             if (journal) {
                 delete journal.sending;
@@ -972,35 +1127,25 @@ async function send(action, deps, resuming) {
             }
             throw new ReviewLineError(WRITE_HOLD_CALL_FAILED_LINE);
         }
-        // A Safe's execTransaction is done only once its hold proved the Safe's
-        // own success; until then the step stays in flight, held and journaled.
-        if (receipt.status === "success" &&
-            isSafeExecTransaction(reviewed.data) &&
-            settled?.result !== "success") {
-            throw new ReviewLineError(WRITE_HOLD_SAFE_UNCONFIRMED_LINE);
-        }
+        const mined = settled.hash;
+        hashes[hashes.length - 1] = mined;
         if (receipt.status !== "success") {
             // It ran and reverted: nothing of it to resume.
             if (journal) {
                 delete journal.sending;
                 await keep();
             }
-            throw new ReviewedCallRevertedError(at, hash, receipt);
+            throw new ReviewedCallRevertedError(at, mined, receipt);
         }
         receipts.push(receipt);
         if (journal) {
             delete journal.sending;
-            journal.completed.push(hash);
+            journal.completed.push(mined);
             await keep();
         }
-        try {
-            await action.onConfirmed?.(call, at, receipt);
-        }
-        catch {
-            /* The step went through whatever the site's callback does. */
-        }
+        await tellConfirmed(action, handles[step], call, at, settled, receipt);
     }
-    onProgress?.({ step: total - 1, total, phase: "done" });
+    onProgress({ step: total - 1, total, phase: "done" });
     return {
         status: "done",
         hashes: journal ? [...journal.completed] : hashes,