newHeads and logs streams and
attempts bounded recovery when an upstream fails. An open socket or a successful
subscription response does not prove that your application received every event.
Use WebSocket endpoints for connection examples and
Supported methods for the released method contract.
Configure the provider pool
Configure both HTTP and WebSocket endpoints for providers that support your chain and workload. Providers inherit the chain’ssubscribe_new_heads setting,
which defaults to true; set a provider override to false if it must not
serve newHeads. A usable WebSocket connection is still required. See
Provider configuration.
Identical subscriptions can share upstream work. Different log filters can
create distinct streams, and HTTP replay consumes upstream requests. A high
client-to-upstream sharing ratio does not establish capacity for many distinct
filters or dense logs. Shared resources do not create quota isolation.
Recovery behavior
Recovery establishes a replacement live subscription, buffers incoming events, and uses HTTP to replay the missing range. HTTP replay and WebSocket delivery can use different eligible upstreams. The coordinator merges replay with its buffered live events and suppresses overlap within retained deduplication state. Recovery has a deadline, a replay allowance, an attempt budget, and a memory bound. Buffer exhaustion terminates the affected downstream connection; it does not silently discard the oldest buffered event and claim uninterrupted delivery. Unavailable history, failed replay, or exhausted recovery can also terminate continuity. The application must reconnect and reconcile its durable checkpoint. Use the v0.5.0 configuration reference for supported configuration keys. The released stream coordinator is the implementation reference. Internal process defaults are not necessarily YAML settings, and increasing a limit cannot supply missing provider history.Application checkpoints and reorgs
Persist the last successfully processed block and its hash outside the socket connection. Handle reconnection andremoved log events. Reconcile your state
against canonical blocks after an outage or reorg; block height alone cannot
distinguish a replacement block from the one your application processed.
In v0.5.0, buffered orphan-log additions and removals drain in their original
per-log order before replacement-block additions, including across block heights.
Positive and removed events have separate deduplication state. Repeated removal
and re-addition of the same log within that window is not fully modeled; reconcile
against canonical state when that sequence occurs.
Do not infer lossless or exactly-once processing from multiplexing or replay.
Verify the received sequence for removed and replacement logs, replay/live
overlap, and sparse filters against the exact released artifact you deploy.
Keep application-fetched repairs separate from events delivered by Lasso when
reporting recovery results.
Qualify your workload
Before production adoption, exercise the intended chain, provider pool, filter cardinality, event rate, and downstream consumption rate:- Confirm real block or log notifications after establishment.
- In an isolated environment with test-owned upstreams, interrupt the active upstream and retain received frames through recovery.
- Compare frames with the expected blocks and logs, including removals and replacement events during a controlled reorg.
- Exercise slow consumers, unavailable HTTP history, and recovery exhaustion. Confirm your client notices termination and restores its checkpoint.
- Restart or replace your Lasso instance and measure application recovery.