BSV blockchainBSV blockchain

Legacy Service Settings

Related Topic: Legacy Service

Every key below is loaded in the Legacy: LegacySettings{ block of settings/settings.go. That block is the only thing that makes a setting configurable. A struct tag in settings/legacy_settings.go is documentation, not wiring: a field with a tag and no loader line arrives as its zero value whatever an operator writes.

Two values are shown for each key:

  • Loader fallback is the default settings/settings.go passes. A node uses it only when no configuration file sets the key.
  • settings.conf is the base value in the committed settings.conf. A node that runs on the repository configuration uses this value, unless settings_local.conf or a context-specific key (key.<context>) sets another. “not set” means the file has no base line for the key, so the loader fallback applies.

${DATADIR} is ./data in settings.conf (/data in the operator context), and ${LEGACY_GRPC_PORT} is 8099.

Configuration Settings

SettingTypeLoader fallbacksettings.confEnvironment VariableUsage
WorkingDirstring”../../data”${DATADIR}/legacylegacy_workingDirDirectory for legacy peer data, resolved to an absolute path and created at startup. Holds the address book when SavePeers is true. Read from the config directly, not through the settings struct
ListenAddresses[]string[]not setlegacy_listen_addressesPipe-separated addresses to accept wire-protocol peers on. Empty falls back to the node’s outbound interface IP and the network’s default port
ConnectPeers[]string[]not setlegacy_connect_peersPipe-separated peers to dial. A non-empty list puts the node in connect-only mode
OrphanEvictionDurationtime.Duration10mnot setlegacy_orphanEvictionDurationHow long an orphan transaction is held. On eviction it gets one last validation attempt
MaxOrphanTxsint100not setlegacy_maxOrphanTxsCap on orphan transactions held in memory. Inserting past the cap evicts the oldest by insertion time. 0 leaves the pool unbounded
RelayTxBytesBudgetint64268435456not setlegacy_relayTxBytesBudgetSerialized bytes of relayed transactions queued for validation or being validated. A transaction over it is dropped and counted; zero or a negative value means one transaction at a time. The node holds about three times this while transactions are being validated
InvQueueMaxHashesint400000not setlegacy_invQueueMaxHashesAnnounced transaction hashes held from the peer’s read loop until a UTXO store lookup finishes with them, node-wide; one peer may hold 100000 at once. Announcements over either limit are dropped and counted. Not covered: at most legacy_invHandlerSlots handler goroutines for transaction-only messages, and up to 50000 missing hashes per peer waiting for a getdata, which is fixed. Covers only the direct route: with kafka_legacyInvConfig set, announcements staged for Kafka are charged only when read back (issue 2103). Below 4096 falls back to the default with a warning; zero is not unbounded
InvLookupWorkersint16not setlegacy_invLookupWorkersWorkers that look transaction announcements up in the UTXO store, capping the store reads in flight from this path; each holds at most about 1.3 MB. Below 1 falls back to the default with a warning
InvHandlerSlotsint1024not setlegacy_invHandlerSlotsGoroutines allowed at once to handle inv messages carrying only transaction announcements, which wait on the blockchain service. A message finding every slot taken is dropped and counted under handlers_busy; block announcements always get a handler. Below 1 falls back to the default with a warning; zero is not unbounded
PrintInvMessagesboolfalsefalselegacy_printInvMessagesLog every inventory message sent and received
GRPCAddressstring""localhost:${LEGACY_GRPC_PORT}legacy_grpcAddressAddress other services dial to reach the legacy service. Client creation fails when empty
AllowBlockPrioritybooltruetruelegacy_allowBlockPriorityNegotiate the BSV multistream BlockPriority policy, which carries block traffic on its own TCP stream. False also refuses an inbound createstream
GRPCListenAddressstring"":${LEGACY_GRPC_PORT}legacy_grpcListenAddressBind address for the legacy gRPC server
SavePeersboolfalsenot setlegacy_savePeersPersist the address book. When false the address manager is given no directory and keeps nothing across a restart
AllowSyncCandidateFromLocalPeersboolfalsenot setlegacy_allowSyncCandidateFromLocalPeersRegtest only. False admits only 127.0.0.1 and localhost peers as sync candidates. On every other network the setting is not read
TempStore*url.URL“file://./data/tempstore”file://${DATADIR}/tempstore?checksum=falsetemp_storeBlob store for temporary data. The out-of-order block park writes here and needs a file:// URL
PeerIdleTimeouttime.Duration125snot setlegacy_peerIdleTimeoutDisconnect a peer after this long with no message. A multistream association with recent traffic on another stream resets the timer. Half this value bounds the streaming pipeline’s admission wait
PeerSendTimeouttime.Duration20mnot setlegacy_peerSendTimeoutDisconnect a peer whose socket has accepted no bytes for at least this long. The check runs once per timeout window, so a peer that stalls partway through a window is dropped after between one and two times this value; SV Node -p2ptimeout drops it after one. Same default as SV Node. Non-positive falls back to 20m
MaxAddnodePeersint8not setlegacy_maxAddnodePeersCeiling on addnode peers, budgeted separately from MaxPeers and enforced on both the startup list and the runtime RPC
ReplenishIntervaltime.Duration2snot setlegacy_replenishIntervalHow often the connection manager dials to close its outbound deficit. 0 restores the one-minute ticker and disables the event-driven wake
MaxFeelerPeersint1not setlegacy_maxFeelerPeersPeer slots reserved for short-lived feeler probes, and the cap on probes at once. 0 disables feelers and the reservation together
FeelerIntervaltime.Duration120snot setlegacy_feelerIntervalMean of the randomised gap between feeler probes. Not a disable lever: a non-positive value falls back to 120s with a warning
FeelerHandshakeTimeouttime.Duration25snot setlegacy_feelerHandshakeTimeoutHow long a feeler waits for a version message. Must stay under the 30s peer negotiate timeout
PeerProcessingTimeouttime.Duration3m10mlegacy_peerProcessingTimeoutPer-message processing watchdog. Not armed for block messages while prefetch ingestion is active. Also the pre-admission deadline on an inbound peer, and part of the block-failure map TTL
BlockDownloadTimeoutBasePercentint64100not setlegacy_blockDownloadTimeoutBasePercentCeiling on one block download at the chain tip, as a percentage of the target block interval. Floored at 30 minutes, so values at or below 300 change nothing on a 10-minute chain
BlockDownloadTimeoutBaseIBDPercentint64600not setlegacy_blockDownloadTimeoutBaseIBDPercentThe same ceiling while catching up. Also floored at 30 minutes, which the 600 default clears on a 10-minute chain
BlockDownloadTimeoutPerPeerPercentint6450not setlegacy_blockDownloadTimeoutPerPeerPercentExtra ceiling per other peer with a block download outstanding. The total is floored at 30 minutes, so this only adds patience
MultiPeerBlockDownloadbooltruenot setlegacy_multiPeerBlockDownloadSpread block requests over every eligible peer. False assigns them all to the sync peer, disconnects a stalled sync peer instead of demoting it, and ignores notfound
MaxBlocksInTransitPerPeerint16not setlegacy_maxBlocksInTransitPerPeerMost block bodies one measured peer may owe at once with multi-peer download on; a peer whose speed is not measured holds 1. A measured peer holds this value scaled by its rate against the fastest peer’s, rounded up, at least 1. Not reduced for large blocks: the 100 GiB park backstop (parkBackstopBytes) guards the disk instead. In every mode it also sizes the pipeline’s admission budget, at four slots per peer, and the peer package’s download-timeout budget
BlockDownloadWindowint1024not setlegacy_blockDownloadWindowBlock bodies the whole node may have outstanding, counting every peer together, and the read-ahead depth: how far above the committed tip a block may be asked for at all. A count, not svnode’s per-peer height range
ParkStoreTimeouttime.Duration10snot setlegacy_parkStoreTimeoutDeadline on each park blob store operation, bounding the wait for the file store’s shared permits. Values below 1s are raised to 1s
PeerRegistryEnabledbooltruenot setlegacy_peerRegistryEnabledMirror connected legacy peers into the centralized peer registry so the dashboard can show them
PeerRegistrySyncIntervaltime.Duration10snot setlegacy_peerRegistrySyncIntervalHow often that mirror reconciles connected legacy peers into the registry

Configuration Dependencies

Peer Connection Management

  • ListenAddresses controls incoming connections. Empty falls back to the IP of the interface that reaches the internet, plus the active network’s default port, which is 8333 on mainnet.
  • ConnectPeers forces outgoing connections to specific peers.
  • When ConnectPeers is set, MaxPeers is lowered to the length of the list and the address-book dialler is not installed, so the configured list is the node’s entire connectivity.
  • ConnectPeers does not switch off DNS seeding. The flag that does is decided before the settings list is read, so a node with legacy_connect_peers set still seeds its address book from DNS.
  • SavePeers controls whether the address book is written to WorkingDir.
  • There is no working legacy_upnp key. The struct field exists but nothing loads it, so it is always false. UPnP is reached through legacy_config_Upnp, which is copied onto the legacy config struct by field name.

Feeler Probes

  • A feeler is a short-lived probe that connects to an address the node is not otherwise using, waits for the version exchange to prove somebody is home, marks the address as verified, and hangs up. Its purpose is to keep the pool of known-reachable addresses from decaying, so a lost peer can be replaced quickly.
  • MaxFeelerPeers is both the number of probes allowed at once and the number of peer slots held back for them. The reservation comes out of the peer-admission ceiling (legacy_config_MaxPeers, 20 by default), never out of the automatic outbound target, so probing can never cost the node a peer it chose to dial.
  • Probes start only once the automatic outbound tier is already at its target.
  • Selection resolves the address it picks and skips any it cannot resolve, so an address this layer has no way of dialling costs one draw rather than the whole probe interval. OnionCat addresses are the case that always takes this path: the address book accepts them but there is no onion dial path here.
  • Feelers switch themselves off, reservation included, in three cases: MaxFeelerPeers at zero or below; connect-only mode (ConnectPeers set); and a peer cap too tight to reserve a slot without pushing the admission ceiling below the outbound target. Each logs its reason at startup.
  • FeelerHandshakeTimeout must stay below the peer package’s 30-second negotiate timeout. If it does not, the peer package hangs up first and a silent host is logged at warning as a lost peer rather than being hung up on quietly by the probe; values at or above the peer timeout are reduced to 29s with a warning. A non-positive value falls back to 25s, also with a warning. Both warnings are emitted once, at startup, and the deadline the feeler settled on is on the [Feeler] Starting line.

Peer Timeout Management

  • PeerIdleTimeout at 125s sits above the protocol’s two-minute ping interval, so a healthy quiet peer is not dropped.
  • PeerProcessingTimeout bounds one message’s handling. While prefetch ingestion is active it is not armed for block messages, because a block can legitimately wait on the admission budget for longer than this; a stalled block download is then caught by the sync-peer stall detector and the idle timer instead.

Sync Candidate Selection

  • AllowSyncCandidateFromLocalPeers is read on regtest and nowhere else.
  • On regtest, false means a peer is a sync candidate only if its host is 127.0.0.1 or localhost. True skips that test and admits any host.
  • On every other network a peer is a sync candidate if it advertises the SFNodeNetwork service flag, and this setting has no part in the decision.

Block Priority

  • With AllowBlockPriority true and a peer that sends an association ID in its version message, the node registers a multistream association and defers registering the peer with the sync manager until the protoconf exchange, so the block stream exists before any getdata goes out.
  • The stream policy itself is negotiated on protoconf, when the peer lists BlockPriority among its stream policies. An outbound peer then opens its required streams synchronously.
  • With it false, the node registers no association and disconnects any peer that sends a createstream.

Block Download

  • BlockDownloadWindow and MaxBlocksInTransitPerPeer bound how many block bodies are outstanding, and BlockDownloadWindow doubles as the read-ahead depth: how far above the committed tip a block may be asked for at all, which is what decides how much disk the park needs.
  • Blocks are chosen by a pass over that range: drop what is already on disk, in the park, arriving, being converted, given up on or already owed, then hand the rest to peers with budget. Below the last checkpoint each block goes to the measured peer with the lowest (blocks owed + 1) / rate: a block size is not known before the download, so the schedule uses none, and no block waits while a peer has room. A peer holds the per-peer depth scaled by its rate against the fastest peer’s. A peer with no rate gets one block from the top of the window. Measured rates of outbound peers are kept by address, with the time each was measured, in legacy-peer-rates.json in the working directory. A remembered rate loses half its weight per hour of age, an entry older than 24 hours is dropped, and the file keeps at most the 1,000 newest. Below the last checkpoint the range comes from the header cache, which runs to the next checkpoint; above it, blocks are asked for from invs and the pass re-asks from the download ledger. There is no download cursor, so nothing carries a position between passes.
  • A block whose owners have sent nothing for the 60-second retry window is offered to another peer on the next pass. An owner that has delivered a block asked after this one has passed this one over, and its bytes do not count for it. Above the last checkpoint this applies to every block, one block per quiet owner. Below it, a block with one active owner that is still sending other block bytes, and has not passed this one over, stays with it, and the watcher judges it; the watcher also treats a passed-over block as one its owner will not deliver.
  • During headers-first sync, a block above the committed tip that has been arriving for 30 seconds at under 100 KB/s, and will not finish before the chain needs it, is asked of one other peer, and the slow peer is disconnected. Every copy of the block must be that slow, a further copy waits 30 seconds after the last one, and at most three peers send or are expected to send a block at once. A peer let off a block that sends nothing is not counted. The slow peer is kept connected when the peer asked is one that was let off the block and asked again, or, at the three-copy limit, when such a peer is still connected and sends nothing. These are SV Node’s slow-fetch timeout, stalling rate and parallel-fetch limit.
  • During headers-first sync, the watcher examines up to 64 owed blocks from the tip every 5 seconds. A block that will land 30 seconds or more after each block below it is also asked of one other peer: for a block arriving, whose size its first bytes declare, the peer that lands a full copy in half the owner’s time; for a queued block, the fastest peer with twice the owner’s rate that lands the block, at the recent mean size, in half the owner’s time. A copy with more than half its bytes gets no extra request unless it will take more than 5 minutes, and a block whose every copy arrives under 100 KB/s is left to the race, with no block above it counted as late. A block is judged while it has one live copy, and the watcher and the race together ask for at most two extra copies of a block in 10 minutes. There is no setting for it; the metric is teranode_legacy_netsync_frontier_races_total.
  • MultiPeerBlockDownload set to false keeps the pass but gives every block to the sync peer, bounded by the block-size ladder alone.

Block Prefetch

Asynchronous block admission is always on and never active on regtest. The block’s bytes have already been streamed to files by the time admission runs, so each block charges one slot against a budget sized as MaxBlocksInTransitPerPeer times four. At the defaults that is 64 blocks.

Out-of-Order Block Park

  • The park needs a temp store it can enumerate after a restart, so the node refuses to start on any temp_store URL that is not a file:// store, and on a node with no temp store at all. Every downloaded block goes through the park.
  • ParkStoreTimeout bounds the wait for the file store’s process-wide permits, which are shared with subtree writes, transaction writes and both persisters. It does not bound the work the store does once it holds a permit.

Peer Registry Mirror

PeerRegistryEnabled and PeerRegistrySyncInterval control the mirror that makes legacy peers visible in the dashboard beside libp2p peers.

The mirror is a read-only visibility path. It feeds no sync, catchup or peer-selection decision, and the legacy service’s own sync engine (services/legacy/netsync) is unaffected by it either way.

  • Each tick snapshots the connected legacy peers and pushes only what changed, so an idle peer costs no RPC.
  • Entries are registered with the wire-protocol transport type and keyed legacy:host:port, which keeps them distinguishable from libp2p peers at every layer.
  • A peer that disappears is marked disconnected once, then left for the registry TTL to reap.
  • Each registry call is bounded independently, so an unresponsive blockchain service delays a tick rather than stalling the mirror.

Requirements

  • The blockchain service must be reachable, since it hosts the registry. When the registry client is unavailable the mirror does not start and the legacy service runs normally without dashboard peer visibility.

Recommendations

  • Keep PeerRegistryEnabled at true for operator visibility. Set it to false only if the extra registry traffic is unwelcome on a node carrying very many legacy connections.
  • The default 10s interval sits well below the legacy two-minute ping interval. Values under one second are pointless, because the underlying peer statistics do not change that fast.

Service Dependencies

DependencyInterfaceUsage
SubtreeStoreblob.StoreCRITICAL - Merkle subtree storage and verification
TempStoreblob.StoreCRITICAL - Temporary data storage, including the out-of-order block park
UTXOStoreutxo.StoreCRITICAL - UTXO operations
BlockchainClientblockchain.ClientICRITICAL - Blockchain operations and state queries
ValidatorClientvalidator.InterfaceCRITICAL - Transaction validation
SubtreeValidationClientsubtreevalidation.InterfaceCRITICAL - Subtree validation
BlockValidationClientblockvalidation.InterfaceCRITICAL - Block validation
BlockAssemblyClient*blockassembly.ClientCRITICAL - Block assembly operations

Validation Rules

SettingValidationImpactWhen Checked
GRPCAddressMust not be emptyClient creation returns a configuration errorDuring client initialization
TempStoreMust be setDaemon returns “temp_store config not found”During store construction
ListenAddressesFalls back to the outbound interface IP and the network’s default port if emptyNetwork connectivityDuring server start
ParkStoreTimeoutRaised to 1s if lowerA zero deadline would fail every store operation instantlyDuring sync manager construction
MaxFeelerPeersZeroed by connect-only mode, or by a peer cap too tight to hold the reservationFeelers and their slot reservation are both switched off, with the reason loggedDuring server construction
FeelerIntervalNon-positive falls back to 120s with a warningProbe pacingWhen the feeler loop starts
FeelerHandshakeTimeoutNon-positive falls back to 25s; 30s or more is reduced to 29s, both with a warningA deadline at or above the peer negotiate timeout lets the peer package tear the connection down firstWhen the feeler loop starts
Block download timeout percentsResult floored at 30 minutes and capped at the largest budget these settings can produceThe scaling can only widen a block’s deadline, never narrow itPer block download

Configuration Examples

Basic Configuration

legacy_listen_addresses = "0.0.0.0:8333"
legacy_savePeers = false

Forced Peer Connections

legacy_connect_peers = "peer1.example.com:8333|peer2.example.com:8333"

Connect-only mode lowers the peer cap to the length of the list and switches feeler probes off. It does not switch off DNS seeding.

Bounding Read-Ahead

legacy_blockDownloadWindow = 32
legacy_maxBlocksInTransitPerPeer = 8

Lower values keep the park small and the node’s memory footprint down, at the cost of a sync more exposed to one slow peer.