Expand description
§evm-fork-cache-hypersync
Envio HyperSync source adapter and runnable durable event service for
evm-fork-cache.
The adapter compiles provider-portable owner interests into bounded HyperSync
queries, emits compact canonical-progress controls and matched logs, persists
opaque rollback state, recovers shallow reorgs explicitly, and wakes on
HyperSync height streaming with REST polling as a fallback. Provider-neutral
session, replay, and gRPC behavior lives in evm-fork-cache-event-service.
When a fresh engine receives its first rollback-guarded page, it also fetches
the immediately preceding compact block as a canonical anchor. Reorg controls
therefore contain only provider-proven block hashes, parents, and timestamps;
the adapter never persists a synthetic ancestor. Deep retained rollbacks locate
the exact common ancestor with logarithmic single-header probes before fetching
the replacement suffix, rather than issuing one replacement query per height.
HyperSync’s max_num_blocks and max_num_logs values are soft batching targets.
The adapter independently enforces configurable hard decoded-response ceilings
for block rows, log rows, and dynamically owned bytes before structural
validation, sorting, cloning, or normalization. Small provider target overshoot
is accepted; crossing a hard local ceiling fails with resource exhaustion.
These limits apply after hypersync-client has decoded its response; they do
not bound upstream HTTP/client-internal allocations, which require separate
process or proxy controls.
SSE archive heights are likewise treated only as fallible wakeup hints. REST
height reconciliation establishes every actual query target and recovers both
erroneously high hints and downward corrections.
Owner catch-up pages below the revision’s activation block advance only the opaque provider scan cursor and checkpoint; their normalized canonical head is empty, so they cannot advance runtime-global coverage. Because protocol v1 has no owner-scoped rollback control, a fork discovered while the previously delivered branch is still wholly pre-activation fails closed instead of emitting a global reorg or silently replaying a replacement owner branch. Start a fresh desired-state revision from an authoritative position to recover.
Full block-header interests are fail-closed by default. HyperSync client 1.4’s
block schema does not expose requests_hash, so it cannot reconstruct current
post-Prague Ethereum header RLP. Embedded deployments may opt a chain in only
after proving every consensus field is available and the reconstructed RLP
hashes to the provider’s block hash; the included binary does not opt in any
chain. Compact progress still exact-hash-pins lazy reads and installs NUMBER
and the provider-proven timestamp at the committed canonical head, but it
cannot supply BASEFEE, COINBASE, PREVRANDAO, or GASLIMIT; those
header-only fields are cleared. A caught-up event cursor proves event-state
coverage, not full-header readiness. Refresh a verified full header or live
source before any simulation that requires the complete EVM environment.
Run the service with:
ENVIO_API_TOKEN=... \
EVM_FORK_CACHE_EVENT_LISTEN=127.0.0.1:50051 \
EVM_FORK_CACHE_EVENT_DB=/var/lib/evm-fork-cache/events.sqlite \
evm-fork-cache-hypersyncUse bearer authentication and TLS together (or a trusted service mesh) across machine
boundaries. The included shared bearer token assumes one trust domain; use a
session-binding custom authorizer for mutually untrusted clients. The
bundled client trusts platform-native server roots; custom CAs or direct client
certificates require custom transport composition or a proxy/service mesh. The
binary refuses a non-loopback listener unless both direct TLS and bearer
authentication are configured, or
EVM_FORK_CACHE_EVENT_TRUSTED_MESH=true explicitly assigns missing encryption
or authentication to the mesh. It warns at startup when that escape hatch is
active. The
binary also caps durable SQLite identities at 65,536 by default; reuse stable
authenticated session ids and prune retired identities offline instead of
churning names. The
operations guide
documents all settings and recovery invariants. Review the
security policy,
including the narrowly scoped upstream Cap’n Proto advisory, before deployment
and every release.
Licensed under MIT OR Apache-2.0.
Structs§
- Canonical
Tracker - Bounded canonical block history used to locate and apply replacement forks.
- Delivery
Request - Durable, provider-neutral inputs for producing one source delivery.
- Desired
State Registry - In-memory authority for committed session desired state.
- Event
Service - Durable tonic event service.
- Event
Service Limits - Resource policy enforced before desired state reaches a provider.
- Event
Service Metrics - Lock-free operational counters shared by all service clones.
- Event
Service Metrics Snapshot - Point-in-time service health counters.
- Event
Source Error - Typed source worker failure surfaced through the versioned protocol.
- Hyper
Sync Data Source - Production chain-data boundary backed by Envio’s native Rust client.
- Hyper
Sync Source Factory - HyperSync source factory using one Envio API token across configured chains.
- Managed
Event Provider - Maintains one in-memory source engine per durable session while SQLite remains authoritative across process restarts.
- Persisted
Session - Durable state for one runtime session and chain.
- Reorg
Delta - Canonical suffix replaced by a newly observed fork.
- Session
Store - SQLite-backed session authority and delivery outbox.
- Source
Engine - One-in-flight source engine with at-least-once replay semantics.
- Source
Page - Provider-neutral page returned by a chain data source.
- Source
Response Limits - Hard local admission policy applied immediately after a provider response is decoded.
- Source
Resume - Durable state used to rebuild a source engine after process restart.
Enums§
- Canonical
Error - Canonical block history could not apply an incoming page safely.
- Desired
State Error - Desired-state validation or compare-and-swap failure.
- Event
Service Config Error - Invalid event-service construction parameters.
- Event
Source Error Kind - Stable classification for source failures. The public protocol exposes the class and retry disposition, never provider credentials or raw internals.
- Normalize
Error - Source data could not be represented by the event protocol.
- Query
Plan Error - Failure compiling portable interests into a HyperSync query.
- Session
Store Error - Durable session transition failure.
- Source
Engine Error - Source engine could not produce or commit an ordered delivery.
- Source
Error - External source request failure.
- Source
Page Error - A provider page violated the bounded, contiguous source contract.
Constants§
- MAX_
BLOCKS_ PER_ QUERY - Bound one provider response so catch-up remains resumable and deliverable over gRPC.
- MAX_
BLOCKS_ PER_ RESPONSE - Hard local block-row ceiling, independent of HyperSync’s soft query target.
- MAX_
COMPILED_ LOG_ FILTERS - Maximum number of distinct provider-side log filters compiled for one revision.
- MAX_
DELIVERY_ SIZE_ BYTES - Maximum encoded delivery accepted from this adapter before the gRPC envelope is added.
- MAX_
DYNAMIC_ BYTES_ PER_ RESPONSE - Hard local ceiling for provider-owned row and field bytes in one decoded response.
- MAX_
LOGS_ PER_ QUERY - Bound high-density log responses rather than relying only on a block span.
- MAX_
LOGS_ PER_ RESPONSE - Hard local log-row ceiling, independent of HyperSync’s soft query target.
Traits§
- Chain
Data Source - Async boundary around HyperSync, mockable at the external service edge.
- Chain
Data Source Factory - Factory for independently configured per-chain data sources.
- Event
Source - Provider-neutral source boundary used by the durable event service.
- Session
Authorizer - Connection-level authorization hook for bearer, mTLS, or gateway identity.
Functions§
- compile_
query - Compile one committed desired state into a bounded HyperSync query.
- normalize_
page_ unchecked - Normalize an already-admitted provider page into one ordered wire delivery.
Type Aliases§
- Chain
Height Stream - Provider-neutral stream of exclusive archive-height updates.