tokenised_fund.sygnum.historical

Documentation for eth_defi.tokenised_fund.sygnum.historical Python module.

Historical state reader for Sygnum FILQ shares.

Classes

SygnumVaultHistoricalReader

Read FILQ supply and its official Chainlink bundle NAV.

SygnumVaultReaderState

Adaptive reader state for FILQ's synthetic USD denomination.
class SygnumVaultReaderState

Bases: eth_defi.erc_4626.vault.VaultReaderState

Adaptive reader state for FILQ’s synthetic USD denomination.

Parameters

  • vault – The vault we are reading historical data for

  • tvl_threshold_1d_read – If the TVL is below this threshold, we will not read it more than once per day, otherwise hourly.

  • down_hard – Stop reading the vault if the TVL is down by this percentage from the peak.

  • min_tvl_threshold – If the vault never reaches this TVL, we stop reading it after the traction period.

  • traction_period – How long we wait for the vault to get traction before we stop reading it.

Parm peaked_tvl_threshold

The TVL value we first need to reach to trigger down hard condition.

property exchange_rate: decimal.Decimal

Return one because FILQ NAV and TVL are already denominated in USD.

__init__(vault, tvl_threshold_1d_read=Decimal('10000'), tiny_tvl_threshold_rare_read=Decimal('1000'), peaked_tvl_threshold=Decimal('200000'), min_tvl_threshold=Decimal('1500'), down_hard=0.98, traction_period=datetime.timedelta(days=60))
Parameters

  • vault (eth_defi.erc_4626.vault.ERC4626Vault) – The vault we are reading historical data for

  • tvl_threshold_1d_read – If the TVL is below this threshold, we will not read it more than once per day, otherwise hourly.

  • down_hard – Stop reading the vault if the TVL is down by this percentage from the peak.

  • min_tvl_threshold – If the vault never reaches this TVL, we stop reading it after the traction period.

  • traction_period (datetime.timedelta) – How long we wait for the vault to get traction before we stop reading it.

Parm peaked_tvl_threshold

The TVL value we first need to reach to trigger down hard condition.

property freshness_qualified: bool

Determine live-row eligibility from persisted estimated USD TVL.

The existing last_tvl and max_tvl values provide the $1,500 entry and $1,000 exit limits without another stored reader-state flag. An unknown denomination conversion cannot certify USD TVL.

Returns

Whether this vault meets the live price-row TVL limits.

get_broken_calls()

Get all calls marked as broken.

Returns

Dict of function_name -> check_block for broken calls

Return type

dict[str, int]

get_call_status(function_name)

Get the status of a function call.

Parameters

function_name (str) – The function name to check

Returns

Tuple of (check_block, reverts) or None if not checked yet

Return type

Optional[tuple[int, bool]]

get_frequency()

Return the adaptive poll cadence for the last estimated USD TVL.

Peaked and faded vaults poll weekly regardless of TVL. Other vaults at or above $10,000 poll hourly; those from $1,000 to $10,000 poll daily. Tiny vaults poll daily for their first 14 days and weekly thereafter. Live row retention uses a separate seven-day interval. Readers with no verified TVL yet use the hourly cadence until a denomination read permits ordinary TVL-based scheduling.

Returns

Poll-frequency label and minimum interval between calls.

Return type

tuple[Literal[‘peaked’, ‘faded’, ‘large_tvl’, ‘small_tvl’, ‘tiny_tvl’, ‘first_read’, ‘not_started’, ‘early’, ‘unverified_tvl’], datetime.timedelta | None]

load(data)

Load the state from a dictionary.

Parameters

data (dict) –

on_called(result, total_assets=None, share_price=None)

Update adaptive polling and USD TVL qualification from a real read.

The denomination-token total assets are converted using the existing exchange_rate estimate. An unknown-rate sentinel does not certify a vault as having meaningful USD TVL. Entry is $1,500 and exit is below $1,000; eligibility is derived from persisted latest and peak TVL across scan cycles.

Parameters
Returns

None.

on_unpriced_call(result)

Update adaptive scan state for a successful supply-only read.

Some tokenised funds expose their share supply but no reviewed scalar NAV or TVL. They still need persistent reader state so the stateful scanner can cache token metadata, advance its last-read block and throttle historical calls. Zero values are internal scheduling sentinels only; the exported historical row must continue to expose None for its share price and total assets.

Parameters

result (eth_defi.event_reader.multicall_batcher.EncodedCallResult) – Successful supply call carrying a block number and timestamp.

Return type

None

pformat()

Pretty print the current state.

Return type

str

requires_result_feedback()

Drain pending observations before choosing another low-frequency read.

Request feedback once for each new first/low-frequency observation. Remember the request locally so an unchanged failed reader cannot force every block into a separate flush. Unknown TVL keeps its existing hourly buffering after the first attempt. This marker never advances saved state.

Returns

Whether the next sampled block needs this result first.

Return type

bool

save()

Persist state across multiple runs.

Returns

Pickleable Python object

Return type

dict

set_call_status(function_name, check_block, reverts)

Record the status of a function call.

Parameters

  • function_name (str) – The function name to record

  • check_block (int) – The block number when we checked

  • reverts (bool) – True if the call reverted

Return type

None

should_invoke(call, block_identifier, timestamp)

Check the condition if this multicall is good to go.

Parameters
Return type

bool

should_skip_call(function_name)

Check if a specific function call should be skipped for this vault.

Part of the warmup system to detect and skip broken contract calls. See README-reader-states.md for documentation.

Parameters

function_name (str) – The function name as stored in extra_data[“function”]

Returns

True if the call was marked as reverting

Return type

bool

first_seen_at_block

Passed from the vault discovery reader, pass the block number as args when we know this vault popped in to the existing

last_tvl: Optional[decimal.Decimal]

TVL from the last read

first_read_at: datetime.datetime

Timestamp of the block of the first successful read of this vault.

max_tvl: decimal.Decimal

Start with zero TVL

last_share_price: decimal.Decimal

Start with zero share price

last_call_at: Optional[datetime.datetime]

When this vault received its last eth_call update

last_block: Optional[int]

When this vault received its last eth_call update

peaked_at: datetime.datetime

Disable reading if the vault has peaked (TVL too much down) and is no longer active

peaked_tvl: float

What was TVL when we disabled reading due to peaking

faded_at: datetime.datetime

Disable reading if the vault has never gotten any traction

traction_period

How much time after deployment we allow to get traction

min_tvl_threshold

Minimum TVL traction threshold to start reading the vault

tiny_tvl_threshold_rare_read

Vaults we do no really care about

entry_count

How many on_called() invocations have we had

invoke_count_passed

How many should_invoke() invocations have we had

invoke_count_first_read

How many should_invoke() invocations have we had

invoke_count_missing_freq

How many should_invoke() invocations have we had

invoke_count_throttled

How many should_invoke() invocations have we had

rpc_error_count

Track RPCc errors

denomination_token_address

Cache denomination token address when preparing readers

share_token_address

Cache share token address when preparing readers

one_raw_share

One share in its raw units

one

Cache denomination token address when preparing readers

chain_id

Copy for state debuggin

vault_poll_frequency

Cache for how often we are polling this vault, the mode name

token_symbol

Cache for debuggin

unsupported_token

Cache for debuggin

call_status: dict[str, tuple[int, bool]]

Map of function names to their call status for warmup system Key is the function name from extra_data[“function”] Value is tuple (check_block: int, reverts: bool) Example: {“maxDeposit”: (12345678, True)} means maxDeposit reverts, detected at block 12345678

class SygnumVaultHistoricalReader

Bases: eth_defi.vault.base.VaultHistoricalReader

Read FILQ supply and its official Chainlink bundle NAV.

FILQ’s price feed is a Chainlink bundle proxy rather than an AggregatorV3 feed. Historical state reads use latestBundle() at the sampled block; the targeted Sygnum backfill separately reads every accepted report event through eth_defi.chainlink.bundle_aggregator and Hypersync.

Create the FILQ state reader.

Parameters

  • vault – FILQ adapter.

  • stateful – Retained for shared reader compatibility.

__init__(vault, stateful)

Create the FILQ state reader.

Parameters

  • vault (SygnumVault) – FILQ adapter.

  • stateful (bool) – Retained for shared reader compatibility.

construct_multicalls()

Construct FILQ supply and Chainlink bundle calls.

Returns

Supply, bundle, report-timestamp and schema-validation calls.

Return type

collections.abc.Iterable[eth_defi.event_reader.multicall_batcher.EncodedCall]

process_result(block_number, timestamp, call_results)

Convert supply and bundle results to a priced history row.

Parameters
Returns

FILQ supply, NAV/share and total NAV history row.

Return type

eth_defi.vault.base.VaultHistoricalRead

fetch_contextual_historical_reads(start_block, end_block, step)

Yield protocol-sourced historical rows outside the static call grid.

Contextual readers override this method and read an already-prefilled local cache. Network collection belongs before the common price scan.

Parameters

  • start_block (int) – Inclusive archive block boundary.

  • end_block (int) – Exclusive archive block boundary.

  • step (int) – Approximate block spacing used to downsample source observations.

Returns

Ordinary VaultHistoricalRead rows for the common writer.

Raises

NotImplementedError – If a reader opts into contextual history without implementing it.

Return type

Iterable[eth_defi.vault.base.VaultHistoricalRead]

property share_price_change_threshold: float

Return this reader’s sparse share-price comparison threshold.

Event-only readers may require every exact price change; ordinary readers retain the existing ten-basis-point suppression threshold.

Returns

Non-negative relative suppression threshold.

property uses_contextual_history: bool

Return whether this reader supplies protocol-sourced observations.

Most EVM vaults expose static calldata that the common multicaller can execute on a regular block grid. Protocols such as GMX instead expose sparse value events that are prefetched into a protocol-owned cache.

Returns

False for the ordinary static-multicall path.

property uses_share_price_equivalence: bool

Return whether cash flows must be ignored by the sparse filter.

Vault-like products without a standard share-price method can still expose a supply-normalised price equivalent. Their TVL and supply changes must not create false performance observations.

Returns

True when the vault carries the share_price_equivalence feature.