LagoonConfig

Documentation for eth_defi.erc_4626.vault_protocol.lagoon.deployment.LagoonConfig Python class.

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.

Attributes summary

parameters

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

safe_owners

Addresses of Safe multisig owners

safe_threshold

Number of owner signatures required for Safe transactions

asset_manager

Primary asset manager kept for backwards compatibility.

asset_managers

Addresses that manage vault assets and execute trades.

uniswap_v2

Uniswap V2 deployment for router whitelisting

uniswap_v3

Uniswap V3 deployment for router/quoter whitelisting

aave_v3

Aave V3 deployment for lending whitelisting

cowswap

Enable CowSwap settlement contract whitelisting

velora

Enable Velora contract whitelisting

gmx_deployment

GMX perpetuals deployment for whitelisting

lighter_deployment

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

cctp_deployment

CCTP V2 deployment for cross-chain USDC transfers

any_asset

Allow any ERC-20 asset instead of explicit whitelist

etherscan_api_key

Etherscan API key for contract verification

verifier

Block explorer for contract verification

verifier_url

Custom block explorer URL

use_forge

Use Forge for contract deployment

between_contracts_delay_seconds

Delay between contract deployments (seconds) for nonce propagation

erc_4626_vaults

ERC-4626 vaults to whitelist for deposit/withdrawal

guard_only

Deploy only the guard, skip vault deployment

existing_vault_address

Reuse an existing vault (requires guard_only=True)

existing_safe_address

Reuse an existing Safe instead of deploying a new one

vault_abi

Vault contract ABI file path

factory_contract

Use BeaconProxyFactory for vault deployment

from_the_scratch

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

max_settlement_amount

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

settlement_cooldown

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

hypercore_vaults

Hypercore native vault addresses to whitelist (HyperEVM only).

assets

ERC-20 token addresses to whitelist

safe_salt_nonce

CREATE2 salt for deterministic Safe address across chains

safe_proxy_factory_address

Override Safe ProxyFactory address (default: v1.4.1 canonical).

forge_cache_dir

Isolated directory for forge cache and output artifacts.

deploy_retries

Number of forge deploy retries on "contract was not deployed" errors.

satellite_chain

When True, deploy only Safe + TradingStrategyModuleV0 guard (no vault).

Methods summary

__init__(parameters, safe_owners, safe_threshold)

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