@leofcoin/launch-chain 0.4.20 → 0.4.22

package/README.md

@@ -17,6 +17,74 @@ const { chain, endpoints, mode } = await launch(
 // when mode is direct means chain is directly available and no endpoint is needed to interact with it
 ```
 
+## command line
+
+No monorepo checkout or global install is required:
+
+```sh
+npx --package @leofcoin/launch-chain leofcoin --help
+```
+
+Run a normal syncing full node with HTTP and WebSocket endpoints:
+
+```sh
+npx --package @leofcoin/launch-chain leofcoin node
+```
+
+The same CLI exposes `node`, `validator`, `account`, `balance`, `status`, and
+`transfer` commands. `node` never registers as a validator. Only the explicit
+`validator` command checks validator eligibility and starts participation.
+
+## run a validator
+
+No monorepo checkout is required. Run the validator directly from the published package:
+
+```sh
+npx --package @leofcoin/launch-chain leofcoin validator
+```
+
+The first run uses the normal interactive identity-password prompt. A new account must receive
+the validator contract's minimum balance before it can register. An existing validator must be
+online to finalize that registration transaction.
+
+For an unattended server, keep the password outside the repository in a mode-`0600` file:
+
+```sh
+npx --package @leofcoin/launch-chain leofcoin-validator \
+  --password-file /secure/leofcoin/password \
+  --root /var/lib/leofcoin/peach \
+  --interval 5
+```
+
+The validator also exposes the HTTP API on port `8080` and WebSocket API on port `4040`, so one
+process can replace a separate launch-chain server. Change them with `--http-port` and `--ws-port`,
+or use `--no-endpoints` for a validator that should not expose an API.
+
+Never put the password or an identity backup in a command-line argument, service file, or Git.
+The legacy `leofcoin-validator` command remains an alias for `leofcoin validator`.
+Use `leofcoin --help` for all commands and options.
+
+### send LFC from the local validator
+
+When the validator runs in a terminal it exposes a local wallet shell. Private keys never leave
+the process:
+
+```text
+leofcoin> account
+leofcoin> balance
+leofcoin> transfer YTq... 1000
+```
+
+When the node is stopped, a one-shot transfer can start the same local identity,
+finalize the transfer, and exit. It does not register or participate as a validator:
+
+```sh
+npx --package @leofcoin/launch-chain leofcoin transfer YTq... 1000 \
+  --password-file /secure/leofcoin/password
+```
+
+Do not run the daemon and one-shot command simultaneously against the same data root.
+
 ## options
 
 ### default

package/exports/cli-options.d.ts

@@ -0,0 +1,14 @@
+export type CliCommand = 'node' | 'validator' | 'account' | 'balance' | 'status' | 'transfer' | 'help' | 'version';
+export type CliOptions = {
+    command: CliCommand;
+    positionals: string[];
+    network?: string;
+    root?: string;
+    passwordFile?: string;
+    intervalMinutes?: number;
+    httpPort: number | false;
+    wsPort: number | false;
+    shell: boolean;
+    stars?: string[];
+};
+export declare const parseCliOptions: (args: string[]) => CliOptions;

package/exports/cli-options.js

@@ -0,0 +1,66 @@
+const commands = new Set(['node', 'validator', 'account', 'balance', 'status', 'transfer', 'help', 'version']);
+const port = (name, value) => {
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed < 1 || parsed > 65_535)
+        throw new Error(`${name} must be a valid port`);
+    return parsed;
+};
+const parseCliOptions = (args) => {
+    let command;
+    const positionals = [];
+    const stars = [];
+    const options = { command: 'help', positionals, httpPort: 8080, wsPort: 4040, shell: true };
+    const value = (index, name) => {
+        const result = args[index + 1];
+        if (!result || result.startsWith('-'))
+            throw new Error(`${name} requires a value`);
+        return result;
+    };
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === '-h' || argument === '--help')
+            command = 'help';
+        else if (argument === '-v' || argument === '--version')
+            command = 'version';
+        else if (argument === '--network')
+            options.network = value(index++, argument);
+        else if (argument === '--root')
+            options.root = value(index++, argument);
+        else if (argument === '--password-file')
+            options.passwordFile = value(index++, argument);
+        else if (argument === '--interval') {
+            options.intervalMinutes = Number(value(index++, argument));
+            if (!Number.isFinite(options.intervalMinutes) || options.intervalMinutes < 1)
+                throw new Error('--interval must be at least one minute');
+        }
+        else if (argument === '--http-port')
+            options.httpPort = port(argument, value(index++, argument));
+        else if (argument === '--ws-port')
+            options.wsPort = port(argument, value(index++, argument));
+        else if (argument === '--no-endpoints') {
+            options.httpPort = false;
+            options.wsPort = false;
+        }
+        else if (argument === '--no-shell')
+            options.shell = false;
+        else if (argument === '--star')
+            stars.push(value(index++, argument));
+        else if (argument === '--no-stars')
+            options.stars = [];
+        else if (argument.startsWith('-'))
+            throw new Error(`unknown option: ${argument}`);
+        else if (!command) {
+            if (!commands.has(argument))
+                throw new Error(`unknown command: ${argument}`);
+            command = argument;
+        }
+        else
+            positionals.push(argument);
+    }
+    options.command = command ?? 'help';
+    if (stars.length > 0)
+        options.stars = stars;
+    return options;
+};
+
+export { parseCliOptions };

package/exports/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export declare const help = "Leofcoin command line\n\nUsage:\n  leofcoin node [options]                     Run a normal full node\n  leofcoin validator [options]                Run a validator node\n  leofcoin account [options]                  Show the local account\n  leofcoin balance [address] [options]        Show an LFC balance\n  leofcoin status [options]                   Show local chain status\n  leofcoin transfer <address> <LFC> [options] Send LFC and await finalization\n\nOptions:\n  --network <name>        Network (default: leofcoin:peach)\n  --root <path>           Persistent data directory\n  --password-file <path>  Read the identity password from a private file\n  --star <url>            Discovery star; repeat for multiple stars\n  --no-stars              Disable discovery stars\n  --http-port <port>      HTTP API port (default: 8080)\n  --ws-port <port>        WebSocket API port (default: 4040)\n  --no-endpoints          Disable HTTP and WebSocket endpoints\n  --no-shell              Disable the interactive wallet shell\n  --interval <minutes>    Validator heartbeat interval (default: 5)\n  -h, --help              Show help\n  -v, --version           Show version\n\nPasswords are never accepted as command-line values. Use --password-file,\nLEOFCOIN_PASSWORD_FILE, LEOFCOIN_PASSWORD, or the interactive password prompt.\n";
+export declare const runCli: (args?: string[]) => Promise<undefined>;

package/exports/cli.js

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { resolve, isAbsolute, relative } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createInterface } from 'node:readline/promises';
+import { parseCliOptions } from './cli-options.js';
+import { startNode } from './node.js';
+import { startValidator } from './validator.js';
+import '@leofcoin/lib';
+import '@leofcoin/networks';
+import './index.js';
+import '@leofcoin/chain/node';
+import '@leofcoin/chain/chain';
+import '@leofcoin/lib/node-config';
+import '@leofcoin/endpoint-clients/ws';
+import '@leofcoin/endpoint-clients/http';
+import '@leofcoin/addresses';
+
+const help = `Leofcoin command line
+
+Usage:
+  leofcoin node [options]                     Run a normal full node
+  leofcoin validator [options]                Run a validator node
+  leofcoin account [options]                  Show the local account
+  leofcoin balance [address] [options]        Show an LFC balance
+  leofcoin status [options]                   Show local chain status
+  leofcoin transfer <address> <LFC> [options] Send LFC and await finalization
+
+Options:
+  --network <name>        Network (default: leofcoin:peach)
+  --root <path>           Persistent data directory
+  --password-file <path>  Read the identity password from a private file
+  --star <url>            Discovery star; repeat for multiple stars
+  --no-stars              Disable discovery stars
+  --http-port <port>      HTTP API port (default: 8080)
+  --ws-port <port>        WebSocket API port (default: 4040)
+  --no-endpoints          Disable HTTP and WebSocket endpoints
+  --no-shell              Disable the interactive wallet shell
+  --interval <minutes>    Validator heartbeat interval (default: 5)
+  -h, --help              Show help
+  -v, --version           Show version
+
+Passwords are never accepted as command-line values. Use --password-file,
+LEOFCOIN_PASSWORD_FILE, LEOFCOIN_PASSWORD, or the interactive password prompt.
+`;
+const packageVersion = async () => {
+    const manifest = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+    return manifest.version;
+};
+const passwordFor = async (passwordFile) => {
+    const file = passwordFile ?? process.env.LEOFCOIN_PASSWORD_FILE;
+    if (!file)
+        return process.env.LEOFCOIN_PASSWORD;
+    const password = (await readFile(resolve(file), 'utf8')).trim();
+    if (!password)
+        throw new Error(`empty identity password file: ${resolve(file)}`);
+    return password;
+};
+// @leofcoin/storage resolves its root below the home directory. Convert an
+// absolute CLI path to the equivalent home-relative path before it reaches the
+// storage layer, so `--root /var/lib/leofcoin` remains truly absolute.
+const dataRootFor = (root) => root && isAbsolute(root) ? relative(homedir(), root) : root;
+const amountFor = (chain, value) => {
+    if (!value)
+        throw new Error('transfer amount is required');
+    try {
+        const amount = BigInt(chain.utils.parseUnits(value));
+        if (amount <= 0n)
+            throw new Error();
+        return amount;
+    }
+    catch {
+        throw new Error('transfer amount must be a positive LFC amount');
+    }
+};
+const showStatus = async (handle) => {
+    const chain = handle.chain;
+    const lastBlock = await chain.lastBlock;
+    const balance = await chain.balanceOf(handle.account);
+    process.stdout.write(`network: ${chain.network ?? 'leofcoin'}\n`);
+    process.stdout.write(`account: ${handle.account}\n`);
+    process.stdout.write(`balance: ${chain.utils.formatUnits(balance)} LFC\n`);
+    process.stdout.write(`height: ${lastBlock?.index ?? 'unknown'}\n`);
+    for (const url of handle.endpoints.http)
+        process.stdout.write(`http: ${url}\n`);
+    for (const url of handle.endpoints.ws)
+        process.stdout.write(`ws: ${url}\n`);
+};
+const runShell = async (handle) => {
+    const shell = createInterface({ input: process.stdin, output: process.stdout });
+    const chain = handle.chain;
+    process.stdout.write('wallet shell ready; type help for commands\n');
+    while (true) {
+        const [command, ...values] = (await shell.question('leofcoin> ')).trim().split(/\s+/);
+        try {
+            if (!command)
+                continue;
+            if (command === 'account')
+                process.stdout.write(`${handle.account}\n`);
+            else if (command === 'balance') {
+                const balance = await chain.balanceOf(values[0] ?? handle.account);
+                process.stdout.write(`${chain.utils.formatUnits(balance)} LFC\n`);
+            }
+            else if (command === 'status')
+                await showStatus(handle);
+            else if (command === 'transfer') {
+                const hash = await handle.transfer(values[0], amountFor(chain, values[1]));
+                process.stdout.write(`transfer finalized: ${hash}\n`);
+            }
+            else if (command === 'help') {
+                process.stdout.write('account | balance [address] | status | transfer <address> <LFC> | exit\n');
+            }
+            else if (command === 'exit' || command === 'quit') {
+                shell.close();
+                break;
+            }
+            else
+                process.stderr.write(`unknown command: ${command}\n`);
+        }
+        catch (error) {
+            process.stderr.write(`${error?.message ?? error}\n`);
+        }
+    }
+};
+const runCli = async (args = process.argv.slice(2)) => {
+    const options = parseCliOptions(args);
+    if (options.command === 'help')
+        return void process.stdout.write(help);
+    if (options.command === 'version')
+        return void process.stdout.write(`${await packageVersion()}\n`);
+    const common = {
+        network: options.network ?? process.env.LEOFCOIN_NETWORK,
+        root: dataRootFor(options.root ?? process.env.LEOFCOIN_DATA_ROOT),
+        password: await passwordFor(options.passwordFile),
+        stars: options.stars,
+        httpPort: options.httpPort,
+        wsPort: options.wsPort
+    };
+    const handle = options.command === 'validator'
+        ? await startValidator({ ...common, intervalMinutes: options.intervalMinutes })
+        : await startNode(common);
+    const nodeHandle = handle;
+    const chain = nodeHandle.chain;
+    const shutdown = (signal) => {
+        process.stdout.write(`received ${signal}; stopping node\n`);
+        nodeHandle.stop();
+        setTimeout(() => process.exit(0), 100);
+    };
+    process.once('SIGINT', () => shutdown('SIGINT'));
+    process.once('SIGTERM', () => shutdown('SIGTERM'));
+    if (options.command === 'account')
+        process.stdout.write(`${nodeHandle.account}\n`);
+    else if (options.command === 'balance') {
+        const balance = await chain.balanceOf(options.positionals[0] ?? nodeHandle.account);
+        process.stdout.write(`${chain.utils.formatUnits(balance)} LFC\n`);
+    }
+    else if (options.command === 'status')
+        await showStatus(nodeHandle);
+    else if (options.command === 'transfer') {
+        const to = options.positionals[0];
+        if (!to)
+            throw new Error('transfer recipient is required');
+        const hash = await nodeHandle.transfer(to, amountFor(chain, options.positionals[1]));
+        process.stdout.write(`transfer finalized: ${hash}\n`);
+    }
+    else {
+        process.stdout.write(`${options.command} account: ${nodeHandle.account}\n`);
+        if (options.shell && process.stdin.isTTY)
+            await runShell(nodeHandle);
+        else
+            return;
+    }
+    nodeHandle.stop();
+    // Peernet and endpoint servers currently expose no shared async close API.
+    // Give pending output a moment to flush, then make one-shot commands and an
+    // explicitly closed interactive shell terminate predictably.
+    setTimeout(() => process.exit(0), 100);
+};
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    runCli().catch((error) => {
+        process.stderr.write(`leofcoin: ${error?.message ?? error}\n`);
+        process.exitCode = 1;
+    });
+}
+
+export { help, runCli };

package/exports/index.d.ts

@@ -26,6 +26,7 @@ type launchOptions = {
     stars?: string[];
     forceRemote?: boolean;
     mode?: launchMode;
+    root?: string;
     ws?: endpointOptions[] | undefined;
     http?: endpointOptions[] | undefined;
 };
@@ -34,5 +35,5 @@ type launchOptions = {
  * @param {object} options { ws: boolean || {url: string, port: number}, http: boolean || {url: string, port: number}, network}
  * @returns '{ mode: string, endpoints: object, chain}'
  */
-declare const launch: (input: launchOptions | undefined, password: string) => Promise<launchReturn>;
+declare const launch: (input?: launchOptions, password?: string) => Promise<launchReturn>;
 export { launch as default };

package/exports/index.js

@@ -11,6 +11,7 @@ const defaultOptions = {
     stars: networks.leofcoin.peach.stars,
     forceRemote: false,
     mode: 'direct',
+    root: undefined,
     ws: [
         {
             port: 4040
@@ -108,7 +109,7 @@ const launch = async (input = {}, password) => {
             throw new Error(`no remotes connected`);
     }
     else if (options.mode === 'direct') {
-        const node = new Node({ network: options.network, stars: options.stars, networkVersion: options.networkVersion }, password);
+        const node = new Node({ network: options.network, stars: options.stars, networkVersion: options.networkVersion, root: options.root }, password);
         await node.ready;
         await nodeConfig({ network: options.network, networkVersion: options.networkVersion });
         chain = new Chain({ network: options.network, stars: options.stars, networkVersion: options.networkVersion });
@@ -137,7 +138,7 @@ const launch = async (input = {}, password) => {
         }
     }
     else {
-        const node = new Node({ network: options.network, stars: options.stars, networkVersion: options.networkVersion }, password);
+        const node = new Node({ network: options.network, stars: options.stars, networkVersion: options.networkVersion, root: options.root }, password);
         await node.ready;
         await nodeConfig({ network: options.network, networkVersion: options.networkVersion });
         chain = new Chain({ network: options.network, stars: options.stars, networkVersion: options.networkVersion });

package/exports/node.d.ts

@@ -0,0 +1,22 @@
+import Chain from '@leofcoin/chain/chain';
+export type LocalNodeOptions = {
+    network?: string;
+    networkVersion?: string;
+    stars?: string[];
+    root?: string;
+    password?: string;
+    httpPort?: number | false;
+    wsPort?: number | false;
+    signal?: AbortSignal;
+};
+export type LocalNodeHandle = {
+    account: string;
+    chain: Chain;
+    endpoints: {
+        http: string[];
+        ws: string[];
+    };
+    transfer: (to: string, amount: bigint) => Promise<string>;
+    stop: () => void;
+};
+export declare const startNode: (options?: LocalNodeOptions) => Promise<LocalNodeHandle>;

package/exports/node.js

@@ -0,0 +1,53 @@
+import { signTransaction } from '@leofcoin/lib';
+import networks from '@leofcoin/networks';
+import launch from './index.js';
+import '@leofcoin/chain/node';
+import '@leofcoin/chain/chain';
+import '@leofcoin/lib/node-config';
+import '@leofcoin/endpoint-clients/ws';
+import '@leofcoin/endpoint-clients/http';
+
+const startNode = async (options = {}) => {
+    const network = options.network ?? 'leofcoin:peach';
+    const networkVersion = options.networkVersion ?? network.split(':')[1] ?? 'peach';
+    const stars = options.stars ?? networks.leofcoin.peach.stars;
+    const controller = new AbortController();
+    options.signal?.addEventListener('abort', () => controller.abort(options.signal?.reason), { once: true });
+    const launched = await launch({
+        mode: 'direct', network, networkVersion, stars, root: options.root,
+        http: options.httpPort === false ? [] : [{ port: options.httpPort ?? 8080 }],
+        ws: options.wsPort === false ? [] : [{ port: options.wsPort ?? 4040 }]
+    }, options.password);
+    if (!launched.chain)
+        throw new Error('node launch did not create a direct chain runtime');
+    const chain = launched.chain;
+    const chainRuntime = chain;
+    const peernet = globalThis.peernet;
+    const account = peernet?.selectedAccount;
+    if (!account)
+        throw new Error('node identity has no selected account');
+    const transfer = async (to, amount) => {
+        if (!to)
+            throw new Error('transfer recipient is required');
+        if (amount <= 0n)
+            throw new Error('transfer amount must be greater than zero');
+        const balance = BigInt(await chainRuntime.balanceOf(account));
+        if (balance < amount)
+            throw new Error(`insufficient balance: have ${balance}, need at least ${amount}`);
+        const raw = await chainRuntime.createTransaction({
+            from: account, to: chain.nativeToken, method: 'transfer', params: [to, amount]
+        });
+        const signed = await signTransaction(raw, peernet.identity);
+        const pending = await chainRuntime.sendTransaction(signed);
+        return pending.wait;
+    };
+    return {
+        account,
+        chain,
+        endpoints: launched.endpoints,
+        transfer,
+        stop: () => controller.abort(new Error('node stopped'))
+    };
+};
+
+export { startNode };

package/exports/validator-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/exports/validator-cli.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import { runCli } from './cli.js';
+import 'node:fs/promises';
+import 'node:os';
+import 'node:path';
+import 'node:url';
+import 'node:readline/promises';
+import './cli-options.js';
+import './node.js';
+import '@leofcoin/lib';
+import '@leofcoin/networks';
+import './index.js';
+import '@leofcoin/chain/node';
+import '@leofcoin/chain/chain';
+import '@leofcoin/lib/node-config';
+import '@leofcoin/endpoint-clients/ws';
+import '@leofcoin/endpoint-clients/http';
+import './validator.js';
+import '@leofcoin/addresses';
+
+runCli(['validator', ...process.argv.slice(2)]).catch((error) => {
+    process.stderr.write(`leofcoin-validator: ${error?.message ?? error}\n`);
+    process.exitCode = 1;
+});

package/exports/validator.d.ts

@@ -0,0 +1,27 @@
+import Chain from '@leofcoin/chain/chain';
+export type ValidatorOptions = {
+    network?: string;
+    networkVersion?: string;
+    stars?: string[];
+    root?: string;
+    password?: string;
+    intervalMinutes?: number;
+    registrationTimeoutMs?: number;
+    httpPort?: number | false;
+    wsPort?: number | false;
+    heartbeat?: boolean;
+    signal?: AbortSignal;
+    logger?: Pick<Console, 'log' | 'warn' | 'error'>;
+};
+export type ValidatorHandle = {
+    account: string;
+    chain: Chain;
+    endpoints: {
+        http: string[];
+        ws: string[];
+    };
+    transfer: (to: string, amount: bigint) => Promise<string>;
+    stop: () => void;
+};
+export declare const validateIntervalMinutes: (value: number) => number;
+export declare const startValidator: (options?: ValidatorOptions) => Promise<ValidatorHandle>;

package/exports/validator.js

@@ -0,0 +1,121 @@
+import addresses from '@leofcoin/addresses';
+import { startNode } from './node.js';
+import '@leofcoin/lib';
+import '@leofcoin/networks';
+import './index.js';
+import '@leofcoin/chain/node';
+import '@leofcoin/chain/chain';
+import '@leofcoin/lib/node-config';
+import '@leofcoin/endpoint-clients/ws';
+import '@leofcoin/endpoint-clients/http';
+
+const delay = (milliseconds, signal) => new Promise((resolve, reject) => {
+    if (signal?.aborted)
+        return reject(signal.reason ?? new Error('validator stopped'));
+    const onAbort = () => {
+        clearTimeout(timeout);
+        reject(signal?.reason ?? new Error('validator stopped'));
+    };
+    const timeout = setTimeout(() => {
+        signal?.removeEventListener('abort', onAbort);
+        resolve();
+    }, milliseconds);
+    signal?.addEventListener('abort', onAbort, { once: true });
+});
+const validateIntervalMinutes = (value) => {
+    if (!Number.isFinite(value) || value < 1)
+        throw new Error('validator interval must be at least one minute');
+    return value;
+};
+const startValidator = async (options = {}) => {
+    const network = options.network ?? 'leofcoin:peach';
+    const networkVersion = options.networkVersion ?? network.split(':')[1] ?? 'peach';
+    const intervalMinutes = validateIntervalMinutes(options.intervalMinutes ?? 5);
+    const registrationTimeoutMs = options.registrationTimeoutMs ?? 5 * 60_000;
+    const logger = options.logger ?? console;
+    const controller = new AbortController();
+    options.signal?.addEventListener('abort', () => controller.abort(options.signal?.reason), { once: true });
+    const node = await startNode({
+        network,
+        networkVersion,
+        stars: options.stars,
+        root: options.root,
+        password: options.password,
+        httpPort: options.httpPort,
+        wsPort: options.wsPort,
+        signal: controller.signal
+    });
+    const chain = node.chain;
+    const chainRuntime = chain;
+    const peernet = globalThis.peernet;
+    const account = peernet?.selectedAccount;
+    if (!account)
+        throw new Error('validator identity has no selected account');
+    logger.log(`validator account: ${account}`);
+    const isRegistered = () => chainRuntime.staticCall(addresses.validators, 'has', [account]);
+    if (!(await isRegistered())) {
+        const [balanceValue, minimumValue] = await Promise.all([
+            chainRuntime.balanceOf(account),
+            chainRuntime.staticCall(addresses.validators, 'minimumBalance')
+        ]);
+        const balance = BigInt(balanceValue);
+        const minimumBalance = BigInt(minimumValue);
+        if (balance < minimumBalance) {
+            throw new Error(`validator account ${account} has balance ${balance}; registration requires at least ${minimumBalance}`);
+        }
+        const submitted = await chainRuntime.participate(account);
+        if (submitted)
+            throw new Error('validator registration state changed unexpectedly');
+        logger.log('validator registration submitted; waiting for finalization...');
+        const deadline = Date.now() + registrationTimeoutMs;
+        while (Date.now() < deadline && !(await isRegistered()))
+            await delay(5_000, controller.signal);
+        if (!(await isRegistered())) {
+            throw new Error('validator registration was not finalized; at least one existing validator must be online to produce it');
+        }
+    }
+    if (!(await chainRuntime.participate(account))) {
+        throw new Error('validator is registered but participation did not activate');
+    }
+    logger.log('validator participation active');
+    const transfer = node.transfer;
+    let sending = false;
+    const heartbeat = async () => {
+        if (controller.signal.aborted || sending)
+            return;
+        sending = true;
+        try {
+            const balance = BigInt(await chainRuntime.balanceOf(account));
+            if (balance <= 1n) {
+                logger.warn(`heartbeat skipped: balance ${balance} is too low`);
+                return;
+            }
+            const hash = await transfer(account, 1n);
+            logger.log(`heartbeat transaction finalized: ${hash}`);
+        }
+        catch (error) {
+            logger.error(`heartbeat transaction failed: ${error?.message ?? error}`);
+        }
+        finally {
+            sending = false;
+        }
+    };
+    // Startup must not wait for a transaction to finalize. In particular, the
+    // interactive wallet shell and API endpoints must remain available while a
+    // single-node validator is still trying to produce/finalize its heartbeat.
+    if (options.heartbeat !== false)
+        void heartbeat();
+    const interval = options.heartbeat === false ? undefined : setInterval(heartbeat, intervalMinutes * 60_000);
+    const stop = () => {
+        if (controller.signal.aborted)
+            return;
+        controller.abort(new Error('validator stopped'));
+        node.stop();
+        if (interval)
+            clearInterval(interval);
+    };
+    controller.signal.addEventListener('abort', () => interval && clearInterval(interval), { once: true });
+    return { account, chain, endpoints: node.endpoints, transfer, stop };
+};
+
+export { startValidator, validateIntervalMinutes };

package/package.json

@@ -1,13 +1,25 @@
 {
   "name": "@leofcoin/launch-chain",
-  "version": "0.4.20",
+  "version": "0.4.22",
   "description": "",
   "exports": {
     ".": {
       "import": "./exports/index.js",
       "types": "./exports/index.d.ts"
+    },
+    "./validator": {
+      "import": "./exports/validator.js",
+      "types": "./exports/validator.d.ts"
+    },
+    "./node": {
+      "import": "./exports/node.js",
+      "types": "./exports/node.d.ts"
     }
   },
+  "bin": {
+    "leofcoin": "./exports/cli.js",
+    "leofcoin-validator": "./exports/validator-cli.js"
+  },
   "files": [
     "exports"
   ],
@@ -29,9 +41,11 @@
   },
   "homepage": "https://github.com/leofcoin/monorepo/tree/main/packages/launch-chain#readme",
   "dependencies": {
-    "@leofcoin/chain": "^1.10.11",
-    "@leofcoin/endpoint-clients": "^0.3.15",
-    "@leofcoin/endpoints": "^0.4.8",
+    "@leofcoin/addresses": "^1.0.62",
+    "@leofcoin/chain": "^1.10.12",
+    "@leofcoin/endpoint-clients": "^0.3.16",
+    "@leofcoin/endpoints": "^0.4.9",
+    "@leofcoin/lib": "^1.3.10",
     "@leofcoin/networks": "^1.1.30"
   },
   "devDependencies": {