New JSON-RPC Libra client API: The gRPC API is being deprecated

We are deprecating the current gRPC-based Libra* client API and replacing it with a JSON-RPC-based API. We now have an entirely new client API for Libra which is based on the JSON-RPC protocol. We have also separated proof verification into a separate API layer. In this post, we describe the motivation and the reasons for this change.

Motivation

The current Libra node provides an API using the gRPC protocol, with data formatted in LCS (Libra Canonical Serialization) format. This is to enable trustless clients to verify Merkle proofs for the response in the Libra Blockchain. While this approach works well for development purposes, it is not end-user friendly, so we decided to improve it.

Why did we change the protocol?

Currently, the Libra client API uses the gRPC protocol. The gRPC protocol is not HTTP-based and lacks built-in JavaScript support. gRPC uses protocol buffers (binary format) which need to be decoded, and the response format for gRPC is not human-readable. We considered HTTP-based protocols like REST and JSON-RPC to replace the gRPC protocol. The following table shows a comparison between gRPC, REST, and JSON-RPC protocols.

	REST	JSON-RPC	gRPC
HTTP-based	Yes	Yes	No
Schema / SPEC support	Manual	Manual	Auto
Batch support	Non-idiomatic	Yes	Yes
In Browser JS support	Yes	Yes	No (requires proxy)
Response format	JSON (Human-readable)	JSON (Human-readable)	Proto needs to be decoded

Both REST and JSON-RPC are developer-friendly protocols that can be used over HTTP, but REST doesn’t have idiomatic batching support. We need that support for advanced use cases, like:

• pub/sub: Receive notifications about payment events for multiple accounts (access paths).
• risk evaluation: Query information on multiple accounts a Libra Blockchain address interacted with in the past

Why did we separate proof verification?

Use case analysis

After analyzing potential use cases of wallet services that require access to data on the Libra Blockchain, we found out that:

• Most service providers will run Libra full nodes, and a full node already does proof verification on the data received from the Libra Blockchain. Internal clients of these services won’t require extra proof checks.
• Passing Merkle proofs between the services adds complexity and requires the target services to maintain minimal blockchain state in a secure manner.

The advantages

• Removing the support for proof verification from our current client API greatly simplifies the API itself and makes it easier for Libra clients to use the API.
• We don’t need to pass LCS (Libra Canonical Serialization) bytes, which means Libra clients don’t need to perform LCS deserialization for various Libra types. We can just pass human-readable serialized objects (e.g., JSON structs).
• This will make writing and maintaining Libra client libraries simpler. For most typical scenarios, developers won’t need to implement LCS serialization or proof checking at all.

Separate API for proofs

• We have isolated proof verification into a separate API, as some Libra applications (e.g., unhosted wallets) might still prefer to verify proofs.
• This will make it easier for users to query blockchain data from Libra full nodes (even via curl) and receive human-readable responses (e.g., JSON).
• Once a response is received, more sophisticated clients can request proofs for specific objects (e.g., transactions, account states, events) via a separate API call.

When will the Libra client API change?

The new API endpoints are already deployed to testnet and available for use. We’ll support both the old API (gRPC) and the new API (JSON-RPC) during a transition period of four weeks from the date of this blog post.

How do I transition to the new API?

To transition to the new API, you’ll need to rewrite your client libraries to use the new JSON-RPC endpoints.

API specification

Refer to the New Libra Client API – Specification for the JSON-RPC endpoints and types.

Terminology

Merkle proof

Proof of an element in a Merkle tree
The proof consists of node hashes along the tree to calculate the validity of elements under the tree root hash. Use case (example): a Libra client wants to prove the state of an account, e.g., check the account balance and prove that it’s correct.

LCS

Libra Canonical Serialization
LCS is a serialization method for converting data structures used on the Libra Blockchain into consistent byte representations that are platform and language independent. The design is optimized for simplicity and safety.

Questions or comments?

Post your thoughts on this topic in our Libra Developer Community.

*On December 1, 2020, the Libra Association was renamed to Diem Association.