Adds live two-line UI, PoolTick telemetry, and vault stream adapter#1
Merged
Conversation
Introduce a single abstraction boundary for vault balance streaming that normalizes updates and hides RPC encoding details. Add a vault stream adapter plus local SPL decoding and an in-memory mint-decimals cache so the app can subscribe with base64 (raw) or jsonParsed (parsed) without pulling in new deps. Wire a VAULT_ENCODING env switch (defaults to raw and logs the default) into the live price path and tooling, seeding state from snapshots and then consuming normalized live updates. Refactor streaming logic to use the adapter, preserve slot-sync and debounce behavior, and keep parsed-mode behavior unchanged. Update docs and add design notes about the approach.
Adds a normalized PoolTick event and a small analytics pipeline to produce per-pool telemetry. Adds a PoolTick model and generator, a rolling-window metrics engine (10s/60s/300s) that computes net quote flow, flow volume and a deterministic depth score (log1p), and a logger that writes one JSON line per emitted tick to logs/poolTicks.log (handles bigint safely). Wires tick creation into existing snapshot and live streaming paths for both AMM and pump sources, maps pump proxies for real reserves, computes staleness per pool, and attaches rolling metrics before logging. Preserves human-readable console output and existing decoding/streaming behavior and stays CommonJS. Includes unit tests for the new telemetry pieces and vault adapters to validate decoding, caching and streaming behaviors.
Documents that the app emits a normalized PoolTick JSON object (one line per tick) to logs/poolTicks.log whenever a price line is printed (snapshot or live). Specifies included fields: spot price, reserves, staleness, and rolling metrics (quote flow + depth score). Clarifies logging format to enable consistent downstream analytics and ingestion.
Adds an optional filename option to the pool tick logger factory so callers can specify the log file location while keeping the original default. Creates the parent directory for a provided log path at instantiation instead of eagerly creating a default logs directory at module load, avoiding side effects and enabling tests to use temporary files. Updates tests to write to a temp log file rather than the repository logs directory.
Adds a deterministic per-pool state labeler that annotates PoolTick records with a state name, direction and concise reasons to make trading signals explainable and machine-consumable. Introduces a MIN_QUOTE_SOL environment variable (default 35) with parsing and startup validation, and logs the configured value. Wires the state evaluator into tick handling so emitted PoolTicks include state metadata. Implements cooldown, warmup, thin/stale gates, impulse/confirm/trend logic with depth-scaled thresholds and concise reason strings. Adds unit tests covering min-quote gate, impulse->confirming, cooldown behavior, warmup, and missing-timestamp handling. Also hardens rolling-window metrics: window sampling and readiness checks improved so metrics are null until sufficient history exists. Updates docs and .env.sample to document the new env var and PoolTick state output. Improves observability and stability by preventing noisy labels on low-liquidity or stale pools and providing clear, reproducible state decisions for downstream analytics.
* analytics: Adds pool state machine with MIN_QUOTE_SOL gating Allows custom pool tick log path Adds pool tick logging note to README Adds PoolTick telemetry and rolling-window metrics Add vault stream adapter with raw/jsonParsed decoding
Adds a TTY live-renderer that prints a two-line in-place display: the existing price line plus a PoolTick summary showing state (with direction arrow), liquidity depth, 10s/60s flows, and staleness. Provides safe non-TTY fallback to plain logging. Introduces small formatting helpers and a summary renderer that consumes the evaluated tick/state output. Wires the summary into the streaming code paths so the latest state line is kept in sync with price updates. Updates documentation to describe the live UI and removes an obsolete planning doc.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Why
Tests & docs
Notes
Checklist