TECHNICAL CASE STUDY · Indexing · API engineering
PLS Supply API
Accounting from chain data to API.
Implemented API and indexer · retirement scheduled November 21, 2026
FROM THE IMPLEMENTATION
Index within finality
finalized_slot = get_finalized_slot()
if finalized_slot is None:
logger.warning("Cannot get finalized slot from beacon API - will retry")
return False
end_slot = min(target_slot, finalized_slot)
When finality is unavailable, retry later. Never map beyond the known finalized boundary. Selected excerpt; intervening comments omitted.
THE ENGINEERING PROBLEM
What needed to work
A supply API has to explain where its numbers come from, not just serve a plausible total. PulseChain accounting combines execution history with consensus staking state, protocol issuance, burns and burn-address balances. I built a Python processing pipeline, PostgreSQL persistence and FastAPI interface to turn those inputs into current, historical and time-series supply data.
Constraints and requirements
- Execution block numbers and consensus slots are separate coordinates. A missing mapping can mean delayed data, a genuine skip or an unresolved error; those cases must not all become an assumed zero.
- Supply totals are cumulative. Processing a later block without complete predecessor data can contaminate every subsequent value, while large validator datasets require bounded batches and deliberate memory use.
ARCHITECTURE & DESIGN
How the system fits together
- Execution blocks + beacon slots
- Finality-aware slot mapping
- Python supply accounting
- PostgreSQL totals + checkpoints
- FastAPI + time series
I separated slot mapping, supply preparation, database access and API presentation. The mapper reads the finalized consensus boundary, processes slot ranges concurrently and stores reusable slot-to-block mappings.
The supply processor gathers the accounting components, validates predecessor continuity and writes prepared records through database sessions. FastAPI provides typed response models and generated documentation for supply, history, time series, burn-address data, mapping statistics and health.
Decisions and tradeoffs
Bound normal slot mapping by finality and retry when finality is unavailable.
The mapper caps its requested range at the observed finalized slot. Failure to obtain that boundary returns a retryable result rather than silently progressing without it.
Tradeoff Accounting can lag the live head. That is an explicit consequence of using a more stable boundary, not evidence that an API’s latest record represents the newest unfinalized block.
Distinguish confirmed skips from execution blocks that still need mapping.
Targeted recovery compares beacon and execution evidence below the mapping frontier. Existing-but-unmapped blocks remain errors; confirmed skips can be excluded while unresolved cases remain pending.
Tradeoff Recovery requires extra probes and retry throttling. Treating every lookup miss as a skip would be simpler but could silently break cumulative accounting.
Validate continuity before committing an accounting batch.
Required predecessor fields and prepared accounting inputs are checked before the batch is stored. The transactional write path commits the group together and rolls back database writes on failure.
Tradeoff One bad input can hold up a batch, and transaction size must remain bounded. That makes incomplete accounting visible rather than accepting partial persistence as successful progress.
PLANNING & EXECUTION
From requirements to working behavior
- I connected the data model to an API that clients can inspect: block-specific responses, bulk history and parameter-limited time series share the stored accounting records instead of independently recomputing totals in each endpoint.
- Operational surfaces include simple and detailed health. Query limits constrain time-series duration, interval and result size, while recovery work addresses holes below a high-water mark instead of assuming that a high frontier proves every earlier mapping exists.
VALIDATION & RECOVERY
How the behavior is checked
- Maintained recovery tests use real SQLAlchemy sessions over an in-memory SQLite fixture, with beacon and execution boundaries scripted independently. They exercise missing mappings, confirmed skips and loud errors for existing blocks.
- Those tests isolate recovery logic; they do not establish production PostgreSQL behavior, complete chain accounting or ongoing endpoint freshness. The case study separates source-backed mechanisms from those broader operational claims.
Implementation references
Repository-relative references identify the implementation behind this case study. Selected code excerpts are also available in the portfolio.
- pls-api-com/app/slot_mapper.py: SlotMapper.ensure_slot_mappings_exist
- pls-api-com/app/supply_processor.py: SupplyProcessor
- pls-api-com/app/supply_processor.py: ensure_previous_block_processed
- pls-api-com/app/postgres_client.py: PostgresClient
- pls-api-com/app/api.py
- pls-api-com/app/tests/test_slot_recovery.py