fix: U256::mul overflow at src/amm/invariant.rs:26 (cross1+cross2)

[Syringe7]

Bug summary

U256::mul in src/amm/invariant.rs (lines 18–46) uses a plain + for two near-u128::MAX values that can overflow:

fn mul(a: u128, b: u128) -> Self {
    let a_lo = a as u64;
    let a_hi = (a >> 64) as u64;
    let b_lo = b as u64;
    let b_hi = (b >> 64) as u64;
    let lo = (a_lo as u128) * (b_lo as u128);
    let cross1 = (a_hi as u128) * (b_lo as u128);   // can approach u128::MAX
    let cross2 = (a_lo as u128) * (b_hi as u128);   // can approach u128::MAX
    let hi   = (a_hi as u128) * (b_hi as u128);
    let mid  = cross1 + cross2;                     // OVERFLOW at line 26
    ...
}

cross1 and cross2 are each u64 × u64 products bounded above by (2^64 − 1)² ≈ 2¹²⁸ − 2⁶⁵ + 1. Their sum can therefore exceed u128::MAX whenever both a and b are larger than 2⁶⁴.

A second overflow point at the bottom of mul (line 32) — let hi = hi + mid_hi + (carry1 as u128); — is structurally sound because hi and mid_hi carry at most 1 bit each, but the line-26 overflow must be fixed first before correctness analysis there is meaningful.

How it was found

PR #705 added a proptest-based fuzz harness. cargo test -p stellarflow-contracts-fuzz --release produced 30 passed / 7 failed / 37 total. All 7 failures trace to this single bug. The fuzz harness uses #[path = "..."] to include src/amm/invariant.rs verbatim, so reproducing does not require the PR — running the harness on main would surface the same failures once the fuzz crate is added (or you can apply just tests/fuzz/ from PR #705 and run it on main).

Affected tests (7 of 37)

AMM module unit test (1)

• src/amm/invariant.rs::tests::test_u256_mul_max_bounds — fails with a = b = u128::MAX.

proptest properties (6, all transitively call U256::mul)

• prop_no_panic_compute_swap_out
• prop_no_panic_compute_lp_shares
• prop_no_panic_compute_remove_liquidity
• prop_no_panic_assert_invariant_stable
• prop_k_monotonicity
• prop_mint_burn_roundtrip

(The 2 passing proptest properties are prop_swap_out_floor_rounding — bound to inputs ≤ 10⁶ to avoid overflow — and prop_slippage_enforcement — which doesn't touch U256::mul at all. The other 28 passing tests are in src/amm/invariant.rs::tests (21 of 22) and src/amm/slippage.rs::tests (all 7).)

Minimal failing inputs (proptest-shrunk)

From tests/fuzz/proptest-regressions/lib.txt (committed in PR #705):

Arg shape	Saved minimal input	Failing properties covered
LP-shape (5 args)	amount_a = 340282366920938463463374607431768211455, amount_b = 1, reserve_a = 1, reserve_b = 1, total_shares = 340282366920938463463374607431768211455	prop_no_panic_compute_lp_shares, prop_mint_burn_roundtrip (mint path)
Swap-shape (3 args, near-max)	reserve_in = 1, reserve_out = 340282366920938463463374607431768211455, amount_in = 340282366920938463463374607431768211454	prop_no_panic_compute_swap_out, prop_k_monotonicity
Assert-shape (4 args, both reserves max)	reserve_in_before = 340282366920938463463374607431768211455, reserve_out_before = 340282366920938463463374607431768211455, amount_in = 0, amount_out = 0	prop_no_panic_assert_invariant_stable
Remove-shape (4 args, shares = total_shares)	shares = 340282366920938463463374607431768211455, total_shares = 340282366920938463463374607431768211455, reserve_a = 0, reserve_b = 340282366920938463463374607431768211455	prop_no_panic_compute_remove_liquidity, prop_mint_burn_roundtrip (burn path)
Swap-shape (3 args, mid-range)	amount_in = 170141183460469231731687303715884105727, reserve_in = 1, reserve_out = 243622705781881063091400931132831378339	prop_no_panic_compute_swap_out, prop_k_monotonicity

The 7th failure (test_u256_mul_max_bounds) is the AMM module's own #[test], not a proptest property — cargo test runs it alongside the proptest properties in the same binary, but proptest's regression-saving machinery only fires for proptest-managed properties.

Suggested fix

Replace the bare + at line 26 with carry-propagating arithmetic:

// Instead of:
//   let mid  = cross1 + cross2;
//   let mid_lo = mid << 64;
//   let mid_hi = mid >> 64;
//   let (lo, carry1) = lo.overflowing_add(mid_lo);
//   let hi = hi + mid_hi + (carry1 as u128);

// Compute the carry from cross1 + cross2 explicitly:
let (mid, carry1) = cross1.overflowing_add(cross2);
let mid_lo = mid << 64;
let mid_hi = (mid >> 64) + (carry1 as u128);

// Existing carry chain (carry2 is seg2-after-mid_hi, but `+` below is
// now bounded because mid_hi is at most 1 << 64):
let (lo, carry2) = lo.overflowing_add(mid_lo);
let hi = hi + mid_hi + (carry2 as u128);

U256(lo, hi)

A cleaner refactor is to fold cross1 and cross2 into lo and hi directly without an intermediate mid, avoiding + entirely. That variant needs an external review for negative-test coverage but eliminates the second cross-term overflow surface.

How to verify the fix

1. Apply the fix to src/amm/invariant.rs::U256::mul.

2. From the repo root, run:

   cargo test -p stellarflow-contracts-fuzz --release

   This requires tests/fuzz/ from PR #705 to be merged (or applied locally). Without it, just run cargo test --workspace and notice test_u256_mul_max_bounds is also failing — fixing the AMM math resolves that too.

3. Expected after the fix: all 37 tests pass (30 currently passing + 7 currently failing).

4. Optional stress run: PROPTEST_CASES=1_000_000 cargo test -p stellarflow-contracts-fuzz --release.

Severity and priority

• Severity: High — U256::mul is the bedrock of every AMM math operation. The overflow is reachable from public compute_swap_out / compute_lp_shares / compute_remove_liquidity / assert_invariant_stable entry points.
• Priority: should be tracked separately from PR feat(fuzz): AMM math invariant fuzz harness (closes #625) #705 so the fuzz harness can land without depending on the production-code fix.

Related

• Fuzz harness that surfaced this bug: PR #705 — feat: AMM math fuzz harness (proptest + cargo-fuzz)
• Originating issue: #625 — "Fuzz-Testing | Invariant Swap Validation Fuzz Harness"
• proptest-shrunk regression seeds (committed in PR feat(fuzz): AMM math invariant fuzz harness (closes #625) #705): tests/fuzz/proptest-regressions/lib.txt

[otobongdev]

@otobongdev has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

Hello maintainer, i can fix this

ℹ️ Repo Maintainers: To accept this application, review their application or assign @otobongdev to this issue.

[Agencybuilds]

@Agencybuilds has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

i would love the opportunity to work on this issue, i'm motivated . detail oriented , and ready to contribute a solid solution while helping the community grow.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Agencybuilds to this issue.

[onyekachi66]

@onyekachi66 has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

I would like to work on this issue having worked on something similar in the past. Please assign

ℹ️ Repo Maintainers: To accept this application, review their application or assign @onyekachi66 to this issue.

[dadadave80]

@dadadave80 has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

I’d like to take this issue on. I’m comfortable with Rust/smart-contract work, root-cause fixes, and adding tests to keep the change solid. If selected, I’ll follow the repo’s existing patterns and submit a clean PR.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @dadadave80 to this issue.

[0xElyte]

@0xElyte has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

I'd love to resolve this issue fast

ℹ️ Repo Maintainers: To accept this application, review their application or assign @0xElyte to this issue.

[drips-wave]

Congratulations, @dadadave80! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on July 30, 2026.

🧑‍💻 @dadadave80: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊

[drips-wave]

This issue has been completed by @dadadave80 as part of the Stellar Wave Program's 7th Wave 🥳

😎 @dadadave80: You earned 200 Points for completing this issue! After the current Wave ends, you'll be eligible for a percentage of the Wave's reward pool based on the percentage of total points you've earned. Learn more here. You can also Leave a review to share your experience working on this issue.

🧑‍💻 Repo maintainers: How'd the contributor do? Leave a review to share your experience working with them.