YNU-724: feat(contracts-new): account for different decimals on chains

[nksazonov]

Summary by CodeRabbit

• New Features

  • Added token decimal validation and support for improved cross-chain token handling.
  • Enhanced escrow finalization events with channel ID tracking for better transaction correlation.

• Improvements

  • Implemented decimal-aware calculations to ensure accurate value comparisons across tokens with different decimal places.
  • Expanded test coverage for cross-chain operations with tokens having varying decimals.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

• 🔍 Trigger a full review

📝 Walkthrough

Walkthrough

This pull request introduces comprehensive token decimals support across escrow and channel management contracts via a new WadMath library for decimal-aware comparisons. The Ledger struct gains a decimals field, validation utilities are added, event signatures are extended with channelId parameters, and internal functions transition from pure to view to support Wad-based arithmetic throughout the system.

Changes

Cohort / File(s)	Summary
New WadMath utility library WadMath.sol	Introduces new internal pure functions for converting uint256 and int256 amounts to 18-decimal (WAD) representation with validation (max precision 18).
Token decimals validation Utils.sol	Adds MAX_PRECISION constant and validateTokenDecimals() function that verifies ledger decimals against token metadata via IERC20Metadata on same-chain deployments.
Ledger struct extension interfaces/Types.sol	Adds uint8 decimals field to Ledger struct, positioned after token address, affecting serialization and state reads/writes across all ledger operations.
Core escrow engine decimal support ChannelEngine.sol, EscrowDepositEngine.sol, EscrowWithdrawalEngine.sol	Adds WadMath imports and decimal validation via Utils. Changes internal calculation functions from pure to view. Replaces direct arithmetic comparisons with WadMath-based Wad conversions for nodeAllocation, userAllocation, net flow deltas, and invariant checks to support cross-decimal comparisons.
Event signature updates ChannelHub.sol	Adds indexed bytes32 channelId parameter to four finalization events (EscrowDepositFinalized, EscrowDepositFinalizedOnHome, EscrowWithdrawalFinalized, EscrowWithdrawalFinalizedOnHome) and updates all corresponding emit sites.
Single-chain test updates test/ChannelHub_Base.t.sol, test/ChannelHub_singlechain.lifecycle.t.sol, test/Utils.t.sol	Updates Ledger initializations to include decimals field (18 for home, 0 or token-specific for non-home). Extends nextState() helpers with new overload supporting nonHomeDecimals parameter. Adds userSig and nodeSig fields to State test objects.
Cross-chain test coverage test/ChannelHub_crosschain.lifecycle.t.sol	Extensive updates to cross-chain lifecycle tests with decimals field propagation (8, 10, 14 decimal variants). Adds new test cases covering escrow deposits/withdrawals/migrations with varying non-home token decimals. Updates balance verification and unlock semantics assertions for decimal-aware amounts.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• YNU-729: feat(ChannelHub): add cross-chain deposit, withdrawal, migration #498 — Extends cross-chain escrow/migration logic by adding token-decimals support and WadMath conversions across the same ChannelEngine/ChannelHub/Escrow engines and validation flows.
• YNU-529: feat: State-Enforced PoC SC implementation #487 — Modifies core type and utility contracts (interfaces/Types.sol and contracts-new/src/Utils.sol), touching the same code-level artifacts for type layouts and utility functions.

Suggested labels

ready

Suggested reviewers

• philanton

Poem

🐰 Decimals dance in Wad-y light,
Converting tokens left and right,
Eighteen decimal dreams we weave,
Cross-chain values now we perceive,
Channels bloom with precision's sight! ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: adding support for different token decimals across chains, which aligns with the core implementation of WadMath conversions, token decimal validation, and updated state handling throughout the codebase.
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.}

---

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.}

[nksazonov]

@coderabbitai review

[gemini-code-assist]

Summary of Changes

Hello @nksazonov, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the contract's ability to manage cross-chain operations by properly accounting for tokens with different decimal precisions. It introduces a standardized mathematical approach for value comparisons and transfers, ensuring that amounts are correctly interpreted and processed regardless of their native decimal representation. This change is crucial for maintaining financial accuracy and preventing potential discrepancies in a multi-chain environment.

Highlights

• Decimal Handling for Cross-Chain Operations: Introduced a new WadMath library and integrated decimal awareness across core contract logic to correctly handle token amounts with varying decimal precisions during cross-chain escrow and migration operations.
• Ledger Struct Enhancement: The Ledger struct now includes a decimals field to explicitly store the token's decimal precision, enabling accurate conversions and validations.
• Token Decimal Validation: Added a validateTokenDecimals utility function to ensure that the decimals stored in a Ledger struct match the actual decimals reported by the corresponding ERC20 token contract on the current chain, preventing inconsistencies.
• Refactored Event Emission: The EscrowDepositFinalized and EscrowWithdrawalFinalized events in ChannelHub.sol have been updated to include channelId as an indexed parameter, improving event traceability and filtering capabilities.
• Comprehensive Testing for Decimal Scenarios: New test cases have been added to cover cross-chain escrow deposits, withdrawals, and migrations involving tokens with different decimal precisions, ensuring robustness of the new decimal handling logic.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[gemini-code-assist]

Code Review

This pull request introduces significant improvements to handle different decimal precisions across various chains in the channel and escrow operations. The new "WadMath" library provides robust "toWad" conversion functions, and the "Ledger" struct has been updated to include a "decimals" field. The "Utils" library now includes a "validateTokenDecimals" function to ensure consistency. All relevant calculations and comparisons in "ChannelEngine", "EscrowDepositEngine", and "EscrowWithdrawalEngine" have been updated to use these decimal-aware conversions, enhancing the correctness and reliability of cross-chain interactions. Comprehensive test cases have also been added to validate this new functionality.

[dimast-x]

In GetEscrowWithdrawalData and GetEscrowDepositData could you please add home channel ID