// Lifecycle
createMarket(description, resolver, collateral, close, canClose) → (marketId, noId)
createMarketAndSeed(description, resolver, collateral, close, canClose,
                    collateralIn, feeOrHook, minLiquidity, to, deadline) → (marketId, noId, liquidity)
closeMarket(marketId)                    // resolver early-close (if canClose)
resolve(marketId, outcome)               // resolver sets winner

// Core
split(marketId, collateralIn, to)        → (shares, used)
merge(marketId, shares, to)              → (merged, collateralOut)
claim(marketId, to)                      → (shares, payout)
claimMany(marketIds[], to)               → totalPayout

// Buy/Sell (split+swap or swap+merge via ZAMM)
buyYes(marketId, collateralIn, minYesOut, minSwapOut, feeOrHook, to, deadline) → yesOut
buyNo(marketId, collateralIn, minNoOut, minSwapOut, feeOrHook, to, deadline) → noOut
sellYes(marketId, yesAmount, swapAmount, minCollateralOut, minSwapOut, feeOrHook, to, deadline) → collateralOut
sellNo(marketId, noAmount, swapAmount, minCollateralOut, minSwapOut, feeOrHook, to, deadline) → collateralOut
sellYesForExactCollateral(marketId, collateralOut, maxYesIn, maxSwapIn, feeOrHook, to, deadline) → yesSpent
sellNoForExactCollateral(marketId, collateralOut, maxNoIn, maxSwapIn, feeOrHook, to, deadline) → noSpent

// ZAMM LP helpers
splitAndAddLiquidity(marketId, collateralIn, feeOrHook, amount0Min, amount1Min,
                     minLiquidity, to, deadline) → (shares, liquidity)
removeLiquidityToCollateral(marketId, feeOrHook, liquidity, amount0Min, amount1Min,
                            minCollateralOut, to, deadline) → (collateralOut, leftoverYes, leftoverNo)
poolKey(marketId, feeOrHook)             // returns ZAMM PoolKey struct

// Resolver
setResolverFeeBps(bps)                   // max 1000 (10%)

// Utility
multicall(bytes[] data)                  // batch multiple calls
permit(token, owner, value, deadline, v, r, s)       // EIP-2612 permit
permitDAI(token, owner, nonce, deadline, allowed, v, r, s)  // DAI-style permit

// Views
getMarket(marketId)
getMarkets(start, count)
getUserPositions(user, start, count)
getPoolState(marketId, feeOrHook)        // ZAMM pool reserves + implied prob
tradingOpen(marketId)
winningId(marketId)
marketCount()
tokenURI(id)                             // NFT-compatible metadata URI

// Place a limit order to buy YES at 0.60 collateral per share
router.placeOrder{value: 6 ether}(
    marketId,         // PAMM market ID
    true,             // isYes: YES shares
    true,             // isBuy: buying (escrowing collateral)
    10 ether,         // shares: want 10 shares
    6 ether,          // collateral: paying 6 ETH (0.60 per share)
    uint56(block.timestamp + 1 days),  // deadline
    true              // partialFill: allow partial fills
);

// Place a limit order to sell NO at 0.45 collateral per share
router.placeOrder(
    marketId,
    false,            // isYes: NO shares
    false,            // isBuy: selling (escrowing shares)
    10 ether,         // shares: selling 10 shares
    4.5 ether,        // collateral: want 4.5 ETH (0.45 per share)
    uint56(block.timestamp + 1 days),
    true
);

// Fill an existing sell order (buy from maker)
router.fillOrder{value: expectedCollateral}(
    orderHash,        // Order to fill
    5 ether,          // sharesToFill (0 = fill all)
    recipient         // Who receives the shares
);

// Fill then route remainder to AMM
router.fillOrdersThenSwap{value: 10 ether}(
    marketId,
    true,             // isYes
    true,             // isBuy
    10 ether,         // totalCollateral
    9 ether,          // minSharesOut (slippage)
    orderHashes,      // Orders to try first
    30,               // feeOrHook for AMM remainder
    recipient
);

// Cancel and reclaim escrowed tokens
router.cancelOrder(orderHash);

// Batch cancel multiple orders
router.batchCancelOrders(orderHashes);

// Buy YES shares via PAMM AMM
router.buy{value: 1 ether}(
    marketId,
    true,             // isYes
    1 ether,          // collateralIn
    0.9 ether,        // minSharesOut (slippage)
    30,               // feeOrHook
    recipient
);

// Sell NO shares via PAMM AMM
router.sell(
    marketId,
    false,            // isYes (NO)
    1 ether,          // sharesIn
    0.4 ether,        // minCollateralOut
    30,               // feeOrHook
    recipient
);

// Swap YES -> NO directly via ZAMM pool
router.swapShares(
    marketId,
    true,             // yesForNo: YES -> NO
    1 ether,          // amountIn
    0.9 ether,        // minOut
    30,               // feeOrHook
    recipient
);

// Swap shares directly to collateral (if ZAMM pool exists)
router.swapSharesToCollateral(marketId, true, 1 ether, 0.5 ether, 30, recipient);

// Swap collateral directly to shares (if ZAMM pool exists)
router.swapCollateralToShares{value: 1 ether}(marketId, true, 1 ether, 1.5 ether, 30, recipient);

// Split collateral into YES + NO shares
router.split{value: 1 ether}(marketId, 1 ether, recipient);

// Merge YES + NO shares back into collateral
router.merge(marketId, 1 ether, recipient);

// Claim winnings from resolved market
router.claim(marketId, recipient);

// Limit Orders
placeOrder(marketId, isYes, isBuy, shares, collateral, deadline, partialFill) → orderHash
cancelOrder(orderHash)
fillOrder(orderHash, sharesToFill, to) → (sharesFilled, collateralFilled)
fillOrdersThenSwap(marketId, isYes, isBuy, totalAmount, minOutput,
                   orderHashes[], feeOrHook, to) → totalOutput
batchCancelOrders(orderHashes[]) → cancelled

// Market Orders (via PAMM AMM)
buy(marketId, isYes, collateralIn, minSharesOut, feeOrHook, to) → sharesOut
sell(marketId, isYes, sharesIn, minCollateralOut, feeOrHook, to) → collateralOut

// Share Swaps (via ZAMM)
swapShares(marketId, yesForNo, amountIn, minOut, feeOrHook, to) → amountOut
swapSharesToCollateral(marketId, isYes, sharesIn, minCollateralOut, feeOrHook, to) → collateralOut
swapCollateralToShares(marketId, isYes, collateralIn, minSharesOut, feeOrHook, to) → sharesOut

// Collateral Operations
split(marketId, amount, to)
merge(marketId, amount, to)
claim(marketId, to) → payout

// Order Views
getOrder(orderHash) → (order, sharesFilled, sharesRemaining, collateralFilled, collateralRemaining, active)
isOrderActive(orderHash) → bool
getMarketOrderCount(marketId) → count
getUserOrderCount(user) → count
getMarketOrderHashes(marketId, offset, limit) → orderHashes[]
getUserOrderHashes(user, offset, limit) → orderHashes[]
getActiveOrders(marketId, isYes, isBuy, limit) → (orderHashes[], orderDetails[])
getBestOrders(marketId, isYes, isBuy, limit) → orderHashes[]

// UX Helpers
getBidAsk(marketId, isYes) → (bidPrice, askPrice, bidCount, askCount)
getOrderbook(marketId, isYes, depth) → (bidHashes[], bidPrices[], bidSizes[],
                                        askHashes[], askPrices[], askSizes[])
getUserPositions(user, marketIds[]) → (yesBalances[], noBalances[])
getUserActiveOrders(user, marketId, limit) → (orderHashes[], orderDetails[])

// Utility
multicall(bytes[] data) → results[]
permit(token, owner, value, deadline, v, r, s)

struct Order {
    address owner;      // Order creator
    uint56 deadline;    // Expiration timestamp
    bool isYes;         // YES or NO shares
    bool isBuy;         // Buying or selling shares
    bool partialFill;   // Allow partial fills
    uint96 shares;      // Share amount
    uint96 collateral;  // Collateral amount
    uint256 marketId;   // PAMM market ID
}

// Get full orderbook for YES shares
(
    bytes32[] memory bidHashes,
    uint256[] memory bidPrices,
    uint256[] memory bidSizes,
    bytes32[] memory askHashes,
    uint256[] memory askPrices,
    uint256[] memory askSizes
) = router.getOrderbook(marketId, true, 10);

// Result (example):
// Bids (buy orders, highest first):
//   0.65 - 5 shares
//   0.60 - 10 shares
//   0.55 - 3 shares
//
// Asks (sell orders, lowest first):
//   0.70 - 8 shares
//   0.75 - 4 shares
//   0.80 - 12 shares

// TWAP observation (call periodically for accurate pricing)
router.updateTWAPObservation(marketId);

// Get current TWAP price
uint256 twapBps = router.getTWAPPrice(marketId);

// Create bid pool: willing to buy YES at 60% (6000 bps)
router.createBidPool(marketId, collateralAmount, true, 6000, recipient);

// Seller sweeps bid pools
router.sellWithSweep(marketId, isYes, shares, minOut, minPriceBps, recipient, deadline);

// Mint 1 ETH worth of shares, keep YES, pool NO at 40% (4000 bps)
router.mintAndPool(marketId, 1 ether, true, 4000, recipient);

// Or deposit existing shares to a pool
router.depositSharesToPool(marketId, false, shares, 4000, recipient);

// Claim collateral when your shares get bought
router.claimProceeds(marketId, false, 4000, recipient);

// Create bid pool: willing to buy YES at 60% (6000 bps)
router.createBidPool(marketId, 1 ether, true, 6000, recipient);

// Claim shares when your bid gets filled
router.claimBidShares(marketId, true, 6000, recipient);

// Get best ask (lowest sell price with liquidity)
(uint256 bestAsk, uint256 depth) = router.getBestAsk(marketId, true);

// Get best bid (highest buy price with liquidity)
(uint256 bestBid, uint256 depth) = router.getBestBid(marketId, true);

// Get spread
(uint256 bid, uint256 ask, uint256 spread) = router.getSpread(marketId, true);

// Get full orderbook at specific prices
router.getOrderbook(marketId, true, pricesArray);

bytes[] memory calls = new bytes[](2);
calls[0] = abi.encodeCall(router.mintAndPool, (marketId, 1 ether, true, 4000, recipient));
calls[1] = abi.encodeCall(router.createBidPool, (marketId, 1 ether, false, 6000, recipient));
router.multicall{value: 2 ether}(calls);

// ASK Pool (sell orders)
mintAndPool(marketId, collateralIn, keepYes, priceInBps, to) → poolId
depositSharesToPool(marketId, isYes, sharesIn, priceInBps, to) → poolId
claimProceeds(marketId, isYes, priceInBps, to) → collateralClaimed
withdrawFromPool(marketId, isYes, priceInBps, sharesToWithdraw, to) → withdrawn
migrateAskPosition(marketId, isYes, fromPrice, toPrice, to) → (sharesWithdrawn, collateralClaimed, newPoolId)

// BID Pool (buy orders)
createBidPool(marketId, collateralIn, buyYes, priceInBps, to) → bidPoolId
claimBidShares(marketId, isYes, priceInBps, to) → sharesClaimed
withdrawFromBidPool(marketId, buyYes, priceInBps, collateralToWithdraw, to) → withdrawn
migrateBidPosition(marketId, buyYes, fromPrice, toPrice, to) → (collateralWithdrawn, sharesClaimed, newBidPoolId)

// Smart Routing
buy(marketId, buyYes, collateralIn, minSharesOut, poolPriceInBps, to, deadline) → (totalSharesOut, sources)
buyWithSweep(marketId, buyYes, collateralIn, minSharesOut, maxPriceBps, to, deadline) → (totalSharesOut, poolSharesOut, poolLevelsFilled, sources)
sell(marketId, sellYes, sharesIn, minCollateralOut, bidPoolPriceInBps, to, deadline) → (totalCollateralOut, sources)
sellWithSweep(marketId, sellYes, sharesIn, minCollateralOut, minPriceBps, to, deadline) → (totalCollateralOut, poolCollateralOut, poolLevelsFilled, sources)

// Vault Integration
mintAndVault(marketId, collateralIn, keepYes, to) → (sharesKept, vaultShares)
mintAndSellOther(marketId, collateralIn, keepYes, minPriceBps, to, deadline) → (sharesKept, collateralRecovered)
provideLiquidity(marketId, collateralAmount, vaultYesShares, vaultNoShares, ammLPShares, minAmount0, minAmount1, to, deadline) → (yesVaultSharesMinted, noVaultSharesMinted, ammLiquidity)

// View Functions
getPoolId(marketId, isYes, priceInBps) → poolId
getBidPoolId(marketId, buyYes, priceInBps) → bidPoolId
getUserPosition(marketId, isYes, priceInBps, user) → (scaled, withdrawableShares, pendingCollateral, debt)
getBidPosition(marketId, buyYes, priceInBps, user) → (scaled, withdrawableCollateral, pendingShares, debt)
getBestAsk(marketId, isYes) → (priceInBps, depth)
getBestBid(marketId, buyYes) → (priceInBps, depth)
getSpread(marketId, isYes) → (bestBid, bestAsk, spreadBps)
getOrderbook(marketId, isYes, pricesInBps[]) → (askDepths[], bidDepths[])

// Utilities
multicall(data[]) → results[]
permit(token, owner, value, deadline, v, r, s)
permitDAI(owner, value, nonce, deadline, v, r, s)

// Lifecycle
createMarket(description, resolver, close, canClose) → (marketId, noId)
closeMarket(marketId)                    // resolver early-close (if canClose)
resolve(marketId, outcome)               // sets winner, calculates payoutPerShare

// Trading (before close)
buyYes(marketId, amount, to)             // accepts ETH or wstETH
buyNo(marketId, amount, to)
sellYes(marketId, amount, to)
sellNo(marketId, amount, to)

// Settlement
claim(marketId, to)

// Resolver
setResolverFeeBps(bps)                   // max 1000 (10%)

// Views
getMarket(marketId)
getMarkets(start, count)
getUserMarkets(user, start, count)
tradingOpen(marketId)
impliedYesOdds(marketId)                 → (yesSupply, total)  // YES prob ≈ yesSupply/total
winningId(marketId)
marketCount()

// Create markets (scalar conditions)
createNumericMarket(observable, collateral, target, callData, op, threshold, close, canClose)
createNumericMarketSimple(observable, collateral, target, selector, op, threshold, close, canClose)
createNumericMarketAndSeed(..., SeedParams)      // + LP seeding
createNumericMarketSeedAndBuy(..., SeedParams, SwapParams)  // + initial position

// Create markets (ratio conditions)
createRatioMarket(observable, collateral, targetA, callDataA, targetB, callDataB, op, threshold, close, canClose)
createRatioMarketSimple(...)   // with bytes4 selectors
createRatioMarketAndSeed(...)  // + LP seeding
createRatioMarketSeedAndBuy(...)  // + initial position

// Register conditions for existing PAMM markets
registerConditionForExistingMarket(marketId, target, callData, op, threshold)
registerConditionForExistingMarketSimple(marketId, target, selector, op, threshold)
registerRatioConditionForExistingMarket(marketId, targetA, callDataA, targetB, callDataB, op, threshold)
registerRatioConditionForExistingMarketSimple(marketId, targetA, selectorA, targetB, selectorB, op, threshold)

// Resolution
resolveMarket(marketId)   // Anyone can call when ready
preview(marketId) → (value, condTrue, ready)  // Check resolution status

// Utility
multicall(bytes[] data)   // Batch operations
permit(token, owner, value, deadline, v, r, s)  // EIP-2612 permit
permitDAI(token, owner, nonce, deadline, allowed, v, r, s)  // DAI-style permit
buildDescription(...)     // Preview auto-generated description

struct SeedParams {
    uint256 collateralIn;   // Any amount (1:1 shares, dust refunded)
    uint256 feeOrHook;      // ZAMM fee tier or hook address
    uint256 amount0Min;     // Slippage protection
    uint256 amount1Min;
    uint256 minLiquidity;
    address lpRecipient;
    uint256 deadline;
}

struct SwapParams {
    uint256 collateralForSwap;  // Amount for buyYes/buyNo
    uint256 minOut;             // Minimum tokens out
    bool yesForNo;              // true = buyNo, false = buyYes
    address recipient;          // Recipient of swapped shares (address(0) = msg.sender)
}

Resolver.SeedParams memory seed = Resolver.SeedParams({
    collateralIn: 10 ether,       // Any amount (1:1 shares)
    feeOrHook: 30,                // ZAMM fee tier (30 = 0.3%)
    amount0Min: 0,                // Slippage protection
    amount1Min: 0,
    minLiquidity: 0,
    lpRecipient: msg.sender,      // Who receives LP tokens
    deadline: block.timestamp + 1 hours
});

// "ETH > $5000 by Dec 31, 2025"
// YES wins if price exceeds $5000 at any point (canClose=true)

Resolver.SeedParams memory seed = Resolver.SeedParams({
    collateralIn: 10 ether,
    feeOrHook: 30,
    amount0Min: 0,
    amount1Min: 0,
    minLiquidity: 0,
    lpRecipient: msg.sender,
    deadline: block.timestamp + 1 hours
});

resolver.createNumericMarketAndSeed{value: 10 ether}(
    "ETH/USD price",
    address(0),                                    // ETH collateral
    0x5f4eC3Df9cbd43714FE2740f5E3616155c5b8419,    // Chainlink ETH/USD
    abi.encodeWithSignature("latestAnswer()"),     // returns int256 (works as uint256 for prices)
    Resolver.Op.GT,
    5000e8,                                        // $5000 (Chainlink uses 8 decimals)
    1735689600,                                    // Dec 31, 2025 Unix timestamp
    true,                                          // early close allowed
    seed
);

// "USDC supply > 50B by June 2025"

address USDC = 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48;
IERC20(USDC).approve(address(resolver), 10000e6);

Resolver.SeedParams memory seed = Resolver.SeedParams({
    collateralIn: 10000e6,        // 10,000 USDC (6 decimals)
    feeOrHook: 30,
    amount0Min: 0,
    amount1Min: 0,
    minLiquidity: 0,
    lpRecipient: msg.sender,
    deadline: block.timestamp + 1 hours
});

resolver.createNumericMarketAndSeed(              // No {value} for ERC20
    "USDC total supply",
    USDC,                                          // USDC as collateral
    USDC,                                          // target = USDC contract
    abi.encodeWithSignature("totalSupply()"),
    Resolver.Op.GT,
    50_000_000_000e6,                              // 50B (6 decimals)
    1719792000,                                    // June 30, 2025
    true,
    seed
);

// Create market, seed LP, and immediately buy YES in one transaction

Resolver.SeedParams memory seed = Resolver.SeedParams({
    collateralIn: 10 ether,
    feeOrHook: 30,
    amount0Min: 0,
    amount1Min: 0,
    minLiquidity: 0,
    lpRecipient: msg.sender,
    deadline: block.timestamp + 1 hours
});

Resolver.SwapParams memory swap = Resolver.SwapParams({
    collateralForSwap: 2 ether,   // Buy tokens with 2 ETH
    minOut: 0,                    // Minimum tokens out (slippage)
    yesForNo: false,              // false = buyYes, true = buyNo
    recipient: address(0)         // address(0) = msg.sender
});

// msg.value = seed.collateralIn + swap.collateralForSwap
resolver.createNumericMarketSeedAndBuy{value: 12 ether}(
    "ETH/USD price",
    address(0),
    0x5f4eC3Df9cbd43714FE2740f5E3616155c5b8419,
    abi.encodeWithSignature("latestAnswer()"),
    Resolver.Op.GT,
    4000e8,
    1735689600,
    true,
    seed,
    swap
);

// "Vitalik holds > 100k ETH"
// Pass empty callData ("") to check target's ETH balance

Resolver.SeedParams memory seed = Resolver.SeedParams({
    collateralIn: 5 ether,
    feeOrHook: 30,
    amount0Min: 0,
    amount1Min: 0,
    minLiquidity: 0,
    lpRecipient: msg.sender,
    deadline: block.timestamp + 1 hours
});

resolver.createNumericMarketAndSeed{value: 5 ether}(
    "vitalik.eth ETH balance",
    address(0),
    0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045,    // vitalik.eth
    "",                                            // empty = ETH balance check
    Resolver.Op.GT,
    100_000 ether,                                 // 100k ETH in wei
    1735689600,
    true,
    seed
);

// "Proposal passes (forVotes > againstVotes)"
// Ratio = forVotes / againstVotes, threshold 1e18 = 1.0

Resolver.SeedParams memory seed = Resolver.SeedParams({
    collateralIn: 10 ether,
    feeOrHook: 30,
    amount0Min: 0,
    amount1Min: 0,
    minLiquidity: 0,
    lpRecipient: msg.sender,
    deadline: block.timestamp + 1 hours
});

resolver.createRatioMarketAndSeed{value: 10 ether}(
    "Proposal 42 vote ratio",
    address(0),
    GOVERNOR,                                      // targetA: forVotes
    abi.encodeWithSignature("proposalVotes(uint256)", 42),
    GOVERNOR,                                      // targetB: againstVotes
    abi.encodeWithSignature("proposalAgainst(uint256)", 42),
    Resolver.Op.GT,
    1e18,                                          // ratio > 1.0 means forVotes > againstVotes
    1704067200,                                    // voting end timestamp
    false,                                         // must wait for vote to end
    seed
);

// "Protocol gets paused"
// bool paused() returns true (1) or false (0)

Resolver.SeedParams memory seed = Resolver.SeedParams({
    collateralIn: 5 ether,
    feeOrHook: 30,
    amount0Min: 0,
    amount1Min: 0,
    minLiquidity: 0,
    lpRecipient: msg.sender,
    deadline: block.timestamp + 1 hours
});

resolver.createNumericMarketAndSeed{value: 5 ether}(
    "Protocol paused status",
    address(0),
    PROTOCOL_ADDRESS,
    abi.encodeWithSignature("paused()"),           // returns bool
    Resolver.Op.EQ,
    1,                                             // true == 1
    1735689600,
    true,                                          // YES wins immediately when paused
    seed
);

// Create market only, no liquidity seeding
// Anyone can add liquidity later via PAMM.splitAndAddLiquidity()

(uint256 marketId, uint256 noId) = resolver.createNumericMarket(
    "ETH/USD price",
    address(0),                                    // ETH collateral
    0x5f4eC3Df9cbd43714FE2740f5E3616155c5b8419,
    abi.encodeWithSignature("latestAnswer()"),
    Resolver.Op.GT,
    5000e8,
    1735689600,
    true
);

// Use bytes4 selector instead of full calldata (for no-argument functions)

resolver.createNumericMarketAndSeedSimple{value: 10 ether}(
    "ETH/USD price",
    address(0),
    0x5f4eC3Df9cbd43714FE2740f5E3616155c5b8419,
    bytes4(keccak256("latestAnswer()")),           // just 4-byte selector
    Resolver.Op.GT,
    5000e8,
    1735689600,
    true,
    seed
);

// Owner configures rewards
oracle.setReward(0.001 ether, 1 hours);  // Pay 0.001 ETH per update, min 1hr cooldown
oracle.receive{value: 10 ether}();       // Fund the contract

// Keepers call update() and receive rewards
// - Reward paid only if elapsed >= cooldown
// - Cooldown prevents rapid draining

// op=3 (GTE): YES wins if baseFeeAverage >= 50 gwei
oracle.createMarket{value: 10 ether}(
    50 gwei,                      // threshold in wei (50 gwei target)
    address(0),                   // collateral (ETH)
    uint64(1735689600),          // close timestamp (Dec 31, 2025)
    true,                         // canClose (early resolution if condition met)
    3,                            // op: 3=GTE (>=), 2=LTE (<=)
    10 ether,                     // collateralIn (liquidity to seed)
    30,                           // feeOrHook (30 bps = 0.3% ZAMM fee)
    0,                            // minLiquidity (slippage protection)
    msg.sender                    // lpRecipient
);
// Observable: "Avg Ethereum base fee >= 50 gwei"

// op=2 (LTE): YES wins if baseFeeAverage <= 30 gwei
oracle.createMarket{value: 10 ether}(
    30 gwei,                      // threshold in wei
    address(0),                   // collateral (ETH)
    uint64(1735689600),          // close timestamp
    false,                        // canClose=false (check at deadline only)
    2,                            // op: 2=LTE (<=)
    10 ether,
    30,
    0,
    msg.sender
);
// Observable: "Avg Ethereum base fee <= 30 gwei"

// Create market + take position to set initial odds away from 50/50
GasPM.SeedParams memory seed = GasPM.SeedParams({
    collateralIn: 10 ether,
    feeOrHook: 30,
    amount0Min: 0,
    amount1Min: 0,
    minLiquidity: 0,
    lpRecipient: msg.sender,
    deadline: block.timestamp + 1 hours
});

GasPM.SwapParams memory swap = GasPM.SwapParams({
    collateralForSwap: 2 ether,   // Additional collateral to buy position
    minOut: 0,
    yesForNo: false,              // false = buyYes, true = buyNo
    recipient: address(0)         // address(0) = msg.sender
});

// msg.value = seed.collateralIn + swap.collateralForSwap = 12 ether
oracle.createMarketAndBuy{value: 12 ether}(
    50 gwei,                      // threshold in wei
    address(0),                   // ETH collateral
    uint64(1735689600),
    true,                         // canClose
    3,                            // op: GTE
    seed,
    swap
);

// Range market: YES wins if 30 <= baseFeeAverage <= 70 gwei
oracle.createRangeMarket{value: 10 ether}(
    30 gwei,                      // lower bound in wei (inclusive)
    70 gwei,                      // upper bound in wei (inclusive)
    address(0),                   // collateral (ETH)
    uint64(1735689600),          // close timestamp
    false,                        // canClose=false (check at deadline)
    10 ether,
    30,
    0,
    msg.sender
);
// Observable: "Avg Ethereum base fee between 30-70 gwei"

// Breakout market: YES wins if baseFeeAverage < 30 OR > 70 gwei
// Use canClose=true to get early payout when breakout occurs
oracle.createBreakoutMarket{value: 10 ether}(
    30 gwei,                      // lower bound in wei
    70 gwei,                      // upper bound in wei
    address(0),                   // collateral (ETH)
    uint64(1735689600),          // close timestamp
    true,                         // canClose=true (early close on breakout!)
    10 ether,
    30,
    0,
    msg.sender
);
// Observable: "Avg Ethereum base fee outside 30-70 gwei"

// Peak market: YES wins if baseFeeMax >= 100 gwei at any point since deployment
// Uses historical max, not TWAP — captures extreme spikes
oracle.createPeakMarket{value: 10 ether}(
    100 gwei,                     // threshold in wei
    address(0),                   // collateral (ETH)
    uint64(1735689600),          // close timestamp
    true,                         // canClose=true (instant payout when peak hit!)
    10 ether,
    30,
    0,
    msg.sender
);
// Observable: "Ethereum base fee spikes to 100 gwei"

// Trough market: YES wins if baseFeeMin <= 10 gwei at any point since deployment
// Uses historical min — captures extreme dips
oracle.createTroughMarket{value: 10 ether}(
    10 gwei,                      // threshold in wei
    address(0),                   // collateral (ETH)
    uint64(1735689600),          // close timestamp
    true,                         // canClose=true (instant payout when dip occurs!)
    10 ether,
    30,
    0,
    msg.sender
);
// Observable: "Ethereum base fee dips to 10 gwei"

// Volatility market: YES wins if baseFeeSpread (max - min) >= 50 gwei
// Bets on high volatility - gas swings between extremes
oracle.createVolatilityMarket{value: 10 ether}(
    50 gwei,                      // threshold in wei
    address(0),                   // collateral (ETH)
    uint64(1735689600),          // close timestamp
    true,                         // canClose=true (instant payout when volatility hits!)
    10 ether,
    30,
    0,
    msg.sender
);
// Observable: "Ethereum base fee swings 50 gwei"

// Stability market: YES wins if baseFeeSpread (max - min) <= 20 gwei
// Opposite of volatility - bets on calm, stable gas prices
oracle.createStabilityMarket{value: 10 ether}(
    20 gwei,                      // threshold in wei
    address(0),                   // collateral (ETH)
    uint64(1735689600),          // close timestamp
    false,                        // canClose=false (check at deadline only)
    10 ether,
    30,
    0,
    msg.sender
);
// Observable: "Ethereum base fee stays within 20 gwei spread"

// Spot market: YES wins if baseFeeCurrent >= 100 gwei at resolution
// Uses live block.basefee, not TWAP - best for high thresholds
oracle.createSpotMarket{value: 10 ether}(
    100 gwei,                     // threshold in wei
    address(0),                   // collateral (ETH)
    uint64(1735689600),          // close timestamp
    true,                         // canClose=true (instant payout when threshold hit!)
    10 ether,
    30,
    0,
    msg.sender
);
// Observable: "Ethereum base fee spot price reaches 100 gwei"

// Comparison market: YES wins if TWAP at close > TWAP at creation
// Snapshots current TWAP, compares at resolution
oracle.createComparisonMarket{value: 10 ether}(
    address(0),                   // collateral (ETH)
    uint64(1735689600),          // close timestamp
    10 ether,
    30,
    0,
    msg.sender
);
// Observable: "Ethereum base fee TWAP higher than 50 gwei start"

// With USDC as collateral
IERC20(USDC).approve(address(oracle), 10000e6);
oracle.createMarket(
    50 gwei,                      // threshold in wei
    USDC,                         // collateral (ERC20)
    uint64(1735689600),
    true,
    3,                            // op: GTE
    10000e6,                      // 10,000 USDC
    30,
    0,
    msg.sender
);

// Window Market: "Gas average will exceed 50 gwei DURING THIS MARKET"
// TWAP calculated from market creation, not oracle deploy
oracle.createWindowMarket{value: 10 ether}(
    50 gwei,                      // threshold
    address(0),
    uint64(block.timestamp + 7 days),  // 1 week market
    true,                         // canClose on condition
    3,                            // op: GTE
    10 ether,
    30,
    0,
    msg.sender
);
// Observable: "Avg gas during market >= 50 gwei"

// Window Peak: "Will gas hit 100 gwei DURING THIS MARKET?"
// Reverts if current basefee >= 100 gwei (threshold already hit)
// Always enables early close (resolves when spike occurs)
oracle.createWindowPeakMarket{value: 10 ether}(
    100 gwei,
    address(0),
    uint64(block.timestamp + 7 days),
    10 ether,
    30,
    0,
    msg.sender
);
// Observable: "Gas spikes to 100 gwei during market"

// Window Trough: "Will gas dip to 10 gwei DURING THIS MARKET?"
// Reverts if current basefee <= 10 gwei (threshold already hit)
// Always enables early close (resolves when dip occurs)
oracle.createWindowTroughMarket{value: 10 ether}(
    10 gwei,
    address(0),
    uint64(block.timestamp + 7 days),
    10 ether,
    30,
    0,
    msg.sender
);
// Observable: "Gas dips to 10 gwei during market"

// Window Volatility: "Will gas spread exceed 30 gwei DURING THIS MARKET?"
// Tracks absolute spread (max - min) during the market window
// Call pokeWindowVolatility(marketId) periodically to capture extremes
// Always enables early close (resolves when spread threshold hit)
oracle.createWindowVolatilityMarket{value: 10 ether}(
    30 gwei,
    address(0),
    uint64(block.timestamp + 7 days),
    10 ether,
    30,
    0,
    msg.sender
);
// Observable: "Gas spread exceeds 30 gwei during market"

// Window Stability: "Will gas spread stay below 10 gwei DURING THIS MARKET?"
// Tracks absolute spread (max - min) during the market window
oracle.createWindowStabilityMarket{value: 10 ether}(
    10 gwei,                      // max 10 gwei spread allowed
    address(0),
    uint64(block.timestamp + 7 days),
    false,                        // check at deadline only
    10 ether,
    30,
    0,
    msg.sender
);
// Observable: "Gas spread stays below 10 gwei during market"

// Use permit to approve + create market in one tx
bytes[] memory calls = new bytes[](2);
calls[0] = abi.encodeCall(oracle.permit, (token, msg.sender, amount, deadline, v, r, s));
calls[1] = abi.encodeCall(oracle.createMarket, (...));
oracle.multicall(calls);

// TWAP Oracle (Lifetime)
update()                          // Record current basefee, earn reward if eligible
baseFeeAverage() → uint256        // TWAP in wei (since deploy)
baseFeeAverageGwei() → uint256    // TWAP in gwei
baseFeeInRange(lower, upper) → uint256     // Returns 1 if TWAP in range (bounds in wei)
baseFeeOutOfRange(lower, upper) → uint256  // Returns 1 if TWAP outside range (bounds in wei)
baseFeeCurrent() → uint256        // Spot basefee in wei
baseFeeCurrentGwei() → uint256    // Spot basefee in gwei
baseFeeMax() → uint256            // Highest basefee ever recorded (wei)
baseFeeMin() → uint256            // Lowest basefee ever recorded (wei)
baseFeeSpread() → uint256         // Volatility: max - min (wei)
trackingDuration() → uint256      // Seconds since oracle deployed

// TWAP Oracle (Window / Market-Specific)
baseFeeAverageSince(marketId) → uint256    // TWAP since market creation (wei)
baseFeeInRangeSince(marketId, lower, upper) → uint256     // Returns 1 if window TWAP in range
baseFeeOutOfRangeSince(marketId, lower, upper) → uint256  // Returns 1 if window TWAP outside range
baseFeeMaxSince(marketId) → uint256        // Max basefee during market window (wei)
baseFeeMinSince(marketId) → uint256        // Min basefee during market window (wei)
baseFeeSpreadSince(marketId) → uint256     // Absolute spread (max - min) during market window
baseFeeHigherThanStart(marketId) → uint256 // Returns 1 if TWAP > start (comparison markets)
pokeWindowVolatility(marketId)             // Update window market's max/min to current basefee
pokeWindowVolatilityBatch(marketIds[])     // Batch update multiple window markets

// Lifetime Market Creation (all thresholds/bounds in wei)
createMarket(threshold, collateral, close, canClose, op,
             collateralIn, feeOrHook, minLiquidity, lpRecipient) → marketId
createMarketAndBuy(threshold, collateral, close, canClose, op,
                   SeedParams, SwapParams) → (marketId, swapOut)
createRangeMarket(lower, upper, collateral, close, canClose,
                  collateralIn, feeOrHook, minLiquidity, lpRecipient) → marketId
createRangeMarketAndBuy(lower, upper, collateral, close, canClose,
                        SeedParams, SwapParams) → (marketId, swapOut)
createBreakoutMarket(lower, upper, collateral, close, canClose,
                     collateralIn, feeOrHook, minLiquidity, lpRecipient) → marketId
createPeakMarket(threshold, collateral, close, canClose,
                 collateralIn, feeOrHook, minLiquidity, lpRecipient) → marketId
createTroughMarket(threshold, collateral, close, canClose,
                   collateralIn, feeOrHook, minLiquidity, lpRecipient) → marketId
createVolatilityMarket(threshold, collateral, close, canClose,
                       collateralIn, feeOrHook, minLiquidity, lpRecipient) → marketId
createStabilityMarket(threshold, collateral, close, canClose,
                      collateralIn, feeOrHook, minLiquidity, lpRecipient) → marketId
createSpotMarket(threshold, collateral, close, canClose,
                 collateralIn, feeOrHook, minLiquidity, lpRecipient) → marketId
createComparisonMarket(collateral, close,
                       collateralIn, feeOrHook, minLiquidity, lpRecipient) → marketId

// Window Market Creation (TWAP calculated from market creation)
createWindowMarket(threshold, collateral, close, canClose, op,
                   collateralIn, feeOrHook, minLiquidity, lpRecipient) → marketId
createWindowMarketAndBuy(threshold, collateral, close, canClose, op,
                         SeedParams, SwapParams) → (marketId, swapOut)
createWindowRangeMarket(lower, upper, collateral, close, canClose,
                        collateralIn, feeOrHook, minLiquidity, lpRecipient) → marketId
createWindowRangeMarketAndBuy(lower, upper, collateral, close, canClose,
                              SeedParams, SwapParams) → (marketId, swapOut)
createWindowBreakoutMarket(lower, upper, collateral, close, canClose,
                           collateralIn, feeOrHook, minLiquidity, lpRecipient) → marketId
createWindowPeakMarket(threshold, collateral, close,
                       collateralIn, feeOrHook, minLiquidity, lpRecipient) → marketId  // always canClose=true
createWindowTroughMarket(threshold, collateral, close,
                         collateralIn, feeOrHook, minLiquidity, lpRecipient) → marketId  // always canClose=true
createWindowVolatilityMarket(threshold, collateral, close,
                             collateralIn, feeOrHook, minLiquidity, lpRecipient) → marketId  // always canClose=true
createWindowStabilityMarket(threshold, collateral, close, canClose,
                            collateralIn, feeOrHook, minLiquidity, lpRecipient) → marketId

// Market Views (for dapp)
marketCount() → uint256
getMarkets(start, count) → uint256[]
getMarketInfos(start, count) → MarketInfo[]
isOurMarket(marketId) → bool
marketSnapshots(marketId) → (cumulative, timestamp)  // Window market snapshot

// Owner Functions
setReward(rewardAmount, cooldown)
setPublicCreation(enabled)        // Allow anyone to create markets
withdraw(to, amount)
transferOwnership(newOwner)

// Utility
multicall(bytes[] data)           // Batch multiple calls
permit(token, owner, value, deadline, v, r, s)       // EIP-2612 permit
permitDAI(token, owner, nonce, deadline, allowed, v, r, s)  // DAI-style permit

struct SeedParams {
    uint256 collateralIn;   // Liquidity to seed
    uint256 feeOrHook;      // ZAMM fee tier (30 = 0.3%)
    uint256 amount0Min;     // Slippage protection
    uint256 amount1Min;
    uint256 minLiquidity;
    address lpRecipient;
    uint256 deadline;
}

struct SwapParams {
    uint256 collateralForSwap;  // Additional collateral for position
    uint256 minOut;             // Minimum tokens out
    bool yesForNo;              // true = buyNo (swap yes for no), false = buyYes (swap no for yes)
    address recipient;          // Recipient of swapped shares (address(0) = msg.sender)
}

struct MarketInfo {
    uint256 marketId;
    uint64 close;           // Market close timestamp
    bool resolved;          // Has market been resolved
    bool outcome;           // YES (true) or NO (false)
    uint256 currentValue;   // Current baseFeeAverage()
    bool conditionMet;      // Is threshold currently exceeded
    bool ready;             // Can be resolved now
}