release 1 (7ab2355a0c)

.env.example

@@ -2,10 +2,14 @@
 # Keep values bare: Docker Compose keeps a trailing "# comment" as part of an empty value, so comments live on their own lines.
 
 # --- keys (never logged) ---
-# Helius: https://dashboard.helius.dev (RPC for balances and transactions)
+# Helius: https://dashboard.helius.dev (RPC for balances and transactions; also the signer's, unless SIGNER_RPC_URL is set)
 HELIUS_API_KEY=
-# Jupiter: https://portal.jup.ag (swaps and token stats)
+# Jupiter: https://portal.jup.ag (swaps, through Jupiter's own Metis routes only, and token stats)
 JUPITER_API_KEY=
+# The bot key: `docker compose exec fly fly-trader wallet new` appends BOT_PRIVATE_KEY=... to this file. Do not add an
+# empty BOT_PRIVATE_KEY= line yourself: wallet new refuses when the name is already here.
+# Optional: a second Solana RPC from another provider for the signer, which simulates every swap before signing it.
+# SIGNER_RPC_URL=
 
 # --- database (docker-compose.yml sets the container's URL; this one is for running outside Docker) ---
 DATABASE_URL=postgresql:///fly_trader
@@ -15,7 +19,7 @@ DATABASE_URL=postgresql:///fly_trader
 LIVE_ENABLED=1
 # What you fund the wallet with; also the paper warm-up bankroll.
 CAPITAL_SOL=0.5
-# Hard cap per position.
+# The fixed size for a model without a sizing table (the shipped fly has one); must be above 0 to trade live.
 MAX_POSITION_SOL=0.05
 # Per position, of the bankroll minus the gas reserve.
 MAX_POSITION_FRACTION=0.10
@@ -26,6 +30,13 @@ MIN_POSITION_SOL=0.02
 # Never spent (fees and token-account rent).
 GAS_RESERVE_SOL=0.05
 KELLY_FRACTION=0.25
+# The signer's own limits (defaults shown): SOL per buy, SOL of buys per day, swaps per minute (buys and sells), priority
+# fee per swap, and the least value a swap may return for what it costs, at the signer's own Jupiter prices.
+# SIGNER_MAX_BUY_SOL=1
+# SIGNER_DAILY_BUY_SOL=10
+# SIGNER_SWAPS_PER_MIN=6
+# SIGNER_MAX_PRIORITY_SOL=0.005
+# SIGNER_MIN_VALUE_RATIO=0.6
 
 # --- rails ---
 # 20 % below the wallet's peak: stop entering ...
@@ -41,18 +52,42 @@ HANDOVER_BEAT_SELECTOR=0
 # A restart keeps the paper book, so the warm-up count survives it.
 RESET_ON_START=0
 
+# --- Robinhood Chain memecoins (Pons launches graduated into Uniswap v4; money in ETH) ---
+# Off by default. 1 = index Robinhood Chain (the rh_stream worker) and paper-trade it in ETH beside Solana. Indexing needs
+# an Envio HyperSync token (ENVIO_API_TOKEN below; the free tier works, slower) -- the public RPC is far too slow for
+# the backfill -- and disk for the history: ~30 GB from 2026-08-04. RH_START_DAY a ~40 days back indexes much less
+# (the RH models need about a month of history per wallet); the RH books trade once the stream reaches the present.
+RH_ENABLED=0
+# ENVIO_API_TOKEN=
+# RH_START_DAY=2026-08-04
+# Real RH transactions stay off: the RH books trade paper until you set 1 and add the key and address below.
+RH_LIVE_ENABLED=0
+# 1 = the rehearsal chain (46630); the guard refuses any other chain id than the one selected here.
+RH_TESTNET=0
+# RPCs (defaults shown): logs from HyperSync (the official RPC when HyperSync fails), transactions from the official RPC,
+# block headers from PublicNode. A QuickNode Robinhood Chain endpoint, if you have one, serves the transactions.
+# RH_RPC_URL=https://rpc.mainnet.chain.robinhood.com
+# RH_RPC_URL_BLOCKS=https://robinhood-rpc.publicnode.com
+# QUICKNODE_RH_API_URL=
+# The address RH_BOT_PRIVATE_KEY must derive to (a guard, not a secret). Needed only for live.
+RH_BOT_ADDRESS=
+# RH_BOT_PRIVATE_KEY (hex) goes in this .env only, on its own line, when you enable live. It is read from here at run
+# time and never baked into the image. Do not leave an empty RH_BOT_PRIVATE_KEY= line.
+
 # --- runtime ---
 SOLANA_CLUSTER=mainnet-beta
 # auto: an NVIDIA GPU when the container has one (docker-compose.cuda.yml), else the CPU. Or cpu | cuda | cuda:1.
 DEVICE=auto
 # Batch sizes are derived from the device's free memory; on a shared GPU cap what the fly may use, in GB.
 # DEVICE_MEMORY_GB=
+# docker-compose.yml sets these to /app/data and /app/logs, your ./data and ./logs
 DATA_DIR=data
 LOG_DIR=logs
 
 # --- staying current ---
-# Every UPDATE_INTERVAL_S the container asks Hugging Face whether HF_REPO has a new release; if so it downloads the new
-# code and model, restarts itself (about a minute; open positions are untouched) and keeps the previous release for a
+# Every UPDATE_INTERVAL_S the container asks Hugging Face whether HF_REPO has a new release. It installs one only if it is
+# signed by a key in release/allowed_signers and newer than the installed one, and every file matches the signed
+# manifest; then it restarts itself (about a minute; open positions are untouched) and keeps the previous release for a
 # rollback if the new one fails to start. AUTO_UPDATE=0 pins this install to what it was built from.
 AUTO_UPDATE=1
 HF_REPO=bryceweiner/fly-trader

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+models/selectors/selector_20261003T201413Z.skops filter=lfs diff=lfs merge=lfs -text

CHANGELOG.md

@@ -0,0 +1,131 @@
+# Changelog
+
+Releases are identified by date. The Docker distribution (branch `distribution`, Hugging Face `bryceweiner/fly-trader`)
+ships signed releases built from this development line.
+
+## 2026-10-11: Robinhood Chain, and a fly that starts as its selector
+
+Not yet published to Hugging Face. Ships fly #157 (network) with selector #154, both trained on Solana and Robinhood
+Chain rows together.
+
+### Upgrading
+
+- **Docker installs from before October 2026 must rebuild once:** `git pull && docker compose up -d --build`. The old
+  image cannot verify signed releases, so it stops updating after this release. Data, the fly's learned state and
+  open positions are kept.
+- **Robinhood Chain is off by default** in the distribution. To turn it on, set `RH_ENABLED=1` and `ENVIO_API_TOKEN` (an
+  Envio HyperSync token; the free tier works) in `.env`.
+  - Indexing the full history from 2026-08-04 takes about 30 GB.
+  - Setting `RH_START_DAY` about 40 days back is enough to trade.
+- **New settings:**
+  - `FLY_SCORE` (default `teacher`), `FLY_TEACHER_GATE` (default on), `FLY_LEARNED_VETO` (default 0.02) and `FLY_SIZING`
+    (default `kelly`).
+  - Robinhood Chain: `ENVIO_API_TOKEN`, `RH_*`, and optionally `QUICKNODE_RH_API_URL` for transactions.
+
+### The fly
+
+- **It scores as its selector plus what it has learned** (`FLY_SCORE=teacher`).
+  - On the first day its score equals the selector's exactly, verified live to 3e-8 on every row.
+  - Its learnable mushroom-body pathway (the plastic KC→MBON synapses) adds a correction, learned from realized returns,
+    that starts at zero.
+  - It therefore learns only where the selector is wrong.
+  - The earlier fly was a distilled copy of the selector, accurate overall but not at the buy line: it ranked the
+    selector's top 1 % of candidates only about 0.6-correlated.
+- **It buys only what the selector buys** (`FLY_TEACHER_GATE`).
+  - The selector's trigger, buy line, win filter, dump veto and fail-closed rules decide every row.
+  - The fly's learning can drop a selector trade (a learned veto: its score more than 0.02 below its starting score) but
+    can never add one.
+  - Ungated, the fly had bought rows the selector rejected; those rows averaged −25.9 % per trade.
+- **It sizes each buy exactly as the selector sizes it** (`FLY_SIZING=kelly`): the selector's score, buy line and Kelly
+  table for that row.
+- **It learns from the selector's trades,** live and in the replay, after a restart too. It no longer learns from rows
+  above its own buy line.
+- **It never trades without its teacher.** A fly whose selector cannot be loaded enters nothing. A release install now
+  points the fly at the shipped selector's new database id. Before that fix, the Docker boot test found a fresh install
+  running the fly ungated.
+- **Replay verdict** (2026-09-24 to 10-09, the fly against the selector itself):
+  - Solana +3.78 % per trade over 308 trades.
+  - Robinhood Chain +2.66 % over 1,477 trades (selector +2.63 %).
+  - Random picks lost 4.4–4.6 %.
+- **Smaller changes:**
+  - The fly calibrates on days its teacher never saw.
+  - A NaN mean can no longer pass the deploy gate.
+  - A second chain's teacher gets 28 days of its own data before the replay starts.
+  - `fly-replay --chains` re-judges one chain and keeps the others' verdicts.
+
+### Robinhood Chain (new)
+
+- **Pons memecoins traded beside pump.fun.** It trades tokens launched on Pons V2 after they graduate into Uniswap v4 pools
+  with the Pons hook.
+  - Each chain has its own books in its own unit (Robinhood Chain in ETH), with its own bankroll, kill switch, handover
+    and verdict.
+  - One selector and one fly cover both chains. A chain trades only if its own replay verdict passed.
+- **Its own indexer.** It reads launches, graduations, swaps, the base assets' prices and 1-minute rows.
+  - Logs come from Envio HyperSync, in one query per pass.
+  - Minutes land about 15–25 s after they close (they took 35–95 s at first).
+  - If HyperSync fails, the official RPC carries the feed until it recovers.
+  - RH minutes up to 240 s old are still traded (`RH_TRADE_LAG_S`).
+- **Live trading** (`RH_LIVE_ENABLED=0` by default):
+  - Swaps route through KyberSwap, with a Uniswap v4 fallback.
+  - One transaction is in flight at a time, booked from measured balances.
+  - It recovers after a crash and is reconciled against the chain.
+  - It has its own circuit breaker (circuit 3).
+  - `fly-trader rh-smoke` runs a tiny mainnet round trip.
+  - A QuickNode endpoint (`QUICKNODE_RH_API_URL`), if set, carries transactions. Its free plan caps log queries at 5
+    blocks, so logs stay on HyperSync.
+- **Costs:** the Pons hook fee and creator tax (0.99 % per side at the median), price impact and gas.
+- **Console:**
+  - A chain picker switches the Overview and Trades pages.
+  - A Robinhood Chain page shows the indexer, quote-asset prices and the ETH wallet.
+  - Safety & wallet shows both chains' bot wallets in USD and withdraws only to your own wallets.
+
+### $FLY vault
+
+- Robinhood Chain profit is paid to lockers in ETH, beside the SOL pot.
+- **Custody:** a Squads treasury with spending limits and a key-isolated signer container. Claims are paid from a
+  separate payout wallet, and code releases are delayed.
+- **Nothing published helps trade ahead of the fly.** The trading wallet's address, open positions and settlement
+  timing are not shown.
+- **Audits:** red-team tests, mutation testing, Echidna and Halmos proofs.
+  - Fixed: a claim double-pay on resume.
+  - Added: Kyber calldata and fee checks, and relay griefing limits.
+
+### Docker distribution
+
+- Runs the development line's code again, merged instead of hand-ported (it had fallen about 35 commits behind).
+- **Signed releases only.**
+  - The container installs a release only if its manifest is signed by a key in `release/allowed_signers`, its number
+    is higher than the installed one, and every file matches its hash.
+  - Releases carry no `.git*` file and no model they do not name.
+  - Startup removes model files an earlier release left behind.
+- **Models are accepted whether or not Robinhood Chain is on.** Before release, an install with RH off would have
+  rejected the combined models and crash-looped at boot.
+- The Robinhood Chain reference table ships in the seed.
+- Kalshi ships dormant: no worker starts, and its pages appear only once `KALSHI_API_KEY_ID` is set.
+
+### Kalshi prediction markets (development line)
+
+- Under development, not traded in the distribution. Covers:
+  - an outcome-blind event corpus
+  - a selector judged by a weekly sign test
+  - maker and taker arms
+  - a visual fly
+
+### Fixes
+
+- **Schema changes no longer deadlock live workers.** An unchanged schema is skipped, and a changed one waits at most
+  5 s for a lock, then retries.
+- **The RH paper books had made no trades.** A day's wallet-skill table did not exist yet when its minutes were scored.
+  Tables are now written ahead of their day, and the stream falls back to the newest one.
+- **HyperSync could stall for 76 s.** A dead server address hung new connections; connections now time out in 5 s and
+  are kept alive.
+- **The RH price scan ran about 270 queries per pass.** It now reads every price cursor at once.
+
+## 2026-09-24: Fly #107 taught by selector #100
+
+- The selector was retrained on real fees, and the fly was bootstrapped from it.
+- The container keeps itself current from Hugging Face.
+
+## 2026-09-22: First distribution
+
+- Fire-and-forget trading in Docker, with the fly, its teacher selector and their connectome.

Dockerfile

@@ -1,28 +1,56 @@
 # fly-trader: the trading engine and its console, on the CPU (a Linux container has no Metal GPU; the fly infers fine on CPU).
-FROM python:3.13-slim
+# Two images from one file:
+#   default (last stage, "brain"): the engine, console and vault worker. It holds NO wallet key.
+#   --target signer: the only holder of the hot keys (fly_trader/signer): standard library + solders + httpx, nothing
+#   else of fly_trader, so none of the brain's dependencies ever run next to a key.
+# Base images are pinned by digest and every Python dependency by hash (uv.lock, docker/signer-requirements.txt): a
+# release builds exactly what was reviewed, whatever the registries serve later.
+ARG PYTHON_IMAGE=python:3.13-slim@sha256:7c61056e61ac89e852de05f3dc6fa51a6dd2181797bceed46aa725dd7cb2cd3b
 
+# ---------------------------------------------------------------- the signer
+FROM ${PYTHON_IMAGE} AS signer
+ENV PYTHONUNBUFFERED=1 PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=/app
+RUN apt-get update && apt-get install -y --no-install-recommends age && rm -rf /var/lib/apt/lists/* \
+    && groupadd -g 10000 fly && useradd -u 10002 -g 10000 -M -s /usr/sbin/nologin signer
+COPY docker/signer-requirements.txt /tmp/req.txt
+RUN pip install --no-cache-dir --require-hashes --only-binary=:all: -r /tmp/req.txt && rm /tmp/req.txt
+WORKDIR /app
+COPY fly_trader/__init__.py fly_trader/__init__.py
+COPY fly_trader/signer fly_trader/signer
+USER 10002:10000
+HEALTHCHECK --interval=30s --timeout=10s --start-period=20s --retries=3 CMD python -m fly_trader.signer ping || exit 1
+CMD ["python", "-m", "fly_trader.signer", "serve"]
+
+# ---------------------------------------------------------------- the brain (default)
+FROM ${PYTHON_IMAGE} AS brain
 ENV PYTHONUNBUFFERED=1 \
     UV_PROJECT_ENVIRONMENT=/app/.venv \
+    UV_COMPILE_BYTECODE=1 \
+    HOME=/tmp \
     PATH="/app/.venv/bin:${PATH}"
 
-RUN apt-get update && apt-get install -y --no-install-recommends postgresql-client ca-certificates curl age \
-    && rm -rf /var/lib/apt/lists/*
-COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+# openssh-client: ssh-keygen verifies signed releases (the self-updater, fly_trader/ops/autoupdate.py)
+RUN apt-get update && apt-get install -y --no-install-recommends postgresql-client ca-certificates curl age openssh-client \
+    && rm -rf /var/lib/apt/lists/* \
+    && groupadd -g 10000 fly && useradd -u 10001 -g 10000 -M -s /usr/sbin/nologin fly
+COPY --from=ghcr.io/astral-sh/uv:0.12.19@sha256:04d046b13e60d6bcec73cbc5e1cad25d680dea90c8573340950a0ac2d1aef424 /uv /usr/local/bin/uv
 
 WORKDIR /app
 COPY . .
 # Which torch: TORCH_INDEX=cpu (default: any machine, ~200 MB) or cu126 / cu130 for an NVIDIA GPU (the CUDA runtime is
 # inside the wheel; the host needs only the driver and the NVIDIA Container Toolkit -- see docker-compose.cuda.yml).
-# Installed first so the project's own pin is already satisfied and PyPI's 3 GB CUDA default is never pulled by accident.
-# Editable install: the package IS /app/fly_trader, so config.REPO_ROOT is /app -- the mounted .env the wallet writes
-# to, the console's static directory, config/. A plain install ran a copy under site-packages and looked there instead.
+# It names the project extra that pins torch to that index. --frozen: exactly uv.lock with its hashes, never a fresh
+# resolution. The project installs editable: the package IS /app/fly_trader, so config.REPO_ROOT is /app.
 ARG TORCH_INDEX=cpu
-RUN uv venv /app/.venv \
-    && uv pip install --index-url "https://download.pytorch.org/whl/${TORCH_INDEX}" "torch>=2.12" \
-    && uv pip install -e . \
-    && chmod +x /app/docker/entrypoint.sh
+ENV TORCH_INDEX=${TORCH_INDEX}
+RUN uv sync --frozen --no-dev --extra "${TORCH_INDEX}" \
+    && chmod +x /app/docker/entrypoint.sh \
+    && mkdir -p /app/fly_trader/ui/static/brain && chown -R 10001:10000 /app/fly_trader/ui/static/brain
+# The vault server runs this unprivileged user and never updates itself (AUTO_UPDATE=0). The self-hosted compose file
+# runs the container as root instead: its self-updater replaces /app, and it writes the bind-mounted data/, logs/, .env.
+USER 10001:10000
 
 EXPOSE 8501
-# healthy = the database answers and the console's worker threads run (the vault server's updater waits on this)
+# healthy = the database answers, the console's worker threads run and (on the vault server) the signer answers
 HEALTHCHECK --interval=30s --timeout=20s --start-period=300s --retries=5 CMD fly-trader health || exit 1
 ENTRYPOINT ["/app/docker/entrypoint.sh"]

README.md

@@ -6,6 +6,7 @@ tags:
   - solana
   - memecoin
   - pump.fun
+  - robinhood-chain
   - trading
   - connectome
   - drosophila
@@ -14,12 +15,12 @@ tags:
 
 # fly-trader — distribution
 
-**A fruit-fly connectome that trades Solana memecoins with your money.**
+**A fruit-fly connectome that trades memecoins with your money: on Solana, and on Robinhood Chain if you turn it on.**
 
 > ## ⚠️ Read this first
 >
-> This software signs real transactions from a wallet you fund. It buys tokens that graduated from pump.fun, holds them
-> for about two hours, and sells. **It can lose everything in that wallet, quickly.** The model was trained on a few
+> This software signs real transactions from a wallet you fund. It buys tokens that graduated from pump.fun (and, if
+> you turn Robinhood Chain on, from Pons), holds them for two to four hours, and sells. **It can lose everything in that wallet, quickly.** The model was trained on a few
 > months of data; the market it trades is adversarial and changes. Nothing here is a claim of profit, and nothing here is
 > financial advice. Run it only with money you can lose entirely, on a wallet used for nothing else. MIT licence — no
 > warranty of any kind. See [LICENSE](LICENSE).
@@ -32,10 +33,16 @@ connectome they run on. The training pipeline lives on [`master`](https://github
 - Every minute it scores every PumpSwap token that graduated from pump.fun at least six hours ago, from live 1-minute
   candles (a token needs that much history before its features mean anything).
 - The fly — the FlyWire *Drosophila* central brain (41,756 neurons) as a rate network on its real signed synapses —
-  predicts each token's net return over the next 120 minutes. It was taught by a gradient-boosted selector; it then keeps
-  learning from what its own trades earn, through plasticity at its mushroom body's KC→MBON synapses.
-- It buys when the predicted return clears its own buy line, sizes the position from measured certainty (a quarter
-  of the growth-optimal bet, capped), holds 120 minutes, sells.
+  starts as the gradient-boosted selector that taught it: it scores every token with the selector's own prediction of
+  its net return. Its mushroom body's KC→MBON synapses then learn, from what the trades earn, a correction to that
+  prediction, and can veto a selector buy they have learned to distrust.
+- It buys only what the selector buys (the selector's strategy, buy line and filters), sizes the position exactly as the
+  selector does (a quarter of the growth-optimal bet for its score band, capped), holds two to four hours (the
+  strategy's hold), sells.
+- **Every transaction is checked before it is signed** (`fly_trader/signer`): swaps go only through Jupiter's own
+  routes, each one is simulated first and refused if it would spend more than ordered, deliver the token anywhere but
+  your wallet, touch another holding, or return far less value than it costs; buys are capped per trade, per day and per
+  minute.
 - **It starts on paper.** After 20 closed paper trades it switches itself to the wallet and stays there. Before that,
   and whenever the wallet is unfunded or a key is missing, it trades paper and says so on the console.
 - **Rails:** 20 % below the wallet's peak it stops entering and sells every open position (the kill switch); three
@@ -46,13 +53,23 @@ connectome they run on. The training pipeline lives on [`master`](https://github
 
 ## Requirements
 
-- Docker (Desktop on macOS/Windows, or Engine + Compose v2 on Linux). ~2 GB of disk for the image and database.
+- Docker (Desktop on macOS/Windows, or Engine + Compose v2 on Linux). ~2 GB of disk for the image and database
+  (Robinhood Chain, if you turn it on, adds ~30 GB for its full history; see below).
 - A [Helius](https://dashboard.helius.dev) API key (free tier is enough) and a [Jupiter](https://portal.jup.ag) API key.
+  Optional: a second Solana RPC from another provider as `SIGNER_RPC_URL`, so the checks above do not rely on Helius
+  alone.
 - 0.5 SOL you are prepared to lose. Not more: the caps below are sized for 0.5.
 - Any 64-bit CPU: the fly scores about as fast on 16 CPU threads as on a GPU (its forward pass is a memory-bound
   scatter over a million synapses). An NVIDIA GPU is used when you start it with the CUDA override (see below). Apple
   GPUs are not reachable from inside Docker.
 
+> ### ⚠️ Robinhood Chain needs an Envio HyperSync API token
+>
+> Robinhood Chain is off by default. To trade it, create a token in the [Envio dashboard](https://envio.dev/app/api-tokens)
+> (personal accounts get one free), put it in `.env` as `ENVIO_API_TOKEN`, and set `RH_ENABLED=1`. Its feed reads the
+> chain's logs from [Envio HyperSync](https://envio.dev/pricing/hypersync); the public Robinhood Chain RPC is far too slow
+> to index its history. Without a token, leave Robinhood Chain off: Solana trades either way.
+
 ## Start trading
 
 1. Download this branch and open a terminal in it:
@@ -67,13 +84,15 @@ connectome they run on. The training pipeline lives on [`master`](https://github
    ```bash
    docker compose up -d --build
    ```
-   The first start builds the image (several minutes), creates the database, installs the models and starts the market
-   feed and the trading engine.
+   The first start builds the image (several minutes), creates the database, downloads the wallet-skill table (~300 MB,
+   checked against its pinned sha256), installs the models and starts the market feed and the trading engine. The
+   Processes page also lists a `vault` worker that stops at once: it runs only on the hosted $FLY vault server.
 4. Create the bot wallet — it prints the public key and writes the secret into your `.env`:
    ```bash
    docker compose exec fly fly-trader wallet new
    ```
-   **Back up `.env` now.** It is the only copy of that key.
+   **Back up `.env` now.** It is the only copy of that key. (`wallet new` refuses if `.env` already has a
+   `BOT_PRIVATE_KEY=` line, even an empty one.)
 5. Send **0.5 SOL** to the printed address, then restart the engine so it picks up the key:
    ```bash
    docker compose restart fly
@@ -92,7 +111,7 @@ scores anything); then it trades paper until 20 trades have closed; then it trad
 | Clear a tripped kill switch | Safety & wallet → **Clear kill switch**, or `docker compose exec fly fly-trader reset-circuit --kill` (re-bases the peak) |
 | Stop everything | `docker compose down` — **open positions stay open in the wallet**; start again and it sells them on schedule, or sell them yourself |
 | See the logs | `docker compose logs -f fly` |
-| Start again from nothing | `docker compose down -v` (deletes the database) and delete `data/` |
+| Start again from nothing | `docker compose down -v` (deletes the database) and `sudo rm -rf data/` (the container writes it as root; it also holds the signer's ledger) |
 
 The console listens on `127.0.0.1` only. Do not expose it: it can start and stop the engine and clear the rails.
 
@@ -100,15 +119,17 @@ The console listens on `127.0.0.1` only. Do not expose it: it can start and stop
 
 | Path | What |
 |---|---|
-| `models/policies/fly_*.pt` | the fly (`brain_snapshots` #62): taught by selector #59, two strategies (`ev`, `capitulation`), 120-minute hold, its own buy lines |
-| `models/selectors/selector_*.joblib` | the selector that taught it (#59), kept so the console can show the paper selector alongside |
+| `models/policies/fly_*.pt` | the fly (#107 on the training machine; a fresh install gives it its own id): taught by selector #100, one strategy (`capitulation`), 240-minute hold, its own buy line. Loaded weights-only: the file cannot run code |
+| `models/selectors/selector_*.skops` | the selector that taught it (#100), kept so the console can show the paper selector alongside. Saved with skops, not pickle |
 | `models/connectome/` | the FlyWire FAFB v783 central brain as the fly runs on it (14 MB), with its calibrated scale |
-| `models/wallet_skill/` | the fitted wallet-skill inputs: `config.json` (the horizon and lookback the model was trained with) and the name of the newest per-day table. The table itself (~300 MB) is on Hugging Face; the container fetches it once at first start |
-| `seed/seed.sql` | the database rows that admit the fly to trade: the model records, the passed replay verdict, autostart |
+| `models/wallet_skill/` | the fitted wallet-skill inputs: `config.json` (the horizon and lookback the model was trained with), the name of the newest per-day table (`TABLE`) and its sha256 (`TABLE.sha256`). The table itself (~300 MB) is on Hugging Face; the container downloads it once and uses it only if the hash matches |
+| `seed/release_seed.json` (`seed/seed.sql` is the fallback) | the database rows that admit the fly to trade: the model records (by file hash), the passed replay verdict, autostart |
+| `release/allowed_signers` | the release keys this install trusts for automatic updates (see Updates) |
 | `.env.example` | every knob, set for 0.5 SOL |
-| `docker-compose.yml`, `Dockerfile`, `docker/entrypoint.sh` | one Postgres, one engine + console |
+| `docker-compose.yml`, `Dockerfile`, `docker/` | one Postgres, one engine + console (the Dockerfile's default stage; its `signer` stage is for the vault server) |
+| `deploy/` | the hosted $FLY vault server: a separate signer container, host hardening, the signed-release updater ([docs/vault/RUNBOOK.md](docs/vault/RUNBOOK.md)) |
 
-The fly's replay verdict shipped here: over the 28 evaluation days it made +1.52 % per trade after real costs (profit
+The replay verdict shipped here: over the 29 evaluation days it made +1.52 % per trade after real costs (profit
 factor 1.13) against −5.27 % for random picks of the same tokens. That is a backtest on one corpus, not a forecast.
 
 ## Tuning
@@ -118,14 +139,40 @@ Edit `.env`, then `docker compose restart fly`. The ones that matter:
 | Variable | Shipped | Meaning |
 |---|---|---|
 | `CAPITAL_SOL` | 0.5 | what you funded; also the paper warm-up bankroll |
-| `MAX_POSITION_SOL` / `MAX_POSITION_FRACTION` | 0.05 / 0.10 | per-position caps (the smaller wins) |
+| `MAX_POSITION_FRACTION` | 0.10 | the most of the bankroll one position may take |
+| `MAX_POSITION_SOL` | 0.05 | the fixed size for a model without a sizing table (the shipped fly has one); must be above 0 to trade live |
 | `GAS_RESERVE_SOL` | 0.05 | never spent |
 | `KILL_SWITCH_DRAWDOWN` / `KILL_SWITCH_LIQUIDATE` | 0.20 / 1 | drawdown from peak that halts and sells everything |
 | `HANDOVER_MIN_TRADES` | 20 | closed paper trades before it goes live |
 | `LIVE_ENABLED` | 1 | set 0 to run paper only |
 
-Scaling the wallet up scales the position caps with it (`MAX_POSITION_FRACTION`), but `MAX_POSITION_SOL` is a hard
-ceiling: raise it deliberately or not at all.
+Scaling the wallet up scales the positions with it (`MAX_POSITION_FRACTION`). The signer has its own limits that do
+not scale: at most `SIGNER_MAX_BUY_SOL` (1) per buy, `SIGNER_DAILY_BUY_SOL` (10) of buys a day and
+`SIGNER_SWAPS_PER_MIN` (6) swaps a minute; raise them in `.env` deliberately.
+
+## Robinhood Chain (Pons) memecoins
+
+The same engine also trades Robinhood Chain: tokens launched on Pons that graduated into Uniswap v4 pools.
+
+- **Off by default; turn it on with `RH_ENABLED=1` and `ENVIO_API_TOKEN` in `.env`** (an Envio HyperSync token; the
+  free tier works). The `rh_stream` worker then starts with the others and indexes Pons launches, graduations and swaps
+  into 1-minute rows: a backfill from `RH_START_DAY` (default 2026-08-04, ~30 GB; ~40 days back is enough to trade),
+  then live, with RH minutes landing ~15-25 s after they close. If HyperSync fails, the official RPC carries the feed
+  until it is back.
+- **Paper, in ETH.** The Robinhood Chain books
+  (`paper_rh_selector`, `paper_rh_fly`) keep their money in native ETH (`RH_CAPITAL_ETH`, 5 SOL's worth at build time)
+  and pay Pons' hook fee, price impact and gas. They have their own kill switch and circuit (Safety & wallet →
+  Robinhood Chain trading rails) and their own handover. The console's chain picker switches Overview and Trades
+  between the two chains, and the **Robinhood Chain** page shows the indexer, the quote-asset prices and the ETH wallet.
+- **One model for both chains.** The shipped selector and fly were trained on both chains' rows together, and the
+  replay judged each chain on its own trades; a chain's books trade only where its verdict passed. With RH off the same
+  models trade Solana alone.
+- **Live** needs `RH_LIVE_ENABLED=1`, `RH_BOT_PRIVATE_KEY` (in `.env` only, never in the image) and the address it
+  derives to as `RH_BOT_ADDRESS`, plus a funded wallet (ETH on Robinhood Chain, chain 4663). Then
+  `docker compose restart fly`. As on Solana, the fly trades the wallet only after it has won the RH paper race.
+- `RH_ENABLED=0` turns all of it off.
+
+RH training data does not ship: an install that turns RH on builds its own from the stream, as Solana does.
 
 ## NVIDIA GPU
 
@@ -139,31 +186,47 @@ docker compose -f docker-compose.yml -f docker-compose.cuda.yml up -d --build
 
 The image is built with the CUDA 12.6 torch wheel (`TORCH_INDEX: cu126` in `docker-compose.cuda.yml`; `cu130` for the
 newest drivers) and the container is given every GPU. `DEVICE=auto` in `.env` then resolves to the GPU; the console's
-Model page shows which device the fly is on. Batch sizes are derived from the card's free memory, so an 8 GB card works;
+Model & training page shows which device the fly is on. Batch sizes are derived from the card's free memory, so an 8 GB card works;
 on a shared card set `DEVICE_MEMORY_GB` in `.env` to what the fly may use.
 
 ## Updates
 
-The container keeps itself current. Every hour it asks Hugging Face whether
-[`bryceweiner/fly-trader`](https://huggingface.co/bryceweiner/fly-trader) has a new release; when it has, it downloads
-the new code and model, restarts (about a minute; the paper books, the fly's learned state and any open positions are
-untouched -- open positions are sold on schedule by the restarted engine) and keeps the previous release beside the new
-one. If the new release does not come up within five minutes it goes back to the previous one and never tries that
-release again. `docker compose logs -f fly` shows what it did. `AUTO_UPDATE=0` in `.env` turns this off; then the
+The container keeps itself current, with **signed releases only**. Every hour it asks Hugging Face whether
+[`bryceweiner/fly-trader`](https://huggingface.co/bryceweiner/fly-trader) has a new release. It installs one only if:
+- its `release.json` is signed by a key in this install's `release/allowed_signers`
+- its release number is higher than the installed one
+- every file matches the size and sha256 the signed manifest lists
+
+Then it restarts (about a minute; the paper books, the fly's learned state and any open positions are untouched --
+open positions are sold on schedule by the restarted engine) and keeps the previous release beside the new one. If the
+new release does not come up within five minutes, it goes back to the previous one and never tries that release again.
+An unsigned or wrongly signed commit is refused and logged. While `release/allowed_signers` lists no key, nothing is
+installed. `docker compose logs -f fly` shows what it did. `AUTO_UPDATE=0` in `.env` turns this off; then the
 "Refreshing the model" steps below are the manual way.
 
+**Installed before October 2026? Rebuild once.** The updater in those images installed whatever Hugging Face held,
+unverified; it may install this release by itself, but only a rebuilt image can check signatures (it needs `ssh-keygen`),
+so it stops at this release. From your install directory:
+
+```bash
+git pull && docker compose up -d --build
+```
+
+Your data, the fly's learned state and open positions are kept. Robinhood Chain stays off until you turn it on.
+
 ## Refreshing the model
 
 The model is a snapshot of one training run. To ship a newer one, on a `master` checkout with its database, after a
 passed replay:
 
 ```bash
-.venv/bin/python tools/make_seed.py --out dist
-cp -R dist/models/* models/ && cp -R dist/seed/* seed/
+.venv/bin/python tools/make_seed.py --out ../fly-trader-dist
 ```
 
-Commit `models/` and `seed/` on this branch. The seed is idempotent: an install that already has these rows is not
-changed by it, so pull the branch, `docker compose up -d --build`, and the new model is in place.
+Then publish it as a signed release with `tools/publish_release.py` (docs/vault/RUNBOOK.md, section 4.1): installs
+with automatic updates pick it up within the hour. For a manual install, commit `models/` and `seed/` on this branch;
+every start runs `fly-trader apply-release`, which reuses rows it already has (same file hash) and registers new
+models, so pull the branch, `docker compose up -d --build`, and the new model is in place.
 
 ## Also on Hugging Face
 
@@ -174,6 +237,6 @@ changed by it, so pull the branch, `docker compose up -d --build`, and the new m
 
 FlyWire consortium, Dorkenwald et al., *Neuronal wiring diagram of an adult brain*, Nature 2024; annotations Schlegel
 et al. 2024; synapse signs Shiu et al. 2024. Connectome export: [snedea/flybrain](https://github.com/snedea/flybrain)
-(MIT). Market data: [PumpAPI](https://pumpapi.io); routing: [Jupiter](https://jup.ag).
+(MIT). Market data: [PumpAPI](https://pumpapi.io); routing: [Jupiter](https://jup.ag) (Metis routes only).
 
 [MIT](LICENSE).

deploy/bootstrap-host.sh

@@ -1,64 +1,459 @@
 #!/usr/bin/env bash
-# One-time setup of the vault fly's server (Ubuntu 24.04, e.g. Netcup RS 2000 G12). Run as root:
-#   bash bootstrap-host.sh "<your ssh-ed25519 RELEASE public key line>"
-# It installs Docker, locks the box down (SSH keys only, firewall: SSH in, nothing else), installs the updater with
-# YOUR release key as the only trusted signer, and lays out /srv/fly. It does not create the wallet or start the fly.
+# One-time setup of the vault fly's server: a dedicated machine (e.g. a mini PC at home) on a fresh Ubuntu Server 24.04
+# with full-disk encryption, hardened along the lines of the CIS Ubuntu 24.04 benchmark for a single-purpose host that
+# holds a hot wallet. Run with sudo, in two passes:
+#
+#   1. sudo TS_AUTHKEY=tskey-auth-... RECOVERY_PUBKEY="ssh-ed25519 AAAA... recovery" EXPECT_MANIFEST=<sha256 of release.json> \
+#        TPM_UNLOCK=1 ADMIN_USER=fly-admin bash bootstrap-host.sh "<release public key line: Secretive's ecdsa-sha2-nistp256 ...>"
+#      then, from your Mac, log in over Tailscale:  ssh fly-admin@fly-vault   (MagicDNS name or the 100.x address)
+#   2. sudo CLOSE_PUBLIC_SSH=1 bash bootstrap-host.sh "<same release key>"
+#      removes the SSH rule for the local network / internet: after it the machine accepts SSH only over Tailscale and
+#      has no other open port.
+#
+# TPM_UNLOCK=1 binds the root disk's LUKS encryption to the TPM (clevis, PCR 7 = the Secure Boot state), so an
+# unattended security reboot comes back up without a passphrase; it asks once for the disk passphrase. Without it the
+# machine waits at every boot for the passphrase on its console, and automatic reboots are turned off.
+#
+# ADMIN_USER (default fly-admin) becomes the only account that can log in over SSH (key only, sudo without a
+# password; root login is switched off). If it has no ~/.ssh/authorized_keys yet, root's are copied to it first, and
+# the script stops before touching SSH if neither exists. Keep this root session open until you have logged in as
+# ADMIN_USER from a second terminal. deploy/check-host.sh verifies every setting afterwards.
+#
+# RELEASE_PUBKEY / RECOVERY_PUBKEY: the two keys whose signatures the updater accepts (principals bryce and
+# bryce-recovery), valid for the release namespace only. EXPECT_MANIFEST pins the first release the updater may
+# install (tools/publish_release.py prints it as the manifest sha256); until it is set the updater installs nothing.
+# TS_AUTHKEY: a one-off, pre-authorised key tagged tag:fly from the Tailscale admin console; used once, not stored.
+#
+# Idempotent: safe to run again (keys and edited config files are never overwritten).
 set -euo pipefail
-RELEASE_PUBKEY="${1:?usage: bootstrap-host.sh \"ssh-ed25519 AAAA... release-key\"}"
+RELEASE_PUBKEY="${1:?usage: ADMIN_USER=fly-admin bootstrap-host.sh \"ecdsa-sha2-nistp256 AAAA... release-key\"}"
+RECOVERY_PUBKEY="${RECOVERY_PUBKEY:-}"
+EXPECT_MANIFEST="${EXPECT_MANIFEST:-}"
+TS_AUTHKEY="${TS_AUTHKEY:-}"
+CLOSE_PUBLIC_SSH="${CLOSE_PUBLIC_SSH:-0}"
+TPM_UNLOCK="${TPM_UNLOCK:-0}"
+ADMIN_USER="${ADMIN_USER:-fly-admin}"
+# container users (the images' USER lines); with userns-remap each is REMAP_UID + id on the host
+BRAIN_UID=10001; SIGNER_UID=10002; FLY_GID=10000
+HERE="$(cd "$(dirname "$0")" && pwd)"
+export DEBIAN_FRONTEND=noninteractive
+step() { printf '\n== %s\n' "$*"; }
 
-apt-get update
-apt-get install -y ca-certificates curl ufw unattended-upgrades python3 openssh-client
+# ---------------------------------------------------------------- 1. packages
+step "packages"
+apt-get update -q
+apt-get install -y -q --no-install-recommends ca-certificates curl ufw unattended-upgrades python3 openssh-client openssl \
+  fail2ban python3-systemd auditd audispd-plugins aide aide-common lynis apparmor-utils systemd-timesyncd needrestart \
+  libpam-tmpdir debsums apt-show-versions apt-listchanges acct sysstat mokutil
 install -m 0755 -d /etc/apt/keyrings
 curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
 echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" > /etc/apt/sources.list.d/docker.list
-apt-get update
-apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
-dpkg-reconfigure -f noninteractive unattended-upgrades
+apt-get update -q
+apt-get install -y -q docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
+# Tailscale: SSH reaches this box only over your tailnet (WireGuard); its repo key is pinned like Docker's
+curl -fsSL "https://pkgs.tailscale.com/stable/ubuntu/$(. /etc/os-release && echo "$VERSION_CODENAME").noarmor.gpg" -o /etc/apt/keyrings/tailscale.gpg
+echo "deb [signed-by=/etc/apt/keyrings/tailscale.gpg] https://pkgs.tailscale.com/stable/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") main" > /etc/apt/sources.list.d/tailscale.list
+apt-get update -q
+apt-get install -y -q tailscale
+# nothing on this box needs snaps; fewer daemons, fewer holes
+if dpkg -l snapd >/dev/null 2>&1; then apt-get purge -y -q snapd; fi
+# no mail server: nothing here sends mail (alerts go to Telegram), and an MTA is one more listening daemon
+if dpkg -l postfix 2>/dev/null | grep -q '^ii'; then apt-get purge -y -q postfix; fi
+
+# ---------------------------------------------------------------- 1b. the machine itself
+step "machine: wireless off, DMA protection, disk encryption"
+# wired Ethernet only: Wi-Fi and Bluetooth drivers can never load (a radio is a way in that bypasses the router)
+printf 'install cfg80211 /bin/false\ninstall mac80211 /bin/false\ninstall bluetooth /bin/false\ninstall btusb /bin/false\n' \
+  > /etc/modprobe.d/61-fly-no-wireless.conf
+command -v rfkill >/dev/null && rfkill block all 2>/dev/null || true
+systemctl disable --now bluetooth.service wpa_supplicant.service 2>/dev/null || true
+# USB4 / Thunderbolt / OCuLink devices can read memory directly; the IOMMU confines them
+if [ -z "$(ls -A /sys/kernel/iommu_groups 2>/dev/null)" ]; then
+  echo "WARNING: the IOMMU is off: enable it (AMD-Vi / IOMMU) in the firmware settings"
+fi
+# the root filesystem must sit on LUKS: the wallet keys are files on this disk
+ROOT_LUKS="$(lsblk -rno NAME,TYPE -s "$(findmnt -no SOURCE /)" 2>/dev/null | awk '$2=="crypt"{found=1} found && $2=="part"{print "/dev/"$1; exit}')"
+if [ -z "$ROOT_LUKS" ]; then
+  echo "WARNING: the root filesystem is not on an encrypted (LUKS) disk: reinstall with 'Encrypt the LVM group with LUKS'"
+elif [ "$TPM_UNLOCK" = 1 ]; then
+  apt-get install -y -q --no-install-recommends clevis clevis-luks clevis-tpm2 clevis-initramfs
+  if ! clevis luks list -d "$ROOT_LUKS" 2>/dev/null | grep -q tpm2; then
+    echo "binding $ROOT_LUKS to the TPM (PCR 7); enter the disk passphrase when asked"
+    clevis luks bind -d "$ROOT_LUKS" tpm2 '{"pcr_ids":"7"}'
+    update-initramfs -u -k all
+  fi
+fi
+
+# ---------------------------------------------------------------- 2. patching
+step "automatic security updates (reboot 04:00 UTC when a kernel needs it)"
+cat > /etc/apt/apt.conf.d/20auto-upgrades <<'EOF'
+APT::Periodic::Update-Package-Lists "1";
+APT::Periodic::Unattended-Upgrade "1";
+APT::Periodic::AutocleanInterval "7";
+EOF
+REBOOT=true                                  # a disk that needs a typed passphrase at boot: no unattended reboots
+if [ -n "${ROOT_LUKS:-}" ] && ! { command -v clevis >/dev/null && clevis luks list -d "$ROOT_LUKS" 2>/dev/null | grep -q tpm2; }; then
+  REBOOT=false
+fi
+cat > /etc/apt/apt.conf.d/52fly-unattended <<EOF
+Unattended-Upgrade::Automatic-Reboot "$REBOOT";
+Unattended-Upgrade::Automatic-Reboot-Time "04:00";
+Unattended-Upgrade::Remove-Unused-Dependencies "true";
+EOF
+systemctl enable --now unattended-upgrades.service
+timedatectl set-timezone UTC
+systemctl enable --now systemd-timesyncd.service      # the relay refuses the fly's requests if the clock is > 5 min off
+
+# ---------------------------------------------------------------- 3. admin account
+step "admin account: $ADMIN_USER"
+id "$ADMIN_USER" >/dev/null 2>&1 || useradd -m -s /bin/bash "$ADMIN_USER"
+passwd -l "$ADMIN_USER" >/dev/null                    # no password at all: SSH key only
+home="$(getent passwd "$ADMIN_USER" | cut -d: -f6)"
+install -d -m 0700 -o "$ADMIN_USER" -g "$ADMIN_USER" "$home/.ssh"
+if [ ! -s "$home/.ssh/authorized_keys" ]; then
+  if [ -s /root/.ssh/authorized_keys ]; then
+    install -m 0600 -o "$ADMIN_USER" -g "$ADMIN_USER" /root/.ssh/authorized_keys "$home/.ssh/authorized_keys"
+  else
+    echo "STOP: neither $ADMIN_USER nor root has ~/.ssh/authorized_keys; add your key first" >&2; exit 1
+  fi
+fi
+echo "$ADMIN_USER ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/90-fly-admin
+chmod 0440 /etc/sudoers.d/90-fly-admin
+visudo -cf /etc/sudoers.d/90-fly-admin >/dev/null
+# NOT in the docker group: that group is root without sudo's log line; docker runs through sudo
+gpasswd -d "$ADMIN_USER" docker >/dev/null 2>&1 || true
+
+# ---------------------------------------------------------------- 4. SSH
+step "SSH: $ADMIN_USER only, key only, modern crypto"
+cat > /etc/ssh/sshd_config.d/10-fly-hardening.conf <<EOF
+PermitRootLogin no
+PasswordAuthentication no
+KbdInteractiveAuthentication no
+PubkeyAuthentication yes
+AuthenticationMethods publickey
+AllowUsers $ADMIN_USER
+MaxAuthTries 3
+MaxSessions 4
+LoginGraceTime 20
+ClientAliveInterval 300
+ClientAliveCountMax 2
+PermitEmptyPasswords no
+PermitUserEnvironment no
+X11Forwarding no
+AllowAgentForwarding no
+# local forwarding stays on: it is how you reach the console (ssh -L 8501:127.0.0.1:8501)
+AllowTcpForwarding local
+GatewayPorts no
+PermitTunnel no
+Compression no
+TCPKeepAlive no
+MaxStartups 10:30:60
+LogLevel VERBOSE
+KexAlgorithms sntrup761x25519-sha512@openssh.com,curve25519-sha256,curve25519-sha256@libssh.org
+Ciphers chacha20-poly1305@openssh.com,aes256-gcm@openssh.com,aes128-gcm@openssh.com
+MACs hmac-sha2-512-etm@openssh.com,hmac-sha2-256-etm@openssh.com
+HostKeyAlgorithms ssh-ed25519,rsa-sha2-512,rsa-sha2-256
+# client keys: ed25519, FIDO/hardware-backed keys, and P-256 (Secure Enclave keys from Secretive; the Ledger later)
+PubkeyAcceptedAlgorithms sk-ssh-ed25519@openssh.com,ssh-ed25519,sk-ecdsa-sha2-nistp256@openssh.com,ecdsa-sha2-nistp256
+EOF
+# older lines in the main file must not win: Include is at the top, and first match wins in sshd
+sed -i 's/^\(PermitRootLogin\|PasswordAuthentication\|KbdInteractiveAuthentication\|X11Forwarding\)/# fly: see sshd_config.d\/10-fly-hardening.conf\n#&/' /etc/ssh/sshd_config
+install -d -m 0755 /run/sshd                            # 24.04 starts sshd on demand; the check needs this dir
+sshd -t
+systemctl reload ssh 2>/dev/null || systemctl restart ssh
 
-# SSH: keys only (make sure your key is in ~/.ssh/authorized_keys BEFORE running this)
-sed -i 's/^#\?PasswordAuthentication .*/PasswordAuthentication no/; s/^#\?PermitRootLogin .*/PermitRootLogin prohibit-password/' /etc/ssh/sshd_config
-systemctl reload ssh || systemctl reload sshd
+step "fail2ban: SSH brute force"
+cat > /etc/fail2ban/jail.d/fly-sshd.local <<'EOF'
+[sshd]
+enabled = true
+backend = systemd
+maxretry = 4
+findtime = 10m
+bantime = 1h
+bantime.increment = true
+EOF
+systemctl enable --now fail2ban
+systemctl restart fail2ban
+
+# ---------------------------------------------------------------- 5. Tailscale + firewall
+step "Tailscale"
+systemctl enable --now tailscaled
+if [ -n "$TS_AUTHKEY" ] && ! tailscale status >/dev/null 2>&1; then
+  tailscale up --auth-key="$TS_AUTHKEY" --hostname=fly-vault --advertise-tags=tag:fly --ssh=false --accept-dns=false
+fi
+unset TS_AUTHKEY
+TS_UP=0; tailscale status >/dev/null 2>&1 && TS_UP=1
+
+step "firewall: SSH over Tailscale only (plus LAN/public SSH until CLOSE_PUBLIC_SSH=1); out: HTTPS, HTTP (apt), DNS, NTP, WireGuard"
+ufw --force reset >/dev/null
 ufw default deny incoming
-ufw default allow outgoing
-ufw allow OpenSSH
+ufw default deny outgoing
+ufw default deny routed
+ufw allow in on tailscale0 to any port 22 proto tcp comment 'ssh over the tailnet'
+if [ "$CLOSE_PUBLIC_SSH" = 1 ]; then
+  [ "$TS_UP" = 1 ] || { echo "STOP: Tailscale is not up; closing public SSH now would lock you out" >&2; exit 1; }
+  echo "public SSH closed: log in with ssh $ADMIN_USER@fly-vault (Tailscale)"
+else
+  ufw limit in 22/tcp comment 'ssh (rate limited) -- removed by CLOSE_PUBLIC_SSH=1'
+fi
+ufw allow out 443/tcp comment 'https: RPCs, relay, HF, Telegram, apt, Tailscale control'
+ufw allow out 80/tcp comment 'http: apt mirrors'
+ufw allow out 53 comment 'dns'
+ufw allow out 123/udp comment 'ntp'
+ufw allow out 41641/udp comment 'tailscale wireguard'
+ufw allow out 3478/udp comment 'tailscale stun'
+ufw logging low
 ufw --force enable
 
-# layout
-install -d -m 0750 /srv/fly /srv/fly/data /srv/fly/logs /srv/fly/releases
+# Docker writes its own iptables rules and bypasses ufw; the DOCKER-USER chain is where the host gets a say. Containers
+# may only talk to each other, reach DNS/HTTPS out, and nothing on the internet may open a connection to them.
+cat > /usr/local/sbin/fly-docker-firewall <<'EOF'
+#!/bin/sh
+set -e
+iptables -N DOCKER-USER 2>/dev/null || true
+iptables -F DOCKER-USER
+iptables -A DOCKER-USER -m conntrack --ctstate ESTABLISHED,RELATED -j RETURN
+iptables -A DOCKER-USER -i docker0 -o docker0 -j RETURN
+iptables -A DOCKER-USER -i br-+ -o br-+ -j RETURN
+for p in 443 80 53; do                  # 80: apt mirrors during image builds (apt checks its own signatures)
+  iptables -A DOCKER-USER -i br-+ -p tcp --dport $p -j RETURN
+  iptables -A DOCKER-USER -i docker0 -p tcp --dport $p -j RETURN
+done
+iptables -A DOCKER-USER -i br-+ -p udp --dport 53 -j RETURN
+iptables -A DOCKER-USER -i docker0 -p udp --dport 53 -j RETURN
+iptables -A DOCKER-USER -i br-+ -j DROP
+iptables -A DOCKER-USER -i docker0 -j DROP
+iptables -A DOCKER-USER -m conntrack --ctstate NEW -j DROP
+EOF
+chmod 0750 /usr/local/sbin/fly-docker-firewall
+cat > /etc/systemd/system/fly-docker-firewall.service <<'EOF'
+[Unit]
+Description=fly-trader: restrict container traffic (DOCKER-USER chain)
+After=docker.service
+Requires=docker.service
+PartOf=docker.service
+[Service]
+Type=oneshot
+RemainAfterExit=yes
+ExecStart=/usr/local/sbin/fly-docker-firewall
+[Install]
+WantedBy=docker.service
+EOF
+
+# ---------------------------------------------------------------- 6. kernel
+step "kernel and network settings"
+cat > /etc/sysctl.d/60-fly-hardening.conf <<'EOF'
+net.ipv4.conf.all.accept_redirects = 0
+net.ipv4.conf.default.accept_redirects = 0
+net.ipv4.conf.all.secure_redirects = 0
+net.ipv4.conf.default.secure_redirects = 0
+net.ipv4.conf.all.send_redirects = 0
+net.ipv4.conf.default.send_redirects = 0
+net.ipv4.conf.all.accept_source_route = 0
+net.ipv4.conf.default.accept_source_route = 0
+net.ipv4.conf.all.rp_filter = 1
+net.ipv4.conf.default.rp_filter = 1
+net.ipv4.conf.all.log_martians = 1
+net.ipv4.conf.default.log_martians = 1
+net.ipv4.icmp_echo_ignore_broadcasts = 1
+net.ipv4.icmp_ignore_bogus_error_responses = 1
+net.ipv4.tcp_syncookies = 1
+net.ipv6.conf.all.accept_redirects = 0
+net.ipv6.conf.default.accept_redirects = 0
+net.ipv6.conf.all.accept_source_route = 0
+net.ipv6.conf.default.accept_source_route = 0
+kernel.kptr_restrict = 2
+kernel.dmesg_restrict = 1
+kernel.unprivileged_bpf_disabled = 1
+net.core.bpf_jit_harden = 2
+kernel.yama.ptrace_scope = 2
+kernel.randomize_va_space = 2
+kernel.sysrq = 0
+fs.protected_hardlinks = 1
+fs.protected_symlinks = 1
+fs.protected_fifos = 2
+fs.protected_regular = 2
+fs.suid_dumpable = 0
+EOF
+sysctl -q --system
+# core dumps could write a key to disk
+cat > /etc/security/limits.d/60-fly-nocore.conf <<'EOF'
+* hard core 0
+EOF
+mkdir -p /etc/systemd/coredump.conf.d
+printf '[Coredump]\nStorage=none\nProcessSizeMax=0\n' > /etc/systemd/coredump.conf.d/60-fly.conf
+aa-status --enabled                                   # AppArmor must be on (Docker's default profile uses it)
+# protocols, filesystems and devices this server never uses: not loadable at all
+for m in dccp sctp rds tipc usb-storage firewire-core cramfs freevxfs hfs hfsplus jffs2 udf; do
+  echo "install $m /bin/false"
+done > /etc/modprobe.d/60-fly-blacklist.conf
+# new files readable by their group at most, never by everyone
+sed -i 's/^UMASK.*/UMASK\t\t027/' /etc/login.defs
+printf 'Authorized access only. Activity on this system is logged.\n' > /etc/issue
+cp /etc/issue /etc/issue.net
+sed -i 's/^ENABLED=.*/ENABLED="true"/' /etc/default/sysstat 2>/dev/null || true
+systemctl enable --now acct sysstat >/dev/null 2>&1 || true
+
+# ---------------------------------------------------------------- 7. Docker
+step "Docker: user namespaces, no new privileges, bounded logs"
+install -d -m 0755 /etc/docker
+[ -f /etc/docker/daemon.json ] || cat > /etc/docker/daemon.json <<'EOF'
+{
+  "userns-remap": "default",
+  "no-new-privileges": true,
+  "icc": false,
+  "live-restore": true,
+  "userland-proxy": false,
+  "log-driver": "json-file",
+  "log-opts": {"max-size": "50m", "max-file": "5"}
+}
+EOF
+systemctl restart docker
+systemctl daemon-reload
+systemctl enable --now fly-docker-firewall.service
+# with user namespaces, root inside a container is this unprivileged uid on the host
+REMAP_UID="$(awk -F: '$1=="dockremap"{print $2; exit}' /etc/subuid)"
+
+# ---------------------------------------------------------------- 8. layout, keys, updater
+step "fly layout and wallets"
+install -d -m 0750 /srv/fly
+install -d -m 0755 /srv/fly/releases                  # public release files (from HF); the remapped container root reads them
+H_BRAIN=$((REMAP_UID + BRAIN_UID)); H_SIGNER=$((REMAP_UID + SIGNER_UID)); H_FLY=$((REMAP_UID + FLY_GID))
+install -d -m 0750 -o "$H_BRAIN" -g "$H_FLY" /srv/fly/data /srv/fly/logs
+install -d -m 0700 -o "$H_SIGNER" -g "$H_SIGNER" /srv/fly/signer        # the signer's own ledger (policy state)
+install -d -m 0750 -o "$H_SIGNER" -g "$H_FLY" /srv/fly/run              # its socket: the brain may connect, nothing else
 install -d -m 0700 /srv/fly/secrets
 install -d -m 0755 /etc/fly /usr/local/lib/fly
-echo "bryce ${RELEASE_PUBKEY}" > /etc/fly/allowed_signers
+# release signers: valid for the release namespace only, so these keys sign nothing else this box would accept. A re-run
+# without RECOVERY_PUBKEY keeps the recovery signer already installed (so closing SSH or updating the scripts never drops it).
+if [ -z "$RECOVERY_PUBKEY" ] && [ -f /etc/fly/allowed_signers ]; then
+  RECOVERY_PUBKEY="$(awk '$1=="bryce-recovery"{ $1=""; $2=""; sub(/^  */, ""); print; exit }' /etc/fly/allowed_signers)"
+fi
+{
+  echo "bryce namespaces=\"fly-trader-release\" ${RELEASE_PUBKEY}"
+  if [ -n "$RECOVERY_PUBKEY" ]; then echo "bryce-recovery namespaces=\"fly-trader-release\" ${RECOVERY_PUBKEY}"; fi
+} > /etc/fly/allowed_signers
 chmod 0644 /etc/fly/allowed_signers
-# the trading wallet: an ed25519 seed made HERE, never copied off this box in plaintext (the fly's backup job writes an
-# age-encrypted copy for you). fly_trader.chain.keys accepts a base58 32-byte seed.
-if [ ! -e /srv/fly/secrets/bot_key ]; then
-  umask 077
-  openssl genpkey -algorithm ed25519 -out /srv/fly/secrets/bot_key.pem
-  python3 - <<'PY'
-import subprocess
+[ -n "$RECOVERY_PUBKEY" ] || echo "WARNING: no RECOVERY_PUBKEY: losing the release key would mean re-bootstrapping the updater"
+install -m 0755 "$HERE/fly" /usr/local/bin/fly     # sudo fly <command>: fly-trader inside the running container
+# the database password: made here, root-only, handed to both database and brain by compose
+if [ ! -s /srv/fly/db.env ]; then
+  pw="$(openssl rand -hex 24)"
+  ( umask 077; printf 'POSTGRES_PASSWORD=%s\nDATABASE_URL=postgresql://fly:%s@db:5432/fly_trader\n' "$pw" "$pw" > /srv/fly/db.env )
+  unset pw
+fi
+chmod 0600 /srv/fly/db.env
+# two hot keys, each an ed25519 seed made HERE and never copied off this box in plaintext (the signer writes
+# age-encrypted backups for you): the trading key (bot_key: the trading wallet; refills itself from the treasury under
+# L1) and the payout key (payout_key: holds nothing; pays claims from the treasury under L2). Only the signer container
+# mounts them. Their public keys are printed below, once; later: sudo fly signer status.
+make_key() {
+  local name="$1"
+  if [ ! -e "/srv/fly/secrets/$name" ]; then
+    umask 077
+    openssl genpkey -algorithm ed25519 -out "/srv/fly/secrets/$name.pem"
+    python3 - "$name" <<'PY'
+import subprocess, sys
+name = sys.argv[1]
 A = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
 def b58(b):
     n = int.from_bytes(b, "big"); s = ""
     while n: n, r = divmod(n, 58); s = A[r] + s
     return "1" * (len(b) - len(b.lstrip(b"\0"))) + s
-priv = subprocess.run(["openssl", "pkey", "-in", "/srv/fly/secrets/bot_key.pem", "-outform", "DER"], check=True, capture_output=True).stdout[-32:]
-pub = subprocess.run(["openssl", "pkey", "-in", "/srv/fly/secrets/bot_key.pem", "-pubout", "-outform", "DER"], check=True, capture_output=True).stdout[-32:]
-open("/srv/fly/secrets/bot_key", "x").write(b58(priv) + "\n")
-print("vault wallet address:", b58(pub))
+pem = f"/srv/fly/secrets/{name}.pem"
+priv = subprocess.run(["openssl", "pkey", "-in", pem, "-outform", "DER"], check=True, capture_output=True).stdout[-32:]
+pub = subprocess.run(["openssl", "pkey", "-in", pem, "-pubout", "-outform", "DER"], check=True, capture_output=True).stdout[-32:]
+open(f"/srv/fly/secrets/{name}", "x").write(b58(priv) + "\n")
+print(f"{name}: {b58(pub)}")
 PY
-  shred -u /srv/fly/secrets/bot_key.pem
-  chmod 0400 /srv/fly/secrets/bot_key
-fi
-HERE="$(cd "$(dirname "$0")" && pwd)"
+    shred -u "/srv/fly/secrets/$name.pem"
+  fi
+  # readable only by the signer container's user (remapped), not by the brain container or any host account
+  chown "$H_SIGNER:$H_SIGNER" "/srv/fly/secrets/$name"
+  chmod 0400 "/srv/fly/secrets/$name"
+}
+make_key bot_key        # the trading hot key: holds at most the float; refills itself from the Squads treasury (L1)
+make_key payout_key     # the payout key: holds nothing; pays claims from the treasury within its weekly cap (L2)
 install -m 0755 "$HERE/fly_update.py" /usr/local/lib/fly/fly_update.py
+install -m 0755 "$HERE/check-host.sh" /usr/local/lib/fly/check-host.sh
 [ -f /etc/fly/update.json ] || install -m 0600 "$HERE/update.json.example" /etc/fly/update.json
+if [ -n "$EXPECT_MANIFEST" ]; then        # pin the first release: the updater refuses anything else until one is installed
+  python3 - "$EXPECT_MANIFEST" <<'PY'
+import json, re, sys
+pin = sys.argv[1].strip().lower()
+if not re.fullmatch(r"[0-9a-f]{64}", pin):
+    raise SystemExit("EXPECT_MANIFEST must be a sha256 hex digest")
+p = "/etc/fly/update.json"; c = json.load(open(p)); c["expect_manifest_sha256"] = pin
+open(p, "w").write(json.dumps(c, indent=1) + "\n")
+PY
+fi
 [ -f /srv/fly/vault.env ] || install -m 0600 "$HERE/vault.env.example" /srv/fly/vault.env
+[ -f /srv/fly/custody.env ] || install -m 0600 "$HERE/custody.env.example" /srv/fly/custody.env
+[ -f /srv/fly/signer.env ] || install -m 0600 "$HERE/signer.env.example" /srv/fly/signer.env
 install -m 0644 "$HERE/docker-compose.vault.yml" /srv/fly/docker-compose.yml
 install -m 0644 "$HERE/fly-update.service" /etc/systemd/system/fly-update.service
 install -m 0644 "$HERE/fly-update.timer" /etc/systemd/system/fly-update.timer
+install -m 0755 "$HERE/fly_audit_watch.py" /usr/local/lib/fly/fly_audit_watch.py
+install -m 0644 "$HERE/fly-audit-watch.service" /etc/systemd/system/fly-audit-watch.service
+install -m 0644 "$HERE/fly-audit-watch.timer" /etc/systemd/system/fly-audit-watch.timer
+install -m 0644 "$HERE/fly-aide.service" /etc/systemd/system/fly-aide.service
+install -m 0644 "$HERE/fly-aide.timer" /etc/systemd/system/fly-aide.timer
 systemctl daemon-reload
-echo
-echo "Next (see deploy/VAULT.md):"
-echo "  1. edit /srv/fly/vault.env and /etc/fly/update.json (Telegram)"
-echo "  2. systemctl enable --now fly-update.timer   # pulls and builds the first release"
-echo "  3. create the wallet key, then restart:  see VAULT.md 'wallet'"
+systemctl enable --now fly-audit-watch.timer    # a key read by anything but the signer goes to Telegram within a minute
+systemctl enable --now fly-aide.timer           # the daily file-integrity check reports to Telegram (there is no mail here)
+
+# ---------------------------------------------------------------- 9. audit and integrity
+step "audit log: key reads and config changes"
+cat > /etc/audit/rules.d/60-fly.rules <<'EOF'
+-w /srv/fly/secrets -p rwa -k fly_keys
+-w /etc/fly -p wa -k fly_conf
+-w /srv/fly/vault.env -p rwa -k fly_conf
+-w /srv/fly/db.env -p rwa -k fly_conf
+-w /srv/fly/custody.env -p wa -k fly_conf
+-w /srv/fly/signer.env -p rwa -k fly_conf
+-w /srv/fly/signer -p wa -k fly_signer
+-w /usr/local/lib/fly -p wa -k fly_updater
+-w /etc/ssh/sshd_config -p wa -k sshd
+-w /etc/ssh/sshd_config.d -p wa -k sshd
+-w /etc/sudoers -p wa -k sudoers
+-w /etc/sudoers.d -p wa -k sudoers
+-w /etc/docker -p wa -k docker_conf
+-w /etc/systemd/system -p wa -k systemd_units
+-w /etc/passwd -p wa -k identity
+-w /etc/shadow -p wa -k identity
+-w /etc/group -p wa -k identity
+EOF
+augenrules --load >/dev/null
+systemctl enable --now auditd
+
+step "file integrity baseline (AIDE, checked daily; takes a few minutes)"
+echo 'Checksums = sha512' > /etc/aide/aide.conf.d/10_fly_checksums
+cat > /etc/aide/aide.conf.d/90_fly_ignore <<'EOF'
+!/srv/fly/data
+!/srv/fly/logs
+!/srv/fly/releases
+!/var/lib/docker
+!/var/lib/containerd
+EOF
+[ -f /var/lib/aide/aide.db ] || { aideinit -y -f >/dev/null 2>&1 && cp /var/lib/aide/aide.db.new /var/lib/aide/aide.db; }
+
+# ---------------------------------------------------------------- 10. logs
+step "persistent journal"
+mkdir -p /etc/systemd/journald.conf.d
+printf '[Journal]\nStorage=persistent\nSystemMaxUse=2G\n' > /etc/systemd/journald.conf.d/60-fly.conf
+systemctl restart systemd-journald
+
+step "done"
+if [ "$CLOSE_PUBLIC_SSH" = 1 ]; then
+  next="Verify:   sudo /usr/local/lib/fly/check-host.sh   (every control should pass now)"
+else
+  next="From your Mac, BEFORE closing this session:   ssh $ADMIN_USER@fly-vault   (over Tailscale; root login is now off)
+Then run this script again with CLOSE_PUBLIC_SSH=1 to remove public SSH."
+fi
+cat <<EOF
+$next
+Next (docs/vault/RUNBOOK.md, sections 4.3 and 4.4):
+  1. the treasury on https://fly-trader.app/owner.html with your owner wallet (the two keys printed above)
+  2. sudoedit /srv/fly/{custody,signer,vault}.env and /etc/fly/update.json (Telegram)
+  3. sudo systemctl enable --now fly-update.timer   # pulls, verifies and starts the pinned first release
+EOF

deploy/check-host.sh

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+# Verify the vault server's hardening (bootstrap-host.sh). Run as root: sudo /usr/local/lib/fly/check-host.sh
+# Prints PASS/FAIL per control and a Lynis hardening index; exits 1 if any control fails.
+set -uo pipefail
+fail=0
+pass() { printf '  PASS  %s\n' "$1"; }
+bad()  { printf '  FAIL  %s\n' "$1"; fail=1; }
+check() { local what="$1"; shift; if "$@" >/dev/null 2>&1; then pass "$what"; else bad "$what"; fi; }
+sshd_is() { sshd -T 2>/dev/null | grep -qix "$1 $2"; }
+sysctl_is() { [ "$(sysctl -n "$1" 2>/dev/null)" = "$2" ]; }
+
+echo "SSH"
+check "root login off"                  sshd_is permitrootlogin no
+check "passwords off"                   sshd_is passwordauthentication no
+check "keyboard-interactive off"        sshd_is kbdinteractiveauthentication no
+check "only the admin account"          sh -c "sshd -T | grep -qi '^allowusers '"
+check "max 3 auth tries"                sshd_is maxauthtries 3
+check "X11 / agent forwarding off"      sh -c "sshd -T | grep -qix 'x11forwarding no' && sshd -T | grep -qix 'allowagentforwarding no'"
+check "only local TCP forwarding"       sshd_is allowtcpforwarding local
+check "no weak ciphers"                 sh -c "! sshd -T | grep -i '^ciphers' | grep -Eqi 'cbc|3des|arcfour'"
+check "fail2ban guards sshd"            sh -c "fail2ban-client status sshd"
+check "client keys: ed25519/P-256/FIDO only" sh -c "sshd -T | grep -i '^pubkeyacceptedalgorithms' | grep -vqi rsa"
+check "admin not in the docker group"   sh -c "! id -nG \"\$(sshd -T | awk 'tolower(\$1)==\"allowusers\"{print \$2}')\" | grep -qw docker"
+
+echo "Machine"
+root_luks() { lsblk -rno NAME,TYPE -s "$(findmnt -no SOURCE /)" | awk '$2=="crypt"{f=1} f && $2=="part"{print "/dev/"$1; exit}'; }
+check "root filesystem encrypted (LUKS)" sh -c "[ -n \"\$(lsblk -rno TYPE -s \$(findmnt -no SOURCE /) | grep -x crypt)\" ]"
+check "unattended reboots unlock (TPM) or are off" sh -c "grep -q 'Automatic-Reboot \"false\"' /etc/apt/apt.conf.d/52fly-unattended || clevis luks list -d $(root_luks) 2>/dev/null | grep -q tpm2"
+check "IOMMU on (USB4/OCuLink DMA)"      sh -c "[ -n \"\$(ls -A /sys/kernel/iommu_groups)\" ]"
+check "Secure Boot on"                  sh -c "mokutil --sb-state 2>/dev/null | grep -qi 'SecureBoot enabled'"
+check "no Wi-Fi or Bluetooth"           sh -c "! ls /sys/class/net/*/wireless >/dev/null 2>&1 && [ -z \"\$(ls -A /sys/class/bluetooth 2>/dev/null)\" ]"
+
+echo "Tailscale"
+check "tailscaled up"                   sh -c "tailscale status >/dev/null"
+check "Tailnet Lock enabled"            sh -c "tailscale lock status 2>/dev/null | grep -qi 'lock is enabled'"
+check "no public SSH (tailnet only)"    sh -c "! ufw status | grep -E '^22/tcp' | grep -v tailscale0 | grep -q ."
+
+echo "Firewall"
+check "ufw active"                      sh -c "ufw status | grep -q 'Status: active'"
+check "incoming denied by default"      sh -c "ufw status verbose | grep -q 'deny (incoming)'"
+check "outgoing denied by default"      sh -c "ufw status verbose | grep -q 'deny (outgoing)'"
+check "only SSH listens publicly"       sh -c "! ss -Hltn | awk '{print \$4}' | grep -vE '^(127\\.|\\[::1\\]|\\[::ffff:127|100\\.|\\[fd7a:)' | grep -vE ':22\$' | grep -q ."
+check "container traffic restricted"    sh -c "iptables -S DOCKER-USER | grep -q -- '-j DROP'"
+check "console bound to localhost"      sh -c "! ss -Hltn | grep -E ':8501 ' | grep -vqE '127\\.0\\.0\\.1:8501'"
+
+echo "Kernel"
+for kv in net.ipv4.conf.all.accept_redirects=0 net.ipv4.conf.all.send_redirects=0 net.ipv4.conf.all.accept_source_route=0 \
+          net.ipv4.conf.all.rp_filter=1 net.ipv4.tcp_syncookies=1 kernel.kptr_restrict=2 kernel.dmesg_restrict=1 \
+          kernel.unprivileged_bpf_disabled=1 kernel.yama.ptrace_scope=2 kernel.randomize_va_space=2 fs.suid_dumpable=0 \
+          fs.protected_symlinks=1 fs.protected_hardlinks=1; do
+  check "${kv%%=*} = ${kv#*=}"          sysctl_is "${kv%%=*}" "${kv#*=}"
+done
+check "core dumps off"                  sh -c "grep -qs 'Storage=none' /etc/systemd/coredump.conf.d/60-fly.conf"
+check "AppArmor enforcing"              aa-status --enabled
+
+echo "Docker"
+check "user namespace remapping"        sh -c "docker info 2>/dev/null | grep -qi 'userns'"
+check "no-new-privileges by default"    sh -c "grep -q '\"no-new-privileges\": true' /etc/docker/daemon.json"
+check "log size bounded"                sh -c "grep -q 'max-size' /etc/docker/daemon.json"
+check "live restore"                    sh -c "docker info 2>/dev/null | grep -qi 'Live Restore Enabled: true'"
+
+echo "Secrets"
+for k in bot_key payout_key; do
+  f=/srv/fly/secrets/$k
+  check "$k exists, mode 400"           sh -c "[ -f $f ] && [ \"\$(stat -c %a $f)\" = 400 ]"
+  check "$k not owned by a login user"  sh -c "[ \"\$(stat -c %U $f)\" != root ] || true; ! getent passwd \"\$(stat -c %U $f)\" | grep -qE ':/bin/(ba)?sh\$'"
+done
+check "secrets dir only root"           sh -c "[ \"\$(stat -c %a /srv/fly/secrets)\" = 700 ]"
+check "signer up (it refuses equal keys)" sh -c "docker inspect fly-fly-signer-1 --format '{{.State.Health.Status}}' | grep -q healthy"
+check "release signer pinned"           sh -c "[ -s /etc/fly/allowed_signers ] && [ \"\$(stat -c %U /etc/fly/allowed_signers)\" = root ]"
+check "updater owned by root"           sh -c "[ \"\$(stat -c %U /usr/local/lib/fly/fly_update.py)\" = root ] && ! [ -w /usr/local/lib/fly/fly_update.py -a \"\$(stat -c %a /usr/local/lib/fly/fly_update.py)\" != 755 ]"
+for e in vault custody signer db; do
+  check "$e.env mode 600"                sh -c "[ \"\$(stat -c %a /srv/fly/$e.env)\" = 600 ]"
+done
+check "no default database password"    sh -c "! grep -qE 'POSTGRES_PASSWORD(:|=) *fly\$' /srv/fly/docker-compose.yml /srv/fly/db.env"
+check "release signers namespaced"      sh -c "! grep -v 'namespaces=\"fly-trader-release\"' /etc/fly/allowed_signers | grep -q ."
+check "first release pinned (no TOFU)"  sh -c "grep -Eq '\"expect_manifest_sha256\": *\"[0-9a-f]{64}\"' /etc/fly/update.json || [ -s /srv/fly/state.json ]"
+
+echo "Key isolation"
+check "keys mounted into the signer only" sh -c "! docker inspect fly-fly-1 --format '{{range .Mounts}}{{.Source}} {{end}}' | grep -q /srv/fly/secrets"
+check "signer has the keys"             sh -c "docker inspect fly-fly-signer-1 --format '{{range .Mounts}}{{.Source}} {{end}}' | grep -q /srv/fly/secrets/bot_key"
+check "signer filesystem read-only"     sh -c "docker inspect fly-fly-signer-1 --format '{{.HostConfig.ReadonlyRootfs}}' | grep -q true"
+check "brain runs as uid 10001"         sh -c "docker inspect fly-fly-1 --format '{{.Config.User}}' | grep -q '^10001'"
+check "database has no route out"       sh -c "docker network inspect fly_internal --format '{{.Internal}}' | grep -q true"
+
+echo "Monitoring"
+check "auditd running"                  systemctl is-active auditd
+check "key reads audited"               sh -c "auditctl -l | grep -q fly_keys"
+check "key-read watcher running"        systemctl is-active fly-audit-watch.timer
+check "daily AIDE report to Telegram"   systemctl is-active fly-aide.timer
+check "AIDE baseline present"           test -f /var/lib/aide/aide.db
+check "journal persistent"              test -d /var/log/journal
+check "automatic security updates"      sh -c "systemctl is-enabled unattended-upgrades && grep -q 'Automatic-Reboot' /etc/apt/apt.conf.d/52fly-unattended"
+check "clock synchronised"              sh -c "timedatectl show -p NTPSynchronized --value | grep -q yes"
+check "no snapd"                        sh -c "! dpkg -l snapd 2>/dev/null | grep -q '^ii'"
+
+echo "Lynis"
+if command -v lynis >/dev/null; then
+  lynis audit system --quick --no-colors >/tmp/lynis.out 2>&1
+  printf '  hardening index: %s\n' "$(grep -o 'Hardening index : [0-9]*' /tmp/lynis.out | grep -o '[0-9]*$' || echo '?')"
+  grep -E '^\s+\* ' /var/log/lynis-report.dat >/dev/null 2>&1 || true
+fi
+
+echo
+[ "$fail" = 0 ] && echo "all controls pass" || echo "SOME CONTROLS FAILED"
+exit $fail

deploy/custody.env.example

@@ -0,0 +1,26 @@
+# /srv/fly/custody.env (mode 600): the treasury setup and the caps, read by BOTH the signer and the brain.
+# Nothing secret: all of it is visible on chain or harmless. Comments on their own lines only.
+# Create the multisig and its limits on https://fly-trader.app/owner.html with your owner wallet (docs/vault/RUNBOOK.md
+# section 4.3); the page prints the three lines below. After changing any value: sudo python3 /usr/local/lib/fly/fly_update.py restart
+
+# the Squads v4 multisig whose vault 0 is the treasury (members: your owner wallets only; never a server key)
+VAULT_MULTISIG=
+# L1: SOL, daily, member = the trading key, the ONLY destination = the trading wallet. A new limit has a new address.
+VAULT_LIMIT_TRADING=
+# L2: SOL, weekly, member = the payout key, any destination (claims)
+VAULT_LIMIT_PAYOUT=
+# the most SOL the trading wallet keeps (positions are sized on the whole book, spent from this float); also the largest
+# single top-up the signer signs. Moves smaller than TOPUP_MIN_SOL are skipped.
+TREASURY_FLOAT_SOL=2.0
+TOPUP_MIN_SOL=0.1
+# the fixed size for a model without a sizing table (sizing is otherwise MAX_POSITION_FRACTION of the book); must be > 0
+MAX_POSITION_SOL=0.5
+# the signer refuses any buy larger than this (a bound on a compromised brain, not sizing)
+SIGNER_MAX_BUY_SOL=0.6
+# the signer's own limits: SOL bought per day, swaps per minute, priority fee per swap, the worst value a swap may return
+SIGNER_DAILY_BUY_SOL=10
+SIGNER_SWAPS_PER_MIN=6
+SIGNER_MAX_PRIORITY_SOL=0.005
+SIGNER_MIN_VALUE_RATIO=0.6
+# your age1... public key (NOT the release key): the signer encrypts the two hot keys to it, the brain the nightly ledger
+VAULT_BACKUP_RECIPIENT=

deploy/docker-compose.vault.yml

@@ -1,47 +1,91 @@
 # The hosted $FLY vault fly (docs/vault/SPEC.md). Installed by bootstrap-host.sh as /srv/fly/docker-compose.yml and
-# driven by the updater (fly_update.py): FLY_RELEASE picks the image tag it built from a verified release.
-# Nothing listens on a public interface: the console is on 127.0.0.1 (reach it with an SSH tunnel) and the fly only
-# makes outbound connections (Solana RPC, Jupiter, pumpapi, Robinhood Chain RPC, the site's relay, Telegram).
+# driven by the updater (fly_update.py): FLY_RELEASE picks the image tags it built from a verified release.
+# Nothing listens on a public interface: the console is on 127.0.0.1 (reach it with an SSH tunnel over Tailscale) and
+# the containers only make outbound connections.
+#
+#   fly-signer  the ONLY container that can read the two hot keys; it checks and signs, over a Unix socket in
+#               /srv/fly/run (a directory only it and the brain's group can enter). Read-only filesystem, no capabilities.
+#   fly         the brain: engine, console, vault worker, data feeds. No key is mounted into it.
+#   db          Postgres on an internal network (no route out), its password generated by bootstrap-host.sh.
+#
+# Settings: /srv/fly/custody.env (public: the treasury multisig, its limits, the float and caps; read by both),
+# /srv/fly/signer.env (the signer's own RPC URL), /srv/fly/vault.env (the brain's API keys, relay, Telegram, backups),
+# /srv/fly/db.env (the database password). All root-only (0600) on the host.
 services:
   db:
-    image: postgres:17
+    image: postgres:17@sha256:d74eeac9a635390a49bc21bd49fccd973de707e2a53a76ac49b552b8712ec46f
+    env_file: /srv/fly/db.env
     environment:
       POSTGRES_USER: fly
-      POSTGRES_PASSWORD: fly
       POSTGRES_DB: fly_trader
     volumes:
       - pgdata:/var/lib/postgresql/data
+    networks: [internal]
     healthcheck:
       test: ["CMD-SHELL", "pg_isready -U fly -d fly_trader"]
       interval: 5s
       timeout: 3s
       retries: 30
     restart: unless-stopped
+    security_opt: ["no-new-privileges:true"]
+    logging: {driver: json-file, options: {max-size: "20m", max-file: "5"}}
+
+  fly-signer:
+    image: fly-signer:${FLY_RELEASE:-none}
+    env_file: [/srv/fly/custody.env, /srv/fly/signer.env]
+    environment:
+      BOT_PRIVATE_KEY_FILE: /run/secrets/bot_key
+      PAYOUT_PRIVATE_KEY_FILE: /run/secrets/payout_key
+      SIGNER_SOCKET: /run/fly-signer/sock
+      SIGNER_DB: /srv/signer/ledger.sqlite
+    volumes:
+      - /srv/fly/secrets/bot_key:/run/secrets/bot_key:ro
+      - /srv/fly/secrets/payout_key:/run/secrets/payout_key:ro
+      - /srv/fly/signer:/srv/signer
+      - /srv/fly/run:/run/fly-signer
+    networks: [egress]                     # its own RPC and Jupiter's price API; nothing reaches in
+    read_only: true
+    tmpfs: [/tmp]
+    restart: unless-stopped
+    security_opt: ["no-new-privileges:true"]
+    cap_drop: [ALL]
+    mem_limit: 512m
+    pids_limit: 64
     logging: {driver: json-file, options: {max-size: "20m", max-file: "5"}}
+
   fly:
-    image: fly-trader:${FLY_RELEASE:?set by the updater}
-    env_file: /srv/fly/vault.env
+    image: fly-trader:${FLY_RELEASE:-none}
+    env_file: [/srv/fly/custody.env, /srv/fly/vault.env, /srv/fly/db.env]
     environment:
-      DATABASE_URL: postgresql://fly:fly@db:5432/fly_trader
       DATA_DIR: /app/data
       LOG_DIR: /app/logs
-      BOT_PRIVATE_KEY_FILE: /run/secrets/bot_key
+      SIGNER_SOCKET: /run/fly-signer/sock
       VAULT_ENABLED: "1"
+      AUTO_UPDATE: "0"                     # releases come through the host updater (signed, 24 h hold on code), never from inside
     volumes:
       - /srv/fly/data:/app/data
       - /srv/fly/logs:/app/logs
-      - /srv/fly/secrets/bot_key:/run/secrets/bot_key:ro
+      - /srv/fly/run:/run/fly-signer
       - ${FLY_RELEASES:-/srv/fly/releases}:/releases:ro
+    networks: [internal, egress]
     ports:
       - "127.0.0.1:8501:8501"
     depends_on:
       db:
         condition: service_healthy
+      fly-signer:
+        condition: service_healthy
     restart: unless-stopped
     stop_grace_period: 150s
     security_opt: ["no-new-privileges:true"]
     cap_drop: [ALL]
-    mem_limit: 14g
+    mem_limit: 48g                         # a dedicated 128 GB box; lower it on a smaller one (16 GB: 14g)
     logging: {driver: json-file, options: {max-size: "50m", max-file: "5"}}
+
+networks:
+  internal:
+    internal: true                          # the database has no route to anything but its two clients
+  egress: {}
+
 volumes:
   pgdata:

deploy/fly

@@ -0,0 +1,9 @@
+#!/bin/sh
+# Run a fly-trader command inside the running brain container, e.g.  sudo fly vault status
+#   sudo fly signer <cmd>   runs python -m fly_trader.signer <cmd> in the signer container (status, clear-panic)
+set -e
+if [ "$1" = "signer" ]; then
+  shift
+  exec docker exec -i fly-fly-signer-1 python -m fly_trader.signer "$@"
+fi
+exec docker exec -i fly-fly-1 fly-trader "$@"

deploy/fly-aide.service

@@ -0,0 +1,8 @@
+[Unit]
+Description=fly-trader vault: daily file-integrity check (AIDE), findings to Telegram
+
+[Service]
+Type=oneshot
+Nice=10
+ExecStart=/usr/bin/python3 /usr/local/lib/fly/fly_audit_watch.py aide
+TimeoutStartSec=3600

deploy/fly-aide.timer

@@ -0,0 +1,9 @@
+[Unit]
+Description=Run the AIDE check daily
+
+[Timer]
+OnCalendar=*-*-* 05:30:00 UTC
+Persistent=true
+
+[Install]
+WantedBy=timers.target

deploy/fly-audit-watch.service

@@ -0,0 +1,8 @@
+[Unit]
+Description=fly-trader vault: alert when anything but the signer reads a wallet key
+After=auditd.service
+
+[Service]
+Type=oneshot
+ExecStart=/usr/bin/python3 /usr/local/lib/fly/fly_audit_watch.py run
+TimeoutStartSec=120

deploy/fly-audit-watch.timer

@@ -0,0 +1,10 @@
+[Unit]
+Description=Check the key-read audit log every minute
+
+[Timer]
+OnBootSec=1min
+OnUnitActiveSec=1min
+AccuracySec=5s
+
+[Install]
+WantedBy=timers.target

deploy/fly_audit_watch.py

@@ -0,0 +1,109 @@
+#!/usr/bin/env python3
+"""Tell the operator when anything but the signer reads a wallet key (runs on the HOST, root, every minute).
+
+auditd logs every access to /srv/fly/secrets (key ``fly_keys``, bootstrap-host.sh). The signer container's Python is
+the only reader there should ever be (plus AIDE's daily integrity scan); a read by anything else -- a shell, cat, a
+process in the brain container -- is the earliest sign of a compromise, so it goes to Telegram at once, with the
+program, user and time. ``ausearch --checkpoint`` makes each event reported once.
+
+    fly_audit_watch.py run            (the systemd timer, every minute)
+    fly_audit_watch.py aide           (fly-aide.timer, daily: AIDE's integrity check; changes go to Telegram, since
+                                       this host has no mail. After reviewing expected changes: sudo aide --update and
+                                       sudo cp /var/lib/aide/aide.db.new /var/lib/aide/aide.db)
+    fly_audit_watch.py test           (send a test message)
+"""
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+import sys
+import urllib.request
+from pathlib import Path
+
+CONF = Path("/etc/fly/update.json")                  # the updater's Telegram settings
+CHECKPOINT = Path("/var/lib/fly/audit.checkpoint")
+SIGNER_EXE = {"/usr/local/bin/python3.13", "/usr/local/bin/python3"}   # the signer image's interpreter
+ALLOWED_EXE = {"/usr/bin/aide", "/usr/sbin/aide"}                        # AIDE hashes every file daily
+SIGNER_UID_OFFSET = 10002                            # the signer container's user; on the host: dockremap base + this
+
+FIELD = re.compile(r'(\w+)=("[^"]*"|\S+)')
+
+
+def remap_base() -> int:
+    for line in Path("/etc/subuid").read_text().splitlines():
+        name, start, _ = line.split(":")
+        if name == "dockremap":
+            return int(start)
+    return -1
+
+
+def events(raw: str) -> list[dict]:
+    """SYSCALL records of ``ausearch --raw`` output as dicts (pure)."""
+    out = []
+    for line in raw.splitlines():
+        if not line.startswith("type=SYSCALL"):
+            continue
+        out.append({k: v.strip('"') for k, v in FIELD.findall(line)})
+    return out
+
+
+def suspicious(evs: list[dict], signer_uid: int) -> list[dict]:
+    """Reads that are not the signer's interpreter as the signer's user, nor AIDE (pure)."""
+    bad = []
+    for e in evs:
+        exe, uid = e.get("exe", ""), int(e.get("uid", "-1")) if e.get("uid", "").lstrip("-").isdigit() else -1
+        if exe in SIGNER_EXE and uid == signer_uid:
+            continue
+        if exe in ALLOWED_EXE and uid == 0:
+            continue
+        bad.append(e)
+    return bad
+
+
+def alert(text: str) -> None:
+    c = json.loads(CONF.read_text()) if CONF.exists() else {}
+    tok, chat = c.get("telegram_bot_token"), c.get("telegram_chat_id")
+    print("ALERT", text, flush=True)
+    if tok and chat:
+        body = json.dumps({"chat_id": chat, "text": "[fly host] " + text}).encode()
+        urllib.request.urlopen(urllib.request.Request(f"https://api.telegram.org/bot{tok}/sendMessage", data=body,
+                                                      headers={"Content-Type": "application/json"}), timeout=10)
+
+
+def run() -> int:
+    CHECKPOINT.parent.mkdir(parents=True, exist_ok=True)
+    r = subprocess.run(["ausearch", "-k", "fly_keys", "--raw", "--checkpoint", str(CHECKPOINT), "--start", "checkpoint"],
+                       capture_output=True, text=True)
+    if r.returncode not in (0, 1):                   # 1: no matches; 10/11/12: checkpoint problems -> start fresh next run
+        CHECKPOINT.unlink(missing_ok=True)
+        return 0
+    bad = suspicious(events(r.stdout), remap_base() + SIGNER_UID_OFFSET)
+    if bad:
+        lines = [f"{e.get('exe')} (uid {e.get('uid')}, comm {e.get('comm')}, syscall {e.get('syscall')})" for e in bad[:10]]
+        alert(f"WALLET KEY READ by something other than the signer ({len(bad)} event(s)):\n" + "\n".join(lines)
+              + "\nIf this was not you: revoke L1 and L2 in the owner wallet now, then investigate.")
+    return len(bad)
+
+
+def aide() -> int:
+    """AIDE's exit code: 0 no change, 1-7 added/removed/changed files, >= 14 an error."""
+    r = subprocess.run(["aide", "--check", "--config", "/etc/aide/aide.conf"], capture_output=True, text=True)
+    if r.returncode == 0:
+        return 0
+    summary = [l for l in r.stdout.splitlines() if l.strip() and (l.startswith(("Added", "Removed", "Changed", "f", "d", "l"))
+                                                                   or "entries" in l)][:25]
+    what = "an ERROR" if r.returncode >= 14 else "file changes"
+    alert(f"AIDE found {what} (exit {r.returncode}). If you did not make them (a release, apt upgrades), investigate:\n"
+          + "\n".join(summary) + "\nFull report: sudo aide --check")
+    return r.returncode
+
+
+if __name__ == "__main__":
+    cmd = sys.argv[1] if len(sys.argv) > 1 else "run"
+    if cmd == "test":
+        alert("audit watch test message")
+    elif cmd == "aide":
+        aide()
+    else:
+        run()

deploy/fly_update.py

@@ -3,7 +3,8 @@
 
 Runs on the HOST (root, systemd timer, standard library only), never inside the container, because it rebuilds and
 restarts the container. Everything it trusts comes from files on this host that no release can change:
-``/etc/fly/allowed_signers`` (Bryce's release key) and ``/etc/fly/update.json``.
+``/etc/fly/allowed_signers`` (Bryce's release keys, restricted to the release namespace) and ``/etc/fly/update.json``
+(which also pins the very first release by its manifest hash: no trust on first use).
 
 One round:
  1. poll the HF model repo's commit sha; nothing to do if it is the installed one
@@ -12,13 +13,19 @@ One round:
     no forks)
  3. download exactly the listed paths (strict path check), verify size + sha256 of each, into a fresh directory
  4. compare file classes with the installed release:
-      only model/seed  -> ``docker compose exec fly fly-trader apply-release /releases/<seq>`` (hot swap)
-      code             -> wait for ``ready-for-restart``, build ``fly-trader:<seq>`` from that directory, recreate,
-                          wait for healthy, else roll back to the previous tag
-      infra            -> stop and ask: ``fly_update.py approve <seq>`` (compose/Dockerfile/entrypoint can grant
-                          host access, so a human looks first)
-
-    fly_update.py run | approve <seq> | status | verify <dir>
+      only model/seed  -> ``docker compose exec fly fly-trader apply-release /releases/<seq>`` (hot swap; models
+                          cannot run code, fly_trader/train/model_io.py); unhealthy after it -> the previous release's
+                          models are re-applied
+      code             -> held for ``code_delay_s`` (24 h) with a Telegram notice, so a stolen signing key cannot ship
+                          code faster than Bryce can ``veto`` it; ``approve`` applies it at once. Then: wait for
+                          ``ready-for-restart``, build ``fly-trader:<seq>`` from that directory, recreate, wait for
+                          healthy, else roll back to the previous tag and compose file
+      infra            -> held until ``approve`` (compose/Dockerfile/entrypoint can grant host access, so a human
+                          looks first)
+
+    fly_update.py run | approve <seq> | veto <seq> | status | restart | verify <dir> <allowed_signers> [principal ...]
+
+``restart`` recreates the containers on the installed release (after you edit /srv/fly/*.env).
 """
 from __future__ import annotations
 
@@ -37,13 +44,17 @@ from pathlib import Path
 CONF = Path(os.environ.get("FLY_UPDATE_CONF", "/etc/fly/update.json"))
 PATH_RE = re.compile(r"^(?!.*\.\.)(?!/)[A-Za-z0-9_.\-/]+$")
 INFRA = ("Dockerfile", "docker-compose.yml", "docker-compose.cuda.yml", ".dockerignore", "docker/", "deploy/")
+# what models/ and seed/ may hold: nothing a loader could execute (fly_trader/train/model_io.SAFE_SUFFIXES)
+MODEL_SUFFIXES = {".pt", ".skops", ".npz", ".json", ".bin", ".parquet", ".txt", ".sha256", ""}
+SEED_SUFFIXES = {".json", ".sql"}
 
 
 def conf() -> dict:
     c = json.loads(CONF.read_text())
     c.setdefault("repo", "bryceweiner/fly-trader")
     c.setdefault("allowed_signers", "/etc/fly/allowed_signers")
-    c.setdefault("principal", "bryce")
+    c.setdefault("principals", [c.get("principal") or "bryce", "bryce-recovery"])
+    c.setdefault("code_delay_s", 86400)
     c.setdefault("namespace", "fly-trader-release")
     c.setdefault("root", "/srv/fly")
     c.setdefault("project", "fly")
@@ -95,13 +106,19 @@ def classify(path: str) -> str:
     return "code"
 
 
-def verify_signature(c: dict, manifest: bytes, sig: bytes) -> None:
+def verify_signature(c: dict, manifest: bytes, sig: bytes) -> str:
+    """The principal whose key signed ``manifest`` (any of ``principals``), else SystemExit."""
+    principals = c.get("principals") or [c["principal"]]
+    err = ""
     with tempfile.TemporaryDirectory() as d:
         sp = Path(d) / "release.json.sig"; sp.write_bytes(sig)
-        r = subprocess.run(["ssh-keygen", "-Y", "verify", "-f", c["allowed_signers"], "-I", c["principal"], "-n", c["namespace"], "-s", str(sp)],
-                           input=manifest, capture_output=True)
-    if r.returncode != 0:
-        raise SystemExit(f"release signature does NOT verify: {r.stderr.decode(errors='replace').strip()[:300]}")
+        for who in principals:
+            r = subprocess.run(["ssh-keygen", "-Y", "verify", "-f", c["allowed_signers"], "-I", who, "-n", c["namespace"], "-s", str(sp)],
+                               input=manifest, capture_output=True)
+            if r.returncode == 0:
+                return who
+            err = r.stderr.decode(errors="replace").strip()
+    raise SystemExit(f"release signature does NOT verify: {err[:300]}")
 
 
 def check_manifest(m: dict) -> None:
@@ -113,6 +130,8 @@ def check_manifest(m: dict) -> None:
             raise SystemExit(f"refusing path {p!r}")
         if f.get("class") != classify(p):
             raise SystemExit(f"{p}: class {f.get('class')} does not match {classify(p)}")
+        if f["class"] == "model" and Path(p).suffix not in MODEL_SUFFIXES or f["class"] == "seed" and Path(p).suffix not in SEED_SUFFIXES:
+            raise SystemExit(f"{p}: file type not allowed in {f['class']}/ (a model or seed must not be able to run code)")
         if not re.fullmatch(r"[0-9a-f]{64}", f.get("sha256", "")) or not isinstance(f.get("size"), int):
             raise SystemExit(f"{p}: bad hash or size")
 
@@ -146,19 +165,27 @@ def save_state(c: dict, st: dict) -> None:
 
 
 def compose(c: dict, *args: str, check: bool = True, env: dict | None = None) -> subprocess.CompletedProcess:
-    e = {**os.environ, **(env or {})}
+    """docker compose on the installed release (FLY_RELEASE = the image tag this host runs, unless ``env`` says otherwise)."""
+    installed_tag = load_state(c).get("image")
+    e = {**os.environ, "FLY_RELEASE": str(installed_tag) if installed_tag is not None else "none", **(env or {})}
     return subprocess.run(["docker", "compose", "-p", c["project"], "-f", str(Path(c["root"]) / "docker-compose.yml"), *args],
                           cwd=c["root"], check=check, capture_output=True, text=True, env=e)
 
 
-def fetch(c: dict, sha: str) -> tuple[dict, Path, bytes]:
+def fetch(c: dict, sha: str) -> tuple[dict, Path, bytes, str]:
     base = f"https://huggingface.co/{c['repo']}/resolve/{sha}/"
     raw = http(base + "release.json"); sig = http(base + "release.json.sig")
-    verify_signature(c, raw, sig)
+    who = verify_signature(c, raw, sig)
     m = json.loads(raw)
     check_manifest(m)
     dest = Path(c["root"]) / "releases" / str(m["seq"])
     if dest.exists():
+        try:                                     # already downloaded (a held or retried release): re-verify, reuse
+            if (dest / "release.json").read_bytes() == raw:
+                verify_dir(dest, m)
+                return m, dest, raw, who
+        except (SystemExit, OSError):
+            pass
         shutil.rmtree(dest)
     part = dest.with_name(dest.name + ".part")
     if part.exists():
@@ -170,7 +197,7 @@ def fetch(c: dict, sha: str) -> tuple[dict, Path, bytes]:
     (part / "release.json").write_bytes(raw); (part / "release.json.sig").write_bytes(sig)
     verify_dir(part, m)
     part.rename(dest)
-    return m, dest, raw
+    return m, dest, raw, who
 
 
 def installed_manifest(c: dict, st: dict) -> dict | None:
@@ -212,82 +239,155 @@ def healthy(c: dict, limit_s: int = 900) -> bool:
     return False
 
 
-def deploy_code(c: dict, st: dict, m: dict, d: Path, infra: bool) -> bool:
+def deploy_code(c: dict, st: dict, m: dict, d: Path, infra: bool) -> str:
+    """'ok', 'busy' (not ready for a restart: retried next round) or 'failed' (rolled back)."""
     tag = f"fly-trader:{m['seq']}"
-    subprocess.run(["docker", "build", "-t", tag, str(d)], check=True, capture_output=True)
-    if infra:                                   # approved: the release's compose file becomes the running one
-        shutil.copy2(d / "deploy" / "docker-compose.vault.yml", Path(c["root"]) / "docker-compose.yml")
-    if not wait_ready(c):
+    root = Path(c["root"]); live, backup = root / "docker-compose.yml", root / "docker-compose.yml.prev"
+    try:                                        # the brain (default stage) and the key-holding signer, same release
+        subprocess.run(["docker", "build", "-t", tag, str(d)], check=True, capture_output=True)
+        subprocess.run(["docker", "build", "--target", "signer", "-t", f"fly-signer:{m['seq']}", str(d)], check=True, capture_output=True)
+    except subprocess.CalledProcessError as e:
+        alert(c, f"release {m['seq']}: image build failed: {(e.stderr or b'').decode(errors='replace')[-300:]}")
+        return "failed"
+    if st.get("image") is not None and not wait_ready(c):     # the first install has nothing running to wait for
         alert(c, f"release {m['seq']}: the fly never became ready for a restart (orders/claims/settlement in flight); will retry")
-        return False
+        return "busy"
+    if infra:                                   # approved: the release's compose file becomes the running one
+        shutil.copy2(live, backup)
+        shutil.copy2(d / "deploy" / "docker-compose.vault.yml", live)
     prev = st.get("image")
-    compose(c, "up", "-d", env={"FLY_RELEASE": str(m["seq"]), "FLY_RELEASES": str(Path(c["root"]) / "releases")})
+    env = {"FLY_RELEASES": str(root / "releases")}
+    compose(c, "up", "-d", check=False, env={**env, "FLY_RELEASE": str(m["seq"])})
     if healthy(c):
-        return True
+        return "ok"
     alert(c, f"release {m['seq']} did not become healthy; rolling back to {prev}")
+    if infra and backup.exists():
+        shutil.copy2(backup, live)
     if prev:
-        compose(c, "up", "-d", env={"FLY_RELEASE": str(prev), "FLY_RELEASES": str(Path(c["root"]) / "releases")})
-    return False
+        compose(c, "up", "-d", check=False, env={**env, "FLY_RELEASE": str(prev)})
+    return "failed"
+
 
+def _when(ts: float) -> str:
+    return time.strftime("%Y-%m-%d %H:%M UTC", time.gmtime(ts))
 
-def apply(c: dict, st: dict, m: dict, d: Path, raw: bytes, hf_sha: str, approved: bool = False) -> None:
+
+def apply(c: dict, st: dict, m: dict, d: Path, raw: bytes, hf_sha: str, approved: bool = False, who: str = "?",
+          now: float | None = None) -> None:
+    now = time.time() if now is None else now
+    msha = hashlib.sha256(raw).hexdigest()
     old = installed_manifest(c, st)
-    if old is not None and m["seq"] <= old["seq"]:
-        raise SystemExit(f"release seq {m['seq']} is not newer than installed {old['seq']} (rollback refused)")
-    if old is not None and m.get("prev_sha256") != st.get("manifest_sha256"):
-        raise SystemExit("release does not chain from the installed one (prev_sha256 mismatch)")
+    if old is None:                              # the first release is pinned by hand at bootstrap (no TOFU)
+        pin = c.get("expect_manifest_sha256")
+        if not pin:
+            raise SystemExit("no release installed and update.json pins none (expect_manifest_sha256): refusing to trust the first one seen")
+        if msha != pin:
+            raise SystemExit(f"first release's manifest {msha[:12]} is not the pinned {str(pin)[:12]}")
+    else:
+        if m["seq"] <= old["seq"]:
+            raise SystemExit(f"release seq {m['seq']} is not newer than installed {old['seq']} (rollback refused)")
+        pend = st.get("pending") or {}
+        chain = {st.get("manifest_sha256"), pend.get("manifest_sha256"), *(st.get("vetoed") or [])} - {None}
+        if m.get("prev_sha256") not in chain:
+            raise SystemExit("release does not chain from the installed one (prev_sha256 mismatch)")
     classes = changed_classes(old, m)
-    if "infra" in classes and not approved:
-        st["pending"] = {"seq": m["seq"], "hf_sha": hf_sha}
+    if old is not None and classes & {"code", "infra"}:
+        pend = st.get("pending") or {}
+        if pend.get("manifest_sha256") != msha:  # newly seen: the delay starts now (a replaced pending one restarts it)
+            pend = {"seq": m["seq"], "hf_sha": hf_sha, "manifest_sha256": msha, "classes": sorted(classes), "signer": who,
+                    "first_seen": now, "due_at": now + float(c.get("code_delay_s", 86400)), "approved": False}
+            st["pending"] = pend
+            what = ("changes Docker/compose/entrypoint files: review it, then `sudo python3 /usr/local/lib/fly/fly_update.py approve "
+                    f"{m['seq']}`" if "infra" in classes else
+                    f"changes code: it applies at {_when(pend['due_at'])} unless you run `sudo python3 /usr/local/lib/fly/fly_update.py veto "
+                    f"{m['seq']}` (`approve {m['seq']}` applies it now)")
+            alert(c, f"release {m['seq']} signed by {who} {what}")
+        if approved:
+            pend["approved"] = True
         save_state(c, st)
-        alert(c, f"release {m['seq']} changes Docker/compose/entrypoint files: review, then run `fly_update.py approve {m['seq']}`")
-        return
+        if "infra" in classes and not pend["approved"]:
+            return
+        if not (pend["approved"] or now >= pend["due_at"]):
+            return
     if classes & {"code", "infra"} or st.get("image") is None:
-        if not deploy_code(c, st, m, d, "infra" in classes):
+        res = deploy_code(c, st, m, d, "infra" in classes)
+        if res == "busy":
             return
+        if res == "failed":
+            raise SystemExit("the new image did not come up healthy (rolled back)")
         st["image"] = m["seq"]
     elif classes & {"model", "seed"}:
         r = compose(c, "exec", "-T", "fly", "fly-trader", "apply-release", f"/releases/{m['seq']}", check=False)
         if r.returncode != 0:
-            alert(c, f"release {m['seq']}: apply-release failed: {(r.stderr or r.stdout)[-300:]}")
-            return
-    st.update({"seq": m["seq"], "manifest_sha256": hashlib.sha256(raw).hexdigest(), "hf_sha": hf_sha, "pending": None})
+            raise SystemExit(f"apply-release failed: {(r.stderr or r.stdout)[-300:]}")
+        if not healthy(c, 300):
+            if old is not None:
+                compose(c, "exec", "-T", "fly", "fly-trader", "apply-release", f"/releases/{old['seq']}", check=False)
+            raise SystemExit("unhealthy after the model release; the previous release's models were re-applied")
+    st.update({"seq": m["seq"], "manifest_sha256": msha, "hf_sha": hf_sha, "pending": None})
     save_state(c, st)
-    alert(c, f"release {m['seq']} applied ({', '.join(sorted(classes))})")
+    alert(c, f"release {m['seq']} applied ({', '.join(sorted(classes))}), signed by {who}")
 
 
-def run(approve_seq: int | None = None) -> None:
+def run(approve_seq: int | None = None, now: float | None = None) -> None:
     c = conf()
+    now = time.time() if now is None else now
     Path(c["root"], "releases").mkdir(parents=True, exist_ok=True)
     st = load_state(c)
-    info = json.loads(http(f"https://huggingface.co/api/models/{c['repo']}"))
-    sha = info["sha"]
+    pend = st.get("pending") or {}
     if approve_seq is not None:
-        pend = st.get("pending") or {}
         if pend.get("seq") != approve_seq:
             raise SystemExit(f"no pending release {approve_seq}")
         sha = pend["hf_sha"]
-    elif sha in (st.get("hf_sha"), st.get("hf_sha_rejected")) or (st.get("pending") or {}).get("hf_sha") == sha:
-        return                                   # installed, already rejected (alerted once), or waiting for approval
+    else:
+        head = json.loads(http(f"https://huggingface.co/api/models/{c['repo']}"))["sha"]
+        if head not in (st.get("hf_sha"), st.get("hf_sha_rejected"), pend.get("hf_sha")):
+            sha = head                           # a new release
+        elif pend and (pend.get("approved") or now >= pend.get("due_at", float("inf"))):
+            sha = pend["hf_sha"]                 # a held release whose time came (or a retry after 'busy')
+        else:
+            return                               # installed, rejected (alerted once), or still held
     try:
-        m, d, raw = fetch(c, sha)
-        apply(c, st, m, d, raw, sha, approved=approve_seq is not None)
+        m, d, raw, who = fetch(c, sha)
+        apply(c, st, m, d, raw, sha, approved=approve_seq is not None, who=who, now=now)
     except SystemExit as e:
+        st = load_state(c)
+        if (st.get("pending") or {}).get("hf_sha") == sha:
+            st["pending"] = None
         st["hf_sha_rejected"] = sha; save_state(c, st)
         alert(c, f"release at {sha[:10]} rejected: {e}")
         raise
 
 
+def veto(seq: int) -> None:
+    c = conf(); st = load_state(c); pend = st.get("pending") or {}
+    if pend.get("seq") != seq:
+        raise SystemExit(f"no pending release {seq}")
+    st["vetoed"] = [*(st.get("vetoed") or []), pend["manifest_sha256"]][-20:]
+    st["hf_sha_rejected"] = pend["hf_sha"]; st["pending"] = None
+    save_state(c, st)
+    alert(c, f"release {seq} VETOED: it will never apply. If you did not publish it, your release key is compromised: "
+             "remove it from /etc/fly/allowed_signers and rotate.")
+
+
 def main(argv: list[str]) -> None:
     cmd = argv[1] if len(argv) > 1 else "run"
     if cmd == "run":
         run()
     elif cmd == "approve":
         run(int(argv[2]))
+    elif cmd == "veto":
+        veto(int(argv[2]))
+    elif cmd == "restart":
+        c = conf()
+        if load_state(c).get("image") is None:
+            raise SystemExit("nothing installed yet")
+        r = compose(c, "up", "-d", "--force-recreate", check=False, env={"FLY_RELEASES": str(Path(c["root"]) / "releases")})
+        print((r.stdout or "") + (r.stderr or ""))
     elif cmd == "status":
         print(json.dumps(load_state(conf()), indent=1))
     elif cmd == "verify":                       # used by tools/publish_release.py on the Mac before uploading
-        d = Path(argv[2]); c = {"allowed_signers": argv[3], "principal": argv[4], "namespace": "fly-trader-release"}
+        d = Path(argv[2]); c = {"allowed_signers": argv[3], "principals": argv[4:] or ["bryce"], "namespace": "fly-trader-release"}
         raw = (d / "release.json").read_bytes()
         verify_signature(c, raw, (d / "release.json.sig").read_bytes())
         m = json.loads(raw); check_manifest(m); verify_dir(d, m)

deploy/signer.env.example

@@ -0,0 +1,4 @@
+# /srv/fly/signer.env (mode 600): the signer's own settings. Only the signer container reads this file.
+# REQUIRED: the signer does not start without it. Use a different provider from the brain's Helius: it simulates every
+# swap and reads the treasury itself. (Its value check reads Jupiter's public price API, lite-api.jup.ag, no key.)
+SIGNER_RPC_URL=

deploy/update.json.example

@@ -1,10 +1,15 @@
 {
   "repo": "bryceweiner/fly-trader",
   "allowed_signers": "/etc/fly/allowed_signers",
-  "principal": "bryce",
+  "principals": [
+    "bryce",
+    "bryce-recovery"
+  ],
   "namespace": "fly-trader-release",
   "root": "/srv/fly",
   "project": "fly",
+  "code_delay_s": 86400,
+  "expect_manifest_sha256": "",
   "telegram_bot_token": "",
   "telegram_chat_id": ""
 }

deploy/vault.env.example

@@ -1,16 +1,18 @@
-# /srv/fly/vault.env for the hosted $FLY vault fly (mode 600). Comments on their own lines only (Compose keeps a
-# trailing "# comment" as part of the value). The wallet key is NOT here: it is the file /srv/fly/secrets/bot_key.
+# /srv/fly/vault.env for the hosted $FLY vault fly's brain (mode 600). Comments on their own lines only (Compose keeps
+# a trailing "# comment" as part of the value). No key is here or anywhere the brain can read: the two hot keys are
+# files only the signer container mounts. Treasury and cap settings both containers share are in custody.env.
 
-# --- keys ---
+# --- API keys ---
 HELIUS_API_KEY=
 JUPITER_API_KEY=
+# a second, independent Solana RPC (Triton, QuickNode, Alchemy...): money-moving reads must agree with it
+SOLANA_CHECK_RPC_URL=
 
-# --- money: the vault wallet (5 SOL principal) ---
+# --- money: the book = the trading wallet (a float, TREASURY_FLOAT_SOL in custody.env) + the Squads treasury ---
 LIVE_ENABLED=1
 SOLANA_CLUSTER=mainnet-beta
+# your principal (what you send from FUNDING_ADDRESSES)
 CAPITAL_SOL=5
-# only used when the fly has no sizing table yet; the Kelly caps below govern (~0.47 SOL per position on 5 SOL)
-MAX_POSITION_SOL=0.5
 MAX_POSITION_FRACTION=0.10
 MAX_POOL_SHARE=0.02
 MIN_POSITION_SOL=0.02
@@ -22,15 +24,21 @@ HANDOVER_DAYS=0
 HANDOVER_MIN_TRADES=20
 HANDOVER_BEAT_SELECTOR=0
 RESET_ON_START=0
+# the CPU: the fly's scoring is memory-bound, and 16+ cores score as fast as a GPU; no GPU driver stack in the container
 DEVICE=cpu
-# leave memory for Postgres and the wallet-skill table (16 GB host)
-DEVICE_MEMORY_GB=6
+# what the fly's batches may use, leaving room for Postgres and the wallet-skill table (128 GB host; 16 GB host: 6)
+DEVICE_MEMORY_GB=24
 
 # --- the vault ---
-# SOL from these addresses is your deposit (principal); from anyone else it is profit for the lockers
+# comma-separated; SOL from these addresses (to the treasury or the trading wallet) is your deposit (principal); from
+# anyone else it is profit for the lockers. At least your Solflare owner address.
 FUNDING_ADDRESSES=
 RH_CHAIN_ID=4663
 RH_RPC_URL=https://rpc.mainnet.chain.robinhood.com
+# Robinhood Chain memecoin trading and the vault's ETH pot stay off on the hosted server: its signer container holds no
+# RH key, and the brain holds no wallet key at all.
+RH_ENABLED=0
+RH_LIVE_ENABLED=0
 # from contracts/deployments/4663.json after you deploy
 VAULT_ADDRESS=
 VAULT_TIMELOCK=
@@ -47,9 +55,11 @@ VAULT_SITE_URI=https://fly-trader.app/vault.html
 # --- alerts ---
 TELEGRAM_BOT_TOKEN=
 TELEGRAM_CHAT_ID=
+# your own Telegram user id: only its /panic and /status are obeyed (message @userinfobot to learn it)
+TELEGRAM_ADMIN_USER_ID=
+# dead-man switch: a healthchecks.io check URL (its Telegram integration tells you when pings stop)
+HEALTHCHECK_URL=
 
-# --- encrypted backups (key once, ledger nightly) ---
-# your age1... or ssh-ed25519 public key
-VAULT_BACKUP_RECIPIENT=
+# --- encrypted backups (hot keys once, by the signer; ledger nightly). The recipient key is in custody.env ---
 VAULT_BACKUP_BUCKET=bryceweiner/fly-vault-backups
 VAULT_BACKUP_HF_TOKEN=

docker-compose.yml

@@ -18,12 +18,19 @@ services:
 
   fly:
     build: .
+    # root inside the container: the self-updater (AUTO_UPDATE=1) replaces the code in /app, and data/, logs/ and .env
+    # are folders and a file of yours bind-mounted from here (the vault server's compose runs an unprivileged user and
+    # never self-updates)
+    user: "0:0"
+    # every key (BOT_PRIVATE_KEY, and RH_BOT_PRIVATE_KEY for Robinhood Chain live) comes from .env at run time, never the image
     env_file: .env
     environment:
       DATABASE_URL: postgresql://fly:fly@db:5432/fly_trader
       DATA_DIR: /app/data
       LOG_DIR: /app/logs
       DEVICE: auto          # the CPU in this image; an NVIDIA GPU with docker-compose.cuda.yml
+      # Robinhood Chain is opt-in: set RH_ENABLED=1 in .env (it needs ENVIO_API_TOKEN and room for its history)
+      RH_ENABLED: ${RH_ENABLED:-0}
     volumes:
       - ./data:/app/data        # models, the fly's plastic state, its hourly snapshots: survives restarts and rebuilds
       - ./logs:/app/logs

docker/bootstrap.sh

@@ -1,24 +1,58 @@
 #!/bin/sh
 # What every boot (and every self-update) does before the console starts: schema, the shipped models into the data
-# volume, the wallet-skill table, the neuron geometry, the seed rows that admit the fly. Nothing here overwrites a
-# running install: copies skip files that exist, the seed is ON CONFLICT DO NOTHING.
+# volume, the wallet-skill table, the neuron geometry, the rows that admit the fly. Nothing here overwrites a running
+# install: copies skip files that exist, and apply-release reuses rows it already has.
 set -e
 cd /app
 until pg_isready -d "$DATABASE_URL" >/dev/null 2>&1; do echo "fly-trader: waiting for postgres"; sleep 2; done
 fly-trader init-db
+# models/ holds exactly this release's fly and selector: an earlier release's (the updater before signed releases never
+# deleted a file) would be copied below, and a pickled .joblib makes apply-release refuse the whole release
+if [ -f seed/release_seed.json ]; then
+  python - <<'PY'
+import json, pathlib
+keep = {s["file"] for s in json.loads(pathlib.Path("seed/release_seed.json").read_text())["snapshots"]}
+for sub in ("policies", "selectors"):
+    for f in pathlib.Path("models", sub).glob("*"):
+        if f.is_file() and f.name not in keep:
+            f.unlink(); print(f"fly-trader: removed {f} (not in this release)")
+PY
+fi
 for sub in policies selectors connectome; do
   mkdir -p "data/brain/$sub"
   for f in models/$sub/*; do [ -e "$f" ] || continue; [ -e "data/brain/$sub/$(basename "$f")" ] || cp "$f" "data/brain/$sub/"; done
 done
+# The wallet-skill inputs: the fitted config and the newest table. The table (~300 MB) is too big for git; it comes from
+# a verified release (the vault server's /releases), or is downloaded from Hugging Face and used only if its sha256 is
+# the one pinned in models/wallet_skill/TABLE.sha256. Nothing unverified reaches the engine.
 mkdir -p data/corpus/wallet_skill
-for f in models/wallet_skill/*; do [ -e "$f" ] || continue; [ -e "data/corpus/wallet_skill/$(basename "$f")" ] || cp "$f" data/corpus/wallet_skill/; done
+for f in models/wallet_skill/*; do
+  [ -e "$f" ] || continue
+  case "$(basename "$f")" in TABLE|TABLE.sha256) continue;; esac
+  [ -e "data/corpus/wallet_skill/$(basename "$f")" ] || cp "$f" data/corpus/wallet_skill/
+done
 T=$(cat models/wallet_skill/TABLE 2>/dev/null || true)
+WANT=$(cat models/wallet_skill/TABLE.sha256 2>/dev/null || true)
 if [ -n "$T" ] && [ ! -e "data/corpus/wallet_skill/$T" ]; then
-  echo "fly-trader: fetching the wallet-skill table $T (~300 MB, once)"
-  curl -fsSL --retry 5 -o "data/corpus/wallet_skill/$T.part" "https://huggingface.co/${HF_REPO:-bryceweiner/fly-trader}/resolve/main/models/wallet_skill/$T" \
-    && mv "data/corpus/wallet_skill/$T.part" "data/corpus/wallet_skill/$T" \
-    || echo "fly-trader: WARNING could not fetch the wallet-skill table; the paper selector will not trade and the fly's skill inputs read as zero until it is present"
+  src=$(ls -d /releases/*/models/wallet_skill/"$T" 2>/dev/null | tail -1 || true)
+  if [ -n "$src" ]; then
+    cp "$src" "data/corpus/wallet_skill/$T"
+  elif [ -n "$WANT" ]; then
+    echo "fly-trader: fetching the wallet-skill table $T (~300 MB, once; checked against its pinned sha256)"
+    if curl -fsSL --retry 5 -o "data/corpus/wallet_skill/$T.part" "https://huggingface.co/${HF_REPO:-bryceweiner/fly-trader}/resolve/main/models/wallet_skill/$T" \
+       && [ "$(sha256sum "data/corpus/wallet_skill/$T.part" | cut -d' ' -f1)" = "$WANT" ]; then
+      mv "data/corpus/wallet_skill/$T.part" "data/corpus/wallet_skill/$T"
+    else
+      rm -f "data/corpus/wallet_skill/$T.part"
+    fi
+  fi
 fi
+[ -z "$T" ] || [ -e "data/corpus/wallet_skill/$T" ] || \
+  echo "fly-trader: WARNING the wallet-skill table $T is missing or did not match its sha256; the paper selector will not trade and the fly's skill inputs read as zero until it is present (data/corpus/wallet_skill/$T)"
 mkdir -p fly_trader/ui/static/brain && cp models/geometry/* fly_trader/ui/static/brain/ 2>/dev/null || true
-psql "$DATABASE_URL" -v ON_ERROR_STOP=1 -q -f seed/seed.sql
+if [ -f seed/release_seed.json ]; then
+  fly-trader apply-release /app --bootstrap        # the shipped models, registered by file hash (fresh ids), idempotently
+else
+  psql "$DATABASE_URL" -v ON_ERROR_STOP=1 -q -f seed/seed.sql
+fi
 echo "fly-trader: device $(python -c 'from fly_trader.brain import device; print(device.describe(device.resolve()))' 2>/dev/null || echo unknown)"

docker/signer-requirements.txt

@@ -0,0 +1,51 @@
+anyio==4.15.1 \
+    --hash=sha256:6152fdbbf9a77fdec97731721bebf7c4c44f7c29b424b0065826173efc7ed101 \
+    --hash=sha256:9f28306018cbd6d329e64a36d58256edff76dd996fe423bc957326e578b82a94
+    # via httpx
+base58==2.1.1 \
+    --hash=sha256:11a36f4d3ce51dfc1043f3218591ac4eb1ceb172919cebe05b52a5bcc8d245c2 \
+    --hash=sha256:c5d0cb3f5b6e81e8e35da5754388ddcc6d0d14b6c6a132cb93d69ed580a7278c
+    # via -r /private/tmp/claude-501/-Users-bryce-Documents-code-fly-trader/28aad393-6f38-484a-a2b2-a06a8f112cf1/scratchpad/signer.in
+certifi==2026.7.22 \
+    --hash=sha256:62f22742b58a1a33014a2b6b706588a8d7e2a88ae7bd1a6ebe8c992928483775 \
+    --hash=sha256:741e2c3b351ddf169a738da9f2c048608ff7f2c5cc02f1ebc6b118bb090d5d55
+    # via
+    #   httpcore
+    #   httpx
+h11==0.16.0 \
+    --hash=sha256:4e35b956cf45792e4caa5885e69fba00bdbc6ffafbfa020300e549b208ee5ff1 \
+    --hash=sha256:63cf8bbe7522de3bf65932fda1d9c2772064ffb3dae62d55932da54b31cb6c86
+    # via httpcore
+httpcore==1.0.9 \
+    --hash=sha256:2d400746a40668fc9dec9810239072b40b4484b640a8c38fd654a024c7a1bf55 \
+    --hash=sha256:6e34463af53fd2ab5d807f399a9b45ea31c3dfa2276f15a2c3f00afff6e176e8
+    # via httpx
+httpx==0.28.1 \
+    --hash=sha256:75e98c5f16b0f35b567856f597f06ff2270a374470a5c2392242528e3e3e42fc \
+    --hash=sha256:d909fcccc110f8c7faf814ca82a9a4d816bc5a6dbfea25d6591d6985b8ba59ad
+    # via -r /private/tmp/claude-501/-Users-bryce-Documents-code-fly-trader/28aad393-6f38-484a-a2b2-a06a8f112cf1/scratchpad/signer.in
+idna==3.20 \
+    --hash=sha256:a7db850025b95ded1eae8a46181a1a6c56c92c96f0e2b005d9ff8dc0210cab44 \
+    --hash=sha256:ab7ae7122974553370f0bdb919e1a960b2cd1bc1ef0276416d896db81c14582c
+    # via
+    #   anyio
+    #   httpx
+jsonalias==0.1.1 \
+    --hash=sha256:64f04d935397d579fc94509e1fcb6212f2d081235d9d6395bd10baedf760a769 \
+    --hash=sha256:a56d2888e6397812c606156504e861e8ec00e188005af149f003c787db3d3f18
+    # via solders
+solders==0.29.0 \
+    --hash=sha256:00524baf575ae5edb2ba43cdb1d80491c59efdc16b48fec96a6f929c0401d0e4 \
+    --hash=sha256:09e80c545c728f434f627d3b4714675a0f654c4d387f3339d54f7d09d59f3f1c \
+    --hash=sha256:62e8a5bb4bc8628d5fe49faa56aca149dce284a9f8bf5f3c56c4721e561be84b \
+    --hash=sha256:785841623bdd7b8dedc68e7c794b54327d3b03e1ab9697eda90a139ca3c98cfe \
+    --hash=sha256:9d2e011ff1d5f82a7de81d6eb89f54d002189f50ee48d4a15d7b51849e04b1c3 \
+    --hash=sha256:c17098cab72a1c202ec4cc0ce3ecbff4296c9de97000e05944337ba5ddb681a8 \
+    --hash=sha256:f36db7b43088866081b5d37ff62668551e30dd136b9ee58a5fb524fcd828082d
+    # via -r /private/tmp/claude-501/-Users-bryce-Documents-code-fly-trader/28aad393-6f38-484a-a2b2-a06a8f112cf1/scratchpad/signer.in
+typing-extensions==4.16.0 \
+    --hash=sha256:481caa481374e813c1b176ada14e97f1f67a4539ce9cfeb3f350d78d6370c2e8 \
+    --hash=sha256:dc983d19a509c94dba722ee6abd33940f7c05a89e243c47e907eb4db6f1a43e5
+    # via
+    #   anyio
+    #   solders

docs/vault/RUNBOOK.md

@@ -1,120 +1,435 @@
 # $FLY vault: launch runbook
 
-These are the steps only you can do, because they need your keys or accounts. They are in order. The agent never
-handles your keys.
-
-## 0. Accounts and keys (once)
-- **Reown project id.** Create it at dashboard.reown.com and allowlist `fly-trader.app`, plus `localhost:5173` for the
-  rehearsal.
-- **Telegram bot.** Create one with @BotFather; you need its token and your chat id.
-- **Release-signing key (Mac).** Run `ssh-keygen -t ed25519 -f ~/.ssh/fly_release`. The public key goes to the server's
-  allowed signers in step 3.
-- **Backup key.** This is the age or ssh-ed25519 public key the backups are encrypted to. You can use
-  `~/.ssh/fly_release.pub` or an age key.
-- **HF storage bucket.** Create a private bucket named `bryceweiner/fly-vault-backups`, then a fine-grained token that
-  can write only to that bucket.
-- **Hardware-wallet EVM account.** This account owns the vault.
-
-## 1. Rehearsal (testnet 46630 + Solana devnet)
-1. Deploy the contracts to the testnet:
-   ```
-   cd contracts
-   forge script script/DeployTestnet.s.sol --rpc-url https://rpc.testnet.chain.robinhood.com --ledger --broadcast
-   ```
-   The addresses land in `contracts/deployments/46630.json`.
-2. Build the site against the testnet:
-   ```
-   cd web
-   VITE_NETWORK=testnet VITE_REOWN_PROJECT_ID=… VITE_VAULT_ADDRESS=… VITE_TIMELOCK_ADDRESS=… VITE_FLY_ADDRESS=<MockFLY> npm run dev
-   ```
-   Run a local relay (see `web/relay/README.md`) with `domain: localhost:5173`, `chain_id: 46630`, `sol_chain: devnet`.
-3. Run the fly (Docker or the Mac) with these settings:
-   - `VAULT_ENABLED=1`, `VAULT_CLUSTER=devnet`, `VAULT_SOLANA_RPC_URL=https://api.devnet.solana.com`
-   - `VAULT_PERIOD_S=900`
-   - `RH_CHAIN_ID=46630`, `RH_RPC_URL=https://rpc.testnet.chain.robinhood.com`
-   - `VAULT_SITE_DOMAIN=localhost:5173`, `VAULT_SITE_URI=http://localhost:5173/vault.html`
-   - `LIVE_ENABLED=0`
-   - a throwaway devnet key, funded from the devnet faucet
-4. Work through the checklist:
-   - lock from two wallets at different times, then request and cancel a withdrawal
-   - send devnet SOL from an address that is not a funding address (it counts as profit)
-   - wait for a 15-minute settlement
-   - claim from both wallets, then replay a used nonce
-   - kill the fly in the middle of a claim and restart it
-   - `fly-trader vault status`
-
-## 2. Mainnet contracts
-1. Deploy:
-   ```
-   cd contracts
-   FLY_TOKEN=0x2fC7f9E2911f20b2C4660d2AEf808aa91bDdb3D3 OWNER=<hardware account> \
-     forge script script/Deploy.s.sol --rpc-url https://rpc.mainnet.chain.robinhood.com --ledger --broadcast
-   ```
-   The script refuses to run on chain 4663 unless the delays are 8 days (timelock) and 7 days (withdrawal).
-2. Verify the contracts on Blockscout. `contracts/README.md` has a manual fallback if Cloudflare blocks forge.
-3. Record the implementation code hash:
-   ```
-   cast keccak $(cast code <impl> --rpc-url https://rpc.mainnet.chain.robinhood.com)
-   ```
-   This value becomes `VAULT_IMPL_CODEHASHES` in step 3.
-
-## 3. Server (Netcup RS 2000 G12, Ubuntu 24.04)
-1. Put your SSH key on the server. Then copy the `deploy/` folder from the distribution branch and run:
-   `sudo bash deploy/bootstrap-host.sh "$(cat ~/.ssh/fly_release.pub)"`
-   It prints the **vault wallet address**. The key is created on the server and stays there.
-2. Edit `/srv/fly/vault.env`. Fill in:
-   - `HELIUS_API_KEY`, `JUPITER_API_KEY`
-   - `FUNDING_ADDRESSES`
-   - `VAULT_ADDRESS`, `VAULT_TIMELOCK`, `VAULT_START_BLOCK`, `VAULT_IMPL_CODEHASHES`
-   - `RELAY_SECRET`
-   - `TELEGRAM_*`
-   - `VAULT_BACKUP_*`
-3. Edit `/etc/fly/update.json`. Only the Telegram fields need filling.
-4. Publish the first release from the Mac. Keep a distribution worktree at `../fly-trader-dist`, then run:
-   `.venv/bin/python tools/publish_release.py --worktree ../fly-trader-dist --key ~/.ssh/fly_release --models`
-5. On the server, start the updater:
-   ```
-   sudo systemctl enable --now fly-update.timer
-   journalctl -u fly-update -f
-   ```
-   It builds the image and starts the fly, which warms up on paper.
-6. To open the console:
-   ```
-   ssh -L 8501:127.0.0.1:8501 <server>
-   ```
-   Then browse to http://localhost:8501/vault.
-
-## 4. Site (Gandi)
+The steps only you can do, because they need your keys, accounts or devices, in the order to do them. The agent never
+handles your keys. How the system works is in [SPEC.md](SPEC.md); this file is what to type.
+
+**Who holds what** (until the Ledger is back; the "Ledger" section moves everything to it without redeploying):
+
+| Key | Where | Can do |
+|---|---|---|
+| Solana owner | Solflare on your phone | Everything with the treasury: create/remove its spending limits, take principal out |
+| EVM owner | MetaMask | Pause new $FLY locks; propose upgrades (public for 8 days); hand the roles to the Ledger |
+| SSH | Secretive on the Mac (Secure Enclave, Touch ID) | Log in to the server over Tailscale |
+| Release signing | Secretive (Touch ID) + an offline recovery key | Sign releases; the server still holds code changes 24 h |
+| Backup decryption | an age key, offline | Read the encrypted backups |
+| Trading / payout | on the server, readable only by the signer container | Refill the float (L1, per day), pay claims (L2, per week) |
+
+A full takeover of the server can lose at most the trading float plus what is left of this day's L1 and this week's
+L2, and only until you revoke them from your phone ("Emergency").
+
+Conventions below:
+- `$` lines run on the **Mac** in the fly-trader checkout (the repo root). Commands for a subfolder run in a subshell,
+  `$ (cd web && …)`, so you are always back at the root.
+- `server$` lines run on the **server** as `fly-admin`.
+- `sudo fly <command>` runs `fly-trader <command>` inside the running fly container; `sudo fly signer <command>` runs
+  in the signer container.
+
+## 0. Once: tools, repos, accounts, keys
+
+### 0.1 Mac tools
+```
+$ brew install age node uv git
+$ brew install --cask secretive tailscale
+$ curl -L https://foundry.paradigm.xyz | bash && foundryup                  # forge, cast
+$ sh -c "$(curl -sSfL https://release.anza.xyz/stable/install)"              # solana CLI + solana-test-validator
+$ uv sync --extra dev                                                        # the Python environment (.venv)
+$ (cd web && npm ci)
+$ (cd contracts && forge soldeer install)
+$ git worktree add ../fly-trader-dist distribution                            # the branch the server runs
+```
+
+### 0.2 Accounts
+- **2FA everywhere.** Use a hardware key or TOTP on Gandi, Hugging Face, GitHub,
+  your Tailscale identity provider and your Apple ID. Set a Telegram two-step password.
+- **Phone wallets.** Write the Solflare and MetaMask seed phrases on paper and keep them offline. The phone needs a
+  passcode and biometrics. Keep a little SOL in Solflare (about 0.05 SOL pays the treasury's setup and any later
+  change) and a little ETH on Robinhood Chain in MetaMask (for `pause()`).
+- **Reown project id.** Create it at dashboard.reown.com. Allowlist `fly-trader.app`, and `localhost:5173` for local
+  testing.
+- **Telegram.**
+  1. Create a bot with @BotFather and note its token.
+  2. Send `/start` to your new bot; it cannot message you before that.
+  3. Message @userinfobot to learn your user id. In a private chat with the bot, the chat id is that same number.
+     Only that user's `/panic` and `/status` count.
+- **Hugging Face.**
+  1. Create a **public** model repo `bryceweiner/fly-trader`: the server and self-hosted installs read releases
+     without logging in.
+  2. Create a **private** storage bucket `bryceweiner/fly-vault-backups` for the encrypted backups.
+  3. Create two tokens: one with write access to the model repo, for publishing from the Mac; one fine-grained,
+     write-only to the bucket, for the server's backups.
+  4. `$ uv run hf auth login` with the first token.
+- **GitHub.** Push access to the fly-trader repo: publishing pushes the `distribution` branch.
+- **Second Solana RPC.** Get an API URL from a provider other than Helius (Triton, QuickNode or Alchemy). It is used
+  twice:
+  - `SOLANA_CHECK_RPC_URL`: settlement balances and halts must agree with it.
+  - `SIGNER_RPC_URL`: the signer's own reads and simulations.
+- **healthchecks.io.** Create a check with period 5 minutes and grace 10 minutes, and connect its Telegram
+  integration. Its ping URL is `HEALTHCHECK_URL`.
+
+### 0.3 Tailscale
+1. Install Tailscale on the Mac, log in, and turn on **MagicDNS** in the admin console, so `fly-vault` resolves.
+2. In the admin console's access controls, add:
+   ```
+   "tagOwners": {"tag:fly": ["autogroup:admin"]},
+   "acls": [{"action": "accept", "src": ["<your Tailscale login>"], "dst": ["tag:fly:22"]}]
+   ```
+   Add no rule whose source is `tag:fly`: the server needs to reach nothing on your tailnet.
+3. Turn on **Tailnet Lock** from the Mac:
+   ```
+   $ tailscale lock status                                          # shows this Mac's tlpub:… key
+   $ tailscale lock init --gen-disablements 3 --confirm tlpub:<that key>
+   ```
+   Store the printed disablement secrets offline, like a seed phrase.
+4. Create a one-off, pre-authorised auth key tagged `tag:fly` in the admin console. Sign it so the server may join the
+   locked tailnet, and keep the output (this is `TS_AUTHKEY` in section 4.2):
+   ```
+   $ tailscale lock sign tskey-auth-…
+   ```
+
+### 0.4 Your keys (Secretive, recovery, backup)
+1. In Secretive create two keys, `fly-ssh` and `fly-release`, each requiring Touch ID. Save their public keys as
+   `~/.ssh/fly-ssh.pub` and `~/.ssh/fly-release.pub`.
+2. Put the path of Secretive's agent in your shell profile (`~/.zshrc`), since several steps use it:
+   `export SECRETIVE=~/Library/Containers/com.maxgoedjen.Secretive.SecretAgent/Data/socket.ssh`.
+   Then tell ssh to use Secretive for the server, in `~/.ssh/config`:
+   ```
+   Host fly-vault
+     User fly-admin
+     IdentityAgent ~/Library/Containers/com.maxgoedjen.Secretive.SecretAgent/Data/socket.ssh
+   ```
+3. The offline recovery release signer:
+   ```
+   $ mkdir -p ~/fly-keys
+   $ ssh-keygen -t ed25519 -f ~/fly-keys/fly-release-recovery -C fly-release-recovery
+   $ age -p ~/fly-keys/fly-release-recovery > ~/fly-keys/fly-release-recovery.age && rm ~/fly-keys/fly-release-recovery
+   ```
+   Put `fly-release-recovery.age` on a USB stick and in your password manager. Keep `fly-release-recovery.pub`.
+4. The backup key: `$ age-keygen -o ~/fly-keys/fly-backup.key`. Store it like the recovery key; its public line
+   (`age1…`, printed and at the top of the file) is `VAULT_BACKUP_RECIPIENT`. It is deliberately not the release key.
+5. Trust both release keys in the distribution, so that self-hosted installs accept your releases:
+   ```
+   $ echo "bryce namespaces=\"fly-trader-release\" $(cat ~/.ssh/fly-release.pub)" >> ../fly-trader-dist/release/allowed_signers
+   $ echo "bryce-recovery namespaces=\"fly-trader-release\" $(cat ~/fly-keys/fly-release-recovery.pub)" >> ../fly-trader-dist/release/allowed_signers
+   $ git -C ../fly-trader-dist status                     # must be clean apart from this file (no merge in progress)
+   $ git -C ../fly-trader-dist commit -m "Release keys" release/allowed_signers
+   ```
+
+## 1. Rehearse locally (no real money)
+- **Custody against the real Squads program:**
+  `$ tools/custody_e2e.sh <your Helius mainnet RPC URL>`. It dumps the program from mainnet (read-only) and runs it on
+  a throwaway validator on ports 11xxx. It checks:
+  - the owner page's code creates the treasury and both limits, changes L2 and revokes them
+  - the signer refills through L1 and pays a claim through L2 up to its cap
+  - a stolen key cannot send L1 anywhere but the trading wallet (refused on chain)
+- **The whole vault on this Mac:** `$ .venv/bin/python tools/vault_demo.py up`. It runs anvil, the contracts, the relay,
+  the vault worker, a treasury on a local validator and the site at http://localhost:5173. The file's docstring lists
+  the wallet settings and commands (`fund-evm`, `profit`, `status`, `down`).
+- **Optional: RH testnet + Solana devnet.**
+  1. Deploy the contracts:
+     ```
+     $ cast wallet new ~/.foundry/keystores rehearsal     # fund it from faucet.testnet.chain.robinhood.com
+     $ (cd contracts && forge script script/DeployTestnet.s.sol --rpc-url robinhood_testnet --account rehearsal \
+         --sender $(cast wallet address --account rehearsal) --broadcast)
+     $ cp contracts/deployments/46630.json ~/fly-keys/testnet-deployment.json
+     ```
+     The addresses land in `contracts/deployments/46630.json`: `vault`, `timelock`, `token` (MockFLY), `blockNumber`.
+     Keep the copy: `vault_demo.py` deploys to anvil, which uses the same chain id, and overwrites that file.
+  2. Run the site against it:
+     Run a relay as in `web/relay/README.md` (e.g. `tools/vault_demo.py` shows how it starts one on port 8612), with
+     `"domain": "localhost:5173"`, `"uri": "http://localhost:5173/vault.html"`, `"chain_id": 46630`,
+     `"sol_chain": "devnet"`. Then:
+     ```
+     $ (cd web && VITE_NETWORK=testnet VITE_REOWN_PROJECT_ID=… VITE_VAULT_ADDRESS=<vault> VITE_TIMELOCK_ADDRESS=<timelock> \
+         VITE_FLY_ADDRESS=<token> VITE_SOLANA_RPC=https://api.devnet.solana.com VITE_RELAY_PROXY=http://127.0.0.1:8612 npm run dev)
+     ```
+  3. Make two throwaway devnet keys (`$ solana-keygen new -o /tmp/devnet-trading.json`, the same for payout; fund
+     the trading one at faucet.solana.com). Create the treasury: http://localhost:5173/owner.html with Solflare on
+     devnet, as in section 4.3, with those two public keys.
+  4. Run the vault worker on the Mac with these settings in the environment:
+     - `VAULT_ENABLED=1`, `VAULT_CLUSTER=devnet`, `VAULT_SOLANA_RPC_URL=https://api.devnet.solana.com`,
+       `SIGNER_RPC_URL=https://api.devnet.solana.com`, `VAULT_PERIOD_S=900`, `LIVE_ENABLED=0`
+     - `BOT_PRIVATE_KEY_FILE=/tmp/devnet-trading.json`, `PAYOUT_PRIVATE_KEY_FILE=/tmp/devnet-payout.json`
+     - `VAULT_MULTISIG`, `VAULT_LIMIT_TRADING`, `VAULT_LIMIT_PAYOUT` (from the owner page)
+     - `RH_CHAIN_ID=46630`, `RH_RPC_URL=https://rpc.testnet.chain.robinhood.com`, `VAULT_ADDRESS`,
+       `VAULT_TIMELOCK`, `VAULT_START_BLOCK`
+     - `VAULT_SITE_DOMAIN=localhost:5173`, `VAULT_SITE_URI=http://localhost:5173/vault.html`
+     - `RELAY_URL=http://127.0.0.1:8612`, `RELAY_SECRET` (the relay's), and a separate `DATABASE_URL`
+       (`createdb fly_vault_rehearsal; DATABASE_URL=postgresql:///fly_vault_rehearsal uv run fly-trader init-db`)
+
+     ```
+     $ uv run python -c "from fly_trader.vault import worker; worker.main()"
+     ```
+
+## 2. Mainnet contracts (EVM owner = MetaMask)
+1. Deploy from a throwaway keystore. It pays the gas and holds no role afterwards:
+   ```
+   $ cast wallet new ~/.foundry/keystores deployer                 # fund with a little ETH on Robinhood Chain
+   $ (cd contracts && FLY_TOKEN=0x2fC7f9E2911f20b2C4660d2AEf808aa91bDdb3D3 OWNER=<your MetaMask address> \
+       forge script script/Deploy.s.sol --rpc-url robinhood --account deployer \
+       --sender $(cast wallet address --account deployer) --broadcast \
+       --verify --verifier blockscout --verifier-url https://robinhoodchain.blockscout.com/api/)
+   ```
+   The script refuses to run on chain 4663 unless the token is the real $FLY and the delays are 8 days (timelock) and
+   7 days (withdrawal). It writes `contracts/deployments/4663.json`: `vault`, `implementation`, `timelock`,
+   `blockNumber`. You need all four below.
+2. Check that the deployer holds nothing. Each of these must print `false`:
+   ```
+   $ D=$(cast wallet address --account deployer)
+   $ R=https://rpc.mainnet.chain.robinhood.com
+   $ cast call <timelock> "hasRole(bytes32,address)(bool)" $(cast keccak PROPOSER_ROLE) $D --rpc-url $R
+   $ cast call <timelock> "hasRole(bytes32,address)(bool)" 0x0000000000000000000000000000000000000000000000000000000000000000 $D --rpc-url $R
+   $ cast call <vault> "hasRole(bytes32,address)(bool)" $(cast keccak PAUSER_ROLE) $D --rpc-url $R
+   ```
+   Then delete `~/.foundry/keystores/deployer`.
+3. Check the contracts show as verified on Blockscout; `contracts/README.md` has a manual fallback if Cloudflare
+   blocked forge's verification.
+4. Record the implementation code hash; it becomes `VAULT_IMPL_CODEHASHES`:
+   `$ cast keccak $(cast code <implementation> --rpc-url https://rpc.mainnet.chain.robinhood.com)`
+5. From your phone (MetaMask), you use Blockscout's page for each contract, under "Write proxy" / "Write contract":
+   - **Pause new locks:** FlyVault, `pause()`; later `unpause()`. Withdrawals always stay open.
+   - **Cancel a timelock operation you did not schedule:** Timelock, `cancel(<id>)`. The Telegram alert gives the full
+     id.
+
+## 3. Site (Gandi)
+The owner page is part of the site, and you need it for the treasury, so the site goes up before the server.
 1. Build the upload bundle:
    ```
-   cd web
-   VITE_REOWN_PROJECT_ID=… VITE_VAULT_ADDRESS=… VITE_TIMELOCK_ADDRESS=… bash scripts/bundle_gandi.sh
+   $ (cd web && VITE_REOWN_PROJECT_ID=… VITE_VAULT_ADDRESS=<vault> VITE_TIMELOCK_ADDRESS=<timelock> bash scripts/bundle_gandi.sh)
+   ```
+   The bundle lands in `build/gandi/` at the repo root: `wsgi.py`, `site-headers.json`, `relay/` and `site/`.
+   `owner.html` is included; it is not linked anywhere, it is noindex, and it can do nothing without your owner wallet.
+2. Upload the contents of `build/gandi/` over Gandi SFTP (or git) into the instance's deploy directory (where
+   `wsgi.py` lives), replacing `site/` entirely.
+3. Make the relay secret: `$ python3 -c "import secrets;print(secrets.token_hex(32))"`. The fly gets the same value as
+   `RELAY_SECRET`.
+4. Upload `relay.json` next to `wsgi.py` (never into `site/`, never into git). The database goes on the instance's
+   persistent disk, outside the deploy directory:
+   ```json
+   {"keys": {"k1": "<the secret>"}, "db_path": "/srv/data/home/relay/relay.sqlite3", "domain": "fly-trader.app",
+    "uri": "https://fly-trader.app/vault.html", "chain_id": 4663, "sol_chain": "mainnet", "claim_ttl_s": 900,
+    "min_lamports": 2000000, "client_ip_header": null}
    ```
-2. Upload the contents of `build/gandi/` so they replace `site/` entirely.
-3. Put `relay.json` next to `wsgi.py`, using the same secret as `RELAY_SECRET`, then restart the instance.
-4. Probe the relay from the Mac:
+   Restart the instance. If a later deploy replaces the directory, upload `relay.json` again.
+5. Probe the relay and work through the 7-point checklist in `web/relay/README.md` (writable, WAL, client IP header,
+   no caching, clock):
+   `$ FLY_RELAY_SECRET=<the secret> python3 web/relay/hmacauth.py https://fly-trader.app/api/fly/probe k1`
+
+## 4. Server (a dedicated machine at home, Ubuntu Server 24.04)
+
+### 4.1 Publish the first release
+1. The distribution worktree must hold exactly what you want to ship. Code is ported there from master by hand (or with
+   a merge); publishing does not port it. Check it is clean: `$ git -C ../fly-trader-dist status`.
+2. `--models` refreshes the models from this Mac; use it for the first release. That needs:
+   - a deployable fly (`fly-trader train-fly-selector`) that passed `fly-trader fly-replay`
+   - a deployed selector (pinned, or the newest that qualifies)
+   - fitted wallet skill (`fly-trader fit-wallet-skill`) with its tables, and a built connectome
+   Without `--models` the release carries the models already in the worktree, and publishing refuses if the
+   wallet-skill table named in `models/wallet_skill/TABLE` is not there.
+3. Publish. `SSH_AUTH_SOCK` points `ssh-keygen` at Secretive, so Touch ID confirms the signature:
    ```
-   FLY_RELAY_SECRET=<secret> python web/relay/hmacauth.py https://fly-trader.app/api/fly/probe k1
+   $ SSH_AUTH_SOCK=$SECRETIVE .venv/bin/python tools/publish_release.py --worktree ../fly-trader-dist --key ~/.ssh/fly-release.pub --models
    ```
-   Check the output against the checklist in `web/relay/README.md`. The things that must hold: the database path is
-   writable, WAL works, and nothing caches `/api`.
+   It runs the tests, commits, signs, verifies with the server's own verifier, pushes the `distribution` branch and
+   uploads one Hugging Face commit. It refuses unless the key is in the worktree's `release/allowed_signers` (0.4 step
+   5). Note the printed **manifest sha256**; it pins this first release on the server.
+4. **Do not publish again until the server has installed this release** (section 4.4). A new server accepts only the
+   pinned manifest, and it permanently refuses any other head it sees first.
+
+### 4.2 The machine and its bootstrap
+A dedicated machine at home (the reference is a GMKtec EVO-X3: Ryzen AI Max+ 395, 128 GB, 2 TB NVMe, 2.5 GbE). It
+runs nothing but the vault fly. The fly runs on its CPU; the Radeon GPU is not used (no GPU driver stack in reach of
+the keys).
+
+1. **Firmware** (press Del or F7 at power-on for the setup screen):
+   - Update the BIOS from the vendor's support site first.
+   - Set a supervisor (admin) password.
+   - Turn on the firmware TPM (AMD fTPM / "Security Device Support"), Secure Boot (standard keys) and the IOMMU
+     (AMD-Vi / "IOMMU: Enabled").
+   - Turn off Wi-Fi and Bluetooth if the menu offers it (the bootstrap also blocks their drivers).
+   - "Restore on AC power loss": Power On.
+   - Boot order: the internal disk first. After installing (step 2), turn off booting from USB.
+2. **A clean Ubuntu Server 24.04 LTS install** from a USB stick made from ubuntu.com's image. Erase the preinstalled
+   Windows; some mini-PC vendors have shipped malware in theirs.
+   - Storage: "Use an entire disk", "Set up this disk as an LVM group", **"Encrypt the LVM group with LUKS"**. Keep
+     the passphrase in your password manager.
+   - Profile: server name `fly-vault`, user **`fly-admin`**, any password (the bootstrap locks it).
+   - SSH: "Install OpenSSH server", with password authentication (only until the bootstrap).
+   - No featured snaps.
+3. **Network:** plug it into the router by cable, on its own VLAN or guest port if the router can. Forward no ports to
+   it, and turn off UPnP on the router. Put it on a UPS: during a power or internet outage the fly cannot sell,
+   refill or pay, and healthchecks.io tells you it went quiet.
+4. From the Mac, on the same network (the machine's address is on its console, `ip -4 addr`):
+   ```
+   $ ssh-copy-id -o IdentityAgent=$SECRETIVE -f -i ~/.ssh/fly-ssh.pub fly-admin@<LAN address>
+   $ scp -o IdentityAgent=$SECRETIVE -r ../fly-trader-dist/deploy ~/.ssh/fly-release.pub ~/fly-keys/fly-release-recovery.pub fly-admin@<LAN address>:
+   $ ssh -o IdentityAgent=$SECRETIVE fly-admin@<LAN address>
+   ```
+5. The first pass. `TPM_UNLOCK=1` binds the disk encryption to the TPM, so security-update reboots come back up on
+   their own; it asks once for the disk passphrase. Without it, every boot waits for the passphrase at the console,
+   and automatic reboots are switched off.
+   ```
+   server$ sudo TS_AUTHKEY=<signed key from 0.3 step 4> RECOVERY_PUBKEY="$(cat fly-release-recovery.pub)" \
+       EXPECT_MANIFEST=<manifest sha256 from 4.1> TPM_UNLOCK=1 ADMIN_USER=fly-admin bash deploy/bootstrap-host.sh "$(cat fly-release.pub)"
+   ```
+   It hardens the box (roughly CIS level 1):
+   - **The machine:** Wi-Fi and Bluetooth drivers can never load; it warns if the IOMMU is off or the disk is not
+     encrypted.
+   - **SSH:** only `fly-admin`, key only (ed25519, P-256, FIDO), root off.
+   - **Firewall:** in and out; containers reach only HTTPS, HTTP (apt) and DNS.
+   - **Kernel and Docker:** user namespaces, no new privileges.
+   - **Monitoring:** fail2ban; an audit log of every read of the wallet keys, with a Telegram alert when anything but
+     the signer reads them; a daily AIDE file-integrity check (05:30 UTC) that reports to Telegram when files changed;
+     automatic security updates (reboot 04:00 UTC when needed and the TPM unlocks the disk).
+   - **Keys:** it makes the trading and payout keys and prints them, **once**, as `bot_key: <address>` (the trading
+     key) and `payout_key: <address>`. Copy both lines now. Later, once the containers run:
+     `server$ sudo fly signer status` (as `"trading"` and `"payout"`).
+6. **Keep this session open.** From a second terminal on the Mac, log in over Tailscale: `$ ssh fly-vault`. Only when
+   that works, run the second pass in the first session. It removes SSH from the local network, leaving Tailscale as
+   the only way in:
+   ```
+   server$ sudo CLOSE_PUBLIC_SSH=1 bash deploy/bootstrap-host.sh "$(cat fly-release.pub)"
+   ```
+   The recovery key already installed is kept. After this the machine has no open port except SSH over Tailscale.
+7. Physical access is now the way around every other control: keep the machine somewhere only you reach. The disk is
+   useless without the TPM on this board (or the passphrase), and the firmware password and USB-boot-off stop anyone
+   booting another system on it. Unbinding the TPM (a new board, a firmware reset) means typing the passphrase at the
+   console once and re-running step 5 with `TPM_UNLOCK=1`.
+
+### 4.3 The treasury (your phone)
+1. Open `https://fly-trader.app/owner.html` in Solflare's browser and connect Solflare.
+2. Paste the trading key (`bot_key`) and the payout key (`payout_key`), leave the multisig field empty, and tap
+   "Read the treasury".
+3. Tap "Create the treasury multisig": you are its only member, threshold 1, no time lock.
+4. Tap "Create L1" (2 SOL a day, to the trading wallet only) and "Create L2" (1 SOL a week, claims).
+5. Every check the page shows must pass. It prints the three lines for `custody.env`. **Save the multisig, L1 and L2
+   addresses in your password manager.** The page remembers them only in that browser, and the Revoke button needs
+   them.
+
+### 4.4 Settings, start, check
+1. Fill in the settings with `sudoedit`: `server$ sudoedit /srv/fly/custody.env`, and so on. The files are root-only
+   (mode 600).
+   - **`/srv/fly/custody.env`:** the three lines from the owner page (`VAULT_MULTISIG`, `VAULT_LIMIT_TRADING`,
+     `VAULT_LIMIT_PAYOUT`) and `VAULT_BACKUP_RECIPIENT` (your `age1…`). The float and caps have working defaults.
+   - **`/srv/fly/signer.env`:** `SIGNER_RPC_URL` (the second provider). Required: the signer does not start without it.
+   - **`/srv/fly/vault.env`:**
+     - `HELIUS_API_KEY`, `JUPITER_API_KEY`, `SOLANA_CHECK_RPC_URL`
+     - `CAPITAL_SOL` (your principal, e.g. 5)
+     - `FUNDING_ADDRESSES`: the addresses you will send principal from, comma-separated; at least your Solflare address
+     - `VAULT_ADDRESS`, `VAULT_TIMELOCK`, `VAULT_START_BLOCK` (`blockNumber`), `VAULT_IMPL_CODEHASHES`, all from step 2
+     - `RELAY_SECRET` (the relay's secret from step 3)
+     - `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID`, `TELEGRAM_ADMIN_USER_ID`, `HEALTHCHECK_URL`
+     - `VAULT_BACKUP_BUCKET`, `VAULT_BACKUP_HF_TOKEN` (the bucket-only token)
+   - **`/etc/fly/update.json`:** `telegram_bot_token` and `telegram_chat_id` (the host updater, the key-read watcher and
+     AIDE report through these). `expect_manifest_sha256` was set by the bootstrap.
+
+   Everything must be filled in before the next step: a first release that does not come up healthy is refused for
+   good. If that happens: fix the cause, publish a new release, and put its manifest sha256 into
+   `expect_manifest_sha256` in `/etc/fly/update.json`.
+2. Start the updater. It installs the pinned release, builds the brain and signer images and starts them (the first
+   build takes several minutes):
+   ```
+   server$ sudo systemctl enable --now fly-update.timer
+   server$ sudo systemctl start fly-update.service          # the first round now, instead of in 2 minutes
+   server$ sudo journalctl -u fly-update -f
+   ```
+3. Check everything:
+   - `server$ sudo /usr/local/lib/fly/check-host.sh`: every control must pass (keys only in the signer, Tailnet Lock on,
+     no public SSH…)
+   - `server$ sudo fly vault custody`: no problems
+   - `server$ sudo python3 /usr/local/lib/fly/fly_audit_watch.py test`: the Telegram test message arrives
+4. The console: `$ ssh -L 8501:127.0.0.1:8501 fly-vault`, then http://localhost:8501/vault.
 
 ## 5. Go live
-1. Send 5 SOL to the vault wallet from an address listed in `FUNDING_ADDRESSES`.
-2. Check the deposit was counted: `fly-trader vault status` (inside the container) should show `deposits: 5000000000`.
-   If it came from another address, run `fly-trader vault reclassify <sig> deposit`.
-3. The fly trades live after the handover: at least 20 paper trades.
-4. Settlements run every Monday at 00:00 UTC. Claims open from the first one.
+1. From a funding address, send **0.05 SOL to the trading wallet** (the `bot_key` address). It pays the fees of its own
+   refills and of claims.
+2. Send your principal to the **treasury** (the vault 0 address on the owner page) from a funding address. The fly
+   refills its 2 SOL float from it through L1 on its own.
+3. `server$ sudo fly vault status`: `"ledger": {"deposits": …}` must equal the SOL you sent from funding addresses. If
+   some came from another address, it counts as profit: `server$ sudo fly vault reclassify <signature> deposit`.
+4. The fly trades live after the handover (at least 20 paper trades). Settlements run every Monday 00:00 UTC; claims
+   open from the first one.
+5. When claims are larger than L2 allows in a week, Telegram says a claim is waiting. Raise L2 as in "Day to day".
+   Waiting claims never fail.
+
+## Emergency
+- **Something is wrong (possible compromise):**
+  1. On your phone, open the owner page and tap **Revoke L1 and L2 now**. From then on the server cannot move any SOL
+     out of the treasury; trading keeps only its float.
+  2. Send `/panic` to the bot. The fly halts; the signer refuses buys, top-ups and claims; open positions are sold; and
+     the float goes back to the treasury, all but the 0.3 SOL gas reserve.
+  3. If $FLY locking should stop too: MetaMask, Blockscout, FlyVault `pause()`.
+- **A key-read, halt, AIDE or setup-change alert:** look before resuming. Resuming is SSH-only:
+  ```
+  server$ sudo fly vault resume
+  server$ sudo fly reset-circuit --kill
+  server$ sudo fly resume-entries
+  server$ sudo fly signer clear-panic
+  ```
+- **Rebuild after losing the server:**
+  1. On the owner page, revoke L1 and L2 of the old keys.
+  2. Publish nothing; take the manifest sha256 of the current release:
+     `$ curl -sL https://huggingface.co/bryceweiner/fly-trader/resolve/main/release.json | shasum -a 256`.
+  3. New server: sections 4.2 (with that pin) to 4.4. On the owner page, clear the old L1/L2 fields and create new
+     limits for the new keys; put the new addresses in `custody.env`.
+  4. Restore the ledger. Download the newest `ledger/<day>.dump.age` from the backup bucket, then:
+     ```
+     $ age -d -i ~/fly-keys/fly-backup.key <day>.dump.age > ledger.dump
+     $ scp ledger.dump fly-vault: && rm ledger.dump
+     server$ sudo docker stop fly-fly-1                     # the brain must not write while the tables are replaced
+     server$ sudo docker exec -i fly-db-1 pg_restore -U fly -d fly_trader --clean < ledger.dump && rm ledger.dump
+     server$ sudo docker exec fly-db-1 psql -U fly -d fly_trader -c "DELETE FROM vault_kv WHERE key IN ('backup_key_done','custody','halt','panic')"
+     server$ sudo python3 /usr/local/lib/fly/fly_update.py restart
+     ```
+  5. The old trading wallet's float and positions: `$ age -d -i ~/fly-keys/fly-backup.key keys/trading-<address>.age`
+     gives its secret (base58, 64 bytes), which you can import into a wallet to move them to the treasury.
 
 ## Day to day
-- **New models or code:** run `publish_release.py`, with `--models` to refresh the models. The server applies the
-  release within 5 minutes. A release that changes Docker or compose files waits until you run
-  `sudo python3 /usr/local/lib/fly/fly_update.py approve <seq>` on the server.
-- **Take principal out:** `docker compose -p fly -f /srv/fly/docker-compose.yml exec fly fly-trader vault withdraw --sol X --to <funding address>`.
-- **A halt alert** (unknown transaction or anomaly):
-  1. Find the cause on the console's `$FLY vault` page.
-  2. Run `fly-trader vault resume`.
-  3. Run `fly-trader resume-entries`.
-- **Restore from backups:**
-  - Key: `age -d -i ~/.ssh/fly_release keys/<pubkey>.age`
-  - Ledger: `age -d … ledger/<day>.dump.age | pg_restore`
+- **Changing a limit** (e.g. raising L2 after a big settlement): on the owner page, "Set L2 to this amount". A new
+  limit has a **new address**, so put it in `/srv/fly/custody.env` and restart:
+  `server$ sudo python3 /usr/local/lib/fly/fly_update.py restart`. Until then claims wait. The same applies to any L1
+  change.
+- **After editing any `/srv/fly/*.env`:** `server$ sudo python3 /usr/local/lib/fly/fly_update.py restart`.
+- **New models or code:** publish as in 4.1 step 3 (`--models` to refresh the models).
+  - Model-only releases apply within 5 minutes; they cannot carry code (weights-only torch files, skops selectors).
+  - A release that changes **code** is held 24 h, and Telegram says so. To apply it now:
+    `server$ sudo python3 /usr/local/lib/fly/fly_update.py approve <seq>`. To stop it:
+    `server$ sudo python3 /usr/local/lib/fly/fly_update.py veto <seq>`. If you did not publish it, the release key is
+    compromised: remove it from `/etc/fly/allowed_signers` and rotate.
+  - A release that changes `deploy/`, `docker/`, the Dockerfile, `.dockerignore` or a compose file waits for
+    `approve`. It replaces only the compose file. For changed host scripts (bootstrap, `fly_update.py`,
+    `check-host.sh`, the watchers), copy them over and re-run the bootstrap **with `CLOSE_PUBLIC_SSH=1`** (without it
+    the bootstrap opens public SSH again); your recovery key is kept:
+    ```
+    $ scp -r ../fly-trader-dist/deploy ~/.ssh/fly-release.pub fly-vault:
+    server$ sudo CLOSE_PUBLIC_SSH=1 bash deploy/bootstrap-host.sh "$(cat fly-release.pub)"
+    ```
+  - To sign with the recovery key: decrypt it (`$ age -d ~/fly-keys/fly-release-recovery.age > /tmp/k && chmod 600
+    /tmp/k`), pass `--key /tmp/k`, then `rm /tmp/k`.
+- **Take principal out:** `server$ sudo fly vault withdraw` prints how much you may take and how. You send it from the
+  treasury in the Squads app with your owner wallet; the fly books and reports it.
+- **Watch it:** `/status` to the bot at any time. A daily report arrives at 09:00 UTC. If it does not, or
+  healthchecks.io alerts, the server or the fly is down. `server$ sudo fly vault status` gives the full ledger.
+- **After an AIDE alert** you expected (a release, apt upgrades): `server$ sudo aide --update` then
+  `server$ sudo cp /var/lib/aide/aide.db.new /var/lib/aide/aide.db`.
+- **Backups:** hot keys once, ledger nightly, both age-encrypted in the bucket. Until `VAULT_BACKUP_*` and the recipient
+  are set, Telegram reminds you daily. To read them:
+  - Hot keys: `$ age -d -i ~/fly-keys/fly-backup.key keys/<name>-<address>.age`
+  - Ledger: see "Rebuild", step 4.
+
+## Ledger (when you're home): no redeploys
+- **Solana:** in the Squads app, add the Ledger as a member, then remove Solflare (or keep both at threshold 2; the
+  owner page then proposes and approves, and the other member executes in the Squads app). L1 and L2 stay as they are.
+- **EVM:** move MetaMask's roles to the Ledger through the timelock (8 days):
+  1. Print the calldata:
+     ```
+     $ (cd contracts && VAULT=<vault> TIMELOCK=<timelock> OLD_OWNER=<MetaMask> NEW_OWNER=<Ledger> MODE=calldata \
+         forge script script/HandOver.s.sol --rpc-url robinhood)
+     ```
+  2. Send the printed "schedule" data from MetaMask to the timelock (Blockscout "Write contract", `scheduleBatch`, or
+     any raw-data send).
+  3. After 8 days, send the "execute" data from any wallet.
+- **SSH and releases:** add the Ledger's SSH key (ledger-agent) to `~fly-admin/.ssh/authorized_keys`. For releases,
+  make the Ledger's key the release key: re-run the bootstrap (as in "Day to day") with the Ledger's public key as the
+  argument (the bootstrap rewrites `/etc/fly/allowed_signers` from its arguments; a line added by hand would be lost),
+  and replace the `bryce` line in the distribution's `release/allowed_signers` (publish that change while the old key
+  still signs). Then remove the Secretive keys.

docs/vault/SPEC.md

@@ -1,11 +1,12 @@
 # $FLY vault — interface spec v1
 
-The contract between the four parts of the vault system. Change it here first, then in code.
+The contract between the parts of the vault system. Change it here first, then in code.
 
 - **FlyVault** (`contracts/`, Robinhood Chain): holds locked $FLY.
 - **The vault fly** (`fly_trader/vault/`, the hosted server): trades, keeps the ledger, settles weekly and pays claims.
+- **The signer** (`fly_trader/signer/`, its own container on the server): the only holder of the two hot keys (§6).
 - **The relay** (`web/relay/`, on the site's Gandi app): passes stats and claims between the fly and browsers.
-- **The site** (`web/`): the Trading and Vault pages.
+- **The site** (`web/`): the Trading, Vault and (unlisted) Owner pages.
 
 Units, everywhere:
 - SOL amounts are integer **lamports**.
@@ -19,18 +20,18 @@ Solidity `0.8.24+` on OpenZeppelin Contracts Upgradeable v5, using UUPS and ERC-
 (`fly.storage.FlyVault`). The constructor calls `_disableInitializers()`.
 
 ```solidity
-uint256 public immutable WITHDRAW_DELAY;   // constructor arg of the implementation: 7 days on mainnet (Deploy.s.sol refuses
-                                            // anything else on chain 4663); shorter on the testnet rehearsal. Changing it = an upgrade.
+uint256 public immutable WITHDRAW_DELAY;   // constructor arg of the implementation: 7 days on mainnet, 300 s by default
+                                            // on the rehearsal (DeployTestnet.s.sol). Changing it = an upgrade.
 bytes32 public constant PAUSER_ROLE   = keccak256("PAUSER_ROLE");
 bytes32 public constant UPGRADER_ROLE = keccak256("UPGRADER_ROLE");
 
-function initialize(address fly, address pauser, address timelock) external initializer;
+function initialize(address fly, address pauser, address timelock) external initializer;   // reverts on a zero address
 // DEFAULT_ADMIN_ROLE + UPGRADER_ROLE -> timelock ; PAUSER_ROLE -> pauser
 
-function lock(uint256 amount) external;                          // whenNotPaused; reverts unless received == amount
+function lock(uint256 amount) external;                          // whenNotPaused, nonReentrant; reverts unless received == amount
 function requestWithdrawal(uint256 amount) external returns (uint256 id);   // never paused
 function cancelRequest(uint256 id) external;                     // whenNotPaused (it re-locks)
-function withdraw(uint256 id) external;                          // never paused; block.timestamp >= readyAt
+function withdraw(uint256 id) external;                          // never paused, nonReentrant; block.timestamp >= readyAt
 function pause() external;   function unpause() external;        // PAUSER_ROLE
 
 function token() external view returns (address);
@@ -47,16 +48,29 @@ event WithdrawRequested(address indexed user, uint256 indexed id, uint256 amount
 event RequestCancelled(address indexed user, uint256 indexed id, uint256 amount, uint256 lockedAfter);
 event Withdrawn(address indexed user, uint256 indexed id, uint256 amount);
 // plus OZ: Paused(address), Unpaused(address), Upgraded(address indexed implementation), RoleGranted/RoleRevoked
+
+error ZeroAddress(); error ZeroAmount(); error TransferAmountMismatch(uint256 expected, uint256 received);
+error InsufficientLocked(uint256 requested, uint256 available); error UnknownRequest(uint256 id);
+error NotRequestOwner(uint256 id); error RequestNotPending(uint256 id); error WithdrawalNotReady(uint256 id, uint64 readyAt);
 ```
 
 - **Request ids** start at 1 and are global.
 - **`lockedAfter`** is the user's earning balance after the event, so the indexer can resync to an absolute value.
-- **Timelock.** Upgrades go through an OZ `TimelockController`:
-  - minDelay = 8 days
-  - proposer = canceller = the operator's hardware account
+- **Timelock.** Upgrades and role changes go through an OZ `TimelockController`:
+  - minDelay = 8 days on mainnet (600 s by default on the rehearsal)
+  - proposer = canceller = the owner (MetaMask until the Ledger takes over; `OWNER` in the deploy)
   - executor = anyone (`address(0)`)
-  - admin = `address(0)`
+  - admin = `address(0)`: the timelock administers itself, so role changes also wait the full delay
+- **Mainnet deploy rules.** On chain 4663 the deploy (`FlyVaultStack.enforceChainRules`) refuses anything but the real
+  $FLY, an 8-day timelock and a 7-day withdraw delay. `PAUSER` defaults to `OWNER`.
 - **No rescue function for FLY.** The token is set only in `initialize`.
+- **The fly indexes** the vault's events and the timelock's `CallScheduled`, `CallExecuted` and `Cancelled` for
+  operations aimed at the vault or the timelock (an alert and `vault.upgrade_scheduled`, §4.1).
+- **Scripts.**
+  - `HandOver.s.sol`: one timelock batch that grants PROPOSER, CANCELLER and PAUSER to a new owner and revokes them
+    from the old one. `MODE=schedule|execute`, or `MODE=calldata` to print the calldata for a browser wallet.
+  - `ScheduleUpgrade.s.sol` rehearses an upgrade locally and schedules `upgradeToAndCall`; `ExecuteUpgrade.s.sol` runs
+    it after the delay.
 
 ## 2. Claim messages (v1)
 
@@ -66,13 +80,15 @@ newline. Vectors: `tests/vectors/claim_v1.json`. Python (`fly_trader/vault/claim
 
 Fields:
 - `domain`: e.g. `fly-trader.app`, or `localhost:5173` on staging
-- `uri`: e.g. `https://fly-trader.app/vault.html`
+- `uri`: e.g. `https://fly-trader.app/vault.html`, or `http://localhost:5173/vault.html` on staging; https (http only
+  for localhost/127.0.0.1), no spaces or line breaks
 - `chain_id`: `4663`, or `46630` on testnet
 - `sol_chain`: `mainnet` or `devnet`
 - `evm`: EIP-55 checksummed
 - `sol`: base58 pubkey
 - `nonce`: 32 lowercase hex characters, issued by the relay
-- `issued_at`, `expires_at`: RFC 3339 `YYYY-MM-DDTHH:MM:SSZ`; expiry = issue + 900 s
+- `issued_at`, `expires_at`: RFC 3339 `YYYY-MM-DDTHH:MM:SSZ`; expiry = issue + 900 s. The fly accepts no other TTL, so
+  the relay's `claim_ttl_s` must stay 900.
 - `request_id`: always `fly-vault-claim-v1`
 
 EVM text, signed with `personal_sign` (EIP-191); the signature is `0x…` hex, 65 bytes for an EOA and up to 1024 bytes
@@ -108,60 +124,95 @@ Request ID: fly-vault-claim-v1
 ```
 
 What the fly checks:
-- **The texts.** It re-renders both texts from the fields and never uses text supplied by the relay.
+- **The texts.** Both are re-rendered from the fields; relay-supplied text is never used. `domain`/`uri` must equal
+  `VAULT_SITE_DOMAIN`/`VAULT_SITE_URI`, `chain_id` must equal `RH_CHAIN_ID`, and `sol_chain` must match `VAULT_CLUSTER`.
+- **Freshness.** A claim is rejected if the fly first stored it more than 3600 s after `expires_at`, or if `issued_at`
+  is more than 300 s in the future. The relay already refuses expired nonces at submission.
 - **The EVM signature.**
-  - Low-s, and v ∈ {27, 28} (0/1 are normalized).
-  - Recovered by ecrecover. If the address has code, it instead calls EIP-1271 `isValidSignature(hashMessage(text), sig) == 0x1626ba7e`.
-- **The Solana signature.** ed25519 over the text.
-- **The nonce.** Unique per EVM address and not expired.
-- **The amount.** Owed ≥ `CLAIM_MIN_LAMPORTS` (2,000,000).
-
-A valid claim pays **all** SOL owed to the EVM address, sent to `sol`.
+  - ecrecover first: exactly 65 bytes, 0 < r < n, low-s, v ∈ {27, 28} (0/1 are normalized).
+  - Only if that does not recover the address and the address has code: EIP-1271 `isValidSignature(hashMessage(text), sig)`
+    (65..1024 bytes, 200,000 gas cap) must return exactly `0x1626ba7e`.
+- **The Solana signature.** 64 bytes, ed25519 over the UTF-8 text; `sol` must be an on-curve pubkey.
+- **The nonce.** Unique per EVM address.
+- **One in flight.** A claim is rejected while another claim for the address is `verified | waiting_liquidity |
+  sending`.
+- **The amount.** Owed ≥ `CLAIM_MIN_LAMPORTS` (2,000,000), read when the claim moves to `sending`; the amount is fixed
+  then. The relay's `min_lamports` and the site's `claimMinLamports` must hold the same value.
+- **Halts.** Nothing is verified or paid while the vault is halted (claims are still pulled from the relay).
+
+A valid claim pays **all** SOL owed to the EVM address, sent to `sol` from the **treasury** (Squads vault 0) under
+spending limit L2 (§6): the payout key signs `spendingLimitUse` and the trading key pays the fee. Nothing is ever paid
+from the trading wallet's own SOL. Neither the treasury, the trading wallet nor any payout signature is published.
+
+**Statuses:** `received → verified → (waiting_liquidity) → sending → paid | rejected | failed`.
+- `waiting_liquidity`: L2 has too little left this week, the treasury is short, or the signer is in panic. The claim
+  retries every loop and alerts the operator; it never fails for these reasons.
+- `failed`: four unlanded attempts, a failure on chain, or a signer policy refusal.
+- The payment's signature and last valid block height are stored before broadcast; a claim is re-signed only once its
+  blockhash has expired unlanded, and the signer keeps its own once-per-claim ledger (§6).
 
 ## 3. Relay HTTP API (v1)
 
 The base is `{origin}/api`. Every response is JSON with `Cache-Control: no-store`. Errors look like `{"error": "<text>"}`
-with status 400, 401, 404, 409, 413, 429 or 503.
+with status 400, 401, 404, 405 (with `Allow`), 409, 413, 429 (with `Retry-After`), 500 or 503. 503 means either
+`relay not configured` (relay.json missing or invalid) or `storage unavailable` (SQLite error, with `Retry-After: 5`).
 
 ### Public
 
 - **`GET /api/stats`** returns the latest snapshot (§4), or 503 before the first push.
 - **`GET /api/history?kind=nav|trades|flows|settlements&before=<cursor>&limit=<1..500, default 100>`** returns
-  `{"kind", "items": [...], "next": <cursor|null>}`, newest first. The cursor is opaque; send it back as `before`.
-- **`GET /api/account?evm=0x…`** returns the account (§4.3). An unknown address gets all zeros.
+  `{"kind", "items": [...], "next": <cursor|null>}`, newest first by (time, id). The time is nav `ts`, trades
+  `closed_at`, flows `ts`, settlements `period_end`. The cursor is opaque; send it back as `before`. An unknown `kind`,
+  a bad `limit` or a bad cursor gets 400.
+- **`GET /api/account?evm=0x…`** returns the account (§4.3). `evm` is accepted in any case. An unknown address gets all
+  zeros; the fly pushes only addresses with at least one allocation.
 - **`GET /api/claim/challenge?evm=0x…&sol=<base58>`**:
   - Returns `{"nonce", "issued_at", "expires_at", "domain", "uri", "chain_id", "sol_chain", "request_id", "min_lamports"}`.
-  - The relay stores the challenge and checks the syntax of `evm` and `sol`.
+  - The relay stores the challenge; a bad `evm` or `sol` gets 400 (checked before the rate limit).
 - **`POST /api/claim`** with body `{"nonce", "evm", "sol", "evm_sig", "sol_sig"}` (≤ 4 KB):
   - Returns `202 {"id", "status": "received"}`.
   - Checks, all cheap and none cryptographic:
     - the nonce is known, unexpired, unused, and issued for this `evm` + `sol`
     - the signatures have valid syntax: `evm_sig` matches `^0x([0-9a-fA-F]{2}){65,1024}$`; `sol_sig` is base58 of 64 bytes
-    - the published account's owed ≥ min
-    - no claim for this EVM address is in flight
-  - 409 if the nonce was already used or a claim is in flight.
-- **`GET /api/claim/<id>`** returns `{"id", "status", "reason", "lamports", "tx", "created_at", "updated_at"}`.
+    - the published account's owed ≥ `min_lamports`
+    - no claim for this EVM address that the fly has verified is in flight (`verified | waiting_liquidity |
+      sending`). An unverified `received` claim does not block, since it may be a stranger's junk; the fly pays
+      each address at most once whatever the relay accepts.
+  - 400 for bad syntax, an unknown, expired or mismatched nonce, or nothing to claim; 409 if the nonce was already used
+    or a verified claim is in flight; 429 per the limits below.
+- **`GET /api/claim/<id>`** (the relay's id, 1-18 digits) returns `{"id", "status", "reason", "lamports", "tx",
+  "created_at", "updated_at"}`, or 404.
   - Status is one of `received | verified | waiting_liquidity | sending | paid | rejected | failed`.
-- **Rate limits (token buckets):**
+  - `tx` is always null: the fly never reports the payout signature.
+- **Rate limits (token buckets; a 429 carries `Retry-After`):**
   - challenge: 30 per hour per IP
-  - claim: 10 per hour per IP and 5 per hour per EVM address
-  - reads: 600 per hour per IP.
+  - claim: 10 per hour per IP, charged after the syntax checks; and 5 per hour per EVM address and IP, charged only
+    after every other check passes (so junk from one client cannot lock a holder out)
+  - reads (stats, history, account, claim/<id>): 600 per hour per IP
+  - IPv6 clients are bucketed per /64. Behind a proxy, `client_ip_header` names the header to read, and the relay takes
+    its rightmost entry (the one the proxy appended). The fly's HMAC routes are not rate-limited.
 
 ### Fly only (HMAC)
 
 - **`POST /api/fly/push`**: upserts.
   - Body: `{"stats": {…§4…}?, "history": {"nav": [...], "trades": [...], "flows": [...], "settlements": [...]}?, "accounts": [ …§4.3… ]?}`.
-  - History items upsert by `id` (nav by `ts`); accounts upsert by `evm`.
+  - Unknown top-level keys get 400. History items upsert by `id` (nav by `ts`); each needs an integer time field (nav
+    `ts`; trades `closed_at` or `opened_at`; settlements `period_end` or `period_start`; flows `ts`) and, except nav, an
+    `id` (an integer ≥ 0 or a string ≤ 200 characters). Accounts upsert by `evm` and need an integer `owed`. `stats` is
+    stored as is; NaN and Infinity become null.
   - Returns `{"ok": true}`. Body ≤ 2 MB.
-- **`GET /api/fly/claims?after=<id>&limit=<1..50>`**:
+- **`GET /api/fly/claims?after=<id, default 0>&limit=<1..50, default 50>`**:
   - Returns `{"claims": [{"id", "nonce", "evm", "sol", "evm_sig", "sol_sig", "domain", "uri", "chain_id", "sol_chain", "issued_at", "expires_at", "created_at"}]}`.
-  - Only claims in status `received`, in id order.
-- **`POST /api/fly/claims/result`**: body `{"results": [{"id", "status", "reason"?, "lamports"?, "tx"?}]}` returns `{"ok": true}`.
-- **`GET /api/fly/probe`** returns `{"python", "db_path", "writable", "wal", "pid", "remote_addr", "headers": {...}}`.
+  - Only claims in status `received`, in id order. `evm` is lowercase; `created_at` is unix seconds.
+- **`POST /api/fly/claims/result`**: body `{"results": [{"id", "status", "reason"?, "lamports"?, "tx"?}]}` returns
+  `{"ok": true}`. `status` must be one of the seven statuses; `reason` is cut to 500 characters; omitted fields keep
+  their value; unknown ids are ignored.
+- **`GET /api/fly/probe`** returns `{"python", "db_path", "writable", "wal", "pid", "remote_addr", "headers": {...},
+  "sqlite", "time", "client_ip", "multiprocess", "multithread"}` (headers: every `HTTP_*` except Cookie).
 
 HMAC headers:
 - `X-Fly-Key`: the key id
-- `X-Fly-Ts`: unix seconds
+- `X-Fly-Ts`: unix seconds (1-15 digits)
 - `X-Fly-Nonce`: 32 hex characters
 - `X-Fly-Sig`: hex HMAC-SHA256(key = the UTF-8 bytes of the configured secret string, canonical)
 
@@ -169,12 +220,15 @@ The canonical string:
 ```
 FLY-RELAY-1\n{METHOD}\n{PATH}\n{QUERY}\n{TS}\n{NONCE}\n{sha256hex(body)}
 ```
-- `PATH` excludes the query string.
+- `PATH` starts at `/api/…` and excludes the query string.
 - `QUERY` is `&`.join(`quote(k,safe='')=quote(v,safe='')` for (k, v) in sorted(parse_qsl(qs, keep_blank_values=True))).
 - The body is the raw bytes; an empty body hashes as sha256 of `b""`.
-- The timestamp must be within ±300 s. Nonces are remembered for 15 minutes, and a reused nonce gets 401.
+- The timestamp must be within ±300 s. Nonces are remembered for 15 minutes (case-insensitively), and a reused nonce
+  gets 401. The body is verified before the nonce is recorded.
 
-Relay config: `relay.json`, kept next to `wsgi.py` and never inside `site/`:
+Relay config: `relay.json`, kept next to `wsgi.py` and never inside `site/`, or wherever `FLY_RELAY_CONFIG` points. It
+is re-read when it changes; a relative `db_path` is resolved against its folder. Secrets must be at least 32 characters
+(64 hex recommended).
 ```json
 {"keys": {"k1": "<64 hex>"}, "db_path": "<writable path>", "domain": "fly-trader.app", "uri": "https://fly-trader.app/vault.html",
  "chain_id": 4663, "sol_chain": "mainnet", "claim_ttl_s": 900, "min_lamports": 2000000, "client_ip_header": null}
@@ -182,33 +236,56 @@ Relay config: `relay.json`, kept next to `wsgi.py` and never inside `site/`:
 
 ## 4. Payloads
 
-### 4.1 Stats snapshot (`stats`, pushed every 60 s)
+### 4.1 Stats snapshot (`stats`, pushed every vault-worker loop, about every 10 s)
 ```json
 {
- "v": 1, "ts": 0, "cluster": "mainnet",
- "fly": {"state": "starting|paper|live|halted", "wallet": "<base58>", "handover": false, "kill_switch": false,
+ "v": 1, "ts": 0, "book": "live", "cluster": "mainnet",
+ "fly": {"state": "starting|paper|live|halted", "handover": false, "kill_switch": false,
          "entries_paused": false, "model": {"fly": 62, "selector": 59, "release": 3}},
- "wallet": {"native": 0, "token_accounts": 0, "open_cost": 0, "positions_value": 0, "exit_cost": 0, "nav": 0},
+ "wallet": {"native": 0, "nav": 0},
  "ledger": {"deposits": 0, "withdrawals": 0, "claims_paid": 0, "realized": 0, "booked_realized": 0,
             "allocated": 0, "reserved": 0, "pot": 0},
  "prices": {"sol_usd": 0.0, "fly_usd": 0.0, "ts": 0},
  "vault": {"address": "0x…", "chain_id": 4663, "total_locked": "0", "total_pending": "0", "earners": 0,
            "finalized_block": 0, "paused": false, "impl": "0x…", "upgrade_scheduled": null},
- "settlement": {"next_at": 0, "last": null},
- "positions": [{"mint": "", "symbol": "", "opened_at": 0, "cost": 0, "value": 0, "entry_price": 0.0, "mark_price": 0.0, "hold_min": 0}],
- "index": {"value": 1.0, "peak": 1.0, "drawdown": 0.0}
+ "settlement": {"last": null}
 }
 ```
-- `wallet.nav` = native + token_accounts + positions_value − exit_cost.
-- `ledger.realized` is R. `pot` = max(0, R − allocated). `reserved` = allocated − claims_paid.
-- `settlement.last` is a settlements item (§4.2) or null.
-- `vault.upgrade_scheduled` is `{"eta": ts, "id": "0x…"}` or null.
+- **Nothing that helps trade ahead of the fly.** `ts` is rounded down to the hour; `wallet.native` and `wallet.nav`
+  come from the last 5-minute mark and are rounded to 0.1 SOL (NAV history points likewise), so one buy cannot be
+  matched to an on-chain trade; `ledger.realized` is R at that same mark. Open positions, the performance index and
+  the next settlement time are not published; a trade appears in `trades` history once it closes. No address of the
+  fly's (trading wallet, treasury, keys) is published, nor anything that leads to one: no transaction signatures and no
+  deposit senders.
+- `book` is `VAULT_BOOK` (`live`, or a paper book such as `paper_fly` on a dry run). `cluster` is `mainnet` or
+  `VAULT_CLUSTER` as is.
+- `fly.state`: `halted` if the vault is halted or the kill switch is on; `live` after the handover once the live wallet
+  reports; `paper` once the fly reports status; else `starting`. `fly.model` = `{fly, selector, release}`, each may be
+  null.
+- `wallet.native` = trading wallet + treasury lamports; `wallet.nav` = native + open positions' value − exit cost.
+- `ledger`: `realized` is R (§7); `pot` = max(0, R − allocated); `reserved` = max(0, allocated − claims_paid);
+  `booked_realized` is the book's summed closed-trade profit; `deposits`, `withdrawals` (fees included) and
+  `claims_paid` are running totals. On a paper book `realized` is closed-trade profit since the vault started and
+  `deposits` is `CAPITAL_SOL`.
+- `prices`: `sol_usd` from Jupiter Price v3, `fly_usd` from the GeckoTerminal pool, cached 60 s (a failed fetch keeps
+  the last value); `ts` is the older of the two fetch times, or 0.
+- `vault`: `total_locked`, `total_pending`, `earners` and `paused` come from events in finalized blocks (about 18 minutes
+  behind the head), up to `finalized_block`. `address` is null until `VAULT_ADDRESS` is set.
+- `settlement.last` is the newest `allocated` settlement (§4.2), or null.
+- `vault.upgrade_scheduled` is `{"eta": ts, "id": "0x…"}` or null: the soonest pending timelock operation whose target is the
+  vault (upgrade, role change) or the timelock itself (`updateDelay`, proposer changes). `eta` is the block time of
+  `CallScheduled` plus its `delay`.
 
 ### 4.2 History items
-- `nav`: `{"ts", "nav", "index", "sol_usd"}`
-- `trades`: `{"id", "mint", "symbol", "opened_at", "closed_at", "cost", "proceeds", "realized", "exit_kind"}`
-- `flows`: `{"id", "ts", "signature", "direction": "in|out", "kind": "deposit|profit|withdrawal|claim", "counterparty", "lamports"}`
-- `settlements`: `{"id", "period_start", "period_end", "realized", "pot", "allocated", "carried", "earners", "total_weight": "<str>", "status"}`
+- `nav`: `{"ts", "nav", "sol_usd"}`: one point per 5-minute boundary (`ts`), from the newest consistent mark at or before
+  it, nav rounded to 0.1 SOL; `sol_usd` is the price at push time.
+- `trades`: `{"id", "mint", "symbol", "opened_at", "closed_at", "cost", "proceeds", "realized", "exit_kind"}`: closed
+  positions of `VAULT_BOOK` only; `proceeds` = cost + realized; `exit_kind` is the forced-exit kind or `hold`.
+- `flows`: `{"id", "ts", "direction": "in|out", "kind": "deposit|profit|withdrawal|claim", "lamports"}`. Internal moves
+  (`sweep`, `topup`) and `unknown_outbound`/`anomaly` rows are never published.
+- `settlements`: `{"id", "period_start", "period_end", "realized", "pot", "allocated", "carried", "earners",
+  "total_weight": "<str>", "status"}`: `status` is always `allocated`; `carried` = pot − allocated; `total_weight` is
+  the sum of wei·seconds; `realized` is R at the snapshot.
 
 ### 4.3 Account
 ```json
@@ -216,15 +293,114 @@ Relay config: `relay.json`, kept next to `wsgi.py` and never inside `site/`:
  "allocations": [{"period_end": 0, "lamports": 0, "weight": "<str>", "share": 0.0}],
  "claims": [{"id": 0, "status": "", "lamports": 0, "sol": "", "tx": "", "created_at": 0, "updated_at": 0}]}
 ```
-`owed` = allocated − claimed − in_flight, where in_flight counts claims in `verified | waiting_liquidity | sending`.
+- `owed` = allocated − claimed − in_flight. `in_flight` counts claims from `sending` on (a `verified` claim has no amount
+  yet).
+- `allocations`: the 52 most recent; `share` = weight / that settlement's total weight.
+- `claims`: the 20 most recent; `id` is the relay's claim id (as in `GET /api/claim/<id>`); `tx` is always `""`.
 
 ## 5. Networks
 
 | | mainnet | rehearsal |
 |---|---|---|
+| Site build | `VITE_NETWORK=mainnet` (default) | `VITE_NETWORK=testnet` |
 | EVM chain | Robinhood Chain 4663, `https://rpc.mainnet.chain.robinhood.com` | RH testnet 46630, `https://rpc.testnet.chain.robinhood.com` |
 | Explorer | `https://robinhoodchain.blockscout.com` | `https://explorer.testnet.chain.robinhood.com` |
 | $FLY | `0x2fC7f9E2911f20b2C4660d2AEf808aa91bDdb3D3` | `MockFLY` (deployed for the rehearsal) |
+| USDG | `0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168` (6 decimals) | — |
+| Multicall3 | `0xcA11bde05977b3631167028862bE2a173976CA11` | same |
 | Solana | mainnet-beta | devnet |
+| Squads v4 | `SQDS4ep65T869zMMBKyuUq6aD6EgTu8psMjkvj52pCf` | same |
+| Settlement period | 7 days (`VAULT_PERIOD_S=604800`) | 900 s |
 | Kyber | `https://aggregator-api.kyberswap.com/robinhood/api/v1/`, router `0x6131B5fae19EA4f9D964eAc0408E4408b66337b5` | — |
 | Chart | GeckoTerminal network `robinhood`, pool `0xe6925f7bdedf22c2714c749d0ff208ce9e4bc1540938fa2b9ab2379486322edd` | fixtures |
+
+- The fly's defaults are mainnet. A rehearsal sets `RH_CHAIN_ID=46630`, `RH_RPC_URL`, `VAULT_CLUSTER=devnet`,
+  `VAULT_SOLANA_RPC_URL`, `VAULT_PERIOD_S=900` and `VAULT_SITE_DOMAIN`/`VAULT_SITE_URI`.
+- The site's Solana RPC (the Owner page) is WalletConnect's unless `VITE_SOLANA_RPC` is set.
+
+## 6. Custody (Solana)
+
+The fly's SOL is one book in two accounts:
+- **The treasury** is vault 0 of a Squads v4 multisig. Its members are the owner's wallets only (Solflare until the
+  Ledger takes over); threshold 1 and no time lock while there is one member.
+- **The trading wallet** is a hot key that keeps a float of about `TREASURY_FLOAT_SOL` (default 2 SOL).
+
+| Spending limit | Member | Destinations | Period | Used for |
+|---|---|---|---|---|
+| L1 | trading key | the trading wallet only | Day | refilling the float (`topup` flows, memo `fly-topup`) |
+| L2 | payout key | any | Week | claims (`spendingLimitUse` from the treasury, memo `fly-vault-claim:<fly claim id>:<nonce>`) |
+
+- **Rebalancing** (every minute, `vault/payout.py`): first the treasury must hold everything owed plus its 890,880-lamport
+  rent minimum, sweeping from the trading wallet if it is short; then the trading wallet is brought to the float, by a
+  top-up under L1 when low or a sweep when high. Moves under `TOPUP_MIN_SOL` (0.1) are skipped, except a sweep the
+  treasury needs. A sweep never takes the trading wallet below `GAS_RESERVE_SOL` + fee. Under `/panic` the float target
+  is 0.
+- **Flows.** A trading → treasury transfer is a `sweep`, a treasury → trading one a `topup`: both internal, excluded
+  from R, the index and published history. SOL or wSOL arriving at either account from `FUNDING_ADDRESSES` is a
+  `deposit`; from anyone else it is `profit` (a gift). A treasury outflow signed by a multisig member is a `withdrawal`
+  (the owner's principal; alerted, louder when the destination is not a funding address). A transaction one of our
+  keys signed that no table knows is `unknown_outbound`; lamports leaving without our or an owner's signature are an
+  `anomaly`. Both halt the vault (§7), unless the second RPC provider sees the transaction differently.
+- **Accounting.** R, NAV and the performance index count both accounts together. Positions are sized on the bankroll
+  = trading free SOL + open positions at cost + (treasury − owed); buys spend only the trading wallet's own SOL, less
+  any owed SOL the treasury does not hold.
+- **The signer** (`fly_trader/signer`) is the only holder of the two hot keys. It builds and signs:
+  - Jupiter swaps: SOL ↔ one token only; Metis routes only (`excludeRouters=jupiterz,dflow,okx`); static rules on every
+    instruction (programs, the trading wallet's roles, a priority-fee cap of `SIGNER_MAX_PRIORITY_SOL`, 0.005); a
+    simulation, through its own RPC, of the trading wallet's SOL and every token account it owns (a buy may spend at
+    most the ordered SOL plus fees and must deliver the token to the trading wallet; a sell may spend at most the
+    ordered tokens and must return SOL; no other holding may shrink); a value floor of `SIGNER_MIN_VALUE_RATIO` (0.6)
+    at the signer's own Jupiter prices. Buys are capped per trade (`SIGNER_MAX_BUY_SOL`, default `MAX_POSITION_SOL`) and
+    per day (`SIGNER_DAILY_BUY_SOL`, 10); all swaps per minute (`SIGNER_SWAPS_PER_MIN`, 6).
+  - top-ups under L1 (at most `TREASURY_FLOAT_SOL` each; L1's destinations must be exactly the trading wallet) and
+    sweeps (a plain transfer to the treasury)
+  - claims under L2, once per claim id, with the same destination and amount; re-signed only after the earlier
+    signature failed or its blockhash expired
+  - closes of empty token accounts of the trading wallet (batches of 10)
+  - the hot keys, age-encrypted to `VAULT_BACKUP_RECIPIENT`, for the off-box backup
+  - after `panic`: no buys, top-ups or claims; `clear-panic` is a CLI command inside its container only
+
+  On the server the brain reaches it over a Unix socket (one JSON request per line, 256 KB max, one at a time) and never
+  sees a key. The signer keeps its own SQLite ledger. Without `SIGNER_SOCKET` (self-hosting, tests) the same signer runs
+  inside the brain's process.
+- **Custody checks** (every minute, `vault/custody.py`), alerted: neither server key is a multisig member; no config
+  authority; L1 is a SOL limit with member = the trading key and sole destination = the trading wallet; L2 is a SOL
+  limit with member = the payout key. Any change to members, threshold, time lock or the limits is reported.
+- **The owner** changes the limits from `owner.html` (`web/src/lib/squads.ts`). Every new limit has a fresh address:
+  the server's `VAULT_LIMIT_TRADING` / `VAULT_LIMIT_PAYOUT` must be updated to it (the page prints the lines). A
+  limit's amount is changed by removing it and adding a new one, in two config transactions: the program rejects both
+  in one.
+
+## 7. Settlement, halts, kill switch
+
+- **Schedule.** Period ends fall at `VAULT_EPOCH + k·VAULT_PERIOD_S` (345600 = Monday 1970-01-05 00:00 UTC; 7 days).
+  The first settlement covers the period before the first end after the vault started; missed periods are settled as
+  one window. Settlements advance one step per minute, in period order.
+- **Two phases.**
+  1. Snapshot at the period end T1: both accounts at a finalized slot that contains every transaction the fly sent,
+     read under the wallet lock. The second RPC provider (`SOLANA_CHECK_RPC_URL`) must report the same balance, or the
+     settlement pauses, alerts and retries. Flows are scanned up to that slot.
+  2. Allocate once Robinhood Chain is finalized past T1, and only if the vault's implementation code hash is in
+     `VAULT_IMPL_CODEHASHES` (else the vault halts).
+
+  Statuses: `snapshotted | allocated | failed`.
+- **Formulas.**
+  ```
+  R   = N + K + C − D + Wd + P       N: both accounts' SOL; K: wSOL and empty token-account rent; C: open positions at
+                                     cost; D: deposits; Wd: withdrawals incl. fees; P: claims paid
+  pot = max(0, R − A)                A: everything ever allocated
+  out = min(pot, N − (A − P) − GAS_RESERVE_SOL)
+  weight_i = ∫ lockedAfter_i dt over [T0, T1)   (wei·s, from FlyVault events)
+  alloc_i  = floor(out · weight_i / Σ weight); the remainder, dust and empty weeks carry forward (A grows only by alloc)
+  ```
+- **Halts.** The vault halts on `unknown_outbound`, `anomaly`, an unknown implementation code hash, or Telegram
+  `/panic` (the operator's user only). A halt stops claim processing, settlement and new entries. `/panic` also trips
+  the kill switch with liquidation, sets the float target to 0 and puts the signer in panic. Resume is SSH-only:
+  `fly-trader vault resume` (clears halt and panic), `fly-trader reset-circuit --kill`, `fly-trader resume-entries`,
+  and the signer's `clear-panic`.
+- **Kill switch.** A flow-adjusted index `I_t = I_{t−1}·(W_t − F_t)/W_{t−1}` over consistent NAV marks of both
+  accounts, where F is every deposit/profit in and withdrawal/claim out since the previous mark. Its peak uses marks at
+  least 600 s old, over 30 days. It trips at `KILL_SWITCH_DRAWDOWN` (default 0.30; the vault server sets 0.20) and, with
+  `KILL_SWITCH_LIQUIDATE`, sells every open position.
+- **Principal withdrawal.** Only the owner, from the Squads app. The cap `fly-trader vault withdraw` prints is
+  min(D − Wd + min(0, R − A), treasury − owed − 890,880).

fly_trader/__main__.py

@@ -144,7 +144,8 @@ def _cmd_fly_replay(args):
     from .logging_setup import setup
     from .train import fly_replay
     setup("train"); _use_device(args)
-    out = fly_replay.main(days=args.days, start_day=args.start_day if args.start_day is not None else fly_replay.DEFAULT_START)
+    out = fly_replay.main(days=args.days, start_day=args.start_day if args.start_day is not None else fly_replay.DEFAULT_START,
+                          only_chains=tuple(args.chains.split(",")) if args.chains else None)
     print(json.dumps({k: out.get(k) for k in ("S", "passed", "reason", "alpha", "half_life_days", "evaluation", "random", "frozen", "plastic_beats_frozen")}, indent=1, default=str))
 
 
@@ -183,6 +184,123 @@ def _cmd_worker(args):
     procs.worker_cli(args.action, args.name)
 
 
+def _cmd_kalshi_history(args):
+    from .kalshi import history
+    history.main()
+
+
+def _cmd_kalshi_build(args):
+    from .kalshi import mature
+    mature.main()
+
+
+def _cmd_kalshi_train_selector(args):
+    from .kalshi import selector
+    from .logging_setup import setup
+    setup("kalshi_train")
+    out = selector.main(days=args.days, holdout_days=args.holdout_days)
+    print(json.dumps({k: out.get(k) for k in ("snapshot_id", "deployable", "deploy_reason")}, indent=1, default=str))
+
+
+def _cmd_kalshi_train_fly(args):
+    from .kalshi import fly
+    from .logging_setup import setup
+    setup("kalshi_train"); _use_device(args)
+    out = fly.main(days=args.days, epochs=args.epochs)
+    print(json.dumps({k: out.get(k) for k in ("snapshot_id", "S", "lines", "calibration", "diagnostics", "gates_ok", "gate_failures", "teacher")}, indent=1, default=str))
+
+
+def _cmd_kalshi_fly_replay(args):
+    from .kalshi import fly_replay
+    from .logging_setup import setup
+    setup("kalshi_train"); _use_device(args)
+    out = fly_replay.main(days=args.days, start_day=args.start_day if args.start_day is not None else fly_replay.DEFAULT_START,
+                          only_chains=tuple(args.chains.split(",")) if args.chains else None)
+    print(json.dumps({k: out.get(k) for k in ("S", "passed", "reason", "alpha", "half_life_days", "evaluation", "random", "frozen", "plastic_beats_frozen")}, indent=1, default=str))
+
+
+def _cmd_kalshi_train(args):
+    from .kalshi import pipeline
+    pipeline.main()
+
+
+def _cmd_kalshi_stream(args):
+    from .kalshi import stream
+    stream.main()
+
+
+def _cmd_kalshi_run(args):
+    from .kalshi import engine
+    engine.main()
+
+
+def _cmd_kalshi_subaccount(args):
+    from .kalshi import client
+    if args.action == "create":
+        print(f"subaccount {client.subaccount_create()} created and written to .env")
+    else:
+        print(json.dumps(client.rest().subaccount_balances(), indent=1, default=str))
+
+
+def _cmd_kalshi_fund(args):
+    from .kalshi import client
+    print(json.dumps(client.fund(args.usd), indent=1, default=str))
+
+
+def _cmd_rh_backfill(args):
+    from .rh import stream
+    stream.main()
+
+
+def _cmd_rh_status(args):
+    from .rh import stream
+    print(json.dumps(stream.status(), indent=1, default=str))
+
+
+def _cmd_rh_probe(args):
+    from .rh import probe
+    print(json.dumps(probe.run(sample=args.sample), indent=1, default=str))
+
+
+def _cmd_rh_wallet(args):
+    from .rh import smoke
+    if args.action == "new":
+        print(f"RH bot wallet {smoke.new_key()} written to .env (RH_BOT_PRIVATE_KEY, RH_BOT_ADDRESS). Fund it with ETH on Robinhood Chain.")
+    else:
+        from . import config
+        from .rh.rpc import RhRpc
+        addr = (config.RH_BOT_ADDRESS or "").lower()
+        print(json.dumps({"address": addr or None, "eth": RhRpc().get_balance(addr) / 1e18 if addr else None,
+                          "live_prerequisites_missing": config.rh_live_prerequisites_missing()}, indent=1))
+
+
+def _cmd_rh_smoke(args):
+    if not args.yes:
+        raise SystemExit("rh-smoke sends real Robinhood Chain transactions: pass --yes")
+    from .rh import smoke
+    print(json.dumps(smoke.run(args.size, args.cap), indent=1, default=str))
+
+
+def _cmd_kalshi_status(args):
+    from .kalshi import client
+    print(json.dumps(client.status(), indent=1, default=str))
+
+
+def _cmd_kalshi_pause(args):
+    from .agent import rails
+    rails.set_entries_paused(True, rails.KALSHI_CIRCUIT)
+
+
+def _cmd_kalshi_resume(args):
+    from .agent import rails
+    rails.set_entries_paused(False, rails.KALSHI_CIRCUIT)
+
+
+def _cmd_kalshi_reset_circuit(args):
+    from .agent import rails
+    rails.reset_circuit(kill=args.kill, circuit_id=rails.KALSHI_CIRCUIT)
+
+
 def build_parser() -> argparse.ArgumentParser:
     p = argparse.ArgumentParser(prog="fly-trader")
     sub = p.add_subparsers(dest="command", required=True)
@@ -211,6 +329,7 @@ def build_parser() -> argparse.ArgumentParser:
     fr.add_argument("--start-day", type=int, default=None,
                     help="day index of the bootstrap (the selector teaches on the days before it); default: train/fly_replay.DEFAULT_START, "
                          "the earliest day that leaves the teacher's walk-forward enough days in each half")
+    fr.add_argument("--chains", default=None, help="store the verdict of these chains only (comma list, e.g. rh); the others keep theirs")
     fr.set_defaults(fn=_cmd_fly_replay)
     bc = sub.add_parser("backtest-corpus"); bc.add_argument("--max-tokens", type=int, default=None); bc.add_argument("--days", type=int, default=None)
     bc.add_argument("--fees", default="0.003,0.0055"); bc.add_argument("--only", default=None); bc.add_argument("--universe", default="graduation", choices=["graduation", "mature"]); bc.set_defaults(fn=_cmd_backtest_corpus)
@@ -229,9 +348,42 @@ def build_parser() -> argparse.ArgumentParser:
     ar.add_argument("dir"); ar.add_argument("--bootstrap", action="store_true"); ar.set_defaults(fn=_cmd_apply_release)
     sub.add_parser("health", help="exit 0 when the database answers and workers run (container HEALTHCHECK)").set_defaults(fn=_cmd_health)
     sub.add_parser("ready-for-restart", help="exit 0 when no order, claim payment or settlement is in flight").set_defaults(fn=_cmd_ready)
+    mc = sub.add_parser("models", help="convert: rewrite this machine's own .joblib selectors as .skops (pickles can run code)")
+    mc.add_argument("action", choices=["convert"]); mc.set_defaults(fn=_cmd_models)
     from .vault import cli as vault_cli
     vault_cli.add(sub)
     wk = sub.add_parser("worker"); wk.add_argument("action", choices=["start", "stop", "status"]); wk.add_argument("name", nargs="?"); wk.set_defaults(fn=_cmd_worker)
+    # ---- Kalshi prediction markets (fly_trader/kalshi) ----
+    ks = sub.add_parser("kalshi-subaccount", help="create the fly's dedicated Kalshi subaccount (writes KALSHI_SUBACCOUNT to .env) or list balances")
+    ks.add_argument("action", choices=["create", "list"]); ks.set_defaults(fn=_cmd_kalshi_subaccount)
+    kf = sub.add_parser("kalshi-fund", help="move dollars from the primary Kalshi account into the fly's subaccount"); kf.add_argument("--usd", type=float, required=True); kf.set_defaults(fn=_cmd_kalshi_fund)
+    sub.add_parser("rh-backfill", help="the Robinhood Chain index from Pons V2's deployment to the head, then live (the rh_stream worker)").set_defaults(fn=_cmd_rh_backfill)
+    sub.add_parser("rh-status", help="Robinhood Chain index cursors, row counts and stream status").set_defaults(fn=_cmd_rh_status)
+    rp = sub.add_parser("rh-probe", help="read-only check of the Robinhood Chain path: contracts, Kyber / v4 routability and gas on recent Pons graduates")
+    rp.add_argument("--sample", type=int, default=12); rp.set_defaults(fn=_cmd_rh_probe)
+    rw = sub.add_parser("rh-wallet", help="new: create the RH bot key in .env (refuses to replace one); show: its address, ETH and what live trading still needs")
+    rw.add_argument("action", choices=["new", "show"]); rw.set_defaults(fn=_cmd_rh_wallet)
+    rs = sub.add_parser("rh-smoke", help="three tiny real RH round trips (Kyber, v4 fallback, non-ETH quote) booked and reconciled to the wei")
+    rs.add_argument("--size", type=float, default=0.002); rs.add_argument("--cap", type=float, default=0.01); rs.add_argument("--yes", action="store_true")
+    rs.set_defaults(fn=_cmd_rh_smoke)
+    sub.add_parser("kalshi-status", help="exchange status, subaccount balance, resting orders, positions, settlements").set_defaults(fn=_cmd_kalshi_status)
+    sub.add_parser("kalshi-history", help="the Kalshi corpus worker: dataset seed, settled markets, candles, trades").set_defaults(fn=_cmd_kalshi_history)
+    sub.add_parser("kalshi-build", help="build the Kalshi feature parts from the corpus").set_defaults(fn=_cmd_kalshi_build)
+    kts = sub.add_parser("kalshi-train-selector", help="fit the Kalshi strategy stack walk-forward and save it"); kts.add_argument("--days", type=int, default=None)
+    kts.add_argument("--holdout-days", type=int, default=None, help="last days withheld from every fit and scored once (default 21)")
+    kts.set_defaults(fn=_cmd_kalshi_train_selector)
+    ktf = sub.add_parser("kalshi-train-fly", help="bootstrap the Kalshi fly (optic lobes) from the deployable Kalshi selector")
+    ktf.add_argument("--days", type=int, default=None); ktf.add_argument("--epochs", type=int, default=None); ktf.add_argument("--device", default=None)
+    ktf.set_defaults(fn=_cmd_kalshi_train_fly)
+    kfr = sub.add_parser("kalshi-fly-replay", help="bootstrap the Kalshi fly once, let it learn from settlements over the corpus, judge it")
+    kfr.add_argument("--days", type=int, default=None); kfr.add_argument("--device", default=None); kfr.add_argument("--start-day", type=int, default=None)
+    kfr.set_defaults(fn=_cmd_kalshi_fly_replay)
+    sub.add_parser("kalshi-train", help="the Kalshi training pipeline worker (selector weekly, fly bootstrap when needed)").set_defaults(fn=_cmd_kalshi_train)
+    sub.add_parser("kalshi-stream", help="the Kalshi live feed worker (websocket → kalshi_minutes / kalshi_quotes)").set_defaults(fn=_cmd_kalshi_stream)
+    sub.add_parser("kalshi-run", help="the Kalshi trading engine worker (the visual fly's paper arms, live mirror behind KALSHI_LIVE_ENABLED)").set_defaults(fn=_cmd_kalshi_run)
+    sub.add_parser("kalshi-pause-entries").set_defaults(fn=_cmd_kalshi_pause)
+    sub.add_parser("kalshi-resume-entries").set_defaults(fn=_cmd_kalshi_resume)
+    kr = sub.add_parser("kalshi-reset-circuit"); kr.add_argument("--kill", action="store_true"); kr.set_defaults(fn=_cmd_kalshi_reset_circuit)
     return p
 
 
@@ -248,6 +400,12 @@ def _cmd_health(args) -> None:
     raise SystemExit(0 if ok else 1)
 
 
+def _cmd_models(args) -> None:
+    from .train import model_io
+    for r in model_io.convert_legacy():
+        print(f"selector #{r['id']} -> {r['path']}")
+
+
 def _cmd_ready(args) -> None:
     from .ops import release
     ok, why = release.ready_for_restart(); print(why)

fly_trader/agent/fly_live.py

@@ -79,15 +79,18 @@ class LiveMirror:
         opens = ledger.open_positions(conn, BOOK); held_mints = {p["mint"] for p in opens} | set(inflight)
         c = rails.load_circuit(conn)
         blocked = "kill switch" if c.kill_switch else "circuit tripped" if c.tripped else "paused" if c.entries_paused else None
-        reserved = 0.0
-        if config.VAULT_ENABLED:                     # SOL owed to vault lockers stays in the wallet but is never traded
+        reserved = treasury = 0.0
+        if config.VAULT_ENABLED:                     # SOL owed to vault lockers is never traded; the treasury's idle SOL is bankroll
             from ..vault import nav as vault_nav
-            reserved = vault_nav.reserved_lamports(conn) / config.LAMPORTS_PER_SOL
-        bankroll = sol_free + sum(float(p["cost_sol"]) for p in opens) - reserved; cash = sol_free - reserved; n_enter = 0; skipped = []
+            reserved = vault_nav.reserved_in_trading(conn) / config.LAMPORTS_PER_SOL
+            treasury = vault_nav.treasury_free(conn) / config.LAMPORTS_PER_SOL
+        # sized on the whole book, spent only from the trading wallet's own float (cash)
+        bankroll = sol_free + sum(float(p["cost_sol"]) for p in opens) - reserved + treasury; cash = sol_free - reserved; n_enter = 0; skipped = []
         for e in entries:
             if e["mint"] in held_mints:
                 skipped.append((e["mint"], "held")); continue
-            size, why = sizing.size_position(e["score"], e.get("threshold", line), e.get("table") or table or [], bankroll, cash, e["info"]["resq"])
+            size, why = sizing.size_position(e["score"], e.get("threshold", line), e.get("table") or table or [], bankroll, cash, e["info"]["resq"],
+                                             flat=config.FLY_SIZING == "flat")
             if blocked or size <= 0:
                 skipped.append((e["mint"], blocked or why)); continue
             if self.worker.submit(ExecRequest(decision_id=e["decision_id"], mint=e["mint"], pool=e["info"]["pool"], side="buy", amount_in=int(size * config.LAMPORTS_PER_SOL),
@@ -109,13 +112,18 @@ class LiveMirror:
                      "ON CONFLICT (beat_id, book) DO NOTHING",
                      (beat_id, BOOK, m1, sol_free, gross_v - exit_cost, exit_cost, wealth, peak, (1.0 - wealth / peak) if peak > 0 else 0.0, exposure, len(opens)))
         if config.VAULT_ENABLED:                     # deposits, withdrawals and payouts are not performance
-            vault_nav.mark(conn, m1, snap.lamports, int(round(gross_v * config.LAMPORTS_PER_SOL)),
+            from ..vault import payout as vault_payout      # trading wallet + treasury are one book: a top-up or sweep is no loss
+            vault_nav.mark(conn, m1, snap.lamports + vault_payout.cached_balance(), int(round(gross_v * config.LAMPORTS_PER_SOL)),
                            int(round(exit_cost * config.LAMPORTS_PER_SOL)))
             ix = vault_nav.status(conn, since=rebase)
-            killed = rails.check_drawdown(conn, ix["value"], ix["peak"])
+            killed = rails.check_drawdown(conn, ix["value"], ix["peak"], unit="index")
         else:
             killed = rails.check_drawdown(conn, wealth, peak)
-        n_liq = self.liquidate(conn, ctx, run_id, beat_id) if killed and config.KILL_SWITCH_LIQUIDATE else 0
+        panic = False
+        if config.VAULT_ENABLED:                     # Telegram /panic: sell everything whatever KILL_SWITCH_LIQUIDATE says
+            from ..vault import state as vault_state
+            panic = bool(vault_state.get("panic"))
+        n_liq = self.liquidate(conn, ctx, run_id, beat_id) if killed and (config.KILL_SWITCH_LIQUIDATE or panic) else 0
         gap = self.gap(conn)
         if ctx.m1_epoch - self.last_sweep >= SWEEP_S:
             self.last_sweep = ctx.m1_epoch; self.sweep(conn, snap, inflight, m1)

fly_trader/agent/fly_session.py

@@ -35,7 +35,7 @@ from pathlib import Path
 import numpy as np
 import torch
 
-from .. import config
+from .. import config, markets
 from ..brain import activity, device as brain_device, plastic
 from ..brain.connectome import current_connectome_path
 from ..db.apilog import record_event
@@ -43,12 +43,12 @@ from ..db.connection import transaction
 from ..execution import ledger
 from ..execution.broker_paper import PaperBroker
 from ..ops.reset import activity_dir, fly_state_dir
-from ..train import fly_calibrate, fly_governance as gov, fly_selector
+from ..train import fly_calibrate, fly_governance as gov, fly_selector, selector, strategies
 from ..train.decisions import X_COLS
 from . import handover, paper_trading
 
 log = logging.getLogger(__name__)
-BOOK, KIND = "paper_fly", "fly"
+BOOK, KIND = "paper_fly", "fly"            # the Solana book's names (another chain's book takes its own from fly_trader/markets)
 BAR_KEEP = 270               # minutes of bars kept per watched mint (the longest strategy hold, 240, + next-open window + margin)
 NEXT_OPEN_S = 120.0          # entry at the next traded minute's open when it comes within two minutes (decisions.build)
 JUMP = 50.0
@@ -90,37 +90,57 @@ def resolve_label(bars: list, t: float, horizon_s: float) -> float | None:
     return float(exit_px / entry * (1 - rows[0][3]) * (1 - rows[j][3]) - 1)
 
 
-def try_start(live: bool = False) -> tuple["FlyBook | None", str]:
-    """A FlyBook when the fly may trade, else (None, why)."""
+def chain_passed(v: dict, chain: str) -> tuple[bool, str]:
+    """Whether the replay lets this chain's book trade: its own per-chain verdict (a combined replay), else the one verdict
+    for Solana (a Solana-only replay says nothing about another chain)."""
+    if "chains" in v:
+        c = v["chains"].get(chain)
+        return (bool(c and c.get("passed")), (c or {}).get("reason") or f"the replay has no {chain} verdict")
+    return (bool(v.get("passed")) and chain == "sol", v.get("reason") if chain == "sol" else f"the replay judged no {chain} trades")
+
+
+def try_start(live: bool = False, chain: str = "sol", brain: "FlyBook | None" = None) -> tuple["FlyBook | None", str]:
+    """A FlyBook for ``chain`` when the fly may trade there, else (None, why). ``brain``: the Solana book whose fly and
+    plastic memory another chain's book shares (one model learns from both chains)."""
     from ..train import fly_replay
     v = fly_replay.verdict()
     if not v:
         return None, "the fly's replay has not run on the current definitions (fly-trader fly-replay)"
-    if not v.get("passed"):
-        return None, f"the fly's replay did not pass: {v.get('reason')}"
+    ok, why = chain_passed(v, chain)
+    if not ok:
+        return None, f"the fly's replay did not pass on {markets.for_chain(chain).name}: {why}"
     with transaction() as conn:
         boot = fly_selector.latest_deployable(conn)
     if boot is None:
         return None, "no deployable fly bootstrap (the training pipeline bootstraps one)"
     try:
-        return FlyBook(boot, v, live=live), "ok"
+        return FlyBook(boot, v, live=live, chain=chain, brain=brain), "ok"
     except Exception as e:
         log.exception("fly book failed to start")
         return None, f"fly book failed to start: {type(e).__name__}: {e}"
 
 
-class FlyBook:
-    name = "fly"
+def no_teacher(n: int) -> dict:
+    """The decision when the teacher gate is on (FLY_TEACHER_GATE) but the fly's teacher could not be loaded: no row is
+    allowed, each recorded with why. A fresh install once lost the teacher's snapshot id (ops/release.remap_teacher)."""
+    return {"strategy": np.full(n, None, dtype=object), "score": np.full(n, -1.0), "hold_s": np.zeros(n), "threshold": np.full(n, np.inf),
+            "tables": [[] for _ in range(n)], "allow": np.zeros(n, bool),
+            "reason": np.full(n, "fail closed: the fly's teacher (the selector that taught it) is not loaded", dtype=object)}
+
 
-    def __init__(self, boot: dict, verdict: dict, live: bool = False):
+class FlyBook:
+    def __init__(self, boot: dict, verdict: dict, live: bool = False, chain: str = "sol", brain: "FlyBook | None" = None):
         self.live = live; self.done = False; self.mirror = None
         self.verdict = verdict
-        self.state_path = fly_state_dir() / "state.pt"
+        self.chain = chain; self.market = markets.for_chain(chain); self.brain = brain
+        self.name = "fly" if chain == "sol" else f"fly_{chain}"
+        self.BOOK = self.market.fly_book; self.KIND = self.name; self.status_key = self.market.fly_status_key
+        self.state_path = fly_state_dir() / ("state.pt" if chain == "sol" else f"state_{chain}.pt")
         self._load_bootstrap(boot)
-        self.run_id = str(uuid.uuid4()); self.beat_no = 0; self.broker = PaperBroker(BOOK)
+        self.run_id = str(uuid.uuid4()); self.beat_no = 0; self.broker = PaperBroker(self.BOOK)
         with transaction() as conn:
             conn.execute("INSERT INTO runs (run_id, kind, config, brain_snapshot_id, status) VALUES (%s,%s,%s,%s,'running')",
-                         (self.run_id, KIND, json.dumps({"channels": self.cfg, "book": BOOK}, default=str), self.boot_id))
+                         (self.run_id, self.KIND, json.dumps({"channels": self.cfg, "book": self.BOOK, "chain": chain}, default=str), self.boot_id))
             self._restore_tags(conn)
         record_event("info", "fly", "fly session started", {"run_id": self.run_id, "bootstrap": self.boot_id, "channels": self.cfg, "lines": self.lines["plastic"],
                                                             "pending": len(self.pending), "learning_frozen": self.learning_frozen})
@@ -128,54 +148,126 @@ class FlyBook:
                  self.lines["plastic"], len(self.pending))
 
     # ---- model and state ----
-    def _load_bootstrap(self, boot: dict) -> None:
-        self.boot_id = int(boot["id"])
-        self.fly = fly_selector.load(boot["path"])
-        try:
-            self.connectome_name = current_connectome_path().name       # stamped on the activity files the console draws
-        except Exception:
-            self.connectome_name = ""
-        self.capture_ok = True
-        self.idx = np.asarray([X_COLS.index(c) for c in self.fly.cols], dtype=int)
-        self.names = list(self.fly.strategies); self.holds = {k: float(self.fly.rules[k]["hold_min"]) * 60.0 for k in self.names}
-        self.H = max(self.holds.values())
-        per = self.verdict.get("per_strategy") or {self.names[0]: {"alpha": self.verdict.get("alpha", 0.0), "half_life_days": self.verdict.get("half_life_days")}}
-        self.cfg = {k: (float((per.get(k) or {}).get("alpha") or 0.0), (per.get(k) or {}).get("half_life_days")) for k in self.names}
-        self.alpha = self.cfg[self.names[0]][0]; self.half_life = float(self.cfg[self.names[0]][1]) if self.cfg[self.names[0]][1] is not None else math.inf
-        net = self.fly.net
-        self.bank = plastic.PlasticBank(net, [(self.alpha, self.half_life)], fly_selector.SCALE, learn=net.learn.cpu().numpy(), read=net.read.cpu().numpy())
-        for j, k in enumerate(self.names):                      # each strategy's channel learns and forgets at its own replay-chosen rate
-            a, h = self.cfg[k]; cols = self.bank.learn[j]
-            self.bank.alpha[0, cols] = a; self.bank.half_life_s[0, cols] = float(h) * 86400.0 if h is not None else float("inf")
+    def _load_bootstrap(self, boot: dict | None) -> None:
+        b = self.brain
+        if b is not None:        # another chain's book: the Solana book's fly and plastic memory, this chain's own lines and tags
+            self.boot_id = b.boot_id; self.fly = b.fly; self.connectome_name = b.connectome_name; self.capture_ok = False
+            self.teacher_models = b.teacher_models; self.idx = b.idx; self.names = b.names; self.holds = b.holds; self.H = b.H
+            self.teacher_live, self.teacher_groups = b.teacher_live, b.teacher_groups
+            self.cfg = b.cfg; self.alpha = b.alpha; self.half_life = b.half_life; self.bank = b.bank
+            net = self.fly.net
+        else:
+            self.boot_id = int(boot["id"])
+            self.fly = fly_selector.load(boot["path"])
+            try:
+                self.connectome_name = current_connectome_path().name       # stamped on the activity files the console draws
+            except Exception:
+                self.connectome_name = ""
+            self.capture_ok = True
+            self.teacher_models = self._teacher_models(boot)
+            self.idx = np.asarray([X_COLS.index(c) for c in self.fly.cols], dtype=int)
+            self.names = list(self.fly.strategies); self.holds = {k: float(self.fly.rules[k]["hold_min"]) * 60.0 for k in self.names}
+            self.H = max(self.holds.values())
+            per = self.verdict.get("per_strategy") or {self.names[0]: {"alpha": self.verdict.get("alpha", 0.0), "half_life_days": self.verdict.get("half_life_days")}}
+            self.cfg = {k: (float((per.get(k) or {}).get("alpha") or 0.0), (per.get(k) or {}).get("half_life_days")) for k in self.names}
+            self.alpha = self.cfg[self.names[0]][0]; self.half_life = float(self.cfg[self.names[0]][1]) if self.cfg[self.names[0]][1] is not None else math.inf
+            net = self.fly.net
+            self.bank = plastic.PlasticBank(net, [(self.alpha, self.half_life)], fly_selector.SCALE, learn=net.learn.cpu().numpy(), read=net.read.cpu().numpy())
+            for j, k in enumerate(self.names):                      # each strategy's channel learns and forgets at its own replay-chosen rate
+                a, h = self.cfg[k]; cols = self.bank.learn[j]
+                self.bank.alpha[0, cols] = a; self.bank.half_life_s[0, cols] = float(h) * 86400.0 if h is not None else float("inf")
         self.pending = plastic.PendingTags(net.n_kc, net.k_active)
         self.bars: dict[str, deque] = {}; self.watch: dict[str, int] = {}
-        self.lines = {"plastic": dict(self.fly.lines), "frozen": dict(self.fly.lines)}
-        self.sizing = {"plastic": {k: list(v) for k, v in self.fly.sizings.items()}, "frozen": {k: list(v) for k, v in self.fly.sizings.items()}}
+        own = {k: self.fly.line_for(k, self.chain) for k in self.names}; own_s = {k: list(self.fly.sizing_for(k, self.chain)) for k in self.names}
+        if config.FLY_SCORE == "teacher" and self.teacher_live:   # it scores on its teacher's scale: it starts on its teacher's lines and bands
+            ts_ = self.teacher_live.get("strategies") or {}
+            own = {k: float(ts_[k]["line"]) if k in ts_ else v for k, v in own.items()}
+            own_s = {k: list(ts_[k].get("sizing") or v) if k in ts_ else v for k, v in own_s.items()}
+        self.lines = {"plastic": dict(own), "frozen": dict(own)}
+        self.sizing = {"plastic": {k: list(v) for k, v in own_s.items()}, "frozen": {k: list(v) for k, v in own_s.items()}}
         self.applied_through = -math.inf; self.learning_frozen = False; self.checks_paused_until = {k: 0.0 for k in self.names}
         self.race_started_at: float | None = None; self.last_day: int | None = None; self.last_hour: int | None = None
         self.rollbacks: dict = {k: [] for k in self.names}; self.nu_set = False; self.hour_stats = self._empty_stats(); self.last_checks: dict = {}
         s = self._read_state()
+        if b is not None:
+            self.nu_set = True                                   # the shared memory is the Solana book's to load and save
+        if s and s.get("bootstrap_id") == self.boot_id and s.get("cfg") == self.cfg and s.get("score", "own") != config.FLY_SCORE:
+            self._archive_state(s)                               # learned under another scoring: it starts from its bootstrap
+            s = None
         if s and s.get("bootstrap_id") == self.boot_id and s.get("cfg") == self.cfg:
-            self.bank.load_state(s["bank"]); self.nu_set = True
+            if b is None:
+                self.bank.load_state(s["bank"])
+            self.nu_set = True
             self.lines, self.sizing = s["lines"], s["sizing"]
             self.applied_through, self.learning_frozen, self.checks_paused_until = s["applied_through"], s["learning_frozen"], s["checks_paused_until"]
             self.race_started_at, self.last_day, self.last_hour, self.rollbacks = s["race_started_at"], s["last_day"], s["last_hour"], s["rollbacks"]
         elif s:
             self.race_started_at = s.get("race_started_at")        # a new bootstrap keeps racing the same book
             with transaction() as conn:
-                conn.execute("UPDATE fly_scored SET state = 'dropped', x = NULL WHERE state = 'pending' AND bootstrap_id IS DISTINCT FROM %s", (self.boot_id,))
+                conn.execute("UPDATE fly_scored SET state = 'dropped', x = NULL WHERE state = 'pending' AND chain = %s AND bootstrap_id IS DISTINCT FROM %s",
+                             (self.chain, self.boot_id))
+
+    teacher_live: dict | None = None
+    teacher_groups: set = set()
+
+    def _teacher_models(self, boot: dict) -> dict | None:
+        """The stack that taught this fly (its snapshot's ``teacher_snapshot``: the holdout-blind copy when that is what
+        taught it), whose final decision on each scored row is stored as ``teacher_allow`` -- the match calibration
+        rule's budget. None (with a warning) when the fly was taught by a refit stack or the snapshot is gone."""
+        meta = boot.get("meta") or {}
+        sid = meta.get("teacher_snapshot")
+        if sid is None:
+            if fly_calibrate.RULE == "match":
+                log.warning("fly #%s names no teacher snapshot: the match rule keeps its bootstrap line", self.boot_id)
+            return None
+        try:
+            m = selector.load_snapshot(int(sid))
+        except Exception:
+            log.exception("fly #%s: teacher snapshot #%s could not be loaded", self.boot_id, sid)
+            return None
+        blind = getattr(m, "blind", None) or {}
+        models = blind["models"] if "blind to the calibration week" in str(meta.get("teacher") or "") and blind.get("models") else getattr(m, "stack", None)
+        live = getattr(m, "stack", None)                         # the gate: the teacher's full stack, as its selector book trades it
+        if live and live.get("strategies") and all(c in X_COLS for v in live["strategies"].values() for c in v["cols"]):
+            self.teacher_live = live
+            self.teacher_groups = set((getattr(m, "metrics", None) or {}).get("groups") or [])
+        if not models or not models.get("strategies") or any(c not in X_COLS for v in models["strategies"].values() for c in v["cols"]):
+            log.warning("fly #%s: teacher #%s has no usable strategy stack", self.boot_id, sid)
+            return None
+        return models
+
+    def _teacher_allow(self, X: np.ndarray, t: float) -> dict[str, np.ndarray]:
+        """Per strategy: would the teacher trade each row (trigger, line and every filter)? Empty when unknown."""
+        if self.teacher_models is None:
+            return {}
+        try:
+            per = strategies.decide_all(self.teacher_models, X, X_COLS, t)
+            return {k: np.asarray(v["allow"], bool) for k, v in per.items()}
+        except Exception:
+            log.exception("teacher decisions failed for this minute (the fly still trades)")
+            return {}
 
     def _read_state(self) -> dict | None:
         if not self.state_path.exists():
             return None
         try:
-            return torch.load(self.state_path, map_location="cpu", weights_only=False)
+            return torch.load(self.state_path, map_location="cpu", weights_only=True)
         except Exception:
             log.exception("fly state unreadable; starting from the bootstrap")
             return None
 
+    def _archive_state(self, s: dict) -> None:
+        """Keep a state learned under another scoring mode beside the new one (never loaded again)."""
+        try:
+            dst = self.state_path.with_name(f"{self.state_path.stem}_{s.get('score', 'own')}_{time.strftime('%Y%m%dT%H%M%S')}.pt")
+            os.replace(self.state_path, dst)
+            record_event("info", "fly", f"fly state learned with FLY_SCORE={s.get('score', 'own')} set aside: the fly starts from its bootstrap",
+                         {"path": str(dst), "drift": None})
+        except OSError:
+            log.exception("could not set the old fly state aside")
+
     def _state(self) -> dict:
-        return {"bootstrap_id": self.boot_id, "cfg": self.cfg, "bank": self.bank.state(), "lines": self.lines, "sizing": self.sizing,
+        return {"bootstrap_id": self.boot_id, "cfg": self.cfg, "score": config.FLY_SCORE, "bank": self.bank.state() if self.brain is None else None, "lines": self.lines, "sizing": self.sizing,
                 "applied_through": self.applied_through, "learning_frozen": self.learning_frozen, "checks_paused_until": self.checks_paused_until,
                 "race_started_at": self.race_started_at, "last_day": self.last_day, "last_hour": self.last_hour, "rollbacks": self.rollbacks,
                 "saved_at": time.time()}
@@ -186,7 +278,8 @@ class FlyBook:
         torch.save(self._state(), tmp); os.replace(tmp, self.state_path)
 
     def _restore_tags(self, conn) -> None:
-        rows = conn.execute("SELECT ts, mint, strategy, x, score, line FROM fly_scored WHERE state = 'pending' AND bootstrap_id = %s ORDER BY ts", (self.boot_id,)).fetchall()
+        rows = conn.execute("SELECT ts, mint, strategy, x, score, line FROM fly_scored WHERE state = 'pending' AND bootstrap_id = %s AND chain = %s ORDER BY ts",
+                            (self.boot_id, self.chain)).fetchall()
         rows = [r for r in rows if r["strategy"] in self.holds]
         applied = [(r["ts"], r["mint"], r["strategy"]) for r in rows if r["ts"].timestamp() + self.holds[r["strategy"]] + LABEL_LAG_S <= self.applied_through]
         if applied:
@@ -198,14 +291,34 @@ class FlyBook:
             groups.setdefault((r["ts"].timestamp(), r["strategy"]), []).append(r)
         for (t, name), rs in sorted(groups.items()):
             j = self.names.index(name)
-            Y, u0, k = self.fly.parts_all(np.asarray([r["x"] for r in rs], dtype=np.float32))
-            w = plastic.row_weights(torch.tensor([[float(r["score"]) for r in rs]]), torch.tensor([float(rs[0]["line"])]))
-            self.pending.push([(t, r["mint"], name) for r in rs], np.full(len(rs), t), t + self.holds[name] + LABEL_LAG_S, Y[:, j], u0, k, w, s=j)
+            Xr = np.asarray([r["x"] for r in rs], dtype=np.float32)
+            Y, u0, k = self.fly.parts_all(Xr[:, self.idx])
+            tv = self._teacher_scores(Xr, t); loc = np.arange(len(rs))
+            if tv is not None:
+                loc = loc[np.isfinite(tv[:, j])]
+                if not len(loc):
+                    continue
+                rs = [rs[i] for i in loc]; Xr = Xr[loc]; li = torch.as_tensor(loc, device=Y.device); Y, u0, k = Y[li], u0[li], k[li]
+            y = self._head(Y[:, j], tv, loc, j, u0)
+            if config.FLY_TEACHER_GATE and self.teacher_live is not None:      # gated: it learns from its teacher's trades, as live
+                d = strategies.decide(self.teacher_live, Xr, X_COLS, t)
+                w = torch.tensor([[float(d["strategy"][i] == name and bool(d["allow"][i])) for i in range(len(rs))]])
+            elif config.FLY_TEACHER_GATE:
+                w = torch.zeros((1, len(rs)))
+            else:
+                w = plastic.row_weights(torch.tensor([[float(r["score"]) for r in rs]]), torch.tensor([float(rs[0]["line"])]))
+            self.pending.push([(t, r["mint"], name) for r in rs], np.full(len(rs), t), t + self.holds[name] + LABEL_LAG_S, y, u0, k, w, s=j)
             for r in rs:
                 self.watch[r["mint"]] = self.watch.get(r["mint"], 0) + 1
 
     def maybe_reload(self) -> bool:
-        """A newer deployable bootstrap (a re-bootstrap) replaces this one at once: D = 0, pending tags dropped, the book carries on."""
+        """A newer deployable bootstrap (a re-bootstrap) replaces this one at once: D = 0, pending tags dropped, the book carries on.
+        Another chain's book follows its brain (the Solana book reloads first)."""
+        if self.brain is not None:
+            if self.brain.boot_id == self.boot_id:
+                return False
+            self._write_state(); self._load_bootstrap(None)
+            return True
         from ..train import fly_replay
         with transaction() as conn:
             boot = fly_selector.latest_deployable(conn)
@@ -231,7 +344,7 @@ class FlyBook:
                     q.append(b)
 
     def open_mints(self, conn) -> set[str]:
-        return {p["mint"] for p in ledger.open_positions(conn, BOOK)}
+        return {p["mint"] for p in ledger.open_positions(conn, self.BOOK)}
 
     def on_minute(self, ctx) -> dict:
         conn, t_now = ctx.conn, ctx.t_start
@@ -254,11 +367,12 @@ class FlyBook:
                 self.race_started_at = ctx.m1_epoch
             self.beat_no += 1
             d = scored["decision"]
-            st = paper_trading.trade_minute(ctx, book=BOOK, run_id=self.run_id, beat_no=self.beat_no, broker=self.broker, kind=KIND, mints=ctx.mints, infos=ctx.infos,
+            st = paper_trading.trade_minute(ctx, book=self.BOOK, run_id=self.run_id, beat_no=self.beat_no, broker=self.broker, kind=self.KIND, mints=ctx.mints, infos=ctx.infos,
                                             scores=d["score"], threshold=d["threshold"], table=None, horizon_s=self.holds[self.names[0]], holds=d["hold_s"],
-                                            strategies=d["strategy"], tables=d["tables"])
+                                            strategies=d["strategy"], tables=d["tables"], flat=config.FLY_SIZING == "flat",
+                                            allow=d.get("allow"), reasons=d.get("reason"))
             out.update({k: v for k, v in st.items() if k != "entries"}); out["stage"] = "trading"
-            if self.live and handover.state(conn) is not None:
+            if self.live and handover.state(conn, self.chain) is not None:
                 out["live"] = self._live(ctx, st)
         else:
             out["stage"] = "learning (not trading this minute)" if ctx.trade else "catching up"
@@ -273,12 +387,15 @@ class FlyBook:
                 cur.executemany("UPDATE fly_scored SET label = %s, state = %s, resolved_at = now(), x = NULL WHERE ts = %s AND mint = %s AND strategy = %s", learned.pop("keys"))
         learned.pop("keys", None)
         out["checks"] = self.last_checks; out["updated_at"] = datetime.now(timezone.utc).isoformat()
-        conn.execute("INSERT INTO ui_settings (key, value) VALUES ('fly_status', %s) ON CONFLICT (key) DO UPDATE SET value = EXCLUDED.value, updated_at = now()",
-                     (json.dumps(out, default=str),))
+        conn.execute("INSERT INTO ui_settings (key, value) VALUES (%s, %s) ON CONFLICT (key) DO UPDATE SET value = EXCLUDED.value, updated_at = now()",
+                     (self.status_key, json.dumps({**out, "chain": self.chain}, default=str)))
         return out
 
     def _live(self, ctx, st: dict) -> dict:
         """The fly holds the seat: mirror this minute on the bot wallet (agent/fly_live.py) while signing is allowed."""
+        if self.chain != "sol":
+            from ..rh import live as rh_live                     # Robinhood Chain: the ETH wallet (rh/live.py)
+            return rh_live.minute(self, ctx, st)
         from ..chain.cluster_guard import signing_allowed
         if not signing_allowed():
             return {"stage": "live gated: signing is not allowed (LIVE_ENABLED=1 and the live prerequisites)"}
@@ -343,21 +460,37 @@ class FlyBook:
         self._capture(H, trig, ctx.t_start); del H
         if not self.nu_set:
             self.bank.estimate_nu(Y[:, 0], u0, k); self.nu_set = True
-        t = ctx.t_start; ts = datetime.fromtimestamp(t, timezone.utc); rows = []
-        V = np.full((n, len(self.names)), -np.inf)
+        t = ctx.t_start; ts = datetime.fromtimestamp(t, timezone.utc); rows = []; ta = self._teacher_allow(ctx.X, t)
+        V = np.full((n, len(self.names)), -np.inf); F = np.full((n, len(self.names)), np.nan)
+        gated = config.FLY_TEACHER_GATE
+        if config.FLY_SCORE == "teacher" and self.teacher_live is None:      # it starts from its teacher's score: none, no score
+            return {"decision": no_teacher(n), "picks": 0}
+        td = self._teacher_decision(ctx) if gated and self.teacher_live is not None else None
+        tv = self._teacher_scores(ctx.X, t)
         for j, name in enumerate(self.names):
             loc = np.flatnonzero(trig[:, j])
+            if tv is not None:
+                loc = loc[np.isfinite(tv[loc, j])]                   # a candidate its teacher scores
             if not len(loc):
                 continue
             li = torch.as_tensor(loc, device=Y.device)
+            y = self._head(Y[li, j], tv, loc, j, u0[li])
             with torch.no_grad():
-                sc, _ = self.bank.predict(Y[li, j], u0[li], k[li], s=np.full(len(loc), j)); sc = sc[0]
-                fr = self.bank.frozen(Y[li, j], u0[li], s=np.full(len(loc), j))
-            v, f = sc.float().cpu().numpy(), fr.float().cpu().numpy(); V[loc, j] = v
+                sc, _ = self.bank.predict(y, u0[li], k[li], s=np.full(len(loc), j)); sc = sc[0]
+                fr = self.bank.frozen(y, u0[li], s=np.full(len(loc), j))
+            v, f = sc.float().cpu().numpy(), fr.float().cpu().numpy(); V[loc, j] = v; F[loc, j] = f
             line, fline = self.lines["plastic"][name], self.lines["frozen"][name]
-            rows += [(ts, ctx.mints[i], name, int(self.holds[name] // 60), ctx.X[i].tolist(), float(v[q]), float(f[q]), line, fline, self.boot_id) for q, i in enumerate(loc)]
-            w = plastic.row_weights(sc[None], torch.tensor([line], dtype=sc.dtype, device=sc.device))
-            self.pending.push([(t, ctx.mints[i], name) for i in loc], np.full(len(loc), t), t + self.holds[name] + LABEL_LAG_S, Y[li, j], u0[li], k[li], w, s=j)
+            al = ta.get(name)
+            rows += [(ts, ctx.mints[i], name, int(self.holds[name] // 60), ctx.X[i].tolist(), float(v[q]), float(f[q]), line, fline, self.boot_id,
+                      None if al is None else bool(al[i])) for q, i in enumerate(loc)]
+            if td is not None:   # gated: its decisions are the teacher's trades of this strategy (before its own vetoes), so it learns from those
+                mine = np.array([td["strategy"][i] == name and bool(td["allow"][i]) for i in loc], dtype=np.float32)
+                w = torch.as_tensor(mine[None], dtype=sc.dtype, device=sc.device)
+            elif gated:          # the gate is on but its teacher is not loaded: nothing to learn from until it is
+                w = torch.zeros((1, len(loc)), dtype=sc.dtype, device=sc.device)
+            else:
+                w = plastic.row_weights(sc[None], torch.tensor([line], dtype=sc.dtype, device=sc.device))
+            self.pending.push([(t, ctx.mints[i], name) for i in loc], np.full(len(loc), t), t + self.holds[name] + LABEL_LAG_S, y, u0[li], k[li], w, s=j)
             for i in loc:
                 m = ctx.mints[i]; self.watch[m] = self.watch.get(m, 0) + 1
                 q_ = self.bars.setdefault(m, deque(maxlen=BAR_KEEP)); b = ctx.bars.get(m)
@@ -365,12 +498,64 @@ class FlyBook:
                     q_.append(b)
         if rows:
             with conn.cursor() as cur:
-                cur.executemany("INSERT INTO fly_scored (ts, mint, strategy, hold_min, x, score, frozen_score, line, frozen_line, bootstrap_id) "
-                                "VALUES (%s,%s,%s,%s,%s,%s,%s,%s,%s,%s) ON CONFLICT (ts, mint, strategy) DO NOTHING", rows)
-        self.fly.lines = dict(self.lines["plastic"]); self.fly.sizings = {k: list(v) for k, v in self.sizing["plastic"].items()}
+                cur.executemany("INSERT INTO fly_scored (ts, mint, strategy, hold_min, x, score, frozen_score, line, frozen_line, bootstrap_id, teacher_allow, chain) "
+                                "VALUES (%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s) ON CONFLICT (ts, mint, strategy) DO NOTHING", [r + (self.chain,) for r in rows])
+        if self.chain == "sol":
+            self.fly.lines = dict(self.lines["plastic"]); self.fly.sizings = {k: list(v) for k, v in self.sizing["plastic"].items()}
+        else:                                                    # the shared model decides this chain's rows on this chain's lines
+            self.fly.chain_lines[self.chain] = dict(self.lines["plastic"]); self.fly.chain_sizings[self.chain] = {k: list(v) for k, v in self.sizing["plastic"].items()}
+        if td is not None:
+            d = self._gated(ctx, V, F, td)
+            return {"decision": d, "picks": int(d["allow"].sum())}
+        if gated:                # never the ungated fly: it bought what the selector rejected and lost (2026-10-08)
+            return {"decision": no_teacher(n), "picks": 0}
         d = fly_selector.fly_decide(self.fly, ctx.X, X_COLS, np.where(np.isfinite(V), V, -np.inf))
         return {"decision": d, "picks": int(sum(1 for x in d["strategy"] if x is not None))}
 
+    def _teacher_scores(self, X: np.ndarray, t) -> np.ndarray | None:
+        """[B, S] the teacher's own score of each row per strategy (NaN off its trigger) when the fly scores as its teacher
+        plus its learned correction (config.FLY_SCORE = teacher), else None."""
+        if config.FLY_SCORE != "teacher" or self.teacher_live is None:
+            return None
+        return fly_selector.teacher_scores(self.teacher_live, X, t, self.names, X_COLS)
+
+    def _head(self, y_own: torch.Tensor, tv: np.ndarray | None, loc: np.ndarray, j: int, u0: torch.Tensor) -> torch.Tensor:
+        """The head output the bank scores with: the fly's own decoder output, or (FLY_SCORE = teacher) the one under which
+        its frozen score is the teacher's score exactly (PlasticBank.head_for), so only its learning moves it."""
+        if tv is None:
+            return y_own
+        return self.bank.head_for(torch.as_tensor(tv[loc, j], dtype=torch.float32, device=self.bank.dev), u0, s=np.full(len(loc), j))
+
+    def _teacher_decision(self, ctx) -> dict:
+        """The deployed selector's decision on this minute's rows, with its live fail-closed rules."""
+        from .selector_session import fail_closed
+        return fail_closed(self.teacher_groups, ctx.infos, strategies.decide(self.teacher_live, ctx.X, X_COLS, ctx.t_start))
+
+    def _gated(self, ctx, V: np.ndarray, F: np.ndarray, td: dict | None = None) -> dict:
+        """The fly's decision under its teacher: each row's strategy, trigger, line, win filter, gates, dump veto and
+        fail-closed rules are the deployed selector's (agent/selector_session.fail_closed), so a fresh bootstrap trades the
+        selector's set; the fly drops a teacher trade only where its learning has moved its score more than
+        ``FLY_LEARNED_VETO`` below its bootstrap score. A row the teacher blocks is recorded with the teacher's reason."""
+        n = len(ctx.mints)
+        td = td if td is not None else self._teacher_decision(ctx)
+        strat = np.full(n, None, dtype=object); score = np.full(n, -1.0); hold = np.zeros(n); thr = np.full(n, np.inf)
+        tables = [[] for _ in range(n)]; allow = np.zeros(n, bool); reason = np.full(n, "", dtype=object)
+        for i in range(n):
+            s_ = td["strategy"][i]
+            if s_ is None or s_ not in self.names:
+                continue
+            j = self.names.index(s_); v, f = V[i, j], F[i, j]
+            # the selector's own score, line and sizing table for the row: a gated fly buy is sized exactly as the selector
+            # sizes it (agent/sizing.size_position; FLY_SIZING=kelly: the same Kelly band, fraction and caps; flat: flat)
+            strat[i] = s_; score[i] = float(td["score"][i]); thr[i] = float(td["threshold"][i]); hold[i] = self.holds[s_]; tables[i] = td["tables"][i]
+            if not td["allow"][i]:
+                reason[i] = f"selector: {td['reason'][i]}"
+            elif np.isfinite(v) and np.isfinite(f) and v < f - config.FLY_LEARNED_VETO:
+                reason[i] = f"learned veto: score {v:.3f} < bootstrap {f:.3f} - {config.FLY_LEARNED_VETO:g}"
+            else:
+                allow[i] = True; reason[i] = "trade"
+        return {"strategy": strat, "score": score, "hold_s": hold, "threshold": thr, "tables": tables, "allow": allow, "reason": reason}
+
     def _capture(self, H: torch.Tensor, trig: np.ndarray, t: float) -> None:
         """The console's brain view: this minute's mean activity over the rows some strategy's trigger fired on (every
         row when none did), one file per minute (brain/activity.py). Never allowed to interrupt scoring."""
@@ -387,25 +572,39 @@ class FlyBook:
     # ---- daily and hourly ----
     def _resolved(self, conn, since_resolved: float, cols: str, name: str) -> list[dict]:
         """A strategy's resolved rows whose labels became known after ``since_resolved`` (epoch s)."""
-        return conn.execute(f"SELECT {cols} FROM fly_scored WHERE state = 'resolved' AND label IS NOT NULL AND bootstrap_id = %s AND strategy = %s AND ts >= %s ORDER BY ts",
-                            (self.boot_id, name, datetime.fromtimestamp(since_resolved - self.holds[name] - LABEL_LAG_S, timezone.utc))).fetchall()
+        return conn.execute(f"SELECT {cols} FROM fly_scored WHERE state = 'resolved' AND label IS NOT NULL AND bootstrap_id = %s AND strategy = %s AND chain = %s "
+                            "AND ts >= %s ORDER BY ts", (self.boot_id, name, self.chain,
+                                                         datetime.fromtimestamp(since_resolved - self.holds[name] - LABEL_LAG_S, timezone.utc))).fetchall()
 
     def _calibrate(self, conn, now: float) -> None:
         day = datetime.fromtimestamp(now, timezone.utc).date()
+        rule = fly_calibrate.RULE
         for name in self.names:
-            rows = self._resolved(conn, now - fly_calibrate.WINDOW_DAYS * 86400.0, "ts, mint, score, frozen_score, label", name)
+            rows = self._resolved(conn, now - fly_calibrate.WINDOW_DAYS * 86400.0, "ts, mint, score, frozen_score, label, teacher_allow", name)
+            target = None
+            if rule == "match":
+                # the teacher's trades over the same rows are the budget; rows scored before it was recorded cannot count
+                rows = [r for r in rows if r["teacher_allow"] is not None]
+                if not rows:
+                    log.info("fly %s: no scored rows with the teacher's decision yet; the line stays %.4f", name, self.lines["plastic"][name])
+                    continue
             if not rows:
                 continue
             ts = np.array([r["ts"].timestamp() for r in rows]); mint = np.array([r["mint"] for r in rows]); lab = np.array([r["label"] for r in rows], dtype=np.float64)
+            if rule == "match":
+                al = np.array([bool(r["teacher_allow"]) for r in rows]) & np.isfinite(lab)
+                target = len(fly_calibrate.taken_idx(ts, mint, self.holds[name], np.flatnonzero(al)))
             for arm, col in (("plastic", "score"), ("frozen", "frozen_score")):
                 cal = fly_calibrate.calibrate(ts, mint, self.holds[name], np.array([r[col] for r in rows], dtype=np.float64), lab,
-                                              prev_line=self.lines[arm][name], prev_sizing=self.sizing[arm][name])
+                                              prev_line=self.lines[arm][name], prev_sizing=self.sizing[arm][name], rule=rule, target_trades=target)
                 if cal.changed:
-                    record_event("info", "fly", f"{name} {arm} line {self.lines[arm][name] * 100:+.2f}% → {cal.line * 100:+.2f}%", {"trades": cal.trades, "mean": cal.mean, "total": cal.total})
+                    record_event("info", "fly", f"{name} {arm} line {self.lines[arm][name] * 100:+.2f}% → {cal.line * 100:+.2f}%",
+                                 {"trades": cal.trades, "mean": cal.mean, "total": cal.total, "rule": rule, "teacher_trades": target})
                 self.lines[arm][name], self.sizing[arm][name] = cal.line, cal.sizing
                 conn.execute("INSERT INTO fly_calibrations (day, arm, line, sizing, trades, total, mean, window_days) VALUES (%s,%s,%s,%s,%s,%s,%s,%s) "
                              "ON CONFLICT (day, arm) DO UPDATE SET line = EXCLUDED.line, sizing = EXCLUDED.sizing, trades = EXCLUDED.trades, total = EXCLUDED.total, mean = EXCLUDED.mean",
-                             (day, f"{arm}:{name}", cal.line, json.dumps(cal.sizing), cal.trades, cal.total, cal.mean, fly_calibrate.WINDOW_DAYS))
+                             (day, f"{arm}:{name}" if self.chain == "sol" else f"{arm}:{self.chain}:{name}", cal.line, json.dumps(cal.sizing), cal.trades,
+                              cal.total, cal.mean, fly_calibrate.WINDOW_DAYS))
 
     def _drift(self, j: int) -> float:
         return float(self.bank.drift(j)[0]) if self.bank.learn.shape[0] > 1 else float(self.bank.drift()[0])
@@ -427,6 +626,10 @@ class FlyBook:
         return out
 
     def _hourly(self, conn, now: float) -> None:
+        if self.brain is not None:
+            # another chain's book: its own handover; the shared memory's checks, snapshots and rollbacks are the Solana book's
+            self._handover_check(conn, now)
+            return
         hour = datetime.fromtimestamp(math.floor(now / 3600) * 3600 - 3600, timezone.utc)
         checks = self._checks(conn, now); self.last_checks = checks
         h = self.hour_stats; first = checks.get(self.names[0]) or {}
@@ -447,7 +650,7 @@ class FlyBook:
         d = fly_state_dir(); d.mkdir(parents=True, exist_ok=True)
         path = d / f"snap_{datetime.fromtimestamp(now, timezone.utc).strftime('%Y%m%dT%H%M')}.pt"
         torch.save({"bank": self.bank.state(), "bootstrap_id": self.boot_id, "lines": self.lines, "sizing": self.sizing}, path)
-        note = {"bootstrap_id": self.boot_id, "data": fly_selector.FLY_VERSION, "good": good, "checks": checks,
+        note = {"bootstrap_id": self.boot_id, "data": fly_selector.FLY_VERSION, "score": config.FLY_SCORE, "good": good, "checks": checks,
                 "drift": max((c["drift"] for c in checks.values()), default=0.0), "ic24": {k: c.get("ic") for k, c in checks.items()}}
         return int(conn.execute("INSERT INTO brain_snapshots (run_id, path, kind, note) VALUES (%s,%s,'fly_plastic',%s) RETURNING id",
                                 (self.run_id, str(path), json.dumps(note, default=str))).fetchone()["id"])
@@ -476,11 +679,11 @@ class FlyBook:
                               (datetime.fromtimestamp(now - ROLLBACK_MIN_AGE_S, timezone.utc),)).fetchall():
             n = json.loads(r["note"] or "{}")
             ok = n.get("good") or not ((n.get("checks") or {}).get(name) or {}).get("triggers")
-            if ok and n.get("bootstrap_id") == self.boot_id and Path(r["path"]).exists():
+            if ok and n.get("bootstrap_id") == self.boot_id and n.get("score", "own") == config.FLY_SCORE and Path(r["path"]).exists():
                 target = r; break
         if target is not None:
             snap = plastic.PlasticBank(self.fly.net, [(0.0, math.inf)], fly_selector.SCALE, learn=self.bank.learn.cpu().numpy(), read=self.bank.read.cpu().numpy())
-            st = torch.load(target["path"], map_location="cpu", weights_only=False)["bank"]
+            st = torch.load(target["path"], map_location="cpu", weights_only=True)["bank"]
             snap.D = torch.zeros_like(snap.D); snap.D[:, snap.mask.bool()] = st["D"].to(snap.dev).float()
             self.bank.D[0][:, cols] = snap.D[0][:, cols]
         else:
@@ -519,15 +722,17 @@ class FlyBook:
         whole race), closed ``config.HANDOVER_MIN_TRADES`` paper trades and, when ``config.HANDOVER_BEAT_SELECTOR``,
         realized at least the paper selector's P&L over that window."""
         days = config.HANDOVER_DAYS
-        if handover.state(conn) is not None or self.race_started_at is None or now - self.race_started_at < days * 86400.0:
+        if handover.state(conn, self.chain) is not None or self.race_started_at is None or now - self.race_started_at < days * 86400.0:
             return
         since = datetime.fromtimestamp(self.race_started_at if days <= 0 else now - days * 86400.0, timezone.utc)
+        fb, sb = self.BOOK, self.market.selector_book                 # this chain's race: its fly book against its selector book
         pnl = {b: conn.execute("SELECT COALESCE(sum(realized_sol), 0) AS s, count(*) AS n FROM positions WHERE book = %s AND status = 'closed' AND closed_at >= %s",
-                               (b, since)).fetchone() for b in (BOOK, "paper_selector")}
-        fly_pnl, sel_pnl, n = float(pnl[BOOK]["s"]), float(pnl["paper_selector"]["s"]), int(pnl[BOOK]["n"])
+                               (b, since)).fetchone() for b in (fb, sb)}
+        fly_pnl, sel_pnl, n = float(pnl[fb]["s"]), float(pnl[sb]["s"]), int(pnl[fb]["n"])
         if n >= config.HANDOVER_MIN_TRADES and (fly_pnl >= sel_pnl or not config.HANDOVER_BEAT_SELECTOR):
             detail = {"at": datetime.fromtimestamp(now, timezone.utc).isoformat(), "fly_pnl_sol": fly_pnl, "selector_pnl_sol": sel_pnl, "fly_trades": n,
-                      "selector_trades": int(pnl["paper_selector"]["n"]), "days": days, "beat_selector": config.HANDOVER_BEAT_SELECTOR, "bootstrap": self.boot_id}
-            handover.record(conn, detail)
+                      "selector_trades": int(pnl[sb]["n"]), "days": days, "beat_selector": config.HANDOVER_BEAT_SELECTOR, "bootstrap": self.boot_id,
+                      "chain": self.chain, "unit": self.market.unit}
+            handover.record(conn, detail, self.chain)
             record_event("info", "handover", f"the fly takes the selector's seat: {fly_pnl:+.3f} SOL vs {sel_pnl:+.3f} SOL over {n} trades"
                          + (f" in {days} days" if days > 0 else ""), detail)

fly_trader/agent/handover.py

@@ -11,14 +11,22 @@ import json
 KEY = "handover"
 
 
-def state(conn) -> dict | None:
-    r = conn.execute("SELECT value FROM ui_settings WHERE key = %s", (KEY,)).fetchone()
+def _key(chain: str | None) -> str:
+    """Each chain's fly takes its own chain's seat (fly_trader/markets: 'handover', 'handover_rh')."""
+    if chain in (None, "sol"):
+        return KEY
+    from ..markets import for_chain
+    return for_chain(chain).handover_key
+
+
+def state(conn, chain: str | None = "sol") -> dict | None:
+    r = conn.execute("SELECT value FROM ui_settings WHERE key = %s", (_key(chain),)).fetchone()
     if not r or r["value"] is None:
         return None
     v = r["value"] if isinstance(r["value"], dict) else json.loads(r["value"])
     return v or None
 
 
-def record(conn, detail: dict) -> None:
+def record(conn, detail: dict, chain: str | None = "sol") -> None:
     conn.execute("INSERT INTO ui_settings (key, value) VALUES (%s, %s) ON CONFLICT (key) DO UPDATE SET value = EXCLUDED.value, updated_at = now()",
-                 (KEY, json.dumps(detail, default=str)))
+                 (_key(chain), json.dumps(detail, default=str)))

fly_trader/agent/minute_engine.py

@@ -30,6 +30,7 @@ from datetime import datetime, timezone
 
 import numpy as np
 
+from .. import config, markets
 from ..db.apilog import record_event
 from ..db.connection import transaction
 from ..market.exit_cost import PUMP_SUPPLY
@@ -78,6 +79,7 @@ class Minute:
     fresh: bool
     trade: bool
     engine: "MinuteEngine"
+    market: object = None     # fly_trader/markets.MarketSpec of these rows (None: Solana)
 
     @property
     def t_start(self) -> float:
@@ -91,7 +93,14 @@ class Minute:
 
 
 class MinuteEngine:
-    def __init__(self, books: list | None = None, live: bool = False):
+    """One market's minutes (``market``: Solana — pump_minutes, corpus_meta — or Robinhood Chain — rh_minutes, rh_meta,
+    amounts in ETH). The engines of both markets share one list of books; each minute goes only to its market's books."""
+
+    def __init__(self, books: list | None = None, live: bool = False, market=None):
+        self.spec = market or markets.SOL; self.rh = self.spec.chain != "sol"
+        # how old a minute may be and still be traded: Solana's feed flushes within seconds; the RH stream's minutes land
+        # ~2–3 min late (confirmations, the index pass, the price marks), so on RH "the current minute" never arrives
+        self.trade_lag_s = float(config.RH_TRADE_LAG_S) if self.rh else 0.0
         self.books = list(books or []); self.live = live
         self.states: dict[str, MintState] = {}
         self.meta_cache: dict[str, dict] = {}; self.last_sweep = time.time(); self.last_minute: float | None = None
@@ -100,21 +109,34 @@ class MinuteEngine:
     def has_book(self, name: str) -> bool:
         return any(b.name == name for b in self.books)
 
+    def tradeable(self, minute: float, m1: float) -> bool:
+        """Whether minute ``minute`` (its end, epoch s) is recent enough to trade at wall-clock minute ``m1``."""
+        return int(m1) - self.trade_lag_s <= int(minute) <= int(m1)
+
+    def my_books(self) -> list:
+        return [b for b in self.books if getattr(b, "chain", "sol") == self.spec.chain]
+
     # ---- lookups ----
     def _meta(self, conn, mint: str) -> dict | None:
         """``corpus_meta`` row (graduation time + creation/creator features), cached for 10 minutes: rows appear at
         graduation and the archive rebuild later replaces stream values, so the cache is refreshed."""
         hit = self.meta_cache.get(mint)
         if hit is None or time.time() - hit["at"] > META_TTL_S:
-            r = conn.execute("SELECT graduated_at, supply, " + ", ".join(META_COLS) + " FROM corpus_meta WHERE mint = %s", (mint,)).fetchone()
+            if self.rh:                                  # Robinhood Chain: rh_meta, the same columns (rh/meta.py), plus the quote class
+                r = conn.execute("SELECT graduated_at, supply, quote_class, " + ", ".join(META_COLS) + " FROM rh_meta WHERE mint = %s", (mint,)).fetchone()
+            else:
+                r = conn.execute("SELECT graduated_at, supply, " + ", ".join(META_COLS) + " FROM corpus_meta WHERE mint = %s", (mint,)).fetchone()
             hit = self.meta_cache[mint] = {"row": dict(r) if r else None, "at": time.time()}
         return hit["row"]
 
     def _state(self, conn, mint: str, pool: str | None, program_label: str | None) -> MintState:
         s = self.states.get(mint)
         if s is None:
-            t = conn.execute("SELECT decimals FROM tokens WHERE mint = %s", (mint,)).fetchone()
-            s = MintState(mint, int((t or {}).get("decimals") or 6), pool, program_label, None, None)
+            if self.rh:                                  # every Pons launch has 18 decimals
+                s = MintState(mint, 18, pool, program_label, None, None); s.meta.ec_size = 0.1 * self.spec.k()
+            else:
+                t = conn.execute("SELECT decimals FROM tokens WHERE mint = %s", (mint,)).fetchone()
+                s = MintState(mint, int((t or {}).get("decimals") or 6), pool, program_label, None, None)
             self.states[mint] = s
         row = self._meta(conn, mint)
         s.meta_row = row
@@ -128,8 +150,11 @@ class MinuteEngine:
         s = self.states.get(mint)
         if s is not None and s.st.last_res_quote_sol:
             return s.st.last_res_quote_sol
-        r = conn.execute("SELECT resq_sol FROM pump_minutes WHERE mint = %s AND resq_sol IS NOT NULL ORDER BY ts DESC LIMIT 1", (mint,)).fetchone()
-        return float(r["resq_sol"]) if r else None
+        if self.rh:
+            r = conn.execute("SELECT resq_eth AS q FROM rh_minutes WHERE mint = %s AND resq_eth IS NOT NULL ORDER BY ts DESC LIMIT 1", (mint,)).fetchone()
+        else:
+            r = conn.execute("SELECT resq_sol AS q FROM pump_minutes WHERE mint = %s AND resq_sol IS NOT NULL ORDER BY ts DESC LIMIT 1", (mint,)).fetchone()
+        return float(r["q"]) if r else None
 
     def _mcap(self, mint: str, price: float | None) -> float | None:
         """Market cap in SOL (price × supply), which sets the pool fee tier; None without a price."""
@@ -138,7 +163,16 @@ class MinuteEngine:
 
     # ---- one minute ----
     def _aggregate(self, conn, m0: datetime, m1: datetime) -> dict[str, dict]:
-        """PumpAPI minutes: every SOL-quoted PumpSwap pump.fun token, the same fields as the archive."""
+        """PumpAPI minutes: every SOL-quoted PumpSwap pump.fun token, the same fields as the archive. Robinhood Chain: the
+        rh_minutes of graduated Pons pools in ETH (rh/minutes.py), under the same keys."""
+        if self.rh:
+            rows = conn.execute("SELECT mint, pool_id, open, high, low, close, buy_eth, sell_eth, n_buys, n_sells, n_traders, resq_eth, fee_rate, "
+                                "n_buyers, wash_eth, wash_buy_eth, top_sell_eth, insider_sell_eth, skill_buy FROM rh_minutes WHERE ts = %s", (m0,)).fetchall()
+            return {r["mint"]: {"open": r["open"], "high": r["high"], "low": r["low"], "close": r["close"], "buy": r["buy_eth"] or 0.0, "sell": r["sell_eth"] or 0.0,
+                                "nb": r["n_buys"] or 0, "ns": r["n_sells"] or 0, "n_traders": int(r["n_traders"] or 0), "resq": r["resq_eth"],
+                                "pool": r["pool_id"], "program_label": self.spec.program_label, "fee_rate": r["fee_rate"],
+                                "n_buyers": r["n_buyers"], "wash_sol": r["wash_eth"], "wash_buy_sol": r["wash_buy_eth"], "top_sell_sol": r["top_sell_eth"],
+                                "insider_sell_sol": r["insider_sell_eth"], "skill_buy": r["skill_buy"]} for r in rows if r["close"]}
         rows = conn.execute("SELECT mint, pool_id, open, high, low, close, buy_sol, sell_sol, n_buys, n_sells, n_traders, resq_sol, fee_rate, "
                             "n_buyers, wash_sol, wash_buy_sol, top_sell_sol, insider_sell_sol, skill_buy FROM pump_minutes WHERE ts = %s", (m0,)).fetchall()
         return {r["mint"]: {"open": r["open"], "high": r["high"], "low": r["low"], "close": r["close"], "buy": r["buy_sol"] or 0.0, "sell": r["sell_sol"] or 0.0,
@@ -151,7 +185,9 @@ class MinuteEngine:
         """The full feature vector (``X_COLS``) of a mint for the minute ending ``t_end``, and what trading needs."""
         s = self._state(conn, mint, a["pool"], a["program_label"])
         st, price, resq = s.st, float(a["close"]), a["resq"]
-        if (s.prev_close and not (1 / 50 <= price / s.prev_close <= 50)) or (resq is not None and resq > 1e5):
+        if self.rh:
+            s.meta.pool_fee = a.get("fee_rate")          # the Pons hook fee this minute charged (the cost model's fee)
+        if (s.prev_close and not (1 / 50 <= price / s.prev_close <= 50)) or (resq is not None and resq > 1e5 * self.spec.k()):
             s.broken = True                          # train/decisions.py: a scale break makes the mint ineligible from that minute on
         s.prev_close = price
         if a["buy"] > 0:
@@ -175,21 +211,27 @@ class MinuteEngine:
                  "meta_known": 1.0 if meta.get("ttg_min") is not None else 0.0, **s.flow.features(t_end), "mkt_vol_1h": self.market.value(t_end)}
         by_name = {**{n: float(f[i]) for i, n in enumerate(FEATURES)}, **extra,
                    **{c: float(meta.get(c)) if meta.get(c) is not None else 0.0 for c in META_COLS}}
+        if self.rh:                                      # the chain inputs (train/decisions.CHAIN_COLS)
+            qc = meta.get("quote_class")
+            by_name.update(chain_rh=1.0, qc_stable=float(qc == "stable"), qc_btc=float(qc == "btc"), qc_stock=float(qc == "stock"))
         x = np.nan_to_num(np.asarray([by_name.get(c, 0.0) for c in X_COLS], dtype=np.float32), nan=0.0, posinf=0.0, neginf=0.0)
         info = {"price": price, "open": float(a["open"]) if a.get("open") else price, "resq": resq, "logvol_15m": f[FIDX["logvol_15m"]],
                 # "ec" is the training label's own cost model (market/exit_cost.cost_at_size), at the size the book trades
-                "ec": float(cost_at_size(f[FIDX["exit_cost_0p1"]], resq)), "age_h": (t_end - s.graduated_at) / 3600 if s.graduated_at else None,
+                "ec": float(cost_at_size(f[FIDX["exit_cost_0p1"]], resq, market=self.spec if self.rh else None)),
+                "age_h": (t_end - s.graduated_at) / 3600 if s.graduated_at else None,
                 "mcap": price * s.meta.supply, "fee_rate": a.get("fee_rate"), "decimals": s.decimals, "pool": s.pool, "program_label": s.program_label, "broken": s.broken,
-                "skill_missing": a.get("skill_buy") is None, "curve_known": bool(meta.get("curve_known"))}
+                "skill_missing": a.get("skill_buy") is None, "curve_known": bool(meta.get("curve_known")), "chain": self.spec.chain,
+                "quote_class": meta.get("quote_class")}
         return x, info
 
-    @staticmethod
-    def eligible(info: dict) -> bool:
+    def eligible(self, info: dict) -> bool:
+        if self.rh:                                      # the same gates in the chain's unit (x K), as training (train/decisions)
+            return not info["broken"] and info["resq"] is not None and info["resq"] >= self.spec.min_resq() and info["logvol_15m"] >= math.log1p(self.spec.min_vol_15m())
         return not info["broken"] and info["resq"] is not None and info["resq"] >= MIN_RESQ_SOL and info["logvol_15m"] >= math.log1p(MIN_VOL_15M_SOL)
 
     def _stream_through(self) -> float | None:
         with transaction() as conn:
-            r = conn.execute("SELECT value->>'flushed_through' AS ft FROM ui_settings WHERE key = 'pumpstream_status'").fetchone()
+            r = conn.execute("SELECT value->>'flushed_through' AS ft FROM ui_settings WHERE key = %s", (self.spec.stream_status_key,)).fetchone()
         return datetime.fromisoformat(r["ft"]).timestamp() if r and r["ft"] else None
 
     def ready_through(self, m1_epoch: float) -> float:
@@ -224,7 +266,7 @@ class MinuteEngine:
                 for mint, a in agg.items():
                     _x, info = self._features(conn, mint, a, t1); n += 1
                     bars[mint] = (t1 - 60.0, info["open"], info["price"], info["ec"])
-                for b in self.books:
+                for b in self.my_books():
                     b.on_bars(t1 - 60.0, bars)
         log.info("warm-up: %d token-minutes over the last %d minutes (%d tokens)", n, minutes, len(self.states))
         return n
@@ -247,9 +289,10 @@ class MinuteEngine:
             X, infos, mints, bars = self._minute_rows(conn, agg, m1_epoch)
             ctx = Minute(conn=conn, m0=m0, m1=m1, m1_epoch=m1_epoch, agg=agg, X=X, infos=infos, mints=mints, bars=bars,
                          prices={m: float(a["close"]) for m, a in agg.items()}, resqs={m: a["resq"] for m, a in agg.items()},
-                         fees={m: a.get("fee_rate") for m, a in agg.items()}, fresh=trade and self.stream_fresh(m1_epoch - 60), trade=trade, engine=self)
+                         fees={m: a.get("fee_rate") for m, a in agg.items()}, fresh=trade and self.stream_fresh(m1_epoch - 60), trade=trade, engine=self,
+                         market=self.spec)
             out.update(mints_traded=len(agg), eligible=len(mints)); held: set[str] = set()
-            for b in list(self.books):
+            for b in list(self.my_books()):
                 try:
                     with conn.transaction():                            # a savepoint per book
                         b.on_bars(m1_epoch - 60.0, bars)
@@ -259,7 +302,7 @@ class MinuteEngine:
                     log.exception("%s: minute %s failed", b.name, m1.isoformat())
                     record_event("error", b.name, f"minute failed: {m1.isoformat()}")
             self._sweep(m1_epoch, held)
-        for b in [b for b in self.books if b.done]:
+        for b in [b for b in self.my_books() if b.done]:
             b.finish(); self.books.remove(b)
         return out
 
@@ -288,35 +331,45 @@ def admit_books(engine: MinuteEngine, live: bool) -> list:
     from . import fly_session, handover
     from .selector_session import NoModel, SelectorBook
     new = []
-    if not engine.has_book("fly"):
-        fb, why = fly_session.try_start(live)
-        if fb is not None:
-            new.append(fb)
-        else:
-            _status("fly_status", {"stage": "not trading", "detail": why})
-    fly_on = engine.has_book("fly") or bool(new)
-    with transaction() as conn:
-        handed = handover.state(conn) is not None
-    if not engine.has_book("selector") and not (handed and fly_on):
-        try:
-            new.append(SelectorBook())
-        except NoModel as e:
-            _status("selector_status", {"stage": "waiting for a model", "detail": str(e)})
+    for m in markets.enabled():                         # Solana first: another chain's fly shares the Solana fly's brain
+        fly_name = "fly" if m.chain == "sol" else f"fly_{m.chain}"; sel_name = "selector" if m.chain == "sol" else f"selector_{m.chain}"
+        if not engine.has_book(fly_name) and not any(b.name == fly_name for b in new):
+            brain = next((b for b in engine.books + new if b.name == "fly"), None) if m.chain != "sol" else None
+            fb, why = fly_session.try_start(live, chain=m.chain, brain=brain)
+            if fb is not None:
+                new.append(fb)
+            else:
+                _status(m.fly_status_key, {"stage": "not trading", "detail": why, "chain": m.chain})
+        fly_on = engine.has_book(fly_name) or any(b.name == fly_name for b in new)
+        with transaction() as conn:
+            handed = handover.state(conn, m.chain) is not None
+        if not engine.has_book(sel_name) and not (handed and fly_on):
+            try:
+                new.append(SelectorBook(m.chain))
+            except NoModel as e:
+                _status(m.selector_status_key, {"stage": "waiting for a model", "detail": str(e), "chain": m.chain})
     return new
 
 
 def main(stop_event: threading.Event | None = None, live: bool = False) -> None:
-    engine = MinuteEngine(live=live)
+    """One engine per enabled chain (markets.enabled()), all sharing one list of books: each engine feeds its minutes, as
+    its own stream writes them, to its chain's books only — a lagging chain never holds another chain's minutes back."""
+    engines = [MinuteEngine(live=live, market=m) for m in markets.enabled()]
+    lead = engines[0]; books: list = []
+    for e in engines:
+        e.books = books                                  # the same list object: admission and removal are seen by every engine
     while not (stop_event is not None and stop_event.is_set()):
-        engine.books = admit_books(engine, live)
-        if engine.books:
+        books += admit_books(lead, live)
+        if books:
             break
         log.info("trading engine waiting: no book qualifies yet")
         (stop_event or threading.Event()).wait(MODEL_CHECK_S)
     else:
         return
     m_start = math.floor(time.time() / 60) * 60
-    engine.warm_up(m_start); engine.last_minute = m_start - 60; last_check = time.time(); n_min = 0
+    for e in engines:
+        e.warm_up(m_start); e.last_minute = m_start - 60
+    last_check = time.time(); n_min = 0
     last_release, last_stamp_check = release_stamp(), 0.0
     try:
         while not (stop_event is not None and stop_event.is_set()):
@@ -327,31 +380,35 @@ def main(stop_event: threading.Event | None = None, live: bool = False) -> None:
                     last_release, last_check = stamp, 0.0
             if now - last_check >= MODEL_CHECK_S:
                 last_check = now
-                for b in engine.books:
+                for b in books:
                     try:
                         b.maybe_reload()
                     except Exception:
                         log.exception("%s: model reload check failed", b.name)
                 try:
-                    engine.books += admit_books(engine, live)
+                    books += admit_books(lead, live)
                 except Exception:
                     log.exception("book admission failed")
-            if engine.books and m1 > engine.last_minute and now - m1 >= 4.0 and (upto := engine.ready_through(m1)) > engine.last_minute:   # only minutes the stream has written
+            for engine in engines:
+                if not engine.my_books() or m1 <= engine.last_minute or now - m1 < 4.0:
+                    continue
+                if (upto := engine.ready_through(m1)) <= engine.last_minute:        # only minutes this chain's stream has written
+                    continue
                 for minute in range(int(engine.last_minute) + 60, int(upto) + 1, 60):
                     try:
-                        st = engine.run_minute(float(minute), trade=(minute == int(m1)))   # missed minutes update features (and the fly's learning) only
+                        st = engine.run_minute(float(minute), trade=engine.tradeable(minute, m1))   # older minutes update features (and the fly's learning) only
                         n_min += 1
-                        if minute == int(m1) and n_min % 10 == 0:
-                            log.info("minute %s: traded %d eligible %d | %s", st["minute"], st.get("mints_traded", 0), st.get("eligible", 0),
+                        if engine.tradeable(minute, m1) and n_min % 10 == 0:
+                            log.info("%s minute %s: traded %d eligible %d | %s", engine.spec.chain, st["minute"], st.get("mints_traded", 0), st.get("eligible", 0),
                                      " | ".join(f"{b.name}: picks {(st.get(b.name) or {}).get('picks')} open {(st.get(b.name) or {}).get('open')} wealth {(st.get(b.name) or {}).get('wealth')}"
-                                                for b in engine.books))
+                                                for b in engine.my_books()))
                     except Exception:
-                        log.exception("minute %s failed", minute); record_event("error", "engine", f"minute failed: {minute}")
+                        log.exception("%s minute %s failed", engine.spec.chain, minute); record_event("error", "engine", f"{engine.spec.chain} minute failed: {minute}")
                 engine.last_minute = upto
             time.sleep(0.5)
     finally:
-        for b in engine.books:
+        for b in books:
             try:
                 b.finish()
             except Exception:
-                log.exception("%s: finish failed", b.name)
+                log.exception("%s: finish failed", b.name)

fly_trader/agent/paper_trading.py

@@ -20,10 +20,11 @@ from ..market.exit_cost import exit_cost_fraction
 
 def trade_minute(ctx, *, book: str, run_id: str, beat_no: int, broker, kind: str, mints: list, infos: list, scores, threshold,
                  table: list | None, horizon_s: float, block: str | None = None, holds=None, strategies=None, allow=None, reasons=None,
-                 tables: list | None = None) -> dict:
+                 tables: list | None = None, flat: bool = False) -> dict:
     """Optional per-row arguments (the selector's strategy stack, train/strategies.decide): ``threshold`` may be per row,
     ``holds`` (s), ``strategies``, ``tables`` (sizing) and ``allow`` / ``reasons`` (a blocked row is recorded with its reason).
-    Left out, the call behaves exactly as the single-strategy engine."""
+    Left out, the call behaves exactly as the single-strategy engine. ``flat``: every buy the same share of the bankroll
+    (agent/sizing.size_position), the fly's rule (``config.FLY_SIZING``)."""
     conn, m1 = ctx.conn, ctx.m1
     beat = conn.execute("INSERT INTO beats (run_id, ts, beat_no, n_slots_active, notes) VALUES (%s,%s,%s,%s,%s) RETURNING id",
                         (run_id, m1, beat_no, len(mints), json.dumps({"minute": m1.isoformat(), "mints_traded": len(ctx.agg), "book": book}))).fetchone()["id"]
@@ -41,7 +42,9 @@ def trade_minute(ctx, *, book: str, run_id: str, beat_no: int, broker, kind: str
     opens_now = ledger.open_positions(conn, book); open_mints = {p["mint"] for p in opens_now}
     cash = ledger.paper_cash(conn, book); n_enter = 0; picks = []; entries = []
     bankroll = cash + sum(float(p["cost_sol"]) for p in opens_now)         # wealth at cost: the sizing base (agent/sizing.py)
-    circuit = conn.execute("SELECT kill_switch, entries_paused FROM circuit_state WHERE id = 1").fetchone()
+    from ..markets import for_book
+    market = for_book(book)                                     # the book's market: its circuit, money settings and sizes
+    circuit = conn.execute("SELECT kill_switch, entries_paused FROM circuit_state WHERE id = %s", (market.circuit_id,)).fetchone()
     blocked = (block or ("kill switch" if circuit and circuit["kill_switch"] else None) or ("paused" if circuit and circuit["entries_paused"] else None)
                or ("book halted" if rails.book_halted(conn, book) else None))
     thr_v = np.broadcast_to(np.asarray(threshold, dtype=np.float64), (len(mints),)) if len(mints) else np.array([])
@@ -51,7 +54,7 @@ def trade_minute(ctx, *, book: str, run_id: str, beat_no: int, broker, kind: str
             continue
         picks.append((m, float(sc)))
         tab_k = tables[k] if tables is not None else table
-        size, why = sizing.size_position(float(sc), thr_k, tab_k or [], bankroll, cash, i["resq"])
+        size, why = sizing.size_position(float(sc), thr_k, tab_k or [], bankroll, cash, i["resq"], flat=flat, market=market)
         denied = allow is not None and not bool(allow[k])
         if m in open_mints or blocked or denied or size <= 0:
             rail = blocked or ("held" if m in open_mints else (str(reasons[k]) if denied and reasons is not None else "filtered") if denied else "sizing")
@@ -84,6 +87,6 @@ def trade_minute(ctx, *, book: str, run_id: str, beat_no: int, broker, kind: str
     peak_row = conn.execute("SELECT max(wealth) AS pk FROM wealth_marks WHERE book = %s", (book,)).fetchone(); peak = max(float(peak_row["pk"] or 0.0), wealth)
     conn.execute("INSERT INTO wealth_marks (beat_id, book, ts, sol_free, positions_value, exit_cost, wealth, peak, drawdown, exposure, n_open) VALUES (%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s)",
                  (beat, book, m1, cash, positions_net, exit_cost, wealth, peak, (1.0 - wealth / peak) if peak > 0 else 0.0, exposure, len(opens)))
-    rails.check_book_drawdown(conn, book, wealth, peak)        # the book's own kill switch: blocks its next minutes' entries
+    rails.check_book_drawdown(conn, book, wealth, peak, drawdown=market.kill_drawdown(), unit=market.unit)   # the book's own kill switch
     return {"beat_id": beat, "entries": entries, "entered": n_enter, "exited": n_exit, "open": len(opens), "cash": cash, "wealth": wealth, "picks": len(picks), "blocked": blocked,
             "top_scores": sorted(picks, key=lambda x: -x[1])[:5], "open_mints": sorted({p["mint"] for p in opens})}

fly_trader/agent/rails.py

@@ -1,6 +1,9 @@
 """Risk rails outside the model. KillSwitch (−KILL_SWITCH_DRAWDOWN from peak wealth → no entries), CircuitBreaker
 (CIRCUIT_THRESHOLD consecutive execution failures), the rolling 24 h notional ledger, and PauseEntries (console
 toggle). State lives in circuit_state / circuit_events / notional_ledger; the trading engine reads it before entries.
+One circuit per trading type: ``circuit_id`` 1 is the memecoin live book (the default everywhere), 2 the Kalshi live
+books (``KALSHI_CIRCUIT``, fly_trader/kalshi), 3 the Robinhood Chain memecoin live book (``RH_CIRCUIT``,
+fly_trader/rh); ``check_drawdown`` takes the drawdown limit of the caller's type.
 """
 from __future__ import annotations
 
@@ -13,6 +16,7 @@ from ..db.apilog import record_event
 from ..db.connection import transaction
 
 log = logging.getLogger(__name__)
+SOLANA_CIRCUIT, KALSHI_CIRCUIT, RH_CIRCUIT = 1, 2, 3
 
 
 @dataclass
@@ -25,63 +29,80 @@ class CircuitState:
     entries_paused: bool = False
 
 
-def load_circuit(conn) -> CircuitState:
-    r = conn.execute("SELECT * FROM circuit_state WHERE id = 1").fetchone()
+def load_circuit(conn, circuit_id: int = SOLANA_CIRCUIT) -> CircuitState:
+    r = conn.execute("SELECT * FROM circuit_state WHERE id = %s", (circuit_id,)).fetchone()
     if not r:
         return CircuitState()
     return CircuitState(r["fail_count"], r["tripped"], r["kill_switch"], r["kill_reason"], r["peak_wealth"], r["entries_paused"])
 
 
-def _event(conn, kind: str, detail: dict | None = None) -> None:
-    conn.execute("INSERT INTO circuit_events (kind, detail) VALUES (%s, %s)", (kind, json.dumps(detail or {}, default=str)))
+def _event(conn, kind: str, detail: dict | None = None, circuit_id: int = SOLANA_CIRCUIT) -> None:
+    conn.execute("INSERT INTO circuit_events (kind, detail) VALUES (%s, %s)", (kind, json.dumps({**(detail or {}), "circuit": circuit_id}, default=str)))
 
 
-def record_failure(conn, reason: str) -> CircuitState:
+def record_failure(conn, reason: str, circuit_id: int = SOLANA_CIRCUIT) -> CircuitState:
     r = conn.execute(
-        "UPDATE circuit_state SET fail_count = fail_count + 1, last_failure_ts = now(), updated_at = now() WHERE id = 1 RETURNING fail_count, tripped"
+        "UPDATE circuit_state SET fail_count = fail_count + 1, last_failure_ts = now(), updated_at = now() WHERE id = %s RETURNING fail_count, tripped", (circuit_id,)
     ).fetchone()
     tripped = r["tripped"]
     if r["fail_count"] >= config.CIRCUIT_THRESHOLD and not tripped:
-        conn.execute("UPDATE circuit_state SET tripped = true, updated_at = now() WHERE id = 1")
-        _event(conn, "tripped", {"reason": reason, "fail_count": r["fail_count"]})
-        record_event("error", "rails", "circuit breaker tripped", {"reason": reason})
-    return load_circuit(conn)
+        conn.execute("UPDATE circuit_state SET tripped = true, updated_at = now() WHERE id = %s", (circuit_id,))
+        _event(conn, "tripped", {"reason": reason, "fail_count": r["fail_count"]}, circuit_id)
+        record_event("error", "rails", "circuit breaker tripped", {"reason": reason, "circuit": circuit_id})
+    return load_circuit(conn, circuit_id)
 
 
-def record_success(conn) -> None:
-    conn.execute("UPDATE circuit_state SET fail_count = 0, updated_at = now() WHERE id = 1")
+def record_success(conn, circuit_id: int = SOLANA_CIRCUIT) -> None:
+    conn.execute("UPDATE circuit_state SET fail_count = 0, updated_at = now() WHERE id = %s", (circuit_id,))
 
 
-def check_drawdown(conn, wealth: float, peak: float) -> bool:
-    """Trip the kill switch when ``wealth`` has fallen KILL_SWITCH_DRAWDOWN below ``peak`` (the book's own peak: the
-    trading engine passes the highest wealth mark of the current run). Returns whether the kill switch is on."""
-    st = load_circuit(conn)
+def check_drawdown(conn, wealth: float, peak: float, circuit_id: int = SOLANA_CIRCUIT, drawdown: float | None = None, unit: str = "SOL") -> bool:
+    """Trip the kill switch when ``wealth`` has fallen ``drawdown`` (default KILL_SWITCH_DRAWDOWN) below ``peak`` (the book's
+    own peak: the trading engine passes the highest wealth mark of the current run). Returns whether the kill switch is on."""
+    st = load_circuit(conn, circuit_id)
     if st.kill_switch:
         return True
-    if peak > 0 and wealth <= peak * (1.0 - config.KILL_SWITCH_DRAWDOWN):
-        conn.execute("UPDATE circuit_state SET kill_switch = true, kill_reason = %s, peak_wealth = %s, updated_at = now() WHERE id = 1",
-                     (f"wealth {wealth:.4f} SOL <= {1 - config.KILL_SWITCH_DRAWDOWN:.2f} x peak {peak:.4f} SOL", peak))
-        _event(conn, "kill_switch", {"wealth": wealth, "peak": peak})
-        record_event("error", "rails", "kill switch tripped: entries blocked", {"wealth": wealth, "peak": peak})
+    dd = config.KILL_SWITCH_DRAWDOWN if drawdown is None else float(drawdown)
+    if peak > 0 and wealth <= peak * (1.0 - dd):
+        conn.execute("UPDATE circuit_state SET kill_switch = true, kill_reason = %s, peak_wealth = %s, updated_at = now() WHERE id = %s",
+                     (f"wealth {wealth:.4f} {unit} <= {1 - dd:.2f} x peak {peak:.4f} {unit}", peak, circuit_id))
+        _event(conn, "kill_switch", {"wealth": wealth, "peak": peak}, circuit_id)
+        record_event("error", "rails", "kill switch tripped: entries blocked", {"wealth": wealth, "peak": peak, "circuit": circuit_id})
+        if config.VAULT_ENABLED:                         # the hosted fly: tell the operator at once
+            try:
+                from ..vault import alerts
+                alerts.send(f"KILL SWITCH tripped: {wealth:.4f} {unit} <= {1 - dd:.2f} x peak {peak:.4f} {unit}. Entries blocked"
+                            + (", open positions are being liquidated" if config.KILL_SWITCH_LIQUIDATE else "")
+                            + ". Clear it with `fly-trader reset-circuit --kill` once you know why.")
+            except Exception:
+                pass
         return True
     return False
 
 
-def kill_rebase_at(conn, circuit_id: int = 1):
-    """When the kill switch was last cleared: peaks are measured from marks after it, so clearing really re-bases.
-    (Before this, the live book recomputed its peak from every wealth mark ever and re-tripped the next minute.)"""
-    r = conn.execute("SELECT max(ts) AS ts FROM circuit_events WHERE kind = 'reset' AND (detail->>'kill')::boolean "
+def kill_rebase_at(conn, circuit_id: int = SOLANA_CIRCUIT):
+    """When the kill switch was last cleared, or money last withdrawn from the live wallet: peaks are measured from marks
+    after it, so clearing really re-bases and a withdrawal is never a drawdown. (Before this, the live book recomputed its
+    peak from every wealth mark ever and re-tripped the next minute.)"""
+    r = conn.execute("SELECT max(ts) AS ts FROM circuit_events WHERE ((kind = 'reset' AND (detail->>'kill')::boolean) OR kind = 'withdrawal') "
                      "AND COALESCE((detail->>'circuit')::int, 1) = %s", (circuit_id,)).fetchone()
     return r["ts"] if r else None
 
 
-def check_book_drawdown(conn, book: str, wealth: float, peak: float) -> bool:
-    """A paper race book's own kill switch: KILL_SWITCH_DRAWDOWN below the book's peak halts that book's entries only,
-    so one book's drawdown never stops the other during the race. Returns whether the book is halted."""
+def record_withdrawal(conn, detail: dict, circuit_id: int = SOLANA_CIRCUIT) -> None:
+    """The operator took money out of a live wallet (chain/withdraw.py, rh/withdraw.py): ``kill_rebase_at`` re-bases the
+    live book's peak at it."""
+    _event(conn, "withdrawal", detail, circuit_id)
+
+
+def check_book_drawdown(conn, book: str, wealth: float, peak: float, drawdown: float | None = None, unit: str = "SOL") -> bool:
+    """A paper race book's own kill switch: ``drawdown`` (default KILL_SWITCH_DRAWDOWN) below the book's peak halts that
+    book's entries only, so one book's drawdown never stops the other during the race. Returns whether the book is halted."""
     if book_halted(conn, book):
         return True
-    if peak > 0 and wealth <= peak * (1.0 - config.KILL_SWITCH_DRAWDOWN):
-        reason = f"wealth {wealth:.4f} SOL <= {1 - config.KILL_SWITCH_DRAWDOWN:.2f} x peak {peak:.4f} SOL"
+    dd = config.KILL_SWITCH_DRAWDOWN if drawdown is None else float(drawdown)
+    if peak > 0 and wealth <= peak * (1.0 - dd):
+        reason = f"wealth {wealth:.4f} {unit} <= {1 - dd:.2f} x peak {peak:.4f} {unit}"
         conn.execute("INSERT INTO book_state (book, halted, reason, peak, updated_at) VALUES (%s, true, %s, %s, now()) "
                      "ON CONFLICT (book) DO UPDATE SET halted = true, reason = EXCLUDED.reason, peak = EXCLUDED.peak, updated_at = now()",
                      (book, reason, peak))
@@ -103,28 +124,29 @@ def clear_book_halt(book: str) -> None:
     record_event("info", "rails", f"{book}: drawdown halt cleared")
 
 
-def notional_24h(conn) -> float:
-    r = conn.execute("SELECT COALESCE(sum(sol), 0) AS s FROM notional_ledger WHERE ts > now() - interval '24 hours'").fetchone()
+def notional_24h(conn, market: str = "sol") -> float:
+    """The last 24 h of entries in ``market``'s unit (``sol`` holds ETH on the ``rh`` market's rows)."""
+    r = conn.execute("SELECT COALESCE(sum(sol), 0) AS s FROM notional_ledger WHERE ts > now() - interval '24 hours' AND market = %s", (market,)).fetchone()
     return float(r["s"])
 
 
-def record_notional(conn, sol: float, kind: str = "entry") -> None:
-    conn.execute("INSERT INTO notional_ledger (sol, kind) VALUES (%s, %s)", (sol, kind))
+def record_notional(conn, sol: float, kind: str = "entry", market: str = "sol") -> None:
+    conn.execute("INSERT INTO notional_ledger (sol, kind, market) VALUES (%s, %s, %s)", (sol, kind, market))
 
 
-def reset_circuit(kill: bool = False) -> None:
+def reset_circuit(kill: bool = False, circuit_id: int = SOLANA_CIRCUIT) -> None:
     with transaction() as conn:
-        conn.execute("UPDATE circuit_state SET fail_count = 0, tripped = false, updated_at = now() WHERE id = 1")
-        _event(conn, "reset", {"kill": kill})
+        conn.execute("UPDATE circuit_state SET fail_count = 0, tripped = false, updated_at = now() WHERE id = %s", (circuit_id,))
+        _event(conn, "reset", {"kill": kill}, circuit_id)
         if kill:
-            conn.execute("UPDATE circuit_state SET kill_switch = false, kill_reason = NULL, peak_wealth = NULL, updated_at = now() WHERE id = 1")
-    record_event("info", "rails", "circuit reset" + (" incl. kill switch (peak re-based)" if kill else ""))
+            conn.execute("UPDATE circuit_state SET kill_switch = false, kill_reason = NULL, peak_wealth = NULL, updated_at = now() WHERE id = %s", (circuit_id,))
+    record_event("info", "rails", "circuit reset" + (" incl. kill switch (peak re-based)" if kill else ""), {"circuit": circuit_id})
     print("circuit reset" + (" + kill switch cleared" if kill else ""))
 
 
-def set_entries_paused(paused: bool) -> None:
+def set_entries_paused(paused: bool, circuit_id: int = SOLANA_CIRCUIT) -> None:
     with transaction() as conn:
-        conn.execute("UPDATE circuit_state SET entries_paused = %s, updated_at = now() WHERE id = 1", (paused,))
-        _event(conn, "paused" if paused else "resumed", {})
-    record_event("info", "rails", "entries paused" if paused else "entries resumed")
+        conn.execute("UPDATE circuit_state SET entries_paused = %s, updated_at = now() WHERE id = %s", (paused, circuit_id))
+        _event(conn, "paused" if paused else "resumed", {}, circuit_id)
+    record_event("info", "rails", "entries paused" if paused else "entries resumed", {"circuit": circuit_id})
     print("entries paused" if paused else "entries resumed")

fly_trader/agent/selector_session.py

@@ -50,23 +50,53 @@ def pinned_snapshot() -> int | None:
     return int(v) if v is not None else None
 
 
-class SelectorBook:
-    name = "selector"
+def chain_deployable(model, chain: str) -> tuple[bool, str]:
+    """Whether the selector may trade ``chain``: Solana by its own deployability (as before); another chain only when the
+    combined stack's holdout on that chain's rows showed an edge (train/strategies.score_holdout_by_chain)."""
+    if chain == "sol":
+        return True, "ok"
+    c = ((getattr(model, "metrics", None) or {}).get("chains") or {}).get(chain)
+    if not c:
+        return False, f"the selector was not judged on {chain} rows"
+    return bool(c.get("deployable")), f"{chain} holdout: {c.get('n', 0)} trades, mean {(c.get('mean') or 0) * 100:+.2f}% (random {(c.get('random_mean') or 0) * 100:+.2f}%)"
+
+
+def fail_closed(groups: set, infos: list, d: dict) -> dict:
+    """The selector's live fail-closed rules on a ``strategies.decide`` result (in place): rows whose inputs training had
+    but live lacks are blocked. Shared by the fly's teacher gate (agent/fly_session.py), so both books obey the same rules."""
+    for k, i in enumerate(infos):
+        if not d["allow"][k]:
+            continue
+        if "skill" in groups and i.get("skill_missing"):
+            d["allow"][k] = False; d["reason"][k] = "fail closed: no wallet-skill table for today"
+        elif "rug" in groups and i.get("age_h") is not None and not i.get("curve_known"):
+            d["allow"][k] = False; d["reason"][k] = "fail closed: curve facts not known yet"
+    return d
+
 
-    def __init__(self):
+class SelectorBook:
+    def __init__(self, chain: str = "sol"):
+        from .. import markets
         from ..train import selector as sel
+        self.chain = chain; self.market = markets.for_chain(chain)
+        self.name = "selector" if chain == "sol" else f"selector_{chain}"
+        self.BOOK = self.market.selector_book; self.KIND = self.name; self.status_key = self.market.selector_status_key
         pin = pinned_snapshot()
         self.model = sel.load_snapshot(pin) if pin is not None else sel.load_latest()
         if self.model is None:
             raise NoModel("no model has qualified to trade yet (trained on the current data, with a backtest that made money after costs and beat random picks)")
+        ok, why = chain_deployable(self.model, chain)
+        if not ok:
+            raise NoModel(f"the selector may not trade {self.market.name}: {why}")
         self.idx = _columns(self.model)
         self.horizon_s = self.model.horizon_min * 60
-        self.broker = PaperBroker(BOOK); self.done = False
+        self.broker = PaperBroker(self.BOOK); self.done = False
         self.run_id = str(uuid.uuid4()); self.beat_no = 0
         with transaction() as conn:
             self.snapshot_id = pin if pin is not None else sel.latest_current(conn)["id"]   # the snapshot actually loaded
             conn.execute("INSERT INTO runs (run_id, kind, config, brain_snapshot_id, status) VALUES (%s,%s,%s,%s,'running')",
-                         (self.run_id, KIND, json.dumps({"threshold": self.model.threshold, "horizon_min": self.model.horizon_min, "book": BOOK}, default=str), self.snapshot_id))
+                         (self.run_id, self.KIND, json.dumps({"threshold": self.model.threshold, "horizon_min": self.model.horizon_min, "book": self.BOOK, "chain": chain},
+                                                             default=str), self.snapshot_id))
         record_event("info", "selector", "selector session started", {"run_id": self.run_id, "snapshot": self.snapshot_id, "threshold": self.model.threshold, "horizon_min": self.model.horizon_min})
         log.info("selector session: snapshot %d threshold %.4f horizon %d min", self.snapshot_id, self.model.threshold, self.model.horizon_min)
 
@@ -74,8 +104,7 @@ class SelectorBook:
         """Switch to a newer deployable model without a restart (the paper book and open positions carry on). While a
         snapshot is pinned (``ui_settings['pinned_selector_snapshot']``) the book stays on it, so a forward test measures
         one model instead of a blend of every retrain that lands during it."""
-        import joblib
-        from ..train import selector as sel
+        from ..train import model_io, selector as sel
         pin = pinned_snapshot()
         with transaction() as conn:
             if pin is not None:                        # a pin freezes the book, but a NEW pin (a release) switches to it
@@ -86,7 +115,7 @@ class SelectorBook:
                 r = sel.latest_current(conn)
         if not r or r["id"] == self.snapshot_id:
             return False
-        m = joblib.load(r["path"])
+        m = model_io.load_selector(r["path"])
         try:
             idx = _columns(m)
         except RuntimeError as e:
@@ -95,7 +124,7 @@ class SelectorBook:
         old = self.snapshot_id; self.model, self.idx, self.snapshot_id, self.horizon_s = m, idx, r["id"], m.horizon_min * 60
         with transaction() as conn:
             conn.execute("UPDATE runs SET brain_snapshot_id = %s, config = %s WHERE run_id = %s",
-                         (r["id"], json.dumps({"threshold": m.threshold, "horizon_min": m.horizon_min, "book": BOOK}, default=str), self.run_id))
+                         (r["id"], json.dumps({"threshold": m.threshold, "horizon_min": m.horizon_min, "book": self.BOOK}, default=str), self.run_id))
         record_event("info", "selector", f"switched to model #{r['id']}", {"from": old, "to": r["id"], "threshold": m.threshold})
         log.info("switched from model #%s to #%d (threshold %.4f)", old, r["id"], m.threshold)
         return True
@@ -104,7 +133,7 @@ class SelectorBook:
         pass
 
     def open_mints(self, conn) -> set[str]:
-        return {p["mint"] for p in ledger.open_positions(conn, BOOK)}
+        return {p["mint"] for p in ledger.open_positions(conn, self.BOOK)}
 
     def _decide(self, ctx) -> dict | None:
         """The strategy stack's per-row decision (train/strategies.decide), with the live fail-closed rules: rows whose
@@ -113,15 +142,7 @@ class SelectorBook:
         if not (getattr(self.model, "stack", None) or {}).get("strategies") or not len(ctx.mints):
             return None
         d = self.model.decide(ctx.X, X_COLS, ctx.t_start)
-        groups = set((getattr(self.model, "metrics", None) or {}).get("groups") or [])
-        for k, i in enumerate(ctx.infos):
-            if not d["allow"][k]:
-                continue
-            if "skill" in groups and i.get("skill_missing"):
-                d["allow"][k] = False; d["reason"][k] = "fail closed: no wallet-skill table for today"
-            elif "rug" in groups and i.get("age_h") is not None and not i.get("curve_known"):
-                d["allow"][k] = False; d["reason"][k] = "fail closed: curve facts not known yet"
-        return d
+        return fail_closed(set((getattr(self.model, "metrics", None) or {}).get("groups") or []), ctx.infos, d)
 
     def on_minute(self, ctx) -> dict:
         conn = ctx.conn
@@ -141,10 +162,10 @@ class SelectorBook:
             status = {**summary, "stage": "stream stale: holding (no entries or exits)", "updated_at": datetime.now(timezone.utc).isoformat()}
             self._write_status(conn, status)
             return status
-        handed = handover.state(conn) is not None and ctx.engine.has_book("fly")
+        handed = handover.state(conn, self.chain) is not None and ctx.engine.has_book("fly" if self.chain == "sol" else f"fly_{self.chain}")
         self.beat_no += 1
         extra = {} if d is None else {"holds": d["hold_s"], "strategies": d["strategy"], "allow": d["allow"], "reasons": d["reason"], "tables": d["tables"]}
-        st = paper_trading.trade_minute(ctx, book=BOOK, run_id=self.run_id, beat_no=self.beat_no, broker=self.broker, kind=KIND, mints=ctx.mints, infos=ctx.infos,
+        st = paper_trading.trade_minute(ctx, book=self.BOOK, run_id=self.run_id, beat_no=self.beat_no, broker=self.broker, kind=self.KIND, mints=ctx.mints, infos=ctx.infos,
                                         scores=scores, threshold=thr, table=getattr(self.model, "sizing", None), horizon_s=self.horizon_s,
                                         block="handed over to the fly" if handed else None, **extra)
         if handed and st["open"] == 0:
@@ -155,10 +176,9 @@ class SelectorBook:
         self._write_status(conn, status)
         return status
 
-    @staticmethod
-    def _write_status(conn, status: dict) -> None:
-        conn.execute("INSERT INTO ui_settings (key, value) VALUES ('selector_status', %s) ON CONFLICT (key) DO UPDATE SET value = EXCLUDED.value, updated_at = now()",
-                     (json.dumps(status, default=str),))
+    def _write_status(self, conn, status: dict) -> None:
+        conn.execute("INSERT INTO ui_settings (key, value) VALUES (%s, %s) ON CONFLICT (key) DO UPDATE SET value = EXCLUDED.value, updated_at = now()",
+                     (self.status_key, json.dumps({**status, "chain": self.chain}, default=str)))
 
     def finish(self) -> None:
         with transaction() as conn:

fly_trader/agent/sizing.py

@@ -4,16 +4,20 @@ Certainty is measured, not assumed. During training the backtest's out-of-sample
 score cleared the buy line (``build_table``: equal-count bands of ``score − threshold``). For each band the growth-optimal
 (Kelly) fraction is found on the band's actual net returns — the bet f that maximises the average of log(1 + f·r), so the
 rare −100 % rugs count in full; a band with no edge gets 0. Live (``size_position``): the current score's band →
-``KELLY_FRACTION`` of that fraction of the deployable bankroll (wealth at cost minus the gas reserve), capped at
-``MAX_POSITION_FRACTION`` of it, ``MAX_POOL_SHARE`` of the pool's quote reserve (bigger buys pay more price impact than
-the 0.1 SOL the backtest measured) and the free cash above the reserve; below ``MIN_POSITION_SOL`` the buy is skipped.
-A model without a table (trained before sizing) trades the fixed ``MAX_POSITION_SOL``.
+``KELLY_FRACTION`` of that fraction of the deployable bankroll (wealth at cost minus the gas reserve); ``flat`` (the
+fly, ``config.FLY_SIZING``): ``MAX_POSITION_FRACTION`` of it on every buy that cleared the line, no bands. Either way
+capped at ``MAX_POSITION_FRACTION`` of the deployable bankroll, the free cash above the reserve, and the label size
+(``market/exit_cost.label_size``: ``LABEL_SIZE_SOL`` or ``MAX_POOL_SHARE`` of the pool) -- the size every edge was
+measured at, so the book behaves the same with 5 SOL or 500: a bigger bankroll buys no bigger than the backtest did,
+it only runs out of cash later. Below ``MIN_POSITION_SOL`` the buy is skipped. A model without a table (trained
+before sizing) trades the fixed ``MAX_POSITION_SOL``, under the same caps.
 """
 from __future__ import annotations
 
 import numpy as np
 
 from .. import config
+from ..market.exit_cost import label_size
 
 N_BANDS = 4
 MIN_BAND_TRADES = 50
@@ -57,26 +61,31 @@ def band_for(table: list[dict], margin: float) -> dict | None:
 
 
 def size_position(score: float, threshold: float, table: list[dict] | None, bankroll_sol: float, cash_sol: float,
-                  res_quote_sol: float | None) -> tuple[float, str]:
-    """(size in SOL, why). Size 0 means skip the buy."""
-    reserve = config.GAS_RESERVE_SOL; free = cash_sol - reserve
-    if not table:
-        size = config.MAX_POSITION_SOL
-        return (size, f"fixed {size:g} SOL (model has no sizing table)") if free >= size else (0.0, "not enough free cash")
-    b = band_for(table, score - threshold)
-    if b is None or b["kelly"] <= 0:
-        return 0.0, "no edge in this score band"
+                  res_quote_sol: float | None, flat: bool = False, market=None) -> tuple[float, str]:
+    """(size in the book's unit, why). Size 0 means skip the buy. ``flat``: ``MAX_POSITION_FRACTION`` of the deployable
+    bankroll on every buy that cleared the line (the fly); otherwise the Kelly band of ``table``. ``market``
+    (fly_trader/markets; default Solana): the gas reserve, minimum position and label size of the book's own market."""
+    rh = market is not None and market.chain != "sol"
+    reserve = market.gas_reserve() if rh else config.GAS_RESERVE_SOL; free = cash_sol - reserve
+    min_pos = market.min_position() if rh else config.MIN_POSITION_SOL
     deployable = max(0.0, bankroll_sol - reserve)
-    size = config.KELLY_FRACTION * b["kelly"] * deployable
-    caps = {"bankroll cap": config.MAX_POSITION_FRACTION * deployable, "free cash": free}
-    if res_quote_sol:
-        caps["pool depth"] = config.MAX_POOL_SHARE * res_quote_sol
+    if flat:
+        size = config.MAX_POSITION_FRACTION * deployable; why = f"flat {config.MAX_POSITION_FRACTION:g} of {deployable:.2f} SOL"
+    elif not table:
+        size = config.MAX_POSITION_SOL * (market.k() if rh else 1.0); why = f"fixed {size:g} {'ETH' if rh else 'SOL'} (model has no sizing table)"
+    else:
+        b = band_for(table, score - threshold)
+        if b is None or b["kelly"] <= 0:
+            return 0.0, "no edge in this score band"
+        size = config.KELLY_FRACTION * b["kelly"] * deployable
+        why = f"band from +{b['lo']:.3f} over the line: Kelly {b['kelly']:.2f} × {config.KELLY_FRACTION:g} of {deployable:.2f} SOL"
+    # the label size is the largest buy any backtest measured: past it the edge is an extrapolation that impact eats
+    caps = {"bankroll cap": config.MAX_POSITION_FRACTION * deployable, "free cash": free, "label size": label_size(res_quote_sol, market if rh else None)}
     limit = min(caps, key=caps.get)
-    why = f"band from +{b['lo']:.3f} over the line: Kelly {b['kelly']:.2f} × {config.KELLY_FRACTION:g} of {deployable:.2f} SOL"
     if caps[limit] < size:
         size = caps[limit]; why += f", capped by {limit}"
-    if size < config.MIN_POSITION_SOL:
-        return 0.0, why + f" → {size:.3f} SOL is below the {config.MIN_POSITION_SOL:g} SOL minimum"
+    if size < min_pos:
+        return 0.0, why + f" → {max(size, 0.0):.6f} is below the {min_pos:g} minimum"
     return float(size), why + f" → {size:.3f} SOL"
 
 

fly_trader/brain/connectome.py

@@ -115,6 +115,9 @@ class Connectome:
                                                             self.pop_ranges, self.pathway_gains)
         self.W_KM0 = torch.from_numpy(np.ascontiguousarray(z["W_KM0"])).to(torch.float32)
         self.M_KM = torch.from_numpy(np.ascontiguousarray(z["M_KM"])).to(torch.bool)
+        # FlyBrain's finer annotation per neuron (VIS_R1R6, VIS_ME, LPTC, ...): the Kalshi fly finds its photoreceptors by it
+        self.flybrain_group = np.asarray(z["flybrain_group"]) if "flybrain_group" in z.files else None
+        self.flybrain_group_names = [str(x) for x in z["flybrain_group_names"]] if "flybrain_group_names" in z.files else []
         self.spectral_radius_raw = float(z["spectral_radius_raw"])
         self.content_sha256 = str(z["content_sha256"])
         self.s = float(scale["s"]) if scale and "s" in scale else float(z["s0"])
@@ -159,3 +162,27 @@ class SubConnectome:
         self.pathway_gains = getattr(c, "pathway_gains", {})
         self.excluded = exclude
         self.keep = keep
+        fg = getattr(c, "flybrain_group", None)
+        self.flybrain_group = fg[keep.numpy()] if fg is not None else None
+        self.flybrain_group_names = list(getattr(c, "flybrain_group_names", []))
+
+
+# ---------------------------------------------------------------- the Kalshi fly's graph: the optic lobes kept, the memecoin senses dropped
+VISUAL_SUB = tuple(AFFERENT_POPS)                # exclude these and VISUAL stays: the second fly's sub-connectome
+PHOTORECEPTOR_GROUPS = ("VIS_R1R6", "VIS_R7R8")  # FlyBrain groups of the retina's photoreceptors (R7R8 is absent in the v783 join)
+
+
+def photoreceptor_rows(graph) -> torch.Tensor:
+    """Rows of ``graph`` (a Connectome or SubConnectome) that are photoreceptors: VISUAL neurons whose FlyBrain group is
+    R1–R6 or R7–R8. The Kalshi fly's features enter here and travel the optic lobes into the central brain."""
+    if "VISUAL" not in graph.pop_ranges:
+        raise ValueError("this graph has no VISUAL population: the Kalshi fly needs the optic lobes")
+    fg = getattr(graph, "flybrain_group", None); names = list(getattr(graph, "flybrain_group_names", []) or [])
+    lo, hi = graph.pop_ranges["VISUAL"]
+    if fg is None or not names:
+        raise ValueError("the connectome artifact carries no flybrain_group annotation; rebuild it (brain/build.py)")
+    want = [i for i, n in enumerate(names) if n in PHOTORECEPTOR_GROUPS]
+    rows = np.flatnonzero(np.isin(fg[lo:hi], want)) + lo
+    if not len(rows):
+        raise ValueError(f"no photoreceptor rows: VISUAL groups present are {sorted(set(names[int(g)] for g in set(fg[lo:hi].tolist()) if int(g) < len(names)))}")
+    return torch.from_numpy(rows.astype(np.int64))

fly_trader/brain/geometry.py

@@ -25,6 +25,8 @@ EXCLUDE = ("VISUAL",)
 POS_COLS = ["pos_x", "pos_y", "pos_z"]
 SOMA_COLS = ["soma_x", "soma_y", "soma_z"]
 BIN, META = "geometry.bin", "geometry.json"
+FULL_BIN, FULL_META = "geometry_full.bin", "geometry_full.json"         # every neuron: the scene both flies are drawn into (ui/brain3d)
+FLY_EXCLUDES = {"memecoin": EXCLUDE, "kalshi": None}                     # None: brain/connectome.VISUAL_SUB (the memecoin afferents), resolved lazily
 
 
 def keep_mask(pop_ranges: dict, n: int, exclude: tuple[str, ...] = EXCLUDE) -> np.ndarray:
@@ -60,10 +62,11 @@ def read_meta(out_dir: Path) -> dict | None:
 
 
 def build_geometry(out_dir: Path, connectome_path: str | Path | None = None, annotations: str | Path | None = None,
-                   exclude: tuple[str, ...] = EXCLUDE) -> dict:
+                   exclude: tuple[str, ...] = EXCLUDE, names: tuple[str, str] = (BIN, META)) -> dict:
     """Write (once per connectome) and return the geometry metadata. Soma centroid where known, else the neuron's
-    annotation point, else its population's centroid (a handful of neurons); scaled to micrometres and centred."""
-    out_dir = Path(out_dir); jpath, bpath = out_dir / META, out_dir / BIN
+    annotation point, else its population's centroid (a handful of neurons); scaled to micrometres and centred.
+    ``exclude=()`` with ``names=(FULL_BIN, FULL_META)`` is the whole brain (``build_full_geometry``)."""
+    out_dir = Path(out_dir); bpath, jpath = out_dir / names[0], out_dir / names[1]
     path = Path(connectome_path) if connectome_path else current_connectome_path()
     with np.load(path, allow_pickle=False) as z:
         sha = str(z["content_sha256"]); n = int(z["N"]); pop_ranges = {k: tuple(v) for k, v in json.loads(str(z["pop_ranges"])).items()}
@@ -97,3 +100,39 @@ def build_geometry(out_dir: Path, connectome_path: str | Path | None = None, ann
     out_dir.mkdir(parents=True, exist_ok=True)
     _atomic(bpath, np.ascontiguousarray(xyz).tobytes()); _atomic(jpath, json.dumps(meta).encode())
     return meta
+
+
+def fly_index(pop_ranges: dict, n: int, exclude: tuple[str, ...]) -> np.ndarray:
+    """int32 map from a fly's sub-graph index to the full-graph index (the rows ``SubConnectome`` keeps, in order)."""
+    return np.flatnonzero(keep_mask(pop_ranges, n, exclude)).astype(np.int32)
+
+
+def build_full_geometry(out_dir: Path, connectome_path: str | Path | None = None, annotations: str | Path | None = None) -> dict:
+    """The whole brain's geometry plus, per fly, the index map from its sub-graph into it (``index_<fly>.bin``): the
+    scene the console draws both flies into. ``geometry_full.json`` carries ``flies`` = {name: {"exclude", "n", "index"}}."""
+    from .connectome import VISUAL_SUB
+    out_dir = Path(out_dir); jpath = out_dir / FULL_META
+    meta = read_meta_named(out_dir, FULL_META)
+    path = Path(connectome_path) if connectome_path else current_connectome_path()
+    with np.load(path, allow_pickle=False) as z:
+        sha = str(z["content_sha256"]); n = int(z["N"]); pop_ranges = {k: tuple(v) for k, v in json.loads(str(z["pop_ranges"])).items()}
+    if meta and meta.get("connectome_sha256") == sha and meta.get("version") == VERSION and meta.get("flies") and (out_dir / FULL_BIN).exists() \
+            and all((out_dir / f["index"]).exists() for f in meta["flies"].values()):
+        return meta
+    meta = build_geometry(out_dir, path, annotations, exclude=(), names=(FULL_BIN, FULL_META))
+    flies = {}
+    for name, exc in FLY_EXCLUDES.items():
+        exc = tuple(exc) if exc is not None else tuple(VISUAL_SUB)
+        idx = fly_index(pop_ranges, n, exc); fname = f"index_{name}.bin"
+        _atomic(out_dir / fname, np.ascontiguousarray(idx).tobytes())
+        flies[name] = {"exclude": list(exc), "n": int(len(idx)), "index": fname}
+    meta = {**meta, "flies": flies}
+    _atomic(jpath, json.dumps(meta).encode())
+    return meta
+
+
+def read_meta_named(out_dir: Path, name: str) -> dict | None:
+    try:
+        return json.loads((Path(out_dir) / name).read_text())
+    except (FileNotFoundError, ValueError):
+        return None

fly_trader/brain/pathways.py

@@ -13,7 +13,8 @@ from datetime import datetime
 from pathlib import Path
 
 import numpy as np
-import torch
+
+from ..train import model_io
 
 TOP_K = 200
 
@@ -27,7 +28,7 @@ def km_pairs(connectome_path: str | Path) -> tuple[np.ndarray, np.ndarray, int,
 
 def bootstrap_weights(boot_path: str | Path) -> tuple[np.ndarray, np.ndarray, list[str]]:
     """(base weight per pair, learn [S, J], strategy names) from a fly bootstrap checkpoint (``fly_selector.save``)."""
-    d = torch.load(boot_path, map_location="cpu", weights_only=False); sd = d["state_dict"]
+    d = model_io.torch_load(boot_path); sd = d["state_dict"]
     w0 = np.logaddexp(0.0, sd["theta_km"].detach().float().numpy()).astype(np.float32)      # softplus
     n_mbon = int(sd["c_sign"].numel()) if "c_sign" in sd else int(sd["mask"].shape[1])
     learn = sd["learn"].numpy().astype(bool) if "learn" in sd else np.ones((1, n_mbon), dtype=bool)
@@ -37,7 +38,7 @@ def bootstrap_weights(boot_path: str | Path) -> tuple[np.ndarray, np.ndarray, li
 
 def bank_D(path: str | Path) -> tuple[np.ndarray, int | None]:
     """The learned change per pair from ``state.pt`` or a ``snap_*.pt`` (both carry ``bank`` and ``bootstrap_id``)."""
-    s = torch.load(path, map_location="cpu", weights_only=False)
+    s = model_io.torch_load(path)
     D = s["bank"]["D"]; D = D[0] if D.ndim == 2 else D
     bid = s.get("bootstrap_id")
     return D.detach().float().numpy(), (int(bid) if bid is not None else None)

fly_trader/brain/plastic.py

@@ -140,7 +140,7 @@ def row_weights(scores: torch.Tensor, lines: torch.Tensor) -> torch.Tensor:
     even at 10x the losing population outweighed the tradeable rows by more than 100:1 and dragged every prediction
     toward the candidate mean. Learning then made the fly worse than the same network frozen (PF 1.012 vs 1.098). A row
     below the line is not a decision, so it carries no weight."""
-    return torch.where(scores >= lines[:, None], 1.0, 0.0)
+    return torch.where(scores >= (lines if lines.dim() == 2 else lines[:, None]), 1.0, 0.0)      # lines [C] or per row [C, B] (each row's chain)
 
 
 class PlasticBank:
@@ -187,6 +187,12 @@ class PlasticBank:
         m = torch.tanh(u)
         return (y_dn[None] + (((m - self.mu) / self.sigma) * self._read(s, len(y_dn))) @ self.c) / self.scale, m
 
+    def head_for(self, target: torch.Tensor, u0: torch.Tensor, s=None) -> torch.Tensor:
+        """The head output under which the frozen score (D = 0) is exactly ``target`` (net-return units) [B]: with it,
+        ``predict`` is ``target`` plus the plastic change of the MBON readout, and ``update`` learns the error of that
+        sum -- the fly that scores as its teacher plus a learned correction (config.FLY_SCORE = teacher)."""
+        return target * self.scale - (((torch.tanh(u0) - self.mu) / self.sigma) * self._read(s, len(target))) @ self.c
+
     def frozen(self, y_dn: torch.Tensor, u0: torch.Tensor, s=None) -> torch.Tensor:
         """The shadow: the bootstrap fly's score (D = 0) [B]."""
         return (y_dn + (((torch.tanh(u0) - self.mu) / self.sigma) * self._read(s, len(y_dn))) @ self.c) / self.scale

fly_trader/chain/cluster_guard.py

@@ -6,6 +6,9 @@ quotes, signature statuses) never do. Signing is allowed only when ALL of these
 exists), ``LIVE_ENABLED=1``, and ``config.live_prerequisites_missing()`` is empty (capital, position
 cap, gas reserve, bot key and API keys all set). ``config`` attributes are read at call time so a
 test can monkeypatch them.
+
+The one exception is a withdrawal to the operator's own wallet (``assert_withdraw_allowed``,
+chain/withdraw.py): it takes money out of the fly's reach and never trades, so it needs no LIVE_ENABLED.
 """
 from __future__ import annotations
 
@@ -35,6 +38,18 @@ def signing_allowed() -> bool:
         return False
 
 
+def assert_withdraw_allowed(dest: str) -> None:
+    """A withdrawal of the bot's SOL (chain/withdraw.py): mainnet, and only to a wallet listed in FUNDING_ADDRESSES — the
+    list lives in .env and is never typed into the console, so whoever reaches the console can at most send the bot's SOL
+    to its owner. Never on the hosted vault fly: its SOL leaves through the treasury (``fly-trader vault withdraw``)."""
+    if config.VAULT_ENABLED:
+        raise SigningRefused("refusing: the vault fly's SOL leaves through the treasury (fly-trader vault withdraw), not from the trading wallet")
+    if config.SOLANA_CLUSTER != "mainnet-beta":
+        raise SigningRefused(f"refusing to withdraw on cluster {config.SOLANA_CLUSTER!r}: the bot wallet is on mainnet-beta")
+    if dest not in config.FUNDING_ADDRESSES:
+        raise SigningRefused(f"refusing: {dest} is not one of your FUNDING_ADDRESSES (.env)")
+
+
 def assert_vault_signing_allowed() -> None:
     """The vault's own signing (claim payouts, principal withdrawals, token-account closes). On mainnet it is the same
     gate as trading. The devnet rehearsal (``VAULT_CLUSTER=devnet``) may sign with a throwaway key that is not a

fly_trader/chain/jupiter_swap.py

@@ -58,7 +58,7 @@ JUPITER_EXECUTE_RPS = config.JUPITER_RPS  # separate bucket, same rate
 JUPITER_LABELS_URL = "https://api.jup.ag/swap/v2/program-id-to-label"
 JUPITER_LABELS_CACHE = config.DATA_DIR / "jupiter_program_labels.json"
 JUPITER_LABELS_MAX_AGE_S = 86400.0
-DEFAULT_EXCLUDE_ROUTERS = "jupiterz"
+DEFAULT_EXCLUDE_ROUTERS = "jupiterz,dflow,okx"   # Metis only: the signer refuses other routers' programs (signer/policy.py)
 
 
 class JupiterError(RuntimeError):

fly_trader/chain/rpc.py

@@ -224,3 +224,9 @@ class HttpSolanaRpc:
         sig = self.call("sendTransaction", [tx_b64, {"encoding": "base64", "skipPreflight": bool(skip_preflight),
                                                      "preflightCommitment": COMMITMENT, "maxRetries": int(max_retries)}])
         return str(sig)
+
+
+def check_rpc() -> "HttpSolanaRpc | None":
+    """A client for the second, independent provider (``SOLANA_CHECK_RPC_URL``) that money-moving reads must agree with,
+    or None when none is configured."""
+    return HttpSolanaRpc(config.SOLANA_CHECK_RPC_URL) if config.SOLANA_CHECK_RPC_URL else None

fly_trader/chain/withdraw.py

@@ -0,0 +1,129 @@
+"""Withdraw SOL from the bot wallet to one of the operator's own wallets (System → Safety & wallet in the console).
+
+- Only to a wallet listed in FUNDING_ADDRESSES and only on mainnet; never on the hosted vault fly, whose SOL leaves
+  through the treasury (cluster_guard.assert_withdraw_allowed). No LIVE_ENABLED: a withdrawal takes money out of the
+  fly's reach and never trades.
+- What is left is 0 or at least the rent-exempt minimum, and while live positions are open at least the gas reserve
+  (their exits pay fees from it). An empty destination must receive at least the rent-exempt minimum.
+- It holds the live broker's in-flight lock, so a swap's balance delta never contains a withdrawal.
+- The signed transaction is recorded (wallet_events 'withdrawal', status 'signed') before it is broadcast; its outcome is
+  added to that row. A confirmed withdrawal re-bases the live book's kill-switch peak (agent/rails.record_withdrawal):
+  money taken out is not a drawdown.
+"""
+from __future__ import annotations
+
+import base64
+import logging
+from decimal import Decimal
+
+from psycopg.types.json import Jsonb
+from solders.hash import Hash
+from solders.message import MessageV0
+from solders.pubkey import Pubkey
+from solders.system_program import TransferParams, transfer
+from solders.transaction import VersionedTransaction
+
+from .. import config
+from ..agent import rails
+from ..db.apilog import record_event
+from ..db.connection import transaction
+from ..logging_setup import scrub
+from ..markets import SOL
+from .cluster_guard import assert_withdraw_allowed
+from .rpc import RpcError, RpcTransportError
+
+log = logging.getLogger(__name__)
+LAMPORTS = config.LAMPORTS_PER_SOL
+FEE_LAMPORTS = 5_000                 # one signature, no priority fee
+RENT_EXEMPT_MIN = 890_880            # a system account without data: a balance below it (other than 0) is refused
+LOCK_WAIT_S = 120.0                  # a swap holds the broker's lock until it confirms or expires
+
+
+class WithdrawRefused(RuntimeError):
+    """Nothing was signed; the message says why."""
+
+
+def destinations() -> list[str]:
+    """The wallets SOL may go to: the valid Solana addresses in FUNDING_ADDRESSES."""
+    out = []
+    for a in config.FUNDING_ADDRESSES:
+        try:
+            Pubkey.from_string(a)
+            out.append(a)
+        except ValueError:
+            log.warning("FUNDING_ADDRESSES: %r is not a Solana address", a)
+    return out
+
+
+def limits(rpc, me: str, to: str | None = None) -> dict:
+    """Fresh reads: the wallet's lamports, what must stay (the gas reserve while live positions are open), the most that
+    can go out, and the destination's lamports."""
+    balance = int(rpc.get_balance(me))
+    with transaction() as conn:
+        n_open = int(conn.execute("SELECT count(*) AS n FROM positions WHERE book = %s AND status = 'open'", (SOL.live_book,)).fetchone()["n"])
+    keep = max(int(config.GAS_RESERVE_SOL * LAMPORTS), RENT_EXEMPT_MIN) if n_open else 0
+    return {"balance": balance, "fee": FEE_LAMPORTS, "keep": keep, "n_open": n_open, "max": max(0, balance - FEE_LAMPORTS - keep),
+            "to_balance": int(rpc.get_balance(to)) if to else None}
+
+
+def plan(lim: dict, sol: float | None) -> tuple[int, str | None]:
+    """(lamports to send, why not or None) for ``sol`` SOL, or everything withdrawable when ``sol`` is None."""
+    lam = lim["max"] if sol is None else int(Decimal(str(sol)) * LAMPORTS)
+    if lam <= 0:
+        return 0, "nothing to withdraw" if sol is None else "enter an amount"
+    if lam > lim["max"]:
+        return lam, (f"at most {lim['max'] / LAMPORTS:.6f} SOL can go out"
+                     + (f": {lim['keep'] / LAMPORTS:g} SOL stays for the fees of {lim['n_open']} open live position(s)" if lim["keep"] else " after the fee"))
+    left = lim["balance"] - lam - lim["fee"]
+    if 0 < left < RENT_EXEMPT_MIN:
+        return lam, f"Solana refuses to leave {left / LAMPORTS:.6f} SOL behind: leave at least {RENT_EXEMPT_MIN / LAMPORTS:g} SOL or withdraw everything"
+    if lim.get("to_balance") == 0 and lam < RENT_EXEMPT_MIN:
+        return lam, f"an empty wallet must receive at least {RENT_EXEMPT_MIN / LAMPORTS:g} SOL"
+    return lam, None
+
+
+def withdraw(sol: float | None, to: str, rpc=None, keypair=None) -> dict:
+    """Send ``sol`` SOL (None: everything withdrawable) from the bot wallet to ``to``. Returns {status, signature, lamports,
+    to, slot}; status 'confirmed', 'failed_on_chain' (only the fee moved) or 'expired' (nothing moved). Raises
+    WithdrawRefused, cluster_guard.SigningRefused or keys.WalletKeyError when nothing was signed."""
+    from ..execution.broker_live import _INFLIGHT, await_confirmation
+    assert_withdraw_allowed(to)
+    if keypair is None:
+        from .keys import load_keypair
+        keypair = load_keypair()
+    if rpc is None:
+        from .rpc import HttpSolanaRpc
+        rpc = HttpSolanaRpc()
+    me = str(keypair.pubkey())
+    if not _INFLIGHT.acquire(timeout=LOCK_WAIT_S):
+        raise WithdrawRefused("a swap is still in flight: try again in a minute")
+    try:
+        lam, why = plan(limits(rpc, me, to), sol)
+        if why:
+            raise WithdrawRefused(why)
+        bh = rpc.get_latest_blockhash()
+        ix = transfer(TransferParams(from_pubkey=keypair.pubkey(), to_pubkey=Pubkey.from_string(to), lamports=lam))
+        tx = VersionedTransaction(MessageV0.try_compile(keypair.pubkey(), [ix], [], Hash.from_string(bh["blockhash"])), [keypair])
+        sig = str(tx.signatures[0])
+        detail = {"to": to, "lamports": lam, "sol": lam / LAMPORTS, "signature": sig, "last_valid_block_height": bh["last_valid_block_height"], "status": "signed"}
+        with transaction() as conn:                                     # recorded before the network ever sees it
+            eid = conn.execute("INSERT INTO wallet_events (kind, pubkey, detail) VALUES ('withdrawal', %s, %s) RETURNING id", (me, Jsonb(detail))).fetchone()["id"]
+        try:
+            rpc.send_transaction(base64.b64encode(bytes(tx)).decode())
+        except RpcError as e:                                           # refused by the node (preflight): never broadcast
+            with transaction() as conn:
+                conn.execute("UPDATE wallet_events SET detail = detail || %s WHERE id = %s", (Jsonb({"status": "rejected", "error": scrub(str(e))[:300]}), eid))
+            raise WithdrawRefused(f"the network refused it: {scrub(str(e))[:200]}") from None
+        except RpcTransportError as e:                                  # it may have gone out: its status decides
+            log.warning("withdrawal %s: send failed in transport (%s); polling its status", sig, e)
+        status, st = await_confirmation(rpc, sig, bh["last_valid_block_height"])
+        slot = int((st or {}).get("slot") or 0)
+        with transaction() as conn:
+            conn.execute("UPDATE wallet_events SET detail = detail || %s WHERE id = %s", (Jsonb({"status": status, "slot": slot}), eid))
+            if status == "confirmed":
+                rails.record_withdrawal(conn, {"sol": lam / LAMPORTS, "to": to, "signature": sig})
+    finally:
+        _INFLIGHT.release()
+    record_event("info" if status == "confirmed" else "warning", "wallet", f"withdrawal of {lam / LAMPORTS:.6f} SOL to {to}: {status}",
+                 {"signature": sig, "slot": slot})
+    return {"status": status, "signature": sig, "lamports": lam, "to": to, "slot": slot}

fly_trader/config.py

@@ -14,8 +14,10 @@ from dotenv import load_dotenv
 REPO_ROOT = Path(__file__).resolve().parent.parent
 load_dotenv(REPO_ROOT / ".env", override=False)
 
-SECRET_ENV_NAMES = ("HELIUS_API_KEY", "JUPITER_API_KEY", "BOT_PRIVATE_KEY",
-                    "RELAY_SECRET", "TELEGRAM_BOT_TOKEN", "VAULT_BACKUP_HF_TOKEN", "VAULT_SOLANA_RPC_URL")
+SECRET_ENV_NAMES = ("HELIUS_API_KEY", "JUPITER_API_KEY", "BOT_PRIVATE_KEY", "KALSHI_API_KEY_ID", "KALSHI_PRIVATE_KEY_PATH",
+                    "RELAY_SECRET", "TELEGRAM_BOT_TOKEN", "VAULT_BACKUP_HF_TOKEN", "VAULT_SOLANA_RPC_URL", "SIGNER_RPC_URL",
+                    "SOLANA_CHECK_RPC_URL", "HEALTHCHECK_URL", "RH_BOT_PRIVATE_KEY", "RH_RPC_URL_LOGS", "ENVIO_API_TOKEN", "QUICKNODE_API_KEY",
+                    "QUICKNODE_RH_API_KEY", "QUICKNODE_RH_API_URL", "RH_RPC_URL_TX")
 
 
 def utcnow() -> datetime:
@@ -76,9 +78,12 @@ KELLY_FRACTION = env_float("KELLY_FRACTION", 0.25)                 # quarter Kel
 MAX_POSITION_FRACTION = env_float("MAX_POSITION_FRACTION", 0.10)   # of the deployable bankroll (wealth minus the gas reserve)
 MAX_POOL_SHARE = env_float("MAX_POOL_SHARE", 0.02)                 # of the pool's quote reserve (bounds price impact)
 # The training label charges what an exit really costs at the size the book takes. market/features.py prices
-# exit_cost_0p1 for a fixed 0.1 SOL, but positions are Kelly-sized up to MAX_POSITION_FRACTION of the bankroll, and
-# impact = value/(value + reserves) grows with size. 0 = the sizing rule's own ceiling (train/decisions.py).
-LABEL_SIZE_SOL = env_float("LABEL_SIZE_SOL", 0.0)
+# exit_cost_0p1 for a fixed 0.1 SOL, but impact = value/(value + reserves) grows with size. Labels are priced at
+# min(LABEL_SIZE_SOL, MAX_POOL_SHARE of the pool) -- the "label size" -- and no position is ever bigger (agent/sizing.py):
+# every edge the models show was measured at that size. A fixed reference, never a share of the bankroll: derived from
+# CAPITAL_SOL it made the labels, and the sizes, grow with the bankroll, and in the 2026-09-26 replay a 500 SOL book
+# sized past it lost 426 SOL over 60 days where one capped at it made the same +13 SOL as a 5 or 50 SOL book.
+LABEL_SIZE_SOL = env_float("LABEL_SIZE_SOL", 0.5)
 MIN_POSITION_SOL = env_float("MIN_POSITION_SOL", 0.02)             # smaller sizes are skipped
 KILL_SWITCH_DRAWDOWN = env_float("KILL_SWITCH_DRAWDOWN", 0.30)
 KILL_SWITCH_LIQUIDATE = env_bool("KILL_SWITCH_LIQUIDATE", False)   # a tripped kill switch also sells every open live position (agent/fly_live.py)
@@ -103,6 +108,25 @@ LAMPORTS_PER_SOL = 1_000_000_000
 STATS_REFRESH_S = env_float("STATS_REFRESH_S", 600.0)
 
 # ---- connectome (the fly) ----
+# How the fly picks its buy line (train/fly_calibrate.py): total | selector | match. match = its teacher's selectivity:
+# in the 2026-09-26 replays it took 92 trades at +10.1 % (58 % winners, PF 1.92) where total took 1,607 at +2.0 %.
+FLY_CALIB_RULE = env_str("FLY_CALIB_RULE", "match")
+# How the fly sizes a buy (agent/sizing.py): kelly = the selector's own Kelly band for the row (its score, line and sizing
+# table; with FLY_TEACHER_GATE every fly buy is a selector buy, sized exactly as the selector sizes it) | flat =
+# MAX_POSITION_FRACTION of the deployable bankroll on every buy. (Flat was the default while the fly sized from its own
+# calibrated bands, which flipped between Kelly 0.97, 0 and 0.15 on its few trades a week; the selector's bands are fitted
+# on its walk-forward and do not.)
+FLY_SIZING = env_str("FLY_SIZING", "kelly")
+# The fly buys only what its teacher (the deployed selector stack) would buy: the same trigger, line, win filter, gates,
+# dump veto and fail-closed rules. Its own learning (plastic score below its bootstrap score by FLY_LEARNED_VETO) can
+# only drop a teacher trade, never add one (2026-10-08: ungated, the fly bought rows the selector rejected and lost).
+FLY_TEACHER_GATE = env_bool("FLY_TEACHER_GATE", True)
+FLY_LEARNED_VETO = env_float("FLY_LEARNED_VETO", 0.02)
+# How the fly scores a row. teacher: its teacher's own score plus what its mushroom body has learned (the plastic change of
+# its KC->MBON synapses, zero at bootstrap), so it starts exactly as the selector and its learning only corrects the
+# selector. own: its distilled copy of the selector (until 2026-10-11): that copy ranked the selector's top 1 % of
+# candidates only ~0.6-correlated, so its own judgement at the line was half noise (fly #157 and #251 alike).
+FLY_SCORE = env_str("FLY_SCORE", "teacher")
 DEVICE = env_str("DEVICE", "auto")          # auto (CUDA, else MPS, else CPU) | cpu | cuda | cuda:N | mps  — brain/device.py
 NT_SIGN_MODE = env_str("NT_SIGN_MODE", "shiu")  # shiu | flybrain
 CELL_TYPES_SOURCE = env_str("CELL_TYPES_SOURCE", "annotations")  # annotations | flybrain
@@ -158,8 +182,8 @@ def live_prerequisites_missing() -> list[str]:
         missing.append("MAX_POSITION_SOL")
     if GAS_RESERVE_SOL <= 0:
         missing.append("GAS_RESERVE_SOL")
-    if not env_str("BOT_PRIVATE_KEY") and not env_str("BOT_PRIVATE_KEY_FILE"):
-        missing.append("BOT_PRIVATE_KEY")
+    if not SIGNER_SOCKET and not env_str("BOT_PRIVATE_KEY") and not env_str("BOT_PRIVATE_KEY_FILE"):
+        missing.append("BOT_PRIVATE_KEY")                          # the vault server's brain has no key: its signer does
     if not JUPITER_API_KEY:
         missing.append("JUPITER_API_KEY")
     if not HELIUS_API_KEY:
@@ -168,9 +192,11 @@ def live_prerequisites_missing() -> list[str]:
 
 # ---- the $FLY vault (fly_trader/vault, docs/vault/SPEC.md): only the hosted vault fly sets VAULT_ENABLED ----
 VAULT_ENABLED = env_bool("VAULT_ENABLED", False)
+PAYOUT_PRIVATE_KEY_FILE = env_str("PAYOUT_PRIVATE_KEY_FILE")      # the key that pays claims from the treasury (spending limit L2); read by the signer only
+VAULT_BOOK = env_str("VAULT_BOOK", "live")                         # the book the vault shares: live; a paper book (e.g. paper_fly) for a dry run on real decisions without real SOL
 VAULT_CLUSTER = env_str("VAULT_CLUSTER", "mainnet-beta")           # devnet only for the rehearsal (trading off, claims on devnet)
 VAULT_SOLANA_RPC_URL = env_str("VAULT_SOLANA_RPC_URL")             # overrides Helius for the vault's reads/claims (the devnet rehearsal)
-FUNDING_ADDRESSES = env_list("FUNDING_ADDRESSES", [])              # SOL from these is a deposit; from anyone else, profit
+FUNDING_ADDRESSES = env_list("FUNDING_ADDRESSES", [])              # your own Solana wallets: SOL from these is a deposit (vault); the console withdraws only to these
 RH_CHAIN_ID = env_int("RH_CHAIN_ID", 4663)
 RH_RPC_URL = env_str("RH_RPC_URL", "https://rpc.mainnet.chain.robinhood.com")
 VAULT_ADDRESS = env_str("VAULT_ADDRESS")                            # the FlyVault proxy
@@ -180,6 +206,8 @@ VAULT_IMPL_CODEHASHES = env_list("VAULT_IMPL_CODEHASHES", [])       # implementa
 VAULT_PERIOD_S = env_int("VAULT_PERIOD_S", 7 * 86400)               # one settlement period; the rehearsal uses 900
 VAULT_EPOCH = env_int("VAULT_EPOCH", 345_600)                       # boundaries at EPOCH + k*PERIOD; 345600 = Monday 1970-01-05 00:00 UTC
 CLAIM_MIN_LAMPORTS = env_int("CLAIM_MIN_LAMPORTS", 2_000_000)       # 0.002 SOL: above the rent-exempt minimum of a new wallet
+CLAIM_MIN_WEI = env_int("CLAIM_MIN_WEI", 100_000_000_000_000)          # 0.0001 ETH: smaller ETH owed waits for the next claim
+VAULT_RH_GAS_RESERVE_WEI = env_int("VAULT_RH_GAS_RESERVE_WEI", 200_000_000_000_000)   # ETH the settlement never allocates (the RH wallet pays payout gas)
 RELAY_URL = env_str("RELAY_URL")                                    # the site origin; the fly calls {RELAY_URL}/api/...
 RELAY_KEY_ID = env_str("RELAY_KEY_ID", "k1")
 RELAY_SECRET = env_str("RELAY_SECRET")
@@ -193,11 +221,161 @@ TELEGRAM_CHAT_ID = env_str("TELEGRAM_CHAT_ID")
 VAULT_BACKUP_RECIPIENT = env_str("VAULT_BACKUP_RECIPIENT")          # age / ssh-ed25519 public key the backups are encrypted to
 VAULT_BACKUP_BUCKET = env_str("VAULT_BACKUP_BUCKET")                # private HF storage bucket, e.g. bryceweiner/fly-vault-backups
 VAULT_BACKUP_HF_TOKEN = env_str("VAULT_BACKUP_HF_TOKEN")            # scoped to that bucket only
+# custody (docs/vault/SPEC.md "Custody"): a Squads v4 treasury the hot keys draw on only through its spending limits
+VAULT_MULTISIG = env_str("VAULT_MULTISIG")                          # the Squads multisig; the treasury is its vault 0
+VAULT_LIMIT_TRADING = env_str("VAULT_LIMIT_TRADING")                # L1: trading key -> the trading wallet only, per day
+VAULT_LIMIT_PAYOUT = env_str("VAULT_LIMIT_PAYOUT")                  # L2: payout key -> any holder, per week
+TREASURY_FLOAT_SOL = env_float("TREASURY_FLOAT_SOL", 2.0)           # the most the trading wallet keeps idle; the rest goes back
+TOPUP_MIN_SOL = env_float("TOPUP_MIN_SOL", 0.1)                     # smaller refills and returns are skipped
+SIGNER_SOCKET = env_str("SIGNER_SOCKET")                            # the signer container's socket; unset: an in-process signer
+SIGNER_RPC_URL = env_str("SIGNER_RPC_URL")                          # the signer's own RPC (a second provider)
+SOLANA_CHECK_RPC_URL = env_str("SOLANA_CHECK_RPC_URL")              # a second provider money-moving reads must agree with
+TELEGRAM_ADMIN_USER_ID = env_str("TELEGRAM_ADMIN_USER_ID")          # the only Telegram user whose /panic and /status count
+HEALTHCHECK_URL = env_str("HEALTHCHECK_URL")                        # dead-man ping (healthchecks.io) every 5 min
 
 
 def vault_solana_rpc_url() -> str:
     return VAULT_SOLANA_RPC_URL or helius_http_url()
 
+
+def signer_env() -> dict:
+    """What an in-process signer reads (fly_trader/signer; the signer container has its own environment)."""
+    return {k: str(v) for k, v in {"VAULT_MULTISIG": VAULT_MULTISIG, "VAULT_LIMIT_TRADING": VAULT_LIMIT_TRADING,
+                                   "VAULT_LIMIT_PAYOUT": VAULT_LIMIT_PAYOUT,
+                                   "TREASURY_FLOAT_SOL": TREASURY_FLOAT_SOL, "VAULT_BACKUP_RECIPIENT": VAULT_BACKUP_RECIPIENT}.items() if v}
+
+# ---- Robinhood Chain memecoins (fly_trader/rh; Pons launches graduated into Uniswap v4; branch rh-memecoins) ----
+# The same selector and fly as Solana, trained on both chains' rows (a chain input tells them apart); RH books keep their
+# money in native ETH. Amounts on RH rows are ETH (non-ETH-quoted pools converted at the minute's base/ETH price).
+RH_ENABLED = env_bool("RH_ENABLED", True)                           # index RH and paper-trade it
+RH_LIVE_ENABLED = env_bool("RH_LIVE_ENABLED", False)                # sign and send real RH transactions (live_rh)
+RH_TESTNET = env_bool("RH_TESTNET", False)                          # chain 46630 (the rehearsal); the guard refuses a mismatch
+RH_EXPECTED_CHAIN_ID = 46630 if RH_TESTNET else RH_CHAIN_ID
+RH_RPC_URL_LOGS = env_str("RH_RPC_URL_LOGS")                        # optional better endpoint for eth_getLogs / tx lookups (else RH_RPC_URL)
+
+
+def quicknode_rh_url() -> str | None:
+    """The QuickNode RH endpoint: QUICKNODE_RH_API_URL, with QUICKNODE_RH_API_KEY appended when the URL does not carry it."""
+    url, key = env_str("QUICKNODE_RH_API_URL"), env_str("QUICKNODE_RH_API_KEY")
+    if not url:
+        return None
+    return url if not key or key in url else url.rstrip("/") + "/" + key
+
+
+# sending and reading transactions (sends, receipts, nonces, balances, eth_call, gas): every RhRpc() without an explicit URL.
+# Never logs: QuickNode's free Discover plan caps eth_getLogs at 5 blocks (measured 2026-10-09), so logs stay on HyperSync /
+# RH_RPC_URL_LOGS / RH_RPC_URL; its 10M credits a month cover the trading path, not a log tail. QuickNode serves mainnet
+# only while RH_RPC_URL is the default: a run that points RH_RPC_URL elsewhere (anvil, the testnet rehearsal) sends there.
+RH_RPC_URL_TX = env_str("RH_RPC_URL_TX") or (quicknode_rh_url() if env_str("RH_RPC_URL") is None and not RH_TESTNET else None)
+# block headers for timing the index (rh/blocktime.py): PublicNode serves header batches fast but refuses eth_getLogs (403),
+# the official RPC serves logs but rate-limits at ~20 requests/min (measured 2026-09-28) — so each does what it does well
+RH_RPC_URL_BLOCKS = env_str("RH_RPC_URL_BLOCKS", "https://robinhood-rpc.publicnode.com")
+RH_HYPERSYNC_URL = env_str("RH_HYPERSYNC_URL", "https://robinhood.hypersync.xyz")   # log history in bulk when ENVIO_API_TOKEN is set (rh/hypersync.py)
+RH_HYPERSYNC_RPM = env_float("RH_HYPERSYNC_RPM", 40)                 # HyperSync queries per minute (free tier: fair use, refused ~6 % at 60; Starter plan: 100)
+RH_BOT_ADDRESS = env_str("RH_BOT_ADDRESS")                          # the address RH_BOT_PRIVATE_KEY must derive to (a guard, not a secret)
+RH_FUNDING_ADDRESSES = env_list("RH_FUNDING_ADDRESSES", [])         # your own EVM wallets: the console withdraws the RH bot's ETH only to these
+RH_CONFIRMATIONS = env_int("RH_CONFIRMATIONS", 3)                   # blocks before a live receipt or a live log is applied
+RH_START_BLOCK = env_int("RH_START_BLOCK", 0)                       # the indexer's first block (0: the Pons V2 factory's deployment block)
+RH_START_DAY = env_str("RH_START_DAY", "2026-08-04")                # Pons V2 went live: the first RH corpus day
+# Fixed at build time by tools/rh_constants.py (2026-09-28 13:12 UTC: SOL/USD 119.51, ETH/USD 2682.05): the Solana sizes in ETH.
+# Never derived live: they set the size every RH label is priced at (see LABEL_SIZE_SOL).
+RH_ETH_PER_SOL = env_float("RH_ETH_PER_SOL", 0.0445583)                   # K: converts fixed-unit thresholds (eligibility, triggers) for RH rows
+RH_CAPITAL_ETH = env_float("RH_CAPITAL_ETH", 0.222791)                   # the RH paper books' bankroll (5 SOL at build time)
+RH_LABEL_SIZE_ETH = env_float("RH_LABEL_SIZE_ETH", 0.0222791)             # 0.5 SOL at build time: RH labels are priced at it; no RH buy is bigger
+RH_MIN_POSITION_ETH = env_float("RH_MIN_POSITION_ETH", 0.000891166)         # 0.02 SOL at build time
+RH_GAS_RESERVE_ETH = env_float("RH_GAS_RESERVE_ETH", 0.0029)        # 200 round trips at 2x the gas rh-probe measured (356k gas, 0.02 gwei, 2026-09-28)
+RH_MAX_FEE_GWEI = env_float("RH_MAX_FEE_GWEI", 5.0)                  # a transaction never offers more per gas
+RH_TX_FEE_ETH = env_float("RH_TX_FEE_ETH", 7.2e-6)                 # one swap's gas in ETH (rh-probe 2026-09-28: 356k gas × 0.02 gwei); fixed like the SOL fee
+RH_HOOK_FEE = env_float("RH_HOOK_FEE", 0.0099)                      # Pons hook fee + creator tax per side when a minute has none: the median of 52k indexed swaps (1 % of the net = 0.99 % of gross; high-tax launches reach 5.7 %)
+RH_KILL_SWITCH_DRAWDOWN = env_float("RH_KILL_SWITCH_DRAWDOWN", 0.30)
+RH_MIN_SWEEP_ETH = env_float("RH_MIN_SWEEP_ETH", 0.0002)           # base-asset or dead-bag balances worth less are dust
+RH_STREAM_POLL_S = env_float("RH_STREAM_POLL_S", 2.0)
+RH_TRADE_LAG_S = env_float("RH_TRADE_LAG_S", 240.0)                 # an RH minute this old (s) is still traded: its stream lands ~2–3 min late
+RH_MINUTES_KEEP_DAYS = env_int("RH_MINUTES_KEEP_DAYS", 14)
+RH_DIR_NAME = "rh"                                                  # data/corpus/rh/... (the RH corpus beside the Solana one)
+# contracts on Robinhood Chain (mainnet; verified to carry code 2026-09-28)
+PONS_FACTORY = env_str("PONS_FACTORY", "0x7ed598bcef8bd9edd8c97a195c6d13f40801ec7e")
+PONS_ROUTER = env_str("PONS_ROUTER", "0xe33e9e479df8802cb0866d5d05258bec4cf62948")
+PONS_HOOK = env_str("PONS_HOOK", "0xe5e702641ea86f4ae6cc3cdaed2b886f976be044")
+PONS_LOCKER = env_str("PONS_LOCKER", "0x267444d099b10fb5ed7c3cc7b7c767adca574952")
+PONS_GRAD_EXECUTOR = env_str("PONS_GRAD_EXECUTOR", "0xc7819b64a1daecd7ec19856d026cb14efbd89046")
+V4_POOL_MANAGER = env_str("V4_POOL_MANAGER", "0x8366a39cc670b4001a1121b8f6a443a643e40951")
+V4_QUOTER = env_str("V4_QUOTER", "0x8dc178efb8111bb0973dd9d722ebeff267c98f94")
+V4_STATE_VIEW = env_str("V4_STATE_VIEW", "0xf3334192d15450cdd385c8b70e03f9a6bd9e673b")
+UNIVERSAL_ROUTER = env_str("UNIVERSAL_ROUTER", "0x8876789976decbfcbbbe364623c63652db8c0904")
+PERMIT2 = env_str("PERMIT2", "0x000000000022D473030F116dDEE9F6B43aC78BA3")
+V3_FACTORY = env_str("V3_FACTORY", "0x1f7d7550b1b028f7571e69a784071f0205fd2efa")
+V3_QUOTER_V2 = env_str("V3_QUOTER_V2", "0x33e885ed0ec9bf04ecfb19341582aadcb4c8a9e7")
+RH_WETH = env_str("RH_WETH", "0x0bd7d308f8e1639fab988df18a8011f41eacad73")      # SwapRouter02.WETH9()
+RH_USDG = env_str("RH_USDG", "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168")
+KYBER_API = env_str("KYBER_API", "https://aggregator-api.kyberswap.com/robinhood/api/v1")
+KYBER_ROUTER = env_str("KYBER_ROUTER", "0x6131B5fae19EA4f9D964eAc0408E4408b66337b5")  # MetaAggregationRouterV2: the only router a built Kyber tx may call
+KYBER_CLIENT_ID = env_str("KYBER_CLIENT_ID", "fly-trader")
+
+
+def rh_live_prerequisites_missing() -> list[str]:
+    missing = []
+    if not RH_LIVE_ENABLED:
+        missing.append("RH_LIVE_ENABLED=1")
+    if not env_str("RH_BOT_PRIVATE_KEY"):
+        missing.append("RH_BOT_PRIVATE_KEY")
+    if not RH_BOT_ADDRESS:
+        missing.append("RH_BOT_ADDRESS")
+    for name in ("RH_CAPITAL_ETH", "RH_LABEL_SIZE_ETH", "RH_MIN_POSITION_ETH", "RH_ETH_PER_SOL", "RH_GAS_RESERVE_ETH"):
+        if globals()[name] <= 0:
+            missing.append(name)
+    return missing
+
+
+# ---- Kalshi prediction markets (fly_trader/kalshi; the same key names as better_bot, whose client is vendored) ----
+KALSHI_API_KEY_ID = env_str("KALSHI_API_KEY_ID")
+KALSHI_PRIVATE_KEY_PATH = env_str("KALSHI_PRIVATE_KEY_PATH")
+KALSHI_API_BASE_URL = env_str("KALSHI_API_BASE_URL", "https://api.elections.kalshi.com/trade-api/v2")
+KALSHI_WS_URL = env_str("KALSHI_WS_URL", "wss://api.elections.kalshi.com/trade-api/ws/v2")
+KALSHI_SUBACCOUNT = env_int("KALSHI_SUBACCOUNT", 0)                # 0 = the primary account: only a dedicated subaccount may trade live
+KALSHI_FEE_FACTOR = env_float("KALSHI_FEE_FACTOR", 0.07)            # taker fee per contract = factor x multiplier x P(1-P)
+KALSHI_MAKER_FEE_FACTOR = env_float("KALSHI_MAKER_FEE_FACTOR", 0.0175)
+KALSHI_CAPITAL_USD = env_float("KALSHI_CAPITAL_USD", 100.0)         # the cap both Kalshi arms share (paper start; live never sizes above it)
+KALSHI_CASH_FLOOR_USD = env_float("KALSHI_CASH_FLOOR_USD", 5.0)     # the gas reserve's analogue: never spent
+KALSHI_MIN_PAYOUT_CENTS = env_int("KALSHI_MIN_PAYOUT_CENTS", 25)    # a fill whose winning profit is below this is skipped
+KALSHI_LIVE_ENABLED = env_bool("KALSHI_LIVE_ENABLED", False)
+KALSHI_TAKER_LIVE = env_bool("KALSHI_TAKER_LIVE", True)
+KALSHI_MAKER_LIVE = env_bool("KALSHI_MAKER_LIVE", True)
+KALSHI_KILL_SWITCH_DRAWDOWN = env_float("KALSHI_KILL_SWITCH_DRAWDOWN", 0.30)
+KALSHI_MAX_SLATE_FRACTION = env_float("KALSHI_MAX_SLATE_FRACTION", 0.50)   # of the cap deployed at once across every open position
+KALSHI_MAX_DAYS_TO_CLOSE = env_float("KALSHI_MAX_DAYS_TO_CLOSE", 10.0)     # the evidence base (Whelan 2026) covers the last 10 days
+KALSHI_MIN_MINUTES_TO_CLOSE = env_float("KALSHI_MIN_MINUTES_TO_CLOSE", 5.0)
+KALSHI_MAX_SPREAD_CENTS = env_int("KALSHI_MAX_SPREAD_CENTS", 10)
+KALSHI_MIN_OPEN_INTEREST = env_float("KALSHI_MIN_OPEN_INTEREST", 100.0)
+KALSHI_MIN_VOLUME_24H = env_float("KALSHI_MIN_VOLUME_24H", 50.0)
+KALSHI_MAKER_QUIET_MIN = env_float("KALSHI_MAKER_QUIET_MIN", 30.0)         # no resting orders this close to the market's close
+KALSHI_MAKER_TTL_H = env_float("KALSHI_MAKER_TTL_H", 6.0)
+KALSHI_MAKER_MAX_RESTING = env_int("KALSHI_MAKER_MAX_RESTING", 40)
+KALSHI_HISTORY_START = env_str("KALSHI_HISTORY_START", "2025-01-01")
+KALSHI_DATASET_DIR = env_str("KALSHI_DATASET_DIR")                        # jon-becker/prediction-market-analysis checkout (data/kalshi/{markets,trades})
+KALSHI_MINUTES_KEEP_DAYS = env_int("KALSHI_MINUTES_KEEP_DAYS", 7)
+KALSHI_MARKETS_PER_DAY = env_int("KALSHI_MARKETS_PER_DAY", 150)           # the event sample's target: about this many markets per category per day (kalshi/history.sample_rates);
+                                                                           # events are kept by md5(event ticker) < the category's rate, blind to outcome and volume
+KALSHI_DIR = DATA_DIR / "kalshi"
+KALSHI_TRAIN_MAX_ROWS = env_int("KALSHI_TRAIN_MAX_ROWS", 8_000_000)        # training rows per walk-forward block / final fit (uniform random subset)
+KALSHI_FILL_THREADS = env_int("KALSHI_FILL_THREADS", 8)                   # markets filled at once by the history worker, all under the one KALSHI_RPS bucket
+KALSHI_RPS = env_float("KALSHI_RPS", 16.0)                                 # per process; the account's Advanced grant reads 200 tokens/s at 10 per call = 20 calls/s, the feed uses ~3
+
+
+def kalshi_live_prerequisites_missing() -> list[str]:
+    missing = []
+    if not KALSHI_LIVE_ENABLED:
+        missing.append("KALSHI_LIVE_ENABLED=1")
+    if not KALSHI_API_KEY_ID:
+        missing.append("KALSHI_API_KEY_ID")
+    if not KALSHI_PRIVATE_KEY_PATH or not Path(KALSHI_PRIVATE_KEY_PATH).expanduser().exists():
+        missing.append("KALSHI_PRIVATE_KEY_PATH (readable PEM file)")
+    if KALSHI_SUBACCOUNT <= 0:
+        missing.append("KALSHI_SUBACCOUNT (a dedicated subaccount, never the primary)")
+    if KALSHI_CAPITAL_USD <= 0:
+        missing.append("KALSHI_CAPITAL_USD")
+    return missing
+
 # ---- historical corpus (every pump.fun graduation, pulled from the migration wallet + pump.fun's swap-api) ----
 CORPUS_DIR = DATA_DIR / "corpus"
 CORPUS_DAYS = env_int("CORPUS_DAYS", 240)                          # enumerate graduations this far back (must reach before CORPUS_PULL_BEFORE)

fly_trader/db/schema.py

@@ -6,7 +6,9 @@ appending a version-gated block AND bumping SCHEMA_VERSION, or it never runs.
 """
 from __future__ import annotations
 
+import hashlib
 import logging
+import time
 from datetime import datetime, timedelta, timezone
 
 import psycopg
@@ -17,8 +19,15 @@ from .connection import connect, database_name, database_url
 
 log = logging.getLogger(__name__)
 
-SCHEMA_VERSION = 6          # 5: the plastic fly's tables and per-book halts (BASE_DDL); 6: the selector's strategy stack (MIGRATIONS[6])
+SCHEMA_VERSION = 12          # 5: the plastic fly's tables and per-book halts (BASE_DDL); 6: the selector's strategy stack (MIGRATIONS[6]); 7: Kalshi (MIGRATIONS[7]); 8: Kalshi minute extremes
 _LOCK_KEY = 0x666C795F6D6967  # "fly_mig"
+# Applying the DDL takes ACCESS EXCLUSIVE on the tables it touches (Postgres takes it for ALTER TABLE ... ADD COLUMN IF NOT
+# EXISTS even when the column exists) and holds it to the end of the transaction, while live workers write those tables.
+# 2026-10-07: the RH stream's start-up apply deadlocked with the trading engine on positions/decisions and crashed. So:
+# unchanged DDL is not re-run at all (its fingerprint is stored), and a run never waits more than LOCK_TIMEOUT for a
+# lock: it rolls back, releases everything it holds, and retries.
+LOCK_TIMEOUT = "5s"
+APPLY_TRIES = 30
 
 BASE_DDL: list[str] = [
     """CREATE TABLE IF NOT EXISTS schema_version (
@@ -150,11 +159,11 @@ BASE_DDL: list[str] = [
         running_mean real[], running_var real[], n bigint NOT NULL DEFAULT 0,
         updated_at timestamptz NOT NULL DEFAULT now())""",
     """CREATE TABLE IF NOT EXISTS circuit_state (
-        id int PRIMARY KEY CHECK (id = 1), fail_count int NOT NULL DEFAULT 0, last_failure_ts timestamptz,
+        id int PRIMARY KEY, fail_count int NOT NULL DEFAULT 0, last_failure_ts timestamptz,
         tripped boolean NOT NULL DEFAULT false, kill_switch boolean NOT NULL DEFAULT false, kill_reason text,
         peak_wealth double precision, entries_paused boolean NOT NULL DEFAULT false,
         updated_at timestamptz NOT NULL DEFAULT now())""",
-    "INSERT INTO circuit_state (id) VALUES (1) ON CONFLICT DO NOTHING",
+    "INSERT INTO circuit_state (id) VALUES (1) ON CONFLICT DO NOTHING",       # id 2 (the Kalshi rails) is inserted by MIGRATIONS[7], after the CHECK is dropped
     """CREATE TABLE IF NOT EXISTS circuit_events (
         id bigserial PRIMARY KEY, ts timestamptz NOT NULL DEFAULT now(), kind text NOT NULL, detail jsonb)""",
     """CREATE TABLE IF NOT EXISTS notional_ledger (
@@ -223,6 +232,8 @@ BASE_DDL: list[str] = [
         label real, state text NOT NULL DEFAULT 'pending', resolved_at timestamptz, bootstrap_id bigint,
         PRIMARY KEY (ts, mint))""",
     "CREATE INDEX IF NOT EXISTS fly_scored_state_ts_idx ON fly_scored (state, ts)",
+    # would the fly's teacher have traded this row (its final decision)? the match calibration rule's budget (train/fly_calibrate.py)
+    "ALTER TABLE fly_scored ADD COLUMN IF NOT EXISTS teacher_allow boolean",
     """CREATE TABLE IF NOT EXISTS fly_calibrations (
         day date NOT NULL, arm text NOT NULL, line real, sizing jsonb, trades int, total real, mean real, window_days int,
         created_at timestamptz NOT NULL DEFAULT now(), PRIMARY KEY (day, arm))""",
@@ -261,6 +272,105 @@ MIGRATIONS: dict[int, list[str]] = {
         "ALTER TABLE fly_scored ADD COLUMN IF NOT EXISTS hold_min int",
         "ALTER TABLE fly_scored DROP CONSTRAINT IF EXISTS fly_scored_pkey",
         "ALTER TABLE fly_scored ADD PRIMARY KEY (ts, mint, strategy)"],
+    # 7: Kalshi prediction markets (fly_trader/kalshi): the exchange catalogue, live minutes and quotes, the corpus registry,
+    # the four Kalshi books' positions/orders/fills, the visual fly's tables, and a second circuit (id 2) for the Kalshi rails
+    7: ["ALTER TABLE circuit_state DROP CONSTRAINT IF EXISTS circuit_state_id_check",
+        "INSERT INTO circuit_state (id) VALUES (2) ON CONFLICT DO NOTHING",
+        """CREATE TABLE IF NOT EXISTS kalshi_series (
+            ticker text PRIMARY KEY, title text, category text, categories text[], tags text[], frequency text, fee_type text,
+            fee_multiplier double precision, settlement_sources jsonb, updated_at timestamptz NOT NULL DEFAULT now())""",
+        """CREATE TABLE IF NOT EXISTS kalshi_events (
+            event_ticker text PRIMARY KEY, series_ticker text, title text, sub_title text, category text, mutually_exclusive boolean,
+            strike_date timestamptz, strike_period text, collateral_return_type text, exchange_index int, raw jsonb,
+            updated_at timestamptz NOT NULL DEFAULT now())""",
+        "CREATE INDEX IF NOT EXISTS kalshi_events_series_idx ON kalshi_events (series_ticker)",
+        """CREATE TABLE IF NOT EXISTS kalshi_markets (
+            ticker text PRIMARY KEY, event_ticker text, market_type text, title text, yes_sub_title text, no_sub_title text, status text,
+            open_time timestamptz, close_time timestamptz, expected_expiration_time timestamptz, latest_expiration_time timestamptz,
+            settlement_ts timestamptz, result text, settlement_value double precision, strike_type text, floor_strike double precision,
+            cap_strike double precision, exchange_index int, price_level_structure text, is_provisional boolean, can_close_early boolean,
+            created_time timestamptz, source text, raw jsonb, updated_at timestamptz NOT NULL DEFAULT now())""",
+        "CREATE INDEX IF NOT EXISTS kalshi_markets_status_close_idx ON kalshi_markets (status, close_time)",
+        "CREATE INDEX IF NOT EXISTS kalshi_markets_event_idx ON kalshi_markets (event_ticker)",
+        "CREATE INDEX IF NOT EXISTS kalshi_markets_settled_idx ON kalshi_markets (settlement_ts)",
+        # the pump_minutes analogue: one row per (market, UTC minute) from the ticker and trade channels
+        """CREATE TABLE IF NOT EXISTS kalshi_minutes (
+            ticker text NOT NULL, ts timestamptz NOT NULL, yes_bid real, yes_ask real, last real, bid_size real, ask_size real,
+            volume_fp double precision, open_interest_fp double precision, dollar_volume double precision,
+            taker_buy_yes double precision, taker_buy_no double precision, n_trades int, max_trade double precision, block_contracts double precision,
+            PRIMARY KEY (ticker, ts))""",
+        "CREATE INDEX IF NOT EXISTS kalshi_minutes_ts_idx ON kalshi_minutes (ts)",
+        # the live top of book (every ticker message), read by the maker arm and the vendored venue's spread tiers
+        """CREATE TABLE IF NOT EXISTS kalshi_quotes (
+            ticker text PRIMARY KEY, ts timestamptz, yes_bid real, yes_ask real, mid real, bid_size real, ask_size real, last real,
+            updated_at timestamptz NOT NULL DEFAULT now())""",
+        """CREATE OR REPLACE VIEW venue_market_cache AS
+            SELECT 'kalshi'::text AS venue, ticker AS market_id, yes_ask AS yes_ask_cents, mid AS market_prob FROM kalshi_quotes""",
+        # the corpus registry (kalshi/history.py) and the daily feature builds (kalshi/mature.py)
+        """CREATE TABLE IF NOT EXISTS kalshi_corpus (
+            ticker text PRIMARY KEY, status text NOT NULL DEFAULT 'pending', settled_ts timestamptz, result text, open_time timestamptz,
+            close_time timestamptz, candles_1m int, trades int, candle_path text, trade_path text, seeded_from text, last_error text,
+            updated_at timestamptz NOT NULL DEFAULT now())""",
+        "CREATE INDEX IF NOT EXISTS kalshi_corpus_status_idx ON kalshi_corpus (status, settled_ts DESC)",
+        """CREATE TABLE IF NOT EXISTS kalshi_days (
+            day date PRIMARY KEY, markets int, rows int, took_s real, built_at timestamptz NOT NULL DEFAULT now())""",
+        # the four Kalshi books (paper_kalshi_taker, paper_kalshi_maker, live_kalshi_taker, live_kalshi_maker); money in cents
+        """CREATE TABLE IF NOT EXISTS kalshi_positions (
+            id bigserial PRIMARY KEY, book text NOT NULL, ticker text NOT NULL, side text NOT NULL, contracts double precision NOT NULL,
+            cost_cents double precision NOT NULL, fee_cents double precision NOT NULL DEFAULT 0, avg_price_cents double precision,
+            opened_at timestamptz NOT NULL DEFAULT now(), closed_at timestamptz, entry_decision_id bigint, exit_decision_id bigint,
+            order_id text, status text NOT NULL DEFAULT 'open', result text, payout_cents double precision, realized_cents double precision,
+            strategy text, arm text, score real, line real, last_mark_cents real, last_mark_ts timestamptz)""",
+        "CREATE INDEX IF NOT EXISTS kalshi_positions_book_status_idx ON kalshi_positions (book, status)",
+        "CREATE INDEX IF NOT EXISTS kalshi_positions_ticker_idx ON kalshi_positions (ticker)",
+        """CREATE TABLE IF NOT EXISTS kalshi_orders (
+            id bigserial PRIMARY KEY, book text NOT NULL, order_id text, client_order_id text, decision_id bigint, ticker text NOT NULL,
+            side text NOT NULL, action text NOT NULL DEFAULT 'buy', price_cents int NOT NULL, count double precision NOT NULL, tif text NOT NULL,
+            post_only boolean NOT NULL DEFAULT false, expiration_ts timestamptz, status text NOT NULL, fill_count double precision NOT NULL DEFAULT 0,
+            remaining double precision, avg_fill_cents double precision, fee_cents double precision, exchange_index int, subaccount int,
+            fair_cents real, margin_cents real, strategy text, request jsonb, response jsonb, error text,
+            ts timestamptz NOT NULL DEFAULT now(), updated_at timestamptz NOT NULL DEFAULT now())""",
+        "CREATE INDEX IF NOT EXISTS kalshi_orders_book_status_idx ON kalshi_orders (book, status)",
+        "CREATE UNIQUE INDEX IF NOT EXISTS kalshi_orders_order_id_uniq ON kalshi_orders (order_id) WHERE order_id IS NOT NULL",
+        """CREATE TABLE IF NOT EXISTS kalshi_fills (
+            trade_id text PRIMARY KEY, order_id text, book text, ticker text NOT NULL, side text NOT NULL, price_cents double precision NOT NULL,
+            count double precision NOT NULL, fee_cents double precision, is_taker boolean, action text, ts timestamptz NOT NULL,
+            post_position double precision, raw jsonb)""",
+        "CREATE INDEX IF NOT EXISTS kalshi_fills_order_idx ON kalshi_fills (order_id)",
+        # the visual fly (kalshi/fly_session.py): scored (market, minute, side) rows waiting for settlement, calibrations, learning, rollbacks
+        """CREATE TABLE IF NOT EXISTS kalshi_fly_scored (
+            ts timestamptz NOT NULL, ticker text NOT NULL, side text NOT NULL, strategy text NOT NULL, x real[], score real, frozen_score real,
+            line real, frozen_line real, label real, state text NOT NULL DEFAULT 'pending', due_ts timestamptz, resolved_at timestamptz,
+            bootstrap_id bigint, PRIMARY KEY (ts, ticker, side, strategy))""",
+        "CREATE INDEX IF NOT EXISTS kalshi_fly_scored_state_idx ON kalshi_fly_scored (state, due_ts)",
+        """CREATE TABLE IF NOT EXISTS kalshi_fly_calibrations (
+            day date NOT NULL, arm text NOT NULL, line real, sizing jsonb, trades int, total real, mean real, window_days int,
+            created_at timestamptz NOT NULL DEFAULT now(), PRIMARY KEY (day, arm))""",
+        """CREATE TABLE IF NOT EXISTS kalshi_fly_updates (
+            hour timestamptz PRIMARY KEY, n int, mean_delta real, mean_abs_delta real, step real, capped int, drift real, ic real, detail jsonb)""",
+        """CREATE TABLE IF NOT EXISTS kalshi_fly_rollbacks (
+            id bigserial PRIMARY KEY, ts timestamptz NOT NULL DEFAULT now(), reason text, checks jsonb, from_snapshot bigint, to_snapshot bigint)"""],
+    # the minute's lowest YES ask and highest YES bid: whether a resting order would have filled (kalshi/maker.py) — the
+    # candle archive's yes_ask_low / yes_bid_high, which the label rule reads (kalshi/mature.py)
+    8: ["ALTER TABLE kalshi_minutes ADD COLUMN IF NOT EXISTS yes_ask_low real",
+        "ALTER TABLE kalshi_minutes ADD COLUMN IF NOT EXISTS yes_bid_high real"],
+    # 9: a market's lifetime volume on its corpus row, so the corpus can keep the most traded markets per day (kalshi/history.prune_pending)
+    9: ["ALTER TABLE kalshi_corpus ADD COLUMN IF NOT EXISTS volume double precision"],
+    # 10: every settled single market Kalshi listed (the dataset's and the exchange walk's), from which the corpus samples whole
+    # events outcome-blind (kalshi/history.select_corpus)
+    10: ["""CREATE TABLE IF NOT EXISTS kalshi_universe (
+            ticker text PRIMARY KEY, event_ticker text, series_ticker text, title text, open_time timestamptz, close_time timestamptz,
+            settled_ts timestamptz, result text, volume double precision, source text, selected boolean NOT NULL DEFAULT false,
+            updated_at timestamptz NOT NULL DEFAULT now())""",
+         "CREATE INDEX IF NOT EXISTS kalshi_universe_close_idx ON kalshi_universe (close_time)",
+         "CREATE INDEX IF NOT EXISTS kalshi_universe_selected_idx ON kalshi_universe (selected) WHERE selected"],
+    # 11: a market's early-close condition: such a market may close before its listed close when its event happens, so its
+    # realized close carries the outcome; its time anchor is the scheduled expected expiration (kalshi/mature.load_meta)
+    11: ["ALTER TABLE kalshi_markets ADD COLUMN IF NOT EXISTS early_close_condition text"],
+    # 12: the minute's taker sales at their extremes: the lowest YES price a taker sold YES at (bought NO) and the highest a
+    # taker bought YES at (sold NO at 100 − it): a resting bid fills when a taker sells into it (kalshi/decisions.maker_filled)
+    12: ["ALTER TABLE kalshi_minutes ADD COLUMN IF NOT EXISTS yes_sold_low real",
+         "ALTER TABLE kalshi_minutes ADD COLUMN IF NOT EXISTS yes_bought_high real"],
 }
 
 
@@ -278,41 +388,93 @@ def ensure_database(url: str | None = None) -> bool:
         return True
 
 
+def ddl_fingerprint() -> str:
+    """sha256 of every statement apply_schema runs (the ladder, the idempotent vault/RH/ETH DDL) and SCHEMA_VERSION."""
+    from ..rh.schema import RH_DDL
+    from ..vault.eth_schema import ETH_DDL
+    from ..vault.schema import VAULT_DDL
+    h = hashlib.sha256()
+    for stmt in [str(SCHEMA_VERSION), *BASE_DDL, *(x for v in sorted(MIGRATIONS) for x in MIGRATIONS[v]), *VAULT_DDL, *RH_DDL, *ETH_DDL]:
+        h.update(stmt.encode()); h.update(b"\0")
+    return h.hexdigest()
+
+
+def _applied(conn, fp: str) -> int | None:
+    """The schema version when exactly this DDL is already applied (nothing to run), else None."""
+    try:
+        row = conn.execute("SELECT version, ddl_sha256 FROM schema_version WHERE singleton").fetchone()
+    except (psycopg.errors.UndefinedTable, psycopg.errors.UndefinedColumn):
+        conn.rollback()
+        return None
+    conn.commit()
+    if row and row["ddl_sha256"] == fp and int(row["version"]) >= SCHEMA_VERSION:
+        return int(row["version"])
+    return None
+
+
+def _apply_all(conn, fp: str) -> int:
+    with conn.cursor() as cur:
+        cur.execute(f"SET LOCAL lock_timeout = '{LOCK_TIMEOUT}'")
+        for stmt in BASE_DDL:
+            cur.execute(stmt)
+        cur.execute("ALTER TABLE schema_version ADD COLUMN IF NOT EXISTS ddl_sha256 text")
+        cur.execute("SELECT version FROM schema_version WHERE singleton")
+        row = cur.fetchone()
+        current = int(row["version"]) if row else 0
+        for v in sorted(MIGRATIONS):
+            if current < v:
+                for stmt in MIGRATIONS[v]:
+                    cur.execute(stmt)
+                current = v
+        from ..vault.schema import VAULT_DDL     # idempotent, outside the ladder: same DDL on master and distribution
+        for stmt in VAULT_DDL:
+            cur.execute(stmt)
+        from ..rh.schema import RH_DDL           # idempotent, outside the ladder: the Robinhood Chain market (fly_trader/rh)
+        for stmt in RH_DDL:
+            cur.execute(stmt)
+        from ..vault.eth_schema import ETH_DDL    # the vault's ETH pot (Robinhood Chain profits paid in ETH)
+        for stmt in ETH_DDL:
+            cur.execute(stmt)
+        target = max(current, SCHEMA_VERSION)
+        cur.execute(
+            "INSERT INTO schema_version (singleton, version, ddl_sha256) VALUES (true, %s, %s) "
+            "ON CONFLICT (singleton) DO UPDATE SET version = EXCLUDED.version, ddl_sha256 = EXCLUDED.ddl_sha256, updated_at = now()",
+            (target, fp),
+        )
+        return target
+
+
 def apply_schema(url: str | None = None) -> int:
-    """Apply the ladder under an advisory lock. Returns the resulting version."""
+    """Apply the ladder under an advisory lock. Returns the resulting version. A no-op (no table locks) when this exact
+    DDL was applied before; otherwise every lock wait is bounded by LOCK_TIMEOUT and the whole run is retried."""
+    fp = ddl_fingerprint()
     with connect(url) as conn:
-        with conn.cursor() as cur:
-            cur.execute("SELECT pg_advisory_lock(%s)", (_LOCK_KEY,))
-            try:
-                for stmt in BASE_DDL:
-                    cur.execute(stmt)
-                cur.execute("SELECT version FROM schema_version WHERE singleton")
-                row = cur.fetchone()
-                current = int(row["version"]) if row else 0
-                for v in sorted(MIGRATIONS):
-                    if current < v:
-                        for stmt in MIGRATIONS[v]:
-                            cur.execute(stmt)
-                        current = v
-                from ..vault.schema import VAULT_DDL     # idempotent, outside the ladder: same DDL on master and distribution
-                for stmt in VAULT_DDL:
-                    cur.execute(stmt)
-                target = max(current, SCHEMA_VERSION)
-                cur.execute(
-                    "INSERT INTO schema_version (singleton, version) VALUES (true, %s) "
-                    "ON CONFLICT (singleton) DO UPDATE SET version = EXCLUDED.version, updated_at = now()",
-                    (target,),
-                )
-                conn.commit()
-                ensure_partitions(conn)
-                conn.commit()
-                return target
-            except Exception:
-                conn.rollback()
-                raise
-            finally:
-                cur.execute("SELECT pg_advisory_unlock(%s)", (_LOCK_KEY,))
-                conn.commit()
+        conn.execute("SELECT pg_advisory_lock(%s)", (_LOCK_KEY,))
+        conn.commit()                                       # the advisory lock is the session's; no transaction stays open
+        try:
+            target = _applied(conn, fp)
+            if target is None:
+                for attempt in range(APPLY_TRIES):
+                    try:
+                        target = _apply_all(conn, fp)
+                        conn.commit()
+                        break
+                    except (psycopg.errors.LockNotAvailable, psycopg.errors.DeadlockDetected) as e:
+                        conn.rollback()                     # releases every table lock this run took
+                        if attempt == APPLY_TRIES - 1:
+                            raise
+                        wait = min(30.0, 1.0 + attempt)
+                        log.warning("schema: %s while applying the DDL (live workers hold the tables); retrying in %.0f s", type(e).__name__, wait)
+                        time.sleep(wait)
+            ensure_partitions(conn)
+            conn.commit()
+            return target
+        except Exception:
+            conn.rollback()
+            raise
+        finally:
+            conn.execute("SELECT pg_advisory_unlock(%s)", (_LOCK_KEY,))
+            conn.commit()
 
 
 def _partition_name(base: str, start: datetime, granularity: str) -> str:

fly_trader/execution/broker_live.py

@@ -23,7 +23,6 @@ Every write is committed immediately so a crash mid-poll leaves an auditable row
 """
 from __future__ import annotations
 
-import base64
 import logging
 import re
 import threading
@@ -31,20 +30,16 @@ import time
 from dataclasses import dataclass
 
 from psycopg.types.json import Jsonb
-from solders.hash import Hash
-from solders.instruction import AccountMeta, Instruction
-from solders.message import MessageV0
-from solders.pubkey import Pubkey
-from solders.transaction import VersionedTransaction
-
 from .. import config
 from ..chain.balances import tx_deltas, Snapshot, compute_delta, snapshot_balances
 from ..chain.cluster_guard import assert_signing_allowed
 from ..chain.jupiter_swap import JupiterError, JupiterSwap
 from ..db.connection import transaction
-from ..chain.keys import load_keypair
 from ..chain.rpc import TOKEN_2022_PROGRAM_ID, TOKEN_PROGRAM_ID, HttpSolanaRpc
-from ..chain.signing import NotASigner, n_lookup_programs, sign_transaction_b64, static_program_ids, transaction_id
+from ..chain.signing import n_lookup_programs, static_program_ids
+from ..signer import client as signer_client
+from ..signer.client import SignerUnavailable
+from ..signer.policy import EXCLUDE_ROUTERS, PolicyError
 from ..db.apilog import record_event
 from ..db.connection import connect, transaction
 from ..logging_setup import scrub
@@ -110,10 +105,14 @@ def await_confirmation(rpc, signature: str | None, last_valid_block_height: int
 
 
 class LiveBroker:
-    def __init__(self, rpc=None, jup=None, keypair=None):
+    """Swaps through Jupiter; the trading key never enters this process: ``signer`` (fly_trader/signer, the signer
+    container's socket on the vault server) checks and signs each transaction."""
+
+    def __init__(self, rpc=None, jup=None, signer=None):
         self._rpc = rpc
         self._jup = jup
-        self._keypair = keypair
+        self._signer = signer
+        self._pubkey: str | None = None
         self._labels: dict[str, str] | None = None
 
     @property
@@ -129,14 +128,16 @@ class LiveBroker:
         return self._jup
 
     @property
-    def keypair(self):
-        if self._keypair is None:
-            self._keypair = load_keypair()
-        return self._keypair
+    def signer(self):
+        if self._signer is None:
+            self._signer = signer_client.get()
+        return self._signer
 
     @property
     def pubkey(self) -> str:
-        return str(self.keypair.pubkey())
+        if self._pubkey is None:
+            self._pubkey = self.signer.call("pubkeys")["trading"]
+        return self._pubkey
 
     @property
     def labels(self) -> dict[str, str]:
@@ -185,7 +186,7 @@ class LiveBroker:
         taker = self.pubkey
         pre = snapshot_balances(self.rpc, taker)
         request = {"inputMint": input_mint, "outputMint": output_mint, "amount": str(amount_in), "taker": taker,
-                   "slippageBps": slippage_bps, "excludeRouters": "jupiterz"}
+                   "slippageBps": slippage_bps, "excludeRouters": EXCLUDE_ROUTERS}
         base = dict(decision_id=decision_id, book=book, attempt=attempt, side=side, input_mint=input_mint,
                     output_mint=output_mint, amount_in=amount_in, slippage_bps=slippage_bps, request=request)
 
@@ -200,7 +201,7 @@ class LiveBroker:
 
         # 1. order
         try:
-            order = self.jup.order(input_mint, output_mint, amount_in, taker=taker, slippage_bps=slippage_bps)
+            order = self.jup.order(input_mint, output_mint, amount_in, taker=taker, slippage_bps=slippage_bps, exclude_routers=EXCLUDE_ROUTERS)
         except JupiterError as e:
             return fail("order_error", scrub(str(e)))
         err_code = _int_or_none(order.get("errorCode"))
@@ -223,14 +224,18 @@ class LiveBroker:
             conn, **base, order_response=order, request_id=order.get("requestId"), router=order.get("router"),
             fee_bps=_int_or_none(order.get("feeBps")), program_ids=program_ids, lvbh=lvbh, status="ordered")
 
-        # 2. sign (our slot only)
+        # 2. sign: the signer checks the transaction (programs, roles, a simulation of our balances) and signs our slot
         try:
-            signed_b64, _idx = sign_transaction_b64(tx_b64, self.keypair)
-        except (NotASigner, ValueError) as e:
-            return fail("sign_error", f"{type(e).__name__}: {scrub(str(e))}", None, order_id=order_id)
-        if _idx != 0 and not order.get("gasless"):
-            return fail("sign_error", f"our key is signer {_idx}, but a non-gasless order must have the taker as fee payer", None, order_id=order_id)
-        tx_sig = transaction_id(signed_b64)
+            signed = self.signer.call("sign_swap", tx=tx_b64, in_mint=input_mint, out_mint=output_mint, in_amount=amount_in,
+                                      min_out=max(1, int(_int_or_none(order.get("otherAmountThreshold")) or 1)))
+        except PolicyError as e:
+            r = fail("sign_refused", f"{e.code}: {scrub(str(e))}", None, order_id=order_id)
+            if e.code == "policy":
+                record_event("error", "signer", f"swap refused: {e}", {"order_id": order_id, "side": side, "mint": mint})
+            return r[0], e.code == "in_flight"          # a simulation that failed (slippage, stale route): retry with a new order
+        except SignerUnavailable as e:
+            return fail("sign_error", scrub(str(e)), None, order_id=order_id)
+        signed_b64, tx_sig = signed["tx"], signed["signature"]
 
         # 3. execute
         exec_req = {"requestId": order.get("requestId"), "lastValidBlockHeight": lvbh, "signedTransaction": signed_b64}
@@ -419,14 +424,13 @@ def swap_smoke(sol: float) -> None:
     print(f"net lamports delta: {net} ({net / config.LAMPORTS_PER_SOL:.9f} SOL)")
 
 
-def close_empty_atas(rpc=None, keypair=None, url: str | None = None, batch: int = CLOSE_ATA_BATCH, skip_mints: set | None = None) -> dict:
-    """Close every zero-balance token account owned by the bot (rent back to the wallet).
-    SPL Token / Token-2022 CloseAccount = instruction index 9, accounts [account, destination, owner].
-    One v0 transaction per ``batch`` accounts; each is recorded as wallet_events(kind='ata_closed')."""
+def close_empty_atas(rpc=None, signer=None, url: str | None = None, batch: int = CLOSE_ATA_BATCH, skip_mints: set | None = None) -> dict:
+    """Close every zero-balance token account owned by the bot (rent back to the wallet). The signer builds and signs
+    the CloseAccount transactions (it re-checks that each account is ours and empty); each is recorded as
+    wallet_events(kind='ata_closed')."""
     assert_signing_allowed()
-    kp = keypair or load_keypair()
-    owner = kp.pubkey()
-    owner_s = str(owner)
+    signer = signer or signer_client.get()
+    owner_s = signer.call("pubkeys")["trading"]
     rpc = rpc or HttpSolanaRpc()
     skip = set(skip_mints or ())
     empties = [a for a in rpc.get_token_accounts_by_owner(owner_s) if int(a["amount"]) == 0 and a["mint"] not in skip and not a.get("is_native")]
@@ -436,16 +440,17 @@ def close_empty_atas(rpc=None, keypair=None, url: str | None = None, batch: int
     for i in range(0, len(empties), batch):
         chunk = empties[i:i + batch]
         accounts = [a["address"] for a in chunk]
-        ixs = [Instruction(Pubkey.from_string(a["program"]), bytes([9]),
-                           [AccountMeta(Pubkey.from_string(a["address"]), False, True),
-                            AccountMeta(owner, False, True),
-                            AccountMeta(owner, True, False)]) for a in chunk]
-        bh = rpc.get_latest_blockhash()
-        msg = MessageV0.try_compile(owner, ixs, [], Hash.from_string(bh["blockhash"]))
-        tx = VersionedTransaction(msg, [kp])
-        tx_b64 = base64.b64encode(bytes(tx)).decode()
         try:
-            sig = rpc.send_transaction(tx_b64)
+            built = signer.call("close_atas", accounts=accounts)
+        except (PolicyError, SignerUnavailable) as e:
+            result["failed"].append({"accounts": accounts, "error": str(e)})
+            record_event("error", "close_empty_atas", "the signer refused", {"accounts": accounts, "error": str(e)})
+            continue
+        if not built:
+            continue
+        bh = {"last_valid_block_height": built[0]["last_valid_block_height"]}
+        try:
+            sig = rpc.send_transaction(built[0]["tx"])
         except Exception as e:
             err = f"{type(e).__name__}: {scrub(str(e))}"
             result["failed"].append({"accounts": accounts, "error": err})

fly_trader/execution/broker_paper.py

@@ -32,7 +32,9 @@ class PaperFill:
 
 class PaperBroker:
     def __init__(self, book: str):
-        assert book in ("paper_selector", "paper_fly") or book.startswith("replay_"), book   # the race books; replay_* for tests
+        from ..markets import MARKETS
+        paper = {b for m in MARKETS.values() for b in m.paper_books}
+        assert book in paper or book.startswith("replay_"), book   # the race books of every market; replay_* for tests
         self.book = book
 
     def buy(self, conn, *, decision_id: int | None, mint: str, pool: str | None, size_sol: float, price: float | None,
@@ -45,7 +47,7 @@ class PaperBroker:
             return PaperFill(False, None, None, 0.0, 0.0, 0, 0.0, "no price")
         if res_quote_sol is None or res_quote_sol <= 0:
             return PaperFill(False, None, None, price, 0.0, 0, 0.0, "no liquidity estimate")
-        fee_frac = fee_fraction(size_sol, mcap_sol, pool_fee)
+        fee_frac = fee_fraction(size_sol, mcap_sol, pool_fee, program_label)
         impact = impact_fraction(size_sol, res_quote_sol, program_label)
         if impact > config.EXECUTABILITY_MAX_IMPACT:
             # a router would not fill this either; refuse like the live executability check
@@ -74,7 +76,7 @@ class PaperBroker:
         gross = qty_raw / (10 ** decimals) * price
         c = exit_cost_fraction(gross, res_quote_sol, mcap_sol, program_label, pool_fee)
         proceeds = gross * (1.0 - c)
-        fee_sol = gross * fee_fraction(gross, mcap_sol, pool_fee)
+        fee_sol = gross * fee_fraction(gross, mcap_sol, pool_fee, program_label)
         if fraction < 0.999:   # partial: shrink the position, realise the sold part
             realized = ledger.realize_partial(conn, position_id=int(position["id"]), qty_raw=qty_raw,
                                               cost_part=float(position["cost_sol"]) * fraction, proceeds_sol=proceeds,

fly_trader/execution/ledger.py

@@ -20,7 +20,8 @@ log = logging.getLogger(__name__)
 
 def open_positions(conn, book: str) -> list[dict]:
     rows = conn.execute(
-        """SELECT p.*, t.decimals, t.graduated_at, wp.program_label,
+        """SELECT p.*, COALESCE(t.decimals, CASE WHEN p.chain = 'rh' THEN 18 END) AS decimals, t.graduated_at,
+                  COALESCE(wp.program_label, CASE WHEN p.chain = 'rh' THEN 'Pons v4' END) AS program_label,
                   COALESCE(p.hold_s, (d.detail->>'hold_s')::float) AS hold_s, COALESCE(p.strategy, d.detail->>'strategy') AS strategy
            FROM positions p LEFT JOIN tokens t ON t.mint = p.mint
            LEFT JOIN watch_pools wp ON wp.pool = p.pool
@@ -38,7 +39,8 @@ def paper_cash(conn, book: str) -> float:
            FROM positions WHERE book = %s""",
         (book,),
     ).fetchone()
-    return config.CAPITAL_SOL + float(r["realized"]) - float(r["open_cost"])
+    from ..markets import for_book
+    return for_book(book).capital() + float(r["realized"]) - float(r["open_cost"])        # the book's own market's capital (SOL / ETH)
 
 
 def record_fill(conn, *, order_id: int | None, book: str, mint: str, side: str, token_delta: int,
@@ -55,6 +57,11 @@ def record_fill(conn, *, order_id: int | None, book: str, mint: str, side: str,
     return int(row["id"])
 
 
+def _chain_of(book: str) -> str:
+    from ..markets import for_book
+    return for_book(book).chain
+
+
 def open_position(conn, *, book: str, mint: str, pool: str | None, qty_raw: int, cost_sol: float,
                   entry_price: float, decision_id: int | None, fees_sol: float, ts: datetime | None = None,
                   hold_s: float | None = None, strategy: str | None = None) -> int:
@@ -70,9 +77,9 @@ def open_position(conn, *, book: str, mint: str, pool: str | None, qty_raw: int,
         return int(existing["id"])
     row = conn.execute(
         """INSERT INTO positions (book, mint, pool, opened_at, entry_decision_id, qty, cost_sol, entry_price, peak_price,
-             last_mark_price, last_mark_ts, fees_sol, status, last_swap_ts, hold_s, strategy)
-           VALUES (%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,'open',%s,%s,%s) RETURNING id""",
-        (book, mint, pool, ts, decision_id, qty_raw, cost_sol, entry_price, entry_price, entry_price, ts, fees_sol, ts, hold_s, strategy),
+             last_mark_price, last_mark_ts, fees_sol, status, last_swap_ts, hold_s, strategy, chain)
+           VALUES (%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,'open',%s,%s,%s,%s) RETURNING id""",
+        (book, mint, pool, ts, decision_id, qty_raw, cost_sol, entry_price, entry_price, entry_price, ts, fees_sol, ts, hold_s, strategy, _chain_of(book)),
     ).fetchone()
     return int(row["id"])
 
@@ -127,11 +134,11 @@ def mark_positions(conn, book: str, prices: dict[str, float], last_swaps: dict[s
 
 def verify_fills() -> None:
     """Reconcile live positions against on-chain token balances; prints mismatches, writes wallet_events."""
-    from ..chain import keys
     from ..chain.rpc import HttpSolanaRpc
     from ..db.connection import transaction
+    from ..signer import client
     rpc = HttpSolanaRpc()
-    pub = keys.bot_pubkey()
+    pub = client.get().call("pubkeys")["trading"]
     accounts = rpc.get_token_accounts_by_owner(pub)
     onchain = {a["mint"]: int(a["amount"]) for a in accounts}
     with transaction() as conn:

fly_trader/kalshi/__init__.py

@@ -0,0 +1 @@
+"""Kalshi prediction markets: the fly's second trading type, on the optic lobes (see the plan of 2026-09-22)."""

fly_trader/kalshi/client.py

@@ -0,0 +1,342 @@
+"""fly-trader's Kalshi REST client: one persistent, authenticated SDK client on a private event-loop thread, paced under
+the account's rate tier, every call logged to ``api_calls`` (service 'kalshi'; the key never appears).
+
+The vendored better_bot client (``kalshi/vendor/kalshi_client.py``) opens and closes an SDK client per call, which is
+right for a daily batch and wrong for a history pull of tens of thousands of candlestick requests or a trading loop.
+This wrapper keeps the same authentication (``Configuration.api_key_id`` / ``private_key_pem``, RSA-PSS by the SDK) and
+the same ``call_api`` transport, adds the endpoints better_bot never needed — subaccounts, resting (GTC, post-only)
+orders, cancel/amend, the historical tier, series and events — and passes ``KALSHI_SUBACCOUNT`` on every portfolio and
+order call. Prices cross this boundary in cents (ints) and contracts as floats; the exchange's fixed-point dollar
+strings are converted here and nowhere else. Paths and body fields verified against kalshi-python-async 3.10 on
+2026-09-22 (``docs.kalshi.com``): V2 orders are ``POST /portfolio/orders`` with ``yes_price``/``no_price`` in cents.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import threading
+import time
+import uuid
+from urllib.parse import urlencode
+
+from .. import config
+from ..chain.jupiter_tokens import TokenBucket
+from ..db.apilog import record_api_call
+from ..logging_setup import scrub
+
+log = logging.getLogger(__name__)
+RETRIES_429 = 5
+
+
+class KalshiApiError(RuntimeError):
+    def __init__(self, method: str, path: str, status: int | None, body):
+        self.method, self.path, self.status, self.body = method, path, status, body
+        err = (body or {}).get("error") if isinstance(body, dict) else None
+        msg = (err.get("message") if isinstance(err, dict) else None) or (body.get("message") if isinstance(body, dict) else None) or str(body)[:200]
+        super().__init__(f"kalshi {method} {path}: HTTP {status}: {scrub(str(msg))}")
+
+
+def _f(x) -> float | None:
+    try:
+        return float(x) if x not in (None, "") else None
+    except (TypeError, ValueError):
+        return None
+
+
+def cents(dollars) -> int | None:
+    """A fixed-point dollar string ('0.5600') as whole cents; None when absent."""
+    v = _f(dollars)
+    return int(round(v * 100)) if v is not None else None
+
+
+def _summary(params: dict | None, body: dict | None) -> dict | None:
+    out = {}
+    if params:
+        out["params"] = {k: v for k, v in params.items()}
+    if body:
+        out["body"] = {k: v for k, v in body.items() if k not in ("signedTransaction",)}
+    return out or None
+
+
+class KalshiRest:
+    """Synchronous facade over the async SDK client (one per process is enough: MPS and the minute loop are single-threaded)."""
+
+    def __init__(self, rps: float | None = None, subaccount: int | None = None, base_url: str | None = None):
+        self.base = (base_url or config.KALSHI_API_BASE_URL).rstrip("/")
+        self.subaccount = config.KALSHI_SUBACCOUNT if subaccount is None else int(subaccount)
+        self.bucket = TokenBucket(rps or config.KALSHI_RPS)
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._thread: threading.Thread | None = None
+        self._client = None
+        self._lock = threading.Lock()
+
+    # ---- lifecycle ----
+    def _ensure(self):
+        with self._lock:
+            if self._client is not None:
+                return self._client
+            if not config.KALSHI_API_KEY_ID or not config.KALSHI_PRIVATE_KEY_PATH:
+                raise RuntimeError("KALSHI_API_KEY_ID and KALSHI_PRIVATE_KEY_PATH are not set")
+            from kalshi_python_async import Configuration, KalshiClient
+            cfg = Configuration(); cfg.host = self.base
+            cfg.api_key_id = config.KALSHI_API_KEY_ID
+            with open(config.KALSHI_PRIVATE_KEY_PATH) as f:
+                cfg.private_key_pem = f.read()
+            try:
+                import certifi
+                cfg.ssl_ca_cert = certifi.where()
+            except ImportError:
+                pass
+            self._loop = asyncio.new_event_loop()
+            self._thread = threading.Thread(target=self._loop.run_forever, name=f"{threading.current_thread().name}-kalshi-io", daemon=True)
+            self._thread.start()
+            self._client = asyncio.run_coroutine_threadsafe(self._make(cfg, KalshiClient), self._loop).result(30)
+            return self._client
+
+    @staticmethod
+    async def _make(cfg, KalshiClient):
+        return KalshiClient(configuration=cfg)
+
+    def close(self) -> None:
+        with self._lock:
+            if self._client is not None and self._loop is not None:
+                try:
+                    asyncio.run_coroutine_threadsafe(self._client.close(), self._loop).result(10)
+                except Exception:
+                    pass
+                self._loop.call_soon_threadsafe(self._loop.stop)
+            self._client = None
+
+    # ---- transport ----
+    async def _call(self, method: str, url: str, body: dict | None):
+        raw = await self._client.call_api(method, url, body=body, header_params={"Content-Type": "application/json"} if body is not None else None)
+        data = await raw.read()
+        text = data.decode("utf-8", "replace") if isinstance(data, (bytes, bytearray)) else str(data)
+        start = text.find("{")
+        try:
+            parsed = json.loads(text[start:]) if start >= 0 else {}
+        except ValueError:
+            parsed = {"raw": text[:300]}
+        return int(raw.status), parsed
+
+    def request(self, method: str, path: str, params: dict | None = None, body: dict | None = None, timeout: float = 60.0) -> dict:
+        """One paced, logged call. Raises ``KalshiApiError`` on HTTP >= 400 (429 is retried with backoff first)."""
+        client = self._ensure()
+        q = {k: v for k, v in (params or {}).items() if v is not None}
+        url = self.base + path + (("?" + urlencode(q)) if q else "")
+        t0 = time.monotonic(); status = None; err = None; parsed = None
+        try:
+            for attempt in range(RETRIES_429 + 1):
+                self.bucket.acquire()
+                status, parsed = asyncio.run_coroutine_threadsafe(self._call(method, url, body), self._loop).result(timeout)
+                if status == 429 and attempt < RETRIES_429:
+                    time.sleep(1.0 + attempt)
+                    continue
+                break
+            if status >= 400:
+                raise KalshiApiError(method, path, status, parsed)
+            return parsed
+        except KalshiApiError as e:
+            err = str(e); raise
+        except Exception as e:
+            err = f"{type(e).__name__}: {scrub(str(e))}"; raise
+        finally:
+            record_api_call("kalshi", path, method, status, int((time.monotonic() - t0) * 1000), err is None, err,
+                            request=_summary(q, body), response_bytes=len(json.dumps(parsed)) if parsed is not None else None)
+
+    def get(self, path: str, **params) -> dict:
+        return self.request("GET", path, params)
+
+    def pages(self, path: str, key: str, params: dict | None = None, limit: int = 1000, max_pages: int = 10_000, cursor: str | None = None, with_cursor: bool = False):
+        """Cursor walk: yields each page's ``key`` list until the cursor ends or a page is empty. ``cursor`` resumes a walk
+        from a page cursor seen before; ``with_cursor`` yields ``(items, next_cursor)`` so the caller can persist its place."""
+        for _ in range(max_pages):
+            data = self.request("GET", path, {**(params or {}), "limit": limit, "cursor": cursor})
+            items = data.get(key) or []; nxt = data.get("cursor") or None
+            if items:
+                yield (items, nxt) if with_cursor else items
+            cursor = nxt
+            if not cursor or not items:
+                break
+
+    # ---- exchange / catalogue ----
+    def exchange_status(self) -> dict:
+        return self.get("/exchange/status")
+
+    def markets(self, cursor: str | None = None, with_cursor: bool = False, **params):
+        """Pages of market rows (``status`` one of unopened|open|closed|settled|...; ``min_settled_ts`` etc.)."""
+        yield from self.pages("/markets", "markets", params, cursor=cursor, with_cursor=with_cursor)
+
+    def historical_markets(self, cursor: str | None = None, with_cursor: bool = False, **params):
+        yield from self.pages("/historical/markets", "markets", params, cursor=cursor, with_cursor=with_cursor)
+
+    def historical_cutoff(self) -> dict:
+        return self.get("/historical/cutoff")
+
+    def market(self, ticker: str) -> dict:
+        return (self.get(f"/markets/{ticker}") or {}).get("market") or {}
+
+    def historical_market(self, ticker: str) -> dict:
+        return (self.get(f"/historical/markets/{ticker}") or {}).get("market") or {}
+
+    def events(self, **params):
+        """Pages of events (``with_nested_markets=true`` nests their markets); limit is capped at 200 by the exchange."""
+        yield from self.pages("/events", "events", params, limit=200)
+
+    def event(self, event_ticker: str, with_nested_markets: bool = True) -> dict:
+        return self.get(f"/events/{event_ticker}", with_nested_markets=str(with_nested_markets).lower())
+
+    def series_list(self, category: str | None = None, **params) -> list[dict]:
+        return (self.get("/series", category=category, **params) or {}).get("series") or []
+
+    def series(self, series_ticker: str) -> dict:
+        return (self.get(f"/series/{series_ticker}") or {}).get("series") or {}
+
+    def orderbook(self, ticker: str, depth: int | None = None) -> dict:
+        return self.get(f"/markets/{ticker}/orderbook", depth=depth)
+
+    def candlesticks(self, series_ticker: str, ticker: str, start_ts: int, end_ts: int, period_interval: int = 1) -> list[dict]:
+        """1/60/1440-minute candles; a market archived past the historical cutoff answers on the historical path."""
+        params = {"start_ts": int(start_ts), "end_ts": int(end_ts), "period_interval": int(period_interval)}
+        try:
+            return (self.request("GET", f"/series/{series_ticker}/markets/{ticker}/candlesticks", params) or {}).get("candlesticks") or []
+        except KalshiApiError as e:
+            if e.status != 404:
+                raise
+        cs = (self.request("GET", f"/historical/markets/{ticker}/candlesticks", params) or {}).get("candlesticks") or []
+        return [{**c, "_units": "dollars"} for c in cs]          # the archive sends prices as dollar strings under plain keys ("close": "0.0100")
+
+    def trades(self, ticker: str, min_ts: int | None = None, max_ts: int | None = None, historical: bool = False):
+        yield from self.pages("/historical/trades" if historical else "/markets/trades", "trades", {"ticker": ticker, "min_ts": min_ts, "max_ts": max_ts})
+
+    # ---- portfolio (always on this process's subaccount unless told otherwise) ----
+    def _sub(self, subaccount) -> int:
+        return self.subaccount if subaccount is None else int(subaccount)
+
+    def balance(self, subaccount: int | None = None) -> dict:
+        """``{"balance_cents", "portfolio_value_cents"}`` of one subaccount (0 = primary)."""
+        d = self.get("/portfolio/balance", subaccount=self._sub(subaccount))
+        return {"balance_cents": int(d.get("balance") or 0), "portfolio_value_cents": int(d.get("portfolio_value") or 0), "updated_ts": d.get("updated_ts")}
+
+    def subaccount_balances(self) -> list[dict]:
+        return (self.get("/portfolio/subaccounts/balances") or {}).get("subaccount_balances") or []
+
+    def create_subaccount(self) -> int:
+        d = self.request("POST", "/portfolio/subaccounts", body={})
+        return int(d["subaccount_number"])
+
+    def transfer_between_subaccounts(self, from_subaccount: int, to_subaccount: int, amount_cents: int) -> dict:
+        body = {"client_transfer_id": str(uuid.uuid4()), "from_subaccount": int(from_subaccount), "to_subaccount": int(to_subaccount), "amount_cents": int(amount_cents)}
+        return self.request("POST", "/portfolio/subaccounts/transfer", body=body)
+
+    def positions(self, subaccount: int | None = None, **params) -> list[dict]:
+        out = []
+        for page in self.pages("/portfolio/positions", "market_positions", {**params, "subaccount": self._sub(subaccount)}, limit=1000):
+            out.extend(page)
+        return out
+
+    def orders(self, status: str | None = None, subaccount: int | None = None, **params) -> list[dict]:
+        out = []
+        for page in self.pages("/portfolio/orders", "orders", {**params, "status": status, "subaccount": self._sub(subaccount)}, limit=1000):
+            out.extend(page)
+        return out
+
+    def order(self, order_id: str) -> dict:
+        return (self.get(f"/portfolio/orders/{order_id}") or {}).get("order") or {}
+
+    def fills(self, subaccount: int | None = None, **params) -> list[dict]:
+        out = []
+        for page in self.pages("/portfolio/fills", "fills", {**params, "subaccount": self._sub(subaccount)}, limit=1000):
+            out.extend(page)
+        return out
+
+    def settlements(self, subaccount: int | None = None, **params) -> list[dict]:
+        out = []
+        for page in self.pages("/portfolio/settlements", "settlements", {**params, "subaccount": self._sub(subaccount)}, limit=1000):
+            out.extend(page)
+        return out
+
+    # ---- orders ----
+    def create_order(self, ticker: str, side: str, price_cents: int, count: float, *, tif: str = "immediate_or_cancel", post_only: bool = False,
+                     expiration_ts: int | None = None, client_order_id: str | None = None, subaccount: int | None = None, action: str = "buy") -> dict:
+        """Buy (or sell) ``count`` contracts of ``side`` ('yes'|'no') at ``price_cents`` each. ``tif``: immediate_or_cancel |
+        good_till_canceled | fill_or_kill; a resting order is GTC (+ ``post_only`` never crosses, ``expiration_ts`` ends it).
+        Returns the exchange's order object (``order_id``, ``status``, ``fill_count``/``remaining_count`` ...)."""
+        if side not in ("yes", "no"):
+            raise ValueError(f"side must be yes|no, got {side!r}")
+        if not 1 <= int(price_cents) <= 99:
+            raise ValueError(f"price {price_cents} outside 1..99 cents")
+        body = {"ticker": ticker, "client_order_id": client_order_id or f"fly-{uuid.uuid4().hex[:16]}", "side": side, "action": action,
+                "count_fp": f"{float(count):.2f}", ("yes_price" if side == "yes" else "no_price"): int(price_cents), "time_in_force": tif,
+                "post_only": bool(post_only), "self_trade_prevention_type": "maker" if post_only else "taker_at_cross",
+                "subaccount": self._sub(subaccount)}
+        if expiration_ts is not None:
+            body["expiration_ts"] = int(expiration_ts)
+        d = self.request("POST", "/portfolio/orders", body=body)
+        return d.get("order") or d
+
+    def cancel_order(self, order_id: str, subaccount: int | None = None) -> dict:
+        d = self.request("DELETE", f"/portfolio/orders/{order_id}", {"subaccount": self._sub(subaccount)})
+        return d.get("order") or d
+
+    def amend_order(self, order_id: str, ticker: str, side: str, price_cents: int, count: float, client_order_id: str, subaccount: int | None = None,
+                    action: str = "buy") -> dict:
+        body = {"ticker": ticker, "side": side, "action": action, "client_order_id": client_order_id, "updated_client_order_id": f"fly-{uuid.uuid4().hex[:16]}",
+                ("yes_price" if side == "yes" else "no_price"): int(price_cents), "count_fp": f"{float(count):.2f}", "subaccount": self._sub(subaccount)}
+        d = self.request("POST", f"/portfolio/orders/{order_id}/amend", body=body)
+        return d.get("order") or d
+
+
+_REST: KalshiRest | None = None
+_REST_LOCK = threading.Lock()
+
+
+def rest() -> KalshiRest:
+    """The process-wide client (built on first use)."""
+    global _REST
+    with _REST_LOCK:
+        if _REST is None:
+            _REST = KalshiRest()
+        return _REST
+
+
+# ---- operator commands (fly-trader kalshi-subaccount / kalshi-fund / kalshi-status) ----
+def subaccount_create(write_env: bool = True) -> int:
+    """Create the dedicated subaccount and record it in .env (``KALSHI_SUBACCOUNT``); refuses when one is already set."""
+    import re
+    from ..db.apilog import record_event
+    if config.KALSHI_SUBACCOUNT > 0:
+        raise RuntimeError(f"KALSHI_SUBACCOUNT={config.KALSHI_SUBACCOUNT} is already set; refusing to create another")
+    n = KalshiRest(subaccount=0).create_subaccount()
+    if write_env:
+        path = config.REPO_ROOT / ".env"; text = path.read_text() if path.exists() else ""
+        text = re.sub(r"^KALSHI_SUBACCOUNT=.*$", f"KALSHI_SUBACCOUNT={n}", text, flags=re.M) if re.search(r"^KALSHI_SUBACCOUNT=", text, re.M) else text.rstrip("\n") + f"\nKALSHI_SUBACCOUNT={n}\n"
+        path.write_text(text)
+    record_event("info", "kalshi", f"subaccount {n} created", {"subaccount": n})
+    return n
+
+
+def fund(usd: float, to_subaccount: int | None = None) -> dict:
+    """Move ``usd`` from the primary account into the fly's subaccount."""
+    from ..db.apilog import record_event
+    to = config.KALSHI_SUBACCOUNT if to_subaccount is None else int(to_subaccount)
+    if to <= 0:
+        raise RuntimeError("no subaccount: run fly-trader kalshi-subaccount create first")
+    out = KalshiRest(subaccount=0).transfer_between_subaccounts(0, to, int(round(usd * 100)))
+    record_event("info", "kalshi", f"funded subaccount {to} with ${usd:.2f}", {"transfer": out})
+    return out
+
+
+def status() -> dict:
+    r = rest()
+    out = {"exchange": r.exchange_status(), "subaccount": r.subaccount, "balances": r.subaccount_balances(),
+           "prerequisites_missing": config.kalshi_live_prerequisites_missing()}
+    try:
+        out["balance"] = r.balance()
+        out["resting_orders"] = r.orders(status="resting")
+        out["positions"] = [p for p in r.positions() if _f(p.get("position_fp") or p.get("position")) not in (None, 0.0)]
+        out["settlements_24h"] = r.settlements(min_ts=int(time.time()) - 86400)
+    except KalshiApiError as e:
+        out["error"] = str(e)
+    return out

fly_trader/kalshi/data.py

@@ -0,0 +1,164 @@
+"""The Kalshi corpus on disk and the catalogue rows both the history puller and the live stream write.
+
+Layout (``config.KALSHI_DIR``):
+- ``candles/<ticker>.parquet`` — 1-minute candles (``CANDLE_SCHEMA``: period end, YES bid/ask OHLC in cents, trade price
+  OHLC when traded, contracts traded in the period, open interest at its end);
+- ``trades/<ticker>.parquet`` — public trades (``TRADE_SCHEMA``: time, YES price in cents, contracts, the taker's side);
+- ``features/<day>/part.parquet`` — the daily feature rows (kalshi/mature.py).
+Rows of ``kalshi_markets`` / ``kalshi_events`` / ``kalshi_series`` are upserted from the exchange's JSON by
+``upsert_market`` and friends; prices are kept in cents, contracts as floats, times as UTC timestamps.
+"""
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+import pyarrow as pa
+
+from .. import config
+
+CANDLES_DIR = config.KALSHI_DIR / "candles"
+TRADES_DIR = config.KALSHI_DIR / "trades"
+FEATURES_DIR = config.KALSHI_DIR / "features"
+CANDLE_SCHEMA = pa.schema([("end_ts", pa.int64()), ("yes_bid_open", pa.float32()), ("yes_bid_high", pa.float32()), ("yes_bid_low", pa.float32()),
+                           ("yes_bid_close", pa.float32()), ("yes_ask_open", pa.float32()), ("yes_ask_high", pa.float32()), ("yes_ask_low", pa.float32()),
+                           ("yes_ask_close", pa.float32()), ("price_open", pa.float32()), ("price_high", pa.float32()), ("price_low", pa.float32()),
+                           ("price_close", pa.float32()), ("price_mean", pa.float32()), ("volume", pa.float64()), ("open_interest", pa.float64())])
+TRADE_SCHEMA = pa.schema([("ts", pa.timestamp("ms", tz="UTC")), ("yes_price", pa.int16()), ("count", pa.float64()), ("taker_side", pa.string()), ("is_block", pa.bool_())])
+# discovery categories the exchange uses, folded into the fixed set the features one-hot (kalshi/features.CATEGORIES)
+CATEGORY_KEYS = (("politic", "politics"), ("election", "politics"), ("sport", "sports"), ("crypto", "crypto"), ("bitcoin", "crypto"), ("econom", "economics"),
+                 ("financ", "economics"), ("weather", "weather"), ("climate", "weather"), ("entertain", "entertainment"), ("culture", "entertainment"),
+                 ("science", "science"), ("tech", "science"), ("compan", "companies"), ("world", "world"), ("health", "health"))
+
+
+def category_key(raw: str | None) -> str:
+    s = raw.lower() if isinstance(raw, str) else ""              # None or NaN (a market whose series is not catalogued yet): 'other'
+    for needle, key in CATEGORY_KEYS:
+        if needle in s:
+            return key
+    return "other"
+
+
+def ts(v) -> datetime | None:
+    """An ISO-8601 string (or epoch seconds) from the exchange as an aware UTC datetime."""
+    if v in (None, ""):
+        return None
+    if isinstance(v, (int, float)):
+        return datetime.fromtimestamp(float(v), timezone.utc)
+    s = str(v).replace("Z", "+00:00")
+    try:
+        d = datetime.fromisoformat(s)
+    except ValueError:
+        return None
+    return d if d.tzinfo else d.replace(tzinfo=timezone.utc)
+
+
+def _f(v) -> float | None:
+    try:
+        return float(v) if v not in (None, "") else None
+    except (TypeError, ValueError):
+        return None
+
+
+def price_cents(row: dict, key: str) -> float | None:
+    """``<key>_dollars`` (fixed point) or ``<key>`` (cents) of a market/ticker row, as cents."""
+    d = _f(row.get(f"{key}_dollars"))
+    if d is not None:
+        return d * 100.0
+    return _f(row.get(key))
+
+
+def series_ticker_of(ticker: str | None) -> str | None:
+    return str(ticker).split("-")[0] if ticker else None
+
+
+MARKET_COLS = ("ticker", "event_ticker", "market_type", "title", "yes_sub_title", "no_sub_title", "status", "open_time", "close_time",
+               "expected_expiration_time", "latest_expiration_time", "settlement_ts", "result", "settlement_value", "strike_type", "floor_strike",
+               "cap_strike", "exchange_index", "price_level_structure", "is_provisional", "can_close_early", "early_close_condition", "created_time", "source", "raw")
+
+
+def market_row(m: dict, source: str) -> dict:
+    return {"ticker": m.get("ticker"), "event_ticker": m.get("event_ticker"), "market_type": m.get("market_type"), "title": m.get("title"),
+            "yes_sub_title": m.get("yes_sub_title"), "no_sub_title": m.get("no_sub_title"), "status": m.get("status"), "open_time": ts(m.get("open_time")),
+            "close_time": ts(m.get("close_time")), "expected_expiration_time": ts(m.get("expected_expiration_time")),
+            "latest_expiration_time": ts(m.get("latest_expiration_time")), "settlement_ts": ts(m.get("settlement_ts") or m.get("settled_time")),
+            "result": m.get("result") or None, "settlement_value": _f(m.get("settlement_value_dollars")) if m.get("settlement_value_dollars") is not None else _f(m.get("settlement_value")),
+            "strike_type": m.get("strike_type"), "floor_strike": _f(m.get("floor_strike")), "cap_strike": _f(m.get("cap_strike")),
+            "exchange_index": m.get("exchange_index"), "price_level_structure": m.get("price_level_structure"), "is_provisional": m.get("is_provisional"),
+            "can_close_early": m.get("can_close_early"), "early_close_condition": m.get("early_close_condition") or None, "created_time": ts(m.get("created_time")), "source": source,
+            "raw": json.dumps({k: v for k, v in m.items() if k not in ("rules_primary", "rules_secondary")}, default=str)}
+
+
+def upsert_markets(conn, markets: list[dict], source: str) -> int:
+    rows = [market_row(m, source) for m in markets if m.get("ticker")]
+    if not rows:
+        return 0
+    cols = MARKET_COLS
+    sets = ", ".join(f"{c} = COALESCE(EXCLUDED.{c}, kalshi_markets.{c})" for c in cols if c not in ("ticker", "source", "raw"))
+    conn.cursor().executemany(
+        f"INSERT INTO kalshi_markets ({', '.join(cols)}) VALUES ({', '.join(['%s'] * len(cols))}) ON CONFLICT (ticker) DO UPDATE SET {sets}, "
+        "source = EXCLUDED.source, raw = EXCLUDED.raw, updated_at = now()", [tuple(r[c] for c in cols) for r in rows])
+    return len(rows)
+
+
+def upsert_event(conn, e: dict) -> None:
+    if not e.get("event_ticker"):
+        return
+    conn.execute("INSERT INTO kalshi_events (event_ticker, series_ticker, title, sub_title, category, mutually_exclusive, strike_date, strike_period, "
+                 "collateral_return_type, exchange_index, raw) VALUES (%s,%s,%s,%s,%s,%s,%s,%s,%s,%s,%s) ON CONFLICT (event_ticker) DO UPDATE SET "
+                 "series_ticker = COALESCE(EXCLUDED.series_ticker, kalshi_events.series_ticker), title = COALESCE(EXCLUDED.title, kalshi_events.title), "
+                 "sub_title = COALESCE(EXCLUDED.sub_title, kalshi_events.sub_title), category = COALESCE(EXCLUDED.category, kalshi_events.category), "
+                 "mutually_exclusive = COALESCE(EXCLUDED.mutually_exclusive, kalshi_events.mutually_exclusive), strike_date = COALESCE(EXCLUDED.strike_date, kalshi_events.strike_date), "
+                 "strike_period = COALESCE(EXCLUDED.strike_period, kalshi_events.strike_period), collateral_return_type = COALESCE(EXCLUDED.collateral_return_type, kalshi_events.collateral_return_type), "
+                 "exchange_index = COALESCE(EXCLUDED.exchange_index, kalshi_events.exchange_index), raw = EXCLUDED.raw, updated_at = now()",
+                 (e["event_ticker"], e.get("series_ticker") or series_ticker_of(e["event_ticker"]), e.get("title"), e.get("sub_title"), e.get("category"),
+                  e.get("mutually_exclusive"), ts(e.get("strike_date")), e.get("strike_period"), e.get("collateral_return_type"), e.get("exchange_index"),
+                  json.dumps({k: v for k, v in e.items() if k != "markets"}, default=str)))
+
+
+def upsert_series(conn, s: dict) -> None:
+    if not s.get("ticker"):
+        return
+    conn.execute("INSERT INTO kalshi_series (ticker, title, category, categories, tags, frequency, fee_type, fee_multiplier, settlement_sources) "
+                 "VALUES (%s,%s,%s,%s,%s,%s,%s,%s,%s) ON CONFLICT (ticker) DO UPDATE SET title = EXCLUDED.title, category = EXCLUDED.category, "
+                 "categories = EXCLUDED.categories, tags = EXCLUDED.tags, frequency = EXCLUDED.frequency, fee_type = EXCLUDED.fee_type, "
+                 "fee_multiplier = EXCLUDED.fee_multiplier, settlement_sources = EXCLUDED.settlement_sources, updated_at = now()",
+                 (s["ticker"], s.get("title"), s.get("category"), list(s.get("categories") or []), list(s.get("tags") or []), s.get("frequency"),
+                  s.get("fee_type"), _f(s.get("fee_multiplier")), json.dumps(s.get("settlement_sources") or [], default=str)))
+
+
+def candle_rows(candles: list[dict]) -> list[dict]:
+    """Exchange candlesticks → ``CANDLE_SCHEMA`` rows (cents; missing trade prices stay NaN)."""
+    out = []
+    for c in candles:
+        yb, ya, pr = c.get("yes_bid") or {}, c.get("yes_ask") or {}, c.get("price") or {}
+        plain = 100.0 if c.get("_units") == "dollars" else 1.0           # live: <k>_dollars or <k> in cents; archive: <k> in dollars
+
+        def q(d, k, plain=plain):
+            v = _f(d.get(f"{k}_dollars"))
+            return v * 100.0 if v is not None else (_f(d.get(k)) * plain if d.get(k) is not None and _f(d.get(k)) is not None else float("nan"))
+        out.append({"end_ts": int(c.get("end_period_ts") or 0),
+                    "yes_bid_open": q(yb, "open"), "yes_bid_high": q(yb, "high"), "yes_bid_low": q(yb, "low"), "yes_bid_close": q(yb, "close"),
+                    "yes_ask_open": q(ya, "open"), "yes_ask_high": q(ya, "high"), "yes_ask_low": q(ya, "low"), "yes_ask_close": q(ya, "close"),
+                    "price_open": q(pr, "open"), "price_high": q(pr, "high"), "price_low": q(pr, "low"), "price_close": q(pr, "close"), "price_mean": q(pr, "mean"),
+                    "volume": _f(c.get("volume_fp") or c.get("volume")) or 0.0, "open_interest": _f(c.get("open_interest_fp") or c.get("open_interest")) or 0.0})
+    return out
+
+
+def trade_rows(trades: list[dict]) -> list[dict]:
+    out = []
+    for t in trades:
+        p = price_cents(t, "yes_price")
+        if p is None:
+            continue
+        out.append({"ts": ts(t.get("created_time")), "yes_price": int(round(p)), "count": _f(t.get("count_fp") or t.get("count")) or 0.0,
+                    "taker_side": t.get("taker_outcome_side") or t.get("taker_side") or "", "is_block": bool(t.get("is_block_trade"))})
+    return [r for r in out if r["ts"] is not None]
+
+
+def write_parquet(rows: list[dict], schema: pa.Schema, path: Path) -> None:
+    import pyarrow.parquet as pq
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_name(path.name + ".tmp")
+    pq.write_table(pa.Table.from_pylist(rows, schema=schema), tmp, compression="zstd"); tmp.replace(path)

fly_trader/kalshi/decisions.py

@@ -0,0 +1,149 @@
+"""Decision points for the Kalshi selector and fly: one row per (market, minute, side) of the feature parts
+(kalshi/mature.py), with the settlement labels both arms trade on.
+
+Reuses ``train.decisions.DecisionSet`` unchanged: ``mint`` = ``"<ticker>:<side>"``, ``ts`` = minute start, ``day`` =
+the minute's date, and — because every position is held to settlement — a per-row hold ``hold_s`` = settlement − ts
+(``taken_idx`` / ``evaluate`` already take per-row holds). Labels, per dollar staked at the fee-inclusive price:
+- ``fwd_pess`` (taker): ``(100·y − eff) / eff`` with ``eff = effective_price_cents(side ask)`` and ``y`` the settlement
+  of the side (1 when it paid);
+- ``fwd`` (reference): the same at the side's mid;
+- ``fwd_h["maker"]``: the maker arm's order (kalshi/maker.py): a bid resting one tick above the side's bid, never at or
+  through its ask (``maker_rest``), for the order's lifetime (``KALSHI_MAKER_TTL_H``, ending ``KALSHI_MAKER_QUIET_MIN``
+  before close); filled (``maker_filled``) when the side's ask came down to it — every bid at that price, ours included,
+  was taken — or a taker sold the side below it, or at it when our bid set a new best price and so stood first in its
+  queue; the maker fee where the series charges one; NaN when unfilled. Until feature version 5 the order rested one tick
+  inside the ask, for the market's whole life, and filled only when the ask later fell strictly below it: it paid away
+  the spread makers earn and counted only the fills that came with an adverse move (2026-10-09).
+Eligibility (the live engine applies the same, ``kalshi/engine.KalshiMinuteEngine.eligible``): both quotes present,
+spread ≤ KALSHI_MAX_SPREAD_CENTS, side ask in 1..99, open interest ≥ KALSHI_MIN_OPEN_INTEREST, 24 h volume ≥
+KALSHI_MIN_VOLUME_24H, settlement yes/no, time to close inside the entry window.
+"""
+from __future__ import annotations
+
+import glob
+import math
+from datetime import date
+
+import numpy as np
+import pandas as pd
+import pyarrow.parquet as pq
+
+from .. import config
+from ..train.corpus_features import _epoch_s
+from ..train.decisions import DecisionSet
+from . import data as D
+from .features import K_COLS, KALSHI_FEATURE_VERSION, KIDX
+from .mature import part_current
+from .vendor import kalshi_client as kc
+
+X_COLS = list(K_COLS)
+
+
+def maker_rest(side_bid, side_ask) -> np.ndarray:
+    """The maker arm's bid (cents): one tick above the side's best bid, at most one tick below its ask (``post_only``
+    never crosses); with a one-tick spread it joins the bid's queue."""
+    return np.clip(np.minimum(np.round(np.asarray(side_bid, dtype=float)) + 1.0, np.round(np.asarray(side_ask, dtype=float)) - 1.0), 1.0, 99.0)
+
+
+def maker_filled(rest, side_bid, ask_low, sold_low) -> np.ndarray:
+    """Would a bid at ``rest``, posted when the side's bid was ``side_bid``, have filled, given the lowest ask the side
+    showed (``ask_low``) and the lowest price a taker sold the side at (``sold_low``) while it rested (NaN: none). The ask
+    reaching ``rest`` means every bid at ``rest`` was taken; a taker sale below ``rest`` means the same; a sale at
+    ``rest`` reaches us only when we were first there — our bid improved on the best bid, so nobody was ahead of us."""
+    rest = np.asarray(rest, dtype=float); ask_low = np.asarray(ask_low, dtype=float); sold_low = np.asarray(sold_low, dtype=float)
+    first = rest > np.round(np.asarray(side_bid, dtype=float))
+    with np.errstate(invalid="ignore"):
+        return (np.isfinite(ask_low) & (ask_low <= rest)) | (np.isfinite(sold_low) & ((sold_low < rest) | (first & (sold_low <= rest))))
+
+
+def maker_fee_cents(price_cents, fee_mult, charged) -> np.ndarray:
+    """Per-contract maker fee in cents where the series charges makers (KALSHI_MAKER_FEE_FACTOR·mult·p(1−p)·100), else 0."""
+    p = np.asarray(price_cents, dtype=float) / 100.0
+    return np.where(np.asarray(charged, dtype=float) > 0, config.KALSHI_MAKER_FEE_FACTOR * np.asarray(fee_mult, dtype=float) * p * (1 - p) * 100.0, 0.0)
+
+
+def eligible_mask(X: np.ndarray, cols: list[str], to_close_s: np.ndarray) -> np.ndarray:
+    c = {n: i for i, n in enumerate(cols)}
+    return ((X[:, c["spread"]] <= config.KALSHI_MAX_SPREAD_CENTS) & (X[:, c["side_ask"]] >= 1.0) & (X[:, c["side_ask"]] <= 99.0)
+            & (X[:, c["side_bid"]] >= 1.0) & (np.expm1(X[:, c["log_oi"]]) >= config.KALSHI_MIN_OPEN_INTEREST)
+            & (np.expm1(X[:, c["log_vol_24h"]]) >= config.KALSHI_MIN_VOLUME_24H)
+            & (to_close_s >= config.KALSHI_MIN_MINUTES_TO_CLOSE * 60.0) & (to_close_s <= config.KALSHI_MAX_DAYS_TO_CLOSE * 86400.0))
+
+
+def build(days: int | None = None, feature_dir=None, label_thr: float = 0.0) -> DecisionSet:
+    """The decision rows of the most recent ``days`` feature days (all of them when None). Each part is reduced to its
+    eligible rows as it is read — float32 inputs, labels, integer market ids — so the whole corpus (tens of millions of
+    rows) fits: reading every part into one pandas frame with its string columns peaked near three times the final size."""
+    root = feature_dir or D.FEATURES_DIR
+    dirs = sorted(glob.glob(str(root / "*")))
+    if days:
+        dirs = dirs[-days:]
+    files = [f for d in dirs for f in sorted(glob.glob(str(root / d.split("/")[-1] / "part-*.parquet")))]
+    if not files:
+        raise RuntimeError("no Kalshi feature parts; run kalshi-build")
+    stale = [f for f in files if not part_current(f)]
+    if stale:
+        raise RuntimeError(f"{len(stale)} Kalshi feature part(s) from another version (e.g. {stale[0]}); run kalshi-build")
+    need = list(dict.fromkeys([*X_COLS, "ticker", "side", "ts", "category", "close_ts", "end_ts", "settled_ts", "result", "fill_ask_low", "fill_sold_low"]))
+    tick_id: dict[str, int] = {}; tick_names: list[str] = []; cat_id: dict[str, int] = {}; cat_names: list[str] = []
+    acc: dict[str, list] = {k: [] for k in ("X", "ts", "settled", "y", "fwd", "fwd_pess", "maker", "tick", "side", "cat", "ord")}
+    for f in files:
+        t = pq.read_table(f, columns=need)
+        if not t.num_rows:
+            continue
+        res = np.asarray(t["result"].to_numpy(zero_copy_only=False), dtype=object); side = np.asarray(t["side"].to_numpy(zero_copy_only=False), dtype=object)
+        ok = (res == "yes") | (res == "no")
+        if not ok.any():
+            continue
+        X = np.column_stack([t[c].to_numpy(zero_copy_only=False).astype(np.float32) for c in X_COLS])
+        X[~np.isfinite(X)] = 0.0
+        ts = t["ts"].cast("int64").to_numpy().astype(np.float64) / 1000.0
+        close = t["close_ts"].to_numpy(zero_copy_only=False).astype(np.float64); st_ = t["settled_ts"].to_numpy(zero_copy_only=False).astype(np.float64)
+        end = t["end_ts"].to_numpy(zero_copy_only=False).astype(np.float64)
+        settled = np.where(np.isfinite(st_), st_, end); to_close = close - ts     # window on the anchor; a label's timing on the realized end
+        y = (res == side).astype(np.float64)
+        eff = X[:, KIDX["eff_price"]].astype(np.float64); mid = np.clip(X[:, KIDX["side_mid"]].astype(np.float64), 1.0, 99.0)
+        fwd_pess = (100.0 * y - eff) / eff; fwd = (100.0 * y - mid) / mid
+        rest = maker_rest(X[:, KIDX["side_bid"]], X[:, KIDX["side_ask"]])
+        filled = maker_filled(rest, X[:, KIDX["side_bid"]], t["fill_ask_low"].to_numpy(zero_copy_only=False).astype(np.float64),
+                              t["fill_sold_low"].to_numpy(zero_copy_only=False).astype(np.float64))
+        m_eff = rest + maker_fee_cents(rest, X[:, KIDX["fee_mult"]], X[:, KIDX["maker_fee"]])
+        maker = np.where(filled, (100.0 * y - m_eff) / m_eff, np.nan)
+        elig = ok & eligible_mask(X, X_COLS, to_close) & np.isfinite(fwd_pess) & (settled > ts)
+        if not elig.any():
+            continue
+        tk = t["ticker"].to_numpy(zero_copy_only=False)[elig]; cats = t["category"].to_numpy(zero_copy_only=False)[elig]
+        acc["X"].append(X[elig]); acc["ts"].append(ts[elig]); acc["settled"].append(settled[elig]); acc["y"].append(y[elig])
+        acc["fwd"].append(fwd[elig].astype(np.float32)); acc["fwd_pess"].append(fwd_pess[elig].astype(np.float32)); acc["maker"].append(maker[elig].astype(np.float32))
+        acc["tick"].append(np.fromiter((tick_id.setdefault(x, len(tick_id)) for x in tk), dtype=np.int64, count=len(tk)))
+        acc["side"].append((side[elig] == "yes").astype(np.int8))
+        acc["cat"].append(np.fromiter((cat_id.setdefault(x, len(cat_id)) for x in cats), dtype=np.int16, count=len(cats)))
+        acc["ord"].append((np.floor(ts[elig] / 86400.0) + 719163).astype(np.int32))          # date.fromordinal(719163) is 1970-01-01
+        del X, t
+    if not acc["X"]:
+        raise RuntimeError("no eligible Kalshi decision rows")
+    cat = lambda k: np.concatenate(acc.pop(k))
+    X = cat("X"); ts = cat("ts"); settled = cat("settled"); y = cat("y"); fwd = cat("fwd"); fwd_pess = cat("fwd_pess"); maker = cat("maker")
+    tick = cat("tick"); side = cat("side"); catc = cat("cat"); ords = cat("ord")
+    tick_names = np.array([None] * len(tick_id), dtype=object)
+    for k_, v in tick_id.items():
+        tick_names[v] = k_
+    cat_names = np.array([None] * len(cat_id), dtype=object)
+    for k_, v in cat_id.items():
+        cat_names[v] = k_
+    day_objs = {o: date.fromordinal(int(o)) for o in np.unique(ords)}
+    day_arr = np.array([day_objs[o] for o in sorted(day_objs)], dtype=object)[np.searchsorted(np.array(sorted(day_objs)), ords)]
+    ds = DecisionSet(X=X, y=(fwd_pess > label_thr).astype(np.int8), fwd=fwd, fwd_pess=fwd_pess, day=day_arr, ts=ts, mint=tick * 2 + side.astype(np.int64),
+                     cols=list(X_COLS), horizon_s=float(np.median(settled - ts)), fwd_h={"maker": maker})
+    ds._day_ord = ords
+    ds.train_max_rows = int(config.KALSHI_TRAIN_MAX_ROWS) or None   # training rows per fit: a random subset (train/strategies.cap_rows)
+    ds.hold_s = (settled - ts).astype(np.float64)                     # per-row: every position is held to its own settlement
+    ds.data_version = f"kalshi-features-{KALSHI_FEATURE_VERSION}"     # in the walk-forward cache key: another feature version never reuses a fit
+    ds.label_ts = (settled + 60.0).astype(np.float64)                 # when the outcome is known: training for a period may use only rows known before it
+    ds.outcome = y.astype(np.float32)
+    ds.side = np.array(["no", "yes"], dtype=object)[side]; ds.ticker = tick_names[tick]; ds.category = cat_names[catc]
+    # the stack's bars (train/strategies.Score): a positive mean with a weekly sign test, not the memecoin PF ≥ 1.3 and 65 %
+    # winners — a contract bought at 95c that pays 5c when it wins needs a 1.3 % edge for PF 1.3, about all the edge the
+    # literature finds left on Kalshi, and its win rate is set by its price (operator decision, 2026-10-09)
+    ds.gate = "significance"
+    return ds