HederaHcsService Guide

The @hiero-did-sdk/hcs package provides powerful tools and services for interacting with Hedera Consensus Service (HCS) topics and messages. The package also implements support for the HCS-1 standard for file storage based on the Hedera ledger.

Overview

Use @hiero-did-sdk/hcs to:

Create, update, and delete HCS topics.
Publish and retrieve messages in HCS topics.
Store and retrieve files using Hedera Consensus Service file abstraction (HCS-1 standard).
Integrate caching and efficient retrieval for topic metadata and info.

Package Architecture

HederaHcsService - A service wrapper providing a convenient API for integration with the Hedera Consensus Service (HCS).
HcsTopicService - A service for managing HCS Topics.
HcsMessageService - A service for submitting and resolving HCS messages.
HcsFileService - A service creating and resolving files on HCS according to HCS-1 standard.
HcsCacheService - A service providing data caching functionality.

Initialization

HederaHcsService accepts the following parameters:

networks: NetworkConfig[]; - Network configuration for initialization.
cache?: CacheConfig | Cache; - Cache service parameters for initializing HcsCacheService.

Network option

export const HEDERA_NETWORKS = ['mainnet', 'testnet', 'previewnet', 'local-node'] as const;

export type HederaNetwork = (typeof HEDERA_NETWORKS)[number];

export type HederaCustomNetwork = {
  name: string;
  nodes: {
    [key: string]: string | AccountId;
  };
  mirrorNodes?: string | string[] | undefined;
};

export interface NetworkConfig {
  network: HederaNetwork | HederaCustomNetwork;
  operatorId: string;
  operatorKey: string;
}

export interface HederaClientConfiguration {
  networks: NetworkConfig[];
}

Networks configuration described in the Client API Reference

Cache option

export type CacheConfig = {
  maxSize: number;
};

export interface Cache {
  get<CacheValue>(key: string): Promise<CacheValue | null>;
  set<CacheValue>(key: string, value: CacheValue, expiresInSeconds?: number): Promise<void>;
  remove(key: string): Promise<void>;
  clear(): Promise<void>;
  cleanupExpired(): Promise<void>;
}

When initializing the cache, you can either use an external cache that implements the interface described in the Core API Reference, or create a cache by specifying the maximum number of elements maxSize. In this case, the network configuration described in the LRU Cache guide will be used.

Example

const options = {
    networks: [
        { network: 'testnet', operatorId, operatorKey  },
        { network: 'local-node', operatorId, operatorKey  },
        {
          network: {
            name: 'custom-network',
            nodes: {
              'https://testnet-node00-00-grpc.hedera.com:443': new AccountId(3),
            },
          },
          operatorId,
          operatorKey,
        },
    ],
    cache: { maxSize: 100 }
}

Basic Usage

Creating a Topic

import { HederaHcsService } from '@hiero-did-sdk/hcs';

const hcsService = new HederaHcsService({
  networks: [
    { 'testnet', operatorId, operatorKey },
  ],
  cache: { maxSize: 100 },
});

const topic = await hcsService.createTopic({
  networkName: 'testnet',
  topicMemo: "Topic Memo",
  waitForChangesVisibility: true,
});

console.log(topic);

Updating a Topic

import { HederaHcsService } from '@hiero-did-sdk/hcs';

const hcsService = new HederaHcsService({
  networks: [
    { 'testnet', operatorId, operatorKey },
  ],
  cache: { maxSize: 100 },
});

const topic = await hcsService.updateTopic({
  networkName: 'testnet',
  topicMemo: "New Topic Memo",
  waitForChangesVisibility: true,
});

console.log(topic);

Deleting a Topic

import { HederaHcsService } from '@hiero-did-sdk/hcs';

const hcsService = new HederaHcsService({
  networks: [
    { 'testnet', operatorId, operatorKey },
  ],
  cache: { maxSize: 100 },
});

const topic = await hcsService.deleteTopic({
  topicId,
  currentAdminKey: PrivateKey.fromStringDer(operatorKey),
  waitForChangesVisibility: true,
});

console.log(topic);

Fetching Topic Info

import { HederaHcsService } from '@hiero-did-sdk/hcs';

const hcsService = new HederaHcsService({
  networks: [
    { 'testnet', operatorId, operatorKey },
  ],
  cache: { maxSize: 100 },
});

const topic = await hcsService.getTopicInfo({
  topicId: "0.0.123"
});

console.log(topic);

Publishing Messages

import { HederaHcsService } from '@hiero-did-sdk/hcs';

const hcsService = new HederaHcsService({
  networks: [
    { 'testnet', operatorId, operatorKey },
  ],
  cache: { maxSize: 100 },
});

const topic = await hcsService.submitMessage({
  networkName: 'testnet',
  topicId: 'topicId',
  message: 'message',
});

console.log(topic);

Fetching Topic Messages

import { HederaHcsService } from '@hiero-did-sdk/hcs';

const hcsService = new HederaHcsService({
  networks: [
    { 'testnet', operatorId, operatorKey },
  ],
  cache: { maxSize: 100 },
});

const topic = await hcsService.getTopicMessages({
  networkName: 'testnet',
  topicId: '0.0.123'
});

console.log(topic);

Storing Files

import { HederaHcsService } from '@hiero-did-sdk/hcs';

const hcsService = new HederaHcsService({
  networks: [
    { 'testnet', operatorId, operatorKey }
  ],
  cache: { maxSize: 100 },
});

const topic = await hcsService.submitFile({
  payload: Buffer.from('This is a test content'),
  submitKey: PrivateKey.generate(),
  waitForChangesVisibility: true,
});

console.log(topic);

Resolving Files

import { HederaHcsService } from '@hiero-did-sdk/hcs';

const hcsService = new HederaHcsService({
  networks: [
    { 'testnet', operatorId, operatorKey },
  ],
  cache: { maxSize: 100 },
});

const topic = await hcsService.resolveFile({ topicId: '0.0.123' };

console.log(topic);