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

  1. Confirm the header source reports timestamp in seconds and convert ms/ns inputs before verification
  2. Re-fetch the block header from a trusted endpoint; an overflow-level timestamp indicates corrupted upstream data
  3. Sanitize/validate timestamp <= i64::MAX / 1_000_000_000 before invoking the verification API
  4. 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

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


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 = included

View on GitHub (pinned to 18893faf8b)