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:

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:

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:

# 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: Full list of CLI flags

• Fakenet: Local development network

• Consensus: How Lachesis aBFT works

• Transaction Lifecycle: End-to-end transaction flow