degenbot.aave.analysis.orchestrator¶

I/O orchestration for Aave V3 position analysis.

A thin Python driver shell over the Rust degenbot-aave::analysis core (ADR-005 three-layer architecture). The pure math (health-factor / LTV / eMode / isolation / scaled-balance calc) lives in Rust; this module owns only the I/O orchestration: resolve the DB path, fetch users / positions / prices via Rust-backed readers, drive the per-user Rust analysis seam, and bucket the results.

The former core.py (pure math + dataclasses) + protocols.py (typing seams) were retired once the Rust core reached byte-identical parity (verified by the §4.2 parity gate before deletion). The PositionAnalysisResult bucket-sorter stays here (it’s trivial Python, not math).

Module Contents¶

class degenbot.aave.analysis.orchestrator.DatabasePositionQuery(database_path: pathlib.Path)¶

PositionQuery backed by the Rust _EnginePositionQuery reader.

Routes every read through the PyO3 seam (ADR-005) over one explicit, file-backed database path.

get_users_with_debt(market_id: int, limit: int | None = None) → list[dict[str, Any]]¶

Get all users with debt positions in a market, as flat dicts.

Returns:

The Rust-backed row dicts (address checksummed to match the price-map keys the analysis seam consumes).

get_collateral_positions(user_id: int) → list[dict[str, Any]]¶

Get collateral positions for a user, as flat dicts.

Returns:

The Rust-backed row dicts (address checksummed).

get_debt_positions(user_id: int) → list[dict[str, Any]]¶

Get debt positions for a user, as flat dicts.

Returns:

The Rust-backed row dicts (address checksummed).

get_collateral_config_map(user_id: int) → dict[int, bool]¶

Get map of asset_id to enabled status for a user.

Returns:

The computed value.

get_oracle_address(market_id: int) → degenbot._ffi.ChecksummedAddress | None¶

Get the price oracle address for a market.

Returns:

The computed value.

get_asset_addresses(market_id: int) → set[degenbot._ffi.ChecksummedAddress]¶

Get all unique underlying asset addresses for a market.

Returns:

The computed value.

class degenbot.aave.analysis.orchestrator.OraclePriceFetcher(provider: degenbot.provider.AlloyProvider, oracle_address: degenbot._ffi.ChecksummedAddress)¶

PriceFetcher using the Aave oracle contract.

Delegating shell over the Rust AavePriceOracle reader (the degenbot-price core crate, ADR-005). getAssetPrice(address) eth_call + uint256 decode run in Rust, with the same tolerant per-asset skip-on-error behavior.

fetch(asset_addresses: set[degenbot._ffi.ChecksummedAddress]) → dict[degenbot._ffi.ChecksummedAddress, int]¶

Fetch prices for all assets from the Aave oracle.

Returns:

The computed value.

class degenbot.aave.analysis.orchestrator.PositionAnalysisResult¶

Result of analyzing positions for liquidation risk.

Bucket-sorter only (no math) — the per-user UserPositionSummary objects (Rust-built via the analysis seam) are categorized by health factor into safe / at-risk / liquidatable lists.

safe_users: list[degenbot.db.UserPositionSummary] = []¶
at_risk_users: list[degenbot.db.UserPositionSummary] = []¶
liquidatable_users: list[degenbot.db.UserPositionSummary] = []¶
property total_users: int¶

Total users.

property at_risk_count: int¶

At risk count.

property liquidatable_count: int¶

Liquidatable count.

categorize(summary: degenbot.db.UserPositionSummary, health_factor_threshold: float = 1.1) → None¶

Categorize a user summary by health factor.

Parameters:

  • summary – A UserPositionSummary (Rust-built).

  • health_factor_threshold – The at-risk threshold (default 1.1).

sort_by_risk() → None¶

Sort at-risk + liquidatable users by health factor (lowest first).

Mirrors the Rust PositionAnalysisResult::sort_by_risk key: a None OR falsy (0.0) health factor sorts as +inf (the Python or treats 0.0 as falsy).

degenbot.aave.analysis.orchestrator.analyze_positions_for_market(database_path: pathlib.Path, market_id: int, health_factor_threshold: float = 1.1, limit: int | None = None, provider: degenbot.provider.AlloyProvider | None = None) → PositionAnalysisResult¶

Analyze all users-with-debt in a market for liquidation risk.

Thin driver shell: fetches users + prices via Rust-backed readers, drives the per-user analyze_aave_user_position Rust seam, and buckets the results. The pure math (HF / LTV / scaled-balance) lives in Rust (degenbot-aave::analysis).

Parameters:

  • database_path – File-backed SQLite database opened by the Rust reader.

  • market_id – The Aave V3 market id.

  • health_factor_threshold – The at-risk threshold (default 1.1).

  • limit – Optional cap on the number of users analyzed.

  • provider – Optional RPC provider for price fetching (when None, prices are treated as 1 — faster, but HFs are relative).

Returns:

The bucketed analysis result.