Skip to main content

Kadena REST API

As discussed in Basic concepts, 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 three distinct sets of endpoints:

  • The Pact server API contains endpoints that you can use to connect locally to a Pact built-in HTTP server to simulate connecting to a Chainweb node to sign, submit, and check the status of transactions.

  • 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 Pact API endpoints or 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 Pact API and its endpoints, see Pact API. 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.

Pact API​

The Pact API is your gateway to interacting with smart contracts on the Kadena blockchain. With Pact API endpoints, you can perform the following command tasks:

  • Execute smart contract functions.
  • Query contract state.
  • Submit transactions to the blockchain.
  • Interact with the Pact interpreter for testing and development.

Pact API is essential for developers building decentralized applications (dApps) and working directly with smart contracts.

Peer-to-peer API​

The Chainweb peer-to-peer (P2P) API provides low level access to node operations on the Kadena blockchain network. The P2P endpoints are primarily used for inter-node communication to establish blockchain consensus. Each computer running chainweb-node must expose 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. However, you should keep in mind that peer-to-peer endpoints only expose features that are required for the peer-to-eer network to function. For most use cases, you should send API requests to Pact API endpoints or service API endpoints.

Endpoints​

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

  • State cut height endpoints
  • Payload endpoints
  • Mempool endpoints
  • Peer endpoints
  • Configuration endpoint

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 the 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.

Service API endpoints enable you to query and retreive information about node activity and chain-specific operations. For example, service API endpoints enable you can perform the following common tasks:

  • Query block and transaction information.
  • Retrieve network statisticss and node status.
  • Interact with the peer-to-peer network.
  • Access chain-specific data in Kadena's multi-chain architecture.

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 service API includes endpoints for requesting the following types of information:

  • Raw full blocks
  • Blocks by block hash
  • Block headers
  • Block header update events
  • Transaction status
  • Node health and general information

The service API also includes endpoints for the following types of jobs:

  • Starting and checking the status of database backup jobs
  • Requesting new work and posting solutions for miners

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 API.

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.