Skip to main content

Part 2: building a DApp

In this second part of the Midnight developer tutorial, you will:

  1. Learn to install the tools necessary to compile a Midnight contract and DApp from source code
  2. Download the example code needed for the remainder of the tutorial
  3. Build a simple example from source
  4. Run the example and deploy your own smart contract
  5. Learn to install and run your own Midnight network node and its associated pub-sub indexer, rather than relying on a node in the cloud.
important

When going through the tutorial, make sure you use compatible versions of example code and Compact compiler, as shown in the release compatibility matrix.

The last sections of part 2 of the tutorial examine the Compact code for the example contract and the TypeScript code for the example DApp in more detail.

When you are done with part 2, you will have built a DApp from source, deployed a contract, and run your own non-voting Midnight node, connected to the Midnight network.

The example contract in the DApp in part 2 is very simple: it merely creates a counter on the ledger and provides a circuit to increment it. The contract does not enforce any constraints beyond those implied by the Counter type itself, and the DApp does not work with any interesting private data. Thus, it does not show off Midnight's capability to shield private data, but when you are done with part 2, you will have built a DApp from source and deployed a new contract on the Midnight network.

Prerequisites for part 2

In part 1 of the tutorial, you installed only the tools needed to use Midnight, not the ones needed to be a Midnight developer. In this part of the tutorial, you will install and configure the tools needed to build Midnight DApps.

info

If you are already an experienced JavaScript or TypeScript developer, you are likely to have NVM and Yarn installed already. In that case, you should read over the following steps and perform only the parts that are relevant to configure the tools for Midnight development.

Node​

Many Midnight Testnet features are provided as TypeScript packages, including the Midnight example applications and Midnight APIs. The Node Version Manager (NVM) is the best way to install the Node.js versions that these repositories require. Installation and troubleshooting instructions for NVM can be found on the NVM GitHub site. (If you are installing on macOS using Homebrew, please pay attention to Homebrew's necessary additions to your shell profile.)

After following the NVM installation instructions, verify that NVM is installed:

nvm --version

You should see a version number printed, such as 0.39.5.

Install LTS version of Node 18x or greater:

nvm install 18 --lts

Midnight Compact compiler​

Download the Compact compiler from the Midnight Testnet releases repository, choosing either the Linux or macOS package. The file is named compactc-<platform>.zip.

Create a directory in which to place the compiler and its supporting binaries, and unzip the file inside that directory. For example:

mkdir ~/my-binaries/compactc
cd ~/my-binaries/compactc
unzip ~/Downloads/compactc-<platform>.zip

MacOS

Add the executables compactc.bin and zkir to your authorized applications set. You can do this as follows:

  1. In your terminal, run compactc.bin. MacOS will warn you that it cannot be opened because 'the developer cannot be verified'. Click the Cancel button in this dialog.
  2. Now open your System settings and navigate to Privacy & Security.
  3. Scroll down near the bottom, and you should see "compactc.bin" is blocked from use because it is not from an identified developer, with a button that says Allow Anyway. Click that button.
  4. Repeat for zkir.

Linux, or Windows with WSL

The unzipped compiler should already be executable, but if you run into problems, check that compactc.bin, zkir, and compactc are executable, or run chmod +x compactc.bin zkir compactc in the unzipped Compact compiler directory.

Testing the compiler installation

After installing the compiler, open your terminal and navigate to the directory where you unzipped the compiler. Then, run the following command:

./compactc --version

This command will display the version number of your installed compiler, such as 0.8.11, confirming that it's properly installed and ready to use. Refer to the release compatibility matrix for the version compatibillity overview.

On MacOS, the first time you run compactc you will be warned that it cannot be opened because 'the identity of the developer cannot be confirmed.' Click the Open button in this dialog box to continue.

Setting up often-used environmental variables

The Midnight example DApps use the shell environment variable COMPACT_HOME to locate the Compact compiler. You may want to add this to your shell profile. For example:

export COMPACT_HOME='<absolute path to compactc directory>'

You may also want to add the directory to your PATH environment.

Running Midnight Compact compiler​

In order to run Midnight Compact compiler, add the directory where the compiler is to your $PATH environment, reload your shell config file and check if Midnight Compact compiler runs with the command:

compactc --version

Optional: Visual Studio Code (VSCode) extension for Compact​

You can use any editor you like to create Midnight DApps. Midnight provides an extension for VSCode, specifically for creating and editing Midnight contracts, which are written in the Compact DSL. In addition to syntax highlighting, the extension does some live, dynamic checking of your contracts as you type, and it can help with debugging. It even provides templates to help you get started with new contracts or parts of them. Even if VSCode is not your primary editor, you may want to use the VSC Compact extension to edit Midnight contracts, at least while you are learning the language.

You can download the VSCode extension for Compact from the Midnight Testnet releases repository, where it will have a file name like compact-x.y.z.vsix for some version x.y.z.

To install the plugin in VSCode:

  • Open the Extensions pane in VSCode
  • Click the ... symbol at the top of the Extensions pane
  • Select 'Install from VSIX...'
  • Locate the file you just downloaded.

VSCode can usually use newly installed plugins immediately, but sometimes it prompts you to restart for the changes to take effect.