binarycodec

Binary Codec

This package contains functions to encode/decode to/from the ripple binary serialization format.

Overview

XRPL nodes communicate using a compact binary format rather than JSON. Before a transaction can be signed or submitted, it must be serialized into this format. The binarycodec package handles that transformation in both directions.

Encoding converts a JSON transaction object into a canonical binary blob:

• Fields are sorted by a protocol-defined ordinal (type code + field code).
• Each field is prefixed with a compact header identifying its type and position.
• Variable-length fields (blobs, account IDs) are preceded by a length prefix.
• The resulting hex string is what gets signed and submitted to the network.

Decoding reverses the process, turning a hex-encoded binary blob back into a JSON object.

There are several encoding variants depending on the use case:

Package Structure

The codec is split into three sub-packages, each with a distinct responsibility:

definitions/

The schema registry for the entire codec. At startup it embeds and parses definitions.json — the authoritative XRPL protocol document — into a singleton Definitions struct. Everything the serializer and parser need to know about a field lives here:

• Types — maps type names (e.g. "UInt32", "Amount") to their numeric type codes.
• Fields — maps field names (e.g. "Fee", "Destination") to a FieldInstance, which contains:
  • FieldHeader (TypeCode + FieldCode): the binary identity of the field written into the encoded stream.
  • Ordinal (TypeCode<<16 | FieldCode): used to sort fields into canonical order before encoding.
  • IsVLEncoded: whether the field value is preceded by a variable-length prefix.
  • IsSerialized: whether the field is included in the encoded blob at all.
  • IsSigningField: whether the field is included when computing the signing payload (EncodeForSigning). Fields like TxnSignature are excluded here.
• TransactionTypes, TransactionResults, LedgerEntryTypes — numeric code mappings for each category.
• DelegatablePermissions / GranularPermissions — permission value mappings used for account delegation features.

serdes/

Contains the low-level binary read/write primitives:

• BinarySerializer — accumulates bytes into a sink. For each field it writes the field header (via FieldIDCodec), an optional variable-length prefix (for VL-encoded fields), and then the raw value bytes. Appends 0xE1 as the STObject end marker when needed.
• BinaryParser — the inverse: reads a hex-encoded stream, decodes field headers back to field names, and hands off to the appropriate type deserializer.
• FieldIDCodec — encodes/decodes the compact field header bytes that prefix every field in the binary format.

types/

One file per XRPL serialization type. Each type implements the SerializedType interface:

type SerializedType interface {
    FromJSON(json any) ([]byte, error)
    ToJSON(parser BinaryParser, opts ...int) (any, error)
}

GetSerializedType(typeName string) acts as the factory, returning the right implementation for a given type name from the definitions.

API

Encode

encoded, err := binarycodec.Encode(jsonObject)

Decode

json, err := binarycodec.Decode(hexEncodedString)

EncodeForMultisigning

encoded, err := binarycodec.EncodeForMultisigning(jsonObject, xrpAccountID)

EncodeForSigning

encoded, err := binarycodec.EncodeForSigning(jsonObject)

EncodeForSigningClaim

encoded, err := binarycodec.EncodeForSigningClaim(jsonObject)

EncodeQuality

encoded, err := binarycodec.EncodeQuality(amountString)

DecodeQuality

decoded, err := binarycodec.DecodeQuality(encoded)

DecodeLedgerData

ledgerData, err := binarycodec.DecodeLedgerData(hexEncodedString)