🔗 StableCoin BC Adapter

StableCoin BC Adapter는 블록체인과 비즈니스 서비스 사이의 중간 계층(Adapter)으로, 입금 감지 · 출금 · 결제 · 정산 · 집금 · 대사 등 스테이블코인 관련 모든 On-chain 오퍼레이션을 처리합니다.

헥사고날 아키텍처(Ports & Adapters)를 채택하여 비즈니스 로직과 인프라를 분리하였으며, NestJS 없이 순수 TypeScript로 수동 조합(Composition Root) 방식을 사용합니다.

메시지 처리 파이프라인

데이터 포맷 변환 규칙

• 외부 → 내부snake_case JSON → parseJsonToCamel() → camelCase 객체
• 내부 처리모든 내부 로직은 camelCase 사용
• 내부 → 외부camelCase → toSnakePayload() → snake_case JSON

부트스트랩 시퀀스

입금 메시지 스키마

핵심 동작 방식

• 메시지 보장Outbox 테이블에 먼저 저장 → Kafka 발행 시도 → 성공 시 Outbox 삭제
• 발행 실패 시Outbox에 남아 5초 간격 스케줄러가 재시도 (무한 재시도, at-least-once)
• 후속 처리입금 감지 후 collectDeposit() 비동기 호출 → HotWallet로 자동 집금
• 발행 토픽adapter.deposit.detected

• Host0.0.0.0 (기본값, 환경변수 DEPOSIT_WS_HOST)
• Port8080 (기본값, 환경변수 DEPOSIT_WS_PORT)
• Path/ws (기본값, 환경변수 DEPOSIT_WS_PATH)
• Ping 간격30초마다 ping 프레임 전송
• 비응답 처리30초 내 pong 미수신 시 연결 강제 종료

이벤트 처리 파이프라인

동시성 제어 상세

• 락 키withdraw:nonce:{chainId}:{senderAddress}
• 락 TTL30초 (자동 해제)
• 락 재시도최대 10회, 100ms 간격
• Nonce 충돌 재시도1회 (100ms 대기 후 새 Nonce 조회하여 재실행)
• Pending Nonce 대기100ms 폴링, 최대 3초 (이전 tx 컨펌 대기)

실행 분기 로직

에러 처리

핵심 처리 규칙

• 전송 주체HotWallet 주소 → Settlement 주소
• 토큰 유형ERC-20만 지원 (Native 미지원)
• 토큰 해석DB 조회 → 환경변수 폴백 → DEFAULT_DECIMALS 폴백
• 결제 체인환경변수 PAYMENT_CHAIN_NAME (기본: KCP)
• 락 키 공유출금과 동일한 withdraw:nonce: 프리픽스 사용 (의도적)
• Nonce 재시도충돌 시 1회 재시도 (출금과 동일 로직)

EOFS Split 상세

• Split 방식하나의 트랜잭션에서 가맹점 주소 + 수수료 주소로 동시 분배
• Nonce 조회블록체인 직접 ethCall (payerNonce 함수) - 번들러 Nonce와 별도
• 락 키settlement:nonce:{chainId}:{settlementAddress}
• 에러 재시도EFS024 에러 시 100ms 대기 → Nonce 재조회 → 1회 재시도

• 수집 방향fromAddress → HotWallet 주소로 자금 회수
• 번들러 메서드executeEoaFundedSplit (Settlement과 동일)
• 응답 토픽adapter.settlement.collect.result

두 가지 실행 모드

재시도 전략

• Native 잔액 재시도잔액이 0이면 1초 대기 후 재시도, 최대 3회
• Nonce 충돌 재시도100ms 대기 → Nonce 캐시 무효화 → 1회 재시도
• Nonce 관리인메모리 캐시 (성공: advance, 실패: invalidate)
• 에러 처리실패 시 에러를 삼키고(swallow) 로그만 기록 (비동기 호출이므로)

컨펌 상태 판정 로직

• 병렬 처리모든 체인 × 토큰 조합을 병렬로 조회
• Native 예외KRW 심볼은 Native 잔액 조회 제외
• ERC-20 조회BALANCE_OF_SELECTOR + address 인코딩으로 ethCall
• 응답 포맷배열: [{chainId, symbol, address, balance}]

핵심 로직

• 별도 프로세스메인 Adapter와 분리된 독립 Worker로 실행 (reconcile.ts)
• Consumer Groupbc-reconcile (메인과 분리)
• 시점 검색KST 날짜시간 → Unix 타임스탬프 → Binary Search로 블록 번호 특정
• 배치 크기100개 주소씩 잔액 조회
• blockTag특정 블록 번호를 기준으로 point-in-time 잔액 조회

집계 그룹

• 주소 생성CREATE2 (factory + salt + bytecodeHash) → 결정적 주소 계산
• 병렬 처리모든 활성 체인에 대해 Promise.allSettled로 동시 계산
• 체인 선택FUJI 체인이 있으면 우선 선택, 없으면 첫 번째 체인
• 검증계산된 주소가 EVM 패턴 (0x + 40자 hex) 일치 확인

• 배포 방식CREATE2 프록시 + EOFS (EOA Funded Split) 멀티스텝
• Registry 확인2초 간격 폴링, 최대 10회 (총 20초)
• 후속 처리배포 완료 후 collectAfterDeploy 비동기 호출 → 모든 토큰 집금
• 중복 방지Redis 분산 락으로 동시 배포 요청 차단

• 응답없음 (NoReply 패턴)
• 처리DB 삭제만 수행, 온체인 작업 없음

블록 타임 계산 방법

• 샘플 크기100블록 (fallback: 1블록)
• 계산(latestTimestamp - pastTimestamp) / 100 → 초 단위 floor
• FinalizedFinalized 블록 지원 시 confirmation 자동 계산, 미지원 시 1
• 응답없음 (NoReply 패턴)

요청 토픽 (Inbound)

응답/이벤트 토픽 (Outbound)

에러 계층 구조

에러 코드 분류 (총 49개)

Kafka 에러 응답 구조

2단계 직렬화 메커니즘

서비스별 락 키 매핑

Nonce 재시도 로직 (executeWithNonceRetry)

Pending Nonce 진행 대기 (waitForPendingNonceAdvance)

• 폴링 간격100ms
• 최대 대기3,000ms (3초)
• 성공 조건currentNonce > previousNonce
• 타임아웃 시경고 로그 후 현재 Nonce로 진행 (실패하지 않음)

Nonce 충돌 감지 기준

인메모리 Nonce 캐시 (Collection 전용)

• 키 형식{chainId}:{address}
• 성공 시advance(key) → 캐시 +1 증가
• 실패 시invalidate(key) → 캐시 삭제 (다음 호출 시 재조회)
• 동시 조회 방지fetchInProgress Map으로 중복 RPC 조회 차단

Outbox 스케줄러

• 폴링 간격5초 (5,000ms)
• 배치 크기500건
• 재시도 횟수무한 (성공할 때까지)
• 실패 처리개별 건 실패 시 경고 로그 → 다음 폴링에서 재시도
• 보장 수준At-Least-Once (최소 1회 발행 보장)

• 엔드포인트GET /health
• Host0.0.0.0 (기본, 환경변수 HEALTH_HOST)
• Port8081 (기본, 환경변수 HEALTH_PORT)
• 체크 타임아웃3,000ms (환경변수 HEALTH_CHECK_TIMEOUT_MS)

점검 항목

응답 코드

• 200 OK모든 컴포넌트 정상
• 503 Unavailable1개 이상 컴포넌트 이상