EventlyMarketsV3.sol

Version: v3.2 (post-audit, pre-deployment) Status: Pending deployment (audit complete) Dependencies: OpenZeppelin ERC-1155, ERC-20 SafeERC20, PRBMath SD59x18

---

Overview

EventlyMarketsV3 is the production prediction markets contract for evently. It combines:

• ERC-1155 tradable positions -- each trade mints/burns fungible shares per outcome

• LMSR AMM -- Logarithmic Market Scoring Rule for automated, manipulation-resistant pricing (b=200 USDm)

• CLOB (Central Limit Order Book) -- bids and asks with price-time priority, matched automatically on placeOrder

• Creator economy -- 1% creator fee on all volume, claimable after finalization

The LMSR mechanism eliminates the core flaw of parimutuel systems: being correct always yields a profit, regardless of how many people chose the same option.

---

Key Parameters

Parameter	Value
Creator collateral	50 USDm
Dispute collateral	50 USDm
Dispute window	24 hours
Burn delay (losing shares)	24 hours after finalization
Total fee (default)	2.5% (1% creator + 1% treasury + 0.5% resolver pool)
Fee hard cap	5%
Max options per market	4
Min options per market	2
Min trade	0.001 shares (1e15)
LMSR liquidity parameter b	200 USDm (200e18)
Max orders per book	200 per (market, option, side)
1 winning share pays out	1 USDm exactly

---

LMSR Pricing Mechanism

LMSR (Logarithmic Market Scoring Rule) is an automated market maker where price follows a mathematically sound cost function:

C(q) = b x ln( sum exp(q[i] / b) )

• q[i] = shares outstanding for option i

• b = liquidity parameter (200 USDm) -- controls price sensitivity

• Cost to buy shares of option i = C(q after) - C(q before)

Implied probability of option i:

P(i) = exp(q[i]/b) / sum exp(q[j]/b)

At initialization all quantities are 0, so each option starts at 1/n probability. Prices always sum to exactly 1.

Market subsidy: To bootstrap liquidity, the creator locks b x ln(n) USDm at market creation. This subsidy guarantees solvency: poolBalance + subsidyDeposited >= total winning shares at all times.

---

Architecture

BUY order  -> CLOB ask orders filled first (price-time priority)
           -> Remaining budget routed to LMSR AMM

SELL order -> CLOB bid orders filled first (price-time priority)
           -> Unmatched remainder rests as limit ask in CLOB
           -> OR: sellToAMM() for instant AMM execution

Resolution -> Each winning share redeemable for exactly 1 USDm
Cancelled  -> All holders get pro-rata refund (poolBalance + subsidyDeposited)

---

Market Lifecycle

1. Created -- creator locks 50 USDm collateral + LMSR subsidy (b x ln(n))

2. Active -- users buy/sell shares via LMSR AMM and CLOB

3. BettingClosed -- after betting deadline, no new trades

4. Resolved -- creator declares winning option

5. Dispute Window (24h) -- any whitelisted user can dispute by locking 50 USDm

6. Finalized -- after dispute window closes or admin settles dispute

7. Redemption -- winning shareholders call redeemWinnings() for 1 USDm per share

---

Fee Structure

Recipient	Default	Description
Market creator	1% (creatorFeeBps = 100)	Accrues in creatorAccruedFees, claimable after finalization
Treasury	1% (treasuryFeeBps = 100)	Accumulates in treasuryBalance
Resolver pool	0.5% (resolverFeeBps = 50)	Initially = admin; redirected post-TGE to staking
Total	2.5%	Hard cap: 5% via setFees()

Admin markets (created by admin): creator cut goes to treasury instead.

---

Audit Fixes Applied (v3.2)

ID	Fix
F-02	claimCancelRefund -- snapshot total supply before burning; prevents insolvency on sequential claims
A-03	MAX_ORDERS_PER_BOOK = 200 per (market, option, side) -- prevents O(n) DoS griefing
F-DS-M02	_cleanBook() called immediately in cancelOrder -- dead CLOB entries removed, book never fills up with ghosts
R2-2	claimCreatorFees requires Finalized status -- blocks creator fee claim while market is Disputed
L-01	nonReentrant added to resolveMarket, cancelMarket, slashMarket
GROK-M01	subsidyDeposited included in claimCancelRefund effective pool -- subsidy recoverable by shareholders on cancel/slash
GPT-R3-3	slashMarket handles Disputed status -- dispute collateral swept to treasury, nothing stranded
GROK-L02	createdAt != 0 guard added to all view functions -- prevents silent zero returns for nonexistent markets
QWEN-I03	BettingClosed event emitted by closeBetting

---

Functions

Trading

• placeOrder(marketId, optionIndex, side, quantity, pricePerShare, minFill) -- BUY or SELL limit order; CLOB matched first, remainder to AMM for BUY

• sellToAMM(marketId, optionIndex, shares, minUsdmOut) -- instant sell to LMSR AMM at current price

• cancelOrder(orderId) -- cancel resting order; escrowed USDm or shares returned immediately

Pricing (view)

• getPrice(marketId, optionIndex) -- LMSR implied probability (0 to 1e18)

• getImpliedPrices(marketId) -- array of all option probabilities

• quoteBuy(marketId, optionIndex, usdmNet) -- shares out for a given net USDm (binary search)

• quoteSell(marketId, optionIndex, shares) -- gross USDm out for a given share quantity

• getQuantities(marketId) -- outstanding shares per option

• getSubsidy(marketId) -- subsidy deposited and b parameter

• getBidBook(marketId, optionIndex) -- resting bid order IDs

• getAskBook(marketId, optionIndex) -- resting ask order IDs

• getOrderInfo(orderId) -- full order struct

Market Management

• createMarket(...) -- locks 50 USDm collateral + LMSR subsidy

• createAdminMarket(...) -- admin pays subsidy only (no creator collateral)

• resolveMarket(marketId, winningOption) -- creator resolves after betting deadline

• closeBetting(marketId) -- permissionless; callable by anyone after bettingDeadline

• disputeMarket(marketId, proposedOption) -- dispute with 50 USDm collateral

• settleDispute(marketId, creatorWasRight, finalOption) -- admin settles

• finalizeMarket(marketId) -- callable by anyone after dispute window closes

• cancelMarket(marketId) -- creator, admin, or anyone after resolutionDeadline

• slashMarket(marketId, reason) -- admin; works on Active, BettingClosed, Resolved, Disputed

Claims

• redeemWinnings(marketId) -- burn winning shares for 1 USDm each

• claimCancelRefund(marketId) -- pro-rata refund on cancelled/slashed markets

• claimCreatorFees(marketId) -- creator withdraws accrued fees (post-finalization only)

• burnLosingShares(marketId, holders[]) -- admin keeper; burns losing shares 24h after finalization

Admin

• setFees(creatorBps, treasuryBps, resolverBps) -- adjust fee split (<=5% total)

• setResolverPoolAddress(addr) -- redirect resolver fees

• withdrawTreasury(to, amount) -- pull accumulated treasury fees

• withdrawResolverPool(to, amount) -- pull accumulated resolver fees

• transferAdmin(newAdmin) -- transfer admin role

• addToWhitelist(wallet) / batchWhitelist(wallets[]) / removeFromWhitelist(wallet) -- whitelist management

• setWhitelistEnabled(bool) -- toggle whitelist enforcement

• createInviteCode(codeHash) / redeemInviteCode(code) -- invite system

---

Token ID Encoding

tokenId = marketId * MAX_OPTIONS + optionIndex

MAX_OPTIONS = 4, so each market occupies token IDs [marketId*4, marketId*4+3].

---

CLOB Design

Property	Value
Order types	BUY and SELL
Matching	Automatic on placeOrder
Price priority	Best price first (ascending for asks, descending for bids)
Time priority	FIFO within same price level
Dead entry cleanup	Immediately on cancelOrder (_cleanBook -- F-DS-M02)
Book cap	200 orders per (market, option, side)