Extending the vault
OrderVault compiles to 21,254 of the 24,576-byte contract limit, so there are 3,322 bytes of headroom
(forge build --sizes). It got there by keeping only the core flow in the vault — place, sweep, evaluate, guard,
fill, settle — and moving everything else out:
| Where | What | Why it is out of the vault |
|---|---|---|
LimitOrderType, StopOrderType, TrailingStopType | When an order fires and how far it is from firing | Order types are plug-ins: separate view-only contracts the vault staticcalls, registered with registerOrderType. A new type needs no vault change and no redeploy (design: docs/PLUGINS-DESIGN.md; how-to: docs/ORDER-TYPES.md). |
OrderVaultLens | The cost and status previews the frontend reads (minBudget, checkCost, fillCost, nextCheckDelay, sweepStatus, previewCharges, surplus, …) | Nothing on-chain needs them. The lens computes them from the vault's raw state. |
SweepMath (internal library) | Every number the vault charges or schedules by | Compiled into both the vault and the lens, so a preview and the real charge come from the same code and cannot drift. |
Settlement (external library) | The SaucerSwap swap, HTS token and order-NFT operations, ERC-20 moves | Call-encoding-heavy code, linked rather than inlined. |
MarketRegistry (external library) | Listing and tuning markets, and their bounds | Owner-only and run once per market, so no sweep pays for the call. |
MarketGuard, OrderCollection (external libraries) | The Chainlink + TWAP read, the one-time NFT collection | As in v1.0. |
Before adding code to the vault, decide where it belongs:
- A new kind of order is a new order type, not a vault change.
- A new read for the UI goes in
OrderVaultLens, and any arithmetic it shares with the vault goes inSweepMath. - Cold code (owner-only, once per market, rarely run) can move to an external library like
MarketRegistry. Keep hot code (anything every sweep runs) in the vault: an external library call costs a colddelegatecalleach time. The capacity probe was measured at ~3,300 gas per rescheduling sweep when it lived inSettlement, which is why it is inline again. The next cold candidates, measured by stubbing them out, arerestartSweep(~160 bytes) andwithdrawSurplus(~350 bytes). - Keep using custom errors and events (the vault has no revert strings) and keep storage structs packed
(
Order,SweepState).
test/GasMeasure.t.sol is the before/after gas report: it runs the same sweeps on the v1.0.1 vault and this one,
each sweep in its own transaction (forge test --match-contract GasMeasure --isolate -vv). Run it after a change
to the sweep path and fold the difference into MarketConfig.costs().
Once there is room, the usual changes:
- Add a market: add a function to
script/MarketConfig.sollikeusdcDai()(both tokens need Chainlink feeds), calllistMarketfromDeploy.s.sol, and redeploy. The frontend lists every market the vault has. - Tune how often checks run:
SweepParams(minInterval,maxInterval,maxMoveBpsPerHour). LowermaxMoveBpsPerHourcosts less and reacts later. Change a live market withupdateMarket. - Tune the guard:
GuardParams.MarketGuard.paramsValidkeeps it meaningful: TWAP 5 min to 1 day, oracle age 60 s to 26 h, deviation and slippage at most 10%. - Recalibrate costs: measure a few scheduled sweeps on the mirror node (
gas_usedin/api/v1/contracts/{id}/results/{timestamp}) and callsetCosts. The frontend reads costs through the lens, so nothing else changes. - Mainnet: add mainnet addresses to
MarketConfig.sol, allow chain 295 inDeploy.s.sol(it deploys to testnet only), add the network toscaffold.config.ts, and tightenmaxOracleAgeto the mainnet feeds' heartbeat.
From README.md at v1.1 (cee2d4e) · View source