eth: The Command-Line Interface Client
Note: This chapter is for getting started with the command-line client
eth. If you are interested only in AlethZero, move on to the next chapter.
eth or ++eth as it is sometimes referred to, is the TurboEthereum CLI client. To use it, you should open a terminal on your system.
eth normally just runs in the background. If you want an interactive console (you do!), it has an option:
console (it has two others -
export. We'll get to those later. So now, start
You'll see a little bit of information:
(++)Ethereum Beware. You're entering the Frontier! 16:13:52| Id: ##59650f8a… 16:13:58| Opened blockchain DB. Latest: #d4e56740… (rebuild not needed) 16:13:58| Opened state DB.
Using the Testnet
There are two Ethereum "networks": the mainnet (the current version of which is called "Frontier") and the testnet (currently called "Morden"). They're independent of each other. The only difference between the two is that ether is essentially gratis on the testnet. By default, you'll connect to the mainnet. If you want to connect to the Morden testnet instead, start
eth with the
--testnet option instead:
eth console --testnet
Setting your Master Password
After this information, the first thing it will do is ask you for a master password.
Please enter a MASTER password to protect your key store (make it strong!):
The master password is a password that protects your privacy and acts as a default security measure for your various Ethereum identities. Even with access to your computer nobody can work out who your online Ethereum addresses are without this password. It's also a default security password for your other keys, if you don't want to be remembering too many password. Anyway, it's the first line of defence and aught to be strong.
Enter a password, preferably taking into account sage advice on password creation. Then when it asks for a confirmation...
Please confirm the password by entering it again:
...enter it again.
It will pause shortly while it figures out your network environment and starts it all up. After a little while, you'll see some information on the software as well as on the account it created for you.
Your First Account
This is your newly created default account (or 'identity'. I use the words interchangeably). In my case, it was the account that begins with
XE712F44. This is an ICAP code, similar to an IBAN code that you might have used when doing banking transfers. You and only you have the special secret key for this account. It's guarded by the password you just typed. Don't ever tell anyone your password or they'll be able to send ether from this account and use it for nefarious means.
Transaction Signer: XE712F44QOZBKNLD20DLAEE8O2YJ7XRGP4 (be5af9b0-9917-b9bc-8f95-65cb9f042052 - 0093503f) Mining Beneficiary: XE712F44QOZBKNLD20DLAEE8O2YJ7XRGP4 (be5af9b0-9917-b9bc-8f95-65cb9f042052 - 0093503f)
eth is nice. It tells you that any transactions you do will come from your account beginning with
XE712F44. Similarly by default, if you mine successfully with the inbuilt miner, the proceeds will go into the same account.
You'll notice that there are two other codes in parentheses. The first is the UUID of the key. This is a code, only used on your computer, which allows us to identify which file the key is stored in without giving any any information of what account the key is for. In this case, the UUID begins with
The second piece of information that is parenthesised is the first few digits of the hex key. Older clients and Ethereum software depend on this to identify accounts. We don't use it any more because it's longer and doesn't have any way of determining if an address is invalid, so errors with mistyping can easily have major consequences.
Let's check that you do indeed have the key file for this account!
Find that Key!
If you're using Linux or MacOS, open another terminal and navigate to
~/.web3/keys. This is where all of your keys are stored. Enter
ls and make sure there's a file that corresponds to the account's UUID.
For Windows users, just use Explorer to navigate into your home folder's AppData/Web3/keys directory (you might need to enable Show Hidden Files to get there).
If you don't find a file with the same name as the UUID, then something is terribly wrong (out of disk space, possibly)! Get yourself on the forums and ask before going any further.
You'll now start seeing a little bit of information as it tries to connect to the network. You might see a line like:
18:25:31|p2p Hello: ++eth-v0.9.40-727666c2/EthDEV Server Frontier//RelWithDebInfo-Linux/g++/JIT V[ 4 ] ##979b7fa2… (eth,61) 30303
This is it telling you that it's managed to contact another node. After a little while it will begin to synchronise to the network. This will probably give you an awful lot of messages. If there are too many for you to handle, reduce them by changing the verbosity. We can set the verbosity to zero (the lowest and quietest) by typing:
true to tell you that all is fine:
> web3.admin.setVerbosity(0) true
As it synchronises, the latest block number will constantly rise, usually rather fast. Once it is synchronised, it'll still rise but much more slowly - at around 1 block every 15 seconds.
You can check its progress by using the console to get the latest block number. To do this, type:
You'll end up with something like:
> web3.eth.blockNumber 11254
You can easily check to see if you have ether in your account using the
eth.getBalance function of
web3. For this to work you'll need the address of which to get the balance. In my case, the address is the aforementioned
> web3.eth.getBalance("XE712F44QOZBKNLD20DLAEE8O2YJ7XRGP4") 0
That's not much, but then it is after all a newly cerated account. Let's query the balance of an account that actually has some funds, the Ethereum Foundation wallet:
> web3.eth.getBalance("XE86PXQKKKORDZQ1RWT9LGUGYZ1U57A56Y2") 11901464239480000000000000
Ooh, rather a lot more. The answer is given in Wei, the lowest denomination of ether. To work out what this is in sensible terms, use
web3.fromWei and provide a sensible unit, e.g.
grand (a grand, for those unfamiliar with English slang, is one thousand Ether):
> web3.fromWei(web3.eth.getBalance("de0b295669a9fd93d5f28d9ec85e40f4cb697bae"), 'grand') 11901.46423948
Wow that's nearly 12 million ether.
When you're done playing, simply type
web3.admin.exit() to exit