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

# Configuration

> Genesis fields, geth command-line flags, and runtime tuning for Quantum Chain.

Quantum Chain is configured through three layers: the **genesis file** (chain rules), **geth command-line flags** (runtime), and **JSON-RPC API admin calls** (live).

## Genesis file

A complete mainnet genesis lives at [`configs/mainnet/genesis.json`](configs/mainnet/genesis.json). The fields specific to Quantum Chain are:

| Field                             | Type       | Required | Notes                                                               |
| --------------------------------- | ---------- | :------: | ------------------------------------------------------------------- |
| `config.chainId`                  | int        |    yes   | `20803` for mainnet                                                 |
| `config.quantumVerificationBlock` | int        |    yes   | Block height at which post-quantum signature verification activates |
| `config.clique.period`            | int        |    yes   | Block time in seconds (mainnet: `15`)                               |
| `config.clique.epoch`             | int        |    yes   | Validator change epoch (mainnet: `30000`)                           |
| `publicKey`                       | hex string |    yes   | Post-quantum public key bound to the genesis block                  |
| `extraData`                       | hex string |    yes   | Encoded list of initial sealers                                     |
| `alloc`                           | map        |    no    | Pre-funded balances                                                 |

Standard Ethereum hard-fork toggles (`homesteadBlock`, `byzantiumBlock`, … `londonBlock`) work as in upstream geth.

## Geth flags

The most common production flags are listed below. Run `geth --help` for the full list.

### Networking

| Flag                           | Default       | Purpose                                  |
| ------------------------------ | ------------- | ---------------------------------------- |
| `--networkid <int>`            | `1`           | Set to `20803` for Quantum Chain mainnet |
| `--datadir <path>`             | `~/.ethereum` | Storage location                         |
| `--syncmode snap\|full\|light` | `snap`        | Snap sync recommended for full nodes     |
| `--port <int>`                 | `30303`       | P2P listen port                          |
| `--bootnodes <enode,...>`      | —             | Override default bootnodes               |
| `--maxpeers <int>`             | `50`          | Peer cap                                 |

### JSON-RPC

| Flag                                 | Default        | Purpose                                          |
| ------------------------------------ | -------------- | ------------------------------------------------ |
| `--http`                             | off            | Enable HTTP RPC                                  |
| `--http.addr <ip>`                   | `127.0.0.1`    | Bind address (use `0.0.0.0` only behind a proxy) |
| `--http.port <int>`                  | `8545`         | HTTP port                                        |
| `--http.api <list>`                  | `eth,net,web3` | API namespaces                                   |
| `--http.corsdomain <list>`           | —              | Allowed CORS origins                             |
| `--ws`                               | off            | Enable WebSocket RPC                             |
| `--ws.addr`, `--ws.port`, `--ws.api` | —              | WebSocket binding                                |
| `--rpc.gascap <int>`                 | `50000000`     | Gas cap on `eth_call` and gas estimation         |
| `--rpc.txfeecap <float>`             | `1.0`          | Cap on transaction fees in QRC                   |

### Mining (Clique sealer)

| Flag                       | Default      | Purpose                 |
| -------------------------- | ------------ | ----------------------- |
| `--mine`                   | off          | Run as a Clique sealer  |
| `--miner.etherbase <addr>` | —            | Sealer address          |
| `--miner.gaslimit <int>`   | `30000000`   | Block gas target        |
| `--miner.gasprice <int>`   | `1000000000` | Minimum gas price (wei) |

### Account unlocking

| Flag                      | Notes                                                                                      |
| ------------------------- | ------------------------------------------------------------------------------------------ |
| `--unlock <addr>`         | Unlock a keystore account at startup                                                       |
| `--password <file>`       | Path to a passphrase file                                                                  |
| `--allow-insecure-unlock` | Required when HTTP RPC is enabled and accounts are unlocked. **Do not use in production.** |

### Storage and pruning

| Flag                        | Default | Purpose                                       |
| --------------------------- | ------- | --------------------------------------------- |
| `--gcmode archive\|full`    | `full`  | `archive` keeps every state trie node forever |
| `--cache <MB>`              | `1024`  | LRU cache size; raise for archive nodes       |
| `--state.scheme path\|hash` | `hash`  | Path-based pruning is faster but newer        |

### TxPool

| Flag                          | Default      |
| ----------------------------- | ------------ |
| `--txpool.pricelimit <wei>`   | `1000000000` |
| `--txpool.accountslots <int>` | `16`         |
| `--txpool.accountqueue <int>` | `64`         |
| `--txpool.globalslots <int>`  | `5120`       |

## Runtime configuration via JSON-RPC

Some parameters are runtime-tunable through the `admin_*`, `miner_*`, and `debug_*` namespaces:

```javascript theme={null}
// Add a peer
admin.addPeer("enode://abc...@1.2.3.4:30303")

// Adjust mining gas price
miner.setGasPrice(2000000000)

// Adjust mining gas limit
miner.setGasLimit(60000000)
```

These namespaces must be enabled with `--http.api admin,miner,debug` and should never be exposed publicly.

## Recommended profiles

### Validator (Clique sealer)

```bash theme={null}
geth \
  --datadir /var/lib/geth \
  --networkid 20803 \
  --syncmode full \
  --gcmode full \
  --port 30303 \
  --maxpeers 50 \
  --mine \
  --miner.etherbase 0x... \
  --unlock 0x... \
  --password /etc/geth/password \
  --http --http.addr 127.0.0.1 --http.api eth,net,web3 \
  --metrics --metrics.addr 0.0.0.0 --metrics.port 6060
```

Always run validators **without** `--http.addr 0.0.0.0`. Expose only on localhost.

### Public RPC node

```bash theme={null}
geth \
  --datadir /var/lib/geth \
  --networkid 20803 \
  --syncmode snap \
  --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.api eth,net,web3 \
  --rpc.gascap 50000000 \
  --rpc.txfeecap 5
```

Place behind a TLS reverse proxy (nginx, Caddy) and a rate limiter.

### Archive node

```bash theme={null}
geth \
  --datadir /var/lib/geth-archive \
  --networkid 20803 \
  --syncmode full \
  --gcmode archive \
  --cache 8192 \
  --http --http.api eth,net,web3,debug,trace
```

## Where to go next

* [Running a node](/quantum-chain/running-a-node)
* [Networks](/quantum-chain/networks)
* [Troubleshooting](/quantum-chain/troubleshooting)