GMXHistoricalContextStore

Documentation for eth_defi.gmx.historical_context.GMXHistoricalContextStore Python class.

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.

Methods summary

__init__(path)

Open the cache and create the GMX table when needed.

close()

Close the underlying DuckDB connection.

insert_share_price(observation)

Persist one GM or GLV observation idempotently.

insert_share_prices(observations)

Persist a batch without using DuckDB ART indexes.

iter_share_prices(*, chain_id, ...)

Yield at most one observation per common block bucket.

__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