[Quality][High] KYC and participant identity policy: state-transition invariants — QE-2026-08

[Baskarayelu]

Objective

enforce participant eligibility and identity transitions consistently at every entry point and during policy changes. Specifically, implement and verify state-transition invariants so the repository provides a deterministic, reviewable guarantee under normal, invalid, repeated, concurrent, and failure conditions.

Why this matters

The current behavior or coverage needs a production-grade guarantee here: a single unguarded path can bypass eligibility controls or invalidate an active position. Without this work, an invalid lifecycle transition leaving an object permanently inconsistent could survive review or deployment.

This is a substantive engineering change. It is not a typo fix, formatting-only change, documentation-only change, or trivial dependency update.

Priority

High

Scope

Area: security / compliance correctness

Starting points:

• src/kyc_policy.rs
• Add or update the closest focused unit, integration, property, or contract test beside the implementation.

Verify the existing implementation before changing it. Keep the change focused on this issue and preserve existing public behavior unless the acceptance criteria require a documented compatibility change.

Acceptance criteria

• define the legal transition matrix, enforce it at the entry point, and preserve all invariants across success and failure paths.
• Preserve compatible public behavior and make any required migration, error, or response-shape change explicit.
• Ensure rejected, stale, repeated, and failed operations leave no unauthorized or partial state.
• Add focused regression coverage that proves the invariant at the actual integration boundary.

Required validation

• cover every legal edge plus stale, repeated, skipped, and out-of-order transitions with invariant checks.
• Run formatter, lint, type/build checks, and the complete repository test suite.
• Run applicable security, contract, migration, gas/resource, or accessibility checks and record commands and results.
• Confirm generated artifacts, secrets, disabled checks, and unrelated refactors are absent from the change.

Documentation requirements

Document the design and invariants, failure behavior and compatibility impact, migration or rollback considerations, operational limitations, and security assumptions where applicable.

Out of scope

No unrelated refactors, typo or formatting-only changes, docs-only changes, broad dependency upgrades, disabled CI, generated noise, or secrets.

Contributor deliverables

Wait for maintainer assignment. Open a focused branch and reference this issue with Closes #<issue-number> or Fixes #<issue-number>. Check off every criterion, link the implementation and tests, include commands and results, and include a short security/correctness note.

Maintainer quality bar

The PR must change real behavior, address every criterion, include meaningful success and failure-path tests, cover relevant edge cases, remain focused, document compatibility, and provide complete validation evidence. Issue creation does not guarantee reward eligibility; PR quality is evaluated independently.

[martinifeanyi058-ship-it]

@martinifeanyi058-ship-it has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

Hello Maintanier, Please i would love to work on this issue as it's something i can resolve.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @martinifeanyi058-ship-it to this issue.

[Fale1278]

@Fale1278 has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

Hi! I'd love to take on this issue.
I can update src/kyc_policy.rs to enforce explicit state-transition invariants and participant eligibility rules across all entry points and policy changes. I will define a strict transition matrix to reject invalid, stale, repeated, or out-of-order identity transitions, ensure failed operations leave no partial state, and write comprehensive regression tests covering both legal transitions and edge-case failure paths. ETA: less than 24 hours.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Fale1278 to this issue.

[Adejumo-2]

@Adejumo-2 has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

please assign me

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Adejumo-2 to this issue.

[drips-wave]

Congratulations, @Fale1278! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on August 31, 2026.

🧑‍💻 @Fale1278: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊