{"record":{"id":"47585ca6ea9a3bda","repo":"nautechsystems/nautilus_trader","slug":"type-name-amount-amount-overflows-u256-while-s","errorCode":null,"errorMessage":"{type_name} amount {amount} overflows U256 while scaling from {decimals} to {fixed_precision} decimals","messagePattern":"(.+?) amount (.+?) overflows U256 while scaling from (.+?) to (.+?) decimals","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/adapters/blockchain/src/decode.rs","lineNumber":106,"sourceCode":"fn scale_u256_to_raw(\n    amount: U256,\n    decimals: u8,\n    fixed_precision: u8,\n    raw_max: U256,\n    type_name: &str,\n    raw_max_name: &str,\n) -> anyhow::Result<U256> {\n    let raw = if decimals < fixed_precision {\n        let scale = U256::from(10)\n            .checked_pow(U256::from(fixed_precision - decimals))\n            .ok_or_else(|| {\n                anyhow::anyhow!(\n                    \"Scale 10^{} exceeds U256 while converting {type_name}\",\n                    fixed_precision - decimals\n                )\n            })?;\n        amount.checked_mul(scale).ok_or_else(|| {\n            anyhow::anyhow!(\n                \"{type_name} amount {amount} overflows U256 while scaling from {decimals} to {fixed_precision} decimals\"\n            )\n        })?\n    } else if decimals > fixed_precision {\n        round_u256_half_even(amount, decimals - fixed_precision, type_name)?\n    } else {\n        amount\n    };\n\n    check_raw_range(raw, raw_max, type_name, raw_max_name)?;\n    Ok(raw)\n}\n\nfn check_raw_range(\n    raw: U256,\n    raw_max: U256,\n    type_name: &str,\n    raw_max_name: &str,","sourceCodeStart":88,"sourceCodeEnd":124,"githubUrl":"https://github.com/nautechsystems/nautilus_trader/blob/18893faf8b356be3320add8de2f861b0b647cf06/crates/adapters/blockchain/src/decode.rs#L88-L124","documentation":"This error is raised by scale_u256_to_raw when multiplying a U256 amount by the scaling factor 10^(fixed_precision - decimals) would exceed the U256 maximum. It means the raw integer value of the amount cannot be represented in U256 after upscaling from the token's decimals to the fixed precision used by the system. The library throws it via checked_mul to avoid silent wrapping arithmetic in blockchain value conversion.","triggerScenarios":"Calling u256_to_quantity or u256_to_price (both funnel through scale_u256_to_raw) with a U256 amount that is already near 2^256 and a target fixed_precision greater than the token's decimals, so the multiply by 10^(fixed_precision-decimals) overflows. Also hit directly by tests with extreme amount/precision combinations.","commonSituations":"Indexing a token with very high decimals plus a fixed_precision configured too high; a malformed or adversarial contract event emitting a near-maximum uint256 amount; incorrectly configured fixed_precision in adapter config.","solutions":["Lower the configured fixed_precision so the required scaling factor 10^(fixed_precision - decimals) fits in U256 for your value range","Check the source event/decimals value: a near-max U256 amount usually indicates a corrupted or adversarial log entry; skip or reject the record","If the token's decimals metadata is wrong (too low), fix the decimals source so no upscaling is attempted","If you genuinely need larger values, reconsider the representation — U256 cannot be widened; use a big-integer type outside this API"],"exampleFix":"// before\nlet qty = u256_to_quantity(amount, decimals, fixed_precision, type_name)?; // fixed_precision = 36\n// after\nlet qty = u256_to_quantity(amount, decimals, 18, type_name)?; // smaller scale avoids overflow","handlingStrategy":"validation","validationCode":"fn can_scale(amount: U256, decimals: u32, fixed_precision: u32) -> bool {\n    if decimals >= fixed_precision { return true; }\n    let scale = U256::from(10).pow(U256::from(fixed_precision - decimals));\n    amount.checked_mul(scale).is_some()\n}","typeGuard":null,"tryCatchPattern":"match u256_to_quantity(amount, decimals, fixed_precision, \"Token\") {\n    Ok(q) => use(q),\n    Err(e) if e.to_string().contains(\"overflows U256\") => reject_record(e),\n    Err(e) => return Err(e),\n}","preventionTips":["Keep fixed_precision at or below token decimals + a small safety margin","Validate amounts against a sane upper bound (e.g. token total supply) before conversion","Sanity-check token decimals metadata from a trusted source","Log and quarantine overflowing records instead of failing the whole indexing run"],"tags":["overflow","u256","arithmetic","blockchain"],"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-14T05:17:10.506Z"}