Skip to main content

Wallet Recovery

In this tutorial, we learn how to recover the wallet after there was an error submitting it. This happens for example if you try to submit a transaction and it fails at broadcast time or at the node.

When this happens, the wallet might be in a state where the current interaction locally is not the same as the current interaction on the node. brambl-cli offers several ways to diagnose and recover the wallet.

Diagnosing the Problem

The first step is to diagnose the problem. A symptom that your wallet is not in sync with the node is that checking the balance on an address does not match the expected balance.

For example, if you check the balance of an address and it shows 0, but you know that the address has funds, then the wallet is not in sync with the node. This can happen because the lock template of that address is shared with another wallet and the other wallet has already spent the funds. If this happens, you can sync the wallet with the node using the sync command. The sync command will update the wallet with the current state of the node.

Another symptom is that you try to submit a transaction and it fails with an error that no UTXOs are available. This can happen if you created a transaction and never submitted it. What happened here, is that the wallet moved to the next interaction internally, and thus is not checking the correct address. You can check list of interactions using the wallet list-interactions command. You can then use the wallet set-interaction command to set the current interaction to the correct one.

Syncing the Wallet

To sync the wallet run the following command:

brambl-cli wallet sync --template-name $LOCK_TEMPLATE_NAME --fellowship-name $FELLOWSHIP_NAME --walletdb $WALLET -n $NETWORK -h $HOST --port $PORT --keyfile $KEYFILE -w $PASSWORD

This will sync the wallet for the fellowship $FELLOWSHIP_NAME and template $LOCK_TEMPLATE_NAME with the bifrost node running on $HOST on port $PORT. The keyfile $KEYFILE is used to derive keys. The password for the wallet is $PASSWORD.

The procedure for the sync is the following:

  • we first derive the next address for the fellowship and template
  • we query the node to see if the UTXOs in that address are spent
  • if the UTXOs are spent, then we derive the next address and repeat the process

Listing Interactions

Each time a transaction is created a new interaction is created. To list all the interactions of a given wallet for a given fellowship and template, use the following command:

brambl-cli wallet list-interactions --walletdb $WALLETDB --fellowship-name $FELLOWSHIP --template-name $TEMPLATE

The result is given in the following format:

<fellowship id> <template id> <interaction id> <address at the location>

Using this feature you can get the addresses at each interaction and check if the address you are trying to use is the correct one.

Setting the Current Interaction

Each time a transaction is created a new interaction is created. Sometimes the transaction might not be useful or might be invalid. In this case, the interaction can be reset. This command will set the interaction to a given value.

brambl-cli wallet set-interaction  --walletdb $WALLET_DB --from-fellowship $FELLOWSHIP --from-template $TEMPLATE --from-interaction $NEW_INTERACTION


Using these commands you can recover your wallet and continue using it.