@anywalletkit/extension-kit 0.0.0-stage → 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,1479 @@
+import { KeyringStorage, SecretStorage } from '@anywalletkit/keyring';
+import { Quote, Swap2ExecutionPlan, CrossChainProvider, QuoteParams, IntentStatus } from '@anywalletkit/protocol-swap2-core';
+
+/** A vault or session rule was broken. Messages are safe to show the user and never contain secrets. */
+declare class VaultError extends Error {
+    readonly code: VaultErrorCode;
+    constructor(message: string, code: VaultErrorCode);
+}
+type VaultErrorCode = 
+/** The password did not open the vault (or the envelope was tampered with — AES-GCM cannot tell the two apart). */
+'wrong-password'
+/** `create` was called while a vault already exists — an existing wallet is never overwritten. */
+ | 'exists'
+/** `unlock` / `getSecret` on a storage area that holds no vault. */
+ | 'missing'
+/** The stored envelope has a version or shape this build does not read. */
+ | 'unsupported-envelope'
+/** The session is locked: the unlocked key is gone (auto-lock, browser exit, explicit lock). */
+ | 'locked'
+/** Bad input (empty or too-short password, bad key length, bad id). */
+ | 'invalid-input'
+/** The stored envelope's KDF parameters are below the floor this build accepts (edited on disk). */
+ | 'weak-kdf';
+
+/** PBKDF2-SHA256 iterations (v1 envelopes): OWASP 2023 floor for SHA-256; anything lower is refused. */
+declare const VAULT_MIN_ITERATIONS = 600000;
+declare const VAULT_DEFAULT_ITERATIONS = 600000;
+/** scrypt for v2 envelopes: OWASP's recommended cost (128 MiB, ~1 s in a service worker). */
+declare const VAULT_SCRYPT: {
+    readonly N: number;
+    readonly r: 8;
+    readonly p: 1;
+};
+/** The weakest scrypt an envelope may carry and still open (16 MiB). Tests use this; `create` uses {@link VAULT_SCRYPT}. */
+declare const VAULT_MIN_SCRYPT: {
+    readonly N: number;
+    readonly r: 8;
+    readonly p: 1;
+};
+/** Shortest password `create` / `changePassword` accept. `unlock` takes whatever opens the vault. */
+declare const VAULT_MIN_PASSWORD_LENGTH = 8;
+interface SealedBox {
+    /** 96-bit AES-GCM nonce, base64. */
+    iv: string;
+    /** ciphertext ‖ 128-bit tag, base64. */
+    data: string;
+}
+interface VaultEnvelopeV1 {
+    v: 1;
+    kdf: {
+        name: 'PBKDF2-SHA256';
+        iterations: number;
+        salt: string;
+    };
+    /** The DEK, sealed under the password-derived key. AAD = version + kdf. */
+    dek: SealedBox;
+    /** One box per key source (keyring source id), sealed under the DEK. AAD `forgewallet-vault/secret/<id>`. */
+    secrets: Record<string, SealedBox>;
+    createdAt: number;
+}
+interface VaultPasskey {
+    /** WebAuthn credential id, base64url. */
+    id: string;
+    label: string;
+    createdAt: number;
+    /** The DEK sealed under HKDF(PRF output, salt = credential id). AAD = `forgewallet-vault/2/passkey/<id>`. */
+    dek: SealedBox;
+    /** The credential's public key (SPKI, base64) when the authenticator gave one — lets the worker verify assertions (passkey-per-signature). */
+    publicKey?: string;
+    /** COSE algorithm of `publicKey` (-7 = ES256). */
+    alg?: number;
+}
+interface VaultEnvelopeV2 {
+    v: 2;
+    kdf: {
+        name: 'scrypt';
+        N: number;
+        r: number;
+        p: number;
+        salt: string;
+    };
+    dek: SealedBox;
+    secrets: Record<string, SealedBox>;
+    passkeys: VaultPasskey[];
+    createdAt: number;
+    /** When a v1 envelope was re-sealed as v2. */
+    upgradedAt?: number;
+}
+type VaultEnvelope = VaultEnvelopeV1 | VaultEnvelopeV2;
+/** Where the envelope lives. `chromeLocalVaultStorage()` for the extension, `memoryVaultStorage()` for tests. */
+interface VaultStorage {
+    get(): Promise<VaultEnvelope | null>;
+    set(envelope: VaultEnvelope): Promise<void>;
+    clear(): Promise<void>;
+}
+interface VaultOptions {
+    storage: VaultStorage;
+    /** KDF for NEW envelopes and re-seals. Default scrypt (v2); `'pbkdf2'` writes v1 (tests, or a build that must stay FIPS-only). */
+    kdf?: 'scrypt' | 'pbkdf2';
+    /** PBKDF2 iterations for v1 envelopes (default and minimum {@link VAULT_DEFAULT_ITERATIONS}). */
+    iterations?: number;
+    /** scrypt cost for v2 envelopes (default {@link VAULT_SCRYPT}; not below {@link VAULT_MIN_SCRYPT}). */
+    scrypt?: {
+        N: number;
+        r: number;
+        p: number;
+    };
+    /** Progress of the scrypt derivation, 0..1 — the unlock screen's bar. */
+    onProgress?: (fraction: number) => void;
+    /** Defaults to `globalThis.crypto`; injectable for tests. */
+    crypto?: Crypto;
+}
+interface VaultKdfInfo {
+    version: 1 | 2;
+    name: 'PBKDF2-SHA256' | 'scrypt';
+    /** Human line for the UI, e.g. "scrypt N=2^17 r=8 p=1". */
+    summary: string;
+}
+declare class Vault {
+    private readonly _storage;
+    private readonly _kdf;
+    private readonly _iterations;
+    private readonly _scrypt;
+    private readonly _onProgress;
+    private readonly _crypto;
+    constructor(options: VaultOptions);
+    exists(): Promise<boolean>;
+    /** What protects the DEK right now (UI). `null` without a vault. */
+    kdfInfo(): Promise<VaultKdfInfo | null>;
+    /**
+     * Create an empty vault protected by `password`. Returns the DEK — hand it to the
+     * session, then `setSecret` the first seed. Refuses when a vault exists.
+     */
+    create(password: string): Promise<Uint8Array>;
+    /**
+     * Derive the KEK from `password`, unseal and return the DEK. `wrong-password` on
+     * failure. A v1 (PBKDF2) envelope that opens is re-sealed as v2 (scrypt) on the
+     * way out, secrets untouched.
+     */
+    unlock(password: string): Promise<Uint8Array>;
+    /** Re-wrap the DEK under a new password (fresh salt, current KDF). Secrets and passkeys are untouched. */
+    changePassword(oldPassword: string, newPassword: string): Promise<void>;
+    /** Public view of the registered passkeys (ids, labels; whether each can verify assertions). */
+    listPasskeys(): Promise<Array<{
+        id: string;
+        label: string;
+        createdAt: number;
+        canVerify: boolean;
+    }>>;
+    /** The SPKI public key (base64) of one passkey, for assertion verification; `null` when unknown. */
+    passkeyPublicKey(id: string): Promise<{
+        publicKey: string;
+        alg: number;
+    } | null>;
+    /**
+     * Register a passkey as a second unlock path: the DEK (from the unlocked session)
+     * is sealed under HKDF-SHA256(`prf`, salt = credential id). The password stays
+     * the recovery path; `prf` is zeroized here. A v1 envelope must be unlocked (and
+     * thereby upgraded) first.
+     */
+    addPasskey(dek: Uint8Array, passkey: {
+        id: string;
+        prf: Uint8Array;
+        label: string;
+        publicKey?: string | undefined;
+        alg?: number | undefined;
+    }): Promise<void>;
+    /** Unseal the DEK with a passkey's PRF output. `wrong-password` when the box does not open, `missing` when the id is unknown. */
+    unlockWithPasskey(id: string, prf: Uint8Array): Promise<Uint8Array>;
+    removePasskey(id: string): Promise<void>;
+    listSecretIds(): Promise<string[]>;
+    /** Seal `secret` under the DEK as `sourceId` (overwrites an entry with the same id). */
+    setSecret(dek: Uint8Array, sourceId: string, secret: Uint8Array): Promise<void>;
+    /** Unseal one secret. `null` when the id is unknown; the caller zeroizes the result after use. */
+    getSecret(dek: Uint8Array, sourceId: string): Promise<Uint8Array | null>;
+    deleteSecret(sourceId: string): Promise<void>;
+    /** Remove the whole vault. The explicit destructive flow only (back up → wipe → create). */
+    destroy(): Promise<void>;
+    private _random;
+    /** A fresh envelope (v2 by default, v1 with `kdf: 'pbkdf2'`) wrapping `dek` under `password`. */
+    private _sealEnvelope;
+    /** The caller's DEK must open this envelope's secrets — it is the key the password protects, not any 32 bytes. */
+    private _requireDek;
+    private _derivePbkdf2;
+    private _deriveScrypt;
+    /** HKDF-SHA256(ikm = PRF output, salt = credential id bytes, info) → AES-256-GCM key. */
+    private _derivePasskeyKek;
+    private _importDek;
+    private _seal;
+    private _open;
+    private _load;
+}
+declare function isEnvelopeV1(x: unknown): x is VaultEnvelopeV1;
+declare function isEnvelopeV2(x: unknown): x is VaultEnvelopeV2;
+/** base64url (WebAuthn ids) → bytes; plain base64 is accepted too. */
+declare function fromBase64Url(text: string): Uint8Array;
+declare function toBase64Url(bytes: Uint8Array): string;
+/** Envelope in memory — tests and the smoke. */
+declare function memoryVaultStorage(initial?: VaultEnvelope | null): VaultStorage & {
+    envelope: VaultEnvelope | null;
+};
+
+/** Structural `chrome.storage.session` (or any `StorageArea`); `memorySessionStorage()` for tests. */
+interface SessionStorage {
+    get(key: string): Promise<unknown>;
+    set(key: string, value: unknown): Promise<void>;
+    remove(key: string): Promise<void>;
+}
+/** Structural `chrome.alarms`: one named alarm, fired once at `when` (ms since epoch). */
+interface SessionAlarms {
+    schedule(name: string, when: number): Promise<void> | void;
+    clear(name: string): Promise<void> | void;
+    /** Register the lock callback; the chrome adapter wires `chrome.alarms.onAlarm`. */
+    onFire(handler: (name: string) => void): void;
+}
+interface SessionOptions {
+    storage: SessionStorage;
+    alarms: SessionAlarms;
+    /** Lock this long after the last `touch` / `unlock`. Default 15 min; 0 disables the timer (lock only on browser exit or explicit lock). */
+    autoLockMs?: number;
+    /** Storage key and alarm name prefix. */
+    name?: string;
+    /** Clock, injectable for tests. */
+    now?: () => number;
+}
+declare const SESSION_DEFAULT_AUTOLOCK_MS: number;
+declare class Session {
+    private readonly _storage;
+    private readonly _alarms;
+    private _autoLockMs;
+    private readonly _key;
+    private readonly _alarm;
+    private readonly _now;
+    private readonly _onLock;
+    constructor(options: SessionOptions);
+    /** Store the DEK and arm the auto-lock. The caller's copy is zeroized. */
+    unlock(dek: Uint8Array): Promise<void>;
+    /** Forget the DEK and cancel the alarm. Safe to call when already locked. */
+    lock(): Promise<void>;
+    isUnlocked(): Promise<boolean>;
+    /**
+     * The DEK for one operation (zeroize it after). `locked` when there is none or the
+     * timer ran out while the worker was asleep — the record is then removed as well, so
+     * a missed alarm cannot keep the key alive.
+     */
+    getKey(): Promise<Uint8Array>;
+    /** User activity: push the auto-lock out again. No-op when locked. */
+    touch(): Promise<void>;
+    get autoLockMs(): number;
+    /** Change the timer (options page); re-arms from now when unlocked. 0 disables. */
+    setAutoLockMs(ms: number): Promise<void>;
+    onLock(callback: () => void): () => void;
+    private _expiry;
+    private _arm;
+    private _read;
+}
+/** In-memory `chrome.storage.session` stand-in. */
+declare function memorySessionStorage(): SessionStorage & {
+    data: Map<string, unknown>;
+};
+/** In-memory alarms: `fire(name)` from the test, `pending` to inspect. */
+declare function memoryAlarms(): SessionAlarms & {
+    pending: Map<string, number>;
+    fire(name: string): void;
+};
+
+/**
+ * Message shapes on the two hops between a dApp and the wallet:
+ *
+ * ```text
+ * page (injected provider, MAIN world)
+ *   │ window.postMessage — PageRequest ⇄ PageResponse / PageEvent
+ * content script (isolated world) — stamps `location.origin`, owns the port
+ *   │ chrome.runtime.connect(PORT_NAME) — RelayRequest ⇄ RelayResponse / RelayEvent
+ * service worker — trusts `port.sender` (set by the browser), never the page
+ * ```
+ *
+ * The page can forge anything it posts, so a page message carries no origin and
+ * no identity: the content script adds the origin, and the service worker
+ * cross-checks it against `port.sender.origin` ({@link checkSenderOrigin}) — a
+ * mismatch is dropped, not answered. Request ids are opaque strings minted by
+ * the page side ({@link newRequestId}); the content script does not reuse them
+ * across ports.
+ */
+/** `chrome.runtime.connect({ name })` for content-script ports. */
+declare const PORT_NAME = "anywalletkit/relay/1";
+/** `window.postMessage` discriminators (both directions). */
+declare const PAGE_TARGET: {
+    readonly toContent: "anywalletkit/content";
+    readonly toPage: "anywalletkit/page";
+};
+/** CAIP-2 namespace of the provider that spoke. */
+type RelayChain = 'eip155' | 'solana' | 'ton' | 'tron' | 'bip122' | 'near';
+interface RelayError {
+    /** EIP-1193 / EIP-1474 numbering for EVM; the same numbers are reused for the other providers. */
+    code: number;
+    message: string;
+    data?: unknown;
+}
+declare const RELAY_ERRORS: {
+    readonly userRejected: 4001;
+    readonly unauthorized: 4100;
+    readonly unsupportedMethod: 4200;
+    readonly disconnected: 4900;
+    readonly chainDisconnected: 4901;
+    /** EIP-3326/3085: the chain is not in the wallet (`wallet_switchEthereumChain` → suggest `wallet_addEthereumChain`). */
+    readonly chainNotAdded: 4902;
+    readonly internal: -32603;
+    readonly invalidRequest: -32600;
+    readonly invalidParams: -32602;
+    /** EIP-1474: a request of the same kind from this origin is already waiting (MetaMask's "already pending"). */
+    readonly resourceUnavailable: -32002;
+    /** EIP-1474: this origin has too many requests waiting. */
+    readonly limitExceeded: -32005;
+};
+interface PageRequest {
+    target: typeof PAGE_TARGET.toContent;
+    id: string;
+    chain: RelayChain;
+    method: string;
+    params?: unknown;
+}
+interface PageResponse {
+    target: typeof PAGE_TARGET.toPage;
+    id: string;
+    result?: unknown;
+    error?: RelayError;
+}
+interface PageEvent {
+    target: typeof PAGE_TARGET.toPage;
+    chain: RelayChain;
+    event: string;
+    data?: unknown;
+}
+interface RelayRequest {
+    kind: 'request';
+    id: string;
+    /** `location.origin` of the page, stamped by the content script. */
+    origin: string;
+    chain: RelayChain;
+    method: string;
+    params?: unknown;
+}
+interface RelayResponse {
+    kind: 'response';
+    id: string;
+    result?: unknown;
+    error?: RelayError;
+}
+interface RelayEvent {
+    kind: 'event';
+    chain: RelayChain;
+    event: string;
+    data?: unknown;
+}
+type RelayToWorker = RelayRequest;
+type RelayToContent = RelayResponse | RelayEvent;
+declare function isPageRequest(x: unknown): x is PageRequest;
+declare function isPageResponse(x: unknown): x is PageResponse;
+declare function isPageEvent(x: unknown): x is PageEvent;
+declare function isRelayRequest(x: unknown): x is RelayRequest;
+declare function isRelayToContent(x: unknown): x is RelayToContent;
+declare function newRequestId(): string;
+/** The content script's stamp: {@link PageRequest} + the page origin. */
+declare function stampOrigin(request: PageRequest, origin: string): RelayRequest;
+/** What `port.sender` looks like (structural `chrome.runtime.MessageSender`). */
+interface PortSender {
+    origin?: string | undefined;
+    url?: string | undefined;
+    tab?: {
+        id?: number | undefined;
+    } | undefined;
+    frameId?: number | undefined;
+}
+/**
+ * The service worker's check before it believes a stamped origin: it must equal the
+ * origin the browser recorded for the port. Returns the trusted origin or `null`.
+ */
+declare function checkSenderOrigin(sender: PortSender | undefined, stamped: string): string | null;
+declare const relayError: (code: number, message: string, data?: unknown) => RelayError;
+
+/**
+ * Adapters over the `chrome.*` APIs, typed structurally so this package needs no
+ * `@types/chrome` and tests can pass fakes. Promise forms (MV3) only.
+ */
+
+interface StorageAreaLike {
+    get(keys: string | string[]): Promise<Record<string, unknown>>;
+    set(items: Record<string, unknown>): Promise<void>;
+    remove(keys: string | string[]): Promise<void>;
+    /** `chrome.storage.session` only. */
+    setAccessLevel?(options: {
+        accessLevel: 'TRUSTED_CONTEXTS' | 'TRUSTED_AND_UNTRUSTED_CONTEXTS';
+    }): Promise<void>;
+}
+interface AlarmsLike {
+    create(name: string, info: {
+        when: number;
+    }): Promise<void> | void;
+    clear(name: string): Promise<boolean> | boolean | void;
+    onAlarm: {
+        addListener(callback: (alarm: {
+            name: string;
+        }) => void): void;
+    };
+}
+/** Stable storage key: existing vaults live under it — never rename. */
+declare const VAULT_STORAGE_KEY = "forgewallet.vault.v1";
+/** The encrypted envelope in `chrome.storage.local` (survives browser restarts; ciphertext only). */
+declare function chromeLocalVaultStorage(area: StorageAreaLike, key?: string): VaultStorage;
+/**
+ * `chrome.storage.session`: memory-only, gone when the browser exits. Access is
+ * pinned to trusted contexts (the default; made explicit so a content script can
+ * never read the unlocked key even if a later change opens the area to them).
+ */
+declare function chromeSessionStorage(area: StorageAreaLike): SessionStorage;
+/** `chrome.alarms` as one-shot named alarms. Chrome rounds alarms to ≥ 30 s in packed extensions. */
+declare function chromeAlarms(alarms: AlarmsLike): SessionAlarms;
+
+/** Stable storage key: existing keyrings live under it — never rename. */
+declare const KEYRING_STORAGE_KEY = "forgewallet.keyring.v1";
+/** Keyring metadata (no secrets) in `chrome.storage.local`. */
+declare function chromeKeyringStorage(area: StorageAreaLike, key?: string): KeyringStorage;
+/** Keyring secrets sealed in the vault; readable only while the session is unlocked. */
+declare function vaultSecretStorage(vault: Vault, session: Session): SecretStorage;
+
+/** One JSON value under one key — the shape every small store here needs. */
+interface JsonStorage<T> {
+    get(): Promise<T | null>;
+    set(value: T): Promise<void>;
+}
+declare function chromeJsonStorage<T>(area: StorageAreaLike, key: string): JsonStorage<T>;
+declare function memoryJsonStorage<T>(initial?: T | null): JsonStorage<T> & {
+    value: T | null;
+};
+
+interface EvmNetwork {
+    /** CAIP-2, `eip155:<chainId>`. */
+    caip2: string;
+    chainId: number;
+    name: string;
+    /** Native currency symbol, 18 decimals on every chain here (on Arc that is the 18-decimal native view of USDC). */
+    symbol: string;
+    /** Tried in order; the client fails over. */
+    rpcs: string[];
+    explorer?: string;
+    /** Set when a SITE supplied the RPC list (wallet_addEthereumChain): every sheet on this network says so and simulations are not trusted. */
+    custom?: {
+        origin: string;
+        addedAt: number;
+    };
+}
+declare const DEFAULT_CHAIN = "eip155:1";
+declare const DEFAULT_NETWORKS: readonly EvmNetwork[];
+declare const chainHex: (caip2: string) => string;
+/** `0x1` / `1` → `eip155:1`; `null` for anything that is not a positive integer chain id. */
+declare function caip2FromChainId(value: unknown): string | null;
+/** Whether the asset catalog knows this chain — the gate for `wallet_addEthereumChain`. */
+declare function isCatalogChain(caip2: string): boolean;
+/**
+ * Shipped networks plus the ones the user accepted from sites, persisted. Lookup
+ * by CAIP-2; a custom entry for a shipped chain is ignored (the build's RPC list
+ * wins — a site must not be able to replace Ethereum's endpoints).
+ */
+declare class NetworksTable {
+    private readonly storage;
+    private readonly defaults;
+    private _custom;
+    private _loading;
+    /** add/remove run one after another (scan F22, as PermissionStore). */
+    private _queue;
+    constructor(storage: JsonStorage<EvmNetwork[]>, defaults?: readonly EvmNetwork[]);
+    list(): Promise<EvmNetwork[]>;
+    get(caip2: string): Promise<EvmNetwork | null>;
+    add(network: EvmNetwork): Promise<void>;
+    remove(caip2: string): Promise<void>;
+    private serialize;
+    /** Cache first (readers see it at once), rolled back when storage refuses. */
+    private write;
+    private custom;
+}
+/**
+ * EIP-3085 `wallet_addEthereumChain` parameter → {@link EvmNetwork}, or the error
+ * to answer with. https RPC urls only; the chain id must be in the catalog.
+ */
+declare function parseAddChainParams(params: unknown, known?: (caip2: string) => boolean): EvmNetwork | RelayError;
+/** Solana mainnet as the catalog names it (`solana:mainnet`); the wallet package also accepts the genesis-hash form. */
+declare const SOLANA_CHAIN = "solana:mainnet";
+declare const SOLANA_RPCS: readonly string[];
+declare const TON_CHAIN = "ton:-239";
+declare const TON_ENDPOINTS: readonly string[];
+declare const TRON_CHAIN = "tron:728126428";
+declare const TRON_PROVIDERS: readonly string[];
+declare const BTC_CHAIN = "bitcoin:mainnet";
+declare const BTC_ESPLORA: readonly string[];
+declare const NEAR_CHAIN = "near:mainnet";
+declare const NEAR_PROVIDERS: readonly string[];
+/** Zcash transparent (t1…) accounts over Blockchair's public API, as `@anywalletkit/wallet-zcash` reads and broadcasts them. */
+declare const ZCASH_CHAIN = "zcash:mainnet";
+declare const ZCASH_BLOCKCHAIR = "https://api.blockchair.com/zcash";
+interface ChainDescriptor {
+    caip2: string;
+    key: 'solana' | 'ton' | 'tron' | 'btc' | 'near' | 'zcash';
+    name: string;
+    symbol: string;
+    decimals: number;
+    explorerTx: string;
+    explorerAddress: string;
+}
+declare const NON_EVM_CHAINS: readonly ChainDescriptor[];
+declare const nonEvmChain: (caip2: string) => ChainDescriptor | undefined;
+
+/**
+ * Per-origin permissions: which accounts a site may see and which chain it is
+ * on. Nothing here is secret (`chrome.storage.local`, plain JSON); the origin
+ * key is the one the browser recorded for the port, never the page's claim.
+ */
+
+interface OriginPermission {
+    origin: string;
+    /** EVM addresses exposed to this origin (checksummed as the keyring stores them). Empty when only another chain is connected. */
+    accounts: string[];
+    /** CAIP-2 chain the origin currently sees (`eth_chainId`). */
+    chain: string;
+    /** Solana addresses exposed to this origin (Wallet Standard `standard:connect`). */
+    solanaAccounts?: string[];
+    /** TON addresses exposed to this origin (TON Connect). */
+    tonAccounts?: string[];
+    /** Tron (TIP-1193), Bitcoin (sats-connect) and NEAR (wallet-selector) addresses. */
+    tronAccounts?: string[];
+    btcAccounts?: string[];
+    nearAccounts?: string[];
+    connectedAt: number;
+}
+type PermissionsState = Record<string, OriginPermission>;
+type ChainAccountsKey = 'solanaAccounts' | 'tonAccounts' | 'tronAccounts' | 'btcAccounts' | 'nearAccounts';
+declare const CHAIN_ACCOUNT_KEYS: readonly ChainAccountsKey[];
+declare class PermissionStore {
+    private readonly storage;
+    private _state;
+    private _loading;
+    /** Every mutation runs here, one after another (scan F22): a read-modify-write never starts from a snapshot another one is about to replace. */
+    private _queue;
+    private readonly _listeners;
+    constructor(storage: JsonStorage<PermissionsState>);
+    private state;
+    /**
+     * Run `fn` after every earlier mutation settled. Public mutators wrap their WHOLE read-modify-write
+     * in this; `write` itself is unlocked (setAccountsEverywhere calls it in a loop — a lock there too
+     * would deadlock). Nothing awaited inside may wait on the user: routers await the approval sheet
+     * first and only then call the store.
+     */
+    private serialize;
+    get(origin: string): Promise<OriginPermission | null>;
+    list(): Promise<OriginPermission[]>;
+    connect(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>;
+    /**
+     * 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).
+     * Lock never writes `[]` here, so the skip cannot strip a real EVM grant.
+     */
+    setAccountsEverywhere(accounts: string[]): Promise<OriginPermission[]>;
+    disconnect(origin: string): Promise<void>;
+    onChange(listener: (origin: string, permission: OriginPermission | null) => void): () => void;
+    /** Unlocked: callers hold the queue. The cache changes before the await (readers see it at once) and is rolled back when storage refuses. */
+    private write;
+}
+
+declare class ReviewDeclined extends Error {
+    readonly code: 4001;
+    constructor(message?: string);
+}
+type ApprovalKind = 'connect' | 'switch-chain' | 'add-chain' | 'sign-message' | 'sign-typed-data' | 'send-transaction' | 'solana-send' | 'swap' | 'earn' | 'chain-send' | 'tron-sign' | 'btc-sign' | 'near-sign' | 'near-signin' | 'wc-session';
+/** How a request reached the wallet when it did not come through a content script. */
+interface OriginVia {
+    transport: 'walletconnect';
+    /** What the dApp declared about itself (self-reported, unverified unless `verify` says so). */
+    url: string;
+    name: string;
+    /** WalletConnect Verify: VALID = the relay saw the request come from `url`'s origin; INVALID = it came from somewhere else; UNKNOWN = not attested. */
+    verify: 'VALID' | 'INVALID' | 'UNKNOWN';
+    scam?: boolean;
+}
+/** The queue refused to enqueue (per-origin limits); carries an EIP-1474 code the page understands. */
+declare class QueueLimitError extends Error {
+    readonly code: number;
+    constructor(code: number, message: string);
+}
+declare const APPROVALS_MAX_PENDING_PER_ORIGIN = 3;
+interface ApprovalRequest<P = unknown> {
+    id: string;
+    origin: string;
+    chain: string;
+    kind: ApprovalKind;
+    /** What the window shows; shape per kind, public data only. */
+    payload: P;
+    createdAt: number;
+    /** Phishing / lookalike / punycode notes about the origin, from the queue's `annotate` hook. */
+    originWarnings?: string[];
+    /** Set when the origin is a transport pseudo-origin (`wc:<topic>`): what the sheet should say about where this came from. */
+    via?: OriginVia;
+}
+interface ApprovalQueueOptions {
+    /** Called for every request's origin; the lines are shown on the sheet (e.g. the shipped phishing list's verdict). */
+    annotate?: (origin: string) => string[];
+    /** Requests one origin may have waiting (current + queued). Default {@link APPROVALS_MAX_PENDING_PER_ORIGIN}. */
+    maxPendingPerOrigin?: number;
+}
+/** The window side: open for one request, close when it is answered. `memoryApprovalWindow()` for tests. */
+interface ApprovalWindow {
+    open(request: ApprovalRequest): Promise<void>;
+    close(requestId: string): Promise<void>;
+    /** The user closed the window themself (chrome.windows.onRemoved): the queue declines the request. */
+    onClosed(handler: (requestId: string) => void): void;
+}
+declare class ApprovalQueue {
+    private readonly window;
+    private readonly newId;
+    private readonly options;
+    private _current;
+    private readonly _waiting;
+    private readonly _listeners;
+    private readonly _via;
+    constructor(window: ApprovalWindow, newId?: () => string, options?: ApprovalQueueOptions);
+    /** 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>;
+    /** 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;
+    /** Requests waiting for `origin` (current + queued). */
+    pendingFor(origin: string): number;
+    /** The request currently shown (the window asks for it by id on load). */
+    get current(): ApprovalRequest | null;
+    get queued(): number;
+    resolve(requestId: string, value: unknown): boolean;
+    decline(requestId: string, error?: Error): boolean;
+    /** Lock, disconnect, shutdown: everything pending is declined. */
+    declineAll(error?: Error): void;
+    onChange(listener: () => void): () => void;
+    private settle;
+    private next;
+    private emit;
+}
+/** In-memory window: tests answer through the queue; `opened` records every request shown. */
+declare function memoryApprovalWindow(): ApprovalWindow & {
+    opened: ApprovalRequest[];
+    openIds: Set<string>;
+    userClose(id: string): void;
+};
+
+/**
+ * The request router: what a dApp may ask and what happens to each request.
+ * Policy ported from Vaulty's in-app browser (`mobile/lib/browser.ts`):
+ *
+ * - the origin is the browser's (checked by the service worker before this runs);
+ * - accounts are exposed only to origins the user connected (`eth_requestAccounts`
+ *   → approval window); `eth_accounts` is `[]` otherwise;
+ * - chain switching and adding go through the approval window; a chain can be
+ *   added only if the asset catalog knows it, with https RPCs;
+ * - read-only JSON-RPC is answered from the wallet's own clients (the networks
+ *   table's failover list), never from a URL the page names;
+ * - `eth_sign` (blind hash signing) is never offered; the other signing methods
+ *   go to the `sign` hook (the review flow) when the wallet provides one;
+ * - everything else is refused with 4200.
+ *
+ * Errors leave as {@link RouterError} (EIP-1193 codes) or {@link ReviewDeclined}
+ * (4001); the service worker turns both into a `RelayResponse.error`.
+ */
+
+declare class RouterError extends Error {
+    readonly code: number;
+    readonly data: unknown;
+    constructor(code: number, message: string, data?: unknown);
+    static from(e: RelayError): RouterError;
+}
+/** Any error → the `RelayError` for the page. Unknown errors keep their message but never their stack. */
+declare function toRelayError(e: unknown): RelayError;
+/** Read-only methods answered from our RPC without asking the user. */
+declare const READ_METHODS: ReadonlySet<string>;
+/** Methods that produce a signature — the review flow's business (step 4), never answered here. */
+declare const SIGNING_METHODS: ReadonlySet<string>;
+interface ConnectApproval {
+    /** Addresses the wallet can expose, active account first (empty while locked — the window unlocks first and reloads). */
+    accounts: string[];
+}
+interface SwitchChainApproval {
+    from: EvmNetwork | null;
+    to: EvmNetwork;
+}
+interface AddChainApproval {
+    network: EvmNetwork;
+}
+interface RouterDeps {
+    permissions: PermissionStore;
+    networks: NetworksTable;
+    approvals: ApprovalQueue;
+    /** EVM addresses the wallet exposes, active account first. Empty when locked or without a wallet. */
+    accounts(): Promise<string[]>;
+    /** Read-only JSON-RPC over the network's own RPC list. */
+    rpc(network: EvmNetwork, method: string, params: unknown[]): Promise<unknown>;
+    /** Push an EIP-1193 event to every page of `origin`. */
+    emit(origin: string, event: string, data: unknown): void;
+    /** The review flow for signing methods. Absent → 4200. */
+    sign?(input: {
+        origin: string;
+        network: EvmNetwork;
+        method: string;
+        params: unknown[];
+        accounts: string[];
+    }): Promise<unknown>;
+    defaultChain?: string;
+}
+declare class RequestRouter {
+    private readonly deps;
+    constructor(deps: RouterDeps);
+    /** The chain an origin currently sees (its permission's, else the default). */
+    chainFor(origin: string): Promise<EvmNetwork>;
+    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;
+    /**
+     * Connected and unlocked → the accounts; otherwise the approval window (which
+     * unlocks first when needed) picks them. Emits `connect` + `accountsChanged`.
+     */
+    private connect;
+    disconnect(origin: string): Promise<void>;
+    private switchChain;
+}
+
+/**
+ * Sign-In with Ethereum (EIP-4361) messages, parsed so the sheet can say what a
+ * `personal_sign` really is and check the fields a phishing site would lie
+ * about: the domain (scheme + host) must be the site asking, the address must
+ * be the signing account, the chain must be the site's, the message must not be
+ * expired or not-yet-valid, and the nonce must look like one (replay).
+ *
+ * Everything here is a WARNING: the sheet turns problems into warn checks and
+ * the user can still sign. Whenever the first line is an EIP-4361 header the
+ * text is treated as a sign-in (scan F9) — a message whose remaining fields do
+ * not parse is reported as malformed instead of silently becoming a plain
+ * message without the cross-site check.
+ */
+
+interface SiweMessage {
+    /** As written in the header: `host[:port]`, optionally prefixed by `scheme://`. */
+    domain: string;
+    address: string;
+    statement?: string;
+    uri: string;
+    version: string;
+    chainId: number;
+    nonce: string;
+    issuedAt: string;
+    expirationTime?: string;
+    notBefore?: string;
+    requestId?: string;
+    resources: string[];
+}
+interface SiweInfo {
+    message: SiweMessage;
+    /** Human lines, each a reason the sheet should warn; empty = the sign-in is consistent with the request. */
+    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;
+}
+interface SiweContext {
+    /** The page that asked, as the browser recorded it (`https://…`), or a transport pseudo-origin (`wc:<topic>`). */
+    origin: string;
+    /** The signing address. */
+    account: string;
+    /** The site's chain. */
+    chainId: number;
+    now?: number;
+    /** Transport note for pseudo-origins (WalletConnect): the dApp's claimed URL and what Verify said about it. */
+    via?: OriginVia;
+}
+/** `null` when the text is not a well-formed EIP-4361 message (see {@link describeSiwe} for the tolerant form the sheet uses). */
+declare function parseSiwe(text: string): SiweMessage | null;
+/** Loopback / `*.localhost` (dev servers): plain http is normal there, so no scheme warnings. Takes `host[:port]`. */
+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[];
+/** `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;
+
+/**
+ * Signing requests from dApps (and from the wallet's own Send): classification,
+ * transaction preparation, the review stop, the signature.
+ *
+ * Classification is Vaulty's `signingRequest` (mobile/lib/browser.ts): the
+ * address a page names must be one the user connected; typed data bound to
+ * another chain than the one the site is on is refused (4901); a transaction
+ * must have a `to` (no deployments) and a `chainId`, when given, equal to the
+ * site's chain; `eth_sign` never reaches here (the router refuses it).
+ *
+ * Preparation fills nonce, gas and fees from the wallet's own RPC (never the
+ * page's): EIP-1559 cap = 2 × base fee + tip with the tip floored at 0.1 gwei
+ * (Vaulty's `evmFees`), legacy `gasPrice` where a chain has no base fee, gas =
+ * the page's limit or `eth_estimateGas` × 1.2.
+ *
+ * The review payload ({@link SignApproval}) carries what the window shows: the
+ * classified request, the prepared fields, the fee, and the preview the wallet
+ * attached (tx-preview-evm: decode, simulation, balance changes, checks). Only
+ * after the user approves does {@link SignDeps.signerFor} open the key; the
+ * handle is disposed (zeroized) in `finally`, the raw transaction goes out via
+ * `eth_sendRawTransaction` on the wallet's RPC.
+ */
+
+type SignRequestInfo = {
+    kind: 'sign-message';
+    method: 'personal_sign';
+    account: string; /** Decoded text when printable, else the hex. */
+    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;
+} | {
+    kind: 'sign-typed-data';
+    method: string;
+    account: string; /** Pretty-printed JSON. */
+    text: string;
+    typedData: TypedData;
+} | {
+    kind: 'send-transaction';
+    method: 'eth_sendTransaction';
+    account: string;
+    tx: {
+        to: string;
+        value: string;
+        data: string | null;
+        gas: string | null;
+    };
+};
+interface TypedData {
+    domain: Record<string, unknown>;
+    types: Record<string, Array<{
+        name: string;
+        type: string;
+    }>>;
+    message: Record<string, unknown>;
+    primaryType?: string;
+}
+interface PreparedTx {
+    chainId: number;
+    nonce: number;
+    gasLimit: string;
+    /** EIP-1559 fields, or `gasPrice` on legacy-fee chains. All 0x hex. */
+    maxFeePerGas?: string;
+    maxPriorityFeePerGas?: string;
+    gasPrice?: string;
+    /** gasLimit × max fee, base units. */
+    maxFee: string;
+}
+/** The approval window's payload for the three signing kinds. */
+interface SignApproval {
+    request: SignRequestInfo;
+    network: EvmNetwork;
+    prepared?: PreparedTx;
+    /** What the wallet attached (tx-preview-evm `TxPreview`, typed-data description…). */
+    preview: unknown;
+}
+interface EvmSigner {
+    signMessage(message: string | Uint8Array): Promise<string>;
+    signTypedData(typed: TypedData): Promise<string>;
+    /** Fully specified tx (chainId, nonce, gas, fees) → signed raw transaction. */
+    signTransaction(tx: {
+        chainId: number;
+        nonce: number;
+        to: string;
+        value: bigint;
+        data: string;
+        gasLimit: bigint;
+        maxFeePerGas?: bigint;
+        maxPriorityFeePerGas?: bigint;
+        gasPrice?: bigint;
+    }): Promise<string>;
+}
+interface SignDeps {
+    approvals: ApprovalQueue;
+    rpc(network: EvmNetwork, method: string, params: unknown[]): Promise<unknown>;
+    /** Opens the key for `address`; `dispose()` zeroizes it. */
+    signerFor(address: string, network: EvmNetwork): Promise<{
+        signer: EvmSigner;
+        dispose(): void;
+    }>;
+    /** Review data for the window (errors inside are the wallet's to swallow → `null`). */
+    preview?(input: {
+        network: EvmNetwork;
+        request: SignRequestInfo;
+        accounts: string[];
+    }): Promise<unknown>;
+    /** Tip floor per chain id in wei (default 0.1 gwei everywhere). */
+    tipFloor?: (chainId: number) => bigint;
+}
+/** Vaulty's `messageText`: hex that decodes to printable text is shown decoded; binary payloads stay hex. */
+declare function messageText(value: unknown): string;
+/**
+ * The message as the signer will sign it: hex decoded when it is valid UTF-8, whatever
+ * its printability (scan 2026-10-23 F7 — the SIWE checks must read the bytes that get
+ * 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;
+    params: unknown[];
+    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;
+}): SignRequestInfo | RelayError;
+/** Nonce, gas, fees from the wallet's RPC. */
+declare function prepareTransaction(deps: Pick<SignDeps, 'rpc' | 'tipFloor'>, network: EvmNetwork, from: string, tx: {
+    to: string;
+    value: string;
+    data: string | null;
+    gas: string | null;
+}): Promise<PreparedTx>;
+/** The router's `sign` hook: classify → prepare → review → sign (→ broadcast). */
+declare function createSignHandler(deps: SignDeps): NonNullable<RouterDeps['sign']>;
+
+/**
+ * Pre-approvals — the second half of Vaulty's `txGate` (mobile/lib/txGate.ts).
+ * A flow that reviewed a WHOLE plan in one sheet (a swap: approvals + source
+ * leg) registers one matcher per operation it is about to perform; the
+ * reviewed account then lets exactly those operations through without a second
+ * window, each once, within `ttlMs`. Anything else still stops at the review.
+ */
+type GatedOp = {
+    kind: 'evm-tx';
+    caip2: string;
+    to: string;
+    data?: string;
+    value: bigint;
+} | {
+    kind: 'evm-typed-data';
+    caip2: string;
+} | {
+    kind: 'solana-transfer';
+    to: string;
+    amount: bigint;
+    token?: string;
+} | {
+    kind: 'solana-tx';
+    to: string;
+    value: bigint;
+} | {
+    kind: 'solana-serialized';
+    serializedTx: string;
+}
+/** A module-built Solana transaction message (instructions), reviewed as a plan. */
+ | {
+    kind: 'solana-message';
+}
+/** TON / Tron / Bitcoin / NEAR send or token transfer (amount in base units; token = jetton master / TRC-20 / NEP-141 id). */
+ | {
+    kind: 'chain-tx';
+    chain: string;
+    to: string;
+    amount: bigint;
+    token?: string | undefined;
+    memo?: string | undefined;
+};
+type GateMatcher = (op: GatedOp) => boolean;
+declare class ReviewGate {
+    private readonly now;
+    private approved;
+    constructor(now?: () => number);
+    /** Each matcher passes ONE operation, within `ttlMs` (default 10 min). */
+    preApprove(matchers: GateMatcher[], ttlMs?: number): void;
+    /** True (and the matcher is spent) when a pre-approval covers `op`. */
+    consume(op: GatedOp): boolean;
+    get pending(): number;
+    clear(): void;
+}
+/** Matcher for an exact EVM call: same chain, `to`, calldata and value. */
+declare function evmCallMatcher(expected: {
+    caip2: string;
+    to: string;
+    data?: string | undefined;
+    value: bigint;
+}): GateMatcher;
+/** Matcher for a non-EVM send: same chain, recipient, amount, token and memo. */
+declare function chainTxMatcher(expected: {
+    chain: string;
+    to: string;
+    amount: bigint;
+    token?: string | undefined;
+    memo?: string | undefined;
+}): GateMatcher;
+
+/**
+ * Swaps for the extension, the DIRECT path of Vaulty mobile's `lib/swap2.ts`:
+ * the providers run in the service worker and talk to their APIs themselves.
+ *
+ * - {@link quoteRoutes}: dry quotes from every provider that can serve the
+ *   pair, delivered progressively (`onUpdate` fires as each venue answers), with
+ *   BEST / FASTEST tags and every refusal named.
+ *   TODO: replace with `CrossChainRouter.getQuotes` (net-USD ranking,
+ *   RouteSet). Until then this fan-out over the public `CrossChainProvider`
+ *   interface ranks by output amount.
+ * - {@link reviewSwapPlan}: the engine's `reviewExecution` hook — one sheet for
+ *   the whole plan (approvals + source leg) BEFORE anything is signed; on
+ *   approval exactly those operations are pre-approved in the {@link ReviewGate}
+ *   so the reviewed account lets them through once; a decline aborts with
+ *   nothing sent (`ReviewDeclined`, 4001).
+ */
+
+interface RouteView {
+    provider: string;
+    destAmount: string;
+    minDestAmount: string;
+    feeUsd: number;
+    /** On-chain pool venues take the fee inside the output; "$0.00" would mislead. */
+    feeNote?: string;
+    etaSeconds: number;
+    validUntilMs: number;
+    tags: ('best' | 'fastest')[];
+}
+interface RouteListView {
+    routes: RouteView[];
+    /** Providers still quoting. */
+    pending: string[];
+    /** Provider → why it sat out (refusal, error, timeout). */
+    refusals: Record<string, string>;
+    /** The quotes themselves, by provider, for execution with the same numbers the user saw. */
+    quotes: Record<string, Quote>;
+}
+interface QuoteRoutesOptions {
+    onUpdate?: (view: RouteListView) => void;
+    /** Per-provider wall clock (default 20 s). */
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    now?: () => number;
+}
+/** 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[];
+/** 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;
+interface SwapReviewMeta {
+    /** Who runs the flow (the wallet's origin). */
+    origin: string;
+    providerLabel: string;
+    fromSymbol: string;
+    fromDecimals: number;
+    toSymbol: string;
+    toDecimals: number;
+    fromChainName: string;
+    toChainName: string;
+    /** All of the user's addresses — recipient own/foreign. */
+    own: string[];
+}
+/** What the swap sheet renders. Amounts are base-unit strings. */
+interface SwapApproval {
+    provider: string;
+    providerLabel: string;
+    fromChain: string;
+    toChain: string;
+    fromChainName: string;
+    toChainName: string;
+    send: {
+        symbol: string;
+        decimals: number;
+        amount: string;
+    };
+    receive: {
+        symbol: string;
+        decimals: number;
+        amount: string;
+        min: string;
+    };
+    recipient: {
+        address: string;
+        isOwn: boolean;
+    };
+    refundAddress: string;
+    feeUsd: number;
+    etaSeconds: number;
+    validUntilMs: number;
+    approvals: {
+        token: string;
+        spender: string;
+        amount: string;
+    }[];
+    source: {
+        kind: 'call';
+        to: string;
+        data?: string;
+        value: string;
+        deposit?: string;
+    } | {
+        kind: 'token-transfer';
+        token: string;
+        recipient: string;
+        amount: string;
+        memo?: string;
+    } | {
+        kind: 'serialized';
+    } | {
+        kind: 'typed-order';
+    };
+    checks: {
+        status: 'ok' | 'warn' | 'unknown';
+        label: string;
+    }[];
+}
+declare const encodeApproveCalldata: (spender: string, amount: bigint) => string;
+declare function swapApprovalPayload(plan: Swap2ExecutionPlan, meta: SwapReviewMeta): SwapApproval;
+/** Matchers for exactly the operations the plan will perform, in the engine's order. */
+declare function planMatchers(plan: Swap2ExecutionPlan): GateMatcher[];
+/** The engine's `reviewExecution`: one sheet for the plan; approve → pre-approve exactly its operations; decline → nothing sent. */
+declare function reviewSwapPlan(approvals: ApprovalQueue, gate: ReviewGate, meta: SwapReviewMeta): (plan: Swap2ExecutionPlan) => Promise<void>;
+
+/**
+ * Pending swaps across service-worker restarts: records in `chrome.storage.local`,
+ * a `chrome.alarms` tick every minute while anything is active, resumable by
+ * the swap2 id (`awk1.<provider>.<intent>[.<sourceTxHash>]`), the provider's
+ * `trackIntent` as the only source of truth.
+ *
+ * States (the provider's `IntentState` plus the wallet's own `claiming`):
+ *   pending ──deposit seen──▶ pending (depositReceived)
+ *   pending ──attested (CCTP)──▶ action-required ──user claims──▶ claiming ──mint seen──▶ completed
+ *   pending ──▶ completed | failed | refunded | refund-pending | partial | cancelled | expired
+ * A tracker error leaves the record as it was (with `lastError`); a record older
+ * than `giveUpAfterMs` with no progress becomes `expired` so the alarm stops.
+ */
+
+type SwapRecordStatus = IntentStatus['state'] | 'claiming';
+interface SwapRecord {
+    /** swap2 id — `awk1.<provider>.<intentId>[.<sourceTxHash>]`. */
+    id: string;
+    provider: string;
+    fromChain: string;
+    toChain: string;
+    fromToken: string;
+    toToken: string;
+    /** Base units. */
+    amountIn: string;
+    destAmount: string;
+    recipient: string;
+    sourceTxHash: string | null;
+    destTxHash: string | null;
+    status: SwapRecordStatus;
+    depositReceived?: boolean;
+    /** Two-phase routes: where and whether the claim can be built now. */
+    claim?: {
+        chain: string;
+        ready: boolean;
+    };
+    createdAt: number;
+    updatedAt: number;
+    /** Last tracker problem (RPC/API), kept until the next successful check. */
+    lastError?: string;
+    checks: number;
+}
+declare const ACTIVE_STATUSES: ReadonlySet<SwapRecordStatus>;
+declare function parseSwapId(id: string): {
+    provider: string;
+    intentId: string;
+    sourceTxHash?: string;
+} | null;
+declare class SwapsStore {
+    private readonly storage;
+    private _records;
+    private readonly _listeners;
+    constructor(storage: JsonStorage<SwapRecord[]>);
+    list(): Promise<SwapRecord[]>;
+    get(id: string): Promise<SwapRecord | null>;
+    active(): Promise<SwapRecord[]>;
+    add(record: SwapRecord): Promise<void>;
+    update(id: string, patch: Partial<SwapRecord>): Promise<SwapRecord | null>;
+    remove(id: string): Promise<void>;
+    onChange(listener: () => void): () => void;
+    private write;
+}
+interface SwapTrackerDeps {
+    store: SwapsStore;
+    /** The provider's view of the swap (`CrossChainRouter.trackIntent`). */
+    status(record: SwapRecord): Promise<IntentStatus>;
+    /** Start / stop the periodic alarm (`chrome.alarms.create(name, { periodInMinutes: 1 })`). */
+    alarm: {
+        start(): Promise<void> | void;
+        stop(): Promise<void> | void;
+    };
+    now?: () => number;
+    /** No progress for this long → `expired` (default 48 h). */
+    giveUpAfterMs?: number;
+}
+declare class SwapTracker {
+    private readonly deps;
+    private readonly now;
+    private ticking;
+    constructor(deps: SwapTrackerDeps);
+    /** Record a just-executed swap and make sure the alarm runs. */
+    track(input: Omit<SwapRecord, 'createdAt' | 'updatedAt' | 'checks' | 'status' | 'destTxHash'> & {
+        status?: SwapRecordStatus;
+    }): Promise<SwapRecord>;
+    /** After the user's claim transaction went out: keep polling until the provider sees the mint. */
+    claimed(id: string, destTxHash: string): Promise<void>;
+    /** One alarm tick: check every active record once; stop the alarm when nothing is active. Concurrent ticks coalesce. */
+    tick(): Promise<void>;
+    private run;
+}
+
+/**
+ * Earn plan review — the Earn modules' counterpart of the swap sheet. A module
+ * that exposes its plan (Aave / Morpho `planSupply` & co: ERC-20 approvals
+ * first, then the call) gets ONE sheet for the whole plan; on approval exactly
+ * those calls are pre-approved in the {@link ReviewGate} so the module's own
+ * `supply()` / `withdraw()` / … passes through the reviewed account without a
+ * second window. Modules without a plan API (Mellow, Lido, SSV, Jito) are
+ * reviewed per transaction by the reviewed account itself — still every send.
+ */
+
+interface EarnTx {
+    to: string;
+    data?: string | undefined;
+    /** Base units, decimal string. */
+    value: string;
+}
+interface EarnPlan {
+    approvals: EarnTx[];
+    tx: EarnTx;
+}
+interface EarnReviewMeta {
+    origin: string;
+    /** 'Aave v3', 'Morpho', … */
+    module: string;
+    /** 'Supply', 'Withdraw', 'Borrow', 'Repay', 'Stake', … */
+    action: string;
+    network: EvmNetwork;
+    /** Human lines the sheet shows (asset, amount, APY, market/vault, health factor…). */
+    facts: {
+        k: string;
+        v: string;
+    }[];
+    /** What the module says about the plan (its own refusals never reach here — they throw before). */
+    checks?: {
+        status: 'ok' | 'warn' | 'unknown';
+        label: string;
+    }[];
+    /** tx-preview-evm result for approvals + call, attached by the wallet (JSON-safe) or null. */
+    preview?: unknown;
+}
+interface EarnApproval {
+    module: string;
+    action: string;
+    network: EvmNetwork;
+    facts: {
+        k: string;
+        v: string;
+    }[];
+    approvals: EarnTx[];
+    tx: EarnTx;
+    checks: {
+        status: 'ok' | 'warn' | 'unknown';
+        label: string;
+    }[];
+    preview: unknown;
+}
+declare function earnPlanMatchers(network: EvmNetwork, plan: EarnPlan): GateMatcher[];
+declare function earnApprovalPayload(plan: EarnPlan, meta: EarnReviewMeta): EarnApproval;
+/** One sheet for the plan; approve → pre-approve exactly its calls; decline → ReviewDeclined, nothing sent. */
+declare function reviewEarnPlan(approvals: ApprovalQueue, gate: ReviewGate, meta: EarnReviewMeta, plan: EarnPlan): Promise<void>;
+
+declare const TONCONNECT_ERRORS: {
+    readonly unknown: 0;
+    readonly badRequest: 1;
+    readonly manifestNotFound: 2;
+    readonly manifestContent: 3;
+    readonly unknownApp: 100;
+    readonly userDeclined: 300;
+    readonly methodNotSupported: 400;
+};
+declare class TonConnectError extends Error {
+    readonly code: number;
+    constructor(code: number, message: string);
+}
+interface TonConnectRequest {
+    manifestUrl: string;
+    /** `ton_addr` always; `ton_proof` with the dApp's payload when asked. */
+    proofPayload?: string;
+}
+declare function parseConnectRequest(message: unknown): TonConnectRequest;
+interface TonConnectMessage {
+    /** Destination, as given (friendly or raw). */
+    address: string;
+    /** Nanotons, decimal string. */
+    amount: string;
+    /** base64 BoC body. */
+    payload?: string;
+    /** base64 BoC state init. */
+    stateInit?: string;
+}
+interface TonConnectSendTransaction {
+    validUntil?: number;
+    network?: string;
+    from?: string;
+    messages: TonConnectMessage[];
+}
+declare const TONCONNECT_MAX_MESSAGES = 4;
+/** `sendTransaction` params[0] (a JSON string per the spec, or an object). */
+declare function parseSendTransaction(param: unknown, options?: {
+    maxMessages?: number;
+    network?: string;
+}): TonConnectSendTransaction;
+type TonSignDataPayload = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'binary';
+    bytes: string;
+};
+/** `signData` params[0]: text or binary only — `cell` payloads need schema-aware rendering and are refused by name. */
+declare function parseSignData(param: unknown): TonSignDataPayload;
+interface TonAddressParts {
+    workchain: number;
+    hash: Uint8Array;
+}
+/** The bytes a wallet signs for `ton_proof` (already hashed — sign them raw with ed25519). */
+declare function tonProofMessage(input: {
+    address: TonAddressParts;
+    domain: string;
+    timestamp: number;
+    payload: string;
+}): Uint8Array;
+/** The bytes a wallet signs for `signData` (text / binary). */
+declare function tonSignDataMessage(input: {
+    address: TonAddressParts;
+    domain: string;
+    timestamp: number;
+    payload: TonSignDataPayload;
+}): Uint8Array;
+/** `0:abcd…` → parts; friendly addresses are the wallet package's job (it hands us the raw form). */
+declare function parseRawAddress(raw: string): TonAddressParts;
+/** The dApp's domain for proofs, from the page origin (host only, as the spec's `domain.value`). */
+declare function proofDomain(origin: string): string;
+/** Our relay errors → TON Connect error codes. */
+declare function tonConnectErrorCode(e: unknown): number;
+
+/**
+ * Phishing / impersonation checks on a page's host, against a SHIPPED list
+ * (never fetched at runtime — decision 10). The list format is MetaMask's
+ * eth-phishing-detect `config.json`: `blacklist` / `whitelist` (hosts; a listed
+ * domain covers its subdomains), `fuzzylist` + `tolerance` (well-known hosts a
+ * lookalike is measured against by Levenshtein distance). On top: punycode
+ * (`xn--`) labels are flagged, because mixed-script lookalikes are the common
+ * impersonation shape.
+ */
+interface PhishingList {
+    version?: number;
+    tolerance?: number;
+    blacklist: readonly string[];
+    whitelist?: readonly string[];
+    fuzzylist?: readonly string[];
+    /** The wallet's own additions to the fuzzylist (the big dApps our users visit): same semantics. */
+    extraFuzzylist?: readonly string[];
+}
+interface HostCheck {
+    host: string;
+    /** On the blocklist (or a subdomain of a listed domain): refuse to inject / connect. */
+    blocked: boolean;
+    /** Human lines for the approval window; empty when nothing is odd. */
+    warnings: string[];
+}
+declare class PhishingDetector {
+    private readonly black;
+    private readonly white;
+    private readonly fuzzy;
+    private readonly tolerance;
+    constructor(list: PhishingList);
+    get size(): number;
+    check(hostOrOrigin: string): HostCheck;
+    /**
+     * `metamask.io-login.com`, `app-uniswap.com`, `uniswap.org.evil.net`: a known site's name used as (part of) a label
+     * of a host that is not that site. Names shorter than 5 characters are skipped (too many honest matches).
+     */
+    brandInLabel(host: string): {
+        known: string;
+        label: string;
+    } | null;
+    /** eth-phishing-detect's fuzzy check: the host (minus the TLD and a www.) within `tolerance` edits of a known one. */
+    lookalike(host: string): string | null;
+}
+declare const normalizeHost: (h: string) => string;
+declare function hostOf(hostOrOrigin: string): string;
+declare function levenshtein(a: string, b: string): number;
+
+interface AssertionInput {
+    /** `PublicKeyCredential.rawId`, base64url. */
+    credentialId: string;
+    /** `AuthenticatorAssertionResponse.authenticatorData`, base64url. */
+    authenticatorData: string;
+    /** `AuthenticatorAssertionResponse.clientDataJSON`, base64url. */
+    clientDataJSON: string;
+    /** `AuthenticatorAssertionResponse.signature` (DER), base64url. */
+    signature: string;
+}
+interface AssertionExpectations {
+    /** SPKI public key of the credential, base64 (what `getPublicKey()` returned at registration). */
+    publicKey: string;
+    /** COSE alg of the key; only -7 is accepted. */
+    alg: number;
+    /** The challenge the worker handed the page (raw bytes; the page sent it base64url in clientDataJSON). */
+    challenge: Uint8Array;
+    /** `chrome-extension://<id>` */
+    origin: string;
+    /** The RP id the credential was created for (the extension id); its SHA-256 must be the first 32 bytes of authenticatorData. */
+    rpId: string;
+    /** Require the UV flag (user verification: biometric / PIN) — on for signing. */
+    requireUserVerification?: boolean;
+    crypto?: Crypto;
+}
+type AssertionVerdict = {
+    ok: true;
+    counter: number;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Verify one assertion. Never throws on bad input — a verdict with the reason, so the worker can refuse in-band. */
+declare function verifyAssertion(input: AssertionInput, expect: AssertionExpectations): Promise<AssertionVerdict>;
+/** DER `SEQUENCE { INTEGER r, INTEGER s }` → 64-byte r‖s; `null` when malformed. */
+declare function derToRaw(der: Uint8Array): Uint8Array | null;
+/** Raw r‖s → DER (tests build assertions with WebCrypto, which signs raw). */
+declare function rawToDer(raw: Uint8Array): Uint8Array;
+/**
+ * The challenge for one approval request: SHA-256 over the request id, kind,
+ * origin and payload, so an assertion made for one sheet cannot answer another.
+ */
+declare function approvalChallenge(request: {
+    id: string;
+    kind: string;
+    origin: string;
+    payload: unknown;
+}, c?: Crypto): Promise<Uint8Array>;
+
+/**
+ * Address poisoning: an attacker sends dust from an address whose first and
+ * last characters match one the user actually paid, hoping the next copy-paste
+ * picks the wrong one. The wallet has no transaction history, so it keeps its
+ * own book of recipients the user confirmed (per chain) and warns when a new
+ * recipient looks like one of them without being it. "Fresh address" (no
+ * activity on chain) is the other half of the signal; the EVM preview computes it.
+ */
+
+type RecipientsState = Record<string, string[]>;
+/** How many characters at each end must match (after any `0x`). */
+declare const LOOKALIKE_PREFIX = 4;
+declare const LOOKALIKE_SUFFIX = 4;
+/** A known recipient that `address` imitates (same start and end, different address), or `null`. */
+declare function lookalikeOf(address: string, known: readonly string[]): string | null;
+/** Recipients the user confirmed on each chain (`eip155`, `solana`, …), newest last, capped. */
+declare class RecipientBook {
+    private readonly storage;
+    private readonly cap;
+    private _state;
+    constructor(storage: JsonStorage<RecipientsState>, cap?: number);
+    private state;
+    list(namespace: string): Promise<string[]>;
+    remember(namespace: string, address: string): Promise<void>;
+    /** `known` → the address is one the user paid before; `lookalike` → it imitates one. */
+    check(namespace: string, address: string): Promise<{
+        known: boolean;
+        lookalike: string | null;
+    }>;
+}
+
+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, type OriginVia, PAGE_TARGET, PORT_NAME, type PageEvent, type PageRequest, type PageResponse, PermissionStore, type PermissionsState, PhishingDetector, type PhishingList, type PortSender, type PreparedTx, QueueLimitError, type QuoteRoutesOptions, READ_METHODS, RELAY_ERRORS, RecipientBook, type RecipientsState, type RelayChain, type RelayError, 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, TONCONNECT_ERRORS, TONCONNECT_MAX_MESSAGES, TON_CHAIN, TON_ENDPOINTS, TRON_CHAIN, TRON_PROVIDERS, type TonAddressParts, TonConnectError, type TonConnectMessage, type TonConnectRequest, type TonConnectSendTransaction, type TonSignDataPayload, type TypedData, VAULT_DEFAULT_ITERATIONS, 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, isRelayRequest, isRelayToContent, levenshtein, lookalikeOf, memoryAlarms, memoryApprovalWindow, memoryJsonStorage, memorySessionStorage, memoryVaultStorage, messageText, newRequestId, nonEvmChain, normalizeHost, parseAddChainParams, parseConnectRequest, parseRawAddress, parseSendTransaction, parseSignData, parseSiwe, parseSwapId, planMatchers, prepareTransaction, proofDomain, quoteRoutes, rank, rawToDer, relayError, reviewEarnPlan, reviewSwapPlan, siweProblems, stampOrigin, swapApprovalPayload, toBase64Url, toRelayError, tonConnectErrorCode, tonProofMessage, tonSignDataMessage, vaultSecretStorage, verifyAssertion };