# Asset Service Settings

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

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...

**Related Topic**: [Asset Service](https://bsvblockchain.com/docs/nodes/teranode/topics/services/asset-server/)

## Configuration Settings

| Setting | Type | Default | Environment Variable | Usage |
|---------|------|---------|---------------------|-------|
| APIPrefix | string | "/api/v1" | asset_apiPrefix | URL prefix for API endpoints |
| CentrifugeListenAddress | string | ":8892" | asset_centrifugeListenAddress | Non-empty enables the WebSocket; not bound (served on Asset HTTP) |
| CentrifugeAllowOrigins | string | "" | asset_centrifugeAllowOrigins | Pipe-separated extra browser origins allowed to open the WebSocket |
| CentrifugeDisable | bool | false | asset_centrifuge_disable | Disables WebSocket server |
| HTTPAddress | string | "`http://localhost:8090/api/v1`" | asset_httpAddress | **Required when Centrifuge enabled** - Must be non-empty and valid URL format |
| HTTPListenAddress | string | ":8090" | asset_httpListenAddress | **CRITICAL** - HTTP server binding (fails during Init() if empty) |
| HTTPPort | int | 8090 | ASSET_HTTP_PORT | **UNUSED** - HTTPListenAddress is used instead |
| HTTPPublicAddress | string | "" | asset_httpPublicAddress | **UNUSED** - Reserved for future use |
| SignHTTPResponses | bool | false | asset_sign_http_responses | Adds X-Signature header (requires P2P.PrivateKey, non-fatal if invalid) |
| EchoDebug | bool | false | ECHO_DEBUG | Enables verbose logging and request middleware |
| PropagationPublicURL | string | "" | asset_propagation_public_url | Public-facing URL for propagation service |

## Concurrency Settings

| Setting | Type | Default | Environment Variable | Usage |
|---------|------|---------|---------------------|-------|
| ConcurrencyGetTransaction | int | 0 | asset_concurrency_get_transaction | Rate limit for GetTransaction (0=unlimited, -1=NumCPU, >0=exact) |
| ConcurrencyGetTransactionMeta | int | 0 | asset_concurrency_get_transaction_meta | Rate limit for GetTransactionMeta |
| ConcurrencyGetSubtreeData | int | 2 | asset_concurrency_get_subtree_data | Rate limit for GetSubtreeData |
| ConcurrencyGetSubtreeDataReader | int | 4 | asset_concurrency_get_subtree_data_reader | Rate limit for GetSubtreeDataReader |
| ConcurrencyGetSubtreeTransactions | int | 2 | asset_concurrency_get_subtree_transactions | Rate limit for GetSubtreeTransactions |
| ConcurrencyGetSubtreeExists | int | 0 | asset_concurrency_get_subtree_exists | Rate limit for GetSubtreeExists |
| ConcurrencyGetSubtreeHead | int | 0 | asset_concurrency_get_subtree_head | Rate limit for GetSubtreeHead |
| ConcurrencyGetUtxo | int | 0 | asset_concurrency_get_utxo | Rate limit for GetUtxo |
| ConcurrencyGetLegacyBlockReader | int | 0 | asset_concurrency_get_legacy_block_reader | Concurrent legacy block streams for anonymous callers (default: unlimited; the cap is opt-in because the permit is held for the whole stream) |
| ConcurrencyGetLegacyBlockReaderPeer | int | 0 | asset_concurrency_get_legacy_block_reader_peer | Concurrent legacy block streams for this node's own legacy peer server (pushBlockMsg); only used when asset_legacyPeerPoolToken is set (default: unlimited) |
| LegacyPeerPoolToken | string | "" | asset_legacyPeerPoolToken | Shared 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 |
| SubtreeDataStreamingChunkSize | int | 10000 | asset_subtreeDataStreamingChunkSize | Records per subtree data streaming chunk |
| SubtreeDataStreamingConcurrency | int | 2 | asset_subtreeDataStreamingConcurrency | Parallel 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

| Setting | Type | Default | Environment Variable | Usage |
|---------|------|---------|---------------------|-------|
| HTTPRateLimit | int | 1024 | asset_httpRateLimit | Per-IP req/s for unverified clients (0 disables) |
| HTTPHeavyRateLimit | int | 10 | asset_httpHeavyRateLimit | Per-IP req/s on heavy endpoints (blocks, subtrees, batch txs, headers_to_common_ancestor) |
| HTTPPeerRateMultiplier | int | 5 | asset_httpPeerRateMultiplier | Authenticated peers get base × this rate |
| HTTPMinerRateLimit | int | 0 | asset_httpMinerRateLimit | Per-peer req/s cap for miner tier; 0 = fully exempt |
| HTTPBodyLimit | string | "100MB" | asset_httpBodyLimit | Max request body size (Echo BodyLimit, returns 413) |
| TrustedProxyCIDRs | string | "" | asset_trustedProxyCIDRs | Pipe-separated CIDRs trusted for X-Forwarded-For extraction (fails Init if non-empty but unparseable) |
| PeerAuthAllowlist | string | "" | asset_peerAuthAllowlist | Pipe-separated libp2p peer IDs eligible for tier elevation; empty = no peer is elevated |
| PeerMinerReputationThreshold | float64 | 50.0 | asset_peerMinerReputationThreshold | Min 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

| Setting | Type | Default | Environment Variable | Usage |
|---------|------|---------|---------------------|-------|
| SecurityLevelHTTP | int | 0 | securityLevelHTTP | 0=HTTP, non-zero=HTTPS |
| ServerCertFile | string | "" | server_certFile | TLS certificate file (required for HTTPS) |
| ServerKeyFile | string | "" | server_keyFile | TLS key file (required for HTTPS) |
| StatsPrefix | string | "gocore" | stats_prefix | URL prefix for gocore stats endpoints |
| Dashboard.Enabled | bool | false | dashboard_enabled | Enables dashboard UI and authentication |
| P2P.PrivateKey | string | "" | p2p_private_key | Hex-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

| Dependency | Interface | Usage |
|------------|-----------|-------|
| UTXOStore | utxo.Store | UTXO-related API endpoints |
| TxStore | blob.Store | Transaction data access |
| SubtreeStore | blob.Store | Subtree data access |
| BlockPersisterStore | blob.Store | Block data access |
| BlockchainClient | blockchain.ClientI | Blockchain operations, FSM state, waits for FSM transition from IDLE |
| BlockvalidationClient | blockvalidation.Interface | Block invalidation/revalidation endpoints |
| P2PClient | p2p.ClientI | Peer registry and catchup status endpoints |

## Validation Rules

| Setting | Validation | Error | When Checked |
|---------|------------|-------|-------------|
| HTTPListenAddress | Must not be empty | "no asset_httpListenAddress setting found" | During Init() |
| HTTPAddress | Must be valid URL when Centrifuge enabled | "asset_httpAddress not found in config" | During Init() |
| ServerCertFile | Must exist when SecurityLevelHTTP != 0 | "server_certFile is required for HTTPS" | During Start() |
| ServerKeyFile | Must exist when SecurityLevelHTTP != 0 | "server_keyFile is required for HTTPS" | During Start() |

## Configuration Examples

### HTTP Configuration

```bash
asset_httpListenAddress=:8090
asset_apiPrefix=/api/v1
```

### HTTPS Configuration

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

### Centrifuge WebSocket

```bash
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

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

### Stats Endpoints

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