---
title: SBET V2 Protocol Documentation
description: Developer documentation for SBET V2 — the freshly-audited redesign of the SBET sports-betting and prediction-market protocol on EVM L2.
canonical: https://sbettoken.org/docs/protocol-v2/
version: 2.0.0
status: pre-deployment
updated: 2026-04-05
---

# SBET V2 Protocol Documentation

SBET V2 is the second generation of the SBET sports-betting and prediction-market protocol,
targeting EVM L2 deployment (Base, Arbitrum). V2 is a ground-up redesign that replaces
the V1 single-grader finalization path with a VRF-selected panel, a two-phase dispute
state machine, and a three-tier pause architecture.

This documentation is written for **protocol integrators, security auditors, grader
operators, and technical due-diligence readers**. If you want the user-facing narrative,
start with the [main protocol overview](/docs/protocol.html); this section is the
engineering source of truth.

---

## Reading order

Read the docs in this order if you're new to V2.

| # | Document | What you'll learn |
|---|----------|-------------------|
| 1 | [Architecture](./architecture.md) | Contract layout, state machine, dispute flow, data custody model |
| 2 | [State machine](./state-machine.md) | Every match-state transition, trigger, actor, and event |
| 3 | [Security model](./security-model.md) | Economic security, slashing math, attack scenarios |
| 4 | [Contracts reference](./contracts-reference.md) | Every external function, event, and error per contract |
| 5 | [User flows](./user-flows.md) | Bet, claim, dispute, void-refund, auto-claim, prediction market flows |
| 6 | [Grader operator guide](./grader-operator-guide.md) | Running a grader: stake, infra, escalation, rotation |
| 7 | [V1 → V2 migration](./v1-to-v2-migration.md) | What changed, why, and what happens to V1 positions |

---

## Locked architectural decisions

V2 is built around **13 locked decisions**. Every contract file contains `[Decision #N]`
and `[Bug Fix #N]` markers tying source code back to these decisions:

| # | Decision | Where |
|---|----------|-------|
| 1 | Dynamic tiered challenge window (90s / 15min / 2h / 4h) | [`ChallengeWindowLib`](./architecture.md#challengewindowlib) |
| 2 | Two-phase finalization: `Open → Proposed → Finalized` | [`SBETCoreV2`](./state-machine.md) |
| 3 | $25k SBET minimum grader stake | [`GraderRegistryV2`](./grader-operator-guide.md#staking) |
| 4 | Per-match payout cap $225k, slash split 50/20/20/10 | [`SBETCoreV2` + `SBETTreasuryV2`](./security-model.md#slashing-economics) |
| 5 | 5-of-9 Safe multisig arbiter | [`DisputeManager`](./contracts-reference.md#arbiterresolve) |
| 6 | Three-tier pause + match-lock bond | [`GuardianCouncil`](./contracts-reference.md#guardiancouncil) |
| 7 | Bond-escalation dispute (1% TVL, 2×, max 3 rounds) | [`DisputeManager`](./security-model.md#dispute-bond-escalation) |
| 8 | Gasless auto-claim via ERC-2771 (2% SBET / 3.5% other) | [`SBETTreasuryV2`](./user-flows.md#auto-claim) |
| 9 | VOID refund = principal + fees | [`SBETCoreV2.claimVoidRefund`](./state-machine.md#void) |
| 10 | 6-tier AI grader escalation | [`grader-operator-guide`](./grader-operator-guide.md#6-tier-escalation) |
| 11 | VOID reason enum (NATURAL / PROTOCOL / DISPUTE) | [`ISBETCoreV2.VoidReason`](./contracts-reference.md#voidreason) |
| 12 | VRF-selected grader panel (size 13, quorum 9) | [`SBETCoreV2.registerMatch`](./architecture.md#vrf-panel) |
| 13 | Hybrid payout: signed-position (binary) + parimutuel | [`SignedPositionLib`](./architecture.md#pooltypes) |
| 14 | Prediction market domain separation | [`PredictionMarketV2.PREDICTION_DOMAIN`](./architecture.md#predictionmarketv2) |
| 15 | LMSR AMM with autonomous payouts | [`PredictionAMMV2`](./architecture.md#predictionammv2) |

---

## Contract set

Nine contracts, ~160kB of source, targeting Solidity `^0.8.24`.

| Contract | Lines | Purpose |
|----------|------:|---------|
| [`SBETCoreV2`](./contracts-reference.md#sbetcorev2) | 923 | Match registry, bet accounting, state machine |
| [`SBETTreasuryV2`](./contracts-reference.md#sbettreasuryv2) | 435 | Token custody, payouts, auto-claim, slash distributor |
| [`GraderRegistryV2`](./contracts-reference.md#graderregistryv2) | 359 | Grader staking, grade submission, slashing |
| [`DisputeManager`](./contracts-reference.md#disputemanager) | 424 | Bond-escalation dispute state machine |
| [`GuardianCouncil`](./contracts-reference.md#guardiancouncil) | 313 | Three-tier pause controller |
| [`SBETStakerRewards`](./contracts-reference.md#sbetstakerrewards) | 293 | Pull-based MasterChef-style reward accumulator |
| [`PredictionMarketV2`](./contracts-reference.md#predictionmarketv2) | 728 | Prediction market lifecycle, metadata, resolution sync |
| [`PredictionAMMV2`](./contracts-reference.md#predictionammv2) | 991 | LMSR pricing, ERC-1155 shares, autonomous payouts |
| `ChallengeWindowLib` + `SignedPositionLib` | 230 | Pure math libraries |

## Status

All 6 V2 Core contracts are **deployed to Sepolia** as of 2026-04-05. Addresses
are in `src/config/contracts.ts` in the dapp repository.

PredictionMarketV2 and PredictionAMMV2 are **code-complete and security-hardened**
but not yet deployed (pending deploy script). The audit is scheduled for Q2 2026.
Deployment targets, release notes, and deployed addresses will be published in
[`deployments.md`](./deployments.md) (to be created at deployment time).

V1 has been **removed from the dapp** — zero V1 ABI imports remain in production
code. All hooks and pages use V2 contracts. V1 positions settle under V1 rules
on the legacy contract set. See [V1 → V2 migration](./v1-to-v2-migration.md)
for details.

## Test coverage

| Suite | Count | Tool |
|-------|------:|------|
| Foundry unit + fuzz | 307 | `forge test` (includes 6 fuzz tests) |
| Echidna invariants | 20 | Property-based invariant testing |
| Indexer pytest | 97 | `pytest` |
| Dapp vitest | 23 | `vitest` |

---

## License

All V2 contracts are MIT-licensed. See [LICENSE](https://github.com/sbettoken/contracts/blob/main/LICENSE).