sigil-tower · types

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct TowerBlock {
pub header: TowerBlockHeader,
pub body: TowerBlockBody
}

pub fn hash(&self) -> SigilHash;

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct TowerBlockHeader {
/// Hash of the parent Tower block.

pub parent_hash: SigilHash,
/// Slot number for this block.

pub slot: u64,
/// Epoch this slot belongs to.

pub epoch: u64,
/// OAS DID of the block proposer.

pub proposer_did: String,
/// Merkle root of committee assignments for this slot.

pub committee_root: SigilHash,
/// Optional finality checkpoint included in this block.

pub finality_checkpoint: Option<FinalityCheckpoint>,
/// Unix timestamp when this block was produced.

pub timestamp: u64,
/// Chain identifier.

pub chain_id: String
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct TowerBlockBody {
/// Committee votes for previous slots.

pub committee_votes: Vec<CommitteeVote>,
/// Finality votes (Casper FFG attestations).

pub finality_votes: Vec<FinalityVote>,
/// Slashing evidence submitted in this block.

pub evidence: Vec<SlashingEvidence>,
/// Validator set updates (registrations, exits, etc.).

pub validator_updates: Vec<ValidatorUpdate>
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ValidatorRecord {
/// OAS DID of this validator entity.

pub did: String,
/// Ed25519 consensus public key.

pub public_key: Vec<u8>,
/// Staked amount in micro-MINT.

pub stake: u64,
/// Whether this validator is a Block Producer or Block Validator.

pub mode: ValidatorMode,
/// Geographic region for diversity enforcement.

pub geographic_region: GeographicRegion,
/// Composite inclusion score (computed from 6 components).

pub inclusion_score: f64,
/// Current lifecycle status.

pub status: ValidatorStatus,
/// Epoch at which this validator became active.

pub activation_epoch: u64,
/// Epoch at which this validator exited (if exited).

pub exit_epoch: Option<u64>,
/// Epoch through which a slashed validator is jailed and excluded.

#[serde(default, skip_serializing_if = "Option::is_none")]
pub slashed_until_epoch: Option<u64>,
/// OAS DID of the human root in the lineage chain.

pub human_root_did: Option<String>
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub enum ValidatorStatus {
    /// Awaiting activation (e.g., pending epoch boundary).
    Pending,
    /// Actively participating in consensus.
    Active,
    /// Has requested exit; still active until epoch boundary.
    Exiting,
    /// Fully exited; no longer in active set.
    Exited,
    /// Slashed and removed from active set.
    Slashed,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub enum GeographicRegion {
    NorthAmerica,
    SouthAmerica,
    Europe,
    Asia,
    Africa,
    Oceania,
    MiddleEast,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct FinalityCheckpoint {
/// The epoch this checkpoint covers.

pub epoch: u64,
/// Hash of the block at the checkpoint boundary.

pub block_hash: SigilHash,
/// Whether this checkpoint has been justified (2/3 supermajority).

pub justified: bool,
/// Whether this checkpoint has been finalized.

pub finalized: bool
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct FinalityVote {
/// OAS DID of the voting validator.

pub voter_did: String,
/// Source epoch (must be a justified checkpoint).

pub source_epoch: u64,
/// Target epoch being voted for.

pub target_epoch: u64,
/// Hash of the target block.

pub target_hash: SigilHash,
/// Stake weight of this vote.

pub stake: u64,
/// Ed25519 signature over the vote content.

pub signature: Vec<u8>
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct SlotInfo {
/// Slot number.

pub slot: u64,
/// Epoch this slot belongs to.

pub epoch: u64,
/// Unix timestamp of the slot start.

pub timestamp: u64,
/// OAS DID of the assigned proposer, if any.

pub proposer_did: Option<String>
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct CommitteeVote {
/// OAS DID of the voter.

pub voter_did: String,
/// The slot being voted on.

pub slot: u64,
/// Hash of the block being attested.

pub block_hash: SigilHash,
/// Ed25519 signature.

pub signature: Vec<u8>
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub enum EvidenceType {
    /// Validator signed two different blocks at the same slot.
    DoubleSign {
        slot: u64,
        block_hash_a: SigilHash,
        block_hash_b: SigilHash,
    },
    /// Validator proposed an invalid block.
    InvalidBlock {
        slot: u64,
        block_hash: SigilHash,
        reason: String,
    },
    /// Validator was offline for an extended period.
    Downtime {
        validator_did: String,
        missed_slots: u64,
    },
    /// Validator cast two conflicting finality votes (surround vote).
    SurroundVote {
        vote_a: FinalityVote,
        vote_b: FinalityVote,
    },
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct SlashingEvidence {
/// The type and proof data of the offense.

pub evidence_type: EvidenceType,
/// OAS DID of the offending validator.

pub subject_did: String,
/// OAS DID of the entity submitting the evidence.

pub submitter_did: String,
/// Unix timestamp when the evidence was created.

pub timestamp: u64,
/// BLAKE3 hash of the evidence payload.

pub evidence_hash: SigilHash
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub enum ValidatorUpdate {
    /// Register a new validator.
    Register(ValidatorRecord),
    /// Update an existing validator's stake.
    StakeChange { did: String, new_stake: u64 },
    /// Update an existing validator's status.
    StatusChange {
        did: String,
        new_status: ValidatorStatus,
    },
    /// Update an existing validator's inclusion score.
    ScoreUpdate { did: String, new_score: f64 },
    /// Exit a validator from the active set.
    Exit { did: String, exit_epoch: u64 },
}