@hiero-ledger/sdk 2.70.0

package/src/LedgerId.js

@@ -0,0 +1,134 @@
+// SPDX-License-Identifier: Apache-2.0
+
+import * as hex from "./encoding/hex.js";
+
+/**
+ * Represents the ID of a network.
+ */
+export default class LedgerId {
+    /**
+     * @hideconstructor
+     * @internal
+     * @param {Uint8Array} ledgerId
+     */
+    constructor(ledgerId) {
+        /**
+         * @readonly
+         * @type {Uint8Array}
+         */
+        this._ledgerId = ledgerId;
+
+        Object.freeze(this);
+    }
+
+    /**
+     * @param {string} ledgerId
+     * @returns {LedgerId}
+     */
+    static fromString(ledgerId) {
+        switch (ledgerId) {
+            case NETNAMES[0]:
+            case "0":
+                return LedgerId.MAINNET;
+            case NETNAMES[1]:
+            case "1":
+                return LedgerId.TESTNET;
+            case NETNAMES[2]:
+            case "2":
+                return LedgerId.PREVIEWNET;
+            case NETNAMES[3]:
+            case "3":
+                return LedgerId.LOCAL_NODE;
+            default: {
+                let ledgerIdDecoded = hex.decode(ledgerId);
+                if (ledgerIdDecoded.length == 0 && ledgerId.length != 0) {
+                    throw new Error("Default reached for fromString");
+                } else {
+                    return new LedgerId(ledgerIdDecoded);
+                }
+            }
+        }
+    }
+
+    /**
+     * If the ledger ID is a known value such as `[0]`, `[1]`, `[2]` this method
+     * will instead return "mainnet", "testnet", or "previewnet", otherwise it will
+     * hex encode the bytes.
+     *
+     * @returns {string}
+     */
+    toString() {
+        if (this._ledgerId.length == 1) {
+            switch (this._ledgerId[0]) {
+                case 0:
+                    return NETNAMES[0];
+                case 1:
+                    return NETNAMES[1];
+                case 2:
+                    return NETNAMES[2];
+                case 3:
+                    return NETNAMES[3];
+                default:
+                    return hex.encode(this._ledgerId);
+            }
+        } else {
+            return hex.encode(this._ledgerId);
+        }
+    }
+
+    /**
+     * Using the UTF-8 byte representation of "mainnet", "testnet",
+     * or "previewnet" is NOT supported.
+     *
+     * @param {Uint8Array} bytes
+     * @returns {LedgerId}
+     */
+    static fromBytes(bytes) {
+        return new LedgerId(bytes);
+    }
+
+    /**
+     * @returns {Uint8Array}
+     */
+    toBytes() {
+        return this._ledgerId;
+    }
+
+    /**
+     * @returns {boolean}
+     */
+    isMainnet() {
+        return this.toString() == NETNAMES[0];
+    }
+
+    /**
+     * @returns {boolean}
+     */
+    isTestnet() {
+        return this.toString() == NETNAMES[1];
+    }
+
+    /**
+     * @returns {boolean}
+     */
+    isPreviewnet() {
+        return this.toString() == NETNAMES[2];
+    }
+
+    /**
+     * @returns {boolean}
+     */
+    isLocalNode() {
+        return this.toString() == NETNAMES[3];
+    }
+}
+
+const NETNAMES = ["mainnet", "testnet", "previewnet", "local-node"];
+
+LedgerId.MAINNET = new LedgerId(new Uint8Array([0]));
+
+LedgerId.TESTNET = new LedgerId(new Uint8Array([1]));
+
+LedgerId.PREVIEWNET = new LedgerId(new Uint8Array([2]));
+
+LedgerId.LOCAL_NODE = new LedgerId(new Uint8Array([3]));

package/src/LocalProvider.js

@@ -0,0 +1,165 @@
+// SPDX-License-Identifier: Apache-2.0
+
+import Client from "./client/NodeClient.js";
+import AccountBalanceQuery from "./account/AccountBalanceQuery.js";
+import AccountInfoQuery from "./account/AccountInfoQuery.js";
+import AccountRecordsQuery from "./account/AccountRecordsQuery.js";
+import TransactionReceiptQuery from "./transaction/TransactionReceiptQuery.js";
+
+/**
+ * @typedef {import("./Provider.js").Provider} Provider
+ * @typedef {import("./LedgerId.js").default} LedgerId
+ * @typedef {import("./Key.js").default} Key
+ * @typedef {import("./transaction/Transaction.js").default} Transaction
+ * @typedef {import("./transaction/TransactionId.js").default} TransactionId
+ * @typedef {import("./transaction/TransactionResponse.js").default} TransactionResponse
+ * @typedef {import("./transaction/TransactionReceipt.js").default} TransactionReceipt
+ * @typedef {import("./transaction/TransactionRecord.js").default} TransactionRecord
+ * @typedef {import("./account/AccountId.js").default} AccountId
+ * @typedef {import("./account/AccountBalance.js").default} AccountBalance
+ * @typedef {import("./account/AccountInfo.js").default} AccountInfo
+ * @typedef {import("./logger/Logger.js").default} Logger
+ */
+
+/**
+ * @template {any} O
+ * @typedef {import("./query/Query.js").default<O>} Query<O>
+ */
+
+/**
+ * @template RequestT
+ * @template ResponseT
+ * @template OutputT
+ * @typedef {import("./Executable.js").default<RequestT, ResponseT, OutputT>} Executable<RequestT, ResponseT, OutputT>
+ */
+
+/**
+ * @implements {Provider}
+ */
+export default class LocalProvider {
+    /**
+     * @param {object} props
+     * @param {Client} [props.client]
+     */
+    constructor(props = {}) {
+        if (props != null && props.client != null) {
+            this._client = props.client;
+            return;
+        }
+
+        if (process.env.HEDERA_NETWORK == null) {
+            throw new Error(
+                "LocalProvider requires the `HEDERA_NETWORK` environment variable to be set",
+            );
+        }
+
+        this._client = Client.forName(process.env.HEDERA_NETWORK);
+    }
+
+    /**
+     * @param {Client} client
+     * @returns {LocalProvider}
+     */
+    static fromClient(client) {
+        return new LocalProvider({ client });
+    }
+
+    /**
+     * @returns {LedgerId?}
+     */
+    getLedgerId() {
+        return this._client.ledgerId;
+    }
+
+    /**
+     * @returns {{[key: string]: (string | AccountId)}}
+     */
+    getNetwork() {
+        return this._client.network;
+    }
+
+    /**
+     * @returns {string[]}
+     */
+    getMirrorNetwork() {
+        return this._client.mirrorNetwork;
+    }
+
+    /**
+     * @param {AccountId | string} accountId
+     * @returns {Promise<AccountBalance>}
+     */
+    getAccountBalance(accountId) {
+        return new AccountBalanceQuery()
+            .setAccountId(accountId)
+            .execute(this._client);
+    }
+
+    /**
+     * @param {AccountId | string} accountId
+     * @returns {Promise<AccountInfo>}
+     */
+    getAccountInfo(accountId) {
+        return new AccountInfoQuery()
+            .setAccountId(accountId)
+            .execute(this._client);
+    }
+
+    /**
+     * @param {AccountId | string} accountId
+     * @returns {Promise<TransactionRecord[]>}
+     */
+    getAccountRecords(accountId) {
+        return new AccountRecordsQuery()
+            .setAccountId(accountId)
+            .execute(this._client);
+    }
+
+    /**
+     * @param {TransactionId | string} transactionId
+     * @returns {Promise<TransactionReceipt>}
+     */
+    getTransactionReceipt(transactionId) {
+        return new TransactionReceiptQuery()
+            .setTransactionId(transactionId)
+            .execute(this._client);
+    }
+
+    /**
+     * @param {TransactionResponse} response
+     * @returns {Promise<TransactionReceipt>}
+     */
+    waitForReceipt(response) {
+        return new TransactionReceiptQuery()
+            .setNodeAccountIds([response.nodeId])
+            .setTransactionId(response.transactionId)
+            .execute(this._client);
+    }
+
+    /**
+     * @template RequestT
+     * @template ResponseT
+     * @template OutputT
+     * @param {Executable<RequestT, ResponseT, OutputT>} request
+     * @returns {Promise<OutputT>}
+     */
+    call(request) {
+        return request.execute(this._client);
+    }
+
+    /**
+     * @returns {void}
+     */
+    close() {
+        this._client.close();
+    }
+
+    /**
+     * Set logger
+     *
+     * @param {Logger} logger
+     */
+    setLogger(logger) {
+        this._client.setLogger(logger);
+    }
+}

package/src/ManagedNode.js

@@ -0,0 +1,269 @@
+// SPDX-License-Identifier: Apache-2.0
+
+import ManagedNodeAddress from "./ManagedNodeAddress.js";
+
+/**
+ * @typedef {import("./account/AccountId.js").default} AccountId
+ * @typedef {import("./channel/Channel.js").default} Channel
+ * @typedef {import("./channel/MirrorChannel.js").default} MirrorChannel
+ * @typedef {import("./address_book/NodeAddress.js").default} NodeAddress
+ */
+
+/**
+ * @template {Channel | MirrorChannel} ChannelT
+ * @typedef {object} NewNode
+ * @property {string | ManagedNodeAddress} address
+ * @property {(address: string, cert?: string) => ChannelT} channelInitFunction
+ */
+
+/**
+ * @template {Channel | MirrorChannel} ChannelT
+ * @typedef {object} CloneNode
+ * @property {ManagedNode<ChannelT>} node
+ * @property {ManagedNodeAddress} address
+ */
+
+/**
+ * @abstract
+ * @template {Channel | MirrorChannel} ChannelT
+ */
+export default class ManagedNode {
+    /**
+     * @param {object} props
+     * @param {NewNode<ChannelT>=} [props.newNode]
+     * @param {CloneNode<ChannelT>=} [props.cloneNode]
+     */
+    constructor(props = {}) {
+        if (props.newNode != null) {
+            this._address =
+                typeof props.newNode.address === "string"
+                    ? ManagedNodeAddress.fromString(props.newNode.address)
+                    : props.newNode.address;
+
+            /** @type {string=} */
+            this._cert = undefined;
+
+            /** @type {ChannelT | null} */
+            this._channel = null;
+
+            /** @type {(address: string, cert?: string) => ChannelT} */
+            this._channelInitFunction = props.newNode.channelInitFunction;
+
+            this._lastUsed = Date.now();
+            this._readmitTime = Date.now();
+            this._useCount = 0;
+            this._badGrpcStatusCount = 0;
+            this._minBackoff = 8000;
+            this._maxBackoff = 1000 * 60 * 60;
+            this._currentBackoff = this._minBackoff;
+        } else if (props.cloneNode != null) {
+            /** @type {ManagedNodeAddress} */
+            this._address = props.cloneNode.address;
+
+            /** @type {string=} */
+            this._cert = props.cloneNode.node._cert;
+
+            /** @type {ChannelT | null} */
+            this._channel = props.cloneNode.node._channel;
+
+            /** @type {(address: string, cert?: string) => ChannelT} */
+            this._channelInitFunction =
+                props.cloneNode.node._channelInitFunction;
+
+            /** @type {number} */
+            this._currentBackoff = props.cloneNode.node._currentBackoff;
+
+            /** @type {number} */
+            this._lastUsed = props.cloneNode.node._lastUsed;
+
+            /** @type {number} */
+            this._readmitTime = props.cloneNode.node._readmitTime;
+
+            /** @type {number} */
+            this._useCount = props.cloneNode.node._useCount;
+
+            /** @type {number} */
+            this._badGrpcStatusCount = props.cloneNode.node._badGrpcStatusCount;
+
+            /** @type {number} */
+            this._minBackoff = props.cloneNode.node._minBackoff;
+
+            /** @type {number} */
+            this._maxBackoff = props.cloneNode.node._minBackoff;
+        } else {
+            throw new Error(
+                `failed to create ManagedNode: ${JSON.stringify(props)}`,
+            );
+        }
+    }
+
+    /**
+     * @abstract
+     * @returns {string}
+     */
+    // eslint-disable-next-line jsdoc/require-returns-check
+    getKey() {
+        throw new Error("not implemented");
+    }
+
+    /**
+     * @param {string} ledgerId
+     * @returns {this}
+     */
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    setCert(ledgerId) {
+        return this;
+    }
+
+    /**
+     * @returns {ManagedNodeAddress}
+     */
+    get address() {
+        return this._address;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get attempts() {
+        return this._badGrpcStatusCount;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get minBackoff() {
+        return this._minBackoff;
+    }
+
+    /**
+     * @param {number} minBackoff
+     * @returns {this}
+     */
+    setMinBackoff(minBackoff) {
+        if (this._currentBackoff <= minBackoff) {
+            this._currentBackoff = minBackoff;
+        }
+
+        this._minBackoff = minBackoff;
+        return this;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get maxBackoff() {
+        return this._maxBackoff;
+    }
+
+    /**
+     * @param {number} maxBackoff
+     * @returns {this}
+     */
+    setMaxBackoff(maxBackoff) {
+        if (this._currentBackoff <= maxBackoff) {
+            this._currentBackoff = maxBackoff;
+        }
+
+        this._maxBackoff = maxBackoff;
+        return this;
+    }
+
+    getChannel() {
+        this._useCount++;
+        this.__lastUsed = Date.now();
+
+        if (this._channel != null) {
+            return this._channel;
+        }
+
+        this._channel = this._channelInitFunction(
+            this.address.toString(),
+            this._cert,
+        );
+        return this._channel;
+    }
+
+    /**
+     * Determines if this node is healthy by checking if this node hasn't been
+     * in use for a the required `_currentBackoff` period. Since this looks at `this._lastUsed`
+     * and that value is only set in the `wait()` method, any node that has not
+     * returned a bad gRPC status will always be considered healthy.
+     *
+     * @returns {boolean}
+     */
+    isHealthy() {
+        return this._readmitTime <= Date.now();
+    }
+
+    increaseBackoff() {
+        this._currentBackoff = Math.min(
+            this._currentBackoff * 2,
+            this._maxBackoff,
+        );
+        this._readmitTime = Date.now() + this._currentBackoff;
+    }
+
+    decreaseBackoff() {
+        this._currentBackoff = Math.max(
+            this._currentBackoff / 2,
+            this._minBackoff,
+        );
+    }
+
+    /**
+     * @returns {number}
+     */
+    getRemainingTime() {
+        return this._readmitTime - this._lastUsed;
+    }
+
+    /**
+     * This is only ever called if the node itself is down.
+     * A node returning a transaction with a bad status code does not indicate
+     * the node is down, and hence this method will not be called.
+     *
+     * @returns {Promise<void>}
+     */
+    backoff() {
+        return new Promise((resolve) =>
+            setTimeout(resolve, this.getRemainingTime()),
+        );
+    }
+
+    /**
+     * @param {ManagedNode<*>} node
+     * @returns {number}
+     */
+    compare(node) {
+        let comparison = this.getRemainingTime() - node.getRemainingTime();
+        if (comparison != 0) {
+            return comparison;
+        }
+
+        comparison = this._currentBackoff - node._currentBackoff;
+        if (comparison != 0) {
+            return comparison;
+        }
+
+        comparison = this._badGrpcStatusCount - node._badGrpcStatusCount;
+        if (comparison != 0) {
+            return comparison;
+        }
+
+        comparison = this._useCount - node._useCount;
+        if (comparison != 0) {
+            return comparison;
+        }
+
+        return this._lastUsed - node._lastUsed;
+    }
+
+    close() {
+        if (this._channel != null) {
+            this._channel.close();
+        }
+
+        this._channel = null;
+    }
+}

package/src/ManagedNodeAddress.js

@@ -0,0 +1,101 @@
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * @typedef {import("./account/AccountId.js").default} AccountId
+ * @typedef {import("./channel/Channel.js").default} Channel
+ * @typedef {import("./channel/MirrorChannel.js").default} MirrorChannel
+ * @typedef {import("./address_book/NodeAddress.js").default} NodeAddress
+ */
+
+export const HOST_AND_PORT = /^(\S+):(\d+)$/;
+
+export default class ManagedNodeAddress {
+    /**
+     * @param {object} props
+     * @param {string} [props.address]
+     * @param {string} [props.host]
+     * @param {number | null} [props.port]
+     */
+    constructor(props = {}) {
+        if (props.address != null) {
+            const hostAndPortResult = HOST_AND_PORT.exec(props.address);
+
+            if (hostAndPortResult == null) {
+                throw new Error(`failed to parse address: ${props.address}`);
+            }
+
+            /** @type {string} */
+            this._address = /** @type {string} */ (hostAndPortResult[1]);
+
+            /** @type {number | null} */
+            this._port =
+                hostAndPortResult[2] != null
+                    ? parseInt(/** @type {string }*/ (hostAndPortResult[2]))
+                    : null;
+        } else if (props.host != null && props.port != null) {
+            /** @type {string} */
+            this._address = props.host;
+
+            /** @type {number | null} */
+            this._port = props.port;
+        } else {
+            throw new Error(
+                `failed to create a managed node address: ${JSON.stringify(
+                    props,
+                )}`,
+            );
+        }
+
+        Object.freeze(this);
+    }
+
+    /**
+     * @param {string} address
+     * @returns {ManagedNodeAddress};
+     */
+    static fromString(address) {
+        return new ManagedNodeAddress({ address });
+    }
+
+    toInsecure() {
+        let port = this.port === 50212 ? 50211 : this.port;
+        return new ManagedNodeAddress({ host: this.address, port });
+    }
+
+    toSecure() {
+        let port = this.port === 50211 ? 50212 : this.port;
+        return new ManagedNodeAddress({ host: this.address, port });
+    }
+
+    /**
+     * @returns {string}
+     */
+    get address() {
+        return this._address;
+    }
+
+    /**
+     * @returns {number | null}
+     */
+    get port() {
+        return this._port;
+    }
+
+    /**
+     * @returns {boolean}
+     */
+    isTransportSecurity() {
+        return this._port == 50212 || this._port == 443;
+    }
+
+    /**
+     * @returns {string}
+     */
+    toString() {
+        if (this.port == null) {
+            return this.address;
+        } else {
+            return `${this.address}:${this.port}`;
+        }
+    }
+}

package/src/MaxAttemptsOrTimeoutError.js

@@ -0,0 +1,42 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * @typedef {object} MaxAttemptsOrTimeoutErrorJSON
+ * @property {string} message
+ * @property {string} nodeAccountId
+ *
+ */
+
+export default class MaxAttemptsOrTimeoutError extends Error {
+    /**
+     * @param {string} message
+     * @param {string} nodeAccountId
+     */
+    constructor(message, nodeAccountId) {
+        // Call the Error constructor with the message
+        super(message);
+
+        // Assign the nodeAccountId as a custom property
+        this.nodeAccountId = nodeAccountId;
+    }
+
+    toJSON() {
+        return {
+            message: this.message,
+            nodeAccountId: this.nodeAccountId,
+        };
+    }
+
+    /**
+     * @returns {string}
+     */
+    toString() {
+        return JSON.stringify(this.toJSON());
+    }
+
+    /**
+     * @returns {MaxAttemptsOrTimeoutErrorJSON}
+     */
+    valueOf() {
+        return this.toJSON();
+    }
+}