Paxeer Node Operations Guide

This guide covers the detailed operational aspects of running a Paxeer node, including configuration management, maintenance procedures, and best practices for stable and performant operations.

Configuration Management

Directory Structure

The Paxeer node configuration is stored in $HOME/.paxeer/config/:

$HOME/.paxeer/config/
├── app.toml          # Application configuration (gas fees, API settings, pruning, etc.)
├── config.toml       # Core Tendermint settings (network, consensus, and RPC)
├── client.toml       # CLI and client-related settings
├── genesis.json      # Chain genesis file, defines initial state
├── node_key.json     # Unique node identity key for peer-to-peer (P2P) networking
└── priv_validator_key.json  # Validator private signing key (if running as a validator)

The snippets below are opinionated tuning recommendations layered on top of the defaults. For the full unmodified app.toml, config.toml, and client.toml shipped by the latest tagged paxd release, jump to Default Configurations at the bottom of this section.

Essential Configuration Parameters

Network Settings (config.toml)

[p2p]
# Public address other nodes use to dial in (host:port)
external-address = "your-public-ip:26656"
# Local address to listen for incoming P2P connections
laddr = "tcp://0.0.0.0:26656"
# Combined inbound + outbound peer limit
max-connections = 200
# Per-connection bandwidth caps in bytes/sec
send-rate = 20971520
recv-rate = 20971520

[rpc]
# RPC listen address
laddr = "tcp://0.0.0.0:26657"
# Maximum number of simultaneous connections (HTTP + WS)
max-open-connections = 900
# Transaction confirmation timeout for /broadcast_tx_commit
timeout-broadcast-tx-commit = "10s"

Application Settings (app.toml)

# Minimum gas prices to prevent spam transactions
minimum-gas-prices = "0.02uhpx"

# Block retention for /block, /block_results, etc.
min-retain-blocks = 100000

# Concurrent transaction execution workers
concurrency-workers = 10

# Optimistic Concurrency Control for parallel tx execution
occ-enabled = true

[api]
# Enable the REST/Cosmos API server (port 1317)
enable = true
max-open-connections = 1000

[state-commit]
# State-commit (memiavl + FlatKV). Recommended on every node.
sc-enable = true

[state-store]
# Historical SS layer for queries. Required for any node serving RPC.
ss-enable = true
# 0 = keep everything
ss-keep-recent = 100000

[receipt-store]
# Storage backend for EVM transaction receipts (pebbledb or parquet).
rs-backend = "pebbledb"

Default Configurations

The full unmodified app.toml, config.toml, and client.toml produced by paxd init against the latest tagged paxd release. Use these as the canonical reference for every available knob and its default value.

Application-layer configuration: gas, API, gRPC, pruning, EVM, etc.

# This is a TOML config file.
# For more information, see https://github.com/toml-lang/toml

###############################################################################
###                           Base Configuration                            ###
###############################################################################

# The minimum gas prices a validator is willing to accept for processing a
# transaction.
minimum-gas-prices = "0.01uhpx"

# MinRetainBlocks defines the minimum block height offset from the current block
# for pruning Tendermint blocks. Set to 0 to disable pruning.
min-retain-blocks = 100000

# ConcurrencyWorkers defines how many workers to run for concurrent transaction execution.
concurrency-workers = 10

# occ-enabled defines whether OCC is enabled or not for transaction execution
occ-enabled = true

# HaltHeight contains a non-zero block height at which a node will gracefully
# halt and shutdown that can be used to assist upgrades and testing.
halt-height = 0

# HaltTime contains a non-zero minimum block time (in Unix seconds) at which
# a node will gracefully halt and shutdown.
halt-time = 0

# InterBlockCache enables inter-block caching.
inter-block-cache = true

# IndexEvents defines the set of events in the form {eventType}.{attributeKey},
# which informs Tendermint what to index.
index-events = []

###############################################################################
###                        State Sync Configuration                         ###
###############################################################################

[state-sync]

# snapshot-interval specifies the block interval at which local state sync snapshots are
# taken (0 to disable). Must be a multiple of pruning-keep-every.
snapshot-interval = 0

# snapshot-keep-recent specifies the number of recent snapshots to keep and serve (0 to keep all).
snapshot-keep-recent = 2

# snapshot-directory sets the directory for where state sync snapshots are persisted.
snapshot-directory = ""

###############################################################################
###                       State Commit Configuration                        ###
###############################################################################

[state-commit]
# Enable defines if the state-commit should be enabled to override existing IAVL db backend.
sc-enable = true

# Defines the SC store directory
sc-directory = ""

# WriteMode defines how EVM data writes are routed between backends.
sc-write-mode = "cosmos_only"

# ReadMode defines how EVM data reads are routed between backends.
sc-read-mode = "cosmos_only"

# AsyncCommitBuffer defines the size of asynchronous commit queue
sc-async-commit-buffer = 100

# KeepRecent defines how many state-commit snapshots (besides the latest one) to keep
sc-keep-recent = 0

# SnapshotInterval defines the block interval the snapshot is taken
sc-snapshot-interval = 10000

###############################################################################
###                         State Store Configuration                       ###
###############################################################################

[state-store]
# Enable defines whether the state-store should be enabled for storing historical data.
ss-enable = true

# Defines the directory to store the state store db files
ss-db-directory = ""

# DBBackend defines the backend database used for state-store.
# Supported backends: pebbledb, rocksdb
ss-backend = "pebbledb"

# AsyncWriteBuffer defines the async queue length for commits to be applied to State Store
ss-async-write-buffer = 100

# KeepRecent defines the number of versions to keep in state store
ss-keep-recent = 100000

# PruneInterval defines the minimum interval in seconds to trigger SS pruning.
ss-prune-interval = 600

###############################################################################
###                        Receipt Store Configuration                      ###
###############################################################################

[receipt-store]
# Backend defines the receipt store backend.
rs-backend = "pebbledb"

# Defines the receipt store directory.
db-directory = ""

# AsyncWriteBuffer defines the async queue length for commits to be applied to receipt store.
async-write-buffer = 100

# PruneIntervalSeconds defines the interval in seconds to trigger pruning.
prune-interval-seconds = 600

###############################################################################
###                            EVM Configuration                            ###
###############################################################################

[evm]
# controls whether an HTTP EVM server is enabled
http_enabled = true
http_port = 8545

# controls whether a websocket server is enabled
ws_enabled = true
ws_port = 8546

# Maximum gas limit for simulation
simulation_gas_limit = 10000000

# list of CORS allowed origins, separated by comma
cors_origins = "*"

# list of WS origins, separated by comma
ws_origins = "*"

# timeout for filters
filter_timeout = "2m0s"

###############################################################################
###                       Giga Executor Configuration                       ###
###############################################################################

[giga_executor]
# enabled controls whether to use the Giga executor (evmone-based) instead of geth's interpreter.
enabled = false

# occ_enabled controls whether to use OCC with the Giga executor.
occ_enabled = false

###############################################################################
###                       Admin Configuration (Auto-managed)                ###
###############################################################################

[admin_server]
admin_enabled = false
admin_address = "127.0.0.1:9095"

###############################################################################
###                   Telemetry Configuration (Auto-managed)                ###
###############################################################################

[telemetry]
service-name = ""
enabled = true
enable-hostname = false
enable-hostname-label = false
enable-service-label = false
prometheus-retention-time = 7200
global-labels = []

###############################################################################
###                       API Configuration (Auto-managed)                  ###
###############################################################################

[api]
enable = true
swagger = true
address = "tcp://0.0.0.0:1317"
max-open-connections = 1000

###############################################################################
###                       gRPC Configuration (Auto-managed)                 ###
###############################################################################

[grpc]
enable = true
address = "0.0.0.0:9090"

###############################################################################
###                        gRPC Web Configuration (Auto-managed)            ###
###############################################################################

[grpc-web]
enable = true
address = "0.0.0.0:9091"
enable-unsafe-cors = false