@anywalletkit/extension-kit 0.3.6 → 0.4.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { KeyringStorage, SecretStorage } from '@anywalletkit/keyring';
-import { Quote, Swap2ExecutionPlan, CrossChainProvider, QuoteParams, IntentStatus } from '@anywalletkit/protocol-swap2-core';
+import { Quote, QuoteParams, Swap2ExecutionPlan, CrossChainProvider, IntentStatus } from '@anywalletkit/protocol-swap2-core';
 import { TonSignDataPayload } from '@anywalletkit/wallet-ton/tonconnect';
 export { TONCONNECT_ERRORS, TONCONNECT_MAX_MESSAGES, TONCONNECT_NETWORKS, TONCONNECT_SIGN_DATA_MAX, TonConnectError, TonConnectMessage, TonConnectParseOptions, TonConnectRequest, TonConnectSendOptions, TonConnectSendTransaction, TonSignDataPayload, parseConnectRequest, parseSendTransaction, parseSignData, sameTonConnectAddress, tonConnectFriendlyAddress, tonConnectRawAddress } from '@anywalletkit/wallet-ton/tonconnect';
 
@@ -178,6 +178,14 @@ declare class Vault {
      */
     unlock(password: string): Promise<Uint8Array>;
     private _unlock;
+    /**
+     * A DEK unwrapped from a dek / passkey box must be the key this vault's secrets are sealed under
+     * (audit 2026-11-09 E21): a box spliced in from another vault, under another password or passkey,
+     * opens with that password but holds a foreign key. Proven with the DEK check, or — in an envelope
+     * written before it — the first secret; an old empty envelope has nothing to prove it with. Returns
+     * `dek`; on a mismatch zeroizes it and fails as `wrong-password` (the same failure as tampering).
+     */
+    private _proveOwn;
     /**
      * Re-wrap the DEK under a new password (fresh salt, current KDF). Secrets and passkeys are untouched —
      * and so is the DEK: after a suspected compromise (a copied profile, a leaked session, a lost passkey)
@@ -194,8 +202,11 @@ declare class Vault {
      *
      * Passkeys are dropped — their boxes hold the old DEK and cannot be re-wrapped without their PRF
      * output — and must be registered again ({@link Vault.addPasskey} with the new DEK).
+     *
+     * With `newPassword` this is also the password change: the new DEK is wrapped under `newPassword`
+     * (at least {@link VAULT_MIN_PASSWORD_LENGTH} characters), and `password` must be the current one.
      */
-    rotateVaultKey(password: string): Promise<Uint8Array>;
+    rotateVaultKey(password: string, newPassword?: string): Promise<Uint8Array>;
     /** Public view of the registered passkeys (ids, labels; whether each can verify assertions). */
     listPasskeys(): Promise<Array<{
         id: string;
@@ -321,10 +332,20 @@ declare class Session {
      * a missed alarm cannot keep the key alive.
      */
     getKey(): Promise<Uint8Array>;
-    /** User activity: push the auto-lock out again. No-op when locked. */
+    /**
+     * User activity: push the auto-lock out again. No-op when locked. Call it for explicit user
+     * gestures only (unlock, send, approve / decline, an action in the wallet's own UI) — not for
+     * passive polls, page requests or worker restarts, or the timer never runs out.
+     */
     touch(): Promise<void>;
     get autoLockMs(): number;
-    /** Change the timer (options page); re-arms from now when unlocked. 0 disables. */
+    /**
+     * Set the timer period (0 disables). Never pushes the deadline out — call this at every worker
+     * start with the stored setting: it re-arms the alarm at the stored deadline (a restart must not
+     * count as activity, audit 2026-11-09 E11), and only brings the deadline forward when the new
+     * period ends sooner. A longer period (or 0) applies from the next {@link Session.touch} /
+     * {@link Session.unlock}; call `touch()` right after when the user changed it explicitly.
+     */
     setAutoLockMs(ms: number): Promise<void>;
     onLock(callback: () => void): () => void;
     private _serial;
@@ -587,6 +608,11 @@ declare class NetworksTable {
     /** Cache first (readers see it at once), rolled back when storage refuses. */
     private write;
     private custom;
+    /**
+     * Forget the cached table: the next read asks storage again. For a storage whose answer changes under
+     * the table — e.g. one that only hands out the user's networks once the wallet is unlocked.
+     */
+    reload(): Promise<void>;
 }
 /**
  * EIP-3085 `wallet_addEthereumChain` parameter → {@link EvmNetwork}, or the error
@@ -664,12 +690,23 @@ declare class PermissionStore {
     get(origin: string): Promise<OriginPermission | null>;
     list(): Promise<OriginPermission[]>;
     connect(origin: string, accounts: string[], chain: string): Promise<OriginPermission>;
+    /**
+     * Add EVM accounts to an origin's grant (per-site grants): the new ones first, the ones it already
+     * holds stay. The chain stays the origin's own when it has one. Used by the router's connect; `connect`
+     * replaces the list instead.
+     */
+    grant(origin: string, accounts: string[], chain: string): Promise<OriginPermission>;
     /** Connect another chain's accounts to the same origin (one "connected sites" list). */
     connectChain(origin: string, key: ChainAccountsKey, accounts: string[], defaultChain: string): Promise<OriginPermission>;
     /** Drop one chain's accounts; the origin stays connected while any chain remains. A no-op (no write) when there is nothing to drop. */
     disconnectChain(origin: string, key: 'accounts' | ChainAccountsKey): Promise<void>;
     setChain(origin: string, chain: string): Promise<OriginPermission | null>;
     /**
+     * @deprecated Rewrites every origin's grant to the active account, which shows that account to sites
+     * the user never connected it to (and links accounts across sites). Grants are per site now: the
+     * router shows an origin its granted accounts that are also active, and connecting another account
+     * adds it to that one origin ({@link grant}). Kept for compatibility; nothing in this package calls it.
+     *
      * The active EVM account changed: every origin holding an EVM grant now sees `accounts` (MetaMask behaviour).
      * An origin connected only on another chain (`accounts: []` — Solana/TON/Tron/BTC/NEAR providers, a WalletConnect
      * session without eip155) is skipped: it never passed an EVM connect and must not learn the EVM address (scan F6/F8).
@@ -708,6 +745,21 @@ declare class OriginRefused extends Error {
     constructor(message: string);
 }
 declare const APPROVALS_MAX_PENDING_PER_ORIGIN = 3;
+/** Requests one site (registrable domain: every subdomain counts) may have waiting. */
+declare const APPROVALS_MAX_PENDING_PER_SITE = 5;
+/** Requests the whole queue holds (exempt origins not counted). */
+declare const APPROVALS_MAX_PENDING_TOTAL = 20;
+/** How fast one site may open sheets: a token bucket per site; running dry refuses for a cooldown that doubles on every repeat. */
+interface ApprovalRateOptions {
+    /** Sheets a site may open at once. Default 10. */
+    burst?: number;
+    /** Sheets per second a site earns back. Default 1/6 (10 a minute). */
+    refillPerSecond?: number;
+    /** First cooldown after the bucket ran dry. Default 30 s. */
+    backoffMs?: number;
+    /** Longest cooldown; also how long a site must stay quiet for its strikes to reset. Default 10 min. */
+    maxBackoffMs?: number;
+}
 interface ApprovalRequest<P = unknown> {
     id: string;
     origin: string;
@@ -732,6 +784,28 @@ interface ApprovalQueueOptions {
     refuse?: (origin: string) => string | null | undefined;
     /** Requests one origin may have waiting (current + queued). Default {@link APPROVALS_MAX_PENDING_PER_ORIGIN}. */
     maxPendingPerOrigin?: number;
+    /** Requests one site may have waiting. Default {@link APPROVALS_MAX_PENDING_PER_SITE}. */
+    maxPendingPerSite?: number;
+    /** Requests the queue holds in all. Default {@link APPROVALS_MAX_PENDING_TOTAL}. */
+    maxPendingTotal?: number;
+    /** Origin → site for the per-site limits. Default {@link defaultSiteOf siteOf} (conservative eTLD+1; pass a Public Suffix List based one if you ship it). */
+    siteOf?: (origin: string) => string;
+    /** Origins that skip every limit (the wallet's own pages: Send, swaps). They still queue behind other requests. */
+    exempt?: (origin: string) => boolean;
+    /** Sheet-opening rate per site; `false` turns it off. */
+    openRate?: ApprovalRateOptions | false;
+    /** Clock (ms), injectable for tests. */
+    now?: () => number;
+}
+/** Options of one {@link ApprovalQueue.request}. */
+interface ApprovalRequestOptions {
+    /**
+     * Another sheet for a request the user has just approved (the fee changed before signing). It skips
+     * the queue and rate limits and is shown ahead of the requests already waiting — once per approval
+     * of the same origin, kind and chain; with no such approval behind it, it is an ordinary request.
+     * `refuse` still applies.
+     */
+    followUp?: boolean;
 }
 /** The window side: open for one request, close when it is answered. `memoryApprovalWindow()` for tests. */
 interface ApprovalWindow {
@@ -748,15 +822,39 @@ declare class ApprovalQueue {
     private readonly _waiting;
     private readonly _listeners;
     private readonly _via;
+    private readonly _rate;
+    /** Per site: cooldown end and strikes (how many times the bucket ran dry recently). */
+    private readonly _cooldown;
+    /** Per origin + kind + chain: approvals that have not been followed up (see {@link ApprovalRequestOptions.followUp}). */
+    private readonly _approved;
     constructor(window: ApprovalWindow, newId?: () => string, options?: ApprovalQueueOptions);
+    private site;
+    private get all();
+    /** The per-site rate: a reason to refuse, or null (and one token spent). */
+    private rateRefusal;
+    private static followUpKey;
+    /** The user approved `r`: it may be followed up once. */
+    private approved;
+    /** Spends one approval of the same origin, kind and chain; false when there is none. */
+    private spendApproval;
     /** Enqueue and wait for the user's answer. Refuses (never queues) past the per-origin limits. */
-    request<T = unknown>(input: Omit<ApprovalRequest, 'id' | 'createdAt' | 'originWarnings' | 'via'>): Promise<T>;
+    request<T = unknown>(input: Omit<ApprovalRequest, 'id' | 'createdAt' | 'originWarnings' | 'via'>, opts?: ApprovalRequestOptions): Promise<T>;
     /** Attach (or clear) the transport note every later request from `origin` carries. */
     setVia(origin: string, via: OriginVia | null): void;
     /** The transport note later requests from `origin` carry (WalletConnect Verify's verdict for `wc:<topic>`), if any. */
     viaFor(origin: string): OriginVia | undefined;
+    private isExempt;
     /** Requests waiting for `origin` (current + queued). */
     pendingFor(origin: string): number;
+    /** Requests waiting for any origin of `site` (current + queued). */
+    pendingForSite(site: string): number;
+    /** The site (registrable domain) the queue's limits put `origin` under. */
+    siteFor(origin: string): string;
+    /** Decline everything waiting for `origin` (its last page closed). Returns how many requests were declined. */
+    declineOrigin(origin: string, error?: Error): number;
+    /** "Decline all from this site": everything waiting for any origin of `site` (see {@link siteFor}). */
+    declineSite(site: string, error?: Error): number;
+    private declineWhere;
     /** The request currently shown (the window asks for it by id on load). */
     get current(): ApprovalRequest | null;
     get queued(): number;
@@ -797,6 +895,14 @@ interface RelayErrorOptions {
 declare function toRelayError(e: unknown, options?: RelayErrorOptions): RelayError;
 /** Read-only methods answered from our RPC without asking the user. */
 declare const READ_METHODS: ReadonlySet<string>;
+/**
+ * Blocks an `eth_getLogs` from an origin without an EVM grant may span. A page that is not connected
+ * reads recent events (a token's latest transfers, a pool's last swaps), not history: 1000 blocks is
+ * ~3.3 h on Ethereum and ~30 min on 2 s chains, and stays inside every public RPC's own range cap,
+ * so one call cannot make the wallet's RPC scan millions of blocks for a page nobody connected.
+ * Connected origins are not bounded here (the node's own limits apply).
+ */
+declare const GETLOGS_MAX_SPAN_UNCONNECTED = 1000;
 /** Methods that produce a signature — the review flow's business (step 4), never answered here. */
 declare const SIGNING_METHODS: ReadonlySet<string>;
 interface ConnectApproval {
@@ -843,9 +949,12 @@ declare class RequestRouter {
     handle(origin: string, chain: RelayChain, method: string, rawParams: unknown): Promise<unknown>;
     /** What a connected origin sees right now: its permitted accounts that the wallet can expose (none while locked). */
     private visibleAccounts;
+    /** An unconnected origin's `eth_getLogs`: a block hash, or a range of at most {@link GETLOGS_MAX_SPAN_UNCONNECTED} blocks. */
+    private boundLogs;
     /**
      * Connected and unlocked → the accounts; otherwise the approval window (which
-     * unlocks first when needed) picks them. Emits `connect` + `accountsChanged`.
+     * unlocks first when needed) picks them, and they are ADDED to this origin's
+     * grant (other origins are untouched). Emits `connect` + `accountsChanged`.
      */
     private connect;
     disconnect(origin: string): Promise<void>;
@@ -887,7 +996,22 @@ interface SiweInfo {
     problems: string[];
     /** The header said "sign-in" but the rest did not parse as EIP-4361 (`message` then holds what could be read). */
     malformed?: boolean;
+    /**
+     * Set when the sign-in names another site than the one asking (its host differs from the page's
+     * host, or from a WalletConnect Verify-attested URL): `domain` as written in the message, `origin`
+     * the asking site as `scheme://host`. A sheet should make this its headline, not one warning among many.
+     */
+    crossSite?: {
+        domain: string;
+        origin: string;
+    };
 }
+/**
+ * Characters a sign-in message is refused for: bidi controls (ALM, LRM / RLM, embeddings, overrides,
+ * isolates), zero-width space / joiners, word joiner and invisible operators, BOM — they can make the
+ * domain or the statement read differently from the bytes that are signed.
+ */
+declare const SIWE_FORBIDDEN_CHARS: RegExp;
 interface SiweContext {
     /** The page that asked, as the browser recorded it (`https://…`), or a transport pseudo-origin (`wc:<topic>`). */
     origin: string;
@@ -905,6 +1029,15 @@ declare function parseSiwe(text: string): SiweMessage | null;
 declare function isLocalHost(host: string): boolean;
 /** The checks; `origin` is the page that asked (as the browser recorded it), `account` the signing address, `chainId` the site's chain. */
 declare function siweProblems(m: SiweMessage, ctx: SiweContext): string[];
+/**
+ * The asking site when the sign-in names a different host: the browser-recorded origin, or for a
+ * WalletConnect pseudo-origin the URL Verify attested (VALID, not scam). `null` when the hosts agree
+ * or when no site can be vouched for at all (that case is a separate "cannot verify" problem).
+ */
+declare function siweCrossSite(m: SiweMessage, ctx: SiweContext): {
+    domain: string;
+    origin: string;
+} | null;
 /** `null` only when the text does not start with an EIP-4361 header; a header with unreadable fields comes back with a "malformed sign-in message" problem. */
 declare function describeSiwe(text: string, ctx: SiweContext): SiweInfo | null;
 
@@ -930,7 +1063,10 @@ declare function describeSiwe(text: string, ctx: SiweContext): SiweInfo | null;
  * The fee caps signed are the ones shown, unless the network outgrew them
  * while the sheet was open (EIP-1559: base fee + tip above the shown cap;
  * legacy: a higher gas price) — then the user is asked again with the new
- * numbers (`repriced: true`).
+ * numbers (`repriced: true`, `repricedFrom` = the max fee shown before) on a
+ * follow-up sheet the queue limits do not refuse, at most {@link MAX_FEE_REASKS}
+ * times in a row; declining it signs nothing. A new max fee above the wallet's
+ * own ceiling ({@link SignDeps.feeCeiling}) is refused without a sheet.
  *
  * The review payload ({@link SignApproval}) carries what the window shows: the
  * classified request, the prepared fields, the fee, and the preview the wallet
@@ -943,16 +1079,19 @@ declare function describeSiwe(text: string, ctx: SiweContext): SiweInfo | null;
 type SignRequestInfo = {
     kind: 'sign-message';
     method: 'personal_sign';
-    account: string; /** Decoded text when printable, else the hex. */
+    account: string; /** Decoded text when printable, else the hex; invisible / direction-changing characters shown as `⟨U+XXXX⟩` ({@link revealHidden}). */
     text: string; /** What is actually signed (hex or utf-8 string). */
     raw: string; /** Parsed Sign-In with Ethereum (EIP-4361) with the checks against the asking origin, when the text is one. */
-    siwe?: SiweInfo;
+    siwe?: SiweInfo; /** `text` had invisible or direction-changing characters (now escaped): the sheet should warn. */
+    hiddenChars?: true; /** The message is exactly 32 bytes (`0x` + 64 hex): a blind hash signature that CoW Protocol (`ethsign`), Safe (v > 30) and others accept as an order or a transfer. Only with the wallet's opt-in ({@link SignDeps.allowBlindHash}); the sheet must make it a danger screen. */
+    blindHash?: true;
 } | {
     kind: 'sign-typed-data';
     method: string;
-    account: string; /** Pretty-printed JSON. */
+    account: string; /** Pretty-printed JSON, invisible / direction-changing characters escaped. */
     text: string;
-    typedData: TypedData;
+    typedData: TypedData; /** `text` had invisible or direction-changing characters (now escaped): the sheet should warn. */
+    hiddenChars?: true;
 } | {
     kind: 'send-transaction';
     method: 'eth_sendTransaction';
@@ -983,6 +1122,15 @@ interface PreparedTx {
     gasPrice?: string;
     /** gasLimit × max fee, base units. */
     maxFee: string;
+    /**
+     * Set when the page chose the gas limit and the wallet's own `eth_estimateGas` answered: the estimate
+     * (0x hex) and whether the page's limit is above max(estimate × 1.5, estimate + 50 000) — then the sheet
+     * should warn with the max fee. The page's limit is still the one signed.
+     */
+    gasCheck?: {
+        estimate: string;
+        excessive: boolean;
+    };
 }
 /** The approval window's payload for the three signing kinds. */
 interface SignApproval {
@@ -991,6 +1139,8 @@ interface SignApproval {
     prepared?: PreparedTx;
     /** A second sheet for the same transaction: the network's fee outgrew the cap the first one showed. */
     repriced?: true;
+    /** With `repriced`: the max fee (`prepared.maxFee`, base units) the sheet before this one showed. */
+    repricedFrom?: string;
     /** What the wallet attached (tx-preview-evm `TxPreview`, typed-data description…). */
     preview: unknown;
 }
@@ -1026,8 +1176,33 @@ interface SignDeps {
     }): Promise<unknown>;
     /** Tip floor per chain id in wei (default 0.1 gwei everywhere). */
     tipFloor?: (chainId: number) => bigint;
+    /**
+     * Whether a personal_sign of a raw 32-byte hash may reach the sheet (read per request). Default: refused — a
+     * blind hash signature can be a CoW order or a Safe transaction paying someone else (extension audit E55).
+     */
+    allowBlindHash?: () => boolean | Promise<boolean>;
+    /**
+     * The most one transaction may cost in fee on `network` (base units), when the wallet has such a limit
+     * (the one its signer enforces). A fee that rose above it after the sheet is refused right away, with
+     * no second sheet. The first sheet is not checked here: the signer is the guard for it.
+     */
+    feeCeiling?: (network: EvmNetwork) => bigint | undefined;
 }
-/** Vaulty's `messageText`: hex that decodes to printable text is shown decoded; binary payloads stay hex. */
+/** How many times in a row one transaction's fee may be asked again ({@link SignApproval.repriced}); the next rise stops the request, nothing signed. */
+declare const MAX_FEE_REASKS = 3;
+/**
+ * Text for a review sheet: every invisible or direction-changing character replaced by a visible
+ * `⟨U+XXXX⟩`, so the order on screen is the order of the bytes (a right-to-left override can make
+ * "exe.gnp" read as "png.exe"). `hidden` says whether anything was replaced — the sheet should warn.
+ */
+declare function revealHidden(text: string): {
+    text: string;
+    hidden: boolean;
+};
+/**
+ * Vaulty's `messageText`: hex that decodes to printable text is shown decoded; binary payloads stay hex.
+ * Invisible and direction-changing characters come back escaped ({@link revealHidden}).
+ */
 declare function messageText(value: unknown): string;
 /**
  * The message as the signer will sign it: hex decoded when it is valid UTF-8, whatever
@@ -1035,7 +1210,6 @@ declare function messageText(value: unknown): string;
  * signed, not the hex fallback `messageText` shows for unprintable text).
  */
 declare function decodedMessage(value: unknown): string | null;
-/** Signing method + params → what the window reviews, or the error to answer with. */
 declare function classifySignRequest(input: {
     network: EvmNetwork;
     method: string;
@@ -1043,9 +1217,16 @@ declare function classifySignRequest(input: {
     accounts: string[]; /** The asking page (browser-recorded) — needed for the SIWE domain check. */
     origin?: string; /** Transport note for pseudo-origins (WalletConnect Verify), for the SIWE check. */
     via?: OriginVia;
-    now?: number;
+    now?: number; /** Let a 32-byte hash personal_sign reach the sheet (marked `blindHash`) instead of refusing it. Default false. */
+    allowBlindHash?: boolean;
 }): SignRequestInfo | RelayError;
-/** Nonce, gas, fees from the wallet's RPC. */
+/** A page's gas limit above max(estimate × 1.5, estimate + 50 000) is flagged on the sheet (never replaced). */
+declare function gasLimitExcessive(limit: bigint, estimate: bigint): boolean;
+/**
+ * Nonce, gas, fees from the wallet's RPC. A gas limit the page set is used as given, but it is checked
+ * against the wallet's own estimate ({@link PreparedTx.gasCheck}); a failed estimate (a call that
+ * reverts now) leaves the check out instead of failing the request.
+ */
 declare function prepareTransaction(deps: Pick<SignDeps, 'rpc' | 'tipFloor'>, network: EvmNetwork, from: string, tx: {
     to: string;
     value: string;
@@ -1168,6 +1349,40 @@ interface RouteView {
     etaSeconds: number;
     validUntilMs: number;
     tags: ('best' | 'fastest')[];
+    /** Why this route is not a plain pick: a flagged route is never BEST (see {@link rank}). Absent when there is nothing to say. */
+    warnings?: RouteWarning[];
+}
+/**
+ * What the wallet cannot vouch for on a route — data for the app's list and sheet, never a refusal:
+ * - `min-below-slippage`: the provider's minimum sits `minGapBps` under its own quote, further than the `slippageBps`
+ *   the app asked for (a backend that inflates the output and drops the minimum would otherwise win BEST);
+ * - `deposit-address`: the route pays an address the provider's server assigns (a 1Click deposit address, a THORChain
+ *   inbound vault on a non-EVM source chain, a Bitcoin deposit address), so where the funds end up is that server's
+ *   word, not calldata the wallet can check.
+ */
+type RouteWarning = {
+    kind: 'min-below-slippage';
+    slippageBps: number;
+    minGapBps: number;
+} | {
+    kind: 'deposit-address';
+};
+/** The app's route policy inputs for {@link rank}. */
+interface RankOptions {
+    /** The slippage the quotes were requested at (bps): a route whose minimum sits further under its output is flagged and never BEST. */
+    slippageBps?: number;
+    /**
+     * Providers whose routes pay an address their server assigns (NEAR Intents 1Click): flagged, and BEST only when no
+     * route from any other provider exists. Which providers these are is the app's call.
+     */
+    depositAddressProviders?: readonly string[];
+    /**
+     * The same flag per route, for a provider that pays a server-assigned address only on some routes (a THORChain
+     * inbound vault on a non-EVM source chain, a Bitcoin deposit address) and verifiable calldata on the rest. A route is
+     * flagged when its provider is listed above OR this returns true; a throw counts as flagged. BEST goes to a flagged
+     * route only when every route is flagged. Which routes these are is the app's call.
+     */
+    depositAddressRoute?: (quote: Quote) => boolean;
 }
 interface RouteListView {
     routes: RouteView[];
@@ -1180,6 +1395,10 @@ interface RouteListView {
 }
 interface QuoteRoutesOptions {
     onUpdate?: (view: RouteListView) => void;
+    /** See {@link RankOptions.depositAddressProviders}; the slippage comes from `params.slippageBps`. */
+    depositAddressProviders?: readonly string[];
+    /** {@link RankOptions.depositAddressRoute} with the request next to the quote (a quote does not name its source chain). */
+    depositAddressRoute?: (quote: Quote, params: QuoteParams) => boolean;
     /** Per-provider wall clock (default 20 s). */
     timeoutMs?: number;
     signal?: AbortSignal;
@@ -1187,8 +1406,15 @@ interface QuoteRoutesOptions {
 }
 /** Dry quotes from every enabled provider that claims the route, progressively. */
 declare function quoteRoutes(providers: readonly CrossChainProvider[], params: QuoteParams, options?: QuoteRoutesOptions): Promise<RouteListView>;
-/** Highest output first (same destination token for every quote); FASTEST = lowest ETA among them. */
-declare function rank(quotes: Quote[]): RouteView[];
+/**
+ * Highest output first (same destination token for every quote); FASTEST = lowest ETA among them.
+ *
+ * BEST goes to the highest output among the routes without a {@link RouteWarning} that bars it: never a route whose
+ * minimum is below the requested slippage, and a deposit-address route only when every route is one (no route with
+ * verifiable calldata exists).
+ * The BEST route is listed first; the rest keep the output order. With no route eligible there is no BEST.
+ */
+declare function rank(quotes: Quote[], options?: RankOptions): RouteView[];
 /** Vaulty's execution floor: 50 bps under the quoted minimum rides normal drift while the user reviews, still refuses a real reprice. */
 declare const FLOOR_TOLERANCE_BPS = 50n;
 declare function executionFloor(minDestAmount: bigint): bigint;
@@ -1206,6 +1432,14 @@ interface SwapReviewMeta {
     toChainName: string;
     /** All of the user's addresses — recipient own/foreign. */
     own: string[];
+    /** The slippage the swap was quoted at (bps): a plan minimum further under its output is warned on the sheet (never refused). */
+    slippageBps?: number;
+    /**
+     * The route pays an address the provider's server assigned (a NEAR Intents 1Click deposit address, a THORChain
+     * inbound vault on a non-EVM source chain, a Bitcoin deposit address — the app's call per route): the sheet warns,
+     * and the recipient check does not pass on `plan.recipient` alone — the transaction does not carry it.
+     */
+    depositAddressAssignedByProvider?: boolean;
 }
 /** What the swap sheet renders. Amounts are base-unit strings. */
 interface SwapApproval {
@@ -1264,6 +1498,14 @@ interface SwapApproval {
         status: 'ok' | 'warn' | 'unknown';
         label: string;
     }[];
+    /** With `meta.slippageBps`: how far the minimum sits under the output, and whether that is more than the slippage. */
+    slippage?: {
+        bps: number;
+        minGapBps: number;
+        below: boolean;
+    };
+    /** With `meta.depositAddressAssignedByProvider`: the funds go to an address the provider's server named. */
+    depositAssignedByProvider?: true;
 }
 declare const encodeApproveCalldata: (spender: string, amount: bigint) => string;
 declare function swapApprovalPayload(plan: Swap2ExecutionPlan, meta: SwapReviewMeta): SwapApproval;
@@ -1606,6 +1848,8 @@ declare class RecipientBook {
     private state;
     list(namespace: string): Promise<string[]>;
     remember(namespace: string, address: string): Promise<void>;
+    /** Forget the cached book: the next read asks storage again (e.g. a storage that only answers once the wallet is unlocked). */
+    reload(): void;
     /** `known` → the address is one the user paid before; `lookalike` → it imitates one. */
     check(namespace: string, address: string): Promise<{
         known: boolean;
@@ -1613,4 +1857,209 @@ declare class RecipientBook {
     }>;
 }
 
-export { ACTIVE_STATUSES, APPROVALS_MAX_PENDING_PER_ORIGIN, type AddChainApproval, type AlarmsLike, type ApprovalKind, ApprovalQueue, type ApprovalQueueOptions, type ApprovalRequest, type ApprovalWindow, type AssertionExpectations, type AssertionInput, type AssertionVerdict, BTC_CHAIN, BTC_ESPLORA, CHAIN_ACCOUNT_KEYS, type ChainAccountsKey, type ChainDescriptor, type ConnectApproval, DEFAULT_CHAIN, DEFAULT_NETWORKS, type EarnApproval, type EarnPlan, type EarnReviewMeta, type EarnTx, type EvmNetwork, type EvmSigner, FLOOR_TOLERANCE_BPS, type GateMatcher, type GatedOp, type HostCheck, type JsonStorage, KEYRING_STORAGE_KEY, LOOKALIKE_PREFIX, LOOKALIKE_SUFFIX, NEAR_CHAIN, NEAR_PROVIDERS, NON_EVM_CHAINS, NetworksTable, type OriginPermission, OriginRefused, type OriginVia, PAGE_TARGET, PORT_NAME, type PageEvent, type PageMessageEvent, type PageRequest, type PageResponse, type PageWindow, PermissionStore, type PermissionsState, PhishingDetector, type PhishingList, type PortSender, type PreparedTx, QueueLimitError, type QuoteRoutesOptions, READ_METHODS, RELAY_ERRORS, RELAY_METHOD_MAX, RecipientBook, type RecipientsState, type RelayChain, type RelayError, type RelayErrorOptions, type RelayEvent, type RelayRequest, type RelayResponse, type RelayToContent, type RelayToWorker, RequestRouter, ReviewDeclined, ReviewGate, type RouteListView, type RouteView, type RouterDeps, RouterError, SESSION_DEFAULT_AUTOLOCK_MS, SIGNING_METHODS, SOLANA_CHAIN, SOLANA_RPCS, type SealedBox, Session, type SessionAlarms, type SessionOptions, type SessionStorage, type SignApproval, type SignDeps, type SignRequestInfo, type SiweContext, type SiweInfo, type SiweMessage, type StorageAreaLike, type SwapApproval, type SwapRecord, type SwapRecordStatus, type SwapReviewMeta, SwapTracker, type SwapTrackerDeps, SwapsStore, type SwitchChainApproval, TON_CHAIN, TON_ENDPOINTS, TRON_CHAIN, TRON_PROVIDERS, type TonAddressParts, type TypedData, VAULT_DEFAULT_ITERATIONS, VAULT_LIMITS, VAULT_MIN_ITERATIONS, VAULT_MIN_PASSWORD_LENGTH, VAULT_MIN_SCRYPT, VAULT_SCRYPT, VAULT_STORAGE_KEY, Vault, type VaultEnvelope, type VaultEnvelopeV1, type VaultEnvelopeV2, VaultError, type VaultErrorCode, type VaultKdfInfo, type VaultOptions, type VaultPasskey, type VaultStorage, ZCASH_BLOCKCHAIR, ZCASH_CHAIN, approvalChallenge, caip2FromChainId, chainHex, chainTxMatcher, checkSenderOrigin, chromeAlarms, chromeJsonStorage, chromeKeyringStorage, chromeLocalVaultStorage, chromeSessionStorage, classifySignRequest, createSignHandler, decodedMessage, derToRaw, describeSiwe, earnApprovalPayload, earnPlanMatchers, encodeApproveCalldata, evmCallMatcher, executionFloor, fromBase64Url, hostOf, isCatalogChain, isEnvelopeV1, isEnvelopeV2, isLocalHost, isPageEvent, isPageRequest, isPageResponse, isRelayMethod, isRelayRequest, isRelayToContent, levenshtein, lookalikeOf, memoryAlarms, memoryApprovalWindow, memoryJsonStorage, memorySessionStorage, memoryVaultStorage, messageText, newRequestId, nonEvmChain, normalizeHost, pageRequestFrom, parseAddChainParams, parseRawAddress, parseSiwe, parseSwapId, planMatchers, prepareTransaction, proofDomain, quoteRoutes, rank, rawToDer, relayError, reviewEarnPlan, reviewSwapPlan, siweProblems, stampOrigin, swapApprovalPayload, toBase64Url, toRelayError, tonConnectErrorCode, tonProofMessage, tonSignDataMessage, typedDataMatcher, vaultSecretStorage, verifyAssertion };
+/** Field of the stored envelope that holds the MAC (base64), or `null` for a value written without a key. */
+declare const STORAGE_MAC_FIELD = "anywalletkit.mac/1";
+/** Field of the stored envelope that holds the value's version (a positive integer, inside the MAC) when the store has a {@link storageVersionLedger}. */
+declare const STORAGE_VERSION_FIELD = "anywalletkit.ver/1";
+/**
+ * The storage MAC key: HKDF-SHA256(ikm = DEK, salt = none, info = "anywalletkit/storage-mac/1"), 32
+ * bytes. One-way — it reveals nothing about the DEK — so a wallet may keep it in
+ * `chrome.storage.session` while locked. The same DEK always gives the same key; a rotated DEK a new one.
+ */
+declare function deriveStorageMacKey(dek: Uint8Array, crypto?: Crypto): Promise<Uint8Array>;
+/**
+ * What a read found:
+ * - `ok`: a value with a valid MAC;
+ * - `empty`: nothing stored;
+ * - `unsigned`: a value without a MAC (written before the wrapper existed, or while no key was there);
+ * - `invalid`: a MAC that does not match (edited, from another store, or under another key);
+ * - `no-key`: something is stored but there is no key to check it with;
+ * - `stale` (only with a {@link storageVersionLedger}): the MAC is valid — or nothing is stored — but
+ *   this is not the latest value the ledger knows: an older signed value put back, a deleted one, or
+ *   a ledger that was itself removed, edited or rolled back.
+ */
+type MacState = 'ok' | 'empty' | 'unsigned' | 'invalid' | 'no-key' | 'stale';
+interface MacRead<T> {
+    state: MacState;
+    /** The stored value — verified only when `state` is `ok`. */
+    value: T | null;
+    /** With a ledger, for a value whose MAC is valid: its version (`0` = signed before versions existed). */
+    version?: number;
+}
+interface MacJsonStorageOptions {
+    /** Names the store inside the MAC: a value signed for one store does not verify in another. */
+    label: string;
+    /** The MAC key ({@link deriveStorageMacKey}), or `null` when the wallet has none (locked). The wrapper zeroizes the copy it gets. */
+    key: () => Promise<Uint8Array | null>;
+    /** `get()` without a key: the stored value unverified (`'unverified'`, default) or `null`. */
+    readWithoutKey?: 'unverified' | 'null';
+    /** `set()` without a key: store the value with no MAC (`'unsigned'`, default — it fails verification later) or throw `VaultError('locked')`. */
+    writeWithoutKey?: 'unsigned' | 'refuse';
+    /**
+     * Rollback protection: the ledger shared by the wallet's signed stores. Every signed write takes the
+     * store's next version (inside the MAC) and records it; a read whose version the ledger does not
+     * agree with is `stale`. The label must not contain a line break.
+     */
+    versions?: StorageVersionLedger;
+}
+interface MacJsonStorage<T> extends JsonStorage<T> {
+    /** The verified value (`null` when empty, unsigned or invalid); without a key, per `readWithoutKey`. */
+    get(): Promise<T | null>;
+    /** Sign with the current key; without one, per `writeWithoutKey`. */
+    set(value: T): Promise<void>;
+    /** The stored value and what verification found, under `key` (default: the current key). */
+    read(key?: Uint8Array): Promise<MacRead<T>>;
+    /** Store `value` signed under `key` (default: the current key; refused without one). */
+    write(value: T, key?: Uint8Array): Promise<void>;
+    /**
+     * Re-sign the stored value under `newKey` when it verifies under `oldKey`; anything else is left as it is. Returns what `oldKey` found.
+     * With a ledger: rekey the ledger first ({@link StorageVersionLedger.rekey}); the value keeps its version, and is re-signed only when the
+     * re-signed ledger agrees with it (`stale` otherwise).
+     */
+    rekey(oldKey: Uint8Array, newKey: Uint8Array): Promise<MacState>;
+}
+/** Wrap `inner` (e.g. `chromeJsonStorage(chrome.storage.local, key)`) with a MAC; see the module comment. */
+declare function macJsonStorage<T>(inner: JsonStorage<unknown>, options: MacJsonStorageOptions): MacJsonStorage<T>;
+/** Deterministic JSON: the same data gives the same text whatever order its keys were stored in. */
+declare function canonicalJson(value: unknown): string;
+/** What a {@link StorageVersionLedger} holds, as {@link StorageVersionLedger.read} found it. */
+interface StorageVersions {
+    /** `ok`; `empty` (no manifest and none expected); `invalid` (unsigned, edited, or another key); `stale` (missing or older than this browser session has seen). */
+    state: 'ok' | 'empty' | 'invalid' | 'stale';
+    /** Goes up by one with every manifest write. `0` when there is no readable manifest. */
+    epoch: number;
+    /** Where this manifest's numbering started: a store's first version is `base + 1`. */
+    base: number;
+    /** After {@link StorageVersionLedger.condemn}: a store the manifest does not list is not trusted, stored or not. */
+    sealed: boolean;
+    /** The latest version of each store, by label. */
+    versions: Record<string, number>;
+}
+/** The ledger operations a store runs inside {@link StorageVersionLedger.exclusive}. */
+interface StorageVersionOps {
+    /**
+     * Is `version` the latest for `label`? `null` = nothing is stored, `0` = a signed value without a
+     * version. A value exactly one ahead of the manifest is accepted and recorded (an interrupted write).
+     */
+    check(label: string, version: number | null, key: Uint8Array): Promise<'ok' | 'stale'>;
+    /**
+     * One write: `write(version)` stores the value signed with the next version, then the manifest records
+     * it. `seen()` is the version of the value stored now (0 when none this key signed). A missing manifest
+     * is created first; a refused one is replaced by a sealed one ({@link StorageVersionLedger.condemn}).
+     */
+    advance(label: string, key: Uint8Array, seen: () => Promise<number>, write: (version: number) => Promise<void>): Promise<number>;
+}
+interface StorageVersionLedgerOptions {
+    /** Where the manifest lives — the same area as the stores it covers (`chrome.storage.local`). */
+    manifest: JsonStorage<unknown>;
+    /**
+     * The highest manifest epoch seen, kept where a write to the stores' area cannot reach it and where it
+     * dies with the browser session (`chrome.storage.session`). `set(null)` clears it.
+     */
+    mark: JsonStorage<unknown>;
+    /** Names the manifest inside its MAC. No store may use it. */
+    label?: string;
+    /**
+     * Accept a validly signed value that carries no version (written before the ledger existed) for a
+     * store the manifest has no record of. Off by default: such a value can be replayed for as long as it
+     * is accepted, so switch it on only to migrate, write every store once, and switch it off again.
+     */
+    acceptUnversioned?: boolean;
+    /** Milliseconds since the epoch — where a new manifest starts numbering. */
+    now?: () => number;
+}
+interface StorageVersionLedger {
+    /** Run `fn` with no other ledger operation in between (stores use it for read-and-check and for a write). Do not nest. */
+    exclusive<R>(fn: (ops: StorageVersionOps) => Promise<R>): Promise<R>;
+    /**
+     * Stop trusting everything signed so far: a fresh, sealed manifest numbered above all it replaces.
+     * Every store then reads `stale` — also one with nothing stored — until it is written again.
+     */
+    condemn(key: Uint8Array): Promise<void>;
+    /** Re-sign the manifest under `newKey` when it is `ok` under `oldKey` (one epoch up); otherwise it is left as it is. Returns what `oldKey` found. Then rekey the stores. */
+    rekey(oldKey: Uint8Array, newKey: Uint8Array): Promise<StorageVersions['state']>;
+    /** The manifest as `key` sees it. */
+    read(key: Uint8Array): Promise<StorageVersions>;
+    /** Forget manifest and mark — only when the stores are wiped with them (a new vault). */
+    reset(): Promise<void>;
+}
+/**
+ * Rollback protection for {@link macJsonStorage} stores: one signed manifest that says which version
+ * of each store is the latest.
+ *
+ * - Every signed value carries its version inside the MAC. A write stores the value with the store's
+ *   next version, then the manifest (its `epoch` goes up by one), then the session mark. A value the
+ *   manifest lists another version for — or lists, when nothing is stored — is `stale`: putting ONE
+ *   store back, or deleting it, is caught, across browser restarts too.
+ * - The manifest lives next to the stores, so the whole area can be put back together. `mark` — the
+ *   highest epoch seen, in session storage — catches that for as long as the browser session lives: a
+ *   manifest older than the mark, or missing while there is a mark, makes every store `stale`.
+ * - A manifest that is unsigned, edited or under another key makes every store `stale`. So does a
+ *   signed value with a version when there is no manifest at all.
+ * - A worker killed between the value and the manifest write leaves a value exactly one version ahead.
+ *   That is accepted and recorded: only the key holder can sign that version, so it is the wallet's own
+ *   last write. Until it is recorded the previous value still verifies — the same as the interrupted
+ *   write never having happened.
+ *
+ * What it cannot see: the whole area (manifest and stores together) put back to an earlier state when
+ * there is no mark — after a browser restart, or an extension reload — and likewise everything deleted
+ * together. Nothing an extension can store survives that and is out of the same writer's reach; it is
+ * what restoring a profile backup looks like. Versions start from the clock (`now`) so that a manifest
+ * created after a loss does not hand out numbers already used; a clock set far back defeats that.
+ *
+ * The ledger never repairs on a read (beyond recording an interrupted write): the wallet decides what
+ * a `stale` store falls back to, calls {@link StorageVersionLedger.condemn} when the manifest itself was
+ * refused, and writes the stores again.
+ */
+declare function storageVersionLedger(options: StorageVersionLedgerOptions): StorageVersionLedger;
+
+/**
+ * "Same site" for limits: the registrable domain (eTLD+1) of an origin, and a
+ * token bucket keyed by any string. Both exist so a page cannot multiply its
+ * allowance by spreading requests over subdomains (`a1.evil.tld`, `a2.evil.tld`…).
+ *
+ * There is no Public Suffix List in this package (it is large and changes); the
+ * helper is conservative instead: the last two labels, or three when the last two
+ * are a known multi-label public suffix ({@link MULTI_LABEL_SUFFIXES}: country
+ * second-level domains such as `co.uk`, and hosting domains where anyone gets a
+ * subdomain, such as `github.io` or `vercel.app`). A suffix that is missing from
+ * the list makes unrelated sites under it share one limit (stricter, never looser);
+ * pass your own `siteOf` to the queue when you ship a full list.
+ */
+/**
+ * Multi-label public suffixes the helper knows. Two groups: country second-level
+ * registries, and hosting platforms that hand out subdomains to anyone (the
+ * Public Suffix List's private section).
+ */
+declare const MULTI_LABEL_SUFFIXES: ReadonlySet<string>;
+/**
+ * The site an origin belongs to: `https://a.b.example.co.uk:8443` → `example.co.uk`,
+ * `https://x.vercel.app` → `x.vercel.app`. IP addresses and single-label hosts
+ * (`localhost`) are their own site. A pseudo-origin that is not a URL (`wc:<topic>`)
+ * is returned unchanged.
+ */
+declare function siteOf(origin: string): string;
+interface TokenBucketOptions {
+    /** Tokens a key holds when full (the burst). */
+    capacity: number;
+    /** Tokens added per second. */
+    refillPerSecond: number;
+    /** Clock (ms), injectable for tests. */
+    now?: () => number;
+    /** Keys tracked before full buckets are dropped (memory bound). Default 2000. */
+    maxKeys?: number;
+}
+/** A token bucket per key: `take(key)` spends one token, `false` when the key is out of tokens. Memory only. */
+declare class TokenBucket {
+    private readonly options;
+    private readonly buckets;
+    constructor(options: TokenBucketOptions);
+    take(key: string, cost?: number): boolean;
+    /** Tokens `key` holds right now (full for an unknown key). */
+    available(key: string): number;
+    private refill;
+    /** Drop buckets that are full again (they carry no state); the oldest half when every one is in use. */
+    private prune;
+}
+
+export { ACTIVE_STATUSES, APPROVALS_MAX_PENDING_PER_ORIGIN, APPROVALS_MAX_PENDING_PER_SITE, APPROVALS_MAX_PENDING_TOTAL, type AddChainApproval, type AlarmsLike, type ApprovalKind, ApprovalQueue, type ApprovalQueueOptions, type ApprovalRateOptions, type ApprovalRequest, type ApprovalRequestOptions, type ApprovalWindow, type AssertionExpectations, type AssertionInput, type AssertionVerdict, BTC_CHAIN, BTC_ESPLORA, CHAIN_ACCOUNT_KEYS, type ChainAccountsKey, type ChainDescriptor, type ConnectApproval, DEFAULT_CHAIN, DEFAULT_NETWORKS, type EarnApproval, type EarnPlan, type EarnReviewMeta, type EarnTx, type EvmNetwork, type EvmSigner, FLOOR_TOLERANCE_BPS, GETLOGS_MAX_SPAN_UNCONNECTED, type GateMatcher, type GatedOp, type HostCheck, type JsonStorage, KEYRING_STORAGE_KEY, LOOKALIKE_PREFIX, LOOKALIKE_SUFFIX, MAX_FEE_REASKS, MULTI_LABEL_SUFFIXES, type MacJsonStorage, type MacJsonStorageOptions, type MacRead, type MacState, NEAR_CHAIN, NEAR_PROVIDERS, NON_EVM_CHAINS, NetworksTable, type OriginPermission, OriginRefused, type OriginVia, PAGE_TARGET, PORT_NAME, type PageEvent, type PageMessageEvent, type PageRequest, type PageResponse, type PageWindow, PermissionStore, type PermissionsState, PhishingDetector, type PhishingList, type PortSender, type PreparedTx, QueueLimitError, type QuoteRoutesOptions, READ_METHODS, RELAY_ERRORS, RELAY_METHOD_MAX, type RankOptions, RecipientBook, type RecipientsState, type RelayChain, type RelayError, type RelayErrorOptions, type RelayEvent, type RelayRequest, type RelayResponse, type RelayToContent, type RelayToWorker, RequestRouter, ReviewDeclined, ReviewGate, type RouteListView, type RouteView, type RouteWarning, type RouterDeps, RouterError, SESSION_DEFAULT_AUTOLOCK_MS, SIGNING_METHODS, SIWE_FORBIDDEN_CHARS, SOLANA_CHAIN, SOLANA_RPCS, STORAGE_MAC_FIELD, STORAGE_VERSION_FIELD, type SealedBox, Session, type SessionAlarms, type SessionOptions, type SessionStorage, type SignApproval, type SignDeps, type SignRequestInfo, type SiweContext, type SiweInfo, type SiweMessage, type StorageAreaLike, type StorageVersionLedger, type StorageVersionLedgerOptions, type StorageVersionOps, type StorageVersions, type SwapApproval, type SwapRecord, type SwapRecordStatus, type SwapReviewMeta, SwapTracker, type SwapTrackerDeps, SwapsStore, type SwitchChainApproval, TON_CHAIN, TON_ENDPOINTS, TRON_CHAIN, TRON_PROVIDERS, TokenBucket, type TokenBucketOptions, type TonAddressParts, type TypedData, VAULT_DEFAULT_ITERATIONS, VAULT_LIMITS, VAULT_MIN_ITERATIONS, VAULT_MIN_PASSWORD_LENGTH, VAULT_MIN_SCRYPT, VAULT_SCRYPT, VAULT_STORAGE_KEY, Vault, type VaultEnvelope, type VaultEnvelopeV1, type VaultEnvelopeV2, VaultError, type VaultErrorCode, type VaultKdfInfo, type VaultOptions, type VaultPasskey, type VaultStorage, ZCASH_BLOCKCHAIR, ZCASH_CHAIN, approvalChallenge, caip2FromChainId, canonicalJson, chainHex, chainTxMatcher, checkSenderOrigin, chromeAlarms, chromeJsonStorage, chromeKeyringStorage, chromeLocalVaultStorage, chromeSessionStorage, classifySignRequest, createSignHandler, decodedMessage, derToRaw, deriveStorageMacKey, describeSiwe, earnApprovalPayload, earnPlanMatchers, encodeApproveCalldata, evmCallMatcher, executionFloor, fromBase64Url, gasLimitExcessive, hostOf, isCatalogChain, isEnvelopeV1, isEnvelopeV2, isLocalHost, isPageEvent, isPageRequest, isPageResponse, isRelayMethod, isRelayRequest, isRelayToContent, levenshtein, lookalikeOf, macJsonStorage, memoryAlarms, memoryApprovalWindow, memoryJsonStorage, memorySessionStorage, memoryVaultStorage, messageText, newRequestId, nonEvmChain, normalizeHost, pageRequestFrom, parseAddChainParams, parseRawAddress, parseSiwe, parseSwapId, planMatchers, prepareTransaction, proofDomain, quoteRoutes, rank, rawToDer, relayError, revealHidden, reviewEarnPlan, reviewSwapPlan, siteOf, siweCrossSite, siweProblems, stampOrigin, storageVersionLedger, swapApprovalPayload, toBase64Url, toRelayError, tonConnectErrorCode, tonProofMessage, tonSignDataMessage, typedDataMatcher, vaultSecretStorage, verifyAssertion };