Midnight Network

Midnight Network Infrastructure

Complete guide to running and managing Midnight Network infrastructure.

Infrastructure Overview

| Component | Purpose | Requirements | |-----------|---------|------------| | Full Node | Validate transactions, relay blocks | 4+ CPU, 8GB RAM, 100GB SSD | | Archive Node | Full history storage | 4+ CPU, 16GB RAM, 1TB SSD | | Validator | Produce blocks, consensus | 8+ CPU, 16GB RAM, 100GB SSD, stake | | Indexer | Query API for DApps | 4+ CPU, 8GB RAM, 500GB SSD, v4.3.3 | | Proof Server | Generate ZK proofs | 8+ CPU, 32GB RAM, GPU recommended |

Quick Start

Local Development (Recommended for DApps)

Option 1: midnight-local-dev (Full Local Network)

Provides complete local network with Node, Indexer, Proof Server:

git clone https://github.com/midnightntwrk/midnight-local-dev
cd midnight-local-dev
npm install
npm start

Network ID: undeployed

Services & Ports:

| Service | Port | URL | |---------|------|-----| | Node | 9944 | http://localhost:9944 | | Indexer GraphQL | 8088 | http://localhost:8088/api/v4/graphql | | Indexer WS | 8088 | ws://localhost:8088/api/v4/graphql/ws | | Proof Server | 6300 | http://localhost:6300 |

Docker Images: node 0.24.0, indexer 4.3.3, proof-server 8.0.3

Funding: Use interactive menu to fund wallets with 50,000 tNIGHT each.

Standalone Mode (No Menu)

docker compose -f standalone.yml up -d

Option 2: midnight-wallet-cli

npx midnight-wallet-cli serve

Option 3: midnight-playground

• https://midnight-playground-one.vercel.app/

Full Node Setup

# Using Docker (recommended)
docker run -d \
  --name midnight-node \
  -p 9933:9933 \
  -p 9944:9944 \
  -v midnight-data:/data \
  midnightnetwork/node:v0.24.0 \
  --network testnet-02 \
  --pruning archive

Validator Setup

# See detailed guide below
# Requires staking tokens

docker run -d \
  --name midnight-validator \
  -p 9933:9933 \
  -p 9944:9944 \
  --restart unless-stopped \
  -v validator-data:/data \
  midnightnetwork/node:v0.24.0 \
  --validator \
  --staking 

Indexer Setup

# Using Docker Compose with PostgreSQL
# v4.0.0+ required

docker run -d \
  --name midnight-indexer \
  -p 3100:3100 \
  -e DATABASE_URL=postgresql://postgres:password@db:5432/indexer \
  -e NETWORK=testnet-02 \
  --link midnight-postgres:db \
  midnightnetwork/indexer:v4.3.3

Node Architecture

Node Types

1. Full Node

• Validates all blocks and transactions
• Stores current state
• No historical queries
• Minimum for DApp connection

1. Archive Node

• Full history storage
• Historical state queries
• Recommended for indexer backend

1. Light Client

• Lightweight verification
• For resource-constrained environments
• Trust minimum

Node Ports

| Port | Protocol | Purpose | |------|---------|---------| | 9933 | HTTP | RPC API | | 9944 | WebSocket | Subscriptions | | 9615 | Prometheus | Metrics |

Docker Deployment

Single Node

# docker-compose.yaml
version: '3.8'
services:
  node:
    image: midnightnetwork/node:v0.24.0
    ports:
      - "9933:9933"
      - "9944:9944"
    environment:
      - NETWORK=testnet-02
    volumes:
      - node-data:/data
    restart: unless-stopped

Full Stack (Node + Indexer + PostgreSQL)

version: '3.8'
services:
  node:
    image: midnightnetwork/node:v0.24.0
    ports:
      - "9933:9933"
    environment:
      - NETWORK=testnet-02
    volumes:
      - node-data:/data

  postgres:
    image: postgres:15
    environment:
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: indexer
    volumes:
      - postgres-data:/var/lib/postgresql/data

  indexer:
    image: midnightnetwork/indexer:v4.3.3
    ports:
      - "3100:3100"
    environment:
      - DATABASE_URL=postgresql://postgres:secret@postgres:5432/indexer
      - NETWORK=testnet-02
    depends_on:
      - postgres
      - node

volumes:
  node-data:
  postgres-data:

Production Validator

version: '3.8'
services:
  validator:
    image: midnightnetwork/node:v0.24.0
    ports:
      - "9933:9933"
      - "9944:9944"
    environment:
      - NETWORK=mainnet
      - VALIDATOR_MODE=true
      - STAKING_ADDRESS=
    volumes:
      - validator-keys:/keys
      - validator-data:/data
    restart: unless-stopped
    deploy:
      resources:
        limits:
          memory: 16G

Validator Operations

Requirements

| Role | Stake Required | Hardware | |------|-------------|---------| | Full Validator | TBD | 8+ CPU, 16GB RAM |

Setup Steps

1. Generate Keys

# Generate staking keypair
docker run --rm -v keys:/keys midnightnetwork/node:v0.24.0 \
  keygen --output /keys/stash

1. Stake Tokens

• Transfer NIGHT to stake address
• Delegate to validator (if using pool)

1. Start Validator

docker run -d \
  --name midnight-validator \
  -v keys:/keys \
  -e NETWORK=mainnet \
  -e VALIDATOR_KEY=stash.ss58 \
  midnightnetwork/node:v0.24.0 \
  --validator

1. Monitor

Validator Commands

# Check status
curl -X POST http://localhost:9933 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"validator_key","id":1}'

# Get producing status
curl -X POST http://localhost:9933 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"validator_producing","id":1}'

# Manual key rotation
curl -X POST http://localhost:9933 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"validator_rotate","params":["newKey"],"id":1}'

Indexer Setup (v4.0.0+)

Docker Deployment

# Start PostgreSQL first
docker run -d \
  --name midnight-postgres \
  -e POSTGRES_PASSWORD=secret \
  -e POSTGRES_DB=indexer \
  -v postgres-data:/var/lib/postgresql/data \
  postgres:15

# Start Indexer
docker run -d \
  --name midnight-indexer \
  -p 3100:3100 \
  -e DATABASE_URL=postgresql://postgres:secret@host:5432/indexer \
  -e NETWORK=testnet-02 \
  --link midnight-postgres:db \
  midnightnetwork/indexer:v4.3.3

GraphQL API

Endpoint: http://localhost:3100/graphql

# Query transactions
query {
  transactions(
    first: 10,
    after: "cursor"
  ) {
    edges {
      node {
        id
        hash
        block {
          height
        }
      }
    }
  }
}

# Query contracts
query {
  contracts(filter: { hasCode: true }) {
    nodes {
      address
      codeHash
    }
  }
}

Monitoring

Prometheus Metrics

| Metric | Type | Description | |--------|------|-------------| | midnight_blocks_produced | Counter | Total blocks produced | | midnight_transactions_total | Counter | Total transactions | | midnight_peer_count | Gauge | Connected peers | | midnight_block_height | Gauge | Current height | | midnight_sync_status | Gauge | Syncing (0/1) |

Health Checks

# Node health
curl http://localhost:9933/health

# Indexer health
curl http://localhost:3100/health

# Prometheus metrics
curl http://localhost:9615/metrics

Useful Queries

# Block production rate
rate(midnight_blocks_produced[5m])

# Transaction throughput
rate(midnight_transactions_total[5m])

# Peer count
midnight_peer_count

# Sync progress
midnight_block_height / ignoring (job) (max by (job) (midnight_block_height))

Network Configuration

Networks

| Network | Purpose | Chain ID | RPC URL | Status | |---------|---------|---------|--------|--------| | mainnet | Production | NIGHT | https://rpc.mainnet.midnight.network | Active | | preprod | Testing | preprod | https://rpc.preprod.midnight.network | Active (use this) | | preview | Early Dev | preview | https://rpc.preview.midnight.network | ⛔ Discontinued | | testnet-02 | Integration | testnet-02 | - | ⛔ Discontinued |

⚠️ Important: Both Preview and Testnet-02 are discontinued. Use Preprod for all testing.

Environment Variables

# Node
export MIDNIGHT_NETWORK=preprod
export MIDNIGHT_RPC_PORT=9933
export MIDNIGHT_WS_PORT=9944
export MIDNIGHT_PRUNING=archive

# Indexer
export DATABASE_URL=postgresql://user:pass@host:5432/midnight
export NETWORK=preprod
export PORT=3100

Troubleshooting

Common Issues

Node not syncing:

# Check sync status
curl -X POST http://localhost:9933 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"system_syncStatus","id":1}'

# Check peers
curl -X POST http://localhost:9933 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"system_peers","id":1}'

Indexer not syncing:

# Check indexer logs
docker logs midnight-indexer

# Check database connection
docker exec midnight-indexer psql -U postgres -c "SELECT 1"

Validator not producing:

# Verify keys
ls -la /keys/

# Check stake balance
curl -X POST http://localhost:9933 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"validator_key","id":1}'

Developer Tools Reference

From midnight-awesome-dapps

• midnight-wallet-cli - Terminal wallet + DApp server
• Midnight Local Dev - Local full node
• Midnight Local Playground - Docker dev environment
• Midnight MNN Helm - K8s deployment
• NightGate - SAP CAP plugin
• Pelagos SDK - Go SDK for appchains
• Midnight Live View - Node monitoring

Block Explorers

• Midnight Explorer - TexLabs
• Midnightscan

Resources

Cross Reference Skills

This skill covers infrastructure and operations. For related areas see these skills.

• midnight-concepts — Network architecture, consensus, cryptography
• midnight-compact — Contract development, compilation, local devnet
• midnight-api — Indexer queries, node RPC, proof server integration
• midnight-wallet — DUST generation, wallet state, MCP operations
• midnight-dapp-dev — Frontend deployment, provider configuration
• midnight-expert — Health diagnostics, tool verification, compatibility matrix

Inline References

• Node architecture: references/node-architecture.md
• Node setup guide: references/node-setup.md
• Validator guide: references/validator-guide.md
• Indexer API: references/api-reference.md
• Proof server operations: references/operations.md
• Local devnet: references/local-devnet.md
• Diagnostics: references/diagnostics.md

• Node Documentation
• Full Node Setup
• RPC Node Setup
• Indexer Release Notes
• Node Release Notes

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mzf11125
• Source: mzf11125/midnightagent_skills
• License: MIT
• Homepage: https://github.com/mzf11125/midnightagentskills#readme

Install and usage instructions live in the source repository linked above.