DEV Community: Uroy Nwankwo

The Complete Guide to Running a Midnight Node: Setup, Sync & Monitoring

Uroy Nwankwo — Thu, 21 May 2026 18:53:41 +0000

If you've been building on Midnight or want to participate in the network without trusting third-party infrastructure, run your own full node. This tutorial takes you from a bare Ubuntu/Debian machine to a healthy, synced node, including common failure points such as dropped peers and getting stuck on block 1.

Target audience: Developers and node operators who are comfortable with the Linux command line and Docker.

Prerequisites:

A Ubuntu 22.04 or Debian 12 server (bare metal or VPS)
Docker Engine installed (covered below)
Git installed
A running Cardano-db-sync + PostgreSQL instance (covered in step 1)
Open firewall on port 30333 (P2P)

What you'll have by the end: A full node synced to Midnight's Testnet, with monitoring commands and troubleshooting steps for common issues.

Understanding the node types

Before you spin anything up, it helps to know what you're actually running. Midnight has four node types:

Full node: syncs the chain, validates transactions, and serves real-time state queries. It prunes historical state older than 256 blocks by default. This is what most developers and node operators need.
Archive node: the same as a full node but retains the entire chain history. Required for block explorers or deep historical queries. Uses more disk space.
RPC node: exposes an HTTP/WebSocket API for DApps to interact with the chain programmatically.
Boot node: helps new nodes discover peers. You don't need to run one unless you're contributing to network bootstrapping.

This tutorial focuses on the full node. Where the archive node diverges, this guide calls out the one flag you need to change.

Step 1: Set up Cardano-db-sync and PostgreSQL

Midnight operates as a Cardano Partnerchain. That means your Midnight node needs a live connection to a Cardano-db-sync instance to track relevant scripts on the Cardano blockchain. This is required. Your node will not function without it.

Clone the midnight-node-docker repository

The midnight-node-docker repository contains the official Docker Compose files for the entire stack.

git clone https://github.com/midnightntwrk/midnight-node-docker
cd midnight-node-docker

Install Docker Engine

If Docker isn't already installed:

# Add Docker's official GPG key
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository
echo \
  "deb [arch=$(dpkg --print-architecture) \
  signed-by=/etc/apt/keyrings/docker.asc] \
  https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

Verify the installation:

docker --version
sudo systemctl status docker

You should see Active: active (running) in the status output.

Configure the Cardano-db-sync service

Open compose-partner-chains.yml in an editor:

nano compose-partner-chains.yml

Make the following changes:

Replace all default usernames and passwords with values only you know. Do not leave postgres / password123 in a production or publicly reachable environment.
Comment out the Ogmios service unless you are a block producer who needs it. Find the ogmios: block and add # to the start of each line.
Save the file.

Start Cardano-db-sync

docker compose -f compose-partner-chains.yml up -d

This starts Cardano-db-sync and PostgreSQL as background services.

Verify Cardano-db-sync is syncing

Install the PostgreSQL client if you don't have it:

sudo apt-get install postgresql-client

Connect and run the sync progress query:

psql -h localhost -U your_postgres_user -d cexplorer -p 5432

Inside the PostgreSQL shell:

SELECT 100 * (
    EXTRACT(EPOCH FROM (MAX(time) AT TIME ZONE 'UTC')) -
    EXTRACT(EPOCH FROM (MIN(time) AT TIME ZONE 'UTC'))
) / (
    EXTRACT(EPOCH FROM (NOW() AT TIME ZONE 'UTC')) -
    EXTRACT(EPOCH FROM (MIN(time) AT TIME ZONE 'UTC'))
) AS sync_percent
FROM block;

You'll see a number between 0 and 100. Cardano-db-sync must reach 100% before your Midnight node can operate correctly. On the Preview Testnet this typically takes several hours depending on your hardware and disk IOPS. Grab a coffee.

Tip: You can keep checking sync progress without entering the shell every time:

docker exec -it db-sync-postgres psql -U your_postgres_user \
  -d cexplorer -c \
  "SELECT 100 * (EXTRACT(EPOCH FROM (MAX(time) AT TIME ZONE 'UTC')) - \
  EXTRACT(EPOCH FROM (MIN(time) AT TIME ZONE 'UTC'))) / \
  (EXTRACT(EPOCH FROM (NOW() AT TIME ZONE 'UTC')) - \
  EXTRACT(EPOCH FROM (MIN(time) AT TIME ZONE 'UTC'))) \
  AS sync_percent FROM block;"

Step 2: Resource requirements

Before you start the Midnight node itself, make sure your machine meets the minimum specs. Running an undersized node is the fastest way to end up stuck on block 1 with peers constantly dropping.

Resource	Full node (Preview Testnet)	Archive node (Preview Testnet)
CPU	4 cores	4 cores
Memory	16 GB RAM	16 GB RAM
Storage	40 GB SSD (for Cardano-db-sync) + 20 GB for node data	150 GB+ SSD
Disk IOPS	30,000+	30,000+
Network	Stable connection, port 30333 open	Stable connection, port 30333 open

Storage note: Low-IOPS disks, including spinning HDDs and cheap cloud volumes, often cause sync stalls and peer disconnections. If your node keeps falling behind the chain tip, check your disk I/O before anything else:

iostat -x 1 5

Look at the %util column. If it stays above 80%, your disk is the bottleneck.

Step 3: Configure and start the full node

Check the current node version

Always use the version listed in the compatibility matrix. At the time of writing, the current node version is 0.22.3 on Preview and Preprod.

Create the Docker Compose file

Create a file called compose-midnight-node.yml in your working directory:

nano compose-midnight-node.yml

Paste the following:

version: "3.8"

services:
  midnight-full-node:
    image: midnightnetwork/midnight-node:0.22.3
    container_name: midnight-full-node
    platform: linux/amd64
    restart: unless-stopped
    ports:
      - "30333:30333"
    volumes:
      - midnight-data:/node
    environment:
      MIDNIGHT_NODE_IMAGE: "midnightnetwork/midnight-node:0.22.3"
      POSTGRES_HOST: "your_postgres_host"
      POSTGRES_PORT: "5432"
      POSTGRES_USER: "your_postgres_user"
      POSTGRES_PASSWORD: "your_postgres_password"
      POSTGRES_DB: "cexplorer"
      DB_SYNC_POSTGRES_CONNECTION_STRING: "psql://your_postgres_user:your_postgres_password@your_postgres_host:5432/cexplorer"
      BASE_PATH: "./node/chain/"
      CFG_PRESET: "testnet-02"
    command: >
      --chain=/res/testnet-02/testnetRaw.json
      --no-private-ip

volumes:
  midnight-data:

Replace all placeholder values (your_postgres_host, your_postgres_user, your_postgres_password) with the credentials you set in step 1.

If you want an archive node instead, add --pruning archive to the command block:

    command: >
      --chain=/res/testnet-02/testnetRaw.json
      --pruning archive
      --no-private-ip

Start the node

docker compose -f compose-midnight-node.yml up -d

The node starts in the background. Give it 30–60 seconds to initialize, then check that it's running:

docker ps

You should see midnight-full-node with status Up.

Step 4: Monitor the initial sync

Stream logs in real time

docker logs -f midnight-full-node

During a healthy sync, you'll see lines like:

2024-05-04 12:00:01 ⚙️  Syncing 45.2 bps, target=#187432 (12 peers), best: #8492 (0x1a2b…c3d4), finalized #8448 (0x5e6f…7a8b)

Key things to watch:

bps: blocks per second being synced. A healthy node syncs at several dozen bps during initial sync.
target=#XXXXXX: the current chain tip.
best: #XXXXXX: your local best block. This should climb steadily.
finalized #XXXXXX: the last finalized block. This should trail your best block by a small number.
(N peers): the number of connected peers. You want to see 5 or more.

Monitor block height

To check your current block height at any point without reading the full log stream:

docker logs midnight-full-node 2>&1 | grep "best:" | tail -1

Or query the node's RPC endpoint directly (if you've also started an RPC node):

curl -s -H "Content-Type: application/json" \
  -X POST \
  -d '{"jsonrpc":"2.0","id":1,"method":"chain_getHeader","params":[]}' \
  http://127.0.0.1:9944 | python3 -m json.tool

The number field in the response is the current best block in hex. Convert it:

printf "%d\n" 0x2DB20   # example output: 187168

Check peer count

docker logs midnight-full-node 2>&1 | grep "peers" | tail -5

A healthy node shows 5–50 peers. If you're consistently seeing 0–2 peers, see the troubleshooting section below.

Step 5: Verify your node is synced and healthy

Once you believe your node has caught up, confirm it's genuinely at the chain tip rather than just stopped at a stale block.

Check the sync gap

docker logs midnight-full-node 2>&1 | grep "Syncing\|Idle" | tail -5

When fully synced, the log line changes from Syncing to Idle:

2024-05-04 14:22:01 💤 Idle (14 peers), best: #187432 (0x1a2b…c3d4), finalized #187428 (0x5e6f…7a8b)

Idle means your node is at the tip and waiting for new blocks. The best block number should match (or be within a few blocks of) the Midnight block explorer.

Compare with the network tip

You can check the current network block height against the Midnight block explorer. If your node's best block is within 5–10 blocks of the explorer, you're synced.

Verify P2P port is reachable

From another machine or using a port checking tool:

nc -zv your_server_ip 30333

If the port is closed, your node can't accept inbound peer connections, which limits your peer count and sync speed. Open it in your firewall:

sudo ufw allow 30333/tcp
sudo ufw reload

Step 6: Troubleshooting common issues

Node is stuck on block 1 (or a very low block number)

This is the most common issue reported in the community. There are three usual causes:

1. Cardano-db-sync hasn't finished syncing

Your Midnight node requires a fully synced Cardano-db-sync instance. If sync_percent in PostgreSQL is below 100, your node stalls. Check it with the query from step 1, and wait until it reaches 100%.

2. The PostgreSQL connection string is wrong

Double-check your DB_SYNC_POSTGRES_CONNECTION_STRING environment variable. A common mistake is using localhost as the host when PostgreSQL is running in a different Docker container. Use the actual container name or host IP instead.

Test the connection directly:

psql "psql://your_postgres_user:your_postgres_password@your_postgres_host:5432/cexplorer" \
  -c "SELECT count(*) FROM block;"

If this fails, fix your connection string before restarting the node.

3. Node image version mismatch

Running an outdated node image against the current Testnet causes immediate sync failure. Always verify against the compatibility matrix and pull the latest image:

docker pull midnightnetwork/midnight-node:0.22.3
docker compose -f compose-midnight-node.yml up -d --force-recreate

Peers keep disconnecting

If peer counts keep climbing to 5 and then dropping back to 0, check these items:

1. Port 30333 is not publicly reachable

This is the most common cause. Even if Docker is forwarding the port locally, your firewall or cloud security group might be blocking inbound connections. Peers connect to you on port 30333; if they can't reach it, they time out and disconnect.

Check your firewall:

sudo ufw status

If 30333 isn't listed as ALLOW, add it:

sudo ufw allow 30333/tcp
sudo ufw reload

If you're on a cloud VM (AWS, GCP, DigitalOcean), also check your provider's inbound security group or firewall rules in the web console.

2. The --no-private-ip flag is missing

Without --no-private-ip, your node advertises its private/internal IP address to peers. External peers try to connect to an address they can never reach, fail, and disconnect. Make sure this flag is in your command block.

3. NAT or double-NAT

If your server is behind NAT (common with home servers or some VPS setups), peers can't initiate connections to you. You either need to set up port forwarding at the router level, or use a VPS with a public IP.

4. Disk I/O bottleneck

High disk utilisation causes the node to fall behind processing blocks, which causes peers to consider it unresponsive and drop the connection. Check with:

iostat -x 1 10

Upgrade to an SSD with 30,000+ IOPS if %util is consistently high.

Node crashes or restarts frequently

Check the logs for the last error before restart:

docker logs midnight-full-node 2>&1 | grep -E "ERROR|WARN|panic" | tail -20

Common causes:

Out of memory: check with free -h. If your machine has less than 16 GB RAM, the node may OOM. Add swap as a temporary workaround:

  sudo fallocate -l 8G /swapfile
  sudo chmod 600 /swapfile
  sudo mkswap /swapfile
  sudo swapon /swapfile

Docker volume corruption: rare, but possible after a hard shutdown. Recreate the volume:

  docker compose -f compose-midnight-node.yml down
  docker volume rm midnight-data
  docker compose -f compose-midnight-node.yml up -d

Note: this wipes your sync progress and starts from block 0.

Checking connectivity manually

To confirm your node can actually talk to the network:

# Check if P2P port is listening
ss -tlnp | grep 30333

# Test reachability from outside (run on a different machine)
nc -zv your_server_ip 30333

# Check how many peer connections are currently open
docker exec midnight-full-node ss -tn | grep 30333 | wc -l

Keeping your node up to date

Midnight is in active Testnet development. Node versions update frequently, and running an outdated version will cause your node to stop syncing or get rejected by peers.

Subscribe to the Midnight Discord channel on Discord and watch the release notes for new node versions.

When a new version drops, update like this:

# Pull the new image
docker pull midnightnetwork/midnight-node:NEW_VERSION

# Update the version in your compose file
nano compose-midnight-node.yml
# Change 0.22.3 to NEW_VERSION in both the image: and MIDNIGHT_NODE_IMAGE: lines

# Restart with the new image
docker compose -f compose-midnight-node.yml up -d --force-recreate

What to do next

You now have a full node running, synced, and healthy. From here:

Set up an RPC node: if you want your DApp to talk directly to your own infrastructure instead of a public endpoint, follow the RPC node setup guide.
Explore the DApp quickstart: start building a privacy-preserving DApp on top of the network you're now running: Getting started.
Join the community: the Midnight developer forum and Discord are the best places to ask questions, report issues, and follow network updates.
Share your work: if you write about your node setup or share what you built on top of it, tag @midnightntwrk on X and use #MidnightforDevs.

This tutorial reflects Midnight node v0.22.3 on the Preview/Preprod Testnet. Always check the compatibility matrix before updating your setup.

DUST Sponsorship on Midnight: How One Wallet Pays Fees for Another User's Transaction

Uroy Nwankwo — Fri, 15 May 2026 17:11:45 +0000

DUST sponsorship on Midnight lets a backend wallet pay transaction fees for users who do not have DUST yet. Every transaction on Midnight consumes DUST, a shielded, non-transferable capacity resource generated by holding NIGHT tokens. That design keeps fees predictable and privacy intact, but it creates onboarding friction: a brand-new wallet holds zero DUST. Without DUST, it cannot submit a single transaction, including the first one a user might want to make in your DApp.

DUST cannot be sent from one wallet to another. You cannot airdrop it, and there is no transferDUST() call.
The only way to cover fees for a wallet that has no DUST is through sponsorship. In this flow, a backend wallet with healthy DUST reserves pays the fees on behalf of the user without changing who signed the transaction or who owns its outputs.

Target audience: Developers building DApps on the Midnight network.

Prerequisites:

Familiarity with TypeScript
Basic understanding of the Midnight wallet SDK
A Midnight wallet setup with access to a proof server

Related reading: DUST architecture · Wallet SDK · Getting started

What you'll have by the end: A working model for DUST sponsorship, including the two-phase balancing flow, an Express sponsor service, the ownPublicKey() behavior in sponsored transactions, and the DUST monitoring rules needed to keep the sponsor wallet funded.

What DUST actually is

Before writing a single line of code, it helps to be precise about what you are working with.

DUST is not a token. It does not appear on a block explorer as a transferable asset. Think of it as a capacity resource, like bandwidth, generated continuously from your NIGHT holdings. The Midnight docs describe the analogy well: NIGHT is the solar panel, DUST is the electricity it produces.

A few key parameters on the Preview Testnet set the shape of that lifecycle:

Parameter	Value	What it means
`night_dust_ratio`	5,000,000,000	5 DUST generated per NIGHT held
`generation_decay_rate`	8,267	~1 week to decay from max to zero
`dust_grace_period`	3 hours	Final window after DUST hits zero

The DUST lifecycle moves through four phases:

Generating: DUST accumulates toward a cap proportional to your NIGHT balance.
Constant: DUST sits at its maximum while NIGHT remains unspent.
Decaying: once the backing NIGHT UTXO is spent, DUST decays to zero over roughly one week.
Grace: a 3-hour grace period allows one final transaction even at zero.

This lifecycle is entirely shielded. DUST UTXOs use commitments and nullifiers, just like Zswap. Spending one consumes the old UTXO and creates a new one with the updated value minus the fee.

The sponsorship flow

The SDK splits transaction balancing into independent phases, controlled by the tokenKindsToBalance parameter on balanceUnboundTransaction. This is the mechanism sponsorship relies on.

The flow has three steps:

Step 1: The user balances their own tokens without DUST

The user calls balanceUnboundTransaction and explicitly excludes 'dust' from the tokenKindsToBalance array. This tells the SDK to settle shielded and unshielded inputs/outputs but leave the DUST portion open for someone else to fill.

import { WalletFacade } from '@midnight-ntwrk/wallet-sdk';

// userWallet is a WalletFacade instance, already synced
const transaction = await userWallet.transact(contractCall);

const userRecipe = await userWallet.balanceUnboundTransaction(
  transaction,
  {
    shieldedSecretKeys: userShieldedKeys,
    dustSecretKey: userDustKey,
  },
  {
    ttl: new Date(Date.now() + 30 * 60 * 1000), // 30-minute TTL
    tokenKindsToBalance: ['shielded', 'unshielded'], // 'dust' is deliberately omitted
  }
);

// Sign and finalize the user's portion
const userSigned = await userWallet.signRecipe(
  userRecipe,
  (payload) => userKeystore.signData(payload)
);
const userFinalized = await userWallet.finalizeRecipe(userSigned);

// Send userFinalized to the sponsor service
const response = await fetch('https://your-sponsor-service/sponsor', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ userFinalized }),
});

const { txHash } = await response.json();
console.log(`Transaction confirmed: ${txHash}`);

The tokenKindsToBalance parameter is the key piece here. By leaving 'dust' out, the user is saying: "I'm settling my own tokens, but I'm not covering the fee. The sponsor will." The finalized transaction is complete from the user's perspective but is not yet submittable.

Step 2: The sponsor adds DUST fees

The sponsor service receives userFinalized and calls balanceFinalizedTransaction with tokenKindsToBalance: ['dust']. This time only DUST is balanced. The sponsor is not touching the user's shielded or unshielded tokens.

// sponsorWallet is a WalletFacade instance with healthy DUST reserves
const sponsorRecipe = await sponsorWallet.balanceFinalizedTransaction(
  userFinalized,
  {
    shieldedSecretKeys: sponsorShieldedKeys,
    dustSecretKey: sponsorDustKey,
  },
  {
    ttl: new Date(Date.now() + 30 * 60 * 1000),
    tokenKindsToBalance: ['dust'], // only DUST
  }
);

const sponsorSigned = await sponsorWallet.signRecipe(
  sponsorRecipe,
  (payload) => sponsorKeystore.signData(payload)
);
const sponsorFinalized = await sponsorWallet.finalizeRecipe(sponsorSigned);

Step 3: The sponsor submits

const txHash = await sponsorWallet.submitTransaction(sponsorFinalized);
console.log(`Submitted: ${txHash}`);

The transaction is now fully balanced. The user's tokens are accounted for, the sponsor's DUST covers the fee, and the combined transaction hits the network.

Full sponsor service implementation

Here is a complete Express-based sponsor service you can adapt for production.

// sponsor-service.ts
import express from 'express';
import { WalletFacade } from '@midnight-ntwrk/wallet-sdk';
import type { FinalizedTransaction } from '@midnight-ntwrk/wallet-api';

const app = express();
app.use(express.json({ limit: '1mb' }));

// Sponsor wallet state

let sponsorWallet: WalletFacade;
let sponsorShieldedKeys: { secretKey: Uint8Array };
let sponsorDustKey: { secretKey: Uint8Array };
let sponsorKeystore: { signData: (payload: Uint8Array) => Promise<Uint8Array> };

async function initSponsorWallet(): Promise<void> {
  const seedPhrase = process.env.SPONSOR_SEED_PHRASE;
  if (!seedPhrase) throw new Error('SPONSOR_SEED_PHRASE is required');

  // Initialize the wallet facade with Preview Testnet config
  sponsorWallet = await WalletFacade.create({
    seedPhrase,
    networkId: process.env.NETWORK_ID ?? '0',
    rpcUrl: process.env.RPC_URL ?? 'https://rpc.midnight.network',
    indexerUrl: process.env.INDEXER_URL ?? 'https://indexer.midnight.network',
    proofServerUrl: process.env.PROOF_SERVER_URL ?? 'http://localhost:6300',
  });

  // Wait until the wallet has synced to the chain tip
  await sponsorWallet.waitForSync();

  // Derive keys. These come from your wallet initialization flow.
  sponsorShieldedKeys = { secretKey: sponsorWallet.shieldedSecretKey };
  sponsorDustKey = { secretKey: sponsorWallet.dustSecretKey };
  sponsorKeystore = {
    signData: (payload) => sponsorWallet.signWithUnshieldedKey(payload),
  };

  const state = await sponsorWallet.getState();
  console.log(`Sponsor wallet ready. DUST balance: ${state.dust.available}`);
}

// DUST monitoring

const DUST_LOW_WATERMARK = 100n; // alert threshold in DUST units

async function checkDustLevel(): Promise<void> {
  const state = await sponsorWallet.getState();
  const available = state.dust.available;

  if (available < DUST_LOW_WATERMARK) {
    console.warn(
      `Sponsor DUST low: ${available}. ` +
      `Add NIGHT to the sponsor wallet to regenerate.`
    );
    // In production: trigger a PagerDuty alert, Slack message, etc.
  }
}

// Sponsorship endpoint

app.post('/sponsor', async (req, res) => {
  const { userFinalized } = req.body as { userFinalized: FinalizedTransaction };

  if (!userFinalized) {
    return res.status(400).json({ error: 'userFinalized is required' });
  }

  try {
    await checkDustLevel();

    // Balance only the DUST portion. The user already balanced everything else.
    const sponsorRecipe = await sponsorWallet.balanceFinalizedTransaction(
      userFinalized,
      {
        shieldedSecretKeys: sponsorShieldedKeys,
        dustSecretKey: sponsorDustKey,
      },
      {
        ttl: new Date(Date.now() + 30 * 60 * 1000),
        tokenKindsToBalance: ['dust'],
      }
    );

    const sponsorSigned = await sponsorWallet.signRecipe(
      sponsorRecipe,
      (payload) => sponsorKeystore.signData(payload)
    );
    const sponsorFinalized = await sponsorWallet.finalizeRecipe(sponsorSigned);

    // Submit the fully balanced transaction
    const txHash = await sponsorWallet.submitTransaction(sponsorFinalized);

    res.json({ success: true, txHash });
  } catch (error) {
    console.error('Sponsorship failed:', error);
    res.status(500).json({ success: false, error: String(error) });
  }
});

// Health check 

app.get('/health', async (_req, res) => {
  const state = await sponsorWallet.getState();
  res.json({ dust: String(state.dust.available), synced: state.isSynced });
});

// Startup 

initSponsorWallet()
  .then(() => {
    app.listen(3001, () =>
      console.log('Sponsor service running on port 3001')
    );
  })
  .catch((err) => {
    console.error('Failed to initialize sponsor wallet:', err);
    process.exit(1);
  });

Environment variables:

export SPONSOR_SEED_PHRASE="your twelve word seed phrase here"
export NETWORK_ID="0"                                 # Preview Testnet
export RPC_URL="https://rpc.midnight.network"
export INDEXER_URL="https://indexer.midnight.network"
export PROOF_SERVER_URL="http://localhost:6300"

Install dependencies:

npm install @midnight-ntwrk/wallet-sdk @midnight-ntwrk/wallet-api express
npm install --save-dev @types/express tsx typescript

Run the service:

npx tsx src/sponsor-service.ts

`ownPublicKey()` in sponsored transactions

One question comes up consistently when developers first work with sponsored transactions: whose key does ownPublicKey() return when the sponsor wallet is doing the balancing?

The answer is the prover's key, always. This is by design.

ownPublicKey() reflects whoever generated the ZK proof for the transaction, not whoever paid the DUST fee. In a standard sponsored flow, the user proves their own transaction before sending it to the sponsor, so ownPublicKey() returns the user's coinPublicKey. The sponsor's identity never leaks into the transaction's cryptographic identity.

This matters for three reasons:

Address derivation: outputs from the transaction are owned by the prover's address, not the sponsor's.
UTXO ownership: the wallet that can later spend those outputs is the prover's wallet.
Balance queries: if you are tracking state after the transaction, query the prover's address.

Some advanced architectures use an explicit key override pattern, where a separate prover wallet generates ZK proofs and the sponsor handles only fee payment and submission. In that configuration, the override is active at balance time:

// With key override active on the sponsor wallet:
sponsorWallet.ownPublicKey();
// → returns overrideKeys.coinPublicKey (the prover's key)
// → NOT the sponsor wallet's own coinPublicKey

The key override is useful when you have a dedicated proof-generation service that is separate from your fee-paying backend. The prover wallet handles cryptographic identity and proof generation; the sponsor wallet handles DUST and submission. ownPublicKey() always reflects the prover, regardless of which wallet calls it.

DUST regeneration vs depletion

Understanding the regeneration curve is essential for sizing your sponsor wallet correctly. Once you know the math, operating a sponsor service becomes straightforward.

The regeneration curve

While NIGHT remains unspent, DUST generates toward its cap and stays there. The moment a backing NIGHT UTXO is spent, for example, if the sponsor wallet moves NIGHT to another address, the associated DUST begins decaying. The decay takes roughly one week.

Sizing your sponsor wallet

Variable	Value (Preview Testnet)
DUST generated per NIGHT	5 DUST per generation cycle
Typical fee per transaction	~0.001–0.01 DUST
Decay time (max to zero)	~1 week
Grace period at zero	3 hours

As a rule of thumb: a wallet holding 100 NIGHT can sponsor tens of thousands of transactions before you need to think about replenishment. In practice, the constraint is more likely to be DUST decay from NIGHT movement than raw transaction volume.

Keeping the sponsor wallet healthy

Two practices keep a production sponsor service running smoothly:

Do not move NIGHT unless you need to. Every time you spend a backing NIGHT UTXO, even to consolidate, the associated DUST starts decaying. If you need to move NIGHT, do it during low-traffic periods and ensure the new NIGHT UTXO has time to build up DUST before the old one's decay expires.

Monitor DUST levels actively. The health endpoint in the service above returns the current DUST balance. Hook it up to whatever alerting you use, such as Datadog, PagerDuty, or a simple cron + Slack webhook, and set a low-watermark alert well before you hit the decay phase.

// Simple cron-style monitoring
setInterval(async () => {
  const state = await sponsorWallet.getState();
  const dustAvailable = state.dust.available;

  if (dustAvailable < DUST_LOW_WATERMARK) {
    await sendAlert(`Sponsor DUST at ${dustAvailable}. Replenish NIGHT.`);
  }
}, 5 * 60 * 1000); // check every 5 minutes

Common mistakes

Mistake 1: Including `'dust'` in the user's `tokenKindsToBalance`

// WRONG: fails if the user has no DUST
const recipe = await userWallet.balanceUnboundTransaction(
  transaction,
  keys,
  { tokenKindsToBalance: ['shielded', 'unshielded', 'dust'] }
  //                                                  ^^^^^ user has no DUST
);

The fix: always omit 'dust' from the user's step and let the sponsor add it separately.

Mistake 2: The sponsor re-balances token types the user already settled

// WRONG: causes double-spend errors
const sponsorRecipe = await sponsorWallet.balanceFinalizedTransaction(
  userFinalized,
  keys,
  { tokenKindsToBalance: ['dust', 'shielded', 'unshielded'] }
  //                              ^^^^^^^^^^^^^^^^^^^^^^^^^ already done
);

The fix: the sponsor's tokenKindsToBalance should be ['dust'] only.

Mistake 3: No TTL set

// WRONG: transaction may expire before submission
const recipe = await sponsorWallet.balanceFinalizedTransaction(
  userFinalized,
  keys,
  { tokenKindsToBalance: ['dust'] }
  // missing ttl
);

The fix: always pass a TTL of 15–30 minutes for both the user step and the sponsor step. Without it, network congestion or a slow proof server can leave you with an expired transaction and a consumed DUST UTXO.

Mistake 4: Treating DUST as a transferable token

There is no transferDUST() call. DUST is generated from NIGHT and consumed as a resource. It exists only within the shielded context of the wallet that holds the corresponding NIGHT. The sponsorship flow described above is the only way to cover fees for another wallet.

Summary

Concept	Key point
DUST	Shielded capacity resource, not a token; generated from NIGHT holdings
Cold-start problem	New wallets have zero DUST and cannot submit transactions
`balanceUnboundTransaction`	User balances `['shielded', 'unshielded']` and omits `'dust'`
`balanceFinalizedTransaction`	Sponsor adds `['dust']` only
`tokenKindsToBalance`	Controls which token types each party settles
`ownPublicKey()`	Always returns the prover's key, not the sponsor's
DUST regeneration	Grows while NIGHT is held; decays ~1 week after NIGHT is spent
Grace period	3 hours after DUST hits zero
Production pattern	Express sponsor service + DUST monitoring + TTL on every step

DUST sponsorship solves the onboarding problem: new users can transact from their first session while your backend absorbs the fee cost. Once you understand the two-phase balancing approach, the implementation is straightforward. The operational overhead stays low as long as you monitor your sponsor wallet's DUST levels.

Next steps

You now have the sponsorship pattern and service structure. From here:

Review the DUST architecture guide to understand how DUST generation, decay, and the grace period work.
Use the Wallet SDK reference to wire sponsorship into your own wallet flow.
Join the Midnight developer forum or Discord if you hit implementation issues.

Setting up Midnight on Windows via WSL2: The Complete Guide

Uroy Nwankwo — Fri, 08 May 2026 22:59:21 +0000

Midnight's toolchain runs natively on UNIX systems, Linux and macOS. If you're on Windows, you will need the Windows Subsystem for Linux 2 (WSL2).
This tutorial takes you from a fresh Windows machine to a working Midnight dev environment.

Target audience: Windows developers who want to build on the Midnight network.

Prerequisites:

Windows 10 (version 2004+) or Windows 11
Administrator access
stable internet connection.

What you'll have by the end: A winodws machine setup with a complete development environment for building on the midnight network.

You will set up WSL2, configure Docker Desktop, allocate enough memory for the proof server, install the Compact compiler, and verify everything by deploying the Hello World contract. It also shows which Windows approaches fail, so you can skip the dead ends.

What does not work on Windows

You cannot run the Midnight toolchain natively on Windows. The following approaches all fail:

PowerShell / Command Prompt: the Compact installer script is a POSIX shell script. It will not run.
Windows-native Node.js: even if you install Node.js for Windows, the Compact compiler and proof server depend on Linux binaries. They will not resolve correctly.
Git Bash / Cygwin: these are POSIX compatibility layers, not real Linux environments. The installer may appear to work, but it will produce broken PATH entries and missing binaries at runtime.

The supported Windows setup is WSL2 with a real Linux distribution. Everything after this point assumes you are inside a WSL2 terminal unless explicitly marked [Windows terminal].

Step 1: Install and configure WSL2

[Windows terminal: run PowerShell as Administrator]

wsl --install

This command installs WSL2 and downloads Ubuntu, which is the recommended distribution. Restart your machine when prompted.

After restart, open Ubuntu from the Start menu. The first launch completes the Ubuntu setup and asks you to create a Linux username and password. These credentials are for your WSL2 environment only. They do not need to match your Windows credentials.

Verify WSL2 is active:

wsl --list --verbose

You should see Ubuntu listed with Version 2. If it shows Version 1, upgrade it:

wsl --set-version Ubuntu 2

Step 2: Configure WSL2 memory with `.wslconfig`

This is the step the official docs miss. The Midnight proof server generates zero-knowledge proofs locally, which takes real memory. By default, WSL2 caps memory at 1 GB, so the proof server can run out of memory and crash without much explanation.

You need to create a .wslconfig file in your Windows user profile directory to raise this limit.

[Windows terminal]

Open Notepad (or any text editor) and create the file at C:\Users\<YourUsername>\.wslconfig:

# .wslconfig: WSL2 resource configuration
[wsl2]
memory=8GB          # Allocate 8 GB RAM to WSL2 (minimum 4 GB for proof server)
processors=4        # Number of CPU cores available to WSL2
swap=2GB            # Optional: virtual swap space
localhostForwarding=true

Save the file, then restart WSL2 from a Windows terminal:

wsl --shutdown

Wait 10 seconds, then reopen your Ubuntu terminal. The new memory limit takes effect immediately.

Warning: The proof server can crash with less than 4 GB allocated. 8GB is the safer setting. If your machine has 16 GB of RAM or more, giving WSL2 8GB still leaves enough memory for Windows and a browser.

Step 3: Set up Docker Desktop with the WSL2 backend

The Midnight proof server runs as a Docker container. Docker Desktop must use the WSL2 backend. The Hyper-V backend does not give your WSL2 terminal access to Docker.

Download and install Docker Desktop.
During installation, select Use WSL2 instead of Hyper-V when prompted.
After installation, open Docker Desktop and go to Settings → General. Confirm that Use the WSL2 based engine is checked.
Go to Settings → Resources → WSL Integration. Enable integration for your Ubuntu distribution.
Click Apply & Restart.

Verify Docker is accessible from inside WSL2:

[WSL terminal]

docker --version

You should see output like Docker version 26.x.x, build .... If you see command not found, Docker is not exposed inside WSL yet. Go back to item 4 in this section and make sure WSL integration is enabled for your Ubuntu distro.

Step 4: Install Node.js inside WSL2

The Midnight DApp tooling requires Node.js v22 or later. Install it inside WSL2 with nvm (Node Version Manager). That keeps the version under your user account and avoids sudo headaches.

[WSL terminal]

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

Reload your shell:

source ~/.bashrc

Install and activate Node.js v22:

nvm install 22
nvm use 22
node --version   # should output v22.x.x

Note: Do not install Node.js with apt for this workflow. Ubuntu's apt packages are usually older and do not meet the v22 requirement.

Step 5: Install the Compact compiler

[WSL terminal]

Run the official Compact installer:

curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/midnightntwrk/compact/releases/latest/download/compact-installer.sh | sh

The installer downloads the Compact binary and adds it to your PATH. Reload your shell config so the PATH change takes effect:

source ~/.bashrc
# or, if you use zsh:
source ~/.zshrc

Verify the installation:

compact --version
compact compile --version
which compact

All three commands should return valid output. If compact: command not found appears, the PATH was not updated. Add it manually:

export PATH="$HOME/.compact/bin:$PATH"
echo 'export PATH="$HOME/.compact/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Update to the latest compiler version:

compact update

Warning: If compact update fails with:
Failed to spawn artifact extraction command
No such file or directory (os error 2)
your WSL environment is missing required system tools (for example unzip or tar). Install them before retrying:
sudo apt update
sudo apt install -y unzip tar gzip curl

Install a package manager

The Hello World example later in this tutorial uses yarn. Install it with npm:

npm install -g yarn

Verify it installed:

yarn --version

Note: yarn is optional. You can use npm or pnpm instead.
If you prefer a different package manager, substitute yarn commands
with your preferred equivalent throughout this tutorial
(e.g. npm install instead of yarn install, npm run env:up
instead of yarn env:up).

Step 6: Start the proof server

The proof server generates ZK proofs for your transactions. It runs as a Docker container on port 6300.

[WSL terminal]

Make sure Docker Desktop is running (check your Windows system tray for the Docker icon). Then start the proof server:

docker run -p 6300:6300 midnightntwrk/proof-server:8.0.3 midnight-proof-server -v

This command occupies the terminal while the server runs. Open a second WSL2 terminal window for the next steps. You should see log output ending with something like:

 INFO actix_server::server: starting service: "actix-web-service-0.0.0.0:6300", 
 workers: 4, listening on: 0.0.0.0:6300

That confirms the proof server is running and ready.

Tip: Keep the proof server terminal open while you work. If you close it, any compile or deploy step that needs ZK proofs will hang or fail.

Step 7: Install the Compact VS Code extension

Before opening any contract files, install the Compact VS Code
extension. It provides syntax highlighting and code snippet
completion for .compact files. Without it, VS Code treats
your contract as plain text.

[WSL terminal]

Download the VSIX package:

curl -L -o compact.vsix https://raw.githubusercontent.com/midnight-ntwrk/releases/gh-pages/artifacts/vscode-extension/compact-0.2.13/compact-0.2.13.vsix

Install it in VS Code:

code --install-extension compact.vsix

Alternatively, install it manually through the VS Code UI:

Open VS Code
Go to Extensions (Ctrl+Shift+X)
Click the ... menu at the top right of the Extensions panel
Select Install from VSIX...
Navigate to and select the downloaded compact.vsix file

Verification: Open the Extensions panel and confirm
Compact Language Support appears in your installed extensions list.

Step 8: Deploy the Hello World contract

With the proof server running, verify the full setup by cloning the Hello World example, compiling a Compact smart contract, and deploying it to a local Devnet.

Before cloning the example project, set up a working directory inside your WSL environment. A fresh Ubuntu install starts in your home directory, which is typically empty.

Check your current location:

ls

If nothing meaningful appears, create a directory for your development work:

mkdir -p ~/dev
cd ~/dev

The -p flag makes this safe to run:

It creates parent directories if they do not exist.
It does not fail if the directory already exists.

That means the command works on both fresh and existing setups.

Note: Keep your project inside WSL (for example ~/dev), not in the Windows filesystem (/mnt/c/...). Working in /mnt/c often causes slower file access, permission issues, and strange behavior with Node.js and Docker.

Confirm your location:

pwd

You should see a path like:

/home/<your-username>/dev

Now clone the Hello World example:

[WSL terminal: new window]

git clone https://github.com/midnightntwrk/example-hello-world.git
cd example-hello-world

Fix the `docker-compose.yml` before running

The default docker-compose.yml in the Hello World repo has two
issues that can make yarn env:up fail on a fresh setup.
Open docker-compose.yml and find the proof-server service block.

It currently looks like this:

proof-server:
  image: 'midnightntwrk/proof-server:8.0.3'
  command: ['midnight-proof-server -v']
  ports:
    - '127.0.0.1:6300:6300'
  environment:
    RUST_BACKTRACE: 'full'
  healthcheck:
    test: ['CMD', 'curl', '-f', 'http://localhost:6300/version']
    interval: 10s
    timeout: 5s
    retries: 20
    start_period: 10s

Replace it with:

proof-server:
  image: 'midnightntwrk/proof-server:8.0.3'
  command: ['midnight-proof-server', '-v']
  ports:
    - '127.0.0.1:6300:6300'
  environment:
    RUST_BACKTRACE: 'full'
  healthcheck:
    test: ['CMD-SHELL', 'echo > /dev/tcp/127.0.0.1/6300']
    interval: 10s
    timeout: 5s
    retries: 20
    start_period: 10s

Two things changed:

command: the original passes the entire string as a single executable, which fails silently. The corrected version passes the flag as a separate argument as Docker expects.
healthcheck: the original uses curl to check if the server is ready, but the proof server image is a minimal production image and does not include curl. The replacement uses a TCP socket check via bash's built-in /dev/tcp, which works without any additional tools.

Note: These issues have been reported upstream. See
issue #16 and PR #17.
If the PR has merged by the time you read this, your file may
already have the corrected command. Only apply the changes that
differ from what you see.

Install dependencies:

yarn install

Create the contract file:

touch contracts/hello-world.compact
code . # opens VS Code for the current working directory

Open contracts/hello-world.compact in VS Code and paste the following:

pragma language_version >= 0.22;

export ledger message: Opaque<"string">;

export circuit storeMessage(newMessage: Opaque<"string">): [] {
  message = disclose(newMessage);
}

A quick breakdown of what this contract does:

ledger message declares a public, persistent on-chain state variable that stores a string.
circuit storeMessage defines the logic to update that variable.
newMessage is a private input by default. The disclose() call marks it safe to write to public ledger state. Without it, the compiler rejects the assignment.

Compile the contract. The compact compile command expects paths
relative to the contracts/ directory, so navigate into it first:

cd contracts
compact compile hello-world.compact managed/hello-world.compact

After compilation completes, navigate back to the project root
before running the next commands:

cd ..

Expected output:

Compiling 1 circuits:
  circuit "storeMessage" (k=6, rows=26)

This generates ZK circuits, proving and verifying keys, and TypeScript API bindings in the contracts/managed/ directory.

Start the local Devnet environment. The first run pulls the required Docker images. Run this in the project terminal while the proof server stays open in the other terminal:

yarn env:up

In your second terminal, deploy and run the test:

yarn test:local

A successful run looks like this:

[12:46:12.694] INFO: Wallet sync complete after 23 emissions
[12:46:12.703] INFO: Providers initialized. Ready to test
[12:46:32.347] INFO: Contract deployed at: bba6579743ae23b44301d4a9f8df30dbd5244d63a59d8fbc2c9fc7ea521a04f8

 ✓ Hello World Contract > Deploys the contract   19649ms
 ✓ Hello World Contract > Stores a message        18184ms

Your Midnight dev environment is now working on Windows.

Troubleshooting

Proof server crashes or goes silent

The most common cause is WSL2 running out of memory. The proof server needs at least 4GB, and 8GB is safer for this workflow.

Open .wslconfig and increase the memory value:

[wsl2]
memory=8GB

Then shut down WSL2 from a Windows terminal:

wsl --shutdown

Restart Ubuntu and rerun the proof server.

`docker: command not found` inside WSL

Docker Desktop is installed on Windows, but it is not exposed inside your WSL2 distribution.

Open Docker Desktop and go to Settings → Resources → WSL Integration. Enable your Ubuntu distro, then click Apply & Restart.

After Docker restarts, verify from your WSL terminal:

docker --version
docker ps

`compact: command not found` after installation

The Compact installer added the binary to your PATH, but your current shell session has not picked up the change yet.

Add the Compact binary directory to your PATH and reload your shell config:

export PATH="$HOME/.compact/bin:$PATH"
echo 'export PATH="$HOME/.compact/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Verify the compiler is available:

compact --version
which compact

`compact update` fails with “Failed to spawn artifact extraction command”

This usually means your WSL environment is missing system utilities that the updater needs for extraction, such as unzip, tar, gzip, or curl.

Install the required tools:

sudo apt update
sudo apt install -y unzip tar gzip curl

Verify:

which unzip
which tar

Retry:

compact update

If the update still fails, remove the existing Compact installation:

rm -rf ~/.compact

Then rerun the Compact installer from step 5.

Port 6300 already in use

An earlier proof server container is still running and already owns port 6300.

Find and stop the running container:

docker ps
docker stop <container_id>

If you need to keep the existing container running, start the proof server on another host port and update your app config to match:

docker run -p 6301:6300 midnightntwrk/proof-server:8.0.3 midnight-proof-server -v

`yarn test:local` hangs indefinitely

The proof server is probably not running, or Docker is not accessible from WSL2.

First, confirm the proof server terminal is still open and showing the listening log:

listening on: 0.0.0.0:6300

Then confirm Docker is reachable from WSL2:

docker ps

If docker ps fails or returns command not found, re-check the WSL integration setting in Docker Desktop.

Working `.wslconfig` reference

Save this file at C:\Users\<YourUsername>\.wslconfig:

[wsl2]
# Memory: minimum 4GB for proof server, 8GB recommended
memory=8GB

# CPU cores available to WSL2
processors=4

# Optional swap space
swap=2GB

# Allow localhost forwarding between Windows and WSL2 (needed for Docker port access)
localhostForwarding=true

After saving, always run wsl --shutdown from a Windows terminal and restart Ubuntu for changes to take effect.

Next steps

Your environment is configured and verified. Next:

Read the Compact language reference to understand how to model privacy in smart contracts.
Explore the full examples library for DApps with more complex state and circuit logic.
Join the Midnight developer forum and Discord for community support and announcements.

If you find an outdated step, leave a comment or ask in the Midnight Discord. If you publish your own build notes, tag @midnightntwrk.

DEV Community: Uroy Nwankwo

The Complete Guide to Running a Midnight Node: Setup, Sync & Monitoring

Understanding the node types

Step 1: Set up Cardano-db-sync and PostgreSQL

Clone the midnight-node-docker repository

Install Docker Engine

Configure the Cardano-db-sync service

Start Cardano-db-sync

Verify Cardano-db-sync is syncing

Step 2: Resource requirements

Step 3: Configure and start the full node

Check the current node version

Create the Docker Compose file

Start the node

Step 4: Monitor the initial sync

Stream logs in real time

Monitor block height

Check peer count

Step 5: Verify your node is synced and healthy

Check the sync gap

Compare with the network tip

Verify P2P port is reachable

Step 6: Troubleshooting common issues

Node is stuck on block 1 (or a very low block number)

Peers keep disconnecting

Node crashes or restarts frequently

Checking connectivity manually

Keeping your node up to date

What to do next

DUST Sponsorship on Midnight: How One Wallet Pays Fees for Another User's Transaction

What DUST actually is

The sponsorship flow

Step 1: The user balances their own tokens without DUST

Step 2: The sponsor adds DUST fees

Step 3: The sponsor submits

Full sponsor service implementation

ownPublicKey() in sponsored transactions

DUST regeneration vs depletion

The regeneration curve

Sizing your sponsor wallet

Keeping the sponsor wallet healthy

Common mistakes

Mistake 1: Including 'dust' in the user's tokenKindsToBalance

Mistake 2: The sponsor re-balances token types the user already settled

Mistake 3: No TTL set

Mistake 4: Treating DUST as a transferable token

Summary

Next steps

Setting up Midnight on Windows via WSL2: The Complete Guide

What does not work on Windows

Step 1: Install and configure WSL2

Step 2: Configure WSL2 memory with .wslconfig

Step 3: Set up Docker Desktop with the WSL2 backend

Step 4: Install Node.js inside WSL2

Step 5: Install the Compact compiler

Install a package manager

Step 6: Start the proof server

Step 7: Install the Compact VS Code extension

Step 8: Deploy the Hello World contract

Fix the docker-compose.yml before running

Troubleshooting

Proof server crashes or goes silent

docker: command not found inside WSL

compact: command not found after installation

compact update fails with “Failed to spawn artifact extraction command”

Port 6300 already in use

yarn test:local hangs indefinitely

Working .wslconfig reference

Next steps

`ownPublicKey()` in sponsored transactions

Mistake 1: Including `'dust'` in the user's `tokenKindsToBalance`

Step 2: Configure WSL2 memory with `.wslconfig`

Fix the `docker-compose.yml` before running

`docker: command not found` inside WSL

`compact: command not found` after installation

`compact update` fails with “Failed to spawn artifact extraction command”

`yarn test:local` hangs indefinitely

Working `.wslconfig` reference