Skip to main content

Casper 1.X -> Casper 2.0 :: JSON-RPC API changes

Introduction​

This article is intended for developers consuming the Casper 2.0 (AKA Condor) JSON RPC, such as dApp developers, SDK developers, or others relying on the JSON-RPC API. In this article we examine the JSON-RPC and break down the differences between v1.5.6 and v2.0.0.

Since the network's inception, the Casper node has exposed an API over HTTP, using JSON, which is known as the JSON-RPC. This API allows client software such as dApps and SDKs to communicate and interact with the node, giving access to query node state, chain state, balance details and other information, as well as to write information to the chain by submitting transactions.

Changes for v2.0​

Casper Sidecar​

One of the major changes in the Condor upgrade is the new casper-sidecar. The sidecar runs in a dedicated process and and is bound to a node's binary port and/or SSE port. The sidecar assumes all responsibility for running the JSON-RPC server and exposing the JSON-RPC endpoints to the internet, i.e. the node software itself no longer exposes a JSON RPC API to the consumer - this job is now done by the sidecar.

Because the sidecar runs in a dedicated process, it is possible to run a sidecar upon a different machine to the node. However in practice, most node operators will likely operate a sidecar process on the same machine as the node. Furthermore an operator's deployment setup is opaque to to a DApp that interacts with the JSON-RPC API via an SDK.

There are several benefits to moving the JSON-RPC API to a sidecar:

  • The JSON-RPC API can now evolve independently of the node
  • A node operator now has a finer degree of control over their operational setup
  • The sidecar reduces the amount of work that the node itself has to do, thereby simplifying the deployment of alternative node implementations (e.g. mojo, go, zig, c++)

Node Binary Port​

The Casper 2.0 Node now exposes a pure Binary Port API, which allows connection over TCP/IP and pure binary serialization for your remote procedure calls. Depending on your use case, you may be interested in considering this option for interacting with Casper Condor. In general, the binary port offers better performance and features compared to the JSON RPC. A detailed discussion of the Binary Port will be contained in a future article. It is anticipated that all SDKs will be updated so as to support the new Binary Port API.

JSON-RPC Differences​

The biggest immediately obvious change in the RPC is the change in name from deploy to transaction. Casper 1.X used the name "deploy" for a unit of work submitted to the blockchain, in Condor a unit of work is now renamed as "Transaction".

JSON-RPC Schema Definitions​

See here for Casper 1.5 node JSON-RPC.

See here for Casper 2.0 node JSON-RPC.

Table of v1.5 & v2.0 JSON-RPC API differences​

Function in v1.5Function in v2.0Remarks
account_put_deployaccount_put_transactionRenamed
chain_get_block_transferschain_get_block_transfersUnchanged
chain_get_blockchain_get_blockNow returns Block with Signatures
chain_get_era_info_by_switch_blockchain_get_era_info_by_switch_blockUnchanged
chain_get_era_summarychain_get_era_summaryUnchanged
chain_get_state_root_hashchain_get_state_root_hashUnchanged
info_get_chainspecinfo_get_chainspecUnchanged
info_get_deployinfo_get_transactionRenamed
info_get_peersinfo_get_peersUnchanged
info_get_statusinfo_get_statusLatest switch block hash included in result
info_get_validator_changesinfo_get_validator_changesUnchanged
query_balancequery_balanceUnchanged
query_balance_detailsAdded
query_global_statequery_global_stateUnchanged
state_get_account_infostate_get_account_infoUnchanged
state_get_auction_infostate_get_auction_infoUnchanged
state_get_balancestate_get_balanceBalance now reflects all active holds
state_get_dictionary_itemstate_get_dictionary_itemUnchanged
state_get_itemstate_get_entityRenamed

Summary​

The major changes in the JSON-RPC between v1.5.6 and v2.0.0 are:

  • The casper-sidecar is now responsible for serving the JSON-RPC API.
  • The sidecar may also expose the Server Side Events API, this is of some relevance to developers relying upon the Casper Event Standard (CES).
  • Deploys are now called Transactions as per the industry norm. There are differences in the representation of these data structures.