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

Type	Name	Description
address	account	The address of the account to get market data for.

Return data:

Type	Description
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:

Type	Description
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:

Type	Description
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:

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

Type	Name	Description
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:

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

Type	Name	Description
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:

Type	Description
uint256	Asset price in WAD ($1 = 1e18)

Position Health & Risk Assessment

getPositionHealth()

Description: Gets the Position health of account inside a market.

Function signature:

function getPositionHealth(
    IMarketManager mm,
    address account,
    address cToken,
    address borrowableCToken,
    bool isDeposit,
    uint256 collateralAssets,
    bool isRepayment,
    uint256 debtAssets, 
    uint256 bufferTime
) public view returns (uint256 positionHealth, bool errorCodeHit) {

Type	Name	Description
IMarketManager	mm	The MarketManager to pull data from.
address	account	The address of the market token.
address	cToken	The number of shares to hypothetically redeem.
address	borrowablecToken	Any additional time buffer debt accrual is expected before a user's action, in seconds.
bool	isDeposit	Whether collateralAssets is for a deposit (true) or redemption (false).
uint256	collateralAssets	The amount of assets for a hypothetical action with cToken.
bool	isRepayment	Whether debtAssets is for a repayment (true) or a borrow (false).
uint256	debtAssets	The amount of assets for a hypothetical action with borrowableCToken
uint256	bufferTime	Any additional time buffer debt accrual is expected before a user's action, in seconds.

Return data:

Type		Description
uint256	positionHealth	The healthiness of account's position inside the market.
uint256	errorCodeHit	Whether an error code was hit or not, which would provide incorrect Position Health

---

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

Type	Name	Description
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:

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

Type	Name	Description
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:

Type	Description
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. marketMultiCooldown

Function signature:

function debtBalanceAtTimestamp(
    address account,
    address borrowableCToken,
    uint256 timestamp
) public view returns (uint256 debtBalance);

Type	Name	Description
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:

Type	Description
uint256	The debt balance of account at timestamp.

getLiquidationPrice()

Description: Determines the collateral price necessary to trigger liquidation.

Function signature:

function getLiquidationPrice(
    address account,
    address cToken,
    bool long
) public view returns (uint256 price, bool errorHit) {

Type	Name	Description
address	account	The account address to check.
address	cToken	The address of the cToken that is being used as collateral.
bool	long	If the position is long or short.

Return data:

Type		Description
uint256	price	The collateral price to liquidate.
uint256	errorCodeHit	Whether an oracle error code was hit or not.

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)

Type	Name	Description
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:

Type	Description
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)

Type	Name	Description
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:

Type	Description
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
    )

Type	Name	Description
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:

Type	Description
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)

Type	Name	Description
address[]	markets	The list of market addresses.
address	user	The user address.

Return data:

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

Type	Name	Description
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:

Type	Description
uint256	The projected supply rate, in WAD seconds.
uint256	The projected borrow amount, in WAD seconds.

---