Package com.privatechain.wallet

Class Wallet

java.lang.Object
com.privatechain.wallet.Wallet
public final class Wallet extends Object
Immutable wallet holding an EC key pair, a derived blockchain address, and performing transaction signing and balance queries.

A wallet is the primary interface for end-users to interact with the blockchain. It holds a secp256k1 key pair, derives a unique blockchain address from the public key, and provides methods to sign transactions and compute balances (FR-WALLET-01, FR-WALLET-04).

Key management

The wallet's private key is never exposed via public API. Instead, callers invoke sign(Transaction) to produce a signed transaction. The private key is accessible only to trusted code during import/export operations.

Address derivation

The blockchain address is derived once during construction via AddressUtil.deriveAddress(java.security.PublicKey) and is immutable.

Thread safety

Wallet is immutable; all methods are thread-safe.

Since:
1.0.0
See Also:

  • Method Details

    • getAddress

      public String getAddress()
      Returns the blockchain address derived from this wallet's public key.
      Returns:
      non-null, Base58Check-encoded address

    • sign

      public Transaction sign(Transaction transaction)
      Signs a transaction with this wallet's private key.

      The transaction is modified in-place (signature bytes are attached). The signer's address should match getAddress(), but this is not enforced here — that validation occurs in the consensus layer.

      Parameters:
      transaction - the transaction to sign (non-null)
      Returns:
      the same transaction, now with a signature attached
      Throws:
      NullPointerException - if transaction is null
      IllegalStateException - if signing fails (e.g., invalid key)

    • getBalance

      public BigDecimal getBalance(Blockchain blockchain)
      Computes the balance of this wallet by scanning the blockchain for all confirmed transactions involving this address.

      The balance is the sum of all incoming transactions minus the sum of all outgoing transactions. Only transactions that have been included in a block are counted (FR-WALLET-04).

      Parameters:
      blockchain - the blockchain to query (non-null)
      Returns:
      the wallet's balance as a non-negative BigDecimal
      Throws:
      NullPointerException - if blockchain is null

    • toString

      public String toString()
      Returns a human-readable summary of the wallet.

      The private key is never included in the output (NFR-SEC-01).

      Overrides:
      toString in class Object
      Returns:
      string representation

    • equals

      public boolean equals(Object obj)
      Two wallets are equal if they derive the same address.
      Overrides:
      equals in class Object
      Parameters:
      obj - object to compare
      Returns:
      true if obj is a Wallet with the same address

    • hashCode

      public int hashCode()
      Hash code based on the wallet's address.
      Overrides:
      hashCode in class Object
      Returns:
      hash code