In brief
A Kaspa wallet is software for keys, addresses, signing, and transaction workflow. Network evidence is checked separately from what a wallet screen shows.
What this page explains#
Wallet troubleshooting maps symptoms to wallet file, daemon, node connection, network, UTXO index, signing, and broadcast layers. This page sits in Wallets, Nodes, And Mining. It gives the topic a plain-language handle first, then shows the working idea, the mechanism, the source trail, and any limits that still matter. This category is operational, so every explanation is tied to an observable workflow. A wallet can build and sign intent, a node can sync and serve state, a miner can work on templates, and none of those observations by themselves replace accepted-network evidence.
The writing follows a simple Kaspa documentation pattern: answer the practical question first, then link outward for details. The closest public sources for this page are WIKI-CLI-WALLET, RK-WALLET, RK-WRPC, RK-RPC-TX. Local notes can help choose what to explain, but public-facing references resolve to upstream websites, repositories, papers, release pages, or docs.
How to think about it#
The practical model starts by naming the layer that owns the topic: wallet use, node operation, consensus, transaction validation, Toccata script behavior, tooling, or research. From there, the page shows which public source can support the explanation and where the explanation becomes incomplete.
For Wallet Troubleshooting, the model is built around these anchors: wrong network creates plausible but useless evidence; missing node indexes can break balance or UTXO queries; signing failures need wallet and sighash context; broadcast errors can be mempool or network failures; accepted evidence should be checked before retry loops. This model is useful, but it does not encode every constant, branch, error type, or edge case. Those details belong in the source path and the source notes.
How it works#
1. wrong network creates plausible but useless evidence. Operational pages explain the workflow by separating local intent, local process state, network submission, and accepted evidence. The guide names the moving part first, then gives the verification surface that can prove or disprove the claim.
2. missing node indexes can break balance or UTXO queries. A UTXO explanation begins with outputs that can later be spent. Inputs do not draw from an account balance; they reference earlier outputs by outpoint and provide the data needed to authorize the spend. This is why wallet balance, transaction construction, validation, and covenant state all need the same ownership vocabulary.
3. signing failures need wallet and sighash context. Signing is a commitment boundary. A wallet or SDK can construct intent, but a signature only authorizes the fields covered by the signing algorithm and available UTXO context. The review must confirm that versioned fields, previous outputs, sequences, payloads, gas, covenant data, scripts, values, and hash-type choices are not silently lost before or after signing.
4. broadcast errors can be mempool or network failures. Mempool and relay behavior describe what a node is willing to hold, replace, forward, or package; they are not final acceptance. Block templates are candidate work for miners, and they can change as node state or policy changes. The guide names each stage separately: built, signed, submitted, admitted, relayed, templated, mined, and accepted.
5. accepted evidence should be checked before retry loops. Virtual state is the bridge from ordered consensus consequences into the state surfaces that tools can inspect. Mempool visibility says a node is considering a transaction; accepted evidence says the transaction was incorporated through consensus processing. UTXO diffs, accepting data, and indexer replay are the review trail for applications that need durable state.
This mechanism section separates local action, node state, network submission, and accepted evidence. Commands and catalogs are useful only when current source or release evidence keeps them fresh.
How to check it#
| Step | Check | Evidence gate |
|---|---|---|
| 1 | Check wrong network creates plausible but useless evidence. | Use WIKI-CLI-WALLET, RK-WALLET, RK-WRPC; check version, network, node sync, index, wallet or miner state, and accepted evidence separately. |
| 2 | Check missing node indexes can break balance or UTXO queries. | Use WIKI-CLI-WALLET, RK-WALLET, RK-WRPC; check version, network, node sync, index, wallet or miner state, and accepted evidence separately. |
| 3 | Check signing failures need wallet and sighash context. | Use WIKI-CLI-WALLET, RK-WALLET, RK-WRPC; check version, network, node sync, index, wallet or miner state, and accepted evidence separately. |
| 4 | Check broadcast errors can be mempool or network failures. | Use WIKI-CLI-WALLET, RK-WALLET, RK-WRPC; check version, network, node sync, index, wallet or miner state, and accepted evidence separately. |
| 5 | Check accepted evidence should be checked before retry loops. | Use WIKI-CLI-WALLET, RK-WALLET, RK-WRPC; check version, network, node sync, index, wallet or miner state, and accepted evidence separately. |
When using this page operationally, record the network, software version, node sync state, wallet or miner state, and the observation being made. A local command result is useful evidence, but accepted network consequences require accepted transaction, UTXO, block, or node-source details.
Related Pages#
- wallet-safety-and-backup
- wallets-nodes-mining
- nodes