[melanindebbie]

Summary

Issue #1137 asks to align the emitted contract events with the Partial claim state so that an indexer can reconstruct the committed action exactly once from event data alone. This PR confirms the current behavior and locks it in with a targeted regression test, plus documentation of the invariant. No contract logic changes are needed or made.

closes #1137

What was checked

The Partial claim workflow named two scenarios to confirm: a one-unit claim followed by remaining claim, and a transfer failing after authorization.

Both were reviewed against contracts/src/lib.rs and the backend indexer (backend/src/services/indexer.ts), which deserializes StreamClaimed by field name.

• claim() computes the payout, calls token_client.transfer(contract, recipient, amount) at lib.rs:906, updates stream.claimed_amount, persists state, and only then publishes StreamClaimed at lib.rs:916. StreamCompleted is published immediately after, only when the claim completes the stream.
• StreamClaimed carries amount (the recipient payout for this call) and claimed_amount (the cumulative claimed balance after the call), so the event is already a complete, self-describing record of a single committed claim.
• Because the event is published strictly after the transfer and the accounting update, a payout that fails after the recipient has already authorized reverts the whole transaction and emits no event. Soroban rolls back the failed invocation's storage writes and events, so the indexer never sees a claim that did not move tokens.

The existing #1138 tests already cover the claim mechanics and per-event field values, and the #1136 test covers recipient authority. None of them asserted the property the indexer actually depends on: that the event stream ALONE reconstructs the committed state exactly once.

What changed

1. contracts/src/test.rs — added test_1137_events_reconstruct_partial_claim_state_exactly_once. It replays the emitted StreamClaimed events the way the indexer does, without ever reading contract storage, across a one-unit claim, a partial claim, a failed payout, and the completing claim. It asserts:

   • each event's claimed_amount equals the running sum of the amount fields, and the balance advances monotonically, so no payout is missed or double-counted;
   • the rolled-back (failed-transfer) claim contributes zero events;
   • exactly one StreamClaimed appears per committed claim;
   • StreamCompleted is never treated as a payout (summing it alongside the claims would over-report the balance).

2. contracts/src/lib.rs — expanded the StreamClaimed struct doc and the claim() ordering doc to state that StreamClaimed is the authoritative partial-claim record and how a failed payout produces no event.

3. contracts/CONTRACT_ABI.md — added a subsection documenting the partial-claim reconstruction invariant and pointing to the new and existing tests.

Alternatives considered

• Modify claim() to emit an additional payout or remaining-balance field. Rejected: the existing amount plus claimed_amount already reconstruct payout and balance, and adding a field is unnecessary churn that the indexer does not currently consume.
• Test the event payload field-by-field only. Rejected as insufficient: #1138 already does that. The distinct acceptance criterion in [CONTRACT] Align events with Partial claim state #1137 is exactly-once reconstruction from events alone, which is what the new test encodes.
• Rely on get_stream storage reads in the test. Rejected: the acceptance criterion is specifically that event data (not storage) lets the indexer reconstruct the action, so the test derives everything from the emitted events and only cross-checks against storage.

Verification

cargo test --lib on the contracts crate: the new test_1137_... passes, along with the adjacent #1133, #1136, and #1138 claim tests.

Note for reviewers: the contracts test binary does not currently compile on main as checked out, independent of this change. test_1136_partial_claim_authority_is_checked_again_for_remainder and test_1138_transfer_failure_after_authorization_rolls_back call assert_eq! on Vec<(Symbol, Val)>, and soroban_sdk::Val does not implement PartialEq. That is pre-existing breakage outside the scope of #1137, so this PR leaves those lines untouched.

[vercel]

@melanindebbie is attempting to deploy a commit to the ritik4ever's projects Team on Vercel.

A member of the Team first needs to authorize it.

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: dec448e4-d05f-406c-b052-00f99013674c

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}