Why keepers are required
Smart contracts store the strategy and control where funds can move. Keepers handle the work that needs live market data: swapping tax income, sending margin to Lighter, managing orders, bringing funds back, and running buybacks or dividends.
A keeper can call only the actions allowed by the contracts. The destination wallets are fixed, while the keeper chooses the amounts, timing, swap limits, and how returned funds are marked.
Keeper gateway
The Vault Keeper Gateway is the normal onchain entry point for operating actions. It separates the global protocol keeper from individual submitter addresses.
The gateway:
- maintains an allowlist of active submitters;
- includes a pause switch for incident response;
- resolves the correct vault and custody for a token;
- forwards only known action types;
- emits a normalized record of each forwarded action.
Service architecture
Keeper operations are separated across services so one process does not require every credential:
- Scheduler
- Selects tokens and workflow stages that are ready for another attempt.
- Worker
- Reads Lighter, calculates strategy actions, and holds Lighter credentials without the EVM submitter key.
- EVM submitter
- Signs approved onchain actions without holding Lighter credential master keys.
- Publisher
- Publishes sanitized account snapshots for the website without receiving execution secrets.
- Postgres
- Stores workflow state, action outcomes, snapshots, retry state, and reconciliation records.
Credentials, authorization headers, encrypted key envelopes, and raw error payloads that may contain secrets are not part of the public read model.
Operational lifecycle
1. Synchronize revenue
The vault identifies revenue-asset balances received since its last synchronization. Recognition updates vault accounting without immediately swapping or releasing funds.
2. Normalize revenue
The keeper selects an approved route from the launch revenue asset to USDG and calls flushRevenue with a minimum output and deadline. The vault sends the route through the configured normalizer, verifies the exact USDG received, and deposits it into the revenue router.
3. Release margin
The keeper chooses an amount of available strategy capital that satisfies protocol and Lighter deposit bounds. The router moves that amount to the token’s registered custody account and records it as outstanding principal.
4. Deposit to Lighter
Custody approves the configured Lighter proxy for the exact USDG amount, deposits into its own account, and removes the approval. The deposit must satisfy both Perpetuals bounds and live Lighter asset limits.
5. Execute portfolio
The offchain keeper reads the active strategy profile and Lighter account state, calculates target positions, and places or cancels orders. Execution accounts for market precision, minimum order size, leverage caps, and available equity.
6. Withdraw from Lighter
When funds should return onchain, the keeper requests a secure USDG withdrawal from the custody-owned account. After Lighter exposes a pending balance, the keeper claims it back to the custody contract.
7. Settle the router
Custody sends USDG to the router with a keeper-selected principal-return portion. The router restores declared principal and recoverable loss, then classifies the remainder as strategy profit.
8. Execute token outcomes
Separate actions spend settled profit from its buyback or dividend bucket. Buybacks purchase and burn the launched token. Dividends convert into the configured dividend asset and deposit it into the token’s Flap dividend contract.
Route execution
Revenue normalization, buybacks, and dividends may require an asset conversion. The production graph uses reviewed Uniswap V2 routes pinned to the configured router, factory, WETH, and expected runtime code.
Route policy includes:
- registered router and factory addresses;
- validated input and output assets;
- deadline enforcement;
- nonzero minimum-output requirements;
- exact approval and post-call balance checks;
- output returned to the authenticated calling component.
A nonzero minimum output does not guarantee economically safe slippage. The keeper is responsible for selecting a minimum that reflects current liquidity and policy.
Action IDs and idempotency
Margin, custody, settlement, buyback, dividend, and credential actions use scoped action IDs. Contracts combine the ID with an action domain and payload hash.
The first valid call records the hash. Repeating the same ID with the same payload returns without executing the state change again. Repeating the ID with different parameters reverts as an action conflict.
This design supports safe transaction retries after RPC timeouts or uncertain submission results without allowing the caller to reuse an approved identifier for another amount or target.
Revenue flushing is the exception: it has no action ID. Instead, the vault’s recognized-balance accounting, exact output checks, and router deposit checks constrain repeated execution.
Lighter key ceremony
Lighter execution requires an API public key associated with the custody-owned account. Key initialization and recovery are forwarded through a gateway that verifies its configuration, router, token, and custody binding.
Key setup and recovery use a separate path from normal strategy actions. The Lighter credential and EVM transaction key are also kept separate.
Portfolio reconciliation
The keeper compares the requested portfolio with current Lighter positions rather than assuming an instruction has already been executed.
A reconciliation cycle can evaluate:
- active profile version and portfolio hash;
- account value and available balance;
- current position direction and size;
- target notional derived from equity allocation and leverage;
- market size and price precision;
- minimum order size;
- open orders and required cancellations;
- risk and pause policy.
Onchain profile validation does not enforce the resulting order. Monitoring must compare actual Lighter state with the instruction and alert on divergence.