@kuiralabs/midnight-chain

Read-only network access for the Midnight CLI packages: whether a node, an indexer and a proof server are ready, the chain's id, time and tip, its events, the ledger version a chain runs (and the guard that refuses one this build doesn't support), and a transaction's status and receipt. It holds no wallet and sends nothing.

Install

npm install @kuiralabs/midnight-cli-core @kuiralabs/midnight-chain @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-chain | The functions below, and the errors they throw | | @kuiralabs/midnight-chain/commands | tx (and status, refused while it is reworked) as a registry entry (chainCommands), its codes (chainCodes) |

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

What you call

• transactionStatus, receiptOf, receiptJson: where a transaction is (pending, in a block, failed) and its receipt.
• waitForFirstBlock, waitForProofServerReady, assertNetworkAnswers: wait for or check a network's services.
• fetchProtocolVersion, assertLedgerSupported, walletsBelowLedger: the ledger a chain runs.
• getChainGenesisHash, fetchChainTime, assertChainClockCurrent, fetchEventTip: the chain's id, time and tip.
• queryIndexer, subscribeGraphqlWs, callNodeRpc: the indexer's GraphQL and the node's RPC, with their failures typed.

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 | |------|------|-----------------|------------| | CHAIN_CLOCK_BEHIND | 4 | The chain's clock lags this computer's (a local chain after sleep), so Dust estimates don't hold. | Wait for it to catch up, or ask the user to restart the local chain. | | UNSUPPORTED_LEDGER | 4 | The chain is still on ledger 8; mn supports ledger 9 only. | Don't retry. Every public network runs ledger 9, so it is a local stack on an older ledger: ask the user to restart or upgrade it (midnight localnet down, then midnight localnet up, starts a ledger-9 one). | | LOCAL_STACK_UNREACHABLE | 4 | No ledger-9 stack answers at the configured endpoints. | Ask the user to start their stack or fix the configured node / indexer-ws / proof-server endpoints. |

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 chain's tx command:

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

const registry = createPackageRegistry([coreCommands, chainCommands], []);
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 tx status <hash> --network preview prints where the transaction is. With an indexer that doesn't answer, it ends with NETWORK_ERROR and exit code 4. A test in mn runs the block above as it is written.