# Cryptoments v2 — 컴포넌트 상세 명세

> **버전**: v1.1
> **작성일**: 2026-02-25 (v1.1: 2026-03-06)
> **목적**: 각 컴포넌트의 역할, 기능, DB/캐시 접근, 통신 관계를 정의
> **상태**: 확정
> **관련 문서**:
> - [Admin Console UI 가이드](CRYPTOMENTS_ADMIN_CONSOLE_UI_GUIDE.md)
> - [Partner Console UI 가이드](CRYPTOMENTS_PARTNER_CONSOLE_UI_GUIDE.md)
> - [CRYPTOMENTS_CORE_LIBRARY.md](CRYPTOMENTS_CORE_LIBRARY.md) v1.0 — 코어 라이브러리 아키텍처
> - [CRYPTOMENTS_NODEJS_SERVERS.md](CRYPTOMENTS_NODEJS_SERVERS.md) v1.0 — Node.js 서버 개발 명세
> - [CRYPTOMENTS_TECH_STACK_BOUNDARY.md](CRYPTOMENTS_TECH_STACK_BOUNDARY.md) v1.0 — 기술 스택 경계
> - [CRYPTOMENTS_SERVICE_MODULES.md](CRYPTOMENTS_SERVICE_MODULES.md) v2.1 — 서비스 모듈 정의

---

## 시스템 컴포넌트 다이어그램

![Cryptoments v2 시스템 컴포넌트 다이어그램](CRYPTOMENTS_V2_COMPONENT_DIAGRAM.png)

> 인터랙티브 버전: [CRYPTOMENTS_V2_COMPONENT_DIAGRAM.html](CRYPTOMENTS_V2_COMPONENT_DIAGRAM.html)
> 텍스트 버전: [CRYPTOMENTS_V2_COMPONENT_DIAGRAM.md](CRYPTOMENTS_V2_COMPONENT_DIAGRAM.md)

---

## 컴포넌트 전체 목록

| # | 컴포넌트 | 기술 스택 | DB | Redis |
|---|---------|----------|:--:|:-----:|
| 1 | Open API 서버 | Spring Boot | ✅ | ✅ |
| 2 | Admin API 서버 | Spring Boot | ✅ | ✅ |
| 3 | Partner API 서버 | Spring Boot | ✅ | ✅ |
| 4 | Widget API 서버 | Spring Boot | ✅ | ✅ |
| 5 | Webhook 수신 서버 | Spring Boot | ✅ | ✅ |
| 6 | 텔레그램 메시지 서버 | Spring Boot | ✅ | ❌ |
| 7 | 스케줄러 서버 | Spring Boot | ✅ | ✅ |
| 8 | Blockchain API 서버 | Node.js | ✅ | ✅ |
| 9 | Relayer API 서버 | Node.js | ✅ | ✅ |
| 10 | 지갑 활성화 서버 | Node.js | ✅ | ✅ |
| 11 | Admin Front | Vue 3 | ❌ | ❌ |
| 12 | Partner Front | Vue 3 | ❌ | ❌ |
| 13 | Widget Front | Vue 3 | ❌ | ❌ |
| 14 | 텔레그램 봇 서버 | Node.js | ✅ | ❌ |

---

## 1. Open API 서버

> **기술**: Spring Boot 3.3 / Java 17 / MyBatis
> **인증**: API Key + API Secret (HMAC 서명)
> **대상**: 파트너 서버 (서버 간 통신)
> **인스턴스**: 2+ (수평 확장, Stateless)

### 역할

파트너가 자기 서버에서 호출하는 REST API. 입금/출금/잔액의 핵심 비즈니스 API를 제공한다.

### 주요 기능

| 기능 | 설명 | 관련 테이블 |
|------|------|------------|
| **인증** | API Key + API Secret HMAC 서명 인증 | partners |
| **체인/토큰 정보 조회** | 지원하는 모든 체인과 해당 체인의 지원 토큰 정보 조회 | blockchain_networks, currencies |
| **파트너 정보 조회** | 파트너의 활성화된 체인 목록, 지갑 정보 조회 | partner_chain_configs, wallet_addresses |
| **환율/가격 조회** | 토큰 가격 조회 (USD/KRW), 환율 변환 (USDT↔KRW 등) | currency_prices, currency_price_history (빗썸 API 주기 갱신) |
| **입금 주소 발급** | 파트너 사용자별 HOT 지갑 주소 할당 또는 기존 주소 반환 | wallet_addresses |
| **출금 요청** | 파트너 → 외부 주소 출금 요청. 정책 검증 (한도/화이트리스트/쿨다운) | withdrawals, partner_withdrawal_policies |
| **잔액 조회** | 파트너의 MASTER 지갑 가용 잔액 조회 | wallet_balances |
| **거래 내역 조회** | 사용자별 입금/출금 내역 조회 (페이징, 필터) | deposits, withdrawals |
| **미완료 입금 조회** | 사용자의 진행 중 입금 건 조회 (PENDING/CONFIRMING) | deposits |
| **입금 확인** | 파트너 측 입금 확인 처리 (단건/일괄). 파트너가 입금을 인지했음을 확정 | deposits |
| **입금 세션 생성** | 소수점 매칭 입금 세션 생성 (Widget 없이 API로 직접) | deposit_sessions, deposit_address_pool |
| **콜백 설정** | Webhook 콜백 URL, 시크릿 키 설정 | partner_telegram_configs |
| **파트너 콜백 발송** | 입금 확인/출금 완료 시 파트너 서버로 Webhook 콜백 전송 (HMAC 서명) | notification_events, notification_deliveries |
| **테스트 콜백** | 콜백 URL 연결 테스트용 테스트 이벤트 전송 | — |
| **Axim 연결 정보 조회** | 파트너 사용자의 Axim 지갑 연결 상태/정보 조회 (connectWalletToken, connectId) | external_wallets, partner_axim_settings |
| **Axim 결제 요청** | Axim Pay API를 통해 결제 요청 생성 (connectWalletToken, 금액, 체인) | axim_payments, partner_axim_settings |
| **Axim 결제 조회** | Axim 결제 목록/상세/상태 조회 | axim_payments |
| **Axim 결제 취소** | 대기 중인 Axim 결제 취소 | axim_payments |
| **Axim 최적 네트워크** | 사용자 지갑 잔액 기반 최적 결제 네트워크 추천 | partner_axim_settings |

### 호출하는 내부/외부 서버

| 대상 | 목적 |
|------|------|
| Blockchain API 서버 | 지갑 주소 파생 (HD Wallet), 잔액 온체인 조회 |
| **Axim Pay API** (외부) | 지갑 연결 조회, 결제 생성/조회/취소, 최적 네트워크 추천 |

> **참고**: 지갑 활성화는 Webhook 수신 서버가 첫 입금 감지 시 wallet_approvals에 PENDING INSERT → 지갑 활성화 서버가 DB 폴링으로 처리. Open API 서버가 직접 호출하지 않음.

### DB 접근

- **MySQL**: 읽기/쓰기 (커넥션 풀)
- **Redis**: API Rate Limiting, 지갑 주소 캐시 (address → wallet_address_id)

---

## 2. Admin API 서버

> **기술**: Spring Boot 3.3 / Java 17 / MyBatis
> **인증**: JWT (Access + Refresh Token)
> **대상**: Admin Front (Super Admin 콘솔)
> **인스턴스**: 1+ (내부 트래픽, 최소 구성)

### 역할

Super Admin 전용 API. 전체 시스템 관리, 파트너 관리, 출금 수동 승인/거부, 모니터링.

### 주요 기능

| 기능 | 설명 | 관련 테이블 |
|------|------|------------|
| 관리자 인증 | 로그인, 2FA, 세션 관리 | admins |
| 파트너 CRUD | 파트너 생성/수정/정지/해제 | partners, partner_chain_configs |
| 출금 승인/거부 | PENDING_APPROVAL 건 수동 승인 또는 거부 | withdrawals, withdrawal_approval_logs |
| 출금 정책 관리 | 파트너별 자동승인 임계값, 일일 한도, 쿨다운 설정 | partner_withdrawal_policies |
| 대시보드 | 전체 입출금 현황, 네트워크별 상태, 잔액 요약 | deposits, withdrawals, wallet_balances |
| 미식별 입금 처리 | 미식별 입금 수동 매칭 또는 환불 | unidentified_deposits |
| CS 매칭 요청 처리 | 파트너가 올린 CS 매칭 요청 검토/처리 | cs_match_requests |
| 시스템 설정 | 글로벌 설정 변경 (가스비 임계값, 배치 설정 등) | system_settings |
| 가스비 리포트 | 네트워크별/파트너별 가스 비용 집계 | gas_cost_records |
| 감사 로그 | 관리자 활동 기록 조회 | admin_audit_logs |
| Relayer 관리 | Relayer 지갑 상태 조회, 활성화/비활성화, 모니터링 | relayer_wallets, nonce_tracker |
| 지갑 모니터링 | GAS 지갑 잔액 부족 경고, MASTER 잔액 현황 | wallet_balances, wallet_addresses |

### 호출하는 내부 서버

| 대상 | 목적 |
|------|------|
| Blockchain API 서버 | 온체인 잔액 실시간 조회 (모니터링 대시보드) |

### DB 접근

- **MySQL**: 읽기/쓰기 (커넥션 풀)
- **Redis**: JWT 세션 관리, 관리자 로그인 세션

---

## 3. Partner API 서버

> **기술**: Spring Boot 3.3 / Java 17 / MyBatis
> **인증**: JWT (Access + Refresh Token)
> **대상**: Partner Front (파트너 콘솔)
> **인스턴스**: 2+ (파트너 수 비례)

### 역할

파트너 관리자 전용 API. 자기 파트너의 입출금 내역, 설정, CS 요청, 사용자 관리, Axim 연동을 처리한다.

### 주요 기능

| 기능 | 설명 | 관련 테이블 |
|------|------|------------|
| **인증/계정** | | |
| 파트너 인증 | 로그인, 2FA, 세션 관리 | admins (role=PARTNER_ADMIN) |
| API 키 관리 | API Key/Secret 조회, 재발급 | partners (api_key, api_secret_hash) |
| **대시보드** | | |
| 대시보드 | 파트너 입출금 현황, 잔액 요약, 최근 거래, Axim 결제 현황 | deposits, withdrawals, wallet_balances, axim_payments |
| **사용자 관리** | | |
| 사용자 조회 | 파트너 사용자 목록 조회 (partner_user_id 기반) | wallet_addresses, deposits, withdrawals |
| 사용자 상세 (통합 뷰) | 특정 사용자의 입금 지갑, 입금 내역, 출금 내역, Axim 연결 상태, Axim 결제 내역을 한 화면에서 조회 | wallet_addresses, deposits, withdrawals, external_wallets, axim_payments |
| **입금** | | |
| 입금 내역 | 입금 목록 조회, 상세, 필터링 (기간/상태/체인/사용자) | deposits |
| 입금 지갑 생성 | 사용자별 입금 지갑 주소 발급 (콘솔에서 직접) | wallet_addresses |
| 결제 링크 생성 | 소수점 매칭 입금 세션 생성 → 결제 링크 URL 발급 | deposit_sessions, deposit_address_pool |
| **출금** | | |
| 출금 내역 | 출금 목록 조회, 상세, 상태 추적 | withdrawals |
| 출금 요청 | 콘솔에서 직접 출금 요청 (request_source=CONSOLE) | withdrawals |
| 출금 취소 | REQUESTED/PENDING_APPROVAL 상태 출금 건 취소 처리 | withdrawals |
| 화이트리스트 관리 | 출금 주소 화이트리스트 등록/삭제 | withdrawal_address_whitelist |
| **Axim 연동** | | |
| Axim 설정 | Axim API Key/Secret 등록, site_id 설정, 활성화/비활성화 | partner_axim_settings |
| Axim 결제 요청 | 연결된 Axim 사용자에게 결제 요청 전송 | axim_payments, partner_axim_settings |
| Axim 결제 내역 | Axim 결제 목록 조회, 상세, 상태 추적 | axim_payments |
| **외부 지갑** | | |
| 외부 지갑 목록 | Axim/MetaMask 등 연결된 외부 지갑 목록 조회 | external_wallets |
| 외부 지갑 상세 | 연결 상태, 지갑 주소, 연결 일시 조회 | external_wallets |
| 외부 지갑 해지 | 연결된 외부 지갑 연결 해제 (REVOKED 처리) | external_wallets |
| **알림/설정** | | |
| 알림 설정 | Telegram 채팅방, Webhook URL 설정, 이벤트 구독 관리 | partner_telegram_configs, partner_telegram_subscriptions |
| **CS/운영** | | |
| CS 매칭 요청 | 미식별 입금/만료 세션 매칭 요청 생성 | cs_match_requests |
| Approve 요청 | 지갑 Approve 상태 조회 및 재요청 | wallet_approvals |

### 호출하는 내부/외부 서버

| 대상 | 목적 |
|------|------|
| Blockchain API 서버 | 온체인 잔액 조회 (대시보드) |
| **Axim Pay API** (외부) | Axim 결제 요청 생성, 결제 상태 조회 |

> **참고**: Approve 재요청은 wallet_approvals에 PENDING INSERT → 지갑 활성화 서버가 DB 폴링으로 처리. Partner API가 직접 호출하지 않음.

### DB 접근

- **MySQL**: 읽기/쓰기 (커넥션 풀). partner_id 기반 데이터 격리 필수
- **Redis**: JWT 세션 관리

---

## 4. Widget API 서버

> **기술**: Spring Boot 3.3 / Java 17 / MyBatis
> **인증**: 파트너 API Key (위젯 초기화 시)
> **대상**: Widget Front (결제 위젯 UI)
> **인스턴스**: 2+ (세션 트래픽 비례)

### 역할

결제 위젯 전용 API. 파트너 사용자가 입금할 때 보는 위젯 UI의 백엔드. 입금 세션 생성, 소수점 매칭, 상태 폴링을 담당한다. Axim 지갑 연결 및 Axim Pay 결제 플로우도 지원한다.

### 주요 기능

| 기능 | 설명 | 관련 테이블 |
|------|------|------------|
| 위젯 초기화 | 파트너 API Key 검증, 지원 네트워크/통화 목록 반환 | partners, partner_chain_configs, currencies, blockchain_networks |
| 입금 세션 생성 | 소수점 매칭 키 할당, 풀 주소 배정, 세션 생성 | deposit_sessions, deposit_address_pool |
| 세션 상태 폴링 | 입금 세션 현재 상태 조회 (WAITING → MATCHED → COMPLETED) | deposit_sessions |
| 환율 조회 | KRW → crypto 환율 변환 (currency_prices 테이블 참조, 빗썸 API 기반) | currency_prices |
| 세션 취소 | 사용자 또는 파트너에 의한 세션 취소 | deposit_sessions |
| **Axim 연결 정보** | 사용자의 Axim 지갑 연결 토큰/상태 조회 (위젯에서 Axim 연결 UI 제공) | external_wallets, partner_axim_settings |
| **Axim 결제 요청** | Axim 연결된 사용자에 대해 Axim Pay 결제 요청 생성 (위젯 내 Axim Pay 플로우) | axim_payments, partner_axim_settings |
| **Axim 결제 상태** | Axim 결제 상태 폴링 (REQUESTED → PENDING → WAITING → CONFIRMED) | axim_payments |

### 호출하는 내부/외부 서버

| 대상 | 목적 |
|------|------|
| **Axim Pay API** (외부) | 지갑 연결 정보 조회, 결제 요청/상태 조회, 최적 네트워크 추천 |

### DB 접근

- **MySQL**: 읽기/쓰기 (커넥션 풀)
- **Redis**: 세션 캐시 (deposit_session TTL), 소수점 키 풀 관리, Rate Limiting

---

## 5. Webhook 수신 서버

> **기술**: Spring Boot 3.3 / Java 17 / MyBatis
> **인증**: IP 화이트리스트 + 서명 검증 (blockchain_monitor) / HMAC-SHA256 서명 검증 (Axim Pay)
> **대상**: blockchain_monitor (외부), Axim Pay (외부)
> **인스턴스**: 2+ (burst 대응, 수평 확장)

### 역할

blockchain_monitor와 Axim Pay가 보내는 Webhook을 수신하고 처리하는 서버. Cryptoments의 **이벤트 진입점**. Store-First 원칙 — 즉시 DB 저장 후 200 OK, 비즈니스 로직은 비동기.

### 주요 기능

| 기능 | 설명 | 관련 테이블 |
|------|------|------------|
| Webhook 수신 | blockchain_monitor POST 수신, 즉시 webhook_events 저장 | webhook_events |
| 중복 방지 | tx_hash + tx_status UNIQUE 키로 멱등성 보장 | webhook_events |
| 비즈니스 분류 | to_address 매칭으로 비즈니스 타입 판별 (DEPOSIT, WITHDRAWAL_CONFIRM, COLLECTION_CONFIRM, GAS_SUPPORT_CONFIRM, APPROVE_CONFIRM 등) | webhook_events, wallet_addresses |
| 입금 생성 | DEPOSIT으로 분류된 이벤트 → deposits 레코드 생성 | deposits, wallet_balances |
| 입금 세션 매칭 | 소수점 매칭 입금 → deposit_sessions와 매칭 | deposit_sessions |
| 출금 확인 | WITHDRAWAL_CONFIRM → withdrawals 상태 CONFIRMED 업데이트 | withdrawals |
| 집금 확인 | COLLECTION_CONFIRM → collection_queue 상태 COMPLETED 업데이트, MASTER 잔액 증가 | collection_queue, wallet_balances |
| Approve 확인 | APPROVE_CONFIRM → wallet_approvals 상태 APPROVED 업데이트 | wallet_approvals |
| 가스비 기록 | TX 수수료(txFee) → gas_cost_records 저장 | gas_cost_records |
| 미식별 처리 | 매칭 실패 → unidentified_deposits 생성 | unidentified_deposits |
| 재처리 | FAILED 이벤트 재시도 (max_retries 이내) | webhook_events |
| 지갑 활성화 요청 | 첫 입금 감지 시 해당 지갑 approve 상태 확인 → PENDING이면 wallet_approvals에 활성화 요청 INSERT (DB 폴링 트리거) | wallet_approvals |
| 집금 요청 | 입금 확인 + 지갑 APPROVED 상태 → collection_queue에 집금 대기 INSERT | collection_queue |
| **Axim Webhook 수신** | Axim Pay에서 보내는 이벤트 수신 (HMAC-SHA256 서명 검증) | webhook_events, partner_axim_settings |
| **Axim 연결 이벤트** | connection.succeeded/failed/revoked → 사용자 Axim 연결 상태 업데이트 | external_wallets |
| **Axim 결제 이벤트** | payment.succeeded → 입금 처리 플로우 진입. payment.failed/canceled/expired → 상태 업데이트, 파트너 콜백 | axim_payments, deposits, notification_events |

### 핵심 플로우 (첫 입금 → 활성화 → 집금)

```
1. blockchain_monitor → Webhook 수신 (입금 감지)
2. webhook_events 저장 (Store-First)
3. 비즈니스 분류 → DEPOSIT
4. deposits 레코드 생성
5. 해당 지갑 wallet_approvals 확인
   → APPROVED → 바로 collection_queue에 집금 대기 INSERT
   → PENDING/없음 → wallet_approvals에 활성화 요청 INSERT
     → 지갑 활성화 서버가 DB 폴링으로 가져감
     → 활성화 완료 후 (APPROVED) collection_queue에 집금 대기 INSERT
```

### 호출하는 내부 서버

| 대상 | 목적 |
|------|------|
| Blockchain API 서버 | TX 상태 재조회 (재처리 시) |
| 텔레그램 메시지 서버 | 입금/출금 확인 알림 트리거 |

> **참고**: Relayer API, 지갑 활성화 서버와는 직접 API 호출하지 않음.
> 집금은 collection_queue INSERT, 활성화는 wallet_approvals INSERT로 DB 기반 연동.

### DB 접근

- **MySQL**: 읽기/쓰기 (커넥션 풀). 고빈도 쓰기 — webhook_events, deposits
- **Redis**: 지갑 주소 캐시 (to_address → wallet_address_id 빠른 매칭), 중복 수신 방지

---

## 6. 텔레그램 메시지 서버

> **기술**: Spring Boot 3.3 / Java 17
> **인증**: 내부 서버 간 통신 (내부 네트워크)
> **대상**: Telegram Bot API (외부)
> **인스턴스**: 1+ (큐 기반)

### 역할

Telegram Bot API를 통해 파트너별 채팅방으로 알림 메시지를 전송하는 서버. 입금/출금 알림, 시스템 경고 등을 마크다운 형식으로 전송한다.

### 주요 기능

| 기능 | 설명 | 관련 테이블 |
|------|------|------------|
| 알림 이벤트 수신 | 다른 서버에서 발행한 notification_events 폴링 또는 수신 | notification_events |
| Telegram 전송 | 파트너별 채팅방으로 Bot API 메시지 전송 | partner_telegram_configs, notification_deliveries |
| 메시지 포맷팅 | 이벤트 타입별 마크다운 메시지 템플릿 | — |
| 재시도 | 전송 실패 시 지수 백오프 재시도 (30s, 60s, 300s, 900s, 3600s) | notification_deliveries |
| 전달 기록 | 전송 결과 (성공/실패, 응답 코드, 소요 시간) 기록 | notification_deliveries |

### 호출하는 외부 서버

| 대상 | 목적 |
|------|------|
| Telegram Bot API | sendMessage (마크다운) |

### DB 접근

- **MySQL**: 읽기/쓰기 (notification_events, notification_deliveries, partner_telegram_configs)
- **Redis**: ❌ (불필요)

---

## 7. 스케줄러 서버

> **기술**: Spring Boot 3.3 / Java 17 / MyBatis
> **인증**: 없음 (내부 전용, 외부 API 없음)
> **대상**: 내부 배치 처리
> **인스턴스**: **1 (단일 인스턴스)** — 중복 실행 방지

### 역할

주기적 배치 작업을 실행하는 서버. 정산, 만료 처리, 잔액 동기화, 미처리 건 재시도 등.

### 주요 기능

| 기능 | 주기 | 설명 | 관련 테이블 |
|------|------|------|------------|
| 만료 세션 정리 | 1분 | expires_at 지난 deposit_sessions → EXPIRED 처리, 소수점 키 반환 | deposit_sessions |
| 미확인 TX 재처리 | 5분 | FAILED/RETRY_PENDING webhook_events 재처리 | webhook_events |
| 잔액 동기화 | 10분 | 온체인 잔액과 DB 잔액 대조 (MASTER, GAS 지갑) | wallet_balances |
| 집금 지연 재시도 | 5분 | FAILED/DEFERRED 상태 collection_queue 재시도 | collection_queue |
| 출금 지연 처리 | 5분 | BALANCE_PENDING 출금 건 잔액 재확인 → 실행 | withdrawals |
| GAS 지갑 잔액 감시 | 10분 | GAS 지갑 네이티브 잔액 부족 감지 → 자동 충전 또는 알림 | wallet_balances, wallet_addresses |
| Relayer 상태 감시 | 5분 | pending TX 수, 연속 에러 체크 → NONCE_STUCK 자동 전환 | relayer_wallets |
| 정산 | 매일 00:00 | 일일 입출금 집계, 원장 정리 | ledger_entries |
| 가스비 정산 | 매일 01:00 | 파트너별 가스 비용 집계 | gas_cost_records |
| 논스 동기화 | 30분 | 온체인 논스와 DB 논스 대조, 갭 해소 | nonce_tracker |

### 호출하는 내부 서버

| 대상 | 목적 |
|------|------|
| Blockchain API 서버 | 잔액 동기화, 논스 동기화 (온체인 조회) |
| 텔레그램 메시지 서버 | GAS 잔액 부족, Relayer 이상 알림 |

> **참고**: 집금 재시도는 collection_queue 상태를 QUEUED로 재설정 → Relayer가 폴링으로 처리.
> 출금 지연 처리도 withdrawals 상태를 APPROVED로 재설정 → Relayer가 폴링으로 처리.
> 스케줄러가 Relayer API를 직접 호출하지 않음.

### DB 접근

- **MySQL**: 읽기/쓰기 (커넥션 풀). 배치 특성상 대량 쿼리 실행
- **Redis**: 분산 락 (스케줄 중복 실행 방지), 잔액 캐시

---

## 8. Blockchain API 서버

> **기술**: Node.js / TypeScript / ethers.js, tronweb
> **인증**: 내부 서버 간 통신 (내부 네트워크)
> **대상**: Spring Boot 서버들, Blockchain Nodes (외부)
> **인스턴스**: 2+ (네트워크별 분리 가능)

### 역할

블록체인 온체인 데이터 **조회 전담**. 쓰기(TX 실행)는 하지 않는다. 잔액, TX 상태, 블록 정보, 컨트랙트 read-only 호출을 처리한다.

### 주요 기능

| 기능 | 설명 | 체인 |
|------|------|------|
| 지갑 주소 파생 | HD Wallet 마스터 시드에서 BIP-44 경로로 주소 파생 | ETH, BSC, Polygon, TRON |
| 토큰 잔액 조회 | ERC-20/TRC-20 balanceOf 호출 | 전체 |
| 네이티브 잔액 조회 | ETH, BNB, POL, TRX 잔액 조회 | 전체 |
| TX 상태 조회 | tx_hash로 TX 확인 상태, 블록 번호, 가스 소모량 조회 | 전체 |
| TX Receipt 조회 | TX 실행 결과 상세 (logs, status, gasUsed) | 전체 |
| Approve 상태 조회 | allowance 함수 호출 (현재 승인량 확인) | 전체 |
| 가스 가격 조회 | 현재 네트워크 가스 가격 (gasPrice / feeData) | EVM |
| 블록 번호 조회 | 최신 블록 번호 (동기화 상태 확인) | 전체 |
| 온체인 잔액 동기화 | 배치 조회 → wallet_balances.onchain_balance 업데이트 | 전체 |

### DB 접근

- **MySQL**: 읽기/쓰기 — hd_wallets(시드 조회), wallet_addresses(주소 저장), wallet_balances(onchain_balance 업데이트)
- **Redis**: 가스 가격 캐시 (짧은 TTL), 주소 조회 결과 캐시

---

## 9. Relayer API 서버

> **기술**: Node.js / TypeScript / ethers.js, tronweb
> **인증**: 내부 서버 간 통신 (내부 네트워크)
> **대상**: Spring Boot 서버들, Blockchain Nodes (외부)
> **인스턴스**: 2+ (역할별 분리 가능)
> **동작 방식**: DB 폴링 (collection_queue, withdrawals 상태 기반)

### 역할

시스템을 제외한 **파트너의 모든 온체인 자금 이동**을 전담 실행한다. Relayer 지갑으로 meta transaction (transferFrom)을 실행하며, 논스 할당부터 브로드캐스트까지 한 플로우에서 처리한다. 또한 **Relayer 지갑 자체의 등록/해제** (컨트랙트 등록)도 관장한다.

### TX 유형 (파트너 모든 출금)

| TX 유형 | 방향 | 설명 | 트리거 |
|---------|------|------|--------|
| **집금** | HOT/POOL → MASTER | 사용자 입금 후 MASTER로 모으기 | collection_queue (QUEUED) |
| **사용자 출금** | MASTER → 외부 주소 | 파트너 API/콘솔 경유 일반 출금 | withdrawals (APPROVED) |
| **환불** | MASTER → 외부 주소 | 미식별/오류 입금 환불 | withdrawals (APPROVED, type=REFUND) |
| **파트너 출금** | MASTER → 파트너 외부 지갑 | 파트너 자체 수익금 출금 | withdrawals (APPROVED, type=PARTNER) |

> **시스템 제외**: 시스템 지갑 간 이동 (가스 충전, 내부 재배분)은 Relayer를 거치지 않고 별도 처리.

### 주요 기능

| 기능 | 설명 | 관련 테이블 |
|------|------|------------|
| **집금 실행** | collection_queue 폴링 → QUEUED 건 처리. HOT/POOL → MASTER transferFrom | collection_queue, nonce_tracker, relayer_wallets |
| **출금 실행** | withdrawals 폴링 → APPROVED 건 처리. MASTER → 외부 transferFrom. 사용자 출금/환불/파트너 출금 모두 포함 | withdrawals, nonce_tracker, relayer_wallets |
| **Relayer 지갑 등록** | 새 Relayer EOA를 meta transaction 컨트랙트에 relayer로 추가 (addRelayer TX) | relayer_wallets |
| **Relayer 지갑 해제** | 컨트랙트에서 relayer 제거 (removeRelayer TX) | relayer_wallets |
| **Relayer 목록 조회** | 컨트랙트에 등록된 relayer 목록 온체인 조회 | — |
| **논스 관리** | nonce_tracker 락 획득 → 논스 할당 → TX 전송 → 논스 확인 | nonce_tracker |
| **Relayer 선택** | network_id + relayer_role 기반 활성 Relayer 선택 (priority/weight) | relayer_wallets |
| **approve 상태 확인** | 집금/출금 실행 전 해당 지갑의 approve 상태 확인. APPROVED가 아니면 스킵(DEFERRED) | wallet_approvals |
| **가스 추정** | TX 실행 전 가스 추정 (estimateGas) | — |
| **TX 상태 추적** | 브로드캐스트 후 pending TX 모니터링, 타임아웃 처리 | relayer_wallets (current_pending_tx_count) |
| **TX 재전송** | 가스 부족/논스 충돌 시 가스 올려서 재전송 | nonce_tracker |
| **배치 집금** | 여러 집금 건을 묶어 순차 실행 (batch_id) | collection_queue |

### 핵심 플로우 (집금 — DB 폴링)

```
1. [폴링] collection_queue에서 status=QUEUED 건 조회
2. 해당 지갑 wallet_approvals 확인
   → APPROVED가 아니면 → DEFERRED로 변경, 스킵
3. relayer_wallets에서 COLLECTION 역할 Relayer 선택
4. nonce_tracker 락 획득 (Redis 분산 락)
5. 논스 할당 (next_nonce)
6. transferFrom TX 서명 (Relayer 개인키 = KMS)
7. TX 브로드캐스트
8. collection_queue 상태 → COLLECTING, tx_hash 기록
9. nonce_tracker.next_nonce 증가
10. 락 해제
11. (확인은 blockchain_monitor → Webhook 수신 서버로 돌아옴)
```

### 핵심 플로우 (Relayer 지갑 등록)

```
1. Admin API → POST /relayer/register {network_id, wallet_address_id, relayer_role}
2. relayer_wallets에 레코드 INSERT (status=REGISTERING)
3. meta transaction 컨트랙트의 addRelayer(address) TX 실행
4. TX 확인 후 relayer_wallets.status → ACTIVE
```

### DB 접근

- **MySQL**: 읽기/쓰기 — collection_queue(폴링/상태 업데이트), withdrawals(폴링/상태 업데이트), nonce_tracker(논스 관리), relayer_wallets(선택/등록/모니터링), wallet_approvals(approve 상태 확인), wallet_addresses(주소 조회)
- **Redis**: 분산 락 (논스 동시성), Relayer 상태 캐시

---

## 10. 지갑 활성화 서버

> **기술**: Node.js / TypeScript / ethers.js, tronweb
> **인증**: 없음 (내부 전용, 외부 API 없음)
> **대상**: Blockchain Nodes (외부)
> **인스턴스**: 1+ (비동기 처리)
> **동작 방식**: **DB 폴링** (wallet_approvals 상태 기반)
> **트리거**: 첫 입금 발생 시 Webhook 수신 서버가 wallet_approvals에 PENDING INSERT

### 역할

지갑의 활성화를 전담한다. 활성화 요청(wallet_approvals PENDING)을 DB 폴링으로 감지하여, 체인별 활성화 절차를 자동 실행한다. 생성 시점이 아닌 **첫 입금 발생 시점**에 활성화하여 불필요한 가스비 낭비를 방지한다.

### 체인별 활성화 절차

| 체인 | 절차 | 설명 |
|------|------|------|
| **ERC (ETH/BSC/Polygon)** | ① 가스비 전송 → ② approve TX | GAS 지갑 → 대상 지갑으로 네이티브 코인(ETH/BNB/POL) 전송 → 대상 지갑에서 ERC-20 approve(relayer, MAX_UINT) 실행 |
| **TRC (TRON)** | ① 가스비 렌탈(에너지/대역폭) → ② 활성화 → ③ approve TX | 에너지/대역폭 렌탈 → TRC-20 계정 활성화 → approve(relayer, MAX_UINT) 실행 |

### 주요 기능

| 기능 | 설명 | 관련 테이블 |
|------|------|------------|
| **활성화 요청 폴링** | wallet_approvals에서 status=PENDING 건 주기적 폴링 | wallet_approvals |
| **ERC 가스 지원** | GAS 지갑 → 대상 지갑으로 네이티브 코인 전송 (approve 가스비) | wallet_approvals, wallet_balances |
| **ERC Approve 실행** | 대상 지갑에서 Relayer 주소로 ERC-20 approve(MAX_UINT) 실행 | wallet_approvals |
| **TRC 가스비 렌탈** | TRON 에너지/대역폭 렌탈 (TRX 스테이킹 또는 외부 렌탈) | wallet_approvals |
| **TRC 계정 활성화** | TRON 계정 활성화 (첫 TRX 전송으로 계정 생성) | wallet_approvals |
| **TRC Approve 실행** | 대상 지갑에서 Relayer 주소로 TRC-20 approve(MAX_UINT) 실행 | wallet_approvals |
| **상태 관리** | PENDING → GAS_SUPPORTING → GAS_READY → APPROVING → APPROVED/FAILED 상태 전이 | wallet_approvals |
| **재시도** | 실패 건 자동 재시도 (가스 가격 조정, 에너지 부족 시 재렌탈) | wallet_approvals |
| **배치 처리** | 폴링 시 다수 PENDING 건을 순차적으로 처리 | wallet_approvals |

### 핵심 플로우 (ERC 지갑 활성화)

```
1. [폴링] wallet_approvals에서 status=PENDING, network=ERC 건 조회
2. 상태 → GAS_SUPPORTING
3. GAS 지갑에서 대상 지갑으로 가스비 전송 (네이티브 코인)
4. 가스비 TX 확인 대기 (blockchain_monitor → Webhook 수신 서버)
5. 상태 → GAS_READY → APPROVING
6. 대상 지갑에서 approve(relayer_address, MAX_UINT) TX 실행
7. wallet_approvals.approve_tx_hash 기록
8. approve TX 확인 대기 (blockchain_monitor → Webhook 수신 서버)
9. 상태 → APPROVED
10. (이후 Relayer 서버가 해당 지갑의 집금 실행 가능)
```

### 핵심 플로우 (TRC 지갑 활성화)

```
1. [폴링] wallet_approvals에서 status=PENDING, network=TRON 건 조회
2. 상태 → GAS_SUPPORTING
3. 에너지/대역폭 렌탈 (TRX 스테이킹 또는 외부 렌탈 API)
4. GAS 지갑 → 대상 지갑으로 소량 TRX 전송 (계정 활성화)
5. 계정 활성화 확인
6. 상태 → GAS_READY → APPROVING
7. 대상 지갑에서 approve(relayer_address, MAX_UINT) TX 실행
8. approve TX 확인 대기
9. 상태 → APPROVED
```

### DB 접근

- **MySQL**: 읽기/쓰기 — wallet_approvals(폴링/상태 관리), wallet_addresses(주소 조회), relayer_wallets(APPROVE Relayer 주소 조회), nonce_tracker(논스 관리), wallet_balances(GAS 잔액 확인)
- **Redis**: 분산 락 (논스)

> **참고**: 이 서버는 API를 제공하지 않는다. DB 폴링으로 자체 동작하며, 다른 서버는 wallet_approvals에 PENDING INSERT만 하면 된다.

---

## 11. Admin Front

> **기술**: Vue 3 / Vite / Static 호스팅 (CDN)
> **인증**: JWT (Admin API 서버 발급)
> **대상**: 내부 운영팀 (Super Admin)
> **인스턴스**: Static (CDN 배포)

### 역할

Super Admin 콘솔 웹 애플리케이션. Admin API 서버와만 통신한다.

### 주요 화면

| 화면 | 설명 |
|------|------|
| 로그인 | 이메일 + 비밀번호 + 2FA |
| 대시보드 | 전체 입출금 현황, 네트워크 상태, 실시간 모니터링 |
| 파트너 관리 | 파트너 목록, 상세, 생성, 수정, 정지/해제 |
| 출금 승인 | 승인 대기 목록, 승인/거부, 이력 |
| 거래 내역 | 전체 입금/출금 내역, 필터, 검색 |
| 미식별 입금 | 미식별 입금 목록, 수동 매칭, 환불 |
| CS 매칭 요청 | 파트너 CS 요청 목록, 처리 |
| 지갑 모니터링 | MASTER/GAS/Relayer 잔액 현황 |
| Relayer 관리 | Relayer 상태, 논스, 활성화/비활성화 |
| 시스템 설정 | 글로벌 설정, 네트워크 설정 |
| 감사 로그 | 관리자 활동 이력 |

### DB 접근

- 없음 (API 서버 경유)

---

## 12. Partner Front

> **기술**: Vue 3 / Vite / Static 호스팅 (CDN)
> **인증**: JWT (Partner API 서버 발급)
> **대상**: 파트너 관리자
> **인스턴스**: Static (CDN 배포)

### 역할

파트너 콘솔 웹 애플리케이션. Partner API 서버와만 통신한다. 자기 파트너 데이터만 조회/관리 가능.

### 주요 화면

| 화면 | 설명 |
|------|------|
| 로그인 | 이메일 + 비밀번호 + 2FA |
| 대시보드 | 파트너 입출금 현황, 잔액 요약, Axim 결제 현황 |
| **사용자 관리** | 사용자 목록, 검색 (partner_user_id) |
| **사용자 상세** | 입금 지갑, 입금/출금 내역, Axim 연결 상태, Axim 결제 내역 통합 뷰 |
| 입금 내역 | 입금 목록, 상세, 필터 (기간/상태/체인/사용자) |
| **입금 지갑 생성** | 사용자별 입금 지갑 주소 직접 발급 |
| **결제 링크 생성** | 소수점 매칭 입금 세션 → 결제 링크 URL 발급 |
| 출금 내역 | 출금 목록, 상세, 상태 추적 |
| 출금 요청 | 콘솔에서 직접 출금 |
| **출금 취소** | REQUESTED/PENDING_APPROVAL 출금 건 취소 |
| 화이트리스트 | 출금 주소 화이트리스트 관리 |
| **Axim 설정** | Axim API Key/Secret, site_id 설정, 활성화/비활성화 |
| **Axim 결제 요청** | Axim 연결 사용자에게 결제 요청 전송 |
| **Axim 결제 내역** | Axim 결제 목록, 상세, 상태 추적 |
| **외부 지갑 관리** | Axim/MetaMask 연결 지갑 목록, 상세, 연결 해지 |
| 알림 설정 | Telegram 채팅방, Webhook URL, 이벤트 구독 |
| API 키 관리 | API Key/Secret 조회, 재발급 |
| CS 매칭 요청 | 미식별/만료 건 매칭 요청, 진행 상태 조회 |

### DB 접근

- 없음 (API 서버 경유)

---

## 13. Widget Front

> **기술**: Vue 3 / Vite / Static 호스팅 (CDN)
> **인증**: 파트너 API Key (초기화 시)
> **대상**: 파트너 사용자 (최종 사용자)
> **인스턴스**: Static (CDN, 고가용성)

### 역할

파트너 사이트에 임베드되는 결제 위젯. Widget API 서버와만 통신한다.

### 주요 화면/기능

| 화면 | 설명 |
|------|------|
| 네트워크/통화 선택 | 지원 체인, 토큰 선택 |
| 입금 안내 | 입금 주소, QR코드, 소수점 매칭 금액 표시 |
| 타이머 | 세션 만료 카운트다운 |
| 상태 폴링 | 입금 감지 → 확인 → 완료 실시간 표시 |
| 완료/만료 | 입금 완료 또는 세션 만료 안내 |
| **Axim 연결** | Axim 지갑 연결 UI (connectWalletToken 기반) |
| **Axim Pay 결제** | Axim 연결 사용자에게 결제 요청 전송, 결제 상태 실시간 표시 |
| **네트워크 추천** | Axim 연결 사용자의 잔액 기반 최적 네트워크 자동 추천 |

### DB 접근

- 없음 (API 서버 경유)

---

## 14. 텔레그램 봇 서버

> **기술**: Node.js / TypeScript / node-telegram-bot-api
> **인증**: Telegram Bot Token
> **대상**: Telegram 사용자 (파트너 관리자)
> **인스턴스**: 1 (봇당 1개)

### 역할

Telegram Bot의 **수신 채널**. 파트너 관리자가 텔레그램 봇에 명령을 보내면 이를 처리한다. 메시지 **발송**은 텔레그램 메시지 서버(#6)가 담당하고, 이 서버는 **수신 + 인터랙션**을 담당한다.

### 주요 기능

| 기능 | 설명 | 관련 테이블 |
|------|------|------------|
| 봇 명령어 수신 | /start, /stop, /balance, /recent, /status, /subscribe, /unsubscribe, /help | — |
| 채팅방 등록 | /start {partner_code} → chat_id 자동 획득, 파트너 연결 | partner_telegram_configs |
| 연결 해제 | /stop → is_active = FALSE | partner_telegram_configs |
| 잔액 조회 | /balance → 파트너 MASTER 잔액 조회 응답 | wallet_balances, wallet_addresses |
| 최근 거래 조회 | /recent → 최근 입출금 내역 응답 | deposits, withdrawals |
| 알림 설정 | /subscribe, /unsubscribe → 이벤트 구독 관리 | partner_telegram_subscriptions |
| 상태 조회 | /status → 시스템 상태, Relayer 상태 요약 | relayer_wallets, blockchain_networks |

### DB 접근

- **MySQL**: 읽기/쓰기 — partner_telegram_configs(채팅방 등록/해제), partner_telegram_subscriptions(이벤트 구독), wallet_balances(잔액 조회), wallet_addresses(MASTER 지갑 조회), deposits/withdrawals(최근 거래), relayer_wallets/blockchain_networks(상태 조회), partners(파트너 코드 검증)
- **Redis**: ❌

---

## 서버 간 통신 요약

```
┌──────────────────────────────────────────────────────────────────────────────┐
│                                                                              │
│  [Frontend]                [Spring Boot]              [Node.js]              │
│                                                                              │
│  Admin Front ──────→ Admin API ──────────→ Blockchain API ──→ Blockchain     │
│  Partner Front ────→ Partner API            Relayer API ─────→ Blockchain    │
│  Widget Front ─────→ Widget API             지갑 활성화 서버 ──→ Blockchain  │
│                                                                              │
│                      Open API ──→ Axim Pay API (결제 요청/조회)             │
│                      Widget API ──→ Axim Pay API (연결/결제/네트워크)       │
│                                                                              │
│                      Webhook 수신 ←──── blockchain_monitor (외부)            │
│                      Webhook 수신 ←──── Axim Pay (Webhook: 연결/결제 이벤트)│
│                        │                                                     │
│                        ├──[DB] wallet_approvals INSERT → 지갑 활성화 서버    │
│                        ├──[DB] collection_queue INSERT → Relayer API         │
│                        ├──→ Blockchain API (TX 조회)                         │
│                        └──→ 텔레그램 메시지 서버 (알림)                       │
│                                                                              │
│                      스케줄러 ────→ Blockchain API (잔액 동기화)              │
│                        └──→ 텔레그램 메시지 서버 (시스템 경고)                │
│                                                                              │
│                      Open API ──→ Blockchain API (지갑 조회)                 │
│                      Open API ──→ Partner Servers (콜백)                     │
│                                                                              │
│                      Admin API ──→ Relayer API (Relayer 지갑 등록/해제)      │
│                                                                              │
│                      텔레그램 메시지 서버 ──→ Telegram Bot API (외부)         │
│                      텔레그램 봇 서버 ←───── Telegram Bot API (외부)         │
│                                                                              │
│  ═══════════════════════════════════════════════════════════════════════════  │
│  [DB 기반 비동기 연동 — API 호출 아닌 상태 폴링]                              │
│                                                                              │
│  Webhook 수신 서버 ──[INSERT]──→ wallet_approvals ──[폴링]──→ 지갑 활성화    │
│  Webhook 수신 서버 ──[INSERT]──→ collection_queue ──[폴링]──→ Relayer API    │
│  Spring Boot 서버 ───[INSERT]──→ withdrawals(APPROVED)──[폴링]──→ Relayer   │
│                                                                              │
│  ═══════════════════════════════════════════════════════════════════════════  │
│  [Data Layer]                                                                │
│                                                                              │
│  MySQL 8.0 ←── 모든 Spring Boot + 모든 Node.js                              │
│  Redis ←────── 모든 Spring Boot + Node.js (일부)                             │
│                                                                              │
└──────────────────────────────────────────────────────────────────────────────┘
```

---

## 외부 시스템

### blockchain_monitor

> **관리**: 외부 운영팀
> **역할**: 블록체인 노드를 모니터링하여 TX 이벤트(입금, 출금 확인, 집금 확인 등)를 Webhook으로 Cryptoments에 전달
> **통신**: → Webhook 수신 서버 (HTTP POST)

### Axim Pay

> **서비스**: 암호화폐 결제/지갑 연동 플랫폼
> **API**: `https://pay.axim.one` (Open API)
> **인증**: API Key + HMAC-SHA256 (X-API-KEY, X-TIMESTAMP, X-ACCESS-TOKEN)
> **역할**: 사용자 지갑 연결(Connection), 결제 요청(Payment), 최적 네트워크 추천, Webhook 이벤트 전송

#### Axim Pay API 엔드포인트 (Cryptoments가 호출)

| 카테고리 | 엔드포인트 | 설명 |
|---------|-----------|------|
| **Connections** | GET /api/v1/open/connections | connectWalletToken으로 연결 정보 조회 |
| | GET /api/v1/open/connections/{connectId} | connectId로 연결 상태 조회 |
| **Payments** | POST /api/v1/open/payments | 결제 요청 생성 |
| | GET /api/v1/open/payments | 결제 목록 조회 (페이징) |
| | GET /api/v1/open/payments/{paymentId} | 결제 상세 조회 |
| | GET /api/v1/open/payments/{paymentId}/status | 결제 상태 조회 |
| | POST /api/v1/open/payments/{paymentId}/cancel | 대기 중 결제 취소 |
| **Networks** | GET /api/v1/open/networks/best | 최적 네트워크 추천 (잔액/TX 수 기반) |
| **Partners** | GET /api/v1/open/partners/me | 파트너 정보 조회 |
| | PUT /api/v1/open/partners/webhook-url | Webhook URL 설정 |
| | GET /api/v1/open/partners/deposit-wallets | 입금 지갑 목록 조회 |
| | POST /api/v1/open/partners/deposit-wallets | 입금 지갑 등록 |

#### Axim Webhook 이벤트 (Axim → Cryptoments)

| 이벤트 | 설명 |
|--------|------|
| `connection.succeeded` | 사용자 지갑 연결 완료 |
| `connection.failed` | 지갑 연결 실패 |
| `connection.revoked` | 지갑 연결 해제 |
| `payment.succeeded` | 결제 완료 (블록 확인 완료) |
| `payment.failed` | 결제 실패 |
| `payment.canceled` | 결제 취소 |
| `payment.expired` | 결제 만료 |

#### 지원 체인/통화

| 체인 | 통화 |
|------|------|
| ETH | USDT, USDC, ETH |
| TRON | USDT, USDC, TRX |
| BSC | USDT, USDC, BNB |
| POLYGON | USDT, USDC, POL |

---

## 기술 스택별 역할 분리 원칙

```
Spring Boot (Java 17)              Node.js (TypeScript)
─────────────────────              ────────────────────────
• 비즈니스 로직                     • 온체인 인터랙션 (조회 + 실행)
• API 인증/인가                     • TX 서명 · 전송 · 논스 관리
• 정책 검증                         • 지갑 주소 파생 (HD Wallet)
• Webhook 수신 · 분류               • Approve · 가스 지원
• 알림 발송 (Telegram, 콜백)        • 잔액 · TX 상태 조회
• 배치 · 스케줄                     • Telegram 봇 수신 · 인터랙션
• 관리 콘솔 API                     • ethers.js / tronweb SDK 활용

─────────────────────────────────────────────────────────
경계 원칙: "체인을 직접 만지는 건 Node.js, 나머지는 Spring Boot"
예외: 텔레그램 봇 서버 (Node.js) — 봇 SDK 편의성
─────────────────────────────────────────────────────────
```

---

## 변경 이력

| 버전 | 날짜 | 변경 내용 |
|------|------|----------|
| v1.0 | 2026-02-25 | 초안 작성 — 14개 컴포넌트 상세 명세 |
| v1.1 | 2026-03-06 | DDL v1.2 / CORE_LIBRARY / NODEJS_SERVERS 정합성 반영: ① §14 텔레그램 봇 명령어 `/register`→`/start {partner_code}` 통합, `/stop` 추가 ② `partner_notification_channels`→`partner_telegram_configs`, `partner_notification_subscriptions`→`partner_telegram_subscriptions` 테이블명 수정 ③ `wallet_assignments`→`wallet_addresses` 통합 반영 (DDL v1.2) ④ 문서 참조 추가 (CORE_LIBRARY, NODEJS_SERVERS, TECH_STACK_BOUNDARY, SERVICE_MODULES) |