Refactor code structure and optimize performance across multiple modules

[GiftedGiftB]

Closes #1712

Description

What changed?

• Added multi-token reward support for quest registration: quests can now be registered with up to 3 reward tokens and percentage splits.
• Escrow accounting, deposits, payouts, and refunds now track balances per token.
• Added regression test test_multitoken.rs and updated property tests to account for the expanded escrow shape.
• Updated CHANGELOG.md with an Unreleased entry.

Why was it changed?

• To let projects distribute quest rewards across multiple Stellar assets (e.g., USDC + project token) while maintaining accurate per-token escrow balances and safe payout flows.

How was it implemented?

• New types: RewardAllocation and EscrowTokenBalance in types.rs.
• Quest now includes reward_allocations: Vec<RewardAllocation> while keeping single-token fields for backward compatibility.
• escrow module (escrow.rs) extended to:
  • track token_balances per escrow,
  • update per-token balances on deposit/payout/refund,
  • preserve CEI ordering for safe transfers.
• payout and submission flows updated to validate and record per-token escrow usage; claim_reward distributes configured percentages across assets.
• Tests: added test_multitoken.rs and adjusted property_tests.rs.
• See changed files list below.

---

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Tests only
• Breaking change (fix or feature that would cause existing functionality to break)
• Security fix
• Refactor (no functional change)
• Documentation update
• Configuration / DevOps change

---

Contract Changelog Discipline

Required for changes under contracts/earn-quest/src/** or any contract storage, event, or interface change.

• No contract implementation changes - not applicable
• Updated CHANGELOG.md under ## [Unreleased]
• If breaking, added a ### Breaking Changes entry with impact, affected files, and migration steps
• If breaking, used Conventional Commit breaking metadata (type(scope)!:) in the PR title or commit history
• If breaking, included a BREAKING CHANGE: explanation below

BREAKING CHANGE details (required for breaking contract changes):

BREAKING CHANGE:

---

Test Evidence

Required: All PRs must include test evidence. PRs missing this section will be blocked from merging.

Unit Tests

• New unit tests added for changed logic (test_multitoken.rs)
• All existing contract unit tests pass (cargo test run for earn-quest)
• Frontend / npm test N/A for contract-only changes

Test output / screenshot:

running 20 tests
...
test test_multitoken::test_multi_token_quest_tracks_escrow_and_payouts_per_token ... ok

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

running 14 property tests
...
test result: ok. 14 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 23.58s

Notes:

• Contract test runner: cd contracts/earn-quest && cargo test
• The new multi-token regression test confirms deposit & claim split behavior.

E2E / Integration Tests

• E2E tests added or updated (npm run test:e2e)
• Tested manually against a local environment

Endpoints tested: N/A (contract-only change)

---

Swagger / API Documentation

Required for any endpoint changes.

• No API changes - Swagger update not applicable

---

Error Handling Checklist

All items below must be verified before requesting review.

HTTP Exceptions

• Not applicable — no HTTP endpoints modified in this PR.

Input Validation (DTOs)

• Not applicable — no backend DTOs changed.

Guards & Authorization

• Not applicable — no endpoint changes.

Logging

• No sensitive data added; contract events already follow existing patterns.

Stellar / Soroban Contract Interactions

• Contract transfers use token::Client::try_transfer with CEI ordering to guard reentrancy.
• Escrow per-token validation prevents over-payout per asset.
• No hardcoded secrets in contract code.

---

Database / Migration

• No database changes - not applicable
• If deploying an upgradeed contract in-place: storage layout changed (new per-token arrays). Provide migration or perform a careful upgrade with storage compatibility checks.

---

Breaking Type / Model Changes (Frontend — FE-068)

• My PR touches none of the watched type/model paths — not applicable.

If the frontend will support multi-token quest creation/display, follow-up tasks:

• Add UI for reward_allocations (select up to 3 assets + percentages).
• Display get_escrow_info per-token balances.

---

Final Pre-Merge Checklist

• Branch is up to date with main / master (please rebase if needed)
• Linting passes (npm run lint) — run CI linters in your environment
• Formatting passes (npm run format / cargo fmt)
• No console.log / debug statements left in production code
• No hardcoded secrets, API keys, or environment-specific values in source code
• .env.example not applicable for contract-only changes
• Self-review completed - I have read through every line of the diff

---

Screenshots / Recordings (if applicable)

N/A for contract-only changes.

---

Additional Notes for Reviewer

• Focus review on:
  • escrow.rs: CEI ordering, per-token token_balances updates, refunds loop correctness.
  • quest.rs: reward_allocations validation (max 3, percentages sum to 100).
  • Storage implications: the contract storage layout changed; if this repo maintains deployed contract instances, please discuss an upgrade/migration plan. I can prepare a migration helper that converts single-token escrows into the new per-token shape if you want.
• I updated CHANGELOG.md under ## [Unreleased]. Consider adding a short migration note to your deployment docs if you plan to upgrade an on-chain instance.

---

If you want, I can now:

• Open the PR on GitHub and paste this body (I can do this via the web link or install gh and create it programmatically).
• Create a small migration helper script to convert existing escrow storage to the new shape.

Which should I do next?

[drips-wave]

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