Fix/test allowance rollback on transfer fail

[onyekachi66]

Closes #38

Root cause

The transfer_from function in token-wrapper implements a write-before-external-call pattern (updating allowance storage before calling the underlying token.transfer). While this ordering is structurally safe due to Soroban's transaction-level rollback guarantees—which revert all state changes in a host invocation if it fails—this critical assumption was entirely unverified by the test suite and lacked explanatory documentation in the code.

What changed and why

1. Added explicit documentation: Included a comment above the allowance state write in transfer_from stating precisely why the write-before-external-call ordering is safe, leaning on Soroban's atomicity model.
2. Added failure-path test coverage: Implemented test_allowance_state_rolls_back_if_underlying_transfer_fails. This test intentionally triggers an underlying token transfer failure (by exceeding the owner's true token balance while remaining within the authorized allowance limit).
3. Verified the invariant: The new test asserts that try_transfer_from fails and then explicitly checks that the original allowance state in storage is completely unchanged, proving the rollback works as assumed. No logic bug was present, so no contract reordering was necessary—the fix is purely closing this coverage/documentation gap.

Definition of done — addressed item by item

• New test reproducing a failing underlying-token-transfer scenario after the allowance check passes.
  • Implemented test_allowance_state_rolls_back_if_underlying_transfer_fails where the allowance is valid but the token.transfer fails due to insufficient balance on the token contract side.
• Test asserts allowance storage is unchanged after the failed attempt.
  • The test explicitly checks client.allowance(...) post-failure and asserts it equals the original un-debited amount.
• If the assumption turns out to be wrong (allowance is NOT rolled back), this becomes a real bug fix... rather than just a coverage gap.
  • The assumption proved correct; Soroban successfully rolls back the allowance write. This PR only adds the coverage and documentation to lock it in.

Evidence this actually runs

running 11 tests
test tests::test_allowance_unset_pair_returns_zero ... ok
test tests::test_approve_and_allowance ... ok
test tests::test_approve_negative_amount_fails ... ok
test tests::test_approve_overwrites_previous_allowance ... ok
test tests::test_approve_past_expiry_fails ... ok
test tests::test_transfer_from_expired_allowance_fails ... ok
test tests::test_transfer_from_happy_path ... ok
test tests::test_transfer_from_insufficient_allowance_fails ... ok
test tests::test_transfer_from_succeeds_exactly_at_expiry_ledger ... ok
test tests::test_transfer_from_zero_amount_fails ... ok
test tests::test_allowance_state_rolls_back_if_underlying_transfer_fails ... ok

test result: ok. 11 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.05s

Tests

Added test_allowance_state_rolls_back_if_underlying_transfer_fails to the token-wrapper unit tests. It asserts:

• try_transfer_from correctly fails when the underlying token transfer fails.
• Reading the allowance afterwards returns the unmodified original value, proving Soroban rolled back the storage debit.

Regression check

No existing logic was modified, only comments and tests were added. Existing tests covering the transfer_from happy path and earlier failure paths (insufficient allowance, expired allowance) were re-run and confirmed to still pass, ensuring no regression on core token wrapper behavior.

Checklist

• Every Definition of done bullet above is checked and explained, not just checked
• Evidence block above is filled in with real output, not omitted
• New/updated tests are included and shown passing
• No leftover console.log/TODO/debug code
• Related/adjacent behavior re-verified, not assumed unaffected