Sigil documentation
ReferenceRust referencesigil-node

sigil-node · bootstrap

Source declarations, signatures and documentation for bootstrap.

Source: sigil/node/sigil-node/src/bootstrap.rs. SHA-256: fa906252ae8d8694d78527fe3e0afe8073601c6401cd2d64772a6fd8ec940ba0.

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.

bootstrap::is_mainnet

Returns true when chain_id identifies a mainnet deployment.

The canonical convention is that every production chain ID begins with the prefix "sigil-mainnet-" (e.g. "sigil-mainnet-1"). Any other prefix — "sigil-testnet-", "sigil-devnet-", "sigil-canary-", etc. — is treated as a non-production network where auto-generation is still permitted.

Add new production chain IDs to the MAINNET_PREFIXES list below rather than changing the calling convention.

pub fn is_mainnet(chain_id: &str) -> bool;

Source line: 40.

bootstrap::KeySource

Describes how validator keys were obtained during this bootstrap run.

main.rs logs this so operators and monitoring can immediately distinguish the three possible key origins. A mainnet node will never log any variant other than PreProvisioned.

Implements Default (→ None) so that serde's #[serde(skip)] on BootstrapResult::key_source can reconstruct the field during deserialization without requiring KeySource to be serialized itself.

#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum KeySource {
    /// Keys were read from a pre-existing file (default path or
    /// `--validator-key-path`). This is the only source permitted on mainnet.
    PreProvisioned,
    /// Keys were freshly generated from a deterministic DID-derived seed.
    /// Only allowed on non-mainnet chains. A `tracing::warn` is emitted.
    TestnetAutoGenerated,
    /// No validator DID was supplied — this node is running in a non-validator
    /// mode (RPC, Archive, Light, Observer).
    #[default]
    None,
}

Source line: 59.

bootstrap::ValidatorKeys

Validator key material stored on disk.

On mainnet these keys must be generated by a hardware security module or secure enclave and written to the data directory before node startup. See docs/operator/validator-key-provisioning.md.

On testnet/devnet/canary networks the node may auto-generate deterministic keys from the validator DID for convenience, but a loud warning is emitted.

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ValidatorKeys {
/// Ed25519 consensus public key (hex-encoded, 64 hex chars = 32 bytes).

pub consensus_pubkey: String,
/// Ed25519 consensus secret key (hex-encoded, 128 hex chars = 64 bytes).

/// NEVER log or transmit this value.

pub consensus_secret: String,
/// P2P network public key (hex-encoded).

pub network_pubkey: String,
/// P2P network secret key (hex-encoded).

/// NEVER log or transmit this value.

pub network_secret: String,
/// OAS DID associated with this key set.

pub validator_did: String,
/// Tower attestation gossip listen address (e.g. "0.0.0.0:26660").

///

/// Sourced from `--tower-addr` CLI flag and stored here so

/// `BlockEngine::new` can access it without needing `NodeConfig`.

#[serde(default = "default_tower_addr")]
pub tower_addr: String,
/// Geographic region label for Tower committee diversity.

///

/// Sourced from `--tower-region` CLI flag and stored here so

/// `BlockEngine::new` can log the region when starting the Tower runtime.

#[serde(default)]
pub tower_region: Option<String>
}

Source line: 139.

bootstrap::InitialState

Initial state snapshot derived from the genesis configuration.

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct InitialState {
/// Genesis state root hash (BLAKE3 of the serialized genesis config).

pub state_root: SigilHash,
/// Chain ID from the genesis config.

pub chain_id: String,
/// Genesis timestamp.

pub genesis_time: u64,
/// Number of initial validators.

pub validator_count: usize,
/// Total staked amount at genesis.

pub total_stake: u64,
/// Total initial balance supply.

pub total_balance: u64,
/// Protocol version at genesis.

pub protocol_version: String
}

Source line: 172.

bootstrap::SeedNode

Seed node entry for P2P bootstrap.

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct SeedNode {
/// Multiaddr-style address (e.g., "/ip4/1.2.3.4/tcp/26656/p2p/PEER_ID").

pub address: String,
/// Optional human-readable label.

pub label: Option<String>
}

Source line: 191.

bootstrap::BootstrapResult

Bootstrap result containing all artifacts from node initialization.

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct BootstrapResult {
/// Path to the data directory that was initialized.

pub data_dir: String,
/// The initial state derived from genesis.

pub initial_state: InitialState,
/// Validator keys if this node is a validator (None for RPC/observer nodes).

pub validator_keys: Option<ValidatorKeys>,
/// Whether the data directory was freshly created vs already existed.

pub freshly_created: bool,
/// How the validator keys were obtained. Used for startup logging and

/// monitoring. On mainnet this must always be `KeySource::PreProvisioned`.

#[serde(skip)]
pub key_source: KeySource
}

Source line: 200.

bootstrap::init_data_directory

Initialize the data directory structure for a Sigil node.

Creates the following subdirectories under data_dir:

  • akashakv/ — production block/index/query storage
  • state/ — state trie storage
  • keys/ — validator key material
  • snapshots/ — state snapshots
  • logs/ — structured logs
  • wal/ — write-ahead log

Returns true if the directory was freshly created, false if it already existed.

pub fn init_data_directory(data_dir: &Path) -> Result<bool, NodeError>;

Source line: 227.

bootstrap::derive_initial_state

Derive the initial state from a genesis configuration.

This computes the state root, tallies initial stakes and balances, and returns a summary of the genesis state.

pub fn derive_initial_state(genesis: &GenesisConfig) -> Result<InitialState, NodeError>;

Source line: 294.

bootstrap::validate_cli_chain_id_matches_genesis

Verify that the CLI-selected chain ID matches the loaded genesis.

Startup must fail before any subsystem accepts, gossips, or executes transactions if the operator-selected chain ID is not the genesis chain ID.

pub fn validate_cli_chain_id_matches_genesis(
    config_chain_id: &str,
    genesis: &GenesisConfig,
) -> Result<(), NodeError>;

Source line: 316.

bootstrap::validate_expected_genesis_hash

Verify an operator-supplied genesis hash before startup continues.

Mainnet nodes must be started with an independently supplied hash so a bad ConfigMap mount or stale local file cannot silently select a different genesis. Non-mainnet nodes may omit the hash for developer ergonomics.

pub fn validate_expected_genesis_hash(
    expected_hash: Option<&str>,
    genesis: &GenesisConfig,
) -> Result<(), NodeError>;

Source line: 334.

bootstrap::validate_mainnet_compute_quorum

#[cfg(feature = "compute")]
pub fn validate_mainnet_compute_quorum(genesis: &GenesisConfig) -> Result<(), NodeError>;

Source line: 369.

bootstrap::generate_testnet_validator_keys

Generate deterministic validator keys for testnet use only.

Derives real Ed25519 keypairs from a deterministic seed (BLAKE3 hash of the DID). This ensures the same DID always produces the same keypair, enabling reproducible testnet setups.

WARNING — NOT FOR PRODUCTION: The derivation seed is computed from a public DID string, making it fully predictable to anyone who knows the DID. This function is never called on mainnet — [bootstrap_node] enforces the fail-closed policy. Do not bypass that policy.

For mainnet use an HSM-generated key or an offline-generated key file provisioned before node startup.

pub fn generate_testnet_validator_keys(validator_did: &str) -> ValidatorKeys;

Source line: 415.

bootstrap::write_validator_keys

Write validator keys to the keys directory.

The keys are stored as keys/validator_keys.json under the data directory. File permissions should be restricted to owner-only in production.

pub fn write_validator_keys(data_dir: &Path, keys: &ValidatorKeys) -> Result<PathBuf, NodeError>;

Source line: 445.

bootstrap::read_validator_keys_from

Read validator keys from a specific file path.

Returns None if the file does not exist.

pub fn read_validator_keys_from(path: &Path) -> Result<Option<ValidatorKeys>, NodeError>;

Source line: 471.

bootstrap::read_validator_keys

Read validator keys from the default location inside data_dir.

Returns None if the key file does not exist.

pub fn read_validator_keys(data_dir: &Path) -> Result<Option<ValidatorKeys>, NodeError>;

Source line: 496.

bootstrap::write_initial_state

Write the initial state snapshot to the state directory.

pub fn write_initial_state(data_dir: &Path, state: &InitialState) -> Result<PathBuf, NodeError>;

Source line: 502.

bootstrap::parse_seed_nodes

Parse a seed nodes file into a list of SeedNode entries.

The file format is one address per line. Lines starting with # are comments. Empty lines are ignored. Lines may optionally end with # label to provide a human-readable label.

pub fn parse_seed_nodes(content: &str) -> Vec<SeedNode>;

Source line: 530.

bootstrap::bootstrap_node

Full bootstrap procedure: initialize data dir, derive state, load or (testnet-only) auto-generate keys, and write everything to disk.

Arguments

  • data_dir — Root data directory for this node.
  • genesis — The validated genesis configuration.
  • validator_did — If set, this node acts as a validator for the given DID.
  • validator_key_path — When Some, read keys from this explicit path instead of <data_dir>/keys/validator_keys.json. Useful for HSM-backed FUSE mounts or sealed volumes.

Mainnet fail-closed policy

When genesis.chain_id starts with "sigil-mainnet-":

  • If validator_did is Some and no key file exists at the expected path, the function returns [NodeError::ProductionKeyMissing] and the node refuses to start.
  • Auto-generation via [generate_testnet_validator_keys] is never called on mainnet regardless of any flags.

Testnet / devnet behaviour

On non-mainnet chains, if no key file is found the node auto-generates deterministic keys and writes them to <data_dir>/keys/validator_keys.json. A tracing::warn is always emitted so the auto-generated origin is visible in logs and monitoring.

pub fn bootstrap_node(
    data_dir: &Path,
    genesis: &GenesisConfig,
    validator_did: Option<&str>,
    validator_key_path: Option<&Path>,
) -> Result<BootstrapResult, NodeError>;

Source line: 583.

sigil-node · admission

Source declarations, signatures and documentation for admission.

sigil-node · compute_durable

Source declarations, signatures and documentation for compute_durable.

On this page

bootstrap::is_mainnetbootstrap::KeySourcebootstrap::ValidatorKeysbootstrap::InitialStatebootstrap::SeedNodebootstrap::BootstrapResultbootstrap::init_data_directorybootstrap::derive_initial_statebootstrap::validate_cli_chain_id_matches_genesisbootstrap::validate_expected_genesis_hashbootstrap::validate_mainnet_compute_quorumbootstrap::generate_testnet_validator_keysbootstrap::write_validator_keysbootstrap::read_validator_keys_frombootstrap::read_validator_keysbootstrap::write_initial_statebootstrap::parse_seed_nodesbootstrap::bootstrap_nodeArgumentsMainnet fail-closed policyTestnet / devnet behaviour