Struct DigPeer 

pub struct DigPeer { /* private fields */ }

A connected DIG Network peer — the client every consumer uses.

Obtain one with DigPeer::connect. It owns the underlying mTLS PeerConnection, the local and remote peer_ids, the peer’s captured BLS-G1 key (the seal target), and an optional SealingIdentity for directed calls. Each RPC opens a fresh multiplexed stream, so calls are naturally concurrent-safe against the mux; the &mut self receiver serializes them per client.

Implementations

impl DigPeer

pub async fn connect(peer: &PeerTarget, tls: &Arc<NodeCert>) -> Result<Self>

Connect to peer, driving the Direct traversal tier only (the convenience entry point for a publicly-reachable peer / loopback). A NAT’d peer needing the full ladder uses Self::connect_with_runtime.

tls is this node’s mTLS NodeCert; the handshake pins the remote to PeerTarget::peer_id (see the crate-level security note). Captures the peer’s BLS-G1 key for sealing.

Errors

DigPeerError::Transport if the peer is unreachable or the peer_id pin fails.

pub async fn connect_with_runtime( peer: &PeerTarget, tls: &Arc<NodeCert>, config: &NatConfig, runtime: &NatRuntime, ) -> Result<Self>

Connect to peer, auto-composing the full NAT-traversal ladder from config + the live runtime handles (direct → UPnP → NAT-PMP → PCP → hole-punch → relayed, IPv6-first). The caller never chooses the method — dig-nat picks the first tier that establishes a peer_id-verified mTLS connection.

Errors

DigPeerError::Transport if no tier could be composed or every composed tier failed.

pub fn from_connection(local_peer_id: NatPeerId, conn: PeerConnection) -> Self

Wrap an already-established PeerConnection as a DigPeer, recording this node’s own peer_id (local_peer_id, the sender identity for directed seals).

Useful for a serving node that accepted an inbound dig-nat connection and wants the typed-RPC client surface over it, without re-dialing.

Unlike Self::connect_with_runtime, this does NOT run the [verify_pinned_peer_id] defense-in-depth check: an accepted inbound connection has no caller-pinned target to compare against — its remote peer_id is captured from the verified handshake (conn.peer_id), not pinned by this node. The mTLS handshake still authenticated that identity; there is simply no expected value to assert equality against.

pub fn with_sealing_identity(self, sealing: SealingIdentity) -> Self

Attach a SealingIdentity so this client can make directed (sealed) RPC calls. Without one, directed calls fail with DigPeerError::NoSealingIdentity.

pub fn peer_id(&self) -> PeerId

The verified remote peer_id.

pub fn peer_bls_pub(&self) -> Option<[u8; 48]>

The peer’s verified BLS-G1 identity (the seal target), or None for an unbound peer.

pub fn state(&self) -> PeerState

The connection lifecycle state.

pub fn is_sealable(&self) -> bool

Whether directed sealed RPC is possible right now (the peer is bound AND a sealing identity is configured).

pub async fn health(&mut self) -> Result<Health>

dig.health — liveness + capability summary. Public-read (unsealed).

Errors

DigPeerError on transport/protocol failure or a peer RPC error.

pub async fn methods(&mut self) -> Result<Methods>

dig.methods — the method names this peer implements (agent self-describe). Public-read.

Errors

DigPeerError on transport/protocol failure or a peer RPC error.

pub async fn get_network_info(&mut self) -> Result<NetworkInfo>

dig.getNetworkInfo — this peer’s own network posture. Directed (sealed §5.4).

Errors

DigPeerError::PeerNotSealable/DigPeerError::NoSealingIdentity if sealing is impossible; otherwise transport/protocol/seal failures or a peer RPC error.

pub async fn get_peers(&mut self) -> Result<PeersList>

dig.getPeers — the peers this peer knows (peer exchange). Directed (sealed §5.4).

Errors

As Self::get_network_info.

pub async fn announce(&mut self, params: &AnnounceParams) -> Result<AnnounceAck>

dig.announce — announce this node’s presence to the peer. Directed (sealed §5.4).

Errors

As Self::get_network_info.

pub async fn get_availability( &mut self, items: Vec<AvailabilityItem>, ) -> Result<AvailabilityResponse>

dig.getAvailability — batch presence pre-check across stores/roots/capsules. Public content presence (unsealed §5.4 exemption); delegates to the dig-nat mux availability primitive.

Errors

DigPeerError::Io on stream failure; DigPeerError::InvalidState after disconnect.

pub async fn fetch_range(&mut self, req: &RangeRequest) -> Result<PeerStream>

dig.fetchRange — open a byte-range stream for req (public merkle-verified content, unsealed §5.4 exemption); delegates to the dig-nat mux range primitive. Returns the raw stream the caller reads dig_nat::RangeFrames from.

Errors

DigPeerError::Io on stream failure; DigPeerError::InvalidState after disconnect.

pub async fn open_stream(&mut self) -> Result<PeerStream>

Open a generic raw multiplexed stream over the (already-established, mTLS-authenticated) connection and hand it to the caller — the unsealed raw-stream escape hatch for a consumer that carries its OWN wire framing rather than dig-peer’s typed RPC methods.

This is the same authenticated mux path Self::fetch_range and the internal RPC calls ride; it performs NO framing, NO JSON, and NO sealing — the bytes on the wire are entirely the caller’s. It exists because a same-level (L20) consumer (e.g. dig-dht, whose DhtRequest dig-peer cannot typed-wrap without an illegal same-level dependency) must encode/decode its own frame over the authenticated connection.

Unsealed, by design. Like content/Self::fetch_range, the stream rides mTLS but is NOT end-to-end sealed. Directed/secret messages MUST use the sealed typed methods (Self::get_network_info, Self::get_peers, Self::announce) — never this escape hatch. A caller that puts recipient-specific secret content on this stream is responsible for its own §5.4 sealing; dig-peer does not seal it.

Errors

DigPeerError::Io on stream failure; DigPeerError::InvalidState after disconnect.

pub async fn disconnect(self)

Cleanly tear down the connection. Once closed, RPCs fail with DigPeerError::InvalidState. Dropping the underlying session ends the mux driver and closes the mTLS byte stream.

Trait Implementations

impl Debug for DigPeer

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.