erc_4626.vault_protocol.antarctic.historical_context

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

Read Antarctic settlements through Hypersync and persist replayable context.

Only subscriptions supply canonical prices. Redemptions retain their execution amounts for diagnostics. Source interfaces: https://arbiscan.io/address/0x98a6aEE58699e4f4E13D8d8d0800e4e9cbBcf8dD#code

Functions

decode_antarctic_settlement(log, deployment)

Decode a Hypersync log with its verified manager interface.

fetch_and_store_antarctic_history(*, web3, ...)

Prefill selected pools before any common price writer replacement.

fetch_antarctic_settlements(*, ...[, ...])

Fetch exact settlement observations, with cached source timestamps.

get_antarctic_historical_context_path()

Return Antarctic's shared historical context path.

Classes

AntarcticHistoricalContextStore

Persist exact settlement history and successful range cursors.

AntarcticPrefillResult

Summarise a completed context refresh, including pending price repairs.

AntarcticSettlement

One settlement with exact execution amounts and source provenance.
get_antarctic_historical_context_path()

Return Antarctic’s shared historical context path.

Other protocols retain their own tables in this file.

Returns

Pipeline context DuckDB path.

Return type

pathlib.Path

class AntarcticSettlement

Bases: object

One settlement with exact execution amounts and source provenance.

chain_id: int

EVM chain identity.

pool_address: eth_typing.evm.HexAddress

LP token identity, not the manager.

block_number: int

Settlement block.

block_hash: str

Canonical source block hash.

block_timestamp: int

Settlement timestamp, Unix seconds.

transaction_hash: str

Source transaction hash.

log_index: int

Block-wide event index.

kind: str

AddLiquidity or RemoveLiquidity.

account: eth_typing.evm.HexAddress

Investor whose settlement was processed.

raw_usdt: int

USDT raw amount; serialised as decimal text in DuckDB.

raw_shares: int

Raw LP shares; serialised as decimal text in DuckDB.

raw_tvl: int

Handler-reported pre-batch raw TVL.

data: str

Original unindexed log bytes for audit/re-decoding.

property source_id: str

Identify a log across replay and database imports.

Block hash is compared separately so a reorg can replace a location.

Returns

Chain, LP token, transaction and log index identity.

__init__(chain_id, pool_address, block_number, block_hash, block_timestamp, transaction_hash, log_index, kind, account, raw_usdt, raw_shares, raw_tvl, data)
Parameters
Return type

None

class AntarcticPrefillResult

Bases: object

Summarise a completed context refresh, including pending price repairs.

observations_fetched: int

Number of source events read, including overlap.

observations_inserted: int

New or replaced source records.

repair_from_blocks: collections.abc.Mapping[eth_typing.evm.HexAddress, int]

Earliest outstanding canonical rewrite per selected pool.

__init__(observations_fetched, observations_inserted, repair_from_blocks)
Parameters
Return type

None

decode_antarctic_settlement(log, deployment)

Decode a Hypersync log with its verified manager interface.

Reject source mismatches and non-positive subscription denominators. Request events are deliberately excluded by the query and are rejected here too.

Parameters
Returns

Exact settlement, awaiting cached block timestamp resolution.

Return type

eth_defi.erc_4626.vault_protocol.antarctic.historical_context.AntarcticSettlement

class AntarcticHistoricalContextStore

Bases: contextlib.AbstractContextManager

Persist exact settlement history and successful range cursors.

File-backed bulk tables intentionally have no ART primary/unique indexes. A complete overlap replacement removes orphaned logs, including removed-only reorgs. Pending price repairs survive a subsequent writer failure.

Open the shared store without altering foreign protocol tables.

Parameters

path – Shared context DuckDB path.

Returns

None.

__init__(path)

Open the shared store without altering foreign protocol tables.

Parameters

path (pathlib.Path) – Shared context DuckDB path.

Returns

None.

Return type

None

fetch_cursor(address)

Read successful range coverage and outstanding price repair.

Empty successful ranges have cursors too, avoiding repeated full scans.

Parameters

address (eth_typing.evm.HexAddress) – Reviewed LP token address.

Returns

Exclusive completed block and earliest pending price repair.

Return type

tuple[int | None, int | None]

replace_range(address, start_block, end_block, observations)

Commit a complete source range and cursor transactionally.

Hash joins compare exact staged records before replacing the target interval. All validation completes before changing persistent tables.

Parameters
Returns

Fetched and inserted/replaced counts.

Return type

tuple[int, int]

acknowledge_repair(address, end_block)

Clear a pending repair after a successful complete price rewrite.

The caller must have written the pool through its completed source end.

Parameters

  • address (eth_typing.evm.HexAddress) – LP token whose price rewrite succeeded.

  • end_block (int) – Exclusive successful price writer boundary.

Returns

None.

Return type

None

iter_settlements(address, start_block, end_block, *, canonical_only=False)

Yield exact source records or one canonical subscription per block.

Raw context retains every event; common price storage collapses a block to the last canonical log, deterministically.

Parameters

  • address (eth_typing.evm.HexAddress) – LP token identity.

  • start_block (int) – Inclusive range boundary.

  • end_block (int) – Exclusive range boundary.

  • canonical_only (bool) – Select last AddLiquidity per block when true.

Returns

Ordered immutable source records.

Return type

collections.abc.Iterator[eth_defi.erc_4626.vault_protocol.antarctic.historical_context.AntarcticSettlement]

fetch_antarctic_settlements(*, hypersync_client, deployment, start_block, end_block, timestamp_cache_path=PosixPath('/home/runner/.tradingstrategy/block-timestamp'))

Fetch exact settlement observations, with cached source timestamps.

Uses only indexed Hypersync logs and exact block headers, never eth_getLogs or a dense timestamp backfill. Reorg block hashes come from the source logs.

Parameters
Returns

Source observations in block/log order.

Return type

collections.abc.Iterator[eth_defi.erc_4626.vault_protocol.antarctic.historical_context.AntarcticSettlement]

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

Prefill selected pools before any common price writer replacement.

Successful quiet ranges advance independent per-pool cursors. A bounded replay replaces orphaned logs and records repairs until the writer succeeds.

Parameters

  • web3 (web3.main.Web3) – Connection used for chain identity only.

  • hypersync_client (eth_defi.hypersync.session.ThrottledHypersyncClient) – Configured indexed event client.

  • pool_start_blocks (collections.abc.Mapping[eth_typing.evm.HexAddress, int]) – Selected LP tokens and inclusive source bounds.

  • end_block (int) – Exclusive reorg-safe scan boundary.

  • context_path (pathlib.Path) – Shared historical context database.

  • timestamp_cache_path (pathlib.Path) – Exact-block timestamp cache root.

  • force_backfill (bool) – Re-read the full requested range regardless of cursor, for an explicit operator migration or a deeper historical repair.

Returns

Read/write counts and persistent pending repairs.

Return type

eth_defi.erc_4626.vault_protocol.antarctic.historical_context.AntarcticPrefillResult