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.

Module Attributes

DEFAULT_LAGOON_SETTLEMENT_COOLDOWN

Default minimum delay between non-zero asset-manager Lagoon settlements.

LAGOON_SETTLEMENT_LIMIT_INTERNAL_VERSION

Earliest GuardV0 internal ABI version with the complete Lagoon v0.5 asset-manager settlement safety policy: gross cap plus enforced cooldown.

DEFAULT_DEPLOYMENT_GAS_MULTIPLIER

Safety multiplier applied to the node eth_estimateGas result for guard setup / deployment broadcasts.

DEFAULT_LAGOON_VAULT_JSON

Packaged ABI for the only Lagoon version whose settlement balance invariant is currently enforced by LagoonLib.

LEGACY_LAGOON_VAULT_JSON

Packaged ABI for the unsupported pre-v0.5 Lagoon deployment path.

LAGOON_BEACON_PROXY_FACTORIES

https://basescan.org/address/0xC953Fd298FdfA8Ed0D38ee73772D3e21Bf19c61b#writeContract https://docs.lagoon.finance/vault/create-your-vault

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

Set up a TradingStrategyModuleV0 guard for its paired Lagoon vault and Safe.

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.
DEFAULT_LAGOON_SETTLEMENT_COOLDOWN = 86400

Default minimum delay between non-zero asset-manager Lagoon settlements.

The maximum gross settlement amount is a safety feature, so it must also rate-limit repeated below-cap calls. Twenty-four hours gives governance time to observe and respond to each automated movement while retaining a direct Safe recovery path.

LAGOON_SETTLEMENT_LIMIT_INTERNAL_VERSION = 3

Earliest GuardV0 internal ABI version with the complete Lagoon v0.5 asset-manager settlement safety policy: gross cap plus enforced cooldown.

DEFAULT_DEPLOYMENT_GAS_MULTIPLIER = 2.0

Safety multiplier applied to the node eth_estimateGas result for guard setup / deployment broadcasts.

Some L2s — Arbitrum in particular — under-estimate eth_estimateGas for simple guard-configuration calls (e.g. allowReceiver), causing the transaction to revert on-chain with “out of gas” even though the estimate was accepted. A multiplier on the estimate avoids this; the sender is still only charged for gas actually used, so over-provisioning the limit is free.

DEFAULT_LAGOON_VAULT_JSON = 'lagoon/v0.5.0/Vault.json'

Packaged ABI for the only Lagoon version whose settlement balance invariant is currently enforced by LagoonLib.

LEGACY_LAGOON_VAULT_JSON = 'lagoon/Vault.json'

Packaged ABI for the unsupported pre-v0.5 Lagoon deployment path.

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

class LagoonDeploymentParameters

Bases: object

Capture core parameters needed to deploy a Lagoon vault

managementRate: int

Management fee in BPS

performanceRate: int

Performance fee in BPS

rateUpdateCooldown: int

Max rate update frequency, seconds

wrappedNativeToken: Optional[eth_typing.evm.HexAddress]

If set None, then autoresolve

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]

__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

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

The optional max_settlement_amount is a Guard safety policy, not a Lagoon vault initialisation parameter. It is therefore kept on this deployment configuration instead of LagoonDeploymentParameters. When configured, deployment binds the Guard to the stock Lagoon v0.5 vault’s underlying token and pending-deposit Silo, and enables atomic post-call validation in TradingStrategyModuleV0.

The safety feature controls gross underlying-token movement in one asset-manager settlement transaction and rate-limits non-zero calls. Deposit assets moving from the Silo to the Safe and redemption assets moving from the Safe to the vault are added rather than netted. The paired settlement_cooldown defaults to 24 hours so an asset manager cannot drain the vault with repeated individually valid non-zero calls. Empty settlements neither start nor wait for cooldown. The policy does not validate the NAV supplied to Lagoon. Safe governance can still settle directly without going through the asset-manager module.

parameters: eth_defi.erc_4626.vault_protocol.lagoon.deployment.LagoonDeploymentParameters

Vault parameters (name, symbol, underlying token, fees)

safe_owners: list[eth_typing.evm.HexAddress | str]

Addresses of Safe multisig owners

safe_threshold: int

Number of owner signatures required for Safe transactions

asset_manager: Optional[eth_typing.evm.HexAddress]

Primary asset manager kept for backwards compatibility.

Deprecated in favour of asset_managers. When both are provided, asset_managers wins.

asset_managers: Optional[list[eth_typing.evm.HexAddress | str]]

Addresses that manage vault assets and execute trades.

All entries are whitelisted as guard senders. The first entry becomes the primary asset manager and is used as the Lagoon valuation manager unless parameters.valuationManager was explicitly set.

The main use case today is splitting permissions between FreqTrade and GMX trading keys while keeping the same Guard rights. Future automated trading or operational workflows may reuse the same mechanism.

uniswap_v2: Optional[eth_defi.uniswap_v2.deployment.UniswapV2Deployment]

Uniswap V2 deployment for router whitelisting

uniswap_v3: Optional[eth_defi.uniswap_v3.deployment.UniswapV3Deployment]

Uniswap V3 deployment for router/quoter whitelisting

aave_v3: Optional[eth_defi.aave_v3.deployment.AaveV3Deployment]

Aave V3 deployment for lending whitelisting

cowswap: bool

Enable CowSwap settlement contract whitelisting

velora: bool

Enable Velora contract whitelisting

gmx_deployment: Optional[eth_defi.gmx.whitelist.GMXDeployment]

GMX perpetuals deployment for whitelisting

lighter_deployment: Optional[eth_defi.lighter.deployment.LighterDeployment]

Lighter (zk-rollup perps DEX, Ethereum L1) deployment for whitelisting

cctp_deployment: Optional[eth_defi.cctp.whitelist.CCTPDeployment]

CCTP V2 deployment for cross-chain USDC transfers

any_asset: bool

Allow any ERC-20 asset instead of explicit whitelist

etherscan_api_key: Optional[str]

Etherscan API key for contract verification

verifier: Optional[Literal['etherscan', 'blockscout', 'sourcify', 'oklink']]

Block explorer for contract verification

verifier_url: Optional[str]

Custom block explorer URL

use_forge: bool

Use Forge for contract deployment

between_contracts_delay_seconds: float

Delay between contract deployments (seconds) for nonce propagation

erc_4626_vaults: Optional[list[eth_defi.erc_4626.vault.ERC4626Vault]]

ERC-4626 vaults to whitelist for deposit/withdrawal

guard_only: bool

Deploy only the guard, skip vault deployment

existing_vault_address: Optional[Union[eth_typing.evm.HexAddress, str]]

Reuse an existing vault (requires guard_only=True)

existing_safe_address: Optional[Union[eth_typing.evm.HexAddress, str]]

Reuse an existing Safe instead of deploying a new one

vault_abi: str

Vault contract ABI file path

factory_contract: bool

Use BeaconProxyFactory for vault deployment

from_the_scratch: bool

Deploy fresh Lagoon protocol (fee registry + vault implementation + factory)

max_settlement_amount: Optional[decimal.Decimal]

Maximum gross Lagoon v0.5 settlement per asset-manager transaction.

Expressed as a Decimal in human-readable underlying token units; for example, Decimal("10000") means 10,000 USDC for a USDC vault. Deployment converts this value to raw token units using the underlying token’s onchain decimals() value.

None is the backwards-compatible default and keeps Lagoon settlement unlimited. Zero is a valid strict cap which permits only a settlement with zero measured asset movement.

The cap is supported only for a stock Lagoon v0.5 vault executed through its paired TradingStrategyModuleV0. It must not be set for a legacy Lagoon ABI or a satellite-chain configuration, because neither has the execution-aware vault settlement path needed to enforce the post-call balance check.

settlement_cooldown: int

Minimum delay between non-zero asset-manager Lagoon settlements.

Expressed in seconds and enforced only when max_settlement_amount is configured. The default is 24 hours. Empty settlements do not start or extend the cooldown and remain callable while it is active. The value must be positive because a zero cooldown would allow repeated non-zero below-cap calls and defeat the safety feature. Direct Safe governance calls bypass this module policy.

hypercore_vaults: Optional[list[eth_typing.evm.HexAddress | str]]

Hypercore native vault addresses to whitelist (HyperEVM only). When set, also whitelists CoreWriter and CoreDepositWallet.

assets: Optional[list[eth_typing.evm.HexAddress | str]]

ERC-20 token addresses to whitelist

safe_salt_nonce: Optional[int]

CREATE2 salt for deterministic Safe address across chains

safe_proxy_factory_address: Optional[Union[eth_typing.evm.HexAddress, str]]

Override Safe ProxyFactory address (default: v1.4.1 canonical). See Safe canonical deployments and Safe contract deployment docs.

forge_cache_dir: Optional[pathlib.Path]

Isolated directory for forge cache and output artifacts. Allows concurrent forge deployments from the same source tree.

deploy_retries: int

Number of forge deploy retries on "contract was not deployed" errors. Only allowed on testnets. Default: 1 (no retries).

satellite_chain: bool

When True, deploy only Safe + TradingStrategyModuleV0 guard (no vault). Used for satellite chains in multichain deployments where only the source chain needs a vault contract.

__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, lighter_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, max_settlement_amount=None, settlement_cooldown=86400, 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 WhitelistEntry

Bases: object

A single guard whitelist entry recorded during deployment.

kind: str

Category (e.g. “Uniswap V3 router”, “ERC-4626 vault”, “CCTP”)

name: str

Human-readable name (e.g. token symbol, vault name)

address: Union[eth_typing.evm.HexAddress, str]

On-chain address, or empty string for non-address entries

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

None

class LagoonAutomatedDeployment

Bases: object

Capture information of the lagoon automated deployment.

  • Have the deployment report for the users for diagnostics

vault: Union[eth_defi.erc_4626.vault_protocol.lagoon.vault.LagoonVault, eth_defi.erc_4626.vault_protocol.lagoon.vault.LagoonSatelliteVault]

The deployed Lagoon vault, or LagoonSatelliteVault for satellite chains.

vault_abi: str

Vault ABI file we use

safe_address: eth_typing.evm.HexAddress

The Safe multisig address, stored explicitly so it is available even on satellite chains where there is no vault contract.

old_trading_strategy_module: Optional[web3.contract.contract.Contract]

In redeploy guard, the old module

beacon_proxy_factory: Optional[eth_typing.evm.HexAddress]

Address of beacon proxy factory

gas_used: Optional[decimal.Decimal]

How much ETH deployment used

safe_salt_nonce: Optional[int]

Salt nonce used for deterministic Safe proxy deployment.

Recorded so the deployment can be reproduced or debugged later. None when deployed without a deterministic address (e.g. from-scratch testnet).

whitelisted_items: tuple[eth_defi.erc_4626.vault_protocol.lagoon.deployment.WhitelistEntry, ...]

Items whitelisted on the guard during deployment.

property asset_manager: eth_typing.evm.HexAddress

Get the primary asset manager.

Kept for backwards compatibility with single-key deployments.

property is_satellite: bool

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

get_deployment_data()

Get JSON data describing the deployment.

Store all addresses etc.

Return type

dict

as_json_friendly_dict()

Get JSON-serialisable deployment data.

LagoonAutomatedDeployment contains live Web3 contract and vault objects that cannot be written to JSON directly. This method captures the deployment as plain JSON values, keeping enough addresses and parameters to reconstruct the deployment object with from_json_friendly_dict().

Returns

JSON-serialisable Lagoon deployment information.

Return type

dict[str, Any]

classmethod from_json_friendly_dict(web3, data)

Recreate deployment information from JSON data.

This recreates the live Web3 contract and vault reader objects from addresses stored by as_json_friendly_dict(). The JSON payload does not contain private keys or signed transactions.

Parameters
Returns

Hydrated Lagoon deployment information.

Return type

eth_defi.erc_4626.vault_protocol.lagoon.deployment.LagoonAutomatedDeployment

pformat()

Return pretty print of deployment info.

Return type

str

format_whitelisted_items(indent='    ')

Format whitelisted items as a human-readable string.

Parameters

indent (str) –

Return type

str

__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

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.

safe_address: eth_typing.evm.HexAddress

The deterministic Safe address shared by all chains

deployments: dict[str, eth_defi.erc_4626.vault_protocol.lagoon.deployment.LagoonAutomatedDeployment]

Per-chain deployment results keyed by chain name (lowercase)

safe_salt_nonce: int

The salt nonce used for deterministic Safe deployment

__init__(safe_address, deployments, safe_salt_nonce)
Parameters
Return type

None

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_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, use_forge=True)

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.

  • use_forge – Use Forge source deployment for the vault implementation. Set to False in local testing when packaged ABI artefacts are enough.

  • 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

This is a low-level Lagoon protocol deployment helper. It deploys the vault contract but does not deploy or configure TradingStrategyModuleV0, so it cannot establish the asset-manager settlement safety policy by itself. Applications needing the settlement security policy must use deploy_automated_lagoon_vault() and pass max_settlement_amount=Decimal(...) or use LagoonConfig.

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_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, lighter_deployment=None, lagoon=True)

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.

This function only deploys and links the execution module. When lagoon is true it links LagoonLib, making settlement-safety calls available, but it does not know the vault, underlying asset, Silo or desired amount and therefore does not configure a limit. Use deploy_automated_lagoon_vault() for the public human-readable API, or call setup_guard() with raw token units in lower-level integrations.

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, lighter_deployment=None, cctp_deployment=None, hypercore_vaults=None, hack_sleep=20.0, assets=None, multicall_chunk_size=40, underlying_token_address=None, lagoon_pending_silo_address=None, lagoon_max_settlement_amount_raw=None, lagoon_settlement_cooldown=86400)

Set up a TradingStrategyModuleV0 guard for its paired Lagoon vault and Safe.

This function applies the onchain policy after the module has been deployed and enabled on the Safe. The deployment topology is one Lagoon vault, one Safe, and one TradingStrategyModuleV0; the module’s avatar and target must both be the supplied Safe.

Lagoon settlement safety requires an execution-aware module because it compares token balances before and after the Safe call in the same atomic transaction. A standalone GuardV0.validateCall() can perform only the pre-call half and must never be used to configure this guarantee. This function verifies the module/Safe pairing before broadcasting any policy transactions whenever a limit is requested.

lagoon_max_settlement_amount_raw is deliberately a lower-level raw-unit argument. Public deployment callers normally use deploy_automated_lagoon_vault() or LagoonConfig, which accept a human-readable Decimal and perform the token-decimal conversion. None selects the legacy unlimited allowlist call; zero is a valid strict cap. Every enabled cap also requires a positive cooldown; lagoon_settlement_cooldown defaults to 24 hours.

Parameters
Returns

List of WhitelistEntry recording everything that was whitelisted.

Return type

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

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, lighter_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, max_settlement_amount=None, settlement_cooldown=86400)

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.

Set max_settlement_amount to opt into the Lagoon v0.5 asset-manager settlement safety feature. The value is a Decimal in human-readable underlying-token units. Deployment discovers the stock v0.5 pending Silo, converts the value with the token’s actual decimals(), configures the paired module, and reads the complete onchain configuration back before continuing.

The cap is enforced atomically around an asset-manager call through TradingStrategyModuleV0. It measures the gross sum of deposits and redemptions, so opposite flows cannot evade the limit by netting. A rejected settlement reverts the complete Lagoon transaction. None preserves the historical unlimited settlement behaviour, while Decimal(0) permits only zero measured movement. Every successful non-zero call starts settlement_cooldown, which defaults to 24 hours, so the asset manager cannot drain the vault through repeated below-cap settlements. Empty settlements do not start, extend or wait for cooldown.

The amount check is per transaction and the cooldown rate-limits those transactions over time. It does not validate the NAV passed to Lagoon or restrict transactions signed directly by Safe governance. It requires the stock Lagoon v0.5 ABI and is unavailable on satellite chains, which have no Lagoon vault.

See the canonical Lagoon smart contract source for the underlying v0.5 settlement implementation.

Parameters
Return type

eth_defi.erc_4626.vault_protocol.lagoon.deployment.LagoonAutomatedDeployment

LAGOON_BEACON_PROXY_FACTORIES = {1: {'abi': 'lagoon/OptinProxyFactory.json', 'address': '0x8D6f5479B14348186faE9BC7E636e947c260f9B1'}, 143: {'abi': 'lagoon/OptinProxyFactory.json', 'address': '0xcCdC4d06cA12A29C47D5d105fED59a6D07E9cf70'}, 957: {'abi': 'lagoon/BeaconProxyFactory.json', 'address': '0x4058140097F313886536bd64a7C1D25FF7356931'}, 999: {'abi': 'lagoon/OptinProxyFactory.json', 'address': '0x90beB507A1BA7D64633540cbce615B574224CD84'}, 8453: {'abi': 'lagoon/BeaconProxyFactory.json', 'address': '0xC953Fd298FdfA8Ed0D38ee73772D3e21Bf19c61b'}, 42161: {'abi': 'lagoon/OptinProxyFactory.json', 'address': '0xb1ee4f77a1691696a737ab9852e389cf4cb1f1f5'}}

https://basescan.org/address/0xC953Fd298FdfA8Ed0D38ee73772D3e21Bf19c61b#writeContract https://docs.lagoon.finance/vault/create-your-vault

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. Every chain gets a distinct Safe contract and guard module at matching addresses. Non-satellite chains additionally get a Lagoon vault paired with that chain’s Safe.

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.) and an optional chain-specific Lagoon settlement safety policy. All configs must share the same safe_salt_nonce to ensure deterministic Safe addresses.

LagoonConfig.max_settlement_amount and its cooldown are forwarded to the public single-chain deployment API and is converted using that chain’s underlying token decimals. Configure it only for chains which deploy or reuse a Lagoon vault. Satellite chains contain only a Safe and guard module and therefore reject settlement-safety configuration instead of silently ignoring it.

Parameters
Returns

LagoonMultichainDeployment with per-chain results.

Return type

eth_defi.erc_4626.vault_protocol.lagoon.deployment.LagoonMultichainDeployment