# Node Overview

### Introduction

Running an OPN node allows you to directly interact with the blockchain, validate transactions, and contribute to network decentralization. This guide covers everything you need to know about operating nodes on OPN Chain.

### Node Types

#### 1. Full Node

Full nodes maintain a complete copy of recent blockchain data and can serve RPC requests.

**Characteristics:**

* Stores recent blockchain history (configurable)
* Can validate all transactions
* Serves RPC/API requests
* Default pruning keeps \~100,000 blocks
* Storage: \~1.5TB

**Use Cases:**

* DApp backends
* Personal use
* Development
* Light validator operations

#### 2. Archive Node

Archive nodes store the complete history of all states and transactions.

**Characteristics:**

* Complete historical data
* Can query any past state
* No pruning
* Storage: \~3TB and growing
* Higher RAM requirements

**Use Cases:**

* Block explorers
* Analytics platforms
* Historical data queries
* Research and analysis

#### 3. Validator Node

Validator nodes participate in consensus and produce blocks.

**Characteristics:**

* Requires staking OPN tokens
* Participates in consensus
* Earns rewards
* Higher uptime requirements
* Needs reliable infrastructure

**Use Cases:**

* Earning staking rewards
* Securing the network
* Governance participation

#### 4. Light Node (Planned)

Light nodes will store only block headers and request data as needed.

**Characteristics:**

* Minimal storage (<1GB)
* Cannot serve others
* Relies on full nodes
* Fast sync

**Use Cases:**

* Wallets
* Simple verification
* Resource-constrained environments

### Quick Comparison

| Feature            | Full Node | Archive Node | Validator Node |
| ------------------ | --------- | ------------ | -------------- |
| Storage Required   | \~1.5TB   | \~3TB        | \~1.5TB        |
| RAM Required       | 16GB      | 32GB         | 16GB           |
| Can Validate TXs   | ✅         | ✅            | ✅              |
| Historical Queries | Limited   | ✅            | Limited        |
| Earns Rewards      | ❌         | ❌            | ✅              |
| Produces Blocks    | ❌         | ❌            | ✅              |
| Setup Complexity   | Medium    | Medium       | High           |

### Why Run a Node?

#### Benefits

1. **Independence**
   * No reliance on third-party services
   * Direct blockchain access
   * Enhanced privacy
2. **Performance**
   * Lower latency
   * No rate limits
   * Custom configuration
3. **Support Network**
   * Increase decentralization
   * Improve network resilience
   * Contribute to ecosystem
4. **Earn Rewards** (Validators)
   * Staking rewards
   * Transaction fees
   * Governance participation

#### Considerations

1. **Resources**
   * Hardware costs
   * Bandwidth usage
   * Electricity costs
   * Maintenance time
2. **Technical Knowledge**
   * Linux administration
   * Network configuration
   * Security practices
   * Troubleshooting skills
3. **Reliability Requirements**
   * Uptime monitoring
   * Backup strategies
   * Update management
   * Security updates

### Node Architecture

```
┌─────────────────────────────────────┐
│         JSON-RPC API Layer          │
│    (HTTP/WebSocket Endpoints)       │
├─────────────────────────────────────┤
│         Application Layer           │
│   (EVM, Transaction Processing)     │
├─────────────────────────────────────┤
│         Consensus Layer             │
│      (Tendermint BFT)              │
├─────────────────────────────────────┤
│          P2P Network               │
│     (Peer Communication)           │
├─────────────────────────────────────┤
│         Storage Layer              │
│    (LevelDB/RocksDB)              │
└─────────────────────────────────────┘
```

### Key Components

#### 1. Tendermint Core

* Handles consensus
* Manages P2P networking
* Produces blocks
* Ensures Byzantine fault tolerance

#### 2. Application Layer

* Processes transactions
* Manages state
* Executes smart contracts
* Handles queries

#### 3. Storage Backend

* Stores blockchain data
* Manages state database
* Handles pruning
* Provides query interface

#### 4. RPC Server

* Serves API requests
* WebSocket subscriptions
* Rate limiting
* Request routing

### Network Topology

```
                    ┌─────────────┐
                    │ Seed Nodes  │
                    └──────┬──────┘
                           │
        ┌──────────────────┼──────────────────┐
        │                  │                  │
   ┌────▼────┐       ┌────▼────┐       ┌────▼────┐
   │Validator│       │Validator│       │Validator│
   │  Node   │◄─────►│  Node   │◄─────►│  Node   │
   └────┬────┘       └────┬────┘       └────┬────┘
        │                  │                  │
        └──────────┬───────┴───────┬──────────┘
                   │               │
              ┌────▼────┐     ┌────▼────┐
              │Full Node│     │Full Node│
              └────┬────┘     └────┬────┘
                   │               │
              ┌────▼────┐     ┌────▼────┐
              │RPC Node │     │RPC Node │
              └─────────┘     └─────────┘
```

### Operational Requirements

#### Network Requirements

| Requirement  | Minimum  | Recommended |
| ------------ | -------- | ----------- |
| Bandwidth    | 100 Mbps | 1 Gbps      |
| Monthly Data | 2 TB     | Unlimited   |
| Latency      | < 100ms  | < 50ms      |
| Packet Loss  | < 0.1%   | 0%          |

#### Uptime Requirements

| Node Type    | Required Uptime | Penalties           |
| ------------ | --------------- | ------------------- |
| Full Node    | None            | None                |
| Archive Node | 95%+            | Service degradation |
| Validator    | 99%+            | Slashing risk       |

#### Security Requirements

1. **Firewall Configuration**
   * Only expose necessary ports
   * Implement DDoS protection
   * Regular security updates
2. **Key Management**
   * Secure key storage
   * Regular backups
   * Access controls
3. **Monitoring**
   * Real-time alerts
   * Performance metrics
   * Security monitoring

### Getting Started

#### Prerequisites Check

```bash
# Check system resources
df -h          # Disk space
free -h        # RAM
nproc          # CPU cores
uname -a       # OS version

# Check network
ping -c 4 testnet-rpc.iopn.tech
curl -s https://testnet-rpc.iopn.tech | jq '.'
```

#### Quick Start Options

1. **Binary Installation** (Easiest)

   ```bash
   wget https://github.com/
   chmod +x opn-node
   ./opn-node init
   ```
2. **Docker** (Recommended)

   ```bash
   docker run -d \
     --name opn-node \
     -p 26656:26656 \
     -p 26657:26657 \
     -v opn-data:/root/.opn \
     opnchain/node:latest
   ```
3. **Build from Source** (Advanced)

   ```bash
   git clone https://github.com/opn/opn-chain
   cd opn-chain
   make install
   ```

### Choosing Node Configuration

#### Decision Tree

```
Do you need historical data?
├─ Yes → Archive Node
└─ No
   └─ Do you want to earn rewards?
      ├─ Yes → Validator Node
      └─ No
         └─ Do you need high availability?
            ├─ Yes → Multiple Full Nodes
            └─ No → Single Full Node
```

#### Configuration Examples

**Development Node:**

```toml
# Aggressive pruning for development
pruning = "everything"
pruning-keep-recent = "100"
pruning-interval = "10"
```

**Production Full Node:**

```toml
# Balanced configuration
pruning = "default"
pruning-keep-recent = "100000"
pruning-interval = "1000"
```

**Archive Node:**

```toml
# No pruning
pruning = "nothing"
index-events = ["tx.hash", "tx.height"]
```

### Monitoring Your Node

#### Key Metrics

1. **Node Health**

   ```bash
   curl localhost:26657/health
   ```
2. **Sync Status**

   ```bash
   curl localhost:26657/status | jq '.result.sync_info'
   ```
3. **Peer Count**

   ```bash
   curl localhost:26657/net_info | jq '.result.n_peers'
   ```

#### Monitoring Stack

```yaml
# docker-compose.yml
services:
  prometheus:
    image: prom/prometheus
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
      
  grafana:
    image: grafana/grafana
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin
```

### Common Operations

#### Starting Your Node

```bash
# Start with systemd
sudo systemctl start opn-node

# Start manually
opn-node start --home ~/.opn

# Start with specific config
opn-node start --p2p.seeds "node1@ip:26656,node2@ip:26656"
```

#### Checking Sync Progress

```bash
#!/bin/bash
while true; do
  CURRENT=$(curl -s localhost:26657/status | jq -r '.result.sync_info.latest_block_height')
  NETWORK=$(curl -s https://testnet-rpc.iopn.tech/status | jq -r '.result.sync_info.latest_block_height')
  BEHIND=$((NETWORK - CURRENT))
  echo "Current: $CURRENT | Network: $NETWORK | Behind: $BEHIND blocks"
  sleep 5
done
```

#### Backing Up

```bash
# Backup keys
cp ~/.opn/config/node_key.json ./backup/
cp ~/.opn/config/priv_validator_key.json ./backup/

# Backup data (stop node first)
systemctl stop opn-node
tar -czf opn-backup-$(date +%Y%m%d).tar.gz ~/.opn/data
systemctl start opn-node
```

### Troubleshooting

#### Node Won't Sync

1. Check peers:

   ```bash
   curl localhost:26657/net_info
   ```
2. Add more peers:

   ```bash
   opn-node tendermint show-node-id
   # Share your id@ip:26656 with others
   ```
3. Reset state:

   ```bash
   opn-node tendermint unsafe-reset-all
   ```

#### High Resource Usage

1. Enable pruning:

   ```toml
   pruning = "custom"
   pruning-keep-recent = "100"
   pruning-interval = "10"
   ```
2. Limit peers:

   ```toml
   max_num_inbound_peers = 20
   max_num_outbound_peers = 10
   ```
3. Reduce cache:

   ```toml
   cache_size = 10000
   ```

### Best Practices

#### Security

1. **Use Firewall**

   ```bash
   sudo ufw allow 26656/tcp  # P2P
   sudo ufw allow 26657/tcp  # RPC (only if needed)
   sudo ufw enable
   ```
2. **Secure Keys**

   ```bash
   chmod 600 ~/.opn/config/*_key.json
   ```
3. **Regular Updates**

   ```bash
   # Check for updates
   curl https://api.github.com/repos/opn/opn-chain/releases/latest
   ```

#### Performance

1. **Use SSD Storage**
   * NVMe preferred
   * RAID not required
   * Regular TRIM
2. **Optimize Database**

   ```toml
   db_backend = "rocksdb"
   db_dir = "data"
   ```
3. **Network Optimization**

   ```toml
   send_rate = 5120000
   recv_rate = 5120000
   ```

***

**Need help?** Join our [Channel](https://discord.gg/iopn) on Discord!


---

# 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://iopn.gitbook.io/iopn/developer-docs/nodes/node-overview.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.