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

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

 Total                            | 94.999000000 
 Immature Coinbase (< 1440)       | 60.000000000
 Awaiting Confirmation (< 10)     | 24.999000000 
 Locked by previous transaction   | 25.000000000 
 -------------------------------- | ------------- 
 Currently Spendable              | 10.000000000 

• 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 Grin