Skip to main content

PerpetualPositionManager

PerpetualPositionManager#

Handles positions for multiple sponsors in an optimistic (i.e., priceless) way without relying on a price feed. On construction, deploys a new ERC20, managed by this contract, that is the synthetic token.

Functions#

constructor(uint256 _withdrawalLiveness, address _collateralAddress, address _tokenAddress, address _finderAddress, bytes32 _priceIdentifier, bytes32 _fundingRateIdentifier, struct FixedPoint.Unsigned _minSponsorTokens, address _configStoreAddress, struct FixedPoint.Unsigned _tokenScaling, address _timerAddress) (public)

Construct the PerpetualPositionManager.

Deployer of this contract should consider carefully which parties have ability to mint and burn the synthetic tokens referenced by _tokenAddress. This contract's security assumes that no external accounts can mint new tokens, which could be used to steal all of this contract's locked collateral. We recommend to only use synthetic token contracts whose sole Owner role (the role capable of adding & removing roles) is assigned to this contract, whose sole Minter role is assigned to this contract, and whose total supply is 0 prior to construction of this contract.

Parameters:#

  • _withdrawalLiveness: liveness delay, in seconds, for pending withdrawals.
  • _collateralAddress: ERC20 token used as collateral for all positions.
  • _tokenAddress: ERC20 token used as synthetic token.
  • _finderAddress: UMA protocol Finder used to discover other protocol contracts.
  • _priceIdentifier: registered in the DVM for the synthetic.
  • _fundingRateIdentifier: Unique identifier for DVM price feed ticker for child financial contract.
  • _minSponsorTokens: minimum number of tokens that must exist at any time in a position.
  • _tokenScaling: initial scaling to apply to the token value (i.e. scales the tracking index).
  • _timerAddress: Contract that stores the current time in a testing environment. Set to 0x0 for production.
depositTo(address sponsor, struct FixedPoint.Unsigned collateralAmount) (public)

Transfers collateralAmount of collateralCurrency into the specified sponsor's position.

Increases the collateralization level of a position after creation. This contract must be approved to spend at least collateralAmount of collateralCurrency.

Parameters:#

  • sponsor: the sponsor to credit the deposit to.
  • collateralAmount: total amount of collateral tokens to be sent to the sponsor's position.
deposit(struct FixedPoint.Unsigned collateralAmount) (public)

Transfers collateralAmount of collateralCurrency into the caller's position.

Increases the collateralization level of a position after creation. This contract must be approved to spend at least collateralAmount of collateralCurrency.

Parameters:#

  • collateralAmount: total amount of collateral tokens to be sent to the sponsor's position.
withdraw(struct FixedPoint.Unsigned collateralAmount) → struct FixedPoint.Unsigned amountWithdrawn (public)

Transfers collateralAmount of collateralCurrency from the sponsor's position to the sponsor.

Reverts if the withdrawal puts this position's collateralization ratio below the global collateralization ratio. In that case, use requestWithdrawal. Might not withdraw the full requested amount to account for precision loss.

Parameters:#

  • collateralAmount: is the amount of collateral to withdraw.
requestWithdrawal(struct FixedPoint.Unsigned collateralAmount) (public)

Starts a withdrawal request that, if passed, allows the sponsor to withdraw from their position.

The request will be pending for withdrawalLiveness, during which the position can be liquidated.

Parameters:#

  • collateralAmount: the amount of collateral requested to withdraw
withdrawPassedRequest() → struct FixedPoint.Unsigned amountWithdrawn (external)

After a passed withdrawal request (i.e., by a call to requestWithdrawal and waiting withdrawalLiveness), withdraws positionData.withdrawalRequestAmount of collateral currency.

Might not withdraw the full requested amount in order to account for precision loss or if the full requested amount exceeds the collateral in the position (due to paying fees).

cancelWithdrawal() (external)

Cancels a pending withdrawal request.

create(struct FixedPoint.Unsigned collateralAmount, struct FixedPoint.Unsigned numTokens) (public)

Creates tokens by creating a new position or by augmenting an existing position. Pulls collateralAmount into the sponsor's position and mints numTokens of tokenCurrency.

This contract must have the Minter role for the tokenCurrency. Reverts if minting these tokens would put the position's collateralization ratio below the global collateralization ratio. This contract must be approved to spend at least collateralAmount of collateralCurrency.

Parameters:#

  • collateralAmount: is the number of collateral tokens to collateralize the position with
  • numTokens: is the number of tokens to mint from the position.
redeem(struct FixedPoint.Unsigned numTokens) → struct FixedPoint.Unsigned amountWithdrawn (public)

Burns numTokens of tokenCurrency and sends back the proportional amount of collateralCurrency.

Can only be called by a token sponsor. Might not redeem the full proportional amount of collateral in order to account for precision loss. This contract must be approved to spend at least numTokens of tokenCurrency. This contract must have the Burner role for the tokenCurrency.

Parameters:#

  • numTokens: is the number of tokens to be burnt for a commensurate amount of collateral.
repay(struct FixedPoint.Unsigned numTokens) (public)

Burns numTokens of tokenCurrency to decrease sponsors position size, without sending back collateralCurrency. This is done by a sponsor to increase position CR. Resulting size is bounded by minSponsorTokens.

Can only be called by token sponsor. This contract must be approved to spend numTokens of tokenCurrency. This contract must have the Burner role for the tokenCurrency.

Parameters:#

  • numTokens: is the number of tokens to be burnt from the sponsor's debt position.
settleEmergencyShutdown() → struct FixedPoint.Unsigned amountWithdrawn (external)

If the contract is emergency shutdown then all token holders and sponsors can redeem their tokens or remaining collateral for underlying at the prevailing price defined by a DVM vote.

This burns all tokens from the caller of tokenCurrency and sends back the resolved settlement value of collateralCurrency. Might not redeem the full proportional amount of collateral in order to account for precision loss. This contract must be approved to spend tokenCurrency at least up to the caller's full balance. This contract must have the Burner role for the tokenCurrency. Note that this function does not call the updateFundingRate modifier to update the funding rate as this function is only called after an emergency shutdown & there should be no funding rate updates after the shutdown.

emergencyShutdown() (external)

Premature contract settlement under emergency circumstances.

Only the governor can call this function as they are permissioned within the FinancialContractAdmin. Upon emergency shutdown, the contract settlement time is set to the shutdown time. This enables withdrawal to occur via the settleEmergencyShutdown function.

remargin() (external)

Theoretically supposed to pay fees and move money between margin accounts to make sure they reflect the NAV of the contract. However, this functionality doesn't apply to this contract.

This is supposed to be implemented by any contract that inherits AdministrateeInterface and callable only by the Governor contract. This method is therefore minimally implemented in this contract and does nothing.

getCollateral(address sponsor) → struct FixedPoint.Unsigned collateralAmount (external)

Accessor method for a sponsor's collateral.

This is necessary because the struct returned by the positions() method shows rawCollateral, which isn't a user-readable value. This method accounts for pending regular fees that have not yet been withdrawn from this contract, for example if the lastPaymentTime != currentTime.

Parameters:#

  • sponsor: address whose collateral amount is retrieved.
totalPositionCollateral() → struct FixedPoint.Unsigned totalCollateral (external)

Accessor method for the total collateral stored within the PerpetualPositionManager.

getFundingRateAppliedTokenDebt(struct FixedPoint.Unsigned rawTokenDebt) → struct FixedPoint.Unsigned totalCollateral (external)
_reduceSponsorPosition(address sponsor, struct FixedPoint.Unsigned tokensToRemove, struct FixedPoint.Unsigned collateralToRemove, struct FixedPoint.Unsigned withdrawalAmountToRemove) (internal)
_deleteSponsorPosition(address sponsor) → struct FixedPoint.Unsigned (internal)
_pfc() → struct FixedPoint.Unsigned (internal)
_getPositionData(address sponsor) → struct PerpetualPositionManager.PositionData (internal)
_getIdentifierWhitelist() → contract IdentifierWhitelistInterface (internal)
_getOracle() → contract OracleInterface (internal)
_getFinancialContractsAdminAddress() → address (internal)
_requestOraclePrice(uint256 requestedTime) (internal)
_getOraclePrice(uint256 requestedTime) → struct FixedPoint.Unsigned price (internal)
_getOracleEmergencyShutdownPrice() → struct FixedPoint.Unsigned (internal)
_resetWithdrawalRequest(struct PerpetualPositionManager.PositionData positionData) (internal)
_incrementCollateralBalances(struct PerpetualPositionManager.PositionData positionData, struct FixedPoint.Unsigned collateralAmount) → struct FixedPoint.Unsigned (internal)
_decrementCollateralBalances(struct PerpetualPositionManager.PositionData positionData, struct FixedPoint.Unsigned collateralAmount) → struct FixedPoint.Unsigned (internal)
_decrementCollateralBalancesCheckGCR(struct PerpetualPositionManager.PositionData positionData, struct FixedPoint.Unsigned collateralAmount) → struct FixedPoint.Unsigned (internal)
_onlyCollateralizedPosition(address sponsor) (internal)
_positionHasNoPendingWithdrawal(address sponsor) (internal)
_getTokenAddress() → address (internal)
applyFundingRate() (public)

This method takes 3 distinct actions:

  1. Pays out regular fees.
  2. If possible, resolves the outstanding funding rate proposal, pulling the result in and paying out the rewards.
  3. Applies the prevailing funding rate over the most recent period.
proposeFundingRate(struct FixedPoint.Signed rate, uint256 timestamp) → struct FixedPoint.Unsigned totalBond (external)

Proposes a new funding rate. Proposer receives a reward if correct.

Parameters:#

  • rate: funding rate being proposed.
  • timestamp: time at which the funding rate was computed.
_getFundingRateAppliedTokenDebt(struct FixedPoint.Unsigned rawTokenDebt) → struct FixedPoint.Unsigned tokenDebt (internal)
_getOptimisticOracle() → contract OptimisticOracleInterface (internal)
_getConfig() → struct ConfigStoreInterface.ConfigSettings (internal)
_updateFundingRate() (internal)
_validateFundingRate(struct FixedPoint.Signed rate) (internal)
_applyEffectiveFundingRate() (internal)
_calculateEffectiveFundingRate(uint256 paymentPeriodSeconds, struct FixedPoint.Signed fundingRatePerSecond, struct FixedPoint.Unsigned currentCumulativeFundingRateMultiplier) → struct FixedPoint.Unsigned newCumulativeFundingRateMultiplier (internal)
_getAncillaryData() → bytes (internal)

We do not need to check that the ancillary data length is less than the hardcoded max length in the OptimisticOracle because the length of the ancillary data is fixed in this function.

payRegularFees() → struct FixedPoint.Unsigned (public)

Pays UMA DVM regular fees (as a % of the collateral pool) to the Store contract.

These must be paid periodically for the life of the contract. If the contract has not paid its regular fee in a week or more then a late penalty is applied which is sent to the caller. If the amount of fees owed are greater than the pfc, then this will pay as much as possible from the available collateral. An event is only fired if the fees charged are greater than 0.

getOutstandingRegularFees(uint256 time) → struct FixedPoint.Unsigned regularFee, struct FixedPoint.Unsigned latePenalty, struct FixedPoint.Unsigned totalPaid (public)

Fetch any regular fees that the contract has pending but has not yet paid. If the fees to be paid are more than the total collateral within the contract then the totalPaid returned is full contract collateral amount.

This returns 0 and exit early if there is no pfc, fees were already paid during the current block, or the fee rate is 0.

pfc() → struct FixedPoint.Unsigned (external)

Gets the current profit from corruption for this contract in terms of the collateral currency.

This is equivalent to the collateral pool available from which to pay fees. Therefore, derived contracts are expected to implement this so that pay-fee methods can correctly compute the owed fees as a % of PfC.

gulp() (external)

Removes excess collateral balance not counted in the PfC by distributing it out pro-rata to all sponsors.

Multiplying the cumulativeFeeMultiplier by the ratio of non-PfC-collateral :: PfC-collateral effectively pays all sponsors a pro-rata portion of the excess collateral. This will revert if PfC is 0 and this contract's collateral balance > 0.

_payFinalFees(address payer, struct FixedPoint.Unsigned amount) (internal)
_gulp() (internal)
_getStore() → contract StoreInterface (internal)
_computeFinalFees() → struct FixedPoint.Unsigned finalFees (internal)
_getFeeAdjustedCollateral(struct FixedPoint.Unsigned rawCollateral) → struct FixedPoint.Unsigned collateral (internal)
_getPendingRegularFeeAdjustedCollateral(struct FixedPoint.Unsigned rawCollateral) → struct FixedPoint.Unsigned (internal)
_convertToRawCollateral(struct FixedPoint.Unsigned collateral) → struct FixedPoint.Unsigned rawCollateral (internal)
_removeCollateral(struct FixedPoint.Unsigned rawCollateral, struct FixedPoint.Unsigned collateralToRemove) → struct FixedPoint.Unsigned removedCollateral (internal)
_addCollateral(struct FixedPoint.Unsigned rawCollateral, struct FixedPoint.Unsigned collateralToAdd) → struct FixedPoint.Unsigned addedCollateral (internal)
_adjustCumulativeFeeMultiplier(struct FixedPoint.Unsigned amount, struct FixedPoint.Unsigned currentPfc) (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.

_notEmergencyShutdown() (internal)
_isEmergencyShutdown() (internal)

Events#

Deposit(address sponsor, uint256 collateralAmount)
Withdrawal(address sponsor, uint256 collateralAmount)
RequestWithdrawal(address sponsor, uint256 collateralAmount)
RequestWithdrawalExecuted(address sponsor, uint256 collateralAmount)
RequestWithdrawalCanceled(address sponsor, uint256 collateralAmount)
PositionCreated(address sponsor, uint256 collateralAmount, uint256 tokenAmount)
NewSponsor(address sponsor)
EndedSponsorPosition(address sponsor)
Redeem(address sponsor, uint256 collateralAmount, uint256 tokenAmount)
Repay(address sponsor, uint256 numTokensRepaid, uint256 newTokenCount)
EmergencyShutdown(address caller, uint256 shutdownTimestamp)
SettleEmergencyShutdown(address caller, uint256 collateralReturned, uint256 tokensBurned)
FundingRateUpdated(int256 newFundingRate, uint256 updateTime, uint256 reward)
RegularFeesPaid(uint256 regularFee, uint256 lateFee)
FinalFeesPaid(uint256 amount)

Modifiers#

onlyCollateralizedPosition(address sponsor)
noPendingWithdrawal(address sponsor)
fees()
paysRegularFees()
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.

notEmergencyShutdown()
isEmergencyShutdown()