The AQUA machine, end to end
This page describes the current repo, not an imagined future version. The desk can be audited in code, replayed in dryfire, and checked against one public Hyperliquid account.
01Overview
AQUA is a public HYPE desk funded by AQUA creator fees. One model reads the market and proposes a posture. The rails decide what can actually happen. The covenant is simple: win or lose, the machine still routes toward burn.
02The Cycle
Every cycle gets a stable ID in the form YYYY-MM-DD#cycle-N. Each stage writes its own result into the checkpoint file and its own append-only ledger entry with a monotonically increasing folio number. If the process stops, rerunning the same cycle resumes completed stages instead of replaying them.
Read the creator vault, enforce the minimum claim threshold, and abort if fee sharing is not locked.
Split claimed SOL by policy, reserve the burn share, and prepare the AQUA buyback route inside the configured slippage and per-cycle burn caps.
Generate and guardian-verify the Unit deposit address at runtime, then bridge the desk share when armed. Amounts below the Unit minimum accumulate for later cycles.
Build the packet, hash it, ask the desk officer for a posture, then clamp or reject that proposal with hard code rails.
Translate the final railed decision into spot or perp actions, or hold/skip when there is no new executable delta.
Snapshot account value, margin usage, and the live HYPE position after the Hyperliquid step.
Burn the bought-back AQUA with the mint-derived token program. Realized desk profits stay on Hyperliquid at launch; the always-on burn starts from the fee-share leg.
Write the current epoch window so the cycle report captures the calendar context alongside the trading state.
| # | stage key | action id | what it does |
|---|---|---|---|
| 01 | claim | claim_creator_fees | Read the creator vault, enforce the minimum claim threshold, and abort if fee sharing is not locked. |
| 02 | swap | swap_sol_to_hype | Split claimed SOL by policy, reserve the burn share, and prepare the AQUA buyback route inside the configured slippage and per-cycle burn caps. |
| 03 | unit | unit_deposit_stub | Generate and guardian-verify the Unit deposit address at runtime, then bridge the desk share when armed. Amounts below the Unit minimum accumulate for later cycles. |
| 04 | desk | desk_decision | Build the packet, hash it, ask the desk officer for a posture, then clamp or reject that proposal with hard code rails. |
| 05 | hyperliquid | hl_position_management | Translate the final railed decision into spot or perp actions, or hold/skip when there is no new executable delta. |
| 06 | pnl | pnl_check | Snapshot account value, margin usage, and the live HYPE position after the Hyperliquid step. |
| 07 | burn | buyback_burn | Burn the bought-back AQUA with the mint-derived token program. Realized desk profits stay on Hyperliquid at launch; the always-on burn starts from the fee-share leg. |
| 08 | epoch | epoch_snapshot | Write the current epoch window so the cycle report captures the calendar context alongside the trading state. |
Stores per-stage RUNNING or COMPLETED status, cached stage results, the matching ledger entry, wokenBy, and reconciliation state.
Stores the finished report with mode, stage results, ledger entries, and the final reconciliation result.
03The Desk Officer
The desk officer receives a structured packet, not an open-ended prompt. It is asked for JSON only and returns a proposal the rails treat as untrusted input.
mid, mark, oracle, prev day, open interest, premium, funding rate, venue max leverage, 24h candles, 7d candles, funding windows, L2 depth
account value, withdrawable balance, total margin used, total notional, perp exposure, spot HYPE balance, spot USDC balance
current tier, desired margin, long/short leverage caps, long/short notional caps, spot preference, realization band, cappedBy list, drawdown state
high-water mark equity
requested lamports, capped lamports, max SOL per cycle
{
"direction": "long" | "short" | "flat", // "short" gated off at launch
"sizeFraction": number,
"execution": "now" | "twap" | "skip",
"carryMode": "perp" | "spot",
"takeProfitPct": number | null,
"rationale": string
}The engine publishes the packet hash, rationale text, officer status, and rails verdict before it reaches the Hyperliquid execution stage. The desk journal is not hand-written copy; it is derived from ledger entries whose action is desk_decision.
Fallback is explicit. Disabled, unsupported-provider, missing-model, missing-key, timeout, provider-error, malformed-output, and rails-rejected paths all resolve to deterministic fallback logic. If even that path cannot be made safe, the engine forces a final flat decision.
04The Rails
These are code bounds, not vibes. The model does not decide them and cannot opt out of them.
5x / 7x / 10x / 10x by fee-funded desk equity tier, then clamped by the live venue max if lower.
Shorts are disabled by published config at launch — a bearish read collapses to defensive FLAT. When the gate opens, short caps run one turn tighter than the matching long cap, floor 1x.
Margin budget is the minimum of live equity, `maxPositionUsd`, 35% of equity, and equity minus the $100 residual floor, then multiplied by the active tier and drawdown scale.
Spot is preferred only when funding is above `0.0005`; otherwise the same long thesis routes to perps.
A live position is marked ready to realize once return on equity reaches `20%`.
No same-cycle flip from long to short, and no same-cycle carry switch between spot and perps. The desk must flatten first and re-enter on a later cycle.
Never allowed. Spot short proposals are rejected outright.
Every accepted perp decision leaves the rails with `marginMode: "isolated"`.
A root `HALT` file aborts the cycle before stage work, and `execute:false` keeps the engine in dry-run mode even when the decision path is live.
If the officer is disabled, missing a model, missing an API key, times out, errors, returns malformed JSON, or still fails after rails, the engine falls back and can force a final flat decision.
| bound | value | where enforced |
|---|---|---|
| Long leverage cap | 5x / 7x / 10x / 10x by fee-funded desk equity tier, then clamped by the live venue max if lower. | `packages/engine/src/policy.ts` |
| Short gate | Shorts are disabled by published config at launch — a bearish read collapses to defensive FLAT. When the gate opens, short caps run one turn tighter than the matching long cap, floor 1x. | `packages/engine/src/desk/rails.ts` |
| Position budget | Margin budget is the minimum of live equity, `maxPositionUsd`, 35% of equity, and equity minus the $100 residual floor, then multiplied by the active tier and drawdown scale. | `packages/engine/src/policy.ts` |
| Spot carry rule | Spot is preferred only when funding is above `0.0005`; otherwise the same long thesis routes to perps. | `packages/engine/src/policy.ts`, `packages/engine/src/desk/fallback.ts` |
| Realization band | A live position is marked ready to realize once return on equity reaches `20%`. | `packages/engine/src/policy.ts`, `packages/engine/src/desk/fallback.ts` |
| One-position rule | No same-cycle flip from long to short, and no same-cycle carry switch between spot and perps. The desk must flatten first and re-enter on a later cycle. | `packages/engine/src/desk/rails.ts` |
| Shorts on spot | Never allowed. Spot short proposals are rejected outright. | `packages/engine/src/desk/rails.ts` |
| Isolated margin only | Every accepted perp decision leaves the rails with `marginMode: "isolated"`. | `packages/engine/src/desk/rails.ts` |
| HALT and no-new-risk gates | A root `HALT` file aborts the cycle before stage work, and `execute:false` keeps the engine in dry-run mode even when the decision path is live. | `packages/engine/src/cycle.ts`, `packages/engine/src/desk/runtime.ts` |
| Fallback and hard flat | If the officer is disabled, missing a model, missing an API key, times out, errors, returns malformed JSON, or still fails after rails, the engine falls back and can force a final flat decision. | `packages/engine/src/desk/officer.ts`, `packages/engine/src/desk/fallback.ts`, `packages/engine/src/desk/runtime.ts` |
05Risk Ladder
The ladder keys off live desk equity, which in practice means fee-funded account value. Higher tiers allow larger long caps and larger position multipliers; short caps (shown for when the gate opens) stay one turn tighter.
| tier | desk equity | long cap | short cap | position multiplier |
|---|---|---|---|---|
| IGNITION | $0+ | 5x | 4x | 1.5x |
| $500 | $500+ | 7x | 6x | 2.0x |
| $2K | $2K+ | 10x | 9x | 2.5x |
| $10K | $10K+ | 10x | 9x | 3.0x |
If the HYPE market reports a lower max leverage than the configured tier, the live venue limit overrides the tier cap.
If equity drops below 80% of the high-water mark, the engine halves the effective position multiplier until the desk recovers.
Once a live position reaches the realization band, fallback logic closes it instead of asking for more risk.
06Clock In
CLOCK IN is permissionless. The engine marks the machine due when accrued fees clear the threshold, the next fee batch has not already fired, cooldown is zero, and at least one caller is queued.
That is 0.0001 SOL. The status surface publishes both accrued lamports and threshold lamports.
After a fire, the machine will not accept another due wake until the cooldown expires.
The winning caller address is recorded into crank state and then written into the cycle ledger for that fire.
To wake it on the public site, open the console, paste a Solana wallet into the CLOCK IN panel, and queue the request once the meter is due. Under the hood that request appends to state/crank-requests.jsonl.
07Verification
AQUA exposes one machine account and an append-only ledger trail. The intended audit loop is repo, console, explorer, and local dryfire.
{
"ts": "ISO timestamp",
"folio": 1,
"cycleId": "2026-08-06#cycle-1",
"action": "desk_decision",
"mode": "DRY_RUN" | "EXECUTE",
"status": "DESK_DECISION_ACCEPTED",
"details": { "...": "stage-specific payload" },
"wokenBy": "optional public caller"
}Append-only cycle entries, each with folio, action, mode, status, details, and optional wake attribution.
Derived view of the latest desk decisions: direction, size fraction, carry mode, execution mode, rationale, officer status, rails verdict, and packet hash.
Public status surface for threshold, due state, cooldown, fee batch, queue depth, last wake, and wake history.
Rewrites the canonical ledger from stored cycle reports and compares reported burn signatures against on-chain burn events when the mint is configured.
- Read the latest decision in the desk journal and note the packet hash, rationale, and rails verdict.
- Open the machine account on the Hyperliquid explorer and compare fills or transfers against the cycle timeline.
- Run the dryfire or `reconcile-ledger` locally if you want the repo to regenerate the same public surfaces from source.
08Risk & honesty
The AI can be wrong long, wrong short, or wrong flat. Nothing in this repo says otherwise.
Red cycles still burn. The machine does not get to hide losses because the narrative prefers green candles.
Leverage cuts both ways. The rails reduce blast radius; they do not remove liquidation risk, basis risk, or venue risk.
Bridge and infrastructure risk are real. Solana RPC, Jupiter, Unit, and Hyperliquid can all fail independently.
No promises are made here. What is published are the constants, the rails, the journal, and the verification path.
09FAQ
Creator fees split mechanically on claim: one share bridges to the desk through Unit, and one share buys back and burns AQUA on the same cycle subject to the published reserve and burn caps.
The machine falls back. Disabled, unsupported, missing-model, missing-key, timeout, provider-error, malformed-json, and rails-rejected paths all resolve to deterministic fallback logic instead of improvising.
The code can always be changed in a future release, which is exactly why the repo is public. The claim being made here is narrower: the running engine enforces rails in code before it can place risk.
The launch engine hard-splits creator fees so a burn share routes into buyback and burn every cycle. Profit-withdrawal routing from realized desk gains is a later addition, not the thing making red cycles burn.
It queues a public wake request. When accrued fees clear the threshold and cooldown is zero, the queued caller can fire the next cycle and be written into the ledger as `wokenBy`.
No. The rails enforce one live HYPE posture at a time. Flip attempts are flattened first and any re-entry waits for the next cycle.
Treat that as a bug or a trust break. The intended audit path is public code, public machine account, append-only ledger, and reproducible dryfire. If those diverge, the divergence is the story.
No. The AI can be wrong long, wrong short, or wrong flat. The repo publishes the constants and the risk controls, not a promise of outcome.