BSV blockchainBSV blockchain

Alert Service Settings

Related Topic: Alert Service

Configuration Settings

SettingTypeDefaultEnvironment VariableUsage
GenesisKeys[]string[] (empty: per-network default, see below)alert_genesis_keysPublic keys allowed to sign alerts (pipe-delimited). Empty uses the network default
P2PPrivateKeystring""alert_p2p_private_keyHex-encoded Ed25519 private key (64-byte seed‖pubkey). Auto-generates if empty
ProtocolIDstring"" (empty: per-network default, see below)alert_protocol_idlibp2p protocol identifier. Empty uses the network default
StoreURL*url.URL“sqlite:///alert”alert_storeDatabase connection URL
TopicNamestring"" (empty: per-network default, see below)alert_topic_nameP2P pubsub topic. Empty uses the network default
P2PPortint9908ALERT_P2P_PORTP2P listening port (string length >= 2 after PORT_PREFIX applied)
P2PBootstrapPeerstring""alert_p2p_bootstrap_peerExtra libp2p bootstrap multiaddr for private alert networks (public IPFS peers are still tried)
P2PAllowPrivateIPsboolfalsealert_p2p_allow_private_ipsAllow dialing/accepting/advertising RFC1918 addresses on the alert network
P2PPeerDiscoveryIntervaltime.Duration10malert_p2p_peer_discovery_intervalPeer discovery and alert sync cadence
P2PDHTModestring“client”alert_p2p_dht_modeKademlia DHT mode: client or server

Network-Specific Behavior

Alert Network Defaults:

GenesisKeys, ProtocolID and TopicName are empty in settings.conf. Each empty setting is filled from the configured network when the service starts; a non-empty value is an explicit override and is used as-is. The defaults come from go-alert-system’s embedded network configs (config.NetworkDefaults), resolved in services/alert/network_defaults.go.

NetworkProtocolIDTopicNameGenesisKeys
mainnet/bitcoin/alert-system/1.0.0bitcoin_alert_systemmainnet key set
testnet/bitcoin-testnet/alert-system/0.0.1bitcoin_alert_system_testnettestnet key set
stn/bitcoin-stn/alert-system/0.0.1bitcoin_alert_system_stntestnet key set
others (regtest, teratestnet, tstn)/bitcoin/alert-system/1.0.0bitcoin_alert_system_{network}mainnet key set

Networks without a public alert network fall back to the mainnet keys and protocol on a network-suffixed topic, and the service logs a warning. Set all three for a private alert network.

PORT_PREFIX Support:

The global PORT_PREFIX environment variable is prepended to P2PPort if set.

Example: PORT_PREFIX=1 with ALERT_P2P_PORT=9908 results in port 19908.

Auto-Generation Behavior

P2P Private Key:

  • Triggers only if P2PPrivateKey is empty
  • Creates directory: $HOME/.bitcoin/ (permissions: 0750)
  • Sets internal PrivateKeyPath to $HOME/.bitcoin/alert_system_private_key (does not modify Teranode settings)
  • Generates a key into that file (permissions: 0600) only if the file is missing or empty; otherwise loads it, so the peer identity is stable across restarts. An unreadable or invalid file fails startup rather than being overwritten

Database Configuration

SchemeURL FormatPool SettingsNotes
SQLitesqlite:///database_nameMax Idle: 1, Max Open: 1File created: {DataFolder}/{database_name}.db
SQLite Memorysqlitememory:///database_nameMax Idle: 1, Max Open: 1In-memory only
PostgreSQLpostgres://user:pass@host:port/db?sslmode=requireMax Idle: 2, Max Open: 5, Timeout: 20sSupports sslmode query param
MySQLmysql://user:pass@host:port/db?sslmode=requireMax Idle: 2, Max Open: 5, Timeout: 20sSupports sslmode query param

Internal Configuration (Hardcoded)

SettingValueUsage
AlertProcessingInterval5 minutesAlert processing frequency
RequestLoggingtrueHTTP request logging
AutoMigratetrueDatabase schema migration on startup
P2P.IP“0.0.0.0”P2P listening address (all interfaces)
PeerBanDuration100 yearsDuration for peer bans (effectively permanent)
DisableRPCVerificationfalseValidates blockchain client connection at startup

Service Dependencies

DependencyInterfaceUsage
BlockchainClientblockchain.ClientIBlock operations, RPC verification
UTXOStoreutxo.StoreUTXO freezing/unfreezing
BlockAssemblyClient*blockassembly.ClientBlock assembly operations
PeerClientpeer.ClientILegacy peer banning
P2PClientp2pservice.ClientIP2P peer operations

Validation Rules

SettingValidationErrorWhen Checked
GenesisKeysMust not be empty after network defaults are appliedconfig.ErrNoGenesisKeysDuring Init()
GenesisKeysEach key must be a hex-encoded compressed public key (66 hex characters); at least 3 keys (an alert needs 3 distinct signers) and at most 10. Blank entries are dropped and repeated keys (in any case) are kept onceConfiguration errorDuring Init()
P2P.IPLength >= 5 charactersconfig.ErrNoP2PIPDuring Init()
P2P.PortString length >= 2 charactersconfig.ErrNoP2PPortDuring Init()
StoreURLSupported scheme (sqlite/sqlitememory/postgres/mysql)ErrDatastoreUnsupportedDuring Init()

Configuration Examples

Production Configuration

alert_store=postgres://user:pass@host:5432/alert_db?sslmode=require
ALERT_P2P_PORT=4001
# genesis keys, protocol ID and topic follow `network`; no need to set them

Private Alert Network

alert_genesis_keys=key1|key2|key3
alert_protocol_id=/my-net/alert-system/0.0.1
alert_topic_name=my_net_alert_system

Development Configuration

alert_store=sqlite:///alert

Auto-Generated Private Key

# Leave empty to auto-generate
alert_p2p_private_key=
# Generated once into $HOME/.bitcoin/alert_system_private_key and reused on restart