Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions docs/learn/fundamentals/data-format/xdr.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -213,6 +213,25 @@ 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.
Comment thread
leighmcculloch marked this conversation as resolved.

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`.
Comment thread
leighmcculloch marked this conversation as resolved.

[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.
Expand Down