DEV Community

Cadalt
Cadalt

Posted on

Deploy Your First Midnight Contract with Nightforge 🚀

#compact #midnightntwrk #nightforge #privacy

A complete guide to compiling and deploying contracts on the Midnight blockchain using Nightforge's synced wallet workflow

Introduction

Deploying a smart contract on the Midnight blockchain can seem complex, but Nightforge streamlines the entire process. This guide walks you through every stepcompactfrom project initialization to a live contract deploymentcompactusing the modern synced wallet state approach.

By the end, you'll have a deployed contract on Midnight's Preprod network and understand the full development workflow.

Requirements: Node.js 18+, npm, tNIGHT testnet tokens

What You'll Learn

  • ✅ Initialize a Midnight contract project
  • ✅ Create and fund a wallet
  • ✅ Synchronize wallet state with the blockchain
  • ✅ Compile your contract
  • ✅ Run a proof server
  • ✅ Deploy to the Midnight blockchain

Prerequisites

Before you start, ensure you have:

  1. Node.js 18+ and npm installed 
   node --version && npm --version
Enter fullscreen mode Exit fullscreen mode
  1. Nightforge CLI installed globally or via npx 
   npm install -g nightforge
   # or use it directly with: npx nightforge
Enter fullscreen mode Exit fullscreen mode

Step 1: Initialize Your Project

Start fresh by creating a new Midnight contract project:

npx nightforge init my-contract-project
Enter fullscreen mode Exit fullscreen mode

Nightforge will:

  • 📁 Create a project directory
  • 📝 Generate a sample contract (my-contract.compact)
  • 📦 Add package.json with Midnight SDK dependencies
  • ⚙️ Create default configuration files

Enter your new project:

cd my-contract-project
Enter fullscreen mode Exit fullscreen mode

Step 2: Create and Fund Your Wallet

Create a new wallet 

npx nightforge wallet create
Enter fullscreen mode Exit fullscreen mode

This command:

  • 🔐 Generates a new cryptographic keypair
  • 💾 Saves it locally in wallet.json
  • 📋 Displays your public address

Important: Your wallet.json is sensitivecompact*never commit it* to version control. It's already in .gitignore.

You'll see output like:

✓ Wallet created successfully
Address: A1B2C3D4E5F6... (actual address shown)
Enter fullscreen mode Exit fullscreen mode

Copy your address for the next step.

Fund from the Faucet

  1. Open https://faucet.midnight.network in your browser
  2. Select Preprod network
  3. Paste your address
  4. Click Send tNIGHT
  5. Wait 30 seconds for confirmation

You should receive 100 tNIGHT on the Preprod testnet.

Step 3: Synchronize Wallet State

The synced wallet approach keeps your wallet state synchronized with the blockchain in real-time. This is the modern, recommended way to deploy.

Initialize sync configuration (one-time setup) 

npx nightforge sync
Enter fullscreen mode Exit fullscreen mode

This creates:

  • midnightwalletsync.config.json compact sync service configuration

Start the sync service

In a terminal window, start the wallet sync service:

npx nightforge sync
Enter fullscreen mode Exit fullscreen mode

Output shows:

✓ Walletsync service starting...
✓ Connected to Preprod network
✓ Syncing wallet state from blockchain
✓ Server ready on http://127.0.0.1:8787
Enter fullscreen mode Exit fullscreen mode

Keep this terminal open. The sync service runs continuously and updates your wallet state every block.

Check Your Balance (New Terminal)

Open a second terminal in your project directory and verify your funded wallet:

npx nightforge wallet balance
Enter fullscreen mode Exit fullscreen mode

Expected output:

Balance: 100 tNIGHT
Network: Preprod
Enter fullscreen mode Exit fullscreen mode

Great! Your wallet is synced and funded. ✨

Convert tNIGHT to DUST

Contracts operate in DUST (the base unit). Convert your tNIGHT:

npx nightforge wallet dust
Enter fullscreen mode Exit fullscreen mode

This command:

  • 💱 Exchanges your tNIGHT for DUST at 1:1,000,000 ratio
  • ⏳ Waits for blockchain confirmation
  • ✓ Updates your synced balance

Output:

✓ DUST conversion successful
New balance: 100,000,000 DUST
Enter fullscreen mode Exit fullscreen mode

Step 4: Compile Your Contract

Still in your second terminal, compile the contract:

npx nightforge compile
Enter fullscreen mode Exit fullscreen mode

Nightforge will:

  • 📖 Parse your .compact contract
  • ✓ Type-check the code
  • 📦 Generate circuit artifacts
  • 📝 Create deployment metadata

Expected output:

✓ Compiling my-contract.compact...
✓ Type checking passed
✓ Circuit compiled successfully
✓ Artifacts ready: dist/artifacts/
Enter fullscreen mode Exit fullscreen mode

Note: Compilation artifacts are in dist/artifacts/ and are not committed to git.

Step 5: Start the Proof Server

Contracts require zero-knowledge proofs for private state transitions. Start the proof server in a third terminal:

npx nightforge proof-server start
# or shorthand:
npx nightforge ps
Enter fullscreen mode Exit fullscreen mode

Output:

✓ Proof server starting on http://127.0.0.1:6300
✓ Ready to generate proofs
Enter fullscreen mode Exit fullscreen mode

Keep this terminal open while deploying. The proof server generates transaction proofs in real-time.

Step 6: Deploy Your Contract

Now deploy! In your second terminal (where you ran compile), run:

npx nightforge deploy my-contract --network preprod
Enter fullscreen mode Exit fullscreen mode

The deployment process:

  1. ✓ Loads compiled artifacts
  2. ✓ Reads synced wallet state from http://127.0.0.1:8787
  3. ✓ Generates initial contract state
  4. ✓ Generates deployment proof via proof server
  5. ✓ Submits transaction to Midnight network
  6. ⏳ Waits for confirmation (1 minutes)

Expected output:

✓ Loading contract artifacts...
✓ Reading synced wallet state...
✓ Generating deployment proof...
✓ Submitting deployment transaction...
✓ Waiting for confirmation...
✓ Contract deployed successfully!

Contract ID: abc123def456...
Transaction: tx_xyz789...
Network: Preprod
Enter fullscreen mode Exit fullscreen mode

Congratulations! Your contract is live on Midnight. 🎉

Verification

Check Deployment Metadata

A deployment.json file was created with your contract details:

cat deployment.json
Enter fullscreen mode Exit fullscreen mode

Contents:

{
  "contractId": "abc123def456...",
  "deploymentTx": "tx_xyz789...",
  "deployedAt": "2024-01-15T10:30:45Z",
  "network": "preprod"
}
Enter fullscreen mode Exit fullscreen mode

📝 Advanced: Flags & Alternatives

Deployment Flags

--remote <URL>

Use an explicit remote proof server instead of the local one:

npx nightforge deploy my-contract --remote http://proof-server.example.com:6300 --network preprod
Enter fullscreen mode Exit fullscreen mode

--legacy

Use the old non-synced wallet approach (for compatibility):

npx nightforge deploy my-contract --legacy --network preprod
Enter fullscreen mode Exit fullscreen mode

⚠️ Note: Legacy mode requires manual wallet state management. Not recommended for new projects.

--auto

Fully automatic deployment with intelligent workflow orchestration:

npx nightforge deploy my-contract --auto --network preprod
Enter fullscreen mode Exit fullscreen mode

This command:

  • ✓ Creates wallet if missing
  • ✓ Checks faucet-funded balance
  • ✓ Auto-converts tNIGHT → DUST
  • ✓ Starts proof server automatically
  • ✓ Deploys when conditions are met

Perfect for CI/CD pipelines or unattended deployments.

🔌 Sync Service Options

Control the sync server behavior:

# Start on custom port (persists in config)
npx nightforge sync --port 9999

# Check sync service status
npx nightforge sync --status

# View synced balance for specific wallet alias
npx nightforge sync --balance my-wallet
Enter fullscreen mode Exit fullscreen mode

🛠️ Troubleshooting

Error: "Sync service not running"

→ Ensure npx nightforge sync is running in a separate terminal

Error: "Insufficient balance"

→ Verify faucet funding: npx nightforge wallet balance

Error: "Proof server connection failed"

→ Check proof server is running: npx nightforge ps

Error: "Contract compilation failed"

→ Verify contract syntax in my-contract.compact and run npx nightforge compile again

🚀 Next Steps

Now that your contract is deployed:

  1. Modify the contract compact Edit my-contract.compact and redeploy
  2. Write integration tests compact Use src/index.ts to test contract calls
  3. Connect to mainnet compact Change --network preprod to --network mainnet when ready
  4. Build a frontend compact Use the contract client to interact from a web/mobile app

📚 Learn More

Summary

You've successfully:

  • ✅ Initialized a Midnight contract project
  • ✅ Created and funded a wallet
  • ✅ Synced wallet state with the blockchain
  • ✅ Compiled your contract
  • ✅ Generated zero-knowledge proofs
  • ✅ Deployed to the Preprod network

You're now a Midnight developer! 🌙

Have questions? Join the Midnight community Discord or open an issue on GitHub.

Last updated: April 2026 | Nightforge v1.0.0

Top comments (0)