json-rpc-spec.md

JSON-RPC SPEC

Overview

The Diem client API is based on the JSON-RPC protocol. This specification defines the client API endpoints and types, and provides usage examples.

List of released stable methods (unless specifically mentioned, all parameters are required for the method.):

• submit(data: string) -> void
• get_transactions(start_version: unsigned_int64, limit: unsigned_int64, include_events: boolean) -> List<Transaction>
• get_account(account: string) -> Account
• get_account_transaction(account: string, sequence_number: unsigned_int64, include_events: boolean) -> List<Transaction>
• get_account_transactions(account: string, start: unsigned_int64, limit: unsigned_int64, include_events: boolean) -> Transaction
• get_metadata(version: unsigned_int64) -> Metadata
• get_events(key: string, start: unsigned_int64, limit: unsigned_int64) -> List<Event>
• get_currencies() -> List<CurrencyInfo>

To implement a client, please checkout our Client Implementation Guide.

Official Client SDKs

• [Go] (https://github.com/diem/client-sdk-go)
• [Java] (https://github.com/diem/client-sdk-java)
• [Python] (https://github.com/diem/client-sdk-python)

JSON-RPC specification

JSON-RPC is a stateless, light-weight remote procedure call (RPC) protocol. Refer to the JSON-RPC Specification for further details.

Diem extensions

The JSON-RPC response object is extended with the following fields:

Field	Type	Meaning
diem_chain_id	unsigned int8	network chain id, e.g. testnet chain id is 2
diem_ledger_version	unsigned int64	server-side latest ledger version number
diem_ledger_timestampusec	unsigned int64	server-side latest ledger timestamp microseconds

You can use this information to verify liveness / status of nodes in the network: if the timestamp or version is old (from the past), it means that the request hit a full node that is not up-to-date.

Example:

{
  "id": 1,
  "jsonrpc": "2.0",
  "diem_chain_id": 2,
  "diem_ledger_timestampusec": 1596680521771648,
  "diem_ledger_version": 3253133,
  "result": {
    "timestamp": 1596680521771648,
    "version": 3253133
  }
}

Batched requests

The JSON-RPC protocol allows requests to be batched. An arbitrary number of requests (maximum 20 by default) can be combined into a single batch and submitted to the server. These requests will be processed together under a single request context.

Errors

If errors occur during a request, they are returned in an error object, as defined in: https://www.jsonrpc.org/specification#error_object. For any invalid request or parameters request, a standard error code and message with human readable information will be returned.

Code	Meaning
-32600	standard invalid request error
-32601	method not found or not specified
-32602	invalid params
-32604	invalid format

Unless specifically mentioned below, Diem JSON-RPC will return the default error code - 32000 for generic server-side errors. More information may be returned in the ‘message’ and the ‘data’ fields, but this is not guaranteed.

Versioning

We use URI versioning to version our API, current version is v1. For example, to hit testnet, the server url is: https://testnet.diem.com/v1. You may check API-CHANGELOG.md and learn more about our API changes.

CORS support

CORS support is embeded.

Allows:

• Origin: any
• Request-Method: POST
• Request-Headers: content-type

HTTP Response Headers Extensions

All Diem JSON-RPC server responses include the following headers:

• X-Diem-Chain-Id: network chain id, e.g. testnet chain id is 2
• X-Diem-Ledger-Version: server-side latest ledger version number
• X-Diem-Ledger-TimestampUsec: server-side latest ledger timestamp microseconds

These headers are similar with Diem extensions, except the value type is all string.