@hiero-ledger/sdk 2.80.0 → 2.81.0-beta.1

package/src/hooks/NftHookCall.js

@@ -0,0 +1,64 @@
+// SPDX-License-Identifier: Apache-2.0
+
+import HookCall from "./HookCall.js";
+import EvmHookCall from "./EvmHookCall.js";
+import NftHookType from "./NftHookType.js";
+/**
+ * @namespace proto
+ * @typedef {import("@hiero-ledger/proto").proto.IHookCall} HieroProto.proto.IHookCall
+ */
+
+/**
+ * @typedef {typeof NftHookType[keyof typeof NftHookType]} NftHookTypeValue
+ */
+
+/**
+ * A typed hook call for NFT transfers.
+ */
+class NftHookCall extends HookCall {
+    /**
+     * @param {object} props
+     * @param {Long} [props.hookId]
+     * @param {import("../hooks/EvmHookCall.js").default} [props.evmHookCall]
+     * @param {NftHookTypeValue} props.type - One of NftHookType (PRE_HOOK_SENDER, PRE_POST_HOOK_SENDER, PRE_HOOK_RECEIVER, PRE_POST_HOOK_RECEIVER)
+     */
+    constructor(props) {
+        super(props);
+
+        if (props.type == null) {
+            throw new Error("type cannot be null");
+        }
+
+        /**
+         * The type of NFT hook
+         * @private
+         * @type {number}
+         */
+        this._type = props.type;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get type() {
+        return this._type;
+    }
+
+    /**
+     * @internal
+     * @param {HieroProto.proto.IHookCall} hookCall
+     * @param {NftHookTypeValue} type
+     * @returns {NftHookCall}
+     */
+    static _fromProtobufWithType(hookCall, type) {
+        return new NftHookCall({
+            hookId: hookCall.hookId != null ? hookCall.hookId : undefined,
+            evmHookCall: hookCall.evmHookCall
+                ? EvmHookCall._fromProtobuf(hookCall.evmHookCall)
+                : undefined,
+            type,
+        });
+    }
+}
+
+export default NftHookCall;

package/src/hooks/NftHookType.js

@@ -0,0 +1,8 @@
+const NftHookType = Object.freeze({
+    PRE_HOOK_SENDER: 0,
+    PRE_POST_HOOK_SENDER: 1,
+    PRE_HOOK_RECEIVER: 2,
+    PRE_POST_HOOK_RECEIVER: 3,
+});
+
+export default NftHookType;

package/src/token/AbstractTokenTransferTransaction.js

@@ -20,6 +20,12 @@ import { convertAmountToLong } from "../util.js";
  * @typedef {import("@hiero-ledger/proto").proto.ITokenAirdropTransactionBody} HieroProto.proto.ITokenAirdropTransactionBody
  */
 
+/**
+ * @typedef {import("../hooks/HookCall.js").default} HookCall
+ * @typedef {import("../hooks/FungibleHookCall.js").default} FungibleHookCall
+ * @typedef {import("../hooks/NftHookCall.js").default} NftHookCall
+ */
+
 /**
  * @typedef {object} TransferTokensInput
  * @property {TokenId | string} tokenId
@@ -106,6 +112,7 @@ export default class AbstractTokenTransferTransaction extends Transaction {
      * @param {number | Long | BigNumber | bigint} amount
      * @param {boolean} isApproved
      * @param {number | null} expectedDecimals
+     * @param {FungibleHookCall} [hookCall]
      * @returns {this}
      */
     _addTokenTransfer(
@@ -114,6 +121,7 @@ export default class AbstractTokenTransferTransaction extends Transaction {
         amount,
         isApproved,
         expectedDecimals,
+        hookCall,
     ) {
         this._requireNotFrozen();
 
@@ -140,9 +148,10 @@ export default class AbstractTokenTransferTransaction extends Transaction {
             new TokenTransfer({
                 tokenId,
                 accountId,
-                expectedDecimals: expectedDecimals,
+                expectedDecimals,
                 amount,
                 isApproved,
+                hookCall,
             }),
         );
 
@@ -165,6 +174,8 @@ export default class AbstractTokenTransferTransaction extends Transaction {
      * @param {AccountId | string | Long | number} senderAccountIdOrSerialNumber
      * @param {AccountId | string} receiverAccountIdOrSenderAccountId
      * @param {(AccountId | string)=} receiver
+     * @param {NftHookCall=} senderHookCall
+     * @param {NftHookCall=} receiverHookCall
      * @returns {this}
      */
     _addNftTransfer(
@@ -173,6 +184,8 @@ export default class AbstractTokenTransferTransaction extends Transaction {
         senderAccountIdOrSerialNumber,
         receiverAccountIdOrSenderAccountId,
         receiver,
+        senderHookCall,
+        receiverHookCall,
     ) {
         this._requireNotFrozen();
 
@@ -263,6 +276,8 @@ export default class AbstractTokenTransferTransaction extends Transaction {
                 senderAccountId,
                 receiverAccountId,
                 isApproved,
+                senderHookCall,
+                receiverHookCall,
             }),
         );
 

package/src/token/TokenAirdropTransaction.js

@@ -137,6 +137,7 @@ export default class TokenAirdropTransaction extends AbstractTokenTransferTransa
             amount,
             true,
             expectedDecimals,
+            undefined,
         );
         return this;
     }

package/src/token/TokenNftTransfer.js

@@ -3,6 +3,8 @@
 import Long from "long";
 import AccountId from "../account/AccountId.js";
 import TokenId from "./TokenId.js";
+import NftHookCall from "../hooks/NftHookCall.js";
+import NftHookType from "../hooks/NftHookType.js";
 
 /**
  * @namespace proto
@@ -29,6 +31,8 @@ export default class TokenNftTransfer {
      * @param {AccountId | string} props.receiverAccountId
      * @param {Long | number} props.serialNumber
      * @param {boolean} props.isApproved
+     * @param {NftHookCall} [props.senderHookCall]
+     * @param {NftHookCall} [props.receiverHookCall]
      */
     constructor(props) {
         /**
@@ -56,6 +60,8 @@ export default class TokenNftTransfer {
                 : AccountId.fromString(props.receiverAccountId);
 
         this.serialNumber = Long.fromValue(props.serialNumber);
+        this.senderHookCall = props.senderHookCall;
+        this.receiverHookCall = props.receiverHookCall;
         this.isApproved = props.isApproved;
     }
 
@@ -74,6 +80,34 @@ export default class TokenNftTransfer {
             for (const transfer of tokenTransfer.nftTransfers != null
                 ? tokenTransfer.nftTransfers
                 : []) {
+                // Determine sender hook type
+                let senderHookCall;
+                if (transfer.preTxSenderAllowanceHook != null) {
+                    senderHookCall = NftHookCall._fromProtobufWithType(
+                        transfer.preTxSenderAllowanceHook,
+                        NftHookType.PRE_HOOK_SENDER,
+                    );
+                } else if (transfer.prePostTxSenderAllowanceHook != null) {
+                    senderHookCall = NftHookCall._fromProtobufWithType(
+                        transfer.prePostTxSenderAllowanceHook,
+                        NftHookType.PRE_POST_HOOK_SENDER,
+                    );
+                }
+
+                // Determine receiver hook type
+                let receiverHookCall;
+                if (transfer.preTxReceiverAllowanceHook != null) {
+                    receiverHookCall = NftHookCall._fromProtobufWithType(
+                        transfer.preTxReceiverAllowanceHook,
+                        NftHookType.PRE_HOOK_RECEIVER,
+                    );
+                } else if (transfer.prePostTxReceiverAllowanceHook != null) {
+                    receiverHookCall = NftHookCall._fromProtobufWithType(
+                        transfer.prePostTxReceiverAllowanceHook,
+                        NftHookType.PRE_POST_HOOK_RECEIVER,
+                    );
+                }
+
                 transfers.push(
                     new TokenNftTransfer({
                         tokenId,
@@ -92,6 +126,8 @@ export default class TokenNftTransfer {
                                 ? transfer.serialNumber
                                 : Long.ZERO,
                         isApproved: transfer.isApproval == true,
+                        senderHookCall: senderHookCall,
+                        receiverHookCall: receiverHookCall,
                     }),
                 );
             }
@@ -105,11 +141,42 @@ export default class TokenNftTransfer {
      * @returns {HieroProto.proto.INftTransfer}
      */
     _toProtobuf() {
-        return {
+        /** @type {HieroProto.proto.INftTransfer} */
+        const result = {
             senderAccountID: this.senderAccountId._toProtobuf(),
             receiverAccountID: this.receiverAccountId._toProtobuf(),
             serialNumber: this.serialNumber,
             isApproval: this.isApproved,
         };
+
+        // Handle sender hook
+        if (this.senderHookCall != null) {
+            switch (this.senderHookCall.type) {
+                case NftHookType.PRE_HOOK_SENDER:
+                    result.preTxSenderAllowanceHook =
+                        this.senderHookCall._toProtobuf();
+                    break;
+                case NftHookType.PRE_POST_HOOK_SENDER:
+                    result.prePostTxSenderAllowanceHook =
+                        this.senderHookCall._toProtobuf();
+                    break;
+            }
+        }
+
+        // Handle receiver hook
+        if (this.receiverHookCall != null) {
+            switch (this.receiverHookCall.type) {
+                case NftHookType.PRE_HOOK_RECEIVER:
+                    result.preTxReceiverAllowanceHook =
+                        this.receiverHookCall._toProtobuf();
+                    break;
+                case NftHookType.PRE_POST_HOOK_RECEIVER:
+                    result.prePostTxReceiverAllowanceHook =
+                        this.receiverHookCall._toProtobuf();
+                    break;
+            }
+        }
+
+        return result;
     }
 }

package/src/token/TokenTransfer.js

@@ -4,6 +4,8 @@ import Long from "long";
 import AccountId from "../account/AccountId.js";
 import TokenId from "./TokenId.js";
 import { convertAmountToLong } from "../util.js";
+import FungibleHookCall from "../hooks/FungibleHookCall.js";
+import FungibleHookType from "../hooks/FungibleHookType.js";
 
 /**
  * @namespace proto
@@ -38,6 +40,7 @@ export default class TokenTransfer {
      * @param {number | null} props.expectedDecimals
      * @param {Long | number | BigNumber | bigint} props.amount
      * @param {boolean} props.isApproved
+     * @param {FungibleHookCall} [props.hookCall]
      */
     constructor(props) {
         /**
@@ -63,6 +66,7 @@ export default class TokenTransfer {
         this.expectedDecimals = props.expectedDecimals;
         this.amount = convertAmountToLong(props.amount);
         this.isApproved = props.isApproved;
+        this.hookCall = props.hookCall || null;
     }
 
     /**
@@ -87,6 +91,20 @@ export default class TokenTransfer {
             for (const transfer of tokenTransfer.transfers != null
                 ? tokenTransfer.transfers
                 : []) {
+                // Determine which hook type is present, if any
+                let hookCall = null;
+                if (transfer.preTxAllowanceHook != null) {
+                    hookCall = FungibleHookCall._fromProtobufWithType(
+                        transfer.preTxAllowanceHook,
+                        FungibleHookType.PRE_TX_ALLOWANCE_HOOK,
+                    );
+                } else if (transfer.prePostTxAllowanceHook != null) {
+                    hookCall = FungibleHookCall._fromProtobufWithType(
+                        transfer.prePostTxAllowanceHook,
+                        FungibleHookType.PRE_POST_TX_ALLOWANCE_HOOK,
+                    );
+                }
+
                 transfers.push(
                     new TokenTransfer({
                         tokenId,
@@ -101,6 +119,7 @@ export default class TokenTransfer {
                                 ? transfer.amount
                                 : Long.ZERO,
                         isApproved: transfer.isApproval == true,
+                        hookCall: hookCall ?? undefined,
                     }),
                 );
             }
@@ -114,11 +133,25 @@ export default class TokenTransfer {
      * @returns {HieroProto.proto.IAccountAmount}
      */
     _toProtobuf() {
-        return {
+        /** @type {HieroProto.proto.IAccountAmount} */
+        const result = {
             accountID: this.accountId._toProtobuf(),
             amount: this.amount,
             isApproval: this.isApproved,
         };
+
+        if (this.hookCall != null) {
+            switch (this.hookCall.type) {
+                case FungibleHookType.PRE_TX_ALLOWANCE_HOOK:
+                    result.preTxAllowanceHook = this.hookCall._toProtobuf();
+                    break;
+                case FungibleHookType.PRE_POST_TX_ALLOWANCE_HOOK:
+                    result.prePostTxAllowanceHook = this.hookCall._toProtobuf();
+                    break;
+            }
+        }
+
+        return result;
     }
 
     /**

package/src/transaction/Transaction.js

@@ -2056,6 +2056,9 @@ export default class Transaction extends Executable {
             transactionId,
             transaction: this,
             logger: this._logger,
+            transactionNodeAccountIds: !this._nodeAccountIds.isEmpty
+                ? this._nodeAccountIds.list
+                : undefined,
         });
     }
 

package/src/transaction/TransactionResponse.js

@@ -43,6 +43,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 +57,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 +86,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 +122,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 +134,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 +170,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;
     }
 
     /**