@cavos/kit 0.0.1 → 0.0.3

package/dist/Cavos-BH2_tOQ2.d.mts

@@ -0,0 +1,994 @@
+import { Account } from 'starknet';
+import { PublicKey, Connection, TransactionInstruction, Keypair } from '@solana/web3.js';
+import { Keypair as Keypair$1 } from '@stellar/stellar-sdk';
+
+/**
+ * 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>;
+}
+
+/** A parsed passkey assertion, chain-agnostic. */
+interface PasskeyAssertion {
+    authenticatorData: Uint8Array;
+    clientDataJSON: Uint8Array;
+    /** ECDSA signature components (raw, as returned by the authenticator). */
+    r: bigint;
+    s: bigint;
+    /** Byte index where the base64url challenge starts inside clientDataJSON. */
+    challengeOffset: number;
+}
+/** base64url (no padding) of a byte array. */
+declare function base64urlEncode(bytes: Uint8Array): string;
+/**
+ * Batch challenge over ordered per-chain leaves: `sha256(leaf_0 ‖ … ‖ leaf_n)`.
+ * A single passkey assertion over this challenge authorizes `add_signer` on every
+ * chain in the batch (each chain verifies only its own leaf sits at its index).
+ * For a single chain the batch is one leaf, so the challenge is `sha256(leaf)`.
+ */
+declare function batchChallenge(leaves: Uint8Array[]): Uint8Array;
+/** The WebAuthn signed digest: `sha256(authenticatorData || sha256(clientDataJSON))`. */
+declare function webauthnDigest(authenticatorData: Uint8Array, clientDataJSON: Uint8Array): Uint8Array;
+/** Both candidate public keys recoverable from `(r, s)` over `digest`, tagged
+ * with their y-parity. On a fresh browser the assertion does not carry the
+ * pubkey, so the caller identifies the real one via the on-chain `is_approver`
+ * view. */
+declare function recoverCandidatePublicKeys(r: bigint, s: bigint, digest: Uint8Array): {
+    publicKey: DevicePublicKey;
+    yParity: boolean;
+}[];
+/** Normalize `s` to the low half of the curve order (required by the Stellar
+ * and Solana verifiers, which do not normalize on-chain). */
+declare function lowS(s: bigint): bigint;
+
+/** 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, add_approver]` bundle enrolling a passkey approver (device-signed). */
+    buildAddApprover(account: string, passkey: DevicePublicKey): Promise<TransactionInstruction[]>;
+    /** `[precompile, remove_approver]` bundle (device-signed). */
+    buildRemoveApprover(account: string, passkey: DevicePublicKey): Promise<TransactionInstruction[]>;
+    /** This chain's leaf for approving `add_signer(newSigner)` at `nonce`:
+     * `sha256(compressed(new_signer) || passkey_nonce_le8)`. The batch challenge the
+     * passkey signs is `sha256(concat(leaves))` across chains. */
+    passkeyLeaf(newSigner: DevicePublicKey, nonce: bigint): Uint8Array;
+    /**
+     * `[precompile(passkey), add_signer_via_passkey]` bundle. The precompile ix
+     * verifies the PASSKEY's WebAuthn assertion over `authData || sha256(clientDataJSON)`;
+     * the program ix binds the challenge to `newSigner` + the passkey nonce and adds
+     * the signer. No device signature — a gasless relayer can submit it.
+     */
+    buildAddSignerViaPasskey(account: string, newSigner: DevicePublicKey, passkey: DevicePublicKey, leaves: Uint8Array[], leafIndex: number, assertion: PasskeyAssertion): TransactionInstruction[];
+    /** Read whether `passkey` is a registered approver. */
+    isApprover(account: string, passkey: DevicePublicKey): Promise<boolean>;
+    /** Read the current passkey-approval nonce. */
+    passkeyNonce(account: string): Promise<bigint>;
+    /** `[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 fetchApprovers;
+    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 PasskeySignerOptions {
+    /** Relying-Party id (usually the eTLD+1). Defaults to `window.location.hostname`. */
+    rpId?: string;
+    /** Human-readable RP name shown in the OS passkey UI. */
+    rpName?: string;
+}
+interface PasskeyEnrollParams {
+    /** Stable user handle for the credential (e.g. the account address or userId). */
+    userId: string;
+    /** Account name shown in the OS passkey UI (e.g. an email). */
+    userName: string;
+    displayName?: string;
+}
+interface EnrolledPasskey {
+    publicKey: DevicePublicKey;
+    credentialId: Uint8Array;
+}
+/**
+ * Browser passkey signer. Creates a discoverable (resident) secp256r1 credential
+ * that syncs across the user's devices (iCloud Keychain / Google Password
+ * Manager), and produces WebAuthn assertions used to authorize `add_signer`.
+ *
+ * This is a step-up primitive: the app decides WHEN to enroll (e.g. after
+ * onboarding, as a "turn on device approvals" / 2FA moment). Enrollment
+ * registers the passkey on-chain as an approver; later, from any browser, an
+ * assertion approves adding that browser's new device key.
+ */
+declare class PasskeySigner {
+    private readonly rpId;
+    private readonly rpName;
+    constructor(opts?: PasskeySignerOptions);
+    /** True if this platform advertises a usable passkey (platform authenticator). */
+    static isSupported(): Promise<boolean>;
+    /** Create a new synced passkey and return its P-256 public key. */
+    enroll(params: PasskeyEnrollParams): Promise<EnrolledPasskey>;
+    /**
+     * Produce a WebAuthn assertion over `challenge` (a 32-byte value the caller
+     * derives from the signer being added + the on-chain nonce). Uses discoverable
+     * credentials — no `allowCredentials` — so it works on a brand-new browser.
+     */
+    assert(challenge: Uint8Array): Promise<PasskeyAssertion>;
+}
+
+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$2 = "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$2;
+    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>;
+    /**
+     * Enroll a passkey as an approver (2FA-style step-up). Device-signed + gasless;
+     * requires a ready device. Idempotent. Returns the passkey pubkey + tx hash.
+     */
+    enrollPasskey(passkey: PasskeySigner, params: PasskeyEnrollParams): Promise<{
+        publicKey: DevicePublicKey;
+        transactionHash?: string;
+    }>;
+    /** Register an already-enrolled passkey pubkey as an approver (gasless).
+     * Idempotent. Lets one passkey be registered across chains without re-prompting. */
+    addApprover(pubkey: DevicePublicKey): Promise<{
+        transactionHash?: string;
+    }>;
+    /**
+     * From a fresh browser (status `needs-device-approval`), approve adding THIS
+     * device with the user's synced passkey. Gasless via the relayer — the bundle
+     * carries the passkey's WebAuthn assertion, so no device signature is needed.
+     */
+    approveThisDeviceWithPasskey(passkey: PasskeySigner): Promise<string>;
+    /** This device's leaf + passkey nonce for a (possibly multi-chain) batch. */
+    passkeyLeafForThisDevice(): Promise<{
+        leaf: Uint8Array;
+        nonce: bigint;
+    }>;
+    /** Submit `add_signer_via_passkey` given a shared assertion + batch position.
+     * Used by `approveThisDeviceWithPasskey` and `approveDeviceEverywhere`. */
+    submitPasskeyApproval(assertion: PasskeyAssertion, leaves: Uint8Array[], leafIndex: number, _nonce: bigint): Promise<{
+        transactionHash: 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;
+}
+
+/** Cavos device-account primitives on Stellar / Soroban. */
+/**
+ * Deployed `cavos-account-factory` contract id per network (see
+ * account-contracts/stellar/deployments). The factory is the fixed deployer that
+ * makes account addresses a deterministic function of (identity, device pubkey).
+ */
+declare const FACTORY_CONTRACT_ID: {
+    readonly "stellar-testnet": "CBCJIODXIEBOXXD66KCUCF7ZDYJARKI4ZIVQOVWPULOBH5XGNCDP6W3I";
+    readonly "stellar-mainnet": "";
+};
+/** Uploaded Wasm hash of `cavos-device-account` (informational / verification). */
+declare const DEVICE_ACCOUNT_WASM_HASH: {
+    readonly "stellar-testnet": "2671b085578e59a385ef5a5664e42f0450322fe3249539f588e1263ed5a31dce";
+    readonly "stellar-mainnet": "";
+};
+declare const STELLAR_NETWORKS: {
+    readonly "stellar-testnet": {
+        readonly rpcUrl: "https://soroban-testnet.stellar.org";
+        readonly passphrase: "Test SDF Network ; September 2015";
+    };
+    readonly "stellar-mainnet": {
+        readonly rpcUrl: "https://soroban-rpc.mainnet.stellar.gateway.fm";
+        readonly passphrase: "Public Global Stellar Network ; September 2015";
+    };
+};
+type StellarNetwork = keyof typeof STELLAR_NETWORKS;
+/** Native XLM Stellar Asset Contract (SAC) id per network — the token the demo
+ *  moves. Any SEP-41 token contract works; this is a convenience default. */
+declare const NATIVE_SAC_ID: {
+    readonly "stellar-testnet": "CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC";
+    readonly "stellar-mainnet": "CAS3J7GYLGXMF6TDJBBYYSE3HQ6BBSMLNUQ34T6TZMYMW2EVH34XOWMA";
+};
+
+interface StellarRelayerOptions {
+    /** Base URL of the Cavos backend exposing /api/stellar/relay. */
+    baseUrl: string;
+    /** Cavos App ID (authorizes the sponsored request). */
+    appId: string;
+    network: StellarNetwork;
+}
+/**
+ * Client for the Cavos Stellar sponsoring relayer. On Stellar the account is a
+ * *contract*, which cannot be a transaction source — so the relayer's own
+ * G-account is the transaction source AND fee payer. The user's silent device
+ * key never pays: it only signs the Soroban *authorization entry* (verified by
+ * the account's `__check_auth`), which is independent of who submits or pays.
+ * That gives a seedless, gasless experience with no fee-payer keypair on the
+ * integrator side — the same "relayer pays, device authorizes" split as Solana.
+ *
+ * The SDK builds the fully-assembled transaction (source = relayer, Soroban auth
+ * entries already device-signed) and hands its unsigned XDR to the relayer, which
+ * validates it against its allowlist, signs the envelope and submits.
+ */
+declare class StellarRelayer {
+    private readonly opts;
+    private source?;
+    constructor(opts: StellarRelayerOptions);
+    /** The relayer's source/fee-payer G-account (fetched + cached from the backend). */
+    getSource(): Promise<string>;
+    /**
+     * POST the assembled, device-authorized transaction XDR to the relayer to sign
+     * the envelope + submit. Returns the confirmed transaction hash.
+     */
+    submit(transactionXdr: string): Promise<string>;
+}
+
+interface ConnectStellarOptions {
+    network: StellarNetwork;
+    /** 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;
+    /** Factory contract id override (else the per-network default). */
+    factoryId?: 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) the relayer is the transaction source + fee payer, so
+     * the integrator needs NO Stellar keypair — the silent device key (which holds
+     * no XLM) gets a seedless, gasless experience.
+     */
+    relayer?: StellarRelayer;
+    /**
+     * Self-funded fallback: a Stellar `Keypair` that is the transaction source +
+     * fee payer. Used only when no `relayer` is configured (tests / advanced).
+     */
+    sourceKeypair?: Keypair$1;
+}
+interface RecoverStellarOptions extends Omit<ConnectStellarOptions, "auth"> {
+    /** The recovery code the user stored when they ran setupRecovery. */
+    code: string;
+    /** Authenticated identity (same user who owns the account). */
+    identity: Identity;
+}
+type ConnectStatus$1 = "ready" | "needs-device-approval";
+/**
+ * High-level Stellar entry — the Soroban analogue of `Cavos.connect` /
+ * `CavosSolana.connect`. One call derives the deterministic device-bound account,
+ * deploys it via the factory if needed, registers it for cross-device
+ * recognition, and returns a ready handle whose silent P-256 device key
+ * authorizes every action through the account's `__check_auth`.
+ *
+ *   const cavos = await CavosStellar.connect({ network: "stellar-testnet", identity, appSalt, relayer });
+ *   if (cavos.status === "ready") await cavos.execute(10_000_000n, dest); // 1 XLM
+ *
+ * Gasless by default: with an `appId` the Cavos relayer is the tx source + fee
+ * payer. `sourceKeypair` is the self-funded fallback.
+ */
+declare class CavosStellar {
+    readonly identity: Identity;
+    readonly address: string;
+    readonly status: ConnectStatus$1;
+    readonly network: StellarNetwork;
+    private readonly adapter;
+    private readonly devicePubkey;
+    private readonly relayer?;
+    private readonly sourceKeypair?;
+    /** Discriminant for the `CavosWallet` union — narrows `execute()` per chain. */
+    readonly chain: "stellar";
+    private constructor();
+    get publicKey(): DevicePublicKey;
+    static connect(opts: ConnectStellarOptions): Promise<CavosStellar>;
+    /** Authorize an additional device signer (device-signed via `__check_auth`). */
+    addSigner(pubkey: DevicePublicKey): Promise<string>;
+    /**
+     * Enroll a passkey as an approver (2FA-style step-up). Device-signed + gasless;
+     * requires a ready device. Idempotent. Returns the passkey pubkey + tx hash.
+     */
+    enrollPasskey(passkey: PasskeySigner, params: PasskeyEnrollParams): Promise<{
+        publicKey: DevicePublicKey;
+        transactionHash?: string;
+    }>;
+    /** Register an already-enrolled passkey pubkey as an approver (gasless).
+     * Idempotent. Lets one passkey be registered across chains without re-prompting. */
+    addApprover(pubkey: DevicePublicKey): Promise<{
+        transactionHash?: string;
+    }>;
+    /**
+     * From a fresh browser (status `needs-device-approval`), approve adding THIS
+     * device using the user's synced passkey. Gasless via the relayer — the call
+     * carries the WebAuthn assertion, so no device signature is needed. Returns the
+     * tx hash. No trip back to an already-authorized device.
+     */
+    approveThisDeviceWithPasskey(passkey: PasskeySigner): Promise<string>;
+    /** This device's leaf + passkey nonce for a (possibly multi-chain) batch. */
+    passkeyLeafForThisDevice(): Promise<{
+        leaf: Uint8Array;
+        nonce: bigint;
+    }>;
+    /** Submit `add_signer_via_passkey` given a shared assertion + batch position.
+     * No device auth entry — authorized purely by the passkey assertion. */
+    submitPasskeyApproval(assertion: PasskeyAssertion, leaves: Uint8Array[], leafIndex: number, nonce: bigint): Promise<{
+        transactionHash: string;
+    }>;
+    /** Move `amount` stroops of native XLM to `destination` (device-signed). */
+    execute(amount: bigint, destination: string): Promise<string>;
+    /** Read this account's balance of `tokenId` (defaults to native XLM), in stroops. */
+    balance(tokenId?: string): Promise<bigint>;
+    /** Transfer `amount` of any SEP-41 token out of the account (device-signed). */
+    executeTransfer(tokenId: string, amount: bigint, destination: string): Promise<string>;
+    /**
+     * Register the backup signer derived from `code` as an authorized signer of
+     * this account (device-signed). Idempotent. The code never leaves the device —
+     * only the derived public key travels on-chain. Mirrors the other chains.
+     */
+    setupRecovery(code: string): Promise<string | undefined>;
+    /**
+     * Recover an account after losing every device signer: derive the backup key
+     * from `code`, use it (not the new device) to authorize `add_signer(newDevice)`,
+     * and return a ready handle bound to the new device. The address is unchanged.
+     */
+    static recover(opts: RecoverStellarOptions): Promise<CavosStellar>;
+    /** The transaction source/fee-payer G-address (relayer or self-funded). */
+    private resolveSource;
+    /**
+     * Build → simulate → device-sign auth → assemble → submit an invoke-contract
+     * host function. `authAccount` is the account whose `__check_auth` must sign the
+     * operation's Soroban auth entry (undefined for a plain factory deploy).
+     */
+    private submitHostFunction;
+    /** Submit a signed tx via RPC and poll to confirmation. Returns the hash. */
+    private sendAndConfirm;
+}
+
+/** 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" | "stellar";
+/**
+ * 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 | CavosStellar;
+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;
+    /** Gasless sponsorship relayer (defaults to the hosted one when `appId` set). */
+    stellarRelayer?: StellarRelayer;
+    /** Self-funded source/fee-payer Stellar keypair when no relayer is configured. */
+    stellarSourceKeypair?: Keypair$1;
+    /** Factory contract id override (else the per-network default). */
+    factoryId?: string;
+}
+/** 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;
+    /** Paymaster URL + API key, for the sponsored passkey-approval path. */
+    private readonly paymaster?;
+    /** 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;
+    }>;
+    /**
+     * Enroll a passkey as an APPROVER so the user can later add devices from any
+     * browser (2FA-style step-up). Requires a ready device (the enrollment call is
+     * device-signed and gasless). Idempotent: a no-op if the passkey is already an
+     * approver. Call this whenever the app decides to prompt "turn on device
+     * approvals". Returns the passkey's public key + the enrollment tx hash.
+     */
+    enrollPasskey(passkey: PasskeySigner, params: PasskeyEnrollParams): Promise<{
+        publicKey: DevicePublicKey;
+        transactionHash?: string;
+    }>;
+    /**
+     * Register an ALREADY-enrolled passkey public key as an approver (gasless,
+     * device-signed). Idempotent. Use this to register ONE passkey across multiple
+     * chains without re-prompting `passkey.enroll()` on each: enroll once, then
+     * call `addApprover(pubkey)` on each chain's wallet.
+     */
+    addApprover(pubkey: DevicePublicKey): Promise<{
+        transactionHash?: string;
+    }>;
+    /**
+     * From a brand-new browser (status `needs-device-approval`), use the user's
+     * synced passkey to authorize adding THIS device — no trip back to an already-
+     * authorized device.
+     *
+     * `add_signer_via_passkey` is a public external authorized by the embedded
+     * WebAuthn assertion (no device signature), so by default we sponsor it through
+     * the Cavos paymaster's `paymaster_executeDirectTransaction` (the forwarder's
+     * `execute_sponsored` runs a generic call — it does NOT require SNIP-9). Pass a
+     * custom `submit` to route it through your own relayer instead. Returns the tx.
+     */
+    approveThisDeviceWithPasskey(opts: {
+        passkey: PasskeySigner;
+        submit?: (call: ChainCall) => Promise<{
+            transactionHash: string;
+        }>;
+    }): Promise<{
+        transactionHash: string;
+    }>;
+    /** This device's leaf + the current passkey nonce, for a (possibly multi-chain)
+     * passkey approval batch. See `approveDeviceEverywhere`. */
+    passkeyLeafForThisDevice(): Promise<{
+        leaf: Uint8Array;
+        nonce: bigint;
+    }>;
+    /** Submit `add_signer_via_passkey` given a (shared) assertion + this chain's
+     * position in the batch. The assertion doesn't carry the passkey pubkey, so we
+     * recover both candidates and pick the enrolled approver via the on-chain view
+     * (no backend). Defaults to sponsoring through the paymaster. */
+    submitPasskeyApproval(assertion: PasskeyAssertion, leaves: Uint8Array[], leafIndex: number, nonce: bigint, submit?: (call: ChainCall) => Promise<{
+        transactionHash: string;
+    }>): 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>;
+}
+/** A chain wallet that can approve THIS device via a passkey (implemented by
+ * `Cavos`, `CavosSolana`, `CavosStellar`). */
+interface PasskeyApprovable {
+    readonly chain: string;
+    readonly status: string;
+    passkeyLeafForThisDevice(): Promise<{
+        leaf: Uint8Array;
+        nonce: bigint;
+    }>;
+    submitPasskeyApproval(assertion: PasskeyAssertion, leaves: Uint8Array[], leafIndex: number, nonce: bigint): Promise<{
+        transactionHash: string;
+    }>;
+}
+/**
+ * Approve THIS device across several chains with a SINGLE passkey prompt. Each
+ * chain is a separate account, so the device must be added per chain — but one
+ * WebAuthn assertion over the batch challenge (`sha256(concat(leaves))`) suffices
+ * for all of them. Only wallets whose status is `needs-device-approval` are
+ * touched. Returns the per-chain tx hashes.
+ *
+ *   await approveDeviceEverywhere([starknet, solana, stellar], passkey);
+ */
+declare function approveDeviceEverywhere(wallets: PasskeyApprovable[], passkey: PasskeySigner): Promise<{
+    chain: string;
+    transactionHash: string;
+}[]>;
+
+export { batchChallenge as $, type AuthProvider as A, type RecoverStellarOptions as B, type ChainAdapter as C, type DevicePublicKey as D, type EnrolledPasskey as E, FACTORY_CONTRACT_ID as F, type RecoveryOptions as G, SECP256R1_PROGRAM_ID as H, type Identity as I, SOLANA_NETWORKS as J, STELLAR_NETWORKS as K, SolanaAdapter as L, type SolanaAdapterOptions as M, NATIVE_SAC_ID as N, type SolanaNetwork as O, type PendingDeviceRequest as P, SolanaRelayer as Q, type RegisteredWallet as R, type StellarNetwork as S, type SolanaRelayerOptions as T, StaticIdentity as U, StellarRelayer as V, type WalletRegistry as W, type StellarRelayerOptions as X, anchorDiscriminator as Y, approveDeviceEverywhere as Z, base64urlEncode as _, type RecoveryClient as a, buildSecp256r1Instruction as a0, compressedPubkey as a1, encodeLowSSignature as a2, lowS as a3, recoverCandidatePublicKeys as a4, serializeInstructions as a5, webauthnDigest as a6, type DeviceSigner as b, type DeviceSignature as c, type ComputeAddressParams as d, type ChainCall as e, type PasskeyAssertion as f, Cavos as g, CavosSolana as h, CavosStellar as i, type CavosWallet as j, type Chain as k, type ConnectOptions as l, type ConnectSolanaOptions as m, type ConnectStatus as n, type ConnectStellarOptions as o, DEVICE_ACCOUNT_PROGRAM_ID as p, DEVICE_ACCOUNT_WASM_HASH as q, InMemoryWalletRegistry as r, type InstructionAccount as s, type InstructionData as t, type NetworkEnv as u, type PasskeyApprovable as v, type PasskeyEnrollParams as w, PasskeySigner as x, type PasskeySignerOptions as y, type RecoverSolanaOptions as z };