FlyingTulipHistoricalContextStore

Documentation for eth_defi.erc_4626.vault_protocol.flying_tulip.historical_context.FlyingTulipHistoricalContextStore Python class.

class FlyingTulipHistoricalContextStore

Bases: contextlib.AbstractContextManager

Persist Flying Tulip source events in the shared contextual cache.

Open the shared DuckDB and initialise Flying Tulip tables.

Parameters
  • path – Shared vault-historical-context.duckdb file.

  • read_only – Open an existing context database without schema writes.

Methods summary

__init__(path, *[, read_only])

Open the shared DuckDB and initialise Flying Tulip tables.

close()

Close the contextual cache connection.

fetch_next_source_block(chain_id, vault_address)

Return the first unscanned source block for one reviewed proxy.

insert_epoch(event)

Insert one epoch event, rejecting any non-identical retry.

insert_reward_price(observation)

Persist one deterministic FT/ftUSD price join idempotently.

insert_supply_change(event)

Insert one mint or burn event, rejecting any non-identical retry.

iter_share_price_observations(chain_id, ...)

Replay reward epochs as a compounded ftUSD price equivalent.

set_source_scan_end_block(chain_id, ...)

Record a fully committed half-open source range.

__init__(path, *, read_only=False)

Open the shared DuckDB and initialise Flying Tulip tables.

Parameters
  • path (pathlib.Path) – Shared vault-historical-context.duckdb file.

  • read_only (bool) – Open an existing context database without schema writes.

Return type

None

insert_epoch(event)

Insert one epoch event, rejecting any non-identical retry.

Parameters

event (eth_defi.erc_4626.vault_protocol.flying_tulip.historical_context.EpochSettlement) – Decoded canonical event.

Returns

True if a new row was inserted.

Return type

bool

insert_supply_change(event)

Insert one mint or burn event, rejecting any non-identical retry.

Parameters

event (eth_defi.erc_4626.vault_protocol.flying_tulip.historical_context.SupplyChange) – Decoded canonical transfer.

Returns

True if a new row was inserted.

Return type

bool

insert_reward_price(observation)

Persist one deterministic FT/ftUSD price join idempotently.

Parameters

observation (eth_defi.erc_4626.vault_protocol.flying_tulip.historical_context.RewardPriceObservation) – Price oracle observation for an epoch.

Returns

True if the cache gained a new row.

Return type

bool

fetch_next_source_block(chain_id, vault_address)

Return the first unscanned source block for one reviewed proxy.

Source coverage is persisted even when a range contains no events. This prevents a dormant deployment from being rediscovered from genesis on every scheduled scanner cycle.

Parameters
Returns

Exclusive end of the last completed range, or None initially.

Return type

Optional[int]

set_source_scan_end_block(chain_id, vault_address, end_block)

Record a fully committed half-open source range.

The caller invokes this only after every chunk through end_block has committed. Monotonic updates make a successful empty range as durable as a range containing source events.

Parameters
  • chain_id (int) – sftUSD deployment chain.

  • vault_address (eth_typing.evm.HexAddress) – Reviewed source proxy.

  • end_block (int) – Exclusive end of the fully committed source range.

Returns

None.

Return type

None

iter_share_price_observations(chain_id, vault_address, asset_decimals, reward_decimals, start_block, end_block, step)

Replay reward epochs as a compounded ftUSD price equivalent.

Tracking starts at the first settlement after the canonical Ethereum Curve FT/ftUSD market was deployed. Earlier rewards cannot be valued from this market and are deliberately excluded. The first tracked settlement establishes a 1.0 baseline; its reward is not compounded because its accrual interval crosses the unsupported boundary. Every later epoch validates the onchain rate identity and stake-seconds supply invariant before it can extend the compounded suffix.

Parameters
  • chain_id (int) – sftUSD deployment chain.

  • vault_address (eth_typing.evm.HexAddress) – Reviewed sftUSD proxy address.

  • asset_decimals (int) – ftUSD and sftUSD decimal count.

  • reward_decimals (int) – FT decimal count.

  • start_block (int) – Inclusive caller range.

  • end_block (int) – Exclusive caller range.

  • step (int) – Common scanner’s approximate block bucket width.

Returns

Valid, bucket-downsampled synthetic price observations.

Return type

collections.abc.Iterator[eth_defi.erc_4626.vault_protocol.flying_tulip.historical_context.FlyingTulipSharePriceObservation]

close()

Close the contextual cache connection.

Return type

None