Wallet Data File Format

Wallet File

Each wallet should be saved to its own file in local (or cloud) storage so it can be backed-up and restored independently of other user wallets.

On-disk json data format

{
  "displayName": "[wallet_display_name]",
  "created": "unix-epoch-timestamp",
  "displayColor": "rgb-value",
  "path": "m/44/[netId]/0/0/",
  "crypto": {
    "cipher": "AES-128-CTR",
    "cipherText": "8662bcdb82f8a38f2d4c3a1b6d848fbb19f03d02388aca9442d5e4cc7b5c70aff02c452b",
    "cipherIv": "106c11fa110e99fdcbc5b4a29ddbff7d",
    "mac": "7c5df1ef3bde5e2642931298a9b00fe4375e8722f32e879a155e0d031dd39cf1"
  },
  "kd": {
    "n": 262144,
    "r": 8,
    "p": 1,
    "saltLen": 16,
    "dkLen": 32,
    "salt": "48464c24034c1e706c82336172b67156"
  }
}

displayName - wallet user friendly display name
created - date wallet was created
displayColor - wallet display rgb value
path - wallet HD 44 path. Note that this specifies the wallet's network. e.g. testNet1, testNet2, mainNet... and that path excludes the accounts part. We use path instead of just netId to support additional account sets per BIP32. For now, the account in the path is always 0 so the only variable in the path is the netId
crypto - encrypted payload and decryption metadata
kd - key deviation meta-data for decrypting the payload

Decrypted cypherText prettified json

In-memory only - should not be persisted to file

{
  "seed": "8662bcdb82f8a38f2d4c3a1b6d848fbb19f03d02388aca9442d5e4cc7b5c70aff02c452b",
  "accounts": [ 
      { "displayName": "account-0-display-name",
        "created": "unix-epoch-timestamp",
        "displayColor": "rgb-value"
      },
      { "displayName": "account-1-display-name",
        "created": "unix-epoch-timestamp",
        "displayColor": "rgb-value"
      }
   ]
}

seed - wallet's master random seed (256 bits)
accounts - array of accounts user-display metadata. Note that the actual account addresses are derived from the seed. When a user adds an account to the wallet UI - a new entry for the account is added to the array with the account default meta-data such as display name and color. When a user renames an account or sets an account color then the info is saved here. The index in the array is the address index in the wallet. e.g. first entry is account 0 (the default spacemesh account for a wallet. The entry at index 1 is the first user added account, etc...
- displayName - account display name
- created - account creation time
- displayColor - account display rgb color
Note that for privacy purposes, we don't leak any account data such as account public address to the on-disk data.

File name syntax

[file-name-encoded-wallet-display-name]-[day-of-month-month-year].json

example:

my-main-wallet-03-08-2018.json

The goal is to create a human readable file name so users will be able to which of their wallets is stored in which data file.
This is useful when restoring a wallet from backup.
User doesn't have to open the data file and inspect the wallet's display name - he can see what wallet the file stores directly when browsing this file in a directory on local or cloud storage.
This is much more user-friendly than something like 106c11fa110e99fdcbc5b4a29ddbff7d.json.

Key Derivation Function