@ocap/resolver 1.31.9 → 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 (42) hide show
  1. package/esm/_virtual/rolldown_runtime.mjs +7 -0
  2. package/esm/api.d.mts +33 -5
  3. package/esm/api.mjs +939 -53
  4. package/esm/dashboard.d.mts +199 -0
  5. package/esm/dashboard.mjs +2481 -0
  6. package/esm/explorer.d.mts +29 -0
  7. package/esm/explorer.mjs +227 -0
  8. package/esm/follower.d.mts +294 -0
  9. package/esm/follower.mjs +2452 -0
  10. package/esm/hooks.mjs +1 -1
  11. package/esm/hotstuff-runtime.d.mts +271 -0
  12. package/esm/hotstuff-runtime.mjs +2668 -0
  13. package/esm/index.d.mts +79 -4
  14. package/esm/index.mjs +911 -174
  15. package/esm/node-preferences.d.mts +203 -0
  16. package/esm/node-preferences.mjs +1021 -0
  17. package/esm/replayer.d.mts +114 -0
  18. package/esm/replayer.mjs +430 -0
  19. package/esm/token-distribution.mjs +2 -2
  20. package/esm/token-flow.mjs +1 -1
  21. package/esm/types.d.mts +25 -2
  22. package/lib/api.cjs +941 -52
  23. package/lib/api.d.cts +33 -5
  24. package/lib/dashboard.cjs +2491 -0
  25. package/lib/dashboard.d.cts +199 -0
  26. package/lib/explorer.cjs +227 -0
  27. package/lib/explorer.d.cts +29 -0
  28. package/lib/follower.cjs +2458 -0
  29. package/lib/follower.d.cts +294 -0
  30. package/lib/hooks.cjs +1 -1
  31. package/lib/hotstuff-runtime.cjs +2671 -0
  32. package/lib/hotstuff-runtime.d.cts +271 -0
  33. package/lib/index.cjs +946 -174
  34. package/lib/index.d.cts +79 -4
  35. package/lib/node-preferences.cjs +1043 -0
  36. package/lib/node-preferences.d.cts +203 -0
  37. package/lib/replayer.cjs +432 -0
  38. package/lib/replayer.d.cts +114 -0
  39. package/lib/token-distribution.cjs +2 -2
  40. package/lib/token-flow.cjs +1 -1
  41. package/lib/types.d.cts +25 -2
  42. package/package.json +20 -14
@@ -0,0 +1,2452 @@
1
+ import { createFollowerPeerFetchGuard } from "./node-preferences.mjs";
2
+ import { FUTURE_LEDGER_ENTRY_TIMESTAMP, LedgerEntryReplayer } from "./replayer.mjs";
3
+ import { ArchivePayloadDecodeError, EntryHashRunVerifier, HotWindowPruneController, IncrementalMerkleTree, assertValidSegment, computeCheckpointHash, computeEntryHash, computeHotTailEntryCommitment, computeSegmentContentHash, createHotStuffTrustAnchor, createWitnessAttestation, deriveSegmentStateRoot, normalizeHttpBaseUrl, resolveTrustAnchor, verifyCheckpointQuorumCertificate, verifyCheckpointSignature, verifyDidMatchesMultiCurvePublicKey, verifyHotTailBatchSignature, verifyHotTailStatusSignature, verifySegmentCommitmentSignature } from "@arcblock/ledger-core";
4
+ import { toBuffer } from "@ocap/util";
5
+ import { CustomError } from "@ocap/util/lib/error";
6
+
7
+ //#region src/follower.ts
8
+ /**
9
+ * Two-Stage Turnkey `FollowerSyncService` (#1710)
10
+ *
11
+ * Stage 1B (Cold Segment Catchup): Streams and verifies immutable `.zst` checkpoint segments via
12
+ * an injected `coldArchiveStore`, replaying entries through `LedgerEntryReplayer` before calling
13
+ * `ledger.importSegment()`.
14
+ *
15
+ * Stage 2 (`< 1s` Hot-Tail Polling): Polls `GET /api/ledger/status` and `GET /api/ledger/entries`
16
+ * from the allowlisted upstream leader (`redirect: 'error'`, strict byte caps), replays entries
17
+ * sequentially (`concurrency = 1`) with pre-commit `expectedCommitHash` verification, falls back
18
+ * seamlessly to Stage 1B on `HTTP 410 PRUNED_SEQUENCE`, and seals verified checkpoints via
19
+ * `ledger.sealVerifiedCheckpoint()`.
20
+ *
21
+ * Halts fail-closed (`halted = true`, `synced = false`) on any `STATE_COMMIT_MISMATCH`,
22
+ * `LEDGER_DIVERGENCE`, `TX_HASH_MISMATCH`, or checkpoint cryptographic verification failure.
23
+ */
24
+ const MAX_HOT_TAIL_LIMIT = 100;
25
+ const MAX_HOT_TAIL_RESPONSE_BYTES = 2 * 1024 * 1024;
26
+ const DEFAULT_FOLLOWER_POLL_INTERVAL_MS = 500;
27
+ const DEFAULT_FOLLOWER_MAX_SYNC_LAG = 20;
28
+ const DEFAULT_FOLLOWER_MAX_UPSTREAM_STALE_MS = 15e3;
29
+ const DEFAULT_FOLLOWER_HTTP_TIMEOUT_MS = 1e4;
30
+ const STATUS_MAX_RESPONSE_BYTES = 64 * 1024;
31
+ const ENTRIES_MAX_RESPONSE_BYTES = MAX_HOT_TAIL_RESPONSE_BYTES + 64 * 1024;
32
+ const MAX_PAGES_PER_SYNC_CYCLE = 20;
33
+ const WITNESS_POST_TIMEOUT_MS = 5e3;
34
+ const WITNESS_POST_MAX_RESPONSE_BYTES = 16 * 1024;
35
+ const MAX_ATTESTED_HEIGHT_CACHE = 1024;
36
+ function classifyUpstreamFetchKind(rawUrl) {
37
+ try {
38
+ const pathname = new URL(rawUrl).pathname.toLowerCase();
39
+ if (pathname.endsWith("/api/ledger/entries") || pathname.includes("/ledger/entries")) return "entries";
40
+ if (pathname.endsWith("/api/ledger/checkpoint") || pathname.includes("/ledger/checkpoint")) return "checkpoints";
41
+ if (pathname.endsWith(".zst")) return "snapshot-archive";
42
+ if (pathname.endsWith("manifest.json") || pathname.endsWith("latest-snapshot.json")) return "snapshot-manifest";
43
+ return "status";
44
+ } catch {
45
+ return "status";
46
+ }
47
+ }
48
+ function adaptColdReaderToArchiveStore(reader) {
49
+ const maybeFull = reader;
50
+ if (typeof maybeFull.putSegment === "function" && typeof maybeFull.hasSegment === "function") return reader;
51
+ return {
52
+ name: maybeFull.name || "follower-cold-reader",
53
+ async putSegment() {
54
+ throw new Error("Follower coldArchiveStore is read-only");
55
+ },
56
+ async getSegment(chainId, height, options) {
57
+ const seg = await reader.getSegment(chainId, height, options);
58
+ if (!seg) return null;
59
+ return seg;
60
+ },
61
+ async hasSegment(chainId, height) {
62
+ const seg = await reader.getSegment(chainId, height);
63
+ return Boolean(seg);
64
+ },
65
+ ...typeof reader.getLatestHead === "function" ? { getLatestHead: reader.getLatestHead.bind(reader) } : {}
66
+ };
67
+ }
68
+ function normalizeDidCompare(did) {
69
+ return String(did ?? "").trim().replace(/^did:abt:/i, "");
70
+ }
71
+ async function readBoundedText(response, maxBytes) {
72
+ const contentLength = response.headers?.get?.("content-length");
73
+ if (contentLength) {
74
+ const declared = Number(contentLength);
75
+ if (Number.isFinite(declared) && declared > maxBytes) {
76
+ try {
77
+ await response.body?.cancel();
78
+ } catch {}
79
+ throw new CustomError("RESPONSE_TOO_LARGE", `Response Content-Length (${declared}) exceeds ${maxBytes} bytes`);
80
+ }
81
+ }
82
+ if (!response.body || typeof response.body.getReader !== "function") {
83
+ const buf = new Uint8Array(await response.arrayBuffer());
84
+ if (buf.byteLength > maxBytes) throw new CustomError("RESPONSE_TOO_LARGE", `Response body (${buf.byteLength}) exceeds ${maxBytes} bytes`);
85
+ return new TextDecoder().decode(buf);
86
+ }
87
+ const reader = response.body.getReader();
88
+ const chunks = [];
89
+ let total = 0;
90
+ try {
91
+ while (true) {
92
+ const { done, value } = await reader.read();
93
+ if (done) break;
94
+ if (!value || value.byteLength === 0) continue;
95
+ total += value.byteLength;
96
+ if (total > maxBytes) {
97
+ try {
98
+ await reader.cancel();
99
+ } catch {}
100
+ throw new CustomError("RESPONSE_TOO_LARGE", `Streaming response exceeded ${maxBytes}-byte ceiling`);
101
+ }
102
+ chunks.push(value);
103
+ }
104
+ } finally {
105
+ try {
106
+ reader.releaseLock();
107
+ } catch {}
108
+ }
109
+ if (chunks.length === 0) return "";
110
+ const merged = new Uint8Array(total);
111
+ let offset = 0;
112
+ for (const chunk of chunks) {
113
+ merged.set(chunk, offset);
114
+ offset += chunk.byteLength;
115
+ }
116
+ return new TextDecoder().decode(merged);
117
+ }
118
+ const MAX_SAFE_EPOCH_MS = 864e13;
119
+ const MAX_STATUS_CHECKPOINT_CHAIN_WALK = 64;
120
+ const LOCAL_EXECUTION_DIVERGENCE_CODES = new Set([
121
+ "STATE_COMMIT_MISMATCH",
122
+ "LEDGER_DIVERGENCE",
123
+ "TX_HASH_MISMATCH"
124
+ ]);
125
+ const UPSTREAM_OR_TRANSPORT_ERROR_CODES = new Set([
126
+ "FORBIDDEN",
127
+ "UPSTREAM_UNAVAILABLE",
128
+ "UPSTREAM_BAD_RESPONSE",
129
+ "RESPONSE_TOO_LARGE",
130
+ "CHAIN_ID_MISMATCH",
131
+ "PROPOSER_MISMATCH",
132
+ "HOT_TAIL_SIGNATURE_MISSING",
133
+ "HOT_TAIL_SIGNATURE_INVALID",
134
+ "UNAUTHENTICATED_STATUS_CHAIN_BINDING",
135
+ "INVALID_CHECKPOINT_HASH",
136
+ "INVALID_CHECKPOINT_SIGNATURE",
137
+ "INVALID_CHECKPOINT_CHAIN",
138
+ "INVALID_CHECKPOINT_QC",
139
+ "PRUNED_SEQUENCE_UNAVAILABLE",
140
+ "COLD_SEGMENT_HEIGHT_MISMATCH",
141
+ "COLD_BUNDLE_WRAPPER_MISMATCH",
142
+ "COLD_SEGMENT_CONTENT_MISMATCH",
143
+ "COLD_SEGMENT_SIGNATURE_INVALID",
144
+ "COLD_SEGMENT_CHAIN_MISMATCH",
145
+ "INVALID_LEDGER_ENTRY",
146
+ "UNFINALIZED_LEDGER_ENTRY",
147
+ "HTTP_ARCHIVE_ERROR",
148
+ FUTURE_LEDGER_ENTRY_TIMESTAMP
149
+ ]);
150
+ function sanitizeUntrustedWireToken(value, maxLen = 128) {
151
+ return String(value ?? "").replace(/[\r\n\t\x00-\x1f\x7f]+/g, " ").trim().slice(0, maxLen);
152
+ }
153
+ function isLocalExecutionDivergenceCode(code) {
154
+ return typeof code === "string" && LOCAL_EXECUTION_DIVERGENCE_CODES.has(code);
155
+ }
156
+ function normalizeHexDigest(raw) {
157
+ return String(raw ?? "").trim().replace(/^0x/i, "").toLowerCase();
158
+ }
159
+ const LOCAL_CHECKPOINT_SEAL_DIVERGENCE_RE = /^Checkpoint (?:stateRoot|txRoot|prevCheckpoint|prevSequence) mismatch|^Checkpoint height conflict|^Local entry |^Cannot seal checkpoint height \d+: expected \d+ local entries, found \d+/;
160
+ const LOCAL_LEDGER_STORAGE_CORRUPTION_RE = /^Local entry |^Cannot seal checkpoint height \d+: expected \d+ local entries, found \d+/;
161
+ function isLocalCheckpointSealDivergenceError(err) {
162
+ return err instanceof Error && LOCAL_CHECKPOINT_SEAL_DIVERGENCE_RE.test(err.message);
163
+ }
164
+ function isTransientSqliteLockError(err) {
165
+ if (!err || typeof err !== "object") return false;
166
+ if (err.upstreamTransportFailure === true) return false;
167
+ const rawCode = err.code;
168
+ const rawErrcode = err.errcode;
169
+ if (rawCode === 5 || rawCode === 6 || rawErrcode === 5 || rawErrcode === 6) return true;
170
+ if (typeof rawErrcode === "number" && Number.isFinite(rawErrcode)) {
171
+ const primaryErr = rawErrcode & 255;
172
+ if (primaryErr === 5 || primaryErr === 6) return true;
173
+ }
174
+ const code = String(rawCode ?? "");
175
+ if (code && UPSTREAM_OR_TRANSPORT_ERROR_CODES.has(code)) return false;
176
+ if (/^SQLITE_(?:BUSY|LOCKED)(?:_|$)/i.test(code)) return true;
177
+ const message = err instanceof Error ? err.message : String(err.message ?? "");
178
+ return /\bSQLITE_(?:BUSY|LOCKED)(?:_[A-Z0-9]+)?\b|database is locked|database table is locked/i.test(message);
179
+ }
180
+ function isLocalLedgerStorageCorruptionError(err) {
181
+ if (isTransientSqliteLockError(err)) return false;
182
+ if (err?.upstreamTransportFailure === true) return false;
183
+ return err instanceof Error && LOCAL_LEDGER_STORAGE_CORRUPTION_RE.test(err.message);
184
+ }
185
+ function isLocalTrustedStorageHashError(err, depth = 0) {
186
+ if (!err || typeof err !== "object" || depth > 3) return false;
187
+ if (isTransientSqliteLockError(err)) return false;
188
+ if (err.localStorageFailure === true) return true;
189
+ if (err.upstreamTransportFailure === true) return false;
190
+ const code = String(err.code ?? "");
191
+ if (code && UPSTREAM_OR_TRANSPORT_ERROR_CODES.has(code)) return false;
192
+ const rawErrcode = err.errcode;
193
+ if (typeof rawErrcode === "number" && Number.isFinite(rawErrcode)) {
194
+ const primaryErr = rawErrcode & 255;
195
+ if (primaryErr === 8 || primaryErr === 10 || primaryErr === 11 || primaryErr === 13 || primaryErr === 14 || primaryErr === 26) return true;
196
+ }
197
+ const name = String(err.name ?? "");
198
+ const message = err instanceof Error ? err.message : String(err.message ?? "");
199
+ if (code === "INVALID_HASH" && /^Trusted hash verification failed\b/i.test(message) || code === "STATE_COMMIT_MISMATCH" && /^(?:Dry-run|Replay) of seq=\d+ \([0-9a-fA-F]{1,128}\) did not commit state \([^)]*; error=INVALID_HASH\)$/i.test(message) || /^SQLITE_/i.test(code) || code === "ERR_SQLITE_ERROR" || name === "SqliteError" || name === "SQLiteError" || !code && /^(?:Failed to verify signature of hash:|Failed to update hash, hash mismatch)/i.test(message) || /^LEDGER_/i.test(code) && /(?:\bSQLITE_(?:CORRUPT|FULL|IOERR|READONLY|CANTOPEN|NOTADB)\b|database disk image is malformed|file is not a database)/i.test(message)) return true;
200
+ const cause = err.cause;
201
+ return cause !== void 0 && cause !== err ? isLocalTrustedStorageHashError(cause, depth + 1) : false;
202
+ }
203
+ /**
204
+ * Halt fail-closed (`NODE_HALTED`) when:
205
+ * (a) local StateDB / Ledger execution or crash-window replay diverges (`localDivergenceFailure === true`)
206
+ * in ANY mode, including `allowUnauthenticated: true` (#1818), OR
207
+ * (b) checkpoint sealing / equivocation check diverges *after* cryptographic proposer
208
+ * authentication (`authenticatedLocalFailure === true`, #1710 / #1711), OR
209
+ * (c) `TRUST_ANCHOR_REQUIRED` node misconfiguration.
210
+ *
211
+ * Unauthenticated upstream HTTP or cold-mirror transport errors (`HOT_TAIL_SIGNATURE_INVALID`,
212
+ * `HOT_TAIL_SIGNATURE_MISSING`, `UPSTREAM_UNAVAILABLE`, forged segment signatures, wrong `chainId`/`proposer`, etc.)
213
+ * disqualify the offending peer and trigger failover/retry without bricking local reads (#1710, #1818).
214
+ */
215
+ function isFatalVerificationFailure(err) {
216
+ if (err instanceof ArchivePayloadDecodeError || err?.name === "ArchivePayloadDecodeError") return false;
217
+ if (isTransientSqliteLockError(err)) return false;
218
+ if (err?.authenticatedLocalFailure === true || err?.localDivergenceFailure === true) return true;
219
+ const code = err?.code;
220
+ if (isLocalTrustedStorageHashError(err)) return true;
221
+ return code === "TRUST_ANCHOR_REQUIRED";
222
+ }
223
+ function canonicalizePeerBaseUrl(rawUrl) {
224
+ const trimmed = rawUrl.trim();
225
+ if (!trimmed) return "";
226
+ try {
227
+ return normalizeHttpBaseUrl(trimmed, "peerUrl");
228
+ } catch {
229
+ return trimmed.replace(/\/+$/g, "");
230
+ }
231
+ }
232
+ var FollowerSyncService = class {
233
+ constructor(options) {
234
+ this.attestedHeights = /* @__PURE__ */ new Set();
235
+ this.pendingWitnessTasks = /* @__PURE__ */ new Set();
236
+ this.timer = null;
237
+ this.syncInFlight = null;
238
+ this.stopped = false;
239
+ this.halted = false;
240
+ this.haltReason = null;
241
+ this.futureTimestampRejections = 0;
242
+ this.lastFutureTimestampRejection = null;
243
+ this.pendingCrashWindowReconcile = false;
244
+ this.initialCrashReconcileCompleted = false;
245
+ this.upstreamSequence = null;
246
+ this.upstreamNodeId = null;
247
+ this.upstreamNodeRole = null;
248
+ this.lastUpstreamSuccessAtMs = 0;
249
+ this.stagnantSyncCycles = 0;
250
+ this.lastPeerProbeAtMs = 0;
251
+ this.seenSignedUpstream = false;
252
+ this.seenSignedStatus = false;
253
+ this.stagedTofuAnchor = null;
254
+ this.resolver = options.resolver;
255
+ this.role = options.role;
256
+ this.writePolicy = options.writePolicy;
257
+ this.syncMode = options.syncMode;
258
+ this.chainId = options.resolver.config.chainId || options.resolver.ledger.chainId;
259
+ this.replayer = new LedgerEntryReplayer(options.resolver, options.futureTimestampGuard ? { futureTimestampGuard: {
260
+ ...options.futureTimestampGuard,
261
+ onReject: (info) => this.recordFutureTimestampRejection(info)
262
+ } } : {});
263
+ const retentionMode = options.retentionMode ?? "archive";
264
+ if (retentionMode !== "archive" && retentionMode !== "tiered") throw new CustomError("INVALID_CONFIG", `Invalid retentionMode "${String(retentionMode)}": expected "archive" or "tiered"`);
265
+ if (retentionMode === "tiered" && !options.coldArchiveStore) throw new CustomError("INVALID_CONFIG", "FollowerSyncService with retentionMode=\"tiered\" requires coldArchiveStore");
266
+ this.retentionMode = retentionMode;
267
+ this.upstreamUrl = options.upstreamUrl ? canonicalizePeerBaseUrl(options.upstreamUrl) || null : null;
268
+ this.allowedBaseUrls = /* @__PURE__ */ new Set();
269
+ if (this.upstreamUrl) this.allowedBaseUrls.add(this.upstreamUrl);
270
+ for (const peer of options.peerUrls ?? []) {
271
+ const normalized = peer ? canonicalizePeerBaseUrl(peer) : "";
272
+ if (normalized) this.allowedBaseUrls.add(normalized);
273
+ }
274
+ for (const candidate of options.leaderRouter?.getCandidateUrls?.() ?? []) {
275
+ const normalized = candidate ? canonicalizePeerBaseUrl(candidate) : "";
276
+ if (normalized) this.allowedBaseUrls.add(normalized);
277
+ }
278
+ this.coldArchiveStore = options.coldArchiveStore;
279
+ if (options.coldArchiveStore) {
280
+ const archiveStore = adaptColdReaderToArchiveStore(options.coldArchiveStore);
281
+ const ledgerWithCold = this.resolver.ledger;
282
+ if (typeof ledgerWithCold.setColdSegmentStore === "function" && !ledgerWithCold.getColdSegmentStore?.()) ledgerWithCold.setColdSegmentStore(archiveStore);
283
+ this.pruneController = retentionMode === "tiered" ? new HotWindowPruneController({
284
+ archiveStore,
285
+ retentionMode: "tiered",
286
+ hotWindowEntries: options.hotWindowEntries,
287
+ hotWindowCheckpoints: options.hotWindowCheckpoints,
288
+ logger: this.resolver.logger
289
+ }) : null;
290
+ } else this.pruneController = null;
291
+ this.leaderRouter = options.leaderRouter;
292
+ this.hotstuffClusterConfig = options.hotstuffClusterConfig;
293
+ this.hotstuffValidatorDids = new Set((options.hotstuffClusterConfig?.validators ?? []).map((v) => normalizeDidCompare(v.did)).filter(Boolean));
294
+ this.trustedProposer = options.hotstuffClusterConfig ? null : options.trustedProposer?.trim() || null;
295
+ this.trustedProposerPublicKey = options.hotstuffClusterConfig ? null : options.trustedProposerPublicKey?.trim() || null;
296
+ this.verifier = options.verifier ?? (options.hotstuffClusterConfig ? createHotStuffTrustAnchor(options.hotstuffClusterConfig).verifier : void 0);
297
+ this.allowUnauthenticated = options.allowUnauthenticated === true;
298
+ this.disallowKeylessCascadedUpstream = options.disallowKeylessCascadedUpstream === true;
299
+ this.paused = options.startPaused === true;
300
+ this.artificialPollDelayMs = typeof options.artificialPollDelayMs === "number" && Number.isFinite(options.artificialPollDelayMs) && options.artificialPollDelayMs > 0 ? Math.trunc(options.artificialPollDelayMs) : 0;
301
+ this.pollIntervalMs = typeof options.pollIntervalMs === "number" && options.pollIntervalMs >= 50 ? options.pollIntervalMs : DEFAULT_FOLLOWER_POLL_INTERVAL_MS;
302
+ this.maxSyncLag = typeof options.maxSyncLag === "number" && options.maxSyncLag >= 0 ? options.maxSyncLag : DEFAULT_FOLLOWER_MAX_SYNC_LAG;
303
+ this.maxUpstreamStaleMs = typeof options.maxUpstreamStaleMs === "number" && options.maxUpstreamStaleMs >= 500 ? options.maxUpstreamStaleMs : DEFAULT_FOLLOWER_MAX_UPSTREAM_STALE_MS;
304
+ this.httpTimeoutMs = typeof options.httpTimeoutMs === "number" && options.httpTimeoutMs >= 500 ? options.httpTimeoutMs : DEFAULT_FOLLOWER_HTTP_TIMEOUT_MS;
305
+ this.witnessWallet = options.witnessWallet;
306
+ this.witnessAddress = (options.witnessAddress || options.witnessWallet?.address || "").trim() || null;
307
+ if (this.witnessWallet && (typeof this.resolver.statedb?.runAsLambda !== "function" || typeof this.resolver.statedb?.getCurrentCommitHash !== "function")) throw new CustomError("WITNESS_STATEDB_UNSUPPORTED", "Witness attestation signing requires a StateDB supporting deterministic runAsLambda and getCurrentCommitHash");
308
+ if (options.witnessSubmitUrls && options.witnessSubmitUrls.length > 0) {
309
+ const normalizedUrls = /* @__PURE__ */ new Set();
310
+ for (const rawUrl of options.witnessSubmitUrls) if (rawUrl?.trim()) normalizedUrls.add(normalizeHttpBaseUrl(rawUrl, "witnessSubmitUrls"));
311
+ this.witnessSubmitUrls = Array.from(normalizedUrls);
312
+ } else if (this.witnessWallet) this.witnessSubmitUrls = Array.from(this.allowedBaseUrls);
313
+ else this.witnessSubmitUrls = [];
314
+ const baseFetchImpl = options.fetchImpl ? options.fetchImpl : createFollowerPeerFetchGuard({
315
+ env: options.env ?? process.env,
316
+ dnsLookup: options.dnsLookup,
317
+ trustedStaticUrls: [...this.allowedBaseUrls, ...this.witnessSubmitUrls],
318
+ baseFetch: globalThis.fetch
319
+ });
320
+ const interceptor = options.interceptUpstreamFetch;
321
+ this.fetchImpl = interceptor ? (async (input, init) => {
322
+ const urlStr = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
323
+ return interceptor({
324
+ kind: classifyUpstreamFetchKind(urlStr),
325
+ url: urlStr,
326
+ init
327
+ }, baseFetchImpl);
328
+ }) : baseFetchImpl;
329
+ this.leaderRouter?.setFetchImplIfDefault?.(this.fetchImpl);
330
+ }
331
+ isHalted() {
332
+ return this.halted;
333
+ }
334
+ isReconciling() {
335
+ return this.pendingCrashWindowReconcile;
336
+ }
337
+ getHaltReason() {
338
+ return this.haltReason;
339
+ }
340
+ getConsensusMode() {
341
+ return this.hotstuffClusterConfig ? "hotstuff" : "single";
342
+ }
343
+ getUpstreamNodeId() {
344
+ return this.upstreamNodeId;
345
+ }
346
+ getUpstreamNodeRole() {
347
+ return this.upstreamNodeRole;
348
+ }
349
+ pause() {
350
+ this.paused = true;
351
+ }
352
+ resume() {
353
+ this.paused = false;
354
+ }
355
+ isPaused() {
356
+ return this.paused;
357
+ }
358
+ updateRuntimeConfig(patch) {
359
+ if (patch.writePolicy !== void 0) {
360
+ if (patch.writePolicy !== "reject" && patch.writePolicy !== "forward") throw new CustomError("INVALID_CONFIG", `Invalid writePolicy "${String(patch.writePolicy)}"`);
361
+ if (patch.writePolicy === "forward" && !this.leaderRouter) throw new CustomError("INVALID_CONFIG", "Cannot enable writePolicy=\"forward\" on a follower without a configured LeaderRouter");
362
+ this.writePolicy = patch.writePolicy;
363
+ }
364
+ if (patch.maxSyncLag !== void 0) {
365
+ if (!Number.isSafeInteger(patch.maxSyncLag) || patch.maxSyncLag < 0 || patch.maxSyncLag > 1e6) throw new CustomError("INVALID_CONFIG", "maxSyncLag must be an integer between 0 and 1000000");
366
+ this.maxSyncLag = patch.maxSyncLag;
367
+ }
368
+ if (patch.peerUrls !== void 0) {
369
+ const normalizedPeers = [];
370
+ for (const raw of patch.peerUrls) {
371
+ if (!raw || !String(raw).trim()) continue;
372
+ normalizedPeers.push(normalizeHttpBaseUrl(raw, "peerUrl"));
373
+ }
374
+ this.leaderRouter?.updateCandidatePeerUrls?.(normalizedPeers);
375
+ this.allowedBaseUrls.clear();
376
+ if (this.upstreamUrl) this.allowedBaseUrls.add(this.upstreamUrl);
377
+ for (const p of normalizedPeers) this.allowedBaseUrls.add(p);
378
+ for (const candidate of this.leaderRouter?.getCandidateUrls?.() ?? []) {
379
+ const normalized = candidate ? canonicalizePeerBaseUrl(candidate) : "";
380
+ if (normalized) this.allowedBaseUrls.add(normalized);
381
+ }
382
+ }
383
+ if (patch.pollIntervalMs !== void 0) {
384
+ if (!Number.isSafeInteger(patch.pollIntervalMs) || patch.pollIntervalMs < 50 || patch.pollIntervalMs > 3e5) throw new CustomError("INVALID_CONFIG", "pollIntervalMs must be an integer between 50 and 300000");
385
+ const changed = this.pollIntervalMs !== patch.pollIntervalMs;
386
+ this.pollIntervalMs = patch.pollIntervalMs;
387
+ if (changed && this.timer && !this.stopped && !this.halted && this.syncMode === "active-follower") {
388
+ clearInterval(this.timer);
389
+ this.timer = setInterval(() => {
390
+ this.syncOnce().catch(() => {});
391
+ }, this.pollIntervalMs);
392
+ if (typeof this.timer.unref === "function") this.timer.unref();
393
+ }
394
+ }
395
+ }
396
+ getRuntimeDiagnostics(options) {
397
+ const includePrivate = options?.includePrivateTopology === true;
398
+ const routerSnap = this.leaderRouter?.getDiagnosticsSnapshot?.();
399
+ const activeLeaderUrl = this.resolveActiveUpstreamUrl();
400
+ const hasHealthyActiveSync = !this.halted && this.lastUpstreamSuccessAtMs > 0;
401
+ const candidates = (routerSnap?.candidates ?? []).map((c, idx) => {
402
+ const isActiveLeader = Boolean(routerSnap?.activeLeaderUrl && c.url === routerSnap.activeLeaderUrl || activeLeaderUrl && c.url === activeLeaderUrl);
403
+ return {
404
+ id: `peer-${idx + 1}`,
405
+ ...includePrivate ? { url: c.url } : {},
406
+ isActiveLeader,
407
+ reachable: Boolean(c.reachable || isActiveLeader && hasHealthyActiveSync),
408
+ writable: c.writable,
409
+ checkpointHeight: c.checkpointHeight,
410
+ latestSequence: c.latestSequence > 0 ? c.latestSequence : isActiveLeader ? this.upstreamSequence : 0,
411
+ qcView: c.qcView,
412
+ rttMs: c.rttMs,
413
+ lastProbedAt: c.lastProbedAtMs > 0 ? new Date(c.lastProbedAtMs).toISOString() : isActiveLeader && this.lastUpstreamSuccessAtMs > 0 ? new Date(this.lastUpstreamSuccessAtMs).toISOString() : null
414
+ };
415
+ });
416
+ return {
417
+ mode: "follower",
418
+ consensusMode: this.getConsensusMode(),
419
+ syncMode: this.syncMode,
420
+ retentionMode: this.retentionMode,
421
+ writePolicy: this.writePolicy,
422
+ pollIntervalMs: this.pollIntervalMs,
423
+ maxSyncLag: this.maxSyncLag,
424
+ maxUpstreamStaleMs: this.maxUpstreamStaleMs,
425
+ upstreamSequence: this.upstreamSequence,
426
+ lastUpstreamSuccessAt: this.lastUpstreamSuccessAtMs > 0 ? new Date(this.lastUpstreamSuccessAtMs).toISOString() : null,
427
+ stagnantSyncCycles: this.stagnantSyncCycles,
428
+ witnessEnabled: Boolean(this.witnessWallet),
429
+ witnessAddress: this.witnessAddress,
430
+ coldArchiveConfigured: Boolean(this.coldArchiveStore),
431
+ peerCount: this.allowedBaseUrls.size,
432
+ ...includePrivate ? {
433
+ upstreamUrl: this.upstreamUrl,
434
+ activeLeaderUrl: this.resolveActiveUpstreamUrl(),
435
+ allowedPeerUrls: Array.from(this.allowedBaseUrls)
436
+ } : { hasActiveLeader: Boolean(this.resolveActiveUpstreamUrl()) },
437
+ leaderRouter: routerSnap ? {
438
+ candidateCount: routerSnap.candidateCount,
439
+ minVerifiedCheckpointHeight: routerSnap.minVerifiedCheckpointHeight,
440
+ inFlightForwards: routerSnap.inFlightForwards,
441
+ maxConcurrentForwards: routerSnap.maxConcurrentForwards,
442
+ requireSignedForwardReceipt: routerSnap.requireSignedForwardReceipt,
443
+ ...includePrivate ? { activeLeaderUrl: routerSnap.activeLeaderUrl } : {},
444
+ candidates
445
+ } : null
446
+ };
447
+ }
448
+ async triggerSyncOrProbe() {
449
+ if (this.halted) throw new CustomError("NODE_HALTED", `Follower node is halted: ${this.haltReason || "verification error"}`);
450
+ const promoted = this.leaderRouter?.probeAndPromoteLeader ? await this.leaderRouter.probeAndPromoteLeader() : null;
451
+ if (this.syncMode === "active-follower") await this.syncOnce();
452
+ const localSequence = await this.resolver.ledger.getLatestSequence();
453
+ return {
454
+ mode: "follower",
455
+ synced: await this.isSynced(),
456
+ localSequence,
457
+ upstreamSequence: this.upstreamSequence,
458
+ hasPromotedLeader: Boolean(promoted || this.resolveActiveUpstreamUrl())
459
+ };
460
+ }
461
+ haltFailClosed(reason, errorCode) {
462
+ this.halted = true;
463
+ this.haltReason = reason;
464
+ if (this.timer) {
465
+ clearInterval(this.timer);
466
+ this.timer = null;
467
+ }
468
+ this.resolver.logger.error(`CRITICAL [NODE_HALTED]: FollowerSyncService halted fail-closed (${reason})`, {
469
+ code: "NODE_HALTED",
470
+ ...errorCode ? { errorCode } : {},
471
+ chainId: this.chainId,
472
+ allowUnauthenticated: this.allowUnauthenticated,
473
+ haltReason: reason
474
+ });
475
+ }
476
+ resolveActiveUpstreamUrl() {
477
+ const rawRouted = this.leaderRouter?.getActiveLeaderUrl();
478
+ const target = (rawRouted ? canonicalizePeerBaseUrl(rawRouted) || null : null) || this.upstreamUrl;
479
+ if (!target) return null;
480
+ if (!this.allowedBaseUrls.has(target)) throw new CustomError("FORBIDDEN", `Upstream URL ${target} is not in FollowerSyncService allowlist`);
481
+ return target;
482
+ }
483
+ isFollowerAuthenticated() {
484
+ return !this.allowUnauthenticated && Boolean(this.trustedProposerPublicKey || this.verifier || this.hotstuffClusterConfig);
485
+ }
486
+ getTrustedProposer() {
487
+ return this.trustedProposer;
488
+ }
489
+ getTrustedProposerPublicKey() {
490
+ return this.trustedProposerPublicKey;
491
+ }
492
+ async isSynced() {
493
+ if (this.halted || this.pendingCrashWindowReconcile) return false;
494
+ if (this.syncMode === "primary" || this.syncMode === "offline-readonly") return true;
495
+ if (this.lastUpstreamSuccessAtMs <= 0) return false;
496
+ const staleCeiling = this.resolveActiveUpstreamUrl() ? this.maxUpstreamStaleMs : this.maxUpstreamStaleMs * 4;
497
+ if (Date.now() - this.lastUpstreamSuccessAtMs > staleCeiling) return false;
498
+ if (this.upstreamSequence === null) return false;
499
+ const localSeq = await this.resolver.ledger.getLatestSequence();
500
+ return Math.max(0, this.upstreamSequence - localSeq) <= this.maxSyncLag;
501
+ }
502
+ async forwardSendTx(args, ctx) {
503
+ if (this.halted) throw new CustomError("NODE_HALTED", `Follower node is halted fail-closed: ${this.haltReason || "verification error"}`);
504
+ if (!this.leaderRouter) throw new CustomError("FORBIDDEN", "This chain node is running in readonly mode (FOLLOWER_READ_ONLY)");
505
+ return this.leaderRouter.forwardSendTx(args, ctx);
506
+ }
507
+ async readLocalStateCommitHash() {
508
+ if (typeof this.resolver.statedb.getCurrentCommitHash === "function") return this.resolver.statedb.getCurrentCommitHash();
509
+ return "UNKNOWN";
510
+ }
511
+ /**
512
+ * Resolve the locally verified `stateRoot` (`string` or `null` when zero state-committing entries
513
+ * have ever run up to this checkpoint) AFTER `LedgerEntryReplayer.replayEntry` has verified every
514
+ * non-orphan entry via `statedb.runAsLambda` (#1711).
515
+ */
516
+ async resolveVerifiedWitnessStateRoot(segmentEntries, localCp, isAtHead) {
517
+ if (!segmentEntries.some((e) => typeof e.stateCommitHash === "string" && e.stateCommitHash.length > 0)) return localCp?.stateRoot ?? null;
518
+ if (isAtHead) {
519
+ const liveCommit = await this.readLocalStateCommitHash().catch((err) => {
520
+ this.rethrowIfLocalStorageOrLockError(err);
521
+ return "UNKNOWN";
522
+ });
523
+ if (liveCommit && liveCommit !== "UNKNOWN" && liveCommit !== "GENESIS") return liveCommit;
524
+ }
525
+ return deriveSegmentStateRoot(segmentEntries, localCp?.stateRoot) ?? null;
526
+ }
527
+ /**
528
+ * Resolve the local StateDB commit hash to report in an `ok: false` fraud alert without ever
529
+ * reading untrusted upstream `segmentEntries` (#1711).
530
+ */
531
+ async resolveLocalFraudAlertStateRoot(localCp) {
532
+ const liveCommit = await this.readLocalStateCommitHash().catch((err) => {
533
+ this.rethrowIfLocalStorageOrLockError(err);
534
+ return "UNKNOWN";
535
+ });
536
+ if (liveCommit && liveCommit !== "UNKNOWN" && liveCommit !== "GENESIS") return liveCommit;
537
+ return localCp?.stateRoot ?? null;
538
+ }
539
+ recordFutureTimestampRejection(info) {
540
+ this.futureTimestampRejections++;
541
+ this.lastFutureTimestampRejection = { ...info };
542
+ }
543
+ /** #1961: how many peer entries were refused for a future timestamp, and the last one (for alerting/tests). */
544
+ getFutureTimestampRejections() {
545
+ return {
546
+ count: this.futureTimestampRejections,
547
+ last: this.lastFutureTimestampRejection ? { ...this.lastFutureTimestampRejection } : null
548
+ };
549
+ }
550
+ async getFollowerStatus() {
551
+ const [localSequence, latestCp, localStateCommitHash, synced] = await Promise.all([
552
+ this.resolver.ledger.getLatestSequence(),
553
+ this.resolver.ledger.getCheckpoint(),
554
+ this.readLocalStateCommitHash(),
555
+ this.isSynced()
556
+ ]);
557
+ const syncLagEntries = this.upstreamSequence !== null ? Math.max(0, this.upstreamSequence - localSequence) : null;
558
+ return {
559
+ chainId: this.chainId,
560
+ nodeRole: this.role,
561
+ writePolicy: this.writePolicy,
562
+ syncMode: this.syncMode,
563
+ synced,
564
+ halted: this.halted,
565
+ haltReason: this.haltReason,
566
+ localSequence,
567
+ upstreamSequence: this.upstreamSequence,
568
+ syncLagEntries,
569
+ verifiedCheckpointHeight: latestCp?.height ?? 0,
570
+ verifiedCheckpointHash: latestCp?.hash ?? null,
571
+ localStateCommitHash,
572
+ activeLeaderUrl: this.resolveActiveUpstreamUrl(),
573
+ lastUpstreamSuccessAt: this.lastUpstreamSuccessAtMs > 0 ? new Date(this.lastUpstreamSuccessAtMs).toISOString() : null,
574
+ retentionMode: this.retentionMode,
575
+ witnessEnabled: Boolean(this.witnessWallet),
576
+ witnessAddress: this.witnessAddress
577
+ };
578
+ }
579
+ isAllowedHotStuffValidator(did) {
580
+ if (!this.hotstuffClusterConfig) return true;
581
+ const norm = normalizeDidCompare(did);
582
+ return Boolean(norm && this.hotstuffValidatorDids.has(norm));
583
+ }
584
+ hasCommittedTrustAnchor() {
585
+ return Boolean(this.hotstuffClusterConfig || this.trustedProposerPublicKey || this.verifier);
586
+ }
587
+ getEffectiveTrustedProposer() {
588
+ return this.trustedProposer || this.stagedTofuAnchor?.proposer || null;
589
+ }
590
+ getEffectiveTrustedProposerPublicKey() {
591
+ return this.trustedProposerPublicKey || this.stagedTofuAnchor?.proposerPublicKey || null;
592
+ }
593
+ getEffectiveSeenSignedUpstream() {
594
+ return this.seenSignedUpstream || Boolean(this.stagedTofuAnchor?.seenSignedUpstream);
595
+ }
596
+ getEffectiveSeenSignedStatus() {
597
+ return this.seenSignedStatus || Boolean(this.stagedTofuAnchor?.seenSignedStatus);
598
+ }
599
+ markSeenSignedUpstream() {
600
+ if (this.stagedTofuAnchor) this.stagedTofuAnchor.seenSignedUpstream = true;
601
+ else this.seenSignedUpstream = true;
602
+ }
603
+ markSeenSignedStatus() {
604
+ if (this.stagedTofuAnchor) this.stagedTofuAnchor.seenSignedStatus = true;
605
+ else this.seenSignedStatus = true;
606
+ }
607
+ async commitStagedTofuAnchor() {
608
+ const staged = this.stagedTofuAnchor;
609
+ if (!staged) return;
610
+ this.stagedTofuAnchor = null;
611
+ if (!this.trustedProposer) this.trustedProposer = staged.proposer;
612
+ this.trustedProposerPublicKey = staged.proposerPublicKey;
613
+ if (staged.seenSignedUpstream) this.seenSignedUpstream = true;
614
+ if (staged.seenSignedStatus) this.seenSignedStatus = true;
615
+ this.leaderRouter?.updateTrustAnchor?.({
616
+ proposer: this.trustedProposer,
617
+ proposerPublicKey: this.trustedProposerPublicKey
618
+ });
619
+ await this.persistTrustAnchorSafe({
620
+ proposer: this.trustedProposer ?? staged.proposer,
621
+ proposerPublicKey: this.trustedProposerPublicKey,
622
+ ...staged.seenSignedUpstream || staged.seenSignedStatus ? { signatureRatchetLocked: true } : {}
623
+ });
624
+ }
625
+ rethrowIfLocalStorageOrLockError(err) {
626
+ if (isTransientSqliteLockError(err)) throw err;
627
+ if (isLocalTrustedStorageHashError(err) || isLocalLedgerStorageCorruptionError(err)) {
628
+ err.localDivergenceFailure = true;
629
+ throw err;
630
+ }
631
+ }
632
+ async persistTrustAnchorSafe(anchor) {
633
+ try {
634
+ await this.resolver.ledger.persistTrustAnchor?.(anchor);
635
+ } catch (err) {
636
+ this.rethrowIfLocalStorageOrLockError(err);
637
+ }
638
+ }
639
+ async isCheckpointAuthenticatedByProposer(checkpoint) {
640
+ if (!checkpoint || typeof checkpoint !== "object") return false;
641
+ if (!this.hasCommittedTrustAnchor()) return false;
642
+ if (typeof checkpoint.height !== "number" || !Number.isSafeInteger(checkpoint.height) || checkpoint.height < 1 || typeof checkpoint.hash !== "string") return false;
643
+ if (computeCheckpointHash(checkpoint).replace(/^0x/i, "").toLowerCase() !== checkpoint.hash.replace(/^0x/i, "").toLowerCase()) return false;
644
+ if (!this.isAllowedHotStuffValidator(checkpoint.proposer)) return false;
645
+ if (!this.hotstuffClusterConfig && this.trustedProposer && normalizeDidCompare(checkpoint.proposer) !== normalizeDidCompare(this.trustedProposer)) return false;
646
+ const importOpts = this.buildSegmentImportOptions();
647
+ const trustAnchor = resolveTrustAnchor({
648
+ proposerPublicKey: importOpts.proposerPublicKey,
649
+ verifier: importOpts.verifier,
650
+ hotstuffClusterConfig: importOpts.hotstuffClusterConfig
651
+ });
652
+ if (!trustAnchor) return false;
653
+ if (!checkpoint.signature || checkpoint.signature === "unsigned") return false;
654
+ if (!await verifyCheckpointSignature(checkpoint, trustAnchor, this.hotstuffClusterConfig ? checkpoint.proposer : this.trustedProposer || checkpoint.proposer)) return false;
655
+ if (this.hotstuffClusterConfig) return verifyCheckpointQuorumCertificate(checkpoint, this.hotstuffClusterConfig).ok;
656
+ return true;
657
+ }
658
+ /**
659
+ * Verify that BOTH `segment.checkpoint.signature` AND `segment.checkpoint.segmentCommitmentSignature`
660
+ * (covering `{ chainId: this.chainId, checkpoint, entries }`) were cryptographically signed by the
661
+ * trusted proposer (#1711). Prevents a corrupt/MITM cold mirror or cross-chain replay from tricking
662
+ * an honest Witness Follower into emitting a false-positive `ok: false` fraud alert.
663
+ */
664
+ async isColdSegmentAuthenticatedByProposer(segment) {
665
+ if (!segment || segment.chainId !== this.chainId || !Array.isArray(segment.entries)) return false;
666
+ if (!await this.isCheckpointAuthenticatedByProposer(segment.checkpoint)) return false;
667
+ const importOpts = this.buildSegmentImportOptions();
668
+ const trustAnchor = resolveTrustAnchor({
669
+ proposerPublicKey: importOpts.proposerPublicKey,
670
+ verifier: importOpts.verifier,
671
+ hotstuffClusterConfig: importOpts.hotstuffClusterConfig
672
+ });
673
+ if (!trustAnchor) return false;
674
+ const actualSegContentHash = computeSegmentContentHash({
675
+ chainId: this.chainId,
676
+ checkpoint: segment.checkpoint,
677
+ entries: segment.entries
678
+ });
679
+ if (segment.checkpoint.segmentContentHash !== void 0 && (typeof segment.checkpoint.segmentContentHash !== "string" || segment.checkpoint.segmentContentHash.replace(/^0x/i, "").toLowerCase() !== actualSegContentHash.replace(/^0x/i, "").toLowerCase())) return false;
680
+ if (!await verifySegmentCommitmentSignature(segment.checkpoint, actualSegContentHash, trustAnchor, this.hotstuffClusterConfig ? segment.checkpoint.proposer : this.trustedProposer || segment.checkpoint.proposer)) return false;
681
+ if (this.hotstuffClusterConfig) {
682
+ if (segment.entries.length !== segment.checkpoint.txCount || segment.entries.length !== segment.checkpoint.sequence - segment.checkpoint.prevSequence) return false;
683
+ const tree = new IncrementalMerkleTree();
684
+ const hashVerifier = new EntryHashRunVerifier();
685
+ for (let i = 0; i < segment.entries.length; i++) {
686
+ const item = segment.entries[i];
687
+ if (!item || item.sequence !== segment.checkpoint.prevSequence + 1 + i || typeof item.entryHash !== "string") return false;
688
+ if (!hashVerifier.matches({
689
+ sequence: item.sequence,
690
+ txRaw: item.txRaw,
691
+ stateCommitHash: item.stateCommitHash ?? "",
692
+ entryHash: item.entryHash
693
+ })) return false;
694
+ tree.append(item.entryHash);
695
+ }
696
+ if (tree.getHexRoot().replace(/^0x/i, "").toLowerCase() !== String(segment.checkpoint.txRoot || "").replace(/^0x/i, "").toLowerCase()) return false;
697
+ }
698
+ return true;
699
+ }
700
+ async dispatchWitnessAttestation(checkpoint, entries, extra) {
701
+ if (!this.witnessWallet || !this.witnessAddress) return null;
702
+ if (!await this.isCheckpointAuthenticatedByProposer(checkpoint)) return null;
703
+ this.seenSignedUpstream = true;
704
+ if (!extra?.allowDuplicateHeight && this.attestedHeights.has(checkpoint.height)) return null;
705
+ if (this.attestedHeights.size >= MAX_ATTESTED_HEIGHT_CACHE && !this.attestedHeights.has(checkpoint.height)) {
706
+ const oldest = this.attestedHeights.values().next().value;
707
+ if (oldest !== void 0) this.attestedHeights.delete(oldest);
708
+ }
709
+ this.attestedHeights.add(checkpoint.height);
710
+ const hotstuffValidatorPk = this.hotstuffClusterConfig ? this.hotstuffClusterConfig.validators.find((v) => normalizeDidCompare(v.did) === normalizeDidCompare(checkpoint.proposer))?.publicKey : void 0;
711
+ const normalizedVerifiedLocalStateRoot = !extra?.forcedFailureReason && extra?.verifiedLocalStateRoot && checkpoint.stateRoot && normalizeHexDigest(extra.verifiedLocalStateRoot) === normalizeHexDigest(checkpoint.stateRoot) ? checkpoint.stateRoot : extra?.verifiedLocalStateRoot;
712
+ const attestation = await createWitnessAttestation({
713
+ chainId: this.chainId,
714
+ checkpoint,
715
+ entries,
716
+ witnessWallet: this.witnessWallet,
717
+ witnessAddress: this.witnessAddress,
718
+ expectedProposer: this.hotstuffClusterConfig ? checkpoint.proposer : this.trustedProposer || void 0,
719
+ proposerPublicKey: this.hotstuffClusterConfig ? hotstuffValidatorPk : this.trustedProposerPublicKey || void 0,
720
+ ...this.hotstuffClusterConfig ? { hotstuffClusterConfig: this.hotstuffClusterConfig } : {},
721
+ ...extra?.expectedPrevCheckpoint !== void 0 ? { expectedPrevCheckpoint: extra.expectedPrevCheckpoint } : {},
722
+ ...extra?.prevStateRoot !== void 0 ? { prevStateRoot: extra.prevStateRoot } : {},
723
+ ...normalizedVerifiedLocalStateRoot !== void 0 ? { verifiedLocalStateRoot: normalizedVerifiedLocalStateRoot } : {},
724
+ ...extra?.forcedFailureReason !== void 0 ? { forcedFailureReason: extra.forcedFailureReason } : {},
725
+ ...extra?.existingCheckpointAtHeight !== void 0 ? { existingCheckpointAtHeight: extra.existingCheckpointAtHeight } : {},
726
+ computeStateRoot: (segEntries) => deriveSegmentStateRoot(segEntries, extra?.prevStateRoot)
727
+ });
728
+ const localWitnessRegistry = this.resolver.ledger.getWitnessRegistry?.();
729
+ if (localWitnessRegistry?.hasTrustedWitnessAllowlist()) await localWitnessRegistry.submitAttestation(attestation).catch(() => void 0);
730
+ await Promise.all(this.witnessSubmitUrls.map(async (baseUrl) => {
731
+ try {
732
+ await readBoundedText(await this.fetchImpl(`${baseUrl}/api/ledger/witness/attestations`, {
733
+ method: "POST",
734
+ headers: {
735
+ "content-type": "application/json",
736
+ accept: "application/json"
737
+ },
738
+ body: JSON.stringify({ attestation }),
739
+ redirect: "error",
740
+ signal: AbortSignal.timeout(WITNESS_POST_TIMEOUT_MS)
741
+ }), WITNESS_POST_MAX_RESPONSE_BYTES).catch(() => void 0);
742
+ } catch (err) {
743
+ this.resolver.logger.warn("Witness attestation submission failed (non-blocking)", {
744
+ chainId: this.chainId,
745
+ height: checkpoint.height,
746
+ targetUrl: baseUrl,
747
+ error: err instanceof Error ? err.message : String(err)
748
+ });
749
+ }
750
+ }));
751
+ return attestation;
752
+ }
753
+ enqueueWitnessAttestation(checkpoint, entries, extra) {
754
+ if (!this.witnessWallet || this.stopped) return;
755
+ const task = this.dispatchWitnessAttestation(checkpoint, entries, extra).then(() => void 0).catch(() => void 0).finally(() => {
756
+ this.pendingWitnessTasks.delete(task);
757
+ });
758
+ this.pendingWitnessTasks.add(task);
759
+ }
760
+ async checkCheckpointEquivocationAgainstLocal(candidateCp, options) {
761
+ if (!candidateCp || typeof candidateCp.height !== "number" || !Number.isSafeInteger(candidateCp.height) || candidateCp.height < 1) return;
762
+ const isStructurallyValidCandidateCp = () => {
763
+ if (typeof candidateCp.hash !== "string" || !candidateCp.hash || !Number.isSafeInteger(candidateCp.sequence) || !Number.isSafeInteger(candidateCp.prevSequence) || !Number.isSafeInteger(candidateCp.txCount) || candidateCp.txCount <= 0 || candidateCp.txCount !== candidateCp.sequence - candidateCp.prevSequence) return false;
764
+ if (candidateCp.height === 1 && (candidateCp.prevSequence !== 0 || candidateCp.prevCheckpoint !== null && candidateCp.prevCheckpoint !== void 0)) return false;
765
+ return normalizeHexDigest(computeCheckpointHash(candidateCp)) === normalizeHexDigest(candidateCp.hash);
766
+ };
767
+ const existingLocalCp = await this.resolver.ledger.getCheckpoint(candidateCp.height);
768
+ if (existingLocalCp) {
769
+ if (normalizeHexDigest(existingLocalCp.hash) === normalizeHexDigest(candidateCp.hash)) return;
770
+ if (!isStructurallyValidCandidateCp()) throw new CustomError("INVALID_CHECKPOINT_HASH", `Conflicting checkpoint at height ${candidateCp.height} failed structural hash validation`);
771
+ if (!await this.isCheckpointAuthenticatedByProposer(candidateCp)) {
772
+ if (!(await this.isCheckpointAuthenticatedByProposer(existingLocalCp) || this.getEffectiveSeenSignedUpstream()) && this.buildSegmentImportOptions().allowUnauthenticated && options?.unauthenticatedChainMatched === true) {
773
+ const divErr = new CustomError("LEDGER_DIVERGENCE", `Local checkpoint divergence at height ${candidateCp.height}: local ${existingLocalCp.hash} vs upstream ${candidateCp.hash}`);
774
+ if (options?.isMultiPeerMode === true) divErr.unauthenticatedPeerDivergence = true;
775
+ else divErr.localDivergenceFailure = true;
776
+ throw divErr;
777
+ }
778
+ throw new CustomError("INVALID_CHECKPOINT_SIGNATURE", `Conflicting checkpoint at height ${candidateCp.height} failed proposer authentication`);
779
+ }
780
+ if (options?.chainBoundAuthenticated !== true) throw new CustomError("UNAUTHENTICATED_STATUS_CHAIN_BINDING", `Conflicting checkpoint at height ${candidateCp.height} lacks chain-bound proposer attestation for ${this.chainId}`);
781
+ this.seenSignedUpstream = true;
782
+ const eqReason = `Proposer checkpoint equivocation detected at height ${candidateCp.height}: local ${existingLocalCp.hash} vs upstream ${candidateCp.hash}`;
783
+ if (this.witnessWallet) await this.dispatchWitnessAttestation(candidateCp, [], {
784
+ existingCheckpointAtHeight: existingLocalCp,
785
+ verifiedLocalStateRoot: existingLocalCp.stateRoot ?? null,
786
+ forcedFailureReason: eqReason,
787
+ allowDuplicateHeight: true
788
+ }).catch(() => void 0);
789
+ const eqErr = new CustomError("EQUIVOCATION_DETECTED", eqReason);
790
+ eqErr.authenticatedLocalFailure = true;
791
+ throw eqErr;
792
+ }
793
+ if (candidateCp.height > 1) {
794
+ const parentLocalCp = await this.resolver.ledger.getCheckpoint(candidateCp.height - 1);
795
+ if (parentLocalCp) {
796
+ const prevHashMatches = typeof candidateCp.prevCheckpoint === "string" && normalizeHexDigest(parentLocalCp.hash) === normalizeHexDigest(candidateCp.prevCheckpoint);
797
+ const prevSeqMatches = candidateCp.prevSequence === parentLocalCp.sequence;
798
+ if (!prevHashMatches || !prevSeqMatches) {
799
+ if (!isStructurallyValidCandidateCp()) throw new CustomError("INVALID_CHECKPOINT_HASH", `Divergent child checkpoint at height ${candidateCp.height} failed structural hash validation`);
800
+ if (!await this.isCheckpointAuthenticatedByProposer(candidateCp)) {
801
+ if (!(await this.isCheckpointAuthenticatedByProposer(parentLocalCp) || this.getEffectiveSeenSignedUpstream()) && this.buildSegmentImportOptions().allowUnauthenticated && options?.unauthenticatedChainMatched === true) {
802
+ const divErr = new CustomError("LEDGER_DIVERGENCE", `Local checkpoint parent divergence at height ${candidateCp.height}: prevCheckpoint ${String(candidateCp.prevCheckpoint)} (prevSequence ${String(candidateCp.prevSequence)}) diverges from local parent height ${parentLocalCp.height} (${parentLocalCp.hash}, seq ${parentLocalCp.sequence})`);
803
+ if (options?.isMultiPeerMode === true) divErr.unauthenticatedPeerDivergence = true;
804
+ else divErr.localDivergenceFailure = true;
805
+ throw divErr;
806
+ }
807
+ throw new CustomError("INVALID_CHECKPOINT_SIGNATURE", `Divergent child checkpoint at height ${candidateCp.height} failed proposer authentication`);
808
+ }
809
+ if (options?.chainBoundAuthenticated !== true) throw new CustomError("UNAUTHENTICATED_STATUS_CHAIN_BINDING", `Divergent child checkpoint at height ${candidateCp.height} lacks chain-bound proposer attestation for ${this.chainId}`);
810
+ this.seenSignedUpstream = true;
811
+ const parentEqReason = `Proposer checkpoint equivocation detected at height ${candidateCp.height}: prevCheckpoint ${String(candidateCp.prevCheckpoint)} (prevSequence ${String(candidateCp.prevSequence)}) diverges from local parent height ${parentLocalCp.height} (${parentLocalCp.hash}, seq ${parentLocalCp.sequence})`;
812
+ if (this.witnessWallet) await this.dispatchWitnessAttestation(candidateCp, [], {
813
+ expectedPrevCheckpoint: parentLocalCp.hash,
814
+ prevStateRoot: parentLocalCp.stateRoot,
815
+ verifiedLocalStateRoot: parentLocalCp.stateRoot ?? null,
816
+ forcedFailureReason: parentEqReason,
817
+ allowDuplicateHeight: true
818
+ }).catch(() => void 0);
819
+ const eqErr = new CustomError("EQUIVOCATION_DETECTED", parentEqReason);
820
+ eqErr.authenticatedLocalFailure = true;
821
+ throw eqErr;
822
+ }
823
+ }
824
+ }
825
+ }
826
+ buildSegmentImportOptions() {
827
+ const effectiveProposer = this.getEffectiveTrustedProposer();
828
+ const effectiveProposerPk = this.getEffectiveTrustedProposerPublicKey();
829
+ const effectiveSeenSigned = this.getEffectiveSeenSignedUpstream();
830
+ return {
831
+ ...!this.hotstuffClusterConfig && effectiveProposer ? { expectedProposer: effectiveProposer } : {},
832
+ ...effectiveProposerPk ? { proposerPublicKey: effectiveProposerPk } : {},
833
+ ...this.verifier ? { verifier: this.verifier } : {},
834
+ ...this.hotstuffClusterConfig ? { hotstuffClusterConfig: this.hotstuffClusterConfig } : {},
835
+ allowUnauthenticated: this.allowUnauthenticated && !this.hotstuffClusterConfig && !effectiveSeenSigned,
836
+ verifyStateRoot: true
837
+ };
838
+ }
839
+ async verifyAndPinTrustAnchorFromStatus(status) {
840
+ if (this.hotstuffClusterConfig) {
841
+ if (!status.proposer || !this.isAllowedHotStuffValidator(status.proposer)) {
842
+ if (!this.allowUnauthenticated) throw new CustomError("PROPOSER_MISMATCH", `Upstream proposer ${String(status.proposer ?? "missing")} is not in HOTSTUFF_VALIDATORS allowlist`);
843
+ return;
844
+ }
845
+ if (status.proposerPublicKey && !verifyDidMatchesMultiCurvePublicKey(status.proposer, status.proposerPublicKey)) {
846
+ if (!this.allowUnauthenticated) throw new CustomError("PROPOSER_MISMATCH", `Upstream proposerPublicKey does not match validator DID ${status.proposer}`);
847
+ }
848
+ return;
849
+ }
850
+ if (status.proposer && this.trustedProposer) {
851
+ if (normalizeDidCompare(status.proposer) !== normalizeDidCompare(this.trustedProposer)) throw new CustomError("PROPOSER_MISMATCH", `Upstream proposer mismatch: expected ${this.trustedProposer}, got ${status.proposer}`);
852
+ }
853
+ const statusIsSigned = status.checkpointSigningEnabled !== false && Boolean(status.statusSignature && status.proposer);
854
+ if (this.allowUnauthenticated && !statusIsSigned) return;
855
+ const hadAuthoritativeProposer = Boolean(this.trustedProposer || this.trustedProposerPublicKey || this.verifier);
856
+ const candidateProposer = this.trustedProposer || (this.allowUnauthenticated ? status.proposer || null : null);
857
+ if (!this.trustedProposerPublicKey && status.proposerPublicKey && candidateProposer) {
858
+ if (!await this.verifyDidOrAccountMatchesPublicKey(candidateProposer, status.proposerPublicKey)) {
859
+ if (!this.allowUnauthenticated) throw new CustomError("PROPOSER_MISMATCH", `Upstream proposerPublicKey does not match proposer DID ${candidateProposer}`);
860
+ return;
861
+ }
862
+ if (this.allowUnauthenticated && status.statusSignature && status.proposer) {
863
+ const candidateAnchor = resolveTrustAnchor({
864
+ proposerPublicKey: status.proposerPublicKey,
865
+ verifier: this.verifier
866
+ });
867
+ if (!candidateAnchor) return;
868
+ if (!await verifyHotTailStatusSignature({
869
+ chainId: status.chainId,
870
+ latestSequence: status.latestSequence,
871
+ checkpointHeight: status.latestCheckpoint?.height ?? 0,
872
+ checkpointHash: status.latestCheckpoint?.hash ?? null,
873
+ writable: status.writable !== false,
874
+ proposer: status.proposer,
875
+ ...status.entryHashV2From !== void 0 ? { entryHashV2From: status.entryHashV2From } : {}
876
+ }, status.statusSignature, candidateAnchor, candidateProposer)) throw new CustomError("HOT_TAIL_SIGNATURE_INVALID", "Invalid proposer statusSignature on /api/ledger/status");
877
+ }
878
+ if (!hadAuthoritativeProposer && this.allowUnauthenticated) {
879
+ this.stagedTofuAnchor = {
880
+ proposer: candidateProposer,
881
+ proposerPublicKey: status.proposerPublicKey,
882
+ seenSignedUpstream: false,
883
+ seenSignedStatus: false
884
+ };
885
+ return;
886
+ }
887
+ if (!this.trustedProposer) this.trustedProposer = candidateProposer;
888
+ this.trustedProposerPublicKey = status.proposerPublicKey;
889
+ this.leaderRouter?.updateTrustAnchor?.({
890
+ proposer: candidateProposer,
891
+ proposerPublicKey: status.proposerPublicKey
892
+ });
893
+ if (status.statusSignature && status.proposer) await this.persistTrustAnchorSafe({
894
+ proposer: candidateProposer,
895
+ proposerPublicKey: status.proposerPublicKey
896
+ });
897
+ } else if (!this.trustedProposer && this.trustedProposerPublicKey && status.proposer && this.allowUnauthenticated && statusIsSigned && status.statusSignature) {
898
+ if (!await this.verifyDidOrAccountMatchesPublicKey(status.proposer, this.trustedProposerPublicKey)) return;
899
+ const existingAnchor = resolveTrustAnchor({
900
+ proposerPublicKey: this.trustedProposerPublicKey,
901
+ verifier: this.verifier
902
+ });
903
+ if (!existingAnchor) return;
904
+ if (!await verifyHotTailStatusSignature({
905
+ chainId: status.chainId,
906
+ latestSequence: status.latestSequence,
907
+ checkpointHeight: status.latestCheckpoint?.height ?? 0,
908
+ checkpointHash: status.latestCheckpoint?.hash ?? null,
909
+ writable: status.writable !== false,
910
+ proposer: status.proposer,
911
+ ...status.entryHashV2From !== void 0 ? { entryHashV2From: status.entryHashV2From } : {}
912
+ }, status.statusSignature, existingAnchor, status.proposer)) throw new CustomError("HOT_TAIL_SIGNATURE_INVALID", "Invalid proposer statusSignature on /api/ledger/status");
913
+ this.trustedProposer = status.proposer;
914
+ await this.persistTrustAnchorSafe({
915
+ proposer: status.proposer,
916
+ proposerPublicKey: String(this.trustedProposerPublicKey)
917
+ });
918
+ }
919
+ }
920
+ async verifyDidOrAccountMatchesPublicKey(did, publicKey) {
921
+ if (verifyDidMatchesMultiCurvePublicKey(did, publicKey)) return true;
922
+ let onChainAccount = null;
923
+ try {
924
+ onChainAccount = await Promise.resolve(this.resolver.statedb.account.get(did));
925
+ } catch (err) {
926
+ this.rethrowIfLocalStorageOrLockError(err);
927
+ onChainAccount = null;
928
+ }
929
+ if (onChainAccount?.pk) try {
930
+ return toBuffer(onChainAccount.pk).equals(toBuffer(publicKey));
931
+ } catch {
932
+ return false;
933
+ }
934
+ return false;
935
+ }
936
+ /**
937
+ * Re-hydrate `seenSignedUpstream` and any TOFU-pinned proposer trust anchor from durable `ledger`
938
+ * storage on process restart so `allowUnauthenticated` cannot regress after sealing signed checkpoints
939
+ * or pinning a verified proposer key (#1856).
940
+ */
941
+ async hydrateDurableTrustRatchet() {
942
+ let localCp = null;
943
+ let persistedAnchor = null;
944
+ try {
945
+ [localCp, persistedAnchor] = await Promise.all([this.resolver.ledger.getCheckpoint(), Promise.resolve(this.resolver.ledger.getPersistedTrustAnchor?.() ?? null)]);
946
+ } catch (err) {
947
+ this.rethrowIfLocalStorageOrLockError(err);
948
+ }
949
+ const localHasSignedCheckpoint = Boolean(localCp?.signature && localCp.signature !== "unsigned");
950
+ if (this.hotstuffClusterConfig) {
951
+ if (localHasSignedCheckpoint && localCp?.qc && verifyCheckpointQuorumCertificate(localCp, this.hotstuffClusterConfig).ok) this.seenSignedUpstream = true;
952
+ return;
953
+ }
954
+ if (!this.allowUnauthenticated && !this.trustedProposer && localCp?.proposer) this.trustedProposer = localCp.proposer;
955
+ if (persistedAnchor?.proposer && (!this.trustedProposer || normalizeDidCompare(this.trustedProposer) === normalizeDidCompare(persistedAnchor.proposer))) {
956
+ if (persistedAnchor.proposerPublicKey) {
957
+ if (await this.verifyDidOrAccountMatchesPublicKey(persistedAnchor.proposer, persistedAnchor.proposerPublicKey)) {
958
+ this.seenSignedUpstream = true;
959
+ if (!this.trustedProposer) this.trustedProposer = persistedAnchor.proposer;
960
+ if (!this.trustedProposerPublicKey) {
961
+ this.trustedProposerPublicKey = persistedAnchor.proposerPublicKey;
962
+ this.leaderRouter?.updateTrustAnchor?.({
963
+ proposer: this.trustedProposer,
964
+ proposerPublicKey: this.trustedProposerPublicKey
965
+ });
966
+ }
967
+ }
968
+ } else if (persistedAnchor.signatureRatchetLocked && this.verifier) {
969
+ this.seenSignedUpstream = true;
970
+ if (!this.trustedProposer) this.trustedProposer = persistedAnchor.proposer;
971
+ }
972
+ }
973
+ if (localHasSignedCheckpoint && localCp && !this.seenSignedUpstream) {
974
+ const configuredAnchor = resolveTrustAnchor({
975
+ proposerPublicKey: this.trustedProposerPublicKey,
976
+ verifier: this.verifier
977
+ });
978
+ if (configuredAnchor) {
979
+ if (await verifyCheckpointSignature(localCp, configuredAnchor, this.trustedProposer || localCp.proposer).catch(() => false)) {
980
+ this.seenSignedUpstream = true;
981
+ if (!this.trustedProposer && localCp.proposer) this.trustedProposer = localCp.proposer;
982
+ }
983
+ } else {
984
+ const candidateProposer = this.trustedProposer || localCp.proposer;
985
+ if (candidateProposer) {
986
+ let onChainAccount = null;
987
+ try {
988
+ onChainAccount = await Promise.resolve(this.resolver.statedb.account.get(candidateProposer));
989
+ } catch (err) {
990
+ this.rethrowIfLocalStorageOrLockError(err);
991
+ onChainAccount = null;
992
+ }
993
+ if (onChainAccount?.pk) {
994
+ let candidatePk = "";
995
+ try {
996
+ candidatePk = typeof onChainAccount.pk === "string" ? onChainAccount.pk.trim() : toBuffer(onChainAccount.pk).toString("hex");
997
+ } catch {
998
+ candidatePk = "";
999
+ }
1000
+ if (candidatePk) {
1001
+ if (await verifyCheckpointSignature(localCp, candidatePk, candidateProposer).catch(() => false)) {
1002
+ this.seenSignedUpstream = true;
1003
+ this.trustedProposer = candidateProposer;
1004
+ this.trustedProposerPublicKey = candidatePk;
1005
+ this.leaderRouter?.updateTrustAnchor?.({
1006
+ proposer: candidateProposer,
1007
+ proposerPublicKey: candidatePk
1008
+ });
1009
+ await this.persistTrustAnchorSafe({
1010
+ proposer: candidateProposer,
1011
+ proposerPublicKey: candidatePk
1012
+ });
1013
+ }
1014
+ }
1015
+ }
1016
+ }
1017
+ }
1018
+ }
1019
+ }
1020
+ tagColdTransportError(err) {
1021
+ if (err && typeof err === "object" && err.localStorageFailure !== true && err.authenticatedLocalFailure !== true && err.localDivergenceFailure !== true) err.upstreamTransportFailure = true;
1022
+ throw err;
1023
+ }
1024
+ async fetchColdSegment(height, verifyOptions) {
1025
+ if (!this.coldArchiveStore) return null;
1026
+ try {
1027
+ return await this.coldArchiveStore.getSegment(this.chainId, height, verifyOptions);
1028
+ } catch (err) {
1029
+ return this.tagColdTransportError(err);
1030
+ }
1031
+ }
1032
+ async fetchColdArchiveHead() {
1033
+ if (!this.coldArchiveStore) return null;
1034
+ try {
1035
+ return await this.coldArchiveStore.getLatestHead?.(this.chainId) ?? await this.coldArchiveStore.getArchiveHead?.(this.chainId) ?? null;
1036
+ } catch (err) {
1037
+ return this.tagColdTransportError(err);
1038
+ }
1039
+ }
1040
+ async fetchAllowlistedJson(baseUrl, pathAndQuery, maxBytes) {
1041
+ if (!this.allowedBaseUrls.has(baseUrl)) throw new CustomError("FORBIDDEN", `Upstream URL ${baseUrl} is not in allowlist`);
1042
+ let response;
1043
+ let text;
1044
+ try {
1045
+ response = await this.fetchImpl(`${baseUrl}${pathAndQuery}`, {
1046
+ method: "GET",
1047
+ headers: { Accept: "application/json" },
1048
+ redirect: "error",
1049
+ signal: AbortSignal.timeout(this.httpTimeoutMs)
1050
+ });
1051
+ text = await readBoundedText(response, maxBytes);
1052
+ } catch (fetchErr) {
1053
+ if (fetchErr && typeof fetchErr === "object") fetchErr.upstreamTransportFailure = true;
1054
+ throw fetchErr;
1055
+ }
1056
+ let parsed;
1057
+ try {
1058
+ parsed = text ? JSON.parse(text) : {};
1059
+ } catch {
1060
+ throw new CustomError("UPSTREAM_BAD_RESPONSE", `Invalid JSON from ${baseUrl}${pathAndQuery}`);
1061
+ }
1062
+ return {
1063
+ status: response.status,
1064
+ body: parsed
1065
+ };
1066
+ }
1067
+ /**
1068
+ * Stage 1B: Catch up sealed `.zst` checkpoint segments from `coldArchiveStore` when available.
1069
+ */
1070
+ async catchUpFromColdSegments(maxTargetHeight, verifiedHeadCheckpoint) {
1071
+ if (!this.coldArchiveStore) return 0;
1072
+ await this.hydrateDurableTrustRatchet();
1073
+ const verifiedColdAncestors = /* @__PURE__ */ new Map();
1074
+ if (verifiedHeadCheckpoint && typeof verifiedHeadCheckpoint.hash === "string" && normalizeHexDigest(computeCheckpointHash(verifiedHeadCheckpoint)) === normalizeHexDigest(verifiedHeadCheckpoint.hash)) verifiedColdAncestors.set(verifiedHeadCheckpoint.height, verifiedHeadCheckpoint);
1075
+ let importedCount = 0;
1076
+ while (!this.halted && !this.stopped) {
1077
+ const [localCp, localSeq] = await Promise.all([this.resolver.ledger.getCheckpoint(), this.resolver.ledger.getLatestSequence()]);
1078
+ const nextHeight = (localCp?.height ?? 0) + 1;
1079
+ if (maxTargetHeight !== void 0 && nextHeight > maxTargetHeight) break;
1080
+ const importOpts = this.buildSegmentImportOptions();
1081
+ const localHasSignedCheckpoint = Boolean(localCp?.signature && localCp.signature !== "unsigned");
1082
+ const canAllowUnsignedCutoverAncestor = this.allowUnauthenticated && !this.hotstuffClusterConfig && !localHasSignedCheckpoint && verifiedColdAncestors.size > 0 && verifiedHeadCheckpoint != null && nextHeight < verifiedHeadCheckpoint.height && verifiedHeadCheckpoint.height - nextHeight <= MAX_STATUS_CHECKPOINT_CHAIN_WALK;
1083
+ const isMultiProviderReplicator = "replicateSegment" in this.coldArchiveStore;
1084
+ const coldVerifyAnchor = importOpts.allowUnauthenticated ? void 0 : importOpts.proposerPublicKey ?? importOpts.verifier;
1085
+ let rawSegment = await this.fetchColdSegment(nextHeight, isMultiProviderReplicator ? {
1086
+ expectedChainId: this.chainId,
1087
+ expectedHeight: nextHeight,
1088
+ expectedProposer: importOpts.expectedProposer,
1089
+ publicKeyOrVerifier: coldVerifyAnchor,
1090
+ requireSignature: !importOpts.allowUnauthenticated,
1091
+ allowUnauthenticated: importOpts.allowUnauthenticated
1092
+ } : void 0).catch((err) => {
1093
+ if (canAllowUnsignedCutoverAncestor) return null;
1094
+ throw err;
1095
+ });
1096
+ if (!rawSegment && isMultiProviderReplicator && canAllowUnsignedCutoverAncestor) rawSegment = await this.fetchColdSegment(nextHeight, {
1097
+ expectedChainId: this.chainId,
1098
+ expectedHeight: nextHeight,
1099
+ expectedProposer: importOpts.expectedProposer,
1100
+ requireSignature: false,
1101
+ allowUnauthenticated: true
1102
+ });
1103
+ if (!rawSegment) break;
1104
+ if (!rawSegment.checkpoint || typeof rawSegment.checkpoint !== "object" || !Array.isArray(rawSegment.entries) || rawSegment.checkpoint.height !== nextHeight) throw new CustomError("COLD_SEGMENT_HEIGHT_MISMATCH", `Cold archive returned misaligned segment for height #${nextHeight} (got ${String(rawSegment.checkpoint?.height)})`);
1105
+ const rawBundle = rawSegment;
1106
+ if ("txHashes" in rawBundle && rawBundle.txHashes !== void 0) {
1107
+ if (!Array.isArray(rawBundle.txHashes) || rawBundle.txHashes.length !== rawSegment.entries.length || rawBundle.txHashes.some((h, idx) => h !== rawSegment.entries[idx]?.hash)) throw new CustomError("COLD_BUNDLE_WRAPPER_MISMATCH", `Cold segment #${nextHeight} unsigned txHashes wrapper does not match entries`);
1108
+ }
1109
+ const canonicalSegment = {
1110
+ chainId: rawSegment.chainId,
1111
+ checkpoint: rawSegment.checkpoint,
1112
+ entries: rawSegment.entries
1113
+ };
1114
+ if ("contentHash" in rawBundle && rawBundle.contentHash !== void 0) {
1115
+ if (typeof rawBundle.contentHash !== "string" || rawBundle.contentHash.replace(/^0x/i, "").toLowerCase() !== computeSegmentContentHash(canonicalSegment).replace(/^0x/i, "").toLowerCase()) throw new CustomError("COLD_BUNDLE_WRAPPER_MISMATCH", `Cold segment #${nextHeight} unsigned contentHash wrapper does not match canonical segment digest`);
1116
+ }
1117
+ const segProposerAuth = await this.isColdSegmentAuthenticatedByProposer(canonicalSegment);
1118
+ if (segProposerAuth) this.seenSignedUpstream = true;
1119
+ let isVerifiedColdCutoverAncestor = false;
1120
+ if (canAllowUnsignedCutoverAncestor && verifiedHeadCheckpoint && (!canonicalSegment.checkpoint.signature || canonicalSegment.checkpoint.signature === "unsigned")) if (verifiedColdAncestors.has(nextHeight)) {
1121
+ const expectedAncestor = verifiedColdAncestors.get(nextHeight);
1122
+ isVerifiedColdCutoverAncestor = typeof canonicalSegment.checkpoint.hash === "string" && normalizeHexDigest(canonicalSegment.checkpoint.hash) === normalizeHexDigest(expectedAncestor.hash) && normalizeHexDigest(computeCheckpointHash(canonicalSegment.checkpoint)) === normalizeHexDigest(expectedAncestor.hash);
1123
+ } else {
1124
+ let walkOk = true;
1125
+ const walked = /* @__PURE__ */ new Map();
1126
+ let cursorCp = verifiedHeadCheckpoint;
1127
+ for (let h = verifiedHeadCheckpoint.height - 1; h >= nextHeight; h--) {
1128
+ const expectedHash = cursorCp.prevCheckpoint;
1129
+ if (typeof expectedHash !== "string" || !expectedHash) {
1130
+ walkOk = false;
1131
+ break;
1132
+ }
1133
+ let stepCp = h === nextHeight ? canonicalSegment.checkpoint : verifiedColdAncestors.get(h) ?? null;
1134
+ if (!stepCp) {
1135
+ const stepSeg = await this.coldArchiveStore.getSegment(this.chainId, h).catch(() => null);
1136
+ stepCp = stepSeg && stepSeg.chainId === this.chainId ? stepSeg.checkpoint : null;
1137
+ }
1138
+ if (!stepCp || typeof stepCp.hash !== "string" || normalizeHexDigest(stepCp.hash) !== normalizeHexDigest(expectedHash) || normalizeHexDigest(computeCheckpointHash(stepCp)) !== normalizeHexDigest(expectedHash)) {
1139
+ walkOk = false;
1140
+ break;
1141
+ }
1142
+ walked.set(h, stepCp);
1143
+ cursorCp = stepCp;
1144
+ }
1145
+ if (walkOk) {
1146
+ for (const [h, cp] of walked) verifiedColdAncestors.set(h, cp);
1147
+ isVerifiedColdCutoverAncestor = true;
1148
+ }
1149
+ }
1150
+ const effectiveImportOpts = isVerifiedColdCutoverAncestor ? {
1151
+ ...importOpts,
1152
+ allowUnauthenticated: true
1153
+ } : importOpts;
1154
+ const effectiveColdVerifyAnchor = effectiveImportOpts.allowUnauthenticated ? void 0 : effectiveImportOpts.proposerPublicKey ?? effectiveImportOpts.verifier;
1155
+ await this.checkCheckpointEquivocationAgainstLocal(canonicalSegment.checkpoint, {
1156
+ chainBoundAuthenticated: segProposerAuth,
1157
+ unauthenticatedChainMatched: effectiveImportOpts.allowUnauthenticated
1158
+ });
1159
+ const expectedPrevHash = localCp?.hash ?? null;
1160
+ const actualPrevHash = canonicalSegment.checkpoint.prevCheckpoint ?? null;
1161
+ const isAlignedHeightAndParent = canonicalSegment.checkpoint.height === nextHeight && canonicalSegment.checkpoint.prevSequence === (localCp?.sequence ?? 0) && (expectedPrevHash === null ? actualPrevHash === null : typeof actualPrevHash === "string" && expectedPrevHash.replace(/^0x/i, "").toLowerCase() === actualPrevHash.replace(/^0x/i, "").toLowerCase());
1162
+ try {
1163
+ if (typeof this.resolver.ledger.verifySegmentForImport === "function") await this.resolver.ledger.verifySegmentForImport(canonicalSegment, {
1164
+ ...effectiveImportOpts,
1165
+ allowAheadLocalSequence: true
1166
+ });
1167
+ else {
1168
+ await assertValidSegment(canonicalSegment, {
1169
+ expectedChainId: this.chainId,
1170
+ expectedHeight: nextHeight,
1171
+ expectedProposer: effectiveImportOpts.expectedProposer,
1172
+ publicKeyOrVerifier: effectiveColdVerifyAnchor,
1173
+ requireSignature: !effectiveImportOpts.allowUnauthenticated,
1174
+ allowUnauthenticated: effectiveImportOpts.allowUnauthenticated
1175
+ });
1176
+ if (effectiveImportOpts.verifyStateRoot !== false) {
1177
+ const derivedRoot = deriveSegmentStateRoot(canonicalSegment.entries, localCp?.stateRoot);
1178
+ if ((canonicalSegment.checkpoint.stateRoot || "") !== derivedRoot) throw new CustomError("STATE_COMMIT_MISMATCH", `Cold segment #${nextHeight} stateRoot mismatch: checkpoint has ${canonicalSegment.checkpoint.stateRoot}, derived ${derivedRoot}`);
1179
+ }
1180
+ }
1181
+ } catch (segVerifyErr) {
1182
+ if (isTransientSqliteLockError(segVerifyErr)) throw segVerifyErr;
1183
+ if (isLocalTrustedStorageHashError(segVerifyErr) || isLocalLedgerStorageCorruptionError(segVerifyErr)) {
1184
+ segVerifyErr.localDivergenceFailure = true;
1185
+ segVerifyErr.authenticatedLocalFailure = false;
1186
+ throw segVerifyErr;
1187
+ }
1188
+ if (segProposerAuth && isAlignedHeightAndParent) segVerifyErr.authenticatedLocalFailure = true;
1189
+ if (this.witnessWallet && segProposerAuth && isAlignedHeightAndParent) {
1190
+ const fraudLocalRoot = await this.resolveLocalFraudAlertStateRoot(localCp);
1191
+ await this.dispatchWitnessAttestation(canonicalSegment.checkpoint, canonicalSegment.entries, {
1192
+ expectedPrevCheckpoint: expectedPrevHash,
1193
+ prevStateRoot: localCp?.stateRoot,
1194
+ verifiedLocalStateRoot: fraudLocalRoot,
1195
+ forcedFailureReason: segVerifyErr instanceof Error ? segVerifyErr.message : String(segVerifyErr),
1196
+ allowDuplicateHeight: true
1197
+ }).catch(() => void 0);
1198
+ }
1199
+ throw segVerifyErr;
1200
+ }
1201
+ for (const entry of canonicalSegment.entries) this.replayer.validateWireEntry(entry);
1202
+ const hadPartialLocalEntries = localSeq > canonicalSegment.checkpoint.prevSequence;
1203
+ let mutatedLocalDb = false;
1204
+ try {
1205
+ if (localSeq === canonicalSegment.checkpoint.prevSequence) {
1206
+ if (canonicalSegment.entries.length > 0 && typeof this.resolver.statedb.runWithinDryRunSession === "function") {
1207
+ const dryRun = await this.replayer.dryRunVerifyEntries(canonicalSegment.entries, {
1208
+ expectedPrevSequence: localSeq,
1209
+ prevStateRoot: localCp?.stateRoot ?? null
1210
+ });
1211
+ const normDerived = String(dryRun.derivedStateRoot ?? "").replace(/^0x/i, "").toLowerCase();
1212
+ const normCpRoot = String(canonicalSegment.checkpoint.stateRoot ?? "").replace(/^0x/i, "").toLowerCase();
1213
+ if (normCpRoot && normDerived !== normCpRoot) throw new CustomError("STATE_COMMIT_MISMATCH", `Cold segment #${nextHeight} dry-run stateRoot (${dryRun.derivedStateRoot}) !== checkpoint stateRoot (${canonicalSegment.checkpoint.stateRoot})`);
1214
+ }
1215
+ this.pendingCrashWindowReconcile = true;
1216
+ try {
1217
+ await this.resolver.ledger.importSegment(canonicalSegment, effectiveImportOpts);
1218
+ mutatedLocalDb = true;
1219
+ } catch (importErr) {
1220
+ if (await this.resolver.ledger.getLatestSequence().catch(() => localSeq) > localSeq) mutatedLocalDb = true;
1221
+ else this.pendingCrashWindowReconcile = false;
1222
+ throw importErr;
1223
+ }
1224
+ for (const entry of canonicalSegment.entries) await this.replayer.replayEntry(entry, { appendToLedger: false });
1225
+ this.pendingCrashWindowReconcile = false;
1226
+ this.leaderRouter?.advanceMinVerifiedCheckpointHeight?.(canonicalSegment.checkpoint.height);
1227
+ } else if (localSeq > canonicalSegment.checkpoint.prevSequence && localSeq < canonicalSegment.checkpoint.sequence) {
1228
+ for (const entry of canonicalSegment.entries) if (entry.sequence > localSeq) await this.replayer.replayEntry(entry, { appendToLedger: true });
1229
+ if (typeof this.resolver.ledger.sealVerifiedCheckpoint === "function") {
1230
+ await this.resolver.ledger.sealVerifiedCheckpoint(canonicalSegment.checkpoint, {
1231
+ ...effectiveImportOpts,
1232
+ chainBoundAuthenticated: segProposerAuth
1233
+ });
1234
+ this.leaderRouter?.advanceMinVerifiedCheckpointHeight?.(canonicalSegment.checkpoint.height);
1235
+ }
1236
+ } else if (localSeq >= canonicalSegment.checkpoint.sequence) {
1237
+ if (typeof this.resolver.ledger.sealVerifiedCheckpoint === "function") {
1238
+ await this.resolver.ledger.sealVerifiedCheckpoint(canonicalSegment.checkpoint, {
1239
+ ...effectiveImportOpts,
1240
+ chainBoundAuthenticated: segProposerAuth
1241
+ });
1242
+ this.leaderRouter?.advanceMinVerifiedCheckpointHeight?.(canonicalSegment.checkpoint.height);
1243
+ }
1244
+ } else break;
1245
+ } catch (replayErr) {
1246
+ if (isTransientSqliteLockError(replayErr)) {
1247
+ if (mutatedLocalDb) replayErr.mutatedLocalDbTransientLock = true;
1248
+ throw replayErr;
1249
+ }
1250
+ const errCode = replayErr?.code;
1251
+ if (isLocalTrustedStorageHashError(replayErr) || isLocalLedgerStorageCorruptionError(replayErr)) {
1252
+ replayErr.localDivergenceFailure = true;
1253
+ replayErr.authenticatedLocalFailure = false;
1254
+ throw replayErr;
1255
+ }
1256
+ if (mutatedLocalDb) replayErr.localDivergenceFailure = true;
1257
+ if (isAlignedHeightAndParent && (isLocalExecutionDivergenceCode(errCode) || isLocalCheckpointSealDivergenceError(replayErr))) {
1258
+ if (segProposerAuth) replayErr.authenticatedLocalFailure = true;
1259
+ if (effectiveImportOpts.allowUnauthenticated || hadPartialLocalEntries || mutatedLocalDb) replayErr.localDivergenceFailure = true;
1260
+ }
1261
+ if (this.witnessWallet && segProposerAuth && isAlignedHeightAndParent && replayErr?.authenticatedLocalFailure === true) {
1262
+ const fraudLocalRoot = await this.resolveLocalFraudAlertStateRoot(localCp);
1263
+ await this.dispatchWitnessAttestation(canonicalSegment.checkpoint, canonicalSegment.entries, {
1264
+ expectedPrevCheckpoint: expectedPrevHash,
1265
+ prevStateRoot: localCp?.stateRoot,
1266
+ verifiedLocalStateRoot: fraudLocalRoot,
1267
+ forcedFailureReason: replayErr instanceof Error ? replayErr.message : String(replayErr),
1268
+ allowDuplicateHeight: true
1269
+ }).catch(() => void 0);
1270
+ }
1271
+ throw replayErr;
1272
+ }
1273
+ if (!this.hotstuffClusterConfig && !this.trustedProposer && canonicalSegment.checkpoint.proposer) this.trustedProposer = canonicalSegment.checkpoint.proposer;
1274
+ if (canonicalSegment.checkpoint.signature && canonicalSegment.checkpoint.signature !== "unsigned") {
1275
+ if (this.stagedTofuAnchor) {
1276
+ this.stagedTofuAnchor.seenSignedUpstream = true;
1277
+ await this.commitStagedTofuAnchor();
1278
+ }
1279
+ if (await this.isCheckpointAuthenticatedByProposer(canonicalSegment.checkpoint)) this.seenSignedUpstream = true;
1280
+ }
1281
+ this.pruneController?.markColdHeightConfirmed(canonicalSegment.checkpoint.height, canonicalSegment.checkpoint.segmentContentHash);
1282
+ const postReplaySeq = await this.resolver.ledger.getLatestSequence();
1283
+ const verifiedColdStateRoot = await this.resolveVerifiedWitnessStateRoot(canonicalSegment.entries, localCp, postReplaySeq === canonicalSegment.checkpoint.sequence);
1284
+ this.enqueueWitnessAttestation(canonicalSegment.checkpoint, canonicalSegment.entries, {
1285
+ expectedPrevCheckpoint: expectedPrevHash,
1286
+ prevStateRoot: localCp?.stateRoot,
1287
+ verifiedLocalStateRoot: verifiedColdStateRoot
1288
+ });
1289
+ importedCount++;
1290
+ if (importedCount >= MAX_PAGES_PER_SYNC_CYCLE) break;
1291
+ }
1292
+ if (importedCount > 0 && this.pruneController) await this.pruneController.pruneHotWindow(this.resolver.ledger);
1293
+ return importedCount;
1294
+ }
1295
+ async sealCaughtUpCheckpoints(baseUrl, latestUpstreamCp, statusSigVerified = false, isMultiPeerMode = false, mutatedLocalDbOnPeer = false) {
1296
+ if (!latestUpstreamCp || typeof this.resolver.ledger.sealVerifiedCheckpoint !== "function") return false;
1297
+ const verifiedStatusAncestors = new Map([[latestUpstreamCp.height, latestUpstreamCp]]);
1298
+ let checkpointEndpointTipVerified = null;
1299
+ let sealedAny = false;
1300
+ while (!this.halted && !this.stopped) {
1301
+ const [localCp, localSeq] = await Promise.all([this.resolver.ledger.getCheckpoint(), this.resolver.ledger.getLatestSequence()]);
1302
+ const nextHeight = (localCp?.height ?? 0) + 1;
1303
+ if (nextHeight > latestUpstreamCp.height) break;
1304
+ let targetCp = null;
1305
+ let targetCpChainBound = false;
1306
+ let linkedToStatusChain = false;
1307
+ let parentMatchesLocalForTarget = false;
1308
+ const importOpts = this.buildSegmentImportOptions();
1309
+ if (nextHeight === latestUpstreamCp.height) {
1310
+ targetCp = latestUpstreamCp;
1311
+ targetCpChainBound = statusSigVerified;
1312
+ linkedToStatusChain = true;
1313
+ } else if (verifiedStatusAncestors.has(nextHeight)) {
1314
+ targetCp = verifiedStatusAncestors.get(nextHeight);
1315
+ targetCpChainBound = statusSigVerified;
1316
+ linkedToStatusChain = true;
1317
+ } else {
1318
+ const cpRes = await this.fetchAllowlistedJson(baseUrl, `/api/ledger/checkpoint?height=${nextHeight}`, STATUS_MAX_RESPONSE_BYTES).catch(() => null);
1319
+ if (cpRes && cpRes.status === 200 && cpRes.body?.height === nextHeight) {
1320
+ const candidateCp = cpRes.body;
1321
+ const candidateHashValid = typeof candidateCp.hash === "string" && normalizeHexDigest(computeCheckpointHash(candidateCp)) === normalizeHexDigest(candidateCp.hash);
1322
+ const parentMatchesLocal = candidateHashValid && localCp !== null && typeof candidateCp.prevCheckpoint === "string" && normalizeHexDigest(candidateCp.prevCheckpoint) === normalizeHexDigest(localCp.hash);
1323
+ const gap = latestUpstreamCp.height - nextHeight;
1324
+ let chainVerified = false;
1325
+ const walked = new Map([[latestUpstreamCp.height, latestUpstreamCp]]);
1326
+ if (candidateHashValid && gap > 0 && gap <= MAX_STATUS_CHECKPOINT_CHAIN_WALK && typeof latestUpstreamCp.hash === "string" && normalizeHexDigest(computeCheckpointHash(latestUpstreamCp)) === normalizeHexDigest(latestUpstreamCp.hash)) {
1327
+ chainVerified = true;
1328
+ let cursorCp = latestUpstreamCp;
1329
+ for (let h = latestUpstreamCp.height - 1; h >= nextHeight; h--) {
1330
+ const expectedHash = cursorCp.prevCheckpoint;
1331
+ if (typeof expectedHash !== "string" || !expectedHash) {
1332
+ chainVerified = false;
1333
+ break;
1334
+ }
1335
+ const stepCp = h === nextHeight ? candidateCp : verifiedStatusAncestors.get(h) ?? await this.fetchAllowlistedJson(baseUrl, `/api/ledger/checkpoint?height=${h}`, STATUS_MAX_RESPONSE_BYTES).then((r) => r.status === 200 && r.body?.height === h ? r.body : null).catch(() => null);
1336
+ if (!stepCp || typeof stepCp.hash !== "string" || normalizeHexDigest(stepCp.hash) !== normalizeHexDigest(expectedHash) || normalizeHexDigest(computeCheckpointHash(stepCp)) !== normalizeHexDigest(expectedHash)) {
1337
+ chainVerified = false;
1338
+ break;
1339
+ }
1340
+ walked.set(h, stepCp);
1341
+ cursorCp = stepCp;
1342
+ }
1343
+ }
1344
+ if (chainVerified) {
1345
+ for (const [h, cp] of walked) verifiedStatusAncestors.set(h, cp);
1346
+ targetCp = candidateCp;
1347
+ targetCpChainBound = statusSigVerified;
1348
+ linkedToStatusChain = true;
1349
+ parentMatchesLocalForTarget = parentMatchesLocal;
1350
+ } else if (gap > MAX_STATUS_CHECKPOINT_CHAIN_WALK && candidateHashValid && (localCp === null || parentMatchesLocal)) {
1351
+ if (checkpointEndpointTipVerified === null) {
1352
+ const tipRes = await this.fetchAllowlistedJson(baseUrl, `/api/ledger/checkpoint?height=${latestUpstreamCp.height}`, STATUS_MAX_RESPONSE_BYTES).catch(() => null);
1353
+ checkpointEndpointTipVerified = Boolean(tipRes && tipRes.status === 200 && tipRes.body?.height === latestUpstreamCp.height && typeof tipRes.body.hash === "string" && typeof latestUpstreamCp.hash === "string" && normalizeHexDigest(tipRes.body.hash) === normalizeHexDigest(latestUpstreamCp.hash) && normalizeHexDigest(computeCheckpointHash(tipRes.body)) === normalizeHexDigest(latestUpstreamCp.hash));
1354
+ }
1355
+ if (checkpointEndpointTipVerified) {
1356
+ targetCp = candidateCp;
1357
+ targetCpChainBound = false;
1358
+ linkedToStatusChain = true;
1359
+ parentMatchesLocalForTarget = parentMatchesLocal;
1360
+ }
1361
+ }
1362
+ }
1363
+ if (!targetCp && this.coldArchiveStore) {
1364
+ const coldVerifyAnchor = importOpts.allowUnauthenticated ? void 0 : importOpts.proposerPublicKey ?? importOpts.verifier;
1365
+ const seg = await this.coldArchiveStore.getSegment(this.chainId, nextHeight, {
1366
+ expectedChainId: this.chainId,
1367
+ expectedHeight: nextHeight,
1368
+ expectedProposer: importOpts.expectedProposer,
1369
+ publicKeyOrVerifier: coldVerifyAnchor,
1370
+ requireSignature: !importOpts.allowUnauthenticated,
1371
+ allowUnauthenticated: importOpts.allowUnauthenticated
1372
+ }).catch(() => null);
1373
+ if (seg && seg.chainId === this.chainId) {
1374
+ targetCp = seg.checkpoint;
1375
+ const coldAuth = await this.isColdSegmentAuthenticatedByProposer(seg);
1376
+ if (coldAuth) this.seenSignedUpstream = true;
1377
+ targetCpChainBound = coldAuth;
1378
+ linkedToStatusChain = true;
1379
+ }
1380
+ }
1381
+ if (!targetCp && cpRes && cpRes.status === 200) throw new CustomError("UPSTREAM_BAD_RESPONSE", `Upstream checkpoint #${nextHeight} failed hash-chain verification against status latestCheckpoint #${latestUpstreamCp.height}`);
1382
+ }
1383
+ if (!targetCp || localSeq < targetCp.sequence) break;
1384
+ if (localCp === null && (targetCp.prevSequence !== 0 || targetCp.prevCheckpoint !== null && targetCp.prevCheckpoint !== void 0)) throw new CustomError("UPSTREAM_BAD_RESPONSE", `Invalid height-1 checkpoint parent metadata (prevSequence=${String(targetCp.prevSequence)}, prevCheckpoint=${String(targetCp.prevCheckpoint)})`);
1385
+ if (targetCp.txCount !== targetCp.sequence - targetCp.prevSequence || targetCp.txCount <= 0) throw new CustomError("UPSTREAM_BAD_RESPONSE", `Invalid checkpoint #${targetCp.height} txCount (${String(targetCp.txCount)}) for sequence range (${String(targetCp.prevSequence)}..${String(targetCp.sequence)})`);
1386
+ const localHasSignedCheckpoint = Boolean(localCp?.signature && localCp.signature !== "unsigned");
1387
+ const isSignedStatusAncestor = statusSigVerified && verifiedStatusAncestors.has(nextHeight);
1388
+ const effectiveImportOpts = this.allowUnauthenticated && !this.hotstuffClusterConfig && !localHasSignedCheckpoint && isSignedStatusAncestor && (!targetCp.signature || targetCp.signature === "unsigned") ? {
1389
+ ...importOpts,
1390
+ allowUnauthenticated: true
1391
+ } : importOpts;
1392
+ const segmentEntries = targetCp.sequence > targetCp.prevSequence && (Boolean(this.witnessWallet) || !targetCpChainBound && Boolean(targetCp.segmentCommitmentSignature)) ? await this.resolver.ledger.getRange(targetCp.prevSequence + 1, targetCp.sequence) : [];
1393
+ if (!targetCpChainBound && targetCp.segmentCommitmentSignature && targetCp.segmentCommitmentSignature !== "unsigned") {
1394
+ if (await this.isColdSegmentAuthenticatedByProposer({
1395
+ chainId: this.chainId,
1396
+ checkpoint: targetCp,
1397
+ entries: segmentEntries
1398
+ })) {
1399
+ targetCpChainBound = true;
1400
+ this.seenSignedUpstream = true;
1401
+ }
1402
+ }
1403
+ try {
1404
+ await this.resolver.ledger.sealVerifiedCheckpoint(targetCp, {
1405
+ ...effectiveImportOpts,
1406
+ chainBoundAuthenticated: targetCpChainBound
1407
+ });
1408
+ } catch (sealErr) {
1409
+ if (isTransientSqliteLockError(sealErr)) {
1410
+ sealErr.authenticatedLocalFailure = false;
1411
+ throw sealErr;
1412
+ }
1413
+ if (isLocalTrustedStorageHashError(sealErr) || isLocalLedgerStorageCorruptionError(sealErr)) {
1414
+ sealErr.localDivergenceFailure = true;
1415
+ sealErr.authenticatedLocalFailure = false;
1416
+ throw sealErr;
1417
+ }
1418
+ if (!this.hasCommittedTrustAnchor()) sealErr.authenticatedLocalFailure = false;
1419
+ const hadProposerAuthenticatedLocalFailure = sealErr?.authenticatedLocalFailure === true;
1420
+ if (!effectiveImportOpts.allowUnauthenticated && !targetCpChainBound) {
1421
+ sealErr.authenticatedLocalFailure = false;
1422
+ if (hadProposerAuthenticatedLocalFailure && parentMatchesLocalForTarget && statusSigVerified && checkpointEndpointTipVerified === true && isLocalCheckpointSealDivergenceError(sealErr)) sealErr.localDivergenceFailure = true;
1423
+ }
1424
+ const isCryptographicallyAuthenticatedSeal = !effectiveImportOpts.allowUnauthenticated && this.hasCommittedTrustAnchor();
1425
+ if ((effectiveImportOpts.allowUnauthenticated || isSignedStatusAncestor || !isCryptographicallyAuthenticatedSeal) && linkedToStatusChain && isLocalCheckpointSealDivergenceError(sealErr)) if (isMultiPeerMode && !isCryptographicallyAuthenticatedSeal && !mutatedLocalDbOnPeer) sealErr.unauthenticatedPeerDivergence = true;
1426
+ else sealErr.localDivergenceFailure = true;
1427
+ if (this.witnessWallet && targetCpChainBound && sealErr?.authenticatedLocalFailure === true) {
1428
+ const fraudLocalRoot = await this.resolveLocalFraudAlertStateRoot(localCp);
1429
+ await this.dispatchWitnessAttestation(targetCp, segmentEntries, {
1430
+ expectedPrevCheckpoint: localCp?.hash ?? null,
1431
+ prevStateRoot: localCp?.stateRoot,
1432
+ verifiedLocalStateRoot: fraudLocalRoot,
1433
+ forcedFailureReason: sealErr instanceof Error ? sealErr.message : String(sealErr),
1434
+ allowDuplicateHeight: true
1435
+ }).catch(() => void 0);
1436
+ }
1437
+ throw sealErr;
1438
+ }
1439
+ if (!this.hotstuffClusterConfig && !this.trustedProposer && targetCp.proposer) this.trustedProposer = targetCp.proposer;
1440
+ if (targetCp.signature && targetCp.signature !== "unsigned") {
1441
+ if (this.stagedTofuAnchor) {
1442
+ this.stagedTofuAnchor.seenSignedUpstream = true;
1443
+ await this.commitStagedTofuAnchor();
1444
+ }
1445
+ if (await this.isCheckpointAuthenticatedByProposer(targetCp)) this.seenSignedUpstream = true;
1446
+ }
1447
+ this.leaderRouter?.advanceMinVerifiedCheckpointHeight?.(targetCp.height);
1448
+ const verifiedHotStateRoot = await this.resolveVerifiedWitnessStateRoot(segmentEntries, localCp, localSeq === targetCp.sequence);
1449
+ this.enqueueWitnessAttestation(targetCp, segmentEntries, {
1450
+ expectedPrevCheckpoint: localCp?.hash ?? null,
1451
+ prevStateRoot: localCp?.stateRoot,
1452
+ verifiedLocalStateRoot: verifiedHotStateRoot
1453
+ });
1454
+ sealedAny = true;
1455
+ }
1456
+ if (sealedAny && this.pruneController) await this.pruneController.pruneHotWindow(this.resolver.ledger);
1457
+ return sealedAny;
1458
+ }
1459
+ async tryEmitHotTailReplayFraudAlert(baseUrl, latestUpstreamCp, statusSigVerified, fetchedEntries, failingSeq, replayErr) {
1460
+ if (!this.witnessWallet || !latestUpstreamCp) return;
1461
+ let localCp = null;
1462
+ try {
1463
+ localCp = await this.resolver.ledger.getCheckpoint();
1464
+ } catch (err) {
1465
+ this.rethrowIfLocalStorageOrLockError(err);
1466
+ return;
1467
+ }
1468
+ const nextHeight = (localCp?.height ?? 0) + 1;
1469
+ if (latestUpstreamCp.height < nextHeight) return;
1470
+ let targetCp = null;
1471
+ let chainBound = false;
1472
+ if (latestUpstreamCp.height === nextHeight) {
1473
+ targetCp = latestUpstreamCp;
1474
+ chainBound = statusSigVerified || localCp !== null && typeof targetCp.prevCheckpoint === "string" && targetCp.prevCheckpoint.replace(/^0x/i, "").toLowerCase() === localCp.hash.replace(/^0x/i, "").toLowerCase();
1475
+ } else {
1476
+ const cpRes = await this.fetchAllowlistedJson(baseUrl, `/api/ledger/checkpoint?height=${nextHeight}`, STATUS_MAX_RESPONSE_BYTES).catch(() => null);
1477
+ if (cpRes && cpRes.status === 200 && cpRes.body?.height === nextHeight) {
1478
+ targetCp = cpRes.body;
1479
+ chainBound = localCp !== null && typeof targetCp.prevCheckpoint === "string" && targetCp.prevCheckpoint.replace(/^0x/i, "").toLowerCase() === localCp.hash.replace(/^0x/i, "").toLowerCase();
1480
+ }
1481
+ }
1482
+ if (!targetCp || !chainBound || targetCp.prevSequence !== (localCp?.sequence ?? 0) || failingSeq <= targetCp.prevSequence || failingSeq > targetCp.sequence) return;
1483
+ if (!await this.isCheckpointAuthenticatedByProposer(targetCp)) return;
1484
+ const bySeq = /* @__PURE__ */ new Map();
1485
+ const localPersisted = await this.resolver.ledger.getRange(targetCp.prevSequence + 1, targetCp.sequence).catch(() => []);
1486
+ for (const item of localPersisted) bySeq.set(item.sequence, item);
1487
+ for (const item of fetchedEntries) if (item.sequence > targetCp.prevSequence && item.sequence <= targetCp.sequence && !bySeq.has(item.sequence)) bySeq.set(item.sequence, item);
1488
+ const segmentEntries = Array.from(bySeq.values()).sort((a, b) => a.sequence - b.sequence);
1489
+ const fraudLocalRoot = await this.resolveLocalFraudAlertStateRoot(localCp);
1490
+ await this.dispatchWitnessAttestation(targetCp, segmentEntries, {
1491
+ expectedPrevCheckpoint: localCp?.hash ?? null,
1492
+ prevStateRoot: localCp?.stateRoot,
1493
+ verifiedLocalStateRoot: fraudLocalRoot,
1494
+ forcedFailureReason: replayErr instanceof Error ? replayErr.message : String(replayErr),
1495
+ allowDuplicateHeight: true
1496
+ });
1497
+ }
1498
+ parseStrictEntryHashV2From(raw) {
1499
+ if (raw === void 0 || raw === null) return;
1500
+ if (raw === "infinity") return "infinity";
1501
+ if (typeof raw !== "string" || !/^[1-9]\d*$/.test(raw)) throw new CustomError("INVALID_LEDGER_ENTRY", `Invalid entryHashV2From value: ${String(raw)}`);
1502
+ const parsed = Number(raw);
1503
+ if (!Number.isSafeInteger(parsed) || parsed < 1) throw new CustomError("INVALID_LEDGER_ENTRY", `Unsafe non-integer entryHashV2From value: ${raw}`);
1504
+ return parsed;
1505
+ }
1506
+ async verifyHotTailEntriesBatchBeforeReplay(requestedFrom, entriesBody, upstreamStatus, parsedV2From) {
1507
+ const entries = entriesBody.entries;
1508
+ if (entries.length === 0) return parsedV2From;
1509
+ if (entriesBody.from !== void 0 && entriesBody.from !== requestedFrom) throw new CustomError("INVALID_LEDGER_ENTRY", `Hot-tail batch from mismatch: requested ${requestedFrom}, response has ${entriesBody.from}`);
1510
+ const batchParsedV2From = this.parseStrictEntryHashV2From(entriesBody.entryHashV2From);
1511
+ if (batchParsedV2From !== void 0 && parsedV2From !== void 0 && batchParsedV2From !== parsedV2From) throw new CustomError("INVALID_LEDGER_ENTRY", `Hot-tail entryHashV2From mismatch between status (${String(parsedV2From)}) and entries (${String(batchParsedV2From)})`);
1512
+ const importOpts = this.buildSegmentImportOptions();
1513
+ const trustAnchor = resolveTrustAnchor({
1514
+ proposerPublicKey: importOpts.proposerPublicKey,
1515
+ verifier: importOpts.verifier,
1516
+ hotstuffClusterConfig: importOpts.hotstuffClusterConfig
1517
+ });
1518
+ if (importOpts.allowUnauthenticated && !trustAnchor) {
1519
+ for (let i = 0; i < entries.length; i++) this.replayer.validateWireEntry(entries[i]);
1520
+ return batchParsedV2From ?? parsedV2From;
1521
+ }
1522
+ if (!trustAnchor) {
1523
+ if (this.allowUnauthenticated) throw new CustomError("HOT_TAIL_SIGNATURE_MISSING", "Signed upstream history requires a verified proposer statusSignature and proposerPublicKey before replaying hot-tail entries");
1524
+ throw new CustomError("TRUST_ANCHOR_REQUIRED", "Cannot verify hot-tail ledger entries without a trusted proposerPublicKey or verifier");
1525
+ }
1526
+ const candidateV2From = batchParsedV2From ?? parsedV2From;
1527
+ const v2Cutoff = candidateV2From === "infinity" ? Number.POSITIVE_INFINITY : typeof candidateV2From === "number" ? candidateV2From : this.resolver.ledger.getEntryHashV2From?.() ?? 1;
1528
+ const entryHashes = [];
1529
+ const entryCommitments = [];
1530
+ for (let i = 0; i < entries.length; i++) {
1531
+ const entry = entries[i];
1532
+ const expectedSeq = requestedFrom + i;
1533
+ if (!entry || entry.sequence !== expectedSeq) throw new CustomError("INVALID_LEDGER_ENTRY", `Hot-tail batch sequence discontinuity at index ${i}: expected ${expectedSeq}, got ${entry?.sequence}`);
1534
+ if (entry.chainId !== this.chainId) throw new CustomError("CHAIN_ID_MISMATCH", `Hot-tail entry chainId (${entry.chainId}) !== local chainId (${this.chainId})`);
1535
+ if (entry.finalized !== true) throw new CustomError("UNFINALIZED_LEDGER_ENTRY", `Hot-tail entry seq=${entry.sequence} is not finalized`);
1536
+ if (!Number.isSafeInteger(entry.timestamp) || entry.timestamp < 0 || entry.timestamp > MAX_SAFE_EPOCH_MS) throw new CustomError("INVALID_LEDGER_ENTRY", `Hot-tail entry seq=${entry.sequence} has invalid timestamp: ${String(entry.timestamp)}`);
1537
+ if (typeof entry.txRaw !== "string" || !entry.txRaw || entry.txRaw !== entry.txRaw.trim()) throw new CustomError("INVALID_LEDGER_ENTRY", `Hot-tail entry seq=${entry.sequence} has missing or non-canonical txRaw`);
1538
+ this.replayer.validateWireEntry(entry);
1539
+ const expectedHash = computeEntryHash(entry.sequence, entry.txRaw, entry.stateCommitHash ?? "", entry.sequence >= v2Cutoff ? 2 : 1);
1540
+ if (entry.entryHash !== expectedHash) throw new CustomError("LEDGER_DIVERGENCE", `Hot-tail entryHash mismatch at seq=${entry.sequence}: expected ${expectedHash}, got ${entry.entryHash}`);
1541
+ entryHashes.push(entry.entryHash);
1542
+ entryCommitments.push(computeHotTailEntryCommitment(entry));
1543
+ }
1544
+ if (entriesBody.batchSignature && !this.hotstuffClusterConfig) {
1545
+ const effectiveTrustedProposer$1 = this.getEffectiveTrustedProposer();
1546
+ const proposer = entriesBody.proposer || upstreamStatus.proposer || effectiveTrustedProposer$1 || "";
1547
+ if (this.hotstuffClusterConfig && !this.isAllowedHotStuffValidator(proposer)) throw new CustomError("HOT_TAIL_SIGNATURE_INVALID", `Hot-tail batch signer ${proposer || "missing"} is not in HOTSTUFF_VALIDATORS`);
1548
+ if (!await verifyHotTailBatchSignature({
1549
+ chainId: this.chainId,
1550
+ from: requestedFrom,
1551
+ count: entries.length,
1552
+ latestSequence: entriesBody.latestSequence,
1553
+ entryCommitments,
1554
+ proposer,
1555
+ ...entriesBody.entryHashV2From !== void 0 ? { entryHashV2From: entriesBody.entryHashV2From } : {}
1556
+ }, entriesBody.batchSignature, trustAnchor, this.hotstuffClusterConfig ? proposer : effectiveTrustedProposer$1 || proposer || void 0)) throw new CustomError("HOT_TAIL_SIGNATURE_INVALID", "Invalid proposer batchSignature on /api/ledger/entries");
1557
+ this.markSeenSignedUpstream();
1558
+ if (!this.stagedTofuAnchor && !this.hotstuffClusterConfig) {
1559
+ const anchorProposer = effectiveTrustedProposer$1 || proposer;
1560
+ if (anchorProposer) await this.persistTrustAnchorSafe({
1561
+ proposer: anchorProposer,
1562
+ proposerPublicKey: this.trustedProposerPublicKey ? String(this.trustedProposerPublicKey) : "",
1563
+ signatureRatchetLocked: true
1564
+ });
1565
+ }
1566
+ return batchParsedV2From;
1567
+ }
1568
+ const cp = upstreamStatus.latestCheckpoint;
1569
+ const effectiveTrustedProposer = this.getEffectiveTrustedProposer();
1570
+ if (cp?.segmentCommitmentSignature && cp.segmentCommitmentSignature !== "unsigned" && this.isAllowedHotStuffValidator(cp.proposer) && entries[0].sequence === cp.prevSequence + 1 && entries[entries.length - 1].sequence === cp.sequence && entries.length === cp.txCount && computeCheckpointHash(cp) === cp.hash && await verifyCheckpointSignature(cp, trustAnchor, this.hotstuffClusterConfig ? cp.proposer : effectiveTrustedProposer || cp.proposer) && (!this.hotstuffClusterConfig || verifyCheckpointQuorumCertificate(cp, this.hotstuffClusterConfig).ok)) {
1571
+ const segContentHash = computeSegmentContentHash({
1572
+ chainId: this.chainId,
1573
+ checkpoint: cp,
1574
+ entries
1575
+ });
1576
+ if ((cp.segmentContentHash === void 0 || cp.segmentContentHash === segContentHash) && await verifySegmentCommitmentSignature(cp, segContentHash, trustAnchor, this.hotstuffClusterConfig ? cp.proposer : effectiveTrustedProposer || cp.proposer)) {
1577
+ const tree = new IncrementalMerkleTree();
1578
+ for (const h of entryHashes) tree.append(h);
1579
+ if (tree.getHexRoot() === cp.txRoot) {
1580
+ this.markSeenSignedUpstream();
1581
+ if (!this.stagedTofuAnchor && !this.hotstuffClusterConfig) {
1582
+ const anchorProposer = effectiveTrustedProposer || cp.proposer;
1583
+ if (anchorProposer) await this.persistTrustAnchorSafe({
1584
+ proposer: anchorProposer,
1585
+ proposerPublicKey: this.trustedProposerPublicKey ? String(this.trustedProposerPublicKey) : "",
1586
+ signatureRatchetLocked: true
1587
+ });
1588
+ }
1589
+ return;
1590
+ }
1591
+ }
1592
+ }
1593
+ if (importOpts.allowUnauthenticated && !entriesBody.batchSignature && !this.hotstuffClusterConfig) return batchParsedV2From ?? parsedV2From;
1594
+ throw new CustomError("HOT_TAIL_SIGNATURE_MISSING", "Hot-tail /api/ledger/entries response is missing a valid proposer batchSignature");
1595
+ }
1596
+ /**
1597
+ * In multi-peer unauthenticated / TOFU buffering mode (`bufferTailBeforeCommit`), pre-verify all
1598
+ * upstream checkpoints up to `bufferedTipSeq` against `(local entries <= localSeq) + allBufferedEntries`
1599
+ * BEFORE mutating `statedb` or `ledger` so a rogue peer serving valid entries with a forged checkpoint
1600
+ * `stateRoot`/`txRoot` triggers clean peer failover instead of poisoning local DB (#1856).
1601
+ */
1602
+ async preVerifyBufferedCheckpointsBeforeCommit(baseUrl, latestUpstreamCp, upstreamLatestSequence, statusSigVerified, preTailLocalCp, localSeq, allBufferedEntries) {
1603
+ if (!latestUpstreamCp || allBufferedEntries.length === 0 || typeof this.resolver.ledger.sealVerifiedCheckpoint !== "function") return;
1604
+ const markUnauthenticatedPeerError = (err) => {
1605
+ this.rethrowIfLocalStorageOrLockError(err);
1606
+ if (!this.hasCommittedTrustAnchor() || this.buildSegmentImportOptions().allowUnauthenticated) {
1607
+ err.unauthenticatedPeerDivergence = true;
1608
+ err.authenticatedLocalFailure = false;
1609
+ }
1610
+ throw err;
1611
+ };
1612
+ if (!Number.isSafeInteger(latestUpstreamCp.sequence) || upstreamLatestSequence < latestUpstreamCp.sequence) return markUnauthenticatedPeerError(new CustomError("UPSTREAM_BAD_RESPONSE", `Upstream status latestSequence (${upstreamLatestSequence}) < latestCheckpoint.sequence (${String(latestUpstreamCp.sequence)})`));
1613
+ const bufferedTipSeq = allBufferedEntries[allBufferedEntries.length - 1].sequence;
1614
+ const bufferedBySeq = /* @__PURE__ */ new Map();
1615
+ for (const item of allBufferedEntries) bufferedBySeq.set(item.sequence, item);
1616
+ const verifiedStatusAncestors = new Map([[latestUpstreamCp.height, latestUpstreamCp]]);
1617
+ let checkpointEndpointTipVerified = null;
1618
+ let cursorCp = preTailLocalCp;
1619
+ while (!this.halted && !this.stopped) {
1620
+ const nextHeight = (cursorCp?.height ?? 0) + 1;
1621
+ if (nextHeight > latestUpstreamCp.height) break;
1622
+ let targetCp = null;
1623
+ const importOpts = this.buildSegmentImportOptions();
1624
+ if (nextHeight === latestUpstreamCp.height) targetCp = latestUpstreamCp;
1625
+ else if (verifiedStatusAncestors.has(nextHeight)) targetCp = verifiedStatusAncestors.get(nextHeight);
1626
+ else {
1627
+ const cpRes = await this.fetchAllowlistedJson(baseUrl, `/api/ledger/checkpoint?height=${nextHeight}`, STATUS_MAX_RESPONSE_BYTES).catch(() => null);
1628
+ if (cpRes && cpRes.status === 200 && cpRes.body?.height === nextHeight) {
1629
+ const candidateCp = cpRes.body;
1630
+ const candidateHashValid = typeof candidateCp.hash === "string" && normalizeHexDigest(computeCheckpointHash(candidateCp)) === normalizeHexDigest(candidateCp.hash);
1631
+ const parentMatchesCursor = candidateHashValid && cursorCp !== null && typeof candidateCp.prevCheckpoint === "string" && normalizeHexDigest(candidateCp.prevCheckpoint) === normalizeHexDigest(cursorCp.hash);
1632
+ const gap = latestUpstreamCp.height - nextHeight;
1633
+ let chainVerified = false;
1634
+ const walked = new Map([[latestUpstreamCp.height, latestUpstreamCp]]);
1635
+ if (candidateHashValid && gap > 0 && gap <= MAX_STATUS_CHECKPOINT_CHAIN_WALK && typeof latestUpstreamCp.hash === "string" && normalizeHexDigest(computeCheckpointHash(latestUpstreamCp)) === normalizeHexDigest(latestUpstreamCp.hash)) {
1636
+ chainVerified = true;
1637
+ let walkCursor = latestUpstreamCp;
1638
+ for (let h = latestUpstreamCp.height - 1; h >= nextHeight; h--) {
1639
+ const expectedHash = walkCursor.prevCheckpoint;
1640
+ if (typeof expectedHash !== "string" || !expectedHash) {
1641
+ chainVerified = false;
1642
+ break;
1643
+ }
1644
+ const stepCp = h === nextHeight ? candidateCp : verifiedStatusAncestors.get(h) ?? await this.fetchAllowlistedJson(baseUrl, `/api/ledger/checkpoint?height=${h}`, STATUS_MAX_RESPONSE_BYTES).then((r) => r.status === 200 && r.body?.height === h ? r.body : null).catch(() => null);
1645
+ if (!stepCp || typeof stepCp.hash !== "string" || normalizeHexDigest(stepCp.hash) !== normalizeHexDigest(expectedHash) || normalizeHexDigest(computeCheckpointHash(stepCp)) !== normalizeHexDigest(expectedHash)) {
1646
+ chainVerified = false;
1647
+ break;
1648
+ }
1649
+ walked.set(h, stepCp);
1650
+ walkCursor = stepCp;
1651
+ }
1652
+ }
1653
+ if (chainVerified) {
1654
+ for (const [h, cp] of walked) verifiedStatusAncestors.set(h, cp);
1655
+ targetCp = candidateCp;
1656
+ } else if (gap > MAX_STATUS_CHECKPOINT_CHAIN_WALK && candidateHashValid && (cursorCp === null || parentMatchesCursor)) {
1657
+ if (checkpointEndpointTipVerified === null) {
1658
+ const tipRes = await this.fetchAllowlistedJson(baseUrl, `/api/ledger/checkpoint?height=${latestUpstreamCp.height}`, STATUS_MAX_RESPONSE_BYTES).catch(() => null);
1659
+ checkpointEndpointTipVerified = Boolean(tipRes && tipRes.status === 200 && tipRes.body?.height === latestUpstreamCp.height && typeof tipRes.body.hash === "string" && typeof latestUpstreamCp.hash === "string" && normalizeHexDigest(tipRes.body.hash) === normalizeHexDigest(latestUpstreamCp.hash) && normalizeHexDigest(computeCheckpointHash(tipRes.body)) === normalizeHexDigest(latestUpstreamCp.hash));
1660
+ }
1661
+ if (checkpointEndpointTipVerified) targetCp = candidateCp;
1662
+ }
1663
+ }
1664
+ if (!targetCp && this.coldArchiveStore) {
1665
+ const coldVerifyAnchor = importOpts.allowUnauthenticated ? void 0 : importOpts.proposerPublicKey ?? importOpts.verifier;
1666
+ const seg = await this.coldArchiveStore.getSegment(this.chainId, nextHeight, {
1667
+ expectedChainId: this.chainId,
1668
+ expectedHeight: nextHeight,
1669
+ expectedProposer: importOpts.expectedProposer,
1670
+ publicKeyOrVerifier: coldVerifyAnchor,
1671
+ requireSignature: !importOpts.allowUnauthenticated,
1672
+ allowUnauthenticated: importOpts.allowUnauthenticated
1673
+ }).catch(() => null);
1674
+ if (seg && seg.chainId === this.chainId) targetCp = seg.checkpoint;
1675
+ }
1676
+ if (!targetCp) return markUnauthenticatedPeerError(new CustomError(cpRes && cpRes.status === 200 ? "UPSTREAM_BAD_RESPONSE" : "UPSTREAM_UNAVAILABLE", `Upstream checkpoint #${nextHeight} unavailable or failed hash-chain verification before buffered commit`));
1677
+ }
1678
+ if (typeof targetCp.timestamp !== "number" || !Number.isSafeInteger(targetCp.timestamp) || targetCp.timestamp < 0 || typeof targetCp.hash !== "string" || normalizeHexDigest(computeCheckpointHash(targetCp)) !== normalizeHexDigest(targetCp.hash)) return markUnauthenticatedPeerError(new CustomError("INVALID_CHECKPOINT_HASH", `Buffered pre-commit checkpoint #${nextHeight} failed hash check`));
1679
+ const expectedPrevSeq = cursorCp?.sequence ?? 0;
1680
+ const expectedPrevHash = cursorCp?.hash ?? null;
1681
+ const prevHashValid = expectedPrevHash === null ? targetCp.prevCheckpoint === null || targetCp.prevCheckpoint === void 0 : typeof targetCp.prevCheckpoint === "string" && normalizeHexDigest(targetCp.prevCheckpoint) === normalizeHexDigest(expectedPrevHash);
1682
+ const expectedCount = targetCp.sequence - targetCp.prevSequence;
1683
+ if (targetCp.prevSequence !== expectedPrevSeq || !prevHashValid || !Number.isSafeInteger(expectedCount) || expectedCount <= 0 || targetCp.txCount !== expectedCount) return markUnauthenticatedPeerError(new CustomError("UPSTREAM_BAD_RESPONSE", `Buffered pre-commit checkpoint #${nextHeight} parent/range mismatch`));
1684
+ const cursorHasSignedCheckpoint = Boolean(cursorCp?.signature && cursorCp.signature !== "unsigned" && this.getEffectiveSeenSignedUpstream());
1685
+ const isSignedStatusAncestor = statusSigVerified && verifiedStatusAncestors.has(nextHeight);
1686
+ const effectiveImportOpts = this.allowUnauthenticated && !this.hotstuffClusterConfig && !cursorHasSignedCheckpoint && isSignedStatusAncestor && (!targetCp.signature || targetCp.signature === "unsigned") ? {
1687
+ ...importOpts,
1688
+ allowUnauthenticated: true
1689
+ } : importOpts;
1690
+ if (effectiveImportOpts.expectedProposer && normalizeDidCompare(targetCp.proposer) !== normalizeDidCompare(effectiveImportOpts.expectedProposer)) return markUnauthenticatedPeerError(new CustomError("INVALID_CHECKPOINT_SIGNATURE", `Buffered pre-commit checkpoint #${nextHeight} proposer mismatch`));
1691
+ const trustAnchor = resolveTrustAnchor({
1692
+ proposerPublicKey: effectiveImportOpts.proposerPublicKey,
1693
+ verifier: effectiveImportOpts.verifier,
1694
+ hotstuffClusterConfig: effectiveImportOpts.hotstuffClusterConfig
1695
+ });
1696
+ if (!effectiveImportOpts.allowUnauthenticated || trustAnchor) {
1697
+ if (!targetCp.signature || targetCp.signature === "unsigned") {
1698
+ if (!effectiveImportOpts.allowUnauthenticated) return markUnauthenticatedPeerError(new CustomError("INVALID_CHECKPOINT_SIGNATURE", `Buffered pre-commit checkpoint #${nextHeight} unsigned`));
1699
+ } else if (trustAnchor) {
1700
+ if (!await verifyCheckpointSignature(targetCp, trustAnchor, effectiveImportOpts.expectedProposer)) return markUnauthenticatedPeerError(new CustomError("INVALID_CHECKPOINT_SIGNATURE", `Buffered pre-commit checkpoint #${nextHeight} invalid signature`));
1701
+ }
1702
+ if (!(Boolean(targetCp.segmentCommitmentSignature) && targetCp.segmentCommitmentSignature !== "unsigned") || !targetCp.segmentContentHash) {
1703
+ if (!effectiveImportOpts.allowUnauthenticated) return markUnauthenticatedPeerError(new CustomError("INVALID_CHECKPOINT_SIGNATURE", `Buffered pre-commit checkpoint #${nextHeight} missing segment commitment signature`));
1704
+ } else if (trustAnchor) {
1705
+ if (!await verifySegmentCommitmentSignature(targetCp, targetCp.segmentContentHash, trustAnchor, effectiveImportOpts.expectedProposer)) return markUnauthenticatedPeerError(new CustomError("INVALID_CHECKPOINT_SIGNATURE", `Buffered pre-commit checkpoint #${nextHeight} invalid segment commitment signature`));
1706
+ }
1707
+ }
1708
+ if (bufferedTipSeq < targetCp.sequence) break;
1709
+ const segEntries = [];
1710
+ if (targetCp.prevSequence + 1 <= localSeq) try {
1711
+ const localPart = await this.resolver.ledger.getRange(targetCp.prevSequence + 1, Math.min(localSeq, targetCp.sequence));
1712
+ segEntries.push(...localPart);
1713
+ } catch (err) {
1714
+ this.rethrowIfLocalStorageOrLockError(err);
1715
+ throw err;
1716
+ }
1717
+ for (let seq = Math.max(localSeq + 1, targetCp.prevSequence + 1); seq <= targetCp.sequence; seq++) {
1718
+ const bufEntry = bufferedBySeq.get(seq);
1719
+ if (bufEntry) segEntries.push(bufEntry);
1720
+ }
1721
+ if (segEntries.length !== expectedCount) return markUnauthenticatedPeerError(new CustomError("LEDGER_DIVERGENCE", `Buffered pre-commit checkpoint #${nextHeight} entry count (${segEntries.length}) !== expected (${expectedCount})`));
1722
+ const hashRun = new EntryHashRunVerifier();
1723
+ const tree = new IncrementalMerkleTree();
1724
+ for (let i = 0; i < segEntries.length; i++) {
1725
+ const entry = segEntries[i];
1726
+ const expectedSeq = targetCp.prevSequence + 1 + i;
1727
+ if (entry.sequence !== expectedSeq || entry.chainId !== this.chainId || !entry.finalized) return markUnauthenticatedPeerError(new CustomError("LEDGER_DIVERGENCE", `Buffered pre-commit checkpoint #${nextHeight} invalid entry at seq=${entry.sequence}`));
1728
+ if (!hashRun.check(entry).ok) return markUnauthenticatedPeerError(new CustomError("LEDGER_DIVERGENCE", `Buffered pre-commit checkpoint #${nextHeight} entryHash mismatch at seq=${entry.sequence}`));
1729
+ tree.append(entry.entryHash);
1730
+ }
1731
+ const computedTxRoot = tree.getHexRoot();
1732
+ if (typeof targetCp.txRoot !== "string" || normalizeHexDigest(computedTxRoot) !== normalizeHexDigest(targetCp.txRoot)) return markUnauthenticatedPeerError(new CustomError("LEDGER_DIVERGENCE", `Buffered pre-commit checkpoint #${nextHeight} txRoot mismatch: expected ${targetCp.txRoot}, got ${computedTxRoot}`));
1733
+ const expectedStateRoot = deriveSegmentStateRoot(segEntries, cursorCp?.stateRoot);
1734
+ const actualStateRoot = targetCp.stateRoot || void 0;
1735
+ if (expectedStateRoot !== actualStateRoot) return markUnauthenticatedPeerError(new CustomError("STATE_COMMIT_MISMATCH", `Buffered pre-commit checkpoint #${nextHeight} stateRoot mismatch: expected ${expectedStateRoot ?? "undefined"}, got ${actualStateRoot ?? "undefined"}`));
1736
+ if (targetCp.segmentContentHash !== void 0) {
1737
+ const computedContentHash = computeSegmentContentHash({
1738
+ chainId: this.chainId,
1739
+ checkpoint: targetCp,
1740
+ entries: segEntries
1741
+ });
1742
+ if (typeof targetCp.segmentContentHash !== "string" || normalizeHexDigest(targetCp.segmentContentHash) !== normalizeHexDigest(computedContentHash)) return markUnauthenticatedPeerError(new CustomError("LEDGER_DIVERGENCE", `Buffered pre-commit checkpoint #${nextHeight} segmentContentHash mismatch`));
1743
+ }
1744
+ cursorCp = targetCp;
1745
+ }
1746
+ }
1747
+ /**
1748
+ * HotStuff BFT Follower Sync (#1712):
1749
+ * Never replays un-QC'd hot-tail entries (`latestSequence > latestCheckpoint.sequence` or 1-of-N `batchSignature`).
1750
+ * Instead, fetches each checkpoint height `h` with a verified `2f+1` `QuorumCertificate`, collects its
1751
+ * finalized entries, runs `verifySegmentForImport` + `dryRunVerifyEntries` BEFORE mutating any local DB,
1752
+ * and commits `statedb` + `ledger` atomically per QC-certified checkpoint.
1753
+ */
1754
+ async catchUpHotStuffQcSegmentsFromHttp(targetBaseUrl, upstreamStatus, parsedV2From) {
1755
+ if (!this.hotstuffClusterConfig) return;
1756
+ const latestUpstreamCp = upstreamStatus.latestCheckpoint;
1757
+ if (!latestUpstreamCp || latestUpstreamCp.height < 1) return;
1758
+ const importOpts = this.buildSegmentImportOptions();
1759
+ let localCp = await this.resolver.ledger.getCheckpoint();
1760
+ let localHeight = localCp?.height ?? 0;
1761
+ let localSeq = await this.resolver.ledger.getLatestSequence();
1762
+ let heightsSynced = 0;
1763
+ let sealedAny = false;
1764
+ while (!this.halted && !this.stopped && localHeight < latestUpstreamCp.height) {
1765
+ if (heightsSynced >= MAX_PAGES_PER_SYNC_CYCLE) break;
1766
+ heightsSynced++;
1767
+ const nextHeight = localHeight + 1;
1768
+ let targetCp = null;
1769
+ if (nextHeight === latestUpstreamCp.height) targetCp = latestUpstreamCp;
1770
+ else {
1771
+ const cpRes = await this.fetchAllowlistedJson(targetBaseUrl, `/api/ledger/checkpoint?height=${nextHeight}`, STATUS_MAX_RESPONSE_BYTES);
1772
+ if (cpRes.status !== 200 || !cpRes.body || cpRes.body.height !== nextHeight) throw new CustomError("UPSTREAM_UNAVAILABLE", `GET /api/ledger/checkpoint?height=${nextHeight} returned HTTP ${cpRes.status}`);
1773
+ targetCp = cpRes.body;
1774
+ }
1775
+ await this.checkCheckpointEquivocationAgainstLocal(targetCp, { chainBoundAuthenticated: true });
1776
+ const qcRes = verifyCheckpointQuorumCertificate(targetCp, this.hotstuffClusterConfig);
1777
+ if (!qcRes.ok) throw new CustomError("INVALID_CHECKPOINT_QC", `Upstream checkpoint #${nextHeight} failed 2f+1 QuorumCertificate verification: ${qcRes.reason || "invalid QC"}`);
1778
+ if (targetCp.prevSequence !== localSeq || (localCp ? targetCp.prevCheckpoint !== localCp.hash : targetCp.prevCheckpoint !== null)) throw new CustomError("INVALID_CHECKPOINT_CHAIN", `Upstream checkpoint #${nextHeight} prevSequence/prevCheckpoint mismatch against local height ${localHeight}`);
1779
+ const segmentEntries = [];
1780
+ let cursor = targetCp.prevSequence + 1;
1781
+ while (cursor <= targetCp.sequence) {
1782
+ const pageLimit = Math.min(MAX_HOT_TAIL_LIMIT, targetCp.sequence - cursor + 1);
1783
+ const entriesRes = await this.fetchAllowlistedJson(targetBaseUrl, `/api/ledger/entries?from=${cursor}&limit=${pageLimit}`, ENTRIES_MAX_RESPONSE_BYTES);
1784
+ if (entriesRes.status === 410 && this.coldArchiveStore) {
1785
+ if (await this.catchUpFromColdSegments(nextHeight) > 0) {
1786
+ localCp = await this.resolver.ledger.getCheckpoint();
1787
+ localHeight = localCp?.height ?? 0;
1788
+ localSeq = await this.resolver.ledger.getLatestSequence();
1789
+ break;
1790
+ }
1791
+ }
1792
+ if (entriesRes.status !== 200 || entriesRes.body?.chainId !== this.chainId) throw new CustomError("UPSTREAM_UNAVAILABLE", `GET /api/ledger/entries?from=${cursor} failed (HTTP ${entriesRes.status})`);
1793
+ const batch = Array.isArray(entriesRes.body.entries) ? entriesRes.body.entries : [];
1794
+ if (batch.length === 0) throw new CustomError("UPSTREAM_UNAVAILABLE", `Upstream returned 0 entries at seq=${cursor}`);
1795
+ for (const item of batch) {
1796
+ if (item.sequence > targetCp.sequence) break;
1797
+ if (item.sequence !== cursor) throw new CustomError("INVALID_LEDGER_ENTRY", `Non-contiguous entry sequence at height ${nextHeight}: expected ${cursor}, got ${item.sequence}`);
1798
+ this.replayer.validateWireEntry(item);
1799
+ segmentEntries.push(item);
1800
+ cursor++;
1801
+ }
1802
+ }
1803
+ if (localHeight >= nextHeight) continue;
1804
+ if (segmentEntries.length !== targetCp.txCount) throw new CustomError("INVALID_LEDGER_ENTRY", `Checkpoint #${nextHeight} entry count (${segmentEntries.length}) !== txCount (${targetCp.txCount})`);
1805
+ const candidateSegment = {
1806
+ chainId: this.chainId,
1807
+ checkpoint: targetCp,
1808
+ entries: segmentEntries
1809
+ };
1810
+ if (typeof this.resolver.ledger.verifySegmentForImport === "function") await this.resolver.ledger.verifySegmentForImport(candidateSegment, {
1811
+ ...importOpts,
1812
+ allowAheadLocalSequence: true
1813
+ });
1814
+ else await assertValidSegment(candidateSegment, {
1815
+ expectedChainId: this.chainId,
1816
+ expectedHeight: nextHeight,
1817
+ publicKeyOrVerifier: importOpts.proposerPublicKey ?? importOpts.verifier,
1818
+ requireSignature: !importOpts.allowUnauthenticated,
1819
+ allowUnauthenticated: importOpts.allowUnauthenticated
1820
+ });
1821
+ let mutatedLocalDb = false;
1822
+ try {
1823
+ if (segmentEntries.length > 0 && typeof this.resolver.statedb.runWithinDryRunSession === "function") {
1824
+ const dryRun = await this.replayer.dryRunVerifyEntries(segmentEntries, {
1825
+ expectedPrevSequence: localSeq,
1826
+ prevStateRoot: localCp?.stateRoot ?? null,
1827
+ entryHashV2From: parsedV2From
1828
+ });
1829
+ if (String(dryRun.derivedStateRoot ?? "").replace(/^0x/i, "").toLowerCase() !== String(targetCp.stateRoot ?? "").replace(/^0x/i, "").toLowerCase()) throw new CustomError("STATE_COMMIT_MISMATCH", `Dry-run stateRoot (${dryRun.derivedStateRoot ?? "null"}) !== QC checkpoint stateRoot (${targetCp.stateRoot ?? "null"}) at height ${nextHeight}`);
1830
+ }
1831
+ this.pendingCrashWindowReconcile = true;
1832
+ try {
1833
+ await this.resolver.ledger.importSegment(candidateSegment, importOpts);
1834
+ mutatedLocalDb = true;
1835
+ } catch (importErr) {
1836
+ if (await this.resolver.ledger.getLatestSequence().catch(() => localSeq) > localSeq) mutatedLocalDb = true;
1837
+ else this.pendingCrashWindowReconcile = false;
1838
+ throw importErr;
1839
+ }
1840
+ for (const entry of segmentEntries) await this.replayer.replayEntry(entry, {
1841
+ appendToLedger: false,
1842
+ entryHashV2From: parsedV2From
1843
+ });
1844
+ this.pendingCrashWindowReconcile = false;
1845
+ } catch (replayErr) {
1846
+ if (isTransientSqliteLockError(replayErr)) {
1847
+ if (mutatedLocalDb) replayErr.mutatedLocalDbTransientLock = true;
1848
+ throw replayErr;
1849
+ }
1850
+ const errCode = replayErr?.code;
1851
+ if (isLocalTrustedStorageHashError(replayErr) || isLocalLedgerStorageCorruptionError(replayErr)) {
1852
+ replayErr.localDivergenceFailure = true;
1853
+ replayErr.authenticatedLocalFailure = false;
1854
+ throw replayErr;
1855
+ }
1856
+ if (mutatedLocalDb) replayErr.localDivergenceFailure = true;
1857
+ if (isLocalExecutionDivergenceCode(errCode) || isLocalCheckpointSealDivergenceError(replayErr)) {
1858
+ replayErr.localDivergenceFailure = true;
1859
+ if (!importOpts.allowUnauthenticated) replayErr.authenticatedLocalFailure = true;
1860
+ }
1861
+ throw replayErr;
1862
+ }
1863
+ this.leaderRouter?.advanceMinVerifiedCheckpointHeight?.(targetCp.height);
1864
+ const verifiedHotStateRoot = await this.resolveVerifiedWitnessStateRoot(segmentEntries, localCp, true);
1865
+ this.enqueueWitnessAttestation(targetCp, segmentEntries, {
1866
+ expectedPrevCheckpoint: localCp?.hash ?? null,
1867
+ prevStateRoot: localCp?.stateRoot,
1868
+ verifiedLocalStateRoot: verifiedHotStateRoot
1869
+ });
1870
+ localCp = targetCp;
1871
+ localHeight = targetCp.height;
1872
+ localSeq = targetCp.sequence;
1873
+ sealedAny = true;
1874
+ }
1875
+ if (sealedAny && this.pruneController) await this.pruneController.pruneHotWindow(this.resolver.ledger);
1876
+ }
1877
+ async getHotLedgerEntryBySequence(seq) {
1878
+ if (Object.prototype.hasOwnProperty.call(this.resolver.ledger, "getBySequence")) return this.resolver.ledger.getBySequence(seq);
1879
+ const storage = this.resolver.ledger.getStorage?.();
1880
+ if (storage && typeof storage.getEntryBySequence === "function") return storage.getEntryBySequence(seq);
1881
+ return this.resolver.ledger.getBySequence(seq);
1882
+ }
1883
+ async findLocalCheckpointAtSequence(seq) {
1884
+ if (!Number.isSafeInteger(seq) || seq < 1) return null;
1885
+ if (typeof this.resolver.ledger.getCheckpointForSequence === "function") {
1886
+ const covering = await this.resolver.ledger.getCheckpointForSequence(seq);
1887
+ if (covering) return covering.sequence === seq ? covering : null;
1888
+ }
1889
+ const latestCp = await this.resolver.ledger.getCheckpoint();
1890
+ if (!latestCp || latestCp.sequence < seq) return null;
1891
+ for (let h = latestCp.height; h >= 1; h--) {
1892
+ const cp = h === latestCp.height ? latestCp : await this.resolver.ledger.getCheckpoint(h);
1893
+ if (!cp) continue;
1894
+ if (cp.sequence === seq) return cp;
1895
+ if (cp.sequence < seq) break;
1896
+ }
1897
+ return null;
1898
+ }
1899
+ async resolveEffectiveCheckpointStateRoot(cp) {
1900
+ const direct = String(cp.stateRoot ?? "").trim().replace(/^0x/i, "").toLowerCase();
1901
+ if (direct) return direct;
1902
+ for (let h = cp.height - 1; h >= 1; h--) {
1903
+ const prior = await this.resolver.ledger.getCheckpoint(h);
1904
+ const priorRoot = String(prior?.stateRoot ?? "").trim().replace(/^0x/i, "").toLowerCase();
1905
+ if (priorRoot) return priorRoot;
1906
+ }
1907
+ return "";
1908
+ }
1909
+ async replayCrashWindowEntry(entry) {
1910
+ try {
1911
+ this.replayer.validateWireEntry(entry, { skipFutureTimestampCheck: true });
1912
+ const expectedCommit = (entry.stateCommitHash ?? "").trim();
1913
+ const v2Cutoff = typeof this.resolver.ledger.getEntryHashV2From === "function" ? this.resolver.ledger.getEntryHashV2From() : void 0;
1914
+ if (typeof v2Cutoff === "number" && !Number.isNaN(v2Cutoff)) {
1915
+ const expectedEntryHash = computeEntryHash(entry.sequence, entry.txRaw, expectedCommit, entry.sequence >= v2Cutoff ? 2 : 1);
1916
+ if (entry.entryHash !== expectedEntryHash) throw new CustomError("INVALID_LEDGER_ENTRY", `Local entry hash mismatch at seq ${entry.sequence}: expected ${expectedEntryHash}, got ${entry.entryHash}`);
1917
+ } else {
1918
+ const expectedV2 = computeEntryHash(entry.sequence, entry.txRaw, expectedCommit, 2);
1919
+ const expectedV1 = computeEntryHash(entry.sequence, entry.txRaw, expectedCommit, 1);
1920
+ if (entry.entryHash !== expectedV2 && entry.entryHash !== expectedV1) throw new CustomError("INVALID_LEDGER_ENTRY", `Local entry hash mismatch at seq ${entry.sequence}: got ${entry.entryHash}`);
1921
+ }
1922
+ await this.replayer.replayEntry(entry, { appendToLedger: false });
1923
+ } catch (err) {
1924
+ if (!isTransientSqliteLockError(err)) err.localDivergenceFailure = true;
1925
+ throw err;
1926
+ }
1927
+ }
1928
+ async reconcileTrailingOrphanRange(fromSeq, toSeq) {
1929
+ if (fromSeq > toSeq) return;
1930
+ this.pendingCrashWindowReconcile = true;
1931
+ for (let s = fromSeq; s <= toSeq; s++) {
1932
+ const orphanEntry = await this.getHotLedgerEntryBySequence(s);
1933
+ if (!orphanEntry || orphanEntry.finalized !== true) {
1934
+ const holeErr = new CustomError("LEDGER_DIVERGENCE", `Missing or unfinalized trailing orphan entry at seq=${s} during crash reconciliation (tip=${toSeq})`);
1935
+ holeErr.localDivergenceFailure = true;
1936
+ throw holeErr;
1937
+ }
1938
+ await this.replayCrashWindowEntry(orphanEntry);
1939
+ }
1940
+ }
1941
+ /**
1942
+ * Reconcile any crash window where finalized `ledger.sqlite` entries were durable ahead of `statedb.sqlite`
1943
+ * (e.g., power loss between `ledger.importSegment` and `replayer.replayEntry`) before polling upstream (#1712).
1944
+ */
1945
+ async reconcileFollowerCrashWindowIfNeeded() {
1946
+ const latestSeq = await this.resolver.ledger.getLatestSequence();
1947
+ if (latestSeq <= 0) {
1948
+ this.pendingCrashWindowReconcile = false;
1949
+ this.initialCrashReconcileCompleted = true;
1950
+ return;
1951
+ }
1952
+ const currentCommit = typeof this.resolver.statedb.getCurrentCommitHash === "function" ? await this.resolver.statedb.getCurrentCommitHash() : null;
1953
+ if (!currentCommit || currentCommit === "UNKNOWN") {
1954
+ this.pendingCrashWindowReconcile = false;
1955
+ this.initialCrashReconcileCompleted = true;
1956
+ return;
1957
+ }
1958
+ const normCurrent = currentCommit.trim().replace(/^0x/i, "").toLowerCase();
1959
+ const isGenesisState = currentCommit === "GENESIS" || !normCurrent;
1960
+ const shouldReconcileOrphans = this.pendingCrashWindowReconcile || !this.initialCrashReconcileCompleted;
1961
+ let finalizedTipSeq = latestSeq;
1962
+ let lastStateMutatingEntry = null;
1963
+ for (let seq = latestSeq; seq >= 1; seq--) {
1964
+ const e = await this.getHotLedgerEntryBySequence(seq);
1965
+ if (!e) {
1966
+ const prunedCp = await this.findLocalCheckpointAtSequence(seq);
1967
+ if (!prunedCp) {
1968
+ const holeErr = new CustomError("LEDGER_DIVERGENCE", `Follower crash reconciliation encountered missing unpruned ledger entry at seq=${seq} (finalizedTipSeq=${finalizedTipSeq})`);
1969
+ holeErr.localDivergenceFailure = true;
1970
+ throw holeErr;
1971
+ }
1972
+ const normPrunedRoot = await this.resolveEffectiveCheckpointStateRoot(prunedCp);
1973
+ if (!isGenesisState && normPrunedRoot && normPrunedRoot === normCurrent || !normPrunedRoot) {
1974
+ if (shouldReconcileOrphans && seq < finalizedTipSeq) await this.reconcileTrailingOrphanRange(seq + 1, finalizedTipSeq);
1975
+ this.pendingCrashWindowReconcile = false;
1976
+ this.initialCrashReconcileCompleted = true;
1977
+ return;
1978
+ }
1979
+ const mismatchErr = new CustomError("STATE_COMMIT_MISMATCH", `Follower crash reconciliation could not align statedb commit (${currentCommit}) with pruned checkpoint #${prunedCp.height} stateRoot (${prunedCp.stateRoot ?? "null"}) at seq=${seq}`);
1980
+ mismatchErr.localDivergenceFailure = true;
1981
+ throw mismatchErr;
1982
+ }
1983
+ if (e.finalized !== true) {
1984
+ if (seq === finalizedTipSeq) {
1985
+ finalizedTipSeq = seq - 1;
1986
+ continue;
1987
+ }
1988
+ const unfinalizedGapErr = new CustomError("LEDGER_DIVERGENCE", `Follower crash reconciliation encountered unfinalized ledger entry at seq=${seq} below finalized tip seq=${finalizedTipSeq}`);
1989
+ unfinalizedGapErr.localDivergenceFailure = true;
1990
+ throw unfinalizedGapErr;
1991
+ }
1992
+ if (e.stateCommitHash) {
1993
+ lastStateMutatingEntry = e;
1994
+ break;
1995
+ }
1996
+ }
1997
+ if (finalizedTipSeq <= 0) {
1998
+ this.pendingCrashWindowReconcile = false;
1999
+ this.initialCrashReconcileCompleted = true;
2000
+ return;
2001
+ }
2002
+ if (!lastStateMutatingEntry) {
2003
+ if (shouldReconcileOrphans) await this.reconcileTrailingOrphanRange(1, finalizedTipSeq);
2004
+ this.pendingCrashWindowReconcile = false;
2005
+ this.initialCrashReconcileCompleted = true;
2006
+ return;
2007
+ }
2008
+ const normTipCommit = String(lastStateMutatingEntry.stateCommitHash ?? "").trim().replace(/^0x/i, "").toLowerCase();
2009
+ if (!isGenesisState && normCurrent === normTipCommit) {
2010
+ if (shouldReconcileOrphans && lastStateMutatingEntry.sequence < finalizedTipSeq) await this.reconcileTrailingOrphanRange(lastStateMutatingEntry.sequence + 1, finalizedTipSeq);
2011
+ this.pendingCrashWindowReconcile = false;
2012
+ this.initialCrashReconcileCompleted = true;
2013
+ return;
2014
+ }
2015
+ const unappliedReversed = [];
2016
+ let matchedBase = false;
2017
+ let prunedAllOrphanBaseSeq = null;
2018
+ for (let seq = finalizedTipSeq; seq >= 1; seq--) {
2019
+ const entry = await this.getHotLedgerEntryBySequence(seq);
2020
+ if (!entry) {
2021
+ const prunedCp = await this.findLocalCheckpointAtSequence(seq);
2022
+ if (prunedCp) {
2023
+ const normPrunedRoot = await this.resolveEffectiveCheckpointStateRoot(prunedCp);
2024
+ if (!isGenesisState && normPrunedRoot && normPrunedRoot === normCurrent || !normPrunedRoot && isGenesisState) matchedBase = true;
2025
+ else if (!normPrunedRoot) prunedAllOrphanBaseSeq = prunedCp.sequence;
2026
+ }
2027
+ break;
2028
+ }
2029
+ if (entry.finalized !== true) break;
2030
+ const normEntryCommit = String(entry.stateCommitHash ?? "").trim().replace(/^0x/i, "").toLowerCase();
2031
+ if (!isGenesisState && normEntryCommit && normEntryCommit === normCurrent) {
2032
+ matchedBase = true;
2033
+ break;
2034
+ }
2035
+ unappliedReversed.push(entry);
2036
+ if (seq === 1 && isGenesisState) matchedBase = true;
2037
+ }
2038
+ const unappliedOrdered = [...unappliedReversed].reverse();
2039
+ if (unappliedOrdered.length > 0) this.pendingCrashWindowReconcile = true;
2040
+ const expectedDryRunPrevSeq = prunedAllOrphanBaseSeq ?? 0;
2041
+ if (!matchedBase && unappliedOrdered.length > 0 && unappliedOrdered[0].sequence === expectedDryRunPrevSeq + 1 && typeof this.resolver.statedb.runWithinDryRunSession === "function") {
2042
+ const dryRun = await this.replayer.dryRunVerifyEntries(unappliedOrdered, {
2043
+ expectedPrevSequence: expectedDryRunPrevSeq,
2044
+ prevStateRoot: currentCommit,
2045
+ skipFutureTimestampCheck: true
2046
+ }).catch((dryErr) => {
2047
+ if (isTransientSqliteLockError(dryErr)) throw dryErr;
2048
+ return null;
2049
+ });
2050
+ if (dryRun && String(dryRun.derivedStateRoot ?? "").trim().replace(/^0x/i, "").toLowerCase() === normTipCommit) matchedBase = true;
2051
+ }
2052
+ if (!matchedBase) {
2053
+ const reconcileErr = new CustomError("STATE_COMMIT_MISMATCH", `Follower crash reconciliation could not align statedb commit (${currentCommit}) with finalized ledger tip (seq=${finalizedTipSeq})`);
2054
+ reconcileErr.localDivergenceFailure = true;
2055
+ throw reconcileErr;
2056
+ }
2057
+ for (const entry of unappliedOrdered) await this.replayCrashWindowEntry(entry);
2058
+ this.pendingCrashWindowReconcile = false;
2059
+ this.initialCrashReconcileCompleted = true;
2060
+ }
2061
+ /**
2062
+ * Run one deterministic synchronization pass (cold segments + hot-tail entries + checkpoint sealing).
2063
+ */
2064
+ async syncOnce() {
2065
+ if (this.paused) return;
2066
+ return this.executeSyncPass();
2067
+ }
2068
+ /**
2069
+ * Execute one deterministic synchronization pass even while background polling is paused (`ChainNodeTestHooks`).
2070
+ */
2071
+ async triggerSyncOnce() {
2072
+ return this.executeSyncPass();
2073
+ }
2074
+ async executeSyncPass() {
2075
+ if (this.halted || this.stopped || this.syncMode !== "active-follower") return;
2076
+ if (this.syncInFlight) return this.syncInFlight;
2077
+ const syncFromUpstreamUrl = async (targetBaseUrl, isMultiPeerMode = false) => {
2078
+ this.stagedTofuAnchor = null;
2079
+ try {
2080
+ if (this.artificialPollDelayMs > 0) await new Promise((resolve) => setTimeout(resolve, this.artificialPollDelayMs));
2081
+ const statusRes = await this.fetchAllowlistedJson(targetBaseUrl, "/api/ledger/status", STATUS_MAX_RESPONSE_BYTES);
2082
+ if (statusRes.status !== 200) throw new CustomError("UPSTREAM_UNAVAILABLE", `GET /api/ledger/status returned HTTP ${statusRes.status}`);
2083
+ const upstreamStatus = statusRes.body;
2084
+ if (!upstreamStatus || upstreamStatus.chainId !== this.chainId) throw new CustomError("CHAIN_ID_MISMATCH", `Upstream chainId (${sanitizeUntrustedWireToken(upstreamStatus?.chainId ?? "missing")}) !== local chainId (${this.chainId})`);
2085
+ if (this.disallowKeylessCascadedUpstream) {
2086
+ if (upstreamStatus.nodeRole !== "validator" || !upstreamStatus.checkpointSigningEnabled || !upstreamStatus.statusSignature || !upstreamStatus.proposer) throw new CustomError("UPSTREAM_CASCADED_FORBIDDEN", `Upstream ${targetBaseUrl} is not a signing validator (nodeRole=${sanitizeUntrustedWireToken(upstreamStatus.nodeRole ?? "unknown", 64)}, checkpointSigningEnabled=${Boolean(upstreamStatus.checkpointSigningEnabled)})`);
2087
+ }
2088
+ await this.verifyAndPinTrustAnchorFromStatus(upstreamStatus);
2089
+ const parsedStatusV2From = this.parseStrictEntryHashV2From(upstreamStatus.entryHashV2From);
2090
+ let statusSigVerified = false;
2091
+ if (!this.allowUnauthenticated && this.hotstuffClusterConfig && (!upstreamStatus.statusSignature || !upstreamStatus.proposer)) throw new CustomError("HOT_TAIL_SIGNATURE_MISSING", "HotStuff validator /api/ledger/status response is missing proposer statusSignature");
2092
+ if (upstreamStatus.statusSignature && upstreamStatus.proposer) {
2093
+ const importOpts = this.buildSegmentImportOptions();
2094
+ const trustAnchor = resolveTrustAnchor({
2095
+ proposerPublicKey: importOpts.proposerPublicKey,
2096
+ verifier: importOpts.verifier,
2097
+ hotstuffClusterConfig: importOpts.hotstuffClusterConfig
2098
+ });
2099
+ if (trustAnchor) {
2100
+ const effectiveTrustedProposer = this.getEffectiveTrustedProposer();
2101
+ statusSigVerified = await verifyHotTailStatusSignature({
2102
+ chainId: upstreamStatus.chainId,
2103
+ latestSequence: upstreamStatus.latestSequence,
2104
+ checkpointHeight: upstreamStatus.latestCheckpoint?.height ?? 0,
2105
+ checkpointHash: upstreamStatus.latestCheckpoint?.hash ?? null,
2106
+ writable: upstreamStatus.writable !== false,
2107
+ proposer: upstreamStatus.proposer,
2108
+ ...upstreamStatus.entryHashV2From !== void 0 ? { entryHashV2From: upstreamStatus.entryHashV2From } : {}
2109
+ }, upstreamStatus.statusSignature, trustAnchor, this.hotstuffClusterConfig ? upstreamStatus.proposer : effectiveTrustedProposer || upstreamStatus.proposer || void 0);
2110
+ if (!statusSigVerified) throw new CustomError("HOT_TAIL_SIGNATURE_INVALID", "Invalid proposer statusSignature on /api/ledger/status");
2111
+ this.markSeenSignedUpstream();
2112
+ this.markSeenSignedStatus();
2113
+ if (!this.stagedTofuAnchor && !this.hotstuffClusterConfig) {
2114
+ const anchorProposer = this.trustedProposer || upstreamStatus.proposer;
2115
+ if (anchorProposer) await this.persistTrustAnchorSafe({
2116
+ proposer: anchorProposer,
2117
+ proposerPublicKey: this.trustedProposerPublicKey ? String(this.trustedProposerPublicKey) : "",
2118
+ signatureRatchetLocked: true
2119
+ });
2120
+ }
2121
+ }
2122
+ }
2123
+ if (this.disallowKeylessCascadedUpstream && !statusSigVerified) throw new CustomError("UPSTREAM_CASCADED_FORBIDDEN", `Upstream ${targetBaseUrl} /api/ledger/status signature could not be cryptographically verified against a validator trust anchor`);
2124
+ this.upstreamNodeId = typeof upstreamStatus.nodeId === "string" && upstreamStatus.nodeId.trim() ? upstreamStatus.nodeId.trim() : null;
2125
+ this.upstreamNodeRole = upstreamStatus.nodeRole === "validator" || upstreamStatus.nodeRole === "standby" || upstreamStatus.nodeRole === "follower" ? upstreamStatus.nodeRole : null;
2126
+ await this.checkCheckpointEquivocationAgainstLocal(upstreamStatus.latestCheckpoint, {
2127
+ chainBoundAuthenticated: statusSigVerified,
2128
+ unauthenticatedChainMatched: true,
2129
+ isMultiPeerMode
2130
+ });
2131
+ const upstreamCpSeq = upstreamStatus.latestCheckpoint?.sequence ?? 0;
2132
+ const candidateUpstreamSequence = this.hotstuffClusterConfig ? upstreamCpSeq : upstreamStatus.latestSequence;
2133
+ const verifiedHeadCp = statusSigVerified ? upstreamStatus.latestCheckpoint : null;
2134
+ const parsedV2From = this.buildSegmentImportOptions().allowUnauthenticated || statusSigVerified ? parsedStatusV2From : void 0;
2135
+ const initialSeq = await this.resolver.ledger.getLatestSequence();
2136
+ let localSeq = initialSeq;
2137
+ let mutatedLocalDbOnPeer = false;
2138
+ if (this.coldArchiveStore && localSeq < upstreamCpSeq) {
2139
+ try {
2140
+ if (await this.catchUpFromColdSegments(upstreamStatus.latestCheckpoint?.height, verifiedHeadCp) > 0) mutatedLocalDbOnPeer = true;
2141
+ } catch (coldErr) {
2142
+ if (isFatalVerificationFailure(coldErr) || coldErr?.mutatedLocalDbTransientLock === true) throw coldErr;
2143
+ this.resolver.logger.warn("Cold archive segment unavailable or unverified; falling back to hot-tail sync", {
2144
+ chainId: this.chainId,
2145
+ error: coldErr instanceof Error ? coldErr.message : String(coldErr)
2146
+ });
2147
+ }
2148
+ localSeq = await this.resolver.ledger.getLatestSequence();
2149
+ }
2150
+ if (this.hotstuffClusterConfig) {
2151
+ await this.catchUpHotStuffQcSegmentsFromHttp(targetBaseUrl, upstreamStatus, parsedV2From);
2152
+ this.upstreamSequence = candidateUpstreamSequence;
2153
+ return { writable: upstreamStatus.writable !== false };
2154
+ }
2155
+ const isCryptographicallyAuthenticatedTail = !this.buildSegmentImportOptions().allowUnauthenticated && this.hasCommittedTrustAnchor();
2156
+ let preTailLocalCp = null;
2157
+ try {
2158
+ preTailLocalCp = await this.resolver.ledger.getCheckpoint();
2159
+ } catch (err) {
2160
+ this.rethrowIfLocalStorageOrLockError(err);
2161
+ }
2162
+ const checkSeq = Math.min(localSeq, upstreamStatus.latestSequence);
2163
+ if (!isCryptographicallyAuthenticatedTail && checkSeq > Math.max(preTailLocalCp?.sequence ?? 0, upstreamCpSeq)) {
2164
+ const tipRes = await this.fetchAllowlistedJson(targetBaseUrl, `/api/ledger/entries?from=${checkSeq}&limit=1`, ENTRIES_MAX_RESPONSE_BYTES);
2165
+ if (tipRes.status !== 200 && tipRes.status !== 410) throw new CustomError("UPSTREAM_UNAVAILABLE", `GET /api/ledger/entries?from=${checkSeq}&limit=1 returned HTTP ${tipRes.status}: ${sanitizeUntrustedWireToken(tipRes.body?.error || "", 160)}`);
2166
+ if (tipRes.status === 200) {
2167
+ if (tipRes.body.chainId !== this.chainId) throw new CustomError("CHAIN_ID_MISMATCH", `Entries response chainId (${sanitizeUntrustedWireToken(tipRes.body.chainId)}) !== ${this.chainId}`);
2168
+ if (tipRes.body.from !== void 0 && tipRes.body.from !== checkSeq) throw new CustomError("UPSTREAM_BAD_RESPONSE", `Uncheckpointed tip check from mismatch: requested ${checkSeq}, got ${String(tipRes.body.from)}`);
2169
+ const peerTipEntry = Array.isArray(tipRes.body.entries) ? tipRes.body.entries[0] : void 0;
2170
+ if (!peerTipEntry || peerTipEntry.sequence !== checkSeq) throw new CustomError("UPSTREAM_BAD_RESPONSE", `Upstream failed to return uncheckpointed tip entry at seq=${checkSeq}`);
2171
+ const localTipEntry = await this.getHotLedgerEntryBySequence(checkSeq);
2172
+ if (!localTipEntry) {
2173
+ const corruptErr = new CustomError("LEDGER_DIVERGENCE", `Local ledger missing uncheckpointed tip entry at seq=${checkSeq}`);
2174
+ corruptErr.localDivergenceFailure = true;
2175
+ throw corruptErr;
2176
+ }
2177
+ if (normalizeHexDigest(peerTipEntry.entryHash) !== normalizeHexDigest(localTipEntry.entryHash)) {
2178
+ const tipDivErr = new CustomError("LEDGER_DIVERGENCE", `Uncheckpointed hot-tail tip divergence at seq=${checkSeq}: local ${localTipEntry.entryHash} vs upstream ${peerTipEntry.entryHash}`);
2179
+ if (isMultiPeerMode && !mutatedLocalDbOnPeer) tipDivErr.unauthenticatedPeerDivergence = true;
2180
+ else tipDivErr.localDivergenceFailure = true;
2181
+ throw tipDivErr;
2182
+ }
2183
+ }
2184
+ }
2185
+ const bufferTailBeforeCommit = isMultiPeerMode && !isCryptographicallyAuthenticatedTail;
2186
+ const bufferedTailBatches = [];
2187
+ let cursorSeq = localSeq;
2188
+ let pagesFetched = 0;
2189
+ const handleHotTailReplayError = async (replayErr, batchEntries, activeReplaySeq) => {
2190
+ if (isTransientSqliteLockError(replayErr)) {
2191
+ if (mutatedLocalDbOnPeer) replayErr.mutatedLocalDbTransientLock = true;
2192
+ throw replayErr;
2193
+ }
2194
+ const errCode = replayErr?.code;
2195
+ if (isLocalTrustedStorageHashError(replayErr) || isLocalLedgerStorageCorruptionError(replayErr)) {
2196
+ replayErr.localDivergenceFailure = true;
2197
+ throw replayErr;
2198
+ }
2199
+ if (isLocalExecutionDivergenceCode(errCode)) {
2200
+ const isAuthNow = !this.buildSegmentImportOptions().allowUnauthenticated && this.hasCommittedTrustAnchor();
2201
+ if (isMultiPeerMode && !isAuthNow && !mutatedLocalDbOnPeer) replayErr.unauthenticatedPeerDivergence = true;
2202
+ else replayErr.localDivergenceFailure = true;
2203
+ if (isAuthNow) {
2204
+ replayErr.authenticatedLocalFailure = true;
2205
+ if (this.witnessWallet) await this.tryEmitHotTailReplayFraudAlert(targetBaseUrl, upstreamStatus.latestCheckpoint, statusSigVerified, batchEntries, activeReplaySeq, replayErr).catch(() => void 0);
2206
+ }
2207
+ }
2208
+ throw replayErr;
2209
+ };
2210
+ while (!this.halted && !this.stopped && cursorSeq < upstreamStatus.latestSequence) {
2211
+ if (pagesFetched >= MAX_PAGES_PER_SYNC_CYCLE) break;
2212
+ pagesFetched++;
2213
+ const from = cursorSeq + 1;
2214
+ const entriesRes = await this.fetchAllowlistedJson(targetBaseUrl, `/api/ledger/entries?from=${from}&limit=${MAX_HOT_TAIL_LIMIT}`, ENTRIES_MAX_RESPONSE_BYTES);
2215
+ if (entriesRes.status === 410) {
2216
+ if (this.coldArchiveStore && bufferedTailBatches.length === 0) {
2217
+ const imported = await this.catchUpFromColdSegments(upstreamStatus.latestCheckpoint?.height, verifiedHeadCp);
2218
+ localSeq = await this.resolver.ledger.getLatestSequence();
2219
+ cursorSeq = localSeq;
2220
+ if (imported > 0) mutatedLocalDbOnPeer = true;
2221
+ if (imported > 0 && localSeq >= from) continue;
2222
+ }
2223
+ throw new CustomError("PRUNED_SEQUENCE_UNAVAILABLE", `Sequence ${from} was pruned from upstream hot storage and cold archive segment is unavailable`);
2224
+ }
2225
+ if (entriesRes.status !== 200) throw new CustomError("UPSTREAM_UNAVAILABLE", `GET /api/ledger/entries?from=${from} returned HTTP ${entriesRes.status}: ${sanitizeUntrustedWireToken(entriesRes.body?.error || "", 160)}`);
2226
+ if (entriesRes.body.chainId !== this.chainId) throw new CustomError("CHAIN_ID_MISMATCH", `Entries response chainId (${sanitizeUntrustedWireToken(entriesRes.body.chainId)}) !== ${this.chainId}`);
2227
+ const entries = Array.isArray(entriesRes.body.entries) ? entriesRes.body.entries : [];
2228
+ if (entries.length === 0) break;
2229
+ const effectiveReplayV2From = await this.verifyHotTailEntriesBatchBeforeReplay(from, entriesRes.body, upstreamStatus, parsedV2From) ?? parsedV2From;
2230
+ const existingLocalV2From = this.resolver.ledger.getEntryHashV2From?.();
2231
+ if (typeof existingLocalV2From === "number" && Number.isSafeInteger(existingLocalV2From) && effectiveReplayV2From !== void 0 && effectiveReplayV2From !== existingLocalV2From) throw new CustomError("INVALID_LEDGER_ENTRY", `Upstream entryHashV2From (${String(effectiveReplayV2From)}) conflicts with pinned local entryHashV2From (${existingLocalV2From})`);
2232
+ if (bufferTailBeforeCommit) {
2233
+ bufferedTailBatches.push({
2234
+ entries,
2235
+ effectiveReplayV2From
2236
+ });
2237
+ cursorSeq = entries[entries.length - 1].sequence;
2238
+ } else {
2239
+ let activeReplaySeq = from;
2240
+ try {
2241
+ for (const entry of entries) {
2242
+ activeReplaySeq = entry.sequence;
2243
+ await this.replayer.replayEntry(entry, {
2244
+ appendToLedger: true,
2245
+ entryHashV2From: effectiveReplayV2From
2246
+ });
2247
+ localSeq = entry.sequence;
2248
+ cursorSeq = localSeq;
2249
+ mutatedLocalDbOnPeer = true;
2250
+ }
2251
+ } catch (replayErr) {
2252
+ return await handleHotTailReplayError(replayErr, entries, activeReplaySeq);
2253
+ }
2254
+ }
2255
+ if (!entriesRes.body.hasMore) break;
2256
+ }
2257
+ if (bufferTailBeforeCommit && !this.halted && !this.stopped && pagesFetched < MAX_PAGES_PER_SYNC_CYCLE && cursorSeq < upstreamStatus.latestSequence) {
2258
+ const truncErr = new CustomError("UPSTREAM_BAD_RESPONSE", `Upstream truncated hot-tail entries at seq=${cursorSeq} below status latestSequence=${upstreamStatus.latestSequence}`);
2259
+ truncErr.unauthenticatedPeerDivergence = true;
2260
+ throw truncErr;
2261
+ }
2262
+ if (bufferTailBeforeCommit && bufferedTailBatches.length > 0) {
2263
+ const allBufferedEntries = bufferedTailBatches.flatMap((b) => b.entries);
2264
+ if (typeof this.resolver.statedb.runWithinDryRunSession === "function") try {
2265
+ await this.replayer.dryRunVerifyEntries(allBufferedEntries, {
2266
+ expectedPrevSequence: localSeq,
2267
+ prevStateRoot: localSeq === 0 ? null : await this.readLocalStateCommitHash(),
2268
+ entryHashV2From: bufferedTailBatches[0].effectiveReplayV2From
2269
+ });
2270
+ } catch (dryErr) {
2271
+ return await handleHotTailReplayError(dryErr, allBufferedEntries, allBufferedEntries[0].sequence);
2272
+ }
2273
+ await this.preVerifyBufferedCheckpointsBeforeCommit(targetBaseUrl, upstreamStatus.latestCheckpoint, upstreamStatus.latestSequence, statusSigVerified, preTailLocalCp, localSeq, allBufferedEntries);
2274
+ let activeReplaySeq = allBufferedEntries[0].sequence;
2275
+ try {
2276
+ for (const batch of bufferedTailBatches) for (const entry of batch.entries) {
2277
+ activeReplaySeq = entry.sequence;
2278
+ await this.replayer.replayEntry(entry, {
2279
+ appendToLedger: true,
2280
+ entryHashV2From: batch.effectiveReplayV2From
2281
+ });
2282
+ localSeq = entry.sequence;
2283
+ mutatedLocalDbOnPeer = true;
2284
+ }
2285
+ } catch (replayErr) {
2286
+ return await handleHotTailReplayError(replayErr, allBufferedEntries, activeReplaySeq);
2287
+ }
2288
+ }
2289
+ const sealedAny = await this.sealCaughtUpCheckpoints(targetBaseUrl, upstreamStatus.latestCheckpoint, statusSigVerified, isMultiPeerMode, mutatedLocalDbOnPeer);
2290
+ const verifiedSyncProgress = localSeq > initialSeq || sealedAny;
2291
+ if (verifiedSyncProgress && this.stagedTofuAnchor) await this.commitStagedTofuAnchor();
2292
+ const allowCascadedIdleUnsignedStatus = !this.allowUnauthenticated && !isMultiPeerMode && this.getEffectiveSeenSignedUpstream() && !this.getEffectiveSeenSignedStatus();
2293
+ if (!statusSigVerified && !verifiedSyncProgress && (this.getEffectiveSeenSignedStatus() || !this.buildSegmentImportOptions().allowUnauthenticated && !allowCascadedIdleUnsignedStatus)) throw new CustomError("HOT_TAIL_SIGNATURE_MISSING", "Upstream /api/ledger/status is missing proposer statusSignature");
2294
+ this.upstreamSequence = candidateUpstreamSequence;
2295
+ return { writable: upstreamStatus.writable !== false };
2296
+ } finally {
2297
+ this.stagedTofuAnchor = null;
2298
+ }
2299
+ };
2300
+ const run = (async () => {
2301
+ try {
2302
+ await this.reconcileFollowerCrashWindowIfNeeded();
2303
+ await this.hydrateDurableTrustRatchet();
2304
+ let initialLocalCp = null;
2305
+ try {
2306
+ initialLocalCp = await this.resolver.ledger.getCheckpoint();
2307
+ } catch (err) {
2308
+ this.rethrowIfLocalStorageOrLockError(err);
2309
+ }
2310
+ if (initialLocalCp?.height && initialLocalCp.height > 0) this.leaderRouter?.advanceMinVerifiedCheckpointHeight?.(initialLocalCp.height);
2311
+ const baseUrl = this.resolveActiveUpstreamUrl();
2312
+ if (!baseUrl) {
2313
+ if (!this.coldArchiveStore) return;
2314
+ const head = await this.fetchColdArchiveHead();
2315
+ if (head) {
2316
+ if (head.chainId !== this.chainId) throw new CustomError("CHAIN_ID_MISMATCH", `Cold archive head chainId (${sanitizeUntrustedWireToken(head.chainId)}) !== local chainId (${this.chainId})`);
2317
+ this.upstreamSequence = head.latestSequence;
2318
+ await this.catchUpFromColdSegments(head.latestHeight);
2319
+ } else {
2320
+ await this.catchUpFromColdSegments();
2321
+ this.upstreamSequence = await this.resolver.ledger.getLatestSequence();
2322
+ }
2323
+ this.lastUpstreamSuccessAtMs = Date.now();
2324
+ return;
2325
+ }
2326
+ const rawRouterCandidates = this.leaderRouter?.getCandidateUrls?.() ?? [];
2327
+ const routerCandidates = rawRouterCandidates.map((u) => u ? canonicalizePeerBaseUrl(u) : "").filter(Boolean);
2328
+ const allCandidateUrls = Array.from(new Set([
2329
+ baseUrl,
2330
+ ...routerCandidates,
2331
+ ...this.allowedBaseUrls
2332
+ ].filter(Boolean)));
2333
+ const buildRouterExclusionSet = (canonicalTried) => {
2334
+ const excluded = new Set(canonicalTried);
2335
+ for (const raw of rawRouterCandidates) {
2336
+ const canon = raw ? canonicalizePeerBaseUrl(raw) : "";
2337
+ if (canon && canonicalTried.has(canon)) excluded.add(raw);
2338
+ }
2339
+ return excluded;
2340
+ };
2341
+ const normalizePromotedPeerUrl = (rawPromoted) => {
2342
+ const canon = rawPromoted ? canonicalizePeerBaseUrl(rawPromoted) : "";
2343
+ if (!canon || !this.allowedBaseUrls.has(canon)) return null;
2344
+ return canon;
2345
+ };
2346
+ const candidateCount = allCandidateUrls.length;
2347
+ const isMultiPeerMode = candidateCount > 1;
2348
+ const triedUrls = /* @__PURE__ */ new Set();
2349
+ const unauthDivergencePeers = /* @__PURE__ */ new Set();
2350
+ let firstUnauthDivergenceErr = null;
2351
+ let currentTarget = baseUrl;
2352
+ let lastErr = null;
2353
+ while (currentTarget && !triedUrls.has(currentTarget)) {
2354
+ triedUrls.add(currentTarget);
2355
+ try {
2356
+ const seqBeforeSync = await this.resolver.ledger.getLatestSequence();
2357
+ const syncOutcome = await syncFromUpstreamUrl(currentTarget, isMultiPeerMode);
2358
+ const seqAfterSync = await this.resolver.ledger.getLatestSequence();
2359
+ this.lastUpstreamSuccessAtMs = Date.now();
2360
+ if (seqAfterSync > seqBeforeSync) this.stagnantSyncCycles = 0;
2361
+ else this.stagnantSyncCycles++;
2362
+ const shouldProbeOtherValidators = syncOutcome.writable === false || this.stagnantSyncCycles >= 2 || Date.now() - this.lastPeerProbeAtMs >= Math.max(1e3, this.pollIntervalMs * 3);
2363
+ if (this.hotstuffClusterConfig && shouldProbeOtherValidators && candidateCount > triedUrls.size && this.leaderRouter?.probeAndPromoteLeader) {
2364
+ this.lastPeerProbeAtMs = Date.now();
2365
+ const exclusion = syncOutcome.writable === false ? buildRouterExclusionSet(triedUrls) : void 0;
2366
+ const promoted = normalizePromotedPeerUrl(await this.leaderRouter.probeAndPromoteLeader(exclusion));
2367
+ if (promoted && !triedUrls.has(promoted)) {
2368
+ this.stagnantSyncCycles = 0;
2369
+ currentTarget = promoted;
2370
+ continue;
2371
+ }
2372
+ }
2373
+ return;
2374
+ } catch (peerErr) {
2375
+ lastErr = peerErr;
2376
+ if (peerErr?.unauthenticatedPeerDivergence === true) {
2377
+ unauthDivergencePeers.add(currentTarget);
2378
+ firstUnauthDivergenceErr ??= peerErr;
2379
+ }
2380
+ if (isFatalVerificationFailure(peerErr) || peerErr?.mutatedLocalDbTransientLock === true) throw peerErr;
2381
+ if (candidateCount <= triedUrls.size) break;
2382
+ const promoted = normalizePromotedPeerUrl(this.leaderRouter?.probeAndPromoteLeader ? await this.leaderRouter.probeAndPromoteLeader(buildRouterExclusionSet(triedUrls)) : null);
2383
+ const nextFallback = promoted && !triedUrls.has(promoted) ? promoted : allCandidateUrls.find((u) => !triedUrls.has(u)) ?? null;
2384
+ if (!nextFallback) break;
2385
+ currentTarget = nextFallback;
2386
+ }
2387
+ }
2388
+ if (firstUnauthDivergenceErr && unauthDivergencePeers.size >= candidateCount) {
2389
+ firstUnauthDivergenceErr.localDivergenceFailure = true;
2390
+ throw firstUnauthDivergenceErr;
2391
+ }
2392
+ if (lastErr) throw lastErr;
2393
+ } catch (err) {
2394
+ const errCode = err?.code;
2395
+ if (isFatalVerificationFailure(err) || errCode === "UPSTREAM_CASCADED_FORBIDDEN") {
2396
+ const message = err instanceof Error ? err.message : String(err);
2397
+ const haltReason = errCode && !message.includes(errCode) ? `${errCode}: ${message}` : message;
2398
+ this.haltFailClosed(haltReason, errCode);
2399
+ throw err;
2400
+ }
2401
+ if (errCode === FUTURE_LEDGER_ENTRY_TIMESTAMP) this.resolver.logger.error(`FollowerSyncService refused a future-dated ledger entry (${errCode}); will retry`, {
2402
+ chainId: this.chainId,
2403
+ code: errCode,
2404
+ rejections: this.futureTimestampRejections,
2405
+ error: err instanceof Error ? err.message : String(err)
2406
+ });
2407
+ else this.resolver.logger.warn("FollowerSyncService transient sync error", {
2408
+ chainId: this.chainId,
2409
+ error: err instanceof Error ? err.message : String(err)
2410
+ });
2411
+ }
2412
+ })();
2413
+ this.syncInFlight = run;
2414
+ try {
2415
+ await run;
2416
+ } finally {
2417
+ if (this.syncInFlight === run) this.syncInFlight = null;
2418
+ }
2419
+ }
2420
+ /**
2421
+ * Start background hot-tail synchronization loop (performs an initial sync pass before returning).
2422
+ */
2423
+ async start() {
2424
+ this.stopped = false;
2425
+ if (this.syncMode !== "active-follower" || this.halted) return;
2426
+ await this.syncOnce();
2427
+ if (this.stopped || this.halted || this.timer) return;
2428
+ this.timer = setInterval(() => {
2429
+ this.syncOnce().catch(() => {});
2430
+ }, this.pollIntervalMs);
2431
+ if (typeof this.timer.unref === "function") this.timer.unref();
2432
+ }
2433
+ async flushWitnessTasks() {
2434
+ if (this.pendingWitnessTasks.size === 0) return;
2435
+ await Promise.allSettled(Array.from(this.pendingWitnessTasks));
2436
+ }
2437
+ /**
2438
+ * Stop background polling and wait for any in-flight replay transaction to finish cleanly.
2439
+ */
2440
+ async close() {
2441
+ this.stopped = true;
2442
+ if (this.timer) {
2443
+ clearInterval(this.timer);
2444
+ this.timer = null;
2445
+ }
2446
+ if (this.syncInFlight) await this.syncInFlight.catch(() => void 0);
2447
+ await this.flushWitnessTasks();
2448
+ }
2449
+ };
2450
+
2451
+ //#endregion
2452
+ export { DEFAULT_FOLLOWER_HTTP_TIMEOUT_MS, DEFAULT_FOLLOWER_MAX_SYNC_LAG, DEFAULT_FOLLOWER_MAX_UPSTREAM_STALE_MS, DEFAULT_FOLLOWER_POLL_INTERVAL_MS, FollowerSyncService, isTransientSqliteLockError };