@ocap/resolver 1.32.1 → 1.32.3

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.
@@ -84,6 +84,10 @@ interface ILedgerHealthSummary {
84
84
  witnessQuorum: number;
85
85
  witnessCircuitBroken: boolean;
86
86
  witnessFraudAlertCount: number;
87
+ /** Present only when the segment publisher runs in DA mode (#2016); never part of `healthy` */
88
+ daPublisher?: Record<string, unknown>;
89
+ /** Present only on a follower that reads the DA archive (#2017): `{ state: 'ok' }` or `{ state: 'stalled', code: 'DA_GAP', ... }`; never part of `healthy` */
90
+ daArchive?: Record<string, unknown>;
87
91
  entryHashV2From: string | null;
88
92
  latestSequence: number;
89
93
  latestCheckpoint: (Record<string, unknown> & {
package/esm/dashboard.mjs CHANGED
@@ -79,6 +79,8 @@ async function collectLedgerHealthSummary(options) {
79
79
  const proposerPublicKey = options.ledger.getProposerPublicKey?.() || null;
80
80
  const checkpointSigningEnabled = typeof options.ledger.isCheckpointSigningEnabled === "function" ? options.ledger.isCheckpointSigningEnabled() : Boolean(proposerPublicKey);
81
81
  const witnessRegistry = extLedger.getWitnessRegistry?.();
82
+ const daPublisher = extLedger.getDaPublisherStatus?.() ?? null;
83
+ const daArchive = options.runtime?.getDaArchiveStatus?.() ?? null;
82
84
  return {
83
85
  healthy,
84
86
  ...halted ? {
@@ -100,6 +102,8 @@ async function collectLedgerHealthSummary(options) {
100
102
  witnessQuorum: witnessRegistry?.getQuorum() ?? 0,
101
103
  witnessCircuitBroken: witnessRegistry?.isCircuitBroken() ?? false,
102
104
  witnessFraudAlertCount: witnessRegistry?.getFraudAlerts().length ?? 0,
105
+ ...daPublisher ? { daPublisher } : {},
106
+ ...daArchive ? { daArchive } : {},
103
107
  entryHashV2From,
104
108
  latestSequence: health.latestSequence,
105
109
  latestCheckpoint: health.latestCheckpoint ? {
@@ -654,6 +658,7 @@ function createNodeDashboardRouter(options) {
654
658
  witnessQuorum: ledgerHealth.witnessQuorum,
655
659
  witnessCircuitBroken: ledgerHealth.witnessCircuitBroken,
656
660
  witnessFraudAlertCount: ledgerHealth.witnessFraudAlertCount,
661
+ ...ledgerHealth.daPublisher ? { publisher: ledgerHealth.daPublisher } : {},
657
662
  latestAnchorReceipt
658
663
  },
659
664
  pipeline,
package/esm/explorer.mjs CHANGED
@@ -1,5 +1,6 @@
1
1
  import { __require } from "./_virtual/rolldown_runtime.mjs";
2
2
  import { UNIFIED_CONSOLE_APP_JS, buildUnifiedConsoleHtml } from "./dashboard.mjs";
3
+ import { isLoopbackAddress } from "@ocap/util/lib/client-ip";
3
4
 
4
5
  //#region src/explorer.ts
5
6
  function loadNodeBuiltin(id) {
@@ -120,8 +121,15 @@ function createExplorerMiddleware(options) {
120
121
  if (verifiedDistRealPath && reqPath === "/static/js/networks.js") {
121
122
  const cfg = options.getConfig() ?? {};
122
123
  const chainId = String(cfg.chainId || "local-chain");
123
- const host = req.get?.("host") || req.headers?.host || "";
124
- const endpoint = /^https?:\/\//.test(chainEndpoint) ? chainEndpoint : `${req.protocol || "http"}://${host}${chainEndpoint.startsWith("/") ? "" : "/"}${chainEndpoint.replace(/\/+$/, "")}/`;
124
+ const rawHost = String(req.get?.("host") || req.headers?.host || "").trim();
125
+ const safeHost = rawHost.length > 0 && rawHost.length <= 255 && (/^[A-Za-z0-9.-]+(?::\d{1,5})?$/.test(rawHost) || /^\[[0-9a-fA-F:]+\](?::\d{1,5})?$/.test(rawHost)) ? rawHost : "127.0.0.1";
126
+ let scheme = req.protocol === "https" ? "https" : "http";
127
+ if (scheme === "http" && isLoopbackAddress(req.socket?.remoteAddress)) {
128
+ const xfProto = String(req.headers?.["x-forwarded-proto"] || "").split(",")[0].trim().toLowerCase();
129
+ const cfVisitor = String(req.headers?.["cf-visitor"] || "");
130
+ if (xfProto === "https" || /"scheme"\s*:\s*"https"/i.test(cfVisitor)) scheme = "https";
131
+ }
132
+ const endpoint = /^https?:\/\//.test(chainEndpoint) ? chainEndpoint : `${scheme}://${safeHost}${chainEndpoint.startsWith("/") ? "" : "/"}${chainEndpoint.replace(/\/+$/, "")}/`;
125
133
  const networks = [{
126
134
  name: chainId,
127
135
  abbr: cfg.token?.symbol || "ARC",
@@ -131,7 +139,8 @@ function createExplorerMiddleware(options) {
131
139
  }];
132
140
  applyExplorerSecurityHeaders(res, false);
133
141
  res.setHeader("Content-Type", "application/javascript; charset=utf-8");
134
- res.setHeader("Cache-Control", "no-cache");
142
+ res.setHeader("Cache-Control", "no-store");
143
+ res.setHeader("Vary", "Host, X-Forwarded-Proto, CF-Visitor");
135
144
  return res.status(200).send(`window.ARCBLOCK_NETWORKS = ${safeJsonForJsLiteral(networks)};\n`);
136
145
  }
137
146
  if (reqPath === "/static/js/networks.js") {
@@ -101,6 +101,24 @@ interface FollowerSyncServiceOptions {
101
101
  };
102
102
  }
103
103
  declare function isTransientSqliteLockError(err: unknown): boolean;
104
+ /** The cold catch-up after a `410`: see `FollowerSyncService.coldCatchUpAfterPrune` (a pure function so it can be tested). */
105
+ declare function catchUpAfterPrune(options: {
106
+ isDaReader: boolean;
107
+ run: () => Promise<number>;
108
+ onSwallowed: (err: unknown, imported: number) => void;
109
+ }): Promise<number>;
110
+ /**
111
+ * A cold catch-up that fails after it already imported segments (a DA stall or a transient error at segment N+k) has
112
+ * changed the local database: the error carries how many it imported, so the callers do not treat the cycle as untouched.
113
+ */
114
+ declare function noteColdImports(err: unknown, imported: number): void;
115
+ /** How many segments a failed cold catch-up had imported before it failed (0 when it imported none or is not annotated). */
116
+ declare function coldImportsBefore(err: unknown): number;
117
+ /**
118
+ * `.catch()` handler for a best-effort cold segment lookup (to find a checkpoint, not to import): a miss or a transient
119
+ * error is "not found here", but a fatal DA reader error (`daFatal`, #2017) is never swallowed: it halts the follower.
120
+ */
121
+ declare function coldLookupMiss(err: unknown): null;
104
122
  declare class FollowerSyncService implements INodeRuntimeAdapter {
105
123
  readonly role: TNodeRole;
106
124
  writePolicy: TNodeWritePolicy;
@@ -170,6 +188,10 @@ declare class FollowerSyncService implements INodeRuntimeAdapter {
170
188
  getRuntimeDiagnostics(options?: {
171
189
  includePrivateTopology?: boolean;
172
190
  }): Record<string, unknown>;
191
+ /** The DA reader's status for `/api/health/ledger` (`daArchive`), or null for any other cold reader (#2017). */
192
+ getDaArchiveStatus(): Record<string, unknown> | null;
193
+ /** DA follower only (#2017): `daArchive: { state: 'ok' | 'stalled', ... }`; nothing is added for any other cold reader. */
194
+ private daArchiveDiagnostics;
173
195
  triggerSyncOrProbe(): Promise<Record<string, unknown>>;
174
196
  private haltFailClosed;
175
197
  private resolveActiveUpstreamUrl;
@@ -242,6 +264,12 @@ declare class FollowerSyncService implements INodeRuntimeAdapter {
242
264
  * Stage 1B: Catch up sealed `.zst` checkpoint segments from `coldArchiveStore` when available.
243
265
  */
244
266
  private catchUpFromColdSegments;
267
+ /**
268
+ * The cold catch-up of a `410` (the leader pruned what the follower needs). Only a DA reader's non-fatal failure (a stall)
269
+ * is treated as "no cold source this cycle"; any other cold reader keeps the base behaviour exactly: its error propagates.
270
+ */
271
+ private coldCatchUpAfterPrune;
272
+ private catchUpFromColdSegmentsInner;
245
273
  private sealCaughtUpCheckpoints;
246
274
  private tryEmitHotTailReplayFraudAlert;
247
275
  private parseStrictEntryHashV2From;
@@ -291,4 +319,4 @@ declare class FollowerSyncService implements INodeRuntimeAdapter {
291
319
  close(): Promise<void>;
292
320
  }
293
321
  //#endregion
294
- export { DEFAULT_FOLLOWER_HTTP_TIMEOUT_MS, DEFAULT_FOLLOWER_MAX_SYNC_LAG, DEFAULT_FOLLOWER_MAX_UPSTREAM_STALE_MS, DEFAULT_FOLLOWER_POLL_INTERVAL_MS, FollowerSyncService, FollowerSyncServiceOptions, IColdSegmentReader, ILeaderRouterLike, TFollowerUpstreamFetchInterceptor, TFollowerUpstreamFetchKind, isTransientSqliteLockError };
322
+ export { DEFAULT_FOLLOWER_HTTP_TIMEOUT_MS, DEFAULT_FOLLOWER_MAX_SYNC_LAG, DEFAULT_FOLLOWER_MAX_UPSTREAM_STALE_MS, DEFAULT_FOLLOWER_POLL_INTERVAL_MS, FollowerSyncService, FollowerSyncServiceOptions, IColdSegmentReader, ILeaderRouterLike, TFollowerUpstreamFetchInterceptor, TFollowerUpstreamFetchKind, catchUpAfterPrune, coldImportsBefore, coldLookupMiss, isTransientSqliteLockError, noteColdImports };
package/esm/follower.mjs CHANGED
@@ -1,5 +1,5 @@
1
1
  import { createFollowerPeerFetchGuard } from "./node-preferences.mjs";
2
- import { FUTURE_LEDGER_ENTRY_TIMESTAMP, LedgerEntryReplayer } from "./replayer.mjs";
2
+ import { FUTURE_LEDGER_ENTRY_TIMESTAMP, LedgerEntryReplayer, assertReplayEntryChainIdAcceptable, isReplayEntryChainIdAcceptable } from "./replayer.mjs";
3
3
  import { ArchivePayloadDecodeError, EntryHashRunVerifier, HotWindowPruneController, IncrementalMerkleTree, assertValidSegment, computeCheckpointHash, computeEntryHash, computeHotTailEntryCommitment, computeSegmentContentHash, createHotStuffTrustAnchor, createWitnessAttestation, deriveSegmentStateRoot, normalizeHttpBaseUrl, resolveTrustAnchor, verifyCheckpointQuorumCertificate, verifyCheckpointSignature, verifyDidMatchesMultiCurvePublicKey, verifyHotTailBatchSignature, verifyHotTailStatusSignature, verifySegmentCommitmentSignature } from "@arcblock/ledger-core";
4
4
  import { toBuffer } from "@ocap/util";
5
5
  import { CustomError } from "@ocap/util/lib/error";
@@ -215,11 +215,43 @@ function isLocalTrustedStorageHashError(err, depth = 0) {
215
215
  function isFatalVerificationFailure(err) {
216
216
  if (err instanceof ArchivePayloadDecodeError || err?.name === "ArchivePayloadDecodeError") return false;
217
217
  if (isTransientSqliteLockError(err)) return false;
218
+ if (err?.daFatal === true) return true;
218
219
  if (err?.authenticatedLocalFailure === true || err?.localDivergenceFailure === true) return true;
219
220
  const code = err?.code;
220
221
  if (isLocalTrustedStorageHashError(err)) return true;
221
222
  return code === "TRUST_ANCHOR_REQUIRED";
222
223
  }
224
+ /** The cold catch-up after a `410`: see `FollowerSyncService.coldCatchUpAfterPrune` (a pure function so it can be tested). */
225
+ async function catchUpAfterPrune(options) {
226
+ if (!options.isDaReader) return options.run();
227
+ try {
228
+ return await options.run();
229
+ } catch (err) {
230
+ if (isFatalVerificationFailure(err) || err?.mutatedLocalDbTransientLock === true) throw err;
231
+ options.onSwallowed(err, coldImportsBefore(err));
232
+ return coldImportsBefore(err);
233
+ }
234
+ }
235
+ /**
236
+ * A cold catch-up that fails after it already imported segments (a DA stall or a transient error at segment N+k) has
237
+ * changed the local database: the error carries how many it imported, so the callers do not treat the cycle as untouched.
238
+ */
239
+ function noteColdImports(err, imported) {
240
+ if (imported > 0 && err && typeof err === "object") err.coldImportedCount = imported;
241
+ }
242
+ /** How many segments a failed cold catch-up had imported before it failed (0 when it imported none or is not annotated). */
243
+ function coldImportsBefore(err) {
244
+ const n = err?.coldImportedCount;
245
+ return typeof n === "number" && Number.isSafeInteger(n) && n > 0 ? n : 0;
246
+ }
247
+ /**
248
+ * `.catch()` handler for a best-effort cold segment lookup (to find a checkpoint, not to import): a miss or a transient
249
+ * error is "not found here", but a fatal DA reader error (`daFatal`, #2017) is never swallowed: it halts the follower.
250
+ */
251
+ function coldLookupMiss(err) {
252
+ if (err?.daFatal === true) throw err;
253
+ return null;
254
+ }
223
255
  function canonicalizePeerBaseUrl(rawUrl) {
224
256
  const trimmed = rawUrl.trim();
225
257
  if (!trimmed) return "";
@@ -428,6 +460,7 @@ var FollowerSyncService = class {
428
460
  witnessEnabled: Boolean(this.witnessWallet),
429
461
  witnessAddress: this.witnessAddress,
430
462
  coldArchiveConfigured: Boolean(this.coldArchiveStore),
463
+ ...this.daArchiveDiagnostics(),
431
464
  peerCount: this.allowedBaseUrls.size,
432
465
  ...includePrivate ? {
433
466
  upstreamUrl: this.upstreamUrl,
@@ -445,6 +478,15 @@ var FollowerSyncService = class {
445
478
  } : null
446
479
  };
447
480
  }
481
+ /** The DA reader's status for `/api/health/ledger` (`daArchive`), or null for any other cold reader (#2017). */
482
+ getDaArchiveStatus() {
483
+ return this.daArchiveDiagnostics().daArchive ?? null;
484
+ }
485
+ /** DA follower only (#2017): `daArchive: { state: 'ok' | 'stalled', ... }`; nothing is added for any other cold reader. */
486
+ daArchiveDiagnostics() {
487
+ const reader = this.coldArchiveStore;
488
+ return reader?.isDaSegmentReader === true && typeof reader.getStatus === "function" ? { daArchive: reader.getStatus() } : {};
489
+ }
448
490
  async triggerSyncOrProbe() {
449
491
  if (this.halted) throw new CustomError("NODE_HALTED", `Follower node is halted: ${this.haltReason || "verification error"}`);
450
492
  const promoted = this.leaderRouter?.probeAndPromoteLeader ? await this.leaderRouter.probeAndPromoteLeader() : null;
@@ -1068,8 +1110,33 @@ var FollowerSyncService = class {
1068
1110
  * Stage 1B: Catch up sealed `.zst` checkpoint segments from `coldArchiveStore` when available.
1069
1111
  */
1070
1112
  async catchUpFromColdSegments(maxTargetHeight, verifiedHeadCheckpoint) {
1113
+ const progress = { imported: 0 };
1114
+ try {
1115
+ return await this.catchUpFromColdSegmentsInner(maxTargetHeight, verifiedHeadCheckpoint, progress);
1116
+ } catch (err) {
1117
+ if (this.coldArchiveStore?.isDaSegmentReader === true) noteColdImports(err, progress.imported);
1118
+ throw err;
1119
+ }
1120
+ }
1121
+ /**
1122
+ * The cold catch-up of a `410` (the leader pruned what the follower needs). Only a DA reader's non-fatal failure (a stall)
1123
+ * is treated as "no cold source this cycle"; any other cold reader keeps the base behaviour exactly: its error propagates.
1124
+ */
1125
+ async coldCatchUpAfterPrune(maxTargetHeight, verifiedHeadCheckpoint) {
1126
+ return catchUpAfterPrune({
1127
+ isDaReader: this.coldArchiveStore?.isDaSegmentReader === true,
1128
+ run: () => this.catchUpFromColdSegments(maxTargetHeight, verifiedHeadCheckpoint),
1129
+ onSwallowed: (err, imported) => this.resolver.logger.warn("Cold archive segment unavailable after a pruned upstream; not a cold source for this cycle", {
1130
+ chainId: this.chainId,
1131
+ imported,
1132
+ error: err instanceof Error ? err.message : String(err)
1133
+ })
1134
+ });
1135
+ }
1136
+ async catchUpFromColdSegmentsInner(maxTargetHeight, verifiedHeadCheckpoint, progress) {
1071
1137
  if (!this.coldArchiveStore) return 0;
1072
1138
  await this.hydrateDurableTrustRatchet();
1139
+ const isDaCold = this.coldArchiveStore.isDaSegmentReader === true;
1073
1140
  const verifiedColdAncestors = /* @__PURE__ */ new Map();
1074
1141
  if (verifiedHeadCheckpoint && typeof verifiedHeadCheckpoint.hash === "string" && normalizeHexDigest(computeCheckpointHash(verifiedHeadCheckpoint)) === normalizeHexDigest(verifiedHeadCheckpoint.hash)) verifiedColdAncestors.set(verifiedHeadCheckpoint.height, verifiedHeadCheckpoint);
1075
1142
  let importedCount = 0;
@@ -1111,6 +1178,7 @@ var FollowerSyncService = class {
1111
1178
  checkpoint: rawSegment.checkpoint,
1112
1179
  entries: rawSegment.entries
1113
1180
  };
1181
+ if (isDaCold && verifiedHeadCheckpoint && canonicalSegment.checkpoint.height === verifiedHeadCheckpoint.height && (normalizeHexDigest(canonicalSegment.checkpoint.hash) !== normalizeHexDigest(verifiedHeadCheckpoint.hash) || normalizeHexDigest(canonicalSegment.checkpoint.stateRoot ?? "") !== normalizeHexDigest(verifiedHeadCheckpoint.stateRoot ?? ""))) throw Object.assign(new CustomError("DA_LEADER_MISMATCH", `DA segment #${nextHeight} (${canonicalSegment.checkpoint.hash}) is not the leader's signed checkpoint at that height (${verifiedHeadCheckpoint.hash})`), { daFatal: true });
1114
1182
  if ("contentHash" in rawBundle && rawBundle.contentHash !== void 0) {
1115
1183
  if (typeof rawBundle.contentHash !== "string" || rawBundle.contentHash.replace(/^0x/i, "").toLowerCase() !== computeSegmentContentHash(canonicalSegment).replace(/^0x/i, "").toLowerCase()) throw new CustomError("COLD_BUNDLE_WRAPPER_MISMATCH", `Cold segment #${nextHeight} unsigned contentHash wrapper does not match canonical segment digest`);
1116
1184
  }
@@ -1132,7 +1200,7 @@ var FollowerSyncService = class {
1132
1200
  }
1133
1201
  let stepCp = h === nextHeight ? canonicalSegment.checkpoint : verifiedColdAncestors.get(h) ?? null;
1134
1202
  if (!stepCp) {
1135
- const stepSeg = await this.coldArchiveStore.getSegment(this.chainId, h).catch(() => null);
1203
+ const stepSeg = await this.coldArchiveStore.getSegment(this.chainId, h).catch(coldLookupMiss);
1136
1204
  stepCp = stepSeg && stepSeg.chainId === this.chainId ? stepSeg.checkpoint : null;
1137
1205
  }
1138
1206
  if (!stepCp || typeof stepCp.hash !== "string" || normalizeHexDigest(stepCp.hash) !== normalizeHexDigest(expectedHash) || normalizeHexDigest(computeCheckpointHash(stepCp)) !== normalizeHexDigest(expectedHash)) {
@@ -1198,7 +1266,10 @@ var FollowerSyncService = class {
1198
1266
  }
1199
1267
  throw segVerifyErr;
1200
1268
  }
1201
- for (const entry of canonicalSegment.entries) this.replayer.validateWireEntry(entry);
1269
+ for (const entry of canonicalSegment.entries) {
1270
+ this.replayer.validateWireEntry(entry);
1271
+ assertReplayEntryChainIdAcceptable(entry, this.chainId, "Cold segment");
1272
+ }
1202
1273
  const hadPartialLocalEntries = localSeq > canonicalSegment.checkpoint.prevSequence;
1203
1274
  let mutatedLocalDb = false;
1204
1275
  try {
@@ -1287,6 +1358,7 @@ var FollowerSyncService = class {
1287
1358
  verifiedLocalStateRoot: verifiedColdStateRoot
1288
1359
  });
1289
1360
  importedCount++;
1361
+ progress.imported = importedCount;
1290
1362
  if (importedCount >= MAX_PAGES_PER_SYNC_CYCLE) break;
1291
1363
  }
1292
1364
  if (importedCount > 0 && this.pruneController) await this.pruneController.pruneHotWindow(this.resolver.ledger);
@@ -1369,7 +1441,7 @@ var FollowerSyncService = class {
1369
1441
  publicKeyOrVerifier: coldVerifyAnchor,
1370
1442
  requireSignature: !importOpts.allowUnauthenticated,
1371
1443
  allowUnauthenticated: importOpts.allowUnauthenticated
1372
- }).catch(() => null);
1444
+ }).catch(coldLookupMiss);
1373
1445
  if (seg && seg.chainId === this.chainId) {
1374
1446
  targetCp = seg.checkpoint;
1375
1447
  const coldAuth = await this.isColdSegmentAuthenticatedByProposer(seg);
@@ -1516,7 +1588,10 @@ var FollowerSyncService = class {
1516
1588
  hotstuffClusterConfig: importOpts.hotstuffClusterConfig
1517
1589
  });
1518
1590
  if (importOpts.allowUnauthenticated && !trustAnchor) {
1519
- for (let i = 0; i < entries.length; i++) this.replayer.validateWireEntry(entries[i]);
1591
+ for (let i = 0; i < entries.length; i++) {
1592
+ this.replayer.validateWireEntry(entries[i]);
1593
+ assertReplayEntryChainIdAcceptable(entries[i], this.chainId, "Hot-tail");
1594
+ }
1520
1595
  return batchParsedV2From ?? parsedV2From;
1521
1596
  }
1522
1597
  if (!trustAnchor) {
@@ -1531,11 +1606,11 @@ var FollowerSyncService = class {
1531
1606
  const entry = entries[i];
1532
1607
  const expectedSeq = requestedFrom + i;
1533
1608
  if (!entry || entry.sequence !== expectedSeq) throw new CustomError("INVALID_LEDGER_ENTRY", `Hot-tail batch sequence discontinuity at index ${i}: expected ${expectedSeq}, got ${entry?.sequence}`);
1534
- if (entry.chainId !== this.chainId) throw new CustomError("CHAIN_ID_MISMATCH", `Hot-tail entry chainId (${entry.chainId}) !== local chainId (${this.chainId})`);
1609
+ if (!isReplayEntryChainIdAcceptable(entry, this.chainId)) assertReplayEntryChainIdAcceptable(entry, this.chainId, "Hot-tail");
1535
1610
  if (entry.finalized !== true) throw new CustomError("UNFINALIZED_LEDGER_ENTRY", `Hot-tail entry seq=${entry.sequence} is not finalized`);
1536
1611
  if (!Number.isSafeInteger(entry.timestamp) || entry.timestamp < 0 || entry.timestamp > MAX_SAFE_EPOCH_MS) throw new CustomError("INVALID_LEDGER_ENTRY", `Hot-tail entry seq=${entry.sequence} has invalid timestamp: ${String(entry.timestamp)}`);
1537
1612
  if (typeof entry.txRaw !== "string" || !entry.txRaw || entry.txRaw !== entry.txRaw.trim()) throw new CustomError("INVALID_LEDGER_ENTRY", `Hot-tail entry seq=${entry.sequence} has missing or non-canonical txRaw`);
1538
- this.replayer.validateWireEntry(entry);
1613
+ this.replayer.validateWireEntry(entry, { skipFutureTimestampCheck: true });
1539
1614
  const expectedHash = computeEntryHash(entry.sequence, entry.txRaw, entry.stateCommitHash ?? "", entry.sequence >= v2Cutoff ? 2 : 1);
1540
1615
  if (entry.entryHash !== expectedHash) throw new CustomError("LEDGER_DIVERGENCE", `Hot-tail entryHash mismatch at seq=${entry.sequence}: expected ${expectedHash}, got ${entry.entryHash}`);
1541
1616
  entryHashes.push(entry.entryHash);
@@ -1563,6 +1638,7 @@ var FollowerSyncService = class {
1563
1638
  signatureRatchetLocked: true
1564
1639
  });
1565
1640
  }
1641
+ for (const entry of entries) this.replayer.assertEntryTimestampNotInFuture(entry);
1566
1642
  return batchParsedV2From;
1567
1643
  }
1568
1644
  const cp = upstreamStatus.latestCheckpoint;
@@ -1586,11 +1662,15 @@ var FollowerSyncService = class {
1586
1662
  signatureRatchetLocked: true
1587
1663
  });
1588
1664
  }
1665
+ for (const entry of entries) this.replayer.assertEntryTimestampNotInFuture(entry);
1589
1666
  return;
1590
1667
  }
1591
1668
  }
1592
1669
  }
1593
- if (importOpts.allowUnauthenticated && !entriesBody.batchSignature && !this.hotstuffClusterConfig) return batchParsedV2From ?? parsedV2From;
1670
+ if (importOpts.allowUnauthenticated && !entriesBody.batchSignature && !this.hotstuffClusterConfig) {
1671
+ for (const entry of entries) this.replayer.assertEntryTimestampNotInFuture(entry);
1672
+ return batchParsedV2From ?? parsedV2From;
1673
+ }
1594
1674
  throw new CustomError("HOT_TAIL_SIGNATURE_MISSING", "Hot-tail /api/ledger/entries response is missing a valid proposer batchSignature");
1595
1675
  }
1596
1676
  /**
@@ -1670,7 +1750,7 @@ var FollowerSyncService = class {
1670
1750
  publicKeyOrVerifier: coldVerifyAnchor,
1671
1751
  requireSignature: !importOpts.allowUnauthenticated,
1672
1752
  allowUnauthenticated: importOpts.allowUnauthenticated
1673
- }).catch(() => null);
1753
+ }).catch(coldLookupMiss);
1674
1754
  if (seg && seg.chainId === this.chainId) targetCp = seg.checkpoint;
1675
1755
  }
1676
1756
  if (!targetCp) return markUnauthenticatedPeerError(new CustomError(cpRes && cpRes.status === 200 ? "UPSTREAM_BAD_RESPONSE" : "UPSTREAM_UNAVAILABLE", `Upstream checkpoint #${nextHeight} unavailable or failed hash-chain verification before buffered commit`));
@@ -1724,7 +1804,7 @@ var FollowerSyncService = class {
1724
1804
  for (let i = 0; i < segEntries.length; i++) {
1725
1805
  const entry = segEntries[i];
1726
1806
  const expectedSeq = targetCp.prevSequence + 1 + i;
1727
- if (entry.sequence !== expectedSeq || entry.chainId !== this.chainId || !entry.finalized) return markUnauthenticatedPeerError(new CustomError("LEDGER_DIVERGENCE", `Buffered pre-commit checkpoint #${nextHeight} invalid entry at seq=${entry.sequence}`));
1807
+ if (entry.sequence !== expectedSeq || !isReplayEntryChainIdAcceptable(entry, this.chainId) || !entry.finalized) return markUnauthenticatedPeerError(new CustomError("LEDGER_DIVERGENCE", `Buffered pre-commit checkpoint #${nextHeight} invalid entry at seq=${entry.sequence}`));
1728
1808
  if (!hashRun.check(entry).ok) return markUnauthenticatedPeerError(new CustomError("LEDGER_DIVERGENCE", `Buffered pre-commit checkpoint #${nextHeight} entryHash mismatch at seq=${entry.sequence}`));
1729
1809
  tree.append(entry.entryHash);
1730
1810
  }
@@ -1782,7 +1862,7 @@ var FollowerSyncService = class {
1782
1862
  const pageLimit = Math.min(MAX_HOT_TAIL_LIMIT, targetCp.sequence - cursor + 1);
1783
1863
  const entriesRes = await this.fetchAllowlistedJson(targetBaseUrl, `/api/ledger/entries?from=${cursor}&limit=${pageLimit}`, ENTRIES_MAX_RESPONSE_BYTES);
1784
1864
  if (entriesRes.status === 410 && this.coldArchiveStore) {
1785
- if (await this.catchUpFromColdSegments(nextHeight) > 0) {
1865
+ if (await this.coldCatchUpAfterPrune(nextHeight) > 0) {
1786
1866
  localCp = await this.resolver.ledger.getCheckpoint();
1787
1867
  localHeight = localCp?.height ?? 0;
1788
1868
  localSeq = await this.resolver.ledger.getLatestSequence();
@@ -1795,7 +1875,8 @@ var FollowerSyncService = class {
1795
1875
  for (const item of batch) {
1796
1876
  if (item.sequence > targetCp.sequence) break;
1797
1877
  if (item.sequence !== cursor) throw new CustomError("INVALID_LEDGER_ENTRY", `Non-contiguous entry sequence at height ${nextHeight}: expected ${cursor}, got ${item.sequence}`);
1798
- this.replayer.validateWireEntry(item);
1878
+ this.replayer.validateWireEntry(item, { skipFutureTimestampCheck: true });
1879
+ assertReplayEntryChainIdAcceptable(item, this.chainId, "HotStuff QC segment");
1799
1880
  segmentEntries.push(item);
1800
1881
  cursor++;
1801
1882
  }
@@ -1818,6 +1899,7 @@ var FollowerSyncService = class {
1818
1899
  requireSignature: !importOpts.allowUnauthenticated,
1819
1900
  allowUnauthenticated: importOpts.allowUnauthenticated
1820
1901
  });
1902
+ for (const item of segmentEntries) this.replayer.assertEntryTimestampNotInFuture(item);
1821
1903
  let mutatedLocalDb = false;
1822
1904
  try {
1823
1905
  if (segmentEntries.length > 0 && typeof this.resolver.statedb.runWithinDryRunSession === "function") {
@@ -2140,8 +2222,10 @@ var FollowerSyncService = class {
2140
2222
  if (await this.catchUpFromColdSegments(upstreamStatus.latestCheckpoint?.height, verifiedHeadCp) > 0) mutatedLocalDbOnPeer = true;
2141
2223
  } catch (coldErr) {
2142
2224
  if (isFatalVerificationFailure(coldErr) || coldErr?.mutatedLocalDbTransientLock === true) throw coldErr;
2225
+ if (coldImportsBefore(coldErr) > 0) mutatedLocalDbOnPeer = true;
2143
2226
  this.resolver.logger.warn("Cold archive segment unavailable or unverified; falling back to hot-tail sync", {
2144
2227
  chainId: this.chainId,
2228
+ ...this.coldArchiveStore?.isDaSegmentReader === true ? { imported: coldImportsBefore(coldErr) } : {},
2145
2229
  error: coldErr instanceof Error ? coldErr.message : String(coldErr)
2146
2230
  });
2147
2231
  }
@@ -2214,7 +2298,7 @@ var FollowerSyncService = class {
2214
2298
  const entriesRes = await this.fetchAllowlistedJson(targetBaseUrl, `/api/ledger/entries?from=${from}&limit=${MAX_HOT_TAIL_LIMIT}`, ENTRIES_MAX_RESPONSE_BYTES);
2215
2299
  if (entriesRes.status === 410) {
2216
2300
  if (this.coldArchiveStore && bufferedTailBatches.length === 0) {
2217
- const imported = await this.catchUpFromColdSegments(upstreamStatus.latestCheckpoint?.height, verifiedHeadCp);
2301
+ const imported = await this.coldCatchUpAfterPrune(upstreamStatus.latestCheckpoint?.height, verifiedHeadCp);
2218
2302
  localSeq = await this.resolver.ledger.getLatestSequence();
2219
2303
  cursorSeq = localSeq;
2220
2304
  if (imported > 0) mutatedLocalDbOnPeer = true;
@@ -2449,4 +2533,4 @@ var FollowerSyncService = class {
2449
2533
  };
2450
2534
 
2451
2535
  //#endregion
2452
- export { DEFAULT_FOLLOWER_HTTP_TIMEOUT_MS, DEFAULT_FOLLOWER_MAX_SYNC_LAG, DEFAULT_FOLLOWER_MAX_UPSTREAM_STALE_MS, DEFAULT_FOLLOWER_POLL_INTERVAL_MS, FollowerSyncService, isTransientSqliteLockError };
2536
+ export { DEFAULT_FOLLOWER_HTTP_TIMEOUT_MS, DEFAULT_FOLLOWER_MAX_SYNC_LAG, DEFAULT_FOLLOWER_MAX_UPSTREAM_STALE_MS, DEFAULT_FOLLOWER_POLL_INTERVAL_MS, FollowerSyncService, catchUpAfterPrune, coldImportsBefore, coldLookupMiss, isTransientSqliteLockError, noteColdImports };
package/esm/hooks.mjs CHANGED
@@ -1,8 +1,8 @@
1
1
  import { name } from "./package.mjs";
2
2
  import { BN } from "@ocap/util";
3
+ import merge from "lodash/merge.js";
3
4
  import { toStakeAddress } from "@arcblock/did-util";
4
5
  import createDebug from "debug";
5
- import merge from "lodash/merge.js";
6
6
  import pick from "lodash/pick.js";
7
7
 
8
8
  //#region src/hooks.ts
package/esm/index.mjs CHANGED
@@ -18,6 +18,7 @@ import { fromPublicKey, isValid, toTypeInfo } from "@arcblock/did";
18
18
  import { BN, fromTokenToUnit, toAddress, toBN } from "@ocap/util";
19
19
  import { CustomError } from "@ocap/util/lib/error";
20
20
  import * as states from "@ocap/state";
21
+ import cloneDeep from "lodash/cloneDeep.js";
21
22
  import { toStakeAddress } from "@arcblock/did-util";
22
23
  import createDebug from "debug";
23
24
  import pick from "lodash/pick.js";
@@ -29,7 +30,6 @@ import { decodeAnySafe } from "@ocap/tx-protocols/lib/util";
29
30
  import { DEFAULT_TOKEN_DECIMAL } from "@ocap/util/lib/constant";
30
31
  import { stripDefaultDepositV2BridgeFields } from "@ocap/util/lib/deposit-v2-bridge-fields";
31
32
  import { md5 } from "@ocap/util/lib/md5";
32
- import cloneDeep from "lodash/cloneDeep.js";
33
33
  import get from "lodash/get.js";
34
34
  import isEmpty from "lodash/isEmpty.js";
35
35
  import isEqual from "lodash/isEqual.js";
@@ -4,7 +4,7 @@ import * as crypto from "node:crypto";
4
4
  import * as dns from "node:dns";
5
5
  import * as net from "node:net";
6
6
  import { isValid } from "@arcblock/did";
7
- import { resolveClientIp } from "@ocap/util/lib/client-ip";
7
+ import { getTrustedClientIpHeaders, resolveClientIp } from "@ocap/util/lib/client-ip";
8
8
 
9
9
  //#region src/node-preferences.ts
10
10
  /**
@@ -826,8 +826,9 @@ var NodePreferencesManager = class {
826
826
  * socket address alone would put all clients in one bucket; `resolveClientIp` reads the trusted proxy header
827
827
  * (`CHAIN_CLIENT_IP_HEADERS`, default `x-real-ip`) only from a loopback peer and ignores them from a remote one (#1922, trust rule in `@ocap/util/lib/client-ip`).
828
828
  */
829
- function extractClientIp(req) {
830
- return resolveClientIp(req) || "unknown";
829
+ function extractClientIp(req, env) {
830
+ const headers = env !== void 0 ? getTrustedClientIpHeaders(env.CHAIN_CLIENT_IP_HEADERS) : void 0;
831
+ return resolveClientIp(req, headers !== void 0 ? { headers } : void 0) || "unknown";
831
832
  }
832
833
  function extractProvidedAdminToken(req) {
833
834
  const headers = req.headers || {};
@@ -919,7 +920,7 @@ function createAdminAuthGuard(options = {}) {
919
920
  const isGatewayNonAdminBearerOnly = Boolean(req.user) && !hasAdminSpecificHeader;
920
921
  if (hasExplicitAuthHeader && !isGatewayNonAdminBearerOnly) {
921
922
  const now = Date.now();
922
- const ip = extractClientIp(req);
923
+ const ip = extractClientIp(req, env);
923
924
  if (!isRateLimited(ip, now).limited) recordFailure(ip, now);
924
925
  }
925
926
  return false;
@@ -933,7 +934,7 @@ function createAdminAuthGuard(options = {}) {
933
934
  if (timingSafeTokenEqual(expected, token)) return "admin";
934
935
  if (Boolean(req.user) && !hasAdminSpecificHeader) return "anonymous";
935
936
  const now = Date.now();
936
- const ip = extractClientIp(req);
937
+ const ip = extractClientIp(req, env);
937
938
  const rate = isRateLimited(ip, now);
938
939
  if (rate.limited) {
939
940
  res.setHeader("Retry-After", String(rate.retryAfterSec));
@@ -993,7 +994,7 @@ function createAdminAuthGuard(options = {}) {
993
994
  return;
994
995
  }
995
996
  const now = Date.now();
996
- const ip = extractClientIp(req);
997
+ const ip = extractClientIp(req, env);
997
998
  const rate = isRateLimited(ip, now);
998
999
  if (rate.limited) {
999
1000
  res.setHeader("Retry-After", String(rate.retryAfterSec));
@@ -31,6 +31,24 @@ interface IDryRunVerifyEntriesOptions {
31
31
  /** Entries come from the local ledger (crash reconciliation), not from a peer: skip the future-timestamp guard. */
32
32
  skipFutureTimestampCheck?: boolean;
33
33
  }
34
+ /**
35
+ * Cross-layer chainId rule for executable replay (#2029, #2039):
36
+ * Own-chain entries (`entry.chainId === expectedChainId`) are accepted directly; a self-declared foreign-`chainId`
37
+ * wire entry (`isEntryChainIdAcceptable(entry, expectedChainId)`) can ONLY execute as a force-finalized orphan
38
+ * (`(entry.stateCommitHash ?? '').trim() === ''`), because `VerifyTx` rejects `chainId !== config.chainId` before
39
+ * `PrepareState`/`CommitState` so a foreign-`chainId` entry can never commit state.
40
+ */
41
+ declare function isReplayEntryChainIdAcceptable(entry: {
42
+ chainId?: string | null;
43
+ txRaw: string;
44
+ stateCommitHash?: string | null;
45
+ }, expectedChainId: string): boolean;
46
+ declare function assertReplayEntryChainIdAcceptable(entry: {
47
+ sequence?: unknown;
48
+ chainId?: string | null;
49
+ txRaw: string;
50
+ stateCommitHash?: string | null;
51
+ }, expectedChainId: string, prefix?: string): void;
34
52
  interface IValidateWireEntryOptions {
35
53
  /** Entries come from the local ledger (crash reconciliation), not from a peer: skip the future-timestamp guard. */
36
54
  skipFutureTimestampCheck?: boolean;
@@ -93,6 +111,19 @@ declare class LedgerEntryReplayer {
93
111
  */
94
112
  validateWireEntry(entry: ILedgerEntry, options?: IValidateWireEntryOptions): void;
95
113
  private authenticateAndDecodeEntry;
114
+ /**
115
+ * Synchronously run `pipes.DecodeTx` + `pipes.DecodeItx` on a force-finalized orphan entry (`stateCommitHash === ''`)
116
+ * so any wire byte ceiling, non-canonical `signatures[].data` JSON, undecodable nested Any, or missing `itx` is
117
+ * caught as a peer-disqualifying `INVALID_LEDGER_ENTRY` BEFORE `importSegment` / `appendVerifiedEntryToLedger`
118
+ * mutates `ledger.sqlite` (#2039).
119
+ */
120
+ private decodeOrphanEntryContext;
121
+ /**
122
+ * Index a rejected-but-ledgered entry (finalized, no stateCommitHash) with the row the leader wrote for it: the
123
+ * leader's `sendTx` passes the context of its `DecodeTx` + `DecodeItx` pipes to `_indexRejectedLedgerTx`, so the
124
+ * follower builds that context from the entry's txRaw with the same pipes and the time pinned to the entry
125
+ * (#1875). Only the rejection code differs: it is not in the ledger, so the row says `ORPHAN_LEDGER_ENTRY`.
126
+ */
96
127
  private indexOrphanEntry;
97
128
  /**
98
129
  * Replay a single finalized `ILedgerEntry` sequentially (`concurrency = 1`).
@@ -104,11 +135,17 @@ declare class LedgerEntryReplayer {
104
135
  * and post-execution `_state_commit` hash with zero mutations to `statedb`, `trusted`, `indexdb`, or `ledger`.
105
136
  */
106
137
  dryRunVerifyEntries(entries: ILedgerEntry[], options?: IDryRunVerifyEntriesOptions): Promise<IDryRunVerifyEntriesResult>;
138
+ /** Upper-cased hashes of `entries` that neither `indexdb.tx` nor `statedb.tx` holds (one `$in` count per page). */
139
+ private hashesMissingFromIndex;
107
140
  /**
108
- * Scan existing local ledger entries in `[fromSeq, toSeq]` and ensure any force-finalized
109
- * orphan entries (`stateCommitHash === ''`) are indexed into `indexdb.tx` after `rebuildIndex()`.
141
+ * After `rebuildIndex()`, index the force-finalized orphan entries of `[fromSeq, toSeq]` that the index does not
142
+ * have yet. An orphan is an entry without a `stateCommitHash` (its tx never reached the statedb, so the build
143
+ * from the statedb cannot see it) whose tx is in neither `indexdb.tx` nor `statedb.tx`. Entries the index already
144
+ * holds are skipped before any decoding: beta's ledger starts with 434k migrated entries without a
145
+ * `stateCommitHash` and in a legacy entry shape, all indexed by the build (#1875). Every entry that is processed
146
+ * is authenticated as before and fails closed.
110
147
  */
111
148
  indexExistingOrphanEntries(fromSeq?: number, toSeq?: number): Promise<number>;
112
149
  }
113
150
  //#endregion
114
- export { FUTURE_LEDGER_ENTRY_TIMESTAMP, IDryRunVerifyEntriesOptions, IDryRunVerifyEntriesResult, IFutureTimestampGuardOptions, IFutureTimestampRejection, ILedgerEntryReplayerOptions, IReplayEntryOptions, IReplayEntryResult, IReplayerResolverTarget, IValidateWireEntryOptions, LedgerEntryReplayer };
151
+ export { FUTURE_LEDGER_ENTRY_TIMESTAMP, IDryRunVerifyEntriesOptions, IDryRunVerifyEntriesResult, IFutureTimestampGuardOptions, IFutureTimestampRejection, ILedgerEntryReplayerOptions, IReplayEntryOptions, IReplayEntryResult, IReplayerResolverTarget, IValidateWireEntryOptions, LedgerEntryReplayer, assertReplayEntryChainIdAcceptable, isReplayEntryChainIdAcceptable };