Skip to content

quickstart.mdx

Latest commit

 

History

History
222 lines (146 loc) · 7.69 KB

quickstart.mdx

File metadata and controls

222 lines (146 loc) · 7.69 KB
title Create a Midnight DApp
description Get started creating a Midnight DApp using the create-mn-app CLI tool.
sidebar_position 15
sidebar_label Quickstart

import Tabs from "@theme/Tabs"; import TabItem from "@theme/TabItem"; import Step, { StepsProvider } from "@site/src/components/Step/Step";

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 first prompts you to choose the type of project you want to create:

  • Contract
  • Full DApp

Contract

Selecting Contract scaffolds a minimal project for deploying a Compact smart contract.

You will be prompted to choose a contract template. Currently the available option is:

  • Hello world

The Hello world contract is a basic example that demonstrates how to deploy a Compact contract and interact with it from the CLI.

Full DApp

Selecting Full DApp scaffolds a complete decentralized application with contract logic, deployment scripts, and a CLI for interacting with the contract.

You will be prompted to choose a DApp template. Available options include:

  • Counter
  • Bulletin board

For this guide, select Contract → Hello world 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:

Option Description
-t, --template <name> Select a template: hello-world, counter, bboard
--use-npm/yarn/pnpm/bun Force the use of a specific package manager
--skip-install Skip the installation of dependencies
--skip-git Skip the initialization of a git repository
--verbose Show detailed output when creating the project
-h, --help Show help
-V, --version Show 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.