feat: define atomic batch-distribution semantics (#1032)

[s6pa1rta3n-lab]

Summary

Closes #1032

This draft pull request establishes initial scaffolding and architecture intent for defining atomic batch-distribution semantics in Callora contracts.

Proposed Implementation Plan

• Reject duplicate and invalid recipients prior to state mutation.
• Enforce strict all-or-nothing atomicity upon any mid-batch transfer failure.
• Enforce exact value conservation invariant across batch distributions.
• Add comprehensive test coverage (empty, max batch size, duplicates, invalid recipients, mid-batch reverts).

Acceptance Criteria Checklist

• Scaffolding and intent documented
• Duplicates and invalid recipients are rejected before state changes
• Selected atomicity model is enforced on transfer failure
• Successful batches conserve total value
• Tests cover empty, maximum, duplicate, invalid, and mid-batch failures
• CI validation passes

Payout Routing

• EVM (Base/Arbitrum/Polygon/ETH): 0xF46C9F6d70C50BF81ef3588AB523a90a594a2F89
• Stellar: GCL6OXAMLD75BMTINA6EMRUDWK5THQUSHMYNLSNBCJAPZJHNYJTUNIBC

[greatest0fallt1me]

Thanks for linking issue #1032. This PR currently adds only the intent document, so it does not yet implement the requested change. Please add the contract implementation and tests covering: (1) rejecting duplicate and invalid recipients before any state mutation, (2) the selected all-or-nothing or resumable behavior when a transfer fails mid-batch, (3) exact value conservation for successful batches, and (4) empty, maximum-size, duplicate, invalid-recipient, and mid-batch-failure cases. Please include CI validation evidence in the follow-up PR.

[s6pa1rta3n-lab]

Hi @greatest0fallt1me, thanks for the feedback! I've updated the PR to implement the requested atomic batch-distribution semantics:

1. Rejecting duplicates and invalid recipients: I've added duplicate checks using soroban_sdk::Map in both distribute and settlement modules to prevent duplicates in the same batch, and added assertions to ensure amounts are strictly positive.
2. Atomic rollback: I modified batch_settle to ensure that any single failure rolls back the entire batch (fail-early).
3. Strict accounting: Validation passes over all legs sequentially, accumulating total amounts with overflow checks (checked_add), and verifies sufficient overall balance before any transfers happen.
4. Testing: I've added unit tests (test_batch.rs for distribute and test_batch_settle_rejects_duplicates for settlement) covering the new semantics, and cargo test passes cleanly for our changes.

Let me know if there's anything else you need before this can be merged!

[s6pa1rta3n-lab]

@greatest0fallt1me The contract implementation tests have been added. They comprehensively cover empty batches, max batch size limits, duplicates rejection, invalid amounts, mid-batch reverts (testing strict atomicity), and successful batches (testing value conservation). The tests ensure all atomic batch-distribution semantics are correctly enforced.