Chapter 1: Getting Started

Contents

Introduction
What Is an Account?
First-Time Installation of the Ethereum-Mist Wallet App
Upgrading From a Previous Version
Is Your Node Fully Synced With the Network?
How the Term “Wallet” Is Used in This Guide
Changing an Account’s Name
Copying Your Account’s Address
Creating a Second Account
Don’t You Just Love Those Identicons
Private Key, Password, Backup
  Introduction
  Backup & Restore
  Password
This Is IMPORTANT: Accessing an Account
If You Already Own Some Ether
Getting Your Ether to Show up in the Wallet App
  If Your Ether Is Held at an Exchange Like Kraken or Poloniex
  If Your Ether Is Still Stored with Your Presale Wallet
  If You Have Moved Your Ether Offline into Cold Storage
If You Currently Do Not Own Any Ether
Sending Ether to Another Account
Transaction Fee
Transaction List

 

Introduction

Versions of the Wallet App are available for Linux, Mac OS X, and Windows. For the Wallet App to work, it will need to connect with a running, fully synced Ethereum node. The Mac, Linux 64Bit and Windows 64Bit versions come with a bundled Ethereum node, the Golang implementation called Geth. As this user guide is targeted at non-technical users who will not want to separately install a Geth node, only these versions with the bundled node are covered in this guide.

Note: The Mac OS X and Win 64Bit versions also include Eth, the C++ Ethereum client. However, only Geth is covered here.

The approach taken in the design of Beta 7 means that what you see the first time you run the app will be very different depending on whether you are upgrading from a previous version, or you are doing a fresh installation. If you are doing a first-time, fresh installation, continue with the next section. If you are upgrading from an earlier version of the Wallet App, or if you have ever run a standalone, standard installation of Geth, jump to this section.

What is an Account?

Before proceeding to the installation proper, we first need to become acquainted with Ethereum’s Accounts. Accounts are a central component of the Ethereum protocol playing a role in every transaction and contract. In Ethereum, there are two types of Accounts: Externally Owned Accounts and Contract Accounts. We will encounter Contract Accounts in Chapter 2. Initially, we’ll work only with Externally Owned Accounts, which we will refer to simply as Accounts throughout this guide.

Accounts can function as wallets, though they can also be used to do things other than just hold ether. In this chapter, we’ll focus on their function as wallets, in which case an Account can be thought of as simply a private key/address pair.

First-Time Installation of the Ethereum-Mist Wallet App

Downloading the Wallet App involves syncing a full copy of the Ethereum blockchain on your computer, requiring initially about one GB of disk space as of mid-February 2016. The disk space requirement will of course grow with time and the number just quoted is for an initial installation from scratch (fast sync technology). For an average computer with an average broadband connection, be prepared to wait about two hours (hopefully 🙂 ) for the initial syncing process to complete.

To do a first-time installation of the Wallet App:
Note: In this example, I work through the installation of the Win 64Bit version.

  1. Select the version you require from the available options on this page.
    For this example, I select: Ethereum-Wallet-win64-0-4-0.zip
  2. After the folder has fully downloaded, right-click on the compressed (zipped) folder and select Extract All.
    Look inside the unzipped folder for the Ethereum-Wallet application/program file. (Ethereum-Wallet.exe for Windows) and double-click it.
     
    You should then see this window:

    40newSplashEarlyLabel

  3. It is best to wait until the blockchain is fully synced before you do anything. Note that the text in blue are links, but refrain from clicking on them for now.
  4. Watch the downloaded blocks indicator at the bottom right of the window. At some point, when the downloading is nearly complete (about 1,500 blocks from the head of the chain), you will see no change in that indicator, appearing as if the process is stuck. In fact, it is not, and after allowing some time for processing of the blocks, you will see the following window indicating syncing is complete:

    40newSyncComplete

    Problems Downloading the Blockchain?

    If there is any suggestion that your node has really stopped syncing, for example, you see zero peers and the block number is not changing, try restarting the app. (In fact, if you encounter any unexpected behavior throughout the use of this app, the first remedy to try is restarting; and just keep your fingers crossed.)

    If the blockchain does not download at all, check if your computer’s clock is accurate. Some Mac users may not be able to start the Ethereum node due to a know problem relating to a missing Geth dependency (GMP). This issue is expected to be resolved in an update of Geth, though if you are adventurous, there are current solutions.


  5. Now click on the START USING ETHEREUM link.
    You will see the following screen asking if you want to import your Presale Wallet file.
    Don’t do anything yet, and just click on SKIP.

    40newFirstScreen

    You will be able to use this feature at any time after you get comfortable with the app.


  6. On selecting SKIP, you will see the following screen:

    40newSecondScreen

    This screen will help you create your first Account. In fact, you have to create an Account to proceed.


  7. Enter a strong password.
    IMPORTANT: Do not forget this password. You will not be able to access this Account, including any ether you send to it, without the password. This applies to all Accounts; you must know the password of the Account before you use it to receive ether.
  8. Click on NEXT.
    You will see the following screen. Again, don’t do anything for now.

    40newThirdScreen

    You can easily access this feature at any time.


  9. Click on NEXT.
    You will see this screen:

    40newAfterShapeShiftLabelNote: The tutorials linked on this and the next couple of screens are more suitable for users who are already comfortable with the basic functionality of the wallet app. When you are ready to explore, you can find them at the Ethereum website.
  10. When you click on LAUNCH APPLICATION!, this is what you will see:

    40newFirstAfterLaunchHD

    Note the opening screen with the Account you created during installation. The first Account you create is named ETHERBASE by default.

Now every time you restart the Wallet App, you will go straight to the Accounts Overview opening screen, bypassing all the “onboarding” and tutorial screens.

Note that every time you stop and restart the Wallet App, you will have to wait a little as your node downloads and processes the latest blocks and becomes fully synced again.

Important Note: There is a very important section on passwords, private keys and backup later in this chapter. Please be sure to read it before you start working with any ether.

Since you have completed a fresh installation, skip the next section which is for users upgrading to Beta 7 from a previous version of the Wallet App.

Upgrading From a Previous Version

This section is intended for users upgrading from a previous version of the Wallet App.

To upgrade from a previous version:
Note: In this example, I work through the installation of the Win 64Bit version.

  1. Select the version you require from the available options on this page .
    For this example, I select: Ethereum-Wallet-win64-0-4-0.zip
  2. After the folder has fully downloaded, right-click on the compressed (zipped) folder and select Extract All.
    Look inside the unzipped folder for the Ethereum-Wallet application/program file. (Ethereum-Wallet.exe for Windows) and double-click it.
    You should then see the following window as your Wallet App’s node syncs up with the network:

    40RestartOld
  3. Once your Wallet App’s node has fully synced up with the network, the familiar Accounts Overview opening screen will be displayed:

    40UpgradeOpeningScreenYour own Accounts Overview screen will display all the Accounts and Contract Wallets you had in the previous version. When you update the Wallet App by downloading a new version, the app will continue to use data from the older version. The directories holding your Account and other Wallet App data are not affected when you upgrade.

If you have just upgraded from Beta 6, you will find little that is different from that version except for the Presale Wallet import feature described here.

Is Your Node Fully Synced With the Network?

Most Wallet App operations will fail if your node is not fully synced, that is, if your copy of the blockchain is not up-to-date with the network.

To check that your copy of the blockchain is up-to-date:

  • Towards the top of the Accounts Overview screen you will see information relating to the sync status of your node. To check that all is well and that you have the latest block, compare this information with what you see in the Network Stats page.

 

How the Term “Wallet” Is Used in This Guide

Consistent usage of terms is something newcomers appreciate as it makes the learning process so much easier.

The term “wallet” can mean different things depending on the context in which it is used. People with a general understanding of Bitcoin will know that “wallet” can refer to a single private key/address pair, as in a Paper Wallet. It can also mean the app in your mobile that manages your coins. Frankly, it gets a little worse with Ethereum.

In this guide, the term “wallet” will always be used in a general/generic sense, to mean anything that can hold ether (or other crypto tokens). So, when I say wallet (or Wallet or WALLET), I can be referring to any or all of the following: Paper Wallet, Presale Wallet, a Wallet App, Multisig Wallet, etc. If I mean a specific type of wallet, then I will refer to it by its specific name, like Presale Wallet or Wallet App, for instance.

Changing an Account’s Name

The first Account you create will by default be named Etherbase. Changing the name of any Account is easy.

To change an Account’s name:

  1. In the Accounts Overview screen, click on the Account. The Specific Wallet page will display:39EditIcon
  2. Move the cursor over the Account name and you will see the Edit icon.
  3. Click on the name and the text cursor will appear allowing you to edit the name.

Copying Your Account’s Address

It will be useful to copy and paste your Account’s address into a text file for easy access.

To copy an Account’s Address:

  1. In the Accounts Overview screen, click on the Account.
  2. Click the Copy Address icon and paste the address into a document.

    Ethereum addresses are in hexadecimal format. They are made up of 40 characters (hexadecimal digits). Additionally, the address may or may not be prefixed with the hexadecimal notation “0x” (zero x). It is generally safer to use the 0x prefix.

    addressImage

    An Ethereum address with the “0x” prefix.

Creating a Second Account

You will need a second Account to follow the exercise later in this chapter. You created your first Account, Etherbase, during the installation process.

Note: Regardless of whether you have any ether, work through the following steps. (You will be shown how you can acquire some ether, if you need to, in a later section.)

To create an Account:

  • Click on ADD ACCOUNT in the Accounts Overview screen.

You will be asked to enter a password and then repeat that password.
Notice that this second Account is named Account 2.

Note: Some users have reported an issue where the Account does not create. Restarting the Wallet App should solve the problem.

Your shiny new Ethereum addresses can be tracked in an Ethereum blockchain explorer like etherscan.io, etherchain.org or live.ether.camp. (Note: It is possible that your Block Explorer may not recognize an address until it is first funded with some ether from another Account.)

Creating Accounts is free; a little rare generosity from the Ethereum protocol :). Most other operations will cost you ether, as you will soon discover. Free or not, I’m sure you appreciate the perils of juggling too many Accounts/wallets.

Don’t You Just Love Those Identicons

Identicons are not original to this app of course, but the implementation here looks and works great. Each Identicon provides a unique pictorial representation of a unique address.

Identicons are not included just for cosmetic reasons. If you are familiar with the identicons of the addresses you work with, then they can help flag an incorrect address entry; the identicon you see will just not match the one you expect. Also, if you type or paste in an address that does not conform to the address format, say you miss out the last character, you will be given ample warning:

IllegitimateAddress

Warning: To reduce the chances of entering an incorrect address, it is always best to copy and paste addresses. And check carefully! Ethereum addresses do not have a checksum like Bitcoin addresses.

Private Key, Password, Backup

Introduction

Every Account like the one you just created, is defined by a pair of keys, a private key and an address (or public key). Every private key/address pair exists as a single keyfile. Keyfiles are found in the keystore subdirectory of your Ethereum node’s data directory. But where is this all-important data directory? (Incidentally, it is a hidden directory by default.)

If you are running the Windows version of the Wallet App, the node’s data directory is located at:

C:\Users\username\%appdata%\Roaming\Ethereum
(Replace username with the actual name you use.)

Linux and Mac users will find the Ethereum node’s data directory in the following locations:

Linux: ~/.ethereum

Mac: ~/Library/Ethereum

Note that the Library, .ethereum and %appdata% directories in Mac, Linux and Windows respectively are all hidden directories. Use whatever method is appropriate for your OS to unhide or search for the contents of these hidden directories.

You should see something like this:

keystoreFolderInside the keystore subdirectory, you will find one keyfile for each of the Accounts you have created.

Backup & Restore

You must have an Account’s keyfile to be able to send any transaction from that Account. In other words, if you delete your keyfile and do not have access to a backup copy, any ether you have stored with that Account is lost forever.

To backup your keyfiles (Accounts):

  • Copy either the individual keyfiles within the keystore subdirectory or copy the entire keystore folder. You can get directly to the keystore subdirectory by selecting the Backup menu in the Menu bar, and selecting Backup Accounts.

    MenuBackup

    Copy into a USB stick, or whatever removable media you are most comfortable with and store it safely.

If you are not going to be using an Account any time soon, that is, you are not going to be sending any transactions from that Account, you may want to backup its keyfile and then delete the keyfile from the keystore subdirectory in your computer. Make sure you have a good backup before deleting anything.

To restore your keyfiles:

  • Copy the keyfiles back into the keystore subdirectory, where they were originally.

It may be a good idea to test your backup and restore procedure with a small amount of ether first, before you send the mother load in.

Password

Each keyfile is a JSON text file which you can open and view in any text editor. The critical component of the keyfile is your Account’s private key. Importantly, this private key is always encrypted, and it is encrypted with the password you entered when you created the Account. So now you know what that password entry was all about! Hopefully you are in the habit of using strong passwords.

This is IMPORTANT: Accessing an Account

For anyone (you, a thief) to send transactions from an Account, including sending ether of course, they must have BOTH the keyfile and the password. So be absolutely sure to have a copy of your keyfile AND remember the password for that keyfile, and store them both as securely as possible. There are no escape routes here; lose the keyfile or forget your password and all your ether is gone.

If You Already Own Some Ether

What you do next will depend on whether you have any ether. And if you do have some ether, then how that ether is currently held; is it in a Presale Wallet, at an exchange, or in cold storage. If you do not yet own any ether, skip to the section that shows you how to get some.

Getting Your Ether to Show up in the Wallet App

Before you can start using the Wallet App to send your ether around, you will have to first gain access to that ether. To gain access, your ether should be in an Account that is displayed in the Wallet App. Under the hood, this means that the Wallet App has access to the encrypted keyfile that controls that Account.

If Your Ether Is Held at an Exchange Like Kraken or Poloniex

This may be ether (ETH) recently bought at the exchange using bitcoin (BTC). Or, it may be ether from your Presale Wallet that was deposited into the exchange using the exchange’s Presale Wallet import tool.

To withdraw ether from an exchange:

  • Just use the address of the first Account you created as the withdrawal address. By default this address should be named Etherbase.

Once the withdrawal has completed, you will see the withdrawn ether in your Etherbase Account the next time you start the Wallet App. (Note: Do not be concerned that you do not see the transaction listed under LATEST TRANSACTIONS. This is explained later.)

If Your Ether Is Still Stored with Your Presale Wallet

This version of the Wallet App (Beta 7) is the first to come with an easy Presale Wallet import feature.

To import your Presale Wallet Account:

  1. In the app’s menu bar, select the Accounts menu and then select the only option there: Import Pre-sale Accounts.40PresaleMenu
  2. In the following window drag and drop your .json file into the designated area and then enter your password.

    40PresaleImport

    Note: As of this writing (February 21), there have been a few reports  of the import function giving a “Wrong Password” error despite the correct password being entered. This possible bug is currently being investigated by the developers.

If You Have Moved Your Ether Offline into Cold Storage

Some of the ways in which users could currently be doing cold storage:

1. They copy individual keyfiles or the entire keystore folder onto a USB stick or some other removable media and erase the keyfile or keystore folder from their computer.

2. They simply print out on paper the contents of the keyfile. This is a JSON text file that includes the encrypted private key. They then erase the keyfile from the keystore folder in the computer.

3. They use Apps like MyEtherWallet.com or EthAddress.org to create a classic, key-pair Paper Wallet. The address and encrypted or unencrypted private key are printed out on paper, with or without QR codes.

Note: If you have taken this route, your private key must be unencrypted so that you can use the geth account import function to create a new keyfile that will be entirely compatible with Geth and the Wallet App.

How to get your cold storage wallet into the Wallet App

  1. If you have copied the keyfile and stored it on some removable media, then it is just a case of copying this keyfile back into the keystore subdirectory in the data directory being accessed by the Wallet App.
  2. If you have printed the contents of the keyfile on paper, then you have to retype and create a new keyfile using a text editor and save it with the appropriate filename. Then copy that new file into the keystore subdirectory in the data directory. Geth keyfiles must be named according to a fixed format, which should become apparent once you examine a few filenames, otherwise you will not be able to unlock the key with the password. (The UTC time and date need not be accurate, though this will affect the numbering of the Account if you have more than one.)
  3. If you have created an unencrypted Paper Wallet, with or without QR codes, using one of the available Paper Wallet creators, then use the following procedure:

To import an Account from a Paper Wallet:
Note: You will need to use a separately installed Geth node or the Wallet App’s bundled Geth node directly to implement this procedure. You need to be comfortable working with the command line interface.

  1. Using your favorite text editor, save your unencrypted private key string as a plain text file and name the file, say, key12345.txt
  2. If on Linux with a separately installed Geth node:
    Open a new terminal and enter the following:

    geth account import /path/to/key12345.txt

    If on Linux and using the bundled Geth node:
    The bundled node should be in Ethereum-Wallet-linux-x64-0-4-0/resources/node/geth for the latest Mist wallet. Running the following from within the geth directory imports the wallet:
    ./geth account import /path/to/key12345.txtIf on Windows and using the bundled Geth node:
    Search for the geth directory and open a Command window. In Win 7 your Command window should look like the following assuming key12345.txt is in the same directory as geth.exe.

    winCommandPromptBefore
  3. You will be asked to enter a passphrase and repeat it.
    Caution: Your new keyfile/Account will now be encrypted with this password. You must remember the password to unlock the Account and spend from it.
  4. The address of the imported Account will be displayed. Ensure that it is the same as the address on your Paper Wallet.

Because you did not specify a data directory with the geth account import command (Step 2), the newly created keyfile will appear in the default data directory.

You should now see the Paper Wallet Account with the correct balance displayed in your Wallet App.

If You Currently Do Not Own Any Ether

With early versions of this app, the ideal option was to acquire some ether from a friend. But with Beta 6 and beyond, your friend has some competition; in the form of ShapeShift.io.

In case you’re not familiar with ShapeShift: The service provided by ShapeShift makes it possible to immediately and conveniently exchange bitcoin and other cryptocurrencies for ether; no registration required! This service is now available right within the Wallet App, making it easier than ever to get some ether and get started.

No friends with ether, don’t want to use ShapeShift? Then there is always the traditional route of going through an exchange like Poloniex or Kraken where you can exchange bitcoin (BTC) for ether (ETH). (While ShapeShift is great for acquiring smaller amounts of ether, for larger amounts going through an exchange should be cheaper.)

To get ether from a friend:

  • If you are getting ether from a friend, send him/her your Etherbase Account address. Then monitor your Etherbase Account balance in the Wallet App to confirm that the ether has been sent.
    Once your friend has executed the send transaction, the ether should appear in your Account in a matter of seconds or a few minutes at most. (Do not be concerned that you do not see the transaction listed under LATEST TRANSACTIONS. This is explained later.)

To get ether using the integrated ShapeShift service:

  1. In the Accounts Overview screen select the Account (or Contract Wallet, which you will learn about in Chapter 2) into which you want to deposit the ether.
  2. In the Specific Wallet page, select the “Deposit Using Bitcoin” icon. You should see a window like the following:

    ShapeShiftStart

    Your address which will receive the ether is prominently displayed.

  3. Using the “Pay With” drop-down list, select Bitcoin (or any other cryptocurrency you want to exchange for ether). Optionally, enter the amount of ether you want to acquire. Then select Submit.
    Once the exchange is completed, usually within a minute or so, you will see a screen like the following:ShapeShiftCompleted

Sending Ether to Another Account

Now that you are in possession of some ether and that ether is in an Account that is displayed in your Wallet App, you can proceed to experiment with the Send function.

To send ether between Accounts that are in your Wallet App:

  1. Select the receiving Account in the Accounts Overview screen.
  2. In the Specific Wallet page for that Account, click on the Deposit icon.
    The Send Funds page will display.
  3. Check that the FROM Account is correct. If not, click on the FROM field and select the desired Account from the drop-down list.

    sendFundsPageLabelled
  4. Enter the amount you want to send.
    At the top-right of the Send Funds page, you can select the unit in which you want to specify the amount. In this example Finney is selected. The text below the AMOUNT field will display the amount you are sending in ether. Always confirm this value is correct before sending.
  5. Select the SEND button at the bottom of the page.
    You will see the Send Transaction box.
  6. Enter the password for the sending Account as requested and select Send Transaction.

You can send ether to any Account, including those not in your own Wallet App of course. All you need to execute a successful Send transaction is the receiving address.

To send ether to any Account:

  1. Ensure that the address of the receiving Account is readily available. For example, have the address in a text document so you can easily copy and paste when required.
  2. In the Accounts Overview screen, select the Account you want to send from.
  3. In the Specific Wallet page, select the Send icon.
  4. In the Send Funds page, paste the receiving address into the TO address field.
  5. Fill in the AMOUNT field and click SEND.
  6. Enter the password for the sending Account as requested and select Send Transaction.

Transaction Fee

You will incur a cost when you execute a transaction in Ethereum. Gas is the unit in which transaction cost is denoted. When you do a plain ether transfer from one Account to another Account, the transaction cost is 21,000 gas. You pay for gas with ether. The cost in ether of one unit of gas is determined dynamically by the Ethereum network. This gas price can be viewed in the Network Stats page. In January of 2016, 1 unit of gas cost 0.00000005 ether. So a 21,000 gas transaction like the ether transfer you just did, would cost 0.00105 ether (or 1.05 Finney). For a slightly more elaborate explanation, refer to this post.

Different types of transactions will incur different gas costs. The Wallet App will estimate the cost of the transaction you are about to execute. Any excess fee in that estimate will be refunded to your sending Account immediately upon execution.

Transaction List

If you have worked through this chapter, you should have at least one entry under LATEST TRANSACTIONS. The thing is, you may have expected more than one transaction to be listed if you have received ether from a friend, or an exchange or ShapeShift. This is where the following note in the Wallet App comes in: “Accounts… can’t display incoming transactions“.

You will learn about wallets that CAN list incoming transactions in the next chapter. For now, be aware that the transaction list will not show transactions in which any of your Accounts has received ether from a wallet that’s not in your Wallet App. The balance of your receiving Account will of course be updated and displayed correctly even though the transaction is not listed.

To see the details of a transaction:

  1. Click on the particular transaction to display the Transaction box.

    TransactionBoxLabelled
  2. Click on the Transaction hash or the Block hash to open a Block Explorer (Etherscan) tab in your browser with even more information relating to the transaction.

The value of the ether transferred with each transaction can be displayed in any of the following units: ETHER, FINNEY, BTC, USD, EUR. Select the desired unit by clicking on the unit selector at the top right of the Wallet App screen. Notice that the value as displayed in the transaction list is the historical value, that is, the value at the time of the transfer and not the current value. A nice feature made possible by using price data provided by cryptocompare.com.

The Filter Transactions field appears to take as input any hexadecimal digit (0123456789abcdef) plus x, that is any character in an address including the hex notation prefix. So you can filter listed transactions by address and even value or date but not names.

Advertisements