New Grin File Layout (Important for all current Grin users)

Tech Support
1

https://github.com/mimblewimble/grin/pull/1433, brings quite a few changes to the paths and file structure used by Grin, and there are few things that everyone currently running a Grin node or wallet needs to be aware of. I’ll give a quick outline of the changes here, and then give a few instructions for how to move existing wallets and chain data to the new format.

Generally:

  • The stratum server and wallet listener are disabled by default. This means if you want to mine, you’ll need to modify grin’s configuration to run the stratum server and run the wallet listener separately.
  • grin.toml no longer exists in the project files, and configuration files are now generated by the executable.
  • Configuration is now split into two files, grin-server.toml andgrin-wallet.toml (instructions below on how to generate them)
  • Running grin server or grin_wallet commands from anywhere creates or uses files in the default ~/.grin directory (this means they’re under the hidden .grin directory wherever your user home directory is.
  • It is also possible to run a server or wallet in the directory of your choosing. If a grin-server.toml (for server commands) or a grin-wallet.toml file exists in directory from where you’re running grin, the options in those files are used instead. You can generate configuration files that are automatically configured to use the current directory.

In more detail, the process of using grin is now as follows:

Normal Use:

  • Running grin from anywhere on a fresh system will create a ~/.grin directory (hidden under your user home directory). This directory will contain a chain_data directory which contains the chain, a new default grin-server.toml file with paths filled out to point at the default directory location, and the grin-server.log file

  • To run a wallet, you need to run grin wallet -p [password] init from anywhere. This will also create the ~/.grin directory if it doesn’t exist, generate a grin-wallet.toml file in there, and create a wallet_data directory which contains wallet.seed and lmdb files. All further calls to grin wallet will use those data files

  • You don’t have to have both a server and a wallet, but if you do the structure will look something like:

~/.grin
   -chain_data/
      -lmdb/
      -txhashset/
   -wallet_data/
      -db/
         -/lmdb
      wallet.seed   
   grin-server.toml
   grin-wallet.toml
   grin-server.log
   grin-wallet.log

To modify the configuration parameters for the server or wallet, modify the values in either grin-server.toml or grin-wallet.toml (both fully documented) as before.

Advanced Use

To run the server in a particular directory, the process is as follows:

Assuming you’re in the target directory.

  • Run grin server config, which will create a grin-server.toml file in the current directory, with the paths configured within to point at the current directory and create the same structure for server files as above.

  • grin server [args] run will use the grin-server.toml file in the current directory if one exists. The first time a grin server command is performed in this directory, grin will create the required database and log files.

Similarly, to run the wallet in a particular directory:

  • grin wallet -p [password] init -h will create a grin-wallet.toml file with paths configured to use the current directory, and will generate the seed and database in the current directory (with the same structure as the above example).

  • Subsequent calls to grin wallet will use settings the grin-wallet.toml file if one exists in the current directory, or the default in '~/.grin` otherwise

Migrating wallets or chains

In the case of the chain, I’d recommend just fast-syncing again from scratch so that the directories are created where they should be. If this is very annoying for you and you would rather migrate your existing data, you can either:

  • run grin once to create the default directory structure, then copy and rename your old .grin directory from wherever it’s located to ~/.grin/chain_data (the structure should look like the file layout given above)

  • In the directory where your current grin data is located, run grin server config to generate a grin-server.toml server configuration file, then modify the db_root within as follows:

db_root = "."

Similary, for the wallet:

  • run grin wallet init or grin wallet init -h (depending on where you want the wallet files), then from your old wallet, copy/rename:
old wallet.seed -> [new wallet dir]\wallet_data\wallet.seed
old wallet_data -> [new wallet dir]\wallet_data\db

The structure should look like:

~/[wallet_directory]
   -wallet_data/
      -db/ <- copy/rename OLD 'wallet_data' directory
         -/lmdb
      wallet.seed   <- copy OLD 'wallet.seed' file
   grin-wallet.toml
   grin-wallet.log

Alternatively, as with the server data, you can generate and modify a configuration file in your old directory as follow.

  • run grin wallet init -h in any directory (outside you current wallet directory).
  • copy the resulting grin-wallet.toml file to your old wallet directory
  • modify the data file path within as follows:
data_file_dir = "."

The wallet should operate as before.

These are large changes and might cause a few annoyances for the time being, but they should hopefully bring us much closer to what the file structure should look like for the actual launch. I’d also expect a few issues and teething problems to pop up, so please let me know or open an issue if you come across anything that used to work but isn’t suddenly… most likely it’s just a file path problem somewhere instead of anything being completely broken!

Around on Gitter as always for any problems.