Blockfrost API Compatibility — Progress Tracker

Blockfrost API Compatibility — Progress Tracker

This document is the single source of truth for tracking Blockfrost extension implementation progress, known gaps vs Blockfrost, and links to all related PRs. Update this file as modules are merged or gaps are resolved.

---

✅ Merged into main

Module	Endpoints	PR	Merged
Epoch	/epochs/* — latest, by number, params, stakes, blocks (10 endpoints)	#780	Feb 2026
Address	/addresses/* — info, extended, UTXOs, transactions, total (6 endpoints)	#784	Feb 2026
Asset	/assets/* — list, detail, history, txs, addresses, policy (7 endpoints)	#780	Feb 2026
Block	/blocks/* — latest, by hash/slot/number, txs, next/previous, addresses, CBOR (11 endpoints)	#811	Mar 2026
Transaction	/txs/* — detail, UTXOs, CBOR, metadata, metadata/cbor, redeemers, stakes, delegations, withdrawals, mirs, pool_updates, pool_retires, required_signers (13 endpoints)	#818	Apr 2026

---

🔄 In Progress (Open PRs)

Module	Endpoints	Issue	PR	Status
Account	/accounts/{stake} + 11 sub-endpoints (rewards, history, delegations, registrations, withdrawals, mirs, addresses, assets, utxos, transactions)	#835	#836	Open — last updated Apr 7
Pools	/pools/* — list, extended, retired, retiring, detail, history, metadata, relays, delegators, blocks, updates, votes (12 endpoints)	#846	#847	Open — needs review
Scripts	/scripts/* — list, detail, json, cbor, redeemers, datum, datum/cbor (7 endpoints)	#851	#852	Open — ready to merge
Governance	/governance/dreps/* + /governance/proposals/* (17 endpoints)	#864	#865	Open — reviewers assigned
Network	/, /genesis, /network, /network/eras (4 endpoints)	—	#866	Open — partially stubbed
Metadata	/metadata/txs/labels, /{label}, /{label}/cbor (3 endpoints)	—	#872	Open — ready to merge

---

⚠️ Known Gaps vs Blockfrost Compatibility

These are persistent limitations across all merged and in-progress modules. They are tracked here for traceability.

Structural / Architectural Gaps

Gap	Affected endpoints	Root cause	Fix path
CBOR format mismatch — returns body-only CBOR (a8xx) instead of full tx envelope (84xx = body + witnesses + metadata)	/blocks/{hash}/txs/cbor, /txs/{hash}/cbor	TransactionProcessor stores body-only CBOR	Requires schema + processor change (#829)
tx.size smaller than Blockfrost	/txs/{hash}	TRANSACTION_CBOR.CBOR_SIZE is body-only, not full tx size	Fix alongside CBOR format above
Off-chain pool metadata always null — name, ticker, homepage, description	/pools/{id}, /pools/{id}/metadata, /txs/{hash}/pool_updates	yaci-store does not crawl off-chain pool metadata URLs	Requires separate metadata crawler
Token metadata always null — metadata, onchain_metadata	/assets/{asset}	No token registry / CIP-68 metadata ingestion	Requires token metadata store
POST /tx/submit not supported	/tx/submit	Requires direct node submit API integration	Out of scope for indexer

Data Gaps (require optional stores enabled)

Gap	Affected endpoints	Required config	Notes
active_stake null	/epochs/*, /accounts/{stake}	store.adapot.enabled=true	Graceful degradation when disabled
rewards_sum / withdrawable_amount underreported	/accounts/{stake}	store.adapot.enabled=true	Missing instant_reward + reward_rest sources — tracked in #836
live_stake / live_delegators always "0"	/pools/{id}, /pools/extended	Requires real-time ledger state	Not available in yaci-store — tracked in #847
drep_id always null	/accounts/{stake}	Conway DRep delegation not wired to account	Planned future work
calidus_key always null	/pools/{id}	CIP-0119 not indexed	Out of scope
ratified_epoch / expired_epoch null	/governance/proposals/*	store.governance-aggr.enabled=true	Graceful degradation — tracked in #865
json_metadata / bytes null on governance anchors	/governance/dreps/{id}/metadata, /governance/proposals/{id}/metadata	External metadata fetching out of scope	On-chain anchor URL/hash returned only

Minor / Cosmetic Gaps

Gap	Affected endpoints	Notes
epoch.total_fees mismatch	/epochs/{number}	DB epoch.total_fees wrong; correct: SUM(block.total_fees) — #781 (open, assigned)
Block distribution query slow	/epochs/{number}/blocks, /epochs/{number}/blocks/{pool_id}	Full scan on block table when filtering by epoch + ordering by slot — #791 (open). Fix: idx_block_epoch_slot already shipped in blockfrost-blocks-index-postgresql.sql
Phantom assets cause pagination shift	/assets	6 assets from failed/invalid transactions indexed by yaci-store but not by Blockfrost — causes row count drift on deep pages — #795 (open, assigned)
transaction_metadata duplicate rows on restart	/metadata/txs/labels, /{label}, /{label}/cbor	MetadataRollbackProcessor uses deleteBySlotGreaterThan (exclusive) but the node re-delivers the block at the cursor slot on reconnect — inserts exact duplicates. No unique constraint on (tx_hash, label) — #889 (open)
invalid_before = 0 ambiguity	/txs/{hash}	Cannot distinguish absent from explicitly set to slot 0 without schema change
cip10 always null	/metadata/txs/labels	CIP-10 community registry not integrated — #872
supply.circulating / supply.locked / stake.live stub	/network	Stubs returning "0" — #866
Plutus JSON field ordering cosmetic diff	/scripts/{hash}/json	constructor before fields vs Blockfrost reverse — accepted deviation
/addresses/{address}/extended mirrors base response	/addresses/{address}/extended	decimals and has_nft_onchain_metadata unavailable without CIP-68 ingestion

---

📋 Index Management

This project does not use Flyway for indexes. Indexes are managed via the admin CLI index applier:

# Apply all standard + extra indexes
yaci-store-admin-cli apply-indexes

# Apply only extra (optional heavy) indexes
yaci-store-admin-cli apply-extra-indexes

# Check which indexes are missing
yaci-store-admin-cli verify-indexes

Index definitions live in components/dbutils/src/main/resources/:

• index.yml — standard indexes applied by apply-indexes
• extra-index.yml — optional heavy indexes (e.g., GIN on amounts)

Already covered in index.yml (no action needed)

Index name	Table	Notes
idx_address_utxo_owner_stake_addr	address_utxo	Covers /accounts/{stake}/addresses, /utxos
idx_withdrawal_address, idx_withdrawal_address_slot	withdrawal	Covers /accounts/{stake}/withdrawals
idx_instant_reward_address_slot	instant_reward	Covers rewards_sum adapot query
idx_reward_rest_address_slot	reward_rest	Covers rewards_sum adapot query

Blockfrost-specific indexes — need wiring into extra-index.yml

Each blockfrost module ships its own SQL file but these are not yet registered in the admin CLI (index.yml / extra-index.yml). Operators must currently apply them manually. These should be moved into extra-index.yml so apply-extra-indexes covers them.

SQL file	Key indexes	Related PR
extensions/blockfrost/account/src/main/resources/sql/blockfrost-account-index-postgresql.sql	idx_address_tx_amount_stake_address, idx_address_tx_amount_stake_addr_slot, idx_transaction_tx_hash	#836
extensions/blockfrost/block/src/main/resources/sql/blockfrost-blocks-index-postgresql.sql	idx_transaction_block_tx_index_tx_hash, idx_block_epoch_slot, idx_address_utxo_block, idx_tx_input_spent_at_block_spent_tx_hash	#811
extensions/blockfrost/asset/src/main/resources/sql/blockfrost-asset-index-postgresql.sql	idx_address_utxo_amounts (GIN — already in extra-index.yml), idx_assets_unit_slot, idx_assets_unit_policy, idx_assets_mint_*, idx_transaction_tx_hash_tx_index	#780

TODO: Wire blockfrost SQL index files into extra-index.yml so operators can apply them consistently via the admin CLI instead of running raw SQL scripts.

---

📊 Summary

State	Modules	Approx. Endpoints
Merged in main	5	~47
In open PRs	6	~54
Total when all merged	11	~101

---

Update this file when PRs are merged or gaps are resolved. When opening a new gap-specific issue, link it back to this document for traceability.