HcsFileService Guide

The @hiero-did-sdk/hcs package provides the HcsFileService — a service for managing file storage on Hedera Consensus Service (HCS) topics using the HCS-1 standard, which supports chunked file uploads with compression.

Overview

HcsFileService allows developers to:

Submit files (potentially large, chunked, and compressed) to Hedera topics.
Resolve and reconstruct files previously submitted to HCS topics.
Handle automatic compression and decompression using Zstandard.
Verify file integrity through memo-based checksum validation.
Integrate with caching to optimize file retrieval.

Initialization

constructor(client: Client, cache?: CacheConfig | Cache | HcsCacheService)

Instantiate a new HcsFileService.

client: Hedera SDK client instance used for network operations.
cache: Optional cache config or instance to support caching resolved files.

Basic Usage

Submitting a File

const fileService = new HcsFileService(client, cache);

const topicId = await fileService.submitFile({
  payload: Buffer.from('Large file content here'),
  submitKey: submitPrivateKey, // Signing key for transactions
  waitForChangesVisibility: true, // Wait until file is visible on the network
  waitForChangesVisibilityTimeoutMs: 60000 // Milliseconds to wait for visibility confirmation
});

console.log("File submitted to topic:", topicId);

Parameters:

payload (Buffer, required): The file content to submit.
submitKey (PrivateKey, required): Key to sign each chunk submission transaction.
waitForChangesVisibility (boolean, optional): Wait for full file visibility after submission.
waitForChangesVisibilityTimeoutMs (number, optional): Timeout in milliseconds to wait.

Returns the Hedera topic ID (string) where the file was submitted.

Resolving a File

const fileBuffer = await fileService.resolveFile({
  topicId: "0.0.1234"
});

console.log("Resolved file contents:", fileBuffer.toString());