@kuiralabs/midnight-contract

Contracts for the Midnight CLI packages: deploying, calling and reading a Compact contract from its dApp folder, the requests a deploy or a call is built from, a compiled contract's circuits and witnesses, and the chain's block limits. A deploy or a call is proved and paid through a payer you pass (connect's servePayer, which runs it through mn serve); its contract script runs under Node.js, also when your program runs under bun.

Install

npm install @kuiralabs/midnight-cli-core @kuiralabs/midnight-contract @kuiralabs/midnight-connect @kuiralabs/midnight-engine-rc

Install with npm 11 or older (npm 12 no longer reads a package's shrinkwrap): the engine ships an npm-shrinkwrap.json that pins its SDK set, and npm 11 honours it. A program that runs the SDK installs the engine, @kuiralabs/midnight-engine-rc, for every network. How a program sets up its process for the SDK (the rejection guard, the heap, Ctrl-C, ending) is in core's README.

Entry points

| Import | What it holds | |---|---| | @kuiralabs/midnight-contract | The functions below, and the errors they throw (ContractNotCompiledError among them) | | @kuiralabs/midnight-contract/commands | contract (inspect, deploy, call, state) and inspect-cost as a registry entry (contractCommands), its codes (contractCodes) |

Every export and its signature is in api-report.md.

What you call

• deployContract, callContract: deploy or call a compiled contract, paid by the payer you pass; they return receipts.
• readContractState, contractExists: a deployed contract's state.
• findContractInfo: a compiled contract's circuits and witnesses, from its managed/ folder.
• contractDeployRequest, contractCallRequest: the requests a deploy or a call is built from, without sending them.

Codes

Each error carries a code, and classifyError(err, registry) gives its code and exit code by that code alone, never by its message. These are the codes this package owns; the rest come from core and the packages below it, each listed in its README.

| Code | Exit | What went wrong | What to do | |------|------|-----------------|------------| | NO_NODE_RUNTIME | 1 | Contract scripts run under Node.js, and none was found on PATH. | Ask the user to install Node.js 22 or later, or to run mn under Node. | | CONTRACT_NOT_COMPILED | 1 | No compiled contract was found where the command looked (managed//compiler/contract-info.json). | Ask the user to compile the contract (compact compile), or pass the dApp folder (path) or the managed folder (managed). | | CONTRACT_INFO_INVALID | 1 | A compiled contract's contract-info.json is not what the Compact compiler writes (not JSON, or its circuits or witnesses missing or malformed). | The message names what is wrong: ask the user to compile the contract again (compact compile). | | CONTRACT_STATE_BUSY | 1 | A contract's private-state store stayed in use by another process (another mn running a call of the same contract) for the 3 minutes a call waits for it. The message names the contract and, when it is an mn, its pid and command. | Let the other mn finish, or stop it if it is stuck. A call reads the store before it submits and writes it after, so read the contract state (midnight_contract_state) to see whether the call landed before retrying it. | | CONTRACT_ASSERTION_FAILED | 2 | A Compact assert in the circuit called (or in the constructor, for a deploy) failed while the contract ran on this machine, before anything was proven or sent. The message names the contract, the circuit and the assert's own text (e.g. "Still locked"). | Nothing was sent or paid. Tell the user the contract refused the call and why, in the assert's words. Don't retry the same call: change its arguments, or wait until the contract's state allows it (a time lock, another party's step). | | WITNESSES_NOT_FOUND | 1 | The contract declares witnesses and the dApp has no compiled witnesses module (dist/witnesses.js or one of the other places the message lists). | Ask the user to build the witnesses (e.g. npm run build) so a witnesses.js exists, then retry; nothing was sent. | | CONTRACT_NOT_FOUND | 2 | No contract is deployed at the address on this network. | Check the address and the network (a contract deployed on another network, or on a local chain that was reset, is not there). |

Mounting its commands

The commands are definitions your program mounts in its own command line, with your state root, settings and notices (core's README explains each part). Its commands name codes the packages it builds on own, so the registry holds their entries too, as mn's does; a registry missing one is refused when it is built. Built on core's example, this one adds the contract commands, and connect's payer for the deploys and calls:

import { homedir } from 'node:os';
import { join } from 'node:path';
import { classifyError, createHost, createPackageRegistry, parseArgs, runCommand, settingsFromEnvironment, UsageError } from '@kuiralabs/midnight-cli-core';
import { coreCommands } from '@kuiralabs/midnight-cli-core/commands';
import { chainCommands } from '@kuiralabs/midnight-chain/commands';
import { walletCommands } from '@kuiralabs/midnight-wallet/commands';
import { contractCommands } from '@kuiralabs/midnight-contract/commands';
import { servePayer } from '@kuiralabs/midnight-connect';
import { createRcEngine } from '@kuiralabs/midnight-engine-rc';

const registry = createPackageRegistry([coreCommands, chainCommands, walletCommands, contractCommands], []);
const host = createHost({
  paths: { stateRoot: join(homedir(), '.my-app'), home: homedir() },
  settings: () => settingsFromEnvironment(process.env),
  notice: (line) => console.error(line),
  engineLoader: async (_set, host) => createRcEngine(host),
});
const output = { result: (data) => console.log(JSON.stringify(data)), stdout: (text) => process.stdout.write(text), stderr: (text) => process.stderr.write(text) };

const args = parseArgs(process.argv.slice(2));
try {
  const definition = registry.find(args.command ?? '');
  if (definition === undefined) throw new UsageError(`Unknown command: ${args.command}`);
  const outcome = await runCommand(definition, args, { host, output, payer: servePayer });
  process.exitCode = outcome?.exitCode ?? 0;
} catch (err) {
  const { errorCode, exitCode } = classifyError(err, registry);
  console.error(`${errorCode}: ${err.message}`);
  process.exitCode = exitCode;
}

node my-cli.mjs contract inspect --path ./my-dapp lists the compiled contract's circuits; in a folder with no compiled contract it ends with CONTRACT_NOT_COMPILED and exit code 1. A test in mn runs the block above as it is written.