Struct PriceLevelStreamBuilder 

pub struct PriceLevelStreamBuilder { /* private fields */ }

Builds a stream of Updates from the Titan pAMM price level WebSocket.

A new builder serves no pAMMs: register the known venues via with_known_pamms, individual ones via add_pamm, or opt into serving unknown streamed venues via auto_detect; with_tokens provides the token metadata pairs are interpreted with.

One component is emitted per (pAMM, token pair), identified by the concatenation pamm ++ token0 ++ token1 (tokens sorted ascending), under the protocol system fallback:{pamm} — or pricelevelstream:{pamm} after without_fallback_router. The venue address is exposed through the PAMM_ADDRESS_ATTRIBUTE static attribute for downstream encoding.

Implementations

impl PriceLevelStreamBuilder

pub fn new() -> Self

pub fn auto_detect(self, enabled: bool) -> Self

Enables serving pAMMs that are not registered via with_known_pamms or add_pamm (disabled by default).

When enabled, any unknown streamed venue — except denied ones (see deny_pamm) — is served under its full lowercase hex address as the name, with the default gas cost. A venue’s protocol system therefore changes from the address form (pricelevelstream:{0xaddress}) to a name (pricelevelstream:{name}) once it gets registered — via add_pamm or a release’s default_served_pamms recognizing it; the name-independent identifiers — the component id and the PAMM_ADDRESS_ATTRIBUTE — stay stable across such renames.

pub fn auto_detected_gas_cost(self, gas_cost: BigUint) -> Self

Overrides the per-swap gas cost that auto-detected pAMMs (see auto_detect) are served with. Defaults to the maximum over the known venue profiles, as the conservative choice. Registered venues are unaffected — their gas cost comes from their PriceLevelStreamConfig.

pub fn endpoint(self, url: impl Into<String>) -> Self

Overrides the stream endpoint, e.g. to connect to a closer Titan region than the default (see https://docs.titanbuilder.xyz/propamms/takers). Without it, the TITAN_PAMM_PRICE_LEVEL_URL environment variable is used when set, else the built-in default.

pub fn connect_timeout(self, timeout: Duration) -> Self

Overrides how long a single connection attempt may take before it is aborted and retried (default: 10s), so a hung TCP/TLS handshake cannot block the stream forever.

pub fn read_idle_timeout(self, timeout: Duration) -> Self

Overrides the longest gap between parsed Titan frames tolerated before the connection is treated as dead and re-established (default: 10s). Titan pushes one frame per second and sends no keepalives, so a multi-second silence means a stalled or half-open connection. Control frames and unparsable text do not reset this timeout, and neither does the time the consumer spends between polls: the gap is measured while the stream waits on the socket.

pub fn max_backoff(self, max_backoff: Duration) -> Self

Overrides the cap on the exponential reconnect backoff of 2^attempt seconds (default: 32s).

pub fn add_pamm(self, config: PriceLevelStreamConfig) -> Self

Registers a pAMM to be served under the given configuration, overriding any default, denied, or auto-detected one for the same address.

Between add_pamm and deny_pamm for the same address, the later call wins; the defaults applied by with_known_pamms never override either, in any call order.

pub fn deny_pamm(self, address: Bytes) -> Self

Excludes a venue from being served: drops its current registration (default or explicit) and blocks auto-detecting it.

Between add_pamm and deny_pamm for the same address, the later call wins; the defaults applied by with_known_pamms never override either, in any call order — so denying a venue from the default set works whether the denial comes before or after with_known_pamms.

pub fn with_known_pamms(self) -> Self

Applies what is known about the streamed venues: registers the known-good ones (default_served_pamms) to be served and denies the known-bad ones (default_denied_pamms) — venues that stream quotes but whose swaps are not executable.

These defaults never override an explicit add_pamm or deny_pamm for the same address, regardless of call order.

pub fn with_tokens(self, tokens: HashMap<Bytes, Token>) -> Self

Provides the token metadata used to build components and interpret amounts. Pairs whose tokens are missing here are skipped.

pub fn without_fallback_router(self) -> Self

Keeps every venue on the direct pricelevelstream:{name} path, so swaps execute on the venues themselves and a stale maker quote reverts the route.

By default components are emitted under fallback:{name}, so tycho-execution routes their swaps through TychoFallbackRouter. Opt out when the direct call is what you want to measure or execute.

pub fn stale_after(self, duration: Duration) -> Self

Overrides how long a component stays served after the last accepted frame that carried it (default: 24s, two slots). A component no accepted frame has carried for this long turns stale and is emitted in removed_pairs; the next accepted frame carrying it re-adds it in new_pairs. Frames whose timestamp is this old or older are rejected. Independent of this setting, a state refuses to quote once its frame is one slot old (see without_quote_guard).

Values above MAX_STALE_AFTER are capped to it. A value shorter than the age frames arrive with rejects every frame as too_old, which the price_level_stream_frames_rejected_total counter and a WARN log show.

pub fn without_quote_guard(self) -> Self

Emits states that never refuse to quote.

By default every emitted state refuses spot_price, get_amount_out and get_limits once its frame is one slot (QUOTE_TTL) old: Titan quotes the block being built, and a venue rejects a fill against an older ladder as stale, so such a quote is not executable. Opt out only for a consumer that quotes a state more than one slot after it arrived by design — a batch simulator, a validation harness — and that accepts a quote the venue may no longer fill. The component still turns stale and is removed after stale_after, which then becomes the only bound on how old a quoted ladder can be. Never disable it on a live router.

pub fn build(self) -> impl Stream<Item = Update> + Send

Consumes the builder and opens the stream.

Components are emitted under fallback:{name}, so tycho-execution routes their swaps through TychoFallbackRouter, which retries a reverted pAMM swap — a stale maker quote reverts in any simulation against a mined block — on the fallback pool the solver names. without_fallback_router keeps them on the direct pricelevelstream: path.

The connection is established lazily on first poll and maintained (with reconnects) for as long as the stream is polled; it never terminates on its own, and dropping the stream closes the connection.

Every accepted frame yields an update with the states of the served pairs it carries, with new_pairs for pairs not currently served. The update does not mention pairs the frame does not carry, so consumers keep their previous state. A component no accepted frame has carried for stale_after turns stale and is emitted in removed_pairs, together with every other component turning stale at that instant, and re-added by the next accepted frame carrying it. Frames that are too old, from the future, out of order, or whose block regresses or jumps more than one block per elapsed slot plus 2 are rejected without effect. Frames that contain no served pAMM produce no update. Pairs whose tokens are missing from the provided token metadata are skipped.

Every update is stamped with the block its frame targets, a removal with the newest accepted block. Block numbers never decrease while something is served. Once every component has turned stale, the next accepted frame is judged as a first frame and may carry a lower block than the removal did: that is how the stream recovers from a frame with an implausible block, so consumers must not rely on the block number to order updates across such a gap. See the module documentation for the full contract.

Trait Implementations

impl Default for PriceLevelStreamBuilder

fn default() -> Self

Returns the “default value” for a type.