@hashgraphonline/standards-agent-kit 0.2.132 → 0.2.135

package/src/tools/inscriber/InscribeHashinalTool.ts

@@ -15,7 +15,6 @@ import {
   extendZodSchema,
   renderConfigs,
 } from '../../lib/zod-render/schema-extension';
-import type { EnhancedRenderConfig } from '../../lib/zod-render/types';
 import {
   createInscriptionSuccess,
   createInscriptionQuote,
@@ -25,15 +24,42 @@ import {
 import { FormValidatable } from '../../interfaces/FormValidatable';
 
 /**
- * Result of HCS-12 block lookup
+ * Network-specific Hashinal block configuration for HashLink blocks
  */
-interface HCS12BlockResult {
-  blockId: string;
-  hashLink: string;
-  template: string;
-  attributes: Record<string, unknown>;
+const HASHLINK_BLOCK_CONFIG = {
+  testnet: {
+    blockId: '0.0.6617393',
+    hashLink: 'hcs://12/0.0.6617393',
+    template: '0.0.6617393',
+  },
+  mainnet: {
+    blockId: '0.0.TBD',
+    hashLink: 'hcs://12/0.0.TBD',
+    template: '0.0.TBD',
+  },
+};
+
+/**
+ * Gets the appropriate HashLink block configuration for the specified network.
+ * Provides graceful fallback to testnet for unknown networks or undeployed mainnet blocks.
+ *
+ * @param network The network type to get configuration for
+ * @returns Network-specific block configuration with blockId, hashLink, and template
+ */
+// @ts-ignore - keep untyped to satisfy mixed parser while using runtime narrowing
+function getHashLinkBlockId(network) {
+  const config =
+    network === 'mainnet'
+      ? HASHLINK_BLOCK_CONFIG.mainnet
+      : HASHLINK_BLOCK_CONFIG.testnet;
+  if (!config || config.blockId === '0.0.TBD') {
+    return HASHLINK_BLOCK_CONFIG.testnet;
+  }
+  return config;
 }
 
+// Note: Using inline return type annotations to avoid parser issues with interface declarations
+
 /**
  * Schema for inscribing Hashinal NFT
  */
@@ -179,6 +205,17 @@ export class InscribeHashinalTool
   description =
     'Tool for inscribing Hashinal NFTs. CRITICAL: When user provides content (url/contentRef/base64Data), call with ONLY the content parameters - DO NOT auto-generate name, description, creator, or attributes. A form will be automatically shown to collect metadata from the user. Only include metadata parameters if the user explicitly provided them in their message.';
 
+  // Declare entity resolution preferences to preserve user-specified literal fields
+  getEntityResolutionPreferences(): Record<string, string> {
+    return {
+      name: 'literal',
+      description: 'literal',
+      creator: 'literal',
+      attributes: 'literal',
+      properties: 'literal',
+    };
+  }
+
   get specificInputSchema(): z.ZodObject<z.ZodRawShape> {
     const baseSchema =
       (inscribeHashinalSchema as z.ZodType & { _def?: { schema?: z.ZodType } })
@@ -318,12 +355,7 @@ export class InscribeHashinalTool
             })
           )
         )
-          .withRender(
-            renderConfigs.array(
-              'NFT Attributes',
-              'Attribute'
-            ) as EnhancedRenderConfig
-          )
+          .withRender(renderConfigs.array('NFT Attributes', 'Attribute'))
           .optional()
           // eslint-disable-next-line @typescript-eslint/no-explicit-any
           .describe('Collectible traits and characteristics.'),
@@ -439,7 +471,7 @@ export class InscribeHashinalTool
       waitForConfirmation: params.quoteOnly
         ? false
         : params.waitForConfirmation ?? true,
-      waitMaxAttempts: 30,
+      waitMaxAttempts: 60,
       waitIntervalMs: 5000,
       network: this.inscriberBuilder['hederaKit'].client.network
         .toString()
@@ -571,6 +603,14 @@ export class InscribeHashinalTool
           },
         });
 
+        this.onEntityCreated?.({
+          entityId: jsonTopicId || imageTopicId || 'unknown',
+          entityName: params.name || 'Unnamed Inscription',
+          entityType: 'topic',
+          transactionId: (result.result as { transactionId?: string })
+            ?.transactionId,
+        });
+
         if (params.withHashLinkBlocks) {
           try {
             const blockData = await this.createHashLinkBlock(
@@ -628,6 +668,14 @@ export class InscribeHashinalTool
               },
             });
 
+            this.onEntityCreated?.({
+              entityId: jsonTopicId || imageTopicId || 'unknown',
+              entityName: params.name || 'Unnamed Inscription',
+              entityType: 'topic',
+              transactionId: (result.result as { transactionId?: string })
+                ?.transactionId,
+            });
+
             if (params.withHashLinkBlocks) {
               try {
                 const blockData = await this.createHashLinkBlock(
@@ -692,20 +740,81 @@ export class InscribeHashinalTool
   }
 
   /**
-   * Creates HashLink block reference for inscription display
+   * Creates HashLink block configuration for Hashinal inscriptions.
+   * Automatically detects network and selects appropriate block ID configuration.
+   * Uses testnet block as fallback for unknown networks or undeployed mainnet blocks.
+   *
+   * @param response The inscription response containing metadata and network information
+   * @param _mimeType Optional MIME type (currently unused, preserved for compatibility)
+   * @returns HCS12BlockResult with network-specific block configuration
+   *
+   * @example
+   * ```typescript
+   * // Testnet usage (automatic detection from client)
+   * const testnetClient = Client.forTestnet();
+   * const tool = new InscribeHashinalTool(testnetClient);
+   * const block = await tool.createHashLinkBlock(inscriptionResponse);
+   * console.log(block.blockId);   // '0.0.6617393'
+   * console.log(block.hashLink);  // 'hcs://12/0.0.6617393'
+   *
+   * // Mainnet usage (automatic detection from client)
+   * const mainnetClient = Client.forMainnet();
+   * const tool = new InscribeHashinalTool(mainnetClient);
+   * const block = await tool.createHashLinkBlock(inscriptionResponse);
+   * console.log(block.blockId);   // Network-specific mainnet block ID
+   *
+   * // HashLink Block Response Structure:
+   * {
+   *   blockId: string;        // Hedera account ID format (e.g., '0.0.6617393')
+   *   hashLink: string;       // HCS-12 URL format: 'hcs://12/{blockId}'
+   *   template: string;       // Block template reference matching blockId
+   *   attributes: {           // Metadata for client-side processing
+   *     name: string;         // Content display name
+   *     creator: string;      // Creator account ID
+   *     topicId: string;      // HCS topic containing the inscription
+   *     hrl: string;          // Hedera Resource Locator
+   *     network: string;      // Network type: 'testnet' | 'mainnet'
+   *   }
+   * }
+   *
+   * // Render function usage in HashLink blocks:
+   * // The block's JavaScript render function receives this structure
+   * // and can access network-specific resources through attributes.network
+   * ```
    */
   private async createHashLinkBlock(
     response: ReturnType<typeof createInscriptionSuccess>,
     _mimeType?: string
-  ): Promise<HCS12BlockResult> {
-    const network = response.inscription.cdnUrl?.includes('mainnet')
+  ): Promise<{
+    blockId: string;
+    hashLink: string;
+    template: string;
+    attributes: Record<string, unknown>;
+  }> {
+    const clientNetwork = this.inscriberBuilder['hederaKit'].client.network
+      .toString()
+      .includes('mainnet')
       ? 'mainnet'
       : 'testnet';
 
+    const cdnNetwork = response.inscription.cdnUrl?.includes('mainnet')
+      ? 'mainnet'
+      : 'testnet';
+
+    if (clientNetwork !== cdnNetwork) {
+      const logger = new Logger({ module: 'InscribeHashinalTool' });
+      logger.warn(
+        `Network mismatch detected: client=${clientNetwork}, cdn=${cdnNetwork}. Using client network.`
+      );
+    }
+
+    const network = clientNetwork;
+    const config = getHashLinkBlockId(network);
+
     return {
-      blockId: '0.0.6617393',
-      hashLink: 'hcs://12/0.0.6617393',
-      template: '0.0.6617393',
+      blockId: config.blockId,
+      hashLink: config.hashLink,
+      template: config.template,
       attributes: {
         name: response.metadata.name || 'Untitled Content',
         creator: response.metadata.creator || '',

package/src/tools/inscriber/base-inscriber-tools.ts

@@ -16,6 +16,16 @@ import {
 } from '@hashgraphonline/standards-sdk';
 import { z } from 'zod';
 
+/**
+ * Event emitted when an entity is created during inscription
+ */
+export interface EntityCreationEvent {
+  entityId: string;
+  entityName: string;
+  entityType: string;
+  transactionId?: string;
+}
+
 /**
  * Base class for Inscriber transaction tools
  */
@@ -28,6 +38,7 @@ export abstract class BaseInscriberTransactionTool<
 > extends BaseHederaTransactionTool<T> {
   protected inscriberBuilder: InscriberBuilder;
   protected contentResolver: ContentResolverInterface | null;
+  protected onEntityCreated?: (event: EntityCreationEvent) => void;
   namespace = 'inscriber' as const;
 
   constructor(params: InscriberTransactionToolParams) {
@@ -50,6 +61,13 @@ export abstract class BaseInscriberTransactionTool<
     return this.contentResolver;
   }
 
+  /**
+   * Set entity creation handler for automatic entity storage
+   */
+  setEntityCreationHandler(handler: (event: EntityCreationEvent) => void): void {
+    this.onEntityCreated = handler;
+  }
+
   /**
    * Generate a quote for an inscription without executing it
    * @param input - The inscription input data
@@ -93,6 +111,7 @@ export abstract class BaseInscriberQueryTool<
 > extends BaseHederaQueryTool<T> {
   protected inscriberBuilder: InscriberBuilder;
   protected contentResolver: ContentResolverInterface | null;
+  protected onEntityCreated?: (event: EntityCreationEvent) => void;
   namespace = 'inscriber' as const;
 
   constructor(params: InscriberQueryToolParams) {
@@ -115,6 +134,13 @@ export abstract class BaseInscriberQueryTool<
     return this.contentResolver;
   }
 
+  /**
+   * Set entity creation handler for automatic entity storage
+   */
+  setEntityCreationHandler(handler: (event: EntityCreationEvent) => void): void {
+    this.onEntityCreated = handler;
+  }
+
   /**
    * Generate a quote for an inscription without executing it
    * @param input - The inscription input data

package/src/types/inscription-response.ts

@@ -131,9 +131,9 @@ export function createInscriptionSuccess(params: {
     },
     metadata,
     nextSteps: {
-      primary: 'Use the HRL below as metadata when minting your NFT',
+      primary: 'CRITICAL: When minting NFTs, use ONLY the mintingMetadata value as a single string in the metadata array. Do NOT create JSON objects.',
       context:
-        'The HRL (Hedera Resource Locator) is the standardized way to reference your inscribed content in NFT metadata.',
+        'The metadata parameter for minting should be exactly: ["' + hrl + '"] - just the HRL string in an array, nothing else.',
       mintingMetadata: hrl,
     },
   };

package/dist/cjs/lib/zod-render/__tests__/withRender.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/cjs/tools/hedera/HederaCreateNftTool.d.ts

@@ -1,72 +0,0 @@
-import { z } from 'zod';
-import { BaseHederaTransactionTool, BaseServiceBuilder } from 'hedera-agent-kit';
-/**
- * Enhanced NFT creation schema with render configurations
- */
-export declare const HederaCreateNftSchema: import('../..').ZodSchemaWithRender<{
-    tokenName: string;
-    memo?: string | undefined;
-    adminKey?: string | undefined;
-    tokenSymbol?: string | undefined;
-    treasuryAccountId?: string | undefined;
-    kycKey?: string | undefined;
-    freezeKey?: string | undefined;
-    wipeKey?: string | undefined;
-    supplyKey?: string | undefined;
-    feeScheduleKey?: string | undefined;
-    pauseKey?: string | undefined;
-    autoRenewAccountId?: string | undefined;
-    autoRenewPeriod?: number | undefined;
-    freezeDefault?: boolean | undefined;
-    supplyType?: "FINITE" | "INFINITE" | undefined;
-    maxSupply?: string | number | undefined;
-    customFees?: ({
-        type: "FIXED" | "FIXED_FEE";
-        amount: string | number;
-        feeCollectorAccountId?: string | undefined;
-        denominatingTokenId?: string | undefined;
-    } | {
-        type: "FRACTIONAL" | "FRACTIONAL_FEE";
-        numerator: number;
-        denominator: number;
-        feeCollectorAccountId?: string | undefined;
-        minAmount?: string | number | undefined;
-        maxAmount?: string | number | undefined;
-        assessmentMethodInclusive?: boolean | undefined;
-    } | {
-        type: "ROYALTY" | "ROYALTY_FEE";
-        numerator: number;
-        denominator: number;
-        feeCollectorAccountId?: string | undefined;
-        fallbackFee?: {
-            amount: string | number;
-            feeCollectorAccountId?: string | undefined;
-            denominatingTokenId?: string | undefined;
-        } | undefined;
-    })[] | undefined;
-}>;
-/**
- * Hedera Create NFT Tool with enhanced render configurations for form generation
- */
-export declare class HederaCreateNftTool extends BaseHederaTransactionTool<any> {
-    name: string;
-    description: string;
-    specificInputSchema: any;
-    namespace: string;
-    /**
-     * Returns the service builder for HTS operations
-     */
-    protected getServiceBuilder(): BaseServiceBuilder;
-    /**
-     * Calls the builder method to create the NFT collection
-     */
-    protected callBuilderMethod(builder: BaseServiceBuilder, specificArgs: z.infer<typeof HederaCreateNftSchema>): Promise<void>;
-    /**
-     * Provides helpful notes for specific field values
-     */
-    protected getNoteForKey(key: string, schemaDefaultValue: unknown, actualValue: unknown): string | undefined;
-    /**
-     * Validates the configuration before execution
-     */
-    protected validateInput(args: z.infer<typeof HederaCreateNftSchema>): Promise<void>;
-}

package/dist/cjs/tools/hedera/index.d.ts

@@ -1 +0,0 @@
-export { HederaCreateNftTool, HederaCreateNftSchema } from './HederaCreateNftTool';

package/dist/es/lib/zod-render/__tests__/withRender.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/es/tools/hedera/HederaCreateNftTool.d.ts

@@ -1,72 +0,0 @@
-import { z } from 'zod';
-import { BaseHederaTransactionTool, BaseServiceBuilder } from 'hedera-agent-kit';
-/**
- * Enhanced NFT creation schema with render configurations
- */
-export declare const HederaCreateNftSchema: import('../..').ZodSchemaWithRender<{
-    tokenName: string;
-    memo?: string | undefined;
-    adminKey?: string | undefined;
-    tokenSymbol?: string | undefined;
-    treasuryAccountId?: string | undefined;
-    kycKey?: string | undefined;
-    freezeKey?: string | undefined;
-    wipeKey?: string | undefined;
-    supplyKey?: string | undefined;
-    feeScheduleKey?: string | undefined;
-    pauseKey?: string | undefined;
-    autoRenewAccountId?: string | undefined;
-    autoRenewPeriod?: number | undefined;
-    freezeDefault?: boolean | undefined;
-    supplyType?: "FINITE" | "INFINITE" | undefined;
-    maxSupply?: string | number | undefined;
-    customFees?: ({
-        type: "FIXED" | "FIXED_FEE";
-        amount: string | number;
-        feeCollectorAccountId?: string | undefined;
-        denominatingTokenId?: string | undefined;
-    } | {
-        type: "FRACTIONAL" | "FRACTIONAL_FEE";
-        numerator: number;
-        denominator: number;
-        feeCollectorAccountId?: string | undefined;
-        minAmount?: string | number | undefined;
-        maxAmount?: string | number | undefined;
-        assessmentMethodInclusive?: boolean | undefined;
-    } | {
-        type: "ROYALTY" | "ROYALTY_FEE";
-        numerator: number;
-        denominator: number;
-        feeCollectorAccountId?: string | undefined;
-        fallbackFee?: {
-            amount: string | number;
-            feeCollectorAccountId?: string | undefined;
-            denominatingTokenId?: string | undefined;
-        } | undefined;
-    })[] | undefined;
-}>;
-/**
- * Hedera Create NFT Tool with enhanced render configurations for form generation
- */
-export declare class HederaCreateNftTool extends BaseHederaTransactionTool<any> {
-    name: string;
-    description: string;
-    specificInputSchema: any;
-    namespace: string;
-    /**
-     * Returns the service builder for HTS operations
-     */
-    protected getServiceBuilder(): BaseServiceBuilder;
-    /**
-     * Calls the builder method to create the NFT collection
-     */
-    protected callBuilderMethod(builder: BaseServiceBuilder, specificArgs: z.infer<typeof HederaCreateNftSchema>): Promise<void>;
-    /**
-     * Provides helpful notes for specific field values
-     */
-    protected getNoteForKey(key: string, schemaDefaultValue: unknown, actualValue: unknown): string | undefined;
-    /**
-     * Validates the configuration before execution
-     */
-    protected validateInput(args: z.infer<typeof HederaCreateNftSchema>): Promise<void>;
-}

package/dist/es/tools/hedera/index.d.ts

@@ -1 +0,0 @@
-export { HederaCreateNftTool, HederaCreateNftSchema } from './HederaCreateNftTool';

package/dist/umd/lib/zod-render/__tests__/withRender.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/umd/tools/hedera/HederaCreateNftTool.d.ts

@@ -1,72 +0,0 @@
-import { z } from 'zod';
-import { BaseHederaTransactionTool, BaseServiceBuilder } from 'hedera-agent-kit';
-/**
- * Enhanced NFT creation schema with render configurations
- */
-export declare const HederaCreateNftSchema: import('../..').ZodSchemaWithRender<{
-    tokenName: string;
-    memo?: string | undefined;
-    adminKey?: string | undefined;
-    tokenSymbol?: string | undefined;
-    treasuryAccountId?: string | undefined;
-    kycKey?: string | undefined;
-    freezeKey?: string | undefined;
-    wipeKey?: string | undefined;
-    supplyKey?: string | undefined;
-    feeScheduleKey?: string | undefined;
-    pauseKey?: string | undefined;
-    autoRenewAccountId?: string | undefined;
-    autoRenewPeriod?: number | undefined;
-    freezeDefault?: boolean | undefined;
-    supplyType?: "FINITE" | "INFINITE" | undefined;
-    maxSupply?: string | number | undefined;
-    customFees?: ({
-        type: "FIXED" | "FIXED_FEE";
-        amount: string | number;
-        feeCollectorAccountId?: string | undefined;
-        denominatingTokenId?: string | undefined;
-    } | {
-        type: "FRACTIONAL" | "FRACTIONAL_FEE";
-        numerator: number;
-        denominator: number;
-        feeCollectorAccountId?: string | undefined;
-        minAmount?: string | number | undefined;
-        maxAmount?: string | number | undefined;
-        assessmentMethodInclusive?: boolean | undefined;
-    } | {
-        type: "ROYALTY" | "ROYALTY_FEE";
-        numerator: number;
-        denominator: number;
-        feeCollectorAccountId?: string | undefined;
-        fallbackFee?: {
-            amount: string | number;
-            feeCollectorAccountId?: string | undefined;
-            denominatingTokenId?: string | undefined;
-        } | undefined;
-    })[] | undefined;
-}>;
-/**
- * Hedera Create NFT Tool with enhanced render configurations for form generation
- */
-export declare class HederaCreateNftTool extends BaseHederaTransactionTool<any> {
-    name: string;
-    description: string;
-    specificInputSchema: any;
-    namespace: string;
-    /**
-     * Returns the service builder for HTS operations
-     */
-    protected getServiceBuilder(): BaseServiceBuilder;
-    /**
-     * Calls the builder method to create the NFT collection
-     */
-    protected callBuilderMethod(builder: BaseServiceBuilder, specificArgs: z.infer<typeof HederaCreateNftSchema>): Promise<void>;
-    /**
-     * Provides helpful notes for specific field values
-     */
-    protected getNoteForKey(key: string, schemaDefaultValue: unknown, actualValue: unknown): string | undefined;
-    /**
-     * Validates the configuration before execution
-     */
-    protected validateInput(args: z.infer<typeof HederaCreateNftSchema>): Promise<void>;
-}

package/dist/umd/tools/hedera/index.d.ts

@@ -1 +0,0 @@
-export { HederaCreateNftTool, HederaCreateNftSchema } from './HederaCreateNftTool';