MarketEngine

MarketEngine is the core contract — one deployed per market. It manages the full lifecycle: LP deposits, position placement, dynamic pricing, resolution, winner redemption, and LP withdrawal. All USDC is held directly by this contract.

State-Changing Functions

placeBet(Side side, uint256 usdcIn, uint256 minSharesOut)

Takes a position on the given side (YES or NO).

Parameter	Type	Description
side	Side (enum: YES=0, NO=1)	Which outcome to take a position on
usdcIn	uint256	USDC amount to spend (6-decimal)
minSharesOut	uint256	Minimum outcome tokens to receive (18-decimal WAD). Reverts if slippage exceeds this.

Behavior:

• Transfers usdcIn USDC from caller to the contract

• Splits the order into 16 piecewise steps, pricing each at the current mark price

• Deducts the dynamic fee (accrues to the pool)

• Mints outcome tokens to the caller

• Checks solvency invariant and skew cap after execution

• Emits BetPlaced event

Requirements: Market must be in Open or CloseOnly state. In CloseOnly, only skew-reducing positions are accepted. Minimum position: minBetUsdc (default 1 USDC).

---

depositLp(uint256 usdcAmount)

Deposits USDC as LP capital into the pool.

Parameter	Type	Description
usdcAmount	uint256	USDC to deposit (6-decimal)

Behavior:

• Transfers USDC from caller to the contract

• Mints LP shares at a fixed 1:1 ratio: newShares = toWad(usdcAmount) ($1 = 1 share, always)

• Accrues any pending fee rewards before updating share balances

• Checks solvency invariant after deposit

Requirements: Market must be in Created or Funded state. First deposit must meet minLpUsdc.

---

resolve(Outcome _outcome)

Resolves the market with the given outcome. Owner-only.

Parameter	Type	Description
_outcome	Outcome (enum: YES=1, NO=2)	The winning outcome

Behavior:

• Sets the market outcome permanently

• Transitions to Resolved state

• Emits MarketResolved event with final liabilities and balance

Requirements: Market must be past its close time. Cannot pass UNRESOLVED (0). Cannot resolve twice.

---

redeem(uint256 shares)

Burns winning outcome tokens and pays 1.00 USDC per token.

Parameter	Type	Description
shares	uint256	Number of winning tokens to redeem (18-decimal WAD)

Behavior:

• Burns shares winning tokens from the caller

• Transfers fromWad(shares) USDC to the caller (1 token = 1 USDC)

• Emits Redeemed event

Requirements: Market must be Resolved or Withdrawable. Caller must hold winning-side tokens.

---

sweepLosing(uint256 shares)

Burns losing outcome tokens. No USDC payout — this is cleanup only.

Parameter	Type	Description
shares	uint256	Number of losing tokens to burn (18-decimal WAD)

Requirements: Market must be Resolved or Withdrawable. Caller must hold losing-side tokens.

---

withdrawLp(uint256 shares)

Burns LP shares and pays the caller their capital share + earned fee share.

Parameter	Type	Description
shares	uint256	Number of LP shares to burn (18-decimal WAD)

Behavior:

• Accrues pending fee rewards before updating share balances

• Calculates lpPool = contractBalance - winningLiability (USDC reserved for unredeemed winners)

• Computes capital share: (capitalPool * shares) / totalLpShares (where capitalPool = lpPool - unclaimedFees)

• Computes fee share: proportional feeEntitlement converted from WAD to USDC

• Pays capitalShare + feeShare in USDC (capped to lpPool for rounding safety)

• Burns the LP shares

• Emits LpWithdrawn event

Requirements: Market must be in Withdrawable state.

View Functions

Pricing

Function	Returns	Description
getMarkPrice()	(uint256 pYes, uint256 pNo)	Current YES and NO prices (WAD). Always sum to 1e18.

Market State

Function	Returns	Description
state()	State	Current lifecycle state (0–5)
outcome()	Outcome	Resolved outcome (0=Unresolved, 1=YES, 2=NO)
bettingCloseTime()	uint256	Unix timestamp when positions close
resolveTime()	uint256	Unix timestamp when resolution is allowed
question()	string	The market question text

Pool & Liabilities

Function	Returns	Description
engineUsdc()	uint256	USDC balance of the contract (6-decimal)
yesLiability()	uint256	Total USDC owed if YES wins (WAD)
noLiability()	uint256	Total USDC owed if NO wins (WAD)
totalOI()	uint256	Total open interest: yesLiability + noLiability (WAD)
imbalance()	uint256	Absolute difference between liabilities (WAD)
maxLiability()	uint256	max(yesLiability, noLiability) (WAD)
accumulatedFees()	uint256	Total fees collected (WAD)
getSkewRatio()	int256	Signed skew ratio: imbalance / backingEff (WAD)

LP Info

Function	Returns	Description
lpShares(address)	uint256	LP shares for a given address (WAD)
totalLpShares()	uint256	Total LP shares outstanding (WAD)
totalLpDeposited()	uint256	Cumulative LP deposits (6-decimal USDC, basis for skew cap)
feePerShare()	uint256	Cumulative fees per LP share (WAD)
userFeePerSharePaid(address)	uint256	User's snapshot of feePerShare at last deposit/withdraw (WAD)
userPendingFees(address)	uint256	User's materialized but unclaimed fee entitlement (WAD)
totalFeesClaimed()	uint256	Total fees already paid out to LPs (WAD)

Parameters (Immutable)

Function	Returns	Description
curveA()	uint256	Pricing curve steepness (WAD)
virtualLiquidity()	uint256	Price damping parameter (WAD)
baseFeeBps()	uint256	Base fee in basis points
feeK()	uint256	Dynamic fee swing parameter
minFeeBps()	uint256	Minimum fee in basis points
maxSkewBps()	uint256	Dynamic skew cap in basis points
minBetUsdc()	uint256	Minimum position size (6-decimal USDC)
minLpUsdc()	uint256	Minimum LP deposit to open trading (6-decimal USDC)
seedImbalance()	int256	Opening price seed (WAD, signed)
yesToken()	address	YES outcome token contract
noToken()	address	NO outcome token contract
usdc()	address	USDC token contract

Events

BetPlaced

event BetPlaced(
    address indexed user,
    Side side,
    uint256 usdcIn,        // 6-decimal USDC (gross amount including fee)
    uint256 fee,           // 6-decimal USDC (LP fee)
    uint256 protocolFee,   // 6-decimal USDC (protocol fee, sent to treasury)
    uint256 sharesOut,     // 18-decimal WAD (tokens minted)
    uint256 markPrice      // 18-decimal WAD (mark price at execution)
);

LpDeposited

event LpDeposited(
    address indexed user,
    uint256 usdcAmount,    // 6-decimal USDC
    uint256 sharesIssued   // 18-decimal WAD
);

MarketResolved

event MarketResolved(
    Outcome outcome,
    uint256 yesLiability,    // 18-decimal WAD
    uint256 noLiability,     // 18-decimal WAD
    uint256 engineBalance    // 6-decimal USDC
);

Redeemed

event Redeemed(
    address indexed user,
    Side side,
    uint256 sharesBurned,   // 18-decimal WAD
    uint256 usdcPaid        // 6-decimal USDC
);

LpWithdrawn

event LpWithdrawn(
    address indexed user,
    uint256 sharesBurned,   // 18-decimal WAD
    uint256 usdcReceived    // 6-decimal USDC
);

StateChanged

event StateChanged(
    State oldState,
    State newState
);

Enums

enum State { Created, Funded, Open, CloseOnly, Resolved, Withdrawable }
enum Side { YES, NO }
enum Outcome { UNRESOLVED, YES, NO }