BSV blockchainBSV blockchain

Subtree Validation Service Settings

Related Topic: Subtree Validation Service

Configuration Settings

SettingTypeDefaultEnvironment VariableUsage
QuorumPathstring""subtree_quorum_pathQuorum coordination directory
QuorumAbsoluteTimeouttime.Duration30ssubtree_quorum_absolute_timeoutQuorum operation timeout
SubtreeStore*url.URL""subtreestoreCRITICAL - Subtree data storage
GetMissingTransactionsintmax(4, CPU/2)subtreevalidation_getMissingTransactionsCRITICAL - Missing transaction retrieval concurrency
GRPCAddressstring“localhost:8089” (Go default; overridden to localhost:8086 by settings.conf via SUBTREE_VALIDATION_GRPC_PORT)subtreevalidation_grpcAddressgRPC client connections
GRPCListenAddressstring“:8089” (Go default; overridden to :8086 by settings.conf via SUBTREE_VALIDATION_GRPC_PORT)subtreevalidation_grpcListenAddressCRITICAL - gRPC server binding, health checks only run if not empty
ProcessTxMetaUsingCacheConcurrencyint32subtreevalidation_processTxMetaUsingCache_ConcurrencyCRITICAL - Cache-probe workers shared by all subtrees being validated (server-wide, not per subtree; peer subtrees and block validation each get a pool of this size)
PeerSubtreeConcurrencyint32subtreevalidation_peerSubtreeConcurrencyPeer-announced subtrees validated at once (each holds ~1 GiB per 1M txs); taken before the quorum lock, so block validation never waits behind the queue. Block subtrees do not use it. 0 or less disables the limit
TxMetaTombstoneWindowtime.Duration30msubtreevalidation_txMetaTombstoneWindowHow long a txmeta DELETE (a tx demoted to conflicting) keeps that tx out of the txmeta cache, against late ADDs and read-through writes; entries live one to two windows, about 60 MB per million demoted txs. Must exceed the worst txmeta consumer lag; must be positive
SkippedSubtreeBackfillMaxint4096subtreevalidation_skippedSubtreeBackfillMaxPeer subtrees announced while catching up that are kept and validated once the node is RUNNING again (deduplicated by hash, oldest dropped when full, replayed with at most half the peer-subtree slots). 0 or less turns the backfill off
FailedSubtreeNegativeCacheTTLtime.Duration30ssubtreevalidation_failedSubtreeNegativeCacheTTLHow long a peer-announced subtree that failed validation is skipped when re-announced with the same URL (keyed by hash and DataHub URL, at most 4096 entries; cancellations are not kept; block validation never consults it). 0 turns the cache off
ProcessTxMetaUsingCacheMissingTxThresholdint1subtreevalidation_processTxMetaUsingCache_MissingTxThresholdCache miss threshold
BlockHeightRetentionAdjustmentint320subtreevalidation_blockHeightRetentionAdjustmentAdjustment applied to GlobalBlockHeightRetention (see GetSubtreeValidationBlockHeightRetention)
SubtreeDAHConcurrencyint8subtreevalidation_subtreeDAHConcurrencyDAH processing concurrency
TxMetaCacheEnabledbooltruesubtreevalidation_txMetaCacheEnabledCRITICAL - Transaction metadata cache
TxMetaCacheMaxMBint256txMetaCacheMaxMBCache memory limit
TxChanBufferSizeint0subtreevalidation_txChanBufferSizeTransaction channel buffer size
BatchMissingTransactionsbooltruesubtreevalidation_batch_missing_transactionsCRITICAL - Missing transaction batching
SpendBatcherSizeint1024subtreevalidation_spendBatcherSizeCRITICAL - Spend operation batch size and concurrency control
MissingTransactionsBatchSizeint16384subtreevalidation_missingTransactionsBatchSizeCRITICAL - Missing transaction batch size
PercentageMissingGetFullDatafloat6420subtreevalidation_percentageMissingGetFullDataCRITICAL - Full subtree vs individual transaction threshold
BlacklistedBaseURLsmap[string]struct{}{}subtreevalidation_blacklisted_baseurlsURL blacklisting
CheckBlockSubtreesConcurrencyint32subtreevalidation_check_block_subtrees_concurrencyCRITICAL - Block subtree checking concurrency
PauseTimeouttime.Duration5msubtreevalidation_pauseTimeoutCRITICAL - Maximum pause duration
TxBatchSizeint1048576subtreevalidation_check_block_subtrees_tx_batch_sizeTransaction batch size for CheckBlockSubtrees (0 = no batching)
UseOrderedLevelAlgorithmbooltruesubtreevalidation_useOrderedLevelAlgorithmCRITICAL - Optimized O(V*I) algorithm for ordered transactions
BlocksOnlyboolfalsesubtreevalidation_blocks_onlyOnly process subtrees from blocks, skip peer-announced subtrees

Configuration Dependencies

Cache Processing

  • ProcessTxMetaUsingCacheConcurrency (server-wide probe workers, one pool for peer subtrees and one for block validation) and ProcessTxMetaUsingCacheMissingTxThreshold work together
  • A subtree’s cache lookups are grouped by cache bucket range; each range is one batched read on one of the shared workers

Missing Transaction Handling

  • When BatchMissingTransactions = true, uses MissingTransactionsBatchSize and GetMissingTransactions
  • PercentageMissingGetFullData determines full subtree vs individual transaction fetching

Concurrency Control

  • CheckBlockSubtreesConcurrency controls block subtree checking operations
  • SpendBatcherSize controls spend operation batch processing and concurrency limits
  • GetMissingTransactions controls missing transaction retrieval concurrency
  • TxBatchSize controls transaction batching for CheckBlockSubtrees (0 disables batching)

Algorithm Optimization

  • UseOrderedLevelAlgorithm enables optimized O(V*I) algorithm assuming transactions are ordered
  • When true, improves performance for ordered transaction processing

gRPC Server Management

  • When GRPCListenAddress is not empty, gRPC server starts and health checks are enabled

Service Dependencies

DependencyInterfaceUsage
SubtreeStoreblob.StoreCRITICAL - Subtree data storage and retrieval
TxStoreblob.StoreCRITICAL - Transaction data access
UTXOStoreutxo.StoreCRITICAL - UTXO operations and validation
ValidatorClientvalidator.InterfaceCRITICAL - Transaction validation operations

Validation Rules

SettingValidationImpactWhen Checked
GRPCListenAddressHealth checks only if not emptyService monitoringDuring service initialization
SubtreeStoreMust be valid URL formatStorage accessDuring service initialization
TxMetaCacheEnabledControls cache usagePerformanceDuring transaction processing
PauseTimeoutControls maximum pause durationProcessing controlDuring block validation
UseOrderedLevelAlgorithmControls algorithm selectionPerformance optimizationDuring subtree validation

Configuration Examples

Basic Configuration

subtreevalidation_grpcListenAddress=:8086
subtreestore=memory:///

Performance Tuning

subtreevalidation_check_block_subtrees_concurrency=64
subtreevalidation_getMissingTransactions=16
subtreevalidation_spendBatcherSize=2048

Cache Configuration

subtreevalidation_txMetaCacheEnabled=true
txMetaCacheMaxMB=512