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
Index of |
|
Standard ERC-20 transfer event signature. |
|
Solidity's indexed zero address representation. |
|
|
|
ERC-20 transfers have signature, sender and recipient topics. |
|
A chain-wide source range is split so every successful request is observable. |
Functions
Collect every Flying Tulip source event in a half-open block range. |
|
Find the first block with runtime code for a reviewed sftUSD proxy. |
|
|
Stream one source range and decode settlement and supply events. |
|
Classify a zero-address ERC-20 transfer as a supply mint or burn. |
Classes
One raw |
|
Summarise one full or bounded Flying Tulip source collection. |
|
Persist Flying Tulip source events in the shared contextual cache. |
|
One replayed, non-redeemable sftUSD price-equivalence observation. |
|
One canonical FT/ftUSD price attached to a settled epoch. |
|
One sftUSD mint or burn reconstructed from |
- EPOCH_SETTLED_TOPIC = '0x34988ca75cbe9139e16a95c8dfd76432a5ecf3b21640b4c1a33c91c65e689d4f'
Index of
epochIdinEpochSettled.
- TRANSFER_TOPIC = '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef'
Standard ERC-20 transfer event signature.
- ZERO_ADDRESS_TOPIC = '0x0000000000000000000000000000000000000000000000000000000000000000'
Solidity’s indexed zero address representation.
- EPOCH_SETTLED_TOPIC_COUNT = 2
EpochSettledhas 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:
objectSummarise one full or bounded Flying Tulip source collection.
- class EpochSettlement
Bases:
objectOne raw
EpochSettledevent needed for performance replay.- vault_address: eth_typing.evm.HexAddress
sftUSD proxy which emitted the event.
- block_timestamp: int
Unix timestamp of
block_number.
- __init__(chain_id, vault_address, epoch_id, block_number, block_timestamp, transaction_hash, log_index, raw_reward_amount, raw_stake_time, raw_rate_ray)
- class SupplyChange
Bases:
objectOne sftUSD mint or burn reconstructed from
Transfer.- vault_address: eth_typing.evm.HexAddress
sftUSD proxy which emitted the transfer.
- block_timestamp: int
Unix timestamp of
block_number.
- __init__(chain_id, vault_address, block_number, block_timestamp, transaction_hash, log_index, is_mint, raw_amount)
- class RewardPriceObservation
Bases:
objectOne 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
uint256units are retained in the context cache so replay never depends on float serialisation.- ethereum_block_timestamp: int
Unix timestamp of
ethereum_block_number.
- pool_address: eth_typing.evm.HexAddress
Reviewed Ethereum Curve pool address.
- __init__(ethereum_block_number, ethereum_block_timestamp, pool_address, raw_oracle, oracle_updated_at, raw_ft_price_in_ftusd)
Bases:
objectOne replayed, non-redeemable sftUSD price-equivalence observation.
Source settlement block.
Source settlement Unix timestamp.
Source
EpochSettledidentifier.
Reconstructed sftUSD principal supply in ftUSD units.
Compounded, non-redeemable ftUSD price equivalent.
Synthetic equivalent value,
share_price * total_supply.This is a reward-reinvested performance value for the shared
share_price_equivalencepipeline, not contractual sftUSD TVL.
- Parameters
block_number (int) –
block_timestamp (int) –
epoch_id (int) –
total_supply (decimal.Decimal) –
share_price (decimal.Decimal) –
total_assets (decimal.Decimal) –
- 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
- Returns
Truefor a mint andFalsefor a burn.- Raises
ValueError – If the transfer does not alter token supply.
- Return type
- class FlyingTulipHistoricalContextStore
Bases:
contextlib.AbstractContextManagerPersist Flying Tulip source events in the shared contextual cache.
Open the shared DuckDB and initialise Flying Tulip tables.
- Parameters
path – Shared
vault-historical-context.duckdbfile.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.duckdbfile.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
Trueif a new row was inserted.- Return type
- 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
Trueif a new row was inserted.- Return type
- 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
Trueif the cache gained a new row.- Return type
- 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
chain_id (int) – sftUSD deployment chain.
vault_address (eth_typing.evm.HexAddress) – Reviewed source proxy.
- Returns
Exclusive end of the last completed range, or
Noneinitially.- Return type
- 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_blockhas 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
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
hypersync_client (eth_defi.hypersync.session.ThrottledHypersyncClient) – Configured client for
chain_id.chain_id (int) – EVM source chain.
vault_address (eth_typing.evm.HexAddress) – Official sftUSD proxy on that chain.
start_block (int) – Inclusive source range start.
end_block (int) – Exclusive source range end.
- 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
- 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