Comment on page
Dolomite Margin - Getters
Dolomite Margin has an extensive list of functions you can use to query the smart contract's state.
These functions are callable on instances of DolomiteMargin on each network Dolomite is deployed. See smart contract addresses to discover the address of DolomiteMargin on each network.
Description:
Get the principal value for a particular account and market.
Parameters:
account(Account.Info calldata): The account to query, represented by anAccount.Infostruct.marketId(uint256): The market to query.
Returns:
Types.Par memory: A struct containing the principal value for the specified account and market.
Function Signature:
library Account {
// Represents the unique key that specifies an account
struct Info {
address owner; // The address that owns the account
uint256 number; // A nonce that allows a single address to control many accounts
}
}
library Types {
struct Par {
bool sign; // true if positive
uint128 value;
}
}
function getAccountPar(Account.Info calldata account, uint256 marketId) external view returns (Types.Par memory);
Description:
Get the token balance for a particular account and market.
Parameters:
account(Account.Info calldata): The account to query, represented by anAccount.Infostruct.marketId(uint256): The market to query.
Returns:
Types.Wei memory: A struct containing the token balance for the specified account and market.
Function Signature:
library Account {
// Represents the unique key that specifies an account
struct Info {
address owner; // The address that owns the account
uint256 number; // A nonce that allows a single address to control many accounts
}
}
library Types {
struct Wei {
bool sign; // true if positive
uint128 value;
}
}
function getAccountWei(Account.Info calldata account, uint256 marketId) external view returns (Types.Wei memory);
Description:
Get the status of an account (Normal, Liquidating, or Vaporizing).
Parameters:
account(Account.Info calldata): The account to query, represented by anAccount.Infostruct.
Returns:
Account.Status: An enumeration value representing the account's status.
Function Signature:
library Account {
struct Info {
address owner;
uint256 number;
}
enum Status {
Normal,
Liquid,
Vapor
}
}
function getAccountStatus(Account.Info calldata account) external view returns (Account.Status);
Description:
Get a list of markets that have a non-zero balance for an account.
Parameters:
account(Account.Info calldata): The account to query, represented by anAccount.Infostruct.
Returns:
uint256[] memory: An array of marketIds representing the markets with non-zero balances for the account.
Function Signature:
library Account {
struct Info {
address owner;
uint256 number;
}
}
function getAccountMarketsWithBalances(Account.Info calldata account) external view returns (uint256[] memory);
Description:
Get the number of markets that have a non-zero balance for an account.
Parameters:
account(Account.Info calldata): The account to query, represented by anAccount.Infostruct.
Returns:
uint256: The number of markets with non-zero balances for the account.
Function Signature:
library Account {
struct Info {
address owner;
uint256 number;
}
}
function getAccountNumberOfMarketsWithBalances(Account.Info calldata account) external view returns (uint256);
Description:
Get the marketId for an account's market with a non-zero balance at the given index.
Parameters:
account(Account.Info calldata): The account to query, represented by anAccount.Infostruct.index(uint256): The index to query. Must be less than the value returned fromgetAccountNumberOfMarketsWithBalances
Returns:
uint256: The marketId for the account's market with a non-zero balance at the specified index.
Function Signature:
library Account {
struct Info {
address owner;
uint256 number;
}
}
function getAccountMarketWithBalanceAtIndex(Account.Info calldata account, uint256 index) external view returns (uint256);
Description:
Get the number of markets with which an account has a negative balance.
Parameters:
account(Account.Info calldata): The account to query, represented by anAccount.Infostruct.
Returns:
uint256: The number of markets with which the account has a negative balance.
Function Signature:
library Account {
struct Info {
address owner;
uint256 number;
}
}
function getAccountNumberOfMarketsWithDebt(Account.Info calldata account) external view returns (uint256);
Description:
Get the total supplied and total borrowed value of an account.
Parameters:
account(Account.Info calldata): The account to query, represented by anAccount.Infostruct.
Returns:
- A tuple containing the following values:
Monetary.Value memory supplied: A struct containing the supplied value of the account. Has 36 decimals of precision. Meaning, a value of123450000000000000000000000000000000000is equal to$123.45.Monetary.Value memory borrowed: A struct containing the borrowed value of the account. Has 36 decimals of precision. Meaning, a value of123450000000000000000000000000000000000is equal to$123.45.
Function Signature:
library Account {
struct Info {
address owner;
uint256 number;
}
}
library Monetary {
struct Value {
uint256 value; // 36 decimals of precision
}
}
function getAccountValues(Account.Info calldata account) external view returns (Monetary.Value memory supplied, Monetary.Value memory borrowed);
Description:
Get the total supplied and total borrowed values of an account adjusted by the
marginPremium of each market. Supplied values are divided by (1 + marginPremium) for each market, and borrowed values are multiplied by (1 + marginPremium) for each market. Comparing these adjusted values gives the margin-ratio of the account, which will be compared to the global margin-ratio when determining if the account can be liquidated.Parameters:
account(Account.Info calldata): The account to query, represented by anAccount.Infostruct.
Returns:
- A tuple containing the following values:
Monetary.Value memory supplied: A struct containing the supplied value of the account (adjusted formarginPremium). Has 36 decimals of precision. Meaning, a value of123450000000000000000000000000000000000is equal to$123.45.Monetary.Value memory borrowed: A struct containing the borrowed value of the account (adjusted formarginPremium). Has 36 decimals of precision. Meaning, a value of123450000000000000000000000000000000000is equal to$123.45.
library Account {
struct Info {
address owner;
uint256 number;
}
}
library Monetary {
struct Value {
uint256 value; // 36 decimals of precision
}
}
function getAdjustedAccountValues(Account.Info calldata account) external view returns (Monetary.Value memory, Monetary.Value memory);
Description:
Get an account's summary for each market.
Parameters:
account(Account.Info calldata): The account to query, represented by anAccount.Infostruct.
Returns:
- A tuple containing the following values:
uint[] memory: An array of market IDs for each market.address[] memory: An array of ERC20 token addresses for each market.Types.Par[] memory: An array ofTypes.Parstructs representing the account's principal value for each market.Types.Wei[] memory: An array ofTypes.Weistructs representing the account's real (supplied or borrowed) number of tokens for each market.
Function Signature:
library Account {
struct Info {
address owner;
uint256 number;
}
}
library Types {
struct Par {
bool sign; // true if positive
uint128 value;
}
struct Wei {
bool sign; // true if positive
uint256 value;
}
}
function getAccountBalances(Account.Info calldata account) external view returns (uint[] memory, address[] memory, Types.Par[] memory, Types.Wei[] memory);
Get the ERC20 token address for a market.
token(address): The token to query.
uint256: The token'smarketIdif the token is valid.
function getMarketIdByTokenAddress(address token) external view returns (uint256);
Get the ERC20 token address for a market.
marketId(uint256): The market to query.
address: The token address associated with the givenmarketId. Reverts if the providedmarketIdis invalid
function getMarketTokenAddress(uint256 marketId) external view returns (address);
Return
true if a particular market is in closing mode. Additional borrows cannot be taken from a market that is closing.marketId(uint256): The market to query.
bool:trueif the market is closing, otherwisefalse.
function getMarketIsClosing(uint256 marketId) external view returns (bool);
Get the price of the token for a market.
marketId(uint256): The market to query.
Monetary.Price memory: A struct containing the price of the token in USD. The number of decimals used to represent this number is36 - token.decimals. Meaning, the USD price for USDC has30decimals. This ensures that numbers are standardized to 36 decimals when representing monetary value.
library Monetary {
/*
* The price of a base-unit of an asset. Has `36 - token.decimals` decimals
*/
struct Price {
uint256 value;
}
}
function getMarketPrice(uint256 marketId) external view returns (Monetary.Price memory);
Description:
Get the total number of markets.
Returns:
uint256: The number of markets.
Function Signature:
function getNumMarkets() external;
Description:
Get the total principal amounts (borrowed and supplied) for a market.
Parameters:
marketId(uint256): The market to query.
Returns:
Types.TotalPar memory: A struct containing the total principal amounts (borrowed and supplied) for the specified market.
Function Signature:
function getMarketTotalPar(uint256 marketId) external view returns (Types.TotalPar memory);
Description:
Get the most recently cached interest index for a market. The
Interest.Index struct is used to convert between Par (scaled) and Wei (real) values.Parameters:
marketId(uint256): The market to query.
Returns:
Interest.Index memory: A struct containing the most recent interest index for the specified market.
Function Signature:
library Interest {
struct Index {
uint96 borrow;
uint96 supply;
uint32 lastUpdate;
}
}
function getMarketCachedIndex(uint256 marketId) external view returns (Interest.Index memory);
Description:
Get the interest index for a market if it were to be updated right now at the current
block.timestamp.Parameters:
marketId(uint256): The market to query.
Returns:
Interest.Index memory: A struct containing the estimated current interest index for the specified market.
Function Signature:
library Interest {
struct Index {
uint96 borrow;
uint96 supply;
uint32 lastUpdate;
}
}
function getMarketCurrentIndex(uint256 marketId) external view returns (Interest.Index memory);
Description:
Get the price oracle address for a market.
Parameters:
marketId(uint256): The market to query.
Returns:
IPriceOracle: The address of the price oracle associated with the specified market.
Function Signature:
function getMarketPriceOracle(uint256 marketId) external view returns (IPriceOracle);
Description:
Get the interest-setter address for a market.
Parameters:
marketId(uint256): The market to query.
Returns:
IInterestSetter: The address of the interest-setter associated with the specified market.
Function Signature:
function getMarketInterestSetter(uint256 marketId) external view returns (IInterestSetter);
Description:
Get the margin premium for a market. A margin premium makes it so that any positions that include the market require a higher collateralization to avoid being liquidated.
Parameters:
marketId(uint256): The market to query.
Returns:
Decimal.D256 memory: A struct containing the margin premium for the specified market. Decimals are scaled to have 18 decimals of precision. Meaning a value of 1e16 (10000000000000000) is equal to 0.01.
Function Signature:
library Decimal {
struct D256 {
uint256 value;
}
}
function getMarketMarginPremium(uint256 marketId) external view returns (Decimal.D256 memory);
Description:
Get the liquidation spread premium for a market. A spread premium makes it so that any liquidations that include the market have a higher spread than the global default.
Parameters:
marketId(uint256): The market to query.
Returns:
Decimal.D256 memory: A struct containing the spread premium for the specified market.
Function Signature:
library Decimal {
struct D256 {
uint256 value;
}
}
function getMarketSpreadPremium(uint256 marketId) external view returns (Decimal.D256 memory);
Description:
Get the maximum supply Wei for a given market. A value of
0 denotes there being no maximum.Parameters:
marketId(uint256): The market to query.
Returns:
Types.Wei memory: A struct containing the maximum supply Wei allowed for the specified market.
Function Signature:
library Types {
struct Wei {
bool sign; // true if positive; can be false OR true if value == 0
uint256 value;
}
}
function getMarketMaxWei(uint256 marketId) external view returns (Types.Wei memory);
Description:
Get the current borrower interest rate for a market.
Parameters:
marketId(uint256): The market to query.
Returns:
Interest.Rate memory: A struct containing the current interest rate for borrowers in the specified market. Interest rates are denoted as percentage-per-second. So a value of3,170,979,198denotes an interest rate of ~10%, which is calculated using the following formula:
0.10 OR 10% = (
3,170,979,198 interest per second
* 86,400 seconds per day
* 365 days per year
) / 10 ** 18;
Function Signature:
library Interest {
struct Rate {
uint256 value;
}
}
function getMarketInterestRate(uint256 marketId) external view returns (Interest.Rate memory);
Description:
Get basic information about a particular market.
Parameters:
marketId(uint256): The market to query.
Returns:
Storage.Market memory: A struct containing the current state of the specified market.
Function Signature:
library Storage {
struct Market {
address token;
bool isClosing;
bool isRecyclable;
Types.TotalPar totalPar;
Interest.Index index;
IPriceOracle priceOracle;
IInterestSetter interestSetter;
Decimal.D256 marginPremium;
Decimal.D256 spreadPremium;
Types.Wei maxWei;
}
}
function getMarket(uint256 marketId) external view returns (Storage.Market memory);
Description:
Get comprehensive information about a particular market.
Parameters:
marketId(uint256): The market to query.
Returns:
- A tuple containing the values:
Storage.Market memory: A struct containing the current state of the market.Interest.Index memory: A struct containing the current estimated interest index.Monetary.Price memory: A struct containing the current token price.Interest.Rate memory: A struct containing the current market interest rate.
Function Signature:
library Storage {
struct Market {
address token;
bool isClosing;
bool isRecyclable;
Types.TotalPar totalPar;
Interest.Index index;
IPriceOracle priceOracle;
IInterestSetter interestSetter;
Decimal.D256 marginPremium;
Decimal.D256 spreadPremium;
Types.Wei maxWei;
}
}
library Interest {
struct Index {
uint96 borrow; // 18 decimals
uint96 supply; // 18 decimals
uint32 lastUpdate;
}
struct Rate {
uint256 value; // interest per second, measured with 18 decimals
}
}
library Monetary {
/*
* The price of a base-unit of an asset. Has `36 - token.decimals` decimals
*/
struct Price {
uint256 value;
}
}
function getMarketWithInfo(uint256 marketId) external view returns (Storage.Market memory, Interest.Index memory, Monetary.Price memory, Interest.Rate memory);
Description:
Return
true if a particular address is approved as an operator for an owner's accounts. Approved operators can act on the accounts of the owner as if it were the operator's own.Parameters:
owner(address): The owner of the accounts.operator(address): The possible operator.
Returns:
bool:trueif the operator is approved for the owner's accounts,falseotherwise.
Function Signature:
function getIsLocalOperator(address owner, address operator) external view returns (bool);
Description:
Return
true if a particular address is approved as a global operator. Such an address can act on any account as if it were the operator's own.Parameters:
operator(address): The address to query.
Returns:
bool:trueif the operator is a global operator,falseotherwise.
Function Signature:
function getIsGlobalOperator(address operator) external view returns (bool);
Description:
Checks if the
autoTrader can only be invoked by a global operator.Parameters:
autoTrader(address): The trader that should be checked for special call privileges.
Returns:
bool:trueif theautoTradercan only be invoked by a global operator,falseotherwise.
Function Signature:
function getIsAutoTraderSpecial(address autoTrader) external view returns (bool);
Description:
Returns the address of the current owner of DolomiteMargin.
Returns:
address: The address of the current owner.
Function Signature:
function owner() external view returns (address);
Description:
Get the global minimum margin-ratio that every position must maintain to prevent being liquidated.
Returns:
Decimal.D256 memory: A struct representing the global margin-ratio. Has 18 decimals of precision, meaning a value of150000000000000000equals 15%. The protocol uses this number as1 + margin-ratio, so in the prior example, the returned result would mean115%minimum collateralization (or86.9565%LTV)
Function Signature:
library Decimal {
struct D256 {
uint256 value;
}
}
function getMarginRatio() external view returns (Decimal.D256 memory);
Description:
Get the global liquidation spread. This is the spread between oracle prices that is used to incentivize the liquidation of risky positions.
Returns:
Decimal.D256 memory: A struct representing the global liquidation spread. Has 18 decimals of precision. Meaning, a value of50000000000000000is equal to 5%.
Function Signature:
library Decimal {
struct D256 {
uint256 value;
}
}
function getLiquidationSpread() external view returns (Decimal.D256 memory);
Description:
Get the adjusted liquidation spread for a specific market pair. This is equal to the global liquidation spread multiplied by
(1 + spreadPremium) for each of the two markets.Parameters:
heldMarketId(uint256): The market for which the account has collateral.owedMarketId(uint256): The market for which the account has borrowed tokens.
Returns:
Decimal.D256 memory: A struct representing the adjusted liquidation spread for the given market pair. Has 18 decimals of precision. Meaning, a value of75000000000000000is equal to 7.5%.
Function Signature:
library Decimal {
struct D256 {
uint256 value;
}
}
function getLiquidationSpreadForPair(uint256 heldMarketId, uint256 owedMarketId) external view returns (Decimal.D256 memory);
Description:
Get the global earnings-rate variable that determines what percentage of the interest paid by borrowers gets passed on to suppliers. The remaining percentage is paid to the protocol owner.
Returns:
Decimal.D256 memory: A struct representing the global earnings rate. Has 18 decimals of precision. Meaning, a value of850000000000000000is 85% and 85% of the borrow rate is paid to suppliers.
Function Signature:
library Decimal {
struct D256 {
uint256 value;
}
}
function getEarningsRate() external view returns (Decimal.D256 memory);
Description:
Get the global minimum-borrow value, which is the minimum value of any account's borrow position can have on DolomiteMargin.
Returns:
Monetary.Value memory: A struct representing the global minimum borrow value. A value of0means there is no minimum. Has 36 decimals of precision, meaning a value of100000000000000000000000000000000000000denotes $100.
Function Signature:
library Monetary {
struct Value {
uint256 value; // 36 decimals of precision
}
}
function getMinBorrowedValue() external view returns (Monetary.Value memory);
Description:
Get all global risk parameters in a single struct.
Returns:
Storage.RiskParams memory: A struct representing all global risk parameters.
Function Signature:
library Decimal {
struct D256 {
uint256 value;
}
}
library Monetary {
struct Value {
uint256 value; // 36 decimals of precision
}
}
library Storage {
struct RiskParams {
Decimal.D256 marginRatio;
Decimal.D256 liquidationSpread;
Decimal.D256 earningsRate;
Monetary.Value minBorrowedValue;
uint256 accountMaxNumberOfMarketsWithBalances;
}
}