Server Client

The server client uses direct Hedera operator credentials to create checkpoint topics and publish checkpoint commitments.

Create a Client

TypeScript

// HCS-27 TypeScript support is not yet available.
// Coming soon to @hashgraphonline/standards-sdk.

Go

import "github.com/hashgraph-online/standards-sdk-go/pkg/hcs27"

client, err := hcs27.NewClient(hcs27.ClientConfig{
	OperatorAccountID:  os.Getenv("HEDERA_ACCOUNT_ID"),
	OperatorPrivateKey: os.Getenv("HEDERA_PRIVATE_KEY"),
	Network:            "testnet",
})
if err != nil {
	log.Fatal(err)
}

Create a Checkpoint Topic

TypeScript

// Not yet available.

Go

topicID, txID, err := client.CreateCheckpointTopic(ctx, hcs27.CreateTopicOptions{
	TTLSeconds:          86400,
	UseOperatorAsAdmin:  true,
	UseOperatorAsSubmit: true,
})
if err != nil {
	log.Fatal(err)
}
fmt.Printf("Created checkpoint topic: %s (tx: %s)\n", topicID, txID)

Publish a Checkpoint

TypeScript

// Not yet available.

Go

metadata := hcs27.CheckpointMetadata{
	Type:   "ans-checkpoint-v1",
	Stream: hcs27.StreamID{Registry: "my-app", LogID: "events"},
	Log: &hcs27.LogProfile{
		Algorithm: "sha-256",
		Leaf:      "rfc6962-leaf",
		Merkle:    "rfc6962-node",
	},
	Root: hcs27.RootCommitment{
		TreeSize:    150,
		RootHashB64: "8zVIY3QJBOdTYR8dnLOzedEfym4Jl7f1xy8pciLEMew",
	},
	Previous: &hcs27.PreviousCommitment{
		TreeSize:    100,
		RootHashB64: "kZ4L2bPe1sX...",
	},
	BatchRange: hcs27.BatchRange{Start: 101, End: 150},
}

result, err := client.PublishCheckpoint(ctx, topicID, metadata, "batch 101-150", "")
if err != nil {
	log.Fatal(err)
}
fmt.Printf("Published checkpoint (seq: %d, tx: %s)\n", result.SequenceNumber, result.TransactionID)

Notes

• If the serialized checkpoint exceeds 1024 bytes, the SDK automatically publishes the metadata via HCS-1 and replaces the inline payload with an hcs://1/<topicId> reference plus a metadata_digest for integrity verification.
• The message memo field must be under 300 characters.

Retrieve Checkpoints

TypeScript

// Not yet available.

Go

records, err := client.GetCheckpoints(ctx, topicID, nil)
if err != nil {
	log.Fatal(err)
}

for _, record := range records {
	fmt.Printf("Seq %d: root=%s treeSize=%d\n",
		record.Sequence,
		record.EffectiveMetadata.Root.RootHashB64,
		record.EffectiveMetadata.Root.TreeSize,
	)
}

Validate a Checkpoint Chain

TypeScript

// Not yet available.

Go

if err := hcs27.ValidateCheckpointChain(records); err != nil {
	log.Fatalf("Chain validation failed: %v", err)
}
fmt.Println("Checkpoint chain is valid")

Resolve HCS-1 References

When checkpoint metadata overflows, the SDK stores it via HCS-1. You can resolve references manually:

TypeScript

// Not yet available.

Go

payload, err := client.ResolveHCS1Reference(ctx, "hcs://1/0.0.789012")
if err != nil {
	log.Fatal(err)
}
fmt.Printf("Resolved %d bytes of metadata\n", len(payload))