sigil-network · message

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct NetworkMessage {
/// Unique message identifier (UUID v4 recommended).

pub id: String,
/// OAS DID of the sender.

pub sender_did: String,
/// Unix timestamp (seconds) when the message was created.

pub timestamp: u64,
/// The type-tagged payload.

pub payload: MessagePayload
}

pub fn content_hash(&self) -> Result<SigilHash, serde_json::Error>;

#[allow(clippy::large_enum_variant)]
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "kind", content = "data")]
pub enum MessagePayload {
    // -- Gossipsub ----------------------------------------------------------
    /// A newly produced block announcement.
    NewBlock(BlockAnnouncement),
    /// One erasure shard of a newly produced block.
    BlockShard(BlockShardAnnouncement),
    /// A new transaction entering the mempool.
    NewTransaction(TransactionAnnouncement),
    /// A pre-vote from the consensus layer.
    PreVote(PreVoteMessage),
    /// A pre-commit from the consensus layer.
    PreCommit(PreCommitMessage),
    /// A compute receipt announcement (feature-gated).
    #[cfg(feature = "compute")]
    ComputeReceipt(ComputeReceiptMessage),

    // -- Request / Response -------------------------------------------------
    /// Request a range of blocks for sync.
    BlockRequest(BlockSyncRequest),
    /// Response containing a batch of blocks.
    BlockResponse(BlockSyncResponse),
    /// Request a slice of the state trie.
    StateRequest(StateSyncRequest),
    /// Response containing state key-value pairs.
    StateResponse(StateSyncResponse),
    /// Request peer metadata.
    PeerInfoRequest(PeerInfoRequest),
    /// Response with peer metadata.
    PeerInfoResponse(PeerInfoResponse),

    // -- Tower Coordination -------------------------------------------------
    /// A newly produced Tower block announcement.
    TowerBlock(TowerBlockAnnouncement),
    /// A Tower Committee vote on a proposal (slashing, param change, etc.).
    TowerCommitteeVote(TowerCommitteeVoteMessage),
    /// Slashing evidence submitted to the Tower chain.
    TowerSlashingEvidence(TowerSlashingEvidenceMessage),
    /// A Casper FFG finality vote.
    TowerFinalityVote(TowerFinalityVoteMessage),
    /// A Tower Casper FFG attestation from an execution-chain validator.
    ///
    /// Broadcast on [`GossipTopic::TowerAttestations`] at every epoch
    /// boundary by any validator that is a member of the Tower committee.
    /// Recipients verify the signature, persist the vote via
    /// `commit_tower_tx`, and apply the Casper FFG rules to advance
    /// [`sigil_tower::finality::FinalityState`].
    TowerAttestation(TowerAttestationMessage),

    // -- CZAC Cross-Zone Communication --------------------------------------
    /// CZAC channel operation message (open, close, heartbeat).
    CzacChannelOp(CzacChannelOpMessage),
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct BlockAnnouncement {
/// The full block.

pub block: Block,
/// Ed25519 signature of the block hash by the proposer.

pub proposer_signature: Vec<u8>
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct BlockShardAnnouncement {
/// Shard metadata and bytes.

pub shard: BlockPropagationShard,
/// Ed25519 signature of `(block_hash || shard_index || payload_hash)` by

/// the proposer. Signature verification is transport-layer specific.

pub proposer_signature: Vec<u8>
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct TransactionAnnouncement {
/// The signed transaction.

pub tx: SignedTransaction
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct PreVoteMessage {
/// The block height being voted on.

pub height: u64,
/// Hash of the block being voted for.

pub block_hash: SigilHash,
/// OAS DID of the voter.

pub voter_did: String,
/// Ed25519 signature of (height || block_hash).

pub signature: Vec<u8>
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct PreCommitMessage {
/// The block height being committed.

pub height: u64,
/// Hash of the block being committed.

pub block_hash: SigilHash,
/// OAS DID of the voter.

pub voter_did: String,
/// Ed25519 signature of (height || block_hash).

pub signature: Vec<u8>
}

#[cfg(feature = "compute")]
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ComputeReceiptMessage {
/// Hash of the full receipt.

pub receipt_hash: SigilHash,
/// OAS DID of the compute provider.

pub provider_did: String,
/// OAS DID of the compute consumer.

pub consumer_did: String
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct BlockSyncRequest {
/// First block height to fetch (inclusive).

pub start_height: u64,
/// Maximum number of blocks to return.

pub max_blocks: u32
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct BlockSyncResponse {
/// The requested blocks in ascending height order.

pub blocks: Vec<Block>
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct StateSyncRequest {
/// State partition identifier (e.g. "accounts", "zones").

pub partition: String,
/// Key to start scanning from (lexicographic order).

pub start_key: Vec<u8>,
/// Maximum number of entries to return.

pub limit: u32
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct StateSyncResponse {
/// Key-value pairs from the state trie.

pub entries: Vec<(Vec<u8>, Vec<u8>)>,
/// `true` if there are more entries beyond this batch.

pub has_more: bool
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct PeerInfoRequest {

}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct PeerInfoResponse {
/// The peer's unique identifier.

pub peer_id: String,
/// Chain ID the peer is on.

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

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

pub current_epoch: u64,
/// OAS DID if the peer is a registered validator.

pub validator_did: Option<String>,
/// Protocol version the peer is running.

pub protocol_version: String
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct TowerBlockAnnouncement {
/// Tower slot number.

pub slot: u64,
/// Tower epoch.

pub epoch: u64,
/// Block hash.

pub block_hash: SigilHash,
/// Proposer's OAS DID.

pub proposer_did: String,
/// Ed25519 signature by the proposer.

pub proposer_signature: Vec<u8>
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct TowerCommitteeVoteMessage {
/// Proposal ID being voted on.

pub proposal_id: String,
/// Voter's OAS DID (must be Tower Committee member).

pub voter_did: String,
/// Approve or reject.

pub approve: bool,
/// Ed25519 signature.

pub signature: Vec<u8>
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct TowerSlashingEvidenceMessage {
/// Evidence type: "double_sign", "downtime", "invalid_block", "invalid_vote".

pub evidence_type: String,
/// Accused validator DID.

pub accused_did: String,
/// Slot of the alleged offense.

pub offense_slot: u64,
/// Hash of the serialized evidence payload.

pub evidence_hash: SigilHash,
/// Submitter's DID.

pub submitter_did: String
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct TowerFinalityVoteMessage {
/// Source epoch (previously justified).

pub source_epoch: u64,
/// Target epoch.

pub target_epoch: u64,
/// Block hash at target epoch boundary.

pub target_block_hash: SigilHash,
/// Voter's OAS DID.

pub voter_did: String,
/// Ed25519 signature over (source_epoch || target_epoch || target_block_hash).

pub signature: Vec<u8>
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct TowerAttestationMessage {
/// Source epoch (must be a justified checkpoint).

pub source_epoch: u64,
/// Target epoch being attested (must be source_epoch + 1 for finalization).

pub target_epoch: u64,
/// Hash of the execution block at the target epoch boundary.

pub target_block_hash: SigilHash,
/// Stake weight of this attestation (micro-MINT).

pub stake: u64,
/// OAS DID of the attesting validator.

pub validator_did: String,
/// Ed25519 signature over `source_epoch_be8 || target_epoch_be8 || target_block_hash_bytes`.

pub signature: Vec<u8>
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct CzacChannelOpMessage {
/// Channel ID.

pub channel_id: String,
/// Operation type: "open", "close", "heartbeat", "dispute".

pub operation: String,
/// Sender's OAS DID.

pub sender_did: String,
/// Target zone.

pub target_zone: String,
/// Sequence number for ordering.

pub sequence: u64,
/// Optional payload hash.

pub payload_hash: Option<SigilHash>
}