# Node operation and recovery A wallet asks a node what happened on the network. Running your own node lets you check and keep that record yourself, rather than depend on another operator for every answer. The node checks blocks, exchanges them with peers and exposes interfaces that wallets and dashboards can use. A non-voting node checks and serves the data. A representative node also signs votes using the weight people have delegated to its account. Running more nodes does not create more voting weight. Both kinds need the state required to check the protocol's rules. Start with [installation](INSTALLATION.md) for a background service, or [build and test](../development/DEVELOPING.md) for a local source build. ## Configuration Save the following as `node.toml` for a local, non-voting Dev node: ```toml network = "Dev" data_dir = "./burst_data_dev" port = 27076 bootstrap_peers = [] enable_representative = false enable_rpc = true rpc_bind = "127.0.0.1" rpc_port = 7077 enable_websocket = true websocket_bind = "127.0.0.1" websocket_port = 7078 enable_upnp = false ``` Start it with `burst-daemon --config node.toml node run`. TOML network names are `"Dev"`, `"Test"` and `"Live"`; the CLI accepts `--network dev`, `test` or `live`. Set the P2P port explicitly in TOML: its default is the Dev port, even when the file selects another network. Without a config file, the CLI picks the selected network's port: 27076 for Dev, 17076 for Test and 7076 for Live. RPC defaults to port 7077 and is enabled. WebSocket defaults to port 7078 and is disabled. Both bind to loopback. Add reachable peers to `bootstrap_peers` when joining a network; an empty list does not supply a public discovery service. Use a separate `data_dir` for each network identity. CLI options and supported environment variables override file values. Some flags only enable or disable one direction: `--faucet` and `--metrics` enable, while `--no-representative` and `--disable-upnp` disable. `--rpc=false` and `--websocket=false` explicitly disable those listeners. For a voting node, enable representative mode and provide `representative_key_file`, a file containing the representative's 32-byte seed as 64 hex characters. On Unix, restrict it with `chmod 600`. Keep one durable data directory per signing key. Voting weight comes from verified accounts that select the representative; running the process alone gives it no weight. The `enable_verification`, `work_threads`, `log_format` and `log_level` fields are currently stored preferences, not controls wired into those runtime paths. Verifier opt-in is a signed account operation. Use environment-based logging as described under [Logging](#logging). Source: [CLI](https://github.com/BURST-UBI/protocol/blob/main/daemon/src/main.rs) and [NodeConfig](https://github.com/BURST-UBI/protocol/blob/main/node/src/config.rs). ## Joining and synchronizing Startup loads the selected network identity and recovers durable state before admitting normal work. Configured peers provide connections and missing data; received blocks and certified state still require validation. A positive peer count does not prove the node has the current certified epoch, required history or signing authority. Check synchronization and recovery status before treating connectivity as readiness. Blocks can arrive before their predecessor or source payment. The node retains missing-dependency work in bounded queues and retries it when dependencies become available. Queue capacity and retention limits protect local resources; queue admission is not confirmation. ## Peer and database compatibility Peers must match the selected network and the node's exact block and wire protocol versions. A successful TCP connection alone does not satisfy these handshake checks. Database opening checks schema and layout markers, then commits supported index rebuilds atomically. Unsupported layouts fail without deleting the ledger or automatically starting a new one. Keep the original data when diagnosing a compatibility error; follow the error's requirements for a separate fresh data directory where needed. ## Reachability and services An established outbound TCP connection carries traffic in both directions. A node behind NAT can therefore communicate by dialing reachable peers without accepting unsolicited inbound connections. Inbound reachability still depends on the router, firewall and upstream network. UPnP can request a router mapping when enabled. It does not guarantee reachability through carrier-grade NAT or multiple routers. Operators can disable it with `--disable-upnp`. Dev skips mapping. Setting `advertise_address` also skips it and disables automatic address detection; use a numeric IPv4 address with an optional `:port`. An invalid value is ignored without falling back to detection. P2P, RPC and WebSocket have separate listeners. Prometheus metrics use `/metrics` on the RPC listener when both RPC and metrics are enabled. Public peer connectivity does not require exposing administrative RPC. RPC binds to localhost by default; review authentication and bind settings before changing that boundary. External time and randomness services have their own network behavior, described under [privacy](../release/PRIVACY.md). The metrics endpoint has incomplete instrumentation. `burst_votes_received_total` has no updater, so zero does not mean no votes arrived. Block, account and unchecked gauges are sampled at startup and shutdown. `burst_confirmation_latency_ms` records election duration at durable confirmation handoff, not elapsed time from network reception through cementation. `burst_transactions_received_total` counts the node's transaction-submission API, not all blocks received over P2P or RPC. ## Peer traffic and duplicate handling Blocks spread to randomly selected peers; authenticated votes also relay across connections. Outgoing control and bulk traffic use separate bounded queues and share per-socket and node-wide bandwidth budgets. Queueing does not guarantee network delivery, and higher proof-of-work does not reorder outgoing messages. Duplicate block gossip is briefly suppressed, then allowed to retry when missing dependencies may have arrived. Repeated signature checks can use a cache, but vote authority and routing still run. Requests and liveness messages are not subject to blanket global deduplication. The peer manager has a score-and-ban helper, but the running node does not invoke its penalty method. Do not rely on automatic reputation bans as a deployed spam control. Queue limits, bandwidth limits and validation are separate mechanisms. ## Queued blocks The running node shares 65,536 retention slots across queued blocks, authentication and dependency recovery. Blocks waiting for missing predecessors or sources can occupy at most 61,440 unchecked entries, leaving 4,096 slots for ingress. Entries older than 15 minutes are removed by a periodic sweep; the deadline is not an instantaneous per-entry timer. These counts limit retained entries, not total RAM. Blocks vary in size, and indexes, workers, economic state and database mappings consume memory separately. A bounded queue can reject work when full; it does not guarantee acceptance under arbitrary load. ## Storage capacity The default LMDB map limit is 1 GiB. To raise it, stop the node and set, for example: ```toml database_map_size_bytes = 4294967296 ``` This permits a 4 GiB database map on a host with a sufficient address space. The value must be a positive whole number of MiB. Use the same configuration for offline snapshot commands. The map limit is not a resident-memory limit or a budget for recovery scratch space. ## Beacon relays The default relay configuration is: ```toml drand_relays = ["https://api.drand.sh"] ``` The client accepts one to four relays for the pinned chain. It requests the same certified round from them in parallel and uses the first authenticated response. A relay cannot select a different chain, round or verifier pool. Remote URLs require HTTPS; numeric loopback HTTP is allowed for local tests. Credentials, query strings, fragments, duplicates and redirects are rejected. If no relay supplies a valid proof, the request remains pending. See [randomness and selection](../protocol/CONSENSUS.md). ## Time and agreed transitions BRN accrual, expiry, voting windows and beacon selection depend on time. Clock synchronization supplies time estimates; it does not itself establish agreement on a state transition. Certified boundaries coordinate deadline effects so that one node crossing a local deadline cannot independently rewrite shared state. The `telemetry` RPC response reports `signing_clock` separately from the diagnostic `ntp_offset_ms`. Its status is `ready`, `unavailable` (with a reason), or `disabled`. A ready reading includes conservative `earliest` and `latest` Unix seconds; it does not establish that this node is otherwise eligible to sign. A missing field on an older response means unknown, not ready. The dashboard shows these states separately. Logs report when authenticated signing time becomes available or unavailable. Configure `nts_sources` with three to eight independently operated NTS services. Each entry has `operator`, `server_name` and `port` (normally 4460). These are local operator choices, not consensus parameters; representatives need not use the same providers. Repeated names or operator labels are rejected, but distinct labels cannot prove independent infrastructure. Check reachability and actual ownership before relying on a set of sources. An empty list disables fresh checkpoint signing. Ordinary non-representative nodes do not start the NTS service. Fresh samples already advance with monotonic elapsed time and increasing uncertainty. They expire after 90 seconds; outages do not extend that limit or permit an unauthenticated fallback. The operating system remains responsible for its own clock. BURST does not set it. Compact recovery rebuilds expiry caches at the authenticated checkpoint cutoff, not an NTP-adjusted local timestamp. A current clock cannot rewrite the recovered checkpoint's meaning. ## What restart must preserve Recovery includes account frontiers, pending receipts, BRN history and stakes, TRST holdings and provenance, verification and governance state. It also includes installed authority and local signing commitments, such as final-vote promises, checkpoint rounds and snapshot attestations. Those commitments constrain what a signing identity may safely sign next. Do not run independent copies of a signing identity from separate or stale databases. A key backup alone does not restore that identity's durable signing history. ## Historical blocks from peers Ascending bootstrap asks peers for account frontiers and subsequent block bodies. A serving peer must still retain those bodies; knowing a hash does not reconstruct the block. Responses are bounded to 128 blocks and the peer-message byte limit. The receiving node checks chain continuity, applies normal admission, and advances its cursor from persisted progress. An empty response is not proof that no history exists. The serving path also returns an empty batch after logging a storage error. Likewise, an idle bootstrap queue does not prove that discovery found every account. Recovery that requires missing history needs another retained source or the supported authenticated snapshot path; it must not invent state from an unavailable predecessor. ## Authenticated snapshots A snapshot can avoid replaying every old transaction, but its sender is not a trust anchor. The archive reader authenticates authority transitions from the configured base and checks the snapshot certificate before reading the economic body. Body validation and installation checks remain separate steps. The node installs a snapshot only after these checks: 1. Starting from its configured trusted base, authenticate the snapshot's authority and certificate. 2. Validate the contents of the snapshot. 3. Check that they agree with the required local history and previous signing decisions. 4. Commit the installation and restore the running node's state. A file checksum only checks file identity; it cannot replace authority and state validation. Importing an authenticated archive is also not the same as installing it. The startup path requires gated recovery, reconciles the snapshot with local state and required history proofs, projects ledger and economic state, commits and synchronizes storage before normal startup proceeds. A peer download first uses temporary storage. Once the complete archive passes its digest, authority, epoch and minimum-height checks, the node publishes the requested output file without overwriting an existing destination. The installer still has to reconcile local history and signing commitments before using it. A peer's snapshot offer cannot change the configured trust base or freshness floor. Archive handling has explicit size and resource budgets. Disk-backed processing reduces the need to hold everything in memory; it does not remove those limits. Snapshots do not contain private keys or replace local signer journals. Operators create snapshots on demand for a named certified epoch. Each signer reconstructs that epoch locally, then the exporter collects matching attestations. There is no fixed daily or block-count export schedule. Offline verification does not install the snapshot or establish that it is the latest checkpoint. Use an independently obtained minimum checkpoint height or expected epoch hash when freshness matters. The original genesis parameters must also come from an independently trusted source. ## Pruning and retirement Expiry alone does not make every historical record dispensable. Provenance, restoration, authority authentication and signing continuity can still depend on retained information. A compact recovery path must preserve what those operations need, even when it no longer keeps every ordinary block body. Physical body retirement is disabled by default, and current non-test startup rejects enabling it. Do not bypass that qualification gate. Pruning also does not promise bounded total storage as accounts and retained state grow. ## Backups Back up the state needed for the role you run. A wallet recovery phrase recreates the account key; an encrypted keystore stores that key protected by a password. Neither contains the pending-action journal, which preserves exact signed actions whose outcomes are still uncertain. A node also needs its database and journals to preserve local history, recovery state and previous signing decisions. An authenticated snapshot can supply shared state through a supported recovery path, but it does not replace those local signing records. Stop the owned node cleanly before taking a filesystem copy of its database. Keep recovery material on a separate device or storage system; a copy on the same disk does not protect against losing that disk. Restore with compatible software and verify network identity and recovery status before resuming service. See [build and upgrade checks](../release/DOWNLOADS.md). ## Implementation - [Node lifecycle](https://github.com/BURST-UBI/protocol/blob/main/node/src/node.rs) - [Configuration](https://github.com/BURST-UBI/protocol/blob/main/node/src/config.rs) - [Drand relay validation](https://github.com/BURST-UBI/protocol/blob/main/vrf/src/drand.rs) - [Missing-dependency queue](https://github.com/BURST-UBI/protocol/blob/main/node/src/unchecked.rs) - [Snapshot archive reader](https://github.com/BURST-UBI/protocol/blob/main/node/src/confirmed_replay/snapshot/archive.rs) - [Startup snapshot installation](https://github.com/BURST-UBI/protocol/blob/main/node/src/node/snapshot_bootstrap.rs) - [Installation journal checks](https://github.com/BURST-UBI/protocol/blob/main/node/src/confirmed_replay/snapshot/installed/journals.rs) ## Logging Set `RUST_LOG` before starting the daemon to control tracing filters. If absent, the initializer uses `BURST_LOG_LEVEL`, then defaults to `info`. Output is human-readable text. Initialization precedes CLI and file configuration parsing, so stored `log_level`, `log_format`, and explicit `--log-level` arguments do not reconfigure the subscriber.