Architecture · Explanation
Node startup, roles, and task ownership
The maintained node executable is svm-vm. Its startup is a sequence of admission gates: resolve configuration, establish a recoverable state baseline, validate the execution machinery required by the role, and only then expose the live node's services.
A process that compiled successfully has not passed those gates. In particular, the CPU-friendly Cargo build is useful for development and inspection; it does not remove the canonical GPU requirement for roles that execute deployed SBF programs.
To prepare an artifact or check configuration, follow build and configuration. The explanation below follows startup ownership and failure gates; validator lifecycle follows membership after startup.
Follow the startup sequence
The binary parses command-line paths for consensus configuration, genesis, and data. It installs an abort-on-unexpected-panic handler early so a failed detached storage worker cannot leave a misleadingly “active” process. Existing QMDB is probed in a disposable child process because its workers have process lifetime; a failed probe must not leave threads accessing storage that recovery may need to quarantine. Entrypoint.
Configuration resolution happens before storage and GPU initialization. The snapshot captures approved static inputs and produces separate consensus/node hashes. The two inspection options have deliberately narrow meanings:
| Option | Result | What it does not establish |
|---|---|---|
--check-config | Validates allowlisted startup fields and exits | Genesis contents, state integrity, secret-provider access, GPU readiness, or network membership |
--print-effective-config | Prints nonsecret effective configuration and exits | That the deployment is healthy or that peers agree with this configuration |
Normal startup installs the snapshot, pins canonical CuEVM process mode, establishes the data directory, and recovers the epoch. This ordering prevents later services from choosing execution semantics from inconsistent process-local state. Configuration and engine initialization.
Recover before seeding genesis
The state path opens or safely reconstructs the persistent baseline, restores a validated account snapshot when needed, and replays WAL entries above the QMDB baseline. Missing height metadata beside persistent artifacts is an error, not evidence of a fresh chain. Snapshot, baseline, and WAL recovery failures stop startup instead of falling back to an unverified in-memory state.
After recovery, the node derives is_fresh_boot from the recovered height. Genesis accounts and genesis sysvars are seeded only for the fresh path; reseeding an existing chain would overwrite later balances and program state. Height-zero bootstrap state must itself be persisted before workers start. Recovery gates, fresh-boot boundary, bootstrap persistence.
The height shared with RPC and consensus is initialized from recovered state. Serving a recovered account map with a genesis-height counter would misrepresent the node's position even if its balances looked plausible.
Roles choose responsibilities
| Role | Live state path | Consensus participation |
|---|---|---|
| Sequencer | Executes finalized blocks and produces replicated diffs | Participates through the configured engine |
| Validator | Re-executes finalized blocks through the reporter | Verifies and participates according to the active set |
| Read-only | Applies the replicated state path, including query metadata | Does not propose or vote |
The validator diff queue can exist as a constructed object while remaining idle. Feeding it in addition to reporter execution would apply a block twice from unordered sources. Read-only replicas are exempt from the startup CUDA requirement because they do not execute SBF; accelerated ingress options are also disabled by the zero-device result on that path. Role semantics, replica GPU exemption.
Validate the real execution boundary
Pending validators have a separate catch-up stage: they follow sequencer diffs until promotion, then stop that poller so finalized execution does not apply the same work twice. Replicas continue the primary pull path from the block server; the older push producer is dormant. Snapshot bootstrap and diff content retain a configured-source trust assumption. The metadata digest does not authenticate the diff bytes, so this is not independent execution validation. Follow and trust boundaries, membership lifecycle.
Executing roles enumerate devices and initialize the canonical BPFCC engine. Startup runs both the standalone hardware/JIT vector and a chain-owned adapter vector. The latter crosses the authenticated invocation boundary and a host-resume syscall; it compares status, return code, consumed units, state/log digests, and the ordered charge trace.
A total compute-unit match alone would miss a misplaced syscall charge. The vector therefore checks the sequence of charges as well as its sum. Passing it establishes a bounded engine observation, not universal compatibility with every program. Adapter vector, installation.
The executor binds the concrete BPFCC adapter before it is shared. The lower installation seam is restricted so external code cannot replace canonical SBF semantics midway through block execution.
Know who owns live work
The node wires the shared state, executor, mempool, height, metrics, and notification channels into RPC and consensus. Synchronous mempool admission verifies transactions before queueing them. Its verified record binds signatures to the actual signed message, rather than treating a bare signature as proof for arbitrary replacement bytes.
Consensus runs on its own runtime/thread topology. The reporter uses a height-ordered execution queue and a bounded finalization lane; the state layer has a separate durability writer. RPC and WebSocket broadcasters observe the resulting local state and receipts. Optional oracle and HILSA services supply inputs or observations, but their outputs must still pass the applicable deterministic state transition.
This separation helps triage stalls: queue growth, a blocked engine, a halted drain, and a broken public gateway are different faults. See observability and incidents.
Shutdown is a persistence operation
On a termination signal, the binary drains the state writer, attempts an authenticated account snapshot, and flushes collected HILSA attestations. A snapshot failure retains the previous authenticated snapshot. Attestations deserve their own flush because collected peer signatures cannot simply be recreated by replaying deterministic account execution. Shutdown.
Do not infer that every external worker or remote relay completed from process exit alone. Validate the recovered baseline on restart and reconcile external settlement separately.
For concrete prerequisites and commands, continue with build and configuration. For a joining node, use validator lifecycle and synchronization.