nautechsystems/nautilus_trader · error

Finalized transaction gas commission overflow

Error message

Finalized transaction gas commission overflow

What it means

When computing the realized gas commission, the adapter multiplies the receipt's `effective_gas_price` by `gas_used` using checked U256 arithmetic. This error is thrown when that multiplication overflows U256, so the gas cost cannot be represented and the commission cannot be computed safely. It is a defensive arithmetic guard preventing an silently-wrapped gas value.

Solutions

1. Verify the RPC endpoint returns standard-conforming receipt fields (effective_gas_price, gas_used) for the connected chain
2. Re-fetch the receipt from a trusted node to rule out malformed data
3. Check the chain is one supported by the adapter (gas unit semantics match)
4. If legitimate values are truly huge, restructure to compute commission with checked per-component math or a wider type before converting to Money

Example fix

// before
let gas_cost = effective_gas_price.checked_mul(U256::from(gas_used))
    .ok_or_else(|| anyhow::anyhow!("Finalized transaction gas commission overflow"))?;
// after: sanity-check inputs first
anyhow::ensure!(gas_used <= 30_000_000, "implausible gas_used {}", gas_used);
anyhow::ensure!(effective_gas_price <= U256::from(1_000_000_000_000_000_000u64), "implausible gas price");
let gas_cost = effective_gas_price.checked_mul(U256::from(gas_used))
    .ok_or_else(|| anyhow::anyhow!("Finalized transaction gas commission overflow"))?;

// before trusting receipt values
ensure!(included.receipt.gas_used > 0 && included.receipt.gas_used <= 30_000_000, "implausible gas_used");
ensure!(included.receipt.effective_gas_price <= U256::from(1_000_000_000_000_000_000u64), "implausible gas price");

fn plausible_receipt(r: &TransactionReceipt) -> bool {
    r.gas_used > 0 && r.gas_used <= 30_000_000 && r.effective_gas_price <= U256::from(1_000_000_000_000_000_000u64)
}

let gas_cost = match effective_gas_price.checked_mul(U256::from(gas_used)) {
    Some(c) => c,
    None => {
        log::error!("gas commission overflow: verify receipt from a trusted RPC");
        return Err(anyhow::anyhow!("gas commission overflow"));
    }
};

When it happens

Trigger: A transaction receipt with an absurdly large `effective_gas_price` (e.g. post-EIP-1559 fields misparsed, or a chain reporting wei-scale values in a wrong unit) combined with `gas_used` such that `effective_gas_price * gas_used >= 2^256`.

Common situations: Adapter connected to a non-standard or misconfigured RPC whose receipt fields are malformed; chains with inflated base fees during extreme congestion producing very large prices combined with huge gas usage; parsing receipts from an incompatible chain (different units or field semantics).

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

• Estimated gas with bps buffer ( ) exceeds gas limit
• Active execution intent
• Cannot increment time beyond u64::MAX
• Cannot represent durations greater than 584 years
• commission calculation overflow

AI-assisted analysis of nautechsystems/nautilus_trader@18893faf8b (2026-09-08). Data as JSON: /api/errors/5f4094df20ae438f. Report an issue: GitHub.

Appendix: source

Thrown at crates/adapters/blockchain/src/execution/client.rs:4834

        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
        .receipt
        .effective_gas_price
        .checked_mul(U256::from(included.receipt.gas_used))
        .ok_or_else(|| anyhow::anyhow!("Finalized transaction gas commission overflow"))?;
    let commission = Money::from_u256(gas_cost, plan.pool.chain.native_currency())?;
    let trade_digest = keccak256(format!("{}:{}", included.tx_hash, swap.log_index));
    let trade_digest = trade_digest.to_string();
    let trade_id = TradeId::new_checked(&trade_digest[2..38])?;

    if plan
        .order
        .trade_ids()
        .iter()
        .any(|existing| **existing == trade_id)
    {
        return Ok(None);
    }

    let venue_order_id = VenueOrderId::new_checked(included.tx_hash.to_string())?;
    let ts_event = UnixNanos::from(timestamp_ns);
    let last_px = match plan.order.order_side() {
        OrderSide::Buy => fill_price_from_quote(last_qty, plan.amount_in, plan.quote_currency)?,

View on GitHub (pinned to 18893faf8b)