How Snow Blossom Client Wallet Files Work

From Snowblossom Wiki
Jump to: navigation, search

Both the command line SnowBlossomClient and the GUI IceLeaf use the same wallet database structure.

The structure is that there is a directory that contains one or more .db files. The files look something like:


The '4' there is the wallet file version number. That is also embedded into the data of the file itself. Each file is a protobuf WalletDatabase object.

When Snowblossom reads these files, it merges them in memory and writes out a new single wallet file of all the data. Only if that is successfully written, the other files are deleted. This way, if the merge fails or there is an error, the source files are still there.

Whenever Snowblossom makes a change to the database, the changes are written out as a new file with a random file name. This way, if the merge is already in progress via another process, the new data will not be lost because the new file won't be removed by that merge. It will simply be picked up on the next load.

If a snowblossom client sees a file with a higher version number than it knows about, it will do the merge but will not delete the source file. The assumption is that a new file format number means there are new fields that might need special merging rules. This way, multiple files hang around until a newer client that does know how to do the merge does so.

All of this means the database structure is safe from:

  • partial writes/incomplete writes
  • simultaneous writes from multiple processes

This also means that you can do fun things like, if you have a bunch of wallets that aren't in regular use any more but you don't want to discard them, you can copy the wallet databases files into a single directory and let the merge smash them into one. (If there are multiple seeds, all seeds will be preserved)

The same goes for backup restores. If you aren't sure which copies are the newest, you can copy them all into a single directory and let the merge work it out.

For example, lets say you are using a QHARD wallet so you don't get HD deterministic key generation. Lets suppose you copied that wallet onto a computer and were using it, which involved generating some new keys. Then that computer was broken for a while and you were using the wallet elsewhere, generating new keys there as well. Once you get the first computer working, you can simply copy in the files and the merge will preserve all addresses generated from either computer.

You can of course automate that syncing with tools like dropbox or unison.