Cowrie Research

wide-integer-helper-trust-boundary-and-exact-overflow-discipline

13 min read

Wide-Integer Helper Trust Boundary and Exact-Overflow Discipline

  • Name: wide-integer helper trust boundary and exact-overflow discipline
  • Category: arithmetic-safety reference / shared-math-helper review note / exact-width discipline / solvency-boundary design companion
  • Summary: Protocols often treat helper functions like checked_shlw, mulDiv, cast wrappers, fixed-point normalizers, and checked_* math adapters as if they were mere implementation details. In practice, these helpers often certify the exact thing a higher-level mint, liquidity-add, collateral, or redemption path needs to believe: that one intermediate fit in the intended width, that no economically meaningful bits were truncated, that a scale factor preserved units, or that a quote still reflects the real amount paid. Once callers start treating that helper output as proven-safe truth, the helper itself becomes a reserve boundary. This note exists to preserve the positive-design target behind incidents like Cetus Protocol: if a custom wide-integer or overflow-check helper lies, downstream solvency logic should not have to guess that it lied.

Why this note exists

  • Many exploit writeups stop at overflow bug, precision bug, or bad constant, which is often too shallow to guide design review.
  • The sharper recurring question is: what exact economic fact was the helper supposed to certify for its callers?
  • In Cetus, checked_shlw() was not just a utility. It was the proof object that told get_delta_a() whether a pool-scale liquidity quote still fit safely inside the protocol’s arithmetic model.
  • Similar failures recur whenever protocols hand-roll wide-integer helpers, custom fixed-point adapters, or quote-preserving math wrappers and then let higher-level mint / liquidity / reserve logic trust them as if they were language-level safety guarantees.
  • The missing healthy-side design target is therefore not merely use safer math, but treat arithmetic helpers that certify solvency-critical width, scaling, and exactness as treasury-grade trust boundaries.

What this note is trying to preserve

  • A helper that claims to return a checked, safe, exact, normalized, or overflow-free result is not just an optimization aid once economic state depends on it.
  • If downstream code mints claims, admits collateral, prices liquidity, or releases reserves on the assumption that the helper already proved width or exactness, the helper has become part of the protocol’s solvency proof.
  • The design target is not never write custom math helpers. It is make the helper's proof obligation explicit, locally derivable, and independently re-checkable before higher layers treat the result as money-good.

The six questions a solvency-critical arithmetic helper should answer clearly

1. What exact economic statement does the helper certify?

  • Reviewers should be able to say in one sentence what the helper is proving for its callers.
  • Examples:
    • this left shift preserved all economically meaningful bits
    • this division rounded in a direction consistent with the quote's safety claim
    • this cast proves the intermediate still fits the narrower width
    • this normalized fixed-point value still represents the same quantity in the same unit system
  • If the answer is fuzzy, callers are probably trusting more than the helper actually proves.

2. What exact width, range, or unit bound is being enforced?

  • A guard constant like 1 << 192, Q96, 1e18, or a limb mask is never just a literal once reserve logic depends on it.
  • The helper needs an explicit derivation showing why that threshold is the right one for the operation being performed.
  • If a reviewer cannot re-derive the bound from the operation’s bit geometry or unit map, the protocol is already relying on folklore.

3. Which operations look equivalent but are not?

  • << is not the same as checked multiplication when the language truncates shifted bits.
  • A cast is not a proof unless the precondition guaranteeing fit is explicit and enforced.
  • mulDiv, shift then divide, normalize then compare, and scale in one domain then settle in another may look algebraically interchangeable while differing badly under finite-width arithmetic and rounding.
  • Healthy designs write down which equivalences they are assuming and test those assumptions directly.

4. How do callers learn whether the helper failed?

  • Revert, Option, (value, overflowed), saturating return, and silent truncation all mean different things.
  • A helper is especially dangerous when its interface suggests a strong guarantee while its failure mode is soft or caller-dependent.
  • If callers can accidentally ignore the failure signal or misinterpret false as safe enough, the API itself is part of the bug surface.

5. Where does the helper’s trust fan out?

  • A shared math helper can sit under many markets, pools, or issuance paths.
  • Review needs a blast-radius map: which contracts, routes, or asset types would inherit reserve fiction if this helper’s proof is wrong?
  • Healthy systems treat a shared arithmetic library more like a verifier or custody primitive than a local code convenience.

6. What independent check proves the helper stayed honest?

  • One implementation should not be allowed to certify itself.
  • There should be an independent oracle for correctness: a wider-precision reference model, a slower big-int implementation, symbolic checks, differential tests, or property tests stated in economic terms.
  • If both production code and tests reuse the same mistaken literal or truncation assumption, the test suite is only rehearsing the bug.

What sound design looks like

  • Helpers certify one narrow thing and say it plainly.
    • A wide-integer helper should advertise whether it proves exact fit, conservative rounding, saturating fallback, or fail-closed rejection. Checked-looking naming should match real semantics.
  • Thresholds are derived, not cargo-culted.
    • Every width bound, shift limit, limb mask, and fixed-point scale participating in solvency-critical math has a short derivation and a single source of truth.
  • Unsafe equivalences are made explicit.
    • If the implementation relies on shift then divide behaving like a mathematical rescaling, or on a cast preserving all relevant magnitude, that assumption is tested as an invariant rather than implied by code style.
  • Callers do not silently inherit soft failure modes.
    • A helper that cannot certify safe arithmetic fails closed before minting, collateral admission, or reserve release logic treats its output as canonical.
  • Independent models check the production helper.
    • High-level state transitions are differential-tested against a wider or simpler arithmetic model so a bad helper cannot quietly certify its own lies.
  • Shared libraries are rolled out like fleet-wide risk.
    • If many pools or issuance paths depend on one helper, operators know that one helper bug is a portfolio-level event and stage deployment, monitoring, and response accordingly.

Useful positive design shapes

1. Single-source derivation for width guards

  • Keep the bound, the derivation, and the helper implementation tied together.
  • If a helper rejects when n >= 1 << 192, the code, comment, and tests should all explain why 192 is the right cutover for that exact operation.
  • The design goal is to make wrong literal in a copied guard hard to ship.

2. Wider-precision oracle implementations

  • Maintain a slow reference path using a strictly wider arithmetic model or big-int library.
  • Production math may need u256 or fixed-point shortcuts; the reference path should not.
  • Differential tests should assert that the helper’s accepted values match the oracle’s exact result and that rejected values really were unsafe.

3. Economic property tests above the helper layer

  • State tests should say things like:
    • adding pool-scale liquidity cannot require one wei of payment unless the exact model agrees
    • quote-side payment and settlement-side claim issuance stay mutually bounded
    • a safe path cannot become cheaper when intermediate width increases past the helper's proof boundary
  • These tests catch bugs even when the lower-level helper still looks internally consistent.

4. Failure-signaling APIs that are hard to misuse

  • Prefer interfaces that make unsafe states impossible to ignore: revert on impossible geometry, typed result objects, or helpers whose success branch alone returns the value.
  • A (value, ok) interface is only safe if callers are forced by structure and review discipline to honor ok before using value.

5. Shared-library blast-radius inventories

  • Maintain a live map of which contracts, pools, and routes depend on each arithmetic helper family.
  • This lets responders ask what else inherited this proof object? immediately instead of after the first drain.
  • Shared math libraries deserve the same fleet awareness protocols already give to bridge verifiers, price oracles, and signer middleware.

6. Fail-closed state transitions above helper truth

  • High-level functions should keep the right to say I do not believe this quote even if the helper returned a value.
  • A healthy liquidity-add, mint, or redemption path still enforces reserve-boundedness and economic sanity checks so one helper error does not automatically become withdrawable value.

Design questions worth asking first

  • What exact economic claim does this helper make for its callers: exact fit, safe scale-up, conservative quote, or unit-preserving normalization?
  • Which literal or threshold encodes that claim, and where is its derivation written down?
  • Are any operations being treated as equivalent even though finite-width arithmetic, truncation, or rounding makes them diverge?
  • Can the helper return a numerically plausible value on failure, and if so what forces callers not to treat that value as canonical?
  • Which mint, liquidity, collateral, or redemption paths inherit this helper’s guarantee today?
  • What independent wider model proves that accepted outputs are truly safe and rejected outputs are truly necessary?

Red flags

  • checked in the helper name, but the function can still return a truncated or caller-misusable value
  • copied shift or mask constants with no short derivation
  • comments that explain algebra over infinite integers while code executes in finite-width arithmetic
  • callers that use the helper’s return value first and only later inspect the failure flag
  • tests that mirror the same production helper rather than comparing against a wider oracle
  • one shared arithmetic library sitting under many pools, with no fleet map or staged rollout discipline
  • audit comfort based on language-level checked arithmetic even though the critical operation is shift, cast, truncation, or fixed-point scaling rather than ordinary addition/multiplication

Failure-prevention checklist

  • For every solvency-critical helper, write down the exact property it certifies: exact fit, overflow absence, conservative rounding, unit-preserving scaling, or safe narrowing cast.
  • Keep threshold constants, limb masks, and scale factors derived in one place. A reviewer should be able to re-derive each critical bound from bit geometry or unit analysis without guessing.
  • Treat shift, cast, truncation, and fixed-point normalization as separate hazards from ordinary checked arithmetic. Do not let language-level overflow comfort stand in for explicit proof of these operations.
  • Make failure modes hard to ignore. If a helper cannot certify safe arithmetic, prefer reversion or typed failure over returning a plausible-looking value that callers might still use.
  • Differential-test every accepted helper output against a wider-precision oracle or big-int implementation, especially at bound - 1, bound, and bound + 1.
  • Add higher-layer economic assertions so one helper mistake cannot silently authorize cheap mint / honest redemption, cheap liquidity add / honest liquidity remove, or cheap collateral admission / honest liquidation asymmetry.
  • Inventory where each shared arithmetic helper is used and treat changes to that helper as fleet-wide risk, not local refactors.
  • Stage rollout of new shared-math helpers or major rewrites behind limited exposure where possible, especially when the same library feeds many pools or markets.
  • Require reviewers to inspect both the arithmetic derivation and the caller contract’s use of the helper result. A correct helper can still be unsafe if its failure signal is consumed incorrectly.
  • Monitor for economic impossibilities that the helper was supposed to prevent: near-zero payment for pool-scale liquidity, extreme quote discontinuities at width boundaries, or sudden reserve outflows after apparently trivial inputs.

Audit prompts

  • What exactly is this helper promising to its callers, and is that promise stronger than what the code really proves?
  • Which operations here depend on bit-level behavior rather than ordinary checked arithmetic semantics?
  • Can a caller receive a numerically plausible output even when the helper’s proof failed or truncated meaningful bits?
  • What is the exact derivation for each critical bound or mask, and could one copied literal drift without reviewers noticing?
  • What independent implementation verifies the helper’s behavior at and around its width limits?
  • If this helper were wrong, which reserves, markets, or pools would start honoring counterfeit value first?
  • Do higher-level functions enforce any reserve-boundedness or economic sanity check after the helper returns, or is the helper treated as the final word?
  • Have edge cases around bound - 1, bound, bound + 1, zero, max-width, and narrow-range geometry been tested under the exact caller contexts that monetize the result?
  • Are reviewers relying on the language checks arithmetic now even though the decisive step is a shift, cast, or truncation the language does not protect the same way?
  • If the helper lives in a shared library, what is the incident-response plan for all dependent deployments if one proof assumption turns out false?

Lessons that should already be standard

  • A helper named checked_* is not automatically a proof object. Its exact guarantee has to be derived and independently verified.
  • Shift is not multiply, cast is not prove fit, and normalized is not same economic quantity. Languages and libraries make different promises for each.
  • Shared arithmetic helpers are treasury code once minting, liquidity, or reserve release logic starts trusting them.
  • A wrong bound is not a local bug when many callers inherit it. One bad literal in a helper can become a fleet-wide solvency failure.
  • Higher-level economic asymmetry is the real cash-out rail. The helper bug matters because a later path still honors the counterfeit result against real reserves.
  • Big-int or wider-model differential testing is not overkill for custom fixed-point and wide-integer helpers; it is often the cheapest way to catch finite-width folklore before mainnet does.
  • If a protocol cannot explain in one sentence what a math helper certifies for reserve logic, the audit burden is not finished.

Negative exemplar cluster

  • Cetus Protocol is the clean preserved exemplar: checked_shlw() was supposed to certify that a u256 << 64 scale-up would not truncate meaningful bits, but a wrong bound let wrapped residue flow into a tiny payment quote while liquidity minting still used the large intended state transition.
  • Truebit is a useful arithmetic cousin on the same economic seam: not a bad checked helper, but the same broader buy-side math stopped proving reserve reality while sell-side redemption kept honoring it asymmetry.

How this note complements the exploit corpus

Internal linkages

Control surface

Graph View

Backlinks