Escrow

Last updated 3 years ago

Was this helpful?

Escrow

Manages a account balances for the entire system including deposits, withdraws, cash balances, collateral lockup for trading, cash transfers (settlement), and liquidation.

Methods

Events

Governance Methods

Methods

isValidCurrency

Evaluates whether or not a currency id is valid
Parameters:
currency: currency id
Return Values:
true if the currency is valid

getExchangeRate

Getter method for exchange rates
Parameters:
base: token address for the base currency
quote: token address for the quote currency
Return Values:
ExchangeRate struct

getBalances

Returns the net balances of all the currencies owned by an account as an array. Each index of the array refers to the currency id.
Parameters:
account: the account to query
Return Values:
the balance of each currency net of the account's cash position

convertBalancesToETH

Converts the balances given to ETH for the purposes of determining whether an account has sufficient free collateral.
Parameters:
amounts: the balance in each currency group as an array, each index refers to the currency group id.
Return Values:
an array the same length as amounts with each balance denominated in ETH

Error Codes:

INVALID_CURRENCY: length of the amounts array must match the total number of currencies
INVALID_EXCHANGE_RATE: exchange rate returned by the oracle is less than 0

depositEth

This is a special function to handle ETH deposits. Value of ETH to be deposited must be specified in msg.value

Error Codes:

OVER_MAX_ETH_BALANCE: balance of deposit cannot overflow uint128

withdrawEth

Withdraw ETH from the contract.
Parameters:
amount: the amount of eth to withdraw from the contract

Error Codes:

INSUFFICIENT_BALANCE: not enough balance in account
INSUFFICIENT_FREE_COLLATERAL: not enough free collateral to withdraw
TRANSFER_FAILED: eth transfer did not return success

deposit

Transfers a balance from an ERC20 token contract into the Escrow. Do not call this for ERC777 transfers, use the send method instead.
Parameters:
token: token contract to send from
amount: tokens to transfer

Error Codes:

INVALID_CURRENCY: token address supplied is not a valid currency

withdraw

Withdraws from an account's collateral holdings back to their account. Checks if the account has sufficient free collateral after the withdraw or else it fails.
Parameters:
token: collateral type to withdraw
amount: total value to withdraw

Error Codes:

INSUFFICIENT_BALANCE: not enough balance in account
INVALID_CURRENCY: token address supplied is not a valid currency
INSUFFICIENT_FREE_COLLATERAL: not enough free collateral to withdraw

settleCashBalanceBatch

Settles the cash balances of payers in batch
Parameters:
localCurrency: the currency that the payer's debts are denominated in
collateralCurrency: the collateral to settle the debts against
payers: the party that has a negative cash balance and will transfer collateral to the receiver
values: the amount of collateral to transfer

Error Codes:

INVALID_CURRENCY: currency specified is invalid
INCORRECT_CASH_BALANCE: payer does not have sufficient cash balance to settle
INVALID_EXCHANGE_RATE: exchange rate returned by the oracle is less than 0
NO_EXCHANGE_LISTED_FOR_PAIR: cannot settle cash because no exchange is listed for the pair
INSUFFICIENT_COLLATERAL_FOR_SETTLEMENT: not enough collateral to settle on the exchange
RESERVE_ACCOUNT_HAS_INSUFFICIENT_BALANCE: settling requires the reserve account, but there is insufficient
balance to do so
INSUFFICIENT_COLLATERAL_BALANCE: account does not hold enough collateral to settle, they will have
additional collateral in a different currency if they are collateralized
INSUFFICIENT_FREE_COLLATERAL_SETTLER: calling account to settle cash does not have sufficient free collateral
after settling payers and receivers

settleCashBalance

Settles the cash balance between the payer and the receiver.
Parameters:
localCurrency: the currency that the payer's debts are denominated in
collateralCurrency: the collateral to settle the debts against
payer: the party that has a negative cash balance and will transfer collateral to the receiver
value: the amount of collateral to transfer

Error Codes:

INCORRECT_CASH_BALANCE: payer or receiver does not have sufficient cash balance to settle
INVALID_EXCHANGE_RATE: exchange rate returned by the oracle is less than 0
NO_EXCHANGE_LISTED_FOR_PAIR: cannot settle cash because no exchange is listed for the pair
INSUFFICIENT_COLLATERAL_FOR_SETTLEMENT: not enough collateral to settle on the exchange
RESERVE_ACCOUNT_HAS_INSUFFICIENT_BALANCE: settling requires the reserve account, but there is insufficient
balance to do so
INSUFFICIENT_COLLATERAL_BALANCE: account does not hold enough collateral to settle, they will have
INSUFFICIENT_FREE_COLLATERAL_SETTLER: calling account to settle cash does not have sufficient free collateral
after settling payers and receivers

liquidateBatch

Liquidates a batch of accounts in a specific currency.
Parameters:
accounts: the account to liquidate
localCurrency: the currency that is undercollateralized
collateralCurrency: the collateral currency to exchange for currency

Error Codes:

CANNOT_LIQUIDATE_SUFFICIENT_COLLATERAL: account has positive free collateral and cannot be liquidated
CANNOT_LIQUIDATE_SELF: liquidator cannot equal the liquidated account
INSUFFICIENT_FREE_COLLATERAL_LIQUIDATOR: liquidator does not have sufficient free collateral after liquidating
accounts

liquidate

Liquidates a single account if it is undercollateralized
Parameters:
account: the account to liquidate
localCurrency: the currency that is undercollateralized
collateralCurrency: the collateral currency to exchange for currency

Error Codes:

CANNOT_LIQUIDATE_SUFFICIENT_COLLATERAL: account has positive free collateral and cannot be liquidated
CANNOT_LIQUIDATE_SELF: liquidator cannot equal the liquidated account
INSUFFICIENT_FREE_COLLATERAL_LIQUIDATOR: liquidator does not have sufficient free collateral after liquidating
accounts
CANNOT_LIQUIDATE_TO_WORSE_FREE_COLLATERAL: we cannot liquidate an account and have it end up in a worse free
collateral position than when it started. This is possible if collateralCurrency has a larger haircut than currency.

settlefCash

Purchase fCash receiver asset in the portfolio. This can only be done if the account has no other positive cash balances and no liquidity tokens in its portfolio. The fCash receiver would be its only source of positive collateral. Notional will first attempt to sell fCash in CashMarkets before selling it to the liquidator at a discount.
Parameters:
payer: account that will pay fCash to settle current debts
localCurrency: currency that current debts are denominated
collateralCurrency: currency that fCash receivers are denominated in, it is possible for collateralCurrency to equal
localCurrency.
valueToSettle: amount of local currency debts to settle

liquidatefCash

Purchase fCash receiver assets in order to recollateralize a portfolio. Similar to settlefCash, this can only be done
Parameters:
payer: account that will pay fCash to settle current debts
localCurrency: currency that current debts are denominated in
collateralCurrency: currency that fCash receivers are denominated in. Unlike settlfCash it is not possible for localCurrency
to equal collateralCurrency because liquidating local currency fCash receivers will never help recollateralize a portfolio. Local currency
fCash receivers only accrue value as they get closer to maturity.

settleReserve

Settles current debts in an account against the reserve. Only possible if an account is truly insolvent, meaning that it only holds debts and has no remaining sources of positive collateral.
Parameters:
account: account that is undercollateralized
localCurrency: currency that current debts are denominated in

Events

NewCurrency

A new currency
Parameters:
token: address of the tradable token

UpdateExchangeRate

A new exchange rate between two currencies
Parameters:
base: id of the base currency
quote: id of the quote currency

Deposit

Notice of a deposit made to an account
Parameters:
currency: currency id of the deposit
account: address of the account where the deposit was made
value: amount of tokens deposited

Withdraw

Notice of a withdraw from an account
Parameters:
currency: currency id of the withdraw
account: address of the account where the withdraw was made
value: amount of tokens withdrawn

Liquidate

Notice of a successful liquidation. msg.sender will be the liquidator.
Parameters:
localCurrency: currency that was liquidated
collateralCurrency: currency that was exchanged for the local currency
account: the account that was liquidated
amountRecollateralized: the amount of local currency that recollateralized

LiquidateBatch

Notice of a successful batch liquidation. msg.sender will be the liquidator.
Parameters:
localCurrency: currency that was liquidated
collateralCurrency: currency that was exchanged for the local currency
accounts: the accounts that were liquidated
amountRecollateralized: the amount of local currency that recollateralized

SettleCash

Notice of a successful cash settlement. msg.sender will be the settler.
Parameters:
localCurrency: currency that was settled
collateralCurrency: currency that was exchanged for the local currency
payer: the account that paid in the settlement
settledAmount: the amount settled between the parties

SettleCashBatch

Notice of a successful batch cash settlement. msg.sender will be the settler.
Parameters:
localCurrency: currency that was settled
collateralCurrency: currency that was exchanged for the local currency
payers: the accounts that paid in the settlement
settledAmounts: the amounts settled between the parties

SetDiscounts

Emitted when liquidation and settlement discounts are set
Parameters:
liquidationDiscount: discount given to liquidators when purchasing collateral
settlementDiscount: discount given to settlers when purchasing collateral
repoIncentive: incentive given to liquidators for pulling liquidity tokens to recollateralize an account

SetReserve

Emitted when reserve account is set
Parameters:
reserveAccount: account that holds balances in reserve

Governance Methods

setDiscounts

Sets discounts applied when purchasing collateral during liquidation or settlement. Discounts are represented as percentages multiplied by 1e18. For example, a 5% discount for liquidators will be set as 1.05e18
Parameters:
liquidation: discount applied to liquidation
settlement: discount applied to settlement
repoIncentive: incentive to repo liquidity tokens

setReserveAccount

Sets the reserve account used to settle against for insolvent accounts
Parameters:
account: address of reserve account

listCurrency

Lists a new currency for deposits
Parameters:
token: address of ERC20 or ERC777 token to list
options: a set of booleans that describe the token

addExchangeRate

Creates an exchange rate between two currencies.
Parameters:
base: the base currency
quote: the quote currency
rateOracle: the oracle that will give the exchange rate between the two
buffer: multiple to apply to the exchange rate that sets the collateralization ratio
rateDecimals: decimals of precision that the rate oracle uses
mustInvert: true if the chainlink oracle must be inverted

PreviousERC1155 Trade NextPortfolios

Last updated 3 years ago

Was this helpful?