# Block Assembly Service Settings

> For the complete documentation index, see [llms.txt](https://bsvblockchain.com/docs/llms.txt).

blockassemblymaxTransactionsInMemory caps the transactions block assembly holds in RAM, counted as those already placed in subtrees plus those queued for ingest.

**Related Topic**: [Block Assembly Service](https://bsvblockchain.com/docs/nodes/teranode/topics/services/block-assembly/)

## 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_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)

| 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 `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

| 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

```text
blockassembly_grpcListenAddress = ":8085"
blockassembly_disabled = false
```

### Performance Tuning

```bash
blockassembly_subtreeProcessorConcurrentReads=500
blockassembly_newSubtreeChanBuffer=2000
blockassembly_subtreeRetryChanBuffer=2000
```

### Mining Configuration

```bash
blockassembly_SubmitMiningSolution_waitForResponse=true
miner_wallet_private_keys=key1|key2
```