Midnight SDK v4 마이그레이션을 통한 패키지 통합 및 아티팩트 버전 불일치 해결

Handling Midnight SDK Breaking Changes: A Developer's Upgrade Playbook

Harrie2026년 5월 12일7분intermediate

AI 요약

Context

기존 Midnight SDK v3.x 버전의 파편화된 6개 패키지 구조로 인한 의존성 관리 복잡성 증가. 컴파일된 Compact 아티팩트의 버전 태그와 SDK 런타임 버전 간 불일치로 발생하는 CompactError의 구조적 제약 발생.

6개의 개별 패키지를 @midnight-ntwrk/midnight-js 단일 Barrel Export 구조로 통합하여 의존성 단순화
Wallet 초기화 로직 내 walletProvider 옵션을 privateStoragePasswordProvider로 명명 변경하여 책임 범위 명확화
balanceTx와 signTx로 분리되었던 트랜잭션 처리 과정을 balanceAndSign 단일 API로 병합하여 호출 단계 최적화
.compact 파일 상단에 pragma language_version 명시를 강제하여 컴파일러 버전 간 하위 호환성 제어
기존 v3.x 아티팩트와 v4.x 런타임 간 Version Mismatch 해결을 위한 managed/ 디렉토리 완전 삭제 후 재컴파일 프로세스 수립
CLI 도구 명칭을 compact compile에서 compactc로 변경하여 툴체인 실행 경로 최적화

실천 포인트

1. npm list 및 outdated 명령을 통한 의존성 사전 감사 수행

2. package.json 내 구버전 패키지 완전 제거 후 단일 Barrel 패키지로 대체

3. node_modules 및 managed/ 내 스태일 아티팩트 강제 삭제

4. .compact 파일 내 pragma 버전 선언 확인 및 최신 버전 반영

5. compact update 실행 후 ~/.compact/bin 경로의 PATH 설정 검증

태그