API reference

interface ConnectOptions {
  // Multi-chain (recommended)
  chains?: Chain[];                       // chains to configure (e.g. ["solana", "stellar"])
  defaultChain?: Chain;                   // must be in `chains`

  // Single-chain (deprecated back-compat)
  chain?: Chain;                          // treated as chains: [chain], defaultChain: chain

  network: "testnet" | "mainnet";         // resolves to each chain's concrete network
  appSalt: string;                        // device-key namespace (not the address)
  auth?: AuthProvider;                    // pass `auth` OR `identity`
  identity?: Identity;
  appId?: string;                         // hosted registry + relayers
  environment?: "development" | "production"; // Cavos console environment
  backendUrl?: string;                    // defaults to Cavos hosted services
  rpcUrl?: string;                        // single-chain only; use rpcUrls for multi-chain
  rpcUrls?: Partial<Record<Chain, string>>; // per-chain RPC overrides
  registry?: WalletRegistry;              // off-chain userId -> wallet map
  recovery?: RecoveryClient;              // device-approval relay (Starknet)
  createSigner?: (keyId: string) => Promise<DeviceSigner>; // native / tests

  // --- Starknet-only ---
  paymasterApiKey?: string;               // sponsors deploy + execute (required on Starknet)
  paymasterUrl?: string;
  classHash?: string;

  // --- Solana-only ---
  programId?: string;                     // device-account program override
  relayer?: SolanaRelayer;                // gasless sponsorship
  feePayer?: Keypair;                     // self-funded fallback

  // --- Stellar-only (classic `G…` multisig) ---
  stellarRelayer?: StellarRelayer;        // gasless sponsorship
  stellarSourceKeypair?: StellarKeypair;  // self-funded source/fee-payer
  stellarDeviceKey?: DeviceUnwrapKey;     // this device's ECDH unwrap key
  createStellarDeviceKey?: (keyId: string) => Promise<DeviceUnwrapKey>;
}

type CavosWallet = Cavos | CavosSolana | CavosStellar;

interface CavosSession {
  chains: Chain[];                        // configured chains
  defaultChain: Chain;                    // the default chain
  wallet(chain: Chain): CavosWallet;      // get wallet for a chain
  chainStatus(chain: Chain): ChainStatus; // get status for a chain
  chainAddress(chain: Chain): string;     // get address for a chain
  enrollPasskeySession(passkey, params): Promise<{ publicKey }>;
  setupRecoverySession(code): Promise<void>;
}

type ChainStatus = "undeployed" | "ready" | "needs-device-approval";

interface RecoveryOptions {
  code: string;
  identity: Identity;
  network: "testnet" | "mainnet";
  appSalt: string;
  paymasterApiKey: string;
  appId?: string;
  backendUrl?: string;
  rpcUrl?: string;
  paymasterUrl?: string;
  classHash?: string;
  address?: string;                       // optional when appId set (registry lookup)
  registry?: WalletRegistry;
  auth?: AuthProvider;
  createSigner?: (keyId: string) => Promise<DeviceSigner>;
}