erc_4626.settlement_events

Documentation for eth_defi.erc_4626.settlement_events Python module.

ERC-4626 event reader helpers for settlement-style events.

This module contains the chain-log mechanics shared by protocol-specific settlement readers. Protocol modules decide which events matter; this helper fetches logs and converts them to eth_defi.vault.settlement_data.VaultSettlement rows for the generic DuckDB store.

Functions

`build_settlement_rows_from_logs`(*, chain_id, ...)	Build generic settlement rows from vault logs.
`fetch_vault_settlement_logs`(*, web3, ...[, ...])	Fetch vault settlement-style logs using Hypersync or JSON-RPC.
`fetch_vault_settlement_logs_for_addresses`(*, ...)	Fetch vault settlement-style logs for multiple vaults as one address batch.
`fetch_vault_settlement_logs_hypersync`(*, ...)	Fetch vault settlement-style logs using Hypersync.
`fetch_vault_settlement_logs_hypersync_for_addresses`(*, ...)	Fetch vault settlement-style logs for multiple vaults using Hypersync.
`fetch_vault_settlement_logs_rpc`(*, web3, ...)	Fetch vault settlement-style logs using chunked JSON-RPC `eth_getLogs`.
`get_event_topic`(event)	Return lower-case `0x`-prefixed event topic0.
`get_log_event_name`(log, event_by_topic)	Resolve a Web3 log event name.
`indexed_log_to_web3_log`(log)	Convert a Hypersync log to Web3.py log shape.
`normalise_log_topic`(topic)	Normalise a Web3 log topic value to lowercase `0x` hex.
`normalise_topic`(topic)	Normalise an event topic.
`should_use_hypersync`()	Check whether Hypersync should be used for event reads.

get_event_topic(event)

Return lower-case 0x-prefixed event topic0.

Parameters: event (web3.contract.contract.ContractEvent) – Web3.py contract event class.
Returns: Normalised topic string.
Return type: str

normalise_topic(topic)

Normalise an event topic.

Parameters: topic (str) – Topic as a string, with or without 0x prefix.
Returns: Lower-case 0x-prefixed topic.
Return type: str

should_use_hypersync()

Check whether Hypersync should be used for event reads.

Returns: True if HYPERSYNC_API_KEY exists and USE_HYPERSYNC is not explicitly disabled.
Return type: bool

fetch_vault_settlement_logs(*, web3, address, topic0_list, start_block, end_block, use_hypersync=None, chunk_size=50000)

Fetch vault settlement-style logs using Hypersync or JSON-RPC.

Parameters

web3 (web3.main.Web3) – Web3 connection for the vault chain.
address (Union[eth_typing.evm.HexAddress, str]) – Vault contract address.
topic0_list (list[str]) – Event topic0 values to include.
start_block (int) – Inclusive start block.
end_block (int) – Inclusive end block.
use_hypersync (Optional[bool]) – Whether to use Hypersync. None auto-detects based on environment.
chunk_size (int) – JSON-RPC eth_getLogs chunk size used by the fallback reader.

Returns

Web3-compatible log objects.

Return type

list[web3.datastructures.AttributeDict]

fetch_vault_settlement_logs_for_addresses(*, web3, addresses, topic0_list, start_block, end_block, use_hypersync=None, chunk_size=50000)

Fetch vault settlement-style logs for multiple vaults as one address batch.

Parameters

web3 (web3.main.Web3) – Web3 connection for the vault chain.
addresses (list[eth_typing.evm.HexAddress | str]) – Vault contract addresses.
topic0_list (list[str]) – Event topic0 values to include.
start_block (int) – Inclusive start block.
end_block (int) – Inclusive end block.
use_hypersync (Optional[bool]) – Whether to use Hypersync. None auto-detects based on environment.
chunk_size (int) – JSON-RPC eth_getLogs chunk size used by the fallback reader.

Returns

Web3-compatible log objects.

Return type

list[web3.datastructures.AttributeDict]

fetch_vault_settlement_logs_hypersync(*, web3, address, topic0_list, start_block, end_block)

Fetch vault settlement-style logs using Hypersync.

Parameters

web3 (web3.main.Web3) – Web3 connection for the vault chain.
address (Union[eth_typing.evm.HexAddress, str]) – Vault contract address.
topic0_list (list[str]) – Event topic0 values.
start_block (int) – Inclusive start block.
end_block (int) – Inclusive end block.

Returns

Web3-compatible log objects.

Return type

list[web3.datastructures.AttributeDict]

fetch_vault_settlement_logs_hypersync_for_addresses(*, web3, addresses, topic0_list, start_block, end_block)

Fetch vault settlement-style logs for multiple vaults using Hypersync.

Parameters

web3 (web3.main.Web3) – Web3 connection for the vault chain.
addresses (list[eth_typing.evm.HexAddress | str]) – Vault contract addresses.
topic0_list (list[str]) – Event topic0 values.
start_block (int) – Inclusive start block.
end_block (int) – Inclusive end block.

Returns

Web3-compatible log objects.

Return type

list[web3.datastructures.AttributeDict]

indexed_log_to_web3_log(log)

Convert a Hypersync log to Web3.py log shape.

Parameters: log (eth_defi.vault.flow_events.IndexedVaultFlowLog) – Hypersync log wrapper.
Returns: Web3.py-style log.
Return type: web3.datastructures.AttributeDict

fetch_vault_settlement_logs_rpc(*, web3, address, topics, start_block, end_block, chunk_size)

Fetch vault settlement-style logs using chunked JSON-RPC eth_getLogs.

Parameters

web3 (web3.main.Web3) – Web3 connection.
address (Union[eth_typing.evm.HexAddress, str, list[eth_typing.evm.HexAddress | str]]) – Vault contract address or list of addresses.
topics (list[str]) – Event topic0 values.
start_block (int) – Inclusive start block.
end_block (int) – Inclusive end block.
chunk_size (int) – Maximum block count per eth_getLogs call.

Returns

Web3-compatible logs.

Return type

list[web3.datastructures.AttributeDict]

build_settlement_rows_from_logs(*, chain_id, address, web3, protocol, logs, event_by_topic=None)

Build generic settlement rows from vault logs.

Parameters

chain_id (int) – Vault chain id.
address (Union[eth_typing.evm.HexAddress, str]) – Vault address.
web3 (Optional[web3.main.Web3]) – Web3 connection, needed when logs do not contain timestamps or block hashes.
protocol (str) – Protocol name stored in DuckDB.
logs (list[web3.datastructures.AttributeDict]) – Web3-compatible logs.
event_by_topic (Optional[collections.abc.Mapping[str, Union[web3.contract.contract.ContractEvent, str]]]) – Optional event topic0 to event class/name mapping used to populate event_name.

Returns

Settlement rows sorted by block and transaction hash.

Return type

list[eth_defi.vault.settlement_data.VaultSettlement]

get_log_event_name(log, event_by_topic)

Resolve a Web3 log event name.

Parameters

log (web3.datastructures.AttributeDict) – Web3-compatible log.
event_by_topic (collections.abc.Mapping[str, Union[web3.contract.contract.ContractEvent, str]]) – Mapping from normalised topic0 to event class or event name.

Returns

Event name, or empty string if it cannot be resolved.

Return type

str

normalise_log_topic(topic)

Normalise a Web3 log topic value to lowercase 0x hex.

Parameters: topic (Union[hexbytes.main.HexBytes, bytes, str]) – Topic as bytes, HexBytes, or string.
Returns: Lower-case 0x-prefixed topic.
Return type: str