@oracle-agent/oracle 0.24.1 → 0.24.3

package/dist/assets/skills/self-custodial-onchain-execution/SKILL.md

@@ -0,0 +1,1284 @@
+---
+name: self-custodial-onchain-execution
+description: Build public token and NFT scanners that prepare wallet-signed swaps or mints without backend custody, with verified routes, simulations, honest risk coverage, and fail-closed transaction gates.
+---
+
+> Oracle native tools: `oracle_cli` (read/prepare), `vault_status`, `signer_status`, `signer_execute` (needs human confirmationNonce), `skill_load`. No generic shell. No fleet SSH.
+
+
+# Self-custodial on-chain execution
+
+Use when a scanner, launchpad, or trading dashboard moves from read-only/paper mode to transactions signed by the user's Rabby or EVM wallet.
+
+## Authority model
+
+A wallet signature proves address control, not operator/admin authority.
+
+- Public wallet session: personalized data, paper records, and transactions that the same wallet must sign.
+- Token-gated session: public scope plus an on-chain ownership check.
+- Operator scope: explicit server allowlist or enrollment.
+- Admin scope: separate credentials for backend signers, portfolios, policy changes, and kill switches.
+
+An open preview may accept any signed wallet only when every money-moving action remains self-custodial and backend live submission is absent from the build.
+
+## Arming posture: key present = armed, user asks = it runs
+
+**DEMI correction — do not gate each capability behind its own env flag.**
+
+```
+Key present      -> capability is ARMED
+User asks for it -> it RUNS
+Autonomous mode  -> the ONLY separate opt-in
+```
+
+Supplying a signing key **is** the authorization decision. Making someone who
+already handed over a key hunt down a second and third `ORACLE_X_ENABLED=1` to
+buy an NFT is friction, not security — and it teaches people to set every flag,
+which is strictly worse than one coherent default. What actually protects the
+user is that every action is **user-initiated** and **bounded by caps at the
+moment it runs**.
+
+Autonomous/unattended trading is the sole exception, because it is the only mode
+where the agent initiates value movement without being asked. An agent that
+trades while you sleep is a different risk class from one that buys the NFT you
+just named.
+
+Keep an `execute: true` marker at the call site (it stops a send happening as a
+side effect of a read path) but do not add an env arm beside it. `armed` and
+`allowed` are distinct states and must be reported separately: key present with
+no user request is `armed: true, allowed: false`. Only the literal string `"1"`
+enables autonomous — `"true"`, `"yes"`, `"01"` must all stay off.
+
+Full rule, the `capabilityStatus` shape, and the retro-fit note (delete arms you
+already added): `references/key-material-and-arming-posture.md`.
+
+## Wallet UX
+
+Wallet connect is a primary control, not a small utility button. Keep it persistent in the top bar and repeat a dominant connect/sign action inside execution. Discover ALL wallets with EIP-6963 (RH AGENT must support Rabby AND MetaMask), rank by rdns for the default (rabby=0, metamask=1, other=2), and render a picker `<select>` in the top bar when more than one wallet announces. Switching wallets must fully reset the session (token, gate status, balances, quotes). Switch/add the target chain, request accounts, sign short-lived single-use challenges only for authenticated actions, and invalidate sessions on account or chain changes. Copy rule: never hardcode "Rabby" in notices/buttons — use the active `walletName` ("WAITING FOR WALLET", "confirm in your wallet") so MetaMask users aren't told to check Rabby.
+
+### Keep wallet identities separate
+
+Never collapse these three concepts in API responses or UI:
+
+- **Connected wallet:** browser signer and holder-gate identity. Its Robinhood Chain balance comes from its address through RPC.
+- **Agent API key owner:** address bound to the `rhag_` credential. The key authenticates reads/prepares; it is not a private key or spending authority.
+- **Executor wallet:** separate capped signer for unattended actions. Put its address, RH balance, caps, spend today, funding state, and kill-switch state in a dedicated card beside Agent Connect.
+
+`GET /api/agent/policy` is policy, not portfolio data. Expose the API-key owner's balance through `GET /api/agent/positions`, and the executor balance through a dedicated status endpoint. Label both with address and chain.
+
+A locally generated executor JSON is **not installed** merely because an address exists. Do not tell the user to fund it until the signer has a secure backup, the key has moved directly into production secret storage without chat/log exposure, executor code is deployed, and the website resolves the same address. Never offer a website private-key download. Deploy code/status first, verify the unfunded capped state, then fund, then separately GO-gate broadcasts.
+
+### Executor discovery, ownership, and activation
+
+An executor address is public, not a secret. Make it easy for the authorized operator to find and verify:
+- Show the full address, copy control, chain, balance, signer-installed state, caps, daily spend, and enabled/halted state in the dedicated Agent Connect card.
+- Expose the same public fields through an authenticated status endpoint. If policy is public, exposing the address there is acceptable, but never expose key material or imply that address visibility grants control.
+- Before funding, derive the address independently from the production signer file and require an exact match with both UI and API.
+
+Do not let public users fund one shared operator executor. A server-wide hot wallet is appropriate only for the operator's own capped automation. Multi-user execution needs one isolated executor or session key per user, tied to that user's API-key owner, with a separate balance, ledger, caps, allowlists, and kill switch. Otherwise the product creates pooled custody, cross-user accounting, and shared-compromise risk.
+
+Treat activation as a ladder, not one switch:
+1. Deploy signer and status with execution disabled.
+2. Verify production address, file ownership/mode, zero balance, caps, and blocked execute routes.
+3. On explicit GO, enable `agent:execute` only for a controller allowlist.
+4. Never promote a key pasted into chat or screenshots. Revoke it, generate a replacement directly into owner-only secret storage, and verify its scope without printing the raw key.
+5. Keep token/NFT and scanner auto-allowlists empty while enabling scope. Execute scope alone must not create a tradeable asset universe.
+6. Add one verified resource allowlist, fund narrowly, execute one tiny idempotent request, wait for a successful receipt, reconcile, then expand.
+
+Report each gate separately. `agent:execute=true` does not mean "trading": an unfunded wallet or empty asset allowlists still blocks every action.
+
+### Chat-leaked burner keys are still burn-only
+
+If a user pastes a Solana secret key, BTC WIF, seed phrase, or Xverse seed into chat, do **not** import or use it, even when they say it is only a burner. Treat the key as compromised, tell them to generate/import a fresh burner directly on the machine that will sign, and accept only the public address in chat. Long base58 Solana strings are often secret keys; validate by reading the public address only. For Bitcoin inscriptions, prefer a fresh local WIF file that pays commit/reveal fees while inscribing **to** a separate ordinal receive address. Never store an Xverse seed for agentic testing.
+
+Creator/operator urgency is not an exception. If DEMI says "use it for now", "save it locally", or "we already did it for EVM", keep the key-ingress invariant and make the safe local path fast: create the owner-only key directory, create empty `0600` files, and provide/run a prompt-only local installer (`read -s`, no echo, no logs) for the user to paste on the signing machine. After install, the agent may report file mode/size, derive public addresses, and check balances/readiness; never print or copy the raw secret.
+
+Detailed response pattern: `references/chat-leaked-key-ingestion.md`.
+
+### Operator installer, owner-gate, and launch hardening
+
+The execution policy is only as strong as the files and launchers that select it. Treat
+operator installation as part of the signer boundary:
+
+- Do not let a model-writable adjacent file reassign the human owner of a pre-tool gate.
+  Pin a dedicated operator identity in reviewed private code, or load it from an
+  integrity-protected authority outside the model's ordinary write surface. Add a regression
+  proving `owner.id`-style files cannot change the caller accepted by the hook. Keep
+  machine-specific identities out of canonical/public defaults.
+- A text-arm must be scoped to the current conversation and current owner. Resolve the actual
+  caller from session state, reject non-owner/unknown sessions, and avoid accepting a stale
+  `GO` from an unrelated message as standing authorization.
+- Never `source` credential env files from shell or generated service launchers. That executes
+  their contents as code. Require regular non-symlink owner-only files, parse them as data, or
+  use the runtime's data-only env-file option. Pass bearer headers through stdin or an
+  equivalent non-argv channel, and make authenticated status helpers reject non-loopback
+  destinations and reflected secrets.
+- Secret migration/recovery writes must be same-directory temp-file + atomic rename, with
+  `lstat` checks that reject symlinks and non-regular destinations. Secure the parent directory,
+  use `0600`, refuse orphaned passphrase/keystore mismatches, verify the derived public address
+  before replacement, and retain a rollback copy without logging key material.
+- Test installers and launchers as security code: injection-shaped env values remain inert,
+  broad file modes fail closed, symlinked destinations are refused, and final status proves the
+  execution plane is still disarmed.
+
+### One key controls MANY addresses — enumerate before concluding
+
+A single secp256k1 key controls P2PKH (`1…`), P2SH-P2WPKH (`3…`), P2WPKH
+(`bc1q…`) and P2TR (`bc1p…`) simultaneously. Old wallets and exchanges default to
+`3…`; modern signing code defaults to `bc1q…`. Funds sitting at one script type
+while the signer builds inputs for another looks *exactly* like "the agent can't
+read the key" or "insufficient funds" — and it is neither.
+
+**Before reporting a balance, before "insufficient funds", and before signing,
+derive and check every address type the key controls.** Use the signing library's
+own derivation (`@scure/btc-signer` `p2wpkh`/`p2tr`/`p2pkh`/`p2sh`), never a
+hand-rolled bech32/base58 path — hand-rolling needs the BIP341 TapTweak by hand
+and produces a plausible-looking wrong taproot address.
+
+When funds are at the wrong script type, consolidate first: a P2SH-wrapped
+segwit input needs **both** `witnessUtxo` and `redeemScript`. Assert derived
+addresses against expected constants before broadcast, and check the UTXO set
+for ordinal/dust outputs (`<= 1000 sats`) before sweeping — an ordinals address
+with hundreds of funded outputs must never be auto-selected.
+
+### Encrypt local signer keys at rest
+
+`0600` is one backup tarball, one `~/.config` cloud-sync, or one stolen disk from
+spendable. Wrap key files: scrypt(N=2^17) → KEK, AES-256-GCM wraps a random DEK,
+DEK encrypts the material, JSON header bound as AAD so a KDF-cost downgrade fails
+authentication instead of silently weakening decryption. Two layers mean a
+passphrase rotation rewraps 32 bytes and never exposes the secret.
+
+State the threat model honestly — it defends backups, sync, and stolen disks; it
+does **not** defend a live process already holding the key or a keylogger. Never
+oversell a file-level scheme.
+
+Operational invariants: verify decrypt-to-byte-identical **before** touching the
+original, never delete the plaintext yourself (move to `.bak`, tell the user to
+`shred -u`), passphrase never in argv (`ps` leaks it), passphrase file outside
+the keys directory, raw key files keep loading unchanged (encryption is opt-in),
+and no code path writes a decrypted key to disk.
+
+Both, with the derivation snippet, vault design, and the tests that carry weight:
+`references/key-material-and-arming-posture.md`.
+
+## Swap gate
+
+Before returning calldata:
+
+1. Resolve factory, router, quoter, wrapped native token, and any Universal Router from authoritative docs plus verified explorer source and live bytecode. Explorer names alone are unsafe because clones share names.
+2. Bind token, pool, fee, side, amount, wallet, and quote to the current server-side market record.
+3. Confirm the advertised pool equals `factory.getPool(token, wrappedNative, fee)`.
+4. Quote on-chain, timestamp it, and reject stale or mismatched quotes.
+5. Apply a bounded slippage cap and nonzero `amountOutMinimum`.
+6. Use a short deadline.
+7. For sells, approve only the exact amount. Never default to unlimited approval.
+8. Simulate the exact transaction with `eth_call` from the connected wallet.
+9. Return a wallet-signable transaction. The server never signs.
+10. Re-quote and re-simulate immediately before preparation, not only when displaying the quote.
+
+## Atomic pre-buy sellability simulation
+
+When honeypot APIs do not support a chain, use a matching verified Universal Router to simulate a full buy and sell in one state-free `eth_call`:
+
+1. `WRAP_ETH` into the router.
+2. `V3_SWAP_EXACT_IN` from WETH to token, recipient router, internal payer.
+3. `V3_SWAP_EXACT_IN` from token back to WETH using `CONTRACT_BALANCE`.
+4. Require a minimum WETH balance.
+5. `UNWRAP_WETH` to the simulated sender.
+
+Quote in both directions first and set minimum round-trip return below the no-tax reverse quote by a bounded tolerance. Treat quote failure, transfer failure, insufficient sender balance, router revert, or minimum-return miss as `FAIL`.
+
+Chain-specific verified addresses, ABI differences, command bytes, and live probe results belong under `references/`. For Robinhood Chain, load `references/robinhood-chain.md` before implementation.
+
+### Venue-agnostic round-trip sell-sim (any chain, any DEX)
+
+When there is no Universal Router to simulate through, get the same signal from
+quotes: **quote the buy, then quote selling exactly what that buy would yield,
+and compare against what went in.** Pass in a quote function so one module covers
+every chain and venue.
+
+DEMI asks for this by name ("a sell sim so people don't ape an unsafe contract
+address or honeypot"). It is the single highest-value guard in the product: the
+most expensive failure in memecoin trading is not a bad entry, it is an entry you
+cannot exit, and a honeypot looks identical to a healthy token on a chart *and*
+on a buy-side quote.
+
+Four verdicts, never a bare boolean — the caller must be able to show the user
+why:
+
+| Verdict | Trigger |
+|---|---|
+| `HONEYPOT` | sell leg fails to quote, returns zero, or round-trip loss ≥ 5000 bps |
+| `CAUTION` | round-trip loss ≥ 1500 bps (high tax or thin liquidity) |
+| `SAFE` | round trip within normal fees |
+| `UNKNOWN` | buy leg unroutable, or unparseable quote output |
+
+Rules that matter:
+
+- **Sell the tokens the buy actually produced**, not a guessed amount. Assert
+  this in a test by capturing the amount passed to the sell leg.
+- **Buy routes + sell won't quote = HONEYPOT**, not `UNKNOWN`. That asymmetry is
+  the classic shape.
+- **Fail CLOSED on `UNKNOWN`.** "Could not verify you can exit" must never read
+  as "safe to ape". `allowUnknown` exists only for research surfaces where no
+  money moves.
+- Garbage quote output (`outAmount: "not-a-number"`) is `UNKNOWN`, never a false
+  `SAFE`.
+- Attach the full result to the thrown error (`err.sellSim`) so the refusal
+  carries its evidence.
+
+### Structural risk is a SECOND question — run it beside the sell-sim
+
+A sell-sim is **behavioural**: it proves the token is sellable *right now*. It
+cannot see a killswitch that has not fired. A token passes a sell-sim perfectly
+while its owner holds `blacklist()`, a mint function, or a fee setter — the
+honeypot is armed, just not triggered yet. So also ask the **structural**
+question: what powers does the deployer still hold?
+
+Read bytecode for retained-power selectors (mint / blacklist / pause / fee /
+upgrade) plus proxy implementation slots. Rules that carry the weight:
+
+- **Derive selectors with `keccak_256` in code, never transcribe hex.** A wrong
+  security constant fails *silently* — it never matches and the guard reports
+  clean forever.
+- **Check every proxy slot.** EIP-1967 alone reported **USDC on mainnet as "not
+  a proxy"**, because its implementation sits in the older unstructured
+  OpenZeppelin slot. Check EIP-1967 + zeppelinos + EIP-1822 and report which
+  matched plus the implementation address.
+- **Never return "safe".** Three levels: `unknown-risk` / `elevated` / `high`.
+  The best result is "no owner powers found, which is weak evidence, not a
+  guarantee" — proxies hide the real logic and absence proves nothing.
+- **An RPC failure is `unavailable`, never clean.** No code at the address is
+  `high` (an approval there is unrecoverable). `owner()` alone is `elevated`,
+  not `high` — crying wolf on every ordinary token trains people to ignore it.
+- **Take the transport as an option** (`opts.rpcCall`): ESM exports cannot be
+  mocked (`Cannot redefine property`), and injection keeps the suite offline.
+
+Selector table, proxy slot constants, the NFT drainer-flagging heuristics (the
+marketplace `spam` flag cannot see an unlisted airdrop, and NSFW is not spam),
+and the full registry-wiring checklist for adding a provider:
+`references/structural-contract-and-nft-risk.md`.
+
+## NFT access gate
+
+Use direct contract RPC as the source of truth for holder-only dashboard access. Do not use OpenSea for access control, it can lag or fail.
+
+### But DO use OpenSea as the cross-chain NFT *index*
+
+Access control and discovery are different jobs. OpenSea v2 indexes NFTs across
+~23 chains keyed by a chain **slug**, so it is the one place to resolve a bare
+contract address on **any** chain (DEMI: "nfts across all chains should be
+scanned through opensea").
+
+Keep a slug↔chainId map (`ethereum:1`, `matic:137`, `base:8453`,
+`arbitrum:42161`, `ape_chain:33139`, `berachain:80094`, `abstract:2741`,
+`ronin:2020`, `zora`, `blast`, `unichain`, `soneium`, `bsc`, … plus `solana`
+with a `null` chainId since it is non-EVM). Expose both directions: the slug is
+what the API path wants, the chainId is what the rest of the agent speaks.
+
+Users paste an address without knowing the chain, and guessing wrong is how
+people buy the wrong asset. So fan out across the supported set with bounded
+concurrency (~6) and report **every** hit rather than the first:
+
+- `400`/`404` from one chain means "not on this chain" during a fan-out — return
+  `null` and keep going, do not abort the scan.
+- one chain erroring must not fail the whole sweep
+- return `{ chainsScanned, found, matches[] }` so "not found anywhere" is
+  distinguishable from "we only looked at one chain"
+
+Pattern:
+1. User connects wallet and signs a short-lived nonce challenge.
+2. Backend verifies the recovered signer.
+3. Operator allowlist bypasses holder checks for DEMI/admin wallets.
+4. Everyone else must pass `balanceOf(wallet) > 0` against the configured ERC-721 contract, or `balanceOf(wallet, tokenId) > 0` for ERC-1155.
+5. Session token stores the access class, e.g. `operator` or `nft-holder`; API routes check the session server-side.
+6. The locked frontend must not fetch protected scanner/market/risk routes before auth, otherwise expected 401s become noisy console errors and hide real issues.
+
+When a specific production wallet needs access without owning the NFT, use a separate access-only allowlist that maps to `nft-holder`, never the development operator bypass. Deployment and verification pattern: `references/production-access-whitelist.md`.
+
+Locals Only holder gate reference, pulled from the Polymarket bot UI: HyperEVM chain `999`, contract `0x62FCFAf7573AD8B41a0FBF347AfEb85e06599A75`, name `Locals Only`, symbol `LOCALS`.
+
+## NFT mint gate
+
+- Discover ERC-721 and ERC-1155 contracts from canonical RPC logs with a bounded startup window and incremental block cursor; use explorer registries only as optional enrichment.
+- Require verified source and ABI.
+- Allow only recognized quantity functions such as `mint(uint256)`, `publicMint(uint256)`, or `mintPublic(uint256)`.
+- Reject ambiguous `mint(address,uint256)` because the integer may be a token ID.
+- Cap quantity.
+- For payable mints, derive price only from a verified no-argument view function.
+- Enforce gas-war limits before returning any wallet-signable mint tx: total gas spend (`gasLimit * maxFeePerGas` or legacy `gasLimit * gasPrice`) must fit the grant/user cap, and optional per-unit `maxFeePerGas` plus `maxPriorityFeePerGas` tip caps must fail closed when exceeded.
+- Treat mint price/value caps and gas caps as separate money bounds. A mint bot with a max price but uncapped gas is not public-safe.
+- Simulate from the connected wallet before returning the transaction.
+- Never accept raw user calldata.
+
+### A guard nobody calls is not a guard
+
+`validateNftMintGasWar()` shipped with a full test suite and **zero call sites** —
+its only appearance outside its own file was a barrel re-export. The caps were
+documented, tested, and enforced on nothing. Tests prove a guard *works*, not
+that it *runs*:
+
+```bash
+rg -n 'guardName\(' src/ bin/ apps/ | grep -v 'export function' | grep -v 'export {'
+```
+
+Zero means the feature is unprotected regardless of its test file. The
+re-export line is what makes a naive grep look healthy.
+
+### Discover the entrypoint; never assume it
+
+ERC-721 standardizes ownership and transfer, **not creation**, so every
+collection invents its own entrypoint. Discover it in deployed bytecode; report
+`unsupported` rather than encoding a guess (guessing wrong in a contested mint
+burns gas *and* the allocation), and report **ambiguous** when several match.
+Verified live: Doodles → `mint(uint256)`, BAYC → **none** (it uses `mintApe`),
+which is the proof discovery is reading bytecode rather than hoping.
+
+Derive every 4-byte selector with `keccak_256` in code. Two silent bugs in one
+session: `publicMint(uint256)` is `2db11544` (not `26092b83`), and `mintActive()`
+is `25fd90f3` — the value first written, `1249c58b`, is actually **`mint()`**, so
+the mint-open check would have probed a mint *function* as a state flag.
+
+### Bid competitively, but bounded
+
+Tips come from `eth_feeHistory` **reward percentiles** (p50/p75/p90 by urgency),
+not `eth_maxPriorityFeePerGas` — one node's opinion hides the distribution, and
+in a gas war the distribution is the signal. Median across blocks so one whale
+cannot skew it.
+
+`maxFeePerGas` is a **refundable ceiling** (headroom against a climbing basefee
+costs nothing); the tip is real spend that orders you against competitors. So:
+generous multiplier on the ceiling, disciplined percentile on the tip.
+
+When a cap would push the bid below observed market, return `viable: false` with
+the arithmetic — **never silently clamp to a losing number**. Paying gas to lose
+is worse than not bidding.
+
+### Arm only on an exact request
+
+Execute requires **all** of: `actionMode` equal to the exact string `"execute"`,
+`ORACLE_AUTONOMOUS_TRADING=1`, and a grant naming this exact contract and chain
+with `maxTotalGasWei`, `maxValueWei`, and a bounded expiry. `"Execute"`,
+`"exec"`, `true`, `1`, `"arm"`, `"fire"` all resolve to `alert_only`. Downgrade
+with a stated reason rather than erroring — an error teaches the caller to retry
+with looser input. Decide arming at creation so a trigger cannot self-upgrade,
+re-check the spend ceiling at fire time, and treat an unreadable sale flag as
+**not open**.
+
+Selector tables, the percentile/multiplier table with live values, the
+`mint(address,uint256)` ambiguity conflict, and the registry-wiring checklist:
+`references/nft-mint-discovery-and-gas-bidding.md`.
+
+## OpenSea drop mint + floor sweep gate
+
+Marketplace mint/sweep is a second path beside verified-ABI local mints. Same custody model: backend prepares, wallet signs.
+
+1. Keep marketplace API keys server-only (`OPENSEA_API_KEY`). Never `VITE_*` or client bundles.
+2. Accept only opensea.io collection URLs; parse slug server-side.
+3. Hard-fail non-target chains (RH bot: Robinhood Chain only). Scanner NFT counts are not proof of mint/sweep readiness.
+4. Drop mint: build mint tx via marketplace API, validate `to`/hex calldata, simulate with `eth_call` from the connected wallet, return wallet-signable payload only after PASS.
+5. Floor listings: best listings sorted ascending; filter to target chain + ACTIVE; expose tokenId, orderHash, price, currency for UI caps.
+6. Floor sweep: cap max items and max price per item (and total spend) before fulfillment. Preview listings against the cap, then request sweep/fulfillment steps.
+7. Normalize marketplace step blobs into concrete `{from,to,data,value}` txs. OpenSea sweep responses may wrap `from` and `to` as `{ value, chainArch }`, return `value` as decimal wei, and expose the chain under `chainIdentifier.chainId`; unwrap and validate all three before simulation. Reject wrong buyer, wrong chain, non-hex data, invalid targets, or missing steps.
+8. Simulate every returned sweep step before returning to the client. On multi-step sweeps, client confirms each step in order and waits for receipt between steps.
+9. Never auto-broadcast. No backend signer. No raw user-supplied marketplace calldata.
+
+RH OpenSea endpoint shapes, payment-token native zero-address, and test fixtures: `references/opensea-rh-mint-sweep.md`.
+
+For Rootio/Photon-style RH bot scanner + mint UI patterns, including honest `UNKNOWN` treatment for unavailable tax/initial-liquidity data, Quick Buy constraints, gas display, and browser verification, use `references/rhbot-rootio-ui-gates.md`.
+
+## Agent Connect API + MCP (RH AGENT)
+
+API keys first, MCP second. Full surface, scopes, caps, and verification: `references/agent-connect-api-mcp.md`. For deploy/regression proof before claiming RH AGENT works, use `references/rh-agent-api-mcp-smoke.md`.
+
+For limited automatic execution through a separate capped hot wallet, use `references/rh-agent-capped-hot-wallet-executor.md`. That reference also carries the fail-closed security-review defect taxonomy for auditing an executor diff (kill-switch TOCTOU, uncapped gas, provenance-as-trust bypass, non-atomic caps, replay/idempotency, create-time-only authz).
+
+Short rules:
+- Locals/operator session creates hashed `rhag_` keys; raw key shown once.
+- Prepare-only scopes are markets/nfts/positions/watch/prepare/shadow.
+- `agent:execute` must be invalid unless `RH_AGENT_EXECUTE_ENABLED=1`; prod deploys should keep it blocked by default.
+- MCP (`server/mcp.js`) is a thin wrapper over the same REST endpoints; exposing an MCP execute tool does not enable execution unless server policy allows it.
+- Signing stays with the connected wallet, a separate capped session key, or a tiny hot wallet explicitly GO-gated by DEMI. Never use DEMI's main seed/private key.
+- x402 is payments later, not trade authority.
+
+### Multi-user distribution end-state (DEMI product rule)
+Everyone gets agent auto-prepare; **hot wallet is theirs, on their machine** — not the house executor.
+**Users never set up two Hermes profiles** (dual profiles = operator cost plumbing only).
+
+**Two website setup paths (AGENTIC TRADING tabs on rhagent.demi.la):**
+1. **Hosted** — connect wallet → create `rhag_` key → TEST → COPY Hermes/Claude MCP → user signs.
+2. **Your VPS** — self-host rhbot → local MCP (`RH_AGENT_BASE_URL=http://127.0.0.1:8792`) → same prepare model; optional thin hot wallet on *their* box only.
+
+Docs: `/agent/setup.md` (server file `public/agent-setup.md`).
+
+**Split buys/sells (same plan house + users + MCP):**
+- `server/split-exec.js`: `planSplitAmounts`, `executeSplitSwap`, `prepareSplitSwaps`.
+- `POST /api/agent/execute-trade` → multi-tx house broadcast; fail mid-split **stops**.
+- `POST /api/agent/prepare-trade` + `POST /api/swaps/prepare` → `mode: prepare-split`, `slices[]`, back-compat `prepared` = slice 1; user signs in order with gap.
+- Exit large sells re-slice when above threshold.
+- MCP `rh_prepare_trade` / `rh_prepare_trade_split` → prepare only (still needs API key to some backend).
+- Env: `RH_SPLIT_ENABLED`, `RH_SPLIT_CHUNKS`, `RH_SPLIT_MAX_CHUNK_ETH`, `RH_SPLIT_GAP_MS`. Multi-tx over time is intentional; single-block multicall is weak/optional.
+- Detail: `references/prepare-trade-response-shape.md` + `references/split-execution-and-setup-paths.md`.
+- Local: `rhag_` + born-encrypted keystore → prepare → sign → broadcast.
+
+## NFT floor exit plans (minimum price + take profit)
+
+NFT positions get server-side exit plans evaluated against the live OpenSea floor, same custody model as token TP/SL: the server tracks and flags, the wallet sells.
+
+- Plan record: `{ slug, contract?, entryPriceEth, minPriceEth (defaults to entry), takeProfitPct }` → derived `targetFloorEth = entry * (1 + tp/100)`. Reject targets below the minimum.
+- Evaluation against live floor (OpenSea `/collections/{slug}/stats` → `total.floor_price`): `BELOW_MIN` (floor under minimum, refuse to sell), `WAITING`, `TRIGGERED` (floor ≥ target, tell user to list/sell in wallet), `UNKNOWN` when floor is missing/zero — never treat a missing floor as a trigger.
+- Routes owner-bound via `requireUser`; check endpoint filters by actor + `type === "nft_take_profit"` and audits every check. No auto-sale, ever.
+- OpenSea stats + recent mints (zero-address transfers filtered to target chain) are read surfaces exposed to both UI and Agent Connect (`rh_get_nft_stats`, `rh_get_nft_mints`) so an agent can watch floors without a browser tab.
+
+Implementation shape: `server/nft-exit-plan.js` (pure build/evaluate, unit-testable), reuses the existing `exitPolicies` store.
+
+## Autonomous SELL execution (exit engine `executeSell` wiring)
+
+The token exit engine (`server/exit-engine.js`) ships PREPARE-ONLY — on a stop-loss/TP trigger it prepares the swap and emits `requiresWalletSignature:true`, status `TRIGGERED`; it does NOT sign/broadcast (`executeSell` is passed `null`). To make it truly hands-off (auto sell-back to native ETH on trigger), wire an `executeSell` closure to a NEW sell-only executor (`executePreparedSell` + `assertSellExecutionAllowed`) behind its own flag `RH_AGENT_EXECUTOR_ALLOW_SELL`. This is the ONE legit backend-hot-key unattended path: it's downside protection on a manually-funded, manually-armed, capped, GO-gated position — NOT entry aping (keep buy/sell conceptually split). Full wiring, the sell gate (value==0, skip ETH-cap, keep halt/router/gas/allowlist), the three blocking traps (wallet-alignment, fresh-wallet `kind:"approval"` blocking the first fire, scanner-quoteToken dependency), the rhbot `loadEnvFile`-not-`dotenv` verify gotcha, and the tiny-size live test sequence: `references/autonomous-exit-executor-sell-wiring.md`.
+
+## Merge / branch inventory before "shipped" claims
+
+When DEMI asks if NFT/OpenSea work is in and ready to merge:
+
+1. Diff `main` against feature branches (`origin/feat/*`), not only the current worktree.
+2. Grep for mint + floor/sweep/fulfillment paths. Mint-only hardening is not floor sweep.
+3. State explicitly what would be left out if current `main` were committed/pushed alone.
+4. Prefer integrating missing gates into the active UI branch over claiming a sibling branch is included by adjacency.
+5. For RH AGENT main claims: confirm gate + Agent Connect + shadow agent + `rhagent.demi.la` prod markers, not only the open feature branch.
+
+## Real-time discovery and conditional execution
+
+A live scanner and a live executor are separate authority domains.
+
+- Detect launches from factory events at block cadence, dedupe by transaction hash plus log index, then enrich through the normal scanner before presenting executable data.
+- Push launch and refresh signals to clients with SSE or WebSocket, but retain bounded periodic snapshot polling as fallback.
+- Persist conditional orders with token contract, side, target price, amount, actor, and explicit execution mode.
+- Browser-evaluated limits and TP/SL are **tab-armed** only. Say clearly that closing the tab disables trigger handling.
+- A trigger opens a fresh trade ticket. Re-quote, re-run sellability/simulation, enforce slippage and size limits, then require Rabby confirmation.
+- Never describe tab-armed triggers as unattended execution. Unattended execution requires an audited conditional-order contract or a restricted smart-wallet/session-key permission path. A backend hot key is not an acceptable shortcut.
+- Persist TP/SL entry price and token contract with each rule; percentages without an entry reference cannot be evaluated correctly.
+- Deduplicate triggered rule IDs client-side so each price update does not reopen the same ticket.
+- A `BLIND APE` UX may skip manual evidence review, but it must never bypass route membership, reverse quote/sell simulation, position caps, slippage caps, or wallet confirmation.
+
+Implementation pattern and DexScreener embed caveats: `references/realtime-conditional-orders.md`.
+
+RPC-native NFT and V3 factory discovery, live proof layers, marketplace runtime verification, temporary smoke-access cleanup, and per-source freshness: `references/rpc-native-discovery-and-live-proof.md`.
+
+## Extensible multi-chain scanners (chain = config, not code)
+
+When the ask is "do we have a scanner for every chain", the answer is a **framework**,
+not N hand-wired integrations. Define a capability contract, implement it once
+generically over standard JSON-RPC, and let a new chain register from a config object.
+
+Two rules keep it honest:
+
+- **Unimplemented ≠ faked.** An unsupported capability throws naming what *is*
+  supported; it never returns `undefined` a caller reads as a negative result.
+- **Capabilities that need a verified per-chain router (`quote`, `sellSimulation`,
+  `prepareUnsignedTx`) stay ABSENT until provenance is recorded.** A chain with no
+  verified venue is fail-closed for routing value — read/research still works. That is
+  a safe state to advertise, not a gap to apologize for.
+
+Ship ONE chain wired end-to-end as the reference so the pattern is copyable, and leave
+the rest at the generic tier rather than bulk-adding unverified routers.
+
+Full contract, the `this`-binding trap that silently blinds `scoreRisk`, evidence/risk
+label semantics, round-trip retention thresholds, the `getAmountsOut` array-decode
+trap, and the non-yielding slippage ceiling: `references/extensible-chain-scanner.md`.
+
+### Venue adapters are per-AMM-shape, never one bent to fit
+
+V3 is not V2 with different addresses: no `getAmountsOut`, prices through a separate
+Quoter, needs an explicit fee tier per hop. Encoding a V3 swap with V2 assumptions
+yields a tx that reverts — or worse, routes through the wrong pool at a price nobody
+quoted. Write a **sibling** adapter and assert separation on the *selector*
+(`d06ca61f` vs `c6a5026a`), which cannot appear in prose by accident.
+
+Select by declared shape and require the whole set: a V3 chain needs **both** quoter
+and router. A router alone stays fail-closed — it could encode a swap with no priced
+expectation to guard against, which is exactly the state that produces an unbounded
+fill.
+
+**Search every fee tier (100/500/3000/10000) and keep the best.** Load-bearing, not
+thoroughness theatre: liquidity concentrates in one tier and which tier varies by pair
+and chain. Live on Arbitrum WETH→USDC the 500 tier returned 1908.72 vs 1862.15 on the
+100 tier — 2.4% a hardcoded 0.3% default would have eaten.
+
+### Verify a venue functionally — codesize proves deployment, not identity
+
+Ask the candidate to **price a pair whose answer you can sanity-check**. A contract
+that correctly quotes WETH→USDC *is* a working quoter, whatever any doc claims.
+
+The canonical mainnet QuoterV2 address returns ~2109 bytes of bytecode on Base — some
+contract, just not one that can price that chain's pairs. A codesize check allowlists
+it; the functional probe caught it and pointed at Base's real quoter (8273 bytes).
+
+Commit the prober as a re-runnable script (`npm run verify:venues`), not a one-off,
+and record provenance as `{ method, source, date, chainId }` — with a test asserting
+`verified.chainId` matches the chain it is listed under. An address verified on
+Arbitrum is not verified on Ethereum, even when the deployment shares an address.
+
+## Best-execution routing (cheapest swap / bridge)
+
+Cheapest ≠ highest quote. Rank on **net received after gas and fees**, querying every
+source in parallel. Gas is part of the price, and the crossover between "better quote"
+and "cheaper gas" moves with trade size — so any fixed preference is wrong on one side
+of it. Intent venues (CoW) where a solver eats the gas routinely win on net while
+losing on gross.
+
+Unknown cost is **never** scored as zero — that is how the worst route wins a
+comparison. Mark it, rank on gross, warn. Quote a spread only when the top two routes
+measure cost the same way, and name the basis.
+
+Per-source cost-semantics table, the spread-basis bug caught live, source-outage
+handling (Odos 410 mid-build), bridge duration reporting, and the deterministic test
+targets: `references/best-execution-routing.md`.
+
+### Hand the winner to prepare — a comparison is not a signature
+
+A ranked winner the user must rebuild by hand is a leak, not a feature. Close the loop:
+**compare → pick → re-quote → build the signable artifact**, so "best route" and "the tx
+you sign" are provably the same route.
+
+Two rules dominate:
+
+- **Artifact kinds are not interchangeable.** `unsigned-transaction` (LI.FI, ParaSwap,
+  0x) gets broadcast; `typed-data-order` (CoW) is signed and submitted to an order API
+  with **nothing to broadcast**. Return `artifactKind` and branch on it — conflating
+  them fails at *signing time, after tokens were already approved*.
+- **`requiresApproval.spender` is not `destination`.** CoW pulls funds through the
+  **vault relayer**, not the settlement contract; approving the wrong one yields an
+  order that silently never fills. Read the provider's field, never derive it.
+
+Prepare must **re-quote** (the comparison is already stale) and report `driftBps` against
+a bounded tolerance — zero tolerance fails constantly between blocks, unbounded silently
+prepares a worse trade than the one agreed to.
+
+Validate the taker locally: reject missing, malformed, and placeholder/burn addresses
+before any network call. **Quoting is anonymous; preparing is not.** ParaSwap rejects
+`0x…dEaD`; other venues happily build a transaction for an address nobody controls, so
+relying on the venue means relying on the least careful one.
+
+Some venues refuse to build calldata until the approval **already exists on-chain**
+(ParaSwap: `Not enough WETH allowance given to TokenTransferProxy`). That is a genuine
+ordering constraint — classify it (`approval-required-first`) rather than surfacing a
+bare HTTP 400 that reads like the router is broken. Read `err.body`, not just
+`err.message`: the status line alone flattens every venue rejection into a generic
+provider error.
+
+Never dead-end and never substitute silently: an unpreparable winner names an
+`alternative`, and a forced non-winner is flagged `wasWinner: false`.
+
+Full artifact table, the CoW relayer assertion, error-classification pattern, drift math,
+and the key-gate test trap that exposed an unreachable preparer:
+`references/route-prepare-handoff.md`.
+
+### Bridge prepare: the artifact is a sequence, and confirmation is not arrival
+
+Same compare→prepare shape, but every bridge failure is **unrecoverable** — funds leave
+the origin chain before anything confirms on the destination. Four rules:
+
+- **Always return a LIST of transactions**, even when there is one. Some routes need an
+  approval *and* a deposit; a bare object for one source and a list for another
+  guarantees someone signs the first item and believes they are done — **approved, not
+  bridged**. State the count, and that multi-tx routes must be signed in order.
+- **Echo both chains.** Transactions execute on the origin and credit the destination;
+  showing only the signing chain hides half the trust decision. **Refuse** a tx whose
+  `chainId` ≠ origin (`chain-mismatch`) rather than letting a wallet prompt on the wrong
+  network.
+- **Say "not atomic" unprompted.** Origin confirmation does not mean funds arrived. This
+  is the most common bridging panic and silence causes **double-sends** — ship the ETA
+  and an explicit "do not re-send while pending".
+- **Duration is reported, never scored.** Saving $2 over 30 minutes vs paying $2 more to
+  land in 20 seconds is the caller's trade-off. Assert duration never enters score math.
+
+**Every fact stated in prose that a caller may act on needs a structured field carrying
+it.** A `no-prepare-path` branch named the fallback in its message but returned
+`alternative: undefined` — and that branch fires often, because Across wins on gross
+(unreported gas) yet cannot be prepared. An agent must not have to regex an error string.
+
+### Never brand a public artifact with a private name
+
+A prepared transaction carried `madSlippage` — the *private* codebase's name — in the
+payload handed to users (16 occurrences, 14 files). This leak class is invisible to a
+secret scan (no key material), a portability test (no path), and a docs test (not prose):
+it lives in the **output payload shape**. Audit field names in anything a stranger
+receives, not just source comments and env vars.
+
+Migrate with a **dual-read window**, never a hard cut: producers emit only the neutral
+name, consumers accept `new ?? legacy` (an artifact prepared *before* the rename must not
+fail its guard *after* it), and keep one legacy-named fixture so back-compat stays
+exercised rather than assumed.
+
+## Non-EVM prepare lanes (Solana, HyperCore, Bitcoin)
+
+Same custody model, different artifact. A Jupiter or Magic Eden prepare is a base64
+**serialized Solana transaction**; a HyperCore stake/delegate/unstake is **EIP-712
+typed data** signed with an EVM key and POSTed to `/exchange` (there is no chain to
+broadcast to — never call it "broadcast"); Bitcoin is a PSBT. Returning one generic
+"prepared" blob across these is the same category error as conflating an unsigned tx
+with a CoW order.
+
+Two rules that carry most of the weight:
+
+- **Prepare is not proof; simulate is.** Jupiter builds a valid-looking swap for a
+  placeholder pubkey and it fails one step later at
+  `simulateTransaction: ... failed to sanitize accounts offsets correctly`. An E2E that
+  stops at "returned base64" proves nothing — assert `err === null` from a real
+  simulate against a real funded pubkey, parameterized by env.
+- **Enforce prepare-only structurally.** Scan the module's own export names for
+  `submit|broadcast|send|sign` and fail the test if one exists, rather than trusting
+  convention. (Watch the `/sign/i` vs `HL_SIGNATURE_CHAIN_ID` false positive — use an
+  explicit allowlist, not a lookahead.)
+
+Provider auth tiers probed live, the Magic Eden cap-before-network-call test, HYPE's
+8-decimal wei and the two-bucket stake/delegate/undelegate/unstake sequence with its
+7-day queue, and the public-constant test-fixture rule:
+`references/non-evm-prepare-lanes.md`.
+
+### Ordinals inscriptions: a confirmed transaction is not a working inscription
+
+The hardest Bitcoin failure class is one where **everything reports success**. The
+broadcast returns 200, the tx confirms in a block, your local content hash matches
+byte-for-byte — and the inscription is dead. It is valid Bitcoin that simply is not
+an inscription, and nothing in the send path can tell you.
+
+Three encoding bugs produced exactly that on one release, each cheap to detect
+locally and expensive to detect on-chain:
+
+- **A spendable taproot internal key means the envelope never enters the witness.**
+  `p2tr(xOnly, {script: leaf})` lets the signer take the cheaper key path, so the
+  body is never revealed and the node rejects it as an *invalid Schnorr signature* —
+  which reads as a signing bug and is not one. Ordinals need a **NUMS (unspendable)**
+  internal key: `p2tr(undefined, {script: leaf})`. **The tell is `vsize`**: a 28KB
+  payload cannot fit in 111 vbytes, so check the size before debugging the signature.
+- **`allowUnknownInputs: true` is required to finalize.** An ordinals envelope is not
+  a standard script template, so `@scure/btc-signer` classifies the leaf as `unknown`
+  and throws `Finalize: Unknown tapLeafScript`. `allowUnknownOutputs` alone is not
+  enough — different flags, different sides of the transaction.
+- **The body tag is a bare `OP_0` (`0x00`), not a 1-byte push of zero.**
+  `encodePush([0])` emits `01 00`; ord reads that as an unknown tag, skips it, and
+  records an inscription **with an empty body**. This one confirms *and indexes*, so
+  the only symptom is a blank render and `content size: 0 bytes`.
+
+**Diff against a live indexed inscription rather than reading the spec.** Pulling a
+recently-indexed reveal off mainnet settles in one command what spec-reading argues
+about for an hour.
+
+**Gate the reveal on envelope structure before it spends anything** — assert the
+content-type tag is `0101`, the body tag is `0x00`, `vsize > 1000`, and the body head
+appears in the raw hex. Then verify *after* broadcast by pulling the tx back and
+reassembling the body from the witness pushes, never by re-hashing your local file:
+that matched perfectly through both dead attempts.
+
+Funds at a superseded **key-spendable** commit are recoverable via the key path by
+rebuilding the *original* leaf encoding — assert the derived address equals the funded
+one before signing. A NUMS commit is not recoverable (that is the point), so size its
+output at exactly `revealFee + 546`.
+
+Byte-level envelope layout, the `finalizeIdx` source that mandates
+`allowUnknownInputs`, the reassembly parser, the recovery script, and why the
+operator's "0 bytes" report *was* the diagnosis:
+`references/ordinals-inscription-envelope.md`.
+
+## Pre-publish security audit (before a repo goes public)
+
+Run an adversarial review with **several independent model lineages** before
+open-sourcing anything that moves money. One model is a spot check; three is an
+audit. Agreement across lineages is the strongest evidence a finding is real
+(Grok and Opus independently reported the same three CRITICALs), and each lineage
+catches defects the others miss (Fable alone found a capless transfer guard that
+authorized `MaxUint256 - 1`).
+
+Mechanics that matter: dispatch a **model** through a neutral profile
+(`hermes -p <neutral> -m <model-id>`), because a dispatch-only profile's SOUL will
+refuse and try to hand the audit to a bus instead; the brief must **forbid
+delegation** or subagents time out and return an empty log; run in background
+with `notify_on_complete`, since a real audit takes 20-45 minutes.
+
+**Provider safety filters block adversarial framing.** OpenAI-family models
+refuse with a cyber-risk flag — that is provider policy, not a harness bug, so do
+not debug the gateway. Reframe honestly as *pre-release engineering review of my
+own first-party code*, ask about **defect classes** ("input shapes where a limit
+is silently not applied") rather than exploits, and drop the words *attacker*,
+*exploit*, *bypass*, *drain*. If it still refuses, that lane is unavailable —
+say so and proceed with the lanes that answered.
+
+**Verify every fix by execution**, one script printing `HOLDS | BROKEN` with
+observed evidence per finding. This caught a wrong function name in the probe
+itself; an unverified fix and an unverified probe look identical on paper. Assert
+the optimization still survives alongside the fix (dedupe still collapses
+same-credential calls after the cache key was hardened).
+
+**Report findings without loss verbs.** Writing that a hostile object "drained
+Satflow, Magic Eden, 1inch, 0x, OpenSea" made DEMI ask *"wait they drained us?"* —
+these were code defects found by reading source, not incidents. Say "would have
+allowed" / "was reachable in code", state up front that nothing was exploited,
+name why each finding could not have fired (a cross-tenant cache leak needs two
+concurrent users with different keys; a private repo has one), and **verify
+balances live and show the numbers** the moment the owner sounds alarmed — before
+any explanation. Finding these while the repo is still private is the system
+working, not failing.
+
+Full brief template, reframing language, verification pattern, and the HMAC
+retro-fit note (re-sign mutations so bound-tests still test bounds, and add one
+unsigned-mutation test for forgery): `references/prepublish-multimodel-audit.md`.
+
+Round-7 concrete repros (allowance decode parity, fresh-window on approvals,
+approvalLike dest allowlist, mandatory slippage HMAC, HL action allowlist,
+keyFile non-leak) and the test-secret pinning pattern:
+`references/oracle-round7-guard-parity.md`.
+
+### When your own scanner flags your own public output, change the OUTPUT
+
+A public-plane response scanner returning 500 `secret-leak-blocked` on a route
+that ships no secret is a signal about the payload, not a reason to soften the
+rule. The audit chain's genesis hash (64 zero hex chars) tripped
+`raw-32-byte-hex-bare`, and it was right to: that shape is indistinguishable from
+a private key.
+
+Wrong fixes, in ascending order of damage: add the field to the hex64 allowlist
+(converts a control into a formality, and the next value under that name is
+unchecked forever); special-case "all zeros is fine" (paddable — invites a
+"mostly zeros" rule a real key can satisfy); `0x`-prefix it (fails
+`raw-32-byte-hex-key`, correctly, since that is the canonical key shape).
+
+Right fix: **stop shipping a key-shaped value.** Genesis carries zero entropy, so
+describe it (`genesisBytes: 32`, `genesisDescription: "32 zero bytes"`) and let
+the integrator reconstruct it. Leave a comment saying why, or a later session
+"simplifies" it back. Ask in order: does the consumer need this exact value or a
+description; can it be a length/boolean/label/prefix instead; and only then, is
+the field name allowlist-worthy on its own merits independent of today's
+inconvenience.
+
+**Keep both scan layers** — they disagreed here. The graph walk gives the
+actionable path (`$.audit.genesis`); the serialized scan is authoritative because
+`toJSON()`, getters, symbol keys and BigInt coercion put bytes on the wire the
+graph never visits. One intermediate attempt passed serialized while still
+failing graph.
+
+**Dogfooding a secret scanner over first-party source returns false positives, and
+you must say so.** 67 files produced 7 findings, all benign on inspection: a
+zero-address constant, an ERC1967 bytecode fragment, and — four times — the
+scanner's own rule definitions (`{ rule: "keystore-path", re: /keystore/i }`).
+Same class as a forbidden-token test that scans its own test file: exclude the
+rule-defining files or strip obvious regex sources first. Report the real
+false-positive rate rather than "7 blockers found", and do not tune the scanner
+into silence either — the public-boundary scan (0 findings) was the check that
+actually mattered and it was clean.
+
+Full worked case, the two-layer disagreement, and the false-positive table:
+`references/secret-scanner-flags-own-output.md`.
+
+## Venue datapoint joins (derive once, not per surface)
+
+When a venue's read API returns **parallel arrays** and stringly-typed numbers
+(Hyperliquid `metaAndAssetCtxs` → `[{universe}, [ctx…]]`, joined by index), every
+chart, card and alert ends up re-deriving the same math and they drift. Do the
+join **once** in a provider module and expose flat rows.
+
+The derivations worth centralizing, because they are the ones people get wrong:
+
+- **Index-joined metadata + context.** `universe[i]` pairs with `assetCtxs[i]`;
+  leverage/decimals come from one, price/OI/funding from the other.
+- **Open interest is denominated in the COIN.** Multiply by mark for USD.
+- **Funding is a per-interval decimal** (8h on HL). Annualize explicitly
+  (`rate * (8760/8) * 100`) and return **both** forms — consumers reach for APR
+  and silently mislabel the raw rate as one.
+- **Filter delisted markets** out of boards and totals.
+- **Missing numeric → `null`, never `NaN`.** A sparse context with no
+  `prevDayPx` must yield `change24hPct: null`, not a value that renders as
+  `NaN%`.
+
+Ship the board cuts (`gainers`/`losers`/`byVolume`/`byOpenInterest`/funding
+extremes) from the same joined rows so a leaderboard can never disagree with the
+market table. Test against **fixed fixtures**, asserting the arithmetic
+(10 coins @ $100 → `1000` OI USD; `0.0001` per 8h → `10.95%` APR) rather than
+live values.
+
+**Read lanes are not trade lanes — say so unprompted.** Hyperliquid `/info`
+gives markets, positions, fills and book; **placing a perp order is a separate
+action set** (`order`, `cancel`, `modify`, `updateLeverage`) EIP-712-signed to
+`/exchange`. An `/exchange` URL constant existing in a staking module does not
+mean orders are wired. When the owner asks "can we trade perps?", grep for the
+order-placement function and answer from that, not from the presence of a venue
+integration.
+
+### Perp order lanes (limit / market / leverage / brackets)
+
+When that answer is "no" and the owner asks for it, the trade lane is its own
+prepare-only module. Two things carry most of the risk:
+
+- **Venue precision is a correctness requirement, not tidiness.** Hyperliquid
+  rejects over-precise orders, and a rejected order is indistinguishable from a
+  missed fill at the moment it matters. Price obeys **both** a 5-significant-figure
+  cap and a `6 − szDecimals` decimal cap (tighter wins; integers are exempt);
+  size rounds to `szDecimals`. Round in exact decimal with `BigInt`, never through
+  a float, and **throw** when a size rounds to zero rather than sending it.
+- **There is no market order type.** A "market" order is an IOC limit priced
+  aggressively off mark (`mark * (1 ± bps/10_000)`), so it *requires* a live mark
+  price and reuses the house **100 bps** slippage ceiling.
+
+Leverage is bounded by the asset's `maxLeverage`, cross vs isolated is explicit
+(never a silent default that hides which balance is at risk), and above ~20x
+attach the liquidation distance — `100 / leverage` ≈ the adverse move that
+liquidates, before fees. Bracket protection legs must be **reduce-only and on the
+opposite side**; a non-reduce-only leg opens a *new* position on trigger.
+
+Wire shapes, the rounding table with observed values, asset-index resolution, the
+full guardrail list, and the fixture trap (asserting sig-figs with `szDecimals=5`
+actually exercises the decimal limit): `references/hyperliquid-perp-orders.md`.
+
+### Crossing into live execution (sign + submit)
+
+When the owner asks to **trade, not prepare**, the signing lane is its own
+provider — not a flag on the prepare module. Keep the prepare modules free of
+write exports and add one execution provider beside them.
+
+Three things carry the risk:
+
+- **Verify the signer against the venue's own known-answer vector, and PULL that
+  vector from the SDK source rather than recalling it.** An unverified signer
+  produces orders the venue silently rejects, which is indistinguishable from
+  "not trading". A first attempt here failed against a fixture reconstructed from
+  memory — the implementation was correct and the *expected value* was invented;
+  fetching the real `signing_test.py` fixture matched immediately.
+- **A transport `200` is not a fill.** Hyperliquid returns `status: "ok"` while
+  individual entries in `response.data.statuses[]` carry rejections. Surface the
+  venue's error and return **no order id** rather than inventing one.
+- **The key never appears in a returned object** — assert it with a
+  `JSON.stringify(result).includes(...)` test. The derived address is fine to
+  surface; the material is not.
+
+Give execution **its own provider id** and exempt exactly that id from the
+write-op denylist, so the exemption is one greppable line rather than a weakened
+predicate — and assert the boundary on a **structured** catalog field
+(`execution: "live"`), never a regex over free-text notes the catalog projection
+may not even expose.
+
+When a prepare-only project grows an exec lane, grep the docs for "never signs"
+and **scope** the claim (routing still never signs) instead of leaving a blanket
+promise that is now false in one module.
+
+Action-hash construction, the phantom-agent EIP-712 envelope, the msgpack
+key-order dependency, key resolution, and venue-verdict parsing:
+`references/hyperliquid-live-execution.md`.
+
+## Testing security guards that live in the transport
+
+Two traps make a security test **pass while the hole is open**:
+
+- **`fetch()` rewrites the `Host` header from the URL.** A DNS-rebinding test
+  written with `fetch(url, { headers: { Host: 'attacker.example' } })` silently
+  sends the loopback Host, gets `200`, and reports the guard broken — or worse,
+  reports it working when it is not. Use a raw `node:net` socket and write the
+  request line and headers verbatim.
+- **A spawned server hangs the runner.** Give the test an explicit
+  `{ timeout: N }`, spawn `detached: true` and kill the **process group**
+  (`process.kill(-proc.pid)`) — an orphan keeps the port and the next run blocks
+  on startup. And pass the server's **actual** env var names: a generic `PORT`
+  that the server reads as `ORACLE_DATA_PORT` starts it on its default port and
+  the readiness poll never succeeds, which reads as "server is broken."
+
+### `assert.throws` on an ASYNC function asserts nothing
+
+`assert.throws(() => asyncFn(...), /pattern/)` **always fails** — the call returns
+a promise rather than throwing, so the assertion is testing the wrong thing while
+appearing to cover the guard. Found live: a 0/0 unprotected-LP-exit guard whose
+implementation was correct the whole time, but whose test had never actually
+exercised it.
+
+```js
+// WRONG: the guard is never asserted; the rejection is unhandled
+assert.throws(() => lpPrepareDecrease({ amount0Min: "0", amount1Min: "0" }), /unprotected/);
+
+// RIGHT
+await assert.rejects(() => lpPrepareDecrease({ ... }), /unprotected/);
+```
+
+Grep the suite for `assert.throws` whose callee is `async` after adding any
+`await` to a guard path. A test that has never seen its guard fire is not
+coverage, and this shape hides that fact.
+
+### Two test files binding the same port collide under a concurrent runner
+
+`node --test` runs FILES in parallel. Two suites that each `spawn` a server on a
+hardcoded `PORT = 18801` pass individually and fail together — one process loses
+the bind, and its tests surface as `404`/`ECONNREFUSED` assertion failures that
+read exactly like a broken product route.
+
+**The tell: green in isolation, red in the full run.** That combination is almost
+never a product bug. Give every server-spawning test file a distinct port and
+comment why. Verify the same way you found it — run the file alone, then run the
+full suite, and require both green.
+
+## Risk coverage
+
+Do not call holder concentration bundle detection. Bundles require launch-block transaction clustering and common-funder evidence. Label each check `LIVE`, `STALE`, `UNKNOWN`, or `UNAVAILABLE`, include timestamps and limitations, and distinguish near-real-time polling from block-by-block surveillance.
+
+## Public data-plane HTTP hardening
+
+A self-hosted scanner runs on free public venue APIs, where the two dominant failures
+are rate limiting and one slow venue poisoning a whole health sweep. Fix both in the
+shared HTTP helper, not in thirty providers: bounded retry that honours `Retry-After`
+and **never retries a 4xx**, single-flight dedupe so N concurrent identical GETs cost
+one upstream call, and `mapLimit` fan-out (~8) instead of `Promise.all` across every
+provider. Dedupe is a request collapser, not a cache — no TTL, so quotes and balances
+never go stale. Prove dedupe by counting upstream calls, never by timing.
+
+Full rules, the key-shape that keeps keyed and keyless callers separate, and the
+pitfalls: `references/public-data-plane-hardening.md`.
+
+## Verification
+
+- Unit-test route mismatch, stale quote, slippage overflow, exact approval, deadline, simulation revert, ambiguous mint ABI, unsupported fee paths, OpenSea non-RH chain rejection, max-price sweep block, and mint/sweep simulation failure.
+- Run a live read-only quote against a real pool.
+- Run one live atomic round-trip `eth_call` against a known executable pool and one failing token fixture.
+- Verify the merged server boots, not only frontend build/tests. Confirm cwd/port is the worktree under test, not a stale sibling checkout.
+- For public unsigned BFFs beside an executor, run them as a separate loopback-only service with execution envs explicitly off; verify the public/unsigned headers and prove executor routes 404/405 on that public port before claiming the self-custody boundary is enforced.
+- When another coequal agent intentionally lands a private execution plane in the same repo, do not delete those files as "pollution" by default. Reconcile on a fresh branch from the integrated base, preserve both lanes, and enforce the custody boundary instead: public Oracle/BFF/UI code must not import private signer/executor/Solana execution modules.
+- Browser-test wallet discovery, chain switching, quote, approval, swap, local mint, OpenSea load, and sweep UI states without broadcasting funds during QA.
+- Before merge-ready claims for NFT scope: inventory sibling branches and confirm mint + floor-sweep paths exist in the tree being pushed.
+
+## Pitfalls
+
+- Paper endpoints presented as execution.
+- Any-wallet sessions accidentally inheriting operator/admin powers.
+- Trusting a named explorer contract without checking constructor-bound factory/WETH.
+- Testing only the buy route and calling the token safe.
+- Client-supplied market objects or calldata reaching the signer unchanged.
+- Treating a successful quote as proof that token transfers or sells work.
+- Claiming OpenSea mint/sweep shipped because a scanner shows NFT collections or a sibling branch is nearby.
+- Merging mint-only OpenSea hardening and calling floor sweep done.
+- Putting marketplace API keys in `VITE_*` or frontend bundles.
+- Accepting marketplace fulfillment steps without per-step simulation and spend caps.
+- Calling an SSE `ready` handshake proof that a real factory launch was observed.
+- Calling browser-only limit or TP/SL monitoring unattended execution.
+- Claiming a DexScreener graph is working because the iframe shell loads when no candles render.
+- Broad wallet-trigger selectors such as `[aria-expanded="true"] span` rotating provider/balance text when connected-state markup wraps content in a span. Give the chevron a semantic class, rotate only that class, and regression-test the selector plus the open state.
+- Testing only logged-out wallet UI. Connected/open states may render different wrappers, balances, provider names, and transforms; inspect computed styles for every child and verify the deployed asset hash when PWA caching or concurrent branches are possible.
+- Capping only `tx.value` and calling the executor "capped." Gas is separate money — unbounded gasLimit/fee drains the wallet outside the ETH caps. See the executor security-review taxonomy.
+- **Shipping a guard with zero call sites.** A green test file proves the guard
+  works, not that anything invokes it — `validateNftMintGasWar` had a full suite
+  and was enforced on nothing. Grep for real callers, excluding the definition
+  and barrel re-exports (the re-export is what makes a naive grep look healthy).
+- Assuming a mint signature instead of discovering it from bytecode. ERC-721 does
+  not standardize creation; BAYC uses `mintApe(uint256)`. Return `unsupported`
+  rather than encoding a guess, and report ambiguity when several selectors match
+  instead of silently taking the first.
+- Encoding `mint(address,uint256)` as a quantity mint. The uint256 may be a
+  **tokenId** — this is why the mint gate rule rejects the signature outright.
+  Its presence in an inherited selector table is not validation of the shape.
+- Reading gas-war tips from `eth_maxPriorityFeePerGas`. It is one node's opinion
+  with no distribution; a contested inclusion needs `eth_feeHistory` reward
+  percentiles, medianed across blocks so one whale cannot skew the read.
+- Treating `maxFeePerGas` as spend. It is a refundable ceiling — padding it is
+  free protection against a climbing basefee, and being stingy strands you on a
+  spike. The tip is the real money.
+- Clamping a bid below the observed market and returning it anyway. Report
+  `viable: false` with the arithmetic; paying gas to lose is worse than not
+  bidding. And never let a clamp produce `maxFeePerGas < maxPriorityFeePerGas`.
+- Arming an unattended action from a truthy or near-miss value. Exact string only
+  — `"Execute"`, `"exec"`, `true`, `1`, `"arm"` must all downgrade, and an
+  unrecognized mode should downgrade *with a reason* rather than error, since an
+  error teaches the caller to retry with looser input.
+- Deciding arming at fire time rather than creation (a trigger that can
+  self-upgrade), accepting a grant for a different contract, or skipping the
+  fire-time spend re-check — gas moved between arming and firing, which is the
+  entire premise.
+- Treating an unreadable sale flag as open. A probe that timed out is `unknown`;
+  firing on it is guessing in the most expensive direction.
+- Trusting scanner-window membership as an allowlist for money movement, or reading a kill switch once at handler entry and broadcasting on that stale value seconds later.
+- Local smoke against a stale server: a leftover `node server.js` from an earlier session can own the smoke port and serve OLD routes — new endpoints return 404/`Cannot POST` and look unimplemented. Before diagnosing "route missing", check the background process log for `EADDRINUSE` and `lsof -t -i :<port>` for a stale PID; kill it and re-smoke.
+- Wiring an autonomous SELL and reusing the BUY executor: the buy gate hard-rejects `side !== "buy"` and asserts `value > 0`, so a sell (value==0) needs a PARALLEL sell-only gate — do not weaken the buy gate. And the exit policy's recorded `wallet` (user session) must be realigned to the EXECUTOR address that actually holds the token, or the balance-read/prepared-sender/signer disagree and the swap fails.
+- A fresh executor wallet with ZERO router allowance makes `prepareSwap` return `kind:"approval"` (not `"swap"`), so the first stop-loss trigger THROWS the sell gate — pre-approve token→router once before expecting an autonomous sell.
+- Verifying rhbot `.env` flags via `dotenv`: rhbot uses its own `loadEnvFile` (dotenv isn't a dep), so `pm2 env` shows nothing and inline `node -e` `import("dotenv")` fails — write the check script INTO the repo and import `./server/env.js`'s loader instead.
+- Reading `getAmountsOut` at `amounts[0]` (the INPUT) instead of the last element; on a single hop the wrong number is obvious, on a multi-hop path it silently passes.
+- Advertising `quote`/`prepare` support for a chain whose router was never verified on that chain, or bulk-adding routers to raise a coverage number.
+- Verifying a third-party venue by **codesize alone**. Bytecode proves deployment, not identity — the canonical QuoterV2 address has code on Base but cannot price its pairs. Probe behaviour.
+- Bending a V2 adapter to cover V3 (or vice versa). Different pricing call, different selector, explicit fee tier — a mis-encoded swap reverts or routes through the wrong pool.
+- Defaulting to one fee tier because 0.3% is common; liquidity concentrates in a tier that varies by pair and chain.
+- Ranking routes on headline `amountOut`. Gas is part of the price and the winner flips with trade size.
+- Treating a missing gas figure as zero — it silently promotes the worst route to first place.
+- Quoting a spread between two routes that measure cost differently (it compares third vs fourth while reading as first vs second).
+- Letting one dead aggregator fail the whole comparison, or spending a timeout on a provider already known to return 410. Check `sunset`/`deprecation` response headers before assuming rate-limit.
+- Guessing a USD gas cost from gas UNITS with no gas price; report `null` instead.
+- Folding bridge duration into the score rather than surfacing it beside the price.
+- Ranking a winner and leaving the user to rebuild it by hand. Hand the winner to
+  prepare so the compared route and the signed route are provably the same.
+- Returning one "prepared" blob for both an unsigned transaction and an EIP-712 order.
+  A CoW order is signed and submitted, never broadcast; conflating them fails at signing
+  time, after the user already approved tokens.
+- Deriving the approval spender from the destination. CoW pulls funds through the
+  **vault relayer**, so approving the settlement contract yields an order that silently
+  never fills.
+- Preparing against the comparison's quote. Re-quote inside prepare and report drift —
+  a minimum computed from a stale quote is not a minimum.
+- Passing the quote placeholder (`0x…dEaD`) into a prepare call. It is correct for
+  anonymous quoting and a category error for preparing; some venues reject it and some
+  build a transaction for an address nobody controls.
+- Reporting a venue's on-chain precondition as a bare HTTP 400. "Not enough allowance"
+  is a fixable ordering constraint (approve first), not a router bug — and the real
+  message is usually on `err.body`, not `err.message`.
+- Silently substituting a different venue when the winner cannot be prepared, or
+  presenting a caller-forced non-winner as the best route.
+- A preparer wired to a **key-gated** source, so on a keyless machine it is unreachable
+  dead code that still looks like coverage. Stub the keys in the test, and pin the
+  quote-only set so a source becoming unpreparable fails CI instead of a user.
+- Returning a bare transaction object for a bridge because *this* route happened to be
+  single-tx. Another source returns an approval plus a deposit, and the caller who
+  learned the object shape signs one of them and believes the bridge is done.
+- Reporting only the signing chain for a bridge, or passing along a transaction whose
+  `chainId` is not the origin — the wallet then prompts on a network the user cannot
+  reason about.
+- Letting the user infer that an origin-chain confirmation means funds arrived. It does
+  not, and the silence is what causes double-sends. State non-atomicity and the ETA.
+- Stating a fact only in an error **message** that a caller must act on (the fallback
+  venue, the failure class) while leaving the structured field `undefined`. Agents
+  consume fields, not prose.
+- Emitting a field named after the private codebase (`madSlippage`) in a payload handed
+  to users. Secret scans, portability tests, and docs tests all miss it because it lives
+  in the output shape — and a hard rename breaks artifacts already in flight, so keep a
+  dual-read window on consumers.
+- `rg -c 'pattern' -r ''` to count occurrences: `-r` is *replace*, so it rewrites the
+  output you were trying to read. Use `rg -n` to list, `rg -o pattern | wc -l` to count.
+- Calling a Solana prepare verified because it returned base64. Jupiter builds a
+  swap for a placeholder pubkey that dies at `simulateTransaction: failed to sanitize
+  accounts offsets correctly` — only a simulate against a real funded pubkey proves it.
+- Hardcoding a probe wallet in an E2E script. Parameterize it; a placeholder default
+  turns a wallet-less machine red and reads as a code regression.
+- Checking a `maxPrice` cap on the venue's *response*. The cap must reject before any
+  network call — assert it with a call counter, not just a thrown error.
+- Passing a listing's `tokenAddress` (the ATA) where the mint belongs, or letting
+  lamports and decimal SOL both reach the caller. Normalize units at the provider edge.
+- Treating HYPE staking as 18 decimals. It is **8** — `1.5 HYPE = 150000000` — and an
+  over-precise amount must be rejected, not silently rounded.
+- Preparing a HyperCore `cWithdraw` without reading `delegatorSummary` first. It only
+  moves the **undelegated** bucket, so "unstake" is two actions (undelegate, then
+  withdraw) and the user pays a round trip to discover that.
+- Describing a HyperCore action POST to `/exchange` as a broadcast. It is a signed
+  action submission; there is no chain transaction and no hash.
+- A `/sign/i` export-name guard that fails on a legitimate `HL_SIGNATURE_CHAIN_ID`
+  constant. Use an explicit allowlist rather than a negative lookahead.
+- Using a real personal burner address as a test fixture. It trips the pre-publish
+  private-term scan and leaks an address into a public repo even when it holds dust —
+  use public constants (wrapped-SOL / USDC mints, `0x0…abc`).
+- Collapsing "provider needs a user key that isn't configured" into `fail` in an E2E
+  report. Report `keyed` as its own state or a correctly-configured machine looks broken.
+- Retrying a 4xx, or ignoring `Retry-After` in favour of your own shorter backoff.
+- Deduping a POST or a request with a body, or sharing a deduped response between a
+  keyed and a keyless caller.
+- Unbounded `Promise.all` across every provider in a health sweep — it trips public
+  rate limits and the resulting 429s read as an outage.
+- Keying a single-flight dedupe on whether an auth header is **present** rather than
+  on its value. Two callers with different API keys collapse into one upstream request
+  and the second receives data fetched with the first one's credential. Hash the full
+  identity header set into the key.
+- Replaying a non-idempotent request after a **transport-level** failure. A status code
+  means the server refused it (safe to retry); no status means the server may have
+  already applied it and only the response was lost. Restrict statusless retries to
+  `GET/HEAD/OPTIONS/PUT/DELETE`.
+- Reporting a Bitcoin balance from ONE derived address. One key controls `1…`, `3…`,
+  `bc1q…`, and `bc1p…` simultaneously — funds at the wrong script type read as a
+  missing key, a bad key, or an empty wallet, and none of those is the actual problem.
+- Signing an input whose script type differs from the address the funds sit at. Same
+  key, different `scriptPubKey`, invalid signature. Consolidate first.
+- Sweeping an address with many small UTXOs. Ordinal-range outputs (`<= 1000 sats`)
+  can be burned as fee; refuse auto-selection and make the user name the UTXO.
+- `Number(wei)` on a `uint64` EIP-712 field. Above 2^53 the wallet is handed a
+  different amount than the one prepared and displayed — silently, and in the field
+  the user is looking at. Keep it exact as a string above `MAX_SAFE_INTEGER`.
+- `Number()` on any user-supplied price or amount: it accepts `"1e2"` → 100, `"0x10"`
+  → 16, and `Infinity`. Require a plain decimal.
+- **A cap accepted as a JS `number` above 2^53 rounds UP, widening itself.**
+  `9007199254740995` arrives as `...996`, so a guard built from it authorizes one
+  more unit than the user asked for — the cap silently becomes larger than the
+  intended one, which is the wrong direction to fail. Reject `!Number.isSafeInteger`
+  on any bound and tell the caller to pass a decimal string or `BigInt`. Distinct
+  from the `Number(wei)` pitfall above: that one corrupts the *displayed* amount,
+  this one corrupts the *limit* protecting it.
+- Gating an approval guard on `approve(address,uint256)` alone. **Every other
+  allowance-granting entrypoint then skips it entirely** — `increaseAllowance`,
+  SafeERC20 `forceApprove`/`safeApprove`/`safeIncreaseAllowance`, Permit2
+  `approve`/`permit`, and EIP-2612 / DAI-style `permit` all grant or raise spend
+  rights. Guard the full set, and **derive each selector with
+  `keccak_256(signature)` in code rather than transcribing hex**: closing this exact
+  finding I hand-wrote the `forceApprove` and `safeApprove` selectors and *both were
+  wrong*, so the fix would have shipped the hole it claimed to close while passing a
+  test that asserted the same recalled constants. Real values: `0x095ea7b3` approve,
+  `0x39509351` increaseAllowance, `0x61f49ed6` forceApprove, `0xeb5625d9` safeApprove,
+  `0xf9255c1f` safeIncreaseAllowance, `0x87517c45` Permit2 approve, `0xd505accf`
+  EIP-2612 permit, `0x8fcbaf0c` DAI permit. Assert the negative arm too —
+  `transfer` (`0xa9059cbb`), `transferFrom`, and `decreaseAllowance` must NOT match.
+  Same rule for event topics, EIP-712 type hashes, and domain separators: a wrong
+  security constant fails **silently**, unlike a wrong test constant.
+  **After expanding recognition, expand the decoder in the same diff** — Grok
+  round 7 caught the half-fix (recognition without decode).
+- Recording a spend cap on the response instead of enforcing it before the call. A
+  `maxPriceSol` that is echoed but never compared is worse than no cap — the caller
+  believes a ceiling held.
+- Accepting a **pre-signed** transaction payload from a marketplace API in a "prepare"
+  path. Take only the documented unsigned field; a compromised or impersonated
+  endpoint otherwise laundres arbitrary bytes past every local check.
+- Forwarding an env API key to a caller-controlled `baseUrl`. That is credential
+  exfiltration and SSRF dressed as configuration — allowlist the hosts and require an
+  explicit opt-out env var for local mocks.
+- Passing a provider flag that widens a bound you already enforced (Jupiter
+  `dynamicSlippage: true` voids the bps ceiling while the returned guard still
+  advertises the capped number). Force it off and reject the request.
+- A destination allowlist that fails **open** when empty. "No allowlist configured"
+  must refuse, not permit everything — the permissive branch fires exactly when the
+  operator has configured the least.
+- Gating a real market submission on a caller-supplied boolean alone. A steered agent
+  can set `execute: true`; what it cannot set is the credential's presence or the
+  autonomous opt-in.
+- **Enforcing a bound only when its field happens to be present.** Two separate
+  CRITICALs came from this one shape: a transfer guard checked `amount` and
+  `maxAmount` each `!= null`, so a guard omitting **both** skipped every check and
+  authorized `MaxUint256 - 1`; and a session grant compared `maxGasWei` only when the
+  *request* volunteered `gasWei`, so omitting the field satisfied a grant whose
+  ceiling would have rejected it. If a guard bounds something, **require** the field —
+  a capless guard is not a guard, and the caller who omits it is exactly the caller you
+  are guarding against. Also reject internally incoherent guards (`amount > maxAmount`).
+- A spend cap that is stripped as an "internal" field and then never compared to
+  anything (Satflow `maxSats`). Enforce it against the venue's **settled** price on the
+  response, not just the caller's requested price, and withhold the artifact when the
+  price is unknown.
+- Authenticating a guard with nothing at the **signer** boundary. If the party
+  supplying the calldata also supplies the object vouching for it, the bound is
+  decorative — `quoteAmountOut: "1"` makes any floor trivially satisfiable.
+  HMAC the guard with the same attestation secret the route/vault attestations
+  use, and verify **before** the bounds checks when signing/broadcasting.
+  **Round 7 + Sol merge:** quote/prepare may attach an *unsigned* bound (self-host
+  UX without a forced secret). `enforceTxPolicy` must pass `requireSigned: true`
+  so missing secret / missing signature fails closed at sign and broadcast.
+  Catching a missing secret and returning `null` *at that gate* was the Opus
+  CRITICAL (forged 1-wei floor on 100 WETH). Never document unauthenticated
+  bounds as acceptable for sign/broadcast. Mint a secret at `oracle-init --apply`
+  into `~/.config/oracle/exec.env`. Pin a dummy secret in the npm test script
+  under `ORACLE_TEST_ISOLATE_SECRETS=1`. See `references/oracle-round7-guard-parity.md`.
+- **Recognising a selector without decoding it bricks legitimate usage.** Round 7
+  Grok DO_NOT_SHIP: allowance selectors were added to the *recognition* list so
+  the guard demanded a bound approval, then `decodeApproveCalldata` only knew
+  `approve()` — so `increaseAllowance` / SafeERC20 / EIP-2612 / Permit2 became
+  unsignable. Recognition and decoding must cover the **same** set; an
+  unknown-but-recognised selector fails closed (`recognised but not decodable`),
+  never silently passes. Slot map: approve/increaseAllowance = w0/w1; SafeERC20
+  and EIP-2612/Permit2 = w1/w2; DAI permit allowed bool at w4.
+- **Every time-bounded guard must call the shared `fresh-window` helper.**
+  `Number(nowMs) > Number(expiresAtMs)` is false for NaN/null/"later"/{}, so a
+  broken clock turns a short TTL permanent. Round 7: approval was the only guard
+  still hand-rolled and accepted timeless + NaN clocks. Grep for `fresh-window`
+  after any new guard.
+- **Do not exempt approval-shaped calldata from the destination allowlist.**
+  `!approvalLike` lets any unreviewed contract with an allowance selector skip
+  the strongest drain control. `assertApprovalGuard` binds the *spender*, not
+  `to`. The token (or Permit2) being called is a destination like any other.
+- **`key present = armed` is trading posture, not withdrawal posture.** A signing
+  lane that only checks `prepared.action` is truthy will sign `withdraw3` /
+  `usdSend` / `approveAgent`. Allowlist prepare-emitted types only
+  (`order`/`cancel`/`updateLeverage`/`updateIsolatedMargin` for HL).
+- **Never construct `new Wallet(raw)` on unvalidated key material.** ethers embeds
+  the full value in `invalid BytesLike value (… value="…")` — a file-read oracle
+  via `keyFile`. Validate `^0x?[0-9a-fA-F]{64}$` first; rethrow naming the source,
+  never the contents.
+- A write-op denylist built from an anchored **name** regex. It blocked `sendFoo` while
+  letting `txBroadcast`, `doSend`, `rawSign`, `orderSubmit` and `forceExecute` straight
+  through, and blocked nothing real because every money-moving op was named `prepare*`.
+  The actual boundary is the catalog: a provider may only be asked for an op it
+  declares. Keep substring matching as defence in depth, not as the control.
+- Treating loopback bind as a security boundary for a local data server. Any page the
+  operator visits can reach `127.0.0.1:<port>`, and DNS rebinding reaches it under an
+  attacker hostname — both arriving with the server's own API keys. Validate the `Host`
+  header is a loopback name and reject a cross-origin `Origin`.
+- `bad-txns-inputs-missingorspent` on a Bitcoin input you already verified is
+  confirmed and unspent. That error is almost always **txid byte order**, not
+  availability — a helper that pre-reverses the txid before handing it to a signer
+  that also reverses internally produces a reference to a nonexistent outpoint.
+  Decode your own signed tx, compare the input txid to the real one, and pass the
+  display-order hex string rather than pre-reversed bytes.
+- Building a reveal against an **unconfirmed** commit, or re-deriving the prepare
+  with different parameters than were funded. Assert `contentSha256` and
+  `commitAddress` against the funded values before signing the reveal.
+- Debugging an `Invalid Schnorr signature` on an ordinals reveal as a signing bug.
+  Check `vsize` first: ~111 vbytes for a multi-KB payload proves the **key path** was
+  taken and the envelope never entered the witness. The commit must be built on a
+  **NUMS** internal key (`p2tr(undefined, {script: leaf})`) so script-path is the only
+  way to spend.
+- Setting `allowUnknownOutputs` on an ordinals reveal and not `allowUnknownInputs`.
+  `@scure/btc-signer` classifies the envelope leaf as `unknown` and throws
+  `Finalize: Unknown tapLeafScript` — two different flags, and only one of them is the
+  one you need.
+- Encoding the ord **body tag** with a push helper. `encodePush([0])` emits `01 00`;
+  the separator is a bare `OP_0` (`0x00`). The wrong form still confirms *and indexes*,
+  producing an inscription with `content size: 0 bytes` — the most expensive kind of
+  success. Diff your envelope bytes against a live indexed inscription instead of
+  reasoning from the spec.
+- Verifying an inscription against your **local** file. The sha256 matched perfectly
+  through two dead attempts; only reassembling the body from the on-chain witness (and
+  a third-party indexer's view) can see an envelope-structure failure.
+- Attributing a **precise** operator symptom to indexer lag. "Blank" is vague; "content
+  size 0 bytes" is a measurement that proves the indexer parsed the envelope and found
+  no body — which waiting never fixes. `GET /content/<id>` returning 404 on a confirmed
+  tx settles it in one command.
+- Trusting your own envelope parser's `body bytes: 0` as evidence the content is gone.
+  Validate the parser against a known-good inscription first — searching for a
+  zero-length push instead of a 1-byte zero push reports an intact inscription as empty.
+- Verifying a `package.json` change without regenerating `package-lock.json`. A bin/
+  export drift guard fails on the lockfile, and the message reads like a missing file
+  rather than stale metadata.
+- Fixing a **class-level** finding only on the files named in the repro. "Every keyed
+  provider follows this pattern" means enumerate the full set by grepping the *shape*,
+  fix all of them behind a shared helper, and add a table-driven test that iterates the
+  membership — otherwise a later provider that forgets the helper ships the hole again.
+- Editing the repo while an audit reads it. Test counts and failures stop being
+  attributable to any commit, and hours go into phantoms. Freeze the tree or have each
+  auditor work from its own `git archive <sha>` snapshot.
+- Rolling a "looks correct on reading" fix into an all-clear. `NOT VERIFIED` is a third
+  verdict beside `HOLDS`/`BROKEN` and must survive into the summary.
+- A secret resolver with a `~/.config` fallback left active under test. The maintainer's
+  suite silently disagrees with CI and with every contributor; add a test-only isolation
+  switch and set it in the `test` script.
+- Writing a DNS-rebinding test with `fetch()` and a manual `Host` header. `fetch`
+  rewrites `Host` from the URL, so the test never sends the attack. Use a raw socket.
+- Spawning a server in a test without `{ timeout }`, without `detached: true` +
+  process-group kill, or with env var names the server does not actually read — each
+  produces a hang or a false "server is broken".
+- `assert.throws` on an **async** function. It never catches the rejection, so the
+  guard it claims to cover has never once fired in the suite while the test file
+  reads as coverage. Use `await assert.rejects`, and grep for the shape after adding
+  any `await` to a guard path.
+- Two test files hardcoding the **same port**. `node --test` runs files in parallel,
+  so one loses the bind and its tests fail as `404`/`ECONNREFUSED` that look like
+  broken product routes. Green-alone plus red-in-full-suite is almost never a product
+  bug — give each server-spawning file its own port.
+- Triaging a **wall** of unrelated test failures as separate bugs. When they share one
+  syscall, one errno, or one port, they are one cause: ~40 failures across a dozen
+  files, all at `writeFileSync`/`appendFileSync`/`mkdtemp` with `UNKNOWN: unknown
+  error, write` and `errno: -122`, were a single exhausted `/tmp` tmpfs quota
+  (`-122` is `EDQUOT`, which Node surfaces as a useless `UNKNOWN`). Probe with a
+  one-line `mkdtempSync`+`writeFileSync`, check `df -h /tmp` and `mount | grep /tmp`
+  for `usrquota`, and prove any reclaimed file is dead (`lsof` empty AND `tar -tf`
+  shows a finished artifact) before deleting.
+- Reading a venue's parallel-array response per surface instead of joining once.
+  Open interest denominated in the coin, funding as a per-interval decimal, and
+  index-paired metadata each get re-derived slightly differently and the chart stops
+  matching the card. Missing numerics must become `null`, never `NaN`.
+- Claiming a venue supports trading because a read integration and an `/exchange` URL
+  constant exist. Order placement is a separate signed action set — grep for the
+  placement function before answering "can we trade here?".
+- Asserting a signing implementation against a known-answer vector **recalled from
+  memory**. A plausible-but-invented fixture fails, and the failure looks like a bug
+  in correct code — costing a debugging detour into msgpack and byte order. Fetch the
+  vector from the SDK's own test file, then compare.
+- Naming an internal module after something that collides with the owner's **brand**
+  (`hl-media` when "HL Media" is a separate company). It reads as that product in
+  every log line, catalog listing and doc. Rename to what it actually is
+  (`hl-markets`), and do the rename with `git mv` plus a longest-first ordered
+  substring pass so `hlMediaHealth`/`hl-media.mjs`/`"hl-media"` all migrate without
+  double-replacing.
+- A `new URL()`-based host guard rejecting a test's mock hostname. `https://mock.0x` is
+  genuinely unparseable (invalid TLD) while `https://mock.1inch` parses — fix the
+  fixture rather than loosening the guard, and treat a blank `baseUrl` override as
+  absent rather than throwing.