Core

It is the main contract of the Opium Protocol. It exposes most of the user-facing functions that a user or a contract need to use in order to interact with the Opium Protocol, such as the creation of new financial products or their executions.

The Core contract is responsible for processing the data encoded in a derivative recipe and for fetching the data from a specified oracle recipe for the purpose of calculating payouts, validating a financial product’s specs.

Contract functions description

create(Derivative memory _derivative, uint256 _quantity, address[2] memory _addresses) public

If the derivative recipe is valid and the msg.sender calling core.create is providing a collateral allowance that matches the margin requirements specified in the derivative recipe, it transfers the collateral from the user via the TokenSpender contract and subsequently it mints a LONG and a SHORT ERC721O tokens for the given derivative recipe via the TokenMinter and transfers them respectively to the specified buyer and seller. As an argument it accepts LibDerivative.derivative, uint256 quantity as the number of positions that the TokenMinter shall mint and a tuple of addresses - respectively the buyer and the seller- that shall be the recipients of the minted positions.

execute(uint256 _tokenId, uint256 _quantity, Derivative memory _derivative)

msg.sender executes a single derivative position type with a specified quantity. The position type being executed is represented by its unique ERC721O tokenId. Internally the function performs the required validation - such as checking whether the derivative associated to the tokenId is expired, the OracleAggregator has already provided the necessary data to settle the derivative and msg.sender is allowed to execute the given position. If all the validations are passed successfully, then it checks whether the provided tokenId belongs to a LONG or SHORT position and then proceeds to computing the payout logic according to the specifications encoded in the derivative recipe - specifically the getExecutionPayout specified in IDerivativeLogic- and the outcome cached in the OracleAggregator from the given derivative’s oracle recipe. After calculating the buyer’s and seller’s payouts, it finally forwards the payout to the winning party and, if specified, it calculates the commission of the derivative’s author. As an argument it accepts the uint256 _tokenId unique tokenId of the position to be executed, uint256 _quantity the number of positions to be executed, and LibDerivative.Derivative the derivative recipe associated with the given tokenId.

execute(uint256[] _tokenId, uint256[] _quantity, Derivative[] memory _derivative)

msg.sender executes a batch of derivatives’ positions with a specified quantity. The high-level logic introduced for execute(uint256 _tokenId, uint256 _quantity, Derivative memory _derivative) is applied to each provided position by looping through their array.

execute(address _tokenOwner, uint256 _tokenId, uint256 _quantity, Derivative memory _derivative)

msg.sender executes a single derivative’s position type on behalf of _tokenOwner. An additional check is required in cases where a third-party requests the execution of a derivative’s position type owned by another account. Internally it checks whether the derivative recipe contract implementing the IDerivativeLogic interface allows the execution from third-parties by calling the IDerivativeLogic function thirdPartyExecutionAllowed, which returns a boolean. If true, the remaining high-level logic is identical to execute(uint256 _tokenId, uint256 _quantity, Derivative memory _derivative)

execute(address _tokenOwner, uint256[] memory _tokenId, uint256[] memory _quantity, Derivative[] memory _derivative)

msg.sender executes a batch of derivatives’ positions on behalf of _tokenOwner. The logic being performed on each position is identical to execute(address _tokenOwner, uint256 _tokenId, uint256 _quantity, Derivative memory _derivative)but applied on each element of the supplied arrays.

cancel(uint256 _tokenId, uint256 _quantity, Derivative memory _derivative)

It allows the cancellation of the execution of a derivative if no data was provided to perform its settlement after 2 weeks from its maturity. If the execution is canceled, then all the allocated margins are returned to the respective position's owners. More importantly, once a position is canceled, it won’t be possible to execute it even if the oracle data will finally arrive at a later time.

cancel(uint256[] memory _tokenId, uint256[] memory _quantity, Derivative[] memory _derivative)

It allows the cancellation of a batch of derivatives if no data was provided to perform their settlement after 2 weeks for each of their maturity. The logic is identical to cancel(uint256 _tokenId, uint256 _quantity, Derivative memory _derivative) but it is applied to each of the derivatives’ positions array in a loop.

withdrawFee(address _tokenAddress) public

Allows the author of a derivative to withdraw the fees that were specified in the related derivative recipe as a commission for the author of said financial product. As an address it accepts the ERC20 address of the token with which the derivative author will be compensated - generally it is the ERC20 token used as a margin for the derivative itself.