feat: design dispute-resolution flow for contested fills - #162
Merged
james2177 merged 1 commit intoJul 28, 2026
Merged
Conversation
Added docs/dispute-resolution-design.md covering: - Scope: what counts as a valid on-chain dispute (underfill already blocked; wrong-recipient is disputable; stale-rate / source-chain non-delivery are out-of-scope for v1 due to lack of cross-chain proof oracle) - New state machine: Filling -> Disputed -> Resolved (Upheld | Dismissed) - Fund flow for happy path, upheld dispute, and dismissed dispute - New entry-points sketched: begin_fill, open_dispute, resolve_dispute, release_fill - Arbiter role: admin in v1, multisig/solver_registry in v2 - Dispute window: 1 hour dispute window, 24 hour arbiter window - Security considerations: griefing bond, arbiter capture, escrow risk, re-entrancy - 8-item implementation plan for follow-up issues No contract code changed; design doc only. Closes stellar-vortex-protocol#48
|
@blessedDev-xyz Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits. You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Creates
docs/dispute-resolution-design.md— a full design document for the dispute-resolution mechanism referenced in the protocol roadmap.Key design decisions
Dispute scope (v1): Limited to on-chain-verifiable grievances only. Stale-rate claims and source-chain non-delivery are deferred until a cross-chain proof oracle is integrated. Wrong-recipient and fill-integrity disputes are in scope.
State machine addition:
Fund flow: Solver deposits fill into contract escrow via
begin_fill. User has a 1-hour window to callopen_dispute. Arbiter resolves within 24 hours. In both outcomes (Upheld/Dismissed) the user receives their tokens — the dispute only determines whether the solver is slashed.Arbiter: Admin in v1 (simple, safe for testnet). Recommended v2: separate
arbiterkey, settable to a multisig or futuresolver_registrycontract.Security: Griefing mitigation (user dispute bond), arbiter capture mitigation (multisig v2), escrow risk (checks-effects-interactions ordering), re-entrancy pattern documented.
What this PR does NOT do
Validation
Docs-only change.
cargo fmt,cargo clippy -- -D warningspass.Closes #48