@cavos/kit 0.0.1 → 0.0.2

package/dist/react/index.js

@@ -4,6 +4,7 @@ var react = require('react');
 var starknet = require('starknet');
 var sha256 = require('@noble/hashes/sha256');
 var p256 = require('@noble/curves/p256');
+var web3_js = require('@solana/web3.js');
 var hkdf = require('@noble/hashes/hkdf');
 var pbkdf2 = require('@noble/hashes/pbkdf2');
 var utils = require('@noble/hashes/utils');
@@ -158,8 +159,8 @@ var CAVOS_PAYMASTER_URL = {
   mainnet: "https://paymaster.cavos.xyz"
 };
 var DEVICE_ACCOUNT_CLASS_HASH = {
-  sepolia: "0x6c3c3426667b6d4adda18a0b8d8cc34c495a1ace7276c4470068ad4c324876d",
-  mainnet: ""
+  sepolia: "0x1840aded59e8a0d2b440a134cb9079a7fc11b06c77f58ed189ab436a034ca6a",
+  mainnet: "0x1840aded59e8a0d2b440a134cb9079a7fc11b06c77f58ed189ab436a034ca6a"
 };
 
 // src/chains/starknet/StarknetAdapter.ts
@@ -308,76 +309,386 @@ var HttpWalletRegistry = class {
   async addDevice(params) {
   }
 };
+function deriveAddressSeed({ userId, appSalt }) {
+  const h = starknet.hash.computePoseidonHashOnElements([feltFromString(userId), feltFromString(appSalt)]);
+  return BigInt(h);
+}
+function deriveAddressSeedSolana({ userId, appSalt }) {
+  return sha256.sha256(new TextEncoder().encode(`cavos:solana:v1:${userId}:${appSalt}`));
+}
+function feltFromString(s) {
+  const bytes = new TextEncoder().encode(s);
+  const chunks = [];
+  for (let i = 0; i < bytes.length; i += 31) {
+    let w = 0n;
+    for (const b of bytes.subarray(i, i + 31)) w = w << 8n | BigInt(b);
+    chunks.push(w);
+  }
+  if (chunks.length === 0) return 0n;
+  if (chunks.length === 1) return chunks[0];
+  return BigInt(starknet.hash.computePoseidonHashOnElements(chunks));
+}
 
-// src/recovery/HttpRecoveryClient.ts
-function toHex2(n) {
-  return "0x" + n.toString(16);
+// src/chains/solana/constants.ts
+var DEVICE_ACCOUNT_PROGRAM_ID = "FHnoYNfYAmFrwt18gcBGG7G1S5q3RAbCBvrV2D29izNJ";
+var SECP256R1_PROGRAM_ID = "Secp256r1SigVerify1111111111111111111111111";
+var ACCOUNT_SEED = "cavos-account";
+var DOMAIN_ADD = "cavos:add_signer:v1";
+var DOMAIN_REMOVE = "cavos:remove_signer:v1";
+var DOMAIN_TRANSFER = "cavos:transfer:v1";
+var DOMAIN_EXECUTE = "cavos:execute:v1";
+var SECP256R1_N = 0xffffffff00000000ffffffffffffffffbce6faada7179e84f3b9cac2fc632551n;
+var SOLANA_NETWORKS = {
+  "solana-devnet": "https://api.devnet.solana.com",
+  "solana-mainnet": "https://api.mainnet-beta.solana.com",
+  "solana-localnet": "http://127.0.0.1:8899"
+};
+
+// src/chains/solana/SolanaAdapter.ts
+var COMPRESSED_PUBKEY_SIZE = 33;
+var SIGNATURE_SIZE = 64;
+var CURRENT_IX = 65535;
+var SolanaAdapter = class {
+  constructor(opts = {}) {
+    this.opts = opts;
+    this.chain = "solana";
+    this.programId = new web3_js.PublicKey(opts.programId ?? DEVICE_ACCOUNT_PROGRAM_ID);
+  }
+  /** Deterministic account address: PDA of [seed, address_seed, initial_signer_x]. */
+  computeAddress(addressSeed, initialSigner) {
+    return this.pda(addressSeed, compressedPubkey(initialSigner)).toBase58();
+  }
+  pda(addressSeed, initialCompressed) {
+    const [pda] = web3_js.PublicKey.findProgramAddressSync(
+      [
+        Buffer.from(ACCOUNT_SEED),
+        Buffer.from(addressSeed),
+        Buffer.from(initialCompressed.slice(1, 33))
+        // x-coordinate
+      ],
+      this.programId
+    );
+    return pda;
+  }
+  /** `initialize` instruction creating the account with its first device signer. */
+  buildInitialize(addressSeed, payer, initialSigner) {
+    const initialCompressed = compressedPubkey(initialSigner);
+    const account = this.pda(addressSeed, initialCompressed);
+    const data = Buffer.concat([
+      anchorDiscriminator("initialize"),
+      Buffer.from(addressSeed),
+      // [u8;32]
+      Buffer.from(initialCompressed)
+      // [u8;33]
+    ]);
+    return new web3_js.TransactionInstruction({
+      programId: this.programId,
+      keys: [
+        { pubkey: account, isSigner: false, isWritable: true },
+        { pubkey: new web3_js.PublicKey(payer), isSigner: true, isWritable: true },
+        { pubkey: web3_js.SystemProgram.programId, isSigner: false, isWritable: false }
+      ],
+      data
+    });
+  }
+  /** `[precompile, add_signer]` bundle, authorized by an existing device signer. */
+  async buildAddSigner(account, newSigner) {
+    const accountPk = new web3_js.PublicKey(account);
+    const newCompressed = compressedPubkey(newSigner);
+    const nonce = await this.fetchNonce(accountPk);
+    const message = concatBytes(
+      Buffer.from(DOMAIN_ADD),
+      accountPk.toBuffer(),
+      newCompressed,
+      u64le(nonce)
+    );
+    const { precompileIx } = await this.signToPrecompile(message);
+    const ix = new web3_js.TransactionInstruction({
+      programId: this.programId,
+      keys: this.guardedKeys(accountPk),
+      data: Buffer.concat([anchorDiscriminator("add_signer"), Buffer.from(newCompressed)])
+    });
+    return [precompileIx, ix];
+  }
+  /** `[precompile, remove_signer]` bundle, authorized by an existing device signer. */
+  async buildRemoveSigner(account, signer) {
+    const accountPk = new web3_js.PublicKey(account);
+    const compressed = compressedPubkey(signer);
+    const nonce = await this.fetchNonce(accountPk);
+    const message = concatBytes(
+      Buffer.from(DOMAIN_REMOVE),
+      accountPk.toBuffer(),
+      compressed,
+      u64le(nonce)
+    );
+    const { precompileIx } = await this.signToPrecompile(message);
+    const ix = new web3_js.TransactionInstruction({
+      programId: this.programId,
+      keys: this.guardedKeys(accountPk),
+      data: Buffer.concat([anchorDiscriminator("remove_signer"), Buffer.from(compressed)])
+    });
+    return [precompileIx, ix];
+  }
+  /** `[precompile, execute_transfer]` bundle moving lamports out of the account. */
+  async buildExecuteTransfer(account, destination, amount) {
+    const accountPk = new web3_js.PublicKey(account);
+    const destPk = new web3_js.PublicKey(destination);
+    const nonce = await this.fetchNonce(accountPk);
+    const message = concatBytes(
+      Buffer.from(DOMAIN_TRANSFER),
+      accountPk.toBuffer(),
+      destPk.toBuffer(),
+      u64le(amount),
+      u64le(nonce)
+    );
+    const { precompileIx } = await this.signToPrecompile(message);
+    const ix = new web3_js.TransactionInstruction({
+      programId: this.programId,
+      keys: [
+        { pubkey: accountPk, isSigner: false, isWritable: true },
+        { pubkey: destPk, isSigner: false, isWritable: true },
+        { pubkey: web3_js.SYSVAR_INSTRUCTIONS_PUBKEY, isSigner: false, isWritable: false }
+      ],
+      data: Buffer.concat([anchorDiscriminator("execute_transfer"), u64le(amount)])
+    });
+    return [precompileIx, ix];
+  }
+  /**
+   * `[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.
+   */
+  async buildExecute(account, instructions) {
+    if (instructions.length === 0) throw new Error("kit/solana: execute requires at least one instruction");
+    const accountPk = new web3_js.PublicKey(account);
+    const nonce = await this.fetchNonce(accountPk);
+    const blob = serializeInstructions(instructions);
+    const ixsHash = sha256.sha256(blob);
+    const message = concatBytes(
+      Buffer.from(DOMAIN_EXECUTE),
+      accountPk.toBuffer(),
+      Buffer.from(ixsHash),
+      u64le(nonce)
+    );
+    const { precompileIx } = await this.signToPrecompile(message);
+    const blobLen = Buffer.alloc(4);
+    new DataView(blobLen.buffer).setUint32(0, blob.length, true);
+    const data = Buffer.concat([anchorDiscriminator("execute"), blobLen, blob]);
+    const remainingAccounts = [];
+    for (const ix2 of instructions) {
+      for (const acc of ix2.accounts) {
+        remainingAccounts.push({
+          pubkey: new web3_js.PublicKey(acc.pubkey),
+          isSigner: false,
+          // signer flags are part of the signed InstructionData
+          isWritable: acc.isWritable
+        });
+      }
+      remainingAccounts.push({
+        pubkey: new web3_js.PublicKey(ix2.programId),
+        isSigner: false,
+        isWritable: false
+      });
+    }
+    const ix = new web3_js.TransactionInstruction({
+      programId: this.programId,
+      keys: [
+        { pubkey: accountPk, isSigner: false, isWritable: true },
+        { pubkey: web3_js.SYSVAR_INSTRUCTIONS_PUBKEY, isSigner: false, isWritable: false },
+        ...remainingAccounts
+      ],
+      data
+    });
+    return [precompileIx, ix];
+  }
+  /** Read whether `signer` is currently an authorized signer of `account`. */
+  async isAuthorizedSigner(account, signer) {
+    const signers = await this.fetchSigners(new web3_js.PublicKey(account));
+    const target = Buffer.from(compressedPubkey(signer)).toString("hex");
+    return signers.some((s) => Buffer.from(s).toString("hex") === target);
+  }
+  guardedKeys(account) {
+    return [
+      { pubkey: account, isSigner: false, isWritable: true },
+      { pubkey: web3_js.SYSVAR_INSTRUCTIONS_PUBKEY, isSigner: false, isWritable: false }
+    ];
+  }
+  /** Sign `message` with the device key and build the matching precompile ix. */
+  async signToPrecompile(message) {
+    if (!this.opts.signer) throw new Error("kit/solana: signer required to authorize");
+    const pubkey = await this.opts.signer.getPublicKey();
+    const sig = await this.opts.signer.sign(message);
+    const signature = encodeLowSSignature(sig.r, sig.s);
+    const precompileIx = buildSecp256r1Instruction(
+      compressedPubkey(pubkey),
+      signature,
+      message
+    );
+    return { precompileIx };
+  }
+  async fetchNonce(account) {
+    const info = await this.requireConnection().getAccountInfo(account);
+    if (!info) return 0n;
+    return readU64le(info.data, 41);
+  }
+  async fetchSigners(account) {
+    const info = await this.requireConnection().getAccountInfo(account);
+    if (!info) return [];
+    const d = info.data;
+    const lenOffset = 8 + 32 + 1 + 8 + COMPRESSED_PUBKEY_SIZE;
+    const count = d.readUInt32LE(lenOffset);
+    const out = [];
+    let off = lenOffset + 4;
+    for (let i = 0; i < count; i++) {
+      out.push(Uint8Array.from(d.subarray(off, off + COMPRESSED_PUBKEY_SIZE)));
+      off += COMPRESSED_PUBKEY_SIZE;
+    }
+    return out;
+  }
+  requireConnection() {
+    if (!this.opts.connection) throw new Error("kit/solana: connection required for reads");
+    return this.opts.connection;
+  }
+};
+function compressedPubkey(pk) {
+  const out = new Uint8Array(COMPRESSED_PUBKEY_SIZE);
+  out[0] = pk.y % 2n === 0n ? 2 : 3;
+  out.set(bigIntTo32Bytes(pk.x), 1);
+  return out;
 }
-function fromHex2(s) {
-  return BigInt(s);
+function encodeLowSSignature(r, s) {
+  const lowS = s > SECP256R1_N / 2n ? SECP256R1_N - s : s;
+  const out = new Uint8Array(SIGNATURE_SIZE);
+  out.set(bigIntTo32Bytes(r), 0);
+  out.set(bigIntTo32Bytes(lowS), 32);
+  return out;
 }
-function deviceLabel() {
-  if (typeof navigator !== "undefined") {
-    return navigator.userAgent || "a new device";
+function buildSecp256r1Instruction(compressed, signature, message) {
+  const headerLen = 2;
+  const offsetsLen = 14;
+  const pubkeyOffset = headerLen + offsetsLen;
+  const sigOffset = pubkeyOffset + COMPRESSED_PUBKEY_SIZE;
+  const msgOffset = sigOffset + SIGNATURE_SIZE;
+  const data = Buffer.alloc(msgOffset + message.length);
+  data.writeUInt8(1, 0);
+  data.writeUInt8(0, 1);
+  let o = headerLen;
+  data.writeUInt16LE(sigOffset, o);
+  o += 2;
+  data.writeUInt16LE(CURRENT_IX, o);
+  o += 2;
+  data.writeUInt16LE(pubkeyOffset, o);
+  o += 2;
+  data.writeUInt16LE(CURRENT_IX, o);
+  o += 2;
+  data.writeUInt16LE(msgOffset, o);
+  o += 2;
+  data.writeUInt16LE(message.length, o);
+  o += 2;
+  data.writeUInt16LE(CURRENT_IX, o);
+  o += 2;
+  Buffer.from(compressed).copy(data, pubkeyOffset);
+  Buffer.from(signature).copy(data, sigOffset);
+  Buffer.from(message).copy(data, msgOffset);
+  return new web3_js.TransactionInstruction({
+    keys: [],
+    programId: new web3_js.PublicKey(SECP256R1_PROGRAM_ID),
+    data
+  });
+}
+function anchorDiscriminator(name) {
+  return Buffer.from(sha256.sha256(`global:${name}`).slice(0, 8));
+}
+function u64le(n) {
+  const b = Buffer.alloc(8);
+  new DataView(b.buffer, b.byteOffset, 8).setBigUint64(0, BigInt(n), true);
+  return b;
+}
+function readU64le(buf, offset) {
+  return new DataView(buf.buffer, buf.byteOffset, buf.length).getBigUint64(
+    offset,
+    true
+  );
+}
+function concatBytes(...parts) {
+  const total = parts.reduce((n, p) => n + p.length, 0);
+  const out = new Uint8Array(total);
+  let off = 0;
+  for (const p of parts) {
+    out.set(p, off);
+    off += p.length;
   }
-  return "a new device";
+  return out;
 }
-var HttpRecoveryClient = class {
+function serializeInstruction(ix) {
+  const programId = new web3_js.PublicKey(ix.programId).toBuffer();
+  const accounts = serializeAccounts(ix.accounts);
+  const data = serializeVecU8(ix.data);
+  return Buffer.concat([programId, accounts, data]);
+}
+function serializeAccounts(metas) {
+  const len = Buffer.alloc(4);
+  new DataView(len.buffer).setUint32(0, metas.length, true);
+  const parts = metas.map(serializeAccountMeta);
+  return Buffer.concat([len, ...parts]);
+}
+function serializeAccountMeta(meta) {
+  const pubkey = new web3_js.PublicKey(meta.pubkey).toBuffer();
+  return Buffer.concat([pubkey, Buffer.from([meta.isSigner ? 1 : 0, meta.isWritable ? 1 : 0])]);
+}
+function serializeVecU8(data) {
+  const len = Buffer.alloc(4);
+  new DataView(len.buffer).setUint32(0, data.length, true);
+  return Buffer.concat([len, Buffer.from(data)]);
+}
+function serializeInstructions(instructions) {
+  return Buffer.concat(instructions.map(serializeInstruction));
+}
+var SolanaRelayer = class {
   constructor(opts) {
     this.opts = opts;
   }
-  async requestDeviceAddition(params) {
-    const res = await fetch(new URL("/api/devices/request", this.opts.baseUrl), {
+  /** The relayer's fee-payer pubkey (fetched + cached from the backend). */
+  async getFeePayer() {
+    if (this.feePayer) return this.feePayer;
+    const res = await fetch(`${this.opts.baseUrl}/api/solana/relay?network=${this.opts.network}`);
+    if (!res.ok) throw new Error(`kit/solana: relayer fee-payer lookup failed (${res.status})`);
+    const { fee_payer } = await res.json();
+    this.feePayer = new web3_js.PublicKey(fee_payer);
+    return this.feePayer;
+  }
+  /**
+   * 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.
+   */
+  async send(instructions) {
+    const feePayer = await this.getFeePayer();
+    const { blockhash } = await this.opts.connection.getLatestBlockhash("confirmed");
+    const tx2 = new web3_js.Transaction();
+    tx2.feePayer = feePayer;
+    tx2.recentBlockhash = blockhash;
+    tx2.add(...instructions);
+    const serialized = tx2.serialize({ requireAllSignatures: false, verifySignatures: false }).toString("base64");
+    const res = await fetch(`${this.opts.baseUrl}/api/solana/relay`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({
         app_id: this.opts.appId,
-        wallet_address: params.accountAddress,
-        new_pub_x: toHex2(params.newSigner.x),
-        new_pub_y: toHex2(params.newSigner.y),
-        device_label: params.deviceLabel ?? deviceLabel(),
-        ...params.email ? { email: params.email } : {}
+        network: this.opts.network,
+        transaction: serialized
       })
     });
     if (!res.ok) {
-      const t = await res.text().catch(() => "");
-      throw new Error(`requestDeviceAddition failed: ${res.status} ${t}`);
-    }
-    const data = await res.json();
-    return { requestId: data.request_id };
-  }
-  async getPendingRequest(requestId) {
-    const url = new URL("/api/devices/request", this.opts.baseUrl);
-    url.searchParams.set("id", requestId);
-    const res = await fetch(url, { headers: { "Content-Type": "application/json" } });
-    if (!res.ok) throw new Error(`getPendingRequest failed: ${res.status}`);
-    const data = await res.json();
-    if (!data.found) return null;
-    const status = data.status;
-    return {
-      requestId: data.request_id,
-      appId: data.app_id,
-      userId: "",
-      // the approving device already knows its own identity
-      accountAddress: data.wallet_address,
-      newSigner: { x: fromHex2(data.new_pub_x), y: fromHex2(data.new_pub_y) },
-      createdAt: data.created_at,
-      status
-    };
-  }
-  async confirmDeviceAddition(params) {
-    const res = await fetch(
-      new URL(`/api/devices/request/${params.requestId}/confirm`, this.opts.baseUrl),
-      {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ tx_hash: params.txHash })
-      }
-    );
-    if (!res.ok) {
-      const t = await res.text().catch(() => "");
-      throw new Error(`confirmDeviceAddition failed: ${res.status} ${t}`);
+      const detail = await res.text().catch(() => "");
+      throw new Error(`kit/solana: relay failed (${res.status}) ${detail}`);
     }
+    const { signature } = await res.json();
+    return signature;
   }
 };
 var BACKUP_KDF_SALT = "cavos-recovery-v1";
@@ -687,24 +998,279 @@ var WORDLIST = [
   "beach",
   "dusk"
 ];
-function deriveAddressSeed({ userId, appSalt }) {
-  const h = starknet.hash.computePoseidonHashOnElements([feltFromString(userId), feltFromString(appSalt)]);
-  return BigInt(h);
+
+// src/chains/solana/CavosSolana.ts
+var CavosSolana = class _CavosSolana {
+  constructor(identity, address, status, connection, adapter, devicePubkey, relayer, feePayer) {
+    this.identity = identity;
+    this.address = address;
+    this.status = status;
+    this.connection = connection;
+    this.adapter = adapter;
+    this.devicePubkey = devicePubkey;
+    this.relayer = relayer;
+    this.feePayer = feePayer;
+    /** Discriminant for the `CavosWallet` union — narrows `execute()` per chain. */
+    this.chain = "solana";
+  }
+  get publicKey() {
+    return this.devicePubkey;
+  }
+  static async connect(opts) {
+    const identity = opts.identity ?? await opts.auth?.authenticate();
+    if (!identity) throw new Error("kit/solana: connect requires `identity` or `auth`");
+    if (opts.network === "solana-mainnet" && !opts.rpcUrl) {
+      console.warn(
+        "[cavos] Using the public mainnet-beta RPC. Pass `rpcUrl` with your own provider (Helius/Triton/QuickNode) for production \u2014 the public endpoint is rate-limited."
+      );
+    }
+    const connection = new web3_js.Connection(opts.rpcUrl ?? SOLANA_NETWORKS[opts.network], "confirmed");
+    const signer = opts.createSigner ? await opts.createSigner(`${identity.userId}:${opts.appSalt}`) : await WebCryptoSigner.loadOrCreate({ keyId: `${identity.userId}:${opts.appSalt}` });
+    const devicePubkey = await signer.getPublicKey();
+    const adapter = new SolanaAdapter({ programId: opts.programId, connection, signer });
+    const addressSeed = deriveAddressSeedSolana({ userId: identity.userId, appSalt: opts.appSalt });
+    const backendUrl = opts.backendUrl ?? "https://cavos.xyz";
+    const registry = opts.registry ?? (opts.appId ? new HttpWalletRegistry({ baseUrl: backendUrl, appId: opts.appId, network: opts.network }) : defaultRegistry);
+    const relayer = opts.relayer ?? (opts.appId ? new SolanaRelayer({ baseUrl: backendUrl, appId: opts.appId, network: opts.network, connection }) : void 0);
+    const existing = await registry.lookup(identity.userId);
+    if (existing) {
+      const isSigner2 = await adapter.isAuthorizedSigner(existing.address, devicePubkey);
+      return new _CavosSolana(
+        identity,
+        existing.address,
+        isSigner2 ? "ready" : "needs-device-approval",
+        connection,
+        adapter,
+        devicePubkey,
+        relayer,
+        opts.feePayer
+      );
+    }
+    const address = adapter.computeAddress(addressSeed, devicePubkey);
+    const deployed = await connection.getAccountInfo(new web3_js.PublicKey(address)) !== null;
+    if (!deployed) {
+      if (relayer) {
+        const payer = await relayer.getFeePayer();
+        const ix = adapter.buildInitialize(addressSeed, payer.toBase58(), devicePubkey);
+        await relayer.send([ix]);
+      } else if (opts.feePayer) {
+        const ix = adapter.buildInitialize(addressSeed, opts.feePayer.publicKey.toBase58(), devicePubkey);
+        await web3_js.sendAndConfirmTransaction(connection, new web3_js.Transaction().add(ix), [opts.feePayer]);
+      } else {
+        throw new Error("kit/solana: a relayer (appId) or feePayer is required to initialize a new account");
+      }
+    }
+    await registry.register({ userId: identity.userId, address, initialSigner: devicePubkey });
+    const isSigner = await adapter.isAuthorizedSigner(address, devicePubkey);
+    return new _CavosSolana(
+      identity,
+      address,
+      isSigner ? "ready" : "needs-device-approval",
+      connection,
+      adapter,
+      devicePubkey,
+      relayer,
+      opts.feePayer
+    );
+  }
+  /** Authorize an additional device signer (device-signed via precompile). */
+  async addSigner(pubkey) {
+    const ixs = await this.adapter.buildAddSigner(this.address, pubkey);
+    return this.send(ixs);
+  }
+  /** Move `amount` lamports out of the account to `destination` (device-signed). */
+  async execute(amount, destination) {
+    if (this.status !== "ready") {
+      throw new Error("kit/solana: this device is not yet an authorized signer of the wallet");
+    }
+    const ixs = await this.adapter.buildExecuteTransfer(this.address, destination, amount);
+    return this.send(ixs);
+  }
+  /**
+   * 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.
+   */
+  async executeInstructions(instructions) {
+    if (this.status !== "ready") {
+      throw new Error("kit/solana: this device is not yet an authorized signer of the wallet");
+    }
+    const ixs = await this.adapter.buildExecute(this.address, instructions);
+    return this.send(ixs);
+  }
+  /**
+   * 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.
+   */
+  async setupRecovery(code) {
+    if (this.status !== "ready") {
+      throw new Error("kit/solana: setupRecovery requires a ready, registered device");
+    }
+    const { publicKey: backupPubkey } = deriveBackupKey(code);
+    const already = await this.adapter.isAuthorizedSigner(this.address, backupPubkey);
+    if (already) return void 0;
+    return this.addSigner(backupPubkey);
+  }
+  /**
+   * 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 async recover(opts) {
+    if (opts.network === "solana-mainnet" && !opts.rpcUrl) {
+      console.warn(
+        "[cavos] Using the public mainnet-beta RPC. Pass `rpcUrl` with your own provider (Helius/Triton/QuickNode) for production \u2014 the public endpoint is rate-limited."
+      );
+    }
+    const connection = new web3_js.Connection(opts.rpcUrl ?? SOLANA_NETWORKS[opts.network], "confirmed");
+    const signer = opts.createSigner ? await opts.createSigner(`${opts.identity.userId}:${opts.appSalt}`) : await WebCryptoSigner.loadOrCreate({ keyId: `${opts.identity.userId}:${opts.appSalt}` });
+    const devicePubkey = await signer.getPublicKey();
+    const backup = BackupSigner.fromCode(opts.code);
+    const backupAdapter = new SolanaAdapter({
+      programId: opts.programId,
+      connection,
+      signer: backup
+    });
+    const backendUrl = opts.backendUrl ?? "https://cavos.xyz";
+    const registry = opts.registry ?? (opts.appId ? new HttpWalletRegistry({ baseUrl: backendUrl, appId: opts.appId, network: opts.network }) : defaultRegistry);
+    const existing = await registry.lookup(opts.identity.userId);
+    if (!existing) {
+      throw new Error("kit/solana: no account found for this identity \u2014 nothing to recover");
+    }
+    const relayer = opts.relayer ?? (opts.appId ? new SolanaRelayer({ baseUrl: backendUrl, appId: opts.appId, network: opts.network, connection }) : void 0);
+    const alreadyAuthed = await backupAdapter.isAuthorizedSigner(existing.address, devicePubkey);
+    if (!alreadyAuthed) {
+      const ixs = await backupAdapter.buildAddSigner(existing.address, devicePubkey);
+      if (relayer) {
+        await relayer.send(ixs);
+      } else if (opts.feePayer) {
+        await web3_js.sendAndConfirmTransaction(connection, new web3_js.Transaction().add(...ixs), [opts.feePayer]);
+      } else {
+        throw new Error("kit/solana: a relayer (appId) or feePayer is required to recover");
+      }
+    }
+    const adapter = new SolanaAdapter({ programId: opts.programId, connection, signer });
+    return new _CavosSolana(
+      opts.identity,
+      existing.address,
+      "ready",
+      connection,
+      adapter,
+      devicePubkey,
+      relayer,
+      opts.feePayer
+    );
+  }
+  async send(ixs) {
+    if (this.relayer) return this.relayer.send(ixs);
+    if (this.feePayer) {
+      return web3_js.sendAndConfirmTransaction(this.connection, new web3_js.Transaction().add(...ixs), [this.feePayer]);
+    }
+    throw new Error("kit/solana: no relayer or feePayer configured to submit transactions");
+  }
+};
+var defaultRegistry = new InMemoryWalletRegistry();
+
+// src/recovery/HttpRecoveryClient.ts
+function toHex2(n) {
+  return "0x" + n.toString(16);
 }
-function feltFromString(s) {
-  const bytes = new TextEncoder().encode(s);
-  const chunks = [];
-  for (let i = 0; i < bytes.length; i += 31) {
-    let w = 0n;
-    for (const b of bytes.subarray(i, i + 31)) w = w << 8n | BigInt(b);
-    chunks.push(w);
+function fromHex2(s) {
+  return BigInt(s);
+}
+function deviceLabel() {
+  if (typeof navigator !== "undefined") {
+    return navigator.userAgent || "a new device";
   }
-  if (chunks.length === 0) return 0n;
-  if (chunks.length === 1) return chunks[0];
-  return BigInt(starknet.hash.computePoseidonHashOnElements(chunks));
+  return "a new device";
 }
+var HttpRecoveryClient = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  async requestDeviceAddition(params) {
+    const res = await fetch(new URL("/api/devices/request", this.opts.baseUrl), {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        app_id: this.opts.appId,
+        wallet_address: params.accountAddress,
+        new_pub_x: toHex2(params.newSigner.x),
+        new_pub_y: toHex2(params.newSigner.y),
+        device_label: params.deviceLabel ?? deviceLabel(),
+        ...params.email ? { email: params.email } : {}
+      })
+    });
+    if (!res.ok) {
+      const t = await res.text().catch(() => "");
+      throw new Error(`requestDeviceAddition failed: ${res.status} ${t}`);
+    }
+    const data = await res.json();
+    return { requestId: data.request_id };
+  }
+  async getPendingRequest(requestId) {
+    const url = new URL("/api/devices/request", this.opts.baseUrl);
+    url.searchParams.set("id", requestId);
+    const res = await fetch(url, { headers: { "Content-Type": "application/json" } });
+    if (!res.ok) throw new Error(`getPendingRequest failed: ${res.status}`);
+    const data = await res.json();
+    if (!data.found) return null;
+    const status = data.status;
+    return {
+      requestId: data.request_id,
+      appId: data.app_id,
+      userId: "",
+      // the approving device already knows its own identity
+      accountAddress: data.wallet_address,
+      newSigner: { x: fromHex2(data.new_pub_x), y: fromHex2(data.new_pub_y) },
+      createdAt: data.created_at,
+      status
+    };
+  }
+  async confirmDeviceAddition(params) {
+    const res = await fetch(
+      new URL(`/api/devices/request/${params.requestId}/confirm`, this.opts.baseUrl),
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ tx_hash: params.txHash })
+      }
+    );
+    if (!res.ok) {
+      const t = await res.text().catch(() => "");
+      throw new Error(`confirmDeviceAddition failed: ${res.status} ${t}`);
+    }
+  }
+};
 
 // src/Cavos.ts
+var STARKNET_ENV = {
+  mainnet: "mainnet",
+  testnet: "sepolia"
+};
+var SOLANA_ENV = {
+  mainnet: "solana-mainnet",
+  testnet: "solana-devnet"
+};
 var Cavos = class _Cavos {
   constructor(identity, address, status, account, adapter, devicePubkey) {
     this.identity = identity;
@@ -713,10 +1279,58 @@ var Cavos = class _Cavos {
     this.account = account;
     this.adapter = adapter;
     this.devicePubkey = devicePubkey;
+    /** Discriminant for the `CavosWallet` union — narrows `execute()` per chain. */
+    this.chain = "starknet";
     /** Request id of the pending device-addition, when status is needs-device-approval. */
     this.pendingRequestId = null;
   }
+  /**
+   * 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 async connect(opts) {
+    if (opts.chain === "solana") {
+      return CavosSolana.connect({
+        network: SOLANA_ENV[opts.network],
+        ...opts.auth ? { auth: opts.auth } : {},
+        ...opts.identity ? { identity: opts.identity } : {},
+        appSalt: opts.appSalt,
+        ...opts.appId ? { appId: opts.appId } : {},
+        ...opts.backendUrl ? { backendUrl: opts.backendUrl } : {},
+        ...opts.registry ? { registry: opts.registry } : {},
+        ...opts.rpcUrl ? { rpcUrl: opts.rpcUrl } : {},
+        ...opts.programId ? { programId: opts.programId } : {},
+        ...opts.createSigner ? { createSigner: opts.createSigner } : {},
+        ...opts.relayer ? { relayer: opts.relayer } : {},
+        ...opts.feePayer ? { feePayer: opts.feePayer } : {}
+      });
+    }
+    if (!opts.paymasterApiKey) {
+      throw new Error("kit: `paymasterApiKey` is required for Starknet connections");
+    }
+    return _Cavos.connectStarknet({
+      network: STARKNET_ENV[opts.network],
+      auth: opts.auth,
+      identity: opts.identity,
+      appSalt: opts.appSalt,
+      appId: opts.appId,
+      backendUrl: opts.backendUrl,
+      registry: opts.registry,
+      recovery: opts.recovery,
+      paymasterApiKey: opts.paymasterApiKey,
+      paymasterUrl: opts.paymasterUrl,
+      rpcUrl: opts.rpcUrl,
+      classHash: opts.classHash,
+      createSigner: opts.createSigner
+    });
+  }
+  static async connectStarknet(opts) {
     const identity = opts.identity ?? await opts.auth?.authenticate();
     if (!identity) throw new Error("kit: connect requires `identity` or `auth`");
     const classHash = opts.classHash ?? DEVICE_ACCOUNT_CLASS_HASH[opts.network];
@@ -740,7 +1354,7 @@ var Cavos = class _Cavos {
       cairoVersion: "1"
     });
     const backendUrl = opts.backendUrl ?? "https://cavos.xyz";
-    const registry = opts.registry ?? (opts.appId ? new HttpWalletRegistry({ baseUrl: backendUrl, appId: opts.appId, network: opts.network }) : defaultRegistry);
+    const registry = opts.registry ?? (opts.appId ? new HttpWalletRegistry({ baseUrl: backendUrl, appId: opts.appId, network: opts.network }) : defaultRegistry2);
     const recovery = opts.recovery ?? (opts.appId ? new HttpRecoveryClient({ baseUrl: backendUrl, appId: opts.appId }) : null);
     const existing = await registry.lookup(identity.userId);
     if (existing) {
@@ -858,13 +1472,14 @@ var Cavos = class _Cavos {
    * re-derive the backup key. The backend never sees the code.
    */
   static async recover(opts) {
-    const classHash = opts.classHash ?? DEVICE_ACCOUNT_CLASS_HASH[opts.network];
-    if (!classHash) throw new Error(`kit: no DeviceAccount class hash for ${opts.network}`);
+    const network = STARKNET_ENV[opts.network];
+    const classHash = opts.classHash ?? DEVICE_ACCOUNT_CLASS_HASH[network];
+    if (!classHash) throw new Error(`kit: no DeviceAccount class hash for ${network}`);
     const provider = new starknet.RpcProvider({
-      nodeUrl: opts.rpcUrl ?? STARKNET_NETWORKS[opts.network].rpcUrl
+      nodeUrl: opts.rpcUrl ?? STARKNET_NETWORKS[network].rpcUrl
     });
     const paymaster = new starknet.PaymasterRpc({
-      nodeUrl: opts.paymasterUrl ?? CAVOS_PAYMASTER_URL[opts.network],
+      nodeUrl: opts.paymasterUrl ?? CAVOS_PAYMASTER_URL[network],
       headers: { "x-paymaster-api-key": opts.paymasterApiKey }
     });
     const signer = opts.createSigner ? await opts.createSigner(`${opts.identity.userId}:${opts.appSalt}`) : await WebCryptoSigner.loadOrCreate({ keyId: `${opts.identity.userId}:${opts.appSalt}` });
@@ -872,7 +1487,7 @@ var Cavos = class _Cavos {
     const backup = BackupSigner.fromCode(opts.code);
     const backupAdapter = new StarknetAdapter({ classHash, signer: backup, provider });
     const backendUrl = opts.backendUrl ?? "https://cavos.xyz";
-    const registry = opts.registry ?? (opts.appId ? new HttpWalletRegistry({ baseUrl: backendUrl, appId: opts.appId, network: opts.network }) : defaultRegistry);
+    const registry = opts.registry ?? (opts.appId ? new HttpWalletRegistry({ baseUrl: backendUrl, appId: opts.appId, network }) : defaultRegistry2);
     const existing = await registry.lookup(opts.identity.userId);
     if (!existing) {
       throw new Error("kit: no account found for this identity \u2014 nothing to recover");
@@ -907,7 +1522,7 @@ var Cavos = class _Cavos {
     return new _Cavos(opts.identity, existing.address, "ready", account, adapter, devicePubkey);
   }
 };
-var defaultRegistry = new InMemoryWalletRegistry();
+var defaultRegistry2 = new InMemoryWalletRegistry();
 var DEVICE_REQUEST_DEDUP_MS = 5 * 60 * 1e3;
 var lastDeviceRequest = /* @__PURE__ */ new Map();
 async function isDeployed(provider, address) {
@@ -1844,7 +2459,7 @@ function CavosProvider({ config, modal, children }) {
   const closeModal = react.useCallback(() => setModalOpen(false), []);
   const clearAuthError = react.useCallback(() => setAuthError(null), []);
   const resendDeviceApproval = react.useCallback(async () => {
-    if (!identity || !cavos || !cavos.pendingRequestId) return;
+    if (!identity || !cavos || cavos.chain !== "starknet" || !cavos.pendingRequestId) return;
     const backendUrl = configRef.current.authBackendUrl ?? "https://cavos.xyz";
     if (!configRef.current.appId) return;
     const recovery = new HttpRecoveryClient({ baseUrl: backendUrl, appId: configRef.current.appId });
@@ -1858,22 +2473,24 @@ function CavosProvider({ config, modal, children }) {
   const connect = react.useCallback(async (id) => {
     setWalletStatus({ ...INITIAL_STATUS, isDeploying: true });
     const c = await Cavos.connect({
+      chain: configRef.current.chain ?? "starknet",
       network: configRef.current.network,
       identity: id,
       appSalt: configRef.current.appSalt,
-      paymasterApiKey: configRef.current.paymasterApiKey,
+      ...configRef.current.paymasterApiKey ? { paymasterApiKey: configRef.current.paymasterApiKey } : {},
       ...configRef.current.appId ? { appId: configRef.current.appId } : {},
       ...configRef.current.authBackendUrl ? { backendUrl: configRef.current.authBackendUrl } : {},
       ...configRef.current.rpcUrl ? { rpcUrl: configRef.current.rpcUrl } : {}
     });
     setCavos(c);
     setIdentity(id);
+    const pendingRequestId = c.chain === "starknet" ? c.pendingRequestId : null;
     setWalletStatus({
       isDeploying: false,
       isReady: c.status === "ready",
       needsDeviceApproval: c.status === "needs-device-approval",
-      awaitingApproval: c.status === "needs-device-approval" && !!c.pendingRequestId,
-      pendingRequestId: c.pendingRequestId
+      awaitingApproval: c.status === "needs-device-approval" && !!pendingRequestId,
+      pendingRequestId
     });
     modal?.onSuccess?.(c.address);
     return c;
@@ -1929,11 +2546,19 @@ function CavosProvider({ config, modal, children }) {
   }, [auth, connect]);
   const execute = react.useCallback(async (calls) => {
     if (!cavos) throw new Error("Not logged in");
+    if (cavos.chain !== "starknet") {
+      throw new Error(
+        "kit: useCavos().execute(calls) is Starknet-only. On Solana use the `wallet` handle: wallet.execute(amount, dest)."
+      );
+    }
     return cavos.execute(calls);
   }, [cavos]);
   const addSigner = react.useCallback(
     async (pubkey) => {
       if (!cavos) throw new Error("Not logged in");
+      if (cavos.chain !== "starknet") {
+        throw new Error("kit: addSigner via useCavos() is Starknet-only; use the `wallet` handle on Solana.");
+      }
       return cavos.addSigner(pubkey);
     },
     [cavos]
@@ -1949,12 +2574,21 @@ function CavosProvider({ config, modal, children }) {
     setAuthError(null);
     setWalletStatus({ ...INITIAL_STATUS, isDeploying: true });
     try {
-      const c = await Cavos.recover({
+      const chain = configRef.current.chain ?? "starknet";
+      const c = chain === "solana" ? await CavosSolana.recover({
+        code,
+        identity,
+        network: configRef.current.network === "mainnet" ? "solana-mainnet" : "solana-devnet",
+        appSalt: configRef.current.appSalt,
+        ...configRef.current.appId ? { appId: configRef.current.appId } : {},
+        ...configRef.current.authBackendUrl ? { backendUrl: configRef.current.authBackendUrl } : {},
+        ...configRef.current.rpcUrl ? { rpcUrl: configRef.current.rpcUrl } : {}
+      }) : await Cavos.recover({
         code,
         identity,
         network: configRef.current.network,
         appSalt: configRef.current.appSalt,
-        paymasterApiKey: configRef.current.paymasterApiKey,
+        paymasterApiKey: configRef.current.paymasterApiKey ?? "",
         ...configRef.current.appId ? { appId: configRef.current.appId } : {},
         ...configRef.current.authBackendUrl ? { backendUrl: configRef.current.authBackendUrl } : {},
         ...configRef.current.rpcUrl ? { rpcUrl: configRef.current.rpcUrl } : {}
@@ -2007,6 +2641,8 @@ function CavosProvider({ config, modal, children }) {
     closeModal,
     isAuthenticated: !!cavos,
     user: identity ? { userId: identity.userId, email: identity.email, provider: identity.provider } : null,
+    chain: config.chain ?? "starknet",
+    wallet: cavos,
     address: cavos?.address ?? null,
     walletStatus,
     isLoading,