@cavos/kit 0.0.1 → 0.0.2

package/dist/Cavos-C2KHZxxu.d.ts

@@ -0,0 +1,590 @@
+import { Account } from 'starknet';
+import { PublicKey, Connection, TransactionInstruction, Keypair } from '@solana/web3.js';
+
+/**
+ * Identity for a Cavos wallet. Login (email / social / OTP) only ever produces a
+ * stable `userId`; that's all the wallet needs to derive its address. Auth never
+ * touches signing — the device key does that, silently.
+ *
+ * Privy-style UX: the user "logs in" and the wallet is provisioned behind the
+ * scenes (device key + auto-deployed smart account). The app never handles keys.
+ */
+interface Identity {
+    /** Stable, backend-managed user identifier. */
+    userId: string;
+    /** Optional metadata (email, provider) for display only. */
+    email?: string;
+    provider?: "google" | "apple" | "email" | "otp" | string;
+}
+/**
+ * Authenticates a user and returns their stable identity. Implementations:
+ * - `CavosAuth` (hosted, mirrors `@cavos/react`: Google/Apple/email/OTP via the
+ *   Cavos backend) — the default, Privy-like experience.
+ * - any custom provider (the app already authenticated the user elsewhere).
+ */
+interface AuthProvider {
+    authenticate(): Promise<Identity>;
+}
+/** Trivial provider when the app already has the user's stable id. */
+declare class StaticIdentity implements AuthProvider {
+    private readonly identity;
+    constructor(identity: Identity);
+    authenticate(): Promise<Identity>;
+}
+
+/** secp256r1 (P-256) public key of a device signer. */
+interface DevicePublicKey {
+    x: bigint;
+    y: bigint;
+}
+/** A raw secp256r1 signature over `sha256(tx_hash)`. */
+interface DeviceSignature {
+    r: bigint;
+    s: bigint;
+    /** Recovery parity of the emitted (r, s); the contract normalizes high-s. */
+    yParity: boolean;
+}
+/**
+ * A silent, device-bound signer. The private key is a secp256r1 key generated
+ * and kept on the device (non-extractable WebCrypto key on web, Secure Enclave
+ * on native) — it never leaves the device and signs WITHOUT any user-visible
+ * prompt (no passkey, no biometrics). OAuth / email only derive identity; they
+ * are never involved in signing.
+ *
+ * `WebCryptoSigner` is the browser implementation. React Native and other
+ * platforms provide their own implementation of this interface.
+ */
+interface DeviceSigner {
+    /** secp256r1 public key of this device signer. */
+    getPublicKey(): Promise<DevicePublicKey>;
+    /**
+     * Sign a transaction hash silently. `txHash` is the 32-byte big-endian tx
+     * hash; the signer signs `sha256(txHash)` and returns the raw (r, s, parity).
+     */
+    sign(txHash: Uint8Array): Promise<DeviceSignature>;
+}
+
+/**
+ * Off-chain map of `user_id -> wallet`. Because the account address is
+ * `f(identity, first_device_pubkey)` (unforgeable, secure), it is NOT derivable
+ * from the identity alone on a new device. The backend is the source of truth
+ * for "does this user already have a wallet?" — enabling multi-device:
+ *
+ *   - First device, unknown user  -> deploy a new wallet, then `register`.
+ *   - Same user, new device        -> `lookup` returns the existing wallet; the
+ *                                      new device is added as a signer (recovery
+ *                                      approval), NOT a new wallet.
+ *
+ * The backend implements this (it already manages the user<->address binding).
+ */
+interface WalletRegistry {
+    /** The user's existing wallet, or null if they don't have one yet. */
+    lookup(userId: string): Promise<RegisteredWallet | null>;
+    /** Record a freshly deployed wallet for the user (first device). */
+    register(params: {
+        userId: string;
+        address: string;
+        initialSigner: DevicePublicKey;
+    }): Promise<void>;
+    /** Note an additional device signer for the user's wallet (after approval). */
+    addDevice?(params: {
+        userId: string;
+        address: string;
+        signer: DevicePublicKey;
+    }): Promise<void>;
+}
+interface RegisteredWallet {
+    address: string;
+    /** Public keys of the devices registered on this wallet (if tracked). */
+    devices?: DevicePublicKey[];
+}
+/** Simple in-memory registry for demos / tests. */
+declare class InMemoryWalletRegistry implements WalletRegistry {
+    private wallets;
+    lookup(userId: string): Promise<RegisteredWallet | null>;
+    register(params: {
+        userId: string;
+        address: string;
+        initialSigner: DevicePublicKey;
+    }): Promise<void>;
+    addDevice(params: {
+        userId: string;
+        address: string;
+        signer: DevicePublicKey;
+    }): Promise<void>;
+}
+
+/** An account meta candidate for a CPI instruction inside `execute`. Mirrors the
+ *  on-chain `AccountMetaCandidate` (Borsh). */
+interface InstructionAccount {
+    pubkey: string;
+    isSigner: boolean;
+    isWritable: boolean;
+}
+/** A CPI instruction the device key authorizes via `execute`. Mirrors the
+ *  on-chain `InstructionData` (Borsh). Serialized canonically and hashed before
+ *  signing, so a signature binds exactly this instruction set. */
+interface InstructionData {
+    programId: string;
+    accounts: InstructionAccount[];
+    data: Uint8Array;
+}
+interface SolanaAdapterOptions {
+    /** Cavos device-account program id (defaults to the deployed one). */
+    programId?: string;
+    /** RPC connection for reads (`isAuthorizedSigner`) and nonce fetch. */
+    connection?: Connection;
+    /** Device signer used to authorize guarded actions. */
+    signer?: DeviceSigner;
+}
+/**
+ * Solana adapter for the Cavos device-signer account. Unlike Starknet (where the
+ * account contract verifies the P-256 signature in `__validate__`), Solana
+ * verifies it natively via the secp256r1 precompile, so every guarded action is
+ * a two-instruction bundle: `[secp256r1 precompile ix, program ix]`. This adapter
+ * derives the account PDA, builds those bundles, and reuses the same
+ * `DeviceSigner` (P-256 / WebCrypto) as every other chain.
+ */
+declare class SolanaAdapter {
+    private readonly opts;
+    readonly chain: "solana";
+    readonly programId: PublicKey;
+    constructor(opts?: SolanaAdapterOptions);
+    /** Deterministic account address: PDA of [seed, address_seed, initial_signer_x]. */
+    computeAddress(addressSeed: Uint8Array, initialSigner: DevicePublicKey): string;
+    private pda;
+    /** `initialize` instruction creating the account with its first device signer. */
+    buildInitialize(addressSeed: Uint8Array, payer: string, initialSigner: DevicePublicKey): TransactionInstruction;
+    /** `[precompile, add_signer]` bundle, authorized by an existing device signer. */
+    buildAddSigner(account: string, newSigner: DevicePublicKey): Promise<TransactionInstruction[]>;
+    /** `[precompile, remove_signer]` bundle, authorized by an existing device signer. */
+    buildRemoveSigner(account: string, signer: DevicePublicKey): Promise<TransactionInstruction[]>;
+    /** `[precompile, execute_transfer]` bundle moving lamports out of the account. */
+    buildExecuteTransfer(account: string, destination: string, amount: bigint): Promise<TransactionInstruction[]>;
+    /**
+     * `[precompile, execute]` bundle running arbitrary CPI instructions with the
+     * account PDA as signer. The device key signs over
+     * `DOMAIN_EXECUTE || account || sha256(canonical(instructions)) || nonce`, so
+     * the signature commits to the EXACT instruction set the program will invoke —
+     * no account/data substitution is possible after signing.
+     *
+     * The instructions' accounts are passed to the program via `remaining_accounts`
+     * (flattened, in order); the program enforces an exact, ordered mapping.
+     */
+    buildExecute(account: string, instructions: InstructionData[]): Promise<TransactionInstruction[]>;
+    /** Read whether `signer` is currently an authorized signer of `account`. */
+    isAuthorizedSigner(account: string, signer: DevicePublicKey): Promise<boolean>;
+    private guardedKeys;
+    /** Sign `message` with the device key and build the matching precompile ix. */
+    private signToPrecompile;
+    private fetchNonce;
+    private fetchSigners;
+    private requireConnection;
+}
+/** Compressed SEC1 P-256 pubkey (33 bytes) from {x, y}. */
+declare function compressedPubkey(pk: DevicePublicKey): Uint8Array;
+/** Encode (r, s) as raw 64-byte r‖s, normalized to low-S (precompile requires it). */
+declare function encodeLowSSignature(r: bigint, s: bigint): Uint8Array;
+/** Build the native secp256r1 precompile instruction (single self-contained sig). */
+declare function buildSecp256r1Instruction(compressed: Uint8Array, signature: Uint8Array, message: Uint8Array): TransactionInstruction;
+/** Anchor instruction discriminator = sha256("global:<name>")[..8]. */
+declare function anchorDiscriminator(name: string): Buffer;
+/** Serialize the full instruction set — the bytes `hash_instructions` hashes. */
+declare function serializeInstructions(instructions: InstructionData[]): Buffer;
+
+/** Cavos device-account program + Solana primitives. */
+/** Deployed `cavos-device-account` program id (see account-contracts/solana). */
+declare const DEVICE_ACCOUNT_PROGRAM_ID = "FHnoYNfYAmFrwt18gcBGG7G1S5q3RAbCBvrV2D29izNJ";
+/** Native secp256r1 signature-verify precompile (SIMD-0075). */
+declare const SECP256R1_PROGRAM_ID = "Secp256r1SigVerify1111111111111111111111111";
+declare const SOLANA_NETWORKS: {
+    readonly "solana-devnet": "https://api.devnet.solana.com";
+    readonly "solana-mainnet": "https://api.mainnet-beta.solana.com";
+    readonly "solana-localnet": "http://127.0.0.1:8899";
+};
+type SolanaNetwork = keyof typeof SOLANA_NETWORKS;
+
+interface SolanaRelayerOptions {
+    /** Base URL of the Cavos backend exposing /api/solana/relay. */
+    baseUrl: string;
+    /** Cavos App ID (authorizes the sponsored request). */
+    appId: string;
+    network: SolanaNetwork;
+    /** Connection used only to fetch a recent blockhash before serializing. */
+    connection: Connection;
+}
+/**
+ * Client for the Cavos Solana sponsoring relayer. Lets the SDK submit
+ * device-account transactions WITHOUT the integrator holding a fee-payer
+ * keypair: the relayer co-signs as fee payer and pays the fee/rent. The relayer
+ * only pays — the device signature inside the instructions (verified by the
+ * secp256r1 precompile) is what authorizes the action, and it does not bind the
+ * fee payer, so sponsorship needs no re-signing.
+ */
+declare class SolanaRelayer {
+    private readonly opts;
+    private feePayer?;
+    constructor(opts: SolanaRelayerOptions);
+    /** The relayer's fee-payer pubkey (fetched + cached from the backend). */
+    getFeePayer(): Promise<PublicKey>;
+    /**
+     * Build a tx with the relayer as fee payer, serialize it unsigned, and POST it
+     * to the relayer to co-sign + submit. Returns the confirmed signature.
+     */
+    send(instructions: TransactionInstruction[]): Promise<string>;
+}
+
+interface ConnectSolanaOptions {
+    network: SolanaNetwork;
+    /** Authenticated user (pass `identity` directly, or an `auth` provider). */
+    auth?: AuthProvider;
+    identity?: Identity;
+    appSalt: string;
+    appId?: string;
+    backendUrl?: string;
+    registry?: WalletRegistry;
+    /** RPC override (else the network default). */
+    rpcUrl?: string;
+    /** Cavos device-account program id override. */
+    programId?: string;
+    /** Override the device signer factory (native / tests); default WebCrypto. */
+    createSigner?: (keyId: string) => Promise<DeviceSigner>;
+    /**
+     * Gasless sponsorship via the Cavos relayer. When set (or when `appId` +
+     * `backendUrl` are given), transactions are co-signed + paid by the Cavos
+     * relayer, so the integrator needs NO fee-payer keypair — the user's silent
+     * device key (which holds no SOL) gets a seedless, gasless experience.
+     */
+    relayer?: SolanaRelayer;
+    /**
+     * Self-funded fallback: a fee-payer keypair the integrator funds. Used only
+     * when no `relayer` is configured (tests / advanced). Sponsored relaying is
+     * the default path when `appId` is provided.
+     */
+    feePayer?: Keypair;
+}
+type ConnectStatus$1 = "ready" | "needs-device-approval";
+/**
+ * Options for recovering a Solana account after losing every device signer.
+ * Mirrors `RecoveryOptions` (Starknet), adapted to the Solana path: the backup
+ * key signs the `add_signer` bundle via the secp256r1 precompile and the Cavos
+ * relayer sponsors it (no fee-payer keypair needed).
+ */
+interface RecoverSolanaOptions {
+    /** The recovery code the user stored when they ran setupRecovery. */
+    code: string;
+    /** Authenticated identity (same user who owns the account). */
+    identity: Identity;
+    /** Solana network the account lives on. */
+    network: SolanaNetwork;
+    appSalt: string;
+    appId?: string;
+    backendUrl?: string;
+    registry?: WalletRegistry;
+    /** RPC override (else the network default). */
+    rpcUrl?: string;
+    /** Cavos device-account program id override. */
+    programId?: string;
+    /** Override the new device's signer (native / tests); default WebCrypto. */
+    createSigner?: (keyId: string) => Promise<DeviceSigner>;
+    /** Gasless sponsorship via the Cavos relayer (defaults to hosted when appId set). */
+    relayer?: SolanaRelayer;
+    /** Self-funded fallback when no relayer is configured (tests / advanced). */
+    feePayer?: Keypair;
+}
+/**
+ * High-level Solana entry — the Solana analogue of `Cavos.connect`. One call
+ * derives the deterministic device-bound account, deploys it (PDA `initialize`)
+ * if needed, registers it for cross-device recognition, and returns a ready
+ * handle whose silent P-256 device key authorizes every action through the
+ * native secp256r1 precompile.
+ *
+ *   const cavos = await CavosSolana.connect({ network: "solana-devnet", identity, appSalt, feePayer });
+ *   if (cavos.status === "ready") await cavos.execute(amount, dest);
+ *
+ * Gasless by default: when an `appId` is provided the Cavos relayer co-signs +
+ * pays (no fee-payer keypair needed). `feePayer` is the self-funded fallback.
+ */
+declare class CavosSolana {
+    readonly identity: Identity;
+    readonly address: string;
+    readonly status: ConnectStatus$1;
+    readonly connection: Connection;
+    private readonly adapter;
+    private readonly devicePubkey;
+    private readonly relayer?;
+    private readonly feePayer?;
+    /** Discriminant for the `CavosWallet` union — narrows `execute()` per chain. */
+    readonly chain: "solana";
+    private constructor();
+    get publicKey(): DevicePublicKey;
+    static connect(opts: ConnectSolanaOptions): Promise<CavosSolana>;
+    /** Authorize an additional device signer (device-signed via precompile). */
+    addSigner(pubkey: DevicePublicKey): Promise<string>;
+    /** Move `amount` lamports out of the account to `destination` (device-signed). */
+    execute(amount: bigint, destination: string): Promise<string>;
+    /**
+     * Run arbitrary CPI `instructions` with the account PDA as signer (device-
+     * signed). The signature commits to sha256 of the canonical Borsh
+     * serialization of the instructions, so it binds exactly the operations the
+     * program will invoke. Unlocks SPL transfers, swaps, staking, etc.
+     *
+     * What the relayer will sponsor is constrained by the app's Solana program
+     * allowlist (configured in the dashboard) — programs outside the allowlist are
+     * rejected before co-signing.
+     */
+    executeInstructions(instructions: InstructionData[]): Promise<string>;
+    /**
+     * Register the backup signer derived from `code` as an authorized signer of this
+     * account (device-signed via precompile). Idempotent: returns without a tx if
+     * the backup signer is already registered. The code never leaves the device —
+     * only the derived public key travels on-chain.
+     *
+     * Self-custodial: anyone who can re-derive the backup key from the code (i.e.
+     * the rightful owner) can later recover the account with `CavosSolana.recover`.
+     * Run this once, on a registered device, and have the user store the code.
+     */
+    setupRecovery(code: string): Promise<string | undefined>;
+    /**
+     * Recover an account after losing every device signer. Derives the backup key
+     * from `code`, uses it (not the new device key) to sign an `add_signer` for the
+     * new device, and returns a ready CavosSolana bound to the new device. The
+     * account address is unchanged.
+     *
+     * Self-custodial: only someone holding the code (i.e. the rightful owner) can
+     * re-derive the backup key. The backend never sees the code.
+     *
+     * This mirrors `Cavos.recover` (Starknet): the backup key is just another
+     * authorized signer, so recovery is an `add_signer(newDevice)` bundle signed by
+     * the backup key. The on-chain program needs no recovery-specific entrypoint.
+     */
+    static recover(opts: RecoverSolanaOptions): Promise<CavosSolana>;
+    private send;
+}
+
+/** A chain-native contract call (Starknet `Call`-shaped; generic for portability). */
+interface ChainCall {
+    contractAddress: string;
+    entrypoint: string;
+    calldata: string[];
+}
+interface ComputeAddressParams {
+    addressSeed: bigint;
+    /** First device signer — part of the address, making it unforgeable. */
+    initialSigner: DevicePublicKey;
+    /** Defaults to `addressSeed` when omitted. */
+    salt?: bigint;
+}
+/**
+ * Per-chain implementation surface. Phase 1 ships only Starknet, but the kit is
+ * designed so Stellar and Solana adapters drop in behind the same interface.
+ */
+interface ChainAdapter {
+    readonly chain: "starknet" | "stellar" | "solana";
+    /** Deterministic address from identity seed + the first device signer. */
+    computeAddress(params: ComputeAddressParams): string;
+    /** Call(s) to deploy the account with its first device signer (UDC). */
+    buildDeploy(params: ComputeAddressParams): ChainCall[];
+    buildAddSigner(accountAddress: string, signer: DevicePublicKey): ChainCall;
+    buildRemoveSigner(accountAddress: string, signer: DevicePublicKey): ChainCall;
+    /** Read whether a pubkey is a currently-authorized signer of the account. */
+    isAuthorizedSigner(accountAddress: string, signer: DevicePublicKey): Promise<boolean>;
+    /**
+     * Compute the signature payload for an outgoing transaction: given the chain's
+     * tx hash, obtain a device assertion and serialize it to the chain's expected
+     * signature encoding.
+     */
+    buildSignature(txHash: bigint): Promise<string[]>;
+}
+
+/**
+ * Multi-device / recovery flow (roadmap §1.2). A new device requests addition;
+ * the backend emails an approval prompt styled as a login request; the user
+ * approves on an ALREADY-registered device, which signs `add_signer` for the
+ * new pubkey. There is no legacy JWT path — recovery is purely device-signer
+ * based.
+ *
+ * The backend lives outside this repo; this is the client contract the kit
+ * speaks to. Provide an implementation (HTTP, etc.) when wiring an app.
+ */
+interface RecoveryClient {
+    /**
+     * Step 1 (new device): request that this pubkey be added to the user's
+     * account. Triggers the approval email. Returns a request id to poll.
+     */
+    requestDeviceAddition(params: {
+        userId: string;
+        accountAddress: string;
+        newSigner: DevicePublicKey;
+        /** Owner email to send the approval link to (the SDK has it from login). */
+        email?: string;
+        /** Optional device label (browser/UA) shown in the approval email. */
+        deviceLabel?: string;
+    }): Promise<{
+        requestId: string;
+    }>;
+    /**
+     * Step 3-4 (existing device): fetch a pending addition request so the
+     * registered device can approve it by signing `add_signer`.
+     */
+    getPendingRequest(requestId: string): Promise<PendingDeviceRequest | null>;
+    /** Mark a request approved after the `add_signer` tx is submitted. */
+    confirmDeviceAddition(params: {
+        requestId: string;
+        txHash: string;
+    }): Promise<void>;
+}
+interface PendingDeviceRequest {
+    requestId: string;
+    appId?: string;
+    userId: string;
+    accountAddress: string;
+    newSigner: DevicePublicKey;
+    createdAt: string;
+    status: "pending" | "approved" | "expired";
+}
+
+/** The chains the unified `Cavos.connect` can target. */
+type Chain = "starknet" | "solana";
+/**
+ * Environment selector. `Cavos.connect` resolves it to the chain's concrete
+ * network: starknet → sepolia/mainnet, solana → solana-devnet/solana-mainnet.
+ */
+type NetworkEnv = "mainnet" | "testnet";
+/** A connected wallet: discriminated by `chain`, so `execute()` stays native. */
+type CavosWallet = Cavos | CavosSolana;
+interface ConnectOptions {
+    /** Target chain. The returned wallet is discriminated by this same value. */
+    chain: Chain;
+    /** Environment. Resolved to sepolia/devnet (testnet) or mainnet per chain. */
+    network: NetworkEnv;
+    /** Authenticated user (pass `identity` directly, or an `auth` provider). */
+    auth?: AuthProvider;
+    identity?: Identity;
+    appSalt: string;
+    /**
+     * Cavos App ID. When set (with `backendUrl`), the kit uses the hosted
+     * WalletRegistry + RecoveryClient by default for real multi-device support.
+     */
+    appId?: string;
+    /** Cavos backend base URL. Defaults to https://cavos.xyz. */
+    backendUrl?: string;
+    /**
+     * Off-chain user_id -> wallet map. Defaults to the hosted HttpWalletRegistry
+     * when `appId` is set, else an in-memory registry (single-device only).
+     */
+    registry?: WalletRegistry;
+    /**
+     * Device-approval relay (Starknet). Defaults to HttpRecoveryClient when
+     * `appId` is set; used to request addition of this device when it isn't a
+     * signer yet.
+     */
+    recovery?: RecoveryClient;
+    rpcUrl?: string;
+    /** Override the device signer factory (native / tests); default WebCrypto. */
+    createSigner?: (keyId: string) => Promise<DeviceSigner>;
+    /** Cavos paymaster API key (sponsors deploy + execute). Required for Starknet. */
+    paymasterApiKey?: string;
+    paymasterUrl?: string;
+    classHash?: string;
+    /** Cavos device-account program id override. */
+    programId?: string;
+    /** Gasless sponsorship relayer (defaults to the hosted one when `appId` set). */
+    relayer?: SolanaRelayer;
+    /** Self-funded fee-payer fallback when no relayer is configured. */
+    feePayer?: Keypair;
+}
+/** Whether this device can already operate the wallet, or needs to be added. */
+type ConnectStatus = "ready" | "needs-device-approval";
+/** Options for recovering an account after losing every device signer. */
+interface RecoveryOptions {
+    /** The recovery code the user stored when they ran setupRecovery. */
+    code: string;
+    /** Authenticated identity (same user who owns the account). */
+    identity: Identity;
+    /** Environment (recovery is Starknet-only): testnet → sepolia, mainnet. */
+    network: NetworkEnv;
+    appSalt: string;
+    paymasterApiKey: string;
+    appId?: string;
+    backendUrl?: string;
+    rpcUrl?: string;
+    paymasterUrl?: string;
+    classHash?: string;
+    /** Off-chain user_id -> wallet map. Defaults to the hosted registry. */
+    registry?: WalletRegistry;
+    /** Override the new device's signer (native / tests); default WebCrypto. */
+    createSigner?: (keyId: string) => Promise<DeviceSigner>;
+}
+/**
+ * High-level Cavos wallet. One call logs the user in and returns a ready, gas-
+ * sponsored smart account controlled by a silent device key.
+ *
+ *   const cavos = await Cavos.connect({ network, identity, appSalt, registry, paymasterApiKey });
+ *   if (cavos.status === "ready") await cavos.execute(calls);
+ *
+ * The account address is `f(identity, device_pubkey)` — unforgeable, so it can't
+ * be hijacked. The `registry` recognizes returning users across devices: a new
+ * device on an existing account is flagged `needs-device-approval` (add it via
+ * an already-registered device) instead of creating a second wallet.
+ */
+declare class Cavos {
+    readonly identity: Identity;
+    readonly address: string;
+    readonly status: ConnectStatus;
+    readonly account: Account;
+    private readonly adapter;
+    private readonly devicePubkey;
+    /** Discriminant for the `CavosWallet` union — narrows `execute()` per chain. */
+    readonly chain: "starknet";
+    /** Request id of the pending device-addition, when status is needs-device-approval. */
+    pendingRequestId: string | null;
+    private constructor();
+    /**
+     * Unified entry point. Pick a `chain` and an `network` environment; the kit
+     * resolves the concrete network (sepolia/devnet for testnet, mainnet for
+     * mainnet) and returns a chain-native wallet. The result is a discriminated
+     * union (`wallet.chain`), so `execute()` keeps each chain's native signature:
+     *
+     *   const wallet = await Cavos.connect({ chain: "solana", network: "testnet", identity, appSalt, appId });
+     *   if (wallet.chain === "starknet") await wallet.execute(calls);
+     *   else                              await wallet.execute(amount, dest);
+     */
+    static connect(opts: ConnectOptions): Promise<CavosWallet>;
+    private static connectStarknet;
+    /** This device's public key (e.g. to request addition to an existing wallet). */
+    get publicKey(): DevicePublicKey;
+    /** Execute a sponsored (gasless) multicall, signed silently by the device. */
+    execute(calls: ChainCall[]): Promise<{
+        transactionHash: string;
+    }>;
+    /** Authorize an additional device signer (sponsored). Self-submitted. */
+    addSigner(pubkey: DevicePublicKey): Promise<{
+        transactionHash: string;
+    }>;
+    /**
+     * Register a self-custodial backup signer derived from `code`, so the account
+     * can be recovered after the user loses every device. Idempotent: if the
+     * derived backup key is already an authorised signer, this is a no-op.
+     *
+     * The code never leaves the device — only its deterministic public key is
+     * added on-chain as an ordinary signer. Sponsor this like any other
+     * add_signer (gasless). Returns the transaction hash (or undefined when the
+     * backup was already set up).
+     */
+    setupRecovery(code: string): Promise<{
+        transactionHash: string;
+    } | undefined>;
+    /**
+     * Recover an account after losing every device signer. Derives the backup key
+     * from `code`, uses it (not the new device key) to sign an `add_signer` for
+     * the new device, and returns a ready Cavos bound to the new device. The
+     * account address is unchanged.
+     *
+     * Self-custodial: only someone holding the code (i.e. the rightful owner) can
+     * re-derive the backup key. The backend never sees the code.
+     */
+    static recover(opts: RecoveryOptions): Promise<Cavos>;
+}
+
+export { type AuthProvider as A, buildSecp256r1Instruction as B, type ChainAdapter as C, type DevicePublicKey as D, compressedPubkey as E, encodeLowSSignature as F, serializeInstructions as G, type Identity as I, type NetworkEnv as N, type PendingDeviceRequest as P, type RegisteredWallet as R, SECP256R1_PROGRAM_ID as S, type WalletRegistry as W, type RecoveryClient as a, type DeviceSigner as b, type DeviceSignature as c, type ComputeAddressParams as d, type ChainCall as e, Cavos as f, CavosSolana as g, type CavosWallet as h, type Chain as i, type ConnectOptions as j, type ConnectSolanaOptions as k, type ConnectStatus as l, DEVICE_ACCOUNT_PROGRAM_ID as m, InMemoryWalletRegistry as n, type InstructionAccount as o, type InstructionData as p, type RecoverSolanaOptions as q, type RecoveryOptions as r, SOLANA_NETWORKS as s, SolanaAdapter as t, type SolanaAdapterOptions as u, type SolanaNetwork as v, SolanaRelayer as w, type SolanaRelayerOptions as x, StaticIdentity as y, anchorDiscriminator as z };