degenbot.exceptions

Exception classes for degenbot.

degenbot.exceptions is the single documented import home for every FFI-raised exception. The FFI-raised types (the PoolRegistrationError fairly, the verifier errors) are direct aliases of the degenbot._ffi pyclasses — never Python subclasses: Rust raises the pyclass instances, so except / isinstance matching requires the exact same class object. The identity contract is pinned by tests/ffi/test_companion_alias_identity.py.

Submodules

• degenbot.exceptions.arbitrage
• degenbot.exceptions.base
• degenbot.exceptions.infrastructure
• degenbot.exceptions.pool
• degenbot.exceptions.rpc
• degenbot.exceptions.verification

Package Contents

class degenbot.exceptions.ArbCalculationError

Bases: ArbitrageError

Raised when an arbitrage calculation fails.

class degenbot.exceptions.ArbitrageError

Bases: degenbot.exceptions.base.DegenbotError

Exception raised inside arbitrage helpers.

class degenbot.exceptions.DirectionResolutionError

Bases: ArbitrageError

A discovered path’s hop directions could not be resolved to a closed token cycle.

The pathfinder contract guarantees every yielded path starts and ends at one of the requested boundary tokens ({WETH, native}), so a failure here is an invariant violation between the DB subgraph edges and the constructed pool objects (e.g. a pool built with different token0/token1 than the subgraph edge used) — a bug, not a skippable condition.

class degenbot.exceptions.DuplicatePoolError(*, pool: str)

Bases: PathRejectedError

The same pool appears more than once in the path.

A degenerate, non-executable cycle. V2/V3 pools are keyed by address; V4 pools by pool_id hex. pool is the duplicated pool’s identity key.

pool

class degenbot.exceptions.HopCountExceededError(*, hop_count: int, max_hops: int)

Bases: PathRejectedError

The path exceeds the configured maximum hop count.

hop_count

max_hops

class degenbot.exceptions.HopCountInsufficientError(*, hop_count: int, min_hops: int)

Bases: PathRejectedError

The path is below the configured minimum hop count.

hop_count

min_hops

class degenbot.exceptions.IncompatiblePoolInvariant

Bases: ArbitrageError

Raised when a pool’s invariant type is not supported for.

arbitrage path construction (e.g. Aerodrome stable pools).

class degenbot.exceptions.InsufficientLiquidityError(*, liquidity: int, min_liquidity: int)

Bases: PathRejectedError

A pool’s liquidity proxy is below the configured minimum.

liquidity is the value returned by the caller-supplied liquidity_of extractor (the library does not encode pool-type-specific liquidity math).

liquidity

min_liquidity

class degenbot.exceptions.InvalidForwardAmount

Bases: ArbitrageError

InvalidForwardAmount class.

class degenbot.exceptions.InvalidSwapPathError

Bases: ArbitrageError

Raised in arbitrage helper constructors when the provided path is invalid.

class degenbot.exceptions.NoLiquidity

Bases: ArbitrageError

Raised if a pool has no liquidity for the requested operation.

class degenbot.exceptions.NoSolverSolution(message: str = 'Solver failed to converge on a solution.')

Bases: ArbitrageError

NoSolverSolution class.

message = 'Solver failed to converge on a solution.'

class degenbot.exceptions.OptimizationError(message: str, *, iterations: int = 0, method: str | None = None)

Bases: ArbitrageError

Raised when a solver fails to find a profitable solution,.

fails to converge, or receives invalid inputs.

message

Human-readable error message explaining why optimization failed.

Type:

str

iterations

Number of iterations completed before failure (if applicable).

Type:

int

method

The solver method that was attempted (if applicable).

Type:

str | None

message

iterations = 0

method = None

class degenbot.exceptions.PathRejectedError

Bases: ArbitrageError

A path candidate was rejected by a path-composition policy predicate.

Policy rejection is distinct from the Rust core’s pool admission floor (HookedPoolRejectedError / DynamicFeePoolRejectedError, which subclass ValueError). Policy rejects by deployment rule (token denylist/allowlist, hop-count, min-liquidity, duplicate-pool); admission rejects by correctness floor. Callers classify by type so the two hierarchies (ArbitrageError vs ValueError) stay separable.

class degenbot.exceptions.RateOfExchangeBelowMinimum(rate: fractions.Fraction)

Bases: ArbitrageError

The rate of exchange for the path is below the minimum.

rate

class degenbot.exceptions.TokenDenylistedError(*, token: str)

Bases: PathRejectedError

An intermediate or profit token is not permitted by the policy.

Covers both denylist membership and allowlist absence. token is the checksummed offending token address.

token

class degenbot.exceptions.Unprofitable

Bases: ArbitrageError

Unprofitable class.

exception degenbot.exceptions.DegenbotError(*, message: str | None = None)

Bases: Exception

Base exception used as the parent class for all exceptions raised by this package.

Calling code should catch DegenbotError and derived classes separately before general exceptions, e.g.:

``` try:

degenbot.some_function()

except SpecificDegenbotError:

… # handle a specific exception

except DegenbotError:

… # handle non-specific degenbot exception

except Exception:

… # handle exceptions raised by 3rd party dependencies or Python built-ins

```

An optional string-formatted message may be attached to the exception and retrieved by accessing the .message attribute.

message: str | None = None

exception degenbot.exceptions.DegenbotTypeError(*, message: str | None = None)

Bases: DegenbotError

DegenbotTypeError error.

exception degenbot.exceptions.DegenbotValueError(*, message: str | None = None)

Bases: DegenbotError

DegenbotValueError error.

exception degenbot.exceptions.AnvilError(method: str, error: str)

Bases: degenbot.exceptions.base.DegenbotError

Raised on errors resulting from failed calls to Anvil via JSON-RPC.

This exception is specifically for errors that occur when making RPC calls to an Anvil instance, such as invalid method calls, parameter errors, or other Anvil-specific failures.

method

error

exception degenbot.exceptions.BackupExists(path: pathlib.Path)

Bases: degenbot.exceptions.base.DegenbotError

Raised by degenbot database backup if a file exists at the target path.

path

exception degenbot.exceptions.Erc20TokenError(*, message: str | None = None)

Bases: degenbot.exceptions.base.DegenbotError

Exception raised inside ERC-20 token helpers.

exception degenbot.exceptions.NoPriceOracle

Bases: Erc20TokenError

Raised when .price is called on a token without a price oracle.

class degenbot.exceptions.AddressMismatch

Bases: LiquidityPoolError

The expected pool address does not match the provided address.

class degenbot.exceptions.BrokenPool

Bases: LiquidityPoolError

BrokenPool class.

class degenbot.exceptions.CurveError

Bases: degenbot.exceptions.base.DegenbotError

Base exception for Curve pool errors.

class degenbot.exceptions.EVMRevertError(error: str | None = None)

Bases: degenbot.exceptions.base.DegenbotError

Raised when a simulated EVM contract operation would revert.

error = None

class degenbot.exceptions.ExternalUpdateError

Bases: LiquidityPoolError

Raised when an external update does not pass sanity checks.

class degenbot.exceptions.HookedPoolResult(amount_in: int, amount_out: int, hooks: set[degenbot.uniswap.v4_liquidity_pool.Hooks])

Bases: PossibleInaccurateResult

Raised when a V4 pool has active hooks that may mutate the swap result.

The pool’s beforeSwap / afterSwap hooks can modify amounts or revert, so the pure-math result may differ from what the contract returns. The set of conflicting hooks is available on the hooks attribute.

hooks

class degenbot.exceptions.IncompleteSwap(amount_in: int, amount_out: int)

Bases: LiquidityPoolError

Raised if a swap calculation would not consume the input or deliver the requested output.

amount_in

amount_out

class degenbot.exceptions.InvalidSwapInputAmount

Bases: LiquidityPoolError

InvalidSwapInputAmount class.

class degenbot.exceptions.InvalidUint256

Bases: EVMRevertError

InvalidUint256 class.

class degenbot.exceptions.LateUpdateError

Bases: LiquidityPoolError

Raised when an automatic update is attempted at a block prior to the last recorded update.

class degenbot.exceptions.LiquidityMapWordMissing(word: int)

Bases: LiquidityPoolError

A word bitmap is not included in the liquidity map.

word

class degenbot.exceptions.LiquidityPoolError

Bases: degenbot.exceptions.base.DegenbotError

Exception raised inside liquidity pool helpers.

class degenbot.exceptions.MissingCurveData(pool_address: str, data_type: str, message: str)

Bases: CurveError

Raised when on-chain data is needed but no fetcher is available.

pool_address

data_type

class degenbot.exceptions.NoPoolStateAvailable(block: degenbot.types.aliases.BlockNumber)

Bases: LiquidityPoolError

Raised when a previous pool state is not available.

This can occur, e.g. if a pool was created in a block at or after a re-organization.

class degenbot.exceptions.PoolCreationFailed

Bases: TrackerError

PoolCreationFailed class.

class degenbot.exceptions.PoolNotAssociated(pool_address: str)

Bases: TrackerError

Raised by a pool tracker if a requested pool address is not associated with the DEX.

class degenbot.exceptions.PossibleInaccurateResult(amount_in: int, amount_out: int, *, message: str)

Bases: LiquidityPoolError

Raised when a swap calculation may not match the on-chain result.

The computed amount_in and amount_out are available on the exception so callers can inspect or use the approximate values after explicitly catching this exception.

Subclasses add domain-specific context (hooks, stale rates, etc.).

amount_in

amount_out

class degenbot.exceptions.StaleRateResult(amount_in: int, amount_out: int)

Bases: PossibleInaccurateResult

Raised when a Balancer ComposableStablePool’s rate cache is stale.

ComposableStablePools with time-varying rates (e.g. bb-a-* yield tokens) cache rates in _tokenRateCaches and refresh them before each swap via _beforeSwapJoinExit(). Without a live BalancerRateProvider, the pool uses construction-time rates that become stale as blocks pass. The computed amounts are available but may not match on-chain execution.

class degenbot.exceptions.TrackerAlreadyInitialized

Bases: TrackerError

Raised by a pool tracker if a caller attempts to create from a known factory address.

class degenbot.exceptions.TrackerError

Bases: degenbot.exceptions.base.DegenbotError

Exception raised inside pool tracker helpers.

class degenbot.exceptions.UnknownPool(pool: degenbot.types.chain.ChecksummedAddress)

Bases: LiquidityPoolError

Raised when an update is provided for a pool not in the snapshot.

Such updates can lead to inconsistent state because the pool state prior to the update is unknown.

class degenbot.exceptions.UnknownPoolId(pool_id: bytes | str)

Bases: LiquidityPoolError

Raised when an update is provided for a pool ID not in the snapshot.

Such updates can lead to inconsistent state because the pool state prior to the update is unknown.

class degenbot.exceptions.ContractLogicError(message: str = '')

Bases: RpcError

An eth_call execution revert reported by the provider.

The degenbot-owned equivalent of web3.exceptions.ContractLogicError. Raised at the provider adapter seam (see degenbot.provider.alloy_errors.alloy_revert_error()) so probe sites catch one type regardless of backend.

Constructed with a positional revert message (mirroring the web3 type’s constructor) so call sites can write ContractLogicError("... reverted") `` and ``str(exc) returns that message.

message = None

class degenbot.exceptions.RpcError

Bases: degenbot.exceptions.base.DegenbotError

Base for provider/RPC-layer failures.

The degenbot-owned equivalent of web3.exceptions.Web3Exception: the broad base a caller can catch to mean “an RPC call failed for some reason.” Probe sites catch this instead of backend-specific native types, so they remain backend-agnostic.

class degenbot.exceptions.TransactionNotFound

Bases: RpcError

A transaction hash the provider could not find.

The degenbot-owned equivalent of web3.exceptions.TransactionNotFound. Raised by the provider adapter seam when a receipt lookup misses.