# API Reference

## Classes

class `Gnosis`(opts)

  Represents the Gnosis Prediction Markets JS Library API

  Warning: Do not use constructor directly. Some asynchronous initialization will not be handled. Instead, use Gnosis.create.

  `Gnosis.``contracts`

    A collection of Truffle contract abstractions for the following Gnosis contracts:

    - Math
    - Event
    - CategoricalEvent
    - ScalarEvent
    - EventFactory
    - Token
    - HumanFriendlyToken
    - Ether Token
    - CentralizedOracle
    - CentralizedOracleFactory
    - UltimateOracle
    - UltimateOracleFactory
    - LMSR Market Maker
    - Market
    - StandardMarket
    - Standard Market Factory

    These are configured to use the web3 provider specified in Gnosis.create or subsequently modified with Gnosis.setWeb3Provider. The default gas costs for these abstractions are set to the maximum cost of their respective entries found in the gas-stats.json file built from the core contracts. Additionally, the default message sender (i.e. from address) is set via the optional defaultAccount param in Gnosis.setWeb3Provider.

  `Gnosis.``create`(opts)

    Factory function for asynchronously creating an instance of the API

    Note: this method is asynchronous and will return a Promise

    Arguments:

    - opts.ethereum (string|Provider) – An instance of a Web3 provider or a URL of a Web3 HTTP provider. If not specified, Web3 provider will be either the browser-injected Web3 (Mist/MetaMask) or an HTTP provider looking at http://localhost:8545
    - opts.defaultAccount (string) – The account to use as the default from address for ethereum transactions conducted through the Web3 instance. If unspecified, will be the first account found on Web3. See Gnosis.setWeb3Provider defaultAccount parameter for more info.
    - opts.ipfs (Object) – ipfs-mini configuration object
    - opts.ipfs.host (string) – IPFS node address
    - opts.ipfs.port (Number) – IPFS protocol port
    - opts.ipfs.protocol (string) – IPFS protocol name
    - opts.logger (function) – A callback for logging. Can also provide ‘console’ to use console.log.

    Returns: | Gnosis – An instance of the pm.js API

  `Gnosis.``defaultAccount`

    The default account to be used as the from address for transactions done with this Gnosis instance. If there is no account, this will not be set.

  `Gnosis.``etherToken`

    If on mainnet, this will be an EtherToken contract abstraction pointing to the MakerDAO WETH contract.

    Otherwise, if EtherToken is deployed to the current network, this will be set to an EtherToken contract abstraction pointing at the deployment address.

  `Gnosis.``importContracts`(artifacts, instanceNames)

    Imports contracts into this Gnosis instance using an object mapping contract names to their corresponding Truffle artifacts. Additionally, attempt to set attributes on the Gnosis instance corresponding to instanceNames.

    Note: this method is asynchronous and will return a Promise

    Arguments:

    - artifacts (Object) – Object mapping contract names to Truffle artifacts.
    - instanceNames (Object) – Object mapping contract names to the name of an attribute on the Gnosis instance which will represent the deployed version of the contract, analogous to `standardMarketFactory` or `lmsrMarketMaker`.

  `Gnosis.``lmsrMarketMaker`

    If LMSRMarketMaker is deployed to the current network, this will be set to an LMSRMarketMaker contract abstraction pointing at the deployment address.

  `Gnosis.``setWeb3Provider`(provider, defaultAccount)

    Setter for the ethereum web3 provider.

    Note: this method is asynchronous and will return a Promise

    Arguments:

    - provider (string|Provider) – An instance of a Web3 provider or a URL of a Web3 HTTP provider. If not specified, Web3 provider will be either the browser-injected Web3 (Mist/MetaMask) or an HTTP provider looking at http://localhost:8545
    - defaultAccount (string) – An address to be used as the default from account for conducting transactions using the associated Web3 instance. If not specified, will be inferred from Web3 using the first account obtained by web3.eth.getAccounts. If no such account exists, default account will not be set.

  `Gnosis.``standardMarketFactory`

    If StandardMarketFactory is deployed to the current network, this will be set to an StandardMarketFactory contract abstraction pointing at the deployment address.

## Methods

`calcLMSRCost`()

  Estimates the cost of buying specified number of outcome tokens from LMSR market. Unfunded markets will be handled as a special case, returning the outcomeTokenCount passed plus its corresponding fee fee.

  Arguments:

  - opts.netOutcomeTokensSold (Array.<number>|Array.<string>|Array.<BigNumber>) – Amounts of net outcome tokens that have been sold. Negative amount means more have been bought than sold.
  - opts.funding (number|string|BigNumber) – The amount of funding market has
  - opts.outcomeTokenIndex (number|string|BigNumber) – The index of the outcome
  - opts.outcomeTokenCount (number|string|BigNumber) – The number of outcome tokens to buy
  - opts.feeFactor (number|string|BigNumber) – The fee factor. Specifying 1,000,000 corresponds to 100%, 50,000 corresponds to 5%, etc.

  Returns: | Decimal – The cost of the outcome tokens in event collateral tokens

`calcLMSRMarginalPrice`()

  Estimates the marginal price of outcome token. Unfunded markets with no outcome tokens sold will be handled as a special case, returning (1 / number of outcomes sold).

  Arguments:

  - opts.netOutcomeTokensSold (Array.<Number>|Array.<string>|Array.<BigNumber>) – Amounts of net outcome tokens that have been sold. Negative amount means more have been bought than sold.
  - opts.funding (number|string|BigNumber) – The amount of funding market has
  - opts.outcomeTokenIndex (number|string|BigNumber) – The index of the outcome

  Returns: | Decimal – The marginal price of outcome tokens. Will differ from actual price, which varies with quantity being moved.

`calcLMSROutcomeTokenCount`()

  Estimates the number of outcome tokens which can be purchased by specified amount of collateral.

  Arguments:

  - opts.netOutcomeTokensSold (Array.<Number>|Array.<string>|Array.<BigNumber>) – Amounts of net outcome tokens that have been sold. Negative amount means more have been bought than sold.
  - opts.funding (number|string|BigNumber) – The amount of funding market has
  - opts.outcomeTokenIndex (number|string|BigNumber) – The index of the outcome
  - opts.cost (number|string|BigNumber) – The amount of collateral for buying tokens

  Returns: | Decimal – The number of outcome tokens that can be bought

`calcLMSRProfit`()

  Estimates profit from selling specified number of outcome tokens to LMSR market.Unfunded markets will be handled as a special case, returning no profit.

  Arguments:

  - opts.netOutcomeTokensSold (Array.<number>|Array.<string>|Array.<BigNumber>) – Amounts of net outcome tokens that have been sold by the market already. Negative amount means more have been sold to the market than sold by the market.
  - opts.funding (number|string|BigNumber) – The amount of funding market has
  - opts.outcomeTokenIndex (number|string|BigNumber) – The index of the outcome
  - opts.outcomeTokenCount (number|string|BigNumber) – The number of outcome tokens to sell
  - opts.feeFactor (number|string|BigNumber) – The fee factor. Specifying 1,000,000 corresponds to 100%, 50,000 corresponds to 5%, etc.

  Returns: | Decimal – The profit from selling outcome tokens in event collateral tokens

`create`(opts)

  Factory function for asynchronously creating an instance of the API

  Note: this method is asynchronous and will return a Promise

  Arguments:

  - opts.ethereum (string|Provider) – An instance of a Web3 provider or a URL of a Web3 HTTP provider. If not specified, Web3 provider will be either the browser-injected Web3 (Mist/MetaMask) or an HTTP provider looking at http://localhost:8545
  - opts.defaultAccount (string) – The account to use as the default from address for ethereum transactions conducted through the Web3 instance. If unspecified, will be the first account found on Web3. See Gnosis.setWeb3Provider defaultAccount parameter for more info.
  - opts.ipfs (Object) – ipfs-mini configuration object
  - opts.ipfs.host (string) – IPFS node address
  - opts.ipfs.port (Number) – IPFS protocol port
  - opts.ipfs.protocol (string) – IPFS protocol name
  - opts.logger (function) – A callback for logging. Can also provide ‘console’ to use console.log.

  Returns: | Gnosis – An instance of the pm.js API

`requireEventFromTXResult`(result, eventName)

  Looks for a single event in the logs of a transaction result. If no such events or multiple matching events are found, throws an error. Otherwise returns the matching event log.

  Arguments:

  - result (Transaction) – Result of sending a transaction
  - eventName (string) – Name of the event

  Returns: | Object – The matching event log found

`buyOutcomeTokens`()

  Buys outcome tokens. If you have ether and plan on transacting with a market on an event which uses EtherToken as collateral, be sure to convert the ether into EtherToken by sending ether to the deposit() method of the contract. For other ERC20 collateral tokens, follow the token’s acquisition process defined by the token’s contract.

  Note: this method is asynchronous and will return a Promise

  Arguments:

  - opts.market (Contract|string) – The market to buy tokens from
  - opts.outcomeTokenIndex (number|string|BigNumber) – The index of the outcome
  - opts.outcomeTokenCount (number|string|BigNumber) – Number of outcome tokens to buy
  - opts.limitMargin (number|string|BigNumber) – Because transactions change prices, there is a chance that the cost limit for the buy, which is set to the cost according to the latest mined block, will prevent the buy transaction from succeeding. This parameter can be used to increase the cost limit by a fixed proportion. For example, specifying limitMargin: 0.05 will make the cost limit increase by 5%.
  - opts.cost (number|string|BigNumber) – Overrides the cost limit supplied to the market contract which is derived from the latest block state of the market along with the outcomeTokenCount and limitMargin parameters.
  - opts.approvalAmount (number|string|BigNumber) – Amount of collateral to allow market to spend. If unsupplied or null, allowance will be reset to the approvalResetAmount only if necessary. If set to 0, the approval transaction will be skipped.
  - opts.approvalResetAmount (number|string|BigNumber) – Set to this amount when resetting market collateral allowance. If unsupplied or null, will be the cost of this transaction.
  - opts.approveTxOpts (Object) – Extra transaction options for the approval transaction if it occurs. These options override the options specified in sibling properties of the parameter object.
  - opts.buyTxOpts (Object) – Extra transaction options for the buy transaction. These options override the options specified in sibling properties of the parameter object.

  Returns: | BigNumber – How much collateral tokens caller paid

`createCategoricalEvent`()

  Creates a categorical event.

  Note: this method is asynchronous and will return a Promise

  Arguments:

  - opts.collateralToken (Contract|string) – The collateral token contract or its address
  - opts.oracle (Contract|string) – The oracle responsible for resolving this event
  - opts.outcomeCount (number|string|BigNumber) – The number of outcomes of this event

  Returns: | Contract – The created categorical event

`createCentralizedOracle`()

  Creates a centralized oracle linked to a published event.

  Note: this method is asynchronous and will return a Promise

  Arguments:

  - ipfsHash (string) – The published event’s IPFS hash

  Returns: | Contract – The created centralized oracle contract instance

`createMarket`()

  Creates a market.

  Note: this method is asynchronous and will return a Promise

  Arguments:

  - opts.event (Contract|string) – The forwarded oracle contract or its address
  - opts.marketMaker (Contract|string) – The collateral token contract or its address
  - opts.fee (number|string|BigNumber) – The fee factor. Specifying 1,000,000 corresponds to 100%, 50,000 corresponds to 5%, etc.
  - opts.marketFactory (Contract|string) – The factory contract

  Returns: | Contract – The created market contract instance. If marketFactory is StandardMarketFactory, this should be a StandardMarket

`createScalarEvent`()

  Creates a scalar event.

  Note: this method is asynchronous and will return a Promise

  Arguments:

  - opts.collateralToken (Contract|string) – The collateral token contract or its address
  - opts.oracle (Contract|string) – The oracle responsible for resolving this event
  - opts.lowerBound (number|string|BigNumber) – The lower bound for the event outcome
  - opts.upperBound (number|string|BigNumber) – The upper bound for the event outcome

  Returns: | Contract – The created scalar event

`createUltimateOracle`()

  Creates an ultimate oracle.

  Note: this method is asynchronous and will return a Promise

  Arguments:

  - opts.forwardedOracle (Contract|string) – The forwarded oracle contract or its address
  - opts.collateralToken (Contract|string) – The collateral token contract or its address
  - opts.spreadMultiplier (number|string|BigNumber) – The spread multiplier
  - opts.challengePeriod (number|string|BigNumber) – The challenge period in seconds
  - opts.challengeAmount (number|string|BigNumber) – The amount of collateral tokens put at stake in the challenge
  - opts.frontRunnerPeriod (number|string|BigNumber) – The front runner period in seconds

  Returns: | Contract – The created ultimate oracle contract instance

`loadEventDescription`(ipfsHash)

  Loads an event description from IPFS.

  Note: this method is asynchronous and will return a Promise

  Arguments:

  - ipfsHash (string) – The IPFS hash locating the published event

  Returns: | Object – A POD object describing the event

`publishEventDescription`(description)

  Publishes an event description onto IPFS.

  Note: this method is asynchronous and will return a Promise

  Arguments:

  - eventDescription (Object) – A POD object describing the event
  - eventDescription.title (string) – A string describing the title of the event
  - eventDescription.description (string) – A string describing the purpose of the event
  - eventDescription.resolutionDate (string) – A string containing the resolution date of the event
  - eventDescription.outcomes (Array.<string>) – A string array containing the outcomes of the event

  Returns: | string – The IPFS hash locating the published event

`resolveEvent`()

  Resolves an event. Assumes event is backed solely by a centralized oracle controlled by you

  Note: this method is asynchronous and will return a Promise

  Arguments:

  - opts.event (Contract|string) – The event address or instance
  - opts.outcome (number|string|BigNumber) – The outcome to set this event to. This is the zero-based index of the outcome for categorical events and the decimals-adjusted value of the outcome for scalar events.

`sellOutcomeTokens`()

  Sells outcome tokens. If transacting with a market which deals with EtherToken as collateral, will need additional step of sending a withdraw(uint amount) transaction to the EtherToken contract if raw ether is desired.

  Note: this method is asynchronous and will return a Promise

  Arguments:

  - opts.market (Contract|string) – The market to sell tokens to
  - opts.outcomeTokenIndex (number|string|BigNumber) – The index of the outcome
  - opts.outcomeTokenCount (number|string|BigNumber) – Number of outcome tokens to sell
  - opts.limitMargin (number|string|BigNumber) – Because transactions change profits, there is a chance that the profit limit for the sell, which is set to the profit according to the latest mined block, will prevent the sell transaction from succeeding. This parameter can be used to decrease the profit limit by a fixed proportion. For example, specifying limitMargin: 0.05 will make the profit limit decrease by 5%.
  - opts.minProfit (number|string|BigNumber) – Overrides the minimum profit limit supplied to the market contract which is derived from the latest block state of the market along with the outcomeTokenCount and limitMargin parameters.
  - opts.approvalAmount (number|string|BigNumber) – Amount of outcome tokens to allow market to handle. If unsupplied or null, allowance will be reset to the approvalResetAmount only if necessary. If set to 0, the approval transaction will be skipped.
  - opts.approvalResetAmount (number|string|BigNumber) – Set to this amount when resetting market outcome token allowance. If unsupplied or null, will be the sale amount specified by outcomeTokenCount.
  - opts.approveTxOpts (Object) – Extra transaction options for the approval transaction if it occurs. These options override the options specified in sibling properties of the parameter object.
  - opts.sellTxOpts (Object) – Extra transaction options for the sell transaction. These options override the options specified in sibling properties of the parameter object.

  Returns: | BigNumber – How much collateral tokens caller received from sale

`setWeb3Provider`(provider, defaultAccount)

  Setter for the ethereum web3 provider.

  Note: this method is asynchronous and will return a Promise

  Arguments:

  - provider (string|Provider) – An instance of a Web3 provider or a URL of a Web3 HTTP provider. If not specified, Web3 provider will be either the browser-injected Web3 (Mist/MetaMask) or an HTTP provider looking at http://localhost:8545
  - defaultAccount (string) – An address to be used as the default from account for conducting transactions using the associated Web3 instance. If not specified, will be inferred from Web3 using the first account obtained by web3.eth.getAccounts. If no such account exists, default account will not be set.