Skip to content

Add a chain

Another package can add a chain without changing this one. It registers an adapter under the entry point group multichain_indexer.adapters; the entry point's name is the chain's name and its value the factory that builds the adapter. Once that package is installed, the chain works everywhere: the Python API, every command, --chain all, the report and the HTTP API.

examples/plugin-template in the repository is a complete, tested plugin to copy. Its tests install it the way pip would and use it through the Python API and the command line.

1. Declare the entry point

[project]
name = "examplechain-indexer"
dependencies = ["multichain-analytics-indexer>=0.7,<0.8"]

[project.entry-points."multichain_indexer.adapters"]
examplechain = "examplechain_indexer:create_indexer"

The name cannot be one of the built-in chains; a plugin that tries is refused with an error naming it. A plugin is imported only when its chain is used.

2. Describe the chain

A ChainProfile says what shared code needs: the native token's symbol and decimals, the base unit, the networks, the default network, and the model for the chain's native block.

PROFILE = ChainProfile(
    name="examplechain",
    native_symbol="EXC",
    base_unit="drop",
    native_decimals=6,
    networks=("testnet",),
    default_network="testnet",
    transaction_model=ExampleTransaction,
)

Put what is specific to the chain in NativeData models. Never squeeze it into the shared fields.

3. Implement BaseIndexer

Method Does
validate_address refuse a malformed address before any request
fetch_account, fetch_asset, fetch_contract read one item; raise InvalidInput for what the chain does not have
chain_head the newest height the endpoint serves
iter_account_transactions yield pages newest first, honouring from_height, to_height and cursor
chain_metrics metrics only this chain has
describe label and value pairs in the chain's own terms
requests_made, aclose request count and cleanup
final_height, recheck_pending override when the chain has no instant finality

Send requests through ApiClient from multichain_indexer.core.http, so timeouts, retries, Retry-After and the response cache come for free, and take the limiter from shared_limiter(host_scope(server), rate), or key_scope when a key is shared with other chains. Measure the public endpoint's limit through ApiClient before choosing the rate.

4. Write the factory

def create_indexer(network, settings, cache=None):
    chosen = network or PROFILE.default_network
    server = settings.endpoint("examplechain", chosen, "API_SERVER", DEFAULT_SERVERS[chosen])
    client = ApiClient(
        server,
        timeout=settings.request_timeout,
        max_retries=settings.max_retries,
        limiter=shared_limiter(host_scope(server), REQUESTS_PER_SECOND),
        cache=cache,
    )
    return ExampleIndexer(chosen, client)

settings.endpoint reads EXAMPLECHAIN_TESTNET_API_SERVER from .env, the environment or [chains.examplechain.testnet] in config.toml, and refuses plain http to remote hosts.

5. Test it

Test the parser on saved real responses, the adapter against a local fake server, and the plugin as installed: tests/test_plugins.py shows how, with a .dist-info folder holding entry_points.txt on the import path.