UTXO Store Settings
Related Topic: UTXO Store
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 (<=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
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). 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_RATENO_AVAILABLE_CONNECTIONS_TO_NODE,SERVER_NOT_AVAILABLE,INVALID_NODE_ERROR,PARTITION_UNAVAILABLESERVER_MEM_ERROR,SERVER_ERROR,DEVICE_OVERLOAD,BATCH_FAILED,GRPC_ERROR- stdlib
context.DeadlineExceeded;net.ErrorwithTimeout() == 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.gofor DAH calculations and cleanup operations - Bounds checking prevents negative results
Database Operations
DBTimeoutcontrols all SQL operation timeouts insql/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
loggingparameter enables operation wrapper infactory/utxo.go VerboseDebugcontrols 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
utxostore = "postgres://user:pass@host:5432/db?logging=true"
utxostore_dbTimeoutDuration = "60s"Aerospike Store
utxostore = "aerospike://host:3000/namespace"
utxostore_spendBatcherSize = 200SQLite Store
utxostore = "sqlite:///data/utxo.db?logging=true"
utxostore_blockHeightRetentionAdjustment = 100