@cavos/kit 0.0.3 → 0.0.5

package/dist/{Cavos-BH2_tOQ2.d.mts → Cavos-D20EtgOK.d.mts}

@@ -184,11 +184,20 @@ declare class SolanaAdapter {
     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;
+    /**
+     * Deterministic account address: PDA of [ACCOUNT_SEED, addressSeed] — the
+     * device pubkey is NOT part of the seeds, so the address is recomputable
+     * from (userId, appSalt) alone. Anti-squatting is the integrator's
+     * responsibility (keep `appSalt` secret; deploy on first login).
+     */
+    computeAddress(addressSeed: Uint8Array): string;
     private pda;
-    /** `initialize` instruction creating the account with its first device signer. */
-    buildInitialize(addressSeed: Uint8Array, payer: string, initialSigner: DevicePublicKey): TransactionInstruction;
+    /**
+     * `initialize` instruction: creates the account PDA and registers the first
+     * device signer. No attestation is required — anti-squatting is NOT enforced
+     * on-chain.
+     */
+    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. */
@@ -209,6 +218,8 @@ declare class SolanaAdapter {
      */
     buildAddSignerViaPasskey(account: string, newSigner: DevicePublicKey, passkey: DevicePublicKey, leaves: Uint8Array[], leafIndex: number, assertion: PasskeyAssertion): TransactionInstruction[];
     /** Read whether `passkey` is a registered approver. */
+    /** True if the account has at least one passkey registered as an approver. */
+    hasPasskeyApprover(account: string): Promise<boolean>;
     isApprover(account: string, passkey: DevicePublicKey): Promise<boolean>;
     /** Read the current passkey-approval nonce. */
     passkeyNonce(account: string): Promise<bigint>;
@@ -331,6 +342,67 @@ declare class PasskeySigner {
     assert(challenge: Uint8Array): Promise<PasskeyAssertion>;
 }
 
+/** A chain-native contract call (Starknet `Call`-shaped; generic for portability). */
+interface ChainCall {
+    contractAddress: string;
+    entrypoint: string;
+    calldata: string[];
+}
+/**
+ * Options for state-changing wallet calls (`execute`, `addSigner`, etc.).
+ *
+ *   await wallet.execute(calls, { sponsored: false }); // self-funded
+ *
+ * `sponsored` defaults to `true`: the Cavos relayer / paymaster pays gas (and, on
+ * Stellar, the reserve) so the user signs but never holds gas tokens. Pass
+ * `sponsored: false` to submit directly — the account pays its own fee / reserve
+ * from its own balance (ETH on Starknet, SOL on Solana, XLM on Stellar). Useful
+ * for testing the device signature, for fee transparency, or as a fallback when
+ * the relayer is unreachable. Self-funded mode requires the account to actually
+ * hold enough native balance for the fee (and Stellar reserve, if the call adds
+ * subentries).
+ */
+interface ExecuteOptions {
+    sponsored?: boolean;
+}
+interface ComputeAddressParams {
+    addressSeed: bigint;
+    /**
+     * First device signer. Required by chains whose address derivation still
+     * includes the device pubkey (Solana PDA seeds, Stellar factory salt). The
+     * Starknet adapter IGNORES this — its address is `f(addressSeed)` only.
+     */
+    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 account address. Starknet: `f(addressSeed)` only (device
+     * pubkey not in the derivation — recovery is self-custodial). Solana: also
+     * `f(addressSeed)` (PDA seeds use only the seed). Stellar: classic `G…`
+     * multisig where the address is the source account.
+     */
+    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[]>;
+}
+
 interface ConnectSolanaOptions {
     network: SolanaNetwork;
     /** Authenticated user (pass `identity` directly, or an `auth` provider). */
@@ -360,7 +432,7 @@ interface ConnectSolanaOptions {
      */
     feePayer?: Keypair;
 }
-type ConnectStatus$2 = "ready" | "needs-device-approval";
+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
@@ -405,7 +477,7 @@ interface RecoverSolanaOptions {
 declare class CavosSolana {
     readonly identity: Identity;
     readonly address: string;
-    readonly status: ConnectStatus$2;
+    readonly status: ConnectStatus$1;
     readonly connection: Connection;
     private readonly adapter;
     private readonly devicePubkey;
@@ -413,6 +485,8 @@ declare class CavosSolana {
     private readonly feePayer?;
     /** Discriminant for the `CavosWallet` union — narrows `execute()` per chain. */
     readonly chain: "solana";
+    /** True when this connect just created a brand-new account (first sign-up). */
+    isNewAccount: boolean;
     private constructor();
     get publicKey(): DevicePublicKey;
     static connect(opts: ConnectSolanaOptions): Promise<CavosSolana>;
@@ -431,6 +505,12 @@ declare class CavosSolana {
     addApprover(pubkey: DevicePublicKey): Promise<{
         transactionHash?: string;
     }>;
+    /** True if this account already has a passkey enrolled as an approver, so a
+     * new device can be approved with the passkey instead of the email flow. */
+    hasPasskey(): Promise<boolean>;
+    /** Re-read (from chain) whether THIS device is now an authorized signer.
+     * Used to poll for readiness after a passkey approval before it's indexed. */
+    isReady(): Promise<boolean>;
     /**
      * From a fresh browser (status `needs-device-approval`), approve adding THIS
      * device with the user's synced passkey. Gasless via the relayer — the bundle
@@ -448,7 +528,7 @@ declare class CavosSolana {
         transactionHash: string;
     }>;
     /** Move `amount` lamports out of the account to `destination` (device-signed). */
-    execute(amount: bigint, destination: string): Promise<string>;
+    execute(amount: bigint, destination: string, opts?: ExecuteOptions): Promise<string>;
     /**
      * Run arbitrary CPI `instructions` with the account PDA as signer (device-
      * signed). The signature commits to sha256 of the canonical Borsh
@@ -457,9 +537,11 @@ declare class CavosSolana {
      *
      * 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.
+     * rejected before co-signing. Pass `{ sponsored: false }` to bypass the relayer
+     * and pay the fee from a configured `feePayer` (e.g. for allowlisted programs
+     * the relayer rejects, or to test the device signature end-to-end).
      */
-    executeInstructions(instructions: InstructionData[]): Promise<string>;
+    executeInstructions(instructions: InstructionData[], opts?: ExecuteOptions): 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
@@ -485,41 +567,79 @@ declare class CavosSolana {
      * the backup key. The on-chain program needs no recovery-specific entrypoint.
      */
     static recover(opts: RecoverSolanaOptions): Promise<CavosSolana>;
+    /**
+     * Submit a built instruction bundle. Sponsored by default (relayer pays the
+     * fee); pass `{ sponsored: false }` to self-fund via the configured `feePayer`.
+     * The device signature is embedded inside the secp256r1 precompile instruction,
+     * NOT applied as a Solana tx signature — so switching only changes who pays,
+     * never the signing identity.
+     */
     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).
+ * The device's P-256 **ECDH** key used only to unwrap the account DEK.
+ *
+ * Note this is a SEPARATE key from the `DeviceSigner` (which is an ECDSA signing
+ * key, non-extractable, and therefore cannot do ECDH). This key is per-device
+ * and non-syncable — losing the device loses only this convenience factor, not
+ * the account (the passkey / recovery factors survive). Its public key goes into
+ * the account's `cv:wd:<id>` on-chain envelope slot; the DEK is ECIES-wrapped to
+ * it so daily unlock is silent.
+ *
+ * `LocalDeviceUnwrapKey` holds a raw scalar (Node / tests / React Native secure
+ * storage). The browser implementation wraps a non-extractable WebCrypto ECDH
+ * key and overrides `unwrap` with `deriveBits`; it never exposes the scalar.
  */
-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": "";
-};
+interface DeviceUnwrapKey {
+    /** SEC1 *uncompressed* (65-byte) public key — the ECIES recipient key that is
+     *  published on-chain in the device's envelope slot. */
+    publicKeySec1(): Uint8Array;
+    /** A short, stable id for this device's envelope slot (`cv:wd:<id>`). */
+    slotId(): string;
+    /** Unwrap the account DEK from this device's ECIES blob. */
+    unwrap(blob: Uint8Array): Promise<Uint8Array>;
+}
+/** Raw-scalar device unwrap key (Node / React Native). */
+declare class LocalDeviceUnwrapKey implements DeviceUnwrapKey {
+    private readonly scalar;
+    private constructor();
+    /** Generate a fresh device unwrap key. */
+    static generate(): LocalDeviceUnwrapKey;
+    /** Rebuild from a persisted 32-byte scalar. */
+    static fromScalar(scalar: Uint8Array): LocalDeviceUnwrapKey;
+    /** The raw scalar, for the caller to persist in secure storage. */
+    export(): Uint8Array;
+    publicKeySec1(): Uint8Array;
+    slotId(): string;
+    unwrap(blob: Uint8Array): Promise<Uint8Array>;
+}
+/** Stable short slot id for a device's envelope entry: first 8 hex of
+ *  `sha256(pubkey)`. Deterministic from the public key, so it's the same on
+ *  every read and can't collide in practice for a handful of devices. */
+declare function deviceSlotId(publicKeySec1: Uint8Array): string;
+
+/** Classic-Stellar (`G…`) network configuration.
+ *
+ * This is now THE Stellar implementation in the kit (the Soroban `C…`
+ * device-account path was removed — `G…` classic multisig is the default). Classic
+ * Stellar uses Horizon (not the Soroban RPC) to load account state and submit
+ * transactions. */
 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";
+declare const HORIZON_URL: {
+    readonly "stellar-testnet": "https://horizon-testnet.stellar.org";
+    readonly "stellar-mainnet": "https://horizon.stellar.org";
 };
+/** Native XLM has 7 decimals (stroops). */
+declare const XLM_DECIMALS = 7;
 
 interface StellarRelayerOptions {
     /** Base URL of the Cavos backend exposing /api/stellar/relay. */
@@ -528,30 +648,33 @@ interface StellarRelayerOptions {
     appId: string;
     network: StellarNetwork;
 }
+/** What the transaction is, so the backend applies the right validation gate.
+ *  - `create`         sponsored account creation (relayer = source + sponsor)
+ *  - `fee-bump`       a control-signed payment wrapped in a relayer fee-bump
+ *  - `sponsored-data` a control-signed data write (add factor/device slot) whose
+ *                     new subentry reserves the relayer sponsors */
+type StellarRelayKind = "create" | "fee-bump" | "sponsored-data";
 /**
- * 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.
+ * Client for the classic-G sponsoring relayer. Unlike the Soroban relayer (which
+ * is the tx *source*), the classic relayer plays two roles:
+ *   - **create**: it is the tx source + fee payer AND sponsors the new account's
+ *     reserves (`begin/endSponsoringFutureReserves`), so the user locks no XLM.
+ *     The SDK sends a master-signed create tx; the relayer co-signs + submits.
+ *   - **fee-bump**: the user's control-signed inner tx (source = their `G…`) is
+ *     wrapped in a fee-bump whose fee source is the relayer. The relayer signs the
+ *     outer envelope only — it pays the fee, never moves the user's funds.
  *
- * 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.
+ * Either way the relayer is a fee payer / reserve sponsor, never a custodian.
  */
 declare class StellarRelayer {
     private readonly opts;
     private source?;
     constructor(opts: StellarRelayerOptions);
-    /** The relayer's source/fee-payer G-account (fetched + cached from the backend). */
+    /** The relayer's source/fee-payer/sponsor G-account (fetched + cached). */
     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>;
+    /** POST a (partially) signed transaction XDR for the relayer to co-sign + submit.
+     *  `kind` selects the validation gate. Returns the confirmed transaction hash. */
+    submit(kind: StellarRelayKind, transactionXdr: string): Promise<string>;
 }
 
 interface ConnectStellarOptions {
@@ -560,157 +683,136 @@ interface ConnectStellarOptions {
     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>;
+    /** This device's P-256 ECDH unwrap key (provisioned + persisted per device). */
+    deviceKey: DeviceUnwrapKey;
     /**
-     * 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.
+     * Gasless sponsorship via the Cavos classic relayer. When set (or when `appId` +
+     * `backendUrl` are given) the relayer is the tx source + fee payer AND sponsors
+     * the account's reserves — the user locks no XLM and pays no fees.
      */
     relayer?: StellarRelayer;
+    /** Cavos App ID — enables the default relayer when no `relayer` is passed. */
+    appId?: string;
+    /** Cavos backend base URL (default https://cavos.xyz). */
+    backendUrl?: string;
     /**
-     * Self-funded fallback: a Stellar `Keypair` that is the transaction source +
-     * fee payer. Used only when no `relayer` is configured (tests / advanced).
+     * Self-funded funder + fee payer: creates + submits classic transactions
+     * directly (the account pays its own reserves + fees). The advanced /
+     * self-hosted fallback used when no relayer is configured.
      */
     sourceKeypair?: Keypair$1;
+    /** Horizon URL override. */
+    horizonUrl?: string;
+    /** Starting balance for a fresh account, in stroops. */
+    startingBalance?: bigint;
 }
-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";
+type StellarConnectStatus = "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`.
+ * High-level entry for the classic-Stellar (`G…`) multisig account — the classic
+ * analogue of `CavosStellar` (Soroban). One `connect` derives the deterministic
+ * `G…` address, creates the account if needed, and on a known device unlocks the
+ * control key from the on-chain envelope so `execute` signs silently.
  *
- *   const cavos = await CavosStellar.connect({ network: "stellar-testnet", identity, appSalt, relayer });
- *   if (cavos.status === "ready") await cavos.execute(10_000_000n, dest); // 1 XLM
+ * Multiple unlock **factors** all wrap the same DEK, so opening any one yields the
+ * control key:
+ *   - **device** (P-256 ECIES): silent daily signing, per-device, non-syncable;
+ *   - **passkey** (WebAuthn PRF): synced anchor to approve a new device / recover;
+ *   - **recovery code**: offline backup (optional).
  *
- * Gasless by default: with an `appId` the Cavos relayer is the tx source + fee
- * payer. `sourceKeypair` is the self-funded fallback.
+ * Self-custodial, no backend, no registry: the address is a pure function of
+ * identity and the control key lives only in the account's own data entries.
+ * Unlike the Soroban `CavosStellar`, this path uses NO wallet registry —
+ * creation needs neither an org API key nor a relayer. The optional relayer is
+ * only a fee payer + reserve sponsor (never a custodian or identity authority),
+ * so a bad/absent relayer can cost fees but can never move funds or squat an
+ * address.
  */
 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. */
+    private readonly deviceKey;
+    private control;
+    private dek;
+    private readonly relayer;
     readonly chain: "stellar";
+    isNewAccount: boolean;
+    private statusValue;
     private constructor();
-    get publicKey(): DevicePublicKey;
+    get status(): StellarConnectStatus;
     static connect(opts: ConnectStellarOptions): Promise<CavosStellar>;
-    /** Authorize an additional device signer (device-signed via `__check_auth`). */
-    addSigner(pubkey: DevicePublicKey): Promise<string>;
+    /** Native XLM balance of the account, in stroops. */
+    balance(): Promise<bigint>;
+    /** True if the account has a passkey factor enrolled (`cv:wp`), so a new device
+     *  can be approved with the passkey instead of a recovery code. Mirrors the
+     *  other chains' `hasPasskey()` for the React provider. */
+    hasPasskey(): Promise<boolean>;
+    /** Whether the control key is unlocked on this device (status ready). Classic
+     *  approvals land synchronously via Horizon, so this reflects state immediately
+     *  (no indexing delay to poll for). */
+    isReady(): Promise<boolean>;
     /**
-     * Enroll a passkey as an approver (2FA-style step-up). Device-signed + gasless;
-     * requires a ready device. Idempotent. Returns the passkey pubkey + tx hash.
+     * Move `amount` stroops of native XLM to `destination`, signed by the control
+     * key. Sponsored by default (the relayer fee-bumps and pays the fee); pass
+     * `{ sponsored: false }` to submit directly — the account pays its own (tiny)
+     * fee from its XLM balance. The control key signs identically in both modes;
+     * only the fee payer differs.
      */
-    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;
-    }>;
+    execute(amount: bigint, destination: string, opts?: ExecuteOptions): Promise<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.
+     * Enroll a passkey as an unlock factor: wrap the DEK under the passkey's PRF
+     * output and write the `cv:wp` entry. This is the synced anchor used to approve
+     * a new device or recover — it survives device loss. Idempotent-ish: writing it
+     * again just overwrites the wrap of the same DEK. Requires a ready 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>;
+    enrollPasskey(prfOutput: Uint8Array): 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.
+     * Set up a recovery code as an unlock factor: wrap the DEK under the code's KEK
+     * and write the `cv:wr` entry. Optional in v1 — the integrating app decides when
+     * to surface it. The code never leaves the device; only the wrap goes on-chain.
+     * Requires a ready device.
      */
-    setupRecovery(code: string): Promise<string | undefined>;
+    setupRecovery(code: string): Promise<string>;
     /**
-     * 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.
+     * From a new browser/device (`needs-device-approval`), approve THIS device using
+     * the user's synced passkey: unlock the DEK via the passkey factor, then wrap it
+     * to this device's slot so future sessions unlock silently. Flips status to
+     * `ready`. No trip back to an already-authorized device.
      */
-    static recover(opts: RecoverStellarOptions): Promise<CavosStellar>;
-    /** The transaction source/fee-payer G-address (relayer or self-funded). */
-    private resolveSource;
+    approveThisDeviceWithPasskey(prfOutput: Uint8Array): Promise<string>;
+    /** Approve THIS device using the recovery code (same as the passkey path, for
+     *  the backup factor). */
+    approveThisDeviceWithRecovery(code: string): Promise<string>;
+    /** The control key's public G address (the weight-1 real signer), for display. */
+    get controlAddress(): string | undefined;
+    private approveThisDevice;
+    /** Write a single-factor wrap (passkey/recovery) into the account data entries,
+     *  signed by the control key. Overwrites cleanly if the base already existed and
+     *  the new blob has the same chunk count. */
+    private writeFactor;
     /**
-     * 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).
+     * Sign an inner (account-sourced) payment tx with the control key and submit it:
+     *   - sponsored (default) → with a relayer, wrap in a fee-bump (relayer pays
+     *     the fee) and POST; falls back to self-funded if no relayer;
+     *   - `{ sponsored: false }` → submit directly (the account pays its own fee).
+     * Payments add no subentries, so no reserve sponsorship is needed here.
      */
-    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>;
+    private submitInner;
     /**
-     * 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.
+     * Write data entries (add a factor / device slot) — which create NEW subentries
+     * that each need ~0.5 XLM of reserve. A relayer-sponsored account holds no XLM,
+     * so the write must be sponsored by the relayer (source + sponsor), exactly like
+     * account creation — a plain fee-bump would fail with `op_low_reserve`.
+     *   - sponsored (default) → with a relayer, build a sponsored write (relayer
+     *     source + begin/end sponsoring), control-sign the account ops, relay
+     *     co-signs + submits; falls back to self-funded if no relayer;
+     *   - `{ sponsored: false }` → the account writes directly (it must hold its
+     *     own reserve for the new subentries).
      */
-    buildSignature(txHash: bigint): Promise<string[]>;
+    private submitDataWrite;
+    private requireControl;
+    private requireUnlocked;
 }
 
 /**
@@ -813,8 +915,12 @@ interface ConnectOptions {
     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;
+    /**
+     * This device's ECDH unwrap key for the Stellar control-key envelope. Defaults
+     * to a persisted `WebCryptoDeviceUnwrapKey` in the browser; pass your own on
+     * React Native / server.
+     */
+    stellarDeviceKey?: DeviceUnwrapKey;
 }
 /** Whether this device can already operate the wallet, or needs to be added. */
 type ConnectStatus = "ready" | "needs-device-approval";
@@ -835,6 +941,13 @@ interface RecoveryOptions {
     classHash?: string;
     /** Off-chain user_id -> wallet map. Defaults to the hosted registry. */
     registry?: WalletRegistry;
+    /**
+     * Skip the registry entirely by passing the account address directly. With
+     * the seed-only derivation, the user can recompute the address from
+     * (userId, appSalt) alone — so recovery no longer depends on the Cavos
+     * backend. Pass this to make recovery fully self-custodial.
+     */
+    address?: string;
     /** Override the new device's signer (native / tests); default WebCrypto. */
     createSigner?: (keyId: string) => Promise<DeviceSigner>;
 }
@@ -863,6 +976,9 @@ declare class Cavos {
     readonly chain: "starknet";
     /** Request id of the pending device-addition, when status is needs-device-approval. */
     pendingRequestId: string | null;
+    /** True when this connect just created & deployed a brand-new account (first
+     * sign-up), so the UI can offer a one-time "secure your account" step. */
+    isNewAccount: boolean;
     private constructor();
     /**
      * Unified entry point. Pick a `chain` and an `network` environment; the kit
@@ -879,11 +995,14 @@ declare class Cavos {
     /** 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<{
+    execute(calls: ChainCall[], opts?: ExecuteOptions): Promise<{
         transactionHash: string;
     }>;
-    /** Authorize an additional device signer (sponsored). Self-submitted. */
-    addSigner(pubkey: DevicePublicKey): Promise<{
+    /**
+     * Authorize an additional device signer. Sponsored by default; pass
+     * `{ sponsored: false }` to pay the fee from the account's own ETH balance.
+     */
+    addSigner(pubkey: DevicePublicKey, opts?: ExecuteOptions): Promise<{
         transactionHash: string;
     }>;
     /**
@@ -893,19 +1012,27 @@ declare class Cavos {
      * 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<{
+    enrollPasskey(passkey: PasskeySigner, params: PasskeyEnrollParams, opts?: ExecuteOptions): 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.
+     * Register an ALREADY-enrolled passkey public key as an approver (gasless by
+     * default, 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. Pass
+     * `{ sponsored: false }` to pay the fee from the account's own balance.
      */
-    addApprover(pubkey: DevicePublicKey): Promise<{
+    addApprover(pubkey: DevicePublicKey, opts?: ExecuteOptions): Promise<{
         transactionHash?: string;
     }>;
+    /** True if this account already has a passkey enrolled as an approver, so a
+     * new device can be approved with the passkey instead of the email flow. */
+    hasPasskey(): Promise<boolean>;
+    /** Re-read (from chain) whether THIS device is now an authorized signer.
+     * Cheap and side-effect free — used to poll for readiness after a passkey /
+     * device approval submits, before the new signer is indexed. */
+    isReady(): Promise<boolean>;
     /**
      * 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-
@@ -950,7 +1077,7 @@ declare class Cavos {
      * add_signer (gasless). Returns the transaction hash (or undefined when the
      * backup was already set up).
      */
-    setupRecovery(code: string): Promise<{
+    setupRecovery(code: string, opts?: ExecuteOptions): Promise<{
         transactionHash: string;
     } | undefined>;
     /**
@@ -964,8 +1091,10 @@ declare class Cavos {
      */
     static recover(opts: RecoveryOptions): Promise<Cavos>;
 }
-/** A chain wallet that can approve THIS device via a passkey (implemented by
- * `Cavos`, `CavosSolana`, `CavosStellar`). */
+/** A chain wallet that can approve THIS device via a batched WebAuthn assertion
+ * (implemented by `Cavos` and `CavosSolana`). Classic Stellar uses a WebAuthn PRF
+ * factor instead (`CavosStellar.approveThisDeviceWithPasskey`), so it is
+ * not part of this batch. */
 interface PasskeyApprovable {
     readonly chain: string;
     readonly status: string;
@@ -984,11 +1113,12 @@ interface PasskeyApprovable {
  * 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);
+ *   await approveDeviceEverywhere([starknet, solana], passkey);
  */
 declare function approveDeviceEverywhere(wallets: PasskeyApprovable[], passkey: PasskeySigner): Promise<{
     chain: string;
-    transactionHash: string;
+    transactionHash?: string;
+    error?: 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 };
+export { anchorDiscriminator as $, type AuthProvider as A, type RecoveryOptions as B, type ChainAdapter as C, type DevicePublicKey as D, type EnrolledPasskey as E, SECP256R1_PROGRAM_ID as F, SOLANA_NETWORKS as G, HORIZON_URL as H, type Identity as I, STELLAR_NETWORKS as J, SolanaAdapter as K, LocalDeviceUnwrapKey as L, type SolanaAdapterOptions as M, type NetworkEnv 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, type StellarConnectStatus as V, type WalletRegistry as W, type StellarRelayKind as X, StellarRelayer as Y, type StellarRelayerOptions as Z, XLM_DECIMALS as _, type RecoveryClient as a, approveDeviceEverywhere as a0, base64urlEncode as a1, batchChallenge as a2, buildSecp256r1Instruction as a3, compressedPubkey as a4, deviceSlotId as a5, encodeLowSSignature as a6, lowS as a7, recoverCandidatePublicKeys as a8, serializeInstructions as a9, webauthnDigest as aa, type DeviceSigner as b, type DeviceSignature as c, type ComputeAddressParams as d, type ChainCall as e, type PasskeyAssertion as f, type DeviceUnwrapKey as g, Cavos as h, CavosSolana as i, CavosStellar as j, type CavosWallet as k, type Chain as l, type ConnectOptions as m, type ConnectSolanaOptions as n, type ConnectStatus as o, type ConnectStellarOptions as p, DEVICE_ACCOUNT_PROGRAM_ID as q, type ExecuteOptions as r, InMemoryWalletRegistry as s, type InstructionAccount as t, type InstructionData as u, type PasskeyApprovable as v, type PasskeyEnrollParams as w, PasskeySigner as x, type PasskeySignerOptions as y, type RecoverSolanaOptions as z };