Forem: Uroy Nwankwo

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.

Forem: Uroy Nwankwo

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