sigil-network · peer

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PeerInfo {
/// Unique peer identifier (e.g. libp2p PeerId).

pub peer_id: String,
/// OAS DID of the peer, if known.

pub did: Option<String>,
/// Chain ID the peer is operating on.

pub chain_id: String,
/// The peer's latest reported block height.

pub current_height: u64,
/// The peer's latest reported epoch.

pub current_epoch: u64,
/// Protocol version the peer advertised.

pub protocol_version: String,
/// Whether this peer is a registered validator.

pub is_validator: bool,
/// Reputation score in `[0.0, 1.0]`.

pub reputation_score: f64,
/// Unix timestamp of last successful communication.

pub last_seen: u64,
/// Current connection state.

pub connection_state: ConnectionState
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub enum ConnectionState {
    /// Actively connected and exchanging messages.
    Connected,
    /// Not currently connected.
    Disconnected,
    /// Connection attempt in progress.
    Connecting,
    /// Peer has been banned due to misbehaviour.
    Banned,
}

pub fn is_active(&self) -> bool;

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub enum PeerAdmission {
    /// Staked validator DID with a recent chain attestation.
    StakedValidator { did: String, attested_epoch: u64 },
    /// Operator allowlisted by launch/bootstrap configuration.
    AllowlistedBootstrap { operator_id: String },
    /// Unstaked peer proof-of-work nonce.
    ProofOfWork { nonce: u64 },
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct PeerDiversity {
pub asn: u32,
pub geo_region: String,
pub cloud_provider: String,
pub lineage_group: String
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct PeerSecurityConfig {
/// Enforce Sybil proof checks in [`PeerRegistry::add_peer_with_admission`].

pub enforce_admission: bool,
/// Current epoch for freshness checks.

pub current_epoch: u64,
/// Maximum age for validator attestations.

pub max_attestation_age_epochs: u64,
/// Minimum leading-zero PoW bits for unstaked peers.

pub min_pow_leading_zero_bits: u32,
/// Allowlisted bootstrap operator identifiers.

pub allowlisted_bootstrap_operators: HashSet<String>,
/// Enforce ASN/region/cloud diversity once enough peers are present.

pub enforce_diversity: bool,
/// Minimum distinct ASNs in the connected set.

pub min_asns: usize,
/// Minimum distinct geo regions in the connected set.

pub min_geo_regions: usize,
/// Minimum distinct cloud providers in the connected set.

pub min_cloud_providers: usize,
/// Maximum fraction of peers sharing one lineage group.

pub max_lineage_fraction: f64
}

#[derive(Debug)]
pub struct PeerRegistry {

}

pub fn new(max_peers: usize) -> Self;

pub fn with_security(max_peers: usize, security: PeerSecurityConfig) -> Self;

pub fn peer_count(&self) -> usize;

pub fn add_peer(&mut self, info: PeerInfo) -> NetworkResult<()>;

pub fn add_peer_with_admission(
        &mut self,
        info: PeerInfo,
        admission: PeerAdmission,
        diversity: Option<PeerDiversity>,
    ) -> NetworkResult<()>;

pub fn remove_peer(&mut self, peer_id: &str) -> NetworkResult<PeerInfo>;

pub fn get_peer(&self, peer_id: &str) -> Option<&PeerInfo>;

pub fn get_peer_mut(&mut self, peer_id: &str) -> Option<&mut PeerInfo>;

pub fn get_scoring(&self, peer_id: &str) -> Option<&PeerScoring>;

pub fn get_scoring_mut(&mut self, peer_id: &str) -> Option<&mut PeerScoring>;

pub fn update_peer<F>(&mut self, peer_id: &str, updater: F) -> NetworkResult<()>
    where
        F: FnOnce(&mut PeerInfo),;

pub fn connected_peers(&self) -> impl Iterator<Item = &PeerInfo>;

pub fn validator_peers(&self) -> impl Iterator<Item = &PeerInfo>;

pub fn best_peers_for_sync(&self) -> Vec<&PeerInfo>;

pub fn should_ban(&self, peer_id: &str) -> bool;

pub fn ban_peer(&mut self, peer_id: &str) -> NetworkResult<()>;

pub fn peer_ids(&self) -> Vec<String>;

pub fn decay_all_scores(&mut self, factor: f64);