navio-sdk 0.1.0 → 0.1.2

package/README.md

@@ -5,6 +5,7 @@ TypeScript SDK for interacting with the Navio blockchain. Provides wallet manage
 ## Features
 
 - **Wallet Management** - HD key derivation with BLS CT support
+- **Wallet Encryption** - Password-based encryption with Argon2id + AES-256-GCM
 - **Dual Sync Backends** - Electrum protocol or direct P2P node connections
 - **Automatic Output Detection** - BLSCT output scanning with view tag optimization
 - **Amount Recovery** - Decrypt confidential transaction amounts
@@ -43,8 +44,8 @@ await client.initialize();
 
 // Sync transaction keys
 await client.sync({
-  onProgress: (height, tip, blocks, txKeys) => {
-    console.log(`Syncing: ${height}/${tip} (${blocks} blocks, ${txKeys} TX keys)`);
+  onProgress: (height, tip, blocks, txKeys, isReorg) => {
+    console.log(`Syncing: ${height}/${tip} (${blocks} blocks, ${txKeys} TX keys${isReorg ? ' [REORG]' : ''})`);
   },
 });
 
@@ -101,6 +102,7 @@ interface NavioClientConfig {
   // Wallet options
   createWalletIfNotExists?: boolean; // Create wallet if missing (default: false)
   restoreFromSeed?: string;          // Restore from seed (hex string)
+  restoreFromMnemonic?: string;      // Restore from BIP39 mnemonic (12-24 words)
   restoreFromHeight?: number;        // Block height when wallet was created (for restore)
   creationHeight?: number;           // Creation height for new wallets (default: chainTip - 100)
 }
@@ -167,6 +169,16 @@ Returns the last synced block height, or -1 if never synced.
 
 Returns current sync state with statistics.
 
+```typescript
+interface SyncState {
+  lastSyncedHeight: number;    // Last synced block height
+  lastSyncedHash: string;      // Last synced block hash
+  totalTxKeysSynced: number;   // Total transaction keys synced
+  lastSyncTime: number;        // Last sync timestamp (ms)
+  chainTipAtLastSync: number;  // Chain tip at last sync
+}
+```
+
 #### Background Sync
 
 ##### `startBackgroundSync(options?: BackgroundSyncOptions): Promise<void>`
@@ -272,10 +284,6 @@ Check if client is connected to the backend.
 
 #### Connection
 
-##### `connect(): Promise<void>`
-
-Connect to the backend.
-
 ##### `disconnect(): Promise<void>`
 
 Disconnect from backend and close database.
@@ -300,12 +308,48 @@ const masterSeed = keyManager.getMasterSeedKey();
 console.log('Seed:', masterSeed.serialize()); // hex string
 ```
 
+#### Mnemonic Support (BIP39)
+
+```typescript
+// Generate a new 24-word mnemonic and set as seed
+const mnemonic = keyManager.generateNewMnemonic();
+console.log('Mnemonic:', mnemonic);
+// "abandon ability able about above absent absorb abstract absurd abuse access accident..."
+
+// Or generate mnemonic with different word counts
+const mnemonic12 = KeyManager.generateMnemonic(128); // 12 words
+const mnemonic24 = KeyManager.generateMnemonic(256); // 24 words (default)
+
+// Validate a mnemonic
+const isValid = KeyManager.validateMnemonic(mnemonic);
+console.log('Valid:', isValid); // true
+
+// Restore from mnemonic
+keyManager.setHDSeedFromMnemonic(mnemonic);
+
+// Get mnemonic from current seed (for backup)
+const backupMnemonic = keyManager.getMnemonic();
+console.log('Backup mnemonic:', backupMnemonic);
+
+// Static conversion methods
+const scalar = KeyManager.mnemonicToScalar(mnemonic); // Convert to Scalar
+const recovered = KeyManager.seedToMnemonic(scalar);  // Convert back to mnemonic
+```
+
 #### Sub-addresses
 
 ```typescript
 // Get sub-address by identifier
 const subAddr = keyManager.getSubAddress({ account: 0, address: 0 });
 
+// Get bech32m encoded address string (recommended)
+const address = keyManager.getSubAddressBech32m({ account: 0, address: 0 }, 'testnet');
+console.log('Address:', address); // tnav1... (Node.js) or hex fallback (browser)
+
+// Get mainnet address
+const mainnetAddress = keyManager.getSubAddressBech32m({ account: 0, address: 0 }, 'mainnet');
+console.log('Address:', mainnetAddress); // nav1...
+
 // Generate new sub-address
 const { subAddress, id } = keyManager.generateNewSubAddress(0); // account 0
 
@@ -315,6 +359,9 @@ keyManager.newSubAddressPool(-1); // Change
 keyManager.newSubAddressPool(-2); // Staking
 ```
 
+> **Note:** In browser environments using navio-blsct WASM, bech32m encoding may fall back to hex
+> representation due to a known issue. This will be addressed in a future navio-blsct release.
+
 #### Output Detection
 
 ```typescript
@@ -331,6 +378,38 @@ const hashId = keyManager.calculateHashId(blindingKey, spendingKey);
 const nonce = keyManager.calculateNonce(blindingKey);
 ```
 
+#### Wallet Encryption
+
+The KeyManager supports password-based encryption using Argon2id for key derivation and AES-256-GCM for encryption.
+
+```typescript
+// Check encryption status
+const isEncrypted = keyManager.isEncrypted();
+const isUnlocked = keyManager.isUnlocked();
+
+// Set a password (encrypts the wallet)
+await keyManager.setPassword('my-secure-password');
+
+// Lock the wallet (clears cached encryption key)
+keyManager.lock();
+
+// Unlock the wallet
+const success = await keyManager.unlock('my-secure-password');
+if (!success) {
+  console.log('Wrong password');
+}
+
+// Change password
+const changed = await keyManager.changePassword('old-password', 'new-password');
+
+// Get encryption parameters (for database storage)
+const params = keyManager.getEncryptionParams();
+// { salt: 'hex...', verificationHash: 'hex...' }
+
+// Restore encryption state from database
+keyManager.setEncryptionParams(params.salt, params.verificationHash);
+```
+
 ---
 
 ### WalletDB
@@ -381,6 +460,50 @@ const utxos = await walletDB.getUnspentOutputs();
 const outputs = await walletDB.getAllOutputs();
 ```
 
+#### Database Encryption
+
+The WalletDB supports full database encryption for secure backup and export.
+
+```typescript
+// Export database as encrypted blob
+const encryptedData = await walletDB.exportEncrypted('backup-password');
+// encryptedData is a Uint8Array that can be saved to file
+
+// Load database from encrypted blob
+const restoredDb = await WalletDB.loadEncrypted(encryptedData, 'backup-password');
+
+// Check if a buffer is an encrypted database
+import { isEncryptedDatabase } from 'navio-sdk';
+const isEncrypted = isEncryptedDatabase(someBuffer);
+
+// Export unencrypted database (for backup without password)
+const rawData = walletDB.export();
+
+// Load from raw bytes
+const db = await WalletDB.loadFromBytes(rawData);
+```
+
+#### Encryption Metadata
+
+```typescript
+// Check if encryption is enabled
+const isEncrypted = walletDB.isEncrypted();
+
+// Save encryption metadata
+walletDB.saveEncryptionMetadata(salt, verificationHash);
+
+// Get encryption metadata
+const metadata = walletDB.getEncryptionMetadata();
+// { salt: 'hex...', verificationHash: 'hex...' } or null
+
+// Get/save encrypted keys
+walletDB.saveEncryptedKey(keyId, publicKey, encryptedSecret);
+const key = walletDB.getEncryptedKey(keyId);
+
+// Delete plaintext keys after encryption
+walletDB.deletePlaintextKeys();
+```
+
 ---
 
 ### SyncProvider Interface
@@ -396,6 +519,7 @@ interface SyncProvider {
   isConnected(): boolean;
   
   getChainTipHeight(): Promise<number>;
+  getChainTip(): Promise<{ height: number; hash: string }>;
   getBlockHeader(height: number): Promise<string>;
   getBlockHeaders(startHeight: number, count: number): Promise<HeadersResult>;
   getBlockTransactionKeysRange(startHeight: number): Promise<TransactionKeysRangeResult>;
@@ -436,7 +560,7 @@ import { P2PSyncProvider } from 'navio-sdk';
 
 const provider = new P2PSyncProvider({
   host: 'localhost',
-  port: 33670,
+  port: 43670,  // testnet port (mainnet: 33670)
   network: 'testnet',
   debug: true,
 });
@@ -468,12 +592,9 @@ const keyManager = client.getKeyManager();
 const seed = keyManager.getMasterSeedKey();
 console.log('SAVE THIS SEED:', seed.serialize());
 
-// Get receiving address
-const { DoublePublicKey, Address, AddressEncoding } = require('navio-blsct');
-const subAddress = keyManager.getSubAddress({ account: 0, address: 0 });
-const dpk = DoublePublicKey.deserialize(subAddress.serialize());
-const address = Address.encode(dpk, AddressEncoding.Bech32M);
-console.log('Address:', address);
+// Get receiving address (bech32m encoded)
+const address = keyManager.getSubAddressBech32m({ account: 0, address: 0 }, 'testnet');
+console.log('Address:', address); // tnav1...
 ```
 
 ### Restore Wallet from Seed
@@ -497,6 +618,27 @@ await client.sync({
 });
 ```
 
+### Restore Wallet from Mnemonic
+
+```typescript
+const client = new NavioClient({
+  walletDbPath: './restored-wallet.db',
+  electrum: { host: 'localhost', port: 50005 },
+  restoreFromMnemonic: 'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon art',
+  restoreFromHeight: 50000, // Block height when wallet was created
+  network: 'testnet',
+});
+
+await client.initialize();
+
+// Full sync from restoration height
+await client.sync({
+  onProgress: (height, tip) => {
+    console.log(`Syncing: ${height}/${tip}`);
+  },
+});
+```
+
 ### Using P2P Backend
 
 ```typescript
@@ -607,6 +749,77 @@ for (const utxo of utxos) {
 }
 ```
 
+### Encrypt Wallet with Password
+
+```typescript
+import { NavioClient } from 'navio-sdk';
+
+const client = new NavioClient({
+  walletDbPath: './secure-wallet.db',
+  electrum: { host: 'localhost', port: 50005 },
+  createWalletIfNotExists: true,
+  network: 'testnet',
+});
+
+await client.initialize();
+
+// Set a password to encrypt the wallet
+const keyManager = client.getKeyManager();
+await keyManager.setPassword('my-secure-password');
+console.log('Wallet encrypted:', keyManager.isEncrypted()); // true
+
+// The wallet is now encrypted but unlocked
+console.log('Wallet unlocked:', keyManager.isUnlocked()); // true
+
+// Lock the wallet (recommended when not in use)
+keyManager.lock();
+console.log('Wallet unlocked:', keyManager.isUnlocked()); // false
+
+// Unlock to use
+const success = await keyManager.unlock('my-secure-password');
+console.log('Unlock successful:', success); // true
+```
+
+### Export Encrypted Backup
+
+```typescript
+// Export encrypted database for backup
+const walletDb = client.getWalletDB();
+const encryptedBackup = await walletDb.exportEncrypted('backup-password');
+
+// Save to file (Node.js)
+const fs = require('fs');
+fs.writeFileSync('wallet-backup.enc', encryptedBackup);
+
+// Or download in browser
+const blob = new Blob([encryptedBackup], { type: 'application/octet-stream' });
+const url = URL.createObjectURL(blob);
+const a = document.createElement('a');
+a.href = url;
+a.download = 'wallet-backup.enc';
+a.click();
+```
+
+### Restore from Encrypted Backup
+
+```typescript
+import { WalletDB } from 'navio-sdk';
+
+// Load encrypted backup
+const fs = require('fs');
+const encryptedData = fs.readFileSync('wallet-backup.enc');
+
+// Decrypt and load
+const walletDb = await WalletDB.loadEncrypted(
+  new Uint8Array(encryptedData),
+  'backup-password'
+);
+
+// Load the wallet
+const keyManager = await walletDb.loadWallet();
+console.log('Wallet restored');
+```
+
 ---
 
 ## Database Schema
@@ -617,12 +830,15 @@ The wallet database includes the following tables:
 |-------|-------------|
 | `keys` | Key pairs for transactions |
 | `out_keys` | Output-specific keys |
+| `crypted_keys` | Encrypted key pairs (when password set) |
+| `crypted_out_keys` | Encrypted output keys (when password set) |
 | `view_key` | View key for output detection |
 | `spend_key` | Spending public key |
 | `hd_chain` | HD chain information |
 | `sub_addresses` | Sub-address mappings |
 | `wallet_outputs` | Wallet UTXOs with amounts |
 | `wallet_metadata` | Wallet creation info |
+| `encryption_metadata` | Encryption parameters (salt, verification hash) |
 | `tx_keys` | Transaction keys (optional) |
 | `block_hashes` | Block hashes for reorg detection |
 | `sync_state` | Synchronization state |
@@ -687,12 +903,14 @@ npm install
 npm run build
 
 # Run tests
+npm run test              # Run all unit tests (vitest)
 npm run test:keymanager   # KeyManager tests
 npm run test:walletdb     # WalletDB tests
 npm run test:electrum     # Electrum client tests
 npm run test:client       # Full client tests (Electrum)
 npm run test:p2p          # P2P protocol tests
 npm run test:client:p2p   # Full client tests (P2P)
+npm run test:encryption   # Encryption module tests
 
 # Generate documentation
 npm run docs              # HTML docs in ./docs
@@ -711,6 +929,52 @@ npm run analyze:db
 
 ---
 
+### Encryption Module
+
+The SDK includes a low-level encryption module for password-based encryption.
+
+```typescript
+import {
+  encrypt,
+  decrypt,
+  deriveKey,
+  serializeEncryptedData,
+  deserializeEncryptedData,
+  createPasswordVerification,
+  verifyPassword,
+  randomBytes,
+} from 'navio-sdk';
+
+// Encrypt arbitrary data
+const plaintext = new TextEncoder().encode('secret data');
+const encrypted = await encrypt(plaintext, 'password');
+
+// Decrypt data
+const decrypted = await decrypt(encrypted, 'password');
+console.log(new TextDecoder().decode(decrypted)); // 'secret data'
+
+// Serialize for storage (converts to base64 strings)
+const serialized = serializeEncryptedData(encrypted);
+const json = JSON.stringify(serialized);
+
+// Deserialize from storage
+const parsed = JSON.parse(json);
+const deserialized = deserializeEncryptedData(parsed);
+
+// Password verification (for UI feedback)
+const salt = randomBytes(16);
+const hash = await createPasswordVerification('password', salt);
+const isValid = await verifyPassword('password', salt, hash);
+```
+
+**Security Properties:**
+- **Key Derivation**: Argon2id with 64MB memory, 3 iterations, 4 parallelism
+- **Encryption**: AES-256-GCM (authenticated encryption)
+- **Random IV**: 12 bytes per encryption (never reused)
+- **Random Salt**: 16 bytes per password derivation
+
+---
+
 ## Known Limitations
 
 1. **Amount Recovery**: The `navio-blsct` library v1.0.20 has a bug in `RangeProof.recoverAmounts()`. Outputs are detected and stored but amounts show as 0 until the library is updated.