Skip to main content

Crate evm_fork_cache_hypersync

Crate evm_fork_cache_hypersync 

Source
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-hypersync

Use 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§

CanonicalTracker
Bounded canonical block history used to locate and apply replacement forks.
DeliveryRequest
Durable, provider-neutral inputs for producing one source delivery.
DesiredStateRegistry
In-memory authority for committed session desired state.
EventService
Durable tonic event service.
EventServiceLimits
Resource policy enforced before desired state reaches a provider.
EventServiceMetrics
Lock-free operational counters shared by all service clones.
EventServiceMetricsSnapshot
Point-in-time service health counters.
EventSourceError
Typed source worker failure surfaced through the versioned protocol.
HyperSyncDataSource
Production chain-data boundary backed by Envio’s native Rust client.
HyperSyncSourceFactory
HyperSync source factory using one Envio API token across configured chains.
ManagedEventProvider
Maintains one in-memory source engine per durable session while SQLite remains authoritative across process restarts.
PersistedSession
Durable state for one runtime session and chain.
ReorgDelta
Canonical suffix replaced by a newly observed fork.
SessionStore
SQLite-backed session authority and delivery outbox.
SourceEngine
One-in-flight source engine with at-least-once replay semantics.
SourcePage
Provider-neutral page returned by a chain data source.
SourceResponseLimits
Hard local admission policy applied immediately after a provider response is decoded.
SourceResume
Durable state used to rebuild a source engine after process restart.

Enums§

CanonicalError
Canonical block history could not apply an incoming page safely.
DesiredStateError
Desired-state validation or compare-and-swap failure.
EventServiceConfigError
Invalid event-service construction parameters.
EventSourceErrorKind
Stable classification for source failures. The public protocol exposes the class and retry disposition, never provider credentials or raw internals.
NormalizeError
Source data could not be represented by the event protocol.
QueryPlanError
Failure compiling portable interests into a HyperSync query.
SessionStoreError
Durable session transition failure.
SourceEngineError
Source engine could not produce or commit an ordered delivery.
SourceError
External source request failure.
SourcePageError
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§

ChainDataSource
Async boundary around HyperSync, mockable at the external service edge.
ChainDataSourceFactory
Factory for independently configured per-chain data sources.
EventSource
Provider-neutral source boundary used by the durable event service.
SessionAuthorizer
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§

ChainHeightStream
Provider-neutral stream of exclusive archive-height updates.