> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stablenet.network/llms.txt
> Use this file to discover all available pages before exploring further.

# Node Configuration

## Purpose and Scope

This document explains how to configure a StableNet node using command-line flags, configuration files, and deployment patterns.

For information on building the node binary, see [Installation and Building](/en/getting-started/2.1-installation-and-building).\
For genesis block setup and network initialization, see [Genesis Setup and Network Initialization](/en/getting-started/2.3-genesis-setup-and-network-initialization).

## Configuration System Overview

StableNet node configuration uses a hierarchical system that converts command-line flags into structured configuration objects, which are then used to initialize each component.

**Configuration precedence**: Command-line flags > TOML configuration file > Defaults

## Command-Line Flags

All configuration flags are defined in `cmd/utils/flags.go` and are grouped by category.

### Core Flag Categories

| Category         | Purpose                            | Key Flags                                                          |
| ---------------- | ---------------------------------- | ------------------------------------------------------------------ |
| Chain / Sync     | Chain and synchronization settings | `--datadir`, `--networkid`, `--syncmode`, `--mainnet`, `--testnet` |
| Accounts         | Key management                     | `--keystore`, `--unlock`, `--password`                             |
| Mining           | Block production                   | `--mine`, `--miner.etherbase`, `--miner.gaslimit`                  |
| Networking       | P2P configuration                  | `--port`, `--maxpeers`, `--bootnodes`, `--nat`                     |
| API              | RPC endpoints                      | `--http`, `--http.port`, `--ws`, `--http.api`                      |
| Transaction Pool | Transaction pool tuning            | `--txpool.pricelimit`, `--txpool.globalslots`                      |
| Performance      | Performance tuning                 | `--cache`, `--cache.database`, `--cache.trie`                      |
| State            | State management                   | `--state.scheme`, `--gcmode`                                       |

### Network Selection Flags

StableNet provides flags for selecting predefined networks:

* `--mainnet`: Connect to StableNet mainnet (ChainID 8282)
* `--testnet`: Connect to StableNet testnet (ChainID 8283)
* `--networkid`: Override the automatic network ID (defaults to ChainID)
* Bootstrap nodes are automatically selected based on the network flag

### Data Directory

The `--datadir` flag specifies the root directory where the node stores blockchain data and state.\
Some sub-paths, such as the keystore, can be overridden with separate flags. If not specified, internal defaults are used.

| Flag                    | Purpose                                    | Default                                             |
| ----------------------- | ------------------------------------------ | --------------------------------------------------- |
| `--datadir`             | Root directory for all data                | Linux: `~/.stablenet`, macOS: `~/Library/StableNet` |
| `--datadir.ancient`     | Separate location for ancient/freezer data | `<datadir>/gstable/ancient`                         |
| `--keystore`            | Override keystore location                 | `<datadir>/keystore`                                |
| `--datadir.minfreedisk` | Auto-shutdown disk threshold (MB)          | 0 (disabled)                                        |

## Database Configuration

This setting controls the type of database engine used by the node.\
It determines how state and chain data are stored and accessed internally, affecting performance and resource usage.

| Flag          | Description                            | Default  |
| ------------- | -------------------------------------- | -------- |
| `--db.engine` | Select state and chain database engine | `pebble` |

## Synchronization Mode

The `--syncmode` flag controls how the blockchain is synchronized:

| Mode      | Value   | Description                                                                    | Use Case                             |
| --------- | ------- | ------------------------------------------------------------------------------ | ------------------------------------ |
| **Full**  | `full`  | Download all blocks and execute all transactions and state transitions locally | Validator nodes, standard full nodes |
| **Snap**  | `snap`  | Download state snapshots first, then sync blocks to quickly build full state   | Fast initial sync                    |
| **Light** | `light` | Keep only block headers; request state/data on demand from peers               | Low-resource environments            |

## State Scheme

The `--state.scheme` flag selects the state storage layout:

* `hash`: Legacy hash-based scheme (default, stable)
* `path`: Path-based scheme with Verkle trie support (experimental)

If not specified, the node automatically selects the scheme matching the existing database.

## Mining and Validator Configuration

Flags controlling block production for StableNet validators (Anzeon-enabled networks).

### Mining Flags

| Flag                | Purpose                  | Default          | Notes                   |
| ------------------- | ------------------------ | ---------------- | ----------------------- |
| `--mine`            | Enable mining/validation | false            | Required for validators |
| `--miner.etherbase` | Block reward address     | Node key address | Auto-set in Anzeon      |
| `--miner.gaslimit`  | Block gas ceiling        | 105,000,000      | Target block gas limit  |
| `--miner.extradata` | Extra block data         | Client version   | Custom identifier       |

## Anzeon Network Design Characteristics

* `etherbase` is automatically derived from `--nodekey` and cannot be manually overridden
* `GasTip` (priority fee) is enforced as a network-wide value via GovValidator governance (except for authorized accounts)
* `BaseFee` uses a StableNet-customized calculation logic, with increase/decrease rates and min/max bounds controlled by chain parameters
* `BaseFee` is not burned; it is distributed to validators

For detailed gas fee policy, see [Gas Fee Policy](/en/transaction-processing/6.4-gas-fee-policy).\
For governance-based gas tip management, see [Validator Governance](/en/governance-system/5.3-validator-governance-\(govvalidator\)).

## P2P Network Configuration

P2P networking flags control peer discovery and connection management.

### P2P Configuration Flags

| Flag            | Purpose                                     | Default                   |
| --------------- | ------------------------------------------- | ------------------------- |
| `--port`        | P2P listening port                          | 30303                     |
| `--maxpeers`    | Maximum peer connections                    | 50                        |
| `--nat`         | NAT port mapping method                     | `any`                     |
| `--bootnodes`   | Bootstrap node enode URLs (comma-separated) | Auto-selected per network |
| `--nodiscover`  | Disable peer discovery                      | false                     |
| `--nodekey`     | P2P node key file path                      | Auto-generated            |
| `--netrestrict` | Allowed network CIDR mask                   | None (allow all)          |

### Bootstrap Node Selection

Bootstrap nodes are selected in the following order:

1. Use `--bootnodes` if explicitly specified
2. Use bootstrap nodes defined in the config file
3. If `--mainnet`, use StableNet mainnet bootstrap nodes
4. If `--testnet`, use StableNet testnet bootstrap nodes

### Static and Trusted Peers

Static and trusted peers can be configured in the `[Node.P2P]` section of a TOML configuration file:

```toml theme={null}
[Node.P2P]
StaticNodes = [
  "enode://pubkey1@ip1:port1",
  "enode://pubkey2@ip2:port2"
]
TrustedNodes = [
  "enode://pubkey3@ip3:port3"
]
```

* **StaticNodes**: Peers the node always tries to maintain connections with
* **TrustedNodes**: Peers exempt from peer count limits

## RPC API Configuration

RPC APIs expose node functionality to external clients. StableNet supports HTTP, WebSocket, and IPC transports.

### HTTP Configuration

| Flag                | Purpose                | Default        |
| ------------------- | ---------------------- | -------------- |
| `--http`            | Enable HTTP-RPC server | Disabled       |
| `--http.addr`       | Listening interface    | `localhost`    |
| `--http.port`       | Listening port         | 8545           |
| `--http.api`        | Exposed API modules    | `eth,net,web3` |
| `--http.corsdomain` | Allowed CORS domains   | None           |
| `--http.vhosts`     | Allowed virtual hosts  | `localhost`    |

### WebSocket Configuration

| Flag           | Purpose                 | Default        |
| -------------- | ----------------------- | -------------- |
| `--ws`         | Enable WebSocket server | Disabled       |
| `--ws.addr`    | Listening interface     | `localhost`    |
| `--ws.port`    | Listening port          | 8546           |
| `--ws.api`     | Exposed API modules     | `eth,net,web3` |
| `--ws.origins` | Allowed origins         | None           |

### IPC Configuration

IPC is enabled by default, creating a socket at `<datadir>/gstable.ipc`.

| Flag           | Purpose         | Default       |
| -------------- | --------------- | ------------- |
| `--ipcdisable` | Disable IPC     | false         |
| `--ipcpath`    | IPC socket path | `gstable.ipc` |

### API Namespace Security

Do not expose all API namespaces publicly. Recommended configurations:

| Deployment Type  | HTTP APIs                           | WebSocket APIs | Notes                          |
| ---------------- | ----------------------------------- | -------------- | ------------------------------ |
| Public RPC node  | `eth,net,web3`                      | `eth,net,web3` | Read-only, safe for public use |
| Validator node   | None or localhost only              | None           | Minimize attack surface        |
| Development node | `eth,net,web3,personal,debug,admin` | Same           | Full access for testing        |
| Archive node     | `eth,net,web3,txpool,debug`         | Same           | Debug APIs for analysis        |

**Warning**: `personal`, `admin`, and `debug` namespaces provide privileged operations. Never expose them on public interfaces without authentication.

### RPC Limiting Flags

| Flag                            | Purpose                                    | Default       |
| ------------------------------- | ------------------------------------------ | ------------- |
| `--rpc.gascap`                  | Max gas for `eth_call` / `eth_estimateGas` | 50,000,000    |
| `--rpc.evmtimeout`              | Timeout for `eth_call`                     | 5 seconds     |
| `--rpc.txfeecap`                | Max fee for `eth_sendTransaction`          | 0 (unlimited) |
| `--rpc.batch-request-limit`     | Max requests per batch                     | 1000          |
| `--rpc.batch-response-max-size` | Max batch response size                    | 25MB          |

These limits protect the node from resource exhaustion by malicious or misconfigured clients.

## Performance Tuning

Cache and database settings have a major impact on node performance and resource usage.

### Cache Configuration

The `--cache` flag sets total memory allocation, which is split across subsystems. Default allocation:

```text theme={null}
Total cache: 1024 MB
├─ Database: 512 MB (50%)
├─ Trie Clean: 154 MB (15%)
├─ Snapshot: 102 MB (10%)
└─ Trie Dirty (GC): 256 MB (25%)
```

For archive nodes (`--gcmode archive`), Trie Dirty cache is disabled and reallocated to Trie Clean and Snapshot.

**Recommended settings by node type:**

| Node Type                | `--cache` | `--gcmode` | Notes                           |
| ------------------------ | --------- | ---------- | ------------------------------- |
| Validator (synced)       | 4096+     | `full`     | Fast state access               |
| Validator (initial sync) | 8192+     | `full`     | Faster initial sync             |
| Full node                | 2048      | `full`     | Balanced performance            |
| Archive node             | 8192+     | `archive`  | No pruning, large disk required |

### Database Engine Selection

The `--db.engine` flag selects the underlying key-value store:

* **`pebble`** (default): Modern, fast, better compression
* **`leveldb`**: Legacy, stable, compatible with older databases

Pebble is recommended for new deployments.

### Garbage Collection and Pruning

The `--gcmode` flag controls state pruning behavior:

* **`full`** (default): Prunes old state tries, keeps recent state only
* **`archive`**: Keeps all historical state without pruning (requires TBs of disk)

## Common Configuration Patterns

### Validator Node

```bash theme={null}
gstable --mainnet \
  --mine \
  --nodekey /path/to/nodekey \
  --syncmode full \
  --datadir /data/gstable \
  --cache 4096 \
  --http \
  --http.addr 127.0.0.1 \
  --http.port 8545 \
  --http.api eth,net,web3 \
  --port 30303 \
  --maxpeers 50
```

* `--mine` enables block production
* `--nodekey` specifies the validator’s operational key (also used as etherbase in Anzeon)
* RPC is bound to localhost for security
* Validators must use `--syncmode full`

### Public RPC Node

```bash theme={null}
gstable --mainnet \
  --syncmode snap \
  --datadir /data/gstable \
  --cache 2048 \
  --http \
  --http.addr 0.0.0.0 \
  --http.port 8545 \
  --http.api eth,net,web3 \
  --http.corsdomain "*" \
  --http.vhosts "*" \
  --ws \
  --ws.addr 0.0.0.0 \
  --ws.port 8546 \
  --ws.api eth,net,web3 \
  --maxpeers 100
```

* `--syncmode snap` allowed since this is not a validator
* Bound to `0.0.0.0` for public access
* Only safe APIs exposed (`eth`, `net`, `web3`)

### Development Node

```bash theme={null}
gstable --dev \
  --dev.period 1 \
  --datadir /tmp/gstable-dev \
  --http \
  --http.addr 127.0.0.1 \
  --http.api eth,net,web3,personal,debug,admin \
  --allow-insecure-unlock
```

* `--dev` creates a temporary development network with pre-funded accounts
* `--dev.period 1` produces a block every second
* All APIs enabled for debugging
* `--allow-insecure-unlock` allows HTTP account unlocking (development only)

### Archive Node

```bash theme={null}
gstable --mainnet \
  --syncmode full \
  --gcmode archive \
  --datadir /data/gstable-archive \
  --cache 8192 \
  --http \
  --http.addr 127.0.0.1 \
  --http.api eth,net,web3,debug,trace \
  --maxpeers 50
```

* `--gcmode archive` disables state pruning
* `debug` and `trace` APIs are useful for analysis
* Requires significant disk space (multiple TBs)

## Configuration Files

While command-line flags are the primary configuration method, TOML configuration files are useful for managing complex deployments.

### TOML Configuration Files

To export the current node configuration to a TOML file:

```bash theme={null}
gstable dumpconfig > config.toml
```

Edit the generated file and load it with the `--config` flag:

```bash theme={null}
gstable --config config.toml
```

Example TOML sections:

```toml theme={null}
[Eth]
NetworkId = 8282
SyncMode = "full"
NoPruning = false

[Eth.Miner]
GasCeil = 105000000

[Node]
DataDir = "/data/gstable"
HTTPHost = "0.0.0.0"
HTTPPort = 8545
HTTPModules = ["eth", "net", "web3"]
WSHost = "0.0.0.0"
WSPort = 8546
WSModules = ["eth", "net", "web3"]
IPCPath = "gstable.ipc"

[Node.P2P]
MaxPeers = 100
ListenAddr = ":30303"
StaticNodes = []
TrustedNodes = []
```

**Configuration precedence**: Command-line flags > TOML file settings > Defaults

### Genesis Configuration

For custom networks, the genesis configuration is provided as JSON and loaded using the `gstable init` command:

```bash theme={null}
gstable init /path/to/genesis.json --datadir /path/to/datadir
```

For detailed information on the genesis file structure, see [Genesis Setup and Network Initialization](/en/getting-started/2.3-genesis-setup-and-network-initialization).