Midnight Network

https://docs.midnight.network
Admin
Midnight Network is a decentralized privacy platform that enables secure and private transactions...
Tokens:610,772
Snippets:7,258
Trust Score:8.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### Run Project Setup Script

Source: https://docs.midnight.network/getting-started/quickstart

Execute this script to initiate the project setup, which includes starting the proof server, compiling, and deploying the contract to the Preprod network. Follow prompts for wallet creation or restoration and ensure your wallet is funded with tNIGHT tokens.

```bash
npm run setup
```

--------------------------------

### Wallet Provider Setup

Source: https://docs.midnight.network/sdks/community/build-using-meshsdk/lace-wallet

Code example demonstrating how to set up the wallet provider and enable the wallet for use with Midnight Network.

```javascript
// Connect to Lace Wallet  
const wallet = window.midnight?.mnLace;  
if (!wallet) {  
  throw new Error('Please install Lace Beta Wallet for Midnight Network');  
}  
  
// Enable wallet and get state  
const walletAPI = await wallet.enable();  
const walletState = await walletAPI.state();  
const uris = await wallet.serviceUriConfig();  
```

--------------------------------

### Start Next.js Development Server

Source: https://docs.midnight.network/guides/nextjs-wallet-connect

Use this command to start the Next.js development server. Ensure you have npm installed.

```bash
npm run dev  

```

--------------------------------

### start()

Source: https://docs.midnight.network/api-reference/testkit-js/classes/MidnightWalletProvider

Starts the wallet provider service.

```APIDOC
## start(waitForFundsInWallet?, tokenType?)

### Description
Initializes and starts the wallet provider.

### Parameters
#### Arguments
- **waitForFundsInWallet** (boolean) - Optional - Whether to wait for funds to be available.
- **tokenType** (TokenType) - Optional - The specific token type to monitor.
```

--------------------------------

### Install MeshSDK for Midnight Network

Source: https://docs.midnight.network/sdks/community/build-using-meshsdk/getting-started

Use yarn to add the core setup package to your project.

```bash
yarn add @meshsdk/midnight-setup
```

--------------------------------

### Run Development Server Command

Source: https://docs.midnight.network/guides/react-wallet-connect

Start your development server using this command. After setup, this command will launch the local development server, typically accessible at http://localhost:5173.

```bash
npm run dev

```

--------------------------------

### Main deployment script logic

Source: https://docs.midnight.network/guides/deploy-mn-app

Handles the entire deployment process, including wallet setup, funding, and DUST registration. It prompts the user for wallet creation or restoration, generates a seed if needed, and syncs the wallet with the network. If the wallet balance is zero, it guides the user to a faucet for funding.

```typescript
// ─── Main Deploy Script ────────────────────────────────────────────────────────

async function main() {
  console.log('\n╔══════════════════════════════════════════════════════════════╗');
  console.log('║        Deploy Hello World to Midnight Preprod                ║');
  console.log('╚══════════════════════════════════════════════════════════════╝\n');

  // Check if contract is compiled
  if (!fs.existsSync(path.join(zkConfigPath, 'contract', 'index.js'))) {
    console.error('Contract not compiled! Run: npm run compile');
    process.exit(1);
  }

  const rl = createInterface({ input: stdin, output: stdout });

  try {
    // 1. Wallet setup
    console.log('─── Step 1: Wallet Setup ───────────────────────────────────────\n');
    const choice = await rl.question(
      '  [1] Create new wallet\n  [2] Restore from seed\n  > '
    );

    const seed = choice.trim() === '2'
      ? await rl.question('\n  Enter your 64-character seed: ')
      : toHex(Buffer.from(generateRandomSeed()));

    if (choice.trim() !== '2') {
      console.log(
        `\n  ⚠️  SAVE THIS SEED (you'll need it later):\n  ${seed}\n`
      );
    }

    console.log('  Creating wallet...');
    const walletCtx = await createWallet(seed);

    console.log('  Syncing with network...');
    const state = await Rx.firstValueFrom(
      walletCtx.wallet.state().pipe(
        Rx.throttleTime(5000),
        Rx.filter((s) => s.isSynced)
      )
    );

    const address = walletCtx.unshieldedKeystore.getBech32Address();
    const balance = state.unshielded.balances[unshieldedToken().raw] ?? 0n;

    console.log(`\n  Wallet Address: ${address}`);
    console.log(`  Balance: ${balance.toLocaleString()} tNight\n`);

    // 2. Fund wallet if needed
    if (balance === 0n) {
      console.log('─── Step 2: Fund Your Wallet ───────────────────────────────────\n');
      console.log('  Visit: https://faucet.preprod.midnight.network/');
      console.log(`  Address: ${address}\n`);
      console.log('  Waiting for funds...');

      await Rx.firstValueFrom(
        walletCtx.wallet.state().pipe(
          Rx.throttleTime(10000),
          Rx.filter((s) => s.isSynced),
          Rx.map((s) => s.unshielded.balances[unshieldedToken().raw] ?? 0n),
          Rx.filter((b) => b > 0n),
        ),
      );
      console.log('  Funds received!\n');
    }

    // 3. Register for DUST
    console.log('─── Step 3: DUST Token Setup ───────────────────────────────────\n');
    const dustState = await Rx.firstValueFrom(
      walletCtx.wallet.state().pipe(Rx.filter((s) => s.isSynced))
    );

    if (dustState.dust.walletBalance(new Date()) === 0n) {
      const nightUtxos = dustState.unshielded.availableCoins.filter(
        (c: any) => !c.meta?.registeredForDustGeneration
      );

      if (nightUtxos.length > 0) {
        console.log('  Registering for DUST generation...');
        const recipe = await walletCtx.wallet.registerNightUtxosForDustGeneration(
          nightUtxos,
          walletCtx.unshieldedKeystore.getPublicKey(),
          (payload) => walletCtx.unshieldedKeystore.signData(payload),
        );
        await walletCtx.wallet.submitTransaction(
          await walletCtx.wallet.finalizeRecipe(recipe)
        );
      }

      console.log('  Waiting for DUST tokens...');
      await Rx.firstValueFrom(
        walletCtx.wallet.state().pipe(
          Rx.throttleTime(5000),

```

--------------------------------

### Start Proof Server and Launch CLI

Source: https://docs.midnight.network/tutorials/counter/counter-cli

Commands to start the required proof server and execute the preprod CLI environment.

```bash
docker run -p 6300:6300 midnightntwrk/proof-server:latest midnight-proof-server -v  
```

```bash
cd counter-cli  
npm run preprod  
```

--------------------------------

### Start local proof server

Source: https://docs.midnight.network/getting-started/hello-world

Starts the local development environment and proof server using Docker.

```bash
yarn env:up
```

--------------------------------

### Check command output examples

Source: https://docs.midnight.network/compact/compilation-and-tooling/dev-tool-usage

Displays the output of the check command when no version is installed versus when an update is available.

```text
compact: no version installed.  
compact: Latest version available: 0.28.0.  
```

```text
compact: aarch64-darwin -- Update Available -- 0.26.0  
compact: Latest version available: 0.28.0.  
```

--------------------------------

### Install Bun on Mac

Source: https://docs.midnight.network/how-to/bun-runtime-midnight

Run this command to download and install the Bun binary on macOS. It installs to `~/.bun/bin`.

```bash
curl -fsSL https://bun.sh/install | bash
```

--------------------------------

### Install DApp Connector API

Source: https://docs.midnight.network/guides/nextjs-wallet-connect

Navigate to your project directory and install the DApp Connector API package. This guide uses v4.0.0.

```bash
cd <project-name>
npm install @midnight-ntwrk/dapp-connector-api
```

--------------------------------

### Install Dependencies

Source: https://docs.midnight.network/tutorials/bship/test-suite

Run this command to install all the project dependencies listed in package.json.

```bash
yarn install  

```

--------------------------------

### Install the Compact Developer Tools

Source: https://docs.midnight.network/blog/compact-developer-tools

Run this shell script to download and install the compact command-line tool.

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

--------------------------------

### Start Proof Server

Source: https://docs.midnight.network/guides/deploy-mn-app

Starts the proof server required for contract deployment. This command should be kept running in a separate terminal.

```bash
npm run start-proof-server
```

--------------------------------

### start

Source: https://docs.midnight.network/api-reference/testkit-js/classes/PreprodTestEnvironment

Initializes the test environment.

```APIDOC
## start

### Description
Starts the test environment by initializing the proof server and environment configuration.

### Parameters
#### Request Body
- **maybeProofServerContainer** (ProofServerContainer) - Optional - Optional proof server container to use instead of creating a new one

### Returns
- **Promise<EnvironmentConfiguration>** - The environment configuration
```

--------------------------------

### Install Compact Smart Contract Language

Source: https://docs.midnight.network/getting-started/installation

Use this command to install the pre-built binaries for the Compact smart contract language. Ensure you have curl installed.

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

--------------------------------

### Copy Example Accounts Config File

Source: https://docs.midnight.network/guides/midnight-local-network

Copy the example accounts configuration file to 'accounts.json'. This file should then be edited with your specific wallet mnemonics.

```bash
cp accounts.example.json accounts.json  
```

--------------------------------

### Initialize React project and install dependencies

Source: https://docs.midnight.network/guides/react-wallet-connect

Commands to scaffold a new React project with Vite and install the required DApp Connector API package.

```bash
npm create vite@latest my-wallet-app -- --template react-ts  
cd my-wallet-app  
```

```bash
npm install @midnight-ntwrk/dapp-connector-api  
```

--------------------------------

### Install Compact Compiler

Source: https://docs.midnight.network/how-to/bun-runtime-midnight

Install the Compact compiler, a standalone tool for converting Compact smart contracts to Midnight blockchain compatible code. By default, it's installed in `$HOME/.local/bin`.

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

--------------------------------

### Start and Stop Proof Server

Source: https://docs.midnight.network/api-reference/testkit-js

Shows how to start a proof server with specific network ID and ID, and then stop it. This is useful for integrating with the proof server in test scenarios.

```javascript
// Example: Start a proof server with network ID = preview and ID = 123
const proofServer = await DynamicProofServerContainer.start(logger, '123', 'preview');

//stop the proof server
await proofServer.stop();
```

--------------------------------

### Start Cardano-db-sync Services

Source: https://docs.midnight.network/nodes/cardano-db-sync

Use this command to start the services defined in the compose-partner-chains.yml file. Ensure Docker is running.

```bash
docker-compose -f compose-partner-chains.yml up -d
```

--------------------------------

### Install PostgreSQL Client

Source: https://docs.midnight.network/nodes/cardano-db-sync

Install the psql client on your system if you plan to connect to PostgreSQL directly. This is a prerequisite for using psql.

```bash
sudo apt-get install postgresql-client
```

--------------------------------

### Install Ubuntu on WSL

Source: https://docs.midnight.network/guides/windows-compact-setup

Executes the installation of the Ubuntu distribution for the Windows Subsystem for Linux.

```bash
wsl --install -d ubuntu  
```

--------------------------------

### Clone Counter Example Repository

Source: https://docs.midnight.network/examples/dapps/counter

Command to clone the Counter DApp example repository from GitHub. This is the first step in setting up the project locally.

```bash
git clone https://github.com/midnightntwrk/example-counter.git  
cd example-counter  

```

--------------------------------

### Troubleshoot Compact Compiler Installation

Source: https://docs.midnight.network/how-to/bun-runtime-midnight

Verify installation, update PATH, or reinstall the Compact compiler.

```bash
compact --version
```

```bash
export PATH="$HOME/.compact/bin:$PATH"
```

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

--------------------------------

### Verify Installations

Source: https://docs.midnight.network/guides/generating-dust-programmatically

Check if Node.js, npm, and Docker are installed and meet the version requirements.

```bash
node --version    # should print v18.x.x or higher  
npm --version     # should print 9.x.x or higher  
docker --version  # should print Docker version 2x.x.x or higher  
```

--------------------------------

### Install Testkit JS

Source: https://docs.midnight.network/api-reference/testkit-js

Install the testing library using yarn. This command should be run in your project's terminal.

```bash
yarn add -D @midnight-ntwrk/testkit-js
```

--------------------------------

### Run the tutorial script

Source: https://docs.midnight.network/guides/generating-dust-programmatically

Command to start the Node.js tutorial script.

```bash
npm start
```

--------------------------------

### Install DApp Connector Proof Provider Package

Source: https://docs.midnight.network/sdks/official/midnight-js

Install the necessary package for the DApp Connector proof provider using npm.

```bash
npm install @midnight-ntwrk/dapp-connector-proof-provider  

```

--------------------------------

### Initialize Wallets and Providers (beforeAll)

Source: https://docs.midnight.network/tutorials/bship/test-suite

Sets up network configuration, builds and starts wallet instances for Alice and Bob, syncs them, and then builds providers. Ensure `setNetworkId` is called first.

```typescript
    // setup before tests  
    beforeAll(async () => {  
        setNetworkId(config.networkId);  
  
        const envConfig: EnvironmentConfiguration = {  
            walletNetworkId: config.networkId,  
            networkId: config.networkId,  
            indexer: config.indexer,  
            indexerWS: config.indexerWS,  
            node: config.node,  
            nodeWS: config.nodeWS,  
            faucet: config.faucet,  
            proofServer: config.proofServer,  
        };  
  
        aliceWallet = await MidnightWalletProvider.build(logger, envConfig, ALICE_SEED);  
        await aliceWallet.start();  
        await syncWallet(logger, aliceWallet.wallet, 600_000);  
  
        bobWallet = await MidnightWalletProvider.build(logger, envConfig, BOB_SEED);  
        await bobWallet.start();  
        await syncWallet(logger, bobWallet.wallet, 600_000);  
  
        aliceProviders = buildProviders(aliceWallet, zkConfigPath, config);  
        bobProviders = buildProviders(bobWallet, zkConfigPath, config);  
  
        logger.info('Providers initialized, ready to test.');  
    });// end of beforeAll  
})// end of describe  

```

--------------------------------

### List Available Compact Toolchain Versions

Source: https://docs.midnight.network/compact/compilation-and-tooling/dev-tool-usage

Lists available Compact toolchain versions on the remote server. Use '--installed' to list locally installed versions.

```bash
compact list  

```

```bash
compact list --installed  

```

--------------------------------

### Clone the starter repository

Source: https://docs.midnight.network/getting-started/hello-world

Initializes the project environment by cloning the official Hello World example repository.

```bash
git clone https://github.com/midnightntwrk/example-hello-world.git
```

--------------------------------

### Get a dummy user address

Source: https://docs.midnight.network/api-reference/onchain-runtime/functions/dummyUserAddress

Use this function to obtain a sample user address string. No setup or imports are required.

```typescript
function dummyUserAddress(): string  

```

--------------------------------

### Start the Proof Server

Source: https://docs.midnight.network/blog/dapp-developers-bls-upgrade

Run the proof server container configured for the testnet.

```bash
docker run -p 6300:6300 midnightnetwork/proof-server -- midnight-proof-server --network testnet
```

--------------------------------

### Install Compact Compiler

Source: https://docs.midnight.network/guides/windows-compact-setup

Run this command in your WSL Ubuntu terminal to download and install the Compact compiler binaries. The script automatically updates your PATH.

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

```

--------------------------------

### Run the frontend

Source: https://docs.midnight.network/sdks/community/build-using-meshsdk/example-integration

Start the development server for the UI application.

```bash
cd ../ui && yarn start
```

--------------------------------

### Verify Setup After Component Updates

Source: https://docs.midnight.network/how-to/fix-version-mismatches

After updating component versions, test your setup to confirm everything functions correctly. This includes testing compilation, running tests, and checking Docker logs.

```bash
# Test compilation
compact compile src/contract.compact contract/

# Run tests
npm test

# Check for errors
docker logs [proof-server-container-id]
```

--------------------------------

### Install Wallet SDK with npm

Source: https://docs.midnight.network/sdks/official/wallet-developer-guide

Install the Midnight wallet SDK packages using npm. Replace VERSION with the compatible version from the release compatibility matrix.

```bash
npm install @midnight-ntwrk/wallet-sdk-facade@VERSION \
            @midnight-ntwrk/wallet-sdk-hd@VERSION \
            @midnight-ntwrk/wallet-sdk-address-format@VERSION \
            @midnight-ntwrk/wallet-sdk-unshielded-wallet@VERSION \
            @midnight-ntwrk/wallet-sdk-shielded@VERSION \
            @midnight-ntwrk/wallet-sdk-dust-wallet@VERSION \
            @midnight-ntwrk/ledger-v8  

```

--------------------------------

### Connect to Lace Wallet and Get State

Source: https://docs.midnight.network/sdks/community/build-using-meshsdk/lace-wallet

Establishes a connection to the Lace Beta Wallet, retrieves wallet state, and configures service URIs. Ensure the Lace Beta Wallet is installed.

```javascript
// Connect to Lace Wallet  
const wallet = window.midnight?.mnLace;  
if (!wallet) {  
  throw new Error('Please install Lace Beta Wallet for Midnight Network');  
}  
  
// Enable wallet and get state  
const walletAPI = await wallet.enable();  
const walletState = await walletAPI.state();  
const uris = await wallet.serviceUriConfig();  

```

--------------------------------

### Get Contract Balance - Kernel ADT

Source: https://docs.midnight.network/compact/data-types/ledger-adt

Retrieves the current contract's balance for a specific unshielded token type. The balance is fixed at the start of execution and not updated during contract runtime.

```typescript
balance(token_type: Either<Bytes<32>, Bytes<32>>): Uint<128>  
```

--------------------------------

### Get Unshielded Token Balance

Source: https://docs.midnight.network/compact/standard-library/exports

Retrieves the contract's unshielded token balance. This balance is fixed at the start of execution and can cause transaction failures if not managed carefully. Prefer balance comparison functions for safer operations.

```circuit
circuit unshieldedBalance(color: Bytes<32>): Uint<128>;
```

--------------------------------

### Start the proof server

Source: https://docs.midnight.network/guides/generating-dust-programmatically

Command to initialize the proof server using Docker Compose.

```bash
cd midnight-dust-tutorial  
docker compose -f proof-server.yml up
```

--------------------------------

### Main Wallet Orchestration Script

Source: https://docs.midnight.network/guides/generating-dust-programmatically

This script manages the entire wallet flow, from initial setup to ongoing DUST monitoring. It handles different scenarios based on existing tNight and DUST balances, guiding the user through necessary actions like funding, registration, and balance checks.

```javascript
const main = async () => {
  // 1. Get or create a wallet seed
  console.log('');
  const seed = await getOrCreateSeed();

  // 2. Derive HD keys
  const keys = deriveKeys(seed);

  // 3. Build the wallet
  const { wallet, unshieldedKeystore } = await withStatus('Building wallet', () => buildWallet(keys));

  // 4. Display all wallet addresses immediately (derived from keys, available before sync)
  const initialState = await Rx.firstValueFrom(wallet.state());
  const networkId = getNetworkId();

  const coinPubKey = ShieldedCoinPublicKey.fromHexString(initialState.shielded.coinPublicKey.toHexString());
  const encPubKey = ShieldedEncryptionPublicKey.fromHexString(initialState.shielded.encryptionPublicKey.toHexString());
  const shieldedAddress = MidnightBech32m.encode(networkId, new ShieldedAddress(coinPubKey, encPubKey)).toString();
  const unshieldedAddress = unshieldedKeystore.getBech32Address();
  const dustAddress = MidnightBech32m.encode(networkId, initialState.dust.address).toString();

  console.log('');
  console.log('  Wallet Addresses:');
  console.log(`    Shielded:    ${shieldedAddress}`);
  console.log(`    Unshielded:  ${unshieldedAddress}  ← send tNight here`);
  console.log(`    Dust:        ${dustAddress}`);
  console.log('');
  console.log(`  Faucet: ${CONFIG.faucetUrl}`);
  console.log('');

  // 5. Sync with the network
  await withStatus('Syncing wallet with network', () => waitForSync(wallet));

  const state = await Rx.firstValueFrom(wallet.state());
  const nightBalance = state.unshielded.balances[unshieldedToken().raw] ?? 0n;
  const dustBalance = state.dust.balance(new Date());

  // 6. Handle three scenarios based on current balances
  let usedExternalAddress = false;

  if (nightBalance > 0n && dustBalance > 0n) {
    // Scenario 3: Has both NIGHT and DUST — show balances and go to monitor
    console.log(`  tNight Balance: ${formatNight(nightBalance)}`);
    console.log(`  DUST Balance:   ${formatDust(dustBalance)}
`);
    console.log('  Your wallet is already generating DUST. No action needed.');
  } else if (nightBalance > 0n && dustBalance === 0n) {
    // Scenario 2: Has NIGHT but no DUST — register for DUST generation
    console.log(`  tNight Balance: ${formatNight(nightBalance)}`);
    console.log('  DUST Balance:   0
');
    console.log('  You have tNight but no DUST yet. Let\'s register for DUST generation.
');

    const targetDustAddress = await promptForDustAddress(dustAddress);
    usedExternalAddress = targetDustAddress !== dustAddress;
    await registerForDustGeneration(wallet, unshieldedKeystore, targetDustAddress, usedExternalAddress);
  } else {
    // Scenario 1: No NIGHT (and therefore no DUST) — wait for faucet funds
    console.log('  Waiting for tNight — copy the unshielded address above and paste it into the faucet.');
    console.log('  ⚠️  Make sure you copy only the address with no extra spaces.
');
    const balance = await withStatus('Waiting for incoming tNight', () => waitForFunds(wallet));
    console.log(`  tNight Balance: ${formatNight(balance)}
`);

    const targetDustAddress = await promptForDustAddress(dustAddress);
    usedExternalAddress = targetDustAddress !== dustAddress;
    await registerForDustGeneration(wallet, unshieldedKeystore, targetDustAddress, usedExternalAddress);
  }

  // 7. Show DUST balance and enter monitor loop
  if (usedExternalAddress) {
    console.log('');
    console.log('  DUST is being generated to the external address you designated.');
    console.log('  Because DUST is a shielded token, only the wallet holding that dust');
    console.log('  secret key can see the balance. Check the receiving wallet to verify');
    console.log('  DUST is accruing.');
  } else {
    const currentDust = await checkDustBalance(wallet);
    console.log('');
    console.log(`  DUST Balance: ${formatDust(currentDust)}`);
    console.log('  DUST generates continuously over time.');
    console.log('  Press Enter to re-check, or type "q" to quit.
');

    // 8. Let the user check the balance repeatedly
    let running = true;
    while (running) {
      const answer = await prompt('  > ');
      if (answer.toLowerCase() === 'q' || answer.toLowerCase() === 'quit' || answer.toLowerCase() === 'exit') {
        running = false;
      } else {
        const updated = await checkDustBalance(wallet);
        const time = new Date().toLocaleTimeString();

```

--------------------------------

### Nonce Management Example

Source: https://docs.midnight.network/concepts/account

Demonstrates how nonces enforce transaction ordering and prevent replay attacks in the account model. This example highlights potential issues like 'nonce too low' errors.

```Solidi
// Alice's account state
{
    address: "0xAlice...",
    balance: 100 ETH,
    nonce: 5  // Next transaction MUST use nonce 5
}

// What happens with transaction ordering:
tx1: { nonce: 5, ... }  // ✅ Processes immediately
tx2: { nonce: 7, ... }  // ❌ Must wait for nonce 6
tx3: { nonce: 6, ... }  // ⏳ Unblocks tx2 when it arrives
tx4: { nonce: 5, ... }  // ❌ Rejected - nonce already used

```

--------------------------------

### Create Project Directory

Source: https://docs.midnight.network/guides/generating-dust-programmatically

Initialize a new directory for the Midnight DUST tutorial project and navigate into it.

```bash
mkdir midnight-dust-tutorial  
cd midnight-dust-tutorial  
```

--------------------------------

### Initialize Compact Project

Source: https://docs.midnight.network/tutorials/bship/smart-contract

Commands to create the project directory structure and the initial contract file.

```bash
mkdir example-battleship && cd example-battleship  
mkdir contract && cd contract  
touch battleship.compact  
```

--------------------------------

### Install Bun Dependencies on Linux/WSL

Source: https://docs.midnight.network/how-to/bun-runtime-midnight

Before installing Bun on Linux or WSL, ensure you have the `unzip` utility installed, as it's required by the Bun installer script.

```bash
sudo apt update
sudo apt install unzip -y
```

--------------------------------

### Install Midnight Package

Source: https://docs.midnight.network/how-to/fix-package-repository-access-failures

Attempt to install the Midnight Network package to confirm successful installation.

```bash
# Verify installation  
npm install @midnight-ntwrk/compact-runtime  
```

--------------------------------

### Initialize Project Directory

Source: https://docs.midnight.network/tutorials/bboard/smart-contract

Commands to create the project root and contract source directories.

```bash
mkdir -p example-bboard/contract/src  
cd example-bboard/contract  
```

--------------------------------

### Create Hello World DApp

Source: https://docs.midnight.network/getting-started/quickstart

Use this command to scaffold the 'Hello world' DApp, which is the default template. It includes a message storage DApp and comes with dependencies pre-installed.

```bash
npx create-mn-app my-app
```

--------------------------------

### Install Compact Devtools 0.3.0

Source: https://docs.midnight.network/relnotes/compact-tools/compact-tools-0-3-0

Use this shell command to install version 0.3.0 of the Compact devtools if you do not have an existing installation.

```bash
Install version 0.3.0 using the shell command shown on the release page.
```

--------------------------------

### Install Compact Devtools

Source: https://docs.midnight.network/relnotes/compact/toolchain-0.30.0

Install the Compact devtools using curl. This command downloads and installs version 0.5.0 from the releases page.

```bash
curl https://github.com/midnightntwrk/compact/releases/tag/compact-v0.5.0
```

--------------------------------

### Verify Compact Installation

Source: https://docs.midnight.network/getting-started/installation

These commands verify that the Compact installation was successful by checking the version of Compact, the compiler version, and the installation path.

```bash
compact --version # print the version of Compact  
```

```bash
compact compile --version # print the version of the compiler  
```

```bash
which compact     # print the installation path  
```

--------------------------------

### Initialize Project Directories

Source: https://docs.midnight.network/tutorials/counter/smart-contract

Commands to create the necessary directory structure for the contract project.

```bash
mkdir -p example-counter/contract/src  
cd example-counter/contract  
```

--------------------------------

### Initialize a new Midnight project with Bun

Source: https://docs.midnight.network/how-to/bun-runtime-midnight

Use these commands to create a new project directory, navigate into it, and initialize a new project with Bun.

```bash
mkdir my-midnight-app
cd my-midnight-app
bun init -y
```

--------------------------------

### Verify Docker Installation

Source: https://docs.midnight.network/nodes/cardano-db-sync

Check the installed Docker version and its executable path. Ensure Docker is installed and accessible in your system's PATH.

```bash
docker --version # return docker version  
which docker # returns executable path  
```

--------------------------------

### Full Compact Contract Implementation

Source: https://docs.midnight.network/compact/reference/writing

A complete contract example demonstrating ledger state, constructor initialization, circuit definitions, and authorization logic using hashes.

```Compact
pragma language_version 0.22;  
  
import CompactStandardLibrary;  
  
enum State {  
  UNSET,  
  SET  
}  
  
export ledger authority: Bytes<32>;  
  
export ledger value: Uint<64>;  
  
export ledger state: State;  
  
export ledger round: Counter;  
  
constructor(sk: Bytes<32>, v: Uint<64>) {  
  authority = disclose(publicKey(round, sk));  
  value = disclose(v);  
  state = State.SET;  
}  
  
circuit publicKey(round: Field, sk: Bytes<32>): Bytes<32> {  
  return persistentHash<Vector<3, Bytes<32>>>(
           [pad(32, "midnight:examples:lock:pk"), round as Bytes<32>, sk]);  
}  
  
export circuit get(): Uint<64> {  
  assert(state == State.SET, "Attempted to get uninitialized value");  
  return value;  
}  
  
witness secretKey(): Bytes<32>;  
  
export circuit set(v: Uint<64>): [] {  
  assert(state == State.UNSET, "Attempted to set initialized value");  
  const sk = secretKey();  
  const pk = publicKey(round, sk);  
  authority = disclose(pk);  
  value = disclose(v);  
  state = State.SET;  
}  
  
export circuit clear(): [] {  
  assert(state == State.SET, "Attempted to clear uninitialized value");  
  const sk = secretKey();  
  const pk = publicKey(round, sk);  
  assert(authority == pk, "Attempted to clear without authorization");  
  state = State.UNSET;  
  round.increment(1);  
}  
```

--------------------------------

### Enable Verbose Logging for npm Install

Source: https://docs.midnight.network/how-to/fix-package-repository-access-failures

Run npm install with the --verbose flag to display detailed error information, which can help diagnose installation issues.

```bash
npm install @midnight-ntwrk/compact-runtime --verbose  
```

--------------------------------

### Install project dependencies

Source: https://docs.midnight.network/getting-started/hello-world

Installs the necessary Node.js dependencies for the project.

```bash
yarn install
```

--------------------------------

### Start testnet with Docker

Source: https://docs.midnight.network/sdks/community/build-using-meshsdk/example-integration

Initialize local testnet services using Docker Compose.

```bash
docker-compose -f testnet.yml up -d
```

--------------------------------

### Update to a Specific Compact Toolchain Version

Source: https://docs.midnight.network/compact/compilation-and-tooling/dev-tool-usage

Updates the Compact toolchain to a specific version. If the version is already installed, it confirms installation and default status. If the version is not installed, it will be downloaded.

```bash
compact update 0.26.0  

```

```bash
compact: aarch64-darwin -- 0.26.0 -- already installed  
compact: aarch64-darwin -- 0.26.0 -- default.  

```

--------------------------------

### Create Source Directory and Index File

Source: https://docs.midnight.network/guides/generating-dust-programmatically

Set up the 'src' directory and create the main script file 'src/index.ts' for the application logic.

```bash
mkdir src  
touch src/index.ts  
```

--------------------------------

### Perform Clean Installation with npm ci

Source: https://docs.midnight.network/how-to/fix-version-mismatches

Use `npm ci` instead of `npm install` for reproducible builds. This command installs exact versions from `package-lock.json` after cleaning the node_modules directory.

```bash
# Clean install from lock file
rm -rf node_modules
npm ci
```

--------------------------------

### Install Polkadot API

Source: https://docs.midnight.network/blog/query-the-blockchain

Install the required dependency to interact with Substrate-based blockchains.

```bash
npm install @polkadot/api
```

--------------------------------

### Create project directories

Source: https://docs.midnight.network/how-to/bun-runtime-midnight

Create the 'src' directory for application source code and the 'contracts' directory for smart contracts.

```bash
mkdir src contracts
```

--------------------------------

### Set up React Application Entry Point

Source: https://docs.midnight.network/guides/react-wallet-connect

Bootstrap your React application by setting up the entry point. This code configures the root element and renders the main App component within StrictMode.

```typescript
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import App from './App.tsx';

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <App />
  </StrictMode>,
);

```

--------------------------------

### Install Contract Dependencies

Source: https://docs.midnight.network/examples/dapps/bboard

Navigate to the contract directory and install its specific Node.js dependencies.

```bash
cd contract
npm install
```

--------------------------------

### Example Output for Check Command

Source: https://docs.midnight.network/blog/compact-developer-tools

Sample output showing that a new version is available or that the current version is up to date.

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

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

--------------------------------

### Install Node.js Dependencies

Source: https://docs.midnight.network/examples/dapps/bboard

Install all required Node.js packages for the contract, API, and UI components.

```bash
npm install
```

--------------------------------

### Start Proof Server with Docker

Source: https://docs.midnight.network/examples/dapps/bboard

Run the proof server locally using Docker. This server is required for deploying and interacting with contracts.

```bash
docker run -p 6300:6300 midnightntwrk/proof-server:7.0.0 -- midnight-proof-server -v
```

--------------------------------

### Install Midnight DApp Connector API

Source: https://docs.midnight.network/api-reference/dapp-connector

Install the package using the Yarn package manager.

```bash
yarn add @midnight-ntwrk/dapp-connector-api
```

--------------------------------

### Launch Bulletin Board CLI

Source: https://docs.midnight.network/examples/dapps/bboard

Navigate to the bboard-cli directory, install its dependencies, and launch the CLI on the Preprod network using the 'preprod-remote' script.

```bash
cd bboard-cli
npm install
npm run preprod-remote
```

--------------------------------

### Create Multiple Wallets in Test Environment

Source: https://docs.midnight.network/api-reference/testkit-js

Demonstrates how to create multiple wallets and verify their properties in a test environment. Ensure the test environment is started before creating wallets.

```javascript
// Example: Create multiple wallets in a test environment
const testEnvironment = getTestEnvironment(logger);
await testEnvironment.start();

// Create 2 wallets
const wallets = await testEnvironment.startMidnightWalletProviders(2);

// Verify wallet properties
expect(wallets).toHaveLength(2);
wallets.forEach(async (wallet) => {
  expect(wallet.coinPublicKey).not.toBeUndefined();
});

// Shutdown the environment after testing
await testEnvironment.shutdown();
```

--------------------------------

### Install Root Dependencies

Source: https://docs.midnight.network/tutorials/counter/counter-cli

Command to install all project dependencies from the root directory, including those for workspace packages.

```bash
npm install

```

--------------------------------

### Install Individual Midnight.js Packages

Source: https://docs.midnight.network/sdks/official/midnight-js

Install specific modular packages for granular control over SDK dependencies.

```shell
npm install @midnight-ntwrk/midnight-js-types
npm install @midnight-ntwrk/midnight-js-contracts
npm install @midnight-ntwrk/midnight-js-network-id
npm install @midnight-ntwrk/midnight-js-utils
npm install @midnight-ntwrk/midnight-js-indexer-public-data-provider
npm install @midnight-ntwrk/midnight-js-level-private-state-provider
npm install @midnight-ntwrk/midnight-js-http-client-proof-provider
npm install @midnight-ntwrk/midnight-js-fetch-zk-config-provider
npm install @midnight-ntwrk/midnight-js-node-zk-config-provider
npm install @midnight-ntwrk/midnight-js-logger-provider
npm install @midnight-ntwrk/ledger-v8
```

```shell
yarn add @midnight-ntwrk/midnight-js-types
yarn add @midnight-ntwrk/midnight-js-contracts
yarn add @midnight-ntwrk/midnight-js-network-id
yarn add @midnight-ntwrk/midnight-js-utils
yarn add @midnight-ntwrk/midnight-js-indexer-public-data-provider
yarn add @midnight-ntwrk/midnight-js-level-private-state-provider
yarn add @midnight-ntwrk/midnight-js-http-client-proof-provider
yarn add @midnight-ntwrk/midnight-js-fetch-zk-config-provider
yarn add @midnight-ntwrk/midnight-js-node-zk-config-provider
yarn add @midnight-ntwrk/midnight-js-logger-provider
yarn add @midnight-ntwrk/ledger-v8
```

--------------------------------

### Install Midnight.js Barrel Package

Source: https://docs.midnight.network/sdks/official/midnight-js

Install the primary entry point for the SDK using npm or yarn.

```shell
npm install @midnight-ntwrk/midnight-js
```

```shell
yarn add @midnight-ntwrk/midnight-js
```

--------------------------------

### Check Installed Midnight Packages

Source: https://docs.midnight.network/how-to/fix-package-repository-access-failures

List all installed packages under the @midnight-ntwrk scope to verify their presence in the project.

```bash
# Check installed packages  
npm list @midnight-ntwrk  
```

--------------------------------

### Verify Compact Installation

Source: https://docs.midnight.network/guides/windows-compact-setup

Check the installed version of the Compact compiler by running this command in your Ubuntu terminal.

```bash
compact --version  

```

--------------------------------

### Run Proof Server with Docker

Source: https://docs.midnight.network/getting-started/installation

Start the proof server as a background service using Docker. Ensure Docker Desktop is running. This command will occupy the terminal window.

```bash
docker run -p 6300:6300 midnightntwrk/proof-server:8.0.3 midnight-proof-server -v  
```

--------------------------------

### Install compact.vim with lazy.nvim

Source: https://docs.midnight.network/compact/compilation-and-tooling/neovim-setup

Use this configuration snippet to install the compact.vim plugin with the lazy.nvim package manager.

```lua
{ "1NickPappas/compact.vim" }
```

--------------------------------

### CLI Initial Connection Output

Source: https://docs.midnight.network/examples/dapps/bboard

Example output shown after launching the bulletin board CLI, indicating successful connection to the environment and services.

```text
 Starting test environment...   
 Performing env health check  
 Connected to indexer https://indexer.preprod.midnight.network/ready: ""  
 Connected to proof server http://127.0.0.1:6300/health: {"status":"ok"}  
 Environment started with configuration  
  
You can do one of the following:  
  1. Build a fresh wallet  
  2. Build wallet from a seed  
  3. Exit  
Which would you like to do?  
```

--------------------------------

### Navigate to the folder

Source: https://docs.midnight.network/sdks/community/build-using-meshsdk/example-integration

Change into the cloned repository directory.

```bash
cd midnight-setup
```

--------------------------------

### Semantic Search Example

Source: https://docs.midnight.network/blog/midnight-mcp-ai-assisted-development

Example of a natural language prompt and the corresponding search results returned by the system.

```text
Prompt: "How do I implement a token with transfer limits?"  
  
midnight-search-compact returns:  
- Token contract examples from midnight-examples  
- Rate limiting patterns from community repos  
- Relevant documentation sections  

```

--------------------------------

### Provider Setup

Source: https://docs.midnight.network/sdks/community/build-using-meshsdk/core-api-methods

Initializes the required providers for interacting with the Midnight Network.

```APIDOC
### Request Example
```javascript
import { setupProviders } from './lib/providers';

const providers = await setupProviders();
// Returns: MidnightSetupContractProviders
```
```

--------------------------------

### GET /health

Source: https://docs.midnight.network/api-reference/testkit-js/classes/ProofServerClient

Checks the health status of the indexer service by making a GET request to the status endpoint.

```APIDOC
## GET /health

### Description
Checks the health status of the indexer service. Makes a GET request to the status endpoint of the indexer service.

### Method
GET

### Response
#### Success Response (200)
- **response** (AxiosResponse) - The response object from the health check request.
```

--------------------------------

### connect() Method

Source: https://docs.midnight.network/api-reference/dapp-connector/type-aliases/InitialAPI

Initiates a connection to the wallet, optionally specifying the desired network.

```APIDOC
## POST /connect

### Description
Initiates a connection to the wallet. DApps can hint at the desired network for the connection.

### Method
POST

### Endpoint
`/connect`

### Parameters

#### Query Parameters

- **networkId** (string) - Optional - The identifier for the desired network (e.g., 'mainnet').

### Request Body

This method does not require a request body.

### Response

#### Success Response (200)
- **ConnectedAPI** (object) - An object representing the established connection, providing further interaction methods.

#### Response Example
```json
{
  "status": "connected",
  "data": { /* ConnectedAPI object details */ }
}
```
```

--------------------------------

### Verify WSL installation

Source: https://docs.midnight.network/guides/windows-compact-setup

Checks the status and version of installed WSL distributions to ensure WSL 2 is active.

```bash
wsl -l -v  
```

--------------------------------

### Main CLI Script for Contract Connection

Source: https://docs.midnight.network/guides/interact-with-mn-app

This script handles loading deployment details, creating a wallet, and connecting to a deployed contract. It validates the existence of 'deployment.json', prompts for a wallet seed, and synchronizes the wallet with the Preprod environment before connecting to the contract.

```typescript
// ─── Main CLI Script ───────────────────────────────────────────────────────────  
  
async function main() {  
  console.log('\n╔══════════════════════════════════════════════════════════╗');  
  console.log('║           Hello World Contract CLI (Preprod)            ║');  
  console.log('╚══════════════════════════════════════════════════════════╝\n');  
  
  // Check for deployment.json  
  if (!fs.existsSync('deployment.json')) {  
    console.error('No deployment.json found! Run `npm run deploy` first.\n');  
    process.exit(1);  
  }  
  
  const deployment = JSON.parse(fs.readFileSync('deployment.json', 'utf-8'));  
  console.log(`  Contract: ${deployment.contractAddress}\n`);  
  
  const rl = createInterface({ input: stdin, output: stdout });  
  
  try {  
    // Get wallet seed  
    const seed = await rl.question('  Enter your wallet seed: ');  
  
    console.log('\n  Connecting to Midnight Preprod...');  
    const walletCtx = await createWallet(seed.trim());  
  
    console.log('  Syncing wallet...');  
    await Rx.firstValueFrom(  
      walletCtx.wallet.state().pipe(  
        Rx.throttleTime(5000),   
        Rx.filter((s) => s.isSynced)  
      )  
    );  
  
    console.log('  Setting up providers...');  
    const providers = await createProviders(walletCtx);  
  
    console.log('  Joining contract...');  
    const contract = await findDeployedContract(providers, {  
      contractAddress: deployment.contractAddress,  
      compiledContract,  
      privateStateId: 'helloWorldState',  
      initialPrivateState: {},  
    });  
  
    console.log('  Connected!\n');  

```

--------------------------------

### startWalletFacade

Source: https://docs.midnight.network/api-reference/testkit-js/classes/WalletFactory

Starts a wallet facade with the provided wallet instance and seeds.

```APIDOC
## POST /api/wallets/start/facade

### Description
Starts a wallet facade with the provided wallet instance, shielded seed, and dust seed.

### Method
POST

### Endpoint
`/api/wallets/start/facade`

### Parameters
#### Request Body
- **wallet** (WalletFacade) - Required - The wallet facade instance.
- **shieldedSeed** (Uint8Array) - Required - The seed for the shielded wallet.
- **dustSeed** (Uint8Array) - Required - The seed for the dust wallet.

### Request Example
```json
{
  "wallet": { ... },
  "shieldedSeed": "0x...",
  "dustSeed": "0x..."
}
```

### Response
#### Success Response (200)
- **WalletFacade** (Promise<WalletFacade>) - A promise that resolves to the started wallet facade.

#### Response Example
```json
{
  "walletFacade": { ... }
}
```
```

--------------------------------

### Install Dependencies with Bun

Source: https://docs.midnight.network/how-to/bun-runtime-midnight

After cleaning npm artifacts, install your project's dependencies using the Bun package manager.

```bash
bun install
```
Tokens:
Raw