erc_4626.vault_protocol.flying_tulip.historical_context

Documentation for eth_defi.erc_4626.vault_protocol.flying_tulip.historical_context Python module.

Collect raw Flying Tulip sftUSD reward and supply history with Hypersync.

The collector stores only canonical source events. The later contextual reader replays these events into the common share_price_equivalence curve.

Module Attributes

EPOCH_SETTLED_TOPIC

Index of epochId in EpochSettled.

TRANSFER_TOPIC

Standard ERC-20 transfer event signature.

ZERO_ADDRESS_TOPIC

Solidity's indexed zero address representation.

EPOCH_SETTLED_TOPIC_COUNT

EpochSettled has signature and indexed epoch topics.

TRANSFER_TOPIC_COUNT

ERC-20 transfers have signature, sender and recipient topics.

FLYING_TULIP_SOURCE_CHUNK_SIZE

A chain-wide source range is split so every successful request is observable.

Functions

fetch_and_store_flying_tulip_source_history(*, ...)

Collect every Flying Tulip source event in a half-open block range.

fetch_flying_tulip_proxy_deployment_block(...)

Find the first block with runtime code for a reviewed sftUSD proxy.

fetch_source_chunk(hypersync_client, ...)

Stream one source range and decode settlement and supply events.

is_mint_transfer(from_topic, to_topic)

Classify a zero-address ERC-20 transfer as a supply mint or burn.

Classes

EpochSettlement

One raw EpochSettled event needed for performance replay.

FlyingTulipContextPrefillResult

Summarise one full or bounded Flying Tulip source collection.

FlyingTulipHistoricalContextStore

Persist Flying Tulip source events in the shared contextual cache.

FlyingTulipSharePriceObservation

One replayed, non-redeemable sftUSD price-equivalence observation.

RewardPriceObservation

One canonical FT/ftUSD price attached to a settled epoch.

SupplyChange

One sftUSD mint or burn reconstructed from Transfer.

EPOCH_SETTLED_TOPIC = '0x34988ca75cbe9139e16a95c8dfd76432a5ecf3b21640b4c1a33c91c65e689d4f'

Index of epochId in EpochSettled.

TRANSFER_TOPIC = '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef'

Standard ERC-20 transfer event signature.

ZERO_ADDRESS_TOPIC = '0x0000000000000000000000000000000000000000000000000000000000000000'

Solidity’s indexed zero address representation.

EPOCH_SETTLED_TOPIC_COUNT = 2

EpochSettled has signature and indexed epoch topics.

TRANSFER_TOPIC_COUNT = 3

ERC-20 transfers have signature, sender and recipient topics.

FLYING_TULIP_SOURCE_CHUNK_SIZE = 10000000

A chain-wide source range is split so every successful request is observable.

class FlyingTulipContextPrefillResult

Bases: object

Summarise one full or bounded Flying Tulip source collection.

chain_id: int

Source EVM chain identifier.

start_block: int

Inclusive first processed block.

end_block: int

Exclusive safe source head.

epochs_fetched: int

Number of decoded EpochSettled logs.

supply_events_fetched: int

Number of mint or burn transfer logs.

rows_inserted: int

Number of new raw rows committed to the contextual cache.

__init__(chain_id, start_block, end_block, epochs_fetched, supply_events_fetched, rows_inserted)
Parameters
  • chain_id (int) –

  • start_block (int) –

  • end_block (int) –

  • epochs_fetched (int) –

  • supply_events_fetched (int) –

  • rows_inserted (int) –

Return type

None

class EpochSettlement

Bases: object

One raw EpochSettled event needed for performance replay.

chain_id: int

Source EVM chain identifier.

vault_address: eth_typing.evm.HexAddress

sftUSD proxy which emitted the event.

epoch_id: int

Sequential contract settlement identifier.

block_number: int

EVM block containing the event.

block_timestamp: int

Unix timestamp of block_number.

transaction_hash: str

Emitting transaction hash.

log_index: int

Event position in the transaction.

raw_reward_amount: int

Raw FT distribution amount.

raw_stake_time: int

Raw aggregate stake-seconds.

raw_rate_ray: int

Raw contract reward-rate identity value.

__init__(chain_id, vault_address, epoch_id, block_number, block_timestamp, transaction_hash, log_index, raw_reward_amount, raw_stake_time, raw_rate_ray)
Parameters
Return type

None

class SupplyChange

Bases: object

One sftUSD mint or burn reconstructed from Transfer.

chain_id: int

Source EVM chain identifier.

vault_address: eth_typing.evm.HexAddress

sftUSD proxy which emitted the transfer.

block_number: int

EVM block containing the transfer.

block_timestamp: int

Unix timestamp of block_number.

transaction_hash: str

Emitting transaction hash.

log_index: int

Event position in the transaction.

is_mint: bool

True for a mint and False for a burn.

raw_amount: int

Raw sftUSD supply delta.

__init__(chain_id, vault_address, block_number, block_timestamp, transaction_hash, log_index, is_mint, raw_amount)
Parameters
Return type

None

class RewardPriceObservation

Bases: object

One canonical FT/ftUSD price attached to a settled epoch.

The price is deliberately source-chain independent: each settlement uses the Ethereum Curve oracle at the greatest Ethereum block no later than the settlement timestamp. Raw uint256 units are retained in the context cache so replay never depends on float serialisation.

ethereum_block_number: int

Ethereum block used for the Curve read.

ethereum_block_timestamp: int

Unix timestamp of ethereum_block_number.

pool_address: eth_typing.evm.HexAddress

Reviewed Ethereum Curve pool address.

raw_oracle: int

Raw inverse price_oracle() response.

oracle_updated_at: int

Curve’s last oracle-update Unix timestamp.

raw_ft_price_in_ftusd: int

Normalised ftUSD-per-FT price, scaled by 1e18.

__init__(ethereum_block_number, ethereum_block_timestamp, pool_address, raw_oracle, oracle_updated_at, raw_ft_price_in_ftusd)
Parameters
Return type

None

class FlyingTulipSharePriceObservation

Bases: object

One replayed, non-redeemable sftUSD price-equivalence observation.

block_number: int

Source settlement block.

block_timestamp: int

Source settlement Unix timestamp.

epoch_id: int

Source EpochSettled identifier.

total_supply: decimal.Decimal

Reconstructed sftUSD principal supply in ftUSD units.

share_price: decimal.Decimal

Compounded, non-redeemable ftUSD price equivalent.

total_assets: decimal.Decimal

Synthetic equivalent value, share_price * total_supply.

This is a reward-reinvested performance value for the shared share_price_equivalence pipeline, not contractual sftUSD TVL.

__init__(block_number, block_timestamp, epoch_id, total_supply, share_price, total_assets)
Parameters
Return type

None

is_mint_transfer(from_topic, to_topic)

Classify a zero-address ERC-20 transfer as a supply mint or burn.

ERC-20 emits a mint with the zero address as sender and a burn with the zero address as recipient. The caller has already filtered ordinary transfers before invoking this helper.

Parameters
  • from_topic (str) – Normalised indexed ERC-20 transfer sender topic.

  • to_topic (str) – Normalised indexed ERC-20 transfer recipient topic.

Returns

True for a mint and False for a burn.

Raises

ValueError – If the transfer does not alter token supply.

Return type

bool

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.

__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

async fetch_source_chunk(hypersync_client, chain_id, vault_address, start_block, end_block)

Stream one source range and decode settlement and supply events.

The query deliberately requests all sftUSD transfers and filters to zero address endpoints locally. This avoids depending on provider-specific wildcard-topic syntax while retaining an address-scoped source stream.

Parameters
Returns

Chronologically sorted epoch and supply source events.

Return type

tuple[list[eth_defi.erc_4626.vault_protocol.flying_tulip.historical_context.EpochSettlement], list[eth_defi.erc_4626.vault_protocol.flying_tulip.historical_context.SupplyChange]]

fetch_flying_tulip_proxy_deployment_block(web3, vault_address, end_block)

Find the first block with runtime code for a reviewed sftUSD proxy.

The binary search is an archive-state operation for one contract, not a historical log or timestamp read. The caller uses it only to establish the complete Hypersync source range; all source events themselves remain on Hypersync.

Parameters
  • web3 (web3.main.Web3) – Archive-capable deployment-chain provider.

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

  • end_block (int) – Exclusive safe head whose preceding block contains proxy code.

Returns

Inclusive deployment block.

Return type

int

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

Collect every Flying Tulip source event in a half-open block range.

This function is restartable: completed source rows are inserted idempotently and a conflicting duplicate stops the run. It has no JSON-RPC log reads and does not construct synthetic prices.

Parameters
  • web3 (web3.main.Web3) – RPC connection for the same chain as Hypersync.

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

  • start_block (int) – Inclusive source boundary, normally the sftUSD proxy deployment block.

  • end_block (int) – Exclusive safe source head.

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

  • source_chunk_size (int) – Maximum source blocks per observable Hypersync request.

Returns

Counts for the complete requested source range.

Return type

eth_defi.erc_4626.vault_protocol.flying_tulip.historical_context.FlyingTulipContextPrefillResult