Testing: implement deterministic protocol state-machine tests

[josephchimebuka]

Summary

Add state-machine test suite that models legal and illegal transitions across protocol lifecycle actions.

Why this change matters

Round protocols are inherently stateful. State-machine tests prevent accidental transition bugs (e.g., resolve before end, recreate while active, claim semantics drift) and improve confidence during refactors.

Where to work

• contracts/src/tests/ (new state-machine module)
• possible helpers in test utilities for reusable transition setup

What contributors should implement

1. Define allowed states and transitions for each mode.
2. Encode both success and rejection transitions.
3. Validate persistence and event side-effects after each step.
4. Include regression cases from historical bugs.

Acceptance Criteria

• Transition graph is documented in test module.
• Illegal transitions consistently return expected errors.
• Tests cover both Up/Down and Precision modes.

Final result should look/feel like

The protocol lifecycle is test-documented as a contract of behavior, making future changes safer and easier to review.

Difficulty

intermediate

[Ekenesamuel8]

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

Hello boss
Please give me the task, I can fit it

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

[sweetesty]

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

hi maintainer please can i be assigned to this issue

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

[Adeolu01]

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

I would love to resolve this issue within the hour

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