Package com.privatechain.wallet

Class WalletManager

java.lang.Object
com.privatechain.wallet.WalletManager
public final class WalletManager extends Object
Manager for creating, importing, and persisting wallets with encrypted keystores.

WalletManager provides a high-level interface for wallet lifecycle: creating new wallets, importing existing wallets from private keys, and serializing/deserializing wallets to/from encrypted keystore files (FR-WALLET-02).

Keystore format

Wallets are persisted using a simplified Web3 Secret Storage v3 format: AES-256-CTR encryption with PBKDF2-derived encryption keys. The keystore is a JSON file containing the encrypted private key and all necessary metadata for reconstruction (FR-WALLET-03).

Thread safety

Access to the internal wallet map is synchronized. However, individual Wallet objects returned by this class are immutable and inherently thread-safe.

Since:
1.0.0
See Also:

  • Constructor Details

    • WalletManager

      public WalletManager()
      Constructs an empty wallet manager.

  • Method Details

    • createWallet

      public Wallet createWallet()
      Creates a new wallet with a randomly generated key pair.
      Returns:
      a new Wallet

    • importWallet

      public Wallet importWallet(String privateKeyHex)
      Imports a wallet from a hex-encoded private key.
      Parameters:
      privateKeyHex - lowercase hex-encoded PKCS#8 private key (non-null, non-blank)
      Returns:
      the imported Wallet
      Throws:
      NullPointerException - if privateKeyHex is null
      IllegalArgumentException - if privateKeyHex is blank or invalid

    • getWallet

      public Optional<Wallet> getWallet(String address)
      Retrieves a wallet by its address.
      Parameters:
      address - the blockchain address to look up (non-null)
      Returns:
      an Optional containing the wallet, or empty if not found
      Throws:
      NullPointerException - if address is null

    • getAllWallets

      public Collection<Wallet> getAllWallets()
      Returns all wallets managed by this manager.
      Returns:
      unmodifiable collection of wallets

    • size

      public int size()
      Returns the number of wallets managed by this manager.
      Returns:
      non-negative integer

    • removeWallet

      public boolean removeWallet(String address)
      Removes a wallet from this manager by address.
      Parameters:
      address - the address to remove (non-null)
      Returns:
      true if a wallet was present and removed

    • exportKeystore

      public String exportKeystore(Wallet wallet, String password)
      Exports a wallet to an encrypted keystore JSON string.

      The keystore uses Web3 Secret Storage v3 format with AES-256-CTR encryption and a PBKDF2-derived key (FR-WALLET-03).

      Parameters:
      wallet - the wallet to export (non-null)
      password - the encryption password (non-null, non-blank)
      Returns:
      JSON keystore string
      Throws:
      NullPointerException - if wallet or password is null
      IllegalArgumentException - if password is blank

    • importFromKeystore

      public Wallet importFromKeystore(String keystoreJson, String password)
      Imports a wallet from an encrypted keystore JSON string.

      The keystore must have been created by exportKeystore(Wallet, String) or be compatible with Web3 Secret Storage v3 format.

      Parameters:
      keystoreJson - the keystore JSON string (non-null, non-blank)
      password - the decryption password (non-null, non-blank)
      Returns:
      the imported Wallet
      Throws:
      NullPointerException - if keystoreJson or password is null
      IllegalArgumentException - if keystoreJson or password is blank, or if decryption fails

    • clear

      public void clear()
      Clears all wallets from this manager.