@hiero-ledger/sdk 2.80.0 → 2.81.0

package/src/token/TokenRejectFlow.js

@@ -4,7 +4,9 @@ import TokenDissociateTransaction from "../token/TokenDissociateTransaction.js";
 
 /**
  * @typedef {import("../PrivateKey.js").default} PrivateKey
- * @typedef {import("../client/Client.js").default<*, *>} Client
+ * @typedef {import("../channel/Channel.js").default} Channel
+ * @typedef {import("../channel/MirrorChannel.js").default} MirrorChannel
+ * @typedef {import("../client/Client.js").default<Channel, MirrorChannel>} Client
  * @typedef {import("../Signer.js").default} Signer
  * @typedef {import("../transaction/TransactionId.js").default} TransactionId
  * @typedef {import("../transaction/Transaction.js").default} Transaction

package/src/token/TokenRevokeKycTransaction.js

@@ -19,7 +19,8 @@ import Transaction, {
 
 /**
  * @typedef {import("../channel/Channel.js").default} Channel
- * @typedef {import("../client/Client.js").default<*, *>} Client
+ * @typedef {import("../channel/MirrorChannel.js").default} MirrorChannel
+ * @typedef {import("../client/Client.js").default<Channel, MirrorChannel>} Client
  * @typedef {import("../transaction/TransactionId.js").default} TransactionId
  */
 

package/src/token/TokenUnfreezeTransaction.js

@@ -19,7 +19,8 @@ import Transaction, {
 
 /**
  * @typedef {import("../channel/Channel.js").default} Channel
- * @typedef {import("../client/Client.js").default<*, *>} Client
+ * @typedef {import("../channel/MirrorChannel.js").default} MirrorChannel
+ * @typedef {import("../client/Client.js").default<Channel, MirrorChannel>} Client
  * @typedef {import("../transaction/TransactionId.js").default} TransactionId
  */
 

package/src/token/TokenUpdateTransaction.js

@@ -24,7 +24,8 @@ import TokenKeyValidation from "./TokenKeyValidation.js";
 /**
  * @typedef {import("bignumber.js").default} BigNumber
  * @typedef {import("../channel/Channel.js").default} Channel
- * @typedef {import("../client/Client.js").default<*, *>} Client
+ * @typedef {import("../channel/MirrorChannel.js").default} MirrorChannel
+ * @typedef {import("../client/Client.js").default<Channel, MirrorChannel>} Client
  * @typedef {import("../transaction/TransactionId.js").default} TransactionId
  */
 

package/src/token/TokenWipeTransaction.js

@@ -21,7 +21,8 @@ import { convertAmountToLong } from "../util.js";
 
 /**
  * @typedef {import("../channel/Channel.js").default} Channel
- * @typedef {import("../client/Client.js").default<*, *>} Client
+ * @typedef {import("../channel/MirrorChannel.js").default} MirrorChannel
+ * @typedef {import("../client/Client.js").default<Channel, MirrorChannel>} Client
  * @typedef {import("../transaction/TransactionId.js").default} TransactionId
  * @typedef {import("bignumber.js").default} BigNumber
  */

package/src/topic/TopicCreateTransaction.js

@@ -22,7 +22,8 @@ import Hbar from "../Hbar.js";
 
 /**
  * @typedef {import("../channel/Channel.js").default} Channel
- * @typedef {import("../client/Client.js").default<*, *>} Client
+ * @typedef {import("../channel/MirrorChannel.js").default} MirrorChannel
+ * @typedef {import("../client/Client.js").default<Channel, MirrorChannel>} Client
  * @typedef {import("../transaction/TransactionId.js").default} TransactionId
  */
 

package/src/topic/TopicUpdateTransaction.js

@@ -22,7 +22,8 @@ import CustomFixedFee from "../token/CustomFixedFee.js";
 
 /**
  * @typedef {import("../channel/Channel.js").default} Channel
- * @typedef {import("../client/Client.js").default<*, *>} Client
+ * @typedef {import("../channel/MirrorChannel.js").default} MirrorChannel
+ * @typedef {import("../client/Client.js").default<Channel, MirrorChannel>} Client
  * @typedef {import("../transaction/TransactionId.js").default} TransactionId
  */
 

package/src/transaction/Transaction.js

@@ -30,7 +30,8 @@ import SignableNodeTransactionBodyBytes from "./SignableNodeTransactionBodyBytes
  * @typedef {import("../schedule/ScheduleCreateTransaction.js").default} ScheduleCreateTransaction
  * @typedef {import("../PrivateKey.js").default} PrivateKey
  * @typedef {import("../channel/Channel.js").default} Channel
- * @typedef {import("../client/Client.js").default<*, *>} Client
+ * @typedef {import("../channel/MirrorChannel.js").default} MirrorChannel
+ * @typedef {import("../client/Client.js").default<Channel, MirrorChannel>} Client
  * @typedef {import("../Signer.js").Signer} Signer
  */
 
@@ -56,6 +57,17 @@ const DEFAULT_TRANSACTION_VALID_DURATION = 120;
 // This value can be overriden using `setChunkSize` when preparing to submit a messsage via `TopicMessageSubmitTransaction`.
 export const CHUNK_SIZE = 1024;
 
+/**
+ * @param {NonNullable<HieroProto.proto.TransactionBody["data"]>} transactionDataCase
+ * @returns {boolean}
+ */
+function isMultiTransactionIdType(transactionDataCase) {
+    return (
+        transactionDataCase === "fileAppend" ||
+        transactionDataCase === "consensusSubmitMessage"
+    );
+}
+
 /**
  * @type {Map<NonNullable<HieroProto.proto.TransactionBody["data"]>, (transactions: HieroProto.proto.ITransaction[], signedTransactions: HieroProto.proto.ISignedTransaction[], transactionIds: TransactionId[], nodeIds: AccountId[], bodies: HieroProto.proto.TransactionBody[]) => Transaction>}
  */
@@ -438,7 +450,7 @@ export default class Transaction extends Executable {
      * @description Batchify method is used to mark a transaction as part of a batch transaction or make it so-called inner transaction.
      * The Transaction will be frozen and signed by the operator of the client.
      *
-     * @param {import("../client/Client.js").default<Channel, *>} client
+     * @param {Client} client
      * @param {Key} batchKey
      * @returns {Promise<this>}
      */
@@ -448,6 +460,82 @@ export default class Transaction extends Executable {
         return await this.signWithOperator(client);
     }
 
+    /**
+     * Validate transaction list shape and consistency.
+     *
+     * @private
+     * @param {NonNullable<HieroProto.proto.TransactionBody["data"]>} transactionDataCase
+     * @param {TransactionId[]} transactionIds
+     * @param {AccountId[]} nodeIds
+     * @param {HieroProto.proto.ITransactionBody[]} bodies
+     * @returns {void}
+     */
+    static _validateTransactionBodies(
+        transactionDataCase,
+        transactionIds,
+        nodeIds,
+        bodies,
+    ) {
+        const hasNoTransactionIds = transactionIds.length === 0;
+        const hasNoBodies = bodies.length === 0;
+
+        if (hasNoTransactionIds || hasNoBodies) {
+            return;
+        }
+
+        const transactionCount = transactionIds.length;
+        const nodeCount = nodeIds.length;
+        const isChunkedTransactionType =
+            isMultiTransactionIdType(transactionDataCase);
+        const hasInvalidLogicalTransactionCount =
+            !isChunkedTransactionType && transactionCount !== 1;
+
+        if (nodeCount === 0) {
+            const hasUnexpectedBodyCountWithoutNodes =
+                bodies.length !== transactionCount;
+
+            if (
+                hasUnexpectedBodyCountWithoutNodes ||
+                hasInvalidLogicalTransactionCount
+            ) {
+                throw new Error("failed to validate transaction bodies");
+            }
+
+            return;
+        }
+
+        const expectedBodyCount = transactionCount * nodeCount;
+        const hasUnexpectedBodyCount = bodies.length !== expectedBodyCount;
+
+        if (hasUnexpectedBodyCount || hasInvalidLogicalTransactionCount) {
+            throw new Error("failed to validate transaction bodies");
+        }
+
+        const ignoredFields = new Set();
+        ignoredFields.add("nodeAccountID");
+
+        for (
+            let transactionIndex = 0;
+            transactionIndex < transactionCount;
+            transactionIndex++
+        ) {
+            const rowStart = transactionIndex * nodeCount;
+            const referenceBody = bodies[rowStart];
+
+            for (let nodeIndex = 1; nodeIndex < nodeCount; nodeIndex++) {
+                if (
+                    !util.compare(
+                        referenceBody,
+                        bodies[rowStart + nodeIndex],
+                        ignoredFields,
+                    )
+                ) {
+                    throw new Error("failed to validate transaction bodies");
+                }
+            }
+        }
+    }
+
     /**
      * This method is called by each `*Transaction._fromProtobuf()` method. It does
      * all the finalization before the user gets hold of a complete `Transaction`
@@ -470,22 +558,12 @@ export default class Transaction extends Executable {
         bodies,
     ) {
         const body = bodies[0];
-
-        // "row" of the 2-D `bodies` array has all the same contents except for `nodeAccountID`
-        for (let i = 0; i < transactionIds.length; i++) {
-            for (let j = 0; j < nodeIds.length - 1; j++) {
-                if (
-                    !util.compare(
-                        bodies[i * nodeIds.length + j],
-                        bodies[i * nodeIds.length + j + 1],
-                        // eslint-disable-next-line ie11/no-collection-args
-                        new Set(["nodeAccountID"]),
-                    )
-                ) {
-                    throw new Error("failed to validate transaction bodies");
-                }
-            }
-        }
+        Transaction._validateTransactionBodies(
+            transaction._getTransactionDataCase(),
+            transactionIds,
+            nodeIds,
+            bodies,
+        );
 
         // Remove node account IDs of 0
         // _IIRC_ this was initial due to some funny behavior with `ScheduleCreateTransaction`
@@ -790,6 +868,43 @@ export default class Transaction extends Executable {
         );
     }
 
+    /**
+     * Defense-in-depth validation before adding signatures.
+     *
+     * @private
+     * @returns {void}
+     */
+    _validateSignedTransactionBodies() {
+        if (
+            this._transactionIds.length === 0 ||
+            this._signedTransactions.length === 0
+        ) {
+            return;
+        }
+
+        /** @type {HieroProto.proto.ITransactionBody[]} */
+        const bodies = [];
+
+        for (const signedTransaction of this._signedTransactions.list) {
+            if (signedTransaction.bodyBytes == null) {
+                throw new Error("failed to validate transaction bodies");
+            }
+
+            bodies.push(
+                HieroProto.proto.TransactionBody.decode(
+                    /** @type {Uint8Array} */ (signedTransaction.bodyBytes),
+                ),
+            );
+        }
+
+        Transaction._validateTransactionBodies(
+            this._getTransactionDataCase(),
+            this._transactionIds.list,
+            this._nodeAccountIds.list,
+            bodies,
+        );
+    }
+
     /**
      * Sign the transaction with the public key and signer function
      *
@@ -821,6 +936,8 @@ export default class Transaction extends Executable {
             return this;
         }
 
+        this._validateSignedTransactionBodies();
+
         // If we add a new signer, then we need to re-create all transactions
         this._transactions.clear();
 
@@ -1706,7 +1823,7 @@ export default class Transaction extends Executable {
      *
      * @override
      * @protected
-     * @param {import("../client/Client.js").default<Channel, *>} client
+     * @param {Client} client
      * @returns {Promise<void>}
      */
     async _beforeExecute(client) {
@@ -2056,6 +2173,9 @@ export default class Transaction extends Executable {
             transactionId,
             transaction: this,
             logger: this._logger,
+            transactionNodeAccountIds: !this._nodeAccountIds.isEmpty
+                ? this._nodeAccountIds.list
+                : undefined,
         });
     }
 

package/src/transaction/TransactionReceiptQuery.js

@@ -14,7 +14,8 @@ const { proto } = HieroProto;
 /**
  * @typedef {import("../account/AccountId.js").default} AccountId
  * @typedef {import("../channel/Channel.js").default} Channel
- * @typedef {import("../client/Client.js").default<*, *>} Client
+ * @typedef {import("../channel/MirrorChannel.js").default} MirrorChannel
+ * @typedef {import("../client/Client.js").default<Channel, MirrorChannel>} Client
  */
 
 /**

package/src/transaction/TransactionRecordQuery.js

@@ -15,7 +15,8 @@ const { proto } = HieroProto;
 
 /**
  * @typedef {import("../channel/Channel.js").default} Channel
- * @typedef {import("../client/Client.js").default<*, *>} Client
+ * @typedef {import("../channel/MirrorChannel.js").default} MirrorChannel
+ * @typedef {import("../client/Client.js").default<Channel, MirrorChannel>} Client
  * @typedef {import("../account/AccountId.js").default} AccountId
  */
 

package/src/transaction/TransactionResponse.js

@@ -10,7 +10,9 @@ import * as hex from "../encoding/hex.js";
 import { wait } from "../util.js";
 
 /**
- * @typedef {import("../client/Client.js").default<*, *>} Client
+ * @typedef {import("../channel/Channel.js").default} Channel
+ * @typedef {import("../channel/MirrorChannel.js").default} MirrorChannel
+ * @typedef {import("../client/Client.js").default<Channel, MirrorChannel>} Client
  * @typedef {import("./Transaction.js").default} Transaction
  * @typedef {import("./TransactionReceipt.js").default} TransactionReceipt
  * @typedef {import("./TransactionRecord.js").default} TransactionRecord
@@ -43,6 +45,7 @@ export default class TransactionResponse {
      * @param {TransactionId} props.transactionId
      * @param {Transaction} [props.transaction]
      * @param {Logger | null} [props.logger]
+     * @param {AccountId[]} [props.transactionNodeAccountIds]
      */
     constructor(props) {
         /** @readonly */
@@ -56,6 +59,14 @@ export default class TransactionResponse {
         this.transaction = props.transaction;
 
         this.logger = props.logger;
+
+        /**
+         * The node account IDs that were configured on the transaction.
+         * Used for receipt query failover when allowReceiptNodeFailover is enabled.
+         * @internal
+         * @type {AccountId[] | undefined}
+         */
+        this.transactionNodeAccountIds = props.transactionNodeAccountIds;
     }
 
     /**
@@ -77,7 +88,7 @@ export default class TransactionResponse {
     async getReceipt(client) {
         let receipt;
         try {
-            receipt = await this.getReceiptQuery().execute(client);
+            receipt = await this.getReceiptQuery(client).execute(client);
         } catch (err) {
             if (
                 err instanceof ReceiptStatusError &&
@@ -113,7 +124,7 @@ export default class TransactionResponse {
     async getRecord(client) {
         await this.getReceipt(client);
 
-        return this.getRecordQuery().execute(client);
+        return this.getRecordQuery(client).execute(client);
     }
 
     /**
@@ -125,10 +136,10 @@ export default class TransactionResponse {
     async getVerboseRecord(client) {
         try {
             // The receipt needs to be called in order to wait for transaction to be included in the consensus. Otherwise we are going to get "DUPLICATE_TRANSACTION".
-            await this.getReceiptQuery().execute(client);
-            return this.getRecordQuery().execute(client);
+            await this.getReceiptQuery(client).execute(client);
+            return this.getRecordQuery(client).execute(client);
         } catch (e) {
-            return this.getRecordQuery().execute(client);
+            return this.getRecordQuery(client).execute(client);
         }
     }
 
@@ -161,21 +172,97 @@ export default class TransactionResponse {
     }
 
     /**
+     * Create a receipt query for this transaction.
+     *
+     * By default, the query is pinned to the submitting node only. If the client has
+     * `allowReceiptNodeFailover` enabled, the query can fail over to other nodes while
+     * still starting with the submitting node first.
+     *
+     * When failover is enabled, the node list is determined by:
+     * 1. Transaction's configured nodes (if transaction had specific nodes set), or
+     * 2. Client's network nodes (as fallback)
+     *
+     * @param {Client} [client] - Optional client to enable failover behavior
      * @returns {TransactionReceiptQuery}
      */
-    getReceiptQuery() {
-        return new TransactionReceiptQuery()
-            .setTransactionId(this.transactionId)
-            .setNodeAccountIds([this.nodeId]);
+    getReceiptQuery(client) {
+        const query = new TransactionReceiptQuery().setTransactionId(
+            this.transactionId,
+        );
+
+        // If client is provided and failover is enabled, construct a node list
+        // that starts with the submitting node followed by other nodes
+        if (client != null && client.allowReceiptNodeFailover) {
+            // Use transaction's configured nodes if available, otherwise use client network
+            const availableNodes =
+                this.transactionNodeAccountIds != null &&
+                this.transactionNodeAccountIds.length > 0
+                    ? this.transactionNodeAccountIds
+                    : client._network.getNodeAccountIdsForExecute();
+
+            // Build node list: [submittedNode, ...otherNodes] without duplicates
+            const nodeList = [this.nodeId];
+            for (const node of availableNodes) {
+                // Only add if it's not the submitting node (avoid duplicates)
+                if (!node.equals(this.nodeId)) {
+                    nodeList.push(node);
+                }
+            }
+
+            query.setNodeAccountIds(nodeList);
+        } else {
+            // Default behavior: pin to submitting node only
+            query.setNodeAccountIds([this.nodeId]);
+        }
+
+        return query;
     }
 
     /**
+     * Create a record query for this transaction.
+     *
+     * By default, the query is pinned to the submitting node only. If the client has
+     * `allowReceiptNodeFailover` enabled, the query can fail over to other nodes while
+     * still starting with the submitting node first.
+     *
+     * When failover is enabled, the node list is determined by:
+     * 1. Transaction's configured nodes (if transaction had specific nodes set), or
+     * 2. Client's network nodes (as fallback)
+     *
+     * @param {Client} [client] - Optional client to enable failover behavior
      * @returns {TransactionRecordQuery}
      */
-    getRecordQuery() {
-        return new TransactionRecordQuery()
-            .setTransactionId(this.transactionId)
-            .setNodeAccountIds([this.nodeId]);
+    getRecordQuery(client) {
+        const query = new TransactionRecordQuery().setTransactionId(
+            this.transactionId,
+        );
+
+        // If client is provided and failover is enabled, construct a node list
+        // that starts with the submitting node followed by other nodes
+        if (client != null && client.allowReceiptNodeFailover) {
+            // Use transaction's configured nodes if available, otherwise use client network
+            const availableNodes =
+                this.transactionNodeAccountIds != null &&
+                this.transactionNodeAccountIds.length > 0
+                    ? this.transactionNodeAccountIds
+                    : client._network.getNodeAccountIdsForExecute();
+
+            // Build node list: [submittedNode, ...otherNodes] without duplicates
+            const nodeList = [this.nodeId];
+            for (const node of availableNodes) {
+                // Only add if it's not the submitting node (avoid duplicates)
+                if (!node.equals(this.nodeId)) {
+                    nodeList.push(node);
+                }
+            }
+
+            query.setNodeAccountIds(nodeList);
+        } else {
+            // Default behavior: pin to submitting node only
+            query.setNodeAccountIds([this.nodeId]);
+        }
+
+        return query;
     }
 
     /**