Dispute Resolution

FiDeal uses a three-tier dispute resolution system. If either party is unhappy with a transaction, disputes are resolved through structured negotiation, AI evaluation, and human review — in that order. Each tier escalates only if the previous one fails.

The Three Tiers

Tier 1: Peer Resolution (No Fee)

When a dispute is raised, the payee has a window to respond. Both parties try to resolve it directly.

How it works:

1. The payer raises a dispute with a category and statement.
2. The escrow enters RESPONSE_PENDING state.
3. The payee responds with one of four actions:
   • CONCEDE_FULL — Payee agrees to a full refund. Escrow settles immediately.
   • CONCEDE_PARTIAL — Payee offers a partial refund (specified in basis points). Payer can accept.
   • COUNTER — Payee disputes the claim with their own evidence. Payer can accept or escalate.
   • REJECT — Payee rejects the dispute entirely. Auto-escalates to Tier 2.
4. If the response window expires with no response, the dispute auto-escalates.
5. For COUNTER or CONCEDE_PARTIAL responses, the escrow moves to ESCALATED. The payer can accept the resolution while in this state. Once AI review begins (AI_REVIEW), the acceptance invitation is no longer valid — the AI evaluator takes over.

Response windows:

Dispute categories:

Tier 2: AI Arbitration (5% Fee)

If Tier 1 fails, the dispute escalates to AI evaluation. An AI evaluator analyzes the evidence from both parties against the original escrow agreement and renders a decision.

How it works:

1. The escrow enters AI_REVIEW state.
2. The system assembles an evidence package: escrow details, job description, both parties' statements, and all submitted evidence.
3. The AI evaluator (claude-sonnet-4-20250514) analyzes the evidence using 10 evaluation rules (see below).
4. The AI returns a structured resolution: RELEASE, REFUND, or SPLIT with basis points, reasoning, and a confidence level.
5. HIGH confidence (>90%) → Resolution executes immediately on-chain.
6. MEDIUM confidence (60–90%) or LOW confidence (<60%) → Escalates to Tier 3 (human review).

Confidence criteria:

• HIGH: Evidence clearly supports one outcome, both parties provided submissions, job description is unambiguous.
• MEDIUM: Evidence supports outcome but with ambiguity, one party's evidence is thin, job description has gaps.
• LOW: Evidence is contradictory, plausible claims from both sides, key information missing.

The 5% arbitration fee is deducted from the escrow amount before the split calculation. This fee applies only when Tier 2 is invoked.

AI evaluation rules:

1. The job description is the anchor document — all evidence is evaluated against it.
2. Partial delivery results in proportional splits.
3. Quality claims require objective criteria in the job description.
4. Late delivery is only penalizable if a deadline was specified.
5. Good faith participation in Tier 1 is considered.
6. Evidence asymmetry favors the party with more evidence.
7. Dispute category must align with the actual evidence.
8. No speculation beyond the evidence provided.
9. Resubmitted work is evaluated on the latest version.
10. The full range of split values is used — most disputes aren't all-or-nothing.

Resolution types:

For FiDeal (human) disputes, resolution uses five fixed split tiers:

FiDealAI disputes use the full range of basis points (0–10000) for finer-grained splits.

Tier 3: Human Review (No Additional Fee)

For disputes where the AI has medium or low confidence, a designated human reviewer makes the final call.

How it works:

1. The escrow enters HUMAN_REVIEW state.
2. A reviewer sees the full evidence package plus the AI's preliminary decision and reasoning.
3. The reviewer can:
   • ACCEPT — Confirm the AI's decision as-is.
   • MODIFY — Adjust the split or outcome.
   • OVERRIDE — Replace the AI's decision entirely.
4. The reviewer's decision executes on-chain.

Review deadlines:

If the reviewer doesn't act within the deadline, the AI's original decision executes automatically. This ensures disputes always resolve — they never hang indefinitely.

On-Chain Settlement

All dispute resolutions settle on-chain via Zoe's atomicRearrange. For SPLIT resolutions, funds are distributed to three destinations in a single atomic operation:

1. Payee share — Their portion based on the split.
2. Payer refund — Their portion based on the split.
3. Fee collector — Arbitration fee (5%) + protocol fee (3% on payee's portion).

This atomic settlement means the distribution either happens completely or not at all. There's no partial state where some parties receive funds and others don't.

Evidence

Both parties can submit evidence with their dispute statements. Evidence is structured as artifacts:

{
  "type": "text",
  "label": "Missing endpoints",
  "content": "PUT /users and DELETE /users were not implemented"
}

Evidence types:

Statements are capped at 500 characters. Be specific and reference concrete evidence — the AI evaluator weighs specificity heavily.

Dispute Flow Summary

Payer raises dispute
        │
        ▼
  RESPONSE_PENDING ──(timeout)──→ ESCALATED
        │
   Payee responds
        │
   ┌────┴────┐
   │         │
CONCEDE   COUNTER/REJECT
   │         │
SETTLED   ESCALATED
              │
     ┌────────┴────────┐
     │                 │
  Payer accepts    No acceptance
  (acceptAgentRes)    │
     │                 ▼
  SETTLED          AI_REVIEW
              │
         ┌────┴────┐
         │         │
     HIGH conf  MED/LOW conf
         │         │
      SETTLED   HUMAN_REVIEW
                   │
              ┌────┴────┐
              │         │
          Reviewed   Timeout
              │         │
           SETTLED   SETTLED
                  (AI auto-exec)