PrecogMarket (V7) Documentation
Overview
PrecogMarketV7 is a Solidity-based implementation of a liquidity-sensitive LMSR (Logarithmic Market Scoring Rule) market maker. The contract facilitates prediction market mechanisms, allowing users to buy and sell shares of possible outcomes in exchange for a collateral token.
Key Features
- Market Creation & Setup: Administered by the contract owner, supporting multiple outcomes.
- Liquidity Management: Utilizes an adaptive LMSR model to price outcome shares dynamically.
- Trading Mechanism: Users can buy and sell shares of specific outcomes.
- Oracle Integration: A designated oracle reports the final outcome.
- Collateral & Redemption: Users redeem shares based on the final outcome.
- Security Measures: Access control modifiers and safeguards for market integrity.
Contract Components
1. State Variables
Public Variables
- owner: The contract’s owner (typically a PrecogMaster contract).
- token: The ERC-20 token used as collateral.
- id: Unique identifier for the market.
- totalOutcomes: The number of possible outcomes (e.g., 2 means YES/NO).
- oracle: Address responsible for reporting results.
- startTimestamp: Timestamp when trading starts.
- endTimestamp: Timestamp when trading ends.
- closeTimestamp: Timestamp when the final result is reported.
- result: The final outcome determined by the oracle.
- accountShares: Mapping storing share balances per account.
Private Variables
- shares: Array storing the number of shares per outcome.
- beta, alpha: Liquidity parameters for the LMSR model.
- dust: Used to mitigate token leakage in share selling.
- currentCost: Tracks the total liquidity in the market.
- totalShares: Total number of shares across all outcomes.
- totalBuys, totalSells: Counters tracking buy/sell transactions.
- marketSetup, internalCall: Flags indicating market configuration status.
Functions
1. Market Setup
initialize(address _token)
- Initializes the contract with a collateral token.
- Can only be called once.
setup(uint _id, address _oracle, uint _totalOutcomes, uint _subsidy, uint _overround)
- Configures the market parameters.
- Requires an initial subsidy for market liquidity.
- Computes LMSR variables (
alpha
,beta
).
2. Trading Functions
buy(uint256 _outcome, int128 _amount) → (uint256 tokenCost)
- Allows users to purchase outcome shares.
- Calls
_buy()
internally.
_buy(uint256 _outcome, int128 _amount, address _account) → (uint256 tokenCost)
- Core function handling the buying process.
- Updates share balances, total shares, and liquidity.
sell(uint256 _outcome, int128 _amount) → (uint256 tokenReturn)
- Allows users to sell their outcome shares.
- Calls
_sell()
internally.
_sell(uint256 _outcome, int128 _amount, address _account) → (uint256 tokenReturn)
- Handles share selling calculations.
- Adjusts market liquidity and returns collateral.
3. Market Administration
updateDates(uint256 _startTimestamp, uint256 _endTimestamp)
- Updates market start and end times.
updateOracle(address _newOracle)
- Assigns a new oracle address.
reportResult(uint256 _id, uint256 _outcome)
- Oracle submits the final market result.
- Validates input and ensures market has ended.
4. Share Redemption & Withdrawals
redeemShares() → (uint256 redeemedShares)
- Users redeem their shares based on the final outcome.
- Calls
_redeem()
internally.
_redeem(address _account) → (uint256 redeemedShares)
- Handles share redemption per account.
- Transfers the corresponding collateral to users.
withdraw(address _token)
- Owner withdraws any remaining collateral after market closure.
5. Ownership Management
transferOwnership(address _newOwner)
- Transfers contract ownership to a new address.
6. Market Data & Pricing
cost() → (int128 totalCost)
- Returns the total cost in the market.
buyPrice(uint256 _outcome, int128 _amount) → (int128 tokenCost)
- Calculates the cost of buying shares.
sellPrice(uint256 _outcome, int128 _amount) → (int128 tokenReturn)
- Calculates the return from selling shares.
getMarketInfo() → (int128, int128[], int128, uint256, uint256)
- Retrieves current market state details.
getPrices() → (uint256[] memory buyPrices, uint256[] memory sellPrices)
- Fetches buy and sell prices for all outcomes.
getAccountOutcomeBalances(address _account) → (uint256[] memory balances)
- Gets a user’s share balances across all outcomes.
7. Internal Math Functions
costAfterBuy(uint256 _outcome, int128 _amount) → (int128)
- Computes market cost after a buy operation.
costAfterSell(uint256 _outcome, int128 _amount) → (int128)
- Computes market cost after a sell operation.
getTokenWei(address _token, int128 _amount) → (uint256)
- Converts int128 (fixed point) to token amount in wei.
getTokenEth(address _token, uint256 _amount) → (int128)
- Converts token amount in wei to int128 (fixed point).
Conclusion
The PrecogMarketV7 contract provides a robust and adaptive market-making mechanism for prediction markets.