vault.flow_events

Documentation for eth_defi.vault.flow_events Python module.

Asynchronous vault request event discovery helpers.

Functions

`create_pending_vault_flow`(*, chain_id, ...)	Create a pending vault flow from common indexed log metadata.
`decode_hypersync_int`(value)	Decode a hex integer field returned by Hypersync.
`decode_indexed_event_address`(topic)	Decode an indexed address topic.
`decode_indexed_event_uint`(topic)	Decode an indexed unsigned integer topic.
`decode_single_uint256_event_data`(data)	Decode a single non-indexed `uint256` event argument.
`event_data_to_bytes`(data)	Convert ABI event data to bytes.
`fetch_vault_flow_logs_for_addresses_hypersync`(*, ...)	Fetch raw vault request logs for multiple vaults with Hypersync.
`fetch_vault_flow_logs_hypersync`(*, ...)	Fetch raw vault request logs with Hypersync.
`normalise_event_topic`(topic)	Normalise an event topic to a lower-case `0x`-prefixed hex string.
`run_vault_flow_log_fetch`(coroutine)	Run a Hypersync log fetch coroutine from sync code.

Classes

`IndexedVaultFlowLog`	Raw indexed log data returned by Hypersync for vault flow discovery.
`PendingVaultFlow`	An indexed asynchronous vault request event.
`VaultFlowDirection`	Direction of an asynchronous vault flow.

class VaultFlowDirection

Bases: enum.Enum

Direction of an asynchronous vault flow.

deposit = 'deposit': The flow moves denomination tokens into a vault and later claims shares.

redeem = 'redeem': The flow moves vault shares into escrow and later claims denomination tokens.

class PendingVaultFlow

Bases: object

An indexed asynchronous vault request event.

This object is the protocol-neutral bridge between event discovery and higher-level accounting recovery. It intentionally carries both the raw request facts and a serialised ticket payload that can be fed back to the protocol-specific vault ticket reconstruction path.

Parameters

chain_id – EVM chain id where the event was emitted.
vault_address – Vault contract that emitted the request event.
owner – Economic owner of the request.
controller – ERC-7540 controller address where applicable. Protocols without a separate controller use the owner address.
direction – Deposit or redemption request.
status – Status implied by the event. Request events are emitted before settlement, so this is normally pending; callers can query the current status with the reconstructed ticket.
request_id – Protocol request id, if any.
settlement_id – Protocol settlement id, if any.
raw_assets – Raw denomination token amount for deposits, when known.
raw_shares – Raw vault share amount for redemptions, when known.
request_tx_hash – Transaction hash that emitted the request event.
request_block_number – Block number that emitted the request event.
request_block_timestamp – Naive UTC timestamp for the request block, when provided by the event backend.
log_index – Log index for stable event identity.
ticket_data – Serialised protocol ticket data compatible with the manager’s reconstruct_*_ticket() methods.

__init__(chain_id, vault_address, owner, controller, direction, status, request_id, settlement_id, raw_assets, raw_shares, request_tx_hash, request_block_number, request_block_timestamp, log_index, ticket_data)

Parameters

chain_id (int) –
vault_address (eth_typing.evm.HexAddress) –
owner (eth_typing.evm.HexAddress) –
controller (Optional[eth_typing.evm.HexAddress]) –
direction (eth_defi.vault.flow_events.VaultFlowDirection) –
status (enum.Enum) –
request_id (Optional[int]) –
settlement_id (Optional[int]) –
raw_assets (Optional[int]) –
raw_shares (Optional[int]) –
request_tx_hash (str) –
request_block_number (int) –
request_block_timestamp (Optional[datetime.datetime]) –
log_index (int) –
ticket_data (dict) –

Return type

None

create_pending_vault_flow(*, chain_id, vault_address, owner, controller, direction, status, log, ticket_data, request_id=None, settlement_id=None, raw_assets=None, raw_shares=None)

Create a pending vault flow from common indexed log metadata.

Parameters

chain_id (int) –
vault_address (eth_typing.evm.HexAddress) –
owner (eth_typing.evm.HexAddress) –
controller (Optional[eth_typing.evm.HexAddress]) –
direction (eth_defi.vault.flow_events.VaultFlowDirection) –
status (enum.Enum) –
log (eth_defi.vault.flow_events.IndexedVaultFlowLog) –
ticket_data (dict) –
request_id (Optional[int]) –
settlement_id (Optional[int]) –
raw_assets (Optional[int]) –
raw_shares (Optional[int]) –

Return type

eth_defi.vault.flow_events.PendingVaultFlow

class IndexedVaultFlowLog

Bases: object

Raw indexed log data returned by Hypersync for vault flow discovery.

address: eth_typing.evm.HexAddress: Contract address that emitted the log.

topics: list[str | None]: Log topics as hex strings.

data: str: ABI-encoded non-indexed event data.

block_number: int: Emitting block number.

block_timestamp: Optional[datetime.datetime]: Optional block timestamp as naive UTC.

transaction_hash: str: Transaction hash as a hex string.

log_index: int: Log index inside the transaction.

__init__(address, topics, data, block_number, block_timestamp, transaction_hash, log_index)

Parameters

address (eth_typing.evm.HexAddress) –
topics (list[str | None]) –
data (str) –
block_number (int) –
block_timestamp (Optional[datetime.datetime]) –
transaction_hash (str) –
log_index (int) –

Return type

None

decode_hypersync_int(value)

Decode a hex integer field returned by Hypersync.

Parameters: value (Union[int, str]) –
Return type: int

normalise_event_topic(topic)

Normalise an event topic to a lower-case 0x-prefixed hex string.

Parameters: topic (Union[str, bytes]) – Topic value from Web3.py or Hypersync.
Returns: Lower-case 0x-prefixed topic.
Return type: str

event_data_to_bytes(data)

Convert ABI event data to bytes.

Parameters: data (Union[str, bytes]) – Hex string or bytes returned by the event backend.
Returns: Raw ABI payload bytes.
Return type: bytes

decode_indexed_event_address(topic)

Decode an indexed address topic.

Parameters: topic (Union[str, bytes]) – ABI event topic containing a right-aligned address.
Returns: Checksummed address.
Return type: eth_typing.evm.HexAddress

decode_indexed_event_uint(topic)

Decode an indexed unsigned integer topic.

Parameters: topic (Union[str, bytes]) – ABI event topic.
Returns: Decoded integer.
Return type: int

decode_single_uint256_event_data(data)

Decode a single non-indexed uint256 event argument.

Parameters: data (Union[str, bytes]) – ABI event data payload.
Returns: Decoded integer.
Return type: int

fetch_vault_flow_logs_hypersync(*, hypersync_client, vault_address, topic0_list, start_block, end_block)

Fetch raw vault request logs with Hypersync.

This synchronous wrapper keeps vault manager APIs threaded and blocking, matching the rest of the vault manager interface.

Parameters

hypersync_client – Configured Hypersync client for the vault chain.
vault_address (eth_typing.evm.HexAddress) – Vault contract address to scan.
topic0_list (list[str]) – Event signature topics to include.
start_block (int) – Inclusive start block.
end_block (int) – Inclusive end block.

Returns

Raw logs sorted by (block_number, log_index).

Return type

list[eth_defi.vault.flow_events.IndexedVaultFlowLog]

fetch_vault_flow_logs_for_addresses_hypersync(*, hypersync_client, vault_addresses, topic0_list, start_block, end_block)

Fetch raw vault request logs for multiple vaults with Hypersync.

This synchronous wrapper keeps vault manager APIs threaded and blocking, matching the rest of the vault manager interface.

Parameters

hypersync_client – Configured Hypersync client for the vault chain.
vault_addresses (list[eth_typing.evm.HexAddress | str]) – Vault contract addresses to scan in one Hypersync request.
topic0_list (list[str]) – Event signature topics to include.
start_block (int) – Inclusive start block.
end_block (int) – Inclusive end block.

Returns

Raw logs sorted by (block_number, log_index).

Return type

list[eth_defi.vault.flow_events.IndexedVaultFlowLog]

run_vault_flow_log_fetch(coroutine)

Run a Hypersync log fetch coroutine from sync code.

Parameters: coroutine – Coroutine returning indexed vault flow logs.
Returns: Raw logs sorted by (block_number, log_index).
Return type: list[eth_defi.vault.flow_events.IndexedVaultFlowLog]