Skip to main content
Version: v1

Wallet SDK v3.0.0 release notes

For the complete documentation index, see llms.txt
  • Version: v3.0.0
  • Date: 2026년 3월 20일
  • Environment: Mainnet, Preprod, Preview

High-level summary​

이번 릴리스는 정확한 수수료 추정과 개발자 편의성 향상에 초점을 맞추었습니다. 수수료 계산은 이제 컨텍스트에 독립적인 calculateFee와, 가용 코인 및 밸런싱 트랜잭션 비용을 반영하는 지갑 인식형 estimateFee로 분리되었습니다. SDK는 ledger v8로 업데이트되었습니다. 또한 지갑 초기화 전에 네트워크 이용약관을 조회할 수 있는 fetchTermsAndConditions, Effect를 사용하지 않는 개발자를 위한 Promise 기반 QueryRunner가 도입되었습니다.

Audience​

이번 릴리스는 다음 개발자에게 해당됩니다.

  • Midnight 네트워크용 지갑을 구축하는 개발자
  • DApp에 Midnight 토큰 전송을 통합하는 개발자
  • shielded(프라이빗) 및 unshielded 토큰 잔액을 관리해야 하는 개발자
  • 당사자 간 원자적 스왑을 구현하는 개발자

What changed (Summary of updates)​

이번 릴리스는 수수료 동작을 다듬고 개발자 워크플로를 개선하면서, SDK를 ledger v8에 맞게 정렬합니다. 아래 업데이트는 지갑 구현 전반에 걸친 API 추가와 보안 중심 처리 변경을 요약합니다.

  • 수수료 계산이 두 API로 분리: 트랜잭션을 단독으로 평가하는 calculateFee와, 밸런싱 비용을 포함해 현재 지갑이 실제로 지불할 수수료를 계산하는 estimateFee.
  • SDK 전반을 ledger v8로 업데이트.
  • 네트워크 이용약관 조회용 정적 메서드 WalletFacade.fetchTermsAndConditions() 추가.
  • GraphQL 쿼리를 plain Promise로 실행할 수 있는 QueryRunner.runPromise() 유틸리티 신규 추가.
  • shielded와 DUST 지갑의 SecretKeysResource가 사용 후 메모리에서 키를 지움.
  • shielded 지갑이 트랜잭션 실패 시 대기 코인을 해제함.
  • 유효하지 않은 트랜잭션 제출과 밸런싱 실패에 대한 오류 메시지 개선.

New features​

이번 릴리스에 도입된 새로운 기능의 상세 내역입니다.

이용약관 조회​

이번 릴리스는 정적 메서드 WalletFacade.fetchTermsAndConditions(configuration)를 추가합니다. 이 메서드는 네트워크 indexer로부터 현재 이용약관(URL과 SHA-256 해시)을 조회합니다. 지갑 초기화 이전 또는 초기화와 독립적으로 호출할 수 있습니다. indexerClientConnection.indexerHttpUrl을 포함하는 모든 설정을 받으므로, 공유 지갑 설정을 그대로 전달할 수 있습니다.

Promise 기반 쿼리 러너​

이번 릴리스는 @midnight-ntwrk/wallet-sdk-indexer-client에 QueryRunner.runPromise()를 도입합니다. Effect 보일러플레이트 없이 plain Promise로 GraphQL 쿼리를 실행합니다. 쿼리, 변수, 서버 설정을 받아 Promise<R>를 반환합니다.

New features requiring configuration updates​

이번 릴리스에서 신규 기능을 사용하기 위한 별도의 설정 업데이트는 필요하지 않습니다.

Improvements​

이번 릴리스에는 지갑 컴포넌트 전반의 품질과 안정성 개선도 포함됩니다.

  • 노드 클라이언트(@midnight-ntwrk/wallet-sdk-node-client)가 유효하지 않은 트랜잭션으로 제출이 실패할 때 더 명확한 오류 메시지를 반환합니다.
  • DUST 지갑이 밸런싱 실패 시 더 상세한 오류 메시지를 제공합니다.
  • shielded와 DUST 지갑의 SecretKeysResource가 참조만 null로 만드는 대신, 사용 후 암호학적 키를 메모리에서 안전하게 지웁니다.

Deprecations​

이번 릴리스에는 deprecation이 없습니다.

Breaking changes​

이번 릴리스에는 마이그레이션이 필요한 API와 동작 변경이 다수 포함됩니다.

Ledger v8​

SDK 전체 패키지가 Ledger v8 호환성으로 업데이트되었습니다. 개발자는 Ledger 의존성을 v8로 업그레이드해야 합니다.

동적 수수료 계산 (@midnight-ntwrk/wallet-sdk-facade, @midnight-ntwrk/wallet-sdk-dust-wallet)​

이전 calculateFee 메서드는 전체 지갑 수수료를 추정하려 했지만, 지갑의 코인 가용성이나 밸런싱 트랜잭션 비용을 반영할 수 없었습니다. v3.0.0에서는 수수료 계산이 두 메서드로 분리됩니다.

  • calculateFee: 트랜잭션을 단독으로 계산한 수수료. 지갑 코인 세트나 밸런싱 트랜잭션 비용은 반영하지 않습니다.
  • estimateFee: 현재 지갑이 실제로 지불할 현실적인 총 수수료를 계산합니다. 코인 가용성과 밸런싱 트랜잭션 비용을 반영합니다. 이 메서드는 secret key와 지갑 상태를 필요로 하며, 지갑이 수수료를 감당할 수 없을 때 InsufficientFundsError를 던집니다.

Wallet facade 마이그레이션:

// Before (v2.0.0) — 단일 메서드
const fee = await wallet.calculateTransactionFee(tx);

// After (v3.0.0) — 두 메서드

// 트랜잭션 자체에 대한 수수료 (밸런싱 비용 제외, 지갑 컨텍스트 없음):
const txFee = await wallet.calculateTransactionFee(tx);

// 지갑이 실제로 지불할 총 수수료 (밸런싱 tx 포함, 지갑 인식):
const totalFee = await wallet.estimateTransactionFee(tx, secretKey, {
  ttl: new Date(/* ... */), // 선택
  currentTime: new Date(), // 선택
});

DUST 지갑 API 마이그레이션:

// Before — 단일 calculateFee
const fee = await dustWallet.calculateFee(transactions);

// After
// 트랜잭션 수수료만 (컨텍스트 독립):
const txOnlyFee = await dustWallet.calculateFee(transactions);

// 지갑이 실제로 지불할 총 수수료 (지갑 인식, InsufficientFundsError 가능):
const totalFee = await dustWallet.estimateFee(secretKey, transactions, ttl, currentTime);

CoinSelection 타입 변경 (@midnight-ntwrk/wallet-sdk-dust-wallet)​

CoinSelection이 타깃 기반 다중 코인 선택 함수에서, 더 단순한 단일 코인 선택 함수로 변경되었습니다.

// Before — 타깃 합계에 맞는 여러 코인 반환
type CoinSelection<T> = (coins: readonly CoinWithValue<T>[], target: bigint) => CoinWithValue<T>[];

// After — 단일 코인(가용 중 가장 작은 것) 또는 undefined 반환
type CoinSelection<T> = (coins: readonly CoinWithValue<T>[]) => CoinWithValue<T> | undefined;

InsufficientFundsError (@midnight-ntwrk/wallet-sdk-dust-wallet)​

이번 릴리스는 지갑이 수수료 요구를 감당할 수 없을 때 estimateFee가 던지는 새로운 오류 타입을 추가합니다. message와 tokenType 필드를 포함합니다.

import { InsufficientFundsError } from '@midnight-ntwrk/wallet-sdk-dust-wallet';

Known issues​

이 섹션은 이번 Wallet SDK 릴리스의 알려진 이슈를 나열합니다.

shielded 및 DUST 지갑에 대한 트랜잭션 이력 미구현​

shielded 지갑과 DUST 지갑은 트랜잭션 이력을 추적하지 않습니다. shielded 지갑의 트랜잭션 이력 getter는 "not yet implemented"를 던집니다. unshielded 지갑만 트랜잭션 기록을 유지합니다.

Packages​

패키지버전설명
@midnight-ntwrk/wallet-sdk-facade3.0.0shielded, unshielded, DUST 지갑을 조율하는 통합 API. 수수료 계산이 calculateFee와 estimateFee로 분리. 이용약관 조회 기능 추가.
@midnight-ntwrk/wallet-sdk-unshielded-wallet2.1.0NIGHT 및 기타 unshielded 토큰 관리. ledger v8로 업데이트.
@midnight-ntwrk/wallet-sdk-shielded2.1.0프라이버시 보존 shielded 토큰 관리. ledger v8로 업데이트. secret 키를 메모리에서 안전하게 제거.
@midnight-ntwrk/wallet-sdk-dust-wallet3.0.0트랜잭션 수수료용 DUST 관리. 동적 수수료 계산, InsufficientFundsError, 밸런싱 오류 메시지 개선.
@midnight-ntwrk/wallet-sdk-capabilities3.2.0공유 지갑 기능(ProvingService, SubmissionService, PendingTransactionsService 포함). ledger v8로 업데이트.
@midnight-ntwrk/wallet-sdk-abstractions2.0.0코어 인터페이스와 도메인 타입. 공유 SyncProgress와 SerializedTransaction 포함.
@midnight-ntwrk/wallet-sdk-prover-client1.2.0prover 서비스와의 인터페이스. ledger v8로 업데이트.
@midnight-ntwrk/wallet-sdk-indexer-client1.2.0GraphQL로 Midnight indexer 조회. 이용약관 쿼리, QueryRunner.runPromise(), ledger v8 업데이트 추가.
@midnight-ntwrk/wallet-sdk-address-format3.1.0Bech32m 형식으로 Midnight 주소 인코딩/디코딩. ledger v8로 업데이트.
@midnight-ntwrk/wallet-sdk-hd3.0.1BIP-32/BIP-44/CIP-1852에 따라 시드에서 암호화 키 파생.
@midnight-ntwrk/wallet-sdk-node-client1.1.0Midnight 노드와 통신. 유효하지 않은 트랜잭션 오류 메시지 개선, ledger v8 지원.
@midnight-ntwrk/wallet-sdk-utilities1.1.0공통 유틸리티. 개발 전용 의존성 정리, ledger v8 지원 추가.
@midnight-ntwrk/wallet-sdk-runtime1.0.2지갑 라이프사이클과 상태 관리 조율.

Fixed defect list​

이번 릴리스에 포함된 결함 수정은 다음과 같습니다.

  • shielded 지갑이 트랜잭션 실패 시 대기 코인을 올바르게 해제합니다. 이전에는 실패 시 대기 코인이 해제되지 않아 재시작 전까지 가용 잔액이 줄어들 수 있었습니다.
  • shielded와 DUST 지갑의 SecretKeysResource가 참조만 null로 만드는 대신, 사용 후 암호학적 키를 메모리에서 안전하게 지웁니다.
  • 노드 클라이언트가 유효하지 않은 트랜잭션으로 제출이 실패할 때 더 명확한 오류 메시지를 반환합니다.
  • DUST 지갑이 밸런싱 실패 시 더 상세한 오류 메시지를 보고합니다.
  • @midnight-ntwrk/wallet-sdk-utilities에서 개발 전용 의존성을 프로덕션 의존성에서 제외했습니다.