Ethereum JSON-RPC Quantities and Hex Data
Decode Ethereum JSON-RPC quantities and byte strings without confusing hexadecimal values, token amounts, addresses or padded contract data.
Overview
When translating these concepts into an integration, keep the scope described by the wallet history api with the result. The examples in wallet transaction history and smart contract event logs show how the same distinction affects neighbouring data questions.
JSON-RPC commonly represents both numbers and bytes as hexadecimal strings. Their appearance can be similar, but their contracts differ. A decoder should know the field type before applying a conversion.
A quantity is not an arbitrary byte array
A quantity encodes a non-negative integer in compact hexadecimal form. Data fields represent byte sequences and preserve byte length. For example, a transaction value and a contract input can both begin with 0x while requiring different handling. Address fields are identifiers; converting them to ordinary numbers discards meaningful formatting and can exceed numeric precision.
Worked example: one unit and one byte
Quantity 0x1 represents integer one. A data field containing the byte 0x01 also has numeric interpretation one, but its one-byte length is part of its representation. Contract return data may pad an integer to a 32-byte ABI word. Parse it with the ABI rather than assuming every 0x-prefixed field is a quantity.
Keep conversions at explicit boundaries
Validate the expected type, reject malformed encodings, and convert large integers with exact arithmetic. Retain the raw field when debugging a decoder. Unit conversion comes later: transaction value is denominated in the network currency base unit, while token amounts use contract-specific decimals. Hex decoding alone does not establish a human-readable asset amount.
A practical acceptance test
Round-trip a compact quantity, an empty data field and a 32-byte ABI word through the decoder. Check both value and byte length where relevant. Include a quantity above 2^53 and verify its exact decimal output. A test that compares only the rounded display can miss a conversion error in the stored integer.
Questions about the topic
Frequently asked questions
Is 0x the same as numeric zero?
An empty data sequence is not the standard quantity representation of zero, which is 0x0.
Can JavaScript Number hold every quantity?
No. Large blockchain integers can exceed its exact integer range.
Standards & technical documentation
