Version: v1

DApp Connector API v4.0.0 release notes

Version: v4.0.0
Date: 28 January 2026
Environment: Preview, PreProd

High-level summary

DApp Connector API의 전면 재설계 릴리스입니다. 타입 기반 아키텍처, 네트워크 인식 연결, 세분화된 잔액/주소 메서드, 증명 위임, CAIP-372 호환 지갑 검색 기능이 추가되었습니다. 호환성을 깨는 변경이 포함되어 v3.0.0 사용자 전원에게 영향을 줍니다.

Audience

다음 개발자가 확인해야 합니다:

DApp에서 @midnight-ntwrk/dapp-connector-api를 사용하는 경우
Midnight 애플리케이션에 지갑 기능을 통합하는 경우
DApp Connector API 호환 지갑 구현을 유지 관리하는 경우

What changed (Summary of updates)

인터페이스 기반에서 타입 기반 아키텍처로 API 전면 재설계
enable()/isEnabled() 연결 모델을 네트워크 인식 connect(networkId)로 교체
@midnight-ntwrk/wallet-api 및 @midnight-ntwrk/zswap 의존성 제거
getProvingProvider() 메서드를 통한 증명 위임 추가
makeIntent() 메서드를 통한 아토믹 스왑 지원 추가
단일 state() 메서드를 대체하는 세분화된 잔액 및 주소 메서드 추가
새로운 오류 코드 추가: PermissionRejected 및 Disconnected
크로스 바운더리 호환성을 위해 APIError을 클래스에서 타입으로 변경
종합적인 사양 문서 추가

New features

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

Proving delegation (`getProvingProvider`)

DApp이 ZK 증명 생성을 지갑에 위임할 수 있습니다. 지갑이 사용자 선호에 따라 로컬, 원격, 하드웨어 가속 등 다양한 증명 방식을 제공할 수 있어 유연성이 높아집니다. DApp이 KeyMaterialProvider를 제공하면 Midnight Ledger 호환 ProvingProvider를 받습니다.

Intent creation (`makeIntent`)

아토믹 스왑을 위해 의도적으로 불균형한 인텐트가 포함된 트랜잭션을 생성합니다. 인텐트 ID와 수수료 결제 옵션을 설정하여 원하는 입출력을 지정할 수 있습니다. DEX 통합 및 P2P 토큰 스왑에 필수적입니다.

Transfer creation (`makeTransfer`)

지정 출력으로 전송 트랜잭션을 생성하는 간편 메서드입니다. 코인 선택과 트랜잭션 구성의 복잡성을 내부적으로 처리합니다.

Data signing (`signData`)

지갑 키로 임의 데이터에 서명합니다. 인코딩(hex, base64, text)과 키 유형을 선택할 수 있으며, 실수로 트랜잭션에 서명하는 것을 방지하기 위해 자동으로 접두사가 추가됩니다.

Transaction history (`getTxHistory`)

지갑 관련 트랜잭션 내역을 페이지네이션으로 조회합니다. 트랜잭션 해시와 상세 상태(pending, confirmed, finalized, discarded)가 포함됩니다.

Connection status (`getConnectionStatus`)

지갑 연결이 유효한지, 어떤 네트워크에 연결되어 있는지 확인합니다.

Hint usage (`hintUsage`)

DApp이 사용할 API 메서드를 미리 힌트로 제공합니다. 지갑이 사전에 필요한 권한을 사용자에게 요청하여 UX가 향상됩니다.

CAIP-372 compatible discovery

새로운 InitialAPI 타입은 CAIP-372 초안 사양과 호환되는 표준화된 지갑 검색을 위해 rdns(역방향 DNS 식별자), name, icon, apiVersion을 포함합니다.

New features requiring configuration updates

설정 변경이 필요한 새 기능입니다.

Network-aware connection

모든 DApp에서 대상 네트워크를 지정하도록 연결 로직을 업데이트해야 합니다. 올바른 네트워크 연결과 멀티 네트워크 지갑 지원을 보장합니다.

필수 업데이트:

wallet.enable()을 wallet.connect(networkId)로 교체하세요.
Preview에는 'preview', Mainnet에는 'mainnet', 테스트 네트워크에는 다른 문자열을 사용하세요.

Improvements

이번 릴리스의 개선 사항입니다.

Granular balance methods

단일 state() 메서드를 getShieldedBalances, getUnshieldedBalances, getDustBalance로 분리했습니다. 의미가 명확해지고 권한을 더 세밀하게 제어할 수 있습니다.

Granular address methods

주소 유형별 조회 메서드(getShieldedAddresses, getUnshieldedAddress, getDustAddress)를 Bech32m 인코딩으로 제공합니다.

Type-based architecture

인터페이스/클래스 기반에서 TypeScript 타입으로 전환했습니다. 크로스 바운더리 instanceof 문제가 해결되고, ts-custom-error 의존성 제거로 번들 크기가 줄었습니다.

Enhanced transaction balancing

트랜잭션 밸런싱을 balanceUnsealedTransaction과 balanceSealedTransaction으로 분리하여 사용 사례에 맞는 메서드를 선택할 수 있습니다.

Deprecations

이번 릴리스에서 deprecated 처리된 기능입니다.

Prover server URI

Starts: v4.0.0
Full removal: v5.0.0 (예정)
Replacement: getProvingProvider() 메서드

마이그레이션 단계:

설정에서 proverServerUri 사용을 중단하세요.
getProvingProvider(keyMaterialProvider)을 사용하여 proving provider을 얻으세요.
키 자료 확인을 위해 Midnight.js의 ZKConfigProvider와 통합하세요.

Breaking changes

호환성을 깨는 변경과 필요한 조치 사항입니다.

Complete API redesign

전체 API 구조가 인터페이스 기반에서 타입 기반 아키텍처로 재설계되었습니다.

영향: v3.0.0 API을 사용하는 모든 기존 DApp 통합에 영향을 미칩니다.

필요한 조치:

모든 import를 새 타입 이름으로 업데이트하세요.
DAppConnectorAPI을 InitialAPI로 교체하세요.
DAppConnectorWalletAPI을 WalletConnectedAPI로 교체하세요.
DAppConnectorWalletState 사용을 개별 메서드 호출로 교체하세요.

코드 예시:

// v3.0.0
const wallet: DAppConnectorAPI = window.midnight?.someWallet;
const enabled = await wallet.isEnabled();
const walletApi = await wallet.enable();
const state = await walletApi.state();
console.log(state.address);

// v4.0.0
const wallet: InitialAPI = window.midnight?.someWallet;
const connectedApi = await wallet.connect('preview');
const addresses = await connectedApi.getShieldedAddresses();
console.log(addresses.shieldedAddress);

Connection model

enable() 및 isEnabled() 메서드가 제거되고 connect(networkId)로 교체되었습니다.

영향: 기존 DApp의 모든 연결 로직에 영향을 미칩니다.

필요한 조치:

wallet.enable()을 wallet.connect(networkId)로 교체하세요.
isEnabled() 확인을 제거하고 대신 getConnectionStatus()을 사용하세요.
네트워크 ID 매개변수를 제공하세요 (Preview에는 'preview', Mainnet에는 'mainnet' 사용).

State access removal

결합된 지갑 상태를 반환하는 state() 메서드가 제거되었습니다.

영향: state().address, state().coinPublicKey 등에 접근하는 모든 코드에 영향을 미칩니다.

필요한 조치:

state()을 적절한 세분화된 메서드로 교체하세요.
shielded 주소와 키에는 getShieldedAddresses()을 사용하세요.
unshielded 주소에는 getUnshieldedAddress()을 사용하세요.
잔액에는 getShieldedBalances() / getUnshieldedBalances()을 사용하세요.

코드 예시:

// v3.0.0
const state = await walletApi.state();
const address = state.address;
const coinPubKey = state.coinPublicKey;

// v4.0.0
const { shieldedAddress, shieldedCoinPublicKey } = await connectedApi.getShieldedAddresses();

Transaction balancing

balanceAndProveTransaction(tx, newCoins)이 balanceUnsealedTransaction(tx) 및 balanceSealedTransaction(tx)으로 교체되었습니다.

영향: 모든 트랜잭션 밸런싱 로직에 영향을 미칩니다.

필요한 조치:

사용 사례에 unsealed(컨트랙트 상호작용) 또는 sealed(스왑 완료) 밸런싱이 필요한지 결정하세요.
메서드 호출을 업데이트하고 문자열 기반 트랜잭션 형식을 처리하세요.
newCoins 매개변수를 제거하세요 (더 이상 필요하지 않습니다).

코드 예시:

// v3.0.0
const provedTx = await walletApi.balanceAndProveTransaction(tx, newCoins);

// v4.0.0
const { tx: balancedTx } = await connectedApi.balanceUnsealedTransaction(serializedTx);

APIError type

APIError이 CustomError을 확장하는 클래스에서 타입 별칭으로 변경되었습니다.

영향: instanceof APIError 검사에 영향을 미칩니다.

필요한 조치:

error instanceof APIError을 error.type === 'DAppConnectorAPIError'로 교체하세요.
오류 처리 로직을 업데이트하세요.

코드 예시:

// v3.0.0
try {
  await walletApi.submitTransaction(tx);
} catch (error) {
  if (error instanceof APIError) {
    console.log(error.code);
  }
}

// v4.0.0
try {
  await connectedApi.submitTransaction(tx);
} catch (error) {
  if (error.type === 'DAppConnectorAPIError') {
    console.log(error.code);
  }
}

Configuration interface

ServiceUriConfig이 Configuration으로 이름이 변경되었고, networkId가 추가되었으며, proverServerUri가 선택적이 되고 deprecated 처리되었습니다.

영향: ServiceUriConfig을 import하거나 사용하는 코드에 영향을 미칩니다.

필요한 조치:

import를 Configuration 타입을 사용하도록 업데이트하세요.
선택적 proverServerUri을 처리하세요.
networkId가 예상 네트워크와 일치하는지 검증하세요.

Removed dependencies

@midnight-ntwrk/wallet-api 및 @midnight-ntwrk/zswap이 의존성에서 제거되었습니다.

영향: 이러한 전이적 의존성에 의존하던 타입 import에 영향을 미칩니다.

필요한 조치: 트랜잭션 타입을 문자열 직렬화 형식을 사용하도록 업데이트하세요.

Links and references

Specification: DApp Connector API specification
API documentation: DApp Connector API documentation
NPM package: @midnight-ntwrk/dapp-connector-api

High-level summary​

Audience​

What changed (Summary of updates)​

New features​

Proving delegation (getProvingProvider)​

Intent creation (makeIntent)​

Transfer creation (makeTransfer)​

Data signing (signData)​

Transaction history (getTxHistory)​

Connection status (getConnectionStatus)​

Hint usage (hintUsage)​

CAIP-372 compatible discovery​

New features requiring configuration updates​

Network-aware connection​

Improvements​

Granular balance methods​

Granular address methods​

Type-based architecture​

Enhanced transaction balancing​

Deprecations​

Prover server URI​

Breaking changes​

Complete API redesign​

Connection model​

State access removal​

Transaction balancing​

APIError type​

Configuration interface​

Removed dependencies​

Links and references​

High-level summary

Audience

What changed (Summary of updates)

New features

Proving delegation (`getProvingProvider`)

Intent creation (`makeIntent`)

Transfer creation (`makeTransfer`)

Data signing (`signData`)

Transaction history (`getTxHistory`)

Connection status (`getConnectionStatus`)

Hint usage (`hintUsage`)

CAIP-372 compatible discovery

New features requiring configuration updates

Network-aware connection

Improvements

Granular balance methods

Granular address methods

Type-based architecture

Enhanced transaction balancing

Deprecations

Prover server URI

Breaking changes

Complete API redesign

Connection model

State access removal

Transaction balancing

APIError type

Configuration interface

Removed dependencies

Links and references