lighter.constants

Documentation for eth_defi.lighter.constants Python module.

Constants for the Lighter integration.

Shared constants used across the Lighter modules (daily_metrics, vault_data_export, etc.).

Module Attributes

`LIGHTER_CHAIN_ID`	Synthetic in-house chain ID for Lighter (ZK-rollup, non-standard EVM).
`LIGHTER_LEGACY_ROBINHOOD_CHAIN_ID`	Legacy synthetic chain ID used by the first implementation of Lighter on Robinhood support.
`LIGHTER_ETHEREUM_DEPLOYMENT_CHAIN_ID`	Ethereum mainnet chain ID associated with the original Lighter deployment.
`LIGHTER_ROBINHOOD_DEPLOYMENT_CHAIN_ID`	Robinhood Chain ID associated with the Robinhood Lighter deployment.
`LIGHTER_ROBINHOOD_LLP_ACCOUNT_INDEX`	LLP account index exposed by the Robinhood Lighter public-pools API.
`LIGHTER_L1_CONTRACT`	Lighter L1 contract (`ZkLighter` proxy), Ethereum mainnet (chain id 1).
`LIGHTER_USDC_ETHEREUM`	USDC on Ethereum mainnet — the Lighter deposit asset.
`LIGHTER_API_URL`	Lighter mainnet API base URL.
`LIGHTER_ROBINHOOD_API_URL`	Lighter API for the deployment settling on Robinhood Chain.
`LIGHTER_DEFAULT_REQUESTS_PER_SECOND`	Default rate limit for Lighter API requests per second.
`LIGHTER_DENOMINATION`	Pool denomination currency.
`LIGHTER_POOL_LOCKUP`	Pool cooldown period for withdrawals.
`LIGHTER_ETHEREUM`	Ethereum-settled Lighter deployment.
`LIGHTER_ROBINHOOD`	Robinhood Chain-settled Lighter deployment.
`LIGHTER_DEPLOYMENTS`	Production Lighter deployments scanned by the all-chain vault pipeline.
`LIGHTER_DEPLOYMENTS_BY_SLUG`	Deployment lookup for DuckDB export and migration code.
`LIGHTER_SYSTEM_POOL_ADDRESSES`	Set of Lighter system pool addresses (protocol-curated).

Functions

identify_lighter_pool_deployment(address)

Resolve a synthetic Lighter pool address to its deployment.

Classes

LighterAPIConfig

Configuration for one independently indexed Lighter deployment.

LIGHTER_CHAIN_ID: int = 9998

Synthetic in-house chain ID for Lighter (ZK-rollup, non-standard EVM).

Added to eth_defi.chain.CHAIN_NAMES as 9998: "Lighter".

Warning

This is a synthetic id used by the off-chain pool-metrics pipeline — it is not an EVM chain. The original deployment’s onchain Lighter deposit/withdraw contract lives on Ethereum mainnet (chain id 1); see LIGHTER_L1_CONTRACT below. The Robinhood metrics deployment is associated with Robinhood Chain (chain id 4663).

LIGHTER_LEGACY_ROBINHOOD_CHAIN_ID: int = 9996

Legacy synthetic chain ID used by the first implementation of Lighter on Robinhood support.

Both deployments now intentionally use LIGHTER_CHAIN_ID because they belong to one native Lighter dataset namespace. Keep this old value only so Parquet and VaultDatabase migrations can remove rows written by the short-lived split-chain implementation.

LIGHTER_ETHEREUM_DEPLOYMENT_CHAIN_ID: int = 1

Ethereum mainnet chain ID associated with the original Lighter deployment.

This is deliberately separate from LIGHTER_CHAIN_ID. The latter is the synthetic vault-dataset ID used to partition native Lighter prices, whereas this value identifies the EVM chain associated with the deployment. This distinction became necessary when adding Lighter on Robinhood Chain.

LIGHTER_ROBINHOOD_DEPLOYMENT_CHAIN_ID: int = 4663

Robinhood Chain ID associated with the Robinhood Lighter deployment.

For now this field exists specifically so lifetime-metrics consumers can distinguish Lighter on Robinhood Chain from Lighter on Ethereum without replacing the synthetic IDs used by the vault price pipeline.

LIGHTER_ROBINHOOD_LLP_ACCOUNT_INDEX: int = 281474976710654

LLP account index exposed by the Robinhood Lighter public-pools API.

For now this override exists specifically for Lighter on Robinhood. Its systemConfig.liquidity_pool_index currently points at the next, uninitialised account instead of the live USDG LLP account. Account type 3 cannot be used as a generic fallback because Ethereum currently exposes both LLP and XLP with that account type. Keeping the workaround in deployment configuration prevents XLP from being misclassified as the canonical LLP.

LIGHTER_L1_CONTRACT: eth_typing.evm.HexAddress = '0x3B4D794a66304F130a4Db8F2551B0070dfCf5ca7'

Lighter L1 contract (ZkLighter proxy), Ethereum mainnet (chain id 1).

Holds all user deposits and the canonical zk-rollup state root. This is the contract whitelisted by the GuardV0 / TradingStrategyModuleV0 Lighter integration for deposits/withdrawals from an asset-managed Safe.

NOTE: distinct from LIGHTER_CHAIN_ID (9998), which is the synthetic chain id used by the off-chain metrics pipeline.

See https://etherscan.io/address/0x3b4d794a66304f130a4db8f2551b0070dfcf5ca7

Stored checksummed so it can be passed directly to web3.py calls.

LIGHTER_USDC_ETHEREUM: eth_typing.evm.HexAddress = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48': USDC on Ethereum mainnet — the Lighter deposit asset.

LIGHTER_API_URL: str = 'https://mainnet.zklighter.elliot.ai': Lighter mainnet API base URL.

LIGHTER_ROBINHOOD_API_URL: str = 'https://api.rh.lighter.xyz': Lighter API for the deployment settling on Robinhood Chain.

LIGHTER_DAILY_METRICS_DATABASE: pathlib.Path = PosixPath('/home/runner/.tradingstrategy/vaults/lighter-pools.duckdb'): Default path for Lighter daily metrics DuckDB database.

LIGHTER_DEFAULT_REQUESTS_PER_SECOND: float = 2.0

Default rate limit for Lighter API requests per second.

Conservative estimate based on observed API behaviour.

LIGHTER_POOL_FEE_MODE: eth_defi.vault.fee.VaultFeeMode = VaultFeeMode.internalised_skimming

Fee mode for Lighter native pools.

Pool operators can set an operator_fee (0-100%). The share prices from the API already reflect the operator’s fee deduction, so the pipeline sees net-of-fees prices. This matches internalised skimming.

LIGHTER_DENOMINATION: str = 'USDC'

Pool denomination currency.

The original Ethereum Lighter deployment uses USDC as its collateral currency. Robinhood deployment configuration overrides this with USDG.

LIGHTER_POOL_LOCKUP: datetime.timedelta = datetime.timedelta(seconds=300)

Pool cooldown period for withdrawals.

Ethereum value from systemConfig.liquidity_pool_cooldown_period (300000ms = 5 minutes). Robinhood deployment configuration overrides it.

class LighterAPIConfig

Bases: object

Configuration for one independently indexed Lighter deployment.

Lighter account indexes are only unique within a deployment. In particular, account 281474976710654 exists on both Ethereum Lighter and Robinhood Lighter, so downstream storage must always pair an account index with slug.

slug: str: Stable storage identifier for the deployment.

name: str: Human-readable scanner and scheduling name.

chain_id: int

Synthetic vault-dataset chain ID.

This remains the primary identity used for price partitions and VaultSpec records.

deployment_chain_id: int

Real EVM chain associated with this deployment.

Do not use this value as the Lighter vault’s primary chain_id. The synthetic chain_id is still required to keep native Lighter price rows separate from ordinary ERC-4626 vaults. Both Lighter deployments share that synthetic ID and use deployment-specific address prefixes for uniqueness. For now this second chain ID supports Lighter on Robinhood in downstream lifetime-metrics exports.

api_url: str: REST API base URL.

app_url: str: Web application base URL used for vault links.

address_prefix: str

Synthetic vault address prefix.

Deployment-specific prefixes prevent address-only metadata rules from leaking between deployments.

denomination: str: Pool collateral symbol.

lockup: datetime.timedelta: Public-pool withdrawal cooldown reported by systemConfig.

llp_account_index_override: Optional[int]

Canonical LLP account override for deployments with unreliable system configuration.

None trusts systemConfig. For now only Lighter on Robinhood uses an override because its live system configuration points at an uninitialised account.

format_pool_address(account_index)

Create a globally unique synthetic pool address.

Parameters: account_index (int) – Deployment-local Lighter account index.
Returns: Synthetic address accepted by eth_defi.vault.base.VaultSpec.
Return type: str

format_pool_link(account_index)

Create the deployment-specific public-pool application link.

Parameters: account_index (int) – Deployment-local Lighter account index.
Returns: Public-pool detail URL.
Return type: str

matches_pool_address(address)

Check whether a synthetic pool address belongs to this deployment.

A numeric suffix is required because the backwards-compatible Ethereum prefix lighter-pool is also the beginning of the Robinhood prefix lighter-pool-robinhood. This exact check lets partial price merges distinguish the two deployments without relying on prefix ordering.

Parameters: address (str) – Synthetic Lighter vault address.
Returns: True when the address has this deployment’s prefix and a numeric Lighter account index.
Return type: bool

property pool_address_pattern: str

Return the PyArrow regex for this deployment’s pool addresses.

Returns: Anchored regular expression matching synthetic pool addresses.

__init__(slug, name, chain_id, deployment_chain_id, api_url, app_url, address_prefix, denomination, lockup, llp_account_index_override=None)

Parameters

slug (str) –
name (str) –
chain_id (int) –
deployment_chain_id (int) –
api_url (str) –
app_url (str) –
address_prefix (str) –
denomination (str) –
lockup (datetime.timedelta) –
llp_account_index_override (Optional[int]) –

Return type

None

LIGHTER_ETHEREUM: eth_defi.lighter.constants.LighterAPIConfig = LighterAPIConfig(slug='ethereum', name='Lighter Ethereum', chain_id=9998, deployment_chain_id=1, api_url='https://mainnet.zklighter.elliot.ai', app_url='https://app.lighter.xyz', address_prefix='lighter-pool', denomination='USDC', lockup=datetime.timedelta(seconds=300), llp_account_index_override=None): Ethereum-settled Lighter deployment. The legacy address format and synthetic chain ID are intentionally retained for dataset compatibility.

LIGHTER_ROBINHOOD: eth_defi.lighter.constants.LighterAPIConfig = LighterAPIConfig(slug='robinhood', name='Lighter Robinhood', chain_id=9998, deployment_chain_id=4663, api_url='https://api.rh.lighter.xyz', app_url='https://robinhoodchain.lighter.xyz', address_prefix='lighter-pool-robinhood', denomination='USDG', lockup=datetime.timedelta(0), llp_account_index_override=281474976710654): Robinhood Chain-settled Lighter deployment. Its live API reports USDG as collateral and a zero public-pool cooldown.

LIGHTER_DEPLOYMENTS: tuple[eth_defi.lighter.constants.LighterAPIConfig, ...] = (LighterAPIConfig(slug='ethereum', name='Lighter Ethereum', chain_id=9998, deployment_chain_id=1, api_url='https://mainnet.zklighter.elliot.ai', app_url='https://app.lighter.xyz', address_prefix='lighter-pool', denomination='USDC', lockup=datetime.timedelta(seconds=300), llp_account_index_override=None), LighterAPIConfig(slug='robinhood', name='Lighter Robinhood', chain_id=9998, deployment_chain_id=4663, api_url='https://api.rh.lighter.xyz', app_url='https://robinhoodchain.lighter.xyz', address_prefix='lighter-pool-robinhood', denomination='USDG', lockup=datetime.timedelta(0), llp_account_index_override=281474976710654)): Production Lighter deployments scanned by the all-chain vault pipeline.

LIGHTER_DEPLOYMENTS_BY_SLUG: dict[str, eth_defi.lighter.constants.LighterAPIConfig] = {'ethereum': LighterAPIConfig(slug='ethereum', name='Lighter Ethereum', chain_id=9998, deployment_chain_id=1, api_url='https://mainnet.zklighter.elliot.ai', app_url='https://app.lighter.xyz', address_prefix='lighter-pool', denomination='USDC', lockup=datetime.timedelta(seconds=300), llp_account_index_override=None), 'robinhood': LighterAPIConfig(slug='robinhood', name='Lighter Robinhood', chain_id=9998, deployment_chain_id=4663, api_url='https://api.rh.lighter.xyz', app_url='https://robinhoodchain.lighter.xyz', address_prefix='lighter-pool-robinhood', denomination='USDG', lockup=datetime.timedelta(0), llp_account_index_override=281474976710654)}: Deployment lookup for DuckDB export and migration code.

identify_lighter_pool_deployment(address)

Resolve a synthetic Lighter pool address to its deployment.

This helper is used by partial Parquet replacement so an independently completed Ethereum or Robinhood scan cannot remove the other deployment’s retained history. LighterAPIConfig.matches_pool_address() validates the numeric account-index suffix, preventing the shorter Ethereum prefix from matching Robinhood addresses.

Parameters: address (str) – Synthetic Lighter vault address.
Returns: Matching deployment, or None when the address is not recognised.
Return type: Optional[eth_defi.lighter.constants.LighterAPIConfig]

LIGHTER_SYSTEM_POOL_ADDRESSES: set[str] = {'lighter-pool-281474976680784', 'lighter-pool-281474976710654', 'lighter-pool-robinhood-281474976710654'}

Set of Lighter system pool addresses (protocol-curated).

The LLP (Lighter Liquidity Pool) is the protocol’s own liquidity pool; the XLP (Experimental Liquidity Provider) is the protocol-run pool for experimental markets. Both are community-owned and protocol-operated. Uses each deployment’s synthetic pool-address format.

These are protocol-operated pools with special properties (no operator fee). Ethereum system pools are fetched separately via systemConfig when they are absent from publicPoolsMetadata; the Robinhood LLP is currently present in that listing. Useful for filtering protocol pools from user-created pools.