JSONRPC

JSON RPC API

JSON is a lightweight data-interchange format. It can represent numbers, strings, ordered sequences of values, and collections of name/value pairs.

JSON-RPC is a stateless, light-weight remote procedure call (RPC) protocol. Primarily this specification defines several data structures and the rules around their processing. It is transport agnostic in that the concepts can be used within the same process, over sockets, over HTTP, or in many various message passing environments. It uses JSON (RFC 4627) as data format.

Types in the JSONRPC

There are several datatypes that are passed over JSON. Of these two are "special" types used particularly for the Ethereum API since Javascript/JSON has no native means of encoding unformatted byte arrays nor large quantities. Both are passed with a hex encoding, however with different requirements to formatting:

When encoding QUANTITIES (integers, numbers): encode as hex, prefix with "0x", the most compact representation (slight exception: zero should be represented as "0x0"). Examples:

• 0x41 (65 in decimal)
• 0x400 (1024 in decimal)
• WRONG: 0x (should always have at least one digit - zero is "0x0")
• WRONG: 0x0400 (no leading zeroes allowed)
• WRONG: ff (must be prefixed 0x)

When encoding UNFORMATTED DATA (byte arrays, account addresses, hashes, bytecode arrays): encode as hex, prefix with "0x", two hex digits per byte. Examples:

• 0x41 (size 1, "A")
• 0x004200 (size 3, "\0B\0")
• 0x (size 0, "")
• WRONG: 0xf0f0f (must be even number of digits)
• WRONG: 004200 (must be prefixed 0x)

Aside from DATA and QUANTITIES, there are also normative JSON types, which we describe as STR (strings) and INT (integer numbers).