@chipi-stack/backend 14.4.0 → 14.7.0

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 import * as _chipi_stack_types from '@chipi-stack/types';
-import { CreateSessionKeyParams, SessionKeyData, AddSessionKeyParams, RevokeSessionKeyParams, GetSessionDataParams, SessionDataResponse, ExecuteWithSessionParams, SetSpendingPolicyParams, GetSpendingPolicyParams, SpendingPolicyData, RemoveSpendingPolicyParams, Currency, PaymasterAdapter, PaymasterAccount, X402FacilitatorConfig, NonceStore, PaymentPayload, VerifyResponse, SettleResponse, ChipiSDKConfig, ExecuteTransactionParams, SignTypedDataParams, SignTypedDataResult, TransferParams, ApproveParams, CallAnyContractParams, CreateWalletParams, CreateWalletResponse, RecordSendTransactionParams, Transaction, GetTransactionListQuery, PaginatedResponse, GetWalletParams, GetTokenBalanceParams, GetTokenBalanceResponse, CreateSkuPurchaseParams, GetSkuListQuery, Sku, TransactionStatusResponse, PrepareWalletUpgradeParams, PrepareWalletUpgradeResponse, ExecuteWalletUpgradeParams, ExecuteWalletUpgradeResponse, ChipiServerSDKConfig, ChipiBrowserSDKConfig, X402PaymentConfig } from '@chipi-stack/types';
+import { CreateSessionKeyParams, SessionKeyData, AddSessionKeyParams, RevokeSessionKeyParams, GetSessionDataParams, SessionDataResponse, ExecuteWithSessionParams, SetSpendingPolicyParams, GetSpendingPolicyParams, SpendingPolicyData, RemoveSpendingPolicyParams, Currency, PaymasterAdapter, PaymasterAccount, X402FacilitatorConfig, NonceStore, PaymentPayload, VerifyResponse, SettleResponse, ChipiSDKConfig, ExecuteTransactionParams, SignTypedDataParams, SignTypedDataResult, TransferParams, ApproveParams, CallAnyContractParams, CreateWalletParams, CreateWalletResponse, RecordSendTransactionParams, Transaction, GetTransactionListQuery, PaginatedResponse, GetWalletParams, GetTokenBalanceParams, GetTokenBalanceResponse, CreateSkuPurchaseParams, GetSkuListQuery, Sku, TransactionStatusResponse, PrepareWalletUpgradeParams, PrepareWalletUpgradeResponse, ExecuteWalletUpgradeParams, ExecuteWalletUpgradeResponse, ChipiServerSDKConfig, ChipiBrowserSDKConfig, X402ClientConfig, PaymentRequirement, X402PaymentConfig, ShhhSignerKind } from '@chipi-stack/types';
 export * from '@chipi-stack/types';
 export { Chain, ChainToken, Currency } from '@chipi-stack/types';
-import { ChipiWallets } from './wallets.js';
+import { C as ChipiWallets } from './wallets-DxKnh21Q.js';
+export { E as ExecuteMigrateResponse, M as MigrateChipiWalletToShhhParams, a as MigrationOutcome, P as PrepareMigrateResponse, m as migrateChipiWalletToShhh } from './wallets-DxKnh21Q.js';
 import { ChipiTransactions } from './transactions.js';
 import { ChipiSkuPurchases } from './skuPurchases.js';
 import { ChipiSkus } from './skus.js';
@@ -21,10 +22,22 @@ declare class ChipiSessions {
     private client;
     constructor(client: ChipiClient);
     /**
-     * Validate that the wallet is a CHIPI wallet (required for session operations).
-     * Throws ChipiSessionError if wallet type is not CHIPI.
+     * Validate that the wallet supports SNIP-163 session keys.
+     *
+     * Both CHIPI v29 (sessions-smart-contract) and SHHH V8.4
+     * (ShhhAccount) embed the same SNIP-163 SessionKeyComponent, so
+     * `add_or_update_session_key` / `revoke_session_key` /
+     * `get_session_data` selectors exist on both. The 4-felt session
+     * signature shape (`[session_pubkey, r, s, valid_until]`) is the
+     * same on both — V8.4's `execute_from_outside_v2` checks
+     * `signature.len() == 4` at account.cairo:389 BEFORE the
+     * V2_SNIP12 envelope dispatch, so sessions land through the
+     * legacy fast path on V8.4 wallets too.
+     *
+     * READY (Argent X v0.4.0) does NOT implement SNIP-163; reject with
+     * a clear error.
      */
-    private validateChipiWallet;
+    private validateWalletSupportsSessions;
     /**
      * Convert a Uint8Array to hex string with 0x prefix.
      */
@@ -38,6 +51,15 @@ declare class ChipiSessions {
      *
      * After generating, call `addSessionKeyToContract()` to register the session on-chain.
      *
+     * **PIN is weak — not recommended for production.** `encryptKey` here
+     * is the symmetric key the SDK uses to encrypt the session's private
+     * key at rest. If you're passing a user-typed PIN, anyone who
+     * observes that PIN can decrypt the session. Derive `encryptKey`
+     * from a platform passkey (`@chipi-stack/chipi-passkey`) — for SHHH
+     * V8.4 wallets prefer `createShhhPasskey` + `signShhhMessage`, where
+     * the wallet's primary key never needs to be decrypted client-side
+     * at all.
+     *
      * @param params - Session creation parameters
      * @returns SessionKeyData for external storage
      *
@@ -459,7 +481,7 @@ declare class ChipiSDK {
      * });
      * ```
      */
-    signTypedData({ params, }: {
+    signTypedData({ params }: {
         params: SignTypedDataParams;
     }): Promise<SignTypedDataResult>;
     /**
@@ -625,6 +647,126 @@ declare const signTypedData: ({ params, }: {
 declare const encryptPrivateKey: (privateKey: string, password: string) => string;
 declare const decryptPrivateKey: (encryptedPrivateKey: string, password: string) => string;
 
+/**
+ * SHHH V8.4 buyer client for the x402 payment protocol.
+ *
+ * The CHIPI v29 / Argent `X402Client` (in `@chipi-stack/core`) signs
+ * a SNIP-12 typed-data message with `account.signMessage()` and lets
+ * the facilitator build the on-chain USDC transfer. That path does
+ * not work for SHHH V8.4 wallets: V8.4's
+ * `execute_from_outside_v2` at `account.cairo:389` rejects raw
+ * `{r, s}` (2-felt) signatures and dispatches based on
+ * `signature[0]` to either the V2_SNIP12 envelope path (single-owner
+ * primary verifier) or the 4-felt session-sig fast path.
+ *
+ * `X402ShhhClient` builds the full execute_from_outside_v2 calldata
+ * + signs the V8.4 SNIP-12 hash locally with the primary STARK key,
+ * then ships the pre-signed span in the `payload.shhh.oeCalldata`
+ * field. The facilitator (`X402Facilitator.settle`) detects
+ * `payload.shhh` and forwards verbatim through
+ * `/transactions/execute-sponsored-raw`. Self-custodial:
+ * `encryptKey` decrypts the wallet's STARK key client-side; chipi-
+ * back never sees the cleartext.
+ *
+ * Same `fetch(url, init)` surface as `X402Client` so an integrator
+ * can pick the right client at construction time based on their
+ * wallet type:
+ *
+ *     const client = wallet.walletType === "SHHH"
+ *       ? new X402ShhhClient({ wallet, encryptKey, chipiClient, bearerToken })
+ *       : new X402Client(account);
+ *
+ * Wave B ships STARK + ED25519 primary signers; the SDK rejects
+ * other kinds with a clear error so a future external-rooted SHHH
+ * wallet (MetaMask, Phantom, passkey, Apple) doesn't silently
+ * produce a sig that reverts on chain.
+ */
+
+interface FetchResponse {
+    status: number;
+    headers: {
+        get(name: string): string | null;
+    };
+}
+/**
+ * The minimal wallet shape the SHHH client needs to sign payments.
+ * Matches the `WalletData`-derived row callers already pass to the
+ * rest of the SDK.
+ */
+interface ShhhX402Wallet {
+    /** Deployed account address (NOT the raw STARK pubkey). */
+    publicKey: string;
+    /** Wallet's PIN/passkey-encrypted STARK private key (ciphertext). */
+    encryptedPrivateKey: string;
+    /**
+     * Defaults to `"STARK"`. Future external-rooted kinds will need
+     * their own signing path; the client throws when handed an
+     * unsupported kind so silent on-chain reverts are impossible.
+     */
+    signerKind?: "STARK" | "ED25519";
+}
+interface X402ShhhClientConfig extends X402ClientConfig {
+    /**
+     * Override the chain id used for SHHH SNIP-12 hashing. Defaults to
+     * Starknet mainnet per CLAUDE.md; sepolia is auto-inferred from
+     * the chipi-back base URL when present. Drift here = the on-chain
+     * V8.4 wallet rejects the signature.
+     */
+    chainId?: bigint | string;
+}
+/**
+ * SHHH-aware buyer client.
+ */
+declare class X402ShhhClient {
+    private readonly wallet;
+    private readonly encryptKey;
+    private readonly chipiClient;
+    private readonly bearerToken;
+    private readonly config;
+    private readonly fetchFn;
+    constructor(opts: {
+        /** The SHHH wallet making the payment. */
+        wallet: ShhhX402Wallet;
+        /** PIN / passkey-derived encryption key for the wallet's STARK key. */
+        encryptKey: string;
+        /** Chipi HTTP client; only used by the facilitator side. The client side
+         * keeps it for forward-compat if a future verifier flow needs to
+         * query chipi-back's chain-id helper at sign-time. */
+        chipiClient: ChipiClient;
+        /** Bearer token for chipi-back. Server-side only; never crosses the wire
+         * to an x402 seller. */
+        bearerToken: string;
+        config?: X402ShhhClientConfig;
+    });
+    /**
+     * Drop-in `fetch` replacement. If the seller returns 402, signs a
+     * payment + retries with the X-PAYMENT header. Same surface as
+     * `X402Client.fetch`.
+     */
+    fetch(url: string, init?: Record<string, any>): Promise<FetchResponse>;
+    parsePaymentRequired(response: FetchResponse): PaymentRequirement;
+    private validateRequirement;
+    /**
+     * Sign an x402 payment as a SHHH V8.4 buyer. Builds the V8.4 OE
+     * containing the single USDC.transfer call, computes the SNIP-12
+     * hash against the wallet address + chain id, signs locally with
+     * the decrypted STARK private key, wraps the result in a V2_SNIP12
+     * envelope, and serializes the full execute_from_outside_v2
+     * calldata. Returns a PaymentPayload with the `shhh` extension
+     * populated; the facilitator's settle branch forwards
+     * `payload.shhh.oeCalldata` verbatim to
+     * `/transactions/execute-sponsored-raw`.
+     *
+     * The `signature: {r, s}` field is also populated with the inner
+     * `(r, s)` pair so the wire format stays valid for receivers that
+     * only inspect the legacy field. The facilitator uses the SHHH
+     * branch when `payload.shhh` is present, so the redundant `{r, s}`
+     * is informational, not load-bearing.
+     */
+    signPayment(requirement: PaymentRequirement): Promise<PaymentPayload>;
+    private retryWithPayment;
+}
+
 interface X402MiddlewareConfig {
     /** x402 facilitator instance for verify + settle */
     facilitator: X402Facilitator;
@@ -674,4 +816,1436 @@ interface X402MiddlewareFlatConfig {
  */
 declare function x402Middleware(config: X402MiddlewareConfig | X402MiddlewareFlatConfig): (req: any, res: any, next: any) => Promise<any>;
 
-export { ChipiBrowserSDK, ChipiClient, ChipiPaymasterAdapter, ChipiSDK, ChipiServerSDK, ChipiSessions, ChipiSkuPurchases, ChipiSkus, ChipiTransactions, ChipiWallets, X402Facilitator, type X402FacilitatorCreateOptions, type X402MiddlewareConfig, type X402MiddlewareFlatConfig, decryptPrivateKey, encryptPrivateKey, signTypedData, x402Middleware };
+/**
+ * SNIP-12 typed-data hash for `OutsideExecution` — TypeScript reference.
+ *
+ * Vendored from haycarlitos/shhh-wallet-cairo @ v8.4 commit 3975532
+ *   source: scripts/ts/snip12-hash.ts
+ *   license: MIT (Copyright (c) 2026 Carlos Castillo and contributors)
+ *
+ * MUST produce byte-identical output to `compute_snip12_hash` in
+ * `src/outside_execution.cairo` at the same commit. If the canonical
+ * Cairo source ships a breaking change, the upstream Shhh maintainer
+ * will open a PR against this file (per Q3 of SHHH_INTEGRATION_ANSWERS.md).
+ */
+
+declare const STARKNET_MESSAGE_PREFIX: string;
+declare const OE_DOMAIN_NAME: string;
+declare const OE_DOMAIN_VERSION = 2n;
+declare const OE_DOMAIN_REVISION = 1n;
+declare const SIG_VERSION_V1_HEX_ASCII: string;
+declare const SIG_VERSION_V2_SNIP12: string;
+declare const SIG_VERSION_V2_THRESHOLD: string;
+declare const ISRC9_V2_ID: bigint;
+declare const ISIGNER_ID: bigint;
+declare const ISIGNER_CANONICAL_LABEL = "ISigner_V1";
+/** Recomputes the canonical `ISIGNER_ID` at runtime. */
+declare function computeISignerId(): bigint;
+type OutsideExecution = {
+    caller: bigint | string;
+    nonce: bigint | string;
+    execute_after: bigint;
+    execute_before: bigint;
+    calls: Call[];
+};
+declare function hashCall(call: Call): bigint;
+declare function hashCalls(calls: Call[]): bigint;
+declare function hashStarknetDomain(chainIdFelt: bigint | string): bigint;
+declare function hashOutsideExecutionStruct(oe: OutsideExecution): bigint;
+/**
+ * The authoritative SNIP-12 message hash for an OutsideExecution.
+ * Signers sign over this felt252 (or its hex-ASCII re-encoding for
+ * Phantom UX compatibility — see snip12HashToHexAsciiBytes).
+ */
+declare function computeSnip12Hash(oe: OutsideExecution, contractAddress: bigint | string, chainIdFelt: bigint | string): bigint;
+/**
+ * Phantom hex-ASCII envelope helper. Phantom signs a string; we give it
+ * a 64-byte hex-ASCII representation of the SNIP-12 hash, and the Cairo
+ * verifier re-computes the hash and compares byte-by-byte.
+ */
+declare function snip12HashToHexAsciiBytes(h: bigint): Uint8Array;
+
+/**
+ * Deterministic ShhhAccount (V8.4) address derivation.
+ *
+ * Vendored from haycarlitos/shhh-wallet-cairo @ v8.4 commit 3975532
+ *   source: scripts/ts/compute-wallet-address.ts
+ *   license: MIT (Copyright (c) 2026 Carlos Castillo and contributors)
+ *
+ * Given the primary owner (kind + raw pubkey bytes) and the
+ * ShhhAccount class hash, returns the Starknet address the account
+ * will deploy to.
+ *
+ * MUST match `src/account.cairo::constructor` at the same commit. If
+ * the upstream constructor changes shape, the Shhh maintainer will
+ * open a PR against this file.
+ */
+type ComputeAddressInput = {
+    /** SHHH ShhhAccount class hash — see WALLET_CLASS_HASHES.SHHH in @chipi-stack/shared. */
+    classHash: bigint;
+    /** Primary signer kind, e.g. 'STARK' / 'ED25519' / 'WEBAUTHN_P256'. */
+    primaryKind: string;
+    /** Raw pubkey bytes interpreted as felt252-sized halves (kind-specific layout). */
+    pubkey: bigint[];
+    /** Verifier class hash for primaryKind — see SHHH_VERIFIER_CLASS_HASHES. */
+    verifierClassHash: bigint;
+    /** Optional user-facing tag bound into the constructor (default 'primary'). */
+    label?: string;
+    /** Factory / UDC address; default 0 for self-deploy. */
+    deployerAddress?: bigint;
+};
+/** Mirrors `src/signer/interface.cairo::owner_commitment` = poseidon(kind_tag, pubkey...). */
+declare function ownerCommitment(kindTag: bigint, pubkey: bigint[]): bigint;
+/**
+ * Mirrors the V8.4 constructor's salt derivation:
+ *   salt = poseidon(primary_kind, primary_pubkey_hash)
+ * where primary_pubkey_hash = owner_commitment(primary_kind, pubkey).
+ * Binding kind into the salt ensures the same raw key under two
+ * different kinds produces two distinct addresses.
+ */
+declare function computeAddressSalt(primaryKind: string, pubkey: bigint[]): bigint;
+/** Computes the deterministic deployment address for a SHHH ShhhAccount. */
+declare function computeShhhAddress(input: ComputeAddressInput): bigint;
+
+/**
+ * Outside-Execution construction for SHHH V8.4 ShhhAccount.
+ *
+ * Wraps the canonical SNIP-12 hash + envelope assembly so SDK callers
+ * never touch the underlying felt-array shapes directly. Implements
+ * the envelope routing per V8.4 handover §5:
+ *
+ *     [ signature[0] ]
+ *       ├─ 'V2_SNIP12'    → [owner_id, kind_tag, ...payload]   (single-owner)
+ *       ├─ 'V2_THRESHOLD' → [n, env_1_len, ..., env_n_len, ...] (multisig)
+ *       └─ (else, len==4) → SNIP-163 session-key envelope
+ *
+ * Source of truth: `src/account.cairo::execute_from_outside_v2` at
+ * shhh-wallet-cairo v8.4 commit 3975532.
+ */
+
+/**
+ * The `caller` sentinel used for paymaster-sponsored OE flows. Any
+ * forwarder may submit the OE; binding `caller = ANY_CALLER` lifts the
+ * usual caller-equality check inside the account.
+ */
+declare const ANY_CALLER_FELT: bigint;
+/**
+ * Per audit M-2, OE validity windows must not exceed 2 hours. The
+ * V8.4 account enforces this on-chain; we expose the constant so SDK
+ * callers can default sensibly.
+ */
+declare const MAX_OE_VALIDITY_WINDOW_SECONDS: number;
+/**
+ * Build a standard paymaster-sponsored OutsideExecution with sensible
+ * defaults. Callers can override any field; the typical happy path is
+ * to pass only `nonce` + `calls`.
+ */
+declare function buildOutsideExecution(params: {
+    /** Unique per-account replay nonce. The account stores these in `oe_nonces`. */
+    nonce: bigint | string;
+    /** The calls the account should execute on success. */
+    calls: Call[];
+    /** Override `caller`; defaults to ANY_CALLER for paymaster flows. */
+    caller?: bigint | string;
+    /**
+     * UNIX seconds. Defaults to `now - OE_EXECUTE_AFTER_CLOCK_SKEW_BUFFER`
+     * (60s in the past) so the OE is valid by the time the next block is
+     * minted regardless of small clock drifts between the SDK host and
+     * the sequencer. The wallet's check is strict `<` (`account.cairo:377`
+     * `'SRC9: now <= execute_after'`) — without the buffer, a fast
+     * SDK→paymaster round trip can land in the SAME block as the OE
+     * was built in and revert with `'SRC9: too early'`. PR sdks#289
+     * (this builder fix) made the buffer the default after the first
+     * session smoke run reproduced the race.
+     */
+    executeAfter?: bigint;
+    /** UNIX seconds; defaults to now + 2h (the maximum window per audit M-2). */
+    executeBefore?: bigint;
+}): OutsideExecution;
+/**
+ * Compute the SNIP-12 hash for the given OutsideExecution against
+ * a specific account address and chain. This is what the signer
+ * (STARK / Ed25519 / EIP-191 / WebAuthn / etc.) commits to.
+ *
+ * For Phantom UX where the user signs a string, hex-encode the
+ * resulting hash via `snip12HashToHexAsciiBytes` from snip12-hash.
+ */
+declare function computeOeHash(oe: OutsideExecution, accountAddress: bigint | string, chainId: bigint | string): bigint;
+/**
+ * Single-owner V2_SNIP12 envelope.
+ *
+ * The account strips signature[0..2] = ['V2_SNIP12', owner_id, kind_tag]
+ * and library_calls the matching verifier with `payload`. Chipi
+ * paymaster passes the entire envelope verbatim to
+ * `execute_from_outside_v2`; it does NOT need to know the kind.
+ *
+ * **`ownerId` is a u32 INDEX into the wallet's owner_set**, NOT the
+ * poseidon `owner_commitment`. Primary owner = `0n`; subsequent owners
+ * added via `propose_add_owner` get `1n`, `2n`, etc. The V8.4
+ * dispatcher (`src/account.cairo:480`) panics with `'SHHH: bad
+ * owner_id'` if signature[1] does not fit in u32 — which happens
+ * silently at the wallet level (outer paymaster tx still reports
+ * SUCCEEDED). Discovered 2026-05-27 in a production trace audit.
+ *
+ * Returns the `signature: felt252[]` span you pass to
+ * `paymaster_executeSponsoredRaw.calldata`.
+ */
+declare function wrapV2Snip12Envelope(params: {
+    /** u32 INDEX into owner_set (0n for primary). NOT the commitment. */
+    ownerId: bigint;
+    kindTag: string | bigint;
+    payload: Array<bigint | string>;
+}): bigint[];
+/**
+ * @deprecated since Wave B B2 — use `buildThresholdEnvelope` from
+ * `@chipi-stack/backend/shhh/threshold` instead. This wrapper exists
+ * for backward compat with v13.x and will be removed one minor
+ * release after `chipi-stack@14.5.0` ships.
+ *
+ * Forwards to the validated builder. Note that callers passing
+ * fewer than 2 envelopes (which the old version silently accepted
+ * with a bogus layout) will now correctly throw — Cairo rejects
+ * `n < 2` thresholds.
+ */
+declare function wrapV2ThresholdEnvelope(innerEnvelopes: bigint[][]): bigint[];
+
+/**
+ * STARK ECDSA signer for SHHH V8.4 ShhhAccount.
+ *
+ * Cheapest verifier path (~2M l2_gas). Native Stark-curve ECDSA over
+ * the SNIP-12 hash; the verifier class is a thin syscall wrapper.
+ *
+ * Reference: shhh-wallet-cairo/scripts/ts/gen-phase3-account-fixture.mjs
+ *   (same Stark signature shape, wrapped in V2_SNIP12).
+ *
+ * For non-STARK kinds (Ed25519, EIP-191, WebAuthn, JWT, BLS) the
+ * envelope payload is per-kind — see sibling files in this directory.
+ */
+/**
+ * Build a V2_SNIP12 envelope for the STARK kind from a private key +
+ * the OE's SNIP-12 hash. The envelope is the `signature` span you
+ * pass to `paymaster_executeSponsoredRaw.calldata`.
+ *
+ * Payload for STARK is exactly `[r, s]` — the verifier reads these
+ * two felts and invokes the chain's `ec_op` syscall.
+ *
+ * **Envelope layout (V8.4):** `[V2_SNIP12, owner_id, kind_tag, ...payload]`
+ *
+ * `owner_id` at position [1] is a **u32 INDEX into the owner_set**,
+ * NOT the poseidon `owner_commitment`. For the primary owner of a
+ * fresh deploy that index is `0n`; for additional owners added via
+ * `propose_add_owner` it's `1n`, `2n`, etc. The V8.4 dispatcher
+ * (`src/account.cairo:480`) does `(*signature.at(1)).try_into::<u32>()`
+ * and panics with `'SHHH: bad owner_id'` if the felt exceeds u32 MAX —
+ * which is exactly what happens if a poseidon commitment is passed
+ * here instead of the index. (Discovered 2026-05-27 trace audit on
+ * tx 0x1d1ee02e0dd1ffdbc6f0dddb426098d0dc87800eee3d0d0201e74d97ddc0a55.)
+ */
+declare function buildStarkEnvelope(params: {
+    /** STARK private key as bigint or 0x-prefixed hex. */
+    privateKey: bigint | string;
+    /** SNIP-12 hash of the OutsideExecution — see oe.ts::computeOeHash. */
+    messageHash: bigint;
+    /**
+     * Owner index in the wallet's owner_set. **Defaults to 0n (primary).**
+     * Override for additional owners added via `propose_add_owner`.
+     * MUST fit in u32 (i.e., < 2^32). Passing the poseidon
+     * `owner_commitment` here will revert on chain with
+     * `'SHHH: bad owner_id'`.
+     */
+    ownerIndex?: bigint;
+}): bigint[];
+/**
+ * Compute the V8.4 owner_id for a STARK-kind owner from its public
+ * key. owner_id = owner_commitment(kind_tag, [pubkey]) per
+ * `src/signer/interface.cairo::owner_commitment`. The account uses
+ * this to dedupe owners and select the verifier class.
+ */
+declare function starkOwnerId(starkPubKey: bigint): bigint;
+/**
+ * STARK pubkey layout for the V8.4 constructor / propose_add_owner.
+ * The Stark curve pubkey fits in one felt252, so this is a 1-element
+ * array. Kept as a function for parity with kinds that split the
+ * pubkey into multiple felts (Ed25519, secp256k1, P-256, BLS).
+ */
+declare function starkPubkeyFelts(starkPubKey: bigint | string): bigint[];
+
+/**
+ * Ed25519 signer for SHHH V8.4 ShhhAccount.
+ *
+ * Used by Phantom (Solana) flows and any generic Ed25519 signer. The
+ * V8.4 verifier (class `0x030a7dfc…949f74`) consumes a Cairo-ready
+ * calldata array produced by Garaga's `eddsaCalldataBuilder` — it
+ * contains the signature halves plus elliptic-curve hints the Cairo
+ * verifier needs to keep gas bounded.
+ *
+ * Reference: shhh-wallet-cairo/scripts/ts/regen-ed25519-fixtures.mjs
+ *
+ * Verifier overhead: ~33M l2_gas (per SHHH_KIND_GAS_OVERHEAD).
+ *
+ * IMPORTANT — dynamic imports
+ *
+ *   Garaga ships a ~1.2MB WASM bundle. We dynamic-import it so callers
+ *   who never touch Ed25519 don't pay the bundle cost. The first call
+ *   to `buildEd25519Envelope` will lazy-load + initialize Garaga; this
+ *   is irreversible and cached for the process lifetime. Cold-start
+ *   cost is ~200-400ms on Android, ~80-150ms on iPhone 13+.
+ *
+ *   `@noble/ed25519` is also dynamic-imported for symmetry, though it
+ *   tree-shakes cleanly as a static import too.
+ */
+/**
+ * The Cairo Ed25519 verifier reads the SNIP-12 hash via its hex-ASCII
+ * 64-byte encoding so the signature commits to a string that Phantom
+ * (and any "sign-this-string" UX) can display. This helper is exposed
+ * here for parity with the Cairo-side decoder; it's the same function
+ * as `snip12HashToHexAsciiBytes` in snip12-hash.ts, re-exported under
+ * a kind-specific name for discoverability.
+ */
+declare function ed25519SignedBytes(messageHash: bigint): Uint8Array;
+/**
+ * Compute the V8.4 owner_id for an Ed25519-kind owner from its public
+ * key. owner_id = owner_commitment(ED25519_tag, [pub_low, pub_high])
+ * — the same shape as `src/signer/ed25519/verifier.cairo` expects in
+ * `validate_pubkey`.
+ */
+declare function ed25519OwnerId(publicKey: Uint8Array): bigint;
+/**
+ * Ed25519 pubkey felt layout for the V8.4 constructor / propose_add_owner.
+ * Returns the low/high u128 halves of the 32-byte public key in that
+ * order — what the Cairo `kind == ED25519` branch reads.
+ */
+declare function ed25519PubkeyFelts(publicKey: Uint8Array): bigint[];
+/**
+ * Build a V2_SNIP12 envelope for the Ed25519 kind. Async because the
+ * underlying Garaga WASM must be initialized; subsequent calls reuse
+ * the cached init.
+ *
+ * Inputs:
+ *   privateKey   — 32-byte Ed25519 secret (Uint8Array, NOT hex/bigint:
+ *                  the noble lib refuses anything else).
+ *   messageHash  — the SNIP-12 hash of the OE (see oe.ts::computeOeHash).
+ *
+ * Output: the `signature` span you pass to
+ *   `paymaster_executeSponsoredRaw.calldata`.
+ */
+declare function buildEd25519Envelope(params: {
+    privateKey: Uint8Array;
+    messageHash: bigint;
+    /**
+     * Owner index in the wallet's owner_set. **Defaults to 0n (primary).**
+     * Override for additional owners added via `propose_add_owner`.
+     * MUST fit in u32 (i.e., < 2^32). Passing the poseidon
+     * `owner_commitment` (e.g. via `ed25519OwnerId`) here will revert
+     * on chain with `'SHHH: bad owner_id'` — the bug Shhh team caught
+     * 2026-05-27 + audit-trail 2026-05-28.
+     */
+    ownerIndex?: bigint;
+}): Promise<bigint[]>;
+/**
+ * Build a V2_SNIP12 Ed25519 envelope from an **externally-produced**
+ * signature — the Phantom / Solana flow. Phantom (and every external
+ * Ed25519 wallet) never exposes the private key: the user signs via
+ * `window.solana.signMessage(...)`, which returns a 64-byte signature
+ * (R‖s). This is the from-signature counterpart of
+ * `buildEd25519Envelope`, mirroring `buildEip191EnvelopeFromSignature`
+ * for MetaMask.
+ *
+ * IMPORTANT — what the wallet MUST sign:
+ *   The wallet must sign the EXACT bytes returned by
+ *   `ed25519SignedBytes(messageHash)` — the 64-byte hex-ASCII encoding
+ *   of the SNIP-12 OE hash — NOT the raw 32-byte `messageHash`. The
+ *   Cairo verifier reconstructs those same bytes from `messageHash`, so
+ *   a mismatch fails on chain. The dashboard adapter does:
+ *     await window.solana.connect();
+ *     // Phantom returns the 32-byte Ed25519 pubkey as a Solana PublicKey;
+ *     // `.toBytes()` is the Uint8Array this API expects.
+ *     const publicKey = window.solana.publicKey.toBytes();
+ *     const msg = ed25519SignedBytes(messageHash);
+ *     // Phantom's signMessage returns { signature: Uint8Array (64B), publicKey }.
+ *     const { signature } = await window.solana.signMessage(msg);
+ *     const env = await buildEd25519EnvelopeFromSignature({
+ *       signature, publicKey, messageHash,
+ *     });
+ *
+ * Async (unlike the synchronous EIP-191 from-signature path): the
+ * Garaga WASM hint builder must be initialized to produce the EC hints
+ * the Cairo Ed25519 verifier needs. The issue sketch (#311) showed a
+ * sync return; Ed25519 cannot avoid the WASM init that secp256k1 does.
+ */
+declare function buildEd25519EnvelopeFromSignature(params: {
+    /** 64-byte Ed25519 signature R(32)‖s(32) from the wallet's signMessage. */
+    signature: Uint8Array;
+    /** 32-byte Ed25519 public key (as Phantom returns it). */
+    publicKey: Uint8Array;
+    /** SNIP-12 hash of the OutsideExecution — see oe.ts::computeOeHash. */
+    messageHash: bigint;
+    /**
+     * Owner index in the wallet's owner_set. **Defaults to 0n (primary).**
+     * MUST fit in u32. Same semantics + footgun as `buildEd25519Envelope`:
+     * pass the INDEX, never an `ed25519OwnerId` commitment.
+     */
+    ownerIndex?: bigint;
+}): Promise<bigint[]>;
+
+/**
+ * EIP-191 secp256k1 signer for SHHH V8.4 ShhhAccount.
+ *
+ * The signer kind for MetaMask + any EVM wallet that exposes the
+ * `personal_sign` RPC. The wallet computes
+ *   keccak256("\x19Ethereum Signed Message:\n32" || msg_be32)
+ * internally and signs with secp256k1; the V8.4 EIP191Secp256k1Verifier
+ * (class `0x03a75997…084e6`) reproduces the same prefix-and-hash and
+ * recovers the signing key from (r, s, y_parity) to compare to the
+ * stored pubkey.
+ *
+ * Reference: shhh-wallet-cairo/scripts/ts/gen-eip191-fixture.mjs
+ *
+ * Verifier overhead: ~10M l2_gas (per SHHH_KIND_GAS_OVERHEAD).
+ *
+ * Two builder entry points:
+ *   - buildEip191EnvelopeFromSignature: production / MetaMask flow.
+ *     Caller already has the 65-byte signature back from `personal_sign`
+ *     and the wallet's pubkey (either pre-known or recovered).
+ *   - buildEip191EnvelopeFromPrivateKey: test / Chipi-held-key flow.
+ *     Sign locally with a known secp256k1 private key.
+ *
+ * Both produce the identical V2_SNIP12 envelope shape:
+ *   [V2_SNIP12, owner_id, EIP191_SECP256K1_tag,
+ *    r.low, r.high, s.low, s.high, y_parity]
+ */
+/**
+ * Uncompressed secp256k1 public key, split into 4 felt252-sized halves
+ * matching what Cairo's EIP191 verifier expects in
+ * `validate_pubkey` — `[x.low, x.high, y.low, y.high]` (big-endian
+ * scalar, low_u128 first).
+ */
+interface Eip191Pubkey {
+    /** 32-byte big-endian X coordinate. */
+    x: Uint8Array;
+    /** 32-byte big-endian Y coordinate. */
+    y: Uint8Array;
+}
+/**
+ * Pubkey felt layout for the V8.4 constructor / propose_add_owner.
+ * Returns `[x.low, x.high, y.low, y.high]` (each u128).
+ */
+declare function eip191PubkeyFelts(pubkey: Eip191Pubkey): bigint[];
+/**
+ * Compute the V8.4 owner_id for an EIP-191 owner.
+ * owner_id = owner_commitment(EIP191_tag, [x.low, x.high, y.low, y.high]).
+ */
+declare function eip191OwnerId(pubkey: Eip191Pubkey): bigint;
+/**
+ * Parse a 65-byte `personal_sign`/`eth_sign` signature hex string into
+ * the Cairo-shaped envelope payload `[r.low, r.high, s.low, s.high, y_parity]`.
+ *
+ * Accepts both `v ∈ {27, 28}` (EIP-191 wallet convention) and
+ * `y_parity ∈ {0, 1}` raw forms.
+ */
+declare function parseEip191Signature(signatureHex: string): bigint[];
+/**
+ * Production / MetaMask flow. Caller already has the 65-byte signature
+ * from `personal_sign` (e.g., `await provider.send("personal_sign", [...])`)
+ * and the wallet's public key.
+ */
+declare function buildEip191EnvelopeFromSignature(params: {
+    /** 65-byte `personal_sign` signature, 0x-prefixed hex. */
+    signatureHex: string;
+    /** Uncompressed secp256k1 pubkey (x, y) as 32 BE bytes each. */
+    pubkey: Eip191Pubkey;
+    /**
+     * Owner index in the wallet's owner_set. **Defaults to 0n (primary).**
+     * MUST fit in u32. Passing `eip191OwnerId(pubkey)` (the commitment)
+     * here will revert on chain with `'SHHH: bad owner_id'`.
+     */
+    ownerIndex?: bigint;
+}): bigint[];
+/**
+ * Test / Chipi-held-key flow. Sign locally with a known secp256k1
+ * private key using the exact `personal_sign` recipe MetaMask uses
+ * (keccak256("\x19Ethereum Signed Message:\n32" || msg_be32),
+ *  secp256k1 sign of that hash).
+ *
+ * Async because @noble/secp256k1 v3 ships ESM and we dynamic-import.
+ */
+declare function buildEip191EnvelopeFromPrivateKey(params: {
+    /** 32-byte secp256k1 private key (Uint8Array OR 0x-prefixed hex). */
+    privateKey: Uint8Array | string;
+    /** SNIP-12 hash of the OutsideExecution — see oe.ts::computeOeHash. */
+    messageHash: bigint;
+    /**
+     * Owner index in the wallet's owner_set. **Defaults to 0n (primary).**
+     * MUST fit in u32. Same semantics as `buildEip191EnvelopeFromSignature`.
+     */
+    ownerIndex?: bigint;
+}): Promise<bigint[]>;
+
+/**
+ * WebAuthn P-256 signer for SHHH V8.4 ShhhAccount.
+ *
+ * The SHHH default signer kind in the browser. Wraps a WebAuthn
+ * `navigator.credentials.get()` assertion (or a synthesized equivalent
+ * in tests) into the V2_SNIP12 envelope the on-chain
+ * WebAuthnP256Verifier (class `0x074f6efd…44657`) consumes.
+ *
+ * The verifier reproduces the WebAuthn assertion check on-chain:
+ *   1. Parse `authData` (rpIdHash 32B || flags 1B || signCount 4B || …).
+ *      Require UP flag (bit 0) set.
+ *   2. Compute `outer = sha256(authData ‖ sha256(clientDataJSON))`.
+ *   3. Verify P-256 ECDSA `(r, s, y_parity)` against `outer` and the
+ *      stored pubkey.
+ *   4. At `challenge_offset` in `clientDataJSON`, base64url-decode the
+ *      next 43 chars to 32 bytes and compare equal to the SNIP-12 hash.
+ *   5. Sanity-check the `clientDataJSON` prefix
+ *      `{"type":"webauthn.get",…` (rejects webauthn.create / missing
+ *      type).
+ *
+ * Reference: shhh-wallet-cairo/scripts/ts/gen-webauthn-fixture.mjs
+ *            and tests/signer_webauthn_fixture.cairo
+ *
+ * Verifier overhead: ~35M l2_gas (per SHHH_KIND_GAS_OVERHEAD).
+ *
+ * Envelope shape (after the V2_SNIP12 + owner_id + kind_tag wrap):
+ *   ByteArray(authData)
+ *   ByteArray(clientDataJSON)
+ *   challenge_offset: u32
+ *   r.low, r.high, s.low, s.high, y_parity
+ *
+ * Cairo ByteArray serde:
+ *   num_full_words: u32
+ *   full_words: felt252[num_full_words]      // 31 bytes packed MSB-first
+ *   pending_word: felt252                    // <31 remaining bytes
+ *   pending_word_len: u32
+ */
+interface WebAuthnPubkey {
+    /** 32-byte big-endian P-256 X coordinate. */
+    x: Uint8Array;
+    /** 32-byte big-endian P-256 Y coordinate. */
+    y: Uint8Array;
+}
+/**
+ * Serialize a byte string as Cairo's `ByteArray` serde — must match
+ * what the Cairo runtime would produce when this same bytes value is
+ * passed as a `ByteArray` parameter.
+ *
+ * Layout: `[num_full_words, ...full_words, pending_word, pending_word_len]`.
+ * Each full word packs 31 bytes MSB-first (network order) into a felt252.
+ */
+declare function byteArrayToFelts(bytes: Uint8Array): bigint[];
+/**
+ * Parse a DER-encoded ECDSA signature into raw (r, s) 32-byte BE values.
+ * WebAuthn assertions return DER per spec; we strip it to the raw
+ * P-256 components the Cairo verifier expects.
+ */
+declare function parseDerEcdsaSignature(der: Uint8Array): {
+    r: Uint8Array<ArrayBuffer>;
+    s: Uint8Array<ArrayBuffer>;
+};
+declare function webauthnPubkeyFelts(pub: WebAuthnPubkey): bigint[];
+declare function webauthnOwnerId(pub: WebAuthnPubkey): bigint;
+/**
+ * Production / browser flow. The caller has run
+ * `navigator.credentials.get({ publicKey: { challenge: msgBe32, ... } })`
+ * and now has the assertion's `authenticatorData`, `clientDataJSON`,
+ * and DER-encoded `signature` (plus the wallet's stored P-256 pubkey).
+ *
+ * This builder:
+ *   1. Parses the DER signature into raw r, s.
+ *   2. Recovers y_parity from the signature (always 0; WebAuthn does
+ *      not expose recovery — the on-chain verifier compares the recovered
+ *      pubkey against the stored one and tries both parities if needed).
+ *   3. Locates the challenge in clientDataJSON to compute challenge_offset.
+ *   4. Encodes authData + clientDataJSON as Cairo ByteArrays.
+ *   5. Wraps everything in the V2_SNIP12 envelope.
+ */
+declare function buildWebAuthnEnvelopeFromAssertion(params: {
+    authenticatorData: Uint8Array;
+    clientDataJSON: Uint8Array;
+    /** DER-encoded ECDSA signature from `assertion.response.signature`. */
+    signatureDer: Uint8Array;
+    /** P-256 pubkey stored at registration time. */
+    pubkey: WebAuthnPubkey;
+    /** SNIP-12 hash the challenge was constructed from. */
+    messageHash: bigint;
+    /**
+     * y_parity recovery bit. WebAuthn assertions don't include this — pass
+     * 0 (the verifier tries both parities internally when needed). Override
+     * only if you know the bit independently.
+     */
+    yParity?: 0n | 1n;
+    /**
+     * Owner index in the wallet's owner_set. Defaults to 0n (primary).
+     * MUST fit in u32. Passing `webauthnOwnerId(pubkey)` (the commitment)
+     * here will revert on chain with `'SHHH: bad owner_id'`.
+     */
+    ownerIndex?: bigint;
+}): bigint[];
+/**
+ * Test / Chipi-held-key flow. Synthesizes a WebAuthn assertion under
+ * a known P-256 private key, then builds the envelope. Matches the
+ * exact recipe in `gen-webauthn-fixture.mjs` so the resulting envelope
+ * byte-for-byte matches `signer_webauthn_fixture.cairo`.
+ *
+ * Defaults match the canonical Shhh fixture: rpId="cifra.mx",
+ * origin="https://cifra.mx", flags=0x05 (UP+UV), signCount=42.
+ */
+declare function buildWebAuthnEnvelopeFromPrivateKey(params: {
+    /** 32-byte P-256 private key (Uint8Array or 0x-prefixed hex). */
+    privateKey: Uint8Array | string;
+    /** SNIP-12 hash of the OutsideExecution. */
+    messageHash: bigint;
+    /** WebAuthn relying-party ID (the rpId field). Default: "cifra.mx". */
+    rpId?: string;
+    /** WebAuthn origin string. Default: "https://cifra.mx". */
+    origin?: string;
+    /** WebAuthn authData flags byte. Default 0x05 (UP+UV). */
+    flags?: number;
+    /** 32-bit sign count. Default 42. */
+    signCount?: number;
+    /**
+     * Owner index in the wallet's owner_set. Defaults to 0n (primary).
+     * MUST fit in u32. Same semantics as `buildWebAuthnEnvelopeFromAssertion`.
+     */
+    ownerIndex?: bigint;
+}): Promise<bigint[]>;
+
+/**
+ * JWT ES256 "Sign in with Apple" sub-bound signer for SHHH V8.4.
+ *
+ * Wave B PR B3. Adds the Apple Sign In signer kind
+ * (`JWT_ES256_APPLE_SUB`, verifier class `0x06b67762...`). The headline
+ * UX value is iOS-native onboarding: users without MetaMask but with
+ * an iPhone authenticate with Apple, and the resulting JWT becomes a
+ * SHHH owner. Multi-tenant safe via the `sub` claim binding.
+ *
+ * Cairo source of truth:
+ *   shhh-wallet-cairo/src/signer/jwt_es256_apple_sub/verifier.cairo
+ *
+ * Envelope layout (Cairo Serde over Span<felt252>):
+ *   header_b64       ByteArray   // base64url JOSE header bytes
+ *   payload_decoded  ByteArray   // raw JSON claims (NOT base64url)
+ *   nonce_offset     u32         // index of the 43-byte b64url nonce
+ *   iss_offset       u32         // index of "https://appleid.apple.com"
+ *   sub_offset       u32         // index of the sub claim VALUE
+ *   sub_len          u32         // byte length of the sub claim VALUE
+ *   r                u256        // low | high
+ *   s                u256        // low | high
+ *   y_parity         felt252     // 0 | 1
+ *
+ * Pubkey layout (5 felts):
+ *   [x_low, x_high, y_low, y_high, sub_hash]
+ *
+ * where sub_hash = poseidon_hash_span over the user's stable Apple
+ * `sub` identifier, one felt per byte. The 5th felt binds the
+ * on-chain owner to a SPECIFIC end-user — so multiple Chipi accounts
+ * sharing Apple's same signing key can't be co-controlled by an
+ * arbitrary Apple-authenticated user.
+ *
+ * Two flows:
+ *   - `buildJwtAppleSubEnvelopeFromTokenResponse` — production. Caller
+ *     drops in the Apple-issued `id_token` + the SNIP-12 message hash
+ *     that was committed to via the OE nonce.
+ *   - `buildJwtAppleSubEnvelopeFromTestKey` — synthesized test path.
+ *     Generates an ES256 keypair, constructs a JWT shaped like
+ *     Apple's, and signs it locally. Used for unit tests + the Wave
+ *     B B9 mainnet smoke. Real Apple-issued fixture upgrade comes
+ *     post-Wave-B (per plan D18).
+ */
+/** The hardcoded `iss` claim every Apple JWT carries. 25 ASCII bytes. */
+declare const APPLE_ISSUER = "https://appleid.apple.com";
+/**
+ * Uncompressed P-256 public key for Apple's current ES256 signing key.
+ * Apple rotates this periodically — see the JWKS endpoint at
+ * `https://appleid.apple.com/auth/keys`.
+ */
+interface JwtAppleSubPubkey {
+    /** 32-byte big-endian X coordinate. */
+    x: Uint8Array;
+    /** 32-byte big-endian Y coordinate. */
+    y: Uint8Array;
+    /** The user's stable Apple `sub` identifier (ASCII), e.g. "001234.abc.5678". */
+    sub: string;
+}
+/**
+ * What you get back from `https://appleid.apple.com/auth/token` after
+ * a Sign-in-with-Apple OAuth flow. Only `id_token` is signature-bearing;
+ * `access_token` and friends are out of scope here.
+ */
+interface AppleTokenResponse {
+    id_token: string;
+}
+/**
+ * Compute the sub_hash that the Cairo verifier checks against.
+ * Equals `poseidon_hash_span` over the bytes of the sub string, one
+ * felt per byte. The SDK and the verifier must agree byte-for-byte.
+ */
+declare function jwtAppleSubHash(sub: string): bigint;
+/**
+ * Pubkey felt layout for the V8.4 constructor / propose_add_owner.
+ * Returns `[x.low, x.high, y.low, y.high, sub_hash]` (5 felts).
+ */
+declare function jwtAppleSubPubkeyFelts(pubkey: JwtAppleSubPubkey): bigint[];
+/** owner_commitment for an Apple JWT owner. */
+declare function jwtAppleSubOwnerId(pubkey: JwtAppleSubPubkey): bigint;
+/**
+ * base64url-no-padding encoding of a 32 BE-byte SNIP-12 hash. The
+ * Cairo verifier asserts the 43 ASCII bytes at
+ * `payload_decoded[nonce_offset .. nonce_offset+43]` equal exactly
+ * this string. Format must match RFC 4648 §5 (no padding `=`).
+ */
+declare function messageHashToNonceB64url(messageHash: bigint): string;
+/**
+ * Split an Apple-issued `id_token` into its three base64url parts.
+ * Returns the decoded payload bytes + the header b64url + the
+ * 64-byte raw ECDSA signature (r || s).
+ */
+declare function parseAppleIdToken(idToken: string): {
+    headerB64: string;
+    payloadDecoded: Uint8Array;
+    rawSignature: Uint8Array;
+};
+/**
+ * Locate the sub claim's VALUE bytes in a decoded JSON payload.
+ * Searches for the literal `"sub":"<value>"` pattern. JSON allows
+ * whitespace, but Apple's id_token always uses canonical
+ * no-whitespace form, so we don't try to handle pretty-printed JSON.
+ *
+ * Returns `{ offset, length }` of the value bytes (not including the
+ * surrounding quotes), suitable for `sub_offset` + `sub_len` in the
+ * envelope.
+ */
+declare function locateSubClaim(payload: Uint8Array): {
+    offset: number;
+    length: number;
+};
+/**
+ * Production flow. Build a V2_SNIP12 envelope wrapping an actual
+ * Apple-issued JWT. Caller has invoked the OAuth flow client-side
+ * (e.g. via `appleid.com` JS SDK or AuthenticationServices on iOS)
+ * and received an `id_token` whose `nonce` claim equals
+ * `messageHashToNonceB64url(oeMessageHash)`.
+ *
+ * Returns the `signature` felt span you pass to
+ * `paymaster_executeSponsoredRaw.calldata`.
+ */
+declare function buildJwtAppleSubEnvelopeFromTokenResponse(params: {
+    /** Apple OAuth token endpoint response (we only need `id_token`). */
+    idToken: string;
+    /** Owner's full pubkey including sub — same as registered on-chain. */
+    pubkey: JwtAppleSubPubkey;
+    /** SNIP-12 hash of the OE — the nonce in the id_token MUST encode this. */
+    messageHash: bigint;
+    /**
+     * Owner index in the wallet's owner_set. Defaults to 0n (primary).
+     * MUST fit in u32. Passing `jwtAppleSubOwnerId(pubkey)` (the commitment)
+     * here will revert on chain with `'SHHH: bad owner_id'`.
+     */
+    ownerIndex?: bigint;
+}): bigint[];
+/**
+ * Test / synthesized-fixture flow. Generate an ES256 P-256 keypair,
+ * construct a JWT shaped like an Apple-issued one, sign it locally,
+ * and wrap into a SHHH envelope.
+ *
+ * Used by unit tests + the Wave B B9 mainnet smoke. The wallet
+ * deployed for the smoke must be registered with the SAME synthesized
+ * pubkey returned here (`{ x, y, sub }`); production wallets register
+ * Apple's actual JWKS pubkey + the user's real sub.
+ *
+ * Async because `@noble/curves` ESM imports.
+ *
+ * Real-Apple-Developer-issued fixture upgrade is tracked as a separate
+ * post-Wave-B item (plan D18).
+ */
+declare function buildJwtAppleSubEnvelopeFromTestKey(params: {
+    /** 32-byte raw P-256 private key. */
+    privateKey: Uint8Array;
+    /** Stable Apple-style sub identifier (e.g. "001234.synthesized.5678"). */
+    sub: string;
+    /** Audience claim — typically the integrator's Apple Developer team ID + bundle ID. */
+    aud: string;
+    /** SNIP-12 hash of the OE; encoded as the nonce claim. */
+    messageHash: bigint;
+    /**
+     * Owner index in the wallet's owner_set. Defaults to 0n (primary).
+     * MUST fit in u32. Same semantics as `buildJwtAppleSubEnvelopeFromTokenResponse`.
+     */
+    ownerIndex?: bigint;
+}): Promise<{
+    envelope: bigint[];
+    pubkey: JwtAppleSubPubkey;
+    idToken: string;
+}>;
+
+/**
+ * SHHH V8.4 governance + recovery call builders.
+ *
+ * Wave B PR B1. The V8.4 ShhhAccount gates every owner-set mutation
+ * through a propose → wait-timelock → execute flow (`@external` fns
+ * in `src/account.cairo`). Each entrypoint is `_assert_self_call`-gated,
+ * which means callers wrap these `Call`s inside an OutsideExecution and
+ * submit through the paymaster.
+ *
+ * This module produces the `Call` (`{ contractAddress, entrypoint,
+ * calldata }`) shape that `oe.ts:buildOutsideExecution` expects. It
+ * does NOT sign — that's the integrator's choice of signer kind. For
+ * recovery initiation specifically, the signer MUST be a guardian owner
+ * (`role == ROLE_GUARDIAN` on-chain).
+ *
+ * Sources of truth on the Cairo side:
+ *
+ *   src/account.cairo:616  propose_add_owner
+ *   src/account.cairo:634  propose_remove_owner
+ *   src/account.cairo:649  propose_rotate_owner
+ *   src/account.cairo:670  propose_set_threshold
+ *   src/account.cairo:731  execute_add_owner
+ *   src/account.cairo:760  execute_remove_owner
+ *   src/account.cairo:769  execute_rotate_owner
+ *   src/account.cairo:786  execute_set_threshold
+ *   src/account.cairo:828  cancel_pending_op
+ *   src/account.cairo:864  initiate_recovery
+ *   src/account.cairo:888  cancel_recovery
+ *   src/account.cairo:897  finalize_recovery
+ *   src/governance/pending_ops.cairo  OP_* + TIMELOCK_* felt constants
+ *   src/owner_set/interface.cairo     ROLE_* felt constants
+ *
+ * Timelock semantics
+
+ *   propose_add_owner      48h
+ *   propose_remove_owner   24h
+ *   propose_rotate_owner   24h
+ *   propose_set_threshold  48h
+ *   initiate_recovery       7d (longest — the headline UX gate)
+ *
+ * Recovery is ADDITIVE on V8.4: `finalize_recovery` adds the new owner
+ * but does not remove existing ones. The integrator's UI is expected
+ * to follow with `propose_remove_owner` for stale devices.
+ *
+ * finalize_recovery is the only entrypoint here that is NOT
+ * `_assert_self_call`-gated — it's permissionless after the 7d window,
+ * so anyone can call it directly without an OE wrapper. The function
+ * still returns a Call so the integrator can dispatch via their
+ * normal account abstraction layer.
+ */
+
+/** `src/owner_set/interface.cairo:10` — `pub const ROLE_OWNER: felt252 = 'OWNER'`. */
+declare const ROLE_OWNER: bigint;
+/** `src/owner_set/interface.cairo:11` — `pub const ROLE_GUARDIAN: felt252 = 'GUARDIAN'`. */
+declare const ROLE_GUARDIAN: bigint;
+/** `src/governance/pending_ops.cairo:19` — `OP_ADD_OWNER: felt252 = 'ADD_OWNER'`. */
+declare const OP_ADD_OWNER: bigint;
+declare const OP_REMOVE_OWNER: bigint;
+declare const OP_ROTATE_OWNER: bigint;
+declare const OP_SET_THRESHOLD: bigint;
+/**
+ * Per-op timelocks in seconds. Match `src/governance/pending_ops.cairo:42-50`
+ * exactly. Exposed so SDK consumers can predict timelock expiry without
+ * an extra on-chain call after `proposeAddOwner` succeeds.
+ */
+declare const TIMELOCK_SECONDS: {
+    readonly ADD_OWNER: 172800;
+    readonly REMOVE_OWNER: 86400;
+    readonly ROTATE_OWNER: 86400;
+    readonly SET_THRESHOLD: 172800;
+    readonly ADD_VERIFIER: 172800;
+    readonly REMOVE_VERIFIER: 86400;
+    readonly ADD_GUARDIAN: 86400;
+    readonly REMOVE_GUARDIAN: 86400;
+    readonly RECOVERY: 604800;
+};
+/** `DEFAULT_OP_EXPIRY_SECONDS` from `pending_ops.cairo:78`. After this
+ * window from propose-time, the pending op auto-expires even if no one
+ * calls cancel. UI should reflect this so users don't sit on a stale op. */
+declare const DEFAULT_OP_EXPIRY_SECONDS = 1209600;
+/** Owner role on-chain. ROLE_OWNER can sign OEs; ROLE_GUARDIAN can
+ * only `initiate_recovery` (no general signing power). */
+type OwnerRole = "OWNER" | "GUARDIAN";
+/**
+ * Inputs shared across add-owner / rotate / initiate-recovery — they
+ * all encode a (kind, pubkey, role, weight, label) tuple.
+ *
+ * `pubkeyBytes` is the per-kind felt-array layout exposed by the
+ * matching `*PubkeyFelts` helper in `signers/{stark,ed25519,eip191,
+ * webauthn}.ts`. The Cairo verifier calls `owner_commitment(kind,
+ * pubkeyBytes)` to derive the on-chain owner_id; if the bytes
+ * disagree with the kind's verifier expectation,
+ * `_validate_pubkey_via_verifier` panics at execute time (audit M-1).
+ */
+interface NewOwnerInput {
+    kind: string;
+    pubkeyBytes: bigint[];
+    role: OwnerRole;
+    weight: number;
+    label: string;
+}
+/**
+ * Build a `propose_add_owner(proposer, kind, pubkey_bytes, role,
+ * weight, label)` call. Wrap in an OE signed by `proposer` and submit
+ * through the paymaster. After confirmation, watch for the
+ * `OpProposed` event to learn the `op_id`; then wait
+ * `TIMELOCK_SECONDS.ADD_OWNER` and call `buildExecuteAddOwnerCall`.
+ */
+declare function buildProposeAddOwnerCall(args: {
+    walletAddress: bigint | string;
+    proposer: number;
+    newOwner: NewOwnerInput;
+}): Call;
+/**
+ * Build an `execute_add_owner(op_id, kind, pubkey_bytes, role, weight,
+ * label)` call. MUST be called after the 48h timelock from the matching
+ * propose. The wallet recomputes the payload and asserts equality
+ * before mutating `owner_set`.
+ */
+declare function buildExecuteAddOwnerCall(args: {
+    walletAddress: bigint | string;
+    opId: bigint | string;
+    newOwner: NewOwnerInput;
+}): Call;
+declare function buildProposeRemoveOwnerCall(args: {
+    walletAddress: bigint | string;
+    proposer: number;
+    ownerId: number;
+}): Call;
+declare function buildExecuteRemoveOwnerCall(args: {
+    walletAddress: bigint | string;
+    opId: bigint | string;
+    ownerId: number;
+}): Call;
+declare function buildProposeRotateOwnerCall(args: {
+    walletAddress: bigint | string;
+    proposer: number;
+    ownerId: number;
+    newPubkeyBytes: bigint[];
+}): Call;
+declare function buildExecuteRotateOwnerCall(args: {
+    walletAddress: bigint | string;
+    opId: bigint | string;
+    ownerId: number;
+    newPubkeyBytes: bigint[];
+}): Call;
+declare function buildProposeSetThresholdCall(args: {
+    walletAddress: bigint | string;
+    proposer: number;
+    newThreshold: number;
+}): Call;
+declare function buildExecuteSetThresholdCall(args: {
+    walletAddress: bigint | string;
+    opId: bigint | string;
+    newThreshold: number;
+}): Call;
+/**
+ * Build a `cancel_pending_op(op_id)` call. Valid any time before the
+ * op is executed; signed by any current owner via OE.
+ */
+declare function buildCancelPendingOpCall(args: {
+    walletAddress: bigint | string;
+    opId: bigint | string;
+}): Call;
+/**
+ * Build an `initiate_recovery(proposer, new_owner_kind, new_pubkey_bytes,
+ * new_role, new_weight, new_label)` call.
+ *
+ * IMPORTANT: `proposer` MUST be an owner with `role == ROLE_GUARDIAN`.
+ * If it's a regular owner, the wallet panics with
+ * `'RECOVERY: not a guardian'`. The new owner being recovered to is
+ * typically `role: "OWNER"` so it can sign after the timelock.
+ *
+ * After confirmation, the wallet starts a 7-day timelock
+ * (`TIMELOCK_SECONDS.RECOVERY`). During the window:
+ *   - Any current ROLE_OWNER can call `cancel_recovery` to abort.
+ *   - After the window, anyone can call `finalize_recovery`.
+ */
+declare function buildInitiateRecoveryCall(args: {
+    walletAddress: bigint | string;
+    /** owner_id of the guardian that's initiating */
+    proposer: number;
+    newOwner: NewOwnerInput;
+}): Call;
+/**
+ * Build a `cancel_recovery(owner_id)` call. Signed by any current
+ * ROLE_OWNER via OE — the canceler must hold a working signing key.
+ * The owner_id arg identifies which owner is canceling (used by the
+ * wallet for event attribution and the not-revoked / role-OWNER check).
+ */
+declare function buildCancelRecoveryCall(args: {
+    walletAddress: bigint | string;
+    ownerId: number;
+}): Call;
+/**
+ * Build a `finalize_recovery(new_owner_kind, new_pubkey_bytes, new_role,
+ * new_weight, new_label)` call.
+ *
+ * Permissionless after the 7-day timelock. The wallet recomputes the
+ * pubkey commitment and asserts equality against the stored value
+ * from `initiate_recovery`. Per audit H-1, the recovery path also
+ * library-calls the per-kind verifier so a poison-pill pubkey from a
+ * compromised guardian still fails at finalize time, not silently.
+ *
+ * Recovery is additive — existing owners stay. Follow up with
+ * `buildProposeRemoveOwnerCall` for the stale devices.
+ *
+ * Because this call is NOT `_assert_self_call`-gated, the integrator
+ * can either wrap it in an OE (signed by anyone) or dispatch directly
+ * via a regular invoke. The Call shape is the same.
+ */
+declare function buildFinalizeRecoveryCall(args: {
+    walletAddress: bigint | string;
+    newOwner: NewOwnerInput;
+}): Call;
+/**
+ * Compute the selector for a view; convenient for `provider.callContract`.
+ * Exposed so SDK consumers can build their own `{ contractAddress,
+ * entryPointSelector, calldata }` `Call`-shaped views without
+ * re-deriving selectors.
+ */
+declare const VIEW_SELECTORS: {
+    readonly get_pending_op: string;
+    readonly get_pending_recovery: string;
+    readonly get_owner: string;
+};
+/**
+ * Given a `valid_after` block timestamp (seconds) returned from
+ * `get_pending_op` or `get_pending_recovery`, compute whether the
+ * timelock has elapsed against a given clock reading. Cheap UI helper
+ * so consumers don't reach for a date library. Accepts fractional
+ * `number` seconds (e.g., `Date.now() / 1000`) — truncates via floor.
+ */
+declare function isReadyToExecute(validAfterSecs: number | bigint, nowSecs: number): boolean;
+/**
+ * Seconds remaining until a pending op / recovery becomes executable.
+ * Returns 0 when the timelock has already elapsed. Useful for showing
+ * a countdown in UI without a separate clock import. Accepts fractional
+ * `number` seconds — truncates via floor.
+ */
+declare function secondsUntilExecutable(validAfterSecs: number | bigint, nowSecs: number): number;
+
+/**
+ * SHHH V8.4 threshold envelope assembly + gas estimation.
+ *
+ * Wave B PR B2. The single-owner OE flow already ships via
+ * `wrap_v2_snip12_envelope` in `oe.ts`. This module adds the
+ * multi-owner threshold flow: N owners (possibly with mixed signer
+ * kinds) co-sign a single OE, and the wallet's
+ * `execute_from_outside_v2` walks the envelope to verify each owner
+ * independently before checking total weight against the configured
+ * threshold.
+ *
+ * Cairo dispatch shape (`src/account.cairo:418-460`):
+ *
+ *   signature = [
+ *     V2_THRESHOLD,         // tag
+ *     n,                    // u32, MUST be >= 2 and <= owner_count
+ *     env_1_len,            // u32
+ *     ...env_1 (env_1_len felts),
+ *     env_2_len,
+ *     ...env_2,
+ *     ...
+ *     env_n_len,
+ *     ...env_n,
+ *   ]
+ *
+ * Each inner envelope is a V2_SNIP12 single-owner envelope
+ * (`wrap_v2_snip12_envelope` output) from a different owner. Nested
+ * threshold envelopes are NOT permitted — the Cairo `_verify_sub_envelope`
+ * recursively checks the inner tag and rejects anything except
+ * V2_SNIP12.
+ *
+ * Cairo-enforced invariants this module replicates client-side so
+ * mis-shaped envelopes fail at the SDK boundary with a clear message
+ * instead of with an opaque "THRESH: …" Starknet revert:
+ *
+ *   - signature.len() >= 2
+ *   - n >= 2 (n=1 is invalid — use V2_SNIP12 directly for single-owner)
+ *   - each inner env_len >= 2
+ *   - no buffer overflow / truncation
+ *   - no trailing bytes after the last inner envelope
+ *   - no duplicate owner_id across inner envelopes (extracted from
+ *     envelope[1] of each inner)
+ *
+ * Total-weight vs threshold is enforced ON-CHAIN (the SDK can't know
+ * the configured threshold without reading on-chain state). Use
+ * `estimateThresholdGasOverhead` to predict paymaster fees.
+ */
+
+/** Minimum number of inner envelopes in a threshold (Cairo enforces >= 2). */
+declare const MIN_THRESHOLD_OWNERS = 2;
+/**
+ * Validate that an envelope is a well-formed V2_SNIP12 single-owner
+ * envelope suitable for inclusion in a threshold envelope. Returns
+ * the extracted `owner_id` (envelope[1]) so the caller can dedupe.
+ *
+ * Rejects nested threshold envelopes (`signature[0] == V2_THRESHOLD`)
+ * — V8.4 does not allow nesting; the Cairo `_verify_sub_envelope`
+ * would revert with `'SRC9: bad tag'`.
+ */
+declare function assertValidV2Snip12Envelope(envelope: bigint[]): bigint;
+/**
+ * Build a V2_THRESHOLD envelope from a list of pre-signed V2_SNIP12
+ * inner envelopes. Each inner envelope must come from a DIFFERENT
+ * owner — duplicates fail loudly here instead of on-chain.
+ *
+ * The typical UI flow:
+ *   1. Compute the OE message hash once (computeOeHash from oe.ts)
+ *   2. Distribute the hash to N owners (push notification, QR, etc.)
+ *   3. Each owner signs with their kind's envelope builder and
+ *      returns the resulting `bigint[]`
+ *   4. UI collects the envelopes and calls this function
+ *   5. UI submits the resulting threshold envelope as the
+ *      `signature` field of `paymaster_executeSponsoredRaw.calldata`
+ *
+ * `buildThresholdEnvelope` does NOT submit anything. It returns the
+ * felt span that goes into the OE calldata.
+ */
+declare function buildThresholdEnvelope(args: {
+    innerEnvelopes: bigint[][];
+}): bigint[];
+/**
+ * Split a V2_THRESHOLD envelope back into its constituent inner
+ * V2_SNIP12 envelopes. Inverse of `buildThresholdEnvelope`.
+ *
+ * Useful for UI flows that need to display "N of M signers signed
+ * so far" status without re-deriving from individual envelopes. Also
+ * useful in tests for round-trip validation.
+ *
+ * Throws if the envelope is malformed (tag mismatch, n < 2, length
+ * mismatch, trailing bytes). Mirrors the Cairo dispatch's structural
+ * checks (`src/account.cairo:418-456`) so the same envelope that
+ * would parse-fail here would also revert on-chain.
+ */
+declare function parseThresholdEnvelope(envelope: bigint[]): {
+    innerEnvelopes: bigint[][];
+};
+/**
+ * Predict the on-chain L2 gas overhead a threshold envelope will
+ * consume. Each inner envelope dispatches to its kind's verifier
+ * class via `library_call`, so total overhead is the sum of
+ * per-kind overheads.
+ *
+ * Returned value is the same unit as `SHHH_KIND_GAS_OVERHEAD` in
+ * `@chipi-stack/shared` (raw L2 gas units). Use to predict paymaster
+ * fees:
+ *   estimatedFee = baselineOEGas + estimateThresholdGasOverhead(owners)
+ *
+ * Does NOT include the wallet's threshold-validation loop overhead
+ * (the deduplication walk and weight summation) — that's a constant
+ * ~50K L2 gas regardless of N, and the paymaster's fee predictor
+ * already accounts for it.
+ */
+declare function estimateThresholdGasOverhead(owners: Array<{
+    signerKind: ShhhSignerKind;
+}>): number;
+
+/**
+ * SHHH V8.4 migration builders — sessions / OZ → V8.4.
+ *
+ * Wave B PR B4. Covers two paths:
+ *
+ *   1. Happy-path atomic multicall (`buildMigrationCalls`)
+ *      Used when the legacy wallet is still operational and can sign
+ *      an OutsideExecution. The wallet emits one OE containing two
+ *      calls in order:
+ *
+ *        upgrade(SHHH_ACCOUNT_CLASS_HASH)
+ *        bootstrap_from_sessions(public_key, STARK_VERIFIER_CLASS_HASH, label)
+ *
+ *      Atomicity is the security property — between `upgrade` and
+ *      `bootstrap_from_sessions` an attacker watching the mempool
+ *      could call `bootstrap_from_sessions(attacker_pk, ...)` first
+ *      and seize the account. The OE bundles them so that race
+ *      window doesn't exist.
+ *
+ *   2. Stranded-state recovery (`buildBootstrapSignedCall` +
+ *      `computeBootstrapMessage` + `signBootstrapMessage`)
+ *      Used when the legacy multicall ran but `bootstrap_from_sessions`
+ *      silently reverted (the old chipi-pay/sessions-smart-contract's
+ *      `_execute_calls` swallowed subcall errors at a
+ *      `Result::Err(_) => res.append(array![].span())` site). The
+ *      account is at V8.4 class but `primary_kind == 0`.
+ *
+ *      Recovery: anyone calls
+ *
+ *        bootstrap_from_sessions_signed(
+ *          public_key, stark_verifier_class, label, signature_r, signature_s
+ *        )
+ *
+ *      where (r, s) is a STARK ECDSA signature over
+ *
+ *        bootstrap_msg = poseidon([
+ *          'SHHH_BOOTSTRAP_V8_4',
+ *          account_address,
+ *          public_key,
+ *          stark_verifier_class,
+ *          label,
+ *        ])
+ *
+ *      Authorization comes from two independent checks on-chain:
+ *        - the preserved `LEGACY_OZ_ACCOUNT_PUBKEY_SLOT` storage slot
+ *          must equal `public_key` (audit C-1 binding to the original
+ *          owner)
+ *        - the signature must verify under `public_key`
+ *
+ *      So this entrypoint is callable from any sponsor / relayer
+ *      without a self-call channel, but is non-transferable: only the
+ *      original owner who controls the STARK private key can produce
+ *      a valid signature.
+ *
+ * Cairo source of truth:
+ *   shhh-wallet-cairo/src/account.cairo:1024  bootstrap_from_sessions
+ *   shhh-wallet-cairo/src/account.cairo:1113  bootstrap_from_sessions_signed
+ *   shhh-wallet-cairo/scripts/ts/migrate-sessions-wallet.ts  (happy-path ref)
+ *
+ * What this module does NOT cover (out of scope for B4):
+ *   - The upstream OE-build + sign step. Caller wraps these `Call`s
+ *     with `buildOutsideExecution` + `buildStarkEnvelope` and submits
+ *     via the paymaster. Same flow as B1's governance builders.
+ *   - Verifying on-chain whether a wallet is stranded. Done by the
+ *     dashboard / UI; here we just produce the recovery call.
+ */
+
+/**
+ * Domain separator the on-chain signed-bootstrap message uses as its
+ * first felt. Mirrors `'SHHH_BOOTSTRAP_V8_4'` literal at
+ * `src/account.cairo:1170`.
+ */
+declare const BOOTSTRAP_DOMAIN_SEPARATOR: bigint;
+/**
+ * Encode a label string as a Starknet short-string felt252.
+ *
+ * starknet.js `shortString.encodeShortString` accepts only ASCII
+ * characters and rejects strings longer than 31 characters (it
+ * stuffs one character per byte, and felt252 has 251 useful bits).
+ * We pre-validate here so callers get a clear error instead of the
+ * generic encoder revert; the previous "≤31 bytes" message was
+ * misleading because non-ASCII strings would silently slip past a
+ * UTF-16 `.length` check.
+ */
+declare function labelToFelt(label: string): bigint;
+interface BuildMigrationCallsParams {
+    /** Address of the legacy CHIPI v29 / sessions wallet being migrated. */
+    legacyAccountAddress: bigint | string;
+    /** STARK public key currently stored in the legacy wallet's OZ slot. */
+    legacyPublicKey: bigint | string;
+    /** Target SHHH ShhhAccount class hash (e.g. `WALLET_CLASS_HASHES.SHHH`). */
+    shhhAccountClassHash: bigint | string;
+    /** STARK verifier class hash (`SHHH_VERIFIER_CLASS_HASHES.STARK`). */
+    starkVerifierClassHash: bigint | string;
+    /** Optional user-facing tag bound into the V8.4 owner record (≤31 ASCII characters). */
+    label?: string;
+}
+/**
+ * Build the two-call atomic multicall that migrates a legacy
+ * CHIPI v29 (chipi-pay/sessions-smart-contract) wallet to SHHH V8.4.
+ *
+ * Caller's responsibility:
+ *   1. Wrap the returned `Call[]` in a single `OutsideExecution`
+ *      against the legacy wallet's address.
+ *   2. Sign the OE with the legacy wallet's STARK key (the SDK's
+ *      legacy CHIPI flow already does this; use that signer here).
+ *   3. Submit via the paymaster.
+ *
+ * The multicall MUST be atomic — if any call between the two could
+ * land independently on chain (e.g. via mempool front-running), the
+ * resulting `upgrade`-but-not-`bootstrap` state is exploitable.
+ * Bundling them in a single OE makes both calls land atomically.
+ *
+ * Returns the calls in order: [upgrade, bootstrap_from_sessions].
+ */
+declare function buildMigrationCalls(params: BuildMigrationCallsParams): Call[];
+interface BootstrapMessageParams {
+    /** The (already-upgraded) SHHH wallet's contract address. */
+    accountAddress: bigint | string;
+    /** STARK public key originally stored in the legacy OZ slot. */
+    publicKey: bigint | string;
+    /** STARK verifier class hash to set as primary. */
+    starkVerifierClassHash: bigint | string;
+    /** User-facing tag bound into the V8.4 owner record (≤31 ASCII characters). */
+    label?: string;
+}
+/**
+ * Compute the canonical bootstrap message the on-chain
+ * `bootstrap_from_sessions_signed` verifier will check the STARK
+ * ECDSA signature against:
+ *
+ *   poseidon([
+ *     'SHHH_BOOTSTRAP_V8_4',
+ *     account_address,
+ *     public_key,
+ *     stark_verifier_class,
+ *     label,
+ *   ])
+ *
+ * Domain separation via the literal prefix means a signature produced
+ * for this message can never be replayed as a different intent
+ * (audit point — covered in `audit_poc_attacker_can_seize_any_stranded_wallet`).
+ */
+declare function computeBootstrapMessage(params: BootstrapMessageParams): bigint;
+/**
+ * Sign the canonical bootstrap message with a STARK private key.
+ *
+ * Used in two situations:
+ *   - Server-side test fixtures + the Wave B B9 mainnet smoke
+ *   - "Recovery as a service" flows where the SDK is allowed to hold
+ *     a temporary STARK key custodied for the user
+ *
+ * Most production flows will instead sign via the user's wallet
+ * (e.g. by exposing the message hash to the legacy wallet's STARK
+ * signing endpoint) and pass `(r, s)` directly to
+ * `buildBootstrapSignedCall`.
+ */
+declare function signBootstrapMessage(params: {
+    privateKey: bigint | string;
+    message: BootstrapMessageParams;
+}): {
+    r: bigint;
+    s: bigint;
+};
+interface BuildBootstrapSignedCallParams {
+    /** The stranded SHHH wallet's contract address. */
+    accountAddress: bigint | string;
+    /** STARK public key originally stored in the legacy OZ slot. */
+    publicKey: bigint | string;
+    /** STARK verifier class hash. Must match the value the original migration intended. */
+    starkVerifierClassHash: bigint | string;
+    /** User-facing tag (≤31 ASCII characters). Must match the original migration intent. */
+    label?: string;
+    /** STARK ECDSA signature r component over `computeBootstrapMessage(...)`. */
+    signatureR: bigint | string;
+    /** STARK ECDSA signature s component. */
+    signatureS: bigint | string;
+}
+/**
+ * Build a `bootstrap_from_sessions_signed(public_key, stark_verifier_class,
+ * label, signature_r, signature_s)` call against a stranded SHHH wallet.
+ *
+ * Permissionless on-chain — anyone (typically a sponsor / relayer)
+ * can dispatch this call. The signature is the auth. So the integrator
+ * does NOT need to wrap it in an OE from the wallet itself; it goes
+ * out as a regular invoke from any STARK account.
+ *
+ * Returns the `Call` for the integrator's account-abstraction layer
+ * (e.g. a chipi-back service account, or a one-off operator wallet).
+ */
+declare function buildBootstrapSignedCall(params: BuildBootstrapSignedCallParams): Call;
+
+/**
+ * High-level SHHH V8.4 OE execution path for the backend SDK.
+ *
+ * This module is the glue between the low-level OE builders in
+ * `oe.ts` + `signers/*.ts` and chipi-back's
+ * `POST /transactions/execute-sponsored-raw` endpoint.
+ *
+ * Why this exists separately from the legacy
+ * `executePaymasterTransaction` flow:
+ *
+ *   - The Chipi paymaster cannot synthesize SHHH envelopes server-side
+ *     (each of the 10 V8.4 signer kinds has a different envelope
+ *     shape; the paymaster's design — see chipi-pay/paymaster#16 — is
+ *     to pass the signature span verbatim to `execute_from_outside_v2`).
+ *   - Therefore SHHH clients MUST build + sign the OE locally and
+ *     submit it pre-signed to a forwarding endpoint
+ *     (`/transactions/execute-sponsored-raw`).
+ *   - The legacy flow (`prepare-typed-data` → sign → `execute-sponsored-
+ *     transaction`) is unchanged and continues to serve CHIPI / READY
+ *     wallets.
+ *
+ * Scope (Wave B, this PR): STARK + ED25519 signer kinds.
+ * EIP-191 / WEBAUTHN_P256 / JWT_ES256_APPLE_SUB still throw the
+ * deferred-feature error until the external-rooted wallet adapter
+ * flow lands.
+ */
+
+/**
+ * Pick the chain ID for SNIP-12 hashing. If the caller did not provide
+ * an explicit override, infer from the chipi-back base URL (sepolia
+ * hostnames map to SN_SEPOLIA; everything else maps to SN_MAIN per
+ * the project's mainnet-only invariant).
+ *
+ * Exported for unit-testing the resolver in isolation.
+ */
+declare function resolveShhhChainId(params: {
+    override?: bigint | string;
+    baseUrl?: string;
+}): string;
+/**
+ * Serialize an OutsideExecution struct + signature span into the
+ * flat felt-array calldata that `execute_from_outside_v2` expects.
+ *
+ * Cairo's serde order (per shhh-wallet-cairo v8.4
+ * `src/account.cairo::execute_from_outside_v2`):
+ *
+ *   caller
+ *   nonce
+ *   execute_after  (u64, 1 felt)
+ *   execute_before (u64, 1 felt)
+ *   calls.len()
+ *   for each Call:
+ *     to                 (felt)
+ *     selector           (felt)
+ *     calldata.len()
+ *     ...calldata felts
+ *   signature.len()
+ *   ...signature felts
+ *
+ * Returns 0x-prefixed lowercase hex strings ready for direct
+ * JSON-RPC submission via the chipi-back forwarder.
+ */
+declare function serializeExecuteFromOutsideV2Calldata(params: {
+    outsideExecution: {
+        caller: bigint | string;
+        nonce: bigint | string;
+        execute_after: bigint;
+        execute_before: bigint;
+        calls: Call[];
+    };
+    signature: bigint[];
+}): string[];
+/**
+ * Decrypt the wallet's STARK private key from its
+ * `encryptedPrivateKey` ciphertext + the per-wallet `encryptKey` (PIN
+ * or passkey-derived secret), build a SHHH V8.4 OE around the given
+ * inner calls, sign it with the wallet's STARK key, serialize the
+ * calldata for `execute_from_outside_v2`, and forward to chipi-back's
+ * `/transactions/execute-sponsored-raw` endpoint.
+ *
+ * Returns the on-chain transaction hash.
+ *
+ * Pre-conditions:
+ *  - `wallet.walletType === "SHHH"`.
+ *  - `wallet.publicKey` is the deployed account address (NOT the raw
+ *    STARK pubkey; V8.4 deployment derives address from kind-bound
+ *    salt + verifier).
+ *  - `wallet.encryptedPrivateKey` decrypts cleanly with `encryptKey`.
+ *  - The wallet is already deployed (no deploy_and_invoke variant
+ *    here; that flow stays inside `createWallet`).
+ */
+declare function executeShhhSponsoredRaw(params: {
+    client: ChipiClient;
+    bearerToken: string;
+    wallet: {
+        publicKey: string;
+        encryptedPrivateKey: string;
+        walletType?: string;
+    };
+    encryptKey: string;
+    calls: Call[];
+    /**
+     * Defaults to `"STARK"`. Wave B ships STARK + ED25519. EIP-191 /
+     * WEBAUTHN_P256 / JWT_ES256_APPLE_SUB are deferred to the
+     * external-rooted wallet adapter PRs.
+     */
+    signerKind?: "STARK" | "ED25519";
+    /** Override the OE nonce; default = `Date.now() << 24 | random24bit`. */
+    nonce?: bigint;
+    /** Optional externalUserId for the audit-log hint. */
+    externalUserId?: string;
+    /**
+     * Override the chain ID used for SNIP-12 hashing. Defaults to
+     * mainnet per CLAUDE.md's mainnet-only invariant; sepolia is auto-
+     * inferred from the chipi-back base URL when present. Drift here
+     * = the V8.4 account rejects the signature on chain.
+     */
+    chainId?: bigint | string;
+}): Promise<string>;
+
+export { ANY_CALLER_FELT, APPLE_ISSUER, type AppleTokenResponse, BOOTSTRAP_DOMAIN_SEPARATOR, type BootstrapMessageParams, type BuildBootstrapSignedCallParams, type BuildMigrationCallsParams, ChipiBrowserSDK, ChipiClient, ChipiPaymasterAdapter, ChipiSDK, ChipiServerSDK, ChipiSessions, ChipiSkuPurchases, ChipiSkus, ChipiTransactions, ChipiWallets, type ComputeAddressInput, DEFAULT_OP_EXPIRY_SECONDS, type Eip191Pubkey, ISIGNER_CANONICAL_LABEL, ISIGNER_ID, ISRC9_V2_ID, type JwtAppleSubPubkey, MAX_OE_VALIDITY_WINDOW_SECONDS, MIN_THRESHOLD_OWNERS, type NewOwnerInput, OE_DOMAIN_NAME, OE_DOMAIN_REVISION, OE_DOMAIN_VERSION, OP_ADD_OWNER, OP_REMOVE_OWNER, OP_ROTATE_OWNER, OP_SET_THRESHOLD, type OutsideExecution, type OwnerRole, ROLE_GUARDIAN, ROLE_OWNER, SIG_VERSION_V1_HEX_ASCII, SIG_VERSION_V2_SNIP12, SIG_VERSION_V2_THRESHOLD, STARKNET_MESSAGE_PREFIX, type ShhhX402Wallet, TIMELOCK_SECONDS, VIEW_SELECTORS, type WebAuthnPubkey, X402Facilitator, type X402FacilitatorCreateOptions, type X402MiddlewareConfig, type X402MiddlewareFlatConfig, X402ShhhClient, type X402ShhhClientConfig, assertValidV2Snip12Envelope, buildBootstrapSignedCall, buildCancelPendingOpCall, buildCancelRecoveryCall, buildEd25519Envelope, buildEd25519EnvelopeFromSignature, buildEip191EnvelopeFromPrivateKey, buildEip191EnvelopeFromSignature, buildExecuteAddOwnerCall, buildExecuteRemoveOwnerCall, buildExecuteRotateOwnerCall, buildExecuteSetThresholdCall, buildFinalizeRecoveryCall, buildInitiateRecoveryCall, buildJwtAppleSubEnvelopeFromTestKey, buildJwtAppleSubEnvelopeFromTokenResponse, buildMigrationCalls, buildOutsideExecution, buildProposeAddOwnerCall, buildProposeRemoveOwnerCall, buildProposeRotateOwnerCall, buildProposeSetThresholdCall, buildStarkEnvelope, buildThresholdEnvelope, buildWebAuthnEnvelopeFromAssertion, buildWebAuthnEnvelopeFromPrivateKey, byteArrayToFelts, computeAddressSalt, computeBootstrapMessage, computeISignerId, computeOeHash, computeShhhAddress, computeSnip12Hash, decryptPrivateKey, ed25519OwnerId, ed25519PubkeyFelts, ed25519SignedBytes, eip191OwnerId, eip191PubkeyFelts, encryptPrivateKey, estimateThresholdGasOverhead, executeShhhSponsoredRaw, hashCall, hashCalls, hashOutsideExecutionStruct, hashStarknetDomain, isReadyToExecute, jwtAppleSubHash, jwtAppleSubOwnerId, jwtAppleSubPubkeyFelts, labelToFelt, locateSubClaim, messageHashToNonceB64url, ownerCommitment, parseAppleIdToken, parseDerEcdsaSignature, parseEip191Signature, parseThresholdEnvelope, resolveShhhChainId, secondsUntilExecutable, serializeExecuteFromOutsideV2Calldata, signBootstrapMessage, signTypedData, snip12HashToHexAsciiBytes, starkOwnerId, starkPubkeyFelts, webauthnOwnerId, webauthnPubkeyFelts, wrapV2Snip12Envelope, wrapV2ThresholdEnvelope, x402Middleware };