|
|
| (19 intermediate revisions by 7 users not shown) |
| Line 1: |
Line 1: |
| ==Documentation of Electrum Bitcoin Client (Focus on the GUI)==
| | Electrum documentation is now hosted at http://docs.electrum.org |
| This page tries to document certain aspects of the [[Electrum|Electrum]] Bitcoin Client. The focus is on explaining certain aspects of its GUI, such that it gets easier for the user to understand its use.
| |
| | |
| More documentation, especially with regard to command line parameters, can be found at the parent page of this Wiki, i.e. [[Electrum|here]].
| |
| | |
| ===Version Info===
| |
| Unless stated otherwise in particular sub-sections, the present state of this documentation is based on
| |
| * '''Electrum version 0.58'''
| |
| As this documentation gets updated, this "version info" can be updated, too!
| |
| | |
| Later versions of Electrum may add new features or deviate from this description to some extend.
| |
| | |
| ===Open/Unclear Points===
| |
| Text in curly brackets {like this} means that the author(s) of this documentation are not really sure about this...
| |
| | |
| --> other authors are welcome to correct/clarify
| |
| | |
| Discussions should take place on the [[Talk:Electrum/Documentation|Discussion page.]]
| |
| | |
| ==What is a "Wallet" and a "Bitcoin Address"?==
| |
| * (General, not specific to Electrum)
| |
| | |
| Your wallet is a list of Bitcoin addresses (more precisely: a list of privat/public key pairs). Each address "contains" (or is associated with) a certain amount of Bitcoins at a given time.
| |
| | |
| Your wallet's balance is the sum of all Bitcoins of all your wallet's Bitcoin addresses.
| |
| | |
| Your wallet consists of both [[#Normal Addresses|normal addresses]] and [[#Change Addresses|change addresses]]. Although they are fully equivalent from the Bitcoin protocol's point of view, they are different in how they are used by Bitcoin clients like Electrum.
| |
| | |
| ===Normal Addresses===
| |
| * (More or less general, not too specific to Electrum)
| |
| ====How are New "Normal Addresses" Created for my Wallet?====
| |
| A Bitcoin client allows you to trigger the generation of a new Bitcoin address either manually, or it generates new addresses automatically upon certain conditions. The latter applies to Electrum: Depending on the "[[#What is the "Gap Limit"?|gap limit]]" setting in Electrum's program preferences, there will always be a certain number of unused addresses showing up in your list of receive addresses (=your own wallet's addresses), and as these addresses get used, new ones will show up automatically.
| |
| | |
| Typically you want to use a new address for receiving Bitcoins from somebody, instead of using any of your wallet's present addresses that have already been used for earlier transactions. This is to protect your privacy, because all Bitcoins transfers are published in the blockchain and can be read by anyone.
| |
| | |
| Another way of adding addresses to your wallet is to [[#Imported Addresses|import]] private keys (with their addresses of course), using Electrum's [[Electrum|command line options]]. See section about [[#Imported Addresses|imported addresses]] for more details.
| |
| | |
| ===Change Addresses===
| |
| * (More or less general, not too specific to Electrum)
| |
| ====What is a "Change Address", and why is it useful?====
| |
| The concept of change addresses is a feature not of the Bitcoin protocol, but of a Bitcoin client. It is implemented not only in Electrum but in most Bitcoin clients, including the original "Satoshi" Bitcoin client.
| |
| | |
| '''How it works:'''
| |
| | |
| Whenever your Bitcoin client (e.g. Electrum) sends Bitcoins from your wallet's address "A" to a foreing address "B", a new change address "C" is created by Electrum and added to your wallet.
| |
| | |
| Example: Address "A" has 20 BTC. Electrum sends 9 BTC from "A" to "B". The change (20-9 = 11 BTC) is sent to the "change address" "C". For this purpose, address "C" is created by Electrum at this moment and added to your wallet.
| |
| | |
| Exception: If all the Bitcoins of "A" are sent to "B", there is no need for creating a change address "C".
| |
| | |
| Actually, Bitcoin clients can also work without change addresses. In this case, the change would be sent back to "A" instead of the new address "C".
| |
| | |
| '''Why the concept of "change addresses" is useful:'''
| |
| | |
| * Using a new change address makes it more difficult for other people (by analyzing the blockchain) to track how many Bitcoins you have or where you're spending them.
| |
| * It also conceals which output is the "spend" and which is the "change".
| |
| | |
| ===Imported Addresses===
| |
| Instead of generating new addresses in the default way from the wallet's [[#Seed|seed]], Electrum also allows you to import addresses (and their private keys of course) from external sources, e.g. from another Bitcoin client's wallet. For this, use Electrum's [[Electrum|command line]] options. Note that imported addresses cannot be recovered from your wallet's [[#Seed|seed]] and therefore need to be secured separately for a complete backup of your wallet.
| |
| | |
| Imported addresses can be used like any other [[#Normal Addresses|normal]] receive address with Electrum for transmission or reception of Bitcoins, and can also be (un)tagged as [[#What does it mean to "Prioritize" or "Freeze" Addresses in Electrum?|"prioritized" or "frozen"]].
| |
| | |
| ===Deterministic Wallet===
| |
| ====What is a "Deterministic Wallet" in Electrum?====
| |
| Traditionally, all new addresses (incl. the private keys of course) added to the wallet ([[#Normal Addresses|normal addresses]] or [[#Change Addresses|change addresses]]) are generated randomly. This is the case e.g. for the original "Satoshi Bitcoin Client" (at least as of today, version 0.6.2).
| |
| | |
| Contrary to that, a Bitcoin client with a "Deterministic Wallet" will generate all new addresses accoding to a pre-defined (i.e. "deterministic") algorithm as a function of a wallet-specific [[#Seed|seed]], which is a 128 bit number. This means, if the seed is known, all new addresses that Electrum will ever create for this wallet are known, because Electrum's algorithm is known (and open source).
| |
| This is a big advantage when it comes to making wallet backups:
| |
| * ''Traditionally'', a wallet backup just contains the bitcoin addresses (and private keys of course) that have been created by the client by the time the backup was made. If the user performs transactions after the backup, new addresses ([[#Normal Addresses|normal]] or [[#Change Addresses|change]] addresses) will be generated and added to the wallet. These are not included in the backup yet. If the wallet in use gets lost, all the Bitcoins that are associated with the new addresses will also be lost. To avoid the risk of a too high loss, regular wallet backups are important.
| |
| * ''With a Deterministic Wallet'' (like with Electrum), the wallet backup only needs to contain the seed, and all new addresses generated in the future are already secured by the initial backup. Hence, regular new backups are not required!
| |
| | |
| ===Seed===
| |
| ====What is the "Seed" of a Deterministic Wallet in Electrum?====
| |
| The Seed of a [[#Deterministic Wallet|deterministic wallet]] is a series of 128 random bits in Electrum.
| |
| For convenience, a seed can also be expressed by a sequence of 12 words in Electrum, and it also supports generation of a QR code to facilitate the backup of the seed.
| |
| | |
| So there are 2^128 possible seeds for a deterministic wallet in Electrum.
| |
| For comparison, the total number of Bitcoin addresses is 2^160, and the number of atoms on earth is 2^166.
| |
| So there exists one Bitcoin address per 1 Million atoms on earth, and there exists one seed of Electrum wallets per 4.3 Billion Bitcoin addresses.
| |
| (By the way: The number of atoms in the complete universe is estimated as 2^266).
| |
| | |
| ===What is the "Gap Limit"?===
| |
| | |
| The gap limit is the maximal number of contiguous unused addresses in your deterministic sequence of addresses.
| |
| | |
| If you recover your wallet from seed, you will notice that the gap limit is asked by the recovery dialog.
| |
| It is used in order to decide when to stop the recovery procedure.
| |
| | |
| If you need to have more receiving addresses in your wallet, you may increase your gap limit (expert mode).
| |
| This, however, means that you will need to remember the new limit in order to be able to recover your wallet from seed.
| |
| | |
| {
| |
| | |
| To avoid misunderstandings and panic: This does not mean that you will irrecoverably loose your funds when you have forgotten the gap limit and want to recover your wallet from seed. It just means:
| |
| * If you enter a too low gap limit when recovering a wallet from seed, it may happen that some of the later addresses in the deterministic sequence of addresses are not recovered although they have a balance>0, such that your wallet will not show the full balance.
| |
| * If you enter a too high value for the gap limit when recovering a wallet from seed, you will unnecessarily generate too many new addresses that will then show up in your wallet, all with zero balance. But at least all your funds are recovered in this case.
| |
| | |
| }
| |
| | |
| ==More on the Electrum GUI==
| |
| ===What does it mean to "Prioritize" or "Freeze" Addresses in Electrum?===
| |
| When sending Bitcoins to a foreign address, Electrum will by default use a built-in method to select the address(es) of the wallet used for sending these Bitcoins.
| |
| | |
| * When you ''prioritize'' some of your wallet's addresses, these addresses will be used with preference. Other addresses will not be used until the prioritized addresses contain no more Bitcoins.
| |
| * When you ''freeze'' some of your wallet's addresses, these addresses will not be used for sending bitcoins. Instead, other addresses will be used. Sending Bitcoins is not possible if the non-frozen addresses of your wallet do not contain enough funds.
| |
| | |
| The user can (de)prioritize or (un)freeze both [[#Normal Addresses|normal]] and [[#Change Addresses|change]] addresses.
| |
| | |
| Note: Clearly, an address can not be "prioritized" and "frozen" at the same time.
| |
| | |
| ===What does the "Tx" column mean in Electrum?===
| |
| * Expert Mode only
| |
| * Applies to "Receive" tab (own wallet's addresses) and "Contacts" tab (foreing addresses).
| |
| | |
| Tx stands for {... ?? "Transaction"? "Transmission" ?? ...}
| |
| | |
| The Tx column in Electrum displays a number for each Bitcoin address in the address list, both for own addresses ("Receive" tab) and for foreing addresses ("Contacts" tab).
| |
| | |
| '''In the "Receive" tab (own addresses):'''
| |
| | |
| The number in the Tx column indicates the total number of _incoming_ Bitcoin transactions that have ever been sent to this address.
| |
| | |
| {
| |
| The number of outgoing transactions is apparently not counted. It is unclear why the column is called "Tx" and not "Rx", because it indicates the number of times that Bitcoins have been sent to this address, i.e. how often this address has "received" Bitcoins.
| |
| Does this "Tx" come from blockchain/blockexplorer terminology? Or why is it called "Tx" ("transmit") and not "Rx" ("receive")? To be clarified.
| |
| }
| |
| | |
| '''In the "Contacts" tab (foreign addresses):'''
| |
| | |
| The number in the Tx column indicates the total number of Bitcoin transactions that have ever been carried out from addresses of the current wallet towards this contact address
| |
| | |
| ===What does the "Balance" column mean in Electrum?===
| |
| * Expert Mode only
| |
| * Applies to "Receive" tab only (i.e. own wallet's addresses).
| |
| | |
| The balance column indicates the amount of Bitcoins belonging to the given address.
| |
| The individual balances add up to the total balance of your wallet.
| |
| | |
| ===What does the "Flag" column mean in Electrum?===
| |
| * Expert Mode only
| |
| * Applies to "Receive" tab only (i.e. own wallet's addresses).
| |
| | |
| This column indicates certain properties of the different addresses:
| |
| * C = [[#Change Addresses|Change address]] (without a "C" it means it is a [[#Normal Addresses|normal address]])
| |
| * P = Prioritized address
| |
| * F = Frozen address
| |
| * I = [[#Imported Addresses|Imported address]]
| |
| | |
| Note: P and F flags can be applied to both [[#Normal Addresses|normal]] and [[#Change Addresses|change]] addresses, and also to [[#Imported Addresses|imported addresses]].
| |
| | |
| ===What do colors mean?===
| |
| In the Receive tab:
| |
| *green = prioritized
| |
| *blue = frozen
| |
| In the Contacts tab:
| |
| *gray = alias
| |
| | |
| ==Troubleshooting==
| |
| | |
| === 'transaction rejected by memorypool' errors ===
| |
| | |
| When you send a transaction, there is a delay before the Electrum client displays the transaction in its history.
| |
| This is because the server polls bitcoind's memorypool every 10 seconds.
| |
| | |
| If you create another transaction during this interval, during which the first tx is not displayed,
| |
| then your client will pick the same coins again, and the transaction will be rejected as a double spend.
| |
| | |
| | |
| | |
| ==External Links==
| |
| * [http://ecdsa.org/electrum Electrum] project website
| |
| * [https://gitorious.org/electrum Electrum] project source (gitorius)
| |
| * [https://bitcointalk.org/index.php?topic=50936.msg950497#msg950497 Electrum Forum] - here this documentation was started
| |