BSV blockchainBSV blockchain

Asset Service Settings

Related Topic: Asset Service

Configuration Settings

SettingTypeDefaultEnvironment VariableUsage
APIPrefixstring“/api/v1”asset_apiPrefixURL prefix for API endpoints
CentrifugeListenAddressstring“:8892”asset_centrifugeListenAddressNon-empty enables the WebSocket; not bound (served on Asset HTTP)
CentrifugeAllowOriginsstring""asset_centrifugeAllowOriginsPipe-separated extra browser origins allowed to open the WebSocket
CentrifugeDisableboolfalseasset_centrifuge_disableDisables WebSocket server
HTTPAddressstring“http://localhost:8090/api/v1”asset_httpAddressRequired when Centrifuge enabled - Must be non-empty and valid URL format
HTTPListenAddressstring“:8090”asset_httpListenAddressCRITICAL - HTTP server binding (fails during Init() if empty)
HTTPPortint8090ASSET_HTTP_PORTUNUSED - HTTPListenAddress is used instead
HTTPPublicAddressstring""asset_httpPublicAddressUNUSED - Reserved for future use
SignHTTPResponsesboolfalseasset_sign_http_responsesAdds X-Signature header (requires P2P.PrivateKey, non-fatal if invalid)
EchoDebugboolfalseECHO_DEBUGEnables verbose logging and request middleware
PropagationPublicURLstring""asset_propagation_public_urlPublic-facing URL for propagation service

Concurrency Settings

SettingTypeDefaultEnvironment VariableUsage
ConcurrencyGetTransactionint0asset_concurrency_get_transactionRate limit for GetTransaction (0=unlimited, -1=NumCPU, >0=exact)
ConcurrencyGetTransactionMetaint0asset_concurrency_get_transaction_metaRate limit for GetTransactionMeta
ConcurrencyGetSubtreeDataint2asset_concurrency_get_subtree_dataRate limit for GetSubtreeData
ConcurrencyGetSubtreeDataReaderint4asset_concurrency_get_subtree_data_readerRate limit for GetSubtreeDataReader
ConcurrencyGetSubtreeTransactionsint2asset_concurrency_get_subtree_transactionsRate limit for GetSubtreeTransactions
ConcurrencyGetSubtreeExistsint0asset_concurrency_get_subtree_existsRate limit for GetSubtreeExists
ConcurrencyGetSubtreeHeadint0asset_concurrency_get_subtree_headRate limit for GetSubtreeHead
ConcurrencyGetUtxoint0asset_concurrency_get_utxoRate limit for GetUtxo
ConcurrencyGetLegacyBlockReaderint0asset_concurrency_get_legacy_block_readerConcurrent legacy block streams for anonymous callers (default: unlimited; the cap is opt-in because the permit is held for the whole stream)
ConcurrencyGetLegacyBlockReaderPeerint0asset_concurrency_get_legacy_block_reader_peerConcurrent legacy block streams for this node’s own legacy peer server (pushBlockMsg); only used when asset_legacyPeerPoolToken is set (default: unlimited)
LegacyPeerPoolTokenstring""asset_legacyPeerPoolTokenShared secret the legacy service sends in X-Teranode-Internal-Token to use the peer pool; set the same value on legacy and Asset. Empty disables the peer pool. Redacted in settings output
SubtreeDataStreamingChunkSizeint10000asset_subtreeDataStreamingChunkSizeRecords per subtree data streaming chunk
SubtreeDataStreamingConcurrencyint2asset_subtreeDataStreamingConcurrencyParallel workers for subtree data streaming

Concurrency Control:

  • 0 = Unlimited concurrency (no rate limiting)
  • -1 = Dynamic limit based on runtime.NumCPU()
  • >0 = Exact concurrency limit

HTTP Rate Limit and Peer Authentication Settings

SettingTypeDefaultEnvironment VariableUsage
HTTPRateLimitint1024asset_httpRateLimitPer-IP req/s for unverified clients (0 disables)
HTTPHeavyRateLimitint10asset_httpHeavyRateLimitPer-IP req/s on heavy endpoints (blocks, subtrees, batch txs, headers_to_common_ancestor)
HTTPPeerRateMultiplierint5asset_httpPeerRateMultiplierAuthenticated peers get base × this rate
HTTPMinerRateLimitint0asset_httpMinerRateLimitPer-peer req/s cap for miner tier; 0 = fully exempt
HTTPBodyLimitstring“100MB”asset_httpBodyLimitMax request body size (Echo BodyLimit, returns 413)
TrustedProxyCIDRsstring""asset_trustedProxyCIDRsPipe-separated CIDRs trusted for X-Forwarded-For extraction (fails Init if non-empty but unparseable)
PeerAuthAllowliststring""asset_peerAuthAllowlistPipe-separated libp2p peer IDs eligible for tier elevation; empty = no peer is elevated
PeerMinerReputationThresholdfloat6450.0asset_peerMinerReputationThresholdMin reputation score for tierMiner classification

Rate-limit tiers:

  • Unverified (no signature or signature fails verification): bucketed by source IP, IPv6 normalised to /64. Held in a bounded LRU (50k entries) so an attacker rotating addresses cannot grow the map without limit.
  • Peer (valid signature + peer ID in allowlist + not classified as miner): bucketed by libp2p peer ID at HTTPRateLimit × HTTPPeerRateMultiplier.
  • Miner (valid signature + peer ID in allowlist + BlocksReceived > 0 + ReputationScore ≥ PeerMinerReputationThreshold): fully exempt if HTTPMinerRateLimit = 0, otherwise bucketed by peer ID at HTTPMinerRateLimit.

When PeerAuthAllowlist is empty (the default), signatures are still verified (replay cache + body digest + ±10s freshness window all apply) but no tier elevation is granted — every authenticated peer is treated as unverified for rate-limit purposes. This is the safe opt-in default; operators must explicitly list trusted peers.

Global Settings

SettingTypeDefaultEnvironment VariableUsage
SecurityLevelHTTPint0securityLevelHTTP0=HTTP, non-zero=HTTPS
ServerCertFilestring""server_certFileTLS certificate file (required for HTTPS)
ServerKeyFilestring""server_keyFileTLS key file (required for HTTPS)
StatsPrefixstring“gocore”stats_prefixURL prefix for gocore stats endpoints
Dashboard.Enabledboolfalsedashboard_enabledEnables dashboard UI and authentication
P2P.PrivateKeystring""p2p_private_keyHex-encoded Ed25519 key for response signing

Configuration Dependencies

Centrifuge WebSocket Server

  • CentrifugeDisable = false enables WebSocket server
  • CentrifugeListenAddress must be non-empty
  • HTTPAddress must be non-empty and valid URL format (validated via url.Parse(), fails Init() if invalid)

HTTP Response Signing

  • SignHTTPResponses = true enables signing
  • Requires P2P.PrivateKey (hex-encoded Ed25519 format)
  • Invalid P2P.PrivateKey logs error but service continues without signing (non-fatal)
  • Adds X-Signature header to responses

HTTPS Support

  • SecurityLevelHTTP != 0 enables HTTPS
  • Both ServerCertFile and ServerKeyFile required
  • Validated during Start(), fails if missing

Service Dependencies

DependencyInterfaceUsage
UTXOStoreutxo.StoreUTXO-related API endpoints
TxStoreblob.StoreTransaction data access
SubtreeStoreblob.StoreSubtree data access
BlockPersisterStoreblob.StoreBlock data access
BlockchainClientblockchain.ClientIBlockchain operations, FSM state, waits for FSM transition from IDLE
BlockvalidationClientblockvalidation.InterfaceBlock invalidation/revalidation endpoints
P2PClientp2p.ClientIPeer registry and catchup status endpoints

Validation Rules

SettingValidationErrorWhen Checked
HTTPListenAddressMust not be empty“no asset_httpListenAddress setting found”During Init()
HTTPAddressMust be valid URL when Centrifuge enabled“asset_httpAddress not found in config”During Init()
ServerCertFileMust exist when SecurityLevelHTTP != 0“server_certFile is required for HTTPS”During Start()
ServerKeyFileMust exist when SecurityLevelHTTP != 0“server_keyFile is required for HTTPS”During Start()

Configuration Examples

HTTP Configuration

asset_httpListenAddress=:8090
asset_apiPrefix=/api/v1

HTTPS Configuration

securityLevelHTTP=1
server_certFile=/path/to/cert.pem
server_keyFile=/path/to/key.pem
asset_httpListenAddress=:8090

Centrifuge WebSocket

asset_centrifuge_disable=false
# Enables the websocket; not bound, the socket is served on Asset HTTP at /connection/websocket
asset_centrifugeListenAddress=:8892
asset_httpAddress=http://localhost:8090/api/v1
# Only needed when a reverse proxy rewrites the Host header the Asset service sees
asset_centrifugeAllowOrigins=https://dashboard.example.com

HTTP Response Signing

asset_sign_http_responses=true
p2p_private_key=<hex-encoded-ed25519-private-key>

Stats Endpoints

stats_prefix=/stats/
# Registers: /stats/stats, /stats/reset, /stats/*