[onajidavid87-web]

Summary

Prevents volume overstatement caused by double-counting trades routed through aggregators:

• Venue Registry Classification: Added VenueClassification (primary | aggregator) to VenueAdapter. Classified SDEX, AMM, and soroswap_amm as primary markets, and aquarius_amm as an aggregator.
• Labelled Net & Gross Totals: Updated /volumes/:asset to report labelled totals: { net, gross }, netVolume, grossVolume, and trade counts (netTradeCount, grossTradeCount). totalVolume defaults to netVolume to preserve backward compatibility without volume inflation.
• Documentation: Documented classification rationale in docs/venues.md and referenced in docs/architecture.md.
• OpenAPI Schema: Updated VolumeResponse in openapi.yaml and regenerated openapi.json.
• Test Coverage: Added fail-first test verifying volume separation for pairs traded on both primary and aggregator venues, alongside registry contract tests.

Related issue

Type of change

• Bug fix
• New feature
• Refactor
• Docs
• Tests
• CI / tooling

Checklist

• I have read CONTRIBUTING.md
• npx tsc --noEmit passes
• npm run build passes
• I added / updated tests where relevant
• I updated docs where relevant

Closes #244

[drips-wave]

@onajidavid87-web 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]

Needs a rebase, and two of the conflicts are design decisions rather than merge noise — so they are yours to make, not mine.

Conflicts: src/ingest/venues/types.ts, src/routes/volumes.ts (3 hunks), plus the two generated OpenAPI files.

1. Two names for the same concept. main now has:

/** Kind is descriptive metadata used by API projections, not the runner. */
readonly kind?: VenueKind

and this PR introduces:

readonly classification: VenueClassification

Same idea, different name, different type, and yours is required where main's is optional. One of them should survive. I would keep one field and one vocabulary rather than have adapters carrying both — but which one is a call for whoever owns the venue model, and required versus optional is the part that actually changes behaviour: a required field forces every existing adapter to declare itself, which is probably what you want and is also the breaking half.

2. The volume query changed shape underneath you. main's handler reads a single row and derives trade_count, total_volume and a status of no_trades / no_positive_volume / ok. Yours loops over rows accumulating net and gross per venue. Those are different SQL and different response semantics, not two spellings of one thing.

I did not resolve this, deliberately. Picking a side would produce an endpoint that returns numbers — and a wrong volume total is the worst kind of wrong, because it looks entirely plausible and nothing fails. You know which query your net/gross split needs; please rebase onto the current handler and reconcile them.

The feature is worth having. Reporting net against gross is a real distinction: counting both sides of a trade, or the same flow across two venues, inflates a figure people compare across venues. Separating primary from derived venues is the right basis for it.

When you rebase, worth adding a test that pins the difference explicitly — one trade visible on two venues should contribute once to net and twice to gross. That is the case the whole change exists for, and it is the one that would silently regress.

[Miracle656]

Merged as 1a332bb — this closes #244.

The issue says "every ecosystem volume figure that has ever been wrong has been wrong for exactly this reason", and the fix treats it with that weight. Reporting both numbers and labelling them is better than silently picking one: a caller who wants gross can still have it, and nobody is guessing which they were given.

Things that were already right and I left alone:

• classification is a required field on VenueAdapter. A new venue cannot be registered without stating what it is, which is the same reason type and description are required. The alternative — an optional field defaulting to primary — would make every forgotten aggregator a silent double-count.
• Distribution statistics stay on gross. Median, HHI and the concentration status describe what was observed, and recomputing them on a filtered set would make them mean something else. The comment says so, which is why I did not have to ask.
• SUM(volume)::float8 casts outside the aggregate. Casting inside is the Prices are stored to 18 decimal places and computed as floats #230 bug — every row to a double before summing, with order-dependent error. You got the form right; worth knowing it is wrong in seven other files, which fix: keep numeric through aggregation and cast once at output #470 is for.
• docs/venues.md gives per-venue reasoning rather than a bare table, and the DeFindex entry ("holds no market of its own: deposits are allocated to underlying strategies... so it is never counted toward net volume") is the kind of thing that stops someone reclassifying it in six months.

Two changes on top, both about the same risk. This field decides whether a venue's volume reaches a published total, so two records of it must not be able to disagree quietly.

1. The hand-maintained map outranked the adapter

const match = VENUE_CLASSIFICATIONS[sourceOrName]
if (match) return match.classification
// ...only then...
const adapter = venueAdapters.find(...)
if (adapter) return adapter.classification

The map came first, so a stale entry would silently override the declaration the compiler enforces. That is the wrong way round: classification on the adapter is the fact a venue author cannot omit and the thing the ingester actually ran under; VENUE_CLASSIFICATIONS is prose maintained by hand beside it.

Inverted, with the precedence and the reason now written into the function. I also documented why an unregistered source still defaults to primary: price_points.source carries values with no adapter behind them (CEX feeds), and those are genuinely independent markets — so defaulting to aggregator would wrongly exclude real volume.

2. Nothing caught drift between the two

The new tests assert named venues:

expect(isAggregatorVenue('aquarius_amm')).toBe(true)
expect(isPrimaryVenue('SDEX')).toBe(true)

Those are good as regression tests for today's four venues, but they do not hold the invariant. A new adapter added next month with no map entry, or with a mismatched one, fails nothing — and the failure mode is a wrong number on a public endpoint, not an exception.

Four tests now hold it over venueAdapters as a whole:

• every adapter has a VENUE_CLASSIFICATIONS entry whose classification matches, reported as a list of disagreements rather than a bare boolean;
• every adapter has documented reasoning;
• getVenueClassification returns the adapter's own answer for both its source and its name;
• an unregistered source resolves to primary and never to aggregator.

The first is the one that matters: it fails the build on the disagreement instead of letting the runtime pick a winner.

One housekeeping note

The PR changes openapi.yaml for the new totals shape, so clients/typescript/src/schema.d.ts needed regenerating — it is byte-compared in CI. For next time, a spec change needs all three:

npm run openapi:gen
npx --yes openapi-typescript@7.13.0 openapi.yaml -o clients/typescript/src/schema.d.ts
npm run readme:gen

130 test files / 1,571 tests pass; tsc --noEmit clean.