tokenised_fund.sygnum.backfill

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

Backfill reviewed Sygnum FILQ metadata and Chainlink bundle NAV history.

The shared Chainlink DataFeedsCache emits every accepted FILQ bundle as a BundleReportUpdated event. Hypersync reads these reports without JSON-RPC log-range queries; archive RPC state supplies the FILQ token supply at each report block. Only the two reviewed FILQ identifiers are replaced in shared raw and cleaned price files.

Run with source .local-test.env && PROTOCOLS=sygnum poetry run python scripts/backfill-tokenised-funds.py. Set DRY_RUN=true to inspect the address-scoped plan without writing. VAULT_DB_PATH, price database paths, START_BLOCK, END_BLOCK and MAX_WORKERS may be overridden for controlled runs.

Functions

create_detection([address, ...])	Create a reviewed FILQ share-class detection.
create_lead([address, first_seen_at_block, ...])	Create an address-scoped discovery lead.
fetch_filq_historical_read(report, vault)	Fetch token supply for one Chainlink report and construct a price row.
fetch_filq_historical_reads(reports, ...)	Fetch FILQ supplies for Chainlink reports in parallel.
main()	Run the FILQ metadata and Chainlink bundle history migration.
parse_bool_env(name, *, default)	Read a conventional Boolean environment variable.
upsert_filq_metadata(vault_db, rows, end_block)	Upsert FILQ share classes while restoring the Ethereum discovery cursor.
write_filq_historical_reads(path, reads, ...)	Atomically replace FILQ rows in the shared raw price Parquet.

parse_bool_env(name, *, default)

Read a conventional Boolean environment variable.

Parameters

• name (str) – Environment-variable name.

• default (bool) – Value used when the variable is absent.

Returns

Parsed Boolean value.

Return type

bool

create_detection(address='0x54a4fc78431f9201824643e99bec891bb7462a1d', first_seen_at_block=24972132, first_seen_at=datetime.datetime(2026, 4, 27, 2, 19, 35))

Create a reviewed FILQ share-class detection.

Returns

Hardcoded non-event-derived FILQ detection.

Parameters

• address (str) –

• first_seen_at_block (int) –

Return type

eth_defi.erc_4626.core.ERC4262VaultDetection

create_lead(address='0x54a4fc78431f9201824643e99bec891bb7462a1d', first_seen_at_block=24972132, first_seen_at=datetime.datetime(2026, 4, 27, 2, 19, 35))

Create an address-scoped discovery lead.

Returns

FILQ potential vault match.

Parameters

• address (str) –

• first_seen_at_block (int) –

Return type

eth_defi.erc_4626.discovery_base.PotentialVaultMatch

upsert_filq_metadata(vault_db, rows, end_block)

Upsert FILQ share classes while restoring the Ethereum discovery cursor.

Parameters

• vault_db (eth_defi.vault.vaultdb.VaultDatabase) – Existing shared vault database.

• rows (dict) – Fresh FILQ metadata rows.

• end_block (int) – Block at which metadata was read.

Returns

None.

Return type

None

fetch_filq_historical_read(report, vault)

Fetch token supply for one Chainlink report and construct a price row.

Parameters

• report (eth_defi.chainlink.bundle_aggregator.ChainlinkBundleReport) – Hypersync-discovered FILQ bundle report.

• vault (eth_defi.tokenised_fund.sygnum.vault.SygnumVault) – FILQ share class matching report.data_id.

Returns

Priced FILQ history row at the report block.

Return type

eth_defi.vault.base.VaultHistoricalRead

fetch_filq_historical_reads(reports, vaults_by_data_id, max_workers)

Fetch FILQ supplies for Chainlink reports in parallel.

Parameters

• reports (list[eth_defi.chainlink.bundle_aggregator.ChainlinkBundleReport]) – Hypersync-discovered reports for the reviewed data ids.

• vaults_by_data_id (dict[bytes, eth_defi.tokenised_fund.sygnum.vault.SygnumVault]) – FILQ adapter keyed by Chainlink data id.

• max_workers (int) – Maximum archive-RPC worker threads.

Returns

Historical rows ordered by block and log index.

Raises

ValueError – If Hypersync returned an unexpected feed identifier.

Return type

list[eth_defi.vault.base.VaultHistoricalRead]

write_filq_historical_reads(path, reads, start_block)

Atomically replace FILQ rows in the shared raw price Parquet.

Existing unrelated chains, vaults, rows before start_block and native protocol columns are retained. Schema migration failures propagate so a corrupt production Parquet can never be silently discarded.

Parameters

• path (pathlib.Path) – Shared uncleaned vault-price Parquet path.

• reads (list[eth_defi.vault.base.VaultHistoricalRead]) – Fresh FILQ event-derived rows.

• start_block (int) – Inclusive replacement boundary.

Returns

Tuple of deleted and inserted row counts.

Return type

tuple[int, int]

main()

Run the FILQ metadata and Chainlink bundle history migration.

Returns

None.

Return type

None