@bananapus/nana-sdk-core 2.38.2 → 2.40.0

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

@@ -0,0 +1,180 @@
+import type { Address, Hex } from "viem";
+import type { WriteHeldState, WriteHold, WriteHoldClient, WriteHoldHandle } from "./writeHold.js";
+import { type HeldWriteStorage, type ReviewedWriteRecoveryInput } from "./writeRecovery.js";
+/** What the app's domain check says of one transaction (or, given none, of a search for the attempt). */
+export type SavedAttemptProof<T> = 
+/** The chain shows this attempt ran, with the app's result (a project ID, a launch). */
+{
+    result: "proven";
+    value: T;
+}
+/** The transaction is some other write. */
+ | {
+    result: "not-this";
+    reason?: string;
+}
+/** It couldn't be read or shown. */
+ | {
+    result: "unknown";
+    reason?: string;
+};
+/** Where a saved attempt was held, and what the app saved of it. Only what was saved: nothing fresh. */
+export type SavedAttemptScope = {
+    chainId: number;
+    /** The account that sent it: the wallet, or the Safe. */
+    account: Address;
+    /** Whether `account` is a Safe; a saved `safeTxHash` says so too. */
+    safe?: boolean;
+    /** Every intent namespace the attempt may be held under, the current one first, legacy ones after. */
+    namespaces: readonly string[];
+    /** The exact saved call, when kept: a saved hash is adopted into the hold against it. */
+    call?: ReviewedWriteRecoveryInput["call"];
+    /**
+     * The app's re-read of its own domain journal, required: awaited under
+     * the hold's locks before any check or exit retirement, it is the final say
+     * of Rule E (only a followed settlement retires a success). Return false,
+     * or throw, while the journal records the attempt's success or can't be
+     * read.
+     */
+    confirmRetirable(): Promise<boolean>;
+    saved?: {
+        /**
+         * The app's send began: the wallet may have opened. Only an explicit
+         * `false`, with no hash or nonce evidence, is proof that nothing was sent.
+         */
+        started?: boolean;
+        /** The transaction hash the wallet returned. */
+        hash?: Hex;
+        /** The Safe proposal the wallet returned. */
+        safeTxHash?: Hex;
+        /** That proposal's Safe nonce, when saved. */
+        safeNonce?: number;
+        /** The account's next nonce before the wallet opened, with the block it was read at. */
+        nonce?: number | bigint;
+        sentNonce?: number | bigint;
+        fromBlock?: bigint;
+        /** When the wallet returned the hash, in milliseconds since the epoch. */
+        submittedAt?: number;
+        /** Settlements already shown before this attempt began: never this attempt's. */
+        before?: readonly Hex[];
+    };
+};
+/** A saved attempt with the app's domain check of a transaction (or, given none, its search for the attempt). */
+export type SavedAttempt<T> = SavedAttemptScope & {
+    authenticate(hash: Hex | undefined): Promise<SavedAttemptProof<T>>;
+};
+/**
+ * What a retirement returned. `durable: false`: it lasts in this tab alone
+ * (show `SAVED_ATTEMPT_TAB_ONLY_LINE`); another tab or a reload asks
+ * again, never sends. `reason: "unreadable"`: the browser has storage but
+ * can't read it, so the warned exit may be offered.
+ */
+export type SavedAttemptRetired = {
+    retired: false;
+    reason?: "unreadable";
+} | {
+    retired: true;
+    durable: boolean;
+};
+/** Why an attempt is retired: the only three things that retire one. */
+export type SavedAttemptRetirement = 
+/** The user's exit released the hold. */
+{
+    by: "exit";
+}
+/**
+ * The user's "I checked it. ..." on exactly this check outcome. With
+ * `force: "unreadable"` (the warned "I checked my wallet. Continue anyway",
+ * offered only after a retirement came back `reason: "unreadable"`), it
+ * retires in this tab alone if the hold's storage still can't be read.
+ */
+ | {
+    by: "check";
+    outcome: SavedAttemptCheck;
+    force?: "unreadable";
+}
+/** The app followed and recorded this settlement. */
+ | {
+    by: "settled";
+    hash?: Hex;
+};
+export type SavedAttemptCheck = {
+    status: "check";
+    /** What couldn't be shown, for logs and details. */
+    reason: string;
+    line: string;
+    warning: string;
+    /** The hold evidence this check evaluated: the user's check retires exactly this. */
+    evidence: string;
+};
+/**
+ * How recovering a saved attempt ended, the one rule every app follows
+ * before any send or discard:
+ * - `held`: the hold still holds the write. Count nothing; show `state`, and
+ *   its exit when due (through `handle`);
+ * - `done`: `success` ran. `authenticated: true` when the app's check showed
+ *   it as this attempt (`value`); `false` when the hold settled it but the
+ *   app's details are unavailable (`reason`): record its `hash` and follow it,
+ *   with "Check again" (recover again) as its only action. Either way, never
+ *   send it again; only `retire({ by: "settled" })` retires it. `failed` is
+ *   the hold's proven revert of it;
+ * - `check`: it can't be shown. One explicit action, "I checked it. ...",
+ *   and only that, retires it (`retire({ by: "check", outcome })`);
+ * - `none`: the hold proves nothing was reserved and nothing saved says it
+ *   was sent, or the attempt was retired (`retired`): by the user or a
+ *   followed settlement, or by the SDK itself when it dropped every
+ *   reservation of it on a definite wallet rejection or an abort before the
+ *   wallet opened (`"rejected"`: nothing can have been sent).
+ */
+export type SavedAttemptOutcome<T> = {
+    status: "held";
+    state: WriteHeldState;
+    handle: WriteHoldHandle;
+} | {
+    status: "done";
+    result: "success";
+    authenticated: true;
+    hash?: Hex;
+    value: T;
+} | {
+    status: "done";
+    result: "success";
+    authenticated: false;
+    /** The settled transaction; absent when another tab's check proved it without one. */
+    hash?: Hex;
+    reason: string;
+} | {
+    status: "done";
+    result: "failed";
+    hash: Hex;
+} | SavedAttemptCheck | {
+    status: "none";
+    retired?: SavedAttemptRetirement["by"] | "rejected";
+};
+/**
+ * Saved-attempt recovery over the app's write hold, framework-free: every
+ * app's launches, linked plans, shop updates and other saved writes recover
+ * the same way. Pass the hold's own `storage` and `locks` when it was made
+ * with custom ones; the defaults are the hold's defaults.
+ *
+ * - Recovery needs only what was saved: run it right after a saved attempt is
+ *   found, before any fresh-send preparation.
+ * - Absence of evidence is `check`, never `none`: a missing hold record, a
+ *   refused or unreadable adoption, an empty search and every exception.
+ * - A settled success always wins: it is never downgraded by a later failed
+ *   or empty read, and it blocks discard until followed.
+ * - Only the user's exit, the user's check action, a followed settlement and
+ *   the SDK's own drop of a rejected reservation retire an attempt, persisted under the hold's locks for every tab and
+ *   reload, and only for the hold evidence they saw.
+ */
+export declare function createSavedAttemptRecovery(options: {
+    hold: WriteHold;
+    storage?: HeldWriteStorage;
+    locks?: Pick<LockManager, "request">;
+}): {
+    recover: <T>(attempt: SavedAttempt<T>, client: WriteHoldClient) => Promise<SavedAttemptOutcome<T>>;
+    retire: (attempt: SavedAttemptScope, reason: SavedAttemptRetirement) => Promise<SavedAttemptRetired>;
+    canDiscard: (attempt: SavedAttemptScope) => boolean;
+};
+export type SavedAttemptRecovery = ReturnType<typeof createSavedAttemptRecovery>;
+//# sourceMappingURL=savedAttempt.d.ts.map

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

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