BSV blockchainBSV blockchain

Block Validation Service Settings

Related Topic: Block Validation Service

Configuration Settings

The Default column is the loader fallback in settings/settings.go. A node uses it only when no configuration file sets the key. A node that runs on the repository configuration uses the base value in the committed settings.conf when that file sets the key, unless settings_local.conf or a context-specific key (key.<context>) sets another. settings.conf sets blockvalidation_quick_validate_create_concurrency, blockvalidation_outpoint_only_below_checkpoint and blockvalidation_legacy_unified_below_checkpoint to the same values as the loader (0, false and false), so for these keys the two agree. The blockvalidation_isParentMined_retry_* keys and blockvalidation_catchup_prefetch_budget_bytes have no line in settings.conf.

SettingTypeDefaultEnvironment VariableUsage
MaxRetriesint3blockValidationMaxRetriesRequeues per block after a fetch failure or deadline
RetrySleeptime.Duration1sblockValidationRetrySleepRetry delay timing
GRPCAddressstring“localhost:8088”blockvalidation_grpcAddressClient connection address
GRPCListenAddressstring“:8088”blockvalidation_grpcListenAddressCRITICAL - gRPC server binding (service skipped if empty)
LocalSetTxMinedConcurrencyint8blockvalidation_localSetTxMinedConcurrencyTransaction mining concurrency
MaxPreviousBlockHeadersToCheckuint64100blockvalidation_maxPreviousBlockHeadersToCheckBlock header validation depth
MissingTransactionsBatchSizeint5000blockvalidation_missingTransactionsBatchSizeMissing transaction batch size
ProcessTxMetaUsingCacheBatchSizeint1024blockvalidation_processTxMetaUsingCache_BatchSizeCache processing batch size
ProcessTxMetaUsingCacheConcurrencyint32blockvalidation_processTxMetaUsingCache_ConcurrencyCache processing concurrency
ProcessTxMetaUsingCacheMissingTxThresholdint1blockvalidation_processTxMetaUsingCache_MissingTxThresholdCache miss threshold
ProcessTxMetaUsingStoreBatchSizeint1024blockvalidation_processTxMetaUsingStore_BatchSizeStore processing batch size
ProcessTxMetaUsingStoreConcurrencyintmax(4, CPU/2)blockvalidation_processTxMetaUsingStore_ConcurrencyStore processing concurrency
ProcessTxMetaUsingStoreMissingTxThresholdint1blockvalidation_processTxMetaUsingStore_MissingTxThresholdStore miss threshold
ProcessTxMetaUsingStoreRetriesint3blockvalidation_processTxMetaUsingStore_RetriesRetries for a transient store failure; negative values clamp to 0
SkipCheckParentMinedboolfalseblockvalidation_skipCheckParentMinedParent block mining validation
SubtreeFoundChConcurrencyint1blockvalidation_subtreeFoundChConcurrencySubtree processing concurrency
SubtreeValidationAbandonThresholdint1blockvalidation_subtree_validation_abandon_thresholdSubtree validation abandonment
ValidateBlockSubtreesConcurrencyintmax(4, CPU/2)blockvalidation_validateBlockSubtreesConcurrencyBlock subtree validation concurrency
ValidationMaxRetriesint3blockvalidation_validation_max_retriesValidation retry attempts
ValidationRetrySleeptime.Duration5sblockvalidation_validation_retry_sleepValidation retry delay
OptimisticMiningbooltrueblockvalidation_optimistic_miningOptimistic mining behavior (global; every validation path also requires OptimisticMiningPeerBlocks, and catch-up is never optimistic)
OptimisticMiningPeerBlocksboolfalseblockvalidation_optimistic_mining_peer_blocksOpt in to optimistic mining on the peer-served path (accepts the invalidate-route tradeoff)
MaxCorruptAttemptsPerBlockint3blockvalidation_max_corrupt_attempts_per_blockBan-score-independent per-(block hash, serving peerID) cap on corrupt re-downloads; also sizes the separate local-policy decline cap and the worker panic cap (0 disables all three, re-opening the DoS)
CorruptAttemptCooldowntime.Duration10mblockvalidation_corrupt_attempt_cooldownFixed cooldown window after which a capped (hash, peerID) is admitted again, for the corrupt, local-policy decline and worker panic caps
IsParentMinedRetryMaxRetryint45blockvalidation_isParentMined_retry_max_retryParent mining check retries
IsParentMinedRetryBackoffMultiplierint4blockvalidation_isParentMined_retry_backoff_multiplierSlope of the linear backoff between parent-mined retries: the wait before retry i, counting from 0, is (multiplier x i + 1) x base
IsParentMinedRetryBackoffDurationtime.Duration20msblockvalidation_isParentMined_retry_backoff_durationParent mining retry backoff base duration
SubtreeGroupConcurrencyint1blockvalidation_subtreeGroupConcurrencySubtree group processing concurrency
BlockFoundChBufferSizeint1000blockvalidation_blockFoundCh_buffer_sizeBlock discovery pipeline buffer
CatchupChBufferSizeint100blockvalidation_catchupCh_buffer_sizeCatchup processing pipeline buffer
UseCatchupWhenBehindboolfalseblockvalidation_useCatchupWhenBehindCRITICAL - Catchup mode enablement
CatchupConcurrencyintmax(4, CPU/2)blockvalidation_catchupConcurrencyCatchup processing concurrency
ValidationWarmupCountint128blockvalidation_validation_warmup_countValidation warmup behavior
BatchMissingTransactionsboolfalseblockvalidation_batch_missing_transactionsMissing transaction batching
CheckSubtreeFromBlockTimeouttime.Duration5mblockvalidation_check_subtree_from_block_timeoutSubtree validation timeout
SubtreeDataFetchTimeouttime.Duration10mblockvalidation_subtree_data_fetch_timeoutBound on one detached subtree_data fetch (download + parse + store)
SubtreeMetaPeerFetchTimeouttime.Duration10mblockvalidation_subtree_meta_peer_fetch_timeoutPer-fetch budget for a subtree meta regeneration subtree_data fetch (all 503 retries + body stream); a cache-busting retry gets a fresh budget
CheckSubtreeFromBlockRetriesint5blockvalidation_check_subtree_from_block_retriesSubtree validation retries
CheckSubtreeFromBlockRetryBackoffDurationtime.Duration30sblockvalidation_check_subtree_from_block_retry_backoff_durationSubtree retry backoff
SecretMiningThresholduint3299blockvalidation_secret_mining_thresholdCRITICAL - Secret mining detection
PreviousBlockHeaderCountuint64100blockvalidation_previous_block_header_countCRITICAL - Header chain cache size. Floored at 11 (settings.MedianTimeSpan): the run is what median-time-past is measured over, so a lower value would compute the median over fewer blocks than consensus requires and accept blocks the rest of the network rejects. Anything below 11 is raised to it, with a warning on stderr
CatchupMaxRetriesint3blockvalidation_catchup_max_retriesCatchup operation retries
CatchupIterationTimeoutint30blockvalidation_catchup_iteration_timeoutCRITICAL - Catchup iteration timeout
CatchupOperationTimeoutint300blockvalidation_catchup_operation_timeoutCRITICAL - Catchup operation timeout
CatchupMaxAccumulatedHeadersint100000blockvalidation_max_accumulated_headersCRITICAL - Memory protection during catchup. Not used on utxoset below the hardcoded checkpoint: each catch-up window there runs from where the node is to the next hardcoded checkpoint (at most one checkpoint gap plus any UTXO-store lag; testnet’s largest gap, 100,010 blocks, is about 8 MB of headers). Block validation refuses to start there when blockvalidation_catchup_checkpoint_hash and blockvalidation_catchup_checkpoint_height are set
CircuitBreakerFailureThresholdint5blockvalidation_circuit_breaker_failure_thresholdCircuit breaker failure detection
CircuitBreakerSuccessThresholdint2blockvalidation_circuit_breaker_success_thresholdCircuit breaker recovery
CircuitBreakerTimeoutSecondsint30blockvalidation_circuit_breaker_timeout_secondsCircuit breaker timeout
MaxBlocksBehindBlockAssemblyint20blockvalidation_maxBlocksBehindBlockAssemblyCRITICAL - Max blocks behind block assembly
PeriodicProcessingIntervaltime.Duration1mblockvalidation_periodic_processing_intervalPeriodic processing interval
RecentBlockIDsLimituint6450000blockvalidation_recentBlockIDsLimitCRITICAL - Fast-path double-spend checking window
MaxParallelForksint4blockvalidation_max_parallel_forksMaximum parallel fork processing
MaxTrackedForksint1000blockvalidation_max_tracked_forksMaximum total forks tracked
NearForkThresholdint0blockvalidation_near_fork_thresholdNear fork detection (0=coinbase maturity/2)
FetchLargeBatchSizeint100blockvalidation_fetch_large_batch_sizeBlock fetch batch size
FetchNumWorkersint16blockvalidation_fetch_num_workersCatchup workers running the per-block subtree-data prewarm
FetchBufferSizeint50blockvalidation_fetch_buffer_sizeBlock fetch channel buffer
SubtreeFetchConcurrencyint32blockvalidation_subtree_fetch_concurrencyConcurrent subtree fetches per block
CatchupPrefetchBudgetBytesint64268435456blockvalidation_catchup_prefetch_budget_bytesDeclared block bytes admitted concurrently into the catchup subtree-data prewarm (0 disables the budget and the subtree-concurrency rule it drives)
SubtreeBatchSizeint16blockvalidation_subtree_batch_sizeSubtrees processed per batch in quick validation
SubtreeBatchPrefetchDepthint2blockvalidation_subtree_batch_prefetch_depthBatches to prefetch ahead in pipeline (0=sequential)
GetBlockTransactionsConcurrencyint64blockvalidation_get_block_transactions_concurrencyBlock transaction fetch concurrency
ExtendTransactionTimeouttime.Duration120sblockvalidation_extend_transaction_timeoutTimeout for extending transaction inputs
SubtreeBatchWriteConcurrencyint64blockvalidation_subtree_batch_write_concurrencyConcurrent subtree file writes per batch
CatchupMinThroughputKBpsint100blockvalidation_catchup_min_throughput_kbpsMinimum throughput (KB/s) before switching peers
CatchupParallelFetchEnabledbooltrueblockvalidation_catchup_parallel_fetch_enabledEnable parallel fetching from multiple peers
CatchupParallelFetchWorkersint3blockvalidation_catchup_parallel_fetch_workersNumber of parallel fetch workers
CatchupKeepBlockAssemblyMaxBlocksint6blockvalidation_catchup_keep_block_assembly_max_blocksMost blocks a catch-up from RUNNING may fetch and still hand transactions to block assembly
QuickValidateCreateConcurrencyint0blockvalidation_quick_validate_create_concurrencyCallers allowed in flight at once in the first wave of a below-checkpoint list that quick validation hands the SQL and Aerospike UTXO stores; that wave creates every record and also spends the inputs of each transaction with no parent in the list. 0 derives it as max(min(utxostore_storeBatcherSize x utxostore_batcherMaxConcurrent, 16384), utxostore_storeBatcherSize x 8); an explicit value is not capped
OutpointOnlyBelowCheckpointboolfalseblockvalidation_outpoint_only_below_checkpointBelow the hardcoded checkpoint, quick validation spends by outpoint and skips parent reads, fees and the UTXO-hash checksum. Only on stores that support outpoint-only spends (SQL); Aerospike keeps reading parent outputs. No effect on utxoset, which always takes this route below the checkpoint
QuickValidateNetRangeint65536blockvalidation_quick_validate_net_rangeTransactions per list that quick validation hands a store that nets below the checkpoint (utxoset): fixed ranges of transaction positions, the same lists whatever subtree size a block arrives with. Must be a power of two, otherwise the default is used. Do not change it while a block is partly applied
LegacyUnifiedBelowCheckpointboolfalseblockvalidation_legacy_unified_below_checkpointLegacy below-checkpoint blocks are quick-validated through the native catchup path’s machinery instead of fully validated. Requires the setting above, a store that supports outpoint-only spends and a header run proven to end at a pinned checkpoint; legacy and block validation must agree on both settings. Off, every legacy block is fully validated. No effect on utxoset: there legacy and block validation ignore this setting and the one above, and always take the route, because that store takes blocks below the checkpoint only through quick validation

Configuration Dependencies

Service Startup

  • Service skipped (not added to ServiceManager) if GRPCListenAddress is empty
  • Kafka consumer created for block processing

Catchup Mode

  • When UseCatchupWhenBehind = true, all catchup settings control behavior
  • CatchupMaxAccumulatedHeaders prevents memory exhaustion
  • Timeout settings control iteration and operation limits
  • Catchup automatically engages when node falls behind

Optimistic Mining

  • OptimisticMining defaults to true: once the block’s subtrees have been validated (transaction and script checks, synchronously), the block is added to the chain and mining can start on it, before the remaining block-level checks have run
  • Those block-level checks continue in the background - merkle root, coinbase and BIP34 checks, duplicate transactions, transaction ordering and parent-spend checks, and the old-block-ID double-spend scan. If a background check proves the block invalid it is invalidated and its UTXO effects are rolled back; a transient storage or processing failure instead schedules a re-validation and leaves the block on the chain in the meantime
  • Can be overridden per-validation via the DisableOptimisticMining option
  • On every validation path optimistic mining is OFF unless BOTH blockvalidation_optimistic_mining AND blockvalidation_optimistic_mining_peer_blocks are set (default (true, false) = off). The requirement is applied where each validation chooses its mode, not only at the peer entry gate, so an internal caller cannot turn optimistic on the global flag alone (bitcoin-sv/teranode#4844). The global flag being false always wins, so the peer-blocks flag can never bypass it (bitcoin-sv/teranode#4692). Revalidation of an already-stored block, and blocks arriving over the legacy sync route (baseURL == "legacy"), are always non-optimistic regardless of these flags.
  • The catch-up path is always non-optimistic, whatever these two flags are set to. It validates against a cached header run holding only the block’s in-batch predecessors, which cannot carry the median-time-past window the optimistic branch checks synchronously; lifting this requires the header cache to top up short windows from the store first (issue 1499).
  • Opt-in tradeoff: with both flags set, a corrupt body on the optimistic-background path is already added before background validation runs, so it takes the invalidate route (it is invalidated/poisoned rather than re-downloaded) until the block.Valid integrity-floor split lands and removes that path. With the default (peer-blocks off) a corrupt body is never added and is re-downloaded, not poisoned.
  • Known exposure under the opt-in: a received body that carries subtrees is still added before it is bound to its header, and when it is invalidated its coinbase is persisted with the invalid record (bitcoin-sv/teranode#4844). A body carrying no subtrees is bound by the coinbase-only rule and rejected before the add. Keep blockvalidation_optimistic_mining_peer_blocks off until the block.Valid split lands.
  • Checkpoint-verified blocks take the quick-validation pipeline instead, which never consults this setting.

Corrupt-body re-download cap

  • Independently of the per-peer ban score, corrupt-body re-downloads are bounded per (block hash, serving peerID) on the RUNNING and legacy netsync paths by MaxCorruptAttemptsPerBlock (default 3) within a fixed CorruptAttemptCooldown window (default 10m), then dropped before the expensive download/validate work until the window lapses (bitcoin-sv/teranode#4692). Keying on the pair rather than the hash alone is deliberate: one peer’s corruption can never consume the budget for a hash an honest peer can still serve, so a bad peer cannot wedge the honest tip. The residual aggregate per-hash bound is therefore (concurrent distinct serving peers) × this cap per window.
  • The cap never poisons a hash: once the window lapses an honest body is admitted again, and the counter is cleared by a successful validation. Setting MaxCorruptAttemptsPerBlock to 0 disables the cap and re-opens the corrupt-body bandwidth DoS, so it is strongly discouraged.
  • A separate per-(hash, peerID) counter, sized by the same two settings, bounds repeat deliveries of a block this node declines on local excessiveblocksize policy, so an oversized block is not re-fetched from the same peer indefinitely. A policy decline is not a corrupt body: it never strikes the peer, never marks the hash invalid, and spends a budget of its own rather than the corrupt one.

Quick Validation Pipeline

For checkpoint-verified blocks, a fan-in pipeline overlaps I/O with processing:

  • SubtreeBatchPrefetchDepth controls how many batches to prefetch ahead (default: 2)
  • Setting to 0 disables the pipeline and uses sequential processing
  • Three pipeline stages:
    1. Reader: Prefetches subtree batches from disk
    2. Extender: Extends transactions with UTXO data (sequential for map dependency)
    3. Processor: Creates/spends UTXOs and writes files in parallel per batch

Transaction Metadata Processing

  • Cache and store processing work together with threshold-based fallback
  • Batch sizes and concurrency settings control performance

Secret Mining Detection

  • SecretMiningThreshold uses PreviousBlockHeaderCount for analysis
  • Detection triggers when block difference exceeds threshold

Two-Phase Double-Spend Detection

  • RecentBlockIDsLimit controls the size of the fast-path in-memory block ID window
  • Transactions mined in blocks within this window are detected immediately (fast path)
  • Transactions mined in older blocks trigger a blockchain service query (slow path)
  • Larger values use more memory but reduce slow-path queries
  • Default of 50,000 covers approximately 347 days of blocks at 10-minute intervals

Channel Buffer Management

  • BlockFoundChBufferSize and CatchupChBufferSize must accommodate processing loads

Service Dependencies

DependencyInterfaceUsage
UTXOStoreutxo.StoreCRITICAL - UTXO operations and validation
TxStoreblob.StoreCRITICAL - Transaction data access
SubtreeStoreblob.StoreCRITICAL - Subtree validation
BlockchainClientblockchain.ClientICRITICAL - Blockchain operations and header retrieval
SubtreeValidationClientsubtreevalidation.ClientICRITICAL - Subtree validation operations
ValidatorClientvalidator.ClientICRITICAL - Block validation operations

Validation Rules

SettingValidationImpactWhen Checked
GRPCListenAddressMust not be emptyService skipped if emptyDuring daemon startup
UseCatchupWhenBehindControls catchup mode activationChain synchronization
CatchupMaxAccumulatedHeadersLimits memory usageMemory protection
SecretMiningThresholdEnables attack detectionSecurity

Configuration Examples

Basic Configuration

blockvalidation_grpcListenAddress=:8088
blockvalidation_useCatchupWhenBehind=false

High Performance Configuration

blockvalidation_validateBlockSubtreesConcurrency=16
blockvalidation_processTxMetaUsingStore_BatchSize=2048
blockvalidation_catchupConcurrency=8
blockvalidation_fetch_num_workers=32
blockvalidation_subtree_batch_size=32

Raising blockvalidation_fetch_num_workers raises catchup memory: each worker runs one block’s subtree-data prewarm, parsing every transaction of every subtree of that block into memory. Size blockvalidation_catchup_prefetch_budget_bytes against measured headroom on the target deployment — it caps the declared block bytes admitted concurrently across those workers, which is not the same thing as a process-memory ceiling.

A block whose declared size exceeds that budget, or which declares no size at all, parses its subtrees one at a time instead of blockvalidation_subtree_fetch_concurrency at a time. Setting the budget to 0 disables the budget and that rule together; it does not restore the pre-budget behaviour exactly, because subtree data is streamed into the blob store either way. The counters teranode_blockvalidation_catchup_prefetch_budget_parked_total, teranode_blockvalidation_catchup_prefetch_oversized_blocks_total and teranode_blockvalidation_catchup_prefetch_undeclared_size_blocks_total report how often each of those regimes is entered.

Catchup Mode Configuration

blockvalidation_useCatchupWhenBehind=true
blockvalidation_catchup_max_retries=5
blockvalidation_catchup_iteration_timeout=60
blockvalidation_max_accumulated_headers=50000

Pipeline Processing Configuration

# Enable pipeline with larger prefetch depth for high-latency storage
blockvalidation_subtree_batch_prefetch_depth=4
blockvalidation_subtree_batch_size=32

# Disable pipeline (sequential processing)
blockvalidation_subtree_batch_prefetch_depth=0