lighter.deployment

Documentation for eth_defi.lighter.deployment Python module.

Lighter guard whitelisting and library deployment.

Production helpers for enabling Lighter (a zk-rollup perpetuals/spot DEX on Ethereum L1) deposits and withdrawals through an asset-managed Gnosis Safe governed by GuardV0 / TradingStrategyModuleV0.

This module is the single source of truth for Lighter guard configuration. It is called both by the Lagoon vault deployment flow (eth_defi.erc_4626.vault_protocol.lagoon.deployment) and by the Anvil-fork tests (via eth_defi.lighter.testing).

The on-chain scope is the L1 custody flow only: deposit / withdraw / withdrawPendingBalance. Account registration is off-chain (EIP-712 / EIP-1271 Safe signature) and does not go through the guard.

See eth_defi/lighter/README-lighter-guard.md for the architecture and security model.

Authoritative docs:

Functions

deploy_lighter_lib(web3, deployer)

Deploy the LighterLib external Forge library.

setup_lighter_whitelisting(web3, module, ...)

Whitelist the Lighter L1 contract on a guard / module.

Classes

LighterDeployment

Lighter L1 deployment configuration for guard whitelisting.

LighterWhitelistEntry

A single Lighter whitelisting action, for deployment reporting.
class LighterDeployment

Bases: object

Lighter L1 deployment configuration for guard whitelisting.

Note

USDC-only. This integration currently whitelists a single Lighter deposit asset — USDC — whose on-chain asset index is read from ZkLighter.USDC_ASSET_INDEX() at whitelist time. Multiple deposit assets / asset indexes are not yet supported (unlike Hypercore, which whitelists multiple vaults via a single multicall). Adding more assets would require a multi-asset whitelistLighter (or a whitelistLighterAssetIndex helper) plus multicall batching.

Variables

  • zk_lighter – The ZkLighter L1 contract (proxy) address. Holds user deposits.

  • usdc – The USDC token address used as the (single) Lighter deposit asset.

__init__(zk_lighter, usdc)
Parameters
Return type

None

classmethod create_ethereum()

Create the canonical Ethereum mainnet Lighter deployment.

Return type

eth_defi.lighter.deployment.LighterDeployment

class LighterWhitelistEntry

Bases: object

A single Lighter whitelisting action, for deployment reporting.

Deliberately Lagoon-independent: the Lagoon deployment module wraps these rows into its own WhitelistEntry type. eth_defi.lighter.deployment must not import WhitelistEntry from the Lagoon module, as that would create a circular import (Lagoon imports this module).

__init__(category, name, address)
Parameters
Return type

None

deploy_lighter_lib(web3, deployer)

Deploy the LighterLib external Forge library.

The library must be deployed and linked into the guard / module at deployment time, exactly like GmxLib and HypercoreVaultLib. The Lagoon deployment flow calls this to populate library_addresses["LighterLib"].

Parameters
Returns

The deployed LighterLib contract.

Return type

web3.contract.contract.Contract

setup_lighter_whitelisting(web3, module, owner, deployment, safe_address, notes='Lighter deposits', broadcast=None)

Whitelist the Lighter L1 contract on a guard / module.

Reads the USDC asset index from the ZkLighter contract (USDC_ASSET_INDEX()) and calls whitelistLighter(zkLighter, usdc, assetIndex, notes).

USDC-only: a single deposit asset (USDC) is whitelisted. Multiple asset indexes are not supported yet (see LighterDeployment). Unlike setup_hypercore_whitelisting this issues sequential transactions rather than a single multicall — there is only ever one whitelistLighter call (plus an optional allowReceiver), so batching buys little here.

The Safe must be an allowed receiver (for deposit._to / withdrawPendingBalance._owner). In the Lagoon flow setup_guard already calls allowReceiver(safe) globally, so this helper calls it only if isAllowedReceiver(safe) is currently false — avoiding a duplicate receiver event. Standalone/test callers still get the Safe whitelisted.

Parameters

  • web3 (web3.main.Web3) – Web3 connection.

  • module (web3.contract.contract.Contract) – Deployed GuardV0 or TradingStrategyModuleV0 contract exposing whitelistLighter / allowReceiver / isAllowedReceiver.

  • owner (Union[eth_typing.evm.HexAddress, str]) – Guard owner address (used by the default broadcaster).

  • deployment (eth_defi.lighter.deployment.LighterDeployment) – Lighter deployment configuration (contract + USDC addresses).

  • safe_address (Union[eth_typing.evm.HexAddress, str]) – The Safe address — the Lighter account owner and the allowed receiver.

  • notes (str) – Annotation stored in the whitelisting event logs.

  • broadcast (Optional[Callable[[web3.contract.contract.ContractFunction], hexbytes.main.HexBytes]]) – Optional transaction broadcaster taking a bound contract function and returning a tx hash (lets the Lagoon flow reuse its own broadcaster). Defaults to func.transact({"from": owner}) + success assertion.

Returns

Lagoon-independent LighterWhitelistEntry rows.

Return type

list[eth_defi.lighter.deployment.LighterWhitelistEntry]