LagoonVault

Documentation for eth_defi.lagoon.vault.LagoonVault Python class.

class LagoonVault[source]

Python interface for interacting with Lagoon Finance vaults.

For information see VaultBase base class documentation.

Notes

Vault contract knows about Safe, Safe does not know about the Vault
Ok so for settlement you dont have to worry about this metric, the only thing you have to value is the assets inside the safe (what you currently have under management) and update the NAV of the vault by calling updateNewTotalAssets (ex: if you have 1M inside the vault and 500K pending deposit you only need to call updateTotalAssets with the 1M that are currently inside the safe). Then, to settle you just call settleDeposit and the vault calculate everything for you.
To monitor the pending deposits it’s a bit more complicated. You have to check the balanceOf the pendingSilo contract (0xAD1241Ba37ab07fFc5d38e006747F8b92BB217D5) in term of underlying (here USDC) for pending deposit and in term of shares (so the vault itself) for pending withdraw requests

Lagoon tokens can be in - Safe: Tradeable assets - Silo: pending deposits (USDC) - Vault: pending redemptions (USDC) - User wallets: after deposit() have been called share tokens are moved to the user wallet

Attributes summary

`address`	Get the vault smart contract address.
`chain_id`
`denomination_token`	Get the token which denominates the vault valuation
`info`	Get info dictionary related to this vault deployment.
`name`	Vault name.
`safe`	Get the underlying Safe object used as an API from safe-eth-py library.
`safe_address`	Get Safe multisig contract address
`safe_contract`	Safe multisig as a contract.
`share_token`	ERC-20 that presents vault shares.
`silo_address`	Pending Silo contract address
`silo_contract`	Pending Silo contract.
`symbol`	Vault share token symbol
`trading_strategy_module`
`underlying_token`	Alias for `denomination_token()`
`valuation_manager`	Valuation manager role on the vault.
`vault_address`
`vault_contract`	Underlying Vault smart contract.

Methods summary

`__init__`(web3, spec[, ...])	param spec
`fetch_denomination_token`()	Read denomination token from onchain.
`fetch_info`()	Use `info()` property for cached access.
`fetch_nav`([block_identifier])	Fetch the most recent onchain NAV value.
`fetch_portfolio`(universe[, block_identifier])	Read the current token balances of a vault.
`fetch_safe`(address)	Use `safe()` property for cached access
`fetch_share_price`(block_identifier)	Get the current share price.
`fetch_share_token`()	Read share token details onchain.
`fetch_total_assets`(block_identifier)	What is the total NAV of the vault.
`fetch_total_supply`(block_identifier)	What is the current outstanding shares.
`fetch_vault_info`()	Get all information we can extract from the vault smart contracts.
`finalise_deposit`(depositor[, raw_amount])	Move shares we received to the user wallet.
`finalise_redeem`(depositor[, raw_amount])	Move redeemed assets to the user wallet.
`get_flow_manager`()	Get flow manager to read individial events.
`has_block_range_event_support`()	Does this vault support block range-based event queries for deposits and redemptions.
`has_deposit_distribution_to_all_positions`()	Deposits go automatically to all open positions.
`post_new_valuation`(total_valuation)	Update the valuations of this vault.
`post_valuation_and_settle`(valuation, ...[, gas])	Do both new valuation and settle.
`request_deposit`(depositor, raw_amount)	Build a deposit transction.
`request_redeem`(depositor, raw_amount)	Build a redeem transction.
`settle_via_trading_strategy_module`()	Settle the new valuation and deposits.
`transact_via_exec_module`(func_call[, value, ...])	Create a multisig transaction using a module.
`transact_via_trading_strategy_module`(func_call)	Create a Safe multisig transaction using TradingStrategyModuleV0.

__init__(web3, spec, trading_strategy_module_address=None)[source]

Parameters

spec (eth_defi.vault.base.VaultSpec) – Address must be Lagoon vault address (not Safe address)
trading_strategy_module_address (Optional[eth_typing.evm.HexAddress]) –
TradingStrategyModuleV0 enabled on Safe for automated trading.

If not given, not known.
web3 (web3.main.Web3) –

has_block_range_event_support()[source]

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()[source]

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()[source]

Get flow manager to read individial events.

Only supported if has_block_range_event_support() is True

Return type: eth_defi.lagoon.vault.LagoonFlowManager

fetch_safe(address)[source]

Use safe() property for cached access

Return type: safe_eth.safe.safe.Safe

property name: str: Vault name.

property symbol: str: Vault share token symbol

property vault_contract: web3.contract.contract.Contract: Underlying Vault smart contract.

fetch_vault_info()[source]

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

Return type: dict

fetch_denomination_token()[source]

Read denomination token from onchain.

Use denomination_token() for cached access.

Return type: eth_defi.token.TokenDetails

fetch_share_token()[source]

Read share token details onchain.

Use share_token() for cached access.

Return type: eth_defi.token.TokenDetails

fetch_info()[source]

Use info() property for cached access.

Returns: See LagoonVaultInfo
Return type: eth_defi.lagoon.vault.LagoonVaultInfo

fetch_nav(block_identifier=None)[source]

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_total_assets(block_identifier)[source]

What is the total NAV of the vault.

Returns: The vault value in underlyinh token
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: decimal.Decimal

fetch_total_supply(block_identifier)[source]

What is the current outstanding shares.

Returns: The vault value in underlyinh token
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: decimal.Decimal

fetch_share_price(block_identifier)[source]

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

Return type

decimal.Decimal

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

property safe_address: eth_typing.evm.HexAddress: Get Safe multisig contract address

property safe: safe_eth.safe.safe.Safe

Get the underlying Safe object used as an API from safe-eth-py library.

Warps Safe Contract using Gnosis’s in-house library

property safe_contract: web3.contract.contract.Contract

Safe multisig as a contract.

Interact with Safe multisig ABI

property valuation_manager: eth_typing.evm.HexAddress: Valuation manager role on the vault.

property silo_address: eth_typing.evm.HexAddress: Pending Silo contract address

property silo_contract: web3.contract.contract.Contract

Pending Silo contract.

This contract does not have any functionality, but stores deposits (pending USDC) and redemptions (pending share token)

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

fetch_portfolio(universe, block_identifier=None)[source]

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

transact_via_exec_module(func_call, value=0, operation=0)[source]

Create a multisig transaction using a module.

Calls execTransactionFromModule on Gnosis Safe contract
Executes a transaction as a multisig
Mostly used for testing w/whitelist ignore

Warning

A special gas fix is needed, because eth_estimateGas seems to fail for these Gnosis Safe transactions.

Example:

# Then settle the valuation as the vault owner (Safe multisig) in this case
settle_call = vault.settle()
moduled_tx = vault.transact_through_module(settle_call)
tx_data = moduled_tx.build_transaction({
    "from": asset_manager,
})
# Normal estimate_gas does not give enough gas for
# Safe execTransactionFromModule() transaction for some reason
gnosis_gas_fix = 1_000_000
tx_data["gas"] = web3.eth.estimate_gas(tx_data) + gnosis_gas_fix
tx_hash = web3.eth.send_transaction(tx_data)
assert_execute_module_success(web3, tx_hash)

Parameters

func_call (web3.contract.contract.ContractFunction) – Bound smart contract function call
value (int) – ETH attached to the transaction
operation – Gnosis enum.

Return type

web3.contract.contract.ContractFunction

transact_via_trading_strategy_module(func_call)[source]

Create a Safe multisig transaction using TradingStrategyModuleV0.

Parameters

module – Deployed TradingStrategyModuleV0 contract that is enabled on Safe.
func_call (web3.contract.contract.ContractFunction) – Bound smart contract function call

Returns

Bound Solidity functionc all you need to turn to a transaction

Return type

web3.contract.contract.ContractFunction

post_new_valuation(total_valuation)[source]

Update the valuations of this vault.

Lagoon vault does not currently track individual positions, but takes a “total value” number
Updating this number also allows deposits and redemptions to proceed

Notes:

How can I post a valuation commitee update 1. as the valuationManager, call the function updateNewTotalAssets(_newTotalAssets) _newTotalAssets being expressed in underlying in its smallest unit for usdc, it would with its 6 decimals. Do not take into account requestDeposit and requestRedeem in your valuation

as the safe, call the function settleDeposit()

Parameters: total_valuation (decimal.Decimal) – The vault value nominated in denomination_token().
Returns: Bound contract function that can be turned to a transaction
Return type: web3.contract.contract.ContractFunction

settle_via_trading_strategy_module()[source]

Settle the new valuation and deposits.

settleDeposit will also settle the redeems request if possible. If there are enough assets in the safe it will settleRedeem It there are not enough assets, it will only settleDeposit.
if there is nothing to settle: no deposit and redeem requests you can still call settleDeposit/settleRedeem to validate the new nav
If there is not enough USDC to redeem, the transaction will revert

Return type: web3.contract.contract.ContractFunction

post_valuation_and_settle(valuation, asset_manager, gas=1000000)[source]

Do both new valuation and settle.

Quickhand method for asset_manager code
Only after this we can read back
Broadcasts two transactions and waits for the confirmation
If there is not enough USDC to redeem, the second transaction will fail with revert

Returns

The transaction hash of the settlement transaction

Parameters

valuation (decimal.Decimal) –
asset_manager (eth_typing.evm.HexAddress) –

Return type

hexbytes.main.HexBytes

request_deposit(depositor, raw_amount)[source]

Build a deposit transction.

Phase 1 of deposit before settlement
Used for testing
Must be approved() first
Uses the vault underlying token (USDC)

Parameters

raw_amount (int) – Raw amount in underlying token
depositor (eth_typing.evm.HexAddress) –

Return type

web3.contract.contract.ContractFunction

finalise_deposit(depositor, raw_amount=None)[source]

Move shares we received to the user wallet.

Phase 2 of deposit after settlement

Parameters

depositor (eth_typing.evm.HexAddress) –
raw_amount (Optional[int]) –

Return type

web3.contract.contract.ContractFunction

request_redeem(depositor, raw_amount)[source]

Build a redeem transction.

Phase 1 of redemption, before settlement
Used for testing
Sets up a redemption request for X shares

Parameters

raw_amount (int) – Raw amount in share token
depositor (eth_typing.evm.HexAddress) –

Return type

web3.contract.contract.ContractFunction

finalise_redeem(depositor, raw_amount=None)[source]

Move redeemed assets to the user wallet.

Phase 2 of the redemption

Parameters

depositor (eth_typing.evm.HexAddress) –
raw_amount (Optional[int]) –

Return type

web3.contract.contract.ContractFunction