sigil-validator-agent · event

Source: sigil/node/sigil-validator-agent/src/event.rs. SHA-256: 6d3383e3ffde44daf7eb00397a98c99fca2fa4ed350deeca4d8b7abb5d2f8c93.

This reference follows declared source modules, retains conditional attributes, and includes public declarations and implementation methods. Private-module re-exports and trait resolution require the compiler; this is a source reference, not a claim that every listed item is a root import. Function bodies and constant values are omitted.

event::TransactionEvent

Opaque transaction event from the chain.

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct TransactionEvent {
/// BLAKE3 hash of the canonical transaction bytes.

pub tx_hash: [u8; 32],
/// Canonical transaction bytes (opaque to this crate).

pub tx_bytes: Vec<u8>,
/// Block height at which the transaction was included.

pub block_height: u64,
/// Block hash at which the transaction was included.

pub block_hash: [u8; 32],
/// Epoch at which the transaction was included.

pub epoch: u64
}

Source line: 23.

event::ChainEvent

Tagged enum of chain events the runtime consumes.

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(tag = "kind", rename_all = "snake_case")]
pub enum ChainEvent {
    /// A new transaction was included in a block.
    Transaction(TransactionEvent),
    /// A new epoch began. The runtime uses this to roll the cycle
    /// budget over.
    EpochAdvance { new_epoch: u64 },
    /// The connection to the RPC node was reset; the runtime should
    /// treat any in-flight state as potentially stale.
    Reconnect,
}

Source line: 39.

event::EventStream

Trait abstracting the source of chain events. Production uses a WebSocket subscriber; tests use [MockEventStream].

#[async_trait]
pub trait EventStream: Send + Sync {
    async fn next_event(&self) -> Result<ChainEvent>;
}

Source line: 53.

event::MockEventStream

In-memory event stream for tests. Pre-populate via [Self::push].

#[derive(Default)]
pub struct MockEventStream {

}

Source line: 59.

event::MockEventStream::new

pub fn new() -> Self;

Source line: 64.

event::MockEventStream::push

pub fn push(&self, event: ChainEvent);

Source line: 68.

event::MockEventStream::push_all

pub fn push_all(&self, events: impl IntoIterator<Item = ChainEvent>);

Source line: 72.

event::MockEventStream::len

pub fn len(&self) -> usize;

Source line: 79.

event::MockEventStream::is_empty

pub fn is_empty(&self) -> bool;

Source line: 83.

event::JsonLineEventStream

Newline-delimited JSON event stream over any AsyncRead.

Each line of the underlying source is expected to deserialize to a [ChainEvent] via serde_json. The stream returns [ValidatorAgentError::EventStreamClosed] when the source reaches EOF. Malformed lines yield [ValidatorAgentError::Config] errors (since they indicate a bug in the upstream producer rather than a recoverable runtime condition).

Why this exists

Decouples the validator-agent from the specific RPC client choice. Operators wire any external fetcher (tokio-tungstenite WebSocket client, reqwest HTTP poller, sigil-rpc subscriber, ssh tunnel, etc.) to emit JSON-lines on stdout, then pipe into the validator-agent. This is a Unix-pipeline composition pattern: each component is testable in isolation and operators choose how to compose them.

Production wiring

Once Agent 05's RPC subscription surface is finalized, a sibling crate (sigil-validator-agent-rpc-bridge or similar) will provide a tokio task that subscribes to the chain via WebSocket and writes ChainEvent JSON-lines to a pipe. The validator-agent reads from the pipe via this JsonLineEventStream.

pub struct JsonLineEventStream<R: AsyncRead + Unpin + Send> {

}

Source line: 123.

event::JsonLineEventStream<R>::new

pub fn new(reader: R) -> Self;

Source line: 128.

event::JsonLineEventStream<R>::shared

Wrap an Arc for shared ownership across tasks.

pub fn shared(reader: R) -> Arc<Self>;

Source line: 135.

sigil-validator-agent · event

On this page