BSV blockchainBSV blockchain

Block Assembly Service Settings

Related Topic: Block Assembly Service

Configuration Settings

SettingTypeDefaultEnvironment VariableUsage
Disabledboolfalseblockassembly_disabledService-level kill switch, all operations return early
GenerateTipWaitTimeouttime.Duration90sblockassembly_generateTipWaitTimeoutBounds the generate readiness wait; effective bound is min(this, caller deadline)
GRPCAddressstring“localhost:8085”blockassembly_grpcAddressClient connection address
GRPCListenAddressstring“:8085”blockassembly_grpcListenAddressCRITICAL - gRPC server binding (service skipped if empty)
GRPCMaxRetriesint3blockassembly_grpcMaxRetriesgRPC client retry attempts
GRPCRetryBackofftime.Duration2sblockassembly_grpcRetryBackoffRetry delay timing
LivenessStallTimeouttime.Duration0sblockassembly_livenessStallTimeoutLiveness reports 503 if the main select stops being serviced for this long; 0 = off
LocalDAHCachestring""blockassembly_localDAHCacheUNUSED - Reserved for future DAH caching
MaxBlockReorgRollbackint100blockassembly_maxBlockReorgRollbackUNUSED - Defined but not referenced in code
MoveBackBlockConcurrencyint375blockassembly_moveBackBlockConcurrencyConcurrency limit for reorg processing (SubtreeProcessor)
ProcessRemainderTxHashesConcurrencyint375blockassembly_processRemainderTxHashesConcurrencyConcurrency limit for remainder tx hash processing
ReconcileIntervaltime.Duration30sblockassembly_reconcileIntervalIdle polling interval, and how often a pass re-reads the low-water mark without a BlockMinedUnset; 0 disables both (a lost BlockMinedUnset then leaves block assembly on an invalidated tip until the next invalidation or a restart), unfinished reset recovery still retries, at most three passes before the history is given up
SendBatchSizeint100blockassembly_sendBatchSizeClient batch size for sending transactions
SendBatchTimeoutint2blockassembly_sendBatchTimeoutClient batch timeout in seconds
SubtreeProcessorBatcherSizeint1000blockassembly_subtreeProcessorBatcherSizeSubtree processing batch size
SubtreeProcessorConcurrentReadsint375blockassembly_subtreeProcessorConcurrentReadsCRITICAL - Subtree read parallelism
NewSubtreeChanBufferint1000blockassembly_newSubtreeChanBufferCRITICAL - New subtree channel buffer
SubtreeRetryChanBufferint1000blockassembly_subtreeRetryChanBufferCRITICAL - Retry channel buffer
SubmitMiningSolutionWaitForResponsebooltrueblockassembly_SubmitMiningSolution_waitForResponseCRITICAL - Sync (true) vs async (false) mining solution processing
InitialMerkleItemsPerSubtreeint1048576initial_merkle_items_per_subtreeInitial subtree size
MinimumMerkleItemsPerSubtreeint1024minimum_merkle_items_per_subtreeMinimum subtree size
MaximumMerkleItemsPerSubtreeint1048576maximum_merkle_items_per_subtreeMaximum subtree size
DoubleSpendWindowtime.Duration0double_spend_window_millisDouble-spend detection window; 0 disables it
MaxGetReorgHashesint10000blockassembly_maxGetReorgHashesCRITICAL - Reorganization hash limit
MinerWalletPrivateKeys[]string[]miner_wallet_private_keysMining wallet keys
EmergencyDifficultyDelaytime.Duration0sblockassembly_emergencyDifficultyDelayExtra wait before a minimum-difficulty candidate; staggers miners (testnets only)
DifficultyCachebooltrueblockassembly_difficultyCacheEnables difficulty calculation caching (Blockchain service)
UseDynamicSubtreeSizeboolfalseblockassembly_useDynamicSubtreeSizeDynamic subtree sizing
BlockchainSubscriptionTimeouttime.Duration5mblockassembly_blockchainSubscriptionTimeoutBlockchain event subscription timeout
OnRestartValidateParentChainbooltrueblockassembly_onRestartValidateParentChainEnables parent chain validation on restart
ParentValidationBatchSizeint1000blockassembly_parentValidationBatchSizeParent validation batch size
OnRestartRemoveInvalidParentChainTxsbooltrueblockassembly_onRestartRemoveInvalidParentChainTxsFilters transactions with invalid parent chains
SubtreeStorageWorkersint4blockassembly_subtreeStorageWorkersWorkers for subtree storage operations
SubtreeAnnouncementIntervaltime.Duration10sblockassembly_subtreeAnnouncementIntervalSubtree announcement frequency
UseColumnarBatchboolfalseblockassembly_useColumnarBatchUse columnar batch format for data layout
UnminedTxDiskSortPaths[]string[]blockassembly_unminedTxDiskSortPathPipe-separated directories for disk-sorted unmined reload runs (OS temp dir if empty)
UnminedTxDiskSortEnabledboolfalseblockassembly_unminedTxDiskSortEnabledEnable disk-based sorting for large mempools
UnminedLoadingBatchSizeint10485760blockassembly_unminedLoadingBatchSizeBatch size for loading unmined transactions
UnminedTxSortBufferRecordsint33554432blockassembly_unminedTxSortBufferRecordsRecords buffered before the disk-sorted reload spills a sorted run
ParallelSetIfNotExistsThresholdint10000blockassembly_parallelSetIfNotExistsThresholdThreshold for parallelizing conditional writes
StoreTxInpointsForSubtreeMetabooltrueblockassembly_storeTxInpointsForSubtreeMetaStore transaction input points in subtree metadata (required for checkblocktemplate)
IdleSleepDurationtime.Duration10msblockassembly_idle_sleep_durationSleep duration when subtree processor queue is empty
MaxTransactionsInMemoryuint640blockassembly_maxTransactionsInMemoryRefuse ingest while this many transactions are held in memory (subtrees plus queue); block transactions are not refused; 0 = off
CoinbaseRecoveryMaxGapBlocksint200blockassembly_coinbaseRecoveryMaxGapBlocksStartup scan window below the tip, and the largest coinbase gap auto-repair will fix
CoinbaseRecoveryConsecutiveGoodint6blockassembly_coinbaseRecoveryConsecutiveGoodConsecutive present coinbases proving the gap floor during walk-back
CoinbaseRecoveryMaxAttemptsint3blockassembly_coinbaseRecoveryMaxAttemptsAutomatic coinbase-recovery attempts before raising an operator alert

In-Memory Transaction Limit

blockassembly_maxTransactionsInMemory caps the transactions block assembly holds in RAM, counted as those already placed in subtrees plus those queued for ingest. It is checked where every transaction enters block assembly, the ingest queue reservation, so it applies to all ingress paths, including the validator’s gRPC and HTTP listeners.

The limit assumes trusted gRPC callers. The InBlock flag on the validator ValidateTransaction request and on block assembly AddTx and AddTxBatch lifts the limit, like the other trust flags on those RPCs. The shipped profile sets security_level_grpc = 0, so an unauthenticated client that can reach the gRPC port can bypass the limit. Operators who expose gRPC must set security_level_grpc.

A batch that would cross the limit is refused with the same resource-exhausted status as a full ingest queue (blockassembly_maxQueueItems):

CallerOutcome
Synchronous submitter (gRPC, HTTP)Told to retry; the validator undoes the work it did for the transaction
Kafka ingestDropped at once, with no in-place retry, because this bound clears when a block connects or a load or reset ends; alert on teranode_validator_shed_dropped_total. Enable validator_kafkaBackpressureEnabled so the backlog waits in Kafka. With it off, every Kafka transaction at the limit, or during a load or reset, is validated, refused, unwound and dropped
Transaction inside a block (block validation, subtree validation, legacy sync)Not refused by this limit. It is admitted and counted. blockassembly_maxQueueItems still applies to it

The limit is soft. The count includes transactions dequeued but not yet placed in a subtree, so it does not under-read while a drain pass runs. Transactions inside a block are admitted past the limit, and the overshoot is bounded by the blocks being validated. A batch larger than the whole limit is admitted alone while the node is below it. The clamp floor comes from this pod’s blockassembly_sendBatchSize, but validator pods fill batches from their own config. The unmined-transaction reload at startup or reset, and transactions re-added from a reorged block, bypass the queue and are not limited: a node that restarts holding more than the limit loads them all and then refuses new ingest until blocks drain it. The held count reads full from construction of block assembly until its unmined load ends, during every reset, and while a failed reload waits for its retry, so mempool ingest is refused as held for that whole time, whatever the real count.

A value below one drain pass plus the coinbase placeholder is clamped up with a warning. Budget roughly 1KB of RAM per transaction when sizing.

Early shed at the limit

A validator polls block assembly’s held count and limit with the same queue-stats call as the Kafka backpressure controller, and shares that reading when the controller runs. Backpressure does not have to be enabled. While the held count is at the limit, the validator refuses an ingest transaction, one that did not arrive inside a block, before any UTXO store work. The refusal carries the same held marker as block assembly’s own, so the Kafka handler, subtree validation, gRPC and HTTP treat it as a held shed: not invalid, counted once in teranode_validator_held_limit_shed_transactions, and warned at a bounded rate. A transaction inside a block is never refused early. The reading can lag by one poll interval, so a transaction that crosses the limit between two polls still takes the refusal and unwind in the table above. The gate fails open: with no fresh reading, no reported limit or a failed read, the validator takes the ordinary path.

Upgrade order

Upgrade every validator and subtree-validation pod to a build that sends the InBlock flag before you set blockassembly_maxTransactionsInMemory on block assembly, and keep the default 0 until then. Block assembly cannot tell an old validator from a mempool batch. A validator that never sends InBlock has its block transactions refused as held, and its in-block shed arm then accepts them and unlocks them without a template entry. A block transaction is then outside the template with nothing holding its children back, which peers reject as an invalid block.

The limit assumes trusted gRPC callers. It does not refuse a transaction flagged inBlock, and the validator and block assembly gRPC APIs take that flag from the caller. The shipped profile has no gRPC authentication (security_level_grpc=0), so a client that can reach those ports can flag mempool transactions inBlock and bypass the limit. The HTTP listeners reject the flag. Restrict access to the gRPC ports, or enable gRPC authentication, where that matters.

A Kafka pause caused only by the held count ends at the retention of the validator transaction topic (the retention parameter of kafka_validatortxsConfig, ten minutes when absent), because past that the broker has dropped the backlog it holds back.

Block transactions kept Locked

When block assembly refuses a block transaction on the ingest queue bound (blockassembly_maxQueueItems), the validator accepts the transaction and keeps its record Locked, so an ordinary child cannot enter the template without it. teranode_validator_shed_inblock_dropped_total counts these, and a rising value is the signal to act. The lock clears when the block’s setMined runs, which it does for every block that validates, side chains included. A block that fails validation before setMined runs leaves the record Locked, and an ordinary child of it is refused as locked. The validator checks each such record five minutes after its shed and resets block assembly if any is still Locked and unmined, counted by teranode_validator_shed_inblock_recovery_resets_total. A block assembly reset, or a restart, runs the unmined reload. It reads every unmined record, including Locked ones, adds them to the template and unlocks them.

Coinbase Divergence Recovery

Block assembly keeps two pieces of state that have to agree: the chain pointer (the header it believes it is on) and the coinbase UTXOs it has created. Nothing makes those two writes atomic, so an unclean shutdown — a crash part-way through the fast-forward create loop, for instance — can leave the pointer ahead of the coinbase set. The damage is not visible immediately: it shows up a hundred blocks later, when a coinbase-maturity spend looks for a parent coinbase that was never written, cannot find it, and wedges the tip permanently.

To catch that, block assembly runs a check once during startup, after the subtree processor is running but before it starts consuming block notifications. It walks down from the persisted tip looking for canonical coinbases missing from the UTXO store. Each one it finds is repaired in place: it scopes the contiguous gap beneath that height and re-creates just those coinbases — never the transactions in those blocks, so the cost is proportional to the number of affected blocks rather than to chain size. The scan then carries on below the repair, because a repair only proves a few present coinbases underneath itself and a second hole further down would otherwise go unnoticed until the next restart.

Three settings bound that work:

  • blockassembly_coinbaseRecoveryMaxGapBlocks does double duty. It is how far below the tip the startup scan looks, and it is the largest gap recovery will repair on its own. The two are deliberately the same number: there is no value in detecting a divergence deeper than the node is willing to fix automatically. A clean boot costs one blockchain-client lookup and one UTXO store read per height in the window, issued one after another — and the first of those is a call to the blockchain service, not a local read, so the startup cost tracks the latency to that service rather than local disk. The scan ends early only when a divergence cannot be repaired, since a refusal is structural and would repeat identically at every lower height. Tuning this down to limit repair scope also shrinks detection coverage by the same amount. A second, non-configurable bound applies underneath it — see the safety floor below — so with the default settings the effective reach is the coinbase-maturity window.
  • blockassembly_coinbaseRecoveryConsecutiveGood guards against under-repair. The fast-forward create loop runs one goroutine per block, so a crash can leave a present coinbase sitting above still-missing ones. Stopping the walk-back at the first present coinbase would miss those, so it keeps going until it has seen this many present coinbases in a row.
  • blockassembly_coinbaseRecoveryMaxAttempts caps automatic retries. Retries exist for transient failures (a store or blockchain-client blip), with a short pause between them. A gap larger than the cap is structural and escalates straight away without spending retries on it.

With the shipped defaults the gap cap never fires. The walk-back stops at the maturity safety floor described below, so it can never collect more than CoinbaseMaturity (100) misses, while coinbaseRecoveryMaxGapBlocks defaults to 200. The cap only becomes a live control when it is set below the maturity — otherwise every escalation you see came from the safety floor, not from the cap. Its other role, bounding the startup scan window, stays live at any setting.

The safety floor

Recovery never looks further back than the coinbase-maturity window, no matter how the settings above are tuned. This is a correctness limit rather than a performance one, and it is worth understanding because it is what keeps the repair safe.

“No coinbase in the UTXO store” is an ambiguous observation. It is true of a coinbase that was never created — the divergence being repaired — but it is equally true of one that was created, matured, fully spent, and then deleted by the pruner. Both look identical to a lookup. Re-creating the second kind would put outputs that were already legitimately spent back into the UTXO set as unspent, which is a far worse problem than the wedge this feature exists to fix.

Coinbase maturity separates the two cases cleanly. A coinbase cannot be spent until maturity blocks have been built on top of it, and an unspent output is never marked for deletion, so it is never pruned. Above tip - CoinbaseMaturity, therefore, absence can only mean “never created”. Below it, the answer is unknowable from a lookup alone, so the walk stops rather than guessing. If a genuine divergence extends past that line, recovery escalates to an operator instead of repairing it.

The tip in that subtraction is the chain tip as the UTXO store sees it, not block assembly’s own position. The pruner marks outputs for deletion against the store’s height, and block assembly’s pointer can sit hundreds of blocks behind it during a normal catch-up. Measuring the floor from the lagging pointer would put the bottom of the window inside already-prunable territory, which is the exact mistake the floor exists to prevent, so the higher of the two heights is always used. The visible effect is that a block assembler well behind the chain scans a narrower window, and one behind by more than the maturity window scans nothing and logs that it skipped the check — correct, because at that distance nothing it could look at is provably unpruned.

Detection coverage is consequently a bounded window, not the whole chain. A hole further below the tip than the smaller of coinbaseRecoveryMaxGapBlocks and the maturity window is not found at startup; detecting that cheaply during normal operation is separate, future work.

Because the maturity window is also the ceiling on how far the walk-back can reach, a network configured with a small coinbase maturity gets little or nothing out of this feature. Below coinbaseRecoveryConsecutiveGood there are not enough probeable heights left to prove a floor, so every miss is refused rather than repaired, and at a maturity of zero — where a coinbase is spendable immediately and so nothing is ever provably unspent — the feature is a deliberate no-op. Every shipped network uses 100, which leaves ample room; only custom chain parameters can land in that territory.

When recovery cannot fix a divergence it logs a single MANUAL INTERVENTION REQUIRED line naming resetblockassembly, and increments the escalated outcome on the teranode_blockassembly_coinbase_divergence_total metric. Startup does not fail in that case — the node boots and keeps building on the diverged tip. That is deliberate: crash-looping the process helps nobody, and a running node an operator can inspect is strictly more useful. The trade-off is that the escalation log is a call to action, not a description of a node that has stopped itself.

Every detection records exactly one follow-up outcome on that metric, so detected == repaired + no_gap + escalated + aborted. A non-zero no_gap means the divergence had already closed by the time recovery scoped it. aborted means the node was shut down while a repair was still retrying — nothing is known to be wrong in that case, and it deliberately raises no alarm, so a node stopped mid-boot does not tell its operator that the UTXO state needs manual intervention.

Hardcoded Settings (Not Configurable)

SettingValueUsage
jobTTL10 minutesMining job cache TTL
coinbaseRecoveryRetryBackoff500 millisecondsPause between automatic coinbase-recovery attempts
coinbaseRecoveryProbeRetries2Probe retries the whole startup divergence scan may spend, shared across every height it visits

Configuration Dependencies

Service Startup

  • Service skipped (not added to ServiceManager) if GRPCListenAddress is empty
  • Channel buffers allocated during Init() based on configured sizes

Service Disable

  • When Disabled = true, all block assembly operations return early
  • All other settings become irrelevant when service is disabled

Channel Buffer Management

  • NewSubtreeChanBuffer and SubtreeRetryChanBuffer must accommodate concurrent processing loads
  • Buffer sizes affect pipeline performance and memory usage

Mining Solution Processing

  • SubmitMiningSolutionWaitForResponse = true: gRPC call blocks until submission completes
  • SubmitMiningSolutionWaitForResponse = false: Returns immediately for async processing
  • Significantly affects mining pool integration behavior

Reorganization Handling

  • MaxGetReorgHashes prevents excessive memory usage during large reorganizations
  • Works with MaxBlockReorgRollback, MoveBackBlockConcurrency

Dynamic Subtree Sizing

  • When UseDynamicSubtreeSize = true, subtree size adjusts based on transaction volume
  • Uses InitialMerkleItemsPerSubtree as starting size
  • Adjusts within MinimumMerkleItemsPerSubtree and MaximumMerkleItemsPerSubtree bounds

Parent Chain Validation

  • OnRestartValidateParentChain = true: Validates transaction parent chains after service restart
  • ParentValidationBatchSize: Controls batch processing size (default: 1000)
  • OnRestartRemoveInvalidParentChainTxs = true (default): Filters out transactions with invalid parent chains
  • OnRestartRemoveInvalidParentChainTxs = false: Keeps transactions despite invalid parents

Service Dependencies

DependencyInterfaceUsage
TxStoreblob.StoreTransaction data access
UTXOStoreutxostore.StoreCRITICAL - UTXO operations and validation
SubtreeStoreblob.StoreCRITICAL - Subtree storage and retrieval
BlockchainClientblockchain.ClientICRITICAL - Blockchain operations, block submission

Validation Rules

SettingValidationImpactWhen Checked
GRPCListenAddressMust not be emptyService skipped if emptyDuring daemon startup
MaxGetReorgHashesLimits reorganization processingMemory protection during reorgsDuring reorg processing
Channel BuffersMust accommodate processing loadsPipeline performance and backpressureDuring Init()

Configuration Examples

Basic Configuration

blockassembly_grpcListenAddress = ":8085"
blockassembly_disabled = false

Performance Tuning

blockassembly_subtreeProcessorConcurrentReads=500
blockassembly_newSubtreeChanBuffer=2000
blockassembly_subtreeRetryChanBuffer=2000

Mining Configuration

blockassembly_SubmitMiningSolution_waitForResponse=true
miner_wallet_private_keys=key1|key2