erc_4626.vault_protocol.frankencoin.backfill

Documentation for eth_defi.erc_4626.vault_protocol.frankencoin.backfill Python module.

Address-scoped Frankencoin Shares metadata and historical backfill.

Only Ethereum FCS is reconciled. Existing discovery counts and timestamps, unrelated vaults, chain discovery progress and scheduled reader state survive. New leads use targeted Hypersync events; FPS wrapping is counted as configuration activity rather than fresh ZCHF deposits.

Functions

apply_frankencoin_shares_metadata(vault_db, ...)

Apply one prepared FCS row while preserving discovery progress.

fetch_frankencoin_shares_detection(vault, ...)

Reclassify existing discovery or fetch a new target-only lead.

fetch_frankencoin_shares_metadata(web3, ...)

Validate FCS and prepare a replacement row without changing the cache.

fetch_frankencoin_shares_prices(vault, *, ...)

Backfill FCS alone through the common hourly Parquet writer.

FRANKENCOIN_SHARES_SPEC = VaultSpec(chain_id=1, vault_address='0xdb861830d9ae2d1fcf99fa0cfd3973de382b0b5b')

Fixed address scope for every metadata and price write.

fetch_frankencoin_shares_detection(vault, vault_db, hypersync_client, metadata_block)

Reclassify existing discovery or fetch a new target-only lead.

Preserve observed discovery history when available. A previously absent deployment is seeded at its reviewed creation block. Event counts come from configured Hypersync, using the verified FCS event interface; see https://docs.frankencoin.com/pool-shares/fcs for wrapping mechanics.

Parameters
Returns

FCS detection with its dedicated classification.

Return type

eth_defi.erc_4626.core.ERC4262VaultDetection

fetch_frankencoin_shares_metadata(web3, vault_db, token_cache, hypersync_client, metadata_block)

Validate FCS and prepare a replacement row without changing the cache.

Validate the chain, underlying FPS and ZCHF pointers against the reviewed deployment catalogue before any metadata or historical file write: https://github.com/Frankencoin-ZCHF/Frankencoin/blob/8b4c4ab67bb361b91d58c474b87f4608fc4c0566/exports/address.config.ts.

Parameters
  • web3 (web3.main.Web3) – Ethereum RPC connection.

  • vault_db (eth_defi.vault.vaultdb.VaultDatabase) – Existing metadata, retained during preparation.

  • token_cache (eth_defi.token.TokenDiskCache) – Temporary or configured ERC-20 metadata cache.

  • hypersync_client (hypersync.HypersyncClient) – Configured Hypersync client for missing leads.

  • metadata_block (int) – Consistent current-state metadata block.

Returns

Validated adapter, detection and merged metadata row.

Raises

ValueError – If chain, pointers or the rebuilt metadata are invalid.

Return type

tuple[eth_defi.erc_4626.vault_protocol.frankencoin.shares.FrankencoinSharesVault, eth_defi.erc_4626.core.ERC4262VaultDetection, eth_defi.vault.vaultdb.VaultRow]

apply_frankencoin_shares_metadata(vault_db, detection, row)

Apply one prepared FCS row while preserving discovery progress.

Update only the reviewed identity. Existing leads, including their observed event counters, are preserved; a missing lead is reconstructed from the prepared detection. Chain cursors are never advanced.

Parameters
Returns

None; the caller controls persistence.

Return type

None

fetch_frankencoin_shares_prices(vault, *, rpc_url, output_path, token_cache, hypersync_client, timestamp_cache_path, start_block, end_block, max_workers)

Backfill FCS alone through the common hourly Parquet writer.

The writer preserves other addresses and rows outside the half-open block range. This stateless invocation never reads or changes scanner progress. Use a staged output copy so failed or empty scans cannot replace good data. Accounting semantics: https://docs.frankencoin.com/pool-shares/fcs.

Parameters
  • vault (eth_defi.erc_4626.vault_protocol.frankencoin.shares.FrankencoinSharesVault) – Reviewed Ethereum FCS adapter.

  • rpc_url (str) – Project-format space-separated Ethereum RPC URLs.

  • output_path (pathlib.Path) – Staged Parquet containing any retained existing rows.

  • token_cache (eth_defi.token.TokenDiskCache) – ERC-20 metadata cache.

  • hypersync_client (hypersync.HypersyncClient) – Configured Ethereum Hypersync client.

  • timestamp_cache_path (pathlib.Path) – Preserved dense per-chain timestamp directory.

  • start_block (int) – Inclusive boundary, at or after deployment.

  • end_block (int) – Exclusive boundary after start_block.

  • max_workers (int) – Maximum archive-reading workers.

Returns

Common writer report with FCS price observations.

Raises
  • ValueError – If scope, range, workers or timestamp cache are invalid.

  • RuntimeError – If output is empty or core accounting contains failed reads.

Return type

eth_defi.vault.historical.ParquetScanResult