DEV Community: Uroy Nwankwo

The Complete Guide to Running a Full 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, running your own full node is the right move. This tutorial takes you from a bare server to a healthy, synced node using the official Midnight node binary and the supporting Cardano infrastructure — Mithril, Cardano-node, Cardano-db-sync, and PostgreSQL — all managed through systemd. Along the way you'll learn how to monitor your sync progress, verify node health, and work through the failure modes that catch most people: dropped peers, getting stuck on block 1, and stale database connections.

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

Prerequisites:

Ubuntu 24.04 LTS (bare metal or VPS) — required; the node binary targets GLIBC 2.39+
A non-root user named midnight with sudo privileges
A stable internet connection with inbound TCP port 30333 open
Outbound HTTPS access

What you'll have by the end: A full node synced to the Midnight network, running via systemd services, with monitoring commands and a tested troubleshooting playbook for common failures.

A note on the Docker repository. Earlier versions of this guide used the midnight-node-docker repository. The official approach has since changed. The current documentation installs native binaries and manages services with systemd. The Docker repository is no longer the official recommended path for running a node.

Understanding the node types

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

Full node: syncs the chain, validates transactions, and provides real-time state queries. It prunes historical state older than 256 blocks by default, making it efficient on disk. This is what most developers and node operators need.
Archive node: identical to a full node but retains the entire chain history. Required for block explorers, historical analytics, or services that query past state at arbitrary heights. Uses substantially more storage.
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 single flag you need to change.

Step 1: Check resource requirements

Before installing anything, confirm your machine meets the minimums. Running an undersized node is the fastest way to end up stuck on block 1 with peers constantly dropping.

The requirements below come directly from the official Midnight documentation:

Requirement	Preview/Preprod Testnet	Cardano Mainnet
OS	Ubuntu 24.04 LTS (64-bit)	Ubuntu 24.04 LTS (64-bit)
Memory	16 GB or more	32 GB or more
CPU cores	4 or more	4 or more
Disk storage	40 GB NVMe SSD (minimum)	320 GB NVMe SSD
Disk IOPS	30,000 IOPS or better	60,000 IOPS or better
Network	Stable 100 Mbps, port 30333 open	Stable 100 Mbps, port 30333 open

A note on GLIBC. The node binary requires GLIBC 2.39 or greater. Ubuntu 24.04 ships with it. Ubuntu 22.04 does not. Check yours:

ldd --version

Avoid HDDs and cheap burstable cloud volumes. Low-IOPS storage causes sync stalls, peer disconnections, and PostgreSQL failures under write load. If your node keeps falling behind the chain tip, check disk I/O before anything else:

iostat -x 1 5

Look at the %util column for your storage device. Sustained values above 80% mean your disk is the bottleneck. Migrate to a faster SSD before continuing.

Step 2: Create the `midnight` user

You can optionally create a non-privileged user to run all node services. Not running blockchain software as root is a security best practice.

sudo adduser midnight
sudo usermod -aG sudo midnight
su - midnight
whoami  # should return: midnight

All remaining steps in this tutorial assume you're operating as the midnight user. Paths like /home/midnight throughout this guide refer to this user's home directory.

Step 3: Set up Cardano node with Mithril

Midnight operates as a Cardano partner chain. Your Midnight node requires a persistent connection to a Cardano-db-sync instance to track relevant scripts on the Cardano blockchain. This is not optional. Your node will stall near block 1 without it.

Syncing Cardano from genesis takes days. This guide uses Mithril to download a cryptographically verified snapshot of the Cardano blockchain, reducing that to roughly 20 minutes.

Install Mithril

Create a working directory and install the Mithril client:

mkdir -p $HOME/tmp/mithril && cd $HOME/tmp/mithril

curl --proto '=https' --tlsv1.2 -sSf \
  https://raw.githubusercontent.com/input-output-hk/mithril/refs/heads/main/mithril-install.sh \
  | sh -s -- -c mithril-client -d unstable -p $(pwd)

Configure Mithril for your network

Set the environment variables for Preview Testnet. For Preprod or Mainnet, use the corresponding values from the Mithril network configurations.

export CARDANO_NETWORK=preview
export AGGREGATOR_ENDPOINT=https://aggregator.pre-release-preview.api.mithril.network/aggregator
export GENESIS_VERIFICATION_KEY=$(wget -q -O - \
  https://raw.githubusercontent.com/input-output-hk/mithril/main/mithril-infra/configuration/pre-release-preview/genesis.vkey)
export ANCILLARY_VERIFICATION_KEY=$(wget -q -O - \
  https://raw.githubusercontent.com/input-output-hk/mithril/main/mithril-infra/configuration/pre-release-preview/ancillary.vkey)
export SNAPSHOT_DIGEST=latest

Download and verify the Cardano snapshot

./mithril-client cardano-db snapshot list
./mithril-client cardano-db snapshot show $SNAPSHOT_DIGEST
./mithril-client cardano-db download --include-ancillary $SNAPSHOT_DIGEST

The Mithril client downloads the snapshot into a db/ directory in the current working directory ($HOME/tmp/mithril/db). You'll move this into place in the next step.

Install Cardano node

Always check the official Cardano node release page and the Midnight compatibility matrix for the current required version. At the time of writing, the required version is 11.0.1.

VERSION="11.0.1"
ARCH="linux-amd64"
URL="https://github.com/IntersectMBO/cardano-node/releases/download/${VERSION}/cardano-node-${VERSION}-${ARCH}.tar.gz"

mkdir -p ~/.local/bin ~/.local/share

# Download binaries and configuration files
curl -L "$URL" | tar -xz -C ~/.local/bin --strip-components=2 ./bin
curl -L "$URL" | tar -xz -C ~/.local/share --strip-components=1 ./share

chmod +x ~/.local/bin/cardano-*

Reload your shell and verify the binary:

source ~/.bashrc
cardano-node --version
# cardano-node 11.0.1 - linux-x86_64 - ghc-9.6

You should see the ~/.local/share directory now contains network config folders: mainnet, preprod, and preview.

Inject the Mithril snapshot and run Cardano node

Create the Cardano data directory and move the snapshot in:

mkdir -p ~/cardano-data
mv ~/tmp/mithril/db/ ~/cardano-data/
ls ~/cardano-data/db  # verify the database exists

Start the Cardano node interactively to confirm it works before creating the systemd service:

cardano-node run \
  --topology ~/.local/share/preview/topology.json \
  --database-path ~/cardano-data/db \
  --socket-path ~/cardano-data/db/node.socket \
  --host-addr 0.0.0.0 \
  --port 3001 \
  --config ~/.local/share/preview/config.json

Once you see the node logging block events, press Ctrl+C and set it up as a systemd service. Create the service file:

sudo vim /etc/systemd/system/cardano-node.service

Paste the following (for Preview; adjust the config and topology paths for Preprod or Mainnet):

[Unit]
Description=Cardano Relay Node
Wants=network-online.target
After=network-online.target

[Service]
User=midnight
Type=simple
WorkingDirectory=/home/midnight/cardano-data
ExecStart=/home/midnight/.local/bin/cardano-node run \
    --topology /home/midnight/.local/share/preview/topology.json \
    --database-path /home/midnight/cardano-data/db \
    --socket-path /home/midnight/cardano-data/db/node.socket \
    --host-addr 0.0.0.0 \
    --port 3001 \
    --config /home/midnight/.local/share/preview/config.json
KillSignal=SIGINT
Restart=always
RestartSec=5
LimitNOFILE=32768

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable cardano-node
sudo systemctl start cardano-node
sudo systemctl status cardano-node

Follow the live logs:

journalctl -fu cardano-node

Check sync progress using cardano-cli. The testnet magic number is 2 for Preview:

export CARDANO_NODE_SOCKET_PATH="$HOME/cardano-data/db/node.socket"
cardano-cli query tip --testnet-magic 2

Example output:

{
    "block": 1253000,
    "epoch": 212,
    "era": "Conway",
    "syncProgress": "99.80"
}

Wait for syncProgress to reach 100 before continuing.

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

Install PostgreSQL 17

sudo apt install curl ca-certificates -y
sudo install -d /usr/share/postgresql-common/pgdg
sudo curl -s -o /usr/share/postgresql-common/pgdg/apt.postgresql.org.asc \
  --fail https://www.postgresql.org/media/keys/ACCC4CF8.asc
sudo sh -c 'echo "deb [signed-by=/usr/share/postgresql-common/pgdg/apt.postgresql.org.asc] \
  https://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" \
  > /etc/apt/sources.list.d/pgdg.list'
sudo apt update && sudo apt -y install postgresql-17 postgresql-server-dev-17

Configure roles and the database

Start the PostgreSQL shell as the admin user:

sudo -i -u postgres psql

Create the midnight database user, grant it privileges, and create the cexplorer database:

CREATE USER midnight WITH PASSWORD 'your_actual_password';
ALTER ROLE midnight WITH SUPERUSER CREATEDB;
CREATE DATABASE cexplorer;
\q

Replace your_actual_password with a strong, unique password only you know.

Configure passwordless authentication

Cardano-db-sync uses a .pgpass file for authentication:

export POSTGRES_PASSWORD='your_actual_password'
export PGPASSFILE="${HOME}/.pgpass"

echo "/var/run/postgresql:5432:cexplorer:midnight:$POSTGRES_PASSWORD" > "$PGPASSFILE"
chmod 0600 "$PGPASSFILE"

Test the connection — it should succeed without a password prompt:

psql -h /var/run/postgresql -U midnight -d cexplorer -c "SELECT current_user; SELECT now();"

PostgreSQL performance tuning

For Mainnet (and good practice on testnets with fast hardware), tune your PostgreSQL configuration. Edit /etc/postgresql/17/main/postgresql.conf and update or uncomment these lines:

shared_buffers = 16GB
maintenance_work_mem = 4GB
max_parallel_maintenance_workers = 4
effective_cache_size = 48GB

Restart PostgreSQL after any config change:

sudo systemctl restart postgresql

Install Cardano-db-sync

The required version is 13.7.1.0. Always verify the current required version against the compatibility matrix before downloading.

cd ~/tmp
curl -L -O https://github.com/IntersectMBO/cardano-db-sync/releases/download/13.7.1.0/cardano-db-sync-13.7.1.0-linux.tar.gz
tar -xzf cardano-db-sync-13.7.1.0-linux.tar.gz

mkdir -p ~/.local/bin
cp bin/* ~/.local/bin/
chmod +x ~/.local/bin/cardano-db-sync*

# Verify
cardano-db-sync --version

Move the schema and download the db-sync config:

mkdir -p ~/cardano-data/
sudo mv ~/tmp/schema ~/cardano-data/

cd ~/cardano-data
curl -O https://book.world.dev.cardano.org/environments/preview/db-sync-config.json

# Update the config to point at the Cardano node's config file
sed -i 's|"NodeConfigFile": "config.json"|"NodeConfigFile": "/home/midnight/.local/share/preview/config.json"|' \
  ~/cardano-data/db-sync-config.json

Start Cardano-db-sync

Test it interactively first:

export PGPASSFILE="${HOME}/.pgpass"

cardano-db-sync \
    --config /home/midnight/cardano-data/db-sync-config.json \
    --socket-path /home/midnight/cardano-data/db/node.socket \
    --schema-dir /home/midnight/cardano-data/schema \
    --state-dir /home/midnight/cardano-data/db-sync-state

It may take 5–20 minutes to initialise. This is normal. Once you see it syncing, press Ctrl+C and create the systemd service:

sudo vim /etc/systemd/system/cardano-db-sync.service

[Unit]
Description=Cardano DB Sync
After=cardano-node.service
Requires=cardano-node.service

[Service]
User=midnight
Type=simple
Environment="PGPASSFILE=/home/midnight/.pgpass"
WorkingDirectory=/home/midnight/cardano-data
ExecStart=/home/midnight/.local/bin/cardano-db-sync \
    --config /home/midnight/cardano-data/db-sync-config.json \
    --socket-path /home/midnight/cardano-data/db/node.socket \
    --schema-dir /home/midnight/cardano-data/schema \
    --state-dir /home/midnight/cardano-data/db-sync-state
KillSignal=SIGINT
Restart=always
RestartSec=10
LimitNOFILE=32768

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable cardano-db-sync
sudo systemctl start cardano-db-sync
sudo systemctl status cardano-db-sync

Monitor Cardano-db-sync sync progress

Follow the logs:

journalctl -u cardano-db-sync -f

Query sync percentage from PostgreSQL:

psql -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;"

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

If you start the Midnight node before db-sync finishes, you'll see this in its logs:

Unable to author block in slot. Failure creating inherent data provider:
'No latest block on chain.' not found.
Possible causes: main chain follower configuration error, db-sync not synced fully,
or data not set on the main chain.

This is the Cardano dependency telling you it's not ready. Wait for sync_percent to reach 100 before proceeding.

Step 5: Install and configure the Midnight node

Create directories and download the binary

Always check the compatibility matrix for the current node version before downloading. At the time of writing, the Preview network uses 1.0.0 (binary release node-0.22.5).

mkdir -p ~/data ~/res ~/.local/bin
mkdir -p ~/tmp && cd ~/tmp

curl -L -O https://github.com/midnightntwrk/midnight-node/releases/download/node-0.22.5/midnight-node-0.22.5-linux-amd64.tar.gz
tar -xvzf midnight-node-0.22.5-linux-amd64.tar.gz

mv ~/tmp/midnight-node ~/.local/bin/
mv ~/tmp/res ~/res

source ~/.bashrc
midnight-node --version

Confirm the chain spec file for your network is present:

ls ~/res/preview/chain-spec-raw.json

Set environment variables

Create an .env file for the PostgreSQL credentials:

cat > ~/.env << 'EOF'
export POSTGRES_HOST="localhost"
export POSTGRES_DB="cexplorer"
export POSTGRES_PORT="5432"
export POSTGRES_USER="midnight"
export POSTGRES_PASSWORD="your_actual_password"
export DB_SYNC_POSTGRES_CONNECTION_STRING="postgresql://midnight:your_actual_password@localhost:5432/cexplorer"
export NODE_NAME="your_node_name"
EOF

source ~/.env
echo $DB_SYNC_POSTGRES_CONNECTION_STRING

Replace your_actual_password and your_node_name with your actual values.

Run the Midnight node

You can start the node interactively first to verify the configuration:

midnight-node \
  --chain /home/midnight/res/preview/chain-spec-raw.json \
  --base-path /home/midnight/data \
  --pool-limit 35 \
  --name $NODE_NAME \
  --no-private-ip

Watch for three things in the output before proceeding:

Postgres connection established — confirms your DB_SYNC_POSTGRES_CONNECTION_STRING is correct.
Best: #0 ... beginning to increment — the node is pulling blocks.
Peer count appearing in the log output — if it stays at 0 peers for more than a few minutes, check your firewall on port 30333.

Once satisfied, press Ctrl+C and set it up as a systemd service.

Create the systemd service

sudo vim /etc/systemd/system/midnight-node.service

[Unit]
Description=Midnight Full Node
Wants=network-online.target
After=network-online.target cardano-db-sync.service
Requires=cardano-db-sync.service

[Service]
User=midnight
Type=simple
EnvironmentFile=/home/midnight/.env
ExecStart=/home/midnight/.local/bin/midnight-node \
    --chain /home/midnight/res/preview/chain-spec-raw.json \
    --base-path /home/midnight/data \
    --pool-limit 35 \
    --name ${NODE_NAME} \
    --no-private-ip
KillSignal=SIGINT
Restart=always
RestartSec=10
LimitNOFILE=32768

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable midnight-node
sudo systemctl start midnight-node
sudo systemctl status midnight-node

Follow the logs:

journalctl -fu midnight-node

Step 6: Monitor the initial sync

Reading the sync log output

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

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

Here's what each field means:

bps: blocks per second. Several dozen during initial sync is healthy. Single-digit bps suggests your disk or CPU is the bottleneck.
target=#XXXXXX: the current chain tip your peers are reporting.
best: #XXXXXX: your local best block. Should climb steadily.
finalized #XXXXXX: the last finalised block, trailing your best by a small number.
(N peers): connected peers. You want 5 or more.

When your node finishes syncing, the log line changes from Syncing to Idle:

2026-06-16 14:22:01 💤 Idle (14 peers), best: #187432 (0x1a2b…c3d4), finalized #187428 (0x5e6f…7a8b)

Idle means you're at the tip and waiting for new blocks.

Check sync state via RPC

The Midnight node exposes a JSON-RPC interface on port 9944. Query sync state directly:

curl -s -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"system_syncState","params":[],"id":1}' \
  http://localhost:9944 | jq '.result'

Example output:

{
  "startingBlock": 0,
  "currentBlock": 142560,
  "highestBlock": 187432
}

When currentBlock equals highestBlock, you're synced. Check peer connectivity at the same time:

curl -s -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"system_health","params":[],"id":1}' \
  http://localhost:9944 | jq '.result'

A healthy, synced node returns:

{
  "peers": 14,
  "isSyncing": false,
  "shouldHavePeers": true
}

isSyncing: false with peers greater than zero means you're at the tip and connected. If peers is persistently 0 or 1, see the troubleshooting section.

Monitor block height on a loop

Save this as monitor-height.sh for reuse throughout operations:

cat > ~/monitor-height.sh << 'EOF'
#!/usr/bin/env bash
set -euo pipefail

RPC="${RPC:-http://localhost:9944}"
INTERVAL="${INTERVAL:-30}"

while true; do
  result=$(curl -fsS \
    -H "Content-Type: application/json" \
    -d '{"jsonrpc":"2.0","method":"system_syncState","params":[],"id":1}' \
    "$RPC" 2>/dev/null | jq -r '
      .result |
      "current=\(.currentBlock)  target=\(.highestBlock)  lag=\(.highestBlock - .currentBlock)"
    ') || result="RPC unreachable"
  printf '%s  %s\n' "$(date -u +"%H:%M:%SZ")" "$result"
  sleep "$INTERVAL"
done
EOF
chmod +x ~/monitor-height.sh

Run it:

~/monitor-height.sh

A healthy syncing node shows a rising current and a shrinking lag. A fully synced node shows lag=0 and holds there.

Step 7: Verify your node is synced and healthy

Once the node reports Idle or lag=0, run through this verification checklist.

All services running:

sudo systemctl status cardano-node cardano-db-sync midnight-node

Node has peers and is not syncing:

curl -s -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"system_health","params":[],"id":1}' \
  http://localhost:9944 | jq '.result'

P2P port is listening:

ss -ltnp | grep ':30333'

No repeated errors in the last 30 minutes:

journalctl -u midnight-node --since "30 minutes ago" \
  | grep -Ei 'error|panic|disconnect' \
  || echo "No errors found."

Confirm binary version:

midnight-node --version

A clean bill of health is: all three services active, isSyncing: false, peer count above zero, and no repeated panics or database errors.

Step 8: Troubleshooting common issues

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

This is the most commonly reported issue. There are four causes, in order of likelihood.

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

Your Midnight node requires a fully synced Cardano-db-sync instance. Run the sync percentage query from Step 4. If it's below 100, wait. The "Unable to author block" log message in your Midnight node's journal is the confirmation of this state.

2. PostgreSQL connection string is wrong

A common mistake is using localhost in the connection string when PostgreSQL is configured to use a Unix socket. The db-sync setup in this guide uses the socket path /var/run/postgresql. Confirm your connection string is correct:

echo $DB_SYNC_POSTGRES_CONNECTION_STRING

Test the connection directly:

psql -h /var/run/postgresql -U midnight -d cexplorer -c 'SELECT COUNT(*) FROM block;'

If this command fails, fix your PostgreSQL configuration before restarting the Midnight node. Also make sure the .env file is loading correctly:

source ~/.env
echo $DB_SYNC_POSTGRES_CONNECTION_STRING

3. Chain spec file is missing or wrong

The --chain flag must point at the correct chain spec for your network. Confirm the file exists:

ls -lh ~/res/preview/chain-spec-raw.json

If the file is missing, the binary extraction in Step 5 may have failed. Re-run the extraction and verify ~/res contains the expected directories.

4. Node binary is outdated

Node versions update frequently, and an outdated binary gets rejected by current network peers. Always cross-reference the version you're running against the compatibility matrix. If a newer version is listed, follow the upgrade procedure at the end of this tutorial.

Peers keep disconnecting

If peer count climbs then immediately drops back to 0, work through these checks in order.

1. Port 30333 is not publicly reachable

This is the single most common cause. Even if the port is open locally, your cloud security group may be blocking inbound connections from external peers.

# Check UFW
sudo ufw status

# Open if missing
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 rules in the web console. The operating-system firewall and the cloud-level firewall are independent.

2. Clock drift

Substrate-based nodes reject connections from peers whose system clocks differ significantly. Check that NTP is active:

timedatectl status

Look for NTP service: active and System clock synchronized: yes. If NTP is inactive:

sudo timedatectl set-ntp true

3. Disk I/O bottleneck

High disk utilisation causes the node to fall behind processing blocks. Peers consider it unresponsive and drop the connection. Run iostat -x 1 10 and check %util. If it's consistently above 80%, the disk is your problem.

4. NAT or double-NAT

If your server is behind NAT, peers can't initiate inbound connections to you. Either configure port forwarding at the router level or use a VPS with a dedicated public IP.

Node crashes or restarts frequently

Check the last error before the most recent restart:

journalctl -u midnight-node -n 50 | grep -E "ERROR|WARN|panic"

Check whether the system OOM-killed the process:

journalctl -k | grep -i "oom\|killed process"

If OOM kills appear, the node is running out of memory. Add more RAM, or as a temporary measure on an undersized machine:

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

For suspected chain data corruption after a hard shutdown, clear the Midnight node's base path while leaving your Cardano-db-sync database intact — this avoids re-running the hours-long db-sync:

sudo systemctl stop midnight-node
rm -rf ~/data
sudo systemctl start midnight-node

If you also need to reset Cardano-db-sync (only do this if you're certain the issue is there; it adds hours of re-sync time):

sudo systemctl stop cardano-db-sync midnight-node
# Drop and recreate the cexplorer database in psql, then restart
sudo systemctl start cardano-db-sync midnight-node

IPC socket errors

After an unclean shutdown you may see Cardano-db-sync logs complaining about a missing or stale socket:

No such file or directory: .../db/node.socket

The socket file is created by Cardano-node on startup. If Cardano-node hasn't fully initialised yet, or if it crashed and left a stale socket, db-sync can't connect.

# Check whether the socket exists
ls -la ~/cardano-data/db/node.socket

# If the Cardano node is running, wait a moment and check again
sudo systemctl status cardano-node

If Cardano-node is running but the socket is missing, restart the service and watch the logs for its creation:

sudo systemctl restart cardano-node
watch -n 2 "ls -la ~/cardano-data/db/node.socket"

Once the socket appears, db-sync will reconnect automatically.

Port conflicts

If a service fails to start with address already in use, something else on your host is already bound to that port. The full port map:

Port	Service
9944	Midnight node RPC
30333	Midnight node P2P
9615	Midnight node Prometheus metrics
3001	Cardano node P2P
5432	PostgreSQL

Identify the conflicting process:

sudo ss -tlnp | grep -E '9944|30333|9615|3001|5432'

Stop the conflicting process or remap the port in the affected service's flags.

Keeping your node up to date

Midnight is in active development. Node versions update frequently, and an outdated binary will stop syncing or get rejected by peers. Watch the Midnight Discord and the release notes for new versions.

When a new version is released:

Check the compatibility matrix to confirm the new binary version and any updated component versions.
Download the new binary:

cd ~/tmp
curl -L -O https://github.com/midnightntwrk/midnight-node/releases/download/<NEW_VERSION>/midnight-node-<NEW_VERSION>-linux-amd64.tar.gz
tar -xvzf midnight-node-<NEW_VERSION>-linux-amd64.tar.gz

Stop the node, replace the binary, and restart:

sudo systemctl stop midnight-node
mv ~/tmp/midnight-node ~/.local/bin/midnight-node
sudo systemctl start midnight-node

Confirm the new version is running:

midnight-node --version

Watch the logs for a clean startup and verify peers reconnect:

journalctl -fu midnight-node

Before every upgrade, back up your configuration. Chain data can be re-synced from genesis, but your env file and service configuration cannot be recovered if lost:

tar -czf "midnight-config-backup-$(date -u +%Y%m%d).tar.gz" \
  ~/.env \
  /etc/systemd/system/midnight-node.service \
  /etc/systemd/system/cardano-node.service \
  /etc/systemd/system/cardano-db-sync.service

What to do next

You now have a full node running on the official stack, synced to the Midnight network, with monitoring commands and a tested troubleshooting playbook.

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 application on top of the network you're now running: Getting started.
Add persistent monitoring: schedule ~/monitor-height.sh via a systemd timer or cron, and set up Prometheus alerting when peer count drops to zero.
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: tag @midnightntwrk on X and use #MidnightforDevs.

References

This tutorial targets Midnight Preview using the current official binary installation method. Always check the compatibility matrix before starting a node or upgrading an existing one.

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

\.wslconfig open in Notepad with both the file path and config contents visible." width="800" height="450">

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 Full Midnight Node: Setup, Sync & Monitoring

Understanding the node types

Step 1: Check resource requirements

Step 2: Create the midnight user

Step 3: Set up Cardano node with Mithril

Install Mithril

Configure Mithril for your network

Download and verify the Cardano snapshot

Install Cardano node

Inject the Mithril snapshot and run Cardano node

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

Install PostgreSQL 17

Configure roles and the database

Configure passwordless authentication

PostgreSQL performance tuning

Install Cardano-db-sync

Start Cardano-db-sync

Monitor Cardano-db-sync sync progress

Step 5: Install and configure the Midnight node

Create directories and download the binary

Set environment variables

Run the Midnight node

Create the systemd service

Step 6: Monitor the initial sync

Reading the sync log output

Check sync state via RPC

Monitor block height on a loop

Step 7: Verify your node is synced and healthy

Step 8: Troubleshooting common issues

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

Peers keep disconnecting

Node crashes or restarts frequently

IPC socket errors

Port conflicts

Keeping your node up to date

What to do next

References

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

Step 2: Create the `midnight` user

`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