Skip to content

Wallet User Guide

Jump to bottom Edit New page
Yeastplume edited this page Feb 3, 2020 · 65 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
   -tor/
   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.

  • tor contains TOR configuration files used by the wallet listener. There should be no need to manipulate anything in this directory manually.

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:3413. 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 could not be 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 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 a successful wallet init, the wallet will 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.

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

Recovering from an existing seed

If you need to recreate your wallet from an existing seed, 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

This command will recreate your existing wallet seed. On first run, the wallet will scan the entire chain and restore any outputs that may belong to the wallet.

recover

The recover command is used to display the wallet's 24 (or 12) word recovery phrase, e.g:

grin-wallet recover
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.

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
 Awaiting Finalization            | 1200.453000000
 Locked by previous transaction   | 1200.453000000
 -------------------------------- | -------------
 Currently Spendable              | 0.000000000

Command 'info' completed successfully
  • Total is the total confirmed amount in the wallet, including coins ready for spending and those awaiting confirmation.
  • Immature coinbase denotes coinbase rewards in the wallet that have not yet matured and are unavailable for spending (you must wait a day's worth of blocks, or 1440 before spending coinbase outputs).
  • Awaiting confirmation denotes the balance from transactions that have appeared on-chain but for which your wallet is waiting a set number of blocks before marking them as spendable. You can override this value by providing the -c (--minimum_confirmations) switch to the wallet.
  • Awaiting Finalization is the balance from transactions that have not yet appeared on the chain. This is usually due to the other involved party not having completed or posted a transaction. This amount does not appear in the wallet total.
  • Locked by previous transaction is the balance locked by a previous transaction you have made that is currently awaiting finalization. This is usually made up of change outputs that are to be returned to your wallet. Once the involved transaction appears on chain, this balance should become unlocked and available for spending.
  • Currently Spendable is the amount currently available for transacting.

listen

The listen command opens an http and (if available) TOR 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 http 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

Note that listening externally via the -e switch is not necessary when using your TOR hidden service address (see below.

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). As an alternative to this, you can ensure your wallet is:

Listening via TOR

As of v3.0.0, the wallet listener is capable of listening via a TOR hidden service. This means that listeners do not have to worry about configuring their network or firewalls so long as your machine can connect to the TOR network.

The wallet listener will automatically listen via TOR so long as the tor or tor.exe executable is available on the system path. If TO is found, the wallet will automatically configure a hidden service and display the wallet's listening address. This address can then be provided to other users to send you funds via the send command.

Note that the TOR listener still requires the http listener to be active, however it does not need to be listening externally (i.e. with the -e) flag. So long as the TOR executable is on the path, it should suffice to run grin-wallet listen.

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 TOR, 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 awaiting finalization, unconfirmed or locked until the transaction hits the chain and is mined and validated.

There are currently several methods of sending:

Sending via HTTP

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 TOR

If the recipient is running a TOR listener (see the listen command above), you can send directly to the listener's TOR hidden service address:

grin-wallet send -d "http://zw5ws7q4oh3arzskmlkco6ia4awmjr2usv72ax7z3pfmhvklhmavzoid.onion" 60.00

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.

Requesting a Payment Proof

Sending an Invoice Transaction

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.

git clone https://github.com/mimblewimble/docs.wiki

Basics

Contributing

Development

Mining

Infrastructure

Exchange integrations

R&D

Grin Community

Grin Governance

Risk Management

Grin Internals

Misc

Clone this wiki locally