ethPM

ethPM enables deterministic, on-chain prediction markets that resolve based on arbitrary smart contract state. Markets can bet on any verifiable on-chain data: TVL, token prices, trading activity, governance votes—without human resolvers.

Core Principles

Contract Addresses

The ethPM stack consists of five interconnected layers, each responsible for a specific domain of functionality.

Data Flow

User interactions flow through the stack as follows:

1. Trade Request: User submits collateral with desired position (YES/NO)
2. Routing: PMHookRouter evaluates Vault OTC vs AMM pricing
3. Fee Calculation: PMFeeHook computes dynamic fee based on market state
4. Execution: zAMM executes swap or PAMM mints new shares
5. Settlement: User receives conditional tokens

PAMM (Prediction AMM) is the core collateral vault that mints and manages ERC6909 conditional tokens (YES/NO shares). Each market is fully collateralized—1 share = 1 wei of collateral.

Token ID Derivation

Market Lifecycle

Core Functions

Market Creation

Creates a new prediction market. The resolver address has exclusive authority to call resolve() and optionally closeMarket().

Split (Collateral → Shares)

Locks collateral and mints equal amounts of YES and NO shares. For ETH markets, send ETH with the call.

Merge (Shares → Collateral)

Burns equal amounts of YES and NO shares to unlock collateral. Allowed until market resolution.

Claim (After Resolution)

Burns winning shares for collateral minus resolver fee (0-10% configurable).

Storage Layout

PMFeeHook is a policy layer that sits between zAMM and PAMM, implementing dynamic swap fees and market protection mechanisms. It uses EIP-1153 transient storage for gas optimization.

Fee Components

Configuration Parameters

Flag Bits

flags (uint16):
  bit 0: FLAG_SKEW          (0x01) - Enable skew fee
  bit 1: FLAG_BOOTSTRAP     (0x02) - Enable bootstrap decay
  bit 2-3: closeWindowMode  (0x0C) - 0=halt, 1=fixed, 2=min, 3=dynamic
  bit 4: FLAG_ASYMMETRIC    (0x10) - Enable directional fee
  bit 5: FLAG_PRICE_IMPACT  (0x20) - Enable impact check
  bit 6: FLAG_VOLATILITY    (0x40) - Enable volatility fee

extraFlags (uint16):
  bit 0-1: skewCurve        - 0=linear, 1=quadratic, 2=cubic, 3=quartic
  bit 2-3: decayMode        - 0=linear, 1=cubic, 2=sqrt, 3=ease-in

Default flags: 0x37 (skew + bootstrap + closeMode=1 + asymmetric + priceImpact)
Default extraFlags: 0x01 (quadratic skew, linear decay)

PMHookRouter provides smart order routing with integrated vault market-making. It creates a "waterfall" effect for best-execution across three venues: Vault OTC, AMM, and Mint fallback.

Order Routing Flow

Key Parameters

View-only quoter contract providing consolidated market data and execution quotes. Separated from routers to keep them under bytecode limit while enabling efficient frontend queries.

Market View Functions

Quote Functions

quoteBootstrapBuy(marketId, buyYes, collateralIn, minOut)
→ (totalShares, usesVault, source, vaultLP)

quoteSellWithBootstrap(marketId, sellYes, sharesIn)
→ (collateralOut, source)

quoteBuyWithSweep(marketId, buyYes, collateralIn, maxPrice)
→ (totalShares, poolShares, levels, pmShares, pmSource)

quoteSellWithSweep(marketId, sellYes, sharesIn, minPrice)
→ (totalCollateral, poolColl, levels, pmColl, pmSource)

Orderbook View Functions

Source Identifiers

Quote functions return a source indicating the execution path:

The deterministic resolver enables markets that resolve based on arbitrary on-chain reads. No human intervention required—resolution is computed via staticcall at close time.

Resolution Modes

target.staticcall(data) → uint256 value
value [op] threshold → YES/NO

targetA.staticcall(dataA) → A
targetB.staticcall(dataB) → B
(A * 1e18 / B) [op] threshold

Comparison Operators

MasterRouter provides pooled limit orders for prediction markets. ASK pools sell shares at fixed prices; BID pools buy shares at fixed prices.

Order Book Architecture

• ASK Pools: Sell shares at fixed price, filled lowest-first by buyWithSweep()
• BID Pools: Buy shares at fixed price, filled highest-first by sellWithSweep()
• Price Bitmap: 40 uint256s per market/side for O(1) best bid/ask discovery
• Accumulator LP: Prevents late-joiner exploitation of pending fills

Pooled Orderbook Design

Unlike traditional orderbooks with individual orders, MasterRouter uses pooled limit orders where multiple LPs can deposit into the same price level. This enables gas-efficient fills and fair pro-rata distribution.

Accumulator Pattern

The accumulator LP pattern (similar to MasterChef) tracks rewards per unit of liquidity. When fills occur, accCollPerScaled (ASK) or accSharesPerScaled (BID) increases. Each user's pending rewards are calculated as:

pending = (position.scaled * accPerScaled) - position.debt

Price Bitmap

The bitmap enables O(1) discovery of the best available price. Each bit represents a price level (1-9999 bps). Finding the lowest ASK or highest BID requires scanning at most 40 uint256 words using bit manipulation.

Sweep Operations

The sweep functions (buyWithSweep, sellWithSweep) traverse the price bitmap to fill orders at the best available prices, then fall back to PMHookRouter for any remaining amount.

Mint Operations

MasterRouter provides three mint variants that split collateral into YES/NO shares, keep one side for directional exposure, and route the other side differently based on strategy.

Listing Orders (Maker)

Users can place limit orders by depositing assets into price-specific pools. ASK pools list shares for sale; BID pools offer to buy shares.

Sweeping Orders (Taker)

Takers use sweep functions to execute against the orderbook, automatically filling through multiple price levels for best execution before falling back to AMM liquidity.

Complete Trading Flow

The MasterRouter enables a complete orderbook experience on top of the ethPM AMM infrastructure:

GasPM is a self-contained "infinite market" example built on top of ethPM. It demonstrates a specialized resolver for gas price predictions with built-in oracle infrastructure.

Market Types

Prerequisites

• Solidity ^0.8.30 (PAMM), ^0.8.31 (PMFeeHook, PMHookRouter)
• EIP-1153 support (Cancun/Dencun hardfork) for transient storage
• Existing zAMM deployment

Deployment Order

1. PAMM — Core vault (immutable)
2. PMFeeHook — Fee policy (owner-configurable)
3. PMHookRouter — Sets PAMM operator, registered as REGISTRAR
4. Resolver — Per-market deployment

Gas Estimates