VelvetVault

Documentation for eth_defi.velvet.vault.VelvetVault Python class.

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)

Attributes summary

address	Vault contract address.
chain_id	Chain this vault is on
denomination_token	Get the token which denominates the vault valuation
deposit_manager	Deposit manager assocaited with this vault
deposit_manager_address
flow_manager	Flow manager associated with this vault
info	Get info dictionary related to this vault deployment.
name	Vault name.
owner_address
portfolio_address
portfolio_contract
rebalance_address
share_token	ERC-20 that presents vault shares.
symbol	Vault share token symbol
token_symbol
vault_address
withdraw_manager_address

Methods summary

__init__(web3, spec[, api_url])	param spec
check_valid_contract()	Check that we have connected to a proper Velvet capital vault contract, not wrong contract.
fetch_denomination_token()	Read denomination token from onchain.
fetch_denomination_token_address()	Get the address for the denomination token.
fetch_deposit_closed_reason()	Get human-readable reason why deposits are closed.
fetch_deposit_next_open()	Get when deposits will next be open.
fetch_info()	Read vault parameters from the chain.
fetch_nav()	Fetch the most recent onchain NAV value.
fetch_portfolio(universe[, block_identifier])	Read the current token balances of a vault.
fetch_redemption_closed_reason()	Get human-readable reason why redemptions are closed.
fetch_redemption_next_open()	Get when withdrawals/redemptions will next be open.
fetch_share_token()	Read share token details onchain.
get_deposit_fee(block_identifier)	Deposit fee is set to zero by default as vaults usually do not have deposit fees.
get_deposit_manager()	Get deposit manager to deposit/redeem from the vault.
get_estimated_lock_up()	What is the estimated lock-up period for this vault.
get_fee_data()	Get fee data structure for this vault.
get_fee_mode()	Get how this vault accounts its fees.
get_flags()	Get various vault state flags from the smart contract.
get_flow_manager()	Get flow manager to read indiviaul settle events.
get_historical_reader()	Get share price reader to fetch historical returns.
get_link([referral])	Get a link to the vault dashboard on its native site.
get_management_fee(block_identifier)	Get the current management fee as a percent.
get_notes()	Get a human readable message if we know somethign special is going on with this vault.
get_performance_fee(block_identifier)	Get the current performance fee as a percent.
get_protocol_name()	Return the name of the vault protocol.
get_risk()	Get risk profile of this vault.
get_spec()
get_withdraw_fee(block_identifier)	Withdraw fee is set to zero by default as vaults usually do not have withdraw fees.
has_block_range_event_support()	Does this vault support block range-based event queries for deposits and redemptions.
has_custom_fees()	Does this vault have custom fee structure reading methods.
has_deposit_distribution_to_all_positions()	Deposits go automatically to all open positions.
prepare_deposit_with_enso(from_, ...)	Prepare a deposit transaction with Enso intents.
prepare_redemption(from_, amount, ...)	Perform a redemption.
prepare_swap_with_enso(token_in, token_out, ...)	Legacy
prepare_swap_with_intent(token_in, ...[, ...])	Prepare a swap transaction using Enso intent engine and Vevlet API.

__init__(web3, spec, api_url='https://intents.velvet.capital/api/v1')

Parameters

• spec (eth_defi.vault.base.VaultSpec) – Address must be Velvet portfolio address (not vault address)

• web3 (web3.main.Web3) –

• api_url (str) –

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.

• Only supported if has_block_range_event_support() is True

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

• 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, int]]) –

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

• from –

  Fill int the from field for the tx data.

  Used with Anvil and unlocked accounts.

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

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

• swap_amount (int) –

• slippage (float) –

• remaining_tokens (set | list) –

• from_ (Optional[Union[eth_typing.evm.HexAddress, str]]) –

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

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

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

• swap_amount (int) –

• slippage (float) –

• remaining_tokens (set | list) –

• from_ (Optional[Union[eth_typing.evm.HexAddress, str]]) –

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

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

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

• amount (int) –

• slippage (float) –

Return type

dict

prepare_redemption(from_, amount, withdraw_token_address, slippage)

Perform a redemption.

Returns

Ethereum transaction payload

Parameters

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

• amount (int) –

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

• slippage (float) –

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

property deposit_manager: eth_defi.vault.deposit_redeem.VaultDepositManager

Deposit manager assocaited with this vault

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

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.

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