hood-alerts 0.1.0

package/dist/pricing-BumgLpvB.d.ts

@@ -0,0 +1,79 @@
+import { Address } from 'viem';
+import { HoodClient } from 'hoodchain';
+
+/**
+ * USD valuation for alert events.
+ *
+ * There is no hardcoded price anywhere in this package. Every dollar figure
+ * comes from live chain state:
+ *
+ * - **USDG legs are the unit of account.** USDG is Paxos' Global Dollar, a
+ *   fully reserved 1:1 USD stablecoin with 6 decimals. A USDG leg of a trade
+ *   is its own USD value, no oracle needed.
+ * - **ETH legs are priced through the chain's own Uniswap v3 liquidity.** The
+ *   oracle asks `hoodchain`'s `quoteSwap` for the real output of selling 1
+ *   WETH into USDG across every fee tier and two-hop route, and takes the best
+ *   route's output as the ETH/USD rate. That is the price a trader would
+ *   actually get, sourced from the same pools the alerts watch.
+ * - **Anything else is `null`.** A memecoin/memecoin pool with no USDG or WETH
+ *   leg has no honest USD value from on-chain data alone, so the event carries
+ *   `usdValue: null` and min-USD rules simply do not match it.
+ *
+ * Rates are cached for a short TTL so a burst of events in one block does not
+ * re-quote the router once per event.
+ */
+/** A source of USD rates for the two priceable legs. */
+interface PriceOracle {
+    /**
+     * USD per 1 ETH, or `null` when no WETH/USDG route has liquidity right now.
+     * Never throws: a quote failure degrades to `null`, which downgrades USD
+     * filters rather than dropping the alert pipeline.
+     */
+    ethUsd(): Promise<number | null>;
+    /** Convert a raw wei amount to USD, or `null` when the rate is unavailable. */
+    weiToUsd(wei: bigint): Promise<number | null>;
+    /** Convert a raw USDG amount (6 decimals) to USD. Always available. */
+    usdgToUsd(atomic: bigint): number;
+}
+/** Options for {@link createPriceOracle}. */
+interface PriceOracleOptions {
+    /**
+     * How long a quoted ETH/USD rate stays fresh, in milliseconds.
+     * @defaultValue `30_000`
+     */
+    ttlMs?: number;
+    /**
+     * Probe size used to quote WETH into USDG. Larger sizes are less sensitive
+     * to a thin tick but need deeper liquidity to fill.
+     * @defaultValue `1` ETH
+     */
+    probeWei?: bigint;
+    /** Clock injection point for tests. @defaultValue `Date.now` */
+    now?: () => number;
+}
+/** WETH and USDG for the client's network. */
+declare function quoteTokens(client: HoodClient): {
+    weth: Address;
+    usdg: Address;
+};
+/**
+ * Build a caching ETH/USD oracle backed by real Uniswap v3 quotes.
+ *
+ * @example
+ * ```ts
+ * import { createHoodClient } from 'hoodchain'
+ * import { createPriceOracle } from 'hood-alerts/events'
+ *
+ * const hood = createHoodClient()
+ * const oracle = createPriceOracle(hood)
+ * console.log('ETH/USD from chain liquidity:', await oracle.ethUsd())
+ * ```
+ */
+declare function createPriceOracle(client: HoodClient, options?: PriceOracleOptions): PriceOracle;
+/**
+ * A fixed-rate oracle. Useful when an operator already has a trusted ETH/USD
+ * feed and wants alerts to agree with it, and for deterministic tests.
+ */
+declare function createStaticPriceOracle(ethUsdRate: number | null): PriceOracle;
+
+export { type PriceOracle as P, type PriceOracleOptions as a, createStaticPriceOracle as b, createPriceOracle as c, quoteTokens as q };

package/dist/ratelimit-BKVQG2oY.d.cts

@@ -0,0 +1,42 @@
+import { R as RateLimitConfig } from './schema-NnIdKFl2.cjs';
+
+/**
+ * Rate limiting is a *storage* question, not an in-memory counter question:
+ * a service that resets its limits on every deploy is not rate limited. The
+ * engine talks to this interface, the service backs it with the same SQLite
+ * file that holds the delivery log, and tests back it with a map.
+ */
+interface RateLimitStore {
+    /** How many deliveries were recorded for `key` at or after `sinceMs`. */
+    countSince(key: string, sinceMs: number): Promise<number>;
+    /** When `key` last delivered, or `null` if never. */
+    lastAt(key: string): Promise<number | null>;
+    /**
+     * Record a delivery against both its rule bucket and its subscriber. The
+     * subscriber attribution is what the tier throughput cap counts, so the two
+     * are written together and can never drift apart.
+     */
+    record(key: string, subscriberId: string, atMs: number): Promise<void>;
+    /** How many alerts a subscriber received since `sinceMs`, for tier caps. */
+    countForSubscriberSince(subscriberId: string, sinceMs: number): Promise<number>;
+}
+/** Why a rate limit rejected a delivery, or `null` when it allowed it. */
+interface RateLimitDecision {
+    allowed: boolean;
+    /** Human-readable reason, safe to log and to show in `/status`. */
+    reason: string | null;
+    /** When the next delivery would be allowed, ms since epoch, if known. */
+    retryAtMs: number | null;
+}
+/**
+ * Check a rule's rate limit without consuming it. Consumption happens through
+ * {@link RateLimitStore.record} after a delivery attempt, so a rule that
+ * matches but fails entitlement checks does not burn quota.
+ */
+declare function checkRateLimit(store: RateLimitStore, key: string, config: RateLimitConfig | undefined, nowMs: number): Promise<RateLimitDecision>;
+/** An in-memory {@link RateLimitStore}. Correct, but resets with the process. */
+declare function createMemoryRateLimitStore(): RateLimitStore;
+/** Canonical rate-limit key: one bucket per rule per subscription. */
+declare function rateLimitKey(subscriptionId: string, ruleId: string): string;
+
+export { type RateLimitDecision as R, type RateLimitStore as a, createMemoryRateLimitStore as b, checkRateLimit as c, rateLimitKey as r };

package/dist/ratelimit-CGLlXNIS.d.ts

@@ -0,0 +1,42 @@
+import { R as RateLimitConfig } from './schema-DuDMPqpq.js';
+
+/**
+ * Rate limiting is a *storage* question, not an in-memory counter question:
+ * a service that resets its limits on every deploy is not rate limited. The
+ * engine talks to this interface, the service backs it with the same SQLite
+ * file that holds the delivery log, and tests back it with a map.
+ */
+interface RateLimitStore {
+    /** How many deliveries were recorded for `key` at or after `sinceMs`. */
+    countSince(key: string, sinceMs: number): Promise<number>;
+    /** When `key` last delivered, or `null` if never. */
+    lastAt(key: string): Promise<number | null>;
+    /**
+     * Record a delivery against both its rule bucket and its subscriber. The
+     * subscriber attribution is what the tier throughput cap counts, so the two
+     * are written together and can never drift apart.
+     */
+    record(key: string, subscriberId: string, atMs: number): Promise<void>;
+    /** How many alerts a subscriber received since `sinceMs`, for tier caps. */
+    countForSubscriberSince(subscriberId: string, sinceMs: number): Promise<number>;
+}
+/** Why a rate limit rejected a delivery, or `null` when it allowed it. */
+interface RateLimitDecision {
+    allowed: boolean;
+    /** Human-readable reason, safe to log and to show in `/status`. */
+    reason: string | null;
+    /** When the next delivery would be allowed, ms since epoch, if known. */
+    retryAtMs: number | null;
+}
+/**
+ * Check a rule's rate limit without consuming it. Consumption happens through
+ * {@link RateLimitStore.record} after a delivery attempt, so a rule that
+ * matches but fails entitlement checks does not burn quota.
+ */
+declare function checkRateLimit(store: RateLimitStore, key: string, config: RateLimitConfig | undefined, nowMs: number): Promise<RateLimitDecision>;
+/** An in-memory {@link RateLimitStore}. Correct, but resets with the process. */
+declare function createMemoryRateLimitStore(): RateLimitStore;
+/** Canonical rate-limit key: one bucket per rule per subscription. */
+declare function rateLimitKey(subscriptionId: string, ruleId: string): string;
+
+export { type RateLimitDecision as R, type RateLimitStore as a, createMemoryRateLimitStore as b, checkRateLimit as c, rateLimitKey as r };

package/dist/registry-D3We8Lg6.d.ts

@@ -0,0 +1,50 @@
+import { Address } from 'viem';
+import { e as Launchpad } from './types-DFPpTMWo.js';
+
+/**
+ * A memecoin pool the whale watcher tracks.
+ *
+ * Why a registry exists at all: chain-wide `Swap` queries are not viable on
+ * Robinhood Chain. A topic-only query for the Uniswap v3 `Swap` signature
+ * overflows the RPC's 10,000-log result cap in well under 2,000 blocks (the
+ * chain produces a block roughly every 100-130ms and is busy). The whale
+ * source therefore watches an explicit, address-filtered *active pool set*
+ * assembled from launchpad activity: NOXA pools are known at launch, Odyssey
+ * pools are known at graduation.
+ */
+interface PoolEntry {
+    pool: Address;
+    /** The memecoin side of the pool. */
+    token: Address;
+    /** The quote side (WETH or USDG). */
+    quoteToken: Address;
+    launchpad: Launchpad;
+    /** Block the pool became known (launch for NOXA, graduation for Odyssey). */
+    createdBlock: bigint;
+}
+/** Storage for known memecoin pools and token origins. */
+interface PoolRegistry {
+    /** Record (or update) a pool. Idempotent. */
+    record(entry: PoolEntry): Promise<void>;
+    /**
+     * The pools to watch for whale trades, newest first, capped at `limit`.
+     * `pinned` tokens (subscriber watchlists) are always included regardless of
+     * age, because a watchlist alert that silently ages out would be a lie.
+     */
+    active(limit: number, pinned?: readonly Address[]): Promise<PoolEntry[]>;
+    /** Which launchpad a token came from, or `null` if never seen. */
+    originOf(token: Address): Promise<Launchpad | null>;
+    /** Every pool recorded for a token. */
+    poolsFor(token: Address): Promise<PoolEntry[]>;
+    /** Total pools recorded, for `/metrics`. */
+    size(): Promise<number>;
+}
+/**
+ * In-memory pool registry. Correct and dependency-free, but it starts empty
+ * on every process start, so the service uses the SQLite-backed registry from
+ * `hood-alerts/service` instead. This one is the right choice for scripts,
+ * examples and tests.
+ */
+declare function createMemoryPoolRegistry(entries?: readonly PoolEntry[]): PoolRegistry;
+
+export { type PoolEntry as P, type PoolRegistry as a, createMemoryPoolRegistry as c };

package/dist/registry-DePA3IyS.d.cts

@@ -0,0 +1,50 @@
+import { Address } from 'viem';
+import { e as Launchpad } from './types-DFPpTMWo.cjs';
+
+/**
+ * A memecoin pool the whale watcher tracks.
+ *
+ * Why a registry exists at all: chain-wide `Swap` queries are not viable on
+ * Robinhood Chain. A topic-only query for the Uniswap v3 `Swap` signature
+ * overflows the RPC's 10,000-log result cap in well under 2,000 blocks (the
+ * chain produces a block roughly every 100-130ms and is busy). The whale
+ * source therefore watches an explicit, address-filtered *active pool set*
+ * assembled from launchpad activity: NOXA pools are known at launch, Odyssey
+ * pools are known at graduation.
+ */
+interface PoolEntry {
+    pool: Address;
+    /** The memecoin side of the pool. */
+    token: Address;
+    /** The quote side (WETH or USDG). */
+    quoteToken: Address;
+    launchpad: Launchpad;
+    /** Block the pool became known (launch for NOXA, graduation for Odyssey). */
+    createdBlock: bigint;
+}
+/** Storage for known memecoin pools and token origins. */
+interface PoolRegistry {
+    /** Record (or update) a pool. Idempotent. */
+    record(entry: PoolEntry): Promise<void>;
+    /**
+     * The pools to watch for whale trades, newest first, capped at `limit`.
+     * `pinned` tokens (subscriber watchlists) are always included regardless of
+     * age, because a watchlist alert that silently ages out would be a lie.
+     */
+    active(limit: number, pinned?: readonly Address[]): Promise<PoolEntry[]>;
+    /** Which launchpad a token came from, or `null` if never seen. */
+    originOf(token: Address): Promise<Launchpad | null>;
+    /** Every pool recorded for a token. */
+    poolsFor(token: Address): Promise<PoolEntry[]>;
+    /** Total pools recorded, for `/metrics`. */
+    size(): Promise<number>;
+}
+/**
+ * In-memory pool registry. Correct and dependency-free, but it starts empty
+ * on every process start, so the service uses the SQLite-backed registry from
+ * `hood-alerts/service` instead. This one is the right choice for scripts,
+ * examples and tests.
+ */
+declare function createMemoryPoolRegistry(entries?: readonly PoolEntry[]): PoolRegistry;
+
+export { type PoolEntry as P, type PoolRegistry as a, createMemoryPoolRegistry as c };