Multi-asset settlement — accept token address per `receive_payment` and track per-token developer balances

[greatest0fallt1me]

Description

CalloraSettlement is hard-wired to a single USDC token. To support stablecoin diversification (USDC + EURC + native XLM wrappers) we need per-asset accounting: a new (asset, developer) -> i128 balance map and an asset parameter on receive_payment and withdraw_developer_balance.

Requirements and Context

• New StorageKey::DeveloperBalanceByAsset(Address, Address) and StorageKey::GlobalPoolByAsset(Address)
• receive_payment(caller, asset, amount, to_pool, developer) — preserve old single-asset path behind a backwards-compat shim
• Must be secure, tested, and documented
• Should be efficient and easy to review

Suggested Execution

1. Fork the repo and create a branch

   git checkout -b feat/settlement-multi-asset

2. Implement changes
   • contracts/settlement/src/lib.rs (new storage keys, function signatures, error variants)
   • contracts/settlement/src/test.rs (two-asset scenario)
   • Update INVARIANTS.md to scope conservation per-asset
3. Test and commit
   • cargo test -p callora-settlement multi_asset
   • Cover edge cases: same developer credited in two assets, single-asset legacy callers
   • Include test output and notes in the PR

Example commit message

feat(settlement): add multi-asset receive_payment and per-asset balances

Acceptance Criteria

• Backwards-compatible default-asset path still works
• Per-asset pool and per-asset developer balance views added
• Conservation invariant holds per-asset in tests

Guidelines

• .rs only under contracts/.../src/, NatSpec-style /// doc comments, 95% coverage
• Use real Soroban SDK idioms; no unwrap() in production paths
• Clear documentation and inline comments
• Timeframe: 96 hours

[Phantomcall]

@Phantomcall has applied to work on this issue as part of the Stellar Wave Program's 6th wave.

I'd like to work on this issue.

I have experience building Soroban smart contracts and extending token/accounting logic while maintaining backwards compatibility. For this task, I'll implement per-asset settlement by introducing asset-scoped storage for developer balances and global pools, while preserving the existing single-asset flow through a compatibility shim so current integrations continue to work unchanged.

I'll update the settlement contract using idiomatic Soroban patterns (avoiding unwrap() in production paths), add comprehensive tests covering multi-asset accounting, legacy callers, and conservation invariants, and update INVARIANTS.md and inline documentation so reviewers can easily verify the design and correctness.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Phantomcall to this issue.

[drips-wave]

Congratulations, @Phantomcall! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on June 30, 2026.

🧑‍💻 @Phantomcall: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Official Campaign campaign!

@Phantomcall's PR #459 was approved and merged by @greatest0fallt1me.

🏆 @Phantomcall: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (576 total points). Track your full progress on GrantFox.

👏 Great work, @Phantomcall! Keep contributing to CalloraOrg.