@hauska-sdk/wallet

Secure wallet management and signing for the CNS Protocol SDK.

Features

• ✅ Automatic Wallet Creation - Generate new Ethereum wallets
• ✅ Secure Encryption - AES-256-GCM encryption with PBKDF2 key derivation
• ✅ Import/Export - Encrypted wallet backup and restore
• ✅ Message Signing - EIP-191 and EIP-712 signature support
• ✅ Seed Phrase Support - Create wallets from mnemonic phrases
• ✅ Password Protection - All wallets encrypted with user passwords

Installation

npm install @hauska-sdk/wallet

Quick Start

import { WalletManager } from '@hauska-sdk/wallet';

const manager = new WalletManager();

// Create a new wallet
const wallet = await manager.createWallet({
  password: 'user-password-123',
  userId: 'user-123',
});

console.log('Wallet address:', wallet.address);

// Sign a message
const signature = await manager.signMessage(
  wallet.address,
  'Hello, World!',
  'user-password-123'
);

// Export wallet for backup
const exported = await manager.exportWallet(
  wallet.address,
  'user-password-123'
);

// Import wallet later
const imported = await manager.importWallet({
  encryptedJson: exported,
  password: 'user-password-123',
});

API Reference

WalletManager

createWallet(options)

Create a new wallet.

const wallet = await manager.createWallet({
  password: 'user-password',
  userId: 'user-123', // optional
});

getOrCreateWallet(userId, password)

Get existing wallet or create new one for user.

const wallet = await manager.getOrCreateWallet('user-123', 'password');

exportWallet(address, password)

Export wallet as encrypted JSON.

const exported = await manager.exportWallet(wallet.address, 'password');

importWallet(options)

Import wallet from encrypted JSON.

const wallet = await manager.importWallet({
  encryptedJson: exportedJson,
  password: 'password',
  userId: 'user-123', // optional
});

signMessage(address, message, password)

Sign a message (EIP-191).

const signature = await manager.signMessage(
  wallet.address,
  'Hello, World!',
  'password'
);

signTypedData(address, domain, types, value, password)

Sign typed data (EIP-712).

const signature = await manager.signTypedData(
  wallet.address,
  {
    name: 'MyApp',
    version: '1',
    chainId: 8453, // Base
  },
  {
    Message: [{ name: 'content', type: 'string' }],
  },
  { content: 'Hello' },
  'password'
);

createWalletFromSeedPhrase(mnemonic, password, userId?, accountIndex?)

Create wallet from BIP39 mnemonic.

const wallet = await manager.createWalletFromSeedPhrase(
  'abandon abandon abandon...',
  'password',
  'user-123',
  0 // account index
);

verifyPassword(address, password)

Verify wallet password without decrypting.

const isValid = await manager.verifyPassword(wallet.address, 'password');

Security

Encryption

• Algorithm: AES-256-GCM
• Key Derivation: PBKDF2 with 100,000+ iterations
• Salt: Unique 32-byte salt per wallet
• IV: Unique 16-byte IV per encryption

Best Practices

1. Never store plaintext private keys
2. Use strong passwords (minimum 12 characters)
3. Store encrypted wallets securely
4. Backup wallets using export functionality
5. Verify passwords before operations

Storage

The WalletManager currently stores wallets in memory. In production, you should:

1. Store encrypted wallets in a database
2. Use secure key management
3. Implement proper access controls
4. Add audit logging

Testing

npm test

License

MIT