# Blockchain Service Settings

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

Configured RUNNING: on a checkpointed network, use only with a pre-seeded store whose tip is at or above the highest checkpoint.

**Related Topic**: [Blockchain Service](https://bsvblockchain.com/docs/nodes/teranode/topics/services/blockchain/)

## Configuration Settings

| Setting | Type | Default | Environment Variable | Usage |
|---------|------|---------|---------------------|-------|
| GRPCAddress | string | "localhost:8087" | blockchain_grpcAddress | Client connection address |
| GRPCListenAddress | string | ":8087" | blockchain_grpcListenAddress | gRPC server binding (optional, skips health checks if empty) |
| HTTPListenAddress | string | ":8082" | blockchain_httpListenAddress | **CRITICAL** - HTTP server binding (fails during Start() if empty) |
| MaxRetries | int | 3 | blockchain_maxRetries | Retry attempts for operations |
| RetrySleep | int | 1000 | blockchain_retrySleep | Retry delay timing (milliseconds) |
| StoreURL | *url.URL | "sqlite:///blockchain" | blockchain_store | **CRITICAL** - Database connection (fails during daemon startup if null) |
| FSMStateRestore | bool | false | fsm_state_restore | **UNUSED** - Previously triggered FSM restore via RPC service, implementation is currently disabled |
| FSMStateChangeDelay | time.Duration | 0 | fsm_state_change_delay | **TESTING ONLY** - Delays FSM state transitions |
| StoreDBTimeoutMillis | int | 5000 | blockchain_store_dbTimeoutMillis | Per-operation FSM checkpoint-read and persistence timeout; non-positive uses 5000 ms |
| InitializeNodeInState | string | "" (`IDLE` for `operator`/`docker.m`) | blockchain_initializeNodeInState | Fresh-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_pool | PostgreSQL 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](https://bsvblockchain.com/docs/nodes/teranode/references/settings/global-settings/#postgresql-connection-pool) 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](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 `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.

| Setting | Type | Default | Environment Variable | Usage |
|---------|------|---------|---------------------|-------|
| MaxOpenConns | int | 0 (falls back to global if unset) | blockchain_postgres_maxOpenConns | Maximum concurrent database connections |
| MaxIdleConns | int | 0 (falls back to global if unset) | blockchain_postgres_maxIdleConns | Maximum idle connections in pool |
| ConnMaxLifetime | time.Duration | 0 (falls back to global if unset) | blockchain_postgres_connMaxLifetime | Maximum connection reuse duration |
| ConnMaxIdleTime | time.Duration | 0 (falls back to global if unset) | blockchain_postgres_connMaxIdleTime | Maximum idle time before closing |
| RetryEnabled | bool | false (no global fallback; see above) | blockchain_postgres_retryEnabled | Enable retries for transient errors |
| RetryMaxAttempts | int | 0 (falls back to global if unset) | blockchain_postgres_retryMaxAttempts | Maximum retry attempts |
| RetryBaseDelay | time.Duration | 0 (falls back to global if unset) | blockchain_postgres_retryBaseDelay | Base 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

| Dependency | Interface | Usage |
|------------|-----------|-------|
| BlockchainStore | blockchain_store.Store | **CRITICAL** - Blockchain data persistence |
| KafkaProducer | kafka.KafkaAsyncProducerI | **CRITICAL** - Block publishing to downstream services |

## Validation Rules

| Setting | Validation | Error | When Checked |
|---------|------------|-------|-------------|
| HTTPListenAddress | Must not be empty | "No blockchain_httpListenAddress specified" | During Start() |
| StoreURL | Must not be null | "blockchain store url not found" | During daemon startup |
| GRPCListenAddress | Optional | No error if empty, skips gRPC health checks | During Health() |

## Configuration Examples

### Basic Configuration

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

### PostgreSQL Configuration

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

### Testing Configuration

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