@bananapus/nana-sdk-core 2.31.0 → 2.33.0

package/dist/cjs/review/index.d.ts

@@ -6,4 +6,5 @@ export * from "./simulation.js";
 export * from "./transactionReview.js";
 export * from "./transaction-message.js";
 export * from "./writeRecovery.js";
+export * from "./writeHold.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/cjs/review/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/review/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/review/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC"}

package/dist/cjs/review/index.js

@@ -22,4 +22,5 @@ __exportStar(require("./simulation.js"), exports);
 __exportStar(require("./transactionReview.js"), exports);
 __exportStar(require("./transaction-message.js"), exports);
 __exportStar(require("./writeRecovery.js"), exports);
+__exportStar(require("./writeHold.js"), exports);
 //# sourceMappingURL=index.js.map

package/dist/cjs/review/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/review/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,qDAAmC;AACnC,2CAAyB;AACzB,gDAA8B;AAC9B,+CAA6B;AAC7B,kDAAgC;AAChC,yDAAuC;AACvC,2DAAyC;AACzC,qDAAmC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/review/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,qDAAmC;AACnC,2CAAyB;AACzB,gDAA8B;AAC9B,+CAA6B;AAC7B,kDAAgC;AAChC,yDAAuC;AACvC,2DAAyC;AACzC,qDAAmC;AACnC,iDAA+B"}

package/dist/cjs/review/messages.d.ts

@@ -39,5 +39,23 @@ export declare const SAFE_PROPOSAL_REPLACED_LINE = "Another Safe transaction use
 export declare const SAFE_PROPOSAL_EXECUTED_LINE = "Your Safe ran this transaction.";
 /** A quote released after its payment failed and its deadline passed. */
 export declare const RELAYR_PAYMENT_RELEASED_LINE = "Your payment didn't go through and its quote expired. Pay a new quote.";
+/** The review's line while held writes last only until this tab closes or reloads. */
+export declare const WRITE_HOLD_IN_TAB_LINE = "This browser can't remember pending transactions. Check your wallet before repeating one.";
+/** A held write whose saved hash is still pending: no exit, the wallet ends it. */
+export declare const WRITE_HOLD_PENDING_LINE = "Still pending in your wallet. Speed it up or cancel it there.";
+/** A write that reverted onchain, held until that is final so a retry can't double it. */
+export declare const WRITE_HOLD_REVERTED_LINE = "This transaction failed onchain. You can try again in a few minutes.";
+/** A held write the chain can't check (saved with no nonce to look at). The exit is offered. */
+export declare const WRITE_HOLD_UNCHECKED_LINE = "This transaction can't be checked onchain. Check your wallet before sending again.";
+/** A send stopped before the wallet because the account's nonce couldn't be read. */
+export declare const WRITE_HOLD_NONCE_LINE = "Couldn't read your account from the network, so nothing was sent. Try again in a moment.";
+/** The warning on the exit of a held write that has a hash. */
+export declare const WRITE_HOLD_HASHED_EXIT_LINE = "If that transaction is still in your wallet, sending again can run it twice.";
+/** A held Safe write whose nonce another Safe transaction used. The exit is offered. */
+export declare const WRITE_HOLD_SAFE_REPLACED_LINE = "Another Safe transaction used this nonce. Check your Safe, then send again.";
+/** A held write the app's effect read shows done. Nothing is released on that alone; the exit is offered. */
+export declare const WRITE_HOLD_LOOKS_DONE_LINE = "This looks done. Check your wallet, then continue.";
+/** A held Safe write whose follower ended without proof. The exit is offered. */
+export declare const WRITE_HOLD_SAFE_UNPROVEN_LINE = "This Safe transaction couldn't be confirmed here. Check your Safe, then send again.";
 export {};
 //# sourceMappingURL=messages.d.ts.map

package/dist/cjs/review/messages.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../../../src/review/messages.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,4FAA4F;AAC5F,KAAK,aAAa,GAAG,KAAK,GAAG,SAAS,GAAG,SAAS,CAAC;AAEnD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,MAAM,EACb,EACE,MAAiB,EACjB,KAAkB,EAClB,UAA0D,GAC3D,GAAE;IACD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC;CAChC,GACL,MAAM,CAIR;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,aAAa,EACrB,EACE,MAAiB,EACjB,OAAmB,EACnB,gBAAwB,GACzB,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAAO,GACxE,MAAM,CAOR;AAED,wEAAwE;AACxE,wBAAgB,gBAAgB,CAAC,MAAM,SAAgB,GAAG,MAAM,CAE/D;AAED,4EAA4E;AAC5E,eAAO,MAAM,gBAAgB,oCAAoC,CAAC;AAElE,8DAA8D;AAC9D,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,EACjC,MAAM,SAAgB,GACrB,MAAM,CAIR;AAED,iEAAiE;AACjE,eAAO,MAAM,2BAA2B,0EACiC,CAAC;AAE1E,gDAAgD;AAChD,eAAO,MAAM,2BAA2B,oCAAoC,CAAC;AAE7E,yEAAyE;AACzE,eAAO,MAAM,4BAA4B,2EACiC,CAAC"}
+{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../../../src/review/messages.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,4FAA4F;AAC5F,KAAK,aAAa,GAAG,KAAK,GAAG,SAAS,GAAG,SAAS,CAAC;AAEnD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,MAAM,EACb,EACE,MAAiB,EACjB,KAAkB,EAClB,UAA0D,GAC3D,GAAE;IACD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC;CAChC,GACL,MAAM,CAIR;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,aAAa,EACrB,EACE,MAAiB,EACjB,OAAmB,EACnB,gBAAwB,GACzB,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAAO,GACxE,MAAM,CAOR;AAED,wEAAwE;AACxE,wBAAgB,gBAAgB,CAAC,MAAM,SAAgB,GAAG,MAAM,CAE/D;AAED,4EAA4E;AAC5E,eAAO,MAAM,gBAAgB,oCAAoC,CAAC;AAElE,8DAA8D;AAC9D,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,EACjC,MAAM,SAAgB,GACrB,MAAM,CAIR;AAED,iEAAiE;AACjE,eAAO,MAAM,2BAA2B,0EACiC,CAAC;AAE1E,gDAAgD;AAChD,eAAO,MAAM,2BAA2B,oCAAoC,CAAC;AAE7E,yEAAyE;AACzE,eAAO,MAAM,4BAA4B,2EACiC,CAAC;AAE3E,sFAAsF;AACtF,eAAO,MAAM,sBAAsB,8FAC0D,CAAC;AAE9F,mFAAmF;AACnF,eAAO,MAAM,uBAAuB,kEAC6B,CAAC;AAElE,0FAA0F;AAC1F,eAAO,MAAM,wBAAwB,yEACmC,CAAC;AAEzE,gGAAgG;AAChG,eAAO,MAAM,yBAAyB,uFACgD,CAAC;AAEvF,qFAAqF;AACrF,eAAO,MAAM,qBAAqB,6FAC0D,CAAC;AAE7F,+DAA+D;AAC/D,eAAO,MAAM,2BAA2B,iFACwC,CAAC;AAEjF,wFAAwF;AACxF,eAAO,MAAM,6BAA6B,gFACqC,CAAC;AAEhF,6GAA6G;AAC7G,eAAO,MAAM,0BAA0B,uDACe,CAAC;AAEvD,iFAAiF;AACjF,eAAO,MAAM,6BAA6B,wFAC6C,CAAC"}

package/dist/cjs/review/messages.js

@@ -5,7 +5,7 @@
  * `action` is a noun such as "action", "launch" or "payment".
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RELAYR_PAYMENT_RELEASED_LINE = exports.SAFE_PROPOSAL_EXECUTED_LINE = exports.SAFE_PROPOSAL_REPLACED_LINE = exports.WRITE_EXIT_LABEL = void 0;
+exports.WRITE_HOLD_SAFE_UNPROVEN_LINE = exports.WRITE_HOLD_LOOKS_DONE_LINE = exports.WRITE_HOLD_SAFE_REPLACED_LINE = exports.WRITE_HOLD_HASHED_EXIT_LINE = exports.WRITE_HOLD_NONCE_LINE = exports.WRITE_HOLD_UNCHECKED_LINE = exports.WRITE_HOLD_REVERTED_LINE = exports.WRITE_HOLD_PENDING_LINE = exports.WRITE_HOLD_IN_TAB_LINE = exports.RELAYR_PAYMENT_RELEASED_LINE = exports.SAFE_PROPOSAL_EXECUTED_LINE = exports.SAFE_PROPOSAL_REPLACED_LINE = exports.WRITE_EXIT_LABEL = void 0;
 exports.relayrHeldMessage = relayrHeldMessage;
 exports.relayrDiscardLine = relayrDiscardLine;
 exports.writeHeldMessage = writeHeldMessage;
@@ -52,4 +52,22 @@ exports.SAFE_PROPOSAL_REPLACED_LINE = "Another Safe transaction used this nonce.
 exports.SAFE_PROPOSAL_EXECUTED_LINE = "Your Safe ran this transaction.";
 /** A quote released after its payment failed and its deadline passed. */
 exports.RELAYR_PAYMENT_RELEASED_LINE = "Your payment didn't go through and its quote expired. Pay a new quote.";
+/** The review's line while held writes last only until this tab closes or reloads. */
+exports.WRITE_HOLD_IN_TAB_LINE = "This browser can't remember pending transactions. Check your wallet before repeating one.";
+/** A held write whose saved hash is still pending: no exit, the wallet ends it. */
+exports.WRITE_HOLD_PENDING_LINE = "Still pending in your wallet. Speed it up or cancel it there.";
+/** A write that reverted onchain, held until that is final so a retry can't double it. */
+exports.WRITE_HOLD_REVERTED_LINE = "This transaction failed onchain. You can try again in a few minutes.";
+/** A held write the chain can't check (saved with no nonce to look at). The exit is offered. */
+exports.WRITE_HOLD_UNCHECKED_LINE = "This transaction can't be checked onchain. Check your wallet before sending again.";
+/** A send stopped before the wallet because the account's nonce couldn't be read. */
+exports.WRITE_HOLD_NONCE_LINE = "Couldn't read your account from the network, so nothing was sent. Try again in a moment.";
+/** The warning on the exit of a held write that has a hash. */
+exports.WRITE_HOLD_HASHED_EXIT_LINE = "If that transaction is still in your wallet, sending again can run it twice.";
+/** A held Safe write whose nonce another Safe transaction used. The exit is offered. */
+exports.WRITE_HOLD_SAFE_REPLACED_LINE = "Another Safe transaction used this nonce. Check your Safe, then send again.";
+/** A held write the app's effect read shows done. Nothing is released on that alone; the exit is offered. */
+exports.WRITE_HOLD_LOOKS_DONE_LINE = "This looks done. Check your wallet, then continue.";
+/** A held Safe write whose follower ended without proof. The exit is offered. */
+exports.WRITE_HOLD_SAFE_UNPROVEN_LINE = "This Safe transaction couldn't be confirmed here. Check your Safe, then send again.";
 //# sourceMappingURL=messages.js.map

package/dist/cjs/review/messages.js.map

@@ -1 +1 @@
-{"version":3,"file":"messages.js","sourceRoot":"","sources":["../../../src/review/messages.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAUH,8CAeC;AAOD,8CAcC;AAGD,4CAEC;AAMD,4CAOC;AA3DD;;;;GAIG;AACH,SAAgB,iBAAiB,CAC/B,KAAa,EACb,EACE,MAAM,GAAG,QAAQ,EACjB,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,EAClB,UAAU,GAAG,CAAC,EAAU,EAAE,EAAE,CAAC,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC,cAAc,EAAE,MAKxD,EAAE;IAEN,OAAO,KAAK,GAAG,KAAK,GAAG,KAAK;QAC1B,CAAC,CAAC,QAAQ,MAAM,4CAA4C,UAAU,CAAC,KAAK,GAAG,KAAK,CAAC,yBAAyB;QAC9G,CAAC,CAAC,QAAQ,MAAM,iEAAiE,CAAC;AACtF,CAAC;AAED;;;;GAIG;AACH,SAAgB,iBAAiB,CAC/B,MAAqB,EACrB,EACE,MAAM,GAAG,QAAQ,EACjB,OAAO,GAAG,SAAS,EACnB,gBAAgB,GAAG,KAAK,MAC6C,EAAE;IAEzE,IAAI,MAAM,KAAK,KAAK;QAClB,OAAO,QAAQ,MAAM,wDAAwD,OAAO,uCAAuC,CAAC;IAC9H,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,OAAO,OAAO,6BAA6B,CAAC;IAC7E,OAAO,gBAAgB;QACrB,CAAC,CAAC,iDAAiD,MAAM,qDAAqD;QAC9G,CAAC,CAAC,QAAQ,MAAM,gDAAgD,CAAC;AACrE,CAAC;AAED,wEAAwE;AACxE,SAAgB,gBAAgB,CAAC,MAAM,GAAG,aAAa;IACrD,OAAO,gBAAgB,MAAM,2CAA2C,CAAC;AAC3E,CAAC;AAED,4EAA4E;AAC/D,QAAA,gBAAgB,GAAG,iCAAiC,CAAC;AAElE,8DAA8D;AAC9D,SAAgB,gBAAgB,CAC9B,IAAiC,EACjC,MAAM,GAAG,aAAa;IAEtB,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,EAAE;QACjC,CAAC,CAAC,mBAAmB,MAAM,0CAA0C;QACrE,CAAC,CAAC,mBAAmB,MAAM,6CAA6C,CAAC;AAC7E,CAAC;AAED,iEAAiE;AACpD,QAAA,2BAA2B,GACtC,uEAAuE,CAAC;AAE1E,gDAAgD;AACnC,QAAA,2BAA2B,GAAG,iCAAiC,CAAC;AAE7E,yEAAyE;AAC5D,QAAA,4BAA4B,GACvC,wEAAwE,CAAC"}
+{"version":3,"file":"messages.js","sourceRoot":"","sources":["../../../src/review/messages.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAUH,8CAeC;AAOD,8CAcC;AAGD,4CAEC;AAMD,4CAOC;AA3DD;;;;GAIG;AACH,SAAgB,iBAAiB,CAC/B,KAAa,EACb,EACE,MAAM,GAAG,QAAQ,EACjB,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,EAClB,UAAU,GAAG,CAAC,EAAU,EAAE,EAAE,CAAC,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC,cAAc,EAAE,MAKxD,EAAE;IAEN,OAAO,KAAK,GAAG,KAAK,GAAG,KAAK;QAC1B,CAAC,CAAC,QAAQ,MAAM,4CAA4C,UAAU,CAAC,KAAK,GAAG,KAAK,CAAC,yBAAyB;QAC9G,CAAC,CAAC,QAAQ,MAAM,iEAAiE,CAAC;AACtF,CAAC;AAED;;;;GAIG;AACH,SAAgB,iBAAiB,CAC/B,MAAqB,EACrB,EACE,MAAM,GAAG,QAAQ,EACjB,OAAO,GAAG,SAAS,EACnB,gBAAgB,GAAG,KAAK,MAC6C,EAAE;IAEzE,IAAI,MAAM,KAAK,KAAK;QAClB,OAAO,QAAQ,MAAM,wDAAwD,OAAO,uCAAuC,CAAC;IAC9H,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,OAAO,OAAO,6BAA6B,CAAC;IAC7E,OAAO,gBAAgB;QACrB,CAAC,CAAC,iDAAiD,MAAM,qDAAqD;QAC9G,CAAC,CAAC,QAAQ,MAAM,gDAAgD,CAAC;AACrE,CAAC;AAED,wEAAwE;AACxE,SAAgB,gBAAgB,CAAC,MAAM,GAAG,aAAa;IACrD,OAAO,gBAAgB,MAAM,2CAA2C,CAAC;AAC3E,CAAC;AAED,4EAA4E;AAC/D,QAAA,gBAAgB,GAAG,iCAAiC,CAAC;AAElE,8DAA8D;AAC9D,SAAgB,gBAAgB,CAC9B,IAAiC,EACjC,MAAM,GAAG,aAAa;IAEtB,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,EAAE;QACjC,CAAC,CAAC,mBAAmB,MAAM,0CAA0C;QACrE,CAAC,CAAC,mBAAmB,MAAM,6CAA6C,CAAC;AAC7E,CAAC;AAED,iEAAiE;AACpD,QAAA,2BAA2B,GACtC,uEAAuE,CAAC;AAE1E,gDAAgD;AACnC,QAAA,2BAA2B,GAAG,iCAAiC,CAAC;AAE7E,yEAAyE;AAC5D,QAAA,4BAA4B,GACvC,wEAAwE,CAAC;AAE3E,sFAAsF;AACzE,QAAA,sBAAsB,GACjC,2FAA2F,CAAC;AAE9F,mFAAmF;AACtE,QAAA,uBAAuB,GAClC,+DAA+D,CAAC;AAElE,0FAA0F;AAC7E,QAAA,wBAAwB,GACnC,sEAAsE,CAAC;AAEzE,gGAAgG;AACnF,QAAA,yBAAyB,GACpC,oFAAoF,CAAC;AAEvF,qFAAqF;AACxE,QAAA,qBAAqB,GAChC,0FAA0F,CAAC;AAE7F,+DAA+D;AAClD,QAAA,2BAA2B,GACtC,8EAA8E,CAAC;AAEjF,wFAAwF;AAC3E,QAAA,6BAA6B,GACxC,6EAA6E,CAAC;AAEhF,6GAA6G;AAChG,QAAA,0BAA0B,GACrC,oDAAoD,CAAC;AAEvD,iFAAiF;AACpE,QAAA,6BAA6B,GACxC,qFAAqF,CAAC"}

package/dist/cjs/review/writeHold.d.ts

@@ -0,0 +1,211 @@
+import { type Hex, type PublicClient, type TransactionReceipt } from "viem";
+import { type SafeQueuedTransaction, type SafeServiceOptions } from "../safeService.js";
+import { verifyReviewedWriteReceipt, type HeldWriteStorage, type ReviewedWriteRecoveryInput, type ReviewedWriteRecoveryRecord } from "./writeRecovery.js";
+/** The reads a write hold makes on the call's chain; a viem PublicClient satisfies it. */
+export type WriteHoldClient = Pick<PublicClient, "getBlock" | "getBlockNumber" | "getChainId" | "getTransaction" | "getTransactionCount" | "getTransactionReceipt" | "request">;
+/** How a held write ended, when the hold saw it end. */
+export type WriteHoldSettled = 
+/** Its verified receipt (a revert only once final). */
+{
+    result: "success" | "failed";
+    hash: Hex;
+}
+/** A Safe proposal's expiry before it ran is proven. */
+ | {
+    result: "expired";
+};
+type Held<S extends string, Extra> = {
+    status: S;
+    /** The record this state was read from: the identity an exit must name. */
+    record: ReviewedWriteRecoveryRecord;
+    /** The one line the app shows for it. */
+    line: string;
+} & Extra;
+/**
+ * What a write hold says about one exact call, from {@link WriteHold.state}:
+ *
+ * - `clear`: nothing is held; `settled` says how a hold just ended;
+ * - `pending-known-hash`: its saved hash (or Safe proposal) can still run. No
+ *   exit: the wallet speeds it up or cancels it;
+ * - `held-no-hash`: the wallet never returned a hash. The exit is offered;
+ * - `dropped-proven`: the node doesn't know the saved hash and a canonical
+ *   finalized block shows another transaction ran at the nonce it was
+ *   actually sent at (`sentNonce`, from its authenticated transaction; the
+ *   nonce read before the wallet opened only locates the call). The exit is
+ *   offered;
+ * - `held-unchecked`: a saved hash the node doesn't know, on a record saved
+ *   with no nonce to check, or 30 minutes after the wallet returned it (or,
+ *   for a record saved before that time was kept, after it was first read). The
+ *   exit is offered, with a line that says so; a hash that shows up later is
+ *   followed as usual. A Safe proposal Safe's service never authenticates
+ *   gets it after the same 30 minutes. Its `warning` says a resend can run it
+ *   twice;
+ * - `safe-replaced`: another Safe transaction used a Safe write's nonce (or
+ *   the executor's, for an execution returned at once). It may have run the
+ *   call too, so it is never released on its own: the exit is offered at
+ *   once, with its `warning`;
+ * - `safe-unproven`: the app's Safe follower ended without proof
+ *   ({@link WriteHoldHandle.onUnproven}). The exit is offered at once, with
+ *   its `warning`; authenticated evidence that arrives later still settles it;
+ * - `looks-done`: the app's effect read shows the call took effect. Nothing
+ *   is released on that alone: its line says so, and the exit is offered at
+ *   once (with the `warning` when it has a hash);
+ * - `ran-executed`: the chain shows it ran (a Safe execution, or a revert
+ *   not final yet). It is kept until its result settles it, and never offered
+ *   a resend.
+ */
+export type WriteHoldState = {
+    status: "clear";
+    settled?: WriteHoldSettled;
+} | Held<"pending-known-hash", {
+    hash: Hex;
+    exit: false;
+}> | Held<"held-no-hash", {
+    exit: true;
+}> | Held<"dropped-proven", {
+    hash: Hex;
+    usedBy: Hex;
+    exit: true;
+    warning: string;
+}> | Held<"held-unchecked", {
+    hash: Hex;
+    exit: true;
+    warning: string;
+}> | Held<"safe-replaced", {
+    hash: Hex;
+    exit: true;
+    warning: string;
+}> | Held<"safe-unproven", {
+    hash: Hex;
+    exit: true;
+    warning: string;
+}> | Held<"looks-done", {
+    hash?: Hex;
+    exit: true;
+    warning?: string;
+}> | Held<"ran-executed", {
+    executionHash?: Hex;
+    result?: "failed";
+    exit: false;
+}>;
+/** Any state but `clear`. */
+export type WriteHeldState = Exclude<WriteHoldState, {
+    status: "clear";
+}>;
+/** A send was refused because the exact call is held; `state` says how. */
+export declare class WriteHeldError extends Error {
+    readonly state: WriteHeldState;
+    readonly name = "WriteHeldError";
+    constructor(state: WriteHeldState);
+}
+/** The account's nonce couldn't be read, so the wallet never opened. */
+export declare class WriteHoldNonceError extends Error {
+    readonly cause: unknown;
+    readonly name = "WriteHoldNonceError";
+    constructor(cause: unknown);
+}
+/** The exact call is already being sent from another flow or tab. */
+export declare class WriteHoldBusyError extends Error {
+    readonly name = "WriteHoldBusyError";
+    constructor();
+}
+/** The callbacks a send hands its wallet boundary (`submitReviewedContractWrite`). */
+export type WriteHoldGate = {
+    /**
+     * Hold the call right before the wallet opens: `beforeWrite`. It reads the
+     * account's next nonce for later proof, rechecks, and throws
+     * {@link WriteHeldError} if the call became held meanwhile. `actualCall`:
+     * a reused Safe proposal's exact call.
+     */
+    beforeSend(actualCall?: ReviewedWriteRecoveryInput["call"]): Promise<void>;
+    /** The wallet returned this hash (a Safe proposal's safeTxHash): `onWriteSubmitted`. */
+    afterSubmit(hash: Hex, proposal?: SafeQueuedTransaction): void;
+    /** Nothing reached the wallet, or it refused: `onWriteRejected` and `onBeforeWriteAborted`. */
+    onRejected(): void;
+};
+type Locks = Pick<LockManager, "request">;
+/**
+ * One controller for held wallet writes, framework-free: every app wires its
+ * send, receipt and exit through it, so nothing is ever sent twice.
+ *
+ * - Holds live in the browser's storage, shared by tabs and kept across
+ *   reloads, or in this tab's memory where storage is refused
+ *   ({@link createHeldWriteStorage}); {@link reviewLine} is then the line the
+ *   review shows. The wallet never opens without a hold.
+ * - A send checks, reserves and hands the call to the wallet under one lock
+ *   per exact call (Web Locks, or the SDK's fallback), so two flows or tabs
+ *   can never both reserve it.
+ * - A verified successful receipt releases at once. A revert holds until a
+ *   canonical finalized block includes it. A Safe proposal proven executed
+ *   is kept through reload until its execution's receipt settles it; one
+ *   proven expired releases. One another Safe transaction replaced is never
+ *   released on its own: the user's exit ends it.
+ */
+export declare function createWriteHold(options?: {
+    storage?: HeldWriteStorage;
+    locks?: Locks;
+    safeService?: SafeServiceOptions;
+    /** How often, and how many times, a ran write is looked at again until it settles. */
+    settle?: {
+        intervalMs?: number;
+        attempts?: number;
+    };
+}): {
+    open: (call: ReviewedWriteRecoveryInput) => {
+        state: (client: WriteHoldClient, checks?: {
+            effect?: (chainId: number) => Promise<boolean>;
+        }) => Promise<WriteHoldState>;
+        /** What the saved record alone says, without asking the chain. */
+        peek: () => WriteHoldState;
+        /** Every state this controller reads or makes for the call, and other tabs' changes. */
+        subscribe(listener: (state: WriteHoldState) => void): () => void;
+        /**
+         * Send the call under its hold. A held call throws
+         * {@link WriteHeldError} before anything opens, and another flow or tab
+         * sending it throws {@link WriteHoldBusyError}. `run` hands the
+         * {@link WriteHoldGate} to its wallet boundary. A write that may have
+         * reached the wallet stays held whatever `run` throws.
+         */
+        send<T>(client: WriteHoldClient, run: (gate: WriteHoldGate) => Promise<T>): Promise<T>;
+        /**
+         * The user checked their wallet. Only an exit-offered `snapshot`, the
+         * state the user saw, is released, after the chain is asked once more:
+         * any change refuses it, and a confirmation that landed meanwhile wins.
+         * `released` true: send again.
+         */
+        exit(snapshot: WriteHoldState, acknowledgement: {
+            checkedWallet: true;
+        }, client: WriteHoldClient): Promise<{
+            released: boolean;
+            state: WriteHoldState;
+        }>;
+        /**
+         * A receipt for the held write: an ordinary write's own hash, or a Safe
+         * proposal's execution (`proof`: its whole batch). It releases only once
+         * verified, and a revert only once final.
+         */
+        onReceipt(receipt: TransactionReceipt, client: WriteHoldClient, proof?: Parameters<typeof verifyReviewedWriteReceipt>[3]): Promise<WriteHoldState>;
+        /**
+         * The app's Safe follower ended without proof (its watch gave up, or
+         * the service lost the proposal). `proposalHash`, when given, must name
+         * the held one. It is held with the exit at once, through reloads;
+         * authenticated evidence that arrives later still settles it.
+         */
+        onUnproven(client: WriteHoldClient, proposalHash?: Hex): Promise<WriteHoldState>;
+        /**
+         * The app's own proof that the held Safe proposal ran, with its
+         * execution's transaction when known. Kept until its result settles it.
+         */
+        onExecuted(client: WriteHoldClient, executionHash?: Hex): Promise<WriteHoldState>;
+    };
+    /** Whether holds outlive this tab right now. */
+    durable: () => boolean;
+    /** The review's line while holds last only in this tab, or null. */
+    reviewLine: () => "This browser can't remember pending transactions. Check your wallet before repeating one." | null;
+    /** Stop every settle poll and the tab listener (tests, teardown). */
+    dispose(): void;
+};
+export type WriteHold = ReturnType<typeof createWriteHold>;
+export type WriteHoldHandle = ReturnType<WriteHold["open"]>;
+export {};
+//# sourceMappingURL=writeHold.d.ts.map

package/dist/cjs/review/writeHold.d.ts.map

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