Skip to main content

XDR

Stellar stores and communicates ledger data, transactions, results, history, and messages in a binary format called External Data Representation (XDR). XDR is optimized for network performance but not human readable. Horizon and the Stellar SDKs convert XDRs into friendlier formats.

.X files​

Data structures in XDR are specified in .x files. These files only contain data structure definitions, no operations or executable code. The .x files for the XDR structures used on the Stellar Network are available on GitHub.

JSON and XDR Conversion Schema​

The canonical JSON and XDR Schema is defined by the stellar-xdr crate and also exposed by the @stellar/stellar-xdr-json-web npm package. The schema provides a round-trippable means for converting any Stellar XDR type to JSON and converting that JSON back to the identical XDR.

This conversion is visible in the Stellar CLI, Lab View XDR, and Hubble events table.

Key Characteristics of the JSON and XDR Conversion Schema​

  • Round-Trippable: The JSON format allows for converting from XDR to JSON and back to XDR without loss of information.
  • Self-Describing: The JSON format describes the internals of the type but does not identify the type that is encoded. This is similar to XDR, which also does not identify the encoded type.
backwards-incompatible

The defined schema (linked above) is not backwards compatible between a given protocol version and prior versions. The best practice is to store required ledger data in XDR format, not in JSON format.

More About XDR​

XDR is specified in RFC 4506 and is similar to tools like Protocol Buffers or Thrift. XDR provides a few important features:

  • It is very compact, so it can be transmitted quickly and stored with minimal disk space.
  • Data encoded in XDR is reliably and predictably stored. Fields are always in the same order, which makes cryptographically signing and verifying XDR messages simple.
  • XDR definitions include rich descriptions of data types and structures, which is not possible in simpler formats like JSON, TOML, or YAML.

Parsing XDR​

Since XDR is a binary format and not as widely known as simpler formats like JSON, the Stellar SDKs all include tools for parsing XDR and will do so automatically when retrieving data.

In addition, the Horizon API server generally exposes the most important parts of the XDR data in JSON, so they are easier to parse if you are not using an SDK. The XDR data is still included (encoded as a base64 string) inside the JSON in case you need direct access to it.