Skip to main content

LongShortPair

LongShortPair#

Uses a combination of long and short tokens to tokenize the bounded price exposure to a given identifier.

Functions#

constructor(struct LongShortPair.ConstructorParams params) (public)

Construct the LongShortPair

Parameters:#

  • params: Constructor params used to initialize the LSP. Key-valued object with the following structure:
    • pairName: Name of the long short pair contract.
    • expirationTimestamp: Unix timestamp of when the contract will expire.
    • collateralPerPair: How many units of collateral are required to mint one pair of synthetic tokens.
    • priceIdentifier: Price identifier, registered in the DVM for the long short pair.
    • longToken: Token used as long in the LSP. Mint and burn rights needed by this contract.
    • shortToken: Token used as short in the LSP. Mint and burn rights needed by this contract.
    • collateralToken: Collateral token used to back LSP synthetics.
    • financialProductLibrary: Contract providing settlement payout logic.
    • customAncillaryData: Custom ancillary data to be passed along with the price request to the OO.
    • proposerReward: Preloaded reward to incentivize settlement price proposals.
    • optimisticOracleLivenessTime: OO liveness time for price requests.
    • optimisticOracleProposerBond: OO proposer bond for price requests.
    • finder: DVM finder to find other UMA ecosystem contracts.
    • timerAddress: Timer used to synchronize contract time in testing. Set to 0x000... in production.
create(uint256 tokensToCreate) → uint256 collateralUsed (public)

Creates a pair of long and short tokens equal in number to tokensToCreate. Pulls the required collateral amount into this contract, defined by the collateralPerPair value.

The caller must approve this contract to transfer tokensToCreate * collateralPerPair amount of collateral.

Parameters:#

  • tokensToCreate: number of long and short synthetic tokens to create.
redeem(uint256 tokensToRedeem) → uint256 collateralReturned (public)

Redeems a pair of long and short tokens equal in number to tokensToRedeem. Returns the commensurate amount of collateral to the caller for the pair of tokens, defined by the collateralPerPair value.

This contract must have the Burner role for the longToken and shortToken in order to call burnFrom. The caller does not need to approve this contract to transfer any amount of tokensToRedeem since long and short tokens are burned, rather than transferred, from the caller. This method can be called either pre or post expiration.

Parameters:#

  • tokensToRedeem: number of long and short synthetic tokens to redeem.
settle(uint256 longTokensToRedeem, uint256 shortTokensToRedeem) → uint256 collateralReturned (public)

Settle long and/or short tokens in for collateral at a rate informed by the contract settlement.

Uses financialProductLibrary to compute the redemption rate between long and short tokens. This contract must have the Burner role for the longToken and shortToken in order to call burnFrom. The caller does not need to approve this contract to transfer any amount of tokensToRedeem since long and short tokens are burned, rather than transferred, from the caller. This function can be called before or after expiration to facilitate early expiration. If a price has not yet been resolved for either normal or early expiration yet then it will revert.

Parameters:#

  • longTokensToRedeem: number of long tokens to settle.
  • shortTokensToRedeem: number of short tokens to settle.
requestEarlyExpiration(uint64 _earlyExpirationTimestamp) (public)

Enables the LSP to request early expiration. This initiates a price request to the optimistic oracle at the provided timestamp with a modified version of the ancillary data that includes the key "earlyExpiration:1" which signals to the OO that this is an early expiration request, rather than standard settlement.

The caller must approve this contract to transfer proposerReward amount of collateral. Will revert if: a) the contract is already early expired, b) it is after the expiration timestamp, c) early expiration is disabled for this contract, d) the proposed expiration timestamp is in the future. e) an early expiration attempt has already been made (in pending state).

Parameters:#

  • _earlyExpirationTimestamp: timestamp at which the early expiration is proposed.
expire() (public)

Expire the LSP contract. Makes a request to the optimistic oracle to inform the settlement price.

The caller must approve this contract to transfer proposerReward amount of collateral. Will revert if: a) the contract is already early expired, b) it is before the expiration timestamp or c) an expire call has already been made.

getPositionTokens(address sponsor) → uint256 longTokens, uint256 shortTokens (public)

Returns the number of long and short tokens a sponsor wallet holds.

Parameters:#

  • sponsor: address of the sponsor to query.
getEarlyExpirationAncillaryData() → bytes (public)

Generates a modified ancillary data that indicates the contract is being expired early.

ignoreEarlyExpirationPrice() → int256 (public)

Defines a special number that, if returned during an attempted early expiration, will cause the contract to do nothing and not expire. This enables the OO (and DVM voters in the case of a dispute) to choose to keep the contract running, thereby denying the early settlement request.

isContractEarlyExpired() → bool (public)

If the earlyExpirationTimestamp is != 0 then a previous early expiration OO request might still be in the pending state. Check if the OO contains the ignore early price. If it does not contain this then the contract was early expired correctly. Note that _getOraclePrice call will revert if the price request is still pending, thereby reverting all upstream calls pre-settlement of the early expiration price request.

_getOraclePrice(uint64 requestTimestamp, bytes requestAncillaryData) → int256 (internal)
_requestOraclePrice(uint64 requestTimestamp, bytes requestAncillaryData) (internal)
getExpirationPrice() (internal)
_getIdentifierWhitelist() → contract IdentifierWhitelistInterface (internal)
_getCollateralWhitelist() → contract AddressWhitelistInterface (internal)
_getOptimisticOracle() → contract OptimisticOracleInterface (internal)
_preEntranceCheck() (internal)
_preEntranceSet() (internal)
_postEntranceReset() (internal)
_startReentrantGuardDisabled() (internal)
_endReentrantGuardDisabled() (internal)
setCurrentTime(uint256 time) (external)

Sets the current time.

Will revert if not running in test mode.

Parameters:#

  • time: timestamp to set current Testable time to.
getCurrentTime() → uint256 (public)

Gets the current time. Will return the last time set in setCurrentTime if running in test mode. Otherwise, it will return the block timestamp.

Events#

TokensCreated(address sponsor, uint256 collateralUsed, uint256 tokensMinted)
TokensRedeemed(address sponsor, uint256 collateralReturned, uint256 tokensRedeemed)
ContractExpired(address caller)
EarlyExpirationRequested(address caller, uint64 earlyExpirationTimeStamp)
PositionSettled(address sponsor, uint256 collateralReturned, uint256 longTokens, uint256 shortTokens)

Modifiers#

preExpiration()
postExpiration()
notEarlyExpired()
nonReentrant()

Prevents a contract from calling itself, directly or indirectly. Calling a nonReentrant function from another nonReentrant function is not supported. It is possible to prevent this from happening by making the nonReentrant function external, and making it call a private function that does the actual state modification.

nonReentrantView()

Designed to prevent a view-only method from being re-entered during a call to a nonReentrant() state-changing method.

onlyIfTest()

Reverts if not running in test mode.