feat: per-token settlement balances

[jerryjuche]

close #495

Summary

Implements per-token settlement support for multi-asset revenue tracking (Closes #495).

What changed

• contracts/settlement/src/types.rs (new): StorageKey::DeveloperBalance(Address, Address) — map keyed by (developer, token). Legacy DeveloperBalanceV1(Address) retained for migration. Added MAX_BATCH_SIZE (50) and MAX_DEVELOPER_BALANCES_PAGE_SIZE (100) constants. DeveloperBalance struct includes token field.

• contracts/settlement/src/lib.rs: All receive_payment, batch_receive_payment, withdraw_developer_balance, force_credit_developer, and view functions now accept a token: Address parameter. The migrate_developer_balance function reads legacy DeveloperBalanceV1 and writes to per-token DeveloperBalance(dev, usdc).

• contracts/settlement/src/test_multi_asset.rs (new): 10 tests covering:

  • Two-token independent balances (single developer, two developers)
  • Withdraw asserts token (cross-token rejection)
  • Migration (happy path, idempotent, unauthorized, no USDC)
  • Batch receive with token

• contracts/vault/src/lib.rs: Settlement trait updated to pass token: Address. Both deduct and batch_deduct now pass the underlying token address.

• contracts/settlement/src/test.rs, test_invariant.rs, test_views.rs, vault/test_reentrancy.rs, tests/e2e_full_cycle.rs: Updated all call sites for new signatures.

Key design decisions

• Balance key is StorageKey::DeveloperBalance(dev, token) — O(1) point read/write, no iteration
• Legacy DeveloperBalanceV1 kept at discriminant 5; new key at discriminant 6 (backward-compatible)
• Migration is admin-only, one-way, idempotent
• Withdraw checks balance against the specific token's storage key (not a combined balance)

Acceptance criteria checklist

• Map keyed by token
• Migration works
• Withdraw asserts token
• Two-token test
• require_auth on all state-changing entrypoints
• Overflow-safe checked arithmetic (no unwrap() in production)
• NatSpec-style rustdoc on public functions

Test output

141 passed; 3 failed (all pre-existing, unrelated to this PR)

The 3 pre-existing failures are:

1. test_cancel_admin_transfer_success — unwrap() on None (vesting logic bug)
2. test_get_all_developer_balances_large_index — expected GasExhaustionRisk error
3. test_upgrade_and_get_version — non-existent WASM hash

Follow-ups

• Fix the 3 pre-existing test failures (out of scope)
• Consider adding a get_all_developer_balances for all tokens simultaneously (requires index per token)

Security note

All state-changing entrypoints require authorization. Arithmetic uses checked_add/checked_sub. No unwrap() in production code paths. The token parameter is validated by the balance key — a wrong token simply reads a different storage slot. Migration is admin-only and idempotent.

[drips-wave]

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

[greatest0fallt1me]

Merged via direct push to main (admin)