trade-doc/economic-markers-k3s.md

Economic Markers In K3s

Cel

Chcemy dodawac markery ekonomiczne i tradingowe jako osobne komponenty runtime na mevnode_bot, bez mieszania ich z samym orderbookiem i bez bezposredniego odpytywania kazdego markera z frontendu.

Docelowy model:

worker -> Postgres -> Hasura/API -> visualizer

To ma byc warstwa:

• szybka do rozwijania
• niezalezna per marker
• latwa do obserwacji i debugowania
• bez ryzyka, ze jeden eksperymentalny marker psuje caly runtime

Zasada architektoniczna

Markery liczymy w osobnych kontenerach na k3s, ale nie wystawiamy ich bezposrednio do UI.

Kazdy marker:

1. czyta dane z juz istniejacego runtime:

   • Hasura
   • Postgres
   • Redis
   • opcjonalnie trade-api
   • opcjonalnie bezposrednio mevnode_sol RPC, jesli marker naprawde tego potrzebuje

2. liczy wlasny sygnal

3. zapisuje wynik do Postgresa

4. Hasura trackuje tabele markerow

5. visualizer rysuje:

   • overlay na chart
   • osobny panel pod chartem
   • badge / regime / warning nad marketem

Frontend nie powinien znac topologii workerow.

Dlaczego osobne kontenery

To daje kilka korzysci:

• izolacja awarii
• latwe rollouty
• rozne cadence per marker
• mozliwosc wlaczania / wylaczania markerow niezaleznie
• prostszy profiling CPU i memory
• latwiejszy eksperyment workflow

Dobry podzial:

• fast markers

  • 200-500 ms
  • mikrostruktura
  • imbalance
  • orderbook slope
  • spread regime

• medium markers

  • 1-5 s
  • funding pressure
  • basis
  • depth depletion
  • oracle divergence

• slow markers

  • 10-60 s
  • volatility regime
  • realized vol
  • trend regime
  • event calendars

Rekomendowany model danych

Nie robimy osobnej tabeli per kazdy marker.

Na start lepszy jest wspolny model:

1. market_markers_latest

Jedna tabela z najnowsza wartoscia markera.

Przyklad kolumn:

• source
• market_name
• marker_name
• ts
• value_num
• value_text
• value_bool
• band
• confidence
• severity
• meta jsonb
• updated_at

Klucz logiczny:

(source, market_name, marker_name)

To jest warstwa pod:

• karty market details
• badge typu risk on, thin book, high dislocation
• ostatni stan markera

2. market_markers_ts

Historia timeseries dla markerow.

Przyklad kolumn:

• event_ts
• id
• source
• market_name
• marker_name
• value_num
• value_text
• value_bool
• band
• confidence
• severity
• meta jsonb
• inserted_at

To jest warstwa pod:

• overlaye na chart
• osobne panele
• replay
• debug
• porownanie markerow w czasie

3. market_marker_events

Opcjonalna tabela tylko dla zmian stanu i alertow.

Przyklad:

• event_ts
• source
• market_name
• marker_name
• event_type
• prev_value
• next_value
• severity
• meta

To jest pod:

• timeline alertow
• debug strategy
• feed zdarzen na UI

Typy markerow

Najlepiej od razu rozdzielic markery na klasy.

Overlay markers

To sa serie rysowane bezposrednio na wykresie ceny:

• fair value
• local VWAP
• short-term imbalance line
• oracle divergence bands
• liquidation zones
• micro support / resistance

Dane:

• value_num
• opcjonalnie band
• opcjonalnie meta.upper, meta.lower

Panel markers

To sa osobne serie pod wykresem:

• spread bps
• imbalance
• depth asymmetry
• book velocity
• trade aggression
• realized vol

State markers

To sa dyskretne stany:

• trend_up
• range
• high_risk
• thin_liquidity
• event_window

Tu zwykle:

• value_text
• value_bool
• severity
• confidence

Rekomendowane markery na start

Pierwszy pakiet powinien byc maly i praktyczny.

Marker 1. oracle_dislocation_bps

Liczy:

(mark - oracle) / oracle * 10_000

Cel:

• pokazac odklejenie od oracle
• ostrzegac, kiedy orderbook/mark zaczyna byc sztucznie przesuniety

Prezentacja:

• panel pod chartem
• badge nad marketem po przekroczeniu progow

Marker 2. top12_imbalance

Liczy:

(bid_usd - ask_usd) / (bid_usd + ask_usd)

na poziomach zblizonych do tego, co pokazuje orderbook UI

Cel:

• prosty sygnal przewagi strony
• zgodnosc z tym, co trader widzi na ekranie

Prezentacja:

• panel
• opcjonalnie mini sparkline obok orderbooka

Marker 3. spread_regime

Liczy stan:

• tight
• normal
• wide

na bazie spread_bps

Cel:

• szybki filtr, czy rynek nadaje sie do wejscia

Prezentacja:

• badge w market details

Marker 4. depth_depletion

Liczy:

• spadek plynnosci top-of-book vs rolling baseline

Cel:

• wykrywanie, ze ksiazka staje sie pusta zanim ruch przyspieszy

Prezentacja:

• panel
• alert event

Marker 5. micro_vol_regime

Liczy:

• rolling realized volatility na 1s / 5s / 1m

Cel:

• odroznic spokojny market od marketu o zbyt duzym noise

Prezentacja:

• panel pod chartem

K3s deployment model

Na start proponuje namespace trade.

Kazdy marker to osobny Deployment, ale z tym samym kontraktem runtime.

Przyklad nazw:

• marker-oracle-dislocation
• marker-top12-imbalance
• marker-spread-regime
• marker-depth-depletion
• marker-micro-vol

Kazdy deployment:

• replicas: 1
• ConfigMap dla parametrow
• Secret tylko jesli musi czytac cos wrazliwego
• write tylko do Postgresa / Hasury

Nie robimy dla nich publicznych Service, jesli nie maja HTTP health/debug endpointu.

Jesli worker ma HTTP:

• tylko ClusterIP
• endpointy:
  • /healthz
  • /metrics
  • /debug/state

Read path dla markerow

Na start marker powinien czytac glownie z durable read modelu:

• dlob_hot_snapshot_latest
• dlob_hot_derived_latest
• dlob_hot_derived_ts
• dlob_all_derived_latest
• dlob_all_derived_ts
• dlob_stats_latest
• dlob_depth_bps_latest
• dlob_slippage_latest

To daje:

• prostszy kod
• mniej zaleznosci
• zgodnosc z tym, co widzi UI

Bezposredni odczyt z mevnode_sol RPC ma sens tylko wtedy, gdy:

• marker potrzebuje point read accountow
• marker potrzebuje szybszego feedu niz Postgres
• marker ma byc trading-critical, a nie tylko UI/debug

Write path dla markerow

Najbezpieczniejszy model:

• worker liczy marker
• worker robi upsert do market_markers_latest
• worker robi insert do market_markers_ts

Opcjonalnie:

• worker emituje event do market_marker_events, gdy zmienia sie band albo severity

Hasura

Hasura powinna trackowac:

• market_markers_latest
• market_markers_ts
• market_marker_events

Public read:

• tylko wybrane kolumny
• filtr po market_name
• opcjonalnie filtr po marker_name

To pozwala frontendowi robic:

• subskrypcje latest
• query historii per marker
• timeline eventow

Visualizer

Visualizer powinien miec trzy tryby prezentacji markerow.

1. Overlay na chart

Dla markerow typu line / band:

• fair value
• oracle dislocation bands
• micro support

UI:

• toggle per marker
• wspolny selector Indicators / Markers

2. Panele pod chartem

Dla markerow oscylatorowych:

• imbalance
• spread bps
• micro vol

UI:

• jeden panel moze pokazywac kilka serii
• albo osobne male panele

3. Market badges

Dla stanow:

• thin book
• wide spread
• high dislocation
• event risk

UI:

• nad chartem
• nad orderbookiem
• w market details

Co jest trading-critical, a co research-only

Trzeba to rozdzielic od poczatku.

Trading-critical

Markery, ktore moga wejsc do decyzji runtime:

• dislocation
• spread regime
• top book depletion
• aggressive imbalance

Dla nich:

• niski latency
• jasne SLA
• monitoring
• alerting

Research-only

Markery, ktore sa glownie dla obserwacji:

• eksperymentalne composite scores
• event overlays
• egzotyczne oscylatory

Dla nich:

• moga byc liczone wolniej
• moga siedziec w osobnych workerach
• nie powinny blokowac runtime

Rekomendowany rollout

Etap 1

Zrobic wspolne tabele:

• market_markers_latest
• market_markers_ts

oraz trackowanie w Hasurze.

Etap 2

Uruchomic 2 pierwsze markery:

• oracle_dislocation_bps
• top12_imbalance

Etap 3

Dorysowac to w visualizerze:

• 1 overlay
• 1 panel
• 1 badge

Etap 4

Dopiero potem dodawac kolejne markery.

Nie zaczynac od 10 workerow naraz.

Kontrakt implementacyjny workerow

Kazdy worker powinien miec:

• jeden glowny loop
• czytelny input set
• czytelny output set
• idempotentny write
• logging per cycle
• proste metryki Prometheus

Minimum metryk:

• marker_compute_duration_ms
• marker_last_success_ts
• marker_rows_written_total
• marker_failures_total
• marker_input_staleness_ms

Moja rekomendacja dla tego projektu

Na teraz najlepszy model to:

1. osobne workery markerow w k3s
2. wspolne tabele latest + ts
3. Hasura jako read layer
4. visualizer jako warstwa renderu
5. mevnode_sol RPC tylko dla markerow, ktore naprawde musza wyjsc poza aktualny read model

To jest wystarczajaco porzadne pod trade, a jednoczesnie nadal lekkie i szybkie do rozwijania.

Co warto zrobic jutro

1. Dodac SQL dla market_markers_latest i market_markers_ts.
2. Doliczyc pierwszy marker oracle_dislocation_bps.
3. Doliczyc drugi marker top12_imbalance.
4. Wystawic obie serie przez Hasure.
5. Narysowac je w visualizerze jako proof of workflow.