Lighter strategy portfolio beta
Lagoon vault running four trading books on Lighter
Source code
The source code of the Lighter strategy portfolio strategy
"""Lagoon vault on Ethereum splitting capital across four Lighter sub-accounts.
The vault's Safe owns one Lighter master account and four sub-accounts. Each
sub-account is a separate trading book run by its own external process, for
example a Nautilus strategy, which signs orders with that sub-account's own API
key. The executor never sees those keys and never places an order: it moves
custody capital, values every account in the Lagoon NAV and funds investor
redemptions.
The executor keeps five exchange-account positions, one per sub-account plus
the master, which acts as the treasury hub. Capital flows Safe -> master ->
sub-account. Sub-accounts return capital directly to the Safe with the key-free
L1 withdrawal, so rebalancing one book into another is a Safe round trip over
several cycles. See :py:func:`decide_lighter_cash_management`.
No Lighter account index appears here. ``lagoon-deploy-vault`` creates one
sub-account per :py:class:`SubAccount`, ``init`` records the indices in the
state and the universe is rebuilt from the state on every start.
See deploy/README-lix.md for deployment and operations.
"""
import datetime
from decimal import Decimal
from tradingstrategy.chain import ChainId
from tradeexecutor.exchange_account.lighter_strategy import (
create_lighter_account_universe,
decide_lighter_cash_management,
)
from tradeexecutor.exchange_account.sub_account import SubAccount
from tradeexecutor.state.trade import TradeExecution
from tradeexecutor.strategy.cycle import CycleDuration
from tradeexecutor.strategy.default_routing_options import TradeRouting
from tradeexecutor.strategy.execution_context import ExecutionContext
from tradeexecutor.strategy.pandas_trader.indicator import IndicatorSet
from tradeexecutor.strategy.pandas_trader.strategy_input import StrategyInput
from tradeexecutor.strategy.pandas_trader.trading_universe_input import CreateTradingUniverseInput
from tradeexecutor.strategy.strategy_module import StrategyParameters
from tradeexecutor.strategy.tag import StrategyTag
from tradeexecutor.strategy.trading_strategy_universe import TradingStrategyUniverse
trading_strategy_engine_version = "0.5"
class Parameters:
"""Custody policy for the Lighter master account and its four sub-accounts."""
chain_id = ChainId.ethereum
initial_cash = 100_000
#: Slow cycle because Safe custody transactions run on Ethereum mainnet.
cycle_duration = CycleDuration.cycle_6h
routing = TradeRouting.default
required_history_period = datetime.timedelta(days=1)
backtest_start = None
backtest_end = None
#: Enables Lighter custody routing in ``start``.
lighter_cash_management = True
#: Fixed USDC equity minimums, consumed by the executor's Lighter cash policy.
#:
#: Ids are permanent: they key the state, the pair tickers and the key
#: hand-over files. Sub-accounts cannot be added after deployment, so the
#: unfunded books exist from the start. A zero minimum receives no automatic
#: funding. Profits stay in each sleeve; only redemptions withdraw capital.
#:
#: These minimums total 9,000 USDC and do not grow with investor deposits.
#: Shortfalls wait for available cash; minimums are never scaled to NAV.
#: Raising a minimum can move real capital at the next cycle, so inspect the
#: planner's movements against Lighter balances before deploying a revision.
lighter_sub_accounts = [
SubAccount(id="vol", name="Volatility", minimum_usd=Decimal(1000)),
SubAccount(id="long-short", name="Long/short", minimum_usd=Decimal(6000)),
SubAccount(id="btc-mean-reversion", name="BTC mean reversion", minimum_usd=Decimal(2000)),
SubAccount(id="momentum-mean-reversion", name="Momentum mean reversion", minimum_usd=Decimal(0)),
]
#: No additional operating buffer; unallocated cash stays in the Safe.
lighter_safe_cash_buffer_usd = Decimal(0)
#: Deposit only funding shortfalls and return surplus master cash to the Safe.
lighter_keep_surplus_in_safe = True
#: The master only passes capital through, so it needs no collateral of its own.
lighter_free_collateral_buffer_usd = Decimal(0)
#: Distance from a book's target tolerated before moving capital.
#:
#: Small losses do not need immediate funding. The band also gates surplus
#: master withdrawals, which can block the executor for about 30 minutes
#: and cost Ethereum gas. Profit above a minimum stays with its trader.
lighter_rebalance_band_usd = Decimal(250)
def create_trading_universe(input: CreateTradingUniverseInput) -> TradingStrategyUniverse:
"""Create one exchange-account pair for the master and each sub-account.
:param input:
Universe construction input. Its state resolves the sub-account ids
to Lighter accounts; deployment has no state yet and uses placeholders.
:return:
Static universe with five Lighter accounts and the USDC reserve.
"""
return create_lighter_account_universe(input, Parameters.lighter_sub_accounts)
def create_indicators(
parameters: StrategyParameters,
indicators: IndicatorSet,
strategy_universe: TradingStrategyUniverse,
execution_context: ExecutionContext,
) -> None:
"""Declare no indicators, because trading decisions are made outside the executor.
:param parameters:
Unused strategy parameters.
:param indicators:
Empty indicator collection retained by the engine interface.
:param strategy_universe:
Static Lighter strategy universe.
:param execution_context:
Current execution context.
"""
def decide_trades(input: StrategyInput) -> list[TradeExecution]:
"""Return this cycle's custody trades.
:param input:
Current strategy state, parameters and treasury-synchronised reserve.
:return:
Trades of at most one movement kind, in priority order: Safe liquidity
for redemptions, needed sleeve funding to the master, sleeve top-ups,
then surplus master cash to the Safe. Profitable books are not trimmed.
"""
return decide_lighter_cash_management(input)
tags = {StrategyTag.beta, StrategyTag.live, StrategyTag.exchange_account_strategy, StrategyTag.archived}
name = "Lighter strategy portfolio"
short_description = "Lagoon vault running four trading books on Lighter"
icon = ""
long_description = """
Lighter strategy portfolio is an Ethereum Lagoon vault that divides its capital
between trading books on Lighter. Each book is a separate Lighter sub-account,
run by its own automated trading process.
## Minimum equity by book
- Volatility: 1,000 USDC
- Long/short: 6,000 USDC
- BTC mean reversion: 2,000 USDC
- Momentum mean reversion: 0 USDC
The books have fixed equity minimums totalling 9,000 USDC and are funded as
capital becomes available, largest shortfall first. Cash beyond their funding
needs stays as USDC in the Safe. Increasing a minimum requires a manual edit;
shortfalls are topped up automatically outside the 250-USDC tolerance.
Profit above each minimum stays in its sleeve. Small amounts may remain on
the master within this tolerance to avoid repeated withdrawals.
## How it works
Investor deposits and redemptions go through the Lagoon vault, and its Safe
owns the Lighter accounts.
The vault's executor moves capital between the Safe and the Lighter accounts,
funds shortfalls below each book's minimum and values all accounts in the vault's
share price. Funding a sleeve from the Safe goes through the master account
and can take several 6-hour cycles. Minimum mode does not rebalance profits
between books.
## Liquidity
Redemptions use Safe cash first. Additional liquidity requires a Lighter
withdrawal, which takes about 30 minutes per account and uses free collateral.
Margin in use by open positions has to be released before it can be withdrawn.
"""