bStocks: Binance-sourced synthetic markets in /v2/rates

[stultusmundi]

Summary

Adds Binance bStocks (tokenized US equities on BNB Smart Chain) as synthetic
market entries in GET /v2/rates, sourced live from Binance's public Spot
API. Design spec: docs/superpowers/specs/2026-08-04-bstocks-integration-design.md
in the ZelTreZ repo (§4.2 covers this repo's contract).

• New Binance provider client (src/services/providers/binance.ts) —
  singleton, no API key, tokenised-asset list + Spot 24h/7d tickers, with a
  last-known-good ticker cache.
• New getBstockPrices() assembler (src/services/bstocks.ts) — intersects
  the BSC-listed tokenised-asset universe with TRADING-status Spot symbols,
  quoted in USDT (verified live — no USDC pairs exist), converts to BTC
  via the same ticker batch's BTCUSDT.
• Wired into zelcoreRatesV2.getAll() and served through the existing
  /v2/rates route.

Emitted ids: bstock-<assetCode lowercase> (e.g. bstock-tslab), always
tagged provider: "coingecko" — not "binance". The ZelCore client does
no provider-prefix parsing; it keys its market store on the literal string
${provider}-${id}, and the sibling api repo advertises each bStock's
coinInfo.coingeckoID as bstock-<code>. The two literals only meet if the
provider here is exactly "coingecko" — any other value misses silently,
with no error. This id/provider pairing is a cross-repo contract; do not
change it in isolation.

Please read before reviewing the diff

1. The positional-merge fix is the highest-impact change in this PR, and it
affects every provider, not just bStocks. The old mergeDeep in
apiServices.ts's serviceRefresher overlaid the freshly-fetched crypto
array onto the previous one by array index. That's only correct while
every provider block returns exactly the same row count in the same order.
When a block shrank (a provider outage, a delisted coin), two things broke:
fields from the old entry at that index leaked onto a different coin (e.g.
a CryptoCompare row inheriting CoinGecko's stale rank/change7d), and
entries past the new, shorter length lived on as stale duplicates. Because
the ZelCore client re-keys on ${provider}-${id} with last-write-wins, and
those stale duplicates sat after the fresh ones in the array, wallet users
were served the stale price on any refresh cycle where a provider
block's row count shifted. Reproduced with a concrete input (simulated
CryptoCompare outage: 40 duplicate keys, client resolved to the stale price
instead of the fresh one). Fixed by replaceCryptoByKey — a key-based
rebuild from the fresh fetch alone (dedup by ${provider}-${id},
last-write-wins, no merge with the previous array). Two behaviour changes
worth knowing: repeated provider+id entries collapse to one at the first
occurrence's position, and an entry the fetch no longer produces disappears
immediately instead of persisting from the previous cycle.

2. The crypto.length > 300 degraded-response guard now counts non-bStock
rows only. That floor exists to reject an under-strength provider response
before it overwrites good in-memory data. It was calibrated before bStocks
existed; the ~56 synthetic bStock rows would otherwise pad the count and let
a genuinely degraded CoinGecko/CryptoCompare/LiveCoinWatch response sail
past the guard, truncating /v2/rates for real assets.

3. Binance returns a halted symbol present, not absent, during a trading
halt (e.g. around a stock split) — with lastPrice: "0.00000000". Verified
live: 20/20 requested BREAK-status symbols came back present in the ticker
response, 9/20 of those priced at zero. An absent-symbol fallback would have
been dead code for this case, and accepting the zero would both serve a $0
price and poison the last-known-good cache. Prices are therefore accepted
only when finite and strictly positive (Number.isFinite(px) && px > 0),
both for what's served and for what's written to the last-known-good store.

4. npm run lint is a no-op repo-wide, unrelated to this branch.
npx eslint ./ --format json lints exactly one file, .eslintrc.js itself,
and zero .ts files — .eslintrc.js uses parserOptions.parser: babel-eslint with no TypeScript parser, and ESLint defaults to .js only.
Every "lint clean" claim in this repo's history is vacuously true.
npx tsc --noEmit is the only real static check and is clean on this
branch. Flagging as a follow-up; not something this PR fixes.

5. Pre-existing debt this PR does not fix: mergeDeep is still
positional for ratesV2.fiat, v1 rates, and marketsUSD in
apiServices.ts — the same stale-tail class of bug described in point 1,
just not yet observed to matter for those paths (v1 rates/marketsUSD are
value-not-array shaped per currency code, so the failure mode is different in
practice; ratesV2.fiat is a small, rarely-outaged list from a single
provider). Worth its own ticket rather than folding into this change.

Live verification (real, not simulated)

No automated test proves bStock entries actually reach /v2/rates against
real Binance, so I booted the service locally and hit the live endpoint.

Environment note: this sandbox has no paid CoinGecko Pro / CryptoCompare /
LiveCoinWatch API keys, and express-prometheus-middleware's prom-client
peer dependency is missing from package.json (pre-existing, unrelated to
this branch — flagging separately, not fixed here). To get a real listening
server for this verification I temporarily (1) installed prom-client
locally and (2) pointed config.coinGeckoUrl at CoinGecko's free public tier
instead of the paid pro-api host. Neither change is in this diff — both
were reverted before committing; they only existed long enough to prove the
real, unmodified /v2/rates code path end-to-end against live Binance +
live (free-tier) CoinGecko data.

Result, curl localhost:3333/v2/rates:

• 56 bstock-* entries, all provider: "coingecko", 0 entries
  tagged provider: "binance".
• 3 examples:
  • bstock-tslab: rates.usd 323.87, rates.btc 0.00504911,
    change24h -0.059, change7d 5.317
  • bstock-nvdab: rates.usd 216.12, rates.btc 0.00336929,
    change24h 3.511, change7d 9.29
  • bstock-sndkb: rates.usd 1411.78, rates.btc 0.02200954,
    change24h 6.242, change7d 27.286
• Sanity check against real share prices (fetched live, same session): TSLA
  $327.35 vs bstock-tslab $323.87 (~1% off); NVDA $215.61 vs bstock-nvdab
  $216.12 (~0.2% off); SNDK $1,435.69 vs bstock-sndkb $1,411.78 (~1.7% off
  — SanDisk was mid-surge on real HBF-standard news at query time, and the
  bStock's change24h/change7d reflect the same move).
• Total crypto array length: 420 (364 non-bStock + 56 bStock). Non-
  bStock entries are real, live CoinGecko data (bitcoin, ethereum,
  tether, binancecoin, usd-coin, ...) confirming bStocks are additive,
  not replacing existing coverage. errors: {"cryptocompare":true, "livecoinwatch":true} reflects the missing paid keys in this sandbox, not
  a bug in this branch.

Test plan

• npx tsc --noEmit — clean
• npx jest --runInBand tests/binanceProvider.spec.ts tests/bstocks.spec.ts tests/mergeCrypto.spec.ts — 24/24 passing
• Live /v2/rates verification against real Binance (+ free-tier CoinGecko) — see above
• npm run lint — no-op repo-wide, see point 4 above

Co-Authored-By: Claude Opus 5 (1M context) noreply@anthropic.com
https://claude.ai/code/session_01UnpQSycV6gfbF9JqRf4x1f

[stultusmundi]

Fixes from final whole-branch review

This commit (87b3888) addresses all 6 findings from the final review, plus the 3 test-coverage blind spots called out alongside them.

1. 24h/7d last-known-good collision (binance.ts) — lastGoodTicker was keyed on bare symbol, so getTicker24h/getTicker7d shared one fallback slot; whichever window last wrote silently overwrote the other's priceChangePercent/quoteVolume. Now keyed per ${window}:${symbol}; mergeTickers/lastGoodAgeMs take an explicit '24h' | '7d' window (omitting it on lastGoodAgeMs reports the freshest of the two).

2. Coins vanishing on a small-provider outage (apiServices.ts) — serviceRefresher rebuilt ratesV2.crypto from the fresh fetch alone once the >300-row floor passed, so a CryptoCompare (~39 rows) or LiveCoinWatch (2 rows) outage dropped those coins from /v2/rates entirely once the remaining providers alone still cleared 300. Fixed exactly as prescribed: carry forward only rows belonging to providers present in ratesV2Fetched.errors, then key-merge with fresh data last so fresh always wins.

3. Invisible total Binance outage + unbounded staleness (bstocks.ts / zelcoreRatesV2.ts) — every failure inside getBstockPrices is caught internally, so a total outage looked identical to a healthy refresh while quietly re-serving frozen prices forever. Added isBstocksDegraded() (true when a refresh prices zero symbols fresh while last-known-good is non-empty), wired into errors.binance, and bounded last-known-good to a new config.bstocksLastGoodMaxAgeMs (7 days — chosen because the outage this exists for, a stock-split halt, is naturally multi-day).

4. Binance outage slowing the whole refresh cycle (zelcoreRatesV2.ts / binance.ts) — getBstockPrices() is now raced against a 10s timeout at the call site, and getTokenisedAssets/getTradingSymbols negatively-cache a failure into longCache for config.binanceFailureCacheMs (60s) so the AxiosWrapper retry storm doesn't repeat every 30s cycle. Note: Promise.race never cancels the losing branch, so the timeout's setTimeout is .unref()'d — otherwise it holds the process open for the tail of the 10s on every healthy cycle (caught this via a lingering-timer test hang during verification).

5. No env kill switch (config/index.ts) — bStocksEnabled now reads process.env.BSTOCKS_ENABLED !== 'false' instead of a literal.

6. rank: 0 sorting bStocks ahead of Bitcoin (bstocks.ts) — rank is now omitted entirely (matching CryptoCompare's rows elsewhere in this repo) instead of hardcoded to 0.

Test blind spots closed: serviceRefresher (previously zero coverage) now has tests for the guard/carry-forward interaction; a total-outage case pins that getBstockPrices never rejects and correctly reports degraded; a multi-asset property test asserts the coingecko/bstock-<code> cross-repo id contract across 5 assets instead of 1.

Verification: npx tsc --noEmit is clean. Full suite (binanceProvider, bstocks, mergeCrypto, plus new config, serviceRefresher, zelcoreRatesV2 specs) is 37/37 passing. Each finding's test was confirmed to fail against the pre-fix code (via targeted git stash of just that file) and pass after — including two findings (3 and 6) that share a file, isolated via a surgical single-line revert to avoid conflating them. productionCompare*.spec.ts still fail for the pre-existing, unrelated reason (no local server on :3333).

🤖 Generated with Claude Code