feat: add new file APIs for non-zero realm/shard (#937)

Signed-off-by: Rob Walworth <robert.walworth@swirldslabs.com>

Author: rwalworth

src/sdk/main/include/Client.h

@@ -70,9 +70,13 @@ class Client
    *
    * @param mirrorNetwork The mirror node network from which to grab the address book and initialize the Client's
    *                      consensus network.
-   * @return A Client with the input mirror network and the corresponding address book consensus network
+   * @param realm         The realm of the network from which to grab the address book.
+   * @param shard         The shard of the network from which to grab the address book.
+   * @return A Client with the input mirror network and the corresponding address book consensus network.
    */
-  [[nodiscard]] static Client forMirrorNetwork(const std::vector<std::string>& mirrorNetwork);
+  [[nodiscard]] static Client forMirrorNetwork(const std::vector<std::string>& mirrorNetwork,
+                                               int64_t realm = 0LL,
+                                               int64_t shard = 0LL);
 
   /**
    * Construct a Client by a name. The name must be one of "mainnet", "testnet", or "previewnet", otherwise this will

src/sdk/main/include/FileId.h

@@ -3,6 +3,7 @@
 #define HIERO_SDK_CPP_FILE_ID_H_
 
 #include <cstddef>
+#include <cstdint>
 #include <memory>
 #include <string>
 #include <string_view>
@@ -43,6 +44,33 @@ class FileId
    */
   [[maybe_unused]] static const FileId EXCHANGE_RATES;
 
+  /**
+   * Get the address book file ID for a particular realm and/or shard.
+   *
+   * @param realm The realm from which to get the address book file.
+   * @param shard The shard from which to get the address book file.
+   * @return The ID of the address book file from the input realm and/or shard.
+   */
+  [[nodiscard]] static FileId getAddressBookFileIdFor(int64_t realm, int64_t shard);
+
+  /**
+   * Get the fee schedule file ID for a particular realm and/or shard.
+   *
+   * @param realm The realm from which to get the fee schedule file.
+   * @param shard The shard from which to get the fee schedule file.
+   * @return The ID of the fee schedule file from the input realm and/or shard.
+   */
+  [[nodiscard]] static FileId getFeeScheduleFileIdFor(int64_t realm, int64_t shard);
+
+  /**
+   * Get the exchange rates file ID for a particular realm and/or shard.
+   *
+   * @param realm The realm from which to get the exchange rates file.
+   * @param shard The shard from which to get the exchange rates file.
+   * @return The ID of the exchange rates file from the input realm and/or shard.
+   */
+  [[nodiscard]] static FileId getExchangeRatesFileIdFor(int64_t realm, int64_t shard);
+
   /**
    * Construct with a file number.
    *

src/sdk/main/src/Client.cc

@@ -157,13 +157,14 @@ Client Client::forNetwork(const std::unordered_map<std::string, AccountId>& netw
 }
 
 //-----
-Client Client::forMirrorNetwork(const std::vector<std::string>& mirrorNetwork)
+Client Client::forMirrorNetwork(const std::vector<std::string>& mirrorNetwork, int64_t realm, int64_t shard)
 {
   Client client;
   client.setMirrorNetwork(mirrorNetwork);
   client.mImpl->mNetwork =
     std::make_shared<internal::Network>(internal::Network::forNetwork(internal::Network::getNetworkFromAddressBook(
-      AddressBookQuery().setFileId(FileId::ADDRESS_BOOK).execute(client), internal::BaseNodeAddress::PORT_NODE_PLAIN)));
+      AddressBookQuery().setFileId(FileId::getAddressBookFileIdFor(realm, shard)).execute(client),
+      internal::BaseNodeAddress::PORT_NODE_PLAIN)));
 
   return client;
 }

src/sdk/main/src/FileId.cc

@@ -10,14 +10,42 @@
 
 namespace Hiero
 {
+namespace
+{
+// The entity number of the address book file.
+const uint64_t ADDRESS_BOOK_ENTITY_NUM = 102ULL;
+// The entity number of the fee schedule file.
+const uint64_t FEE_SCHEDULE_ENTITY_NUM = 111ULL;
+// The entity number of the exchange rates file.
+const uint64_t EXCHANGE_RATES_ENTITY_NUM = 112ULL;
+}
+
+//-----
+const FileId FileId::ADDRESS_BOOK = FileId(ADDRESS_BOOK_ENTITY_NUM);
+
 //-----
-const FileId FileId::ADDRESS_BOOK = FileId(0ULL, 0ULL, 102ULL);
+const FileId FileId::FEE_SCHEDULE = FileId(FEE_SCHEDULE_ENTITY_NUM);
 
 //-----
-const FileId FileId::FEE_SCHEDULE = FileId(0ULL, 0ULL, 111ULL);
+const FileId FileId::EXCHANGE_RATES = FileId(EXCHANGE_RATES_ENTITY_NUM);
 
 //-----
-const FileId FileId::EXCHANGE_RATES = FileId(0ULL, 0ULL, 112ULL);
+FileId FileId::getAddressBookFileIdFor(int64_t realm, int64_t shard)
+{
+  return FileId(shard, realm, ADDRESS_BOOK_ENTITY_NUM);
+}
+
+//-----
+FileId FileId::getFeeScheduleFileIdFor(int64_t realm, int64_t shard)
+{
+  return FileId(shard, realm, FEE_SCHEDULE_ENTITY_NUM);
+}
+
+//-----
+FileId FileId::getExchangeRatesFileIdFor(int64_t realm, int64_t shard)
+{
+  return FileId(shard, realm, EXCHANGE_RATES_ENTITY_NUM);
+}
 
 //-----
 FileId::FileId(uint64_t num)