@hiero-ledger/sdk 2.70.0

package/src/node/ServiceEndpoint.js

@@ -0,0 +1,145 @@
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * @namespace proto
+ * @typedef {import("@hashgraph/proto").proto.IServiceEndpoint} IServiceEndpoint
+ */
+
+export default class ServiceEndpoint {
+    /**
+     * @param {object} [props]
+     * @param {?Uint8Array} [props.ipAddressV4]
+     * @param {?number} [props.port]
+     * @param {?string} [props.domainName]
+     */
+    constructor(props) {
+        /**
+         * @type {?Uint8Array}
+         * @description The 4-byte IPv4 address of the endpoint
+         * encoded in left to right order
+         * (e.g. 127.0.0.1 has bytes [127, 0, 0, 1]).
+         */
+        this._ipAddressV4 =
+            props?.ipAddressV4 != null ? props.ipAddressV4 : null;
+
+        /**
+         * @type {?number}
+         * @description The port of the service endpoint. It's required.
+         */
+        this._port = props?.port != null ? props.port : null;
+
+        /**
+         * @type {?string}
+         * @description A node domain name. This MUST be the
+         * fully qualified domain(DNS) name of the node. This
+         * value MUST NOT be more than 253 characters.
+         * domain_name and ipAddressV4 are mutually exclusive.
+         * When the `domain_name` field is set, the `ipAddressV4`
+         * field MUST NOT be set. When the `ipAddressV4` field
+         * is set, the `domain_name` field MUST NOT be set.
+         */
+        this._domainName = props?.domainName != null ? props.domainName : null;
+    }
+
+    /**
+     * @param {Uint8Array} ipAddressV4
+     * @description Set 4-byte IPv4 address of the endpoint.
+     * @returns {ServiceEndpoint}
+     *
+     */
+    setIpAddressV4(ipAddressV4) {
+        if (this._domainName != null) {
+            throw new Error(
+                "Cannot set IP address when domain name is already set.",
+            );
+        }
+        this._ipAddressV4 = ipAddressV4;
+        return this;
+    }
+
+    /**
+     * @description Get 4-byte IPv4 address of the endpoint.
+     * @returns {?Uint8Array}
+     *
+     */
+    get getIpAddressV4() {
+        return this._ipAddressV4;
+    }
+
+    /**
+     * @param {number} port
+     * @description Set port of the endpoint.
+     * @returns {ServiceEndpoint}
+     *
+     */
+    setPort(port) {
+        this._port = port;
+        return this;
+    }
+
+    /**
+     * @description Get port of the endpoint.
+     * @returns {?number}
+     *
+     */
+    get getPort() {
+        return this._port;
+    }
+
+    /**
+     * @param {string} domainName
+     * @description Set domain name of the endpoint.
+     * @returns {ServiceEndpoint}
+     *
+     */
+    setDomainName(domainName) {
+        if (this._ipAddressV4 != null) {
+            throw new Error(
+                "Cannot set domain name when IP address is already set.",
+            );
+        }
+        this._domainName = domainName;
+        return this;
+    }
+
+    /**
+     * @description Get domain name of the endpoint.
+     * @returns {?string}
+     *
+     */
+    get getDomainName() {
+        return this._domainName;
+    }
+
+    /**
+     * @internal
+     * @param {IServiceEndpoint} serviceEndpoint
+     * @returns {ServiceEndpoint}
+     */
+    static _fromProtobuf(serviceEndpoint) {
+        return new ServiceEndpoint({
+            ipAddressV4:
+                serviceEndpoint.ipAddressV4 != null
+                    ? serviceEndpoint.ipAddressV4
+                    : undefined,
+            port:
+                serviceEndpoint.port != null ? serviceEndpoint.port : undefined,
+            domainName:
+                serviceEndpoint.domainName != null
+                    ? serviceEndpoint.domainName
+                    : undefined,
+        });
+    }
+
+    /**
+     * @internal
+     * @returns {IServiceEndpoint}
+     */
+    _toProtobuf() {
+        return {
+            ipAddressV4: this._ipAddressV4,
+            port: this._port,
+            domainName: this._domainName,
+        };
+    }
+}

package/src/query/CostQuery.js

@@ -0,0 +1,187 @@
+// SPDX-License-Identifier: Apache-2.0
+
+import TransactionId from "../transaction/TransactionId.js";
+import Hbar from "../Hbar.js";
+import AccountId from "../account/AccountId.js";
+import * as HieroProto from "@hashgraph/proto";
+import QueryBase from "./QueryBase.js";
+
+/**
+ * @typedef {import("../channel/Channel.js").default} Channel
+ * @typedef {import("../Status.js").default} Status
+ * @typedef {import("../Executable.js").ExecutionState} ExecutionState
+ */
+
+/**
+ * @template OutputT
+ * @augments {QueryBase<HieroProto.proto.IQuery, HieroProto.proto.IResponse, Hbar>}
+ */
+export default class CostQuery extends QueryBase {
+    /**
+     * @param {import("./Query.js").default<OutputT>} query
+     */
+    constructor(query) {
+        super();
+
+        this._query = query;
+        this._grpcDeadline = query._grpcDeadline;
+        this._requestTimeout = query._requestTimeout;
+        this._nodeAccountIds = query._nodeAccountIds.clone();
+        this._operator = query._operator;
+
+        /**
+         * @type {HieroProto.proto.IQueryHeader | null}
+         */
+        this._header = null;
+    }
+
+    /**
+     * @returns {TransactionId}
+     */
+    _getTransactionId() {
+        return this._query._getTransactionId();
+    }
+
+    /**
+     * @returns {string}
+     */
+    _getLogId() {
+        return `CostQuery:${this._query._getLogId()}`;
+    }
+
+    /**
+     * @abstract
+     * @protected
+     * @param {import("../client/Client.js").default<*, *>} client
+     * @returns {Promise<void>}
+     */
+    async _beforeExecute(client) {
+        if (client == null) {
+            throw new Error("Cannot do CostQuery without Client");
+        }
+
+        const operator =
+            this._operator != null ? this._operator : client._operator;
+
+        if (operator == null) {
+            throw new Error(
+                "`client` must have an `operator` or an explicit payment transaction must be provided",
+            );
+        }
+
+        if (this._query._nodeAccountIds.isEmpty) {
+            this._query._nodeAccountIds.setList(
+                client._network.getNodeAccountIdsForExecute(),
+            );
+        }
+
+        // operator.accountId
+        const transactionId = TransactionId.generate(operator.accountId);
+        if (this._query.paymentTransactionId == null) {
+            this._query.setPaymentTransactionId(transactionId);
+        }
+
+        const logId = this._getLogId();
+        const nodeId = new AccountId(0);
+        const paymentTransactionId =
+            /** @type {import("../transaction/TransactionId.js").default} */
+            (TransactionId.generate(new AccountId(0)));
+        const paymentAmount = new Hbar(0);
+        if (this._logger) {
+            this._logger.debug(
+                `[${logId}] making a payment transaction for node ${nodeId.toString()} and transaction ID ${paymentTransactionId.toString()} with amount ${paymentAmount.toString()}`,
+            );
+        }
+
+        this._header = {
+            payment: await this._makePaymentTransaction(
+                paymentTransactionId,
+                new AccountId(0),
+                operator,
+                paymentAmount,
+            ),
+            responseType: HieroProto.proto.ResponseType.COST_ANSWER,
+        };
+    }
+
+    /**
+     * @abstract
+     * @internal
+     * @returns {Promise<HieroProto.proto.IQuery>}
+     */
+    _makeRequestAsync() {
+        return Promise.resolve(
+            this._query._onMakeRequest(
+                /** @type {HieroProto.proto.IQueryHeader} */ (this._header),
+            ),
+        );
+    }
+
+    /**
+     * @abstract
+     * @internal
+     * @param {HieroProto.proto.IQuery} request
+     * @param {HieroProto.proto.IResponse} response
+     * @returns {[Status, ExecutionState]}
+     */
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _shouldRetry(request, response) {
+        return this._query._shouldRetry(request, response);
+    }
+
+    /**
+     * @abstract
+     * @internal
+     * @param {HieroProto.proto.IQuery} request
+     * @param {HieroProto.proto.IResponse} response
+     * @param {AccountId} nodeId
+     * @returns {Error}
+     */
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _mapStatusError(request, response, nodeId) {
+        return this._query._mapStatusError(request, response, nodeId);
+    }
+
+    /**
+     * @override
+     * @internal
+     * @param {HieroProto.proto.IResponse} response
+     * @param {AccountId} nodeAccountId
+     * @param {HieroProto.proto.IQuery} request
+     * @returns {Promise<Hbar>}
+     */
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _mapResponse(response, nodeAccountId, request) {
+        const cost = this._query._mapResponseHeader(response).cost;
+        return Promise.resolve(
+            Hbar.fromTinybars(/** @type {Long | number} */ (cost)),
+        );
+    }
+
+    /**
+     * @override
+     * @internal
+     * @param {Channel} channel
+     * @param {HieroProto.proto.IQuery} request
+     * @returns {Promise<HieroProto.proto.IResponse>}
+     */
+    _execute(channel, request) {
+        return this._query._execute(channel, request);
+    }
+
+    /**
+     * @param {HieroProto.proto.Query} request
+     * @returns {Uint8Array}
+     */
+    _requestToBytes(request) {
+        return this._query._requestToBytes(request);
+    }
+
+    /**
+     * @param {HieroProto.proto.Response} response
+     * @returns {Uint8Array}
+     */
+    _responseToBytes(response) {
+        return this._query._responseToBytes(response);
+    }
+}

package/src/query/MirrorNodeContractCallQuery.js

@@ -0,0 +1,49 @@
+import MirrorNodeContractQuery from "./MirrorNodeContractQuery.js";
+import * as hex from "../encoding/hex.js";
+
+/**
+ * @typedef {import("../channel/Channel.js").default} Channel
+ * @typedef {import("../client/Client.js").default<*, *>} Client
+ */
+
+/**
+ A query that simulates a contract function call using the Hedera Mirror Node.
+ * 
+ * This query allows you to execute a read-only smart contract call without submitting a transaction
+ * to the main network. It's useful for querying contract state or executing view/pure functions.
+ * The simulation is performed against the state of the contract at a specific block height.
+ */
+export default class MirrorNodeContractCallQuery extends MirrorNodeContractQuery {
+    /**
+     * @returns {object}
+     */
+    get JSONPayload() {
+        if (this.callData == null) {
+            throw new Error("Call data is required.");
+        }
+
+        return {
+            data: hex.encode(this.callData),
+            from: this.senderEvmAddress,
+            to: this.contractEvmAddress,
+            estimate: false,
+            gasPrice: this.gasPrice?.toString(),
+            gas: this.gasLimit?.toString(),
+            blockNumber: this.blockNumber?.toString(),
+            value: this.value?.toString(),
+        };
+    }
+
+    /**
+     * @param {Client} client
+     * @returns {Promise<string>}
+     */
+    async execute(client) {
+        const mirrorNodeRequest = await this.performMirrorNodeRequest(
+            client,
+            this.JSONPayload,
+        );
+
+        return mirrorNodeRequest.result;
+    }
+}

package/src/query/MirrorNodeContractEstimateQuery.js

@@ -0,0 +1,48 @@
+import MirrorNodeContractQuery from "./MirrorNodeContractQuery.js";
+import * as hex from "../encoding/hex.js";
+/**
+ * @typedef {import("../channel/Channel.js").default} Channel
+ * @typedef {import("../client/Client.js").default<*, *>} Client
+ */
+
+/**
+ * A query that estimates the gas required for a contract function call using the Hedera Mirror Node.
+ *
+ * This query simulates a contract call to estimate the amount of gas that would be required
+ * to execute the same call on the main network. It's useful for determining the appropriate
+ * gas limit before submitting an actual transaction.
+ */
+export default class MirrorNodeContractEstimateQuery extends MirrorNodeContractQuery {
+    /**
+     * @returns {object}
+     */
+    get JSONPayload() {
+        if (this.callData == null) {
+            throw new Error("Call data is required.");
+        }
+
+        return {
+            data: hex.encode(this.callData),
+            from: this.senderEvmAddress,
+            to: this.contractEvmAddress,
+            estimate: true,
+            gasPrice: this.gasPrice?.toString(),
+            gas: this.gasLimit?.toString(),
+            blockNumber: this.blockNumber?.toString(),
+            value: this.value?.toString(),
+        };
+    }
+
+    /**
+     * @param {Client} client
+     * @returns {Promise<number>}
+     */
+    async execute(client) {
+        const mirrorNodeRequest = await this.performMirrorNodeRequest(
+            client,
+            this.JSONPayload,
+        );
+
+        return Number(mirrorNodeRequest.result);
+    }
+}

package/src/query/MirrorNodeContractQuery.js

@@ -0,0 +1,266 @@
+import ContractFunctionParameters from "../contract/ContractFunctionParameters.js";
+
+/**
+ * @typedef {import("../contract/ContractId").default} ContractId
+ * @typedef {import("../account/AccountId").default} AccountId
+ * @typedef {import("../client/Client.js").default<*, *>} Client
+ *
+ */
+
+/**
+ * @typedef {object} MirrorNodeResponse
+ * @property {string} result
+ * @property {string} [error]
+ * @property {string} [gasUsed]
+ * @property {string} [contractAddress]
+ * @property {string} [status]
+ */
+
+/**
+ * MirrorNodeContractQuery returns a result from EVM execution such as cost-free execution of read-only smart contract
+ * queries, gas estimation, and transient simulation of read-write operations.
+ * When working with sender that has ECDSA key with alias, you MUST:
+ * 1. Retrieve the account's EVM address from the Mirror Node API first
+ * 2. Use setSenderEvmAddress() instead of setSender()
+ *
+ * This is because EVM addresses for accounts with ECDSA keys and aliases cannot be automatically
+ * derived and must be fetched from the Mirror Node. Example:
+ *
+ * ```javascript
+ * // For accounts with ECDSA keys and aliases:
+ * const evmAddress = // ... fetch from Mirror Node API ...
+ * query.setSenderEvmAddress(evmAddress);
+ * ```
+ */
+export default class MirrorNodeContractQuery {
+    constructor() {
+        this._contractId = null;
+        this._contractEvmAddress = null;
+        this._sender = null;
+        this._senderEvmAddress = null;
+        this._functionName = null;
+        this._functionParameters = null;
+        this._value = null;
+        this._gasLimit = null;
+        this._gasPrice = null;
+        this._blockNumber = null;
+    }
+
+    /**
+     *
+     * @param {ContractId} contractId
+     * @description Sets the contract instance to call.
+     * @returns {this}
+     */
+    setContractId(contractId) {
+        this._contractId = contractId;
+        return this;
+    }
+
+    /**
+     * @param {AccountId} sender
+     * @description Sets the sender of the transaction simulation.
+     * @returns {this}
+     */
+    setSender(sender) {
+        this._sender = sender;
+        return this;
+    }
+
+    /**
+     * @param {string} sender
+     * @description Set the 20-byte EVM address of the sender.
+     * This method must be used explicitly when working with accounts that have ECDSA keys with aliases,
+     * as their EVM addresses cannot be automatically derived and must be retrieved from the Mirror Node API.
+     * The EVM address can be filled using `accountId.populateAccountEvmAddress(client)`
+     * @returns {this}
+     */
+    setSenderEvmAddress(sender) {
+        this._senderEvmAddress = sender;
+        return this;
+    }
+
+    /**
+     *
+     * @param {string} name
+     * @param {ContractFunctionParameters} functionParameters
+     * @description Sets the function to call, and the parameters to pass to the function
+     * @returns {this}
+     */
+    setFunction(name, functionParameters) {
+        this._functionParameters =
+            functionParameters != null
+                ? functionParameters._build(name)
+                : new ContractFunctionParameters()._build(name);
+
+        return this;
+    }
+
+    /**
+     * @param {Long} value
+     * @description Sets the amount of value (in tinybars or wei) to be sent to the contract in the transaction.
+     * Use this to specify an amount for a payable function call.
+     * @returns {this}
+     */
+    setValue(value) {
+        this._value = value;
+        return this;
+    }
+
+    /**
+     * @param {Long} gasLimit
+     * @description Sets the gas limit for the contract call.
+     * This specifies the maximum amount of gas that the transaction can consume.
+     * @returns {this}
+     */
+    setGasLimit(gasLimit) {
+        this._gasLimit = gasLimit;
+        return this;
+    }
+
+    /**
+     * @param {Long} gasPrice
+     * @description Sets the gas price to be used for the contract call. This specifies the price of each unit of gas used in the transaction.
+     * @returns {this}
+     */
+    setGasPrice(gasPrice) {
+        this._gasPrice = gasPrice;
+        return this;
+    }
+
+    /**
+     * @param {Long} blockNumber
+     * @description  Sets the block number for the simulation of the contract call.
+     * The block number determines the context of the contract call simulation within the blockchain.
+     * @returns {this}
+     */
+    setBlockNumber(blockNumber) {
+        this._blockNumber = blockNumber;
+        return this;
+    }
+
+    /**
+     * @returns {ContractId?}
+     */
+    get contractId() {
+        return this._contractId;
+    }
+
+    /**
+     * @returns {string}
+     */
+    get contractEvmAddress() {
+        const solidityAddress = this._contractId?.toEvmAddress();
+        if (solidityAddress == null) {
+            throw new Error("Contract ID is not set");
+        }
+        return solidityAddress;
+    }
+
+    /**
+     * @returns {AccountId?}
+     */
+    get sender() {
+        return this._sender;
+    }
+
+    /**
+     * @returns {string | null }
+     */
+    get senderEvmAddress() {
+        return this._senderEvmAddress;
+    }
+
+    /**
+     * @returns {Uint8Array | null | undefined}
+     */
+    get callData() {
+        return this._functionParameters;
+    }
+
+    /**
+     * @returns {Long?}
+     */
+    get value() {
+        return this._value;
+    }
+
+    /**
+     * @returns {Long?}
+     */
+    get gasLimit() {
+        return this._gasLimit;
+    }
+
+    /**
+     * @returns {Long?}
+     */
+    get gasPrice() {
+        return this._gasPrice;
+    }
+
+    /**
+     * @returns {Long?}
+     */
+    get blockNumber() {
+        return this._blockNumber;
+    }
+
+    /**
+     *
+     * @param {Client} client
+     * @param {object} jsonPayload
+     * @returns {Promise<MirrorNodeResponse>}
+     */
+    async performMirrorNodeRequest(client, jsonPayload) {
+        if (this.contractId == null) {
+            throw new Error("Contract ID is not set");
+        }
+        this._fillEvmAddress();
+        let mirrorNetworkAddress = client.mirrorNetwork[0];
+        const contractCallEndpoint = "/api/v1/contracts/call";
+
+        if (!client.ledgerId || client.ledgerId?.isLocalNode()) {
+            mirrorNetworkAddress = "http://"
+                .concat(client.mirrorNetwork[0].replace("5600", "8545"))
+                .concat(contractCallEndpoint);
+        } else {
+            let trimmed = client.mirrorNetwork[0].split(":");
+            mirrorNetworkAddress = "https://"
+                .concat(trimmed[0])
+                .concat(contractCallEndpoint);
+        }
+
+        // eslint-disable-next-line n/no-unsupported-features/node-builtins
+        const response = await fetch(mirrorNetworkAddress, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(jsonPayload),
+        });
+
+        if (!response.ok) {
+            throw new Error(`HTTP error! status: ${response.status}`);
+        }
+
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        const data = /** @type {MirrorNodeResponse} */ (await response.json());
+        return data;
+    }
+
+    _fillEvmAddress() {
+        if (this.senderEvmAddress == null && this.sender != null) {
+            this._senderEvmAddress = this.sender.toEvmAddress();
+        }
+    }
+    // eslint-disable-next-line jsdoc/require-returns-check
+    /**
+     * @returns {object}
+     */
+    get JSONPayload() {
+        throw new Error(
+            "JSONPayload getter is not implemented. Please implement this method in the subclass.",
+        );
+    }
+}