erc_4626.vault_protocol.rysk.historical_context

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

Collect final Rysk Premium epoch prices from onchain events.

Rysk first emits EpochPriceSet and may replace the proposal with EpochPriceDisputed during the dispute window. epochExecuted is the finalisation boundary. Only the latest price update preceding that execution is exposed as a share-price-equivalent observation.

Functions

`fetch_and_store_rysk_premium_history`(*, ...)	Incrementally collect final onchain epochs for selected Rysk pools.
`fetch_rysk_finalised_epoch_prices`(*, ...[, ...])	Reconstruct final Rysk prices from proposed, disputed and executed events.
`get_rysk_historical_context_path`()	Return the shared contextual-history database path.

Classes

`RyskEpochPriceUpdate`	Represent one proposed or disputed onchain epoch price.
`RyskHistoricalContextPrefillResult`	Summarise one onchain Rysk history refresh.
`RyskHistoricalContextStore`	Persist final Rysk epoch observations without DuckDB ART indexes.
`RyskHistoricalSharePriceObservation`	Represent one price made final by `epochExecuted`.

get_rysk_historical_context_path()

Return the shared contextual-history database path.

Rysk owns one table in the pipeline-wide DuckDB context file. Other protocol tables and their rows are not modified.

Returns: Pipeline vault-historical-context.duckdb location.
Return type: pathlib.Path

class RyskEpochPriceUpdate

Bases: object

Represent one proposed or disputed onchain epoch price.

epoch: int: Epoch whose prices were updated.

block_number: int: EVM block containing the update.

log_index: int: Event position within the transaction.

raw_deposit_pps: int: Raw subscription price in collateral-token precision.

raw_withdrawal_pps: int: Raw redemption price in collateral-token precision.

__init__(epoch, block_number, log_index, raw_deposit_pps, raw_withdrawal_pps)

Parameters

epoch (int) –
block_number (int) –
log_index (int) –
raw_deposit_pps (int) –
raw_withdrawal_pps (int) –

Return type

None

class RyskHistoricalSharePriceObservation

Bases: object

Represent one price made final by epochExecuted.

chain_id: int: EVM chain containing the pool.

pool_address: eth_typing.evm.HexAddress: Pool and ERC-20 LP share-token address.

epoch: int: Epoch finalised by the execution.

block_number: int: Execution block, which is the finalisation boundary.

block_timestamp: int: Unix timestamp of the execution block.

transaction_hash: str: Execution transaction hash.

log_index: int: Execution event position within the transaction.

raw_deposit_pps: int: Final raw subscription price retained for auditing.

raw_withdrawal_pps: int: Final raw redemption price retained for scaling.

withdrawal_share_price: Optional[decimal.Decimal]: Collateral-denominated final redemption price for one share.

__init__(chain_id, pool_address, epoch, block_number, block_timestamp, transaction_hash, log_index, raw_deposit_pps, raw_withdrawal_pps, withdrawal_share_price=None)

Parameters

chain_id (int) –
pool_address (eth_typing.evm.HexAddress) –
epoch (int) –
block_number (int) –
block_timestamp (int) –
transaction_hash (str) –
log_index (int) –
raw_deposit_pps (int) –
raw_withdrawal_pps (int) –
withdrawal_share_price (Optional[decimal.Decimal]) –

Return type

None

class RyskHistoricalContextPrefillResult

Bases: object

Summarise one onchain Rysk history refresh.

observations_fetched: int: Final execution events reconstructed from the requested ranges.

observations_inserted: int: Previously unseen final observations persisted.

__init__(observations_fetched, observations_inserted)

Parameters

observations_fetched (int) –
observations_inserted (int) –

Return type

None

class RyskHistoricalContextStore

Bases: contextlib.AbstractContextManager

Persist final Rysk epoch observations without DuckDB ART indexes.

Open the shared cache and create the Rysk event table.

Parameters: path – Shared contextual-history DuckDB path.
Returns: None.

__init__(path)

Open the shared cache and create the Rysk event table.

Parameters: path (pathlib.Path) – Shared contextual-history DuckDB path.
Returns: None.
Return type: None

fetch_next_source_block(chain_id, pool_address, default_start_block)

Return an inclusive restart block for one pool.

The last finalisation block is intentionally replayed so a price update for the next epoch in the same block cannot be skipped. Exact execution rows are deduplicated when inserted.

Parameters

chain_id (int) – EVM chain identifier.
pool_address (eth_typing.evm.HexAddress) – Pool whose cursor is requested.
default_start_block (int) – First discovery block when no context exists.

Returns

Inclusive source restart block.

Return type

int

fetch_source_ids_at_block(chain_id, pool_address, block_number)

Return stored execution identities at one replay boundary.

The incremental collector replays the last finalisation block so it cannot miss a next-epoch price update emitted later in that block. Stored executions at the boundary may refer to a price proposal before the replay window and are therefore supplied to the join as known rows.

Parameters

chain_id (int) – EVM chain identifier.
pool_address (eth_typing.evm.HexAddress) – Pool whose execution rows are inspected.
block_number (int) – Inclusive replay block.

Returns

Stored source identities at the boundary.

Return type

frozenset[str]

insert_observations(observations)

Insert final epoch observations transactionally and idempotently.

Source identities use the execution log location. No uniqueness index is created because large file-backed ART indexes are unsafe with the repository’s supported DuckDB and Python versions.

Parameters: observations (collections.abc.Iterable[eth_defi.erc_4626.vault_protocol.rysk.historical_context.RyskHistoricalSharePriceObservation]) – Finite stream reconstructed from Rysk events.
Returns: (fetched, inserted) counts.
Return type: tuple[int, int]

iter_finalised_share_prices(*, chain_id, pool_address, start_block, end_block, collateral_decimals)

Yield final execution prices in chronological order.

raw_withdrawal_pps is encoded using the pool collateral token’s precision. No total-assets or supply value is fabricated.

Parameters

chain_id (int) – EVM chain identifier.
pool_address (eth_typing.evm.HexAddress) – Pool and share-token address.
start_block (int) – Inclusive execution block boundary.
end_block (int) – Exclusive execution block boundary.
collateral_decimals (int) – Native precision of the collateral token.

Returns

Final collateral-denominated exit prices.

Return type

collections.abc.Iterable[eth_defi.erc_4626.vault_protocol.rysk.historical_context.RyskHistoricalSharePriceObservation]

fetch_rysk_finalised_epoch_prices(*, hypersync_client, chain_id, pool_address, start_block, end_block, source_chunk_size=10000000, timestamp_cache_path=PosixPath('/home/runner/.tradingstrategy/block-timestamp'), known_execution_source_ids=())

Reconstruct final Rysk prices from proposed, disputed and executed events.

Price updates are ordered by block and log index. An execution selects the greatest update for its processed epoch that precedes the execution event.

Parameters

hypersync_client (eth_defi.hypersync.session.ThrottledHypersyncClient) – Configured throttle-aware Hypersync client.
chain_id (int) – EVM chain identifier.
pool_address (eth_typing.evm.HexAddress) – Rysk pool to scan.
start_block (int) – Inclusive source boundary.
end_block (int) – Exclusive source boundary.
source_chunk_size (int) – Maximum blocks per observable Hypersync request.
timestamp_cache_path (pathlib.Path) – Persistent cache directory for execution-block timestamps.
known_execution_source_ids (collections.abc.Collection[str]) – Stored execution rows at an inclusive replay boundary. A known row may have its price update before the requested range and is skipped instead of being treated as corrupt source history.

Returns

Final epoch observations ordered by execution location.

Return type

tuple[eth_defi.erc_4626.vault_protocol.rysk.historical_context.RyskHistoricalSharePriceObservation, …]

fetch_and_store_rysk_premium_history(*, web3, hypersync_client, pool_start_blocks, end_block, context_path, timestamp_cache_path=PosixPath('/home/runner/.tradingstrategy/block-timestamp'))

Incrementally collect final onchain epochs for selected Rysk pools.

Each pool resumes from its last stored execution block, or its own supplied discovery block when no history exists. Rysk event and timestamp reads use Hypersync; JSON-RPC eth_getLogs is never used.

Parameters

web3 (web3.main.Web3) – RPC connection used only for chain identity.
hypersync_client (eth_defi.hypersync.session.ThrottledHypersyncClient) – Configured client for the same chain.
pool_start_blocks (collections.abc.Mapping[eth_typing.evm.HexAddress, int]) – Rysk pool addresses mapped to their individual inclusive discovery boundaries.
end_block (int) – Exclusive safe source head.
context_path (pathlib.Path) – Shared contextual-history DuckDB path.
timestamp_cache_path (pathlib.Path) – Persistent per-chain timestamp-cache directory.

Returns

Aggregate fetched and inserted observation counts.

Return type

eth_defi.erc_4626.vault_protocol.rysk.historical_context.RyskHistoricalContextPrefillResult