Skip to main content
Last updated

Chainweb node API

As discussed in Chainweb simplified, Chainweb is a scalable proof-of-work (PoW) consensus algorithm. Chainweb extends the Bitcoin Nakamoto consensus algorithm, a protocol designed for a single chain, to handle consensus with transactions coming from multiple parallel chains. Because Chainweb scales horizontally by using multiple chains, the Kadena network provides better transaction throughput with lower transaction fees than other proof-of-work blockchains.

The Chainweb node API consists of two distinct APIs: the peer-to-peer (P2P) API and the service API.

  • The peer-to-peer API contains the RPC endpoints that nodes must expose to support consensus and the queueing and processing of transactions. The peer-to-peer endpoints are intended primarily for communication between Chainweb nodes. These endpoints are typically more efficient than the service API endpoints for most use cases. However, peer-to-peer endpoints only expose features that are required for the peer-to-peer network to function. For most use cases, you should send API requests to service API endpoints.

  • The service API allows querying and control of Chainweb nodes by clients outside of the blockchain network. Node operators must explicitly enable access to the service API and expose its endpoints on a different network interface than the peer-to-peer API. The specific service API endpoints that are exposed for any node depend on the node configuration settings.

For more information about the peer-to-peer API and its endpoints, see Peer-to-peer API. For more information about the service API and its endpoints, see Service API.

Getting documentation

This part of the documentation summarizes the key endpoints you can use to query and update Chainweb nodes and the data models you should be familiar with when interacting with Chainweb nodes and the blockchain network.

For full documentation of the Chainweb node API, including sample requests and responses, see the generated Kadena Chainweb Node OpenAPI. You can also build and serve the OpenAPI documentation locally from a Docker container.

To build a local copy of the documentation:

  1. Open a terminal shell on your computer.

  2. Clone the chainweb-openapi repository by running the following command:

    git clone https://github.com/kadena-io/chainweb-openapi.git
    git clone https://github.com/kadena-io/chainweb-openapi.git

  3. Change to the root of the chainweb-openapi repository by running the following command:

    cd chainweb-openapi
    cd chainweb-openapi

  4. Build the documentation from the Dockerfile by running the following command:

    docker build . --tag chainweb.openapi
    docker build . --tag chainweb.openapi

  5. Serve the API documentation locally using http://localhost:8080/openapi/ by running the following command:

    docker run --rm --publish 8080:80 chainweb.openapi
    docker run --rm --publish 8080:80 chainweb.openapi

To provide feedback or report bugs for the API documentation, open an issue in the chainweb-openapi repository.

To provide feedback or report bugs for the chainweb-node software, open an issue in the chainweb-node repository.

Peer-to-peer API

The Chainweb P2P API is used for inter-node communication to establish blockchain consensus. Each computer running chainweb-node serves these endpoints using the secure Hypertext Transfer Protocol (HTTPS) on a network interface and port that is available directly on the public internet.

You can also make P2P API endpoints available for other clients by exposing the endpoints using reverse proxies, load balancers, authentication frameworks, or similar web technologies.

Endpoints

The Chainweb peer-to-peer API includes the following endpoints:

Base URL

The base URL for peer-to-peer API endpoints typically take the form of <hostname>/chainweb/0.0/mainnet01 where the <hostname> is the IP address or domain name of a Chainweb node in the Kadena public blockchain network. Similarly, the base URL for peer-to-peer endpoints in the Kadena test network is typically <hostname>/chainweb/0.0/testnet04 where the <hostname> is the IP address or domain name of a Chainweb node in the Kadena test network. If you're running a local development environment, you can typically replace <hostname> with localhost:8080 to connect to the API and specify development as the network name.

Service API

The Chainweb service API includes endpoints that expose functionality of the Chainweb node to clients other than computers running the chainweb-node software. For example, other clients might include mining pools, decentralized services, web applications, exchanges, wallets, and so on.

If you're a node operator, you can enable service API endpoints using configuration settings for the Chainweb node. The endpoints are served on a separate port over the unencrypted Hypertext Transfer Protocol (HTTP). As a node operator, you can also choose to expose the endpoints locally or through reverse proxies, load balancers, authentication frameworks, and other similar web technologies.

Endpoints

The Chainweb service API includes the following endpoints:

Base URL

Because the service API is configurable for individual nodes, the base URL for service API endpoints can vary. For bootstrap nodes, service API endpoints typically take the form of api.<hostname>/chainweb/0.0/mainnet01 where the <hostname> is the IP address or domain name of a Chainweb node in the Kadena public blockchain network. Similarly, the base URL for service API endpoints in the Kadena test network is typically api.testnet.<hostname>/chainweb/0.0/testnet04 where the <hostname> is the IP address or domain name of a Chainweb node in the Kadena test network. If you're running a local development environment, you can typically replace <hostname> with localhost:8080 to connect to the API and, if necessary, specify development as the network name.

Note that if you send requests to Pact endpoints through the service API to query information from a specific chain, you should include the chain identifier in the route prefix. For example, the URL should include /chain/{chainId}/pact/ in addition to the base URL. For more information about Pact endpoints, see the Pact REST API or the Pact OpenAPI specification.

Resource consumption and vulnerability

Some of the endpoints of the service API can require considerable resources on the server side and administrators should be careful when exposing those publicly. Generally, endpoints of the service API are more vulnerable to DOS attacks.

Data models

Data models summarize the parameters that define important Chainweb node elements. You can view the data models for the following Chainweb node features.

Binary encoding

For technical details about binary encoding and calculated values, see Binary encoding.