V2-SC-016 — Implement Dispute Opening and Challenge Bond Custody

[dDevAhmed]

V2-SC-016 — Implement Dispute Opening and Challenge Bond Custody

Overview

Implement one valid challenge per claim, exact challenge timing, bond locking, and transition into Disputed.

Problem Context

A provisional result must be challengeable without letting spam or privileged actors halt claims for free. Challenge bonds need the same protected custody guarantees as verifier stake.

This issue belongs to V2-EPIC-SC-001 — Canonical Contract Topology and Deployment. Existing repository issues are historical only; their titles, labels, closure state, or partial implementations do not satisfy this issue.

Technical Scope

• Accept challenges only during ChallengeWindow and before the frozen deadline.
• Lock the configured bond asset and amount through StakeVault.
• Record challenger, challenged outcome, bond lock, appeal parameters, and dispute identifier.
• Reject recursive or duplicate challenges and emit DisputeOpened.
• Transition the claim into Disputed atomically.

The contributor must begin by auditing current files that overlap this scope. Reusable logic may be retained only when it conforms to the governing V2 interfaces, events, authority boundaries, and tests. The pull request must identify reused, replaced, and deprecated paths.

Security and Integrity Requirements

• No dispute record may exist without a successful bond lock.
• Prevent governance, guardian, or treasury bypass of bond requirements.
• Protect against reentrancy and unsupported bond assets.
• Preserve blockchain authority and every applicable protocol invariant.
• Do not add secrets, production credentials, dummy production addresses, backend settlement authority, or Stellar/Freighter runtime dependencies.

Required Tests

• Successful challenge at valid timestamps.
• Early, late, duplicate, finalized, paused, insufficient allowance, and failed-transfer tests.
• Atomicity test for state and custody.
• Run the repository’s complete required Hardhat and Foundry suites and report unrelated pre-existing failures separately.
• Add regression coverage for every defect or unsafe legacy behavior removed by this work.

Acceptance Criteria

• Exactly one appeal path can open per claim.
• Bond and dispute records reconcile.
• Claim state changes only after successful custody.
• Events contain all appeal-round initialization inputs.
• All new and existing relevant tests pass on the final commit.
• Static analysis and formatting introduce no new unresolved finding.
• Documentation and generated artifacts affected by the change are current.
• The pull request maps evidence to every acceptance criterion.

Deliverables

• Production-quality Solidity, interfaces, libraries, deployment code, or test code required by the scope.
• Unit and higher-level tests described above.
• NatSpec and contract-specific technical documentation.
• A pull-request summary covering architecture, security analysis, gas or storage impact, migration implications, and residual risks.
• Evidence of commands run and their results.

Dependencies

• V2-SC-004 — Implement Versioned Protocol Configuration Registry
• V2-SC-009 — Implement Stake Vault Custody and Lock Ledger
• V2-SC-015 — Implement Provisional Settlement Engine

This issue must not be assigned while any required dependency is unresolved or incompatible with the reviewed interface version.

Non-Goals

• Resolving the appeal or paying a challenger reward.
• Off-chain adjudication.
• Creating, modifying, reopening, or relabelling historical GitHub issues.
• Applying the external Stellar Wave label.

Complexity and Review

• Complexity: high
• Repository: DigiNodes/truthbounty-contract
• Risk: protocol-critical
• Required review: human maintainer review; automatic merge is prohibited
• Candidate state: wave-candidate

References

• Protocol specification §15
• TruthBounty Protocol V2 Specification
• TruthBounty V2 Engineering Blueprint
• ADR-0001 — Canonical V2 Contract Topology
• Drips Stellar Wave Operations

---

🏷 Labels

• contracts
• disputes
• protocol-critical
• web3
• complexity-high
• wave-candidate
• staking
• security

---

[Samaro1]

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

Gm gm boss. I would like to take this one on. I can audit existing dispute-related code first per the reuse requirement, implement the challenge-window and deadline-gated dispute opening flow that locks the bond through StakeVault, record the challenger, outcome, bond lock, and appeal parameters atomically alongside the DisputeOpened event, reject recursive or duplicate challenges, ensure the claim only transitions to Disputed after a successful bond lock with no governance/guardian/treasury bypass, and cover it with the full valid/early/late/duplicate/finalized/paused/insufficient-allowance/failed-transfer and atomicity test suite plus the required Hardhat and Foundry runs. Please assign it to me.

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

[felixumeh]

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

Hi maintainer, I would like to solve this issue for you as it's part of my current study. I will deliver PR as soon as possible

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

[Oyixah]

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

Hi, can i work on this issue please

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

[emmyafolly123-coder]

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

Hello Maintainer, I’m interested in working on this issue and I’m ready to start immediately. I’m committed to resolving it properly and delivering quality work. Please consider assigning this issue to me. Thank you.

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

[yunus-dev-codecrafter]

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

Hi! I've carefully reviewed the entire task description and fully understand the requirements and expected outcome.
I have experience working on similar tasks and I'm confident I can complete this within about an hour. I'd be happy to take ownership of this issue and submit a clean, well-tested solution promptly.
If it's available, please assign it to me. Thank you!

ℹ️ Repo Maintainers: To accept this application, review their application or assign @yunus-dev-codecrafter to this issue.

[drips-wave]

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

🧑‍💻 @Oyixah: 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 🌊