binarycodec

README

Binary Codec

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

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)

Documentation

Overview

Package binarycodec implements binary serialization and deserialization of XRPL objects using the canonical field ordering defined by the XRPL protocol.

It converts between JSON representations and the compact binary format used for on-ledger storage, transaction signing, and network transmission. Fields are serialized in a deterministic order based on their type code and field code, ensuring identical binary output across all implementations.

The codec supports all XRPL serialized types including amounts, account IDs, hashes, path sets, and nested objects (STObject, STArray).

Index

• Variables
• func Decode(hexEncoded string) (map[string]any, error)
• func DecodeBytes(b []byte) (map[string]any, error)
• func DecodeQuality(quality string) (string, error)
• func Encode(json map[string]any) (string, error)
• func EncodeBytes(json map[string]any) ([]byte, error)
• func EncodeForMultisigning(json map[string]any, xrpAccountID string) (string, error)
• func EncodeForSigning(json map[string]any) (string, error)
• func EncodeForSigningBatch(json map[string]any) (string, error)
• func EncodeForSigningClaim(json map[string]any) (string, error)
• func EncodeQuality(quality string) (string, error)
• type LedgerData
  • func DecodeLedgerData(data string) (LedgerData, error)

Variables

var (
	// ErrSigningClaimFieldNotFound is returned when the channel and amount fields are not both present.
	ErrSigningClaimFieldNotFound = errors.New("channel and amount fields are required")
	// ErrBatchFlagsFieldNotFound is returned when the flags field is missing.
	ErrBatchFlagsFieldNotFound = errors.New("missing flags field")
	// ErrBatchTxIDsFieldNotFound is returned when the txIDs field is missing.
	ErrBatchTxIDsFieldNotFound = errors.New("missing txIDs field")
	// ErrBatchTxIDsNotArray is returned when the txIDs field is not an array.
	ErrBatchTxIDsNotArray = errors.New("txIDs field must be an array")
	// ErrBatchTxIDNotString is returned when a txID is not a string.
	ErrBatchTxIDNotString = errors.New("each txID must be a string")
	// ErrBatchFlagsNotUInt32 is returned when the flags field is not a uint32.
	ErrBatchFlagsNotUInt32 = errors.New("flags field must be a uint32")
	// ErrBatchTxIDsLengthTooLong is returned when the txIDs field is too long.
	ErrBatchTxIDsLengthTooLong = errors.New("txIDs length exceeds maximum uint32 value")
	// ErrUnknownField is returned when Encode receives a JSON key with no
	// matching field definition. Silently dropping unknown keys masks typos
	// (e.g. "Acount" vs "Account") that produce different binary transactions.
	ErrUnknownField = errors.New("unknown field")
)

var (
	// ErrInvalidQuality is returned when the quality is invalid.
	ErrInvalidQuality = errors.New("invalid quality")
)

Functions

func Decode

func Decode(hexEncoded string) (map[string]any, error)

Decode decodes a hex string in the canonical binary format into a JSON transaction object.

func DecodeBytes

func DecodeBytes(b []byte) (map[string]any, error)

DecodeBytes decodes canonical binary bytes into a JSON transaction object. Prefer this over Decode on hot paths that already hold the raw bytes.

func DecodeQuality

func DecodeQuality(quality string) (string, error)

DecodeQuality decodes a quality amount from a hex string to a string.

func Encode

func Encode(json map[string]any) (string, error)

Encode converts a JSON transaction object to a hex string in the canonical binary format. The binary format is defined in XRPL's core codebase.

func EncodeBytes

func EncodeBytes(json map[string]any) ([]byte, error)

EncodeBytes encodes a JSON transaction object directly to canonical binary bytes. Prefer this over Encode on hot paths that immediately re-decode. EncodeBytes does not mutate the caller-supplied map. An unknown field name is treated as an error rather than silently dropped — see ErrUnknownField.

func EncodeForMultisigning

func EncodeForMultisigning(json map[string]any, xrpAccountID string) (string, error)

EncodeForMultisigning encodes a transaction into binary format in preparation for providing one signature towards a multi-signed transaction. Only signing fields are encoded. The caller's map is never mutated.

func EncodeForSigning

func EncodeForSigning(json map[string]any) (string, error)

EncodeForSigning encodes a transaction into binary format in preparation for signing.

func EncodeForSigningBatch

func EncodeForSigningBatch(json map[string]any) (string, error)

EncodeForSigningBatch encodes a batch transaction into binary format in preparation for signing.

func EncodeForSigningClaim

func EncodeForSigningClaim(json map[string]any) (string, error)

EncodeForSigningClaim encodes a payment channel claim into binary format in preparation for signing. The message format is: HashPrefix('CLM\0') + channel_id (32 bytes) + amount (8 bytes big-endian uint64) Note: Unlike normal XRP amounts, payment channel claim amounts use the full uint64 range as raw drops, without the XRP amount validation limits.

func EncodeQuality

func EncodeQuality(quality string) (string, error)

EncodeQuality encodes a quality amount to a hex string.

Types

type LedgerData

type LedgerData struct {
	LedgerIndex         uint32
	TotalCoins          string
	ParentHash          string
	TransactionHash     string
	AccountHash         string
	ParentCloseTime     uint32
	CloseTime           uint32
	CloseTimeResolution uint8
	CloseFlags          uint8
}

LedgerData represents the data of a ledger.

func DecodeLedgerData

func DecodeLedgerData(data string) (LedgerData, error)

DecodeLedgerData decodes a hex string in the canonical binary format into a LedgerData object. The hex string should represent a ledger data object.