Overflow-Safe Stake Accounting & Slashing with Checked i128 Math

[meshackyaro]

Description

This issue aims to address the implementation of Overflow-Safe Stake Accounting & Slashing with Checked i128 Math.

The core objective is to: Reimplement stake, reward, and slashing accounting using checked i128 arithmetic with saturating/guarded paths so no operation can overflow or silently truncate funds.

By completing this feature, we will ensure that the TrustFlow protocol maintains its high standards for security, usability, and decentralized logic. This issue requires careful attention to the Smart Contracts architecture and adherence to the existing project conventions.

When picking up this issue, please ensure you document any new dependencies or architectural decisions made during development.

Component

Smart Contracts

Difficulty

🔴 Hard

Tasks

• Review Soroban architecture and soroban-cli usage
• Implement Rust logic for: Overflow-Safe Stake Accounting & Slashing with Checked i128 Math
• Write comprehensive unit tests in Rust
• Ensure proper event emission for indexing
• Run cargo fmt and cargo clippy
• Verify soroban contract build successfully compiles to WASM without bloating size

Acceptance Criteria

• Feature accurately implements the objective: Reimplement stake, reward, and slashing accounting using checked i128 arithmetic with saturating/guarded paths so no operation can overflow or silently truncate funds.
• Any PR that introduces Rust errors is automatically blocked
• CI pipeline runs in under 3 minutes per PR
• Code is properly reviewed and approved by codeowners

Estimated Time

1-3 days

[Paranoa-dev]

I'd like to take this on.

I have experience building Rust/Soroban smart contracts with an emphasis on secure financial accounting, overflow-safe arithmetic, and comprehensive contract testing. Since this issue directly impacts stake accounting and protocol safety, I'll focus on correctness, backward compatibility where applicable, and thorough validation.

My implementation plan is to:

• Review the current staking, reward, and slashing logic to identify every arithmetic operation that can overflow, underflow, or silently truncate.
• Replace unchecked arithmetic with checked_* operations throughout the accounting flow, returning explicit contract errors whenever an operation would exceed valid i128 bounds.
• Use guarded or saturating logic only where it is intentionally required by the protocol semantics, documenting every such decision.
• Ensure stake balances, accumulated rewards, and slashing calculations preserve accounting invariants under normal and edge-case conditions.
• Add or update events so stake, reward, and slashing state transitions remain fully indexable without changing existing event semantics unless required.
• Write comprehensive unit tests covering normal flows, boundary values (0, 1, i128::MAX, i128::MIN where applicable), overflow attempts, repeated reward accrual, multiple slashing scenarios, and invalid inputs.
• Verify no public contract entrypoint can panic due to arithmetic overflow.
• Run cargo fmt, cargo clippy, the complete test suite, and ensure the contract builds successfully to optimized WASM without unnecessary size regressions before submitting the PR.

I'll keep the changes focused on overflow-safe accounting while following the existing contract architecture and documenting any design decisions made during implementation.

[grantfox-oss]

🦊 GrantFox — @Paranoa-dev has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

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

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox!

@Paranoa-dev's PR #51 was approved and merged by @meshackyaro.

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

👏 Great work, @Paranoa-dev! Keep contributing to trustflow-protocol.