🌙 Midnight Quick Starter Template

Base template for blockchain projects on Midnight Network - A complete and modern template for developing decentralized applications (dApps) with smart contracts, backend APIs, CLI tools, and user interfaces.

📋 Table of Contents

🎯 Description
✨ Features
🏗️ Architecture
⚙️ System Requirements
🚀 Installation
📖 Basic Usage
🏛️ Project Structure
🔍 Quick Development Guide
🐳 Docker Services
🚀 Running the Application
🤝 Contributing
📄 License
🚀 Roadmap & Ideas for Improvement

🎯 Description

Midnight Quick Starter is a complete and modern template for developing blockchain applications on the Midnight network. This template provides a solid foundation with all the necessary tools to create dApps with smart contracts, APIs, user interfaces, and CLI tools.

Use Cases

✅ Complete dApp development on Midnight Network
✅ Smart contract creation with Compact
✅ Backend APIs for blockchain interaction
✅ Modern user interfaces with React
✅ CLI tools for development
✅ Monorepo with optimized dependency management

✨ Features

🔧 Monorepo with Turbo - Optimized build system and dependency management
📝 TypeScript - Complete static typing across all packages
⚡ React + Vite - Modern UI with hot reload
🔒 Compact Contracts - Smart contracts with Compact language
🌐 REST/WebSocket API - Backend for blockchain interaction
🖥️ CLI Tools - Command line tools
🎨 Tailwind CSS - Modern and responsive styles
📏 ESLint + Prettier - Clean and consistent code

🏗️ Architecture

midnight-quick-starter/
├── 📦 packages/
│   ├── 🎨 ui/          # React + Vite Frontend
│   ├── 🔧 api/         # Backend API
│   ├── 🖥️ cli/         # CLI Tools
│   └── 🔒 contract/    # Compact Contracts
├── 🔧 compact/         # Compact Compiler
└── 📚 docs/           # Documentation

⚙️ System Requirements

Node.js >= 22.0.0
Yarn >= 4.9.2
Git >= 2.0.0
Docker (optional, for local testing)

Requirements Verification

node --version  # >= 22.0.0
yarn --version  # >= 4.9.2
git --version   # >= 2.0.0

🚀 Installation

1. Clone the Template

# Option 1: Use "Use this template" button on GitHub
# Click "Use this template" → "Create a new repository"

# Option 2: Fork the repository
# Click "Fork" → Clone your forked repository
git clone <your-forked-repository-url>
cd midnight-quick-starter

# Option 3: Clone directly (for contributing)
git clone <repository-url>
cd midnight-quick-starter

2. Install Dependencies

yarn install

3. Download and Prepare ZK Parameters (Required for Proofs)

Before building, you need to fetch the zero-knowledge (ZK) parameters required by the proof server. This is done via a helper script that you should place in the CLI package:

# Move to the CLI package directory
cd packages/cli

# Download the fetch-zk-params.sh script
curl -O https://raw.githubusercontent.com/bricktowers/midnight-proof-server/main/fetch-zk-params.sh
# or
wget https://raw.githubusercontent.com/bricktowers/midnight-proof-server/main/fetch-zk-params.sh

# Give execution permissions
chmod +x fetch-zk-params.sh

# Run the script to download ZK parameters
./fetch-zk-params.sh

Note:

This script will generate a folder at /.cache/midnight/zk-params with all the required parameters for zero-knowledge proofs.

Why is this needed? If you see an error like:
Error in response: Proving(public parameters for k=16 not found in cache)
it means the required parameters are missing.

This script is a workaround to ensure your application works locally. The Midnight team is working on a more integrated solution for parameter management in the future.

4. Configure Compact Compiler

To Install the compiler in your teminal follow these steps:

Download compiler

This command will download and run a shell script. It will instruct you how to add the binary directory it uses to your PATH environment variable.

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

Update compiler

Once you've done this, the compact command line tool is available to use. This tool has a number of useful subcommands that can be invoked. For instance, to update the toolchain to the latest version, you will run the command:

compact update

The output will look something like this (on an Apple Silicon macOS machine, for instance):

compact: aarch64-darwin -- 0.24.0 -- installed
compact: aarch64-darwin -- 0.24.0 -- default.

Check new version available

You can check if there is a new version available using the check subcommand like this:

compact check

If there is a new version available, you will see something like:

compact: aarch64-darwin -- Update Available -- 0.24.0
compact: Latest version available: 0.24.0.

This is reporting that you are on version 0.24.0 and that 0.25.0 is available.

Note:
You will not actually see this output until there is a new version available. Instead, you will see that you are on the latest version:

compact: aarch64-darwin -- Up to date -- 0.24.0

Invoking the Compiler

In addition to keeping the toolchain updated, the compact tool will also be the official supported way to invoke all the toolchain tools themselves. For the time being, the only such tool is the compiler, but we will be building out more tools in the future. The compiler can be invoked with the compile subcommand:

compact compile <contract file> <output directory>

You can see and learn more information, commands about the compiler here: compact developer tools

5. Build All Packages

# Build all packages (creates necessary folders automatically)
yarn build:all

Note: The build process automatically creates the necessary folders (keys and zkir) that are required by the frontend. No manual folder creation is needed.

What yarn build:all does:

Builds the contract package (compiles Compact contracts)

Builds the API package (TypeScript compilation)

Builds the CLI package (TypeScript compilation)

Builds the UI package (Vite build with contract assets)

Creates necessary folders for frontend compatibility

🏛️ Project Structure

📦 Main Packages

`packages/ui/` - Frontend

ui/
├── src/
│   ├── components/     # React Components
│   ├── hooks/         # Custom hooks
│   ├── lib/           # Utilities
│   ├── providers/     # Context providers
│   └── assets/        # Static resources
├── public/            # Public files
└── dist/              # Production build

`packages/api/` - Backend API

api/
├── src/
│   ├── index.ts       # Entry point
│   └── test/          # Tests
└── dist/              # Compiled build

`packages/contract/` - Smart Contracts

contract/
├── src/
│   ├── quick-starter.compact  # Main contract
│   ├── managed/               # Generated contracts
│   └── index.ts              # Exports
└── dist/                     # Compiled build

`packages/cli/` - CLI Tools

cli/
├── src/
│   ├── launcher/      # Network launchers
│   ├── config.ts      # Configurations
│   └── index.ts       # Entry point
└── dist/              # Compiled build

🔧 Configuration

turbo.json - Monorepo configuration
package.json - Root dependencies and scripts
.eslintrc.js - Linting rules
tsconfig.json - TypeScript configuration

🔍 Quick Development Guide

🎯 Areas to Modify (Marked with TODO)

To quickly find areas that need customization, search for TODO comments throughout the codebase:

Using your code editor's global search:

VS Code: Ctrl+Shift+F (or Cmd+Shift+F on Mac) and search for TODO
WebStorm/IntelliJ: Ctrl+Shift+F and search for TODO
Sublime Text: Ctrl+Shift+F and search for TODO

Using command line:

# Search for all TODO comments
grep -r "TODO" .

# Or search in specific packages
grep -r "TODO" packages/contract/
grep -r "TODO" packages/api/
grep -r "TODO" packages/ui/
grep -r "TODO" packages/cli/

📝 Key Files to Customize

packages/contract/src/quick-starter.compact - Your main smart contract
packages/contract/src/index.ts - Contract exports and logic
packages/api/src/index.ts - Backend API implementation
packages/cli/src/index.ts - CLI interaction logic
packages/ui/src/main.tsx - Main React application
packages/ui/src/components/ - React components
packages/ui/src/hooks/ - Custom React hooks
packages/ui/src/lib/ - Utility functions
packages/ui/src/providers/ - Context providers

🚀 Development Workflow

Edit your contract in packages/contract/src/quick-starter.compact
Build the contract with cd packages/contract && npx turbo run build
Build other packages as needed using individual build commands
Customize UI components in packages/ui/src/
Implement API logic in packages/api/src/

🐳 Docker Services

After building your packages, you can run the Infrastructure services using Docker:

Testnet Environment

cd packages/cli
docker compose -f testnet.yml up -d

Standalone Environment

cd packages/cli
docker compose -f standalone.yml up -d

Note: The -d flag runs containers in detached mode (background), so you can continue using your terminal.

You should see something like:

✔ Container quick-starter-proof-server  Started
✔ Container quick-starter-node          Started  
✔ Container quick-starter-indexer       Started

🚀 Running the Application

Start the UI

cd packages/ui
yarn start

The application will be available at localhost:8080

🤝 Contributing

Contribution Guidelines

This is a template designed to be used as a starting point for new projects. You can:

Use as Template - Click "Use this template" to create a new repository
Fork the repository for your own project
Contribute - Any PR is welcome to improve the template

If contributing:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'feat: add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Code Standards

Use TypeScript for all code
Follow configured ESLint and Prettier
Write tests for new features
Document APIs and complex functions

Commit Structure

feat: new feature
fix: bug fix
docs: documentation
style: code formatting
refactor: refactoring
test: tests
chore: maintenance tasks

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

🚀 Roadmap & Ideas for Improvement

This template is designed to be a living project and welcomes suggestions and contributions for new features and improvements. Here are some ideas and known areas for future enhancement:

Have an idea? Open an issue or pull request to help make this template even better!

🆘 Support

If you have issues or questions:

Check the documentation
Search existing issues
Create a new issue

🔗 Useful Links

⭐ If this template is useful to you, consider giving the repository a star!

Made with ❤️ by the Midnight ecosystem

luislucena16/midnight-quick-starter