For the complete documentation index, see llms.txt

Wallet SDK error reference

Midnight wallet SDK의 모든 오류는 별도로 명시되지 않는 한 Effect Data.TaggedError 인스턴스입니다.

오류를 처리하려면 각 오류에 표시된 _tag 필드와 함께 Effect.catchTag를 사용하세요. 유니온 타입의 경우 Effect.catchTags를 사용하세요.

이 레퍼런스에서는 각 오류 클래스를 처리하고 해결하는 방법을 자세히 안내합니다.

Node client (@midnight-ntwrk/wallet-sdk-node-client)

다음 7개의 오류가 NodeClientError 유니온 타입을 구성합니다.

SubmissionError

노드로 트랜잭션을 제출하는 데 실패했음을 나타내는 오류입니다.

Field	Value
_tag	'SubmissionError'
Fields	message: string, txData: unknown, cause?: unknown

해결 방법: message와 cause를 확인해 근본 원인을 파악하세요. 노드 연결 상태와 트랜잭션 형식이 올바른지 점검하세요.

Effect.catchTag('SubmissionError', (e) => ...)

ConnectionError

WebSocket을 통한 노드 연결에 실패했음을 나타내는 오류입니다.

Field	Value
_tag	'ConnectionError'

알려진 메시지:

• "Could not connect within specified time range (5s)": 노드에 도달할 수 없거나 응답이 느린 경우
• "Failed to retrieve genesis transactions": 연결은 됐지만 제네시스 데이터를 사용할 수 없는 경우

해결 방법: 노드 WebSocket URL이 올바른지, 노드가 실행 중인지 확인하세요. 노드가 느린 네트워크에 있는 경우 연결 타임아웃을 늘려보세요.

Effect.catchTag('ConnectionError', (e) => ...)

TransactionProgressError

제출된 트랜잭션이 예상 시간 내에 원하는 수명 주기 단계에 도달하지 못했음을 나타내는 오류입니다.

Field	Value
_tag	'TransactionProgressError'

알려진 메시지: "Transaction did not reach finality within expected time"

해결 방법: 네트워크 혼잡도와 노드 상태를 확인하세요. 트랜잭션이 아직 멤풀에 있을 수 있으므로, 재제출 전에 상태를 먼저 조회하세요.

Effect.catchTag('TransactionProgressError', (e) => ...)

ParseError

SDK가 노드에서 반환된 결과를 파싱하지 못했음을 나타내는 오류입니다.

Field	Value
_tag	'ParseError'

해결 방법: 대체로 SDK와 노드 간의 프로토콜 버전 불일치를 나타냅니다. SDK와 노드 버전이 호환되는지 확인하세요.

Effect.catchTag('ParseError', (e) => ...)

TransactionUsurpedError

동일한 discriminator를 가진 다른 트랜잭션이 기존 트랜잭션을 대체했음을 나타내는 오류입니다.

Field	Value
_tag	'TransactionUsurpedError'

해결 방법: 원래 트랜잭션은 더 이상 유효하지 않습니다. 예기치 않은 대체가 발생한 경우, 충돌하는 트랜잭션을 제출한 프로세스를 조사하세요.

Effect.catchTag('TransactionUsurpedError', (e) => ...)

TransactionDroppedError

노드가 트랜잭션을 삭제했음을 나타내는 오류입니다. 대부분 멤풀이 가득 찬 경우 발생합니다.

Field	Value
_tag	'TransactionDroppedError'

해결 방법: 멤풀이 비워질 때까지 기다렸다가 재제출하세요. 네트워크가 수수료 우선순위를 지원한다면 트랜잭션 수수료를 높이는 것도 고려해보세요.

Effect.catchTag('TransactionDroppedError', (e) => ...)

TransactionInvalidError

노드가 트랜잭션을 유효하지 않다고 판단해 거부했음을 나타내는 오류입니다.

Field	Value
_tag	'TransactionInvalidError'

해결 방법: 잘못 구성된 트랜잭션이나 검증 규칙 위반으로 발생한 오류입니다. 트랜잭션 구성 로직을 검토하세요. 수정 없이 재제출하지 마세요.

Effect.catchTag('TransactionInvalidError', (e) => ...)

Shielded wallet (@midnight-ntwrk/wallet-sdk-shielded)

Shielded 지갑은 8가지 오류 타입을 제공합니다.

OtherWalletError

더 구체적인 범주에 해당하지 않는 지갑 오류를 처리하는 포괄적인 오류입니다.

Field	Value
_tag	'Wallet.Other'

해결 방법: 오류 세부 정보를 확인하세요. 프로덕션에서 이 오류가 발생한다면 재현 케이스와 함께 이슈를 등록하는 것을 고려해보세요.

Effect.catchTag('Wallet.Other', (e) => ...)

SyncWalletError

Midnight 블록체인과의 지갑 동기화에 실패했음을 나타내는 오류입니다.

Field	Value
_tag	'Wallet.Sync'

해결 방법: 노드 연결 상태를 확인하고 동기화 작업을 재시도하세요. 지속적으로 실패한다면 로컬 상태가 손상되었을 수 있습니다.

Effect.catchTag('Wallet.Sync', (e) => ...)

SubmissionWalletError

지갑 레이어에서 발생한 제출 오류를 감싸는 래퍼입니다 (노드 클라이언트의 SubmissionError와는 별개입니다).

Field	Value
_tag	'Wallet.SubmissionWalletError'

해결 방법: 내부 원인을 풀어서 확인하세요. 대체로 노드 클라이언트 제출 경로로 위임됩니다.

Effect.catchTag('Wallet.SubmissionWalletError', (e) => ...)

InsufficientFundsError

지정된 토큰 타입에 대해 지갑에 작업을 완료할 만큼 충분한 토큰이 없음을 나타내는 오류입니다.

Field	Value
_tag	'Wallet.InsufficientFunds'
Fields	tokenType: string, amount: bigint

해결 방법: 트랜잭션 구성 전에 tokenType의 지갑 잔액을 확인하세요. 충전을 요청하거나 전송 금액을 줄이세요.

Effect.catchTag('Wallet.InsufficientFunds', (e) => {
  console.log(`Need more ${e.tokenType}, shortfall: ${e.amount}`)
})

AddressError

제공된 주소가 유효하지 않음을 나타내는 오류입니다.

Field	Value
_tag	'Wallet.Address'
Fields	originalAddress: string

해결 방법: 사용 전에 주소 형식을 검증하세요. 주소 형식에 대한 자세한 내용은 지갑 SDK 가이드의 Address encoding 섹션을 참조하세요. originalAddress 필드에 거부된 입력값이 담겨 있습니다.

Effect.catchTag('Wallet.Address', (e) => ...)

InvalidCoinHashesError

하나 이상의 코인에 필수 논스 해시가 없음을 나타내는 오류입니다.

Field	Value
_tag	'Wallet.InvalidCoinHashes'
Fields	missingNonces: unknown[]

해결 방법: 코인을 지출하기 전에 완전히 동기화되었는지 확인하세요. missingNonces 필드에 영향을 받는 코인이 식별됩니다.

Effect.catchTag('Wallet.InvalidCoinHashes', (e) => ...)

TransactingError

트랜잭션 구성 또는 수수료 밸런싱 중에 발생한 오류입니다.

Field	Value
_tag	'Wallet.Transacting'

해결 방법: 입력값이 유효하고 수수료 토큰 잔액이 충분한지 확인하세요. 트랜잭션 파라미터를 검토하세요.

Effect.catchTag('Wallet.Transacting', (e) => ...)

TransactionHistoryError

트랜잭션 기록 저장소를 읽거나 쓰는 중에 발생한 오류입니다.

Field	Value
_tag	'Wallet.TransactionHistory'

해결 방법: 로컬 스토리지의 가용성과 권한을 확인하세요. 손상된 저장소 기록이 원인일 수 있습니다. 초기화 후 재동기화로 복구할 수 있습니다.

Effect.catchTag('Wallet.TransactionHistory', (e) => ...)

Unshielded wallet (@midnight-ntwrk/wallet-sdk-unshielded-wallet)

Unshielded 지갑은 11가지 오류 타입을 제공합니다. Shielded 지갑의 8가지 오류(동일한 _tag 값)를 포함하며, 아래 5가지 추가 타입이 더 있습니다.

SignError

트랜잭션 서명에 실패한 경우 발생합니다.

Field	Value
_tag	'Wallet.Sign'

해결 방법: 서명 키가 사용 가능하고 잠겨있지 않은지 확인하세요. 해당되는 경우 하드웨어 지갑 연결 상태도 점검하세요.

Effect.catchTag('Wallet.Sign', (e) => ...)

ApplyTransactionError

로컬 UTXO 세트에 트랜잭션을 적용하는 데 실패한 경우 발생합니다.

Field	Value
_tag	'Wallet.ApplyTransaction'

해결 방법: 대체로 제출 오류 이후에 발생합니다. 로컬에 적용하기 전에 노드가 트랜잭션을 수락했는지 확인하세요.

Effect.catchTag('Wallet.ApplyTransaction', (e) => ...)

RollbackUtxoError

체인 재편성(chain reorganisation) 중 UTXO 롤백에 실패한 경우 발생합니다.

Field	Value
_tag	'Wallet.RollbackUtxo'

해결 방법: 롤백이 반복적으로 실패한다면 로컬 UTXO 상태가 불일치 상태일 수 있습니다. 이 경우 전체 재동기화가 필요할 수 있습니다.

Effect.catchTag('Wallet.RollbackUtxo', (e) => ...)

SpendUtxoError

UTXO를 소비됨으로 표시하는 데 실패한 경우 발생합니다.

Field	Value
_tag	'Wallet.SpendUtxo'

해결 방법: 해당 UTXO가 이미 소비되었거나 로컬 세트에 존재하지 않을 수 있습니다. 상태를 맞추려면 지갑을 재동기화하세요.

Effect.catchTag('Wallet.SpendUtxo', (e) => ...)

UtxoNotFoundError

참조된 UTXO를 로컬 세트에서 찾을 수 없는 경우 발생합니다.

Field	Value
_tag	'UtxoNotFoundError'

해결 방법: 지갑이 완전히 동기화되어 있는지 확인하세요. 해당 UTXO가 이미 소비되었거나 동기화가 체인 최신 상태보다 뒤처져 있을 수 있습니다.

Effect.catchTag('UtxoNotFoundError', (e) => ...)

DUST wallet (@midnight-ntwrk/wallet-sdk-dust-wallet)

DUST 지갑은 Shielded 지갑과 공유되는 4가지 오류 타입을 제공합니다.

Error	_tag
OtherWalletError	'Wallet.Other'
SyncWalletError	'Wallet.Sync'
TransactingError	'Wallet.Transacting'
InsufficientFundsError	'Wallet.InsufficientFunds'

필드 세부 정보 및 해결 방법은 Shielded wallet 섹션을 참조하세요.

Capabilities (@midnight-ntwrk/wallet-sdk-capabilities)

capabilities 패키지는 3가지 오류 타입을 제공합니다.

ProvingError

proof provider에서 발생한 오류를 감싸는 래퍼입니다.

Field	Value
_tag	'Wallet.Proving'

해결 방법: proof server 연결 상태와 올바른 circuit 키를 로드하고 있는지 확인하세요. 래핑된 원인을 검사해 provider의 근본 오류를 파악하세요.

Effect.catchTag('Wallet.Proving', (e) => ...)

SubmissionError (Capabilities)

capabilities/서비스 레이어에서 발생한 제출 오류입니다.

Field	Value
_tag	'SubmissionError'

해결 방법: 노드 클라이언트의 SubmissionError와 동일합니다. 노드 연결 상태와 트랜잭션 유효성을 확인하세요.

Effect.catchTag('SubmissionError', (e) => ...)

InsufficientFundsError (Capabilities — native Error)

이 오류는 일반 JavaScript Error로, Data.TaggedError가 아닙니다. 코인 선택 중에 Effect 실패가 아닌 throw 방식으로 발생합니다.

알려진 메시지: "Insufficient Funds: could not balance <tokenType>"

여기서 <tokenType>은 토큰 식별자입니다.

해결 방법: 표준 try/catch 또는 Effect.tryPromise로 처리하세요. 코인 선택을 호출하기 전에 지갑에 지정된 토큰 타입이 충분한지 확인하세요.

Utilities (@midnight-ntwrk/wallet-sdk-utilities)

utilities 패키지는 5가지 오류 타입을 제공합니다.

LedgerError

레저 WASM 모듈에서 발생한 예외를 감싸는 래퍼입니다.

Field	Value
_tag	'LedgerError'

해결 방법: 래핑된 원인을 확인하세요. 대체로 레저에 유효하지 않은 상태가 전달되었음을 나타냅니다. 레저 입력이 올바른 형식인지 점검하세요.

Effect.catchTag('LedgerError', (e) => ...)

LeftError<L>

Right를 기대하는 곳에서 Either.Left 값을 만났을 때 발생합니다.

Field	Value
_tag	'LeftError'

해결 방법: Either 값을 생성하는 로직을 확인하세요. 여기서 Left는 처리되지 않은 오류 분기를 나타냅니다.

Effect.catchTag('LeftError', (e) => ...)

InvalidProtocolSchemeError

제공된 네트워크 URL 중 하나 이상이 지원되지 않는 프로토콜 스킴을 사용할 때 발생하는 오류입니다.

Field	Value
_tag	'InvalidProtocolSchemeError'

해결 방법: URL에 올바른 스킴을 사용하고 있는지 확인하세요 (예: WebSocket 연결의 경우 ws:// 또는 wss://, HTTP의 경우 http:// 또는 https://).

Effect.catchTag('InvalidProtocolSchemeError', (e) => ...)

FailedToDeriveWebSocketUrlError

제공된 입력에서 WebSocket URL을 도출할 수 없을 때 발생하는 오류입니다.

Field	Value
_tag	'FailedToDeriveWebSocketUrlError'

해결 방법: 입력 URL이 올바른 형식인지, 도출 로직이 제공된 스킴/호스트 조합을 지원하는지 확인하세요.

Effect.catchTag('FailedToDeriveWebSocketUrlError', (e) => ...)

ClientError

HTTP 400–499 상태 코드에 해당하는 클라이언트 측 네트워크 오류입니다.

Field	Value
_tag	'ClientError'

해결 방법: 잘못된 입력, 인증 실패, 리소스 없음 등 요청 자체의 문제를 나타냅니다. 요청을 수정하지 않고 재시도하지 마세요. 오류에서 구체적인 상태 코드를 확인하세요.

Effect.catchTag('ClientError', (e) => ...)

ServerError

HTTP 500 이상 상태 코드에 해당하는 서버 측 오류입니다.

Field	Value
_tag	'ServerError'

해결 방법: 500 오류가 지속된다면 서버 로그를 확인하세요. SDK는 일시적인 502–504 오류(게이트웨이/서비스 불가 오류)에 대해 자동으로 재시도합니다.

Effect.catchTag('ServerError', (e) => ...)

Runtime (@midnight-ntwrk/wallet-sdk-runtime)

runtime 패키지는 1가지 오류 타입을 제공합니다.

WalletRuntimeError

지갑 런타임의 설정 오류입니다.

Field	Value
_tag	'WalletRuntimeError'

알려진 메시지:

• "No variant to init": 초기화 중에 지갑 변형이 제공되지 않은 경우
• "Empty variants list": 런타임에 제공된 변형 목록이 비어있는 경우

해결 방법: 런타임을 초기화하기 전에 최소 하나의 지갑 변형을 설정하세요.

Effect.catchTag('WalletRuntimeError', (e) => ...)

Address format (@midnight-ntwrk/wallet-sdk-address-format)

address format 패키지는 5가지 오류 타입을 제공합니다.

이 오류들은 Data.TaggedError 인스턴스가 아닌 일반 JavaScript Error throw입니다. 표준 try/catch로 처리하세요.

Message	Cause
"Expected prefix mn"	주소가 mn 접두사로 시작하지 않는 경우
"Segment contains disallowed characters"	주소 세그먼트에 허용되지 않는 문자가 포함된 경우
"Expected type <expected>, got <actual>"	주소 타입 바이트가 예상 타입과 일치하지 않는 경우
"Coin public key needs to be 32 bytes long"	공개 키 구성요소의 길이가 올바르지 않은 경우
"Unshielded address needs to be 32 bytes long"	Unshielded 주소 페이로드의 길이가 올바르지 않은 경우
"Dust address is too large"	DUST 주소가 허용된 최대 크기를 초과한 경우

해결 방법: address-format API에 전달하기 전에 주소 문자열을 검증하세요. 상위 수준의 주소 검증에는 Shielded 지갑의 AddressError('Wallet.Address')를 사용하세요.

Complete tag registry

알파벳순으로 정렬된 29개의 _tag 값 전체 목록

_tag	Package	Error type
'ClientError'	@midnight-ntwrk/wallet-sdk-utilities	ClientError
'ConnectionError'	@midnight-ntwrk/wallet-sdk-node-client	ConnectionError
'FailedToDeriveWebSocketUrlError'	@midnight-ntwrk/wallet-sdk-utilities	FailedToDeriveWebSocketUrlError
'InvalidProtocolSchemeError'	@midnight-ntwrk/wallet-sdk-utilities	InvalidProtocolSchemeError
'LeftError'	@midnight-ntwrk/wallet-sdk-utilities	LeftError<L>
'LedgerError'	@midnight-ntwrk/wallet-sdk-utilities	LedgerError
'ParseError'	@midnight-ntwrk/wallet-sdk-node-client	ParseError
'ServerError'	@midnight-ntwrk/wallet-sdk-utilities	ServerError
'SubmissionError'	@midnight-ntwrk/wallet-sdk-node-client, @midnight-ntwrk/wallet-sdk-capabilities	SubmissionError
'TransactionDroppedError'	@midnight-ntwrk/wallet-sdk-node-client	TransactionDroppedError
'TransactionInvalidError'	@midnight-ntwrk/wallet-sdk-node-client	TransactionInvalidError
'TransactionProgressError'	@midnight-ntwrk/wallet-sdk-node-client	TransactionProgressError
'TransactionUsurpedError'	@midnight-ntwrk/wallet-sdk-node-client	TransactionUsurpedError
'UtxoNotFoundError'	@midnight-ntwrk/wallet-sdk-unshielded-wallet	UtxoNotFoundError
'Wallet.Address'	@midnight-ntwrk/wallet-sdk-shielded, @midnight-ntwrk/wallet-sdk-unshielded-wallet	AddressError
'Wallet.ApplyTransaction'	@midnight-ntwrk/wallet-sdk-unshielded-wallet	ApplyTransactionError
'Wallet.InsufficientFunds'	@midnight-ntwrk/wallet-sdk-shielded, @midnight-ntwrk/wallet-sdk-unshielded-wallet, @midnight-ntwrk/wallet-sdk-dust-wallet	InsufficientFundsError
'Wallet.InvalidCoinHashes'	@midnight-ntwrk/wallet-sdk-shielded, @midnight-ntwrk/wallet-sdk-unshielded-wallet	InvalidCoinHashesError
'Wallet.Other'	@midnight-ntwrk/wallet-sdk-shielded, @midnight-ntwrk/wallet-sdk-unshielded-wallet, @midnight-ntwrk/wallet-sdk-dust-wallet	OtherWalletError
'Wallet.Proving'	@midnight-ntwrk/wallet-sdk-capabilities	ProvingError
'Wallet.RollbackUtxo'	@midnight-ntwrk/wallet-sdk-unshielded-wallet	RollbackUtxoError
'Wallet.Sign'	@midnight-ntwrk/wallet-sdk-unshielded-wallet	SignError
'Wallet.SpendUtxo'	@midnight-ntwrk/wallet-sdk-unshielded-wallet	SpendUtxoError
'Wallet.SubmissionWalletError'	@midnight-ntwrk/wallet-sdk-shielded, @midnight-ntwrk/wallet-sdk-unshielded-wallet	SubmissionError (지갑)
'Wallet.Sync'	@midnight-ntwrk/wallet-sdk-shielded, @midnight-ntwrk/wallet-sdk-unshielded-wallet, @midnight-ntwrk/wallet-sdk-dust-wallet	SyncWalletError
'Wallet.Transacting'	@midnight-ntwrk/wallet-sdk-shielded, @midnight-ntwrk/wallet-sdk-unshielded-wallet, @midnight-ntwrk/wallet-sdk-dust-wallet	TransactingError
'Wallet.TransactionHistory'	@midnight-ntwrk/wallet-sdk-shielded, @midnight-ntwrk/wallet-sdk-unshielded-wallet	TransactionHistoryError
'WalletRuntimeError'	@midnight-ntwrk/wallet-sdk-runtime	WalletRuntimeError