-
Notifications
You must be signed in to change notification settings - Fork 25
How to use the Vcash wallet
This instructions assume you've downloaded and installed the Vcash software, and are running a synced node. Instructions on how to do this can be found on the How to Run a Vcash Node page.
Before you can use the Vcash wallet, it must be initialized. This process will initialize your wallet's database and create your secret master seed file.
To do this, run:
vcash-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/.vcash/main/vcash-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/.vcash/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 .vcash/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 .vcash/main/vcash-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.
Your wallet must always have a running VCash 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 Vcash 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.:
vcash-wallet -r http://some_public_node.org:3513 info
or you can edit the value of check_node_api_http_addr in vcash-wallet.toml
To check your contents of your wallet, use the info command:
vcash-wallet info
____ Wallet Summary Info - Account 'default' as of height 195 ____
Total | 20.000000000
Awaiting Confirmation (< 1) | 0.000000000
Awaiting Finalization | 0.000000000
Locked by previous transaction | 0.000000000
-------------------------------- | -------------
Currently Spendable | 20.000000000
-------------------------------- | -------------
-------------------------------- | -------------
Token Type | 02533eac442e90da5b206d6e5e1cf3d997fc8c69e83eab8929776a1e3369ac94
Total | 30.000000000
Awaiting Confirmation (< 1) | 0.000000000
Awaiting Finalization | 0.000000000
Locked by previous transaction | 0.000000000
-------------------------------- | -------------
Currently Spendable | 30.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.
- Token Type is your token asset's token id.
There are a number of different ways to send vcash/token to another wallet:
Sending Vcash via file is currently recommended for beginners. The process is as follows:
vcash-wallet send -m file -d my_vcash_transaction.tx 10.25
This will create a transaction file called my_vcash_transaction.tx in the current directory.
For token:
./vcash-wallet send -k 02533eac442e90da5b206d6e5e1cf3d997fc8c69e83eab8929776a1e3369ac94 -m file -d my_vcash_transaction.tx 10
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.
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:
vcash-wallet finalize -i my_vcash_transaction.tx.response
This will post the transaction to the listening vcash node, and the balances should confirm in both your wallet and the recipient's wallet after a few blocks have been found.
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:
vcash-wallet send -d http://10.20.20.1:3415 10.25
For token:
./vcash-wallet send -k 02533eac442e90da5b206d6e5e1cf3d997fc8c69e83eab8929776a1e3369ac94 -d http://10.20.20.1:3415 10
If successful, the amounts will be confirmed in both wallets after a few blocks have been found.
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:
vcash-wallet receive -i my_vcash_transaction.tx
This will create a response file called my_vcash_transaction.tx.response which you must then send back to the sender to complete and post to the chain.
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 ~./vcash-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
vcash-wallet listen
Alternatively, you can pass in the -e (external) wallet argument to listen on 0.0.0.0:
vcash-wallet -e listen
You can also change the listening port in vcash-wallet.toml or via the command line (see cash wallet help listen for details). Once you listener is running, any sender who wishes to send you Vcash can do so as described above
Anyone can issue a token asset on VCash now. To issue your own token, use issue_token command with an issue amount:
vcash-wallet issue_token 21000000
Then you can use info command to check your balance.
The Vcash 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 Vcash have come from, as well as for cancelling partial transactions that may not have been completed.
To view the transaction log:
vcash-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:
vcash-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
----------------------------------------------------------------------------------------------------------------------------------------------------
It is very possible when using Vcash 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:
vcash-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.
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, Vcash provides a manual scan 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 scan or restore.
To perform a scan 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:
vcash-wallet scan
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.
Back up your existing wallet:
mv ~/.vcash/wallet_data ~/.vcash/wallet_data_bak
Then:
vcash-wallet init -r
[... follow onscreen instructions...]
vcash-wallet restore
See restore in the user guide for further information.
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
restorewhen 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