블록체인 시스템을 처음 설계할 때 가장 많이 하는 오해가 있다. “스마트컨트랙트에 비즈니스 로직을 넣으면 된다.” 틀렸다. 스마트컨트랙트는 이벤트를 발행하는 트리거일 뿐이다. 실제 비즈니스 로직은 그 이벤트를 받아서 처리하는 오프체인 시스템이 담당한다.
이것이 Web3 구조 설계자 Basic 검정에서 가장 중요하게 다루는 개념이다. 블록체인을 ‘변조 불가능한 이벤트 로그’로 이해하는 순간, 전체 아키텍처가 보이기 시작한다.
• 스마트컨트랙트 이벤트란 무엇인가
• 이벤트 드리븐 아키텍처(EDA)가 왜 Web3에 필수인가
• 실전 구현: 이벤트 구독·복구·멱등성·재시도
• 교보생명 NFT 사례로 보는 실전 적용
• Web3 구조 설계자 검정 시험 출제 포인트
1. 스마트컨트랙트 이벤트란 무엇인가
이더리움 솔리디티 기준으로 이벤트는 이렇게 정의된다.
event NFTMinted(
address indexed owner,
uint256 indexed tokenId,
string metadataURI,
uint256 timestamp
);
// 이벤트 발행
function mintNFT(address to, string memory uri) external {
uint256 tokenId = _nextTokenId++;
_mint(to, tokenId);
emit NFTMinted(to, tokenId, uri, block.timestamp);
}
이 코드에서 중요한 것은 emit NFTMinted(...) 한 줄이다. 이 이벤트는 트랜잭션 영수증(Receipt)에 로그로 기록되며, 블록체인 외부의 어떤 시스템이든 이것을 구독할 수 있다. 스마트컨트랙트는 “NFT가 발행됐다”고 알릴 뿐이다. 그 다음에 무엇을 할지는 오프체인 시스템의 몫이다.
| 역할 | 온체인 (스마트컨트랙트) | 오프체인 (백엔드 시스템) |
|---|---|---|
| 핵심 기능 | 상태 변경 + 이벤트 발행 | 이벤트 구독 + 비즈니스 처리 |
| 데이터 저장 | 최소화 (Gas 비용) | 상세 기록 (DB) |
| 알림·연동 | 불가능 | 가능 (Push, Email, Webhook) |
| 신뢰성 | 블록체인이 보장 | 개발자가 설계해야 함 |
| 수정 가능성 | 불가능 (불변) | 자유롭게 수정 가능 |
2. 이벤트 드리븐 아키텍처(EDA)가 왜 Web3에 필수인가
전통적인 웹 백엔드는 폴링(Polling) 방식을 쓴다. 주기적으로 서버에 “새 데이터 있어?”라고 물어보는 방식이다. 블록체인 시스템에서 이 방식을 쓰면 심각한 문제가 생긴다.
- RPC 요청 비용 누적
- 이벤트 누락 가능성
- 실시간성 부재
- 블록 재구성(Reorg) 처리 어려움
- 서버 재시작 시 이벤트 유실
- 실시간 이벤트 수신
- 이벤트 기반 처리 보장
- 블록 번호 기반 복구 가능
- 마이크로서비스 분리 용이
- 확장성 우수
블록체인의 핵심 특성을 생각하면 이벤트 드리븐이 필수인 이유가 명확해진다. 블록체인은 이미 이벤트 소싱(Event Sourcing) 그 자체다. 모든 상태 변경이 트랜잭션이라는 이벤트로 기록되고, 그 이벤트들의 누적이 현재 상태다. 오프체인 시스템도 같은 패러다임으로 설계해야 일관성이 유지된다.
3. 실전 구현: 이벤트 리스너 설계
기본 구조 — ethers.js 기반
const provider = new ethers.WebSocketProvider(RPC_WS_URL);
const contract = new ethers.Contract(ADDRESS, ABI, provider);
// 이벤트 구독
contract.on(‘NFTMinted’, async (owner, tokenId, metadataURI, timestamp, event) => {
// 비즈니스 로직 처리
await processNFTMinted({ owner, tokenId, metadataURI, timestamp });
// 처리한 블록 번호 저장 (복구 포인트)
await saveLastProcessedBlock(event.blockNumber);
});
이 코드는 기본이다. 실제 운영 환경에서는 세 가지 원칙을 추가로 구현해야 한다.
원칙 1 — 블록 번호 기반 복구 (Replay)
const lastBlock = await db.getLastProcessedBlock();
const currentBlock = await provider.getBlockNumber();
if (lastBlock < currentBlock) {
// 놓친 이벤트 일괄 처리
const events = await contract.queryFilter(
contract.filters.NFTMinted(),
lastBlock + 1,
currentBlock
);
for (const event of events) {
await processEvent(event);
}
}
}
원칙 2 — 멱등성 (Idempotency)
const uniqueKey = `${event.transactionHash}-${event.index}`;
// 이미 처리된 이벤트인지 확인
const exists = await db.eventExists(uniqueKey);
if (exists) {
console.log(`이미 처리됨: ${uniqueKey}`);
return;
}
// 처리 + DB 기록 (트랜잭션으로 묶기)
await db.transaction(async (trx) => {
await processBusinessLogic(event, trx);
await trx.markEventProcessed(uniqueKey);
});
}
원칙 3 — 재시도 + Dead Letter Queue
4. 교보생명 NFT 사례 — 실전 아키텍처
이 개념을 가장 쉽게 이해할 수 있는 실제 사례가 교보생명의 헬스케어 NFT 프로젝트다. 고객이 만보 걷기 목표를 달성하면 스마트컨트랙트가 NFT를 발행하고, 보험료 할인이 자동으로 적용된다.
| 단계 | 처리 주체 | 내용 |
|---|---|---|
| 1. 이벤트 발생 | 스마트컨트랙트 | NFTMinted 이벤트 emit, 블록체인 기록 |
| 2. 이벤트 수신 | 이벤트 리스너 | WebSocket으로 실시간 감지, 멱등성 검사 |
| 3. DB 기록 | 백엔드 서비스 | tokenId, owner, timestamp 원장 저장 |
| 4. Core Banking 연동 | 백엔드 서비스 | 보험료 할인 적용 Webhook 전송 (재시도 포함) |
| 5. 고객 알림 | 알림 서비스 | Push + 앱 알림 발송 |
이 전체 파이프라인에서 스마트컨트랙트가 하는 일은 1단계뿐이다. 나머지 4단계는 전부 오프체인 시스템이 처리한다. 블록체인은 “NFT가 발행됐다”는 변조 불가능한 사실을 기록하고, 비즈니스 시스템이 그 사실을 읽어 처리한다.
5. 블록 재구성(Reorg) 처리
이벤트 드리븐 아키텍처에서 가장 어려운 부분 중 하나가 블록 재구성 처리다. PoW 체인에서는 드물지 않고, 최근 라이트코인 13블록 롤백 사례처럼 대규모 Reorg도 발생할 수 있다.
1. 확정 블록 이후에만 처리: 이더리움 기준 12~20 컨펌 후 “최종 확정” 처리
2. Pending 상태 분리: DB에 confirmed/pending 상태 구분 저장
3. Reorg 감지 로직: 이미 처리한 txHash가 다른 블록에 나타나면 Reorg로 판단
4. 롤백 처리: Reorg 발생 시 pending 레코드 자동 취소, Core Banking에 취소 신호 전송
6. Web3 구조 설계자 Basic 검정 — 이 개념이 왜 핵심인가
CoinCraft가 운영하는 Web3 구조 설계자 Basic 검정은 단순히 블록체인 용어를 외우는 시험이 아니다. 실제 기업 환경에서 블록체인 시스템을 어떻게 설계하고 연동하는지를 평가한다.
이벤트 드리븐 아키텍처와 시스템 신뢰성(복구·멱등성·재시도) 영역이 전체 배점의 80%를 차지한다. 스마트컨트랙트 코드를 잘 짜는 능력보다, 그 코드가 발행하는 이벤트를 어떻게 신뢰성 있게 처리하는지를 더 중요하게 본다.
자주 출제되는 시나리오 문제 유형
| 시나리오 | 핵심 설계 포인트 |
|---|---|
| 서버 재시작 후 이벤트 유실 | 블록 번호 저장 + queryFilter 복구 |
| 같은 이벤트 두 번 처리 | txHash+logIndex 고유 키 + 멱등성 검사 |
| Core Banking Webhook 실패 | 지수 백오프 재시도 + DLQ |
| 블록 Reorg 발생 | 컨펌 수 기반 처리 + pending 상태 관리 |
| 이벤트 처리 지연 대응 | 큐(Queue) 기반 비동기 처리 + 백프레셔 |
7. 실무에서 가장 많이 하는 실수
정리 — 블록체인 = 이벤트 로그, 비즈니스 = 오프체인
이 글에서 다룬 핵심 개념을 한 문장으로 정리하면 이렇다: 블록체인은 변조 불가능한 이벤트 로그이고, 비즈니스 시스템은 그 로그를 구독해서 가치를 만드는 오프체인 파이프라인이다.
스마트컨트랙트를 잘 짜는 것보다, 그 컨트랙트가 발행하는 이벤트를 얼마나 신뢰성 있게 처리하는지가 Web3 시스템 엔지니어링의 본질이다. 교보생명 사례처럼 실제 금융 인프라에 블록체인을 연동할 때, 이 설계 능력의 차이가 시스템의 신뢰성을 결정한다.
• 스마트컨트랙트 = 이벤트 트리거. 비즈니스 로직은 오프체인에
• 복구: 마지막 처리 블록 번호 저장 → queryFilter 재스캔
• 멱등성: txHash + logIndex 고유 키 → 이중 처리 방지
• 재시도: 지수 백오프 + DLQ → 이벤트 데이터 유실 없음
• Reorg: 컨펌 수 기반 처리 → pending/confirmed 상태 분리
CoinCraft Web3 구조 설계자 Basic 검정 관련 문의: coincraft.io
About the Author
