Jelli Core 🔐

Multi-chain wallet management made simple

Platform-agnostic cryptographic utilities for Jelli applications. A solid, TypeScript-first library for HD wallet operations, private key management, and blockchain interactions across Bitcoin, Ethereum, Solana, and Base.

🌐 Works everywhere: Node.js, Web Browsers, React Native, and any JavaScript environment.

What is Jelli Core?

@iheartsolana/jelli-core is our production-ready TypeScript library that handles all the complex crypto operations so you can focus on building amazing wallet experiences. It's the foundation powering wallet operations across our entire ecosystem.

✨ What it does:

• 🔐 Complete Wallet Management - HD wallets, private key imports, account derivation
• ⛓️ Multi-Chain Support - Bitcoin, Ethereum, Solana, Base out of the box
• 🧬 BIP39/BIP44 Compliant - Industry-standard HD wallet operations
• 🔑 Private Key Import - Import accounts from any valid private key
• 📝 Structured Logging - Production-ready logging with caller information
• 🧪 Interactive Testing - Comprehensive test program for all features
• 🎯 100% Phantom Compatible - Generates identical addresses to Phantom Wallet (verified across 20+ test cases)
• 🌐 Platform Agnostic - Dependency injection pattern works in any JavaScript environment

🚀 What makes it special:

• 100% Phantom Compatible - Verified identical address generation across all chains
• Professional Grade - Matches Phantom/MetaMask architecture patterns
• Developer Friendly - Clean APIs with excellent TypeScript support
• Battle Tested - 235 passing tests with comprehensive Phantom compatibility validation
• Platform Agnostic - Works in Node.js, browsers, React Native via dependency injection
• Zero Platform Dependencies - Core library is environment-neutral

🎯 Phantom Compatibility Achievement

✅ VERIFIED: 100% Address Matching with Phantom Wallet

Jelli Core has been extensively tested and generates identical addresses to Phantom Wallet for all supported chains:

| Test Results | Status | |--------------|--------| | Solana Addresses | ✅ 5/5 Perfect Matches | | Ethereum Addresses | ✅ 5/5 Perfect Matches |
| Bitcoin Addresses | ✅ 5/5 Perfect Matches | | Base Addresses | ✅ 5/5 Perfect Matches | | Total Verification | ✅ 20/20 Perfect Matches |

This means you can:

• Import any Phantom wallet into Jelli applications
• Export any Jelli wallet to Phantom
• Generate identical addresses for the same mnemonic + account index
• Achieve perfect interoperability between Jelli and Phantom ecosystems

⚡ Core Features

🏗️ Wallet Management Architecture

• HD Wallets - BIP39/BIP44 compliant hierarchical deterministic wallets
• Multi-Wallet Support - Create multiple wallets from the same seed phrase using wallet indices
• Private Key Import - Import standalone accounts from private keys
• Unified Account View - Seamlessly combine HD and imported accounts

⛓️ Multi-Chain Support

• Bitcoin - Native SegWit (P2WPKH) with bech32 addresses (bc1q...)
• Ethereum - Standard BIP44 derivation with EIP-55 checksums
• Solana - Ed25519 SLIP-0010 derivation with base58 addresses
• Base - Coinbase Layer 2 with Ethereum-compatible derivation

🔑 Private Key Management

• Format Validation - Supports hex, base58, and prefixed formats per chain
• Secure Storage - Encrypted private key storage with platform-specific vaults
• Duplicate Prevention - Prevents importing the same account twice
• Address Derivation - Accurate address generation from private keys

🔐 Advanced Security Features

• Phantom-Style Architecture - Proven distributed key management (used by Phantom wallet)
• Seed-Based Entropy - Generate wallets from cryptographically secure seed bytes (not just mnemonics)
• AEAD Encryption - ChaCha20-Poly1305 authenticated encryption for seed/mnemonic protection
• Shamir's Secret Sharing - Split encryption keys using 2-of-2 threshold schemes
• Distributed Trust Model - No single party can recover wallet alone
• OPRF PIN Protection - Cryptographically secure PIN verification via Juicebox
• Zero Permanent Storage - Device never stores full seed, mnemonic, or encryption key
• Backward Compatibility - Supports both legacy mnemonic-based and modern seed-based wallets

🧪 Developer Experience

• Interactive Test Program - Full-featured testing interface (npm run test:interactive)
• TypeScript First - Complete type safety with comprehensive interfaces
• Comprehensive Testing - 90%+ test coverage with edge case handling
• Clean APIs - Intuitive method names with consistent error handling
• Educational Examples - Production workflows and security demonstrations

Installation

npm install @iheartsolana/jelli-core

🌐 Platform Setup

Jelli Core uses dependency injection to work across all JavaScript environments. You must provide a crypto adapter for your platform:

🖥️ Node.js Setup

import { setCryptoAdapter } from '@iheartsolana/jelli-core';

// Create Node.js crypto adapter
const crypto = require('crypto');
setCryptoAdapter({
  randomBytes: (size) => crypto.randomBytes(size),
  createCipheriv: (algorithm, key, iv) => {
    const cipher = crypto.createCipheriv(algorithm, key, iv);
    return {
      update: (data) => cipher.update(data),
      final: () => cipher.final(),
      getAuthTag: () => cipher.getAuthTag()
    };
  },
  createDecipheriv: (algorithm, key, iv) => {
    const decipher = crypto.createDecipheriv(algorithm, key, iv);
    return {
      setAuthTag: (tag) => decipher.setAuthTag(tag),
      update: (data) => decipher.update(data),
      final: () => decipher.final()
    };
  }
});

🌐 Web Browser Setup

import { setCryptoAdapter } from '@iheartsolana/jelli-core';
// Install: npm install @noble/ciphers

const { chacha20poly1305 } = require('@noble/ciphers/chacha');

setCryptoAdapter({
  randomBytes: (size) => {
    const array = new Uint8Array(size);
    crypto.getRandomValues(array);
    return Buffer.from(array);
  },
  // ... implement createCipheriv and createDecipheriv using @noble/ciphers
  // See examples/crypto/web-crypto-adapter.ts for complete implementation
});

📱 React Native Setup

// Using @iheartsolana/jelli-wallet-sdk (recommended)
import { JelliConfig } from '@iheartsolana/jelli-wallet-sdk';

// Crypto adapter is initialized automatically!
JelliConfig.initialize({ ... });

Manual React Native Setup:

import { setCryptoAdapter } from '@iheartsolana/jelli-core';
import { createReactNativeCryptoAdapter } from '@iheartsolana/jelli-wallet-sdk';

setCryptoAdapter(createReactNativeCryptoAdapter());

🔧 Dependency Injection Architecture

Jelli Core uses dependency injection to remain platform-agnostic. This means:

✅ What Jelli Core Provides:

• 🧬 HD wallet logic and BIP39/BIP44 compliance
• 🔑 Private key derivation and management
• 📊 Multi-chain address generation
• 🏗️ Wallet management abstractions
• 📝 TypeScript interfaces and types

🔌 What You Provide (via Dependency Injection):

• 🔐 Crypto Adapter: Platform-specific encryption implementation
• 💾 Storage Adapters: Platform-specific storage (optional - defaults to in-memory)

🎯 Benefits:

• 🌐 Universal Compatibility: Works in any JavaScript environment
• 🔒 Security: No platform-specific vulnerabilities in core
• 🧪 Testability: Easy to mock dependencies for testing
• 📦 Bundle Size: No unused platform code in your bundles
• 🔄 Flexibility: Swap implementations without changing core logic

🏗️ HD Wallet Architecture (Phantom Compatible)

Understanding the Phantom-compatible account derivation system:

HD Wallet System (Phantom Compatible - Account Index Based)
├── 📝 Mnemonic Phrase (ROOT)
│   └── 🔑 Master Private Key (derived from mnemonic)
│       └── 🌳 Single Wallet (walletIndex=0) - Phantom Standard
│           ├── 🔑 Bitcoin Account 0: m/84'/0'/0'/0/0
│           ├── 🔑 Bitcoin Account 1: m/84'/0'/0'/0/1
│           ├── 🔑 Bitcoin Account 2: m/84'/0'/0'/0/2
│           ├── 🔑 Ethereum Account 0: m/44'/60'/0'/0/0
│           ├── 🔑 Ethereum Account 1: m/44'/60'/0'/0/1
│           ├── 🔑 Ethereum Account 2: m/44'/60'/0'/0/2
│           ├── 🔑 Solana Account 0: m/44'/501'/0'/0'
│           ├── 🔑 Solana Account 1: m/44'/501'/1'/0'
│           ├── 🔑 Solana Account 2: m/44'/501'/2'/0'
│           └── 🔑 ... (infinite accounts per chain)

Key Concepts (Phantom Compatible):

• One Mnemonic → One Wallet → Infinite Accounts per Chain
• Account Index creates multiple accounts for each blockchain (like Phantom)
• Wallet Index always 0 for Phantom compatibility
• Each Account has its own unique private key and address
• Backup Mnemonic = backup ALL accounts across all chains (current + future)
• Export Individual Key = just that one specific account
• 100% Phantom Compatible - identical addresses for same mnemonic + account index

Import Methods:

| HD Wallet Import (Phantom Compatible) | Individual Account Import | |---------------------|------------------------------| | Input: Mnemonic phrase (12-24 words) | Input: Private key (hex/base58) | | Result: Recreates entire account structure for all chains | Result: Single standalone account | | Use: importWallet(name, mnemonic) | Use: importAccount(name, privateKey, chain) | | Backup: One phrase backs up ALL accounts across all chains | Backup: Each key must be backed up separately | | Compatibility: 100% Phantom compatible addresses | Limitation: No derivation, just single account |

Phantom Compatible Examples:

// Import wallet with Phantom-compatible derivation
await manager.importWallet('My Phantom Wallet', mnemonic);

// Derive multiple accounts (like Phantom's "Create Account" feature)
const account0 = await manager.deriveAccount(walletId, ChainType.Ethereum, 0);
const account1 = await manager.deriveAccount(walletId, ChainType.Ethereum, 1);
const account2 = await manager.deriveAccount(walletId, ChainType.Ethereum, 2);

// All addresses will match Phantom exactly! ✅

🚀 Quick Start

Complete Wallet Manager Example

import { 
  HDWalletEngine, 
  WalletManager, 
  InMemoryWalletStore, 
  InMemorySecretVault,
  ChainType,
  setCryptoAdapter
} from '@iheartsolana/jelli-core';

// Step 1: Set up crypto adapter (required!)
const crypto = require('crypto');
setCryptoAdapter({
  randomBytes: (size) => crypto.randomBytes(size),
  createCipheriv: (algorithm, key, iv) => {
    const cipher = crypto.createCipheriv(algorithm, key, iv);
    return {
      update: (data) => cipher.update(data),
      final: () => cipher.final(),
      getAuthTag: () => cipher.getAuthTag()
    };
  },
  createDecipheriv: (algorithm, key, iv) => {
    const decipher = crypto.createDecipheriv(algorithm, key, iv);
    return {
      setAuthTag: (tag) => decipher.setAuthTag(tag),
      update: (data) => decipher.update(data),
      final: () => decipher.final()
    };
  }
});

// Step 2: Initialize the complete wallet system
const engine = new HDWalletEngine();
const store = new InMemoryWalletStore();
const vault = new InMemorySecretVault();
const walletManager = new WalletManager(engine, store, vault);

// Create a new HD wallet (auto-derives accounts for all chains)
const result = await walletManager.createWallet('My Main Wallet');
if (result.success) {
  console.log('✅ Wallet created:', result.wallet?.name);
  console.log('⚠️  Backup this mnemonic:', result.mnemonic);
  
  // List all derived accounts
  const accounts = await walletManager.listAccounts(result.wallet!.id);
  accounts.forEach(acc => {
    console.log(`${acc.chainType}: ${acc.address}`);
  });
}

// Import an account from private key
const importResult = await walletManager.importAccount(
  'Trading Account',
  '0xa1b2c3d4e5f6...', // Your private key
  ChainType.Ethereum
);

if (importResult.success) {
  console.log('✅ Account imported:', importResult.account?.address);
}

// Get unified view of all accounts (HD + imported)
const allAccounts = await walletManager.getAllAccounts(result.wallet?.id);
console.log(`Total accounts: ${allAccounts.length}`);
allAccounts.forEach(acc => {
  console.log(`${acc.name} (${acc.type}): ${acc.address}`);
});

Engine-Only Usage (Lower Level)

import { HDWalletEngine, ChainType } from '@iheartsolana/jelli-core';

const engine = new HDWalletEngine();

// Create wallet and derive specific accounts
const result = await engine.createWallet('My Wallet');
if (result.success && result.mnemonic) {
  // Derive Solana account at index 1
  const account = await engine.deriveAccount({
    mnemonic: result.mnemonic,
    chain: ChainType.Solana,
    accountIndex: 1,
    includePrivateKey: true
  });
  
  if (account.success) {
    console.log('Solana account:', account.account?.address);
  }
}

🎯 Phantom Compatibility

Jelli Core generates 100% identical addresses to Phantom Wallet for all supported chains:

Seed-Based Derivation (Phantom Architecture)

import { HDWalletEngine, generateSeedBytes } from '@iheartsolana/jelli-core';
import { mnemonicToSeed } from '@scure/bip39';

const engine = new HDWalletEngine();

// Method 1: Generate from mnemonic (same as Phantom)
const mnemonic = 'nice invite flip artwork april enable ancient juice mesh maid crash ozone';
const seedUint8Array = await mnemonicToSeed(mnemonic, ''); // Empty passphrase
const seedBytes = Buffer.from(seedUint8Array);

// Method 2: Generate cryptographically secure seed bytes directly
const seedBytes = generateSeedBytes(32); // 256-bit entropy

// Derive accounts using seed bytes (Phantom's approach)
const solanaAccount = await engine.deriveAccountFromSeed({
  seedBytes,
  chain: 'solana',
  accountIndex: 0,
  walletIndex: 0
});

const ethereumAccount = await engine.deriveAccountFromSeed({
  seedBytes,
  chain: 'ethereum', 
  accountIndex: 0,
  walletIndex: 0
});

const bitcoinAccount = await engine.deriveAccountFromSeed({
  seedBytes,
  chain: 'bitcoin',
  accountIndex: 0,
  walletIndex: 0
});

// All addresses will match Phantom exactly! ✅

Address Generation Results

For the test mnemonic: nice invite flip artwork april enable ancient juice mesh maid crash ozone

| Chain | Our Address | Phantom Address | Match | |-------|-------------|-----------------|-------| | Solana | 7NDRginhpnMhcyjM4EBRnW6MTVzFk4NkfU4RHj8VmJ9E | 7NDRginhpnMhcyjM4EBRnW6MTVzFk4NkfU4RHj8VmJ9E | ✅ | | Ethereum | 0x0aeac0472eeebf3100c9b7d6cf03cb9cc3ce0e42 | 0x0aeac0472eeebf3100c9b7d6cf03cb9cc3ce0e42 | ✅ | | Bitcoin | bc1qvzgwl62wxrn2a3nke5qa038j9avp0779rcdftv | bc1qvzgwl62wxrn2a3nke5qa038j9avp0779rcdftv | ✅ | | Base | 0x0aeac0472eeebf3100c9b7d6cf03cb9cc3ce0e42 | 0x0aeac0472eeebf3100c9b7d6cf03cb9cc3ce0e42 | ✅ |

🔐 Security & Encryption

Phantom-Style Distributed Key Management

Jelli Core implements Phantom's proven architecture for secure, distributed mnemonic protection:

🔐 Phantom Security Model (2-of-2 Architecture)
┌─────────────────────────────────────────────────────────────────┐
│  PRIMARY FLOW (New Wallet Creation):                           │
│  1. Device generates BIP39 mnemonic (12-24 words)              │
│  2. Device converts mnemonic → seed bytes (32 bytes)           │
│  3. Device encrypts MNEMONIC with 32-byte key (ChaCha20-Poly1305) │
│  4. Device splits ENCRYPTION KEY into 2 shares (Shamir's SSS)  │
│  5. Distribution:                                               │
│     • Jelli Backend: encrypted mnemonic + key share #1         │
│     • Juicebox: key share #2 (PIN-gated via OPRF)             │
│  6. Device: stores nothing permanently                          │
│                                                                 │
│  RECOVERY FLOW (Import Existing Wallet):                       │
│  1. User enters existing mnemonic phrase                       │
│  2. Device encrypts MNEMONIC with 32-byte key                  │
│  3. Continue with steps 4-6 from primary flow                  │
└─────────────────────────────────────────────────────────────────┘

🛡️ Security Guarantees

• ✅ Jelli backend alone: CANNOT decrypt (has ciphertext + 1 share, needs 2)
• ✅ Juicebox alone: CANNOT decrypt (has 1 share, no ciphertext)
• ✅ User with OAuth + PIN: CAN decrypt (gets both shares + ciphertext)
• ✅ OPRF Protection: PIN is cryptographically protected, not stored in plaintext

Implementation Example

import { 
  encryptAndSplitMnemonic, 
  reconstructAndDecryptMnemonic,
  HDWalletEngine 
} from '@iheartsolana/jelli-core';

// === PRIMARY FLOW: NEW WALLET CREATION (Phantom Architecture) ===

const engine = new HDWalletEngine();

// Step 1: Generate BIP39 mnemonic (like Phantom)
const walletResult = await engine.createWallet('My Wallet');
const mnemonic = walletResult.mnemonic; // 12-24 word BIP39 phrase

// Step 2: Encrypt mnemonic and split encryption key (2-of-2)
const result = await encryptAndSplitMnemonic(mnemonic, {
  threshold: 2,
  totalShares: 2  // Phantom's 2-of-2 architecture
});

// Step 3: Distribute securely
const encryptedMnemonic = result.encrypted;       // → Jelli Backend
const jelliKeyShare = result.keyShares.shares[0]; // → Jelli Backend
const juiceboxKeyShare = result.keyShares.shares[1]; // → Juicebox (PIN-gated)

// Step 4: Device clears all sensitive data
// (No permanent storage of mnemonic or full encryption key)

// === RECOVERY FLOW: IMPORT EXISTING WALLET ===

// User imports existing mnemonic
const existingMnemonic = 'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about';

// Encrypt and distribute same as primary flow
const importResult = await encryptAndSplitMnemonic(existingMnemonic, {
  threshold: 2,
  totalShares: 2
});

// === WALLET RECOVERY (Cross-Device) ===
// User signs in with OAuth (gets encrypted mnemonic + Jelli's key share)
// User enters PIN (gets Juicebox's key share via OPRF)

const recovered = await reconstructAndDecryptMnemonic(
  encryptedMnemonic,                    // From Jelli backend
  [jelliKeyShare, juiceboxKeyShare],    // From both sources
  2 // threshold
);

if (recovered.success && recovered.mnemonic) {
  console.log('🎉 Mnemonic recovered! Wallet can be restored.');
  
  // Now derive accounts from recovered mnemonic (Phantom compatible)
  const account = await engine.deriveAccount({
    mnemonic: recovered.mnemonic,
    chain: 'ethereum',
    accountIndex: 0  // Phantom-compatible account indexing
  });
}

Security Features

ChaCha20-Poly1305 AEAD Encryption

• Confidentiality: ChaCha20 stream cipher encrypts the mnemonic
• Integrity: Poly1305 MAC prevents tampering
• Performance: Used by Signal, WireGuard, TLS 1.3
• Standards: RFC 7539 compliant
• Key Size: 256-bit encryption keys

Shamir's Secret Sharing (Key Splitting)

• Threshold Security: 2-of-2 scheme (both shares required)
• Information-Theoretic Security: 1 share reveals nothing about the key
• Perfect Secrecy: Mathematically unbreakable
• Share Size: ~33 bytes (perfect for Juicebox storage)
• Audited Library: Uses shamir-secret-sharing npm package

Distributed Trust Model

• No Single Point of Failure: No entity can decrypt alone
• User Sovereignty: Only user with OAuth + PIN can recover
• Cross-Device Recovery: Works seamlessly on new devices
• PIN Protection: Threshold OPRF prevents brute force attacks

🎯 Phantom Compatible Account Derivation

Overview

The @iheartsolana/jelli-core library provides 100% Phantom-compatible account derivation, generating identical addresses to Phantom Wallet for all supported chains. This is achieved through account indices in the BIP44 derivation path, matching Phantom's exact implementation.

How It Works (Phantom Compatible)

Account Index Based Derivation (Phantom Standard)

• Derivation Path: m/44'/coin_type'/0'/0/account_index (Bitcoin, Ethereum, Base)
• Solana Path: m/44'/501'/account_index'/0' (SLIP-0010 standard)
• Examples:
  • Account 0: m/44'/60'/0'/0/0 (Ethereum account 0)
  • Account 1: m/44'/60'/0'/0/1 (Ethereum account 1)
  • Account 2: m/44'/60'/0'/0/2 (Ethereum account 2)

Key Features

✅ 100% Phantom Compatible: Identical addresses for same mnemonic + account index
✅ Single Seed Backup: One mnemonic phrase backs up all accounts across all chains
✅ Deterministic Generation: Same seed + account index = same addresses as Phantom
✅ Multi-Chain Support: Bitcoin, Ethereum, Solana, Base with correct derivation paths
✅ Account Index System: Uses account indexing like Phantom (not wallet indexing)
✅ Perfect Interoperability: Import/export between Jelli and Phantom seamlessly

Phantom Compatible API Usage

Creating Accounts (Phantom Style)

import { WalletManager, HDWalletEngine, InMemoryWalletStore, InMemorySecretVault } from '@iheartsolana/jelli-core';

const engine = new HDWalletEngine();
const store = new InMemoryWalletStore();
const vault = new InMemorySecretVault();
const manager = new WalletManager(engine, store, vault);

// Create wallet (Phantom compatible)
const wallet = await manager.createWallet('My Phantom Wallet');

// Derive multiple accounts (like Phantom's "Create Account")
const account0 = await manager.deriveAccount(wallet.wallet.id, ChainType.Ethereum, 0);
const account1 = await manager.deriveAccount(wallet.wallet.id, ChainType.Ethereum, 1);
const account2 = await manager.deriveAccount(wallet.wallet.id, ChainType.Ethereum, 2);

// All addresses match Phantom exactly! ✅

Manual Account Derivation (Phantom Compatible)

// Derive accounts with Phantom-compatible paths
const account0 = await engine.deriveAccount({
  mnemonic: 'your twelve word mnemonic phrase here...',
  chain: ChainType.Ethereum,
  accountIndex: 0  // Phantom uses account indexing
});

const account1 = await engine.deriveAccount({
  mnemonic: 'your twelve word mnemonic phrase here...',
  chain: ChainType.Ethereum,
  accountIndex: 1  // Next account (like Phantom)
});

// Addresses will match Phantom exactly! ✅
console.log(account0.account.address); // Same as Phantom Account 1
console.log(account1.account.address); // Same as Phantom Account 2

Derivation Paths by Chain (Phantom Compatible)

| Chain | Path Template | Example (Account 1) | Phantom Match | |-------|---------------|---------------------|---------------| | Bitcoin | m/84'/0'/0'/0/account_index | m/84'/0'/0'/0/1 | ✅ | | Ethereum | m/44'/60'/0'/0/account_index | m/44'/60'/0'/0/1 | ✅ | | Solana | m/44'/501'/account_index'/0' | m/44'/501'/1'/0' | ✅ | | Base | m/44'/60'/0'/0/account_index | m/44'/60'/0'/0/1 | ✅ Same as Ethereum |

✅ Phantom Compatibility Verified:
All derivation paths have been tested and verified to produce identical addresses to Phantom Wallet. Base uses Ethereum's derivation path (coin type 60) for maximum wallet compatibility, which is the same approach used by Phantom and other major wallets.

🧪 Interactive Testing

Experience all features with our comprehensive test program:

# Build the library first
npm run build

# Run the interactive test program
npm run test:interactive

# Or run directly
node examples/wallet-management/test-interactive.js

Available Test Features

Wallet Management

• Create a new HD wallet - Generate a new BIP39 wallet with mnemonic
• Import wallet from mnemonic - Import an existing wallet using a mnemonic phrase
• List all wallets - View all created/imported wallets
• Get active wallet - See which wallet is currently active
• Set active wallet - Switch the active wallet
• Remove wallet - Delete a wallet and its accounts

Account Operations

• Derive account address - Generate addresses for specific chains and account indices
• List accounts for wallet - View all derived accounts for a wallet
• Import account from private key - Import standalone accounts from private keys
• Test account derivation with private key - Derive accounts including private keys (for testing)
• Bulk derive accounts (all chains) - Generate multiple accounts across all supported chains

Phantom Compatibility Testing

• Create Phantom Compatible Wallet - Test wallet creation with Phantom derivation
• Derive Multiple Accounts - Test account indexing like Phantom
• Compare Addresses with Phantom - Verify identical address generation
• Test Cross-Chain Derivation - Consistency across Bitcoin, Ethereum, Solana, Base
• Phantom Import/Export Testing - Verify seamless interoperability

Utilities & Validation

• Validate mnemonic phrase - Test BIP39 mnemonic validation
• Get supported chains - List all supported blockchain types
• Export wallet details - Get a summary of wallet and account information
• Clear all data (reset) - Reset to fresh state

Important Notes

Security Warnings

• This is for testing only - Uses in-memory storage that doesn't persist
• Private keys are displayed - Never use in production environments
• Mnemonics are shown in plain text - For educational/testing purposes only

Data Persistence

• All data is stored in memory and will be lost when the program exits
• Use option 19 to clear all data and start fresh during testing
• No sensitive data is written to disk

Perfect for:

• Testing integration before implementing in your app
• Understanding account derivation patterns
• Experimenting with private key imports
• Validating multi-chain address generation

📚 API Reference

HDWalletEngine (Core)

Core cryptographic operations for HD wallets.

class HDWalletEngine {
  // Wallet Creation
  createWallet(name: string, strength?: number): Promise<IWalletCreationResult>
  createWalletFromSeed(name: string, seedBytes: Buffer, walletIndex?: number): Promise<IWalletCreationResult>
  
  // Validation
  validateMnemonic(mnemonic: string): IMnemonicValidationResult
  
  // Account Derivation
  deriveAccount(params: IAccountDerivationParams): Promise<IAccountDerivationResult>
  deriveAccountFromSeed(params: {
    seedBytes: Buffer;
    chain: ChainType;
    accountIndex: number;
    walletIndex?: number;
    includePrivateKey?: boolean;
    checksumAddress?: boolean;
    btcNetwork?: 'mainnet' | 'testnet';
  }): Promise<IAccountDerivationResult>
  
  // Utilities
  mnemonicToSeedBytes(mnemonic: string): Promise<Buffer>
  getCoinTypes(): CoinType[]
  getSupportedChains(): string[]
}

interface IAccountDerivationParams {
  mnemonic: string;
  chain: ChainType;
  accountIndex: number;
  walletIndex?: number;  // Always 0 for Phantom compatibility
  includePrivateKey?: boolean;
  checksumAddress?: boolean;
  btcNetwork?: 'mainnet' | 'testnet';
}

WalletManager (Recommended)

High-level wallet orchestration with automatic account management.

class WalletManager {
  // HD Wallet Operations (Phantom Compatible)
  createWallet(name: string, strength?: number): Promise<IWalletCreationResult>
  importWallet(name: string, mnemonic: string): Promise<IWalletCreationResult>
  listWallets(): Promise<IWalletMetadata[]>
  removeWallet(walletId: string): Promise<void>
  
  // Account Derivation (Phantom Compatible)
  deriveAccount(walletId: string, chain: ChainType, accountIndex: number): Promise<IAccountDerivationResult>
  listAccounts(walletId: string): Promise<AccountMeta[]>
  
  // Private Key Import
  importAccount(name: string, privateKey: string, chainType: ChainType): Promise<IAccountImportResult>
  listImportedAccounts(): Promise<ImportedAccount[]>
  removeImportedAccount(address: string): Promise<void>
  
  // Unified View
  getAllAccounts(walletId?: string): Promise<UnifiedAccount[]>
  
  // Active Wallet Management
  getActiveWallet(): Promise<IWalletMetadata | null>
  setActiveWallet(walletId: string): Promise<void>
}

Encryption & Security Utilities

Production-ready cryptographic utilities for secure key management.

⚠️ Requires Crypto Adapter: Make sure to call setCryptoAdapter() before using encryption functions.

// Mnemonic-based encryption (Phantom compatible - primary approach)
function encryptAndSplitMnemonic(mnemonic: string, config: ShamirConfig): Promise<EncryptAndSplitResult>
function reconstructAndDecryptMnemonic(encrypted: EncryptedData, shares: Buffer[], threshold: number): Promise<{ success: boolean, mnemonic?: string }>

// Seed-based encryption (legacy support for existing wallets)
function encryptAndSplitSeed(seedBytes: Buffer, config: ShamirConfig): Promise<EncryptAndSplitSeedResult>
function reconstructAndDecryptSeed(encrypted: EncryptedData, shares: Buffer[], threshold: number): Promise<ReconstructAndDecryptSeedResult>

// Low-level AEAD encryption
function encryptWithAEAD(data: string | Buffer, key?: Buffer): EncryptionResult
function decryptWithAEAD(encrypted: EncryptedData, key: Buffer): Buffer

// Utilities
function generateSeedBytes(byteLength?: number): Buffer

Supported Chain Types

enum ChainType {
  Bitcoin = 'bitcoin',    // P2WPKH bech32 (bc1q...)
  Ethereum = 'ethereum',  // EIP-55 checksum (0x...)
  Solana = 'solana',     // Base58 (...)
  Base = 'base'          // EIP-55 checksum (0x...) - Uses Ethereum derivation for compatibility
}

enum CoinType {
  Bitcoin = 0,     // BIP44 coin type
  Solana = 501,    // SLIP-0044 registered
  Ethereum = 60,   // SLIP-0044 registered  
  Base = 60        // Uses Ethereum coin type for Phantom compatibility (official: 8453)
}

Development

Prerequisites

• Node.js 18+
• npm or yarn

Setup & Development

# Install dependencies
npm install

# 🧪 Interactive testing (recommended first step)
npm run test:interactive

# 🧪 Unit testing
npm test                    # Run all tests
npm run test:watch         # Watch mode for development
npm run test:coverage      # Coverage report

# 🏗️ Building
npm run build              # Compile TypeScript to dist/

# 📚 Documentation  
npm run docs               # Generate API documentation
npm run docs:serve         # Live documentation server

# 🔍 Code quality
npm run lint               # ESLint checks
npm run lint:fix           # Auto-fix linting issues

🎯 Recommended Development Workflow

1. Start with Interactive Testing

   npm run test:interactive

   This gives you hands-on experience with all features before diving into code.

2. Explore the Test Suite

   npm run test:coverage

   Our tests are the best documentation of how everything works.

3. Run the Documentation Server

   npm run docs:serve

   Live API reference with examples and concept guides.

4. Make Your Changes

   • Add features to existing modules
   • Write tests for new functionality
   • Update documentation in JSDoc comments

5. Validate Everything

   npm test && npm run build && npm run lint

🔒 Security & Compliance

✅ Cryptographic Standards

• BIP39 - Standard mnemonic phrase generation and validation
• BIP44 - Hierarchical deterministic wallet derivation paths
• SLIP-0010 - Ed25519 support for Solana accounts
• EIP-55 - Ethereum checksum address encoding

✅ Security Features

• Cryptographically Secure - Uses platform-native secure random generation
• Input Validation - Comprehensive sanitization and format validation
• Private Key Security - Encrypted storage with platform-specific vaults
• No Data Leakage - Sensitive data never appears in logs or errors
• Memory Safety - Proper cleanup of sensitive data structures

✅ Multi-Chain Address Generation

• Bitcoin - P2WPKH SegWit (bech32) addresses with proper hash160
• Ethereum - Keccak256 hashing with EIP-55 checksum validation
• Solana - Ed25519 keypairs with base58 encoding
• Base - Ethereum-compatible with Coinbase L2 specifications

⚠️ Security Notes

• Test Environment Only - In-memory stores are NOT secure for production
• Platform Implementation Required - Implement secure ISecretVault for your platform
• Mnemonic Backup - Users MUST backup mnemonic phrases securely
• Private Key Handling - Never log, display, or transmit private keys unsecurely
• Share Distribution - Store secret shares in different secure locations
• Threshold Selection - Balance security vs. availability (e.g., 3-of-5 for production)

🤝 Contributing

Quick Contribution Workflow

1. 🧪 Test First - Use npm run test:interactive to understand current behavior
2. 🍴 Fork & Branch - Create a feature branch from main
3. 🔧 Develop - Write code, tests, and documentation
4. ✅ Validate - npm test && npm run build && npm run lint
5. 📝 Document - Update README if adding major features
6. 🚀 Submit - Create pull request with clear description

Contribution Standards

• ✅ Type Safety - All new code must be fully typed
• ✅ Test Coverage - New features require comprehensive tests
• ✅ Documentation - Public APIs need JSDoc with examples
• ✅ Security - Crypto operations require extra review

📄 License

MIT License - see LICENSE file for details.

🎉 Ready to Build Amazing Wallets?

npm install @iheartsolana/jelli-core
npm run test:interactive  # Start exploring!

This library is the foundation everything else is built on. Built for developers who demand security, flexibility, and excellent developer experience. 🔐✨