Privacy Wallet Generation SDK

A TypeScript SDK for generating privacy-focused cryptocurrency wallets with secure claiming mechanisms.

Behavioral Organization

The SDK is organized into behavioral modules for better maintainability and separation of concerns:

/wallet - Wallet Generation and Cryptographic Operations

• generator.ts - Core wallet generation logic from salt strings, HD wallets, and mnemonics
• Handles deterministic entropy derivation and cryptographic operations

/storage - Data Persistence and Encryption

• secure-storage.ts - Encrypted storage for wallet data with expiration and cleanup
• Manages secure storage, retrieval, and encryption/decryption of sensitive data

/claims - Token-based Claiming System

• claim-manager.ts - Manages claim tokens, verification codes, and wallet claiming
• Handles token generation, validation, and secure wallet distribution

/validators - Input Validation Logic

• salt.validator.ts - Validates salt strings for security requirements
• Ensures proper input validation and security standards

/utils - Shared Utility Functions

• crypto.ts - Cryptographic utilities for token generation, entropy derivation, and strength assessment
• Provides common cryptographic operations used across modules

/core - Main SDK Integration

• PrivacyWalletSDK.ts - Main SDK class that orchestrates all modules
• Provides high-level API for wallet creation, claiming, and management

/config - Configuration Management

• default.ts - Default configuration values and environment-specific configs
• Centralized configuration management for all modules

/types - Type Definitions

• types-index.ts - Central export point for all type definitions
• wallet.ts - Wallet-related type definitions
• config.ts - Configuration type definitions
• claim.ts - Claim-related type definitions
• storage.ts - Storage-related type definitions

/errors - Centralized Error Handling

• PrivacyWalletError.ts - Base error class
• ValidationError.ts - Validation-specific errors
• **SecurityError.ts - Security-related errors
• **error-index.ts - Error factory functions and type guards

Installation

npm install privacy-wallet-sdk
# or
yarn add privacy-wallet-sdk
# or
pnpm add privacy-wallet-sdk

Requirements

• Node.js >= 16.0.0
• TypeScript >= 4.8.0 (for TypeScript projects)

Quick Start

Basic Usage

import { PrivacyWalletSDK, ValidationError } from 'privacy-wallet-sdk';

// Initialize the SDK
const sdk = new PrivacyWalletSDK({
  saltMinLength: 64,
  walletExpirationHours: 48
});

// Create a wallet from a salt string
const result = await sdk.createWallet('my-super-secret-salt-string-that-is-very-long');

console.log('Wallet Address:', result.walletData.address);
console.log('Claim Token:', result.claimToken);

// Claim the wallet
const wallet = await sdk.claimWallet(result.claimToken!);
console.log('Claimed Wallet:', wallet.address);

Advanced Usage

import { PrivacyWalletSDK, ValidationError, SecurityError } from 'privacy-wallet-sdk';

const sdk = new PrivacyWalletSDK({
  saltMinLength: 64,
  walletExpirationHours: 48,
  encryptStoredData: true
});

// Event listeners
sdk.on('walletCreated', (data) => {
  console.log('Wallet created:', data.address);
});

sdk.on('walletClaimed', (data) => {
  console.log('Wallet claimed:', data.address);
});

sdk.on('error', (error) => {
  console.error('SDK Error:', error.message);
});

try {
  // Create HD wallet with multiple addresses
  const result = await sdk.createWallet('my-super-secret-salt-string', {
    chain: 'ethereum',
    addressCount: 3 // Creates HD wallet with 3 addresses
  });

  console.log('HD Wallet Addresses:', result.walletData.addresses?.length);
  console.log('Claim Token:', result.claimToken);

  // Claim the wallet
  const wallet = await sdk.claimWallet(result.claimToken!);
  console.log('Claimed Wallet:', wallet.address);

  // Get wallet information
  const info = await sdk.getWalletInfo(result.claimToken!);
  console.log('Wallet Info:', info.wallet);

  // Validate salt strength
  const validation = sdk.validateSalt('my-salt-string');
  console.log('Salt Strength:', validation.strength);

} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Validation error:', error.message);
  } else if (error instanceof SecurityError) {
    console.error('Security error:', error.message);
  } else {
    console.error('Unexpected error:', error);
  }
}

Individual Module Usage

import { 
  WalletGenerator, 
  SecureStorage, 
  ClaimManager,
  CryptoUtils,
  SaltValidator 
} from 'privacy-wallet-sdk';

// Use wallet generator directly
const generator = new WalletGenerator();
const wallet = generator.generateFromSalt('my-salt-string');

// Use secure storage
const storage = new SecureStorage();
storage.store('wallet-1', wallet);

// Use claim manager
const claimManager = new ClaimManager();
const claimResult = claimManager.generateClaimToken(wallet);

// Use crypto utilities
const token = CryptoUtils.generateSecureToken(32);
const strength = CryptoUtils.assessSaltStrength('my-salt');

// Use validators
const validator = new SaltValidator(32);
validator.validate('my-salt-string');

Features

• Deterministic Wallet Generation: Create wallets from salt strings with consistent results
• HD Wallet Support: Generate hierarchical deterministic wallets with multiple addresses
• Secure Claiming: Token-based system for secure wallet distribution
• Encrypted Storage: Secure storage with automatic expiration and cleanup
• Event-Driven Architecture: Real-time notifications for wallet operations
• TypeScript Support: Full type safety and IntelliSense support
• Configurable Security: Adjustable security parameters for different use cases

Security Features

• Configurable salt length requirements
• PBKDF2 key derivation with configurable iterations
• AES-256-GCM encryption for stored data
• Secure random token generation
• Automatic data expiration and cleanup
• Verification code support for high-security scenarios

API Reference

PrivacyWalletSDK

The main SDK class that orchestrates all wallet operations.

Constructor

new PrivacyWalletSDK(config?: Partial<PrivacyWalletConfig>)

Methods

• createWallet(saltString: string, options?: WalletGenerationOptions): Promise<WalletCreationResult>
• claimWallet(claimToken: string, verificationCode?: string): Promise<ClaimedWalletData>
• getWalletInfo(claimToken: string): Promise<WalletInfo>
• validateSalt(saltString: string): WalletValidationResult
• getStats(): SDKStats

Events

• initialized - SDK initialization complete
• walletCreationStarted - Wallet creation started
• walletCreated - Wallet creation completed
• claimStarted - Wallet claiming started
• walletClaimed - Wallet claiming completed
• claimFailed - Wallet claiming failed
• error - Error occurred

Configuration

interface PrivacyWalletConfig {
  // Cryptographic settings
  saltMinLength: number;              // Default: 32
  keyDerivationIterations: number;    // Default: 100000
  encryptionAlgorithm: string;        // Default: 'aes-256-cbc'
  hashAlgorithm: string;              // Default: 'sha256'
  
  // Wallet settings
  defaultDerivationPath: string;      // Default: "m/44'/60'/0'/0/0"
  supportedChains: string[];          // Default: ['ethereum', 'polygon', 'bsc', 'arbitrum']
  
  // Security settings
  claimTokenLength: number;           // Default: 64
  verificationCodeLength: number;     // Default: 6
  walletExpirationHours: number;      // Default: 24
  
  // Storage settings
  maxStoredWallets: number;           // Default: 1000
  encryptStoredData: boolean;         // Default: true
}

Development

Building from Source

git clone https://github.com/ANCILAR/wallet-generation-sdk.git
cd privacy-wallet-sdk
npm install
npm run build

Running Tests

# Run all tests
npm test

# Run specific test suites
npm run test:unit
npm run test:integration
npm run test:performance

# Run with coverage
npm run test:coverage

Contributing

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

• 📖 Documentation
• 🐛 Report Issues
• 💬 Discussions