@leofcoin/launch-chain 0.4.20 → 0.4.21

package/README.md

@@ -17,6 +17,34 @@ const { chain, endpoints, mode } = await launch(
 // when mode is direct means chain is directly available and no endpoint is needed to interact with it
 ```
 
+## 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.
+Use `leofcoin-validator --help` for all options.
+
 ## options
 
 ### default

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/validator-cli.d.ts

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

package/exports/validator-cli.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { startValidator } from './validator.js';
+import '@leofcoin/addresses';
+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 args = process.argv.slice(2);
+const valueAfter = (name) => {
+    const index = args.indexOf(name);
+    if (index === -1)
+        return undefined;
+    const value = args[index + 1];
+    if (value === undefined || value.startsWith('--'))
+        throw new Error(`${name} requires a value`);
+    return value;
+};
+if (args.includes('--help') || args.includes('-h')) {
+    process.stdout.write(`Usage: leofcoin-validator [options]
+
+Options:
+  --network <name>           Network (default: leofcoin:peach)
+  --root <path>              Persistent Leofcoin data directory
+  --password-file <path>     Read the identity password from a private file
+  --interval <minutes>       Heartbeat interval (default: 5, minimum: 1)
+  --http-port <port>         HTTP API port (default: 8080)
+  --ws-port <port>           WebSocket API port (default: 4040)
+  --no-endpoints             Disable both API endpoints
+  -h, --help                 Show this help
+
+Without --password-file, LEOFCOIN_PASSWORD is used when set. Otherwise the
+standard interactive password prompt is shown. Never pass a password directly
+as a command-line argument.
+`);
+    process.exit(0);
+}
+const passwordFile = valueAfter('--password-file') ?? process.env.LEOFCOIN_PASSWORD_FILE;
+const password = passwordFile
+    ? (await readFile(resolve(passwordFile), 'utf8')).trim()
+    : process.env.LEOFCOIN_PASSWORD;
+if (passwordFile && !password)
+    throw new Error(`empty validator password file: ${resolve(passwordFile)}`);
+const intervalValue = valueAfter('--interval') ?? process.env.LEOFCOIN_TRANSACTION_INTERVAL_MINUTES;
+const noEndpoints = args.includes('--no-endpoints');
+const port = (name, fallback) => {
+    const value = Number(valueAfter(name) ?? fallback);
+    if (!Number.isSafeInteger(value) || value < 1 || value > 65_535)
+        throw new Error(`${name} must be a valid port`);
+    return value;
+};
+const handle = await startValidator({
+    network: valueAfter('--network') ?? process.env.LEOFCOIN_NETWORK,
+    root: valueAfter('--root') ?? process.env.LEOFCOIN_DATA_ROOT,
+    password,
+    intervalMinutes: intervalValue === undefined ? undefined : Number(intervalValue),
+    httpPort: noEndpoints ? false : port('--http-port', 8080),
+    wsPort: noEndpoints ? false : port('--ws-port', 4040)
+});
+const shutdown = (signal) => {
+    process.stdout.write(`received ${signal}; stopping validator\n`);
+    handle.stop();
+    setTimeout(() => process.exit(0), 100);
+};
+process.once('SIGINT', () => shutdown('SIGINT'));
+process.once('SIGTERM', () => shutdown('SIGTERM'));

package/exports/validator.d.ts

@@ -0,0 +1,21 @@
+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;
+    signal?: AbortSignal;
+    logger?: Pick<Console, 'log' | 'warn' | 'error'>;
+};
+export type ValidatorHandle = {
+    account: string;
+    chain: Chain;
+    stop: () => void;
+};
+export declare const validateIntervalMinutes: (value: number) => number;
+export declare const startValidator: (options?: ValidatorOptions) => Promise<ValidatorHandle>;

package/exports/validator.js

@@ -0,0 +1,123 @@
+import addresses from '@leofcoin/addresses';
+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 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 stars = options.stars ?? networks.leofcoin.peach.stars;
+    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 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('validator 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('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');
+    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 raw = await chainRuntime.createTransaction({
+                from: account,
+                to: chain.nativeToken,
+                method: 'transfer',
+                params: [account, account, 1n]
+            });
+            const signed = await signTransaction(raw, peernet.identity);
+            const pending = await chainRuntime.sendTransaction(signed);
+            const hash = await pending.wait;
+            logger.log(`heartbeat transaction finalized: ${hash}`);
+        }
+        catch (error) {
+            logger.error(`heartbeat transaction failed: ${error?.message ?? error}`);
+        }
+        finally {
+            sending = false;
+        }
+    };
+    await heartbeat();
+    const interval = setInterval(heartbeat, intervalMinutes * 60_000);
+    const stop = () => {
+        if (controller.signal.aborted)
+            return;
+        controller.abort(new Error('validator stopped'));
+        clearInterval(interval);
+    };
+    controller.signal.addEventListener('abort', () => clearInterval(interval), { once: true });
+    return { account, chain, stop };
+};
+
+export { startValidator, validateIntervalMinutes };

package/package.json

@@ -1,13 +1,20 @@
 {
   "name": "@leofcoin/launch-chain",
-  "version": "0.4.20",
+  "version": "0.4.21",
   "description": "",
   "exports": {
     ".": {
       "import": "./exports/index.js",
       "types": "./exports/index.d.ts"
+    },
+    "./validator": {
+      "import": "./exports/validator.js",
+      "types": "./exports/validator.d.ts"
     }
   },
+  "bin": {
+    "leofcoin-validator": "./exports/validator-cli.js"
+  },
   "files": [
     "exports"
   ],
@@ -29,9 +36,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": {