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..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 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 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"; 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..fc7a418b59 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..61d48c71e8 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 @@ -215,7 +216,7 @@ There are many cases in which the different union arms share structure, and `.va ## 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: +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. @@ -227,10 +228,7 @@ In Stellar's usage today each record contains exactly one XDR object, encoded as - **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 +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`. ---