erc_4626.vault_protocol.umami.vault

Documentation for eth_defi.erc_4626.vault_protocol.umami.vault Python module.

Umami gmUSDC vault support.

Classes

`UmamiDepositManager`	Umami deposit manager with custom logic.
`UmamiVault`	Umami vaults.

class UmamiVault

Bases: eth_defi.erc_4626.vault.ERC4626Vault

Umami vaults.

GMUSDC, etc: https://umami.finance/vaults/arbitrum/gm/gmusdc

Umami vaults do not have open source Github repository, developer documentation or easy developer access for integrations, making it not recommended to deal with them.

Vault smart contract code: https://arbiscan.io/address/0x959f3807f0aa7921e18c78b00b2819ba91e52fef#code

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, use get_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.

get_risk()

Get risk profile of this vault.

Return type: eth_defi.vault.risk.VaultTechnicalRisk | None

property vault_contract: web3.contract.contract.Contract: Get vault deployment.

has_custom_fees()

Deposit/withdrawal fees.

Return type: bool

get_management_fee(block_identifier)

Umami fees hardcoded because no transparent development/onchain accessors.

https://umami.finance/vaults/arbitrum/gm/gmusdc

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) –
Return type: float

get_performance_fee(block_identifier)

Umami fees hardcoded because no transparent development/onchain accessors.

https://umami.finance/vaults/arbitrum/gm/gmusdc

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) –
Return type: float | None

get_estimated_lock_up()

ERC-4626 vaults do not have a lock up by fault.

Note

Because of so many protocol specific lockups, this must be explicitly set to zero.

Return type: datetime.timedelta

get_deposit_manager()

Get deposit manager to deposit/redeem from the vault.

Return type: eth_defi.umami.vault.UmamiDepositManager

__init__(web3, spec, token_cache=None, features=None, default_block_identifier=None)

Parameters

web3 (web3.main.Web3) – Connection we bind this instance to
spec (eth_defi.vault.base.VaultSpec) – Chain, address tuple
token_cache (dict | None) –
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 (set[eth_defi.erc_4626.core.ERC4626Feature] | None) – 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, use get_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.

property address: eth_typing.evm.HexAddress: Get the vault smart contract address.

property chain_id: int: Chain this vault is on

property denomination_token: eth_defi.token.TokenDetails | None

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

property deposit_manager: eth_defi.vault.deposit_redeem.VaultDepositManager: Deposit manager assocaited with this vault

property erc_7540: bool

Is this ERC-7540 vault with asynchronous deposits.

For example previewDeposit() function and other functions will revert

fetch_denomination_token()

Read denomination token from onchain.

Use denomination_token() for cached access.

Return type: eth_defi.token.TokenDetails | None

fetch_denomination_token_address()

Get the address for the denomination token.

Triggers RCP call

Return type: Optional[eth_typing.evm.HexAddress]

fetch_info()

Use info() property for cached access.

Returns: See LagoonVaultInfo
Return type: eth_defi.erc_4626.vault.ERC4626VaultInfo

fetch_nav(block_identifier=None)

Fetch the most recent onchain NAV value.

In the case of Lagoon, this is the last value written in the contract with updateNewTotalAssets() and ` settleDeposit()`
TODO: updateNewTotalAssets() there is no way to read pending asset update on chain

Returns: Vault NAV, denominated in denomination_token()
Return type: decimal.Decimal

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

eth_defi.vault.base.VaultPortfolio

fetch_share_price(block_identifier)

Get the current share price.

Returns

The share price in underlying token.

If supply is zero return zero.

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]) –

Return type

decimal.Decimal

fetch_share_token()

Read share token details onchain.

Use share_token() for cached access.

Return type: eth_defi.token.TokenDetails

fetch_share_token_address(block_identifier='latest')

Get share token of this vault.

Vault itself (ERC-4626)
share() accessor (ERc-7575)

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]) –
Return type: eth_typing.evm.HexAddress

fetch_total_assets(block_identifier)

What is the total NAV of the vault.

Example:

assert vault.denomination_token.symbol == "USDC"
assert vault.share_token.symbol == "ipUSDCfusion"
assert vault.fetch_total_assets(block_identifier=test_block_number) == Decimal("1437072.77357")
assert vault.fetch_total_supply(block_identifier=test_block_number) == Decimal("1390401.22652875")

Parameters

Block number to read.

Use web3.eth.block_number for the last block.

Returns

The vault value in underlyinh token

Return type

decimal.Decimal | None

fetch_total_supply(block_identifier)

What is the current outstanding shares.

Example:

Parameters

Block number to read.

Use web3.eth.block_number for the last block.

Returns

The vault value in underlyinh token

Return type

decimal.Decimal

fetch_vault_info()

Get all information we can extract from the vault smart contracts.

Return type: eth_defi.erc_4626.vault.ERC4626VaultInfo

property flow_manager: eth_defi.vault.base.VaultFlowManager: Flow manager associated with this vault

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().

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) –
Return type: float | None

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: eth_defi.vault.fee.FeeData

get_fee_mode()

Get how this vault accounts its fees.

Return type: eth_defi.vault.fee.VaultFeeMode | None

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

set[eth_defi.vault.flag.VaultFlag]

get_flow_manager()

Get flow manager to read indiviaul settle events.

Only supported if has_block_range_event_support() is True

Return type: eth_defi.vault.base.VaultFlowManager

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: eth_defi.vault.base.VaultHistoricalReader

get_link(referral=None)

Get a link to the vault dashboard on its native site.

By default, give RouteScan link

Parameters: referral (str | None) – Optional referral code to append to the URL.
Returns: URL string
Return type: str

get_notes()

Get a human readable message if we know somethign special is going on with this vault.

Return type: str | None

get_protocol_name()

Return the name of the vault protocol.

Return type: str

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().

Parameters: block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) –
Return type: float

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_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: bool

property name: str: Vault name.

property share_token: eth_defi.token.TokenDetails

ERC-20 that presents vault shares.

User gets shares on deposit and burns them on redemption

property symbol: str: Vault share token symbol

property underlying_token: eth_defi.token.TokenDetails: Alias for denomination_token()

first_seen_at_block: int | None

Block number hint when this vault was deployed.

Must be set externally, as because of shitty Ethereum RPC we cannot query this. Allows us to avoid unnecessary work when scanning historical price data.

class UmamiDepositManager

Bases: eth_defi.erc_4626.deposit_redeem.ERC4626DepositManager

Umami deposit manager with custom logic.

create_deposit_request(owner, to=None, amount=None, raw_amount=None, check_max_deposit=True, check_enough_token=True, max_slippage=0.01, gas=30000000)

Umami has a slippage tolerance on deposits.

Umami has a 0.15% deposit fee taken from the shares minted.
Umami deposit is gas hungry
Umami deposit must have ETH attached to the transaction as something spends it there

// DEPOSIT & WITHDRAW
// ------------------------------------------------------------------------------------------

/**
 * @notice Deposit a specified amount of assets and mint corresponding shares to the receiver
 * @param assets The amount of assets to deposit
 * @param minOutAfterFees Minimum amount out after fees
 * @param receiver The address to receive the minted shares
 * @return shares The estimate amount of shares minted for the deposited assets
 */
function deposit(uint256 assets, uint256 minOutAfterFees, address receiver)
    public
    payable
    override
    whenDepositNotPaused
    nonReentrant
    returns (uint256 shares)
{
    // Check for rounding error since we round down in previewDeposit.
    require((shares = previewDeposit(assets)) != 0, "ZERO_SHARES");
    require(
        totalAssets() + assets <= previewVaultCap() + asset.balanceOf(address(this)), "AssetVault: over vault cap"
    );
    // Transfer assets to aggregate vault, transfer before minting or ERC777s could reenter.
    asset.safeTransferFrom(msg.sender, address(this), assets);
    aggregateVault.handleDeposit{ value: msg.value }(assets, minOutAfterFees, receiver, msg.sender, address(0));

    emit Deposit(msg.sender, receiver, assets, shares);
}

ETH spend:

/**
 * @notice Handles a deposit of a specified amount of an ERC20 asset into the AggregateVault from an account, with a deposit fee deducted.
 * @param assets The amount of the asset to be deposited.
 * @param account The address of the account from which the deposit will be made.
 */
function handleDeposit(uint256 assets, uint256 minOutAfterFees, address account, address sender, address callback)
    external
    payable
    onlyAssetVault
{
    if (assets == 0) revert AmountEqualsZero();
    if (account == address(0)) revert ZeroAddress();
    AVStorage storage stg = _getStorage();
    uint256 gas = _gasRequirement(callback != address(0));
    if (msg.value < gas * tx.gasprice) revert MinGasRequirement();

    // store request data
    uint256 key = _saveRequest(sender, account, msg.sender, callback, true, assets, minOutAfterFees);

    // send execution gas cost
    TransferUtils.transferNativeAsset(stg.rebalanceKeeper, msg.value);

    _executeHook(HookType.DEPOSIT_HOOK, msg.data[4:]);

    // emit request event
    Emitter(stg.emitter).emitDepositRequest(key, account, msg.sender);
}

Parameters

owner (eth_typing.evm.HexAddress) –
to (eth_typing.evm.HexAddress) –
amount (decimal.Decimal) –
raw_amount (int) –

Return type

eth_defi.erc_4626.deposit_redeem.ERC4626DepositRequest

__init__(vault)

Parameters: vault (eth_defi.erc_4626.vault.ERC4626Vault) –

analyse_deposit(claim_tx_hash, deposit_ticket)

Analyse the transaction where we claim shares

Return information of the actual executed price for which we got the shares for

Parameters

claim_tx_hash (hexbytes.main.HexBytes | str) –
deposit_ticket (eth_defi.vault.deposit_redeem.DepositTicket | None) –

Return type

eth_defi.vault.deposit_redeem.DepositRedeemEventAnalysis | eth_defi.vault.deposit_redeem.DepositRedeemEventFailure

analyse_redemption(claim_tx_hash, redemption_ticket)

Analyse the transaction where we claim our capital back.

Return information of the actual executed price for which we got the shares for

Parameters

claim_tx_hash (hexbytes.main.HexBytes | str) –
redemption_ticket (eth_defi.vault.deposit_redeem.RedemptionTicket | None) –

Return type

eth_defi.vault.deposit_redeem.DepositRedeemEventAnalysis | eth_defi.vault.deposit_redeem.DepositRedeemEventFailure

can_create_deposit_request(owner)

Can we start depositing now.

Vault can be full?

Parameters: owner (eth_typing.evm.HexAddress) –
Return type: bool

can_create_redemption_request(owner)

Gains allows request redepetion only two first days of three days epoch.

Returns: True if can create a redemption request now
Parameters: owner (eth_typing.evm.HexAddress) –
Return type: bool

can_finish_deposit(deposit_ticket)

Synchronous deposits can be finished immediately.

Parameters: deposit_ticket (eth_defi.erc_4626.deposit_redeem.ERC4626DepositTicket) –

can_finish_redeem(redemption_ticket)

Synchronous redemptions can be finished immediately.

Parameters: redemption_ticket (eth_defi.erc_4626.deposit_redeem.ERC4626RedemptionTicket) –

create_redemption_request(owner, to=None, shares=None, raw_shares=None, check_max_deposit=True, check_enough_token=True)

Create a redemption request.

Abstracts IPOR, Lagoon, Gains, other vault redemption flow.

See eth_defi.gains.vault.GainsVault for an example usage.

Flow

create_redemption_request
sign and broadcast the transaction
parse success and redemption request id from the transaction
wait until the redemption delay is over
settle the redemption request

Parameters

owner (eth_typing.evm.HexAddress) – Deposit owner.
shares (decimal.Decimal) –
Share amount in decimal.

Will be converted to raw_shares using share_token decimals.
raw_shares (int) – Raw amount in share token
to (eth_typing.evm.HexAddress) –

Returns

Redemption request wrapper.

Return type

eth_defi.erc_4626.deposit_redeem.ERC4626RedemptionRequest

estimate_deposit(owner, amount, block_identifier='latest')

How many shares we get for a deposit.

Parameters

owner (eth_typing.evm.HexAddress) –
amount (decimal.Decimal) –
block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) –

Return type

decimal.Decimal

estimate_redeem(owner, shares, block_identifier='latest')

How many denomination tokens we get for a redeem.

Parameters

owner (eth_typing.evm.HexAddress) –
shares (decimal.Decimal) –
block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) –

Return type

decimal.Decimal

estimate_redemption_delay()

Get the redemption delay for this vault.

What is overall redemption delay: not related to the current moment
How long it takes before a redemption request is allowed
This is not specific for any address, but the general vault rule
E.g. you get 0xa592703b is an IPOR Fusion error code AccountIsLocked, if you try to instantly redeem from IPOR vaults

Returns: Redemption delay as a datetime.timedelta
Raises: NotImplementedError – If not implemented for this vault protocoll.
Return type: datetime.timedelta

finish_deposit(deposit_ticket)

Can we finish the deposit process in async vault.

We can claim our shares from the vault now

Parameters: deposit_ticket (eth_defi.vault.deposit_redeem.DepositTicket) –
Return type: web3.contract.contract.ContractFunction

get_max_deposit(owner)

How much we can deposit

Parameters: owner (eth_typing.evm.HexAddress) –
Return type: decimal.Decimal | None

get_redemption_delay_over(address)

Get the redemption timer left for an address.

How long it takes before a redemption request is allowed
This is not specific for any address, but the general vault rule
E.g. you get 0xa592703b is an IPOR Fusion error code AccountIsLocked, if you try to instantly redeem from IPOR vaults

Returns

UTC timestamp when the account can redeem.

Naive datetime.

Raises

NotImplementedError – If not implemented for this vault protocoll.

Parameters

address (Union[eth_typing.evm.HexAddress, str]) –

Return type

datetime.datetime

has_synchronous_deposit()

Does this vault support synchronous deposits?

E.g. ERC-4626 vaults

Return type: bool

has_synchronous_redemption()

Does this vault support synchronous deposits?

E.g. ERC-4626 vaults

Return type: bool

is_deposit_in_progress(owner)

Check if the owner has an active deposit request.

Parameters: owner (eth_typing.evm.HexAddress) – Owner of the shares
Returns: True if there is an active redemption request
Return type: bool

is_redemption_in_progress(owner)

Check if the owner has an active redemption request.

Parameters: owner (eth_typing.evm.HexAddress) – Owner of the shares
Returns: True if there is an active redemption request
Return type: bool