Submerge Crystal: Open-Source Indexer API for Polkadot SDK Chains

Tech Talk
1

Introduction

This thread will be used to share Submerge release updates and news with the Polkadot community, starting with Submerge Crystal, the core indexer component and its API. Submerge is an open-source (GPLv3) indexing, data processing, and compliance platform for Polkadot SDK-based blockchains, being built by Helikon and funded by the Polkadot treasury.

Submerge Crystal API

Submerge Crystal is the core indexer component of Submerge. It is deployed per-chain, and its API exposes blocks, extrinsics, calls, events, storage traces, genesis state, and runtime metadata as queryable REST resources.

Crystal indexes the base data consumed by Submerge’s upper layers, and is also a standalone indexer API for developers who need direct, structured access to historical chain data.

Crystal API documentation is available at docs.submerge.io/crystal-api. The API is currently live for Polkadot Coretime and Polkadot People. The complete set of Polkadot and Kusama relay chains and their system parachains is currently indexing, with public endpoints to follow in the coming days.

The Crystal API is organized around seven resource types:

  • Blocks
  • Calls
  • Events
  • Extrinsics
  • Genesis
  • Metadata
  • Traces

Below is a summary of what each of these sections provides.

Blocks

The Blocks section exposes the chain’s block history through two endpoints. Blocks can be listed and filtered by author, status, runtime spec version, and block number or timestamp ranges, or queried directly by hash or number. Pruned blocks are marked through the status field, alongside finalized blocks.

Calls

The Calls section provides access to the chain’s runtime call history through ten endpoints. The API indexes every dispatched call as a first-class entity, not just as a member of an extrinsic.

This means a query like pallet_name=broker&call_name=renew returns every call instance across the chain history, regardless of whether the call appeared at the top level of an extrinsic or was wrapped inside a call such as utility.batch, proxy.proxy, multisig.asMulti, etc. Name filters accept partial and case-insensitive matches.

The call tree is also accessible. Parent and child relationships are queryable, so a nested call can be traced back to its root call, extrinsic, and signer.

Events

The Events section exposes all events emitted by the runtime during block execution, queryable by pallet name, event name, and ranges of block number, timestamp, and spec version, or scoped to a specific block or extrinsic.

Decoded event arguments are available on demand via the include_args parameter, keeping list responses lean while making full event payloads available.

Extrinsics

The Extrinsics section provides four endpoints that expose signed and unsigned extrinsics, queryable by signer and signed status, or scoped to a specific block.

Genesis

The Genesis section provides access to the chain’s genesis storage records, with each record resolved to its pallet and storage item. This is useful to track storage changes where a storage entity begins its life in the genesis rather than initiated through an extrinsic post-genesis.

Metadata

The Metadata section exposes every indexed runtime version’s metadata, available either as raw SCALE bytes or pre-decoded JSON, and drillable down to the pallet level: calls, events, errors, constants, and storage items can each be queried per pallet, per spec version. This provides convenience for comparing a pallet’s API surface across runtime upgrades.

Traces

The Traces section provides access to storage traces. Every read, write, and delete applied to the chain’s storage during block execution can be queried. Pallet and storage item information is decoded within each trace record.

Traces are filterable by storage key prefix and key parameters, so questions such as “every write to System.Account for this account” or “every change to Staking.Bonded” become single API calls.

Querying storage traces through a public API is not common in the Polkadot infrastructure space. This is typically only available by running a private archive node with State.TraceBlock RPC call exposed.

Try It

Submerge Crystal API documentation is available at docs.submerge.io/crystal-api, with two chains currently available at endpoints as documented on the site:

  • https://coretime.polkadot.crystal.api.submerge.io/v1
  • https://people.polkadot.crystal.api.submerge.io/v1

Please give it a try and let us know about any issues or questions in this thread, via direct messages, or as a GitHub issue.

:robot: Also feel free to point your agent at the OpenAPI specification as a starting point.

Submerge is still under heavy development, so please expect major changes, and follow this thread or the GitHub repository for change tracking.

Known Issues

Filtering calls and events by pallet or name can be slow on rare matches. This is being resolved, and the fix will be patched in the coming days.

What’s Next

  • Polkadot and Kusama relay chains and the remaining system parachains will be available in the coming days.
  • A separate documentation for self-hosting Crystal will be shared.
  • Design and development work continues on Submerge’s upper layers and web application.

All updates will be posted in this thread as they become available.

Thanks for your time.

4 Likes