JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 9
  • Score
    100M100P100Q70364F
  • License MIT

Multi-chain wallet management SDK for cardinals ecosystem

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/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