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.

Getters for Accounts

getAccountPar

Description:

Get the principal value for a particular account and market.

Parameters:

• account (Account.Info calldata): The account to query, represented by an Account.Info struct.

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

getAccountWei

Description:

Get the token balance for a particular account and market.

Parameters:

• account (Account.Info calldata): The account to query, represented by an Account.Info struct.

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

getAccountStatus

Description:

Get the status of an account (Normal, Liquidating, or Vaporizing).

Parameters:

• account (Account.Info calldata): The account to query, represented by an Account.Info struct.

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);

getAccountMarketsWithBalances

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 an Account.Info struct.

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);

getAccountNumberOfMarketsWithBalances

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 an Account.Info struct.

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);

getAccountMarketWithBalanceAtIndex

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 an Account.Info struct.

• index (uint256): The index to query. Must be less than the value returned from getAccountNumberOfMarketsWithBalances

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);

getAccountNumberOfMarketsWithDebt

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 an Account.Info struct.

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);

getAccountValues

Description:

Get the total supplied and total borrowed value of an account.

Parameters:

• account (Account.Info calldata): The account to query, represented by an Account.Info struct.

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 of 123450000000000000000000000000000000000 is 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 of 123450000000000000000000000000000000000 is 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);

getAdjustedAccountValues

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 an Account.Info struct.

Returns:

• A tuple containing the following values:

  • Monetary.Value memory supplied: A struct containing the supplied value of the account (adjusted for marginPremium). Has 36 decimals of precision. Meaning, a value of 123450000000000000000000000000000000000 is equal to $123.45.

  • Monetary.Value memory borrowed: A struct containing the borrowed value of the account (adjusted for marginPremium). Has 36 decimals of precision. Meaning, a value of 123450000000000000000000000000000000000 is 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);

getAccountBalances

Description:

Get an account's summary for each market.

Parameters:

• account (Account.Info calldata): The account to query, represented by an Account.Info struct.

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 of Types.Par structs representing the account's principal value for each market.

  • Types.Wei[] memory: An array of Types.Wei structs 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);

Getters for Markets

getMarketIdByTokenAddress

Get the ERC20 token address for a market.

Parameters

• token (address): The token to query.

Returns

• uint256: The token's marketId if the token is valid.

Function Signature

function getMarketIdByTokenAddress(address token) external view returns (uint256);

getMarketTokenAddress

Get the ERC20 token address for a market.

Parameters

• marketId (uint256): The market to query.

Returns

• address: The token address associated with the given marketId. Reverts if the provided marketId is invalid

Function Signature

function getMarketTokenAddress(uint256 marketId) external view returns (address);

getMarketIsClosing

Return true if a particular market is in closing mode. Additional borrows cannot be taken from a market that is closing.

Parameters

• marketId (uint256): The market to query.

Returns

• bool: true if the market is closing, otherwise false.

Function Signature:

function getMarketIsClosing(uint256 marketId) external view returns (bool);

getMarketPrice

Get the price of the token for a market.

Parameters

• marketId (uint256): The market to query.

Returns

• Monetary.Price memory: A struct containing the price of the token in USD. The number of decimals used to represent this number is 36 - token.decimals. Meaning, the USD price for USDC has 30 decimals. This ensures that numbers are standardized to 36 decimals when representing monetary value.

Function Signature:

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);

getNumMarkets

Description:

Get the total number of markets.

Returns:

• uint256: The number of markets.

Function Signature:

function getNumMarkets() external;

getMarketTotalPar

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:

library Types {
    struct TotalPar {
        uint128 borrow;
        uint128 supply;
    }
}

function getMarketTotalPar(uint256 marketId) external view returns (Types.TotalPar memory);

getMarketTotalWei

This function is not available on Arbitrum

Description:

Get the total wei amounts (borrowed and supplied) for a market.

Parameters:

• marketId (uint256): The market to query.

Returns:

• Types.TotalWei memory: A struct containing the total principal amounts (borrowed and supplied) for the specified market.

Function Signature:

library Types {
    struct TotalWei {
        uint128 borrow;
        uint128 supply;
    }
}

function getMarketTotalWei(uint256 marketId) external view returns (Types.TotalWei memory);

getMarketCachedIndex

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);

getMarketCurrentIndex

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);

getMarketPriceOracle

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);

getMarketInterestSetter

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);

getMarketMarginPremium

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);

getMarketSpreadPremium

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);

getMarketMaxWei

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);

getMarketMaxSupplyWei

This function is not available on Arbitrum

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 getMarketMaxSupplyWei(uint256 marketId) external view returns (Types.Wei memory);

getMarketMaxBorrowWei

This function is not available on Arbitrum

Description:

Get the maximum borrow 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 getMarketMaxBorrowWei(uint256 marketId) external view returns (Types.Wei memory);

getMarketInterestRate

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 of 3,170,979,198 denotes 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);

getMarket

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);

getMarketWithInfo

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);

Getters for Permissions

getIsLocalOperator

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: true if the operator is approved for the owner's accounts, false otherwise.

Function Signature:

function getIsLocalOperator(address owner, address operator) external view returns (bool);

getIsGlobalOperator

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: true if the operator is a global operator, false otherwise.

Function Signature:

function getIsGlobalOperator(address operator) external view returns (bool);

getIsAutoTraderSpecial

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: true if the autoTrader can only be invoked by a global operator, false otherwise.

Function Signature:

function getIsAutoTraderSpecial(address autoTrader) external view returns (bool);

owner

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);

Getters for Risk Params

getMarginRatio

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 of 150000000000000000 equals 15%. The protocol uses this number as 1 + margin-ratio, so in the prior example, the returned result would mean 115% minimum collateralization (or 86.9565% LTV)

Function Signature:

library Decimal {
    struct D256 {
        uint256 value;
    }
}

function getMarginRatio() external view returns (Decimal.D256 memory);

getMarginRatioForAccount

This function is not available on Arbitrum

Description:

Get the global minimum margin-ratio that every position must maintain to prevent being liquidated.

Params:

• Account.Info memory: The account whose margin ratio is being queried. This is used to determine if there is an override that supercedes the default value in getMarginRatio.

Returns:

• Decimal.D256 memory: A struct representing the global margin-ratio. Has 18 decimals of precision, meaning a value of 150000000000000000 equals 15%. The protocol uses this number as 1 + margin-ratio, so in the prior example, the returned result would mean 115% minimum collateralization (or 86.9565% LTV)

Function Signature:

library Account {
    struct Info {
        address owner;
        uint256 number;
    }
}

library Decimal {
    struct D256 {
        uint256 value;
    }
}

function getMarginRatioForAccount(
    Account.Info memory account
) external view returns (Decimal.D256 memory);

getLiquidationSpread

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 of 50000000000000000 is equal to 5%.

Function Signature:

library Decimal {
    struct D256 {
        uint256 value;
    }
}

function getLiquidationSpread() external view returns (Decimal.D256 memory);

getLiquidationSpreadForPair

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 of 75000000000000000 is equal to 7.5%.

Function Signature:

library Decimal {
    struct D256 {
        uint256 value;
    }
}

function getLiquidationSpreadForPair(uint256 heldMarketId, uint256 owedMarketId) external view returns (Decimal.D256 memory);

getLiquidationSpreadForAccountAndPair

This function is not available on Arbitrum

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:

• Account.Info memory: The account whose liquidation spread is being queried. This is used to determine if there is an override that supercedes the default value in getLiquidationSpread.

• 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 of 75000000000000000 is equal to 7.5%.

Function Signature:

library Account {
    struct Info {
        address owner;
        uint256 number;
    }
}

library Decimal {
    struct D256 {
        uint256 value;
    }
}

function getLiquidationSpreadForAccountAndPair(
    Account.Info calldata account,
    uint256 heldMarketId,
    uint256 owedMarketId
) external view;

getEarningsRate

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 of 850000000000000000 is 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);

getMinBorrowedValue

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 of 0 means there is no minimum. Has 36 decimals of precision, meaning a value of 100000000000000000000000000000000000000 denotes $100.

Function Signature:

library Monetary {
    struct Value {
        uint256 value; // 36 decimals of precision
    }
}

function getMinBorrowedValue() external view returns (Monetary.Value memory);

getRiskParams

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;
    }
}

function getRiskParams() external view returns (Storage.RiskParams memory);

getRiskLimits

Description:

Get all global risk parameter limits in a single struct. These are the maximum limits at which the risk parameters can be set by the admin of DolomiteMargin. These values are immutable and cannot change after DolomiteMargin is initialized.

Returns:

• Storage.RiskLimits memory: A struct representing all global risk parameter limits.

Function Signature:

library Storage {
    struct RiskLimits {
        uint64 marginRatioMax;
        uint64 liquidationSpreadMax;
        uint64 earningsRateMax;
        uint64 marginPremiumMax;
        uint64 spreadPremiumMax;
        uint128 minBorrowedValueMax;
    }
}

function getRiskLimits() external view returns (Storage.RiskLimits memory);

getDefaultAccountRiskOverrideSetter

Description:

Get the account risk override setter for global use. This contract enables E-Mode and granular risk control over positions.

Returns:

• IDolomiteAccountRiskOverrideSetter: An address pointing to the risk override setter contract.

Function Signature:

function getDefaultAccountRiskOverrideSetter() external view returns (IDolomiteAccountRiskOverrideSetter);