Cardinals Wallet Keyring SDK

A powerful multi-chain wallet management SDK that supports generating, recovering, and managing wallets for multiple blockchain networks with advanced security features and comprehensive backup capabilities.

Features

Core Functionality

• Multi-Network Support - Generate and manage wallets across 8+ blockchain networks
• BIP39 Mnemonic Generation - Secure mnemonic phrase generation with configurable strength
• Hierarchical Deterministic Wallets - BIP32/BIP44 compliant wallet derivation
• Private Key Recovery - Recover wallets from private keys, WIF format, and encrypted JSON
• Address Validation - Validate various blockchain address formats
• Message Signing - Support for Ethereum-like network message signing

Advanced Security

• AES Encryption - Encrypt sensitive data with salt-based password obfuscation
• Password Strength Validation - Comprehensive password policy enforcement
• Mnemonic Strength Validation - Validate mnemonic entropy and word count
• Memory Security - Secure memory management for sensitive data

Multi-Wallet Management

• Wallet Groups - Organize wallets into groups with custom naming
• Account Management - Multiple accounts per wallet with network-specific addresses
• Network Configuration - Enable/disable specific networks per wallet
• Backup & Restore - Comprehensive backup and restore functionality
• Password Management - Individual and global password management

Performance & Optimization

• Bundle Optimization - Advanced build optimization with 32% size reduction
• Code Splitting - Intelligent chunking by functionality
• Tree Shaking - Remove unused code and dependencies
• Gzip Compression - Built-in compression analysis and optimization

Supported Networks

| Network | Symbol | Type | Derivation Path | |---------|--------|------|-----------------| | Bitcoin | BTC | Bitcoin-like | m/44'/0'/0'/0/0 | | Litecoin | LTC | Bitcoin-like | m/44'/2'/0'/0/0 | | Dogecoin | DOGE | Bitcoin-like | m/44'/3'/0'/0/0 | | Pepecoin | PEPE | Bitcoin-like | m/44'/3'/0'/0/0 | | Ethereum | ETH | Ethereum-like | m/44'/60'/0'/0/0 | | EthereumFair | ETHF | Ethereum-like | m/44'/3'/0'/0/0 | | Classzz | CZZ | Ethereum-like | m/44'/3'/0'/0/0 | | DogeOS | DOGEOS | Ethereum-like | m/44'/3'/0'/0/0 |

Installation

npm install @cardinals_org/keyring

Quick Start

Basic Usage

import { MultiWalletManager } from "@cardinals_org/keyring";

// Create wallet manager instance
const walletManager = new MultiWalletManager();

// Initialize with password
await walletManager.initialize({ password: "your-secure-password" });

// Create a new wallet
const wallet = await walletManager.createWallet({
  name: "My First Wallet",
  password: "your-secure-password"
});

console.log("Wallet created:", wallet.name);
console.log("Wallet ID:", wallet.id);

Generate Mnemonic

import { generateMnemonic, validateMnemonic } from "@cardinals_org/keyring";

// Generate a new mnemonic (256-bit entropy by default)
const mnemonic = generateMnemonic(256);
console.log("Generated mnemonic:", mnemonic);

// Validate mnemonic
const isValid = validateMnemonic(mnemonic);
console.log("Mnemonic is valid:", isValid);

Recover Wallet from Mnemonic

// Recover wallet from mnemonic
const recoveredWallet = await walletManager.recoverWalletFromMnemonic(
  mnemonic,
  "your-password",
  "Recovered Wallet"
);

console.log("Recovered wallet:", recoveredWallet.name);

Add Account to Wallet

// Add a new account to the wallet
const account = await walletManager.addAccount(wallet.id, {
  name: "Trading Account",
  password: "your-password"
});

console.log("Account created:", account.name);
console.log("Account ID:", account.id);

Access Network Addresses

// Get Bitcoin address for the account
const bitcoinAddress = walletManager.getNetworkAddress(
  wallet.id,
  account.id,
  "bitcoin"
);

console.log("Bitcoin address:", bitcoinAddress?.address);

// Get all network addresses for the account
account.networkAddresses.forEach(networkAddr => {
  console.log(`${networkAddr.networkType}: ${networkAddr.address}`);
});

Advanced Usage

Network Configuration

// Create wallet manager with specific networks enabled
const enabledNetworks = ["bitcoin", "dogecoin", "ethereum"];
const walletManager = new MultiWalletManager(
  undefined, // no initial wallets
  "my-password",
  enabledNetworks
);

// Check enabled networks
console.log("Enabled networks:", walletManager.getEnabledNetworks());

// Add/remove networks
walletManager.addEnabledNetwork("pepe");
walletManager.removeEnabledNetwork("ethereum");

// Reset to all supported networks
walletManager.resetNetworks();

Private Key Recovery

// Recover wallet from private key
const privateKeyWallet = await walletManager.recoverWalletFromPrivateKey(
  "your-private-key-here",
  undefined, // auto-generate wallet ID
  "Private Key Wallet"
);

// Recover from WIF format
const wifWallet = await walletManager.recoverWalletFromPrivateKey(
  "your-wif-private-key",
  undefined,
  "WIF Wallet"
);

Encrypted Wallet Management

// Create encrypted wallet backup
const backup = await walletManager.backupWallet(
  wallet.id,
  "backup-password"
);

console.log("Backup data:", backup);

// Verify wallet password
const isValidPassword = await walletManager.verifyWalletPassword(
  wallet.id,
  "your-password"
);

// Change wallet password
await walletManager.changeWalletPassword(
  wallet.id,
  "old-password",
  "new-password"
);

Address and Private Key Management

// Get private key for a specific address
const keyInfo = await walletManager.getAddressPrivateKey({
  address: "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
  password: "your-password",
  networkType: "bitcoin"
});

console.log("Private key:", keyInfo?.privateKey);

// Get wallet info by address
const addressInfo = walletManager.getAddressInfo(
  "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
  "bitcoin"
);

if (addressInfo) {
  console.log("Wallet:", addressInfo.wallet.name);
  console.log("Account:", addressInfo.account.name);
}

Security Features

// Validate password strength
import { validatePassword } from "@cardinals_org/keyring";

const passwordValidation = validatePassword("your-password");
console.log("Password strength:", passwordValidation.strength);

// Validate mnemonic strength
const mnemonicStrength = MultiWalletManager.validateMnemonicStrength(mnemonic);
console.log("Mnemonic strength:", mnemonicStrength.strength);

// Encrypt/decrypt sensitive data
import { encryptData, decryptData } from "@cardinals_org/keyring";

const encrypted = await encryptData("sensitive-data", "password");
const decrypted = await decryptData(encrypted, "password");

Bundle Optimization

The SDK includes advanced bundle optimization features:

Build Commands

# Standard build
npm run build

# Optimized build (22% size reduction)
npm run build:optimized

# Production build (32% size reduction)
npm run build:prod

# Test all build configurations
npm run build:test

# Analyze bundle size
npm run size-check

Bundle Sizes

• Standard Build: ~4.1MB
• Optimized Build: ~3.2MB (22% reduction)
• Production Build: ~2.8MB (32% reduction)
• Gzip Compressed: ~0.8MB (80% reduction)

Development

Prerequisites

• Node.js >= 16.0.0
• npm >= 8.0.0

Setup

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Type checking
npm run type-check

# Linting
npm run lint

Testing

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

Browser Compatibility

The SDK is built for modern browsers and includes necessary polyfills:

• Target: ES2020
• Browsers: > 1% market share, last 2 versions
• Polyfills: Node.js modules (crypto, buffer, stream, etc.)

Examples

Check the demo/ directory for complete examples:

• KeyringTest.tsx - Basic usage examples
• MultiWalletTest.tsx - Advanced multi-wallet functionality

Run the demo:

cd demo
npm install
npm run dev

Security Considerations

1. Private Key Security: Never hardcode private keys in client-side code
2. Mnemonic Backup: Securely backup mnemonics and never store them in the cloud
3. Password Strength: Use strong passwords to protect encrypted wallets
4. Environment Security: Generate and use wallets in secure environments
5. Memory Management: Clear sensitive data from memory when possible

Performance

Optimization Features

• Code Splitting: Separate chunks for crypto, blockchain, and utility functions
• Tree Shaking: Remove unused code during build
• Minification: Advanced Terser configuration for maximum compression
• Gzip Compression: Built-in compression analysis

Expected Performance

• Initial Load: 32% smaller bundle size
• Caching: Better cache efficiency with code splitting
• Runtime: Optimized for modern JavaScript engines

Contributing

We welcome contributions! Please see our contributing guidelines:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

If you encounter any issues or have questions:

1. Check the documentation
2. Search existing issues
3. Create a new issue with detailed information

Roadmap

• [ ] Support for more blockchain networks
• [ ] Hardware wallet integration
• [ ] Advanced encryption features
• [ ] WebAssembly optimizations
• [ ] React Native optimizations
• [ ] DeFi protocol integrations
• [ ] Cross-chain transaction support

Changelog

See CHANGELOG.md for version history and updates.

SDK Information

import { SDK_INFO } from "@cardinals_org/keyring";

console.log("SDK Version:", SDK_INFO.version);
console.log("Supported Networks:", SDK_INFO.supportedNetworks);
console.log("Features:", SDK_INFO.features);

Built with ❤️ by the Cardinals Team