BSV blockchainBSV blockchain

Block Persister Service Settings

Related Topic: Block Persister Service

Configuration Settings

Settings are organized under the BlockPersister struct in settings.Settings.

SettingTypeDefaultEnvironment VariableUsage
Store*url.URL“file://./data/blockstore”blockpersister_storeCRITICAL - Block data storage location
HTTPListenAddressstring“127.0.0.1:8083”blockpersister_httpListenAddressHTTP server for blob store access
HTTPAuthTokenstring""blockpersister_httpAuthTokenCRITICAL - bearer token required for blob HTTP writes; unset means read-only
Concurrencyint8blockpersister_concurrencyCRITICAL - Parallel subtree processing, reduced by half in all-in-one mode
SkipUTXODeleteboolfalseblockpersister_skipUTXODeleteSkip UTXO deletion processing
PersistSleeptime.Duration10sblockpersister_persistSleepSleep duration when no blocks available or after errors
ProcessUTXOFilesbooltrueblockpersister_processUTXOFilesEnable UTXO additions/deletions file generation
SettingTypeDefaultEnvironment VariableUsage
ProcessTxMetaUsingStoreBatchSizeint1024blockvalidation_processTxMetaUsingStore_BatchSizeSHARED - Transaction metadata batch size (shared with Block Validation service)
BlockStore*url.URL“file://./data/blockstore”blockstoreRequired when HTTP server enabled

Configuration Dependencies

HTTP Server

  • When HTTPListenAddress is not empty, HTTP server starts
  • Requires valid Block.BlockStore URL or returns configuration error
  • The blob API it exposes requires Authorization: Bearer <HTTPAuthToken> on POST, PATCH and DELETE. With HTTPAuthToken unset the API serves GET and HEAD only and refuses every mutating request with 401
  • The endpoint is plain HTTP with no TLS, so the token crosses the wire in the clear. It binds to loopback by default for that reason; publish it only on a trusted segment
  • Clients configure the same value with blob_httpAuthToken, never in the store URL — store URLs are logged verbatim

Concurrency Management

  • Concurrency reduced by half when IsAllInOneMode is true
  • Minimum concurrency of 1 enforced

Block Processing Strategy

  • PersistSleep controls polling frequency when idle and after errors
  • Database persisted_at column tracks which blocks have been persisted

Transaction Processing

  • Transaction metadata is always fetched in batches, sized by ProcessTxMetaUsingStoreBatchSize
  • Note: ProcessTxMetaUsingStoreBatchSize uses the blockvalidation_ prefix (not blockpersister_) as it’s a shared setting with the Block Validation service. Both services use the same batch size for consistent transaction metadata processing.

UTXO File Processing

  • When ProcessUTXOFiles is true (default), generates .utxo-additions and .utxo-deletions files for each block
  • These files are used by the UTXO Persister service to maintain UTXO sets
  • Set to false to disable UTXO file generation for performance in scenarios where UTXO sets are not needed

Service Dependencies

DependencyInterfaceUsage
BlockStoreblob.StoreCRITICAL - Block data storage
SubtreeStoreblob.StoreCRITICAL - Subtree data storage
UTXOStoreutxo.StoreCRITICAL - UTXO operations and transaction metadata
BlockchainClientblockchain.ClientICRITICAL - Block retrieval and operations

Validation Rules

SettingValidationError
Block.BlockStoreRequired when HTTP server enabled“blockstore setting error”
StoreMust be valid URL formatStore creation failure
HTTPAuthTokenRequired for any blob write over HTTP; unset leaves the API read-onlyHTTP 401 Unauthorized

Configuration Examples

Basic Configuration

blockpersister_store=file://./data/blockstore
blockpersister_persistSleep=10s

High Performance Configuration

blockpersister_concurrency=16
blockvalidation_processTxMetaUsingStore_BatchSize=2048

HTTP Server Configuration

blockpersister_httpListenAddress=127.0.0.1:8083
blockstore=file://./data/blockstore

# Required for writes. Set both in the environment and configure the same value on the
# client side. Values in settings files are masked in the startup dump but held in clear
# in the file; never put them in the committed settings.conf.
blockpersister_httpAuthToken=<shared-secret>
blob_httpAuthToken=<shared-secret>

Disable UTXO File Processing

blockpersister_processUTXOFiles=false

Migration Notes

Listen Address Default

blockpersister_httpListenAddress now defaults to 127.0.0.1:8083 instead of :8083. The endpoint is plain HTTP and its blob API accepts writes, so it no longer binds every interface by default. A deployment that reaches this endpoint from another host must set the address explicitly.

Blob API writes require a token

POST, PATCH and DELETE on the blob HTTP API now return 401 until blockpersister_httpAuthToken is set on the server and the same value is set as blob_httpAuthToken on each client. Reads (GET, HEAD, /health) are unaffected.

The HTTP blob client reports a 401 as a configuration error. The pruner keeps deletions for that store queued and logs an error on each pass until the tokens match, instead of retrying and dropping them. Deletions for the other blob stores carry on.

Overwrite over the HTTP blob API

allowOverwrite is sent only on a POST (options.WithAllowOverwrite(true)) and honoured only for a caller presenting the matching token. An unauthenticated caller cannot write at all. Without the flag, a write to a key that already exists is answered 409 and returned as ErrBlobAlreadyExists.

Callers that replace blobs (the UTXO persister’s lastProcessed marker, the set-hash sidecar, checkpoints, seed packages, subtree re-writes, the peer registry snapshot) work over an http:// blob store once both tokens are set.

Settings Reorganization

The Block Persister settings have been reorganized into a dedicated BlockPersisterSettings struct. The following environment variable names have changed:

Old VariableNew Variable
blockPersisterStoreblockpersister_store
blockPersister_httpListenAddressblockpersister_httpListenAddress
blockPersister_persistSleepblockpersister_persistSleep

Removed Settings

The following settings have been removed in the current version as persistence state is now tracked in the database:

  • blockPersister_stateFile - No longer needed, persistence tracked in database persisted_at column
  • blockpersister_persistAge - No longer needed, blocks processed as soon as they’re available
  • blockpersister_enableDefensiveReorgCheck - No longer needed, reorg handling simplified

If you have these settings in your configuration files, they can be safely removed.