Bulletin Board DApp

This project is built on the Midnight Network.

A Midnight smart contract example demonstrating a simple one-item bulletin board with zero-knowledge proofs on testnet. Users can post a single message at a time, and only the message author can remove it.

Project Structure

bulletin-board/
├── contract/               # Smart contract in Compact language
│   └── src/               # Contract source and utilities
├── api/                   # Methods, classes and types for CLI and UI
├── bboard-cli/            # Command-line interface
│   └── src/               # CLI implementation
└── bboard-ui/             # Web browser interface
    └── src/               # Web UI implementation

Prerequisites

1. Node.js Version Check

You need Node.js (tested with current LTS):

node --version

Expected output: v24.11.1 or higher.

If you get a lower version: Install Node.js LTS.

2. Docker Installation

The proof server runs in Docker and is required for both CLI and UI to generate zero-knowledge proofs:

docker --version

Expected output: Docker version X.X.X.

If Docker is not found: Install Docker Desktop. Make sure Docker Desktop is running.

3. Lace Wallet Extension (UI Only)

For the web interface, install the official Cardano Lace wallet extension on Chrome Store or the Edge Store (tested with version 1.36.0).

After installing, set up the Midnight wallet:

1. Open the Lace wallet extension and go to Settings
2. Enable the Beta Program to unlock Midnight network support
3. Create a new wallet — Midnight will appear as a network option
4. Go to Settings > Midnight and set Network to Preprod
5. Set Proof server to Local (http://localhost:6300) — this must point to your local proof server started via Docker
6. Click Save configuration
7. Fund your wallet with tNIGHT tokens from the Preprod Faucet
8. Go to Tokens in the wallet, click Generate tDUST, and confirm the transaction — tDUST tokens are required to pay transaction fees on preprod

Setup Instructions

Install Project Dependencies

# Install root dependencies
npm install

# Install API dependencies
cd api && npm install && cd ..

# Install contract dependencies and compile
cd contract && npm install

Compile the Smart Contract

The Compact compiler (v0.29.0) generates TypeScript bindings and zero-knowledge circuits from the smart contract source code:

npm run compact    # Compiles the Compact contract
npm run build      # Copies compiled files to dist/
cd ..

Expected output:

> compact
> compact compile src/bboard.compact ./src/managed/bboard

Compiling 2 circuits:
  circuit "post" (k=14, rows=10070)
  circuit "takeDown" (k=14, rows=10087)

> build
> rm -rf dist && tsc --project tsconfig.build.json && cp -Rf ./src/managed ./dist/managed && cp ./src/bboard.compact ./dist

Build the CLI Interface

cd bboard-cli
npm install
npm run build
cd ..

Build the UI Interface (Optional)

Only needed if you want to use the web interface:

cd bboard-ui
npm install
npm run build
cd ..

Option 1: CLI Interface

Run the CLI

# For preprod network
npm run preprod-remote

# For preview network
npm run preview-remote

Using the CLI

Create a Wallet

1. Choose option 1 to build a fresh wallet
2. The system will generate a wallet address and seed
3. Save both the address and seed - you'll need them later

Expected output:

Your wallet seed is: [64-character hex string]
Using unshielded address: mn_addr_preprod1hdvtst70zfgd8wvh7l8ppp7mcrxnjn56wc5hlxpwflz3fxdykaesrw0ln4 waiting for funds...

Fund Your Wallet

Before deploying contracts, you need testnet tokens.

1. Copy your wallet address from the output above
2. Visit the faucet
3. Paste your address and request funds
4. Wait for the CLI to detect the funds (takes 2-3 minutes)

Expected output:

Your NIGHT wallet balance is: 1000000000

Deploy Your Contract

1. Choose the contract deployment option
2. Wait for deployment (takes ~30 seconds)
3. Save the contract address for future use

Expected output:

Deployed bulletin board contract at address: [contract address]

Use the Bulletin Board

You can now:

• Post a message to the bulletin board
• View the current message
• Remove your message (only if you posted it)
• Exit when done

Each action creates a real transaction on Midnight Testnet using zero-knowledge proofs generated by the proof server.

Option 2: Web UI Interface

The web interface uses the same proof server and requires additional browser setup.

Start the Proof Server (if not already running)

If you haven't started the proof server for the CLI, start it now:

cd bboard-cli
docker compose -f proof-server-local.yml up -d

Verify it's running:

docker ps

Start the Web Interface

The UI can run against preprod or preview networks:

cd bboard-ui

# For preprod network
npm run build:start

# For preview network
npm run build:start:preview

The UI will be available at:

• http://127.0.0.1:8080

Browser Setup

1. Open the UI URL in a browser with Lace wallet extension installed
2. Set up Lace wallet if it's your first time
3. Authorize the application when Lace wallet prompts
4. Use the bulletin board web interface

Useful Links

• Get Testnet tNIGHT on Preprod Faucet or Preview Faucet
• Midnight Documentation - Complete developer guide
• Compact Language Guide - Smart contract language reference
• Get Lace wallet on the Chrome Store or the Edge Store

Troubleshooting

Common Issue	Solution
npm install fails	Ensure you're using Node.js LTS version. If you get ERESOLVE errors, try npm install --legacy-peer-deps
Contract compilation fails	Ensure you're in contract directory and run npm run compact
Network connection timeout	CLI requires internet connection, restart if connection times out
Token funding takes too long	Wait 1-2 minutes, funding is automatic in CLI
"Application not authorized" error	Start proof server: docker compose -f proof-server-local.yml up -d
Lace wallet not detected	Install Lace wallet browser extension and refresh page
Docker issues	Ensure Docker Desktop is running, check docker --version
Port 6300 in use	Run docker compose down then restart services
Dependencies won't install	Use Node.js LTS version. For older npm versions, you may need --legacy-peer-deps
Contract deployment fails	Verify wallet has sufficient balance and network connection

Notes

• CLI and UI can run simultaneously and share the same proof server
• Proof server (Docker) is required for both CLI and UI to generate zero-knowledge proofs
• Contract must be compiled before building CLI or UI
• Fund your wallet using the testnet faucet before deploying contracts

Repository Notes / Temporary Workarounds

This repository contains several workarounds required due to current limitations in upstream tooling and dependencies. Each item below documents a concrete deviation from the default or expected setup.

• Modified testkit sources Some parts of midnight-testkit-js are vendored into this repository and modified to work correctly with the current setup.

• Transaction fee configuration
  The default additionalFeeOverhead value (500_000_000_000_000_000n) from 'midnight-testkit-js' is required on the Undeployed network (lower values fail with BalanceCheckOverspend on the midnight-node side). On the Preview network, that high overhead prevents transaction creation because it requires a large amount of dust, so it is overridden and set to 1_000n. The root cause is not yet clear.

• LevelDB private state provider
  The levelDbPrivateStateProvider, shipped with Node.js dependencies, does not work in browser environments. An in-memory private state provider is used instead; the implementation is copied from midnight-js.

• Overall API Usage Some of the tooling used in midnight-testkit-js, midnight-js and midnight-wallet is not currently well suited for direct application use. Significant wiring and integration logic is required, parts of which are copied into this repository. More flexible and composable APIs would reduce the need for copying and modification, allowing consumers to extend functionality rather than patch or fork existing implementations.