| name | midnight-node:node-architecture |
| description | Midnight node architecture, Substrate runtime, Polkadot SDK, pallets, consensus, AURA, GRANDPA, BEEFY, MMR, ledger storage, ParityDB, transaction lifecycle, ZK proof verification, Cardano integration, partner chains, cNIGHT bridging, transaction filtering, throttle pallet, source layout, epoch, block production, finality, light client, how does the Midnight node produce blocks, what pallets does Midnight use, how do transactions flow through the node, how does Midnight connect to Cardano. |
| version | 0.1.0 |
Node Architecture
The Midnight node is a Substrate-based blockchain client built on Polkadot SDK (polkadot-stable2603) and the Cardano Partner Chain framework (v1.8.1). It produces blocks, finalizes them, verifies ZK proofs, manages ledger state, and bridges to the Cardano mainchain.
Current version: node-1.0.0 (mainnet GA) — runtime spec_version 1_000_000, transaction_version 3. These version identifiers track upstream releases and may change with new Midnight releases.
Source Layout
midnight-node/
├── node/ # Client binary — networking, RPC server, service wiring
├── runtime/ # WASM runtime — pallet composition, runtime API, genesis
├── pallets/ # Custom pallets — Midnight-specific on-chain logic
├── primitives/ # Shared types — block, transaction, address, crypto
├── ledger/ # Custom ledger storage — ParityDB-backed, ZK state
├── res/ # Static resources — chain specs, genesis configs
│ └── cfg/ # Network-specific TOML configuration presets
└── ...
Runtime Pallets (28)
The runtime composes exactly 28 pallets organized by function (the #[frame_support::runtime] block has 28 pallet_index entries at node-1.0.0).
Core / System
| Pallet | Purpose |
|---|
frame_system (System) | Core runtime framework — accounts, events, block context |
pallet_timestamp (Timestamp) | On-chain time via inherent extrinsics |
pallet_preimage (Preimage) | Store and manage preimages for hashed proposals |
pallet_scheduler (Scheduler) | Scheduled dispatch of calls at future blocks |
pallet_migrations (MultiBlockMigrations) | Multi-block runtime storage migrations |
pallet_tx_pause (TxPause) | Pause and resume individual dispatchable calls |
Consensus
| Pallet | Purpose |
|---|
pallet_aura (Aura) | AURA block production — round-robin slot assignment |
pallet_grandpa (Grandpa) | GRANDPA deterministic finality gadget |
pallet_beefy (Beefy) | BEEFY bridge protocol for light client proofs |
pallet_mmr (Mmr) | Merkle Mountain Range for light client state proofs |
pallet_beefy_mmr (BeefyMmrLeaf) | BEEFY MMR leaf construction for light client proofs |
Partner Chains / Session (Cardano Integration)
| Pallet | Purpose |
|---|
pallet_sidechain (Sidechain) | Sidechain registration and cross-chain message handling |
pallet_session_validator_management (SessionCommitteeManagement) | Validator set rotation synced from Cardano mainchain |
pallet_partner_chains_session (Session) | Partner Chains session rotation and committee wiring |
pallet_session (PalletSession) | Stub session pallet — committee writes to CurrentIndex |
pallet_partner_chains_bridge (Bridge) | cNIGHT bridging and cross-chain token transfers |
Midnight-Specific
| Pallet | Purpose |
|---|
pallet_midnight (Midnight) | Core Midnight logic — transaction processing, ZK proof verification, ledger API |
pallet_midnight_system (MidnightSystem) | System-level Midnight operations — epoch transitions, parameter management |
pallet_version (NodeVersion) | On-chain node version tracking and compatibility checks |
pallet_cnight_observation (CNightObservation) | cNIGHT cross-chain observation and validation |
pallet_system_parameters (SystemParameters) | On-chain governance parameters — D-parameter, Terms & Conditions |
pallet_throttle (Throttle) | Per-account transaction rate limiting — max bytes and max transaction count over a rolling block window |
Governance
| Pallet | Purpose |
|---|
pallet_collective (Council) | Council governance body — motions and voting |
pallet_collective (TechnicalCommittee) | Technical committee governance body |
pallet_membership (CouncilMembership) | Manages Council membership set |
pallet_membership (TechnicalCommitteeMembership) | Manages Technical Committee membership set |
pallet_federated_authority (FederatedAuthority) | Two-body federated governance — requires both Council and TechnicalCommittee approval |
pallet_federated_authority_observation (FederatedAuthorityObservation) | Observes and validates federated authority actions |
sp_session_validator_management_query is not a pallet — it is a runtime-API / RPC query crate for session and validator data, so it is not listed in the inventory above.
Full inventory: references/pallet-inventory.md — all 28 pallets with their pallet_index, crate, alias, role (local vs framework), and the key calls/storage of the 8 Midnight-local pallets.
Consensus Mechanism
The Midnight node uses a layered consensus architecture.
┌──────────────────────────────────────────────────────┐
│ Light Clients │
│ BEEFY (ECDSA) + MMR state proofs │
├──────────────────────────────────────────────────────┤
│ Finality │
│ GRANDPA (Ed25519 signatures) │
│ Justification period: 512 blocks │
├──────────────────────────────────────────────────────┤
│ Block Production │
│ AURA (Sr25519, round-robin slots) │
│ Block time: 6 seconds, 300 slots/epoch │
└──────────────────────────────────────────────────────┘
AURA (Block Production)
- Algorithm: Round-robin slot assignment among registered authorities
- Key type: Sr25519
- Block time: 6 seconds per slot
- Epoch length: 300 slots (30 minutes)
GRANDPA (Finality)
- Algorithm: Deterministic finality via Byzantine agreement
- Key type: Ed25519
- Justification period: Every 512 blocks, GRANDPA produces a finality proof
- Behavior: Finalizes chains of blocks, not individual blocks
BEEFY (Bridge Protocol)
- Algorithm: Best effort to extend finality for bridge proofs
- Key type: ECDSA (secp256k1)
- Purpose: Produces compact finality proofs for light clients and cross-chain bridges
MMR (Merkle Mountain Range)
- Purpose: Append-only authenticated data structure for light client state proofs
- Usage: Light clients verify on-chain state without downloading the full chain
Deep dive: references/consensus-and-finality.md — the four-layer stack with exact key types, slot/epoch parameters, the GRANDPA justification period, the SessionKeys struct, and why BEEFY is present as a pallet but not yet wired as a validator session key.
Ledger Storage
The Midnight node maintains a custom ledger separate from the standard Substrate state trie. This ledger stores ZK-specific state including commitment trees, nullifier sets, and contract states.
- Storage engine: Custom ParityDB-based implementation
- Separation: Ledger state is distinct from Substrate's key-value state storage
- Versions: Supports v7 and v8 ledger formats
- Contents: Zswap state roots, contract states, commitment trees, nullifier sets
Transaction Lifecycle
Client Node Runtime
│ │ │
│ author_submitExtrinsic │
│ (send_mn_transaction) │ │
│───────────────────────→│ │
│ │ LedgerApi::apply_transaction()
│ │───────────────────────────→│
│ │ │ ZK proof verification
│ │ │ Nullifier check
│ │ │ Contract state update
│ │ │ Commitment tree update
│ │←───────────────────────────│
│ │ Events emitted │
│ │ (contract actions, │
│ │ ledger events) │
│←───────────────────────│ │
│ Transaction hash │ │
- Submission: Client submits the
send_mn_transaction extrinsic (MidnightCall::send_mn_transaction) via the standard author_submitExtrinsic RPC — there is no RPC method literally named send_mn_transaction
- Pool filtering:
FilteringTransactionPool validates the transaction against CheckCallFilter rules
- Application:
LedgerApi::apply_transaction() processes the transaction in the runtime
- ZK verification: Zero-knowledge proof is verified against the circuit's verification key
- State update: Nullifiers are consumed, commitments are added, contract state is updated
- Events: Runtime events are emitted for contract actions and ledger state changes
Transaction Filtering
The node implements multi-layer transaction filtering to protect against spam and resource exhaustion.
| Layer | Mechanism | Purpose |
|---|
FilteringTransactionPool | Custom transaction pool implementation | Rejects transactions before they enter the pool |
CheckCallFilter | Transaction extension | Validates transaction calls against allow/deny rules |
pallet_throttle | Runtime pallet | Rate-limits each account by both total bytes and transaction count over a rolling block window |
The Throttle pallet enforces, per account, a configurable maximum number of transaction bytes (MaxBytes) and a maximum transaction count (MaxTxs) within a rolling block window (WindowSize), preventing any single account from overwhelming the network. Per-account usage is tracked in AccountUsage as a UsageStats record (bytes_used, txs_used, window_start).
Cardano Integration
The Midnight node connects to the Cardano mainchain through a PostgreSQL database backed by db-sync.
Cardano Node ──→ db-sync ──→ PostgreSQL ←── Midnight Node
(main chain follower)
Key Integration Points
| Feature | Details |
|---|
| Connection | PostgreSQL connection to Cardano db-sync instance |
| cNIGHT bridging | Observes Cardano UTXOs for cNIGHT lock transactions |
| Throughput limits | NIGHT bridge (ICS→Midnight): max 256 transfers/block (BridgeMaxTransfersPerBlock, runtime/src/lib.rs:877). cNIGHT observation: up to 200 Cardano txs/block (DEFAULT_CARDANO_TX_CAPACITY_PER_BLOCK). The 256 limit is the NIGHT bridge's, not a cNIGHT limit |
| Governance sync | Council and TechnicalCommittee membership read from Cardano mainchain UTXOs |
| Validator management | Validator set rotation driven by Cardano epoch transitions |
| Mock mode | use_main_chain_follower_mock=true for development without Cardano |
Deep dive: references/cardano-integration.md — the db-sync follower data sources, cNIGHT observation throughput, the NIGHT bridge limit, Ariadne committee selection, governance-membership sync, and the PostgreSQL SSL modes.
References
| Name | Description | When used |
|---|
references/pallet-inventory.md | All 28 runtime pallets: pallet_index, crate, alias, role, local-vs-framework, and the key calls/storage of the 8 Midnight-local pallets | When identifying which pallet owns a behaviour or auditing the runtime composition |
references/consensus-and-finality.md | AURA / GRANDPA / BEEFY / MMR deep-dive — key types, slot/epoch params, justification period, SessionKeys, and the BEEFY-not-wired status | When reasoning about block production, finality, or light-client proofs |
references/cardano-integration.md | The Cardano partner-chain integration — db-sync follower, cNIGHT observation, NIGHT bridge, Ariadne committee selection, governance sync, SSL modes | When working on cross-chain data flow or the main-chain follower |
Cross-References
midnight-tooling:devnet — Manages the node as part of the local development stackmidnight-node:node-validator — Running a validator: keys, candidacy, committee selection, and block productioncompact-core:compact-transaction-model — Transaction structure and execution model from the Compact language perspectivecore-concepts:architecture — High-level Midnight network architecture and component relationships
