How $RIVALS works

$RIVALS is an ERC20 paired with a Uniswap V4 hook (RivalHook) and a pari-mutuel betting contract (BetVault). Bet resolution is read from a sports oracle (Chainlink Sports, with a 3-of-5 multisig fallback). 5% of every losing pool is captured as protocol rake, swapped via an internal V4 trade to $RIVALS, and burned.

                    ┌──────────────────────────┐
                    │   Uniswap V4 PoolManager │
                    └──────────┬───────────────┘
                               │ hook callbacks
                               ▼
        ┌──────────────────────────────────┐
        │ RivalHook                        │     ┌──────────────────┐
        │  • LDF bands (100 × 30 ETH)      │     │ BetVault         │
        │  • borrow / repay / liquidate    │────▶│  • pari-mutuel   │
        │  • borrowToBet                   │     │  • oracle read   │
        │  • rakeBurn (called by vault)    │◀────│  • claim/refund  │
        └──────────────────────────────────┘     └──────┬───────────┘
                  │                                     │
                  ▼                                     ▼
        ┌──────────────────┐                  ┌────────────────────┐
        │ $RIVALS (ERC20)   │                  │ Sports oracle      │
        │  • 1M fixed      │                  │ (or multisig fall) │
        └──────────────────┘                  └────────────────────┘

• V = 20 ETH - virtual reserve so the curve is defined at zero real ETH
• K = 20,000,000 - establishes 1,000,000 $RIVALS at launch
• Spot price = (V + realETH) / realTokens

Liquidity is sliced into 100 bands of 30 ETH each (a Liquidity Distribution Function), covering 0 to 3,000 ETH of cumulative inflow. Each band i holds:

Band 0 (0 to 30 ETH) gets 60% of the supply; later bands taper sharply.

1. Pulls collateral and prices it at spot.
2. Computes the liquidation ETH level via √0.6 × (V + spotETH) − V and maps it to a bound band.
3. Withdraws ETH from that band's LP (which sits below current spot, so price is unchanged).
4. Routes 1% to the fee collector, sends 99% to the user, records the position.

Liquidations sell the collateral via a V4 swap, pay a capped 1% bounty to the caller, and refill the bound band as fresh single-sided ETH LP. No $RIVALS is burned; the band just gets deeper. This is the protocol's self-healing property.

1. resolve(matchId) - anyone can call after the match ends. Reads the oracle, sets winningOutcome.
2. claim(matchId, outcome) - winners pull stake + (stake × losersPool × 0.95) / winnersPool.
3. The first winner-claim triggers the buyback and burn (next section).
4. settleBetPosition(...) - permissionless settler for borrow-routed bets. Auto-repays debt, returns collateral plus surplus, or banks winnings if the position was liquidated mid-bet.
5. If the oracle does not report within 48h: timeoutRefund(matchId) opens and all stakes are refunded at par.

When the first winner claims, BetVault forwards 5% of the losers' pool to RivalHook.rakeBurn(). Inside an unlockCallback:

1. poolManager.sync(ETH); poolManager.settle{value: rake}();
2. swap(zeroForOne=true, amountSpecified=-rake);
3. poolManager.take(RIVALS, hook, tokensBought);
4. RIVALS.burn(tokensBought);

The burn block is marked lastLiquidationBlock; external swaps in the same block are rejected by beforeSwap, which blocks sandwich attempts around the buyback. Internal swaps (where sender == hook) bypass this gate.

Edge case: if nobody bet the winning outcome, anyone can call sweepNoWinners(matchId) to route the entire pot to a burn. Permissionless, one-shot.

Resolution depends on a single interface:

function getOutcomeForFixture(bytes32 feedKey)
    external view
    returns (uint8 outcome, uint64 settledAt, uint8 statusFlag);

// statusFlag:  0 pending  · 1 final  · 2 cancelled  · 3 abandoned

Primary: a Chainlink Sports Data Streams adapter. Fallback: a 3-of-5 multisig MultisigResolver keyed off a public scores feed, gated by a one-hour challenge window. After 48h with no report, timeoutRefund opens.

The deployer may call ownerBootstrapBuy() before start() opens public swaps, paying the same 1% swap fee as any buyer. The ETH committed is at the deployer's discretion and is verifiable via the BootstrapBuy(buyer, ethIn, tokensOut) event. This pristine first entry is intentional: it sets a clean starting price with no front-running.

1. Deploy FeeCollector with a multisig owner.
2. Deploy the $RIVALS ERC20, mint 1M to the deployer.
3. Mine a CREATE2 salt encoding the V4 hook permission flags 0x3ACC.
4. Deploy RivalHook at the mined address.
5. Transfer 1M $RIVALS from deployer to hook.
6. Deploy BetVault(hook, oracle, multisig).
7. hook.setBetVault(vault) - one-shot, self-bricks.
8. hook.initializePool(), then seedBands(0, 50) and seedBands(50, 100).
9. Register the opening slate of matches in BetVault.
10. Final atomic bundle: ownerBootstrapBuy + start(). Public swaps open.
11. Later rounds are registered progressively as brackets settle.
12. After the final match resolves, ownership of both contracts is renounced.