@hashgraphonline/standards-agent-kit 0.2.101 → 0.2.103

package/src/tools/hcs2/UpdateEntryTool.ts

@@ -0,0 +1,68 @@
+import { z } from 'zod';
+import { BaseHCS2QueryTool } from './base-hcs2-tools';
+import { CallbackManagerForToolRun } from '@langchain/core/callbacks/manager';
+
+/**
+ * Schema for updating an entry in HCS-2
+ */
+const updateEntrySchema = z.object({
+  registryTopicId: z
+    .string()
+    .regex(/^\d+\.\d+\.\d+$/)
+    .describe('The HCS-2 registry topic ID (must be indexed)'),
+  targetTopicId: z
+    .string()
+    .regex(/^\d+\.\d+\.\d+$/)
+    .describe('The new topic ID to point to'),
+  uid: z
+    .string()
+    .describe('The unique ID of the entry to update'),
+  metadata: z
+    .string()
+    .optional()
+    .describe('Optional metadata URI (HIP-412 format)'),
+  memo: z
+    .string()
+    .max(500)
+    .optional()
+    .describe('Optional memo (max 500 characters)'),
+});
+
+
+/**
+ * Tool for updating entries in HCS-2 registries
+ */
+export class UpdateEntryTool extends BaseHCS2QueryTool<typeof updateEntrySchema> {
+  name = 'updateHCS2Entry';
+  description = 'Update an existing entry in an indexed HCS-2 registry';
+
+  get specificInputSchema() {
+    return updateEntrySchema;
+  }
+
+  protected async executeQuery(
+    params: z.infer<typeof updateEntrySchema>,
+    _runManager?: CallbackManagerForToolRun
+  ): Promise<unknown> {
+    try {
+      const result = await this.hcs2Builder.updateEntry(
+        params.registryTopicId,
+        {
+          targetTopicId: params.targetTopicId,
+          uid: params.uid,
+          metadata: params.metadata,
+          memo: params.memo,
+        }
+      );
+
+      if (!result.success) {
+        throw new Error(result.error || 'Failed to update entry');
+      }
+
+      return `Successfully updated entry in HCS-2 registry!\n\nRegistry Topic: ${params.registryTopicId}\nUID: ${params.uid}\nNew Target Topic ID: ${params.targetTopicId}${params.metadata ? `\nMetadata: ${params.metadata}` : ''}${params.memo ? `\nMemo: ${params.memo}` : ''}\n\nThe entry has been updated in the registry.`;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Failed to update entry';
+      throw new Error(`Entry update failed: ${errorMessage}`);
+    }
+  }
+}

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

@@ -0,0 +1,65 @@
+import {
+  BaseHederaTransactionTool,
+  BaseHederaQueryTool,
+  BaseServiceBuilder,
+} from 'hedera-agent-kit';
+import { HCS2Builder } from '../../builders/hcs2/hcs2-builder';
+import {
+  HCS2TransactionToolParams,
+  HCS2QueryToolParams,
+} from './hcs2-tool-params';
+import { z } from 'zod';
+
+/**
+ * Base class for HCS2 transaction tools
+ */
+export abstract class BaseHCS2TransactionTool<
+  T extends z.ZodObject<
+    z.ZodRawShape,
+    z.UnknownKeysParam,
+    z.ZodTypeAny
+  > = z.ZodObject<z.ZodRawShape>
+> extends BaseHederaTransactionTool<T> {
+  protected hcs2Builder: HCS2Builder;
+  namespace = 'hcs2' as const;
+
+  constructor(params: HCS2TransactionToolParams) {
+    super(params);
+    this.hcs2Builder = params.hcs2Builder;
+  }
+
+  /**
+   * Override to return the HCS2Builder
+   */
+  protected getServiceBuilder(): BaseServiceBuilder {
+    return this.hcs2Builder;
+  }
+}
+
+/**
+ * Base class for HCS2 query tools
+ */
+export abstract class BaseHCS2QueryTool<
+  T extends z.ZodObject<
+    z.ZodRawShape,
+    z.UnknownKeysParam,
+    z.ZodTypeAny,
+    Record<string, unknown>,
+    Record<string, unknown>
+  > = z.ZodObject<z.ZodRawShape>
+> extends BaseHederaQueryTool<T> {
+  protected hcs2Builder: HCS2Builder;
+  namespace = 'hcs2' as const;
+
+  constructor(params: HCS2QueryToolParams) {
+    super(params);
+    this.hcs2Builder = params.hcs2Builder;
+  }
+
+  /**
+   * Override to return the HCS2Builder
+   */
+  protected getServiceBuilder(): BaseServiceBuilder {
+    return this.hcs2Builder;
+  }
+}

package/src/tools/hcs2/hcs2-tool-params.ts

@@ -0,0 +1,21 @@
+import { HederaAgentKit } from 'hedera-agent-kit';
+import type { BasePluginContext } from 'hedera-agent-kit';
+import { HCS2Builder } from '../../builders/hcs2/hcs2-builder';
+
+/**
+ * Parameters for HCS2 transaction tools
+ */
+export interface HCS2TransactionToolParams {
+  hederaKit: HederaAgentKit;
+  hcs2Builder: HCS2Builder;
+  logger?: BasePluginContext['logger'];
+}
+
+/**
+ * Parameters for HCS2 query tools
+ */
+export interface HCS2QueryToolParams {
+  hederaKit: HederaAgentKit;
+  hcs2Builder: HCS2Builder;
+  logger?: BasePluginContext['logger'];
+}

package/src/tools/hcs2/index.ts

@@ -0,0 +1,8 @@
+export * from './base-hcs2-tools';
+export * from './hcs2-tool-params';
+export * from './CreateRegistryTool';
+export * from './RegisterEntryTool';
+export * from './UpdateEntryTool';
+export * from './DeleteEntryTool';
+export * from './MigrateRegistryTool';
+export * from './QueryRegistryTool';

package/src/tools/index.ts

@@ -1,2 +1,3 @@
-// Export all HCS10 tools from the subdirectory
-export * from './hcs10';
+export * from './hcs10';
+export * from './hcs2';
+export * from './inscriber';

package/src/tools/inscriber/InscribeFromBufferTool.ts

@@ -0,0 +1,105 @@
+import { z } from 'zod';
+import { BaseInscriberQueryTool } from './base-inscriber-tools';
+import { InscriptionOptions } from '@hashgraphonline/standards-sdk';
+import { CallbackManagerForToolRun } from '@langchain/core/callbacks/manager';
+
+/**
+ * Schema for inscribing from buffer
+ */
+const inscribeFromBufferSchema = z.object({
+  base64Data: z.string().describe('Base64 encoded content to inscribe'),
+  fileName: z.string().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'),
+  apiKey: z
+    .string()
+    .optional()
+    .describe('API key for inscription service'),
+});
+
+
+/**
+ * Tool for inscribing content from buffer
+ */
+export class InscribeFromBufferTool extends BaseInscriberQueryTool<typeof inscribeFromBufferSchema> {
+  name = 'inscribeFromBuffer';
+  description = 'Inscribe content from a buffer/base64 data to the Hedera network';
+
+  get specificInputSchema() {
+    return inscribeFromBufferSchema;
+  }
+
+  protected async executeQuery(
+    params: z.infer<typeof inscribeFromBufferSchema>,
+    _runManager?: CallbackManagerForToolRun
+  ): Promise<unknown> {
+    const buffer = Buffer.from(params.base64Data, 'base64');
+
+    const options: InscriptionOptions = {
+      mode: params.mode,
+      metadata: params.metadata,
+      tags: params.tags,
+      chunkSize: params.chunkSize,
+      waitForConfirmation: params.waitForConfirmation ?? true,
+      waitMaxAttempts: 10,
+      waitIntervalMs: 3000,
+      apiKey: params.apiKey,
+      network: this.inscriberBuilder['hederaKit'].client.network.toString().includes('mainnet') ? 'mainnet' : 'testnet',
+    };
+
+    try {
+      const timeoutPromise = new Promise((_, reject) => {
+        setTimeout(() => reject(new Error('Inscription timed out after 30 seconds')), 30000);
+      });
+
+      const result = await Promise.race([
+        this.inscriberBuilder.inscribe(
+          {
+            type: 'buffer',
+            buffer,
+            fileName: params.fileName,
+            mimeType: params.mimeType,
+          },
+          options
+        ),
+        timeoutPromise
+      ]) as any;
+
+      if (result.confirmed) {
+        const topicId = result.inscription?.topic_id || result.result.topicId;
+        const network = options.network || 'testnet';
+        const cdnUrl = topicId ? `https://kiloscribe.com/api/inscription-cdn/${topicId}?network=${network}` : null;
+        return `Successfully inscribed and confirmed content on the Hedera network!\n\nTransaction ID: ${result.result.transactionId}\nTopic ID: ${topicId || 'N/A'}${cdnUrl ? `\nView inscription: ${cdnUrl}` : ''}\n\nThe inscription is now available.`;
+      } else {
+        return `Successfully submitted inscription to the Hedera network!\n\nTransaction ID: ${result.result.transactionId}\n\nThe inscription is processing and will be confirmed shortly.`;
+      }
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Failed to inscribe from buffer';
+      throw new Error(`Inscription failed: ${errorMessage}`);
+    }
+  }
+}

package/src/tools/inscriber/InscribeFromFileTool.ts

@@ -0,0 +1,93 @@
+import { z } from 'zod';
+import { BaseInscriberQueryTool } from './base-inscriber-tools';
+import { InscriptionOptions } from '@hashgraphonline/standards-sdk';
+import { CallbackManagerForToolRun } from '@langchain/core/callbacks/manager';
+
+/**
+ * Schema for inscribing from file
+ */
+const inscribeFromFileSchema = z.object({
+  filePath: z.string().describe('The file path of the content to inscribe'),
+  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'),
+  apiKey: z
+    .string()
+    .optional()
+    .describe('API key for inscription service'),
+});
+
+
+/**
+ * Tool for inscribing content from file
+ */
+export class InscribeFromFileTool extends BaseInscriberQueryTool<typeof inscribeFromFileSchema> {
+  name = 'inscribeFromFile';
+  description = 'Inscribe content from a local file to the Hedera network';
+
+  get specificInputSchema() {
+    return inscribeFromFileSchema;
+  }
+
+  protected async executeQuery(
+    params: z.infer<typeof inscribeFromFileSchema>,
+    _runManager?: CallbackManagerForToolRun
+  ): Promise<unknown> {
+    const options: InscriptionOptions = {
+      mode: params.mode,
+      metadata: params.metadata,
+      tags: params.tags,
+      chunkSize: params.chunkSize,
+      waitForConfirmation: params.waitForConfirmation ?? true,
+      waitMaxAttempts: 10,
+      waitIntervalMs: 3000,
+      apiKey: params.apiKey,
+      network: this.inscriberBuilder['hederaKit'].client.network.toString().includes('mainnet') ? 'mainnet' : 'testnet',
+    };
+
+    try {
+      const timeoutPromise = new Promise((_, reject) => {
+        setTimeout(() => reject(new Error('Inscription timed out after 30 seconds')), 30000);
+      });
+
+      const result = await Promise.race([
+        this.inscriberBuilder.inscribe(
+          { type: 'file', path: params.filePath },
+          options
+        ),
+        timeoutPromise
+      ]) as any;
+
+      if (result.confirmed) {
+        const topicId = result.inscription?.topic_id || result.result.topicId;
+        const network = options.network || 'testnet';
+        const cdnUrl = topicId ? `https://kiloscribe.com/api/inscription-cdn/${topicId}?network=${network}` : null;
+        return `Successfully inscribed and confirmed content on the Hedera network!\n\nTransaction ID: ${result.result.transactionId}\nTopic ID: ${topicId || 'N/A'}${cdnUrl ? `\nView inscription: ${cdnUrl}` : ''}\n\nThe inscription is now available.`;
+      } else {
+        return `Successfully submitted inscription to the Hedera network!\n\nTransaction ID: ${result.result.transactionId}\n\nThe inscription is processing and will be confirmed shortly.`;
+      }
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Failed to inscribe from file';
+      throw new Error(`Inscription failed: ${errorMessage}`);
+    }
+  }
+}

package/src/tools/inscriber/InscribeFromUrlTool.ts

@@ -0,0 +1,93 @@
+import { z } from 'zod';
+import { BaseInscriberQueryTool } from './base-inscriber-tools';
+import { InscriptionOptions } from '@hashgraphonline/standards-sdk';
+import { CallbackManagerForToolRun } from '@langchain/core/callbacks/manager';
+
+/**
+ * Schema for inscribing from URL
+ */
+const inscribeFromUrlSchema = z.object({
+  url: z.string().url().describe('The URL of the content to inscribe'),
+  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'),
+  apiKey: z
+    .string()
+    .optional()
+    .describe('API key for inscription service'),
+});
+
+
+/**
+ * Tool for inscribing content from URL
+ */
+export class InscribeFromUrlTool extends BaseInscriberQueryTool<typeof inscribeFromUrlSchema> {
+  name = 'inscribeFromUrl';
+  description = 'Inscribe content from a URL to the Hedera network';
+
+  get specificInputSchema() {
+    return inscribeFromUrlSchema;
+  }
+
+  protected async executeQuery(
+    params: z.infer<typeof inscribeFromUrlSchema>,
+    _runManager?: CallbackManagerForToolRun
+  ): Promise<unknown> {
+    const options: InscriptionOptions = {
+      mode: params.mode,
+      metadata: params.metadata,
+      tags: params.tags,
+      chunkSize: params.chunkSize,
+      waitForConfirmation: params.waitForConfirmation ?? true,
+      waitMaxAttempts: 10,
+      waitIntervalMs: 3000,
+      apiKey: params.apiKey,
+      network: this.inscriberBuilder['hederaKit'].client.network.toString().includes('mainnet') ? 'mainnet' : 'testnet',
+    };
+
+    try {
+      const timeoutPromise = new Promise((_, reject) => {
+        setTimeout(() => reject(new Error('Inscription timed out after 30 seconds')), 30000);
+      });
+
+      const result = await Promise.race([
+        this.inscriberBuilder.inscribe(
+          { type: 'url', url: params.url },
+          options
+        ),
+        timeoutPromise
+      ]) as any;
+
+      if (result.confirmed) {
+        const topicId = result.inscription?.topic_id || result.result.topicId;
+        const network = options.network || 'testnet';
+        const cdnUrl = topicId ? `https://kiloscribe.com/api/inscription-cdn/${topicId}?network=${network}` : null;
+        return `Successfully inscribed and confirmed content on the Hedera network!\n\nTransaction ID: ${result.result.transactionId}\nTopic ID: ${topicId || 'N/A'}${cdnUrl ? `\nView inscription: ${cdnUrl}` : ''}\n\nThe inscription is now available.`;
+      } else {
+        return `Successfully submitted inscription to the Hedera network!\n\nTransaction ID: ${result.result.transactionId}\n\nThe inscription is processing and will be confirmed shortly.`;
+      }
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Failed to inscribe from URL';
+      throw new Error(`Inscription failed: ${errorMessage}`);
+    }
+  }
+}

package/src/tools/inscriber/InscribeHashinalTool.ts

@@ -0,0 +1,117 @@
+import { z } from 'zod';
+import { BaseInscriberQueryTool } from './base-inscriber-tools';
+import { InscriptionOptions } from '@hashgraphonline/standards-sdk';
+import { CallbackManagerForToolRun } from '@langchain/core/callbacks/manager';
+
+/**
+ * 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")'),
+  attributes: z
+    .array(
+      z.object({
+        trait_type: z.string(),
+        value: z.union([z.string(), z.number()]),
+      })
+    )
+    .optional()
+    .describe('NFT attributes'),
+  properties: z
+    .record(z.unknown())
+    .optional()
+    .describe('Additional properties'),
+  jsonFileURL: z
+    .string()
+    .url()
+    .optional()
+    .describe('URL to JSON metadata file'),
+  tags: z
+    .array(z.string())
+    .optional()
+    .describe('Tags to categorize the NFT'),
+  chunkSize: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe('Chunk size for large files'),
+  waitForConfirmation: z
+    .boolean()
+    .optional()
+    .describe('Whether to wait for inscription confirmation'),
+  apiKey: z
+    .string()
+    .optional()
+    .describe('API key for inscription service'),
+});
+
+
+/**
+ * Tool for inscribing Hashinal NFTs
+ */
+export class InscribeHashinalTool extends BaseInscriberQueryTool<typeof inscribeHashinalSchema> {
+  name = 'inscribeHashinal';
+  description = 'Inscribe content as a Hashinal NFT on the Hedera network';
+
+  get specificInputSchema() {
+    return inscribeHashinalSchema;
+  }
+
+  protected async executeQuery(
+    params: z.infer<typeof inscribeHashinalSchema>,
+    _runManager?: CallbackManagerForToolRun
+  ): Promise<unknown> {
+    const metadata = {
+      name: params.name,
+      creator: params.creator,
+      description: params.description,
+      type: params.type,
+      attributes: params.attributes,
+      properties: params.properties,
+    };
+
+    const options: InscriptionOptions = {
+      mode: 'hashinal',
+      metadata,
+      jsonFileURL: params.jsonFileURL,
+      tags: params.tags,
+      chunkSize: params.chunkSize,
+      waitForConfirmation: params.waitForConfirmation ?? true,
+      waitMaxAttempts: 10,
+      waitIntervalMs: 3000,
+      apiKey: params.apiKey,
+      network: this.inscriberBuilder['hederaKit'].client.network.toString().includes('mainnet') ? 'mainnet' : 'testnet',
+    };
+
+    try {
+      const timeoutPromise = new Promise((_, reject) => {
+        setTimeout(() => reject(new Error('Inscription timed out after 30 seconds')), 30000);
+      });
+
+      const result = await Promise.race([
+        this.inscriberBuilder.inscribe(
+          { type: 'url', url: params.url },
+          options
+        ),
+        timeoutPromise
+      ]) as any;
+
+      if (result.confirmed) {
+        const topicId = result.inscription?.topic_id || result.result.topicId;
+        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.transactionId}\nTopic ID: ${topicId || 'N/A'}${cdnUrl ? `\nView inscription: ${cdnUrl}` : ''}\n\nThe Hashinal NFT is now available.`;
+      } else {
+        return `Successfully submitted Hashinal NFT inscription to the Hedera network!\n\nTransaction ID: ${result.result.transactionId}\n\nThe inscription is processing and will be confirmed shortly.`;
+      }
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Failed to inscribe Hashinal NFT';
+      throw new Error(`Inscription failed: ${errorMessage}`);
+    }
+  }
+}

package/src/tools/inscriber/RetrieveInscriptionTool.ts

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+import { BaseInscriberQueryTool } from './base-inscriber-tools';
+import { CallbackManagerForToolRun } from '@langchain/core/callbacks/manager';
+
+/**
+ * Schema for retrieving inscription
+ */
+const retrieveInscriptionSchema = z.object({
+  transactionId: z
+    .string()
+    .describe('The transaction ID of the inscription to retrieve'),
+  apiKey: z
+    .string()
+    .optional()
+    .describe('API key for inscription service'),
+});
+
+
+/**
+ * Tool for retrieving inscriptions
+ */
+export class RetrieveInscriptionTool extends BaseInscriberQueryTool<typeof retrieveInscriptionSchema> {
+  name = 'retrieveInscription';
+  description = 'Retrieve details of an existing inscription from the Hedera network';
+
+  get specificInputSchema() {
+    return retrieveInscriptionSchema;
+  }
+
+  protected async executeQuery(
+    params: z.infer<typeof retrieveInscriptionSchema>,
+    _runManager?: CallbackManagerForToolRun
+  ): Promise<unknown> {
+    const result = await this.inscriberBuilder.retrieveInscription(
+      params.transactionId,
+      {
+        apiKey: params.apiKey,
+        network: this.inscriberBuilder['hederaKit'].client.network.toString().includes('mainnet') ? 'mainnet' : 'testnet',
+      }
+    );
+
+    return {
+      inscriptionId: (result as any).inscriptionId,
+      transactionId: result.transactionId,
+      topicId: (result as any).topic_id,
+      status: result.status,
+      holderId: (result as any).holderId,
+      metadata: result.metadata,
+      tags: (result as any).tags,
+      mode: result.mode,
+      chunks: (result as any).chunks,
+      createdAt: (result as any).createdAt,
+      completedAt: (result as any).completed || (result as any).completedAt,
+      fileUrl: result.fileUrl,
+      mimeType: (result as any).mimeType,
+      fileSize: (result as any).fileSize,
+    };
+  }
+}