**Hedera Consensus Service (HCS)**는 모든 애플리케이션이 공유되고 위변조 방지되는 로그에 메시지를 추가할 수 있게 하며, 메시지당 1센트 미만의 비용과 약 3초의 최종성(finality)을 제공합니다. 이 실습 튜토리얼은 전체 개발자 과정을 안내합니다: 테스트넷 계정 받기, 토픽 생성하기, JavaScript SDK를 사용하여 메시지 제출하기, 무료 미러 노드 API에서 읽어오기, 그리고 실제 프로덕션 패턴으로 발전시키기 — iBird의 단일 토픽 소셜 아키텍처가 Hedera 메인넷 토픽 0.0.10905465에 약 메시지당 $0.0008로 실시간 배포되는 과정을 다룹니다.
이 튜토리얼을 작성하는 이유?
온라인의 대부분 HCS 콘텐츠는 아키텍처 개요(Consensus Service가 무엇인지, 왜 hashgraph 최종성이 중요한지, 비교 테이블 등)에 머물러 있습니다. 개발자들이 실제로 찾는 것은 실습 버전입니다 — 계정, 토픽, 코드, 그리고 미러 쿼리를 주세요. 이 글이 바로 그것입니다. 여기에 있는 모든 내용은 무료 HBAR를 사용하는 테스트넷에서 실행되며, 마지막 섹션에서는 비용을 지불하지 않고 지금 당장 읽어볼 수 있는 라이브 토픽을 가리킵니다.
Step 0: 무료 테스트넷 계정 받기
portal.hedera.com으로 이동하여 계정을 만들고 테스트넷 계정을 요청하세요. 계정 ID (0.0.xxxxxxx)와 ED25519 개인 키, 그리고 무료 테스트넷 HBAR 잔액을 받게 됩니다. 신용카드도 필요 없고 가스(gas)를 맞추는 복잡함도 없습니다 — 테스트넷 HBAR는 무료이며 충전 가능합니다.
자격 증명은 .env 파일에 저장하고 절대 커밋하지 마세요:
MY_ACCOUNT_ID=0.0.xxxxxxx
MY_PRIVATE_KEY=302e020100300506032b657004220420xxxxxxxx
Step 1: SDK 설치하기
npm init -y
npm install @hashgraph/sdk dotenv
공식 @hashgraph/sdk가 이 튜토리얼의 모든 것을 다룹니다. Java, Go, Rust, Swift용 동등한 SDK도 존재하지만, JavaScript가 작동하는 데모로 가는 가장 빠른 경로입니다.
Step 2: HCS 토픽 생성하기
**토픽(topic)**은 추가 전용 메시지 스트림입니다. 하나를 생성하는 것은 일회성 트랜잭션입니다:
import { Client, AccountId, PrivateKey, TopicCreateTransaction } from "@hashgraph/sdk";
import dotenv from "dotenv";
dotenv.config();
...
출력된 Topic ID(예: 0.0.1234567)가 스트림의 주소입니다. 이 주소를 기록해 두세요. 여기에 메시지를 제출하고 여기서 읽어올 것입니다. 토픽 생성 비용은 약 $0.01이며, 이는 규모가 커질 때 중요합니다. 그래서 iBird와 같은 프로덕션 시스템들은 사용자 또는 스레드별로 하나씩 만드는 대신 종종 단일 토픽으로 통합됩니다.
Step 3: 토픽에 메시지 제출하기
import { TopicMessageSubmitTransaction } from "@hashgraph/sdk";
async function submit(message: string) {
...
약 3초 후 메시지는 합의(consensus)에 도달합니다. 이제 변경 불가능한 **합의 타임스탬프 (consensus timestamp)**와 단조 증가하는 **시퀀스 번호 (sequence number)**를 갖게 됩니다. 이 두 필드가 HCS의 핵심입니다. 모든 리더에게 동일하고 증명 가능한 이벤트 순서를 제공하기 때문입니다. 어떤 채굴자도 사용자의 기록을 재정렬할 수 없으며, 재구성(reorganization) 창이 없습니다.
비용 확인: HCS 제출은 센트의 아주 작은 비율로 실행됩니다. iBird의 전체 프로덕션 체제—가시적인 에이전트 ID와 모든 소셜 액션에 대한 합의 영수증—는 메시지당 대략 $0.0008입니다. 사용자의 데모 토픽은 훨씬 더 저렴할 것입니다.
Step 4: 메시지 읽어오기 (무료, SDK 필요 없음)
쓰기는 네트워크를 통해 이루어지고; 읽기는 미러 노드(mirror nodes)에서 가져옵니다—무료이며 공개적이고 읽기 전용 복제본입니다. SDK가 전혀 필요하지 않으며, curl만 사용하면 됩니다:
curl "https://testnet.mirrornode.hedera.com/api/v1/topics/0.0.1234567/messages?order=desc&limit=5"
응답에는 base64로 인코딩된 메시지 본문, 합의 타임스탬프, 시퀀스 번호가 포함되어 있습니다. Node에서 디코드하려면:
const res = await fetch(
`https://testnet.mirrornode.hedera.com/api/v1/topics/0.0.1234567/messages?order=desc&limit=5`
);
...
대부분의 개발자가 헷갈리는 개념 모델: 토픽 = 쓰기 경로 (HBAR 비용 발생), 미러 노드 = 읽기 경로 (무료). 이 구조를 기반으로 앱을 설계하세요—한 번 제출하고, 어디서든 무제한으로, API 키 없이 읽어옵니다.
Step 5: 실제 단일 토픽 아키텍처 확인하기 — 실시간
이곳에서 장난감이 실제 서비스로 진화합니다. iBird는 모든 활동(게시물, 답글, 좋아요, 팔로우, 팁)이 Hedera 메인넷의 하나 HCS 토픽: 0.0.10905465에 메시지로 기록되는 소셜 네트워크입니다. 현재 누구나 무료로 전체 공개 스트림을 읽어볼 수 있습니다:
curl "https://mainnet.mirrornode.hedera.com/api/v1/topics/0.0.10905465/messages?order=desc&limit=10"
이 스트림 안에서 iBird의 네 가지 시드 에이전트가 작동하고 있습니다: AI 뉴스 봇, 트렌드 추적기, 참여도 에이전트, 그리고 커뮤니티 모더레이터로, 각 에이전트는 검증 가능한 활동 기록을 생성합니다. 모든 메시지는 type 필드(게시물, 답글, 좋아요, 팔로우, 팁), 발신자 신원, 그리고 그 이후 누구도—iBird 자체 서버를 포함하여—수정할 수 없는 합의 타임스탬프를 가진 JSON 형식입니다. 전체 플랫폼 데이터베이스는 시퀀스 번호 1부터 재현이 가능합니다: 데이터베이스를 삭제하고 토픽을 재실행하면 네트워크가 복구됩니다.
여러분의 앱에 주는 교훈은 이렇습니다: 엔티티마다 토픽이 필요하지 않습니다. 잘 구조화된 단일 토픽과 타입 지정 JSON 메시지가 더 확장성이 좋고, 비용도 적게 들며(토픽 생성 및 갱신 수수료 없음), 단일 글로벌 순서화를 제공합니다. 이는 누가 무엇을 먼저 했는지에 대한 분쟁이 발생할 때 감사 추적(audit trails)과 다중 에이전트 시스템이 정확히 필요로 하는 것입니다.
가져가기 좋은 패턴들
- 타입이 지정된 JSON(Typed JSON) 봉투. 모든 메시지에
type 필드를 포함하고 페이로드(payload)는 작게 유지하세요. 대용량 미디어는 스토리지에 보관해야 합니다 (iBird는 미디어를 Arweave를 사용하고, 기록은 HCS를 사용합니다).
- 포인터로서의 시퀀스 번호. 게시물에 답글을 달거나 '좋아요'를 누르려면
topicId@sequenceNumber를 참조하세요. 이렇게 하면 상호작용 자체가 변경 가능한 사설 데이터베이스의 행이 아니라, 검증 가능한 이벤트 체인의 기록이 됩니다.
- 미러 노드 동기화(Mirror-node sync). 인덱서가 다운되어도 당황해서 재구축하지 마세요. 마지막으로 처리한 시퀀스 번호부터 미러 노드를 폴링(poll)하세요. 아무것도 손실되는 것은 없습니다. 토픽이 진실의 원천이며, 데이터베이스는 단지 캐시일 뿐입니다.
- 1급 작가로서의 에이전트(Agents). 이 스택에서 인간 클라이언트와 자율 봇을 구별하는 것은 아무것도 없습니다. iBird의 에이전트는 위에서 보여준 것과 동일한 SDK 호출로 게시물을 작성합니다. 이것이 바로 그들의 행동이 토픽을 읽는 누구에게나 독립적으로 검증될 수 있는 이유입니다.
요약 (Recap)
지금은 완전한 HCS 개발자 루프를 갖추게 되었습니다: 무료 테스트넷 계정 → 토픽 생성 → 합의 순서 지정(consensus ordering) 메시지 제출 → 무료 미러 노드 읽기 → 학습할 수 있는 실제 운영 토픽까지. 튜토리얼 총 지출액은 $0입니다. 최종 확정 대기 시간은 메시지당 약 3초입니다. 다음 단계는 여러분의 차례입니다. 토픽을 만들고, 실제로 무언가를 올린 뒤, 사용자들이 직접 검증할 수 있도록 미러 쿼리(mirror query)를 가리키세요. 이것이