feat(program-escrow): fee-on-transfer audit with regression tests (closes #946)

[precious-akpan]

Summary

Resolves #946 — Fee-on-transfer (FoT) token handling review for program-escrow.

This PR audits and validates program-escrow accounting under deflationary / fee-on-transfer token conditions. All existing tests continue to pass (78 passing, 0 failing).

---

Changes

contracts/program-escrow/src/test_fee_on_transfer.rs [NEW]

A purpose-built DeflatToken mock contract charges a configurable basis-point fee on every transfer / transfer_from call, faithfully simulating real-world FoT / deflationary tokens. 12 edge-case integration tests:

#	Test	What it validates
1	test_fot_lock_10pct_fee_credits_actual_received	10 % FoT fee on inbound lock — remaining_balance reflects actual_received, not requested amount
2	test_fot_lock_50pct_fee_credits_actual_received	50 % high-fee scenario
3	test_fot_repeated_locks_accumulate_actual_received	3× sequential locks accumulate correctly
4	test_fot_lock_v2_rejects_amount_exceeding_actual_balance	lock_program_funds_v2 detects FoT mismatch and panics
5	test_fot_lock_v2_accepts_actual_received_amount	lock_program_funds_v2 succeeds when amount == actual balance
6	test_zero_fee_token_behaves_like_standard_sac	Zero-fee token is identical to standard SAC token
7	test_fot_remaining_balance_never_exceeds_on_chain_balance	Invariant: accounting ≤ on-chain reality
8	test_fot_lock_then_payout_succeeds_within_actual_balance	Payout from FoT-funded pool succeeds
9	test_fot_lock_then_over_payout_panics	Over-payout panics — cannot draw more than credited balance
10	test_fot_funds_locked_event_reflects_actual_received	FundsLocked event carries actual_received, not requested amount
11	test_fot_cumulative_balance_invariant_across_sequential_locks	Multi-depositor sequential locks — invariant holds
12	test_fot_batch_payout_distributes_correctly_from_credited_funds	Batch payout from FoT-funded escrow

contracts/program-escrow/src/lib.rs

• Registered mod test_fee_on_transfer in the test module block.
• Fixed gas_optimization::efficient_math::safe_sub_zero — was using checked_sub which only returns None on arithmetic overflow (not on negative results); replaced with explicit if b > a { 0 } else { a - b }.
• Fixed test_draft_state::test_operations_succeed_after_publish — added token.approve() before lock_program_funds_from (which uses transfer_from, requiring a pre-approved allowance).

---

Security Notes

• Inbound (lock): lock_program_funds_from measures balance_before → balance_after and credits only actual_received. FoT fees are transparently reconciled.
• Inbound (v2 lock): lock_program_funds_v2 asserts contract_balance ≥ requested_amount before crediting, catching any FoT shortfall.
• Outbound (payout): The escrow debits remaining_balance by the requested release amount and calls token::transfer. If the token silently burns a fee on the outbound transfer, the recipient receives less than requested. This is documented but cannot be prevented at the escrow layer — it is inherent to non-standard FoT tokens.
• Recommendation: Use standard Stellar SAC tokens only. Non-standard FoT tokens are not a supported use case.

---

Test Results

running 84 tests
test result: ok. 78 passed; 0 failed; 6 ignored

[vercel]

@precious-akpan is attempting to deploy a commit to the Jagadeesh B's projects Team on Vercel.

A member of the Team first needs to authorize it.

[drips-wave]

@precious-akpan 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