Introducing Buttercup’s new Vault format

2 min readOct 2, 2022

Buttercup is switching vault formats from its legacy deltas format to a new, more robust and performance-friendly one. The core library has used “Format A” since the beginning — a string of commands instructing Buttercup on how to build someone’s vault, storing the vault’s complete history — but it’s become evident to the developers that it’s struggling to maintain the performance they expect. The problem with storing an ever-growing list of commands is that the vault constantly takes up more space, even if the user deletes items.

Format A’s historical commands were meant to be used as a way to rewind vaults to an earlier time, to fetch previous passwords and secrets when the user might need to recall them. At some stage item property histories were implemented where, while processing the vault’s commands, a list of all changes to each item’s properties are stored in a collection ready for the UI to display them. This wasn’t what the developers had had in mind when originally designing this, and it became evident that their original vision of rewinding state wasn’t something that users really needed.

Enter Format B, a new vault structure based on JSON. It uses a minimalistic naming scheme and structure to store the same vault data as before, but in a manner that’s both faster to parse and update, but more reliable in terms of migrations (updates in structure). Using JSON is also an obvious choice in upgrade, as it’s somewhat native to the JavaScript ecosystem.

Vault sizes are expected to drop to somewhere in the range of 20–50% of the original Format A size, which will itself increase unlock and lock times. There may be some incompatibilities in migrating to another format while other instances are unlocked and still running Format A, so it’s advised that you lock all sessions before upgrading. You should absolutely back up your vault before doing so.

Upgrade to Format B using the vault settings dialog in the Desktop application.

You will need to use the desktop application to update, and all Buttercup apps should be at the latest version to support the new format properly.

Format B will also be required for new, upcoming features such as sharing.




Free, accessible, cross-platform password manager for everyone. Manage your secrets easily on every device — never be locked out.