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

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

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

Visibility

public

State Mutability

``

Requires

• setCreatorCapitalRequirement

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) view 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) view returns (address[])

Visibility

external

State Mutability

view

numActiveMarkets

_Source

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

Details

Signature

numActiveMarkets() view returns (uint256)

Visibility

external

State Mutability

view

numMaturedMarkets

_Source

Returns the number of currently-tracked matured markets.

Details

Signature

numMaturedMarkets() view returns (uint256)

Visibility

external

State Mutability

view

resolverAddressesRequired

_Source

Details

Signature

resolverAddressesRequired() view returns (bytes32[] addresses)

Visibility

public

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

``

Modifiers

• onlyKnownMarkets

• notPaused

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

``

Modifiers

• onlyActiveMarkets

• notPaused

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

``

Modifiers

• onlyOwner

Emits

• MarketsMigrated

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

``

Modifiers

• onlyOwner

Emits

• CreatorCapitalRequirementUpdated

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

``

Requires

• require(..., "Total fee must be less than 100%.")

• require(..., "Total fee must be nonzero.")

Modifiers

• onlyOwner

Emits

• CreatorFeeUpdated

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

``

Requires

• require(..., "Creator skew limit must be no greater than 1.")

Modifiers

• onlyOwner

Emits

• CreatorSkewLimitUpdated

setExpiryDuration

_Source

Allows the contract owner to update durations.expiryDuration.

Details

Signature

setExpiryDuration(uint256 _expiryDuration)

Visibility

public

State Mutability

``

Modifiers

• onlyOwner

Emits

• ExpiryDurationUpdated

setMarketCreationEnabled

_Source

Allows the owner to toggle whether market creation is enabled.

Details

Signature

setMarketCreationEnabled(bool enabled)

Visibility

public

State Mutability

``

Modifiers

• onlyOwner

setMaxOraclePriceAge

_Source

Allows the contract owner to update durations.maxOraclePriceAge.

Details

Signature

setMaxOraclePriceAge(uint256 _maxOraclePriceAge)

Visibility

public

State Mutability

``

Modifiers

• onlyOwner

Emits

• MaxOraclePriceAgeUpdated

setMaxTimeToMaturity

_Source

Allows the contract owner to update durations.maxTimeToMaturity.

Details

Signature

setMaxTimeToMaturity(uint256 _maxTimeToMaturity)

Visibility

public

State Mutability

``

Modifiers

• onlyOwner

Emits

• MaxTimeToMaturityUpdated

setMigratingManager

_Source

Allows the owner to set the value of _migratingManager.

Details

Signature

setMigratingManager(contract BinaryOptionMarketManager manager)

Visibility

public

State Mutability

``

Modifiers

• onlyOwner

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

``

Requires

• require(..., "Total fee must be less than 100%.")

• require(..., "Total fee must be nonzero.")

Modifiers

• onlyOwner

Emits

• PoolFeeUpdated

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

``

Requires

• require(..., "Refund fee must be no greater than 100%.")

Modifiers

• onlyOwner

Emits

• RefundFeeUpdated

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() view returns (contract IExchangeRates)

Visibility

internal

State Mutability

view

_factory

_Source

Retrieves the cached address of the BinaryOptionMarketFactory instance.

Details

Signature

_factory() view 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) view 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) view returns (bool)

Visibility

internal

State Mutability

view

_sUSD

_Source

The cached sUSD instance.

Details

Signature

_sUSD() view 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() view returns (contract ISystemStatus)

Visibility

internal

State Mutability

view

External Functions

cancelMarket

_Source

Details

Signature

cancelMarket(address market)

Visibility

external

State Mutability

``

Requires

• require(..., "Not an active market")

• require(..., "Sender not market creator")

Modifiers

• notPaused

Emits

• MarketCancelled

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:

• The manager is paused
• The system is suspended
• Market creation has been disabled
• The provided oracle key is invalid.
• The given maturity date is further than durations.maxTimeToMaturity in the future
• The provided maturity date is not after the provided bidding end date.
• The sum of longBid and shortBid is less than capitalRequirement.
• The bids skey more than than the skew limit.
• The creator has not approved the manager to transfer at least longBid + shortBid sUSD on their behalf.

Details

Signature

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

Visibility

external

State Mutability

``

Requires

• require(..., "Market creation is disabled")

• require(..., "Invalid key")

• require(..., "Maturity too far in the future")

• require(..., "End of bidding has passed")

• require(..., "Maturity predates end of bidding")

Modifiers

• notPaused

Emits

• MarketCreated

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

``

Modifiers

• notPaused

rebuildMarketCaches

_Source

Details

Signature

rebuildMarketCaches(contract BinaryOptionMarket[] marketsToSync)

Visibility

external

State Mutability

``

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

``

Requires

• require(..., "Only permitted for migrating manager.")

Emits

• MarketsReceived

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

``

Requires

• require(..., "Not an active market")

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)

MarketCancelled

_Source

Signature: MarketCancelled(address market)

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)