velvet.vault

Documentation for eth_defi.velvet.vault Python module.

Velvet Capital vault adapter.

Notes:

Classes

VelvetVault

Python interface for interacting with Velvet Capital vaults.

VelvetVaultInfo

Velvet Capital vault deployment info.

Exceptions

VelvetBadConfig

Likely wrong vault address given
exception VelvetBadConfig

Bases: Exception

Likely wrong vault address given

__init__(*args, **kwargs)
__new__(**kwargs)
add_note()

Exception.add_note(note) – add a note to the exception

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class VelvetVaultInfo

Bases: eth_defi.vault.base.VaultInfo

Velvet Capital vault deployment info.

  • Fetched over proprietary API server

__init__(*args, **kwargs)
__new__(**kwargs)
clear() → None.  Remove all items from D.
copy() → a shallow copy of D
fromkeys(value=None, /)

Create a new dictionary with keys from iterable and values set to value.

get(key, default=None, /)

Return the value for key if key is in the dictionary, else default.

items() → a set-like object providing a view on D's items
keys() → a set-like object providing a view on D's keys
pop(k[, d]) → v, remove specified key and return the corresponding value.

If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem()

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

setdefault(key, default=None, /)

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

update([E, ]**F) → None.  Update D from mapping/iterable E and F.

If E is present and has a .keys() method, then does: for k in E.keys(): D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values() → an object providing a view on D's values
class VelvetVault

Bases: eth_defi.vault.base.VaultBase

Python interface for interacting with Velvet Capital vaults.

Parameters

spec – Address must be Velvet portfolio address (not vault address)

__init__(web3, spec, api_url='https://intents.velvet.capital/api/v1')
Parameters
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

get_flow_manager()

Get flow manager to read indiviaul settle events.

check_valid_contract()

Check that we have connected to a proper Velvet capital vault contract, not wrong contract.

Raises

AssertionError – Looks bad

fetch_info()

Read vault parameters from the chain.

Return type

eth_defi.velvet.vault.VelvetVaultInfo

property info: eth_defi.velvet.vault.VelvetVaultInfo

Get info dictionary related to this vault deployment.

  • Get cached data on the various vault parameters

Returns

Vault protocol specific information dictionary

property address: eth_typing.evm.HexAddress

Vault contract address.

  • Often vault protocols need multiple contracts per vault, so what this function returns depends on the protocol

property chain_id: int

Chain this vault is on

property name: str

Vault name.

fetch_portfolio(universe, block_identifier=None)

Read the current token balances of a vault.

  • SHould be supported by all implementations

Parameters
Return type

eth_defi.vault.base.VaultPortfolio

prepare_swap_with_intent(token_in, token_out, swap_amount, slippage, remaining_tokens, swap_all=False, from_=None, retries=5, manage_token_list=True, swap_all_tripwire_pct=0.01)

Prepare a swap transaction using Enso intent engine and Vevlet API.

Parameters
Return type

dict

prepare_swap_with_enso(token_in, token_out, swap_amount, slippage, remaining_tokens, swap_all=False, from_=None, retries=5, manage_token_list=True, swap_all_tripwire_pct=0.01)

Legacy

Parameters
Return type

dict

prepare_deposit_with_enso(from_, deposit_token_address, amount, slippage)

Prepare a deposit transaction with Enso intents.

  • Velvet trades any incoming assets and distributes them on open positions

Returns

Ethereum transaction payload

Parameters
Return type

dict

prepare_redemption(from_, amount, withdraw_token_address, slippage)

Perform a redemption.

Returns

Ethereum transaction payload

Parameters
Return type

dict

fetch_denomination_token()

Read denomination token from onchain.

Use denomination_token() for cached access.

fetch_share_token()

Read share token details onchain.

Use share_token() for cached access.

fetch_nav()

Fetch the most recent onchain NAV value.

Returns

Vault NAV, denominated in denomination_token()

property symbol

Vault share token symbol

get_historical_reader()

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

Get deposit manager to deposit/redeem from the vault.

Return type

eth_defi.vault.deposit_redeem.VaultDepositManager

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

Note

None results 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: str | None

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

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

decimal.Decimal | None

fetch_denomination_token_address()

Get the address for the denomination token.

Triggers RCP call

Return type

eth_typing.evm.HexAddress

fetch_deposit_closed_reason()

Get human-readable reason why deposits are closed.

  • Override in protocol-specific subclasses

  • Default behaviour: assume deposits are always open (return None)

Returns

Human-readable string explaining why deposits are closed, or None if deposits are open.

Example reasons:

  • ”Epoch redemption window closed (opens in 14h)”

  • ”Vault paused by admin”

  • ”Max deposit cap reached”

  • ”Vault utilisation too high”

Return type

str | None

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

datetime.datetime | None

fetch_redemption_closed_reason()

Get human-readable reason why redemptions are closed.

  • Override in protocol-specific subclasses

  • Default behaviour: assume redemptions are always open (return None)

Returns

Human-readable string explaining why redemptions are closed, or None if redemptions are open.

Example reasons:

  • ”Epoch funding phase in progress (opens in 2d 5h)”

  • ”Vault paused by admin”

  • ”Vault utilisation too high - insufficient liquidity”

Return type

str | None

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

datetime.datetime | None

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

float | None

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

What is the estimated lock-up period for this vault.

Returns

None if not know

Return type

datetime.timedelta | 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.

Returns

Flag set.

Do not modify in place.

Return type

set[eth_defi.vault.flag.VaultFlag]

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_management_fee(block_identifier)

Get the current management fee as a percent.

Internal: Use get_fee_data().

Returns

0.1 = 10%

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

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

Return type

str | None

get_performance_fee(block_identifier)

Get the current performance fee as a percent.

Internal: Use get_fee_data().

Returns

0.1 = 10%

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

Return the name of the vault protocol.

Return type

str

get_risk()

Get risk profile of this vault.

Return type

eth_defi.vault.risk.VaultTechnicalRisk | None

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

bool

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: str | None

One-liner vault summary.

  • Shorter version of description() suitable for listings and tables

  • Returns None if not available

  • Override in subclasses that support offchain metadata

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.