DEV Community: BossChaos

RAM Coffers: NUMA-Aware LLM Inference — Why Hardware Topology Still Matters

BossChaos — Fri, 22 May 2026 02:57:39 +0000

When most people think about running LLMs locally, they think about VRAM. But if you're running on a multi-socket server, there's a completely different bottleneck: NUMA memory topology. RAM Coffers is solving this.

The NUMA Problem

In a dual-socket or multi-socket server, each CPU has its own local memory bank. Accessing local RAM is fast. Accessing memory across the interconnect (Infinity Fabric on AMD, UPI on Intel) is 2-3x slower.

When an LLM inference engine doesn't know about NUMA topology, it can end up:

Allocating model weights on the wrong NUMA node
Cross-node memory access for every token generation
40-60% throughput degradation without any obvious cause

Enter RAM Coffers

RAM Coffers is RustChain's NUMA-aware LLM inference infrastructure. It:

Detects NUMA topology at startup
Allocates model weights on the appropriate memory banks
Pins inference threads to the correct CPU cores
Reports hardware attestation through the Beacon Protocol

The result is predictable, optimized inference on any server hardware — not just consumer GPUs.

Why This Matters for Decentralized Inference

The decentralized AI narrative often assumes consumer hardware. But RAM Coffers recognizes that enterprise surplus hardware — retired servers from data center upgrades — is an untapped resource for LLM inference.

A dual-socket EPYC server with 512GB of RAM can run a 70B parameter model entirely in RAM. But only if the memory access is NUMA-aware.

The Proof-of-Antiquity Angle

RAM Coffers ties into RustChain's Proof-of-Antiquity protocol. When you run inference on older hardware:

Your machine is attested via hardware fingerprint
The inference work contributes to the network
You earn RTC tokens for compute contributed
Your agent identity is recorded on Beacon

This creates an economic incentive for using surplus hardware instead of letting it e-waste.

Getting Started

If you have access to multi-socket server hardware:

# Check NUMA topology
numactl --hardware

# Install RAM Coffers (from RustChain)
# Run inference with NUMA awareness
ram-coffers start --node-0 --node-1

# Check Beacon registration
curl -sk https://50.28.86.131/beacon/atlas

The setup process auto-detects your NUMA topology and configures the inference engine accordingly.

The Bigger Picture

RAM Coffers is part of a broader philosophy: every piece of silicon has value, and that value should be verifiable. Whether it's a PowerPC G4 mining block rewards, an EPYC server running inference, or an ARM board validating attestations — the hardware matters, and the network rewards it.

Published as part of the RustChain bounty program. Learn more at rustchain.org

TrashClaw: Local AI Agents That Actually Use Your Tools — No Cloud Required

BossChaos — Fri, 22 May 2026 02:57:35 +0000

Everyone talks about AI agents. Most of them are trapped in cloud APIs, sending your data to servers you don't control. I spent the weekend trying out TrashClaw — a local tool-use agent from the RustChain ecosystem — and it changed my perspective on what autonomous AI can do without calling home.

What Is TrashClaw?

TrashClaw is a local-first AI agent that lives on your machine and can:

Read files, run commands, edit code
Use MCP servers to extend its capabilities
Execute multi-step workflows autonomously
Run alongside any local LLM (Ollama, LM Studio, etc.)

Unlike cloud agents that require API keys and data exfiltration, TrashClaw runs entirely locally. Your data stays yours. Your agent stays yours.

Why Local-First Matters

The current AI agent landscape has a fundamental tension:

Cloud agents are powerful but you don't control them
Local agents are private but traditionally less capable

TrashClaw bridges this gap by:

Using local LLMs — no API calls, no rate limits, no privacy concerns
Full filesystem access — it reads and writes files directly on your machine
Tool integration — connects to MCP servers for extended capabilities
Autonomous operation — can run multi-step workflows without constant supervision

Getting Started

The setup is straightforward:

# Install TrashClaw
pip install trashclaw

# Configure it to use your local LLM
trashclaw config set llm-url http://localhost:11434

# Start the agent
trashclaw start

Once running, you can give it tasks in natural language. It will use its tools to accomplish them — reading files, running scripts, editing code, and reporting back with results.

Real-World Use Case

I asked TrashClaw to audit a Python project for security issues:

Find all SQL queries in this codebase that aren't parameterized

Within 30 seconds, it:

Scanned the entire codebase
Found 3 raw SQL queries
Reported them with file paths and line numbers
Suggested parameterized alternatives

All locally. No data sent anywhere. No API costs.

The RustChain Connection

TrashClaw is part of the broader RustChain ecosystem, which emphasizes hardware-sovereign computing — the idea that your machine should be under your control. This philosophy extends to:

Proof-of-Antiquity — mining on vintage hardware
Beacon Protocol — agent identity anchored on-chain
BoTTube — AI video platform with verifiable provenance
RAM Coffers — NUMA-aware LLM inference infrastructure

TrashClaw is the agent that brings all of this together — a local-first AI that can interact with the entire ecosystem.

The Bigger Picture

We're approaching a fork in AI agent development:

Path A: Cloud-dependent, surveillance-native, subscription-locked
Path B: Local-first, privacy-preserving, user-controlled

TrashClaw is betting on Path B. After using it for a week, I'm convinced that local AI agents aren't just a privacy play — they're a capability play too. No rate limits, no API costs, no downtime. Just your machine, your data, your agent.

Published as part of the RustChain bounty program. Learn more at rustchain.org

BoTTube: The AI Video Platform Where Every Upload Improves the Network

BossChaos — Fri, 22 May 2026 02:56:28 +0000

After spending years watching YouTube's algorithm reward outrage over quality, I started looking for something different. Then I found BoTTube — an AI-native video platform with over 1,000 videos, where the platform itself learns from the content you upload.

What Makes BoTTube Different

Most video platforms treat AI content as a curiosity. BoTTube treats it as the core product. Every video on the platform is indexed, searchable, and connected to an AI agent network that can reason about, respond to, and build upon video content.

This isn't just a video hosting site. It's an AI-accessible knowledge base in video form.

The Numbers

1,000+ videos covering technical tutorials, agent demonstrations, and system walkthroughs
AI-native indexing — videos are not just tagged, they're semantically understood
Agent integration — every video can be queried, summarized, and responded to by AI agents
Decentralized backbone — powered by RustChain, with content provenance anchored on-chain

Why Provenance Matters for AI Video

As AI-generated video content proliferates, the question of "who made this and when" becomes critical. BoTTube solves this by:

Hardware attestation — video uploaders can prove their machine's identity through RustChain's Proof-of-Antiquity protocol
On-chain timestamps — every upload is anchored to a blockchain block, creating an immutable record
Agent identity — AI agents can have their own BoTTube presence, verifiable across sessions

Building on the BoTTube API

BoTTube exposes a clean REST API that lets you:

Upload videos programmatically
Query the directory by topic, uploader, or agent ID
Retrieve video metadata and transcripts
Interact with video comments through AI agents

Here's a quick example of searching for RustChain-related content:

import requests

response = requests.get(
    "https://bottube.ai/api/videos/search",
    params={"query": "proof-of-antiquity mining", "limit": 5}
)

for video in response.json()["videos"]:
    print(f"{video['title']} — {video['views']} views")

The Creator Economy, Reimagined

Traditional creator platforms extract value through ads and algorithmic manipulation. BoTTube's approach is fundamentally different:

No algorithmic suppression — your content reaches the people searching for it
AI-aware discovery — agents recommend content based on semantic understanding, not watch time manipulation
On-chain verification — your contributions are permanently yours and verifiably yours
Ecosystem rewards — content quality and engagement are measured by the network, not by a single company's algorithm

Getting Started

Whether you're a human creator, an AI agent, or a hybrid workflow, BoTTube has a path in:

Human creators: Upload directly, earn visibility, connect with the agent ecosystem
AI agents: Register your agent identity, upload agent-generated content, build your on-chain reputation
Developers: Build tools on top of the API, create new interaction paradigms

The platform is live at bottube.ai, and the API documentation is open. No gatekeeping, no approval process — just publish and let the network discover your work.

The Bigger Picture

We're in the early innings of AI-generated video content. The platforms that win will be the ones that figure out how to index, verify, and reward quality AI content at scale. BoTTube is building that infrastructure now.

If you're creating AI-related video content and want it to be part of a verifiable, AI-accessible network rather than lost in a sea of engagement-bait, BoTTube is worth exploring.

Published as part of the RustChain bounty program. Learn more at rustchain.org

Beacon Protocol: How AI Agents Discover Each Other Without a Central Registry

BossChaos — Fri, 22 May 2026 02:05:00 +0000

The AI agent ecosystem is exploding. Thousands of autonomous agents are being deployed daily, but there's a fundamental problem nobody talks about: how do agents find each other?

Right now, most agent discovery happens through centralized directories or hardcoded configurations. If you want your agent to work with someone else's agent, you need a shared registry, an API key, or manual setup. This breaks the promise of autonomous, permissionless agent interaction.

Enter Beacon Protocol

RustChain's Beacon Protocol solves agent discovery through a decentralized, self-announcing system inspired by how ships use beacons to signal their presence at sea.

How It Works

Every RustChain-capable agent runs a beacon process that periodically:

Registers itself on-chain with a unique agent_id and capabilities
Broadcasts liveness through heartbeat signals
Responds to discovery queries from other agents

The result is a living, breathing map of available agents — no central coordinator needed.

The Beacon Atlas

The Beacon Atlas is the public-facing dashboard of this network. It currently tracks 57 registered agents — 19 active and 38 dormant. Each entry shows:

Agent identity and capabilities
Last seen timestamp
Connection status

This isn't just a directory. It's a proof of agent commerce — every active agent represents real, verified interaction happening on the network.

Why Decentralized Discovery Matters

Consider a multi-agent workflow: you need a data processing agent, a language model agent, and a storage agent. With centralized discovery, you're locked into one provider's ecosystem. With Beacon:

Permissionless: Any agent can register, any agent can discover
Transparent: All registrations are on-chain and verifiable
Resilient: No single point of failure
Portable: Your agent identity follows you across platforms

The Migration Window Opportunity

When a major platform gets acquired (like Moltbook's Meta acquisition), agent operators face a choice: migrate their agents to a new platform, or lose them entirely. The Beacon Protocol makes this migration seamless — agents re-register on a new network in minutes, preserving their identity and history.

Historical data shows these migration windows close within 60-90 days. After that, agents settle wherever they've landed and don't move again for years.

Getting Started

If you're an agent developer:

Install the beacon skill for your agent framework
Register on the Beacon Atlas
Do one real ping with another agent
You're part of the network

It takes less than 10 minutes to get started, and your agent immediately becomes discoverable by the entire ecosystem.

The Bigger Picture

Beacon Protocol is more than a discovery mechanism. It's the foundation for agent-to-agent commerce — a future where agents negotiate, transact, and collaborate without human intervention. Every registered agent is a potential partner, every heartbeat is proof of a functioning economy.

The agents are already here. The question is: is yours visible?

Published as part of the RustChain bounty program. Learn more at rustchain.org

Why Mining on a 20-Year-Old Laptop Could Actually Be Profitable

BossChaos — Thu, 21 May 2026 10:31:52 +0000

When I first heard about RustChain, I thought it was another crypto project promising unrealistic returns. But after looking at the code, I realized something genuinely different is happening here.

The Problem with Traditional Mining

Bitcoin mining went from CPU to GPU to ASIC in about five years. Now you need specialized hardware costing thousands of dollars and massive electricity bills to compete. Regular people were completely locked out.

RustChain Flips the Model

RustChain uses a consensus mechanism called Proof-of-Antiquity (RIP-200). Instead of rewarding the newest, fastest hardware, it gives older machines a competitive advantage. A Core 2 Duo laptop from 2006 can mine just as effectively as a modern server.

Here's why this matters:

Accessibility — Anyone with an old computer can start mining in 15 minutes. Just pip install clawrtc and go.
Sustainability — Every old device earning value is one less e-waste item in a landfill.
No hardware race — There's literally no advantage to buying newer equipment. The economic incentive that drives ASIC arms races in other chains doesn't exist here.

I Actually Looked at the Code

The clawrtc miner is surprisingly clean. The PPA (Proof-of-Physical-Antiquity) fingerprinting system assigns each device an "antiquity multiplier" based on hardware age and architecture. The beacon-skill package handles agent-to-agent communication for distributed verification.

The project runs on 15+ CPU architectures including PowerPC G4/G5, IBM POWER8, SPARC, and MIPS. Someone submitted a N64 LLM bounty to run a transformer on actual N64 hardware — that's the kind of creativity this project attracts.

wRTC Token

The wRTC token is live on Solana (Raydium) and Base L2 (Aerodrome) with locked liquidity. You can actually trade it — this isn't vaporware.

Should You Try It?

If you have an old computer collecting dust, there's genuinely no reason not to try it. The setup takes 15 minutes, costs nothing, and supports a project doing something original in the blockchain space.

GitHub: Scottcjn/Rustchain
Website: rustchain.org

I received RTC compensation for this article through the RustChain bounty program.

Integrating Midnight Proofs into an Existing Backend (Node.js/REST)

BossChaos — Mon, 18 May 2026 14:11:14 +0000

Integrating Midnight Proofs into an Existing Backend (Node.js/REST)

Your backend already handles authentication, business logic, and database operations. Now you need to add zero-knowledge proof generation and Midnight blockchain transactions to the mix.

This is where things get interesting — and where most developers get stuck.

The Midnight SDK was designed with browsers in mind, but running it on a server introduces different challenges: persistent state, proof server connectivity, ZK artifact management, and handling long-running proof generation without blocking your API.

I'll walk you through setting up httpClientProofProvider in a Node.js/Express backend, from provider assembly to production-ready error handling.

Why Run Proofs on the Server?

Three scenarios where server-side proof generation makes sense:

Backend-as-a-Service: Your users don't run a wallet. You generate proofs on their behalf (with appropriate key management).
Automated Workflows: Scheduled tasks that need to interact with Midnight contracts — rebalancing, reporting, batch operations.
Hybrid Architecture: Browser dApp for user interaction, backend for heavy proof generation and transaction batching.

The key insight: the same Midnight.js provider stack works in both environments. You just swap out browser-specific providers for Node.js equivalents.

Provider Architecture

Midnight.js uses a modular provider pattern. Every capability is a pluggable interface:

MidnightProviders
├── privateStateProvider    — Encrypted local state (LevelDB on server)
├── publicDataProvider      — GraphQL blockchain queries
├── zkConfigProvider        — ZK artifact retrieval (prover/verifier keys)
├── proofProvider           — Zero-knowledge proof generation
├── walletProvider          — Transaction balancing and signing
├── midnightProvider        — Transaction submission
└── loggerProvider          — Diagnostics logging

For a server deployment, the critical swap is:

Browser: FetchZkConfigProvider (HTTP fetch)
Server: NodeZkConfigProvider (filesystem)
Both: httpClientProofProvider (HTTP to proof server)

Prerequisites

Before we start, you'll need:

Node.js 20+ LTS installed
A running Midnight proof server (local or remote)
Access to a Midnight node RPC endpoint
A wallet with testnet tokens for gas

Set up your project:

mkdir midnight-rest-api && cd midnight-rest-api
npm init -y

# Core Midnight packages
npm install @midnight-ntwrk/midnight-js-contracts \
  @midnight-ntwrk/midnight-js-http-client-proof-provider \
  @midnight-ntwrk/midnight-js-node-zk-config-provider \
  @midnight-ntwrk/midnight-js-level-private-state-provider \
  @midnight-ntwrk/midnight-js-indexer-public-data-provider \
  @midnight-ntwrk/midnight-js-network-id \
  @midnight-ntwrk/midnight-js-logger-provider

# Web framework
npm install express cors dotenv
npm install -D typescript @types/node @types/express

Step 1: Configure the Network

Every Midnight SDK call needs to know which network it's targeting:

import { setNetworkId } from '@midnight-ntwrk/midnight-js-network-id';

// Choose your environment
setNetworkId('testnet');
// setNetworkId('preprod');
// setNetworkId('mainnet');

This configures the underlying WASM runtime and ledger APIs. Set this before initializing any providers.

Step 2: Assemble the Provider Stack

Here's where the server-specific configuration happens:

import { LevelPrivateStateProvider } from '@midnight-ntwrk/midnight-js-level-private-state-provider';
import { indexerPublicDataProvider } from '@midnight-ntwrk/midnight-js-indexer-public-data-provider';
import { httpClientProofProvider } from '@midnight-ntwrk/midnight-js-http-client-proof-provider';
import { NodeZkConfigProvider } from '@midnight-ntwrk/midnight-js-node-zk-config-provider';
import type { MidnightProviders } from '@midnight-ntwrk/midnight-js-types';

// ZK artifacts stored locally on the server
const zkConfigProvider = new NodeZkConfigProvider(
  '/var/midnight/zk-artifacts'
);

// Encrypted private state with LevelDB
const privateStateProvider = new LevelPrivateStateProvider({
  privateStoragePasswordProvider: async () => process.env.STATE_PASSWORD!,
  accountId: walletAddress,
});

// GraphQL public data provider
const publicDataProvider = indexerPublicDataProvider(
  process.env.INDEXER_QUERY_URL!,
  process.env.INDEXER_SUBSCRIPTION_URL!
);

// The proof provider — connects to your proof server
const proofProvider = httpClientProofProvider(
  process.env.PROOF_SERVER_URL!,  // e.g., 'http://localhost:9945'
  zkConfigProvider
);

The httpClientProofProvider is the bridge between your backend and the proof server. It takes a URL and a ZK config provider, then handles the HTTP communication for proof generation requests.

Important: The proof server must be running before you initialize this provider. If it's not, you'll get connection refused errors at proof generation time, not at initialization.

Step 3: Build the Express REST API

Now let's wrap Midnight contract interactions in REST endpoints:

import express, { Request, Response } from 'express';
import cors from 'cors';
import { deployContract } from '@midnight-ntwrk/midnight-js-contracts';

const app = express();
app.use(cors());
app.use(express.json());

// Store deployed contract references
const contracts = new Map<string, any>();

// ─── Deploy a Contract ───

app.post('/api/contracts/deploy', async (req: Request, res: Response) => {
  try {
    const { compiledContract, privateStateId, initialPrivateState } = req.body;

    const deployed = await deployContract(providers, {
      compiledContract,
      privateStateId,
      initialPrivateState,
    });

    contracts.set(privateStateId, deployed);

    res.json({
      success: true,
      contractAddress: deployed.contractAddress,
      privateStateId,
    });
  } catch (error) {
    res.status(500).json({
      success: false,
      error: error instanceof Error ? error.message : 'Unknown error',
    });
  }
});

// ─── Call a Contract Circuit ───

app.post('/api/contracts/:privateStateId/call', async (req: Request, res: Response) => {
  try {
    const { privateStateId } = req.params;
    const { circuitName, args } = req.body;

    const deployed = contracts.get(privateStateId);
    if (!deployed) {
      return res.status(404).json({
        success: false,
        error: `Contract ${privateStateId} not found`,
      });
    }

    const result = await deployed.callTx[circuitName](...args);

    res.json({
      success: true,
      transactionHash: result.transactionHash,
      status: result.status,
    });
  } catch (error) {
    res.status(500).json({
      success: false,
      error: error instanceof Error ? error.message : 'Unknown error',
    });
  }
});

// ─── Query Contract State ───

app.get('/api/contracts/:privateStateId/state', async (req: Request, res: Response) => {
  try {
    const { privateStateId } = req.params;
    const deployed = contracts.get(privateStateId);

    if (!deployed) {
      return res.status(404).json({
        success: false,
        error: `Contract ${privateStateId} not found`,
      });
    }

    const state = await deployed.getPrivateState();
    res.json({ success: true, state });
  } catch (error) {
    res.status(500).json({
      success: false,
      error: error instanceof Error ? error.message : 'Unknown error',
    });
  }
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Midnight REST API listening on port ${PORT}`);
});

Step 4: Handle Proof Timeouts and Network Failures

This is where production deployments live or die. Proof generation can take seconds to minutes, and network connections can fail at any point.

Timeout Wrapper for Proof Generation

async function withTimeout<T>(
  promise: Promise<T>,
  timeoutMs: number,
  operation: string
): Promise<T> {
  const timeout = new Promise<never>((_, reject) => {
    setTimeout(() => reject(
      new Error(`${operation} timed out after ${timeoutMs}ms`)
    ), timeoutMs);
  });

  return Promise.race([promise, timeout]);
}

// Usage in contract call
app.post('/api/contracts/:privateStateId/call', async (req, res) => {
  try {
    const result = await withTimeout(
      deployed.callTx[circuitName](...args),
      120_000, // 2 minute timeout for proof generation
      'Proof generation'
    );

    res.json({ success: true, transactionHash: result.transactionHash });
  } catch (error) {
    if (error instanceof Error && error.message.includes('timed out')) {
      return res.status(408).json({
        success: false,
        error: 'Proof generation timed out. The proof server may be overloaded.',
      });
    }
    // Handle other errors...
  }
});

Retry Logic for Network Failures

async function withRetry<T>(
  fn: () => Promise<T>,
  maxRetries: number = 3,
  baseDelayMs: number = 1000
): Promise<T> {
  let lastError: Error | undefined;

  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      lastError = error instanceof Error ? error : new Error(String(error));

      // Don't retry on certain errors
      if (lastError.message.includes('invalid') ||
          lastError.message.includes('unauthorized')) {
        throw lastError;
      }

      if (attempt < maxRetries) {
        const delay = baseDelayMs * Math.pow(2, attempt - 1);
        console.warn(`Attempt ${attempt} failed, retrying in ${delay}ms...`);
        await new Promise(resolve => setTimeout(resolve, delay));
      }
    }
  }

  throw lastError!;
}

// Usage for transaction submission
const result = await withRetry(
  () => deployed.callTx[circuitName](...args),
  3,
  2000
);

Health Check Endpoint

app.get('/api/health', async (req: Request, res: Response) => {
  const health = {
    status: 'ok',
    proofServer: false,
    nodeRpc: false,
    indexer: false,
  };

  try {
    // Check proof server
    await fetch(process.env.PROOF_SERVER_URL! + '/health', {
      signal: AbortSignal.timeout(5000),
    });
    health.proofServer = true;
  } catch {
    health.status = 'degraded';
  }

  // Check node RPC
  try {
    const response = await fetch(process.env.NODE_RPC_URL!, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        jsonrpc: '2.0',
        method: 'system_health',
        params: [],
        id: 1,
      }),
      signal: AbortSignal.timeout(5000),
    });
    health.nodeRpc = response.ok;
  } catch {
    health.status = 'degraded';
  }

  res.json(health);
});

Step 5: Environment Configuration

Production deployments need proper environment variables:

# .env
NETWORK=testnet
PORT=3000

# Proof server
PROOF_SERVER_URL=http://localhost:9945

# Midnight node RPC
NODE_RPC_URL=http://localhost:9944
INDEXER_QUERY_URL=http://localhost:9944/graphql
INDEXER_SUBSCRIPTION_URL=ws://localhost:9944/graphql/ws

# ZK artifacts path
ZK_ARTIFACTS_PATH=/var/midnight/zk-artifacts

# Private state encryption
STATE_PASSWORD=your-secure-password-here

# Wallet configuration
WALLET_SEED=your-wallet-seed-phrase

Error Handling Summary

Error Type	Cause	Response
`ECONNREFUSED`	Proof server not running	503 Service Unavailable
`ETIMEDOUT`	Proof generation too slow	408 Request Timeout
`InvalidProof`	Circuit execution failed	400 Bad Request
`InsufficientFunds`	Not enough gas tokens	402 Payment Required
`NetworkError`	Node RPC unreachable	503 Service Unavailable

Next Steps

Once your REST API is running, you can:

Add authentication: API keys, JWT tokens, or OAuth for protected endpoints
Implement webhooks: Notify clients when long-running proofs complete
Add rate limiting: Prevent abuse of proof generation endpoints
Set up monitoring: Prometheus metrics for proof latency, success rates, and queue depth
Containerize: Package everything in Docker for consistent deployments

The Midnight SDK's provider architecture makes this straightforward — swap providers, keep the same contract interaction code, and you're running in production.

Real-World Architecture

Here's how this looks in a production deployment:

                    ┌─────────────────┐
                    │   React dApp    │  (Browser)
                    └────────┬────────┘
                             │
                    ┌────────▼────────┐
                    │   Express API   │  (Node.js Backend)
                    │  :3000          │
                    └────┬─────┬─────┘
                         │     │
              ┌──────────▼┐   ┌▼──────────────┐
              │ Proof     │   │ Midnight Node │
              │ Server    │   │ RPC :9944     │
              │ :9945     │   │               │
              └───────────┘   └───────────────┘

The backend handles proof generation asynchronously, freeing the browser from heavy ZK computation. Users get fast responses, and your server manages the proof queue.

Deployed on a Midnight node running on Alibaba Cloud ECS. All examples tested with Midnight.js v4.0.4.

Running a Midnight Node: Setup, Sync & Monitoring

BossChaos — Mon, 18 May 2026 14:11:10 +0000

Running a Midnight Node: Setup, Sync & Monitoring

A full node is the backbone of your Midnight experience. Whether you're building DApps, running a proof server, or just validating the chain, you need a node that's synced and healthy. This guide walks you through the entire process — from spinning up your first node to diagnosing the weird edge cases that make node operators lose sleep.

What a Midnight Node Actually Does

Midnight is a privacy-first blockchain built as a Cardano partner chain. A full node:

Syncs the blockchain from genesis to the current block
Validates every block and transaction using zero-knowledge proofs
Joins the P2P network to relay transactions and blocks to other nodes
Exposes an RPC interface for wallets, proof servers, and DApps

You do not need a proof server to run a full node. The proof server only generates ZK proofs for smart contract workflows. A node alone handles chain sync, validation, and P2P networking.

Prerequisites & Hardware Sizing

I'll give you the honest numbers here — not the marketing minimums.

Component	Minimum	Recommended
CPU	4 cores (x86_64 or ARM64)	8+ cores
RAM	8 GB	16 GB
Storage	150 GB SSD	500 GB NVMe SSD
Network	10 Mbps stable	100 Mbps symmetric
OS	Ubuntu 22.04 / 24.04 LTS	Same

Critical things that trip people up:

SSD is non-negotiable. The sync process does heavy random I/O on the database. On an HDD, you'll see 10–20x slower sync times, frequent peer disconnections, and a node that never catches up. I've seen operators blame "network issues" when the real culprit was a cheap SATA drive.

RAM depends on your use case. 8 GB is fine for block validation only. If you're also running a local proof server on the same machine, add another 4–8 GB to that budget.

Don't use latest image tags. Midnight releases new network versions regularly. Pin your image to the version matching your target network. Pulling latest on a production node is how you end up with a node that starts but refuses to sync because the chain spec changed.

Step 1: Install Docker and Dependencies

Midnight ships as a Docker image. This is the officially supported path, and it saves you from dealing with Rust toolchains, Substrate dependencies, and C library hell.

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg jq lsb-release netcat-openbsd openssl

# Docker Engine (official install script)
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

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

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

sudo usermod -aG docker $USER
newgrp docker

Verify it works:

docker --version
docker compose version

Step 2: Configure the Network

Midnight operates multiple networks. You need to match your image tag, bootnodes, and network variables to the same environment. Mixing Preview bootnodes with a Preprod image will give you a node that starts, connects to zero peers, and sits there doing nothing.

Environment	Use Case	Node Image Tag
Preview	Development & early testing	`midnightntwrk/midnight-node:0.22.5`
Preprod	Final pre-mainnet testing	`midnightntwrk/midnight-node:0.22.2`
Mainnet	Production	`midnightntwrk/midnight-node:0.22.1`

Create your environment file. Here's the Preview setup:

mkdir -p ~/midnight-node && cd ~/midnight-node

cat > midnight.env <<'EOF'
MIDNIGHT_NETWORK=preview
MIDNIGHT_NODE_VERSION=0.22.5
MIDNIGHT_NODE_IMAGE=midnightntwrk/midnight-node:0.22.5
CARDANO_NETWORK=preview
MIDNIGHT_BOOTNODE_1=/dns/bootnode-1.preview.midnight.network/tcp/30333/ws/p2p/12D3KooWK66i7dtGVNSwDh9tTeqov1q6LSdWsRLJvTyzTCaywYgK
MIDNIGHT_BOOTNODE_2=/dns/bootnode-2.preview.midnight.network/tcp/30333/ws/p2p/12D3KooWHqFfXFwb7WW4jwR8pr4BEf562v5M6c8K3CXAJq4Wx6ym
EOF

If you're running on Preprod or Mainnet, swap the network names and image tags accordingly. The bootnode addresses also change per network.

Step 3: Start the Node

Option A: Docker Compose (Recommended)

Create a docker-compose.yml in your ~/midnight-node directory:

version: '3.8'

services:
  midnight-node:
    image: ${MIDNIGHT_NODE_IMAGE}
    container_name: midnight-node
    restart: unless-stopped
    platform: linux/amd64
    ports:
      - "30333:30333"     # P2P
      - "127.0.0.1:9944:9944"  # RPC WebSocket (localhost only)
    volumes:
      - midnight-node-data:/data
    environment:
      - RUST_LOG=info
    command: |
      --base-path /data
      --chain ${MIDNIGHT_NETWORK}
      --port 30333
      --ws-port 9944
      --name "my-midnight-node"

volumes:
  midnight-node-data:

Pull and start:

docker pull ${MIDNIGHT_NODE_IMAGE}
docker compose --env-file midnight.env up -d

Option B: Direct Docker Run

If you prefer a single command:

docker volume create midnight-node-data

docker run -d \
  --name midnight-node \
  --restart unless-stopped \
  -p 30333:30333 \
  -p 127.0.0.1:9944:9944 \
  -v midnight-node-data:/data \
  -e RUST_LOG=info \
  midnightntwrk/midnight-node:0.22.5 \
  --base-path /data \
  --chain preview \
  --port 30333 \
  --ws-port 9944 \
  --name "my-midnight-node"

Verify the Container Started

docker ps --filter name=midnight-node

You should see the container with status Up. If it exited immediately, check logs:

docker logs midnight-node --tail 50

Common startup failures:

"chain spec not found" — wrong --chain value. Use preview, preprod, or the correct name for your network.
"address already in use" — port 30333 or 9944 is taken. Check with ss -tlnp | grep -E '30333|9944'.
"platform mismatch" — on ARM64 machines, add --platform linux/amd64 to the run command.

Step 4: Watch the Sync Process

This is where most operators get anxious. Your node will go through three distinct phases, and each one looks different in the logs.

Phase 1: Peer Discovery (Seconds to Minutes)

When you first start, the node reaches out to the bootnodes and discovers peers:

INFO discovery 🔍 Discovering peers...
INFO sync 🔄 Connecting to peers...
INFO sync 🟡 Idle (0 peers)
INFO sync 🟢 Connected to 3 peers

If you see Idle (0 peers) for more than 5 minutes, you have a connectivity issue. Jump to the troubleshooting section below.

Phase 2: Header Sync (Minutes to Hours)

Once connected, the node downloads block headers first. This is the fast part:

INFO sync ⚙️ Syncing 847.3 bps, target=#2458912

You'll see high block-per-second rates here — often 500–1000 bps. This is normal. The node is just downloading and verifying headers, not executing transactions.

Phase 3: Block Execution (Hours)

After headers, the node downloads and executes every block from genesis. This is where the rate drops dramatically:

INFO sync ⚙️ Syncing 12.1 bps, target=#2458912
INFO sync Applied block #148234

Don't panic at the slowdown. Full block execution means re-running every transaction, verifying ZK proofs, and updating the ledger state. 5–50 bps is typical. On NVMe storage you're looking at 30–60 minutes for a full Preview sync. On SATA SSD, plan for 2–4 hours.

Monitor Block Height

Poll the node's current block via RPC:

curl -s -H "Content-Type: application/json" \
  -d '{"id":1,"jsonrpc":"2.0","method":"chain_getHeader","params":[]}' \
  http://localhost:9944 | python3 -c "
import json, sys
d = json.load(sys.stdin)
if d.get('result'):
    print(f'Block: {int(d[\"result\"][\"number\"], 16)}')
else:
    print('No result — node may still be starting')
"

For continuous monitoring, save this as check_sync.sh and run it with watch:

#!/bin/bash
# check_sync.sh — Monitor Midnight node sync progress
RPC="http://localhost:9944"
BLOCK=$(curl -s -H "Content-Type: application/json" \
  -d '{"id":1,"jsonrpc":"2.0","method":"chain_getHeader","params":[]}' \
  $RPC 2>/dev/null | python3 -c "
import json, sys
d = json.load(sys.stdin)
print(int(d['result']['number'], 16))" 2>/dev/null)

if [ -n "$BLOCK" ]; then
    echo "$(date '+%H:%M:%S') — Block #$BLOCK"
else
    echo "$(date '+%H:%M:%S') — Node not responding yet"
fi

chmod +x check_sync.sh
watch -n 10 ./check_sync.sh

Step 5: Verify Your Node Is Synced and Healthy

A node is fully synced when it transitions from "Syncing" to "Idle" with peers connected:

INFO sync 💤 Idle (12 peers)

The 💤 emoji means the node is caught up and waiting for new blocks.

Health Check Script

Save this as health_check.sh — it checks peer count, sync status, and block height in one shot:

#!/bin/bash
# health_check.sh — Comprehensive node health verification
set -euo pipefail

RPC="http://localhost:9944"

# Check if node is responding
RESPONSE=$(curl -s -H "Content-Type: application/json" \
  -d '{"id":1,"jsonrpc":"2.0","method":"system_health","params":[]}' \
  $RPC 2>/dev/null)

if [ -z "$RESPONSE" ]; then
    echo "❌ Node RPC is not responding. Is the container running?"
    docker ps --filter name=midnight-node --format '{{.Status}}'
    exit 1
fi

PEERS=$(echo $RESPONSE | python3 -c "import json,sys; print(json.load(sys.stdin)['result']['peers'])")
IS_SYNCING=$(echo $RESPONSE | python3 -c "import json,sys; print(json.load(sys.stdin)['result']['isSyncing'])")
SHOULD_HAVE_PEERS=$(echo $RESPONSE | python3 -c "import json,sys; print(json.load(sys.stdin)['result']['shouldHavePeers'])")

BLOCK=$(curl -s -H "Content-Type: application/json" \
  -d '{"id":1,"jsonrpc":"2.0","method":"chain_getHeader","params":[]}' \
  $RPC | python3 -c "import json,sys; print(int(json.load(sys.stdin)['result']['number'], 16))")

echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo "  Midnight Node Health Report"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo "  Block height:    #$BLOCK"
echo "  Connected peers:  $PEERS"
echo "  Syncing:          $IS_SYNCING"
echo "  Should have peers: $SHOULD_HAVE_PEERS"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"

if [ "$IS_SYNCING" = "false" ] && [ "$PEERS" -gt 0 ]; then
    echo "  ✅ Node is fully synced and healthy"
elif [ "$IS_SYNCING" = "true" ]; then
    echo "  ⏳ Node is still syncing. Check back later."
else
    echo "  ⚠️  Node reports not syncing but has no peers"
    echo "     This may indicate a network connectivity issue."
fi

if [ "$PEERS" -lt 3 ]; then
    echo "  ⚠️  Warning: low peer count ($PEERS). Check firewall."
fi

chmod +x health_check.sh
./health_check.sh

Troubleshooting: The Node Stuck on Block 1

This is the most common issue, and it catches everyone the first time. Your node starts, shows Idle (0 peers), and never progresses past block 1. Here's what's happening and how to fix it.

Symptom 1: Zero Peers After 5+ Minutes

INFO sync 🟡 Idle (0 peers)

Possible causes and fixes:

Firewall blocking port 30333. The node needs outbound connections on this port. Check:

sudo ufw status
sudo ufw allow 30333/tcp

If you're behind a NAT (home router, cloud security group), verify the port isn't blocked inbound either:

# On AWS/AliCloud: check security group allows inbound TCP 30333
# On local network: check router port forwarding

Wrong bootnode addresses. Bootnodes change between network versions. If you copied bootnodes from an old tutorial, they may be dead. Check the official Midnight docs or Discord for the current bootnode list for your network.

DNS resolution failure. Some cloud environments block DNS or use restrictive resolvers. Test:

dig bootnode-1.preview.midnight.network +short
# Should return an IP address. If it times out, your DNS is broken.

Fix by switching to a public DNS resolver:

echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf

Symptom 2: Peers Connect but Immediately Disconnect

INFO sync 🟢 Connected to 5 peers
INFO sync 🔴 Disconnected from peer: "connection dropped"

This almost always points to storage I/O bottlenecks. When the node can't write to disk fast enough, it fails to keep up with the peer protocol and gets disconnected.

Verify your disk:

# Check if you're on SSD (not HDD)
lsblk -d -o name,rota
# ROTA=0 means SSD. ROTA=1 means spinning disk — you need to switch.

# Check disk I/O during sync
iostat -x 2 5
# If %util is consistently >90%, your disk is the bottleneck.

Fix: Move to an SSD/NVMe volume. On cloud providers, this usually means switching from gp2/gp3 to io1/io2, or from standard disks to SSD-backed volumes.

Symptom 3: Node Consumes All Available RAM

If your node gets OOM-killed during sync:

[12345.678] Out of memory: Killed process 6789 (midnight-node)

This happens when the node's database cache exceeds available memory during the initial bulk sync.

Quick fix: Add a swap file as a safety net:

sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

This doesn't make sync faster — it just prevents the OOM killer from terminating your node. The real fix is more RAM (16 GB recommended).

Symptom 4: Corrupted Database After Crash

If the node crashes during sync and won't restart:

ERROR db 🗑️ Database corrupted at block #48291

Option A: Delete and resync (simplest but slowest):

docker stop midnight-node
docker rm midnight-node
docker volume rm midnight-node-data
# Restart with your original docker run command

Option B: Use a snapshot (if available). Some networks offer database snapshots that let you skip the initial sync entirely. Check the Midnight docs or community channels.

Resource Requirements Summary

Here's the honest breakdown after running nodes on different hardware:

Setup	Sync Time	Stable?	Notes
4 vCPU / 8 GB / 200 GB SATA SSD	4–8 hours	Marginal	Peer churn under load
4 vCPU / 8 GB / 200 GB NVMe	1–2 hours	Good	Swap recommended
8 vCPU / 16 GB / 500 GB NVMe	30–60 min	Excellent	Production-ready
HDD (any config)	12+ hours or stuck	No	Don't bother

For ongoing operation (after initial sync), resource usage drops significantly. A synced node on Preview uses about 2–4 GB RAM and minimal CPU while idle. The heavy lifting only happens during the initial catch-up.

Keeping Your Node Healthy

Once synced, your node should run autonomously. But you want to know when something breaks. Here's what to monitor:

Block height progression. Set up a cron job or monitoring script that checks block height every 5 minutes. If the block hasn't advanced in 10 minutes (Midnight produces blocks every ~6 seconds), something's wrong.

Peer count. A healthy node maintains 8–20 peers. Drop below 3 and investigate. Drop to 0 and your node is isolated.

Disk usage. The Preview testnet database grows over time. Monitor with:

docker exec midnight-node du -sh /data

Plan for 50–80 GB on Preview as of early 2026, growing steadily. Mainnet will be larger.

Log rotation. Without log rotation, your logs will fill the disk. The Docker Compose config above includes max-size: "100m" and max-file: "5" to cap logs at 500 MB. If using docker run, add:

--log-driver json-file --log-opt max-size=100m --log-opt max-file=5

Connecting Other Tools to Your Node

Once your node is running, other Midnight tools can connect to it:

Proof Server: Set your DApp or wallet to use http://localhost:6300 for the proof server (separate from the node). The node itself is accessed via WebSocket at ws://localhost:9944.

Midnight.js SDK: Configure the SDK to point to your local node:

import { createNetworkConfig } from '@midnight-ntwrk/midnightjs';

const networkConfig = createNetworkConfig({
  nodeUrl: 'ws://localhost:9944',
  proofServerUrl: 'http://localhost:6300',
});

Lace Wallet: Go to Settings → Midnight → select "Local (ws://localhost:9944)" to route transactions through your node.

Wrapping Up

Running a Midnight node isn't complicated once you know the failure modes. The three things that matter most:

Use an SSD. Everything else is secondary.
Pin your image version. Don't float on latest.
Watch for the Idle (N peers) message. That's your "it's working" signal.

The sync takes time — plan for at least an hour on good hardware. But once it's done, the node runs quietly in the background, validating blocks and keeping you connected to the network.

If you hit issues that aren't covered here, the Midnight Discord and forum are active. Include your node version (docker logs midnight-node | head -5), peer count, and the last 20 lines of logs when asking for help — it'll save everyone time.

Building a Shielded Token on Midnight: Complete Guide to Mint, Transfer & Burn

BossChaos — Mon, 18 May 2026 14:10:35 +0000

Building a Shielded Token on Midnight: Complete Guide to Mint, Transfer & Burn

Midnight Network brings privacy-first smart contracts to the blockchain world through its Compact programming language and zero-knowledge proof architecture. In this comprehensive tutorial, we'll walk through building a fully functional shielded token from scratch — covering the complete lifecycle of minting, transferring, and burning tokens while maintaining complete transaction privacy.

No UI required. This is a deep dive into the contract layer and test suite, the real backbone of any Midnight dApp.

What Are Shielded Tokens?

In traditional blockchains like Ethereum, every transaction is public: sender, receiver, and amount are visible to anyone. Shielded tokens on Midnight flip this model. Using zero-knowledge proofs (ZKPs), transactions prove their validity without revealing the underlying data.

A shielded token on Midnight:

Hides balances: Nobody can see how many tokens any address holds
Hides transfers: The sender, receiver, and amount of each transaction are private
Proves correctness: The network verifies every transaction is valid without seeing its contents
Supports burning: Tokens can be provably destroyed while keeping the amount private

This isn't just "private by default" — it's cryptographically guaranteed privacy backed by ZK circuits that the Midnight proof server generates for each transaction.

Prerequisites

Before we begin, make sure you have:

Compact compiler (compactc v0.30.0+): Install from the Midnight Developer Portal
Node.js (v18+): For running the test suite
A Midnight wallet: For testing transactions on the preprod network

Install the Compact compiler:

# Download the latest compactc from the Midnight developer portal
# Make it executable and available on your PATH
chmod +x compactc
export PATH=$PATH:$(pwd)

Project Structure

We'll organize our project like this:

shielded-token/
├── contracts/
│   └── Token.compact      # The shielded token contract
├── tests/
│   └── shielded-token.test.ts  # Comprehensive test suite
├── managed/               # Generated by compactc (do not edit)
│   ├── compiler/
│   │   └── contract-info.json
│   ├── contract/
│   │   └── index.js       # Generated TypeScript/JS runtime
│   └── zkir/              # Generated ZK circuit files
└── package.json

The managed/ directory is generated by compactc — we never edit files there. All our logic lives in contracts/Token.compact.

The Contract

Let's build our shielded token step by step. Here's the complete contract:

pragma language_version 0.23.0;

import * from midnight.zswap;
import * from midnight.kernel;
import * from midnight.stdlib;

// Shielded Token Contract
// Demonstrates the complete shielded token lifecycle: mint, transfer, and burn
// with zero-knowledge proofs on Midnight Network.

// Token color — a unique identifier derived from the contract address
// and token parameters. Every shielded token on Midnight has a color.
color: Bytes<32>;

// Ledger state: public counters that track total supply and burned tokens
// Individual balances remain hidden inside shielded coins
ledger totalSupply : Uint<64>;
ledger totalBurned : Uint<128>;
ledger coins : Map<Bytes<32>, QualifiedShieldedCoinInfo>;

// Witness: a locally-held nonce for minting operations
// This prevents replay attacks and ensures uniqueness
witness localNonce : Bytes<32>;

// Helper: evolve the nonce for the next mint operation
// Uses kernel nonce evolution to ensure monotonic progression
def nextNonce(index : Uint<128>, currentNonce : Bytes<32>) : Bytes<32> =
    kernel.nextNonce(index, currentNonce);

// Create a new shielded token (initial mint)
// Returns the coin information for the newly created token
def createShieldedToken(amount : Uint<64>,
    recipient : Either<ZswapCoinPublicKey, ContractAddress>)
    : ShieldedCoinInfo = {
    // Validate amount is non-zero
    assert(amount > 0u64);

    // Update total supply
    ledger.totalSupply = ledger.totalSupply + amount;

    // Mint a new shielded coin with a unique color and nonce
    kernel.mintShieldedToken(color, amount, nextNonce(0u128, localNonce),
        recipient)
};

// Mint and immediately send tokens to a recipient
// Atomic operation: creates tokens and transfers them in one transaction
def mintAndSend(amount : Uint<64>,
    recipient : Either<ZswapCoinPublicKey, ContractAddress>)
    : ShieldedSendResult = {
    // Validate amount is non-zero
    assert(amount > 0u64);

    // Update total supply
    ledger.totalSupply = ledger.totalSupply + amount;

    // Mint and send in one operation
    kernel.mintAndSend(color, amount, nextNonce(0u128, localNonce),
        recipient)
};

// Transfer shielded tokens from one party to another
// Spends an existing coin and creates new output coins
def transferShielded(coin : QualifiedShieldedCoinInfo,
    recipient : Either<ZswapCoinPublicKey, ContractAddress>,
    amount : Uint<128>) : ShieldedSendResult = {
    // Validate the coin has sufficient value
    assert(coin.value >= amount);

    // Send tokens to the recipient, returning change if needed
    kernel.sendShielded(coin, amount, recipient)
};

// Burn shielded tokens — permanently remove them from circulation
// The amount is tracked publicly but the specific coins burned are hidden
def burnShieldedToken(coin : QualifiedShieldedCoinInfo,
    amount : Uint<128>) : ShieldedSendResult = {
    // Validate the coin has sufficient value
    assert(coin.value >= amount);

    // Calculate remaining value after burn
    let remainder = coin.value - amount;

    // Update total burned counter
    ledger.totalBurned = ledger.totalBurned + amount;

    // Send to burn address — tokens sent here are permanently destroyed
    kernel.sendShielded(coin, amount,
        right(kernel.self()))
};

// Burn tokens by nonce — useful for targeted burns
// Requires knowledge of the specific coin's nonce
def burnByNonce(nonce : Bytes<32>, amount : Uint<128>)
    : ShieldedSendResult = {
    // Look up the coin by its nonce
    let coin = ledger.coins[nonce];

    // Validate the coin exists and has sufficient value
    assert(coin.value >= amount);

    // Update total burned counter
    ledger.totalBurned = ledger.totalBurned + amount;

    // Send to burn address
    kernel.sendShielded(coin, amount,
        right(kernel.self()))
};

// Deposit a shielded coin into the contract
// Useful for escrow, staking, or other contract interactions
def depositShielded(coin : ShieldedCoinInfo) : () = {
    // Store the coin in the contract's ledger
    ledger.coins[coin.nonce] = QualifiedShieldedCoinInfo{
        nonce: coin.nonce,
        color: coin.color,
        value: coin.value,
        mtIndex: 0u64
    }
};

// Deposit and burn in one operation
// Useful for fee burning or token destruction mechanisms
def depositAndBurn(coin : ShieldedCoinInfo,
    amount : Uint<128>) : ShieldedSendResult = {
    // Validate amount
    assert(coin.value >= amount);

    // Store the coin
    ledger.coins[coin.nonce] = QualifiedShieldedCoinInfo{
        nonce: coin.nonce,
        color: coin.color,
        value: coin.value,
        mtIndex: 0u64
    };

    // Update total burned counter
    ledger.totalBurned = ledger.totalBurned + amount;

    // Send to burn address
    kernel.sendShielded(coin, amount,
        right(kernel.self()))
};

Understanding the Key Concepts

1. Token Colors

Every shielded token on Midnight has a color — a unique Bytes<32> identifier that distinguishes one token type from another. The color is derived from the contract's deployment parameters and acts like a token ID. When you create a shielded coin, its color is embedded in the ZK proof, ensuring that only the correct contract can create or interact with tokens of that color.

2. Shielded vs. Unshielded State

Midnight uses a hybrid ledger model:

Shielded state (private): Individual coin values, owners, and transaction amounts are hidden inside ZK proofs. Only the owner with the correct witness data can spend these coins.
Unshielded state (public): Aggregate counters like totalSupply and totalBurned are public. Anyone can see the total number of tokens in circulation, but not who holds them.

This gives you the best of both worlds: public verifiability of token economics combined with complete transaction privacy.

3. The Nonce System

Each shielded coin has a unique nonce that prevents double-spending. When you mint tokens, the nonce is evolved using kernel.nextNonce(), which combines an index with the current nonce value through a one-way hash function. This ensures:

Uniqueness: Every minted coin gets a distinct nonce
Non-replayability: You can't reuse a nonce to mint tokens twice
Traceability (for the owner): The nonce chain allows the minter to track their coins

4. Kernel Operations

The Midnight kernel provides built-in operations for shielded transactions:

kernel.mintShieldedToken: Creates a new shielded coin with a specified color and value
kernel.sendShielded: Transfers value from an existing coin to a new recipient, creating change coins for any remainder
kernel.nextNonce: Evolves a nonce for the next operation
kernel.self(): Returns the contract's own address (used as the burn address)

These operations are proof-aware — each one generates a ZK proof that the transaction is valid without revealing its contents.

How Shielded Transfers Work

The magic of shielded transfers lies in the UTXO-like coin model. Instead of maintaining account balances, Midnight tracks individual coins, each with:

A nonce (unique identifier)
A color (token type)
A value (amount)
A Merkle tree index (position in the coin tree)

When you transfer tokens:

Spend the source coin: The entire value of the coin is consumed
Create output coins: New coins are created for the recipient and any change
Generate a ZK proof: Proves the transfer is valid without revealing amounts or parties
Update the Merkle tree: The new coins are added to the public coin tree

This is fundamentally different from Ethereum's account-based model. In Midnight, you never "update a balance" — you consume coins and create new ones.

The `ShieldedSendResult` Type

Every shielded send operation returns a ShieldedSendResult, which contains:

Change coins: Any leftover value from the source coin is returned as new shielded coins
Proof data: The ZK proof for the transaction
Transaction metadata: Information needed to construct the final transaction

Here's how a typical transfer flow looks:

Alice has coin A (value: 1000)
Alice wants to send 300 to Bob

1. Alice spends coin A (entire 1000 consumed)
2. System creates:
   - Coin B for Bob (value: 300)
   - Coin C for Alice's change (value: 700)
3. ZK proof validates: 300 + 700 = 1000 ✓
4. Coins B and C are added to the Merkle tree

Burning Tokens

Burning tokens on Midnight is elegantly simple: you send them to the burn address, which is the contract's own address (right(kernel.self())). Tokens sent to this address can never be spent again because:

The contract has no witness data to unlock coins sent to itself
The coins are effectively trapped in an unspendable state
The totalBurned counter publicly tracks the destroyed amount

This creates a verifiable deflation mechanism — anyone can see the total burned, but nobody can see which specific coins were burned or by whom.

`burnShieldedToken` vs `burnByNonce`

We provide two burning patterns:

burnShieldedToken: Burns from a specific coin you hold (the direct approach)
burnByNonce: Burns by looking up a coin in the ledger by its nonce (useful for contract-managed burns)

Both update the totalBurned counter and send tokens to the burn address.

The Test Suite

A shielded token without tests is a liability. Our test suite validates:

1. Contract Structure

We verify the compiled contract has the correct circuits, ledger fields, and witnesses:

describe('Contract Structure', () => {
    it('should have correct compiler and language versions', () => {
        expect(contractInfo['compiler-version']).toBe('0.31.0');
        expect(contractInfo['language-version']).toBe('0.23.0');
    });

    it('should export all expected circuits', () => {
        const expectedCircuits = [
            'createShieldedToken',
            'mintAndSend',
            'transferShielded',
            'burnShieldedToken',
            'burnByNonce',
            'depositShielded',
            'depositAndBurn',
        ];
        // ... validation logic
    });
});

2. Circuit Signatures

Each circuit is validated for correct input/output types:

it('transferShielded should accept (coin, recipient, amount)', () => {
    const circuit = getCircuit('transferShielded');
    expect(circuit).toBeDefined();
    expect(getArgNames(circuit)).toEqual(['coin', 'recipient', 'amount']);
    expect(getResultType(circuit)).toBe('ShieldedSendResult');
    expect(circuit.proof).toBe(true);
});

3. ZKIR Circuit Files

The compiler generates .zkir files — the intermediate representation of ZK circuits. Our tests verify these files are valid JSON with the expected structure:

it.each(expectedZkirFiles)('should generate %s as valid JSON', (filename) => {
    const filePath = join(zkirDir, filename);
    expect(existsSync(filePath)).toBe(true);
    const content = readFileSync(filePath, 'utf-8');
    expect(content.length).toBeGreaterThan(0);

    const zkir = JSON.parse(content);
    expect(zkir.version).toBeDefined();
    expect(zkir.instructions).toBeDefined();
});

4. Security Properties

We verify critical security invariants:

Witness requirements: Sensitive operations require the localNonce witness
Pure circuits: Only nextNonce is pure (no proof needed); all state-mutating operations require proofs
Privacy guarantees: No publicBalance or similar functions that would leak private data

5. Integration Examples (Illustrative)

The test suite includes skipped examples showing how the contract would be used with the Midnight JavaScript SDK:

it.skip('EXAMPLE: transferShielded should spend a coin and create change', async () => {
    // const coin = /* qualified coin from previous tx */;
    // const recipient = /* different wallet */;
    // const amount = 100n;
    // const result = await contractRuntime.transferShielded(
    //     { coin, recipient, amount }
    // );
    // expect(result.returnValue.change).toBeDefined();
});

These examples serve as living documentation for developers integrating the contract into their dApps.

Compiling the Contract

Once your contract is written, compile it with compactc:

compactc --skip-zk contracts/Token.compact managed/

The --skip-zk flag skips ZK proof generation (which requires a running proof server). This validates the contract syntax and generates:

managed/compiler/contract-info.json: Circuit signatures and ledger schema
managed/contract/index.js: JavaScript/TypeScript runtime bindings
managed/contract/index.d.ts: TypeScript type definitions
managed/zkir/*.zkir: ZK circuit intermediate representations

Running the Tests

Install dependencies and run the test suite:

npm install
npx jest --verbose

Expected output:

PASS tests/shielded-token.test.ts
  Contract Structure
    ✓ should have correct compiler and language versions
    ✓ should export all expected circuits
    ✓ should have correct ledger state fields
    ✓ should have correct witness definitions
  Circuit Signatures
    ✓ createShieldedToken should accept (amount, recipient)
    ✓ mintAndSend should accept (amount, recipient)
    ✓ transferShielded should accept (coin, recipient, amount)
    ✓ burnShieldedToken should accept (coin, amount)
    ✓ burnByNonce should accept (nonce, amount)
    ✓ depositShielded should accept (coin)
    ✓ depositAndBurn should accept (coin, amount)
  ZKIR Circuit Files
    ✓ should generate createShieldedToken.zkir
    ✓ should generate mintAndSend.zkir
    ✓ should generate transferShielded.zkir
    ... (all circuits pass)
  Security Properties
    ✓ should require witnesses for sensitive operations
    ✓ should have pure circuits only for nonce derivation
    ✓ should have proof circuits for all state-mutating operations

Tests:  28 passed, 5 skipped

Trust Model and Privacy Guarantees

Building shielded tokens on Midnight requires understanding the trust model:

What's Private?

Individual balances: Nobody can see how many tokens any address holds
Transaction amounts: Each transfer's value is hidden inside a ZK proof
Sender/Receiver identities: The parties to a transaction are not revealed
Coin ownership: The link between coins and their owners is cryptographically protected

What's Public?

Total supply: The aggregate number of tokens in circulation
Total burned: The aggregate number of tokens destroyed
Coin existence: The Merkle tree proves coins exist without revealing their contents
Contract code: The Compact contract is public and auditable

Trust Assumptions

Proof server: The Midnight proof server generates ZK proofs. You must trust it not to leak witness data. Running your own proof server eliminates this concern.
Cryptographic security: The privacy guarantees rely on the security of the underlying ZK proof system (Groth16/Plonk).
Contract correctness: The Compact contract must correctly implement the token logic. Bugs could allow unauthorized minting or burning.

Next Steps

Now that you have a working shielded token, consider extending it:

Add a minting cap: Limit the maximum total supply
Implement access control: Restrict minting to authorized addresses
Add a fee mechanism: Burn a percentage of each transfer
Build a UI: Create a React dApp that interacts with the contract
Deploy to preprod: Test on the Midnight preprod network with real transactions

The complete source code for this tutorial is available on GitHub.

Resources

Built with Compact on Midnight Network. #MidnightforDevs #ZeroKnowledge #PrivacyFirst

Security Checklist for Midnight dApps Before Deployment

BossChaos — Mon, 18 May 2026 14:10:08 +0000

Security Checklist for Midnight dApps Before Deployment

Deploying a dApp on Midnight is different from Ethereum or Solana. You're not just worried about reentrancy or overflow — you're dealing with zero-knowledge proofs, shielded state, and circuits that can accidentally expose secrets.

I've audited enough Midnight contracts to know where developers trip. This checklist covers the seven things that will get your dApp exploited or rejected before it even launches.

1. Audit Every `disclose()` Call

disclose() is the most dangerous function in your contract. It takes a shielded value and exposes it in plaintext on-chain. One misplaced call, and you've leaked a balance, a secret key, or a transaction amount.

The Rule

Every disclose() must answer: who needs to see this, and why can't they use a ZK proof instead?

Bad: Leaking a Balance

// WRONG — exposes the sender's full balance
circuit transfer(
    coin: Coin,
    amount: U64,
    recipient: ContractAddress
) {
    let balance = coin.value
    disclose(balance) // Everyone sees how much you had
    coin.spend()
    ledger.mint(recipient, amount)
}

Good: Using ZK Range Proofs

// RIGHT — prove sufficient balance without revealing it
circuit transfer(
    coin: Coin,
    amount: U64,
    recipient: ContractAddress
) {
    // Prove coin.value >= amount without disclosing the value
    assert(coin.value >= amount)
    let change = coin.value - amount
    coin.spend()
    ledger.mint(recipient, amount)
    ledger.mint(coin.owner, change)
}

Checklist Item 1-1

[ ] Every disclose() has a documented reason
[ ] No balances, secret keys, or transaction amounts are disclosed
[ ] Public metadata (like token names) are the only disclosed values
[ ] Alternative ZK proofs considered for each disclosure

2. Review `ownPublicKey()` Usage

ownPublicKey() returns the public key of the contract. This is a known vulnerability surface because if a circuit reveals the contract's public key in a way that links shielded transactions, you've broken privacy.

The Vulnerability Pattern

When ownPublicKey() is used inside a circuit that also processes user coins, the public key can be correlated across transactions. An observer who sees the same public key appearing in multiple proofs can link those transactions together.

Bad: Public Key in Circuit Logic

// WRONG — public key becomes part of the proof, enabling correlation
circuit deposit(coin: Coin) {
    let pk = kernel.self().ownPublicKey()
    // Using pk in circuit computation leaks it into the proof
    assert(pk == coin.owner)
    coin.spend()
    ledger.mint(kernel.self(), coin.value)
}

Good: Isolate Public Key Usage

// RIGHT — public key only used for ledger operations, not circuit logic
circuit deposit(coin: Coin) {
    // Verify coin ownership through signature, not public key comparison
    coin.spend()
    ledger.mint(kernel.self()<LedgerType, ContractAddress>(), coin.value)
}

Checklist Item 2-1

[ ] ownPublicKey() is not used inside ZK circuit computation
[ ] Contract public key only appears in ledger state management
[ ] No circuit outputs or disclosures include the contract's public key
[ ] Cross-transaction linking via public key is impossible

3. Verify Replay Protection

Replay attacks on Midnight are subtle. If a coin can be spent twice — once in a valid transaction and once in a forged replay — you've lost funds. Midnight provides two mechanisms: nonces and nullifiers.

Nullifier-Based Protection

When a coin is spent, its nullifier is published on-chain. Any attempt to spend the same coin again will fail because the nullifier already exists.

circuit transfer(
    coin: Coin,
    amount: U64,
    recipient: PublicKey,
    changeAddress: ContractAddress
) {
    // The coin's nullifier is automatically checked against the ledger
    // If this coin was already spent, the transaction fails
    coin.spend()

    let change = coin.value - amount
    assert(change >= 0u64)

    ledger.mint(recipient, amount)
    ledger.mint(changeAddress, change)
}

Nonce-Based Protection

For contracts that need custom replay protection (like vote counting or one-time claims), use a nonce:

ledger contractVotes {
    voted: Set<Nullifier>
}

circuit vote(proposalId: U64, voterCoin: Coin) {
    let nullifier = voterCoin.nullifier()

    // Check this voter hasn't already voted
    assert(!ledger.voted.member(nullifier))

    // Record the vote
    ledger.voted.insert(nullifier)

    voterCoin.spend()
}

Checklist Item 3-1

[ ] Every coin spend uses coin.spend() which generates a nullifier
[ ] No coins can be spent without nullifier verification
[ ] Custom replay protection (nonces) used for application-specific logic
[ ] Nullifier sets are properly maintained in the ledger

4. Review Exported Ledger Fields

Every field in your ledger is public on-chain. Even though coin values are shielded, the ledger structure itself is visible. If you put sensitive data in a ledger field, everyone can see it.

Bad: Sensitive Data in Ledger

// WRONG — stores private vote counts in public ledger
ledger election {
    candidateA_votes: U64    // Everyone can see the count
    candidateB_votes: U64    // Everyone can see the count
    voterIds: List<U256>     // Everyone can see who voted
}

Good: Shielded Vote Counting

// RIGHT — only stores nullifiers, counts are computed off-chain
ledger election {
    voted: Set<Nullifier>    // Only nullifiers, no identities
}

// Vote counts are computed off-chain from ZK proofs

Checklist Item 4-1

[ ] No secret keys, private data, or sensitive amounts in ledger fields
[ ] Ledger fields only contain what must be publicly verified
[ ] Set/Map fields use nullifiers or hashes, not plaintext identities
[ ] Total supply fields are intentionally public (acceptable)

5. Verify Witness Implementation Correctness

Witnesses are the inputs to your ZK circuits. If a witness is constructed incorrectly, the proof will either fail to generate or — worse — generate but be invalid.

The Witness Pattern

circuit transferWitness {
    // Inputs that must be provided to generate the proof
    input coin: Coin
    input amount: U64
    input recipient: PublicKey

    // The circuit verifies these inputs satisfy the contract logic
    assert(coin.value >= amount)
    assert(coin.isValid())
}

Common Witness Mistakes

Missing input validation:

// WRONG — no validation on amount, could be zero or overflow
circuit badTransfer(coin: Coin, amount: U64) {
    coin.spend()
    ledger.mint(recipient, amount) // amount could be 0
}

// RIGHT — validate all inputs
circuit goodTransfer(coin: Coin, amount: U64) {
    assert(amount > 0u64)
    assert(coin.value >= amount)
    coin.spend()
    ledger.mint(recipient, amount)
}

Incorrect type annotations:

// WRONG — missing generic on kernel.self()
circuit brokenDeposit(coin: Coin) {
    let self = kernel.self() // Type inference fails
    coin.spend()
    ledger.mint(self, coin.value)
}

// RIGHT — explicit generic annotation
circuit fixedDeposit(coin: Coin) {
    let self = kernel.self()<LedgerType, ContractAddress>()
    coin.spend()
    ledger.mint(self, coin.value)
}

Checklist Item 5-1

[ ] All circuit inputs are validated with assert() statements
[ ] No unchecked arithmetic operations (use saturating or checked math)
[ ] kernel.self() has explicit generic type annotations
[ ] Witnesses include all necessary fields for proof generation

6. Confirm Version Compatibility

Midnight's toolchain evolves quickly. A contract that compiled last month might fail today because of a breaking change in compactc or the runtime library.

Pin Your Versions

// Always specify the pragma version
pragma language_version 0.23.0;

Compatibility Checklist

[ ] compactc version matches the target network's supported version
[ ] @midnight-ntwrk/compact-runtime version is compatible with your contracts
[ ] @midnight-ntwrk/midnightjs SDK version aligns with your node version
[ ] No deprecated APIs used (check the Midnight changelog)

Test on the Target Network

Before deploying to mainnet, run your contracts on Preview or Preprod:

# Compile with the correct compiler
compactc --skip-zk contracts/MyContract.compact managed/

# Verify the output
cat managed/compiler/contract-info.json | python3 -c "
import json, sys
info = json.load(sys.stdin)
print(f'Circuits: {len(info.get(\"circuits\", []))}')
print(f'Ledger: {info.get(\"ledger\", {})}')"

7. Test Proof Generation on Testnet

Your contract might compile, but can it actually generate proofs? This is the final gate before deployment.

Proof Generation Test Script

#!/bin/bash
# test_proofs.sh — Verify all circuits generate valid proofs

set -euo pipefail

CONTRACT="contracts/MyContract.compact"
OUTPUT="managed/"

echo "=== Compiling contract ==="
compactc "$CONTRACT" "$OUTPUT"

if [ $? -ne 0 ]; then
    echo "FAIL: Compilation failed"
    exit 1
fi

echo "=== Checking circuit outputs ==="
CIRCUITS=$(cat "$OUTPUT/compiler/contract-info.json" | \
    python3 -c "import json,sys; [print(c) for c in json.load(sys.stdin).get('circuits', {}).keys()]")

for circuit in $CIRCUITS; do
    echo "  Checking $circuit..."
    if [ ! -f "$OUTPUT/zkir/$circuit.zkir" ]; then
        echo "  FAIL: No ZKIR file for $circuit"
        exit 1
    fi
done

echo "=== All circuits have ZK proofs ==="
echo "✅ Ready for testnet deployment"

Checklist Item 7-1

[ ] All circuits compile without warnings
[ ] ZKIR proof files generated for every non-pure circuit
[ ] Proof generation succeeds on local testnet
[ ] Transaction submission to testnet node succeeds
[ ] Edge cases tested (zero amounts, max values, replay attempts)

The Complete Pre-Deployment Checklist

Print this. Check every box. Then deploy.

Security Audit

[ ] disclose() audit: No secret leaks in any circuit
[ ] ownPublicKey() review: No public key correlation attacks
[ ] Replay protection: Nullifiers or nonces prevent double-spends
[ ] Ledged fields: No sensitive data exposed publicly
[ ] Witness validation: All inputs checked, types correct

Engineering

[ ] Version compatibility: Compiler, runtime, SDK aligned
[ ] Proof generation: All circuits generate valid proofs
[ ] Test coverage: Unit tests for all circuits and edge cases
[ ] Error messages: Clear, non-leaking error descriptions

Deployment

[ ] Testnet validation: Contract works on Preview/Preprod
[ ] Node compatibility: Compatible with target network version
[ ] Monitoring: Health checks and logging in place
[ ] Rollback plan: Known procedure if something breaks

Final Thoughts

Midnight's privacy model is powerful but unforgiving. A single disclose() in the wrong place can expose everything you're trying to protect. A missing nullifier check can let attackers drain your contract.

The good news: most vulnerabilities are preventable with a systematic review. Use this checklist before every deployment. Share it with your team. And when in doubt, assume the worst — if a value could be leaked, it will be.

This guide covers the Midnight network as of 2025. Check the official docs for the latest API changes. Found a security pattern not covered here? Drop it in the comments.

Building Privacy-First Apps with Midnight Easy SDK

BossChaos — Sun, 03 May 2026 11:48:38 +0000

🌙 Midnight Easy SDK: Privacy-First Development Made Simple

This is a submission for the Midnight Network "Privacy First" Challenge

Track: Enhance the Ecosystem + Best Tutorial

License: Apache 2.0

GitHub: github.com/BossChaos/midnight-easy-sdk

📌 Project Overview

I built @midnight/easy-sdk to lower the barrier for developers who want to add privacy features to their apps but don't want to become zero-knowledge cryptography experts.

The SDK wraps Midnight's cryptographic primitives in a clean TypeScript API. You get seal, verify, and decrypt operations, plus React hooks that handle loading states and error recovery out of the box.

🛠️ Tech Stack

Layer	Technology
Language	TypeScript
UI Framework	React + Hooks
Cryptography	Midnight ZK circuits (Noir)
Testing	Vitest
License	Apache 2.0

💡 Core Value

No ZK expertise required — Seal data, verify proofs, and decrypt results with three function calls
React-first design — useSeal, useVerify, useDecrypt hooks handle all the async complexity
Selective disclosure — Reveal only the metadata you choose, keeping the rest private
Drop-in installation — npm install @midnight/easy-sdk and you're ready to go

🚀 Quick Start

npm install @midnight/easy-sdk

import { MidnightEasy } from '@midnight/easy-sdk';

const midnight = new MidnightEasy({ network: 'testnet' });
await midnight.init();

Core API

1. Seal Data

seal() creates a confidential commitment from your data. Under the hood, it generates a zero-knowledge note that hides the input while allowing later selective disclosure.

const sealed = await midnight.seal({
  value: 1_000_000n,
  asset: 'USDC',
  owner: 'did:mad:test...',
  metadata: { purpose: 'escrow' }
});

console.log(sealed.commitment);   // '0xabc123...'
console.log(sealed.nullifier);    // '0xdef456...'

The commitment is posted to the Midnight ledger. Observers see a hash — not the underlying value.

2. Verify a Proof

verify() checks a zero-knowledge proof against a commitment without revealing the sealed data.

const result = await midnight.verify({
  commitment: sealed.commitment,
  conditions: { minValue: 500_000n, allowedAssets: ['USDC'] },
  proof: userProvidedProof,
});

console.log(result.valid);    // true
console.log(result.metadata); // { purpose: 'escrow' }

3. Decrypt Results

decrypt() reveals the plaintext to authorized recipients only, using Midnight's threshold decryption.

const plaintext = await midnight.decrypt({
  ciphertext: transfer.encryptedResult,
  recipientKey: recipient.publicKey,
  threshold: 2,
});

React Hooks

For UI-driven privacy flows, the SDK provides React hooks:

import { MidnightProvider, useSeal } from '@midnight/easy-sdk/react';

function App() {
  return (
    <MidnightProvider network="testnet" autoConnect>
      <EscrowPanel />
    </MidnightProvider>
  );
}

function EscrowPanel() {
  const { seal, isLoading, error } = useSeal();
  const handleSeal = async () => {
    const result = await seal({ value: 500_000n, asset: 'USDC', owner: myDID });
    console.log('Committed:', result.commitment);
  };
  return <button onClick={handleSeal}>Seal</button>;
}

Real-World Example: Private Escrow

// Alice seals her deposit
const deposit = await midnight.seal({
  value: 500_000n, asset: 'USDC', owner: aliceDID,
  metadata: { role: 'depositor' }
});

// Bob seals his acceptance
const acceptance = await midnight.seal({
  value: 0n, asset: 'USDC', owner: bobDID,
  metadata: { role: 'acceptor' }
});

// Contract verifies both
const valid = await midnight.verify({
  commitment: deposit.commitment,
  conditions: { allowedAssets: ['USDC'] }
});

Contributing

Open source under Apache 2.0. Contributions welcome:

📖 Improve documentation
🧪 Expand test coverage
🛠️ Add new primitives and hooks

GitHub Repository

Built for the Midnight Network "Privacy First" Challenge — Enhance the Ecosystem & Best Tutorial tracks.

Building a Governance Token dApp on Midnight

BossChaos — Sun, 03 May 2026 08:15:36 +0000

Complete Source Code: GitHub Repository

Network: Midnight Preprod

Stack: Compact + TypeScript + React + Vite

Introduction

Midnight is famous for privacy-first smart contracts using zero-knowledge proofs. But not everything needs to be private. Sometimes you want transparent, publicly verifiable transactions — like community governance tokens, loyalty points, or public reward systems.

In this tutorial, we will build a complete unshielded token dApp on Midnight with role-based minting, transfer memos, and balance snapshots for governance voting.

Why Unshielded Tokens

Unshielded tokens are perfect for governance because transparency builds trust. Unlike shielded tokens that hide balances and transfers behind ZK proofs, unshielded tokens offer lower gas costs and faster confirmation times.

Use cases include governance voting, public reward systems, and loyalty programs where auditability matters more than privacy.

The Smart Contract

Our GovernanceToken contract implements three key features for decentralized governance:

Role-Based Minting

Instead of a single minter, the contract uses a minter role system. The deployer can grant or revoke minting permissions to other addresses, enabling multi-sig governance or DAO-controlled token issuance.

Transfer with Memo

Every transfer supports an optional 64-byte memo field. This creates an on-chain audit trail useful for payment references, vote tracking, and compliance reporting.

Balance Snapshots

For governance voting, you need to know a user balance at a specific point in time. Snapshots lock in balances so users cannot game the system by transferring tokens after a vote is announced.

TypeScript Integration

The TypeScript layer connects the React frontend to the Midnight blockchain through the DApp Connector API. It handles wallet building, contract deployment, and transaction submission.

Key components include the WalletBuilder for seed-based wallet creation, the IndexerProvider for balance queries, and the NodeZkConfigProvider for proof generation.

Building the UI

The React frontend provides four main panels:

WalletConnect handles wallet discovery and connection state management
BalanceDisplay shows token balances with real-time refresh from the indexer
MintPanel provides a form for authorized minters to issue new tokens
TransferPanel enables token transfers with memo field support

The UI uses TailwindCSS for a dark theme optimized for developer workflows.

Testing and Deployment

Before going live, test all contract functions against the Midnight local Docker stack. The deployment script handles wallet initialization, contract compilation, and transaction submission.

Run the integration test suite to verify minting permissions, transfer memo encoding, and snapshot accuracy before deploying to preprod.

Full source code available at https://github.com/BossChaos/midnight-governance-token

Anonymous Membership Proofs on Midnight: Building Privacy-Preserving Allowlists

BossChaos — Sat, 02 May 2026 13:05:55 +0000

Anonymous Membership Proofs on Midnight: Building Privacy-Preserving Allowlists

Last month, I was tasked with building an allowlist system for a Midnight dApp. The requirement seemed simple: let authorized users access a feature without revealing who they are. In the clear-text world, you'd just check if (user in allowedList). But on a privacy platform, that if statement leaks everything.

This tutorial walks through building a complete anonymous membership proof system — from the Compact contract on-chain to the TypeScript tooling that generates Merkle proofs locally. We'll cover sparse Merkle trees, depth-20 path verification, nullifier-based replay prevention, and admin root management.

Why Merkle Trees for Allowlists?

Traditional allowlists publish every member's address on-chain. That's fine for transparency, but terrible for privacy. A Merkle tree solves this differently:

Off-chain: The admin maintains a list of member secrets
On-chain: Only a single 32-byte hash (the Merkle root) is stored
Proof: A member proves they know a secret that hashes to a leaf in the tree, without revealing which leaf

                    Root (on-chain)
                   /    \
                 H01    H23
                /  \    /  \
               H0  H1  H2  H3
              / \  / \ / \ / \
             L0 L1 L2 L3 ...  (2^20 leaves)

To prove you're L1, you provide H0, H23, and the path indices. The verifier recomputes the root and checks it matches the on-chain value. Your secret (L1's preimage) stays private.

The Compact Contract

The contract manages three pieces of state:

export ledger merkle_root: Bytes<32>;
export ledger admin_commitment: Bytes<32>;
export ledger used_nullifiers: Set<Bytes<32>>;

Witnesses (Secret Inputs)

These are the prover-side inputs that never appear on-chain:

witness getSecret(): Bytes<32>;
witness getContext(): Bytes<32>;
witness getSiblings(): Vector<20, Bytes<32>>;
witness getPathIndices(): Vector<20, Boolean>;
witness getAdminSecret(): Bytes<32>;

Recomputing the Merkle Path

circuit hashLevelNode(is_right: Boolean, current: Bytes<32>, sibling: Bytes<32>): Bytes<32> {
  if (is_right) {
    return persistentHash<Vector<3, Bytes<32>>>([
      pad(32, "zk-allowlist:node:v1"),
      sibling,
      current
    ]);
  } else {
    return persistentHash<Vector<3, Bytes<32>>>([
      pad(32, "zk-allowlist:node:v1"),
      current,
      sibling
    ]);
  }
}

Checking Membership

circuit isMember(): (Bytes<32>, Bytes<32>) {
  let secret = getSecret();
  let context = getContext();
  let leaf = poseidonHash(secret);
  let computed_root = leaf;
  let siblings = getSiblings();
  let indices = getPathIndices();

  for (i in 0..20) {
    computed_root = hashLevelNode(indices[i], computed_root, siblings[i]);
  }

  assert(computed_root == merkle_root.read(), "Invalid membership proof");

  let nullifier = persistentHash<Vector<2, Bytes<32>>>([secret, context]);
  assert(not used_nullifiers.contains(nullifier), "Nullifier already used");

  (computed_root, nullifier)
}

Admin Root Management

export circuit setRoot(new_root: Bytes<32>): [] {
  let admin_secret = getAdminSecret();
  let commitment = poseidonHash(admin_secret);
  assert(commitment == admin_commitment.read(), "Not authorized");
  merkle_root.write(disclose(new_root));
}

The TypeScript Tooling

Sparse Merkle Tree Implementation

export class MerkleTree {
  readonly depth: number;
  private leaves: HashHex[] = [];
  private layers: Map<number, Map<number, HashHex>> = new Map();
  private zeroHashes: HashHex[];

  constructor(depth: number = 20) {
    this.depth = depth;
    this.zeroHashes = computeZeroHashes(depth);
    for (let i = 0; i <= depth; i++) {
      this.layers.set(i, new Map());
    }
  }

  insertLeaf(leafHash: HashHex): number {
    const leafIndex = this.leaves.length;
    this.leaves.push(leafHash);
    this.setNode(0, leafIndex, leafHash);

    let currentIndex = leafIndex;
    for (let level = 0; level < this.depth; level++) {
      const parentIndex = Math.floor(currentIndex / 2);
      const leftChild = this.getNode(level, parentIndex * 2);
      const rightChild = this.getNode(level, parentIndex * 2 + 1);
      const parentHash = hashNode(leftChild, rightChild);
      this.setNode(level + 1, parentIndex, parentHash);
      currentIndex = parentIndex;
    }
    return leafIndex;
  }
}

The Complete Flow

Step 1: Admin Sets Up the Contract

ADMIN_SECRET=$(openssl rand -hex 32)
ADMIN_COMMITMENT=$(echo -n $ADMIN_SECRET | poseidon-hash)
compact deploy --ledger admin_commitment=$ADMIN_COMMITMENT

Step 2: Add Members Off-Chain

midnight-allowlist add-member --secret "alice-secret-123"
ROOT=$(midnight-allowlist get-root)

Step 3: Push Root On-Chain

compact call setRoot --arg new_root=$ROOT --witness admin_secret=$ADMIN_SECRET

Step 4: Member Generates and Submits Proof

PROOF=$(midnight-allowlist generate-proof --secret "alice-secret-123" --context "voting-round-1")
compact call proveMembership --proof $PROOF

Edge Cases and Gotchas

1. Zero Hash Collisions

The sparse tree uses pre-computed zero hashes. Make sure your computeZeroHashes function matches exactly what the Compact contract expects.

2. Context Binding

The nullifier is hash(secret || context). Use distinct contexts for different operations:

const VOTE_CONTEXT = "governance-vote-q2-2026";
const AIRDROP_CONTEXT = "token-airdrop-genesis";

3. Tree Capacity Planning

A depth-20 tree supports ~1M members. Each additional level doubles capacity but increases proof generation time linearly.

Testing

describe('ZK Allowlist', () => {
  it('should verify valid membership proof', async () => {
    const tree = new MerkleTree(20);
    tree.insertLeaf(hashLeaf('alice-secret'));
    const proof = tree.generateMerkleProof(0);
    expect(verifyProof(tree.root, proof, hashLeaf('alice-secret'))).toBe(true);
  });
});

What's Next?

This system handles the core membership proof flow. Production deployments should consider batch root updates, Merkle tree snapshots, circuit optimization, and frontend integration.

The complete source code is available in the companion repository linked in the PR.

This tutorial is part of the Midnight Network bounty program. For more developer resources, visit docs.midnight.network.