sigil-node · crate

pub mod admission;

pub mod bootstrap;

#[cfg(feature = "compute")]
pub mod compute_durable;

#[cfg(feature = "compute")]
pub mod compute_state;

pub mod consensus_coordinator;

#[cfg(feature = "contracts")]
pub mod contract_durable;

pub mod crucible_durable;

pub mod dex_durable;

pub mod engine;

pub mod error;

pub mod executor;

#[cfg(feature = "compute")]
pub mod executor_compute;

#[cfg(feature = "contracts")]
pub mod executor_contract;

pub mod executor_crucible;

#[cfg(feature = "dao-validators")]
pub mod executor_dao;

pub mod executor_dex;

pub mod executor_evidence;

#[cfg(feature = "tower")]
pub mod executor_gal;

pub mod executor_labor;

pub mod executor_mail;

pub mod executor_nft;

pub mod executor_nova;

pub mod executor_recovery;

pub mod executor_storage;

pub mod executor_username;

#[cfg(feature = "vigils-v1")]
pub mod executor_vigils;

#[cfg(feature = "tower")]
pub mod gal_durable;

pub mod genesis_loader;

pub mod governance_durable;

pub mod health;

#[cfg(feature = "wasm")]
pub mod host_backend;

pub mod labor_durable;

pub mod logging;

pub mod mail_durable;

pub mod mempool;

pub mod metrics;

pub mod nft_durable;

pub mod nova_durable;

pub mod recovery_durable;

#[cfg(feature = "compute")]
pub mod rpc_compute;

#[cfg(feature = "contracts")]
pub mod rpc_contract;

pub mod rpc_crucible;

pub mod rpc_dex;

pub mod rpc_evidence;

#[cfg(feature = "tower")]
pub mod rpc_gal;

pub mod rpc_labor;

pub mod rpc_mail;

pub mod rpc_middleware;

pub mod rpc_nft;

pub mod rpc_nova;

pub mod rpc_server;

pub mod rpc_storage_market;

pub mod rpc_sync;

pub mod rpc_username;

#[cfg(feature = "vigils-v1")]
pub mod rpc_vigils;

pub mod snapshot;

pub mod storage_market_durable;

pub mod storage_migration;

#[cfg(feature = "tee-verify")]
pub mod tee_verify;

pub mod tower_durable;

pub mod tower_runtime;

pub mod username_durable;

pub mod validator_agent;

pub mod weave;

pub mod ws;

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, clap::ValueEnum, Serialize, Deserialize)]
pub enum NodeMode {
    /// Block Producer: execute transactions, generate ZK proofs.
    Producer,
    /// Block Validator: verify ZK proofs, participate in consensus.
    Validator,
    /// RPC node: serve API queries (no consensus participation).
    Rpc,
    /// Archive node: store full chain history.
    Archive,
    /// Light node: verify block headers only.
    Light,
    /// Tower coordination chain validator: participate in Tower consensus,
    /// committee selection, finality voting, and slashing evidence processing.
    /// Runs the Tower chain alongside the execution chain.
    #[cfg(feature = "tower")]
    Tower,
    /// Observer node: subscribe to blocks and transactions without participating
    /// in consensus. Useful for analytics, indexing, and monitoring dashboards.
    Observer,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, clap::ValueEnum, Serialize, Deserialize)]
pub enum StateSyncMode {
    /// Do not attempt snapshot restore or state sync at startup.
    Off,
    /// Restore the latest signed snapshot, then catch up from peers.
    SnapshotThenP2pCatchup,
    /// Header sync first, then fetch state chunks against the finalized root.
    HeaderThenStateFetch,
}

#[derive(Debug, Clone, Parser)]
#[command(name = "sigil-node", version, about = "Sigil blockchain node")]
pub struct NodeConfig {
/// Node operating mode.

#[arg(long, value_enum, default_value_t = NodeMode::Validator)]
pub mode: NodeMode,
/// Chain ID.

#[arg(long, default_value = "sigil-mainnet-1")]
pub chain_id: String,
/// Data directory for chain state and blocks.

#[arg(long, default_value = "./data")]
pub data_dir: String,
/// RPC listen address.

#[arg(long, default_value = "0.0.0.0:12618")]
pub rpc_addr: String,
/// P2P listen address.

#[arg(long, default_value = "0.0.0.0:26656")]
pub p2p_addr: String,
/// Validator DID (required for producer/validator modes).

#[arg(long)]
pub validator_did: Option<String>,
/// Log level (e.g. "info", "debug", "trace").

#[arg(long, default_value = "info")]
pub log_level: String,
/// Genesis file path.

#[arg(long, default_value = "genesis.json")]
pub genesis: String,
/// Expected BLAKE3 state-root hash of the loaded genesis file.

///

/// When set, startup recomputes the canonical genesis hash and refuses to

/// start if it differs. Mainnet chain IDs require this flag so a validator

/// or RPC pod cannot silently boot against stale or tampered genesis data.

#[arg(long)]
pub expected_genesis_hash: Option<String>,
/// Tower coordination chain listen address (Tower mode only).

#[arg(long, default_value = "0.0.0.0:26660")]
pub tower_addr: String,
/// Geographic region for Tower committee diversity (e.g., "us-east", "eu-west").

#[arg(long)]
pub tower_region: Option<String>,
/// Path to a pre-provisioned validator key file (`validator_keys.json`).

///

/// When set, the node reads Ed25519 validator keys from this path instead

/// of the default `<data-dir>/keys/validator_keys.json`. This allows

/// operators to keep key material on an HSM-backed FUSE mount, a sealed

/// volume, or a separate read-only filesystem.

///

/// **Mainnet requirement**: on mainnet (`chain-id` starting with

/// `sigil-mainnet-`) this flag (or a pre-existing key file at the default

/// path) is mandatory. The node will refuse to start without pre-provisioned

/// keys — auto-generation and DID-derived keys are forbidden on mainnet.

///

/// Recommended HSM workflows:

/// - **Software HSM / OpenBao / Vault**: use `vault kv get` to export the

///   key JSON to a tempfs path, mount it read-only, and point this flag at

///   it. Revoke the export token after startup.

/// - **Hardware HSM (YubiHSM / Thales)**: generate the key inside the HSM,

///   export the public components to `validator_keys.json` (keep the private

///   key in the HSM), and adapt `BlockEngine` to call the HSM signing API.

/// - **Sealed file (e.g., Linux Keyring / TPM)**: decrypt the key file at

///   boot via `systemd-creds` or `clevis`, write to a tmpfs path, and pass

///   that path here.

///

/// See `docs/operator/validator-key-provisioning.md` for step-by-step

/// instructions and the audit checklist.

#[arg(long)]
pub validator_key_path: Option<PathBuf>,
/// Snapshot URI to restore before bootstrapping a fresh data directory.

///

/// Supported forms are an unpacked local snapshot directory, a local

/// `.tar`/`.tar.zst` archive, or an HTTP(S) `latest.json` manifest that

/// points to the archive payload. The restored state root is verified

/// against genesis for height 0 snapshots or against the restored canonical

/// block header for height > 0 snapshots.

#[arg(long)]
pub restore_from: Option<String>,
/// Startup state-sync strategy.

#[arg(long, value_enum, default_value_t = StateSyncMode::Off)]
pub state_sync_mode: StateSyncMode,
/// Public snapshot base URL used when `state-sync-mode` is

/// `snapshot-then-p2p-catchup` and `--restore-from` is omitted.

#[arg(long)]
pub snapshot_base_url: Option<String>,
/// Finalized block retention window kept for snapshot restore and

/// state-sync catchup.

#[arg(long, default_value_t = 100_000)]
pub retain_finalized_blocks: u64
}

pub fn apply_env_overrides(&mut self) -> Result<(), error::NodeError>;

pub fn is_public_production_chain(&self) -> bool;

pub fn validate_public_validator_peers(
        &self,
        sigil_peers: Option<&str>,
    ) -> Result<(), error::NodeError>;

pub fn effective_restore_uri(&self) -> Option<String>;

pub fn requires_validator(&self) -> bool;

pub fn requires_zk_prover(&self) -> bool;

pub fn requires_full_state(&self) -> bool;

pub fn stores_full_history(&self) -> bool;

#[cfg(feature = "tower")]
pub fn runs_tower_chain(&self) -> bool;

pub fn is_observer(&self) -> bool;

pub fn validate(&self) -> Result<(), error::NodeError>;

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

pub fn peer_config_empty(sigil_peers: Option<&str>) -> bool;

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct NodeInfo {
/// Software version.

pub version: String,
/// Chain ID.

pub chain_id: String,
/// Operating mode.

pub mode: NodeMode,
/// Current block height.

pub current_height: u64,
/// Current epoch number.

pub current_epoch: u64,
/// Number of connected peers.

pub peer_count: usize,
/// Whether the node has finished initial sync.

pub synced: bool,
/// Current Tower slot number (Tower/Validator/Producer modes only).

#[cfg(feature = "tower")]
#[serde(default, skip_serializing_if = "Option::is_none")]
pub tower_slot: Option<u64>,
/// Latest finalized epoch via Casper FFG (Tower modes only).

#[cfg(feature = "tower")]
#[serde(default, skip_serializing_if = "Option::is_none")]
pub finalized_epoch: Option<u64>
}