typed error taxonomy with exhaustive negative-path tests for settlement

[mikewheeleer]

Summary

settlement returns generic or panicking failures, so callers can't distinguish causes and some rejections are untested. Introduce a typed error enum and cover every negative path.

Why this matters

Untyped failures and untested rejections hide bugs and confuse integrators. A typed taxonomy + negative tests is correctness insurance.

Requirements

• Define/extend a typed error enum covering each settlement failure with a stable code.
• Replace generic failures/panics with the typed errors.
• Add tests asserting each guarded entrypoint returns the right error.
• Document the codes and when they fire.

Technical guidance

• Give each variant a unique, stable discriminant.
• Assert the exact error in tests, not just failure.

Edge cases — each must have a test

• each guard -> its specific typed error
• invalid input -> correct code
• unauthorized -> correct code
• no path panics
• codes are stable and documented

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

• Error message localization
• Off-chain error mapping

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]

Hey team,

I would like to resolve this issue. Here is my proposed execution plan:

• Implementation: Implement typed error taxonomy with exhaustive negative-path tests for settlement with explicit require_auth checks, clean storage layouts, and robust Soroban contract logic.
• Testing: Add comprehensive unit tests verifying both happy-path invocations and unauthorized revert scenarios.

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

[Rodrigoue9]

Hi team, I would like to work on #449.

Relevant Experience

• Rust & Soroban contract developer with focus on formal verification, typed error handling, and test-driven development.

Proposed Approach

1. Typed Error Enum: Create #[contracterror] #[repr(u32)] pub enum SettlementError covering all domain error cases.
2. Exhaustive Negative Tests: Write dedicated unit tests verifying that every assertion and boundary condition triggers the exact expected error code.
3. Documentation: Document every error discriminant and failure rationale in the contract docstrings.

Estimate: First PR in 24h.

[tokenjunkielabs]

@tokenjunkielabs taking #449 for the GrantFox OSS campaign. I will implement the complete typed settlement error taxonomy, stable codes, negative-path coverage, and documentation, and submit the sponsor PR closing #449.