MIJI DApp Server Docs

IMPLEMENTATION_GUIDE_BILLING.md: 코인 시세 정산 로직 가이드

1. 📋 MongoDB 스키마 업데이트 (필수)

PLAN.md의 MintingOrder 스키마를 다음과 같이 확장해야 합니다. (기존 필드에 4개 필드 추가)

필드 타입 설명
total_fee_avax String (신규) 소모된 총 수수료 (AVAX 단위로 환산, BigNumber String)
avax_price_usd Number (신규) TX 완료 시점의 1 AVAX당 달러 가격
total_fee_usd Number (신규) 최종 정산 달러 금액
avax_price_krw Number (신규) TX 완료 시점의 1 AVAX당 원화 가격
total_fee_krw Number (신규) 최종 정산 원화 금액

2. 📡 CoinGecko API 전략 및 캐싱

CoinGecko의 무료 티어(월 10K 호출)를 효율적으로 사용하고 성능을 확보하기 위해 Redis 캐싱을 필수로 적용합니다.

2-1. 사용 API Endpoint

API 기능 엔드포인트 사용 파라미터
AVAX 시세 조회 /simple/price ids=avalanche-2 (AVAX 코인 ID)
통화 단위 N/A vs_currencies=usd,krw (USD 및 KRW 동시 요청)
Redis 캐시 키 N/A pricing:avax:usd_krw (고정 캐시 키)

2-2. 캐싱 정책 (최우선 순위)

  1. TTL (Time-To-Live): Redis 캐시의 유효 기간은 60초 ~ 180초 (1분 ~ 3분)로 설정합니다.
  2. 최초 조회: 큐 프로세서가 트랜잭션을 처리할 때, 가장 먼저 Redis에서 pricing:avax:usd_krw 키를 조회해야 합니다.
  3. 캐시 히트: 캐시 값이 존재하면 CoinGecko API 호출을 생략하고 캐시된 시세를 사용합니다.
  4. 캐시 미스: CoinGecko API를 호출하고, 그 결과를 DB에 사용하기 전에 Redis에 60~180초 TTL로 저장합니다.

3. ⚙️ 민팅 프로세서 (T-120/T-121) 구현 상세 가이드

MintingProcessor가 트랜잭션 성공(CONFIRMED 상태)을 확인한 직후, 다음의 4단계를 순차적으로 실행해야 합니다.

단계 1: 시세 데이터 조회 (CoinGeckoService)

  1. Redis 조회: Redis에서 pricing:avax:usd_krw 키를 조회합니다.
  2. API 호출 (캐시 미스 시): 캐시가 없으면, CoinGecko API를 호출하여 { “avalanche-2”: { “usd”: 20.50, “krw”: 28000 } } 형태의 데이터를 가져와 Redis에 캐시합니다.

단계 2: AVAX 단위 총액 계산 (BigNumber 사용)

트랜잭션에 기록된 mintingGasUsed는 Wei 단위이므로, 18자리(10^18)로 나누어 AVAX 단위로 환산해야 합니다.

  1. 라이브러리: ethers.js의 BigNumber 유틸리티 또는 BigNumber.js를 사용합니다.

  2. 계산:

    \[Total\_{AVAX} \= \\frac{mintingGasUsed \\text{ (Wei)}}{\\text{10}^{18}}\]
  3. 계산된 값을 정밀도 높은 문자열 형태로 total_fee_avax 필드에 저장합니다.

단계 3: 법정 화폐 금액 계산 및 적재

이전 단계에서 얻은 시세와 총액을 곱하여 정산 금액을 계산합니다.

  1. USD 계산:

    \[Total\_{USD} \= Total\_{AVAX} \\times avax\\\_price\\\_usd\]

  2. KRW 계산:

    \[Total\_{KRW} \= Total\_{AVAX} \\times avax\\\_price\\\_krw\]

  3. 계산된 Total_{USD}와 Total_{KRW}를 total_fee_usd와 total_fee_krw 필드에 저장합니다.

단계 4: DB 업데이트 완료

MintingOrder 문서의 status를 CONFIRMED로 변경하며, 새로 계산된 5개 필드(total_fee_avax, avax_price_usd, total_fee_usd, avax_price_krw, total_fee_krw)를 모두 포함하여 DB를 업데이트합니다.

4. 📝 PLAN.md 업데이트 지침

P3-3 (TX 상태 추적 및 로깅) 태스크의 상세 내용에 다음 내용이 추가되어야 합니다.