gmx.historical_oracle

Documentation for eth_defi.gmx.historical_oracle Python module.

Read GMX V2 liquidity-provider value-and-supply events.

The ratio of value to corresponding supply provides a sparse USD share-price equivalent without treating a change in TVL or share count as profit. GM emits MarketPoolValueUpdated after a deposit and GLV emits GlvValueUpdated after execution. GM withdrawal observations are deliberately excluded because GMX values deposits and withdrawals with different PnL-factor contexts. The common vault scanner later applies its normal change threshold.

Module Attributes

GMX_SHARE_PRICE_EVENT_NAMES

GMX EventEmitter event names containing matched value and supply.

GMX_DEPOSIT_ACTION_TYPE

actionType emitted by GMX after a deposit execution.

GMX_EVENT_LOG1_DATA_TYPES

Non-indexed EventLog1 inputs.

Functions

decode_historical_share_price_event_data(...)

Decode the GMX EventLog1 fields needed for LP valuation.

encode_address_as_event_topic(address)

Encode an EVM address as a GMX EventLog1 topic.

extract_historical_share_price_observation(...)

Convert a GMX value event into a share-price observation.

fetch_historical_share_price_observations_hypersync(*, ...)

Fetch GM and GLV value-and-supply observations.

Classes

GMXHistoricalSharePriceObservation

One GM or GLV value-and-supply observation.

GMX_SHARE_PRICE_EVENT_NAMES: tuple[str, ...] = ('MarketPoolValueUpdated', 'GlvValueUpdated')

GMX EventEmitter event names containing matched value and supply.

GMX_DEPOSIT_ACTION_TYPE: bytes = b'`y\x91\xfcYc\xe2d\xf1\xa9O\xaa\x12lcH/\xdcZ\xf1Jeo\x08u\x1d\xc8\xb0\xc5\xd4v0'

actionType emitted by GMX after a deposit execution.

GMX_EVENT_LOG1_DATA_TYPES: tuple[str, str, str] = ('address', 'string', '(((string,address)[],(string,address[])[]),((string,uint256)[],(string,uint256[])[]),((string,int256)[],(string,int256[])[]),((string,bool)[],(string,bool[])[]),((string,bytes32)[],(string,bytes32[])[]),((string,bytes)[],(string,bytes[])[]),((string,string)[],(string,string[])[]))')

Non-indexed EventLog1 inputs. Direct decoding avoids materialising all seven generic GMX key/value families through Web3’s event wrapper.

encode_address_as_event_topic(address)

Encode an EVM address as a GMX EventLog1 topic.

Parameters

address (eth_typing.evm.HexAddress) – GM or GLV product address.

Returns

Lower-case, zero-padded 32-byte topic.

Return type

str

decode_historical_share_price_event_data(web3, data, product_topic)

Decode the GMX EventLog1 fields needed for LP valuation.

Parameters
  • web3 (web3.main.Web3) – Web3 instance providing the ABI codec.

  • data (Union[str, bytes]) – Raw non-indexed EventLog1 payload.

  • product_topic (Union[str, bytes]) – Indexed GM or GLV address topic.

Returns

Minimal decoded event data.

Return type

eth_defi.gmx.events.GMXEventData

class GMXHistoricalSharePriceObservation

Bases: object

One GM or GLV value-and-supply observation.

MarketPoolValueUpdated contains GM value and supply after a deposit. Withdrawal-context observations are excluded because GMX uses different valuation parameters for withdrawals. GlvValueUpdated contains GLV value and supply after execution; GLV minting and burning use the pre-flow ratio, so updating both numerator and denominator does not mechanically rebase the existing holders’ claim.

chain_id: int

EVM chain where GMX emitted the observation.

block_number: int

Block containing the valuation event.

block_timestamp: int

Unix timestamp of the valuation block.

transaction_hash: str

Emitting transaction hash.

log_index: int

Log position inside its block.

product_address: eth_typing.evm.HexAddress

GM market token or GLV share token.

raw_value: int

USD GM market or GLV value using GMX’s 30-decimal precision.

raw_supply: int

ERC-20 share supply using 18-decimal precision.

event_name: str

MarketPoolValueUpdated or GlvValueUpdated.

property total_assets: decimal.Decimal

Return the USD product value in decimal units.

property total_supply: decimal.Decimal

Return the ERC-20 share supply in decimal units.

property share_price: decimal.Decimal

Return the supply-normalised USD value per share.

__init__(chain_id, block_number, block_timestamp, transaction_hash, log_index, product_address, raw_value, raw_supply, event_name)
Parameters
Return type

None

extract_historical_share_price_observation(event, *, chain_id, block_number, block_timestamp, transaction_hash, log_index)

Convert a GMX value event into a share-price observation.

The canonical event definitions are in GMX’s MarketEventUtils.sol and GlvEventUtils.sol.

Parameters
  • event (eth_defi.gmx.events.GMXEventData) – Decoded GMX EventEmitter payload.

  • chain_id (int) – Chain represented by the source stream.

  • block_number (int) – Emitting block number.

  • block_timestamp (int) – Unix timestamp of the emitting block.

  • transaction_hash (str) – Emitting transaction hash.

  • log_index (int) – Log position inside its block.

Returns

Complete value-and-supply observation, or None for another event or a non-positive value/supply pair.

Return type

Optional[eth_defi.gmx.historical_oracle.GMXHistoricalSharePriceObservation]

fetch_historical_share_price_observations_hypersync(*, hypersync_client, web3, chain_id, event_emitter_address, start_block, end_block, product_addresses=None, event_loop_runner=None)

Fetch GM and GLV value-and-supply observations.

Parameters
  • hypersync_client (eth_defi.hypersync.session.ThrottledHypersyncClient) – Configured throttle-aware Hypersync client for the chain.

  • web3 (web3.main.Web3) – Web3 instance used to decode GMX EventEmitter payloads.

  • chain_id (int) – Chain represented by the query.

  • event_emitter_address (eth_typing.evm.HexAddress) – GMX EventEmitter deployment.

  • start_block (int) – Inclusive block boundary.

  • end_block (int) – Exclusive block boundary.

  • product_addresses (Optional[collections.abc.Iterable[eth_typing.evm.HexAddress]]) – Optional GM and GLV addresses selected at the indexed-log level.

  • event_loop_runner (Optional[asyncio.runners.Runner]) – Optional long-lived event-loop runner. Full-chain backfills must reuse one runner across chunks so the native Hypersync client’s asynchronous resources stay on their creating loop.

Returns

Chronologically ordered observations.

Return type

list[eth_defi.gmx.historical_oracle.GMXHistoricalSharePriceObservation]