BSV blockchainBSV blockchain

UTXO Store Settings

Related Topic: UTXO Store

Configuration Settings

SettingTypeDefaultEnvironment VariableUsage
UtxoStore*url.URL""utxostoreCRITICAL - UTXO store backend URL
BlockHeightRetentionuint32288 (globalBlockHeightRetention)utxostore_blockHeightRetentionBlock height retention period
UnminedTxRetentionuint32144 (globalBlockHeightRetention/2)utxostore_unminedTxRetentionUnmined transaction retention
ParentPreservationBlocksuint321440 (blocksInADayOnAverage*10)utxostore_parentPreservationBlocksParent preservation period
OutpointBatcherSizeint100utxostore_outpointBatcherSizeOutpoint operation batch size
OutpointBatcherDurationMillisint10utxostore_outpointBatcherDurationMillisOutpoint batch duration
SpendBatcherDurationMillisint100utxostore_spendBatcherDurationMillisSpend batch duration
SpendBatcherSizeint100utxostore_spendBatcherSizeSpend operation batch size
SpendBatcherConcurrencyint32utxostore_spendBatcherConcurrencySQL per-transaction input-spend cap (SpendBatcherSize × this); also caps quick-validation concurrent transactions (SpendBatcherSize × this × 2)
SpendWaitTimeouttime.Duration30sutxostore_spendWaitTimeoutSpend operation wait timeout
SpendCircuitBreakerFailureCountint10utxostore_spendCircuitBreakerFailureCountCircuit breaker failure threshold (infrastructure-level errors only — see “Spend Circuit Breaker Trigger Set” below)
SpendCircuitBreakerCooldowntime.Duration30sutxostore_spendCircuitBreakerCooldownCircuit breaker cooldown period
SpendCircuitBreakerHalfOpenMaxint4utxostore_spendCircuitBreakerHalfOpenMaxCircuit breaker half-open max
StoreBatcherDurationMillisint10utxostore_storeBatcherDurationMillisStore batch duration (SQL and Aerospike)
StoreBatcherSizeint100utxostore_storeBatcherSizeStore operation batch size
UtxoBatchSizeint128utxostore_utxoBatchSizeUTXO operation batch size
IncrementBatcherSizeint256utxostore_incrementBatcherSizeIncrement operation batch size
IncrementBatcherDurationMillisint10utxostore_incrementBatcherDurationMillisIncrement batch duration
SetDAHBatcherSizeint256utxostore_setDAHBatcherSizeDAH operation batch size
SetDAHBatcherDurationMillisint10utxostore_setDAHBatcherDurationMillisDAH batch duration
LockedBatcherSizeint1024utxostore_lockedBatcherSizeLocked operation batch size
LockedBatcherDurationMillisint5utxostore_lockedBatcherDurationMillisLocked batch duration
LongestChainBatcherSizeint1024utxostore_longestChainBatcherSizeLongest chain batch size
LongestChainBatcherDurationMillisint5utxostore_longestChainBatcherDurationMillisLongest chain batch duration
GetBatcherSizeint1utxostore_getBatcherSizeGet operation batch size
GetBatcherDurationMillisint10utxostore_getBatcherDurationMillisGet batch duration
BatcherMaxConcurrentint64utxostore_batcherMaxConcurrentMax concurrent in-flight batch callbacks per batcher (shared cap; 0 = unlimited)
OutpointBatcherMaxConcurrentint0utxostore_outpointBatcherMaxConcurrentPer-batcher outpoint/decorate concurrency override, the #1187 read fan-out throttle (0 = inherit utxostore_batcherMaxConcurrent)
DBTimeouttime.Duration5sutxostore_dbTimeoutDurationCRITICAL - Database operation timeout
UseExternalTxCachebooltrueutxostore_useExternalTxCacheExternal transaction cache usage
ExternalTxCacheMaxItemsint1024utxostore_externalTxCacheMaxItemsMax entries in each external transaction cache (0 = unbounded)
ExternalizeAllTransactionsboolfalseutxostore_externalizeAllTransactionsTransaction externalization control
ExternalStoreConcurrencyint16utxostore_externalStoreConcurrencyMaximum concurrent external storage operations
VerboseDebugboolfalseutxostore_verbose_debugVerbose debug logging
MaxMinedRoutinesint128utxostore_maxMinedRoutinesMax mined transaction routines
MaxMinedBatchSizeint1024utxostore_maxMinedBatchSizeMax mined transaction batch size
BlockHeightRetentionAdjustmentint320utxostore_blockHeightRetentionAdjustmentCRITICAL - Retention adjustment
DisableDAHCleanerboolfalseutxostore_disableDAHCleanerCRITICAL - DAH cleaner process control
SkipTxBodyBelowCheckpointboolfalseutxostore_skipTxBodyBelowCheckpointutxoset only - skip the tx_body write at or below the hardcoded checkpoint
SpendJournalRetentionBlocksuint32288utxostore_spendJournalRetentionBlocksutxoset 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
RetainWindowsIndefinitelyboolfalseutxostore_retainWindowsIndefinitelyutxoset only - keep every tx_mined and undo partition instead of dropping them past retention; the stamp still runs, and the disk grows without bound
NettedBelowWorkersint16utxostore_nettedBelowWorkersutxoset 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
ConflictingChildrenMaxNodesint100000utxostore_conflictingChildrenMaxNodesFail-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.

SettingTypeDefaultEnvironment VariableUsage
MaxOpenConnsint0 (falls back to global if unset)utxostore_postgres_maxOpenConnsMaximum concurrent database connections
MaxIdleConnsint0 (falls back to global if unset)utxostore_postgres_maxIdleConnsMaximum idle connections in pool
ConnMaxLifetimetime.Duration0 (falls back to global if unset)utxostore_postgres_connMaxLifetimeMaximum connection reuse duration
ConnMaxIdleTimetime.Duration0 (falls back to global if unset)utxostore_postgres_connMaxIdleTimeMaximum idle time before closing
RetryEnabledboolfalse (no global fallback; see above)utxostore_postgres_retryEnabledEnable retries for transient errors
RetryMaxAttemptsint0 (falls back to global if unset)utxostore_postgres_retryMaxAttemptsMaximum retry attempts
RetryBaseDelaytime.Duration0 (falls back to global if unset)utxostore_postgres_retryBaseDelayBase delay for retry backoff

URL Query Parameters

ParameterTypeDefaultUsageImpact
loggingboolfalsestoreURL.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

BackendSchemeParameters Supported
aerospikeaerospike://All settings, logging parameter
postgrespostgres://All settings, logging parameter
sqlitesqlite://All settings, logging parameter
sqlitememorysqlitememory://All settings, logging parameter
memorymemory://All settings, logging parameter
nullnull://All settings, logging parameter

Validation Rules

SettingValidationImpactWhen Checked
UtxoStoreMust be valid URLStore initializationDuring store factory initialization
DBTimeoutUsed for context timeoutOperation reliabilityDuring SQL operations
BlockHeightRetentionAdjustmentBounds checking appliedRetention calculationDuring DAH calculations
loggingBoolean string checkLogging wrapper creationDuring 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 = 200

SQLite Store

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