HOL HCS SDK (Go)

	Go reference implementation of the Hiero Consensus Specifications (HCS) and Registry Broker utilities. 📚 Standards SDK Documentation 📖 Hiero Consensus Specifications Documentation

Quick Start

cd standards-sdk-go
go mod tidy
go test ./...
go vet ./...

Lint:

golangci-lint run

Install

go get github.com/hashgraph-online/standards-sdk-go@latest

CodeSandbox Examples

• Examples index
• HCS-2 create registry
• HCS-5 build mint transaction
• HCS-6 create dynamic registry
• HCS-7 register metadata
• HCS-10 build connection message
• HCS-11 build agent profile
• HCS-12 build register payload
• HCS-14 parse UAID
• HCS-15 build account transaction
• HCS-16 build flora topic transaction
• HCS-17 build state hash message
• HCS-18 build announce message
• HCS-20 deploy points
• HCS-21 build adapter declaration
• HCS-26 parse memos
• HCS-27 publish checkpoint
• Inscriber authenticate + client

Supported Packages

Package	Coverage
pkg/hcs2	HCS-2 registry topic creation, tx builders, indexed entry operations, memo helpers, mirror reads.
pkg/hcs5	HCS-5 Hashinal minting helpers and end-to-end inscribe+mint workflow.
pkg/hcs6	HCS-6 dynamic hashinal non-indexed registry creation, register operations, memo helpers, mirror reads.
pkg/hcs7	HCS-7 indexed registry creation with EVM/WASM config and metadata registration helpers.
pkg/hcs10	HCS-10 topic/message builders, connection operations, registry operations, and message stream reads.
pkg/hcs11	HCS-11 profile models/builders, validation, inscription, account memo updates, and profile resolution.
pkg/hcs12	HCS-12 action/assembly/hashlinks registry topic creation, submit helpers, and mirror entry reads.
pkg/hcs14	HCS-14 UAID generation/parsing plus profile resolution (_uaid, _agent, ANS _ans, and uaid:did base DID reconstruction).
pkg/hcs15	HCS-15 base/petal account creation, tx builders, and petal/base key verification helpers.
pkg/hcs16	HCS-16 flora account + topic management, message builders/senders, and threshold-member key assembly helpers.
pkg/hcs17	HCS-17 state-hash topic/message support, deterministic state hash calculators, and verification helpers.
pkg/hcs18	HCS-18 flora discovery topic creation, discovery message operations, and proposal readiness checks.
pkg/hcs20	HCS-20 auditable points validation, transaction builders, SDK client flows, and mirror-driven state indexing.
pkg/hcs21	HCS-21 adapter registry/declaration publish flows, topic helpers, and signature/digest verification utilities.
pkg/hcs26	HCS-26 memo helpers and resolver flows for discovery, version, and manifest reconstruction.
pkg/hcs27	HCS-27 checkpoint topic creation, publish/retrieval, validation, Merkle/proof helpers.
pkg/inscriber	Inscriber auth flow, websocket-first high-level inscription utilities, quote generation, bulk-files support, registry-broker quote/job helpers, and skill inscription helpers.
pkg/registrybroker	Full Registry Broker client (search, adapters, agents, credits, verification, ledger auth, chat/encryption, feedback, skills).
pkg/mirror	Mirror node client used by HCS and inscriber packages.
pkg/shared	Network normalization, operator env loading, Hedera client/key parsing helpers.

Usage Examples

HCS-2

client, _ := hcs2.NewClient(hcs2.ClientConfig{
	OperatorAccountID:  "0.0.1234",
	OperatorPrivateKey: "<private-key>",
	Network:            "testnet",
})

_, _ = client.CreateRegistry(context.Background(), hcs2.CreateRegistryOptions{
	RegistryType:        hcs2.RegistryTypeIndexed,
	TTL:                 86400,
	UseOperatorAsAdmin:  true,
	UseOperatorAsSubmit: true,
})

HCS-27

client, _ := hcs27.NewClient(hcs27.ClientConfig{
	OperatorAccountID:  "0.0.1234",
	OperatorPrivateKey: "<private-key>",
	Network:            "testnet",
})

metadata := hcs27.CheckpointMetadata{
	Type:   "ans-checkpoint-v1",
	Stream: hcs27.StreamID{Registry: "ans", LogID: "default"},
	Root:   hcs27.RootCommitment{TreeSize: "1", RootHashB64u: "<base64url-root>"},
}

HCS-14

client := hcs14.NewClient(hcs14.ClientOptions{})

result, _ := client.Resolve(
	context.Background(),
	"uaid:aid:ans-godaddy-ote;uid=ans://v1.0.1.ote.agent.cs3p.com;registry=ans;proto=a2a;nativeId=ote.agent.cs3p.com;version=1.0.1",
)

HCS-20

client, _ := hcs20.NewClient(hcs20.ClientConfig{
	OperatorAccountID:  "0.0.1234",
	OperatorPrivateKey: "<private-key>",
	Network:            "testnet",
})

pointsInfo, _ := client.DeployPoints(context.Background(), hcs20.DeployPointsOptions{
	Name: "Loyalty Points",
	Tick: "loyal",
	Max:  "1000000",
})

Inscriber

authClient := inscriber.NewAuthClient("")
authResult, _ := authClient.Authenticate(ctx, accountID, privateKey, inscriber.NetworkTestnet)

client, _ := inscriber.NewClient(inscriber.Config{
	APIKey:  authResult.APIKey,
	Network: inscriber.NetworkTestnet,
})

Registry Broker

client, _ := registrybroker.NewRegistryBrokerClient(registrybroker.RegistryBrokerClientOptions{
	APIKey:  "<registry-broker-api-key>",
	BaseURL: "https://hol.org/registry/api/v1",
})

_, _ = client.Stats(context.Background())

Registry Broker skill domain proof

status, _ := client.GetSkillVerificationStatusWithOptions(
	context.Background(),
	"demo-skill",
	registrybroker.SkillVerificationStatusOptions{Version: "1.0.0"},
)

challenge, _ := client.CreateSkillDomainProofChallenge(
	context.Background(),
	registrybroker.SkillVerificationDomainProofChallengeRequest{
		Name:    "demo-skill",
		Version: "1.0.0",
		Domain:  "example.com",
	},
)

_, _ = client.VerifySkillDomainProof(
	context.Background(),
	registrybroker.SkillVerificationDomainProofVerifyRequest{
		Name:           "demo-skill",
		Version:        "1.0.0",
		Domain:         "example.com",
		ChallengeToken: "<token-from-dns-txt-record>",
	},
)

_ = status
_ = challenge

Runnable example: go run ./examples/registry-broker-skill-domain-proof.

Environment Variables

Common:

• HEDERA_ACCOUNT_ID
• HEDERA_PRIVATE_KEY
• HEDERA_NETWORK
• aliases also supported: HEDERA_OPERATOR_ID/HEDERA_OPERATOR_KEY, OPERATOR_ID/OPERATOR_KEY, ACCOUNT_ID/PRIVATE_KEY

Network-scoped overrides (pkg/shared):

• TESTNET_HEDERA_ACCOUNT_ID
• TESTNET_HEDERA_PRIVATE_KEY
• MAINNET_HEDERA_ACCOUNT_ID
• MAINNET_HEDERA_PRIVATE_KEY
• aliases also supported: TESTNET_HEDERA_OPERATOR_ID/TESTNET_HEDERA_OPERATOR_KEY, MAINNET_HEDERA_OPERATOR_ID/MAINNET_HEDERA_OPERATOR_KEY

The SDK auto-loads .env from the current working directory or ancestor directories before resolving credentials.

Inscriber integration:

• RUN_INTEGRATION=1
• RUN_INSCRIBER_INTEGRATION=1
• INSCRIPTION_AUTH_BASE_URL (optional)
• INSCRIPTION_API_BASE_URL (optional)
• INSCRIBER_HEDERA_NETWORK (optional; defaults to testnet)

Registry Broker integration:

• RUN_INTEGRATION=1
• RUN_REGISTRY_BROKER_INTEGRATION=1
• REGISTRY_BROKER_API_KEY
• REGISTRY_BROKER_BASE_URL (optional)

Tests

All packages:

go test ./...

Live HCS + Inscriber integration (no mocks):

RUN_INTEGRATION=1 \
RUN_INSCRIBER_INTEGRATION=1 \
go test -v ./pkg/hcs2 ./pkg/hcs27 ./pkg/inscriber

Live HCS-15 integration (base/petal account flow):

RUN_INTEGRATION=1 \
go test -v ./pkg/hcs15 -run TestHCS15Integration_CreateBaseAndPetalAccounts

Live HCS-16 integration (flora + topic/message flow):

RUN_INTEGRATION=1 \
go test -v ./pkg/hcs16 -run TestHCS16Integration_CreateFloraAndPublishMessages

Live HCS-17 integration (compute + publish state hash):

RUN_INTEGRATION=1 \
go test -v ./pkg/hcs17 -run TestHCS17Integration_ComputeAndPublishStateHash

Live HCS-20 integration (deploy + register + mint/transfer/burn + indexing):

RUN_INTEGRATION=1 \
go test -v ./pkg/hcs20 -run TestHCS20Integration_EndToEnd

Live high-level inscriber utilities (websocket default + bulk-files quote):

RUN_INTEGRATION=1 \
RUN_INSCRIBER_INTEGRATION=1 \
go test -v ./pkg/inscriber -run 'TestInscriberIntegration_(HighLevelInscribe_DefaultWebSocket|GenerateQuote_BulkFiles)'

Live Registry Broker skill inscription utility:

RUN_INTEGRATION=1 \
RUN_REGISTRY_BROKER_INTEGRATION=1 \
REGISTRY_BROKER_API_KEY=<api-key> \
go test -v ./pkg/inscriber -run TestInscriberIntegration_RegistryBrokerSkillInscribe

Live HCS-5 mint integration (requires target NFT token and supply key):

RUN_INTEGRATION=1 \
HCS5_INTEGRATION_TOKEN_ID=<token-id> \
HCS5_INTEGRATION_SUPPLY_KEY=<private-key> \
go test -v ./pkg/hcs5 -run TestHCS5Integration_MintWithExistingHCS1Topic

Live HCS-11 profile lookup integration:

RUN_INTEGRATION=1 \
HCS11_INTEGRATION_ACCOUNT_ID=<account-id> \
HCS11_INTEGRATION_NETWORK=testnet \
go test -v ./pkg/hcs11 -run TestHCS11Integration_FetchProfileByAccountID

Live HCS-14 integration (DNS/Web resolution):

RUN_INTEGRATION=1 \
go test -v ./pkg/hcs14 -run TestHCS14Integration_ANSDNSWebResolution

Live Registry Broker integration:

RUN_INTEGRATION=1 \
RUN_REGISTRY_BROKER_INTEGRATION=1 \
REGISTRY_BROKER_API_KEY=<api-key> \
go test -v ./pkg/registrybroker

Contributing

Please read CONTRIBUTING.md and CODE_OF_CONDUCT.md before contributing.

Security

For security concerns, see SECURITY.md.

Maintainers

See MAINTAINERS.md.

Resources

• Hiero Consensus Specifications (HCS) Documentation
• Hedera Documentation
• Telegram Community

📝 Blog Tutorials

• Building a Decentralized Registry with Go & HCS-2
• Universal Agent Discovery with MCP
• Discovering Virtuals Agents with Registry Broker
• Creating Reactive Service Agents
• End-to-End Encrypted Agent Communication

License

Apache-2.0