SMART CONTRACTSMaster Contract

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.

Scaffold Precog