@leofcoin/launch-chain 0.4.19 → 0.4.21

package/README.md

@@ -1,4 +1,4 @@
-# lauch-chain
+# launch-chain
 
 > launch chain & peernet (reuses exposed transports when already running)
 
@@ -7,13 +7,44 @@
 ```js
 import launch from '@leofcoin/launch-chain'
 
-const { chain, endpoints, mode } = await launch()
+const { chain, endpoints, mode } = await launch(
+  { mode: 'direct' },
+  process.env.LEOFCOIN_PASSWORD
+)
 // chain is undefined when mode is remote
 // endpoints contain urls to connect to the desired remote
 // when mode is remote means an instance is already running
 // 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
@@ -21,7 +52,7 @@ const { chain, endpoints, mode } = await launch()
 ```js
 {
   network: 'leofcoin:peach',
-  stars: ['wss://peach.leofcoin.org'],
+  stars: ['wss://star.leofcoin.org'],
   forceRemote: false, // when set to true only tries to connect to an external/local exposed node
   ws: {
     port: 4040,

package/exports/index.d.ts

@@ -3,15 +3,15 @@ import WSClient from '@leofcoin/endpoint-clients/ws';
 import HttpClient from '@leofcoin/endpoint-clients/http';
 type launchMode = 'direct' | 'remote' | 'server';
 type endpointReturns = {
-    http?: string[];
-    ws?: string[];
+    http: string[];
+    ws: string[];
 };
 type clientReturns = {
-    http?: HttpClient[];
-    ws?: WSClient[];
+    http: HttpClient[];
+    ws: WSClient[];
 };
 type launchReturn = {
-    chain: Chain;
+    chain?: Chain;
     mode: launchMode;
     endpoints: endpointReturns;
     clients: clientReturns;
@@ -23,9 +23,10 @@ type endpointOptions = {
 type launchOptions = {
     network?: string;
     networkVersion?: string;
-    stars: string[];
-    forceRemote: boolean;
+    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: (options: launchOptions, 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
@@ -72,11 +73,8 @@ const getWS = async (url, networkVersion) => {
  * @param {object} options { ws: boolean || {url: string, port: number}, http: boolean || {url: string, port: number}, network}
  * @returns '{ mode: string, endpoints: object, chain}'
  */
-const launch = async (options, password) => {
-    if (!options)
-        options = defaultOptions;
-    else
-        options = { ...defaultOptions, ...options };
+const launch = async (input = {}, password) => {
+    const options = { ...defaultOptions, ...input };
     const clients = {
         http: [],
         ws: []
@@ -89,26 +87,29 @@ const launch = async (options, password) => {
     if (options.mode === 'remote') {
         if (options.http) {
             for (const endpoint of options.http) {
-                if (endpoint.port && !endpoint.url)
-                    endpoint.url = `http://localhost:${endpoint.port}`;
-                const client = await getHttp(endpoint.url, options.networkVersion);
-                if (client)
-                    endpoints.http.push(endpoint.url) && clients.http.push(client);
+                const url = endpoint.url ?? `http://localhost:${endpoint.port}`;
+                const client = await getHttp(url, options.networkVersion);
+                if (client) {
+                    endpoints.http.push(url);
+                    clients.http.push(client);
+                }
             }
         }
         if (options.ws) {
             for (const endpoint of options.ws) {
-                if (endpoint.port && !endpoint.url)
-                    endpoint.url = `ws://localhost:${endpoint.port}`;
-                const client = await getWS(endpoint.url, options.networkVersion);
-                client && endpoints.ws.push(endpoint.url) && clients.ws.push(client);
+                const url = endpoint.url ?? `ws://localhost:${endpoint.port}`;
+                const client = await getWS(url, options.networkVersion);
+                if (client) {
+                    endpoints.ws.push(url);
+                    clients.ws.push(client);
+                }
             }
         }
         if (endpoints.http.length === 0 && endpoints.ws.length === 0)
             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 });
@@ -117,11 +118,10 @@ const launch = async (options, password) => {
             const importee = await import('@leofcoin/endpoints/ws');
             const wsServer = importee.default;
             for (const endpoint of options.ws) {
-                if (endpoint.port && !endpoint.url)
-                    endpoint.url = `ws://localhost:${endpoint.port}`;
+                const url = endpoint.url ?? `ws://localhost:${endpoint.port}`;
                 await wsServer(chain, endpoint.port, options.networkVersion);
-                endpoints.ws.push(endpoint.url);
-                const client = await getWS(endpoint.url, options.networkVersion);
+                endpoints.ws.push(url);
+                const client = await getWS(url, options.networkVersion);
                 client && clients.ws.push(client);
             }
         }
@@ -129,17 +129,16 @@ const launch = async (options, password) => {
             const importee = await import('@leofcoin/endpoints/http');
             const httpServer = importee.default;
             for (const endpoint of options.http) {
-                if (endpoint.port && !endpoint.url)
-                    endpoint.url = `http://localhost:${endpoint.port}`;
+                const url = endpoint.url ?? `http://localhost:${endpoint.port}`;
                 await httpServer(chain, endpoint.port, options.networkVersion);
-                endpoints.http.push(endpoint.url);
-                const client = await getHttp(endpoint.url, options.networkVersion);
+                endpoints.http.push(url);
+                const client = await getHttp(url, options.networkVersion);
                 client && clients.http.push(client);
             }
         }
     }
     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 });
@@ -148,20 +147,18 @@ const launch = async (options, password) => {
             const importee = await import('@leofcoin/endpoints/ws');
             const wsServer = importee.default;
             for (const endpoint of options.ws) {
-                if (endpoint.port && !endpoint.url)
-                    endpoint.url = `ws://localhost:${endpoint.port}`;
+                const url = endpoint.url ?? `ws://localhost:${endpoint.port}`;
                 await wsServer(chain, endpoint.port, options.networkVersion);
-                endpoints.ws.push(endpoint.url);
+                endpoints.ws.push(url);
             }
         }
         if (options.http) {
             const importee = await import('@leofcoin/endpoints/http');
             const httpServer = importee.default;
             for (const endpoint of options.http) {
-                if (endpoint.port && !endpoint.url)
-                    endpoint.url = `http://localhost:${endpoint.port}`;
+                const url = endpoint.url ?? `http://localhost:${endpoint.port}`;
                 await httpServer(chain, endpoint.port, options.networkVersion);
-                endpoints.http.push(endpoint.url);
+                endpoints.http.push(url);
             }
         }
     }

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,24 +1,32 @@
 {
   "name": "@leofcoin/launch-chain",
-  "version": "0.4.19",
+  "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"
   ],
   "type": "module",
   "scripts": {
     "build": "rollup -c",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "node --test test/*.test.js"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/leofcoin/launch-chain.git"
+    "url": "https://github.com/leofcoin/monorepo.git",
+    "directory": "packages/launch-chain"
   },
   "keywords": [],
   "author": "",
@@ -26,11 +34,13 @@
   "bugs": {
     "url": "https://github.com/leofcoin/launch-chain/issues"
   },
-  "homepage": "https://github.com/leofcoin/launch-chain#readme",
+  "homepage": "https://github.com/leofcoin/monorepo/tree/main/packages/launch-chain#readme",
   "dependencies": {
-    "@leofcoin/chain": "^1.10.9",
-    "@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": {

package/exports/src/index.d.ts

@@ -1,38 +0,0 @@
-import Chain from '@leofcoin/chain/chain';
-import WSClient from '@leofcoin/endpoint-clients/ws';
-import HttpClient from '@leofcoin/endpoint-clients/http';
-type launchMode = 'direct' | 'remote' | 'server';
-type endpointReturns = {
-    http?: string[];
-    ws?: string[];
-};
-type clientReturns = {
-    http?: HttpClient[];
-    ws?: WSClient[];
-};
-type launchReturn = {
-    chain: Chain;
-    mode: launchMode;
-    endpoints: endpointReturns;
-    clients: clientReturns;
-};
-type endpointOptions = {
-    port: number;
-    url?: string;
-};
-type launchOptions = {
-    network?: string;
-    networkVersion?: string;
-    stars: string[];
-    forceRemote: boolean;
-    mode?: launchMode;
-    ws?: endpointOptions[] | undefined;
-    http?: endpointOptions[] | undefined;
-};
-/**
- *
- * @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: (options: launchOptions, password: string) => Promise<launchReturn>;
-export { launch as default };