Implement Dispute Raising Function

[meshackyaro]

Description

This issue aims to address the implementation of Implement Dispute Raising Function.

The core objective is to: Create the raise_dispute entrypoint allowing either party to halt escrow release and call for a jury.

By completing this feature, we will ensure that the TrustFlow protocol maintains its high standards for security, usability, and decentralized logic. This issue requires careful attention to the Smart Contracts architecture and adherence to the existing project conventions.

When picking up this issue, please ensure you document any new dependencies or architectural decisions made during development.

Component

Smart Contracts

Difficulty

🔴 Hard

Tasks

• Review Soroban architecture and soroban-cli usage
• Implement Rust logic for: Implement Dispute Raising Function
• Write comprehensive unit tests in Rust
• Ensure proper event emission for indexing
• Run cargo fmt and cargo clippy
• Verify soroban contract build successfully compiles to WASM without bloating size

Acceptance Criteria

• Feature accurately implements the objective: Create the raise_dispute entrypoint allowing either party to halt escrow release and call for a jury.
• Any PR that introduces TypeScript/Rust errors is automatically blocked
• CI pipeline runs in under 3 minutes per PR
• Code is properly reviewed and approved by codeowners

Estimated Time

1-3 days

[davidmaronio]

Relevant experience
Soroban and Rust smart contract engineer. I've built escrow contracts with funded/release/refund state machines and the auth and event patterns that go with them, so a dispute entrypoint that gates release and signals a jury is squarely in my lane.

Understanding of the problem
raise_dispute lets either party to an escrow halt the normal release and call for a jury. The part that matters most is that halting release has to be enforced, not just recorded. It isn't enough to store a Disputed flag; the release path itself has to check that state and refuse to pay out while a dispute is open, otherwise the escrow still releases and the objective isn't met. This issue is the raise side, with jury selection and resolution presumably handled separately.

Proposed approach

• Authorization: require_auth on the caller and verify the caller is one of the two parties to this specific escrow, so an arbitrary authenticated address cannot dispute someone else's escrow.
• State gating: allow raise_dispute only from the legal source states (funded/active, not already released, refunded, completed, or disputed), and make a second raise on an already-disputed escrow error rather than double-trigger.
• Transition and enforce: move the escrow into a Disputed state and wire that state into the release entrypoint so release is blocked while disputed. This is the core of halting release.
• Record and emit: persist the dispute metadata (status, who raised it, ledger/timestamp) keyed to the escrow, and emit a structured DisputeRaised event so indexers can pick it up.

Edge cases

• A non-party caller is rejected.
• raise_dispute from a terminal or already-disputed state is rejected.
• Release is provably blocked once a dispute is open.

Testing
Comprehensive Rust unit tests: either party can raise; a non-party cannot; raising from an invalid state fails; the release path is blocked after a dispute is raised; and the DisputeRaised event is emitted with the right fields.

Open questions

• Where is the boundary between this issue and the jury flow? Does raise_dispute need to register with an existing jury/arbitration module, or set status and emit the event for a later resolution entrypoint to consume?
• Should a reason or evidence reference be a parameter on raise_dispute, or is that out of scope here?
• Is there a dispute window (for example, only disputable before an auto-release timeout)?

Conventions and scope
I'll follow existing project conventions and document any new dependencies or architectural decisions, as the issue asks. cargo fmt and cargo clippy clean, and soroban contract build compiling to WASM without bloating size. Jury selection and resolution stay out of scope for this PR unless you want them folded in.

Availability
This fits the 1 to 3 day estimate and I can commit the time. Happy to confirm the jury-boundary question up front. Please assign this to me and I'll start with the entrypoint, the release-path gate, and the tests.

[Akpolo]

I'd like to take the raise_dispute issue. I build Soroban and Rust contracts, including escrow flows with funded, release and refund state machines, so a dispute entrypoint that gates settlement and emits for indexing is in my lane.

The point I'd hold onto is that halting release has to be enforced on the release path, not just recorded. A Disputed flag the release entrypoint doesn't check still lets the escrow settle, so this is really two coupled edits: the new entrypoint plus a guard on release. raise_dispute would require_auth on the caller and verify they're one of the two parties to that specific escrow, allow the call only from an active, funded state (rejecting released, refunded, completed or already-disputed, and erroring on a repeat), move the escrow to Disputed, block release while it's open, persist the dispute metadata, and emit a DisputeRaised event for indexers.

Tests would cover both parties raising, a non-party rejected, invalid-state rejection, release blocked after a dispute, and the event fields, with cargo fmt and clippy clean and the WASM build not bloating. I'll document any new dependencies or decisions as the issue asks.

One thing I'd confirm: whether raise_dispute hands off to an existing jury module or just sets status and emits for a later resolution entrypoint, since that sets this PR's boundary. This fits the 1 to 3 day estimate. Please assign it to me and I'll start with the entrypoint and the release guard.

[grantfox-oss]

🦊 GrantFox — @Akpolo has been assigned to this issue as part of the Official Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #3)
2. Your PR will be reviewed by the trustflow-protocol maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Official Campaign campaign!

@Akpolo's PR #27 was approved and merged by @meshackyaro.

🏆 @Akpolo: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (296 total points). Track your full progress on GrantFox.

👏 Great work, @Akpolo! Keep contributing to trustflow-protocol.