Aave V3¶

Connector for Aave V3 lending protocol.

almanak.framework.connectors.aave_v3 ¶

Aave V3 Connector.

This module provides an adapter for interacting with Aave V3 lending protocol, supporting supply, borrow, repay, withdraw, flash loans, E-Mode, isolation mode, and comprehensive event parsing.

Aave V3 is a decentralized lending protocol supporting: - Supply assets to earn yield - Borrow against collateral - Flash loans for atomic arbitrage - Efficiency Mode (E-Mode) for correlated assets - Isolation Mode for new assets with limited debt ceiling - Variable and stable interest rates

Supported chains: - Ethereum - Arbitrum - Optimism - Polygon - Base - Avalanche

Example

from almanak.framework.connectors.aave_v3 import AaveV3Adapter, AaveV3Config

config = AaveV3Config( chain="arbitrum", wallet_address="0x...", ) adapter = AaveV3Adapter(config)

Supply collateral¶

result = adapter.supply( asset="USDC", amount=Decimal("1000"), )

Borrow against collateral¶

result = adapter.borrow( asset="WETH", amount=Decimal("0.5"), )

Execute flash loan¶

result = adapter.flash_loan_simple( receiver_address="0x...", asset="USDC", amount=Decimal("100000"), )

Calculate health factor¶

hf_calc = adapter.calculate_health_factor( positions=positions, reserve_data=reserve_data, )

AaveV3Adapter ¶

AaveV3Adapter(
    config: AaveV3Config,
    price_oracle: PriceOracle | None = None,
    token_resolver: TokenResolver | None = None,
)

Adapter for Aave V3 lending protocol.

This adapter provides methods for interacting with Aave V3: - Supply/withdraw collateral - Borrow/repay assets - Flash loans - E-Mode configuration - Health factor calculations - Liquidation price calculations

Example

config = AaveV3Config( chain="arbitrum", wallet_address="0x...", ) adapter = AaveV3Adapter(config)

Supply USDC as collateral¶

result = adapter.supply("USDC", Decimal("1000"))

Borrow ETH¶

result = adapter.borrow("WETH", Decimal("0.5"))

Check health factor¶

hf = adapter.calculate_health_factor(positions, prices)

Initialize the adapter.

Parameters:

Name	Type	Description	Default
`config`	`AaveV3Config`	Adapter configuration	required
`price_oracle`	`PriceOracle \| None`	Price oracle callback. REQUIRED for production use. If not provided and allow_placeholder_prices=False, health factor calculations will raise an error. Pass a real price oracle from your MarketSnapshot or PriceAggregator.	`None`
`token_resolver`	`TokenResolver \| None`	Optional TokenResolver instance. If None, uses singleton.	`None`

Raises:

Type	Description
`ValueError`	If no price_oracle is provided and allow_placeholder_prices=False

supply ¶

supply(
    asset: str,
    amount: Decimal,
    on_behalf_of: str | None = None,
) -> TransactionResult

Build a supply transaction.

Parameters:

Name	Type	Description	Default
`asset`	`str`	Asset symbol or address	required
`amount`	`Decimal`	Amount to supply (in token units)	required
`on_behalf_of`	`str \| None`	Address to credit (defaults to wallet_address)	`None`

Returns:

Type	Description
`TransactionResult`	TransactionResult with transaction data

withdraw ¶

withdraw(
    asset: str,
    amount: Decimal,
    to: str | None = None,
    withdraw_all: bool = False,
) -> TransactionResult

Build a withdraw transaction.

Parameters:

Name	Type	Description	Default
`asset`	`str`	Asset symbol or address	required
`amount`	`Decimal`	Amount to withdraw (in token units)	required
`to`	`str \| None`	Address to receive tokens (defaults to wallet_address)	`None`
`withdraw_all`	`bool`	If True, use MAX_UINT256 to withdraw all	`False`

Returns:

Type	Description
`TransactionResult`	TransactionResult with transaction data

borrow ¶

borrow(
    asset: str,
    amount: Decimal,
    interest_rate_mode: AaveV3InterestRateMode = AaveV3InterestRateMode.VARIABLE,
    on_behalf_of: str | None = None,
) -> TransactionResult

Build a borrow transaction.

Parameters:

Name	Type	Description	Default
`asset`	`str`	Asset symbol or address	required
`amount`	`Decimal`	Amount to borrow (in token units)	required
`interest_rate_mode`	`AaveV3InterestRateMode`	Interest rate mode (STABLE or VARIABLE)	`VARIABLE`
`on_behalf_of`	`str \| None`	Address to debit (defaults to wallet_address)	`None`

Returns:

Type	Description
`TransactionResult`	TransactionResult with transaction data

repay ¶

repay(
    asset: str,
    amount: Decimal,
    interest_rate_mode: AaveV3InterestRateMode = AaveV3InterestRateMode.VARIABLE,
    on_behalf_of: str | None = None,
    repay_all: bool = False,
) -> TransactionResult

Build a repay transaction.

Parameters:

Name	Type	Description	Default
`asset`	`str`	Asset symbol or address	required
`amount`	`Decimal`	Amount to repay (in token units)	required
`interest_rate_mode`	`AaveV3InterestRateMode`	Interest rate mode of debt to repay	`VARIABLE`
`on_behalf_of`	`str \| None`	Address with debt (defaults to wallet_address)	`None`
`repay_all`	`bool`	If True, use MAX_UINT256 to repay full debt	`False`

Returns:

Type	Description
`TransactionResult`	TransactionResult with transaction data

set_user_use_reserve_as_collateral ¶

set_user_use_reserve_as_collateral(
    asset: str, use_as_collateral: bool
) -> TransactionResult

Build a transaction to enable/disable asset as collateral.

Parameters:

Name	Type	Description	Default
`asset`	`str`	Asset symbol or address	required
`use_as_collateral`	`bool`	Whether to use as collateral	required

Returns:

Type	Description
`TransactionResult`	TransactionResult with transaction data

set_user_emode ¶

set_user_emode(category_id: int) -> TransactionResult

Build a transaction to set user E-Mode category.

E-Mode (Efficiency Mode) allows higher LTV for correlated assets.

Categories: - 0: None (normal mode) - 1: ETH correlated (ETH, wstETH, cbETH, rETH) - 2: Stablecoins (USDC, USDT, DAI)

Parameters:

Name	Type	Description	Default
`category_id`	`int`	E-Mode category ID	required

Returns:

Type	Description
`TransactionResult`	TransactionResult with transaction data

get_emode_category_data ¶

get_emode_category_data(category_id: int) -> dict[str, Any]

Get E-Mode category configuration.

Parameters:

Name	Type	Description	Default
`category_id`	`int`	E-Mode category ID	required

Returns:

Type	Description
`dict[str, Any]`	Dictionary with E-Mode category data

flash_loan ¶

flash_loan(
    receiver_address: str,
    assets: list[str],
    amounts: list[Decimal],
    modes: list[int],
    on_behalf_of: str | None = None,
    params: bytes = b"",
) -> TransactionResult

Build a flash loan transaction.

Flash loans allow borrowing assets without collateral, provided they are returned (plus premium) within the same transaction.

Modes: - 0: No open debt (must repay within same transaction) - 1: Open stable rate debt - 2: Open variable rate debt

Parameters:

Name	Type	Description	Default
`receiver_address`	`str`	Contract that will receive the flash loan	required
`assets`	`list[str]`	List of asset symbols or addresses	required
`amounts`	`list[Decimal]`	List of amounts to borrow	required
`modes`	`list[int]`	List of debt modes (0, 1, or 2)	required
`on_behalf_of`	`str \| None`	Address to receive debt if mode != 0	`None`
`params`	`bytes`	Extra data to pass to receiver	`b''`

Returns:

Type	Description
`TransactionResult`	TransactionResult with transaction data

flash_loan_simple ¶

flash_loan_simple(
    receiver_address: str,
    asset: str,
    amount: Decimal,
    params: bytes = b"",
) -> TransactionResult

Build a simple flash loan transaction (single asset, no debt).

This is a simplified flash loan for a single asset that must be repaid within the same transaction.

Parameters:

Name	Type	Description	Default
`receiver_address`	`str`	Contract that will receive the flash loan	required
`asset`	`str`	Asset symbol or address	required
`amount`	`Decimal`	Amount to borrow	required
`params`	`bytes`	Extra data to pass to receiver	`b''`

Returns:

Type	Description
`TransactionResult`	TransactionResult with transaction data

liquidation_call ¶

liquidation_call(
    collateral_asset: str,
    debt_asset: str,
    user: str,
    debt_to_cover: Decimal,
    receive_atoken: bool = False,
) -> TransactionResult

Build a liquidation transaction.

Liquidation allows repaying another user's debt in exchange for their collateral at a discount (liquidation bonus).

Parameters:

Name	Type	Description	Default
`collateral_asset`	`str`	Asset to receive as collateral	required
`debt_asset`	`str`	Asset to repay	required
`user`	`str`	Address of user to liquidate	required
`debt_to_cover`	`Decimal`	Amount of debt to repay	required
`receive_atoken`	`bool`	If True, receive aTokens instead of underlying	`False`

Returns:

Type	Description
`TransactionResult`	TransactionResult with transaction data

calculate_health_factor ¶

calculate_health_factor(
    positions: list[AaveV3Position],
    reserve_data: dict[str, AaveV3ReserveData],
    prices: dict[str, Decimal] | None = None,
    emode_category: int = 0,
) -> AaveV3HealthFactorCalculation

Calculate health factor from positions.

Health Factor = (Sum of Collateral * Liquidation Threshold) / Total Debt

A health factor < 1.0 means the position can be liquidated.

Parameters:

Name	Type	Description	Default
`positions`	`list[AaveV3Position]`	List of user positions	required
`reserve_data`	`dict[str, AaveV3ReserveData]`	Reserve data for each asset	required
`prices`	`dict[str, Decimal] \| None`	Asset prices in USD (uses oracle if not provided)	`None`
`emode_category`	`int`	User's E-Mode category (affects LT calculations)	`0`

Returns:

Type	Description
`AaveV3HealthFactorCalculation`	AaveV3HealthFactorCalculation with detailed breakdown

calculate_liquidation_price ¶

calculate_liquidation_price(
    collateral_asset: str,
    collateral_amount: Decimal,
    debt_usd: Decimal,
    liquidation_threshold_bps: int,
) -> Decimal

Calculate the price at which a position becomes liquidatable.

Parameters:

Name	Type	Description	Default
`collateral_asset`	`str`	Collateral asset symbol	required
`collateral_amount`	`Decimal`	Amount of collateral (in token units)	required
`debt_usd`	`Decimal`	Total debt in USD	required
`liquidation_threshold_bps`	`int`	Liquidation threshold in basis points	required

Returns:

Type	Description
`Decimal`	Price at which position becomes liquidatable

calculate_max_borrow ¶

calculate_max_borrow(
    collateral_value_usd: Decimal,
    current_debt_usd: Decimal,
    ltv_bps: int,
) -> Decimal

Calculate maximum additional borrow amount.

Parameters:

Name	Type	Description	Default
`collateral_value_usd`	`Decimal`	Total collateral value in USD	required
`current_debt_usd`	`Decimal`	Current debt in USD	required
`ltv_bps`	`int`	Loan-to-Value ratio in basis points	required

Returns:

Type	Description
`Decimal`	Maximum additional borrow amount in USD

calculate_health_factor_after_borrow ¶

calculate_health_factor_after_borrow(
    current_hf_calc: AaveV3HealthFactorCalculation,
    borrow_amount_usd: Decimal,
) -> Decimal

Calculate health factor after a hypothetical borrow.

Parameters:

Name	Type	Description	Default
`current_hf_calc`	`AaveV3HealthFactorCalculation`	Current health factor calculation	required
`borrow_amount_usd`	`Decimal`	Amount to borrow in USD	required

Returns:

Type	Description
`Decimal`	Projected health factor after borrow

get_isolation_mode_debt_ceiling ¶

get_isolation_mode_debt_ceiling(asset: str) -> Decimal

Get debt ceiling for an isolated asset.

Assets in isolation mode have a debt ceiling limiting total borrows.

Parameters:

Name	Type	Description	Default
`asset`	`str`	Asset symbol	required

Returns:

Type	Description
`Decimal`	Debt ceiling in USD (0 if not isolated)

is_asset_isolated ¶

is_asset_isolated(asset: str) -> bool

Check if asset is in isolation mode.

Parameters:

Name	Type	Description	Default
`asset`	`str`	Asset symbol	required

Returns:

Type	Description
`bool`	True if asset is isolated

build_approve_tx ¶

build_approve_tx(
    asset: str, amount: Decimal | None = None
) -> TransactionResult

Build an ERC20 approve transaction for Aave Pool.

Parameters:

Name	Type	Description	Default
`asset`	`str`	Asset symbol or address	required
`amount`	`Decimal \| None`	Amount to approve (defaults to MAX_UINT256)	`None`

Returns:

Type	Description
`TransactionResult`	TransactionResult with transaction data

get_reserve_data ¶

get_reserve_data(asset: str) -> AaveV3ReserveData | None

Get reserve data for an asset.

Parameters:

Name	Type	Description	Default
`asset`	`str`	Asset symbol	required

Returns:

Type	Description
`AaveV3ReserveData \| None`	Reserve data or None

set_reserve_data ¶

set_reserve_data(
    asset: str, data: AaveV3ReserveData
) -> None

Set reserve data for an asset (for testing/mocking).

Parameters:

Name	Type	Description	Default
`asset`	`str`	Asset symbol	required
`data`	`AaveV3ReserveData`	Reserve data	required

AaveV3Config `dataclass` ¶

AaveV3Config(
    chain: str,
    wallet_address: str,
    default_slippage_bps: int = 50,
    allow_placeholder_prices: bool = False,
)

Configuration for Aave V3 adapter.

Attributes:

Name	Type	Description
`chain`	`str`	Blockchain network (ethereum, arbitrum, optimism, polygon, base, avalanche)
`wallet_address`	`str`	User wallet address
`default_slippage_bps`	`int`	Default slippage tolerance in basis points
`allow_placeholder_prices`	`bool`	If True, allows fallback to hardcoded placeholder prices. WARNING: NEVER set to True in production! Placeholder prices cause incorrect health factor calculations which can lead to unexpected liquidations. Only use for local testing/development without real price data.

__post_init__ ¶

__post_init__() -> None

Validate configuration.

AaveV3EModeCategory ¶

Bases: IntEnum

Aave V3 E-Mode categories.

AaveV3FlashLoanParams `dataclass` ¶

AaveV3FlashLoanParams(
    assets: list[str],
    amounts: list[Decimal],
    modes: list[int],
    on_behalf_of: str,
    params: bytes = bytes(),
    referral_code: int = 0,
)

Parameters for an Aave V3 flash loan.

Attributes:

Name	Type	Description
`assets`	`list[str]`	List of asset addresses to borrow
`amounts`	`list[Decimal]`	List of amounts to borrow (in token units)
`modes`	`list[int]`	Interest rate modes (0 = no debt, 1 = stable, 2 = variable)
`on_behalf_of`	`str`	Address to receive debt (if modes != 0)
`params`	`bytes`	Extra params to pass to receiver contract
`referral_code`	`int`	Referral code (usually 0)

__post_init__ ¶

__post_init__() -> None

Validate flash loan parameters.

AaveV3HealthFactorCalculation `dataclass` ¶

AaveV3HealthFactorCalculation(
    total_collateral_usd: Decimal,
    total_debt_usd: Decimal,
    weighted_liquidation_threshold: Decimal,
    health_factor: Decimal,
    liquidation_price: Decimal | None = None,
    assets_breakdown: dict[str, dict[str, Any]] = dict(),
)

Health factor calculation details.

Attributes:

Name	Type	Description
`total_collateral_usd`	`Decimal`	Total collateral value in USD
`total_debt_usd`	`Decimal`	Total debt value in USD
`weighted_liquidation_threshold`	`Decimal`	Weighted average liquidation threshold
`health_factor`	`Decimal`	Calculated health factor
`liquidation_price`	`Decimal \| None`	Price at which position becomes liquidatable
`assets_breakdown`	`dict[str, dict[str, Any]]`	Per-asset breakdown

is_healthy `property` ¶

is_healthy: bool

Check if position is healthy (HF >= 1).

buffer_to_liquidation `property` ¶

buffer_to_liquidation: Decimal

Get buffer to liquidation as percentage.

to_dict ¶

to_dict() -> dict[str, Any]

Convert to dictionary.

AaveV3InterestRateMode ¶

Bases: IntEnum

Aave V3 interest rate modes.

AaveV3Position `dataclass` ¶

AaveV3Position(
    asset: str,
    asset_address: str,
    current_atoken_balance: Decimal = Decimal("0"),
    current_stable_debt: Decimal = Decimal("0"),
    current_variable_debt: Decimal = Decimal("0"),
    principal_stable_debt: Decimal = Decimal("0"),
    scaled_variable_debt: Decimal = Decimal("0"),
    stable_borrow_rate: Decimal = Decimal("0"),
    liquidity_rate: Decimal = Decimal("0"),
    usage_as_collateral_enabled: bool = False,
)

User position in a specific Aave V3 reserve.

Attributes:

Name	Type	Description
`asset`	`str`	Asset symbol
`asset_address`	`str`	Asset contract address
`current_atoken_balance`	`Decimal`	Current aToken balance (supplied amount + interest)
`current_stable_debt`	`Decimal`	Current stable debt
`current_variable_debt`	`Decimal`	Current variable debt
`principal_stable_debt`	`Decimal`	Principal stable debt
`scaled_variable_debt`	`Decimal`	Scaled variable debt
`stable_borrow_rate`	`Decimal`	Current stable borrow rate
`liquidity_rate`	`Decimal`	Current supply/liquidity rate
`usage_as_collateral_enabled`	`bool`	Whether using as collateral
`is_collateral`	`bool`	Alias for usage_as_collateral_enabled

is_collateral `property` ¶

is_collateral: bool

Check if position is being used as collateral.

total_debt `property` ¶

total_debt: Decimal

Get total debt (stable + variable).

has_supply `property` ¶

has_supply: bool

Check if user has supply in this reserve.

has_debt `property` ¶

has_debt: bool

Check if user has debt in this reserve.

to_dict ¶

to_dict() -> dict[str, Any]

Convert to dictionary.

AaveV3ReserveData `dataclass` ¶

AaveV3ReserveData(
    asset: str,
    asset_address: str,
    atoken_address: str = "",
    stable_debt_token_address: str = "",
    variable_debt_token_address: str = "",
    ltv: int = 0,
    liquidation_threshold: int = 0,
    liquidation_bonus: int = 0,
    reserve_factor: int = 0,
    usage_as_collateral_enabled: bool = True,
    borrowing_enabled: bool = True,
    stable_borrow_rate_enabled: bool = False,
    is_active: bool = True,
    is_frozen: bool = False,
    is_paused: bool = False,
    supply_cap: Decimal = Decimal("0"),
    borrow_cap: Decimal = Decimal("0"),
    debt_ceiling: Decimal = Decimal("0"),
    emode_ltv: int = 0,
    emode_liquidation_threshold: int = 0,
    emode_liquidation_bonus: int = 0,
    emode_category: int = 0,
)

Reserve data for an Aave V3 asset.

Attributes:

Name	Type	Description
`asset`	`str`	Asset symbol
`asset_address`	`str`	Asset contract address
`atoken_address`	`str`	aToken contract address
`stable_debt_token_address`	`str`	Stable debt token address
`variable_debt_token_address`	`str`	Variable debt token address
`ltv`	`int`	Loan-to-Value ratio (in basis points, e.g., 8000 = 80%)
`liquidation_threshold`	`int`	Liquidation threshold (in basis points)
`liquidation_bonus`	`int`	Liquidation bonus (in basis points, e.g., 10500 = 5% bonus)
`reserve_factor`	`int`	Reserve factor (in basis points)
`usage_as_collateral_enabled`	`bool`	Whether asset can be used as collateral
`borrowing_enabled`	`bool`	Whether asset can be borrowed
`stable_borrow_rate_enabled`	`bool`	Whether stable borrow rate is enabled
`is_active`	`bool`	Whether reserve is active
`is_frozen`	`bool`	Whether reserve is frozen
`is_paused`	`bool`	Whether reserve is paused
`supply_cap`	`Decimal`	Maximum supply (0 = unlimited)
`borrow_cap`	`Decimal`	Maximum borrow (0 = unlimited)
`debt_ceiling`	`Decimal`	Debt ceiling for isolation mode (0 = not isolated)
`emode_ltv`	`int`	LTV when in E-Mode
`emode_liquidation_threshold`	`int`	Liquidation threshold in E-Mode
`emode_liquidation_bonus`	`int`	Liquidation bonus in E-Mode
`emode_category`	`int`	E-Mode category ID

is_isolated `property` ¶

is_isolated: bool

Check if asset is in isolation mode.

to_dict ¶

to_dict() -> dict[str, Any]

Convert to dictionary.

AaveV3UserAccountData `dataclass` ¶

AaveV3UserAccountData(
    total_collateral_base: Decimal,
    total_debt_base: Decimal,
    available_borrows_base: Decimal,
    current_liquidation_threshold: int,
    ltv: int,
    health_factor: Decimal,
    emode_category: int = 0,
)

User account data from Aave V3.

Attributes:

Name	Type	Description
`total_collateral_base`	`Decimal`	Total collateral in base currency (USD)
`total_debt_base`	`Decimal`	Total debt in base currency (USD)
`available_borrows_base`	`Decimal`	Available borrows in base currency
`current_liquidation_threshold`	`int`	Current weighted liquidation threshold
`ltv`	`int`	Current weighted LTV
`health_factor`	`Decimal`	Health factor (1e18 = 1.0, < 1.0 = liquidatable)
`emode_category`	`int`	Current E-Mode category

health_factor_normalized `property` ¶

health_factor_normalized: Decimal

Get health factor as a normalized value (1.0 = healthy threshold).

is_liquidatable `property` ¶

is_liquidatable: bool

Check if position is liquidatable.

distance_to_liquidation `property` ¶

distance_to_liquidation: Decimal

Get distance to liquidation (0 = liquidatable, 1 = 2x health factor).

to_dict ¶

to_dict() -> dict[str, Any]

Convert to dictionary.

TransactionResult `dataclass` ¶

TransactionResult(
    success: bool,
    tx_data: dict[str, Any] | None = None,
    gas_estimate: int = 0,
    description: str = "",
    error: str | None = None,
)

Result of a transaction build operation.

Attributes:

Name	Type	Description
`success`	`bool`	Whether operation succeeded
`tx_data`	`dict[str, Any] \| None`	Transaction data (to, value, data)
`gas_estimate`	`int`	Estimated gas
`description`	`str`	Human-readable description
`error`	`str \| None`	Error message if failed

to_dict ¶

to_dict() -> dict[str, Any]

Convert to dictionary.

AaveV3Event `dataclass` ¶

AaveV3Event(
    event_type: AaveV3EventType,
    event_name: str,
    log_index: int,
    transaction_hash: str,
    block_number: int,
    contract_address: str,
    data: dict[str, Any],
    raw_topics: list[str] = list(),
    raw_data: str = "",
    timestamp: datetime = (lambda: datetime.now(tz=None))(),
)

Parsed Aave V3 event.

Attributes:

Name	Type	Description
`event_type`	`AaveV3EventType`	Type of event
`event_name`	`str`	Name of event (e.g., "Supply")
`log_index`	`int`	Index of log in transaction
`transaction_hash`	`str`	Transaction hash
`block_number`	`int`	Block number
`contract_address`	`str`	Contract that emitted event
`data`	`dict[str, Any]`	Parsed event data
`raw_topics`	`list[str]`	Raw event topics
`raw_data`	`str`	Raw event data
`timestamp`	`datetime`	Event timestamp

to_dict ¶

to_dict() -> dict[str, Any]

Convert to dictionary.

from_dict `classmethod` ¶

from_dict(data: dict[str, Any]) -> AaveV3Event

Create from dictionary.

AaveV3EventType ¶

Bases: Enum

Aave V3 event types.

AaveV3ReceiptParser ¶

AaveV3ReceiptParser(**kwargs: Any)

Parser for Aave V3 transaction receipts.

This parser extracts and decodes Aave V3 events from transaction receipts, providing structured data for supplies, borrows, repays, flash loans, liquidations, and other protocol events.

Example

parser = AaveV3ReceiptParser()

Parse a receipt dict (from web3.py)¶

result = parser.parse_receipt(receipt)

if result.success: for event in result.events: print(f"Event: {event.event_name}")

for supply in result.supplies:
    print(f"Supply: {supply.amount} to {supply.reserve}")

Initialize the parser.

Parameters:

Name	Type	Description	Default
`**kwargs`	`Any`	Additional arguments (ignored for compatibility)	`{}`

parse_receipt ¶

parse_receipt(receipt: dict[str, Any]) -> ParseResult

Parse a transaction receipt.

Parameters:

Name	Type	Description	Default
`receipt`	`dict[str, Any]`	Transaction receipt dict containing 'logs', 'transactionHash', 'blockNumber', etc.	required

Returns:

Type	Description
`ParseResult`	ParseResult with extracted events and data

parse_logs ¶

parse_logs(logs: list[dict[str, Any]]) -> list[AaveV3Event]

Parse a list of logs.

Parameters:

Name	Type	Description	Default
`logs`	`list[dict[str, Any]]`	List of log dicts	required

Returns:

Type	Description
`list[AaveV3Event]`	List of parsed events

extract_supply_amount ¶

extract_supply_amount(
    receipt: dict[str, Any],
) -> int | None

Extract supply amount from a transaction receipt.

Parameters:

Name	Type	Description	Default
`receipt`	`dict[str, Any]`	Transaction receipt dict with 'logs' field	required

Returns:

Type	Description
`int \| None`	Supply amount if found, None otherwise

extract_withdraw_amount ¶

extract_withdraw_amount(
    receipt: dict[str, Any],
) -> int | None

Extract withdraw amount from a transaction receipt.

Parameters:

Name	Type	Description	Default
`receipt`	`dict[str, Any]`	Transaction receipt dict with 'logs' field	required

Returns:

Type	Description
`int \| None`	Withdraw amount if found, None otherwise

extract_borrow_amount ¶

extract_borrow_amount(
    receipt: dict[str, Any],
) -> int | None

Extract borrow amount from a transaction receipt.

Parameters:

Name	Type	Description	Default
`receipt`	`dict[str, Any]`	Transaction receipt dict with 'logs' field	required

Returns:

Type	Description
`int \| None`	Borrow amount if found, None otherwise

extract_repay_amount ¶

extract_repay_amount(receipt: dict[str, Any]) -> int | None

Extract repay amount from a transaction receipt.

Parameters:

Name	Type	Description	Default
`receipt`	`dict[str, Any]`	Transaction receipt dict with 'logs' field	required

Returns:

Type	Description
`int \| None`	Repay amount if found, None otherwise

extract_a_token_received ¶

extract_a_token_received(
    receipt: dict[str, Any],
) -> int | None

Extract aToken amount received from a transaction receipt.

Looks for Transfer events from the zero address (minting).

Parameters:

Name	Type	Description	Default
`receipt`	`dict[str, Any]`	Transaction receipt dict with 'logs' field	required

Returns:

Type	Description
`int \| None`	aToken amount if found, None otherwise

extract_borrow_rate ¶

extract_borrow_rate(
    receipt: dict[str, Any],
) -> Decimal | None

Extract borrow rate from a transaction receipt.

Parameters:

Name	Type	Description	Default
`receipt`	`dict[str, Any]`	Transaction receipt dict with 'logs' field	required

Returns:

Type	Description
`Decimal \| None`	Borrow rate (as decimal, e.g., 0.05 for 5%) if found, None otherwise

is_aave_event ¶

is_aave_event(topic: str | bytes) -> bool

Check if a topic is a known Aave V3 event.

Parameters:

Name	Type	Description	Default
`topic`	`str \| bytes`	Event topic (supports bytes, hex string with/without 0x, any case)	required

Returns:

Type	Description
`bool`	True if topic is a known Aave V3 event

get_event_type ¶

get_event_type(topic: str | bytes) -> AaveV3EventType

Get the event type for a topic.

Parameters:

Name	Type	Description	Default
`topic`	`str \| bytes`	Event topic (supports bytes, hex string with/without 0x, any case)	required

Returns:

Type	Description
`AaveV3EventType`	Event type or UNKNOWN

BorrowEventData `dataclass` ¶

BorrowEventData(
    reserve: str,
    user: str,
    on_behalf_of: str,
    amount: Decimal,
    interest_rate_mode: int,
    borrow_rate: Decimal = Decimal("0"),
    referral_code: int = 0,
)

Parsed data from Borrow event.

Attributes:

Name	Type	Description
`reserve`	`str`	Asset address that was borrowed
`user`	`str`	User who initiated the borrow
`on_behalf_of`	`str`	Address that received the debt
`amount`	`Decimal`	Amount borrowed (in token units)
`interest_rate_mode`	`int`	1 = stable, 2 = variable
`borrow_rate`	`Decimal`	Current borrow rate (ray, 1e27)
`referral_code`	`int`	Referral code used

is_variable_rate `property` ¶

is_variable_rate: bool

Check if borrow is variable rate.

to_dict ¶

to_dict() -> dict[str, Any]

Convert to dictionary.

FlashLoanEventData `dataclass` ¶

FlashLoanEventData(
    target: str,
    initiator: str,
    asset: str,
    amount: Decimal,
    interest_rate_mode: int,
    premium: Decimal = Decimal("0"),
    referral_code: int = 0,
)

Parsed data from FlashLoan event.

Attributes:

Name	Type	Description
`target`	`str`	Contract that received the flash loan
`initiator`	`str`	Address that initiated the flash loan
`asset`	`str`	Asset address that was borrowed
`amount`	`Decimal`	Amount borrowed (in token units)
`interest_rate_mode`	`int`	Debt mode (0 = no debt, 1 = stable, 2 = variable)
`premium`	`Decimal`	Premium paid (in token units)
`referral_code`	`int`	Referral code used

opened_debt `property` ¶

opened_debt: bool

Check if flash loan opened debt.

to_dict ¶

to_dict() -> dict[str, Any]

Convert to dictionary.

IsolationModeDebtUpdatedEventData `dataclass` ¶

IsolationModeDebtUpdatedEventData(
    asset: str, total_debt: Decimal
)

Parsed data from IsolationModeTotalDebtUpdated event.

Attributes:

Name	Type	Description
`asset`	`str`	Asset address
`total_debt`	`Decimal`	New total debt (in USD with 2 decimals)

to_dict ¶

to_dict() -> dict[str, Any]

Convert to dictionary.

LiquidationCallEventData `dataclass` ¶

LiquidationCallEventData(
    collateral_asset: str,
    debt_asset: str,
    user: str,
    debt_to_cover: Decimal,
    liquidated_collateral_amount: Decimal,
    liquidator: str,
    receive_atoken: bool = False,
)

Parsed data from LiquidationCall event.

Attributes:

Name	Type	Description
`collateral_asset`	`str`	Collateral asset that was seized
`debt_asset`	`str`	Debt asset that was repaid
`user`	`str`	User who was liquidated
`debt_to_cover`	`Decimal`	Amount of debt repaid (in debt token units)
`liquidated_collateral_amount`	`Decimal`	Amount of collateral seized (in collateral token units)
`liquidator`	`str`	Address that performed the liquidation
`receive_atoken`	`bool`	Whether liquidator received aTokens

to_dict ¶

to_dict() -> dict[str, Any]

Convert to dictionary.

ParseResult `dataclass` ¶

ParseResult(
    success: bool,
    events: list[AaveV3Event] = list(),
    supplies: list[SupplyEventData] = list(),
    withdraws: list[WithdrawEventData] = list(),
    borrows: list[BorrowEventData] = list(),
    repays: list[RepayEventData] = list(),
    flash_loans: list[FlashLoanEventData] = list(),
    liquidations: list[LiquidationCallEventData] = list(),
    error: str | None = None,
    transaction_hash: str = "",
    block_number: int = 0,
)

Result of parsing a receipt.

Attributes:

Name	Type	Description
`success`	`bool`	Whether parsing succeeded
`events`	`list[AaveV3Event]`	List of parsed events
`supplies`	`list[SupplyEventData]`	Supply events
`withdraws`	`list[WithdrawEventData]`	Withdraw events
`borrows`	`list[BorrowEventData]`	Borrow events
`repays`	`list[RepayEventData]`	Repay events
`flash_loans`	`list[FlashLoanEventData]`	Flash loan events
`liquidations`	`list[LiquidationCallEventData]`	Liquidation events
`error`	`str \| None`	Error message if parsing failed
`transaction_hash`	`str`	Transaction hash
`block_number`	`int`	Block number

to_dict ¶

to_dict() -> dict[str, Any]

Convert to dictionary.

RepayEventData `dataclass` ¶

RepayEventData(
    reserve: str,
    user: str,
    repayer: str,
    amount: Decimal,
    use_atokens: bool = False,
)

Parsed data from Repay event.

Attributes:

Name	Type	Description
`reserve`	`str`	Asset address that was repaid
`user`	`str`	User whose debt was repaid
`repayer`	`str`	Address that made the repayment
`amount`	`Decimal`	Amount repaid (in token units)
`use_atokens`	`bool`	Whether aTokens were used for repayment

to_dict ¶

to_dict() -> dict[str, Any]

Convert to dictionary.

ReserveDataUpdatedEventData `dataclass` ¶

ReserveDataUpdatedEventData(
    reserve: str,
    liquidity_rate: Decimal,
    stable_borrow_rate: Decimal,
    variable_borrow_rate: Decimal,
    liquidity_index: Decimal = Decimal("0"),
    variable_borrow_index: Decimal = Decimal("0"),
)

Parsed data from ReserveDataUpdated event.

Attributes:

Name	Type	Description
`reserve`	`str`	Asset address
`liquidity_rate`	`Decimal`	Current supply/liquidity rate (ray, 1e27)
`stable_borrow_rate`	`Decimal`	Current stable borrow rate (ray, 1e27)
`variable_borrow_rate`	`Decimal`	Current variable borrow rate (ray, 1e27)
`liquidity_index`	`Decimal`	Current liquidity index
`variable_borrow_index`	`Decimal`	Current variable borrow index

to_dict ¶

to_dict() -> dict[str, Any]

Convert to dictionary.

SupplyEventData `dataclass` ¶

SupplyEventData(
    reserve: str,
    user: str,
    on_behalf_of: str,
    amount: Decimal,
    referral_code: int = 0,
)

Parsed data from Supply event.

Attributes:

Name	Type	Description
`reserve`	`str`	Asset address that was supplied
`user`	`str`	User who initiated the supply
`on_behalf_of`	`str`	Address that received the aTokens
`amount`	`Decimal`	Amount supplied (in token units)
`referral_code`	`int`	Referral code used

to_dict ¶

to_dict() -> dict[str, Any]

Convert to dictionary.

UserEModeSetEventData `dataclass` ¶

UserEModeSetEventData(user: str, category_id: int)

Parsed data from UserEModeSet event.

Attributes:

Name	Type	Description
`user`	`str`	User address
`category_id`	`int`	E-Mode category ID (0 = none, 1 = ETH correlated, 2 = stablecoins)

category_name `property` ¶

category_name: str

Get category name.

to_dict ¶

to_dict() -> dict[str, Any]

Convert to dictionary.

WithdrawEventData `dataclass` ¶

WithdrawEventData(
    reserve: str, user: str, to: str, amount: Decimal
)

Parsed data from Withdraw event.

Attributes:

Name	Type	Description
`reserve`	`str`	Asset address that was withdrawn
`user`	`str`	User who initiated the withdrawal
`to`	`str`	Address that received the tokens
`amount`	`Decimal`	Amount withdrawn (in token units)

to_dict ¶

to_dict() -> dict[str, Any]

Convert to dictionary.

Aave V3¶

almanak.framework.connectors.aave_v3 ¶

Supply collateral¶

Borrow against collateral¶

Execute flash loan¶

Calculate health factor¶

AaveV3Adapter ¶

Supply USDC as collateral¶

Borrow ETH¶

Check health factor¶

supply ¶

withdraw ¶

borrow ¶

repay ¶

set_user_use_reserve_as_collateral ¶

set_user_emode ¶

get_emode_category_data ¶

flash_loan ¶

flash_loan_simple ¶

liquidation_call ¶

calculate_health_factor ¶

calculate_liquidation_price ¶

calculate_max_borrow ¶

calculate_health_factor_after_borrow ¶

get_isolation_mode_debt_ceiling ¶

is_asset_isolated ¶

build_approve_tx ¶

get_reserve_data ¶

set_reserve_data ¶

AaveV3Config dataclass ¶

__post_init__ ¶

AaveV3EModeCategory ¶

AaveV3FlashLoanParams dataclass ¶

__post_init__ ¶

AaveV3HealthFactorCalculation dataclass ¶

is_healthy property ¶

buffer_to_liquidation property ¶

to_dict ¶

AaveV3InterestRateMode ¶

AaveV3Position dataclass ¶

is_collateral property ¶

total_debt property ¶

has_supply property ¶

has_debt property ¶

to_dict ¶

AaveV3ReserveData dataclass ¶

is_isolated property ¶

to_dict ¶

AaveV3UserAccountData dataclass ¶

health_factor_normalized property ¶

is_liquidatable property ¶

distance_to_liquidation property ¶

to_dict ¶

TransactionResult dataclass ¶

to_dict ¶

AaveV3Event dataclass ¶

to_dict ¶

from_dict classmethod ¶

AaveV3EventType ¶

AaveV3ReceiptParser ¶

Parse a receipt dict (from web3.py)¶

parse_receipt ¶

parse_logs ¶

extract_supply_amount ¶

extract_withdraw_amount ¶

extract_borrow_amount ¶

extract_repay_amount ¶

extract_a_token_received ¶

extract_borrow_rate ¶

is_aave_event ¶

get_event_type ¶

BorrowEventData dataclass ¶

is_variable_rate property ¶

to_dict ¶

FlashLoanEventData dataclass ¶

opened_debt property ¶

to_dict ¶

IsolationModeDebtUpdatedEventData dataclass ¶

to_dict ¶

LiquidationCallEventData dataclass ¶

AaveV3Config `dataclass` ¶

AaveV3FlashLoanParams `dataclass` ¶

AaveV3HealthFactorCalculation `dataclass` ¶

is_healthy `property` ¶

buffer_to_liquidation `property` ¶

AaveV3Position `dataclass` ¶

is_collateral `property` ¶

total_debt `property` ¶

has_supply `property` ¶

has_debt `property` ¶

AaveV3ReserveData `dataclass` ¶

is_isolated `property` ¶

AaveV3UserAccountData `dataclass` ¶

health_factor_normalized `property` ¶

is_liquidatable `property` ¶

distance_to_liquidation `property` ¶

TransactionResult `dataclass` ¶

AaveV3Event `dataclass` ¶

from_dict `classmethod` ¶

BorrowEventData `dataclass` ¶

is_variable_rate `property` ¶

FlashLoanEventData `dataclass` ¶

opened_debt `property` ¶

IsolationModeDebtUpdatedEventData `dataclass` ¶

LiquidationCallEventData `dataclass` ¶

ParseResult `dataclass` ¶

RepayEventData `dataclass` ¶

ReserveDataUpdatedEventData `dataclass` ¶

SupplyEventData `dataclass` ¶

UserEModeSetEventData `dataclass` ¶

category_name `property` ¶

WithdrawEventData `dataclass` ¶