Configuration Reference

Complete reference for all Guts node configuration options.

Configuration Methods

Guts supports three configuration methods, in order of precedence:

Command-line flags (highest priority)
Environment variables
Configuration file (lowest priority)

Configuration File

Default location: config.yaml (current directory) or /etc/guts/config.yaml

Full Configuration Example

yaml

# Guts Node Configuration
# All values shown are defaults unless noted

#──────────────────────────────────────────────────────────────────────────────
# HTTP API Configuration
#──────────────────────────────────────────────────────────────────────────────
api:
  # Listen address for HTTP API
  # Environment: GUTS_API_ADDR
  # CLI: --api-addr
  addr: "127.0.0.1:8080"

  # Request timeout in seconds (1-3600)
  # Environment: GUTS_REQUEST_TIMEOUT_SECS
  request_timeout_secs: 30

  # Maximum request body size in bytes
  # Environment: GUTS_MAX_REQUEST_BODY_SIZE
  max_request_body_size: 104857600  # 100MB

  # Enable CORS (for browser access)
  cors:
    enabled: false
    allowed_origins:
      - "https://example.com"
    allowed_methods:
      - GET
      - POST
      - PUT
      - DELETE
    allowed_headers:
      - Content-Type
      - Authorization
    max_age_secs: 3600

#──────────────────────────────────────────────────────────────────────────────
# P2P Networking Configuration
#──────────────────────────────────────────────────────────────────────────────
p2p:
  # Listen address for P2P connections
  # Environment: GUTS_P2P_ADDR
  # CLI: --p2p-addr
  addr: "0.0.0.0:9000"

  # Bootstrap nodes for network discovery
  # Format: /ip4/<ip>/tcp/<port>/p2p/<peer-id>
  # Environment: GUTS_BOOTSTRAP_NODES (comma-separated)
  bootstrap_nodes: []
  # Example:
  # bootstrap_nodes:
  #   - "/ip4/1.2.3.4/tcp/9000/p2p/12D3KooWExample..."
  #   - "/dns4/bootstrap.guts.network/tcp/9000/p2p/12D3KooW..."

  # External address (for NAT traversal)
  # Environment: GUTS_EXTERNAL_ADDR
  external_addr: null

  # Maximum number of peer connections
  max_peers: 50

  # Connection timeout in seconds
  connection_timeout_secs: 30

  # Dial timeout in seconds
  dial_timeout_secs: 10

  # Message size limit in bytes
  max_message_size: 1048576  # 1MB

#──────────────────────────────────────────────────────────────────────────────
# Metrics Configuration
#──────────────────────────────────────────────────────────────────────────────
metrics:
  # Listen address for Prometheus metrics endpoint
  # Environment: GUTS_METRICS_ADDR
  # CLI: --metrics-addr
  addr: "0.0.0.0:9090"

  # Metrics endpoint path
  path: "/metrics"

  # Include process metrics
  include_process_metrics: true

  # Include Go runtime metrics (if applicable)
  include_runtime_metrics: true

#──────────────────────────────────────────────────────────────────────────────
# Storage Configuration
#──────────────────────────────────────────────────────────────────────────────
storage:
  # Data directory for all persistent data
  # Environment: GUTS_DATA_DIR
  # CLI: --data-dir
  data_dir: "./data"

  # Storage backend: "memory" or "rocksdb"
  # Environment: GUTS_STORAGE_BACKEND
  backend: "rocksdb"

  # RocksDB specific options
  rocksdb:
    # Write buffer size in bytes
    write_buffer_size: 67108864  # 64MB

    # Maximum number of write buffers
    max_write_buffer_number: 3

    # Block cache size in bytes
    block_cache_size: 536870912  # 512MB

    # Enable compression
    compression: true

    # Compression algorithm: "none", "snappy", "lz4", "zstd"
    compression_type: "lz4"

    # Maximum number of open files
    max_open_files: 10000

    # Enable statistics
    enable_statistics: true

  # Cache configuration
  cache:
    # Enable in-memory cache
    enabled: true

    # Maximum cache size in bytes
    max_size: 268435456  # 256MB

    # TTL for cached objects in seconds
    ttl_secs: 3600

#──────────────────────────────────────────────────────────────────────────────
# Logging Configuration
#──────────────────────────────────────────────────────────────────────────────
logging:
  # Log level: trace, debug, info, warn, error
  # Environment: GUTS_LOG_LEVEL
  # CLI: --log-level
  level: "info"

  # Log format: json, pretty
  # Environment: GUTS_LOG_FORMAT
  # CLI: --log-format
  format: "json"

  # Include source location in logs
  include_location: false

  # Include target (module path) in logs
  include_target: true

  # Log file (optional, default is stdout)
  # file: "/var/log/guts/node.log"

  # Filter specific modules
  # filters:
  #   guts_p2p: debug
  #   guts_consensus: debug
  #   tower_http: info

#──────────────────────────────────────────────────────────────────────────────
# Consensus Configuration
#──────────────────────────────────────────────────────────────────────────────
consensus:
  # Enable consensus engine
  # Environment: GUTS_CONSENSUS_ENABLED
  enabled: false

  # Use Simplex BFT (production consensus)
  # Environment: GUTS_CONSENSUS_USE_SIMPLEX_BFT
  use_simplex_bft: false

  # Block production interval in milliseconds
  # Environment: GUTS_CONSENSUS_BLOCK_TIME_MS
  block_time_ms: 2000

  # Maximum transactions per block
  # Environment: GUTS_CONSENSUS_MAX_TXS_PER_BLOCK
  max_txs_per_block: 1000

  # Mempool configuration
  mempool:
    # Maximum pending transactions
    # Environment: GUTS_CONSENSUS_MEMPOOL_MAX_TXS
    max_txs: 10000

    # Transaction TTL in seconds
    # Environment: GUTS_CONSENSUS_MEMPOOL_TTL_SECS
    ttl_secs: 600

  # Genesis file path (for validator networks)
  # Environment: GUTS_CONSENSUS_GENESIS_FILE
  genesis_file: null

  # Validator configuration
  validator:
    # Private key (hex-encoded Ed25519)
    # Environment: GUTS_PRIVATE_KEY
    # CLI: --private-key
    private_key: null

    # Or load from file
    # Environment: GUTS_PRIVATE_KEY_FILE
    private_key_file: null

#──────────────────────────────────────────────────────────────────────────────
# Security Configuration
#──────────────────────────────────────────────────────────────────────────────
security:
  # Rate limiting
  rate_limit:
    enabled: true
    # Requests per second per IP
    requests_per_second: 100
    # Burst size
    burst_size: 200

  # TLS configuration (for HTTPS)
  tls:
    enabled: false
    cert_file: null
    key_file: null
    # Minimum TLS version: "1.2" or "1.3"
    min_version: "1.2"

  # Authentication
  auth:
    # Require authentication for write operations
    require_auth_for_writes: false
    # API token validation
    validate_tokens: true

#──────────────────────────────────────────────────────────────────────────────
# Resilience Configuration
#──────────────────────────────────────────────────────────────────────────────
resilience:
  # Retry configuration
  retry:
    # Maximum retry attempts
    max_attempts: 3
    # Initial backoff in milliseconds
    initial_backoff_ms: 100
    # Maximum backoff in milliseconds
    max_backoff_ms: 10000
    # Backoff multiplier
    multiplier: 2.0
    # Add jitter to backoff
    jitter: true

  # Circuit breaker configuration
  circuit_breaker:
    # Failure threshold before opening
    failure_threshold: 5
    # Success threshold to close
    success_threshold: 3
    # Timeout in seconds before half-open
    timeout_secs: 30

  # Timeouts
  timeouts:
    # Default operation timeout in seconds
    operation_timeout_secs: 30
    # P2P operation timeout
    p2p_timeout_secs: 60
    # Consensus timeout
    consensus_timeout_secs: 120

#──────────────────────────────────────────────────────────────────────────────
# Health Check Configuration
#──────────────────────────────────────────────────────────────────────────────
health:
  # Enable health check endpoints
  enabled: true

  # Startup probe configuration
  startup:
    # Maximum time to wait for startup
    timeout_secs: 60

  # Liveness probe configuration
  liveness:
    # Check interval
    interval_secs: 10

  # Readiness probe configuration
  readiness:
    # Minimum peer count to be ready
    min_peers: 0
    # Require sync to be complete
    require_synced: false

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293

Environment Variables

All configuration options can be set via environment variables:

Variable	Description	Default
`GUTS_API_ADDR`	HTTP API listen address	`127.0.0.1:8080`
`GUTS_P2P_ADDR`	P2P listen address	`0.0.0.0:9000`
`GUTS_METRICS_ADDR`	Metrics listen address	`0.0.0.0:9090`
`GUTS_DATA_DIR`	Data directory	`./data`
`GUTS_LOG_LEVEL`	Log level	`info`
`GUTS_LOG_FORMAT`	Log format	`json`
`GUTS_PRIVATE_KEY`	Node private key (hex)	-
`GUTS_PRIVATE_KEY_FILE`	Path to private key file	-
`GUTS_BOOTSTRAP_NODES`	Bootstrap nodes (comma-separated)	-
`GUTS_CONSENSUS_ENABLED`	Enable consensus	`false`
`GUTS_CONSENSUS_USE_SIMPLEX_BFT`	Use Simplex BFT	`false`
`GUTS_CONSENSUS_BLOCK_TIME_MS`	Block time (ms)	`2000`
`GUTS_CONSENSUS_MAX_TXS_PER_BLOCK`	Max TXs per block	`1000`
`GUTS_CONSENSUS_MEMPOOL_MAX_TXS`	Max mempool size	`10000`
`GUTS_CONSENSUS_MEMPOOL_TTL_SECS`	Mempool TTL	`600`
`GUTS_CONSENSUS_GENESIS_FILE`	Genesis file path	-
`GUTS_STORAGE_BACKEND`	Storage backend	`rocksdb`
`GUTS_REQUEST_TIMEOUT_SECS`	Request timeout	`30`

Command-Line Flags

guts-node [OPTIONS]

Options:
  --config <FILE>           Configuration file path [default: config.yaml]
  --api-addr <ADDR>         HTTP API listen address
  --p2p-addr <ADDR>         P2P listen address
  --metrics-addr <ADDR>     Metrics listen address
  --data-dir <DIR>          Data directory
  --log-level <LEVEL>       Log level (trace, debug, info, warn, error)
  --log-format <FORMAT>     Log format (json, pretty)
  --private-key <KEY>       Node private key (hex-encoded)
  --local                   Enable local development mode (pretty logs)
  -h, --help                Print help
  -V, --version             Print version

Configuration Validation

The node validates configuration on startup:

bash

# Validate configuration without starting
guts-node --config /etc/guts/config.yaml --dry-run

# Common validation errors:
# - Invalid address format
# - Port already in use
# - Invalid private key format
# - Genesis file not found
# - Invalid log level

Example Configurations

Development Node

yaml

api:
  addr: "127.0.0.1:8080"

p2p:
  addr: "0.0.0.0:9000"

storage:
  data_dir: "./dev-data"
  backend: "memory"

logging:
  level: "debug"
  format: "pretty"

Production Full Node

yaml

api:
  addr: "0.0.0.0:8080"
  request_timeout_secs: 30

p2p:
  addr: "0.0.0.0:9000"
  bootstrap_nodes:
    - "/dns4/bootstrap1.guts.network/tcp/9000/p2p/..."
    - "/dns4/bootstrap2.guts.network/tcp/9000/p2p/..."

metrics:
  addr: "0.0.0.0:9090"

storage:
  data_dir: "/var/lib/guts"
  backend: "rocksdb"
  rocksdb:
    block_cache_size: 1073741824  # 1GB

logging:
  level: "info"
  format: "json"

security:
  rate_limit:
    enabled: true
    requests_per_second: 1000

Validator Node

yaml

api:
  addr: "0.0.0.0:8080"

p2p:
  addr: "0.0.0.0:9000"
  bootstrap_nodes:
    - "/dns4/bootstrap1.guts.network/tcp/9000/p2p/..."

storage:
  data_dir: "/var/lib/guts"
  backend: "rocksdb"

logging:
  level: "info"
  format: "json"

consensus:
  enabled: true
  use_simplex_bft: true
  block_time_ms: 2000
  max_txs_per_block: 1000
  genesis_file: "/etc/guts/genesis.json"
  validator:
    private_key_file: "/etc/guts/node.key"

Genesis File Format

For validator networks:

json

{
  "chain_id": "guts-mainnet",
  "genesis_time": "2025-01-01T00:00:00Z",
  "validators": [
    {
      "public_key": "abc123...",
      "power": 1,
      "name": "validator-1"
    },
    {
      "public_key": "def456...",
      "power": 1,
      "name": "validator-2"
    },
    {
      "public_key": "ghi789...",
      "power": 1,
      "name": "validator-3"
    },
    {
      "public_key": "jkl012...",
      "power": 1,
      "name": "validator-4"
    }
  ],
  "consensus": {
    "block_time_ms": 2000,
    "max_txs_per_block": 1000
  }
}

Configuration Reference ​

Configuration Methods ​

Configuration File ​

Full Configuration Example ​

Environment Variables ​

Command-Line Flags ​

Configuration Validation ​

Example Configurations ​

Development Node ​

Production Full Node ​

Validator Node ​

Genesis File Format ​

Related Documentation ​

Configuration Reference

Configuration Methods

Configuration File

Full Configuration Example

Environment Variables

Command-Line Flags

Configuration Validation

Example Configurations

Development Node

Production Full Node

Validator Node

Genesis File Format

Related Documentation