node.example.toml

# rustock node configuration.
#
#   rustock --config /etc/rustock/node.toml
#
# Precedence: command line  >  this file  >  built-in default.
# Anything given on the command line wins, so a setting here can always be
# overridden for one run without editing the file.
#
# EVERYTHING HERE IS COMMENTED OUT, on purpose. Copy this file, uncomment the
# few settings you are changing, and the uncommented lines are then exactly
# your changes -- there is no need to remember which of them you touched, or
# to diff against the original to find out.
#
# A copy taken unchanged therefore does nothing at all; a test asserts that.
#
# Each line says what the node does without it:
#
#   # key = value   # default          the value shown IS the built-in default
#   # key = ...     # default: unset   no built-in default; the value is an
#                                      illustration of the shape expected
#
# A test checks every one of those claims against the node's real defaults, so
# this file can be read as the authoritative statement of what the node does
# when left alone.
# Unknown keys are an ERROR rather than being ignored, so a typo is reported
# instead of silently leaving a setting at its default.
#
# One-shot operations (--import-*, --repair, --trie-tool-*, --probe-*,
# --build-*, --metadata-*) are command-line only. They run and then exit, so a
# node that re-ran an import on every start would be a trap, not a convenience.

[node]
# port = 30303                      # default — P2P listen port
# data_dir = "./data"               # default — database and node key
# network_id = 30                   # default — 30 mainnet, 31 testnet
# secret_key = "…"                  # default: unset — hex node key; generated and stored if unset
# external_ip = "203.0.113.1"       # default: unset — advertised address; 127.0.0.1 if unset
# off | per-block | per-transaction | both. Per-transaction is strictly more
# sensitive: block-level netting hides a creation when one transaction mints
# and another destroys the same amount. "both" keeps per-block as a cross-check
# that the per-transaction deltas account for the whole block.
# supply_check = "both"             # default
# rskj_multisig_senders = "on"      # default — on | off — emulate rskj multisig peg-in senders

# Threads for RSKIP-144 parallel sublists. 1 runs every transaction in order on
# one thread. A block only splits if its header says so, so on a chain where
# RSKIP-144 is unscheduled this setting changes nothing. The cap is 2, because
# that is the most parallel sublists a block may declare.
# execution_threads = 1             # default

# Serving a frozen chain, for timed comparisons between clients. A server that
# is still following is not the same fixture twice: it grows between runs and
# the second client has more to do than the first.
#
# Turning following off is the instruction -- serve what is held, adopt
# nothing. Opening read-only is the defence behind it: if some path is missed,
# the database refuses the write rather than taking it.
# read_only = false                 # default
# sigcache = true                   # default — remember recovered transaction
#                                   # senders so the pool and the executor do
#                                   # not each recover the same signature.
#                                   # false recomputes every one.
# follow_up = true                  # default
# Behave as though the chain ends here. Everything announced agrees with it,
# total difficulty included; nothing above it is served. Requires following to
# be off.
# simulate_height = 1000000         # default: unset
# Exit once synced, reporting the elapsed time -- an unambiguous end time for
# a measurement, rather than a log line to scrape.
# exit_when_synced = false          # default
# account_slots = 16                # default — transactions one sender may queue past its nonce (rskj transaction.accountSlots)

[rpc]
# host = "127.0.0.1"                # default
# port = 4444                       # default
# admin = false                     # default — enables rsk_collectTrie, rsk_pruneBlocks, …
# disabled = false                  # default — true is the same as --no-rpc
# logs_max_blocks = 10000           # default — widest eth_getLogs span; rskj's rpc.logs.maxBlocksToQuery is 5000
# gas_estimator_binary_search = false # default — estimate gas in one pass.
#                                   # true restores the old estimator, which
#                                   # executes ~24 times narrowing an interval.
#                                   # The two differ on a CALL with a large
#                                   # fixed allowance: see
#                                   # rustock_execution::gas_estimator.
# dev = false                       # default — evm_* namespace: snapshot/revert/mine — development chains only
# account_search = false           # default — rsk_lastAccountChange: finds the
#                                  # block an account last changed in by bisecting
#                                  # its trie leaf. OFF because one call is 10-24
#                                  # state lookups (round trips, on an SPV node),
#                                  # and that cost is invisible at the call site.
# ws = false                        # default — WebSocket JSON-RPC, for eth_subscribe
# ws_port = 4445                    # default
#
# A file of private keys this node may sign with, one 32-byte hex key per
# line; blank lines and `#` comments are skipped. Off by default, and the
# only way the node ever holds a key for signing: without it eth_accounts
# is empty and eth_sign, eth_signTransaction and eth_sendTransaction
# report as unknown methods.
#
# Not a keystore -- no encryption, no passphrase, no personal_* namespace.
# The keys are read once and held in memory. It exists so a load-testing
# harness can drive eth_sendTransaction from funded senders.
#
# Anyone who can reach this RPC endpoint can spend from these accounts.
# Give the file mode 0600 and do not set this on a node whose RPC is
# reachable from anywhere you do not control.
# wallet_file = "/etc/rustock/wallet.keys"   # default: unset — no wallet, no signing

[metrics]
# Prometheus metrics, served on their own listener. Absent port means no
# listener is opened at all, which is the default.
# port = 9898                       # default: unset — serving metrics is opt-in
# host = "127.0.0.1"                # default — bind elsewhere to scrape from another host

[peers]
# max_peers = 25                    # default
# max_inbound_peers = 32            # default
# max_inbound_per_ip = 4            # default
# max_inbound_per_cidr = 16         # default
# inbound_cidr_prefix = 24          # default
# bootnodes = ["127.0.0.1:30304"]   # default: unset — replaces the chain's built-in list; port is listen+1
# banned_peers = ["203.0.113.0/24"] # default: unset — refused at connection time; rskj's peer.bannedPeerIPs
# no_peer_punishment = false        # default — count scoring events but never act on them
# Never learn node ids from peers and never dial them. With `bootnodes` this
# pins the node to exactly the addresses named there, which is what makes a
# controlled two-node test trustworthy; on its own it only stops discovery.
# closed_network = false            # default

[trie]
# single | external | epoch. "single" keeps every historical version in the
# main database and grows without bound; "epoch" bounds the size by reclaiming
# state older than the retention window, which means historical state queries
# below that window stop working. That is a real trade, so it is opt-in — but
# "epoch" is what a node that is not an archive wants.
# backend = "single"                # default
# dir = "/var/lib/rustock/trie-epochs"# default: unset
# node = "…"                        # default: unset — diagnostic: start from this state root

# rocksdb | flatdb. Orthogonal to `backend`, which chooses retention: this
# chooses what holds the nodes. flatdb is measurably faster on reads and far
# steadier (docs/flatdb.md) and is EXPERIMENTAL — it has not run on a real
# chain, so the default stays rocksdb. The single backend cannot use it: that
# one keeps nodes in a column family of the main database, which only rocksdb
# provides. The node refuses to start if the directory on disk was written by
# the other engine, rather than opening an empty store beside the data.
# engine = "rocksdb"                # default

# Keys to size a flatdb index for; ignored by rocksdb. Zero derives it from
# the rotation threshold below: an epoch rotates at a known size, so the
# records it will ever hold are bounded and can be computed rather than
# guessed. Exceeding it costs a stop-the-world rehash; over-sizing costs
# reclaimable address space and nothing else, because the index is a file
# mapping and not committed memory. Set it only to override the derivation.
# expected_keys = 0                 # default

# Blocks executed per trie durability point while catching up. Trie nodes are
# derivable, so the store may flush less often than the node executes; the
# executed head never advances past what a crash would keep, so the only cost
# of raising this is that many blocks of re-execution after an unclean stop.
# Follow mode ignores it and makes every block durable.
# flush_every = 100                 # default
# BTC stored-block cache. Answering "which BTC block is at height H?" costs one
# trie read per block of depth whenever the RSKIP199 height index cannot answer.
# The cache holds blocks already read for consensus -- it never pre-loads and
# never records an absence -- so it changes latency and nothing else.
# ~200 bytes per entry; 0 disables.
# btc_block_cache_entries = 10000   # default

# Threads for parallel reads: the snapshot-sync client, the trie store, and the
# one-shot state verifier. Defaults to the core count, clamped to at least 1.
# read_threads = 16                 # default
# Trie garbage collection. `burial` must exceed the deepest reorg worth
# surviving: collecting against a root that is later reorganised away discards
# state the chain needs to rebuild.
[gc]
# epochs = 4                        # default
# rotate_mb = 1024                  # default
# burial = 4000                     # default
# check_secs = 60                   # default
# ---------------------------------------------------------------------------
# Peg events the Bridge does not emit
# ---------------------------------------------------------------------------
#
# `registerFlyoverBtcTransaction` calls no event logger at any height, so a
# Flyover peg-in reaches no receipt -- and `bridge_events` is built from
# receipts, so it is absent there too. It is also an internal call, invisible
# in block bodies. Only execution sees it.
#
# Recording keeps a store of those missing events current as blocks arrive,
# in the same key and value layout as the node's own event index, so one
# reader handles both and the union never double-counts. Read it back with
# the `legacy_events` tool.
#
# This is a bridge until the event exists. When a future network upgrade
# makes the Bridge log Flyover peg-ins, synthesis stops on its own: the gate
# is a per-topic flag set where the decision is recorded, so the synthesised
# event and the real one can never both exist.
#
# A separate database, not a column family of the node's own: these events
# are derived rather than observed, and folding them into the receipts-built
# index would make it assert something about the chain that is not true.
[peg_events]
# Turn recording off. On by default -- the cost on an ordinary block is one
# thread-local read per Bridge decision, and most blocks make none.
# disabled = false                 # default — recording is on
# Where the records go.
# dir = "..."                       # default: unset — <data-dir>/peg-events



# SPV client: answer state queries by asking a peer and checking the proof,
# instead of reading a local trie.
#
# Not the same thing as `node-light.example.toml`, despite the word. That is
# a pruned FULL node: it executes every block and reads its own trie, just on
# a few gigabytes instead of forty-five. This executes nothing and has no
# trie at all.
#
# A light client follows headers and never executes a block, so it holds no
# state. `eth_getProof` goes out over the wire, and the nodes that come back
# are verified against the state root of a header this node validated itself
# before any of it reaches the caller. A peer that lies costs a round trip,
# not a wrong balance; a peer that stays silent is an error rather than an
# account with nothing in it.
#
# This is what makes the account modification witness usable from a wallet.
# `eth_getProof` reports `lastModifiedBlock`, so a wallet can walk an
# account's history backwards -- one proven hop per block in which the
# account actually changed -- which is the only way to follow native rBTC,
# since a value transfer emits no log and so sets no bloom bit.
#
# The trie is withheld from the RPC layer even when one exists on disk.
# Leaving it in place would let state queries quietly answer from local data
# and never exercise the proof path, which is the one a real light client
# depends on.
#
# Today this switches the state path only: the node still syncs and executes
# as it otherwise would. Following headers alone is a larger change.
[spv]
# enabled = false                   # default — read the local trie



# Block-history pruning: bodies, receipts, the transaction index, headers and
# the canonical mapping, for blocks far enough behind.
#
# Off by default, and deliberately. Turning it on is not a tuning change — it
# discards history that only a resync restores, and `eth_getTransactionReceipt`
# stops answering for a pruned height. Bridge events are KEPT: they live in
# their own index, self-contained, and are what the peg is debugged from.
# Genesis is always retained.
#
# `keep_depth` is clamped up to 8000 whatever is given — 4000 for reorg
# tolerance plus 4000 for the block-info precompiles and REMASC's maturity,
# which a re-executed block may itself reach through. The depth is measured
# from the block this node has EXECUTED to, not from the best header it holds:
# on a snapshot-synced node those differ by thousands of blocks, and measuring
# from the header would delete what execution has not reached yet.
#
# Sweeps never run until the node has settled into ordinary sync, so a
# snapshot sync's blocks are never swept while it is still fetching them.
# `rsk_pruneBlocks` (needs rpc.admin) forces one sweep with the same clamps.
[prune]
# blocks = false                    # default — run sweeps at all
# What a sweep removes. `blocks` removes everything; the four below do one part
# each, so a node can keep a walkable, servable chain without the transactions.
#
# `headers` requires `bodies` and `receipts`: bodies and receipts are keyed by
# block hash, and the canonical index that finds the hash for an old height
# goes with the headers. Keeping them without it leaves data nothing can name.
#
# `uncles` is prevention, not removal. Uncles have no store of their own here --
# they live inside bodies -- so the only separate copy is the freezer's, and the
# freezer cannot drop from the bottom. A node that does not want uncle history
# simply never writes it. One that already has it keeps what it has.
# bodies = false                    # default
# headers = false                   # default
# receipts = false                  # default
# uncles = false                    # default — archive uncles, so this node can
#                                   # serve rsk/63 and re-derive its own work
# keep_depth = 100000               # default
# max_batch = 50000                 # default — most blocks one sweep may remove
# every_secs = 300                  # default — seconds between sweeps
# Delete headers from the block database once the freezer holds them. Every
# lookup by hash for those blocks then depends on the freezer.
# frozen_headers = false            # default
# freezer = true                    # default — move settled headers into flat files

# What this node does with the difficulty checkpoint it ships.
#
# Two independent switches. `bound_work` is on by default; `verify_hash` is not:
#
#   verify_hash  bound_work   what you get
#   -----------  ----------   ------------------------------------------------
#   false        false        nothing
#   true         false        a peer must be on the checkpointed chain
#   false        true         a peer's claimed work is bounded, and this build  <- default
#                             declares no winning fork
#   true         true         both
#
# The third row is why these are separate. A checkpoint *hash* states which
# chain is canonical, so shipping one asks whoever builds the node to choose a
# fork — a governance act. Bounding the work makes no such statement: it says
# only that a claim exceeds what any chain could carry.
[checkpoint]
# Ask a peer for the header at the checkpoint height and check its hash.
# Without this, the work below the checkpoint — over 99% of mainnet's
# cumulative total — is credited to any peer, including one on a fork that
# diverged below it and never did that work.
# verify_hash = false              # default — off; see the note above

# Bound a peer's claimed cumulative difficulty, sampling its chain above the
# checkpoint to do it. Costs about 585 messages per peer judged.
#
# The bound and the sampling are one setting on purpose. Bounding without
# sampling refutes a claim only for a height at or below the checkpoint, which
# an attacker avoids for free by claiming a height above it — and would claim
# anyway, since a sync peer wants to look like the longest chain. A setting
# that bounded without sampling would read as a defence and be none.
#
# On by default: it is the only half with adversarial value, and unlike
# verify_hash it does not ask this node to declare which fork is canonical.
# Set false here, or pass `--checkpoint-bound-work false`, to turn it off.
# bound_work = true                # default — on; bound and sampling together

# Snapshot sync: catch up by downloading a state rather than executing into
# one. The header chain is verified to the snapshot point first — a snapshot is
# only trustworthy because the walk vouches for the checkpoint it hangs from.
[snapshot]
# sync = false                      # default — act as a client
# server = false                    # default — serve snapshots to peers that ask
# Blocks of history to download below the checkpoint. These are the blocks the
# node holds once the sync is done. Setting this above prune.keep_depth is how
# a pruning node is given its first sweep's work.
# blocks = 6000                     # default
# chunk_bytes = 100000              # default — state bytes per chunk request
# chunk_grid = 100000               # default — offset grid chunks sit on; changing it
                                   # invalidates a server's cached cells
# parallel = 8                      # default — chunk requests in flight, across all peers
# Fill the canonical index for history below the checkpoint window after a
# snapshot sync. Costs ~0.4 GB and, on a cold store, up to an hour and a half
# of low-priority background disk; resumable, and it stops at the prune floor.
# Without it this node can answer RPC about its window only, and cannot help
# anyone else sync past it.
# index_history = true              # default
# Establish the header chain by ascending from a block this node already holds,
# with the uncles alongside (rsk/63, RSKIP-698), instead of descending from the
# peer's offered checkpoint. Totals cumulative difficulty exactly, so the
# sampling gate and the claimed-work ceiling are not needed — the offered
# checkpoint is checked against the chain this node proved for itself. A peer at
# rsk/62 cannot serve it and the session falls back to the descending walk.
# Experimental: the descending walk is what has been run against mainnet.
# forward_headers = false           # default
# peer_rate = 8388608               # default — state bytes/s served to ONE peer
# total_rate = 33554432             # default — state bytes/s this server produces in total

[mining]
# enabled = false                   # default — serve the mnr_* namespace
# coinbase = "0x…"                  # default: unset — REQUIRED when enabled
# extra_data = ""                   # default — client string, cut to fit rskj's 32-byte [1, "<version>-<commit>", extra] field
# refresh_secs = 60                 # default
# min_gas_price = 0                 # default: unset — wei to steer the block minimum toward, 1% per block (rskj miner.minGasPrice)
# submission_rate_limit_ms = 0      # default — refuse a second submission inside this window (rskj workSubmissionRateLimitInMills)
# update_work_on_new_transaction = false  # default — rebuild when arrivals pay a tenth of the candidate's fees (rskj updateWorkOnNewTransaction)
# timed = "10s"                     # default: unset — mine on rskj's regtest clock (timedMine): exponential delays with this median
# flush_every = 10                  # default — mined blocks between trie flushes (rskj blockchain.flushNumberOfBlocks)

# Per-account virtual gas quota (rskj TxQuotaChecker). An account accumulates
# quota while idle and spends it when broadcasting, so one that floods the
# mempool is refused here and not relayed onward. Ordinary use never reaches it.
[account_tx_rate_limit]
# enabled = true                    # default
# cleaner_period = 30               # default — minutes; 0 or negative disables the sweep
# max_accounts = 400000             # default
# quota_multiplier = 2000           # default — seconds of idleness an account may bank
# gas_per_second_percent = 0.9      # default — of the block gas limit, accrued per second

[log]
# level = "info"                    # default
# to_stdout = false                 # default — true when run under systemd (journald)
# Timezone for log timestamps: "utc" (default), "local", or a fixed UTC
# offset. Timestamps stay RFC 3339, so the offset is part of every line:
# UTC prints ...T21:13:45.9+00:00, "-03:00" prints ...T18:13:45.9-03:00.
# "local" is read once at start-up and then held, so it does not follow a
# daylight-saving change; a fixed offset says so plainly, and is exactly
# right for zones without DST (Argentina has had none since 2009).
# timezone = "utc"                  # default — or "local", or a fixed offset like "-03:00"
[alerts]
# alerts_config = "/etc/rustock/alerts.toml"# default: unset
# Regtest: a chain that has to match one an rskj node runs, for example to
# import blocks rskj mined (--import-blocks). Refused on mainnet and testnet
# unless allow_overrides says this is a copy of the chain (genesis excepted).
[chain]
# genesis = "genesis.json"          # default: unset — an rskj genesis JSON file, instead of rustock's regtest genesis
# skip_pow_validation = false       # default — rskj's miner.server.skipPowValidation
# consensus_rules = { rskip97 = 0 } # default: unset — rskj's blockchain.config.consensusRules; -1 disables
# min_gas_limit = 3000000           # default: unset (regtest: 1) — rskj's regtest minimum
# max_gas_limit = 1000000000        # default: unset (regtest: 10000000) — rskj has no upper bound
# hardforks = { reed810 = 9002504 }  # default: unset — rskj's blockchain.config.hardforkActivationHeights; -1 takes an upgrade off
# allow_overrides = false            # default — take these on a copy of mainnet or testnet too (genesis excepted)