nautechsystems/nautilus_trader · error

Minimum output derivation overflow

Error message

Minimum output derivation overflow

What it means

The client derives a swap's minimum acceptable output as quoted_amount_out * (BPS_DENOMINATOR - slippage_bps) / BPS_DENOMINATOR using checked arithmetic. This error is thrown when either the multiplication or the subsequent division overflows/cannot complete in U256, so a safe minimum output cannot be computed.

Solutions

  1. Reduce the trade size so quoted_amount_out fits after scaling
  2. Sanitize/validate the quote feed — reject quotes whose raw value is implausibly large
  3. Split the swap into multiple smaller swaps, or perform the bps scaling in a wider integer type before narrowing to U256

Example fix

// before
quoted_amount_out.checked_mul(U256::from(BPS_DENOMINATOR - slippage_bps))
// after
let factor = U256::from(BPS_DENOMINATOR - slippage_bps);
if quoted_amount_out > U256::MAX / factor { anyhow::bail!("quote too large for slippage scaling"); }
quoted_amount_out.checked_mul(factor)
Defensive patterns

Strategy: validation

Validate before calling

fn assert_min_out_derivable(quoted: U256, slippage_bps: u64) -> Result<(), String> {
    if slippage_bps >= BPS_DENOMINATOR { return Err("slippage must be < 10000 bps".into()); }
    let factor = U256::from(BPS_DENOMINATOR - slippage_bps);
    if quoted > U256::MAX / factor { return Err("quote too large for slippage scaling".into()); }
    if quoted * factor / U256::from(BPS_DENOMINATOR) == U256::zero() { return Err("min output rounds to zero".into()); }
    Ok(())
}

Try / catch

match client.build_swap(...) {
    Err(e) if e.to_string().contains("Minimum output derivation overflow") => { /* split trade or reject quote */ }
    other => other?,
}

Prevention

When it happens

Trigger: Building a swap transaction with a quoted_amount_out large enough that multiplying by (10000 - slippage_bps) overflows U256, while slippage_bps is itself valid (< 10000).

Common situations: Quoting extremely large trades (huge output amounts) on low-decimal tokens; a quoting feed returning a corrupted, near-U256-max amount; slippage configured so the multiplier is near the full 10000 bps with a maximal quote.

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/15dd3c7238fb835f. Report an issue: GitHub.

Appendix: source

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

    };

    if !amount.is_negative() {
        anyhow::bail!("Swap quote output amount {amount} is not a positive output");
    }
    Ok(amount.unsigned_abs())
}

/// Derives the minimum output accepted for the swap: the quoted output reduced by
/// `slippage_bps`, in exact integer arithmetic. Rejects a zero minimum, which would leave
/// the swap without slippage protection.
fn derive_min_amount_out(quoted_amount_out: U256, slippage_bps: u32) -> anyhow::Result<U256> {
    if slippage_bps >= BPS_DENOMINATOR {
        anyhow::bail!("Slippage {slippage_bps} bps must be below {BPS_DENOMINATOR}");
    }
    let min_amount_out = quoted_amount_out
        .checked_mul(U256::from(BPS_DENOMINATOR - slippage_bps))
        .and_then(|scaled| scaled.checked_div(U256::from(BPS_DENOMINATOR)))
        .ok_or_else(|| anyhow::anyhow!("Minimum output derivation overflow"))?;
    if min_amount_out.is_zero() {
        anyhow::bail!(
            "Derived minimum output is zero for quoted output {quoted_amount_out} at {slippage_bps} bps slippage"
        );
    }
    Ok(min_amount_out)
}

impl BlockchainExecutionClient {
    async fn build_execution_verification_migration(
        &self,
        snapshot: ExecutionVerificationMigrationSnapshot,
        finalized: VerifiedBlockHeader,
        finalized_headers: &[VerifiedBlockHeader],
        nonce_verification: &Verified<u64>,
    ) -> anyhow::Result<ExecutionVerificationMigration> {
        let next_canonical_nonce = nonce_verification.value;
        let mut hashes_by_intent: HashMap<i64, Vec<&ExecutionTransactionHashRow>> = HashMap::new();

View on GitHub (pinned to 18893faf8b)