Token Decimal Normalization for Split Calculations

[Kingsman-99]

Description

Stellar assets can have different decimal precisions (XLM uses 7 decimal places; custom tokens may use 2, 6, or 18). When computing each recipient's share from a raw token amount, integer arithmetic on differing scales produces silently wrong results — either overpaying or underpaying recipients. The contract must normalize amounts to a canonical scale before any split calculation and denormalize before token transfer.

Technical Context

contracts/split/src/lib.rs — #[contractimpl] pay() and release_funds() entry points; contracts/split/src/types.rs — Invoice and RecipientShare structs (add token_decimals: u32 field); contracts/split/src/math.rs (new helper module) — normalize_amount(raw: i128, decimals: u32) -> i128 and denormalize_amount(normalized: i128, decimals: u32) -> i128 functions; soroban_sdk::token::Client::decimals() called against the payment token during initialize() to populate the stored decimal count.

Acceptance Criteria

• Invoice stores the payment token's decimal count, populated from soroban_sdk::token::Client::decimals() during initialize()
• normalize_amount scales all raw amounts to a fixed 7-decimal internal representation before split arithmetic
• denormalize_amount converts back to the token's native scale before each token::Client::transfer() call
• A unit test in contracts/split/src/tests/decimal_tests.rs verifies correct per-recipient amounts for tokens with 2, 6, and 7 decimal places across at least three split configurations
• Checked arithmetic (checked_mul, checked_div) is used throughout and propagates Error::ArithmeticOverflow on out-of-range inputs
• All CI checks (cargo build --target wasm32-unknown-unknown, cargo test, cargo clippy) pass and the branch has no merge conflicts

---

[adeboladee]

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

Hello Maintainer, Please I would like to work on this issue

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

[Nwoyemartha]

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

Hi, I would like to work on this issue

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

[Anadudev]

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

Hello maintainer, I'd love to work on this issue!

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

[iwayemi5]

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

Hi maintainer I will like to work on this issue please assign to me

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

[tegaReed-crypto]

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

Hi maintainer, I would love to work on this issue

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

[drips-wave]

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

🧑‍💻 @tegaReed-crypto: 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 🌊