# UTXO Store Settings

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

These settings override the global Postgres pool settings for the UTXO store only.

**Related Topic**: [UTXO Store](https://bsvblockchain.com/docs/nodes/teranode/topics/stores/utxo/)

## Configuration Settings

| Setting | Type | Default | Environment Variable | Usage |
|---------|------|---------|---------------------|-------|
| UtxoStore | *url.URL | "" | utxostore | **CRITICAL** - UTXO store backend URL |
| BlockHeightRetention | uint32 | 288 (globalBlockHeightRetention) | utxostore_blockHeightRetention | Block height retention period |
| UnminedTxRetention | uint32 | 144 (globalBlockHeightRetention/2) | utxostore_unminedTxRetention | Unmined transaction retention |
| ParentPreservationBlocks | uint32 | 1440 (blocksInADayOnAverage*10) | utxostore_parentPreservationBlocks | Parent preservation period |
| OutpointBatcherSize | int | 100 | utxostore_outpointBatcherSize | Outpoint operation batch size |
| OutpointBatcherDurationMillis | int | 10 | utxostore_outpointBatcherDurationMillis | Outpoint batch duration |
| SpendBatcherDurationMillis | int | 100 | utxostore_spendBatcherDurationMillis | Spend batch duration |
| SpendBatcherSize | int | 100 | utxostore_spendBatcherSize | Spend operation batch size |
| SpendBatcherConcurrency | int | 32 | utxostore_spendBatcherConcurrency | SQL per-transaction input-spend cap (`SpendBatcherSize` × this); also caps quick-validation concurrent transactions (`SpendBatcherSize` × this × 2) |
| SpendWaitTimeout | time.Duration | 30s | utxostore_spendWaitTimeout | Spend operation wait timeout |
| SpendCircuitBreakerFailureCount | int | 10 | utxostore_spendCircuitBreakerFailureCount | Circuit breaker failure threshold (infrastructure-level errors only — see "Spend Circuit Breaker Trigger Set" below) |
| SpendCircuitBreakerCooldown | time.Duration | 30s | utxostore_spendCircuitBreakerCooldown | Circuit breaker cooldown period |
| SpendCircuitBreakerHalfOpenMax | int | 4 | utxostore_spendCircuitBreakerHalfOpenMax | Circuit breaker half-open max |
| StoreBatcherDurationMillis | int | 10 | utxostore_storeBatcherDurationMillis | Store batch duration (SQL and Aerospike) |
| StoreBatcherSize | int | 100 | utxostore_storeBatcherSize | Store operation batch size |
| UtxoBatchSize | int | 128 | utxostore_utxoBatchSize | UTXO operation batch size |
| IncrementBatcherSize | int | 256 | utxostore_incrementBatcherSize | Increment operation batch size |
| IncrementBatcherDurationMillis | int | 10 | utxostore_incrementBatcherDurationMillis | Increment batch duration |
| SetDAHBatcherSize | int | 256 | utxostore_setDAHBatcherSize | DAH operation batch size |
| SetDAHBatcherDurationMillis | int | 10 | utxostore_setDAHBatcherDurationMillis | DAH batch duration |
| LockedBatcherSize | int | 1024 | utxostore_lockedBatcherSize | Locked operation batch size |
| LockedBatcherDurationMillis | int | 5 | utxostore_lockedBatcherDurationMillis | Locked batch duration |
| LongestChainBatcherSize | int | 1024 | utxostore_longestChainBatcherSize | Longest chain batch size |
| LongestChainBatcherDurationMillis | int | 5 | utxostore_longestChainBatcherDurationMillis | Longest chain batch duration |
| GetBatcherSize | int | 1 | utxostore_getBatcherSize | Get operation batch size |
| GetBatcherDurationMillis | int | 10 | utxostore_getBatcherDurationMillis | Get batch duration |
| BatcherMaxConcurrent | int | 64 | utxostore_batcherMaxConcurrent | Max concurrent in-flight batch callbacks per batcher (shared cap; 0 = unlimited) |
| OutpointBatcherMaxConcurrent | int | 0 | utxostore_outpointBatcherMaxConcurrent | Per-batcher outpoint/decorate concurrency override, the #1187 read fan-out throttle (0 = inherit utxostore_batcherMaxConcurrent) |
| DBTimeout | time.Duration | 5s | utxostore_dbTimeoutDuration | **CRITICAL** - Database operation timeout |
| UseExternalTxCache | bool | true | utxostore_useExternalTxCache | External transaction cache usage |
| ExternalTxCacheMaxItems | int | 1024 | utxostore_externalTxCacheMaxItems | Max entries in each external transaction cache (0 = unbounded) |
| ExternalizeAllTransactions | bool | false | utxostore_externalizeAllTransactions | Transaction externalization control |
| ExternalStoreConcurrency | int | 16 | utxostore_externalStoreConcurrency | Maximum concurrent external storage operations |
| VerboseDebug | bool | false | utxostore_verbose_debug | Verbose debug logging |
| MaxMinedRoutines | int | 128 | utxostore_maxMinedRoutines | Max mined transaction routines |
| MaxMinedBatchSize | int | 1024 | utxostore_maxMinedBatchSize | Max mined transaction batch size |
| BlockHeightRetentionAdjustment | int32 | 0 | utxostore_blockHeightRetentionAdjustment | **CRITICAL** - Retention adjustment |
| DisableDAHCleaner | bool | false | utxostore_disableDAHCleaner | **CRITICAL** - DAH cleaner process control |
| SkipTxBodyBelowCheckpoint | bool | false | utxostore_skipTxBodyBelowCheckpoint | utxoset only - skip the tx_body write at or below the hardcoded checkpoint |
| SpendJournalRetentionBlocks | uint32 | 288 | utxostore_spendJournalRetentionBlocks | utxoset only - blocks of spends the undo journal keeps for reorgs and the replay of an interrupted block; 0 is the default, values are held to 100 through 1440 |
| RetainWindowsIndefinitely | bool | false | utxostore_retainWindowsIndefinitely | utxoset only - keep every tx_mined and undo partition instead of dropping them past retention; the stamp still runs, and the disk grows without bound |
| NettedBelowWorkers | int | 16 | utxostore_nettedBelowWorkers | utxoset only - chunks of a list that the below-checkpoint netted write runs at once, each one database transaction; at most half of the pool's connections are used, whatever the value |
| ConflictingChildrenMaxNodes | int | 100000 | utxostore_conflictingChildrenMaxNodes | Fail-closed node budget per root of a conflicting-descendant walk (&lt;=0 = unlimited). Subtree validation walks a block's conflicting transactions as one batch from N roots (the transactions and their counter-spenders) and allows N × this budget: the old aggregate bound of N separate walks. Worst case, the visited set reaches N × this budget entries, and a single runaway cone fails after N × this budget reads rather than this budget. A walk that stops on the budget still rejects the block with `TX_INVALID` if it already reached a counter-conflicting transaction (a conflicting transaction, a counter-spender or a counter-spender's descendant) mined on the candidate chain; the conflicting transactions' own descendants are only checked for frozen outputs. Otherwise the block fails with `UTXO_WALK_LIMIT_EXCEEDED` and is retried |

### PostgreSQL Connection Pool (PostgresPool)

These settings override the [global Postgres pool settings](https://bsvblockchain.com/docs/nodes/teranode/references/settings/global-settings/#postgresql-connection-pool)
for the UTXO store only. Each is read directly (not through `PostgresPool`'s own struct tags, which only
describe the opaque `utxostore_postgres_pool` field as a whole) via `getPostgresPoolSettings("utxostore",
...)`, and all default to the zero value. The family is six numeric/duration settings plus `RetryEnabled` and five circuit breaker settings
(`utxostore_postgres_circuitBreakerEnabled`, `..._circuitBreakerFailureThreshold`, `..._circuitBreakerHalfOpenMax`,
`..._circuitBreakerCooldown`, `..._circuitBreakerFailureWindow`; documented in the
[global table](https://bsvblockchain.com/docs/nodes/teranode/references/settings/global-settings/#postgresql-connection-pool)). `PostgresPool` stays `nil` only when
none of the twelve is configured: any non-zero numeric/duration value, `RetryEnabled=true`, or an
explicit `CircuitBreakerEnabled` (`true` or `false`) creates it, so a lone `utxostore_postgres_retryEnabled = true`
does take effect. Once the pool exists, zero numeric/duration values and an unset `CircuitBreakerEnabled`
fall back to the global values; an explicit `CircuitBreakerEnabled=false` is preserved. `RetryEnabled` has
no global fallback: the service's value (`false` included) replaces the global one outright. Note that
`utxostore_postgres_retryEnabled = false` alone is indistinguishable from unset and does not create the pool.

| Setting | Type | Default | Environment Variable | Usage |
|---------|------|---------|---------------------|-------|
| MaxOpenConns | int | 0 (falls back to global if unset) | utxostore_postgres_maxOpenConns | Maximum concurrent database connections |
| MaxIdleConns | int | 0 (falls back to global if unset) | utxostore_postgres_maxIdleConns | Maximum idle connections in pool |
| ConnMaxLifetime | time.Duration | 0 (falls back to global if unset) | utxostore_postgres_connMaxLifetime | Maximum connection reuse duration |
| ConnMaxIdleTime | time.Duration | 0 (falls back to global if unset) | utxostore_postgres_connMaxIdleTime | Maximum idle time before closing |
| RetryEnabled | bool | false (no global fallback; see above) | utxostore_postgres_retryEnabled | Enable retries for transient errors |
| RetryMaxAttempts | int | 0 (falls back to global if unset) | utxostore_postgres_retryMaxAttempts | Maximum retry attempts |
| RetryBaseDelay | time.Duration | 0 (falls back to global if unset) | utxostore_postgres_retryBaseDelay | Base delay for retry backoff |

## URL Query Parameters

| Parameter | Type | Default | Usage | Impact |
|-----------|------|---------|-------|--------|
| logging | bool | false | `storeURL.Query().Get("logging") == "true"` | **CRITICAL** - Enables operation logging wrapper |

## Spend Circuit Breaker Trigger Set

The spend circuit breaker counts only **infrastructure-level** aerospike errors toward `SpendCircuitBreakerFailureCount`. Data-state errors (e.g. `KEY_NOT_FOUND_ERROR` for a missing parent during catch-up sync, `FILTERED_OUT` for a Lua business-rule rejection) are handled by per-record error paths in the calling code — missing parents flow into subtree validation's sequential revalidation pass, and Lua business-rule rejections surface to the caller — and never increment the failure counter.

Counted as infrastructure failure:

- `TIMEOUT`, `NETWORK_ERROR`, `NO_RESPONSE`, `MAX_RETRIES_EXCEEDED`, `MAX_ERROR_RATE`
- `NO_AVAILABLE_CONNECTIONS_TO_NODE`, `SERVER_NOT_AVAILABLE`, `INVALID_NODE_ERROR`, `PARTITION_UNAVAILABLE`
- `SERVER_MEM_ERROR`, `SERVER_ERROR`, `DEVICE_OVERLOAD`, `BATCH_FAILED`, `GRPC_ERROR`
- stdlib `context.DeadlineExceeded`; `net.Error` with `Timeout() == true`

Anything else — including unknown / non-aerospike errors — is treated as non-infrastructure. The bias is intentional: a false trip during IBD stalls sync (issue #953), while a missed infrastructure signal is recoverable by the higher-level `SpendWaitTimeout` and health checks.

## Configuration Dependencies

### Block Height Retention

- Effective retention = `GlobalBlockHeightRetention + BlockHeightRetentionAdjustment`
- Used in `sql/sql.go` for DAH calculations and cleanup operations
- Bounds checking prevents negative results

### Database Operations

- `DBTimeout` controls all SQL operation timeouts in `sql/sql.go`
- PostgreSQL connection settings control connection pooling
- Used across Create, Get, Spend, Delete, and batch operations

### Batch Processing

- Size and duration settings work together for different operation types
- Controls memory usage and performance for bulk operations
- Separate batchers for outpoint, spend, store, increment, DAH, and locked operations

### DAH Functionality

- When `DisableDAHCleaner = false`, uses retention settings for cleanup
- DAH calculations use block height retention values
- Pruning operations respect retention adjustment settings

### Debug Logging

- URL `logging` parameter enables operation wrapper in `factory/utxo.go`
- `VerboseDebug` controls detailed logging output
- Logs all store operations with parameters and duration

## Backend Support

| Backend | Scheme | Parameters Supported |
|---------|--------|---------------------|
| aerospike | aerospike:// | All settings, logging parameter |
| postgres | postgres:// | All settings, logging parameter |
| sqlite | sqlite:// | All settings, logging parameter |
| sqlitememory | sqlitememory:// | All settings, logging parameter |
| memory | memory:// | All settings, logging parameter |
| null | null:// | All settings, logging parameter |

## Validation Rules

| Setting | Validation | Impact | When Checked |
|---------|------------|--------|-------------|
| UtxoStore | Must be valid URL | Store initialization | During store factory initialization |
| DBTimeout | Used for context timeout | Operation reliability | During SQL operations |
| BlockHeightRetentionAdjustment | Bounds checking applied | Retention calculation | During DAH calculations |
| logging | Boolean string check | Logging wrapper creation | During store initialization |

## Configuration Examples

### PostgreSQL Store

```text
utxostore = "postgres://user:pass@host:5432/db?logging=true"
utxostore_dbTimeoutDuration = "60s"
```

### Aerospike Store

```text
utxostore = "aerospike://host:3000/namespace"
utxostore_spendBatcherSize = 200
```

### SQLite Store

```text
utxostore = "sqlite:///data/utxo.db?logging=true"
utxostore_blockHeightRetentionAdjustment = 100
```