[decrypted-dev]

Closes #283

Summary

Defines liquidity in the OpenAPI spec and route documentation, validates that the underlying query calculation matches the definition, and names the unit in the response.

Details & Specification

• Definition: For each watched pair on the selected network, liquidity represents total AMM reserves denominated in the quote/counter asset (asset_b), computed across all active liquidity pools (source = 'AMM') as:
  $$\sum (\text{reserve_a} \times \text{spot_price} + \text{reserve_b})$$
  evaluated at each pool's latest snapshot spot price.
• Unit: Denominated in the quote asset (asset_b), exposed explicitly as liquidity_unit on each row (e.g., USDC for XLM/USDC).
• Network Scoping: Echoes network in the top-level /screener response and documents ?network= in openapi.yaml and openapi.json.
• Number Changes: No numeric change was required to the stored calculation, as (ps.reserve_a * ps.spot_price + ps.reserve_b) already faithfully evaluates total liquidity in units of asset_b.

Verification

• npm test src/__tests__/screener.test.ts: Passes all 18 tests, including tests verifying the SQL formula structure and liquidity_unit naming.
• npm test tests/openapi.test.ts: Passes and verifies OpenAPI parity.
• npm test: Full test suite passes (631 passed).

[drips-wave]

@decrypted-dev Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[Miracle656]

Screened against current main and this does not pass on its own branch, so a rebase alone will not fix it.

Merged alone it gives type errors against main. Run npx tsc --noEmit on a fresh rebase and you will see them.

Please rebase, get npx tsc --noEmit and npx vitest run both clean locally, and re-request. I would rather take this than not — it is held on correctness, not on wanting it.

[decrypted-dev]

Screened against current main and this does not pass on its own branch, so a rebase alone will not fix it.

Merged alone it gives type errors against main. Run npx tsc --noEmit on a fresh rebase and you will see them.

Please rebase, get npx tsc --noEmit and npx vitest run both clean locally, and re-request. I would rather take this than not — it is held on correctness, not on wanting it.

done boss
please review and merge

[decrypted-dev]

Screened against current main and this does not pass on its own branch, so a rebase alone will not fix it.

Merged alone it gives type errors against main. Run npx tsc --noEmit on a fresh rebase and you will see them.

Please rebase, get npx tsc --noEmit and npx vitest run both clean locally, and re-request. I would rather take this than not — it is held on correctness, not on wanting it.

review and merge boss

[Miracle656]

Merged to main as c9ed2d3. The earlier type errors are gone and it's clean against current main.

This is a better change than its title suggests. /screener was reporting a liquidity number with no stated unit, source or formula — which makes it uninterpretable: a consumer can't tell whether two rows are comparable, or even what currency the figure is in.

Putting liquidity_unit on each row is the part that matters. Documenting the definition in a comment helps whoever reads the source; shipping the unit with the data helps everyone who doesn't. Naming the network in the response is the same instinct.

The formula comment is correct, which I checked because this is exactly the kind of note that gets written down wrong. spot_price is asset_b per asset_a, so reserve_a * spot_price is reserve_a valued in asset_b — and for a constant-product pool that equals reserve_b, making the sum the whole pool's value in quote terms rather than a double count. Deriving the unit from pair_key.split('/')[1] with a 'quote' fallback is a reasonable way to get there without a second query.

One thing I did on merge: regenerated clients/typescript/src/schema.d.ts. Since #403 landed earlier today, any PR touching openapi.yaml also has to update the generated client or CI's git diff --exit-code -- clients/typescript fails. Worth knowing for your next one — npm run client:gen.

Lens: 115 files, 1,423 tests passing, typecheck clean.