@hashgraphonline/standards-agent-kit 0.2.127 → 0.2.129

package/src/tools/inscriber/InscribeFromBufferTool.ts

@@ -1,57 +1,23 @@
 import { z } from 'zod';
 import { BaseInscriberQueryTool } from './base-inscriber-tools';
-import { InscriptionOptions, ContentResolverRegistry } from '@hashgraphonline/standards-sdk';
+import { InscriptionOptions } from '@hashgraphonline/standards-sdk';
 import { CallbackManagerForToolRun } from '@langchain/core/callbacks/manager';
+import { resolveContent } from '../../utils/content-resolver';
+import { contentRefSchema } from '../../validation/content-ref-schemas';
 import { loadConfig } from '../../config/ContentReferenceConfig';
 
 const inscribeFromBufferSchema = z.object({
-  base64Data: z
-    .string()
-    .min(1, 'Data cannot be empty')
-    .describe(
-      'The content to inscribe. Accept BOTH plain text AND base64. Also accepts content reference IDs in format "content-ref:[id]". When user says "inscribe it" or "inscribe the content", use the EXACT content from your previous message or from MCP tool results. DO NOT generate new content. DO NOT create repetitive text. Pass the actual search results or other retrieved content EXACTLY as you received it.'
-    ),
-  fileName: z
-    .string()
-    .min(1, 'File name cannot be empty')
-    .describe('Name for the inscribed content. Required for all inscriptions.'),
+  base64Data: z.union([z.string(), contentRefSchema])
+    .describe('Content to inscribe as base64 data, plain text, or content reference'),
+  fileName: z.string().min(1).describe('Name for the inscribed content'),
   mimeType: z.string().optional().describe('MIME type of the content'),
-  mode: z
-    .enum(['file', 'hashinal'])
-    .optional()
-    .describe('Inscription mode: file or hashinal NFT'),
-  metadata: z
-    .record(z.unknown())
-    .optional()
-    .describe('Metadata to attach to the inscription'),
-  tags: z
-    .array(z.string())
-    .optional()
-    .describe('Tags to categorize the inscription'),
-  chunkSize: z
-    .number()
-    .int()
-    .positive()
-    .optional()
-    .describe('Chunk size for large files'),
-  waitForConfirmation: z
-    .boolean()
-    .optional()
-    .describe('Whether to wait for inscription confirmation'),
-  timeoutMs: z
-    .number()
-    .int()
-    .positive()
-    .optional()
-    .describe(
-      'Timeout in milliseconds for inscription (default: no timeout - waits until completion)'
-    ),
+  metadata: z.record(z.unknown()).optional().describe('Metadata to attach'),
+  tags: z.array(z.string()).optional().describe('Tags to categorize the inscription'),
+  chunkSize: z.number().int().positive().optional().describe('Chunk size for large files'),
+  waitForConfirmation: z.boolean().optional().describe('Wait for inscription confirmation'),
+  timeoutMs: z.number().int().positive().optional().describe('Timeout in milliseconds'),
   apiKey: z.string().optional().describe('API key for inscription service'),
-  quoteOnly: z
-    .boolean()
-    .optional()
-    .default(false)
-    .describe('If true, returns a cost quote instead of executing the inscription'),
+  quoteOnly: z.boolean().optional().default(false).describe('Return cost quote only'),
 });
 
 export class InscribeFromBufferTool extends BaseInscriberQueryTool<
@@ -59,7 +25,7 @@ export class InscribeFromBufferTool extends BaseInscriberQueryTool<
 > {
   name = 'inscribeFromBuffer';
   description =
-    'Inscribe content that you have already retrieved or displayed. When user says "inscribe it" after you showed search results or other content, use THIS tool. The base64Data field accepts PLAIN TEXT (not just base64) and content reference IDs in format "content-ref:[id]". Pass the EXACT content from your previous response or MCP tool output. DO NOT generate new content or create repetitive text. Content references are automatically resolved to the original content for inscription. Set quoteOnly=true to get cost estimates without executing the inscription.';
+    'Inscribe content that you have already retrieved or displayed as standard file inscription (NOT for hashinal NFTs - use InscribeHashinalTool for NFTs). When user says "inscribe it" after you showed search results or other content, use THIS tool. The base64Data field accepts PLAIN TEXT (not just base64) and content reference IDs in format "content-ref:[id]". Pass the EXACT content from your previous response or MCP tool output. DO NOT generate new content or create repetitive text. Content references are automatically resolved to the original content for inscription. Set quoteOnly=true to get cost estimates without executing the inscription.';
 
   private config = loadConfig();
 
@@ -73,7 +39,7 @@ export class InscribeFromBufferTool extends BaseInscriberQueryTool<
   ): Promise<unknown> {
     this.validateInput(params);
 
-    const resolvedContent = await this.resolveContent(
+    const resolvedContent = await resolveContent(
       params.base64Data,
       params.mimeType,
       params.fileName
@@ -86,11 +52,13 @@ export class InscribeFromBufferTool extends BaseInscriberQueryTool<
     const resolvedFileName = resolvedContent.fileName || params.fileName;
 
     const options: InscriptionOptions = {
-      mode: params.mode,
+      mode: 'file',
       metadata: params.metadata,
       tags: params.tags,
       chunkSize: params.chunkSize,
-      waitForConfirmation: params.quoteOnly ? false : (params.waitForConfirmation ?? true),
+      waitForConfirmation: params.quoteOnly
+        ? false
+        : params.waitForConfirmation ?? true,
       waitMaxAttempts: 10,
       waitIntervalMs: 3000,
       apiKey: params.apiKey,
@@ -113,7 +81,7 @@ export class InscribeFromBufferTool extends BaseInscriberQueryTool<
           },
           options
         );
-        
+
         return {
           success: true,
           quote: {
@@ -126,11 +94,15 @@ export class InscribeFromBufferTool extends BaseInscriberQueryTool<
             mimeType: resolvedMimeType,
             sizeBytes: buffer.length,
           },
-          message: `Estimated Quote for buffer content: ${resolvedFileName} (${(buffer.length / 1024).toFixed(2)} KB)\nTotal cost: ${quote.totalCostHbar} HBAR`,
+          message: `Estimated Quote for buffer content: ${resolvedFileName} (${(
+            buffer.length / 1024
+          ).toFixed(2)} KB)\nTotal cost: ${quote.totalCostHbar} HBAR`,
         };
       } catch (error) {
         const errorMessage =
-          error instanceof Error ? error.message : 'Failed to generate inscription quote';
+          error instanceof Error
+            ? error.message
+            : 'Failed to generate inscription quote';
         throw new Error(`Quote generation failed: ${errorMessage}`);
       }
     }
@@ -247,7 +219,8 @@ export class InscribeFromBufferTool extends BaseInscriberQueryTool<
     options: InscriptionOptions
   ): string {
     if (result.confirmed && !result.quote) {
-      const topicId = result.inscription?.topic_id || (result.result as any).topicId;
+      const topicId =
+        result.inscription?.topic_id || (result.result as any).topicId;
       const network = options.network || 'testnet';
       const cdnUrl = topicId
         ? `https://kiloscribe.com/api/inscription-cdn/${topicId}?network=${network}`
@@ -260,88 +233,12 @@ export class InscribeFromBufferTool extends BaseInscriberQueryTool<
     }
 
     if (!result.quote && !result.confirmed) {
-      return `Successfully submitted inscription to the Hedera network!\n\nTransaction ID: ${(result.result as any).transactionId}\n\nThe inscription is processing and will be confirmed shortly.`;
+      return `Successfully submitted inscription to the Hedera network!\n\nTransaction ID: ${
+        (result.result as any).transactionId
+      }\n\nThe inscription is processing and will be confirmed shortly.`;
     }
 
     return 'Inscription operation completed.';
   }
 
-  private async resolveContent(
-    input: string,
-    providedMimeType?: string,
-    providedFileName?: string
-  ): Promise<{
-    buffer: Buffer;
-    mimeType?: string;
-    fileName?: string;
-    wasReference?: boolean;
-  }> {
-    const trimmedInput = input.trim();
-    
-    const resolver = this.getContentResolver() || ContentResolverRegistry.getResolver();
-    
-    if (!resolver) {
-      return this.handleDirectContent(trimmedInput, providedMimeType, providedFileName);
-    }
-    
-    const referenceId = resolver.extractReferenceId(trimmedInput);
-
-    if (referenceId) {
-      try {
-        const resolution = await resolver.resolveReference(referenceId);
-
-        return {
-          buffer: resolution.content,
-          mimeType: resolution.metadata?.mimeType || providedMimeType,
-          fileName: resolution.metadata?.fileName || providedFileName,
-          wasReference: true,
-        };
-      } catch (error) {
-        const errorMsg =
-          error instanceof Error
-            ? error.message
-            : 'Unknown error resolving reference';
-        throw new Error(`Reference resolution failed: ${errorMsg}`);
-      }
-    }
-
-    return this.handleDirectContent(trimmedInput, providedMimeType, providedFileName);
-  }
-
-  private handleDirectContent(
-    input: string,
-    providedMimeType?: string,
-    providedFileName?: string
-  ): {
-    buffer: Buffer;
-    mimeType?: string;
-    fileName?: string;
-    wasReference?: boolean;
-  } {
-    const isValidBase64 = /^[A-Za-z0-9+/]*={0,2}$/.test(input);
-
-    if (isValidBase64) {
-      try {
-        const buffer = Buffer.from(input, 'base64');
-        return {
-          buffer,
-          mimeType: providedMimeType,
-          fileName: providedFileName,
-          wasReference: false,
-        };
-      } catch (error) {
-        throw new Error(
-          'Failed to decode base64 data. Please ensure the data is properly encoded.'
-        );
-      }
-    }
-
-    const buffer = Buffer.from(input, 'utf8');
-    return {
-      buffer,
-      mimeType: providedMimeType || 'text/plain',
-      fileName: providedFileName,
-      wasReference: false,
-    };
-  }
 }

package/src/tools/inscriber/InscribeHashinalTool.ts

@@ -1,17 +1,66 @@
 import { z } from 'zod';
 import { BaseInscriberQueryTool } from './base-inscriber-tools';
-import { InscriptionOptions } from '@hashgraphonline/standards-sdk';
+import {
+  InscriptionOptions,
+  ContentResolverRegistry,
+} from '@hashgraphonline/standards-sdk';
 import { CallbackManagerForToolRun } from '@langchain/core/callbacks/manager';
+import { validateHIP412Metadata } from '../../validation/hip412-schemas';
+import { contentRefSchema } from '../../validation/content-ref-schemas';
+import { generateDefaultMetadata } from '../../utils/metadata-defaults';
+
 
 /**
  * Schema for inscribing Hashinal NFT
  */
 const inscribeHashinalSchema = z.object({
-  url: z.string().url().describe('The URL of the content to inscribe as Hashinal NFT'),
-  name: z.string().describe('Name of the Hashinal NFT'),
-  creator: z.string().describe('Creator account ID or name'),
-  description: z.string().describe('Description of the Hashinal NFT'),
-  type: z.string().describe('Type of NFT (e.g., "image", "video", "audio")'),
+  url: z
+    .string()
+    .optional()
+    .describe(
+      'The URL of the content to inscribe as Hashinal NFT (use this OR contentRef)'
+    ),
+  contentRef: contentRefSchema
+    .optional()
+    .describe(
+      'Content reference ID in format "content-ref:[id]" for already stored content (use this OR url)'
+    ),
+  base64Data: z
+    .string()
+    .optional()
+    .describe(
+      'Base64 encoded content data (use this if neither url nor contentRef provided)'
+    ),
+  fileName: z
+    .string()
+    .optional()
+    .describe(
+      'File name for the content (required when using base64Data or contentRef)'
+    ),
+  mimeType: z
+    .string()
+    .optional()
+    .describe('MIME type of the content (e.g., "image/png", "image/jpeg")'),
+  name: z
+    .string()
+    .optional()
+    .describe(
+      'Name of the Hashinal NFT (defaults to filename if not provided)'
+    ),
+  creator: z
+    .string()
+    .optional()
+    .describe('Creator account ID or name (defaults to operator account)'),
+  description: z
+    .string()
+    .optional()
+    .describe(
+      'Description of the Hashinal NFT (auto-generated if not provided)'
+    ),
+  type: z
+    .string()
+    .optional()
+    .describe('Type of NFT (auto-detected from MIME type if not provided)'),
   attributes: z
     .array(
       z.object({
@@ -30,10 +79,14 @@ const inscribeHashinalSchema = z.object({
     .url()
     .optional()
     .describe('URL to JSON metadata file'),
-  tags: z
-    .array(z.string())
+  fileStandard: z
+    .enum(['1', '6'])
     .optional()
-    .describe('Tags to categorize the NFT'),
+    .default('1')
+    .describe(
+      'HCS file standard: 1 for static Hashinals (HCS-5), 6 for dynamic Hashinals (HCS-6)'
+    ),
+  tags: z.array(z.string()).optional().describe('Tags to categorize the NFT'),
   chunkSize: z
     .number()
     .int()
@@ -49,25 +102,28 @@ const inscribeHashinalSchema = z.object({
     .int()
     .positive()
     .optional()
-    .describe('Timeout in milliseconds for inscription (default: no timeout - waits until completion)'),
-  apiKey: z
-    .string()
-    .optional()
-    .describe('API key for inscription service'),
+    .describe(
+      'Timeout in milliseconds for inscription (default: no timeout - waits until completion)'
+    ),
+  apiKey: z.string().optional().describe('API key for inscription service'),
   quoteOnly: z
     .boolean()
     .optional()
     .default(false)
-    .describe('If true, returns a cost quote instead of executing the inscription'),
+    .describe(
+      'If true, returns a cost quote instead of executing the inscription'
+    ),
 });
 
-
 /**
  * Tool for inscribing Hashinal NFTs
  */
-export class InscribeHashinalTool extends BaseInscriberQueryTool<typeof inscribeHashinalSchema> {
+export class InscribeHashinalTool extends BaseInscriberQueryTool<
+  typeof inscribeHashinalSchema
+> {
   name = 'inscribeHashinal';
-  description = 'Inscribe content as a Hashinal NFT on the Hedera network. Set quoteOnly=true to get cost estimates without executing the inscription.';
+  description =
+    'STEP 1: Inscribe content as Hashinal NFT. This tool creates the inscription and returns metadataForMinting (HRL format). CRITICAL: You MUST use the metadataForMinting field from this tool output as the metadata parameter when calling mint NFT tools. DO NOT use the original content reference for minting. This tool only inscribes - call minting tools separately after this completes. Use fileStandard=6 for dynamic Hashinals (HCS-6) or fileStandard=1 for static Hashinals (HCS-5).';
 
   get specificInputSchema() {
     return inscribeHashinalSchema;
@@ -77,36 +133,90 @@ export class InscribeHashinalTool extends BaseInscriberQueryTool<typeof inscribe
     params: z.infer<typeof inscribeHashinalSchema>,
     _runManager?: CallbackManagerForToolRun
   ): Promise<unknown> {
-    const metadata = {
-      name: params.name,
-      creator: params.creator,
-      description: params.description,
-      type: params.type,
+    // Validate input - must have either url, contentRef, or base64Data
+    if (!params.url && !params.contentRef && !params.base64Data) {
+      throw new Error(
+        'Must provide either url, contentRef, or base64Data for the Hashinal NFT content'
+      );
+    }
+
+    const operatorAccount =
+      this.inscriberBuilder['hederaKit']?.client?.operatorAccountId?.toString() || '0.0.unknown';
+
+    const rawMetadata = {
+      ...generateDefaultMetadata({
+        name: params.name,
+        creator: params.creator,
+        description: params.description,
+        type: params.type,
+        fileName: params.fileName,
+        mimeType: params.mimeType,
+        operatorAccount,
+      }),
       attributes: params.attributes,
       properties: params.properties,
     };
 
+    // Validate metadata against HIP-412 standard
+    let validatedMetadata;
+    try {
+      validatedMetadata = validateHIP412Metadata(rawMetadata);
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
+      throw new Error(`Metadata validation error: ${errorMessage}`);
+    }
+
     const options: InscriptionOptions = {
       mode: 'hashinal',
-      metadata,
+      metadata: validatedMetadata,
       jsonFileURL: params.jsonFileURL,
+      fileStandard: params.fileStandard,
       tags: params.tags,
       chunkSize: params.chunkSize,
-      waitForConfirmation: params.quoteOnly ? false : (params.waitForConfirmation ?? true),
+      waitForConfirmation: params.quoteOnly
+        ? false
+        : params.waitForConfirmation ?? true,
       waitMaxAttempts: 10,
       waitIntervalMs: 3000,
       apiKey: params.apiKey,
-      network: this.inscriberBuilder['hederaKit'].client.network.toString().includes('mainnet') ? 'mainnet' : 'testnet',
+      network: this.inscriberBuilder['hederaKit'].client.network
+        .toString()
+        .includes('mainnet')
+        ? 'mainnet'
+        : 'testnet',
       quoteOnly: params.quoteOnly,
     };
 
+    // Determine inscription data based on input type
+    let inscriptionData: any;
+
+    if (params.url) {
+      inscriptionData = { type: 'url', url: params.url };
+    } else if (params.contentRef || params.base64Data) {
+      // Handle content reference or base64 data
+      const inputData = params.contentRef || params.base64Data || '';
+      const { buffer, mimeType, fileName } = await this.resolveContent(
+        inputData,
+        params.mimeType,
+        params.fileName
+      );
+
+      inscriptionData = {
+        type: 'buffer' as const,
+        buffer,
+        fileName: fileName || params.fileName || 'hashinal-content',
+        mimeType: mimeType || params.mimeType,
+      };
+    }
+
     if (params.quoteOnly) {
       try {
         const quote = await this.generateInscriptionQuote(
-          { type: 'url', url: params.url },
+          inscriptionData,
           options
         );
-        
+
         return {
           success: true,
           quote: {
@@ -124,49 +234,164 @@ export class InscribeHashinalTool extends BaseInscriberQueryTool<typeof inscribe
         };
       } catch (error) {
         const errorMessage =
-          error instanceof Error ? error.message : 'Failed to generate inscription quote';
+          error instanceof Error
+            ? error.message
+            : 'Failed to generate inscription quote';
         throw new Error(`Quote generation failed: ${errorMessage}`);
       }
     }
 
     try {
       let result: Awaited<ReturnType<typeof this.inscriberBuilder.inscribe>>;
-      
+
       if (params.timeoutMs) {
         const timeoutPromise = new Promise<never>((_, reject) => {
           setTimeout(
-            () => reject(new Error(`Inscription timed out after ${params.timeoutMs}ms`)),
+            () =>
+              reject(
+                new Error(`Inscription timed out after ${params.timeoutMs}ms`)
+              ),
             params.timeoutMs
           );
         });
 
         result = await Promise.race([
-          this.inscriberBuilder.inscribe(
-            { type: 'url', url: params.url },
-            options
-          ),
-          timeoutPromise
+          this.inscriberBuilder.inscribe(inscriptionData, options),
+          timeoutPromise,
         ]);
       } else {
-        result = await this.inscriberBuilder.inscribe(
-          { type: 'url', url: params.url },
-          options
-        );
+        result = await this.inscriberBuilder.inscribe(inscriptionData, options);
       }
 
       if (result.confirmed && !result.quote) {
-        const topicId = result.inscription?.topic_id || (result.result as any).topicId;
+        const imageTopicId = result.inscription?.topic_id;
+        const jsonTopicId = result.inscription?.jsonTopicId;
         const network = options.network || 'testnet';
-        const cdnUrl = topicId ? `https://kiloscribe.com/api/inscription-cdn/${topicId}?network=${network}` : null;
-        return `Successfully inscribed and confirmed Hashinal NFT on the Hedera network!\n\nTransaction ID: ${(result.result as any).transactionId}\nTopic ID: ${topicId || 'N/A'}${cdnUrl ? `\nView inscription: ${cdnUrl}` : ''}\n\nThe Hashinal NFT is now available.`;
+
+        const cdnUrl = jsonTopicId
+          ? `https://kiloscribe.com/api/inscription-cdn/${jsonTopicId}?network=${network}`
+          : null;
+
+        const fileStandard = params.fileStandard || '1';
+        const hrl = jsonTopicId ? `hcs://${fileStandard}/${jsonTopicId}` : null;
+        const standardType = fileStandard === '6' ? 'Dynamic' : 'Static';
+
+        return {
+          success: true,
+          transactionId: (result.result as any).transactionId,
+          imageTopicId: imageTopicId || 'N/A',
+          jsonTopicId: jsonTopicId || 'N/A',
+          metadataForMinting: hrl,
+          hcsStandard: `hcs://${fileStandard}`,
+          fileStandard: fileStandard,
+          standardType: standardType,
+          message: `STEP 1 COMPLETE: ${standardType} Hashinal inscription finished! NOW FOR STEP 2: Use EXACTLY this metadata for minting: "${hrl}". DO NOT use the original content reference.`,
+          cdnUrl: cdnUrl,
+          NEXT_STEP_INSTRUCTIONS: `Call mint NFT tool with metadata: ["${hrl}"]`,
+          WARNING:
+            'DO NOT use content-ref for minting - only use the metadataForMinting value above',
+        };
       } else if (!result.quote && !result.confirmed) {
-        return `Successfully submitted Hashinal NFT inscription to the Hedera network!\n\nTransaction ID: ${(result.result as any).transactionId}\n\nThe inscription is processing and will be confirmed shortly.`;
+        return `Successfully submitted Hashinal NFT inscription to the Hedera network!\n\nTransaction ID: ${
+          (result.result as any).transactionId
+        }\n\nThe inscription is processing and will be confirmed shortly.`;
       } else {
         return 'Inscription operation completed.';
       }
     } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : 'Failed to inscribe Hashinal NFT';
+      const errorMessage =
+        error instanceof Error
+          ? error.message
+          : 'Failed to inscribe Hashinal NFT';
       throw new Error(`Inscription failed: ${errorMessage}`);
     }
   }
-}
+
+  private async resolveContent(
+    input: string,
+    providedMimeType?: string,
+    providedFileName?: string
+  ): Promise<{
+    buffer: Buffer;
+    mimeType?: string;
+    fileName?: string;
+    wasReference?: boolean;
+  }> {
+    const trimmedInput = input.trim();
+
+    const resolver =
+      this.getContentResolver() || ContentResolverRegistry.getResolver();
+
+    if (!resolver) {
+      return this.handleDirectContent(
+        trimmedInput,
+        providedMimeType,
+        providedFileName
+      );
+    }
+
+    const referenceId = resolver.extractReferenceId(trimmedInput);
+
+    if (referenceId) {
+      try {
+        const resolution = await resolver.resolveReference(referenceId);
+
+        return {
+          buffer: resolution.content,
+          mimeType: resolution.metadata?.mimeType || providedMimeType,
+          fileName: resolution.metadata?.fileName || providedFileName,
+          wasReference: true,
+        };
+      } catch (error) {
+        const errorMsg =
+          error instanceof Error
+            ? error.message
+            : 'Unknown error resolving reference';
+        throw new Error(`Reference resolution failed: ${errorMsg}`);
+      }
+    }
+
+    return this.handleDirectContent(
+      trimmedInput,
+      providedMimeType,
+      providedFileName
+    );
+  }
+
+  private handleDirectContent(
+    input: string,
+    providedMimeType?: string,
+    providedFileName?: string
+  ): {
+    buffer: Buffer;
+    mimeType?: string;
+    fileName?: string;
+    wasReference?: boolean;
+  } {
+    const isValidBase64 = /^[A-Za-z0-9+/]*={0,2}$/.test(input);
+
+    if (isValidBase64) {
+      try {
+        const buffer = Buffer.from(input, 'base64');
+        return {
+          buffer,
+          mimeType: providedMimeType,
+          fileName: providedFileName,
+          wasReference: false,
+        };
+      } catch (error) {
+        throw new Error(
+          'Failed to decode base64 data. Please ensure the data is properly encoded.'
+        );
+      }
+    }
+
+    const buffer = Buffer.from(input, 'utf8');
+    return {
+      buffer,
+      mimeType: providedMimeType || 'text/plain',
+      fileName: providedFileName,
+      wasReference: false,
+    };
+  }
+}