@ocap/chain-node 1.32.0 → 1.32.2

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.
@@ -66,6 +66,87 @@ function formatBlockletEnvLeftoversWarning({ standaloneMarkers, leftovers, readB
66
66
  const read = readByChain.length ? ` ${readByChain.join(", ")} still feed key/path fallbacks when the CHAIN_* equivalent is unset.` : "";
67
67
  return `[chain] standalone env (${standaloneMarkers.join(", ")}) also carries Blocklet Server variables: ${leftovers.join(", ")}.${read} Remove them so CHAIN_* is the only source (docs/ops/chain-env-mapping.md, #1923)`;
68
68
  }
69
+ /** Env names of the `transaction.*` master switches a chain app maps into its chain config. */
70
+ const TRANSACTION_SWITCH_ENV = {
71
+ bridge: "CHAIN_TX_BRIDGE_ENABLED",
72
+ rollupV1: "CHAIN_TX_ROLLUP_V1_ENABLED"
73
+ };
74
+ /** `1`/`true` -> true, `0`/`false` -> false, unset/blank -> undefined; anything else fails startup. */
75
+ function parseStrictBoolEnv(env, name) {
76
+ const raw = String(env[name] ?? "").trim().toLowerCase();
77
+ if (!raw) return void 0;
78
+ if (raw === "1" || raw === "true") return true;
79
+ if (raw === "0" || raw === "false") return false;
80
+ throw new Error(`Invalid ${name}="${env[name]}": expected 1/true or 0/false (or leave it empty for the default)`);
81
+ }
82
+ /**
83
+ * `transaction.bridge` / `transaction.rollupV1` from env. Only explicitly set switches are returned, so an env
84
+ * without them leaves the chain config exactly as before (bridge absent = disabled, rollupV1 absent = enabled).
85
+ */
86
+ function resolveTransactionSwitchesFromEnv(env = process.env) {
87
+ const out = {};
88
+ const bridge = parseStrictBoolEnv(env, TRANSACTION_SWITCH_ENV.bridge);
89
+ if (bridge !== void 0) out.bridge = { enabled: bridge };
90
+ const rollupV1 = parseStrictBoolEnv(env, TRANSACTION_SWITCH_ENV.rollupV1);
91
+ if (rollupV1 !== void 0) out.rollupV1 = { enabled: rollupV1 };
92
+ return out;
93
+ }
94
+ /**
95
+ * `CHAIN_CONFIG_CHECK`: what a follower does with the startup comparison of its consensus config against the
96
+ * upstream leader's `getConfig` (`off` default: no request at all; `warn`: log differences and start; `enforce`:
97
+ * refuse to start on any difference or when the upstream cannot be asked).
98
+ */
99
+ function resolveConfigCheckModeFromEnv(env = process.env) {
100
+ const raw = String(env.CHAIN_CONFIG_CHECK ?? "").trim().toLowerCase();
101
+ if (!raw) return "off";
102
+ if (raw === "off" || raw === "warn" || raw === "enforce") return raw;
103
+ throw new Error(`Invalid CHAIN_CONFIG_CHECK="${env.CHAIN_CONFIG_CHECK}": expected off, warn or enforce`);
104
+ }
105
+ const DEFAULT_CONFIG_CHECK_TIMEOUT_SECONDS = 60;
106
+ /**
107
+ * `CHAIN_CONFIG_CHECK_TIMEOUT_SEC` (non-negative integer seconds, default 60): how long `enforce` keeps retrying an
108
+ * unreachable / bad upstream before it decides (start with a warning on existing local state, refuse when fresh).
109
+ */
110
+ function resolveConfigCheckTimeoutMsFromEnv(env = process.env) {
111
+ const raw = env.CHAIN_CONFIG_CHECK_TIMEOUT_SEC;
112
+ if (raw === void 0 || raw === "") return DEFAULT_CONFIG_CHECK_TIMEOUT_SECONDS * 1e3;
113
+ if (!/^(?:0|[1-9]\d*)$/.test(raw) || !Number.isSafeInteger(Number(raw) * 1e3)) throw new Error(`Invalid CHAIN_CONFIG_CHECK_TIMEOUT_SEC="${raw}": expected a non-negative integer (seconds)`);
114
+ return Number(raw) * 1e3;
115
+ }
116
+ /**
117
+ * A fee / gas env value (`CHAIN_GAS_PRICE`, `CREATE_*_TX_FEE`), parsed identically on leader and follower:
118
+ * unset or empty -> undefined (the caller's default / no overlay); otherwise a plain non-negative decimal
119
+ * (`integer`: digits only). Whitespace, NaN, negatives, exponents and hex fail startup instead of becoming `0`.
120
+ */
121
+ function parseNonNegativeNumberEnv(env, name, { integer = false } = {}) {
122
+ const raw = env[name];
123
+ if (raw === void 0 || raw === "") return void 0;
124
+ const re = integer ? /^(?:0|[1-9]\d*)$/ : /^(?:0|[1-9]\d*)(?:\.\d+)?$/;
125
+ const value = Number(raw);
126
+ if (!re.test(raw) || !Number.isFinite(value) || integer && !Number.isSafeInteger(value)) throw new Error(`Invalid ${name}="${raw}": expected a non-negative ${integer ? "integer" : "number"} (or leave it empty)`);
127
+ return value;
128
+ }
129
+ /** Default clock skew a replayed entry's timestamp may be ahead of the local clock (#1961; #1965 owns the value). */
130
+ const DEFAULT_FUTURE_TIMESTAMP_SKEW_SECONDS = 300;
131
+ /**
132
+ * `LEDGER_FUTURE_TIMESTAMP_FROM_SEQ` (positive integer; unset = guard disabled, today's behavior) and
133
+ * `LEDGER_FUTURE_TIMESTAMP_SKEW_SEC` (non-negative integer seconds, default 300; ignored while the guard is off).
134
+ */
135
+ function resolveFutureTimestampGuardFromEnv(env = process.env) {
136
+ const rawSeq = String(env.LEDGER_FUTURE_TIMESTAMP_FROM_SEQ ?? "").trim();
137
+ if (!rawSeq) return void 0;
138
+ if (!/^[1-9]\d*$/.test(rawSeq) || !Number.isSafeInteger(Number(rawSeq))) throw new Error(`Invalid LEDGER_FUTURE_TIMESTAMP_FROM_SEQ="${env.LEDGER_FUTURE_TIMESTAMP_FROM_SEQ}": expected a positive integer`);
139
+ const rawSkew = String(env.LEDGER_FUTURE_TIMESTAMP_SKEW_SEC ?? "").trim();
140
+ let skewSeconds = DEFAULT_FUTURE_TIMESTAMP_SKEW_SECONDS;
141
+ if (rawSkew) {
142
+ if (!/^(?:0|[1-9]\d*)$/.test(rawSkew) || !Number.isSafeInteger(Number(rawSkew) * 1e3)) throw new Error(`Invalid LEDGER_FUTURE_TIMESTAMP_SKEW_SEC="${env.LEDGER_FUTURE_TIMESTAMP_SKEW_SEC}": expected a non-negative integer`);
143
+ skewSeconds = Number(rawSkew);
144
+ }
145
+ return {
146
+ activationSequence: Number(rawSeq),
147
+ maxSkewMs: skewSeconds * 1e3
148
+ };
149
+ }
69
150
 
70
151
  //#endregion
71
- export { BLOCKLET_ENV_CHAIN_FALLBACKS, STANDALONE_ENV_MARKERS, findBlockletEnvLeftovers, formatBlockletEnvLeftoversWarning, resolveTrustedSubject };
152
+ export { BLOCKLET_ENV_CHAIN_FALLBACKS, DEFAULT_CONFIG_CHECK_TIMEOUT_SECONDS, DEFAULT_FUTURE_TIMESTAMP_SKEW_SECONDS, STANDALONE_ENV_MARKERS, TRANSACTION_SWITCH_ENV, findBlockletEnvLeftovers, formatBlockletEnvLeftoversWarning, parseNonNegativeNumberEnv, resolveConfigCheckModeFromEnv, resolveConfigCheckTimeoutMsFromEnv, resolveFutureTimestampGuardFromEnv, resolveTransactionSwitchesFromEnv, resolveTrustedSubject };
@@ -1,13 +1,14 @@
1
1
  import { createAccessLogMiddleware } from "./access-log.mjs";
2
+ import { fetchUpstreamChainConfig, verifyFollowerConfigAgainstUpstream } from "./config-consistency.mjs";
3
+ import { isCompleteChainConfig, orphanIndexFromSequence, rehydrateFollowerChainConfig } from "./follower-config.mjs";
2
4
  import { assertValidChainNodeTestHooks } from "./test-hooks-token.mjs";
5
+ import { CustomError } from "@ocap/util/lib/error";
3
6
  import { LeaderRouter, Ledger, bytesToHex, canonicalizeMultiCurvePublicKey, createCheckpointSigner, createEnvAnchorPublisher, createEnvColdArchiveReader, createEnvSegmentPublisher, createEnvWitnessRegistry, decodeMultiCurvePublicKey, normalizeDidForCompare, resolveConsensusProposerFromSigner, toHotStuffClusterConfig, verifyDidMatchesMultiCurvePublicKey } from "@arcblock/ledger-core";
4
7
  import { SqliteHotStuffStateStore, SqliteLedgerStorage, formatLocalProcessHolderId, hasExistingFollowerDatabases, persistFollowerHighWaterMark, prepareFollowerDataDirectory, readFollowerTrustedSecretKeyIfPresent, unlinkFollowerTrustedSecretKeyIfPresent } from "@arcblock/ledger-sqlite";
5
- import { CustomError } from "@ocap/util/lib/error";
6
8
  import crypto from "node:crypto";
7
9
  import fs from "node:fs";
8
10
  import path from "node:path";
9
11
  import { isValid } from "@arcblock/did";
10
- import * as Config from "@ocap/config";
11
12
  import { createHttpHandler, createSocketHandler } from "@ocap/gql";
12
13
  import SqliteIndexDB from "@ocap/indexdb-sqlite";
13
14
  import OCAPResolver, { FollowerSyncService, HotStuffNodeRuntime, NodePreferencesManager, applyBootRuntimePreferences, createAdminAuthGuard, createExplorerMiddleware, createFollowerPeerFetchGuard, createNodeDashboardRouter, createNodeMaintenanceController, createUnifiedConsoleMiddleware, isDashboardEnabled, isExplorerEnabled } from "@ocap/resolver";
@@ -59,6 +60,22 @@ function assertSafeNonSymlinkDirectory(rawDataDir) {
59
60
  if (fs.lstatSync(dataDir).isSymbolicLink()) throw new CustomError("SECURITY_VIOLATION", `Refusing symlinked chain node dataDir: ${dataDir}`);
60
61
  return dataDir;
61
62
  }
63
+ /** Write a small file and fsync it and its directory, so it survives a crash or power loss right after. */
64
+ function writeFileDurably(filePath, content) {
65
+ const fd = fs.openSync(filePath, "w", 384);
66
+ try {
67
+ fs.writeFileSync(fd, content);
68
+ fs.fsyncSync(fd);
69
+ } finally {
70
+ fs.closeSync(fd);
71
+ }
72
+ const dirFd = fs.openSync(path.dirname(filePath), "r");
73
+ try {
74
+ fs.fsyncSync(dirFd);
75
+ } finally {
76
+ fs.closeSync(dirFd);
77
+ }
78
+ }
62
79
  function loadOrCreateNodeId(dataDir, explicitNodeId) {
63
80
  const nodeIdPath = path.join(dataDir, NODE_ID_FILENAME);
64
81
  if (fs.existsSync(nodeIdPath) && fs.lstatSync(nodeIdPath).isSymbolicLink()) throw new CustomError("SECURITY_VIOLATION", `Refusing symlinked .node-id file: ${nodeIdPath}`);
@@ -148,9 +165,6 @@ function adaptColdReaderToArchiveStore(reader) {
148
165
  ...typeof reader.getLatestHead === "function" ? { getLatestHead: reader.getLatestHead.bind(reader) } : {}
149
166
  };
150
167
  }
151
- function isCompleteChainConfig(candidate) {
152
- return Boolean(candidate && typeof candidate.chainId === "string" && candidate.chainId.trim() && candidate.moderator?.address && candidate.token?.symbol && candidate.vaults?.slashedStake);
153
- }
154
168
  function formatHttpHostForUrl(bindHost) {
155
169
  const trimmed = bindHost.trim();
156
170
  if (!trimmed || trimmed === "0.0.0.0" || trimmed === "::" || trimmed === "[::]") return "127.0.0.1";
@@ -181,6 +195,7 @@ async function bootChainNodeOnce(params) {
181
195
  if ((role.kind === "validator" || role.kind === "hotstuff") && !isCompleteChainConfig(profile.chainConfig)) throw new CustomError("INVALID_CONFIG", `${role.kind} role requires a complete chainConfig`);
182
196
  if ((role.kind === "validator" || role.kind === "hotstuff") && !role.signer) throw new CustomError("INVALID_CONFIG", `${role.kind} role requires role.signer`);
183
197
  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");
198
+ if (role.kind === "follower" && role.orphanIndexFromSequence !== void 0 && (!Number.isSafeInteger(role.orphanIndexFromSequence) || role.orphanIndexFromSequence < 1)) throw new CustomError("INVALID_CONFIG", `role.orphanIndexFromSequence must be a positive integer, got ${String(role.orphanIndexFromSequence)}`);
184
199
  const logger = testHooks?.logger ?? profile.logger ?? createDefaultLogger("chain-node");
185
200
  const variadicLogger = toVariadicLogger(logger);
186
201
  const followerExpectedChainId = "expectedChainId" in profile ? profile.expectedChainId : void 0;
@@ -228,6 +243,7 @@ async function bootChainNodeOnce(params) {
228
243
  let ledgerCleanupIndex = -1;
229
244
  let followerPrep = null;
230
245
  const isKeylessFollower = role.kind === "follower" && !profile.storage?.trustedStorageSecretKey?.trim();
246
+ let followerFetchGuard;
231
247
  if (role.kind === "follower") {
232
248
  if (fs.existsSync(ledgerPath) && fs.statSync(ledgerPath).size > 0) {
233
249
  const precheckLedgerStorage = createLedgerStorage();
@@ -264,6 +280,7 @@ async function bootChainNodeOnce(params) {
264
280
  init
265
281
  }, guardedBootstrapFetch);
266
282
  }) : guardedBootstrapFetch;
283
+ followerFetchGuard = bootstrapFetchImpl;
267
284
  const explicitExpectedChainId = followerExpectedChainId?.trim() || "";
268
285
  const profileChainId = profile.chainConfig?.chainId?.trim() || "";
269
286
  if (explicitExpectedChainId && profileChainId && explicitExpectedChainId !== profileChainId) throw new CustomError("SNAPSHOT_CHAIN_ID_MISMATCH", `Follower expectedChainId (${explicitExpectedChainId}) !== profile.chainConfig.chainId (${profileChainId})`);
@@ -343,13 +360,7 @@ async function bootChainNodeOnce(params) {
343
360
  const storedChainId = typeof storedChainPartial.chainId === "string" ? storedChainPartial.chainId.trim() : "";
344
361
  const overrideChainId = typeof profile.chainConfig?.chainId === "string" ? profile.chainConfig.chainId.trim() : "";
345
362
  if (storedChainId && overrideChainId && overrideChainId !== storedChainId) throw new CustomError("SNAPSHOT_CHAIN_ID_MISMATCH", `Follower profile.chainConfig.chainId (${overrideChainId}) !== statedb chain.chainId (${storedChainId})`);
346
- const baseSymbol = storedChainPartial.token?.symbol || "TBA";
347
- const reservedSymbols = Array.from(new Set([baseSymbol, ...storedChainPartial.reservedSymbols ?? []].map((s) => String(s || "").trim().toUpperCase()).filter(Boolean)));
348
- chainConfig = Config.create({
349
- ...storedChain,
350
- ...storedChainId ? { chainId: storedChainId } : {},
351
- reservedSymbols
352
- });
363
+ chainConfig = rehydrateFollowerChainConfig(storedChain, profile.chainConfig, profile.reservedSymbols);
353
364
  } else {
354
365
  const baseConfig = profile.chainConfig;
355
366
  if (role.kind === "follower") {
@@ -360,6 +371,7 @@ async function bootChainNodeOnce(params) {
360
371
  chainConfig = baseConfig;
361
372
  }
362
373
  if (role.kind === "follower" && followerExpectedChainId && chainConfig.chainId !== followerExpectedChainId) throw new CustomError("SNAPSHOT_CHAIN_ID_MISMATCH", `Rehydrated Follower chainId (${chainConfig.chainId}) !== expectedChainId (${followerExpectedChainId})`);
374
+ const orphanIndexStart = role.kind === "follower" ? orphanIndexFromSequence(chainConfig.chainId, role.orphanIndexFromSequence) : 1;
363
375
  const hotstuffValidators = role.kind === "hotstuff" ? role.validators : role.kind === "follower" ? role.hotstuffValidators ?? [] : [];
364
376
  const hotstuffQuorumThreshold = role.kind === "hotstuff" ? role.quorumThreshold : role.kind === "follower" ? role.hotstuffQuorumThreshold : void 0;
365
377
  const hotstuffClusterConfig = role.kind === "hotstuff" || hotstuffValidators.length > 0 ? toHotStuffClusterConfig(chainConfig.chainId, hotstuffValidators, hotstuffQuorumThreshold) : void 0;
@@ -528,6 +540,9 @@ async function bootChainNodeOnce(params) {
528
540
  });
529
541
  }
530
542
  const indexDbExisted = fs.existsSync(indexdbPath);
543
+ const indexBuildMarkerPath = `${indexdbPath}.build-pending`;
544
+ let followerIndexBuildNeeded = role.kind === "follower" && (Boolean(followerPrep?.bootstrapped) || !indexDbExisted || fs.existsSync(indexBuildMarkerPath));
545
+ if (followerIndexBuildNeeded) writeFileDurably(indexBuildMarkerPath, `${(/* @__PURE__ */ new Date()).toISOString()}\n`);
531
546
  const indexdb = new SqliteIndexDB({
532
547
  filename: indexdbPath,
533
548
  ...profile.storage?.indexWalAutoCheckpoint !== void 0 ? { walAutoCheckpoint: profile.storage.indexWalAutoCheckpoint } : {}
@@ -537,8 +552,16 @@ async function bootChainNodeOnce(params) {
537
552
  });
538
553
  await indexdb.initialize();
539
554
  await waitEventEmitterReady(indexdb);
555
+ if (role.kind === "follower" && !followerIndexBuildNeeded) {
556
+ if (await indexdb.tx.count() === 0 && await ledger.getLatestSequence() > 0) {
557
+ logger.warn?.("follower IndexDB has no transactions while the ledger has entries; rebuilding it", { indexdbPath });
558
+ followerIndexBuildNeeded = true;
559
+ writeFileDurably(indexBuildMarkerPath, `${(/* @__PURE__ */ new Date()).toISOString()}\n`);
560
+ }
561
+ }
540
562
  let resolverRef = null;
541
- const adminEnv = profile.http.adminEnv ?? {};
563
+ const explicitAdminEnv = profile.http.adminEnv;
564
+ const adminEnv = explicitAdminEnv ?? {};
542
565
  const preferencesManager = new NodePreferencesManager({
543
566
  dataDir,
544
567
  env: adminEnv,
@@ -594,6 +617,15 @@ async function bootChainNodeOnce(params) {
594
617
  const initialPrefs = preferencesManager.getSnapshot();
595
618
  if (initialPrefs.runtime.txMaxRequest !== void 0) resolver.setMaxTxRequest(initialPrefs.runtime.txMaxRequest);
596
619
  await resolver.initialize();
620
+ if (role.kind === "follower") await verifyFollowerConfigAgainstUpstream({
621
+ mode: profile.configCheck?.mode ?? "off",
622
+ localConfig: resolver.config,
623
+ upstreamUrl: role.upstreamChainUrl ?? role.clusterPeerUrls?.[0] ?? null,
624
+ fetchUpstreamConfig: profile.configCheck?.fetchUpstreamConfig ?? ((u) => fetchUpstreamChainConfig(u, followerFetchGuard ? { fetchImpl: followerFetchGuard } : void 0)),
625
+ hasLocalState: !followerPrep?.bootstrapped && await ledger.getLatestSequence() > 0,
626
+ ...profile.configCheck?.retryDeadlineMs !== void 0 ? { retryDeadlineMs: profile.configCheck.retryDeadlineMs } : {},
627
+ logger
628
+ });
597
629
  let followerSync;
598
630
  let hotstuffRuntime;
599
631
  if (role.kind === "follower") {
@@ -635,6 +667,10 @@ async function bootChainNodeOnce(params) {
635
667
  startPaused: testHooks?.followerSync?.startPaused,
636
668
  artificialPollDelayMs: testHooks?.followerSync?.artificialPollDelayMs,
637
669
  interceptUpstreamFetch: testHooks?.followerSync?.interceptUpstreamFetch,
670
+ ...profile.replayGuards?.futureTimestamp ? { futureTimestampGuard: {
671
+ ...profile.replayGuards.futureTimestamp,
672
+ now: clockNow
673
+ } } : {},
638
674
  env: { ALLOW_PRIVATE_PEER_URLS: role.allowPrivatePeers ? "1" : "0" }
639
675
  });
640
676
  resolver.setNodeRuntime(followerSync);
@@ -647,9 +683,20 @@ async function bootChainNodeOnce(params) {
647
683
  triggerSyncOnce: () => syncRef.triggerSyncOnce()
648
684
  });
649
685
  }
650
- if (Boolean(followerPrep?.bootstrapped) || !indexDbExisted) {
651
- await resolver.rebuildIndex();
652
- await followerSync.replayer.indexExistingOrphanEntries();
686
+ if (followerIndexBuildNeeded) {
687
+ const buildStart = Date.now();
688
+ logger.info?.("follower initial index build started", {
689
+ indexdbPath,
690
+ resumed: indexDbExisted
691
+ });
692
+ const built = await resolver.rebuildIndex();
693
+ const orphans = await followerSync.replayer.indexExistingOrphanEntries(orphanIndexStart);
694
+ fs.rmSync(indexBuildMarkerPath, { force: true });
695
+ logger.info?.("follower initial index build finished", {
696
+ tables: built?.tables,
697
+ orphanEntries: orphans,
698
+ durationMs: Date.now() - buildStart
699
+ });
653
700
  }
654
701
  } else if (role.kind === "hotstuff") {
655
702
  const hotstuffStateStore = new SqliteHotStuffStateStore(ledgerStorage);
@@ -719,7 +766,7 @@ async function bootChainNodeOnce(params) {
719
766
  res.once("close", markDone);
720
767
  next();
721
768
  });
722
- if (profile.http.enableAccessLog) app.use(createAccessLogMiddleware(logger));
769
+ if (profile.http.enableAccessLog) app.use(createAccessLogMiddleware(logger, explicitAdminEnv ? { env: explicitAdminEnv } : void 0));
723
770
  app.head("/", (_req, res) => {
724
771
  res.status(200).send("OK");
725
772
  });
@@ -762,7 +809,10 @@ async function bootChainNodeOnce(params) {
762
809
  const server = createSocketHandler({
763
810
  indexdb,
764
811
  app,
765
- wsOptions: { broadcastEventName: `@arcblock/ws:broadcast:${nodeId}:${crypto.randomUUID()}` }
812
+ wsOptions: {
813
+ broadcastEventName: `@arcblock/ws:broadcast:${nodeId}:${crypto.randomUUID()}`,
814
+ ...explicitAdminEnv ? { env: explicitAdminEnv } : {}
815
+ }
766
816
  });
767
817
  pushCleanup(async () => {
768
818
  isShuttingDown = true;
@@ -797,6 +847,7 @@ async function bootChainNodeOnce(params) {
797
847
  });
798
848
  app.use("/", createHttpHandler({
799
849
  resolver,
850
+ ...explicitAdminEnv ? { env: explicitAdminEnv } : {},
800
851
  onError: profile.http.onGraphqlError ? (err) => {
801
852
  profile.http.onGraphqlError(err);
802
853
  } : () => {}
package/esm/types.d.mts CHANGED
@@ -1,3 +1,4 @@
1
+ import { FutureTimestampGuardConfig, TChainConfigCheckMode } from "./standalone-env.mjs";
1
2
  import { CHAIN_NODE_TEST_HOOKS_TOKEN } from "./test-hooks-token.mjs";
2
3
  import { AnchorPublisher, ICheckpointSignerWallet, IHotStuffRuntimeValidatorMember, ILedgerHealth, INodeRoleConfig, ISegmentArchiveStore, IWriterLeaseConfig, Ledger, LedgerConfig } from "@arcblock/ledger-core";
3
4
  import { SqliteLedgerStorage } from "@arcblock/ledger-sqlite";
@@ -6,8 +7,8 @@ import OCAPResolver, { FollowerSyncService, HotStuffNodeRuntime, HotStuffNodeRun
6
7
  import SqliteStateDB from "@ocap/statedb-sqlite";
7
8
  import { SqliteTrustedStorage } from "@ocap/trusted-storage";
8
9
  import express from "express";
9
- import http from "node:http";
10
10
  import { IChainConfig, IPipelineLogger, TFollowerSyncMode, TNodeWritePolicy } from "@ocap/types";
11
+ import http from "node:http";
11
12
 
12
13
  //#region src/types.d.ts
13
14
  type ILedgerLeaseOptions = IWriterLeaseConfig;
@@ -85,6 +86,11 @@ interface FollowerRoleConfig {
85
86
  signer?: ChainNodeSignerConfig;
86
87
  /** Optional explicit runtime role (`'follower'` default or `'standby'`) */
87
88
  runtimeRole?: 'follower' | 'standby';
89
+ /**
90
+ * First sequence whose orphan ledger entries the initial index build indexes (default: where the chain's leader
91
+ * began indexing them, see `orphanIndexFromSequence`; 1 for chains not listed there).
92
+ */
93
+ orphanIndexFromSequence?: number;
88
94
  }
89
95
  interface HotStuffValidatorRoleConfig {
90
96
  kind: 'hotstuff';
@@ -190,6 +196,22 @@ interface ChainProfileBase {
190
196
  env?: Record<string, string | undefined>;
191
197
  };
192
198
  validateTokenConfig?: boolean;
199
+ /**
200
+ * Follower only (#1961): before any replay, compare the consensus config this node replays with against the
201
+ * upstream leader's `getConfig`. Default `off` (no request). `enforce` refuses to start on a difference.
202
+ */
203
+ configCheck?: {
204
+ mode: TChainConfigCheckMode;
205
+ /** Stub upstream for tests; defaults to `getConfig` over `<upstreamChainUrl>/api/gql`. */
206
+ fetchUpstreamConfig?: (upstreamUrl: string) => Promise<unknown>;
207
+ /** `enforce`: how long an unavailable upstream is retried before deciding (default 60 s). */
208
+ retryDeadlineMs?: number;
209
+ };
210
+ /** Follower only (#1961): acceptance guards on replayed ledger entries. Default: none (today's behavior). */
211
+ replayGuards?: {
212
+ /** Refuse (retryably) entries at or after `activationSequence` whose timestamp is ahead of the local clock. */
213
+ futureTimestamp?: FutureTimestampGuardConfig;
214
+ };
193
215
  logger?: IPipelineLogger;
194
216
  configureApp?: (app: express.Express, ctx: ChainAppHookContext) => void | Promise<void>;
195
217
  }
@@ -37,7 +37,8 @@ const chunkBytes = (chunk, encoding) => {
37
37
  return 0;
38
38
  };
39
39
  /** Express middleware writing one `formatAccessLogLine` per finished response through `logger.info`. */
40
- function createAccessLogMiddleware(logger) {
40
+ function createAccessLogMiddleware(logger, options = {}) {
41
+ const getHeaders = () => options.env !== void 0 ? (0, _ocap_util_lib_client_ip.getTrustedClientIpHeaders)(options.env.CHAIN_CLIENT_IP_HEADERS) : void 0;
41
42
  return (req, res, next) => {
42
43
  const startedAt = Date.now();
43
44
  let bytes = 0;
@@ -52,13 +53,14 @@ function createAccessLogMiddleware(logger) {
52
53
  return origEnd.apply(this, args);
53
54
  };
54
55
  res.once("finish", () => {
56
+ const trustedHeaders = getHeaders();
55
57
  logger.info(formatAccessLogLine({
56
58
  method: req.method,
57
59
  path: req.originalUrl,
58
60
  status: res.statusCode,
59
61
  durationMs: Date.now() - startedAt,
60
62
  bytes,
61
- clientIp: (0, _ocap_util_lib_client_ip.resolveClientIp)(req),
63
+ clientIp: (0, _ocap_util_lib_client_ip.resolveClientIp)(req, trustedHeaders !== void 0 ? { headers: trustedHeaders } : void 0),
62
64
  host: headerString(req.headers.host),
63
65
  cfRay: headerString(req.headers["cf-ray"]),
64
66
  userAgent: headerString(req.headers["user-agent"])
@@ -26,9 +26,12 @@ interface AccessLogFields {
26
26
  userAgent?: string;
27
27
  }
28
28
  declare function formatAccessLogLine(f: AccessLogFields): string;
29
+ interface AccessLogMiddlewareOptions {
30
+ env?: Record<string, string | undefined>;
31
+ }
29
32
  /** Express middleware writing one `formatAccessLogLine` per finished response through `logger.info`. */
30
33
  declare function createAccessLogMiddleware(logger: {
31
34
  info: (msg: string) => void;
32
- }): (req: Request, res: Response, next: NextFunction) => void;
35
+ }, options?: AccessLogMiddlewareOptions): (req: Request, res: Response, next: NextFunction) => void;
33
36
  //#endregion
34
- export { AccessLogFields, createAccessLogMiddleware, formatAccessLogLine };
37
+ export { AccessLogFields, AccessLogMiddlewareOptions, createAccessLogMiddleware, formatAccessLogLine };
@@ -0,0 +1,263 @@
1
+ const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
2
+ let _ocap_config = require("@ocap/config");
3
+ let _ocap_config_lib_default = require("@ocap/config/lib/default");
4
+ _ocap_config_lib_default = require_rolldown_runtime.__toESM(_ocap_config_lib_default);
5
+ let _ocap_util_lib_error = require("@ocap/util/lib/error");
6
+
7
+ //#region src/config-consistency.ts
8
+ /**
9
+ * Follower startup consistency check (#1961): before a follower replays anything it asks the upstream leader for
10
+ * its in-memory chain config (`getConfig`, core/resolver `getConfig()` returns `JSON.stringify(this.config)`) and
11
+ * compares every consensus-relevant key, both sides normalized with the same defaults. A follower that replays with
12
+ * a different config computes different state commits (e.g. `transaction.bridge.enabled` off rejects the first
13
+ * bridge reserve entry in `bridge-reserve-v2-gate.ts`) and halts; this check turns that into a clear startup error.
14
+ *
15
+ * Consensus-relevant keys (`CONSENSUS_CONFIG_KEYS`) are what the tx pipeline / replayer reads from `context.config`:
16
+ * - `chainId` every protocol (`tx.chainId` checks), replayer entry chain id
17
+ * - `mode` `Config.create` defaults (`ledger` zeroes fees and gas)
18
+ * - `moderator.address` moderator-only protocols (token / factory / rollup governance)
19
+ * - `token.address/symbol/decimal` official token, fee and stake units, reserved base symbol
20
+ * - `vaults` where fees, gas and slashed stake go (`txFee`, `txFees`, `txGas`, `slashedStake`)
21
+ * - `reservedSymbols` `create_token_factory` verification (compared as a case-insensitive set)
22
+ * - `transaction` the whole section: `txFee`, `txGas` (+ free-gas / burst knobs), `txStake`,
23
+ * `maxTxSize`, `maxAssetSize`, `maxListSize`, `maxMultisig`, `delegate`, `supportedTxs`,
24
+ * `multiSignV2Txs`, `maxWriteSetSize`, `security`, `bridge`, `rollupV1`, `exchangeV2`
25
+ * Not compared: `version` (software), `accounts` and token metadata/supply (genesis only: a follower never re-runs
26
+ * genesis, it starts from a verified snapshot), `moderator.pk` (protocols compare the address), `genesisTime`.
27
+ */
28
+ const CONSENSUS_CONFIG_KEYS = [
29
+ "chainId",
30
+ "mode",
31
+ "moderator.address",
32
+ "token.address",
33
+ "token.symbol",
34
+ "token.decimal",
35
+ "vaults",
36
+ "reservedSymbols",
37
+ "transaction"
38
+ ];
39
+ /** Protocol fallback of `transaction.exchangeV2.defaultTtlSeconds` (core/tx-protocols exchange-v2.ts). */
40
+ const DEFAULT_EXCHANGE_V2_TTL_SECONDS = 720 * 60 * 60;
41
+ const isPlainObject = (v) => Boolean(v) && typeof v === "object" && !Array.isArray(v);
42
+ /** JSON round trip: drops `undefined`, functions and frozen-ness, so both sides compare as the wire would. */
43
+ function toJsonValue(value) {
44
+ if (value === void 0) return void 0;
45
+ return JSON.parse(JSON.stringify(value));
46
+ }
47
+ function getPath(obj, dotted) {
48
+ let cur = obj;
49
+ for (const seg of dotted.split(".")) {
50
+ if (!isPlainObject(cur)) return void 0;
51
+ cur = cur[seg];
52
+ }
53
+ return cur;
54
+ }
55
+ function setPath(obj, dotted, value) {
56
+ const segs = dotted.split(".");
57
+ let cur = obj;
58
+ for (const seg of segs.slice(0, -1)) {
59
+ if (!isPlainObject(cur[seg])) cur[seg] = {};
60
+ cur = cur[seg];
61
+ }
62
+ cur[segs[segs.length - 1]] = value;
63
+ }
64
+ /** Fill only keys that are absent (`undefined`); present values, records and arrays are kept as they are. */
65
+ function fillAbsent(target, defaults) {
66
+ const out = { ...target };
67
+ for (const [k, v] of Object.entries(defaults)) if (out[k] === void 0) out[k] = toJsonValue(v);
68
+ return out;
69
+ }
70
+ function normalizeTransaction(raw) {
71
+ const tx = fillAbsent(isPlainObject(raw) ? toJsonValue(raw) : {}, _ocap_config_lib_default.default.transaction);
72
+ tx.txGas = fillAbsent(isPlainObject(tx.txGas) ? tx.txGas : {}, _ocap_config.defaultGasSecurityKnobs.txGas);
73
+ tx.security = fillAbsent(isPlainObject(tx.security) ? tx.security : {}, _ocap_config.defaultGasSecurityKnobs.security);
74
+ tx.bridge = { enabled: isPlainObject(tx.bridge) && tx.bridge.enabled === true };
75
+ tx.rollupV1 = { enabled: !(isPlainObject(tx.rollupV1) && tx.rollupV1.enabled === false) };
76
+ const exchangeV2 = isPlainObject(tx.exchangeV2) ? tx.exchangeV2 : {};
77
+ tx.exchangeV2 = {
78
+ ...exchangeV2,
79
+ defaultTtlSeconds: typeof exchangeV2.defaultTtlSeconds === "number" ? exchangeV2.defaultTtlSeconds : DEFAULT_EXCHANGE_V2_TTL_SECONDS
80
+ };
81
+ return tx;
82
+ }
83
+ /** The consensus-relevant projection of a chain config, with defaults applied identically on both sides. */
84
+ function normalizeConsensusConfig(config) {
85
+ const out = {};
86
+ for (const key of CONSENSUS_CONFIG_KEYS) {
87
+ const value = toJsonValue(getPath(config, key));
88
+ switch (key) {
89
+ case "mode":
90
+ setPath(out, key, value === "ledger" ? "ledger" : "chain");
91
+ break;
92
+ case "token.address":
93
+ setPath(out, key, typeof value === "string" ? value : "");
94
+ break;
95
+ case "vaults":
96
+ setPath(out, key, isPlainObject(value) ? value : {});
97
+ break;
98
+ case "reservedSymbols":
99
+ setPath(out, key, Array.from(new Set((Array.isArray(value) ? value : []).map((s) => String(s ?? "").trim().toUpperCase()).filter(Boolean))).sort());
100
+ break;
101
+ case "transaction":
102
+ setPath(out, key, normalizeTransaction(value));
103
+ break;
104
+ default: setPath(out, key, value === void 0 ? null : value);
105
+ }
106
+ }
107
+ return out;
108
+ }
109
+ function collectDiff(local, upstream, prefix, out) {
110
+ if (isPlainObject(local) && isPlainObject(upstream)) {
111
+ const keys = Array.from(new Set([...Object.keys(local), ...Object.keys(upstream)])).sort();
112
+ for (const k of keys) collectDiff(local[k], upstream[k], prefix ? `${prefix}.${k}` : k, out);
113
+ return;
114
+ }
115
+ if (JSON.stringify(local) !== JSON.stringify(upstream)) out.push({
116
+ path: prefix,
117
+ local: local === void 0 ? null : local,
118
+ upstream: upstream === void 0 ? null : upstream
119
+ });
120
+ }
121
+ /** Differences between two configs' consensus projections, by dotted path (arrays compare as a whole). */
122
+ function diffConsensusConfig(local, upstream) {
123
+ const out = [];
124
+ collectDiff(normalizeConsensusConfig(local), normalizeConsensusConfig(upstream), "", out);
125
+ return out;
126
+ }
127
+ const MAX_CONFIG_RESPONSE_BYTES = 8 * 1024 * 1024;
128
+ const GET_CONFIG_QUERY = "{ getConfig { code config } }";
129
+ async function readBoundedResponseText(res, url, maxBytes) {
130
+ const contentLength = res.headers?.get?.("content-length");
131
+ if (contentLength !== null && contentLength !== void 0 && contentLength.trim() !== "") {
132
+ const parsedLen = Number(contentLength);
133
+ if (Number.isFinite(parsedLen) && parsedLen > maxBytes) {
134
+ try {
135
+ await res.body?.cancel();
136
+ } catch {}
137
+ throw new Error(`getConfig from ${url} failed: response larger than ${maxBytes} bytes`);
138
+ }
139
+ }
140
+ if (!res.body || typeof res.body.getReader !== "function") {
141
+ const text$1 = await res.text();
142
+ if (Buffer.byteLength(text$1, "utf8") > maxBytes) throw new Error(`getConfig from ${url} failed: response larger than ${maxBytes} bytes`);
143
+ return text$1;
144
+ }
145
+ const reader = res.body.getReader();
146
+ const decoder = new TextDecoder();
147
+ let totalBytes = 0;
148
+ let text = "";
149
+ for (;;) {
150
+ const { done, value } = await reader.read();
151
+ if (done) break;
152
+ if (value) {
153
+ totalBytes += value.byteLength;
154
+ if (totalBytes > maxBytes) {
155
+ try {
156
+ await reader.cancel();
157
+ } catch {}
158
+ throw new Error(`getConfig from ${url} failed: response larger than ${maxBytes} bytes`);
159
+ }
160
+ text += decoder.decode(value, { stream: true });
161
+ }
162
+ }
163
+ text += decoder.decode();
164
+ return text;
165
+ }
166
+ /** POST `{ getConfig }` to `<upstreamUrl>/api/gql` and return the parsed in-memory config of the upstream. */
167
+ async function fetchUpstreamChainConfig(upstreamUrl, { fetchImpl = fetch, timeoutMs = 1e4 } = {}) {
168
+ const url = `${String(upstreamUrl).trim().replace(/\/+$/, "")}/api/gql`;
169
+ const res = await fetchImpl(url, {
170
+ method: "POST",
171
+ headers: {
172
+ "content-type": "application/json",
173
+ accept: "application/json"
174
+ },
175
+ body: JSON.stringify({ query: GET_CONFIG_QUERY }),
176
+ redirect: "error",
177
+ signal: AbortSignal.timeout(timeoutMs)
178
+ });
179
+ const text = await readBoundedResponseText(res, url, MAX_CONFIG_RESPONSE_BYTES);
180
+ if (!res.ok) throw new Error(`getConfig from ${url} failed: HTTP ${res.status}`);
181
+ const body = JSON.parse(text);
182
+ if (body.errors?.length) throw new Error(`getConfig from ${url} failed: ${body.errors.map((e) => e.message).join("; ")}`);
183
+ const raw = body.data?.getConfig?.config;
184
+ if (typeof raw !== "string" || !raw) throw new Error(`getConfig from ${url} failed: no config in the response (code=${body.data?.getConfig?.code})`);
185
+ return assertUpstreamConfigShape(JSON.parse(raw), url);
186
+ }
187
+ /** A response that is not a chain config is a bad body ("unavailable"), never a definite mismatch. */
188
+ function assertUpstreamConfigShape(parsed, source) {
189
+ if (!isPlainObject(parsed)) throw new Error(`getConfig from ${source} failed: config is not an object`);
190
+ if (typeof parsed.chainId !== "string" || !parsed.chainId.trim() || !isPlainObject(parsed.transaction)) throw new Error(`getConfig from ${source} failed: config has no chainId / transaction section`);
191
+ return parsed;
192
+ }
193
+ const formatValue = (v) => {
194
+ const s = JSON.stringify(v);
195
+ return s.length > 160 ? `${s.slice(0, 157)}...` : s;
196
+ };
197
+ function formatConfigDifferences(diff) {
198
+ return diff.map((d) => `${d.path} (local=${formatValue(d.local)}, upstream=${formatValue(d.upstream)})`).join("; ");
199
+ }
200
+ /**
201
+ * Compare the follower's replay config with the upstream leader's. `off`: no request. `warn`: one attempt, log
202
+ * any difference or failure and continue. `enforce`: a definite difference throws `CHAIN_CONFIG_MISMATCH` (lists
203
+ * every differing key). An unavailable upstream (down, HTTP error such as 429, bad body) is retried with backoff
204
+ * until `retryDeadlineMs`; then a node with existing local state starts with a warning, and only a fresh bootstrap
205
+ * throws `CHAIN_CONFIG_CHECK_UNAVAILABLE`.
206
+ */
207
+ async function verifyFollowerConfigAgainstUpstream(opts) {
208
+ if (opts.mode === "off") return {
209
+ status: "skipped",
210
+ diff: []
211
+ };
212
+ const enforce = opts.mode === "enforce";
213
+ const now = opts.now ?? (() => Date.now());
214
+ const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
215
+ const unavailable = (reason) => {
216
+ const message$1 = `Follower config check (CHAIN_CONFIG_CHECK=${opts.mode}) could not read the upstream config: ${reason}`;
217
+ if (enforce && !opts.hasLocalState) throw new _ocap_util_lib_error.CustomError("CHAIN_CONFIG_CHECK_UNAVAILABLE", `${message$1}; refusing to start a fresh bootstrap before replay`);
218
+ opts.logger.warn(`[chain-node] ${message$1}; starting without the check${enforce ? " (existing local state)" : ""}`);
219
+ return {
220
+ status: "unavailable",
221
+ diff: []
222
+ };
223
+ };
224
+ const upstreamUrl = String(opts.upstreamUrl ?? "").trim();
225
+ if (!upstreamUrl) return unavailable("no upstream URL (UPSTREAM_CHAIN_URL) is configured");
226
+ const fetchConfig = opts.fetchUpstreamConfig ?? ((u) => fetchUpstreamChainConfig(u));
227
+ const deadline = now() + Math.max(0, opts.retryDeadlineMs ?? 6e4);
228
+ const maxDelay = Math.max(0, opts.retryMaxDelayMs ?? 1e4);
229
+ let delay = Math.max(0, opts.retryDelayMs ?? 1e3);
230
+ let upstreamConfig = null;
231
+ while (upstreamConfig === null) try {
232
+ upstreamConfig = assertUpstreamConfigShape(await fetchConfig(upstreamUrl), upstreamUrl);
233
+ } catch (err) {
234
+ const reason = err instanceof Error ? err.message : String(err);
235
+ if (!enforce || now() + delay > deadline) return unavailable(reason);
236
+ opts.logger.warn(`[chain-node] follower config check: upstream unavailable (${reason}); retrying in ${delay} ms`);
237
+ await sleep(delay);
238
+ delay = Math.min(maxDelay, delay * 2);
239
+ }
240
+ const diff = diffConsensusConfig(opts.localConfig, upstreamConfig);
241
+ if (diff.length === 0) {
242
+ opts.logger.info(`[chain-node] follower consensus config matches upstream ${upstreamUrl}`);
243
+ return {
244
+ status: "match",
245
+ diff
246
+ };
247
+ }
248
+ const message = `Follower consensus config differs from upstream ${upstreamUrl} in ${diff.length} key(s): ${formatConfigDifferences(diff)}`;
249
+ if (enforce) throw new _ocap_util_lib_error.CustomError("CHAIN_CONFIG_MISMATCH", `${message}; refusing to start before replay (#1961)`);
250
+ opts.logger.warn(`[chain-node] ${message}`);
251
+ return {
252
+ status: "mismatch",
253
+ diff
254
+ };
255
+ }
256
+
257
+ //#endregion
258
+ exports.CONSENSUS_CONFIG_KEYS = CONSENSUS_CONFIG_KEYS;
259
+ exports.diffConsensusConfig = diffConsensusConfig;
260
+ exports.fetchUpstreamChainConfig = fetchUpstreamChainConfig;
261
+ exports.formatConfigDifferences = formatConfigDifferences;
262
+ exports.normalizeConsensusConfig = normalizeConsensusConfig;
263
+ exports.verifyFollowerConfigAgainstUpstream = verifyFollowerConfigAgainstUpstream;