refactor(book-feeds)!: port the five venues onto the snapshot feed layer

[die-herdplatte]

The second of three PRs replacing #1440, and the one with the behaviour in it: #1554 is merged, and #1562 follows this one.

What is already merged

#1554 added the feed layer and nothing that runs: the SnapshotFeed trait, the Publisher an implementor is handed and cannot construct itself, a WebSocket loop and a polling loop, three ways to read a feed (BookFeedStream, BookFeedStreams, BookFeedWatch), and the book/ vocabulary — books, snapshots, price ladders, TVL conversion, component ids. Nothing implemented the trait, so no venue changed. None of that surface changes here.

What this PR does

Bebop, Hashflow, Liquorice, Native and Metric are ported onto that layer, and the path they used before — five per-protocol decoders, the wire-format round trip through TychoStreamDecoder, and the RFQStreamBuilder merge layer — is deleted.

• A feed owns its socket and is always polled, so a busy consumer can no longer starve the keepalive. That is the 1011 keepalive ping timeout a customer's Bebop connection kept closing with.
• Feeds emit simulate-ready states. Each client used to serialise its book into indexer wire format so TychoStreamDecoder could parse it back in the same process, which also announced every component as new on every update: 23–39 % less CPU, and ~576 re-additions per update become 0.
• One loop instead of five. 58 % of the five providers' non-test code implemented the same shared concerns, with five sets of defaults and defects, and fixes that only ever landed in one copy. It is now one WebSocket loop, one poll loop, one configuration, one price-ladder type.
• What is left per venue is its builder, its book source and its API client — which is the part of the diff worth reading closely.
• The venue-wide component layout of feat(simulation): RFQ venues as one component for all pairs with quote reuse rules #1501 comes along, rebuilt on this layer: all_pairs() on a venue's builder publishes it as one component for all of its pairs, held to a QuoteRule, with the directions it prices on the component. feat(simulation): RFQ venues as one component for all pairs with quote reuse rules #1501 merged while this was in review and wired that layout through the decoders and the client builder this PR deletes, so it is ported rather than merged.

What breaks, and what someone has to do

• Feeds, not clients. RFQClient, every *Client / *ClientBuilder and RFQStreamBuilder are gone. Build BebopFeedBuilder::new(book_config, usd_quote_tokens, ws_key).build()? — the config first, credentials as arguments. The tokens(), tvl_threshold(), quote_tokens() and poll_time() setters, and Native's from_env(), go with them.
• You compose the feeds. Nothing merges them any more: add each to a BookFeedStreams and read (provider, event), hold a single BookFeedStream, or keep a BookFeedWatch you borrow() when pricing.
• Two cases you did not have to handle before. Withdrawn means stop quoting that venue — a book is taken away once nobody is refreshing it, where the last one used to stand for the length of an outage. Ended says a provider stopped, and why; the merge task's result was dropped before, so a dead feed went unnoticed until someone saw stale prices.
• The library reads no environment. Credentials, min_tvl_usd and the USD quote-token set (book::quote_tokens::usd_stablecoins_for_chain(chain)) are all passed in. Metric's API key is required rather than optional.
• Every pair-keyed component id changes, and every state's serialized form with it, so recordings made before this do not replay. Metric is the exception — its component is a pool and keeps the pool address.
• Metric moved to pamm::protocols::metric and its state is no longer IndicativelyPriced, because v1 signs nothing. Its token map is both filter and metadata source, so pass the full map where an empty filter used to mean "every pool".
• States are opaque: no public constructors, no public fields and no accessors beyond HashflowState::min_amount_in() and, on the all-pairs state, the same minimum per direction. A book's pair is on the component beside it, component.tokens, in the orientation the venue published.
• Binding quotes come off the state: state.as_indicatively_priced()?.request_signed_quote(params).await.
• Native publishes a pair in address order, so some pairs come out with base and quote swapped relative to the orientation it used before.

Upgrading

Building a feed — before (main):

let client = BebopClientBuilder::new(chain, ws_key)
    .tokens(token_ids)           // HashSet<Bytes>, ids only
    .tvl_threshold(100.0)
    .build()?;
let builder = RFQStreamBuilder::new()
    .set_tokens(all_tokens.clone()).await
    .add_client::<BebopState>("bebop", Box::new(client));
let (tx, mut rx) = mpsc::channel(64);
tokio::spawn(builder.build(tx));
while let Some(update) = rx.recv().await {
    // Update { block_number_or_timestamp, new_pairs, states, removed_components, .. }
}

After:

let config = BookFeedConfig { chain, tokens: Arc::new(all_tokens), min_tvl_usd: 100.0 };
let usd = usd_stablecoins_for_chain(chain).expect("curated set for this chain");
let feed = BebopFeedBuilder::new(config.clone(), usd.clone(), ws_key).build()?;

let mut feeds = BookFeedStreams::new();
feeds.add(bebop::PROTOCOL_SYSTEM, feed).expect("one feed per protocol system");

while let Some((provider, event)) = feeds.next().await {
    match event {
        BookFeedEvent::Published(BookSnapshot { anchor, books }) => {
            for book in books.values() { /* book.component, book.state, book.updated_at */ }
        }
        BookFeedEvent::Withdrawn => { /* stop quoting `provider` until it publishes again */ }
        BookFeedEvent::Ended(SnapshotFeedOutcome::Failed(error)) => { /* gone; `error` says why */ }
        BookFeedEvent::Ended(outcome) => { /* ran out, or a bug in the feed task */ }
    }
}

Three complete consumers are in the diff: examples/book_quickstart, the integration test's book_stream_processor, and — outside this repo — propeller-heads/fynd#562, which ports the consumer side and lands once this is released.

Why the feeds look like this — the incident, the benchmark, the five copies

A customer's Bebop pricing socket flapped, and every flap replayed the whole book

A solver running Fynd on tycho-simulation 0.357.2 reported Bebop closing the pricing WebSocket every few minutes with 1011 keepalive ping timeout. The flapping sat on top of a cost that was already there: Bebop pushes its full book on every update (roughly 228 KB of protobuf every 1.7 s, about 130 KB/s), every update travelled through an encode → decode round trip and a bounded queue, and the stream layer reported the entire book as new_pairs on every update — 500-plus "new" components every couple of seconds, reproduced 1:1 on a release build. A consumer that applies each update under a write lock has to keep up with that or fall behind; each reconnect then re-delivered the whole book to a consumer that was already behind.

The closes themselves came from the shape of the stream. BebopClient::stream() was an async_stream generator feeding that queue, so the socket was polled only when the consumer polled. Once the consumer fell behind by more than Bebop's ~20 s pong deadline, the socket sat unpolled, the pong went out late, and Bebop closed the connection. Reproduced end to end: Fynd under a 5 % CPU quota plus quote load closed with exactly that frame every 100–130 s, with RFQ lag ramping past 200 s; at 10 % it kept up.

The socket now belongs to a dedicated feed task that is polled regardless of the consumer, and the consumer gets a watch channel holding the latest complete book. A stalled consumer wakes up to the newest book and nothing else; the socket never sees the stall. Regression test: snapshot_feed::ws::tests::answers_pings_while_the_consumer_stalls (#1554).

Benchmark. This work against 0.387.0, both driving Fynd against the live Bebop book on Ethereum. Release builds, slices alternating between the two sides so each sees the same market, warm-up discarded, three configurations from an idle consumer to the full on-chain protocol set pinned to two cores — the last of them run twice, three hours apart. The --protocols strings below are the ones both sides were given on the day.

configuration	slices per side	CPU s per steady minute	CPU saved	components announced as new per update
rfq:bebop alone	3 × 180 s	0.62 → 0.38	39 %	575 → 0
all_onchain,rfq:bebop	3 × 300 s	7.40 → 5.68	23 %	576 → 0
all_onchain,rfq:bebop, two cores	1 × 300 s	7.18 → 5.49	24 %	575 → 0
all_onchain,rfq:bebop, two cores	1 × 140 s	7.12 → 4.81	32 %	577 → 0

23–39 % less CPU for the same work — a steady 1.7 to 2.3 CPU-seconds a minute — at identical throughput and cadence: about 31 updates a minute roughly 1.95 s apart on both sides, and no book older than a second at apply time in any run. Peak RSS is 13 MB lower with only the book feed running, and within noise once an on-chain market dominates it.

Most of that is the round trip this PR deletes. On 0.387.0 the client emits a full StateSyncMessage snapshot per frame and TychoStreamDecoder reports everything in a snapshot as a new pair, so the consumer re-inserts all ~576 components and announces 576 additions to everything downstream, 32 times a minute, indefinitely. Here a component is announced once and later frames are state refreshes.

Five integrations that had drifted into five copies of the same loop

Reviewing the Native integration (#1244) against the four existing ones showed that the shared part of an RFQ integration — connect or poll, count failures, back off, filter by TVL, build components and states, read credentials, request a quote with retries — existed five times, with five sets of defaults and defects, and that in most cases one of the five already had the correct version.

Measured on main: 58 % of the non-test lines in the five provider directories implement those shared concerns, against a shared layer that barely existed — Hashflow's and Liquorice's retry loops, to take one pair, differ only in a comment and two auth headers.

The copies did not stay in sync. In the module's history every commit touching several providers is a mechanical refactor or a lint fix; not one behavioural fix was ever applied across providers, and ten fixes landed in exactly one copy while the siblings that need them still lack them.

Adding Native cost some 3,600 lines under rfq/: its builder and its decoder are near-verbatim copies of Hashflow's and Liquorice's, and over half of it is tests re-testing shared-shape behaviour.

Fixed here, because they are the shape of the loop rather than venue behaviour:

• Every client hand-rolled connect, reconnect, backoff and polling. Only Bebop counted failures and gave up (after ten); the four polling venues continued forever against a dead API, and no poll request except Metric's per-pool call had a timeout. One run_ws_feed and one run_http_poll_feed now drive every provider, with one FailureTracker, one WsFeedConfig / HttpFeedConfig, a request timeout on every poll, and a rejected zero interval (previously guarded by Native alone; tokio's interval panics on zero).
• Every builder carried chain, tokens, tvl_threshold and quote_tokens with its own setters and defaults; Metric's TVL floor defaulted to 0, the others to 100. One BookFeedConfig, taken by value by every builder.
• Bebop, Hashflow and Liquorice built a fresh reqwest::Client for every binding quote — a full TCP and TLS handshake inside the quote deadline; Metric already pooled. Each venue now has one pooled client, shared by its feed and by every state it emits, so the book poll and the quotes reuse the same connections. Native previously held a second pool for its orderbook poll.
• Every client derived Debug with its key in clear text and compensated by hand-writing Debug on the state. Credentials are now skipped where they live.
• The library read credentials and endpoints from the environment in five copies of the same reader plus Metric's builder and the Bebop origin variables from fix(rfq): send Bebop origin fields and accept router-mode quotes #1280. The library now reads no environment; credentials are constructor arguments.
• The level arithmetic (fill an amount level by level, invert a side, value a side, average price) existed four times, once per venue with a (price, quantity) ladder; only Native's copy guarded against non-finite results. One Levels newtype that every venue decodes its wire levels into at ingestion and that guarantees finite positive quantities and prices, and one book::sim for what every state does around it: direction detection, decimal scaling, the partial-fill result, checked limit conversion (three venues cast through u128). Component construction, pair ids, the token-universe lookup, the TVL floor check, the send/status/parse HTTP shape and the address conversion each had a copy per venue and now have one.

Left for follow-ups, because they change routing or quoting behaviour on live venues and belong in their own PRs:

• spot_price means three different things — the mid for Bebop, Native and Metric, the best level for Hashflow, the best whole-book average across makers for Liquorice — and only Native checks that the result is finite and positive.
• fee() and delta_transition() are todo!() in Hashflow and Liquorice.
• Bebop's TVL formula halves a one-sided book.
• Only Native checks a quote's expiry, recipient, payable value and calldata shape; the other three check the tokens and the input amount alone — Bebop's aggregate orders not even those, and Liquorice never the taker and receiver.
• The quote deadline covers the request but not the response body read, in Bebop, Hashflow and Liquorice.
• new_state claims an inexhaustible book: the state it hands back after a swap still holds the depth the swap consumed.
• Bebop measures TVL through a normalization of its own and picks the conversion book in HashSet iteration order, where Hashflow and Liquorice share book::tvl and Native picks the deepest book and prices the TVL amount rather than one unit. The planned fix is that shared normalization taking Native's rule, with Bebop on it.
• The quote deadline moves from the client to the caller.

Where repetition is legitimate and stays: WebSocket versus polling; two-sided books (Bebop, Native) versus one-directional level arrays (Hashflow, Liquorice) versus Q64.64 prices with cumulative depth (Metric); per-market-maker books for two venues only; Native's merge of mirrored orderbooks; and four irreducibly different signed-quote request shapes, Metric having none.

The RFQ path was co-opting TychoStreamDecoder

TychoStreamDecoder exists to turn indexer output — wire-format ComponentWithState with attribute byte maps, block headers, pending-state deltas — into ProtocolSim states. RFQ books are neither indexed nor block-anchored, and both ends of the trip lived in one process; nothing ever crossed a wire. This was conceptually wrong from the start and only became visible when it became expensive.

What it cost on main: every client serialised its bids and asks into JSON attribute bytes, and a per-protocol decoder.rs (285 to 377 lines each, five of them) parsed them straight back; the decoder rebuilt each state's quoting client from environment variables, silently dropping the builder's configuration — credentials, Bebop origin identification, quote timeouts (the #1280/#1281 finding); Update.block_number had to become block_number_or_timestamp and a TimestampHeader had to impersonate a block header, which produced a real downstream bug in a consumer that evicted overlays by treating the timestamp as a block number. The merge layer on top forwarded Updates whose removed_components each client computed against the book it had sent before. A removal is only meaningful to a consumer that applied every earlier update, so the layer had to be a queue that delivers each update exactly once — which is what tied the socket's fate to the consumer's pace. The new_pairs side was degenerate regardless: every client re-sent its whole book as snapshot states on every update, and the decoder reports every snapshot state as a new pair.

This PR deletes the decoders, the attribute round trip, TimestampHeader, rfq::stream and the RFQClient trait. Feeds emit ready-to-simulate books directly. Update.block_number_or_timestamp becomes a block number again in #1562, which is only correct once TimestampHeader is gone — which is why it comes last.

Design

#1554 has the SnapshotFeed contract, the Publisher an implementor is handed and cannot construct, the two transport loops, the three reader shapes, and the book/ vocabulary. What follows is what this PR adds on top of it.

Module hierarchy. rfq/ holds the binding-quote family (Bebop, Hashflow, Liquorice, Native) and the crate-private RFQError for the quoting path; pamm/ holds Metric, a pAMM that is priced off-chain but executed against the pool — Metric's own documentation describes pools that "quote off a live reference price instead of discovering price from their own reserves", with makers setting bid, ask and spread through a Price Provider contract ("PropAMM on demand") and trades reverting on a stale price.

The line between the two is who the counterparty is: a venue is an RFQ when a maker can decline a specific trade after pricing it and signs a commitment to that one trade, and a pAMM when its pool fills any taker who arrives with fresh price data, even data fetched per trade (pre-v1 Metric attached a signed oracle update and was a pAMM all along; an IndicativelyPriced state is a mechanism, not the family).

rfq/ and pamm/ depend on book/, never on each other; FeedError and RFQError are parallel enums with no conversion between them, and the two halves never call each other: the feed path (loops, sources, builders) only produces FeedError, the quoting path (request_binding_quote, validation) only RFQError, and each converts into SimulationError on its own. That matters because the two halves have different consumers: the encoders in tycho-execution need the states and their quoting clients at encode time and have no use for WebSocket and polling machinery, so the quoting half is what a later extraction into a shared crate would move, and this split keeps that move free of feed dependencies.

Per provider: feed.rs with the public <Provider>Feed and <Provider>FeedBuilder, a private client.rs, a private source.rs, and state.rs. The feed is { feed_config, source }, and its run is one call handing each half to its loop.

The line between client and source is what talks to the venue versus what interprets the answer. client.rs holds the venue's endpoints, its credentials and one pooled reqwest::Client, and it makes every request: the book poll or the WebSocket handshake the feed needs, and — where the venue signs quotes — the binding-quote request the emitted states make through an Arc to it. source.rs implements HttpSource (fetch) or WsSource (request + decode) and does the decoding, the orientation, the TVL measurement and the component and state building, returning a BookSnapshot stamped with the feed's clock. No source holds a credential or assembles a request.

Which chains a venue prices. Where the venue's requests name the chain — Bebop in its path, api.bebop.xyz/pmm/{chain}/v3, Native in a chain=ethereum query parameter — the list is ours: a <Venue>SupportedChain in the provider's models.rs, with build() refusing anything else. Where the API takes a chain id instead, the builder resolves the id and the venue itself answers, because a list of ours there could only repeat what the venue already knows and would refuse a chain it does price as soon as it drifted. Each of those three clients recognises its own venue's refusal in the body of the failing response, which snapshot_feed::http carries as a verdict every fetch takes, so what a failing status means stays the venue's to say. Both lists are measured against the venue's published API and held to it by an #[ignore]d test, rather than by a table that restates the match arms under it.

The snapshot_feed{provider} span a feed's logs are recorded in is raised by the consumer from the name it added the feed under, so nothing per-provider has to remember it and a venue is spelled once instead of twice with nothing keeping the two in step.

One component for a venue's pairs. A consumer that carries simulated state from one swap to the next does so per component, so a route can only be held to the number of quotes a venue signs for it if the venue is one component. all_pairs() on the four RFQ builders publishes it that way — taking the rule on the two that name their makers: the books behind it are the per-pair states the other layout would publish, book::all_pairs picks the best one still allowed to quote and records it as spent in the state the swap returns, and the component carries the rule (once_per_maker for the venues that name their makers, once_per_venue for those that pick them) and the directions it prices, since its token list is not its pairs. Per pair stays the default, and Metric has no quote to decline. This is #1501's feature on this PR's primitives: pricing, level validation, limits and the firm quote are the per-pair states' as everywhere else, which is why it is ~400 lines rather than the ~1 100 it replaced.

Where the ported layout differs from #1501. Selection, the quote rule and its attribute, the direction encoding, the per-maker scoping and the choice of a single maker's limits are the same; four things are not, and all four follow from this PR rather than from the layout:

• The component id is the venue's protocol system, rfq:<venue>, where feat(simulation): RFQ venues as one component for all pairs with quote reuse rules #1501 hashes "<venue>_<chain id>". A feed serves one chain and a consumer keys its components within one, so the venue is the whole identity; a pair's id adds its two addresses for the same reason, and neither hashes what it carries.
• The books keep the per-pair states' guards, which feat(simulation): RFQ venues as one component for all pairs with quote reuse rules #1501's reimplementation over flat price levels does not have: the zero-amount refusal, the four-ulp fill tolerance, ladder validation at ingestion, Bebop's dollar floor and Native's minimum in and out.
• A direction whose books are all empty is InvalidInput, not RecoverableError: it is what the per-pair states of this PR already report for a side nothing can fill, and a router reads it as "no larger amount works either".
• The component carries no TVL, because no Book on this PR does. A venue's books are filtered by min_tvl_usd in the feed before anything is published, which is the same threshold a consumer passed to the client before (fynd passes its --min-tvl to each RFQ client today, and reads component_tvl nowhere).

Feed defaults per venue. The feed configs have no Default: every builder exposes default_feed_config() with the values that fit its venue — the shared WebSocket set for Bebop, the shared polling set for Hashflow, Liquorice and Native, and Metric's own slower one, since its poll is a page of pool metadata plus a request per pool — and a consumer spreads from that, so a venue-specific default can never be dropped by an anonymous ..Default::default().

The quickstart, the integration test and fynd are the three complete consumer examples.

Breaking changes, grouped and then item by item

Grouped below; the per-item list with exact signatures follows. #1554 already landed the layer's surface — snapshot_feed::{SnapshotFeed, Publisher, SnapshotFeedStream, SnapshotFeedStreams, SnapshotFeedWatch, SnapshotFeedEvent, SnapshotFeedOutcome}, snapshot_feed::errors::FeedError, snapshot_feed::ws::WsFeedConfig, snapshot_feed::http::HttpFeedConfig, and all of book::{Book, BookSnapshot, ReceivedAt, BookFeedConfig, BookFeedStream, BookFeedStreams, BookFeedWatch, BookFeedEvent, BookFeedOutcome} with book::quote_tokens::usd_stablecoins_for_chain — and none of it changes here. What this PR adds to the public surface is the venues: a pamm module beside rfq, and per provider a module-level PROTOCOL_SYSTEM, <provider>::feed::{<Provider>Feed, <Provider>FeedBuilder} and state::<Provider>State (private fields, token accessors). The opt-in layout adds book::all_pairs::{QuoteRule, SWAP_DIRECTIONS_ATTRIBUTE, decode_swap_directions}, the four state::<Provider>AllPairsState, and all_pairs() on the four RFQ builders, which takes the rule on Hashflow's and Liquorice's. What it removes is everything the old path exposed, below. Everything else under book/, rfq/ and pamm/ is crate-private.

• A. Streaming surface — RFQClient, rfq::stream, TimestampHeader, per-protocol decoders, rfq::protocols::utils removed; pamm added.
• B. Provider types — *Client → *Feed, *ClientBuilder → *FeedBuilder with new(book_config, …) signatures for all five providers including Native, PROTOCOL_SYSTEM as module constants, Metric relocated to pamm.
• C. States — no public constructors (fields are pub(super); only the provider's own source builds its states), token accessors, changed serialized form; tokens outside the pair are InvalidInput everywhere (Bebop and Native's spot_price returned RecoverableError); MetricState no longer implements IndicativelyPriced (its v1 impl recomputed get_amount_out with an empty attribute map, and the Metric swap encoder never casts to the trait).
• D. Errors — FeedError for the feed path; RFQError stays the quoting path's error but is crate-private now, since no public signature ever carried it (states convert it into SimulationError); no conversion between the two.
• E. Configuration and constants — BookFeedConfig becomes every builder's first argument, no public default constants, no environment reads, auth helpers and BebopOrigins removed.
• F. Behaviour — see the behaviour-changes section below.
• G. Cargo — derive_more becomes a direct dependency; serde_with is a new optional dep of book-feeds (both were already in the lock; only the edge is new).

Per-item list — every API-visible change, with signatures.

A. Streaming surface

1. rfq::client::RFQClient removed (stream(), request_binding_quote()). Replacement: tycho_simulation::snapshot_feed::SnapshotFeed, added in feat(snapshot-feed): add the latest-value snapshot feed layer #1554. Binding quotes go through IndicativelyPriced on the emitted states.
2. rfq::stream removed, with it the only public item it held, RFQStreamBuilder. Consumers read feeds through SnapshotFeedStream, SnapshotFeedStreams or SnapshotFeedWatch (feat(snapshot-feed): add the latest-value snapshot feed layer #1554); book::{BookFeedStream, BookFeedStreams, BookFeedEvent, BookFeedWatch, BookFeedOutcome} are the same with the book types filled in. Producer-side new_pairs / removed_pairs diffs no longer exist — every snapshot is complete, so diffing is consumer bookkeeping.
3. rfq::models::TimestampHeader removed. A feed publishes book::BookSnapshot<A> { anchor: A, books: Arc<HashMap<String, Book>> } with ReceivedAt(pub DateTime<Utc>) on the feed's clock (no accessor; read anchor.0), and book::Book { component: ProtocolComponent, state: Arc<dyn ProtocolSim>, updated_at: Option<DateTime<Utc>> } is one pair's book. updated_at is the provider's clock: Some for Bebop (last_update_ts), Liquorice (newest maker's updatedAt) and Metric (server_ts), None for Hashflow and Native, whose payloads carry no timestamp.
4. Per-provider decoder modules removed (rfq::protocols::{bebop,hashflow,liquorice,metric,native}::decoder); feeds emit ready-to-simulate states directly.
5. rfq::protocols::utils removed. default_quote_tokens_for_chain is book::quote_tokens::usd_stablecoins_for_chain(Chain) -> Option<HashSet<Bytes>> since feat(snapshot-feed): add the latest-value snapshot feed layer #1554 (was Result<_, RFQError>; None means no curated set for that chain).
6. New public module pamm.

B. Provider types

7. Feed types renamed *Client → *Feed and moved to <provider>::feed: BebopFeed, HashflowFeed, LiquoriceFeed, MetricFeed, and NativeFeed (from feat: integrate native RFQ protocol #1244's native::client::NativeClient, which was feed and quoter in one). Each implements SnapshotFeed with Snapshot = BookSnapshot<ReceivedAt> and Error = FeedError. NativeClient::{PROTOCOL_SYSTEM, DEFAULT_ENDPOINT} → native::PROTOCOL_SYSTEM; the endpoint is private.
8. *ClientBuilder → *FeedBuilder, in <provider>::feed (client_builder modules gone). new() takes BookFeedConfig by value first:
   • BebopFeedBuilder::new(book_config, usd_quote_tokens, ws_key)
   • HashflowFeedBuilder::new(book_config, usd_quote_tokens, auth_user, auth_key)
   • LiquoriceFeedBuilder::new(book_config, usd_quote_tokens, auth_solver, auth_key)
   • NativeFeedBuilder::new(book_config, usd_quote_tokens, api_key)
   • MetricFeedBuilder::new(book_config, api_key) usd_quote_tokens: impl Into<Arc<HashSet<Bytes>>> is the USD-priced set the first four normalize book TVL into; Metric's API reports USD TVL, so its builder takes none. Metric's Bearer key is a required String (main: an Option read from METRIC_API_KEY inside the builder) — without it the bid/ask endpoint rejects every pool. Setters tokens(), tvl_threshold() and quote_tokens() are gone (configure on the config); Metric also loses quote_timeout() and api_key(), keeping base_url() and feed_config(). poll_time() is gone from all four HTTP builders: the cadence is HttpFeedConfig::poll_interval, set through feed_config() — and a call that raises it above the 30 s max_snapshot_age should raise that too, or the feed serves each book for 30 s and nothing until the next poll (item 24). Native loses from_env(). build() returns Result<*Feed, FeedError> (was RFQError).
9. The 7-to-9-argument *Client::new(...) feed constructors are gone; construct through the builders.
10. *Client types are gone from the public API. The name now denotes the crate-private client that talks to the venue (pub(crate) mod <provider>::client) — for the four RFQ venues that is also the quoting client, which their states reach through IndicativelyPriced; Metric's is held by its feed alone. A stale use …::client::BebopClient fails with "private module".
11. PROTOCOL_SYSTEM moves from associated consts to module constants: rfq::protocols::{bebop,hashflow,liquorice,native}::PROTOCOL_SYSTEM, pamm::protocols::metric::PROTOCOL_SYSTEM. Their values are unchanged: rfq:bebop, rfq:hashflow, rfq:liquorice, rfq:native, rfq:metric.
12. MetricClient::create_component_with_state removed.
13. Metric relocated: rfq::protocols::metric::* → pamm::protocols::metric::*. MetricState holds no client: v1's request_signed_quote computes locally and never used the one it stored, so the state no longer implements IndicativelyPriced (as_indicatively_priced() returns the default error). The crate-private MetricClient that talks to the API belongs to the feed alone.

C. States

14. The *State types have no constructor: fields are pub(super) and the provider's own source.rs writes the struct literal. All fields are private (were pub) — token identity is stored redundantly next to the raw book data and nothing re-validates it, so a field write could desynchronize direction matching, decimals or the quoting client. The only accessors are HashflowState::min_amount_in() -> BigUint and HashflowAllPairsState::min_amount_in(&Bytes, &Bytes) -> Option<BigUint>, the smallest its makers on that direction accept; a state's pair is read off the Book's component, whose tokens carry it in the published orientation. No accessors for the raw books either, and every provider's models and client modules are private.
15. Tokens outside a state's pair are rejected with SimulationError::InvalidInput(_, None) by every book state's spot_price, get_amount_out and get_limits (Bebop, and Native's spot_price, previously RecoverableError). Swap limits convert through a checked BigUint::from_f64 (Bebop, Hashflow and Liquorice cast through u128).
16. Price levels are validated at ingestion by the four venues that publish ladders (Levels, shared by Bebop, Hashflow, Liquorice and Native; Metric's depth model is its own and is untouched): a negative or non-finite quantity, or a non-positive/non-finite price on a level with quantity, rejects the whole response, and zero-quantity levels are dropped.
17. Native takes one entry per book side instead of concatenating; a second entry for the same pair, side and orientation is dropped with a warning.
18. The serialized form of every RFQ and Metric state changed. For Bebop, Hashflow, Liquorice and Native the client field now serializes the venue's client (its endpoints — the book ones as well as the quote one — plus timeout and origins; credentials and HTTP pool skipped) instead of the whole feed client; MetricState has no client field. BebopState serializes book (base, quote, last_update_ts, bids/asks as {price, quantity}) where main serialized the prost message with flat f32 arrays; NativeState's book nests its ladders and minimums under bids/asks. Recordings made before this branch do not deserialize.
19. The wire models of Metric and Native are private. MetricMetadata, MetricBidAskResponse, PaginatedMetadataResponse, MetricDepth, MetricDepthBin and q64_to_f64 have no public path, and neither does anything in native::models (public on main since feat: integrate native RFQ protocol #1244). Every provider's models module is private now.

D. Errors

20. snapshot_feed::errors::FeedError { Connection, Parsing, Fatal, InvalidInput } (from feat(snapshot-feed): add the latest-value snapshot feed layer #1554) is used by feeds, builders and Metric end to end.
21. rfq::errors::RFQError is crate-private (was pub). It is the quoting path's error, but every function returning it lives in a private module and the states convert it into SimulationError, so no public signature carried it. Variants unchanged, now Clone. There is no conversion between the two enums.

E. Configuration and constants

22. book::BookFeedConfig { chain, tokens: Arc<HashMap<Bytes, Token>>, min_tvl_usd: f64 } (added in feat(snapshot-feed): add the latest-value snapshot feed layer #1554) becomes required: it is the first argument of every feed builder. A plain struct with public fields, built as a literal, no setters. Tokens carry metadata (the builders previously took HashSet<Bytes> ids). Quote tokens are not on it and are not defaulted anywhere: pass book::quote_tokens::usd_stablecoins_for_chain(chain) to the four builders that take them.
23. The minimum TVL is required and named for its unit: min_tvl_usd (was tvl_threshold on the builders). Metric's implicit 0.0 default is gone, and there is no public default constant.
24. The library no longer reads the environment. Removed: rfq::constants::{get_bebop_auth, get_hashflow_auth, get_liquorice_auth, get_native_auth, BebopAuth, HashflowAuth, LiquoriceAuth, NativeAuth}, {DEFAULT_METRIC_API_URL, MetricConfig, get_metric_config}, and {BebopOrigins, get_bebop_origins}. rfq::protocols::utils::bytes_to_address is gone too, replaced by the crate's existing evm::protocol::utils::bytes_to_address. Credentials are constructor arguments; Bebop's origins are builder setters. rfq::constants is crate-private and no public default constants remain.
25. MetricFeedBuilder gains bid_ask_concurrency(NonZeroUsize) — how many of a poll's per-pool bid/ask requests run at once, default 16 — and its default_feed_config() is the one that is not the shared set: a 20 s cadence, a 15 s request timeout and a 60 s withdrawal age. Metric is the only venue whose poll is many requests (a page of pool metadata, then one per pool), so it costs more per poll and is given more time to finish one; measured live it reprices every 2-3 s against a poll that can take close to 9 s. The two in-repo consumers drop the overrides they used to pass.

F. Behaviour

26. See "Behaviour changes worth a heads-up" below.

G. Cargo

27. serde_with is a new optional dep of book-feeds and derive_more becomes an unconditional direct dependency. Both were already in the lock. serde_with also moves from an inline version in tycho-ethereum to the workspace; tokio-stream is pinned to the workspace version (same 0.1 line, listed for completeness); and tycho-integration-test gains tokio-stream and chrono.
28. tycho_test::execution::encoding::USER_ADDR is now pub (was a private const), so the integration test can identify its simulated flow to venues that screen origins.

Behaviour changes worth a heads-up

These compile without a change on the consumer's side and still alter what a running system does:

• Feeds retry forever by default (max_consecutive_failures: None); Bebop used to give up after ten consecutive failed connections. Only a fatal error ends a feed whatever the budget says, and fatal means no attempt can answer differently: an unsupported chain, an unbuildable request. A rejected credential is not one — it is fixed at the venue while the feed keeps trying, and the attempt that follows serves the book again without a restart. Giving up resolves the feed future with the error that ended it, classified as its source classified it, withdraws the published book and drops the sender; it never appears as an item.
• A chain the venue does not price ends the feed rather than being retried forever. Bebop and Native refuse it at build(), their endpoints needing a name for the chain that no chain id supplies; Hashflow, Liquorice and Metric resolve its chain id at build and let the venue answer, so the first poll's refusal ends the feed and withdraws its books. Bebop builds for the eight chains its API prices, where main built only for Ethereum and Base. On main Hashflow and Liquorice checked nothing and reached the chain through Chain::id() on every poll and every quote, which panics for a custom chain missing from the registry — so a chain they do not serve was an endless retry loop, and an unregistered one a panicking feed task.
• Metric refuses at build() a configuration it cannot run with. An empty trading key is InvalidInput: Metric answers an empty bearer token with the same Unknown chainId 404 it refuses an unserved chain with, where a key it rejects is a plain 401, so a feed started without one would read its own misconfiguration as the venue's refusal and end. A base_url() that is not a URL is InvalidInput too, where reqwest reports it once per request and the loop retries it for as long as the process runs.
• Latest-value semantics: a slow consumer observes only the newest snapshot per provider. There is no per-update queue and no back-pressure on the socket.
• WebSocket keepalive is serviced by the feed task independently of consumer reads.
• Binding quotes reuse one pooled HTTP client per provider.
• Metric's token set is both filter and metadata source. On main the client accepted an empty filter as "every pool" and the decoder then dropped any pool whose tokens were missing from its own, separately supplied token map; here one map does both jobs, so a consumer that relied on the empty filter passes its full token map instead and gets the same pools. Metric's per-pool bid/ask deadline is a fixed 5 s.
• Every pair-keyed book component id changes. An id is the protocol system and the pair's two addresses concatenated — rfq:bebop followed by the 20 bytes of each token — where main hashed a similar string with keccak256. Same information, no hash, and the protocol system instead of a bare venue name, so a venue that later gets a native integration cannot collide with its book feed. Hashflow's ids carry one more segment, the market maker's name, because a pair's makers are separate books (below). Metric is the exception: its component is a pool, not a pair, and it keeps the pool address. Ids recorded from main do not match any more.
• Every Hashflow market maker is its own book. A pair several makers quote used to be served as one component, keeping whichever maker the response iterated last — a different one per poll, with the rest of the venue's liquidity dropped — and the binding quote then went to the API at large, which could answer from a maker whose price the state never simulated. Each maker's ladder is a component of its own now, and its quote request names that maker and forbids the substitution. A consumer therefore sees several Hashflow components where it saw one, each with the depth of a single maker rather than an arbitrary one of them, and a route through one is settled by the maker that priced it.
• A Liquorice quote names the maker that priced it. Its component holds every maker quoting the pair, and get_amount_out fills against the one paying most — but the quote request named nobody, so the venue could answer with a level from another maker, on another maker's depth, at a price the route was never built on. The request carries the maker now and the response is filtered to it. Same defect as Hashflow's above, and still open on main, where the maker filter reached only the all-pairs path feat(simulation): RFQ venues as one component for all pairs with quote reuse rules #1501 added.
• A venue refusing one quote no longer marks the component as one to stop simulating. Every quoting failure reached the caller as SimulationError::FatalError, which says there is a bug with this pool or protocol and that it should not be simulated again — a connection that did not hold and a body that did not parse among them. Each lands by what it is now, and three refusals that are none of those are classified where they are read:
  • The trade the venue will not do is a missing quote: Hashflow's No maker supports this request and Exceeds supported amounts, Bebop's InsufficientLiquidity and MinSize. All four are an answer about one trade at one size, which the same book quotes at another. Neither venue publishes a catalogue of its codes, so a code they have not been seen to decline with stays fatal; what is known about each list is recorded beside it.
  • A status the venue refuses a quote with is a connection error for Hashflow and Liquorice, as it already was for Bebop. The request reached the venue, so the status is about this attempt — a rate limit, a gateway in between, a key to be fixed at the venue while the feed runs on. Both also read the status and dropped it, logging the body alone; it is in the message now.
  • Native's own classification of its documented codes into temporary failures, liquidity refusals and bad requests reaches a caller for the first time; it was flattened one call later.
    No consumer acts on the difference today: tycho-execution carries it into EncodingError variant for variant, and both in-repo consumers flatten that into a message. What changes is that a venue's verdict survives to the one deciding what to do about it. In the error counts of a deployment running the old classification, the three refusals above were the largest quoting failures by a wide margin.
• Native publishes a pair in address order. Main put a token on the quote side when it was the only one of the two in the configured quote-token set, and fell back to address order otherwise — so the emitted base and quote depended on the consumer's configuration and could flip mid-stream when that set changed, while the component id, already keyed on the sorted pair, stayed put. Some Native pairs therefore come out with base and quote swapped relative to main. Bebop, Hashflow and Liquorice still publish the orientation the venue sent.
• A feed withdraws its book when nobody is refreshing it: the watch goes back to None after the book is older than max_snapshot_age (both transports), or when the feed ends at all — giving up, or the consumer dropping the stream or watch running it — and the next book restores it. On main the last book stayed in place for the length of an outage. Consumers therefore have to handle None after the first snapshot, not only before it, and a consumer that only watches the channel still learns that a feed died.
• poll_interval (ex poll_time) starts from the same 5 s as main for every HTTP feed; a zero interval fails the feed immediately instead of panicking in tokio. It is a floor on the gap between two polls whatever a poll costs: one that outruns the interval is followed by the next as soon as it answers, and the cadence runs on from there — the intervals it ran through are not owed back as a burst of catch-up polls. A consumer that polls a venue more slowly than the 30 s default withdrawal age usually wants to move both knobs together, or every book is withdrawn before the poll that would refresh it; the feed warns rather than refuses, because serving a book only while it is fresh is a legitimate choice when the venue's rate limit fixes the cadence. The integration test pairs its three 30 s pollers with 90 s.
• Both transports back off while a provider keeps failing, sharing one failure counter. The socket doubles its reconnect wait from backoff_unit; a poller stretches poll_interval itself, waiting a multiple of it in place of the next tick, so the schedule is poll_interval doubled up to max_backoff_exp times — 5, 10, 20, 40 s on the defaults — and a recovered poll resumes the plain cadence rather than being followed by a catch-up one. On main no HTTP client backed off at all: a provider that was down or rate-limiting was polled every 5 s for the whole outage.
• Price levels are validated where they enter: a negative or non-finite quantity, or a price that is not finite and positive, rejects the whole response (a failed poll for Hashflow, Liquorice and Native, a dropped frame and reconnect for Bebop), the rule Native already applied on main. Hashflow, Liquorice and Bebop accepted such levels before; Liquorice also silently dropped malformed [price, quantity] pairs. Zero-quantity levels are dropped at ingestion for every venue (Native's [0, 0] placeholders were the only known producer).
• Native takes one entry per book side instead of concatenating. Its aggregated orderbook publishes each (pair, side, orientation) once — verified across all four supported chains, 194 entries, every key unique — so a side's ladder comes from the single entry that published it, and a second entry for the same side is dropped with a warning. feat: integrate native RFQ protocol #1244 appended them, which put the first entry's worst price ahead of the second's best (a fill walks a ladder in order) and counted the liquidity twice where two entries repeated each other, including in the TVL used for filtering.
• Metric fetches its pools' quotes concurrently, sixteen requests at a time by default. One poll is one request per pool, so walking them in sequence made a poll's duration grow with the venue's pool count until it exceeded the loop's whole-poll deadline — which discards every pool already fetched, not just the slow one. Measured live on Base: 4.4-6.9 s in sequence against 0.6-2.4 s concurrent for the same eight pools, and a pool that stalls now costs the 5 s of its own deadline instead of that plus every pool behind it.
• A Native API key the venue refuses no longer ends the feed. feat: integrate native RFQ protocol #1244 classified two of its error codes as unrecoverable; a credential is fixed at the venue while the feed keeps polling, and the poll that then succeeds restores the book without a restart.
• A Bebop trade worth less than a dollar is refused before it is quoted. Bebop will not sign one — MinSize: Request quotes over $1. — and nothing published said so, so a leg worth cents simulated clean and the refusal arrived at encode time, with the quote lost. BebopState now holds what one of its quote tokens is worth in USD, which the feed already works out to measure the book's TVL, and get_amount_out reads the trade's worth off the quote side. The floor was measured rather than assumed: bisecting the refusal on Ethereum and Base, in both directions and on three pairs, gives one dollar of the sell side everywhere, and the venue publishes no per-token minimum. In the base-to-quote direction the trade is valued at the maker's own price rather than at mid, so the floor sits half a spread high. Hashflow has held callers to its maker's first level all along; this is Bebop catching up, and BebopState's serialized form gains the price it needs to.
• Hashflow's advertised minimum is quotable. min_amount_in() scales the first level's quantity into base units and get_amount_out used to scale the caller's amount back down before comparing, which for roughly 5 % of 18-decimal quantities lands an ulp short and rejected a caller that asked for exactly what it was told to ask for. The floor is compared in base units against the value min_amount_in() hands out.
• Filling a ladder to exactly the depth get_limits reports is a complete fill. The limit goes out through atomic units and comes back a hair different — the round trip alone overshoots by up to one ulp — and fill used to leave that hair as an unfilled remainder, so get_amount_out at the advertised limit answered with an error instead of a quote. A remainder within four ulps of the input now counts as spent; a real shortfall is still reported.
• usd_stablecoins_for_chain returns None for chains without a curated set; previously an empty set silently filtered out every pair.
• Logging is structured tracing with spans. Every feed runs in a snapshot_feed span carrying the provider, so every event from a source or the loop is attributable; each HTTP fetch runs in a poll span and each decoded WebSocket frame in a ws_frame span, whose close timings give the cost of a fetch and of a decode. Binding quote requests run in a quote_request span with the pair and amount. Variables are fields, not message text (error, consecutive, component_id, books, …). Level changes: conditions the loop retries on its own (WebSocket read, decode and connect failures) log at warn, where main logged some of them at error; per-poll fetch counts and TVL-normalization skips are debug (Bebop and Native warned per pair per update). New events: info when a feed publishes a book while none was servable (first book, and every restoration after a withdrawal) and when a poll or connection succeeds after failures; debug per published snapshot after that, and per decoded frame with the venue's pair count where the source knows it.

Consuming the feeds, and what a deployment has to carry

Two things that used to be hidden are in the consumer's hands, and both are visible in the snippet:

• Withdrawal is a case. None in the channel — nothing servable — arrives as BookFeedEvent::Withdrawn, which the consumer has to name rather than skip with a continue, and which means "stop quoting this provider", not only "nothing yet".
• Termination is observable. Ended(outcome) is where the consumer learns that a provider stopped, and why — it gave up, it ran out, or its task died of a bug. On main the merge task's result was dropped, so a dead feed went unnoticed until someone saw stale prices.

In exchange the consumer decides how the feeds are consumed, where the merge layer forced one shape on everyone:

• One task per provider, no merging: SnapshotFeedStream::spawn(provider, feed) and read it, instead of a merged queue every provider had to share.
• Pull instead of push: SnapshotFeedWatch::spawn(provider, feed), keep a receiver() next to the router and read borrow() only when a route is being priced; no stream and no task of your own, and a reader cannot slow the venue's connection.
• Different cadence per provider: sample Hashflow every 30 s and react to every Bebop frame (the integration test does this by throttling per provider label).
• Restart policy: on Ended(_), rebuild the feed and add it again, or drop the provider for the session; on main the retry budget was the library's call.
• Feeds next to other streams: the same select! can hold the block stream, so books and on-chain state are consumed in one loop.

Requesting a binding quote is unchanged in principle and moves to the state: state.as_indicatively_priced()?.request_signed_quote(params).await. Additions and removals are the consumer's own bookkeeping: compare the snapshot's book ids with the previous view.

Deployment

Recorded component ids and states do not carry over. Every pair-keyed id changes (the new scheme is in the behaviour section), and every RFQ and Metric state's serialized form changes with it, so a saved market recording made before this fails to replay against the new states. The protocol-system strings are unchanged, so nothing in a deployment's configuration moves.

Open questions and follow-ups

• Both gitbook pages are retitled Off-Chain Priced Venues and lead with the family — books published by the venue — with the binding-quote material scoped to the four venues that sign. Their file paths, and so their published URLs (.../for-solvers/request-for-quote-protocols), stay: the repo has no .gitbook.yaml and no redirect map, and other docs deep-link those anchors. Cleaning the URLs wants a redirects entry and is its own change.
• One fix is open against this work, to review and merge after it: fix(execution): follow Liquorice to its current settlement contract #1487 follows Liquorice to the settlement contract it deployed on 2026-08-05, which is what the LiquoriceExecutor__InvalidSelector reverts under Verification are.
• Follow-ups without a PR yet: quote deadline and retries move to the caller (removes the quote_timeout setters); the price-level stream onto SnapshotFeed; the five-venue behaviour fixes listed under drift; a shared per-provider quote budget.
• Fynd's matching change is refactor(core): consume off-chain book venues as per-venue watch feeds fynd#562: it reads the venues through BookFeedStreams, keeps the ids each venue last published to derive additions and removals, and writes book updates to the base market state instead of relabelling the market with a timestamp.
• The header generic on the decoding path has a single instantiation after this PR: HeaderLike, FeedMessage<H>, StateSyncMessage<H> in tycho-client and TychoStreamDecoder<H>, TryFromWithBlock<T, H> (23 implementations) in tycho-simulation existed to let a TimestampHeader stand in for a block header on the RFQ path. Removing the parameter is mechanical but breaks the public API of both crates, so it is its own PR. refactor(protocol)!: rename Update.block_number_or_timestamp to block_number #1562 takes the one piece of it that is not: the Update field name.
• IndicativelyPriced names a pricing quality but is used as a mechanism: "this state needs a round trip to the venue before encoding, and the signed result goes into the calldata". Titan's price-level venues are indicatively priced too and do not implement it, while pre-v1 Metric implemented it to fetch a signed oracle update that was no quote. A name that says what the method does, and a return type not called SignedQuote, is a tycho-common change touching every RFQ swap encoder, so it is a separate design question.

Verification — automated, live per venue, and end to end

Automated. cargo +nightly fmt --all --check clean; cargo clippy --workspace --all-targets --all-features clean. tycho-simulation --lib: 1793 pass, the 18 failures RPC_URL-gated EVM tests this branch does not touch (simulation_db, the generic VM hook handler); tycho-integration-test 35 pass; tycho-execution 286 pass with 19 RPC_URL-gated failures of the same kind (permit2, the encoding integration tests).

Live, per provider. The rfq/, pamm/ and book/ suites run against the real APIs with credentials, network-gated tests included: 321 tests, 320 pass. Bebop's pricing socket and both quote shapes, Hashflow's poll and its binding quote, Liquorice's quote path, Native's orderbook and Metric across nine chains are all exercised. The one failure is Metric on HyperEVM, where the chain's only pool answers "priceProviderStatus": "feed_down" with bidAdj: 0 and no depth while an Ethereum pool quotes normally in the same minute — the venue declining to quote, which is what the test asserts against.

Live, end to end. One trade quoted on every venue inside the same minute, five times: 5 000 USDC → WETH on Ethereum. The size clears Hashflow's per-pair minimum and sits inside the depth every venue advertises.

sample	Bebop	Hashflow	Liquorice	Native	spread
1	1.967742	1.967414	1.966935	1.967621	0.041 %
2	1.964936	1.964632	1.964235	1.964798	0.036 %
3	1.965151	1.964725	1.964085	1.964892	0.054 %
4	1.965569	1.965249	1.964535	1.965181	0.053 %
5	1.969060	1.968462	1.968235	1.969022	0.042 %

Four venues, four wire formats, one ladder implementation, agreeing within 0.054 % on every sample and drifting together as the market moves — the strongest available check that the shared pipeline decodes, orients and fills correctly, since a venue-specific bug in any of those steps shows up as one column diverging.

Metric serves no Ethereum pools. On Base it prices tokenised equities against USDC, where 5 000 USDC buys 21.92 NVDAc against Bebop's 21.87 for the same pair in the same minute — the pAMM and the RFQ families cross-checking each other.

The venue-wide layout was quoted the same way: with --all-pairs, Hashflow's six per-maker components collapse into one and all four venues still answer the 5 000 USDC trade within 0.01 % of their per-pair prices.

Integration test, book feeds against tycho-beta, simulating, encoding and executing per sampled component. Two 900 s runs, one per layout, same flags (--skip-messages-duration 30), one process at a time:

	per pair (default)	all pairs
components seen	392	19
swaps executed, slippage measured	820	491
median slippage	+0.00 %	−0.00 %
slippage worse than −1 %	22	4
get_amount_out failures	4	0
get_limits failures	354	176
executor reverts	126	104
execution failures	2	2

The layout does what it is for: 392 components become 19 — one per RFQ venue plus Metric's pools, which stay one per pool — and a route is held to one quote per maker inside each. Fewer components is also why it executes fewer swaps: the harness samples at most --max-simulations directions per component and update, so collapsing a venue's books into one component bounds what one update can simulate.

It quotes what it advertises, and every failure in the table has a cause:

• get_limits refuses a one-sided book: tokenised equities (tGLD, QQQon, CRCLx, INTCon) and SYRUP, which the venue quotes in one direction only. RecoverableError("No liquidity") is the contract this PR gives an empty side, and the harness counts it because it asks every direction.
• get_amount_out refused 4 Hashflow swaps on USDC/USDT, each asking one atomic unit more than its book held. The run predates the fix in this PR, which is why the column still shows them. A book of a single level advertises that level as both its minimum and its depth; min_amount_in() rounded it up to a whole unit of the token while get_limits rounds the total down, so no size satisfied both and the harness asked the minimum. It rounds down now — a live maker signs one, two, ten and ninety units under its published level, and refuses half of it with code 79 — so the minimum is a size the book can fill.
• The reverts are two different things. 124 of 126 per pair, and 102 of 104 venue-wide, are LiquoriceExecutor__InvalidSelector() (0x8c4b1d97), which fix(execution): follow Liquorice to its current settlement contract #1487 fixes by following Liquorice to the settlement contract it deployed on 2026-08-05. The two Bebop ones per run are LimitAmountViolation() from Bebop's own settlement at 0xbeb0009a…: the venue enforcing the order's limit amount, which is the guard working.
• The two execution failures are the harness: its slot detector finds no balance storage slot for LDO, so the swap cannot be simulated.
• The slippage tail is 22 fills worse than −1 % per pair and 4 venue-wide, all Bebop, all on thin long-tail books — REQ, BAT and ZRX — at the harness's capped size of about 12 700 USD. The firm quote comes back materially under the indicative book there, worst −19.59 %. Whether that is the venue repricing a size its published ladder advertises, or our fill reading those ladders too generously, is not settled by this run: all three REQ fills landed at the same capped size, so there is no small-size comparison in it. Worth a targeted probe before anyone reads these books as executable at depth.

The benchmark numbers in the table at the top are from 2026-09-10 and stand as measured; everything in this section was measured on 2026-10-12.

🤖 Generated with Claude Code

[tamaralipows]

Thank you, a few bigger comments here. My main concern is the maker comment on hashflow/source.rs: please take a look at that one first.

[louise-poole]

These are the most important findings from my review. I'll follow up with the smaller findings in a separate review.

[louise-poole]

I agree - makes this cleaner and more consistent.

---

🤖 Suggestion

Both venues name their makers, and both now send the quote to the maker that priced it. Hashflow publishes one component per maker and pair. Liquorice publishes one component per pair whose state picks a maker inside: best_fill picks for the swap and the deepest maker sets get_limits. That is a second copy of the selection AllPairs::best and AllPairs::get_limits already do, and consumers see two shapes for the same kind of venue.

Publish Liquorice per maker and pair the way Hashflow does, and drop the multi-maker branch from LiquoriceState. Its all-pairs layout already builds single-maker states.

[louise-poole]

I like the consistency recommended here.

---

🤖 Suggestion

The PR says client.rs holds the venue's endpoints. Bebop and Metric do: they derive them in new from the chain and a base URL. Hashflow and Liquorice take full URLs from the builder, which pushes their constructors to seven positional arguments. Native keeps its base URL as a constant in feed.rs. The production Hashflow URLs are also pasted into four test call sites.

Use the Metric shape everywhere. new takes one base URL, the client derives each path from it, and the production base is a constant in client.rs. Tests keep injecting a mock server through the base URL.

[louise-poole]

I'm not sure if it is intentional that we cannot replay them? But this suggestion makes sense in that case.

---

🤖 Suggestion

The client: Arc<…> field is serialized with every state. Credentials are skipped, so a replayed state fails any quote anyway. Each deserialized Arc is a separate client with its own reqwest pool, so replay loses the pooling the PR adds. An all-pairs state of ~576 books also writes the same endpoints ~576 times.

Make the state's client an #[serde(skip)] Option<Arc<…>>, and have a missing client fail the quote. That says outright that a replayed state cannot quote, and recordings shrink.

[louise-poole]

Was this an intentional decision? I think the proposed fix here makes sense if this was not a purposeful choice to stop considering if the direction can actually be quoted.

---

🤖 Important

A solver reads the venue's list of tradable directions and adds each one to its routing graph. Some of those directions have no liquidity behind them. Every route through one fails at simulation, and the integration test logs a failure for each one it samples. Before this change, the list only named directions the venue was actually quoting.

Root cause: Each source writes VenueBook::directions by hand, but only the state knows which sides of its book have levels.

Symptoms (each would be resolved by the fix below):

• Behavior: Bebop and Native push both orientations of every pair, whether or not that side has levels. The deleted code from #1501 added a direction only for a non-empty side, and skipped books with neither. Native routinely builds one-sided books from a single entry. Its component therefore lists directions whose only book refuses with "Pool has no liquidity on this side", crates/tycho-simulation/src/rfq/protocols/bebop/source.rs:155–163, crates/tycho-simulation/src/rfq/protocols/native/source.rs:234–243
• Architecture: Hashflow and Liquorice restate the same fact a third and fourth time, so the four sources and the states' valid_direction_guard can drift apart, crates/tycho-simulation/src/rfq/protocols/hashflow/source.rs:145, crates/tycho-simulation/src/rfq/protocols/liquorice/source.rs:158

Proposed fix: Add fn directions(&self) -> Vec<(Bytes, Bytes)> to PairState, returning only the sides with levels, and have AllPairs read it. Drop the directions field from VenueBook, and skip a book whose state returns none. The bug goes away because the empty-side check lives in the state. The copies go away because no source writes directions any more.

[louise-poole]

Accurate error triggering is vital.

---

🤖 Suggestion

The MIN_TRADE_USD check runs before sim::fill_result. Selling base into a book with no bids fills nothing, so fill.amount_out is 0 and the swap fails with "Trade is worth 0 USD, below the 1 USD Bebop quotes". That is a RecoverableError about size. The other venues return the "no liquidity on this side" InvalidInput here, which is the single answer commit a698cd1 set out to give for this case.

A caller asks Bebop to sell a token on a pair where nobody is bidding. The error says the trade is too small. The caller raises the amount and gets the same error, at any size.

Check fill.remaining_in == amount_in first, or run the dollar floor only when fill.amount_out > 0.0, so an empty side reaches fill_result and gets its no-liquidity error.

[louise-poole]

Agreed - let's be more precise about how these errors should be presented to be handled. Will an immediate retry guarentee the same result? If so, it's not a recoverable error.

---

🤖 Suggestion

From<RFQError> for SimulationError now maps ParsingError to RecoverableError. Native reports a token, recipient, signed-amount or payable-value mismatch as RFQError::ParsingError, so these come out as RecoverableError. Bebop, Hashflow and Liquorice report the same checks as FatalError. Before this change every RFQError became FatalError, so all four venues agreed.

Native signs a quote for the wrong recipient or the wrong token. The caller is told the failure is temporary, so it retries the venue. Bebop, Hashflow or Liquorice returning the same bad quote is reported as permanent.

Return RFQError::FatalError from Native's validation mismatches in process_quote_response. Keep ParsingError for bodies that fail to parse.

[louise-poole]

Consistency.

---

🤖 Suggestion

updated_at is the max of the makers' updated_at, but LiquoriceState::get_amount_out prices against whichever maker pays most, fresh or not. The all-pairs layout takes the min on purpose, so a component "is no fresher than the stalest book behind it" (crates/tycho-simulation/src/book/all_pairs.rs:196–206). The same makers therefore report different ages under the two layouts.

An operator drops books older than a minute. A pair where one maker repriced just now and another went quiet an hour ago still looks fresh. Swaps on that pair can be priced off the hour-old maker.

Use .min() over the makers' timestamps, matching AllPairs::updated_at. Only use the freshest maker if the state stops quoting makers that are older than it.

[louise-poole]

All-pool failures should be handled as a fail.

---

🤖 Suggestion

A failed per-pool fetch_bid_ask is logged and skipped. When every pool fails (a revoked key gets a 401 on each one), fetch returns Ok with no books. The poll loop counts that as a success: it clears the failure streak and replaces the live snapshot with an empty one, and max_consecutive_failures never trips. SkipInvalidEntries refuses to let the other venues do exactly this ("a response that reads as nothing withdraws every pair").

An operator's Metric key gets revoked. The feed keeps running and keeps saying it has data, but it serves no pools. Nothing reports a failure, so it looks like Metric simply has no liquidity.

Fail the poll with FeedError::Connection when quotable was non-empty and every bid/ask request failed, so the failure budget and withdrawal apply. A mock server answering 401 on every bid/ask request would pin it in a test.

Scope: The deleted Metric client did the same, but this PR adds the failure budget and the empty-response rule this path skips.

[louise-poole]

Honestly I'd prefer we do not change the interface for something as minor as this... "book" is an action as well as a noun so makes names using it sometimes seem ambiguous...

---

🤖 Suggestion

--disable-rfq became --disable-rfq-feeds, --rfq-all-pairs became --book-all-pairs, and --run-pamm-protocols is gone. Clap rejects an unknown flag at startup. So a cluster job still passing --disable-rfq won't start the integration test at all, rather than just running with different settings. Nothing in this repo passes them, but the cluster configs live elsewhere 👀

Have you checked the deployed integration-test args? If they use the old flags, can we update them in lockstep with this release, or mention the rename in the PR's breaking-changes list so whoever deploys knows?

[louise-poole]

Yes - this docs claim is not consistent with Hashflow's design.

---

🤖 Important

In the per-pair layout, the Hashflow source keys each component by pair and market maker (maker_component_id in crates/tycho-simulation/src/rfq/protocols/hashflow/source.rs:68–75). A pair three makers quote now arrives as three components. On main they collapsed into one. A consumer who reads this page and keys its graph by token pair will see several components for one edge, and nothing on the page tells them so.

Say that Hashflow's default layout publishes one component per market maker and pair. The builder doc at crates/tycho-simulation/src/rfq/protocols/hashflow/feed.rs:101 already says so. Add it to the breaking changes the release notes list.

[louise-poole]

These are bulk AI findings: nice to have addressed, but they don't need much input. Feel free to point Claude at this review and let it work through them.

[louise-poole]

🤖 Suggestion

Every source matches on ComponentLayout, ignores the rule in the AllPairs(_) arm, then matches again after the loop to read it and build the venue component. That is four copies of the layout rule in a PR whose point is ending per-venue copies. A fifth venue, or a change to how the all-pairs book is assembled, has to land in four places.

Put a small collector in book/all_pairs.rs that the source builds from its layout. It takes each per-pair state with its id, maker and updated_at, and a finish() returns Books. The sources then never name ComponentLayout. A smaller step is to have all_pairs_book take the venue books and the rule and return Option<Book>, which turns each ten-line tail into one line.

[louise-poole]

🤖 Suggestion

Each venue's all-pairs wrapper is a copy of one block. It holds a constructor, the AllPairsState impl, ten ProtocolSim methods and IndicativelyPriced. Only the type names differ, plus Hashflow's minimum-amount check. Diffed with the venue names stripped, the Bebop, Liquorice and Native blocks are identical. That is about 360 lines, and a fix to one copy will not reach the other three.

typetag needs concrete types, but a macro_rules! can emit them. Have it take the wrapper and pair type and generate all four impls. impl_non_serializable_protocol in crates/tycho-simulation/src/serde_helpers.rs is the precedent. Give Hashflow's floor a hook, e.g. a defaulted AllPairsState::check_amount, or let Hashflow keep a hand-written get_amount_out.

[louise-poole]

Sounds reasonable. I'll leave it to you to decide.

---

🤖 Suggestion

A per-pair Hashflow or Liquorice component prices base into quote only, but its attributes say nothing about it. The integration test therefore keys on hashflow::PROTOCOL_SYSTEM and liquorice::PROTOCOL_SYSTEM. A Hashflow feed built with_fallback_router() publishes fallback:rfq:hashflow, misses that check, and gets simulated in a direction no maker quotes.

Have pair_book stamp SWAP_DIRECTIONS_ATTRIBUTE on a one-way pair, using the state's own directions. Consumers then read one attribute for both layouts and stop listing venues.

[louise-poole]

🤖 Suggestion

The PR body cites Hashflow's and Liquorice's retry loops as its example of copies that drifted. Both are kept, along with Bebop's, and this diff rewrites the same log lines and status handling in each copy. The deadline-versus-body-read gap the PR lists as a follow-up will need fixing three times.

Extract one helper that takes the deadline, the attempt count and a closure that sends one attempt and parses it. Do it here, since every copy is already touched, or name it in the follow-up list.

[louise-poole]

Would be cleaner

---

🤖 Nit

The three origin_* options always travel together from builder to client. Group them into one struct and bring the constructor down from six arguments to four.

[louise-poole]

🤖 Nit

snapshot_feed docs say "its task died" or name Panicked. Write "panicked" at these three sites.

[louise-poole]

🤖 Nit

Before: 2. Leverage Tycho Simulation to get the best quoted prices across them.
After: 2. Use Tycho Simulation to find the best quoted price across them.
Why: simplicity — "leverage" is an inflated "use".

[louise-poole]

🤖 Nit

Before: Only the two venues that name their market makers take a rule, because only there is there a choice to make; QuoteRule lives in tycho_simulation::book::all_pairs.
After: Only Hashflow and Liquorice take a rule, because only they name their market makers. QuoteRule lives in tycho_simulation::book::all_pairs.
Why: clarity — names the two venues.

[louise-poole]

🤖 Suggestion

A 9-line map entry became one paragraph that argues the design ("nothing else is its to get right"). An agent reading the guide to find where code lives has to read 34 lines to learn the file layout. The rationale already lives in the snapshot_feed module docs.

Keep the bullet to what lives where (SnapshotFeed, Publisher, the three consumer types, the two loops and their configs), one sentence each. Leave the reasons in the module docs.

[louise-poole]

🤖 Nit

Edits were spliced into wrapped lines without rewrapping: line 57 is 148 characters, while the book/ bullet at lines 82–86 breaks after 28. Rewrap the touched paragraphs at 100.