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:

WhereWhatWhy it is out of the vault
LimitOrderType, StopOrderType, TrailingStopTypeWhen an order fires and how far it is from firingOrder 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).
OrderVaultLensThe 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 byCompiled 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 movesCall-encoding-heavy code, linked rather than inlined.
MarketRegistry (external library)Listing and tuning markets, and their boundsOwner-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 collectionAs 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 in SweepMath.
  • 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 cold delegatecall each time. The capacity probe was measured at ~3,300 gas per rescheduling sweep when it lived in Settlement, which is why it is inline again. The next cold candidates, measured by stubbing them out, are restartSweep (~160 bytes) and withdrawSurplus (~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.sol like usdcDai() (both tokens need Chainlink feeds), call listMarket from Deploy.s.sol, and redeploy. The frontend lists every market the vault has.
  • Tune how often checks run: SweepParams (minInterval, maxInterval, maxMoveBpsPerHour). Lower maxMoveBpsPerHour costs less and reacts later. Change a live market with updateMarket.
  • Tune the guard: GuardParams. MarketGuard.paramsValid keeps 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_used in /api/v1/contracts/{id}/results/{timestamp}) and call setCosts. The frontend reads costs through the lens, so nothing else changes.
  • Mainnet: add mainnet addresses to MarketConfig.sol, allow chain 295 in Deploy.s.sol (it deploys to testnet only), add the network to scaffold.config.ts, and tighten maxOracleAge to the mainnet feeds' heartbeat.

From README.md at v1.1 (cee2d4e) · View source