aave_v3.reserve

Documentation for eth_defi.aave_v3.reserve Python module.

Reserve, TVL and interest data reading of pools.

• Reads Aave reserves metrics data on-chain from a certain timestamp/block number

• Relies on a lot of undocumented Aave v3 source code to pull out the data

• Based on

  • https://github.com/aave/aave-utilities

  • https://github.com/aave/aave-utilities/tree/master/packages/contract-helpers/src/v3-UiPoolDataProvider-contract

  • https://github.com/aave/aave-v3-periphery/blob/master/contracts/misc/UiPoolDataProviderV3.sol

  • https://github.com/aave/aave-ui/blob/f34f1cfc4fa6c1128b31eaa70b37b5b2109d1dc5/src/libs/pool-data-provider/hooks/use-v2-protocol-data-with-rpc.tsx#L62

  • https://github.com/aave/aave-utilities/blob/664e92b5c7710e8060d4dcac5d6c0ebb48bb069f/packages/math-utils/src/formatters/user/index.ts#L95

  • https://github.com/aave/aave-utilities/blob/664e92b5c7710e8060d4dcac5d6c0ebb48bb069f/packages/math-utils/src/formatters/reserve/index.ts#L310

Functions

fetch_aave_reserves_snapshot(web3[, ...])	Get a snapshot of all data of Aave reserves at a certain point of time.
fetch_reserve_data(contracts[, block_identifier])	Fetch data for all reserves.
fetch_reserves(contracts[, block_identifier])	Enumerate available reserves.
get_helper_contracts(web3)	Get helper contracts need to read Aave reserve data.

Classes

AggregatedReserveData	Rough mapping of AggreatedReserveData in Aave v3 Solidity source code.
BaseCurrencyInfo	Rough mapping of BaseCurrencyInfo in Aave v3 Solidity source code.
HelperContracts	Contracts needed to resolve reserve info on Aave v3.
JSONSerialisableReserveData	JSON friendly way to store Aave v3 protocol reserve status.

Exceptions

AaveContractsNotConfigured

We lack hardcoded data of Aave contract addresses for a particular chain.

exception AaveContractsNotConfigured

Bases: Exception

We lack hardcoded data of Aave contract addresses for a particular chain.

__init__(*args, **kwargs)

__new__(**kwargs)

add_note()

Exception.add_note(note) – add a note to the exception

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class HelperContracts

Bases: object

Contracts needed to resolve reserve info on Aave v3.

chain_id: int

Which EVM chain

ui_pool_data_provider: web3.contract.contract.Contract

See - https://github.com/aave/aave-v3-periphery/blob/master/contracts/misc/interfaces/IUiPoolDataProviderV3.sol - https://github.com/aave/aave-v3-periphery/blob/master/contracts/misc/UiPoolDataProviderV3.sol

pool_addresses_provider: web3.contract.contract.Contract

See https://github.com/aave/aave-v3-core/blob/27a6d5c83560694210849d4abf09a09dec8da388/contracts/interfaces/IPoolAddressesProvider.sol#L5

__init__(chain_id, ui_pool_data_provider, pool_addresses_provider)

Parameters

• chain_id (int) –

• ui_pool_data_provider (web3.contract.contract.Contract) –

• pool_addresses_provider (web3.contract.contract.Contract) –

Return type

None

StructVal: TypeAlias = str | bool | int

Quick and dirty “any” Solidity value hack

class AggregatedReserveData

Bases: TypedDict

Rough mapping of AggreatedReserveData in Aave v3 Solidity source code.

Note

This data is not useful until JavaScript based formatters from aave-utilities are applied. As writing of this, these formatters are only available as undocumented JavaScript code in this repository. See the repository for more information.

__init__(*args, **kwargs)

__new__(**kwargs)

clear() → None.  Remove all items from D.

copy() → a shallow copy of D

fromkeys(value=None, /)

Create a new dictionary with keys from iterable and values set to value.

get(key, default=None, /)

Return the value for key if key is in the dictionary, else default.

items() → a set-like object providing a view on D's items

keys() → a set-like object providing a view on D's keys

pop(k[, d]) → v, remove specified key and return the corresponding value.

If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem()

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

setdefault(key, default=None, /)

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

update([E, ]**F) → None.  Update D from mapping/iterable E and F.

If E is present and has a .keys() method, then does: for k in E.keys(): D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values() → an object providing a view on D's values

class BaseCurrencyInfo

Bases: TypedDict

Rough mapping of BaseCurrencyInfo in Aave v3 Solidity source code.

Aave internally gets this data from ChainLink feed.

__init__(*args, **kwargs)

__new__(**kwargs)

clear() → None.  Remove all items from D.

copy() → a shallow copy of D

fromkeys(value=None, /)

Create a new dictionary with keys from iterable and values set to value.

get(key, default=None, /)

Return the value for key if key is in the dictionary, else default.

items() → a set-like object providing a view on D's items

keys() → a set-like object providing a view on D's keys

pop(k[, d]) → v, remove specified key and return the corresponding value.

If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem()

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

setdefault(key, default=None, /)

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

update([E, ]**F) → None.  Update D from mapping/iterable E and F.

If E is present and has a .keys() method, then does: for k in E.keys(): D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values() → an object providing a view on D's values

class JSONSerialisableReserveData

Bases: TypedDict

JSON friendly way to store Aave v3 protocol reserve status.

All ints are converted to JavaScript to avoid BigInt issues.

Note

This data is not useful until JavaScript based formatters from aave-utilities are applied. As writing of this, these formatters are only available as undocumented JavaScript code in this repository. See the repository for more information.

chain_id: int

Which chain this was one

block_number: int

When this fetch was performed

block_hash: str

When this fetch was performed

timestamp: int

Unix timestamp when this fetch was performed

reserves: Dict[str, eth_defi.aave_v3.reserve.AggregatedReserveData]

ERC-20 address -> reserve info mapping.

All addresses are lowercased 0x strings

base_currency_info: eth_defi.aave_v3.reserve.BaseCurrencyInfo

Chainlink currency conversion multipliers needed by aave-utilities to convert values to USD/useful/human-readable

__init__(*args, **kwargs)

__new__(**kwargs)

clear() → None.  Remove all items from D.

copy() → a shallow copy of D

fromkeys(value=None, /)

Create a new dictionary with keys from iterable and values set to value.

get(key, default=None, /)

Return the value for key if key is in the dictionary, else default.

items() → a set-like object providing a view on D's items

keys() → a set-like object providing a view on D's keys

pop(k[, d]) → v, remove specified key and return the corresponding value.

If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem()

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

setdefault(key, default=None, /)

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

update([E, ]**F) → None.  Update D from mapping/iterable E and F.

If E is present and has a .keys() method, then does: for k in E.keys(): D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values() → an object providing a view on D's values

get_helper_contracts(web3)

Get helper contracts need to read Aave reserve data.

Raises

AaveContractsNotConfigured – If we do not have labelled addresses for this chain

Parameters

web3 (web3.main.Web3) –

Return type

eth_defi.aave_v3.reserve.HelperContracts

fetch_reserves(contracts, block_identifier=None)

Enumerate available reserves.

https://github.com/aave/aave-v3-core/blob/27a6d5c83560694210849d4abf09a09dec8da388/contracts/interfaces/IPool.sol#L603

Returns

Returns the list of the underlying assets of all the initialized reserves.

List of ERC-20 addresses.

Parameters

contracts (eth_defi.aave_v3.reserve.HelperContracts) –

Return type

List[str]

fetch_reserve_data(contracts, block_identifier=None)

Fetch data for all reserves.

Parameters

contracts (eth_defi.aave_v3.reserve.HelperContracts) – Helper contracts needed to pull the data

Returns

List of data of all reserves, currency data from ChainLink used to convert this info for display

Return type

Tuple[List[eth_defi.aave_v3.reserve.AggregatedReserveData], eth_defi.aave_v3.reserve.BaseCurrencyInfo]

fetch_aave_reserves_snapshot(web3, block_identifier=None)

Get a snapshot of all data of Aave reserves at a certain point of time.

See JSONSerialisableReserveData for notes on how to transform the output to useful and/or human readable.

Example:

# Read Polygon Aave v3 reserves data at current block
snapshot = fetch_aave_reserves_snapshot(web3)

Example output:

{'block_number': 46092890,
 'block_hash': '0x66b91e13e66978632d7687fa37d61994a092194dd83ab800c4b3fbbfbbc4b882',
 'timestamp': 1691574096,
 'reserves': {'0x8f3Cf7ad23Cd3CaDbD9735AFf958023239c6A063': {'underlyingAsset': '0x8f3Cf7ad23Cd3CaDbD9735AFf958023239c6A063',
   'name': '(PoS) Dai Stablecoin',
   'symbol': 'DAI',
   'decimals': '18',
   'baseLTVasCollateral': '7600',
   'reserveLiquidationThreshold': '8100',
   'reserveLiquidationBonus': '10500',
   'reserveFactor': '1000',
   'usageAsCollateralEnabled': True,
   'borrowingEnabled': True,
   'stableBorrowRateEnabled': True,
   'isActive': True,
   'isFrozen': False,
   'liquidityIndex': '1022026858597482843618393800',
   'variableBorrowIndex': '1039320957656647363864994430',
   'liquidityRate': '28850861922310792585422606',
   'variableBorrowRate': '39579583454495318816309720',
   'stableBorrowRate': '54947447931811914852038715',
   'lastUpdateTimestamp': '1691574072',
   'aTokenAddress': '0x82E64f49Ed5EC1bC6e43DAD4FC8Af9bb3A2312EE',
   'stableDebtTokenAddress': '0xd94112B5B62d53C9402e7A60289c6810dEF1dC9B',
   'variableDebtTokenAddress': '0x8619d80FB0141ba7F184CbF22fd724116D9f7ffC',
   'interestRateStrategyAddress': '0xA9F3C3caE095527061e6d270DBE163693e6fda9D',
   'availableLiquidity': '1889483036044495898670614',
   'totalPrincipalStableDebt': '411830124610128093102375',
   'averageStableRate': '55554322387136738659305167',
   'stableDebtLastUpdateTimestamp': '1691573968',
   'totalScaledVariableDebt': '6509001421349391268535081',
   'priceInMarketReferenceCurrency': '99970000',
   'priceOracle': '0x4746DeC9e833A82EC7C2C1356372CcF2cfcD2F3D',
   'variableRateSlope1': '40000000000000000000000000',
   'variableRateSlope2': '750000000000000000000000000',
   'stableRateSlope1': '5000000000000000000000000',
   'stableRateSlope2': '750000000000000000000000000',
   'baseStableBorrowRate': '50000000000000000000000000',
   'baseVariableBorrowRate': '0',
   'optimalUsageRatio': '800000000000000000000000000',
   'isPaused': False,
   'isSiloedBorrowing': False,
   'accruedToTreasury': '142442743829638527556',
   'unbacked': '0',
   'isolationModeTotalDebt': '0',
   'flashLoanEnabled': True,
   'debtCeiling': '0',
   'debtCeilingDecimals': '2',
   'eModeCategoryId': '1',
   'borrowCap': '30000000',
   'supplyCap': '45000000',
   'eModeLtv': '9300',
   'eModeLiquidationThreshold': '9500',
   'eModeLiquidationBonus': '10100',
   'eModePriceSource': '0x0000000000000000000000000000000000000000',
   'eModeLabel': 'Stablecoins',
   'borrowableInIsolation': True},
  '0x53E0bca35eC356BD5ddDFebbD1Fc0fD03FaBad39': {'underlyingAsset': '0x53E0bca35eC356BD5ddDFebbD1Fc0fD03FaBad39',
   'name': 'ChainLink Token',
   'symbol': 'LINK',
   'decimals': '18',

Parameters

• web3 (web3.main.Web3) – Web3 connection for some of the chain for which we have Aave v3 contract data available.

• block_identifier –

  Block when to take the snapshot.

  If not given, use the latest block.

Returns

JSON friendly dict where all ints are converted to string

Return type

eth_defi.aave_v3.reserve.JSONSerialisableReserveData