@ocap/resolver 1.31.8 → 1.32.0

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