Dispute System

Overview

The dispute system enables decentralized conflict resolution between users and merchants, with Circle Admins acting as first-instance arbitrators.

Dispute Flow

┌─────────────────────────────────────────────────┐
│                   OPENING                       │
│  User opens dispute with evidence               │
│  → Transaction becomes locked                   │
└─────────────────────┬───────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────┐
│                   RESPONSE                      │
│  Merchant has 48h to respond                    │
│  → Can attach counter-evidence                  │
└─────────────────────┬───────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────┐
│                   ANALYSIS                      │
│  Circle Admin has 7 days to decide              │
│  → Analyzes evidence from both sides            │
└─────────────────────┬───────────────────────────┘
                      │
              ┌───────┴───────┐
              │               │
              ▼               ▼
┌─────────────────┐   ┌─────────────────┐
│  USER WINS      │   │  MERCHANT WINS  │
│ → Refund        │   │ → Release funds │
│ → Slash merch.  │   │ → Case closed   │
└────────┬────────┘   └────────┬────────┘
         │                     │
         └──────────┬──────────┘
                    │
                    ▼
┌─────────────────────────────────────────────────┐
│              APPEAL (optional)                  │
│  Losing party can appeal within 48h             │
│  → Protocol reviews the decision                │
└─────────────────────────────────────────────────┘

Dispute Types

1. Non-receipt

• Claim: User paid but didn't receive crypto
• Expected evidence: Payment proof
• Typical resolution: Refund from protection fund

2. Incorrect amount

• Claim: Received less than expected
• Expected evidence: Transaction screenshot + receipt
• Typical resolution: Difference covered by fund

3. Excessive delay

• Claim: Merchant didn't complete in reasonable time
• Expected evidence: Transaction timeline
• Typical resolution: Cancellation + possible slashing

4. Fraud

• Claim: Deliberate malicious behavior
• Expected evidence: Complete documentation
• Typical resolution: Ban + total slashing + refund

---

Deadlines

Stage	Deadline	Consequence if not met
Merchant response	48h	Automatic ruling against
Admin decision	7 days	Admin slashing
Appeal	48h	Decision becomes final
Protocol review	14 days	Previous decision upheld

---

Penalties

For Merchants

Outcome	Penalty
Loses 1st dispute	Transaction value (from stake)
Loses 3+ disputes	Stake retained for review
Proven fraud	Permanent ban + 100% stake

For Circle Admins

Outcome	Penalty
Decision reversed (1x)	Warning
Decision reversed (2x+)	Partial slashing
Ignores dispute	0.5% stake per occurrence
Proven collusion	Ban + 100% stake

---

Evidence

Accepted types

• Screenshots with metadata
• Bank receipts (PDF)
• Chat history (from app)
• On-chain transactions (hash)
• Videos (special cases)

Validation

• Metadata verified when possible
• Cross-reference with on-chain data
• Chat history is official (recorded)

---

Technical Implementation

Dispute states

enum DisputeState {
    Open,           // Awaiting response
    UnderReview,    // Admin analyzing
    Resolved,       // Decision made
    Contested,      // Under appeal
    Final           // Case closed
}

Data structure

struct Dispute {
    uint256 transactionId;
    address claimant;      // Who opened
    address respondent;    // Against whom
    DisputeState state;
    uint256 openedAt;
    uint256 resolvedAt;
    bytes32 evidenceHash;  // IPFS hash
    address resolver;      // Admin who decided
    bool claimantWon;
}

Events

event DisputeOpened(uint256 indexed disputeId, uint256 transactionId);
event DisputeResolved(uint256 indexed disputeId, bool claimantWon);
event DisputeContested(uint256 indexed disputeId);
event DisputeFinalized(uint256 indexed disputeId);

---

Admin Metrics

The protocol tracks admin performance:

Metric	Impact
% disputes resolved in under 48h	Ranking
% decisions appealed	Negative score
% decisions reversed	Potential slashing
Average resolution time	Ranking

Admins with good metrics:

• Rank higher in the system
• Attract more merchants
• May receive protocol bonuses