MouthBet

​

Overview

• PvP (1v1): A specific opponent is set at creation. Only that address can accept.
• Open PvP: No specific opponent (address(0)). Anyone can deposit, and multiple opponents can each fill a portion of the total.

​

Initialization

function initialize(
    address _factory,
    address _challenger,
    address _opponent,
    uint256 _challengerAmount,
    uint256 _totalOpponentAmount,
    uint256 _odds,
    uint256 _expirationDate,
    uint256 _acceptanceDeadline,
    string calldata _title,
    bool _disputeable
) external initializer

​

State Machine

​

PvP (1v1) — Disputeable

​

PvP (1v1) — Non-Disputeable

​

Open PvP (Partially Fillable)

​

State Variables

​

Constants

​

Enums

enum BetStatus {
    Pending,      // Created, waiting for opponent(s)
    Filling,      // Open PvP: at least one opponent deposited, not fully filled
    Active,       // Fully funded and locked
    Resolved,     // Outcome determined, 48h dispute window active
    Finalized,    // Dispute window passed, claimable
    Claimed,      // Winner(s) claimed funds
    Cancelled,    // Challenger cancelled or mutual cancellation
    Expired       // Acceptance deadline passed with no fills
}

enum BetOutcome {
    Unresolved,
    ChallengerWins,
    OpponentWins,
    Draw
}

​

Odds & Asymmetric Deposits

• At odds = 50: both sides deposit the same amount (challengerAmount == totalOpponentAmount)
• At other values: deposits are asymmetric

totalOpponentAmount = challengerAmount * (100 - odds) / odds

​

Functions

​

deposit

function deposit(uint256 _amount) external

1. Caller must be the specified Opponent (Challenger cannot call — they deposit via Factory)
2. Bet must be in Pending status
3. Opponent deposits totalOpponentAmount (the _amount parameter is ignored, overridden to totalOpponentAmount)
4. Transfer USDC from caller to this contract (requires prior approval of the bet contract)
5. Collect 2% fee on total pot: fee = (challengerAmount + totalOpponentAmount) * feePercentage / 10000
6. Transfer fee to treasury
7. Status becomes Active
8. Emit Deposited, FeeCollected, and BetActivated events

1. Caller must be any Mouth user (not the Challenger)
2. Bet must be in Pending or Filling status
3. _amount must be greater than 0 and not exceed remaining unfilled amount (totalOpponentAmount - filledAmount)
4. Transfer USDC from caller to this contract
5. Record deposit in opponentDeposits[caller] and add to opponentList if new (capped at MAX_OPPONENTS = 100 unique depositors; existing depositors can top up without counting toward this limit)
6. Increment filledAmount by _amount
7. Status becomes Filling if not already
8. Collect proportional fee: fee = _amount * (challengerAmount + totalOpponentAmount) * feePercentage / (totalOpponentAmount * 10000)
9. Transfer fee to treasury
10. If filledAmount == totalOpponentAmount: Status becomes Active
11. Emit Deposited and FeeCollected events (and BetActivated event when fully filled)

​

activatePartial

function activatePartial() external

1. Bet must be in Filling status
2. Caller must be the Challenger, or acceptanceDeadline must have passed
3. filledAmount must be > 0
4. Recalculate challengerAmount proportionally: matchedChallengerAmount = (filledAmount * challengerAmount) / totalOpponentAmount
5. Return excess Challenger deposit (challengerAmount - matchedChallengerAmount) to Challenger
6. Update challengerAmount and totalOpponentAmount to the matched values
7. Status becomes Active (fee already collected per-deposit)
8. Emit PartialActivation and BetActivated events

​

withdraw

function withdraw() external

1. Caller must be the Challenger or the Resolver
2. Bet must be in Pending status (no opponent has deposited yet, or Open PvP with no fills)
3. Challenger must have deposited
4. If called by the Resolver, acceptanceDeadline must have passed (deserted bet cleanup)
5. If acceptanceDeadline has passed → set status to Expired, emit BetExpired
6. If called before deadline → set status to Cancelled
7. Transfer USDC back to Challenger, emit Withdrawn (emitted in all cases, regardless of timing)

​

resolve

function resolve(BetOutcome _outcome) external

1. Caller must be the resolver (checked via Factory)
2. Bet must be in Active status
3. block.timestamp must be at or past expirationDate
4. Set outcome and resolvedAt timestamp
5. Emit Resolved event
6. If disputeable = true: set status to Resolved (48h dispute window starts)
7. If disputeable = false: snapshot claimableBalance, set status to Finalized, emit Finalized event (no dispute window)

​

reResolve

function reResolve(BetOutcome _outcome) external

1. Bet must be disputeable
2. Caller must be the resolver (checked via Factory)
3. Bet must be in Resolved status
4. block.timestamp must be within the 48-hour dispute window (< resolvedAt + DISPUTE_WINDOW)
5. Update outcome and reset resolvedAt to current timestamp (restarts the 48h window)
6. Emit ReResolved(oldOutcome, newOutcome) event

​

finalize

function finalize() external

1. Bet must be in Resolved status
2. At least 48 hours must have passed since resolvedAt
3. Snapshot the contract’s USDC balance into claimableBalance
4. Set status to Finalized
5. Emit Finalized(claimableBalance) event

​

claim

function claim() external

1. Bet must be in Finalized status
2. Determine winner based on outcome
3. Distribute funds:
   • ChallengerWins / OpponentWins: transfer the entire remaining contract balance to the winner
   • Draw: each party receives their proportional share of the remaining balance
4. Set status to Claimed
5. Emit Claimed event

1. Bet must be in Finalized status
2. Determine winner based on outcome
3. Distribute funds:
   • ChallengerWins: Challenger receives the entire remaining contract balance
   • OpponentWins: each opponent claims their proportional share of the remaining balance, based on their deposit ratio (opponentDeposits[caller] / filledAmount)
   • Draw: each party receives their proportional share of the remaining balance
4. Set status to Claimed (after all parties have claimed)
5. Emit Claimed event

​

resolverClaim

function resolverClaim() external

1. Caller must be the resolver (checked via Factory)
2. Bet must be in Finalized status
3. No individual claim() must have been called yet (claimedCount == 0) — once any party claims individually, resolverClaim is blocked
4. Distribute funds to all winners via _distributeAll():
   • ChallengerWins: transfer entire claimableBalance to Challenger
   • OpponentWins: transfer proportional shares to each opponent (or full amount to single opponent in PvP)
   • Draw: transfer proportional shares to all parties
5. Set status to Claimed
6. Emit Claimed events for each recipient

​

mutualCancel

function mutualCancel() external

1. Bet must be in Active status
2. Caller must be Challenger or Opponent (for 1v1) / any deposited opponent (for Open PvP)
3. Record caller’s approval in cancelApprovals
4. For PvP: both Challenger and Opponent must have approved
5. For Open PvP: Challenger and all opponents must have approved
6. Refund each party their remaining deposit (the 2% fee was already collected at deposit time and is not refunded)
7. Set status to Cancelled
8. Emit MutualCancelled event

​

Events

event Deposited(address indexed depositor, uint256 amount);
event FeeCollected(uint256 fee, address indexed treasury);
event Withdrawn(address indexed challenger, uint256 amount);
event BetActivated(uint256 totalPot);
event PartialActivation(uint256 filledAmount, uint256 returnedToChallenger);
event Resolved(BetOutcome outcome);
event ReResolved(BetOutcome oldOutcome, BetOutcome newOutcome);
event Finalized(uint256 claimableBalance);
event Claimed(address indexed claimant, uint256 payout);
event MutualCancelled();
event BetExpired();

​

Access Control