@ocap/resolver 1.32.0 → 1.32.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
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") {
@@ -1,5 +1,5 @@
1
1
  import { DnsLookupAllFn } from "./node-preferences.mjs";
2
- import { IReplayerResolverTarget, LedgerEntryReplayer } from "./replayer.mjs";
2
+ import { IFutureTimestampRejection, IReplayerResolverTarget, LedgerEntryReplayer } from "./replayer.mjs";
3
3
  import { ICheckpointSignerWallet } from "@arcblock/ledger-core";
4
4
  import { IFollowerStatusResponse, IHotStuffClusterConfig, ILedgerArchiveHead, ILedgerSegment, INodeRuntimeAdapter, IResolverContext, TFollowerSyncMode, TNodeRetentionMode, TNodeRole, TNodeWritePolicy } from "@ocap/types";
5
5
 
@@ -90,6 +90,15 @@ interface FollowerSyncServiceOptions {
90
90
  fetchImpl?: typeof fetch;
91
91
  dnsLookup?: DnsLookupAllFn;
92
92
  env?: Record<string, string | undefined>;
93
+ /**
94
+ * #1961: refuse (retryably) peer entries with `sequence >= activationSequence` whose timestamp is more than
95
+ * `maxSkewMs` ahead of `now()`. Unset (default): no guard, today's behavior.
96
+ */
97
+ futureTimestampGuard?: {
98
+ activationSequence: number;
99
+ maxSkewMs: number;
100
+ now?: () => number;
101
+ };
93
102
  }
94
103
  declare function isTransientSqliteLockError(err: unknown): boolean;
95
104
  declare class FollowerSyncService implements INodeRuntimeAdapter {
@@ -129,6 +138,8 @@ declare class FollowerSyncService implements INodeRuntimeAdapter {
129
138
  private stopped;
130
139
  private halted;
131
140
  private haltReason;
141
+ private futureTimestampRejections;
142
+ private lastFutureTimestampRejection;
132
143
  private pendingCrashWindowReconcile;
133
144
  private initialCrashReconcileCompleted;
134
145
  private upstreamSequence;
@@ -185,6 +196,12 @@ declare class FollowerSyncService implements INodeRuntimeAdapter {
185
196
  * reading untrusted upstream `segmentEntries` (#1711).
186
197
  */
187
198
  private resolveLocalFraudAlertStateRoot;
199
+ private recordFutureTimestampRejection;
200
+ /** #1961: how many peer entries were refused for a future timestamp, and the last one (for alerting/tests). */
201
+ getFutureTimestampRejections(): {
202
+ count: number;
203
+ last: IFutureTimestampRejection | null;
204
+ };
188
205
  getFollowerStatus(): Promise<IFollowerStatusResponse>;
189
206
  private isAllowedHotStuffValidator;
190
207
  private hasCommittedTrustAnchor;
package/esm/follower.mjs CHANGED
@@ -1,5 +1,5 @@
1
1
  import { createFollowerPeerFetchGuard } from "./node-preferences.mjs";
2
- import { LedgerEntryReplayer } from "./replayer.mjs";
2
+ import { FUTURE_LEDGER_ENTRY_TIMESTAMP, LedgerEntryReplayer } 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";
@@ -144,7 +144,8 @@ const UPSTREAM_OR_TRANSPORT_ERROR_CODES = new Set([
144
144
  "COLD_SEGMENT_CHAIN_MISMATCH",
145
145
  "INVALID_LEDGER_ENTRY",
146
146
  "UNFINALIZED_LEDGER_ENTRY",
147
- "HTTP_ARCHIVE_ERROR"
147
+ "HTTP_ARCHIVE_ERROR",
148
+ FUTURE_LEDGER_ENTRY_TIMESTAMP
148
149
  ]);
149
150
  function sanitizeUntrustedWireToken(value, maxLen = 128) {
150
151
  return String(value ?? "").replace(/[\r\n\t\x00-\x1f\x7f]+/g, " ").trim().slice(0, maxLen);
@@ -237,6 +238,8 @@ var FollowerSyncService = class {
237
238
  this.stopped = false;
238
239
  this.halted = false;
239
240
  this.haltReason = null;
241
+ this.futureTimestampRejections = 0;
242
+ this.lastFutureTimestampRejection = null;
240
243
  this.pendingCrashWindowReconcile = false;
241
244
  this.initialCrashReconcileCompleted = false;
242
245
  this.upstreamSequence = null;
@@ -253,7 +256,10 @@ var FollowerSyncService = class {
253
256
  this.writePolicy = options.writePolicy;
254
257
  this.syncMode = options.syncMode;
255
258
  this.chainId = options.resolver.config.chainId || options.resolver.ledger.chainId;
256
- this.replayer = new LedgerEntryReplayer(options.resolver);
259
+ this.replayer = new LedgerEntryReplayer(options.resolver, options.futureTimestampGuard ? { futureTimestampGuard: {
260
+ ...options.futureTimestampGuard,
261
+ onReject: (info) => this.recordFutureTimestampRejection(info)
262
+ } } : {});
257
263
  const retentionMode = options.retentionMode ?? "archive";
258
264
  if (retentionMode !== "archive" && retentionMode !== "tiered") throw new CustomError("INVALID_CONFIG", `Invalid retentionMode "${String(retentionMode)}": expected "archive" or "tiered"`);
259
265
  if (retentionMode === "tiered" && !options.coldArchiveStore) throw new CustomError("INVALID_CONFIG", "FollowerSyncService with retentionMode=\"tiered\" requires coldArchiveStore");
@@ -530,6 +536,17 @@ var FollowerSyncService = class {
530
536
  if (liveCommit && liveCommit !== "UNKNOWN" && liveCommit !== "GENESIS") return liveCommit;
531
537
  return localCp?.stateRoot ?? null;
532
538
  }
539
+ recordFutureTimestampRejection(info) {
540
+ this.futureTimestampRejections++;
541
+ this.lastFutureTimestampRejection = { ...info };
542
+ }
543
+ /** #1961: how many peer entries were refused for a future timestamp, and the last one (for alerting/tests). */
544
+ getFutureTimestampRejections() {
545
+ return {
546
+ count: this.futureTimestampRejections,
547
+ last: this.lastFutureTimestampRejection ? { ...this.lastFutureTimestampRejection } : null
548
+ };
549
+ }
533
550
  async getFollowerStatus() {
534
551
  const [localSequence, latestCp, localStateCommitHash, synced] = await Promise.all([
535
552
  this.resolver.ledger.getLatestSequence(),
@@ -1518,7 +1535,7 @@ var FollowerSyncService = class {
1518
1535
  if (entry.finalized !== true) throw new CustomError("UNFINALIZED_LEDGER_ENTRY", `Hot-tail entry seq=${entry.sequence} is not finalized`);
1519
1536
  if (!Number.isSafeInteger(entry.timestamp) || entry.timestamp < 0 || entry.timestamp > MAX_SAFE_EPOCH_MS) throw new CustomError("INVALID_LEDGER_ENTRY", `Hot-tail entry seq=${entry.sequence} has invalid timestamp: ${String(entry.timestamp)}`);
1520
1537
  if (typeof entry.txRaw !== "string" || !entry.txRaw || entry.txRaw !== entry.txRaw.trim()) throw new CustomError("INVALID_LEDGER_ENTRY", `Hot-tail entry seq=${entry.sequence} has missing or non-canonical txRaw`);
1521
- this.replayer.validateWireEntry(entry);
1538
+ this.replayer.validateWireEntry(entry, { skipFutureTimestampCheck: true });
1522
1539
  const expectedHash = computeEntryHash(entry.sequence, entry.txRaw, entry.stateCommitHash ?? "", entry.sequence >= v2Cutoff ? 2 : 1);
1523
1540
  if (entry.entryHash !== expectedHash) throw new CustomError("LEDGER_DIVERGENCE", `Hot-tail entryHash mismatch at seq=${entry.sequence}: expected ${expectedHash}, got ${entry.entryHash}`);
1524
1541
  entryHashes.push(entry.entryHash);
@@ -1546,6 +1563,7 @@ var FollowerSyncService = class {
1546
1563
  signatureRatchetLocked: true
1547
1564
  });
1548
1565
  }
1566
+ for (const entry of entries) this.replayer.assertEntryTimestampNotInFuture(entry);
1549
1567
  return batchParsedV2From;
1550
1568
  }
1551
1569
  const cp = upstreamStatus.latestCheckpoint;
@@ -1569,11 +1587,15 @@ var FollowerSyncService = class {
1569
1587
  signatureRatchetLocked: true
1570
1588
  });
1571
1589
  }
1590
+ for (const entry of entries) this.replayer.assertEntryTimestampNotInFuture(entry);
1572
1591
  return;
1573
1592
  }
1574
1593
  }
1575
1594
  }
1576
- if (importOpts.allowUnauthenticated && !entriesBody.batchSignature && !this.hotstuffClusterConfig) return batchParsedV2From ?? parsedV2From;
1595
+ if (importOpts.allowUnauthenticated && !entriesBody.batchSignature && !this.hotstuffClusterConfig) {
1596
+ for (const entry of entries) this.replayer.assertEntryTimestampNotInFuture(entry);
1597
+ return batchParsedV2From ?? parsedV2From;
1598
+ }
1577
1599
  throw new CustomError("HOT_TAIL_SIGNATURE_MISSING", "Hot-tail /api/ledger/entries response is missing a valid proposer batchSignature");
1578
1600
  }
1579
1601
  /**
@@ -1778,7 +1800,7 @@ var FollowerSyncService = class {
1778
1800
  for (const item of batch) {
1779
1801
  if (item.sequence > targetCp.sequence) break;
1780
1802
  if (item.sequence !== cursor) throw new CustomError("INVALID_LEDGER_ENTRY", `Non-contiguous entry sequence at height ${nextHeight}: expected ${cursor}, got ${item.sequence}`);
1781
- this.replayer.validateWireEntry(item);
1803
+ this.replayer.validateWireEntry(item, { skipFutureTimestampCheck: true });
1782
1804
  segmentEntries.push(item);
1783
1805
  cursor++;
1784
1806
  }
@@ -1801,6 +1823,7 @@ var FollowerSyncService = class {
1801
1823
  requireSignature: !importOpts.allowUnauthenticated,
1802
1824
  allowUnauthenticated: importOpts.allowUnauthenticated
1803
1825
  });
1826
+ for (const item of segmentEntries) this.replayer.assertEntryTimestampNotInFuture(item);
1804
1827
  let mutatedLocalDb = false;
1805
1828
  try {
1806
1829
  if (segmentEntries.length > 0 && typeof this.resolver.statedb.runWithinDryRunSession === "function") {
@@ -1891,7 +1914,7 @@ var FollowerSyncService = class {
1891
1914
  }
1892
1915
  async replayCrashWindowEntry(entry) {
1893
1916
  try {
1894
- this.replayer.validateWireEntry(entry);
1917
+ this.replayer.validateWireEntry(entry, { skipFutureTimestampCheck: true });
1895
1918
  const expectedCommit = (entry.stateCommitHash ?? "").trim();
1896
1919
  const v2Cutoff = typeof this.resolver.ledger.getEntryHashV2From === "function" ? this.resolver.ledger.getEntryHashV2From() : void 0;
1897
1920
  if (typeof v2Cutoff === "number" && !Number.isNaN(v2Cutoff)) {
@@ -2024,7 +2047,8 @@ var FollowerSyncService = class {
2024
2047
  if (!matchedBase && unappliedOrdered.length > 0 && unappliedOrdered[0].sequence === expectedDryRunPrevSeq + 1 && typeof this.resolver.statedb.runWithinDryRunSession === "function") {
2025
2048
  const dryRun = await this.replayer.dryRunVerifyEntries(unappliedOrdered, {
2026
2049
  expectedPrevSequence: expectedDryRunPrevSeq,
2027
- prevStateRoot: currentCommit
2050
+ prevStateRoot: currentCommit,
2051
+ skipFutureTimestampCheck: true
2028
2052
  }).catch((dryErr) => {
2029
2053
  if (isTransientSqliteLockError(dryErr)) throw dryErr;
2030
2054
  return null;
@@ -2380,7 +2404,13 @@ var FollowerSyncService = class {
2380
2404
  this.haltFailClosed(haltReason, errCode);
2381
2405
  throw err;
2382
2406
  }
2383
- this.resolver.logger.warn("FollowerSyncService transient sync error", {
2407
+ if (errCode === FUTURE_LEDGER_ENTRY_TIMESTAMP) this.resolver.logger.error(`FollowerSyncService refused a future-dated ledger entry (${errCode}); will retry`, {
2408
+ chainId: this.chainId,
2409
+ code: errCode,
2410
+ rejections: this.futureTimestampRejections,
2411
+ error: err instanceof Error ? err.message : String(err)
2412
+ });
2413
+ else this.resolver.logger.warn("FollowerSyncService transient sync error", {
2384
2414
  chainId: this.chainId,
2385
2415
  error: err instanceof Error ? err.message : String(err)
2386
2416
  });
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.d.mts CHANGED
@@ -3,7 +3,7 @@ import { CreateNodeDashboardRouterOptions, CreateUnifiedConsoleMiddlewareOptions
3
3
  import { IAddressArgs, IAssetState, IChainConfig, IChunkIterator, IDataObject, IDelegateState, IEvidenceState, IFilter as IFilter$1, IFollowerStatusResponse, IGetAccountStateArgs, IGetAccountTokensArgs, IGetStateParams, IIndexDB as IIndexDB$1, IListChunksParams, INodeRuntimeAdapter, IPaginatedResult, IPipelineLogger as IPipelineLogger$1, IResolver, IResolverAccountState, IResolverChainInfo, IResolverContext as IResolverContext$1, IResolverFactoryState, IResolverForgeStats, IResolverListAccountsResult, IResolverListAssetsResult, IResolverListDelegationsResult, IResolverListFactoriesResult, IResolverListRollupBlocksResult, IResolverListRollupValidatorsResult, IResolverListRollupsResult, IResolverListStakesResult, IResolverListTokenFactoriesResult, IResolverListTokensResult, IResolverListTransactionsResult, IResolverNetInfo, IResolverNodeInfo, IResolverPaging, IResolverParams, IResolverRollupState, IResolverStakeState, IResolverTransaction, IResolverValidatorsInfo, IRollupBlock, IStateDB as IStateDB$1, ITokenCache, ITokenFactoryState, ITokenFlowsResult, ITokenInfo, ITokenState, TIndexedTokenState as TIndexedTokenState$1, TRequestEstimateGas, TRequestGetEvidenceState, TRequestGetRollupBlock, TRequestGetTokenDistribution, TRequestGetTx, TRequestListAssetTransactions, TRequestListAssets, TRequestListDelegations, TRequestListFactories, TRequestListRollupBlocks, TRequestListRollupValidators, TRequestListRollups, TRequestListStakes, TRequestListTokenFactories, TRequestListTokenFlows, TRequestListTokens, TRequestListTopAccounts, TRequestListTransactions, TRequestSearch, TRequestVerifyAccountRisk, TSearchResult, TTokenDistribution, TVerifyAccountRiskResult } from "./types.mjs";
4
4
  import { CreateAPIHandlerOptions, ICreateAPIHandlerParams } from "./api.mjs";
5
5
  import { CreateExplorerMiddlewareOptions, createExplorerMiddleware, isExplorerEnabled } from "./explorer.mjs";
6
- import { IDryRunVerifyEntriesOptions, IDryRunVerifyEntriesResult, IReplayEntryOptions, IReplayEntryResult, IReplayerResolverTarget, LedgerEntryReplayer } from "./replayer.mjs";
6
+ import { FUTURE_LEDGER_ENTRY_TIMESTAMP, IDryRunVerifyEntriesOptions, IDryRunVerifyEntriesResult, IFutureTimestampGuardOptions, IFutureTimestampRejection, ILedgerEntryReplayerOptions, IReplayEntryOptions, IReplayEntryResult, IReplayerResolverTarget, IValidateWireEntryOptions, LedgerEntryReplayer } from "./replayer.mjs";
7
7
  import { DEFAULT_FOLLOWER_MAX_SYNC_LAG, DEFAULT_FOLLOWER_MAX_UPSTREAM_STALE_MS, DEFAULT_FOLLOWER_POLL_INTERVAL_MS, FollowerSyncService, FollowerSyncServiceOptions, IColdSegmentReader, ILeaderRouterLike, TFollowerUpstreamFetchInterceptor, TFollowerUpstreamFetchKind, isTransientSqliteLockError } from "./follower.mjs";
8
8
  import { ConsensusAbortError, HotStuffNodeRuntime, HotStuffNodeRuntimeOptions, IHotStuffNetworkInterceptorContext, IHotStuffRuntimeStateSnapshot, IHotStuffRuntimeStateStore, TConsensusAbortCode } from "./hotstuff-runtime.mjs";
9
9
  import { MigrationChainManager } from "./migration-chain.mjs";
@@ -350,4 +350,4 @@ declare class OCAPResolver implements IResolver {
350
350
  }): Promise<IChunkIterator<IResolverStakeState>>;
351
351
  }
352
352
  //#endregion
353
- export { type AdminAuthGuardOptions, ConsensusAbortError, type CreateAPIHandlerOptions, type CreateExplorerMiddlewareOptions, type CreateNodeDashboardRouterOptions, type CreateUnifiedConsoleMiddlewareOptions, DEFAULT_FOLLOWER_MAX_SYNC_LAG, DEFAULT_FOLLOWER_MAX_UPSTREAM_STALE_MS, DEFAULT_FOLLOWER_POLL_INTERVAL_MS, type DnsLookupAllFn, FollowerSyncService, type FollowerSyncServiceOptions, GRAPHQL_INDEXED_TX_COLUMNS, HotStuffNodeRuntime, type HotStuffNodeRuntimeOptions, type IAdminAuthGuard, type IAttributedBlockedAccount, type IAttributedReservedSymbol, type IAttributedTrustedAccount, type IBlockedAccountEntry, type IChainConfig, type IChunkIterator, type IColdSegmentReader, type ICreateAPIHandlerParams, type IDashboardResolverTarget, type IDataObject, type IDatabaseFileMetrics, type IDryRunVerifyEntriesOptions, type IDryRunVerifyEntriesResult, type IFollowerStatusResponse, type IHotStuffNetworkInterceptorContext, type IHotStuffRuntimeStateSnapshot, type IHotStuffRuntimeStateStore, type ILeaderRouterLike, type ILedgerHealthSummary, type ILedgerHealthThresholds, type ILegacyPreferencesResult, type INodeMaintenanceController, type INodeMaintenanceStatusSummary, type INodePreferencesFileSchema, type INodePreferencesSnapshot, type INodeRuntimeAdapter, type INodeRuntimePreferences, type IPaginatedResult, type IReplayEntryOptions, type IReplayEntryResult, type IReplayerResolverTarget, type IReservedSymbolEntry, type IResolverPaging, type IResolverParams, type IResolverTransaction, type ISlowStorageTelemetry, type ITokenInfo, type ITrustedAccountEntry, type IUpdateNodePreferencesInput, type IUpdateNodePreferencesResult, LedgerEntryReplayer, MAX_BLOCKED_ACCOUNTS, MAX_CONFIG_BODY_BYTES, MAX_MEMO_LENGTH, MAX_PEER_URLS, MAX_RESERVED_SYMBOLS, MAX_TRUSTED_ACCOUNTS, type NodeMaintenanceControllerOptions, NodePreferencesError, NodePreferencesManager, type NodePreferencesManagerOptions, type TConsensusAbortCode, type TFollowerUpstreamFetchInterceptor, type TFollowerUpstreamFetchKind, type TPreferenceSource, UNIFIED_CONSOLE_APP_JS, applyBootRuntimePreferences, buildUnifiedConsoleHtml, collectLedgerHealthSummary, createAdminAuthGuard, createExplorerMiddleware, createFollowerPeerFetchGuard, createNodeDashboardRouter, createNodeMaintenanceController, createUnifiedConsoleMiddleware, OCAPResolver as default, formatData, formatDelegationOps, isDashboardEnabled, isExplorerEnabled, isPrivateOrReservedIpAddress, isTransientSqliteLockError, isValidAccountAddressCandidate, loadNodePreferences, normalizeBlockedAccountKey, timingSafeTokenEqual, validateFollowerPeerUrls };
353
+ export { type AdminAuthGuardOptions, ConsensusAbortError, type CreateAPIHandlerOptions, type CreateExplorerMiddlewareOptions, type CreateNodeDashboardRouterOptions, type CreateUnifiedConsoleMiddlewareOptions, DEFAULT_FOLLOWER_MAX_SYNC_LAG, DEFAULT_FOLLOWER_MAX_UPSTREAM_STALE_MS, DEFAULT_FOLLOWER_POLL_INTERVAL_MS, type DnsLookupAllFn, FUTURE_LEDGER_ENTRY_TIMESTAMP, FollowerSyncService, type FollowerSyncServiceOptions, GRAPHQL_INDEXED_TX_COLUMNS, HotStuffNodeRuntime, type HotStuffNodeRuntimeOptions, type IAdminAuthGuard, type IAttributedBlockedAccount, type IAttributedReservedSymbol, type IAttributedTrustedAccount, type IBlockedAccountEntry, type IChainConfig, type IChunkIterator, type IColdSegmentReader, type ICreateAPIHandlerParams, type IDashboardResolverTarget, type IDataObject, type IDatabaseFileMetrics, type IDryRunVerifyEntriesOptions, type IDryRunVerifyEntriesResult, type IFollowerStatusResponse, type IFutureTimestampGuardOptions, type IFutureTimestampRejection, type IHotStuffNetworkInterceptorContext, type IHotStuffRuntimeStateSnapshot, type IHotStuffRuntimeStateStore, type ILeaderRouterLike, type ILedgerEntryReplayerOptions, type ILedgerHealthSummary, type ILedgerHealthThresholds, type ILegacyPreferencesResult, type INodeMaintenanceController, type INodeMaintenanceStatusSummary, type INodePreferencesFileSchema, type INodePreferencesSnapshot, type INodeRuntimeAdapter, type INodeRuntimePreferences, type IPaginatedResult, type IReplayEntryOptions, type IReplayEntryResult, type IReplayerResolverTarget, type IReservedSymbolEntry, type IResolverPaging, type IResolverParams, type IResolverTransaction, type ISlowStorageTelemetry, type ITokenInfo, type ITrustedAccountEntry, type IUpdateNodePreferencesInput, type IUpdateNodePreferencesResult, type IValidateWireEntryOptions, LedgerEntryReplayer, MAX_BLOCKED_ACCOUNTS, MAX_CONFIG_BODY_BYTES, MAX_MEMO_LENGTH, MAX_PEER_URLS, MAX_RESERVED_SYMBOLS, MAX_TRUSTED_ACCOUNTS, type NodeMaintenanceControllerOptions, NodePreferencesError, NodePreferencesManager, type NodePreferencesManagerOptions, type TConsensusAbortCode, type TFollowerUpstreamFetchInterceptor, type TFollowerUpstreamFetchKind, type TPreferenceSource, UNIFIED_CONSOLE_APP_JS, applyBootRuntimePreferences, buildUnifiedConsoleHtml, collectLedgerHealthSummary, createAdminAuthGuard, createExplorerMiddleware, createFollowerPeerFetchGuard, createNodeDashboardRouter, createNodeMaintenanceController, createUnifiedConsoleMiddleware, OCAPResolver as default, formatData, formatDelegationOps, isDashboardEnabled, isExplorerEnabled, isPrivateOrReservedIpAddress, isTransientSqliteLockError, isValidAccountAddressCandidate, loadNodePreferences, normalizeBlockedAccountKey, timingSafeTokenEqual, validateFollowerPeerUrls };
package/esm/index.mjs CHANGED
@@ -1,7 +1,7 @@
1
1
  import { MAX_BLOCKED_ACCOUNTS, MAX_CONFIG_BODY_BYTES, MAX_MEMO_LENGTH, MAX_PEER_URLS, MAX_RESERVED_SYMBOLS, MAX_TRUSTED_ACCOUNTS, NodePreferencesError, NodePreferencesManager, applyBootRuntimePreferences, createAdminAuthGuard, createFollowerPeerFetchGuard, isPrivateOrReservedIpAddress, isValidAccountAddressCandidate, loadNodePreferences, normalizeBlockedAccountKey, timingSafeTokenEqual, validateFollowerPeerUrls } from "./node-preferences.mjs";
2
2
  import { UNIFIED_CONSOLE_APP_JS, buildUnifiedConsoleHtml, collectLedgerHealthSummary, createNodeDashboardRouter, createNodeMaintenanceController, createUnifiedConsoleMiddleware, isDashboardEnabled } from "./dashboard.mjs";
3
3
  import { createExplorerMiddleware, isExplorerEnabled } from "./explorer.mjs";
4
- import { LedgerEntryReplayer } from "./replayer.mjs";
4
+ import { FUTURE_LEDGER_ENTRY_TIMESTAMP, LedgerEntryReplayer } from "./replayer.mjs";
5
5
  import { DEFAULT_FOLLOWER_MAX_SYNC_LAG, DEFAULT_FOLLOWER_MAX_UPSTREAM_STALE_MS, DEFAULT_FOLLOWER_POLL_INTERVAL_MS, FollowerSyncService, isTransientSqliteLockError } from "./follower.mjs";
6
6
  import { name } from "./package.mjs";
7
7
  import { onCreateRollup, onCreateRollupBlock, onCreateTx, onUpdateToken } from "./hooks.mjs";
@@ -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";
@@ -2653,4 +2653,4 @@ var OCAPResolver = class {
2653
2653
  };
2654
2654
 
2655
2655
  //#endregion
2656
- export { ConsensusAbortError, DEFAULT_FOLLOWER_MAX_SYNC_LAG, DEFAULT_FOLLOWER_MAX_UPSTREAM_STALE_MS, DEFAULT_FOLLOWER_POLL_INTERVAL_MS, FollowerSyncService, GRAPHQL_INDEXED_TX_COLUMNS, HotStuffNodeRuntime, LedgerEntryReplayer, MAX_BLOCKED_ACCOUNTS, MAX_CONFIG_BODY_BYTES, MAX_MEMO_LENGTH, MAX_PEER_URLS, MAX_RESERVED_SYMBOLS, MAX_TRUSTED_ACCOUNTS, NodePreferencesError, NodePreferencesManager, UNIFIED_CONSOLE_APP_JS, applyBootRuntimePreferences, buildUnifiedConsoleHtml, collectLedgerHealthSummary, createAdminAuthGuard, createExplorerMiddleware, createFollowerPeerFetchGuard, createNodeDashboardRouter, createNodeMaintenanceController, createUnifiedConsoleMiddleware, OCAPResolver as default, formatData, formatDelegationOps, isDashboardEnabled, isExplorerEnabled, isPrivateOrReservedIpAddress, isTransientSqliteLockError, isValidAccountAddressCandidate, loadNodePreferences, normalizeBlockedAccountKey, timingSafeTokenEqual, validateFollowerPeerUrls };
2656
+ export { ConsensusAbortError, DEFAULT_FOLLOWER_MAX_SYNC_LAG, DEFAULT_FOLLOWER_MAX_UPSTREAM_STALE_MS, DEFAULT_FOLLOWER_POLL_INTERVAL_MS, FUTURE_LEDGER_ENTRY_TIMESTAMP, FollowerSyncService, GRAPHQL_INDEXED_TX_COLUMNS, HotStuffNodeRuntime, LedgerEntryReplayer, MAX_BLOCKED_ACCOUNTS, MAX_CONFIG_BODY_BYTES, MAX_MEMO_LENGTH, MAX_PEER_URLS, MAX_RESERVED_SYMBOLS, MAX_TRUSTED_ACCOUNTS, NodePreferencesError, NodePreferencesManager, UNIFIED_CONSOLE_APP_JS, applyBootRuntimePreferences, buildUnifiedConsoleHtml, collectLedgerHealthSummary, createAdminAuthGuard, createExplorerMiddleware, createFollowerPeerFetchGuard, createNodeDashboardRouter, createNodeMaintenanceController, createUnifiedConsoleMiddleware, OCAPResolver as default, formatData, formatDelegationOps, isDashboardEnabled, isExplorerEnabled, isPrivateOrReservedIpAddress, isTransientSqliteLockError, isValidAccountAddressCandidate, loadNodePreferences, normalizeBlockedAccountKey, timingSafeTokenEqual, validateFollowerPeerUrls };
@@ -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));
@@ -28,6 +28,38 @@ interface IDryRunVerifyEntriesOptions {
28
28
  expectedPrevSequence?: number;
29
29
  prevStateRoot?: string | null;
30
30
  entryHashV2From?: number | 'infinity';
31
+ /** Entries come from the local ledger (crash reconciliation), not from a peer: skip the future-timestamp guard. */
32
+ skipFutureTimestampCheck?: boolean;
33
+ }
34
+ interface IValidateWireEntryOptions {
35
+ /** Entries come from the local ledger (crash reconciliation), not from a peer: skip the future-timestamp guard. */
36
+ skipFutureTimestampCheck?: boolean;
37
+ }
38
+ /** Error code of a replayed entry refused for a timestamp ahead of the local clock (retryable, never halting). */
39
+ declare const FUTURE_LEDGER_ENTRY_TIMESTAMP = "FUTURE_LEDGER_ENTRY_TIMESTAMP";
40
+ interface IFutureTimestampRejection {
41
+ sequence: number;
42
+ hash: string;
43
+ timestamp: number;
44
+ nowMs: number;
45
+ maxSkewMs: number;
46
+ activationSequence: number;
47
+ }
48
+ /**
49
+ * #1961: `entry.timestamp` is not covered by `entryHash`, so a leader can stamp a real entry with a future time
50
+ * (and with it every time lock the tx sets). A follower refuses peer entries at or after `activationSequence` whose
51
+ * timestamp is more than `maxSkewMs` ahead of its own clock. Past timestamps are always accepted (no monotonic
52
+ * rule, #1972). The refusal is retryable: the entry is accepted once the local clock catches up.
53
+ */
54
+ interface IFutureTimestampGuardOptions {
55
+ activationSequence: number;
56
+ maxSkewMs: number;
57
+ now?: () => number;
58
+ onReject?: (info: IFutureTimestampRejection) => void;
59
+ }
60
+ interface ILedgerEntryReplayerOptions {
61
+ /** Unset (default): no timestamp guard, today's behavior. */
62
+ futureTimestampGuard?: IFutureTimestampGuardOptions;
31
63
  }
32
64
  interface IDryRunVerifyEntriesResult {
33
65
  derivedStateRoot: string;
@@ -43,16 +75,30 @@ declare class LedgerEntryReplayer {
43
75
  private lastCommitMismatchError;
44
76
  private lastStorageError;
45
77
  private mutex;
46
- constructor(resolver: IReplayerResolverTarget);
78
+ private readonly futureTimestampGuard;
79
+ constructor(resolver: IReplayerResolverTarget, options?: ILedgerEntryReplayerOptions);
47
80
  private runExclusive;
48
81
  private appendVerifiedEntryToLedger;
49
82
  private verifyRawTxHashMatchesEntry;
83
+ /**
84
+ * #1961 future-timestamp guard (no-op unless `futureTimestampGuard` is configured). Throws a retryable
85
+ * `FUTURE_LEDGER_ENTRY_TIMESTAMP` that is neither a local divergence nor a peer authentication failure, so the
86
+ * follower logs it, keeps its state and retries on the next sync cycle.
87
+ */
88
+ assertEntryTimestampNotInFuture(entry: ILedgerEntry): void;
50
89
  /**
51
90
  * Pre-replay wire & primitive validation for untrusted network hot-tail / cold-segment payloads (#1710).
52
- * Throws `INVALID_LEDGER_ENTRY` (peer-disqualifying, non-halting) on any malformed wire field or lossy JSON coercion.
91
+ * Throws `INVALID_LEDGER_ENTRY` (peer-disqualifying, non-halting) on any malformed wire field or lossy JSON coercion,
92
+ * and the retryable `FUTURE_LEDGER_ENTRY_TIMESTAMP` when the #1961 guard is on (unless the entry is local).
53
93
  */
54
- validateWireEntry(entry: ILedgerEntry): void;
94
+ validateWireEntry(entry: ILedgerEntry, options?: IValidateWireEntryOptions): void;
55
95
  private authenticateAndDecodeEntry;
96
+ /**
97
+ * Index a rejected-but-ledgered entry (finalized, no stateCommitHash) with the row the leader wrote for it: the
98
+ * leader's `sendTx` passes the context of its `DecodeTx` + `DecodeItx` pipes to `_indexRejectedLedgerTx`, so the
99
+ * follower builds that context from the entry's txRaw with the same pipes and the time pinned to the entry
100
+ * (#1875). Only the rejection code differs: it is not in the ledger, so the row says `ORPHAN_LEDGER_ENTRY`.
101
+ */
56
102
  private indexOrphanEntry;
57
103
  /**
58
104
  * Replay a single finalized `ILedgerEntry` sequentially (`concurrency = 1`).
@@ -64,11 +110,17 @@ declare class LedgerEntryReplayer {
64
110
  * and post-execution `_state_commit` hash with zero mutations to `statedb`, `trusted`, `indexdb`, or `ledger`.
65
111
  */
66
112
  dryRunVerifyEntries(entries: ILedgerEntry[], options?: IDryRunVerifyEntriesOptions): Promise<IDryRunVerifyEntriesResult>;
113
+ /** Upper-cased hashes of `entries` that neither `indexdb.tx` nor `statedb.tx` holds (one `$in` count per page). */
114
+ private hashesMissingFromIndex;
67
115
  /**
68
- * Scan existing local ledger entries in `[fromSeq, toSeq]` and ensure any force-finalized
69
- * orphan entries (`stateCommitHash === ''`) are indexed into `indexdb.tx` after `rebuildIndex()`.
116
+ * After `rebuildIndex()`, index the force-finalized orphan entries of `[fromSeq, toSeq]` that the index does not
117
+ * have yet. An orphan is an entry without a `stateCommitHash` (its tx never reached the statedb, so the build
118
+ * from the statedb cannot see it) whose tx is in neither `indexdb.tx` nor `statedb.tx`. Entries the index already
119
+ * holds are skipped before any decoding: beta's ledger starts with 434k migrated entries without a
120
+ * `stateCommitHash` and in a legacy entry shape, all indexed by the build (#1875). Every entry that is processed
121
+ * is authenticated as before and fails closed.
70
122
  */
71
123
  indexExistingOrphanEntries(fromSeq?: number, toSeq?: number): Promise<number>;
72
124
  }
73
125
  //#endregion
74
- export { IDryRunVerifyEntriesOptions, IDryRunVerifyEntriesResult, IReplayEntryOptions, IReplayEntryResult, IReplayerResolverTarget, LedgerEntryReplayer };
126
+ export { FUTURE_LEDGER_ENTRY_TIMESTAMP, IDryRunVerifyEntriesOptions, IDryRunVerifyEntriesResult, IFutureTimestampGuardOptions, IFutureTimestampRejection, ILedgerEntryReplayerOptions, IReplayEntryOptions, IReplayEntryResult, IReplayerResolverTarget, IValidateWireEntryOptions, LedgerEntryReplayer };