agent0.ethpy.hyperdrive.interface

High-level interface for the Hyperdrive market.

Submodules

Classes

`HyperdriveReadInterface`	Read-only end-point API for interfacing with a deployed Hyperdrive pool.
`HyperdriveReadWriteInterface`	Read-write end-point API for interfacing with a deployed Hyperdrive pool.

Package Contents

class agent0.ethpy.hyperdrive.interface.HyperdriveReadInterface(hyperdrive_address: eth_typing.ChecksumAddress, rpc_uri: str | None = None, web3: web3.Web3 | None = None, txn_receipt_timeout: float | None = None, txn_signature: bytes | None = None)

Read-only end-point API for interfacing with a deployed Hyperdrive pool.

class HyperdriveKind

Bases: enum.Enum

Hyperdrive contract kind.

NOTE the values of these enums match the output of the kind() function from the hyperdrive contract.

ERC4626 = 'ERC4626Hyperdrive'

STETH = 'StETHHyperdrive'

MORPHO = 'MorphoBlueHyperdrive'

EZETH = 'EzETHHyperdrive'

RETH = 'RETHHyperdrive'

STKWELL = 'StkWellHyperdrive'

EETH = 'EETHHyperdrive'

hyperdrive_address

web3 = None

hyperdrive_contract

hyperdrive_version

pool_config

hyperdrive_name

morpho_contract = None

morpho_market_id = None

base_token_contract: hyperdrivetypes.types.ERC20MintableContract

txn_receipt_timeout = None

last_state_block_number = -1

get_deploy_block_number() → eth_typing.BlockNumber | None

Get the block number that the Hyperdrive contract was deployed on.

NOTE: The deploy event may get lost on e.g., anvil, so we ensure we only check once

Returns:: The block number that the Hyperdrive contract was deployed on. Returns None if it can’t be found.
Return type:: BlockNumber | None

property current_pool_state: agent0.ethpy.hyperdrive.state.PoolState

The current state of the pool.

Each time this is accessed we use an RPC to check that the pool state is synced with the current block.

get_current_block() → web3.types.BlockData

Use an RPC to get the current block.

Returns:: A web3py dataclass containing information about the latest mined block.
Return type:: BlockData

get_block(block_identifier: web3.types.BlockIdentifier) → web3.types.BlockData

Use an RPC to get the block for the provided identifier.

Delegates to eth_getBlockByNumber if block_identifier is an integer or one of the predefined block parameters ‘latest’, ‘earliest’, ‘pending’, ‘safe’, ‘finalized’. Otherwise delegates to eth_getBlockByHash. Throws BlockNotFound error if the block is not found.

Parameters:: block_identifier (BlockIdentifier) – Any one of the web3py types: [BlockParams, BlockNumber, Hash32, HexStr, HexBytes, int].
Returns:: A web3py dataclass containing block information.
Return type:: BlockData

get_block_number(block: web3.types.BlockData) → eth_typing.BlockNumber

Use an RPC to get the number for the provided block.

Parameters:: block (BlockData) – A web3py dataclass for storing block information.
Returns:: The number for the corresponding block.
Return type:: BlockNumber

get_block_timestamp(block: web3.types.BlockData) → web3.types.Timestamp

Use an RPC to get the time for the provided block.

Parameters:: block (BlockData) – A web3py dataclass for storing block information.
Returns:: The integer timestamp, in seconds, for the corresponding block.
Return type:: Timestamp

get_hyperdrive_state(block_identifier: web3.types.BlockIdentifier | None = None, block_data: web3.types.BlockData | None = None) → agent0.ethpy.hyperdrive.state.PoolState

Use RPCs and contract calls to get the Hyperdrive pool and block state, given a block identifier.

Parameters:

block_identifier (BlockIdentifier, optional) – The block identifier to get hyperdrive state on.
block_data (BlockData, optional) – The block data to use to get hyperdrive state. This parameter is useful for reusing a previously retrieved block data. Can’t provide both block_identifier and block_data at the same time.

Returns:

A dataclass containing PoolInfo, PoolConfig, Checkpoint, and Block information that is synced to a given block number.

Return type:

PoolState

get_checkpoint(checkpoint_time: web3.types.Timestamp, block_identifier: web3.types.BlockIdentifier | None = None) → hyperdrivetypes.CheckpointFP

Use an RPC to get the checkpoint info for the Hyperdrive contract for a given checkpoint_time index.

Parameters:

checkpoint_time (Timestamp) – The block timestamp that indexes the checkpoint to get.
block_identifier (BlockIdentifier, optional) – The identifier for a block. If not given, the latest block is used.

Returns:

The dataclass containing the checkpoint info in fixed point

Return type:

CheckpointFP

get_minimum_transaction_amount_shares(block_identifier: web3.types.BlockIdentifier | None = None) → fixedpointmath.FixedPoint

Use an RPC to get the minimum transaction amount in units of shares at the given block.

Parameters:: block_identifier (BlockIdentifier, optional) – The identifier for a block. If not given, the latest block number is used.
Returns:: The quantity of withdrawal shares available in the Hyperdrive pool.
Return type:: FixedPoint

get_total_supply_withdrawal_shares(block_identifier: web3.types.BlockIdentifier | None = None) → fixedpointmath.FixedPoint

Use an RPC to get the total supply of withdrawal shares in the pool at the given block.

Parameters:: block_identifier (BlockIdentifier, optional) – The identifier for a block. If not given, the latest block number is used.
Returns:: The quantity of withdrawal shares available in the Hyperdrive pool.
Return type:: FixedPoint

get_vault_shares(block_identifier: web3.types.BlockIdentifier | None = None) → fixedpointmath.FixedPoint

Use an RPC to get the balance of shares that the Hyperdrive pool has in the underlying yield source.

Parameters:: block_identifier (BlockNumber, optional) – The identifier for a block. Defaults to the current block number.
Returns:: The quantity of vault shares for the yield source at the provided block.
Return type:: FixedPoint

get_idle_shares(pool_state: agent0.ethpy.hyperdrive.state.PoolState | None = None) → fixedpointmath.FixedPoint

Get the balance of idle shares that the Hyperdrive pool has.

Parameters:: pool_state (PoolState | None, optional) – The state of the pool, which includes block details, pool config, and pool info. If not given, use the current pool state.
Returns:: The quantity of vault shares for the yield source at the provided block.
Return type:: FixedPoint

get_variable_rate(block_identifier: web3.types.BlockIdentifier | None = None) → fixedpointmath.FixedPoint | None

Use an RPC to get the yield source variable rate.

Note

This function assumes there exists an underlying getRate function in the contract.

This call will return None if the deployed yield contract doesn’t have a getRate function. In this case, use get_standardized_variable_rate instead.

Parameters:: block_identifier (BlockIdentifier, optional) – The identifier for a block. Defaults to the current block number.
Returns:: The variable rate for the yield source at the provided block, or None if the yield source doesn’t have a getRate function.
Return type:: FixedPoint | None

get_standardized_variable_rate(time_range: int = 604800) → fixedpointmath.FixedPoint

Get a standardized variable rate using vault share prices from checkpoints in the last time_range seconds.

Note

This function will throw an error if the pool was deployed within the last time_range seconds.

Parameters:: time_range (int) – The time range (in seconds) to use to calculate the variable rate to look for checkpoints.
Returns:: The standardized variable rate.
Return type:: FixedPoint

get_eth_base_balances(agent: eth_account.signers.local.LocalAccount) → tuple[fixedpointmath.FixedPoint, fixedpointmath.FixedPoint]

Use an RPC to get the agent’s balance on the Base & Hyperdrive contracts.

Parameters:: agent (LocalAccount) – The account for the agent that is executing and signing the trade transaction.
Returns:: A tuple containing the [agent_eth_balance, agent_base_balance].
Return type:: tuple[FixedPoint]

get_hyperdrive_eth_balance() → fixedpointmath.FixedPoint

Get the current Hyperdrive eth balance from an RPC.

Returns:: The eth on the chain.
Return type:: FixedPoint

get_hyperdrive_base_balance(block_identifier: web3.types.BlockIdentifier | None = None) → fixedpointmath.FixedPoint

Get the current Hyperdrive balance in the base contract.

Parameters:: block_identifier (BlockIdentifier, optional) – The identifier for a block. Defaults to the current block number.
Returns:: The result of base_token_contract.balanceOf(hyperdrive_address).
Return type:: FixedPoint

get_gov_fees_accrued(block_identifier: web3.types.BlockIdentifier | None = None) → fixedpointmath.FixedPoint

Get the current amount of Uncollected Governance Fees in the Hyperdrive contract.

Parameters:: block_identifier (BlockIdentifier, optional) – The identifier for a block. Defaults to the current block number.
Returns:: The result of hyperdrive_contract.functions.getUncollectedGovernanceFees
Return type:: FixedPoint

get_long_total_supply(maturity_time: int, block_identifier: web3.types.BlockIdentifier | None = None) → fixedpointmath.FixedPoint

Get the total supply of long tokens with the given maturity time.

Parameters:

maturity_time (int) – The maturity time in seconds.
block_identifier (BlockIdentifier, optional) – The identifier for a block. Defaults to the current block number.

Returns:

The result of the total supply of long tokens with the given maturity time.

Return type:

FixedPoint

get_short_total_supply(maturity_time: int, block_identifier: web3.types.BlockIdentifier | None = None) → fixedpointmath.FixedPoint

Get the total supply of short tokens with the given maturity time.

Parameters:

maturity_time (int) – The maturity time in seconds.
block_identifier (BlockIdentifier, optional) – The identifier for a block. Defaults to the current block number.

Returns:

The result of the total supply of short tokens with the given maturity time.

Return type:

FixedPoint

get_pool_is_paused() → bool

Get whether or not the pool is paused from events.

Returns:: Whether or not the pool is paused.
Return type:: bool

calc_position_duration_in_years(pool_state: agent0.ethpy.hyperdrive.state.PoolState | None = None) → fixedpointmath.FixedPoint

Return the pool config position duration as a fraction of a year.

This “annualized” time value is used in some calculations, such as the Fixed APR. The function does not perform contract calls, but instead relies on the Hyperdrive-rust api to simulate the contract outputs.

Parameters:: pool_state (PoolState | None, optional) – The state of the pool, which includes block details, pool config, and pool info. If not given, use the current pool state.
Returns:: The annualized position duration
Return type:: FixedPoint

calc_time_stretch(target_rate: fixedpointmath.FixedPoint, target_position_duration: fixedpointmath.FixedPoint) → fixedpointmath.FixedPoint

Return the time stretch parameter given a target fixed rate and position duration.

Parameters:

target_rate (FixedPoint) – The fixed rate that the Hyperdrive pool will be initialized with.
target_position_duration (FixedPoint) – The position duration that the Hyperdrive pool will be initialized with.

Returns:

The time stretch constant.

Return type:

FixedPoint

calc_checkpoint_timestamp(time: int | web3.types.Timestamp, pool_state: agent0.ethpy.hyperdrive.state.PoolState | None = None) → web3.types.Timestamp

Converts a timestamp to the checkpoint timestamp that it corresponds to.

Parameters:

time (int | Timestamp) – Any timestamp (in seconds) before or at the present.
pool_state (PoolState | None, optional) – The state of the pool, which includes block details, pool config, and pool info. If not given, use the current pool state.

Returns:

The checkpoint timestamp.

Return type:

Timestamp

calc_checkpoint_id(checkpoint_duration: int | None = None, block_timestamp: web3.types.Timestamp | None = None) → web3.types.Timestamp

Calculate the Checkpoint ID for a given timestamp.

The function does not perform contract calls, but instead relies on the Hyperdrive-rust api to simulate the contract outputs.

Parameters:

checkpoint_duration (int, optional) – The time, in seconds, between checkpoints. Defaults to the current pool’s checkpoint duration.
block_timestamp (Timestamp, optional) – A timestamp for any block. Use the latest block to get the current checkpoint id, or a specific timestamp of a transaction’s block if getting the checkpoint id for that transaction. Defaults to the current block timestamp.

Returns:

The checkpoint id, in units of seconds, which represents the time of the last checkpoint.

Return type:

int

calc_spot_rate(pool_state: agent0.ethpy.hyperdrive.state.PoolState | None = None) → fixedpointmath.FixedPoint

Calculate the spot fixed rate for a given pool state.

The function does not perform contract calls, but instead relies on the Hyperdrive-rust api to simulate the contract outputs. The simulation follows the formula:

\[r = ((1 / p) - 1) / t = (1 - p) / (p * t)\]

Parameters:: pool_state (PoolState | None, optional) – The state of the pool, which includes block details, pool config, and pool info. If not given, use the current pool state.
Returns:: The fixed rate apr for the Hyperdrive pool state.
Return type:: FixedPoint

calc_rate_given_fixed_price(price: fixedpointmath.FixedPoint, position_duration: fixedpointmath.FixedPoint) → fixedpointmath.FixedPoint

Calculate the rate assuming a given price is constant for some annualized duration.

We calculate the rate for a fixed length of time as:

..math::: r = (1 - p) / (p t)

where $p$ is the price and $t$ is the length of time that this price is assumed to be constant, in units of years. For example, if the price is constant for 6 months, then $t=0.5$. In our case, $t = text{position_duration} / (60*60*24*365)$.

Parameters:

price (FixedPoint) – The spot price of bonds fora given pool.
position_duration (FixedPoint) – The pool bond position duration, over which the price is assumed to be constant.

Returns:

The fixed rate apr for a given fixed price and position duration.

Return type:

FixedPoint

calc_spot_price(pool_state: agent0.ethpy.hyperdrive.state.PoolState | None = None) → fixedpointmath.FixedPoint

Calculate the spot price for a given Hyperdrive pool.

The function does not perform contract calls, but instead relies on the Hyperdrive-rust api to simulate the contract outputs.

Parameters:: pool_state (PoolState | None, optional) – The state of the pool, which includes block details, pool config, and pool info. If not given, use the current pool state.
Returns:: The spot price for the Hyperdrive pool state.
Return type:: FixedPoint

calc_max_spot_price(pool_state: agent0.ethpy.hyperdrive.state.PoolState | None = None) → fixedpointmath.FixedPoint

Get the pool’s max spot price.

Parameters:: pool_state (PoolState | None, optional) – The state of the pool, which includes block details, pool config, and pool info. If not given, use the current pool state.
Returns:: The pool’s maximum achievable spot price.
Return type:: FixedPoint

calc_effective_share_reserves(pool_state: agent0.ethpy.hyperdrive.state.PoolState | None = None) → fixedpointmath.FixedPoint

Calculate the adjusted share reserves for a given Hyperdrive pool.

The function does not perform contract calls, but instead relies on the Hyperdrive-rust api to simulate the contract outputs.

Parameters:: pool_state (PoolState | None, optional) – The state of the pool, which includes block details, pool config, and pool info. If not given, use the current pool state.
Returns:: The effective (aka zeta-adjusted) share reserves.
Return type:: FixedPoint

calc_idle_share_reserves_in_base(pool_state: agent0.ethpy.hyperdrive.state.PoolState | None = None) → fixedpointmath.FixedPoint

Calculates the idle share reserves in base of the pool.

Parameters:: pool_state (PoolState | None, optional) – The state of the pool, which includes block details, pool config, and pool info. If not given, use the current pool state.
Returns:: The pool’s idle share reserves in base.
Return type:: FixedPoint

calc_bonds_given_shares_and_rate(target_rate: fixedpointmath.FixedPoint, target_shares: fixedpointmath.FixedPoint | None = None, pool_state: agent0.ethpy.hyperdrive.state.PoolState | None = None) → fixedpointmath.FixedPoint

Return the bond reserves for the market share reserves and a given fixed rate.

The function does not perform contract calls, but instead relies on the Hyperdrive-rust api to simulate the contract outputs. The calculation is based on the formula:

\[\mu * (z - \zeta) * (1 + \text{apr} * t)^{1 / \tau}\]

Parameters:

target_rate (FixedPoint) – The target apr for which to calculate the bond reserves given the pools current share reserves.
target_shares (FixedPoint, optional) – The target share reserves for the pool
pool_state (PoolState | None, optional) – The state of the pool, which includes block details, pool config, and pool info. If not given, use the current pool state.

Returns:

The output bonds.

Return type:

FixedPoint

calc_open_long(base_amount: fixedpointmath.FixedPoint, pool_state: agent0.ethpy.hyperdrive.state.PoolState | None = None) → fixedpointmath.FixedPoint

Calculate the long amount that will be opened for a given base amount after fees.

The function does not perform contract calls, but instead relies on the Hyperdrive-rust api to simulate the contract outputs.

Parameters:

base_amount (FixedPoint) – The amount to spend, in base.
pool_state (PoolState | None, optional) – The state of the pool, which includes block details, pool config, and pool info. If not given, use the current pool state.

Returns:

The amount of bonds purchased.

Return type:

FixedPoint

calc_pool_deltas_after_open_long(base_amount: fixedpointmath.FixedPoint, pool_state: agent0.ethpy.hyperdrive.state.PoolState | None = None) → tuple[fixedpointmath.FixedPoint, fixedpointmath.FixedPoint]

Calculate the bond deltas to be applied to the pool after opening a long.

Parameters:

base_amount (FixedPoint) – The amount of base used to open a long.
pool_state (PoolState | None, optional) – The state of the pool, which includes block details, pool config, and pool info. If not given, use the current pool state.

Returns:

The amount of (shares, bonds) to remove from the pool reserves.

Return type:

tuple[FixedPoint, FixedPoint]

calc_spot_price_after_long(base_amount: fixedpointmath.FixedPoint, bond_amount: fixedpointmath.FixedPoint | None = None, pool_state: agent0.ethpy.hyperdrive.state.PoolState | None = None) → fixedpointmath.FixedPoint

Calculate the spot price for a given Hyperdrive pool after a long is opened for base_amount.

The function does not perform contract calls, but instead relies on the Hyperdrive-rust api to simulate the contract outputs.

Parameters:

base_amount (FixedPoint) – The amount of base provided for the long.
bond_amount (FixedPoint | None, optional) – The amount of bonds that would be purchased by the long. The default is to use whatever is returned by calc_open_long(base_amount).
pool_state (PoolState | None, optional) – The state of the pool, which includes block details, pool config, and pool info. If not given, use the current pool state.

Returns:

The spot price for the Hyperdrive pool state.

Return type:

FixedPoint

calc_spot_rate_after_long(base_amount: fixedpointmath.FixedPoint, bond_amount: fixedpointmath.FixedPoint | None = None, pool_state: agent0.ethpy.hyperdrive.state.PoolState | None = None) → fixedpointmath.FixedPoint

Calculate the spot rate for a given Hyperdrive pool after a long is opened for base_amount.

The function does not perform contract calls, but instead relies on the Hyperdrive-rust api to simulate the contract outputs.

Parameters:

base_amount (FixedPoint) – The amount of base provided for the long.
bond_amount (FixedPoint | None, optional) – The amount of bonds that would be purchased by the long. The default is to use whatever is returned by calc_open_long(base_amount).
pool_state (PoolState | None, optional) – The state of the pool, which includes block details, pool config, and pool info. If not given, use the current pool state.

Returns:

The spot rate for the Hyperdrive pool state.

Return type:

FixedPoint

calc_max_long(budget: fixedpointmath.FixedPoint, pool_state: agent0.ethpy.hyperdrive.state.PoolState | None = None) → fixedpointmath.FixedPoint

Calculate the maximum allowable long for the given Hyperdrive pool and agent budget.

The function does not perform contract calls, but instead relies on the Hyperdrive-rust api to simulate the contract outputs.

Parameters:

budget (FixedPoint) – How much money the agent is able to spend, in base.
pool_state (PoolState | None, optional) – The state of the pool, which includes block details, pool config, and pool info. If not given, use the current pool state.

Returns:

The maximum long, in units of base.

Return type:

FixedPoint

calc_close_long(bond_amount: fixedpointmath.FixedPoint, maturity_time: int, pool_state: agent0.ethpy.hyperdrive.state.PoolState | None = None) → fixedpointmath.FixedPoint

Calculate the amount of shares that will be returned after fees for closing a long.

Parameters:

bond_amount (FixedPoint) – The amount of bonds to sell.
maturity_time (int) – The maturity time of the bond.
pool_state (PoolState | None, optional) – The state of the pool, which includes block details, pool config, and pool info. If not given, use the current pool state.

Returns:

The amount of shares returned.

Return type:

FixedPoint

calc_market_value_long(bond_amount: fixedpointmath.FixedPoint, maturity_time: int, pool_state: agent0.ethpy.hyperdrive.state.PoolState | None = None) → fixedpointmath.FixedPoint

Calculate the amount of shares that will be returned after fees for closing a long.

Parameters:

bond_amount (FixedPoint) – The amount of bonds to sell.
maturity_time (int) – The maturity time of the bond.
pool_state (PoolState | None, optional) – The state of the pool, which includes block details, pool config, and pool info. If not given, use the current pool state.

Returns:

An estimate of the amount of shares returned upon closing the long.

Return type:

FixedPoint

calc_targeted_long(budget: fixedpointmath.FixedPoint, target_rate: fixedpointmath.FixedPoint, max_iterations: int | None = None, allowable_error: fixedpointmath.FixedPoint | None = None, pool_state: agent0.ethpy.hyperdrive.state.PoolState | None = None) → fixedpointmath.FixedPoint

Calculate the amount of bonds that can be purchased for the given budget.

Parameters:

budget (FixedPont) – The account budget in base for making a long.
target_rate (FixedPoint) – The target fixed rate.
max_iterations (int | None, optional) – The number of iterations to use for the Newtonian method. Defaults to 7.
allowable_error (FixedPoint | None, optional) – The amount of error supported for reaching the target rate. Defaults to 1e-4.
pool_state (PoolState | None, optional) – The state of the pool, which includes block details, pool config, and pool info. If not given, use the current pool state.

Returns:

The amount of shares returned.

Return type:

FixedPoint

calc_open_short(bond_amount: fixedpointmath.FixedPoint, pool_state: agent0.ethpy.hyperdrive.state.PoolState | None = None) → fixedpointmath.FixedPoint

Calculate the amount of base the trader will need to deposit for a short of a given size, after fees.

The function does not perform contract calls, but instead relies on the Hyperdrive-rust api to simulate the contract outputs.

Parameters:

bond_amount (FixedPoint) – The amount to of bonds to short.
pool_state (PoolState | None, optional) – The state of the pool, which includes block details, pool config, and pool info. If not given, use the current pool state.

Returns:

The amount of base required to short the bonds (aka the “max loss”).

Return type:

FixedPoint

calc_pool_share_delta_after_open_short(bond_amount: fixedpointmath.FixedPoint, pool_state: agent0.ethpy.hyperdrive.state.PoolState | None = None) → fixedpointmath.FixedPoint

Calculate the amount of shares the pool will add after opening a short.

Parameters:

bond_amount (FixedPoint) – The amount to of bonds to short.
pool_state (PoolState | None, optional) – The state of the pool, which includes block details, pool config, and pool info. If not given, use the current pool state.

Returns:

The amount of shares to add to the pool reserves.

Return type:

FixedPoint

calc_spot_price_after_short(bond_amount: fixedpointmath.FixedPoint, base_amount: fixedpointmath.FixedPoint | None = None, pool_state: agent0.ethpy.hyperdrive.state.PoolState | None = None) → fixedpointmath.FixedPoint

Calculate the spot price for a given Hyperdrive pool after a short is opened for base_amount.

The function does not perform contract calls, but instead relies on the Hyperdrive-rust api to simulate the contract outputs.

Parameters:

bond_amount (FixedPoint) – The amount that woud be used to open a short.
base_amount (FixedPoint | None, optional) – The amount of base provided for the short. The default is to use whatever is returned by calc_open_short(bond_amount).
pool_state (PoolState | None, optional) – The state of the pool, which includes block details, pool config, and pool info. If not given, use the current pool state.

Returns:

The spot price for the Hyperdrive pool state.

Return type:

FixedPoint

calc_max_short(budget: fixedpointmath.FixedPoint, pool_state: agent0.ethpy.hyperdrive.state.PoolState | None = None) → fixedpointmath.FixedPoint

Calculate the maximum allowable short for the given Hyperdrive pool and agent budget.

The function does not perform contract calls, but instead relies on the Hyperdrive-rust api to simulate the contract outputs.

Parameters:

budget (FixedPoint) – How much money the agent is able to spend, in base.
pool_state (PoolState | None, optional) – The state of the pool, which includes block details, pool config, and pool info. If not given, use the current pool state.

Returns:

The maximum short, in units of bonds.

Return type:

FixedPoint

calc_close_short(bond_amount: fixedpointmath.FixedPoint, open_vault_share_price: fixedpointmath.FixedPoint, close_vault_share_price: fixedpointmath.FixedPoint, maturity_time: int, pool_state: agent0.ethpy.hyperdrive.state.PoolState | None = None) → fixedpointmath.FixedPoint

Get the amount of shares the trader will receive from closing a short.

Parameters:

bond_amount (FixedPoint) – The amount to of bonds provided.
open_vault_share_price (FixedPoint) – The checkpoint share price when the short was opened.
close_vault_share_price (FixedPoint) – The share price when the short was closed. If the short isn’t mature, this is the current share price. If the short is mature, this is the share price of the maturity checkpoint.
maturity_time (int) – The maturity time of the short.
pool_state (PoolState | None, optional) – The state of the pool, which includes block details, pool config, and pool info. If not given, use the current pool state.

Returns:

The amount of shares the trader will receive for closing the short.

Return type:

FixedPoint

calc_market_value_short(bond_amount: fixedpointmath.FixedPoint, open_vault_share_price: fixedpointmath.FixedPoint, close_vault_share_price: fixedpointmath.FixedPoint, maturity_time: int, pool_state: agent0.ethpy.hyperdrive.state.PoolState | None = None) → fixedpointmath.FixedPoint

Estimates the current market value of an open short position.

Parameters:

bond_amount (FixedPoint) – The amount to of bonds provided.
open_vault_share_price (FixedPoint) – The checkpoint share price when the short was opened.
close_vault_share_price (FixedPoint) – The share price when the short was closed. If the short isn’t mature, this is the current share price. If the short is mature, this is the share price of the maturity checkpoint.
maturity_time (int) – The maturity time of the short.
pool_state (PoolState | None, optional) – The state of the pool, which includes block details, pool config, and pool info. If not given, use the current pool state.

Returns:

An estimate of the amount of shares returned upon closing the short.

Return type:

FixedPoint

calc_present_value(pool_state: agent0.ethpy.hyperdrive.state.PoolState | None = None) → fixedpointmath.FixedPoint

Calculate the present value of LPs capital in the pool.

Parameters:: pool_state (PoolState | None, optional) – The state of the pool, which includes block details, pool config, and pool info. If not given, use the current pool state.
Returns:: The present value of all LP capital in the pool.
Return type:: FixedPoint

calc_solvency(pool_state: agent0.ethpy.hyperdrive.state.PoolState | None = None) → fixedpointmath.FixedPoint

Calculate the pool’s solvency.

Parameters:: pool_state (PoolState | None, optional) – The state of the pool, which includes block details, pool config, and pool info. If not given, use the current pool state.
Returns:: solvency = share_reserves - long_exposure / vault_share_price - minimum_share_reserves
Return type:: FixedPoint

calc_bonds_out_given_shares_in_down(amount_in: fixedpointmath.FixedPoint, pool_state: agent0.ethpy.hyperdrive.state.PoolState | None = None) → fixedpointmath.FixedPoint

Calculate the amount of bonds a user will receive from the pool by providing a specified amount of shares.

We underestimate the amount of bonds. The amount returned is before fees are applied. The function does not perform contract calls, but instead relies on the Hyperdrive-rust api to simulate the contract outputs.

Parameters:

amount_in (FixedPoint) – The amount of shares going into the pool.
pool_state (PoolState | None, optional) – The state of the pool, which includes block details, pool config, and pool info. If not given, use the current pool state.

Returns:

The amount of bonds out.

Return type:

FixedPoint

calc_shares_in_given_bonds_out_up(amount_in: fixedpointmath.FixedPoint, pool_state: agent0.ethpy.hyperdrive.state.PoolState | None = None) → fixedpointmath.FixedPoint

Calculate the amount of shares a user must provide the pool to receive a specified amount of bonds.

We overestimate the amount of shares in. The amount returned is before fees are applied. The function does not perform contract calls, but instead relies on the Hyperdrive-rust api to simulate the contract outputs.

Parameters:

amount_in (FixedPoint) – The amount of bonds to target.
pool_state (PoolState | None, optional) – The state of the pool, which includes block details, pool config, and pool info. If not given, use the current pool state.

Returns:

The amount of shares in to reach the target.

Return type:

FixedPoint

calc_shares_in_given_bonds_out_down(amount_in: fixedpointmath.FixedPoint, pool_state: agent0.ethpy.hyperdrive.state.PoolState | None = None) → fixedpointmath.FixedPoint

Calculate the amount of shares a user must provide the pool to receive a specified amount of bonds.

We underestimate the amount of shares in. The amount returned is before fees are applied. The function does not perform contract calls, but instead relies on the Hyperdrive-rust api to simulate the contract outputs.

Parameters:

amount_in (FixedPoint) – The amount of bonds to target.
pool_state (PoolState | None, optional) – The state of the pool, which includes block details, pool config, and pool info. If not provided, use the current pool state.

Returns:

The amount of shares in to reach the target.

Return type:

FixedPoint

calc_shares_out_given_bonds_in_down(amount_in: fixedpointmath.FixedPoint, pool_state: agent0.ethpy.hyperdrive.state.PoolState | None = None) → fixedpointmath.FixedPoint

Calculate the amount of shares a user will receive from the pool by providing a specified amount of bonds.

We underestimate the amount of shares out. The amount returned is before fees are applied. The function does not perform contract calls, but instead relies on the Hyperdrive-rust api to simulate the contract outputs.

Parameters:

amount_in (FixedPoint) – The amount of bonds in.
pool_state (PoolState | None, optional) – The state of the pool, which includes block details, pool config, and pool info. If not provided, use the current pool state.

Returns:

The amount of shares out.

Return type:

FixedPoint

class agent0.ethpy.hyperdrive.interface.HyperdriveReadWriteInterface(hyperdrive_address: eth_typing.ChecksumAddress, rpc_uri: str | None = None, web3: web3.Web3 | None = None, txn_receipt_timeout: float | None = None, txn_signature: bytes | None = None)

Bases: agent0.ethpy.hyperdrive.interface.read_interface.HyperdriveReadInterface

Read-write end-point API for interfacing with a deployed Hyperdrive pool.

get_read_interface() → agent0.ethpy.hyperdrive.interface.read_interface.HyperdriveReadInterface

Return the current instance as an instance of the parent (HyperdriveReadInterface) class.

Returns:: This instantiated object, but as a ReadInterface.
Return type:: HyperdriveReadInterface

create_checkpoint(sender: eth_account.signers.local.LocalAccount, checkpoint_time: int | None = None, preview: bool = False, gas_limit: int | None = None, nonce_func: Callable[[], web3.types.Nonce] | None = None) → hyperdrivetypes.CreateCheckpointEventFP

Create a Hyperdrive checkpoint.

Parameters:

sender (LocalAccount) – The sender account that is executing and signing the trade transaction.
checkpoint_time (int, optional) – The checkpoint time to use. Defaults to the corresponding checkpoint for the provided block_number
preview (bool, optional) – Whether to preview the transaction first for error catching.
gas_limit (int | None, optional) – The maximum amount of gas used by the transaction.
nonce_func (Callable[[], Nonce] | None) – A callable function to use to get a nonce. This function is useful for e.g., passing in a safe nonce getter tied to an agent.

Returns:

A dataclass containing the output event of the contract call.

Return type:

CreateCheckpoint

set_variable_rate(sender: eth_account.signers.local.LocalAccount, new_rate: fixedpointmath.FixedPoint) → None

Set the variable rate for the yield source.

Note

This function assumes there’s an underlying setRate function in the contract.

This call will fail if the deployed yield contract doesn’t have a setRate function.

Parameters:

sender (LocalAccount) – The sender account that is executing and signing the trade transaction.
new_rate (FixedPoint) – The new variable rate for the yield source.

async async_open_long(sender: eth_account.signers.local.LocalAccount, trade_amount: fixedpointmath.FixedPoint, slippage_tolerance: fixedpointmath.FixedPoint | None = None, gas_limit: int | None = None, txn_options_base_fee_multiple: float | None = None, txn_options_priority_fee_multiple: float | None = None, nonce_func: Callable[[], web3.types.Nonce] | None = None, preview_before_trade: bool = False) → hyperdrivetypes.OpenLongEventFP

Contract call to open a long position.

Parameters:

sender (LocalAccount) – The account that is executing and signing the trade transaction.
trade_amount (FixedPoint) – The size of the position, in base.
slippage_tolerance (FixedPoint, optional) – Amount of slippage allowed from the trade. If given, then the trade will not execute unless the slippage is below this value. If not given, then execute the trade regardless of the slippage.
gas_limit (int | None, optional) – The maximum amount of gas used by the transaction. Defaults to eth_estimateGas RPC output.
txn_options_base_fee_multiple (float | None, optional) – The multiple applied to the base fee for the transaction. Defaults to 1.
txn_options_priority_fee_multiple (float | None, optional) – The multiple applied to the priority fee for the transaction. Defaults to 1.
nonce_func (Callable[[], Nonce] | None) – A callable function to use to get a nonce. This function is useful for e.g., passing in a safe nonce getter tied to an agent. Defaults to setting it to the result of get_transaction_count.
preview_before_trade (bool, optional) – Whether to preview the trade before executing. Defaults to False.

Returns:

A dataclass containing the output event of the contract call.

Return type:

OpenLong

async async_close_long(sender: eth_account.signers.local.LocalAccount, trade_amount: fixedpointmath.FixedPoint, maturity_time: int, slippage_tolerance: fixedpointmath.FixedPoint | None = None, gas_limit: int | None = None, txn_options_base_fee_multiple: float | None = None, txn_options_priority_fee_multiple: float | None = None, nonce_func: Callable[[], web3.types.Nonce] | None = None, preview_before_trade: bool = False) → hyperdrivetypes.CloseLongEventFP

Contract call to close a long position.

Parameters:

sender (LocalAccount) – The account that is executing and signing the trade transaction.
trade_amount (FixedPoint) – The amount of bonds you wish to close.
maturity_time (int) – The token maturity time in seconds.
slippage_tolerance (FixedPoint, optional) – Amount of slippage allowed from the trade. If given, then the trade will not execute unless the slippage is below this value. If not given, then execute the trade regardless of the slippage.
gas_limit (int | None, optional) – The maximum amount of gas used by the transaction. Defaults to eth_estimateGas RPC output.
txn_options_base_fee_multiple (float | None, optional) – The multiple applied to the base fee for the transaction. Defaults to 1.
txn_options_priority_fee_multiple (float | None, optional) – The multiple applied to the priority fee for the transaction. Defaults to 1.
nonce_func (Callable[[], Nonce] | None) – A callable function to use to get a nonce. This function is useful for e.g., passing in a safe nonce getter tied to an agent. Defaults to setting it to the result of get_transaction_count.
preview_before_trade (bool, optional) – Whether to preview the trade before executing. Defaults to False.

Returns:

A dataclass containing the output event of the contract call.

Return type:

CloseLong

async async_open_short(sender: eth_account.signers.local.LocalAccount, trade_amount: fixedpointmath.FixedPoint, slippage_tolerance: fixedpointmath.FixedPoint | None = None, gas_limit: int | None = None, txn_options_base_fee_multiple: float | None = None, txn_options_priority_fee_multiple: float | None = None, nonce_func: Callable[[], web3.types.Nonce] | None = None, preview_before_trade: bool = False) → hyperdrivetypes.OpenShortEventFP

Contract call to open a short position.

Parameters:

sender (LocalAccount) – The account that is executing and signing the trade transaction.
trade_amount (FixedPoint) – The size of the position, in base.
slippage_tolerance (FixedPoint, optional) – Amount of slippage allowed from the trade. If given, then the trade will not execute unless the slippage is below this value. If not given, then execute the trade regardless of the slippage.
gas_limit (int | None, optional) – The maximum amount of gas used by the transaction. Defaults to eth_estimateGas RPC output.
txn_options_base_fee_multiple (float | None, optional) – The multiple applied to the base fee for the transaction. Defaults to 1.
txn_options_priority_fee_multiple (float | None, optional) – The multiple applied to the priority fee for the transaction. Defaults to 1.
nonce_func (Callable[[], Nonce] | None) – A callable function to use to get a nonce. This function is useful for e.g., passing in a safe nonce getter tied to an agent. Defaults to setting it to the result of get_transaction_count.
preview_before_trade (bool, optional) – Whether to preview the trade before executing. Defaults to False.

Returns:

A dataclass containing the output event of the contract call.

Return type:

OpenShort

async async_close_short(sender: eth_account.signers.local.LocalAccount, trade_amount: fixedpointmath.FixedPoint, maturity_time: int, slippage_tolerance: fixedpointmath.FixedPoint | None = None, gas_limit: int | None = None, txn_options_base_fee_multiple: float | None = None, txn_options_priority_fee_multiple: float | None = None, nonce_func: Callable[[], web3.types.Nonce] | None = None, preview_before_trade: bool = False) → hyperdrivetypes.CloseShortEventFP

Contract call to close a short position.

Parameters:

sender (LocalAccount) – The account that is executing and signing the trade transaction.
trade_amount (FixedPoint) – The size of the position, in base.
maturity_time (int) – The token maturity time in seconds.
slippage_tolerance (FixedPoint, optional) – Amount of slippage allowed from the trade. If given, then the trade will not execute unless the slippage is below this value. If not given, then execute the trade regardless of the slippage.
gas_limit (int | None, optional) – The maximum amount of gas used by the transaction. Defaults to eth_estimateGas RPC output.
txn_options_base_fee_multiple (float | None, optional) – The multiple applied to the base fee for the transaction. Defaults to 1.
txn_options_priority_fee_multiple (float | None, optional) – The multiple applied to the priority fee for the transaction. Defaults to 1.
nonce_func (Callable[[], Nonce] | None) – A callable function to use to get a nonce. This function is useful for e.g., passing in a safe nonce getter tied to an agent. Defaults to setting it to the result of get_transaction_count.
preview_before_trade (bool, optional) – Whether to preview the trade before executing. Defaults to False.

Returns:

A dataclass containing the output event of the contract call.

Return type:

CloseShort

async async_add_liquidity(sender: eth_account.signers.local.LocalAccount, trade_amount: fixedpointmath.FixedPoint, min_apr: fixedpointmath.FixedPoint, max_apr: fixedpointmath.FixedPoint, slippage_tolerance: fixedpointmath.FixedPoint | None = None, gas_limit: int | None = None, txn_options_base_fee_multiple: float | None = None, txn_options_priority_fee_multiple: float | None = None, nonce_func: Callable[[], web3.types.Nonce] | None = None, preview_before_trade: bool = False) → hyperdrivetypes.AddLiquidityEventFP

Contract call to add liquidity to the Hyperdrive pool.

Parameters:

sender (LocalAccount) – The account that is executing and signing the trade transaction.
trade_amount (FixedPoint) – The size of the position, in base.
min_apr (FixedPoint) – The minimum allowable APR after liquidity is added.
max_apr (FixedPoint) – The maximum allowable APR after liquidity is added.
slippage_tolerance (FixedPoint, optional) – Amount of slippage allowed from the trade. If given, then the trade will not execute unless the slippage is below this value. If not given, then execute the trade regardless of the slippage.
gas_limit (int | None, optional) – The maximum amount of gas used by the transaction. Defaults to eth_estimateGas RPC output.
txn_options_base_fee_multiple (float | None, optional) – The multiple applied to the base fee for the transaction. Defaults to 1.
txn_options_priority_fee_multiple (float | None, optional) – The multiple applied to the priority fee for the transaction. Defaults to 1.
nonce_func (Callable[[], Nonce] | None) – A callable function to use to get a nonce. This function is useful for e.g., passing in a safe nonce getter tied to an agent. Defaults to setting it to the result of get_transaction_count.
preview_before_trade (bool, optional) – Whether to preview the trade before executing. Defaults to False.

Returns:

A dataclass containing the output event of the contract call.

Return type:

AddLiquidity

async async_remove_liquidity(sender: eth_account.signers.local.LocalAccount, trade_amount: fixedpointmath.FixedPoint, gas_limit: int | None = None, txn_options_base_fee_multiple: float | None = None, txn_options_priority_fee_multiple: float | None = None, nonce_func: Callable[[], web3.types.Nonce] | None = None, preview_before_trade: bool = False) → hyperdrivetypes.RemoveLiquidityEventFP

Contract call to remove liquidity from the Hyperdrive pool.

Parameters:

sender (LocalAccount) – The account that is executing and signing the trade transaction.
trade_amount (FixedPoint) – The size of the position, in base.
gas_limit (int | None, optional) – The maximum amount of gas used by the transaction. Defaults to eth_estimateGas RPC output.
txn_options_base_fee_multiple (float | None, optional) – The multiple applied to the base fee for the transaction. Defaults to 1.
txn_options_priority_fee_multiple (float | None, optional) – The multiple applied to the priority fee for the transaction. Defaults to 1.
nonce_func (Callable[[], Nonce] | None) – A callable function to use to get a nonce. This function is useful for e.g., passing in a safe nonce getter tied to an agent. Defaults to setting it to the result of get_transaction_count.
preview_before_trade (bool, optional) – Whether to preview the trade before executing. Defaults to False.

Returns:

A dataclass containing the output event of the contract call.

Return type:

RemoveLiquidity

async async_redeem_withdraw_shares(sender: eth_account.signers.local.LocalAccount, trade_amount: fixedpointmath.FixedPoint, gas_limit: int | None = None, txn_options_base_fee_multiple: float | None = None, txn_options_priority_fee_multiple: float | None = None, nonce_func: Callable[[], web3.types.Nonce] | None = None, preview_before_trade: bool = False) → hyperdrivetypes.RedeemWithdrawalSharesEventFP

Contract call to redeem withdraw shares from Hyperdrive pool.

This should be done after closing liquidity.

Note

This is not guaranteed to redeem all shares. The pool will try to redeem as many as possible, up to the withdrawPool.readyToRedeem limit, without reverting. This will revert if the min_output is too high or the user is trying to withdraw more shares than they have.

Parameters:

sender (LocalAccount) – The account that is executing and signing the trade transaction.
trade_amount (FixedPoint) – The size of the position, in base.
gas_limit (int | None, optional) – The maximum amount of gas used by the transaction. Defaults to eth_estimateGas RPC output.
txn_options_base_fee_multiple (float | None, optional) – The multiple applied to the base fee for the transaction. Defaults to 1.
txn_options_priority_fee_multiple (float | None, optional) – The multiple applied to the priority fee for the transaction. Defaults to 1.
nonce_func (Callable[[], Nonce] | None) – A callable function to use to get a nonce. This function is useful for e.g., passing in a safe nonce getter tied to an agent. Defaults to setting it to the result of get_transaction_count.
preview_before_trade (bool, optional) – Whether to preview the trade before executing. Defaults to False.

Returns:

A dataclass containing the output event of the contract call.

Return type:

RedeemWithdrawalShares