> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mouth.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Resolution Engine

> How the Mouth resolution engine determines bet outcomes.

## Overview

The Resolution Engine is the most critical component of the Mouth protocol. It determines bet outcomes and ensures fair, transparent resolution.

## Resolution Types

### Type 1: Automatic (Oracle-Based)

For bets with **quantifiable, verifiable** conditions:

```mermaid theme={null}
graph LR
    A[Bet Expires] --> B[Engine Detects]
    B --> C[Fetch Oracle Data]
    C --> D[Evaluate Condition]
    D --> E[Submit Resolution]
    E --> F{Disputeable?}
    F -->|Yes| G[48h Dispute Window]
    G --> H[Finalized]
    F -->|No| H[Finalized immediately]
```

**Supported conditions:**

| Condition                 | Data Source            | Example               |
| ------------------------- | ---------------------- | --------------------- |
| Token price above/below X | Chainlink, Pyth        | "ETH > \$5,000"       |
| FDV above/below X         | CoinGecko API + oracle | "Monad FDV \< \$1B"   |
| TVL above/below X         | DeFi Llama API         | "Aave TVL > \$20B"    |
| On-chain event occurred   | RPC query              | "Uniswap v4 deployed" |

**How it works:**

1. At bet creation, the resolution criteria are stored as structured metadata:
   ```json theme={null}
   {
     "type": "price_threshold",
     "asset": "ETH",
     "condition": "above",
     "threshold": 5000,
     "source": "chainlink"
   }
   ```
2. At expiration, the engine fetches the data from the specified source
3. Evaluates the condition against the data
4. Submits the resolution on-chain

### Type 2: Manual (Mouth Team)

For bets with **subjective or off-chain** conditions:

```mermaid theme={null}
graph LR
    A[Bet Expires] --> B[Engine Detects]
    B --> C[Flags for Review]
    C --> D[Mouth Team Reviews]
    D --> E[Submit Resolution]
    E --> F{Disputeable?}
    F -->|Yes| G[48h Dispute Window]
    G --> H[Finalized]
    F -->|No| H[Finalized immediately]
```

**Process:**

1. Bet expires and is flagged in the Mouth admin dashboard
2. A Mouth team member reviews the bet terms and checks the outcome
3. Resolution is submitted via the admin dashboard
4. **If disputeable**: 48-hour dispute window starts. If disputed, the team re-reviews with additional evidence and can call `reResolve()` to update the outcome.
5. **If non-disputeable**: bet is immediately finalized. For PvP 1v1, the backend calls `resolverClaim()` to distribute funds.

## Dispute Mechanism

The dispute mechanism only applies to **disputeable** bets. Non-disputeable bets are immediately finalized after resolution.

### Window

Every disputeable resolution (automatic or manual) has a **48-hour dispute window** before finalization.

### Filing a Dispute

1. Either party clicks **"Dispute"** on the bet page within 48 hours
2. Must provide:
   * **Reason**: Why they believe the resolution is incorrect
   * **Evidence**: Links, screenshots, data sources supporting their claim
3. A dispute bond may be required in the future to prevent spam (not in v1)

### Dispute Review Process

```mermaid theme={null}
graph TD
    A[Dispute Filed] --> B[Mouth Team Notified]
    B --> C[Team Reviews Evidence]
    C --> D{Original Resolution Correct?}
    D -->|Yes| E[Dispute Rejected, Original Stands]
    D -->|No| F[Resolution Overturned]
    F --> G[New Resolution Submitted]
    E --> H[Dispute Window Ends]
    G --> H
    H --> I[Bet Finalized]
```

### Dispute Outcomes

| Outcome              | Result                                           |
| -------------------- | ------------------------------------------------ |
| **Dispute rejected** | Original resolution stands, bet is finalized     |
| **Dispute upheld**   | Resolution is overturned, new outcome is set     |
| **Inconclusive**     | Bet is resolved as a Draw, both parties refunded |

## Resolution on Smart Contract

The Resolution Engine interacts with the Bet smart contract via a **dedicated resolver wallet**:

```
resolverWallet.resolve(betAddress, outcome)
```

The smart contract enforces:

* Only the authorized resolver address can call `resolve()`
* Resolution can only happen after the expiration timestamp
* The outcome must be one of: `ChallengerWins`, `OpponentWins`, `Draw`
* **If disputeable**: status → `Resolved`, 48-hour dispute window timer starts on-chain
* **If non-disputeable**: status → `Finalized` immediately, claimable balance is snapshotted

After finalization, the resolver can optionally call `resolverClaim()` to batch-distribute all funds to winners (especially useful for PvP 1v1 bets). For Open PvP bets with many opponents, individual `claim()` calls are safer to avoid out-of-gas issues.

The resolver can also:

* Call `reResolve()` during the dispute window to update the outcome (disputeable only)
* Call `withdraw()` after the acceptance deadline to clean up deserted bets (Pending status only)

## Future: Decentralized Resolution

In future versions, Mouth may integrate decentralized arbitration for disputes:

* **UMA Optimistic Oracle**: Propose outcomes with a dispute bond, escalate to UMA token holders if disputed
* **Kleros**: Decentralized court system for subjective disputes
* **Reality.eth**: Crowd-sourced oracle with economic incentives for truthful reporting

This removes the trust assumption on the Mouth team for manual resolutions.