Skip to main content
Version: v1

Midnight.js v3.0.0 release notes

  • Version: v3.0.0
  • Date: December 17, 2025
  • Environment: Preview, Preprod

High-level summary​

Midnight.js의 주요 업그레이드입니다. 암호화 저장소 보안 모델, 비동기 트랜잭션 처리, 개선된 트랜잭션 워크플로가 포함되어 있습니다. v2.x에서 업그레이드하는 개발자는 호환성을 깨는 변경과 마이그레이션 단계를 반드시 확인하세요.

Audience​

다음에 해당하는 개발자가 확인해야 합니다:

  • Midnight.js로 애플리케이션이나 스마트 컨트랙트를 개발하는 경우
  • LevelPrivateStateProvider로 private state 저장소를 관리하는 경우
  • 동기식 트랜잭션 제출 또는 컨트랙트 호출을 사용하는 경우
  • 인덱서와 통합하는 경우

Summary of updates​

  • 암호화된 private state 저장소 도입 (비밀번호 제공자 설정 가능)
  • 트랜잭션 제출/컨트랙트 호출을 비동기 API로 전환
  • 명시적 트랜잭션 상태를 가진 새 증명 레시피 시스템 추가
  • 상위 레벨 제출 헬퍼로 트랜잭션 워크플로 간소화
  • 비차폐(unshielded) NIGHT 토큰 잔액 조회 지원
  • 트랜잭션 TTL(유효 기간) 지원
  • Compact 컴파일러/런타임 의존성 업데이트
  • ESM/CommonJS 패키지 호환성 개선

New features​

추가된 기능의 상세 내역입니다.

Storage encryption​

Private state 저장소가 이제 명시적 인증 설정과 함께 AES-256-GCM 암호화를 사용합니다.

보안이 강화되고 시크릿 매니저와 통합할 수 있습니다.

Configurable password provider​

암호화된 저장소를 위한 PrivateStoragePasswordProvider를 지원합니다. 개발자는 다음과 같이 활용할 수 있습니다:

  • 저장소 암호화를 지갑과 분리
  • 커스텀 비밀번호 관리
  • 보안 시크릿 매니저 연동
  • 유연한 폴백 전략 구현

Async transaction handling​

트랜잭션 제출과 컨트랙트 호출이 비동기 실행을 지원합니다.

주요 장점:

  • 완료까지 논블로킹 대기
  • 향상된 오류 처리
  • 최신 비동기 워크플로와 자연스러운 통합

모든 submitTx 및 contract.call.* 호출에 await을 사용해야 합니다.

Enhanced proving recipe system​

트랜잭션 증명 파이프라인이 세 가지 명시적 상태를 가진 새로운 BalancedProvingRecipe 유니온 타입으로 재설계되었습니다:

  • TransactionToProve
  • BalanceTransactionToProve
  • NothingToProve

트랜잭션 상태를 명시적으로 관리하여 제출 시 잘못된 가정을 방지합니다.

High-level transaction functions​

밸런싱, 증명, 제출을 내부적으로 처리하는 헬퍼 함수로 트랜잭션 라이프사이클을 간소화합니다:

  • submitDeployTx
  • submitCallTx

Unshielded NIGHT token support​

공개 인덱서를 통해 비차폐 NIGHT 토큰 잔액을 조회할 수 있습니다.

Transaction TTL support​

밸런싱 시 트랜잭션에 유효 기간(TTL)을 설정할 수 있습니다. 만료된 트랜잭션 제출을 방지하고 네트워크 리소스를 절약합니다.

Compact compiler update​

Compact 컴파일러 v0.27.0으로 업데이트되어 다음을 제공합니다:

  • 개선된 타입 추론
  • 더 나은 오류 메시지
  • 향상된 회로 최적화

ESM and CommonJS dual support​

패키지 exports가 ESM/CommonJS 환경을 모두 지원하도록 수정되어, 최신 번들러 및 빌드 시스템과의 호환성이 개선되었습니다.

Binary circuit results support​

성능 향상을 위해 바이너리(Uint8Array) 회로 결과를 도입했습니다:

  • 회로 실행 중 메모리 할당 감소
  • 더 빠른 직렬화 및 역직렬화
  • 대규모 또는 복잡한 회로 작업 시 성능 향상

Breaking changes​

기존 코드에 영향을 주는 호환성을 깨는 변경입니다.

LevelPrivateStateProvider authentication required​

변경 내용: 암묵적 저장소 인증이 제거되었습니다.

영향: walletProvider 또는 privateStoragePasswordProvider 없이 인스턴스를 생성하는 모든 코드에 영향을 줍니다.

필요한 조치:

  • 모든 provider 인스턴스화를 업데이트하세요.
  • 세션 간 비밀번호 일관성을 확보하세요.

WalletProvider.balanceTx return type​

변경 내용: balanceTx이 이제 BalancedProvingRecipe 유니온을 반환합니다.

영향: 단일 트랜잭션 타입을 가정하는 코드에 영향을 줍니다.

필요한 조치:

  • 타입 판별 로직을 추가하세요.
  • 세 가지 레시피 변형을 모두 명시적으로 처리하세요.

MidnightProvider.submitTx is now async​

변경 내용: 반환 타입이 TransactionId에서 Promise<TransactionId>로 변경되었습니다.

영향: 동기식 제출 로직에 영향을 줍니다.

필요한 조치:

  • 모든 submitTx 호출에 await을 추가하세요.
  • 호출하는 함수를 async로 업데이트하세요.
// Before
const txId = midnightProvider.submitTx(tx);

// After
const txId = await midnightProvider.submitTx(tx);

Contract calls are now async​

변경 내용: 모든 contract.call.* 메서드가 이제 Promise<T>을 반환합니다.

영향: 동기식 컨트랙트 호출 사용에 영향을 줍니다.

필요한 조치:

  • 모든 컨트랙트 호출에 await을 추가하세요.
  • 의존하는 로직을 그에 맞게 업데이트하세요.

Zswap offer generation​

변경 내용: zswapStateToOffer()이 이제 undefined을 반환할 수 있습니다.

영향: 항상 offer가 생성된다고 가정하는 코드에 영향을 줍니다.

필요한 조치: 빈 Zswap 상태에 대한 검사를 추가하세요.

const offer = zswapStateToOffer(state, encKey);
if (!offer) {
  // Handle empty state
}

networkId type change​

변경 내용: networkId이 enum에서 일반 문자열로 변경되었습니다.

영향: enum 임포트 및 패턴 매칭에 영향을 줍니다.

필요한 조치:

  • NetworkId enum 사용을 제거하세요.
  • 문자열 리터럴로 대체하세요 (예: 'preview').
// Before
import { NetworkId } from '@midnight-ntwrk/types';
config.networkId = NetworkId.Testnet;

// After
config.networkId = 'preview';

Known issues​

릴리스 시점 기준 치명적인 알려진 이슈는 없습니다. 문제 발생 시 다음을 확인하세요:

  • Node.js 22 이상 설치 여부
  • 컨트랙트 호출에 await 추가 여부