getLedgerEntries: Outline building and parsing all sorts of LedgerKeys
#1060
Conversation
Shaptic
added
documentation
|
Something went wrong with PR preview build please check |
2 similar comments
|
Something went wrong with PR preview build please check |
|
Something went wrong with PR preview build please check |
Shaptic
requested review from
leighmcculloch,
janewang,
tomerweller,
ElliotFriend and
kalepail
|
Something went wrong with PR preview build please check |
|
Preview is available here: |
|
Something went wrong with PR preview build please check |
|
Preview is available here: |
| ::: | ||
| ### Contract Data | ||
|
|
||
| Suppose we've deployed the [`increment` example contract] and want to find out what value is stored in the `COUNTER` ledger key. To build the key, |
| import { RpcMethod } from "@site/src/components/RpcMethod"; | ||
| import rpcSpec from "@site/static/stellar-rpc.openrpc.json"; | ||
|
|
||
| <RpcMethod | ||
| method={rpcSpec.methods.filter((meth) => meth.name === "getLedgerEntries")[0]} | ||
| /> | ||
|
|
||
| ### Generating `keys` Parameters | ||
| The Stellar ledger is, on some level, essentially a key-value store. The keys are `LedgerKey`s and the values are `LedgerEntryData`s in the XDR. An interesting product of the store's internal design is that the key is a _subset_ of the entry: we'll see more of this later. |
There was a problem hiding this comment.
Losing the heading here looks pretty odd when rendered, because this text blocks starts inside the example section:
|
|
||
| The example above is querying a deployment of the [`increment` example contract] to find out what value is stored in the `COUNTER` ledger entry. This value can be derived using the following code snippets. You should be able to extrapolate from the provided examples how to get `keys` parameters for other types and values. | ||
| The `getLedgerEntries` method returns the "values" (or "entries") for a given set of "keys". `LedgerKey`s come in a lot of forms, and we'll go over the valuable ones on this page alongside tutorials on how to build and use them. |
There was a problem hiding this comment.
What do you mean by valuable? Commonly used?
| The `getLedgerEntries` method returns the "values" (or "entries") for a given set of "keys". `LedgerKey`s come in a lot of forms, and we'll go over the valuable ones on this page alongside tutorials on how to build and use them. | |
| The `getLedgerEntries` method returns the "values" (or "entries") for a given set of "keys". `LedgerKey`s come in a lot of forms, and we'll go over the commonly used ones on this page alongside tutorials on how to build and use them. |
|
|
||
| :::note | ||
| The source of truth should always be the XDR defined in the protocol. `LedgerKey`s are a union type defined in [Stellar-ledger-entries.x](https://github.com/stellar/stellar-xdr/blob/529d5176f24c73eeccfa5eba481d4e89c19b1181/Stellar-ledger-entries.x#L600). There are 10 different forms a ledger key can take: |
There was a problem hiding this comment.
Can this link be to a protocol version. XDR is tagged.
|
|
||
| If you are using the [Python](https://stellar-sdk.readthedocs.io/en/latest/) `stellar_sdk` to generate these keys, you will need to install the latest version of the SDK. This can be done like so: | ||
| 1. **Account:** holistically defines a Stellar account, including its balance, signers, etc. (see [Accounts](https://developers.stellar.org/docs/learn/fundamentals/stellar-data-structures/accounts)) |
There was a problem hiding this comment.
At the beginning of the list, the list is describe as "forms a ledger key can take," however the list describes the ledger entries, rather than the keys. For example:
Account: holistically defines a Stellar account, including its balance, signers, etc.
Maybe:
There are 10 different forms a ledger key can take and each refers one-to-one with the following ledger entries:
| 1. **Account:** holistically defines a Stellar account, including its balance, signers, etc. (see [Accounts](https://developers.stellar.org/docs/learn/fundamentals/stellar-data-structures/accounts)) | ||
| 2. **Trustline:** defines a balance line to a non-native asset issued on the network (see [`changeTrustOp`](https://developers.stellar.org/docs/learn/fundamentals/transactions/list-of-operations#change-trust)) |
There was a problem hiding this comment.
The 'defines' is pretty repetitive in this section, suggest dropping it:
| 1. **Account:** holistically defines a Stellar account, including its balance, signers, etc. (see [Accounts](https://developers.stellar.org/docs/learn/fundamentals/stellar-data-structures/accounts)) | |
| 2. **Trustline:** defines a balance line to a non-native asset issued on the network (see [`changeTrustOp`](https://developers.stellar.org/docs/learn/fundamentals/transactions/list-of-operations#change-trust)) | |
| 1. **Account:** a Stellar account, including its balance, signers, etc. (see [Accounts](https://developers.stellar.org/docs/learn/fundamentals/stellar-data-structures/accounts)) | |
| 2. **Trustline:** a balance holding an issued asset (see [`changeTrustOp`](https://developers.stellar.org/docs/learn/fundamentals/transactions/list-of-operations#change-trust)) |
|
|
||
| ##### Python | ||
| <CodeExample> | ||
|
|
||
| ```python |
There was a problem hiding this comment.
Some examples are Python and JavaScript, some are Python and TypeScript, and some are unlabelled and I assume just JavaScript. Can we make them consistent, maybe all JS instead of TS, and all also have Python?
| If you don't want to parse the XDR out programmatically, you can also leverage both the [Stellar CLI](https://developers.stellar.org/docs/tools/developer-tools/cli/stellar-cli) and the [Stellar Lab](https://lab.stellar.org/xdr/view) to get a human-readable view of ledger keys and entries. For example, | ||
|
|
||
| ```bash | ||
| echo 'AAAAAAAAAAAL76GC5jcgEGfLG9+nptaB9m+R44oweeN3EcqhstdzhQ==' | stellar xdr decode --type LedgerKey | jq |
There was a problem hiding this comment.
jq makes some assumptions about a developers environment and assumes some familiarity with the tool. Suggest tweaking as below to be more inclusive, and to narrowly focus on the Stellar tools:
| echo 'AAAAAAAAAAAL76GC5jcgEGfLG9+nptaB9m+R44oweeN3EcqhstdzhQ==' | stellar xdr decode --type LedgerKey | jq | |
| echo 'AAAAAAAAAAAL76GC5jcgEGfLG9+nptaB9m+R44oweeN3EcqhstdzhQ==' | stellar xdr decode --type LedgerKey --output json-formatted |
This command with the use of echo and pipe probably won't work on Windows. Could you add a tabbed box for Windows with the equivalent Windows command? The docs don't do this consistently yet but in new docs we're putting some effort into working on windows. (@fnando has suggested using UTM to try out windows commands.)
This makes the following changes:
As part of (2) I tried to morph it to be in line with the way (1) is explained. Notice that I've removed all of the base64 cruft: this is intentional as these can quickly become out of date and the guide is structured to teach someone to fish rather than giving them a base64-encoded fish.
Closes #469.
For Reviewers
I recommend viewing the entire Markdown file in this PR as-is and comparing it to the existing page rather than going line-by-line as the changes are significant and hard to parse out of a diff.