How to use the Grin wallet

[WIP]

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.

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/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/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/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:13413 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
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

• 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 though whatever means 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 your both 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:13415 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 must edit ~./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

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