gmx.historical_context

Documentation for eth_defi.gmx.historical_context Python module.

Persist GMX V2 liquidity-provider value-and-supply observations.

The shared vault-historical-context.duckdb file contains one table per protocol. GMX stores sparse value-and-supply events here before the common vault price scanner reads them. Calculated prices remain in the common Parquet dataset, not in this cache.

Module Attributes

GMX_HYPERSYNC_VALUATION_CHUNK_SIZE	Maximum Hypersync block range committed in one transaction.
GMX_HYPERSYNC_RATE_LIMIT_RETRIES	Maximum bounded retries for a rate-limited Hypersync request.
GMX_HISTORICAL_CONTEXT_COLUMNS	Direct columns owned by the GMX context table.

Functions

fetch_and_store_gmx_historical_share_prices(*, ...)	Cache GM and GLV value-and-supply events.
get_gmx_historical_context_path()	Return the shared contextual-reader DuckDB path.

Classes

GMXHistoricalContextPrefillResult	Summarise one incremental GMX observation fetch.
GMXHistoricalContextStore	Manage GMX's table in the shared historical-context DuckDB.

GMX_HYPERSYNC_VALUATION_CHUNK_SIZE: int = 10000000

Maximum Hypersync block range committed in one transaction.

GMX_HYPERSYNC_RATE_LIMIT_RETRIES: int = 10

Maximum bounded retries for a rate-limited Hypersync request.

GMX_HISTORICAL_CONTEXT_COLUMNS: frozenset[str] = frozenset({'block_number', 'block_timestamp', 'chain_id', 'event_name', 'log_index', 'product_address', 'raw_supply', 'raw_value', 'transaction_hash'})

Direct columns owned by the GMX context table.

get_gmx_historical_context_path()

Return the shared contextual-reader DuckDB path.

Returns

vault-historical-context.duckdb under the pipeline data directory.

Return type

pathlib.Path

class GMXHistoricalContextPrefillResult

Bases: object

Summarise one incremental GMX observation fetch.

Records the source range and event counts for scanner diagnostics and operator-facing backfill output.

chain_id: int

GMX deployment chain.

start_block: int

Inclusive source range boundary.

end_block: int

Exclusive source range boundary.

observations_fetched: int

Value-and-supply events decoded from the source range.

observations_inserted: int

Observations inserted or promoted to the current payload schema.

__init__(chain_id, start_block, end_block, observations_fetched, observations_inserted)

Parameters

• chain_id (int) –

• start_block (int) –

• end_block (int) –

• observations_fetched (int) –

• observations_inserted (int) –

Return type

None

class GMXHistoricalContextStore

Bases: contextlib.AbstractContextManager

Manage GMX’s table in the shared historical-context DuckDB.

Open the cache and create the GMX table when needed.

Parameters

path – Shared contextual-cache DuckDB filename.

__init__(path)

Open the cache and create the GMX table when needed.

Parameters

path (pathlib.Path) – Shared contextual-cache DuckDB filename.

Return type

None

insert_share_price(observation)

Persist one GM or GLV observation idempotently.

The chain transaction hash and log index identify the source event. Repeating an identical event is a no-op; conflicting values are rejected.

Parameters

observation (eth_defi.gmx.historical_oracle.GMXHistoricalSharePriceObservation) – Canonical onchain value-and-supply event.

Returns

True when inserted and False for an identical retry.

Raises

ValueError – If an existing observation has a different payload.

Return type

bool

insert_share_prices(observations)

Persist a batch without using DuckDB ART indexes.

Rows are staged in an unconstrained temporary table. Hash joins detect conflicting source identities and insert only previously unseen rows. This preserves idempotency without the file-backed PRIMARY KEY index that can corrupt DuckDB 1.5.0 on Python 3.14. See the related DuckDB ART issue.

Parameters

observations (collections.abc.Iterable[eth_defi.gmx.historical_oracle.GMXHistoricalSharePriceObservation]) – Canonical GMX observations from one source chunk.

Returns

Number of newly inserted observations.

Raises

ValueError – If a source identity has different payloads within the batch or in the existing table.

Return type

int

iter_share_prices(*, chain_id, product_address, start_block, end_block, step)

Yield at most one observation per common block bucket.

Parameters

• chain_id (int) – GMX deployment chain.

• product_address (eth_typing.evm.HexAddress) – GM market token or GLV share token.

• start_block (int) – Inclusive archive boundary.

• end_block (int) – Exclusive archive boundary.

• step (int) – Positive common price-scan bucket width.

Returns

Verified observations ordered by block and log index.

Return type

collections.abc.Iterable[eth_defi.gmx.historical_oracle.GMXHistoricalSharePriceObservation]

close()

Close the underlying DuckDB connection.

Return type

None

fetch_and_store_gmx_historical_share_prices(*, web3, hypersync_client, start_block, end_block, context_path=None, source_chunk_size=10000000, product_addresses=None)

Cache GM and GLV value-and-supply events.

Each source chunk is committed before the next Hypersync request, making a lifetime backfill restartable.

Parameters

• web3 (web3.main.Web3) – Web3 connection for Arbitrum One or Avalanche.

• hypersync_client (eth_defi.hypersync.session.ThrottledHypersyncClient) – Configured Hypersync client for the same chain.

• start_block (int) – Inclusive requested source boundary.

• end_block (int) – Exclusive requested source boundary.

• context_path (Optional[pathlib.Path]) – Optional shared contextual-cache DuckDB path.

• source_chunk_size (int) – Maximum half-open Hypersync range committed at once.

• product_addresses (Optional[collections.abc.Iterable[eth_typing.evm.HexAddress]]) – Optional current catalogue addresses to filter at the log level.

Returns

Source observation and insertion counts.

Return type

eth_defi.gmx.historical_context.GMXHistoricalContextPrefillResult