# Configuration

Complete reference for all Armchain node (`armnode`) command-line flags. You can also export a config file and customize it. See [Configuration File (TOML)](#configuration-file-toml) at the bottom.

## General

| Flag          | Default      | Description                                                                                                                                                                                                                            |
| ------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--datadir`   | `~/.armnode` | Data directory for databases and keystore                                                                                                                                                                                              |
| `--genesis`   | -            | Path to genesis file (required for joining a network)                                                                                                                                                                                  |
| `--config`    | -            | Path to TOML configuration file                                                                                                                                                                                                        |
| `--fakenet`   | -            | Run as fakenet validator (`n/N` format)                                                                                                                                                                                                |
| `--cache`     | `3600`       | Megabytes of memory allocated for internal caching (minimum 3600)                                                                                                                                                                      |
| `--syncmode`  | `full`       | Blockchain sync mode (`full`, `snap`)                                                                                                                                                                                                  |
| `--gcmode`    | `archive`    | Garbage collection mode (`archive`, `full`, `light`). **Note**: Unlike Geth, Armchain defaults to `archive`. See [Node Types](/node-operators/node-types.md).                                                                          |
| `--db.preset` | `ldb-1`      | Database layout preset (`ldb-1`, `pbl-1`, `legacy-ldb`, `legacy-pbl`). See [Node Types - Database Configuration](/node-operators/node-types.md#database-configuration).                                                                |
| `--nousb`     | `false`      | Disable USB hardware wallet monitoring. **Note**: Hardware wallets (USB/Ledger/Trezor) have not been upgraded to support ML-DSA44 PQC keys. This flag is retained for compatibility but HW wallet signing is not currently functional. |
| `--verbosity` | `3`          | Log verbosity (0=silent, 1=error, 2=warn, 3=info, 4=debug, 5=detail)                                                                                                                                                                   |

## Network (P2P)

| Flag            | Default | Description                                          |
| --------------- | ------- | ---------------------------------------------------- |
| `--port`        | `5050`  | P2P listening port                                   |
| `--maxpeers`    | `50`    | Maximum number of network peers                      |
| `--bootnodes`   | -       | Comma-separated enode URLs for bootstrapping         |
| `--nat`         | `any`   | NAT port mapping (`any`, `none`, `upnp`, `extip:IP`) |
| `--nodiscover`  | `false` | Disable peer discovery                               |
| `--netrestrict` | -       | Restrict network to CIDR ranges                      |

## HTTP JSON-RPC

| Flag                | Default        | Description                                   |
| ------------------- | -------------- | --------------------------------------------- |
| `--http`            | `false`        | Enable HTTP RPC server                        |
| `--http.addr`       | `localhost`    | HTTP RPC listening address                    |
| `--http.port`       | `18545`        | HTTP RPC port                                 |
| `--http.api`        | `eth,net,web3` | Comma-separated API namespaces to expose      |
| `--http.corsdomain` | `""`           | Comma-separated list of allowed CORS domains  |
| `--http.vhosts`     | `localhost`    | Comma-separated list of allowed virtual hosts |

## WebSocket

| Flag           | Default        | Description                              |
| -------------- | -------------- | ---------------------------------------- |
| `--ws`         | `false`        | Enable WebSocket RPC server              |
| `--ws.addr`    | `localhost`    | WebSocket listening address              |
| `--ws.port`    | `18546`        | WebSocket port                           |
| `--ws.api`     | `eth,net,web3` | Comma-separated API namespaces to expose |
| `--ws.origins` | -              | Allowed WebSocket origins                |

## Validator

| Flag                   | Default | Description                                    |
| ---------------------- | ------- | ---------------------------------------------- |
| `--validator.id`       | -       | Validator ID (required for validators)         |
| `--validator.pubkey`   | -       | Validator public key (ML-DSA44 hex)            |
| `--validator.password` | -       | Path to file containing validator key password |

## RPC Limits

| Flag                          | Default    | Description                                  |
| ----------------------------- | ---------- | -------------------------------------------- |
| `--rpc.gascap`                | `50000000` | Gas cap for `eth_call` and `eth_estimateGas` |
| `--rpc.txfeecap`              | `1`        | Transaction fee cap in ARM                   |
| `--rpc.timeout`               | `5s`       | HTTP RPC timeout                             |
| `--rpc.allow-unprotected-txs` | `false`    | Allow non-EIP-155 transactions               |

## Account Management

| Flag                      | Default | Description                                 |
| ------------------------- | ------- | ------------------------------------------- |
| `--allow-insecure-unlock` | `false` | Allow account unlock over HTTP (dangerous!) |
| `--unlock`                | -       | Comma-separated account addresses to unlock |
| `--password`              | -       | Password file for account unlock            |

## Performance Tuning

| Flag               | Default | Description                                                        |
| ------------------ | ------- | ------------------------------------------------------------------ |
| `--cache`          | `3600`  | Memory cache in MB (minimum 3600; increase for better performance) |
| `--cache.database` | -       | Percentage of cache for database                                   |
| `--cache.gc`       | -       | Percentage of cache for trie pruning                               |
| `--maxpeers`       | `50`    | Peer count (more peers = more bandwidth but better connectivity)   |

## Tracing and Debugging

| Flag           | Default | Description              |
| -------------- | ------- | ------------------------ |
| `--tracing`    | `false` | Enable Jaeger tracing    |
| `--verbosity`  | `3`     | Log verbosity level      |
| `--pprof`      | `false` | Enable pprof HTTP server |
| `--pprof.port` | `6060`  | pprof port               |

## API Namespaces

Available namespaces for `--http.api` and `--ws.api`:

| Namespace  | Description                                               |
| ---------- | --------------------------------------------------------- |
| `eth`      | Standard Ethereum API (transactions, blocks, state, logs) |
| `net`      | Network information (version, peer count, listening)      |
| `web3`     | Web3 utilities (client version, SHA3)                     |
| `personal` | Account management (create, unlock, sign)                 |
| `txpool`   | Transaction pool inspection (pending, queued)             |
| `debug`    | Debugging and tracing (trace transaction, stack traces)   |
| `admin`    | Node administration (peers, node info, datadir)           |
| `arm`      | Armchain-specific methods                                 |
| `dag`      | DAG-specific queries (events, epochs)                     |

## Subcommands

```bash
# Account management
armnode account new           # Create a new account
armnode account list          # List all accounts
armnode account import <key>  # Import a private key
armnode account update <addr> # Update account password

# Validator management
armnode validator new         # Create a new ML-DSA44 validator key
armnode validator convert     # Convert account key to validator key

# Console
armnode console               # Start interactive JavaScript console
armnode attach                # Attach to a running node's IPC
armnode js <file>            # Execute a JavaScript file

# Configuration
armnode dumpconfig            # Dump current configuration
armnode checkconfig           # Validate configuration

# Chain data
armnode import <file>         # Import chain data
armnode export <file>         # Export chain data

# Database
armnode db stats              # Database statistics
armnode db compact            # Compact database

# Snapshot
armnode snapshot prune-state  # Prune state data

# Info
armnode version               # Print version information
armnode license               # Display license
```

## Configuration File (TOML)

Export a configuration file and customize it:

```bash
./build/armnode dumpconfig > config.toml
```

Example TOML structure:

```toml
[Node]
DataDir = "/data/armchain"

[Node.P2P]
MaxPeers = 50
ListenAddr = ":5050"
BootstrapNodes = ["enode://...@1.2.3.4:5050"]

[Node.HTTPHost]
Addr = "localhost"
Port = 18545
API = "eth,net,web3,arm"
Cors = "*"

[Emitter]
# Validator configuration
ValidatorID = 1
```

Then start with:

```bash
./build/armnode --config config.toml
```

## Environment Variables

| Variable  | Description                               |
| --------- | ----------------------------------------- |
| `GOPROXY` | Go module proxy (used during build)       |
| `HOME`    | Home directory (default datadir location) |

## Further Reading

* [Node Types and Configurations](/node-operators/node-types.md): GC modes, sync modes, database presets, and resource requirements
* [Fakenet](/node-operators/fakenet.md): Local development network options


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.armchain.org/node-operators/configuration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.