# Node.js ↔ DDL v1.4 / Java 크로스체크 리포트

> **기준**: DDL v1.4 (2072줄, 40개 테이블) + Java Entity/Enum이 소스 오브 트루스
> **대상**: Node.js 패키지 (`blockchain-api`, `common`, `relayer-api`, `wallet-activator`, `telegram-bot`)
> **작성일**: 2026-03-16

---

## 요약

| 심각도 | 건수 | 설명 |
|--------|------|------|
| 🟠 HIGH | 4 | Enum 값 불일치, 컬럼명 차이 |
| 🟡 MEDIUM | 4 | 추가 enum 값, 스펠링, 추가 컬럼 |
| ✅ MATCH | 다수 | v1.3/v1.4에서 Node.js 실구현 반영 완료 |

**v1.4 DDL에서 이미 반영된 것들** (이전 v1.0 기준 리포트에서 CRITICAL로 분류했던 항목):
- `blockchain_networks`: `chain_symbol`, `network_type`, `rpc_url`, `rpc_url_fallback`, `block_confirmation_count` ✅
- `relayer_wallets`: `relayer_role`, `priority`, `current_pending_tx_count`, `max_pending_tx_count` ✅
- `collection_queue`: `error_message`, `retry_count`, `relayer_wallet_id`, `tx_hash` ✅
- `withdrawals`: `relayer_wallet_id`, `error_message` ✅
- `wallet_approvals`: `gas_tx_hash`, `error_message`, `retry_count`, `status`(GAS_SUPPORTING/GAS_READY/DEFERRED) ✅
- `collection_queue.status`: `BROADCASTING` ✅
- `gas_cost_records.tx_type`: `ENERGY_RENTAL` ✅
- `relayer_contracts` 테이블 ✅
- `wallet_addresses.wallet_type`: `ADMIN` ✅

---

## 🟠 HIGH — Enum 값 불일치 (Node.js 수정 필요)

### H-1. `relayer_wallets.status` — 값 불일치

| DDL v1.4 | Node.js | 비고 |
|----------|---------|------|
| `ACTIVE` | `ACTIVE` | ✅ |
| `PAUSED` | `INACTIVE` | ❌ 값 불일치 |
| — | `REGISTERING` | ❌ `status`가 아닌 `registration_status` 값 |
| — | `DEREGISTERING` | ❌ `status`가 아닌 `registration_status` 값 |

**원인**: Node.js에서 `status`와 `registration_status`를 혼용.

**DDL 정의**:
- `status`: `ACTIVE / PAUSED`
- `registration_status`: `PENDING / REGISTERED / REVOKED`

> **🔧 조치**:
> 1. `INACTIVE` → `PAUSED`
> 2. `REGISTERING`/`DEREGISTERING`은 `registration_status` 컬럼으로 분리 (DDL에는 `PENDING/REGISTERED/REVOKED`만 있으므로 `REGISTERING`/`DEREGISTERING`을 `PENDING`으로 매핑하거나 DDL 추가 논의)

---

### H-2. `withdrawals.withdrawal_type` — 값 축약

| DDL v1.4 | Node.js | 비고 |
|----------|---------|------|
| `USER_PAYOUT` | `USER` | ❌ 축약 |
| `REFUND` | `REFUND` | ✅ |
| `PARTNER_WITHDRAW` | `PARTNER` | ❌ 축약 |
| `SETTLEMENT_WITHDRAW` | — | Node.js 미사용 (OK) |
| `INTERNAL` | — | Node.js 미사용 (OK) |

> **🔧 조치**: `USER` → `USER_PAYOUT`, `PARTNER` → `PARTNER_WITHDRAW`

---

### H-3. `wallet_addresses.status` — 추가 값

| DDL v1.4 | Node.js | 비고 |
|----------|---------|------|
| `ACTIVE` | `ACTIVE` | ✅ |
| `INACTIVE` | `INACTIVE` | ✅ |
| — | `SUSPENDED` | ❌ DDL에 없음 |

DDL은 `ACTIVE / INACTIVE`만 정의.

> **🔧 조치**: `SUSPENDED` 제거. 필요 시 DDL 추가 논의.

---

### H-4. `nonce_tracker` — Node.js 전용 컬럼

| Node.js 컬럼 | DDL v1.4 존재 | 비고 |
|-------------|--------------|------|
| `network_id` | ❌ 없음 | `wallet_address_id` → `wallet_addresses.network_id` JOIN 가능 |

> **🔧 조치**: JOIN으로 대체하거나, 쿼리 편의상 필요하면 DDL 추가 논의.

---

## 🟡 MEDIUM — 컬럼명/스펠링/추가값

### M-1. `collection_queue.status` — `CANCELLED` 누락

| DDL v1.4 상태값 | Node.js | 비고 |
|-----------------|---------|------|
| `QUEUED` | `QUEUED` | ✅ |
| `COLLECTING` | `COLLECTING` | ✅ |
| `BROADCASTING` | `BROADCASTING` | ✅ |
| `CONFIRMED` | `COMPLETED` | ❌ DDL은 `CONFIRMED` |
| `FAILED` | `FAILED` | ✅ |
| `DEFERRED` | `DEFERRED` | ✅ |
| — | — | DDL에 `CANCELLED` 없음 (삭제됨) |

> **🔧 조치**: `COMPLETED` → `CONFIRMED` (DDL v1.4 기준)

---

### M-2. `withdrawals.status` — 스펠링 차이

| DDL v1.4 | Node.js | 비고 |
|----------|---------|------|
| `CANCELLED` | `CANCELED` | ❌ L 1개 vs 2개 |

> **🔧 조치**: `CANCELED` → `CANCELLED`

---

### M-3. `wallet_keys.encryption_key_version` — 컬럼명 차이

| DDL v1.4 컬럼명 | Node.js 컬럼명 | 비고 |
|-----------------|---------------|------|
| `encryption_key_version` | `key_version` | ❌ 축약 |

> **🔧 조치**: `key_version` → `encryption_key_version`

---

### M-4. `wallet_index_manager` — 컬럼 차이

| DDL v1.4 컬럼명 | Node.js 컬럼명 | 비고 |
|-----------------|---------------|------|
| `current_index` | `last_index` | ❌ 불일치 |
| — | `hd_wallet_id` | ❌ DDL에 없음 |

> **🔧 조치**: `last_index` → `current_index`, `hd_wallet_id` 사용 여부 검토.

---

## ✅ 정상 일치 확인 (v1.4 DDL = Node.js)

| 항목 | DDL v1.4 | Node.js | 결과 |
|------|----------|---------|------|
| `blockchain_networks.chain_symbol` | `chain_symbol` | `chain_symbol` | ✅ |
| `blockchain_networks.network_type` | `EVM / TVM` | `EVM / TVM` | ✅ |
| `blockchain_networks.rpc_url` | ✅ 존재 | ✅ 사용 | ✅ |
| `blockchain_networks.block_confirmation_count` | `block_confirmation_count` | `block_confirmation_count` | ✅ |
| `relayer_wallets.relayer_role` | `COLLECTION / WITHDRAWAL` | `COLLECTION / WITHDRAWAL` | ✅ |
| `relayer_wallets.priority` | ✅ 존재 | ✅ 사용 | ✅ |
| `relayer_wallets.current_pending_tx_count` | ✅ 존재 | ✅ 사용 | ✅ |
| `relayer_wallets.max_pending_tx_count` | ✅ 존재 | ✅ 사용 | ✅ |
| `collection_queue.tx_hash` | `tx_hash` (v1.4) | `tx_hash` | ✅ |
| `collection_queue.relayer_wallet_id` | ✅ 존재 | ✅ 사용 | ✅ |
| `collection_queue.error_message` | ✅ 존재 | ✅ 사용 | ✅ |
| `collection_queue.retry_count` | ✅ 존재 | ✅ 사용 | ✅ |
| `withdrawals.relayer_wallet_id` | ✅ 존재 | ✅ 사용 | ✅ |
| `withdrawals.error_message` | ✅ 존재 | ✅ 사용 | ✅ |
| `wallet_approvals.status` | `status` (not approve_status) | `status` | ✅ |
| `wallet_approvals.gas_tx_hash` | ✅ 존재 | ✅ 사용 | ✅ |
| `wallet_approvals.error_message` | ✅ 존재 | ✅ 사용 | ✅ |
| `wallet_approvals.retry_count` | ✅ 존재 | ✅ 사용 | ✅ |
| `wallet_approvals` 상태값 | `GAS_SUPPORTING/GAS_READY/DEFERRED` | 동일 | ✅ |
| `gas_cost_records.tx_type` | `ENERGY_RENTAL` 포함 | 동일 | ✅ |
| `wallet_addresses.wallet_type` | `ADMIN` 포함 | 동일 | ✅ |
| `relayer_contracts` 테이블 | ✅ 존재 | ✅ 사용 | ✅ |

---

## Node.js 수정 체크리스트

| # | 파일 | 변경 내용 | 심각도 |
|---|------|----------|--------|
| 1 | `types/wallet.ts` | `RelayerStatus`: `INACTIVE` → `PAUSED` | 🟠 |
| 2 | `types/wallet.ts` | `RelayerStatus`: `REGISTERING`/`DEREGISTERING` 분리 → `registration_status`로 | 🟠 |
| 3 | `types/tx.ts` | `WithdrawalType`: `USER` → `USER_PAYOUT`, `PARTNER` → `PARTNER_WITHDRAW` | 🟠 |
| 4 | `types/wallet.ts` | `WalletAddressStatus`: `SUSPENDED` 제거 | 🟠 |
| 5 | `types/tx.ts` | `CollectionStatus`: `COMPLETED` → `CONFIRMED` | 🟡 |
| 6 | `types/tx.ts` | `WithdrawalStatus`: `CANCELED` → `CANCELLED` | 🟡 |
| 7 | `repositories/WalletKeyRepo.ts` 등 | `key_version` → `encryption_key_version` | 🟡 |
| 8 | `repositories/WalletIndexRepo.ts` 등 | `last_index` → `current_index`, `hd_wallet_id` 검토 | 🟡 |
| 9 | `repositories/NonceTrackerRepo.ts` | `network_id` 컬럼 사용 여부 검토 (JOIN 대체 또는 DDL 추가) | 🟡 |

---

## Java Entity ↔ DDL v1.4 불일치 (DDL_V1.4_REVIEW.md 참조)

DDL v1.4에 맞게 Java 측도 업데이트가 필요한 항목:

| 항목 | 상태 | 비고 |
|------|------|------|
| `PartnerExchangeRatePolicy` Entity/Repository | ❌ 미생성 | v1.4 신규 테이블 |
| `RelayerContract` Entity/Repository | ❌ 미생성 | v1.3 신규 테이블 |
| `Withdrawal.relayerWalletId` 필드 | ❌ 누락 | v1.3 추가 컬럼 |
| `Withdrawal.errorMessage` 필드 | ❌ 누락 | v1.3 추가 컬럼 |
| 여러 Entity의 v1.3/v1.4 추가 컬럼 | ⚠️ 검토 필요 | 상세는 DDL_V1.4_REVIEW.md |

---

## DB 폴링 상태 전이 계약 (Spring Boot ↔ Node.js)

| 테이블 | Spring Boot INSERT | Node.js 폴링 | 중간 상태 (Node.js 관리) | 최종 상태 |
|--------|-------------------|-------------|----------------------|----------|
| `collection_queue` | `QUEUED` | `QUEUED` | `COLLECTING → BROADCASTING` | `CONFIRMED / FAILED` |
| `withdrawals` | `APPROVED` | `APPROVED` | `PROCESSING → BROADCASTING` | `CONFIRMED / FAILED` |
| `wallet_approvals` | `PENDING` | `PENDING`, `GAS_READY` | `GAS_SUPPORTING → GAS_READY → APPROVING` | `APPROVED / FAILED` |

> Spring Boot는 최초 상태 INSERT와 최종 상태 READ만 담당.
> 중간 상태 전이는 모두 Node.js가 관리.

---

## API 계약 (Spring Boot → Node.js)

### blockchain-api (Port 3001) — 읽기 전용

| Endpoint | 용도 |
|----------|------|
| `GET /api/wallet/derive` | HD 지갑 주소 파생 |
| `GET /api/balance/:address` | 온체인 잔액 조회 |
| `GET /api/tx/status/:txHash` | TX 상태 조회 |
| `GET /api/gas/estimate` | 가스비 추정 |

### relayer-api (Port 3002) — Admin 전용

| Endpoint | 용도 |
|----------|------|
| `POST /api/relayer/register` | Relayer 온체인 등록 |
| `POST /api/relayer/unregister` | Relayer 해제 |
| `GET /api/relayer/list` | Relayer 목록 |