Package com.privatechain.network.peer

Class Peer

java.lang.Object
com.privatechain.network.peer.Peer
public final class Peer extends Object
Immutable value object representing a remote peer node in the private blockchain network.

A Peer encapsulates all the addressing and identity information needed to establish and maintain a TCP connection to another network participant. It is used by PeerManager to track the set of known nodes and by NodeClient to open outbound connections (design.md ยง3, FR-NET-01).

Identity vs address

The nodeId is a stable logical identifier (e.g., a hex-encoded public key hash) that persists across reconnections. The host/port pair is the current physical location of the peer, which may change if the peer restarts on a different address.

Usage


 Peer peer = Peer.builder()
     .nodeId("ab12cd34ef56...")
     .host("192.168.1.10")
     .port(8545)
     .publicKeyHex("04aabb...")
     .build();

 // Record a heartbeat
 Peer refreshed = peer.withLastSeen(Instant.now());
Since:
1.0.0
See Also:

  • Method Details

    • builder

      public static Peer.Builder builder()
      Returns a new Peer.Builder for constructing a Peer.
      Returns:
      a fresh, empty builder

    • getNodeId

      public String getNodeId()
      Returns the stable logical identifier of this peer.
      Returns:
      non-null, non-blank node ID

    • getHost

      public String getHost()
      Returns the hostname or IP address of this peer.
      Returns:
      non-null, non-blank host string

    • getPort

      public int getPort()
      Returns the TCP port on which this peer's node server listens.
      Returns:
      port in range [1024, 65535]

    • getPublicKeyHex

      public String getPublicKeyHex()
      Returns the hex-encoded secp256k1 public key of this peer.

      May return null if the key exchange handshake has not yet completed (e.g., for a freshly discovered peer).

      Returns:
      hex-encoded public key, or null before handshake

    • getLastSeen

      public Instant getLastSeen()
      Returns the UTC instant of the most recent heartbeat or message exchange.

      Returns null for peers that have been added to the peer list but have not yet been contacted.

      Returns:
      last-seen timestamp, or null

    • getAddress

      public String getAddress()
      Returns the network address in host:port notation.
      Returns:
      formatted address string (e.g. "192.168.1.10:8545")

    • withLastSeen

      public Peer withLastSeen(Instant lastSeen)
      Returns a new Peer with the lastSeen field updated to the given instant.

      All other fields are carried over unchanged. This method is used by PeerManager on every successful heartbeat or message exchange.

      Parameters:
      lastSeen - updated last-seen timestamp (non-null)
      Returns:
      new Peer instance with updated timestamp
      Throws:
      NullPointerException - if lastSeen is null

    • withPublicKey

      public Peer withPublicKey(String publicKeyHex)
      Returns a new Peer with the public key filled in after handshake.
      Parameters:
      publicKeyHex - hex-encoded secp256k1 public key (non-null, non-blank)
      Returns:
      new Peer instance with populated public key
      Throws:
      NullPointerException - if publicKeyHex is null
      IllegalArgumentException - if publicKeyHex is blank

    • equals

      public boolean equals(Object obj)
      Two peers are equal if and only if their nodeIds are equal.
      Overrides:
      equals in class Object
      Parameters:
      obj - the object to compare
      Returns:
      true if both peers have the same node ID

    • hashCode

      public int hashCode()
      Hash code based solely on nodeId for consistency with equals(java.lang.Object).
      Overrides:
      hashCode in class Object
      Returns:
      hash code

    • toString

      public String toString()
      Returns a human-readable summary of this peer (safe for logging).
      Overrides:
      toString in class Object
      Returns:
      string representation