erc_4626.settlement_scan

Documentation for eth_defi.erc_4626.settlement_scan Python module.

Populate generic vault settlement data from ERC-4626 protocol readers.

This module owns the scan orchestration for sparse settlement events. Production scanner calls select one chain from vault metadata and the just-completed price scan end block. Standalone backfill calls can still select ranges from the raw price parquet. Both paths batch event reads by chain and route returned logs back to protocol-specific row builders.

Functions

`fetch_and_store_vault_settlements`([...])	Fetch and store settlement/open-state events for supported protocols.
`fetch_and_store_vault_settlements_for_chain`(*, ...)	Fetch and store settlement events for one already-scanned chain.
`resolve_rpc_urls_by_chain_from_env`(rpc_env_vars)	Resolve configured JSON-RPC URLs to chain ids.
`select_vault_settlement_scan_ranges`(...[, ...])	Select supported vault block ranges that need settlement scans.
`select_vault_settlement_scan_ranges_for_chain`(...)	Select settlement scan ranges from vault metadata and chain scan state.

Classes

`ChainSettlementUpdateResult`	Result of one per-chain settlement event batch.
`PreparedSettlementVault`	Vault adapter and event metadata ready for a settlement log scan.
`SettlementRangeUpdateResult`	Result of executing one or more selected settlement ranges.
`VaultSettlementScanRange`	Block range where one vault needs settlement events scanned.
`VaultSettlementScanResult`	Summary of a settlement scan run.

class VaultSettlementScanRange

Bases: object

Block range where one vault needs settlement events scanned.

Parameters

chain_id – EVM chain id.
address – Lowercase vault address.
start_block – Inclusive start block.
end_block – Inclusive end block.

__init__(chain_id, address, start_block, end_block)

Parameters

chain_id (int) –
address (Union[eth_typing.evm.HexAddress, str]) –
start_block (int) –
end_block (int) –

Return type

None

class VaultSettlementScanResult

Bases: object

Summary of a settlement scan run.

Parameters

candidate_vaults – Supported protocol vaults found in both metadata and raw prices.
scanned_vaults – Vault ranges selected for chain settlement batches.
skipped_vaults – Candidate vaults skipped because the existing database was already current for the raw price block range.
rows_written – Settlement rows written to DuckDB.
scanned_chains – Chains whose settlement batch completed.
failed_chains – Chains whose settlement batch failed and was skipped.

__init__(candidate_vaults, scanned_vaults, skipped_vaults, rows_written, scanned_chains=0, failed_chains=0)

Parameters

candidate_vaults (int) –
scanned_vaults (int) –
skipped_vaults (int) –
rows_written (int) –
scanned_chains (int) –
failed_chains (int) –

Return type

None

class PreparedSettlementVault

Bases: object

Vault adapter and event metadata ready for a settlement log scan.

Parameters

vault – Protocol-specific vault adapter.
event_by_topic – Normalised event topic to event class/name mapping.

__init__(vault, event_by_topic)

Parameters

vault (Union[eth_defi.erc_4626.vault_protocol.lagoon.vault.LagoonVault, eth_defi.erc_4626.vault_protocol.d2.vault.D2Vault, eth_defi.erc_4626.vault_protocol.ember.vault.EmberVault, eth_defi.erc_4626.vault_protocol.accountable.vault.AccountableVault]) –
event_by_topic (dict[str, object]) –

Return type

None

class ChainSettlementUpdateResult

Bases: object

Result of one per-chain settlement event batch.

Parameters

rows_written – Settlement rows written to DuckDB.
scanned_vaults – Vault scan-state rows advanced after the event batch completed.

__init__(rows_written, scanned_vaults)

Parameters

rows_written (int) –
scanned_vaults (int) –

Return type

None

class SettlementRangeUpdateResult

Bases: object

Result of executing one or more selected settlement ranges.

Parameters

rows_written – Settlement rows written to DuckDB.
scanned_vaults – Vault scan-state rows advanced after completed event batches.
scanned_chains – Chains whose settlement batch completed.
failed_chains – Chains whose settlement batch failed and was skipped.

__init__(rows_written, scanned_vaults, scanned_chains, failed_chains)

Parameters

rows_written (int) –
scanned_vaults (int) –
scanned_chains (int) –
failed_chains (int) –

Return type

None

resolve_rpc_urls_by_chain_from_env(rpc_env_vars)

Resolve configured JSON-RPC URLs to chain ids.

The vault pipeline stores RPC endpoint names as environment variable names on ChainConfig. Settlement scanning needs a chain-id keyed mapping so it can instantiate vault adapters for the chains found in raw price data.

Parameters: rpc_env_vars (list[str]) – Environment variable names containing JSON-RPC fallback URL strings.
Returns: Mapping chain_id -> RPC configuration string.
Return type: dict[int, str]

select_vault_settlement_scan_ranges(vault_db, raw_prices_df, settlement_db, supported_features=frozenset({<ERC4626Feature.accountable_like: 'accountable_like'>, <ERC4626Feature.lagoon_like: 'lagoon_like'>, <ERC4626Feature.d2_like: 'd2_like'>, <ERC4626Feature.ember_like: 'ember_like'>}), forced_start_block=None, forced_end_block=None)

Select supported vault block ranges that need settlement scans.

The range is bounded by raw price data, because settlement markers are only useful where the cleaned price parquet has rows to annotate. Existing rows in vault-settlements.duckdb make normal scans incremental. Empty scans are tracked separately from sparse settlement event rows.

Parameters

vault_db (eth_defi.vault.vaultdb.VaultDatabase) – Vault metadata database.
raw_prices_df (pandas.DataFrame) – Raw price DataFrame with chain, address and block_number.
settlement_db (eth_defi.vault.settlement_data.VaultSettlementDatabase) – Settlement database used to determine latest scanned settlement block.
supported_features (Union[set[eth_defi.erc_4626.core.ERC4626Feature], frozenset[eth_defi.erc_4626.core.ERC4626Feature]]) – Protocol feature flags whose event readers are available.
forced_start_block (Optional[int]) – Optional operator-supplied inclusive start block for backfills.
forced_end_block (Optional[int]) – Optional operator-supplied inclusive end block for backfills.

Returns

Scan ranges sorted by chain id and address.

Return type

list[eth_defi.erc_4626.settlement_scan.VaultSettlementScanRange]

select_vault_settlement_scan_ranges_for_chain(vault_db, settlement_db, chain_id, end_block, supported_features=frozenset({<ERC4626Feature.accountable_like: 'accountable_like'>, <ERC4626Feature.lagoon_like: 'lagoon_like'>, <ERC4626Feature.d2_like: 'd2_like'>, <ERC4626Feature.ember_like: 'ember_like'>}), forced_start_block=None, forced_end_block=None)

Select settlement scan ranges from vault metadata and chain scan state.

Production per-chain scans already know the latest scanned chain block from the completed price scan. Using that block avoids re-reading the raw price parquet just to rediscover the chain-level end block.

Parameters

vault_db (eth_defi.vault.vaultdb.VaultDatabase) – Vault metadata database.
settlement_db (eth_defi.vault.settlement_data.VaultSettlementDatabase) – Settlement database used to determine latest scanned settlement block.
chain_id (int) – Chain id to select.
end_block (int) – Latest block reached by the successful chain price scan.
supported_features (Union[set[eth_defi.erc_4626.core.ERC4626Feature], frozenset[eth_defi.erc_4626.core.ERC4626Feature]]) – Protocol feature flags whose event readers are available.
forced_start_block (Optional[int]) – Optional operator-supplied inclusive start block for backfills.
forced_end_block (Optional[int]) – Optional operator-supplied inclusive end block for backfills.

Returns

Scan ranges sorted by address.

Return type

list[eth_defi.erc_4626.settlement_scan.VaultSettlementScanRange]

fetch_and_store_vault_settlements(vault_db_path=PosixPath('/home/runner/.tradingstrategy/vaults/vault-metadata-db.pickle'), raw_price_path=PosixPath('/home/runner/.tradingstrategy/vaults/vault-prices-1h.parquet'), settlement_db_path=None, rpc_urls_by_chain=None, supported_features=frozenset({<ERC4626Feature.accountable_like: 'accountable_like'>, <ERC4626Feature.lagoon_like: 'lagoon_like'>, <ERC4626Feature.d2_like: 'd2_like'>, <ERC4626Feature.ember_like: 'ember_like'>}), forced_start_block=None, forced_end_block=None, use_hypersync=None, chunk_size=50000, chain_ids=None, fail_gracefully=True)

Fetch and store settlement/open-state events for supported protocols.

This standalone/backfill helper reads raw price parquet to bound scan ranges. The production scanner loop uses fetch_and_store_vault_settlements_for_chain() to avoid re-reading raw price parquet during each chain cycle. Currently supported protocol readers are Lagoon, D2 Finance and Ember.

Parameters

vault_db_path (pathlib.Path) – Vault metadata pickle path.
raw_price_path (pathlib.Path) – Raw price parquet path.
settlement_db_path (Optional[pathlib.Path]) – Settlement DuckDB path. None uses the default pipeline path.
rpc_urls_by_chain (Optional[dict[int, str]]) – Mapping chain_id -> JSON-RPC configuration string.
supported_features (Union[set[eth_defi.erc_4626.core.ERC4626Feature], frozenset[eth_defi.erc_4626.core.ERC4626Feature]]) – Protocol feature flags whose event readers are available.
forced_start_block (Optional[int]) – Optional inclusive backfill start block.
forced_end_block (Optional[int]) – Optional inclusive backfill end block.
use_hypersync (Optional[bool]) – Passed to protocol readers. None lets each reader auto-detect.
chunk_size (int) – JSON-RPC eth_getLogs chunk size for fallback reads.
chain_ids (Optional[Union[set[int], frozenset[int]]]) – Optional chain id filter for manual or backfill scans.
fail_gracefully (bool) – If True, one failed chain settlement batch is logged and counted without aborting the caller.

Returns

Scan summary.

Return type

eth_defi.erc_4626.settlement_scan.VaultSettlementScanResult

fetch_and_store_vault_settlements_for_chain(*, vault_db, chain_id, rpc_url, end_block, settlement_db_path=None, supported_features=frozenset({<ERC4626Feature.accountable_like: 'accountable_like'>, <ERC4626Feature.lagoon_like: 'lagoon_like'>, <ERC4626Feature.d2_like: 'd2_like'>, <ERC4626Feature.ember_like: 'ember_like'>}), forced_start_block=None, forced_end_block=None, use_hypersync=None, chunk_size=50000, fail_gracefully=True)

Fetch and store settlement events for one already-scanned chain.

This helper is used by the production scanner loop. It avoids re-reading the vault pickle and raw price parquet by consuming the already-loaded vault metadata and the end block reported by the just-completed chain scan.

Parameters

vault_db (eth_defi.vault.vaultdb.VaultDatabase) – Vault metadata database.
chain_id (int) – Chain id to scan.
rpc_url (str) – JSON-RPC configuration string for the chain.
end_block (int) – Latest block reached by the successful chain scan.
settlement_db_path (Optional[pathlib.Path]) – Settlement DuckDB path. None uses the default pipeline path.
supported_features (Union[set[eth_defi.erc_4626.core.ERC4626Feature], frozenset[eth_defi.erc_4626.core.ERC4626Feature]]) – Protocol feature flags whose event readers are available.
forced_start_block (Optional[int]) – Optional inclusive backfill start block.
forced_end_block (Optional[int]) – Optional inclusive backfill end block.
use_hypersync (Optional[bool]) – Passed to protocol readers. None lets each reader auto-detect.
chunk_size (int) – JSON-RPC eth_getLogs chunk size for fallback reads.
fail_gracefully (bool) – If True, a failed chain settlement batch is logged and counted without aborting the caller.

Returns

Scan summary.

Return type

eth_defi.erc_4626.settlement_scan.VaultSettlementScanResult