How to use the Grin wallet

Prerequisites

This instructions assume you've downloaded and installed the Grin software, and are running a synced node. Instructions on how to do this can be found on the How to Run a Grin Node page.

From 1.1.0 and onwards, the Grin wallet is split out into its own repository, so you'll have to download it separately from the Grin node.

Initialize the Wallet

Before you can use the Grin wallet, it must be initialized. This process will initialize your wallet's database and create your secret master seed file.

To do this, run:

grin-wallet init

You will then be prompted to enter a password. This password will be used to encrypt your master seed file, and you will need to provide this password every time you want to use your wallet.

File /home/yeastplume/.grin/main/grin-wallet.toml configured and created
Please enter a password for your new wallet
Password: 
Confirm Password: 

Once this is done, your wallet seed file will be generated, and you will be given a 24 word recovery phrase which you can use to recover your wallet if you lose your seed file or forget the password. Write this phrase down using a pen and paper and keep it somewhere safe, since anyone who has this phrase can control all of your funds:

20190105 17:36:35.814 WARN grin_wallet::types - Generating wallet seed file at: /home/yeastplume/.grin/wallet_data/wallet.seed
Your recovery phrase is:
foster approve pen ancient engage bomb fantasy life short stuff mesh bus design truck oyster ankle shallow torch double melody town century nice report
Please back-up these words in a non-digital format.
Command 'init' completed successfully

Your wallet seed file is located at .grin/main/wallet_data/wallet.seed. Be sure to back up this file somewhere safe and ensure it remains private.

Your wallet's configuration file is located at .grin/main/grin-wallet.toml. You can change the default node address, default listener ports and many more options by editing this file. More on what these options can be used for is found below.

Connecting to a Node

Your wallet must always have a running Grin node to talk to. The node should be fully synced.

We currently recommend that you run your own node. Instructions on how to do this can be found on the How to Run a Grin Node page.

By default, the wallet attempts to communicate with a node running on your local machine. To communicate with another node, you can either specify the --api_server_address (or -r for short) on the command line, e.g.:

grin-wallet -r http://some_public_node.org:3413 info

or you can edit the value of check_node_api_http_addr in grin-wallet.toml

Checking your Wallet Balance

To check your contents of your wallet, use the info command:

grin-wallet info

____ 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

• Total is your total amount, including any balance awaiting confirmation.
• Immature Coinbase denotes any coinbase transactions (i.e. won blocks) that have yet to mature before they can be spent
• Awaiting Confirmation is the balance that the wallet won't spend until a given number of confirmations (number of blocks added to the chain since the block in which the transaction was confirmed). This defaults to 10 blocks.
• Locked by previous transaction are outputs locked by a previous send transaction, which cannot be included in further transactions. These will generally disappear (become spent) when the transaction confirms.

Sending Grins

There are a number of different ways to send grins to another wallet:

Sending via File

Sending Grins via file is currently recommended for beginners. The process is as follows:

Create a transaction file:

grin-wallet send -m file -d my_grin_transaction.tx 10.25

This will create a transaction file called my_grin_transaction.tx in the current directory.

Send the transaction file to the recipient

Send this file through whichever method you like (email, ftp) to the intended recipient. The recipient will have to perform their part of the transaction in their wallet, and send the file back to you. See Receiving a transaction file below.

Finalize the transaction

The recipient will send a transaction response file back to you. After confirming with the recipient that they processed your send file, you can then finalize and post the transaction to the chain:

grin-wallet finalize -i my_grin_transaction.tx.response

This will post the transaction to the listening grin node, and the balances should confirm in both your wallet and the recipient's wallet after a few blocks have been found.

Sending to a running wallet listener

If the recipient is running an HTTP listener, you can send an amount from your wallet to theirs and post the transaction to the chain in a single step:

grin-wallet send -d http://10.20.20.1:3415 10.25

If successful, the amounts will be confirmed in both wallets after a few blocks have been found.

Receiving Grins

Via File

The sender will send you a transaction file (as outlined in Create a transaction file), which you must import into your wallet via the receive command:

grin-wallet receive -i my_grin_transaction.tx

This will create a response file called my_grin_transaction.tx.response which you must then send back to the sender to complete and post to the chain.

Via wallet Listener

Running a wallet listener is considered an advanced operation, and should only be done by those who have the infrastructure to support it and are able to deal with NAT/Firewall issues, DOS concerns, etc, all of which are well beyond the scope of this guide

By default, the wallet will only listen to requests on the local machine. To accept wallet connections from other machines, you can edit ~/.grin/main/grin-wallet.toml as follows:

Change

api_listen_interface = "127.0.0.1"

to

api_listen_interface = "0.0.0.0"

Or any particular IP address you wish to bind to. You can then run an external wallet listener with

grin-wallet listen

Alternatively, you can pass in the -e (external) wallet argument to listen on 0.0.0.0:

grin-wallet -e listen

You can also change the listening port in grin-wallet.toml or via the command line (see grin-wallet help listen for details). Once your listener is running, any sender who wishes to send you Grins can do so as described above.

The Transaction Log

The Grin wallet maintains a log of all transaction operations. It keeps track of all completed and uncompleted transactions, as well as which outputs are associated with each. This log is useful to see where your Grins have come from, as well as for cancelling partial transactions that may not have been completed.

To view the transaction log:

grin-wallet txs

Transaction Log - Account 'default' - Block Height: 13830
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------                          
 Id  Type         Shared Transaction Id                 Creation Time        Confirmed?  Confirmation Time    Num.    Num.     Amount     Amount     Fee    Net         Tx                                                                    
                                                                                                              Inputs  Outputs  Credited   Debited           Difference  Data                                                                  
====================================================================================================================================================================================================================                          
 0   Received Tx  20f978d4-d2a5-4df2-a1a4-806330db5718  2019-01-02 12:50:33  true        2019-01-02 15:56:23  0       1        20000.0    0.0        None   20000.0     None                                                                  
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------                          
 1   Sent Tx      c2dd4216-7820-4545-bd49-eea8119c39d0  2019-01-02 15:59:20  false       None                 1       1        19998.992  20000.0    0.008  -1.008      c2dd4216-7820-4545-bd49-eea8119c39d0.grintx                           
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------                          
 2   Sent Tx      c8a7b02e-78e1-4813-b8a9-7367b630a070  2019-01-02 15:59:27  false       None                 1       1        19997.984  19998.992  0.008  -1.008      c8a7b02e-78e1-4813-b8a9-7367b630a070.grintx                           
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------                          
 3   Sent Tx      856c3c85-0cb9-4951-9f33-124f032ac21e  2019-01-02 15:59:31  false       None                 1       1        19996.976  19997.984  0.008  -1.008      856c3c85-0cb9-4951-9f33-124f032ac21e.grintx                           
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- 

To see the full details of a transaction, as well as which outputs are associated with it, use the -i parameter:

grin-wallet txs -i 3

Transaction Log - Account 'default' - Block Height: 13830
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 Id  Type     Shared Transaction Id                 Creation Time        Confirmed?  Confirmation Time  Num.    Num.     Amount     Amount     Fee    Net         Tx  
                                                                                                        Inputs  Outputs  Credited   Debited           Difference  Data 
==============================================================================================================================================================================================================
 3   Sent Tx  856c3c85-0cb9-4951-9f33-124f032ac21e  2019-01-02 15:59:31  false       None               1       1        19996.976  19997.984  0.008  -1.008      856c3c85-0cb9-4951-9f33-124f032ac21e.grintx 
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------


Wallet Outputs - Account 'default' - Block Height: 13830
----------------------------------------------------------------------------------------------------------------------------------------------------
 Output Commitment                                                   Block Height  Locked Until  Status  Coinbase?  # Confirms  Value            Tx 
====================================================================================================================================================
 08ad4948a215e22e37f7909c7e36460afa5e38d6696361b0a27b983b38e78540c5  6742          0             Spent   false      7089        19997.984000000  3 
----------------------------------------------------------------------------------------------------------------------------------------------------

Cancelling Transactions

It is very possible when using Grin to create transactions that will never be completed, particularly when using file-based or completely asynchronous transaction exchange methods.

If you have an unconfirmed transaction in your log that you don't believe will be completed, you can cancel a transaction with:

grin-wallet cancel -i 3

This will set the transaction's status to 'Cancelled', remove any unconfirmed change outputs and unlock any outputs that were previously locked by the transaction, making them available to spend again. Note that if you or someone else completes the transaction after you've cancelled it, your outputs can still end up spent and unavailable for use by your wallet. Alternatively, if you spend the same outputs in a new transaction and someone tries to complete the cancelled one, the posted transaction will fail.

Wallet Check

Because of all of the possibilities listed in the cancel command, as well as the possibility of forks, it is quite possible for your wallet to end up in an inconsistent state. For this reason, Grin provides a manual check command that scans the chain's UTXO set for any outputs belonging to your wallet, and ensures they're in a consistent state with your local wallet database.

It's important to remember that your wallet's state can always be reconstructed from the chain with your wallet's seed file or recovery phrase. If something seems off or unexpected with your balance or outputs, rest assured they're safely in the UTXO set (so long as they haven't been spent) and can always be recovered via check or restore.

To perform a check on your wallet and ensure its content matches the version on the chain, ensure you have no outstanding transactions, ensure your node is up to date then:

grin-wallet check

This scan the chain and cancel all pending transactions, unlock any locked outputs, restore any missing outputs, and ensure your wallet's content is consistent with the chain's version. You can run this command as often as you like to check and update your wallet's contents.

Recovering / Restoring a wallet from a recovery phrase

Back up your existing wallet:

mv ~/.grin/wallet_data ~/.grin/wallet_data_bak

Then:

grin-wallet init -r
[... follow onscreen instructions...]
grin-wallet restore

See restore in the user guide for further information.

Further commands

Other important commands, as well as details on all of the commands on this page, can be found in the detailed Wallet User Guide. We recommend you read through this guide to get a sense of what's possible with the wallet.

Some commands you should be particularly aware of are:

• check - Refresh your wallet outputs by keeping your transaction history log intact (always try this before restore when you are missing outputs in your wallet)
• recover - Recovers your wallet seed from a seed phrase, or view your existing recovery phrase
• restore - Restores an empty wallet from scratch from a seed file