feat(zest): position scanner for v0-8-market, finds real liquidatable accounts

[mattglory]

Summary

Enumeration: positions live in v0-market-vault (the persistent shared vault contract), not the market contract itself — that's why v0-4 → v0-8 never needed a position migration. get-nr() = total registered accounts (1,334), lookup(id) gives {account, mask, ...} for each.

Pricing architecture, confirmed by reading resolve-pyth/resolve-callcode directly rather than guessed: only 3 real Pyth Lazer feeds exist in the whole protocol (u1 sBTC, u7 USDC, u45 STX) — every other asset (the 7 v0-vault-* zToken/share tokens, stSTX, stBTC) derives its price from one of these via a callcode multiplier (ztoken index, ststx ratio, stbtc ratio), not an independent feed. USDH prices via a separate DIA oracle call — its "ident" field is a Clarity-serialized string ("USDh/USD"), not a Pyth hash.

Liquidation eligibility read directly from liquidate()'s own health check, not inferred: current-ltv = debt-usd * 10000 / collateral-usd, liquidatable when current-ltv >= LTV-LIQ-PARTIAL (the egroup's own threshold for that exact position mask).

Real bugs found and fixed while building and testing this against live data

• cvToValue(cv, true)'s envelope behavior is genuinely inconsistent: a value bare at a function's own top-level return type (e.g. get-nr's plain uint, lookup's plain tuple) decodes with no {type,value} envelope; a value recovered from inside an unwrapped response/optional keeps one. Several decode sites assumed one pattern or the other without checking — normalized with a single uw() helper after confirming the actual shape of every call site empirically.
• STSTX-RATIO-DECIMALS was assumed to be 1e8 by analogy with STBTC's own ratio scale — wrong, it's 1e6, caught because the resulting stSTX price came out ~84x too low ($0.0046 instead of ~$0.46). Re-read the real constant directly rather than keep guessing from the wrong one.
• A full 1,334-account scan hit a bare ETIMEDOUT partway through — a transient network read timeout, not a rate limit, which threw directly out of fetch() and bypassed the JSON-parse-step retry entirely, killing the whole scan. Retry now wraps the fetch() call itself too. Also made the main loop resilient to a single account failing after retries are exhausted (logged and skipped, not fatal to the whole run).

Update: STX pricing fixed — no longer needs the Lazer entitlement at all

The original version of this PR was blocked on an external gap: this account's Pyth Lazer plan grants feeds 1 (sBTC) and 7 (USDC) but not 45 (STX) — confirmed by testing each feed individually ("Not entitled: feed 45"), requiring a loudly-warned STX_PRICE_USD8_FALLBACK manual escape hatch for every real run.

Checked whether a cheaper Lazer tier solves this instead of paying for Starter ($500/mo): it doesn't. Pyth Core (their free pull-oracle, Hermes) dropped Stacks support entirely on 2026-08-26 — Lazer is now the only Pyth product live on Stacks at all, and Lazer's own Free tier has no API access regardless.

But this scanner never submits anything on-chain — it only estimates risk off-chain — so it never actually needed Lazer's entitled feed in the first place. Zest's own v0-8-market already reads a second, independent oracle (DIA) for USDH; confirmed live that DIA also carries its own STX/USD feed (currently $0.3947, same USD x 1e8 scale as USDh/USD), free, no entitlement gate. Swapped the feed-45 Lazer call for a new fetchDiaStx() and removed STX_PRICE_USD8_FALLBACK entirely — no longer needed.

This does not help the real on-chain liquidate() submission (modes 3/4 of zest-v2-liquidation-receiver, PR #98) — Zest's own contract hardcodes verification against a genuine signed Lazer buffer for that call, so there's no substitute there regardless of cost. Only this scanner's off-chain estimation needed an alternative, and now has one for free.

Scope: this scans and flags candidates only — it does not liquidate anything. Exact liquidation sizing (how much debt to repay, the real bonus) uses Zest's own curve-based calc-liquidation-params, which this does not replicate; the receiver's own min-collateral-expected/min-profit checks are the real safety net for sizing precision, same as every other receiver built this session. Wiring a found candidate into zest-v2-liquidation-receiver's set-target/set-price-feed/flash-loan execution flow is a separate next step.

Test plan

• Run against the complete live dataset, not a sample: all 1,334 accounts, 1,039 correctly skipped (no debt), 295 fully evaluated with real collateral/debt/price/LTV computation, 0 failures, 0 liquidatable right now — a plausible healthy state for Zest's current borrowers, not an untested claim
• Verified the pricing math against hand-computed expectations at each step (sBTC/USDC/USDH/STX base prices, all 7 derived callcode prices) before trusting the enumeration loop
• Verified resilience fixes by reproducing the original ETIMEDOUT failure mode and confirming the full rerun completed cleanly
• node --check clean after the DIA pricing change; confirmed the exact get-value decode path against a live call (STX/USD → $0.394714, same field-access shape as the existing fetchDiaUsdh); confirmed no LAZER_TOKEN/feed-45/fallback references remain in the file
• Not re-run end-to-end against the full 1,334-account dataset with a live LAZER_TOKEN in this environment (none available) — the sBTC/USDC Lazer calls are unchanged from the already-verified prior run, only the STX source changed and was independently confirmed correct

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
web	Ready	Preview	Oct 12, 2026 5:40pm UTC

[mattglory]

Found and fixed a real reliability bug while running #102's keeper live: `readOnly()`'s `fetch()` call had no timeout at all. A long-running watch loop hung completely for 37+ minutes on a single stuck call -- 0% CPU, no open socket, zero log output, stuck on an `await` that was never going to resolve or reject on its own.

Wrapped the call in an `AbortController`, 20s. Verified in isolation against a deliberately unroutable address (the exact hang shape -- a connection that never responds, not one that's refused) that this actually throws a catchable `AbortError` instead of hanging forever. The existing retry logic already handled that case correctly; it just never got the chance to fire before.

Also synced this file's full `export` surface to match the keeper branch (only `uw` had made it back here before) -- no behavior change, just keeps this branch the single source of truth.

[mattglory]

Second reliability fix from running #102's keeper live: a transient Lazer feed timeout was killing the entire WATCH-mode process outright, not just failing one scan cycle. `fetchLazerPrices()` called `process.exit(1)` on that error -- correct for this script's own one-shot run, but `process.exit()` isn't catchable, so it bypassed the keeper's loop `try/catch` entirely.

Now throws instead; the one-shot `main()` still exits the same way via its existing top-level wrapper. The missing-token case stays a hard exit (permanent config error, not transient).

[mattglory]

@unixwhisperer #98 is merged. This one's next in the stack -- scanner only, no execution: finds liquidatable Zest accounts off-chain, doesn't touch the receiver. Same discipline as #98: pricing math/decode shapes verified against live calls, not assumed (full writeup in the PR body, including the STSTX-RATIO-DECIMALS and ETIMEDOUT-retry bugs it caught along the way).

One thing worth your eyes specifically: the STX-pricing switch from Lazer feed 45 to DIA -- this scanner never submits on-chain, so it doesn't need Zest's entitled feed, but want your confirmation that's a sound boundary (scanner estimates off DIA, the receiver in #98 still verifies against a real signed Lazer buffer on-chain, nothing crosses that line).

Ready for review whenever you have a minute.

[unixwhisperer]

Looks good overall. The pricing derivation and LTV formula match v0-8-market, and the timeout, no-process.exit and diagnostics fixes are the right calls.

One fix before merge: getCollateral/getDebtScaled (L397-408) turn any error into 0n, including readOnly running out of network retries, not just the documented "no entry" case. A collateral read that fails this way gives collateralUsd = 0, so currentLtv = BPS, and the account is flagged as liquidatable (L461-465). The keeper would then arm a healthy position and burn gas until Zest rejects it with ERR-HEALTHY. Please return 0n only for !res.okay and rethrow network errors. lookup (L372-378) should count its failures the same way instead of dropping the account silently.

Minor: STX is priced from DIA here, but Zest checks against Lazer feed 45 on-chain, and near the threshold the two can disagree. Before anything acts on a candidate close to the threshold, I'd require a small margin (say 50 bps) over LTV-LIQ-PARTIAL.