Skip to main content
Version: v1

Create a Midnight DApp

This guide explains how to scaffold a Midnight DApp using the create-mn-app CLI tool.

Prerequisites​

The following tools are required to run a Midnight DApp:

Midnight CLI tool​

The create-mn-app CLI tool provides starter templates for Midnight DApps. It includes a preconfigured TypeScript setup, hot reloading, and wallet operation logic.

To scaffold a new DApp, run the following command:

npx create-mn-app [project-name]
info

Ensure you replace [project-name] with the name of your new DApp.

The CLI tool prompts you to select a template. Available options include:

  • Hello world
  • Counter
  • Bulletin board

Select the Hello world template and follow the prompts to complete the setup. You should see the following output:

Creating a new Midnight app in /path/to/my-app.

Template: hello-world

✔ Project structure created
✔ Dependencies installed
✔ Git repository initialized
✔ Docker is ready for proof server
✔ Contract compiled successfully

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🎉 Success! Your Midnight app is ready.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Once the installation is complete, navigate to the my-app directory:

cd my-app

Your project structure should look similar to this:

my-app/
├── contracts/
│   └── hello-world.compact    # Compact smart contract
├── src/
│   ├── cli.ts                 # Interact with deployed contract
│   ├── deploy.ts              # Deploy contract to Preprod
│   └── check-balance.ts       # Check wallet balance
├── docker-compose.yml         # Proof server config
├── package.json
└── deployment.json            # Deployment information (contains wallet seed and contract address)

The contracts/hello-world.compact file contains the Compact smart contract code.

pragma language_version 0.21;

export ledger message: Opaque<"string">;

export circuit storeMessage(newMessage: Opaque<"string">): [] {
  message = disclose(newMessage);
}

Compact is Midnight's smart contract language used to define contract logic. It is similar to TypeScript but is designed for use with the Midnight runtime.

The docker-compose.yml file contains the configuration for the proof server. The proof server generates Zero Knowledge (ZK) proofs for smart contracts on the Midnight network. It must be running before you can deploy or interact with the contract.

Set up the project​

Run the script to set up the project:

npm run setup

This script starts the proof server, compiles the contract, and deploys the contract to the Preprod network.

The CLI prompts you to create a new wallet or restore an existing wallet. If you choose to create a new wallet, the CLI generates a new wallet seed and displays the wallet address. Save the wallet seed in a secure location. You'll need it to restore your wallet.

note

You'll need to fund your wallet with tNIGHT tokens from the Preprod faucet. tNIGHT is used to generate tDUST, which is required to pay for transaction fees on the Midnight blockchain.

After funding your wallet, the CLI automatically generates tDUST and deploys the contract to the Preprod network. This process takes a few seconds to complete.

You should see the following output after the deployment is complete:

  ✅ Contract deployed successfully!

  Contract Address: b92d63e566cbcede6............

  Saved to deployment.json

The deployment.json file in the root directory contains the deployment information for the contract. The CLI references this file when interacting with the contract.

Interact with the contract​

The tool provides a command-line interface to interact with the contract. Run the following command to start the CLI:

npm run cli

This command starts the CLI and prompts you to enter your wallet seed. After syncing your wallet with the network, you can interact with the contract using the following commands:

1. Store a message
2. Read current message
3. Check wallet balance
4. Exit

Choose an option from the menu and follow the prompts to interact with the contract.

Templates​

The Midnight CLI tool provides starter templates for the following DApps:

Hello world​

The Hello world template is a message storage DApp that allows you to post and retrieve messages on the blockchain.

npx create-mn-app my-app

The Hello world template is the default and comes with dependencies installed. You don't need to use the --template flag when creating a new hello world DApp.

Counter​

The Counter template is a simple counter DApp that allows you to increment and decrement a counter.

npx create-mn-app my-app --template counter
cd my-app
npm install

To learn more about the Counter template, see the Counter DApp example.

Bulletin board​

The Bulletin board template is a privacy-preserving bulletin board DApp that allows you to post and remove messages.

npx create-mn-app my-app --template bboard
cd my-app
npm install

This template uses ZK proofs to verify the identity of the poster and the owner of the message without revealing their identity on-chain. To learn more about the Bulletin board DApp, see the Bulletin board DApp example.

CLI options​

The following options are available when creating a new DApp using the create-mn-app CLI tool:

OptionDescription
-t, --template <name>Select a template: hello-world, counter, bboard
--use-npm/yarn/pnpm/bunForce the use of a specific package manager
--skip-installSkip the installation of dependencies
--skip-gitSkip the initialization of a git repository
--verboseShow detailed output when creating the project
-h, --helpShow help
-V, --versionShow the version of the CLI tool

Next steps​

Now you know how to scaffold a new DApp using the Midnight CLI tool. Check out the hello world tutorial to learn how to write your first Midnight contract using the Compact language.