BlockETL - 블록체인 온톨로지 기반 지식그래프 시스템

Ethereum 블록체인 데이터를 ETL 파이프라인으로 수집하여 Neo4j 그래프 데이터베이스에 지식그래프로 구축하고, 이를 활용한 분석 API를 제공하는 Kotlin/Spring Boot 기반 백엔드 시스템입니다.

프로젝트 구조

blocketl/
├── blockinfra/                    # 인프라 설정
│   ├── docker-compose.yml         # Docker Compose 설정
│   ├── neo4j/                     # Neo4j 초기화 스크립트
│   ├── postgres/                  # PostgreSQL 초기화 스크립트
│   ├── start.sh                   # 인프라 시작 스크립트
│   ├── stop.sh                    # 인프라 중지 스크립트
│   └── README.md                  # 상세 문서
│
├── src/main/kotlin/com/jun/blocketl/
│   ├── domain/                    # 도메인 모델
│   │   ├── blockchain/            # 블록체인 데이터 모델
│   │   ├── graph/                 # Neo4j 그래프 노드 모델
│   │   └── meta/                  # PostgreSQL 메타데이터 모델
│   │
│   ├── repository/                # 데이터 접근 계층
│   │   ├── graph/                 # Neo4j Repository
│   │   └── meta/                  # JPA Repository
│   │
│   ├── etl/                       # ETL 파이프라인
│   │   ├── EthereumEtlService.kt  # 블록체인 데이터 수집
│   │   └── GraphBuilderService.kt # 그래프 빌드
│   │
│   ├── service/                   # 비즈니스 로직
│   │   ├── GraphQueryService.kt   # 그래프 쿼리
│   │   └── AmlAnalysisService.kt  # AML 분석
│   │
│   ├── api/                       # REST API
│   │   ├── BlockchainGraphController.kt
│   │   ├── AmlController.kt
│   │   └── EtlController.kt
│   │
│   └── config/                    # 설정
│       ├── Neo4jConfig.kt
│       ├── KafkaConfig.kt
│       ├── CacheConfig.kt
│       └── OpenApiConfig.kt
│
└── src/main/resources/
    └── application.yml             # 애플리케이션 설정

빠른 시작

1. 인프라 실행

cd blockinfra
./start.sh

또는 Windows에서:

cd blockinfra
docker-compose up -d

2. Ethereum RPC 설정

src/main/resources/application.yml 파일을 열고 Alchemy API Key를 설정합니다:

blockchain:
  etl:
    ethereum:
      rpc-url: https://eth-mainnet.g.alchemy.com/v2/YOUR_ALCHEMY_KEY

무료 API Key 발급: https://www.alchemy.com/

3. 애플리케이션 실행

./gradlew bootRun

4. API 접속

• Swagger UI: http://localhost:8080/swagger-ui.html
• Neo4j Browser: http://localhost:7474 (neo4j/blockchain123)

주요 기능

1. 블록체인 ETL 파이프라인

Ethereum 블록체인에서 블록과 트랜잭션 데이터를 실시간으로 수집합니다.

# 블록 동기화 시작
POST http://localhost:8080/api/v1/etl/sync/start?startBlock=0&endBlock=1000

# 동기화 재개
POST http://localhost:8080/api/v1/etl/sync/resume

작동 방식:

1. Web3j를 통해 Ethereum RPC에서 블록 데이터 조회
2. Kafka로 블록/트랜잭션 이벤트 발행
3. GraphBuilderService가 이벤트를 소비하여 Neo4j에 그래프 구축
4. PostgreSQL에 체크포인트 및 메타데이터 저장

2. 지식그래프 기반 분석

Neo4j 그래프 데이터베이스를 활용한 고급 분석 기능을 제공합니다.

주소 분석

# 주소 정보 조회
GET /api/v1/graph/address/0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb

# 연관 주소 찾기 (2-hop)
GET /api/v1/graph/address/{address}/connected?maxHops=2

자금 흐름 추적

# 두 주소 간 자금 이동 분석
GET /api/v1/graph/flow?fromAddress=0x...&toAddress=0x...

엔티티 분석

# 엔티티 정보 조회 (거래소, DeFi 프로토콜 등)
GET /api/v1/graph/entity/{entityId}

# 엔티티가 소유한 모든 주소
GET /api/v1/graph/entity/{entityId}/addresses

3. AML (자금세탁 방지) 분석

블록체인 주소의 자금세탁 위험도를 자동으로 평가합니다.

# 주소 위험도 평가
POST /api/v1/aml/evaluate/0x...

# 고위험 주소 목록
GET /api/v1/aml/high-risk?minScore=70.0

위험도 평가 요소:

• 믹서/텀블러 사용 여부
• 제재 대상 엔티티 연관성
• 비정상적인 거래 패턴
• 고위험 주소와의 연결성
• 계정 활동 기간 및 거래량

기술 스택

카테고리	기술
언어	Kotlin 2.2.21
프레임워크	Spring Boot 4.0.1
그래프 DB	Neo4j 5.15.0
관계형 DB	PostgreSQL 16
메시지 브로커	Apache Kafka 7.5.3
캐시	Redis 7.2
블록체인	Web3j 4.10.3 (Ethereum)
API 문서	SpringDoc OpenAPI 3

데이터 모델

Neo4j 그래프 온톨로지

(Block)-[:CONTAINS]->(Transaction)
(Transaction)-[:FROM]->(Address)
(Transaction)-[:TO]->(Address)
(Address)-[:BELONGS_TO]->(Entity)
(Entity)-[:OWNS]->(Address)

노드 타입:

• Block: 블록 정보
• Transaction: 트랜잭션
• Address: 주소 (EOA, Contract, Exchange, DeFi 등)
• Entity: 실제 소유자/조직
• Contract: 스마트 컨트랙트
• Token: ERC20/ERC721 토큰

사용 사례

1. 거래소 입출금 모니터링

// Neo4j: 특정 거래소로의 대규모 입금 찾기
MATCH (from:Address)-[:SENT]->(tx:Transaction)-[:TO]->(exchange:Address)
WHERE exchange.label = 'Binance Hot Wallet'
  AND toFloat(tx.value) > 100000000000000000000  // > 100 ETH
  AND tx.timestamp >= datetime('2024-01-01')
RETURN from, tx, exchange
ORDER BY tx.value DESC

2. 자금세탁 패턴 탐지

// Neo4j: 레이어링 패턴 탐지 (다단계 자금 분산)
MATCH path = (start:Address)-[:SENT*3..5]->(end:Address)
WHERE start.address = '0x...'
  AND ALL(r IN relationships(path) WHERE toFloat(r.value) > 1000000000000000000)
RETURN path

3. DeFi 프로토콜 사용자 분석

// Neo4j: Uniswap 사용자 중 고액 거래자 찾기
MATCH (user:Address)-[:SENT]->(tx:Transaction)-[:TO]->(uniswap:Address)
WHERE uniswap.label CONTAINS 'Uniswap'
WITH user, SUM(toFloat(tx.value)) as totalVolume
WHERE totalVolume > 10000000000000000000  // > 10 ETH
RETURN user, totalVolume
ORDER BY totalVolume DESC

성능 최적화

• Redis 캐싱: 자주 조회되는 주소 정보 및 그래프 쿼리 결과 캐싱
• 배치 처리: 100블록 단위 배치로 ETL 처리
• Circuit Breaker: Resilience4j를 활용한 RPC 장애 대응
• 비동기 처리: Coroutine 기반 비동기 ETL 파이프라인

모니터링

# Health Check
GET /actuator/health

# Metrics (Prometheus)
GET /actuator/prometheus

# ETL 상태 확인
GET /api/v1/etl/status

개발 환경

테스트 실행

./gradlew test

빌드

./gradlew build

JAR 실행

java -jar build/libs/blocketl-0.0.1-SNAPSHOT.jar

라이센스

Apache License 2.0

참고 자료

• 상세 문서
• Neo4j Cypher 가이드
• Web3j 문서
• Spring Boot 문서

✅ Kotlin/Spring Boot 기반 백엔드 개발 ✅ Neo4j 그래프 데이터베이스 활용 ✅ 블록체인 ETL 파이프라인 구축 ✅ 온톨로지 모델링 (엔티티, 관계 정의) ✅ AML 분석 기능 구현 ✅ Kafka 이벤트 스트리밍

핵심 강조점

1. ETL 파이프라인: "노드/ETL이 만든 그래프/지식 레이어"를 어떻게 구축하는지 설명
2. 그래프 활용: "그래프DB를 어떻게 Spring 기반 서비스로 감쌀 수 있는지" - Cypher 쿼리, Repository 패턴
3. 실무 적용성: AML, 주소 라벨링, 엔티티 클러스터링 등 실제 유스케이스