Skip to content

BinaryOptionMarketManager

Description

The BinaryOptionMarketManager contract is responsible for creating and destroying BinaryOptionMarket instances, as well as keeping track of the set of currently-active markets and the total value of deposits across those markets.

In addition, various static market parameters such as the current fee levels, are maintained in the manager, and these are inherited by new markets when they are created.

The manager owner can disable the creation of new markets, or pause all binary option markets altogether. The manager and its markets will also stop operating if the system is suspended. These facilities are provided to allow upgrades to occur smoothly, for which purpose the manager contract also provides functions to migrate its markets to a new manager instance.

This contract operates in a complex with BinaryOptionMarketFactory, which is responsible for actually instantiating new BinaryOptionMarket instances. Since the factory must contain the entire bytecode of the market contract, we must separate the factory from the manager, as the combined contract would otherwise exceed the maximum contract size specified in EIP 170.

Related Contracts
  • BinaryOptionMarketFactory: The factory is responsible for actually instantiating new BinaryOptionMarket instances at the direction of the manager.
  • BinaryOptionMarket: The manager directs the factory to construct new BinaryOptionMarket instances, and keeps track of them in the _markets array.
  • Synth (sUSD): As all bids and settlements are made in sUSD, the manager must know the sUSD address in order to accept initial bids.
  • SystemStatus: The manager pauses if the system is suspended on the SystemStatus contract.
  • AddressResolver: The addresses of SystemStatus and sUSD are retrieved from here.

Source: contracts/BinaryOptionMarketManager.sol

Architecture

Libraries

Inheritance Graph

graph TD BinaryOptionMarketManager[BinaryOptionMarketManager] --> Pausable[Pausable] BinaryOptionMarketManager[BinaryOptionMarketManager] --> SelfDestructible[SelfDestructible] BinaryOptionMarketManager[BinaryOptionMarketManager] --> MixinResolver[MixinResolver] Pausable[Pausable] --> Owned[Owned] SelfDestructible[SelfDestructible] --> Owned[Owned] MixinResolver[MixinResolver] --> Owned[Owned]

Structs

CreatorLimits

Source

These are the parameters governing the limits that binary option market creators must abide by.

Field Type Description
capitalRequirement uint256 Markets require the creator to maintain at least this value of sUSD in bids.
skewLimit uint256 The market requires a percentage of the creator's bids to be retained on each size, governed by this variable.

Durations

Source

This struct holds the current values of time periods governing the duration of various BinaryOptionMarket phases. All durations are in seconds.

Note that unlike other parameters, varying maxOraclePriceAge will affect already-instantiated markets.

Field Type Description
maxOraclePriceAge uint256 A market can still be resolved if the last oracle price was updated less than maxOraclePriceAge seconds before the maturity date.
expiryDuration uint256 The duration that options can be exercised for after maturity.
maxTimeToMaturity uint256 Markets cannot be created with a maturity date further in the future than this.

Fees

Source

The global fee rates, which are inherited by new markets. Note that the sum poolFee + creatorFee must be between 0 and 1 exclusive, while refundFee must be no greater than 1.

Field Type Description
poolFee uint256 The portion of the sUSD deposited in the market at resolution that is collected by the fee pool. This is an 18-decimal fixed point number.
creatorFee uint256 The portion collected by the market's creator as a fee. This is an 18-decimal fixed point number.
refundFee uint256 When a bid is refunded, this portion of its value is retained in the market to be paid out at maturity. This fee is intended to compensate the market for the toxic price signal that the bidder has sent, by increasing the payoff of the remaining bidders, and to discourage excessive price volatility at the end of bidding. This is an 18-decimal fixed point number.

Variables

creatorLimits

Source

This holds the current values for market creator limits.

Type: struct BinaryOptionMarketManager.CreatorLimits

durations

Source

This holds the current values that new markets will inherit for several time-related parameters.

Type: struct BinaryOptionMarketManager.Durations

fees

Source

This holds the current values that new markets will inherit for their fee rates. Once created, a market's fee rates are constant, so that if they are altered on the manager contract they do not change in existing markets.

Type: struct BinaryOptionMarketManager.Fees

marketCreationEnabled

Source

New markets cannot be created if this is false.

Type: bool

totalDeposited

Source

This tracks the total of sUSD deposited across all binary option markets. This is updated whenever bids are made or refunded, options exercised, or a markets created or destroyed.

Type: uint256

Constructor

constructor

Source

The constructor initialises the inherited contracts and sets the initial values for fees, durations and other settings. These parameters follow the constraints of the setter functions so that the various parameters can't be set out of range.

Details

Signature

(address _owner, address _resolver, uint256 _maxOraclePriceAge, uint256 _expiryDuration, uint256 _maxTimeToMaturity, uint256 _creatorCapitalRequirement, uint256 _creatorSkewLimit, uint256 _poolFee, uint256 _creatorFee, uint256 _refundFee)

Visibility

public

State Mutability

nonpayable

Requires

Views

activeMarkets

Source

Returns markets that are not yet mature.

This function returns a slice of the internal active markets array, consisting of pageSize elements starting at index. If the page would extend past the end of the array, the slice will be shorter than pageSize elements long. The entire array can be retrieved with markets(0, numMarkets()), or any larger page size.

Details

Signature

activeMarkets(uint256 index, uint256 pageSize) returns (address[])

Visibility

external

State Mutability

view

maturedMarkets

Source

Returns markets that are mature.

This function behaves the same way as activeMarkets does.

Details

Signature

maturedMarkets(uint256 index, uint256 pageSize) returns (address[])

Visibility

external

State Mutability

view

numActiveMarkets

Source

Returns the number of currently-tracked non-matured markets.

Details

Signature

numActiveMarkets() returns (uint256)

Visibility

external

State Mutability

view

numMaturedMarkets

Source

Returns the number of currently-tracked matured markets.

Details

Signature

numMaturedMarkets() returns (uint256)

Visibility

external

State Mutability

view

Restricted Functions

decrementTotalDeposited

Source

Allows markets to decrease the tracked total deposit value.

The transaction reverts if the sender is not a known market, or if the manager is paused, or if the system is suspended.

Details

Signature

decrementTotalDeposited(uint256 delta)

Visibility

external

State Mutability

nonpayable

Modifiers

incrementTotalDeposited

Source

Allows markets to increase the tracked total deposit value.

The transaction reverts if the sender is not a known market, or if the manager is paused, or if the system is suspended.

Details

Signature

incrementTotalDeposited(uint256 delta)

Visibility

external

State Mutability

nonpayable

Modifiers

migrateMarkets

Source

Allows the contract owner to migrate a set of markets to a new manager instance, for example in case of upgrades. This requires first setting the migrating manager in the receiving manager, so that the receiveMarkets can be called from this function call. This will also migrate the total value of deposits in the migrated markets between the factories.

The most efficient way of invoking this market is to provide the markets in the reverse order that they are listed in _markets, so that they can be popped off the end without rewriting any other parts of the array.

The transaction will revert if any of the markets provided is not known, or is a duplicate.

Details

Signature

migrateMarkets(contract BinaryOptionMarketManager receivingManager, bool active, contract BinaryOptionMarket[] marketsToMigrate)

Visibility

external

State Mutability

nonpayable

Modifiers

Emits

setCreatorCapitalRequirement

Source

Allows the contract owner to set the minimum sUSD value required to open a market.

Details

Signature

setCreatorCapitalRequirement(uint256 _creatorCapitalRequirement)

Visibility

public

State Mutability

nonpayable

Modifiers

Emits

setCreatorFee

Source

Allows the contract owner to update fees.creatorFee.

The transaction reverts if the sum of fees.poolFee and fees.creatorFee is not between 0 and 100%.

Details

Signature

setCreatorFee(uint256 _creatorFee)

Visibility

public

State Mutability

nonpayable

Requires

Modifiers

Emits

setCreatorSkewLimit

Source

Allows the contract owner to set the skew limit creators must abide by to open a market.

Details

Signature

setCreatorSkewLimit(uint256 _creatorSkewLimit)

Visibility

public

State Mutability

nonpayable

Requires

Modifiers

Emits

setExpiryDuration

Source

Allows the contract owner to update durations.expiryDuration.

Details

Signature

setExpiryDuration(uint256 _expiryDuration)

Visibility

public

State Mutability

nonpayable

Modifiers

Emits

setMarketCreationEnabled

Source

Allows the owner to toggle whether market creation is enabled.

Details

Signature

setMarketCreationEnabled(bool enabled)

Visibility

public

State Mutability

nonpayable

Modifiers

setMaxOraclePriceAge

Source

Allows the contract owner to update durations.maxOraclePriceAge.

Details

Signature

setMaxOraclePriceAge(uint256 _maxOraclePriceAge)

Visibility

public

State Mutability

nonpayable

Modifiers

Emits

setMaxTimeToMaturity

Source

Allows the contract owner to update durations.maxTimeToMaturity.

Details

Signature

setMaxTimeToMaturity(uint256 _maxTimeToMaturity)

Visibility

public

State Mutability

nonpayable

Modifiers

Emits

setMigratingManager

Source

Allows the owner to set the value of _migratingManager.

Details

Signature

setMigratingManager(contract BinaryOptionMarketManager manager)

Visibility

public

State Mutability

nonpayable

Modifiers

setPoolFee

Source

Allows the contract owner to update fees.poolFee.

The transaction reverts if the sum of fees.poolFee and fees.creatorFee is not between 0 and 1.

Details

Signature

setPoolFee(uint256 _poolFee)

Visibility

public

State Mutability

nonpayable

Requires

Modifiers

Emits

setRefundFee

Source

Allows the contract owner to update fees.refundFee.

The transaction reverts if the refund fee is greater than 100%.

Details

Signature

setRefundFee(uint256 _refundFee)

Visibility

public

State Mutability

nonpayable

Requires

Modifiers

Emits

setResolverAndSyncCacheOnMarkets

Source

Calls setResolverAndSyncCache on a given array of markets, updating their address caches.

Details

Signature

setResolverAndSyncCacheOnMarkets(contract AddressResolver _resolver, contract BinaryOptionMarket[] marketsToSync)

Visibility

external

State Mutability

nonpayable

Modifiers

Internal Functions

_exchangeRates

Source

Retrieves the cached address of the ExchangeRates instance, which is used to determine whether currency keys are valid to create new markets.

Details

Signature

_exchangeRates() returns (contract IExchangeRates)

Visibility

internal

State Mutability

view

_factory

Source

Retrieves the cached address of the BinaryOptionMarketFactory instance.

Details

Signature

_factory() returns (contract BinaryOptionMarketFactory)

Visibility

internal

State Mutability

view

_isKnownMarket

Source

Returns true if the provided address exists in either of the active or matured markets lists, and false otherwise.

Details

Signature

_isKnownMarket(address candidate) returns (bool)

Visibility

internal

State Mutability

view

_isValidKey

Source

A key can be used for a binary option market if it is not sUSD (as the price of sUSD is fixed at $1), and not an inverse synth (since they are equivalent to using the non-inverse and reversing long and short).

Details

Signature

_isValidKey(bytes32 oracleKey) returns (bool)

Visibility

internal

State Mutability

view

_sUSD

Source

The cached sUSD instance.

Details

Signature

_sUSD() returns (contract IERC20)

Visibility

internal

State Mutability

view

_systemStatus

Source

The cached SystemStatus instance. The manager contract does not function when the system is suspended.

Details

Signature

_systemStatus() returns (contract ISystemStatus)

Visibility

internal

State Mutability

view

External Functions

createMarket

Source

Calls out to BinaryOptionMarketFactory.createMarket to create a new BinaryOptionMarket instance and adds its address to the _markets array.

The creator (the message sender) must provide the following parameters:

Field Type Description
oracleKey bytes32 The key of the underlying asset of this market in the ExchangeRates contract.
strikePrice uint (18 decimals) The strike price of the underlying asset at maturity, in the same units as reported by the ExchangeRates contract.
times uint[2] calldata The unix timestamps (seconds) of the bidding end date and the maturity date of the new market, in that order.
bids uint[2] calldata (18 decimals) The initial sUSD bids by the market creator on the long and short sides of the market, in that order.

Upon creation, the manager transfers bids[0] + bids[1] sUSD from the creator to the new market using an ERC20 transferFrom call, so the creator must have given sufficient transfer approval to the manager. The initial bids will be reflected in the total deposited quantity, and the market creator will be credited bids[0] worth of bids on the long option, and bids[1] worth on the short option. These bids, like any other user's, can be claimed and exercised as options, but they cannot be refunded if such a refund would decrease the creator's bid total to less than the minimum liquidity requirement.

The expiry date of the new market will be set to the provided maturity date (times[1]) plus durations.expiryDuration, while the fee rates will be set from the current values in the manager. The resolver address of the new market is inherited from the address known to the BinaryOptionMarketFactory which performs the actual instantiation. The BinaryOptionMarket contract has no setters, so once constructed, these values are fixed for the lifetime of the market. The resolver cache of the new market is synchronised immediately after construction by the manager.

The transaction reverts if any of the following conditions is true:

Details

Signature

createMarket(bytes32 oracleKey, uint256 strikePrice, uint256[2] times, uint256[2] bids) returns (contract IBinaryOptionMarket)

Visibility

external

State Mutability

nonpayable

Requires

Modifiers

Emits

expireMarkets

Source

Allows markets to be destroyed once they have reached their expiry dates. The transaction will revert if any single market in the provided list is not ready to expire.

Details

Signature

expireMarkets(address[] markets)

Visibility

external

State Mutability

nonpayable

Modifiers

receiveMarkets

Source

This is called by a migrating manager once it has prepared its markets to be received to finalise the migration. The value of deposits in the migrated markets will be added to the receiving manager's total.

The function reverts if the message sender is not the migrating manager, which must previously have been set, or if any provided market is already known to the manager, or is a duplicate.

Details

Signature

receiveMarkets(bool active, contract BinaryOptionMarket[] marketsToReceive)

Visibility

external

State Mutability

nonpayable

Requires

Emits

resolveMarket

Source

Allows a particular market to be resolved. When this occurs, the market will be moved from the active markets list to the matured markets list.

Details

Signature

resolveMarket(address market)

Visibility

external

State Mutability

nonpayable

Requires

Modifiers

onlyActiveMarkets

Source

The transaction reverts if the message sender is not an active market.

onlyKnownMarkets

Source

The transaction reverts if the message sender is not a known market.

Events

CreatorCapitalRequirementUpdated

Source

The capital requirement was updated.

Signature: CreatorCapitalRequirementUpdated(uint256 value)

CreatorFeeUpdated

Source

The creator fee was updated.

Signature: CreatorFeeUpdated(uint256 fee)

CreatorSkewLimitUpdated

Source

The skew limit was updated.

Signature: CreatorSkewLimitUpdated(uint256 value)

ExerciseDurationUpdated

Source

Signature: ExerciseDurationUpdated(uint256 duration)

ExpiryDurationUpdated

Source

The expiry duration was updated.

Signature: ExpiryDurationUpdated(uint256 duration)

MarketCreated

Source

A new market was created.

Signature: MarketCreated(address market, address creator, bytes32 oracleKey, uint256 strikePrice, uint256 biddingEndDate, uint256 maturityDate, uint256 expiryDate)

MarketCreationEnabledUpdated

Source

Market creation was enabled or disabled.

Signature: MarketCreationEnabledUpdated(bool enabled)

MarketExpired

Source

An expiring market was destroyed.

Signature: MarketExpired(address market)

MarketsMigrated

Source

A set of markets was migrated to a certain receiving manager.

Signature: MarketsMigrated(contract BinaryOptionMarketManager receivingManager, contract BinaryOptionMarket[] markets)

MarketsReceived

Source

A set of markets was migrated from a certain migrating manager.

Signature: MarketsReceived(contract BinaryOptionMarketManager migratingManager, contract BinaryOptionMarket[] markets)

MaxOraclePriceAgeUpdated

Source

The max oracle price age was updated.

Signature: MaxOraclePriceAgeUpdated(uint256 duration)

MaxTimeToMaturityUpdated

Source

The maximum time to maturity was updated.

Signature: MaxTimeToMaturityUpdated(uint256 duration)

PoolFeeUpdated

Source

The pool fee was updated.

Signature: PoolFeeUpdated(uint256 fee)

RefundFeeUpdated

Source

The refund fee was updated.

Signature: RefundFeeUpdated(uint256 fee)