{"record":{"id":"e5e5a29159795e34","repo":"nautechsystems/nautilus_trader","slug":"order-amount-scaling-overflow","errorCode":null,"errorMessage":"Order amount scaling overflow","messagePattern":"Order amount scaling overflow","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/adapters/blockchain/src/execution/client.rs","lineNumber":5211,"sourceCode":"}\n\n/// Converts a base-denominated order quantity into raw token units with exact integer\n/// scaling by the base token decimals.\n///\n/// `Quantity::raw` is scaled to the greater of its declared precision and `FIXED_PRECISION`;\n/// token amounts are scaled to the token's decimals. Quantities not exactly representable in\n/// token units are rejected rather than rounded.\nfn quantity_to_raw_amount(quantity: Quantity, decimals: u8) -> anyhow::Result<U256> {\n    if quantity.is_zero() {\n        anyhow::bail!(\"Order quantity must be positive\");\n    }\n\n    let raw = U256::from(quantity.raw);\n    let raw_precision = quantity.precision.max(FIXED_PRECISION);\n    if decimals >= raw_precision {\n        let scale = U256::from(10u64)\n            .checked_pow(U256::from(decimals - raw_precision))\n            .ok_or_else(|| anyhow::anyhow!(\"Order amount scaling overflow\"))?;\n        raw.checked_mul(scale).ok_or_else(|| {\n            anyhow::anyhow!(\"Order amount overflow scaling quantity to raw token units\")\n        })\n    } else {\n        let divisor = U256::from(10u64)\n            .checked_pow(U256::from(raw_precision - decimals))\n            .ok_or_else(|| anyhow::anyhow!(\"Order amount scaling overflow\"))?;\n        if !(raw % divisor).is_zero() {\n            anyhow::bail!(\n                \"Order quantity {quantity} is not exactly representable in {decimals} base token decimals\"\n            );\n        }\n        Ok(raw / divisor)\n    }\n}\n\nfn swap_token_pair(\n    side: OrderSide,","sourceCodeStart":5193,"sourceCodeEnd":5229,"githubUrl":"https://github.com/nautechsystems/nautilus_trader/blob/18893faf8b356be3320add8de2f861b0b647cf06/crates/adapters/blockchain/src/execution/client.rs#L5193-L5229","documentation":"When converting an order Quantity to raw token units, the client raises 10^(decimals - raw_precision) and multiplies the fixed-precision raw value. This error is thrown when the scaling power itself (10^exponent) overflows U256, meaning the decimal delta between the order precision and the token decimals is too large to represent.","triggerScenarios":"Calling the execution client to submit an order whose instrument quantity precision differs from the token's decimals by an exponent so large that 10^(decimals - raw_precision) exceeds U256::MAX (e.g. absurd decimals values or a token with astronomically many decimals).","commonSituations":"Misconfigured instrument definitions where token decimals were read from the wrong contract or hardcoded incorrectly; a corrupted/malicious token metadata feed reporting decimals in the hundreds; copy-paste decimals from a different chain's token.","solutions":["Verify the token's decimals value matches the on-chain contract (call decimals() on the token) and fix the instrument/provider config","Ensure quantity.precision (or FIXED_PRECISION fallback) is set correctly for the instrument so decimals - raw_precision stays small","Cap or sanitize decimals before calling the conversion; reject tokens with implausible decimals values upstream"],"exampleFix":"// before\nlet scale = U256::from(10u64).checked_pow(U256::from(decimals - raw_precision))?;\n// after\nlet exponent = (decimals - raw_precision) as u32;\nif exponent > 78 { anyhow::bail!(\"decimals delta {exponent} too large for U256 scaling\"); }\nlet scale = U256::from(10u64).checked_pow(U256::from(exponent))?;","handlingStrategy":"validation","validationCode":"fn assert_scalable(quantity_precision: u32, decimals: u32) -> Result<(), String> {\n    let delta = decimals.abs_diff(quantity_precision.max(FIXED_PRECISION));\n    if delta > 78 { Err(format!(\"decimals delta {delta} cannot be scaled in U256\")) } else { Ok(()) }\n}","typeGuard":null,"tryCatchPattern":"match client.submit_order(...) {\n    Err(e) if e.to_string().contains(\"Order amount scaling overflow\") => { /* fix decimals config / reject order */ }\n    other => other?,\n}","preventionTips":["Load token decimals from the on-chain contract, never hardcode","Validate decimals is in a plausible range (0..=78) at instrument registration","Log the precision delta between instrument and token when it exceeds a threshold"],"tags":["overflow","u256","arithmetic","blockchain","quantity-scaling"],"backgroundTag":"value-out-of-range","analyzedSha":"18893faf8b356be3320add8de2f861b0b647cf06","analyzedAt":"2026-09-08T20:49:34.690Z","contentChangedAt":"2026-09-08T20:49:34.690Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}