@veil-cash/sdk 0.2.0 → 0.3.0

package/src/keypair.ts

@@ -4,9 +4,22 @@
  */
 
 import { ethers } from 'ethers';
+import { privateKeyToAccount } from 'viem/accounts';
 import { poseidonHash, toFixedHex } from './utils.js';
 import type { EncryptedMessage } from './types.js';
 
+/**
+ * Canonical message signed by a wallet to derive a Veil keypair.
+ * Must match the frontend's SIGNED_MESSAGE in data/wallet/config.ts.
+ */
+export const VEIL_SIGNED_MESSAGE = "Sign this message to create your Veil Wallet private key. This will be used to decrypt your balances. Ensure you are signing this message on the Veil Cash website.";
+
+/**
+ * Any async function that performs EIP-191 personal_sign and returns a 0x-prefixed signature.
+ * Used with Keypair.fromSigner() to support external signing services.
+ */
+export type MessageSigner = (message: string) => Promise<string>;
+
 // eth-sig-util for x25519 encryption
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const ethSigUtil = require('eth-sig-util');
@@ -125,6 +138,72 @@ export class Keypair {
     });
   }
 
+  /**
+   * Derive a Keypair from an EIP-191 personal_sign signature.
+   * The private key is keccak256(signature) -- matching the frontend derivation.
+   * 
+   * @param signature - Raw ECDSA signature (0x-prefixed, 132 hex chars)
+   * @returns Keypair derived from the signature
+   * 
+   * @example
+   * ```typescript
+   * const keypair = Keypair.fromSignature(signature);
+   * ```
+   */
+  static fromSignature(signature: string): Keypair {
+    const privkey = ethers.keccak256(signature);
+    return new Keypair(privkey);
+  }
+
+  /**
+   * Derive a Keypair from an Ethereum wallet private key.
+   * Signs VEIL_SIGNED_MESSAGE with the wallet, then derives via keccak256(signature).
+   * Produces the same keypair as the frontend for the same wallet.
+   * 
+   * @param walletPrivateKey - Ethereum EOA private key (0x-prefixed)
+   * @returns Promise resolving to the derived Keypair
+   * 
+   * @example
+   * ```typescript
+   * const keypair = await Keypair.fromWalletKey('0xYOUR_WALLET_PRIVATE_KEY');
+   * console.log(keypair.depositKey()); // Same as frontend login with this wallet
+   * ```
+   */
+  static async fromWalletKey(walletPrivateKey: `0x${string}`): Promise<Keypair> {
+    const account = privateKeyToAccount(walletPrivateKey);
+    const signature = await account.signMessage({ message: VEIL_SIGNED_MESSAGE });
+    return Keypair.fromSignature(signature);
+  }
+
+  /**
+   * Derive a Keypair using any external signer that supports personal_sign (EIP-191).
+   * The signer function receives VEIL_SIGNED_MESSAGE and must return a 0x-prefixed signature.
+   * Works with any signing backend: Bankr, MPC wallets, custodial services, hardware wallets, etc.
+   * 
+   * @param signer - Async function that signs a message and returns a 0x-prefixed signature
+   * @returns Promise resolving to the derived Keypair
+   * 
+   * @example
+   * ```typescript
+   * // With Bankr
+   * const keypair = await Keypair.fromSigner(async (message) => {
+   *   const res = await fetch('https://api.bankr.bot/agent/sign', {
+   *     method: 'POST',
+   *     headers: { 'X-API-Key': apiKey, 'Content-Type': 'application/json' },
+   *     body: JSON.stringify({ signatureType: 'personal_sign', message }),
+   *   });
+   *   return (await res.json()).signature;
+   * });
+   * 
+   * // With any custom signer
+   * const keypair = await Keypair.fromSigner(async (msg) => myService.personalSign(msg));
+   * ```
+   */
+  static async fromSigner(signer: MessageSigner): Promise<Keypair> {
+    const signature = await signer(VEIL_SIGNED_MESSAGE);
+    return Keypair.fromSignature(signature);
+  }
+
   /**
    * Sign a message using the private key
    * @param commitment - Commitment hash

package/src/relay.ts

@@ -98,8 +98,8 @@ export async function submitRelay(options: SubmitRelayOptions): Promise<RelayRes
     throw new RelayError('Invalid type. Must be "withdraw" or "transfer"', 400);
   }
 
-  if (pool !== 'eth' && pool !== 'usdc') {
-    throw new RelayError('Invalid pool. Must be "eth" or "usdc"', 400);
+  if (pool !== 'eth' && pool !== 'usdc' && pool !== 'cbbtc') {
+    throw new RelayError('Invalid pool. Must be "eth", "usdc", or "cbbtc"', 400);
   }
 
   if (!proofArgs || !extData) {

package/src/transfer.ts

@@ -5,7 +5,7 @@
 
 import { createPublicClient, http, parseUnits } from 'viem';
 import { base } from 'viem/chains';
-import { getAddresses, POOL_CONFIG } from './addresses.js';
+import { getAddresses, getPoolAddress, POOL_CONFIG } from './addresses.js';
 import { POOL_ABI, ENTRY_ABI } from './abi.js';
 import { Keypair } from './keypair.js';
 import { Utxo } from './utxo.js';
@@ -17,6 +17,7 @@ import type {
   BuildTransferProofOptions, 
   ProofBuildResult, 
   TransferResult,
+  RelayPool,
 } from './types.js';
 
 /**
@@ -137,13 +138,13 @@ export async function buildTransferProof(
     amount,
     recipientAddress,
     senderKeypair,
+    pool = 'eth',
     rpcUrl,
     onProgress,
   } = options;
 
-  const addresses = getAddresses();
-  const poolConfig = POOL_CONFIG.eth;
-  const poolAddress = addresses.ethPool;
+  const poolConfig = POOL_CONFIG[pool];
+  const poolAddress = getPoolAddress(pool);
 
   // 1. Check recipient is registered and get their deposit key
   onProgress?.('Checking recipient registration...');
@@ -160,6 +161,7 @@ export async function buildTransferProof(
   onProgress?.('Fetching your UTXOs...');
   const balanceResult = await getPrivateBalance({
     keypair: senderKeypair,
+    pool,
     rpcUrl,
     onProgress,
   });
@@ -283,7 +285,7 @@ export async function buildTransferProof(
 export async function transfer(
   options: BuildTransferProofOptions
 ): Promise<TransferResult> {
-  const { amount, recipientAddress, onProgress } = options;
+  const { amount, recipientAddress, pool = 'eth', onProgress } = options;
 
   // Build the proof
   const proof = await buildTransferProof(options);
@@ -292,7 +294,7 @@ export async function transfer(
   onProgress?.('Submitting to relay...');
   const relayResult = await submitRelay({
     type: 'transfer',
-    pool: 'eth',
+    pool,
     proofArgs: proof.proofArgs,
     extData: proof.extData,
     metadata: {
@@ -334,19 +336,20 @@ export async function transfer(
 export async function mergeUtxos(options: {
   amount: string;
   keypair: Keypair;
+  pool?: RelayPool;
   rpcUrl?: string;
   onProgress?: (stage: string, detail?: string) => void;
 }): Promise<TransferResult> {
-  const { amount, keypair, rpcUrl, onProgress } = options;
+  const { amount, keypair, pool = 'eth', rpcUrl, onProgress } = options;
 
-  const addresses = getAddresses();
-  const poolConfig = POOL_CONFIG.eth;
-  const poolAddress = addresses.ethPool;
+  const poolConfig = POOL_CONFIG[pool];
+  const poolAddress = getPoolAddress(pool);
 
   // 1. Get sender's unspent UTXOs
   onProgress?.('Fetching your UTXOs...');
   const balanceResult = await getPrivateBalance({
     keypair,
+    pool,
     rpcUrl,
     onProgress,
   });
@@ -435,7 +438,7 @@ export async function mergeUtxos(options: {
   onProgress?.('Submitting to relay...');
   const relayResult = await submitRelay({
     type: 'transfer',
-    pool: 'eth',
+    pool,
     proofArgs: {
       proof: result.args.proof,
       root: result.args.root,

package/src/types.ts

@@ -5,7 +5,7 @@
 /**
  * Supported tokens
  */
-export type Token = 'ETH' | 'USDC';
+export type Token = 'ETH' | 'USDC' | 'CBBTC';
 
 /**
  * Encrypted message format (x25519-xsalsa20-poly1305)
@@ -27,6 +27,9 @@ export interface NetworkAddresses {
   usdcPool: `0x${string}`;
   usdcQueue: `0x${string}`;
   usdcToken: `0x${string}`;
+  cbbtcPool: `0x${string}`;
+  cbbtcQueue: `0x${string}`;
+  cbbtcToken: `0x${string}`;
   chainId: number;
   relayUrl: string;
 }
@@ -118,7 +121,7 @@ export interface PrivateBalanceResult {
 /**
  * Pool type for relay operations
  */
-export type RelayPool = 'eth' | 'usdc';
+export type RelayPool = 'eth' | 'usdc' | 'cbbtc';
 
 /**
  * Type of relay transaction
@@ -223,6 +226,8 @@ export interface BuildWithdrawProofOptions {
   recipient: `0x${string}`;
   /** User's keypair for signing */
   keypair: import('./keypair.js').Keypair;
+  /** Pool to withdraw from (default: 'eth') */
+  pool?: RelayPool;
   /** Optional RPC URL */
   rpcUrl?: string;
   /** Progress callback */
@@ -239,6 +244,8 @@ export interface BuildTransferProofOptions {
   recipientAddress: `0x${string}`;
   /** Sender's keypair */
   senderKeypair: import('./keypair.js').Keypair;
+  /** Pool to transfer in (default: 'eth') */
+  pool?: RelayPool;
   /** Optional RPC URL */
   rpcUrl?: string;
   /** Progress callback */

package/src/withdraw.ts

@@ -5,7 +5,7 @@
 
 import { createPublicClient, http, parseUnits, formatUnits } from 'viem';
 import { base } from 'viem/chains';
-import { getAddresses, POOL_CONFIG } from './addresses.js';
+import { getPoolAddress, POOL_CONFIG } from './addresses.js';
 import { POOL_ABI } from './abi.js';
 import { Keypair } from './keypair.js';
 import { Utxo } from './utxo.js';
@@ -143,18 +143,19 @@ export async function buildWithdrawProof(
     amount,
     recipient,
     keypair,
+    pool = 'eth',
     rpcUrl,
     onProgress,
   } = options;
 
-  const addresses = getAddresses();
-  const poolConfig = POOL_CONFIG.eth;
-  const poolAddress = addresses.ethPool;
+  const poolConfig = POOL_CONFIG[pool];
+  const poolAddress = getPoolAddress(pool);
 
   // 1. Get user's unspent UTXOs
   onProgress?.('Fetching your UTXOs...');
   const balanceResult = await getPrivateBalance({
     keypair,
+    pool,
     rpcUrl,
     onProgress,
   });
@@ -269,7 +270,7 @@ export async function buildWithdrawProof(
 export async function withdraw(
   options: BuildWithdrawProofOptions
 ): Promise<WithdrawResult> {
-  const { amount, recipient, onProgress } = options;
+  const { amount, recipient, pool = 'eth', onProgress } = options;
 
   // Build the proof
   const proof = await buildWithdrawProof(options);
@@ -278,7 +279,7 @@ export async function withdraw(
   onProgress?.('Submitting to relay...');
   const relayResult = await submitRelay({
     type: 'withdraw',
-    pool: 'eth',
+    pool,
     proofArgs: proof.proofArgs,
     extData: proof.extData,
     metadata: {