BSV blockchainBSV blockchain

Blockchain Service Settings

Related Topic: Blockchain Service

Configuration Settings

SettingTypeDefaultEnvironment VariableUsage
GRPCAddressstring“localhost:8087”blockchain_grpcAddressClient connection address
GRPCListenAddressstring“:8087”blockchain_grpcListenAddressgRPC server binding (optional, skips health checks if empty)
HTTPListenAddressstring“:8082”blockchain_httpListenAddressCRITICAL - HTTP server binding (fails during Start() if empty)
MaxRetriesint3blockchain_maxRetriesRetry attempts for operations
RetrySleepint1000blockchain_retrySleepRetry delay timing (milliseconds)
StoreURL*url.URL“sqlite:///blockchain”blockchain_storeCRITICAL - Database connection (fails during daemon startup if null)
FSMStateRestoreboolfalsefsm_state_restoreUNUSED - Previously triggered FSM restore via RPC service, implementation is currently disabled
FSMStateChangeDelaytime.Duration0fsm_state_change_delayTESTING ONLY - Delays FSM state transitions
StoreDBTimeoutMillisint5000blockchain_store_dbTimeoutMillisPer-operation FSM checkpoint-read and persistence timeout; non-positive uses 5000 ms
InitializeNodeInStatestring"" (IDLE for operator/docker.m)blockchain_initializeNodeInStateFresh-node FSM state: IDLE, CATCHINGBLOCKS, or RUNNING. Empty means CATCHINGBLOCKS; persisted state takes precedence and bypasses this setting’s validation; invalid values fail fresh-node startup
PostgresPool*PostgresSettings(see below)blockchain_postgres_poolPostgreSQL connection pool settings

Configured RUNNING: on a checkpointed network, use only with a pre-seeded store whose tip is at or above the highest checkpoint. A lower tip or a tip-read failure aborts startup without falling back to CATCHINGBLOCKS. Choose CATCHINGBLOCKS to synchronize a fresh node. Networks without checkpoints allow configured RUNNING directly.

PostgreSQL Connection Pool (PostgresPool)

When using PostgreSQL as the blockchain store, these settings override the global Postgres pool settings for this service only. Each is read directly (not through PostgresPool’s own struct tags, which only describe the opaque blockchain_postgres_pool field as a whole) via getPostgresPoolSettings("blockchain", ...), and all default to the zero value. The family is six numeric/duration settings plus RetryEnabled and five circuit breaker settings (blockchain_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 blockchain_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 blockchain_postgres_retryEnabled = false alone is indistinguishable from unset and does not create the pool.

SettingTypeDefaultEnvironment VariableUsage
MaxOpenConnsint0 (falls back to global if unset)blockchain_postgres_maxOpenConnsMaximum concurrent database connections
MaxIdleConnsint0 (falls back to global if unset)blockchain_postgres_maxIdleConnsMaximum idle connections in pool
ConnMaxLifetimetime.Duration0 (falls back to global if unset)blockchain_postgres_connMaxLifetimeMaximum connection reuse duration
ConnMaxIdleTimetime.Duration0 (falls back to global if unset)blockchain_postgres_connMaxIdleTimeMaximum idle time before closing
RetryEnabledboolfalse (no global fallback; see above)blockchain_postgres_retryEnabledEnable retries for transient errors
RetryMaxAttemptsint0 (falls back to global if unset)blockchain_postgres_retryMaxAttemptsMaximum retry attempts
RetryBaseDelaytime.Duration0 (falls back to global if unset)blockchain_postgres_retryBaseDelayBase delay for retry backoff

Configuration Dependencies

gRPC Server

  • GRPCListenAddress optional - when empty, gRPC server not started
  • Health checks skipped if empty
  • Service runs with HTTP API only when empty
  • GRPCAddress used for client connections

HTTP API Server

  • HTTPListenAddress required - service fails during Start() if empty
  • Provides block invalidation/revalidation endpoints

FSM State Management

  • FSMStateRestore: Currently unused. The implementation that sent a Restore event via RPC is disabled.
  • On startup, the blockchain service restores the last persisted FSM state from the database store.
  • FSMStateChangeDelay delays state transitions for test timing control.
  • Initial FSM state set via -localTestStartFromState CLI argument.

Database Configuration

  • StoreURL determines database backend
  • Service fails during daemon startup if null
  • StoreDBTimeoutMillis bounds FSM checkpoint reads and persistence writes in the blockchain service; it is not a general store query timeout.
  • Zero or negative values use the 5000 ms default, rather than disabling timeouts.
  • Checkpoint reads respect an earlier caller deadline. Admitted writes run with their own bounded context even after the caller disconnects.
  • A RUN transition can consume two independent store budgets while holding the transition lock. Notification delivery and the complete RPC are not bounded by this setting. Large values can delay other transitions after a caller exits.
  • The store helper does not retry. Automatic catchup promotion retries transient failures at most three times with cancellable backoff and warns on exhaustion. Explicit operator requests can be retried after store recovery.
  • Tune using observed store latency under load; the five-second default is not a measured production p99 guarantee.

Service Dependencies

DependencyInterfaceUsage
BlockchainStoreblockchain_store.StoreCRITICAL - Blockchain data persistence
KafkaProducerkafka.KafkaAsyncProducerICRITICAL - Block publishing to downstream services

Validation Rules

SettingValidationErrorWhen Checked
HTTPListenAddressMust not be empty“No blockchain_httpListenAddress specified”During Start()
StoreURLMust not be null“blockchain store url not found”During daemon startup
GRPCListenAddressOptionalNo error if empty, skips gRPC health checksDuring Health()

Configuration Examples

Basic Configuration

blockchain_grpcListenAddress=:8087
blockchain_httpListenAddress=:8082
blockchain_store=sqlite:///blockchain

PostgreSQL Configuration

blockchain_store=postgres://user:pass@host:5432/blockchain

Testing Configuration

fsm_state_change_delay=1s
# Set initial FSM state via CLI argument:
# -localTestStartFromState=IDLE