Add canonicalize(Float) -> Float for byte-equivalence use cases

[thedavidmeister]

Fixes #183.

What

Adds LibDecimalFloat.canonicalize(Float) -> Float: a public-API library function that returns a unique byte representation per numeric value, so two Floats are numerically equal iff their canonical forms are byte-equal. Intended for consumers that need raw-byte equality (mapping(Float => X) keys, hashing, set membership, content-addressed storage).

How

Floats are non-canonical by design — eq rescales before comparing rather than relying on byte equality. canonicalize picks the representative with the largest |coefficient| that fits int224 subject to the exponent staying >= type(int32).min, reached by the loop-multiply approach from the issue:

function canonicalize(Float float) internal pure returns (Float) {
    (int256 signedCoefficient, int256 exponent) = float.unpack();
    if (signedCoefficient == 0) return FLOAT_ZERO;
    unchecked {
        while (exponent > type(int32).min) {
            int256 trySignedCoefficient = signedCoefficient * 10;
            if (int224(trySignedCoefficient) != trySignedCoefficient) break;
            signedCoefficient = trySignedCoefficient;
            exponent -= 1;
        }
    }
    return packLossless(signedCoefficient, exponent);
}

This avoids the two failure modes of the obvious packLossless(maximizeFull(...)) composition described in the issue (packLossless flagging value-preserving int224 truncation as lossy; packLossy silently zeroing tiny inputs on exponent underflow). The function never reverts for any valid input Float, is idempotent, and is value-preserving (eq to the input).

Bytecode / deploy impact

canonicalize is internal and unused by the concrete DecimalFloat contract, so Solidity dead-code-eliminates it from the deployed bytecode. testDeployAddress and testExpectedCodeHashDecimalFloat both still pass — no redeploy or deploy-constant regeneration required.

Tests

New test/src/lib/LibDecimalFloat.canonicalize.t.sol (matches the draft test list in the issue):

• testCanonicalizeZero — zero at any exponent canonicalizes to FLOAT_ZERO.
• testCanonicalizeEqualValuesByteEqual / testCanonicalizeNegativeEqualValuesByteEqual — different representations of the same value canonicalize to identical bytes32 (positive and negative).
• testCanonicalizeValuePreserving / testCanonicalizeIdempotent — concrete value preservation and idempotence.
• testCanonicalizeValuePreservingFuzz(int224,int32), testCanonicalizeIdempotentFuzz(int224,int32), testCanonicalizeEqImpliesByteEqualFuzz(int128,uint8) — fuzzed, 5096 runs each.

All 8 pass. Full forge test: 459 passed, 5 failed — the 5 failures are all in LibDecimalFloatDeployProd.t.sol and are pre-existing *_RPC_URL environment failures (live-fork prod-deployment checks); they fail identically on a clean origin/main checkout in this sandbox and are unrelated to this change. forge fmt --check is clean.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added decimal float canonicalization to normalize numerically equal values into a stable canonical form for reliable byte-level equality.

• Tests

  • Added extensive tests covering zero, positive/negative values, edge boundaries, idempotence, value preservation, adversarial cases, and fuzz/property tests to ensure correctness.

[coderabbitai]

Warning

Review limit reached

@thedavidmeister, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 11 minutes and 48 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 9dd3b705-7203-4cfc-a8fa-ff2413e1fddf

📥 Commits

Reviewing files that changed from the base of the PR and between 0dca9cc and 8398200.

📒 Files selected for processing (8)

• crates/float/abi/DecimalFloat.json
• crates/float/src/js_api.rs
• crates/float/src/lib.rs
• src/concrete/DecimalFloat.sol
• src/lib/deploy/LibDecimalFloatDeploy.sol
• test/src/concrete/DecimalFloat.canonicalize.t.sol
• test/src/lib/LibDecimalFloat.canonicalize.t.sol
• test_js/float.test.ts

Walkthrough

This PR adds an internal canonicalize(Float) that normalizes non-canonical Float representations by scaling the coefficient up (decrementing exponent) within int224/int32 bounds and repacking via packLossless. It also adds unit and adversarial tests validating zero handling, numeric preservation, idempotence, and that numerically equal Floats canonicalize to identical bytes.

Changes

Float Canonicalization

Layer / File(s)	Summary
Canonicalize function src/lib/LibDecimalFloat.sol	canonicalize(Float) unpacks, returns FLOAT_ZERO for zero, then multiplies the coefficient by 10 while decrementing exponent until int224 would overflow or exponent == int32.min, then repacks with packLossless to produce a deterministic, value-preserving representative.
Basic canonicalize tests test/src/lib/LibDecimalFloat.canonicalize.t.sol	Unit and fuzz tests asserting zero canonicalization, byte-equality for numerically-equal positive and negative values, value preservation, and idempotence.
Adversarial and boundary tests test/src/lib/LibDecimalFloat.canonicalizeAdversarial.t.sol	Adversarial concrete and fuzz tests covering no-collision at int32.min and int224 caps, cross-representation floor cases, boundary value-preservation and idempotence, and an iff property equating eq() with canonical byte-equality.

🎯 3 (Moderate) | ⏱️ ~20 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: adding a canonicalize function for byte-equivalence use cases, which is the core purpose of this PR.
Linked Issues check	✅ Passed	The implementation fully addresses all coding objectives from issue #183: canonicalize function with loop-multiply approach, comprehensive tests covering zero/equivalence/preservation/idempotence/fuzzing, and adversarial boundary cases.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to implementing and testing canonicalize(Float) per issue #183; no out-of-scope refactoring or unrelated modifications are present.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 2026-06-13-issue-183

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}