erc_4626.vault_protocol.forgeyields.vault
Documentation for eth_defi.erc_4626.vault_protocol.forgeyields.vault Python module.
ForgeYields vault support.
ForgeYields is a cross-chain, non-custodial yield aggregator deploying into frontier DeFi strategies underwritten by the Hallmark public risk methodology.
The fyUSDC, fyETH and fyWBTC vaults issue auto-compounding ERC-4626 tokens (fyTokens). The Ethereum vault is built on Veda Labs’ BoringVault and allocates across Aave, Morpho, Curve, Pendle and others.
NAV calculation
The TokenGateway contract does not implement totalAssets() — the call reverts.
On-chain convertToAssets(totalSupply()) returns only the gateway’s residual balance
(~$12K), not the true cross-chain AUM (~$1.8M). The canonical TVL comes from
ForgeYields’ proprietary API at https://api.forgeyields.com/strategies.
See offchain_metadata for
the API integration.
Fee model:
20 % daily performance fee, internalised into the share price
No management fee, no deposit/withdrawal fees
Example contracts:
Classes
Read ForgeYields vault data — share price from on-chain, TVL from offchain API. |
|
ForgeYields vault. |
- class ForgeYieldsHistoricalReader
Bases:
eth_defi.erc_4626.vault.ERC4626HistoricalReaderRead ForgeYields vault data — share price from on-chain, TVL from offchain API.
The on-chain
totalAssets()reverts on the TokenGateway andconvertToAssets(totalSupply())returns only the gateway residual.For rows near the chain head (within 24 hours of now), this reader writes the current denomination-token TVL from the ForgeYields API into
total_assets. Older rows gettotal_assets=None— the backfill script fills those from the API’s 30-dayhistoryReports.The current TVL is also fed into the reader state so adaptive polling does not degrade to faded/tiny cadence.
- __init__(vault, stateful)
- Parameters
vault (eth_defi.erc_4626.vault.ERC4626Vault) –
stateful (bool) –
- construct_core_erc_4626_multicall()
Polling endpoints defined in ERC-4626 spec.
Does not include fee calls which do not have standard
- construct_multicalls()
Get the onchain calls that are needed to read the share price.
- dictify_multicall_results(block_number, call_results, allow_failure=True)
Convert batch of multicalls made for this vault to more digestible dict.
Assert that all multicalls succeed
- Returns
Dictionary where each multicall is keyed by its
EncodedCall.extra_data["function"]- Parameters
block_number (int) –
call_results (list[eth_defi.event_reader.multicall_batcher.EncodedCallResult]) –
- Return type
dict[str, eth_defi.event_reader.multicall_batcher.EncodedCallResult]
- get_warmup_calls()
Yield (function_name, callable, contract_call) tuples for warmup testing.
Each callable should execute a single contract call. If it raises, the function is marked as broken.
The optional contract_call is used for gas estimation to detect expensive calls before executing them. If provided, calls using excessive gas (>1M gas) will be marked as broken without execution.
Override in subclasses to add protocol-specific calls.
- process_core_erc_4626_result(call_by_name)
Decode common ERC-4626 calls.
- Parameters
call_by_name (dict[str, eth_defi.event_reader.multicall_batcher.EncodedCallResult]) –
- Return type
- process_result(block_number, timestamp, call_results)
Process the result of mult
Calls are created in
construct_multicalls()This method combines result of this calls to a easy to manage historical record
VaultHistoricalRead
- Parameters
block_number (int) –
timestamp (datetime.datetime) –
call_results (list[eth_defi.event_reader.multicall_batcher.EncodedCallResult]) –
- Return type
- class ForgeYieldsVault
Bases:
eth_defi.erc_4626.vault.ERC4626VaultForgeYields vault.
Cross-chain, non-custodial yield aggregator for underwritten frontier DeFi strategies.
Built on Veda Labs’ BoringVault with TokenGateway cross-chain deposit architecture
Hallmark-underwritten strategies with public risk methodology
Atomic Transparency Ledger for real-time on-chain-verifiable reporting
Asynchronous request-then-claim redemption; funds keep earning until claimed
The TokenGateway contract does not implement
totalAssets(). On-chainconvertToAssets(totalSupply())returns only the gateway residual. The canonical TVL comes from the offchain API.See
offchain_metadata.- Parameters
web3 – Connection we bind this instance to
spec – Chain, address tuple
token_cache –
Cache used with
fetch_erc20_details()to avoid multiple calls to the same token.Reduces the number of RPC calls when scanning multiple vaults.
features – Pass vault feature flags along, externally detected.
default_block_identifier –
Override block identifier for on-chain metadata reads.
When
None, useget_safe_cached_latest_block_number()(the default, safe for broken RPCs). Set to"latest"for freshly deployed vaults whose contracts do not exist at the safe-cached block.require_denomination_token – If
True, accessingdenomination_tokenwill raiseRuntimeErrorwhen the on-chain lookup returnsNone.
- __init__(web3, spec, token_cache=None, features=None, default_block_identifier=None, require_denomination_token=False)
- Parameters
web3 (web3.main.Web3) – Connection we bind this instance to
spec (eth_defi.vault.base.VaultSpec) – Chain, address tuple
token_cache (Optional[dict]) –
Cache used with
fetch_erc20_details()to avoid multiple calls to the same token.Reduces the number of RPC calls when scanning multiple vaults.
features (Optional[set[eth_defi.erc_4626.core.ERC4626Feature]]) – Pass vault feature flags along, externally detected.
default_block_identifier (Optional[Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, hexbytes.main.HexBytes, int]]) –
Override block identifier for on-chain metadata reads.
When
None, useget_safe_cached_latest_block_number()(the default, safe for broken RPCs). Set to"latest"for freshly deployed vaults whose contracts do not exist at the safe-cached block.require_denomination_token (bool) – If
True, accessingdenomination_tokenwill raiseRuntimeErrorwhen the on-chain lookup returnsNone.
- property address: eth_typing.evm.HexAddress
Get the vault smart contract address.
- can_check_deposit()
Check if maxDeposit(address(0)) can be used to check global deposit availability.
Most ERC-4626 vaults implement maxDeposit in a way that returns meaningful values when called with address(0):
Returns 0 when deposits are globally closed/capped
Returns a positive value indicating maximum deposit allowed
Override to return False in subclasses where maxDeposit(address(0)) doesn’t provide meaningful global availability information.
- Returns
True if maxDeposit(address(0)) returns meaningful values for global deposit availability checking.
- Return type
- can_check_redeem()
Check if maxRedeem(address(0)) can be used to check global redemption availability.
Most protocols return 0 for maxRedeem(address(0)) because that address has no balance/shares, not because redemptions are closed:
Gearbox: maxRedeem returns min(balanceOf(owner), convertToShares(availableLiquidity))
Most vaults: Return 0 because address(0) has no shares
Some protocols do use maxRedeem(address(0)) meaningfully:
Morpho, IPOR, Plutus: Return 0 when redemptions are globally blocked
Override to return True in subclasses that support address(0) redemption checks.
- Returns
True if maxRedeem(address(0)) returns meaningful values for global redemption availability checking.
- Return type
- property denomination_token: Optional[eth_defi.token.TokenDetails]
Get the token which denominates the vault valuation
Used in deposits and redemptions
Used in NAV calculation
Used in profit benchmarks
Usually USDC
- Returns
Token wrapper instance.
Maybe None for broken vaults like https://arbiscan.io/address/0x9d0fbc852deccb7dcdd6cb224fa7561efda74411#code
Note
Noneresults are not cached — the next access will retry the on-chain call. This avoids permanently caching a transient RPC failure.
- property deposit_manager: eth_defi.vault.deposit_redeem.VaultDepositManager
Deposit manager assocaited with this vault
- property description: Optional[str]
Human-readable vault strategy description.
Fetched from protocol-specific offchain sources (e.g. Euler GitHub labels, Lagoon web app API)
Returns None if the protocol does not provide descriptions or the vault is not in the metadata source
Override in subclasses that support offchain metadata
- property erc_7540: bool
Is this ERC-7540 vault with asynchronous deposits.
For example
previewDeposit()function and other functions will revert
- fetch_available_liquidity(block_identifier='latest')
Get the amount of denomination token available for immediate withdrawal.
Only applicable to lending protocol vaults (IPOR, Euler, Morpho, Gearbox, etc.). Non-lending protocols should leave this method unimplemented.
Note: maxRedeem(address(0)) does NOT work as a proxy for available liquidity because it requires a specific address that has already deposited shares. For address(0), balanceOf is always 0, so maxRedeem returns 0 regardless of actual liquidity.
- Parameters
block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Block to query. Defaults to “latest”.
- Raises
NotImplementedError – For non-lending protocol vaults.
- Returns
Amount in denomination token units (human-readable Decimal).
- Return type
- fetch_denomination_token()
Read denomination token from onchain.
Use
denomination_token()for cached access.- Return type
- fetch_denomination_token_address()
Get the
asset()denomination token address of this vault.Results are disk-cached per
(chain_id, vault_address)viaeth_defi.erc_4626.vault_tokenwhen the vault was constructed with aeth_defi.token.TokenDiskCacheand no pinneddefault_block_identifier. The denomination token is immutable post-deployment, so the cached value is correct regardless of which block the caller would have asked for.Only a definitive non-null answer is persisted. The
Nonepath taken on revert / broken contract is never cached, matching the behaviour ofeth_defi.vault.base.VaultBase.denomination_token()which explicitly avoids memoisingNoneso transient failures can be retried.To disable the cache, pass
token_cache=None(or any non-TokenDiskCachedict) when constructing the vault, or construct with a pinneddefault_block_identifier.- Returns
Denomination token address, or
Noneif the vault contract is broken and did not return a valid address.- Return type
- fetch_deposit_closed_reason()
Check if deposits are closed using maxDeposit(address(0)).
Uses the ERC-4626 standard maxDeposit function to determine if deposits are available. Returns a human-readable reason with the max deposit amount if deposits are restricted.
- fetch_deposit_next_open()
Get when deposits will next be open.
For epoch-based vaults (Ostium, D2), return calculated window open time
For non-epoch vaults (Plutus, IPOR, Morpho), return None
Override in protocol-specific subclasses
- Returns
Naive UTC datetime when deposits will next be available, or None if:
Deposits are currently open
Timing is unpredictable (manually controlled)
Protocol does not support timing information
- Return type
- fetch_nav(block_identifier=None)
Fetch current TVL in denomination token units from the ForgeYields API.
Returns the cross-chain AUM in the vault’s denomination token (ETH, USDC, WBTC) from
api.forgeyields.com/strategies.- Returns
Total vault value in denomination token units, or
None.- Return type
- fetch_portfolio(universe, block_identifier=None, allow_fallback=True)
Read the current token balances of a vault.
SHould be supported by all implementations
- Parameters
universe (eth_defi.vault.base.TradingUniverse) –
block_identifier (Optional[Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, hexbytes.main.HexBytes, int]]) –
allow_fallback (bool) –
- Return type
- fetch_redemption_closed_reason()
Check if redemptions are closed using maxRedeem(address(0)).
Only works for protocols that implement maxRedeem in a way that returns meaningful values for address(0). Most protocols return 0 because address(0) has no shares, not because redemptions are closed.
- fetch_redemption_next_open()
Get when withdrawals/redemptions will next be open.
For epoch-based vaults (Ostium, D2), return calculated window open time
For non-epoch vaults (Plutus, IPOR, Morpho), return None
Override in protocol-specific subclasses
- Returns
Naive UTC datetime when withdrawals will next be available, or None if:
Withdrawals are currently open
Timing is unpredictable (manually controlled)
Protocol does not support timing information
- Return type
- fetch_share_price(block_identifier)
Get the current share price.
- fetch_share_token()
Read share token details onchain.
Use
share_token()for cached access.- Return type
- fetch_share_token_address(block_identifier='latest')
Get share token of this vault.
Vault itself (ERC-4626)
share()accessor (ERC-7575)
Results are disk-cached per
(chain_id, vault_address)viaeth_defi.erc_4626.vault_tokenwhen the vault was constructed with aeth_defi.token.TokenDiskCache. Under normal circumstances theblock_identifierargument is effectively ignored on cache hits — ERC-4626 share tokens are immutable post-deployment, so the cached value is correct regardless of which block the caller asked for.Only a definitive answer from the chain is ever persisted: a successful call, or a revert matching
KNOWN_SHARE_TOKEN_ERROR_MESSAGES(which positively classifies the contract as non-ERC-7575). Transient RPC failures (ProbablyNodeHasNoBlock, HTTP 502) fall back toself.vault_addressbut are not written to the cache, so a flaky node cannot poison a real ERC-7575 vault’s entry.To disable the cache, pass
token_cache=None(or any non-TokenDiskCachedict) when constructing the vault, or construct with a pinneddefault_block_identifierto force the uncached historical-read path on every call.- Parameters
block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, hexbytes.main.HexBytes, int]) – Block to query. Cache is only consulted/written when the caller passes the default
"latest"and the vault instance has no pinneddefault_block_identifier.- Return type
- fetch_total_assets(block_identifier)
Not available — on-chain value is the gateway residual, not the true AUM.
The TokenGateway’s
convertToAssets(totalSupply())returns only the small residual held by the Ethereum gateway (~$12K), not the cross-chain AUM (~$1.8M). Usefetch_nav()for the canonical current TVL from the ForgeYields API.
- fetch_total_supply(block_identifier)
What is the current outstanding shares.
Example:
- Parameters
block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, hexbytes.main.HexBytes, int]) –
Block number to read.
Use web3.eth.block_number for the last block.
- Returns
The vault value in underlyinh token
- Return type
- fetch_tvl()
Fetch total cross-chain TVL in denomination token units from the ForgeYields API.
Returns the TVL in the vault’s denomination token (ETH, USDC, WBTC), suitable for writing to
total_assetsin the price parquet.Uses a short (1-hour) disk cache so hourly scan cycles pick up fresh TVL values, unlike the 2-day metadata cache used for ranking.
- Returns
Total vault value in denomination token units, or
Noneif unavailable.- Return type
- fetch_utilisation_percent(block_identifier='latest')
Get the percentage of assets currently lent out.
Only applicable to lending protocol vaults (IPOR, Euler, Morpho, Gearbox, etc.). Non-lending protocols should leave this method unimplemented.
- Parameters
block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Block to query. Defaults to “latest”.
- Raises
NotImplementedError – For non-lending protocol vaults.
- Returns
Utilisation as float between 0.0 and 1.0 (0% to 100%).
- Return type
- fetch_vault_info()
Get all information we can extract from the vault smart contracts.
- Return type
- property flow_manager: eth_defi.vault.base.VaultFlowManager
Flow manager associated with this vault
- property forgeyields_metadata: Optional[eth_defi.erc_4626.vault_protocol.forgeyields.offchain_metadata.ForgeYieldsVaultMetadata]
Offchain metadata from ForgeYields’ proprietary API.
Fetched from
api.forgeyields.com/strategiesCached on first access (in-process + disk)
Returns None if vault address is not a known ForgeYields Ethereum gateway
- get_deposit_fee(block_identifier)
Deposit fee is set to zero by default as vaults usually do not have deposit fees.
Internal: Use
get_fee_data().
- get_deposit_manager()
Get deposit manager to deposit/redeem from the vault.
- get_estimated_lock_up()
Asynchronous request-then-claim redemption.
Redemptions are processed in epochs. Typical turnaround is within a few days but can vary depending on vault liquidity.
- Return type
- get_fee_data()
Get fee data structure for this vault.
- Raises
ValueError – In the case of broken or unimplemented fee reading methods in the smart contract
- Return type
- get_fee_mode()
Get how this vault accounts its fees.
- Return type
- get_flags()
Get various vault state flags from the smart contract.
Override to add status flags
Also add flags from our manual flag list in
eth_defi.vault.flag
- Returns
Flag set.
Do not modify in place.
- Return type
- get_flow_manager()
Get flow manager to read indiviaul settle events.
Only supported if
has_block_range_event_support()is True
- Return type
- get_historical_reader(stateful)
Get share price reader to fetch historical returns.
- Parameters
stateful – If True, use a stateful reading strategy.
- Returns
None if unsupported
- Return type
- get_link(referral=None)
Link to the ForgeYields app.
- get_management_fee(block_identifier)
No management fee.
- get_notes()
Get a human readable message if we know somethign special is going on with this vault.
- get_performance_fee(block_identifier)
20 % daily performance fee, internalised into the share price.
- get_risk()
Get risk profile of this vault.
- Return type
- get_withdraw_fee(block_identifier)
Withdraw fee is set to zero by default as vaults usually do not have withdraw fees.
Internal: Use
get_fee_data().
- has_block_range_event_support()
Does this vault support block range-based event queries for deposits and redemptions.
If not we use chain balance polling-based approach
- has_custom_fees()
Does this vault have custom fee structure reading methods.
Causes risk in the vault comparison.
E.g.
Withdraw fee
Deposit fee
- Returns
True if custom fee reading methods are implemented
- Return type
- has_deposit_distribution_to_all_positions()
Deposits go automatically to all open positions.
Deposits do not land into the vault as cash
Instead, smart contracts automatically increase all open positions
The behaviour of Velvet Capital
- property info: eth_defi.vault.base.VaultInfo
Get info dictionary related to this vault deployment.
Get cached data on the various vault parameters
- Returns
Vault protocol specific information dictionary
- is_valid()
Check if this vault is valid.
Call a known smart contract function to verify the function exists
- Return type
- property share_token: eth_defi.token.TokenDetails
ERC-20 that presents vault shares.
User gets shares on deposit and burns them on redemption
- property short_description: Optional[str]
One-liner vault summary.
Shorter version of
description()suitable for listings and tablesReturns None if not available
Override in subclasses that support offchain metadata
- property underlying_token: eth_defi.token.TokenDetails
Alias for
denomination_token()
- property vault_contract: web3.contract.contract.Contract
Get vault deployment.