agent0.hyperfuzz.system_fuzz

System level fuzz bots.

Submodules

Functions

`run_invariant_checks`(...)	Run the invariant checks.
`generate_fuzz_hyperdrive_config`(...)	Fuzz over hyperdrive config.
`run_fuzz_bots`(...)	Runs fuzz bots on a hyperdrive pool.

Package Contents

agent0.hyperfuzz.system_fuzz.run_invariant_checks(check_block_data: web3.types.BlockData, interface: agent0.ethpy.hyperdrive.HyperdriveReadInterface, log_to_rollbar: bool = True, rollbar_log_level_threshold: int | None = None, rollbar_log_filter_func: Callable[[Exception], bool] | None = None, pool_name: str | None = None, lp_share_price_test: bool | None = None, crash_report_additional_info: dict[str, Any] | None = None, log_anvil_state_dump: bool = False, pending_pool_state: agent0.ethpy.hyperdrive.state.pool_state.PoolState | None = None, check_price_spike: bool = True) → list[agent0.hyperfuzz.FuzzAssertionException]

Run the invariant checks.

# Invariance checks (these should be True): - hyperdrive base & eth balances are zero - the expected total shares equals the hyperdrive balance in the vault contract - the pool has more than the minimum share reserves - the system is solvent, i.e. (share reserves - long exposure in shares - min share reserves) > 0 - present value is greater than idle shares - the lp share price doesn’t exceed an amount from block to block - check negative interest on yield source - Warn if a trade causes a large rate spike; which is a precursor to an attack

Parameters:

check_block_data (BlockData) – The current block to be tested.
interface (HyperdriveReadInterface) – An instantiated HyperdriveReadInterface object constructed using the script arguments.
log_to_rollbar (bool) – If True, log to rollbar if any invariant check fails.
rollbar_log_level_threshold (int | None, optional) – Threshold for logging to rollbar.
rollbar_log_filter_func (Callable[[Exception], bool] | None) – A function that filters exceptions to log to rollbar. The function should return True for exceptions that should be filtered from rollbar logging. Defaults to logging all exceptions.
pool_name (str | None) – The name of the pool for crash reporting information.
lp_share_price_test (bool | None, optional) – If True, only test the lp share price. If False, skips the lp share price test. If None (default), runs all tests.
crash_report_additional_info (dict[str, Any] | None) – Additional information to include in the crash report.
log_anvil_state_dump (bool) – If True, log anvil state dump on crash.
pending_pool_state (BlockData | None, optional) – The pool state for the pending block. If None, assumes the block is ticking in the background and will maintain the pending block itself.
check_price_spike (bool) – If True, check price spike

Returns:

A list of FuzzAssertionExceptions, one for each failed invariant check.

Return type:

list[FuzzAssertionException]

agent0.hyperfuzz.system_fuzz.generate_fuzz_hyperdrive_config(rng: numpy.random.Generator, lp_share_price_test: bool, steth: bool) → agent0.LocalHyperdrive.Config

Fuzz over hyperdrive config.

Parameters:

rng (np.random.Generator) – Random number generator.
lp_share_price_test (bool) – If True, uses lp share price test fuzz parameters.
steth (bool) – If True, uses steth instead of erc4626

Returns:

Fuzzed hyperdrive config.

Return type:

LocalHyperdrive.Config

agent0.hyperfuzz.system_fuzz.run_fuzz_bots(chain: agent0.Chain, hyperdrive_pools: agent0.Hyperdrive | Sequence[agent0.Hyperdrive], check_invariance: bool, num_random_agents: int | None = None, num_random_hold_agents: int | None = None, agents: Sequence[agent0.core.hyperdrive.interactive.hyperdrive_agent.HyperdriveAgent] | None = None, base_budget_per_bot: fixedpointmath.FixedPoint | None = None, eth_budget_per_bot: fixedpointmath.FixedPoint | None = None, slippage_tolerance: fixedpointmath.FixedPoint | None = None, raise_error_on_crash: bool = False, raise_error_on_failed_invariance_checks: bool = False, ignore_raise_error_func: Callable[[Exception], bool] | None = None, minimum_avg_agent_base: fixedpointmath.FixedPoint | None = None, minimum_avg_agent_eth: fixedpointmath.FixedPoint | None = None, log_to_rollbar: bool = True, run_async: bool = False, random_advance_time: bool = False, random_variable_rate: bool = False, num_iterations: int | None = None, lp_share_price_test: bool = False, whale_accounts: dict[eth_typing.ChecksumAddress, eth_typing.ChecksumAddress] | None = None, accrue_interest_func: Callable[[agent0.ethpy.hyperdrive.HyperdriveReadWriteInterface, fixedpointmath.FixedPoint, int], None] | None = None, accrue_interest_rate: fixedpointmath.FixedPoint | None = None) → Sequence[agent0.core.hyperdrive.interactive.hyperdrive_agent.HyperdriveAgent]

Runs fuzz bots on a hyperdrive pool.

Parameters:

chain (Chain) – The chain to run the bots on.
hyperdrive_pools (Hyperdrive | Sequence[Hyperdrive]) – The hyperdrive pool(s) to run the bots on.
check_invariance (bool) – If True, will run invariance checks after each set of trades.
agents (Sequence[HyperdriveAgent] | None, optional) – The agents making trades. If None, will create random agents.
num_random_agents (int | None, optional) – The number of random agents to create. Defaults to 2.
num_random_hold_agents (int | None, optional) – The number of random agents to create. Defaults to 2.
base_budget_per_bot (FixedPoint | None, optional) – The base budget per bot. Defaults to 10_000_000
eth_budget_per_bot (FixedPoint | None, optional) – The ETH budget per bot. Defaults to 1_000
slippage_tolerance (FixedPoint | None, optional) – The slippage tolerance. Defaults to 1% slippage
raise_error_on_crash (bool, optional) – If True, will exit the process if a bot crashes. Defaults to False.
raise_error_on_failed_invariance_checks (bool, optional) – If True, will exit the process if the pool fails an invariance check. Defaults to False.
ignore_raise_error_func (Callable[[Exception], bool] | None, optional) – A function that determines if an exception should be ignored when raising error on crash. The function takes an exception as an an argument and returns True if the exception should be ignored. Defaults to raising all errors.
minimum_avg_agent_base (FixedPoint | None, optional) – The minimum average agent base. Will refund bots if average agent base drops below this. Defaults to 1/10 of base_budget_per_bot
minimum_avg_agent_eth (FixedPoint | None, optional) – The minimum average agent eth. Will refund bots if average agent base drops below this. Defaults to 1/10 of eth_budget_per_bot
log_to_rollbar (bool, optional) – If True, log errors rollbar. Defaults to True.
run_async (bool, optional) – If True, will run the bots asynchronously. Defaults to False.
random_advance_time (bool, optional) – If True, will advance the time randomly between sets of trades. Defaults to False.
random_variable_rate (bool, optional) – If True, will randomly change the rate between sets of trades. Defaults to False.
num_iterations (int | None, optional) – The number of iterations to run. Defaults to None (infinite)
lp_share_price_test (bool, optional) – If True, will test the LP share price. Defaults to False.
whale_accounts (dict[ChecksumAddress, ChecksumAddress] | None, optional) – A mapping between token -> whale addresses to use to fund the fuzz agent. If the token is not in the mapping, fuzzing will attempt to call mint on the token contract. Defaults to an empty mapping.
accrue_interest_func (Callable[[HyperdriveReadWriteInterface, FixedPoint, int], None] | None, optional) – A function that will accrue interest on the hyperdrive pool. This function will get called after advancing time, with the following signature: accrue_interest_func(hyperdrive_interface, variable_rate, block_number_before_advance).
accrue_interest_rate (FixedPoint | None, optional) – The variable rate to be passed into the accrue_interest_func. Note this value is only used when forking, as variable interest is handled by a mock yield source when simulating. If random_variable_rate is True, this value will be ignored.

Returns:

The set of agents making trades.

Return type:

Sequence[HyperdriveAgent]