erc_4626.vault_protocol.lagoon.deployment

Documentation for eth_defi.erc_4626.vault_protocol.lagoon.deployment Python module.

Deploy new Lagoon vaults.

Lagoon automatised vault consists of

  • Safe multisig - we use 1.4.1 here

  • Vault module

  • Lagoon protocol smart contracts

  • TradingStrategyModuleV0 module enabling guarded automated trade executor for the Safe

  • Support deployments with Forge and Etherscan verification

Any Safe must be deployed as 1-of-1 deployer address multisig and multisig holders changed after the deployment.

Functions

deploy_automated_lagoon_vault(*, web3, deployer)

Deploy a full Lagoon setup with a guard.

deploy_fresh_lagoon_protocol(web3, deployer, ...)

Deploy a fresh Lagoon implementation from the scratch.

deploy_lagoon(web3, deployer, safe, ...[, ...])

Deploy a new Lagoon vault.

deploy_lagoon_protocol_registry(web3, ...[, ...])

Deploy a fee registry contract.

deploy_multichain_lagoon_vault(*, ...[, ...])

Deploy Lagoon vaults across multiple chains with a shared deterministic Safe.

deploy_safe_trading_strategy_module(web3, ...)

Deploy TradingStrategyModuleV0 for Safe and Lagoon.

setup_guard(*, web3, safe, deployer, owner, ...)

Setups up TradingStrategyModuleV0 guard on the Lagoon vault.

should_enable_hypercore_guard(*, chain_id, ...)

Should Hypercore guard support be enabled for this deployment.

Classes

LagoonAutomatedDeployment

Capture information of the lagoon automated deployment.

LagoonConfig

Configuration for Lagoon vault deployment.

LagoonDeploymentParameters

Capture core parameters needed to deploy a Lagoon vault

LagoonMultichainDeployment

Result of deploying Lagoon vaults across multiple chains with a shared deterministic Safe.

WhitelistEntry

A single guard whitelist entry recorded during deployment.
class LagoonAutomatedDeployment

Bases: object

Capture information of the lagoon automated deployment.

  • Have the deployment report for the users for diagnostics

__init__(chain_id, vault, trading_strategy_module, asset_managers, valuation_manager, multisig_owners, deployer, block_number, parameters, vault_abi, safe_address=None, old_trading_strategy_module=None, beacon_proxy_factory=None, gas_used=None, safe_salt_nonce=None, whitelisted_items=())
Parameters
Return type

None

property asset_manager: eth_typing.evm.HexAddress

Get the primary asset manager.

Kept for backwards compatibility with single-key deployments.

format_whitelisted_items(indent='    ')

Format whitelisted items as a human-readable string.

Parameters

indent (str) –

Return type

str

get_deployment_data()

Get JSON data describing the deployment.

Store all addresses etc.

Return type

dict

property is_satellite: bool

Whether this deployment is a satellite chain (Safe + guard only, no vault).

pformat()

Return pretty print of deployment info.

Return type

str

class LagoonConfig

Bases: object

Configuration for Lagoon vault deployment.

Captures all parameters needed to deploy a Lagoon vault except the chain connection (web3) and deployer account.

Can be passed to deploy_automated_lagoon_vault() (single chain) or deploy_multichain_lagoon_vault() (multiple chains).

__init__(parameters, safe_owners, safe_threshold, asset_manager=None, asset_managers=None, uniswap_v2=None, uniswap_v3=None, aave_v3=None, cowswap=False, velora=False, gmx_deployment=None, cctp_deployment=None, any_asset=False, etherscan_api_key=None, verifier=None, verifier_url=None, use_forge=False, between_contracts_delay_seconds=5.0, erc_4626_vaults=None, guard_only=False, existing_vault_address=None, existing_safe_address=None, vault_abi='lagoon/v0.5.0/Vault.json', factory_contract=True, from_the_scratch=False, hypercore_vaults=None, assets=None, safe_salt_nonce=None, safe_proxy_factory_address=None, forge_cache_dir=None, deploy_retries=1, satellite_chain=False)
Parameters
Return type

None

class LagoonDeploymentParameters

Bases: object

Capture core parameters needed to deploy a Lagoon vault

__init__(underlying, name, symbol, safe=None, whitelistManager=None, valuationManager=None, admin=None, feeReceiver=None, feeRegistry=None, managementRate=200, performanceRate=2000, enableWhitelist=False, rateUpdateCooldown=86400, wrappedNativeToken=None)
Parameters
Return type

None

as_abi_encoded_bytes()

Return Lagoon vault initialization struct ABI encoded.

  • Before was passed as is, was changed to ABI encoded bytes in Lagoon v0.5.0.

  • Does not include wrappedNativeToken

  • Does not include feeRegistry, as it is passed separately.

Return type

hexbytes.main.HexBytes

get_create_vault_proxy_arguments()

For createVaultProxy()

Return type

list[Any]

class LagoonMultichainDeployment

Bases: object

Result of deploying Lagoon vaults across multiple chains with a shared deterministic Safe.

All vaults share the same deterministic Safe address created via CREATE2 with the same salt nonce on each chain.

__init__(safe_address, deployments, safe_salt_nonce)
Parameters
Return type

None

class WhitelistEntry

Bases: object

A single guard whitelist entry recorded during deployment.

__init__(kind, name, address='')
Parameters
Return type

None

deploy_automated_lagoon_vault(*, web3, deployer, config=None, asset_manager=None, asset_managers=None, parameters=None, safe_owners=None, safe_threshold=None, uniswap_v2=None, uniswap_v3=None, aave_v3=None, cowswap=False, velora=False, gmx_deployment=None, cctp_deployment=None, hypercore_vaults=None, any_asset=False, etherscan_api_key=None, verifier=None, verifier_url=None, use_forge=False, between_contracts_delay_seconds=5.0, erc_4626_vaults=None, guard_only=False, existing_vault_address=None, existing_safe_address=None, vault_abi='lagoon/v0.5.0/Vault.json', factory_contract=True, from_the_scratch=False, assets=None, safe_salt_nonce=None, safe_proxy_factory_address=None)

Deploy a full Lagoon setup with a guard.

Lagoon automatised vault consists of

  • Safe multisig - we use 1.4.1 here

  • Vault module

  • Lagoon protocol smart contracts

  • TradingStrategyModuleV0 module enabling guarded automated trade executor for the Safe

For roles - The primary asset manager and Valuation Manager (Lagoon) are the same role - Multiple asset-manager keys may share the same Guard rights; today this

mainly supports separate FreqTrade and GMX trading keys, but other workflows may use the same pattern in the future

  • Any Safe must be deployed as 1-of-1 deployer address multisig and multisig holders changed after the deployment.

Warning

Because we need to mix Forge, Safe lib and Web3.py transaction nonce management becomes a madness.

Note

Deployer account must be manually removed from the Safe by new owners.

Parameters
Return type

eth_defi.erc_4626.vault_protocol.lagoon.deployment.LagoonAutomatedDeployment

deploy_fresh_lagoon_protocol(web3, deployer, safe, broadcast_func, etherscan_api_key=None, verifier=None, verifier_url=None, forge_sync_delay=4.0, cache_dir=None, deploy_retries=1)

Deploy a fresh Lagoon implementation from the scratch.

  • Fee registry contract

  • Vault implementation

  • Beacon proxy factory contract

Parameters

  • cache_dir (Optional[pathlib.Path]) – Isolated directory for forge cache and output artifacts. Allows concurrent deployments from the same source tree.

  • web3 (web3.main.Web3) –

  • deployer (eth_defi.hotwallet.HotWallet) –

  • safe (safe_eth.safe.safe.Safe) –

  • broadcast_func (Callable) –

  • etherscan_api_key (str) –

  • verifier (Optional[Literal['etherscan', 'blockscout', 'sourcify', 'oklink']]) –

  • verifier_url (Optional[str]) –

  • deploy_retries (int) –

Return type

web3.contract.contract.Contract

deploy_lagoon(web3, deployer, safe, asset_manager, parameters, owner, gas=2000000, etherscan_api_key=None, use_forge=False, beacon_proxy=False, factory_contract=True, beacon_address='0x652716FaD571f04D26a3c8fFd9E593F17123Ab20', beacon_proxy_factory_address=None, beacon_proxy_factory_abi='lagoon/BeaconProxyFactory.json', vault_abi='lagoon/v0.5.0/Vault.json', deploy_fee_registry=True, fee_registry_address=None, legacy=False, salt=b'\x01\x01\x01\x01\x01\x01\x01\x01\x01\x01\x01\x01\x01\x01\x01\x01\x01\x01\x01\x01\x01\x01\x01\x01\x01\x01\x01\x01\x01\x01\x01\x01', optin_proxy_delay=259200)

Deploy a new Lagoon vault.

  • Create a new Safe

  • Create a new Lagoon vault

  • Set guard policies

  • Set owership

For Foundry recipe see https://github.com/hopperlabsxyz/lagoon-v0/blob/main/script/deploy_vault.s.sol

Parameters
Returns

Vault contract.

Is a proxy contract.

Return type

web3.contract.contract.Contract

deploy_lagoon_protocol_registry(web3, deployer, safe, broadcast_func, etherscan_api_key=None, verifier=None, verifier_url=None, cache_dir=None, deploy_retries=1)

Deploy a fee registry contract.

  • This is referred by all Lagoon deployments

Parameters
Return type

web3.contract.contract.Contract

deploy_multichain_lagoon_vault(*, chain_web3, deployer, chain_configs, max_workers=None)

Deploy Lagoon vaults across multiple chains with a shared deterministic Safe.

Uses CREATE2 via the canonical Safe v1.4.1 ProxyFactory to produce the same Safe address on every chain. Each chain gets its own vault and guard deployment, but all vaults share the same Safe multisig address.

Deploys all chains in parallel using threads to minimise wall-clock time.

Each chain receives its own LagoonConfig with chain-specific whitelisting (ERC-4626 vaults, Hypercore vaults, CCTP, CowSwap, etc.). All configs must share the same safe_salt_nonce to ensure deterministic Safe addresses.

Parameters

  • chain_web3 (dict[str, web3.main.Web3]) – Mapping of chain names (lowercase, matching eth_defi.chain.CHAIN_NAMES) to Web3 instances. Example: {"ethereum": w3_eth, "arbitrum": w3_arb}.

  • deployer (eth_account.signers.local.LocalAccount) – The deployer account. A separate HotWallet is created per chain for nonce management.

  • chain_configs (dict[str, eth_defi.erc_4626.vault_protocol.lagoon.deployment.LagoonConfig]) – Per-chain LagoonConfig instances. Keys must match chain_web3 keys. All configs must have the same safe_salt_nonce set. The parameters.underlying field is auto-resolved per chain from eth_defi.token.USDC_NATIVE_TOKEN if set to a zero/empty address.

  • max_workers (Optional[int]) – Maximum number of parallel deployment threads. Defaults to the number of chains.

Returns

LagoonMultichainDeployment with per-chain results.

Return type

eth_defi.erc_4626.vault_protocol.lagoon.deployment.LagoonMultichainDeployment

deploy_safe_trading_strategy_module(web3, deployer, safe, use_forge=False, etherscan_api_key=None, verifier=None, verifier_url=None, enable_on_safe=True, uniswap_v2=None, uniswap_v3=None, cowswap=False, velora=False, gmx_deployment=None)

Deploy TradingStrategyModuleV0 for Safe and Lagoon.

On HyperEVM chains, automatically enables big blocks only for the TradingStrategyModuleV0 deployment (~5.4M gas). Library deployments (CowSwapLib, GmxLib, HypercoreVaultLib, VeloraLib) fit in small blocks and are deployed without toggling.

Parameters
Returns

TradingStrategyModuleV0 instance

Return type

web3.contract.contract.Contract

setup_guard(*, web3, safe, deployer, owner, asset_managers, vault, module, broadcast_func, any_asset=False, uniswap_v2=None, uniswap_v3=None, aave_v3=None, erc_4626_vaults=None, cowswap=False, velora=False, gmx_deployment=None, cctp_deployment=None, hypercore_vaults=None, hack_sleep=20.0, assets=None, multicall_chunk_size=40, underlying_token_address=None)

Setups up TradingStrategyModuleV0 guard on the Lagoon vault.

  • Creates the guard smart contract (TradingStrategyModuleV0) and enables it on the Safe multisig as a module.

  • Runs through various whitelisting rules as transactions against this contract

Parameters
Returns

List of WhitelistEntry recording everything that was whitelisted.

Return type

list[eth_defi.erc_4626.vault_protocol.lagoon.deployment.WhitelistEntry]

should_enable_hypercore_guard(*, chain_id, any_asset, hypercore_vaults)

Should Hypercore guard support be enabled for this deployment.

any_asset=True intentionally bypasses per-vault Hypercore address checks, but Hypercore deposits and withdrawals still require CoreWriter actions and CoreDepositWallet approval/target validation to be whitelisted.

Parameters
Return type

bool