Smart Contract Reference

Smart Contract Reference

Deployed Contracts (Fuji Testnet)

Contract	Address	Type
WagerEscrow	0x4F0e1936475Bfc4A0e9daf1d4bb84Aa5Bc402825	Immutable
MockUSDC	0x1e8f044E0D8CC87A4B99E9D0eCF0C17b9FacF102	ERC-20
WagerAccessControl	0xf421214fA1feeF6f6c2e9c226484729081B9D3A7	UUPS Proxy

Chain: Avalanche Fuji (Chain ID: 43113)

RPC: https://api.avax-test.network/ext/bc/C/rpc

---

Function Selectors

All selectors verified using ethers.Interface. Do not hand-compute.

Function	Selector	Full Signature
createWager	0xe4c02f16	createWager(bytes32,address,uint256,uint256,uint256,address,uint16,bytes32)
deposit	0xb214faa5	deposit(bytes32)
submitOutcome	0x8c884211	submitOutcome(bytes32,uint8)
withdraw	0x8e19899e	withdraw(bytes32)
getWager	0x71dd4a42	getWager(bytes32)
approve (USDC)	0x095ea7b3	approve(address,uint256)
balanceOf (USDC)	0x70a08231	balanceOf(address)

---

Wager State Machine

State 0: PENDING
  Wager created, no deposits yet.
  → Creator deposits → PARTIALLY_FUNDED
  → Creator cancels → REFUNDED
  → Funding deadline passes → EXPIRED

State 1: PARTIALLY_FUNDED
  One party has deposited.
  → Second party deposits → ACTIVE
  → Funding deadline passes → EXPIRED (depositor refunded)

State 3: ACTIVE
  Both parties deposited. Waiting for the real-world event.
  → Either party submits outcome → AWAITING_OUTCOME

State 4: AWAITING_OUTCOME
  At least one outcome submitted.
  → Both submit → truth table evaluation
  → Outcome deadline passes → expiration handling

State 5: DISPUTED
  Outcomes conflict in a way the truth table can't auto-resolve.
  → Mediator submits ruling → APPEAL
  → Mediator deadline passes → MEDIATOR_REPLACEMENT

State 6: MEDIATOR_REPLACEMENT
  Original mediator failed to act.
  → Parties vote for replacement mediator.
  → Replacement rules → APPEAL
  → Replacement fails → OPERATOR_ESCALATED

State 7: OPERATOR_ESCALATED
  All mediator paths failed.
  → Operator settles → SETTLED or REFUNDED

State 8: APPEAL
  Mediator ruling submitted, 48-hour freeze.
  → Appeal window expires → settlement executes → SETTLED
  → Party flags appeal → extended review

State 9: SETTLED (terminal)
  Winner determined. Funds available for withdrawal.
  → Winner calls withdraw()
  → 90 days unclaimed → operator can sweep

State 10: REFUNDED (terminal)
  Both parties get their deposits back.
  → Both call withdraw() to reclaim funds

---

Truth Table

When both parties submit outcomes, the contract evaluates:

Creator	Taker	Result
WON	LOST	Creator wins (auto-settle)
LOST	WON	Taker wins (auto-settle)
WON	WON	Draw refund (both claim victory)
LOST	LOST	Draw refund (mutual concession)
DRAW	DRAW	Draw refund (agreement)
WON	DRAW	Disputed (mediator needed)
DRAW	WON	Disputed
LOST	DRAW	Disputed
DRAW	LOST	Disputed

Auto-settle cases require no external intervention. Disputed cases require mediator resolution.

---

Fee Structure

Fee	Default	Max Cap	When Charged
Protocol fee	5% (500 bps)	10% (1000 bps)	Deducted from winning payout
Creation fee	2 USDC	10 USDC	Pulled at wager creation (non-refundable)
Creation deposit	5 USDC	50 USDC	Pulled at creation (refundable on cancel)
Dispute fee	10 USDC	100 USDC	When dispute is opened
Late submission penalty	5 USDC	50 USDC	Applied if outcome deadline missed
Appeal fee	10 USDC	50 USDC	To flag an appeal

Fee rates are snapshotted at wager creation. Changes to governance fees don't affect existing wagers.

---

Security Measures

• ReentrancyGuard on all fund-moving functions

• SafeERC20 for all USDC transfers

• Pull-pattern withdrawals (contract never pushes funds)

• Custom errors instead of string reverts (gas efficient)

• Immutable constructor parameters (USDC address, AccessControl address)

• Fee hardcaps prevent governance from setting excessive fees

• Granular pause states (deposits, settlements, withdrawals can be paused independently)

• 90-day unclaimed sweep prevents permanent fund lockup

---

Wager Struct (16 Fields)

Returned by getWager(bytes32):

Word 0:  wagerId (bytes32)
Word 1:  creator (address)
Word 2:  taker (address)
Word 3:  amount (uint256), USDC raw (6 decimals)
Word 4:  state (uint8), WagerState enum
Word 5:  fundingDeadline (uint256), Unix timestamp
Word 6:  outcomeExpiration (uint256), Unix timestamp
Word 7:  mediatorAddress (address)
Word 8:  protocolFeeBps (uint16), basis points (snapshotted)
Word 9:  outcomeA (uint8), creator's outcome
Word 10: outcomeB (uint8), taker's outcome
Word 11: winner (address), zero until settled
Word 12: depositA (bool), creator deposited
Word 13: depositB (bool), taker deposited
Word 14: metadataHash (bytes32), keccak256 of off-chain metadata
Word 15: createdAt (uint256), block timestamp