@odatano/nightgate

CAP Plugin - Midnight Blockchain Indexer with OData V4 API

@odatano/nightgate is a self-contained Midnight blockchain indexer packaged as an SAP CAP plugin. It connects directly to a Midnight node over Substrate JSON-RPC WebSocket, normalizes chain data into CAP entities, and exposes it through OData V4 services.

This project integrates with the Midnight Network. For more information about the Midnight Network, please visit their website: Midnight Network.

Midnight Node (local ws://localhost:9944 or remote wss://rpc.preprod.midnight.network/)
    |
    | Substrate RPC / WebSocket
    v
MidnightNodeProvider
    |
    | Catch-up, live sync, retry, reorg detection
    v
Crawler + BlockProcessor
    |
    | Atomic persistence via CAP DB API
    v
SQLite / CAP Database
    |
    | OData V4
    v
NightgateService / NightgateIndexerService / Analytics / Admin

Highlights

Capability	Details
Direct node indexing	Connects over ws:// or wss://; no external indexer required
CAP plugin auto-registration	Registers db/ and srv/ models automatically through cds-plugin.js
Catch-up plus live sync	Indexes historical finalized blocks, then subscribes to new heads
Reorg handling	Detects parent-hash mismatches, rolls back affected data, records ReorgLog
OData API	Blockchain, indexer, analytics, and admin services
Operational endpoints	Health, readiness, liveness, reorg history, Prometheus-style metrics
Wallet sessions	connectWallet / disconnectWallet with encrypted viewing-key storage
Offline mode	CAP app starts even if the node is unreachable

Version 0.1.2 is a read-side first release. Transaction build/sign/submit flows are not yet included.

Quick Start

Preprod (default — no Docker needed)

npm ci
npm run dev

Nightgate defaults to Preprod with the public RPC at wss://rpc.preprod.midnight.network/. No .env or extra config required.

Testnet with local Docker node

npm ci
docker compose -f docker/docker-compose.yml up -d

Create a .env in the repo root:

NIGHTGATE_NETWORK=testnet
NIGHTGATE_NODE_URL=ws://localhost:9944

npm run dev

Use as a CAP plugin

cd my-cap-app
npm install @odatano/nightgate @cap-js/sqlite

Add to package.json:

{
  "cds": {
    "requires": {
      "db": { "kind": "sqlite" },
      "nightgate": { "kind": "nightgate" }
    }
  }
}

Then cds watch. Defaults to Preprod. Override via env vars or CDS config:

Env var	CDS config key	Default
NIGHTGATE_NETWORK	network	preprod
NIGHTGATE_NODE_URL	nodeUrl	wss://rpc.preprod.midnight.network/
NIGHTGATE_CRAWLER_NODE_URL	crawler.nodeUrl	same as nodeUrl

If switching an existing DB to a different network, delete db/midnight.db* first.

Query The API

# Latest blocks
curl "http://localhost:4004/api/v1/nightgate/Blocks?$top=5&$orderby=height desc"

# Indexer health
curl "http://localhost:4004/api/v1/indexer/getHealth()"

# Prometheus-style metrics
curl "http://localhost:4004/api/v1/indexer/getMetrics()"

Services

Service	Path
NightgateService	/api/v1/nightgate
NightgateIndexerService	/api/v1/indexer
NightgateAnalyticsService	/api/v1/analytics
NightgateAdminService	/api/v1/admin

Documentation

• Quickstart Guide: step-by-step from zero to first API call
• Reference: configuration, runtime behavior, full API surface, project structure
• Release 0.1.2: prepared GitHub/npm release notes and publish checklist
• Changelog: list of notable changes by version

Development

npm run dev         # Start with auto-reload
npm run lint        # ESLint
npm run typecheck   # TypeScript check
npm run cds:types   # Regenerate @cds-models
npm test            # Full test suite with coverage

License

Apache-2.0

Links

• ODATANO GitHub
• Midnight Network
• SAP CAP Documentation