atlas-node

Summary

atlas-node is the main application/runtime package of the Rust workspace. It is the place where atlas-consensus, atlas-ledger, atlas-mempool, and atlas-p2p are assembled into a running node process with networking, block production, state sync, public APIs, telemetry, and operator-facing setup flows.

This package is not only the atlas-node executable. It also exposes a reusable library surface, several utility binaries, and integration tests that exercise the runtime end to end.

Why This Crate Exists

• boot and run an AtlasDB node from config, key material, and genesis state
• wire consensus, ledger, mempool, and P2P into one runtime
• expose public REST and gRPC surfaces for transactions and reads
• expose an optional secure proposal-submission gRPC service
• enforce node security policy, ingress limits, TLS/mTLS, and CORS
• provide operational helper binaries for config generation, ID inspection, and local cluster setup

Current Role In The Workspace

atlas-node currently owns six major concerns:

1. startup and bootstrapping in `main.rs`
2. runtime construction in `runtime/builder.rs`
3. orchestration of block production, consensus progression, sync, and maintenance through Maestro
4. public interfaces: REST, public ledger gRPC, and optional secure proposal gRPC
5. security and operational policy through SecurityConfig, NodeSecurity, TLS, CORS, and ingress rate limiting
6. package-local tooling and examples through the extra binaries under `src/bin/`

In practice, this is the current operator-facing node package. If someone asks "where does the running validator node actually live?", this is the answer.

Public Surface

Top-Level Modules

• api
• cli
• config
• env_config
• rpc
• runtime
• security
• setup
• telemetry

Main Public Reexports

• Config
• build_runtime

Important Types

• config::Config
• config::BlockProductionConfig
• runtime::builder::AtlasRuntime
• runtime::maestro::Maestro
• runtime::block_producer::BlockProducer
• runtime::consensus_driver::ConsensusDriver
• runtime::sync_driver::SyncDriver
• api::state::AppState
• security::SecurityConfig
• security::NodeSecurity
• security::IngressLimiter

Package Targets

The package currently exposes these targets:

• library target atlas_node
• binary target atlas-node
• binary target cli
• binary target generate_configs
• binary target print_peer_id
• binary target print_wallet_address
• binary target read_account
• binary target setup
• binary target show_id
• integration tests cluster_simulation, end_to_end_pipeline, and grpc_end_to_end
• build script in `build.rs`

Key Modules

• `lib.rs`: library export surface and feature gate around demo/admin APIs
• `main.rs`: main executable startup, logging, metrics, genesis handling, and REST/admin bring-up
• `config.rs`: persisted node config model plus runtime construction helpers
• `runtime/builder.rs`: AtlasRuntime, adapter setup, mempool creation, driver wiring, and Maestro spawn
• `runtime/maestro/mod.rs`: top-level orchestrator state for timers, servers, and runtime drivers
• `runtime/maestro/run.rs`: main runtime loop, adapter-event handling, sync timer, sealing timer, and block timer
• `runtime/maestro/grpc.rs`: public/proposal gRPC startup and supervision
• `runtime/block_producer.rs`: transaction gossip, sealing consumption, leader checks, proposal assembly, and gap recovery
• `runtime/consensus_driver.rs`: proposal/vote/evidence handling and phase progression
• `runtime/sync_driver/mod.rs`: state-sync driver facade
• `runtime/sync_driver/request.rs`: state and pending-by-sender request handling
• `runtime/sync_driver/bundle.rs`: inbound state bundle application and checkpoint install flow
• `api/rest.rs`: Axum router, REST routes, CORS, and rate limiting
• `api/state.rs`: REST/shared application state
• `rpc/server.rs`: public ledger gRPC, secure proposal gRPC, TLS/mTLS, and gRPC-web CORS
• `rpc/client.rs`: proposal-submission client used by the helper CLI
• `security.rs`: security policy, socket validation, ingress limiter, and client-key derivation
• `setup.rs`: default config creation and UPnP helpers
• `telemetry.rs`: node-level metrics and Linux process metrics collector
• `build.rs`: generates Tonic code from `atlas.proto`

Inputs And Outputs

Inputs

• node CLI arguments such as listen address, gRPC port, config path, and keypair path
• config JSON and optional env overrides for security and block production
• libp2p key material
• genesis state from a nearby genesis.json or example/genesis.json
• P2P adapter events for proposals, votes, evidence, heartbeats, and sync requests
• REST and gRPC client requests
• persisted ledger state and local redb ledger indexes

Outputs

• running P2P adapter and runtime event loop
• public REST API
• public ledger gRPC server
• optional secure proposal gRPC service
• optional demo/admin API when feature-enabled
• proposal broadcasts, vote broadcasts, state-sync requests, and sync responses
• ledger commits and mempool mutation
• metrics endpoints and structured log files
• generated example configs and local-cluster helper scripts from utility binaries

Internal Dependencies

Workspace Dependencies

• atlas-common
• atlas-ledger
• atlas-p2p
• atlas-consensus
• atlas-mempool
• atlas-bank
• atlas-kyc
• optional atlas-node-admin

This is the main application-level assembly point for the workspace. Most lower-level crates feed into this package.

External Dependencies That Shape The Design

• tokio for async runtime and task orchestration
• tonic, prost, and tonic-web for gRPC and generated protocol clients/servers
• axum and tower-http for REST API, middleware, and CORS
• tracing, tracing-subscriber, and tracing-appender for multi-stream operational logging
• metrics and metrics-exporter-prometheus for runtime instrumentation
• libp2p for key, peer ID, and network integration
• igd for UPnP port mapping

Used By

No other workspace package currently depends directly on atlas-node as a library.

The main consumers are the package's own targets:

• `main.rs`: production node executable
• `src/bin/cli.rs`: helper that submits a proposal through the proposal gRPC service
• `src/bin/generate_configs.rs`: writes sample node configs
• `src/bin/setup.rs`: builds a local multi-node example directory and start scripts
• `src/bin/print_peer_id.rs`: prints PeerId from key material
• `src/bin/print_wallet_address.rs`: derives a wallet address from the same key material
• `src/bin/read_account.rs`: inspects shard/account files
• `src/bin/show_id.rs`: alternate PeerId display helper

Runtime Model

Startup And Boot

The main startup path in `main.rs` currently does the following:

1. parse CLI args
2. install panic hook and multi-destination tracing setup
3. create a default config if needed through `ensure_config(...)`
4. load or generate the libp2p keypair
5. apply security and block-production env overrides
6. optionally configure UPnP
7. expose Prometheus metrics
8. discover and load genesis state
9. build the runtime with `build_runtime(...)`
10. apply genesis into the ledger
11. spawn REST and optional demo/admin APIs
12. keep the process alive while Maestro and the adapter run in background tasks

The executable also maintains multiple log streams:

• system log
• transaction log
• proposal-timeline log
• optional profile log

Runtime Composition

build_runtime(...) in `runtime/builder.rs` assembles the node out of:

• Cluster from atlas-consensus
• Ledger extracted from the cluster environment
• Libp2pAdapter plus AdapterHandle
• a local Mempool
• ConsensusDriver
• SyncDriver
• BlockProducer
• Maestro
• NodeSecurity

Two implementation details are especially important:

• the runtime explicitly self-registers the local node in PeerManager so consensus counts the local validator correctly
• even when Redis-backed ledger/index is enabled, the mempool is intentionally kept local; the old Redis mempool backend was removed because it did not support the sealing primitives this runtime depends on

Maestro As Orchestrator

Maestro is the runtime coordinator. Its main loop in `run.rs` multiplexes:

• incoming AdapterEvent values from the network
• periodic state-sync and maintenance ticks
• batch sealing decisions
• block production attempts

It also owns supervision of the gRPC servers so they can be restarted if their tasks exit.

Block Production

BlockProducer in `block_producer.rs` currently owns four related jobs:

• gossip pending transactions while filtering already-stale ones
• request gap recovery by (sender, nonce) when a pending sequence is incomplete
• decide whether the local node is leader for (height, view)
• consume a sealed mempool batch, build a signed Proposal, and publish it

Proposal assembly is chained to the committed tip, computes a metadata-based state_root, signs the proposal, and rolls back the tentative local proposal if network publication fails.

Consensus And Sync Bridging

atlas-node does not reimplement consensus, but it does own the runtime sequencing around it.

`ConsensusDriver` currently:

• receives inbound proposals and votes from the adapter
• creates Prepare, PreCommit, and Commit votes at the right moments
• checks approved phases and drives phase transitions
• handles final commit and mempool cleanup
• broadcasts equivocation evidence

`SyncDriver` currently:

• responds to GetState and GetPendingBySender requests
• validates inbound state bundles and checkpoint bundles
• installs checkpoint snapshots into the ledger when needed
• falls back to alternate peers on invalid bundles
• escalates to sync recovery / forked state through Cluster

Public Interfaces

The package currently exposes three main network-facing surfaces:

• REST API via `api/rest.rs`
• public ledger gRPC via `rpc/server.rs`
• optional secure proposal gRPC via the same RPC module

The REST surface covers:

• transactions and mempool
• balances and account history
• tokens and institutions
• aliases
• KYC lookups
• audit proposal and vote views
• SSE event stream

The gRPC surface is split intentionally:

• public ledger service for transaction submission and reads
• separate proposal service that can enforce dedicated TLS/mTLS rules

When the demo-admin-apis feature is enabled and allowed by security config, main.rs also starts an admin API from atlas-node-admin.

Security And Operational Policy

SecurityConfig in `security.rs` is one of the defining pieces of this crate. It controls:

• bind addresses for REST, gRPC, proposal gRPC, and admin API
• strict-mode behavior
• TLS and mTLS requirements
• ingress rate limits
• body and message size limits
• CORS allowlist logic
• whether public tx submission and proposal submission are enabled

NodeSecurity then wraps that config with a shared IngressLimiter used by both REST and gRPC surfaces.

Configuration Model

The current primary config path is `Config`. It is more than a thin transport config object: it also includes runtime-adjacent structures such as Graph, Storage, and PeerManager, and build_cluster_env(...) turns it directly into a running Cluster.

There is also an `env_config` module that can serialize and reconstruct an AtlasEnv, but it does not appear to be part of the current runtime path.

Testing

atlas-node has both module-level tests and explicit integration tests.

The package-level integration tests are:

• `cluster_simulation.rs`: basic consensus-driver flow around proposals and votes
• `end_to_end_pipeline.rs`: end-to-end node pipeline across REST, block production, consensus, and ledger behavior
• `grpc_end_to_end.rs`: gRPC service behavior and security policy checks

There is also broad unit coverage across config, security, runtime, REST, gRPC, and sync/consensus helpers.

Risks Or Design Tension

Very Broad Package Scope

This package combines:

• runtime orchestration
• public interfaces
• security policy
• config loading
• metrics and logging
• operational helper binaries

That is useful operationally, but it also makes atlas-node one of the heaviest crates to reason about.

Two Runtime Shapes Seem To Coexist

The current runtime clearly uses:

• Config::build_cluster_env(...)
• runtime/builder.rs
• Maestro

But the crate also still exports `env_config.rs`, and there is a separate root file `src/builder.rs` that references that path while not appearing to be wired into the current library/module tree. That suggests older startup machinery is still hanging around in source form.

Config Is Not Purely Declarative

Config currently contains serialized runtime-ish structures such as Graph, Storage, and PeerManager, not just ports, paths, and policy. That works, but it blurs the line between "configuration" and "runtime state container".

Local Self-Registration Is A Runtime Workaround

build_runtime(...) force-registers the local node into PeerManager so consensus counts local participation. That may be the right fix for today, but it is still a special-case runtime patch rather than an obviously native invariant.

Redis Removed

The runtime no longer uses Redis for mempool or ledger indexing. Transaction hashes, signatures, and statuses are stored in the local redb-backed ledger index.

Server Ownership Is Split

Public and proposal gRPC servers are spawned and supervised by Maestro, while REST and optional admin API are spawned directly from main.rs. Functionally this works, but operational lifecycle ownership is not fully centralized in one place.

Tooling Surface Has Some Overlap

The package ships multiple operational binaries, including both `print_peer_id.rs` and `show_id.rs`. That is not harmful by itself, but it is another sign that the operator-tooling surface has grown incrementally.