From d22bd15db85046a2d408039bd62490207774d4e8 Mon Sep 17 00:00:00 2001 From: Helix Date: Tue, 12 May 2026 18:39:00 +0000 Subject: [PATCH 1/5] chore: bump start-sdk to 1.5.0; refresh dep refs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - @start9labs/start-sdk 1.3.3 → 1.5.0 - Cast bitcoin-core-startos's autoconfig Action to our SDK's Action interface — sibling packages are still on 1.3.3, and 1.5.0 added effects.notification which makes structural Action matching fail in createTask's GetActionInputType inference (input value narrows to never). Cast restores the input type. - Refresh bitcoin-core-startos / cln-startos / lnd-startos pinned commits to current master HEADs. npm update is blocked by cln-startos's plugins submodule pointing at the deleted Start9Labs/c-lightning-pruning-plugin repo, so the lock file was edited directly (resolved commit + nested @start9labs/start-sdk bumped from 1.3.2 → 1.3.3 to match each sibling's package.json). - Bump StartOS revision 3.3.1:2 → 3.3.1:3 with matching release notes. --- package-lock.json | 100 +++++++++++++----- package.json | 2 +- startos/dependencies.ts | 8 +- startos/versions/index.ts | 4 +- startos/versions/{v3.3.1_2.ts => v3.3.1_3.ts} | 14 +-- 5 files changed, 91 insertions(+), 37 deletions(-) rename startos/versions/{v3.3.1_2.ts => v3.3.1_3.ts} (88%) diff --git a/package-lock.json b/package-lock.json index f9a7972..1ba908d 100644 --- a/package-lock.json +++ b/package-lock.json @@ -6,7 +6,7 @@ "": { "name": "mempool-startos", "dependencies": { - "@start9labs/start-sdk": "1.3.3", + "@start9labs/start-sdk": "1.5.0", "bitcoin-core-startos": "github:Start9Labs/bitcoin-core-startos#28.x", "cln-startos": "github:Start9Labs/cln-startos#master", "lnd-startos": "github:Start9Labs/lnd-startos#master" @@ -64,9 +64,9 @@ "license": "MIT" }, "node_modules/@start9labs/start-sdk": { - "version": "1.3.3", - "resolved": "https://registry.npmjs.org/@start9labs/start-sdk/-/start-sdk-1.3.3.tgz", - "integrity": "sha512-aL9ilSj6CyP2+tSooxPZFqWXP1/1dMgYljcu1s2ECoPv6CTmSBqwrBw9SdsQp7PYmnU4rsSZQteWogkDOf93YQ==", + "version": "1.5.0", + "resolved": "https://registry.npmjs.org/@start9labs/start-sdk/-/start-sdk-1.5.0.tgz", + "integrity": "sha512-nsbJdXU2eZS8EFOVH68nOgQvDi/dAN0Swd37od4Luyu+ajKEKTdyt30fze/CbdaXF8gwV54D8A2k3uni1KnLBQ==", "license": "MIT", "dependencies": { "@iarna/toml": "^3.0.0", @@ -74,15 +74,48 @@ "@noble/hashes": "^1.8.0", "@types/ini": "^4.1.1", "deep-equality-data-structures": "^2.0.0", - "fast-xml-parser": "~5.6.0", + "fast-xml-parser": "~5.7.0", "ini": "^5.0.0", "isomorphic-fetch": "^3.0.0", "mime": "^4.1.0", "yaml": "^2.8.3", - "zod": "^4.3.6", + "zod": "4.3.6", "zod-deep-partial": "^1.2.0" } }, + "node_modules/@start9labs/start-sdk/node_modules/@nodable/entities": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/@nodable/entities/-/entities-2.1.0.tgz", + "integrity": "sha512-nyT7T3nbMyBI/lvr6L5TyWbFJAI9FTgVRakNoBqCD+PmID8DzFrrNdLLtHMwMszOtqZa8PAOV24ZqDnQrhQINA==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/nodable" + } + ], + "license": "MIT" + }, + "node_modules/@start9labs/start-sdk/node_modules/fast-xml-parser": { + "version": "5.7.3", + "resolved": "https://registry.npmjs.org/fast-xml-parser/-/fast-xml-parser-5.7.3.tgz", + "integrity": "sha512-C0AaNuC+mscy6vrAQKAc/rMq+zAPHodfHGZu4sGVehvAQt/JLG1O5zEcYcXSY5zSqr4YVgxsB+pHXTq0i7eDlg==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/NaturalIntelligence" + } + ], + "license": "MIT", + "dependencies": { + "@nodable/entities": "^2.1.0", + "fast-xml-builder": "^1.1.7", + "path-expression-matcher": "^1.5.0", + "strnum": "^2.2.3" + }, + "bin": { + "fxparser": "src/cli/cli.js" + } + }, "node_modules/@types/ini": { "version": "4.1.1", "resolved": "https://registry.npmjs.org/@types/ini/-/ini-4.1.1.tgz", @@ -111,16 +144,16 @@ }, "node_modules/bitcoin-core-startos": { "name": "bitcoin-core", - "resolved": "git+ssh://git@github.com/Start9Labs/bitcoin-core-startos.git#e873695fc4e9fa5a21d13db9b56edbb1dab48d08", + "resolved": "git+ssh://git@github.com/Start9Labs/bitcoin-core-startos.git#b3bc91c970db6822b38228b07b646ec7ad3138fa", "dependencies": { - "@start9labs/start-sdk": "1.3.2", + "@start9labs/start-sdk": "1.3.3", "diskusage": "^1.2.0" } }, "node_modules/bitcoin-core-startos/node_modules/@start9labs/start-sdk": { - "version": "1.3.2", - "resolved": "https://registry.npmjs.org/@start9labs/start-sdk/-/start-sdk-1.3.2.tgz", - "integrity": "sha512-Iw26tSjN+2yKYul8VabrV9VtpbHnEes4FCCxhGrmdFzjP/wc+K4DLqN+cLgqwtVebVB0mJVhhh63nbRil1pqWg==", + "version": "1.3.3", + "resolved": "https://registry.npmjs.org/@start9labs/start-sdk/-/start-sdk-1.3.3.tgz", + "integrity": "sha512-aL9ilSj6CyP2+tSooxPZFqWXP1/1dMgYljcu1s2ECoPv6CTmSBqwrBw9SdsQp7PYmnU4rsSZQteWogkDOf93YQ==", "license": "MIT", "dependencies": { "@iarna/toml": "^3.0.0", @@ -138,18 +171,18 @@ } }, "node_modules/cln-startos": { - "resolved": "git+ssh://git@github.com/Start9Labs/cln-startos.git#30de0b7eee3339ecb44b469d78b2c9a438d885c9", + "resolved": "git+ssh://git@github.com/Start9Labs/cln-startos.git#f80349c4caa48ac5fdbd618ac46f423d7677cb46", "dependencies": { - "@start9labs/start-sdk": "1.3.2", + "@start9labs/start-sdk": "1.3.3", "bitcoin-core-startos": "github:Start9Labs/bitcoin-core-startos#28.x", "dotenv": "^17.2.0", "node-forge": "^1.3.1" } }, "node_modules/cln-startos/node_modules/@start9labs/start-sdk": { - "version": "1.3.2", - "resolved": "https://registry.npmjs.org/@start9labs/start-sdk/-/start-sdk-1.3.2.tgz", - "integrity": "sha512-Iw26tSjN+2yKYul8VabrV9VtpbHnEes4FCCxhGrmdFzjP/wc+K4DLqN+cLgqwtVebVB0mJVhhh63nbRil1pqWg==", + "version": "1.3.3", + "resolved": "https://registry.npmjs.org/@start9labs/start-sdk/-/start-sdk-1.3.3.tgz", + "integrity": "sha512-aL9ilSj6CyP2+tSooxPZFqWXP1/1dMgYljcu1s2ECoPv6CTmSBqwrBw9SdsQp7PYmnU4rsSZQteWogkDOf93YQ==", "license": "MIT", "dependencies": { "@iarna/toml": "^3.0.0", @@ -205,9 +238,9 @@ "license": "MIT" }, "node_modules/fast-xml-builder": { - "version": "1.1.4", - "resolved": "https://registry.npmjs.org/fast-xml-builder/-/fast-xml-builder-1.1.4.tgz", - "integrity": "sha512-f2jhpN4Eccy0/Uz9csxh3Nu6q4ErKxf0XIsasomfOihuSUa3/xw6w8dnOtCDgEItQFJG8KyXPzQXzcODDrrbOg==", + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/fast-xml-builder/-/fast-xml-builder-1.2.0.tgz", + "integrity": "sha512-00aAWieqff+ZJhsXA4g1g7M8k+7AYoMUUHF+/zFb5U6Uv/P0Vl4QZo84/IcufzYalLuEj9928bXN9PbbFzMF0Q==", "funding": [ { "type": "github", @@ -216,7 +249,8 @@ ], "license": "MIT", "dependencies": { - "path-expression-matcher": "^1.1.3" + "path-expression-matcher": "^1.5.0", + "xml-naming": "^0.1.0" } }, "node_modules/fast-xml-parser": { @@ -260,18 +294,18 @@ } }, "node_modules/lnd-startos": { - "resolved": "git+ssh://git@github.com/Start9Labs/lnd-startos.git#0a3ab8f4783b04f70bd6f2b735890f5fc850674c", + "resolved": "git+ssh://git@github.com/Start9Labs/lnd-startos.git#95dfbe730758d1fe3e0ef3839f6c7ec598ada032", "dependencies": { - "@start9labs/start-sdk": "1.3.2", + "@start9labs/start-sdk": "1.3.3", "bitcoin-core-startos": "github:Start9Labs/bitcoin-core-startos#28.x", "mime": "^4.0.7", "rfc4648": "1.5.4" } }, "node_modules/lnd-startos/node_modules/@start9labs/start-sdk": { - "version": "1.3.2", - "resolved": "https://registry.npmjs.org/@start9labs/start-sdk/-/start-sdk-1.3.2.tgz", - "integrity": "sha512-Iw26tSjN+2yKYul8VabrV9VtpbHnEes4FCCxhGrmdFzjP/wc+K4DLqN+cLgqwtVebVB0mJVhhh63nbRil1pqWg==", + "version": "1.3.3", + "resolved": "https://registry.npmjs.org/@start9labs/start-sdk/-/start-sdk-1.3.3.tgz", + "integrity": "sha512-aL9ilSj6CyP2+tSooxPZFqWXP1/1dMgYljcu1s2ECoPv6CTmSBqwrBw9SdsQp7PYmnU4rsSZQteWogkDOf93YQ==", "license": "MIT", "dependencies": { "@iarna/toml": "^3.0.0", @@ -445,6 +479,21 @@ "webidl-conversions": "^3.0.0" } }, + "node_modules/xml-naming": { + "version": "0.1.0", + "resolved": "https://registry.npmjs.org/xml-naming/-/xml-naming-0.1.0.tgz", + "integrity": "sha512-k8KO9hrMyNk6tUWqUfkTEZbezRRpONVOzUTnc97VnCvyj6Tf9lyUR9EDAIeiVLv56jsMcoXEwjW8Kv5yPY52lw==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/NaturalIntelligence" + } + ], + "license": "MIT", + "engines": { + "node": ">=16.0.0" + } + }, "node_modules/yaml": { "version": "2.8.3", "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.8.3.tgz", @@ -465,7 +514,6 @@ "resolved": "https://registry.npmjs.org/zod/-/zod-4.3.6.tgz", "integrity": "sha512-rftlrkhHZOcjDwkGlnUtZZkvaPHCsDATp4pGpuOOMDaTdDDXF91wuVDJoWoPsKX/3YPQ5fHuF3STjcYyKr+Qhg==", "license": "MIT", - "peer": true, "funding": { "url": "https://github.com/sponsors/colinhacks" } diff --git a/package.json b/package.json index c1c5da5..bcee4c8 100644 --- a/package.json +++ b/package.json @@ -6,7 +6,7 @@ "check": "tsc --noEmit" }, "dependencies": { - "@start9labs/start-sdk": "1.3.3", + "@start9labs/start-sdk": "1.5.0", "bitcoin-core-startos": "github:Start9Labs/bitcoin-core-startos#28.x", "cln-startos": "github:Start9Labs/cln-startos#master", "lnd-startos": "github:Start9Labs/lnd-startos#master" diff --git a/startos/dependencies.ts b/startos/dependencies.ts index 9f646fc..1dc75d8 100644 --- a/startos/dependencies.ts +++ b/startos/dependencies.ts @@ -1,9 +1,15 @@ import { T } from '@start9labs/start-sdk' -import { autoconfig } from 'bitcoin-core-startos/startos/actions/config/autoconfig' +import type { Action } from '@start9labs/start-sdk/base/lib/actions/setupActions' +import { autoconfig as _autoconfig } from 'bitcoin-core-startos/startos/actions/config/autoconfig' import { configJson } from './file-models/mempool-config.json' import { i18n } from './i18n' import { sdk } from './sdk' +const autoconfig = _autoconfig as unknown as Action< + 'autoconfig', + (typeof _autoconfig)['_INPUT'] +> + export const setDependencies = sdk.setupDependencies(async ({ effects }) => { await sdk.action.createTask(effects, 'bitcoind', autoconfig, 'critical', { input: { diff --git a/startos/versions/index.ts b/startos/versions/index.ts index 109cd07..89dfe80 100644 --- a/startos/versions/index.ts +++ b/startos/versions/index.ts @@ -1,7 +1,7 @@ import { VersionGraph } from '@start9labs/start-sdk' -import { v_3_3_1_2 } from './v3.3.1_2' +import { v_3_3_1_3 } from './v3.3.1_3' export const versionGraph = VersionGraph.of({ - current: v_3_3_1_2, + current: v_3_3_1_3, other: [], }) diff --git a/startos/versions/v3.3.1_2.ts b/startos/versions/v3.3.1_3.ts similarity index 88% rename from startos/versions/v3.3.1_2.ts rename to startos/versions/v3.3.1_3.ts index f9f0ebc..c443165 100644 --- a/startos/versions/v3.3.1_2.ts +++ b/startos/versions/v3.3.1_3.ts @@ -2,14 +2,14 @@ import { IMPOSSIBLE, VersionInfo, YAML } from '@start9labs/start-sdk' import { readFile, rm, writeFile } from 'fs/promises' import { configJson } from '../file-models/mempool-config.json' -export const v_3_3_1_2 = VersionInfo.of({ - version: '3.3.1:2', +export const v_3_3_1_3 = VersionInfo.of({ + version: '3.3.1:3', releaseNotes: { - en_US: 'Internal updates (start-sdk 1.3.3)', - es_ES: 'Actualizaciones internas (start-sdk 1.3.3)', - de_DE: 'Interne Aktualisierungen (start-sdk 1.3.3)', - pl_PL: 'Aktualizacje wewnętrzne (start-sdk 1.3.3)', - fr_FR: 'Mises à jour internes (start-sdk 1.3.3)', + en_US: 'Internal updates (start-sdk 1.5.0)', + es_ES: 'Actualizaciones internas (start-sdk 1.5.0)', + de_DE: 'Interne Aktualisierungen (start-sdk 1.5.0)', + pl_PL: 'Aktualizacje wewnętrzne (start-sdk 1.5.0)', + fr_FR: 'Mises à jour internes (start-sdk 1.5.0)', }, migrations: { up: async ({ effects }) => { From 02b0be32359f39be7591a37b7882172169a76dbe Mon Sep 17 00:00:00 2001 From: Helix Date: Tue, 12 May 2026 20:49:50 +0000 Subject: [PATCH 2/5] chore: refresh npm registry dependencies MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit npm update bumps: - @types/node 22.19.15 → 22.19.19 - prettier 3.8.1 → 3.8.3 - fast-xml-parser 5.6.0 → 5.7.3 (and dedupes from start-sdk's nested copy) - @nodable/entities 1.1.0 → 2.1.0 (dedupes for the same reason) - nan 2.26.2 → 2.27.0 - strnum 2.2.3 → 2.3.0 - yaml 2.8.3 → 2.9.0 Sibling git deps (bitcoin-core-startos@28.x, cln-startos@master, lnd-startos@master) were already at their branch HEADs. --- package-lock.json | 178 +++++++++++++++++++++++++++++++--------------- 1 file changed, 122 insertions(+), 56 deletions(-) diff --git a/package-lock.json b/package-lock.json index 1ba908d..921d427 100644 --- a/package-lock.json +++ b/package-lock.json @@ -52,9 +52,9 @@ } }, "node_modules/@nodable/entities": { - "version": "1.1.0", - "resolved": "https://registry.npmjs.org/@nodable/entities/-/entities-1.1.0.tgz", - "integrity": "sha512-bidpxmTBP0pOsxULw6XlxzQpTgrAGLDHGBK/JuWhPDL6ZV0GZ/PmN9CA9do6e+A9lYI6qx6ikJUtJYRxup141g==", + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/@nodable/entities/-/entities-2.1.0.tgz", + "integrity": "sha512-nyT7T3nbMyBI/lvr6L5TyWbFJAI9FTgVRakNoBqCD+PmID8DzFrrNdLLtHMwMszOtqZa8PAOV24ZqDnQrhQINA==", "funding": [ { "type": "github", @@ -83,39 +83,6 @@ "zod-deep-partial": "^1.2.0" } }, - "node_modules/@start9labs/start-sdk/node_modules/@nodable/entities": { - "version": "2.1.0", - "resolved": "https://registry.npmjs.org/@nodable/entities/-/entities-2.1.0.tgz", - "integrity": "sha512-nyT7T3nbMyBI/lvr6L5TyWbFJAI9FTgVRakNoBqCD+PmID8DzFrrNdLLtHMwMszOtqZa8PAOV24ZqDnQrhQINA==", - "funding": [ - { - "type": "github", - "url": "https://github.com/sponsors/nodable" - } - ], - "license": "MIT" - }, - "node_modules/@start9labs/start-sdk/node_modules/fast-xml-parser": { - "version": "5.7.3", - "resolved": "https://registry.npmjs.org/fast-xml-parser/-/fast-xml-parser-5.7.3.tgz", - "integrity": "sha512-C0AaNuC+mscy6vrAQKAc/rMq+zAPHodfHGZu4sGVehvAQt/JLG1O5zEcYcXSY5zSqr4YVgxsB+pHXTq0i7eDlg==", - "funding": [ - { - "type": "github", - "url": "https://github.com/sponsors/NaturalIntelligence" - } - ], - "license": "MIT", - "dependencies": { - "@nodable/entities": "^2.1.0", - "fast-xml-builder": "^1.1.7", - "path-expression-matcher": "^1.5.0", - "strnum": "^2.2.3" - }, - "bin": { - "fxparser": "src/cli/cli.js" - } - }, "node_modules/@types/ini": { "version": "4.1.1", "resolved": "https://registry.npmjs.org/@types/ini/-/ini-4.1.1.tgz", @@ -123,9 +90,9 @@ "license": "MIT" }, "node_modules/@types/node": { - "version": "22.19.15", - "resolved": "https://registry.npmjs.org/@types/node/-/node-22.19.15.tgz", - "integrity": "sha512-F0R/h2+dsy5wJAUe3tAU6oqa2qbWY5TpNfL/RGmo1y38hiyO1w3x2jPtt76wmuaJI4DQnOBu21cNXQ2STIUUWg==", + "version": "22.19.19", + "resolved": "https://registry.npmjs.org/@types/node/-/node-22.19.19.tgz", + "integrity": "sha512-dyh/xO2Fh5bYrfWaaqGrRQQGkNdmYw6AmaAUvYeUMNTWQtvb796ikLdmTchRmOlOiIJ1TDXfWgVx1QkUlQ6Hew==", "dev": true, "license": "MIT", "dependencies": { @@ -150,6 +117,18 @@ "diskusage": "^1.2.0" } }, + "node_modules/bitcoin-core-startos/node_modules/@nodable/entities": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/@nodable/entities/-/entities-1.1.0.tgz", + "integrity": "sha512-bidpxmTBP0pOsxULw6XlxzQpTgrAGLDHGBK/JuWhPDL6ZV0GZ/PmN9CA9do6e+A9lYI6qx6ikJUtJYRxup141g==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/nodable" + } + ], + "license": "MIT" + }, "node_modules/bitcoin-core-startos/node_modules/@start9labs/start-sdk": { "version": "1.3.3", "resolved": "https://registry.npmjs.org/@start9labs/start-sdk/-/start-sdk-1.3.3.tgz", @@ -170,6 +149,27 @@ "zod-deep-partial": "^1.2.0" } }, + "node_modules/bitcoin-core-startos/node_modules/fast-xml-parser": { + "version": "5.6.0", + "resolved": "https://registry.npmjs.org/fast-xml-parser/-/fast-xml-parser-5.6.0.tgz", + "integrity": "sha512-5G+uaEBbOm9M4dgMOV3K/rBzfUNGqGqoUTaYJM3hBwM8t71w07gxLQZoTsjkY8FtfjabqgQHEkeIySBDYeBmJw==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/NaturalIntelligence" + } + ], + "license": "MIT", + "dependencies": { + "@nodable/entities": "^1.1.0", + "fast-xml-builder": "^1.1.4", + "path-expression-matcher": "^1.5.0", + "strnum": "^2.2.3" + }, + "bin": { + "fxparser": "src/cli/cli.js" + } + }, "node_modules/cln-startos": { "resolved": "git+ssh://git@github.com/Start9Labs/cln-startos.git#f80349c4caa48ac5fdbd618ac46f423d7677cb46", "dependencies": { @@ -179,6 +179,18 @@ "node-forge": "^1.3.1" } }, + "node_modules/cln-startos/node_modules/@nodable/entities": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/@nodable/entities/-/entities-1.1.0.tgz", + "integrity": "sha512-bidpxmTBP0pOsxULw6XlxzQpTgrAGLDHGBK/JuWhPDL6ZV0GZ/PmN9CA9do6e+A9lYI6qx6ikJUtJYRxup141g==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/nodable" + } + ], + "license": "MIT" + }, "node_modules/cln-startos/node_modules/@start9labs/start-sdk": { "version": "1.3.3", "resolved": "https://registry.npmjs.org/@start9labs/start-sdk/-/start-sdk-1.3.3.tgz", @@ -199,6 +211,27 @@ "zod-deep-partial": "^1.2.0" } }, + "node_modules/cln-startos/node_modules/fast-xml-parser": { + "version": "5.6.0", + "resolved": "https://registry.npmjs.org/fast-xml-parser/-/fast-xml-parser-5.6.0.tgz", + "integrity": "sha512-5G+uaEBbOm9M4dgMOV3K/rBzfUNGqGqoUTaYJM3hBwM8t71w07gxLQZoTsjkY8FtfjabqgQHEkeIySBDYeBmJw==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/NaturalIntelligence" + } + ], + "license": "MIT", + "dependencies": { + "@nodable/entities": "^1.1.0", + "fast-xml-builder": "^1.1.4", + "path-expression-matcher": "^1.5.0", + "strnum": "^2.2.3" + }, + "bin": { + "fxparser": "src/cli/cli.js" + } + }, "node_modules/deep-equality-data-structures": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/deep-equality-data-structures/-/deep-equality-data-structures-2.0.0.tgz", @@ -254,9 +287,9 @@ } }, "node_modules/fast-xml-parser": { - "version": "5.6.0", - "resolved": "https://registry.npmjs.org/fast-xml-parser/-/fast-xml-parser-5.6.0.tgz", - "integrity": "sha512-5G+uaEBbOm9M4dgMOV3K/rBzfUNGqGqoUTaYJM3hBwM8t71w07gxLQZoTsjkY8FtfjabqgQHEkeIySBDYeBmJw==", + "version": "5.7.3", + "resolved": "https://registry.npmjs.org/fast-xml-parser/-/fast-xml-parser-5.7.3.tgz", + "integrity": "sha512-C0AaNuC+mscy6vrAQKAc/rMq+zAPHodfHGZu4sGVehvAQt/JLG1O5zEcYcXSY5zSqr4YVgxsB+pHXTq0i7eDlg==", "funding": [ { "type": "github", @@ -265,8 +298,8 @@ ], "license": "MIT", "dependencies": { - "@nodable/entities": "^1.1.0", - "fast-xml-builder": "^1.1.4", + "@nodable/entities": "^2.1.0", + "fast-xml-builder": "^1.1.7", "path-expression-matcher": "^1.5.0", "strnum": "^2.2.3" }, @@ -302,6 +335,18 @@ "rfc4648": "1.5.4" } }, + "node_modules/lnd-startos/node_modules/@nodable/entities": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/@nodable/entities/-/entities-1.1.0.tgz", + "integrity": "sha512-bidpxmTBP0pOsxULw6XlxzQpTgrAGLDHGBK/JuWhPDL6ZV0GZ/PmN9CA9do6e+A9lYI6qx6ikJUtJYRxup141g==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/nodable" + } + ], + "license": "MIT" + }, "node_modules/lnd-startos/node_modules/@start9labs/start-sdk": { "version": "1.3.3", "resolved": "https://registry.npmjs.org/@start9labs/start-sdk/-/start-sdk-1.3.3.tgz", @@ -322,6 +367,27 @@ "zod-deep-partial": "^1.2.0" } }, + "node_modules/lnd-startos/node_modules/fast-xml-parser": { + "version": "5.6.0", + "resolved": "https://registry.npmjs.org/fast-xml-parser/-/fast-xml-parser-5.6.0.tgz", + "integrity": "sha512-5G+uaEBbOm9M4dgMOV3K/rBzfUNGqGqoUTaYJM3hBwM8t71w07gxLQZoTsjkY8FtfjabqgQHEkeIySBDYeBmJw==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/NaturalIntelligence" + } + ], + "license": "MIT", + "dependencies": { + "@nodable/entities": "^1.1.0", + "fast-xml-builder": "^1.1.4", + "path-expression-matcher": "^1.5.0", + "strnum": "^2.2.3" + }, + "bin": { + "fxparser": "src/cli/cli.js" + } + }, "node_modules/mime": { "version": "4.1.0", "resolved": "https://registry.npmjs.org/mime/-/mime-4.1.0.tgz", @@ -338,9 +404,9 @@ } }, "node_modules/nan": { - "version": "2.26.2", - "resolved": "https://registry.npmjs.org/nan/-/nan-2.26.2.tgz", - "integrity": "sha512-0tTvBTYkt3tdGw22nrAy50x7gpbGCCFH3AFcyS5WiUu7Eu4vWlri1woE6qHBSfy11vksDqkiwjOnlR7WV8G1Hw==", + "version": "2.27.0", + "resolved": "https://registry.npmjs.org/nan/-/nan-2.27.0.tgz", + "integrity": "sha512-hC+0LidcL3XE4rp1C4H54KujgXKzbfyTngZTwBByQxsOxCEKZT0MPQ4hOKUH2jU1OYstqdDH4onyHPDzcV0XdQ==", "license": "MIT" }, "node_modules/node-fetch": { @@ -397,9 +463,9 @@ } }, "node_modules/prettier": { - "version": "3.8.1", - "resolved": "https://registry.npmjs.org/prettier/-/prettier-3.8.1.tgz", - "integrity": "sha512-UOnG6LftzbdaHZcKoPFtOcCKztrQ57WkHDeRD9t/PTQtmT0NHSeWWepj6pS0z/N7+08BHFDQVUrfmfMRcZwbMg==", + "version": "3.8.3", + "resolved": "https://registry.npmjs.org/prettier/-/prettier-3.8.3.tgz", + "integrity": "sha512-7igPTM53cGHMW8xWuVTydi2KO233VFiTNyF5hLJqpilHfmn8C8gPf+PS7dUT64YcXFbiMGZxS9pCSxL/Dxm/Jw==", "dev": true, "license": "MIT", "bin": { @@ -419,9 +485,9 @@ "license": "MIT" }, "node_modules/strnum": { - "version": "2.2.3", - "resolved": "https://registry.npmjs.org/strnum/-/strnum-2.2.3.tgz", - "integrity": "sha512-oKx6RUCuHfT3oyVjtnrmn19H1SiCqgJSg+54XqURKp5aCMbrXrhLjRN9TjuwMjiYstZ0MzDrHqkGZ5dFTKd+zg==", + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/strnum/-/strnum-2.3.0.tgz", + "integrity": "sha512-ums3KNd42PGyx5xaoVTO1mjU1bH3NpY4vsrVlnv9PNGqQj8wd7rJ6nEypLrJ7z5vxK5RP0yMLo6J/Gsm62DI5Q==", "funding": [ { "type": "github", @@ -495,9 +561,9 @@ } }, "node_modules/yaml": { - "version": "2.8.3", - "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.8.3.tgz", - "integrity": "sha512-AvbaCLOO2Otw/lW5bmh9d/WEdcDFdQp2Z2ZUH3pX9U2ihyUY0nvLv7J6TrWowklRGPYbB/IuIMfYgxaCPg5Bpg==", + "version": "2.9.0", + "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.9.0.tgz", + "integrity": "sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA==", "license": "ISC", "bin": { "yaml": "bin.mjs" From 560ff588268d94da6128889d572d3906348c764f Mon Sep 17 00:00:00 2001 From: Helix Date: Tue, 12 May 2026 22:10:22 +0000 Subject: [PATCH 3/5] docs: add instructions.md, refresh CLAUDE/CONTRIBUTING, drop docsUrls - New root instructions.md walks first-launch through Bitcoin Core + Electrum indexer + optional Lightning, points at the Select Indexer / Enable Lightning / Configure Indexing actions, and surfaces the 16 GB RAM gate. - Ports the upstream Mempool docs URL out of the manifest's docsUrls into the instructions Documentation section. - Lists the consequential limitations users will run into: mainnet-only, Electrum-only backend, single indexer and single Lightning node at a time, disabled MaxMind/Redis/Stratum/replication/accelerator features. - CLAUDE.md slimmed to a pointer at CONTRIBUTING.md; the "how upstream is pulled" notes move into CONTRIBUTING.md's Updating the upstream version section, covering the frontend+backend tag pair plus the independent MariaDB sidecar tag. - CONTRIBUTING.md reshaped to match the hello-world template. --- CLAUDE.md | 8 +++----- CONTRIBUTING.md | 43 ++++++++++++++++++++++++++++----------- instructions.md | 41 +++++++++++++++++++++++++++++++++++++ startos/manifest/index.ts | 1 - 4 files changed, 75 insertions(+), 18 deletions(-) create mode 100644 instructions.md diff --git a/CLAUDE.md b/CLAUDE.md index 8fdbcee..4e45943 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,5 +1,3 @@ -## How the upstream version is pulled -- dockerTags in `startos/manifest/index.ts`: - - `mempool/frontend:v` - - `mempool/backend:v` -- Both must be updated together. Sidecar `mariadb` has its own version. +# CLAUDE.md + +See [CONTRIBUTING.md](CONTRIBUTING.md) for the doc map and contribution workflow. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a4b0692..59f0a75 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,21 +1,40 @@ # Contributing -## Building and Development +This repo packages [Mempool](https://github.com/mempool/mempool) for StartOS. -See the [StartOS Packaging Guide](https://docs.start9.com/packaging/) for complete environment setup and build instructions. +## Documentation — keep it in sync -### Quick Start +- **`README.md`** — what this package is and how it's built (image, volumes, interfaces). For developers and AI assistants. +- **`instructions.md`** — the user-facing instructions packed into the `.s9pk` and shown on the **Instructions** tab in StartOS, for the person running the service. +- **`CONTRIBUTING.md`** — this file. +- **`CLAUDE.md`** — operating rules for AI developers working in this repo. -```bash -# Install dependencies -npm ci +**Any code change that warrants it must update `README.md` and `instructions.md` in the same change** — a new or renamed action, an added or removed volume / port / interface / dependency, a changed default, a new limitation, any altered user-visible behavior. Don't defer: a package that ships with a stale README or stale instructions is not done, even if the code is perfect. Content rules live in the packaging guide: [Writing READMEs](https://docs.start9.com/packaging/writing-readmes.html) and [Writing Service Instructions](https://docs.start9.com/packaging/writing-instructions.html). + +## Building -# Build universal package -make +See the [StartOS Packaging Guide](https://docs.start9.com/packaging/) for environment setup, then: + +```bash +npm ci # install dependencies +make # build the universal .s9pk ``` -## How to Contribute +## Updating the upstream version + +Mempool ships as two upstream containers that must move together, plus a MariaDB sidecar that tracks its own release line. + +1. Bump both `dockerTag` values in `startos/manifest/index.ts` to the new Mempool release: + - `images.frontend.source.dockerTag` → `mempool/frontend:v` + - `images.backend.source.dockerTag` → `mempool/backend:v` + Both must be bumped together; the frontend and backend share a release tag. +2. If MariaDB itself needs a bump, update `images.mariadb.source.dockerTag` independently. MariaDB has its own version cadence and should usually only move on a deliberate decision. +3. Update `version` and `releaseNotes` in the file under `startos/versions/`, renaming it to the new version string. A *new* version file is only needed when the bump carries an `up`/`down` migration, or when you want the old release notes preserved in git history — see [Versions](https://docs.start9.com/packaging/versions.html). +4. Rebuild (`make`), sideload the `.s9pk`, and confirm it starts. +5. Review `README.md` and `instructions.md` for anything the bump changed. + +## How to contribute -1. Fork the repository and create a branch from `master` -2. Make your changes -3. Open a pull request to `master` +1. Fork the repository and create a branch from `master`. +2. Make your changes — including the doc updates above. +3. Open a pull request to `master`. diff --git a/instructions.md b/instructions.md new file mode 100644 index 0000000..783dda4 --- /dev/null +++ b/instructions.md @@ -0,0 +1,41 @@ +# Mempool + +## Documentation + +- [Mempool documentation](https://mempool.space/docs/) — upstream API reference, configuration, and feature documentation. + +## What you get on StartOS + +- A **Web UI** interface — the Mempool block explorer, visualizer, fee estimator, and REST/WebSocket API in one site. +- Address lookup powered by a separate StartOS Electrum indexer (Fulcrum or Electrs). +- An optional **Lightning** explorer that pulls network data from a local LND or Core Lightning node. +- A bundled MariaDB sidecar; you do not configure a database. + +## Getting set up + +Mempool needs Bitcoin Core, an Electrum-style indexer, and (optionally) a Lightning node to be useful. Install dependencies before or alongside Mempool. + +1. Install **Bitcoin Core** if you don't have it. Mempool posts a critical task on Bitcoin Core requiring `txindex` enabled and pruning disabled, with an autoconfig action attached — accept it. The task re-appears any time those conditions stop being met. +2. Install **Fulcrum** (recommended) or **Electrs**. +3. After installing Mempool, run the **Select Indexer** task that appears for Mempool and pick **Fulcrum** or **Electrs**. +4. Optionally install **LND** or **Core Lightning**, then run **Enable Lightning** and pick the backend you want feeding the Lightning tab. +5. Start Mempool. It will wait until Bitcoin Core, the selected indexer, and (if enabled) the Lightning backend are healthy and synced. + +## Using Mempool + +### Web UI + +Open the **Web UI** interface to reach Mempool. The home page shows the live mempool, recent blocks, and fee estimates; use the search bar for transactions, blocks, and (once an indexer is selected) addresses. The **Lightning** tab appears when Enable Lightning is configured against a running LND or Core Lightning node. WebSocket and REST API consumers use the same hostname as the Web UI. + +### Actions + +- **Select Indexer** — switch the Electrum backend between Fulcrum and Electrs. Mempool's dependency set updates accordingly. +- **Enable Lightning** — choose LND, Core Lightning, or none for the Lightning tab's data source. The selected node is mounted read-only. +- **Configure Indexing** — turn on optional backend indexing: **Block Summaries Indexing**, **Goggles Indexing**, **Block Audit** (requires Block Summaries), and **CPFP Indexing**. Each toggle trades disk and CPU for richer block visualizations. Enabling any toggle triggers a historical backfill on the next start that can take several hours. This action requires at least 16 GB of system RAM and is rejected on lower-memory devices. + +## Limitations + +- **Mainnet only.** Testnet, testnet4, signet, regtest, and Liquid are not available. +- **Electrum backend only.** The Esplora backend is not used. +- **One indexer and one Lightning node at a time.** You cannot run Fulcrum and Electrs, or LND and CLN, simultaneously against Mempool. +- **No paid acceleration, no MaxMind GeoIP, no Redis, no Stratum, no replication** — these upstream features are deliberately disabled. diff --git a/startos/manifest/index.ts b/startos/manifest/index.ts index 104a4a0..7b3ab1f 100644 --- a/startos/manifest/index.ts +++ b/startos/manifest/index.ts @@ -19,7 +19,6 @@ export const manifest = setupManifest({ upstreamRepo: 'https://github.com/mempool/mempool', marketingUrl: 'https://mempool.space', donationUrl: 'https://mempool.space/sponsor', - docsUrls: ['https://mempool.space/docs/'], description: { short, long }, volumes: ['main', 'cache', 'db', 'config'], images: { From 856267bda29b49e63c1f2afe2ee7302c4cc62266 Mon Sep 17 00:00:00 2001 From: Matt Hill Date: Wed, 13 May 2026 17:41:39 -0600 Subject: [PATCH 4/5] chore: bump start-sdk to 1.5.1; repoint deps to next --- package-lock.json | 190 ++++------------------------------------------ package.json | 8 +- 2 files changed, 20 insertions(+), 178 deletions(-) diff --git a/package-lock.json b/package-lock.json index 921d427..f899cdf 100644 --- a/package-lock.json +++ b/package-lock.json @@ -6,10 +6,10 @@ "": { "name": "mempool-startos", "dependencies": { - "@start9labs/start-sdk": "1.5.0", - "bitcoin-core-startos": "github:Start9Labs/bitcoin-core-startos#28.x", - "cln-startos": "github:Start9Labs/cln-startos#master", - "lnd-startos": "github:Start9Labs/lnd-startos#master" + "@start9labs/start-sdk": "1.5.1", + "bitcoin-core-startos": "github:Start9Labs/bitcoin-core-startos#next/28.x", + "cln-startos": "github:Start9Labs/cln-startos#next", + "lnd-startos": "github:Start9Labs/lnd-startos#next" }, "devDependencies": { "@types/node": "^22.1.0", @@ -64,9 +64,9 @@ "license": "MIT" }, "node_modules/@start9labs/start-sdk": { - "version": "1.5.0", - "resolved": "https://registry.npmjs.org/@start9labs/start-sdk/-/start-sdk-1.5.0.tgz", - "integrity": "sha512-nsbJdXU2eZS8EFOVH68nOgQvDi/dAN0Swd37od4Luyu+ajKEKTdyt30fze/CbdaXF8gwV54D8A2k3uni1KnLBQ==", + "version": "1.5.1", + "resolved": "https://registry.npmjs.org/@start9labs/start-sdk/-/start-sdk-1.5.1.tgz", + "integrity": "sha512-iztLiOCtHuTfUCd2JOWio4OvBk5qFGa0NI+G+ZB/dQ1sWtunYEnzqMcF6N/Ss4L6+7bBOMAMU4VuhyxeZoHyIw==", "license": "MIT", "dependencies": { "@iarna/toml": "^3.0.0", @@ -111,127 +111,21 @@ }, "node_modules/bitcoin-core-startos": { "name": "bitcoin-core", - "resolved": "git+ssh://git@github.com/Start9Labs/bitcoin-core-startos.git#b3bc91c970db6822b38228b07b646ec7ad3138fa", + "resolved": "git+ssh://git@github.com/Start9Labs/bitcoin-core-startos.git#c745e4dffc8a9ff3984bd00c1ea9ea843439b74c", "dependencies": { - "@start9labs/start-sdk": "1.3.3", + "@start9labs/start-sdk": "1.5.1", "diskusage": "^1.2.0" } }, - "node_modules/bitcoin-core-startos/node_modules/@nodable/entities": { - "version": "1.1.0", - "resolved": "https://registry.npmjs.org/@nodable/entities/-/entities-1.1.0.tgz", - "integrity": "sha512-bidpxmTBP0pOsxULw6XlxzQpTgrAGLDHGBK/JuWhPDL6ZV0GZ/PmN9CA9do6e+A9lYI6qx6ikJUtJYRxup141g==", - "funding": [ - { - "type": "github", - "url": "https://github.com/sponsors/nodable" - } - ], - "license": "MIT" - }, - "node_modules/bitcoin-core-startos/node_modules/@start9labs/start-sdk": { - "version": "1.3.3", - "resolved": "https://registry.npmjs.org/@start9labs/start-sdk/-/start-sdk-1.3.3.tgz", - "integrity": "sha512-aL9ilSj6CyP2+tSooxPZFqWXP1/1dMgYljcu1s2ECoPv6CTmSBqwrBw9SdsQp7PYmnU4rsSZQteWogkDOf93YQ==", - "license": "MIT", - "dependencies": { - "@iarna/toml": "^3.0.0", - "@noble/curves": "^1.9.7", - "@noble/hashes": "^1.8.0", - "@types/ini": "^4.1.1", - "deep-equality-data-structures": "^2.0.0", - "fast-xml-parser": "~5.6.0", - "ini": "^5.0.0", - "isomorphic-fetch": "^3.0.0", - "mime": "^4.1.0", - "yaml": "^2.8.3", - "zod": "^4.3.6", - "zod-deep-partial": "^1.2.0" - } - }, - "node_modules/bitcoin-core-startos/node_modules/fast-xml-parser": { - "version": "5.6.0", - "resolved": "https://registry.npmjs.org/fast-xml-parser/-/fast-xml-parser-5.6.0.tgz", - "integrity": "sha512-5G+uaEBbOm9M4dgMOV3K/rBzfUNGqGqoUTaYJM3hBwM8t71w07gxLQZoTsjkY8FtfjabqgQHEkeIySBDYeBmJw==", - "funding": [ - { - "type": "github", - "url": "https://github.com/sponsors/NaturalIntelligence" - } - ], - "license": "MIT", - "dependencies": { - "@nodable/entities": "^1.1.0", - "fast-xml-builder": "^1.1.4", - "path-expression-matcher": "^1.5.0", - "strnum": "^2.2.3" - }, - "bin": { - "fxparser": "src/cli/cli.js" - } - }, "node_modules/cln-startos": { - "resolved": "git+ssh://git@github.com/Start9Labs/cln-startos.git#f80349c4caa48ac5fdbd618ac46f423d7677cb46", + "resolved": "git+ssh://git@github.com/Start9Labs/cln-startos.git#9149541bb06eb6a71addb00939b277e06fe8fb74", "dependencies": { - "@start9labs/start-sdk": "1.3.3", - "bitcoin-core-startos": "github:Start9Labs/bitcoin-core-startos#28.x", + "@start9labs/start-sdk": "1.5.1", + "bitcoin-core-startos": "github:Start9Labs/bitcoin-core-startos#next/28.x", "dotenv": "^17.2.0", "node-forge": "^1.3.1" } }, - "node_modules/cln-startos/node_modules/@nodable/entities": { - "version": "1.1.0", - "resolved": "https://registry.npmjs.org/@nodable/entities/-/entities-1.1.0.tgz", - "integrity": "sha512-bidpxmTBP0pOsxULw6XlxzQpTgrAGLDHGBK/JuWhPDL6ZV0GZ/PmN9CA9do6e+A9lYI6qx6ikJUtJYRxup141g==", - "funding": [ - { - "type": "github", - "url": "https://github.com/sponsors/nodable" - } - ], - "license": "MIT" - }, - "node_modules/cln-startos/node_modules/@start9labs/start-sdk": { - "version": "1.3.3", - "resolved": "https://registry.npmjs.org/@start9labs/start-sdk/-/start-sdk-1.3.3.tgz", - "integrity": "sha512-aL9ilSj6CyP2+tSooxPZFqWXP1/1dMgYljcu1s2ECoPv6CTmSBqwrBw9SdsQp7PYmnU4rsSZQteWogkDOf93YQ==", - "license": "MIT", - "dependencies": { - "@iarna/toml": "^3.0.0", - "@noble/curves": "^1.9.7", - "@noble/hashes": "^1.8.0", - "@types/ini": "^4.1.1", - "deep-equality-data-structures": "^2.0.0", - "fast-xml-parser": "~5.6.0", - "ini": "^5.0.0", - "isomorphic-fetch": "^3.0.0", - "mime": "^4.1.0", - "yaml": "^2.8.3", - "zod": "^4.3.6", - "zod-deep-partial": "^1.2.0" - } - }, - "node_modules/cln-startos/node_modules/fast-xml-parser": { - "version": "5.6.0", - "resolved": "https://registry.npmjs.org/fast-xml-parser/-/fast-xml-parser-5.6.0.tgz", - "integrity": "sha512-5G+uaEBbOm9M4dgMOV3K/rBzfUNGqGqoUTaYJM3hBwM8t71w07gxLQZoTsjkY8FtfjabqgQHEkeIySBDYeBmJw==", - "funding": [ - { - "type": "github", - "url": "https://github.com/sponsors/NaturalIntelligence" - } - ], - "license": "MIT", - "dependencies": { - "@nodable/entities": "^1.1.0", - "fast-xml-builder": "^1.1.4", - "path-expression-matcher": "^1.5.0", - "strnum": "^2.2.3" - }, - "bin": { - "fxparser": "src/cli/cli.js" - } - }, "node_modules/deep-equality-data-structures": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/deep-equality-data-structures/-/deep-equality-data-structures-2.0.0.tgz", @@ -327,67 +221,14 @@ } }, "node_modules/lnd-startos": { - "resolved": "git+ssh://git@github.com/Start9Labs/lnd-startos.git#95dfbe730758d1fe3e0ef3839f6c7ec598ada032", + "resolved": "git+ssh://git@github.com/Start9Labs/lnd-startos.git#0e166a059e2b1768abb6747b34780d52c160ad26", "dependencies": { - "@start9labs/start-sdk": "1.3.3", - "bitcoin-core-startos": "github:Start9Labs/bitcoin-core-startos#28.x", + "@start9labs/start-sdk": "1.5.1", + "bitcoin-core-startos": "github:Start9Labs/bitcoin-core-startos#next/28.x", "mime": "^4.0.7", "rfc4648": "1.5.4" } }, - "node_modules/lnd-startos/node_modules/@nodable/entities": { - "version": "1.1.0", - "resolved": "https://registry.npmjs.org/@nodable/entities/-/entities-1.1.0.tgz", - "integrity": "sha512-bidpxmTBP0pOsxULw6XlxzQpTgrAGLDHGBK/JuWhPDL6ZV0GZ/PmN9CA9do6e+A9lYI6qx6ikJUtJYRxup141g==", - "funding": [ - { - "type": "github", - "url": "https://github.com/sponsors/nodable" - } - ], - "license": "MIT" - }, - "node_modules/lnd-startos/node_modules/@start9labs/start-sdk": { - "version": "1.3.3", - "resolved": "https://registry.npmjs.org/@start9labs/start-sdk/-/start-sdk-1.3.3.tgz", - "integrity": "sha512-aL9ilSj6CyP2+tSooxPZFqWXP1/1dMgYljcu1s2ECoPv6CTmSBqwrBw9SdsQp7PYmnU4rsSZQteWogkDOf93YQ==", - "license": "MIT", - "dependencies": { - "@iarna/toml": "^3.0.0", - "@noble/curves": "^1.9.7", - "@noble/hashes": "^1.8.0", - "@types/ini": "^4.1.1", - "deep-equality-data-structures": "^2.0.0", - "fast-xml-parser": "~5.6.0", - "ini": "^5.0.0", - "isomorphic-fetch": "^3.0.0", - "mime": "^4.1.0", - "yaml": "^2.8.3", - "zod": "^4.3.6", - "zod-deep-partial": "^1.2.0" - } - }, - "node_modules/lnd-startos/node_modules/fast-xml-parser": { - "version": "5.6.0", - "resolved": "https://registry.npmjs.org/fast-xml-parser/-/fast-xml-parser-5.6.0.tgz", - "integrity": "sha512-5G+uaEBbOm9M4dgMOV3K/rBzfUNGqGqoUTaYJM3hBwM8t71w07gxLQZoTsjkY8FtfjabqgQHEkeIySBDYeBmJw==", - "funding": [ - { - "type": "github", - "url": "https://github.com/sponsors/NaturalIntelligence" - } - ], - "license": "MIT", - "dependencies": { - "@nodable/entities": "^1.1.0", - "fast-xml-builder": "^1.1.4", - "path-expression-matcher": "^1.5.0", - "strnum": "^2.2.3" - }, - "bin": { - "fxparser": "src/cli/cli.js" - } - }, "node_modules/mime": { "version": "4.1.0", "resolved": "https://registry.npmjs.org/mime/-/mime-4.1.0.tgz", @@ -580,6 +421,7 @@ "resolved": "https://registry.npmjs.org/zod/-/zod-4.3.6.tgz", "integrity": "sha512-rftlrkhHZOcjDwkGlnUtZZkvaPHCsDATp4pGpuOOMDaTdDDXF91wuVDJoWoPsKX/3YPQ5fHuF3STjcYyKr+Qhg==", "license": "MIT", + "peer": true, "funding": { "url": "https://github.com/sponsors/colinhacks" } diff --git a/package.json b/package.json index bcee4c8..6f400e7 100644 --- a/package.json +++ b/package.json @@ -6,10 +6,10 @@ "check": "tsc --noEmit" }, "dependencies": { - "@start9labs/start-sdk": "1.5.0", - "bitcoin-core-startos": "github:Start9Labs/bitcoin-core-startos#28.x", - "cln-startos": "github:Start9Labs/cln-startos#master", - "lnd-startos": "github:Start9Labs/lnd-startos#master" + "@start9labs/start-sdk": "1.5.1", + "bitcoin-core-startos": "github:Start9Labs/bitcoin-core-startos#next/28.x", + "cln-startos": "github:Start9Labs/cln-startos#next", + "lnd-startos": "github:Start9Labs/lnd-startos#next" }, "devDependencies": { "@types/node": "^22.1.0", From 096ae0d58253410e284d7897c4cdbb237d4b88cc Mon Sep 17 00:00:00 2001 From: Matt Hill Date: Wed, 13 May 2026 23:57:16 -0600 Subject: [PATCH 5/5] feat: add Indexing and Performance action; default to Low-CPU profile Replaces the Configure Indexing action with a broader Indexing and Performance action that combines a poll/projection profile, statistics toggle, and the four indexing toggles on one form. Low-CPU (POLL_RATE_MS 8000, MEMPOOL_BLOCKS_AMOUNT 4) is the new default; Balanced (4000/6) and Responsive (2000/8, matching the upstream in-source default) opt in. Existing installs migrate to Low-CPU on upgrade. PROFILES live in utils.ts as the single source of truth for the file-model defaults, migration, and action. --- README.md | 60 +++++++--- instructions.md | 5 +- startos/actions/configureIndexing.ts | 76 ------------ startos/actions/index.ts | 4 +- startos/actions/indexingAndPerformance.ts | 131 +++++++++++++++++++++ startos/file-models/mempool-config.json.ts | 14 ++- startos/i18n/dictionaries/default.ts | 13 ++ startos/i18n/dictionaries/translations.ts | 52 ++++++++ startos/utils.ts | 17 +++ startos/versions/index.ts | 5 +- startos/versions/v3.3.1_4.ts | 70 +++++++++++ 11 files changed, 344 insertions(+), 103 deletions(-) delete mode 100644 startos/actions/configureIndexing.ts create mode 100644 startos/actions/indexingAndPerformance.ts create mode 100644 startos/versions/v3.3.1_4.ts diff --git a/README.md b/README.md index 737dea7..e3723c1 100644 --- a/README.md +++ b/README.md @@ -72,7 +72,7 @@ StartOS-specific files: 3. On install, StartOS creates a **critical task** to select an Electrum indexer for address lookups 4. Mempool will not start until Bitcoin Core (and the selected indexer, and the Lightning backend if configured) report healthy via their StartOS health checks — see [Health Checks](#health-checks) 5. Optionally run "Enable Lightning" for Lightning network data -6. Optionally run "Configure Indexing" to opt in to block-summary, goggles, audit, and/or CPFP indexing +6. Optionally run "Indexing and Performance" to change the performance profile, toggle statistics, or opt in to block-summary, goggles, audit, and/or CPFP indexing On first install, StartOS auto-generates a 22-character MariaDB password and writes it to `mempool-config.json`. The database is localhost-only. @@ -106,16 +106,19 @@ Mempool is configured via `mempool-config.json`, managed by StartOS. ### Written by Actions -| Setting | Action | Notes | -| ------------------------------------------ | ------------------ | ------------------------------------------------------------- | -| `ELECTRUM.HOST` / `.PORT` / `.TLS_ENABLED` | Select Indexer | `fulcrum.startos` or `electrs.startos`, port `50001`, TLS off | -| `LIGHTNING.ENABLED` / `.BACKEND` | Enable Lightning | Backend is `lnd` or `cln` | -| `LND.TLS_CERT_PATH` / `.MACAROON_PATH` | Enable Lightning | Paths under the LND mount | -| `CLIGHTNING.SOCKET` | Enable Lightning | `lightning-rpc` socket under the CLN mount | -| `MEMPOOL.BLOCKS_SUMMARIES_INDEXING` | Configure Indexing | Default off | -| `MEMPOOL.GOGGLES_INDEXING` | Configure Indexing | Default off | -| `MEMPOOL.AUDIT` | Configure Indexing | Default off; requires `BLOCKS_SUMMARIES_INDEXING` | -| `MEMPOOL.CPFP_INDEXING` | Configure Indexing | Default off | +| Setting | Action | Notes | +| ------------------------------------------ | ------------------------ | ------------------------------------------------------------- | +| `ELECTRUM.HOST` / `.PORT` / `.TLS_ENABLED` | Select Indexer | `fulcrum.startos` or `electrs.startos`, port `50001`, TLS off | +| `LIGHTNING.ENABLED` / `.BACKEND` | Enable Lightning | Backend is `lnd` or `cln` | +| `LND.TLS_CERT_PATH` / `.MACAROON_PATH` | Enable Lightning | Paths under the LND mount | +| `CLIGHTNING.SOCKET` | Enable Lightning | `lightning-rpc` socket under the CLN mount | +| `MEMPOOL.POLL_RATE_MS` | Indexing and Performance | `8000` (Low-CPU) / `4000` (Balanced) / `2000` (Responsive) | +| `MEMPOOL.MEMPOOL_BLOCKS_AMOUNT` | Indexing and Performance | `4` (Low-CPU) / `6` (Balanced) / `8` (Responsive) | +| `STATISTICS.ENABLED` | Indexing and Performance | Default on | +| `MEMPOOL.BLOCKS_SUMMARIES_INDEXING` | Indexing and Performance | Default off | +| `MEMPOOL.GOGGLES_INDEXING` | Indexing and Performance | Default off | +| `MEMPOOL.AUDIT` | Indexing and Performance | Default off; requires `BLOCKS_SUMMARIES_INDEXING` | +| `MEMPOOL.CPFP_INDEXING` | Indexing and Performance | Default off | ### Bitcoin Core Requirements @@ -158,20 +161,39 @@ Selecting an indexer enables address search and transaction history features. Se When enabled, configures the `LIGHTNING` and `LND`/`CLIGHTNING` sections of the configuration and mounts the selected Lightning node's volume. -### Configure Indexing +### Indexing and Performance -- **Name:** Configure Indexing -- **Purpose:** Opt in to richer block visualizations and audit data by enabling backend indexing features +- **Name:** Indexing and Performance +- **Purpose:** Tune backend CPU/responsiveness, toggle the statistics service, and opt in to optional indexing features - **Visibility:** Enabled - **Availability:** Any status -- **Inputs:** Four independent toggles — Block Summaries Indexing, Goggles Indexing, Block Audit (requires Block Summaries Indexing), CPFP Indexing +- **Inputs:** + - **Performance Profile** — one of `low-cpu` / `balanced` / `responsive` + - **Enable Statistics** — toggle (default on) + - **Block Summaries Indexing** — toggle (default off) + - **Goggles Indexing** — toggle (default off) + - **Block Audit** — toggle (default off; requires Block Summaries Indexing) + - **CPFP Indexing** — toggle (default off) - **Outputs:** None -All four toggles are off by default, matching upstream. Enabling any of them triggers a historical backfill on the next service restart, which can take several hours and consume significant disk space. Sets the `MEMPOOL.BLOCKS_SUMMARIES_INDEXING`, `MEMPOOL.GOGGLES_INDEXING`, `MEMPOOL.AUDIT`, and `MEMPOOL.CPFP_INDEXING` fields in the configuration. +Sets `MEMPOOL.POLL_RATE_MS`, `MEMPOOL.MEMPOOL_BLOCKS_AMOUNT`, `STATISTICS.ENABLED`, `MEMPOOL.BLOCKS_SUMMARIES_INDEXING`, `MEMPOOL.GOGGLES_INDEXING`, `MEMPOOL.AUDIT`, and `MEMPOOL.CPFP_INDEXING` on the configuration. Changes apply on the next service restart. -**RAM requirement:** The action rejects any combination that enables at least one toggle when the host has less than ~16 GB of total RAM (threshold: 15 GiB). Backend indexing competes with Bitcoin Core's dbcache, the selected Electrum indexer, and any Lightning node, so enabling it on a low-memory device is likely to OOM one of the services in the stack. +**Performance profile.** The Mempool backend recomputes a Rust-based block-template projection on every poll; the cost scales with poll frequency and projection depth, and on healthy nodes this loop is the dominant background CPU consumer. The profile picks both together: -**Heap behavior:** When any toggle is on, the backend's V8 heap is raised on the next restart so indexing has room to work. The formula subtracts a 6 GB reserve for the co-resident stack (Bitcoin Core, the selected indexer, any Lightning node, StartOS) and then takes 1/4 of the remainder, clamped 4–8 GB. A 16 GB box gets a 4 GB heap; a 32 GB box gets ~6.5 GB; ≥40 GB gets the 8 GB max. +| Preset | `POLL_RATE_MS` | `MEMPOOL_BLOCKS_AMOUNT` | Notes | +| ------------------ | -------------- | ----------------------- | ------------------------------------------------- | +| Low-CPU (default) | 8000 | 4 | Recommended for low-power devices | +| Balanced | 4000 | 6 | | +| Responsive | 2000 | 8 | Matches upstream in-source default; highest CPU | + +New installs land on Low-CPU. Existing installs are migrated to Low-CPU on upgrade; run the action afterwards to pick Balanced or Responsive if you prefer. + +**Statistics.** When on (default, matching upstream), the backend samples mempool throughput at 1 Hz and writes periodic statistics rows to MariaDB to power the dashboard charts. Turning it off stops the sampler and the writes; saves background CPU and disk I/O at the cost of the tx/s + vbytes/s charts. + +**Indexing.** All four indexing toggles are off by default, matching upstream. Enabling any of them triggers a historical backfill on the next service restart, which can take several hours and consume significant disk space. + +- **RAM requirement:** The action rejects any submission with at least one indexing toggle on when the host has less than ~16 GB of total RAM (threshold: 15 GiB). Backend indexing competes with Bitcoin Core's dbcache, the selected Electrum indexer, and any Lightning node, so enabling it on a low-memory device is likely to OOM one of the services in the stack. +- **Heap behavior:** When any indexing toggle is on, the backend's V8 heap is raised on the next restart so indexing has room to work. The formula subtracts a 6 GB reserve for the co-resident stack (Bitcoin Core, the selected indexer, any Lightning node, StartOS) and then takes 1/4 of the remainder, clamped 4–8 GB. A 16 GB box gets a 4 GB heap; a 32 GB box gets ~6.5 GB; ≥40 GB gets the 8 GB max. ## Backups and Restore @@ -291,7 +313,7 @@ startos_managed_env_vars: actions: - select-indexer - enable-lightning - - configure-indexing + - indexing-and-performance health_checks: - mariadb: healthcheck.sh (120s grace) - api: port_listening 8999 (45s grace) diff --git a/instructions.md b/instructions.md index 783dda4..0552307 100644 --- a/instructions.md +++ b/instructions.md @@ -31,7 +31,10 @@ Open the **Web UI** interface to reach Mempool. The home page shows the live mem - **Select Indexer** — switch the Electrum backend between Fulcrum and Electrs. Mempool's dependency set updates accordingly. - **Enable Lightning** — choose LND, Core Lightning, or none for the Lightning tab's data source. The selected node is mounted read-only. -- **Configure Indexing** — turn on optional backend indexing: **Block Summaries Indexing**, **Goggles Indexing**, **Block Audit** (requires Block Summaries), and **CPFP Indexing**. Each toggle trades disk and CPU for richer block visualizations. Enabling any toggle triggers a historical backfill on the next start that can take several hours. This action requires at least 16 GB of system RAM and is rejected on lower-memory devices. +- **Indexing and Performance** — tune backend behavior on a single form: + - **Performance Profile** — pick **Low-CPU** (default; polls bitcoind every 8s, projects 4 future blocks), **Balanced** (4s / 6 blocks), or **Responsive** (2s / 8 blocks; highest CPU). The Mempool backend rebuilds its block projection on every poll, so this is the main lever for CPU usage on low-power devices. + - **Enable Statistics** — leave on (default) for the tx/s and vbytes/s dashboard charts; turn off to skip the 1 Hz sampler and periodic MariaDB writes. + - **Indexing toggles** — **Block Summaries Indexing**, **Goggles Indexing**, **Block Audit** (requires Block Summaries), and **CPFP Indexing**. Each trades disk and CPU for richer block visualizations. Enabling any toggle triggers a historical backfill on the next start that can take several hours. The action rejects any submission with an indexing toggle on when the device has less than 16 GB of system RAM. ## Limitations diff --git a/startos/actions/configureIndexing.ts b/startos/actions/configureIndexing.ts deleted file mode 100644 index 59f6daf..0000000 --- a/startos/actions/configureIndexing.ts +++ /dev/null @@ -1,76 +0,0 @@ -import { totalmem } from 'os' -import { configJson } from '../file-models/mempool-config.json' -import { i18n } from '../i18n' -import { sdk } from '../sdk' -const { InputSpec, Value } = sdk - -// 15 GiB floor to cover 16 GB devices that report slightly less than 16 * 2^30. -const MIN_INDEXING_MEM_BYTES = 15 * 1024 * 1024 * 1024 - -const indexingInputSpec = InputSpec.of({ - BLOCKS_SUMMARIES_INDEXING: Value.toggle({ - name: i18n('Block Summaries Indexing'), - description: i18n( - 'Indexes a compact per-transaction summary of every block. Powers the expected-vs-actual fee visualization and per-block fee histograms. Required for Block Audit.', - ), - default: false, - }), - GOGGLES_INDEXING: Value.toggle({ - name: i18n('Goggles Indexing'), - description: i18n( - 'Indexes per-transaction metadata (RBF, script types, annex, sighash). Powers the colored goggles overlay filters on mempool and block views, including annex and sighash highlighting.', - ), - default: false, - }), - AUDIT: Value.toggle({ - name: i18n('Block Audit'), - description: i18n( - 'On every new block, compares what miners included vs. what the mempool predicted and flags missing, added, prioritized, and accelerated transactions. Requires Block Summaries Indexing.', - ), - default: false, - }), - CPFP_INDEXING: Value.toggle({ - name: i18n('CPFP Indexing'), - description: i18n( - 'Historically indexes CPFP (Child-Pays-For-Parent) relationships, enabling the full CPFP view on older blocks.', - ), - default: false, - }), -}) - -export const configureIndexing = sdk.Action.withInput( - 'configure-indexing', - - { - name: i18n('Configure Indexing'), - description: i18n( - 'Enable optional indexing features that unlock richer block visualizations and audit data. Each toggle trades disk space and CPU for more features. Requires at least 16 GB of system RAM — rejected on lower-memory devices. Changes apply on the next service restart.', - ), - warning: i18n( - 'Enabling indexing will trigger a historical backfill on the next start, which can take several hours and consume significant disk space.', - ), - allowedStatuses: 'any', - group: null, - visibility: 'enabled', - }, - - indexingInputSpec, - - async ({ effects }) => configJson.read((c) => c.MEMPOOL).once(), - - async ({ effects, input }) => { - const wantsIndexing = - input.BLOCKS_SUMMARIES_INDEXING || - input.GOGGLES_INDEXING || - input.AUDIT || - input.CPFP_INDEXING - if (wantsIndexing && totalmem() < MIN_INDEXING_MEM_BYTES) { - throw new Error( - i18n( - 'Indexing features require at least 16 GB of system RAM. This device has less than 16 GB available and cannot safely run backend indexing alongside Bitcoin Core and the selected Electrum backend.', - ), - ) - } - return configJson.merge(effects, { MEMPOOL: input }) - }, -) diff --git a/startos/actions/index.ts b/startos/actions/index.ts index fc1c758..44515aa 100644 --- a/startos/actions/index.ts +++ b/startos/actions/index.ts @@ -1,9 +1,9 @@ import { sdk } from '../sdk' import { selectIndexer } from './selectIndexer' import { enableLightning } from './enableLightning' -import { configureIndexing } from './configureIndexing' +import { indexingAndPerformance } from './indexingAndPerformance' export const actions = sdk.Actions.of() .addAction(selectIndexer) .addAction(enableLightning) - .addAction(configureIndexing) + .addAction(indexingAndPerformance) diff --git a/startos/actions/indexingAndPerformance.ts b/startos/actions/indexingAndPerformance.ts new file mode 100644 index 0000000..32e7ffb --- /dev/null +++ b/startos/actions/indexingAndPerformance.ts @@ -0,0 +1,131 @@ +import { totalmem } from 'os' +import { configJson } from '../file-models/mempool-config.json' +import { i18n } from '../i18n' +import { sdk } from '../sdk' +import { PROFILES, DEFAULT_PROFILE, PerformanceProfile } from '../utils' +const { InputSpec, Value } = sdk + +// 15 GiB floor to cover 16 GB devices that report slightly less than 16 * 2^30. +const MIN_INDEXING_MEM_BYTES = 15 * 1024 * 1024 * 1024 + +const inputSpec = InputSpec.of({ + profile: Value.select({ + name: i18n('Performance Profile'), + description: i18n( + 'Low-CPU: poll bitcoind every 8s and project 4 future blocks — recommended for low-power devices. Balanced: poll every 4s, project 6 blocks. Responsive: poll every 2s, project 8 blocks — matches the upstream in-source default and uses the most CPU.', + ), + default: DEFAULT_PROFILE, + values: { + 'low-cpu': i18n('Low-CPU (recommended)'), + balanced: i18n('Balanced'), + responsive: i18n('Responsive'), + }, + }), + STATISTICS_ENABLED: Value.toggle({ + name: i18n('Enable Statistics'), + description: i18n( + 'Collects mempool statistics (transactions per second, vbytes per second) for the dashboard charts. Disabling stops the 1 Hz sampler and the periodic statistics writes to MariaDB, reducing background CPU and disk I/O on low-power devices.', + ), + default: true, + }), + BLOCKS_SUMMARIES_INDEXING: Value.toggle({ + name: i18n('Block Summaries Indexing'), + description: i18n( + 'Indexes a compact per-transaction summary of every block. Powers the expected-vs-actual fee visualization and per-block fee histograms. Required for Block Audit.', + ), + default: false, + }), + GOGGLES_INDEXING: Value.toggle({ + name: i18n('Goggles Indexing'), + description: i18n( + 'Indexes per-transaction metadata (RBF, script types, annex, sighash). Powers the colored goggles overlay filters on mempool and block views, including annex and sighash highlighting.', + ), + default: false, + }), + AUDIT: Value.toggle({ + name: i18n('Block Audit'), + description: i18n( + 'On every new block, compares what miners included vs. what the mempool predicted and flags missing, added, prioritized, and accelerated transactions. Requires Block Summaries Indexing.', + ), + default: false, + }), + CPFP_INDEXING: Value.toggle({ + name: i18n('CPFP Indexing'), + description: i18n( + 'Historically indexes CPFP (Child-Pays-For-Parent) relationships, enabling the full CPFP view on older blocks.', + ), + default: false, + }), +}) + +function matchPerformanceProfile(pollRateMs: number, blocksAmount: number): PerformanceProfile { + for (const [name, p] of Object.entries(PROFILES) as [ + PerformanceProfile, + (typeof PROFILES)[PerformanceProfile], + ][]) { + if ( + p.POLL_RATE_MS === pollRateMs && + p.MEMPOOL_BLOCKS_AMOUNT === blocksAmount + ) { + return name + } + } + return 'low-cpu' +} + +export const indexingAndPerformance = sdk.Action.withInput( + 'indexing-and-performance', + + { + name: i18n('Indexing and Performance'), + description: i18n( + 'Tune backend behavior: poll/projection profile, mempool statistics, and optional indexing features. Changes apply on the next service restart. Enabling any indexing toggle triggers a historical backfill on the next start, which can take several hours and consume significant disk space; indexing requires at least 16 GB of system RAM and is rejected on lower-memory devices.', + ), + warning: null, + allowedStatuses: 'any', + group: null, + visibility: 'enabled', + }, + + inputSpec, + + async ({ effects }) => { + const config = await configJson.read().const(effects) + if (!config) throw new Error('Config file not found') + const { MEMPOOL, STATISTICS } = config + return { + profile: matchPerformanceProfile(MEMPOOL.POLL_RATE_MS, MEMPOOL.MEMPOOL_BLOCKS_AMOUNT), + STATISTICS_ENABLED: STATISTICS.ENABLED, + BLOCKS_SUMMARIES_INDEXING: MEMPOOL.BLOCKS_SUMMARIES_INDEXING, + GOGGLES_INDEXING: MEMPOOL.GOGGLES_INDEXING, + AUDIT: MEMPOOL.AUDIT, + CPFP_INDEXING: MEMPOOL.CPFP_INDEXING, + } + }, + + async ({ effects, input }) => { + const wantsIndexing = + input.BLOCKS_SUMMARIES_INDEXING || + input.GOGGLES_INDEXING || + input.AUDIT || + input.CPFP_INDEXING + if (wantsIndexing && totalmem() < MIN_INDEXING_MEM_BYTES) { + throw new Error( + i18n( + 'Indexing features require at least 16 GB of system RAM. This device has less than 16 GB available and cannot safely run backend indexing alongside Bitcoin Core and the selected Electrum backend.', + ), + ) + } + const preset = PROFILES[input.profile as PerformanceProfile] + return configJson.merge(effects, { + MEMPOOL: { + ...preset, + BLOCKS_SUMMARIES_INDEXING: input.BLOCKS_SUMMARIES_INDEXING, + GOGGLES_INDEXING: input.GOGGLES_INDEXING, + AUDIT: input.AUDIT, + CPFP_INDEXING: input.CPFP_INDEXING, + }, + STATISTICS: { ENABLED: input.STATISTICS_ENABLED }, + }) + }, +) diff --git a/startos/file-models/mempool-config.json.ts b/startos/file-models/mempool-config.json.ts index f7829d4..4b48890 100644 --- a/startos/file-models/mempool-config.json.ts +++ b/startos/file-models/mempool-config.json.ts @@ -1,6 +1,12 @@ import { FileHelper, z } from '@start9labs/start-sdk' import { sdk } from '../sdk' -import { btcMountpoint, lndMountpoint, clnMountpoint } from '../utils' +import { + btcMountpoint, + lndMountpoint, + clnMountpoint, + PROFILES, + DEFAULT_PROFILE, +} from '../utils' const mempoolSection = z.object({ // enforced @@ -12,14 +18,16 @@ const mempoolSection = z.object({ HTTP_PORT: z.number().catch(8999), SPAWN_CLUSTER_PROCS: z.number().catch(0), API_URL_PREFIX: z.string().catch('/api/v1/'), - POLL_RATE_MS: z.number().catch(2000), + POLL_RATE_MS: z.number().catch(PROFILES[DEFAULT_PROFILE].POLL_RATE_MS), CACHE_DIR: z.string().catch('./cache'), CACHE_ENABLED: z.boolean().catch(true), CLEAR_PROTECTION_MINUTES: z.number().catch(20), RECOMMENDED_FEE_PERCENTILE: z.number().catch(50), BLOCK_WEIGHT_UNITS: z.number().catch(4000000), INITIAL_BLOCKS_AMOUNT: z.number().catch(8), - MEMPOOL_BLOCKS_AMOUNT: z.number().catch(8), + MEMPOOL_BLOCKS_AMOUNT: z.number().catch( + PROFILES[DEFAULT_PROFILE].MEMPOOL_BLOCKS_AMOUNT, + ), INDEXING_BLOCKS_AMOUNT: z.number().catch(52560), BLOCKS_SUMMARIES_INDEXING: z.boolean().catch(false), GOGGLES_INDEXING: z.boolean().catch(false), diff --git a/startos/i18n/dictionaries/default.ts b/startos/i18n/dictionaries/default.ts index 4de238d..e8d1e89 100644 --- a/startos/i18n/dictionaries/default.ts +++ b/startos/i18n/dictionaries/default.ts @@ -36,6 +36,19 @@ const dict = { 'CPFP Indexing': 37, 'Historically indexes CPFP (Child-Pays-For-Parent) relationships, enabling the full CPFP view on older blocks.': 38, 'Indexing features require at least 16 GB of system RAM. This device has less than 16 GB available and cannot safely run backend indexing alongside Bitcoin Core and the selected Electrum backend.': 39, + 'Configure Performance': 40, + 'Select a CPU/responsiveness profile. The Mempool backend recomputes a projection of upcoming blocks on every poll; this action controls how often that happens and how deep the projection goes. Changes apply on the next service restart.': 41, + 'Performance Profile': 42, + 'Low-CPU: poll bitcoind every 8s and project 4 future blocks — recommended for low-power devices. Balanced: poll every 4s, project 6 blocks. Responsive: poll every 2s, project 8 blocks — matches the upstream in-source default and uses the most CPU.': 43, + 'Low-CPU (recommended)': 44, + Balanced: 45, + Responsive: 46, + 'Configure Statistics': 47, + 'Toggle the backend mempool statistics service. Changes apply on the next service restart.': 48, + 'Enable Statistics': 49, + 'Collects mempool statistics (transactions per second, vbytes per second) for the dashboard charts. Disabling stops the 1 Hz sampler and the periodic statistics writes to MariaDB, reducing background CPU and disk I/O on low-power devices.': 50, + 'Indexing and Performance': 51, + 'Tune backend behavior: poll/projection profile, mempool statistics, and optional indexing features. Changes apply on the next service restart. Enabling any indexing toggle triggers a historical backfill on the next start, which can take several hours and consume significant disk space; indexing requires at least 16 GB of system RAM and is rejected on lower-memory devices.': 52, } as const export type I18nKey = keyof typeof dict diff --git a/startos/i18n/dictionaries/translations.ts b/startos/i18n/dictionaries/translations.ts index a1eb755..217ecea 100644 --- a/startos/i18n/dictionaries/translations.ts +++ b/startos/i18n/dictionaries/translations.ts @@ -37,6 +37,19 @@ export default { 37: 'Indexacion CPFP', 38: 'Indexa historicamente las relaciones CPFP (Child-Pays-For-Parent), habilitando la vista CPFP completa en bloques antiguos.', 39: 'Las funciones de indexacion requieren al menos 16 GB de RAM del sistema. Este dispositivo tiene menos de 16 GB disponibles y no puede ejecutar la indexacion del backend de forma segura junto con Bitcoin Core y el backend Electrum seleccionado.', + 40: 'Configurar rendimiento', + 41: 'Seleccione un perfil de CPU/respuesta. El backend de Mempool recalcula una proyeccion de los proximos bloques en cada consulta; esta accion controla con que frecuencia ocurre y la profundidad de la proyeccion. Los cambios se aplican al siguiente reinicio del servicio.', + 42: 'Perfil de rendimiento', + 43: 'Bajo consumo de CPU: consulta a bitcoind cada 8s y proyecta 4 bloques futuros — recomendado para dispositivos de baja potencia. Equilibrado: consulta cada 4s, proyecta 6 bloques. Responsivo: consulta cada 2s, proyecta 8 bloques — coincide con el valor predeterminado del codigo fuente y usa mas CPU.', + 44: 'Bajo consumo de CPU (recomendado)', + 45: 'Equilibrado', + 46: 'Responsivo', + 47: 'Configurar estadisticas', + 48: 'Alterna el servicio de estadisticas de mempool del backend. Los cambios se aplican al siguiente reinicio del servicio.', + 49: 'Habilitar estadisticas', + 50: 'Recopila estadisticas de mempool (transacciones por segundo, vbytes por segundo) para los graficos del panel. Desactivarlo detiene el muestreador de 1 Hz y las escrituras periodicas a MariaDB, reduciendo el uso de CPU en segundo plano y la E/S de disco en dispositivos de baja potencia.', + 51: 'Indexacion y rendimiento', + 52: 'Ajusta el comportamiento del backend: perfil de consulta/proyeccion, estadisticas de mempool y funciones opcionales de indexacion. Los cambios se aplican al siguiente reinicio del servicio. Activar cualquier opcion de indexacion desencadena un llenado historico en el siguiente arranque, que puede tardar varias horas y consumir espacio de disco significativo; la indexacion requiere al menos 16 GB de RAM y se rechaza en dispositivos con menos memoria.', }, de_DE: { 0: 'Mempool wird gestartet', @@ -74,6 +87,19 @@ export default { 37: 'CPFP-Indexierung', 38: 'Indexiert historische CPFP-Beziehungen (Child-Pays-For-Parent) und ermoeglicht die vollstaendige CPFP-Ansicht fuer aeltere Bloecke.', 39: 'Indexierungsfunktionen benoetigen mindestens 16 GB Arbeitsspeicher. Dieses Geraet hat weniger als 16 GB verfuegbar und kann die Backend-Indexierung nicht sicher neben Bitcoin Core und dem gewaehlten Electrum-Backend ausfuehren.', + 40: 'Leistung konfigurieren', + 41: 'Waehlen Sie ein CPU/Reaktionsprofil. Das Mempool-Backend berechnet bei jeder Abfrage eine Projektion der naechsten Bloecke neu; diese Aktion steuert, wie oft das geschieht und wie tief die Projektion reicht. Aenderungen werden beim naechsten Dienstneustart wirksam.', + 42: 'Leistungsprofil', + 43: 'Niedrige-CPU: bitcoind alle 8s abfragen und 4 zukuenftige Bloecke projizieren — empfohlen fuer leistungsschwache Geraete. Ausgeglichen: alle 4s abfragen, 6 Bloecke projizieren. Reaktionsschnell: alle 2s abfragen, 8 Bloecke projizieren — entspricht dem Standard im Quellcode und nutzt am meisten CPU.', + 44: 'Niedrige-CPU (empfohlen)', + 45: 'Ausgeglichen', + 46: 'Reaktionsschnell', + 47: 'Statistik konfigurieren', + 48: 'Schaltet den Statistikdienst des Mempool-Backends um. Aenderungen werden beim naechsten Dienstneustart wirksam.', + 49: 'Statistik aktivieren', + 50: 'Sammelt Mempool-Statistiken (Transaktionen pro Sekunde, vBytes pro Sekunde) fuer die Dashboard-Diagramme. Beim Deaktivieren wird der 1-Hz-Sampler gestoppt und die periodischen Statistik-Schreibvorgaenge in MariaDB entfallen, was die Hintergrund-CPU-Last und die Festplatten-E/A auf leistungsschwachen Geraeten reduziert.', + 51: 'Indexierung und Leistung', + 52: 'Optimiert das Verhalten des Backends: Abfrage-/Projektionsprofil, Mempool-Statistik und optionale Indexierungsfunktionen. Aenderungen werden beim naechsten Dienstneustart wirksam. Das Aktivieren einer Indexierungsoption loest beim naechsten Start einen historischen Abgleich aus, der mehrere Stunden dauern und viel Speicherplatz beanspruchen kann; die Indexierung erfordert mindestens 16 GB Arbeitsspeicher und wird auf Geraeten mit weniger Speicher abgelehnt.', }, pl_PL: { 0: 'Uruchamianie Mempool', @@ -111,6 +137,19 @@ export default { 37: 'Indeksowanie CPFP', 38: 'Indeksuje historyczne relacje CPFP (Child-Pays-For-Parent), umozliwiajac pelny widok CPFP dla starszych blokow.', 39: 'Funkcje indeksowania wymagaja co najmniej 16 GB pamieci RAM systemu. To urzadzenie ma mniej niz 16 GB dostepnej pamieci i nie moze bezpiecznie uruchomic indeksowania backendu rownolegle z Bitcoin Core oraz wybranym backendem Electrum.', + 40: 'Konfiguruj wydajnosc', + 41: 'Wybierz profil CPU/responsywnosci. Backend Mempool przelicza projekcje nadchodzacych blokow przy kazdym odpytaniu; ta akcja kontroluje, jak czesto to sie dzieje i jak gleboka jest projekcja. Zmiany sa stosowane przy nastepnym ponownym uruchomieniu uslugi.', + 42: 'Profil wydajnosci', + 43: 'Niska-CPU: odpytuje bitcoind co 8s i projektuje 4 przyszle bloki — zalecane dla urzadzen o niskiej mocy. Zbalansowany: odpytuje co 4s, projektuje 6 blokow. Responsywny: odpytuje co 2s, projektuje 8 blokow — odpowiada domyslnej wartosci w kodzie zrodlowym i zuzywa najwiecej CPU.', + 44: 'Niska-CPU (zalecane)', + 45: 'Zbalansowany', + 46: 'Responsywny', + 47: 'Konfiguruj statystyki', + 48: 'Przelacza serwis statystyk mempool backendu. Zmiany sa stosowane przy nastepnym ponownym uruchomieniu uslugi.', + 49: 'Wlacz statystyki', + 50: 'Zbiera statystyki mempool (transakcje na sekunde, vbajty na sekunde) dla wykresow panelu. Wylaczenie zatrzymuje sampler 1 Hz i okresowe zapisy statystyk do MariaDB, zmniejszajac uzycie CPU w tle i operacje I/O dysku na urzadzeniach o niskiej mocy.', + 51: 'Indeksowanie i wydajnosc', + 52: 'Dostosowuje zachowanie backendu: profil odpytywania/projekcji, statystyki mempool i opcjonalne funkcje indeksowania. Zmiany sa stosowane przy nastepnym ponownym uruchomieniu uslugi. Wlaczenie dowolnej opcji indeksowania uruchomi historyczne uzupelnienie przy nastepnym starcie, co moze zajac wiele godzin i zuzyc znaczna ilosc miejsca na dysku; indeksowanie wymaga co najmniej 16 GB pamieci RAM i jest odrzucane na urzadzeniach z mniejsza iloscia pamieci.', }, fr_FR: { 0: 'Demarrage de Mempool', @@ -148,5 +187,18 @@ export default { 37: 'Indexation CPFP', 38: 'Indexe historiquement les relations CPFP (Child-Pays-For-Parent), activant la vue CPFP complete sur les anciens blocs.', 39: "Les fonctions d'indexation necessitent au moins 16 Go de RAM systeme. Cet appareil dispose de moins de 16 Go et ne peut pas executer en toute securite l'indexation du backend aux cotes de Bitcoin Core et du backend Electrum selectionne.", + 40: 'Configurer les performances', + 41: "Selectionnez un profil CPU/reactivite. Le backend de Mempool recalcule une projection des prochains blocs a chaque interrogation ; cette action controle la frequence et la profondeur de cette projection. Les changements prennent effet au prochain redemarrage du service.", + 42: 'Profil de performance', + 43: "CPU reduit : interroge bitcoind toutes les 8s et projette 4 blocs futurs — recommande pour les appareils a faible puissance. Equilibre : interroge toutes les 4s, projette 6 blocs. Reactif : interroge toutes les 2s, projette 8 blocs — correspond a la valeur par defaut du code source et utilise le plus de CPU.", + 44: 'CPU reduit (recommande)', + 45: 'Equilibre', + 46: 'Reactif', + 47: 'Configurer les statistiques', + 48: 'Bascule le service de statistiques mempool du backend. Les changements prennent effet au prochain redemarrage du service.', + 49: 'Activer les statistiques', + 50: "Collecte les statistiques mempool (transactions par seconde, vbytes par seconde) pour les graphiques du tableau de bord. Le desactiver arrete l'echantillonneur a 1 Hz et les ecritures periodiques en base MariaDB, reduisant l'utilisation CPU en arriere-plan et les E/S disque sur les appareils a faible puissance.", + 51: 'Indexation et performances', + 52: "Ajuste le comportement du backend : profil d'interrogation/projection, statistiques mempool et fonctionnalites d'indexation optionnelles. Les changements prennent effet au prochain redemarrage du service. L'activation de toute option d'indexation declenche un remplissage historique au prochain demarrage, qui peut prendre plusieurs heures et consommer un espace disque important ; l'indexation necessite au moins 16 Go de RAM et est rejetee sur les appareils disposant de moins de memoire.", }, } satisfies Record diff --git a/startos/utils.ts b/startos/utils.ts index 1aac726..f4e1071 100644 --- a/startos/utils.ts +++ b/startos/utils.ts @@ -15,3 +15,20 @@ export const dbPort = 3306 export const btcMountpoint = '/mnt/bitcoind' export const lndMountpoint = '/mnt/lnd' export const clnMountpoint = '/mnt/cln' + +// Performance profile presets. POLL_RATE_MS is the main-loop period; +// MEMPOOL_BLOCKS_AMOUNT is the depth of the Rust GBT projection. Both +// scale backend CPU roughly linearly. Single source of truth — referenced +// by the file model defaults, the migration, and the action. +export type PerformanceProfile = 'low-cpu' | 'balanced' | 'responsive' + +export const PROFILES: Record< + PerformanceProfile, + { POLL_RATE_MS: number; MEMPOOL_BLOCKS_AMOUNT: number } +> = { + 'low-cpu': { POLL_RATE_MS: 8000, MEMPOOL_BLOCKS_AMOUNT: 4 }, + balanced: { POLL_RATE_MS: 4000, MEMPOOL_BLOCKS_AMOUNT: 6 }, + responsive: { POLL_RATE_MS: 2000, MEMPOOL_BLOCKS_AMOUNT: 8 }, +} + +export const DEFAULT_PROFILE: PerformanceProfile = 'low-cpu' diff --git a/startos/versions/index.ts b/startos/versions/index.ts index 89dfe80..7ac8993 100644 --- a/startos/versions/index.ts +++ b/startos/versions/index.ts @@ -1,7 +1,8 @@ import { VersionGraph } from '@start9labs/start-sdk' import { v_3_3_1_3 } from './v3.3.1_3' +import { v_3_3_1_4 } from './v3.3.1_4' export const versionGraph = VersionGraph.of({ - current: v_3_3_1_3, - other: [], + current: v_3_3_1_4, + other: [v_3_3_1_3], }) diff --git a/startos/versions/v3.3.1_4.ts b/startos/versions/v3.3.1_4.ts new file mode 100644 index 0000000..1f532f7 --- /dev/null +++ b/startos/versions/v3.3.1_4.ts @@ -0,0 +1,70 @@ +import { IMPOSSIBLE, VersionInfo } from '@start9labs/start-sdk' +import { configJson } from '../file-models/mempool-config.json' +import { PROFILES, DEFAULT_PROFILE } from '../utils' + +export const v_3_3_1_4 = VersionInfo.of({ + version: '3.3.1:4', + releaseNotes: { + en_US: `**Features** + +- The **Configure Indexing** action has been replaced with a broader **Indexing and Performance** action that combines performance, statistics, and indexing on a single form: + - **Performance Profile** — three presets (Low-CPU / Balanced / Responsive) controlling how often the backend polls bitcoind and how many future blocks it projects. Low-CPU is the new default — recommended for low-power devices. + - **Enable Statistics** — toggle the backend tx/s + vbytes/s sampler. Disable to cut background CPU and DB writes if you don't use the dashboard charts. + - Indexing toggles unchanged (Block Summaries, Goggles, Audit, CPFP). + +**Internal** + +- New installs default to \`POLL_RATE_MS=8000\` and \`MEMPOOL_BLOCKS_AMOUNT=4\` (Low-CPU profile). +- Existing installs are migrated to the Low-CPU profile on upgrade. Run **Indexing and Performance** afterwards to pick Balanced or Responsive if you prefer.`, + es_ES: `**Funciones** + +- La acción **Configurar Indexación** se ha reemplazado por una acción más amplia **Indexación y Rendimiento** que combina rendimiento, estadísticas e indexación en un único formulario: + - **Perfil de Rendimiento** — tres preajustes (Bajo Consumo CPU / Equilibrado / Responsivo) que controlan con qué frecuencia el backend consulta a bitcoind y cuántos bloques futuros proyecta. Bajo Consumo CPU es el nuevo valor predeterminado — recomendado para dispositivos de baja potencia. + - **Habilitar Estadísticas** — alterna el muestreador de tx/s + vbytes/s del backend. Desactívelo para reducir CPU y escrituras en disco si no usa los gráficos del panel. + - Las opciones de indexación no cambian (Resúmenes de Bloques, Goggles, Auditoría, CPFP). + +**Interno** + +- Nuevas instalaciones usan \`POLL_RATE_MS=8000\` y \`MEMPOOL_BLOCKS_AMOUNT=4\` (perfil Bajo Consumo CPU). +- Las instalaciones existentes se migran al perfil Bajo Consumo CPU al actualizar. Ejecute **Indexación y Rendimiento** después si prefiere Equilibrado o Responsivo.`, + de_DE: `**Funktionen** + +- Die Aktion **Indexierung konfigurieren** wurde durch die umfassendere Aktion **Indexierung und Leistung** ersetzt, die Leistung, Statistik und Indexierung in einem einzigen Formular vereint: + - **Leistungsprofil** — drei Voreinstellungen (Niedrige-CPU / Ausgeglichen / Reaktionsschnell), die steuern, wie oft das Backend bitcoind abfragt und wie viele zukünftige Blöcke projiziert werden. Niedrige-CPU ist der neue Standard — empfohlen für leistungsschwache Geräte. + - **Statistik aktivieren** — schaltet den tx/s + vbytes/s-Sampler des Backends um. Deaktivieren, um Hintergrund-CPU und DB-Schreibvorgänge zu reduzieren, wenn die Dashboard-Diagramme nicht genutzt werden. + - Indexierungsoptionen unverändert (Blockzusammenfassungen, Goggles, Audit, CPFP). + +**Intern** + +- Neue Installationen verwenden \`POLL_RATE_MS=8000\` und \`MEMPOOL_BLOCKS_AMOUNT=4\` (Niedrige-CPU-Profil). +- Bestehende Installationen werden beim Upgrade auf das Niedrige-CPU-Profil migriert. Führen Sie anschließend **Indexierung und Leistung** aus, wenn Sie Ausgeglichen oder Reaktionsschnell bevorzugen.`, + pl_PL: `**Funkcje** + +- Akcja **Konfiguruj Indeksowanie** została zastąpiona szerszą akcją **Indeksowanie i Wydajność**, która łączy wydajność, statystyki i indeksowanie w jednym formularzu: + - **Profil Wydajności** — trzy presety (Niska-CPU / Zbalansowany / Responsywny) kontrolujące częstotliwość odpytywania bitcoind i liczbę projektowanych przyszłych bloków. Niska-CPU jest nowym domyślnym — zalecane dla urządzeń o niskiej mocy. + - **Włącz Statystyki** — przełącza sampler tx/s + vbytes/s w backendzie. Wyłącz, aby zmniejszyć użycie CPU i zapisów do bazy danych, jeśli nie korzystasz z wykresów panelu. + - Opcje indeksowania bez zmian (Podsumowania Bloków, Goggles, Audyt, CPFP). + +**Wewnętrzne** + +- Nowe instalacje używają \`POLL_RATE_MS=8000\` i \`MEMPOOL_BLOCKS_AMOUNT=4\` (profil Niska-CPU). +- Istniejące instalacje są migrowane do profilu Niska-CPU przy aktualizacji. Uruchom następnie **Indeksowanie i Wydajność**, jeśli wolisz Zbalansowany lub Responsywny.`, + fr_FR: `**Fonctionnalités** + +- L'action **Configurer l'Indexation** a été remplacée par une action plus large **Indexation et Performances** qui combine performances, statistiques et indexation sur un seul formulaire : + - **Profil de Performance** — trois préréglages (CPU Réduit / Équilibré / Réactif) qui contrôlent la fréquence des requêtes du backend vers bitcoind et le nombre de blocs futurs projetés. CPU Réduit est la nouvelle valeur par défaut — recommandé pour les appareils à faible puissance. + - **Activer les Statistiques** — bascule l'échantillonneur tx/s + vbytes/s du backend. Désactivez-le pour réduire la CPU et les écritures en base de données si vous n'utilisez pas les graphiques du tableau de bord. + - Les options d'indexation sont inchangées (Résumés de Blocs, Goggles, Audit, CPFP). + +**Interne** + +- Les nouvelles installations utilisent \`POLL_RATE_MS=8000\` et \`MEMPOOL_BLOCKS_AMOUNT=4\` (profil CPU Réduit). +- Les installations existantes sont migrées vers le profil CPU Réduit lors de la mise à niveau. Exécutez ensuite **Indexation et Performances** si vous préférez Équilibré ou Réactif.`, + }, + migrations: { + up: async ({ effects }) => { + await configJson.merge(effects, { MEMPOOL: PROFILES[DEFAULT_PROFILE] }) + }, + down: IMPOSSIBLE, + }, +})