soroban-rpc: Replace getLedgerEntry with getLedgerEntries

CHANGELOG.md

@@ -4,6 +4,9 @@
 
 A breaking change should be clearly marked in this log.
 
+#### Unreleased
+* **Breaking**: replaced `getLedgerEntry` with `getLedgerEntries`. `getLedgerEntry` is deprecated and should no longer be used.
+
 #### 0.6.1
 * removed reference to deprecated usage of gulp in docs build step [#80](https://github.com/stellar/js-soroban-client/pull/80)
 

docs/reference/readme.md

@@ -31,7 +31,7 @@ Methods return a [promise](https://developer.mozilla.org/en-US/docs/Web/JavaScri
 The transaction endpoints will return some fields in raw [XDR](https://developers.stellar.org/api/introduction/xdr/)
 form. You can convert this XDR to JSON using the `.fromXDR()` method.
 
-An example of using the `getLedgerEntry` method to read the current ledger entry for an account and print the XDR field as JSON:
+An example of using the `getLedgerEntries` method to read the current ledger entry for an account and print the XDR field as JSON:
 
 ```javascript
 // Construct the LedgerKey we want to look up
@@ -42,8 +42,9 @@ const key = SorobanClient.xdr.LedgerKey.account(
 );
 
 // Fetch the current LedgerKeyData from the server.
-server.getLedgerEntry(key).then(function (response) {
-  const parsed = SorobanClient.xdr.LedgerEntryData.fromXDR(response.xdr, 'base64');
+server.getLedgerEntries([key]).then(function (response) {
+  const ledgerEntry = response.entries[0];
+  const parsed = SorobanClient.xdr.LedgerEntryData.fromXDR(ledgerEntry.xdr, 'base64');
   console.log( JSON.stringify(parsed) );
 });
 ```

src/server.ts

@@ -82,17 +82,26 @@ export class Server {
    * @returns {Promise<Account>} Returns a promise to the {@link Account} object with populated sequence number.
    */
   public async getAccount(address: string): Promise<Account> {
-    const { xdr: ledgerEntryData } = await jsonrpc.post<SorobanRpc.GetLedgerEntryResponse>(
+    const ledgerKey = xdr.LedgerKey.account(
+      new xdr.LedgerKeyAccount({
+        accountId: xdr.PublicKey.publicKeyTypeEd25519(
+          StrKey.decodeEd25519PublicKey(address),
+        ),
+      }),
+    ).toXDR("base64");
+    const data: SorobanRpc.GetLedgerEntriesResponse = await jsonrpc.post(
       this.serverURL.toString(),
-      "getLedgerEntry",
-      xdr.LedgerKey.account(
-        new xdr.LedgerKeyAccount({
-          accountId: xdr.PublicKey.publicKeyTypeEd25519(
-            StrKey.decodeEd25519PublicKey(address),
-          ),
-        }),
-      ).toXDR("base64"),
+      "getLedgerEntries",
+      [ledgerKey],
     );
+    const ledgerEntries = data.entries;
+    if (ledgerEntries.length === 0) {
+      return Promise.reject({
+        code: 404,
+        message: "Ledger entry not found. Key: " + ledgerKey,
+      });
+    }
+    const ledgerEntryData = ledgerEntries[0].xdr;
     const accountEntry = xdr.LedgerEntryData.fromXDR(
       ledgerEntryData,
       "base64",
@@ -135,29 +144,37 @@ export class Server {
    *
    * @param {string} contractId - The contract ID containing the data to load. Encoded as a hex string.
    * @param {xdr.ScVal} key - The key of the contract data to load.
-   * @returns {Promise<SorobanRpc.GetLedgerEntryResponse>} Returns a promise to the {@link SorobanRpc.GetLedgerEntryResponse} object with the current value.
+   * @returns {Promise<SorobanRpc.LedgerEntryResult>} Returns a promise to the {@link SorobanRpc.LedgerEntryResult} object with the current value.
    */
   public async getContractData(
     contractId: string,
     key: xdr.ScVal,
-  ): Promise<SorobanRpc.GetLedgerEntryResponse> {
-    return await jsonrpc.post(
+  ): Promise<SorobanRpc.LedgerEntryResult> {
+    const contractKey = xdr.LedgerKey.contractData(
+      new xdr.LedgerKeyContractData({
+        contractId: Buffer.from(contractId, "hex"),
+        key,
+      }),
+    ).toXDR("base64");
+    const getLedgerEntriesResponse: SorobanRpc.GetLedgerEntriesResponse = await jsonrpc.post(
       this.serverURL.toString(),
-      "getLedgerEntry",
-      xdr.LedgerKey.contractData(
-        new xdr.LedgerKeyContractData({
-          contractId: Buffer.from(contractId, "hex"),
-          key,
-        }),
-      ).toXDR("base64"),
+      "getLedgerEntries",
+      [contractKey],
     );
+    if (getLedgerEntriesResponse.entries.length === 0) {
+      return Promise.reject({
+        code: 404,
+        message: "Ledger entry not found. Key: " + contractKey,
+      });
+    }
+    return getLedgerEntriesResponse.entries[0];
   }
 
   /**
    * Reads the current value of ledger entries directly.
    *
-   * Allows you to directly inspect the current state of a contract,
-   * contract's code, or any other ledger entry. This is a backup way to access
+   * Allows you to directly inspect the current state of contracts,
+   * contract's code, or any other ledger entries. This is a backup way to access
    * your contract data which may not be available via events or
    * simulateTransaction.
    *
@@ -169,22 +186,24 @@ export class Server {
    *   contractId: Buffer.from(contractId, "hex"),
    *   key: xdr.ScVal.scvSymbol("counter"),
    * }));
-   * server.getLedgerEntry(key).then(data => {
-   *   console.log("value:", data.xdr);
-   *   console.log("lastModified:", data.lastModifiedLedgerSeq);
-   *   console.log("latestLedger:", data.latestLedger);
+   * server.getLedgerEntries([key]).then(response => {
+   *   const ledgerData = response.entries[0];
+   *   console.log("key:", ledgerData.key);
+   *   console.log("value:", ledgerData.xdr);
+   *   console.log("lastModified:", ledgerData.lastModifiedLedgerSeq);
+   *   console.log("latestLedger:", response.latestLedger);
    * });
    *
    * @param {xdr.ScVal} key - The key of the contract data to load.
-   * @returns {Promise<SorobanRpc.GetLedgerEntryResponse>} Returns a promise to the {@link SorobanRpc.GetLedgerEntryResponse} object with the current value.
+   * @returns {Promise<SorobanRpc.GetLedgerEntriesResponse>} Returns a promise to the {@link SorobanRpc.GetLedgerEntriesResponse} object with the current value.
    */
-  public async getLedgerEntry(
-    key: xdr.LedgerKey,
-  ): Promise<SorobanRpc.GetLedgerEntryResponse> {
+  public async getLedgerEntries(
+    keys: xdr.LedgerKey[],
+  ): Promise<SorobanRpc.GetLedgerEntriesResponse> {
     return await jsonrpc.post(
       this.serverURL.toString(),
-      "getLedgerEntry",
-      key.toXDR("base64"),
+      "getLedgerEntries",
+      keys.map((k) => k.toXDR("base64")),
     );
   }
 

src/soroban_rpc.ts

@@ -24,13 +24,18 @@ export namespace SorobanRpc {
     status: "healthy";
   }
 
-  /* Response for jsonrpc method `getLedgerEntry`
-   */
-  export interface GetLedgerEntryResponse {
+  export interface LedgerEntryResult {
+    key: string;
     // xdr is a base-64 encoded {@link xdr.LedgerEntryData}
     xdr: string;
     lastModifiedLedgerSeq?: number;
-    latestLedger?: number;
+  }
+
+  /* Response for jsonrpc method `getLedgerEntries`
+   */
+  export interface GetLedgerEntriesResponse {
+    entries: LedgerEntryResult[];
+    latestLedger: number;
   }
 
   /* Response for jsonrpc method `getNetwork`

test/unit/server/get_account_test.js

@@ -24,20 +24,26 @@ describe("Server#getAccount", function () {
       .withArgs(serverUrl, {
         jsonrpc: "2.0",
         id: 1,
-        method: "getLedgerEntry",
+        method: "getLedgerEntries",
         params: [
-          xdr.LedgerKey.account(
-            new xdr.LedgerKeyAccount({
-              accountId,
-            })
-          ).toXDR("base64"),
+          [
+            xdr.LedgerKey.account(
+              new xdr.LedgerKeyAccount({
+                accountId,
+              })
+            ).toXDR("base64"),
+          ],
         ],
       })
       .returns(
         Promise.resolve({
           data: {
             result: {
-              xdr: "AAAAAAAAAABzdv3ojkzWHMD7KUoXhrPx0GH18vHKV0ZfqpMiEblG1g3gtpoE608YAAAAAAAAAAEAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAABAAAAAAAAAAAAAAAAAAAAAAAAAAIAAAAAAAAAAAAAAAAAAAADAAAAAAAAAAQAAAAAY9D8iA",
+              entries: [
+                {
+                  xdr: "AAAAAAAAAABzdv3ojkzWHMD7KUoXhrPx0GH18vHKV0ZfqpMiEblG1g3gtpoE608YAAAAAAAAAAEAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAABAAAAAAAAAAAAAAAAAAAAAAAAAAIAAAAAAAAAAAAAAAAAAAADAAAAAAAAAAQAAAAAY9D8iA",
+                },
+              ],
             },
           },
         })

test/unit/server/get_contract_data_test.js

@@ -29,17 +29,27 @@ describe("Server#getContractData", function () {
       .withArgs(serverUrl, {
         jsonrpc: "2.0",
         id: 1,
-        method: "getLedgerEntry",
+        method: "getLedgerEntries",
         params: [
-          xdr.LedgerKey.contractData(
-            new xdr.LedgerKeyContractData({
-              contractId: Buffer.from(address, "hex"),
-              key,
-            })
-          ).toXDR("base64"),
+          [
+            xdr.LedgerKey.contractData(
+              new xdr.LedgerKeyContractData({
+                contractId: Buffer.from(address, "hex"),
+                key,
+              })
+            ).toXDR("base64"),
+          ],
         ],
       })
-      .returns(Promise.resolve({ data: { result } }));
+      .returns(
+        Promise.resolve({
+          data: {
+            result: {
+              entries: [result],
+            },
+          },
+        })
+      );
 
     this.server
       .getContractData(address, key)
@@ -58,17 +68,19 @@ describe("Server#getContractData", function () {
       .withArgs(serverUrl, {
         jsonrpc: "2.0",
         id: 1,
-        method: "getLedgerEntry",
+        method: "getLedgerEntries",
         params: [
-          xdr.LedgerKey.contractData(
-            new xdr.LedgerKeyContractData({
-              contractId: Buffer.from(address, "hex"),
-              key,
-            })
-          ).toXDR("base64"),
+          [
+            xdr.LedgerKey.contractData(
+              new xdr.LedgerKeyContractData({
+                contractId: Buffer.from(address, "hex"),
+                key,
+              })
+            ).toXDR("base64"),
+          ],
         ],
       })
-      .returns(Promise.resolve({ data: { error: { code: 404 } } }));
+      .returns(Promise.resolve({ data: { result: { entries: [] } } }));
 
     this.server
       .getContractData(address, key)

test/unit/server/request_airdrop_test.js

@@ -117,22 +117,30 @@ describe("Server#requestAirdrop", function () {
       .withArgs(serverUrl, {
         jsonrpc: "2.0",
         id: 1,
-        method: "getLedgerEntry",
+        method: "getLedgerEntries",
         params: [
-          xdr.LedgerKey.account(
-            new xdr.LedgerKeyAccount({
-              accountId: xdr.PublicKey.publicKeyTypeEd25519(
-                StrKey.decodeEd25519PublicKey(accountId)
-              ),
-            })
-          ).toXDR("base64"),
+          [
+            xdr.LedgerKey.account(
+              new xdr.LedgerKeyAccount({
+                accountId: xdr.PublicKey.publicKeyTypeEd25519(
+                  StrKey.decodeEd25519PublicKey(accountId)
+                ),
+              })
+            ).toXDR("base64"),
+          ],
         ],
       })
       .returns(
         Promise.resolve({
           data: {
             result: {
-              xdr: accountLedgerEntryData(accountId, "1234").toXDR("base64"),
+              entries: [
+                {
+                  xdr: accountLedgerEntryData(accountId, "1234").toXDR(
+                    "base64"
+                  ),
+                },
+              ],
             },
           },
         })