@hiero-ledger/sdk 2.70.0 → 2.71.0

package/src/client/NativeClient.js

@@ -5,40 +5,13 @@ import NativeChannel from "../channel/NativeChannel.js";
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 import AccountId from "../account/AccountId.js";
 import LedgerId from "../LedgerId.js";
-import {
-    MAINNET,
-    NATIVE_TESTNET,
-    NATIVE_PREVIEWNET,
-} from "../constants/ClientConstants.js";
+import { MirrorNetwork, WebNetwork } from "../constants/ClientConstants.js";
+import AddressBookQuery from "../network/AddressBookQueryWeb.js";
+import FileId from "../file/FileId.js";
 
 /**
  * @typedef {import("./Client.js").ClientConfiguration} ClientConfiguration
  */
-export const Network = {
-    /**
-     * @param {string} name
-     * @returns {{[key: string]: (string | AccountId)}}
-     */
-    fromName(name) {
-        switch (name) {
-            case "mainnet":
-                return Network.MAINNET;
-
-            case "testnet":
-                return Network.TESTNET;
-
-            case "previewnet":
-                return Network.PREVIEWNET;
-
-            default:
-                throw new Error(`unknown network name: ${name}`);
-        }
-    },
-
-    MAINNET: MAINNET,
-    TESTNET: NATIVE_TESTNET,
-    PREVIEWNET: NATIVE_PREVIEWNET,
-};
 
 /**
  * @augments {Client<NativeChannel, *>}
@@ -54,18 +27,21 @@ export default class NativeClient extends Client {
             if (typeof props.network === "string") {
                 switch (props.network) {
                     case "mainnet":
-                        this.setNetwork(Network.MAINNET);
+                        this.setNetwork(WebNetwork.MAINNET);
                         this.setLedgerId(LedgerId.MAINNET);
+                        this.setMirrorNetwork(MirrorNetwork.MAINNET);
                         break;
 
                     case "testnet":
-                        this.setNetwork(Network.TESTNET);
+                        this.setNetwork(WebNetwork.TESTNET);
                         this.setLedgerId(LedgerId.TESTNET);
+                        this.setMirrorNetwork(MirrorNetwork.TESTNET);
                         break;
 
                     case "previewnet":
-                        this.setNetwork(Network.PREVIEWNET);
+                        this.setNetwork(WebNetwork.PREVIEWNET);
                         this.setLedgerId(LedgerId.PREVIEWNET);
+                        this.setMirrorNetwork(MirrorNetwork.PREVIEWNET);
                         break;
 
                     default:
@@ -121,7 +97,6 @@ export default class NativeClient extends Client {
     static forNetwork(network) {
         return new NativeClient({
             network,
-            scheduleNetworkUpdate: false,
         });
     }
 
@@ -130,7 +105,7 @@ export default class NativeClient extends Client {
      * @returns {NativeClient}
      */
     static forName(network) {
-        return new NativeClient({ network, scheduleNetworkUpdate: false });
+        return new NativeClient({ network });
     }
 
     /**
@@ -141,7 +116,6 @@ export default class NativeClient extends Client {
     static forMainnet() {
         return new NativeClient({
             network: "mainnet",
-            scheduleNetworkUpdate: false,
         });
     }
 
@@ -153,7 +127,6 @@ export default class NativeClient extends Client {
     static forTestnet() {
         return new NativeClient({
             network: "testnet",
-            scheduleNetworkUpdate: false,
         });
     }
 
@@ -165,10 +138,76 @@ export default class NativeClient extends Client {
     static forPreviewnet() {
         return new NativeClient({
             network: "previewnet",
-            scheduleNetworkUpdate: false,
         });
     }
 
+    /**
+     * Construct a Hedera client pre-configured for Mainnet access with network update.
+     *
+     * @returns {Promise<NativeClient>}
+     */
+    static async forMainnetAsync() {
+        return new NativeClient({
+            network: "mainnet",
+        }).updateNetwork();
+    }
+
+    /**
+     * Construct a Hedera client pre-configured for Testnet access with network update.
+     *
+     * @returns {Promise<NativeClient>}
+     */
+    static async forTestnetAsync() {
+        return new NativeClient({
+            network: "testnet",
+        }).updateNetwork();
+    }
+
+    /**
+     * Construct a Hedera client pre-configured for Previewnet access with network update.
+     *
+     * @returns {Promise<NativeClient>}
+     */
+    static async forPreviewnetAsync() {
+        return new NativeClient({
+            network: "previewnet",
+        }).updateNetwork();
+    }
+
+    /**
+     * Construct a client for a specific network with optional network update.
+     * Updates network only if the network is not "local-node".
+     *
+     * @param {string} network
+     * @returns {Promise<NativeClient>}
+     */
+    static async forNameAsync(network) {
+        const client = new NativeClient({ network });
+
+        if (network !== "local-node") {
+            await client.updateNetwork();
+        }
+
+        return client;
+    }
+
+    /**
+     * Construct a client configured to use mirror nodes.
+     * This will query the address book to get the network nodes.
+     *
+     * @param {string[] | string} mirrorNetwork
+     * @returns {Promise<NativeClient>}
+     */
+    static async forMirrorNetwork(mirrorNetwork) {
+        const client = new NativeClient({
+            mirrorNetwork,
+        });
+
+        await client.updateNetwork();
+
+        return client;
+    }
+
     /**
      * @param {{[key: string]: (string | AccountId)} | string} network
      * @returns {void}
@@ -177,13 +216,13 @@ export default class NativeClient extends Client {
         if (typeof network === "string") {
             switch (network) {
                 case "previewnet":
-                    this._network.setNetwork(Network.PREVIEWNET);
+                    this._network.setNetwork(WebNetwork.PREVIEWNET);
                     break;
                 case "testnet":
-                    this._network.setNetwork(Network.TESTNET);
+                    this._network.setNetwork(WebNetwork.TESTNET);
                     break;
                 case "mainnet":
-                    this._network.setNetwork(Network.MAINNET);
+                    this._network.setNetwork(WebNetwork.MAINNET);
             }
         } else {
             this._network.setNetwork(network);
@@ -192,11 +231,75 @@ export default class NativeClient extends Client {
 
     /**
      * @param {string[] | string} mirrorNetwork
-     * @returns {void}
+     * @returns {this}
      */
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
     setMirrorNetwork(mirrorNetwork) {
-        // Do nothing as this is not currently supported
+        if (typeof mirrorNetwork === "string") {
+            switch (mirrorNetwork) {
+                case "local-node":
+                    this._mirrorNetwork.setNetwork(MirrorNetwork.LOCAL_NODE);
+                    break;
+                case "previewnet":
+                    this._mirrorNetwork.setNetwork(MirrorNetwork.PREVIEWNET);
+                    break;
+                case "testnet":
+                    this._mirrorNetwork.setNetwork(MirrorNetwork.TESTNET);
+                    break;
+                case "mainnet":
+                    this._mirrorNetwork.setNetwork(MirrorNetwork.MAINNET);
+                    break;
+                default:
+                    this._mirrorNetwork.setNetwork([mirrorNetwork]);
+            }
+        } else {
+            this._mirrorNetwork.setNetwork(mirrorNetwork);
+        }
+
+        return this;
+    }
+
+    /**
+     * @override
+     * @returns {Promise<this>}
+     */
+    async updateNetwork() {
+        if (this._isUpdatingNetwork) {
+            return this;
+        }
+
+        this._isUpdatingNetwork = true;
+
+        try {
+            const addressBook = await new AddressBookQuery()
+                .setFileId(
+                    FileId.getAddressBookFileIdFor(this.shard, this.realm),
+                )
+                .execute(this);
+
+            /** @type {Record<string, AccountId>} */
+            const network = {};
+            for (const nodeAddress of addressBook.nodeAddresses) {
+                for (const endpoint of nodeAddress.addresses) {
+                    if (nodeAddress.accountId != null) {
+                        network[endpoint.toString()] = nodeAddress.accountId;
+                    }
+                }
+            }
+
+            this.setNetwork(network);
+        } catch (/** @type {unknown} */ error) {
+            if (this._logger) {
+                const errorMessage =
+                    error instanceof Error ? error.message : String(error);
+                this._logger.trace(
+                    `failed to update client address book: ${errorMessage}`,
+                );
+            }
+        } finally {
+            this._isUpdatingNetwork = false;
+        }
+
+        return this;
     }
 
     /**
@@ -208,11 +311,12 @@ export default class NativeClient extends Client {
     }
 
     /**
-     * @abstract
+     * @override
      * @returns {(address: string) => *}
      */
     _createMirrorNetworkChannel() {
-        // eslint-disable-next-line @typescript-eslint/no-unused-vars
-        return (address) => null;
+        return () => {
+            throw new Error("mirror support is not supported in native");
+        };
     }
 }

package/src/client/NodeClient.js

@@ -165,13 +165,11 @@ export default class NodeClient extends Client {
      * @returns {Promise<NodeClient>}
      */
     static async forMirrorNetwork(mirrorNetwork, shard, realm) {
-        const INITIAL_UPDATE_PERIOD = 10_000;
-
         const client = new NodeClient({
             mirrorNetwork,
             shard,
             realm,
-        }).setNetworkUpdatePeriod(INITIAL_UPDATE_PERIOD);
+        });
 
         await client.updateNetwork();
 
@@ -203,6 +201,61 @@ export default class NodeClient extends Client {
         });
     }
 
+    /**
+     * Construct a Hedera client pre-configured for Mainnet access with network update.
+     *
+     * @param {object} [props]
+     * @param {boolean} [props.scheduleNetworkUpdate]
+     * @returns {Promise<NodeClient>}
+     */
+    static async forMainnetAsync(props = {}) {
+        return new NodeClient({ network: "mainnet", ...props }).updateNetwork();
+    }
+
+    /**
+     * Construct a Hedera client pre-configured for Testnet access with network update.
+     *
+     * @param {object} [props]
+     * @param {boolean} [props.scheduleNetworkUpdate]
+     * @returns {Promise<NodeClient>}
+     */
+    static async forTestnetAsync(props = {}) {
+        return new NodeClient({ network: "testnet", ...props }).updateNetwork();
+    }
+
+    /**
+     * Construct a Hedera client pre-configured for Previewnet access with network update.
+     *
+     * @param {object} [props]
+     * @param {boolean} [props.scheduleNetworkUpdate]
+     * @returns {Promise<NodeClient>}
+     */
+    static async forPreviewnetAsync(props = {}) {
+        return new NodeClient({
+            network: "previewnet",
+            ...props,
+        }).updateNetwork();
+    }
+
+    /**
+     * Construct a client for a specific network with optional network update.
+     * Updates network only if the network is not "local-node".
+     *
+     * @param {string} network
+     * @param {object} [props]
+     * @param {boolean} [props.scheduleNetworkUpdate]
+     * @returns {Promise<NodeClient>}
+     */
+    static async forNameAsync(network, props = {}) {
+        const client = new NodeClient({ network, ...props });
+
+        if (network !== "local-node") {
+            await client.updateNetwork();
+        }
+
+        return client;
+    }
+
     /**
      * @param {{[key: string]: (string | AccountId)} | string} network
      * @returns {void}

package/src/client/WebClient.js

@@ -3,12 +3,7 @@
 import Client from "./Client.js";
 import WebChannel from "../channel/WebChannel.js";
 import LedgerId from "../LedgerId.js";
-import {
-    MAINNET,
-    WEB_TESTNET,
-    WEB_PREVIEWNET,
-    MirrorNetwork,
-} from "../constants/ClientConstants.js";
+import { WebNetwork, MirrorNetwork } from "../constants/ClientConstants.js";
 import AddressBookQuery from "../network/AddressBookQueryWeb.js";
 import FileId from "../file/FileId.js";
 
@@ -17,32 +12,6 @@ import FileId from "../file/FileId.js";
  * @typedef {import("../account/AccountId.js").default} AccountId
  */
 
-export const Network = {
-    /**
-     * @param {string} name
-     * @returns {{[key: string]: (string | AccountId)}}
-     */
-    fromName(name) {
-        switch (name) {
-            case "mainnet":
-                return Network.MAINNET;
-
-            case "testnet":
-                return Network.TESTNET;
-
-            case "previewnet":
-                return Network.PREVIEWNET;
-
-            default:
-                throw new Error(`unknown network name: ${name}`);
-        }
-    },
-
-    MAINNET: MAINNET,
-    TESTNET: WEB_TESTNET,
-    PREVIEWNET: WEB_PREVIEWNET,
-};
-
 /**
  * Represents a client for interacting with the Hedera network over the web.
  * The `WebClient` class extends the base `Client` class and provides methods
@@ -61,19 +30,19 @@ export default class WebClient extends Client {
             if (typeof props.network === "string") {
                 switch (props.network) {
                     case "mainnet":
-                        this.setNetwork(Network.MAINNET);
-                        this.setMirrorNetwork(MirrorNetwork.MAINNET);
+                        this.setNetwork(WebNetwork.MAINNET);
                         this.setLedgerId(LedgerId.MAINNET);
+                        this.setMirrorNetwork(MirrorNetwork.MAINNET);
                         break;
 
                     case "testnet":
-                        this.setNetwork(Network.TESTNET);
+                        this.setNetwork(WebNetwork.TESTNET);
                         this.setLedgerId(LedgerId.TESTNET);
                         this.setMirrorNetwork(MirrorNetwork.TESTNET);
                         break;
 
                     case "previewnet":
-                        this.setNetwork(Network.PREVIEWNET);
+                        this.setNetwork(WebNetwork.PREVIEWNET);
                         this.setLedgerId(LedgerId.PREVIEWNET);
                         this.setMirrorNetwork(MirrorNetwork.PREVIEWNET);
                         break;
@@ -173,6 +142,56 @@ export default class WebClient extends Client {
         });
     }
 
+    /**
+     * Construct a Hedera client pre-configured for Mainnet access with network update.
+     *
+     * @returns {Promise<WebClient>}
+     */
+    static async forMainnetAsync() {
+        return new WebClient({
+            network: "mainnet",
+        }).updateNetwork();
+    }
+
+    /**
+     * Construct a Hedera client pre-configured for Testnet access with network update.
+     *
+     * @returns {Promise<WebClient>}
+     */
+    static async forTestnetAsync() {
+        return new WebClient({
+            network: "testnet",
+        }).updateNetwork();
+    }
+
+    /**
+     * Construct a Hedera client pre-configured for Previewnet access with network update.
+     *
+     * @returns {Promise<WebClient>}
+     */
+    static async forPreviewnetAsync() {
+        return new WebClient({
+            network: "previewnet",
+        }).updateNetwork();
+    }
+
+    /**
+     * Construct a client for a specific network with optional network update.
+     * Updates network only if the network is not "local-node".
+     *
+     * @param {string} network
+     * @returns {Promise<WebClient>}
+     */
+    static async forNameAsync(network) {
+        const client = new WebClient({ network });
+
+        if (network !== "local-node") {
+            await client.updateNetwork();
+        }
+
+        return client;
+    }
+
     /**
      * Construct a client configured to use mirror nodes.
      * This will query the address book to get the network nodes.
@@ -181,9 +200,7 @@ export default class WebClient extends Client {
      * @returns {Promise<WebClient>}
      */
     static async forMirrorNetwork(mirrorNetwork) {
-        const client = new WebClient();
-
-        client.setMirrorNetwork(mirrorNetwork);
+        const client = new WebClient({ mirrorNetwork: mirrorNetwork });
 
         await client.updateNetwork();
 
@@ -198,13 +215,13 @@ export default class WebClient extends Client {
         if (typeof network === "string") {
             switch (network) {
                 case "previewnet":
-                    this._network.setNetwork(Network.PREVIEWNET);
+                    this._network.setNetwork(WebNetwork.PREVIEWNET);
                     break;
                 case "testnet":
-                    this._network.setNetwork(Network.TESTNET);
+                    this._network.setNetwork(WebNetwork.TESTNET);
                     break;
                 case "mainnet":
-                    this._network.setNetwork(Network.MAINNET);
+                    this._network.setNetwork(WebNetwork.MAINNET);
             }
         } else {
             this._network.setNetwork(network);
@@ -242,11 +259,11 @@ export default class WebClient extends Client {
 
     /**
      * @override
-     * @returns {Promise<void>}
+     * @returns {Promise<this>}
      */
     async updateNetwork() {
         if (this._isUpdatingNetwork) {
-            return;
+            return this;
         }
 
         this._isUpdatingNetwork = true;
@@ -280,6 +297,8 @@ export default class WebClient extends Client {
         } finally {
             this._isUpdatingNetwork = false;
         }
+
+        return this;
     }
 
     /**