degenbot Documentation

With the removal of SnapshotStore, the bot ensures data consistency during startup by using a single SQLite WAL (Write-Ahead Logging) read transaction.

The Consistency Problem

Previously, SnapshotStore froze the database state at boot. Without it, if the pool_updater process writes new data to the SQLite DB while the bot is still performing per-pool registration (build_paths), a race condition occurs:

1. The global snapshot_seed_block (S) is set at boot.
2. A pool registered after the updater has written new rows will read data at block S+N.
3. The verification logic (verify_*_snapshot_seed) will compare this S+N data against the on-chain state at block S, causing a false verification failure.

The Solution: Held Read Transaction

To prevent this, the bot uses Approach 1: holding one BEGIN DEFERRED read transaction across the entire build_paths process.

Because SQLite in WAL mode provides MVCC (Multi-Version Concurrency Control), a single read transaction sees the database exactly as it was when the first read in that transaction started. Even if the pool_updater commits new data, the bot's view remains frozen at the boot-time snapshot. This ensures that the global S and all per-pool liquidity maps are perfectly synchronized for verification.

Degenbot uses an I/O-free architecture to separate network operations from mathematical calculations.

• Pools as Pure Calculation Objects: Once constructed, pool objects (like UniswapV2Pool or CurvePool) have no network dependencies. They do not import ProviderAdapter or perform async calls. This makes them highly testable, performant, and easy to snapshot or pickle.
• Builders for I/O: All network I/O (DB lookups, RPC fetches, decoding) is encapsulated within Builder classes (e.g., V2PoolBuilder, V3PoolBuilder). Builders handle the choreography of fetching data and then injecting it into the pool.
• State Updates: State changes in pools are performed via the external_update() method, which accepts a typed update object (e.g., UniswapV2PoolExternalUpdate). This method contains pure logic to validate the update and transition the pool's state without performing any I/O.
• Curve Calculators: Specifically for Curve, calculators use a DyCalculationInputs frozen dataclass to receive pre-resolved data, ensuring no private member access or hidden I/O occurs during calculation.

Degenbot uses different mathematical strategies for solving swap paths depending on the liquidity pool family to balance latency and precision. The core decision is whether to use a fast f64 (floating point) 'narrowing' pass to find a candidate optimum before performing a high-precision U256 verification sweep.

Strategy by Pool Family

Precision and Verification

When using f64 narrowing, precision loss is expected because f64 (52-bit mantissa) cannot exactly represent large U256 values (e.g., $1M 18dp pools).

• Bracketing: f64 is safe for finding the general vicinity of the optimum.
• Verification: A U256 integer verify sweep (a ±3 integer scan around the f64-derived optimum) is mandatory to catch the true maximum and ensure exactness.

Aave updates liquidity and borrow indices to reflect interest accrual over time.

Liquidity Index Update (Linear Interest)

Used for liquidity rates. It uses a linear interest calculation.

• Formula: cumulatedInterest = 1 + (rate * timeDelta / SECONDS_PER_YEAR)
• Update: newIndex = oldIndex.rayMul(cumulatedInterest)

Borrow Index Update (Compounded Interest)

Used for variable borrow rates. It uses a Taylor series approximation for compounded interest.

• Formula: newIndex = oldIndex.rayMul(cumulatedInterest)
• Implementation: Uses MathUtils.calculateCompoundedInterest which accounts for the rate per second and the time elapsed since the last update.

// Linear interest calculation
function calculateLinearInterest(uint256 rate, uint40 lastUpdateTimestamp)
    internal view returns (uint256)
{
    uint256 timeDifference = block.timestamp - uint256(lastUpdateTimestamp);
    return (rate * timeDifference) / SECONDS_PER_YEAR + WadRayMath.RAY;
}

Degenbot maintains a consistent structural pattern between its Rust core and Python implementation for managing Concentrated Liquidity (CL) pool states (like Uniswap V3/V4).

Key architectural principles:

• Flat State Structs: Both Rust and Python avoid splitting state into nested sub-structs (like Slot0Head or TickBookkeepingMap) within the main pool state. Instead, V3PoolState and V4PoolState (Rust) or UniswapV3PoolState (Python) keep fields like liquidity, sqrt_price_x96, and tick_data as flat, sibling fields.
• Trait/Protocol-based Narrowing: To solve the problem of functions needing only a subset of the state (e.g., a verifier that only needs tick data), the project uses traits in Rust and protocols in Python.
  • In Rust, the TickMap trait is used to provide a typed, narrow view of the tick-related data to consumers like the CL verifier or liquidity application paths.
  • In Python, the _HasTickData and _HasPoolLiquidityMap protocols serve the same purpose.
• Mutation Separation: Mutation paths are split at the method level. For example, apply_v3_swap handles slot0 scalars, while apply_v3_liquidity_update handles the tick map. This mirrors the Python pattern where external_update() handles scalars and update_liquidity_map() handles the tick map.

Aave handles debt repayment differently depending on whether the debt is Variable Rate or Stable Rate. Understanding these transformations is critical for calculating exact repayment amounts.

Variable Rate Repay

Variable debt uses a scaled balance approach where interest is factored into an index.

1. Validation: currentDebt must be greater than 0.
2. Calculation: The payback amount is the minimum of the requested amount or the currentDebt.
3. Scaling: The scaledAmountToBurn is calculated as payback.rayDiv(index) (using rayDivFloor in v4+).
4. Update: The _scaledBalance is reduced by the scaledAmountToBurn.

Stable Rate Repay

Stable debt tracks a principal amount and uses timestamps to calculate interest.

1. Calculation: currentDebt is derived from principal + accruedInterest (where interest is principal * compoundedInterest - principal).
2. Validation: currentDebt must be greater than 0.
3. Calculation: The payback amount is the minimum of the requested amount or the currentDebt.
4. Update: The new principal becomes currentDebt - payback, and the lastUpdateTimestamp is updated to block.timestamp.

Key Takeaways

• Repayment Methods: You can repay using the underlying tokens OR by using aTokens.
• Full Repayment: Setting the amount to MAX will clear all debt in that specific mode.

Mainnet Curve pools use different calculation formulas depending on the pool contract version. These are determined by the pool address at construction and stored as enums. There are three primary variant types:

DVariant

Identifies the calc_d / calc_dp formula pair used in _get_d().

• STANDARD: Standard formula for both.
• VARIANT_ALPHA: Variant alpha for calc_d, Standard for calc_dp.
• VARIANT_ALPHA_DP_ALPHA: Variant alpha for both.
• VARIANT_DP_ALPHA: Standard for calc_d, Variant alpha for calc_dp.
• VARIANT_BETA_DP: Standard for calc_d, Variant beta for calc_dp.
• VARIANT_GAMMA_DP: Standard for calc_d, Variant gamma for calc_dp.

YVariant

Identifies the Y-calculation formula used in _get_y(), controlling the amp divisor and c/b formula.

• STANDARD: Uses A_PRECISION for both amp divisor and c/b formula.
• VARIANT_0: Does not use A_PRECISION for either.
• VARIANT_1: Uses A_PRECISION for amp divisor, but not for c/b formula.

YDVariant

Identifies the Y_D-calculation formula used in _get_y_d(), controlling A_PRECISION in b/c formulas.

• STANDARD: Without A_PRECISION.
• VARIANT_0: With A_PRECISION.

Resolution is handled by resolve_d_variant(), resolve_y_variant(), and resolve_yd_variant() in _variant_groups.py during CurvePoolBuilder.build().