nautechsystems/nautilus_trader · error
Finalized block timestamp overflows nanoseconds
Error message
Finalized block timestamp overflows nanoseconds
What it means
The verified inclusion block's timestamp (seconds) is converted to nanoseconds for the swap event's ts_init. checked_mul fails when the seconds value overflows the nanosecond integer range, so the library refuses to construct the swap with a corrupt timestamp rather than emitting an event with an invalid time.
Solutions
- Confirm the header source reports timestamp in seconds and convert ms/ns inputs before verification
- Re-fetch the block header from a trusted endpoint; an overflow-level timestamp indicates corrupted upstream data
- Sanitize/validate timestamp <= i64::MAX / 1_000_000_000 before invoking the verification API
- Keep the header and receipt from the same provider so units and values are consistent
Example fix
// before
let timestamp_ns = block.timestamp.checked_mul(NANOSECONDS_IN_SECOND)?;
// after
let secs = if block.timestamp > 253_402_300_800 { block.timestamp / 1000 } else { block.timestamp };
let timestamp_ns = secs.checked_mul(NANOSECONDS_IN_SECOND)?; Defensive patterns
Strategy: validation
Validate before calling
const MAX_TS_SECS: u64 = (i64::MAX as u64) / 1_000_000_000;
if block.timestamp > MAX_TS_SECS { return Err(anyhow!("block timestamp {} out of range", block.timestamp)); } Type guard
fn ts_fits_nanos(ts: u64) -> bool { ts <= (i64::MAX as u64) / 1_000_000_000 } Try / catch
let ts_ns = block.timestamp.checked_mul(NANOSECONDS_IN_SECOND)
.ok_or_else(|| { log::error!("timestamp overflow: {}", block.timestamp); anyhow!("overflow") })?; Prevention
- Validate header timestamps are in seconds at the provider boundary
- Reject implausible timestamps (before genesis or far in the future) early
- Use checked arithmetic for all timestamp scaling
- Keep header and receipt sources consistent in units
When it happens
Trigger: Verifying a finalized swap whose inclusion_header.timestamp is anomalously large (ms/ns instead of seconds, sentinel u64 max, or corrupted header from a faulty provider), making timestamp * 1e9 exceed the integer bound.
Common situations: Provider returning millisecond timestamps; mocked headers with placeholder timestamps in tests; a hardfork or L2 sequencer quirk producing an out-of-range timestamp; mixing header sources with different timestamp units.
Understand the failure class
Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.
Related errors
- Verified inclusion timestamp exceeds nanoseconds
- Binance timestamp is outside the UnixNanos range
- Derived minimum output is zero for quoted output
- Executed amount scaling overflow
- Finalized transaction gas commission overflow
AI-assisted analysis of nautechsystems/nautilus_trader@18893faf8b (2026-09-08).
Data as JSON: /api/errors/46935283d2970b51.
Report an issue: GitHub.
Appendix: source
Thrown at crates/adapters/blockchain/src/execution/client.rs:4812
raw_amount_to_quantity(
base_amount.unsigned_abs(),
plan.pool.get_base_token().decimals,
)?
}
};
let block = &included.finality.inclusion_header;
anyhow::ensure!(
block.number == included.block_number
&& block.hash == included.receipt.block_hash.to_string(),
"Verified inclusion header {} does not match receipt hash {}",
included.block_number,
included.receipt.block_hash
);
let timestamp_ns = block
.timestamp
.checked_mul(NANOSECONDS_IN_SECOND)
.ok_or_else(|| anyhow::anyhow!("Finalized block timestamp overflows nanoseconds"))?;
let mut swap = event.to_pool_swap(
plan.pool.chain.clone(),
plan.instrument_id,
plan.pool.pool_identifier,
UnixNanos::from(timestamp_ns),
);
swap.calculate_trade_info(&plan.pool.token0, &plan.pool.token1, None)?;
let trade = swap
.trade_info
.as_ref()
.ok_or_else(|| anyhow::anyhow!("Finalized Swap has no calculated trade information"))?;
anyhow::ensure!(
trade.order_side == plan.order.order_side(),
"Finalized Swap side {} does not match {} order",
trade.order_side,
plan.order.order_side()
);
let gas_cost = includedView on GitHub (pinned to 18893faf8b)