Financial calculations use floating-point math instead of fixed-point/decimal — cumulative rounding drift

[Wilfred007]

What

Introduce a shared fixed-point/decimal money type (or a well-tested decimal library) for payroll-related financial math, and migrate the repeated parseFloat/toFixed pattern across tax, benefits, and bonus calculations to use it.

Why

Three separate services repeat the same anti-pattern of rounding each intermediate value to a fixed number of decimals via .toFixed() and then accumulating results with native JS floating-point addition:

• backend/src/services/taxService.ts — calculateDeductionsRuleBased (L242-278): deductedAmount = parseFloat((grossAmount * (Number(rule.value) / 100)).toFixed(7)), then totalTax += deductedAmount accumulated as a JS number
• backend/src/services/benefitsService.ts — L64: parseFloat(n.toFixed(7))
• backend/src/services/payrollBonusService.ts — L222-227: .reduce((sum, item) => sum + parseFloat(item.amount), 0)

JS floats can't exactly represent most decimals. Rounding each line item to 7 decimals (matching Stellar's stroop precision) and then summing with float addition across an arbitrary number of stacked deduction/tax rules lets rounding error accumulate — net payroll amounts submitted on-chain can silently diverge from gross minus deductions by fractions of a stroop, compounding across pay periods and audit reports.

Scope

In scope:

• Introduce (or adopt an existing) fixed-point/decimal type for all money math in these three services
• Migrate the specific call sites listed above to use it consistently
• Tests demonstrating the old code's drift on a stacked multi-rule example, and that the new code doesn't drift

Out of scope:

• Contract-side (Rust) math — that's tracked separately (#398 covers revenue_split dust/rounding)
• Non-financial numeric calculations elsewhere in the backend

Acceptance Criteria

• A shared decimal/fixed-point money type exists and is used by taxService.ts, benefitsService.ts, payrollBonusService.ts
• Summing N stacked deduction/tax rules produces an exact result (no drift), verified by a regression test that fails against the old float-based code
• Existing tax/benefits/bonus tests still pass with correct (not just similar) values

Technical Context

• backend/src/services/taxService.ts L242-278
• backend/src/services/benefitsService.ts L64
• backend/src/services/payrollBonusService.ts L222-227

[MarcusDavidG]

I can handle this issue and will like to work on it, Please assign thank you.

[ABEEGOLD]

Hi, I'd like to work on this issue. I have experience introducing fixed-point/decimal types to eliminate floating-point drift in financial calculations, especially where stacked rounding across services compounds over time.

My plan: introduce a shared fixed-point/decimal money type (matching Stellar's 7-decimal stroop precision) and migrate the specific call sites — calculateDeductionsRuleBased in taxService.ts, the rounding in benefitsService.ts, and the reduce/sum in payrollBonusService.ts — off parseFloat/toFixed float accumulation onto it. I'll write a regression test with a stacked multi-rule example that demonstrably fails against the old float-based code but produces an exact result with the new type, and confirm existing tax/benefits/bonus tests pass with correct (not just approximately similar) values.

Happy to get started right away.

[alfeedrips]

Application to Work on Fixed-Point Money Type and Payroll Calculation Precision

I am interested in contributing to this issue because it addresses an important problem in financial software: maintaining accurate and consistent monetary calculations.

I understand that the current implementation relies on JavaScript floating-point numbers together with repeated parseFloat() and .toFixed() operations across the tax, benefits, and bonus services. While this may appear to provide sufficient precision, accumulating rounded floating-point values across multiple deduction and tax rules can introduce small discrepancies that become significant when payroll calculations are repeated over time.

My approach would be to introduce a shared fixed-point or decimal-based money type and use it consistently across the affected services. I would focus on the following areas:

• Replacing the repeated parseFloat() / .toFixed() pattern in taxService.ts.
• Updating the benefits calculations in benefitsService.ts.
• Updating the bonus aggregation logic in payrollBonusService.ts.
• Ensuring that intermediate calculations remain in the decimal representation instead of being converted back to native JavaScript numbers.
• Preserving the required seven-decimal precision for Stellar-related monetary calculations.
• Maintaining compatibility with the existing service interfaces where possible.

I would also add regression tests that demonstrate the rounding drift in the existing implementation using multiple stacked deduction rules. The new implementation would then be tested against the same scenario to verify that the accumulated result remains exact.

In addition, I would run the existing tax, benefits, and bonus test suites to make sure the migration does not change correct expected values or introduce regressions.

I believe this approach would provide a safer foundation for payroll calculations, improve consistency across the affected services, and make future financial calculations easier to reason about and test.

I would be happy to contribute to the implementation, testing, and review of this change.

[grantfox-oss]

🦊 GrantFox — @alfeedrips has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #451)
2. Your PR will be reviewed by the Protocol-Guild maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Third Campaign campaign!

@alfeedrips's PR #461 was approved and merged by @Wilfred007.

🏆 @alfeedrips: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (204 total points). Track your full progress on GrantFox.

👏 Great work, @alfeedrips! Keep contributing to Protocol-Guild.