test(invoice-token): cross-contract integration test suite for escrow…

[neyij]

…-triggered burn-on-settlement callback (#382)

Description

Added a cross-contract integration test suite for the escrow-triggered invoice token burn-on-settlement flow.

The new MockSettlementEscrow harness simulates the interaction between the settlement escrow and InvoiceToken contracts, covering both direct burn and allowance-based burn_from settlement flows.

The integration tests verify successful settlement, allowance consumption, authorization behavior, expected failure paths, emitted events, residual balances, and transfer unlock behavior after full settlement.

Closes #382

Type of Change

• 🐛 Bug fix (non-breaking change which fixes an existing issue)
• ✨ New feature (non-breaking change which adds functionality)
• 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
• 📝 Documentation update
• 🎨 UI/UX improvement
• ♻️ Code refactoring
• ✅ Test addition or update
• 🔧 Configuration change

Checklist

• My code follows the code style of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published

Testing

Added a cross-contract integration test suite using a MockSettlementEscrow contract to exercise the complete escrow-to-token settlement flow.

How to Test

1. Run the invoice token test suite:
   cargo test -p invoice-token
2. Deploy the mock settlement escrow and InvoiceToken contracts using the test environment and configure the required authorization and token state.
3. Execute the burn_on_settlement and burn_from_on_settlement flows and verify successful token burning, allowance deduction, and emitted events.
4. Execute the failure scenarios and verify the expected errors are returned for insufficient balance, invalid amount, insufficient allowance, expired allowance, and paused contract states.
5. Complete a full settlement and verify that token transfers are unlocked and any remaining balances are preserved correctly.

Test Coverage

• Unit tests added/updated
• Integration tests added/updated
• E2E tests added/updated (if applicable)
• Manual testing completed

Screenshots (if applicable)

Not applicable — this change adds Soroban cross-contract integration tests and does not affect the user interface.

Additional Notes

The integration test harness validates the interaction between the settlement escrow and InvoiceToken rather than testing token burning in isolation.

Coverage includes:

• Successful burn_on_settlement flow
• Successful burn_from_on_settlement flow
• Allowance deduction and verification
• InsufficientBalance
• InvalidAmount
• InsufficientAllowance
• AllowanceExpired
• Paused
• Post-settlement transfer unlock
• Residual balance preservation
• Event emission from both contracts

This provides coverage for the authorization and state transitions that occur when invoice tokens are burned as part of escrow settlement.

For Reviewers

Please focus on:

• Code quality and readability
• Test coverage
• Security implications
• Performance impact
• Breaking changes

In particular, review the cross-contract authorization flow, allowance consumption during burn_from, error propagation, event assertions, and the post-settlement transfer unlock behavior.

[drips-wave]

@neyij 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