From b9be4c8c74caa271a792f684d49f7e344586bb25 Mon Sep 17 00:00:00 2001 From: "john.xlm" <60260750+JFWooten4@users.noreply.github.com> Date: Tue, 12 May 2026 23:54:10 -0400 Subject: [PATCH 1/3] =?UTF-8?q?=F0=9F=93=9D=20Refresh=20data=20format=20do?= =?UTF-8?q?cs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Codex --- .../api-reference/structure/data-format.mdx | 2 +- .../fundamentals/data-format/_category_.json | 9 ++++++++ .../fundamentals/data-format/xdr-json.mdx | 1 + docs/learn/fundamentals/data-format/xdr.mdx | 22 ++----------------- 4 files changed, 13 insertions(+), 21 deletions(-) create mode 100644 docs/learn/fundamentals/data-format/_category_.json diff --git a/docs/data/apis/rpc/api-reference/structure/data-format.mdx b/docs/data/apis/rpc/api-reference/structure/data-format.mdx index 26ea7ed242..9106cd933d 100644 --- a/docs/data/apis/rpc/api-reference/structure/data-format.mdx +++ b/docs/data/apis/rpc/api-reference/structure/data-format.mdx @@ -9,7 +9,7 @@ In the Stellar network, transactions are encoded using a standardized protocol c In RPC, you will encounter XDR when [simulating](../methods/simulateTransaction) and [sending](../methods/sendTransaction) transactions, as well as when retrieving [transactions](../methods/getTransactions), [ledgers](../methods/getLedgers), and [ledger entries](../methods/getLedgerEntries). -By default, RPC will return all XDR attributes as the machine-readable base64-encoded string. XDR-encoded response fields are usually suffixed with `Xdr`. You can decode this XDR on the Stellar Lab’s [XDR page](https://lab.stellar.org/xdr/view?$=network$id=testnet&label=Testnet&horizonUrl=https:////horizon-testnet.stellar.org&rpcUrl=https:////soroban-testnet.stellar.org&passphrase=Test%20SDF%20Network%20/;%20September%202015;;). +By default, RPC will return all XDR attributes as the machine-readable base64-encoded string. XDR-encoded response fields are usually suffixed with `Xdr`. You can decode this XDR in the Stellar Lab’s [XDR page](https://lab.stellar.org/xdr/view?$=network$id=testnet&label=Testnet&horizonUrl=https:////horizon-testnet.stellar.org&rpcUrl=https:////soroban-testnet.stellar.org&passphrase=Test%20SDF%20Network%20/;%20September%202015;;). ### JSON Format diff --git a/docs/learn/fundamentals/data-format/_category_.json b/docs/learn/fundamentals/data-format/_category_.json new file mode 100644 index 0000000000..bba43ef4d4 --- /dev/null +++ b/docs/learn/fundamentals/data-format/_category_.json @@ -0,0 +1,9 @@ +{ + "label": "Data Format", + "position": 85, + "link": { + "type": "doc", + "id": "learn/fundamentals/data-format/README" + }, + "description": "Understand Stellar's XDR and JSON encodings so you can inspect transactions, debug payloads, and interchange data with other systems." +} diff --git a/docs/learn/fundamentals/data-format/xdr-json.mdx b/docs/learn/fundamentals/data-format/xdr-json.mdx index efb13a1778..73a18e6908 100644 --- a/docs/learn/fundamentals/data-format/xdr-json.mdx +++ b/docs/learn/fundamentals/data-format/xdr-json.mdx @@ -1,6 +1,7 @@ --- title: XDR-JSON sidebar_position: 2 +description: "Use the XDR-JSON schema to round-trip Stellar XDR payloads through JSON tools without losing fidelity." --- The XDR-JSON schema is defined by the [stellar-xdr crate](https://docs.rs/stellar-xdr) and provides a round-trippable means for converting Stellar [XDR] values to JSON and converting that JSON back to the identical XDR. diff --git a/docs/learn/fundamentals/data-format/xdr.mdx b/docs/learn/fundamentals/data-format/xdr.mdx index f1f0a2c800..b03488d920 100644 --- a/docs/learn/fundamentals/data-format/xdr.mdx +++ b/docs/learn/fundamentals/data-format/xdr.mdx @@ -1,6 +1,7 @@ --- title: XDR sidebar_position: 1 +description: "Understand Stellar's XDR binary format, why it exists, and how to inspect or parse it safely." --- Stellar stores and communicates ledger data, transactions, results, history, and messages in a binary format called External Data Representation (XDR). XDR is defined in [RFC4506]. XDR is optimized for network performance but not human readable. The Stellar SDKs convert XDRs into friendlier formats. @@ -31,7 +32,7 @@ The XDR data is still included (encoded as a base64 string) inside the JSON in c ## Digging into XDR structures -Since the XDR format is a fundamental underpinning of the Stellar Network, we often find it necessary to dig into these raw binary data structures for clients to interact with things like transactions and authorization entries. It can be hard to understand because of its structure, but this section will aim to enlighten you on the ways to interact with it in a handful of popular languages. The Protocol's schema is defined in the [`stellar/stellar-xdr`](https://github.com/stellar/stellar-xdr/) repository, though that contains far more than what we'll need for our purposes. +Since the XDR format is a fundamental underpinning of the Stellar Network, we often find it necessary to dig into these raw binary data structures for clients to interact with things like transactions and authorization entries. It can be hard to understand because of its structure, but this section will aim to enlighten you on the ways to interact with it in a handful of popular languages. The Protocol's schema is defined in the [`stellar/stellar-xdr`](https://github.com/stellar/stellar-xdr) repository, though that contains far more than what we'll need for our purposes. ### XDR's Common Forms @@ -213,25 +214,6 @@ In the last part, we "abuse" the fact that there is only one variation of the `b There are many cases in which the different union arms share structure, and `.value()` lets you take advantage of that. -## Record Marking / Frames in Streams - -In some applications like stellar-core, when multiple XDR objects are stored sequentially in a file or stream, each object is framed using the Record Marking Standard defined in [RFC 5531 Section 11][RFC5531s11]. Each record is composed of one or more fragments. Each fragment begins with a 4-byte header followed by the fragment data: - -- **Bit 31 (high bit)**: Set to `1` if this is the last fragment of the record, `0` if more fragments follow. -- **Bits 0-30**: The length in bytes of the fragment data that follows the header. - -The header is encoded as a 4-byte big-endian unsigned integer. Note that this header is _not_ itself in XDR standard form. - -In Stellar's usage today each record contains exactly one XDR object, encoded as a single fragment with the last-fragment bit always set. This framing is used in: - -- **History archives**: Bucket files and checkpoint ledger files written and read by stellar-core. -- **Streaming LedgerCloseMeta**: The LedgerCloseMeta stream output by stellar-core. - -When decoding XDR with the [stellar-cli], streams framed with the record marking can be decoded by specifying the `--input stream-framed`. - -[stellar-cli]: ../../../tools/cli/stellar-cli.mdx -[RFC5531s11]: https://www.rfc-editor.org/rfc/rfc5531#section-11 - --- This overview should give you a strong baseline on understanding how to inspect XDR in your respective SDK to dig into the fields that you're interested in. Specifics will, of course, be language dependent, but if you start at the foundation--that being the raw [.x files](#.x-files) themselves--you will get an understanding of the structure itself and should be able to access that same structure directly in your language of choice, as we've outlined here. From 5fab8587b56e6fd697e8ebae38e118744a66e4f7 Mon Sep 17 00:00:00 2001 From: "john.xlm" <60260750+JFWooten4@users.noreply.github.com> Date: Tue, 12 May 2026 23:58:26 -0400 Subject: [PATCH 2/3] =?UTF-8?q?=F0=9F=93=9D=20Refine=20data=20format=20doc?= =?UTF-8?q?s?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Codex --- .../api-reference/structure/data-format.mdx | 2 +- .../fundamentals/data-format/xdr-json.mdx | 2 +- docs/learn/fundamentals/data-format/xdr.mdx | 18 +++++++++++++++++- 3 files changed, 19 insertions(+), 3 deletions(-) diff --git a/docs/data/apis/rpc/api-reference/structure/data-format.mdx b/docs/data/apis/rpc/api-reference/structure/data-format.mdx index 9106cd933d..8fedf7d59b 100644 --- a/docs/data/apis/rpc/api-reference/structure/data-format.mdx +++ b/docs/data/apis/rpc/api-reference/structure/data-format.mdx @@ -9,7 +9,7 @@ In the Stellar network, transactions are encoded using a standardized protocol c In RPC, you will encounter XDR when [simulating](../methods/simulateTransaction) and [sending](../methods/sendTransaction) transactions, as well as when retrieving [transactions](../methods/getTransactions), [ledgers](../methods/getLedgers), and [ledger entries](../methods/getLedgerEntries). -By default, RPC will return all XDR attributes as the machine-readable base64-encoded string. XDR-encoded response fields are usually suffixed with `Xdr`. You can decode this XDR in the Stellar Lab’s [XDR page](https://lab.stellar.org/xdr/view?$=network$id=testnet&label=Testnet&horizonUrl=https:////horizon-testnet.stellar.org&rpcUrl=https:////soroban-testnet.stellar.org&passphrase=Test%20SDF%20Network%20/;%20September%202015;;). +By default, RPC will return all XDR attributes as the machine-readable base64-encoded string. XDR-encoded response fields are usually suffixed with `Xdr`. You can decode this XDR in the Stellar Lab's [XDR page](https://lab.stellar.org/xdr/view?$=network$id=testnet&label=Testnet&horizonUrl=https:////horizon-testnet.stellar.org&rpcUrl=https:////soroban-testnet.stellar.org&passphrase=Test%20SDF%20Network%20/;%20September%202015;;). ### JSON Format diff --git a/docs/learn/fundamentals/data-format/xdr-json.mdx b/docs/learn/fundamentals/data-format/xdr-json.mdx index 73a18e6908..fc7a418b59 100644 --- a/docs/learn/fundamentals/data-format/xdr-json.mdx +++ b/docs/learn/fundamentals/data-format/xdr-json.mdx @@ -1,7 +1,7 @@ --- title: XDR-JSON sidebar_position: 2 -description: "Use the XDR-JSON schema to round-trip Stellar XDR payloads through JSON tools without losing fidelity." +description: Use the XDR-JSON schema to round-trip Stellar XDR payloads through JSON tools without losing fidelity. --- The XDR-JSON schema is defined by the [stellar-xdr crate](https://docs.rs/stellar-xdr) and provides a round-trippable means for converting Stellar [XDR] values to JSON and converting that JSON back to the identical XDR. diff --git a/docs/learn/fundamentals/data-format/xdr.mdx b/docs/learn/fundamentals/data-format/xdr.mdx index b03488d920..61d48c71e8 100644 --- a/docs/learn/fundamentals/data-format/xdr.mdx +++ b/docs/learn/fundamentals/data-format/xdr.mdx @@ -1,7 +1,7 @@ --- title: XDR sidebar_position: 1 -description: "Understand Stellar's XDR binary format, why it exists, and how to inspect or parse it safely." +description: Understand Stellar's XDR binary format, why it exists, and how to inspect or parse it safely. --- Stellar stores and communicates ledger data, transactions, results, history, and messages in a binary format called External Data Representation (XDR). XDR is defined in [RFC4506]. XDR is optimized for network performance but not human readable. The Stellar SDKs convert XDRs into friendlier formats. @@ -214,6 +214,22 @@ In the last part, we "abuse" the fact that there is only one variation of the `b There are many cases in which the different union arms share structure, and `.value()` lets you take advantage of that. +## Record Marking / Frames in Streams + +In some applications like stellar-core, when multiple XDR objects are stored sequentially in a file or stream, each object is framed using the Record Marking Standard defined in [RFC 5531 Section 11](https://www.rfc-editor.org/rfc/rfc5531#section-11). Each record is composed of one or more fragments. Each fragment begins with a 4-byte header followed by the fragment data: + +- **Bit 31 (high bit)**: Set to `1` if this is the last fragment of the record, `0` if more fragments follow. +- **Bits 0-30**: The length in bytes of the fragment data that follows the header. + +The header is encoded as a 4-byte big-endian unsigned integer. Note that this header is _not_ itself in XDR standard form. + +In Stellar's usage today each record contains exactly one XDR object, encoded as a single fragment with the last-fragment bit always set. This framing is used in: + +- **History archives**: Bucket files and checkpoint ledger files written and read by stellar-core. +- **Streaming LedgerCloseMeta**: The LedgerCloseMeta stream output by stellar-core. + +When decoding XDR with the [stellar-cli](../../../tools/cli/stellar-cli.mdx), streams framed with the record marking can be decoded by specifying the `--input stream-framed`. + --- This overview should give you a strong baseline on understanding how to inspect XDR in your respective SDK to dig into the fields that you're interested in. Specifics will, of course, be language dependent, but if you start at the foundation--that being the raw [.x files](#.x-files) themselves--you will get an understanding of the structure itself and should be able to access that same structure directly in your language of choice, as we've outlined here. From af562e28b67033797d62c29a473e49a2f01033e3 Mon Sep 17 00:00:00 2001 From: "john.xlm" <60260750+JFWooten4@users.noreply.github.com> Date: Wed, 13 May 2026 00:12:16 -0400 Subject: [PATCH 3/3] =?UTF-8?q?=F0=9F=93=9D=20Address=20data=20format=20re?= =?UTF-8?q?view?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Codex --- docs/data/apis/rpc/api-reference/structure/data-format.mdx | 2 +- docs/learn/fundamentals/data-format/README.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/data/apis/rpc/api-reference/structure/data-format.mdx b/docs/data/apis/rpc/api-reference/structure/data-format.mdx index 8fedf7d59b..0077a4e539 100644 --- a/docs/data/apis/rpc/api-reference/structure/data-format.mdx +++ b/docs/data/apis/rpc/api-reference/structure/data-format.mdx @@ -9,7 +9,7 @@ In the Stellar network, transactions are encoded using a standardized protocol c In RPC, you will encounter XDR when [simulating](../methods/simulateTransaction) and [sending](../methods/sendTransaction) transactions, as well as when retrieving [transactions](../methods/getTransactions), [ledgers](../methods/getLedgers), and [ledger entries](../methods/getLedgerEntries). -By default, RPC will return all XDR attributes as the machine-readable base64-encoded string. XDR-encoded response fields are usually suffixed with `Xdr`. You can decode this XDR in the Stellar Lab's [XDR page](https://lab.stellar.org/xdr/view?$=network$id=testnet&label=Testnet&horizonUrl=https:////horizon-testnet.stellar.org&rpcUrl=https:////soroban-testnet.stellar.org&passphrase=Test%20SDF%20Network%20/;%20September%202015;;). +By default, RPC will return all XDR attributes as the machine-readable base64-encoded string. XDR-encoded response fields are usually suffixed with `Xdr`. You can decode this XDR on the Stellar Lab's [XDR page](https://lab.stellar.org/xdr/view?$=network$id=testnet&label=Testnet&horizonUrl=https:////horizon-testnet.stellar.org&rpcUrl=https:////soroban-testnet.stellar.org&passphrase=Test%20SDF%20Network%20/;%20September%202015;;). ### JSON Format diff --git a/docs/learn/fundamentals/data-format/README.mdx b/docs/learn/fundamentals/data-format/README.mdx index 044cc2da14..fbb2f0dbf2 100644 --- a/docs/learn/fundamentals/data-format/README.mdx +++ b/docs/learn/fundamentals/data-format/README.mdx @@ -1,6 +1,6 @@ --- title: Data Format -sidebar_position: 85 +sidebar_position: 0 --- import DocCardList from "@theme/DocCardList";