hood-alerts 0.1.0 → 0.2.0

package/README.md

@@ -1,369 +1,313 @@
 # hood-alerts
 
-**Telegram and Discord alert bots for [Robinhood Chain](https://docs.robinhood.com/chain/) memecoins (chain ID 4663): new launches, graduations, whale trades. Hosted service, free and premium tier.**
+[![license](https://img.shields.io/badge/license-MIT-93a1af?labelColor=101418)](./LICENSE)
 
-Chain watching is not this package's job. [`hoodchain`](https://github.com/nirholas/robinhood-chain-sdk) already has the launchpad watchers, the sequencer firehose and the Uniswap v3 quote path, and [`hoodkit`](https://github.com/nirholas/robinhood-chain-kit) has the swap decoding. hood-alerts is everything above them, which is where an alert product actually lives:
+The alert layer for **Robinhood Chain** (chain ID 4663): Telegram and Discord bots, plus optional
+X (Twitter) auto-posting, backed by one shared detection engine that watches launches, graduations,
+whale trades, Stock Token price moves, on-chain premium/discount arbitrage, holder milestones, and
+liquidity-pull rug warnings. Free tier plus x402 USDG premium.
 
-- a normalized **event taxonomy** over both launchpads, with honest USD values,
-- a schema-validated **rule engine** whose rules are data a subscriber can edit from chat,
-- **delivery adapters** that get escaping and rate limiting right on both platforms,
-- the **bot** command surface,
-- an enforced **tier policy**,
-- and a **hosted service** that survives a restart mid-stream without double-sending or silently skipping a block.
+## What it detects
 
-Docs: **https://nirholas.github.io/hood-alerts/**
+| Detector | Topic | Source |
+| --- | --- | --- |
+| New token launch | `launches` (`launches:noxa`, `launches:odyssey`) | NOXA (instant Uniswap v3 pool) and The Odyssey (bonding curve) |
+| Bonding-curve graduation | `graduations` | Odyssey curve fills and migrates to a locked Uniswap v3 pool |
+| Whale trades | `whales`, or per-token `token:0x…` | Odyssey curve trades and Uniswap v3 swaps, chain-wide, threshold in USD |
+| Stock Token price moves | `stock:SYMBOL` | Chainlink feed, rolling window, signed percent change |
+| On-chain premium/discount (the arb signal) | `premiums` (premium tier) | DEX mid vs Chainlink feed, hysteresis ladder at 1/2/3/5/10/20/50% |
+| Holder milestones | per-token `token:0x…` | Blockscout `token_holders_count`, crossing 10 through 100,000 |
+| Liquidity-pull rug warning | `rugs` (premium tier), or per-token `token:0x…` | tracked pool's quote-side (USDG/WETH) reserves dropping sharply |
 
-## The thing most memecoin alert bots get wrong
+Every event is deduped per fingerprint before it reaches a subscriber, routed through a
+premium/quiet-hours/digest gate, and rendered as a platform-native card (Telegram HTML, Discord
+embed, a compact X post, or a structured console log line) with links back to the chain explorer
+and `three.ws/markets/robinhood`.
 
-Robinhood Chain has two memecoin launchpads and they do not have the same lifecycle. Treating them as one product produces alerts that are simply false.
+## Quickstart (self-host)
 
-| | NOXA (`fun.noxa.fi/robinhood`) | The Odyssey (`theodyssey.fun`) |
-|---|---|---|
-| Model | Instant launcher | pump.fun-style bonding curve with virtual reserves |
-| At launch | Deploys the ERC-20, creates a Uniswap v3 pool, seeds single-sided liquidity and locks the LP NFT, all in one transaction | Opens a curve. No pool exists yet |
-| Trading | Normal Uniswap v3 swaps from block one | On the curve until it fills |
-| Graduation | **Never happens. There is no curve to fill** | `PoolCompleted` + `PoolMigrated` when the curve fills and liquidity moves to a locked Uniswap v3 pool |
-| Emits | `launch`, `whale_trade` | `launch`, `curve_trade`, `graduation`, `whale_trade` |
-
-A "NOXA graduation" alert would describe an event that does not exist on chain. hood-alerts encodes that asymmetry in the types and in the rule schema, so an impossible rule is **rejected at validation time** instead of being accepted and never firing:
-
-```ts
-import { safeParseRule } from 'hood-alerts/rules'
-
-const result = safeParseRule({ id: 'nope', kinds: ['graduation'], launchpads: ['noxa'] })
-console.log(result.success)
-// false: "this combination can never fire: NOXA is an instant launcher with no
-// bonding curve, so it emits no curve_trade and no graduation"
+```sh
+npm install
+npm run dev     # tsx watch, console transport only if no bot tokens are set
 ```
 
-## Event taxonomy
-
-Every event carries a stable id (`kind:txHash:logIndex`), the token, the actor, the block, the transaction hash, a USD value and explorer links.
+With zero environment variables the engine still runs: detectors connect to the public Robinhood
+Chain RPC, alerts print as structured JSON log lines (the console transport), and `/healthz` comes
+up on `:8080`. That is the self-host smoke-test mode. Copy `.env.example` to `.env` and fill in a
+Telegram and/or Discord bot token to go live on those platforms; see `.env.example` for every
+variable, defaults, and what each detector threshold controls.
 
-| Kind | Source | Launchpads | `usdValue` is | Extra fields |
-|---|---|---|---|---|
-| `launch` | NOXA `TokenLaunched`, Odyssey `TokenCreated` | both | the deployer's initial buy (NOXA), or `null` (Odyssey: the curve holds the liquidity) | `pool`, `pairToken`, `initialBuyAmount`, `positionId`, `instantListing` |
-| `curve_trade` | Odyssey `Traded` on a bonding-curve factory | Odyssey only | the native-ETH leg, priced through live WETH/USDG liquidity | `side`, `tokenAmount`, `quoteAmountWei`, `feeWei`, `virtualQuoteWei`, `virtualTokenAmount`, `priceEth` |
-| `graduation` | Odyssey `PoolMigrated` | Odyssey only | the quote side used to seed the migrated pool | `pool`, `positionId`, `liquidity`, `tokenUsed`, `quoteUsed` |
-| `whale_trade` | Uniswap v3 `Swap` on a tracked memecoin pool | both | the swap's quote leg | `pool`, `quoteToken`, `quoteSymbol`, `side`, `tokenAmount`, `quoteAmount`, `price`, `feeTier` |
-
-### USD values are measured, never assumed
-
-There is no hardcoded price anywhere in this package.
-
-- **USDG legs are the unit of account.** USDG is the chain's fully reserved dollar stablecoin at 6 decimals, so a USDG leg is its own USD value.
-- **ETH legs are priced through the chain's own liquidity.** `hoodchain`'s `quoteSwap` is asked for the real output of selling 1 WETH into USDG across every fee tier and two-hop route, cached for 30 seconds and coalesced so a burst of events makes one quote.
-- **Anything else is `null`.** A memecoin/memecoin pool has no honest USD value from chain data alone, so the event says so and a `minUsd` rule does not match it. Unknown is never treated as zero (which would satisfy every `maxUsd` filter) or as infinity.
-
-### Evidence: every source decoded against mainnet
+```sh
+npm run build   # tsc -> dist/
+npm start       # node dist/src/index.js
+```
 
-`npm run verify:chain` runs the whole read path against the public RPC with no credentials, no database and no writes. Replaying the launchpads' first 1.44 million blocks:
+### Creating the bots
+
+- **Telegram**: message [@BotFather](https://t.me/BotFather), `/newbot`, paste the token into
+  `HOOD_ALERTS_TELEGRAM_TOKEN`. The bot registers its command list on startup.
+- **Discord**: create an application at the
+  [Developer Portal](https://discord.com/developers/applications), add a bot, copy the bot token
+  into `HOOD_ALERTS_DISCORD_TOKEN` and the application id into `HOOD_ALERTS_DISCORD_APP_ID`. Slash
+  commands register (guild-visible immediately) on startup.
+
+Leaving either token unset disables that transport; the engine and the console transport keep
+running regardless.
+
+### X (Twitter)
+
+X is a broadcast-only transport: there is no inbound bot, so you cannot DM the account and get a
+reply the way you can with Telegram or Discord. What it auto-posts is fixed at startup by
+`HOOD_ALERTS_X_TOPICS` (default `launches,graduations,whales`) instead of `watch`/`unwatch`
+commands, parsed through the same topic resolver the bots use. Pick exactly **one** of two modes
+via `HOOD_ALERTS_X_MODE`; see `.env.example` for the full variable list.
+
+**`official`**: the real X API v2, `POST /2/tweets`, signed with your own developer app's OAuth1
+user-context credentials. This is the normal, ToS-compliant path, and it costs money: X gates
+posting behind a paid API tier. Check current pricing at
+[developer.x.com/en/portal/products/buy](https://developer.x.com/en/portal/products/buy) before
+relying on it; it has changed before and can change again.
+
+Setup: create an app at the [developer portal](https://developer.x.com/en/portal), generate a
+consumer key/secret (`HOOD_ALERTS_X_API_KEY` / `HOOD_ALERTS_X_API_SECRET`), then generate an
+access token/secret with **read and write** permissions (`HOOD_ALERTS_X_ACCESS_TOKEN` /
+`HOOD_ALERTS_X_ACCESS_SECRET`). All four are required; hood-alerts signs every request itself with
+Node's built-in `crypto` (HMAC-SHA1 per RFC 5849), no extra dependency.
+
+**`xactions`**: posts through a self-hosted [XActions](https://github.com/nirholas/XActions)
+instance instead of the official API: browser-automation driving your own X session cookie. Free,
+no developer account, no paid tier. This is **not** the official API and carries real ToS risk;
+run it on an account you are prepared to lose if X acts on that. Point `HOOD_ALERTS_XACTIONS_URL`
+at your running instance and `HOOD_ALERTS_XACTIONS_TOKEN` at its bearer token. Posting is
+async/job-queued: hood-alerts treats a 2xx from `POST {url}/api/posting/tweet` as "accepted", not
+"delivered", and logs that delivery is not confirmed synchronously (the real xactions API responds
+`{ operationId, status: "queued" }`, not a tweet id).
+
+Both modes fail loudly: a configured mode missing any required credential logs a warning and
+disables the X transport (Telegram, Discord, and the console transport keep running) instead of
+crashing the process. Every X post is compacted to fit X's 280-character limit: title, the single
+most important line, and the first link; only the text portion truncates, never the URL. Digests
+(too many alerts to post individually) post the single most significant event plus a `(+N more)`
+count, and log the full summarized batch, so nothing is silently dropped from the record even
+though it is dropped from the post itself.
+
+## Bot commands
+
+Both bots share one command router (`src/commands/commands.ts`), so the UX is identical modulo
+native slash-command vs `/command arg` syntax:
 
 ```
-$ FROM_BLOCK=61688 TO_BLOCK=1500000 npm run verify:chain
-
-chain 4663, head block 15010850
-ETH/USD from live Uniswap v3 liquidity: $1905.26
-
-scanning blocks 61688 to 1500000 (1438313 blocks)
-
-NOXA launches        2621 events  217029ms
-  launch       ? 0x6399E2Bd8af62C0ac13f55613C3469b67332a6Fd $266.74 block 61869
-  launch       HUSK 0x57EB9C9153cfE0277F91Ff8B8604C2D3006a9196 $9.53 block 61987
-  launch       JOHN 0x1E963A1539681d0B877570F8bdC000cbE8404fC4 $95.26 block 62204
-Odyssey launches        4 events  757ms
-  launch       ROBIN 0xfB4729659eeF22Bfc1c2B680F6F873f8147aaaab unpriced block 983265
-Odyssey curve trades  110 events  2482ms
-  curve_trade  ROBIN 0xfB4729659eeF22Bfc1c2B680F6F873f8147aaaab $18.67 block 983265
-Odyssey graduations     1 events  344ms
-  graduation   ROBIN 0xfB4729659eeF22Bfc1c2B680F6F873f8147aaaab $7618.47 block 1048638
-Whale trades         4045 events  83886ms
-  whale_trade  CHEEMS 0xdaA213A0Bd8B048D6022e2c46df877E8A204072b $190.46 block 1439024
-
-pools discovered and registered for whale watching: 2622
+watch <what> [threshold]
+  launches            every new token (add noxa/odyssey to filter)
+  graduations         Odyssey curves migrating to Uniswap v3
+  whales [usd]        trades >= usd, chain-wide (default 5000)
+  premiums [pct]      Stock Token DEX premium/discount vs Chainlink (premium tier)
+  rugs [pct]          liquidity-pull rug warnings (premium tier)
+  <TICKER>            a Stock Token: price moves + premium crossings (e.g. TSLA)
+  <0x address>        a memecoin: whale trades, graduation, holders, liquidity
+
+unwatch <what|all>    stop watching
+list                  your subscriptions
+threshold <what> <n>  change a subscription's threshold
+digest on|off [min]   batch alerts into digests (default 60 min)
+quiet <from> <to>     quiet hours in UTC (e.g. quiet 22 7); quiet off
+premium               premium status + how to upgrade
+help                  this message
 ```
 
-Read the ROBIN token across those four lines and the taxonomy proves itself: a curve opens (`launch`, unpriced, because a curve holds no pool), trades on the curve (`curve_trade`, priced through the ETH leg), then fills and migrates (`graduation`, $7,618.47 of liquidity seeded). NOXA tokens never appear in the middle two rows, because they cannot. The first NOXA launch has no `symbol()` and renders as `?` rather than dropping the alert.
+In a group chat or server, `watch`, `unwatch`, `threshold`, `digest`, and `quiet` are restricted to
+admins; `list`, `premium`, and `help` are open to everyone.
 
-The whale row also shows the pool set working: 2,622 pools were discovered from launchpad activity during the same scan, and the whale watcher queried exactly those.
+## Free vs premium
 
-## Install
-
-```bash
-npm install hood-alerts hoodchain hoodkit viem
-```
+| | Free | Premium |
+| --- | --- | --- |
+| Subscriptions | 3 | Unlimited |
+| Delivery | Batched to at most one immediate alert per 60s; extras fold into a digest | Real-time, subject only to quiet hours / digest mode you set |
+| `premiums` (Stock Token arb signal) | Not available | Included |
+| `rugs` (liquidity-pull warning) | Not available | Included |
+| Price | Free | `HOOD_ALERTS_PREMIUM_PRICE_USDG` (default 5) USDG for `HOOD_ALERTS_PREMIUM_DAYS` (default 30) days |
 
-Node >= 20. `hoodchain`, `hoodkit` and `viem` are peer dependencies.
+Premium is paid on Robinhood Chain via **x402** using [`hood402`](../hood402) (USDG,
+EIP-3009 `transferWithAuthorization`, chain 4663). The bot's `premium` command hands back a
+`POST /premium/activate?platform=...&chat=...` URL: the first request gets a 402 challenge with
+payment instructions, and any x402 client (`hood402`, `x402-fetch`) that can sign a USDG
+authorization completes the purchase. The entitlement never activates before the transfer settles
+on-chain, so a signature alone buys nothing.
 
-## Quickstart: the event pipeline
+Purchases stay disabled (`503` + setup instructions) until the instance sets `HOOD402_PAY_TO` and
+either `HOOD402_FACILITATOR_URL` (delegates verification and settlement, no gas key on this box) or
+`HOOD402_SETTLER_KEY` (this instance broadcasts the settlement itself). See `.env.example` for both
+modes.
 
-```ts
-import { createHoodClient } from 'hoodchain'
-import {
-  createEventSources,
-  createMemoryPoolRegistry,
-  createPriceOracle,
-  createTokenMetaReader,
-} from 'hood-alerts/events'
-
-const hood = createHoodClient()
-const sources = createEventSources({
-  client: hood,
-  oracle: createPriceOracle(hood),
-  tokens: createTokenMetaReader(hood),
-  registry: createMemoryPoolRegistry(),
-})
-
-const head = await hood.public.getBlockNumber()
-for (const source of sources) {
-  for (const event of await source.poll(head - 5_000n, head - 2n)) {
-    console.log(event.kind, event.symbol, event.usdValue, event.explorer.tx)
-  }
-}
-```
+## HTTP API
 
-## Quickstart: rules and delivery
+The same process that runs the bots serves a small Hono app on `PORT` (default 8080):
 
-```ts
-import { matchRules, parseRule } from 'hood-alerts/rules'
-import { createTelegramNotifier, renderAlert } from 'hood-alerts/notifiers'
+| Endpoint | Method | Returns |
+| --- | --- | --- |
+| `/` | GET | service metadata and endpoint list |
+| `/healthz` | GET | uptime, last detector event time, per-event-type counts, whether premium purchases are enabled |
+| `/premium/status?platform=telegram\|discord\|console\|x&chat=<id>` | GET | `{ tier: 'free' \| 'premium', expiresAt }` for that chat |
+| `/premium/activate?platform=...&chat=...` | POST | the x402 purchase flow: 402 challenge, then 200 + entitlement once payment settles |
 
-const rules = [
-  parseRule({ id: 'whales', name: 'Whale buys over $25k', kinds: ['whale_trade'], minUsd: 25_000, side: 'buy' }),
-  parseRule({ id: 'grads', kinds: ['graduation'], launchpads: ['odyssey'] }),
-]
+## Example: reading the alert engine's pure logic directly
 
-const telegram = createTelegramNotifier({ botToken: process.env.TELEGRAM_BOT_TOKEN as string })
+`src/engine/gate.ts` and `src/engine/topics.ts` have no I/O and are safe to import standalone, for
+example to preview how a threshold will gate before wiring a subscription:
 
-for (const { rule } of await matchRules(rules, event)) {
-  const result = await telegram.send('-1001234567890', renderAlert(event, { footer: `rule: ${rule.id}` }))
-  if (!result.ok) console.error(result.error, 'retryable:', result.retryable)
+```ts
+import { gate } from './src/engine/gate.js'
+import { resolveWatchTarget, parseTopic } from './src/engine/topics.js'
+
+const target = resolveWatchTarget('whales') // { ok: true, topic: 'whales' }
+if (target.ok) {
+  const topic = parseTopic(target.topic) // { kind: 'whales' }
+  const decision = gate(
+    { premium: false, digest: false, quietStart: null, quietEnd: null, lastDeliveredAt: null, deliveredLastMinute: 0 },
+    Math.floor(Date.now() / 1000),
+  )
+  console.log(topic, decision) // { kind: 'whales' } { action: 'deliver' }
 }
 ```
 
-To see the exact bytes each platform would receive, with real chain events and no credentials:
-
-```bash
-npm run demo:notify
-```
-
-## Rules are data
-
-A rule is a JSON document validated by a [Zod](https://zod.dev) schema, so it can be stored per subscriber, edited from a chat command, exported and diffed. The schema is the single source of truth: the bot, the service and the tier policy all validate through it.
-
-| Field | Type | Filter |
-|---|---|---|
-| `id` | slug | Stable id, unique per subscription |
-| `name` | string | Label shown in `/rules` |
-| `enabled` | boolean | Off without deleting |
-| `kinds` | `launch` / `curve_trade` / `graduation` / `whale_trade` | Which events |
-| `launchpads` | `noxa` / `odyssey` | Which launchpad |
-| `minUsd`, `maxUsd` | number | USD value band. An unpriced event never matches |
-| `minLiquidityUsd`, `maxLiquidityUsd` | number | Deepest known pool's USD reserves |
-| `tokens` | address[] | Watchlist. Non-empty means only these tokens |
-| `deployers` | address[] | Only these actors |
-| `excludeDeployers` | address[] | Never these actors |
-| `side` | `buy` / `sell` / `any` | Trade direction (trades only) |
-| `reputation.minPriorLaunches` | int | Deployer's prior launches as of the event's block |
-| `reputation.maxPriorLaunches` | int | Rejects serial deployers |
-| `reputation.maxRuggedLaunches` | int | Rejects deployers with drained pools |
-| `reputation.requireLpLocked` | boolean | LP NFT held by the launchpad locker |
-| `rateLimit.maxPerHour` | int | Cap per rolling hour |
-| `rateLimit.minIntervalSeconds` | int | Minimum gap between alerts |
-
-Evaluation is lazy and ordered: cheap in-memory filters run before anything that costs an RPC call, so a rule that rejects an event on its kind never triggers a pool balance read. With thousands of subscriptions that is the difference between keeping up with the chain and not.
-
-### Deployer reputation is derived on chain
-
-Nothing is scraped, self-reported or scored by a model.
-
-- **Prior launches**: `TokenLaunched` logs on the NOXA factory indexed by `deployer`, plus `TokenCreated` on the three Odyssey factories indexed by `creator`. Both queries are topic-selective, so the RPC serves the full chain history in one call each. Counted relative to the event's own block, so replaying a historical range gives the same answer twice.
-- **LP locked**: `NonfungiblePositionManager.ownerOf(positionId)` equals the NOXA locker contract. That is the launchpad's own permanent-lock mechanism, read directly rather than trusted from a UI badge.
-- **Drained**: a prior launch whose pool quote reserve is now below the rug threshold (default $50). This is a **heuristic** and is labelled as one everywhere it appears: a token that never traded and a token whose liquidity was pulled both end up with an empty pool. Pair it with `minPriorLaunches` for a meaningful signal.
-
-```bash
-npx tsx examples/deployer-reputation.ts 0xYourDeployerAddress
-```
-
-## Escaping, because that is how alert bots die
-
-Memecoin names are adversarial input by nature. A token called `WHO_LET_THE` italicises half a MarkdownV2 message; a token called `<b>RUG` injects markup under HTML parse mode. Either way Telegram answers `400 Bad Request: can't parse entities` and the alert is lost.
-
-Each context gets its own escaper and its own tests, because the rules are not symmetric even within one platform:
-
-| Context | Escaped |
-|---|---|
-| Telegram MarkdownV2 text | all 18 of ``_*[]()~`>#+-=\|{}.!`` |
-| MarkdownV2 link URL | only `)` and `\` (escaping the full set corrupts query strings) |
-| MarkdownV2 code span | only `` ` `` and `\` |
-| Telegram HTML text | `&`, `<`, `>` |
-| Telegram HTML attribute | the above plus `"` |
-| Discord embeds | ``\*_~`\|>[]()`` |
+A threshold typed after the target (`watch whales 10000`) is parsed separately by
+`Commands.watch()`, not by `resolveWatchTarget` itself.
 
-Telegram delivery defaults to HTML: three special characters instead of eighteen makes a malformed-entity 400 far less likely on hostile input. Truncation is surrogate-pair aware, so a long emoji-bearing name is cut cleanly instead of ending in a replacement character.
+The package does not ship a public library entry point today (`main`/`bin` both point at the CLI
+process in `src/index.ts`, which starts the bots and the HTTP server and does not export anything);
+importing from `src/` as above works in this checkout but is not a published API contract.
 
-## Rate limiting, per each platform's actual contract
+## Configuration
 
-The two platforms do not work the same way, and treating them the same is how a bot gets throttled into silence.
+Every variable, its default, and what it controls: [`.env.example`](.env.example). Highlights:
 
-- **Telegram** answers `429` with `parameters.retry_after` in **whole seconds** and expects exactly that wait. hood-alerts honours it (falling back to the `Retry-After` header, then to exponential backoff), caps the total wait at `maxWaitMs` so one throttled chat cannot stall the dispatch loop, and treats `400`/`403` as permanent so a deleted chat or a blocked bot stops being retried forever.
-- **Discord** publishes a per-route bucket on every response (`X-RateLimit-Remaining`, `X-RateLimit-Reset-After` in **fractional seconds**). The correct behaviour is to not send once a bucket is exhausted rather than to send and spend a 429, so the adapter waits before the request. A 429 that still slips through carries `retry_after` as a float, and `X-RateLimit-Global` is applied to every route rather than only the one that hit it.
+- `HOOD_ALERTS_RPC_URL` — custom RPC; defaults to viem's public `robinhood` chain RPC.
+- `HOOD_ALERTS_DB` — SQLite path (subscriptions, entitlements, dedup, delivery log). `:memory:`
+  works for tests.
+- `HOOD_ALERTS_WHALE_FLOOR_USD` / `HOOD_ALERTS_WHALE_DEFAULT_USD` — engine-side emission floor vs.
+  the default per-subscription threshold.
+- `HOOD_ALERTS_PRICE_WINDOW_S` / `HOOD_ALERTS_PRICE_DEFAULT_PCT` — Chainlink rolling-window move
+  detector.
+- `HOOD_ALERTS_PREMIUM_POLL_S` / `HOOD_ALERTS_PREMIUM_DEFAULT_PCT` — Stock Token arb poll cadence
+  and default ladder entry.
+- `HOOD_ALERTS_RUG_DEFAULT_PCT` — default liquidity-pull threshold (percent of quote reserves).
 
-## The service
-
-One process: poll the chain, match rules, queue deliveries, drain the queue, serve health and metrics.
+## Development
 
-```bash
-cp .env.example .env      # nothing is required for a dry run
+```sh
 npm install
-npm run build
-DRY_RUN=1 npm start
+npm run typecheck   # tsc --noEmit, strict + exactOptionalPropertyTypes
+npm test            # vitest: dedup/rate-limit gate, digest batching, topic parsing and
+                     # matching, event fingerprinting/TTL, alert card rendering, config
+                     # loading, the command router, and the subscriber/entitlement/delivery
+                     # repositories — all offline, no chain or bot credentials required
+npm run build       # tsc -> dist/
 ```
 
-```bash
-docker build -t hood-alerts .
-docker run --rm -p 8080:8080 -v hood-alerts-data:/app/data \
-  -e TELEGRAM_BOT_TOKEN=123456789:AA... hood-alerts
-```
+The `whale-classify` and `detectors` suites run against **real captured mainnet event streams** in
+`tests/fixtures/` (real Uniswap v3 swaps, Odyssey bonding-curve trades, and Chainlink prices).
+Refresh them any time with `npm run capture-fixtures`, which re-reads live chain 4663.
 
-| Endpoint | Purpose |
-|---|---|
-| `GET /health` | Liveness, head block, last poll, configured platforms |
-| `GET /ready` | 503 when the poll loop has stalled, so an orchestrator restarts a process that is alive but no longer ingesting |
-| `GET /metrics` | Prometheus text: subscriptions, outbox by status, deliveries per hour, tracked pools, per-source cursor and lag |
-| `POST /discord/interactions` | Discord slash commands (Ed25519 verified) |
+`npm run test:live` and `npm run probe` exercise the live detector set against real Robinhood Chain
+RPC and, for `probe`, the console transport; they need real network access and are not part of the
+offline unit suite above. `npm run grant-premium` comps or inspects a premium entitlement directly
+in the database (handy for testing premium delivery before a payment rail is wired).
 
-### Surviving a restart mid-stream
+### Local sibling packages
 
-This is the part that is easy to get wrong and expensive to get wrong: an alert bot that double-sends is spam, and one that skips a range misses the launch its subscribers paid for.
+`hood402`, `hoodkit`, and `hoodchain` are consumed as `file:` dependencies of the other Robinhood
+Chain repos in this workspace (`../hood402`, `../hoodkit`, `../robinhood-chain-sdk`) rather than
+their published npm versions, so a change to any of them is picked up on the next `npm install`
+here. A `file:` link keeps each sibling's own `viem` copy, so a patch-level skew (e.g. `2.55.2`
+here vs `2.55.1` in `hood402`) makes viem's structural `Chain` / `WalletClient` types diverge across
+the two copies. `src/premium/paywall.ts` bridges that boundary explicitly (casting the local viem
+clients to `hood402`'s `HoodBroadcaster` / `HoodConfirmer`), so the build stays green across a patch
+skew; the runtime objects are the same correct viem clients. Once the siblings are on npm and a
+single `viem` resolves, the cast is a no-op.
 
-1. **Never double-send.** Every potential delivery has a deterministic primary key, `eventId|subscriptionId|ruleId`, and the event id comes from the transaction hash and log index. Re-processing a block range regenerates identical keys, so the second pass inserts nothing.
-2. **Never silently skip.** The block cursor advances only after every event in a chunk has been enqueued and committed. A crash mid-chunk leaves the cursor at the start of that chunk, so the range is re-read. A failed RPC call leaves it untouched for the same reason.
-3. **Never lose an enqueued alert.** Queued rows live in an outbox until they are delivered or dead-lettered. On startup, rows left in `sending` (a crash mid-flight) return to `pending` and are retried.
+## Deploy
 
-The one honest caveat: if the process dies after the platform accepted a message but before the row was marked `sent`, that alert goes out twice. Neither the Telegram nor the Discord send API takes a client-supplied idempotency key, so that window cannot be closed from here. Everything outside it is exactly once.
+hood-alerts is one long-running process (engine + HTTP server + both bots), so run it as a service
+with a warm instance, not a job.
 
-All three properties are tested, including a simulated crash part way through writing a batch:
+Because the sibling packages are `file:` links, the Docker build context is the **parent
+`robinhood/` directory** so they resolve:
 
-```
-✓ cursor semantics > leaves the cursor untouched when a source throws, so nothing is skipped
-✓ dedupe > enqueues an event once even when the same range is processed twice
-✓ crash recovery > re-processes only the unfinished range after a crash mid-batch
-✓ crash recovery > returns rows abandoned in flight to the queue on restart
-```
+```sh
+# from robinhood/ (the parent of hood-alerts/)
+docker build -f hood-alerts/Dockerfile -t hood-alerts .
 
-## Bot command reference
-
-The same router serves Telegram (long polling, so no public URL, TLS certificate or inbound firewall rule is needed) and Discord (slash commands over the HTTP interactions endpoint). Every command answers bad input with a specific, actionable message.
-
-| Command | What it does |
-|---|---|
-| `/start`, `/help` | Every command, plus the launchpad lifecycle explanation |
-| `/subscribe [target]` | Send alerts here with a starter rule set. On Discord the target may be a webhook URL or a channel id; it defaults to the current channel |
-| `/unsubscribe [id]` | Stop a subscription. Lists them when there is more than one |
-| `/rules` | Every rule on every subscription, with its filters |
-| `/rule add {json}` | Add a rule. Validation errors come back as the field that failed |
-| `/rule rm\|on\|off <id>` | Remove, enable or disable a rule |
-| `/threshold <rule> <usd>` | Set a rule's minimum USD value |
-| `/watch <token> [rule]` | Add a token to a rule's watchlist |
-| `/unwatch <token> [rule]` | Remove one |
-| `/tier` | Your tier, its limits, and where the entitlement came from |
-| `/status` | Subscriptions, rule counts, alerts used this hour |
-| `/link [address] [signature]` | Link the wallet that pays. Send it bare to get the message to sign |
-| `/upgrade` | How to go premium on this deployment |
-
-Register the Discord slash commands with:
-
-```bash
-DISCORD_APPLICATION_ID=... DISCORD_BOT_TOKEN=... npm run register:discord
+gcloud run deploy hood-alerts \
+  --image=REGION-docker.pkg.dev/PROJECT/repo/hood-alerts:latest \
+  --min-instances=1 --no-cpu-throttling --port=8080 \
+  --set-env-vars=HOOD_ALERTS_TELEGRAM_TOKEN=…,HOOD_ALERTS_DISCORD_TOKEN=…,HOOD_ALERTS_DISCORD_APP_ID=…
 ```
 
-[INTEGRATION.md](./INTEGRATION.md) has the full Telegram and Discord setup, including the interactions endpoint.
+Mount a volume at `/data` (the default `HOOD_ALERTS_DB` path) so subscriptions, entitlements, and
+the delivery log survive restarts. The container answers `GET /healthz`; `SIGTERM` flushes pending
+digests before exit. Once the siblings are published to npm, switch the `file:` specs in
+`package.json` and the image builds from the `hood-alerts/` directory alone. Full self-host and
+premium-wiring guide: the `docs/` site.
 
-## Tiers are enforced, not advertised
+## Docs site (GitHub Pages)
 
-Every limit maps to a real cost the service pays, and the check lives in exactly one place (`createEntitlementGate`). The bot asks it before accepting a subscription or a rule; the dispatcher asks it before queuing a delivery. Nothing else reads the policy table, so the two cannot disagree about who is premium.
+`docs/` is a static, hand-built site (no framework, no build step): open `docs/index.html` locally,
+or serve it from GitHub Pages. Its landing page renders a **live** premium/discount feed client-side
+straight from the public RPC (real Chainlink feeds vs real DEX pools, no server). One-time setup:
+Settings -> Pages -> Deploy from a branch -> `main` -> `/docs`.
 
-| | Free | Premium |
-|---|---|---|
-| Subscriptions | 1 | 10 |
-| Rules per subscription | 3 | 50 |
-| Filters per rule | 3 | 24 |
-| Watchlist size | 5 | 500 |
-| Alerts per hour | 30 | 2,000 |
-| Delivery delay | 60s | none |
-| Liquidity and reputation filters | no | yes |
-| Event kinds | `launch`, `graduation`, `whale_trade` | all four, including the `curve_trade` firehose |
-
-The delivery delay is enforced in the outbox (the row carries `not_before`), so it survives a restart instead of being a `setTimeout` a crash erases.
-
-### Entitlements: what actually ships
+## Architecture notes
 
-`EntitlementProvider` is a one-method interface and two implementations ship. **Both work; neither is a placeholder.**
+- **Console transport is not a fallback, it's the smoke-test mode.** With no bot tokens configured
+  the engine still ingests real chain events and logs every alert/digest as structured JSON; that
+  is how a fresh self-host proves the pipeline works before touching Telegram or Discord.
+- **The entitlement never activates before settlement.** `PremiumPaywall.activate()` calls
+  `hood402`'s verify-then-settle flow and only writes the entitlement row after the on-chain
+  transfer succeeds.
+- **Digest buffering is in-memory by design.** A restart loses at most one pending batch, never a
+  subscription (subscriptions and the delivery log are in SQLite); `AlertEngine.stop()` flushes
+  every buffered digest before shutdown.
+- **Auto-tracked pools expire; watched pools do not.** A NOXA/Odyssey launch or graduation starts a
+  24h rug-watch on its pool automatically; a user `watch 0x…` keeps that pool's liquidity monitor
+  running indefinitely.
 
-1. **`createStaticEntitlementProvider` is the documented default.** Premium comes from `PREMIUM_SUBSCRIBERS` (or `ALL_PREMIUM=1` for a private deployment). No dependencies, works offline, and is what a self-hoster running the bot for their own community wants.
-2. **`createUsdgEntitlementProvider` is a working on-chain rail.** It reads USDG `Transfer` logs from a subscriber's linked wallet to the operator's `USDG_RECEIVER` and accrues subscription time from those real payments: each payment buys `floor(amount / price)` periods, starting from whenever the current entitlement would have lapsed, so renewing early extends rather than overwrites. No facilitator, no card processor, no third-party service. USDG is the chain's own dollar and the ledger is the chain.
+## Repo layout
 
-Wallet linking is signature-verified (EIP-191 `personal_sign` over a server-issued, single-use nonce), so nobody inherits a paying subscriber's entitlement by pasting their address.
-
-```env
-ENTITLEMENTS=both
-USDG_RECEIVER=0xYourReceivingAddress
-PREMIUM_PRICE_USDG=25
-PREMIUM_PERIOD_DAYS=30
-PAYMENTS_FROM_BLOCK=12000000
+```
+src/index.ts                 CLI entry: wires config, db, engine, detectors, transports, HTTP server
+src/config.ts                environment -> validated Config
+src/server.ts                Hono app: /, /healthz, /premium/status, /premium/activate
+src/engine/                  event types, dedup fingerprinting, topic parsing/matching, the
+                              digest buffer, the delivery gate, and the live detector set
+src/engine/detectors/        pure per-signal detectors (price move, premium ladder, holder
+                              milestones, liquidity pull, whale classification) plus live.ts,
+                              which wires them to hoodchain/hoodkit streams
+src/db/                      better-sqlite3 repositories: subscribers, entitlements, deliveries
+src/premium/paywall.ts       the hood402 x402 purchase flow
+src/transports/              Telegram (grammY), Discord (discord.js), X (OAuth1 API v2 or self-
+                              hosted xactions), and console transports
+src/commands/commands.ts     the shared, platform-neutral command router
+src/format/cards.ts          alert -> platform-neutral card -> per-platform rendering
+tests/                       vitest unit suite + tests/fixtures (real captured chain events) +
+                             tests/live (opt-in on-chain reads)
+scripts/                     capture-fixtures, live-probe, grant-premium (see Development above)
+docs/                        static GitHub Pages site with a live client-side premium feed
+Dockerfile                   one-container build (engine + both bots), build from robinhood/
 ```
 
-A deliberate non-choice: hood-alerts does **not** wire the sibling `hood402` x402 rail. x402 prices a single HTTP request, and a subscription is not a request. Bolting one onto the other would have produced a payment integration that demos but does not work. The USDG provider is the honest version of the same idea, and `EntitlementProvider` is one method wide for anyone who wants a different one.
-
-## API
-
-| Export | From | What it is |
-|---|---|---|
-| `createEventSources` | `hood-alerts/events` | Every source for a mainnet client. Throws on testnet, where neither launchpad exists |
-| `createNoxaLaunchSource`, `createOdysseyLaunchSource`, `createOdysseyCurveTradeSource`, `createOdysseyGraduationSource`, `createWhaleTradeSource` | `hood-alerts/events` | The sources individually |
-| `createPriceOracle`, `createStaticPriceOracle` | `hood-alerts/events` | USD valuation from live liquidity, or a fixed rate |
-| `createLiquidityReader` | `hood-alerts/events` | Pool reserves in USD, cached |
-| `createMemoryPoolRegistry` | `hood-alerts/events` | The tracked memecoin pool set |
-| `fetchLogRange` | `hood-alerts/events` | `eth_getLogs` that bisects on the result cap and retries rate limits |
-| `parseRule`, `safeParseRule`, `ruleSchema`, `subscriptionSchema` | `hood-alerts/rules` | Rule validation |
-| `evaluateRule`, `matchRules` | `hood-alerts/rules` | The engine |
-| `checkRateLimit`, `createMemoryRateLimitStore` | `hood-alerts/rules` | Per-rule rate limiting |
-| `createRpcReputationProvider` | `hood-alerts/rules` | On-chain deployer history |
-| `renderAlert` | `hood-alerts/notifiers` | One event rendered for both platforms |
-| `createTelegramNotifier`, `createTelegramClient` | `hood-alerts/notifiers` | Telegram Bot API |
-| `createDiscordWebhookNotifier`, `createDiscordBotNotifier` | `hood-alerts/notifiers` | Discord, both delivery paths |
-| `createCaptureNotifier` | `hood-alerts/notifiers` | Records instead of sending. Backs `DRY_RUN=1` |
-| `escapeMarkdownV2`, `escapeHtml`, `escapeDiscordMarkdown` | `hood-alerts/notifiers` | The escapers, individually testable |
-| `createCommandRouter`, `COMMANDS` | `hood-alerts/bot` | The shared command surface |
-| `createTelegramBot` | `hood-alerts/bot` | Long-polling front end |
-| `createDiscordInteractionHandler`, `registerDiscordCommands`, `verifyDiscordSignature` | `hood-alerts/bot` | Slash commands and Ed25519 verification |
-| `TIER_POLICIES`, `createEntitlementGate` | `hood-alerts/tiers` | The policy table and the one chokepoint |
-| `createStaticEntitlementProvider`, `createUsdgEntitlementProvider` | `hood-alerts/tiers` | Who is premium |
-| `AlertStore` | `hood-alerts/service` | SQLite state: subscriptions, outbox, cursors, pools, links |
-| `createDispatcher` | `hood-alerts/service` | `pollOnce` and `flushOnce` |
-| `createService`, `loadConfig` | `hood-alerts/service` | The whole thing, wired |
-
-## Limits and caveats
-
-- **Mainnet only.** NOXA and The Odyssey are deployed on chain 4663. Building sources against testnet throws rather than reporting an empty chain as "no launches".
-- **Whale trades cover a tracked pool set, not every pool on the chain.** A topic-only Uniswap v3 `Swap` query overflows the public RPC's 10,000-log result cap in under 2,000 blocks, so "watch everything" is not something the endpoint can serve. The pool set is assembled from launchpad activity (NOXA pools at launch, Odyssey pools at graduation), capped by `WHALE_POOL_LIMIT` newest-first, with every subscriber's watchlist tokens pinned on top of the cap. A pool the service has never seen a launch for is not watched.
-- **A fresh database starts `INITIAL_LOOKBACK_BLOCKS` behind the head.** Deleting the SQLite file loses subscriptions and replays that window. Mount it on a volume.
-- **Liquidity is total pool reserves, not tradeable depth.** For concentrated Uniswap v3 positions the reserve inside the active tick can be far smaller. Read `minLiquidityUsd` as "how much is in there", not "how much I can sell into".
-- **The rug figure is a heuristic**, defined precisely above. It is evidence, not a verdict.
-- **Rate-limit quota is consumed at enqueue, not at send.** An alert that is queued and then dead-lettered still counted against the hour. Counting at send time would let one block's events blow through every cap before the first delivery.
-- **The public RPC throttles bursts.** Above a few hundred tracked pools, set `ROBINHOOD_RPC_URL` to a dedicated endpoint.
-
-## Development
+## Notes
 
-```bash
-npm install
-npm run typecheck
-npm test               # 219 tests
-npm run build
-npm run verify:chain   # against the real RPC, no credentials
-```
+- **Stock Tokens.** Stock Tokens are tokenized debt securities (issuer: Robinhood Assets (Jersey)
+  Ltd) and may not be offered, sold, or delivered to US persons (additional limits: Canada, UK,
+  Switzerland). hood-alerts only ever displays price/premium data derived from public Chainlink
+  feeds and DEX pools; it never facilitates acquiring a Stock Token.
+- Liquidity-pull alerts are an early warning, not proof of a rug: always check the pool before
+  acting on one.
+- Not affiliated with Robinhood Markets, Inc.
 
 ## License
 
-Proprietary, all rights reserved. See [LICENSE](./LICENSE).
+MIT. See [LICENSE](./LICENSE).
+
+Built by [nirholas](https://x.com/nichxbt) · [three.ws](https://three.ws)