HD Wallet API

The HD Wallet API provides hierarchical deterministic wallet functionality, allowing you to derive multiple keys and addresses from a single master key. This is an alternative to the Account API that supports enhanced privacy through key derivation and follows BIP32/CIP1852 standards.

Key Features

Hierarchical Key Derivation: Generate multiple keys from a single master key
Address Privacy: Generate new addresses for each transaction
BIP32/CIP1852 Compliance: Follow industry standards for key derivation
Multi-Account Support: Manage multiple accounts within a single wallet
Deterministic Generation: Same mnemonic always generates same addresses

Core Classes

Wallet Interface

The main interface for HD wallet operations, providing methods for address generation, account management, and transaction signing.

DefaultWallet Class

The default implementation of the Wallet interface, supporting standard HD wallet functionality.

Key Methods:

create() - Create new wallet with generated mnemonic
createFromMnemonic() - Restore wallet from existing mnemonic
getBaseAddress() - Get base address at specific index
getEntAddress() - Get enterprise address at specific index
sign() - Sign transactions with wallet keys

Usage Examples

Creating HD Wallets

Create wallets with different mnemonic lengths and configurations:


// Create wallet with 24-word mnemonic (default)
Wallet wallet = Wallet.create(Networks.testnet());
String mnemonic = wallet.getMnemonic();
System.out.println("Generated 24-word mnemonic");
 
// Create wallet with 15-word mnemonic
Wallet wallet15 = Wallet.create(Networks.testnet(), Words.FIFTEEN);
String mnemonic15 = wallet15.getMnemonic();
System.out.println("Generated 15-word mnemonic");
 
// Create wallet with 12-word mnemonic
Wallet wallet12 = Wallet.create(Networks.testnet(), Words.TWELVE);
String mnemonic12 = wallet12.getMnemonic();
System.out.println("Generated 12-word mnemonic");

Restoring Wallets

Restore wallets from existing mnemonic phrases:


// Restore wallet from mnemonic
String mnemonic = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about";
Wallet restoredWallet = Wallet.createFromMnemonic(Networks.mainnet(), mnemonic);
 
// Restore wallet for specific account
Wallet accountWallet = Wallet.createFromMnemonic(Networks.mainnet(), mnemonic, 1);

Address Generation

Generate multiple addresses from a single wallet:


// Generate base addresses at different indexes
Address address0 = wallet.getBaseAddress(0);
Address address1 = wallet.getBaseAddress(1);
Address address2 = wallet.getBaseAddress(2);
 
System.out.println("Address 0: " + address0.getAddress());
System.out.println("Address 1: " + address1.getAddress());
System.out.println("Address 2: " + address2.getAddress());
 
// Generate enterprise addresses (no staking)
Address entAddress0 = wallet.getEntAddress(0);
Address entAddress1 = wallet.getEntAddress(1);
 
System.out.println("Enterprise Address 0: " + entAddress0.getAddress());
System.out.println("Enterprise Address 1: " + entAddress1.getAddress());

Multi-Account Management

Manage multiple accounts within a single wallet:


// Get addresses for different accounts
Address account0Address = wallet.getBaseAddress(0, 0); // Account 0, Index 0
Address account1Address = wallet.getBaseAddress(1, 0); // Account 1, Index 0
Address account2Address = wallet.getBaseAddress(2, 0); // Account 2, Index 0
 
// Switch between accounts
wallet.setAccountNo(0); // Switch to account 0
Address currentAccountAddress = wallet.getBaseAddress(0);
 
wallet.setAccountNo(1); // Switch to account 1
Address newAccountAddress = wallet.getBaseAddress(0);

Account Object Access

Get Account objects for transaction operations:


// Get account at specific index for current account number
Account account0 = wallet.getAccountAtIndex(0);
Account account1 = wallet.getAccountAtIndex(1);
 
// Get account for specific account number and index
Account specificAccount = wallet.getAccount(1, 5); // Account 1, Index 5
 
// Use accounts for transaction signing
String accountAddress = account0.baseAddress();
Transaction signedTx = account0.sign(transaction);

Advanced Usage

Privacy-Enhanced Address Generation

HD wallets naturally support enhanced privacy by generating a new address for each transaction. Simply increment the address index when requesting a new receiving address:


// Generate a fresh address for each transaction
Address address0 = wallet.getBaseAddress(0); // First transaction
Address address1 = wallet.getBaseAddress(1); // Second transaction
Address address2 = wallet.getBaseAddress(2); // Third transaction

Wallet Recovery and Scanning

Implement wallet recovery with address scanning:


// Configure wallet scanning
DefaultWallet wallet = new DefaultWallet(Networks.testnet());
 
// Set gap limit for address scanning
wallet.setGapLimit(50); // Scan 50 consecutive empty addresses
 
// Set specific indexes to scan (bypass gap limit)
wallet.setIndexesToScan(new int[]{0, 1, 2, 5, 10, 20});
 
// Scan for used addresses
public List<Address> scanForUsedAddresses(Wallet wallet, UtxoSupplier utxoSupplier) {
    List<Address> usedAddresses = new ArrayList<>();
    int gapCount = 0;
    int index = 0;
 
    while (gapCount < wallet.getGapLimit()) {
        Address address = wallet.getBaseAddress(index);
        List<Utxo> utxos = utxoSupplier.getAll(address.getAddress());
 
        if (!utxos.isEmpty()) {
            usedAddresses.add(address);
            gapCount = 0; // Reset gap counter
        } else {
            gapCount++;
        }
        index++;
    }
 
    return usedAddresses;
}

Key Management

Access and manage wallet keys securely:


// Get root key pair (if available)
Optional<HdKeyPair> rootKeyPair = wallet.getRootKeyPair();
if (rootKeyPair.isPresent()) {
    HdKeyPair keyPair = rootKeyPair.get();
    System.out.println("Root key available");
}
 
// Get root private key bytes
Optional<byte[]> rootPrivateKey = wallet.getRootPvtKey();
if (rootPrivateKey.isPresent()) {
    byte[] keyBytes = rootPrivateKey.get();
    System.out.println("Root private key: " + keyBytes.length + " bytes");
}
 
// Get stake address for delegation
String stakeAddress = wallet.getStakeAddress();
System.out.println("Stake Address: " + stakeAddress);

Transaction Signing

Sign transactions with wallet UTXOs:


// Sign transaction with specific UTXOs
Set<WalletUtxo> walletUtxos = getWalletUtxos(); // Your UTXO collection logic
Transaction signedTx = wallet.sign(transaction, walletUtxos);
 
// Sign with stake key
Transaction stakeSignedTx = wallet.signWithStakeKey(transaction);
 
// Combined signing
Transaction fullySignedTx = wallet.sign(
    wallet.signWithStakeKey(transaction),
    walletUtxos
);

Best Practices

Secure Wallet Creation


// Generate wallet securely
Wallet secureWallet = Wallet.create(Networks.mainnet());
String mnemonic = secureWallet.getMnemonic();
 
// Store mnemonic securely (encrypted storage recommended)
// Never store mnemonic in plain text
storeSecurely(mnemonic);
 
// Recreate wallet when needed
Wallet restoredWallet = Wallet.createFromMnemonic(Networks.mainnet(), mnemonic);

Address Management Strategy

Use different account numbers to organize addresses by purpose:


// Receiving addresses (account 0)
Address receivingAddr = wallet.getBaseAddress(0, 0);
 
// Change addresses (account 1)
Address changeAddr = wallet.getBaseAddress(1, 0);
 
// Business addresses (account 2)
Address businessAddr = wallet.getBaseAddress(2, 0);

HD Wallet vs Account API Comparison

Feature	HD Wallet API	Account API
Key Management	Hierarchical key derivation	Single key pair
Address Generation	Multiple derived addresses	Fixed addresses
Privacy	High (new address per transaction)	Limited
Use Case	Privacy-focused applications	Simple applications
Complexity	Medium to High	Low
Multi-Account	Native support	Manual management

Use Account API if your application is using only one address or account.