Wallet User Guide

Gary Yu edited this page Feb 8, 2019 · 25 revisions

Grin Wallet User Guide

General Information

Wallet File Structure

A Grin wallet maintains its state in an LMDB database, with the master seed stored in a separate file. When creating a new wallet, the file structure should be:

~/[Wallet Directory]
   -wallet_data/
      -db/
         -/lmdb
      wallet.seed
   grin-wallet.toml
   grin-wallet.log
  • grin-wallet.toml contains configuration information for the wallet. You can modify values within to change ports, the address of your grin node, or logging values.

  • wallet_data/wallet.seed is your master seed file. Its contents are encrypted with your password (required). You should back this file up somewhere in order to be able to recover or restore your wallet. Your seed file can also be recovered using a seed phrase if you lose this file or forget your password.

Data Directory

By default grin will create all wallet files in the hidden directory .grin under your home directory (i.e. ~/.grin). You can also create and use a wallet with data files in the current directory, as explained in the grin wallet init command below.

Logging Output

Logging configuration for the wallet is read from grin-wallet.toml.

Global Wallet Arguments

Account

The wallet supports multiple accounts. To set the active account for a wallet command, use the '-a' switch, e.g:

grin wallet -a account_1 info

All output creation, transaction building, and querying is done against a particular account in the wallet. If the '-a' switch is not provided for a command, the account named 'default' is used.

Node Address

The wallet generally needs to talk to a running grin node in order to remain up-to-date and verify its contents. By default, the wallet tries to contact a node at 127.0.0.1:13413. To change this, modify the value in the wallet's grin_wallet.toml file. Alternatively, you can provide the -r (seRver) switch to the wallet command, e.g.:

grin wallet -r "http://192.168.0.2:1341" info

If commands that need to update from a grin node can't find one, they will generally inform you that the node couldn't be reached and the results verified against the latest chain information.

Password

Your wallet.seed file, which contains your wallet's unique master seed, is encrypted with your password. Your password is specified at wallet creation time, and must be provided for any wallet operation. You will be prompted for your password when required, but you can also specify it on the command line by providing the -p argument. Please note this will place your password in your shell's command history, so use this switch with caution.

grin wallet -p mypass info

Wallet Commands

help

grin wallet --help will display usage info and all flags. grin wallet help [command] will display flags specific to the command, e.g grin wallet help listen

init

Before using a wallet a new grin-wallet.toml configuration file, master seed (contained in wallet.seed) and storage database need to be generated via the init command as follows:

grin wallet init

You will be prompted to enter a password for the new wallet. By default, your wallet files will be placed into ~/.grin. Alternatively, if you'd like to run a wallet in a directory other than the default, you can run:

grin wallet -p mypass init -h

This will create a grin-wallet.toml file in the current directory configured to use the data files in the current directory, as well as all needed data files. When running any grin wallet command, grin will check the current directory to see if a grin-wallet.toml file exists. If not it will use the default in ~/.grin

On success, the init command will also print a 24 (or 12) word recovery phrase, which you should write down and store in a non-digital format. This phrase can be used to re-create your master seed file if it gets lost or corrupted, or if you forget the wallet password. If you'd prefer to use a 12-word recovery phrase, you can also pass in the --short_wordlist or -s parameter.

If you need to recreate your wallet, you can init a wallet with an existing recovery phrase using the -r recover flag. The following initializes a wallet in the current directory, prompting the user for a recovery phrase to use when creating its wallet.seed file.

grin wallet init -hr
File /home/yeastplume/wallet/grin-wallet.toml configured and created
Please enter your recovery phrase:
phrase> error decide hen crunch despair play entry decorate moon risk mixed exit century razor endless attack either spray small stable fan result wrong brief
Please provide a new password for the recovered wallet
Password:
Confirm Password:
20190110 11:33:42.111 WARN grin_wallet::types - Generating wallet seed file at: /home/yeastplume/wallet/wallet_data/wallet.seed                                                                                                                                                 
Your recovery phrase is:

error decide hen crunch despair play entry decorate moon risk mixed exit century razor endless attack either spray small stable fan result wrong brief

Please back-up these words in a non-digital format.
Command 'init' completed successfully

Note this will just recreate your wallet seed, not restore your wallet's contents from the chain's UTXO set. If you wish to restore your wallet outputs, you then need to run grin wallet restore

It is highly recommended that you back up the ~/.grin/wallet_data/wallet.seed file somewhere safe and private, and ensure you somehow remember the password used to encrypt the wallet seed file.

recover

The recover command is used to regenerate your wallet seed file from your recovery phrase. Note that this operation only restores your seed file, not the outputs stored in your wallet. If, for instance, you forget your wallet password, you can run grin wallet recover, and (provided you used the correct recovery phrase,) your wallet contents should again be usable.

If you're lost your password and want to recover your wallet seed while keeping all wallet contents intact, run:

grin wallet recover

Existing wallet.seed file already exists. Continue?
Continuing will back up your existing 'wallet.seed' file as 'wallet.seed.bak'

Replace seed? (y/n)> y
Please enter your recovery phrase:
phrase> bracket sail recipe violin blur trip public dance ladder wire fuel aunt rude vast gas funny deposit health fame illegal spare spell finger deer
Please provide a new password for the recovered wallet
Password: 
Confirm Password: 
20190109 16:16:00.378 WARN grin_wallet::types - /home/me/wallet_data/wallet.seed backed up as /home/me/wallet_data/wallet.seed.bak
20190109 16:16:00.383 WARN grin_wallet::types - Seed created from word list
Command 'recover' completed successfully

As shown above, you will be asked to confim backing up your existing wallet.seed file, an then prompted for your recovery phrase as well as a new password for your seed file. The old wallet.seed file will be renamed as described in the log output.

To recreate a wallet from scratch, you can also pass -r to grin wallet init).

If you're restoring a wallet from scratch, you'll then need to use the grin wallet restore command to scan the chain for your outputs and restore them.

You can also view your recovery phrase with your password by running the recover command with the -d (display) argument, e.g:

grin wallet recover -d
Password:
Your recovery phrase is:

shiver alarm excuse turtle absorb surface lunch virtual want remind hard slow vacuum park silver asthma engage library battle jelly buffalo female inquiry wire

Please back-up these words in a non-digital format.

account

The account command is use used to manage wallet accounts. To create a new account, use the grin wallet account command with the argument '-c', e.g.:

grin wallet account -c my_account

This will create a new account called 'my_account'. To use this account in subsequent commands, provide the '-a' flag to all wallet commands:

grin wallet -a my_account info

To display a list of created accounts in the wallet, use the 'account' command with no flags:

grin wallet account

____ Wallet Accounts ____

 Name       | Parent BIP-32 Derivation Path
------------+-------------------------------
 default    | m/0/0
 my_account | m/1/0
 

info

The info command summarizes wallet account balances. Note that the Total sum may appear inflated if you have a lot of unconfirmed outputs in your wallet (especially ones where a transaction is initiated by other parties who then never it by posting to the chain). Currently Spendable is the most accurate field to look at here.

grin wallet info
Password:

____ Wallet Summary Info - Account 'default' as of height 13833 ____

 Total                            | 60.482000000
 Immature Coinbase (< 1440)       | 60.030000000
 Awaiting Confirmation (< 10)     | 0.452000000
 Locked by previous transaction   | 1200.453000000
 -------------------------------- | -------------
 Currently Spendable              | 0.000000000

Command 'info' completed successfully

And you can pass the minimum confirmations optional parameter for this info command:

grin wallet info --min_conf=100
Password:

____ Wallet Summary Info - Account 'default' as of height 33868 ____

 Total                            | 0.407000000 
 Awaiting Confirmation (< 100)    | 0.058333333 
 Locked by previous transaction   | 0.174333333 
 -------------------------------- | ------------- 
 Currently Spendable              | 0.348666667 

Command 'info' completed successfully

listen

The listen command opens an http listener on the specified port, which will listen for:

  • Coinbase Transaction from a mining server
  • Transactions initiated by other parties

By default the listen commands runs in a manner that only allows access from the local machine. To open this port up to other machines, you can either modify the api_listen_interface parameter in grin-wallet.toml, or use the -e switch:

grin wallet -e listen

To change the port on which the wallet is listening, either configure api_listen_port in grin-wallet.toml or use the -l flag, e.g:

grin wallet -l 14000 listen

The wallet will listen for requests until the process is cancelled with <Ctrl-C>. Note that external ports/firewalls need to be configured properly if you're expecting requests from outside your local network (well out of the scope of this document).

send

The send command is the method through which you interactively send Grins to another party. This can either be an immediate synchronous exchange, as happens when contacting a listening wallet directly via http, or an asynchronous process, such as exchanging transaction files via email.

It's important to understand exactly what happens during a send command, so at a very basic level the send interaction is as follows:

  1. Your wallet selects a number of unspent inputs from your wallet, enough to cover the 60 grins + fees.
  2. Your wallet locks these inputs so as not to select them for other transactions, and creates a change output in your wallet for the difference.
  3. Your wallet adds these inputs and outputs to a transaction, and sends the transaction to the recipient.
  4. The recipient adds their output for 60 grins to the transaction, and returns it to the sender.
  5. The sender completes signing of the transaction.
  6. The sender posts the transaction to the chain.

Outputs in your wallet that are involved in a send transaction will appear as unconfirmed or locked until the transaction hits the chain and is mined and validated.

There are currently several methods of sending:

Synchronous HTTP transactions to a listening wallet

If the recipient is running an accessible wallet listener, sending a transaction via HTTP is the most direct method. Usually, all that should be required are the destination (-d) and the amount itself. To send an amount to another listening wallet:

grin wallet send -d "http://192.168.0.10:13415" 60.00

This will create a transaction with the other wallet listening at 192.168.0.10, port 13415 which credits the other wallet 60 grins while debiting the 60 Grin + fees from your wallet.

Sending via File

  • -m 'Method', which can be 'http', 'file' or 'self' (described above). If 'http' is specified (default), the transaction will be sent to the IP address which follows the -d flag.

Transaction can also be created via the exchange of files. If the parameter -m file is specified, Grin wallet will generate a partial transaction file under the file name specified in the -d flag:

grin wallet send -d "transaction.tx" -m file 60.00

This file then needs to be sent to the recipient, who can then import the transaction into their wallet using:

grin wallet receive -i transaction.tx

This will create a transaction.tx.response file, which the recipient must send back to the sender to finalize:

grin wallet finalize -i transaction.tx.response`

Self Sending

You can also create a transaction entirely within your own wallet by specifying the method 'self'. Using the 'self' method, you can send yourself money in a single command (for testing purposes,) or distribute funds between accounts within your wallet without having to run a listener or manipulate files. For instance, to send funds from your wallet's 'default' account to an account called 'account1', use:

grin wallet send -m self -d "account1" 60

or, to send between accounts, use the -a flag to specify the source account:

grin wallet -a "my_source_account" send -m self -d "my_dest_account" 60

When sending to self, the transaction will be created and posted to the chain in the same operation.

Other flags

  • -m 'Method', which can be 'http', 'file' or 'self' (described above).

  • -s 'Selection strategy', which can be 'all' or 'smallest'. Since it's advantageous for outputs to be removed from the Grin chain, the default strategy for selecting inputs in Step 1 above is to use as many outputs as possible to consolidate your balance into a couple of outputs. This also drastically reduces your wallet size, so everyone wins. The downside is that the entire contents of your wallet remains locked until the transaction is mined validated on the chain. To instead only select just enough inputs to cover the amount you want to send + fees, use:

grin wallet send -d "http://192.168.0.10:13415" -s smallest 60.00
  • -f 'Fluff' Grin uses a protocol called 'Dandelion' which bounces your transaction directly through several listening nodes in a 'Stem Phase' before randomly 'Fluffing', i.e. broadcasting it to the entire network. This reduces traceability at the cost of lengthening the time before your transaction appears on the chain. To ignore the stem phase and broadcast immediately:
grin wallet send -f -d "http://192.168.0.10:13415" 60.00
  • -g 'Message' - You can specify an optional message to include alongside your transaction data. This message is purely for informational purposes between all transacting participants, and is not included in transaction data sent to the chain. Each participant message includes a signature that can be verified with the participant's public key. A message can also be specified by the recipient during a grin wallet receive command.
grin wallet send -f -d "http://192.168.0.10:13415" -g "This is from Dave" 60.00

outputs

Simply displays all the the outputs in your wallet: e.g:

grin wallet outputs
Wallet Outputs - Account 'default' - Block Height: 49                                                                                                               
------------------------------------------------------------------------------------------------------------------------------------------------
 Key Id                Child Key Index  Block Height  Locked Until  Status       Is Coinbase?  Num. of Confirmations  Value         Transaction
================================================================================================================================================
Wallet Outputs - Account 'default' - Block Height: 12548
------------------------------------------------------------------------------------------------------------------------------------------------------
 Output Commitment                                                   Block Height  Locked Until  Status       Coinbase?  # Confirms  Value         Tx
======================================================================================================================================================
 0916ac8d29511c1c75a190981c09664fc077eb917888ee1755114de0e0d01101fa  12548         0             Unconfirmed  false      0           14.742000000  3
------------------------------------------------------------------------------------------------------------------------------------------------------
 088c087a1efcd3b0711fde1ef56f95b0d781dc7f9678411e8ae7fcfcd94b40c3b1  12548         0             Unconfirmed  false      0           10.250000000  4
------------------------------------------------------------------------------------------------------------------------------------------------------
 08f2218522fcc3b7e6bc24f26de25e429d057219716615e77061fcbed37df73e2b  6762          6762          Locked       false      5787        0.049000000   3
------------------------------------------------------------------------------------------------------------------------------------------------------
 08feb352971ed97918759ba29461aed9634989c3080c9319bcd2a99b46662cd3f2  6762          6762          Locked       false      5787        24.950000000  3
------------------------------------------------------------------------------------------------------------------------------------------------------

Spent outputs are not shown by default. To show them, provide the -s flag.

grin wallet -s outputs

txs

Every time an operation is performed in your wallet (receive coinbase, send, receive), an entry is added to an internal transaction log containing vital information about the transaction. Because the Mimblewimble chain contains no identifying information whatsoever, this transaction log is necessary in order to allow your wallet to keep track of what was sent and received. To view the contents of the transaction log, use the txs command:

grin wallet txs
Transaction Log - Account 'default' - Block Height: 49                                                                                                                                                                                                                                                                                            
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 Id  Type                 Shared Transaction Id                 Creation Time                      Confirmed?  Confirmation Time                  Num. Inputs  Num. Outputs  Amount Credited  Amount Debited  Fee          Net Difference
==========================================================================================================================================================================================================================================
 1   Confirmed Coinbase   None                                  2018-07-20 19:46:45.658263284 UTC  true        2018-07-20 19:46:45.658264768 UTC  0            1             60.000000000     0.000000000     None         60.000000000
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 2   Confirmed Coinbase   None                                  2018-07-20 19:46:45.658424352 UTC  true        2018-07-20 19:46:45.658425102 UTC  0            1             60.000000000     0.000000000     None         60.000000000
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 3   Confirmed Coinbase   None                                  2018-07-20 19:46:45.658541297 UTC  true        2018-07-20 19:46:45.658542029 UTC  0            1             60.000000000     0.000000000     None         60.000000000
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 4   Confirmed Coinbase   None                                  2018-07-20 19:46:45.658657246 UTC  true        2018-07-20 19:46:45.658657970 UTC  0            1             60.000000000     0.000000000     None         60.000000000
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 5   Confirmed Coinbase   None                                  2018-07-20 19:46:45.658864074 UTC  true        2018-07-20 19:46:45.658864821 UTC  0            1             60.000000000     0.000000000     None         60.000000000
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 6   Received Tx          03715cf6-f29b-4a3a-bda5-b02cba6bf0d9  2018-07-20 19:46:46.120244904 UTC  false       None                               0            1             60.000000000     0.000000000     None         60.000000000
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

To see the inputs/outputs associated with a particular transaction, use the -i switch providing the Id of the given transaction, e.g:

grin wallet txs -i 6
Transaction Log - Account 'default' - Block Height: 49
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 Id  Type         Shared Transaction Id                 Creation Time                      Confirmed?  Confirmation Time  Num. Inputs  Num. Outputs  Amount Credited  Amount Debited  Fee   Net Difference
===========================================================================================================================================================================================================
 6   Received Tx  03715cf6-f29b-4a3a-bda5-b02cba6bf0d9  2018-07-20 19:46:46.120244904 UTC  false       None               0            1             60.000000000     0.000000000     None  60.000000000
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------


Wallet Outputs - Block Height: 49
------------------------------------------------------------------------------------------------------------------------------------------------
 Key Id                Child Key Index  Block Height  Locked Until  Status       Is Coinbase?  Num. of Confirmations  Value         Transaction
================================================================================================================================================
 a7aebee71fdd78396ae6  9                5             0             Unconfirmed  false         0                      60.000000000  6
------------------------------------------------------------------------------------------------------------------------------------------------

cancel

Everything before Step 6 in the (send)[send] phase above happens completely locally in the wallets' data storage and separately from the chain. Since it's very easy for a sender, (through error or malice,) to fail to post a transaction to the chain, it's very possible for the contents of a wallet to become locked, with all outputs unable to be selected because the wallet is waiting for a transaction that will never hit the chain to complete. For example, in the output from grin wallet txs -i 6 above, the transaction is showing as confirmed == false meaning the wallet has not seen any of the associated outputs on the chain. If it's evident that this transaction will never be posted, locked outputs can be unlocked and associate unconfirmed outputs removed with the cancel command.

Running against the data above, as an example:

grin wallet cancel -i 6
grin wallet txs -i 6
Transaction Log - Account 'default' - Block Height: 49
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 Id  Type                     Shared Transaction Id                 Creation Time                      Confirmed?  Confirmation Time  Num. Inputs  Num. Outputs  Amount Credited  Amount Debited  Fee   Net Difference
=======================================================================================================================================================================================================================
 6   Received Tx - Cancelled  03715cf6-f29b-4a3a-bda5-b02cba6bf0d9  2018-07-20 19:46:46.120244904 UTC  false       None               0            1             60.000000000     0.000000000     None  60.000000000
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Note that the Receive transaction has been cancelled, and the corresponding output was removed from the wallet. If I were the sender, my change output would have been deleted, and any outputs that were locked for the transaction would again be available for use in another transaction.

Be sure to use this command with caution, as there are many edge cases and possible attacks that still need to be dealt with, particularly if you're the recipient of a transaction. For the time being please be 100% certain that the relevant transaction is never, ever going to be posted before running grin wallet cancel

repost

If you're the sender of a posted transaction that doesn't confirm on the chain (due to a fork or full transaction pool), you can repost the copy of it that grin automatically stores in your wallet data whenever a transaction is finalized. This doesn't need to communicate with the recipient again, it just re-posts a transaction created during a previous send attempt.

To do this, look up the transaction id using the grin wallet txs command, and using the id (say 3 in this example,) enter:

grin wallet repost -i 3

This will attempt to repost the transaction to the chain. Note this won't attempt to send if the transaction is already marked as 'confirmed' within the wallet.

You can also use the repost command to dump the transaction in a raw json format with the -m (duMp) switch, e.g:

grin wallet repost -i 3 -m tx_3.json

This will create a file called tx_3.json containing your raw transaction data. Note that this formatting in the file isn't yet very user-readable.

check

If for some reason the wallet cancel commands above don't work and you believe your outputs are in an inconsistent state, you have two options, check and restore. It's highly recommended you try the check command first, as it will leave your transaction history log intact.

The check command will scan the entire UTXO set from the node, identify which outputs are yours and update your wallet state to be consistent with what's currently in the UTXO set. This command will unlock all outputs, restore any missing outputs, and mark any outputs that have been marked 'Spent' but are still in the UTXO set as 'Unspent' (as can happen during a fork). It will also attempt to cancel any transaction log entries associated with any locked outputs or outputs incorrectly marked 'Spent'

For these reasons, you should be fairly sure that nobody will attempt to post any unconfirmed transactions involving your wallet before trying this command, (but even it someone does, it should be possible to re-run this command to fix any resulting issues.

To attempt a repair, ensure a wallet listener isn't running, and enter:

grin wallet check

The operation may take some time (it's advised to only perform this operation using a release build,) and it will report any inconsistencies it finds and repairs it makes. Once it's done, the state of your wallet outputs should match the contents of the chain's UTXO set.

restore

If check isn't working, or you need to restore your wallet from a backed up wallet.seed file and password, or have recovered the wallet seed from a recovery phrase, you can perform a full wallet restore.

This command acts similarly to the check command in that it scans the UTXO set for your outputs, however it will only restore found UTXOs into an empty wallet, refusing to run if the wallet isn't empty.

Preparing to restore from a backed-up wallet.seed file

Generate an empty wallet somewhere with:

grin wallet init -h

Delete the newly generated wallet seed file:

[host@new_wallet_dir]$ rm wallet_data/wallet.seed

Copy your backed up wallet.seed file into the new wallet_data directory.

Preparing to restore from a recovery phrase

Create a new wallet using the -r flag:

grin wallet init -r

or to create in the current directory instead of in ~/.grin:

grin wallet init -hr

Check the the grin wallet recover command for further options

Performing the restore

Ensure the Grin node with which your wallet is communicating is running, and make sure nothing is attempting to mine into your wallet. If you're restoring into a custom wallet location, ensure your current directory is the one containing its grin-wallet.toml file.

Then:

grin wallet restore

Note this operation can potentially take a long time. Once it's done, your wallet outputs should be restored, and you'll be able to transact with your restored wallet as before the backup. Your transaction log history is not restored, and will simply contain incoming transactions for each output found.

Wallet plugins

Other than the default communication methods (http, file), grin exposes an interface that developers can use to integrate any communication channel (i.e Telegram, Signal, email) for the exchange of slates.

Keybase

Grin comes bundled with an experimental keybase.io plugin. The keybase client must be installed in the system. Usage is as follows:

Recipient starts a keybase listener.

grin wallet listen -m keybase

Sender creates a transaction, sends it to the recipient and awaits for the reply.

grin wallet send <amount> -m keybase -d <recipient>

Where recipient is a keybase username. If everything goes well the transaction is finalized and sent to the node for broadcasting.

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.