@ocap/chain-node 0.0.0-stage → 1.32.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/README.md +234 -2
  2. package/esm/access-log.d.mts +34 -0
  3. package/esm/access-log.mjs +71 -0
  4. package/esm/config-consistency.d.mts +59 -0
  5. package/esm/config-consistency.mjs +220 -0
  6. package/esm/env.d.mts +32 -0
  7. package/esm/env.mjs +218 -0
  8. package/esm/follower-config.d.mts +25 -0
  9. package/esm/follower-config.mjs +57 -0
  10. package/esm/index.d.mts +7 -0
  11. package/esm/index.mjs +7 -0
  12. package/esm/standalone-env.d.mts +92 -0
  13. package/esm/standalone-env.mjs +152 -0
  14. package/esm/start-chain-node.d.mts +14 -0
  15. package/esm/start-chain-node.mjs +1107 -0
  16. package/esm/test-hooks-token.d.mts +12 -0
  17. package/esm/test-hooks-token.mjs +21 -0
  18. package/esm/testing.d.mts +13 -0
  19. package/esm/testing.mjs +23 -0
  20. package/esm/types.d.mts +310 -0
  21. package/esm/types.mjs +1 -0
  22. package/lib/_virtual/rolldown_runtime.cjs +29 -0
  23. package/lib/access-log.cjs +73 -0
  24. package/lib/access-log.d.cts +34 -0
  25. package/lib/config-consistency.cjs +227 -0
  26. package/lib/config-consistency.d.cts +59 -0
  27. package/lib/env.cjs +221 -0
  28. package/lib/env.d.cts +32 -0
  29. package/lib/follower-config.cjs +63 -0
  30. package/lib/follower-config.d.cts +25 -0
  31. package/lib/index.cjs +32 -0
  32. package/lib/index.d.cts +7 -0
  33. package/lib/standalone-env.cjs +165 -0
  34. package/lib/standalone-env.d.cts +92 -0
  35. package/lib/start-chain-node.cjs +1116 -0
  36. package/lib/start-chain-node.d.cts +14 -0
  37. package/lib/test-hooks-token.cjs +24 -0
  38. package/lib/test-hooks-token.d.cts +12 -0
  39. package/lib/testing.cjs +23 -0
  40. package/lib/testing.d.cts +13 -0
  41. package/lib/types.cjs +0 -0
  42. package/lib/types.d.cts +310 -0
  43. package/package.json +78 -4
@@ -0,0 +1,1107 @@
1
+ import { createAccessLogMiddleware } from "./access-log.mjs";
2
+ import { verifyFollowerConfigAgainstUpstream } from "./config-consistency.mjs";
3
+ import { isCompleteChainConfig, rehydrateFollowerChainConfig } from "./follower-config.mjs";
4
+ import { assertValidChainNodeTestHooks } from "./test-hooks-token.mjs";
5
+ import { CustomError } from "@ocap/util/lib/error";
6
+ import { LeaderRouter, Ledger, bytesToHex, canonicalizeMultiCurvePublicKey, createCheckpointSigner, createEnvAnchorPublisher, createEnvColdArchiveReader, createEnvSegmentPublisher, createEnvWitnessRegistry, decodeMultiCurvePublicKey, normalizeDidForCompare, resolveConsensusProposerFromSigner, toHotStuffClusterConfig, verifyDidMatchesMultiCurvePublicKey } from "@arcblock/ledger-core";
7
+ import { SqliteHotStuffStateStore, SqliteLedgerStorage, formatLocalProcessHolderId, hasExistingFollowerDatabases, persistFollowerHighWaterMark, prepareFollowerDataDirectory, readFollowerTrustedSecretKeyIfPresent, unlinkFollowerTrustedSecretKeyIfPresent } from "@arcblock/ledger-sqlite";
8
+ import crypto from "node:crypto";
9
+ import fs from "node:fs";
10
+ import path from "node:path";
11
+ import { isValid } from "@arcblock/did";
12
+ import { createHttpHandler, createSocketHandler } from "@ocap/gql";
13
+ import SqliteIndexDB from "@ocap/indexdb-sqlite";
14
+ import OCAPResolver, { FollowerSyncService, HotStuffNodeRuntime, NodePreferencesManager, applyBootRuntimePreferences, createAdminAuthGuard, createExplorerMiddleware, createFollowerPeerFetchGuard, createNodeDashboardRouter, createNodeMaintenanceController, createUnifiedConsoleMiddleware, isDashboardEnabled, isExplorerEnabled } from "@ocap/resolver";
15
+ import { createAPIHandler } from "@ocap/resolver/api";
16
+ import { Blacklist } from "@ocap/state";
17
+ import SqliteStateDB from "@ocap/statedb-sqlite";
18
+ import { SqliteTrustedStorage } from "@ocap/trusted-storage";
19
+ import cors from "cors";
20
+ import express from "express";
21
+
22
+ //#region src/start-chain-node.ts
23
+ const CHAIN_STATE_ADDR = crypto.createHash("md5").update("OCAP_CHAIN_ADDR").digest("hex");
24
+ const NODE_ID_FILENAME = ".node-id";
25
+ const DEFAULT_DRAIN_TIMEOUT_MS = 5e3;
26
+ const FORMATTED_HOLDER_ID_RE = /:\d+:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
27
+ function createDefaultLogger(prefix = "chain-node") {
28
+ return {
29
+ info: (...args) => console.info(`[${prefix}]`, ...args),
30
+ warn: (...args) => console.warn(`[${prefix}]`, ...args),
31
+ error: (...args) => console.error(`[${prefix}]`, ...args),
32
+ debug: (...args) => console.debug(`[${prefix}]`, ...args)
33
+ };
34
+ }
35
+ function toVariadicLogger(logger) {
36
+ return {
37
+ info: (...args) => logger.info(String(args[0] ?? ""), ...args.slice(1)),
38
+ warn: (...args) => logger.warn(String(args[0] ?? ""), ...args.slice(1)),
39
+ error: (...args) => logger.error(String(args[0] ?? ""), ...args.slice(1)),
40
+ debug: (...args) => logger.debug(String(args[0] ?? ""), ...args.slice(1))
41
+ };
42
+ }
43
+ function classifyFetchKind(rawUrl) {
44
+ try {
45
+ const pathname = new URL(rawUrl).pathname.toLowerCase();
46
+ if (pathname.endsWith("/api/ledger/entries") || pathname.includes("/ledger/entries")) return "entries";
47
+ if (pathname.endsWith("/api/ledger/checkpoint") || pathname.includes("/ledger/checkpoint")) return "checkpoints";
48
+ if (pathname.endsWith(".zst")) return "snapshot-archive";
49
+ if (pathname.endsWith("manifest.json") || pathname.endsWith("latest-snapshot.json")) return "snapshot-manifest";
50
+ return "status";
51
+ } catch {
52
+ return "status";
53
+ }
54
+ }
55
+ function assertSafeNonSymlinkDirectory(rawDataDir) {
56
+ const dataDir = path.resolve(rawDataDir);
57
+ if (fs.existsSync(dataDir)) {
58
+ if (fs.lstatSync(dataDir).isSymbolicLink()) throw new CustomError("SECURITY_VIOLATION", `Refusing symlinked chain node dataDir: ${dataDir}`);
59
+ } else fs.mkdirSync(dataDir, { recursive: true });
60
+ if (fs.lstatSync(dataDir).isSymbolicLink()) throw new CustomError("SECURITY_VIOLATION", `Refusing symlinked chain node dataDir: ${dataDir}`);
61
+ return dataDir;
62
+ }
63
+ function loadOrCreateNodeId(dataDir, explicitNodeId) {
64
+ const nodeIdPath = path.join(dataDir, NODE_ID_FILENAME);
65
+ if (fs.existsSync(nodeIdPath) && fs.lstatSync(nodeIdPath).isSymbolicLink()) throw new CustomError("SECURITY_VIOLATION", `Refusing symlinked .node-id file: ${nodeIdPath}`);
66
+ const trimmedExplicit = explicitNodeId?.trim();
67
+ if (trimmedExplicit) {
68
+ if (!fs.existsSync(nodeIdPath)) {
69
+ const tmpPath$1 = `${nodeIdPath}.tmp.${process.pid}.${crypto.randomBytes(4).toString("hex")}`;
70
+ fs.writeFileSync(tmpPath$1, `${trimmedExplicit}\n`, { mode: 384 });
71
+ fs.renameSync(tmpPath$1, nodeIdPath);
72
+ }
73
+ return trimmedExplicit;
74
+ }
75
+ if (fs.existsSync(nodeIdPath)) {
76
+ const existing = fs.readFileSync(nodeIdPath, "utf8").trim();
77
+ if (existing) return existing;
78
+ }
79
+ const generated = crypto.randomUUID();
80
+ const tmpPath = `${nodeIdPath}.tmp.${process.pid}.${crypto.randomBytes(4).toString("hex")}`;
81
+ fs.writeFileSync(tmpPath, `${generated}\n`, { mode: 384 });
82
+ fs.renameSync(tmpPath, nodeIdPath);
83
+ return generated;
84
+ }
85
+ function resolveStorageLeaseOptions(leaseOption) {
86
+ if (leaseOption === false || leaseOption?.enabled === false) return {
87
+ enabled: false,
88
+ autoAcquire: false
89
+ };
90
+ const ttlMs = typeof leaseOption?.ttlMs === "number" && Number.isFinite(leaseOption.ttlMs) && leaseOption.ttlMs > 0 ? leaseOption.ttlMs : 3e4;
91
+ const startupWaitMs = typeof leaseOption?.startupWaitMs === "number" && Number.isFinite(leaseOption.startupWaitMs) && leaseOption.startupWaitMs >= 0 ? leaseOption.startupWaitMs : Math.ceil(ttlMs * 1.5);
92
+ const rawHolderId = leaseOption?.holderId?.trim();
93
+ const holderId = rawHolderId && FORMATTED_HOLDER_ID_RE.test(rawHolderId) ? rawHolderId : formatLocalProcessHolderId(rawHolderId);
94
+ return {
95
+ enabled: true,
96
+ autoAcquire: leaseOption?.autoAcquire !== false,
97
+ holderId,
98
+ ttlMs,
99
+ startupWaitMs,
100
+ ...leaseOption?.renewIntervalMs !== void 0 ? { renewIntervalMs: leaseOption.renewIntervalMs } : {}
101
+ };
102
+ }
103
+ function buildFollowerNodeRoleConfig(role, resolvedSigner) {
104
+ const hotstuffValidators = Array.isArray(role.hotstuffValidators) ? role.hotstuffValidators : [];
105
+ const isHotStuffCluster = hotstuffValidators.length > 0;
106
+ const hasExplicitTrustedAnchor = role.trustedProposer != null || role.trustedProposerPublicKey != null;
107
+ return {
108
+ role: role.runtimeRole ?? "follower",
109
+ consensusMode: isHotStuffCluster ? "hotstuff" : "single",
110
+ rpcBindHost: null,
111
+ consensusBindHost: null,
112
+ consensusPort: null,
113
+ allowPublicConsensusBind: false,
114
+ hotstuffValidators,
115
+ hotstuffQuorumThreshold: role.hotstuffQuorumThreshold,
116
+ writePolicy: role.writePolicy,
117
+ retentionMode: role.retentionMode ?? "archive",
118
+ hotWindowEntries: role.hotWindowEntries ?? 1e4,
119
+ hotWindowCheckpoints: role.hotWindowCheckpoints ?? 2,
120
+ syncMode: role.syncMode ?? "active-follower",
121
+ upstreamChainUrl: role.upstreamChainUrl ?? null,
122
+ clusterPeerUrls: role.clusterPeerUrls ?? [],
123
+ snapshotBaseUrl: role.snapshotBaseUrl ?? null,
124
+ trustedProposer: isHotStuffCluster ? null : hasExplicitTrustedAnchor ? role.trustedProposer ?? null : resolvedSigner?.address ?? null,
125
+ trustedProposerPublicKey: isHotStuffCluster ? null : hasExplicitTrustedAnchor ? role.trustedProposerPublicKey ?? null : resolvedSigner?.publicKey ?? null,
126
+ allowUnauthenticatedBootstrap: Boolean(role.allowUnauthenticatedBootstrap),
127
+ witnessQuorum: 0,
128
+ witnessSubmitUrls: role.witnessSubmitUrls ?? [],
129
+ anchorWebhookUrl: null
130
+ };
131
+ }
132
+ function adaptColdReaderToArchiveStore(reader) {
133
+ const maybeFull = reader;
134
+ if (typeof maybeFull.putSegment === "function" && typeof maybeFull.hasSegment === "function") return reader;
135
+ return {
136
+ name: maybeFull.name || "chain-node-cold-reader",
137
+ async putSegment() {
138
+ throw new Error("Cold archive reader is read-only");
139
+ },
140
+ async getSegment(chainId, height, options) {
141
+ const seg = await reader.getSegment(chainId, height, options);
142
+ if (!seg) return null;
143
+ return seg;
144
+ },
145
+ async hasSegment(chainId, height) {
146
+ const seg = await reader.getSegment(chainId, height);
147
+ return Boolean(seg);
148
+ },
149
+ ...typeof reader.getLatestHead === "function" ? { getLatestHead: reader.getLatestHead.bind(reader) } : {}
150
+ };
151
+ }
152
+ function formatHttpHostForUrl(bindHost) {
153
+ const trimmed = bindHost.trim();
154
+ if (!trimmed || trimmed === "0.0.0.0" || trimmed === "::" || trimmed === "[::]") return "127.0.0.1";
155
+ if (trimmed.includes(":") && !trimmed.startsWith("[")) return `[${trimmed}]`;
156
+ return trimmed;
157
+ }
158
+ async function waitEventEmitterReady(target) {
159
+ if (typeof target.onReady !== "function") return;
160
+ await new Promise((resolve) => {
161
+ target.onReady(() => resolve());
162
+ });
163
+ }
164
+ async function bootChainNodeOnce(params) {
165
+ const { profile, testHooks, clockNow } = params;
166
+ const cleanupStack = [];
167
+ const pushCleanup = (fn) => cleanupStack.push(fn) - 1;
168
+ const unwindCleanupStack = async () => {
169
+ for (let i = cleanupStack.length - 1; i >= 0; i--) try {
170
+ await cleanupStack[i]();
171
+ } catch {}
172
+ };
173
+ try {
174
+ assertValidChainNodeTestHooks(testHooks);
175
+ if (!profile || typeof profile !== "object" || typeof profile.dataDir !== "string" || !profile.dataDir.trim()) throw new CustomError("INVALID_CONFIG", "ChainProfile.dataDir must be a non-empty directory path");
176
+ const dataDir = assertSafeNonSymlinkDirectory(profile.dataDir);
177
+ const { role } = profile;
178
+ if (!role || role.kind !== "validator" && role.kind !== "follower" && role.kind !== "hotstuff") throw new CustomError("INVALID_CONFIG", "ChainProfile.role.kind must be \"validator\", \"follower\", or \"hotstuff\"");
179
+ if ((role.kind === "validator" || role.kind === "hotstuff") && !isCompleteChainConfig(profile.chainConfig)) throw new CustomError("INVALID_CONFIG", `${role.kind} role requires a complete chainConfig`);
180
+ if ((role.kind === "validator" || role.kind === "hotstuff") && !role.signer) throw new CustomError("INVALID_CONFIG", `${role.kind} role requires role.signer`);
181
+ if (role.kind === "hotstuff" && (!Array.isArray(role.validators) || role.validators.length === 0)) throw new CustomError("INVALID_CONFIG", "HotStuff role requires a non-empty validators list");
182
+ const logger = testHooks?.logger ?? profile.logger ?? createDefaultLogger("chain-node");
183
+ const variadicLogger = toVariadicLogger(logger);
184
+ const followerExpectedChainId = "expectedChainId" in profile ? profile.expectedChainId : void 0;
185
+ const statedbPath = profile.storage?.statedbPath ? path.resolve(profile.storage.statedbPath) : path.join(dataDir, "statedb.sqlite");
186
+ const ledgerPath = profile.storage?.ledgerPath ? path.resolve(profile.storage.ledgerPath) : path.join(dataDir, "ledger.sqlite");
187
+ const indexdbPath = profile.storage?.indexdbPath ? path.resolve(profile.storage.indexdbPath) : path.join(dataDir, "indexdb.sqlite");
188
+ const trustedPath = profile.storage?.trustedPath ? path.resolve(profile.storage.trustedPath) : path.join(dataDir, "trusted.sqlite");
189
+ const nodeId = loadOrCreateNodeId(dataDir, profile.nodeId);
190
+ let resolvedProposer = null;
191
+ let pkOnlyValidatorAddress = null;
192
+ let pkOnlyValidatorPublicKey;
193
+ if (role.kind === "hotstuff") {
194
+ if (!role.signer.secretKey?.trim()) throw new CustomError("INVALID_CONFIG", "HotStuff validator role requires role.signer.secretKey");
195
+ resolvedProposer = resolveConsensusProposerFromSigner(role.signer);
196
+ } else if (role.kind === "validator") if (role.signer.secretKey?.trim()) resolvedProposer = resolveConsensusProposerFromSigner({
197
+ address: role.signer.address,
198
+ secretKey: role.signer.secretKey,
199
+ ...role.signer.publicKey ? { publicKey: role.signer.publicKey } : {},
200
+ ...role.signer.keyType ? { keyType: role.signer.keyType } : {}
201
+ });
202
+ else {
203
+ if (!profile.storage?.trustedStorageSecretKey?.trim()) throw new CustomError("INVALID_CONFIG", "Validator without signer.secretKey requires explicit storage.trustedStorageSecretKey");
204
+ const rawAddr = String(role.signer.address ?? "").trim();
205
+ const normalizedAddr = normalizeDidForCompare(rawAddr);
206
+ const isEthAddr = /^0x[0-9a-fA-F]{40}$/.test(normalizedAddr);
207
+ if (!normalizedAddr || !isEthAddr && !isValid(normalizedAddr)) throw new CustomError("INVALID_CONFIG", `Invalid validator signer address DID: ${rawAddr}`);
208
+ pkOnlyValidatorAddress = normalizedAddr;
209
+ const rawPk = role.signer.publicKey !== void 0 ? String(role.signer.publicKey).trim() : "";
210
+ if (rawPk) {
211
+ const canonicalPk = canonicalizeMultiCurvePublicKey(rawPk);
212
+ if (!canonicalPk || !verifyDidMatchesMultiCurvePublicKey(normalizedAddr, canonicalPk.bytes)) throw new CustomError("INVALID_CONFIG", `Validator signer publicKey does not match address ${normalizedAddr}`);
213
+ pkOnlyValidatorPublicKey = `0x${bytesToHex(canonicalPk.bytes)}`;
214
+ }
215
+ }
216
+ else if (role.signer) resolvedProposer = resolveConsensusProposerFromSigner(role.signer);
217
+ const resolvedLeaseOptions = resolveStorageLeaseOptions(profile.storage?.lease);
218
+ const createLedgerStorage = () => new SqliteLedgerStorage({
219
+ filename: ledgerPath,
220
+ tablePrefix: "ledger",
221
+ entryHashV2: profile.storage?.entryHashV2 ?? "auto",
222
+ lease: resolvedLeaseOptions,
223
+ ...profile.storage?.walAutoCheckpoint !== void 0 ? { walAutoCheckpoint: profile.storage.walAutoCheckpoint } : {}
224
+ });
225
+ let ledgerStorage = null;
226
+ let ledgerCleanupIndex = -1;
227
+ let followerPrep = null;
228
+ const isKeylessFollower = role.kind === "follower" && !profile.storage?.trustedStorageSecretKey?.trim();
229
+ if (role.kind === "follower") {
230
+ if (fs.existsSync(ledgerPath) && fs.statSync(ledgerPath).size > 0) {
231
+ const precheckLedgerStorage = createLedgerStorage();
232
+ ledgerStorage = precheckLedgerStorage;
233
+ ledgerCleanupIndex = pushCleanup(async () => {
234
+ await precheckLedgerStorage.close();
235
+ });
236
+ await precheckLedgerStorage.init();
237
+ if (!hasExistingFollowerDatabases(dataDir, {
238
+ statedbPath,
239
+ ledgerPath
240
+ })) {
241
+ await precheckLedgerStorage.close();
242
+ cleanupStack[ledgerCleanupIndex] = async () => {};
243
+ ledgerStorage = null;
244
+ ledgerCleanupIndex = -1;
245
+ }
246
+ }
247
+ const guardedBootstrapFetch = createFollowerPeerFetchGuard({
248
+ env: { ALLOW_PRIVATE_PEER_URLS: role.allowPrivatePeers ? "1" : "0" },
249
+ trustedStaticUrls: [
250
+ role.upstreamChainUrl,
251
+ role.snapshotBaseUrl,
252
+ ...role.clusterPeerUrls ?? []
253
+ ].filter((u) => Boolean(u && String(u).trim())),
254
+ baseFetch: globalThis.fetch
255
+ });
256
+ const interceptFetch = testHooks?.followerSync?.interceptUpstreamFetch;
257
+ const bootstrapFetchImpl = interceptFetch ? (async (input, init) => {
258
+ const urlStr = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
259
+ return interceptFetch({
260
+ kind: classifyFetchKind(urlStr),
261
+ url: urlStr,
262
+ init
263
+ }, guardedBootstrapFetch);
264
+ }) : guardedBootstrapFetch;
265
+ const explicitExpectedChainId = followerExpectedChainId?.trim() || "";
266
+ const profileChainId = profile.chainConfig?.chainId?.trim() || "";
267
+ if (explicitExpectedChainId && profileChainId && explicitExpectedChainId !== profileChainId) throw new CustomError("SNAPSHOT_CHAIN_ID_MISMATCH", `Follower expectedChainId (${explicitExpectedChainId}) !== profile.chainConfig.chainId (${profileChainId})`);
268
+ followerPrep = await prepareFollowerDataDirectory({
269
+ dataDir,
270
+ roleConfig: buildFollowerNodeRoleConfig(role, resolvedProposer),
271
+ expectedChainId: explicitExpectedChainId || profileChainId || void 0,
272
+ snapshotPrefix: role.snapshotPrefix,
273
+ statedbPath,
274
+ ledgerPath,
275
+ trustedPath,
276
+ keyless: isKeylessFollower,
277
+ fetchImpl: bootstrapFetchImpl
278
+ });
279
+ }
280
+ if (!ledgerStorage) {
281
+ const freshLedgerStorage = createLedgerStorage();
282
+ ledgerStorage = freshLedgerStorage;
283
+ ledgerCleanupIndex = pushCleanup(async () => {
284
+ await freshLedgerStorage.close();
285
+ });
286
+ await freshLedgerStorage.init();
287
+ }
288
+ const trustedSecretKey = role.kind === "follower" && isKeylessFollower ? followerPrep.trustedSecretKey : profile.storage?.trustedStorageSecretKey?.trim() || resolvedProposer?.secretKey || "";
289
+ if (!trustedSecretKey) throw new CustomError("INVALID_CONFIG", "Missing trustedStorageSecretKey for SQLite trusted storage");
290
+ const followerLegacyKey = readFollowerTrustedSecretKeyIfPresent(dataDir);
291
+ const proposerLegacyKey = profile.storage?.trustedStorageSecretKey?.trim() ? resolvedProposer?.secretKey : void 0;
292
+ const trustedStorage = new SqliteTrustedStorage({
293
+ filename: trustedPath,
294
+ secretKey: trustedSecretKey,
295
+ legacySecretKeys: Array.from(new Set([
296
+ ...profile.storage?.legacyTrustedSecretKeys ?? [],
297
+ followerLegacyKey,
298
+ proposerLegacyKey
299
+ ].map((k) => typeof k === "string" ? k.trim() : "").filter((k) => Boolean(k) && k !== trustedSecretKey))),
300
+ retryLimit: profile.storage?.trustedRetryLimit ?? 60,
301
+ allowLegacySignatures: Boolean(followerLegacyKey) || profile.storage?.trustedAllowLegacySignatures !== false
302
+ });
303
+ pushCleanup(async () => {
304
+ await trustedStorage.close();
305
+ });
306
+ const statedb = new SqliteStateDB({
307
+ filename: statedbPath,
308
+ trustedStorage,
309
+ allowTrustedBootstrap: role.kind === "follower" && (Boolean(followerPrep?.bootstrapped) || Boolean(followerPrep?.reanchoredTrusted)),
310
+ ...profile.storage?.walAutoCheckpoint !== void 0 ? { walAutoCheckpoint: profile.storage.walAutoCheckpoint } : {}
311
+ });
312
+ pushCleanup(async () => {
313
+ await statedb.close();
314
+ });
315
+ await statedb.initialize();
316
+ await waitEventEmitterReady(statedb);
317
+ if (!isKeylessFollower) unlinkFollowerTrustedSecretKeyIfPresent(dataDir);
318
+ if (testHooks?.resolver?.beforeStateDbCommit) {
319
+ const hookFn = testHooks.resolver.beforeStateDbCommit;
320
+ const origRunAsLambda = statedb.runAsLambda.bind(statedb);
321
+ statedb.runAsLambda = ((fn, options) => {
322
+ const prevBeforeCommit = options?.beforeCommit;
323
+ return origRunAsLambda(fn, {
324
+ ...options,
325
+ beforeCommit: async (info) => {
326
+ if (prevBeforeCommit) await prevBeforeCommit(info);
327
+ if (!options?.dryRun) await hookFn({
328
+ commitHash: info.commitHash,
329
+ prevHash: info.prevHash,
330
+ seq: info.seq
331
+ });
332
+ }
333
+ });
334
+ });
335
+ }
336
+ let chainConfig;
337
+ if (role.kind === "follower" && !isCompleteChainConfig(profile.chainConfig)) {
338
+ const storedChain = await statedb.chain.get(CHAIN_STATE_ADDR);
339
+ if (!storedChain) throw new CustomError("INVALID_STATE", `Missing chain state (${CHAIN_STATE_ADDR}) in Follower statedb.sqlite (${statedbPath})`);
340
+ const storedChainPartial = storedChain;
341
+ const storedChainId = typeof storedChainPartial.chainId === "string" ? storedChainPartial.chainId.trim() : "";
342
+ const overrideChainId = typeof profile.chainConfig?.chainId === "string" ? profile.chainConfig.chainId.trim() : "";
343
+ if (storedChainId && overrideChainId && overrideChainId !== storedChainId) throw new CustomError("SNAPSHOT_CHAIN_ID_MISMATCH", `Follower profile.chainConfig.chainId (${overrideChainId}) !== statedb chain.chainId (${storedChainId})`);
344
+ chainConfig = rehydrateFollowerChainConfig(storedChain, profile.chainConfig);
345
+ } else {
346
+ const baseConfig = profile.chainConfig;
347
+ if (role.kind === "follower") {
348
+ const storedChain = await statedb.chain.get(CHAIN_STATE_ADDR);
349
+ const storedChainId = storedChain && typeof storedChain.chainId === "string" ? (storedChain.chainId || "").trim() : "";
350
+ if (storedChainId && baseConfig.chainId !== storedChainId) throw new CustomError("SNAPSHOT_CHAIN_ID_MISMATCH", `Follower profile.chainConfig.chainId (${baseConfig.chainId}) !== statedb chain.chainId (${storedChainId})`);
351
+ }
352
+ chainConfig = baseConfig;
353
+ }
354
+ if (role.kind === "follower" && followerExpectedChainId && chainConfig.chainId !== followerExpectedChainId) throw new CustomError("SNAPSHOT_CHAIN_ID_MISMATCH", `Rehydrated Follower chainId (${chainConfig.chainId}) !== expectedChainId (${followerExpectedChainId})`);
355
+ const hotstuffValidators = role.kind === "hotstuff" ? role.validators : role.kind === "follower" ? role.hotstuffValidators ?? [] : [];
356
+ const hotstuffQuorumThreshold = role.kind === "hotstuff" ? role.quorumThreshold : role.kind === "follower" ? role.hotstuffQuorumThreshold : void 0;
357
+ const hotstuffClusterConfig = role.kind === "hotstuff" || hotstuffValidators.length > 0 ? toHotStuffClusterConfig(chainConfig.chainId, hotstuffValidators, hotstuffQuorumThreshold) : void 0;
358
+ const segmentPublisher = profile.da?.segmentPublisher !== void 0 ? profile.da.segmentPublisher : role.kind !== "follower" && profile.da?.env ? createEnvSegmentPublisher({
359
+ env: profile.da.env,
360
+ logger: variadicLogger
361
+ }) : null;
362
+ const explicitColdReader = profile.da?.coldArchiveReader ?? null;
363
+ const envColdReader = !explicitColdReader && profile.da?.env ? createEnvColdArchiveReader({ env: profile.da.env }) : null;
364
+ const coldSegmentStore = explicitColdReader ? adaptColdReaderToArchiveStore(explicitColdReader) : segmentPublisher?.getArchiveStore?.() || (envColdReader ? adaptColdReaderToArchiveStore(envColdReader) : void 0);
365
+ const hasExplicitTrustedAnchor = role.kind === "follower" && (role.trustedProposer != null || role.trustedProposerPublicKey != null);
366
+ const followerExplicitPk = role.kind === "follower" ? followerPrep?.trustedProposerPublicKey || role.trustedProposerPublicKey || null : null;
367
+ const followerFallbackDidCandidate = role.kind === "follower" ? (hasExplicitTrustedAnchor ? null : resolvedProposer?.address || null) || chainConfig.moderator.address : null;
368
+ const activeProposerDid = role.kind === "validator" || role.kind === "hotstuff" ? resolvedProposer?.address ?? pkOnlyValidatorAddress : hotstuffClusterConfig ? chainConfig.moderator.address : followerPrep?.trustedProposer || role.trustedProposer || (followerFallbackDidCandidate && (!followerExplicitPk || verifyDidMatchesMultiCurvePublicKey(followerFallbackDidCandidate, followerExplicitPk)) ? followerFallbackDidCandidate : "");
369
+ const followerFallbackPkCandidate = role.kind === "follower" ? (hasExplicitTrustedAnchor ? null : resolvedProposer?.publicKey || null) || chainConfig.moderator.pk || null : null;
370
+ const activeProposerPk = role.kind === "validator" || role.kind === "hotstuff" ? resolvedProposer?.publicKey ?? pkOnlyValidatorPublicKey : hotstuffClusterConfig ? void 0 : followerExplicitPk || (followerFallbackPkCandidate && (!activeProposerDid || verifyDidMatchesMultiCurvePublicKey(activeProposerDid, followerFallbackPkCandidate)) ? followerFallbackPkCandidate : void 0);
371
+ const witnessQuorum = "witnessQuorum" in role ? role.witnessQuorum : void 0;
372
+ const trustedWitnesses = "trustedWitnesses" in role ? role.trustedWitnesses : void 0;
373
+ const witnessRegistry = createEnvWitnessRegistry({
374
+ chainId: chainConfig.chainId,
375
+ witnessQuorum,
376
+ trustedWitnesses,
377
+ hotstuffClusterConfig,
378
+ expectedProposer: hotstuffClusterConfig ? void 0 : activeProposerDid,
379
+ proposerPublicKey: hotstuffClusterConfig ? void 0 : activeProposerPk,
380
+ logger
381
+ }) || void 0;
382
+ const anchorPublisher = profile.da?.anchorPublisher !== void 0 ? profile.da.anchorPublisher || void 0 : role.kind === "validator" && resolvedProposer && (role.anchorWebhookUrl || profile.da?.env) ? createEnvAnchorPublisher({
383
+ chainId: chainConfig.chainId,
384
+ signer: createCheckpointSigner(resolvedProposer.proposerWallet, resolvedProposer.address),
385
+ anchorSigner: resolvedProposer.address,
386
+ anchorPublicKey: resolvedProposer.publicKey,
387
+ env: {
388
+ ...profile.da?.env ?? {},
389
+ ...role.anchorWebhookUrl ? { ANCHOR_WEBHOOK_URL: role.anchorWebhookUrl } : {}
390
+ },
391
+ logger
392
+ }) || void 0 : void 0;
393
+ const cpBatchSize = testHooks?.checkpoint?.batchSize ?? profile.checkpoint?.batchSize ?? (role.kind === "validator" ? 100 : 1e3);
394
+ const cpTimeoutMs = role.kind === "validator" ? testHooks?.checkpoint?.timeoutMs ?? profile.checkpoint?.timeoutMs ?? 6e4 : 0;
395
+ const cpAuto = role.kind === "validator" ? profile.checkpoint?.auto !== false : false;
396
+ const cpPeriodicTimer = role.kind === "validator" ? profile.checkpoint?.periodicTimer ?? (cpAuto !== false && cpTimeoutMs > 0) : false;
397
+ const ledger = new Ledger(ledgerStorage, {
398
+ chainId: chainConfig.chainId,
399
+ proposer: activeProposerDid,
400
+ proposerWallet: role.kind !== "follower" ? resolvedProposer?.proposerWallet : void 0,
401
+ proposerPublicKey: activeProposerPk || void 0,
402
+ nodeRole: role.kind === "follower" ? role.runtimeRole ?? "follower" : "validator",
403
+ consensusMode: role.kind === "hotstuff" ? "hotstuff" : "single",
404
+ hotstuffClusterConfig,
405
+ segmentPublisher: segmentPublisher || void 0,
406
+ coldSegmentStore,
407
+ witnessRegistry,
408
+ anchorPublisher,
409
+ now: clockNow,
410
+ checkpoint: {
411
+ batchSize: cpBatchSize,
412
+ timeoutMs: cpTimeoutMs,
413
+ auto: cpAuto,
414
+ periodicTimer: cpPeriodicTimer,
415
+ ...profile.checkpoint?.timerIntervalMs !== void 0 ? { timerIntervalMs: profile.checkpoint.timerIntervalMs } : {}
416
+ }
417
+ });
418
+ cleanupStack[ledgerCleanupIndex] = async () => {
419
+ await ledger.close();
420
+ };
421
+ await ledger.initialize();
422
+ const isFileBackedFollower = role.kind === "follower" && ledgerPath !== ":memory:" && statedbPath !== ":memory:";
423
+ const followerHwmProposer = hotstuffClusterConfig ? null : followerPrep?.trustedProposer ?? (role.kind === "follower" ? role.trustedProposer : null) ?? null;
424
+ const followerHwmProposerPk = hotstuffClusterConfig ? null : followerPrep?.trustedProposerPublicKey ?? (role.kind === "follower" ? role.trustedProposerPublicKey : null) ?? null;
425
+ let followerHwmClosed = false;
426
+ let followerHwmTimer = null;
427
+ const cancelFollowerHwmTimer = () => {
428
+ followerHwmClosed = true;
429
+ if (followerHwmTimer) {
430
+ clearTimeout(followerHwmTimer);
431
+ followerHwmTimer = null;
432
+ }
433
+ };
434
+ if (isFileBackedFollower) {
435
+ pushCleanup(async () => {
436
+ cancelFollowerHwmTimer();
437
+ });
438
+ const [initialSeq, initialCp] = await Promise.all([ledger.getLatestSequence(), ledger.getCheckpoint()]);
439
+ let persistedSeq = Math.max(followerPrep?.record?.snapshotSequence ?? 0, followerPrep?.record?.lastKnownSequence ?? 0, initialSeq);
440
+ let persistedCpHeight = Math.max(followerPrep?.record?.checkpointHeight ?? 0, followerPrep?.record?.lastKnownCheckpointHeight ?? 0, initialCp?.height ?? 0);
441
+ let pendingSeq = persistedSeq;
442
+ let pendingCpHeight = persistedCpHeight;
443
+ let lastHotTailPersistAt = 0;
444
+ try {
445
+ persistFollowerHighWaterMark({
446
+ dataDir,
447
+ sequence: pendingSeq,
448
+ checkpointHeight: pendingCpHeight,
449
+ chainId: chainConfig.chainId,
450
+ proposer: followerHwmProposer,
451
+ proposerPublicKey: followerHwmProposerPk
452
+ });
453
+ } catch (err) {
454
+ logger.warn(`[chain-node] initial follower high-water mark persist failed: ${err instanceof Error ? err.message : String(err)}`);
455
+ }
456
+ const flushFollowerHighWaterMark = () => {
457
+ if (followerHwmTimer) {
458
+ clearTimeout(followerHwmTimer);
459
+ followerHwmTimer = null;
460
+ }
461
+ if (followerHwmClosed || pendingSeq <= persistedSeq && pendingCpHeight <= persistedCpHeight) return;
462
+ try {
463
+ persistFollowerHighWaterMark({
464
+ dataDir,
465
+ sequence: pendingSeq,
466
+ checkpointHeight: pendingCpHeight,
467
+ chainId: chainConfig.chainId,
468
+ proposer: followerHwmProposer,
469
+ proposerPublicKey: followerHwmProposerPk
470
+ });
471
+ persistedSeq = Math.max(persistedSeq, pendingSeq);
472
+ persistedCpHeight = Math.max(persistedCpHeight, pendingCpHeight);
473
+ lastHotTailPersistAt = Date.now();
474
+ } catch (err) {
475
+ logger.warn(`[chain-node] live follower high-water mark update failed: ${err instanceof Error ? err.message : String(err)}`);
476
+ }
477
+ };
478
+ const scheduleFollowerHighWaterMark = (immediate) => {
479
+ if (followerHwmClosed || pendingSeq <= persistedSeq && pendingCpHeight <= persistedCpHeight) return;
480
+ if (immediate || Date.now() - lastHotTailPersistAt >= 20) {
481
+ flushFollowerHighWaterMark();
482
+ return;
483
+ }
484
+ if (!followerHwmTimer) {
485
+ followerHwmTimer = setTimeout(() => {
486
+ followerHwmTimer = null;
487
+ flushFollowerHighWaterMark();
488
+ }, 20);
489
+ if (typeof followerHwmTimer.unref === "function") followerHwmTimer.unref();
490
+ }
491
+ };
492
+ const origImportSegment = ledger.importSegment.bind(ledger);
493
+ ledger.importSegment = (async (...args) => {
494
+ await origImportSegment(...args);
495
+ const cp = args[0]?.checkpoint;
496
+ if (cp) {
497
+ if (Number.isFinite(cp.sequence)) pendingSeq = Math.max(pendingSeq, Math.trunc(cp.sequence));
498
+ if (Number.isFinite(cp.height)) pendingCpHeight = Math.max(pendingCpHeight, Math.trunc(cp.height));
499
+ scheduleFollowerHighWaterMark(true);
500
+ }
501
+ });
502
+ const origAppendVerifiedEntries = ledger.appendVerifiedEntries.bind(ledger);
503
+ ledger.appendVerifiedEntries = (async (...args) => {
504
+ await origAppendVerifiedEntries(...args);
505
+ const entries = args[0];
506
+ if (Array.isArray(entries) && entries.length > 0) {
507
+ for (const e of entries) if (e && Number.isFinite(e.sequence)) pendingSeq = Math.max(pendingSeq, Math.trunc(e.sequence));
508
+ scheduleFollowerHighWaterMark(false);
509
+ }
510
+ });
511
+ const origSaveCheckpoint = ledgerStorage.saveCheckpoint.bind(ledgerStorage);
512
+ ledgerStorage.saveCheckpoint = (async (...args) => {
513
+ await origSaveCheckpoint(...args);
514
+ const cp = args[0];
515
+ if (cp) {
516
+ if (Number.isFinite(cp.sequence)) pendingSeq = Math.max(pendingSeq, Math.trunc(cp.sequence));
517
+ if (Number.isFinite(cp.height)) pendingCpHeight = Math.max(pendingCpHeight, Math.trunc(cp.height));
518
+ scheduleFollowerHighWaterMark(true);
519
+ }
520
+ });
521
+ }
522
+ const indexDbExisted = fs.existsSync(indexdbPath);
523
+ const indexdb = new SqliteIndexDB({
524
+ filename: indexdbPath,
525
+ ...profile.storage?.indexWalAutoCheckpoint !== void 0 ? { walAutoCheckpoint: profile.storage.indexWalAutoCheckpoint } : {}
526
+ });
527
+ pushCleanup(async () => {
528
+ await indexdb.close();
529
+ });
530
+ await indexdb.initialize();
531
+ await waitEventEmitterReady(indexdb);
532
+ let resolverRef = null;
533
+ const adminEnv = profile.http.adminEnv ?? {};
534
+ const preferencesManager = new NodePreferencesManager({
535
+ dataDir,
536
+ env: adminEnv,
537
+ staticBlockedAddresses: profile.blacklist?.staticBlockedAddresses,
538
+ baseReservedSymbols: Array.from(new Set([
539
+ chainConfig.token?.symbol || "TBA",
540
+ ...chainConfig.reservedSymbols ?? [],
541
+ ...profile.reservedSymbols ?? []
542
+ ].filter(Boolean))),
543
+ getNodeRole: () => resolverRef?.getNodeRuntime?.()?.role || (role.kind === "follower" ? role.runtimeRole ?? "follower" : "validator"),
544
+ getConsensusMode: () => role.kind === "hotstuff" || Boolean(hotstuffClusterConfig) ? "hotstuff" : "single",
545
+ onApply: async (snap) => {
546
+ if (snap.runtime.txMaxRequest !== void 0 && resolverRef?.setMaxTxRequest) resolverRef.setMaxTxRequest(snap.runtime.txMaxRequest);
547
+ const activeRuntime = resolverRef?.getNodeRuntime?.();
548
+ if (activeRuntime && typeof activeRuntime.updateRuntimeConfig === "function") await Promise.resolve(activeRuntime.updateRuntimeConfig(snap.runtime));
549
+ }
550
+ });
551
+ const resolveTrustedAccounts = profile.blacklist?.getTrustedAccounts;
552
+ const filter = new Blacklist({
553
+ dumpPath: profile.blacklist?.dumpPath ?? path.join(dataDir, "filter.json"),
554
+ dumpInterval: profile.blacklist?.dumpIntervalMs ?? 1e3,
555
+ getBlockedAccounts: async () => [],
556
+ getTrustedAccounts: resolveTrustedAccounts ? async () => await resolveTrustedAccounts() : async () => preferencesManager.getTrustedAccounts()
557
+ });
558
+ pushCleanup(async () => {
559
+ filter.dispose();
560
+ });
561
+ const resolverChainConfig = profile.genesisTime && !chainConfig.genesisTime ? {
562
+ ...chainConfig,
563
+ genesisTime: profile.genesisTime
564
+ } : chainConfig;
565
+ const resolver = new OCAPResolver({
566
+ statedb,
567
+ indexdb,
568
+ ledger,
569
+ filter,
570
+ admissionBlockedCheck: profile.blacklist?.admissionBlockedCheck ?? ((addr) => preferencesManager.isBlocked(addr)),
571
+ admissionReservedSymbolCheck: profile.blacklist?.admissionReservedSymbolCheck ?? ((sym) => preferencesManager.isReservedSymbol(sym)),
572
+ config: resolverChainConfig,
573
+ validateTokenConfig: role.kind === "follower" ? false : profile.validateTokenConfig ?? true,
574
+ skipInitializeStateDB: role.kind === "follower",
575
+ deferInitialize: true,
576
+ consensusMode: role.kind === "hotstuff" || Boolean(hotstuffClusterConfig) ? "hotstuff" : "single",
577
+ txQueueConfig: profile.txQueue,
578
+ now: clockNow,
579
+ logger
580
+ });
581
+ resolverRef = resolver;
582
+ pushCleanup(async () => {
583
+ await resolver.shutdown();
584
+ ledger.setNodeRole("readonly");
585
+ });
586
+ const initialPrefs = preferencesManager.getSnapshot();
587
+ if (initialPrefs.runtime.txMaxRequest !== void 0) resolver.setMaxTxRequest(initialPrefs.runtime.txMaxRequest);
588
+ await resolver.initialize();
589
+ if (role.kind === "follower") await verifyFollowerConfigAgainstUpstream({
590
+ mode: profile.configCheck?.mode ?? "off",
591
+ localConfig: resolver.config,
592
+ upstreamUrl: role.upstreamChainUrl ?? role.clusterPeerUrls?.[0] ?? null,
593
+ fetchUpstreamConfig: profile.configCheck?.fetchUpstreamConfig,
594
+ hasLocalState: !followerPrep?.bootstrapped && await ledger.getLatestSequence() > 0,
595
+ ...profile.configCheck?.retryDeadlineMs !== void 0 ? { retryDeadlineMs: profile.configCheck.retryDeadlineMs } : {},
596
+ logger
597
+ });
598
+ let followerSync;
599
+ let hotstuffRuntime;
600
+ if (role.kind === "follower") {
601
+ const hotstuffPeerUrls = (role.hotstuffValidators ?? []).map((v) => v.rpcUrl);
602
+ const mergedPeerUrls = Array.from(new Set([...role.clusterPeerUrls ?? [], ...hotstuffPeerUrls]));
603
+ const leaderRouter = Boolean(role.upstreamChainUrl) || mergedPeerUrls.length > 0 ? new LeaderRouter({
604
+ chainId: chainConfig.chainId,
605
+ upstreamUrl: role.upstreamChainUrl ?? null,
606
+ peerUrls: mergedPeerUrls,
607
+ hotstuffClusterConfig,
608
+ trustedProposer: followerPrep?.trustedProposer || role.trustedProposer || void 0,
609
+ trustedProposerPublicKey: followerPrep?.trustedProposerPublicKey || role.trustedProposerPublicKey || void 0,
610
+ allowUnauthenticatedLeaderFailover: Boolean(role.allowUnauthenticatedBootstrap)
611
+ }) : void 0;
612
+ const coldReaderForFollower = explicitColdReader ?? envColdReader ?? void 0;
613
+ followerSync = new FollowerSyncService({
614
+ resolver,
615
+ role: role.runtimeRole ?? "follower",
616
+ writePolicy: role.writePolicy,
617
+ syncMode: role.syncMode ?? "active-follower",
618
+ retentionMode: role.retentionMode ?? "archive",
619
+ hotWindowEntries: role.hotWindowEntries,
620
+ hotWindowCheckpoints: role.hotWindowCheckpoints,
621
+ upstreamUrl: role.upstreamChainUrl ?? null,
622
+ peerUrls: mergedPeerUrls,
623
+ snapshotBaseUrl: role.snapshotBaseUrl ?? null,
624
+ coldArchiveStore: coldReaderForFollower,
625
+ leaderRouter,
626
+ hotstuffClusterConfig,
627
+ trustedProposer: followerPrep?.trustedProposer ?? role.trustedProposer ?? null,
628
+ trustedProposerPublicKey: followerPrep?.trustedProposerPublicKey ?? role.trustedProposerPublicKey ?? null,
629
+ allowUnauthenticated: Boolean(role.allowUnauthenticatedBootstrap),
630
+ disallowKeylessCascadedUpstream: Boolean(role.disallowKeylessCascadedUpstream),
631
+ witnessWallet: role.witnessWallet,
632
+ witnessSubmitUrls: role.witnessSubmitUrls,
633
+ pollIntervalMs: role.pollIntervalMs,
634
+ maxSyncLag: role.maxSyncLag,
635
+ maxUpstreamStaleMs: role.maxUpstreamStaleMs,
636
+ startPaused: testHooks?.followerSync?.startPaused,
637
+ artificialPollDelayMs: testHooks?.followerSync?.artificialPollDelayMs,
638
+ interceptUpstreamFetch: testHooks?.followerSync?.interceptUpstreamFetch,
639
+ ...profile.replayGuards?.futureTimestamp ? { futureTimestampGuard: {
640
+ ...profile.replayGuards.futureTimestamp,
641
+ now: clockNow
642
+ } } : {},
643
+ env: { ALLOW_PRIVATE_PEER_URLS: role.allowPrivatePeers ? "1" : "0" }
644
+ });
645
+ resolver.setNodeRuntime(followerSync);
646
+ if (testHooks?.followerSync?.onControllerReady) {
647
+ const syncRef = followerSync;
648
+ testHooks.followerSync.onControllerReady({
649
+ pause: () => syncRef.pause(),
650
+ resume: () => syncRef.resume(),
651
+ isPaused: () => syncRef.isPaused(),
652
+ triggerSyncOnce: () => syncRef.triggerSyncOnce()
653
+ });
654
+ }
655
+ if (Boolean(followerPrep?.bootstrapped) || !indexDbExisted) {
656
+ await resolver.rebuildIndex();
657
+ await followerSync.replayer.indexExistingOrphanEntries();
658
+ }
659
+ } else if (role.kind === "hotstuff") {
660
+ const hotstuffStateStore = new SqliteHotStuffStateStore(ledgerStorage);
661
+ hotstuffRuntime = new HotStuffNodeRuntime({
662
+ resolver,
663
+ validatorDid: resolvedProposer.address,
664
+ validatorWallet: resolvedProposer.proposerWallet,
665
+ validatorPublicKey: resolvedProposer.publicKey,
666
+ validators: role.validators,
667
+ quorumThreshold: role.quorumThreshold,
668
+ consensusBindHost: role.consensusBindHost,
669
+ consensusPort: role.consensusPort,
670
+ allowPublicBind: Boolean(role.allowPublicConsensusBind),
671
+ allowPrivateHttpPeers: Boolean(role.allowPrivatePeers),
672
+ writePolicy: role.writePolicy ?? "forward",
673
+ stateStore: hotstuffStateStore,
674
+ onOutboundConsensusRequest: testHooks?.hotstuff?.onOutboundConsensusRequest ?? testHooks?.hotstuff?.interceptOutboundRpc
675
+ });
676
+ resolver.setNodeRuntime(hotstuffRuntime);
677
+ }
678
+ await applyBootRuntimePreferences({
679
+ runtime: resolver.getNodeRuntime?.(),
680
+ preferencesManager,
681
+ env: adminEnv,
682
+ logger: variadicLogger
683
+ });
684
+ if (followerSync) {
685
+ const syncRef = followerSync;
686
+ pushCleanup(async () => {
687
+ await syncRef.close();
688
+ });
689
+ await followerSync.start();
690
+ } else if (hotstuffRuntime) {
691
+ const hsRef = hotstuffRuntime;
692
+ pushCleanup(async () => {
693
+ await hsRef.close();
694
+ });
695
+ await hotstuffRuntime.start();
696
+ }
697
+ const app = express();
698
+ let isShuttingDown = false;
699
+ let activeResponses = 0;
700
+ const drainWaiters = /* @__PURE__ */ new Set();
701
+ if (profile.http.corsOrigins !== false) app.use(profile.http.corsOrigins !== void 0 && profile.http.corsOrigins !== true ? cors({ origin: profile.http.corsOrigins }) : cors());
702
+ app.use((_req, res, next) => {
703
+ if (isShuttingDown) {
704
+ res.setHeader("Connection", "close");
705
+ res.setHeader("Cache-Control", "no-store");
706
+ res.status(503).json({
707
+ code: "SERVICE_UNAVAILABLE",
708
+ error: "Chain node is shutting down"
709
+ });
710
+ return;
711
+ }
712
+ activeResponses++;
713
+ let settled = false;
714
+ const markDone = () => {
715
+ if (settled) return;
716
+ settled = true;
717
+ activeResponses = Math.max(0, activeResponses - 1);
718
+ if (activeResponses === 0 && drainWaiters.size > 0) {
719
+ for (const notify of Array.from(drainWaiters)) notify();
720
+ drainWaiters.clear();
721
+ }
722
+ };
723
+ res.once("finish", markDone);
724
+ res.once("close", markDone);
725
+ next();
726
+ });
727
+ if (profile.http.enableAccessLog) app.use(createAccessLogMiddleware(logger));
728
+ app.head("/", (_req, res) => {
729
+ res.status(200).send("OK");
730
+ });
731
+ const maintenanceController = createNodeMaintenanceController({
732
+ resolver,
733
+ preferencesManager,
734
+ replayFilter: filter,
735
+ pruneIndexDbFn: profile.maintenance?.pruneIndexDbFn ? ({ findOnly }) => Promise.resolve(profile.maintenance.pruneIndexDbFn({
736
+ findOnly,
737
+ indexdb,
738
+ statedb
739
+ })) : void 0,
740
+ requireAllowUpdateTokenDistributionEnv: profile.maintenance?.requireAllowUpdateTokenDistributionEnv ?? false,
741
+ env: profile.maintenance?.env ?? adminEnv
742
+ });
743
+ const effectiveRetentionMode = role.retentionMode ?? "archive";
744
+ const effectiveSnapshotBaseUrl = "snapshotBaseUrl" in role ? role.snapshotBaseUrl ?? null : null;
745
+ const adminAuthGuard = createAdminAuthGuard({ env: adminEnv });
746
+ const nodeDashboardRouter = createNodeDashboardRouter({
747
+ resolver,
748
+ dataDir,
749
+ retentionMode: effectiveRetentionMode,
750
+ preferencesManager,
751
+ maintenanceController,
752
+ authGuard: adminAuthGuard,
753
+ env: adminEnv
754
+ });
755
+ if (profile.configureApp) await profile.configureApp(app, {
756
+ nodeId,
757
+ dataDir,
758
+ role: role.kind,
759
+ config: chainConfig,
760
+ statedb,
761
+ indexdb,
762
+ ledger,
763
+ resolver,
764
+ preferencesManager,
765
+ maintenanceController
766
+ });
767
+ const server = createSocketHandler({
768
+ indexdb,
769
+ app,
770
+ wsOptions: { broadcastEventName: `@arcblock/ws:broadcast:${nodeId}:${crypto.randomUUID()}` }
771
+ });
772
+ pushCleanup(async () => {
773
+ isShuttingDown = true;
774
+ await new Promise((resolveClose) => {
775
+ server.close(() => resolveClose());
776
+ });
777
+ });
778
+ app.use("/api", createAPIHandler({
779
+ resolver,
780
+ retentionMode: effectiveRetentionMode,
781
+ snapshotBaseUrl: effectiveSnapshotBaseUrl,
782
+ nodeId,
783
+ preferencesManager,
784
+ authGuard: adminAuthGuard,
785
+ nodeDashboardRouter,
786
+ nodeDashboardOptions: {
787
+ env: adminEnv,
788
+ authGuard: adminAuthGuard
789
+ }
790
+ }));
791
+ app.use("/node", nodeDashboardRouter);
792
+ if (profile.http.enableExplorer ?? isExplorerEnabled(adminEnv)) app.use(createExplorerMiddleware({
793
+ getConfig: () => resolver.config,
794
+ explorerDistDir: profile.http.explorerDistDir
795
+ }));
796
+ if (profile.http.enableDashboard ?? isDashboardEnabled(adminEnv)) app.use(createUnifiedConsoleMiddleware({
797
+ mountPath: "/dashboard",
798
+ getConfig: () => resolver.config
799
+ }));
800
+ app.use("/consensus", (_req, res) => {
801
+ res.status(404).json({ error: "Not found" });
802
+ });
803
+ app.use("/", createHttpHandler({
804
+ resolver,
805
+ onError: profile.http.onGraphqlError ? (err) => {
806
+ profile.http.onGraphqlError(err);
807
+ } : () => {}
808
+ }));
809
+ const bindHost = profile.http.host?.trim() || "127.0.0.1";
810
+ const requestedPort = profile.http.port;
811
+ if (!Number.isSafeInteger(requestedPort) || requestedPort < 0 || requestedPort > 65535) throw new CustomError("INVALID_CONFIG", `Invalid http.port="${String(requestedPort)}": expected 0..65535`);
812
+ await new Promise((resolveListen, rejectListen) => {
813
+ const onError = (err) => {
814
+ server.off("listening", onListening);
815
+ rejectListen(err);
816
+ };
817
+ const onListening = () => {
818
+ server.off("error", onError);
819
+ resolveListen();
820
+ };
821
+ server.once("error", onError);
822
+ server.once("listening", onListening);
823
+ server.listen(requestedPort, bindHost);
824
+ });
825
+ const addressInfo = server.address();
826
+ const boundPort = addressInfo && typeof addressInfo === "object" && typeof addressInfo.port === "number" ? addressInfo.port : requestedPort;
827
+ const urlHost = formatHttpHostForUrl(bindHost);
828
+ const endpoint = `http://${urlHost}:${boundPort}`;
829
+ const wsUrl = `ws://${urlHost}:${boundPort}`;
830
+ if (testHooks?.onAfterBoot) await testHooks.onAfterBoot({
831
+ dataDir,
832
+ statedb,
833
+ ledger,
834
+ trustedStorage
835
+ });
836
+ const drainTimeoutMs = typeof profile.http.drainTimeoutMs === "number" && Number.isFinite(profile.http.drainTimeoutMs) && profile.http.drainTimeoutMs >= 0 ? profile.http.drainTimeoutMs : DEFAULT_DRAIN_TIMEOUT_MS;
837
+ const waitForActiveHttpDrain = async () => {
838
+ if (activeResponses <= 0 || drainTimeoutMs <= 0) return;
839
+ await new Promise((resolveDrain) => {
840
+ let timer = null;
841
+ const finish = () => {
842
+ if (timer) {
843
+ clearTimeout(timer);
844
+ timer = null;
845
+ }
846
+ drainWaiters.delete(finish);
847
+ resolveDrain();
848
+ };
849
+ drainWaiters.add(finish);
850
+ timer = setTimeout(finish, drainTimeoutMs);
851
+ if (typeof timer.unref === "function") timer.unref();
852
+ if (activeResponses <= 0) finish();
853
+ });
854
+ };
855
+ let stopPromise = null;
856
+ const stop = () => {
857
+ if (stopPromise) return stopPromise;
858
+ stopPromise = (async () => {
859
+ let firstError = null;
860
+ const captureErr = (err) => {
861
+ if (firstError === null) firstError = err;
862
+ };
863
+ try {
864
+ if (followerSync) await followerSync.close().catch(captureErr);
865
+ cancelFollowerHwmTimer();
866
+ if (hotstuffRuntime) await hotstuffRuntime.close().catch(captureErr);
867
+ isShuttingDown = true;
868
+ server.closeIdleConnections?.();
869
+ await waitForActiveHttpDrain();
870
+ await new Promise((resolveClose) => {
871
+ server.close(() => resolveClose());
872
+ });
873
+ await resolver.shutdown().catch(captureErr);
874
+ ledger.setNodeRole("readonly");
875
+ try {
876
+ filter.dispose();
877
+ } catch (err) {
878
+ captureErr(err);
879
+ }
880
+ await statedb.close().catch(captureErr);
881
+ await trustedStorage.close().catch(captureErr);
882
+ await indexdb.close().catch(captureErr);
883
+ if (isFileBackedFollower) try {
884
+ const [latestSeq, latestCp] = await Promise.all([ledger.getLatestSequence(), ledger.getCheckpoint()]);
885
+ persistFollowerHighWaterMark({
886
+ dataDir,
887
+ sequence: latestSeq,
888
+ checkpointHeight: latestCp?.height ?? 0,
889
+ chainId: chainConfig.chainId,
890
+ proposer: followerHwmProposer,
891
+ proposerPublicKey: followerHwmProposerPk
892
+ });
893
+ } catch (err) {
894
+ captureErr(err);
895
+ }
896
+ } finally {
897
+ await ledger.close().catch(captureErr);
898
+ }
899
+ if (firstError !== null) throw firstError;
900
+ })();
901
+ return stopPromise;
902
+ };
903
+ const finalProposerDid = (role.kind === "follower" ? followerSync?.getTrustedProposer() : null) || ledger.getProposer?.() || null;
904
+ const finalProposerPk = (role.kind === "follower" ? followerSync?.getTrustedProposerPublicKey() : null) || ledger.getProposerPublicKey?.() || null;
905
+ const signatureKeyType = finalProposerPk ? decodeMultiCurvePublicKey(finalProposerPk)?.curve ?? null : null;
906
+ return {
907
+ endpoint,
908
+ rpcUrl: endpoint,
909
+ wsUrl,
910
+ port: boundPort,
911
+ host: bindHost,
912
+ chainId: chainConfig.chainId,
913
+ role: role.kind,
914
+ nodeId,
915
+ dataDir,
916
+ get proposerDid() {
917
+ return (role.kind === "follower" ? followerSync?.getTrustedProposer() : null) || ledger.getProposer?.() || finalProposerDid;
918
+ },
919
+ get proposerPublicKey() {
920
+ return (role.kind === "follower" ? followerSync?.getTrustedProposerPublicKey() : null) || ledger.getProposerPublicKey?.() || finalProposerPk;
921
+ },
922
+ get signatureKeyType() {
923
+ const pk = (role.kind === "follower" ? followerSync?.getTrustedProposerPublicKey() : null) || ledger.getProposerPublicKey?.() || finalProposerPk;
924
+ return pk ? decodeMultiCurvePublicKey(pk)?.curve ?? null : signatureKeyType;
925
+ },
926
+ app,
927
+ resolver,
928
+ ledger,
929
+ ledgerStorage,
930
+ statedb,
931
+ indexdb,
932
+ trustedStorage,
933
+ server,
934
+ ...followerSync ? { followerSync } : {},
935
+ ...hotstuffRuntime ? { hotstuffRuntime } : {},
936
+ preferencesManager,
937
+ maintenanceController,
938
+ stop
939
+ };
940
+ } catch (err) {
941
+ await unwindCleanupStack();
942
+ throw err;
943
+ }
944
+ }
945
+ function isStartChainNodeOptions(input) {
946
+ return Boolean(input && typeof input === "object" && "profile" in input && input.profile);
947
+ }
948
+ async function startChainNode(optionsOrProfile) {
949
+ const initialProfile = isStartChainNodeOptions(optionsOrProfile) ? optionsOrProfile.profile : optionsOrProfile;
950
+ const testHooks = optionsOrProfile.testHooks;
951
+ assertValidChainNodeTestHooks(testHooks);
952
+ const baseNow = testHooks?.now ?? (() => Date.now());
953
+ let clockOffsetMs = Math.trunc((testHooks?.initialClockOffsetMs ?? 0) + (testHooks?.initialClockOffsetSeconds ?? 0) * 1e3);
954
+ const clockNow = () => baseNow() + clockOffsetMs;
955
+ let currentProfile = initialProfile;
956
+ let currentBooted = await bootChainNodeOnce({
957
+ profile: currentProfile,
958
+ testHooks,
959
+ clockNow
960
+ });
961
+ const advanceClockFn = testHooks !== void 0 ? (seconds) => {
962
+ assertValidChainNodeTestHooks(testHooks);
963
+ if (typeof seconds !== "number" || !Number.isFinite(seconds)) throw new CustomError("INVALID_PARAMS", `advanceClock requires a finite number of seconds, got ${String(seconds)}`);
964
+ clockOffsetMs += Math.trunc(seconds * 1e3);
965
+ return clockNow();
966
+ } : void 0;
967
+ let lifecycleChain = Promise.resolve();
968
+ const withLifecycleLock = (fn) => {
969
+ const next = lifecycleChain.then(fn, fn);
970
+ lifecycleChain = next.then(() => void 0, () => void 0);
971
+ return next;
972
+ };
973
+ const handle = {
974
+ get endpoint() {
975
+ return currentBooted.endpoint;
976
+ },
977
+ get rpcUrl() {
978
+ return currentBooted.rpcUrl;
979
+ },
980
+ get wsUrl() {
981
+ return currentBooted.wsUrl;
982
+ },
983
+ get port() {
984
+ return currentBooted.port;
985
+ },
986
+ get host() {
987
+ return currentBooted.host;
988
+ },
989
+ get chainId() {
990
+ return currentBooted.chainId;
991
+ },
992
+ get role() {
993
+ return currentBooted.role;
994
+ },
995
+ get nodeId() {
996
+ return currentBooted.nodeId;
997
+ },
998
+ get dataDir() {
999
+ return currentBooted.dataDir;
1000
+ },
1001
+ get proposerDid() {
1002
+ return currentBooted.proposerDid;
1003
+ },
1004
+ get proposerPublicKey() {
1005
+ return currentBooted.proposerPublicKey;
1006
+ },
1007
+ get signatureKeyType() {
1008
+ return currentBooted.signatureKeyType;
1009
+ },
1010
+ get app() {
1011
+ return currentBooted.app;
1012
+ },
1013
+ get resolver() {
1014
+ return currentBooted.resolver;
1015
+ },
1016
+ get ledger() {
1017
+ return currentBooted.ledger;
1018
+ },
1019
+ get ledgerStorage() {
1020
+ return currentBooted.ledgerStorage;
1021
+ },
1022
+ get statedb() {
1023
+ return currentBooted.statedb;
1024
+ },
1025
+ get indexdb() {
1026
+ return currentBooted.indexdb;
1027
+ },
1028
+ get trustedStorage() {
1029
+ return currentBooted.trustedStorage;
1030
+ },
1031
+ get server() {
1032
+ return currentBooted.server;
1033
+ },
1034
+ get followerSync() {
1035
+ return currentBooted.followerSync;
1036
+ },
1037
+ get hotstuffRuntime() {
1038
+ return currentBooted.hotstuffRuntime;
1039
+ },
1040
+ get preferencesManager() {
1041
+ return currentBooted.preferencesManager;
1042
+ },
1043
+ get maintenanceController() {
1044
+ return currentBooted.maintenanceController;
1045
+ },
1046
+ async ledgerHealth() {
1047
+ return currentBooted.ledger.getHealth();
1048
+ },
1049
+ ...advanceClockFn ? { advanceClock: advanceClockFn } : {},
1050
+ async restart(nextProfile) {
1051
+ return withLifecycleLock(async () => {
1052
+ const previousPort = currentBooted.port;
1053
+ await currentBooted.stop();
1054
+ const mergedHttp = {
1055
+ ...currentProfile.http,
1056
+ ...nextProfile?.http ?? {},
1057
+ port: nextProfile?.http?.port !== void 0 ? nextProfile.http.port : previousPort
1058
+ };
1059
+ const mergedProfile = {
1060
+ ...currentProfile,
1061
+ ...nextProfile ?? {},
1062
+ http: mergedHttp,
1063
+ ...currentProfile.storage || nextProfile?.storage ? { storage: {
1064
+ ...currentProfile.storage ?? {},
1065
+ ...nextProfile?.storage ?? {}
1066
+ } } : {},
1067
+ ...currentProfile.checkpoint || nextProfile?.checkpoint ? { checkpoint: {
1068
+ ...currentProfile.checkpoint ?? {},
1069
+ ...nextProfile?.checkpoint ?? {}
1070
+ } } : {},
1071
+ ...currentProfile.da || nextProfile?.da ? { da: {
1072
+ ...currentProfile.da ?? {},
1073
+ ...nextProfile?.da ?? {}
1074
+ } } : {},
1075
+ ...currentProfile.blacklist || nextProfile?.blacklist ? { blacklist: {
1076
+ ...currentProfile.blacklist ?? {},
1077
+ ...nextProfile?.blacklist ?? {}
1078
+ } } : {},
1079
+ ...currentProfile.txQueue || nextProfile?.txQueue ? { txQueue: {
1080
+ ...currentProfile.txQueue ?? {},
1081
+ ...nextProfile?.txQueue ?? {}
1082
+ } } : {},
1083
+ ...currentProfile.maintenance || nextProfile?.maintenance ? { maintenance: {
1084
+ ...currentProfile.maintenance ?? {},
1085
+ ...nextProfile?.maintenance ?? {}
1086
+ } } : {}
1087
+ };
1088
+ currentBooted = await bootChainNodeOnce({
1089
+ profile: mergedProfile,
1090
+ testHooks,
1091
+ clockNow
1092
+ });
1093
+ currentProfile = mergedProfile;
1094
+ return handle;
1095
+ });
1096
+ },
1097
+ async stop() {
1098
+ return withLifecycleLock(async () => {
1099
+ await currentBooted.stop();
1100
+ });
1101
+ }
1102
+ };
1103
+ return handle;
1104
+ }
1105
+
1106
+ //#endregion
1107
+ export { startChainNode };