soroban-rpc: Replace getLedgerEntry with getLedgerEntries

[paulbellamy]

What problem does your feature solve?

Currently, to fetch multiple ledger entries you have to issue multiple getLedgerEntry calls, and you might get them as of multiple ledger states.

What would you like to see?

Replacing:

getLedgerEntry(key: xdr.LedgerKey): {
  xdr: xdr.LedgerEntryData,
  lastModifiedLedgerSeq: number,
  latestLedger: number,
}

with:

getLedgerEntries(keys: xdr.LedgerKey[]): {
  entries: (null | {
    xdr: xdr.LedgerEntryData,
    lastModifiedLedgerSeq: number
  })[],
  latestLedger: number,
}

If any of the keys are not found they should be put as null into the output fields. This is so the client can pair up the requested keys with their results.

We will need to:

• Add the new method, and deprecate the old one in the first release.
• Remove the old method in the next release.
• Update soroban-cli
• Update js-soroban-client
• Update soroban-docs
• Update system-test

What alternatives are there?

[stellarsaur]

Have we considered adding getLedgerEntries, but keeping getLedgerEntry as-is? Saves users the effort to update how they're calling the RPC server, and makes more sense semantically to use getLedgerEntry when you only want to get a single entry.

Just a thought.

[tomerweller]

Instead of modifying getLedgerEntry to work on multiple keys, can we have our json-rpc handler allow for a batch of requests to operate on a consistent state? Consistent state across a batch of requests can potentially have benefits beyond just batching ledger entry reads.

EDIT: I haven't gotten into the details but the json-rpc 2.0 spec does support batching and that's implemented in jrpc2. Batching is also supported by geth.

[paulbellamy]

+1 for batching support in future, but (I'd assume) that's a bigger lift. There's no reason not to do both getLedgerEntries now, and batching later, imo.

Edit: Based on the docs for the jsonrpc server we're using, it supports batching out-of-the-box, but doesn't give any way to guarantee atomicity withing a batch. So, we would need to rework the jsonrpc server, and refactor the database transaction handling to support that.
You can see it currently supports batching with:

$ curl -X POST \
  --header "content-type: application/json" \
  https://rpc-futurenet.stellar.org:443/soroban/rpc \
  -d '[{"jsonrpc": "2.0", "id": 1, "method": "getHealth"}, {"jsonrpc": "2.0", "id": 2, "method": "getHealth"}]' \
  | jq -S .
[
  {
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
      "status": "healthy"
    }
  },
  {
    "id": 2,
    "jsonrpc": "2.0",
    "result": {
      "status": "healthy"
    }
  }
]

[paulbellamy]

Created #28 to work on atomicity within batches

[mollykarcher]

Closing in favor of #28