/** * `@rocketh/unknown-signer` — what happens when rocketh cannot sign, at the CALL site. * * Two wrappers, both scoping the unknown-signer policy to ONE action through the same * push/pop policy frame on the environment: `catchUnknownSigner` (the hardhat-deploy v1 * helper: force the throw path and hand the transaction back) and * `withUnknownSignerPolicy` (choose the policy for one call, within what the run can * actually do). * * Wrap a privileged call whose `from` is an account rocketh cannot sign for (a Safe * multisig, a hardware wallet left unplugged, an air-gapped or governance key) and * instead of halting the run you get back the exact transaction to execute * out-of-band. Execute it on your Safe, then re-run the idempotent script: the * on-chain state check sees the change and skips the completed step. * * ```typescript * import {catchUnknownSigner} from '@rocketh/unknown-signer'; * import {execute} from '@rocketh/read-execute'; * * const deferred = await catchUnknownSigner(env)(() => * execute(env)(proxy, {account: 'safeOwner', functionName: 'upgradeTo', args: [newImpl.address]}), * ); * if (deferred) { * // {from, to, value, data} — execute this on the Safe, then re-run. * } * ``` * * ONE WRAPPER CAPTURES ONE TRANSACTION. The error unwinds the wrapped action, so the * FIRST unsignable transaction inside it is the one you get back and everything after * it in that action is skipped. Deferring several steps means one * `catchUnknownSigner` per step. * * NOTHING IS PERSISTED. There is no unsigned-transactions file and no other side * effect, exactly like v1: idempotency comes from on-chain state alone. * * SCOPE OF THE POLICY FRAME (ADR 0006). The frame this wrapper pushes forces `throw` * over `ask` (the interactive policy), NEVER over impersonation. An account the node * can sign for — including one `autoImpersonate` took on — is signable, full stop, and * still BROADCASTS inside the wrapper. That is what keeps a mixed run working, and it * is why testing the throw path on a fork is done with * `autoImpersonate: false` for the run. * * The frame stack is dynamic scope, which suits how rocketh runs deploy scripts * (sequentially, one await at a time). Running `Promise.all` of two actions inside one * wrapper leaks the frame to the concurrent action, which under an ambient `'ask'` * policy means that concurrent action throws where it would have prompted. Recorded as * a known limitation in ADR 0006. * * DECISION — the per-call override is a WRAPPER (`withUnknownSignerPolicy`) in this * package, not an option on `deploy` / `execute` / `tx`. It reuses the frame stack the * seam already reads, so precedence stays ONE rule (innermost frame, else the run's * `onUnknownSigner`) and no extension package's options bag has to grow a policy field * that each would then thread to the choke point separately. The alternative, an * `onUnknownSigner` option on every call site, was rejected on that duplication: it * would put the same decision in four packages and make "which one wins" a second * precedence rule. The cost of this shape is that the override is written around the * call rather than inside it, and that it lives in the package a user installs for * `catchUnknownSigner`. Frames nest LIFO, so an override written INSIDE a * `catchUnknownSigner` wins over the wrapper's own frame: the deferral guarantee is * about the AMBIENT policy, not about an override the same script deliberately asked * for. See the `## Decisions` block of * `work/tasks/done/per-call-ask-override-and-deferral-precedence.md`. */ import type { Environment, UnknownSignerPolicy } from '@rocketh/core/types'; /** * What a caught unknown signer gives you back: the transaction to execute * out-of-band. The shape is hardhat-deploy v1's, so a migrated script that reads, * compares or forwards this object needs no change — every key is PRESENT even when * its value is `undefined` (v1 returned a destructure), and `value` is a string. * * `contract` is deliberately absent: it exists only to enrich the printed message. That * includes the called function's ABI, which is printed for a Safe's Transaction Builder * and is NOT a key here: adding one would break v1 parity for a script that compares or * forwards this object. */ export type CaughtUnknownSignerTransaction = { from: string; to?: string; value?: string; data?: string; }; export type CatchUnknownSignerOptions = { /** Print the transaction to execute. Defaults to `true`, as in v1. */ log?: boolean; }; /** * The action to run. * * DELIBERATE DIVERGENCE FROM v1, and the only one: v1 accepted * `Promise | (() => Promise)`; here it is a THUNK only. A promise argument has * already started executing before this wrapper is called, so there is no moment at * which to push the policy frame, and accepting it would produce a wrapper that * silently does not do its job. Migrating a v1 script is therefore the import plus * one mechanical change: `catchUnknownSigner(execute(...))` becomes * `catchUnknownSigner(() => execute(...))`. */ export type UnknownSignerAction = () => Promise | T; export type CatchUnknownSignerFunction = (action: UnknownSignerAction, options?: CatchUnknownSignerOptions) => Promise; export type WithUnknownSignerPolicyFunction = (policy: UnknownSignerPolicy, action: UnknownSignerAction) => Promise; /** * Choose the unknown-signer policy for ONE action, overriding the run's own * (`onUnknownSigner`, itself resolved as run parameter > chain config > `'auto'`). * * ```typescript * import {withUnknownSignerPolicy} from '@rocketh/unknown-signer'; * * // on a fork whose run-level policy is 'throw': rehearse the interactive flow, once * const receipt = await withUnknownSignerPolicy(env)('ask', () => * execute(env)(proxy, {account: 'safeOwner', functionName: 'upgradeTo', args: [next.address]}), * ); * ``` * * It is the SAME mechanism `catchUnknownSigner` uses — a policy frame pushed on the * environment for the duration of the action — so the precedence is one rule rather * than two: the innermost frame wins, and with no frame the run's policy applies. * Whatever the action returns is handed back, and whatever it throws propagates (a * deferral under `'throw'` therefore throws `UnknownSignerError`, catchable by * wrapping this in `catchUnknownSigner`). * * CAPABILITY IS A CEILING, NOT A DEFAULT (ADR 0007). Asking for `'ask'` here can only * choose among what the run can already do: where the run cannot ask a human for text * (`env.canPromptForText()` is false — CI, a non-TTY shell, the browser) it degrades * to `'throw'` and nobody is prompted. A script that hardcodes the override therefore * still runs, un-hangable, in CI. * * WHAT IT DOES NOT DO: it never turns a SIGNABLE account into a throw, and never * defeats impersonation. The policy is read only inside the seam's `unsignable` * branch, so a `local` / `node` / `impersonated` account broadcasts identically inside * this scope (ADR 0006). * * The action is a THUNK, for the same reason `catchUnknownSigner`'s is: a promise has * already started before the frame could be pushed, so accepting one would silently * not apply the override. */ export declare function withUnknownSignerPolicy(env: Environment): WithUnknownSignerPolicyFunction; /** * Run `action`, catch an `UnknownSignerError`, print the transaction to execute * out-of-band and return its description. Returns `null` when the action succeeded. * Any other error is rethrown unchanged. * * Kept for scripts ported from hardhat-deploy v1. A new script uses rocketh's own * handling instead: the pause from a terminal, `throw` plus a `guard` unattended, a fork * rehearsal for the whole batch (https://rocketh.dev/documentation/unknown-signers/). * * DECISION — the print goes through `env.showMessage`, not `console.log` as v1 did. * `showMessage` is rocketh's user-message channel (the same one the environment uses * to announce a deployed address), so the block respects the run's `--log-level` and * stays capturable in tests, and this package needs no `named-logs` dependency of its * own nor an entry in `@rocketh/node`'s `packagesWithLogsEnabled`. It is user-visible: * a run with logging turned down below `log` level will not show the block, whereas v1 * always printed. `options.log === false` remains the explicit way to suppress it. */ export declare function catchUnknownSigner(env: Environment): CatchUnknownSignerFunction; //# sourceMappingURL=index.d.ts.map