feat: implement NFT transfer tool with tests (#423)

Signed-off-by: skurzyp-blockydevs <[email protected]>

Author: skurzyp-blockydevs

docs/HEDERAPLUGINS.md

@@ -105,6 +105,7 @@ A plugin for the Hedera **Token Service (HTS)**, enabling creation and managemen
 | [`TRANSFER_FUNGIBLE_TOKEN_WITH_ALLOWANCE_TOOL`](./HEDERATOOLS.md#transfer_fungible_token_with_allowance_tool)   | Transfers fungible token using an allowance              | [View Parameters & Examples](./HEDERATOOLS.md#transfer_fungible_token_with_allowance_tool)         |
 | [`APPROVE_NFT_ALLOWANCE_TOOL`](./HEDERATOOLS.md#approve_nft_allowance_tool)                                     | Approve NFT allowances                                   | [View Parameters & Examples](./HEDERATOOLS.md#approve_nft_allowance_tool)                          |
 | [`TRANSFER_NFT_WITH_ALLOWANCE_TOOL`](./HEDERATOOLS.md#transfer_nft_with_allowance_tool)                         | Transfers NFTs using an allowance                        | [View Parameters & Examples](./HEDERATOOLS.md#transfer_nft_with_allowance_tool)                    |
+| [`TRANSFER_NON_FUNGIBLE_TOKEN_TOOL`](./HEDERATOOLS.md#transfer_non_fungible_token_tool)                         | Transfers NFTs from operator's account                   | [View Parameters & Examples](./HEDERATOOLS.md#transfer_non_fungible_token_tool)                    |
 
 ---
 

docs/HEDERATOOLS.md

@@ -43,6 +43,7 @@ For a high-level overview of available plugins, see [HEDERAPLUGINS.md](./HEDERAP
     - [DELETE_TOKEN_ALLOWANCE_TOOL](#delete_token_allowance_tool)
     - [TRANSFER_FUNGIBLE_TOKEN_WITH_ALLOWANCE_TOOL](#transfer_fungible_token_with_allowance_tool)
     - [APPROVE_NFT_ALLOWANCE_TOOL](#approve_nft_allowance_tool)
+    - [TRANSFER_NON_FUNGIBLE_TOKEN_TOOL](#transfer_non_fungible_token_tool)
     - [TRANSFER_NFT_WITH_ALLOWANCE_TOOL](#transfer_nft_with_allowance_tool)
 - [Token Query Tools](#token-query-tools)
     - [GET_TOKEN_INFO_QUERY_TOOL](#get_token_info_query_tool)
@@ -750,6 +751,28 @@ Grant approval for the entire collection token 0.0.1010 to account 0.0.2020
 
 ---
 
+### TRANSFER_NON_FUNGIBLE_TOKEN_TOOL
+
+Transfers NFTs from the operator's account to specified recipients.
+
+#### Parameters
+
+| Parameter         | Type                                                 | Required | Description                                                         |
+|-------------------|------------------------------------------------------|----------|---------------------------------------------------------------------|
+| `tokenId`         | `string`                                             | ✅        | The NFT token ID to transfer.                                       |
+| `recipients`      | `Array<{recipientId: string, serialNumber: number}>` | ✅        | List of recipients with recipient account ID and NFT serial number. |
+| `transactionMemo` | `string`                                             | ❌        | Memo for the transaction.                                           |
+
+#### Example Prompts
+
+```
+Transfer NFT 0.0.12345 serial 1 to 0.0.222
+Send my NFT 0.0.12345 serials 1 and 2 to 0.0.333
+Transfer NFT token 0.0.5555 serial 3 to account 0.0.6666 with memo "gift"
+```
+
+---
+
 ### TRANSFER_NFT_WITH_ALLOWANCE_TOOL
 
 Transfers NFTs using an existing token allowance.

typescript/src/plugins/core-token-plugin/index.ts

@@ -31,6 +31,9 @@ import associateTokenTool, {
 import transferNonFungibleTokenWithAllowanceTool, {
   TRANSFER_NON_FUNGIBLE_TOKEN_WITH_ALLOWANCE_TOOL,
 } from '@/plugins/core-token-plugin/tools/non-fungible-token/transfer-non-fungible-token-with-allowance';
+import transferNonFungibleTokenTool, {
+  TRANSFER_NON_FUNGIBLE_TOKEN_TOOL,
+} from '@/plugins/core-token-plugin/tools/non-fungible-token/transfer-non-fungible-token';
 
 export const coreTokenPlugin: Plugin = {
   name: 'core-token-plugin',
@@ -48,6 +51,7 @@ export const coreTokenPlugin: Plugin = {
       dissociateTokenTool(context),
       associateTokenTool(context),
       transferNonFungibleTokenWithAllowanceTool(context),
+      transferNonFungibleTokenTool(context),
       transferFungibleTokenWithAllowanceTool(context),
     ];
   },
@@ -65,6 +69,7 @@ export const coreTokenPluginToolNames = {
   ASSOCIATE_TOKEN_TOOL,
   UPDATE_TOKEN_TOOL,
   TRANSFER_NON_FUNGIBLE_TOKEN_WITH_ALLOWANCE_TOOL,
+  TRANSFER_NON_FUNGIBLE_TOKEN_TOOL,
   TRANSFER_FUNGIBLE_TOKEN_WITH_ALLOWANCE_TOOL,
 } as const;
 

typescript/src/plugins/core-token-plugin/tools/non-fungible-token/transfer-non-fungible-token.ts

@@ -0,0 +1,74 @@
+import { z } from 'zod';
+import type { Context } from '@/shared/configuration';
+import type { Tool } from '@/shared/tools';
+import { Client, Status } from '@hashgraph/sdk';
+import { handleTransaction, RawTransactionResponse } from '@/shared/strategies/tx-mode-strategy';
+import HederaBuilder from '@/shared/hedera-utils/hedera-builder';
+import { transferNonFungibleTokenParameters } from '@/shared/parameter-schemas/token.zod';
+import HederaParameterNormaliser from '@/shared/hedera-utils/hedera-parameter-normaliser';
+import { PromptGenerator } from '@/shared/utils/prompt-generator';
+import { transactionToolOutputParser } from '@/shared/utils/default-tool-output-parsing';
+
+const transferNonFungibleTokenPrompt = (context: Context = {}) => {
+    const contextSnippet = PromptGenerator.getContextSnippet(context);
+    const usageInstructions = PromptGenerator.getParameterUsageInstructions();
+
+    return `
+${contextSnippet}
+This tool will transfer non-fungible tokens (NFTs) from the operator's account to specified recipients.
+
+Parameters:
+- tokenId (string, required): The NFT token ID to transfer (e.g. "0.0.12345")
+- recipients (array, required): List of objects specifying recipients and serial numbers
+  - recipientId (string): Account to transfer to
+  - serialNumber (number): NFT serial number to transfer
+- transactionMemo (string, optional): Optional memo for the transaction
+${PromptGenerator.getScheduledTransactionParamsDescription(context)}
+
+${usageInstructions}
+`;
+};
+
+const postProcess = (response: RawTransactionResponse) => {
+    if (response.scheduleId) {
+        return `Scheduled non-fungible token transfer created successfully.
+Transaction ID: ${response.transactionId}
+Schedule ID: ${response.scheduleId.toString()}`;
+    }
+    return `Non-fungible tokens successfully transferred. Transaction ID: ${response.transactionId}`;
+};
+
+const transferNonFungibleToken = async (
+    client: Client,
+    context: Context,
+    params: z.infer<ReturnType<typeof transferNonFungibleTokenParameters>>,
+) => {
+    try {
+        const normalisedParams = await HederaParameterNormaliser.normaliseTransferNonFungibleToken(
+            params,
+            context,
+            client,
+        );
+
+        const tx = HederaBuilder.transferNonFungibleToken(normalisedParams);
+        return await handleTransaction(tx, client, context, postProcess);
+    } catch (error) {
+        const desc = 'Failed to transfer non-fungible token';
+        const message = desc + (error instanceof Error ? `: ${error.message}` : '');
+        console.error('[transfer_non_fungible_token_tool]', message);
+        return { raw: { status: Status.InvalidTransaction, error: message }, humanMessage: message };
+    }
+};
+
+export const TRANSFER_NON_FUNGIBLE_TOKEN_TOOL = 'transfer_non_fungible_token_tool';
+
+const tool = (context: Context): Tool => ({
+    method: TRANSFER_NON_FUNGIBLE_TOKEN_TOOL,
+    name: 'Transfer Non Fungible Token',
+    description: transferNonFungibleTokenPrompt(context),
+    parameters: transferNonFungibleTokenParameters(context).innerType(),
+    execute: transferNonFungibleToken,
+    outputParser: transactionToolOutputParser,
+});
+
+export default tool;

typescript/src/shared/hedera-utils/hedera-builder.ts

@@ -38,6 +38,7 @@ import {
   updateTokenParametersNormalised,
   transferFungibleTokenWithAllowanceParametersNormalised,
   transferNonFungibleTokenWithAllowanceParametersNormalised,
+  transferNonFungibleTokenParametersNormalised,
 } from '@/shared/parameter-schemas/token.zod';
 import z from 'zod';
 import {
@@ -96,6 +97,22 @@ export default class HederaBuilder {
     return tx;
   }
 
+  static transferNonFungibleToken(
+    params: z.infer<ReturnType<typeof transferNonFungibleTokenParametersNormalised>>,
+  ) {
+    const tx = new TransferTransaction();
+
+    for (const transfer of params.transfers) {
+      tx.addNftTransfer(transfer.nftId, params.senderAccountId, transfer.receiver);
+    }
+
+    if (params.transactionMemo) {
+      tx.setTransactionMemo(params.transactionMemo);
+    }
+
+    return HederaBuilder.maybeWrapInSchedule(tx, params.schedulingParams);
+  }
+
   static transferHbarWithAllowance(
     params: z.infer<ReturnType<typeof transferHbarWithAllowanceParametersNormalised>>,
   ) {

typescript/src/shared/hedera-utils/hedera-parameter-normaliser.ts

@@ -19,6 +19,8 @@ import {
   mintNonFungibleTokenParametersNormalised,
   transferNonFungibleTokenWithAllowanceParameters,
   transferNonFungibleTokenWithAllowanceParametersNormalised,
+  transferNonFungibleTokenParameters,
+  transferNonFungibleTokenParametersNormalised,
   transferFungibleTokenWithAllowanceParameters,
   transferFungibleTokenWithAllowanceParametersNormalised,
   updateTokenParameters,
@@ -156,7 +158,7 @@ export default class HederaParameterNormaliser {
     // Normalize scheduling parameters (if present and isScheduled = true)
     const schedulingParams = parsedParams?.schedulingParams?.isScheduled
       ? (await this.normaliseScheduledTransactionParams(parsedParams, context, client))
-          .schedulingParams
+        .schedulingParams
       : { isScheduled: false };
 
     return {
@@ -206,7 +208,7 @@ export default class HederaParameterNormaliser {
     // Normalize scheduling parameters (if present and isScheduled = true)
     const schedulingParams = parsedParams?.schedulingParams?.isScheduled
       ? (await this.normaliseScheduledTransactionParams(parsedParams, context, client))
-          .schedulingParams
+        .schedulingParams
       : { isScheduled: false };
 
     return {
@@ -261,7 +263,7 @@ export default class HederaParameterNormaliser {
     // Normalize scheduling parameters (if present and isScheduled = true)
     const schedulingParams = parsedParams?.schedulingParams?.isScheduled
       ? (await this.normaliseScheduledTransactionParams(parsedParams, context, client))
-          .schedulingParams
+        .schedulingParams
       : { isScheduled: false };
 
     return {
@@ -448,6 +450,44 @@ export default class HederaParameterNormaliser {
     };
   }
 
+  static async normaliseTransferNonFungibleToken(
+    params: z.infer<ReturnType<typeof transferNonFungibleTokenParameters>>,
+    context: Context,
+    client: Client,
+  ): Promise<z.infer<ReturnType<typeof transferNonFungibleTokenParametersNormalised>>> {
+    // Validate input using schema
+    const parsedParams: z.infer<ReturnType<typeof transferNonFungibleTokenParameters>> =
+      this.parseParamsWithSchema(params, transferNonFungibleTokenParameters, context);
+
+    // Resolve sender account (defaults to operator)
+    const senderAccountId = AccountResolver.getDefaultAccount(context, client);
+    if (!senderAccountId) {
+      throw new Error('Could not determine sender account ID');
+    }
+
+    // Convert tokenId to SDK TokenId
+    const tokenId = TokenId.fromString(parsedParams.tokenId);
+
+    // Map recipients to normalized NFT transfers
+    const transfers = parsedParams.recipients.map(recipient => ({
+      nftId: new NftId(tokenId, Number(recipient.serialNumber)),
+      receiver: AccountId.fromString(recipient.recipientId),
+    }));
+
+    // Normalize scheduling parameters (if present and isScheduled = true)
+    const schedulingParams = parsedParams?.schedulingParams?.isScheduled
+      ? (await this.normaliseScheduledTransactionParams(parsedParams, context, client))
+        .schedulingParams
+      : { isScheduled: false };
+
+    return {
+      senderAccountId: AccountId.fromString(senderAccountId),
+      transactionMemo: parsedParams.transactionMemo,
+      transfers,
+      schedulingParams,
+    };
+  }
+
   static async normaliseApproveTokenAllowance(
     params: z.infer<ReturnType<typeof approveTokenAllowanceParameters>>,
     context: Context,
@@ -549,7 +589,7 @@ export default class HederaParameterNormaliser {
     // Normalize scheduling parameters (if present and isScheduled = true)
     const schedulingParams = parsedParams?.schedulingParams?.isScheduled
       ? (await this.normaliseScheduledTransactionParams(parsedParams, context, client))
-          .schedulingParams
+        .schedulingParams
       : { isScheduled: false };
 
     return {
@@ -755,7 +795,7 @@ export default class HederaParameterNormaliser {
     // Normalize scheduling parameters (if present and isScheduled = true)
     const schedulingParams = parsedParams?.schedulingParams?.isScheduled
       ? (await this.normaliseScheduledTransactionParams(parsedParams, context, client))
-          .schedulingParams
+        .schedulingParams
       : { isScheduled: false };
 
     return {
@@ -793,7 +833,7 @@ export default class HederaParameterNormaliser {
     // Normalize scheduling parameters (if present and isScheduled = true)
     const schedulingParams = parsedParams.schedulingParams?.isScheduled
       ? (await this.normaliseScheduledTransactionParams(parsedParams, context, client))
-          .schedulingParams
+        .schedulingParams
       : { isScheduled: false };
 
     return {
@@ -859,7 +899,7 @@ export default class HederaParameterNormaliser {
     // Normalize scheduling parameters (if present and isScheduled = true)
     const schedulingParams = parsedParams?.schedulingParams?.isScheduled
       ? (await this.normaliseScheduledTransactionParams(parsedParams, context, client))
-          .schedulingParams
+        .schedulingParams
       : { isScheduled: false };
 
     return {
@@ -897,7 +937,7 @@ export default class HederaParameterNormaliser {
     // Normalize scheduling parameters (if present and isScheduled = true)
     const schedulingParams = parsedParams?.schedulingParams?.isScheduled
       ? (await this.normaliseScheduledTransactionParams(parsedParams, context, client))
-          .schedulingParams
+        .schedulingParams
       : { isScheduled: false };
 
     return {
@@ -929,7 +969,7 @@ export default class HederaParameterNormaliser {
     // Normalize scheduling parameters (if present and isScheduled = true)
     const schedulingParams = parsedParams?.schedulingParams?.isScheduled
       ? (await this.normaliseScheduledTransactionParams(parsedParams, context, client))
-          .schedulingParams
+        .schedulingParams
       : { isScheduled: false };
 
     return {
@@ -953,7 +993,7 @@ export default class HederaParameterNormaliser {
     // Normalize scheduling parameters (if present and isScheduled = true)
     const schedulingParams = parsedParams?.schedulingParams?.isScheduled
       ? (await this.normaliseScheduledTransactionParams(parsedParams, context, client))
-          .schedulingParams
+        .schedulingParams
       : { isScheduled: false };
 
     return {
@@ -993,7 +1033,7 @@ export default class HederaParameterNormaliser {
     // Normalize scheduling parameters (if present and isScheduled = true)
     const schedulingParams = parsedParams?.schedulingParams?.isScheduled
       ? (await this.normaliseScheduledTransactionParams(parsedParams, context, client))
-          .schedulingParams
+        .schedulingParams
       : { isScheduled: false };
 
     return {
@@ -1039,7 +1079,7 @@ export default class HederaParameterNormaliser {
     // Normalize scheduling parameters (if present and isScheduled = true)
     const schedulingParams = parsedParams?.schedulingParams?.isScheduled
       ? (await this.normaliseScheduledTransactionParams(parsedParams, context, client))
-          .schedulingParams
+        .schedulingParams
       : { isScheduled: false };
 
     return {
@@ -1078,7 +1118,7 @@ export default class HederaParameterNormaliser {
     // Normalize scheduling parameters (if present and isScheduled = true)
     const schedulingParams = parsedParams?.schedulingParams?.isScheduled
       ? (await this.normaliseScheduledTransactionParams(parsedParams, context, client))
-          .schedulingParams
+        .schedulingParams
       : { isScheduled: false };
 
     return {
@@ -1146,7 +1186,7 @@ export default class HederaParameterNormaliser {
     // Normalize scheduling parameters (if present and isScheduled = true)
     const schedulingParams = parsedParams?.schedulingParams?.isScheduled
       ? (await this.normaliseScheduledTransactionParams(parsedParams, context, client))
-          .schedulingParams
+        .schedulingParams
       : { isScheduled: false };
 
     return {