For the complete documentation index, see llms.txt
Midnight node error codes
Midnight 노드 오류는 LedgerApiError 코드를 u8 (0–255)로 매핑한 값입니다. 노드가 레저 수준에서 트랜잭션을 거부할 때 Substrate의 InvalidTransaction::Custom(u8)을 통해 표면화됩니다.
노드가 제출된 트랜잭션을 Substrate 디스패치 오류의 Custom(N) 형태로 거부할 때 자주 발생합니다.
info
팔렛 수준의 DispatchError::Module은 인덱스 5 (pallet_midnight) 또는 6 (pallet_midnight_system)으로 표면화되며, 내부 오류를 디코딩해야 합니다. 내부 오류 디코딩 방법은 Decode 1010 transaction rejection errors 문제 해결 가이드를 참조하세요.
Errors from the wallet or SDK
오류가 지갑이나 SDK 호출에서 발생했다면, 예컨대 SubmissionError: Transaction submission error라면 Transaction submission errors부터 보세요. 이 섹션은 SDK 오류 안에서 노드 코드를 찾는 방법을 보여줍니다.
Error tables by code range
아래는 유형 및 상태 코드별로 분류된 Midnight 노드 전용 오류 목록입니다. 오류 테이블은 코드 범위별로 오류를 그룹화하여 오류 유형을 식별하는 데 도움을 줍니다.
이 표는 노드 버전 1.0.x가 반환하는 코드를 나열합니다. 코드 번호는 노드 릴리스마다 바뀔 수 있습니다. 네트워크가 실행하는 노드 버전은 compatibility matrix에서 확인하세요.
Deserialization errors (0–11)
노드가 와이어 포맷에서 데이터 역직렬화에 실패할 때 발생하는 오류입니다.
| Code | Name | Description | How to fix |
|---|---|---|---|
| 0 | NetworkId | 네트워크 ID 역직렬화에 실패한 경우 | SDK 버전 호환성 확인, 네트워크 ID 인코딩 검증 |
| 1 | Transaction | 트랜잭션 페이로드 역직렬화에 실패한 경우 | 호환되는 SDK 버전으로 트랜잭션을 빌드했는지 확인 |
| 2 | LedgerState | 레저 상태 역직렬화에 실패한 경우 | 노드 내부 오류 |
| 3 | ContractAddress | 컨트랙트 주소 역직렬화에 실패한 경우 | 컨트랙트 주소 형식 확인 |
| 4 | PublicKey | 공개 키 역직렬화에 실패한 경우 | 키 형식 및 인코딩 확인 |
| 5 | VersionedArenaKey | 버전 관리 아레나 키 역직렬화에 실패한 경우 | 내부 오류 |
| 6 | UserAddress | 사용자 주소 역직렬화에 실패한 경우 | 주소 형식 확인 |
| 7 | TypedArenaKey | 타입 지정 아레나 키 역직렬화에 실패한 경우 | 내부 오류 |
| 8 | SystemTransaction | 시스템 트랜잭션 역직렬화에 실패한 경우 | 거버넌스/브릿지 트랜잭션 형식 오류 |
| 9 | DustPublicKey | DUST 공개 키 역직렬화에 실패한 경우 | DUST 키 형식 확인 |
| 10 | CNightGeneratesDustActionType | cNIGHT-generates-DUST 액션 타입 역직렬화에 실패한 경우 | 내부 브릿지/관측 오류 |
| 11 | CNightGeneratesDustEvent | cNIGHT-generates-DUST 이벤트 역직렬화에 실패한 경우 | 내부 브릿지/관측 오류 |
역직렬화 오류의 대부분은 버전 불일치로 인해 발생합니다. 호환성 매트릭스를 참조하여 Midnight 블록체인 구성 요소의 호환 버전을 사용하고 있는지 항상 확인하세요.
Serialization errors (50–63)
노드가 저장 또는 전송을 위한 데이터 직렬화에 실패할 때 발생하는 오류입니다.
| Code | Name | Description | How to fix |
|---|---|---|---|
| 50 | TransactionIdentifier | 트랜잭션 식별자 직렬화에 실패한 경우 | 내부 오류 |
| 51 | LedgerState | 레저 상태 직렬화에 실패한 경우 | 노드 내부 오류 |
| 52 | LedgerParameters | 레저 파라미터 직렬화에 실패한 경우 | 노드 내부 오류 |
| 53 | ContractAddress | 컨트랙트 주소 직렬화에 실패한 경우 | 내부 오류 |
| 54 | ContractState | 컨트랙트 상태 직렬화에 실패한 경우 | 컨트랙트 상태가 손상되었을 수 있음 |
| 55 | ContractStateToJson | 컨트랙트 상태의 JSON 직렬화에 실패한 경우 | 컨트랙트 상태 형식이 JSON 직렬화와 호환되지 않음 |
| 56 | ZswapState | Zswap 상태 직렬화에 실패한 경우 | Zswap 내부 오류 |
| 57 | UnknownType | 알 수 없는 타입 직렬화에 실패한 경우 | 내부 오류 |
| 58 | MerkleTreeDigest | 머클 트리 다이제스트 직렬화에 실패한 경우 | 내부 머클 트리 오류 |
| 59 | VersionedArenaKey | 버전 관리 아레나 키 직렬화에 실패한 경우 | 내부 오류 |
| 60 | TypedArenaKey | 타입 지정 아레나 키 직렬화에 실패한 경우 | 내부 오류 |
| 61 | CNightGeneratesDustEvent | cNIGHT-generates-DUST 이벤트 직렬화에 실패한 경우 | 내부 브릿지 오류 |
| 62 | SystemTransaction | 시스템 트랜잭션 직렬화에 실패한 경우 | 내부 거버넌스 오류 |
| 63 | ArenaHash | 아레나 해시 직렬화에 실패한 경우 | 내부 오류 |
Transaction invalid (100–109, 193–200)
노드가 트랜잭션을 레저 상태에 적용한 후 레저 불변 조건 위반으로 거부할 때 발생하는 오류입니다.
| Code | Name | Description | How to fix |
|---|---|---|---|
| 100 | EffectsMismatch | 선언된 트랜잭션 이펙트가 계산된 이펙트와 일치하지 않는 경우 | 트랜잭션을 다시 빌드하세요. 이펙트 선언이 오래되었거나 SDK가 잘못 계산했을 수 있습니다 |
| 101 | ContractAlreadyDeployed | 대상 주소에 이미 컨트랙트가 존재하는 경우 | 다른 컨트랙트 주소를 사용하거나 기존 배포를 확인하세요 |
| 102 | ContractNotPresent | 지정한 주소에 존재하지 않는 컨트랙트를 호출한 경우 | 컨트랙트 주소를 확인하고 먼저 컨트랙트를 배포하세요 |
| 103 | Zswap | Zswap 수준의 트랜잭션 오류 (예: 이중 지출, 알 수 없는 머클 루트) | nullifier 재사용 여부를 확인하고 코인 트리 루트가 최신 상태인지 검증하세요 |
| 104 | Transcript | 노드가 온체인 트랜스크립트 실행을 거부한 경우 | 컨트랙트 로직을 확인하세요. circuit의 온체인 트랜스크립트 실행에 실패했습니다 |
| 105 | InsufficientClaimable | 클레임할 NIGHT 토큰이 부족한 경우 | 해당 작업에 충분한 NIGHT 잔액이 있는지 확인하세요 |
| 106 | VerifierKeyNotFound | circuit 작업에 필요한 검증자 키가 없는 경우 | circuit을 호출하기 전에 검증자 키를 배포하세요 |
| 107 | VerifierKeyAlreadyPresent | 해당 작업에 검증자 키가 이미 존재하는 경우 | 키가 이미 배포되어 있으므로 추가 조치가 필요하지 않습니다 |
| 108 | ReplayCounterMismatch | 서명된 카운터가 일치하지 않는 경우 (리플레이 공격 방지) | 현재 리플레이 카운터로 트랜잭션을 다시 빌드하세요 |
| 109 | UnknownError | 분류되지 않은 트랜잭션 무효 오류 | 노드 로그에서 자세한 내용을 확인하세요 |
| 193 | ReplayProtectionViolation | 트랜잭션이 리플레이 보호를 위반한 경우 (인텐트 중복) | 해당 트랜잭션 또는 인텐트가 이미 제출되었습니다 |
| 194 | BalanceCheckOutOfBounds | 토큰 잔액이 오버플로우 또는 언더플로우를 일으킬 경우 | 토큰 수량이 표현 가능한 범위를 초과하지 않는지 확인하세요 |
| 195 | InputNotInUtxos | 입력이 UTXO 집합에 존재하지 않는 UTXO를 참조하는 경우 | 해당 코인이 이미 사용되었을 수 있습니다. 지갑 상태를 다시 동기화하세요 |
| 196 | DustDoubleSpend | 동일한 DUST를 이중으로 지출하려는 경우 | DUST UTXO가 이미 소비되었습니다. DUST 지갑을 다시 동기화하세요 |
| 197 | DustDeregistrationNotRegistered | 등록되지 않은 DUST 주소를 등록 해제하려는 경우 | DUST 주소가 현재 등록되어 있는지 확인하세요 |
| 198 | GenerationInfoAlreadyPresent | DUST 생성 정보가 이미 존재하는 경우 | 생성 정보가 중복 제출되었습니다 |
| 199 | InvariantViolation | 프로토콜 수준의 불변 조건이 위반된 경우 (예: NIGHT 공급량 초과) | 해당 트랜잭션은 근본적인 프로토콜 규칙을 위반합니다 |
| 200 | RewardTooSmall | 클레임한 보상이 최소 지급 기준에 미달하는 경우 | 보상을 더 누적한 후 클레임하세요 |
Transaction malformed (110–139, 166–192)
노드가 구조적으로 유효하지 않은 트랜잭션을 거부할 때 발생하는 오류입니다.
| Code | Name | Description | How to fix |
|---|---|---|---|
| 110 | VerifierKeyNotSet | 필수 검증자 키 없이 컨트랙트가 배포된 경우 | 컨트랙트 배포 시 검증자 키를 포함하세요 |
| 111 | TransactionTooLarge | 트랜잭션이 최대 허용 크기를 초과한 경우 | 트랜잭션 페이로드를 줄이거나 여러 트랜잭션으로 분할하세요 |
| 112 | VerifierKeyTooLarge | 검증자 키가 역직렬화 한도를 초과한 경우 | 더 작은 circuit을 사용하거나 Midnight 지원팀에 문의하세요 |
| 113 | VerifierKeyNotPresent | 참조한 검증자 키를 찾을 수 없는 경우 | circuit을 호출하기 전에 검증자 키와 함께 컨트랙트를 배포하세요 |
| 114 | ContractNotPresent | 트랜잭션이 존재하지 않는 컨트랙트를 참조하는 경우 | 컨트랙트 주소를 확인하고 먼저 컨트랙트를 배포하세요 |
| 115 | InvalidProof | 영지식 증명 검증에 실패한 경우 | 증명을 다시 생성하세요. proof server가 호환 버전인지 확인하세요 |
| 116 | BindingCommitmentOpeningInvalid | 바인딩 commitment가 올바르게 열리지 않은 경우 | Zswap 내부 오류: 트랜잭션을 다시 빌드하세요 |
| 117 | NotNormalized | 트랜잭션이 정규 형식이 아닌 경우 | SDK로 다시 빌드하세요. 제출 전 트랜잭션을 정규화하세요 |
| 118 | FallibleWithoutCheckpoint | 폴러블 트랜스크립트에 초기 체크포인트가 없는 경우 | 폴러블 섹션 시작 부분에 kernel.checkpoint()를 추가하세요 |
| 119 | ClaimReceiveFailed | 코인 commitment 수신 클레임에 실패한 경우 | 코인 commitment 형식 오류 — 트랜잭션을 다시 빌드하세요 |
| 120 | ClaimSpendFailed | 코인 commitment 지출 클레임에 실패한 경우 | 코인 commitment 형식 오류 — 트랜잭션을 다시 빌드하세요 |
| 121 | ClaimNullifierFailed | nullifier 클레임에 실패한 경우 | nullifier 형식 오류 — 트랜잭션을 다시 빌드하세요 |
| 122 | ClaimCallFailed | 컨트랙트 호출 클레임에 실패한 경우 | 컨트랙트 호출 형식 오류 — 트랜잭션을 다시 빌드하세요 |
| 123 | InvalidSchnorrProof | Fiat-Shamir Schnorr 증명 검증에 실패한 경우 | 서명 오류: 트랜잭션 서명을 다시 생성하세요 |
| 124 | UnclaimedCoinCom | 컨트랙트 소유 출력이 클레임되지 않은 채로 남아 있는 경우 | 트랜잭션 제출 전 모든 컨트랙트 출력을 클레임하세요 |
| 125 | UnclaimedNullifier | 컨트랙트 소유 코인 입력이 승인되지 않은 경우 | 모든 컨트랙트 입력을 반드시 승인하세요 |
| 126 | Unbalanced | 특정 토큰 타입에서 잔액이 음수가 된 경우 | 트랜잭션 잔액이 맞지 않습니다. 토큰 수량을 확인하세요 |
| 127 | Zswap | Zswap 오퍼의 구조가 잘못된 경우 | Zswap 오퍼를 다시 빌드하고 증명 유효성을 확인하세요 |
| 128 | BuiltinDecode | FAB(field-aligned binary) 디코드 오류 | 내부 인코딩 오류 — 데이터 형식을 확인하세요 |
| 129 | GuaranteedLimit | 보장 섹션 한도를 초과한 경우 | 보장 섹션 크기를 줄이세요 |
| 130 | MergingContracts | 컨트랙트 인텐트 병합 중 오류가 발생한 경우 | 해당 컨트랙트들은 병합할 수 없습니다. 설정을 확인하세요 |
| 131 | CantMergeTypes | 호환되지 않는 트랜잭션 타입을 병합하려는 경우 | 병합하려는 트랜잭션 타입이 서로 호환되어야 합니다 |
| 132 | ClaimOverflow | 클레임한 코인 값이 델타를 초과하는 경우 | 토큰 수량이 표현 가능한 범위를 초과합니다 |
| 133 | ClaimCoinMismatch | ClaimRewards 코인이 실제 코인과 일치하지 않는 경우 | 올바른 코인 데이터로 클레임을 다시 빌드하세요 |
| 134 | KeyNotInCommittee | 서명 키가 위원회 구성원이 아닌 경우 | 위원회 구성원만 해당 작업에 서명할 수 있습니다 |
| 135 | InvalidCommitteeSignature | 위원회 서명 검증에 실패한 경우 | 서명 키와 서명을 확인하세요 |
| 136 | ThresholdMissed | 위원회 승인 임계값에 미달하는 경우 | 위원회 서명을 더 수집하세요 |
| 137 | TooManyZswapEntries | Zswap 항목이 너무 많은 경우 (>=2^16) | shielded 작업 수를 줄이세요 |
| 138 | BalanceCheckOverspend | 트랜잭션 세그먼트에서 잔액이 음수가 된 경우 | 세그먼트가 가용 금액을 초과하여 지출합니다. 수량을 확인하세요 |
| 139 | UnknownError | 분류되지 않은 잘못된 트랜잭션 오류 | 노드 로그에서 자세한 내용을 확인하세요 |
| 166 | InvalidNetworkId | 트랜잭션의 네트워크 ID가 노드의 네트워크와 일치하지 않는 경우 | networkId가 대상과 일치하는지 확인하세요 (예: 데브넷의 경우 undeployed). setNetworkId() 설정을 확인하세요 |
| 167 | IllegallyDeclaredGuaranteed | 허용되지 않는 위치에 보장 세그먼트(0)가 사용된 경우 | 인텐트에는 segment_id 0을 사용하지 마세요 |
| 168 | FeeCalculation | 수수료 계산 오류 | 트랜잭션 크기 또는 타이밍 파라미터가 유효하지 않습니다 |
| 169 | InvalidDustRegistrationSignature | DUST 등록 서명 검증에 실패한 경우 | 올바른 키로 DUST 등록을 다시 생성하세요 |
| 170 | InvalidDustSpendProof | 트랜잭션이 선언한 시각 기준으로 노드의 DUST 상태에 대해 DUST 지출 증명 검증에 실패한 경우 | 모든 DUST 이벤트를 동기화하기 전에 트랜잭션을 빌드하는 지갑에서 이 오류가 발생합니다. 지갑이 동기화될 때까지 기다린 뒤, 새 트랜잭션을 빌드·증명·제출하세요. DUST troubleshooting을 참조하세요 |
| 171 | OutOfDustValidityWindow | 트랜잭션이 DUST 동작에 대해 선언한 시각이 블록 시각보다 늦거나, DUST grace period가 허용하는 것보다 오래된 경우 | wallet SDK는 등록에는 시스템 클럭 시각을, 수수료 지불에는 indexer의 최신 블록 시각을 선언합니다. 클럭이 체인보다 앞서 있지 않은지, indexer가 체인을 따라잡았는지 확인한 뒤 트랜잭션을 다시 빌드하세요 |
| 172 | MultipleDustRegistrationsForKey | 하나의 인텐트에 동일한 키에 대한 DUST 등록이 여러 개인 경우 | 인텐트당 키 하나에 DUST 등록은 하나만 허용됩니다 |
| 173 | InsufficientDustForRegistrationFee | 등록이 허용하는 수수료 지불액이, 해당 NIGHT UTXO가 생성된 이후 만들어 냈을 DUST보다 큰 경우 | NIGHT이 수수료만큼 DUST를 생성할 때까지 기다린 뒤 등록을 다시 빌드하세요. 지갑이 이미 보유한 DUST는 이 검사에 포함되지 않습니다. Registration rules를 참조하세요 |
| 174 | MalformedContractDeploy | 컨트랙트 배포의 구조가 유효하지 않은 경우 | 배포 시 잔액이 0이 아니거나 충전 상태가 잘못되었는지 확인하세요 |
| 175 | IntentSignatureVerificationFailure | 인텐트 서명 검증에 실패한 경우 | 인텐트 서명을 다시 생성하세요 |
| 176 | IntentSignatureKeyMismatch | 서명 키가 verifier key와 일치하지 않는 경우 | 인텐트에 올바른 서명 키를 사용하세요 |
| 177 | IntentSegmentIdCollision | 인텐트 병합 시 segment_id가 중복되는 경우 | 각 인텐트는 고유한 segment_id를 가져야 합니다 |
| 178 | IntentAtGuaranteedSegmentId | 인텐트가 segment_id 0 (보장 세그먼트 예약)에 위치한 경우 | 인텐트에는 segment_id >= 1을 사용하세요 |
| 179 | UnsupportedProofVersion | 지원되지 않는 증명 버전인 경우 | SDK 또는 proof server를 호환 버전으로 업데이트하세요 |
| 180 | GuaranteedTranscriptVersion | 보장 트랜스크립트 버전이 지원되지 않는 경우 | 호환되는 레저/SDK 버전으로 업데이트하세요 |
| 181 | FallibleTranscriptVersion | 폴러블 트랜스크립트 버전이 지원되지 않는 경우 | 호환되는 레저/SDK 버전으로 업데이트하세요 |
| 182 | TransactionApplicationError | 인텐트 TTL이 만료되었거나 너무 먼 미래인 경우 | 새 TTL로 트랜잭션을 다시 빌드하고 TTL이 지나기 전에 제출하세요 |
| 183 | BalanceCheckOutOfBounds | 세그먼트에서 잔액 오버플로우 또는 언더플로우가 발생한 경우 | 세그먼트 내 토큰 수량이 표현 가능한 범위를 초과합니다 |
| 184 | BalanceCheckConversionFailure | 잔액을 i128로 변환하는 데 실패한 경우 | 토큰 수량이 내부 표현에 비해 너무 큽니다 |
| 185 | PedersenCheckFailure | 바인딩 commitment 불일치 | 내부 암호화 오류: 트랜잭션을 다시 빌드하세요 |
| 186 | EffectsCheckFailure | 트랜잭션 이펙트 검증에 실패한 경우 | 선언된 이펙트가 계산된 이펙트와 일치하지 않습니다 |
| 187 | DisjointCheckFailure | 입력/출력 집합이 분리되어 있지 않은 경우 | shielded 및 트랜지언트 입력/출력은 서로 겹치지 않아야 합니다 |
| 188 | SequencingCheckFailure | 호출 그래프의 순서 조건이 위반된 경우 | 컨트랙트 호출은 순서 제약을 준수해야 합니다 |
| 189 | InputsNotSorted | 언shielded 입력이 정렬되지 않은 경우 | 제출 전 언shielded 입력을 정렬하세요 |
| 190 | OutputsNotSorted | 언shielded 출력이 정렬되지 않은 경우 | 제출 전 언shielded 출력을 정렬하세요 |
| 191 | DuplicateInputs | 언shielded 입력이 중복된 경우 | 트랜잭션에서 중복 입력을 제거하세요 |
| 192 | InputsSignaturesLengthMismatch | 입력 수와 서명 수가 일치하지 않는 경우 | 각 입력에 대응하는 서명이 있는지 확인하세요 |
Infrastructure errors (150–155, 165)
트랜잭션 내용과 직접 관련 없는 인프라 오류가 노드에서 발생할 때 나타나는 오류입니다.
| Code | Name | Description | How to fix |
|---|---|---|---|
| 150 | LedgerCacheError | 레저 캐시 뮤텍스/락이 오염된 경우 | 노드를 재시작하세요. 내부 동시성 오류입니다 |
| 151 | NoLedgerState | 노드에 레저 상태가 없는 경우 | 노드가 완전히 동기화되지 않았을 수 있습니다. 동기화가 완료될 때까지 기다리세요 |
| 152 | LedgerStateScaleDecodingError | 레저 상태의 SCALE 디코딩에 실패한 경우 | 노드 상태가 손상되었을 수 있습니다. 재동기화를 시도하세요 |
| 153 | ContractCallCostError | 컨트랙트 호출 비용 계산에 실패한 경우 | 내부 비용 모델 오류 |
| 154 | BlockLimitExceededError | 트랜잭션이 블록 한도를 초과한 경우 | 트랜잭션 크기를 줄이거나 덜 혼잡한 블록을 기다리세요 |
| 155 | FeeCalculationError | 수수료 계산에 실패한 경우 | 내부 수수료 모델 오류 |
| 165 | GetTransactionContextError | 트랜잭션 컨텍스트 조회에 실패한 경우 | 노드 내부 오류 |
System transaction errors (201–211)
거버넌스 및 브릿지 시스템 트랜잭션에서 노드가 오류를 만날 때 발생하는 오류입니다. 이는 네트워크 거버넌스 메커니즘이 제출하는 특수 트랜잭션입니다.
| Code | Name | Description | How to fix |
|---|---|---|---|
| 201 | IllegalPayout | 지급액이 남은 공급량 또는 브릿지 풀을 초과하는 경우 | 지급 금액이 가용 자금에 비해 너무 큽니다 |
| 202 | InsufficientTreasuryFunds | 재무부에 자금이 부족한 경우 | 요청한 금액이 재무부 잔액을 초과합니다 |
| 203 | CommitmentAlreadyPresent | 페어리 골드 이중 commitment 시도 | commitment가 이미 트리에 존재합니다 |
| 204 | UnknownError | 분류되지 않은 시스템 트랜잭션 오류 | 노드 로그를 확인하세요 |
| 205 | ReplayProtectionFailure | 시스템 트랜잭션 리플레이 보호가 위반된 경우 | 시스템 트랜잭션이 중복 제출되었습니다 |
| 206 | IllegalReserveDistribution | 리저브 배분이 공급량을 초과하는 경우 | 배분 금액이 가용 리저브를 초과합니다 |
| 207 | GenerationInfoAlreadyPresent | DUST 생성 정보가 이미 삽입된 경우 | 생성 정보가 중복 제출되었습니다 |
| 208 | InvalidBasisPoints | 브릿지 수수료 베이시스 포인트가 10,000 이상인 경우 | 베이시스 포인트는 0에서 9,999 사이여야 합니다 |
| 209 | InvariantViolation | 프로토콜 수준의 불변 조건이 위반된 경우 | 해당 트랜잭션은 근본적인 프로토콜 규칙을 위반합니다 |
| 210 | TreasuryDisabled | 비활성화된 재무부에 접근하려는 경우 | 재무부 기능이 활성화되어 있지 않습니다 |
| 211 | MerkleTreeError | 시스템 트랜잭션을 적용하는 중 머클 트리 업데이트에 실패한 경우 | 내부 ledger 오류입니다. 노드 로그를 확인하세요 |
Host API error (255)
노드가 호스트 API 오류를 만날 때 발생하는 오류입니다.
| Code | Name | Description | How to fix |
|---|---|---|---|
| 255 | HostApiError | 호스트 API 처리 중 오류가 발생한 경우 | 내부 런타임 오류입니다. 노드 로그를 확인하세요 |
Pallet dispatch errors
트랜잭션이 Substrate 팔렛 내에서 실패하면 DispatchError::Module { index, error } 형태로 오류가 표면화됩니다.
index는 팔렛을 식별하며, error는 해당 팔렛 오류 열거형 내 변형의 SCALE 인코딩 인덱스입니다.
아래는 팔렛 및 변형별로 분류된 Midnight 노드 전용 팔렛 오류 목록입니다.
Pallet index map
아래는 Midnight 노드 전용 팔렛 인덱스와 설명 목록입니다.
| Index | Pallet | Description |
|---|---|---|
| 5 | pallet_midnight | Core Midnight ledger pallet |
| 6 | pallet_midnight_system | System transaction pallet |
| 13 | pallet_cnight_observation | cNIGHT bridge observation |
| 44 | pallet_federated_authority | Governance authority |
| 45 | pallet_federated_authority_observation | Authority observation |
| 50 | pallet_system_parameters | System parameters |
| 51 | pallet_throttle | Transaction throttling |
pallet_midnight
레저 상태와 트랜잭션을 관리하는 핵심 팔렛에서 발생하는 오류입니다.
| Variant | Name | Description |
|---|---|---|
| 0 | NewStateOutOfBounds | 새 레저 상태가 허용 범위를 벗어난 경우 |
| 1 | Deserialization | DeserializationError (코드 0–11)를 래핑합니다 |
| 2 | Serialization | SerializationError (코드 50–63)를 래핑합니다 |
| 3 | Transaction | TransactionError (코드 100–211)를 래핑합니다 |
| 4 | LedgerCacheError | 레저 캐시 오염 (코드 150) |
| 5 | NoLedgerState | 레저 상태 없음 (코드 151) |
| 6 | LedgerStateScaleDecodingError | SCALE 디코딩 실패 (코드 152) |
| 7 | ContractCallCostError | 비용 계산 실패 (코드 153) |
| 8 | BlockLimitExceededError | 블록 한도 초과 (코드 154) |
| 9 | FeeCalculationError | 수수료 계산 실패 (코드 155) |
| 10 | HostApiError | 호스트 API 오류 (코드 255) |
| 11 | NetworkIdNotString | 네트워크 ID가 유효한 문자열이 아닌 경우 |
| 12 | GetTransactionContextError | 트랜잭션 컨텍스트 조회 오류 (코드 165) |
pallet_midnight_system
시스템 트랜잭션 팔렛에서 발생하는 오류입니다.
| Variant | Name | Description |
|---|---|---|
| 0 | LedgerApiError | 전체 LedgerApiError를 래핑합니다 |
| 1 | SystemTransactionNotAllowedForGovernance | 거버넌스에서 허용되지 않는 시스템 트랜잭션 |
pallet_federated_authority
다중 집합 거버넌스 권한 팔렛에서 발생하는 오류입니다.
| Variant | Name | Description |
|---|---|---|
| 0 | MotionAlreadyApproved | 권한 기관이 이미 해당 동의안을 승인한 경우 |
| 1 | MotionApprovalMissing | 승인자가 승인 목록에 없는 경우 |
| 2 | MotionApprovalExceedsBounds | 최대 권한 기관 수를 초과한 경우 |
| 3 | MotionNotFound | 동의안이 존재하지 않는 경우 |
| 4 | MotionNotEnded | 동의안 투표가 아직 완료되지 않은 경우 |
| 5 | MotionHasEnded | 동의안이 종료되어 더 이상 변경할 수 없는 경우 |
| 6 | MotionTooEarlyToClose | 승인 기간이 아직 종료되지 않은 경우 |
| 7 | MotionAlreadyExists | 동의안이 이미 존재하는 경우 |
| 8 | MotionExpired | 충분한 승인 없이 동의안이 만료된 경우 |
| 9 | MotionWeightBoundTooLow | 호출에 대한 가중치 한도가 너무 낮은 경우 |
pallet_cnight_observation
cNIGHT 브릿지 통합 팔렛에서 발생하는 오류입니다.
| Variant | Name | Description |
|---|---|---|
| 0 | MaxCardanoAddrLengthExceeded | Cardano 지갑 주소가 너무 긴 경우 |
| 1 | MaxRegistrationsExceeded | 등록이 너무 많은 경우 |
| 2 | LedgerApiError | LedgerApiError를 래핑합니다 |
| 3 | InherentAlreadyExecuted | 블록당 내재 호출은 한 번만 허용됩니다 |
| 4 | CardanoPositionRegression | 다음 Cardano 포지션이 앞으로 진행되지 않는 경우 |
| 5 | TooManyUtxos | UTXO 수가 용량을 초과하는 경우 |
pallet_federated_authority_observation
다중 집합 거버넌스 동기화 팔렛에서 발생하는 오류입니다.
| Variant | Name | Description |
|---|---|---|
| 0 | EmptyMembers | 멤버십 집합이 비어 있는 경우 |
| 1 | DuplicatedMembers | 집합에 중복 멤버가 있는 경우 |
| 2 | InherentAlreadyExecuted | 블록당 내재 호출은 한 번만 허용됩니다 |
pallet_system_parameters
시스템 파라미터 팔렛에서 발생하는 오류입니다.
| Variant | Name | Description |
|---|---|---|
| 0 | UrlTooLong | URL이 최대 허용 길이를 초과하는 경우 |
JSON-RPC error codes
Midnight 노드는 jsonrpsee 크레이트의 표준 JSON-RPC 2.0 오류 코드를 사용합니다. 아래는 노드와 상호작용할 때 자주 마주칠 수 있는 오류 코드입니다.
| Code | Name | Used in | Description |
|---|---|---|---|
| -32602 | INVALID_PARAMS | State RPC, Block RPC, Events, Peer Info | 잘못된 컨트랙트 주소, 계정 주소, 블록 해시, 피어 ID 또는 기타 유효하지 않은 파라미터 |
| -32603 | INTERNAL_ERROR | Peer Info RPC, System Parameters RPC | 내부 요청 전송/수신 실패, 런타임 API 오류 |
Transaction submission errors
DApp이나 지갑이 트랜잭션을 제출하면, 노드의 오류는 코드에 도달하기 전에 여러 소프트웨어 레이어를 거칩니다. 각 레이어는 아래 레이어의 오류를 감싸고 자신의 메시지를 덧붙입니다. 가장 먼저 보이는 메시지는 보통 근본 원인이 아니라 가장 바깥쪽 래퍼입니다.
How the error layers fit together
노드는 제출된 각 트랜잭션을 ledger에 대해 검증합니다. 검증에 실패하면 노드는 ledger 오류를 error tables의 u8 코드 중 하나로 변환합니다. 그다음 Substrate 트랜잭션 풀이 그 코드를 JSON-RPC 오류 1010으로 반환합니다.
{ "code": 1010, "message": "Invalid Transaction", "data": "Custom error: 196" }
Midnight wallet SDK로 제출하면, SDK 레이어가 다음 순서로 오류를 감쌉니다.
- Polkadot.js API 클라이언트가 응답을
1010: Invalid Transaction: Custom error: 196메시지의RpcError로 바꿉니다. - wallet SDK 노드 클라이언트(
@midnightntwrk/wallet-sdk-node-client)가 그RpcError를Transaction submission failed메시지의SubmissionError로 감쌉니다. - wallet SDK 제출 서비스(
@midnightntwrk/wallet-sdk-capabilities)가 그 오류를 다시Transaction submission error메시지의 또 다른SubmissionError로 감쌉니다. - promise 기반 API가 이름이
(FiberFailure) SubmissionError인 EffectFiberFailure로 reject합니다.WalletFacade.submitTransaction은 지갑의 shielded, unshielded, DUST 상태에서 트랜잭션을 되돌린 뒤 이 오류를 다시 throw합니다. - Midnight.js
submitCallTx가 그 오류를 메시지가Unexpected error submitting scoped transaction으로 시작하고 감싸진 오류의 텍스트를 포함하는 일반Error로 감쌉니다.
FiberFailure의 message 속성에는 가장 바깥쪽 텍스트만 담기고, FiberFailure는 error.cause를 설정하지 않습니다. Custom error: N을 포함한 전체 체인을 보려면 String(error)로 오류를 문자열로 변환하거나, Node.js에서는 console.error(error)로 기록하세요. 브라우저 콘솔은 바깥쪽 메시지만 보여주므로 거기서도 String(error)를 사용하세요. JSON.stringify(error)는 노드 오류 텍스트를 버립니다.
노드를 직접 운영한다면 노드 로그에도 원인이 기록됩니다. 제출 시점의 거부는 Rejected transaction <hash> from mempool이 포함된 줄에, 노드가 블록을 빌드하는 중에 버린 트랜잭션은 Rejecting transaction <hash> at pre-dispatch가 포함된 줄에 있습니다.
DApp이 DApp Connector API로 브라우저 지갑을 통해 제출한다면, 지갑이 제출을 수행하고 code와 reason 필드가 있는 오류를 반환합니다. API는 지갑이 노드의 응답을 포함하도록 요구하지 않습니다. reason 텍스트에 Custom error: N이 포함되어 있으면 error tables에서 N을 찾아보세요.
Codes above 255
노드 ledger 코드는 u8 값이므로 항상 0에서 255 사이입니다. 그보다 큰 숫자, 예컨대 다섯 자리 코드가 보인다면 이 페이지의 노드 오류 표에서 온 것이 아닙니다. 오류 체인의 다른 곳에서 1010 응답이나 Custom error: N 텍스트를 찾거나 노드 로그를 확인하세요.
Submission error messages
아래 표는 제출이 실패할 때 볼 수 있는 메시지, 각 메시지를 만들어 내는 레이어, 그리고 다음에 할 일을 정리한 것입니다.
| Message or error | Origin | Description | How to fix |
|---|---|---|---|
1010: Invalid Transaction: Custom error: N | 노드(Substrate 트랜잭션 풀) | 노드의 ledger가 코드 N으로 트랜잭션을 거부한 경우 | error tables에서 N을 찾아보세요 |
Custom error: N이 없는 1010: Invalid Transaction | 노드(Substrate 트랜잭션 풀) | Substrate의 weight 검사가 트랜잭션을 한 블록에 담기에 너무 무겁다고 거부한 경우. data 필드에는 Substrate의 텍스트가 담기며, 보통 Transaction would exhaust the block limits입니다 | When 1010 has no inner u8을 참조하세요 |
SubmissionError: Transaction submission failed | wallet SDK 노드 클라이언트 | 트랜잭션을 노드로 보내는 호출이 실패한 경우. 노드의 응답은 cause에 있습니다 | 1010 응답을 보려면 cause를 읽으세요 |
TransactionInvalidError: Transaction is invalid and was rejected by the node | wallet SDK 노드 클라이언트 | 노드가 트랜잭션을 풀에 받아들였다가, 현재 상태에 대한 ledger 검사를 더 이상 통과하지 못해 나중에 버린 경우. 재현된 사례에서는 노드가 블록을 빌드하는 중에 버렸습니다. 클라이언트에는 코드가 전달되지 않습니다. 직접 운영하는 노드라면 Rejecting transaction <hash> at pre-dispatch 또는 Rejected transaction <hash> from mempool이 포함된 로그 줄에서 원인을 알 수 있습니다 | 재현된 원인은 하나의 seed를 쓰는 두 지갑 인스턴스가 첫 번째 트랜잭션이 아직 대기 중일 때 같은 DUST를 지출한 것입니다. seed마다 지갑 인스턴스를 하나만 실행하고, 다음 트랜잭션을 제출하기 전에 대기 중인 트랜잭션이 확정될 때까지 기다리세요. 첫 번째 트랜잭션이 블록에 들어가면 같은 지출은 대신 Custom error: 196을 반환합니다 |
SubmissionError: Transaction submission error | wallet SDK 제출 서비스 | 제출 중 발생한 모든 노드 클라이언트 오류. 노드 거부, 연결 끊김, 또는 노드가 버렸거나 유효하지 않다고 보고한 트랜잭션을 포함합니다 | 전체 오류 체인을 출력해 가장 안쪽 오류를 찾으세요 |
(FiberFailure) SubmissionError | wallet SDK (Effect 런타임) | promise 기반 wallet SDK API가 앞 행에서 설명한 SubmissionError로 reject한 경우 | String(error)로 전체 cause 체인을 출력하세요 |
Unexpected error submitting scoped transaction '<name>': ... | Midnight.js | 트랜잭션이 블록에 도달하기 전에 submitCallTx가 실패한 경우. 메시지에는 기저 오류의 텍스트가 포함됩니다 | 메시지에서 Custom error: N을 찾아 N을 조회하세요 |
CallTxFailedError | Midnight.js | 트랜잭션이 블록에 도달했지만 상태가 SucceedEntirely가 아닌 경우 | 오류의 finalizedTxData.status를 확인해 트랜잭션의 어느 부분이 실패했는지 보세요 |
Failed to decode ledger event payload | wallet SDK shielded 지갑 | 동기화 중 지갑이 indexer에서 받은 ledger 이벤트를 역직렬화하지 못한 경우. 한 가지 원인은 wallet SDK에 번들된 ledger 버전과 네트워크가 실행하는 ledger 버전의 불일치입니다. indexer가 지갑이 디코딩할 수 없는 페이로드를 반환해도 같은 메시지가 나타납니다 | 네트워크에 맞는 wallet SDK와 Midnight.js 버전을 compatibility matrix에서 확인해 사용하세요 |
Common submission codes
다음 노드 코드는 제출 오류 안에서 자주 나타납니다. 그 의미는 노드 버전 1.0.x에 적용됩니다.
| Code | Name | Description | How to fix |
|---|---|---|---|
| 103 | Zswap | 트랜잭션의 shielded(Zswap) 부분이 ledger 상태와 충돌하는 경우. 코인의 nullifier가 이미 지출되었거나, 새 코인 commitment가 이미 존재하거나, 증명이 노드가 인식하지 못하는 코인 트리 루트를 참조하거나, 머클 트리 업데이트가 실패할 때 노드가 이 오류를 보고합니다. 노드는 과거 코인 트리 루트를 약 1시간 동안 보관하므로, 그보다 오래된 루트를 증명에 사용한 트랜잭션은 거부합니다 | 지갑이 동기화를 마치도록 둔 뒤 트랜잭션을 다시 빌드해 재제출하세요. 같은 shielded 코인을 지출하는 트랜잭션을 여러 개 동시에 제출하지 마세요 |
| 196 | DustDoubleSpend | 트랜잭션 수수료를 지불하는 DUST UTXO가 이미 지출된 경우. 그 nullifier가 이미 ledger의 DUST nullifier 집합에 있습니다 | 지갑이 앞선 트랜잭션을 동기화하도록 둔 뒤 다시 빌드해 재제출하세요. 같은 seed에서 지갑 인스턴스를 둘 이상 동시에 실행하지 말고, 이미 블록에 들어가 있을 수 있는 트랜잭션을 재제출하지 마세요 |