Skip to main content

Node management API

When postchain is run in managed mode (as it always does with a management chain), the module in bc0 must fulfill a specific API. This API provides information to postchain about which blockchains to run and blockchain and node configurations.

Any postchain module that fulfills this API may serve as bc0. The module is typically written in Rell, where blockchains and nodes are managed through consensus voting. It is up to the module to decide how to answer these queries. For example, >50% of bc0 signers must agree on a new blockchain before it gets visible through nm_api. Another good approach is to have a designated admin that adds blockchains and configurations, but that comes with some centralization.

This topic refrains from explaining individual bc0 modules. We are focusing instead on the general process of setting up a cluster in managed mode, which is independent of which bc0 module is used.

Postchain in managed mode expects that bc0 provides the following queries:

nm_get_peer_infosReturn a list of peers (IP address, port, pubkey)
nm_get_peer_list_versionReturn an integer version. This could be the timestamp of the last block at the time the node list was updated, but it could be anything as long as it changes every time the node list changes.
nm_compute_blockchain_listReturn a list of blockchain RIDs that the node identified by the provided pubkey should run.
nm_get_blockchain_configurationReturn a blockchain's effective configuration, as a byte array, with RID brid at the provided height.
nm_find_next_configuration_heightReturn the height at which the next configuration change occurs. If no future configuration changes are planned, or if brid doesn't exist, null is returned. The returned integer is strictly greater than the height.
nm_get_blockchain_replica_node_mapReturn all replicas for each blockchain, thus a map from brid to the replica node's pubkey.