> For the complete documentation index, see [llms.txt](https://docs.notional.finance/developers/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.notional.finance/developers/smart-contract-documentation/escrow.md). # Escrow ## Escrow Manages a account balances for the entire system including deposits, withdraws, cash balances, collateral lockup for trading, cash transfers (settlement), and liquidation. ### Methods * [isValidCurrency(uint16 currency)](#isValidCurrency) * [getExchangeRate(uint16 base, uint16 quote)](#getExchangeRate) * [getBalances(address account)](#getBalances) * [convertBalancesToETH(int256\[\] amounts)](#convertBalancesToETH) * [depositEth()](#depositEth) * [withdrawEth(uint128 amount)](#withdrawEth) * [deposit(address token, uint128 amount)](#deposit) * [withdraw(address token, uint128 amount)](#withdraw) * [settleCashBalanceBatch(uint16 localCurrency, uint16 collateralCurrency, address\[\] payers, uint128\[\] values)](#settleCashBalanceBatch) * [settleCashBalance(uint16 localCurrency, uint16 collateralCurrency, address payer, uint128 value)](#settleCashBalance) * [liquidateBatch(address\[\] accounts, uint16 localCurrency, uint16 collateralCurrency)](#liquidateBatch) * [liquidate(address account, uint16 localCurrency, uint16 collateralCurrency)](#liquidate) * [settlefCash(address payer, uint16 localCurrency, uint16 collateralCurrency, uint128 valueToSettle)](#settlefCash) * [liquidatefCash(address payer, uint16 localCurrency, uint16 collateralCurrency)](#liquidatefCash) * [settleReserve(address account, uint16 localCurrency)](#settleReserve) ### Events * [NewCurrency(address token)](#NewCurrency) * [UpdateExchangeRate(uint16 base, uint16 quote)](#UpdateExchangeRate) * [Deposit(uint16 currency, address account, uint256 value)](#Deposit) * [Withdraw(uint16 currency, address account, uint256 value)](#Withdraw) * [Liquidate(uint16 localCurrency, uint16 collateralCurrency, address account, uint128 amountRecollateralized)](#Liquidate) * [LiquidateBatch(uint16 localCurrency, uint16 collateralCurrency, address\[\] accounts, uint128\[\] amountRecollateralized)](#LiquidateBatch) * [SettleCash(uint16 localCurrency, uint16 collateralCurrency, address payer, uint128 settledAmount)](#SettleCash) * [SettleCashBatch(uint16 localCurrency, uint16 collateralCurrency, address\[\] payers, uint128\[\] settledAmounts)](#SettleCashBatch) * [SetDiscounts(uint128 liquidationDiscount, uint128 settlementDiscount, uint128 repoIncentive)](#SetDiscounts) * [SetReserve(address reserveAccount)](#SetReserve) ### Governance Methods * [setDiscounts(uint128 liquidation, uint128 settlement, uint128 repoIncentive)](#setDiscounts) * [setReserveAccount(address account)](#setReserveAccount) * [listCurrency(address token, struct EscrowStorage.TokenOptions options)](#listCurrency) * [addExchangeRate(uint16 base, uint16 quote, address rateOracle, uint128 buffer, uint128 rateDecimals, bool mustInvert)](#addExchangeRate) ## 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 --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.notional.finance/developers/smart-contract-documentation/escrow.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.