Add high-level details on what network data is available under each endpoint.

docs/data/rpc/api-reference/methods/README.mdx

@@ -8,3 +8,20 @@ import DocCardList from "@theme/DocCardList";
 All you need to know about available RPC methods, parameters and responses, and making RPC requests.
 
 <DocCardList />
+
+Don't know which endpoint you need to get what you want? A lot of the returned fields are deeply-nested [XDR structures](/docs/learn/encyclopedia/data-format/xdr.mdx#more-about-xdr), so it can be hard to figure out what kind of information is available in each of these. Here's a bit of a dive into what the "workhorse" endpoints provide, in decreasing order of granularity:
+
+- [`getLedgers`](./getLedgers.mdx) operates at the block level, providing you with the full, complete details of what occurred during application of that ledger (known as "ledger metadata", defined in the protocol by the [`LedgerCloseMetaV1`](https://github.com/stellar/stellar-xdr/blob/v22.0/Stellar-ledger.x#L508-L537) structure). Each of the subsequent endpoints is just a microscope into a subset of the data available provided by this endpoint. Metadata includes things like:
+  - Details for recreating the blockchain's state (see [Ledger Headers](/docs/learn/encyclopedia/network-configuration/ledger-headers.mdx) for more).
+  - The consensus information that led to the block closing (see [Stellar Consensus Protocol](/docs/learn/fundamentals/stellar-consensus-protocol.mdx)).
+  - The set of transactions, their respective operations, and the results of applying those transactions in this block (see [Transactions](/docs/learn/fundamentals/transactions/operations-and-transactions)).
+- [`getTransaction(s)`](./getTransactions.mdx) operates across a span of ledgers or on a single transaction hash depending on the variant. The structured data here includes details such as:
+  - The exact transaction structure ("envelope") that was submitted.
+  - Results for each of the operations within the transaction.
+  - All side-effects to ledger state that occurred as a result of this transaction.
+- `getEvents` lets you search for events that occurred over a ledger range. Each event is made up of topics (which you can filter on) and data which are `ScVal`s, Stellar's generic "value" type (see [Contract Development](/docs/learn/encyclopedia/contract-development/types/built-in-types) for more).
+- [`getLedgerEntries`](./getLedgerEntries.mdx), in contrast to the above endpoints, provides information about **live** on-chain state rather than historical actions. The [getLedgerEntries](./getLedgerEntries.mdx) page itself goes into detail on the different kinds of state stored on chain and how to fetch them.
+
+If you still aren't sure what you're looking for, remember that you can pass `xdrFormat: "json"` as a parameter to each of these endpoints to get a fully unpacked, human-readable JSON version of the XDR structures returned. You can look through these until you find what you need and go back to the Base64+unpack variation in your app. Equipped with an understanding of how to traverse XDR, the structure of the protocol, and your [favorite SDK](/docs/tools/sdks/), you should be able to find anything you want about the Stellar network with these endpoints.
+
+TODO: Merge #1060 before this so that the above `getLedgerEntries` cross-ref actually makes sense.

docs/data/rpc/api-reference/structure/data-format.mdx

@@ -1,6 +1,6 @@
 ---
 sidebar_position: 60
-title: Data Format
+title: Data Formats
 ---
 
 import { ExampleResponse } from "@site/src/components/ExampleResponse";
@@ -12,23 +12,58 @@ 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 XDR 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
 
 All RPC endpoints which return encoded XDR fields accept the `xdrFormat` attribute. This allows a client to change the response format to JSON, ultimately making it more human-readable. Note that you should not rely on any schema for the JSON, as it will change when the underlying XDR changes.
 
 In the event that a `json` output format is requested, response fields suffixed with `Xdr` will be omitted and replaced with their `Json` suffixed counterparts.
 
-<ExampleResponse title="Example Transaction Response with XDR">
+<ExampleResponse title="Example getTransaction response">
 
 ```json
 {
-  // xdrFormat = base64
-  "resultMetaXdr": AAAAAwAAAAAAAAACAAAAAwAWuFYAAAAAAAAAAEBQYAimx5waQHaAptKgy2a/IAHMSe96ETt5wiMOSpKXAAAAF0JZ4rAAACHUAAekYwAAAAAAAAAAAAAAAAAAAAABAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAgAAAAAAAAAAAAAAAAAAAAMAAAAAABa4VAAAAABnyjD0AAAAAAAAAAEAFrhWAAAAAAAAAABAUGAIpsecGkB2gKbSoMtmvyABzEnvehE7ecIjDkqSlwAAABdCWeKwAAAh1AAHpGQAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAABAAAAAAAAAAAAAAAAAAAAAAAAAAIAAAAAAAAAAAAAAAAAAAADAAAAAAAWuFYAAAAAZ8ow/gAAAAAAAAAAAAAAAAAAAAA=
-
-  // xdrFormat = json
-  "resultMetaJson": { ... }
+  // xdrFormat = 'base64'
+  "resultMetaXdr": "AAAAAwAAAAAAAAACAAAAAwAWuFYAAAAAAAAAAEBQYAimx5waQHaAptKgy2a/IAHMSe96ETt5wiMOSpKXAAAAF0JZ4rAAACHUAAekYwAAAAAAAAAAAAAAAAAAAAABAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAgAAAAAAAAAAAAAAAAAAAAMAAAAAABa4VAAAAABnyjD0AAAAAAAAAAEAFrhWAAAAAAAAAABAUGAIpsecGkB2gKbSoMtmvyABzEnvehE7ecIjDkqSlwAAABdCWeKwAAAh1AAHpGQAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAABAAAAAAAAAAAAAAAAAAAAAAAAAAIAAAAAAAAAAAAAAAAAAAADAAAAAAAWuFYAAAAAZ8ow/gAAAAAAAAAAAAAAAAAAAAA=",
+  // xdrFormat = 'json'
+  "resultMetaJson": {
+    "tx": {
+      "tx": {
+        "source_account": "GCW2NGRNWISFIXSGCBXPU23GDBAMHIOQOWO52LZWEWNELRC4XDQMDWNT",
+        "fee": 100,
+        "seq_num": 58248347706520,
+        "cond": {
+          "time": {
+            "min_time": 0,
+            "max_time": 1741309515
+          }
+        },
+        "memo": {
+          "text": "6764203ea0bcd7058f922d32"
+        },
+        "operations": [
+          {
+            "source_account": null,
+            "body": {
+              "payment": {
+                "destination": "GBZA3UPYFIFXXPH4QPQSFL73TZND7MEN744BLU4DPBR4T2XS526PRRN2",
+                "asset": "native",
+                "amount": 635808330
+              }
+            }
+          }
+        ],
+        "ext": "v0"
+      },
+      "signatures": [
+        {
+          "hint": "5cb8e0c1",
+          "signature": "cfcfc8192be1448b6c1e06265bd89b7375fdd818927f5167071d1e4f383522e6968771c91272fc248b4984f3f8c3ea7089396ab63c5dc557a45130c307f1840a"
+        }
+      ]
+    }
+  }
 }
 ```
 

openrpc/src/stellar-rpc/schemas/Event.json

@@ -53,7 +53,7 @@
         "type": "string"
     },
     "EventValue": {
-        "description": "The emitted body value of the event (serialized in a base64 string).",
+        "description": "The emitted body value of the [DiagnosticEvent](https://github.com/stellar/stellar-xdr/blob/v22.0/Stellar-ledger.x#L360) structure (serialized as a base64 string).",
         "type": "string"
     }
 }

openrpc/src/stellar-rpc/schemas/LedgerEntries.json

@@ -1,10 +1,10 @@
 {
     "LedgerKey": {
         "type": "string",
-        "description": "Ledger key, serialized as a base64 string, corresponding to an existing ledger entry you wish to retrieve."
+        "description": "The [LedgerKey](https://github.com/stellar/stellar-xdr/blob/v22.0/Stellar-ledger-entries.x#L600) union corresponding to an existing ledger entry you want to retrieve (base64-encoded string)."
     },
     "LedgerKeys": {
-        "description": "Array containing ledger keys. The maximum number of ledger keys accepted is 200.",
+        "description": "An array of LedgerKeys. The maximum number of ledger keys accepted is 200.",
         "type": "array",
         "items": {
             "$ref": "#/components/schemas/LedgerKey"
@@ -16,11 +16,11 @@
         "properties": {
             "key": {
                 "type": "string",
-                "description": "The key of the ledger entry (serialized in a base64 string)."
+                "description": "The [LedgerKey](https://github.com/stellar/stellar-xdr/blob/v22.0/Stellar-ledger-entries.x#L600) corresponding to the ledger entry (base64 string)."
             },
             "xdr": {
                 "type": "string",
-                "description": "The current value of the given ledger entry (serialized in a base64 string)."
+                "description": "The key's current [LedgerEntryData](https://github.com/stellar/stellar-xdr/blob/v22.0/Stellar-ledger-entries.x#L564) value (base64 string)."
             },
             "lastModifiedLedgerSeq": {
                 "description": "The ledger sequence number of the last time this entry was updated.",

openrpc/src/stellar-rpc/schemas/Ledgers.json

@@ -18,11 +18,11 @@
       },
       "headerXdr": {
         "type": "string",
-        "description": "A base64 encoded string of the raw `LedgerHeader` xdr struct for this ledger."
+        "description": "The [LedgerHeader](https://github.com/stellar/stellar-xdr/blob/v22.0/Stellar-ledger.x#L74) structure for this ledger (base64-encoded string)."
       },
       "metadataXdr": {
         "type": "string",
-        "description": "A base64 encoded string of the raw `LedgerCloseMeta` xdr struct for this ledger."
+        "description": "The [LedgerCloseMeta](https://github.com/stellar/stellar-xdr/blob/v22.0/Stellar-ledger.x#L539) union for this ledger (base64-encoded string)."
       }
     }
   }

openrpc/src/stellar-rpc/schemas/Transaction.json

@@ -1,7 +1,7 @@
 {
     "Transaction": {
         "title": "transaction",
-        "description": "A Stellar transaction, serialized as a base64 string",
+        "description": "A Stellar [TransactionEnvelope](https://github.com/stellar/stellar-xdr/blob/v22.0/Stellar-transaction.x#L1009) (as a base64-encoded string)",
         "type": "string"
     }
 }

openrpc/src/stellar-rpc/schemas/Transactions.json

@@ -16,19 +16,19 @@
       },
       "envelopeXdr": {
         "type": "string",
-        "description": "A base64 encoded string of the raw TransactionEnvelope XDR struct for this transaction."
+        "description": "The [TransactionEnvelope](https://github.com/stellar/stellar-xdr/blob/v22.0/Stellar-transaction.x#L1009) structure for this transaction (base64-encoded string)."
       },
       "resultXdr": {
         "type": "string",
-        "description": "A base64 encoded string of the raw TransactionResult XDR struct for this transaction."
+        "description": "The [TransactionResult](https://github.com/stellar/stellar-xdr/blob/v22.0/Stellar-transaction.x#L2088) structure for this transaction (base64-encoded string)."
       },
       "resultMetaXdr": {
         "type": "string",
-        "description": "A base64 encoded string of the raw TransactionMeta XDR struct for this transaction."
+        "description": "The [TransactionResultMeta](L446https://github.com/stellar/stellar-xdr/blob/v22.0/Stellar-ledger.x#L461) structure for this transaction (base64-encoded string)."
       },
       "diagnosticEventsXdr": {
         "type": "array",
-        "description": "(optional) A base64 encoded slice of xdr.DiagnosticEvent. This is only present if the `ENABLE_SOROBAN_DIAGNOSTIC_EVENTS` has been enabled in the stellar-core config.",
+        "description": "(optional) A base64 encoded slice of xdr.DiagnosticEvent. This is only present if the `ENABLE_SOROBAN_DIAGNOSTIC_EVENTS` has been enabled on the RPC server.",
         "items": {
           "type": "string"
         }

static/stellar-rpc.openrpc.json

@@ -205,7 +205,7 @@
                     }
                   },
                   "value": {
-                    "description": "The emitted body value of the event (serialized in a base64 string).",
+                    "description": "The emitted body value of the [DiagnosticEvent](https://github.com/stellar/stellar-xdr/blob/v22.0/Stellar-ledger.x#L360) structure (serialized as a base64 string).",
                     "type": "string"
                   },
                   "txHash": {
@@ -690,11 +690,11 @@
           "description": "Array containing the keys of the ledger entries you wish to retrieve. (an array of serialized base64 strings)",
           "required": true,
           "schema": {
-            "description": "Array containing ledger keys. The maximum number of ledger keys accepted is 200.",
+            "description": "An array of LedgerKeys. The maximum number of ledger keys accepted is 200.",
             "type": "array",
             "items": {
               "type": "string",
-              "description": "Ledger key, serialized as a base64 string, corresponding to an existing ledger entry you wish to retrieve."
+              "description": "The [LedgerKey](https://github.com/stellar/stellar-xdr/blob/v22.0/Stellar-ledger-entries.x#L600) union corresponding to an existing ledger entry you want to retrieve (base64-encoded string)."
             }
           }
         },
@@ -732,11 +732,11 @@
                 "properties": {
                   "key": {
                     "type": "string",
-                    "description": "The key of the ledger entry (serialized in a base64 string)."
+                    "description": "The [LedgerKey](https://github.com/stellar/stellar-xdr/blob/v22.0/Stellar-ledger-entries.x#L600) corresponding to the ledger entry (base64 string)."
                   },
                   "xdr": {
                     "type": "string",
-                    "description": "The current value of the given ledger entry (serialized in a base64 string)."
+                    "description": "The key's current [LedgerEntryData](https://github.com/stellar/stellar-xdr/blob/v22.0/Stellar-ledger-entries.x#L564) value (base64 string)."
                   },
                   "lastModifiedLedgerSeq": {
                     "title": "ledgerSequence",
@@ -923,11 +923,11 @@
                   },
                   "headerXdr": {
                     "type": "string",
-                    "description": "A base64 encoded string of the raw `LedgerHeader` xdr struct for this ledger."
+                    "description": "The [LedgerHeader](https://github.com/stellar/stellar-xdr/blob/v22.0/Stellar-ledger.x#L74) structure for this ledger (base64-encoded string)."
                   },
                   "metadataXdr": {
                     "type": "string",
-                    "description": "A base64 encoded string of the raw `LedgerCloseMeta` xdr struct for this ledger."
+                    "description": "The [LedgerCloseMeta](https://github.com/stellar/stellar-xdr/blob/v22.0/Stellar-ledger.x#L539) union for this ledger (base64-encoded string)."
                   }
                 }
               }
@@ -1331,19 +1331,19 @@
                   },
                   "envelopeXdr": {
                     "type": "string",
-                    "description": "A base64 encoded string of the raw TransactionEnvelope XDR struct for this transaction."
+                    "description": "The [TransactionEnvelope](https://github.com/stellar/stellar-xdr/blob/v22.0/Stellar-transaction.x#L1009) structure for this transaction (base64-encoded string)."
                   },
                   "resultXdr": {
                     "type": "string",
-                    "description": "A base64 encoded string of the raw TransactionResult XDR struct for this transaction."
+                    "description": "The [TransactionResult](https://github.com/stellar/stellar-xdr/blob/v22.0/Stellar-transaction.x#L2088) structure for this transaction (base64-encoded string)."
                   },
                   "resultMetaXdr": {
                     "type": "string",
-                    "description": "A base64 encoded string of the raw TransactionMeta XDR struct for this transaction."
+                    "description": "The [TransactionResultMeta](L446https://github.com/stellar/stellar-xdr/blob/v22.0/Stellar-ledger.x#L461) structure for this transaction (base64-encoded string)."
                   },
                   "diagnosticEventsXdr": {
                     "type": "array",
-                    "description": "(optional) A base64 encoded slice of xdr.DiagnosticEvent. This is only present if the `ENABLE_SOROBAN_DIAGNOSTIC_EVENTS` has been enabled in the stellar-core config.",
+                    "description": "(optional) A base64 encoded slice of xdr.DiagnosticEvent. This is only present if the `ENABLE_SOROBAN_DIAGNOSTIC_EVENTS` has been enabled on the RPC server.",
                     "items": {
                       "type": "string"
                     }
@@ -1644,7 +1644,7 @@
           "required": true,
           "schema": {
             "title": "transaction",
-            "description": "A Stellar transaction, serialized as a base64 string",
+            "description": "A Stellar [TransactionEnvelope](https://github.com/stellar/stellar-xdr/blob/v22.0/Stellar-transaction.x#L1009) (as a base64-encoded string)",
             "type": "string"
           }
         }
@@ -1810,7 +1810,7 @@
           "required": true,
           "schema": {
             "title": "transaction",
-            "description": "A Stellar transaction, serialized as a base64 string",
+            "description": "A Stellar [TransactionEnvelope](https://github.com/stellar/stellar-xdr/blob/v22.0/Stellar-transaction.x#L1009) (as a base64-encoded string)",
             "type": "string"
           }
         },