API Reference

Classes

class Gnosis(opts)

Represents the gnosis.js 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:

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 (https://github.com/gnosis/gnosis-contracts#readme). 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 gnosis.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 (https://etherscan.io/address/0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2#code).

Otherwise, if EtherToken (https://gnosis.github.io/gnosis-contracts/docs/EtherToken/) is deployed to the current network, this will be set to an EtherToken contract abstraction pointing at the deployment address.

Gnosis.lmsrMarketMaker

If LMSRMarketMaker (https://gnosis.github.io/gnosis-contracts/docs/LMSRMarketMaker/) is deployed to the current network, this will be set to an LMSRMarketMaker contract abstraction pointing at the deployment address.

Gnosis.olympiaAddressRegistry

If AddressRegistry (https://github.com/gnosis/olympia-token) is deployed to the current network (this should only work for Rinkeby), this will be set to an AddressRegistry contract abstraction pointing at the deployment address. This is intended for use with Olympia.

Gnosis.olympiaToken

If OlympiaToken (https://github.com/gnosis/olympia-token) is deployed to the current network (this should only work for Rinkeby), this will be set to an OlympiaToken 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 (https://gnosis.github.io/gnosis-contracts/docs/StandardMarketFactory/) is deployed to the current network, this will be set to an StandardMarketFactory contract abstraction pointing at the deployment address.

Methods

calcLMSRCost(opts)

Estimates the cost of buying specified number of outcome tokens from LMSR market.

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(opts)

Estimates the marginal price of outcome token.

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(opts)

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(opts)

Estimates profit from selling specified number of outcome tokens to LMSR market.

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 gnosis.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(opts)

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(opts)

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(ipfsHash)

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(opts)

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 (https://gnosis.github.io/gnosis-contracts/docs/StandardMarketFactory/), this should be a StandardMarket (https://gnosis.github.io/gnosis-contracts/docs/StandardMarket/)
createScalarEvent(opts)

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(opts)

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(eventDescription)

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(opts)

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(opts)

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.