@kuiralabs/midnight-grant

Grants for the Midnight CLI packages: mn grant, the wallet owner's side of an account (@kuiralabs/midnight-account-chain) and the grants that let an agent spend from it, its owner devices and backups; and the protector wallet protect seals the accounts' records with. The account package runs through the loaded engine, on the SDK set the engine installs.

Install

npm install @kuiralabs/midnight-cli-core @kuiralabs/midnight-wallet @kuiralabs/midnight-grant @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-grant | accountProtector, the account records, and the errors grant throws | | @kuiralabs/midnight-grant/commands | grant as a registry entry (grantCommands), its codes (grantCodes) |

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

What you call

• accountProtector: pass it as a protector so wallet protect also seals the accounts' records.
• accountRecordsDir, accountArtifactsDir: where an account's records and its contract's keys are kept under your state root.

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_ACCOUNT | 1 | A grant command (midnight_grant_* tool) was called for a wallet that has no account on this network. | Offer midnight_grant_deploy(), after telling the user how its owner key is kept (see the allowance flow). | | ACCOUNT_KEYS_UNAVAILABLE | 1 | A proving key of the account contract couldn't be had: the installed account build's keys are not published (HTTP 404), or fetching them failed. Nothing was submitted. | Show the message: it names the key, the build and where it was fetched from. Not published: tell the user mn grant needs an mn release whose account keys are published, or a local build of the account contract given with midnight config set account-artifacts <folder> (or MN_ACCOUNT_ARTIFACTS); don't retry. A file the source has that is not this build's: the source is another build; ask the user for the right one. A failed fetch: retry once. |

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 grant beside the wallet's commands, connect's payer for the account's transactions, and the protector wallet protect seals the accounts with:

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

const registry = createPackageRegistry([coreCommands, chainCommands, walletCommands, contractCommands, grantCommands], []);
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, protectors: [accountProtector] });
  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 grant list --wallet alice --network preview lists alice's grants; for a wallet with no account on that network it ends with NO_ACCOUNT and exit code 1. A test in mn runs the block above as it is written.