Protocol Reader
Overview
ProtocolReader is a comprehensive auxiliary contract designed for efficiently querying data from the Curvance ecosystem. It serves as the primary interface for data aggregators, frontends, and external systems to retrieve protocol information with minimal RPC calls.
Key Features
Data Consolidation: Consolidates multiple variable fetches into single view functions, significantly reducing the number of EVM calls needed for comprehensive protocol queries.
Pure View Interface: Contains no active storage values beyond immutable configuration and consists entirely of view functions, making it seamlessly upgradeable to support new data formats or query requirements.
Comprehensive Data Access: Provides three main categories of data:
Static Market Data: Token configurations, collateral requirements, liquidation parameters.
Dynamic Market Data: Real-time prices, interest rates, utilization rates, liquidity levels.
User Data: Individual positions, collateral balances, debt positions, and veCVE locks.
User Interaction Functions
Data Aggregation
getAllDynamicState()
Description: Returns both real-time market data across all markets and comprehensive user position data in a single call. It combines getDynamicMarketData() (current prices, interest rates, liquidity) with getUserData() (user's positions,
collateral, debt, veCVE locks) to minimize RPC calls for frontend dashboards.
Function signature:
function getAllDynamicState(
address account
) public view returns (
DynamicMarketData[] memory market,
UserData memory user
);address
account
The address of the account to get market data for.
Return data:
DynamicMarketData[]
Real-time market information including current prices, interest rates, liquidity, and utilization for all tokens across all markets.
UserData
The user's veCVE locks and position data across all markets including collateral, debt, health, and token balances.
getStaticMarketData()
Description: Returns immutable configuration data for all markets including token details, collateral requirements, debt caps, liquidation parameters, and oracle adapter types.
Function signature:
function getStaticMarketData() public view returns (StaticMarketData[] memory data);Return data:
StaticMarketData[]
The address of the MarketManager, unique oracle adaptors, the market's cooldown length and tokens involved in the market.
getDynamicMarketData()
Description: Returns real-time data for all markets
Function signature:
function getDynamicMarketData() public view returns (DynamicMarketData[] memory data)Return data:
DynamicMarketData[]
Real-time market information including current prices, interest rates, liquidity, and utilization for all tokens across all markets.
getUserData()
Description: Returns the current outstanding borrows across all Curvance markets.
Function signature:
function getUserData(address account) public view returns (UserData memory data)Return data:
uint256
The current outstanding borrows inside Curvance, in WAD (18 decimals)
Price Oracle
getPrice()
Description:
Function signature:
function getPrice(
address asset,
bool inUSD,
bool getLower)
public view returns(
uint256 price,
uint256 errorCode
);address
asset
Asset address to get prices for
bool
inUSD
Boolean whether to return prices in USD or the native token
bool
getLower
Boolean indicating whether to get the lower or higher price
Return data:
uint256
Asset price in WAD ($1 = 1e18)
uint256
The reported error code, 0 if there is no error, 1 if there's a moderate oracle issue that blocks new borrowing, or 2 if there's a severe oracle issue that pauses all actions involving that asset.
getPriceSafely()
Description:
Function signature:
function getPriceSafely(
address asset,
bool inUSD,
bool getLower,
uint256 errorCodeBreakpoint
) public view returns (uint256);address
asset
Asset address to get prices for
bool
inUSD
Boolean whether to return prices in USD or the native token
bool
getLower
Boolean indicating whether to get the lower or higher price
uint256
errorCodeBreakpoint
The minimum error code threshold that causes the function to revert - set to 1 to revert on any oracle issues, 2 to only revert on severe issues, or 3+ to never revert.
Return data:
uint256
Asset price in WAD ($1 = 1e18)
Position Health & Risk Assessment
hypotheticalRedemptionOf()
Description: Determine what the account liquidity would be if the given shares were redeemed.
Function signature:
function hypotheticalRedemptionOf(
address account,
address cTokenModified,
uint256 redemptionShares,
uint256 bufferTime
) public view returns (uint256, uint256, bool, bool) {address
account
The account to determine liquidity for.
address
cTokenModified
The address of the market token
uint256
redemptionShares
The number of shares to hypothetically redeem.
uint256 bu
bufferTime
Any additional time buffer debt accrual is expected before a user's action, in seconds.
Return data:
uint256
Hypothetical account liquidity in excess of collateral requirements.
uint256
Hypothetical account liquidity deficit below collateral requirements.
bool
The amount of collateral posted or debt owed by the account.
bool
Whether an error code was hit.
maxRedemptionOf()
Description: Determine the maximum amount of cTokenRedeemed that account can redeem.
Function signature:
function maxRedemptionOf(
address account,
address cTokenRedeemed,
uint256 bufferTime
) public view returns (
uint256 collateralizedSharesRedeemable,
uint256 uncollateralizedShares,
bool errorHit
);address
account
The account to determine redemptions for.
address
cTokenRedeemed
The cToken to redeem.
uint256
bufferTime
Any additional time buffer debt accrual is expected before a user's action, in seconds.
Return data:
uint256
The amount of collateralized cTokenModified shares redeemable by account.
uint256
The amount of uncollateralized cTokenModified shares redeemable by account.
bool
Whether an error code was hit.
debtBalanceAtTimestamp()
Description: Returns the debt balance of account at timestamp.
Function signature:
function debtBalanceAtTimestamp(
address account,
address borrowableCToken,
uint256 timestamp
) public view returns (uint256 debtBalance);address
account
The address whose debt balance should be calculated.
address
borrowableCToken
The token that account's debt balance will be checked for.
uint256
timestamp
The unix timestamp to calculate account debt balance with.
Return data:
uint256
The debt balance of account at timestamp.
Hypothetical Simulation Functions
hypotheticalRedemptionOf()
Description: Determine what the account liquidity would be if the given shares were redeemed.
Function signature:
function hypotheticalRedemptionOf(
address account,
address cTokenModified,
uint256 redemptionShares
) public view returns (uint256, uint256, bool, bool)address
account
The account to determine liquidity for.
address
cTokenModified
The cToken to hypothetically redeem.
uint256
redemptionShares
The number of shares to hypothetically redeem.
Return data:
uint256
Hypothetical account liquidity in excess of collateral requirements.
uint256
Hypothetical account liquidity deficit below collateral requirements.
bool
Whether the proposed action is not possible. NOT whether it passes liquidity constraints or not.
bool
Whether an error code was hit or not.
hypotheticalBorrowOf()
Description: Determine what the account liquidity would be if the given assets were borrowed.
Function signature:
function hypotheticalBorrowOf(
address account,
address borrowableCTokenModified,
uint256 borrowAssets
) public view returns (uint256, uint256, bool, bool, bool)address
account
The account to determine liquidity for.
address
borrowableCTokenModified
The borrowableCToken to hypothetically borrow.
uint256
borrowAssets
The number of assets to hypothetically borrow.
Return data:
uint256
Hypothetical account liquidity in excess of collateral requirements.
uint256
Hypothetical account liquidity deficit below collateral requirements.
bool
Whether the proposed action is possible. NOT whether it passes liquidity constraints or not.
bool
Whether the desired loan size is insufficient causing an error.
bool
Whether an error code was hit or not.
hypotheticalLeverageOf()
Description: Calculates the hypothetical maximum amount of borrowableCToken assets account can borrow for maximum leverage based on a new cToken collateralized deposit.
Function signature:
function hypotheticalLeverageOf(
address account,
address cToken,
address borrowableCToken,
uint256 assets,
uint256 bufferTime
) public view returns (
uint256 currentLeverage,
uint256 adjustedMaxLeverage,
uint256 maxLeverage,
uint256 maxDebtBorrowable,
bool loanSizeError,
bool oracleError
)address
account
The account to query maximum borrow amount for.
address
cToken
The token that account will deposit to leverage against.
address
borrowableCToken
The token that account will borrow assets from to achieve leverage.
uint256
assets
The amount of cToken underlying that account will deposit to leverage against.
uint256
bufferTime
Any additional time buffer debt accrual is expected before a user's action, in seconds.
Return data:
uint256
Returns the current leverage multiplier of account, in WAD.
uint256
Returns the maximum leverage multiplier of account after a hypothetical deposit action, adjusted by liquidity constraints, in WAD.
uint256
Returns the maximum leverage multiplier of account after a hypothetical deposit action, in WAD.
uint256
Returns the maximum remaining borrow amount allowed from borrowableCToken, measured in underlying token amount, after the new hypothetical deposit.
bool
Whether the desired loan size is insufficient causing an error.
bool
Whether an oracle error was hit when pricing assets.
Market Analysis Functions
marketMultiCooldown()
Description: Returns the cooldown periods for multiple markets for a user.
Function signature:
function marketMultiCooldown(
address[] calldata markets,
address user
) public view returns (uint256[] memory)address[]
markets
The list of market addresses.
address
user
The user address.
Return data:
uint256[]
The list of cooldown periods for each market.
previewAssetImpact()
Description: Returns the outstanding underlying tokens borrowed from an EToken market.
Function signature:
function previewAssetImpact(
address user,
address collateralCToken,
address debtBorrowableCToken,
uint256 newCollateralAssets,
uint256 newDebtAssets
) public view returns (uint256 supply, uint256 borrow);address
user
The address of the user account to preview asset impact of.
address
collateralCToken
The address of the collateral cToken.
address
debtBorrowableCToken
The address of the debt borrowable cToken.
uint256
newCollateralAssets
The amount of new collateral asset to deposit, in assets.
uint256
newDebtAssets
The amount of new debt asset to borrow, in assets.
Return data:
uint256
The projected supply rate, in WAD seconds.
uint256
The projected borrow amount, in WAD seconds.
Last updated