Liquidatable
Liquidatable#
Adds logic to a position-managing contract that enables callers to liquidate an undercollateralized position.
The liquidation has a liveness period before expiring successfully, during which someone can "dispute" the liquidation, which sends a price request to the relevant Oracle to settle the final collateralization ratio based on a DVM price. The contract enforces dispute rewards in order to incentivize disputers to correctly dispute false liquidations and compensate position sponsors who had their position incorrectly liquidated. Importantly, a prospective disputer must deposit a dispute bond that they can lose in the case of an unsuccessful dispute. NOTE: this contract does not work with ERC777 collateral currencies or any others that call into the receiver on transfer(). Using an ERC777 token would allow a user to maliciously grief other participants (while also losing money themselves).
Functions#
constructor(struct Liquidatable.ConstructorParams params) (public)Constructs the liquidatable contract.
Parameters:#
- params: struct to define input parameters for construction of Liquidatable. Some params are fed directly into the PricelessPositionManager's constructor within the inheritance tree.
createLiquidation(address sponsor, struct FixedPoint.Unsigned minCollateralPerToken, struct FixedPoint.Unsigned maxCollateralPerToken, struct FixedPoint.Unsigned maxTokensToLiquidate, uint256 deadline) → uint256 liquidationId, struct FixedPoint.Unsigned tokensLiquidated, struct FixedPoint.Unsigned finalFeeBond (external)Liquidates the sponsor's position if the caller has enough synthetic tokens to retire the position's outstanding tokens. Liquidations above a minimum size also reset an ongoing "slow withdrawal"'s liveness.
This method generates an ID that will uniquely identify liquidation for the sponsor. This contract must be
approved to spend at least tokensLiquidated of tokenCurrency and at least finalFeeBond of collateralCurrency.
This contract must have the Burner role for the tokenCurrency.
Parameters:#
- sponsor: address of the sponsor to liquidate.
- minCollateralPerToken: abort the liquidation if the position's collateral per token is below this value.
- maxCollateralPerToken: abort the liquidation if the position's collateral per token exceeds this value.
- maxTokensToLiquidate: max number of tokens to liquidate.
- deadline: abort the liquidation if the transaction is mined after this timestamp.
dispute(uint256 liquidationId, address sponsor) → struct FixedPoint.Unsigned totalPaid (external)Disputes a liquidation, if the caller has enough collateral to post a dispute bond and pay a fixed final fee charged on each price request.
Can only dispute a liquidation before the liquidation expires and if there are no other pending disputes.
This contract must be approved to spend at least the dispute bond amount of collateralCurrency. This dispute
bond amount is calculated from disputeBondPercentage times the collateral in the liquidation.
Parameters:#
- liquidationId: of the disputed liquidation.
- sponsor: the address of the sponsor whose liquidation is being disputed.
withdrawLiquidation(uint256 liquidationId, address sponsor) → struct Liquidatable.RewardsData (public)After a dispute has settled or after a non-disputed liquidation has expired, anyone can call this method to disperse payments to the sponsor, liquidator, and disdputer.
If the dispute SUCCEEDED: the sponsor, liquidator, and disputer are eligible for payment. If the dispute FAILED: only the liquidator can receive payment. This method will revert if rewards have already been dispersed.
Parameters:#
- liquidationId: uniquely identifies the sponsor's liquidation.
- sponsor: address of the sponsor associated with the liquidation.
getLiquidations(address sponsor) → struct Liquidatable.LiquidationData[] liquidationData (external)Gets all liquidation information for a given sponsor address.
Parameters:#
- sponsor: address of the position sponsor.
transformCollateralRequirement(struct FixedPoint.Unsigned price) → struct FixedPoint.Unsigned (public)Accessor method to calculate a transformed collateral requirement using the finanical product library specified during contract deployment. If no library was provided then no modification to the collateral requirement is done.
This method should never revert.
Parameters:#
- price: input price used as an input to transform the collateral requirement.
_settle(uint256 liquidationId, address sponsor) (internal)_pfc() → struct FixedPoint.Unsigned (internal)_getLiquidationData(address sponsor, uint256 liquidationId) → struct Liquidatable.LiquidationData liquidation (internal)_getLiquidationExpiry(struct Liquidatable.LiquidationData liquidation) → uint256 (internal)_disputable(uint256 liquidationId, address sponsor) (internal)_withdrawable(uint256 liquidationId, address sponsor) (internal)_transformCollateralRequirement(struct FixedPoint.Unsigned price) → struct FixedPoint.Unsigned (internal)requestTransferPosition() (public)Requests to transfer ownership of the caller's current position to a new sponsor address. Once the request liveness is passed, the sponsor can execute the transfer and specify the new sponsor.
The liveness length is the same as the withdrawal liveness.
transferPositionPassedRequest(address newSponsorAddress) (public)After a passed transfer position request (i.e., by a call to requestTransferPosition and waiting
withdrawalLiveness), transfers ownership of the caller's current position to newSponsorAddress.
Transferring positions can only occur if the recipient does not already have a position.
Parameters:#
- newSponsorAddress: is the address to which the position will be transferred.
cancelTransferPosition() (external)Cancels a pending transfer position request.
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.
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.
This contract must have the Minter role for the tokenCurrency.
Parameters:#
- collateralAmount: is the number of collateral tokens to collateralize the position with
- numTokens: is the number of tokens to mint from the position.
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.
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.
settleExpired() → struct FixedPoint.Unsigned amountWithdrawn (external)After a contract has passed expiry all token holders can redeem their tokens for underlying at the
prevailing price defined by the DVM from the expire function.
This burns all tokens from the caller of tokenCurrency and sends back the proportional amount 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.
expire() (external)Locks contract state in expired and requests oracle price.
this function can only be called once the contract is expired and can't be re-called.
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 standard settleExpired function. Contract state is set to ExpiredPriceRequested
which prevents re-entry into this function or the expire function. No fees are paid when calling
emergencyShutdown as the governor who would call the function would also receive the fees.
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 (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 (external)Accessor method for the total collateral stored within the PricelessPositionManager.
This method accounts for pending regular fees that have not yet been withdrawn from this contract, for
example if the lastPaymentTime != currentTime.
transformPrice(struct FixedPoint.Unsigned price, uint256 requestTime) → struct FixedPoint.Unsigned (public)Accessor method to compute a transformed price using the finanicalProductLibrary specified at contract deployment. If no library was provided then no modification to the price is done.
This method should never revert.
Parameters:#
- price: input price to be transformed.
- requestTime: timestamp the oraclePrice was requested at.
transformPriceIdentifier(uint256 requestTime) → bytes32 (public)Accessor method to compute a transformed price identifier using the finanicalProductLibrary specified at contract deployment. If no library was provided then no modification to the identifier is done.
This method should never revert.
Parameters:#
- requestTime: timestamp the identifier is to be used at.
_reduceSponsorPosition(address sponsor, struct FixedPoint.Unsigned tokensToRemove, struct FixedPoint.Unsigned collateralToRemove, struct FixedPoint.Unsigned withdrawalAmountToRemove) (internal)_deleteSponsorPosition(address sponsor) → struct FixedPoint.Unsigned (internal)_getPositionData(address sponsor) → struct PricelessPositionManager.PositionData (internal)_getIdentifierWhitelist() → contract IdentifierWhitelistInterface (internal)_getOracle() → contract OracleInterface (internal)_getOptimisticOracle() → contract OptimisticOracleInterface (internal)_getFinancialContractsAdminAddress() → address (internal)_requestOraclePriceExpiration(uint256 requestedTime) (internal)_getOraclePriceExpiration(uint256 requestedTime) → struct FixedPoint.Unsigned (internal)_requestOraclePriceLiquidation(uint256 requestedTime) (internal)_getOraclePriceLiquidation(uint256 requestedTime) → struct FixedPoint.Unsigned (internal)_resetWithdrawalRequest(struct PricelessPositionManager.PositionData positionData) (internal)_incrementCollateralBalances(struct PricelessPositionManager.PositionData positionData, struct FixedPoint.Unsigned collateralAmount) → struct FixedPoint.Unsigned (internal)_decrementCollateralBalances(struct PricelessPositionManager.PositionData positionData, struct FixedPoint.Unsigned collateralAmount) → struct FixedPoint.Unsigned (internal)_decrementCollateralBalancesCheckGCR(struct PricelessPositionManager.PositionData positionData, struct FixedPoint.Unsigned collateralAmount) → struct FixedPoint.Unsigned (internal)_onlyOpenState() (internal)_onlyPreExpiration() (internal)_onlyPostExpiration() (internal)_onlyCollateralizedPosition(address sponsor) (internal)_positionHasNoPendingWithdrawal(address sponsor) (internal)_getSyntheticDecimals(address _collateralAddress) → uint8 decimals (public)_transformPrice(struct FixedPoint.Unsigned price, uint256 requestTime) → struct FixedPoint.Unsigned (internal)_transformPriceIdentifier(uint256 requestTime) → bytes32 (internal)_getAncillaryData() → bytes (internal)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)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#
LiquidationCreated(address sponsor, address liquidator, uint256 liquidationId, uint256 tokensOutstanding, uint256 lockedCollateral, uint256 liquidatedCollateral, uint256 liquidationTime)LiquidationDisputed(address sponsor, address liquidator, address disputer, uint256 liquidationId, uint256 disputeBondAmount)DisputeSettled(address caller, address sponsor, address liquidator, address disputer, uint256 liquidationId, bool disputeSucceeded)LiquidationWithdrawn(address caller, uint256 paidToLiquidator, uint256 paidToDisputer, uint256 paidToSponsor, enum Liquidatable.Status liquidationStatus, uint256 settlementPrice)RequestTransferPosition(address oldSponsor)RequestTransferPositionExecuted(address oldSponsor, address newSponsor)RequestTransferPositionCanceled(address oldSponsor)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)Repay(address sponsor, uint256 numTokensRepaid, uint256 newTokenCount)Redeem(address sponsor, uint256 collateralAmount, uint256 tokenAmount)ContractExpired(address caller)SettleExpiredPosition(address caller, uint256 collateralReturned, uint256 tokensBurned)EmergencyShutdown(address caller, uint256 originalExpirationTimestamp, uint256 shutdownTimestamp)RegularFeesPaid(uint256 regularFee, uint256 lateFee)FinalFeesPaid(uint256 amount)Modifiers#
disputable(uint256 liquidationId, address sponsor)withdrawable(uint256 liquidationId, address sponsor)onlyPreExpiration()onlyPostExpiration()onlyCollateralizedPosition(address sponsor)onlyOpenState()noPendingWithdrawal(address sponsor)fees()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.