> ## 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 & Claiming

> How bets are resolved and how winners claim their funds.

## Overview

When a bet's expiration date is reached, it enters the resolution phase. The outcome is determined, and the winner can claim the pot.

## Resolution Flow

### Disputeable Bets

```mermaid theme={null}
sequenceDiagram
    participant Timer as Expiration Timer
    participant RE as Resolution Engine
    participant SC as Smart Contract
    participant W as Winner
    participant Bot as Mouth Bot
    participant X as X (Twitter)

    Timer->>RE: Expiration date reached
    RE->>RE: Evaluate outcome
    RE->>SC: resolve(outcome)
    SC-->>SC: Bet status → Resolved (48h dispute window)
    Bot->>X: Posts result, tags both parties
    Note over SC: 48h dispute window
    SC-->>SC: finalize() → Finalized
    W->>SC: claim()
    SC-->>W: Transfers remaining USDC
```

### Non-Disputeable Bets

```mermaid theme={null}
sequenceDiagram
    participant Timer as Expiration Timer
    participant RE as Resolution Engine
    participant SC as Smart Contract
    participant W as Winner
    participant Bot as Mouth Bot
    participant X as X (Twitter)

    Timer->>RE: Expiration date reached
    RE->>RE: Evaluate outcome
    RE->>SC: resolve(outcome)
    SC-->>SC: Bet status → Finalized (immediate)
    RE->>SC: resolverClaim() (PvP 1v1)
    SC-->>W: Funds distributed automatically
    Bot->>X: Posts result, tags both parties
```

<Note>
  For non-disputeable PvP 1v1 bets, the backend calls `resolverClaim()` immediately after `resolve()` to distribute funds in one step. For Open PvP bets with many opponents, individual opponents can `claim()` themselves to avoid potential out-of-gas issues.
</Note>

## Resolution Methods

### Automatic Resolution (Oracle-Based)

For bets tied to **verifiable on-chain data**, resolution can be fully automatic:

* **Token price**: "ETH will be above \$5,000 by June 1"
* **FDV / Market cap**: "Monad FDV under \$1B in 3 months"
* **TVL**: "Aave TVL will exceed \$20B"
* **On-chain events**: "Uniswap v4 will be deployed on mainnet by Q2"

The resolution engine pulls data from oracles (Chainlink, Pyth) or on-chain sources at the expiration timestamp and resolves automatically.

### Manual Resolution (Mouth Team)

For bets tied to **off-chain or subjective outcomes**, the Mouth team resolves:

* **Real-world events**: "Trump will win the election"
* **Subjective claims**: "Project X will launch their mainnet"
* **Ambiguous criteria**: Anything not clearly measurable on-chain

**Process:**

1. Expiration date is reached
2. Mouth team reviews the bet terms and evaluates the outcome
3. Resolution is submitted to the smart contract
4. A **48-hour dispute window** opens
5. If no dispute, the resolution is finalized
6. If disputed, it enters the dispute process (see below)

## Dispute Mechanism

Only applies to **disputeable** bets. Non-disputeable bets skip straight to `Finalized` with no dispute window.

If a party disagrees with the resolution:

1. **Dispute window**: 48 hours after resolution is submitted
2. **Filing a dispute**: The disagreeing party clicks "Dispute" on the web app and provides evidence/reasoning
3. **Review**: The Mouth team reviews the dispute with the provided evidence
4. **Re-resolution**: The resolver can call `reResolve()` to update the outcome (resets the 48h timer)
5. **Final decision**: The team issues a final resolution
6. **Future improvement**: As the protocol matures, disputes may be escalated to a decentralized arbitration system (e.g., UMA Optimistic Oracle, Kleros)

<Warning>
  During the dispute window, funds remain locked in the smart contract. Neither party can claim until the dispute is resolved or the window expires. The `reResolve()` function is only available for disputeable bets.
</Warning>

## Claiming Winnings

Once a bet is finalized (either immediately after resolution for non-disputeable bets, or after the 48h dispute window for disputeable bets):

### Automatic Distribution (PvP 1v1, Non-Disputeable)

For non-disputeable PvP 1v1 bets, the backend calls `resolverClaim()` right after `resolve()`. Funds are distributed automatically — no manual claim needed.

### Manual Claim (Disputeable or Open PvP)

1. **Winner** navigates to the bet page on pvp.mouth.app
2. Clicks **"Claim Winnings"**
3. The smart contract:
   * Transfers the remaining USDC balance to the winner's embedded wallet (the 2% fee was already collected at deposit time)
   * Marks the bet as settled
4. Winner can then **withdraw USDC** from their embedded wallet to any external address

The resolver can also call `resolverClaim()` to batch-distribute all funds to winners at once.

### Payout Breakdown

| Component     | Amount                     | When                      | Recipient                |
| ------------- | -------------------------- | ------------------------- | ------------------------ |
| Protocol fee  | 2% of total pot            | Collected at deposit time | Mouth treasury           |
| Winner payout | Remaining contract balance | At claim time             | Winner's embedded wallet |

## Edge Cases

### Draw / Ambiguous Outcome

If the outcome is genuinely ambiguous or the bet terms were too vague:

* The Mouth team can resolve as a **Draw**
* Both parties receive their remaining deposit back (the 2% fee was already collected at deposit time and is not refunded)