sigil-validator-agent · snapshot_builder

Source: sigil/node/sigil-validator-agent/src/snapshot_builder.rs. SHA-256: ae94b7b30c2d1e310eddc9345e923dea36ceeb92a953457e3ceed7d09c047d13.

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.

snapshot_builder::SnapshotBuilder

Build a [SnapshotView] for the given event.

The snapshot's block_height should reflect the block in which the event occurred. The set of keys included must be a superset of every required key declared by the rules in rule_set's metadata; the runtime relies on this to avoid running rules against incomplete views.

#[async_trait]
pub trait SnapshotBuilder: Send + Sync {
    async fn build(&self, event: &ChainEvent, rule_set: &RuleSet) -> Result<SnapshotView>;
}

Source line: 50.

snapshot_builder::MockSnapshotBuilder

Mock builder for tests. Holds a pre-populated snapshot in memory and returns it (with the event's block height applied) for every call. The snapshot itself is supplied at construction; the same snapshot is returned regardless of rule_set content.

pub struct MockSnapshotBuilder {

}

Source line: 58.

snapshot_builder::MockSnapshotBuilder::new

pub fn new(base: SnapshotView) -> Self;

Source line: 63.

snapshot_builder::MockSnapshotBuilder::replace

pub fn replace(&self, view: SnapshotView);

Source line: 69.

snapshot_builder::SnapshotFileSchema

On-disk JSON description of a snapshot view, parsed by [JsonFileSnapshotBuilder].

File format

{
  "block_height": 100,
  "block_hash_hex": "0000000000000000000000000000000000000000000000000000000000000000",
  "entries": {
    "metric:avg_gas_per_block:last_64": "e803000000000000",
    "lineage_depth:abcd...": "05000000"
  }
}

entries values are hex-encoded bytes — operators write raw byte strings in hex because the on-chain format for many keys is little-endian fixed-width integers (e.g., e803000000000000 is 1000u64 LE). The hex-encoded format is operator-readable and avoids forcing operators to write base64.

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SnapshotFileSchema {
pub block_height: u64,
/// Hex-encoded BLAKE3-32 block hash. Must be exactly 64 hex chars.

pub block_hash_hex: String,
/// Map of snapshot key → hex-encoded byte value.

#[serde(default)]
pub entries: std::collections::BTreeMap<String, String>
}

Source line: 118.

snapshot_builder::SnapshotFileSchema::into_view

pub fn into_view(self) -> std::result::Result<SnapshotView, String>;

Source line: 128.

snapshot_builder::JsonFileSnapshotBuilder

Snapshot builder that loads a single snapshot view from a JSON file. Useful for offline analysis (the simulate subcommand) and for reproducible test runs. The same view is returned for every event, with the event's block_height applied to Transaction events.

pub struct JsonFileSnapshotBuilder {

}

Source line: 171.

snapshot_builder::JsonFileSnapshotBuilder::load_from

pub fn load_from(path: impl AsRef<Path>) -> std::result::Result<Self, String>;

Source line: 177.

snapshot_builder::JsonFileSnapshotBuilder::source

pub fn source(&self) -> &Path;

Source line: 190.