Struct TreeState 

pub struct TreeState { /* private fields */ }

Local spanning tree state for a node.

Contains this node’s declaration, coordinates, and view of peers’ tree positions. State is bounded by O(P × D) where P is peer count and D is tree depth.

Implementations

impl TreeState

pub fn new(my_node_addr: NodeAddr) -> Self

Create initial tree state for a node (as root candidate).

The node starts as its own root until it learns of a smaller node_addr. Initial sequence is 1 per protocol spec; timestamp is current Unix time.

pub fn my_node_addr(&self) -> &NodeAddr

Get this node’s NodeAddr.

pub fn my_declaration(&self) -> &ParentDeclaration

Get this node’s current declaration.

pub fn my_coords(&self) -> &TreeCoordinate

Get this node’s current coordinates.

pub fn root(&self) -> &NodeAddr

Get the current root.

pub fn is_root(&self) -> bool

Check if this node is currently the root.

pub fn peer_coords(&self, peer_id: &NodeAddr) -> Option<&TreeCoordinate>

Get coordinates for a peer, if known.

pub fn peer_declaration(&self, peer_id: &NodeAddr) -> Option<&ParentDeclaration>

Get declaration for a peer, if known.

pub fn peer_count(&self) -> usize

Number of known peers.

pub fn peer_ids(&self) -> impl Iterator<Item = &NodeAddr>

Iterate over all peer node IDs.

pub fn update_peer( &mut self, declaration: ParentDeclaration, ancestry: TreeCoordinate, ) -> bool

Add or update a peer’s tree state.

Returns true if the state was updated (new or fresher declaration).

pub fn remove_peer(&mut self, peer_id: &NodeAddr)

Remove a peer from the tree state.

pub fn set_parent( &mut self, parent_id: NodeAddr, sequence: u64, timestamp: u64, ) -> bool

Update this node’s parent selection.

Call this when switching parents. Updates the declaration and coordinates. Returns true if flap dampening was just engaged due to this switch. Only records a flap when the parent actually changes.

pub fn recompute_coords(&mut self)

Update this node’s coordinates based on current parent’s ancestry.

Defensive: if extending the parent’s ancestry would put self at the minimum (because self is smaller than the parent’s root), the declaration is demoted to self-root in place. The caller is responsible for re-signing the declaration after this call (do set_parent → recompute_coords → sign_declaration, not set_parent → sign_declaration → recompute_coords).

pub fn smallest_visible_root(&self) -> Option<NodeAddr>

Smallest root_id visible across known peers.

pub fn should_be_root(&self) -> bool

Whether this node should be the tree root: either there are no peers, or our NodeAddr is <= every visible root.

pub fn become_root(&mut self)

Promote self to root with an incremented sequence number.

Caller must sign_declaration afterwards before sending the result.

pub fn distance_to_peer(&self, peer_id: &NodeAddr) -> Option<usize>

Calculate tree distance to a peer.

pub fn find_next_hop(&self, dest_coords: &TreeCoordinate) -> Option<NodeAddr>

Find the best next hop toward a destination using greedy tree routing.

Returns the peer that minimizes tree distance to the destination, but only if that peer is strictly closer than we are (prevents routing loops at local minima). Tie-breaks equal distance by smallest node_addr.

Returns None if:

• No peers have coordinates
• Destination is in a different tree (different root)
• No peer is closer to the destination than we are

pub fn set_parent_hysteresis(&mut self, hysteresis: f64)

Set the parent hysteresis factor (0.0-1.0).

pub fn set_hold_down(&mut self, secs: u64)

Set the hold-down duration after parent switches.

pub fn set_flap_dampening( &mut self, threshold: u32, window_secs: u64, dampening_secs: u64, )

Configure flap dampening parameters.

pub fn record_parent_switch(&mut self) -> bool

Record a parent switch for flap detection. Returns true if dampening was just engaged.

pub fn is_flap_dampened(&self) -> bool

Check if flap dampening is currently active.

pub fn evaluate_parent( &self, peer_costs: &HashMap<NodeAddr, f64>, ) -> Option<NodeAddr>

Evaluate whether to switch parents based on current peer tree state.

Uses effective_depth (depth + link_cost) for parent comparison. peer_costs maps each peer’s NodeAddr to its link cost (from local MMP measurements). Missing entries default to 1.0 (optimistic).

Returns Some(peer_node_addr) if a parent switch is recommended, or None if the current parent is adequate.

pub fn handle_parent_lost( &mut self, peer_costs: &HashMap<NodeAddr, f64>, ) -> bool

Handle loss of current parent.

Tries to find an alternative parent among remaining peers. If none available, becomes its own root (increments sequence).

Returns true if the tree state changed (caller should re-announce).

pub fn sign_declaration(&mut self, identity: &Identity) -> Result<(), TreeError>

Sign this node’s declaration with the given identity.

The identity’s node_addr must match this TreeState’s node_addr.

pub fn is_declaration_signed(&self) -> bool

Check if this node’s declaration is signed.

Trait Implementations

impl Debug for TreeState

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

Formats the value using the given formatter.