Skip to main content

API Reference

This page summarizes the public HCS-27 surfaces exposed by the Standards SDK family after the draft-alignment work.

Import PathsDirect link to Import Paths​

import {
  HCS27Client,
  type HCS27CheckpointMetadata,
  type HCS27CheckpointMessage,
  type HCS27CheckpointRecord,
  type HCS27CreateCheckpointTopicOptions,
  type HCS27CreateCheckpointTopicResult,
  type HCS27PublishCheckpointResult,
  type HCS27InclusionProof,
  type HCS27ConsistencyProof,
  type HCS27TopicMemo,
} from '@hashgraphonline/standards-sdk';

Client ConstructionDirect link to Client Construction​

new HCS27Client({
  operatorId,
  operatorKey,
  network: 'testnet' | 'mainnet',
  client,
  keyType,
  mirrorNode,
  cdnEndpoint,
  logger,
});
  • client lets you inject an existing @hashgraph/sdk client.
  • cdnEndpoint controls HCS-1 reference resolution for overflow metadata.

Core TypesDirect link to Core Types​

interface HCS27CheckpointMetadata {
  type: 'ans-checkpoint-v1';
  stream: { registry: string; log_id: string };
  log: { alg: string; leaf: string; merkle: string };
  root: { treeSize: string; rootHashB64u: string };
  prev?: { treeSize: string; rootHashB64u: string };
  sig?: { alg: string; kid: string; b64u: string };
}

interface HCS27CheckpointMessage {
  p: 'hcs-27';
  op: 'register';
  metadata: HCS27CheckpointMetadata | string;
  metadata_digest?: { alg: 'sha-256'; b64u: string };
  m?: string;
}

Main Client MethodsDirect link to Main Client Methods​

createCheckpointTopic(options?): Promise<HCS27CreateCheckpointTopicResult>
publishCheckpoint(topicId, metadata, messageMemo?, transactionMemo?): Promise<HCS27PublishCheckpointResult>
registerTopicSubmitKey(topicId, submitKey): void
getCheckpoints(topicId): Promise<HCS27CheckpointRecord[]>
resolveHCS1Reference(reference): Promise<Buffer>
validateCheckpointMessage(message, resolver?): Promise<HCS27CheckpointMetadata>
validateCheckpointChain(records): void
buildTopicMemo(ttl?): string
parseTopicMemo(memo): HCS27TopicMemo | null
buildTransactionMemo(): string
emptyRoot(): Buffer
hashLeaf(...)
hashNode(...)
merkleRootFromEntries(entries): string
merkleRootFromCanonicalEntries(entries): string
verifyInclusionProof(proof): boolean
verifyConsistencyProof(proof): boolean

Topic Key Signing RulesDirect link to Topic Key Signing Rules​

  • createCheckpointTopic(...) accepts topic-key inputs as booleans, private keys, and public key material.
  • true means "reuse operator key" for that topic key.
  • If you pass public key material without a private signer, the SDK only accepts it when the configured operator can satisfy that key at execution time.
  • If the operator cannot satisfy the key, pass a private key signer for that key instead.

Overflow Metadata BehaviorDirect link to Overflow Metadata Behavior​

All three SDKs publish the checkpoint metadata inline when it fits inside the Hedera message payload budget. When it does not fit, they automatically:

  1. Store the metadata as an inscription.
  2. Publish an HCS-27 checkpoint with an hcs://1/<topicId> metadata reference.
  3. Attach a metadata_digest so the resolved bytes can be validated on read.

That means the checkpoint read APIs always return both the raw message and the resolved effectiveMetadata, while resolveHCS1Reference(...) remains available if you need the raw overflow payload yourself.