stellar / stellar-docs

Documentation for Stellar
https://developers.stellar.org
Apache License 2.0
55 stars 124 forks source link

getLedgerEntries: add meaningful coding examples #469

Open tomerweller opened 7 months ago

tomerweller commented 7 months ago

The getLedgerEntries method is pretty powerful, you can retrieve any piece of state from the ledger: accounts, trustlines, offers, data, liquidity pools, contract wasms, contract instances, contract storage, yada yada.

However, there are two challenges associated with that:

  1. building the relevant xdr key for the type of ledger entry you're looking for
  2. parsing the xdr result

However, our coding examples use pre-built keys and don't parse the results. I think that modifying our JS and Python examples in this page to include these can help unlock human potential

### Tasks
- [ ] Add a full list of keys and description for each key
- [ ] Add examples for how to use the keys to retrieve accounts and balances
- [ ] Add examples for how to use the keys to retrieve trustlines
- [ ] Add examples for how to use the keys to retrieve contract wasms
- [ ] Add examples for how to use the keys to retreive contract state / storage
- [ ] Add examples for how to use the keys to retrieve contract instances
leighmcculloch commented 7 months ago

A couple thoughts:

Laboratory – I think building ledger keys would be a perfect feature to add to the Laboratory. In classic stellar days building txs was really the only thing we needed to build, and Laboratory supports that. But with Soroban, building other types is necessary. We could invest UI that auto-generated to build any XDR type also.

Soroban CLI – The stellar-xdr CLI is also now embedded into the soroban-cli, which means it's possible to construct these ledger keys and decode the responses on the command line with the tool that folks already have installed. We should include examples. Here's an example of building an account ledger key:

❯ echo '{"account":{"account_id":"GBCPWDD43RTGBLBYQGELGIAV7QN4O5CHJDWYIQJQGAWLQAXNGNERPSY6"}}' | soroban lab xdr encode --type LedgerKey
AAAAAAAAAABE+wx83GZgrDiBiLMgFfwbx3RHSO2EQTAwLLgC7TNJFw==
kalepail commented 7 months ago

Plus one on adding LedgerKey encoding to the Laboratory!

janewang commented 7 months ago

Where could I find a full list of ledger keys and descriptions?

tomerweller commented 7 months ago

Not sure if ledger entries and keys are well documented anywhere but the ground truth is in the ledger entries xdr spec here: https://github.com/stellar/stellar-xdr/blob/curr/Stellar-ledger-entries.x

More specifically,