decane-connect-kit 2.7.5 → 2.8.0

package/dist/index.d.ts

@@ -1,258 +1,569 @@
 import * as _simplewebauthn_browser from '@simplewebauthn/browser';
 import React, { ReactNode } from 'react';
 
-type ChainType = "evm" | "solana" | "tron" | "bitcoin";
-type ChainSupport = ChainType[];
-interface ChainDescriptor {
-    id: string;
-    type: ChainType;
-    name: string;
-    nativeCurrency: {
-        name: string;
-        symbol: string;
-        decimals: number;
+interface RecoveryShareFile {
+    version: number;
+    type: 'decane-recovery-share';
+    shareSetVersion: number;
+    kdf: 'pbkdf2-sha256';
+    kdfParams: {
+        iterations: number;
+        salt: string;
     };
-    rpcUrl?: string;
-    blockExplorerUrl?: string;
-    iconUrl?: string;
-    chainId?: number;
-    isCustom?: boolean;
-}
-interface UnifiedWalletAccount {
-    id: string;
-    name: string;
-    icon: string;
-    rdns?: string;
-    chainSupport: ChainSupport;
-    evmProvider?: EIP1193Provider;
-    solanaProvider?: StandardWallet;
-    tronProvider?: TronProvider;
-    bitcoinProvider?: BitcoinProvider;
-}
-type CAIP25Method = "wallet_requestPermissions" | "wallet_revokePermissions" | "wallet_getPermissions" | "wallet_sendTransaction" | "wallet_signMessage" | "wallet_signTypedData";
-interface ChainScope {
-    methods: CAIP25Method[];
-    accounts: string[];
-    events?: string[];
-}
-interface CAIP25SessionRequest {
-    requiredScopes: Partial<Record<string, ChainScope>>;
-    optionalScopes: Partial<Record<string, ChainScope>>;
+    cipher: 'aes-256-gcm';
+    iv: string;
+    ciphertext: string;
+    addresses: {
+        evm: string;
+        solana: string;
+    };
+    passwordHint: string | null;
+    createdAt: string;
 }
-interface CAIP25SessionResult {
-    sessionId: string;
-    grantedScopes: Partial<Record<string, ChainScope>>;
+
+interface PortableBackup {
+    version: number;
+    type: 'decane-portable-backup';
+    shareSetVersion: number;
+    kdf: 'pbkdf2-sha256';
+    kdfParams: {
+        iterations: number;
+        salt: string;
+    };
+    cipher: 'aes-256-gcm';
+    iv: string;
+    ciphertext: string;
+    addresses: {
+        evm: string;
+        solana: string;
+    };
+    passwordHint: string | null;
+    createdAt: string;
 }
-interface ActiveSession {
-    sessionId: string;
-    grantedScopes: Partial<Record<string, ChainScope>>;
-    walletId: string;
-    walletType: ChainType | "multi";
-    createdAt: number;
+
+interface BalanceResult {
+    /** Smallest unit — wei for EVM, lamports for Solana. */
+    raw: bigint;
+    /** Human-readable amount in whole native units, e.g. "1.2345". */
+    formatted: string;
+    /** Native currency symbol, e.g. "ETH", "MATIC", "SOL". */
+    symbol: string;
+    /** Decimals of the native currency (18 for EVM, 9 for Solana). */
+    decimals: number;
 }
-interface DecaneProvider {
+
+interface Eip1193Provider {
     request(args: {
         method: string;
-        params?: unknown[];
+        params?: unknown[] | object;
     }): Promise<unknown>;
-    on(event: string, handler: (...args: unknown[]) => void): void;
-    off(event: string, handler: (...args: unknown[]) => void): void;
-    readonly wallets: UnifiedWalletAccount[];
-    readonly evmWallets: UnifiedWalletAccount[];
-    readonly solanaWallets: UnifiedWalletAccount[];
-    readonly multiChainWallets: UnifiedWalletAccount[];
-    readonly tronWallets: UnifiedWalletAccount[];
-    readonly bitcoinWallets: UnifiedWalletAccount[];
-    connect(wallet: UnifiedWalletAccount, preferredChain?: ChainType): Promise<void>;
-    disconnect(): Promise<void>;
-    addChain(chain: ChainDescriptor): void;
-    removeChain(chainId: string): void;
-    getChain(chainId: string): ChainDescriptor | undefined;
-    readonly chains: ChainDescriptor[];
-    readonly connectedWallet: UnifiedWalletAccount | null;
-    readonly activeSession: ActiveSession | null;
-    readonly activeChain: string | null;
+    on(event: string, handler: (...args: unknown[]) => void): this;
+    removeListener(event: string, handler: (...args: unknown[]) => void): this;
+    /** Marks this as the Decane provider (parallel to wallets' isMetaMask etc.). */
+    readonly isDecane: true;
 }
-type ConnectMode = "all" | "social" | "wallets" | "evm" | "solana" | "tron" | "evm+social" | "solana+social" | "tron+social" | "evm+tron" | "evm+tron+social";
-interface SocialConfig {
+interface EthereumProviderOptions {
+    /** Initial chain id (numeric). Defaults to the first configured EVM chain, else 1. */
+    chainId?: number;
+    /** Per-chain RPC overrides ('evm:8453' -> url). Falls back to Decane's defaults. */
+    rpcUrls?: Record<string, string>;
+}
+/**
+ * Build an EIP-1193 provider over a connected Decane social client.
+ *
+ * `signAuthorization` (EIP-7702) is wired only when the client exposes it — that
+ * requires the TEE signer to support the authorization signing path.
+ */
+declare function createEthereumProvider(client: DecaneConnect, opts?: EthereumProviderOptions): Eip1193Provider;
+
+interface SignedAuthorization {
+    chainId: number;
+    address: string;
+    nonce: number;
+    yParity: number;
+    r: string;
+    s: string;
+}
+
+type Chain = `evm:${number}` | `solana:${'mainnet' | 'devnet'}` | `tron:${'mainnet' | 'shasta' | 'nile'}`;
+interface DecaneConnectConfig {
+    /** Dashboard project ID (public). Sent with every request so the backend can
+     *  confirm the API key below actually belongs to this project. */
+    appId: string;
     apiKey: string;
-    authMethods?: ("google" | "email" | "kingschat")[];
+    chains: Chain[];
+    authMethods: Array<'google' | 'email' | 'phone' | 'kingschat'>;
     /**
-     * Scopes requested from KingsChat. Defaults to `['send_chat_message']`, which
-     * is what KingsChat's own SDK asks for and is enough to establish identity.
+     * Scopes requested from KingsChat at sign-in. Defaults to
+     * `['send_chat_message']`, which is what KingsChat's own SDK asks for and is
+     * enough to establish identity. Widen only if the app actually calls
+     * KingsChat APIs on the user's behalf — the consent screen lists every scope,
+     * so asking for more than you use costs conversions.
      */
     kingsChatScopes?: string[];
-    promptPin?: () => Promise<string>;
     apiBaseUrl?: string;
-    chains?: string[];
-    rpcUrls?: Record<string, string>;
+    sessionDurationMinutes?: number;
+    promptPin?: () => Promise<string>;
     /**
-     * Show the built-in full-screen status overlay while a wallet is being
-     * created or unlocked. Default **true**.
+     * Require a fresh WebAuthn assertion for every signature, instead of letting
+     * an unlocked session sign freely until it expires. The TEE session stays
+     * warm — this costs one authenticator prompt per signature, not a re-auth or
+     * re-attestation — and the check is enforced inside the enclave, not here.
      *
-     * The overlay exists because those flows can take several seconds and often
-     * run right after a Google redirect, when no modal of yours is mounted — so
-     * without it the page can look frozen. It is rendered by `<DecaneKit>` itself,
-     * as a portal, and injects its own theme tokens.
+     * Default false, which preserves the session-signing model: unlock once, sign
+     * for the session's lifetime with no further prompts.
      *
-     * Set false to suppress it and render your own. Everything it displays is
-     * already available to you: `useSocialAuth()` exposes `phase`
-     * (`"creating" | "unlocking" | null`) plus the `isCreatingWallet` /
-     * `isUnlockingWallet` booleans, and the client emits `wallet-creating` and
-     * `wallet-unlocking` events. If you suppress it, show something of your own —
-     * a silent multi-second pause reads as a broken page.
+     * Two things worth knowing before turning this on:
+     *  - Multi-step flows prompt per leg. An ERC-20 approve + swap is two
+     *    prompts, not one.
+     *  - The policy is declared by the client at session open, so it hardens a
+     *    leaked session handle (useless without the authenticator) but a fully
+     *    compromised page could open a session without it. Making it
+     *    unbypassable requires the policy to come from the server per user or
+     *    per project; that is not implemented yet.
      */
-    showStatusOverlay?: boolean;
+    requireAssertionPerSignature?: boolean;
+    rpId?: string;
+    rpName?: string;
+    rpcUrls?: Record<string, string>;
+    teeUrl?: string;
     /**
-     * Require a fresh WebAuthn assertion for every signature rather than letting
-     * an unlocked session sign freely until it expires. Enforced inside the TEE.
+     * Persist the live session (handle + JWT) in sessionStorage so a page RELOAD
+     * silently resumes it — no repeat passkey/sign-in. Survives reloads, cleared
+     * on tab close. Default true. Set false to require a fresh unlock on every
+     * page load (stricter, but the reload friction that motivated this returns).
+     */
+    persistSession?: boolean;
+    /**
+     * Offer to save a recovery-share file at signup. **Default false** since
+     * 2.7.4 — opt in explicitly with `true`.
      *
-     * Does not change the session lifetime — the session stays warm (no
-     * re-attestation, no re-auth) and authority is re-proven per signature
-     * instead. Default false. Needs a passkey; PIN-only wallets have no
-     * authenticator to assert with. See SocialConfig's counterpart in
-     * social/types.ts for the full caveats.
+     * The offer existed because a new device could not otherwise get a device
+     * share. Server-assisted provisioning now covers that case: every wallet is
+     * enrolled at creation, un-enrolled wallets repair themselves on the next
+     * unlock, and a returning user is provisioned from their sign-in alone. For
+     * almost every app the dialog is now a password prompt during onboarding that
+     * buys nothing, so it is off unless asked for.
+     *
+     * Recovery files themselves are unchanged and still work — `rotateShares()`
+     * issues one on demand, and `promptForRecoveryFile` still accepts one during
+     * recovery. Turn this back on if you want users to hold an offline fallback
+     * that does not depend on Decane being reachable.
      */
-    requireAssertionPerSignature?: boolean;
+    offerRecoveryAtSignup?: boolean;
+    /** Ask the user whether they want a recovery share and, if so, a password for it. */
+    onRecoveryShareOffer?: (addresses: {
+        evmAddress: string;
+        solanaAddress: string;
+    }) => Promise<{
+        wants: boolean;
+        password: string;
+        passwordHint?: string;
+    }>;
+    /** Hand the built file + suggested filename to the dApp, which owns the actual download. */
+    onRecoveryFileReady?: (file: RecoveryShareFile, filename: string) => Promise<void>;
+    /** Prompt for a recovery-share file (and its password) during Flow B. Return null to cancel. */
+    promptForRecoveryFile?: () => Promise<{
+        value: unknown;
+        getPassword: () => Promise<string | null>;
+    } | null>;
     /**
-     * Sign in with a token from your own auth system (Auth0, Clerk, Firebase,
-     * Cognito, or your own backend) — surfaced as a button in the built-in
-     * WalletSelector / SocialWalletModal UI, alongside Google and email.
-     * getToken() runs when the user clicks the button; wire it to however you
-     * already obtain a token from your auth system (e.g. after your own login
-     * flow completes). Configure the issuer and JWKS URL for this token
-     * against your project in the dashboard first. `providerId` is only
-     * needed when the project has more than one custom provider configured.
+     * Every successful recovery/rotation invalidates the previous recovery
+     * file — this MUST prompt for a new password and block progress until the
+     * dApp confirms the user saved the new file (see MIGRATE_SSS_RECOVERY.md §10).
      */
-    customAuth?: {
-        label: string;
-        providerId?: string;
-        getToken: () => Promise<string>;
-    };
-}
-interface DecaneConfig {
-    appId: string;
-    chains?: ChainDescriptor[];
-    supportedChainIds?: string[];
-    networks?: "evm" | "solana" | "tron" | "bitcoin" | "all";
-    defaultChain?: string;
-    theme?: "light" | "dark" | "auto";
-    mode?: ConnectMode;
-    social?: SocialConfig;
+    onRecoveryRotated?: (addresses: {
+        evmAddress: string;
+        solanaAddress: string;
+    }) => Promise<{
+        password: string;
+        passwordHint?: string;
+    }>;
+    /** Recovery stage callbacks, for dApp UI. */
+    onRecoveryProgress?: (event: RecoveryProgress) => void;
+    /**
+     * Rotate the whole share set whenever a NEW device recovers via passkey sync
+     * (Flow A) — the "every device holds a distinct share" model.
+     *
+     * Default false, which preserves the historical behaviour: every device
+     * synced to the same passkey caches the byte-identical wrapped share, so a
+     * device that is later lost keeps a share that stays valid until someone
+     * explicitly calls rotateShares(). There is no way to revoke one device
+     * without revoking all of them.
+     *
+     * With this on, joining a new device re-splits the master and issues that
+     * device its own share, which invalidates every other device's cached copy
+     * at the same instant. That is what makes per-device revocation possible,
+     * and it has three consequences worth accepting deliberately:
+     *
+     *  - **Other devices are logged out, not just the lost one.** Each surviving
+     *    device hits StaleDeviceShareError on its next unlock, clears its share,
+     *    and silently re-recovers through Flow A (one passkey prompt). Expected,
+     *    but it means a shared-family-device setup re-prompts more often.
+     *  - **The user's recovery FILE dies too.** Rotation issues a new recovery
+     *    share, so `onRecoveryRotated` MUST be configured to capture it —
+     *    enabling this without that callback throws at connect time rather than
+     *    stranding the user with a dead file.
+     *  - **Adding a device costs a TEE round trip.** Recovery is slower.
+     */
+    rotateOnNewDeviceRecovery?: boolean;
 }
-interface EIP1193Provider {
-    request(args: {
-        method: string;
-        params?: unknown[];
-    }): Promise<unknown>;
-    on(event: string, handler: (...args: unknown[]) => void): void;
-    removeListener(event: string, handler: (...args: unknown[]) => void): void;
+interface ConnectResult {
+    addresses: {
+        evm?: string;
+        solana?: string;
+        tron?: string;
+    };
+    isNewUser: boolean;
+    /** Present when the provider released a profile — see {@link AuthProfile}. */
+    profile?: AuthProfile;
 }
-interface StandardWallet {
-    name: string;
-    icon: string;
-    features: Record<string, unknown>;
-    accounts: StandardWalletAccount[];
+/** A recorded on-chain transaction in the user's history. */
+interface TransactionRecord {
+    id: string;
+    chain: string;
+    kind: string;
+    txHash: string | null;
+    to: string | null;
+    value: string | null;
+    status: 'submitted' | 'confirmed' | 'failed' | string;
+    metadata: Record<string, unknown> | null;
+    createdAt: string;
+    updatedAt?: string;
 }
-interface StandardWalletAccount {
-    address: string;
-    publicKey: Uint8Array;
-    chains: string[];
+/** What the dApp passes to record a transaction it broadcast. */
+interface RecordTransactionInput {
+    chain: string;
+    txHash?: string;
+    to?: string;
+    value?: string;
+    kind?: string;
+    status?: string;
+    metadata?: Record<string, unknown>;
 }
-interface TronProvider {
-    request(args: {
-        method: string;
-        params?: unknown[] | Record<string, unknown>;
-    }): Promise<unknown>;
-    on(event: string, handler: (...args: unknown[]) => void): void;
-    removeListener(event: string, handler: (...args: unknown[]) => void): void;
+interface SignMessageRequest {
+    chain: Chain;
+    message: string | Uint8Array;
 }
-interface BitcoinProvider {
-    requestAccounts(): Promise<string[] | Array<{
-        address: string;
-    }>>;
-    getAccounts?(): Promise<string[] | Array<{
-        address: string;
-    }>>;
-    signMessage(message: string, ...args: unknown[]): Promise<string>;
-    sendBitcoin?(toAddress: string, satoshis: number, options?: unknown): Promise<string>;
-    send?(params: unknown): Promise<string>;
-    signPsbt?(psbtHex: string, options?: unknown): Promise<string>;
-    on?(event: string, handler: (...args: unknown[]) => void): void;
+interface SendTransactionRequest {
+    chain: Chain;
+    to: string;
+    value?: bigint;
+    data?: string;
+    gasLimit?: bigint;
+    gasPrice?: bigint;
 }
-
-declare function createDecane(config: DecaneConfig): DecaneProvider;
-
-declare class ApiClient {
-    private readonly baseUrl;
-    private readonly apiKey;
-    private readonly appId;
-    constructor(baseUrl: string, apiKey: string, appId: string);
-    private _request;
-    getGoogleInitUrl(): Promise<{
-        url: string;
-    }>;
+interface SignTypedDataRequest {
+    chain: Chain;
+    domain: Record<string, unknown>;
+    types: Record<string, unknown>;
+    message: Record<string, unknown>;
+    primaryType?: string;
+}
+type SdkEvent = 'connected' | 'disconnected' | 'session-expired' | 'session-started' | 'wallet-creating' | 'wallet-unlocking'
+/**
+ * Emitted when this wallet could not be enrolled for server-assisted
+ * recovery. Not fatal — the wallet works — but until it is enrolled the user
+ * cannot get a device share from login alone, so a future new device will
+ * need a passkey backup or a recovery file. The SDK retries automatically on
+ * later unlocks; surface or report this if you want visibility rather than a
+ * console line.
+ */
+ | 'enrolment-failed';
+interface DecaneConnect {
+    connect(): Promise<ConnectResult>;
+    connectWithGoogle(): Promise<ConnectResult>;
     /**
-     * Exchange a Google ID token the app already holds for a Decane session.
-     * Resolves to the SAME identity as the redirect flow, so one Google account
-     * means one wallet across web and mobile.
+     * Sign in with a Google ID token the app already obtained — native Google
+     * Sign-In on mobile, or Google Identity Services on the web.
+     *
+     * Resolves to the SAME wallet as connectWithGoogle(): both end at the
+     * backend's Google identity, so a user who signs in on your website and then
+     * on your app lands on one wallet, not two.
      */
-    authGoogleToken(idToken: string): Promise<AuthResult>;
-    /** The project's KingsChat clientId, so the dApp never has to hardcode it. */
-    getKingsChatConfig(): Promise<{
-        clientId: string;
-        authorizationUrl: string;
+    connectWithGoogleToken(idToken: string): Promise<ConnectResult>;
+    /**
+     * Sign in with KingsChat.
+     *
+     * Opens KingsChat's consent screen in a popup, so this MUST be called
+     * directly from a click handler — a popup opened after an await is blocked by
+     * every browser. The resulting access token is exchanged server-side for a
+     * Decane session; it is never treated as one on its own.
+     */
+    connectWithKingsChat(): Promise<ConnectResult>;
+    /**
+     * Sign in with a KingsChat access token the app already holds — from
+     * kingschat-web-sdk, a native SDK, or any other flow. Use when you want to
+     * own the consent step yourself; connectWithKingsChat() is the turnkey path.
+     */
+    connectWithKingsChatToken(accessToken: string): Promise<ConnectResult>;
+    connectWithEmail(email: string): Promise<{
+        codeRequired: true;
     }>;
     /**
-     * Exchange a KingsChat access token for a Decane session. The backend spends
-     * the token against KingsChat's own API to establish the identity — it is
-     * never trusted on its face, and never stored.
+     * Sign in with a JWT from your own auth system (Auth0, Clerk, Firebase,
+     * Cognito, your own backend — anything that publishes a JWKS endpoint).
+     *
+     * Configure the issuer and JWKS URL against your project in the dashboard;
+     * no client-side setup and no secret in your dApp. `providerId` is only
+     * required if the project has more than one provider configured.
+     *
+     * The user's wallet is derived from the configured identity claim, so the
+     * same token subject always resolves to the same wallet.
      */
-    authKingsChat(accessToken: string): Promise<AuthResult>;
-    authEmailStart(email: string): Promise<void>;
-    authEmailVerify(email: string, code: string): Promise<AuthResult>;
-    getAddresses(jwt: string): Promise<{
-        evm: string | null;
-        solana: string | null;
-        tron: string | null;
+    connectWithToken(token: string, opts?: {
+        providerId?: string;
+    }): Promise<ConnectResult>;
+    verifyEmailCode(email: string, code: string): Promise<ConnectResult>;
+    /**
+     * Send a 6-digit sign-in code by SMS (delivered via Termii).
+     *
+     * `phone` must be **E.164** — `+2348012345678`. Local formats like
+     * `08012345678` are rejected rather than guessed at: the wallet is derived
+     * from the number, so guessing a country would either merge two people onto
+     * one wallet or split one person across two. Collect the country in your UI.
+     *
+     * Always resolves, whether or not the number has an account — the backend
+     * answers identically either way so this cannot be used to discover who is
+     * registered. Follow with {@link verifyPhoneCode}.
+     */
+    connectWithPhone(phone: string): Promise<{
+        codeRequired: true;
     }>;
-    putShare(jwt: string, share: {
-        ciphertext: Uint8Array;
-        iv: Uint8Array;
-        wrappedShareMeta: WrappedShareMeta;
-        evmAddress: string;
-        solanaAddress: string;
-        tronAddress: string;
-    }): Promise<void>;
-    recordTransaction(jwt: string, tx: {
-        chain: string;
-        txHash?: string;
-        to?: string;
-        value?: string;
-        kind?: string;
-        status?: string;
-        metadata?: Record<string, unknown>;
-    }): Promise<TransactionRecord>;
-    getTransactions(jwt: string, limit?: number): Promise<TransactionRecord[]>;
-    getWebAuthnRegisterOptions(jwt: string, rpId: string, rpName: string): Promise<_simplewebauthn_browser.PublicKeyCredentialCreationOptionsJSON>;
-    postWebAuthnRegister(jwt: string, response: _simplewebauthn_browser.RegistrationResponseJSON, origin: string): Promise<void>;
+    /** Verify the SMS code and open the wallet. Pass the same E.164 number. */
+    verifyPhoneCode(phone: string, code: string): Promise<ConnectResult>;
+    unlock(): Promise<void>;
+    isUnlocked(): boolean;
     /**
-     * Exchange a token from the developer's own auth system for a Decane
-     * session. `providerId` is only needed when the project has more than one
-     * provider configured.
+     * True when the user's identity is known from a previous visit but there is
+     * no live session, so unlock() cannot succeed and they must sign in again.
+     * Check this before offering an "Unlock" action.
+     *
+     * Note this can be true while canSignInWithPasskey() is also true — in which
+     * case "sign in again" costs one biometric prompt, not a full auth round
+     * trip. Prefer offering that over a Google/email button.
      */
-    authExternal(token: string, providerId?: string): Promise<AuthResult>;
+    needsReconnect(): boolean;
     /**
-     * Returns null when this user has no server-registered passkey, which is the
-     * expected answer for wallets created before passkey sign-in existed or for
-     * PIN-only users — the caller falls back to the normal sign-in flow.
+     * True when a returning user can be signed straight back in with the passkey
+     * already on this device — no Google redirect, no email code. Requires a
+     * remembered identity plus a passkey-wrapped device share in local storage,
+     * so it is false on new devices and for PIN-only wallets.
      */
-    getWebAuthnLoginOptions(userId: string, rpId: string): Promise<_simplewebauthn_browser.PublicKeyCredentialRequestOptionsJSON | null>;
-    postWebAuthnLogin(userId: string, response: _simplewebauthn_browser.AuthenticationResponseJSON, origin: string): Promise<AuthResult>;
-    revoke(jwt: string): Promise<void>;
-    hasRecoveryBackup(jwt: string): Promise<boolean>;
-    getRecoveryBackup(jwt: string): Promise<{
-        wrappedDeviceShare: Uint8Array;
+    canSignInWithPasskey(): Promise<boolean>;
+    /**
+     * Sign in using only the device passkey. connect() already tries this first
+     * when it's available, so call this directly only when driving the UI
+     * yourself. Throws NewDeviceError when this device isn't eligible.
+     */
+    signInWithPasskey(): Promise<ConnectResult>;
+    sessionExpiresAt(): number | null;
+    signMessage(req: SignMessageRequest): Promise<string>;
+    sendTransaction(req: SendTransactionRequest): Promise<string>;
+    /** Sign EIP-712 typed data (EVM only). Throws on a Solana chain. */
+    signTypedData(req: SignTypedDataRequest): Promise<string>;
+    /**
+     * A standard EIP-1193 Ethereum provider backed by this wallet — drop it into
+     * viem (`custom(provider)`), wagmi, or ethers (`BrowserProvider`). Signing
+     * goes through the TEE; reads are forwarded to the chain RPC. Memoized, so
+     * repeated calls return the same instance (safe for wagmi).
+     */
+    getEthereumProvider(opts?: {
+        chainId?: number;
+    }): Eip1193Provider;
+    /**
+     * Sign an EIP-7702 authorization, delegating this EOA to a smart-account
+     * implementation contract on `chainId`. Enables account-abstraction /
+     * sponsored-gas flows. Returns the full viem `SignedAuthorization` tuple, so
+     * it drops straight into a userOperation's `authorization` field or a type-4
+     * transaction's authorizationList. `address` and `contractAddress` are
+     * interchangeable (the latter matches Privy's/older viem's param name).
+     */
+    signAuthorization(req: {
+        chainId: number;
+        address?: string;
+        contractAddress?: string;
+        nonce: number;
+    }): Promise<SignedAuthorization>;
+    /**
+     * The current session's access token (the Decane JWT). Use it to authenticate
+     * the user to your own backend (e.g. a sponsored-bundler proxy); verify it
+     * server-side against backend.decane.app/.well-known/jwks.json. Null with no
+     * live session.
+     */
+    getAccessToken(): string | null;
+    signSolanaTransaction(tx: Uint8Array): Promise<Uint8Array>;
+    /**
+     * Sign a Tron transaction. Pass the transaction's `raw_data_hex` (the value
+     * TronWeb puts on a built transaction). The enclave computes the txID
+     * (sha256(raw_data)) and signs it with the same secp256k1 key as the EVM
+     * wallet; returns the 65-byte recoverable signature as 0x-hex. Attach it to
+     * the transaction's `signature` array and broadcast via TronWeb / a full node.
+     */
+    signTronTransaction(rawDataHex: string): Promise<string>;
+    /**
+     * Record a transaction this wallet broadcast, so it appears in the user's
+     * history (and the developer dashboard). EVM `sendTransaction` records itself
+     * automatically; call this for Solana/Tron transactions your dApp broadcasts,
+     * or to attach a `confirmed`/`failed` status update to an existing hash.
+     */
+    recordTransaction(tx: RecordTransactionInput): Promise<TransactionRecord>;
+    /** The user's transaction history, most recent first. Requires a live session. */
+    getTransactionHistory(limit?: number): Promise<TransactionRecord[]>;
+    disconnect(): Promise<void>;
+    getAddresses(): {
+        evm?: string;
+        solana?: string;
+        tron?: string;
+    } | null;
+    /**
+     * Native-token balance for a chain (defaults to the first configured EVM
+     * chain, else Solana). Read-only public data — works even while the wallet
+     * is locked. Returns raw (wei/lamports), a human `formatted` string, the
+     * native `symbol`, and `decimals`.
+     */
+    getBalance(chain?: string): Promise<BalanceResult>;
+    /** Native balances across every configured chain the wallet has an address for. */
+    getBalances(): Promise<Array<{
+        chain: string;
+        balance: BalanceResult | null;
+    }>>;
+    /**
+     * Voluntary share rotation — after a suspected device compromise, or just
+     * to invalidate an old recovery file. Requires a fresh WebAuthn assertion.
+     * Returns the new recovery-share file (the caller still owns delivering it
+     * to the user — this does not download anything itself).
+     */
+    rotateShares(opts: {
+        password: string;
+        passwordHint?: string;
+    }): Promise<RecoveryShareFile>;
+    /**
+     * The two-share bearer portable backup (device + recovery). This file plus
+     * its password gives complete control of the wallet — see the mandatory
+     * warning-screen requirements in MIGRATE_SSS_RECOVERY.md §10. Requires a
+     * fresh WebAuthn assertion and rotates the share set on every export.
+     */
+    exportPortableBackup(opts: {
+        password: string;
+        passwordHint?: string;
+    }): Promise<PortableBackup>;
+    /** Whether the user has ever saved a recovery-share file (UX flag only — Decane never stores the share). */
+    hasRecoveryShare(): Promise<boolean>;
+    /** True at most once per account: no recovery share saved, never nagged, wallet holds value. */
+    shouldPromptRecovery(): Promise<boolean>;
+    /** Call regardless of the user's answer — the recovery nag fires once, ever. */
+    dismissRecoveryPrompt(): Promise<void>;
+    /** Whether a wrapped-share backup exists on the server. */
+    hasBackup(): Promise<boolean>;
+    /** Delete the server-side backup. Disables Flow A recovery. */
+    deleteBackup(): Promise<void>;
+    on(event: SdkEvent, handler: (...args: unknown[]) => void): void;
+    off(event: SdkEvent, handler: (...args: unknown[]) => void): void;
+}
+interface WrappedShareMeta {
+    unlockMethod: 'passkey' | 'pin';
+    credentialId?: string;
+    prfSalt?: string;
+    pinSalt?: string;
+    pinIterations?: number;
+}
+/**
+ * Who the user is, as the identity provider just described them.
+ *
+ * Passed through from the provider at sign-in and never stored by Decane — the
+ * backend keeps only an HMAC and a masked identifier, so there is no profile to
+ * look up later. Cache what you need at sign-in if you want to show a name
+ * after a page reload.
+ *
+ * Every field is optional because providers differ in what they release, and a
+ * user can withhold most of it. Email sign-in returns an empty profile.
+ */
+interface AuthProfile {
+    name?: string;
+    email?: string;
+    picture?: string;
+}
+interface AuthResult {
+    jwt: string;
+    isNewUser: boolean;
+    hasShare: boolean;
+    userId: string;
+    profile?: AuthProfile;
+}
+
+declare class ApiClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly appId;
+    constructor(baseUrl: string, apiKey: string, appId: string);
+    private _request;
+    getGoogleInitUrl(): Promise<{
+        url: string;
+    }>;
+    /**
+     * Exchange a Google ID token the app already holds for a Decane session.
+     * Resolves to the SAME identity as the redirect flow, so one Google account
+     * means one wallet across web and mobile.
+     */
+    authGoogleToken(idToken: string): Promise<AuthResult>;
+    /** The project's KingsChat clientId, so the dApp never has to hardcode it. */
+    getKingsChatConfig(): Promise<{
+        clientId: string;
+        authorizationUrl: string;
+    }>;
+    /**
+     * Exchange a KingsChat access token for a Decane session. The backend spends
+     * the token against KingsChat's own API to establish the identity — it is
+     * never trusted on its face, and never stored.
+     */
+    authKingsChat(accessToken: string): Promise<AuthResult>;
+    authEmailStart(email: string): Promise<void>;
+    authEmailVerify(email: string, code: string): Promise<AuthResult>;
+    authPhoneStart(phone: string): Promise<void>;
+    authPhoneVerify(phone: string, code: string): Promise<AuthResult>;
+    getAddresses(jwt: string): Promise<{
+        evm: string | null;
+        solana: string | null;
+        tron: string | null;
+    }>;
+    putShare(jwt: string, share: {
+        ciphertext: Uint8Array;
+        iv: Uint8Array;
+        wrappedShareMeta: WrappedShareMeta;
+        evmAddress: string;
+        solanaAddress: string;
+        tronAddress: string;
+    }): Promise<void>;
+    recordTransaction(jwt: string, tx: {
+        chain: string;
+        txHash?: string;
+        to?: string;
+        value?: string;
+        kind?: string;
+        status?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<TransactionRecord>;
+    getTransactions(jwt: string, limit?: number): Promise<TransactionRecord[]>;
+    getWebAuthnRegisterOptions(jwt: string, rpId: string, rpName: string): Promise<_simplewebauthn_browser.PublicKeyCredentialCreationOptionsJSON>;
+    postWebAuthnRegister(jwt: string, response: _simplewebauthn_browser.RegistrationResponseJSON, origin: string): Promise<void>;
+    /**
+     * Exchange a token from the developer's own auth system for a Decane
+     * session. `providerId` is only needed when the project has more than one
+     * provider configured.
+     */
+    authExternal(token: string, providerId?: string): Promise<AuthResult>;
+    /**
+     * Returns null when this user has no server-registered passkey, which is the
+     * expected answer for wallets created before passkey sign-in existed or for
+     * PIN-only users — the caller falls back to the normal sign-in flow.
+     */
+    getWebAuthnLoginOptions(userId: string, rpId: string): Promise<_simplewebauthn_browser.PublicKeyCredentialRequestOptionsJSON | null>;
+    postWebAuthnLogin(userId: string, response: _simplewebauthn_browser.AuthenticationResponseJSON, origin: string): Promise<AuthResult>;
+    revoke(jwt: string): Promise<void>;
+    hasRecoveryBackup(jwt: string): Promise<boolean>;
+    getRecoveryBackup(jwt: string): Promise<{
+        wrappedDeviceShare: Uint8Array;
         iv: Uint8Array;
         unlockMethod: 'passkey';
         credentialId: Uint8Array;
@@ -301,480 +612,234 @@ type RecoveryProgress = {
     shareSetVersion: number;
 };
 
-interface RecoveryShareFile {
-    version: number;
-    type: 'decane-recovery-share';
-    shareSetVersion: number;
-    kdf: 'pbkdf2-sha256';
-    kdfParams: {
-        iterations: number;
-        salt: string;
-    };
-    cipher: 'aes-256-gcm';
-    iv: string;
-    ciphertext: string;
-    addresses: {
-        evm: string;
-        solana: string;
+type ChainType = "evm" | "solana" | "tron" | "bitcoin";
+type ChainSupport = ChainType[];
+interface ChainDescriptor {
+    id: string;
+    type: ChainType;
+    name: string;
+    nativeCurrency: {
+        name: string;
+        symbol: string;
+        decimals: number;
     };
-    passwordHint: string | null;
-    createdAt: string;
+    rpcUrl?: string;
+    blockExplorerUrl?: string;
+    iconUrl?: string;
+    chainId?: number;
+    isCustom?: boolean;
 }
-
-interface PortableBackup {
-    version: number;
-    type: 'decane-portable-backup';
-    shareSetVersion: number;
-    kdf: 'pbkdf2-sha256';
-    kdfParams: {
-        iterations: number;
-        salt: string;
-    };
-    cipher: 'aes-256-gcm';
-    iv: string;
-    ciphertext: string;
-    addresses: {
-        evm: string;
-        solana: string;
-    };
-    passwordHint: string | null;
-    createdAt: string;
-}
-
-interface BalanceResult {
-    /** Smallest unit — wei for EVM, lamports for Solana. */
-    raw: bigint;
-    /** Human-readable amount in whole native units, e.g. "1.2345". */
-    formatted: string;
-    /** Native currency symbol, e.g. "ETH", "MATIC", "SOL". */
-    symbol: string;
-    /** Decimals of the native currency (18 for EVM, 9 for Solana). */
-    decimals: number;
-}
-
-interface Eip1193Provider {
-    request(args: {
-        method: string;
-        params?: unknown[] | object;
-    }): Promise<unknown>;
-    on(event: string, handler: (...args: unknown[]) => void): this;
-    removeListener(event: string, handler: (...args: unknown[]) => void): this;
-    /** Marks this as the Decane provider (parallel to wallets' isMetaMask etc.). */
-    readonly isDecane: true;
-}
-interface EthereumProviderOptions {
-    /** Initial chain id (numeric). Defaults to the first configured EVM chain, else 1. */
-    chainId?: number;
-    /** Per-chain RPC overrides ('evm:8453' -> url). Falls back to Decane's defaults. */
-    rpcUrls?: Record<string, string>;
-}
-/**
- * Build an EIP-1193 provider over a connected Decane social client.
- *
- * `signAuthorization` (EIP-7702) is wired only when the client exposes it — that
- * requires the TEE signer to support the authorization signing path.
- */
-declare function createEthereumProvider(client: DecaneConnect, opts?: EthereumProviderOptions): Eip1193Provider;
-
-interface SignedAuthorization {
-    chainId: number;
-    address: string;
-    nonce: number;
-    yParity: number;
-    r: string;
-    s: string;
-}
-
-type Chain = `evm:${number}` | `solana:${'mainnet' | 'devnet'}` | `tron:${'mainnet' | 'shasta' | 'nile'}`;
-interface DecaneConnectConfig {
-    /** Dashboard project ID (public). Sent with every request so the backend can
-     *  confirm the API key below actually belongs to this project. */
-    appId: string;
-    apiKey: string;
-    chains: Chain[];
-    authMethods: Array<'google' | 'email' | 'kingschat'>;
-    /**
-     * Scopes requested from KingsChat at sign-in. Defaults to
-     * `['send_chat_message']`, which is what KingsChat's own SDK asks for and is
-     * enough to establish identity. Widen only if the app actually calls
-     * KingsChat APIs on the user's behalf — the consent screen lists every scope,
-     * so asking for more than you use costs conversions.
-     */
-    kingsChatScopes?: string[];
-    apiBaseUrl?: string;
-    sessionDurationMinutes?: number;
-    promptPin?: () => Promise<string>;
-    /**
-     * Require a fresh WebAuthn assertion for every signature, instead of letting
-     * an unlocked session sign freely until it expires. The TEE session stays
-     * warm — this costs one authenticator prompt per signature, not a re-auth or
-     * re-attestation — and the check is enforced inside the enclave, not here.
-     *
-     * Default false, which preserves the session-signing model: unlock once, sign
-     * for the session's lifetime with no further prompts.
-     *
-     * Two things worth knowing before turning this on:
-     *  - Multi-step flows prompt per leg. An ERC-20 approve + swap is two
-     *    prompts, not one.
-     *  - The policy is declared by the client at session open, so it hardens a
-     *    leaked session handle (useless without the authenticator) but a fully
-     *    compromised page could open a session without it. Making it
-     *    unbypassable requires the policy to come from the server per user or
-     *    per project; that is not implemented yet.
-     */
-    requireAssertionPerSignature?: boolean;
-    rpId?: string;
-    rpName?: string;
-    rpcUrls?: Record<string, string>;
-    teeUrl?: string;
-    /**
-     * Persist the live session (handle + JWT) in sessionStorage so a page RELOAD
-     * silently resumes it — no repeat passkey/sign-in. Survives reloads, cleared
-     * on tab close. Default true. Set false to require a fresh unlock on every
-     * page load (stricter, but the reload friction that motivated this returns).
-     */
-    persistSession?: boolean;
-    /**
-     * Offer to save a recovery-share file at signup. **Default false** since
-     * 2.7.4 — opt in explicitly with `true`.
-     *
-     * The offer existed because a new device could not otherwise get a device
-     * share. Server-assisted provisioning now covers that case: every wallet is
-     * enrolled at creation, un-enrolled wallets repair themselves on the next
-     * unlock, and a returning user is provisioned from their sign-in alone. For
-     * almost every app the dialog is now a password prompt during onboarding that
-     * buys nothing, so it is off unless asked for.
-     *
-     * Recovery files themselves are unchanged and still work — `rotateShares()`
-     * issues one on demand, and `promptForRecoveryFile` still accepts one during
-     * recovery. Turn this back on if you want users to hold an offline fallback
-     * that does not depend on Decane being reachable.
-     */
-    offerRecoveryAtSignup?: boolean;
-    /** Ask the user whether they want a recovery share and, if so, a password for it. */
-    onRecoveryShareOffer?: (addresses: {
-        evmAddress: string;
-        solanaAddress: string;
-    }) => Promise<{
-        wants: boolean;
-        password: string;
-        passwordHint?: string;
-    }>;
-    /** Hand the built file + suggested filename to the dApp, which owns the actual download. */
-    onRecoveryFileReady?: (file: RecoveryShareFile, filename: string) => Promise<void>;
-    /** Prompt for a recovery-share file (and its password) during Flow B. Return null to cancel. */
-    promptForRecoveryFile?: () => Promise<{
-        value: unknown;
-        getPassword: () => Promise<string | null>;
-    } | null>;
-    /**
-     * Every successful recovery/rotation invalidates the previous recovery
-     * file — this MUST prompt for a new password and block progress until the
-     * dApp confirms the user saved the new file (see MIGRATE_SSS_RECOVERY.md §10).
-     */
-    onRecoveryRotated?: (addresses: {
-        evmAddress: string;
-        solanaAddress: string;
-    }) => Promise<{
-        password: string;
-        passwordHint?: string;
-    }>;
-    /** Recovery stage callbacks, for dApp UI. */
-    onRecoveryProgress?: (event: RecoveryProgress) => void;
-    /**
-     * Rotate the whole share set whenever a NEW device recovers via passkey sync
-     * (Flow A) — the "every device holds a distinct share" model.
-     *
-     * Default false, which preserves the historical behaviour: every device
-     * synced to the same passkey caches the byte-identical wrapped share, so a
-     * device that is later lost keeps a share that stays valid until someone
-     * explicitly calls rotateShares(). There is no way to revoke one device
-     * without revoking all of them.
-     *
-     * With this on, joining a new device re-splits the master and issues that
-     * device its own share, which invalidates every other device's cached copy
-     * at the same instant. That is what makes per-device revocation possible,
-     * and it has three consequences worth accepting deliberately:
-     *
-     *  - **Other devices are logged out, not just the lost one.** Each surviving
-     *    device hits StaleDeviceShareError on its next unlock, clears its share,
-     *    and silently re-recovers through Flow A (one passkey prompt). Expected,
-     *    but it means a shared-family-device setup re-prompts more often.
-     *  - **The user's recovery FILE dies too.** Rotation issues a new recovery
-     *    share, so `onRecoveryRotated` MUST be configured to capture it —
-     *    enabling this without that callback throws at connect time rather than
-     *    stranding the user with a dead file.
-     *  - **Adding a device costs a TEE round trip.** Recovery is slower.
-     */
-    rotateOnNewDeviceRecovery?: boolean;
-}
-interface ConnectResult {
-    addresses: {
-        evm?: string;
-        solana?: string;
-        tron?: string;
-    };
-    isNewUser: boolean;
-    /** Present when the provider released a profile — see {@link AuthProfile}. */
-    profile?: AuthProfile;
-}
-/** A recorded on-chain transaction in the user's history. */
-interface TransactionRecord {
+interface UnifiedWalletAccount {
     id: string;
-    chain: string;
-    kind: string;
-    txHash: string | null;
-    to: string | null;
-    value: string | null;
-    status: 'submitted' | 'confirmed' | 'failed' | string;
-    metadata: Record<string, unknown> | null;
-    createdAt: string;
-    updatedAt?: string;
-}
-/** What the dApp passes to record a transaction it broadcast. */
-interface RecordTransactionInput {
-    chain: string;
-    txHash?: string;
-    to?: string;
-    value?: string;
-    kind?: string;
-    status?: string;
-    metadata?: Record<string, unknown>;
-}
-interface SignMessageRequest {
-    chain: Chain;
-    message: string | Uint8Array;
-}
-interface SendTransactionRequest {
-    chain: Chain;
-    to: string;
-    value?: bigint;
-    data?: string;
-    gasLimit?: bigint;
-    gasPrice?: bigint;
-}
-interface SignTypedDataRequest {
-    chain: Chain;
-    domain: Record<string, unknown>;
-    types: Record<string, unknown>;
-    message: Record<string, unknown>;
-    primaryType?: string;
+    name: string;
+    icon: string;
+    rdns?: string;
+    chainSupport: ChainSupport;
+    evmProvider?: EIP1193Provider;
+    solanaProvider?: StandardWallet;
+    tronProvider?: TronProvider;
+    bitcoinProvider?: BitcoinProvider;
 }
-type SdkEvent = 'connected' | 'disconnected' | 'session-expired' | 'session-started' | 'wallet-creating' | 'wallet-unlocking'
-/**
- * Emitted when this wallet could not be enrolled for server-assisted
- * recovery. Not fatal — the wallet works — but until it is enrolled the user
- * cannot get a device share from login alone, so a future new device will
- * need a passkey backup or a recovery file. The SDK retries automatically on
- * later unlocks; surface or report this if you want visibility rather than a
- * console line.
- */
- | 'enrolment-failed';
-interface DecaneConnect {
-    connect(): Promise<ConnectResult>;
-    connectWithGoogle(): Promise<ConnectResult>;
-    /**
-     * Sign in with a Google ID token the app already obtained — native Google
-     * Sign-In on mobile, or Google Identity Services on the web.
-     *
-     * Resolves to the SAME wallet as connectWithGoogle(): both end at the
-     * backend's Google identity, so a user who signs in on your website and then
-     * on your app lands on one wallet, not two.
-     */
-    connectWithGoogleToken(idToken: string): Promise<ConnectResult>;
-    /**
-     * Sign in with KingsChat.
-     *
-     * Opens KingsChat's consent screen in a popup, so this MUST be called
-     * directly from a click handler — a popup opened after an await is blocked by
-     * every browser. The resulting access token is exchanged server-side for a
-     * Decane session; it is never treated as one on its own.
-     */
-    connectWithKingsChat(): Promise<ConnectResult>;
-    /**
-     * Sign in with a KingsChat access token the app already holds — from
-     * kingschat-web-sdk, a native SDK, or any other flow. Use when you want to
-     * own the consent step yourself; connectWithKingsChat() is the turnkey path.
-     */
-    connectWithKingsChatToken(accessToken: string): Promise<ConnectResult>;
-    connectWithEmail(email: string): Promise<{
-        codeRequired: true;
-    }>;
-    /**
-     * Sign in with a JWT from your own auth system (Auth0, Clerk, Firebase,
-     * Cognito, your own backend — anything that publishes a JWKS endpoint).
-     *
-     * Configure the issuer and JWKS URL against your project in the dashboard;
-     * no client-side setup and no secret in your dApp. `providerId` is only
-     * required if the project has more than one provider configured.
-     *
-     * The user's wallet is derived from the configured identity claim, so the
-     * same token subject always resolves to the same wallet.
-     */
-    connectWithToken(token: string, opts?: {
-        providerId?: string;
-    }): Promise<ConnectResult>;
-    verifyEmailCode(email: string, code: string): Promise<ConnectResult>;
-    unlock(): Promise<void>;
-    isUnlocked(): boolean;
-    /**
-     * True when the user's identity is known from a previous visit but there is
-     * no live session, so unlock() cannot succeed and they must sign in again.
-     * Check this before offering an "Unlock" action.
-     *
-     * Note this can be true while canSignInWithPasskey() is also true — in which
-     * case "sign in again" costs one biometric prompt, not a full auth round
-     * trip. Prefer offering that over a Google/email button.
-     */
-    needsReconnect(): boolean;
-    /**
-     * True when a returning user can be signed straight back in with the passkey
-     * already on this device — no Google redirect, no email code. Requires a
-     * remembered identity plus a passkey-wrapped device share in local storage,
-     * so it is false on new devices and for PIN-only wallets.
-     */
-    canSignInWithPasskey(): Promise<boolean>;
-    /**
-     * Sign in using only the device passkey. connect() already tries this first
-     * when it's available, so call this directly only when driving the UI
-     * yourself. Throws NewDeviceError when this device isn't eligible.
-     */
-    signInWithPasskey(): Promise<ConnectResult>;
-    sessionExpiresAt(): number | null;
-    signMessage(req: SignMessageRequest): Promise<string>;
-    sendTransaction(req: SendTransactionRequest): Promise<string>;
-    /** Sign EIP-712 typed data (EVM only). Throws on a Solana chain. */
-    signTypedData(req: SignTypedDataRequest): Promise<string>;
-    /**
-     * A standard EIP-1193 Ethereum provider backed by this wallet — drop it into
-     * viem (`custom(provider)`), wagmi, or ethers (`BrowserProvider`). Signing
-     * goes through the TEE; reads are forwarded to the chain RPC. Memoized, so
-     * repeated calls return the same instance (safe for wagmi).
-     */
-    getEthereumProvider(opts?: {
-        chainId?: number;
-    }): Eip1193Provider;
-    /**
-     * Sign an EIP-7702 authorization, delegating this EOA to a smart-account
-     * implementation contract on `chainId`. Enables account-abstraction /
-     * sponsored-gas flows. Returns the full viem `SignedAuthorization` tuple, so
-     * it drops straight into a userOperation's `authorization` field or a type-4
-     * transaction's authorizationList. `address` and `contractAddress` are
-     * interchangeable (the latter matches Privy's/older viem's param name).
-     */
-    signAuthorization(req: {
-        chainId: number;
-        address?: string;
-        contractAddress?: string;
-        nonce: number;
-    }): Promise<SignedAuthorization>;
+type CAIP25Method = "wallet_requestPermissions" | "wallet_revokePermissions" | "wallet_getPermissions" | "wallet_sendTransaction" | "wallet_signMessage" | "wallet_signTypedData";
+interface ChainScope {
+    methods: CAIP25Method[];
+    accounts: string[];
+    events?: string[];
+}
+interface CAIP25SessionRequest {
+    requiredScopes: Partial<Record<string, ChainScope>>;
+    optionalScopes: Partial<Record<string, ChainScope>>;
+}
+interface CAIP25SessionResult {
+    sessionId: string;
+    grantedScopes: Partial<Record<string, ChainScope>>;
+}
+interface ActiveSession {
+    sessionId: string;
+    grantedScopes: Partial<Record<string, ChainScope>>;
+    walletId: string;
+    walletType: ChainType | "multi";
+    createdAt: number;
+}
+interface DecaneProvider {
+    request(args: {
+        method: string;
+        params?: unknown[];
+    }): Promise<unknown>;
+    on(event: string, handler: (...args: unknown[]) => void): void;
+    off(event: string, handler: (...args: unknown[]) => void): void;
+    readonly wallets: UnifiedWalletAccount[];
+    readonly evmWallets: UnifiedWalletAccount[];
+    readonly solanaWallets: UnifiedWalletAccount[];
+    readonly multiChainWallets: UnifiedWalletAccount[];
+    readonly tronWallets: UnifiedWalletAccount[];
+    readonly bitcoinWallets: UnifiedWalletAccount[];
+    connect(wallet: UnifiedWalletAccount, preferredChain?: ChainType): Promise<void>;
+    disconnect(): Promise<void>;
+    addChain(chain: ChainDescriptor): void;
+    removeChain(chainId: string): void;
+    getChain(chainId: string): ChainDescriptor | undefined;
+    readonly chains: ChainDescriptor[];
+    readonly connectedWallet: UnifiedWalletAccount | null;
+    readonly activeSession: ActiveSession | null;
+    readonly activeChain: string | null;
+}
+type ConnectMode = "all" | "social" | "wallets" | "evm" | "solana" | "tron" | "evm+social" | "solana+social" | "tron+social" | "evm+tron" | "evm+tron+social";
+interface SocialConfig {
+    apiKey: string;
+    authMethods?: ("google" | "email" | "phone" | "kingschat")[];
     /**
-     * The current session's access token (the Decane JWT). Use it to authenticate
-     * the user to your own backend (e.g. a sponsored-bundler proxy); verify it
-     * server-side against backend.decane.app/.well-known/jwks.json. Null with no
-     * live session.
+     * Scopes requested from KingsChat. Defaults to `['send_chat_message']`, which
+     * is what KingsChat's own SDK asks for and is enough to establish identity.
      */
-    getAccessToken(): string | null;
-    signSolanaTransaction(tx: Uint8Array): Promise<Uint8Array>;
+    kingsChatScopes?: string[];
+    promptPin?: () => Promise<string>;
+    apiBaseUrl?: string;
+    chains?: string[];
+    rpcUrls?: Record<string, string>;
     /**
-     * Sign a Tron transaction. Pass the transaction's `raw_data_hex` (the value
-     * TronWeb puts on a built transaction). The enclave computes the txID
-     * (sha256(raw_data)) and signs it with the same secp256k1 key as the EVM
-     * wallet; returns the 65-byte recoverable signature as 0x-hex. Attach it to
-     * the transaction's `signature` array and broadcast via TronWeb / a full node.
+     * Show the built-in full-screen status overlay while a wallet is being
+     * created or unlocked. Default **true**.
+     *
+     * The overlay exists because those flows can take several seconds and often
+     * run right after a Google redirect, when no modal of yours is mounted — so
+     * without it the page can look frozen. It is rendered by `<DecaneKit>` itself,
+     * as a portal, and injects its own theme tokens.
+     *
+     * Set false to suppress it and render your own. Everything it displays is
+     * already available to you: `useSocialAuth()` exposes `phase`
+     * (`"creating" | "unlocking" | null`) plus the `isCreatingWallet` /
+     * `isUnlockingWallet` booleans, and the client emits `wallet-creating` and
+     * `wallet-unlocking` events. If you suppress it, show something of your own —
+     * a silent multi-second pause reads as a broken page.
      */
-    signTronTransaction(rawDataHex: string): Promise<string>;
+    showStatusOverlay?: boolean;
     /**
-     * Record a transaction this wallet broadcast, so it appears in the user's
-     * history (and the developer dashboard). EVM `sendTransaction` records itself
-     * automatically; call this for Solana/Tron transactions your dApp broadcasts,
-     * or to attach a `confirmed`/`failed` status update to an existing hash.
+     * Offer to save a recovery-share file at signup. **Default false** since
+     * 2.7.4 — opt in explicitly with `true`.
+     *
+     * Server-assisted provisioning now covers the new-device case (wallets are
+     * enrolled at creation and repair themselves on unlock), so for most apps
+     * this dialog is a password prompt during onboarding that buys nothing. Turn
+     * it on if you want users to hold an offline fallback that works when Decane
+     * is unreachable.
      */
-    recordTransaction(tx: RecordTransactionInput): Promise<TransactionRecord>;
-    /** The user's transaction history, most recent first. Requires a live session. */
-    getTransactionHistory(limit?: number): Promise<TransactionRecord[]>;
-    disconnect(): Promise<void>;
-    getAddresses(): {
-        evm?: string;
-        solana?: string;
-        tron?: string;
-    } | null;
+    offerRecoveryAtSignup?: boolean;
+    /** Ask the user whether they want a recovery share and, if so, a password for it. */
+    onRecoveryShareOffer?: (addresses: {
+        evmAddress: string;
+        solanaAddress: string;
+    }) => Promise<{
+        wants: boolean;
+        password: string;
+        passwordHint?: string;
+    }>;
+    /** Hand the built file + suggested filename to the app, which owns the download. */
+    onRecoveryFileReady?: (file: RecoveryShareFile, filename: string) => Promise<void>;
     /**
-     * Native-token balance for a chain (defaults to the first configured EVM
-     * chain, else Solana). Read-only public data — works even while the wallet
-     * is locked. Returns raw (wei/lamports), a human `formatted` string, the
-     * native `symbol`, and `decimals`.
+     * Prompt for a recovery-share file (and its password) during recovery.
+     * Return null to cancel. **Without this, a user who needs the recovery-file
+     * path fails immediately with NewDeviceError** — there is nowhere to ask them
+     * for the file.
      */
-    getBalance(chain?: string): Promise<BalanceResult>;
-    /** Native balances across every configured chain the wallet has an address for. */
-    getBalances(): Promise<Array<{
-        chain: string;
-        balance: BalanceResult | null;
-    }>>;
+    promptForRecoveryFile?: () => Promise<{
+        value: unknown;
+        getPassword: () => Promise<string | null>;
+    } | null>;
     /**
-     * Voluntary share rotation — after a suspected device compromise, or just
-     * to invalidate an old recovery file. Requires a fresh WebAuthn assertion.
-     * Returns the new recovery-share file (the caller still owns delivering it
-     * to the user — this does not download anything itself).
+     * Every successful recovery/rotation invalidates the previous recovery file,
+     * so this must prompt for a new password and capture the replacement.
+     * Required before recovery can run at all.
      */
-    rotateShares(opts: {
+    onRecoveryRotated?: (addresses: {
+        evmAddress: string;
+        solanaAddress: string;
+    }) => Promise<{
         password: string;
         passwordHint?: string;
-    }): Promise<RecoveryShareFile>;
+    }>;
+    /** Recovery stage callbacks, for your own progress UI. */
+    onRecoveryProgress?: (event: RecoveryProgress) => void;
     /**
-     * The two-share bearer portable backup (device + recovery). This file plus
-     * its password gives complete control of the wallet — see the mandatory
-     * warning-screen requirements in MIGRATE_SSS_RECOVERY.md §10. Requires a
-     * fresh WebAuthn assertion and rotates the share set on every export.
+     * Require a fresh WebAuthn assertion for every signature rather than letting
+     * an unlocked session sign freely until it expires. Enforced inside the TEE.
+     *
+     * Does not change the session lifetime — the session stays warm (no
+     * re-attestation, no re-auth) and authority is re-proven per signature
+     * instead. Default false. Needs a passkey; PIN-only wallets have no
+     * authenticator to assert with. See SocialConfig's counterpart in
+     * social/types.ts for the full caveats.
      */
-    exportPortableBackup(opts: {
-        password: string;
-        passwordHint?: string;
-    }): Promise<PortableBackup>;
-    /** Whether the user has ever saved a recovery-share file (UX flag only — Decane never stores the share). */
-    hasRecoveryShare(): Promise<boolean>;
-    /** True at most once per account: no recovery share saved, never nagged, wallet holds value. */
-    shouldPromptRecovery(): Promise<boolean>;
-    /** Call regardless of the user's answer — the recovery nag fires once, ever. */
-    dismissRecoveryPrompt(): Promise<void>;
-    /** Whether a wrapped-share backup exists on the server. */
-    hasBackup(): Promise<boolean>;
-    /** Delete the server-side backup. Disables Flow A recovery. */
-    deleteBackup(): Promise<void>;
-    on(event: SdkEvent, handler: (...args: unknown[]) => void): void;
-    off(event: SdkEvent, handler: (...args: unknown[]) => void): void;
+    requireAssertionPerSignature?: boolean;
+    /**
+     * Sign in with a token from your own auth system (Auth0, Clerk, Firebase,
+     * Cognito, or your own backend) — surfaced as a button in the built-in
+     * WalletSelector / SocialWalletModal UI, alongside Google and email.
+     * getToken() runs when the user clicks the button; wire it to however you
+     * already obtain a token from your auth system (e.g. after your own login
+     * flow completes). Configure the issuer and JWKS URL for this token
+     * against your project in the dashboard first. `providerId` is only
+     * needed when the project has more than one custom provider configured.
+     */
+    customAuth?: {
+        label: string;
+        providerId?: string;
+        getToken: () => Promise<string>;
+    };
 }
-interface WrappedShareMeta {
-    unlockMethod: 'passkey' | 'pin';
-    credentialId?: string;
-    prfSalt?: string;
-    pinSalt?: string;
-    pinIterations?: number;
+interface DecaneConfig {
+    appId: string;
+    chains?: ChainDescriptor[];
+    supportedChainIds?: string[];
+    networks?: "evm" | "solana" | "tron" | "bitcoin" | "all";
+    defaultChain?: string;
+    theme?: "light" | "dark" | "auto";
+    mode?: ConnectMode;
+    social?: SocialConfig;
 }
-/**
- * Who the user is, as the identity provider just described them.
- *
- * Passed through from the provider at sign-in and never stored by Decane — the
- * backend keeps only an HMAC and a masked identifier, so there is no profile to
- * look up later. Cache what you need at sign-in if you want to show a name
- * after a page reload.
- *
- * Every field is optional because providers differ in what they release, and a
- * user can withhold most of it. Email sign-in returns an empty profile.
- */
-interface AuthProfile {
-    name?: string;
-    email?: string;
-    picture?: string;
+interface EIP1193Provider {
+    request(args: {
+        method: string;
+        params?: unknown[];
+    }): Promise<unknown>;
+    on(event: string, handler: (...args: unknown[]) => void): void;
+    removeListener(event: string, handler: (...args: unknown[]) => void): void;
 }
-interface AuthResult {
-    jwt: string;
-    isNewUser: boolean;
-    hasShare: boolean;
-    userId: string;
-    profile?: AuthProfile;
+interface StandardWallet {
+    name: string;
+    icon: string;
+    features: Record<string, unknown>;
+    accounts: StandardWalletAccount[];
+}
+interface StandardWalletAccount {
+    address: string;
+    publicKey: Uint8Array;
+    chains: string[];
+}
+interface TronProvider {
+    request(args: {
+        method: string;
+        params?: unknown[] | Record<string, unknown>;
+    }): Promise<unknown>;
+    on(event: string, handler: (...args: unknown[]) => void): void;
+    removeListener(event: string, handler: (...args: unknown[]) => void): void;
+}
+interface BitcoinProvider {
+    requestAccounts(): Promise<string[] | Array<{
+        address: string;
+    }>>;
+    getAccounts?(): Promise<string[] | Array<{
+        address: string;
+    }>>;
+    signMessage(message: string, ...args: unknown[]): Promise<string>;
+    sendBitcoin?(toAddress: string, satoshis: number, options?: unknown): Promise<string>;
+    send?(params: unknown): Promise<string>;
+    signPsbt?(psbtHex: string, options?: unknown): Promise<string>;
+    on?(event: string, handler: (...args: unknown[]) => void): void;
 }
 
+declare function createDecane(config: DecaneConfig): DecaneProvider;
+
 declare function createDecaneConnect(config: DecaneConnectConfig): Promise<DecaneConnect>;
 
 /**
@@ -1006,13 +1071,17 @@ interface WalletSelectorProps {
     theme?: "light" | "dark" | "auto";
     networks?: "evm" | "solana" | "tron" | "bitcoin" | "all";
     mode?: ConnectMode;
-    socialAuthMethods?: ("google" | "email" | "kingschat")[];
+    socialAuthMethods?: ("google" | "email" | "phone" | "kingschat")[];
     onGoogleSignIn?: () => Promise<void>;
     onKingsChatSignIn?: () => Promise<void>;
     onEmailStart?: (email: string) => Promise<{
         codeRequired: true;
     }>;
     onEmailVerify?: (email: string, code: string) => Promise<void>;
+    onPhoneStart?: (phone: string) => Promise<{
+        codeRequired: true;
+    }>;
+    onPhoneVerify?: (phone: string, code: string) => Promise<void>;
     /** Button text for the developer's own auth system, e.g. "Continue with Acme Inc". Omitted entirely when not configured. */
     customAuthLabel?: string;
     onCustomAuthSignIn?: () => Promise<void>;
@@ -1022,7 +1091,7 @@ interface WalletSelectorProps {
     passkeyAddress?: string | null;
     onPasskeySignIn?: () => Promise<unknown>;
 }
-declare function WalletSelector({ provider, open, onClose, onConnect, theme, networks, mode, socialAuthMethods, onGoogleSignIn, onKingsChatSignIn, onEmailStart, onEmailVerify, customAuthLabel, onCustomAuthSignIn, canUsePasskey, passkeyAddress, onPasskeySignIn, }: WalletSelectorProps): React.ReactPortal | null;
+declare function WalletSelector({ provider, open, onClose, onConnect, theme, networks, mode, socialAuthMethods, onGoogleSignIn, onKingsChatSignIn, onEmailStart, onEmailVerify, onPhoneStart, onPhoneVerify, customAuthLabel, onCustomAuthSignIn, canUsePasskey, passkeyAddress, onPasskeySignIn, }: WalletSelectorProps): React.ReactPortal | null;
 
 type Theme = "light" | "dark" | "auto";
 interface SocialAuthState {
@@ -1085,7 +1154,11 @@ interface SocialWalletModalProps {
         codeRequired: true;
     }>;
     onEmailVerify: (email: string, code: string) => Promise<void>;
-    authMethods?: Array<"google" | "email" | "kingschat">;
+    onPhoneStart?: (phone: string) => Promise<{
+        codeRequired: true;
+    }>;
+    onPhoneVerify?: (phone: string, code: string) => Promise<void>;
+    authMethods?: Array<"google" | "email" | "phone" | "kingschat">;
     customAuthLabel?: string;
     onCustomAuthSignIn?: () => Promise<void>;
     canUsePasskey?: boolean;
@@ -1102,7 +1175,7 @@ interface SocialWalletModalProps {
     rpcUrls?: Record<string, string>;
     chains?: string[];
 }
-declare function SocialWalletModal({ open, onClose, theme, socialAuth, onUnlock, onDisconnect, onGoogleSignIn, onKingsChatSignIn, onEmailStart, onEmailVerify, authMethods, customAuthLabel, onCustomAuthSignIn, canUsePasskey, passkeyAddress, onPasskeySignIn, onRotateShares, onExportPortableBackup, rpcUrls, chains, }: SocialWalletModalProps): React.ReactPortal | null;
+declare function SocialWalletModal({ open, onClose, theme, socialAuth, onUnlock, onDisconnect, onGoogleSignIn, onKingsChatSignIn, onEmailStart, onEmailVerify, onPhoneStart, onPhoneVerify, authMethods, customAuthLabel, onCustomAuthSignIn, canUsePasskey, passkeyAddress, onPasskeySignIn, onRotateShares, onExportPortableBackup, rpcUrls, chains, }: SocialWalletModalProps): React.ReactPortal | null;
 
 declare function DecaneMark({ size, muted }: {
     size?: number;
@@ -1133,6 +1206,7 @@ declare function useSocialAuth(): {
     needsReconnect: boolean;
     googleLoading: boolean;
     emailLoading: boolean;
+    phoneLoading: boolean;
     tokenLoading: boolean;
     customLoading: boolean;
     customAuthLabel: string | undefined;
@@ -1143,6 +1217,10 @@ declare function useSocialAuth(): {
         codeRequired: true;
     }>;
     confirmEmailCode: (email: string, code: string) => Promise<void>;
+    sendPhoneCode: (phone: string) => Promise<{
+        codeRequired: true;
+    }>;
+    confirmPhoneCode: (phone: string, code: string) => Promise<void>;
     signInWithToken: (token: string, opts?: {
         providerId?: string;
     }) => Promise<void>;