Package Exports
- @cardinals_org/keyring
- @cardinals_org/keyring/browser
Readme
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/keyringQuick 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-checkBundle 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 lintTesting
# Run all tests
npm test
# Run tests in watch mode
npm run test:watch
# Run tests with coverage
npm run test:coverageBrowser 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 examplesMultiWalletTest.tsx- Advanced multi-wallet functionality
Run the demo:
cd demo
npm install
npm run devSecurity Considerations
- Private Key Security: Never hardcode private keys in client-side code
- Mnemonic Backup: Securely backup mnemonics and never store them in the cloud
- Password Strength: Use strong passwords to protect encrypted wallets
- Environment Security: Generate and use wallets in secure environments
- 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:
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests for new functionality
- Ensure all tests pass
- Submit a pull request
License
MIT License - see LICENSE file for details.
Support
If you encounter any issues or have questions:
- Check the documentation
- Search existing issues
- 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