Block Assembly Service Settings
Related Topic: Block Assembly Service
Configuration Settings
| Setting | Type | Default | Environment Variable | Usage |
|---|---|---|---|---|
| Disabled | bool | false | blockassembly_disabled | Service-level kill switch, all operations return early |
| GenerateTipWaitTimeout | time.Duration | 90s | blockassembly_generateTipWaitTimeout | Bounds the generate readiness wait; effective bound is min(this, caller deadline) |
| GRPCAddress | string | “localhost:8085” | blockassembly_grpcAddress | Client connection address |
| GRPCListenAddress | string | “:8085” | blockassembly_grpcListenAddress | CRITICAL - gRPC server binding (service skipped if empty) |
| GRPCMaxRetries | int | 3 | blockassembly_grpcMaxRetries | gRPC client retry attempts |
| GRPCRetryBackoff | time.Duration | 2s | blockassembly_grpcRetryBackoff | Retry delay timing |
| LivenessStallTimeout | time.Duration | 0s | blockassembly_livenessStallTimeout | Liveness reports 503 if the main select stops being serviced for this long; 0 = off |
| LocalDAHCache | string | "" | blockassembly_localDAHCache | UNUSED - Reserved for future DAH caching |
| MaxBlockReorgRollback | int | 100 | blockassembly_maxBlockReorgRollback | UNUSED - Defined but not referenced in code |
| MoveBackBlockConcurrency | int | 375 | blockassembly_moveBackBlockConcurrency | Concurrency limit for reorg processing (SubtreeProcessor) |
| ProcessRemainderTxHashesConcurrency | int | 375 | blockassembly_processRemainderTxHashesConcurrency | Concurrency limit for remainder tx hash processing |
| ReconcileInterval | time.Duration | 30s | blockassembly_reconcileInterval | Idle 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 |
| SendBatchSize | int | 100 | blockassembly_sendBatchSize | Client batch size for sending transactions |
| SendBatchTimeout | int | 2 | blockassembly_sendBatchTimeout | Client batch timeout in seconds |
| SubtreeProcessorBatcherSize | int | 1000 | blockassembly_subtreeProcessorBatcherSize | Subtree processing batch size |
| SubtreeProcessorConcurrentReads | int | 375 | blockassembly_subtreeProcessorConcurrentReads | CRITICAL - Subtree read parallelism |
| NewSubtreeChanBuffer | int | 1000 | blockassembly_newSubtreeChanBuffer | CRITICAL - New subtree channel buffer |
| SubtreeRetryChanBuffer | int | 1000 | blockassembly_subtreeRetryChanBuffer | CRITICAL - Retry channel buffer |
| SubmitMiningSolutionWaitForResponse | bool | true | blockassembly_SubmitMiningSolution_waitForResponse | CRITICAL - Sync (true) vs async (false) mining solution processing |
| InitialMerkleItemsPerSubtree | int | 1048576 | initial_merkle_items_per_subtree | Initial subtree size |
| MinimumMerkleItemsPerSubtree | int | 1024 | minimum_merkle_items_per_subtree | Minimum subtree size |
| MaximumMerkleItemsPerSubtree | int | 1048576 | maximum_merkle_items_per_subtree | Maximum subtree size |
| DoubleSpendWindow | time.Duration | 0 | double_spend_window_millis | Double-spend detection window; 0 disables it |
| MaxGetReorgHashes | int | 10000 | blockassembly_maxGetReorgHashes | CRITICAL - Reorganization hash limit |
| MinerWalletPrivateKeys | []string | [] | miner_wallet_private_keys | Mining wallet keys |
| EmergencyDifficultyDelay | time.Duration | 0s | blockassembly_emergencyDifficultyDelay | Extra wait before a minimum-difficulty candidate; staggers miners (testnets only) |
| DifficultyCache | bool | true | blockassembly_difficultyCache | Enables difficulty calculation caching (Blockchain service) |
| UseDynamicSubtreeSize | bool | false | blockassembly_useDynamicSubtreeSize | Dynamic subtree sizing |
| BlockchainSubscriptionTimeout | time.Duration | 5m | blockassembly_blockchainSubscriptionTimeout | Blockchain event subscription timeout |
| OnRestartValidateParentChain | bool | true | blockassembly_onRestartValidateParentChain | Enables parent chain validation on restart |
| ParentValidationBatchSize | int | 1000 | blockassembly_parentValidationBatchSize | Parent validation batch size |
| OnRestartRemoveInvalidParentChainTxs | bool | true | blockassembly_onRestartRemoveInvalidParentChainTxs | Filters transactions with invalid parent chains |
| SubtreeStorageWorkers | int | 4 | blockassembly_subtreeStorageWorkers | Workers for subtree storage operations |
| SubtreeAnnouncementInterval | time.Duration | 10s | blockassembly_subtreeAnnouncementInterval | Subtree announcement frequency |
| UseColumnarBatch | bool | false | blockassembly_useColumnarBatch | Use columnar batch format for data layout |
| UnminedTxDiskSortPaths | []string | [] | blockassembly_unminedTxDiskSortPath | Pipe-separated directories for disk-sorted unmined reload runs (OS temp dir if empty) |
| UnminedTxDiskSortEnabled | bool | false | blockassembly_unminedTxDiskSortEnabled | Enable disk-based sorting for large mempools |
| UnminedLoadingBatchSize | int | 10485760 | blockassembly_unminedLoadingBatchSize | Batch size for loading unmined transactions |
| UnminedTxSortBufferRecords | int | 33554432 | blockassembly_unminedTxSortBufferRecords | Records buffered before the disk-sorted reload spills a sorted run |
| ParallelSetIfNotExistsThreshold | int | 10000 | blockassembly_parallelSetIfNotExistsThreshold | Threshold for parallelizing conditional writes |
| StoreTxInpointsForSubtreeMeta | bool | true | blockassembly_storeTxInpointsForSubtreeMeta | Store transaction input points in subtree metadata (required for checkblocktemplate) |
| IdleSleepDuration | time.Duration | 10ms | blockassembly_idle_sleep_duration | Sleep duration when subtree processor queue is empty |
| MaxTransactionsInMemory | uint64 | 0 | blockassembly_maxTransactionsInMemory | Refuse ingest while this many transactions are held in memory (subtrees plus queue); block transactions are not refused; 0 = off |
| CoinbaseRecoveryMaxGapBlocks | int | 200 | blockassembly_coinbaseRecoveryMaxGapBlocks | Startup scan window below the tip, and the largest coinbase gap auto-repair will fix |
| CoinbaseRecoveryConsecutiveGood | int | 6 | blockassembly_coinbaseRecoveryConsecutiveGood | Consecutive present coinbases proving the gap floor during walk-back |
| CoinbaseRecoveryMaxAttempts | int | 3 | blockassembly_coinbaseRecoveryMaxAttempts | Automatic 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):
| Caller | Outcome |
|---|---|
| Synchronous submitter (gRPC, HTTP) | Told to retry; the validator undoes the work it did for the transaction |
| Kafka ingest | Dropped 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_coinbaseRecoveryMaxGapBlocksdoes 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_coinbaseRecoveryConsecutiveGoodguards 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_coinbaseRecoveryMaxAttemptscaps 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)
| Setting | Value | Usage |
|---|---|---|
| jobTTL | 10 minutes | Mining job cache TTL |
| coinbaseRecoveryRetryBackoff | 500 milliseconds | Pause between automatic coinbase-recovery attempts |
| coinbaseRecoveryProbeRetries | 2 | Probe 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
GRPCListenAddressis 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
NewSubtreeChanBufferandSubtreeRetryChanBuffermust accommodate concurrent processing loads- Buffer sizes affect pipeline performance and memory usage
Mining Solution Processing
SubmitMiningSolutionWaitForResponse = true: gRPC call blocks until submission completesSubmitMiningSolutionWaitForResponse = false: Returns immediately for async processing- Significantly affects mining pool integration behavior
Reorganization Handling
MaxGetReorgHashesprevents excessive memory usage during large reorganizations- Works with
MaxBlockReorgRollback,MoveBackBlockConcurrency
Dynamic Subtree Sizing
- When
UseDynamicSubtreeSize = true, subtree size adjusts based on transaction volume - Uses
InitialMerkleItemsPerSubtreeas starting size - Adjusts within
MinimumMerkleItemsPerSubtreeandMaximumMerkleItemsPerSubtreebounds
Parent Chain Validation
OnRestartValidateParentChain = true: Validates transaction parent chains after service restartParentValidationBatchSize: Controls batch processing size (default: 1000)OnRestartRemoveInvalidParentChainTxs = true(default): Filters out transactions with invalid parent chainsOnRestartRemoveInvalidParentChainTxs = false: Keeps transactions despite invalid parents
Service Dependencies
| Dependency | Interface | Usage |
|---|---|---|
| TxStore | blob.Store | Transaction data access |
| UTXOStore | utxostore.Store | CRITICAL - UTXO operations and validation |
| SubtreeStore | blob.Store | CRITICAL - Subtree storage and retrieval |
| BlockchainClient | blockchain.ClientI | CRITICAL - Blockchain operations, block submission |
Validation Rules
| Setting | Validation | Impact | When Checked |
|---|---|---|---|
| GRPCListenAddress | Must not be empty | Service skipped if empty | During daemon startup |
| MaxGetReorgHashes | Limits reorganization processing | Memory protection during reorgs | During reorg processing |
| Channel Buffers | Must accommodate processing loads | Pipeline performance and backpressure | During Init() |
Configuration Examples
Basic Configuration
blockassembly_grpcListenAddress = ":8085"
blockassembly_disabled = falsePerformance Tuning
blockassembly_subtreeProcessorConcurrentReads=500
blockassembly_newSubtreeChanBuffer=2000
blockassembly_subtreeRetryChanBuffer=2000Mining Configuration
blockassembly_SubmitMiningSolution_waitForResponse=true
miner_wallet_private_keys=key1|key2