Struct VanguardState 

pub struct VanguardState {
    pub layer2: Vec<GuardNode>,
    pub layer3: Vec<GuardNode>,
    pub state_file: String,
    pub rendguard: RendGuard,
    pub pickle_revision: u32,
    pub enable_vanguards: bool,
}

Persistent vanguard state containing guard layers and rendguard tracking.

Contains the layer 2 and layer 3 guard lists, along with rendguard state. This state is persisted to disk in Python pickle format for compatibility.

Guard Layers

┌─────────────────────────────────────────────────────────────────────────┐
│                         VanguardState                                   │
│                                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │ Layer 2 Guards (HSLayer2Nodes)                                  │    │
│  │ • 4-8 guards (configurable)                                     │    │
│  │ • Lifetime: 1-45 days (configurable)                            │    │
│  │ • Used for second hop in HS circuits                            │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │ Layer 3 Guards (HSLayer3Nodes)                                  │    │
│  │ • 4-8 guards (configurable)                                     │    │
│  │ • Lifetime: 1-48 hours (configurable)                           │    │
│  │ • Used for third hop in HS circuits                             │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │ RendGuard                                                       │    │
│  │ • Tracks rendezvous point usage                                 │    │
│  │ • Detects statistical attacks                                   │    │
│  └─────────────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────────┘

State File Format

The state file uses Python pickle format with the following structure:

VanguardState {
    layer2: [GuardNode, ...],
    layer3: [GuardNode, ...],
    state_file: String,
    rendguard: RendGuard,
    pickle_revision: u32,
}

Thread Safety

VanguardState is not thread-safe. It should be accessed from a single task or protected with appropriate synchronization.

Example

use vanguards_rs::vanguards::VanguardState;
use std::path::Path;

// Load existing state or create new
let mut state = VanguardState::load_or_create(Path::new("vanguards.state"));

// Check current guards
println!("Layer 2: {}", state.layer2_guardset());
println!("Layer 3: {}", state.layer3_guardset());

// Save state
state.write_to_file(Path::new("vanguards.state")).unwrap();

See Also

• GuardNode - Individual guard node
• RendGuard - Rendezvous point tracking
• crate::config::VanguardsConfig - Configuration options

Fields

layer2: Vec<GuardNode>

Layer 2 guard nodes (second hop).

layer3: Vec<GuardNode>

Layer 3 guard nodes (third hop).

state_file: String

Path to the state file.

rendguard: RendGuard

Rendezvous point usage tracking.

pickle_revision: u32

Version number for pickle compatibility.

enable_vanguards: bool

Whether vanguards are enabled (runtime flag, not persisted).

Implementations

impl VanguardState

pub fn new(state_file: &str) -> Self

Creates a new empty vanguard state.

pub fn load_or_create(path: &Path) -> Self

Loads state from a file or creates new state if the file doesn’t exist.

Arguments

• path - Path to the state file

Returns

The loaded or newly created state.

pub fn read_from_file(path: &Path) -> Result<Self>

Reads state from a pickle file with validation.

Validates that:

• All fingerprints are valid 40-character hex strings
• No timestamps are in the future (with 1 hour tolerance)
• The file format is valid

Errors

Returns Error::State if the file cannot be read, parsed, or fails validation.

pub fn validate(&self) -> Result<()>

Validates the state for integrity.

Checks:

• All fingerprints are valid 40-character hex strings
• No timestamps are in the future (with 1 hour tolerance for clock skew)

Errors

Returns Error::State if validation fails.

pub fn write_to_file(&self, path: &Path) -> Result<()>

Writes state to a pickle file with atomic write and secure permissions.

Uses atomic write (write to temp file, then rename) to prevent corruption. On Unix systems, sets file permissions to 0600 (owner read/write only).

Errors

Returns Error::State if the file cannot be written.

pub fn layer2_guardset(&self) -> String

Returns the layer 2 guard fingerprints as a comma-separated string.

pub fn layer3_guardset(&self) -> String

Returns the layer 3 guard fingerprints as a comma-separated string.

pub fn calculate_guard_lifetime(min_hours: u32, max_hours: u32) -> f64

Calculates a guard lifetime using max of two uniform random samples.

This distribution favors longer lifetimes, providing better security by reducing guard rotation frequency.

Arguments

• min_hours - Minimum lifetime in hours
• max_hours - Maximum lifetime in hours

Returns

Lifetime in seconds.

pub fn add_new_layer2( &mut self, generator: &BwWeightedGenerator, excluded: &ExcludeNodes, config: &VanguardsConfig, ) -> Result<()>

Adds a new layer 2 guard.

Selects a guard using the provided generator, avoiding duplicates and excluded nodes.

pub fn add_new_layer3( &mut self, generator: &BwWeightedGenerator, excluded: &ExcludeNodes, config: &VanguardsConfig, ) -> Result<()>

Adds a new layer 3 guard.

Selects a guard using the provided generator, avoiding duplicates and excluded nodes.

pub fn remove_down_from_layer( layer: &mut Vec<GuardNode>, consensus_fps: &HashSet<String>, )

Removes guards that are no longer in the consensus.

pub fn remove_expired_from_layer(layer: &mut Vec<GuardNode>)

Removes guards whose rotation time has expired.

pub fn remove_excluded_from_layer( layer: &mut Vec<GuardNode>, router_map: &HashMap<String, &RouterStatusEntry>, excluded: &ExcludeNodes, )

Removes guards that match the ExcludeNodes configuration.

pub fn replenish_layers( &mut self, generator: &BwWeightedGenerator, excluded: &ExcludeNodes, config: &VanguardsConfig, ) -> Result<()>

Replenishes guard layers to configured counts.

First trims layers if they exceed configured counts, then adds new guards until the configured count is reached.

Trait Implementations

impl Clone for VanguardState

fn clone(&self) -> VanguardState

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for VanguardState

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

Formats the value using the given formatter.

impl Default for VanguardState

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for VanguardState

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for VanguardState

fn eq(&self, other: &VanguardState) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for VanguardState

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for VanguardState