Forem: UtkarshVarma

Building midnight-agent-skills: AI-Powered Development for Privacy-First Blockchain Made Easy

UtkarshVarma — Sun, 18 Jan 2026 05:12:31 +0000

By Utkarsh Varma, Webisoft Development Labs

The Problem: Privacy Blockchain Development is Hard

Building on Midnight Network isn't like building on Ethereum or Solana. It's a completely different paradigm:

New Language: Compact, a domain-specific language for zero-knowledge circuits
Privacy Primitives: Shielded/unshielded states, selective disclosure, witnesses
Complex Tooling: Proof servers, indexers, specialized nodes
Limited Resources: Fewer tutorials, examples, and Stack Overflow answers

When I started building on Midnight, I spent hours:

Debugging pragma syntax errors (is it >= 0.16 && <= 0.18 or >= 0.19?)
Figuring out why circuit fn(): Void doesn't work (it's [], not Void)
Understanding the difference between ledger {} block syntax (deprecated) vs export ledger (correct)
Setting up local infrastructure with the right version combinations

Every AI coding assistant I used—Claude, Cursor, Copilot—would generate wrong Compact code because they were trained on outdated or incorrect syntax.

The Insight: AI Agents Need Midnight-Specific Knowledge

AI coding assistants are incredibly powerful, but they have a knowledge cutoff. They don't know:

The latest Compact syntax (v0.19+ as of December 2025)
Midnight-specific patterns (commit-reveal, selective disclosure)
Infrastructure setup quirks (version synchronization between node/indexer/proof-server)
Common mistakes and their fixes

What if we could give AI agents the knowledge they need to build on Midnight correctly?

That's when I discovered the Agent Skills format from Vercel. They created a way to package domain-specific knowledge that AI agents can consume and use.

The Solution: midnight-agent-skills

I built midnight-agent-skills—a collection of curated, verified knowledge that extends AI coding assistants for Midnight development.

How It Works

┌─────────────────────────────────────────────────────────────┐
│                     Your AI Agent                           │
│               (Claude, Cursor, Copilot)                     │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      │ reads
                      ▼
┌─────────────────────────────────────────────────────────────┐
│                 midnight-agent-skills                        │
│                                                             │
│  ┌─────────────────┐  ┌─────────────────┐                  │
│  │ CLAUDE.md       │  │ AGENTS.md       │                  │
│  │ Agent guidance  │  │ Agent guidance  │                  │
│  └─────────────────┘  └─────────────────┘                  │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │                    skills/                           │   │
│  │                                                      │   │
│  │  midnight-compact-guide/    Compact v0.19+ syntax   │   │
│  │  midnight-sdk-guide/        TypeScript SDK          │   │
│  │  midnight-infra-setup/      Infrastructure          │   │
│  │  midnight-deploy/           Deployment              │   │
│  │  midnight-test-runner/      Testing                 │   │
│  │                                                      │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
└─────────────────────────────────────────────────────────────┘
                      │
                      │ generates
                      ▼
┌─────────────────────────────────────────────────────────────┐
│              Correct Midnight Code                          │
│                                                             │
│  pragma language_version >= 0.19;                          │
│  import CompactStandardLibrary;                            │
│  export ledger counter: Counter;                           │
│  export circuit increment(): [] { ... }                    │
│                                                             │
└─────────────────────────────────────────────────────────────┘

When you clone the repo into your project, your AI agent automatically reads the CLAUDE.md and AGENTS.md files. These files:

Describe available skills and when to use them
Provide critical syntax notes so the agent doesn't make common mistakes
Reference detailed rules in the skills/ directory

The Skills

1. midnight-compact-guide

The core skill. Contains everything about Compact language syntax (v0.19+):

Correct patterns:

pragma language_version >= 0.19;

import CompactStandardLibrary;

// Ledger - individual declarations (NOT block syntax)
export ledger counter: Counter;
export ledger owner: Bytes<32>;

// Witness - declaration only, NO body
witness local_secret_key(): Bytes<32>;

// Circuit - returns [] (NOT Void)
export circuit increment(): [] {
  counter.increment(1);
}

// Pure circuit (NOT pure function)
pure circuit helper(x: Field): Field {
  return x + 1;
}

Common mistakes it prevents:

AI Would Generate	Skill Teaches Correct
`ledger { counter: Counter; }`	`export ledger counter: Counter;`
`circuit fn(): Void`	`circuit fn(): []`
`pure function helper()`	`pure circuit helper()`
`Choice::rock`	`Choice.rock`
`counter.value()`	`counter.read()`

2. midnight-sdk-guide

TypeScript SDK integration:

Wallet connection (Lace)
Contract deployment
State management
Error handling
React hooks

3. midnight-infra-setup

Local infrastructure setup:

Node (ws://127.0.0.1:9944)
Indexer (http://127.0.0.1:8088)
Proof Server (http://127.0.0.1:6300)
Critical: Version synchronization between components

4. midnight-deploy

Deployment workflow:

Compile contracts
Deploy to local
Deploy to preview testnet
Environment configuration

5. midnight-test-runner

Testing with Vitest:

Contract simulators
Private state testing
Selective disclosure verification

How I Built It

Step 1: Study Existing Formats

I cloned vercel-labs/agent-skills to understand the format:

skill/
├── SKILL.md           # Main skill definition (YAML frontmatter + content)
├── rules/             # Detailed rules
│   └── rule-name.md
└── scripts/           # Executable scripts
    └── script.sh

Step 2: Gather Authoritative Sources

I studied multiple sources for correct Compact syntax:

MeshJS Starter Template - Most up-to-date (pragma >= 0.19, updated Dec 2025)
midnight-mcp - Comprehensive syntax reference
OpenZeppelin Compact Contracts - Older but battle-tested patterns
Official Midnight Docs - Language reference

The MeshJS template was the most current, so I based the syntax on that.

Step 3: Create Skills with Verified Patterns

Every code example in the skills was verified against actual compiling contracts. I didn't just copy from docs—I checked:

Does this pragma format work?
Is ledger {} block syntax still supported? (No, deprecated)
What's the return type for circuits? ([], not Void)
Do witnesses have bodies in Compact? (No, declaration only)

Step 4: Build the CLI

I created an npx-installable CLI:

// bin/cli.js
#!/usr/bin/env node
import { run } from '../src/index.js';
run(process.argv.slice(2));

// Usage
npx midnight-agent-skills init        // Add all skills
npx midnight-agent-skills add <skill> // Add specific skill
npx midnight-agent-skills list        // List skills

Problems It Solves

1. Wrong Syntax Generation

Before: AI generates circuit fn(): Void { }
After: AI generates circuit fn(): [] { }

2. Outdated Patterns

Before: AI uses deprecated ledger {} block syntax
After: AI uses correct export ledger field: Type;

3. Infrastructure Confusion

Before: Spend hours figuring out version compatibility
After: Skill provides exact versions and synchronization requirements

4. Missing Patterns

Before: Reinvent commit-reveal pattern from scratch
After: Copy verified, working pattern from skill

5. Testing Struggles

Before: Figure out how to test private state
After: Use provided simulator patterns

Building with midnight-agent-skills

Quick Start

# Create a new Midnight project
mkdir my-midnight-dapp
cd my-midnight-dapp

# Add the skills
npx midnight-agent-skills init

# Now your AI agent knows Midnight!

Example Workflow

1. Ask your AI to write a contract:

Write a Midnight contract for a simple voting system where:
- Users can vote once
- Votes are private (shielded)
- Final tally is public

2. The AI reads the skills and generates correct code:

pragma language_version >= 0.19;

import CompactStandardLibrary;

export ledger totalVotes: Counter;
export ledger hasVoted: Map<Bytes<32>, Boolean>;

witness local_secret_key(): Bytes<32>;

circuit get_voter_id(): Bytes<32> {
  const sk = local_secret_key();
  return persistentHash<Vector<2, Bytes<32>>>([pad(32, "vote:id:"), sk]);
}

export circuit vote(choice: Uint<8>): [] {
  const voter = get_voter_id();
  assert(disclose(!hasVoted.member(voter)), "Already voted");

  hasVoted.insert(disclose(voter), true);
  totalVotes.increment(1);
}

3. Ask for infrastructure setup:

Set up local Midnight infrastructure for testing

4. The AI provides correct commands:

# Start node
docker run -p 9944:9944 midnightntwrk/midnight-node

# Start indexer (must match node version)
docker run -p 8088:8088 midnightntwrk/midnight-indexer

# Start proof server
docker run -p 6300:6300 midnightntwrk/midnight-proof-server

Technical Architecture

File Structure

midnight-agent-skills/
├── package.json              # npm package config
├── bin/
│   └── cli.js               # npx entry point
├── src/
│   └── index.js             # CLI logic
├── skills/
│   ├── midnight-compact-guide/
│   │   ├── SKILL.md         # Main skill (Compact v0.19+)
│   │   └── rules/
│   │       ├── privacy-selective-disclosure.md
│   │       ├── tokens-shielded-unshielded.md
│   │       ├── common-errors.md
│   │       └── openzeppelin-patterns.md
│   ├── midnight-sdk-guide/
│   │   ├── SKILL.md
│   │   └── rules/
│   │       └── wallet-integration.md
│   ├── midnight-infra-setup/
│   │   ├── SKILL.md
│   │   └── scripts/
│   │       └── setup.sh
│   ├── midnight-deploy/
│   │   ├── SKILL.md
│   │   └── scripts/
│   │       └── deploy.sh
│   └── midnight-test-runner/
│       ├── SKILL.md
│       └── scripts/
│           └── test.sh
├── AGENTS.md                 # Agent guidance
├── CLAUDE.md                 # Claude-specific guidance
├── README.md
├── CONTRIBUTING.md
└── LICENSE

SKILL.md Format

---
name: midnight-compact-guide
description: Triggers on "write contract", "Compact syntax"...
license: MIT
metadata:
  author: webisoft
  version: "2.1.0"
  compact-version: "0.19+"
---

# Skill Title

Content with verified code examples...

How AI Agents Discover Skills

Claude Code: Reads CLAUDE.md automatically
Cursor: Reads .cursorrules or AGENTS.md
Other agents: Read AGENTS.md or skill files directly

The CLAUDE.md and AGENTS.md files contain:

Overview of available skills
Trigger phrases
Critical syntax notes (prevents common mistakes)
Quick reference code

Verification Process

Every code pattern in the skills was verified:

Source Priority

MeshJS Starter Template (Dec 2025) - Most current
Midnight Official Docs - Language reference
midnight-mcp - Curated syntax guide
OpenZeppelin Compact - Audited patterns (older version)

Verification Steps

# 1. Check MeshJS template
grep "pragma language_version" counter-contract/src/counter.compact
# Result: pragma language_version >= 0.19;

# 2. Check OpenZeppelin
grep "pragma language_version" compact-contracts/contracts/**/*.compact
# Result: pragma language_version >= 0.15.0;  (older)

# 3. Check git history
git log --format="%ad %s" --date=short counter-contract/src/counter.compact
# Result: 2025-12-17 bump: preview yaml and tooling & compiler

# Conclusion: Use >= 0.19 from MeshJS (most recent)

Future Plans

More Skills

midnight-audit - Security audit patterns
midnight-upgrade - Contract upgrade patterns
midnight-bridge - Cross-chain integration
midnight-identity - DID and credential patterns

Better Tooling

VS Code extension for skill browsing
Web interface for skill search
Auto-update mechanism for syntax changes

Community Contributions

Contribution guide available
Open for PRs with new patterns
Verification process for community skills

Conclusion

Building on Midnight doesn't have to be painful. With midnight-agent-skills, your AI coding assistant becomes a Midnight expert:

Knows the correct Compact syntax (v0.19+)
Understands privacy patterns
Can set up infrastructure
Helps with testing and deployment

Get started:

npx midnight-agent-skills init

Then just ask your AI to help you build on Midnight. It will know what to do.

Resources

GitHub: https://github.com/UvRoxx/midnight-agent-skills
Midnight Docs: https://docs.midnight.network
Compact Guide: https://docs.midnight.network/develop/reference/compact/lang-ref
MeshJS Template: https://github.com/MeshJS/midnight-starter-template

Built with care by Webisoft Development Labs

Maintained by Utkarsh Varma (@UvRoxx)

Building a Privacy-Preserving Custodian App with Selective Disclosure on Midnight

UtkarshVarma — Sat, 17 Jan 2026 17:04:25 +0000

A comprehensive guide to building custodial asset management with selective disclosure using Midnight Network and zero-knowledge proofs

Introduction to Selective Disclosure
Why Build Custodian Apps on Midnight?
Understanding Selective Disclosure Architecture
Prerequisites & Setup
Project Structure
Writing the Custodian Contract
Implementing Selective Disclosure
Frontend Integration
Testing Your Contract
Deployment Guide
Advanced Patterns
Compliance & Regulatory Considerations
Next Steps & Resources

Introduction to Selective Disclosure

What is Selective Disclosure?

Selective Disclosure is a privacy-preserving technique that allows users to prove specific claims about their data without revealing the underlying information. Using zero-knowledge proofs, a user can demonstrate:

They have sufficient balance without revealing the exact amount
They are over 18 without revealing their birth date
They are an accredited investor without revealing net worth
They own specific assets without revealing their full portfolio
They passed KYC without revealing personal documents

The Custodian Model

A custodian is an entity that holds and manages assets on behalf of clients. Traditional custodians include:

Banks holding deposits
Brokerages holding securities
Crypto exchanges holding tokens
Asset managers holding investment portfolios

The Privacy Problem

Traditional custodians face a dilemma:

Full Transparency: Reveals sensitive client information
Full Opacity: Provides no verifiability or auditability

Midnight's Solution: Selective disclosure enables custodians to prove claims about client assets while keeping sensitive details private.

Why Build Custodian Apps on Midnight?

Real-World Use Cases

1. Proof of Reserves

Exchanges can prove they hold sufficient assets to cover all customer deposits without revealing individual account balances.

2. Accredited Investor Verification

Investment platforms can verify investor accreditation status without collecting and storing sensitive financial documents.

3. Credit Scoring

Lenders can verify creditworthiness without seeing complete financial history.

4. Regulatory Compliance

Demonstrate compliance with regulations (AML/KYC) while maintaining client privacy.

5. Asset Verification

Prove ownership of specific asset classes without revealing entire portfolio.

Comparison: Traditional vs. Midnight Custodian

Aspect	Traditional	Midnight
Balance Verification	Reveal exact amounts	Prove range/threshold
Identity Verification	Share documents	Prove attributes
Audit Trail	Full transaction history	Selective proof generation
Regulatory Reports	Detailed disclosures	Compliant proofs
Client Privacy	Minimal	Maximum

Why Zero-Knowledge Proofs?

Traditional Approach:
User → "My balance is $50,000" → Verifier sees exact amount

ZK Approach:
User → "I can prove balance > $10,000" → Verifier learns ONLY that balance exceeds threshold

Understanding Selective Disclosure Architecture

System Architecture

+------------------------------------------------------------------+
|                        Client Application                         |
|    +------------------+  +------------------+  +----------------+ |
|    | Wallet Interface |  | Proof Generator  |  | Claim Builder  | |
|    +------------------+  +------------------+  +----------------+ |
+------------------------------------------------------------------+
                               |
                               v
+------------------------------------------------------------------+
|                     Midnight Network                              |
|  +--------------------+  +--------------------+  +--------------+ |
|  | Public Ledger      |  | Private State      |  | ZK Circuits  | |
|  | - Account exists   |  | - Actual balance   |  | - Proofs     | |
|  | - Proof validity   |  | - Personal data    |  | - Verifiers  | |
|  | - Custodian status |  | - Asset details    |  |              | |
|  +--------------------+  +--------------------+  +--------------+ |
+------------------------------------------------------------------+
                               |
                               v
+------------------------------------------------------------------+
|                        Verifier/Auditor                          |
|    Can verify proofs without accessing private data              |
+------------------------------------------------------------------+

Data Flow for Selective Disclosure

1. Client deposits assets with custodian
   └─→ Balance stored in private state

2. Client requests disclosure proof
   └─→ "Prove balance > $10,000"

3. ZK circuit generates proof
   └─→ Uses private balance, outputs boolean

4. Verifier checks proof
   └─→ Learns only: balance exceeds threshold

5. Private data never leaves client
   └─→ Zero knowledge transfer

Key Components

1. Custodian Contract

Manages deposits, withdrawals, and account states.

2. Disclosure Circuits

ZK circuits that generate proofs about private data.

3. Verifier Functions

On-chain verification of disclosure proofs.

4. Credential Registry

Tracks verified attributes (KYC status, accreditation, etc.).

Prerequisites & Setup

Required Tools

# Check prerequisites
node -v   # Required: v23+
npm -v    # Required: v11+
docker -v # Required: Latest

Step 1: Install Compact Compiler

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

# Install compiler version 0.27.0
compact update +0.27.0

# Verify installation
compact check

Step 2: Clone the Starter Template

# Clone repository
git clone https://github.com/MeshJS/midnight-starter-template.git
cd midnight-starter-template

# Install dependencies
npm install

Step 3: Create Custodian Contract Structure

# Create new contract directory
mkdir -p custodian-contract/src
mkdir -p custodian-contract/src/test

# Create package.json for custodian contract
cat > custodian-contract/package.json << 'EOF'
{
  "name": "custodian-contract",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "build": "compactc src/custodian.compact --output src/managed",
    "test": "vitest run"
  },
  "dependencies": {
    "@midnight-ntwrk/compact-runtime": "^0.27.0"
  },
  "devDependencies": {
    "vitest": "^1.0.0"
  }
}
EOF

Project Structure

Directory Layout

midnight-starter-template/
├── custodian-contract/              # Smart contract code
│   ├── src/
│   │   ├── custodian.compact        # Main contract logic
│   │   ├── witnesses.ts             # Private state definitions
│   │   ├── managed/                 # Compiled artifacts
│   │   └── test/
│   │       ├── custodian.test.ts    # Unit tests
│   │       └── simulators/
│   │           └── simulator.ts     # Test simulator
│   └── package.json
│
├── custodian-cli/                   # CLI deployment tools
│   ├── src/
│   │   └── config.ts                # Network configuration
│   └── package.json
│
├── frontend-vite-react/             # React frontend
│   ├── src/
│   │   ├── pages/
│   │   │   └── custodian/           # Custodian UI pages
│   │   └── modules/midnight/
│   │       └── custodian-sdk/       # Contract SDK
│   └── package.json
│
└── package.json                     # Root workspace config

Writing the Custodian Contract

The Complete Custodian Contract

Create custodian-contract/src/custodian.compact:

pragma language_version >= 0.19;

import CompactStandardLibrary;

// ============================================
// CUSTODIAN CONTRACT WITH SELECTIVE DISCLOSURE
// ============================================

// Account status enum (as Uint<8>)
// 0 = Inactive
// 1 = Active
// 2 = Frozen
// 3 = Closed

// KYC Level enum (as Uint<8>)
// 0 = None
// 1 = Basic (email verified)
// 2 = Standard (ID verified)
// 3 = Enhanced (full verification)

// Accreditation Status (as Uint<8>)
// 0 = Not verified
// 1 = Accredited Investor
// 2 = Qualified Purchaser

// ============================================
// PUBLIC LEDGER STATE
// ============================================

// Total accounts registered
export ledger totalAccounts: Counter;

// Total assets under custody (aggregated, privacy-preserving)
export ledger totalAssetsUnderCustody: Counter;

// Account existence mapping (proves account exists without revealing balance)
export ledger accountExists: Map<Bytes<32>, Boolean>;

// Account status mapping
export ledger accountStatus: Map<Bytes<32>, Uint<8>>;

// KYC verification status (public proof that KYC was completed)
export ledger kycVerified: Map<Bytes<32>, Boolean>;

// KYC level (public)
export ledger kycLevel: Map<Bytes<32>, Uint<8>>;

// Accreditation status (public proof)
export ledger accreditationStatus: Map<Bytes<32>, Uint<8>>;

// Proof verification results (for auditors)
export ledger proofVerificationLog: Counter;

// Disclosure request nonces (prevent replay)
export ledger disclosureNonces: Map<Bytes<32>, Counter>;

// Custodian admin address
export ledger custodianAdmin: Bytes<32>;

// Contract initialized flag
export ledger initialized: Boolean;

// Minimum balance thresholds for different tiers
export ledger tierOneThreshold: Uint<64>;    // e.g., 10,000
export ledger tierTwoThreshold: Uint<64>;    // e.g., 100,000
export ledger tierThreeThreshold: Uint<64>;  // e.g., 1,000,000

// ============================================
// INITIALIZATION
// ============================================

export circuit initialize(
  adminAddress: Bytes<32>,
  tier1: Uint<64>,
  tier2: Uint<64>,
  tier3: Uint<64>
): [] {
  assert(!initialized, "Contract already initialized");

  custodianAdmin = adminAddress;
  tierOneThreshold = tier1;
  tierTwoThreshold = tier2;
  tierThreeThreshold = tier3;
  initialized = true;
}

// ============================================
// ACCOUNT MANAGEMENT
// ============================================

// Register a new custodial account
// accountId is a hash of user's identity (privacy-preserving)
export circuit registerAccount(accountId: Bytes<32>): [] {
  assert(initialized, "Contract not initialized");
  assert(!accountExists[accountId], "Account already exists");

  accountExists[accountId] = true;
  accountStatus[accountId] = 1; // Active
  kycVerified[accountId] = false;
  kycLevel[accountId] = 0;
  accreditationStatus[accountId] = 0;

  totalAccounts.increment(1);
}

// Deposit assets (amount is added to private state, only aggregates are public)
export circuit deposit(
  accountId: Bytes<32>,
  amount: Uint<64>
): [] {
  assert(initialized, "Contract not initialized");
  assert(accountExists[accountId], "Account does not exist");
  assert(accountStatus[accountId] == 1, "Account not active");

  // Increment total custody (privacy: individual amounts hidden)
  totalAssetsUnderCustody.increment(amount);
}

// Withdraw assets
export circuit withdraw(
  accountId: Bytes<32>,
  amount: Uint<64>
): [] {
  assert(initialized, "Contract not initialized");
  assert(accountExists[accountId], "Account does not exist");
  assert(accountStatus[accountId] == 1, "Account not active");

  // Note: In a full implementation, balance check would be in private state
  // This decrements the public aggregate
  // The actual balance verification happens via ZK proof
}

// ============================================
// KYC VERIFICATION (Admin Functions)
// ============================================

// Admin verifies KYC for an account
export circuit verifyKYC(
  accountId: Bytes<32>,
  level: Uint<8>,
  adminSig: Bytes<32>
): [] {
  assert(initialized, "Contract not initialized");
  assert(accountExists[accountId], "Account does not exist");
  assert(level >= 1, "Invalid KYC level");
  assert(level <= 3, "Invalid KYC level");

  // In production: verify adminSig matches custodianAdmin

  kycVerified[accountId] = true;
  kycLevel[accountId] = level;
}

// Admin verifies accreditation status
export circuit verifyAccreditation(
  accountId: Bytes<32>,
  status: Uint<8>,
  adminSig: Bytes<32>
): [] {
  assert(initialized, "Contract not initialized");
  assert(accountExists[accountId], "Account does not exist");
  assert(kycVerified[accountId], "KYC required first");
  assert(status >= 1, "Invalid accreditation status");
  assert(status <= 2, "Invalid accreditation status");

  accreditationStatus[accountId] = status;
}

// ============================================
// SELECTIVE DISCLOSURE CIRCUITS
// ============================================

// Prove balance exceeds a threshold without revealing exact balance
// This circuit takes the actual balance as a private witness input
export circuit proveBalanceAboveThreshold(
  accountId: Bytes<32>,
  threshold: Uint<64>,
  actualBalance: Uint<64>,  // Private witness
  nonce: Bytes<32>          // Prevent replay
): [] {
  assert(initialized, "Contract not initialized");
  assert(accountExists[accountId], "Account does not exist");
  assert(accountStatus[accountId] == 1, "Account not active");

  // The ZK magic: prove balance > threshold without revealing balance
  assert(actualBalance >= threshold, "Balance below threshold");

  // Log successful verification
  proofVerificationLog.increment(1);
  disclosureNonces[accountId].increment(1);
}

// Prove balance is within a range (e.g., $10k - $100k)
export circuit proveBalanceInRange(
  accountId: Bytes<32>,
  minBalance: Uint<64>,
  maxBalance: Uint<64>,
  actualBalance: Uint<64>,  // Private witness
  nonce: Bytes<32>
): [] {
  assert(initialized, "Contract not initialized");
  assert(accountExists[accountId], "Account does not exist");
  assert(minBalance <= maxBalance, "Invalid range");

  // Prove balance is within range
  assert(actualBalance >= minBalance, "Balance below minimum");
  assert(actualBalance <= maxBalance, "Balance above maximum");

  proofVerificationLog.increment(1);
  disclosureNonces[accountId].increment(1);
}

// Prove account tier (based on balance thresholds)
// Returns tier without revealing exact balance
export circuit proveAccountTier(
  accountId: Bytes<32>,
  actualBalance: Uint<64>,  // Private witness
  claimedTier: Uint<8>,
  nonce: Bytes<32>
): [] {
  assert(initialized, "Contract not initialized");
  assert(accountExists[accountId], "Account does not exist");
  assert(claimedTier >= 1, "Invalid tier");
  assert(claimedTier <= 3, "Invalid tier");

  // Verify claimed tier matches actual balance
  if (claimedTier == 1) {
    assert(actualBalance >= tierOneThreshold, "Insufficient balance for Tier 1");
  }
  if (claimedTier == 2) {
    assert(actualBalance >= tierTwoThreshold, "Insufficient balance for Tier 2");
  }
  if (claimedTier == 3) {
    assert(actualBalance >= tierThreeThreshold, "Insufficient balance for Tier 3");
  }

  proofVerificationLog.increment(1);
}

// Prove KYC status meets minimum level
export circuit proveKYCLevel(
  accountId: Bytes<32>,
  minimumLevel: Uint<8>
): [] {
  assert(initialized, "Contract not initialized");
  assert(accountExists[accountId], "Account does not exist");
  assert(kycVerified[accountId], "KYC not completed");
  assert(kycLevel[accountId] >= minimumLevel, "KYC level insufficient");

  proofVerificationLog.increment(1);
}

// Prove accredited investor status
export circuit proveAccreditedInvestor(accountId: Bytes<32>): [] {
  assert(initialized, "Contract not initialized");
  assert(accountExists[accountId], "Account does not exist");
  assert(accreditationStatus[accountId] >= 1, "Not accredited");

  proofVerificationLog.increment(1);
}

// Combined proof: KYC + Balance threshold (common for investments)
export circuit proveInvestmentEligibility(
  accountId: Bytes<32>,
  minKYCLevel: Uint<8>,
  minBalance: Uint<64>,
  actualBalance: Uint<64>,  // Private witness
  nonce: Bytes<32>
): [] {
  assert(initialized, "Contract not initialized");
  assert(accountExists[accountId], "Account does not exist");
  assert(accountStatus[accountId] == 1, "Account not active");

  // Verify KYC
  assert(kycVerified[accountId], "KYC required");
  assert(kycLevel[accountId] >= minKYCLevel, "Insufficient KYC level");

  // Verify balance (private)
  assert(actualBalance >= minBalance, "Insufficient balance");

  proofVerificationLog.increment(1);
}

// ============================================
// ADMIN FUNCTIONS
// ============================================

// Freeze an account (compliance action)
export circuit freezeAccount(
  accountId: Bytes<32>,
  adminSig: Bytes<32>
): [] {
  assert(initialized, "Contract not initialized");
  assert(accountExists[accountId], "Account does not exist");

  accountStatus[accountId] = 2; // Frozen
}

// Unfreeze an account
export circuit unfreezeAccount(
  accountId: Bytes<32>,
  adminSig: Bytes<32>
): [] {
  assert(initialized, "Contract not initialized");
  assert(accountExists[accountId], "Account does not exist");
  assert(accountStatus[accountId] == 2, "Account not frozen");

  accountStatus[accountId] = 1; // Active
}

// Close an account
export circuit closeAccount(
  accountId: Bytes<32>,
  adminSig: Bytes<32>
): [] {
  assert(initialized, "Contract not initialized");
  assert(accountExists[accountId], "Account does not exist");

  accountStatus[accountId] = 3; // Closed
}

// Update tier thresholds
export circuit updateTierThresholds(
  tier1: Uint<64>,
  tier2: Uint<64>,
  tier3: Uint<64>,
  adminSig: Bytes<32>
): [] {
  assert(initialized, "Contract not initialized");
  assert(tier1 < tier2, "Tier 1 must be less than Tier 2");
  assert(tier2 < tier3, "Tier 2 must be less than Tier 3");

  tierOneThreshold = tier1;
  tierTwoThreshold = tier2;
  tierThreeThreshold = tier3;
}

Implementing Selective Disclosure

Private State Definition

Create custodian-contract/src/witnesses.ts:

// ============================================
// PRIVATE STATE (WITNESSES) FOR CUSTODIAN
// ============================================

export type AssetHolding = {
  assetType: string;       // "TOKEN", "NFT", "FIAT"
  assetId: string;         // Token address or asset identifier
  amount: bigint;          // Actual amount held
  acquisitionDate: number; // Unix timestamp
  acquisitionPrice: bigint; // Original purchase price
};

export type PersonalData = {
  firstName: string;
  lastName: string;
  dateOfBirth: number;     // Unix timestamp
  countryOfResidence: string;
  taxId: string;           // SSN, TIN, etc.
  email: string;
  phone: string;
};

export type KYCDocuments = {
  idType: string;          // "PASSPORT", "DRIVERS_LICENSE", "NATIONAL_ID"
  idNumber: string;
  idExpiry: number;
  proofOfAddressType: string;
  verificationDate: number;
  verifiedBy: string;      // Verification provider
};

export type AccreditationData = {
  verificationType: string; // "INCOME", "NET_WORTH", "PROFESSIONAL"
  verificationDate: number;
  expiryDate: number;
  certifyingEntity: string;
  supportingDocHash: string;
};

export type CustodianPrivateState = {
  // Account identification
  accountId: string;        // Hashed account ID (public reference)
  internalId: string;       // Internal account number

  // Financial data (PRIVATE - never disclosed directly)
  totalBalance: bigint;
  availableBalance: bigint;
  lockedBalance: bigint;
  holdings: AssetHolding[];

  // Personal data (PRIVATE - only attributes disclosed via ZK)
  personalData: PersonalData;

  // KYC data (PRIVATE - only verification status disclosed)
  kycDocuments: KYCDocuments | null;

  // Accreditation (PRIVATE - only status disclosed)
  accreditationData: AccreditationData | null;

  // Transaction history (PRIVATE)
  transactionCount: number;
  lastActivityDate: number;
};

// Factory function to create initial private state
export const createPrivateState = (
  accountId: string,
  internalId: string
): CustodianPrivateState => {
  return {
    accountId,
    internalId,
    totalBalance: 0n,
    availableBalance: 0n,
    lockedBalance: 0n,
    holdings: [],
    personalData: {
      firstName: '',
      lastName: '',
      dateOfBirth: 0,
      countryOfResidence: '',
      taxId: '',
      email: '',
      phone: '',
    },
    kycDocuments: null,
    accreditationData: null,
    transactionCount: 0,
    lastActivityDate: 0,
  };
};

// ============================================
// WITNESS FUNCTIONS FOR SELECTIVE DISCLOSURE
// ============================================

export const witnesses = {
  // Witness for balance threshold proof
  getBalanceForThresholdProof: (
    state: CustodianPrivateState
  ): bigint => {
    return state.totalBalance;
  },

  // Witness for range proof
  getBalanceForRangeProof: (
    state: CustodianPrivateState
  ): bigint => {
    return state.availableBalance;
  },

  // Witness for tier proof
  getTierWitness: (
    state: CustodianPrivateState,
    tierThresholds: { tier1: bigint; tier2: bigint; tier3: bigint }
  ): { balance: bigint; tier: number } => {
    const balance = state.totalBalance;
    let tier = 0;
    if (balance >= tierThresholds.tier3) tier = 3;
    else if (balance >= tierThresholds.tier2) tier = 2;
    else if (balance >= tierThresholds.tier1) tier = 1;
    return { balance, tier };
  },

  // Witness for age verification
  getAgeWitness: (
    state: CustodianPrivateState,
    referenceDate: number
  ): { dateOfBirth: number; ageInYears: number } => {
    const dob = state.personalData.dateOfBirth;
    const ageMs = referenceDate - dob;
    const ageYears = Math.floor(ageMs / (365.25 * 24 * 60 * 60 * 1000));
    return { dateOfBirth: dob, ageInYears: ageYears };
  },

  // Witness for country verification
  getResidencyWitness: (
    state: CustodianPrivateState
  ): string => {
    return state.personalData.countryOfResidence;
  },

  // Witness for investment eligibility
  getInvestmentEligibilityWitness: (
    state: CustodianPrivateState
  ): {
    balance: bigint;
    kycComplete: boolean;
    isAccredited: boolean;
  } => {
    return {
      balance: state.availableBalance,
      kycComplete: state.kycDocuments !== null,
      isAccredited: state.accreditationData !== null,
    };
  },
};

// ============================================
// DISCLOSURE PROOF BUILDERS
// ============================================

export type DisclosureType =
  | 'BALANCE_THRESHOLD'
  | 'BALANCE_RANGE'
  | 'ACCOUNT_TIER'
  | 'KYC_LEVEL'
  | 'ACCREDITATION'
  | 'AGE_VERIFICATION'
  | 'RESIDENCY'
  | 'INVESTMENT_ELIGIBILITY';

export type DisclosureRequest = {
  type: DisclosureType;
  accountId: string;
  parameters: Record<string, unknown>;
  nonce: string;
  requestedBy: string;
  requestedAt: number;
  expiresAt: number;
};

export type DisclosureProof = {
  type: DisclosureType;
  accountId: string;
  claim: string;           // Human-readable claim
  proofData: Uint8Array;   // ZK proof bytes
  publicInputs: unknown[]; // Public inputs for verification
  generatedAt: number;
  expiresAt: number;
};

// Build a disclosure proof from private state
export const buildDisclosureProof = async (
  request: DisclosureRequest,
  privateState: CustodianPrivateState
): Promise<DisclosureProof> => {
  // This would integrate with the Midnight proof server
  // to generate actual ZK proofs

  const now = Date.now();

  switch (request.type) {
    case 'BALANCE_THRESHOLD':
      const threshold = request.parameters.threshold as bigint;
      const meetsThreshold = privateState.totalBalance >= threshold;
      return {
        type: 'BALANCE_THRESHOLD',
        accountId: request.accountId,
        claim: `Balance exceeds ${threshold}`,
        proofData: new Uint8Array(), // Actual proof would go here
        publicInputs: [request.accountId, threshold, meetsThreshold],
        generatedAt: now,
        expiresAt: request.expiresAt,
      };

    case 'ACCOUNT_TIER':
      const { tier } = witnesses.getTierWitness(privateState, {
        tier1: 10000n,
        tier2: 100000n,
        tier3: 1000000n,
      });
      return {
        type: 'ACCOUNT_TIER',
        accountId: request.accountId,
        claim: `Account is Tier ${tier}`,
        proofData: new Uint8Array(),
        publicInputs: [request.accountId, tier],
        generatedAt: now,
        expiresAt: request.expiresAt,
      };

    // Add more cases for other disclosure types...

    default:
      throw new Error(`Unsupported disclosure type: ${request.type}`);
  }
};

Contract Controller

Create frontend-vite-react/src/modules/midnight/custodian-sdk/api/contractController.ts:

import {
  deployContract,
  findDeployedContract,
  type DeployedContract,
  type ContractAddress,
} from '@midnight-ntwrk/midnight-js-contracts';
import * as Rx from 'rxjs';

// Import compiled contract
import { Custodian } from 'custodian-contract/src/managed/custodian';
import {
  type CustodianPrivateState,
  createPrivateState,
  witnesses,
  type DisclosureRequest,
  type DisclosureProof,
  buildDisclosureProof,
} from 'custodian-contract/src/witnesses';

export type CustodianProviders = {
  publicDataProvider: PublicDataProvider;
  privateStateProvider: PrivateStateProvider;
  zkConfigProvider: ZkConfigProvider;
  proofProvider: ProofProvider;
  midnightProvider: MidnightProvider;
  walletProvider: WalletProvider;
};

export type CustodianLedgerState = {
  totalAccounts: bigint;
  totalAssetsUnderCustody: bigint;
  initialized: boolean;
  tierOneThreshold: bigint;
  tierTwoThreshold: bigint;
  tierThreeThreshold: bigint;
};

export type AccountInfo = {
  accountId: string;
  exists: boolean;
  status: number;
  kycVerified: boolean;
  kycLevel: number;
  accreditationStatus: number;
};

export type DerivedState = {
  ledger: CustodianLedgerState;
  accounts: Map<string, AccountInfo>;
  privateState: CustodianPrivateState | null;
  pendingDisclosures: DisclosureRequest[];
  completedProofs: DisclosureProof[];
};

export interface CustodianControllerInterface {
  readonly deployedContractAddress: ContractAddress;
  readonly state$: Rx.Observable<DerivedState>;

  // Account management
  registerAccount(accountId: string): Promise<void>;
  deposit(accountId: string, amount: bigint): Promise<void>;
  withdraw(accountId: string, amount: bigint): Promise<void>;

  // KYC/Accreditation
  verifyKYC(accountId: string, level: number): Promise<void>;
  verifyAccreditation(accountId: string, status: number): Promise<void>;

  // Selective disclosure
  requestDisclosure(request: DisclosureRequest): Promise<void>;
  generateProof(request: DisclosureRequest): Promise<DisclosureProof>;

  // Verification circuits
  proveBalanceAboveThreshold(
    accountId: string,
    threshold: bigint
  ): Promise<void>;
  proveBalanceInRange(
    accountId: string,
    min: bigint,
    max: bigint
  ): Promise<void>;
  proveAccountTier(
    accountId: string,
    tier: number
  ): Promise<void>;
  proveInvestmentEligibility(
    accountId: string,
    minKYC: number,
    minBalance: bigint
  ): Promise<void>;
}

export class CustodianController implements CustodianControllerInterface {
  readonly deployedContractAddress: ContractAddress;
  readonly state$: Rx.Observable<DerivedState>;

  private readonly deployedContract: DeployedContract<Custodian>;
  private readonly providers: CustodianProviders;
  private privateState: CustodianPrivateState | null = null;
  private pendingDisclosures: DisclosureRequest[] = [];
  private completedProofs: DisclosureProof[] = [];

  private constructor(
    deployedContract: DeployedContract<Custodian>,
    providers: CustodianProviders
  ) {
    this.deployedContract = deployedContract;
    this.deployedContractAddress = deployedContract.deployTxData.public.contractAddress;
    this.providers = providers;

    // Set up reactive state
    this.state$ = this.createStateObservable();
  }

  // ============================================
  // FACTORY METHODS
  // ============================================

  static async deploy(
    providers: CustodianProviders,
    adminAddress: string,
    tiers: { tier1: bigint; tier2: bigint; tier3: bigint }
  ): Promise<CustodianController> {
    const deployedContract = await deployContract(providers, {
      contract: Custodian,
      initialPrivateState: createPrivateState('', ''),
    });

    const controller = new CustodianController(deployedContract, providers);

    // Initialize contract
    await controller.deployedContract.callTx.initialize(
      stringToBytes32(adminAddress),
      tiers.tier1,
      tiers.tier2,
      tiers.tier3
    );

    return controller;
  }

  static async join(
    contractAddress: ContractAddress,
    providers: CustodianProviders
  ): Promise<CustodianController> {
    const deployedContract = await findDeployedContract(providers, {
      contractAddress,
      contract: Custodian,
    });

    return new CustodianController(deployedContract, providers);
  }

  // ============================================
  // ACCOUNT MANAGEMENT
  // ============================================

  async registerAccount(accountId: string): Promise<void> {
    const accountIdBytes = stringToBytes32(accountId);
    await this.deployedContract.callTx.registerAccount(accountIdBytes);

    // Initialize local private state
    this.privateState = createPrivateState(accountId, generateInternalId());
  }

  async deposit(accountId: string, amount: bigint): Promise<void> {
    const accountIdBytes = stringToBytes32(accountId);
    await this.deployedContract.callTx.deposit(accountIdBytes, amount);

    // Update local private state
    if (this.privateState && this.privateState.accountId === accountId) {
      this.privateState.totalBalance += amount;
      this.privateState.availableBalance += amount;
      this.privateState.transactionCount++;
      this.privateState.lastActivityDate = Date.now();
    }
  }

  async withdraw(accountId: string, amount: bigint): Promise<void> {
    if (!this.privateState || this.privateState.accountId !== accountId) {
      throw new Error('Not authorized for this account');
    }

    if (this.privateState.availableBalance < amount) {
      throw new Error('Insufficient balance');
    }

    const accountIdBytes = stringToBytes32(accountId);
    await this.deployedContract.callTx.withdraw(accountIdBytes, amount);

    this.privateState.totalBalance -= amount;
    this.privateState.availableBalance -= amount;
    this.privateState.transactionCount++;
    this.privateState.lastActivityDate = Date.now();
  }

  // ============================================
  // KYC & ACCREDITATION
  // ============================================

  async verifyKYC(accountId: string, level: number): Promise<void> {
    const accountIdBytes = stringToBytes32(accountId);
    const adminSig = stringToBytes32('admin-signature'); // Simplified
    await this.deployedContract.callTx.verifyKYC(
      accountIdBytes,
      BigInt(level),
      adminSig
    );
  }

  async verifyAccreditation(accountId: string, status: number): Promise<void> {
    const accountIdBytes = stringToBytes32(accountId);
    const adminSig = stringToBytes32('admin-signature');
    await this.deployedContract.callTx.verifyAccreditation(
      accountIdBytes,
      BigInt(status),
      adminSig
    );
  }

  // ============================================
  // SELECTIVE DISCLOSURE
  // ============================================

  async requestDisclosure(request: DisclosureRequest): Promise<void> {
    this.pendingDisclosures.push(request);
  }

  async generateProof(request: DisclosureRequest): Promise<DisclosureProof> {
    if (!this.privateState) {
      throw new Error('No private state available');
    }

    const proof = await buildDisclosureProof(request, this.privateState);
    this.completedProofs.push(proof);

    // Remove from pending
    this.pendingDisclosures = this.pendingDisclosures.filter(
      (r) => r.nonce !== request.nonce
    );

    return proof;
  }

  async proveBalanceAboveThreshold(
    accountId: string,
    threshold: bigint
  ): Promise<void> {
    if (!this.privateState || this.privateState.accountId !== accountId) {
      throw new Error('Not authorized for this account');
    }

    const accountIdBytes = stringToBytes32(accountId);
    const nonce = stringToBytes32(generateNonce());

    await this.deployedContract.callTx.proveBalanceAboveThreshold(
      accountIdBytes,
      threshold,
      this.privateState.totalBalance, // Private witness
      nonce
    );
  }

  async proveBalanceInRange(
    accountId: string,
    min: bigint,
    max: bigint
  ): Promise<void> {
    if (!this.privateState || this.privateState.accountId !== accountId) {
      throw new Error('Not authorized for this account');
    }

    const accountIdBytes = stringToBytes32(accountId);
    const nonce = stringToBytes32(generateNonce());

    await this.deployedContract.callTx.proveBalanceInRange(
      accountIdBytes,
      min,
      max,
      this.privateState.availableBalance,
      nonce
    );
  }

  async proveAccountTier(accountId: string, tier: number): Promise<void> {
    if (!this.privateState || this.privateState.accountId !== accountId) {
      throw new Error('Not authorized for this account');
    }

    const accountIdBytes = stringToBytes32(accountId);
    const nonce = stringToBytes32(generateNonce());

    await this.deployedContract.callTx.proveAccountTier(
      accountIdBytes,
      this.privateState.totalBalance,
      BigInt(tier),
      nonce
    );
  }

  async proveInvestmentEligibility(
    accountId: string,
    minKYC: number,
    minBalance: bigint
  ): Promise<void> {
    if (!this.privateState || this.privateState.accountId !== accountId) {
      throw new Error('Not authorized for this account');
    }

    const accountIdBytes = stringToBytes32(accountId);
    const nonce = stringToBytes32(generateNonce());

    await this.deployedContract.callTx.proveInvestmentEligibility(
      accountIdBytes,
      BigInt(minKYC),
      minBalance,
      this.privateState.availableBalance,
      nonce
    );
  }

  // ============================================
  // PRIVATE HELPERS
  // ============================================

  private createStateObservable(): Rx.Observable<DerivedState> {
    return this.providers.publicDataProvider
      .contractStateObservable(this.deployedContractAddress, { type: 'all' })
      .pipe(
        Rx.map((state) => {
          const ledger = Custodian.ledger(state.data);
          return {
            ledger: {
              totalAccounts: ledger.totalAccounts,
              totalAssetsUnderCustody: ledger.totalAssetsUnderCustody,
              initialized: ledger.initialized,
              tierOneThreshold: ledger.tierOneThreshold,
              tierTwoThreshold: ledger.tierTwoThreshold,
              tierThreeThreshold: ledger.tierThreeThreshold,
            },
            accounts: new Map(),
            privateState: this.privateState,
            pendingDisclosures: this.pendingDisclosures,
            completedProofs: this.completedProofs,
          };
        })
      );
  }
}

// ============================================
// UTILITY FUNCTIONS
// ============================================

function stringToBytes32(str: string): Uint8Array {
  const encoder = new TextEncoder();
  const bytes = encoder.encode(str);
  const result = new Uint8Array(32);
  result.set(bytes.slice(0, 32));
  return result;
}

function generateNonce(): string {
  return crypto.randomUUID();
}

function generateInternalId(): string {
  return `INT-${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
}

Frontend Integration

Main Custodian Dashboard

Create frontend-vite-react/src/pages/custodian/index.tsx:

import { useState, useEffect } from 'react';
import { Button } from '@/components/ui/button';
import { Card, CardContent, CardHeader, CardTitle, CardDescription } from '@/components/ui/card';
import { Input } from '@/components/ui/input';
import { Label } from '@/components/ui/label';
import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs';
import { Badge } from '@/components/ui/badge';
import { Alert, AlertDescription } from '@/components/ui/alert';
import {
  Shield,
  Eye,
  EyeOff,
  CheckCircle,
  AlertTriangle,
  Lock,
  Unlock,
  FileCheck,
  DollarSign,
  Users,
  Activity,
} from 'lucide-react';

// Types
type AccountStatus = 'inactive' | 'active' | 'frozen' | 'closed';
type KYCLevel = 0 | 1 | 2 | 3;
type AccreditationStatus = 0 | 1 | 2;

type AccountInfo = {
  accountId: string;
  status: AccountStatus;
  kycLevel: KYCLevel;
  accreditationStatus: AccreditationStatus;
  // Private (local only)
  balance?: bigint;
  availableBalance?: bigint;
};

type DisclosureProof = {
  type: string;
  claim: string;
  verified: boolean;
  timestamp: number;
};

// Mock data for demonstration
const mockAccount: AccountInfo = {
  accountId: '0x1234...5678',
  status: 'active',
  kycLevel: 2,
  accreditationStatus: 1,
  balance: 150000n,
  availableBalance: 145000n,
};

export const CustodianDashboard = () => {
  const [account, setAccount] = useState<AccountInfo | null>(null);
  const [activeTab, setActiveTab] = useState('overview');
  const [showBalance, setShowBalance] = useState(false);
  const [proofs, setProofs] = useState<DisclosureProof[]>([]);
  const [loading, setLoading] = useState(false);

  // Disclosure form state
  const [disclosureType, setDisclosureType] = useState('');
  const [threshold, setThreshold] = useState('');

  useEffect(() => {
    // Load account data
    setAccount(mockAccount);
  }, []);

  const handleGenerateProof = async (type: string) => {
    setLoading(true);

    // Simulate proof generation
    await new Promise((resolve) => setTimeout(resolve, 2000));

    const newProof: DisclosureProof = {
      type,
      claim: getClaimText(type),
      verified: true,
      timestamp: Date.now(),
    };

    setProofs((prev) => [newProof, ...prev]);
    setLoading(false);
  };

  const getClaimText = (type: string): string => {
    switch (type) {
      case 'balance_threshold':
        return `Balance exceeds $${threshold}`;
      case 'tier':
        return 'Account is Tier 2 or higher';
      case 'kyc':
        return 'KYC Level 2 verified';
      case 'accredited':
        return 'Accredited Investor status verified';
      case 'investment_eligible':
        return 'Eligible for qualified investments';
      default:
        return 'Claim verified';
    }
  };

  const getStatusBadge = (status: AccountStatus) => {
    const variants: Record<AccountStatus, { color: string; icon: React.ReactNode }> = {
      active: { color: 'bg-green-500', icon: <CheckCircle className="w-3 h-3" /> },
      inactive: { color: 'bg-gray-500', icon: <AlertTriangle className="w-3 h-3" /> },
      frozen: { color: 'bg-blue-500', icon: <Lock className="w-3 h-3" /> },
      closed: { color: 'bg-red-500', icon: <AlertTriangle className="w-3 h-3" /> },
    };

    return (
      <Badge className={`${variants[status].color} text-white`}>
        {variants[status].icon}
        <span className="ml-1 capitalize">{status}</span>
      </Badge>
    );
  };

  const getKYCBadge = (level: KYCLevel) => {
    const labels = ['None', 'Basic', 'Standard', 'Enhanced'];
    const colors = ['bg-gray-500', 'bg-yellow-500', 'bg-blue-500', 'bg-green-500'];

    return (
      <Badge className={`${colors[level]} text-white`}>
        <FileCheck className="w-3 h-3 mr-1" />
        KYC: {labels[level]}
      </Badge>
    );
  };

  if (!account) {
    return (
      <div className="min-h-screen flex items-center justify-center">
        <div className="animate-spin rounded-full h-12 w-12 border-b-2 border-primary" />
      </div>
    );
  }

  return (
    <div className="min-h-screen bg-background py-8 px-4">
      <div className="max-w-6xl mx-auto space-y-6">
        {/* Header */}
        <div className="flex items-center justify-between">
          <div>
            <h1 className="text-3xl font-bold flex items-center gap-2">
              <Shield className="w-8 h-8 text-primary" />
              Custodian Dashboard
            </h1>
            <p className="text-muted-foreground mt-1">
              Privacy-preserving asset custody with selective disclosure
            </p>
          </div>
          <div className="flex gap-2">
            {getStatusBadge(account.status)}
            {getKYCBadge(account.kycLevel)}
          </div>
        </div>

        {/* Stats Overview */}
        <div className="grid grid-cols-1 md:grid-cols-4 gap-4">
          <Card>
            <CardContent className="pt-6">
              <div className="flex items-center justify-between">
                <div>
                  <p className="text-sm text-muted-foreground">Total Balance</p>
                  <div className="flex items-center gap-2">
                    {showBalance ? (
                      <p className="text-2xl font-bold">
                        ${account.balance?.toLocaleString()}
                      </p>
                    ) : (
                      <p className="text-2xl font-bold">*****</p>
                    )}
                    <Button
                      variant="ghost"
                      size="sm"
                      onClick={() => setShowBalance(!showBalance)}
                    >
                      {showBalance ? (
                        <EyeOff className="w-4 h-4" />
                      ) : (
                        <Eye className="w-4 h-4" />
                      )}
                    </Button>
                  </div>
                </div>
                <DollarSign className="w-8 h-8 text-muted-foreground" />
              </div>
            </CardContent>
          </Card>

          <Card>
            <CardContent className="pt-6">
              <div className="flex items-center justify-between">
                <div>
                  <p className="text-sm text-muted-foreground">Account Tier</p>
                  <p className="text-2xl font-bold">Tier 2</p>
                </div>
                <Activity className="w-8 h-8 text-muted-foreground" />
              </div>
            </CardContent>
          </Card>

          <Card>
            <CardContent className="pt-6">
              <div className="flex items-center justify-between">
                <div>
                  <p className="text-sm text-muted-foreground">Proofs Generated</p>
                  <p className="text-2xl font-bold">{proofs.length}</p>
                </div>
                <Shield className="w-8 h-8 text-muted-foreground" />
              </div>
            </CardContent>
          </Card>

          <Card>
            <CardContent className="pt-6">
              <div className="flex items-center justify-between">
                <div>
                  <p className="text-sm text-muted-foreground">Accreditation</p>
                  <p className="text-2xl font-bold">
                    {account.accreditationStatus === 1 ? 'Verified' : 'Pending'}
                  </p>
                </div>
                <Users className="w-8 h-8 text-muted-foreground" />
              </div>
            </CardContent>
          </Card>
        </div>

        {/* Main Content Tabs */}
        <Tabs value={activeTab} onValueChange={setActiveTab}>
          <TabsList className="grid w-full grid-cols-4">
            <TabsTrigger value="overview">Overview</TabsTrigger>
            <TabsTrigger value="disclosure">Selective Disclosure</TabsTrigger>
            <TabsTrigger value="proofs">Proof History</TabsTrigger>
            <TabsTrigger value="settings">Settings</TabsTrigger>
          </TabsList>

          {/* Overview Tab */}
          <TabsContent value="overview" className="space-y-4">
            <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
              <Card>
                <CardHeader>
                  <CardTitle>Account Information</CardTitle>
                  <CardDescription>
                    Your custodial account details
                  </CardDescription>
                </CardHeader>
                <CardContent className="space-y-4">
                  <div className="flex justify-between">
                    <span className="text-muted-foreground">Account ID</span>
                    <span className="font-mono">{account.accountId}</span>
                  </div>
                  <div className="flex justify-between">
                    <span className="text-muted-foreground">Status</span>
                    {getStatusBadge(account.status)}
                  </div>
                  <div className="flex justify-between">
                    <span className="text-muted-foreground">KYC Level</span>
                    {getKYCBadge(account.kycLevel)}
                  </div>
                  <div className="flex justify-between">
                    <span className="text-muted-foreground">Accreditation</span>
                    <Badge variant={account.accreditationStatus ? 'default' : 'secondary'}>
                      {account.accreditationStatus === 1
                        ? 'Accredited Investor'
                        : account.accreditationStatus === 2
                        ? 'Qualified Purchaser'
                        : 'Not Verified'}
                    </Badge>
                  </div>
                </CardContent>
              </Card>

              <Card>
                <CardHeader>
                  <CardTitle>Privacy Status</CardTitle>
                  <CardDescription>
                    What information is public vs. private
                  </CardDescription>
                </CardHeader>
                <CardContent className="space-y-3">
                  <div className="flex items-center gap-2 text-green-600">
                    <Lock className="w-4 h-4" />
                    <span>Exact balance (Private)</span>
                  </div>
                  <div className="flex items-center gap-2 text-green-600">
                    <Lock className="w-4 h-4" />
                    <span>Personal information (Private)</span>
                  </div>
                  <div className="flex items-center gap-2 text-green-600">
                    <Lock className="w-4 h-4" />
                    <span>Transaction history (Private)</span>
                  </div>
                  <div className="flex items-center gap-2 text-blue-600">
                    <Unlock className="w-4 h-4" />
                    <span>Account exists (Public)</span>
                  </div>
                  <div className="flex items-center gap-2 text-blue-600">
                    <Unlock className="w-4 h-4" />
                    <span>KYC verified status (Public)</span>
                  </div>
                </CardContent>
              </Card>
            </div>

            <Alert>
              <Shield className="w-4 h-4" />
              <AlertDescription>
                Your sensitive financial data is encrypted and stored privately.
                Only you can generate proofs about your data, and you control
                exactly what information is disclosed.
              </AlertDescription>
            </Alert>
          </TabsContent>

          {/* Selective Disclosure Tab */}
          <TabsContent value="disclosure" className="space-y-4">
            <Card>
              <CardHeader>
                <CardTitle>Generate Disclosure Proofs</CardTitle>
                <CardDescription>
                  Prove claims about your account without revealing sensitive data
                </CardDescription>
              </CardHeader>
              <CardContent className="space-y-6">
                {/* Balance Threshold Proof */}
                <div className="border rounded-lg p-4 space-y-4">
                  <div className="flex items-center justify-between">
                    <div>
                      <h3 className="font-semibold">Balance Threshold Proof</h3>
                      <p className="text-sm text-muted-foreground">
                        Prove your balance exceeds a specific amount
                      </p>
                    </div>
                    <DollarSign className="w-6 h-6 text-muted-foreground" />
                  </div>
                  <div className="flex gap-4">
                    <div className="flex-1">
                      <Label htmlFor="threshold">Threshold Amount ($)</Label>
                      <Input
                        id="threshold"
                        type="number"
                        placeholder="10000"
                        value={threshold}
                        onChange={(e) => setThreshold(e.target.value)}
                      />
                    </div>
                    <Button
                      className="self-end"
                      onClick={() => handleGenerateProof('balance_threshold')}
                      disabled={loading || !threshold}
                    >
                      {loading ? 'Generating...' : 'Generate Proof'}
                    </Button>
                  </div>
                  <p className="text-xs text-muted-foreground">
                    This will prove: "Balance &ge; ${threshold || '0'}" without revealing exact amount
                  </p>
                </div>

                {/* Tier Proof */}
                <div className="border rounded-lg p-4 space-y-4">
                  <div className="flex items-center justify-between">
                    <div>
                      <h3 className="font-semibold">Account Tier Proof</h3>
                      <p className="text-sm text-muted-foreground">
                        Prove your account tier without revealing balance
                      </p>
                    </div>
                    <Activity className="w-6 h-6 text-muted-foreground" />
                  </div>
                  <div className="flex gap-2">
                    <Button
                      variant="outline"
                      onClick={() => handleGenerateProof('tier')}
                      disabled={loading}
                    >
                      Prove Tier 1+
                    </Button>
                    <Button
                      variant="outline"
                      onClick={() => handleGenerateProof('tier')}
                      disabled={loading}
                    >
                      Prove Tier 2+
                    </Button>
                    <Button
                      variant="outline"
                      onClick={() => handleGenerateProof('tier')}
                      disabled={loading}
                    >
                      Prove Tier 3
                    </Button>
                  </div>
                </div>

                {/* KYC Level Proof */}
                <div className="border rounded-lg p-4 space-y-4">
                  <div className="flex items-center justify-between">
                    <div>
                      <h3 className="font-semibold">KYC Verification Proof</h3>
                      <p className="text-sm text-muted-foreground">
                        Prove KYC completion without revealing documents
                      </p>
                    </div>
                    <FileCheck className="w-6 h-6 text-muted-foreground" />
                  </div>
                  <Button
                    onClick={() => handleGenerateProof('kyc')}
                    disabled={loading}
                  >
                    Prove KYC Level 2+
                  </Button>
                </div>

                {/* Accredited Investor Proof */}
                <div className="border rounded-lg p-4 space-y-4">
                  <div className="flex items-center justify-between">
                    <div>
                      <h3 className="font-semibold">Accredited Investor Proof</h3>
                      <p className="text-sm text-muted-foreground">
                        Prove accreditation without revealing financials
                      </p>
                    </div>
                    <Users className="w-6 h-6 text-muted-foreground" />
                  </div>
                  <Button
                    onClick={() => handleGenerateProof('accredited')}
                    disabled={loading || account.accreditationStatus === 0}
                  >
                    {account.accreditationStatus === 0
                      ? 'Accreditation Required'
                      : 'Prove Accredited Status'}
                  </Button>
                </div>

                {/* Combined Investment Eligibility */}
                <div className="border rounded-lg p-4 space-y-4 bg-primary/5">
                  <div className="flex items-center justify-between">
                    <div>
                      <h3 className="font-semibold">Investment Eligibility Proof</h3>
                      <p className="text-sm text-muted-foreground">
                        Combined proof: KYC + Balance + Accreditation
                      </p>
                    </div>
                    <Shield className="w-6 h-6 text-primary" />
                  </div>
                  <Button
                    onClick={() => handleGenerateProof('investment_eligible')}
                    disabled={loading}
                    className="w-full"
                  >
                    Generate Investment Eligibility Proof
                  </Button>
                  <p className="text-xs text-muted-foreground">
                    Proves you meet all requirements for qualified investments
                    in a single proof, without revealing specific details.
                  </p>
                </div>
              </CardContent>
            </Card>
          </TabsContent>

          {/* Proof History Tab */}
          <TabsContent value="proofs" className="space-y-4">
            <Card>
              <CardHeader>
                <CardTitle>Generated Proofs</CardTitle>
                <CardDescription>
                  History of your disclosure proofs
                </CardDescription>
              </CardHeader>
              <CardContent>
                {proofs.length === 0 ? (
                  <div className="text-center py-8 text-muted-foreground">
                    <Shield className="w-12 h-12 mx-auto mb-4 opacity-50" />
                    <p>No proofs generated yet</p>
                    <p className="text-sm">
                      Generate proofs from the Selective Disclosure tab
                    </p>
                  </div>
                ) : (
                  <div className="space-y-3">
                    {proofs.map((proof, index) => (
                      <div
                        key={index}
                        className="flex items-center justify-between p-4 border rounded-lg"
                      >
                        <div className="flex items-center gap-3">
                          {proof.verified ? (
                            <CheckCircle className="w-5 h-5 text-green-500" />
                          ) : (
                            <AlertTriangle className="w-5 h-5 text-yellow-500" />
                          )}
                          <div>
                            <p className="font-medium">{proof.claim}</p>
                            <p className="text-sm text-muted-foreground">
                              {new Date(proof.timestamp).toLocaleString()}
                            </p>
                          </div>
                        </div>
                        <Badge variant={proof.verified ? 'default' : 'secondary'}>
                          {proof.verified ? 'Verified' : 'Pending'}
                        </Badge>
                      </div>
                    ))}
                  </div>
                )}
              </CardContent>
            </Card>
          </TabsContent>

          {/* Settings Tab */}
          <TabsContent value="settings" className="space-y-4">
            <Card>
              <CardHeader>
                <CardTitle>Privacy Settings</CardTitle>
                <CardDescription>
                  Configure your disclosure preferences
                </CardDescription>
              </CardHeader>
              <CardContent className="space-y-4">
                <div className="flex items-center justify-between p-4 border rounded-lg">
                  <div>
                    <p className="font-medium">Auto-expire proofs</p>
                    <p className="text-sm text-muted-foreground">
                      Proofs automatically expire after 24 hours
                    </p>
                  </div>
                  <Button variant="outline">Configure</Button>
                </div>
                <div className="flex items-center justify-between p-4 border rounded-lg">
                  <div>
                    <p className="font-medium">Require confirmation</p>
                    <p className="text-sm text-muted-foreground">
                      Confirm before generating any proof
                    </p>
                  </div>
                  <Button variant="outline">Configure</Button>
                </div>
                <div className="flex items-center justify-between p-4 border rounded-lg">
                  <div>
                    <p className="font-medium">Audit log</p>
                    <p className="text-sm text-muted-foreground">
                      Keep record of all proof requests
                    </p>
                  </div>
                  <Button variant="outline">View Log</Button>
                </div>
              </CardContent>
            </Card>
          </TabsContent>
        </Tabs>
      </div>
    </div>
  );
};

export default CustodianDashboard;

Verifier Component

Create frontend-vite-react/src/pages/custodian/verifier.tsx:

import { useState } from 'react';
import { Button } from '@/components/ui/button';
import { Card, CardContent, CardHeader, CardTitle, CardDescription } from '@/components/ui/card';
import { Input } from '@/components/ui/input';
import { Label } from '@/components/ui/label';
import { Badge } from '@/components/ui/badge';
import { Alert, AlertDescription } from '@/components/ui/alert';
import {
  Shield,
  CheckCircle,
  XCircle,
  Upload,
  Search,
} from 'lucide-react';

type VerificationResult = {
  valid: boolean;
  claim: string;
  accountId: string;
  timestamp: number;
  expiresAt: number;
};

export const ProofVerifier = () => {
  const [proofInput, setProofInput] = useState('');
  const [verifying, setVerifying] = useState(false);
  const [result, setResult] = useState<VerificationResult | null>(null);

  const handleVerify = async () => {
    setVerifying(true);

    // Simulate verification
    await new Promise((resolve) => setTimeout(resolve, 1500));

    // Mock result
    setResult({
      valid: true,
      claim: 'Balance exceeds $10,000',
      accountId: '0x1234...5678',
      timestamp: Date.now() - 3600000,
      expiresAt: Date.now() + 86400000,
    });

    setVerifying(false);
  };

  return (
    <div className="min-h-screen bg-background py-8 px-4">
      <div className="max-w-2xl mx-auto space-y-6">
        <div className="text-center">
          <h1 className="text-3xl font-bold flex items-center justify-center gap-2">
            <Shield className="w-8 h-8 text-primary" />
            Proof Verifier
          </h1>
          <p className="text-muted-foreground mt-2">
            Verify selective disclosure proofs without accessing private data
          </p>
        </div>

        <Card>
          <CardHeader>
            <CardTitle>Verify a Proof</CardTitle>
            <CardDescription>
              Paste a proof or upload a proof file to verify its validity
            </CardDescription>
          </CardHeader>
          <CardContent className="space-y-4">
            <div className="space-y-2">
              <Label htmlFor="proof">Proof Data</Label>
              <Input
                id="proof"
                placeholder="Paste proof data here..."
                value={proofInput}
                onChange={(e) => setProofInput(e.target.value)}
              />
            </div>

            <div className="flex gap-2">
              <Button
                onClick={handleVerify}
                disabled={verifying || !proofInput}
                className="flex-1"
              >
                {verifying ? (
                  <>Verifying...</>
                ) : (
                  <>
                    <Search className="w-4 h-4 mr-2" />
                    Verify Proof
                  </>
                )}
              </Button>
              <Button variant="outline">
                <Upload className="w-4 h-4 mr-2" />
                Upload File
              </Button>
            </div>
          </CardContent>
        </Card>

        {result && (
          <Card className={result.valid ? 'border-green-500' : 'border-red-500'}>
            <CardHeader>
              <CardTitle className="flex items-center gap-2">
                {result.valid ? (
                  <>
                    <CheckCircle className="w-6 h-6 text-green-500" />
                    Proof Valid
                  </>
                ) : (
                  <>
                    <XCircle className="w-6 h-6 text-red-500" />
                    Proof Invalid
                  </>
                )}
              </CardTitle>
            </CardHeader>
            <CardContent className="space-y-4">
              <div className="grid grid-cols-2 gap-4">
                <div>
                  <p className="text-sm text-muted-foreground">Claim</p>
                  <p className="font-medium">{result.claim}</p>
                </div>
                <div>
                  <p className="text-sm text-muted-foreground">Account</p>
                  <p className="font-mono">{result.accountId}</p>
                </div>
                <div>
                  <p className="text-sm text-muted-foreground">Generated</p>
                  <p>{new Date(result.timestamp).toLocaleString()}</p>
                </div>
                <div>
                  <p className="text-sm text-muted-foreground">Expires</p>
                  <p>{new Date(result.expiresAt).toLocaleString()}</p>
                </div>
              </div>

              <Alert>
                <Shield className="w-4 h-4" />
                <AlertDescription>
                  This proof was verified using zero-knowledge cryptography.
                  The verifier learned ONLY that the claim is true, without
                  accessing any private data.
                </AlertDescription>
              </Alert>
            </CardContent>
          </Card>
        )}

        <Card>
          <CardHeader>
            <CardTitle>What Can Be Verified</CardTitle>
          </CardHeader>
          <CardContent>
            <div className="grid grid-cols-2 gap-4">
              <div className="flex items-center gap-2">
                <Badge>Balance</Badge>
                <span className="text-sm">Exceeds threshold</span>
              </div>
              <div className="flex items-center gap-2">
                <Badge>Tier</Badge>
                <span className="text-sm">Account tier level</span>
              </div>
              <div className="flex items-center gap-2">
                <Badge>KYC</Badge>
                <span className="text-sm">Verification level</span>
              </div>
              <div className="flex items-center gap-2">
                <Badge>Accreditation</Badge>
                <span className="text-sm">Investor status</span>
              </div>
            </div>
          </CardContent>
        </Card>
      </div>
    </div>
  );
};

export default ProofVerifier;

Testing Your Contract

Test Suite

Create custodian-contract/src/test/custodian.test.ts:

import { describe, it, expect, beforeEach } from 'vitest';
import { CustodianSimulator } from './simulators/simulator';

describe('Custodian Contract with Selective Disclosure', () => {
  let simulator: CustodianSimulator;

  beforeEach(() => {
    simulator = CustodianSimulator.deploy({
      adminAddress: 'admin-001',
      tier1: 10000n,
      tier2: 100000n,
      tier3: 1000000n,
    });
  });

  describe('Account Management', () => {
    it('registers a new account', () => {
      simulator.registerAccount('user-001');

      const ledger = simulator.getLedger();
      expect(ledger.totalAccounts).toBe(1n);
      expect(simulator.accountExists('user-001')).toBe(true);
    });

    it('prevents duplicate account registration', () => {
      simulator.registerAccount('user-001');

      expect(() => {
        simulator.registerAccount('user-001');
      }).toThrow('Account already exists');
    });

    it('handles deposits correctly', () => {
      simulator.registerAccount('user-001');
      simulator.deposit('user-001', 50000n);

      const ledger = simulator.getLedger();
      expect(ledger.totalAssetsUnderCustody).toBe(50000n);
    });
  });

  describe('KYC Verification', () => {
    it('verifies KYC for an account', () => {
      simulator.registerAccount('user-001');
      simulator.verifyKYC('user-001', 2);

      expect(simulator.getKYCLevel('user-001')).toBe(2);
      expect(simulator.isKYCVerified('user-001')).toBe(true);
    });

    it('requires valid KYC level', () => {
      simulator.registerAccount('user-001');

      expect(() => {
        simulator.verifyKYC('user-001', 5);
      }).toThrow('Invalid KYC level');
    });
  });

  describe('Selective Disclosure', () => {
    beforeEach(() => {
      simulator.registerAccount('user-001');
      simulator.deposit('user-001', 150000n);
      simulator.verifyKYC('user-001', 2);
    });

    it('proves balance above threshold', () => {
      // This should succeed - balance 150000 > 100000
      expect(() => {
        simulator.proveBalanceAboveThreshold('user-001', 100000n, 150000n);
      }).not.toThrow();
    });

    it('fails proof when balance is insufficient', () => {
      // This should fail - balance 150000 < 200000
      expect(() => {
        simulator.proveBalanceAboveThreshold('user-001', 200000n, 150000n);
      }).toThrow('Balance below threshold');
    });

    it('proves balance in range', () => {
      expect(() => {
        simulator.proveBalanceInRange('user-001', 100000n, 200000n, 150000n);
      }).not.toThrow();
    });

    it('fails range proof when outside range', () => {
      expect(() => {
        simulator.proveBalanceInRange('user-001', 200000n, 300000n, 150000n);
      }).toThrow('Balance below minimum');
    });

    it('proves account tier', () => {
      // Balance 150000 qualifies for Tier 2 (100000 threshold)
      expect(() => {
        simulator.proveAccountTier('user-001', 150000n, 2);
      }).not.toThrow();
    });

    it('fails tier proof for higher tier', () => {
      // Balance 150000 does not qualify for Tier 3 (1000000 threshold)
      expect(() => {
        simulator.proveAccountTier('user-001', 150000n, 3);
      }).toThrow('Insufficient balance for Tier 3');
    });

    it('proves KYC level', () => {
      expect(() => {
        simulator.proveKYCLevel('user-001', 2);
      }).not.toThrow();
    });

    it('proves investment eligibility', () => {
      simulator.verifyAccreditation('user-001', 1);

      expect(() => {
        simulator.proveInvestmentEligibility('user-001', 2, 100000n, 150000n);
      }).not.toThrow();
    });
  });

  describe('Admin Functions', () => {
    it('freezes an account', () => {
      simulator.registerAccount('user-001');
      simulator.freezeAccount('user-001');

      expect(simulator.getAccountStatus('user-001')).toBe(2); // Frozen
    });

    it('unfreezes an account', () => {
      simulator.registerAccount('user-001');
      simulator.freezeAccount('user-001');
      simulator.unfreezeAccount('user-001');

      expect(simulator.getAccountStatus('user-001')).toBe(1); // Active
    });

    it('prevents operations on frozen accounts', () => {
      simulator.registerAccount('user-001');
      simulator.freezeAccount('user-001');

      expect(() => {
        simulator.deposit('user-001', 10000n);
      }).toThrow('Account not active');
    });
  });

  describe('Privacy Guarantees', () => {
    it('does not expose actual balance in ledger', () => {
      simulator.registerAccount('user-001');
      simulator.deposit('user-001', 150000n);

      const ledger = simulator.getLedger();
      // Ledger should only show aggregate, not individual balance
      expect(ledger.totalAssetsUnderCustody).toBe(150000n);
      // Individual balance should not be accessible from ledger
    });

    it('increments proof counter without exposing proof details', () => {
      simulator.registerAccount('user-001');
      simulator.deposit('user-001', 150000n);

      const before = simulator.getLedger().proofVerificationLog;
      simulator.proveBalanceAboveThreshold('user-001', 100000n, 150000n);
      const after = simulator.getLedger().proofVerificationLog;

      expect(after).toBe(before + 1n);
    });
  });
});

Test Simulator

Create custodian-contract/src/test/simulators/simulator.ts:

type LedgerState = {
  totalAccounts: bigint;
  totalAssetsUnderCustody: bigint;
  initialized: boolean;
  tierOneThreshold: bigint;
  tierTwoThreshold: bigint;
  tierThreeThreshold: bigint;
  proofVerificationLog: bigint;
};

type AccountState = {
  exists: boolean;
  status: number;
  kycVerified: boolean;
  kycLevel: number;
  accreditationStatus: number;
};

type InitConfig = {
  adminAddress: string;
  tier1: bigint;
  tier2: bigint;
  tier3: bigint;
};

export class CustodianSimulator {
  private ledger: LedgerState;
  private accounts: Map<string, AccountState>;
  private balances: Map<string, bigint>;

  private constructor(config: InitConfig) {
    this.ledger = {
      totalAccounts: 0n,
      totalAssetsUnderCustody: 0n,
      initialized: true,
      tierOneThreshold: config.tier1,
      tierTwoThreshold: config.tier2,
      tierThreeThreshold: config.tier3,
      proofVerificationLog: 0n,
    };
    this.accounts = new Map();
    this.balances = new Map();
  }

  static deploy(config: InitConfig): CustodianSimulator {
    return new CustodianSimulator(config);
  }

  getLedger(): LedgerState {
    return { ...this.ledger };
  }

  accountExists(accountId: string): boolean {
    return this.accounts.has(accountId);
  }

  getAccountStatus(accountId: string): number {
    return this.accounts.get(accountId)?.status ?? 0;
  }

  getKYCLevel(accountId: string): number {
    return this.accounts.get(accountId)?.kycLevel ?? 0;
  }

  isKYCVerified(accountId: string): boolean {
    return this.accounts.get(accountId)?.kycVerified ?? false;
  }

  registerAccount(accountId: string): void {
    if (this.accounts.has(accountId)) {
      throw new Error('Account already exists');
    }

    this.accounts.set(accountId, {
      exists: true,
      status: 1,
      kycVerified: false,
      kycLevel: 0,
      accreditationStatus: 0,
    });
    this.balances.set(accountId, 0n);
    this.ledger.totalAccounts += 1n;
  }

  deposit(accountId: string, amount: bigint): void {
    const account = this.accounts.get(accountId);
    if (!account) throw new Error('Account does not exist');
    if (account.status !== 1) throw new Error('Account not active');

    this.balances.set(accountId, (this.balances.get(accountId) ?? 0n) + amount);
    this.ledger.totalAssetsUnderCustody += amount;
  }

  verifyKYC(accountId: string, level: number): void {
    const account = this.accounts.get(accountId);
    if (!account) throw new Error('Account does not exist');
    if (level < 1 || level > 3) throw new Error('Invalid KYC level');

    account.kycVerified = true;
    account.kycLevel = level;
  }

  verifyAccreditation(accountId: string, status: number): void {
    const account = this.accounts.get(accountId);
    if (!account) throw new Error('Account does not exist');
    if (!account.kycVerified) throw new Error('KYC required first');

    account.accreditationStatus = status;
  }

  proveBalanceAboveThreshold(
    accountId: string,
    threshold: bigint,
    actualBalance: bigint
  ): void {
    const account = this.accounts.get(accountId);
    if (!account) throw new Error('Account does not exist');
    if (actualBalance < threshold) throw new Error('Balance below threshold');

    this.ledger.proofVerificationLog += 1n;
  }

  proveBalanceInRange(
    accountId: string,
    min: bigint,
    max: bigint,
    actualBalance: bigint
  ): void {
    const account = this.accounts.get(accountId);
    if (!account) throw new Error('Account does not exist');
    if (actualBalance < min) throw new Error('Balance below minimum');
    if (actualBalance > max) throw new Error('Balance above maximum');

    this.ledger.proofVerificationLog += 1n;
  }

  proveAccountTier(
    accountId: string,
    actualBalance: bigint,
    claimedTier: number
  ): void {
    const account = this.accounts.get(accountId);
    if (!account) throw new Error('Account does not exist');

    if (claimedTier === 1 && actualBalance < this.ledger.tierOneThreshold) {
      throw new Error('Insufficient balance for Tier 1');
    }
    if (claimedTier === 2 && actualBalance < this.ledger.tierTwoThreshold) {
      throw new Error('Insufficient balance for Tier 2');
    }
    if (claimedTier === 3 && actualBalance < this.ledger.tierThreeThreshold) {
      throw new Error('Insufficient balance for Tier 3');
    }

    this.ledger.proofVerificationLog += 1n;
  }

  proveKYCLevel(accountId: string, minimumLevel: number): void {
    const account = this.accounts.get(accountId);
    if (!account) throw new Error('Account does not exist');
    if (!account.kycVerified) throw new Error('KYC not completed');
    if (account.kycLevel < minimumLevel) throw new Error('KYC level insufficient');

    this.ledger.proofVerificationLog += 1n;
  }

  proveInvestmentEligibility(
    accountId: string,
    minKYC: number,
    minBalance: bigint,
    actualBalance: bigint
  ): void {
    const account = this.accounts.get(accountId);
    if (!account) throw new Error('Account does not exist');
    if (!account.kycVerified) throw new Error('KYC required');
    if (account.kycLevel < minKYC) throw new Error('Insufficient KYC level');
    if (actualBalance < minBalance) throw new Error('Insufficient balance');

    this.ledger.proofVerificationLog += 1n;
  }

  freezeAccount(accountId: string): void {
    const account = this.accounts.get(accountId);
    if (!account) throw new Error('Account does not exist');
    account.status = 2;
  }

  unfreezeAccount(accountId: string): void {
    const account = this.accounts.get(accountId);
    if (!account) throw new Error('Account does not exist');
    if (account.status !== 2) throw new Error('Account not frozen');
    account.status = 1;
  }
}

Running Tests

# Navigate to contract directory
cd custodian-contract

# Run tests
npm run test

# Run with coverage
npm run test -- --coverage

Deployment Guide

Local Development

# Terminal 1: Start local Midnight infrastructure
npm run setup-standalone

# Terminal 2: Start frontend
npm run dev:frontend

Preview Network Deployment

Configure Environment

# custodian-cli/.env
MY_PREVIEW_MNEMONIC="your twelve word mnemonic phrase"
ADMIN_ADDRESS="your-admin-address"

Deploy Contract

cd custodian-cli
npm run deploy

Initialize Contract

// Initialize with tier thresholds
await contract.initialize(
  adminAddress,
  10000n,    // Tier 1: $10,000
  100000n,   // Tier 2: $100,000
  1000000n   // Tier 3: $1,000,000
);

Deployment Checklist

[ ] Contract compiled successfully
[ ] All tests passing
[ ] Environment variables configured
[ ] Admin wallet funded with tSTAR
[ ] Tier thresholds defined
[ ] Contract deployed
[ ] Contract initialized
[ ] Frontend configured with contract address

Advanced Patterns

Pattern 1: Multi-Asset Custody

// Support multiple asset types
export ledger assetTypes: Map<Bytes<32>, Boolean>;
export ledger assetTotals: Map<Bytes<32>, Counter>;

export circuit depositAsset(
  accountId: Bytes<32>,
  assetId: Bytes<32>,
  amount: Uint<64>
): [] {
  assert(accountExists[accountId], "Account does not exist");
  assert(assetTypes[assetId], "Asset type not supported");

  assetTotals[assetId].increment(amount);
}

// Prove holdings in specific asset
export circuit proveAssetHolding(
  accountId: Bytes<32>,
  assetId: Bytes<32>,
  actualHolding: Uint<64>,  // Private witness
  minHolding: Uint<64>
): [] {
  assert(actualHolding >= minHolding, "Insufficient holding");
  proofVerificationLog.increment(1);
}

Pattern 2: Time-Bound Proofs

export ledger proofValidityPeriod: Uint<64>;  // In seconds

export circuit proveBalanceWithExpiry(
  accountId: Bytes<32>,
  threshold: Uint<64>,
  actualBalance: Uint<64>,
  currentTime: Uint<64>,
  expiryTime: Uint<64>
): [] {
  assert(expiryTime > currentTime, "Proof already expired");
  assert(expiryTime <= currentTime + proofValidityPeriod, "Expiry too far");
  assert(actualBalance >= threshold, "Balance below threshold");

  proofVerificationLog.increment(1);
}

Pattern 3: Delegated Proofs

// Allow authorized parties to generate proofs
export ledger authorizedDelegates: Map<Bytes<32>, Map<Bytes<32>, Boolean>>;

export circuit authorizeDelegateForProofs(
  accountId: Bytes<32>,
  delegateId: Bytes<32>
): [] {
  assert(accountExists[accountId], "Account does not exist");
  // Caller must be account owner (verified via signature)
  authorizedDelegates[accountId][delegateId] = true;
}

export circuit delegatedBalanceProof(
  accountId: Bytes<32>,
  delegateId: Bytes<32>,
  threshold: Uint<64>,
  actualBalance: Uint<64>
): [] {
  assert(authorizedDelegates[accountId][delegateId], "Not authorized");
  assert(actualBalance >= threshold, "Balance below threshold");

  proofVerificationLog.increment(1);
}

Pattern 4: Compliance Reporting

// Generate aggregate compliance reports without individual disclosure
export ledger complianceReportCount: Counter;

export circuit generateComplianceReport(
  reportType: Uint<8>,
  aggregateData: Uint<64>,  // Private aggregate
  threshold: Uint<64>
): [] {
  // Prove aggregate metrics meet compliance requirements
  // without revealing individual account data
  assert(aggregateData >= threshold, "Compliance threshold not met");

  complianceReportCount.increment(1);
}

Pattern 5: Proof Revocation

export ledger revokedProofs: Map<Bytes<32>, Boolean>;

export circuit revokeProof(
  proofId: Bytes<32>,
  adminSig: Bytes<32>
): [] {
  // Admin can revoke proofs if account status changes
  revokedProofs[proofId] = true;
}

// Verifier checks revocation status
pure function isProofValid(proofId: Bytes<32>): Boolean {
  return !revokedProofs[proofId];
}

Compliance & Regulatory Considerations

KYC/AML Integration

Selective disclosure enables compliance without data exposure:

Requirement	Traditional Approach	Selective Disclosure
Identity Verification	Share ID documents	Prove "ID verified by provider X"
Address Verification	Share utility bills	Prove "Residency verified"
Source of Funds	Bank statements	Prove "Funds from verified source"
Sanctions Check	Full name/DOB	Prove "Cleared sanctions check"

Regulatory Benefits

GDPR Compliance: Minimize data collection/exposure
Data Breach Mitigation: Less sensitive data to protect
Right to be Forgotten: Easier to delete (less data stored)
Audit Trails: Cryptographic proof of compliance

Auditor Access

Auditors can verify:

Total assets under custody (aggregate)
Number of KYC-verified accounts
Compliance proof counts
System health metrics

Without accessing:

Individual balances
Personal information
Transaction details

Next Steps & Resources

Learning Path

Beginner: Implement basic account management
Intermediate: Add selective disclosure circuits
Advanced: Multi-asset custody with compliance reporting

Use Case Extensions

Decentralized Exchange: Prove sufficient balance for trades
Lending Platform: Prove collateral without revealing portfolio
Insurance: Prove coverage without revealing policy details
Healthcare: Prove insurance status without medical records

Official Resources

Midnight Documentation: docs.midnight.network
Compact Language Guide: docs.midnight.network/compact
Lace Wallet: lace.io
Faucet: faucet.preview.midnight.network

Quick Reference

Compact Disclosure Patterns

// Threshold proof
export circuit proveThreshold(
  actual: Uint<64>,    // Private witness
  threshold: Uint<64>  // Public parameter
): [] {
  assert(actual >= threshold, "Below threshold");
}

// Range proof
export circuit proveRange(
  actual: Uint<64>,
  min: Uint<64>,
  max: Uint<64>
): [] {
  assert(actual >= min, "Below minimum");
  assert(actual <= max, "Above maximum");
}

// Set membership proof
export circuit proveMembership(
  value: Uint<8>,
  validSet: Vector<Uint<8>, 10>
): [] {
  // Prove value is in validSet
}

Disclosure Types Summary

Type	Reveals	Hides
Balance Threshold	"Balance > X"	Exact balance
Balance Range	"X < Balance < Y"	Exact balance
Account Tier	Tier level	Balance that determines tier
KYC Level	Verification level	Documents, personal data
Accreditation	Status	Financial details
Age Verification	"Age > X"	Birth date

Conclusion

This tutorial demonstrated how to build a privacy-preserving custodian application with selective disclosure on Midnight. Key takeaways:

Zero-Knowledge Proofs enable proving claims without revealing underlying data
Selective Disclosure gives users control over what information they share
Compliance is achievable while maximizing privacy
Auditable systems don't require full transparency

The custodian pattern applies to:

Financial services
Healthcare records
Identity management
Credential verification
Any scenario requiring verified claims with privacy

Build trust through cryptographic proof, not data exposure.

Built with the Midnight Starter Template

Webisoft Development Labs

Building a Privacy-Preserving Voting System on Midnight: A Complete Developer Tutorial

UtkarshVarma — Wed, 14 Jan 2026 19:59:19 +0000

A comprehensive guide to building anonymous, verifiable voting dApps using Midnight Network and zero-knowledge proofs

Introduction to Private Voting
Why Build Voting Systems on Midnight?
Understanding the Voting Architecture
Prerequisites & Setup
Project Structure
Writing the Voting Contract in Compact
Building the Complete Voting System
Frontend Integration with React
Testing Your Voting Contract
Deployment Guide
Advanced Voting Patterns
Troubleshooting & Best Practices
Next Steps & Resources

Introduction to Private Voting

The Problem with Traditional Blockchain Voting

Voting is one of the most critical democratic processes, yet implementing it on traditional blockchains presents a fundamental paradox:

Transparency vs Privacy: Blockchains are transparent by design, but votes should be private
Verifiability vs Anonymity: We need to verify votes are valid without revealing who voted for what
Coercion Resistance: Public votes enable vote buying and coercion

Midnight's Solution

Midnight solves these problems using zero-knowledge proofs (ZK proofs):

Anonymous Voting: Prove you're eligible to vote without revealing your identity
Verifiable Results: Anyone can verify the vote count is correct
Coercion Resistant: No one can prove how you voted, even if you want to
Double-Vote Prevention: Cryptographically prevent voting twice

Real-World Applications

Use Case	Description
DAO Governance	Token-weighted voting without revealing holdings
Corporate Boards	Anonymous board member decisions
Community Polls	Private opinion gathering
Elections	Secure, verifiable democratic voting
Jury Systems	Anonymous verdict deliberation

Why Build Voting Systems on Midnight?

Traditional Voting System Problems

+------------------------------------------+
|        Traditional Blockchain Vote       |
+------------------------------------------+
| Transaction: 0x123...                    |
| From: Alice (0xabc...)                   |
| Vote: Candidate B        <-- VISIBLE!    |
| Timestamp: 2024-01-15                    |
+------------------------------------------+
         |
         v
   Everyone knows Alice voted for Candidate B
   - Vote buying possible
   - Social pressure
   - Retaliation risk

Midnight's Private Voting

+------------------------------------------+
|          Midnight Private Vote           |
+------------------------------------------+
| ZK Proof: Valid voter, valid choice      |
| Public: Vote counted +1                  |
| Private: Identity, choice  <-- HIDDEN!   |
+------------------------------------------+
         |
         v
   No one knows who voted for what
   + Verifiable total count
   + Provably fair
   + Coercion resistant

Key Privacy Guarantees

Property	Description	How Midnight Achieves It
Ballot Secrecy	No one sees your vote	ZK proofs hide vote content
Eligibility Proof	Prove you can vote	ZK proof of membership
Double-Vote Prevention	Can't vote twice	Nullifier commitments
Verifiable Tally	Anyone can verify count	Public ledger state
Coercion Resistance	Can't prove your vote	No receipt possible

Understanding the Voting Architecture

System Overview

+------------------------------------------------------------------+
|                         VOTING SYSTEM                             |
+------------------------------------------------------------------+
|                                                                   |
|  +------------------+          +------------------+               |
|  |   Voter A        |          |   Voter B        |               |
|  +------------------+          +------------------+               |
|  | Private:         |          | Private:         |               |
|  | - Eligibility    |          | - Eligibility    |               |
|  | - Vote choice    |          | - Vote choice    |               |
|  | - Nullifier      |          | - Nullifier      |               |
|  +--------+---------+          +--------+---------+               |
|           |                             |                         |
|           | ZK Proof                    | ZK Proof                |
|           v                             v                         |
|  +--------------------------------------------------------+      |
|  |                    SMART CONTRACT                       |      |
|  +--------------------------------------------------------+      |
|  | Public Ledger:                                          |      |
|  | - Proposal details                                      |      |
|  | - Vote counts per option                                |      |
|  | - Voting deadline                                       |      |
|  | - Used nullifiers (hashed)                              |      |
|  +--------------------------------------------------------+      |
|                                                                   |
+------------------------------------------------------------------+

Key Components

1. Voter Registry

A system to verify voter eligibility without revealing identity:

Merkle tree of eligible voters
ZK proof of membership

2. Nullifier System

Prevents double voting while maintaining anonymity:

Each voter generates a unique nullifier
Nullifier is revealed (hashed) when voting
Contract rejects duplicate nullifiers

3. Vote Tallying

Transparent counting with private ballots:

Public counters for each option
ZK proofs verify valid votes
Anyone can verify final tally

4. Time Controls

Enforce voting periods:

Registration phase
Voting phase
Reveal/tally phase

Prerequisites & Setup

Required Tools

# Check prerequisites
node -v   # Required: v23+
npm -v    # Required: v11+
docker -v # Required: Latest

Step 1: Install Git LFS

# macOS
brew install git-lfs

# Ubuntu/Debian
sudo apt-get install git-lfs

# Initialize
git lfs install

Step 2: Install Compact Compiler

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

# Install compiler version 0.27.0
compact update +0.27.0

# Verify installation
compact check

Step 3: Install Lace Wallet

Install from Chrome Web Store
Create a new wallet
Switch to Midnight Preview Network
Get test tokens from Faucet

Step 4: Clone and Setup

# Clone the repository
git clone https://github.com/MeshJS/midnight-starter-template.git
cd midnight-starter-template

# Install dependencies
npm install

# Build the project
npm run build

Project Structure

Voting dApp Directory Layout

midnight-voting-dapp/
├── voting-contract/              # Smart contract code
│   ├── src/
│   │   ├── voting.compact        # Main voting logic
│   │   ├── witnesses.ts          # Private state types
│   │   ├── managed/              # Compiled artifacts
│   │   └── test/                 # Contract tests
│   │       ├── voting.test.ts
│   │       └── simulators/
│   └── package.json
│
├── voting-cli/                   # CLI deployment tools
│   ├── src/
│   │   ├── config.ts             # Network configurations
│   │   ├── deploy.ts             # Deployment script
│   │   └── admin.ts              # Admin operations
│   └── package.json
│
├── frontend-vite-react/          # React frontend
│   ├── src/
│   │   ├── pages/
│   │   │   ├── create-proposal/  # Create new proposals
│   │   │   ├── vote/             # Voting interface
│   │   │   └── results/          # View results
│   │   ├── components/
│   │   │   ├── ProposalCard.tsx
│   │   │   ├── VoteButton.tsx
│   │   │   └── ResultsChart.tsx
│   │   └── modules/midnight/
│   │       └── voting-sdk/       # Contract interaction
│   └── package.json
│
├── package.json
└── turbo.json

Writing the Voting Contract in Compact

Basic Voting Contract

Create voting-contract/src/voting.compact:

pragma language_version >= 0.19;

import CompactStandardLibrary;

// ============================================
// VOTING SYSTEM SMART CONTRACT
// A privacy-preserving voting system on Midnight
// ============================================

// Proposal states
// 0 = Created (registration open)
// 1 = Active (voting open)
// 2 = Ended (results final)

// ============================================
// PUBLIC LEDGER STATE
// ============================================

// Proposal metadata
export ledger proposalState: Uint<8>;
export ledger proposalTitle: Bytes<64>;
export ledger optionCount: Uint<8>;

// Vote tallies for up to 4 options
export ledger votesOption1: Counter;
export ledger votesOption2: Counter;
export ledger votesOption3: Counter;
export ledger votesOption4: Counter;

// Voting controls
export ledger totalVoters: Counter;
export ledger votingDeadline: Uint<64>;

// Admin
export ledger admin: Bytes<32>;

// ============================================
// CIRCUITS (State-changing functions)
// ============================================

// Initialize a new proposal
export circuit createProposal(
  title: Bytes<64>,
  options: Uint<8>,
  deadline: Uint<64>,
  adminKey: Bytes<32>
): [] {
  assert(proposalState == 0, "Proposal already exists");
  assert(options >= 2, "Need at least 2 options");
  assert(options <= 4, "Maximum 4 options");

  proposalTitle = title;
  optionCount = options;
  votingDeadline = deadline;
  admin = adminKey;
  proposalState = 1;
}

// Cast a vote for an option (1-4)
export circuit castVote(option: Uint<8>): [] {
  // Verify voting is active
  assert(proposalState == 1, "Voting not active");

  // Verify valid option
  assert(option >= 1, "Invalid option: too low");
  assert(option <= optionCount, "Invalid option: too high");

  // Increment the appropriate counter
  if (option == 1) {
    votesOption1.increment(1);
  } else if (option == 2) {
    votesOption2.increment(1);
  } else if (option == 3) {
    votesOption3.increment(1);
  } else if (option == 4) {
    votesOption4.increment(1);
  }

  // Track total votes
  totalVoters.increment(1);
}

// End voting period (admin only)
export circuit endVoting(adminKey: Bytes<32>): [] {
  assert(proposalState == 1, "Voting not active");
  assert(adminKey == admin, "Not authorized");

  proposalState = 2;
}

// Reset for new proposal (admin only)
export circuit resetProposal(adminKey: Bytes<32>): [] {
  assert(adminKey == admin, "Not authorized");

  proposalState = 0;
}

Private State Definition

Create voting-contract/src/witnesses.ts:

// ============================================
// PRIVATE STATE TYPES
// Stored locally, never on-chain
// ============================================

export type VotingPrivateState = {
  // Voter's eligibility proof data
  voterSecret: string;

  // The vote choice (kept private until cast)
  pendingVote: number;

  // Has this voter already voted?
  hasVoted: boolean;

  // Nullifier to prevent double voting
  nullifier: string;
};

export const createPrivateState = (): VotingPrivateState => {
  return {
    voterSecret: '',
    pendingVote: 0,
    hasVoted: false,
    nullifier: '',
  };
};

// Generate a unique nullifier for this voter
export const generateNullifier = (voterSecret: string, proposalId: string): string => {
  // In production, use proper cryptographic hash
  return `nullifier-${voterSecret}-${proposalId}`;
};

// Create voter eligibility proof
export const createEligibilityProof = (voterSecret: string): string => {
  // In production, this would be a ZK proof of membership
  return `eligibility-${voterSecret}`;
};

export const witnesses = {};

Building the Complete Voting System

Enhanced Contract with Double-Vote Prevention

Create voting-contract/src/voting-advanced.compact:

pragma language_version >= 0.19;

import CompactStandardLibrary;

// ============================================
// ADVANCED VOTING SYSTEM
// With double-vote prevention and eligibility
// ============================================

// Proposal states
export ledger proposalState: Uint<8>;
export ledger proposalId: Bytes<32>;

// Vote tallies
export ledger votesOption1: Counter;
export ledger votesOption2: Counter;
export ledger votesOption3: Counter;
export ledger votesOption4: Counter;

// Option labels (stored as hashes for space efficiency)
export ledger option1Label: Bytes<32>;
export ledger option2Label: Bytes<32>;
export ledger option3Label: Bytes<32>;
export ledger option4Label: Bytes<32>;

// Metadata
export ledger optionCount: Uint<8>;
export ledger totalVotes: Counter;
export ledger registeredVoters: Counter;

// Timing
export ledger votingStartTime: Uint<64>;
export ledger votingEndTime: Uint<64>;

// Admin
export ledger admin: Bytes<32>;

// ============================================
// PROPOSAL MANAGEMENT
// ============================================

// Create a new proposal with options
export circuit initializeProposal(
  id: Bytes<32>,
  numOptions: Uint<8>,
  label1: Bytes<32>,
  label2: Bytes<32>,
  label3: Bytes<32>,
  label4: Bytes<32>,
  startTime: Uint<64>,
  endTime: Uint<64>,
  adminKey: Bytes<32>
): [] {
  assert(proposalState == 0, "Proposal exists");
  assert(numOptions >= 2, "Min 2 options");
  assert(numOptions <= 4, "Max 4 options");
  assert(endTime > startTime, "Invalid timeframe");

  proposalId = id;
  optionCount = numOptions;
  option1Label = label1;
  option2Label = label2;
  option3Label = label3;
  option4Label = label4;
  votingStartTime = startTime;
  votingEndTime = endTime;
  admin = adminKey;

  proposalState = 1;
}

// ============================================
// VOTING
// ============================================

// Cast an anonymous vote
export circuit vote(choice: Uint<8>): [] {
  // Verify voting is active
  assert(proposalState == 1, "Voting not active");

  // Verify valid choice
  assert(choice >= 1, "Choice too low");
  assert(choice <= optionCount, "Choice too high");

  // Record vote
  if (choice == 1) {
    votesOption1.increment(1);
  } else if (choice == 2) {
    votesOption2.increment(1);
  } else if (choice == 3) {
    votesOption3.increment(1);
  } else if (choice == 4) {
    votesOption4.increment(1);
  }

  totalVotes.increment(1);
}

// ============================================
// ADMIN FUNCTIONS
// ============================================

// Finalize voting
export circuit finalizeVoting(adminKey: Bytes<32>): [] {
  assert(proposalState == 1, "Not active");
  assert(adminKey == admin, "Unauthorized");

  proposalState = 2;
}

// Get winner (pure function - no state change)
export pure function getLeadingOption(
  v1: Uint<64>,
  v2: Uint<64>,
  v3: Uint<64>,
  v4: Uint<64>
): Uint<8> {
  let maxVotes: Uint<64> = v1;
  let winner: Uint<8> = 1;

  if (v2 > maxVotes) {
    maxVotes = v2;
    winner = 2;
  }
  if (v3 > maxVotes) {
    maxVotes = v3;
    winner = 3;
  }
  if (v4 > maxVotes) {
    winner = 4;
  }

  return winner;
}

Contract Controller

Create frontend-vite-react/src/modules/midnight/voting-sdk/api/votingController.ts:

import * as Rx from 'rxjs';
import {
  type ContractAddress,
  type DeployedContract,
} from '@midnight-ntwrk/midnight-js-contracts';
import {
  deployContract,
  findDeployedContract,
} from '@midnight-ntwrk/midnight-js-contracts';
import { type Logger } from 'pino';

// Import compiled contract
import { Contract as VotingContract } from '../contract/managed/voting/contract/index.cjs';
import {
  createPrivateState,
  type VotingPrivateState,
} from '../contract/witnesses';

// Contract instance
const votingContractInstance = new VotingContract.Contract({});

// Derived state type
export type DerivedState = {
  proposalState: number;
  optionCount: number;
  votes: {
    option1: bigint;
    option2: bigint;
    option3: bigint;
    option4: bigint;
  };
  totalVotes: bigint;
  hasVoted: boolean;
};

// Provider types
export type VotingProviders = {
  publicDataProvider: any;
  privateStateProvider: any;
  zkConfigProvider: any;
  walletProvider: any;
  midnightProvider: any;
};

export interface VotingControllerInterface {
  readonly deployedContractAddress: ContractAddress;
  readonly state$: Rx.Observable<DerivedState>;
  vote(choice: number): Promise<void>;
  createProposal(
    title: string,
    options: number,
    deadline: number,
    adminKey: string
  ): Promise<void>;
  endVoting(adminKey: string): Promise<void>;
}

export class VotingController implements VotingControllerInterface {
  readonly deployedContractAddress: ContractAddress;
  readonly state$: Rx.Observable<DerivedState>;

  private constructor(
    private readonly deployedContract: DeployedContract<
      typeof votingContractInstance
    >,
    private readonly providers: VotingProviders,
    private readonly logger: Logger
  ) {
    this.deployedContractAddress = deployedContract.deployTxData.public.contractAddress;
    this.state$ = this.createStateObservable();
  }

  // Deploy new voting contract
  static async deploy(
    providers: VotingProviders,
    logger: Logger
  ): Promise<VotingController> {
    logger.info('Deploying voting contract...');

    const deployedContract = await deployContract(providers, {
      contract: votingContractInstance,
      initialPrivateState: createPrivateState(),
    });

    logger.info(
      `Contract deployed at: ${deployedContract.deployTxData.public.contractAddress}`
    );

    return new VotingController(deployedContract, providers, logger);
  }

  // Join existing voting contract
  static async join(
    contractAddress: ContractAddress,
    providers: VotingProviders,
    logger: Logger
  ): Promise<VotingController> {
    logger.info(`Joining voting contract at: ${contractAddress}`);

    const deployedContract = await findDeployedContract(providers, {
      contractAddress,
      contract: votingContractInstance,
      privateStateId: 'votingPrivateState',
      initialPrivateState: createPrivateState(),
    });

    return new VotingController(deployedContract, providers, logger);
  }

  // Create state observable
  private createStateObservable(): Rx.Observable<DerivedState> {
    return this.providers.publicDataProvider
      .contractStateObservable(this.deployedContractAddress, { type: 'all' })
      .pipe(
        Rx.map((state: any) => {
          const ledger = VotingContract.ledger(state.data);
          return {
            proposalState: Number(ledger.proposalState),
            optionCount: Number(ledger.optionCount),
            votes: {
              option1: ledger.votesOption1,
              option2: ledger.votesOption2,
              option3: ledger.votesOption3,
              option4: ledger.votesOption4,
            },
            totalVotes: ledger.totalVoters,
            hasVoted: false, // Tracked in private state
          };
        })
      );
  }

  // Cast a vote
  async vote(choice: number): Promise<void> {
    this.logger.info(`Casting vote for option ${choice}`);

    // Convert choice to proper type
    const choiceBytes = BigInt(choice);

    await this.deployedContract.callTx.castVote(choiceBytes);

    this.logger.info('Vote cast successfully');
  }

  // Create new proposal
  async createProposal(
    title: string,
    options: number,
    deadline: number,
    adminKey: string
  ): Promise<void> {
    this.logger.info(`Creating proposal: ${title}`);

    // Convert strings to bytes
    const titleBytes = this.stringToBytes64(title);
    const adminBytes = this.stringToBytes32(adminKey);

    await this.deployedContract.callTx.createProposal(
      titleBytes,
      BigInt(options),
      BigInt(deadline),
      adminBytes
    );

    this.logger.info('Proposal created');
  }

  // End voting
  async endVoting(adminKey: string): Promise<void> {
    this.logger.info('Ending voting period');

    const adminBytes = this.stringToBytes32(adminKey);
    await this.deployedContract.callTx.endVoting(adminBytes);

    this.logger.info('Voting ended');
  }

  // Helper: Convert string to Bytes<64>
  private stringToBytes64(str: string): Uint8Array {
    const bytes = new Uint8Array(64);
    const encoder = new TextEncoder();
    const encoded = encoder.encode(str.slice(0, 64));
    bytes.set(encoded);
    return bytes;
  }

  // Helper: Convert string to Bytes<32>
  private stringToBytes32(str: string): Uint8Array {
    const bytes = new Uint8Array(32);
    const encoder = new TextEncoder();
    const encoded = encoder.encode(str.slice(0, 32));
    bytes.set(encoded);
    return bytes;
  }
}

Frontend Integration with React

Voting Page Component

Create frontend-vite-react/src/pages/vote/index.tsx:

import { useState, useEffect } from 'react';
import { Button } from '@/components/ui/button';
import {
  Card,
  CardContent,
  CardDescription,
  CardHeader,
  CardTitle,
} from '@/components/ui/card';
import { Progress } from '@/components/ui/progress';
import { Badge } from '@/components/ui/badge';
import { useVotingContract } from '@/modules/midnight/voting-sdk/hooks/use-voting-contract';
import { useWallet } from '@/modules/midnight/wallet-widget/hooks/useWallet';

// Proposal option type
type VoteOption = {
  id: number;
  label: string;
  votes: bigint;
  percentage: number;
};

// Proposal state labels
const stateLabels: Record<number, string> = {
  0: 'Not Created',
  1: 'Voting Active',
  2: 'Voting Ended',
};

// State badge colors
const stateBadgeVariant: Record<number, 'default' | 'secondary' | 'destructive'> = {
  0: 'secondary',
  1: 'default',
  2: 'destructive',
};

export const VotingPage = () => {
  // Contract state
  const {
    deployedContractAPI,
    derivedState,
    isLoading,
    error,
  } = useVotingContract();

  // Wallet state
  const { status } = useWallet();

  // Local state
  const [selectedOption, setSelectedOption] = useState<number | null>(null);
  const [isVoting, setIsVoting] = useState(false);
  const [hasVoted, setHasVoted] = useState(false);

  // Calculate vote options with percentages
  const calculateOptions = (): VoteOption[] => {
    if (!derivedState) return [];

    const { votes, optionCount, totalVotes } = derivedState;
    const total = Number(totalVotes) || 1;

    const options: VoteOption[] = [];
    const voteValues = [votes.option1, votes.option2, votes.option3, votes.option4];
    const labels = ['Option A', 'Option B', 'Option C', 'Option D'];

    for (let i = 0; i < optionCount; i++) {
      options.push({
        id: i + 1,
        label: labels[i],
        votes: voteValues[i],
        percentage: (Number(voteValues[i]) / total) * 100,
      });
    }

    return options;
  };

  const options = calculateOptions();

  // Handle vote submission
  const handleVote = async () => {
    if (!selectedOption || !deployedContractAPI) return;

    try {
      setIsVoting(true);
      await deployedContractAPI.vote(selectedOption);
      setHasVoted(true);
      setSelectedOption(null);
    } catch (err) {
      console.error('Vote failed:', err);
    } finally {
      setIsVoting(false);
    }
  };

  // Render voting interface
  const renderVotingInterface = () => {
    if (!derivedState) {
      return (
        <div className="text-center py-8">
          <p className="text-muted-foreground">Loading proposal...</p>
        </div>
      );
    }

    const { proposalState } = derivedState;

    // Proposal not created
    if (proposalState === 0) {
      return (
        <div className="text-center py-8">
          <p className="text-xl mb-4">No Active Proposal</p>
          <p className="text-muted-foreground">
            Wait for an admin to create a proposal.
          </p>
        </div>
      );
    }

    // Voting ended - show results
    if (proposalState === 2) {
      return (
        <div className="space-y-6">
          <h3 className="text-xl font-semibold text-center">Final Results</h3>
          {options.map((option) => (
            <div key={option.id} className="space-y-2">
              <div className="flex justify-between">
                <span className="font-medium">{option.label}</span>
                <span className="text-muted-foreground">
                  {option.votes.toString()} votes ({option.percentage.toFixed(1)}%)
                </span>
              </div>
              <Progress value={option.percentage} className="h-3" />
            </div>
          ))}
          <div className="text-center pt-4 border-t">
            <p className="text-lg font-semibold">
              Total Votes: {derivedState.totalVotes.toString()}
            </p>
          </div>
        </div>
      );
    }

    // Voting active
    return (
      <div className="space-y-6">
        {hasVoted ? (
          <div className="text-center py-8">
            <div className="text-4xl mb-4">✓</div>
            <h3 className="text-xl font-semibold text-green-600">
              Vote Submitted!
            </h3>
            <p className="text-muted-foreground mt-2">
              Your vote has been recorded anonymously.
            </p>
          </div>
        ) : (
          <>
            <h3 className="text-lg font-medium text-center">
              Select your choice:
            </h3>
            <div className="grid gap-3">
              {options.map((option) => (
                <Button
                  key={option.id}
                  variant={selectedOption === option.id ? 'default' : 'outline'}
                  className="h-16 text-lg justify-start px-6"
                  onClick={() => setSelectedOption(option.id)}
                  disabled={isVoting}
                >
                  <span className="w-8 h-8 rounded-full bg-primary/10 flex items-center justify-center mr-4">
                    {option.id}
                  </span>
                  {option.label}
                </Button>
              ))}
            </div>
            <Button
              className="w-full h-12 text-lg"
              disabled={!selectedOption || isVoting}
              onClick={handleVote}
            >
              {isVoting ? 'Submitting Vote...' : 'Cast Anonymous Vote'}
            </Button>
          </>
        )}

        {/* Live vote count (visible during voting) */}
        <div className="pt-4 border-t">
          <p className="text-center text-muted-foreground">
            Current participation: {derivedState.totalVotes.toString()} votes
          </p>
        </div>
      </div>
    );
  };

  return (
    <div className="min-h-screen bg-background py-12 px-4">
      <div className="max-w-2xl mx-auto">
        <Card>
          <CardHeader className="text-center">
            <div className="flex justify-center mb-2">
              <Badge variant={stateBadgeVariant[derivedState?.proposalState ?? 0]}>
                {stateLabels[derivedState?.proposalState ?? 0]}
              </Badge>
            </div>
            <CardTitle className="text-3xl">
              Community Proposal Vote
            </CardTitle>
            <CardDescription>
              Privacy-preserving voting powered by Midnight
            </CardDescription>
          </CardHeader>
          <CardContent>
            {status?.status !== 'connected' ? (
              <div className="text-center py-8">
                <p className="text-muted-foreground mb-4">
                  Connect your wallet to participate
                </p>
              </div>
            ) : (
              renderVotingInterface()
            )}
          </CardContent>
        </Card>

        {/* Privacy notice */}
        <div className="mt-6 text-center text-sm text-muted-foreground">
          <p>Your vote is anonymous and verified using zero-knowledge proofs.</p>
          <p>No one can see how you voted, but the total count is verifiable.</p>
        </div>
      </div>
    </div>
  );
};

export default VotingPage;

Admin Panel Component

Create frontend-vite-react/src/pages/admin/index.tsx:

import { useState } from 'react';
import { Button } from '@/components/ui/button';
import {
  Card,
  CardContent,
  CardDescription,
  CardHeader,
  CardTitle,
} from '@/components/ui/card';
import { Input } from '@/components/ui/input';
import { Label } from '@/components/ui/label';
import { useVotingContract } from '@/modules/midnight/voting-sdk/hooks/use-voting-contract';

export const AdminPage = () => {
  const { deployedContractAPI, derivedState, onDeploy } = useVotingContract();

  // Form state
  const [proposalTitle, setProposalTitle] = useState('');
  const [optionCount, setOptionCount] = useState(2);
  const [adminKey, setAdminKey] = useState('');
  const [isCreating, setIsCreating] = useState(false);
  const [isEnding, setIsEnding] = useState(false);

  // Deploy new contract
  const handleDeploy = async () => {
    try {
      setIsCreating(true);
      await onDeploy();
    } catch (err) {
      console.error('Deploy failed:', err);
    } finally {
      setIsCreating(false);
    }
  };

  // Create proposal
  const handleCreateProposal = async () => {
    if (!deployedContractAPI || !proposalTitle || !adminKey) return;

    try {
      setIsCreating(true);
      const deadline = Math.floor(Date.now() / 1000) + 86400; // 24 hours
      await deployedContractAPI.createProposal(
        proposalTitle,
        optionCount,
        deadline,
        adminKey
      );
    } catch (err) {
      console.error('Create proposal failed:', err);
    } finally {
      setIsCreating(false);
    }
  };

  // End voting
  const handleEndVoting = async () => {
    if (!deployedContractAPI || !adminKey) return;

    try {
      setIsEnding(true);
      await deployedContractAPI.endVoting(adminKey);
    } catch (err) {
      console.error('End voting failed:', err);
    } finally {
      setIsEnding(false);
    }
  };

  return (
    <div className="min-h-screen bg-background py-12 px-4">
      <div className="max-w-2xl mx-auto space-y-6">
        <Card>
          <CardHeader>
            <CardTitle>Voting Admin Panel</CardTitle>
            <CardDescription>
              Create and manage voting proposals
            </CardDescription>
          </CardHeader>
          <CardContent className="space-y-6">
            {/* Deploy Section */}
            {!deployedContractAPI && (
              <div className="space-y-4">
                <h3 className="font-semibold">Step 1: Deploy Contract</h3>
                <Button onClick={handleDeploy} disabled={isCreating}>
                  {isCreating ? 'Deploying...' : 'Deploy Voting Contract'}
                </Button>
              </div>
            )}

            {/* Create Proposal Section */}
            {deployedContractAPI && derivedState?.proposalState === 0 && (
              <div className="space-y-4">
                <h3 className="font-semibold">Create New Proposal</h3>

                <div className="space-y-2">
                  <Label htmlFor="title">Proposal Title</Label>
                  <Input
                    id="title"
                    value={proposalTitle}
                    onChange={(e) => setProposalTitle(e.target.value)}
                    placeholder="What should we decide?"
                  />
                </div>

                <div className="space-y-2">
                  <Label htmlFor="options">Number of Options</Label>
                  <Input
                    id="options"
                    type="number"
                    min={2}
                    max={4}
                    value={optionCount}
                    onChange={(e) => setOptionCount(Number(e.target.value))}
                  />
                </div>

                <div className="space-y-2">
                  <Label htmlFor="adminKey">Admin Key</Label>
                  <Input
                    id="adminKey"
                    type="password"
                    value={adminKey}
                    onChange={(e) => setAdminKey(e.target.value)}
                    placeholder="Secret admin key"
                  />
                </div>

                <Button
                  onClick={handleCreateProposal}
                  disabled={isCreating || !proposalTitle || !adminKey}
                  className="w-full"
                >
                  {isCreating ? 'Creating...' : 'Create Proposal'}
                </Button>
              </div>
            )}

            {/* Active Voting Controls */}
            {deployedContractAPI && derivedState?.proposalState === 1 && (
              <div className="space-y-4">
                <h3 className="font-semibold">Voting In Progress</h3>
                <p className="text-muted-foreground">
                  Total votes: {derivedState.totalVotes.toString()}
                </p>

                <div className="space-y-2">
                  <Label htmlFor="endAdminKey">Admin Key</Label>
                  <Input
                    id="endAdminKey"
                    type="password"
                    value={adminKey}
                    onChange={(e) => setAdminKey(e.target.value)}
                    placeholder="Enter admin key to end voting"
                  />
                </div>

                <Button
                  variant="destructive"
                  onClick={handleEndVoting}
                  disabled={isEnding || !adminKey}
                  className="w-full"
                >
                  {isEnding ? 'Ending...' : 'End Voting Period'}
                </Button>
              </div>
            )}

            {/* Results */}
            {derivedState?.proposalState === 2 && (
              <div className="text-center py-4">
                <p className="text-lg font-semibold text-green-600">
                  Voting Complete
                </p>
                <p className="text-muted-foreground">
                  Results are now final and publicly verifiable.
                </p>
              </div>
            )}
          </CardContent>
        </Card>
      </div>
    </div>
  );
};

export default AdminPage;

Results Visualization Component

Create frontend-vite-react/src/components/ResultsChart.tsx:

import { useMemo } from 'react';

type VoteResult = {
  label: string;
  votes: bigint;
  color: string;
};

type ResultsChartProps = {
  results: VoteResult[];
  totalVotes: bigint;
};

export const ResultsChart = ({ results, totalVotes }: ResultsChartProps) => {
  const total = Number(totalVotes) || 1;

  // Calculate percentages and find winner
  const processedResults = useMemo(() => {
    const processed = results.map((result) => ({
      ...result,
      percentage: (Number(result.votes) / total) * 100,
    }));

    // Sort by votes descending
    return processed.sort((a, b) => Number(b.votes - a.votes));
  }, [results, total]);

  const winner = processedResults[0];

  return (
    <div className="space-y-6">
      {/* Winner announcement */}
      <div className="text-center p-6 bg-primary/5 rounded-lg">
        <p className="text-sm text-muted-foreground mb-1">Winner</p>
        <p className="text-2xl font-bold" style={{ color: winner?.color }}>
          {winner?.label}
        </p>
        <p className="text-lg">
          {winner?.percentage.toFixed(1)}% ({winner?.votes.toString()} votes)
        </p>
      </div>

      {/* Bar chart */}
      <div className="space-y-4">
        {processedResults.map((result, index) => (
          <div key={index} className="space-y-1">
            <div className="flex justify-between text-sm">
              <span className="font-medium">{result.label}</span>
              <span className="text-muted-foreground">
                {result.votes.toString()} ({result.percentage.toFixed(1)}%)
              </span>
            </div>
            <div className="h-8 bg-secondary rounded-full overflow-hidden">
              <div
                className="h-full rounded-full transition-all duration-500"
                style={{
                  width: `${result.percentage}%`,
                  backgroundColor: result.color,
                }}
              />
            </div>
          </div>
        ))}
      </div>

      {/* Total */}
      <div className="text-center pt-4 border-t">
        <p className="text-2xl font-bold">{totalVotes.toString()}</p>
        <p className="text-sm text-muted-foreground">Total Votes Cast</p>
      </div>
    </div>
  );
};

Testing Your Voting Contract

Unit Tests

Create voting-contract/src/test/voting.test.ts:

import { describe, it, expect, beforeEach } from 'vitest';
import { VotingSimulator } from './simulators/voting-simulator';

describe('Voting Smart Contract', () => {
  let simulator: VotingSimulator;

  beforeEach(() => {
    simulator = VotingSimulator.deployContract();
  });

  describe('Proposal Creation', () => {
    it('should create a proposal successfully', () => {
      const admin = 'admin-secret-key';

      simulator.as('admin').createProposal(
        'Test Proposal',
        3, // 3 options
        Date.now() + 86400000, // 24 hours
        admin
      );

      const state = simulator.getLedger();
      expect(state.proposalState).toEqual(1n);
      expect(state.optionCount).toEqual(3n);
    });

    it('should reject proposal with less than 2 options', () => {
      expect(() => {
        simulator.as('admin').createProposal('Bad Proposal', 1, Date.now(), 'key');
      }).toThrow('Need at least 2 options');
    });

    it('should reject proposal with more than 4 options', () => {
      expect(() => {
        simulator.as('admin').createProposal('Bad Proposal', 5, Date.now(), 'key');
      }).toThrow('Maximum 4 options');
    });
  });

  describe('Voting', () => {
    beforeEach(() => {
      simulator.as('admin').createProposal(
        'Test Vote',
        3,
        Date.now() + 86400000,
        'admin-key'
      );
    });

    it('should allow voting for valid options', () => {
      simulator.as('voter1').castVote(1);
      simulator.as('voter2').castVote(2);
      simulator.as('voter3').castVote(1);

      const state = simulator.getLedger();
      expect(state.votesOption1).toEqual(2n);
      expect(state.votesOption2).toEqual(1n);
      expect(state.totalVoters).toEqual(3n);
    });

    it('should reject vote for option 0', () => {
      expect(() => {
        simulator.as('voter1').castVote(0);
      }).toThrow('Invalid option: too low');
    });

    it('should reject vote for option beyond count', () => {
      expect(() => {
        simulator.as('voter1').castVote(4); // Only 3 options
      }).toThrow('Invalid option: too high');
    });

    it('should reject vote when voting not active', () => {
      simulator.as('admin').endVoting('admin-key');

      expect(() => {
        simulator.as('voter1').castVote(1);
      }).toThrow('Voting not active');
    });
  });

  describe('Ending Voting', () => {
    beforeEach(() => {
      simulator.as('admin').createProposal(
        'Test Vote',
        2,
        Date.now() + 86400000,
        'admin-key'
      );
    });

    it('should allow admin to end voting', () => {
      simulator.as('admin').endVoting('admin-key');

      const state = simulator.getLedger();
      expect(state.proposalState).toEqual(2n);
    });

    it('should reject non-admin ending voting', () => {
      expect(() => {
        simulator.as('attacker').endVoting('wrong-key');
      }).toThrow('Not authorized');
    });
  });

  describe('Multi-voter scenarios', () => {
    beforeEach(() => {
      simulator.as('admin').createProposal(
        'Community Decision',
        4,
        Date.now() + 86400000,
        'admin-key'
      );
    });

    it('should correctly tally votes from multiple voters', () => {
      // Simulate 10 voters
      for (let i = 0; i < 10; i++) {
        const option = (i % 4) + 1; // Distribute across options
        simulator.as(`voter${i}`).castVote(option);
      }

      const state = simulator.getLedger();
      expect(state.totalVoters).toEqual(10n);

      // Options 1-4 should each have some votes
      const totalVotes =
        Number(state.votesOption1) +
        Number(state.votesOption2) +
        Number(state.votesOption3) +
        Number(state.votesOption4);
      expect(totalVotes).toEqual(10);
    });

    it('should handle unanimous voting', () => {
      for (let i = 0; i < 5; i++) {
        simulator.as(`voter${i}`).castVote(2); // Everyone votes option 2
      }

      const state = simulator.getLedger();
      expect(state.votesOption1).toEqual(0n);
      expect(state.votesOption2).toEqual(5n);
      expect(state.votesOption3).toEqual(0n);
      expect(state.votesOption4).toEqual(0n);
    });
  });
});

Simulator Implementation

Create voting-contract/src/test/simulators/voting-simulator.ts:

import {
  Contract as VotingContract,
} from '../../managed/voting/contract/index.cjs';
import {
  createPrivateState,
  type VotingPrivateState,
} from '../../witnesses';

type LedgerState = {
  proposalState: bigint;
  optionCount: bigint;
  votesOption1: bigint;
  votesOption2: bigint;
  votesOption3: bigint;
  votesOption4: bigint;
  totalVoters: bigint;
};

export class VotingSimulator {
  private ledgerState: LedgerState;
  private privateStates: Map<string, VotingPrivateState>;
  private currentUser: string;

  private constructor() {
    this.ledgerState = {
      proposalState: 0n,
      optionCount: 0n,
      votesOption1: 0n,
      votesOption2: 0n,
      votesOption3: 0n,
      votesOption4: 0n,
      totalVoters: 0n,
    };
    this.privateStates = new Map();
    this.currentUser = 'default';
  }

  static deployContract(): VotingSimulator {
    return new VotingSimulator();
  }

  as(user: string): this {
    this.currentUser = user;
    if (!this.privateStates.has(user)) {
      this.privateStates.set(user, createPrivateState());
    }
    return this;
  }

  getLedger(): LedgerState {
    return { ...this.ledgerState };
  }

  getPrivateState(): VotingPrivateState {
    return this.privateStates.get(this.currentUser) || createPrivateState();
  }

  createProposal(
    title: string,
    options: number,
    deadline: number,
    adminKey: string
  ): void {
    if (this.ledgerState.proposalState !== 0n) {
      throw new Error('Proposal already exists');
    }
    if (options < 2) {
      throw new Error('Need at least 2 options');
    }
    if (options > 4) {
      throw new Error('Maximum 4 options');
    }

    this.ledgerState.proposalState = 1n;
    this.ledgerState.optionCount = BigInt(options);
  }

  castVote(option: number): void {
    if (this.ledgerState.proposalState !== 1n) {
      throw new Error('Voting not active');
    }
    if (option < 1) {
      throw new Error('Invalid option: too low');
    }
    if (option > Number(this.ledgerState.optionCount)) {
      throw new Error('Invalid option: too high');
    }

    // Increment appropriate counter
    switch (option) {
      case 1:
        this.ledgerState.votesOption1++;
        break;
      case 2:
        this.ledgerState.votesOption2++;
        break;
      case 3:
        this.ledgerState.votesOption3++;
        break;
      case 4:
        this.ledgerState.votesOption4++;
        break;
    }

    this.ledgerState.totalVoters++;

    // Update private state
    const privateState = this.privateStates.get(this.currentUser);
    if (privateState) {
      privateState.hasVoted = true;
      privateState.pendingVote = option;
    }
  }

  endVoting(adminKey: string): void {
    if (this.ledgerState.proposalState !== 1n) {
      throw new Error('Voting not active');
    }
    // In a real implementation, verify admin key
    if (adminKey !== 'admin-key') {
      throw new Error('Not authorized');
    }

    this.ledgerState.proposalState = 2n;
  }
}

Running Tests

# Run voting contract tests
cd voting-contract
npm run test

# Run with coverage
npm run test -- --coverage

# Run specific test file
npm run test -- voting.test.ts

Deployment Guide

Local Development

# Terminal 1: Start local Midnight node
npm run setup-standalone

# Terminal 2: Start frontend
npm run dev:frontend

Preview Network Deployment

Configure Environment

# voting-cli/.env
MY_PREVIEW_MNEMONIC="your wallet mnemonic phrase"

Fund Your Wallet
- Visit Midnight Faucet
- Request tSTAR tokens
Deploy Contract

cd voting-cli
npm run deploy

Configure Frontend

# frontend-vite-react/.env
VITE_CONTRACT_ADDRESS="deployed_contract_address_here"

Start Application

npm run dev:frontend

Deployment Checklist

[ ] Compact compiler installed (v0.27.0)
[ ] Contract compiles without errors
[ ] All tests passing
[ ] Wallet funded with tSTAR
[ ] Environment variables configured
[ ] Contract deployed successfully
[ ] Frontend connected to contract

Advanced Voting Patterns

Pattern 1: Weighted Voting

For token-weighted governance:

pragma language_version >= 0.19;

import CompactStandardLibrary;

// Weighted voting based on token holdings
export ledger weightedVotesOption1: Counter;
export ledger weightedVotesOption2: Counter;

export circuit voteWithWeight(option: Uint<8>, weight: Uint<64>): [] {
  assert(proposalState == 1, "Voting not active");
  assert(weight > 0, "No voting power");

  if (option == 1) {
    weightedVotesOption1.increment(weight);
  } else if (option == 2) {
    weightedVotesOption2.increment(weight);
  }
}

Pattern 2: Quadratic Voting

Reduce plutocracy with quadratic costs:

pragma language_version >= 0.19;

import CompactStandardLibrary;

// Quadratic voting: cost = votes^2
export ledger creditsSpent: Map<Bytes<32>, Counter>;

export pure function calculateCost(votes: Uint<64>): Uint<64> {
  return votes * votes; // Quadratic cost
}

export circuit quadraticVote(
  option: Uint<8>,
  numVotes: Uint<64>,
  voterKey: Bytes<32>
): [] {
  let cost: Uint<64> = calculateCost(numVotes);
  // Verify voter has enough credits
  // Deduct credits and record votes
}

Pattern 3: Delegated Voting

Allow vote delegation:

pragma language_version >= 0.19;

import CompactStandardLibrary;

// Delegation mapping
export ledger delegates: Map<Bytes<32>, Bytes<32>>;
export ledger delegatedPower: Map<Bytes<32>, Counter>;

export circuit delegateVote(
  fromVoter: Bytes<32>,
  toDelegate: Bytes<32>
): [] {
  // Record delegation
  delegates[fromVoter] = toDelegate;
  delegatedPower[toDelegate].increment(1);
}

export circuit voteAsDelegate(
  delegate: Bytes<32>,
  option: Uint<8>
): [] {
  // Vote with accumulated power
  // let power = delegatedPower[delegate];
  // Apply votes
}

Pattern 4: Multi-Round Voting

Implement runoff elections:

pragma language_version >= 0.19;

import CompactStandardLibrary;

export ledger currentRound: Uint<8>;
export ledger eliminatedOptions: Map<Uint<8>, Boolean>;

export circuit advanceRound(): [] {
  // Find option with lowest votes
  // Mark as eliminated
  // Increment round
  currentRound = currentRound + 1;
}

export circuit voteInRound(option: Uint<8>): [] {
  // Verify option not eliminated
  assert(eliminatedOptions[option] == false, "Option eliminated");
  // Record vote
}

Pattern 5: Time-Locked Results

Hide results until voting ends:

// Client-side: Encrypt votes with time-lock
const encryptVote = async (vote: number, unlockTime: number) => {
  // Use threshold encryption or timelock puzzles
  // Results only decryptable after deadline
  return encryptedVote;
};

// Contract stores encrypted votes
// Reveal phase decrypts and tallies

Troubleshooting & Best Practices

Common Issues

1. "Proposal already exists" Error

Error: Proposal already exists

Solution: Call resetProposal() with admin key before creating a new proposal.

2. Vote Not Recording

Symptoms: Vote transaction succeeds but count doesn't change.

Solutions:

Verify voting is active (proposalState == 1)
Check option is within valid range
Ensure contract address is correct

3. Admin Key Mismatch

Error: Not authorized

Solution: Use the exact same admin key used during proposal creation.

4. State Not Updating in UI

Solution: Ensure observable subscription is active:

useEffect(() => {
  const subscription = votingContract.state$.subscribe((state) => {
    setDerivedState(state);
  });
  return () => subscription.unsubscribe();
}, [votingContract]);

Best Practices

1. Validate Inputs Early

export circuit castVote(option: Uint<8>): [] {
  // Validate FIRST, before any state changes
  assert(proposalState == 1, "Voting not active");
  assert(option >= 1, "Invalid option");
  assert(option <= optionCount, "Invalid option");

  // Then modify state
  // ...
}

2. Use Clear State Transitions

// Clear state machine
// 0 -> 1: createProposal
// 1 -> 2: endVoting
// 2 -> 0: resetProposal

export circuit createProposal(...): [] {
  assert(proposalState == 0, "Wrong state");
  // ...
  proposalState = 1;
}

3. Handle Errors Gracefully

const handleVote = async (option: number) => {
  try {
    setLoading(true);
    setError(null);
    await contract.vote(option);
    setSuccess(true);
  } catch (err) {
    if (err.message.includes('Voting not active')) {
      setError('Voting period has ended.');
    } else if (err.message.includes('Invalid option')) {
      setError('Please select a valid option.');
    } else {
      setError('Vote failed. Please try again.');
    }
    console.error('Vote error:', err);
  } finally {
    setLoading(false);
  }
};

4. Test Edge Cases

describe('Edge cases', () => {
  it('handles maximum number of voters', async () => {
    // Test with 1000+ voters
  });

  it('handles tie votes', async () => {
    // Equal votes for multiple options
  });

  it('handles zero votes', async () => {
    // End voting with no participation
  });
});

Next Steps & Resources

Learning Path

Beginner: Complete this tutorial with the basic voting contract
Intermediate: Add weighted voting and delegation
Advanced: Implement quadratic voting with Merkle proofs

Extend Your Voting System

Feature	Difficulty	Description
Voter Registration	Medium	Merkle tree eligibility proofs
Delegation	Medium	Allow vote power transfer
Quadratic Voting	Hard	Token-weighted with diminishing returns
Anonymous Results	Hard	Reveal results only after deadline
Multi-Sig Admin	Medium	Require multiple admins to end voting

Official Resources

Midnight Documentation: docs.midnight.network
Compact Language Guide: docs.midnight.network/compact
Lace Wallet: lace.io
Faucet: faucet.preview.midnight.network

Community

Discord: Join the Midnight developer community
GitHub: Contribute to open-source tools
Forum: Ask questions and share projects

Related Projects

MeshJS/midnight-starter-template: GitHub
Mesh SDK: meshjs.dev
Edda Labs: eddalabs.io

Quick Reference Card

Compact Cheat Sheet

// Pragma
pragma language_version >= 0.19;

// Imports
import CompactStandardLibrary;

// Public state
export ledger voteCount: Counter;
export ledger proposalState: Uint<8>;
export ledger adminKey: Bytes<32>;

// State-changing circuits
export circuit vote(option: Uint<8>): [] {
  assert(proposalState == 1, "Not active");
  voteCount.increment(1);
}

// Pure functions (no state change)
export pure function isValidOption(opt: Uint<8>, max: Uint<8>): Boolean {
  return opt >= 1 && opt <= max;
}

// Assertions
assert(condition, "Error message");

npm Scripts

npm install              # Install dependencies
npm run build            # Compile contracts
npm run dev:frontend     # Start dev server
npm run test             # Run tests
npm run setup-standalone # Local network
npm run build-production # Production build

Key Files

File	Purpose
`voting-contract/src/voting.compact`	Voting logic
`voting-contract/src/witnesses.ts`	Private state
`frontend/src/modules/midnight/voting-sdk/`	SDK
`voting-cli/.env`	CLI config
`frontend/.env`	Frontend config

Conclusion

You now have a complete foundation for building privacy-preserving voting systems on Midnight. The combination of:

Zero-knowledge proofs for voter privacy
Public ledger for verifiable results
Compact language for secure logic
React frontend for user interaction

...enables entirely new categories of democratic applications where votes remain private but results are transparent and verifiable.

Privacy-preserving voting is one of the most impactful applications of zero-knowledge technology. Whether for DAOs, corporate governance, or community decisions, Midnight provides the tools to build fair, anonymous, and verifiable voting systems.

Happy building!

Built with the Midnight Starter Template

Mesh x Edda Labs

Building Your First Game on Midnight: A Complete Developer Tutorial

UtkarshVarma — Fri, 09 Jan 2026 16:20:05 +0000

A comprehensive guide to building privacy-preserving blockchain games using Midnight Network and this starter template

Introduction to Midnight
Why Build Games on Midnight?
Understanding the Architecture
Prerequisites & Setup
Project Structure Deep Dive
Writing Smart Contracts in Compact
Building a Simple Game: Rock-Paper-Scissors
Frontend Integration with React
Testing Your Contracts
Deployment Guide
Advanced Patterns
Troubleshooting & Best Practices
Next Steps & Resources

Introduction to Midnight

What is Midnight?

Midnight is a privacy-first blockchain platform that enables developers to build decentralized applications (dApps) with built-in data protection. Unlike traditional blockchains where all transactions are publicly visible, Midnight uses zero-knowledge proofs (ZK proofs) to allow users to prove the validity of their actions without revealing sensitive information.

Key Features

Privacy by Default: All contract state can be kept private using ZK proofs
Shielded & Unshielded Assets: Support for both private and public funds
Compact Language: A purpose-built smart contract language optimized for privacy
Full-Stack dApp Support: Complete SDK for frontend integration
Testnet Ready: Preview network available for development and testing

The Privacy Advantage for Games

Imagine building a poker game where:

Players can prove they have valid cards without revealing them
Bet amounts can be hidden until the reveal phase
Game state remains private until the appropriate time

This is the power of Midnight for game development.

Why Build Games on Midnight?

Traditional Blockchain Gaming Problems

Transparent State: On Ethereum, all contract state is visible. In a card game, this means everyone can see your hand.
Front-Running: Miners/validators can see pending transactions and exploit them.
Privacy Concerns: Players' strategies and holdings are public knowledge.

Midnight's Solutions

Problem	Midnight Solution
Visible game state	Private state with ZK proofs
Front-running attacks	Encrypted transactions
Strategy exposure	Shielded computations
Unfair advantages	Verifiable random numbers

Perfect Use Cases

Card Games: Poker, Blackjack, Trading Card Games
Strategy Games: Hidden unit movements, fog of war
Betting/Prediction Markets: Private bets with public outcomes
Turn-Based Games: Hidden moves revealed after both players commit
NFT Games: Private ownership verification

Understanding the Architecture

The Midnight Stack

+--------------------------------------------------+
|                   Frontend (React)               |
|    - Wallet Integration (Lace)                   |
|    - Contract Interaction                        |
|    - State Subscriptions                         |
+--------------------------------------------------+
                        |
                        v
+--------------------------------------------------+
|              Midnight JS SDK                      |
|    - Contract Deployment                         |
|    - Transaction Building                        |
|    - Proof Generation                            |
+--------------------------------------------------+
                        |
                        v
+--------------------------------------------------+
|              Midnight Network                     |
|    +----------------+  +---------------------+   |
|    | Public Ledger  |  | Private State Store |   |
|    | (Visible)      |  | (Encrypted)         |   |
|    +----------------+  +---------------------+   |
+--------------------------------------------------+

Key Components Explained

1. Smart Contracts (Compact Language)

Written in Compact, a domain-specific language for privacy-preserving smart contracts. Compact compiles to WebAssembly and generates ZK circuits.

2. Public Ledger

The blockchain state visible to all participants. Used for:

Contract addresses
Public game outcomes
Scores and rankings

3. Private State

Encrypted state only accessible to its owner. Used for:

Player hands
Hidden moves
Secret strategies

4. Proof Server

Generates zero-knowledge proofs that verify transactions without revealing private data.

5. Indexer

Queries blockchain state efficiently for frontend applications.

Prerequisites & Setup

Required Tools

# Check if you have the prerequisites
node -v   # Required: v23+
npm -v    # Required: v11+
docker -v # Required: Latest

Step 1: Install Git LFS

Git LFS handles large binary files in the repository.

# macOS
brew install git-lfs

# Ubuntu/Debian
sudo apt-get install git-lfs

# Fedora/RHEL
sudo dnf install git-lfs

# Initialize Git LFS
git lfs install

Step 2: Install Compact Compiler

Compact is Midnight's smart contract language.

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

# Install compiler version 0.27.0
compact update +0.27.0

# Verify installation
compact check

Step 3: Install Lace Wallet

The Lace wallet browser extension is required for interacting with Midnight.

Install from Chrome Web Store
Create a new wallet or import existing
Switch to Midnight Preview Network
Get test tokens from Faucet

Step 4: Clone and Setup the Starter Template

# Clone the repository
git clone https://github.com/MeshJS/midnight-starter-template.git
cd midnight-starter-template

# Install dependencies
npm install

# Build the project (compiles contracts)
npm run build

Step 5: Configure Environment Variables

# Create environment files from templates
cp counter-cli/.env_template counter-cli/.env
cp frontend-vite-react/.env_template frontend-vite-react/.env

Edit the files with your configuration:

counter-cli/.env

MY_PREVIEW_MNEMONIC="your twelve word mnemonic phrase here"
MY_UNDEPLOYED_UNSHIELDED_ADDRESS=''

frontend-vite-react/.env

VITE_CONTRACT_ADDRESS=""

Project Structure Deep Dive

Directory Layout

midnight-starter-template/
├── counter-contract/           # Smart contract code
│   ├── src/
│   │   ├── counter.compact     # Main contract logic
│   │   ├── witnesses.ts        # Private state types
│   │   ├── managed/            # Compiled artifacts (generated)
│   │   └── test/               # Contract tests
│   └── package.json
│
├── counter-cli/                # CLI deployment tools
│   ├── src/
│   │   ├── config.ts           # Network configurations
│   │   └── test/               # Integration tests
│   └── package.json
│
├── frontend-vite-react/        # React frontend
│   ├── src/
│   │   ├── pages/              # Page components
│   │   ├── components/         # UI components
│   │   └── modules/midnight/   # Midnight SDK integration
│   │       ├── wallet-widget/  # Wallet connection
│   │       └── counter-sdk/    # Contract interaction
│   └── package.json
│
├── package.json                # Root workspace config
└── turbo.json                  # Build orchestration

Understanding Each Component

counter-contract/

Contains the smart contract written in Compact. This is where your game logic lives.

counter-cli/

Command-line tools for deploying and testing contracts without a frontend.

frontend-vite-react/

A complete React application with:

Wallet integration
Contract deployment UI
Real-time state updates

Writing Smart Contracts in Compact

The Compact Language

Compact is designed specifically for privacy-preserving smart contracts. Let's understand its key concepts:

Basic Contract Structure

Here's the counter contract from the starter template:

pragma language_version >= 0.19;

import CompactStandardLibrary;

// Public state - visible to everyone
export ledger round: Counter;

// Circuit function - modifies state with ZK proof
export circuit increment(): [] {
  round.increment(1);
}

Key Concepts

1. Ledger (Public State)

export ledger round: Counter;

ledger declares public blockchain state
Counter is a built-in type for counting
Everyone can see this value

2. Circuits

export circuit increment(): [] {
  round.increment(1);
}

circuit defines a function that modifies state
Generates a ZK proof when called
[] indicates no return value

3. Private State (Witnesses)

Private state is defined in TypeScript alongside the contract:

// witnesses.ts
export type CounterPrivateState = {
  privateCounter: number;
};

export const createPrivateState = (value: number): CounterPrivateState => {
  return {
    privateCounter: value,
  };
};

export const witnesses = {};

Data Types in Compact

Type	Description	Example
`Counter`	Incrementable integer	`ledger score: Counter;`
`Uint<N>`	Unsigned integer (N bits)	`Uint<64>`
`Boolean`	True/False	`Boolean`
`Bytes<N>`	Fixed-size bytes	`Bytes<32>`
`Vector<T, N>`	Fixed-size array	`Vector<Uint<8>, 52>`
`Map<K, V>`	Key-value mapping	`Map<Address, Counter>`

Building a Simple Game: Rock-Paper-Scissors

Now let's build a real game! We'll create a Rock-Paper-Scissors game that demonstrates Midnight's privacy features.

Game Design

+-------------------+     +-------------------+
|     Player 1      |     |     Player 2      |
+-------------------+     +-------------------+
| Private: move     |     | Private: move     |
| (rock/paper/      |     | (rock/paper/      |
|  scissors)        |     |  scissors)        |
+-------------------+     +-------------------+
          |                        |
          v                        v
+------------------------------------------------+
|              Public Ledger                      |
| - Game state (waiting/committed/revealed)       |
| - Player addresses                              |
| - Winner (after reveal)                         |
+------------------------------------------------+

Step 1: Create the Contract

Create a new file rps-contract/src/rps.compact:

pragma language_version >= 0.19;

import CompactStandardLibrary;

// Game states
// 0 = Waiting for players
// 1 = Player 1 committed
// 2 = Both committed, waiting for reveal
// 3 = Game complete

// Public ledger state
export ledger gameState: Uint<8>;
export ledger player1Commitment: Bytes<32>;
export ledger player2Commitment: Bytes<32>;
export ledger winner: Uint<8>; // 0 = none, 1 = player1, 2 = player2, 3 = draw

// Move encoding: 1 = Rock, 2 = Paper, 3 = Scissors

// Player 1 commits their move (hashed)
export circuit commitMove1(commitment: Bytes<32>): [] {
  assert(gameState == 0, "Game already started");
  player1Commitment = commitment;
  gameState = 1;
}

// Player 2 commits their move (hashed)
export circuit commitMove2(commitment: Bytes<32>): [] {
  assert(gameState == 1, "Waiting for player 1");
  player2Commitment = commitment;
  gameState = 2;
}

// Reveal phase - players reveal moves
export circuit reveal(
  move1: Uint<8>,
  salt1: Bytes<32>,
  move2: Uint<8>,
  salt2: Bytes<32>
): [] {
  assert(gameState == 2, "Not in reveal phase");

  // Verify commitments match
  // In production, use proper hash verification

  // Determine winner
  // Rock (1) beats Scissors (3)
  // Paper (2) beats Rock (1)
  // Scissors (3) beats Paper (2)

  if (move1 == move2) {
    winner = 3; // Draw
  } else if (
    (move1 == 1 && move2 == 3) ||
    (move1 == 2 && move2 == 1) ||
    (move1 == 3 && move2 == 2)
  ) {
    winner = 1; // Player 1 wins
  } else {
    winner = 2; // Player 2 wins
  }

  gameState = 3;
}

// Reset for new game
export circuit resetGame(): [] {
  gameState = 0;
  winner = 0;
}

Step 2: Define Private State

Create rps-contract/src/witnesses.ts:

export type RPSPrivateState = {
  myMove: number;      // 1=Rock, 2=Paper, 3=Scissors
  mySalt: string;      // Random salt for commitment
  hasCommitted: boolean;
};

export const createPrivateState = (): RPSPrivateState => {
  return {
    myMove: 0,
    mySalt: '',
    hasCommitted: false,
  };
};

// Helper to generate commitment hash
export const generateCommitment = (move: number, salt: string): string => {
  // In production, use proper cryptographic hash
  return `${move}-${salt}`;
};

export const witnesses = {};

Step 3: Frontend Integration

Create a React component for the game:

// pages/rps/index.tsx
import { useState, useEffect } from 'react';
import { Button } from '@/components/ui/button';
import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';

// Move icons
const moves = {
  1: { name: 'Rock', emoji: '🪨' },
  2: { name: 'Paper', emoji: '📄' },
  3: { name: 'Scissors', emoji: '✂️' },
};

export const RockPaperScissors = () => {
  const [gameState, setGameState] = useState(0);
  const [selectedMove, setSelectedMove] = useState<number | null>(null);
  const [winner, setWinner] = useState(0);

  // Subscribe to contract state
  useEffect(() => {
    // Contract state subscription would go here
    // Similar to the counter example
  }, []);

  const commitMove = async (move: number) => {
    setSelectedMove(move);
    // Generate salt
    const salt = crypto.randomUUID();
    // Generate commitment
    const commitment = await generateCommitment(move, salt);
    // Call contract
    // await contract.commitMove1(commitment);
  };

  const renderGameState = () => {
    switch (gameState) {
      case 0:
        return (
          <div className="text-center">
            <h2 className="text-xl mb-4">Choose Your Move</h2>
            <div className="flex gap-4 justify-center">
              {Object.entries(moves).map(([key, { name, emoji }]) => (
                <Button
                  key={key}
                  onClick={() => commitMove(Number(key))}
                  className="text-4xl p-8"
                >
                  {emoji}
                  <span className="ml-2 text-sm">{name}</span>
                </Button>
              ))}
            </div>
          </div>
        );
      case 1:
        return (
          <div className="text-center">
            <h2 className="text-xl">Waiting for opponent...</h2>
            <p>Your move is committed and hidden!</p>
          </div>
        );
      case 2:
        return (
          <div className="text-center">
            <h2 className="text-xl">Both players committed!</h2>
            <Button onClick={() => revealMoves()}>
              Reveal Moves
            </Button>
          </div>
        );
      case 3:
        return (
          <div className="text-center">
            <h2 className="text-2xl mb-4">
              {winner === 1 && 'Player 1 Wins!'}
              {winner === 2 && 'Player 2 Wins!'}
              {winner === 3 && "It's a Draw!"}
            </h2>
            <Button onClick={() => resetGame()}>
              Play Again
            </Button>
          </div>
        );
    }
  };

  return (
    <div className="min-h-screen bg-background py-12 px-4">
      <div className="max-w-2xl mx-auto">
        <Card>
          <CardHeader>
            <CardTitle className="text-center text-3xl">
              Rock Paper Scissors
            </CardTitle>
            <p className="text-center text-muted-foreground">
              Privacy-preserving game on Midnight
            </p>
          </CardHeader>
          <CardContent>
            {renderGameState()}
          </CardContent>
        </Card>
      </div>
    </div>
  );
};

Frontend Integration with React

The Provider Pattern

The starter template uses a powerful provider pattern for managing blockchain state. Let's understand how it works.

Architecture Overview

<ThemeProvider>
  <MidnightMeshProvider>        {/* Wallet Connection */}
    <LocalStorageProvider>       {/* Persistence */}
      <ProvidersProvider>        {/* Blockchain Providers */}
        <DeployedProvider>       {/* Contract Instance */}
          <App />
        </DeployedProvider>
      </ProvidersProvider>
    </LocalStorageProvider>
  </MidnightMeshProvider>
</ThemeProvider>

Key Hooks

1. useWallet() - Wallet Connection

import { useWallet } from '@/modules/midnight/wallet-widget/hooks/useWallet';

const MyComponent = () => {
  const {
    status,           // Connection status
    connectWallet,    // Connect function
    disconnectWallet, // Disconnect function
    addresses,        // Wallet addresses
    balances          // Token balances
  } = useWallet();

  return (
    <div>
      {status?.status === 'connected' ? (
        <p>Connected: {addresses?.shieldedAddress}</p>
      ) : (
        <Button onClick={connectWallet}>Connect Wallet</Button>
      )}
    </div>
  );
};

2. useContractSubscription() - Real-time State

import { useContractSubscription } from '@/modules/midnight/counter-sdk/hooks/use-contract-subscription';

const GameComponent = () => {
  const {
    deployedContractAPI,  // Contract instance
    derivedState,         // Current state
    onDeploy,             // Deploy new contract
    providers             // Blockchain providers
  } = useContractSubscription();

  // State updates automatically via RxJS observables
  useEffect(() => {
    console.log('Counter value:', derivedState?.round);
  }, [derivedState]);

  const handleIncrement = async () => {
    await deployedContractAPI?.increment();
  };

  return (
    <div>
      <p>Current Count: {derivedState?.round || 0}</p>
      <Button onClick={handleIncrement}>Increment</Button>
    </div>
  );
};

Contract Controller Pattern

The ContractController class manages all contract interactions:

// api/contractController.ts
export class ContractController implements ContractControllerInterface {
  readonly deployedContractAddress: ContractAddress;
  readonly state$: Rx.Observable<DerivedState>;

  // Deploy a new contract
  static async deploy(
    providers: CounterProviders,
    logger: Logger
  ): Promise<ContractController> {
    const deployedContract = await deployContract(providers, {
      contract: counterContractInstance,
      initialPrivateState: createPrivateState(0),
    });
    return new ContractController(deployedContract, providers, logger);
  }

  // Join an existing contract
  static async join(
    contractAddress: ContractAddress,
    providers: CounterProviders,
    logger: Logger
  ): Promise<ContractController> {
    const deployedContract = await findDeployedContract(providers, {
      contractAddress,
      contract: counterContractInstance,
    });
    return new ContractController(deployedContract, providers, logger);
  }

  // Call contract function
  async increment(): Promise<void> {
    await this.deployedContract.callTx.increment();
  }
}

Observable State Management

The template uses RxJS for reactive state updates:

// State combines multiple sources
this.state$ = Rx.combineLatest([
  // Public ledger state from indexer
  providers.publicDataProvider
    .contractStateObservable(this.deployedContractAddress, { type: 'all' })
    .pipe(Rx.map((state) => Counter.ledger(state.data))),

  // Private state from local storage
  Rx.from(providers.privateStateProvider.get(privateStateId)),

  // User action status
  this.turns$,
]).pipe(
  Rx.map(([ledgerState, privateState, userActions]) => ({
    round: ledgerState.round,
    privateState,
    turns: userActions,
  }))
);

Testing Your Contracts

Unit Testing with Vitest

The template includes a testing framework for contracts:

// counter.test.ts
import { CounterSimulator } from "./simulators/simulator";
import { describe, it, expect } from "vitest";

describe("Counter smart contract", () => {
  it("displays initial values", () => {
    const simulator = CounterSimulator.deployContract(0);
    const ledgerState = simulator.as("player1").getLedger();
    const privateState = simulator.as("player1").getPrivateState();

    expect(ledgerState.round).toEqual(0n);
    expect(privateState).toEqual({ privateCounter: 0 });
  });

  it("increments the counter correctly", () => {
    const simulator = CounterSimulator.deployContract(0);

    // Call increment
    const newState = simulator.as("player1").increment();

    expect(newState.round).toEqual(1n);
  });

  it("maintains private state separately", () => {
    const simulator = CounterSimulator.deployContract(0);
    simulator.createPrivateState("player2", 100);

    // Each player has their own private state
    const p1State = simulator.as("player1").getPrivateState();
    const p2State = simulator.as("player2").getPrivateState();

    expect(p1State.privateCounter).toEqual(0);
    expect(p2State.privateCounter).toEqual(100);
  });
});

Running Tests

# Run contract tests
cd counter-contract
npm run test

# Run all tests
npm run test

Integration Testing

For full integration tests with the blockchain:

// integration.test.ts
import { deployContract } from '@midnight-ntwrk/midnight-js-contracts';

describe("Integration tests", () => {
  it("deploys and interacts with contract on testnet", async () => {
    // Setup providers
    const providers = await setupProviders();

    // Deploy contract
    const deployed = await deployContract(providers, {
      contract: counterContract,
      initialPrivateState: { privateCounter: 0 },
    });

    // Interact
    await deployed.callTx.increment();

    // Verify state
    const state = await deployed.getState();
    expect(state.round).toEqual(1n);
  });
});

Deployment Guide

Local Development (Undeployed Network)

For rapid development without connecting to the testnet:

# Terminal 1: Start local Midnight node
npm run setup-standalone

# This starts:
# - Local Midnight node (ws://127.0.0.1:9944)
# - Indexer (http://127.0.0.1:8088)
# - Proof server (http://127.0.0.1:6300)

# Terminal 2: Start frontend
npm run dev:frontend

Preview Network (Testnet)

For testing on the public testnet:

Get Test Tokens
- Visit Midnight Faucet
- Enter your wallet address
- Receive tSTAR tokens
Configure Environment

   # counter-cli/.env
   MY_PREVIEW_MNEMONIC="your wallet mnemonic phrase"

Start Frontend

   npm run dev:frontend

Production Build

# Build everything for production
npm run build-production

# Output:
# - counter-contract/dist/  - Compiled contract
# - frontend-vite-react/dist/ - Built frontend

Deployment Checklist

[ ] Contract compiled successfully
[ ] Tests passing
[ ] Environment variables configured
[ ] Wallet funded with tSTAR
[ ] Contract deployed and address saved
[ ] Frontend configured with contract address

Advanced Patterns

Pattern 1: Multi-Player Game State

// Define player structure
export ledger players: Map<Address, PlayerState>;
export ledger currentTurn: Address;
export ledger maxPlayers: Uint<8>;
export ledger playerCount: Counter;

// Join game
export circuit joinGame(): [] {
  assert(playerCount < maxPlayers, "Game full");
  // Add player logic
  playerCount.increment(1);
}

Pattern 2: Commit-Reveal Scheme

For hidden moves that are revealed later:

// Client-side commitment
const createCommitment = async (move: number, salt: string) => {
  const encoder = new TextEncoder();
  const data = encoder.encode(`${move}:${salt}`);
  const hashBuffer = await crypto.subtle.digest('SHA-256', data);
  return new Uint8Array(hashBuffer);
};

// Store commitment
await contract.commitMove(commitment);

// Later, reveal
await contract.revealMove(move, salt);

Pattern 3: Time-Locked Actions

export ledger deadline: Uint<64>;
export ledger roundStartTime: Uint<64>;

export circuit startRound(): [] {
  // Set deadline for this round
  deadline = currentTime() + 300; // 5 minutes
}

export circuit submitMove(move: Uint<8>): [] {
  assert(currentTime() < deadline, "Round ended");
  // Process move
}

Pattern 4: Random Number Generation

// Use block hash as randomness source
export circuit generateRandom(): Uint<64> {
  // Combine multiple entropy sources
  let seed = blockHash ^ transactionHash ^ timestamp;
  return seed;
}

Pattern 5: Token Staking for Games

export ledger stakes: Map<Address, Uint<64>>;
export ledger prizePool: Counter;

export circuit stake(amount: Uint<64>): [] {
  // Transfer tokens to contract
  transferToContract(amount);
  stakes[caller] = amount;
  prizePool.increment(amount);
}

export circuit claimPrize(): [] {
  assert(isWinner(caller), "Not winner");
  let prize = prizePool;
  prizePool = 0;
  transferFromContract(caller, prize);
}

Troubleshooting & Best Practices

Common Issues

1. Compact Compilation Errors

Error: Unknown type 'MyType'

Solution: Ensure all types are imported from CompactStandardLibrary or defined.

2. Proof Generation Timeout

Error: Proof server timeout

Solution:

Check proof server is running
Increase timeout in configuration
Simplify circuit logic

3. Wallet Connection Issues

Error: No Midnight provider found

Solution:

Install Lace wallet extension
Ensure wallet is on correct network
Refresh page after installing

4. State Not Updating

Solution: Check observable subscription:

useEffect(() => {
  const sub = contract.state$.subscribe(setState);
  return () => sub.unsubscribe();
}, [contract]);

Best Practices

1. Minimize Circuit Complexity

// Good: Simple, focused circuits
export circuit incrementScore(): [] {
  score.increment(1);
}

// Avoid: Complex circuits increase proof time
export circuit complexOperation(): [] {
  // Many operations...
}

2. Use Appropriate State Visibility

// Public: Scores, rankings, game outcomes
export ledger publicScore: Counter;

// Private: Player hands, strategies, hidden moves
// (handled in TypeScript witnesses)

3. Handle Errors Gracefully

const handleAction = async () => {
  try {
    setLoading(true);
    await contract.someAction();
  } catch (error) {
    console.error('Transaction failed:', error);
    setError('Transaction failed. Please try again.');
  } finally {
    setLoading(false);
  }
};

4. Test Edge Cases

it("handles maximum players", () => {
  const sim = createSimulator();
  for (let i = 0; i < MAX_PLAYERS; i++) {
    sim.joinGame();
  }
  expect(() => sim.joinGame()).toThrow("Game full");
});

Next Steps & Resources

Learning Path

Beginner: Complete this tutorial, modify the counter contract
Intermediate: Build the Rock-Paper-Scissors game
Advanced: Create a multi-player card game

Official Resources

Midnight Documentation: docs.midnight.network
Compact Language Guide: docs.midnight.network/compact
Lace Wallet: lace.io
Faucet (Test Tokens): faucet.preview.midnight.network

Community

Discord: Join the Midnight developer community
GitHub: Contribute to open-source tools
Forum: Ask questions and share projects

Starter Template Resources

Live Demo: counter.nebula.builders
Template Repo: MeshJS/midnight-starter-template
Mesh SDK: meshjs.dev
Webisoft Development Labs: webisoft.com

Quick Reference Card

Compact Cheat Sheet

// Pragma (required)
pragma language_version >= 0.19;

// Imports
import CompactStandardLibrary;

// Public state (ledger)
export ledger myCounter: Counter;
export ledger myValue: Uint<64>;
export ledger myMap: Map<Address, Uint<64>>;

// Circuits (state-changing functions)
export circuit myFunction(param: Uint<64>): [] {
  myCounter.increment(param);
}

// Pure functions (no state change)
export pure function add(a: Uint<64>, b: Uint<64>): Uint<64> {
  return a + b;
}

// Assertions
assert(condition, "Error message");

npm Scripts Reference

npm install          # Install dependencies
npm run build        # Compile contracts & build all
npm run dev:frontend # Start development server
npm run test         # Run tests
npm run setup-standalone  # Start local network
npm run build-production  # Production build

File Locations

File	Purpose
`counter-contract/src/*.compact`	Smart contract logic
`counter-contract/src/witnesses.ts`	Private state types
`frontend-vite-react/src/modules/midnight/`	SDK integration
`counter-cli/.env`	CLI configuration
`frontend-vite-react/.env`	Frontend configuration

Conclusion

You now have everything you need to start building privacy-preserving games on Midnight! The combination of:

Compact for smart contract logic
Zero-knowledge proofs for privacy
React + TypeScript for the frontend
RxJS for reactive state management

...gives you a powerful toolkit for creating games that were previously impossible on blockchain.

Start with the counter example, experiment with the concepts, and gradually build more complex games. The privacy features of Midnight open up entirely new categories of blockchain games where fairness and secrecy can coexist.

Happy building!

Built with the Midnight Starter Template

Webisoft Development Labs

Forem: UtkarshVarma

Building midnight-agent-skills: AI-Powered Development for Privacy-First Blockchain Made Easy

The Problem: Privacy Blockchain Development is Hard

The Insight: AI Agents Need Midnight-Specific Knowledge

The Solution: midnight-agent-skills

How It Works

The Skills

1. midnight-compact-guide

2. midnight-sdk-guide

3. midnight-infra-setup

4. midnight-deploy

5. midnight-test-runner

How I Built It

Step 1: Study Existing Formats

Step 2: Gather Authoritative Sources

Step 3: Create Skills with Verified Patterns

Step 4: Build the CLI

Problems It Solves

1. Wrong Syntax Generation

2. Outdated Patterns

3. Infrastructure Confusion

4. Missing Patterns

5. Testing Struggles

Building with midnight-agent-skills

Quick Start

Example Workflow

Technical Architecture

File Structure

SKILL.md Format

How AI Agents Discover Skills

Verification Process

Source Priority

Verification Steps

Future Plans

More Skills

Better Tooling

Community Contributions

Conclusion

Resources

Building a Privacy-Preserving Custodian App with Selective Disclosure on Midnight

Table of Contents

Introduction to Selective Disclosure

What is Selective Disclosure?

The Custodian Model

The Privacy Problem

Why Build Custodian Apps on Midnight?

Real-World Use Cases

1. Proof of Reserves

2. Accredited Investor Verification

3. Credit Scoring

4. Regulatory Compliance

5. Asset Verification

Comparison: Traditional vs. Midnight Custodian

Why Zero-Knowledge Proofs?

Understanding Selective Disclosure Architecture

System Architecture

Data Flow for Selective Disclosure

Key Components

1. Custodian Contract

2. Disclosure Circuits

3. Verifier Functions

4. Credential Registry

Prerequisites & Setup

Required Tools

Step 1: Install Compact Compiler

Step 2: Clone the Starter Template

Step 3: Create Custodian Contract Structure

Project Structure

Directory Layout

Writing the Custodian Contract

The Complete Custodian Contract

Implementing Selective Disclosure

Private State Definition

Contract Controller

Frontend Integration

Main Custodian Dashboard

Verifier Component

Testing Your Contract

Test Suite

Test Simulator