reentrancy / double-application guard on the settlement settlement path

[mikewheeleer]

Summary

The settlement settlement path can be re-entered or applied twice, enabling double-spend-style bugs. Add a guard that makes settlement strictly once-only.

Why this matters

Double application on a value-moving path is a critical vulnerability. A once-only guard is mandatory hardening.

Requirements

• Mark settlement settlement as claimed/settled atomically before external effects.
• Reject a second settlement of the same settlement with a typed error.
• Order effects so state is committed before any outward call.
• Cover the double-call path with tests.

Technical guidance

• Set the settled flag first, then move value — never the reverse.
• Make the guard total across all settlement entrypoints.

Edge cases — each must have a test

• first settlement -> succeeds
• second settlement of the same settlement -> rejected
• concurrent double-call -> only one applies
• flag set before external effect
• unrelated settlements unaffected

Acceptance criteria

• All requirements and every edge case above implemented and covered by tests
• New unit and integration tests; existing tests still pass and no regressions
• Structured, typed errors (no leaked internals; stable codes)
• cargo fmt --check, cargo clippy --all-targets -- -D warnings, and cargo test all pass locally
• Code follows the repo's existing conventions; no duplication or dead code
• Short docs/comments explaining the design and any non-obvious decisions
• PR description explains the approach and includes Closes #<issue>

Out of scope

• Cross-contract reentrancy
• Formal verification

Rewards

Part of the GrantFox OSS / Official Campaign (FWC26) — this task may be rewarded. PR quality is assessed by AI: depth, correctness under edge cases, meaningful tests, and clean design are what earn the reward. Shallow changes (typos, formatting, trivial docs) do not qualify.

[rupesh-kumar-sah]

Hello @maintainers,

I would love to take this on. My planned approach:

• Implement reentrancy / double-application guard on the settlement settlement path with thorough authorization verification and clean data structures.
• Add Soroban test cases checking unauthorized invocations, edge values, and state updates.

I am ready to start immediately—please feel free to assign this to me!