VaultSettlementDatabase

Documentation for eth_defi.vault.settlement_data.VaultSettlementDatabase Python class.

class VaultSettlementDatabase

Bases: object

Mini DuckDB interface for vault settlement events.

The schema has no primary key because DuckDB ART indexes have caused stability issues elsewhere in this project. Idempotence is handled with a delete-then-insert transaction keyed by (chain_id, address, tx_hash, event_name). Different transactions in the same block and different settlement events in the same transaction are separate rows.

Parameters

path – DuckDB database path.

Open the database and create the schema if needed.

Parameters

path – DuckDB file path.

Methods summary

__init__(path)	Open the database and create the schema if needed.
close()	Close the database connection.
get_latest_block_number(chain_id, address)	Return the latest stored settlement block for a vault.
get_latest_scanned_block_number(chain_id, ...)	Return the latest successfully scanned settlement block for a vault.
get_settlement_count()	Return the number of stored settlement rows.
get_settlements([chain_id, address, protocol])	Read settlement rows as a DataFrame.
save()	Checkpoint the database.
upsert_scan_state(scan_states)	Update settlement scan watermarks.
upsert_settlements(settlements)	Insert settlement rows idempotently.

__init__(path)

Open the database and create the schema if needed.

Parameters

path (pathlib.Path) – DuckDB file path.

close()

Close the database connection.

Return type

None

save()

Checkpoint the database.

Return type

None

upsert_settlements(settlements)

Insert settlement rows idempotently.

Existing rows with the same (chain_id, address, tx_hash, event_name) are replaced. This lets protocol readers rescan overlapping block ranges without collapsing different settlement transactions in the same block or different event logs in the same transaction.

Parameters

settlements (list[eth_defi.vault.settlement_data.VaultSettlement]) – Settlement rows to store.

Returns

Number of rows inserted.

Return type

int

get_settlements(chain_id=None, address=None, protocol=None)

Read settlement rows as a DataFrame.

Parameters

• chain_id (Optional[int]) – Optional chain filter.

• address (Optional[Union[eth_typing.evm.HexAddress, str]]) – Optional vault address filter.

• protocol (Optional[str]) – Optional protocol filter.

Returns

DataFrame sorted by chain_id, address, timestamp and tx_hash.

Return type

pandas.DataFrame

get_settlement_count()

Return the number of stored settlement rows.

Return type

int

get_latest_block_number(chain_id, address)

Return the latest stored settlement block for a vault.

Parameters

• chain_id (int) – Chain id.

• address (Union[eth_typing.evm.HexAddress, str]) – Vault address.

Returns

Latest block number, or None if no settlement is stored.

Return type

Optional[int]

get_latest_scanned_block_number(chain_id, address)

Return the latest successfully scanned settlement block for a vault.

Settlement events are sparse, so the event table cannot tell whether a vault has no new events or whether it has never been scanned. This scan-state table records successful empty scans as well.

Parameters

• chain_id (int) – Chain id.

• address (Union[eth_typing.evm.HexAddress, str]) – Vault address.

Returns

Latest scanned block number, or None if no scan state exists.

Return type

Optional[int]

upsert_scan_state(scan_states)

Update settlement scan watermarks.

The stored watermark never moves backwards. Forced historical backfills may scan old ranges, but they must not erase knowledge of newer ranges that already completed successfully.

Parameters

scan_states (list[tuple[int, eth_typing.evm.HexAddress | str, int]]) – Tuples of (chain_id, address, last_scanned_block).

Returns

Number of distinct vault scan-state rows updated.

Return type

int