Architecture

How OrderVault works, what each Hedera service does in it, what an order costs, and how it can fail. The README covers setup and the live proofs.

ComponentsCopy Anchor Link

An order from placement to fillCopy Anchor Link

StatesCopy Anchor Link

placeOrder ──► Open, funded ──sweep: trigger not met ──► pay share, reschedule by distance
                  │   ├─ trigger met, guard closed ──► FillHeld, back off
                  │   ├─ trigger met, guard open ──► swap (try/catch, gas-capped)
                  │   │        ├─ ok ──► Filled (proceeds + unused budget to holder, NFT wiped)
                  │   │        └─ revert ──► FillFailed, back off
                  │   ├─ budget can't pay a check ──► Open, unfunded: "Budget empty" (pays its part of this sweep)
                  │   │        └─ topUp ──► funded again, checks resume
                  │   └─ past expiry ──► Expired (escrow + budget refunded, NFT wiped)
                  └─ cancel by NFT holder ──► Cancelled (escrow + budget refunded, NFT wiped)

When checks runCopy Anchor Link

Scheduling a contract call through HSS is a fixed network fee: ScheduleCreate with an inner ContractCall is $0.0099 + $0.09, plus Hedera's 20% system-contract surcharge. Measured on testnet in isolation:

So about 89% of a check is the schedule fee, and the only real lever is how many sweeps run. Hedera bills gas used, not the gas limit, so padding the limit changes nothing but the balance the vault must hold up front.

Each sweep therefore waits about as long as the price needs to reach the nearest trigger:

wait = distance_to_nearest_trigger_bps × 1 h ÷ maxMoveBpsPerHour, clamped to [minInterval, maxInterval], ≤ time to expiry

• Triggered orders the guard holds (and failed swaps) back off: 10, 20, 40 min … up to maxInterval.
• Rotation: when more orders are open than one sweep checks (maxOrders), the next sweep runs at minInterval.
• A new order that needs a check sooner than the pending sweep schedules an earlier one under a new epoch. The superseded sweep still fires, sees a stale epoch, and returns at once; the new order pays for that empty run.
• The trade-off: a move faster than maxMoveBpsPerHour is caught late. The fill is still priced from Chainlink at fill time and guarded, and anyone can call executeOrder or sweep at their own cost to check sooner.

What it costsCopy Anchor Link

Every figure comes from the vault's views (checkCost, checkCostShared, fillCost, minBudget, nextCheckDelay), which price gas in USD cents and convert it through 0x168. At the testnet rate (1 HBAR = 7.7 ¢):

What a market costs per day, alone, before and after distance-aware scheduling:

The ticket sizes the budget to cover the order's whole lifetime at today's distance, then shows the cost next to each expiry option. Orders sharing a market split the fixed part, so each pays less.

Nothing comes from the vault's spare HBAR. Each order's reserve pays for its fill and for its part of the chain's final sweep. When the last funded order leaves while a sweep is pending, it pays for that sweep's empty run. An order that brings a sweep forward pays for the superseded one.

Why each Hedera service is load-bearingCopy Anchor Link

• Schedule Service: without it, nothing happens after placement except by a bot. The vault pays for its own schedules out of order budgets; the payer of every scheduled sweep is the vault.
• Token Service: the order is the NFT. Whoever holds it cancels and gets paid, so orders are transferable positions. Settlement wipes it with the vault's wipe key and never reverts the sweep. HTS payouts that fail (unassociated receiver) become claim credits.
• Exchange rate: gas is priced in tinycents and converted at the live rate, so budgets track the HBAR price.
• Mirror node: My orders is the wallet's NFTs plus its OrderPlaced logs. Each order's trail is its event history, linked to HashScan.

Threat modelCopy Anchor Link

Known limitsCopy Anchor Link

• A residual stall is recoverable, not preventable. A scheduled sweep must pay gasLimit × gas price at execution. surplus() withholds a payer float (one sweep of the costliest funded market, ~3 HBAR, endowed at deploy by fund()), so an owner withdrawing surplus can never starve the keeper. What no on-chain reserve can rule out is a gas-price spike past the cost model's safety margin, or the Schedule Service's per-second capacity being full when a sweep tries to rebook: either can stop one market's chain. That is why restartSweep is permissionless — the UI shows "Checks stopped" and anyone can resume it once capacity or balance frees. It is a self-healing edge, not a keeper.
• An NFT sent to the vault settles into a credit nobody can claim. Sending your order to the vault gives it up.
• Testnet pools. The only testnet HBAR/USDC pool trades about 19× above Chainlink, so its guard never opens there (see the README for the numbers and how to re-align a pool).

InvariantsCopy Anchor Link

test/OrderVault.invariant.t.sol drives random placements, cancels, top-ups, NFT transfers, price moves, claims, restarts and the passage of time. HSS is simulated faithfully: every accepted schedule, superseded ones included, runs at its second with its own gas limit. After every call:

1. Escrow per token equals open orders' inputs, and total budgets equal open budgets.
2. The vault holds at least what it owes, in every asset.
3. Credit totals match per-account credits.
4. Open lists, funded counters and NFTs agree with order state.
5. A settled order has no NFT.
6. Liveness: every funded open order is looked at by a scheduled sweep within its market's longest wait, plus rotation, and no scheduled sweep reverts.