@kuiralabs/midnight-connect

mn serve for the Midnight CLI packages: the DApp connector API over a local WebSocket JSON-RPC server, the serve manager that starts one or reuses one already running, and the payer that pays a command through it. A command that pays (contract, swap, grant, dev) takes this payer.

Install

npm install @kuiralabs/midnight-cli-core @kuiralabs/midnight-wallet @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-connect | The payer (servePayer, servePayerAt), the serve manager and the RPC server | | @kuiralabs/midnight-connect/commands | serve as a registry entry (connectCommands), its codes (connectCodes) |

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

What you call

• servePayer: the payer that pays through a running mn serve for the wallet and network asked, starting one when none runs; servePayerAt for one at a given port.
• startServeOrReuse, probeServeNetwork: start or find a server.
• createRpcServer: the JSON-RPC server itself, over handlers you give.

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 | |------|------|-----------------|------------| | SERVE_PORT_IN_USE | 1 | The port mn serve was to use is taken by a process that can't serve this command (another program, or an mn serve for another network, chain or wallet). | The message names the port and how to find the process on it: ask the user to stop that process, or run on another port. | | APPROVAL_UNAVAILABLE | 1 | A request to mn serve needed approval and nobody could be asked: the serve has no terminal and was not started to approve it without asking. | Ask the user to restart mn serve with --approve-all (or --approve-fees for a wallet that only pays an agent's Dust fee), or to run it at a terminal. |

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 serve beside the wallet's commands, which make the wallet it serves:

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 { connectCommands } from '@kuiralabs/midnight-connect/commands';
import { createRcEngine } from '@kuiralabs/midnight-engine-rc';

const registry = createPackageRegistry([coreCommands, chainCommands, walletCommands, connectCommands], []);
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 });
  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 serve --wallet alice --network preview serves alice's wallet until it is stopped; for a wallet that doesn't exist it ends with WALLET_NOT_FOUND and exit code 3. A test in mn runs the block above as it is written.