# Node Types

Armchain supports several node configurations that you can mix and match depending on your needs, whether you're running a local dev node, a public RPC endpoint, or a validator.

## Configuration Dimensions

```
┌─────────────────────────────────────────────────────────────────────────┐
│  Node Configuration Dimensions                                          │
│                                                                         │
│  ┌─────────────────────────┐  ┌─────────────────────────┐              │
│  │  Garbage Collection     │  │  Synchronization        │              │
│  │  Mode (--gcmode)        │  │  Mode (--syncmode)      │              │
│  ├─────────────────────────┤  ├─────────────────────────┤              │
│  │  • archive (default)    │  │  • full (default)       │              │
│  │  • full                 │  │  • snap                 │              │
│  │  • light                │  │                         │              │
│  └─────────────────────────┘  └─────────────────────────┘              │
│                                                                         │
│  ┌─────────────────────────┐  ┌─────────────────────────┐              │
│  │  Validator Role         │  │  Database Preset        │              │
│  │                         │  │  (--db.preset)          │              │
│  ├─────────────────────────┤  ├─────────────────────────┤              │
│  │  • Validator            │  │  • pbl-1 (Pebble)      │              │
│  │    (--validator.id)     │  │  • ldb-1 (LevelDB)     │              │
│  │  • Non-validator        │  │  • legacy-ldb           │              │
│  │    (readonly)           │  │  • legacy-pbl           │              │
│  └─────────────────────────┘  └─────────────────────────┘              │
└─────────────────────────────────────────────────────────────────────────┘
```

> **Key difference from Geth**: Unlike go-ethereum where `full` is the default GC mode, Armchain defaults to `archive` mode.

***

## Garbage Collection Modes

The `--gcmode` flag controls how the node handles historical EVM state data. This is the primary differentiator for storage requirements and historical query capabilities.

### Archive Mode

**Flag**: `--gcmode archive` (**DEFAULT**)

Archive mode preserves all historical state by disabling trie write caching and garbage collection entirely.

```
┌─────────────────────────────────────────────────────────────────────┐
│  Archive Node - State Trie DB                                        │
│                                                                      │
│   Block 1    Block 2    Block 3    ...    Block N                    │
│  ┌───────┐  ┌───────┐  ┌───────┐        ┌───────┐                  │
│  │ State │  │ State │  │ State │        │ State │                  │
│  │ Root  │  │ Root  │  │ Root  │        │ Root  │                  │
│  │   1   │  │   2   │  │   3   │        │   N   │                  │
│  └───┬───┘  └───┬───┘  └───┬───┘        └───┬───┘                  │
│      ▼          ▼          ▼              ▼                          │
│  ALL STATE   ALL STATE   ALL STATE   ALL STATE                      │
│    KEPT       KEPT        KEPT        KEPT                          │
│                                                                      │
│  ✓ Query any historical block state                                  │
│  ✓ eth_call at any block number                                      │
│  ✓ Debug and trace any historical transaction                        │
└─────────────────────────────────────────────────────────────────────┘
```

**Configuration details**:

| Setting             | Value                                       |
| ------------------- | ------------------------------------------- |
| `TrieDirtyDisabled` | `true` - disables trie write caching and GC |
| `GreedyGC`          | `false` - no greedy garbage collection      |

When `TrieDirtyDisabled` is set, every state commit is flushed directly to disk; no state trie is ever garbage-collected.

**Use cases**:

* Block explorers requiring historical state queries
* DeFi analytics platforms
* Debugging and forensic analysis
* RPC providers serving `eth_call` at arbitrary blocks

**Storage characteristics**:

* **Highest storage requirement**: all state preserved
* **Continuous growth**: no data is ever pruned

### Full Mode

**Flag**: `--gcmode full`

Full mode implements greedy garbage collection that prunes old state while keeping recent state accessible.

```
┌─────────────────────────────────────────────────────────────────────┐
│  Full Node - State Trie DB                                           │
│                                                                      │
│  Block N-16  Block N-15  ...  Block N-1  Block N                    │
│  ┌───────┐   ┌───────┐      ┌───────┐   ┌───────┐                  │
│  │ State │   │ State │      │ State │   │ State │                  │
│  │ Root  │   │ Root  │      │ Root  │   │ Root  │                  │
│  └───┬───┘   └───┬───┘      └───┬───┘   └───┬───┘                  │
│      ▼           ▼              ▼           ▼                        │
│   GC QUEUE     KEPT           KEPT        KEPT                      │
│                                                                      │
│  TriesInMemory = 16 (recent tries kept in memory/disk)              │
│                                                                      │
│  ✓ Query recent block state                                          │
│  ✗ Limited historical state access                                   │
│  ✓ Reduced storage footprint                                         │
└─────────────────────────────────────────────────────────────────────┘
```

**Configuration details**:

| Setting             | Value                               |
| ------------------- | ----------------------------------- |
| `TrieDirtyDisabled` | `false` - enable dirty trie caching |
| `GreedyGC`          | `true` - enable greedy GC           |
| `TriesInMemory`     | `16` - keep 16 most recent tries    |

**Garbage collection process**:

The node keeps the 16 most recent state tries in memory. When the current block exceeds `TriesInMemory`, matured singleton nodes are flushed to disk, and older tries are dereferenced (marked for garbage collection). The GC queue processes roots in block-number order, removing all entries below the chosen retention threshold.

**Use cases**:

* Standard network participants
* dApp backends needing recent state
* Staking/validator operations
* General RPC endpoints

**Storage characteristics**:

* **Moderate storage**: old state is pruned
* **Bounded growth**: only recent state retained

### Light Mode

**Flag**: `--gcmode light`

Light mode provides minimal state retention for resource-constrained environments.

> **Important**: Unlike Geth's light client, Armchain's light mode does **not** implement a light client protocol (Ethereum LES). The node still downloads all blocks and events, validates all transactions, and participates in P2P gossip. The "light" designation only refers to more aggressive state pruning behavior, not protocol differences.

**Configuration details**:

| Setting             | Value                                       |
| ------------------- | ------------------------------------------- |
| `TrieDirtyDisabled` | `false`                                     |
| `GreedyGC`          | `false` (but with reduced `TrieDirtyLimit`) |

**Use cases**:

* Development and testing
* Resource-constrained environments
* Non-critical read operations

**Storage characteristics**:

* **Most aggressive pruning**
* **Minimal historical state**
* **Smallest storage footprint**

***

## Synchronization Modes

The `--syncmode` flag controls how the node initially synchronizes with the network.

### Full Sync

**Flag**: `--syncmode full` (**DEFAULT**)

Full synchronization downloads all events and replays all transactions from genesis.

```
┌─────────────────────────────────────────────────────────────────────┐
│  Full Sync Process                                                   │
│                                                                      │
│  Genesis ──▶ Event 1 ──▶ Event 2 ──▶ ... ──▶ Latest Event          │
│     │           │           │                    │                    │
│     ▼           ▼           ▼                    ▼                    │
│  Execute     Execute     Execute              Execute                │
│    Txs         Txs         Txs                  Txs                  │
│     │           │           │                    │                    │
│     ▼           ▼           ▼                    ▼                    │
│  State 0 ──▶ State 1 ──▶ State 2 ──▶ ... ──▶ Current State         │
│                                                                      │
│  • Downloads all DAG events from genesis                             │
│  • Executes all transactions sequentially                            │
│  • Builds complete state history (if archive mode)                   │
│  • Longest sync time but most complete                               │
└─────────────────────────────────────────────────────────────────────┘
```

**Process**:

1. Download events from the DAG
2. Process each event through Lachesis consensus
3. Execute transactions and build state
4. Continue until caught up with the network

The sync state machine tracks progress through stages: snapshot sync (if applicable), EVM snapshot generation, and events processing. Events are only accepted once the node reaches the `ssEvents` stage.

### Snap Sync

**Flag**: `--syncmode snap`

Snapshot synchronization downloads a recent state snapshot and only replays recent history.

```
┌─────────────────────────────────────────────────────────────────────┐
│  Snap Sync Process                                                   │
│                                                                      │
│  PHASE 1: Snapshot Download                                          │
│  ──────────────────────────                                          │
│  Remote peer's State Root @ Epoch N ───download───▶ Local copy      │
│  (accounts + storage)                                                │
│                                                                      │
│  PHASE 2: EVM Snapshot Generation                                    │
│  ────────────────────────────────                                    │
│  Generate local EVM snapshot from downloaded state                   │
│                                                                      │
│  PHASE 3: Catch-up Sync                                              │
│  ──────────────────────                                              │
│  Epoch N ──▶ Events ──▶ ... ──▶ Current                             │
│  (Switches to full sync for recent history)                          │
└─────────────────────────────────────────────────────────────────────┘
```

**Snap sync state machine**:

The handler tracks sync stages (`ssUnknown` → `ssSnaps` → `ssEvmSnapGen` → `ssEvents`) with the following rules:

* Full sync is never allowed while EVM snapshot generation is ongoing
* Snap sync is only possible if explicitly allowed (`AllowSnapsync`) and the node hasn't already transitioned to full sync
* Snap sync is needed when the node doesn't have a state DB for the finalized state root **or** when the epoch start time exceeds 14 days ago
* Once full sync (events stage) is reached, the node never reverts to snap sync

**Benefits**:

* **Faster initial sync**: skip historical transaction execution
* **Reduced bandwidth**: only download state, not full history
* **Quicker time-to-operational**: node becomes useful faster

**Limitations**:

* Cannot query state before the snapshot point
* Requires snap-capable peers
* May need fallback to full sync if snap is unavailable

***

## Validator vs Non-Validator Nodes

### Non-Validator (Readonly) Node

**Launch command**:

```bash
armnode --genesis file.g
```

Non-validator nodes synchronize with the network and validate all data but do not participate in block production.

```
┌─────────────────────────────────────────────────────────────────────┐
│  Non-Validator Node                                                  │
│                                                                      │
│  Network ◄────────────────────────────────▶ Network                 │
│  (Receive Events)                    (Gossip Transactions)           │
│       │                                    ▲                         │
│       ▼                                    │                         │
│  ┌─────────────┐                 ┌─────────────┐                    │
│  │  Validate   │                 │ Transaction │                    │
│  │  Events     │                 │    Pool     │                    │
│  └──────┬──────┘                 └─────────────┘                    │
│         ▼                                                            │
│  ┌─────────────┐                                                    │
│  │  Execute    │                                                    │
│  │    Txs      │                                                    │
│  └──────┬──────┘                                                    │
│         ▼                                                            │
│  ┌─────────────┐                 ┌─────────────┐                    │
│  │ Update      │────────────────▶│  Serve RPC  │                    │
│  │ State DB    │                 │             │                    │
│  └─────────────┘                 └─────────────┘                    │
│                                                                      │
│  ✗ NO event creation                                                 │
│  ✗ NO block production                                               │
│  ✗ NO consensus participation                                        │
│  ✓ Full validation                                                   │
│  ✓ RPC services                                                      │
└─────────────────────────────────────────────────────────────────────┘
```

**Use cases**:

* RPC endpoint providers
* Block explorers
* dApp backends
* Network observers

### Validator Node

**Launch command**:

```bash
armnode --validator.id YOUR_ID --validator.pubkey 0xYOUR_PUBKEY
```

Validator nodes actively participate in consensus by creating events and producing blocks.

```
┌─────────────────────────────────────────────────────────────────────┐
│  Validator Node                                                      │
│                                                                      │
│  Network ◄────────────────────────────────▶ Network                 │
│  (Receive Events)                    (Broadcast Events)              │
│       │                                    ▲                         │
│       ▼                                    │                         │
│  ┌─────────────┐                 ┌─────────────┐                    │
│  │  Validate   │                 │   EMITTER   │◄── KEY UNLOCKED    │
│  │  Events     │                 │ Create Evts │                    │
│  └──────┬──────┘                 └──────┬──────┘                    │
│         ▼                               ▲                            │
│  ┌─────────────┐◄──────────────▶┌─────────────┐                    │
│  │  Lachesis   │                │ Transaction │                    │
│  │  Consensus  │                │    Pool     │                    │
│  └──────┬──────┘                └─────────────┘                    │
│         ▼                                                            │
│  ┌─────────────┐                                                    │
│  │  Execute    │                                                    │
│  │    Txs      │                                                    │
│  └──────┬──────┘                                                    │
│         ▼                                                            │
│  ┌─────────────┐                                                    │
│  │  Produce    │                                                    │
│  │  Blocks     │                                                    │
│  └─────────────┘                                                    │
│                                                                      │
│  ✓ Event creation (Emitter)                                          │
│  ✓ Block production                                                  │
│  ✓ Consensus participation                                           │
│  ✓ Earns rewards                                                     │
└─────────────────────────────────────────────────────────────────────┘
```

**Required configuration**:

| Flag                   | Description                                  |
| ---------------------- | -------------------------------------------- |
| `--validator.id`       | ID of a validator to create events from      |
| `--validator.pubkey`   | Public key (ML-DSA44 hex) of the validator   |
| `--validator.password` | Password to unlock the validator private key |

**Validator key management**:

```bash
# Create new validator key
armnode validator new

# Convert existing account key to validator key
armnode validator convert <account address> <validator pubkey>
```

> **Important**: Validator functionality is independent of GC mode. A validator can run with any GC mode (`archive`, `full`, or `light`), though `full` or `archive` is recommended for reliability.

***

## Database Configuration

### Database Presets

The `--db.preset` flag controls the database layout and engine selection.

| Preset       | Engine  | Description                      |
| ------------ | ------- | -------------------------------- |
| `pbl-1`      | Pebble  | Modern layout, optimized storage |
| `ldb-1`      | LevelDB | Modern layout (**DEFAULT**)      |
| `legacy-ldb` | LevelDB | Legacy layout                    |
| `legacy-pbl` | Pebble  | Legacy layout with Pebble        |

### Storage Layout: ldb-1 (LevelDB)

```
datadir/
├── main/                     # Main database
│   ├── lachesis (C table)    # Consensus data
│   ├── gossip                # Gossip protocol data
│   ├── evm                   # EVM state
│   └── evm-logs (L table)    # Log indices
│
└── epoch-N/                  # Per-epoch databases
    ├── gossip (G table)      # Epoch gossip data
    └── lachesis (L table)    # Epoch consensus data
```

**Runtime cache distribution**:

| Database  | Cache Allocation           |
| --------- | -------------------------- |
| `main`    | 900 MiB (90% of allocated) |
| `epoch-N` | 100 MiB (10% of allocated) |

### Storage Layout: pbl-1 (Pebble)

```
datadir/
├── main/                     # Main consolidated DB
│   ├── lachesis (C table)
│   ├── gossip
│   └── evm
│
├── events/                   # Events database
│   └── gossip/e
│
├── evm-data/                 # EVM state (Pebble DRC)
│   └── evm/M
│
├── evm-logs/                 # Log indices
│
└── epoch-N/                  # Per-epoch (LevelDB)
    ├── gossip (G table)
    └── lachesis (L table)
```

**Runtime cache distribution**:

| Database   | Cache Allocation |
| ---------- | ---------------- |
| `evm-data` | 460 MiB          |
| `main`     | 320 MiB          |
| `evm-logs` | 260 MiB          |
| `events`   | 240 MiB          |
| `epoch-N`  | 100 MiB          |

***

## Resource Requirements

> **Note**: The storage estimates below are reference values from the upstream go-opera network and have **not** been updated for Armchain's \~57× larger ML-DSA44 signature sizes. Actual Armchain storage requirements will be significantly higher. Memory and bandwidth figures are indicative.

### Memory

| Setting             | Value                     |
| ------------------- | ------------------------- |
| Default cache size  | 3,600 MB (`--cache` flag) |
| Minimum cache size  | 3,600 MB                  |
| Constant cache size | 600 MB (always allocated) |

| Component           | Archive         | Full             | Light            |
| ------------------- | --------------- | ---------------- | ---------------- |
| Trie Dirty Limit    | Disabled        | 256 MiB (scaled) | 256 MiB (scaled) |
| EVM Database Cache  | 32 MiB (scaled) | 32 MiB (scaled)  | 32 MiB (scaled)  |
| Snapshot Cache      | 32 MiB (scaled) | 32 MiB (scaled)  | 32 MiB (scaled)  |
| **Recommended RAM** | **8+ GB**       | **4+ GB**        | **2+ GB**        |

### Storage (Reference Only)

> These figures are from the upstream network (Fantom Opera). Armchain's larger signature sizes will substantially increase storage requirements, particularly for events/DAG data and transaction receipts. Exact figures are pending evaluation.

| GC Mode | Reference Estimate | Growth Pattern               |
| ------- | ------------------ | ---------------------------- |
| Archive | 500+ GB            | Continuous (no pruning)      |
| Full    | 200–300 GB         | Bounded (pruned state)       |
| Light   | 150–200 GB         | Minimal (aggressive pruning) |

**Storage components** (reference breakdown):

| Component         | Approximate Size                    |
| ----------------- | ----------------------------------- |
| Events / DAG data | \~100 GB (same for all modes)       |
| EVM state         | Varies by GC mode (main difference) |
| Logs index        | \~50 GB                             |
| Receipts / Txs    | \~30 GB                             |
| Epoch data        | \~20 GB                             |

> **SSD is strongly recommended** for all modes.

### Bandwidth

**Initial sync**:

| Sync Mode | Data Size   | Typical Duration |
| --------- | ----------- | ---------------- |
| Full      | \~200+ GB   | Days to weeks    |
| Snap      | \~50–100 GB | Hours to days    |

**Steady-state**:

| Direction              | Bandwidth                     |
| ---------------------- | ----------------------------- |
| Inbound                | 1–5 Mbps (event/tx gossip)    |
| Outbound               | 1–5 Mbps (serving peers)      |
| Validator (additional) | \~1 Mbps (event broadcasting) |

**Port requirements**:

| Port  | Protocol | Usage                                  |
| ----- | -------- | -------------------------------------- |
| 5050  | TCP/UDP  | P2P (configurable via `--port`)        |
| 18545 | TCP      | HTTP JSON-RPC (if `--http` enabled)    |
| 18546 | TCP      | WebSocket JSON-RPC (if `--ws` enabled) |

***

## Node Selection Guide

### Decision Tree

```
START
  │
  ▼
┌─────────────────────────────────────────┐
│  Need historical state queries?          │
│  (eth_call at old blocks, tracing)       │
└───────────┬─────────────────┬───────────┘
          YES               NO
            │                 │
            ▼                 ▼
      ┌──────────┐   ┌──────────────────────────────┐
      │ ARCHIVE  │   │  Need to validate network?    │
      └──────────┘   │  (not just read)              │
                      └───────────┬──────────┬───────┘
                                YES        NO
                                  │          │
                                  ▼          ▼
                            ┌──────────┐ ┌──────────┐
                            │   FULL   │ │  LIGHT   │
                            └──────────┘ └──────────┘

┌─────────────────────────────────────────┐
│  Fast initial sync needed?               │
└───────────┬─────────────────┬───────────┘
          YES               NO
            │                 │
            ▼                 ▼
      ┌──────────┐     ┌──────────┐
      │ --sync   │     │ --sync   │
      │   snap   │     │   full   │
      └──────────┘     └──────────┘

┌─────────────────────────────────────────┐
│  Participating in consensus?             │
└───────────┬─────────────────┬───────────┘
          YES               NO
            │                 │
            ▼                 ▼
      ┌──────────────┐ ┌──────────────┐
      │ --validator  │ │  (no flags)  │
      │ .id + .pubkey│ │   readonly   │
      └──────────────┘ └──────────────┘
```

### Recommended Configurations

| Use Case        | GC Mode   | Sync Mode | Validator | Command Example                                                 |
| --------------- | --------- | --------- | --------- | --------------------------------------------------------------- |
| Block Explorer  | `archive` | `full`    | No        | `armnode --gcmode archive --genesis file.g`                     |
| RPC Provider    | `archive` | `snap`    | No        | `armnode --gcmode archive --syncmode snap --genesis file.g`     |
| Validator       | `full`    | `full`    | Yes       | `armnode --gcmode full --validator.id ID --validator.pubkey PK` |
| dApp Backend    | `full`    | `snap`    | No        | `armnode --gcmode full --syncmode snap --genesis file.g`        |
| Development     | `light`   | `snap`    | No        | `armnode --gcmode light --syncmode snap --genesis file.g`       |
| Fakenet Testing | `archive` | `full`    | Yes       | `armnode --fakenet 1/1`                                         |

***

## Summary

1. **Garbage Collection Modes** control state retention:
   * `archive` (**default**): All historical state preserved
   * `full`: Recent state with pruning (TriesInMemory = 16)
   * `light`: Minimal state retention
2. **Synchronization Modes** control initial sync behavior:
   * `full` (**default**): Complete history replay from genesis
   * `snap`: State snapshot-based fast sync
3. **Validator vs Non-Validator** determines consensus participation:
   * Validators require key configuration (`--validator.id`, `--validator.pubkey`)
   * Non-validators are read-only (synchronize and serve RPC)
4. **Key Differences from Geth**:
   * Archive mode is the default (not `full`)
   * Light mode is **not** a light client protocol; the node still downloads and validates everything
   * Validator functionality is separate from GC mode

## Further Reading

* [Configuration Reference](/node-operators/configuration.md): Full list of CLI flags
* [Fakenet](/node-operators/fakenet.md): Local development network
* [Consensus](/architecture/consensus.md): How Lachesis aBFT works
* [Transaction Lifecycle](/architecture/transaction-lifecycle.md): End-to-end transaction flow


---

# 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/node-types.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.