TECHNICAL CASE STUDY · Indexing · API engineering

PLS Supply API

Accounting from chain data to API.

Implemented API and indexer · retirement scheduled November 21, 2026

PLS Supply API interactive OpenAPI documentation
Public API documentation capture · November 20, 2026.

FROM THE IMPLEMENTATION

Index within finality

Python · SELECTED SOURCE
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)
pls-api-com/app/slot_mapper.py

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

  1. Execution blocks + beacon slots
  2. Finality-aware slot mapping
  3. Python supply accounting
  4. PostgreSQL totals + checkpoints
  5. 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

  1. 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.
  2. 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