robinhood-chain-sdk 0.10.0 → 0.12.0

package/README.md

@@ -251,9 +251,11 @@ const { events, has_more, next_before, coverage } = await client.lpEvents({ toke
 for (const ev of events) {
   if (ev.provider_is_token_deployer) console.warn("deployer pulled liquidity:", ev.tx_hash, ev.dex, ev.token_amount_raw);
 }
-console.log(coverage.adds_persisted); // false — always
+console.log(coverage.events); // ["remove"] — the default request is removals only
 ```
 
+Since 2026-09-23 `action: "add" | "pool_created" | "all"` opts into liquidity adds (kept 7 days) and pool creations, and every row carries the depth fields `tick_lower` / `tick_upper`, `liquidity_delta`, `in_range`, `active_liquidity_delta`, `active_share` (v3/v4), `share_of_reserves` (v2) and `material` — null where the pool state was unknown and on older rows.
+
 > **Removals ONLY.** Liquidity adds are not persisted (v4 adds share the topic and are dropped at decode; v2/v3 `Mint` is not subscribed), so every row is `event: "remove"` and an empty page means "no removals seen", never "no liquidity activity" — the `coverage` block spells this out. Amounts are **raw uint256 decimal strings** (`liquidity`, `amount0` / `amount1`, plus pre-resolved `token_amount_raw` / `quote_token` / `quote_amount_raw`) — do not `Number()` them; v4 rows carry `liquidity` only because the pool manager emits no token amounts. Filters: `token`, `pool` (v2/v3 address or v4 bytes32 poolId), `provider`, `dex`. Data since 2026-08-05.
 
 ## Token intelligence — `client.tokens`
@@ -583,7 +585,7 @@ await client.kol.firstTouchSubscriptions.update(subscription.id, { filters: {} }
 
 ## Streaming — `client.stream` (PRO+)
 
-Managed WebSocket with token fetch on every (re)connect, auto-reconnect with backoff, heartbeat liveness, and typed events. Stream tokens **never expire** (since 2026-08-27) — there is no refresh timer; `client.stream.getToken()` returns the same token every call (`expires_at` / `next_refresh_at` are always `null`), and `getToken({ rotate: true })` replaces it (the old one keeps working for 60 s). Nine RHC channels:
+Managed WebSocket with token fetch on every (re)connect, auto-reconnect with backoff, heartbeat liveness, and typed events. Stream tokens **never expire** (since 2026-08-27) — there is no refresh timer; `client.stream.getToken()` returns the same token every call (`expires_at` / `next_refresh_at` are always `null`), and `getToken({ rotate: true })` replaces it (the old one keeps working for 60 s). Fourteen RHC channels:
 
 | Channel | Emits | Tier | Scope |
 |---|---|---|---|
@@ -595,8 +597,32 @@ Managed WebSocket with token fetch on every (re)connect, auto-reconnect with bac
 | `rhc:price_alert:events` | `rhc:price_alert:dip`, `rhc:price_alert:recovery` | PRO+ | user-scoped; event-driven off each trade (a few seconds), not sub-second |
 | `rhc:kol:coordination` | `rhc:kol:coordination` | PRO+ | user-scoped — only **your** rules' fires |
 | `rhc:kol:first_touches` | `rhc:kol:first_touch` | PRO+ | broadcast — ULTRA gates only the first-touch *subscription CRUD*, not this channel |
-| `rhc:token_locks` | `rhc:token_lock` | PRO+ | broadcast — a token lock / vesting contract created on chain |
+| `rhc:token_locks` | `rhc:token_lock` (+ `rhc:token_unlock_upcoming`, `rhc:token_unlock_available` with `filters.lifecycle: true`) | PRO+ | broadcast — a token lock / vesting contract created on chain; opt-in unlock-schedule events (claims / cancels are not observable on RHC) |
 | `rhc:token_prices` | `rhc:token_price` | PRO+ | **address-scoped** — `filters.addresses` required (25 / 100 / 250 per connection); one `snapshot: true` frame per address, then ≤ 1 tick per address per 250 ms with `quality` fresh / stale / unreliable + reason (`RhcTokenPriceTick`); no `seq` / `id` |
+| `rhc:lp_events` | `rhc:lp_event` | **ULTRA+** | broadcast — liquidity `add` / `remove` / `pool_created` on tracked Uniswap v2/v3/v4 pools with `in_range`, `active_share`, `share_of_reserves`, `material` (`RhcLpStreamEvent`); filters `RhcLpEventsFilters`; durable resume |
+| `rhc:token_candles` | `rhc:candle_closed`, `rhc:candle_revised` (+ `rhc:candle_update` with `filters.updates: true`) | PRO+ | scoped — live 1-minute candles for `filters.addresses` (`RhcCandleClosedEvent` / `RhcCandleUpdateEvent`); durable resume |
+| `rhc:token_risk` | `rhc:risk_verdict_changed` (+ `rhc:risk_verdict` snapshot) | PRO+ | scoped — risk-verdict changes for `filters.addresses` (`RhcRiskVerdictChangedEvent`); score HIGHER = SAFER |
+| `rhc:wallet_scores` | `rhc:deployer_tier_changed` | PRO+ | scoped — deployer tier changes for `filters.wallets` (0x deployers, `RhcDeployerTierChangedEvent`) |
+
+**Liquidity events and lock schedule (server 2026-09-23).** `rhc:lp_events` frames carry raw `amount0` / `amount1` strings (null on v4), the position range and, for v3/v4, `in_range` / `active_liquidity_delta` / `active_share` — a share of liquidity at the current price, not of TVL (an out-of-range removal is `active_share: 0`); v2 carries `share_of_reserves`; `material: true` = a removal of ≥ 25 %. When the pool's tick was not known the active fields are `null` with `active_share_reason: "pool_state_unknown"` — never guessed. `provider` is usually the router / position manager. No USD field. On `rhc:token_locks`, `filters.lifecycle: true` adds `rhc:token_unlock_upcoming` (within 24 h) and `rhc:token_unlock_available` (passed within 30 min — **claimable per the schedule, not claimed**; `withdrawals_tracked: false`).
+
+```ts
+const lp = client.stream.connect();
+lp.subscribe({ subId: "rugs", channels: ["rhc:lp_events"], filters: { actions: ["remove"], material_only: true } });
+lp.on("rhc:lp_event", (e: RhcLpStreamEvent) => console.log(e.dex, e.pool, e.action, e.active_share ?? e.share_of_reserves));
+```
+
+**Candles, risk verdicts and deployer tiers (server 2026-09-23).** All three are PRO+ and **scoped**: per-connection cap PRO 25 / ULTRA 100 / BUSINESS 250 across named subscriptions; over the cap or without a scope the channel is rejected, never truncated. `rhc:token_candles` (`filters.addresses`, a budget separate from `rhc:token_prices`): `rhc:candle_closed` is the stored 1-minute row (id `candle:robinhood:<address>:<bucket epoch s>`), `rhc:candle_revised` the same row rewritten (`revision` n > 0, id suffix `:r<n>`); `filters.updates: true` adds `rhc:candle_update`, the in-progress minute (≤ 1 per address per second, a state stream: no id, never replayed, no snapshot). `rhc:token_risk` (`filters.addresses`, optional `risk_events`, `risk_snapshot` default `true`): `rhc:risk_verdict_changed` when a sweep recheck stores a different verdict — the change happened somewhere in `(previous_checked_at, checked_at]` — plus one `rhc:risk_verdict` snapshot frame per address (`frame.snapshot === true`); `score` is **higher = safer**, the opposite of Solana's `risk_score`. `rhc:wallet_scores` (`filters.wallets`, 0x deployers, optional `score_events`): `rhc:deployer_tier_changed` after each 5-min refresh ("recomputed at T", not "changed at T").
+
+```ts
+const s = client.stream.connect();
+s.subscribe({ subId: "candles", channels: ["rhc:token_candles"], filters: { addresses: [TOKEN], updates: true } });
+s.subscribe({ subId: "risk", channels: ["rhc:token_risk"], filters: { addresses: [TOKEN] } });
+s.subscribe({ subId: "tiers", channels: ["rhc:wallet_scores"], filters: { wallets: [DEPLOYER] } });
+s.on("rhc:candle_closed", (c: RhcCandleClosedEvent) => console.log(c.bucket_start, c.open_price_usd, c.close_price_usd, c.volume_usd));
+s.on("rhc:risk_verdict_changed", (e: RhcRiskVerdictChangedEvent) => console.log(e.token_address, e.changed, e.before.score, "→", e.after.score));
+s.on("rhc:deployer_tier_changed", (e: RhcDeployerTierChangedEvent) => console.log(e.address, e.tier_before, "→", e.tier_after));
+```
 
 > **Deprecated:** `rhc:trades` was never a real channel — 0.4.0 subscribers got a `channels_rejected` warning and silence. The server now accepts it as an alias of `rhc:dex_trades` (and acks it under the canonical name), and the SDK keeps the literal marked `@deprecated` so 0.4.0 code compiles. Use `rhc:dex_trades`.
 

package/dist/index.d.ts

@@ -369,17 +369,26 @@ export interface RhcLpEventsParams {
     provider?: string;
     /** Filter by DEX version. */
     dex?: UniswapVersion;
+    /**
+     * Which actions to return (2026-09-23). Default `"remove"` = the historical
+     * removals-only feed, unchanged. `"add"` (kept 7 days), `"pool_created"` or
+     * `"all"` opt into rows persisted since the WS Phase 3 producer.
+     */
+    action?: RhcLpAction | "all";
     /** Opaque cursor from `next_before` (same (block_time,id) keyset as /rhc/trades). */
     before?: string;
 }
+/** A liquidity action on Robinhood Chain. */
+export type RhcLpAction = "add" | "remove" | "pool_created";
 /**
- * One liquidity REMOVAL from `/rhc/lp-events`. Every row is `event: "remove"` —
- * adds are not persisted. Amounts are raw on-chain uint256 integers as decimal
- * STRINGS; v4 rows carry `liquidity` only (the pool manager emits no token
- * amounts), so `amount0` / `amount1` / `token_amount_raw` are null there.
+ * One liquidity event from `/rhc/lp-events`. Without `action` every row is
+ * `event: "remove"` (the default feed is removals only). Amounts are raw
+ * on-chain uint256 integers as decimal STRINGS; v4 rows carry `liquidity` only
+ * (the pool manager emits no token amounts), so `amount0` / `amount1` /
+ * `token_amount_raw` are null there.
  */
 export interface RhcLpEvent {
-    event: "remove";
+    event: RhcLpAction;
     pool: string;
     dex: UniswapVersion;
     fee_tier: number | null;
@@ -411,6 +420,305 @@ export interface RhcLpEvent {
     block_time: string;
     tx_hash: string;
     log_index: number;
+    tick_lower?: number | null;
+    tick_upper?: number | null;
+    /** Signed liquidity change (v3/v4), int256 as string. */
+    liquidity_delta?: string | null;
+    /** tick_lower <= current tick < tick_upper just before the event; null = tick unknown. */
+    in_range?: boolean | null;
+    /** liquidity_delta when in range, "0" out of range. */
+    active_liquidity_delta?: string | null;
+    /** |active delta| / active liquidity before (v3/v4); 0 out of range; adds can exceed 1. */
+    active_share?: number | null;
+    /** v2 only: amount / reserve before (from the pair's Sync). */
+    share_of_reserves?: number | null;
+    /** true = a removal of ≥ 25 % of reserves / active liquidity; null for adds, creations and unknown shares. */
+    material?: boolean | null;
+}
+/** Why `active_share` is null / not the relevant share. */
+export type RhcLpActiveShareReason = "pool_created" | "not_concentrated" | "pool_state_unknown" | "no_active_liquidity";
+/**
+ * `rhc:lp_event` frame `data` (WS channel `rhc:lp_events`, ULTRA / BUSINESS,
+ * 2026-09-23). Frame id = `rhc:lp_event:<tx_hash>:<log_index>`. Every key is
+ * always present (null when unknown). `in_range` / `active_*` are null with
+ * `active_share_reason: "pool_state_unknown"` when the pool's tick was not
+ * known — never guessed. `provider` is usually a router / position manager,
+ * not the beneficial owner. No USD field.
+ */
+export interface RhcLpStreamEvent {
+    chain: Chain;
+    action: RhcLpAction;
+    dex: UniswapVersion;
+    pool: string;
+    token_address: string | null;
+    token: {
+        address: string | null;
+        symbol: string | null;
+        decimals: number | null;
+    };
+    token0: string | null;
+    token1: string | null;
+    provider: string | null;
+    liquidity: string | null;
+    /** NULL on v4 — ModifyLiquidity reports no token amounts. */
+    amount0: string | null;
+    amount1: string | null;
+    tick_lower: number | null;
+    tick_upper: number | null;
+    liquidity_delta: string | null;
+    in_range: boolean | null;
+    active_liquidity_delta: string | null;
+    active_share: number | null;
+    active_share_reason: RhcLpActiveShareReason | null;
+    share_of_reserves: number | null;
+    material: boolean | null;
+    block_number: number | null;
+    block_time: string | null;
+    tx_hash: string;
+    log_index: number | null;
+}
+/** Per-subscription filters for `rhc:lp_events` (all optional, AND; invalid values reject the channel). */
+export interface RhcLpEventsFilters {
+    addresses?: string[];
+    pools?: string[];
+    dexes?: UniswapVersion[];
+    actions?: RhcLpAction[];
+    material_only?: boolean;
+    /** 0..1000 — only events whose relevant share (reserves on v2, active on v3/v4) is known and ≥ this. */
+    min_share?: number;
+}
+/** Unlock-schedule event names on `rhc:token_locks` (only with `filters.lifecycle: true`). */
+export type RhcTokenLockLifecycleEventName = "rhc:token_unlock_upcoming" | "rhc:token_unlock_available";
+/**
+ * Filters that switch `rhc:token_locks` to lifecycle mode. Claims, extensions
+ * and cancels are NOT observable on Robinhood Chain — only the unlock schedule.
+ */
+export interface RhcTokenLockLifecycleFilters {
+    lifecycle: true;
+    events?: RhcTokenLockLifecycleEventName[];
+    unlock_kinds?: Array<"cliff" | "final" | "tranche">;
+    /** Token scope for creates AND lifecycle (≤ 500); applied only with `lifecycle: true`. */
+    addresses?: string[];
+}
+/**
+ * `rhc:token_unlock_upcoming` (the lock's NEXT unlock, when it is within 24 h) /
+ * `rhc:token_unlock_available` (passed within the last 30 min — claimable PER
+ * THE SCHEDULE, NOT claimed). Frame id = `<event>:<event_key>`.
+ */
+export interface RhcTokenUnlockScheduleEvent {
+    event_key: string;
+    lock_id: string;
+    token_address: string;
+    family: string;
+    observed_at: string | null;
+    unlock_at: string;
+    unlock_kind: "cliff" | "final" | "tranche";
+    amount_raw: string | null;
+    amount_reason: string | null;
+    unlocked_total_raw: string | null;
+    release_model: "at_end" | "linear" | "tranched";
+    claimable?: true;
+    chain: Chain;
+    locker: string | null;
+    kind: string | null;
+    subject: string | null;
+    lp_kind: string | null;
+    lp_pool: string | null;
+    sender: string | null;
+    recipient: string | null;
+    locked_amount_raw: string | null;
+    amount_unit: string | null;
+    decimals: number | null;
+    withdrawals_tracked: false;
+}
+/**
+ * `rhc:token_candles` subscribe filters (PRO+). `addresses` is REQUIRED (0x,
+ * case-insensitive) and capped per CONNECTION across named subscriptions —
+ * PRO 25 / ULTRA 100 / BUSINESS 250, a budget separate from
+ * `rhc:token_prices`. Over the cap, a missing scope or a non-boolean
+ * `updates` rejects the channel, never truncates.
+ */
+export interface RhcTokenCandlesFilters {
+    addresses: string[];
+    /** Also receive the in-progress minute as `rhc:candle_update` (a state stream). Default false. */
+    updates?: boolean;
+}
+/**
+ * `rhc:candle_closed` / `rhc:candle_revised` frame `data` — the STORED
+ * 1-minute row (`rhc_ohlc_1m`), identical live and on a durable resume.
+ * Every key is always present (null when unknown). Frame id =
+ * `candle:robinhood:<address>:<bucket_start epoch s>`, plus `:r<n>` for the
+ * n-th revision (not event-prefixed). `revision` 0 = the close as first
+ * written; a rewrite (restart merge, spoofed-pool purge) bumps it and is
+ * announced as `rhc:candle_revised` with the full rewritten row.
+ */
+export interface RhcCandleClosedEvent {
+    chain: Chain;
+    address: string;
+    bucket_start: string;
+    /** bucket_start + 60 s. */
+    bucket_end: string;
+    /** When the row was first written. */
+    closed_at: string | null;
+    revision: number;
+    /** Latest rewrite; null for revision 0. */
+    revised_at: string | null;
+    open_price_usd: number | null;
+    high_price_usd: number | null;
+    low_price_usd: number | null;
+    close_price_usd: number | null;
+    open_mc_usd: number | null;
+    high_mc_usd: number | null;
+    low_mc_usd: number | null;
+    close_mc_usd: number | null;
+    close_liquidity_usd: number | null;
+    close_supply: number | null;
+    volume_usd: number | null;
+    buy_volume_usd: number | null;
+    sell_volume_usd: number | null;
+    trades: number | null;
+    buy_count: number | null;
+    sell_count: number | null;
+    dex: string | null;
+    pool_address: string | null;
+    final: true;
+    source: "rhc_ohlc_1m";
+}
+/**
+ * `rhc:candle_update` frame `data` (only with `filters.updates: true`) — the
+ * producer's in-progress minute, ≤ 1 per address per second. A state stream:
+ * no id / seq, never replayed, no snapshot on subscribe.
+ */
+export interface RhcCandleUpdateEvent {
+    chain: Chain;
+    address: string;
+    bucket_start: string;
+    bucket_end: string;
+    open_price_usd: number | null;
+    high_price_usd: number | null;
+    low_price_usd: number | null;
+    close_price_usd: number | null;
+    close_mc_usd: number | null;
+    volume_usd: number | null;
+    trades: number | null;
+    final: false;
+    /** The producer's timestamp of this state (ISO). */
+    as_of: string | null;
+    source: "rhc-dex-stream:open_candle";
+}
+/**
+ * `rhc:token_risk` subscribe filters (PRO+). `addresses` is REQUIRED (0x,
+ * lowercased), capped per connection PRO 25 / ULTRA 100 / BUSINESS 250.
+ */
+export interface RhcTokenRiskFilters {
+    addresses: string[];
+    /** Non-empty subset of the channel's event types. */
+    risk_events?: Array<"rhc:risk_verdict_changed">;
+    /** Send one `rhc:risk_verdict` snapshot per address on subscribe / scope change / resume. Default true. */
+    risk_snapshot?: boolean;
+}
+/** A stored RHC risk verdict (event `before` / `after`, snapshot `verdict`). */
+export interface RhcRiskVerdict {
+    /** 100 − penalties: HIGHER = SAFER — the opposite of Solana's `risk_score`; never compare the two. */
+    score: number | null;
+    sellable: boolean | null;
+    sellable_reason: string | null;
+    proxy_kind: string | null;
+    upgradeable: boolean | null;
+    owner_model: string | null;
+    can_mint: boolean | null;
+    can_pause: boolean | null;
+    lp_custody: string | null;
+    lp_burned_pct: number | null;
+    code_size: number | null;
+    flags: string[];
+}
+/**
+ * `rhc:risk_verdict_changed` — a sweep recheck stored a verdict that differs
+ * in a diffed field. The change happened somewhere in
+ * `(previous_checked_at, checked_at]` (days to weeks), never at `checked_at`.
+ * A first assessment is never an event. Frame id =
+ * `rhc:risk_verdict_changed:<event_key>`.
+ */
+export interface RhcRiskVerdictChangedEvent {
+    chain: Chain;
+    token_address: string;
+    /** `<token>:verdict:<checked_at epoch ms>`. */
+    event_key: string;
+    changed: Array<"score" | "sellable" | "proxy_kind" | "upgradeable" | "owner_model" | "can_mint" | "can_pause" | "lp_custody" | "flags">;
+    flags_added: string[];
+    flags_removed: string[];
+    before: RhcRiskVerdict;
+    after: RhcRiskVerdict;
+    checked_at: string;
+    previous_checked_at: string | null;
+    score_semantics: "higher_is_safer";
+    detection: {
+        method: "recheck_sweep";
+        recheck_target_hours: number;
+        sweep_interval_minutes: number;
+        min_liquidity_usd: number;
+        note: string;
+    };
+    written_at: string;
+    source: "rhc_token_risk";
+}
+/**
+ * `rhc:risk_verdict` snapshot frame `data` (frame `snapshot: true`, no id /
+ * seq): the CURRENT stored verdict of one scoped address.
+ */
+export interface RhcRiskVerdictSnapshot {
+    chain: Chain;
+    token_address: string;
+    /** false = never assessed (verdict and checked_at null). */
+    assessed: boolean;
+    verdict: RhcRiskVerdict | null;
+    checked_at: string | null;
+    score_semantics: "higher_is_safer";
+    source: "rhc_token_risk";
+}
+/**
+ * `rhc:wallet_scores` subscribe filters (PRO+). `wallets` is REQUIRED — 0x
+ * deployer addresses (lowercased) — capped per connection PRO 25 / ULTRA 100 /
+ * BUSINESS 250. A subscription that also holds the Solana `wallet:scores`
+ * channel may mix in base58 wallets; an entry of a chain the subscription does
+ * not hold is refused.
+ */
+export interface RhcWalletScoresFilters {
+    wallets: string[];
+    /** Optional subset of the held channels' event types. */
+    score_events?: Array<"rhc:deployer_tier_changed" | "deployer:tier_changed" | "kol:score_state_changed">;
+}
+/**
+ * `rhc:deployer_tier_changed` — the 5-min `mv_rhc_deployers` refresh found a
+ * different tier ("recomputed at T", not "changed at T"). A deployer appearing
+ * `neutral` is not an event; entering a ranked tier is (`tier_before:
+ * "neutral"`), a first appearance already ranked has `tier_before: null` +
+ * `first_appearance: true`, vanishing from the matview has `tier_after: null`.
+ * Frame id = `rhc:deployer_tier_changed:<event_key>`.
+ */
+export interface RhcDeployerTierChangedEvent {
+    /** `<address>:<refresh epoch ms>`. */
+    event_key: string;
+    chain: Chain;
+    address: string;
+    tier_before: DeployerTier | null;
+    tier_after: DeployerTier | null;
+    first_appearance: boolean;
+    /** null when the deployer left the matview. */
+    stats: {
+        tokens_deployed: number | null;
+        graduated: number | null;
+        graduation_rate: number | null;
+        runners: number | null;
+        runner_rate: number | null;
+        best_peak_mc_usd: number | null;
+        first_deploy_at: string | null;
+        last_deploy_at: string | null;
+    } | null;
+    computed_at: string;
+    source: "matview_refresh";
+    matview: "mv_rhc_deployers";
 }
 export interface RhcLpEventsResponse {
     chain: Chain;
@@ -419,10 +727,11 @@ export interface RhcLpEventsResponse {
     has_more: boolean;
     /** Opaque pagination cursor; pass back as `before`. */
     next_before: string | null;
-    /** Honesty block: `events: ["remove"]`, `adds_persisted: false`, note, since. */
+    /** Honesty block: the actions this response covers (["remove"] by default), adds_persisted, note, since. */
     coverage: {
         events: string[];
-        adds_persisted: boolean;
+        adds_persisted: boolean | null;
+        adds_retention_days?: number;
         note: string;
         since: string;
     };