task: audit balance ledger underflow and transfer ordering

[DTriple-p]

Closes: #546

Summary

This PR audits the internal balance ledger used by deposit/withdraw and tightens reconciliation between balance writes and SAC token transfers.

What changed

• Hardened BalanceStorage balance mutation helpers in contracts/predictify-hybrid/src/storage.rs
• Added positive-delta validation for balance mutations
• Made over-withdrawal return typed Error::InsufficientBalance without mutating storage
• Split debit computation from persistence with checked_sub_balance
• Updated withdraw in contracts/predictify-hybrid/src/balances.rs to use a strict check-transfer-then-debit flow
• Added regression tests for:
  • withdraw == balance
  • withdraw > balance
  • transfer failure does not leave a phantom debit
• Updated docs/contracts/BALANCES.md with storage and transfer-ordering invariants

Security Notes

Underflow / over-withdrawal

sub_balance no longer relies on wrapping behavior. It explicitly rejects debits larger than the recorded balance with Error::InsufficientBalance.

Transfer reconciliation

• Deposit remains transfer-then-credit
• Withdraw now computes the next balance, performs the SAC transfer, and only persists the debit after transfer success

This prevents phantom debits if the outbound token transfer fails.

Storage invariants

• Balance mutation deltas must be strictly positive
• Stored balances must never be negative
• Internal balance mutation is paired with the corresponding transfer ordering

Files changed

• contracts/predictify-hybrid/src/balances.rs
• contracts/predictify-hybrid/src/storage.rs
• docs/contracts/BALANCES.md

Test coverage added

Added focused balance tests covering:

• exact withdrawal to zero
• over-withdrawal typed error with no storage mutation
• failed transfer rollback / no phantom debit
• storage helper rejection of invalid deltas and overdraw

Test output

Attempted:

cargo test -p predictify-hybrid balance

[drips-wave]

@Agbasimere Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits