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.

disputable(uint256 liquidationId, address sponsor) modifier


==== withdrawable(uint256 liquidationId, address sponsor) modifier

==== onlyPreExpiration() modifier


onlyPostExpiration() modifier

onlyCollateralizedPosition(address sponsor) modifier

onlyOpenState() modifier

fees() modifier


==== onlyIfTest() modifier

Reverts if not running in test mode.

==== constructor(struct Liquidatable.ConstructorParams params) public

Constructs the liquidatable contract.


  • 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 collateralPerToken, struct FixedPoint.Unsigned maxTokensToLiquidate) → uint256 liquidationId external

Liquidates the sponsor’s position if the caller has enough synthetic tokens to retire the position’s outstanding tokens.

This method generates an ID that will uniquely identify liquidation for the sponsor.


  • sponsor: address to liquidate.

  • collateralPerToken: abort the liquidation if the position’s collateral per token exceeds this value.

  • maxTokensToLiquidate: max number of tokes to liquidate.

==== dispute(uint256 liquidationId, address sponsor) 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.


  • liquidationId: of the disputed liquidation.

  • sponsor: the address of the sponsor who’s liquidation is being disputed.

==== withdrawLiquidation(uint256 liquidationId, address sponsor) → struct FixedPoint.Unsigned withdrawalAmount public

After a dispute has settled or after a non-disputed liquidation has expired, the sponsor, liquidator, and/or disputer can call this method to receive payments.

If the dispute SUCCEEDED: the sponsor, liquidator, and disputer are eligible for payment If the dispute FAILED: only the liquidator can receive payment Once all collateral is withdrawn, delete the liquidation data.


  • liquidationId: uniquely identifies the sponsor’s liquidation.

  • sponsor: address of the sponsor associated with the liquidation.

==== pfc() → struct FixedPoint.Unsigned public

This overrides pfc() so the Liquidatable contract can report its profit from corruption.

==== getLiquidations(address sponsor) → struct Liquidatable.LiquidationData[] external

==== _settle(uint256 liquidationId, address sponsor) internal


_getLiquidationData(address sponsor, uint256 liquidationId) → struct Liquidatable.LiquidationData liquidation internal

_getLiquidationExpiry(struct Liquidatable.LiquidationData liquidation) → uint256 internal

_disputable(uint256 liquidationId, address sponsor) internal

These internal functions are supposed to act identically to modifiers, but re-used modifiers unnecessarily increase contract bytecode size. source:

_withdrawable(uint256 liquidationId, address sponsor) internal

transfer(address newSponsorAddress) public

Transfers ownership of the caller’s current position to newSponsorAddress.

Transferring positions can only occur if the recipient does not already have a position.


  • newSponsorAddress: is the address to which the position will be transferred.

deposit(struct FixedPoint.Unsigned collateralAmount) public

Transfers collateralAmount of collateralCurrency into the sponsor’s position.

Increases the collateralization level of a position after creation.


  • collateralAmount: total amount of collateral tokens to be sent to the sponsor’s position.

withdraw(struct FixedPoint.Unsigned collateralAmount) 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 requestWithdrawawal.


  • 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 collateralAmount from their position.

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


  • collateralAmount: the amount of collateral requested to withdraw

withdrawPassedRequest() external

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

cancelWithdrawal() external

Cancels a pending withdrawal request.

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

Pulls collateralAmount into the sponsor’s position and mints numTokens of tokenCurrency.

Reverts if the minting these tokens would put the position’s collateralization ratio below the global collateralization ratio.


  • 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) public

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

Can only be called by a token sponsor.


  • numTokens: is the number of tokens to be burnt for a commensurate amount of collateral.

settleExpired() 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.

expire() external

Locks contract state in expired and requests oracle price.

this function can only be called once the contract is expired and cant be re-called due to the state modifiers applied on it.

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

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.


  • sponsor: address whose collateral amount is retrieved.

totalPositionCollateral() → struct FixedPoint.Unsigned external

Accessor method for the total collateral stored within the PricelessPositionManager.

_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

==== _getStoreAddress() → address internal

==== _getFinancialContractsAdminAddress() → address internal

==== _requestOraclePrice(uint256 requestedTime) internal

==== _getOraclePrice(uint256 requestedTime) → struct FixedPoint.Unsigned internal

==== _onlyOpenState() internal

These internal functions are supposed to act identically to modifiers, but re-used modifiers unnecessarily increase contract bytecode size. source:

==== _onlyPreExpiration() internal

==== _onlyPostExpiration() internal

==== _onlyCollateralizedPosition(address sponsor) internal

==== payFees() → struct FixedPoint.Unsigned totalPaid public

Pays UMA DVM regular fees 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 mre then a late penalty is applied which is sent to the caller.

==== _payFinalFees(address payer, struct FixedPoint.Unsigned amount) internal

Pays UMA DVM final fees to the Store contract.

This is a flat fee charged for each price request.


  • payer: address of who is paying the fees.

  • amount: the amount of collateral to send as the final fee.

==== _getStore() → contract StoreInterface internal


_computeFinalFees() → struct FixedPoint.Unsigned finalFees internal

_getCollateral(struct FixedPoint.Unsigned rawCollateral) → struct FixedPoint.Unsigned collateral internal

_convertCollateral(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

setCurrentTime(uint256 _time) external

Sets the current time.

Will revert if not running in test mode.

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.

LiquidationCreated(address sponsor, address liquidator, uint256 liquidationId, uint256 tokensOutstanding, uint256 lockedCollateral, uint256 liquidatedCollateral) event


==== LiquidationDisputed(address sponsor, address liquidator, address disputer, uint256 liquidationId, uint256 disputeBondAmount) event

==== DisputeSettled(address caller, address sponsor, address liquidator, address disputer, uint256 liquidationId, bool DisputeSucceeded) event

==== LiquidationWithdrawn(address caller, uint256 withdrawalAmount, enum Liquidatable.Status liquidationStatus) event

==== Transfer(address oldSponsor, address newSponsor) event


Deposit(address sponsor, uint256 collateralAmount) event

Withdrawal(address sponsor, uint256 collateralAmount) event

RequestWithdrawal(address sponsor, uint256 collateralAmount) event

RequestWithdrawalExecuted(address sponsor, uint256 collateralAmount) event

RequestWithdrawalCanceled(address sponsor, uint256 collateralAmount) event

PositionCreated(address sponsor, uint256 collateralAmount, uint256 tokenAmount) event

NewSponsor(address sponsor) event

Redeem(address sponsor, uint256 collateralAmount, uint256 tokenAmount) event

ContractExpired(address caller) event

SettleExpiredPosition(address caller, uint256 collateralReturned, uint256 tokensBurned) event

EmergencyShutdown(address caller, uint256 originalExpirationTimestamp, uint256 shutdownTimestamp) event

© UMA Project 2018-2019