https://en.bitcoin.it/w/api.php?action=feedcontributions&feedformat=atom&user=Michael+SBitcoin Wiki - User contributions [en]2026-04-22T03:19:46ZUser contributionsMediaWiki 1.43.8https://en.bitcoin.it/w/index.php?title=Segwit_support&diff=63466Segwit support2017-06-18T15:50:13Z<p>Michael S: Added Poloniex to the table, like Kraken and Bitstamp already (all of them still without any support statement)</p>
<hr />
<div><big><big>'''PLEASE NOTE:''' This list is not yet complete.</big></big><br />
<br />
'''Developers: Please add a row for yourself to reflect your positions. If for some reason you don't already have a wiki account that can edit the page, make an account and ask luke-jr for help if you get caught in the anti-spam.'''<br />
<br />
{| class="wikitable"<br />
| {{No}} || doesn't support (but might or might not go along with it with sufficient community support)<br />
|-<br />
| {{Deficient}} || okay with the idea, but considers it to have insufficient community support<br />
|-<br />
| {{Evaluating}} || still evaluating the idea<br />
|-<br />
| {{AccJuly}} || it is a workable solution, provided it is activated before August 1 (and therefore BIP148-compatible)<br />
|-<br />
| {{Wanting}} || positively likes the idea, but considers it to have insufficient community support<br />
|-<br />
| {{Weak}} || better than nothing at all<br />
|-<br />
| {{Acceptable}} || it is a workable solution<br />
|-<br />
| {{Prefer}} || it is what he would choose if it was only up to him and no outside influences<br />
|}<br />
<br />
<!-- README: please keep alphabetically ordered by surname! --><br />
<br />
''Note that support for BIP148 does not mean developers support merging it into Core.''<br />
<br />
{| class="wikitable sortable"<br />
! rowspan=2 | Developer<br />
! rowspan=2 | Aff* <!-- Using one year before the the creation date of this page as the benchmark. Do not list yourself as affiliated with a project that you haven't made meaningful contributions to since then. --><br />
! Segwit itself<br />
! colspan=3 | Deployment methods<br />
! colspan=2 | Hardfork bundles (Silbert agreement)<br />
|-<br />
! [https://github.com/bitcoin/bips/blob/master/bip-0141.mediawiki BIP 141] !! [https://github.com/bitcoin/bips/blob/master/bip-0148.mediawiki BIP 148] !! [https://github.com/bitcoin/bips/blob/master/bip-0149.mediawiki BIP 149] !! [https://github.com/bitcoin/bips/blob/master/bip-0091.mediawiki BIP 91] || Segwit2x || [https://lists.linuxfoundation.org/pipermail/bitcoin-dev/2017-May/014445.html COOP]<br />
|-<br />
| Karl-Johan Alm || Core || {{Prefer}} || {{Acceptable}} || {{Acceptable}} || {{Acceptable}} || {{No}} || {{No}}<br />
|-<br />
| Bryan Bishop || Core || {{Prefer}} || {{Wanting}} || {{Acceptable}} || {{Weak}} || {{No}} || {{No}}<br />
|-<br />
| ฿tcDrak || Core || {{Prefer}} || {{Acceptable}} || {{Acceptable}} || {{No}} || {{No}} || {{No}}<br />
|-<br />
| Andrew Chow || Core || {{Prefer}} || {{Prefer}} || {{Acceptable}} || {{Weak}} || {{No}} || {{No}}<br />
|-<br />
| Matt Corallo || Core || {{Prefer}} || {{No}} || || {{Acceptable}} || {{No|LOL}} ||<br />
|-<br />
| Johnathan Corgan || Core || {{Prefer}} || {{Prefer}} || {{Acceptable}} || {{No}} || {{No}} || {{No}}<br />
|-<br />
| Luke Dashjr || Core || {{Prefer}} || {{Prefer}} || {{No}} || {{AccJuly}} || {{No}} || {{Deficient}}<br />
|-<br />
| Christian Decker || c-lightning || {{Prefer}} || {{Acceptable}} || || || || <br />
|-<br />
| Nicolas Dorier || Core || {{Prefer}} || {{Deficient}} || {{Acceptable}} || {{AccJuly}} || ||<br />
|-<br />
| Thaddeus Dryja || lit || {{Prefer}} || {{No}} || {{Acceptable}} || {{Acceptable}} || {{No}} || {{No}}<br />
|-<br />
| Marco Falke || Core || {{Prefer}} || {{Deficient}} || {{Prefer}} || {{Deficient}} || ||<br />
|-<br />
| Mark Friedenbach || BIP 68/112 || {{Prefer}} || {{Prefer}} || {{No}} || {{AccJuly}} || {{No|LOL}} || {{No|Nope}}<br />
|-<br />
| Pavel Janik || Core || {{Prefer}} || {{No}} || {{Acceptable}} || {{No}} || {{No}} || {{No}}<br />
|-<br />
| Thomas Kerin || Core || {{Prefer}} || {{Wanting}} || {{Prefer}} || {{Weak}} || {{No}} || {{No}}<br />
|-<br />
| Johnson Lau || Core || {{Prefer}} || {{Wanting}} || {{Acceptable}} || {{Acceptable}} || ||<br />
|-<br />
| Eric Lombrozo || || {{Prefer}} || {{Acceptable}} || {{Weak}} || {{AccJuly}} || {{No}} || {{No}}<br />
|-<br />
| Greg Maxwell || Core || {{Prefer}} || {{Deficient}} || {{Acceptable}} || {{Weak}} || {{No}} || {{No}}<br />
|-<br />
| Alex Morcos || Core || {{Prefer}} || {{Deficient}} || {{Acceptable}} || {{Weak}} || {{No}} ||<br />
|-<br />
| Laolu "roasbeef" Osuntokun || lnd || {{Prefer}} || || || || {{No}} ||<br />
|-<br />
| Pavol "stick" Rusnak || Trezor || {{Prefer}} || {{Wanting}} || {{Acceptable}} || {{Acceptable}} || {{No}} || {{No}}<br />
|-<br />
| Rusty Russell || c-lightning || {{Prefer}} || {{Prefer}} || || || ||<br />
|-<br />
| Gregory Sanders || Core || {{Prefer}} || {{Wanting}} || {{Acceptable}} || {{Weak}} || {{No}} ||<br />
|-<br />
| Jonas Schnelli || Core || {{Prefer}} || {{Wanting}} || {{Acceptable}} || {{Acceptable}} || {{No}} || {{No}}<br />
|-<br />
| Patrick Strateman || Core || {{Prefer}} || || || || {{No}} || {{No}}<br />
|-<br />
| Paul Sztorc || || {{Prefer}} || {{Deficient}} || {{Wanting}} || {{AccJuly}} || {{Evaluating}} || {{No}}<br />
|-<br />
| Jorge Timon || Core || {{Prefer}} || {{No}} || {{Prefer}} || {{Deficient}} || {{No}} || {{No}}<br />
|-<br />
| Peter Todd || Core || {{Prefer}} || {{Acceptable}} || || || ||<br />
|-<br />
| Warren Togami || Elements || {{Prefer}} || {{Prefer}} || {{Acceptable}} || || ||<br />
|-<br />
| Wladimir van der Laan || Core || {{Prefer}} || {{Prefer}} || {{Acceptable}} || {{Acceptable}} || {{No}} || {{No}}<br />
|-<br />
| Leo Wandersleb || Mycelium || {{Prefer}} || {{Prefer}} || {{Acceptable}} || {{Weak}} || {{No}} || {{No}}<br />
|-<br />
| Pieter Wuille || Core || {{Prefer}} || || || || {{No}} ||<br />
|}<br />
<br />
* "affiliation" is an optional field for the company or project the individual is associated with, that most qualifies the person to comment on the matter and is not meant as a company or project endorsement of the individual's position.<br />
<br />
<hr><br />
<br />
'''When adding companies below, sources for each position MUST be provided.'''<br />
<br />
{| class="wikitable sortable"<br />
! rowspan=2 | Company <br />
! rowspan=2 | Service<br />
! Segwit itself<br />
! colspan=3 | Deployment methods<br />
! colspan=2 | Hardfork bundles (Silbert agreement)<br />
|-<br />
! [https://github.com/bitcoin/bips/blob/master/bip-0141.mediawiki BIP 141] !! [https://github.com/bitcoin/bips/blob/master/bip-0148.mediawiki BIP 148] !! [https://github.com/bitcoin/bips/blob/master/bip-0149.mediawiki BIP 149] !! [https://github.com/bitcoin/bips/blob/master/bip-0091.mediawiki BIP 91] || Segwit2x || [https://lists.linuxfoundation.org/pipermail/bitcoin-dev/2017-May/014445.html COOP]<br />
|-<br />
| Abra || wallet || {{Prefer}}<ref name="coindance" /> || {{Prefer}}<ref name="coindance" /> || || {{AccJuly}} || {{AccJuly}}<ref name="silbert" /> ||<br />
|-<br />
| Bitcoin India || exchange/miner || {{Prefer}}<ref name="coindance" /> || {{Prefer}}<ref name="coindance" /> || || || ||<br />
|-<br />
| Bitfinex || exchange || {{Acceptable}}<ref name="coindance" /> || {{Acceptable}} || || || ||<br />
|-<br />
| Bitfury || miner || {{Prefer}}<ref name="coindance" /> || {{Acceptable}} || || {{AccJuly}} || {{AccJuly}}<ref name="silbert" /> ||<br />
|-<br />
| Bitmain || miner || {{AccJuly}}<ref name="bitmain">[https://blog.bitmain.com/en/uahf-contingency-plan-uasf-bip148/ Bitmain's plot against BIP148]</ref> || {{No}} || || {{AccJuly}} || {{AccJuly}}<ref name="bitmain" /> ||<br />
|-<br />
| Bitonic/BL3P.eu || exchange || {{Prefer}}<ref name="bitonic">[https://bitonic.nl/en/news/138/our-position-on-scaling-proposals Bitonic's position on scaling proposals]</ref> || {{Prefer}}<ref name="bitonic"/> || {{Acceptable}}<ref name="bitonic"/> || {{Weak}}<ref name="bitonic"/> || {{No}}<ref name="bitonic"/> || {{No}}<br />
|-<br />
| Bitpay || wallet || {{Prefer}}<ref name="bccore_swadoption"/> || {{No}} || || {{Prefer}} || {{Prefer}}<ref name="silbert" /> ||<br />
|-<br />
| Bitrated || || {{Prefer}}<ref name="coindance" /> || {{Prefer}}<ref name="coindance" /> || || || ||<br />
|-<br />
| Bitrefill || merchant || {{Prefer}}<ref name="coindance" /> || {{Prefer}}<ref name="coindance" /> || || || ||<br />
|-<br />
| Bitsquare || exchange || {{Prefer}} || {{Prefer}}<ref name="bitsquare">[https://forum.bitsquare.io/t/bitsquare-will-support-uasf-bitcoin-not-bitmaincoin/2265 Bitsquare will support UASF Bitcoin not BitMainCoin]</ref> || {{Acceptable}}<ref name="bitsquare"/> || || || ||<br />
|-<br />
| Bitstamp || exchange || || || || || ||<br />
|-<br />
| Bittylicious || exchange || {{Prefer}}<ref name="coindance" /> || {{Prefer}}<ref>[https://twitter.com/Bittylicious_/status/867305106668224513 Bittylicious answer on Twitter]</ref> || || || ||<br />
|-<br />
| Blockchain.info || wallet || {{Acceptable}}<ref name="bccore_swadoption"/> || || || {{AccJuly}} || {{AccJuly}}<ref name="silbert" /> || <br />
|-<br />
| blockonomics || || {{Prefer}} || {{Prefer}}<ref>[https://twitter.com/blockonomics_co/status/851738251509497856 blockonomics announcement on Twitter]</ref> || || || ||<br />
|-<br />
| Bustabit|| gambling || {{Prefer}}<ref name="bustabit">[https://www.bustabit.com/statement-on-forks Bustabit Statement on Bitcoin Forks]</ref> || {{Acceptable}}<ref name="bustabit"/> || || || {{AccJuly}}<ref name="bustabit"/> ||<br />
|-<br />
| Ciphrex || wallet / dev stack || {{Prefer}}<ref name="coindance" /> || {{Acceptable}}<ref name="coindance" /> || || || ||<br />
|-<br />
| Coinbase || wallet || {{Acceptable}}<ref name="bccore_swadoption"/> || || || {{AccJuly}} || {{AccJuly}}<ref name="silbert" /> || <br />
|-<br />
| CoinGate || exchange || {{Prefer}}<ref name="coindance" /> || {{Prefer}}<ref name="coindance" /> || || || ||<br />
|-<br />
| CoinJar || wallet || || {{Evaluating}}<ref>[https://twitter.com/GetCoinJar/status/875581525730787329 CoinJar answer on Twitter]</ref> || || || ||<br />
|-<br />
| Coinkite || || {{Prefer}}<ref name="coindance" /> || {{Prefer}}<ref name="coindance" /> || || || ||<br />
|-<br />
| coinomi || wallet || {{Prefer}}<ref name="coindance" /> || {{Prefer}}<ref name="coindance" /> || || || ||<br />
|-<br />
| DigitalBitbox || wallet(hardware) || {{Prefer}} || {{Acceptable}} || {{Prefer}}|| || ||<br />
|-<br />
| Échange de Montréal || exchange || {{Prefer}}<ref name="echangedemontreal" /> || {{Prefer}}<ref name="echangedemontreal" /> || || ||<br />
|-<br />
| Electrum || wallet || {{Prefer}}<ref name="coindance" /> || {{Prefer}}<ref name="coindance" /> || || || ||<br />
|-<br />
| Kraken || exchange || || || || || ||<br />
|-<br />
| LightningASIC || miner || {{Prefer}}<ref name="coindance" /> || {{Prefer}}<ref name="coindance" /> || || || ||<br />
|-<br />
| OneHash || betting || {{Prefer}}<ref>[https://blog.onehash.com/sick-of-presidential-election-3f1a2defbbbf OneHash, "Sick of presidential election ?!"]</ref> || || || {{AccJuly}} || {{AccJuly}}<ref name="silbert" /> ||<br />
|-<br />
| Poloniex || exchange || || || || || ||<br />
|-<br />
| Slushpool || miner || {{Prefer}}<ref name="coindance" /> || {{Acceptable}}<ref name="coindance" /> || || || ||<br />
|-<br />
| TheRockTrading || exchange || || {{Evaluating}}<ref>[https://twitter.com/TheRockTrading/status/872464394034315269 @TheRockTrading message on Twitter]</ref> || || || ||<br />
|-<br />
| Vaultoro || exchange || {{Prefer}}<ref name="coindance" /> || {{Acceptable}}<ref name="coindance" /> || || {{AccJuly}} || {{AccJuly}}<ref name="silbert" /> ||<br />
|-<br />
| Walltime || || {{Prefer}}<ref name="coindance" /> || {{Prefer}}<ref name="coindance" /> || || || ||<br />
|-<br />
| Xapo || wallet || {{Prefer}}<ref name="coindance" /> || || || {{Prefer}} || {{Prefer}}<ref>[https://twitter.com/tedmrogers/status/867362691370954752 Tweet by president of Xapo]</ref> || <br />
|-<br />
|}<br />
<br />
<references><br />
<ref name="bccore_swadoption">[https://bitcoincore.org/en/segwit_adoption/ Bitcoin Core's Segwit adoption list]</ref><br />
<ref name="coindance">[https://coin.dance/poli Coin Dance, "Global Bitcoin Political Support & Public Opinion"]</ref><br />
<ref name="silbert">[https://medium.com/@DCGco/bitcoin-scaling-agreement-at-consensus-2017-133521fe9a77 Digital Currency Group, "Bitcoin Scaling Agreement at Consensus 2017"]</ref><br />
<ref name="echangedemontreal">[https://twitter.com/echangedemtl/status/875781093261271040 Échange de Montréal on twitter]</ref><br />
</references></div>Michael Shttps://en.bitcoin.it/w/index.php?title=Vanitygen&diff=44883Vanitygen2014-03-10T22:22:26Z<p>Michael S: /* Vanity addresses for other crypto-coins */ PPCoin is now called Peercoin</p>
<hr />
<div>'''Vanitygen''' is a command-line vanity bitcoin address generator.<br />
<br />
If you're tired of the random, cryptic addresses generated by regular bitcoin clients, you can use vanitygen to create a more personalized address. Add unique flair when you tell people to send bitcoins to 1stDownqyMHHqnDPRSfiZ5GXJ8Gk9dbjL or dogecoins to DMooNvsY5dJth17qop3RUUnZG3ta3MW2Ua. Alternatively, vanitygen can be used to generate random addresses offline.<br />
<br />
Vanitygen accepts as input a pattern, or list of patterns to search for, and produces a list of addresses and private keys. Vanitygen's search is probabilistic, and the amount of time required to find a given pattern depends on how complex the pattern is, the speed of your computer, and whether you get lucky.<br />
<br />
The example below illustrates a session of vanitygen. It is typical, and took about 10 sec to finish, using my Core 2 Duo E6600 CPU on x86-64 Linux:<br />
<syntaxhighlight lang="bash"><br />
$ ./vanitygen 1Boat<br />
Difficulty: 4476342<br />
Pattern: 1Boat <br />
Address: 1BoatSLRHtKNngkdXEeobR76b53LETtpyT<br />
Privkey: 5J4XJRyLVgzbXEgh8VNi4qovLzxRftzMd8a18KkdXv4EqAwX3tS<br />
</syntaxhighlight><br />
<br />
Vanitygen includes components to perform address searching on your CPU (vanitygen) and your OpenCL-compatible GPU (oclvanitygen). Both can be built from source, and both are included in the Windows binary package. Also included is oclvanityminer, the vanity address mining client. Oclvanityminer can be used to automatically claim bounties on sites such as [[User:ThePiachu|ThePiachu]]'s [[Vanity Pool]].<br />
<br />
Current version: 0.22<br />
<br />
Windows x86+x64 binaries [https://github.com/downloads/samr7/vanitygen/vanitygen-0.20-win.zip here]. PGP signature [http://insight.gotdns.org/~samr7/vanitygen-0.20-win.zip.asc here].<br />
<br />
Get the source from [https://github.com/samr7/vanitygen GitHub]. Includes Makefiles for Linux and Mac OS X.<br />
<br />
Main discussion at [https://bitcointalk.org/index.php?topic=25804.0 BitCoinTalk]<br />
<br />
For AMD Catalyst 13.1+ you need to run the AMD APP SDK Runtime from Catalyst 12.10 in order to get this program to work. (So all your Catalyst drivers would be brand new except for the SDK Runtime.) This is discussed on [https://github.com/samr7/vanitygen/issues/19 GitHub]. For Linux, use AMD APP SDK 2.7.<br />
<br />
Also the latest source doesn't work properly for high-end AMD cards (7XXX and greater). Solution is to change line 459 in oclengine.c from: return quirks; to: return quirks & ~VG_OCL_AMD_BFI_INT;<br />
Windows x86+x64 binaries that solve this problem plus provide support for compressed keys [https://lifeboat.com/oclvanitygen here]. PGP signature [https://lifeboat.com/oclvanitygen.zip.sig here]. If you have any problems with the binaries, join the relevant [https://bitcointalk.org/index.php?topic=301068.0 BitCoinTalk discussion].<br />
<br />
== Expected keysearch rate ==<br />
Main article: [[Vanitygen keysearch rate]]<br />
<br />
What key search rate can I expect from hardware X?<br />
<br />
Detailed list forthcoming. Some ballpark estimates are listed below.<br />
<br />
Dual-core desktop CPUs, 32-bit mode: 100-250 Kkey/s.<br />
Dual-core desktop CPUs, 64-bit mode: 150-450 Kkey/s.<br />
Quad-core desktop CPUs, 32-bit mode: 200-400 Kkey/s.<br />
Quad-core desktop CPUs, 64-bit mode: 300-750 Kkey/s.<br />
NVIDIA GT200 GPUs: up to 6.5 Mkey/s<br />
AMD Radeon 58XX, 68XX GPUs: up to 23.5 Mkey/s.<br />
AMD Radeon 69XX GPUs: up to 19.5 Mkey/s.<br />
<br />
As vanitygen performs a lot of large integer arithmetic, running it in 64-bit mode makes a huge difference in key search rate, easily a 50% improvement over 32-bit mode. If you are using a 64-bit edition of Windows, and not using a GPU, be sure to use vanitygen64.exe.<br />
<br />
Radeon 58XX outperforms Radeon 69XX by a very comfortable margin. Oclvanitygen is sensitive to integer multiply throughput, and Radeon 58XX can multiply concurrently with other operations. At similar clocks, a hobbled Radeon 5830 will outperform a Radeon 6970.<br />
<br />
In custom builds, CPU performance will be less than expected if the OpenSSL library is an older version (<1.0.0d) or is not built with the appropriate optimizations enabled.<br />
<br />
== Vanity addresses for other crypto-coins ==<br />
While all "normal" bitcoin addresses start with a "1" (one) (except multi-signature addresses that start with "3"), some other crypto-coins use different address name spaces. Vanitygen (as of version 0.22) can be used to produce vanity addresses for these crypto coins as well (but not for [http://bitmessage.org bitmessage] addresses), by using the "-X" option. The following list provides some example command line calls and also indicates the address range for the respective coin (in ascending order of the "-X" parameter):<br />
<br />
Generate '''Bitcoin''' (BTC), '''Devcoin''' (DVC), '''Freicoin''' (FRC), '''Terracoin''' (TRC) addresses:<br />
$ ./vanitygen -X 0 1 -k<br />
or simply just<br />
$ ./vanitygen 1 -k<br />
<br />
Generate '''Bitcoin''' (BTC) etc. '''multi-signature''' addresses:<br />
$ ./vanitygen -X 5 3 -k<br />
$ ./vanitygen -X 5 31 -k<br />
$ ./vanitygen -X 5 39 -k<br />
$ ./vanitygen -X 5 3A -k<br />
$ ./vanitygen -X 5 3R -k<br />
<br />
Generate '''Novacoin''' (NVC) addresses:<br />
$ ./vanitygen -X 8 4 -k<br />
$ ./vanitygen -X 8 4D -k<br />
$ ./vanitygen -X 8 4Z -k<br />
$ ./vanitygen -X 8 4a -k<br />
$ ./vanitygen -X 8 4d -k<br />
<br />
Generate '''Feathercoin''' (FTC) addresses:<br />
$ ./vanitygen -X 14 6 -k<br />
$ ./vanitygen -X 14 6d -k<br />
$ ./vanitygen -X 14 6z -k<br />
$ ./vanitygen -X 14 7 -k<br />
$ ./vanitygen -X 14 71 -k<br />
$ ./vanitygen -X 14 72 -k<br />
$ ./vanitygen -X 14 73 -k<br />
<br />
Generate '''Anoncoin''' (ANC) addresses:<br />
$ ./vanitygen -X 23 A -k<br />
$ ./vanitygen -X 23 AF -k<br />
$ ./vanitygen -X 23 AZ -k<br />
$ ./vanitygen -X 23 Aa -k<br />
$ ./vanitygen -X 23 Af -k<br />
<br />
Generate '''Digitalcoin''' (DGC) or '''Dogecoin''' (DOGE) addresses:<br />
$ ./vanitygen -X 30 D -k<br />
$ ./vanitygen -X 30 D5 -k<br />
$ ./vanitygen -X 30 D9 -k<br />
$ ./vanitygen -X 30 DA -k<br />
$ ./vanitygen -X 30 DU -k<br />
<br />
Generate '''Franko''' (FRK) addresses:<br />
$ ./vanitygen -X 35 F -k<br />
$ ./vanitygen -X 35 FD -k<br />
$ ./vanitygen -X 35 FE -k<br />
$ ./vanitygen -X 35 FN -k<br />
$ ./vanitygen -X 35 FR -k<br />
<br />
Generate '''Litecoin''' (LTC) addresses:<br />
$ ./vanitygen -X 48 L -k<br />
$ ./vanitygen -X 48 LK -k<br />
$ ./vanitygen -X 48 LZ -k<br />
$ ./vanitygen -X 48 La -k<br />
$ ./vanitygen -X 48 Li -k<br />
<br />
Generate '''Namecoin''' (NMC) addresses:<br />
$ ./vanitygen -X 52 M -k<br />
$ ./vanitygen -X 52 Mv -k<br />
$ ./vanitygen -X 52 Mz -k<br />
$ ./vanitygen -X 52 N -k<br />
$ ./vanitygen -X 52 N1 -k<br />
$ ./vanitygen -X 52 N9 -k<br />
$ ./vanitygen -X 52 NA -k<br />
$ ./vanitygen -X 52 NK -k<br />
<br />
Generate '''Peercoin''' (='''PPCoin''') (PPC) addresses:<br />
$ ./vanitygen -X 55 P -k<br />
$ ./vanitygen -X 55 P8 -k<br />
$ ./vanitygen -X 55 P9 -k<br />
$ ./vanitygen -X 55 PA -k<br />
$ ./vanitygen -X 55 PX -k<br />
<br />
Generate '''Vertcoin''' (VTC) addresses:<br />
$ ./vanitygen -X 71 V -k<br />
$ ./vanitygen -X 71 VZ -k<br />
$ ./vanitygen -X 71 Va -k<br />
$ ./vanitygen -X 71 Vy -k<br />
<br />
Generate '''YaCoin''' (YAC) addresses:<br />
$ ./vanitygen -X 77 X -k<br />
$ ./vanitygen -X 77 Xz -k<br />
$ ./vanitygen -X 77 Y -k<br />
$ ./vanitygen -X 77 Y1 -k<br />
$ ./vanitygen -X 77 Y9 -k<br />
$ ./vanitygen -X 77 YA -k<br />
$ ./vanitygen -X 77 YP -k<br />
<br />
Generate '''BBQcoin''' (BQC) addresses:<br />
$ ./vanitygen -X 85 b -k<br />
$ ./vanitygen -X 85 bC -k<br />
$ ./vanitygen -X 85 bZ -k<br />
$ ./vanitygen -X 85 ba -k<br />
$ ./vanitygen -X 85 bc -k<br />
<br />
Generate '''Ixcoin''' (IXC) addresses:<br />
$ ./vanitygen -X 138 x -k<br />
$ ./vanitygen -X 138 xX -k<br />
$ ./vanitygen -X 138 xZ -k<br />
$ ./vanitygen -X 138 xa -k<br />
$ ./vanitygen -X 138 xv -k<br />
<br />
Generally, to find out the address format of a given crypto-coin (i.e. the number after the -X option of vanitygen) one can use this service:<br />
<nowiki>http://darkgamex.ch:2751/q/decode_address/<Address></nowiki><br />
Example: Take any Litecoin address, e.g. "LNipKabgGoTPnzhxsyFwTZdjVSXybjWucp", and submit this URL:<br />
http://darkgamex.ch:2751/q/decode_address/LNipKabgGoTPnzhxsyFwTZdjVSXybjWucp<br />
The browser output will be:<br />
30:265dcf8616a9723d3b4ba35c246b041e20013597<br />
The '''30''' is Litecoin's address format in hex (!), i.e. '''30''' (hex) = 48 (decimal) [because '''3'''*16 + '''0'''*1 = 48], i.e. use '''-X 48''' in vanitygen to generate Litecoin addresses.<br />
<br />
Some related info here: https://en.bitcoin.it/wiki/List_of_address_prefixes<br />
<br />
== See also ==<br />
* [[Firstbits]]<br />
* [[Bitcoin Vanity Generation Website]]<br />
<br />
[[Category:Vanity address]]</div>Michael Shttps://en.bitcoin.it/w/index.php?title=Vanitygen&diff=44882Vanitygen2014-03-10T22:20:16Z<p>Michael S: /* Vanity addresses for other crypto-coins */ Added Vertcoin (VTC) to the list of examples</p>
<hr />
<div>'''Vanitygen''' is a command-line vanity bitcoin address generator.<br />
<br />
If you're tired of the random, cryptic addresses generated by regular bitcoin clients, you can use vanitygen to create a more personalized address. Add unique flair when you tell people to send bitcoins to 1stDownqyMHHqnDPRSfiZ5GXJ8Gk9dbjL or dogecoins to DMooNvsY5dJth17qop3RUUnZG3ta3MW2Ua. Alternatively, vanitygen can be used to generate random addresses offline.<br />
<br />
Vanitygen accepts as input a pattern, or list of patterns to search for, and produces a list of addresses and private keys. Vanitygen's search is probabilistic, and the amount of time required to find a given pattern depends on how complex the pattern is, the speed of your computer, and whether you get lucky.<br />
<br />
The example below illustrates a session of vanitygen. It is typical, and took about 10 sec to finish, using my Core 2 Duo E6600 CPU on x86-64 Linux:<br />
<syntaxhighlight lang="bash"><br />
$ ./vanitygen 1Boat<br />
Difficulty: 4476342<br />
Pattern: 1Boat <br />
Address: 1BoatSLRHtKNngkdXEeobR76b53LETtpyT<br />
Privkey: 5J4XJRyLVgzbXEgh8VNi4qovLzxRftzMd8a18KkdXv4EqAwX3tS<br />
</syntaxhighlight><br />
<br />
Vanitygen includes components to perform address searching on your CPU (vanitygen) and your OpenCL-compatible GPU (oclvanitygen). Both can be built from source, and both are included in the Windows binary package. Also included is oclvanityminer, the vanity address mining client. Oclvanityminer can be used to automatically claim bounties on sites such as [[User:ThePiachu|ThePiachu]]'s [[Vanity Pool]].<br />
<br />
Current version: 0.22<br />
<br />
Windows x86+x64 binaries [https://github.com/downloads/samr7/vanitygen/vanitygen-0.20-win.zip here]. PGP signature [http://insight.gotdns.org/~samr7/vanitygen-0.20-win.zip.asc here].<br />
<br />
Get the source from [https://github.com/samr7/vanitygen GitHub]. Includes Makefiles for Linux and Mac OS X.<br />
<br />
Main discussion at [https://bitcointalk.org/index.php?topic=25804.0 BitCoinTalk]<br />
<br />
For AMD Catalyst 13.1+ you need to run the AMD APP SDK Runtime from Catalyst 12.10 in order to get this program to work. (So all your Catalyst drivers would be brand new except for the SDK Runtime.) This is discussed on [https://github.com/samr7/vanitygen/issues/19 GitHub]. For Linux, use AMD APP SDK 2.7.<br />
<br />
Also the latest source doesn't work properly for high-end AMD cards (7XXX and greater). Solution is to change line 459 in oclengine.c from: return quirks; to: return quirks & ~VG_OCL_AMD_BFI_INT;<br />
Windows x86+x64 binaries that solve this problem plus provide support for compressed keys [https://lifeboat.com/oclvanitygen here]. PGP signature [https://lifeboat.com/oclvanitygen.zip.sig here]. If you have any problems with the binaries, join the relevant [https://bitcointalk.org/index.php?topic=301068.0 BitCoinTalk discussion].<br />
<br />
== Expected keysearch rate ==<br />
Main article: [[Vanitygen keysearch rate]]<br />
<br />
What key search rate can I expect from hardware X?<br />
<br />
Detailed list forthcoming. Some ballpark estimates are listed below.<br />
<br />
Dual-core desktop CPUs, 32-bit mode: 100-250 Kkey/s.<br />
Dual-core desktop CPUs, 64-bit mode: 150-450 Kkey/s.<br />
Quad-core desktop CPUs, 32-bit mode: 200-400 Kkey/s.<br />
Quad-core desktop CPUs, 64-bit mode: 300-750 Kkey/s.<br />
NVIDIA GT200 GPUs: up to 6.5 Mkey/s<br />
AMD Radeon 58XX, 68XX GPUs: up to 23.5 Mkey/s.<br />
AMD Radeon 69XX GPUs: up to 19.5 Mkey/s.<br />
<br />
As vanitygen performs a lot of large integer arithmetic, running it in 64-bit mode makes a huge difference in key search rate, easily a 50% improvement over 32-bit mode. If you are using a 64-bit edition of Windows, and not using a GPU, be sure to use vanitygen64.exe.<br />
<br />
Radeon 58XX outperforms Radeon 69XX by a very comfortable margin. Oclvanitygen is sensitive to integer multiply throughput, and Radeon 58XX can multiply concurrently with other operations. At similar clocks, a hobbled Radeon 5830 will outperform a Radeon 6970.<br />
<br />
In custom builds, CPU performance will be less than expected if the OpenSSL library is an older version (<1.0.0d) or is not built with the appropriate optimizations enabled.<br />
<br />
== Vanity addresses for other crypto-coins ==<br />
While all "normal" bitcoin addresses start with a "1" (one) (except multi-signature addresses that start with "3"), some other crypto-coins use different address name spaces. Vanitygen (as of version 0.22) can be used to produce vanity addresses for these crypto coins as well (but not for [http://bitmessage.org bitmessage] addresses), by using the "-X" option. The following list provides some example command line calls and also indicates the address range for the respective coin (in ascending order of the "-X" parameter):<br />
<br />
Generate '''Bitcoin''' (BTC), '''Devcoin''' (DVC), '''Freicoin''' (FRC), '''Terracoin''' (TRC) addresses:<br />
$ ./vanitygen -X 0 1 -k<br />
or simply just<br />
$ ./vanitygen 1 -k<br />
<br />
Generate '''Bitcoin''' (BTC) etc. '''multi-signature''' addresses:<br />
$ ./vanitygen -X 5 3 -k<br />
$ ./vanitygen -X 5 31 -k<br />
$ ./vanitygen -X 5 39 -k<br />
$ ./vanitygen -X 5 3A -k<br />
$ ./vanitygen -X 5 3R -k<br />
<br />
Generate '''Novacoin''' (NVC) addresses:<br />
$ ./vanitygen -X 8 4 -k<br />
$ ./vanitygen -X 8 4D -k<br />
$ ./vanitygen -X 8 4Z -k<br />
$ ./vanitygen -X 8 4a -k<br />
$ ./vanitygen -X 8 4d -k<br />
<br />
Generate '''Feathercoin''' (FTC) addresses:<br />
$ ./vanitygen -X 14 6 -k<br />
$ ./vanitygen -X 14 6d -k<br />
$ ./vanitygen -X 14 6z -k<br />
$ ./vanitygen -X 14 7 -k<br />
$ ./vanitygen -X 14 71 -k<br />
$ ./vanitygen -X 14 72 -k<br />
$ ./vanitygen -X 14 73 -k<br />
<br />
Generate '''Anoncoin''' (ANC) addresses:<br />
$ ./vanitygen -X 23 A -k<br />
$ ./vanitygen -X 23 AF -k<br />
$ ./vanitygen -X 23 AZ -k<br />
$ ./vanitygen -X 23 Aa -k<br />
$ ./vanitygen -X 23 Af -k<br />
<br />
Generate '''Digitalcoin''' (DGC) or '''Dogecoin''' (DOGE) addresses:<br />
$ ./vanitygen -X 30 D -k<br />
$ ./vanitygen -X 30 D5 -k<br />
$ ./vanitygen -X 30 D9 -k<br />
$ ./vanitygen -X 30 DA -k<br />
$ ./vanitygen -X 30 DU -k<br />
<br />
Generate '''Franko''' (FRK) addresses:<br />
$ ./vanitygen -X 35 F -k<br />
$ ./vanitygen -X 35 FD -k<br />
$ ./vanitygen -X 35 FE -k<br />
$ ./vanitygen -X 35 FN -k<br />
$ ./vanitygen -X 35 FR -k<br />
<br />
Generate '''Litecoin''' (LTC) addresses:<br />
$ ./vanitygen -X 48 L -k<br />
$ ./vanitygen -X 48 LK -k<br />
$ ./vanitygen -X 48 LZ -k<br />
$ ./vanitygen -X 48 La -k<br />
$ ./vanitygen -X 48 Li -k<br />
<br />
Generate '''Namecoin''' (NMC) addresses:<br />
$ ./vanitygen -X 52 M -k<br />
$ ./vanitygen -X 52 Mv -k<br />
$ ./vanitygen -X 52 Mz -k<br />
$ ./vanitygen -X 52 N -k<br />
$ ./vanitygen -X 52 N1 -k<br />
$ ./vanitygen -X 52 N9 -k<br />
$ ./vanitygen -X 52 NA -k<br />
$ ./vanitygen -X 52 NK -k<br />
<br />
Generate '''PPCoin''' (PPC) addresses:<br />
$ ./vanitygen -X 55 P -k<br />
$ ./vanitygen -X 55 P8 -k<br />
$ ./vanitygen -X 55 P9 -k<br />
$ ./vanitygen -X 55 PA -k<br />
$ ./vanitygen -X 55 PX -k<br />
<br />
Generate '''Vertcoin''' (VTC) addresses:<br />
$ ./vanitygen -X 71 V -k<br />
$ ./vanitygen -X 71 VZ -k<br />
$ ./vanitygen -X 71 Va -k<br />
$ ./vanitygen -X 71 Vy -k<br />
<br />
Generate '''YaCoin''' (YAC) addresses:<br />
$ ./vanitygen -X 77 X -k<br />
$ ./vanitygen -X 77 Xz -k<br />
$ ./vanitygen -X 77 Y -k<br />
$ ./vanitygen -X 77 Y1 -k<br />
$ ./vanitygen -X 77 Y9 -k<br />
$ ./vanitygen -X 77 YA -k<br />
$ ./vanitygen -X 77 YP -k<br />
<br />
Generate '''BBQcoin''' (BQC) addresses:<br />
$ ./vanitygen -X 85 b -k<br />
$ ./vanitygen -X 85 bC -k<br />
$ ./vanitygen -X 85 bZ -k<br />
$ ./vanitygen -X 85 ba -k<br />
$ ./vanitygen -X 85 bc -k<br />
<br />
Generate '''Ixcoin''' (IXC) addresses:<br />
$ ./vanitygen -X 138 x -k<br />
$ ./vanitygen -X 138 xX -k<br />
$ ./vanitygen -X 138 xZ -k<br />
$ ./vanitygen -X 138 xa -k<br />
$ ./vanitygen -X 138 xv -k<br />
<br />
Generally, to find out the address format of a given crypto-coin (i.e. the number after the -X option of vanitygen) one can use this service:<br />
<nowiki>http://darkgamex.ch:2751/q/decode_address/<Address></nowiki><br />
Example: Take any Litecoin address, e.g. "LNipKabgGoTPnzhxsyFwTZdjVSXybjWucp", and submit this URL:<br />
http://darkgamex.ch:2751/q/decode_address/LNipKabgGoTPnzhxsyFwTZdjVSXybjWucp<br />
The browser output will be:<br />
30:265dcf8616a9723d3b4ba35c246b041e20013597<br />
The '''30''' is Litecoin's address format in hex (!), i.e. '''30''' (hex) = 48 (decimal) [because '''3'''*16 + '''0'''*1 = 48], i.e. use '''-X 48''' in vanitygen to generate Litecoin addresses.<br />
<br />
Some related info here: https://en.bitcoin.it/wiki/List_of_address_prefixes<br />
<br />
== See also ==<br />
* [[Firstbits]]<br />
* [[Bitcoin Vanity Generation Website]]<br />
<br />
[[Category:Vanity address]]</div>Michael Shttps://en.bitcoin.it/w/index.php?title=Vanitygen&diff=44881Vanitygen2014-03-10T22:19:18Z<p>Michael S: /* Vanity addresses for other crypto-coins */ clarified that list is in ascending order of "-X" parameter</p>
<hr />
<div>'''Vanitygen''' is a command-line vanity bitcoin address generator.<br />
<br />
If you're tired of the random, cryptic addresses generated by regular bitcoin clients, you can use vanitygen to create a more personalized address. Add unique flair when you tell people to send bitcoins to 1stDownqyMHHqnDPRSfiZ5GXJ8Gk9dbjL or dogecoins to DMooNvsY5dJth17qop3RUUnZG3ta3MW2Ua. Alternatively, vanitygen can be used to generate random addresses offline.<br />
<br />
Vanitygen accepts as input a pattern, or list of patterns to search for, and produces a list of addresses and private keys. Vanitygen's search is probabilistic, and the amount of time required to find a given pattern depends on how complex the pattern is, the speed of your computer, and whether you get lucky.<br />
<br />
The example below illustrates a session of vanitygen. It is typical, and took about 10 sec to finish, using my Core 2 Duo E6600 CPU on x86-64 Linux:<br />
<syntaxhighlight lang="bash"><br />
$ ./vanitygen 1Boat<br />
Difficulty: 4476342<br />
Pattern: 1Boat <br />
Address: 1BoatSLRHtKNngkdXEeobR76b53LETtpyT<br />
Privkey: 5J4XJRyLVgzbXEgh8VNi4qovLzxRftzMd8a18KkdXv4EqAwX3tS<br />
</syntaxhighlight><br />
<br />
Vanitygen includes components to perform address searching on your CPU (vanitygen) and your OpenCL-compatible GPU (oclvanitygen). Both can be built from source, and both are included in the Windows binary package. Also included is oclvanityminer, the vanity address mining client. Oclvanityminer can be used to automatically claim bounties on sites such as [[User:ThePiachu|ThePiachu]]'s [[Vanity Pool]].<br />
<br />
Current version: 0.22<br />
<br />
Windows x86+x64 binaries [https://github.com/downloads/samr7/vanitygen/vanitygen-0.20-win.zip here]. PGP signature [http://insight.gotdns.org/~samr7/vanitygen-0.20-win.zip.asc here].<br />
<br />
Get the source from [https://github.com/samr7/vanitygen GitHub]. Includes Makefiles for Linux and Mac OS X.<br />
<br />
Main discussion at [https://bitcointalk.org/index.php?topic=25804.0 BitCoinTalk]<br />
<br />
For AMD Catalyst 13.1+ you need to run the AMD APP SDK Runtime from Catalyst 12.10 in order to get this program to work. (So all your Catalyst drivers would be brand new except for the SDK Runtime.) This is discussed on [https://github.com/samr7/vanitygen/issues/19 GitHub]. For Linux, use AMD APP SDK 2.7.<br />
<br />
Also the latest source doesn't work properly for high-end AMD cards (7XXX and greater). Solution is to change line 459 in oclengine.c from: return quirks; to: return quirks & ~VG_OCL_AMD_BFI_INT;<br />
Windows x86+x64 binaries that solve this problem plus provide support for compressed keys [https://lifeboat.com/oclvanitygen here]. PGP signature [https://lifeboat.com/oclvanitygen.zip.sig here]. If you have any problems with the binaries, join the relevant [https://bitcointalk.org/index.php?topic=301068.0 BitCoinTalk discussion].<br />
<br />
== Expected keysearch rate ==<br />
Main article: [[Vanitygen keysearch rate]]<br />
<br />
What key search rate can I expect from hardware X?<br />
<br />
Detailed list forthcoming. Some ballpark estimates are listed below.<br />
<br />
Dual-core desktop CPUs, 32-bit mode: 100-250 Kkey/s.<br />
Dual-core desktop CPUs, 64-bit mode: 150-450 Kkey/s.<br />
Quad-core desktop CPUs, 32-bit mode: 200-400 Kkey/s.<br />
Quad-core desktop CPUs, 64-bit mode: 300-750 Kkey/s.<br />
NVIDIA GT200 GPUs: up to 6.5 Mkey/s<br />
AMD Radeon 58XX, 68XX GPUs: up to 23.5 Mkey/s.<br />
AMD Radeon 69XX GPUs: up to 19.5 Mkey/s.<br />
<br />
As vanitygen performs a lot of large integer arithmetic, running it in 64-bit mode makes a huge difference in key search rate, easily a 50% improvement over 32-bit mode. If you are using a 64-bit edition of Windows, and not using a GPU, be sure to use vanitygen64.exe.<br />
<br />
Radeon 58XX outperforms Radeon 69XX by a very comfortable margin. Oclvanitygen is sensitive to integer multiply throughput, and Radeon 58XX can multiply concurrently with other operations. At similar clocks, a hobbled Radeon 5830 will outperform a Radeon 6970.<br />
<br />
In custom builds, CPU performance will be less than expected if the OpenSSL library is an older version (<1.0.0d) or is not built with the appropriate optimizations enabled.<br />
<br />
== Vanity addresses for other crypto-coins ==<br />
While all "normal" bitcoin addresses start with a "1" (one) (except multi-signature addresses that start with "3"), some other crypto-coins use different address name spaces. Vanitygen (as of version 0.22) can be used to produce vanity addresses for these crypto coins as well (but not for [http://bitmessage.org bitmessage] addresses), by using the "-X" option. The following list provides some example command line calls and also indicates the address range for the respective coin (in ascending order of the "-X" parameter):<br />
<br />
Generate '''Bitcoin''' (BTC), '''Devcoin''' (DVC), '''Freicoin''' (FRC), '''Terracoin''' (TRC) addresses:<br />
$ ./vanitygen -X 0 1 -k<br />
or simply just<br />
$ ./vanitygen 1 -k<br />
<br />
Generate '''Bitcoin''' (BTC) etc. '''multi-signature''' addresses:<br />
$ ./vanitygen -X 5 3 -k<br />
$ ./vanitygen -X 5 31 -k<br />
$ ./vanitygen -X 5 39 -k<br />
$ ./vanitygen -X 5 3A -k<br />
$ ./vanitygen -X 5 3R -k<br />
<br />
Generate '''Novacoin''' (NVC) addresses:<br />
$ ./vanitygen -X 8 4 -k<br />
$ ./vanitygen -X 8 4D -k<br />
$ ./vanitygen -X 8 4Z -k<br />
$ ./vanitygen -X 8 4a -k<br />
$ ./vanitygen -X 8 4d -k<br />
<br />
Generate '''Feathercoin''' (FTC) addresses:<br />
$ ./vanitygen -X 14 6 -k<br />
$ ./vanitygen -X 14 6d -k<br />
$ ./vanitygen -X 14 6z -k<br />
$ ./vanitygen -X 14 7 -k<br />
$ ./vanitygen -X 14 71 -k<br />
$ ./vanitygen -X 14 72 -k<br />
$ ./vanitygen -X 14 73 -k<br />
<br />
Generate '''Anoncoin''' (ANC) addresses:<br />
$ ./vanitygen -X 23 A -k<br />
$ ./vanitygen -X 23 AF -k<br />
$ ./vanitygen -X 23 AZ -k<br />
$ ./vanitygen -X 23 Aa -k<br />
$ ./vanitygen -X 23 Af -k<br />
<br />
Generate '''Digitalcoin''' (DGC) or '''Dogecoin''' (DOGE) addresses:<br />
$ ./vanitygen -X 30 D -k<br />
$ ./vanitygen -X 30 D5 -k<br />
$ ./vanitygen -X 30 D9 -k<br />
$ ./vanitygen -X 30 DA -k<br />
$ ./vanitygen -X 30 DU -k<br />
<br />
Generate '''Franko''' (FRK) addresses:<br />
$ ./vanitygen -X 35 F -k<br />
$ ./vanitygen -X 35 FD -k<br />
$ ./vanitygen -X 35 FE -k<br />
$ ./vanitygen -X 35 FN -k<br />
$ ./vanitygen -X 35 FR -k<br />
<br />
Generate '''Litecoin''' (LTC) addresses:<br />
$ ./vanitygen -X 48 L -k<br />
$ ./vanitygen -X 48 LK -k<br />
$ ./vanitygen -X 48 LZ -k<br />
$ ./vanitygen -X 48 La -k<br />
$ ./vanitygen -X 48 Li -k<br />
<br />
Generate '''Namecoin''' (NMC) addresses:<br />
$ ./vanitygen -X 52 M -k<br />
$ ./vanitygen -X 52 Mv -k<br />
$ ./vanitygen -X 52 Mz -k<br />
$ ./vanitygen -X 52 N -k<br />
$ ./vanitygen -X 52 N1 -k<br />
$ ./vanitygen -X 52 N9 -k<br />
$ ./vanitygen -X 52 NA -k<br />
$ ./vanitygen -X 52 NK -k<br />
<br />
Generate '''PPCoin''' (PPC) addresses:<br />
$ ./vanitygen -X 55 P -k<br />
$ ./vanitygen -X 55 P8 -k<br />
$ ./vanitygen -X 55 P9 -k<br />
$ ./vanitygen -X 55 PA -k<br />
$ ./vanitygen -X 55 PX -k<br />
<br />
Generate '''YaCoin''' (YAC) addresses:<br />
$ ./vanitygen -X 77 X -k<br />
$ ./vanitygen -X 77 Xz -k<br />
$ ./vanitygen -X 77 Y -k<br />
$ ./vanitygen -X 77 Y1 -k<br />
$ ./vanitygen -X 77 Y9 -k<br />
$ ./vanitygen -X 77 YA -k<br />
$ ./vanitygen -X 77 YP -k<br />
<br />
Generate '''BBQcoin''' (BQC) addresses:<br />
$ ./vanitygen -X 85 b -k<br />
$ ./vanitygen -X 85 bC -k<br />
$ ./vanitygen -X 85 bZ -k<br />
$ ./vanitygen -X 85 ba -k<br />
$ ./vanitygen -X 85 bc -k<br />
<br />
Generate '''Ixcoin''' (IXC) addresses:<br />
$ ./vanitygen -X 138 x -k<br />
$ ./vanitygen -X 138 xX -k<br />
$ ./vanitygen -X 138 xZ -k<br />
$ ./vanitygen -X 138 xa -k<br />
$ ./vanitygen -X 138 xv -k<br />
<br />
Generally, to find out the address format of a given crypto-coin (i.e. the number after the -X option of vanitygen) one can use this service:<br />
<nowiki>http://darkgamex.ch:2751/q/decode_address/<Address></nowiki><br />
Example: Take any Litecoin address, e.g. "LNipKabgGoTPnzhxsyFwTZdjVSXybjWucp", and submit this URL:<br />
http://darkgamex.ch:2751/q/decode_address/LNipKabgGoTPnzhxsyFwTZdjVSXybjWucp<br />
The browser output will be:<br />
30:265dcf8616a9723d3b4ba35c246b041e20013597<br />
The '''30''' is Litecoin's address format in hex (!), i.e. '''30''' (hex) = 48 (decimal) [because '''3'''*16 + '''0'''*1 = 48], i.e. use '''-X 48''' in vanitygen to generate Litecoin addresses.<br />
<br />
Some related info here: https://en.bitcoin.it/wiki/List_of_address_prefixes<br />
<br />
== See also ==<br />
* [[Firstbits]]<br />
* [[Bitcoin Vanity Generation Website]]<br />
<br />
[[Category:Vanity address]]</div>Michael Shttps://en.bitcoin.it/w/index.php?title=Vanitygen&diff=44880Vanitygen2014-03-10T22:18:13Z<p>Michael S: /* Vanity addresses for other crypto-coins */ Removed redundant Dogecoin Entry and used correct order for Franko and Dogecoin</p>
<hr />
<div>'''Vanitygen''' is a command-line vanity bitcoin address generator.<br />
<br />
If you're tired of the random, cryptic addresses generated by regular bitcoin clients, you can use vanitygen to create a more personalized address. Add unique flair when you tell people to send bitcoins to 1stDownqyMHHqnDPRSfiZ5GXJ8Gk9dbjL or dogecoins to DMooNvsY5dJth17qop3RUUnZG3ta3MW2Ua. Alternatively, vanitygen can be used to generate random addresses offline.<br />
<br />
Vanitygen accepts as input a pattern, or list of patterns to search for, and produces a list of addresses and private keys. Vanitygen's search is probabilistic, and the amount of time required to find a given pattern depends on how complex the pattern is, the speed of your computer, and whether you get lucky.<br />
<br />
The example below illustrates a session of vanitygen. It is typical, and took about 10 sec to finish, using my Core 2 Duo E6600 CPU on x86-64 Linux:<br />
<syntaxhighlight lang="bash"><br />
$ ./vanitygen 1Boat<br />
Difficulty: 4476342<br />
Pattern: 1Boat <br />
Address: 1BoatSLRHtKNngkdXEeobR76b53LETtpyT<br />
Privkey: 5J4XJRyLVgzbXEgh8VNi4qovLzxRftzMd8a18KkdXv4EqAwX3tS<br />
</syntaxhighlight><br />
<br />
Vanitygen includes components to perform address searching on your CPU (vanitygen) and your OpenCL-compatible GPU (oclvanitygen). Both can be built from source, and both are included in the Windows binary package. Also included is oclvanityminer, the vanity address mining client. Oclvanityminer can be used to automatically claim bounties on sites such as [[User:ThePiachu|ThePiachu]]'s [[Vanity Pool]].<br />
<br />
Current version: 0.22<br />
<br />
Windows x86+x64 binaries [https://github.com/downloads/samr7/vanitygen/vanitygen-0.20-win.zip here]. PGP signature [http://insight.gotdns.org/~samr7/vanitygen-0.20-win.zip.asc here].<br />
<br />
Get the source from [https://github.com/samr7/vanitygen GitHub]. Includes Makefiles for Linux and Mac OS X.<br />
<br />
Main discussion at [https://bitcointalk.org/index.php?topic=25804.0 BitCoinTalk]<br />
<br />
For AMD Catalyst 13.1+ you need to run the AMD APP SDK Runtime from Catalyst 12.10 in order to get this program to work. (So all your Catalyst drivers would be brand new except for the SDK Runtime.) This is discussed on [https://github.com/samr7/vanitygen/issues/19 GitHub]. For Linux, use AMD APP SDK 2.7.<br />
<br />
Also the latest source doesn't work properly for high-end AMD cards (7XXX and greater). Solution is to change line 459 in oclengine.c from: return quirks; to: return quirks & ~VG_OCL_AMD_BFI_INT;<br />
Windows x86+x64 binaries that solve this problem plus provide support for compressed keys [https://lifeboat.com/oclvanitygen here]. PGP signature [https://lifeboat.com/oclvanitygen.zip.sig here]. If you have any problems with the binaries, join the relevant [https://bitcointalk.org/index.php?topic=301068.0 BitCoinTalk discussion].<br />
<br />
== Expected keysearch rate ==<br />
Main article: [[Vanitygen keysearch rate]]<br />
<br />
What key search rate can I expect from hardware X?<br />
<br />
Detailed list forthcoming. Some ballpark estimates are listed below.<br />
<br />
Dual-core desktop CPUs, 32-bit mode: 100-250 Kkey/s.<br />
Dual-core desktop CPUs, 64-bit mode: 150-450 Kkey/s.<br />
Quad-core desktop CPUs, 32-bit mode: 200-400 Kkey/s.<br />
Quad-core desktop CPUs, 64-bit mode: 300-750 Kkey/s.<br />
NVIDIA GT200 GPUs: up to 6.5 Mkey/s<br />
AMD Radeon 58XX, 68XX GPUs: up to 23.5 Mkey/s.<br />
AMD Radeon 69XX GPUs: up to 19.5 Mkey/s.<br />
<br />
As vanitygen performs a lot of large integer arithmetic, running it in 64-bit mode makes a huge difference in key search rate, easily a 50% improvement over 32-bit mode. If you are using a 64-bit edition of Windows, and not using a GPU, be sure to use vanitygen64.exe.<br />
<br />
Radeon 58XX outperforms Radeon 69XX by a very comfortable margin. Oclvanitygen is sensitive to integer multiply throughput, and Radeon 58XX can multiply concurrently with other operations. At similar clocks, a hobbled Radeon 5830 will outperform a Radeon 6970.<br />
<br />
In custom builds, CPU performance will be less than expected if the OpenSSL library is an older version (<1.0.0d) or is not built with the appropriate optimizations enabled.<br />
<br />
== Vanity addresses for other crypto-coins ==<br />
While all "normal" bitcoin addresses start with a "1" (one) (except multi-signature addresses that start with "3"), some other crypto-coins use different address name spaces. Vanitygen (as of version 0.22) can be used to produce vanity addresses for these crypto coins as well (but not for [http://bitmessage.org bitmessage] addresses), by using the "-X" option. The following list provides some example command line calls and also indicates the address range for the respective coin:<br />
<br />
Generate '''Bitcoin''' (BTC), '''Devcoin''' (DVC), '''Freicoin''' (FRC), '''Terracoin''' (TRC) addresses:<br />
$ ./vanitygen -X 0 1 -k<br />
or simply just<br />
$ ./vanitygen 1 -k<br />
<br />
Generate '''Bitcoin''' (BTC) etc. '''multi-signature''' addresses:<br />
$ ./vanitygen -X 5 3 -k<br />
$ ./vanitygen -X 5 31 -k<br />
$ ./vanitygen -X 5 39 -k<br />
$ ./vanitygen -X 5 3A -k<br />
$ ./vanitygen -X 5 3R -k<br />
<br />
Generate '''Novacoin''' (NVC) addresses:<br />
$ ./vanitygen -X 8 4 -k<br />
$ ./vanitygen -X 8 4D -k<br />
$ ./vanitygen -X 8 4Z -k<br />
$ ./vanitygen -X 8 4a -k<br />
$ ./vanitygen -X 8 4d -k<br />
<br />
Generate '''Feathercoin''' (FTC) addresses:<br />
$ ./vanitygen -X 14 6 -k<br />
$ ./vanitygen -X 14 6d -k<br />
$ ./vanitygen -X 14 6z -k<br />
$ ./vanitygen -X 14 7 -k<br />
$ ./vanitygen -X 14 71 -k<br />
$ ./vanitygen -X 14 72 -k<br />
$ ./vanitygen -X 14 73 -k<br />
<br />
Generate '''Anoncoin''' (ANC) addresses:<br />
$ ./vanitygen -X 23 A -k<br />
$ ./vanitygen -X 23 AF -k<br />
$ ./vanitygen -X 23 AZ -k<br />
$ ./vanitygen -X 23 Aa -k<br />
$ ./vanitygen -X 23 Af -k<br />
<br />
Generate '''Digitalcoin''' (DGC) or '''Dogecoin''' (DOGE) addresses:<br />
$ ./vanitygen -X 30 D -k<br />
$ ./vanitygen -X 30 D5 -k<br />
$ ./vanitygen -X 30 D9 -k<br />
$ ./vanitygen -X 30 DA -k<br />
$ ./vanitygen -X 30 DU -k<br />
<br />
Generate '''Franko''' (FRK) addresses:<br />
$ ./vanitygen -X 35 F -k<br />
$ ./vanitygen -X 35 FD -k<br />
$ ./vanitygen -X 35 FE -k<br />
$ ./vanitygen -X 35 FN -k<br />
$ ./vanitygen -X 35 FR -k<br />
<br />
Generate '''Litecoin''' (LTC) addresses:<br />
$ ./vanitygen -X 48 L -k<br />
$ ./vanitygen -X 48 LK -k<br />
$ ./vanitygen -X 48 LZ -k<br />
$ ./vanitygen -X 48 La -k<br />
$ ./vanitygen -X 48 Li -k<br />
<br />
Generate '''Namecoin''' (NMC) addresses:<br />
$ ./vanitygen -X 52 M -k<br />
$ ./vanitygen -X 52 Mv -k<br />
$ ./vanitygen -X 52 Mz -k<br />
$ ./vanitygen -X 52 N -k<br />
$ ./vanitygen -X 52 N1 -k<br />
$ ./vanitygen -X 52 N9 -k<br />
$ ./vanitygen -X 52 NA -k<br />
$ ./vanitygen -X 52 NK -k<br />
<br />
Generate '''PPCoin''' (PPC) addresses:<br />
$ ./vanitygen -X 55 P -k<br />
$ ./vanitygen -X 55 P8 -k<br />
$ ./vanitygen -X 55 P9 -k<br />
$ ./vanitygen -X 55 PA -k<br />
$ ./vanitygen -X 55 PX -k<br />
<br />
Generate '''YaCoin''' (YAC) addresses:<br />
$ ./vanitygen -X 77 X -k<br />
$ ./vanitygen -X 77 Xz -k<br />
$ ./vanitygen -X 77 Y -k<br />
$ ./vanitygen -X 77 Y1 -k<br />
$ ./vanitygen -X 77 Y9 -k<br />
$ ./vanitygen -X 77 YA -k<br />
$ ./vanitygen -X 77 YP -k<br />
<br />
Generate '''BBQcoin''' (BQC) addresses:<br />
$ ./vanitygen -X 85 b -k<br />
$ ./vanitygen -X 85 bC -k<br />
$ ./vanitygen -X 85 bZ -k<br />
$ ./vanitygen -X 85 ba -k<br />
$ ./vanitygen -X 85 bc -k<br />
<br />
Generate '''Ixcoin''' (IXC) addresses:<br />
$ ./vanitygen -X 138 x -k<br />
$ ./vanitygen -X 138 xX -k<br />
$ ./vanitygen -X 138 xZ -k<br />
$ ./vanitygen -X 138 xa -k<br />
$ ./vanitygen -X 138 xv -k<br />
<br />
Generally, to find out the address format of a given crypto-coin (i.e. the number after the -X option of vanitygen) one can use this service:<br />
<nowiki>http://darkgamex.ch:2751/q/decode_address/<Address></nowiki><br />
Example: Take any Litecoin address, e.g. "LNipKabgGoTPnzhxsyFwTZdjVSXybjWucp", and submit this URL:<br />
http://darkgamex.ch:2751/q/decode_address/LNipKabgGoTPnzhxsyFwTZdjVSXybjWucp<br />
The browser output will be:<br />
30:265dcf8616a9723d3b4ba35c246b041e20013597<br />
The '''30''' is Litecoin's address format in hex (!), i.e. '''30''' (hex) = 48 (decimal) [because '''3'''*16 + '''0'''*1 = 48], i.e. use '''-X 48''' in vanitygen to generate Litecoin addresses.<br />
<br />
Some related info here: https://en.bitcoin.it/wiki/List_of_address_prefixes<br />
<br />
== See also ==<br />
* [[Firstbits]]<br />
* [[Bitcoin Vanity Generation Website]]<br />
<br />
[[Category:Vanity address]]</div>Michael Shttps://en.bitcoin.it/w/index.php?title=Vanitygen&diff=44879Vanitygen2014-03-10T22:16:08Z<p>Michael S: /* Vanity addresses for other crypto-coins */ Error Correction: Dogecoin Addresses do not start with a "One"</p>
<hr />
<div>'''Vanitygen''' is a command-line vanity bitcoin address generator.<br />
<br />
If you're tired of the random, cryptic addresses generated by regular bitcoin clients, you can use vanitygen to create a more personalized address. Add unique flair when you tell people to send bitcoins to 1stDownqyMHHqnDPRSfiZ5GXJ8Gk9dbjL or dogecoins to DMooNvsY5dJth17qop3RUUnZG3ta3MW2Ua. Alternatively, vanitygen can be used to generate random addresses offline.<br />
<br />
Vanitygen accepts as input a pattern, or list of patterns to search for, and produces a list of addresses and private keys. Vanitygen's search is probabilistic, and the amount of time required to find a given pattern depends on how complex the pattern is, the speed of your computer, and whether you get lucky.<br />
<br />
The example below illustrates a session of vanitygen. It is typical, and took about 10 sec to finish, using my Core 2 Duo E6600 CPU on x86-64 Linux:<br />
<syntaxhighlight lang="bash"><br />
$ ./vanitygen 1Boat<br />
Difficulty: 4476342<br />
Pattern: 1Boat <br />
Address: 1BoatSLRHtKNngkdXEeobR76b53LETtpyT<br />
Privkey: 5J4XJRyLVgzbXEgh8VNi4qovLzxRftzMd8a18KkdXv4EqAwX3tS<br />
</syntaxhighlight><br />
<br />
Vanitygen includes components to perform address searching on your CPU (vanitygen) and your OpenCL-compatible GPU (oclvanitygen). Both can be built from source, and both are included in the Windows binary package. Also included is oclvanityminer, the vanity address mining client. Oclvanityminer can be used to automatically claim bounties on sites such as [[User:ThePiachu|ThePiachu]]'s [[Vanity Pool]].<br />
<br />
Current version: 0.22<br />
<br />
Windows x86+x64 binaries [https://github.com/downloads/samr7/vanitygen/vanitygen-0.20-win.zip here]. PGP signature [http://insight.gotdns.org/~samr7/vanitygen-0.20-win.zip.asc here].<br />
<br />
Get the source from [https://github.com/samr7/vanitygen GitHub]. Includes Makefiles for Linux and Mac OS X.<br />
<br />
Main discussion at [https://bitcointalk.org/index.php?topic=25804.0 BitCoinTalk]<br />
<br />
For AMD Catalyst 13.1+ you need to run the AMD APP SDK Runtime from Catalyst 12.10 in order to get this program to work. (So all your Catalyst drivers would be brand new except for the SDK Runtime.) This is discussed on [https://github.com/samr7/vanitygen/issues/19 GitHub]. For Linux, use AMD APP SDK 2.7.<br />
<br />
Also the latest source doesn't work properly for high-end AMD cards (7XXX and greater). Solution is to change line 459 in oclengine.c from: return quirks; to: return quirks & ~VG_OCL_AMD_BFI_INT;<br />
Windows x86+x64 binaries that solve this problem plus provide support for compressed keys [https://lifeboat.com/oclvanitygen here]. PGP signature [https://lifeboat.com/oclvanitygen.zip.sig here]. If you have any problems with the binaries, join the relevant [https://bitcointalk.org/index.php?topic=301068.0 BitCoinTalk discussion].<br />
<br />
== Expected keysearch rate ==<br />
Main article: [[Vanitygen keysearch rate]]<br />
<br />
What key search rate can I expect from hardware X?<br />
<br />
Detailed list forthcoming. Some ballpark estimates are listed below.<br />
<br />
Dual-core desktop CPUs, 32-bit mode: 100-250 Kkey/s.<br />
Dual-core desktop CPUs, 64-bit mode: 150-450 Kkey/s.<br />
Quad-core desktop CPUs, 32-bit mode: 200-400 Kkey/s.<br />
Quad-core desktop CPUs, 64-bit mode: 300-750 Kkey/s.<br />
NVIDIA GT200 GPUs: up to 6.5 Mkey/s<br />
AMD Radeon 58XX, 68XX GPUs: up to 23.5 Mkey/s.<br />
AMD Radeon 69XX GPUs: up to 19.5 Mkey/s.<br />
<br />
As vanitygen performs a lot of large integer arithmetic, running it in 64-bit mode makes a huge difference in key search rate, easily a 50% improvement over 32-bit mode. If you are using a 64-bit edition of Windows, and not using a GPU, be sure to use vanitygen64.exe.<br />
<br />
Radeon 58XX outperforms Radeon 69XX by a very comfortable margin. Oclvanitygen is sensitive to integer multiply throughput, and Radeon 58XX can multiply concurrently with other operations. At similar clocks, a hobbled Radeon 5830 will outperform a Radeon 6970.<br />
<br />
In custom builds, CPU performance will be less than expected if the OpenSSL library is an older version (<1.0.0d) or is not built with the appropriate optimizations enabled.<br />
<br />
== Vanity addresses for other crypto-coins ==<br />
While all "normal" bitcoin addresses start with a "1" (one) (except multi-signature addresses that start with "3"), some other crypto-coins use different address name spaces. Vanitygen (as of version 0.22) can be used to produce vanity addresses for these crypto coins as well (but not for [http://bitmessage.org bitmessage] addresses), by using the "-X" option. The following list provides some example command line calls and also indicates the address range for the respective coin:<br />
<br />
Generate '''Bitcoin''' (BTC), '''Devcoin''' (DVC), '''Freicoin''' (FRC), '''Terracoin''' (TRC) addresses:<br />
$ ./vanitygen -X 0 1 -k<br />
or simply just<br />
$ ./vanitygen 1 -k<br />
<br />
Generate '''Bitcoin''' (BTC) etc. '''multi-signature''' addresses:<br />
$ ./vanitygen -X 5 3 -k<br />
$ ./vanitygen -X 5 31 -k<br />
$ ./vanitygen -X 5 39 -k<br />
$ ./vanitygen -X 5 3A -k<br />
$ ./vanitygen -X 5 3R -k<br />
<br />
Generate '''Dogecoin''' (DOGE) addresses:<br />
$ ./vanitygen -X 30 D -k<br />
$ ./vanitygen -X 30 DMooN -k<br />
$ ./vanitygen -X 30 DMUcH -k<br />
$ ./vanitygen -X 30 DMANy -k<br />
$ ./vanitygen -X 30 DSHibE -k<br />
(Unfortunately, "Dwow" is not possible).<br />
<br />
Generate '''Novacoin''' (NVC) addresses:<br />
$ ./vanitygen -X 8 4 -k<br />
$ ./vanitygen -X 8 4D -k<br />
$ ./vanitygen -X 8 4Z -k<br />
$ ./vanitygen -X 8 4a -k<br />
$ ./vanitygen -X 8 4d -k<br />
<br />
Generate '''Feathercoin''' (FTC) addresses:<br />
$ ./vanitygen -X 14 6 -k<br />
$ ./vanitygen -X 14 6d -k<br />
$ ./vanitygen -X 14 6z -k<br />
$ ./vanitygen -X 14 7 -k<br />
$ ./vanitygen -X 14 71 -k<br />
$ ./vanitygen -X 14 72 -k<br />
$ ./vanitygen -X 14 73 -k<br />
<br />
Generate '''Anoncoin''' (ANC) addresses:<br />
$ ./vanitygen -X 23 A -k<br />
$ ./vanitygen -X 23 AF -k<br />
$ ./vanitygen -X 23 AZ -k<br />
$ ./vanitygen -X 23 Aa -k<br />
$ ./vanitygen -X 23 Af -k<br />
<br />
Generate '''Franko''' (FRK) addresses:<br />
$ ./vanitygen -X 35 F -k<br />
$ ./vanitygen -X 35 FD -k<br />
$ ./vanitygen -X 35 FE -k<br />
$ ./vanitygen -X 35 FN -k<br />
$ ./vanitygen -X 35 FR -k<br />
<br />
Generate '''Digitalcoin''' (DGC) addresses:<br />
$ ./vanitygen -X 30 D -k<br />
$ ./vanitygen -X 30 D5 -k<br />
$ ./vanitygen -X 30 D9 -k<br />
$ ./vanitygen -X 30 DA -k<br />
$ ./vanitygen -X 30 DU -k<br />
<br />
Generate '''Litecoin''' (LTC) addresses:<br />
$ ./vanitygen -X 48 L -k<br />
$ ./vanitygen -X 48 LK -k<br />
$ ./vanitygen -X 48 LZ -k<br />
$ ./vanitygen -X 48 La -k<br />
$ ./vanitygen -X 48 Li -k<br />
<br />
Generate '''Namecoin''' (NMC) addresses:<br />
$ ./vanitygen -X 52 M -k<br />
$ ./vanitygen -X 52 Mv -k<br />
$ ./vanitygen -X 52 Mz -k<br />
$ ./vanitygen -X 52 N -k<br />
$ ./vanitygen -X 52 N1 -k<br />
$ ./vanitygen -X 52 N9 -k<br />
$ ./vanitygen -X 52 NA -k<br />
$ ./vanitygen -X 52 NK -k<br />
<br />
Generate '''PPCoin''' (PPC) addresses:<br />
$ ./vanitygen -X 55 P -k<br />
$ ./vanitygen -X 55 P8 -k<br />
$ ./vanitygen -X 55 P9 -k<br />
$ ./vanitygen -X 55 PA -k<br />
$ ./vanitygen -X 55 PX -k<br />
<br />
Generate '''YaCoin''' (YAC) addresses:<br />
$ ./vanitygen -X 77 X -k<br />
$ ./vanitygen -X 77 Xz -k<br />
$ ./vanitygen -X 77 Y -k<br />
$ ./vanitygen -X 77 Y1 -k<br />
$ ./vanitygen -X 77 Y9 -k<br />
$ ./vanitygen -X 77 YA -k<br />
$ ./vanitygen -X 77 YP -k<br />
<br />
Generate '''BBQcoin''' (BQC) addresses:<br />
$ ./vanitygen -X 85 b -k<br />
$ ./vanitygen -X 85 bC -k<br />
$ ./vanitygen -X 85 bZ -k<br />
$ ./vanitygen -X 85 ba -k<br />
$ ./vanitygen -X 85 bc -k<br />
<br />
Generate '''Ixcoin''' (IXC) addresses:<br />
$ ./vanitygen -X 138 x -k<br />
$ ./vanitygen -X 138 xX -k<br />
$ ./vanitygen -X 138 xZ -k<br />
$ ./vanitygen -X 138 xa -k<br />
$ ./vanitygen -X 138 xv -k<br />
<br />
Generally, to find out the address format of a given crypto-coin (i.e. the number after the -X option of vanitygen) one can use this service:<br />
<nowiki>http://darkgamex.ch:2751/q/decode_address/<Address></nowiki><br />
Example: Take any Litecoin address, e.g. "LNipKabgGoTPnzhxsyFwTZdjVSXybjWucp", and submit this URL:<br />
http://darkgamex.ch:2751/q/decode_address/LNipKabgGoTPnzhxsyFwTZdjVSXybjWucp<br />
The browser output will be:<br />
30:265dcf8616a9723d3b4ba35c246b041e20013597<br />
The '''30''' is Litecoin's address format in hex (!), i.e. '''30''' (hex) = 48 (decimal) [because '''3'''*16 + '''0'''*1 = 48], i.e. use '''-X 48''' in vanitygen to generate Litecoin addresses.<br />
<br />
Some related info here: https://en.bitcoin.it/wiki/List_of_address_prefixes<br />
<br />
== See also ==<br />
* [[Firstbits]]<br />
* [[Bitcoin Vanity Generation Website]]<br />
<br />
[[Category:Vanity address]]</div>Michael Shttps://en.bitcoin.it/w/index.php?title=Vanitygen&diff=43244Vanitygen2013-12-17T17:19:20Z<p>Michael S: /* Vanity addresses for other crypto-coins */ typo, and added a remark for dummies for hex->dec conversion</p>
<hr />
<div>Vanitygen is a command-line vanity bitcoin address generator.<br />
<br />
If you're tired of the random, cryptic addresses generated by regular bitcoin clients, you can use vanitygen to create a more personalized address. Add unique flair when you tell people to send bitcoins to 1stDownqyMHHqnDPRSfiZ5GXJ8Gk9dbjL. Alternatively, vanitygen can be used to generate random addresses offline.<br />
<br />
Vanitygen accepts as input a pattern, or list of patterns to search for, and produces a list of addresses and private keys. Vanitygen's search is probabilistic, and the amount of time required to find a given pattern depends on how complex the pattern is, the speed of your computer, and whether you get lucky.<br />
<br />
The example below illustrates a session of vanitygen. It is typical, and took about 10 sec to finish, using my Core 2 Duo E6600 CPU on x86-64 Linux:<br />
<syntaxhighlight lang="bash"><br />
$ ./vanitygen 1Boat<br />
Difficulty: 4476342<br />
Pattern: 1Boat <br />
Address: 1BoatSLRHtKNngkdXEeobR76b53LETtpyT<br />
Privkey: 5J4XJRyLVgzbXEgh8VNi4qovLzxRftzMd8a18KkdXv4EqAwX3tS<br />
</syntaxhighlight><br />
<br />
Vanitygen includes components to perform address searching on your CPU (vanitygen) and your OpenCL-compatible GPU (oclvanitygen). Both can be built from source, and both are included in the Windows binary package. Also included is oclvanityminer, the vanity address mining client. Oclvanityminer can be used to automatically claim bounties on sites such as [[User:ThePiachu|ThePiachu]]'s [[Vanity Pool]].<br />
<br />
Current version: 0.22<br />
<br />
Windows x86+x64 binaries [https://github.com/downloads/samr7/vanitygen/vanitygen-0.20-win.zip here]. PGP signature [http://insight.gotdns.org/~samr7/vanitygen-0.20-win.zip.asc here].<br />
<br />
Get the source from [https://github.com/samr7/vanitygen GitHub]. Includes Makefiles for Linux and Mac OS X.<br />
<br />
Main discussion at [https://bitcointalk.org/index.php?topic=25804.0 BitCoinTalk]<br />
<br />
For AMD Catalyst 13.1+ you need to run the AMD APP SDK Runtime from Catalyst 12.10 in order to get this program to work. (So all your Catalyst drivers would be brand new except for the SDK Runtime.) This is discussed on [https://github.com/samr7/vanitygen/issues/19 GitHub]. For Linux, use AMD APP SDK 2.7.<br />
<br />
Also the latest source doesn't work properly for high-end AMD cards (7XXX and greater). Solution is to change line 459 in oclengine.c from: return quirks; to: return quirks & ~VG_OCL_AMD_BFI_INT;<br />
Windows x86+x64 binaries that solve this problem plus provide support for compressed keys [https://lifeboat.com/oclvanitygen here]. PGP signature [https://lifeboat.com/oclvanitygen.zip.sig here]. If you have any problems with the binaries, join the relevant [https://bitcointalk.org/index.php?topic=301068.0 BitCoinTalk discussion].<br />
<br />
== Expected keysearch rate ==<br />
Main article: [[Vanitygen keysearch rate]]<br />
<br />
What key search rate can I expect from hardware X?<br />
<br />
Detailed list forthcoming. Some ballpark estimates are listed below.<br />
<br />
Dual-core desktop CPUs, 32-bit mode: 100-250 Kkey/s.<br />
Dual-core desktop CPUs, 64-bit mode: 150-450 Kkey/s.<br />
Quad-core desktop CPUs, 32-bit mode: 200-400 Kkey/s.<br />
Quad-core desktop CPUs, 64-bit mode: 300-750 Kkey/s.<br />
NVIDIA GT200 GPUs: up to 6.5 Mkey/s<br />
AMD Radeon 58XX, 68XX GPUs: up to 23.5 Mkey/s.<br />
AMD Radeon 69XX GPUs: up to 19.5 Mkey/s.<br />
<br />
As vanitygen performs a lot of large integer arithmetic, running it in 64-bit mode makes a huge difference in key search rate, easily a 50% improvement over 32-bit mode. If you are using a 64-bit edition of Windows, and not using a GPU, be sure to use vanitygen64.exe.<br />
<br />
Radeon 58XX outperforms Radeon 69XX by a very comfortable margin. Oclvanitygen is sensitive to integer multiply throughput, and Radeon 58XX can multiply concurrently with other operations. At similar clocks, a hobbled Radeon 5830 will outperform a Radeon 6970.<br />
<br />
In custom builds, CPU performance will be less than expected if the OpenSSL library is an older version (<1.0.0d) or is not built with the appropriate optimizations enabled.<br />
<br />
== Vanity addresses for other crypto-coins ==<br />
While all "normal" bitcoin addresses start with a "1" (one) (except multi-signature addresses that start with "3"), some other crypto-coins use different address name spaces. Vanitygen (as of version 0.22) can be used to produce vanity addresses for these crypto coins as well (but not for [http://bitmessage.org bitmessage] addresses), by using the "-X" option. The following list provides some example command line calls and also indicates the address range for the respective coin:<br />
<br />
Generate '''Bitcoin''' (BTC), '''Devcoin''' (DVC), '''Freicoin''' (FRC), '''Terracoin''' (TRC) addresses:<br />
$ ./vanitygen -X 0 1 -k<br />
or simply just<br />
$ ./vanitygen 1 -k<br />
<br />
Generate '''Bitcoin''' (BTC) etc. '''multi-signature''' addresses:<br />
$ ./vanitygen -X 5 3 -k<br />
$ ./vanitygen -X 5 31 -k<br />
$ ./vanitygen -X 5 39 -k<br />
$ ./vanitygen -X 5 3A -k<br />
$ ./vanitygen -X 5 3R -k<br />
<br />
Generate '''Novacoin''' (NVC) addresses:<br />
$ ./vanitygen -X 8 4 -k<br />
$ ./vanitygen -X 8 4D -k<br />
$ ./vanitygen -X 8 4Z -k<br />
$ ./vanitygen -X 8 4a -k<br />
$ ./vanitygen -X 8 4d -k<br />
<br />
Generate '''Feathercoin''' (FTC) addresses:<br />
$ ./vanitygen -X 14 6 -k<br />
$ ./vanitygen -X 14 6d -k<br />
$ ./vanitygen -X 14 6z -k<br />
$ ./vanitygen -X 14 7 -k<br />
$ ./vanitygen -X 14 71 -k<br />
$ ./vanitygen -X 14 72 -k<br />
$ ./vanitygen -X 14 73 -k<br />
<br />
Generate '''Anoncoin''' (ANC) addresses:<br />
$ ./vanitygen -X 23 A -k<br />
$ ./vanitygen -X 23 AF -k<br />
$ ./vanitygen -X 23 AZ -k<br />
$ ./vanitygen -X 23 Aa -k<br />
$ ./vanitygen -X 23 Af -k<br />
<br />
Generate '''Chinacoin''' (CNC) addresses:<br />
$ ./vanitygen -X 28 C -k<br />
$ ./vanitygen -X 28 CG -k<br />
$ ./vanitygen -X 28 CZ -k<br />
$ ./vanitygen -X 28 Ca -k<br />
$ ./vanitygen -X 28 Cf -k<br />
<br />
Generate '''Digitalcoin''' (DGC) addresses:<br />
$ ./vanitygen -X 30 D -k<br />
$ ./vanitygen -X 30 D5 -k<br />
$ ./vanitygen -X 30 D9 -k<br />
$ ./vanitygen -X 30 DA -k<br />
$ ./vanitygen -X 30 DU -k<br />
<br />
Generate '''Litecoin''' (LTC) addresses:<br />
$ ./vanitygen -X 48 L -k<br />
$ ./vanitygen -X 48 LK -k<br />
$ ./vanitygen -X 48 LZ -k<br />
$ ./vanitygen -X 48 La -k<br />
$ ./vanitygen -X 48 Li -k<br />
<br />
Generate '''Namecoin''' (NMC) addresses:<br />
$ ./vanitygen -X 52 M -k<br />
$ ./vanitygen -X 52 Mv -k<br />
$ ./vanitygen -X 52 Mz -k<br />
$ ./vanitygen -X 52 N -k<br />
$ ./vanitygen -X 52 N1 -k<br />
$ ./vanitygen -X 52 N9 -k<br />
$ ./vanitygen -X 52 NA -k<br />
$ ./vanitygen -X 52 NK -k<br />
<br />
Generate '''PPCoin''' (PPC) addresses:<br />
$ ./vanitygen -X 55 P -k<br />
$ ./vanitygen -X 55 P8 -k<br />
$ ./vanitygen -X 55 P9 -k<br />
$ ./vanitygen -X 55 PA -k<br />
$ ./vanitygen -X 55 PX -k<br />
<br />
Generate '''YaCoin''' (YAC) addresses:<br />
$ ./vanitygen -X 77 X -k<br />
$ ./vanitygen -X 77 Xz -k<br />
$ ./vanitygen -X 77 Y -k<br />
$ ./vanitygen -X 77 Y1 -k<br />
$ ./vanitygen -X 77 Y9 -k<br />
$ ./vanitygen -X 77 YA -k<br />
$ ./vanitygen -X 77 YP -k<br />
<br />
Generate '''BBQcoin''' (BQC) addresses:<br />
$ ./vanitygen -X 85 b -k<br />
$ ./vanitygen -X 85 bC -k<br />
$ ./vanitygen -X 85 bZ -k<br />
$ ./vanitygen -X 85 ba -k<br />
$ ./vanitygen -X 85 bc -k<br />
<br />
Generate '''Ixcoin''' (IXC) addresses:<br />
$ ./vanitygen -X 138 x -k<br />
$ ./vanitygen -X 138 xX -k<br />
$ ./vanitygen -X 138 xZ -k<br />
$ ./vanitygen -X 138 xa -k<br />
$ ./vanitygen -X 138 xv -k<br />
<br />
Generally, to find out the address format of a given crypto-coin (i.e. the number after the -X option of vanitygen) one can use this service:<br />
<nowiki>http://darkgamex.ch:2751/q/decode_address/<Address></nowiki><br />
Example: Take any Litecoin address, e.g. "LNipKabgGoTPnzhxsyFwTZdjVSXybjWucp", and submit this URL:<br />
http://darkgamex.ch:2751/q/decode_address/LNipKabgGoTPnzhxsyFwTZdjVSXybjWucp<br />
The browser output will be:<br />
30:265dcf8616a9723d3b4ba35c246b041e20013597<br />
The '''30''' is Litecoin's address format in hex (!), i.e. '''30''' (hex) = 48 (decimal) [because '''3'''*16 + '''0'''*1 = 48], i.e. use '''-X 48''' in vanitygen to generate Litecoin addresses.<br />
<br />
Some related info here: https://en.bitcoin.it/wiki/List_of_address_prefixes<br />
<br />
== See also ==<br />
* [[Firstbits]]<br />
* [[Bitcoin Vanity Generation Website]]<br />
<br />
[[Category:Vanity address]]</div>Michael Shttps://en.bitcoin.it/w/index.php?title=Talk:Invoice_address&diff=42942Talk:Invoice address2013-12-07T13:15:33Z<p>Michael S: Minimum Address length = 26 (not 27) characters?</p>
<hr />
<div>During the described process of generating a bitcoin address, can it further be explained which parts are the private key or how they are computed too?<br />
<br />
:Please see [[Technical background of Bitcoin addresses]] for that information --[[User:Atheros|Atheros]] 08:42, 9 December 2011 (GMT)<br />
<br />
<br />
<br />
<br />
This wiki says a bitcoin address can have a length between 27 and 34 characters. But acc. to "https://bitcointalk.org/index.php?topic=278814.msg2978906#msg2978906" bitcoin addresses with only 26 (!) characters are also possible as well. What is written there appears plausible to me, so maybe someone skilled can verify, and if confirmed, correct the text in this wiki. --[[User:Michael_S|Michael_S]], 14:13, 7 December 2013 (CET)</div>Michael Shttps://en.bitcoin.it/w/index.php?title=Vanitygen&diff=42753Vanitygen2013-11-29T02:29:42Z<p>Michael S: /* Vanity addresses for other crypto-coins */ typo</p>
<hr />
<div>Vanitygen is a command-line vanity bitcoin address generator.<br />
<br />
If you're tired of the random, cryptic addresses generated by regular bitcoin clients, you can use vanitygen to create a more personalized address. Add unique flair when you tell people to send bitcoins to 1stDownqyMHHqnDPRSfiZ5GXJ8Gk9dbjL. Alternatively, vanitygen can be used to generate random addresses offline.<br />
<br />
Vanitygen accepts as input a pattern, or list of patterns to search for, and produces a list of addresses and private keys. Vanitygen's search is probabilistic, and the amount of time required to find a given pattern depends on how complex the pattern is, the speed of your computer, and whether you get lucky.<br />
<br />
The example below illustrates a session of vanitygen. It is typical, and took about 10 sec to finish, using my Core 2 Duo E6600 CPU on x86-64 Linux:<br />
<syntaxhighlight lang="bash"><br />
$ ./vanitygen 1Boat<br />
Difficulty: 4476342<br />
Pattern: 1Boat <br />
Address: 1BoatSLRHtKNngkdXEeobR76b53LETtpyT<br />
Privkey: 5J4XJRyLVgzbXEgh8VNi4qovLzxRftzMd8a18KkdXv4EqAwX3tS<br />
</syntaxhighlight><br />
<br />
Vanitygen includes components to perform address searching on your CPU (vanitygen) and your OpenCL-compatible GPU (oclvanitygen). Both can be built from source, and both are included in the Windows binary package. Also included is oclvanityminer, the vanity address mining client. Oclvanityminer can be used to automatically claim bounties on sites such as [[User:ThePiachu|ThePiachu]]'s [[Vanity Pool]].<br />
<br />
Current version: 0.22<br />
<br />
Windows x86+x64 binaries [https://github.com/downloads/samr7/vanitygen/vanitygen-0.20-win.zip here]. PGP signature [http://insight.gotdns.org/~samr7/vanitygen-0.20-win.zip.asc here].<br />
<br />
Get the source from [https://github.com/samr7/vanitygen GitHub]. Includes Makefiles for Linux and Mac OS X.<br />
<br />
Main discussion at [https://bitcointalk.org/index.php?topic=25804.0 BitCoinTalk]<br />
<br />
For AMD Catalyst 13.1+ you need to run the AMD APP SDK Runtime from Catalyst 12.10 in order to get this program to work. (So all your Catalyst drivers would be brand new except for the SDK Runtime.) This is discussed on [https://github.com/samr7/vanitygen/issues/19 GitHub]. For Linux, use AMD APP SDK 2.7.<br />
<br />
Also the latest source doesn't work properly for high-end AMD cards (7XXX and greater). Solution is to change line 459 in oclengine.c from: return quirks; to: return quirks & ~VG_OCL_AMD_BFI_INT;<br />
Windows x86+x64 binaries that solve this problem plus provide support for compressed keys [https://lifeboat.com/oclvanitygen here]. PGP signature [https://lifeboat.com/oclvanitygen.zip.sig here]. If you have any problems with the binaries, join the relevant [https://bitcointalk.org/index.php?topic=301068.0 BitCoinTalk discussion].<br />
<br />
== Expected keysearch rate ==<br />
Main article: [[Vanitygen keysearch rate]]<br />
<br />
What key search rate can I expect from hardware X?<br />
<br />
Detailed list forthcoming. Some ballpark estimates are listed below.<br />
<br />
Dual-core desktop CPUs, 32-bit mode: 100-250 Kkey/s.<br />
Dual-core desktop CPUs, 64-bit mode: 150-450 Kkey/s.<br />
Quad-core desktop CPUs, 32-bit mode: 200-400 Kkey/s.<br />
Quad-core desktop CPUs, 64-bit mode: 300-750 Kkey/s.<br />
NVIDIA GT200 GPUs: up to 6.5 Mkey/s<br />
AMD Radeon 58XX, 68XX GPUs: up to 23.5 Mkey/s.<br />
AMD Radeon 69XX GPUs: up to 19.5 Mkey/s.<br />
<br />
As vanitygen performs a lot of large integer arithmetic, running it in 64-bit mode makes a huge difference in key search rate, easily a 50% improvement over 32-bit mode. If you are using a 64-bit edition of Windows, and not using a GPU, be sure to use vanitygen64.exe.<br />
<br />
Radeon 58XX outperforms Radeon 69XX by a very comfortable margin. Oclvanitygen is sensitive to integer multiply throughput, and Radeon 58XX can multiply concurrently with other operations. At similar clocks, a hobbled Radeon 5830 will outperform a Radeon 6970.<br />
<br />
In custom builds, CPU performance will be less than expected if the OpenSSL library is an older version (<1.0.0d) or is not built with the appropriate optimizations enabled.<br />
<br />
== Vanity addresses for other crypto-coins ==<br />
While all "normal" bitcoin addresses start with a "1" (one) (except multi-signature addresses that start with "3"), some other crypto-coins use different address name spaces. Vanitygen (as of version 0.22) can be used to produce vanity addresses for these crypto coins as well (but not for [http://bitmessage.org bitmessage] addresses), by using the "-X" option. The following list provides some example command line calls and also indicates the address range for the respective coin:<br />
<br />
Generate '''Bitcoin''' (BTC), '''Devcoin''' (DVC), '''Freicoin''' (FRC), '''Terracoin''' (TRC) addresses:<br />
$ ./vanitygen -X 0 1 -k<br />
or simply just<br />
$ ./vanitygen 1 -k<br />
<br />
Generate '''Bitcoin''' (BTC) etc. '''multi-signature''' addresses:<br />
$ ./vanitygen -X 5 3 -k<br />
$ ./vanitygen -X 5 31 -k<br />
$ ./vanitygen -X 5 39 -k<br />
$ ./vanitygen -X 5 3A -k<br />
$ ./vanitygen -X 5 3R -k<br />
<br />
Generate '''Novacoin''' (NVC) addresses:<br />
$ ./vanitygen -X 8 4 -k<br />
$ ./vanitygen -X 8 4D -k<br />
$ ./vanitygen -X 8 4Z -k<br />
$ ./vanitygen -X 8 4a -k<br />
$ ./vanitygen -X 8 4d -k<br />
<br />
Generate '''Feathercoin''' (FTC) addresses:<br />
$ ./vanitygen -X 14 6 -k<br />
$ ./vanitygen -X 14 6d -k<br />
$ ./vanitygen -X 14 6z -k<br />
$ ./vanitygen -X 14 7 -k<br />
$ ./vanitygen -X 14 71 -k<br />
$ ./vanitygen -X 14 72 -k<br />
$ ./vanitygen -X 14 73 -k<br />
<br />
Generate '''Anoncoin''' (ANC) addresses:<br />
$ ./vanitygen -X 23 A -k<br />
$ ./vanitygen -X 23 AF -k<br />
$ ./vanitygen -X 23 AZ -k<br />
$ ./vanitygen -X 23 Aa -k<br />
$ ./vanitygen -X 23 Af -k<br />
<br />
Generate '''Chinacoin''' (CNC) addresses:<br />
$ ./vanitygen -X 28 C -k<br />
$ ./vanitygen -X 28 CG -k<br />
$ ./vanitygen -X 28 CZ -k<br />
$ ./vanitygen -X 28 Ca -k<br />
$ ./vanitygen -X 28 Cf -k<br />
<br />
Generate '''Digitalcoin''' (DGC) addresses:<br />
$ ./vanitygen -X 30 D -k<br />
$ ./vanitygen -X 30 D5 -k<br />
$ ./vanitygen -X 30 D9 -k<br />
$ ./vanitygen -X 30 DA -k<br />
$ ./vanitygen -X 30 DU -k<br />
<br />
Generate '''Litecoin''' (LTC) addresses:<br />
$ ./vanitygen -X 48 L -k<br />
$ ./vanitygen -X 48 LK -k<br />
$ ./vanitygen -X 48 LZ -k<br />
$ ./vanitygen -X 48 La -k<br />
$ ./vanitygen -X 48 Li -k<br />
<br />
Generate '''Namecoin''' (NMC) addresses:<br />
$ ./vanitygen -X 52 M -k<br />
$ ./vanitygen -X 52 Mv -k<br />
$ ./vanitygen -X 52 Mz -k<br />
$ ./vanitygen -X 52 N -k<br />
$ ./vanitygen -X 52 N1 -k<br />
$ ./vanitygen -X 52 N9 -k<br />
$ ./vanitygen -X 52 NA -k<br />
$ ./vanitygen -X 52 NK -k<br />
<br />
Generate '''PPCoin''' (PPC) addresses:<br />
$ ./vanitygen -X 55 P -k<br />
$ ./vanitygen -X 55 P8 -k<br />
$ ./vanitygen -X 55 P9 -k<br />
$ ./vanitygen -X 55 PA -k<br />
$ ./vanitygen -X 55 PX -k<br />
<br />
Generate '''YaCoin''' (YAC) addresses:<br />
$ ./vanitygen -X 77 X -k<br />
$ ./vanitygen -X 77 Xz -k<br />
$ ./vanitygen -X 77 Y -k<br />
$ ./vanitygen -X 77 Y1 -k<br />
$ ./vanitygen -X 77 Y9 -k<br />
$ ./vanitygen -X 77 YA -k<br />
$ ./vanitygen -X 77 YP -k<br />
<br />
Generate '''BBQcoin''' (BQC) addresses:<br />
$ ./vanitygen -X 85 b -k<br />
$ ./vanitygen -X 85 bC -k<br />
$ ./vanitygen -X 85 bZ -k<br />
$ ./vanitygen -X 85 ba -k<br />
$ ./vanitygen -X 85 bc -k<br />
<br />
Generate '''Ixcoin''' (IXC) addresses:<br />
$ ./vanitygen -X 138 x -k<br />
$ ./vanitygen -X 138 xX -k<br />
$ ./vanitygen -X 138 xZ -k<br />
$ ./vanitygen -X 138 xa -k<br />
$ ./vanitygen -X 138 xv -k<br />
<br />
Generally, to find out the address format of a given crypto-coin (i.e. the number after the -X option of vanitygen) one can use this service:<br />
<nowiki>http://darkgamex.ch:2751/q/decode_address/<Address></nowiki><br />
Example: Take any Litecoin address, e.g. "LNipKabgGoTPnzhxsyFwTZdjVSXybjWucp", and submit this URL:<br />
http://darkgamex.ch:2751/q/decode_address/LNipKabgGoTPnzhxsyFwTZdjVSXybjWucp<br />
The browser output will be:<br />
30:265dcf8616a9723d3b4ba35c246b041e20013597<br />
The '''30''' is Litecoin's address format in hex (!), i.e. 30 (hex) = 48 (decimal), i.e. use '''-X 48''' in vanitygen to generate Liteoin addresses.<br />
<br />
Some related info here: https://en.bitcoin.it/wiki/List_of_address_prefixes<br />
<br />
== See also ==<br />
* [[Firstbits]]<br />
* [[Bitcoin Vanity Generation Website]]<br />
<br />
[[Category:Vanity address]]</div>Michael Shttps://en.bitcoin.it/w/index.php?title=Vanitygen&diff=42752Vanitygen2013-11-29T02:27:12Z<p>Michael S: /* Vanity addresses for other crypto-coins */ more on multi-signature addresses</p>
<hr />
<div>Vanitygen is a command-line vanity bitcoin address generator.<br />
<br />
If you're tired of the random, cryptic addresses generated by regular bitcoin clients, you can use vanitygen to create a more personalized address. Add unique flair when you tell people to send bitcoins to 1stDownqyMHHqnDPRSfiZ5GXJ8Gk9dbjL. Alternatively, vanitygen can be used to generate random addresses offline.<br />
<br />
Vanitygen accepts as input a pattern, or list of patterns to search for, and produces a list of addresses and private keys. Vanitygen's search is probabilistic, and the amount of time required to find a given pattern depends on how complex the pattern is, the speed of your computer, and whether you get lucky.<br />
<br />
The example below illustrates a session of vanitygen. It is typical, and took about 10 sec to finish, using my Core 2 Duo E6600 CPU on x86-64 Linux:<br />
<syntaxhighlight lang="bash"><br />
$ ./vanitygen 1Boat<br />
Difficulty: 4476342<br />
Pattern: 1Boat <br />
Address: 1BoatSLRHtKNngkdXEeobR76b53LETtpyT<br />
Privkey: 5J4XJRyLVgzbXEgh8VNi4qovLzxRftzMd8a18KkdXv4EqAwX3tS<br />
</syntaxhighlight><br />
<br />
Vanitygen includes components to perform address searching on your CPU (vanitygen) and your OpenCL-compatible GPU (oclvanitygen). Both can be built from source, and both are included in the Windows binary package. Also included is oclvanityminer, the vanity address mining client. Oclvanityminer can be used to automatically claim bounties on sites such as [[User:ThePiachu|ThePiachu]]'s [[Vanity Pool]].<br />
<br />
Current version: 0.22<br />
<br />
Windows x86+x64 binaries [https://github.com/downloads/samr7/vanitygen/vanitygen-0.20-win.zip here]. PGP signature [http://insight.gotdns.org/~samr7/vanitygen-0.20-win.zip.asc here].<br />
<br />
Get the source from [https://github.com/samr7/vanitygen GitHub]. Includes Makefiles for Linux and Mac OS X.<br />
<br />
Main discussion at [https://bitcointalk.org/index.php?topic=25804.0 BitCoinTalk]<br />
<br />
For AMD Catalyst 13.1+ you need to run the AMD APP SDK Runtime from Catalyst 12.10 in order to get this program to work. (So all your Catalyst drivers would be brand new except for the SDK Runtime.) This is discussed on [https://github.com/samr7/vanitygen/issues/19 GitHub]. For Linux, use AMD APP SDK 2.7.<br />
<br />
Also the latest source doesn't work properly for high-end AMD cards (7XXX and greater). Solution is to change line 459 in oclengine.c from: return quirks; to: return quirks & ~VG_OCL_AMD_BFI_INT;<br />
Windows x86+x64 binaries that solve this problem plus provide support for compressed keys [https://lifeboat.com/oclvanitygen here]. PGP signature [https://lifeboat.com/oclvanitygen.zip.sig here]. If you have any problems with the binaries, join the relevant [https://bitcointalk.org/index.php?topic=301068.0 BitCoinTalk discussion].<br />
<br />
== Expected keysearch rate ==<br />
Main article: [[Vanitygen keysearch rate]]<br />
<br />
What key search rate can I expect from hardware X?<br />
<br />
Detailed list forthcoming. Some ballpark estimates are listed below.<br />
<br />
Dual-core desktop CPUs, 32-bit mode: 100-250 Kkey/s.<br />
Dual-core desktop CPUs, 64-bit mode: 150-450 Kkey/s.<br />
Quad-core desktop CPUs, 32-bit mode: 200-400 Kkey/s.<br />
Quad-core desktop CPUs, 64-bit mode: 300-750 Kkey/s.<br />
NVIDIA GT200 GPUs: up to 6.5 Mkey/s<br />
AMD Radeon 58XX, 68XX GPUs: up to 23.5 Mkey/s.<br />
AMD Radeon 69XX GPUs: up to 19.5 Mkey/s.<br />
<br />
As vanitygen performs a lot of large integer arithmetic, running it in 64-bit mode makes a huge difference in key search rate, easily a 50% improvement over 32-bit mode. If you are using a 64-bit edition of Windows, and not using a GPU, be sure to use vanitygen64.exe.<br />
<br />
Radeon 58XX outperforms Radeon 69XX by a very comfortable margin. Oclvanitygen is sensitive to integer multiply throughput, and Radeon 58XX can multiply concurrently with other operations. At similar clocks, a hobbled Radeon 5830 will outperform a Radeon 6970.<br />
<br />
In custom builds, CPU performance will be less than expected if the OpenSSL library is an older version (<1.0.0d) or is not built with the appropriate optimizations enabled.<br />
<br />
== Vanity addresses for other crypto-coins ==<br />
While all "normal" bitcoin addresses start with a "1" (one) (except multi-signature addresses that start with "3"), some other crypto-coins use different address name spaces. Vanitygen (as of version 0.22) can be used to produce vanity addresses for these crypto coins as well (but not for [http://bitmessage.org bitmessage] addresses), by using the "-X" option. The following list provides some example command line calls and also indicates the address range for the respective coin:<br />
<br />
Generate '''Bitcoin''' (BTC), '''Devcoin''' (DVC), '''Freicoin''' (FRC), '''Terracoin''' (TRC) addresses:<br />
$ ./vanitygen -X 0 1 -k<br />
or simply just<br />
$ ./vanitygen 1 -k<br />
<br />
Generate '''Bitcoin''' (BTC) etc. '''mult-signature''' addresses:<br />
$ ./vanitygen -X 5 3 -k<br />
$ ./vanitygen -X 5 31 -k<br />
$ ./vanitygen -X 5 39 -k<br />
$ ./vanitygen -X 5 3A -k<br />
$ ./vanitygen -X 5 3R -k<br />
<br />
Generate '''Novacoin''' (NVC) addresses:<br />
$ ./vanitygen -X 8 4 -k<br />
$ ./vanitygen -X 8 4D -k<br />
$ ./vanitygen -X 8 4Z -k<br />
$ ./vanitygen -X 8 4a -k<br />
$ ./vanitygen -X 8 4d -k<br />
<br />
Generate '''Feathercoin''' (FTC) addresses:<br />
$ ./vanitygen -X 14 6 -k<br />
$ ./vanitygen -X 14 6d -k<br />
$ ./vanitygen -X 14 6z -k<br />
$ ./vanitygen -X 14 7 -k<br />
$ ./vanitygen -X 14 71 -k<br />
$ ./vanitygen -X 14 72 -k<br />
$ ./vanitygen -X 14 73 -k<br />
<br />
Generate '''Anoncoin''' (ANC) addresses:<br />
$ ./vanitygen -X 23 A -k<br />
$ ./vanitygen -X 23 AF -k<br />
$ ./vanitygen -X 23 AZ -k<br />
$ ./vanitygen -X 23 Aa -k<br />
$ ./vanitygen -X 23 Af -k<br />
<br />
Generate '''Chinacoin''' (CNC) addresses:<br />
$ ./vanitygen -X 28 C -k<br />
$ ./vanitygen -X 28 CG -k<br />
$ ./vanitygen -X 28 CZ -k<br />
$ ./vanitygen -X 28 Ca -k<br />
$ ./vanitygen -X 28 Cf -k<br />
<br />
Generate '''Digitalcoin''' (DGC) addresses:<br />
$ ./vanitygen -X 30 D -k<br />
$ ./vanitygen -X 30 D5 -k<br />
$ ./vanitygen -X 30 D9 -k<br />
$ ./vanitygen -X 30 DA -k<br />
$ ./vanitygen -X 30 DU -k<br />
<br />
Generate '''Litecoin''' (LTC) addresses:<br />
$ ./vanitygen -X 48 L -k<br />
$ ./vanitygen -X 48 LK -k<br />
$ ./vanitygen -X 48 LZ -k<br />
$ ./vanitygen -X 48 La -k<br />
$ ./vanitygen -X 48 Li -k<br />
<br />
Generate '''Namecoin''' (NMC) addresses:<br />
$ ./vanitygen -X 52 M -k<br />
$ ./vanitygen -X 52 Mv -k<br />
$ ./vanitygen -X 52 Mz -k<br />
$ ./vanitygen -X 52 N -k<br />
$ ./vanitygen -X 52 N1 -k<br />
$ ./vanitygen -X 52 N9 -k<br />
$ ./vanitygen -X 52 NA -k<br />
$ ./vanitygen -X 52 NK -k<br />
<br />
Generate '''PPCoin''' (PPC) addresses:<br />
$ ./vanitygen -X 55 P -k<br />
$ ./vanitygen -X 55 P8 -k<br />
$ ./vanitygen -X 55 P9 -k<br />
$ ./vanitygen -X 55 PA -k<br />
$ ./vanitygen -X 55 PX -k<br />
<br />
Generate '''YaCoin''' (YAC) addresses:<br />
$ ./vanitygen -X 77 X -k<br />
$ ./vanitygen -X 77 Xz -k<br />
$ ./vanitygen -X 77 Y -k<br />
$ ./vanitygen -X 77 Y1 -k<br />
$ ./vanitygen -X 77 Y9 -k<br />
$ ./vanitygen -X 77 YA -k<br />
$ ./vanitygen -X 77 YP -k<br />
<br />
Generate '''BBQcoin''' (BQC) addresses:<br />
$ ./vanitygen -X 85 b -k<br />
$ ./vanitygen -X 85 bC -k<br />
$ ./vanitygen -X 85 bZ -k<br />
$ ./vanitygen -X 85 ba -k<br />
$ ./vanitygen -X 85 bc -k<br />
<br />
Generate '''Ixcoin''' (IXC) addresses:<br />
$ ./vanitygen -X 138 x -k<br />
$ ./vanitygen -X 138 xX -k<br />
$ ./vanitygen -X 138 xZ -k<br />
$ ./vanitygen -X 138 xa -k<br />
$ ./vanitygen -X 138 xv -k<br />
<br />
Generally, to find out the address format of a given crypto-coin (i.e. the number after the -X option of vanitygen) one can use this service:<br />
<nowiki>http://darkgamex.ch:2751/q/decode_address/<Address></nowiki><br />
Example: Take any Litecoin address, e.g. "LNipKabgGoTPnzhxsyFwTZdjVSXybjWucp", and submit this URL:<br />
http://darkgamex.ch:2751/q/decode_address/LNipKabgGoTPnzhxsyFwTZdjVSXybjWucp<br />
The browser output will be:<br />
30:265dcf8616a9723d3b4ba35c246b041e20013597<br />
The '''30''' is Litecoin's address format in hex (!), i.e. 30 (hex) = 48 (decimal), i.e. use '''-X 48''' in vanitygen to generate Liteoin addresses.<br />
<br />
Some related info here: https://en.bitcoin.it/wiki/List_of_address_prefixes<br />
<br />
== See also ==<br />
* [[Firstbits]]<br />
* [[Bitcoin Vanity Generation Website]]<br />
<br />
[[Category:Vanity address]]</div>Michael Shttps://en.bitcoin.it/w/index.php?title=Vanitygen&diff=42751Vanitygen2013-11-29T02:21:31Z<p>Michael S: /* Vanity addresses for other crypto-coins */ added Bitcoin multi-signature addresses in the list</p>
<hr />
<div>Vanitygen is a command-line vanity bitcoin address generator.<br />
<br />
If you're tired of the random, cryptic addresses generated by regular bitcoin clients, you can use vanitygen to create a more personalized address. Add unique flair when you tell people to send bitcoins to 1stDownqyMHHqnDPRSfiZ5GXJ8Gk9dbjL. Alternatively, vanitygen can be used to generate random addresses offline.<br />
<br />
Vanitygen accepts as input a pattern, or list of patterns to search for, and produces a list of addresses and private keys. Vanitygen's search is probabilistic, and the amount of time required to find a given pattern depends on how complex the pattern is, the speed of your computer, and whether you get lucky.<br />
<br />
The example below illustrates a session of vanitygen. It is typical, and took about 10 sec to finish, using my Core 2 Duo E6600 CPU on x86-64 Linux:<br />
<syntaxhighlight lang="bash"><br />
$ ./vanitygen 1Boat<br />
Difficulty: 4476342<br />
Pattern: 1Boat <br />
Address: 1BoatSLRHtKNngkdXEeobR76b53LETtpyT<br />
Privkey: 5J4XJRyLVgzbXEgh8VNi4qovLzxRftzMd8a18KkdXv4EqAwX3tS<br />
</syntaxhighlight><br />
<br />
Vanitygen includes components to perform address searching on your CPU (vanitygen) and your OpenCL-compatible GPU (oclvanitygen). Both can be built from source, and both are included in the Windows binary package. Also included is oclvanityminer, the vanity address mining client. Oclvanityminer can be used to automatically claim bounties on sites such as [[User:ThePiachu|ThePiachu]]'s [[Vanity Pool]].<br />
<br />
Current version: 0.22<br />
<br />
Windows x86+x64 binaries [https://github.com/downloads/samr7/vanitygen/vanitygen-0.20-win.zip here]. PGP signature [http://insight.gotdns.org/~samr7/vanitygen-0.20-win.zip.asc here].<br />
<br />
Get the source from [https://github.com/samr7/vanitygen GitHub]. Includes Makefiles for Linux and Mac OS X.<br />
<br />
Main discussion at [https://bitcointalk.org/index.php?topic=25804.0 BitCoinTalk]<br />
<br />
For AMD Catalyst 13.1+ you need to run the AMD APP SDK Runtime from Catalyst 12.10 in order to get this program to work. (So all your Catalyst drivers would be brand new except for the SDK Runtime.) This is discussed on [https://github.com/samr7/vanitygen/issues/19 GitHub]. For Linux, use AMD APP SDK 2.7.<br />
<br />
Also the latest source doesn't work properly for high-end AMD cards (7XXX and greater). Solution is to change line 459 in oclengine.c from: return quirks; to: return quirks & ~VG_OCL_AMD_BFI_INT;<br />
Windows x86+x64 binaries that solve this problem plus provide support for compressed keys [https://lifeboat.com/oclvanitygen here]. PGP signature [https://lifeboat.com/oclvanitygen.zip.sig here]. If you have any problems with the binaries, join the relevant [https://bitcointalk.org/index.php?topic=301068.0 BitCoinTalk discussion].<br />
<br />
== Expected keysearch rate ==<br />
Main article: [[Vanitygen keysearch rate]]<br />
<br />
What key search rate can I expect from hardware X?<br />
<br />
Detailed list forthcoming. Some ballpark estimates are listed below.<br />
<br />
Dual-core desktop CPUs, 32-bit mode: 100-250 Kkey/s.<br />
Dual-core desktop CPUs, 64-bit mode: 150-450 Kkey/s.<br />
Quad-core desktop CPUs, 32-bit mode: 200-400 Kkey/s.<br />
Quad-core desktop CPUs, 64-bit mode: 300-750 Kkey/s.<br />
NVIDIA GT200 GPUs: up to 6.5 Mkey/s<br />
AMD Radeon 58XX, 68XX GPUs: up to 23.5 Mkey/s.<br />
AMD Radeon 69XX GPUs: up to 19.5 Mkey/s.<br />
<br />
As vanitygen performs a lot of large integer arithmetic, running it in 64-bit mode makes a huge difference in key search rate, easily a 50% improvement over 32-bit mode. If you are using a 64-bit edition of Windows, and not using a GPU, be sure to use vanitygen64.exe.<br />
<br />
Radeon 58XX outperforms Radeon 69XX by a very comfortable margin. Oclvanitygen is sensitive to integer multiply throughput, and Radeon 58XX can multiply concurrently with other operations. At similar clocks, a hobbled Radeon 5830 will outperform a Radeon 6970.<br />
<br />
In custom builds, CPU performance will be less than expected if the OpenSSL library is an older version (<1.0.0d) or is not built with the appropriate optimizations enabled.<br />
<br />
== Vanity addresses for other crypto-coins ==<br />
While all bitcoin addresses start with a "1" (one), some other crypto-coins use different address name spaces. Vanitygen (as of version 0.22) can be used to produce vanity addresses for these crypto coins as well (but not for [http://bitmessage.org bitmessage] addresses), by using the "-X" option. The following list provides some example command line calls and also indicates the address range for the respective coin:<br />
<br />
Generate '''Bitcoin''' (BTC), '''Devcoin''' (DVC), '''Freicoin''' (FRC), '''Terracoin''' (TRC) addresses:<br />
$ ./vanitygen -X 0 1 -k<br />
or simply just<br />
$ ./vanitygen 1 -k<br />
<br />
Generate '''Bitcoin''' (BTC) etc. '''mult-signature''' addresses:<br />
$ ./vanitygen -X 5 31 -k<br />
$ ./vanitygen -X 5 39 -k<br />
$ ./vanitygen -X 5 3A -k<br />
$ ./vanitygen -X 5 3R -k<br />
<br />
Generate '''Novacoin''' (NVC) addresses:<br />
$ ./vanitygen -X 8 4 -k<br />
$ ./vanitygen -X 8 4D -k<br />
$ ./vanitygen -X 8 4Z -k<br />
$ ./vanitygen -X 8 4a -k<br />
$ ./vanitygen -X 8 4d -k<br />
<br />
Generate '''Feathercoin''' (FTC) addresses:<br />
$ ./vanitygen -X 14 6 -k<br />
$ ./vanitygen -X 14 6d -k<br />
$ ./vanitygen -X 14 6z -k<br />
$ ./vanitygen -X 14 7 -k<br />
$ ./vanitygen -X 14 71 -k<br />
$ ./vanitygen -X 14 72 -k<br />
$ ./vanitygen -X 14 73 -k<br />
<br />
Generate '''Anoncoin''' (ANC) addresses:<br />
$ ./vanitygen -X 23 A -k<br />
$ ./vanitygen -X 23 AF -k<br />
$ ./vanitygen -X 23 AZ -k<br />
$ ./vanitygen -X 23 Aa -k<br />
$ ./vanitygen -X 23 Af -k<br />
<br />
Generate '''Chinacoin''' (CNC) addresses:<br />
$ ./vanitygen -X 28 C -k<br />
$ ./vanitygen -X 28 CG -k<br />
$ ./vanitygen -X 28 CZ -k<br />
$ ./vanitygen -X 28 Ca -k<br />
$ ./vanitygen -X 28 Cf -k<br />
<br />
Generate '''Digitalcoin''' (DGC) addresses:<br />
$ ./vanitygen -X 30 D -k<br />
$ ./vanitygen -X 30 D5 -k<br />
$ ./vanitygen -X 30 D9 -k<br />
$ ./vanitygen -X 30 DA -k<br />
$ ./vanitygen -X 30 DU -k<br />
<br />
Generate '''Litecoin''' (LTC) addresses:<br />
$ ./vanitygen -X 48 L -k<br />
$ ./vanitygen -X 48 LK -k<br />
$ ./vanitygen -X 48 LZ -k<br />
$ ./vanitygen -X 48 La -k<br />
$ ./vanitygen -X 48 Li -k<br />
<br />
Generate '''Namecoin''' (NMC) addresses:<br />
$ ./vanitygen -X 52 M -k<br />
$ ./vanitygen -X 52 Mv -k<br />
$ ./vanitygen -X 52 Mz -k<br />
$ ./vanitygen -X 52 N -k<br />
$ ./vanitygen -X 52 N1 -k<br />
$ ./vanitygen -X 52 N9 -k<br />
$ ./vanitygen -X 52 NA -k<br />
$ ./vanitygen -X 52 NK -k<br />
<br />
Generate '''PPCoin''' (PPC) addresses:<br />
$ ./vanitygen -X 55 P -k<br />
$ ./vanitygen -X 55 P8 -k<br />
$ ./vanitygen -X 55 P9 -k<br />
$ ./vanitygen -X 55 PA -k<br />
$ ./vanitygen -X 55 PX -k<br />
<br />
Generate '''YaCoin''' (YAC) addresses:<br />
$ ./vanitygen -X 77 X -k<br />
$ ./vanitygen -X 77 Xz -k<br />
$ ./vanitygen -X 77 Y -k<br />
$ ./vanitygen -X 77 Y1 -k<br />
$ ./vanitygen -X 77 Y9 -k<br />
$ ./vanitygen -X 77 YA -k<br />
$ ./vanitygen -X 77 YP -k<br />
<br />
Generate '''BBQcoin''' (BQC) addresses:<br />
$ ./vanitygen -X 85 b -k<br />
$ ./vanitygen -X 85 bC -k<br />
$ ./vanitygen -X 85 bZ -k<br />
$ ./vanitygen -X 85 ba -k<br />
$ ./vanitygen -X 85 bc -k<br />
<br />
Generate '''Ixcoin''' (IXC) addresses:<br />
$ ./vanitygen -X 138 x -k<br />
$ ./vanitygen -X 138 xX -k<br />
$ ./vanitygen -X 138 xZ -k<br />
$ ./vanitygen -X 138 xa -k<br />
$ ./vanitygen -X 138 xv -k<br />
<br />
Generally, to find out the address format of a given crypto-coin (i.e. the number after the -X option of vanitygen) one can use this service:<br />
<nowiki>http://darkgamex.ch:2751/q/decode_address/<Address></nowiki><br />
Example: Take any Litecoin address, e.g. "LNipKabgGoTPnzhxsyFwTZdjVSXybjWucp", and submit this URL:<br />
http://darkgamex.ch:2751/q/decode_address/LNipKabgGoTPnzhxsyFwTZdjVSXybjWucp<br />
The browser output will be:<br />
30:265dcf8616a9723d3b4ba35c246b041e20013597<br />
The '''30''' is Litecoin's address format in hex (!), i.e. 30 (hex) = 48 (decimal), i.e. use '''-X 48''' in vanitygen to generate Liteoin addresses.<br />
<br />
Some related info here: https://en.bitcoin.it/wiki/List_of_address_prefixes<br />
<br />
== See also ==<br />
* [[Firstbits]]<br />
* [[Bitcoin Vanity Generation Website]]<br />
<br />
[[Category:Vanity address]]</div>Michael Shttps://en.bitcoin.it/w/index.php?title=Talk:BIP_0021&diff=40992Talk:BIP 00212013-09-12T01:41:14Z<p>Michael S: /* Critical Improvement of BIP 0021 for "req-" param */</p>
<hr />
<div>Marian on IRC reports: "The BNF [here] is erroneous, regarding the params, it says [ "?" bitcoinparams ] while bitcoinparams is just *bitcoinparam, thus with that BNF there are no separators between the parameters". --[[User:Gmaxwell|Gmaxwell]] ([[User talk:Gmaxwell|talk]]) 23:04, 23 April 2013 (GMT)<br />
<br />
--> ([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 8 Sept 2013) So should it rather be written something like this (I am not a BNF expert, just following my logic):<br />
bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparam [ bitcoinparams ] ]<br />
bitcoinparams = *bitcoinparamamp<br />
bitcoinparamamp = "&" bitcoinparam<br />
<br />
<br />
== Suggesting usability enhancement in BIP 0021 for paying tips in restaurant/bar conveniently ("tips w/o taps") ==<br />
([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 8 Sept 2013)<br />
<br />
I am suggesting a simple downward compatible enhancement of BIP 0021 to allow effortless tipping in restaurants, bars, pubs, etc.<br />
<br />
When watching bitpay's mobile checkout demo video "http://www.youtube.com/watch?v=YZ-pqo0cLcE" it is clear that paying tips is somewhat cumbersome for the customer with today's wallet and merchant solutions. This can be dramatically improved with some support by the client app and a minor enhancement of BIP 0021.<br />
<br />
<span style="color:#0000FF">'''Enhancement proposal'''</span>:<br />
<br />
bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparams ]<br />
bitcoinaddress = base58 *base58<br />
bitcoinparams = *bitcoinparam<br />
bitcoinparam = amountparam | labelparam | messageparam | <span style="color:#0000FF">'''tipparam |'''</span> otherparam | reqparam<br />
amountparam = "amount=" *digit [ "." *digit ]<br />
labelparam = "label=" *pchar<br />
messageparam = "message=" *pchar<br />
<span style="color:#0000FF">'''tipparam = "tip=" [ *digit [ "." *digit ] [ "%" [ "25" ] ] ]'''</span><br />
otherparam = pchar *pchar "=" *pchar<br />
reqparam = "req-" pchar *pchar "=" *pchar<br />
<br />
Actually, "tipparam" is just a special case of "otherparam", hence completely downwards compatible.<br />
<br />
The tip can be specified in BTC or in percent of the amount, and it acts as a recommended or default tip setting in the customer's wallet app.<br />
<br />
'''Examples''' for the following scenario:<br />
:Request 0.567 BTC from the customer of a restaurant and make the customer's bitcoin app show an advanced send dialog that allows adding a tip:<br />
<br />
Ex. 1a) The pre-set tip value in the send dialog is undefined (user must specify) or set to the client's pre-configured default tip value:<br />
<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip='''</span><br />
<br />
Ex. 1b) The pre-set tip value in the send dialog is explicitly set to zero (this restaurant is on "service charge included in 'amount'" policy and informs the client about this explicitly by "tip=0" in the URI):<br />
<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=0'''</span><br />
<br />
Ex. 2) The pre-set tip value is 15% of 0.567 BTC, i.e. 0.08508 BTC:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=0.08505'''</span><br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25'''</span><br />
[URI code of the percentage character is "%25"]<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%'''</span><br />
["lazy" notation, omitting the "25". Actually, this is NOT correct, not URI compliant (RFC 2396), hence such an URI<br />
should not be generated. But it is proposed that the wallet app that has to decode the URI is implemented to understand<br />
this "lazy" syntax in the "tip" field anyhow, as safeguard to avoid errors in case that the merchant app generates such<br />
a "lazy" URI]<br />
<br />
Ex. 3) The pre-set tip value is 0.08508 BTC, and the "notes" field in the client app is pre-occupied with the name of the restaurant:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25'''</span>&message=Charly%27s%20Bar<br />
<br />
Explanation:<br />
* The new parameter has no "req-" prefix, i.e. if an old bitcoin client app does not know it, it can safely ignore it.<br />
* Otherwise, the customer's bitcoin client will not open the normal but an enhanced send dialog where the customer can specify a tip that will be added to the bill to be paid. In examples 2 and 3 above the tip shall be pre-configured with the amount specified in the URI, so the customer can most conveniently just accept it by a simple tap, if the client app is well-written.<br />
<br />
The details are of course dependent on the client app implementation, a best practice-example is demonstrated in the following images.<br />
<br />
Standard send dialog (no tips):<br />
<br />
[[File:bitcoin-app-tipOFF_BIP_0021.png|border]]<br />
<br />
<br />
Advanced send dialog for giving tips:<br />
<br />
[[File:bitcoin-app-tipON_BIP_0021.png|border]]<br />
<br />
Discussion: It has been argued that the described improvement of the user experience for the scenario "make payment with a tip" can be achieved by sole improvement of the wallet app, without any protocol change.<br />
<br />
But this is only partly true. Certainly enhancement of the wallet app to provide an advanced "send" dialog for easy tipping is crucial. However, with the legacy BIP 0021 the wallet app cannot know whether it shall display the standard send dialog (no tip) or the advanced send dialog (with tip option) to the user. So the user has to select this manually. With the optional "tip" parameter in the URI, the wallet app can readily display the appropriate send dialog without extra user interaction, thereby providing ultimate user experience.<br />
<br />
== Further enhancement for paying tips in restaurant/bar: "tip address" ==<br />
([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 9 Sept 2013)<br />
<br />
Further enhancement: Sending billing amount and tip to separate addresses:<br />
<br />
(Note: This feature is typically invisible in the GUI of the customer's wallet app)<br />
<br />
bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparams ]<br />
bitcoinaddress = base58 *base58<br />
bitcoinparams = *bitcoinparam<br />
bitcoinparam = amountparam | labelparam | messageparam | <span style="color:#0000FF">'''tipparam |'''</span> <span style="color:#E20074">'''tipaddrparam |'''</span> otherparam | reqparam<br />
amountparam = "amount=" *digit [ "." *digit ]<br />
labelparam = "label=" *pchar<br />
messageparam = "message=" *pchar<br />
<span style="color:#0000FF">'''tipparam = "tip=" [ *digit [ "." *digit ] [ "%" [ "25" ] ] ]'''</span><br />
<span style="color:#E20074">'''tipaddrparam = "tipaddr=" bitcoinaddress'''</span><br />
otherparam = pchar *pchar "=" *pchar<br />
reqparam = "req-" pchar *pchar "=" *pchar<br />
<br />
Example:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25</span><span style="color:#E20074">&tipaddr=1waiter7b38klseWrTZm5sE8PrrupPB2Q2'''</span><br />
<br />
The "tipaddr" parameter specifies that if the wallet app sends a tip in addition to the "amount", it shall '''''preferably''''' send it to the specifed "tip address". However, this is not mandatory (because it is an optional parameter w/o "req-"), so if the wallet app sends amount and tip to the main address, the merchant shall still be able to figure this out.<br />
<br />
If the merchant cannot handle tips sent to the same address as the billing amount, he shall instead make use of this parameter:<br />
<br />
<span style="color:#a20024">'''reqtipaddrparam = "req-tipaddr=" bitcoinaddress'''</span><br />
<br />
Example:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25&</span><span style="color:#a20024">&req-tipaddr=1waiter7b38klseWrTZm5sE8PrrupPB2Q2'''</span><br />
<br />
In this case, the wallet app is guaranteed to send the tip to the separate address, or will otherwise reject the complete URI. Upon rejection, the waiter knows that the customer has a non-compliant wallet app and can start a second try showing the URI without any tip parameters (or with "tip=0"). The tip can then be paid in a separate transaction (or classically by cash).<br />
<br />
== Short parameter tags yielding shorter URIs for QR codes ==<br />
([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 10 Sept 2013)<br />
<br />
Another proposal: Allow short forms for the parameter tags, to shorten the URIs.<br />
<br />
This is not important for URIs when used in links on web pages, but it can become relevant when generating QR codes. The longer the URI, the more difficult it will be to scan and decode the QR code by a smartphone due to smaller QR code block size or lower error protection level.<br />
<br />
Hence a simple table of equivalent ALIASES is proposed, to shorten the URI:<br />
<br />
'''Parameter Tag Alias'''<br />
amount= a=<br />
label= l=<br />
message= m=<br />
tip= t=<br />
tipaddr= ta=<br />
req- -<br />
req-tipaddr= -ta=<br />
req-aal= -aal=<br />
<br />
Hence, for example the following URIs are fully equivalent:<br />
<br />
155 characters:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567&tip=15%25&req-tipaddr=1waiter7b38klseWrTZm5sE8PrrupPB2Q2&message=Thank%20You&label=Charly%27s%20Bar</nowiki><br />
<br />
129 characters:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?a=.567&t=15%25&-ta=1waiter7b38klseWrTZm5sE8PrrupPB2Q2&m=Thank%20You&l=Charly%27s%20Bar</nowiki><br />
<br />
== Critical Improvement of BIP 0021 for "req-" param ==<br />
([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 12 Sept 2013)<br />
<br />
One aspect of current BIP 0021 is critical:<br />
<br />
It says that wallets that do not know one or several "req-" keys in the URI should reject (i.e. not process) the complete URI, to avoid doing anything in the wrong way.<br />
<br />
However, very old wallet apps may have not even implemented this rule and may still process the "known part" of the URI, thereby causing an unwanted result.<br />
<br />
The solution to the problem is to specify BIP 0021 in a way that, in case that at least one "req-" key is used, some other details of the URI must be modified too, such that it becomes "incompatible" and "undecodable" by older apps.<br />
<br />
The concrete proposal here is to append "R-" directly after "bitcoin:". Then a string with a "req-" parameter would look like this:<br />
<nowiki>bitcoin:</nowiki>'''R-'''<nowiki>175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567&tip=15%25&</nowiki>'''req-'''<nowiki>tipaddr=1waiter7b38klseWrTZm5sE8PrrupPB2Q2&message=Thank%20You&label=Charly%27s%20Bar</nowiki><br />
<br />
<br />
The BFN Syntax then looks as follows:<br />
bitcoinurn = "bitcoin:" '''[ "R-" ]''' bitcoinaddress [ "?" bitcoinparams ]<br />
where "R-" is mandatory as soon as at least one "reqparam" is used.<br />
<br />
== Paying to Multiple Outputs ==<br />
([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 12 Sept 2013)<br />
<br />
Another Enhancement relates to the "Humble Bundle" scenario: Paying one transaction with multiple outputs, specifying a dedicated amount for each output address.<br />
<br />
This scenario allows to specify additional pairs of addresses and amounts. Optionally, also further labels can be specified. We call the new parameter "'''req-aal'''" for '''a'''ddress-'''a'''mount-'''l'''abel, and we specify it as a '''req'''uired parameter because procesing an incomplete URI would result in sending only a partial amount.<br />
<br />
bitcoinparam = amountparam | labelparam | '''reqaalparam |''' messageparam | tipparam | tipaddrparam | otherparam | reqparam<br />
reqaalparam = "req-aal=" bitcoinaddress ":" *digit [ "." *digit ] [ ":" *pchar]<br />
<br />
Example:<br />
<nowiki>bitcoin:R-175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567&label=book&req-aal=1tZdShH7b38klseWrTZm5sE8PrtZPwqdK:0.123:game&message=Thank%20You</nowiki></div>Michael Shttps://en.bitcoin.it/w/index.php?title=Talk:BIP_0021&diff=40991Talk:BIP 00212013-09-12T01:38:27Z<p>Michael S: /* Short parameter tags yielding shorter URIs for QR codes */</p>
<hr />
<div>Marian on IRC reports: "The BNF [here] is erroneous, regarding the params, it says [ "?" bitcoinparams ] while bitcoinparams is just *bitcoinparam, thus with that BNF there are no separators between the parameters". --[[User:Gmaxwell|Gmaxwell]] ([[User talk:Gmaxwell|talk]]) 23:04, 23 April 2013 (GMT)<br />
<br />
--> ([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 8 Sept 2013) So should it rather be written something like this (I am not a BNF expert, just following my logic):<br />
bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparam [ bitcoinparams ] ]<br />
bitcoinparams = *bitcoinparamamp<br />
bitcoinparamamp = "&" bitcoinparam<br />
<br />
<br />
== Suggesting usability enhancement in BIP 0021 for paying tips in restaurant/bar conveniently ("tips w/o taps") ==<br />
([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 8 Sept 2013)<br />
<br />
I am suggesting a simple downward compatible enhancement of BIP 0021 to allow effortless tipping in restaurants, bars, pubs, etc.<br />
<br />
When watching bitpay's mobile checkout demo video "http://www.youtube.com/watch?v=YZ-pqo0cLcE" it is clear that paying tips is somewhat cumbersome for the customer with today's wallet and merchant solutions. This can be dramatically improved with some support by the client app and a minor enhancement of BIP 0021.<br />
<br />
<span style="color:#0000FF">'''Enhancement proposal'''</span>:<br />
<br />
bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparams ]<br />
bitcoinaddress = base58 *base58<br />
bitcoinparams = *bitcoinparam<br />
bitcoinparam = amountparam | labelparam | messageparam | <span style="color:#0000FF">'''tipparam |'''</span> otherparam | reqparam<br />
amountparam = "amount=" *digit [ "." *digit ]<br />
labelparam = "label=" *pchar<br />
messageparam = "message=" *pchar<br />
<span style="color:#0000FF">'''tipparam = "tip=" [ *digit [ "." *digit ] [ "%" [ "25" ] ] ]'''</span><br />
otherparam = pchar *pchar "=" *pchar<br />
reqparam = "req-" pchar *pchar "=" *pchar<br />
<br />
Actually, "tipparam" is just a special case of "otherparam", hence completely downwards compatible.<br />
<br />
The tip can be specified in BTC or in percent of the amount, and it acts as a recommended or default tip setting in the customer's wallet app.<br />
<br />
'''Examples''' for the following scenario:<br />
:Request 0.567 BTC from the customer of a restaurant and make the customer's bitcoin app show an advanced send dialog that allows adding a tip:<br />
<br />
Ex. 1a) The pre-set tip value in the send dialog is undefined (user must specify) or set to the client's pre-configured default tip value:<br />
<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip='''</span><br />
<br />
Ex. 1b) The pre-set tip value in the send dialog is explicitly set to zero (this restaurant is on "service charge included in 'amount'" policy and informs the client about this explicitly by "tip=0" in the URI):<br />
<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=0'''</span><br />
<br />
Ex. 2) The pre-set tip value is 15% of 0.567 BTC, i.e. 0.08508 BTC:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=0.08505'''</span><br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25'''</span><br />
[URI code of the percentage character is "%25"]<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%'''</span><br />
["lazy" notation, omitting the "25". Actually, this is NOT correct, not URI compliant (RFC 2396), hence such an URI<br />
should not be generated. But it is proposed that the wallet app that has to decode the URI is implemented to understand<br />
this "lazy" syntax in the "tip" field anyhow, as safeguard to avoid errors in case that the merchant app generates such<br />
a "lazy" URI]<br />
<br />
Ex. 3) The pre-set tip value is 0.08508 BTC, and the "notes" field in the client app is pre-occupied with the name of the restaurant:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25'''</span>&message=Charly%27s%20Bar<br />
<br />
Explanation:<br />
* The new parameter has no "req-" prefix, i.e. if an old bitcoin client app does not know it, it can safely ignore it.<br />
* Otherwise, the customer's bitcoin client will not open the normal but an enhanced send dialog where the customer can specify a tip that will be added to the bill to be paid. In examples 2 and 3 above the tip shall be pre-configured with the amount specified in the URI, so the customer can most conveniently just accept it by a simple tap, if the client app is well-written.<br />
<br />
The details are of course dependent on the client app implementation, a best practice-example is demonstrated in the following images.<br />
<br />
Standard send dialog (no tips):<br />
<br />
[[File:bitcoin-app-tipOFF_BIP_0021.png|border]]<br />
<br />
<br />
Advanced send dialog for giving tips:<br />
<br />
[[File:bitcoin-app-tipON_BIP_0021.png|border]]<br />
<br />
Discussion: It has been argued that the described improvement of the user experience for the scenario "make payment with a tip" can be achieved by sole improvement of the wallet app, without any protocol change.<br />
<br />
But this is only partly true. Certainly enhancement of the wallet app to provide an advanced "send" dialog for easy tipping is crucial. However, with the legacy BIP 0021 the wallet app cannot know whether it shall display the standard send dialog (no tip) or the advanced send dialog (with tip option) to the user. So the user has to select this manually. With the optional "tip" parameter in the URI, the wallet app can readily display the appropriate send dialog without extra user interaction, thereby providing ultimate user experience.<br />
<br />
== Further enhancement for paying tips in restaurant/bar: "tip address" ==<br />
([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 9 Sept 2013)<br />
<br />
Further enhancement: Sending billing amount and tip to separate addresses:<br />
<br />
(Note: This feature is typically invisible in the GUI of the customer's wallet app)<br />
<br />
bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparams ]<br />
bitcoinaddress = base58 *base58<br />
bitcoinparams = *bitcoinparam<br />
bitcoinparam = amountparam | labelparam | messageparam | <span style="color:#0000FF">'''tipparam |'''</span> <span style="color:#E20074">'''tipaddrparam |'''</span> otherparam | reqparam<br />
amountparam = "amount=" *digit [ "." *digit ]<br />
labelparam = "label=" *pchar<br />
messageparam = "message=" *pchar<br />
<span style="color:#0000FF">'''tipparam = "tip=" [ *digit [ "." *digit ] [ "%" [ "25" ] ] ]'''</span><br />
<span style="color:#E20074">'''tipaddrparam = "tipaddr=" bitcoinaddress'''</span><br />
otherparam = pchar *pchar "=" *pchar<br />
reqparam = "req-" pchar *pchar "=" *pchar<br />
<br />
Example:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25</span><span style="color:#E20074">&tipaddr=1waiter7b38klseWrTZm5sE8PrrupPB2Q2'''</span><br />
<br />
The "tipaddr" parameter specifies that if the wallet app sends a tip in addition to the "amount", it shall '''''preferably''''' send it to the specifed "tip address". However, this is not mandatory (because it is an optional parameter w/o "req-"), so if the wallet app sends amount and tip to the main address, the merchant shall still be able to figure this out.<br />
<br />
If the merchant cannot handle tips sent to the same address as the billing amount, he shall instead make use of this parameter:<br />
<br />
<span style="color:#a20024">'''reqtipaddrparam = "req-tipaddr=" bitcoinaddress'''</span><br />
<br />
Example:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25&</span><span style="color:#a20024">&req-tipaddr=1waiter7b38klseWrTZm5sE8PrrupPB2Q2'''</span><br />
<br />
In this case, the wallet app is guaranteed to send the tip to the separate address, or will otherwise reject the complete URI. Upon rejection, the waiter knows that the customer has a non-compliant wallet app and can start a second try showing the URI without any tip parameters (or with "tip=0"). The tip can then be paid in a separate transaction (or classically by cash).<br />
<br />
== Short parameter tags yielding shorter URIs for QR codes ==<br />
([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 10 Sept 2013)<br />
<br />
Another proposal: Allow short forms for the parameter tags, to shorten the URIs.<br />
<br />
This is not important for URIs when used in links on web pages, but it can become relevant when generating QR codes. The longer the URI, the more difficult it will be to scan and decode the QR code by a smartphone due to smaller QR code block size or lower error protection level.<br />
<br />
Hence a simple table of equivalent ALIASES is proposed, to shorten the URI:<br />
<br />
'''Parameter Tag Alias'''<br />
amount= a=<br />
label= l=<br />
message= m=<br />
tip= t=<br />
tipaddr= ta=<br />
req- -<br />
req-tipaddr= -ta=<br />
req-aal= -aal=<br />
<br />
Hence, for example the following URIs are fully equivalent:<br />
<br />
155 characters:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567&tip=15%25&req-tipaddr=1waiter7b38klseWrTZm5sE8PrrupPB2Q2&message=Thank%20You&label=Charly%27s%20Bar</nowiki><br />
<br />
129 characters:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?a=.567&t=15%25&-ta=1waiter7b38klseWrTZm5sE8PrrupPB2Q2&m=Thank%20You&l=Charly%27s%20Bar</nowiki><br />
<br />
== Critical Improvement of BIP 0021 for "req-" param ==<br />
([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 12 Sept 2013)<br />
<br />
One aspect of current BIP 0021 is critical:<br />
<br />
It says that wallets that do not know any of the "req-" keys in the URI should reject (i.e. not process) the complete URI, to avoid doing anything in the wrong way.<br />
<br />
However, even older wallet apps may have not even implemented this rule and may still process the "known part" of the URI, thereby causing an unwanted result.<br />
<br />
The solution to the problem is to specify BIP 0021 in a way that, in case that at least one "req-" key is used, some other details of the URI must be modified too, such that it becomes "incompatible" and "undecodable" by older apps.<br />
<br />
The concrete proposal here is to append "R-" directly after "bitcoin:". Then a string with a "req-" parameter would look like this:<br />
<nowiki>bitcoin:</nowiki>'''R-'''<nowiki>175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567&tip=15%25&</nowiki>'''req-'''<nowiki>tipaddr=1waiter7b38klseWrTZm5sE8PrrupPB2Q2&message=Thank%20You&label=Charly%27s%20Bar</nowiki><br />
<br />
<br />
The BFN Syntax then looks as follows:<br />
bitcoinurn = "bitcoin:" '''[ "R-" ]''' bitcoinaddress [ "?" bitcoinparams ]<br />
where "R-" is mandatory as soon as at least one "reqparam" is used.<br />
<br />
<br />
== Paying to Multiple Outputs ==<br />
([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 12 Sept 2013)<br />
<br />
Another Enhancement relates to the "Humble Bundle" scenario: Paying one transaction with multiple outputs, specifying a dedicated amount for each output address.<br />
<br />
This scenario allows to specify additional pairs of addresses and amounts. Optionally, also further labels can be specified. We call the new parameter "'''req-aal'''" for '''a'''ddress-'''a'''mount-'''l'''abel, and we specify it as a '''req'''uired parameter because procesing an incomplete URI would result in sending only a partial amount.<br />
<br />
bitcoinparam = amountparam | labelparam | '''reqaalparam |''' messageparam | tipparam | tipaddrparam | otherparam | reqparam<br />
reqaalparam = "req-aal=" bitcoinaddress ":" *digit [ "." *digit ] [ ":" *pchar]<br />
<br />
Example:<br />
<nowiki>bitcoin:R-175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567&label=book&req-aal=1tZdShH7b38klseWrTZm5sE8PrtZPwqdK:0.123:game&message=Thank%20You</nowiki></div>Michael Shttps://en.bitcoin.it/w/index.php?title=Talk:BIP_0021&diff=40990Talk:BIP 00212013-09-12T01:32:47Z<p>Michael S: Enhancement: Multiple output addresses</p>
<hr />
<div>Marian on IRC reports: "The BNF [here] is erroneous, regarding the params, it says [ "?" bitcoinparams ] while bitcoinparams is just *bitcoinparam, thus with that BNF there are no separators between the parameters". --[[User:Gmaxwell|Gmaxwell]] ([[User talk:Gmaxwell|talk]]) 23:04, 23 April 2013 (GMT)<br />
<br />
--> ([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 8 Sept 2013) So should it rather be written something like this (I am not a BNF expert, just following my logic):<br />
bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparam [ bitcoinparams ] ]<br />
bitcoinparams = *bitcoinparamamp<br />
bitcoinparamamp = "&" bitcoinparam<br />
<br />
<br />
== Suggesting usability enhancement in BIP 0021 for paying tips in restaurant/bar conveniently ("tips w/o taps") ==<br />
([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 8 Sept 2013)<br />
<br />
I am suggesting a simple downward compatible enhancement of BIP 0021 to allow effortless tipping in restaurants, bars, pubs, etc.<br />
<br />
When watching bitpay's mobile checkout demo video "http://www.youtube.com/watch?v=YZ-pqo0cLcE" it is clear that paying tips is somewhat cumbersome for the customer with today's wallet and merchant solutions. This can be dramatically improved with some support by the client app and a minor enhancement of BIP 0021.<br />
<br />
<span style="color:#0000FF">'''Enhancement proposal'''</span>:<br />
<br />
bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparams ]<br />
bitcoinaddress = base58 *base58<br />
bitcoinparams = *bitcoinparam<br />
bitcoinparam = amountparam | labelparam | messageparam | <span style="color:#0000FF">'''tipparam |'''</span> otherparam | reqparam<br />
amountparam = "amount=" *digit [ "." *digit ]<br />
labelparam = "label=" *pchar<br />
messageparam = "message=" *pchar<br />
<span style="color:#0000FF">'''tipparam = "tip=" [ *digit [ "." *digit ] [ "%" [ "25" ] ] ]'''</span><br />
otherparam = pchar *pchar "=" *pchar<br />
reqparam = "req-" pchar *pchar "=" *pchar<br />
<br />
Actually, "tipparam" is just a special case of "otherparam", hence completely downwards compatible.<br />
<br />
The tip can be specified in BTC or in percent of the amount, and it acts as a recommended or default tip setting in the customer's wallet app.<br />
<br />
'''Examples''' for the following scenario:<br />
:Request 0.567 BTC from the customer of a restaurant and make the customer's bitcoin app show an advanced send dialog that allows adding a tip:<br />
<br />
Ex. 1a) The pre-set tip value in the send dialog is undefined (user must specify) or set to the client's pre-configured default tip value:<br />
<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip='''</span><br />
<br />
Ex. 1b) The pre-set tip value in the send dialog is explicitly set to zero (this restaurant is on "service charge included in 'amount'" policy and informs the client about this explicitly by "tip=0" in the URI):<br />
<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=0'''</span><br />
<br />
Ex. 2) The pre-set tip value is 15% of 0.567 BTC, i.e. 0.08508 BTC:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=0.08505'''</span><br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25'''</span><br />
[URI code of the percentage character is "%25"]<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%'''</span><br />
["lazy" notation, omitting the "25". Actually, this is NOT correct, not URI compliant (RFC 2396), hence such an URI<br />
should not be generated. But it is proposed that the wallet app that has to decode the URI is implemented to understand<br />
this "lazy" syntax in the "tip" field anyhow, as safeguard to avoid errors in case that the merchant app generates such<br />
a "lazy" URI]<br />
<br />
Ex. 3) The pre-set tip value is 0.08508 BTC, and the "notes" field in the client app is pre-occupied with the name of the restaurant:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25'''</span>&message=Charly%27s%20Bar<br />
<br />
Explanation:<br />
* The new parameter has no "req-" prefix, i.e. if an old bitcoin client app does not know it, it can safely ignore it.<br />
* Otherwise, the customer's bitcoin client will not open the normal but an enhanced send dialog where the customer can specify a tip that will be added to the bill to be paid. In examples 2 and 3 above the tip shall be pre-configured with the amount specified in the URI, so the customer can most conveniently just accept it by a simple tap, if the client app is well-written.<br />
<br />
The details are of course dependent on the client app implementation, a best practice-example is demonstrated in the following images.<br />
<br />
Standard send dialog (no tips):<br />
<br />
[[File:bitcoin-app-tipOFF_BIP_0021.png|border]]<br />
<br />
<br />
Advanced send dialog for giving tips:<br />
<br />
[[File:bitcoin-app-tipON_BIP_0021.png|border]]<br />
<br />
Discussion: It has been argued that the described improvement of the user experience for the scenario "make payment with a tip" can be achieved by sole improvement of the wallet app, without any protocol change.<br />
<br />
But this is only partly true. Certainly enhancement of the wallet app to provide an advanced "send" dialog for easy tipping is crucial. However, with the legacy BIP 0021 the wallet app cannot know whether it shall display the standard send dialog (no tip) or the advanced send dialog (with tip option) to the user. So the user has to select this manually. With the optional "tip" parameter in the URI, the wallet app can readily display the appropriate send dialog without extra user interaction, thereby providing ultimate user experience.<br />
<br />
== Further enhancement for paying tips in restaurant/bar: "tip address" ==<br />
([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 9 Sept 2013)<br />
<br />
Further enhancement: Sending billing amount and tip to separate addresses:<br />
<br />
(Note: This feature is typically invisible in the GUI of the customer's wallet app)<br />
<br />
bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparams ]<br />
bitcoinaddress = base58 *base58<br />
bitcoinparams = *bitcoinparam<br />
bitcoinparam = amountparam | labelparam | messageparam | <span style="color:#0000FF">'''tipparam |'''</span> <span style="color:#E20074">'''tipaddrparam |'''</span> otherparam | reqparam<br />
amountparam = "amount=" *digit [ "." *digit ]<br />
labelparam = "label=" *pchar<br />
messageparam = "message=" *pchar<br />
<span style="color:#0000FF">'''tipparam = "tip=" [ *digit [ "." *digit ] [ "%" [ "25" ] ] ]'''</span><br />
<span style="color:#E20074">'''tipaddrparam = "tipaddr=" bitcoinaddress'''</span><br />
otherparam = pchar *pchar "=" *pchar<br />
reqparam = "req-" pchar *pchar "=" *pchar<br />
<br />
Example:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25</span><span style="color:#E20074">&tipaddr=1waiter7b38klseWrTZm5sE8PrrupPB2Q2'''</span><br />
<br />
The "tipaddr" parameter specifies that if the wallet app sends a tip in addition to the "amount", it shall '''''preferably''''' send it to the specifed "tip address". However, this is not mandatory (because it is an optional parameter w/o "req-"), so if the wallet app sends amount and tip to the main address, the merchant shall still be able to figure this out.<br />
<br />
If the merchant cannot handle tips sent to the same address as the billing amount, he shall instead make use of this parameter:<br />
<br />
<span style="color:#a20024">'''reqtipaddrparam = "req-tipaddr=" bitcoinaddress'''</span><br />
<br />
Example:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25&</span><span style="color:#a20024">&req-tipaddr=1waiter7b38klseWrTZm5sE8PrrupPB2Q2'''</span><br />
<br />
In this case, the wallet app is guaranteed to send the tip to the separate address, or will otherwise reject the complete URI. Upon rejection, the waiter knows that the customer has a non-compliant wallet app and can start a second try showing the URI without any tip parameters (or with "tip=0"). The tip can then be paid in a separate transaction (or classically by cash).<br />
<br />
== Short parameter tags yielding shorter URIs for QR codes ==<br />
([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 10 Sept 2013)<br />
<br />
Another proposal: Allow short forms for the parameter tags, to shorten the URIs.<br />
<br />
This is not important for URIs when used in links on web pages, but it can become relevant when generating QR codes. The longer the URI, the more difficult it will be to scan and decode the QR code by a smartphone due to smaller QR code block size or lower error protection level.<br />
<br />
Hence a simple table of equivalent ALIASES is proposed, to shorten the URI:<br />
<br />
'''Parameter Tag Alias'''<br />
amount= a=<br />
label= l=<br />
message= m=<br />
tip= t=<br />
tipaddr= i=<br />
req- -<br />
req-tipaddr= -i=<br />
<br />
Hence, for example the following URIs are fully equivalent:<br />
<br />
155 characters:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567&tip=15%25&req-tipaddr=1waiter7b38klseWrTZm5sE8PrrupPB2Q2&message=Thank%20You&label=Charly%27s%20Bar</nowiki><br />
<br />
128 characters:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?a=.567&t=15%25&-i=1waiter7b38klseWrTZm5sE8PrrupPB2Q2&m=Thank%20You&l=Charly%27s%20Bar</nowiki><br />
<br />
== Critical Improvement of BIP 0021 for "req-" param ==<br />
([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 12 Sept 2013)<br />
<br />
One aspect of current BIP 0021 is critical:<br />
<br />
It says that wallets that do not know any of the "req-" keys in the URI should reject (i.e. not process) the complete URI, to avoid doing anything in the wrong way.<br />
<br />
However, even older wallet apps may have not even implemented this rule and may still process the "known part" of the URI, thereby causing an unwanted result.<br />
<br />
The solution to the problem is to specify BIP 0021 in a way that, in case that at least one "req-" key is used, some other details of the URI must be modified too, such that it becomes "incompatible" and "undecodable" by older apps.<br />
<br />
The concrete proposal here is to append "R-" directly after "bitcoin:". Then a string with a "req-" parameter would look like this:<br />
<nowiki>bitcoin:</nowiki>'''R-'''<nowiki>175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567&tip=15%25&</nowiki>'''req-'''<nowiki>tipaddr=1waiter7b38klseWrTZm5sE8PrrupPB2Q2&message=Thank%20You&label=Charly%27s%20Bar</nowiki><br />
<br />
<br />
The BFN Syntax then looks as follows:<br />
bitcoinurn = "bitcoin:" '''[ "R-" ]''' bitcoinaddress [ "?" bitcoinparams ]<br />
where "R-" is mandatory as soon as at least one "reqparam" is used.<br />
<br />
<br />
== Paying to Multiple Outputs ==<br />
([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 12 Sept 2013)<br />
<br />
Another Enhancement relates to the "Humble Bundle" scenario: Paying one transaction with multiple outputs, specifying a dedicated amount for each output address.<br />
<br />
This scenario allows to specify additional pairs of addresses and amounts. Optionally, also further labels can be specified. We call the new parameter "'''req-aal'''" for '''a'''ddress-'''a'''mount-'''l'''abel, and we specify it as a '''req'''uired parameter because procesing an incomplete URI would result in sending only a partial amount.<br />
<br />
bitcoinparam = amountparam | labelparam | '''reqaalparam |''' messageparam | tipparam | tipaddrparam | otherparam | reqparam<br />
reqaalparam = "req-aal=" bitcoinaddress ":" *digit [ "." *digit ] [ ":" *pchar]<br />
<br />
Example:<br />
<nowiki>bitcoin:R-175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567&label=book&req-aal=1tZdShH7b38klseWrTZm5sE8PrtZPwqdK:0.123:game&message=Thank%20You</nowiki></div>Michael Shttps://en.bitcoin.it/w/index.php?title=Talk:BIP_0021&diff=40987Talk:BIP 00212013-09-12T01:07:53Z<p>Michael S: Critical improvement proposal of BIP 0021 for "req-" parameter</p>
<hr />
<div>Marian on IRC reports: "The BNF [here] is erroneous, regarding the params, it says [ "?" bitcoinparams ] while bitcoinparams is just *bitcoinparam, thus with that BNF there are no separators between the parameters". --[[User:Gmaxwell|Gmaxwell]] ([[User talk:Gmaxwell|talk]]) 23:04, 23 April 2013 (GMT)<br />
<br />
--> ([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 8 Sept 2013) So should it rather be written something like this (I am not a BNF expert, just following my logic):<br />
bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparam [ bitcoinparams ] ]<br />
bitcoinparams = *bitcoinparamamp<br />
bitcoinparamamp = "&" bitcoinparam<br />
<br />
<br />
== Suggesting usability enhancement in BIP 0021 for paying tips in restaurant/bar conveniently ("tips w/o taps") ==<br />
([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 8 Sept 2013)<br />
<br />
I am suggesting a simple downward compatible enhancement of BIP 0021 to allow effortless tipping in restaurants, bars, pubs, etc.<br />
<br />
When watching bitpay's mobile checkout demo video "http://www.youtube.com/watch?v=YZ-pqo0cLcE" it is clear that paying tips is somewhat cumbersome for the customer with today's wallet and merchant solutions. This can be dramatically improved with some support by the client app and a minor enhancement of BIP 0021.<br />
<br />
<span style="color:#0000FF">'''Enhancement proposal'''</span>:<br />
<br />
bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparams ]<br />
bitcoinaddress = base58 *base58<br />
bitcoinparams = *bitcoinparam<br />
bitcoinparam = amountparam | labelparam | messageparam | <span style="color:#0000FF">'''tipparam |'''</span> otherparam | reqparam<br />
amountparam = "amount=" *digit [ "." *digit ]<br />
labelparam = "label=" *pchar<br />
messageparam = "message=" *pchar<br />
<span style="color:#0000FF">'''tipparam = "tip=" [ *digit [ "." *digit ] [ "%" [ "25" ] ] ]'''</span><br />
otherparam = pchar *pchar "=" *pchar<br />
reqparam = "req-" pchar *pchar "=" *pchar<br />
<br />
Actually, "tipparam" is just a special case of "otherparam", hence completely downwards compatible.<br />
<br />
The tip can be specified in BTC or in percent of the amount, and it acts as a recommended or default tip setting in the customer's wallet app.<br />
<br />
'''Examples''' for the following scenario:<br />
:Request 0.567 BTC from the customer of a restaurant and make the customer's bitcoin app show an advanced send dialog that allows adding a tip:<br />
<br />
Ex. 1a) The pre-set tip value in the send dialog is undefined (user must specify) or set to the client's pre-configured default tip value:<br />
<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip='''</span><br />
<br />
Ex. 1b) The pre-set tip value in the send dialog is explicitly set to zero (this restaurant is on "service charge included in 'amount'" policy and informs the client about this explicitly by "tip=0" in the URI):<br />
<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=0'''</span><br />
<br />
Ex. 2) The pre-set tip value is 15% of 0.567 BTC, i.e. 0.08508 BTC:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=0.08505'''</span><br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25'''</span><br />
[URI code of the percentage character is "%25"]<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%'''</span><br />
["lazy" notation, omitting the "25". Actually, this is NOT correct, not URI compliant (RFC 2396), hence such an URI<br />
should not be generated. But it is proposed that the wallet app that has to decode the URI is implemented to understand<br />
this "lazy" syntax in the "tip" field anyhow, as safeguard to avoid errors in case that the merchant app generates such<br />
a "lazy" URI]<br />
<br />
Ex. 3) The pre-set tip value is 0.08508 BTC, and the "notes" field in the client app is pre-occupied with the name of the restaurant:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25'''</span>&message=Charly%27s%20Bar<br />
<br />
Explanation:<br />
* The new parameter has no "req-" prefix, i.e. if an old bitcoin client app does not know it, it can safely ignore it.<br />
* Otherwise, the customer's bitcoin client will not open the normal but an enhanced send dialog where the customer can specify a tip that will be added to the bill to be paid. In examples 2 and 3 above the tip shall be pre-configured with the amount specified in the URI, so the customer can most conveniently just accept it by a simple tap, if the client app is well-written.<br />
<br />
The details are of course dependent on the client app implementation, a best practice-example is demonstrated in the following images.<br />
<br />
Standard send dialog (no tips):<br />
<br />
[[File:bitcoin-app-tipOFF_BIP_0021.png|border]]<br />
<br />
<br />
Advanced send dialog for giving tips:<br />
<br />
[[File:bitcoin-app-tipON_BIP_0021.png|border]]<br />
<br />
Discussion: It has been argued that the described improvement of the user experience for the scenario "make payment with a tip" can be achieved by sole improvement of the wallet app, without any protocol change.<br />
<br />
But this is only partly true. Certainly enhancement of the wallet app to provide an advanced "send" dialog for easy tipping is crucial. However, with the legacy BIP 0021 the wallet app cannot know whether it shall display the standard send dialog (no tip) or the advanced send dialog (with tip option) to the user. So the user has to select this manually. With the optional "tip" parameter in the URI, the wallet app can readily display the appropriate send dialog without extra user interaction, thereby providing ultimate user experience.<br />
<br />
== Further enhancement for paying tips in restaurant/bar: "tip address" ==<br />
([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 9 Sept 2013)<br />
<br />
Further enhancement: Sending billing amount and tip to separate addresses:<br />
<br />
(Note: This feature is typically invisible in the GUI of the customer's wallet app)<br />
<br />
bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparams ]<br />
bitcoinaddress = base58 *base58<br />
bitcoinparams = *bitcoinparam<br />
bitcoinparam = amountparam | labelparam | messageparam | <span style="color:#0000FF">'''tipparam |'''</span> <span style="color:#E20074">'''tipaddrparam |'''</span> otherparam | reqparam<br />
amountparam = "amount=" *digit [ "." *digit ]<br />
labelparam = "label=" *pchar<br />
messageparam = "message=" *pchar<br />
<span style="color:#0000FF">'''tipparam = "tip=" [ *digit [ "." *digit ] [ "%" [ "25" ] ] ]'''</span><br />
<span style="color:#E20074">'''tipaddrparam = "tipaddr=" bitcoinaddress'''</span><br />
otherparam = pchar *pchar "=" *pchar<br />
reqparam = "req-" pchar *pchar "=" *pchar<br />
<br />
Example:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25</span><span style="color:#E20074">&tipaddr=1waiter7b38klseWrTZm5sE8PrrupPB2Q2'''</span><br />
<br />
The "tipaddr" parameter specifies that if the wallet app sends a tip in addition to the "amount", it shall '''''preferably''''' send it to the specifed "tip address". However, this is not mandatory (because it is an optional parameter w/o "req-"), so if the wallet app sends amount and tip to the main address, the merchant shall still be able to figure this out.<br />
<br />
If the merchant cannot handle tips sent to the same address as the billing amount, he shall instead make use of this parameter:<br />
<br />
<span style="color:#a20024">'''reqtipaddrparam = "req-tipaddr=" bitcoinaddress'''</span><br />
<br />
Example:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25&</span><span style="color:#a20024">&req-tipaddr=1waiter7b38klseWrTZm5sE8PrrupPB2Q2'''</span><br />
<br />
In this case, the wallet app is guaranteed to send the tip to the separate address, or will otherwise reject the complete URI. Upon rejection, the waiter knows that the customer has a non-compliant wallet app and can start a second try showing the URI without any tip parameters (or with "tip=0"). The tip can then be paid in a separate transaction (or classically by cash).<br />
<br />
== Short parameter tags yielding shorter URIs for QR codes ==<br />
([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 10 Sept 2013)<br />
<br />
Another proposal: Allow short forms for the parameter tags, to shorten the URIs.<br />
<br />
This is not important for URIs when used in links on web pages, but it can become relevant when generating QR codes. The longer the URI, the more difficult it will be to scan and decode the QR code by a smartphone due to smaller QR code block size or lower error protection level.<br />
<br />
Hence a simple table of equivalent ALIASES is proposed, to shorten the URI:<br />
<br />
'''Parameter Tag Alias'''<br />
amount= a=<br />
label= l=<br />
message= m=<br />
tip= t=<br />
tipaddr= i=<br />
req- -<br />
req-tipaddr= -i=<br />
<br />
Hence, for example the following URIs are fully equivalent:<br />
<br />
155 characters:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567&tip=15%25&req-tipaddr=1waiter7b38klseWrTZm5sE8PrrupPB2Q2&message=Thank%20You&label=Charly%27s%20Bar</nowiki><br />
<br />
128 characters:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?a=.567&t=15%25&-i=1waiter7b38klseWrTZm5sE8PrrupPB2Q2&m=Thank%20You&l=Charly%27s%20Bar</nowiki><br />
<br />
== Critical Improvement of BIP 0021 for "req-" param ==<br />
([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 12 Sept 2013)<br />
<br />
One aspect of current BIP 0021 is critical:<br />
<br />
It says that wallets that do not know any of the "req-" keys in the URI should reject (i.e. not process) the complete URI, to avoid doing anything in the wrong way.<br />
<br />
However, even older wallet apps may have not even implemented this rule and may still process the "known part" of the URI, thereby causing an unwanted result.<br />
<br />
The solution to the problem is to specify BIP 0021 in a way that, in case that at least one "req-" key is used, some other details of the URI must be modified too, such that it becomes "incompatible" and "undecodable" by older apps.<br />
<br />
The concrete proposal here is to append "R-" directly after "bitcoin:". Then a string with a "req-" parameter would look like this:<br />
<nowiki>bitcoin:</nowiki>'''R-'''<nowiki>175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567&tip=15%25&</nowiki>'''req-'''<nowiki>tipaddr=1waiter7b38klseWrTZm5sE8PrrupPB2Q2&message=Thank%20You&label=Charly%27s%20Bar</nowiki><br />
<br />
<br />
The BFN Syntax then looks as follows:<br />
bitcoinurn = "bitcoin:" '''[ "R-" ]''' bitcoinaddress [ "?" bitcoinparams ]<br />
where "R-" is mandatory as soon as at least one "reqparam" is used.</div>Michael Shttps://en.bitcoin.it/w/index.php?title=Talk:BIP_0021&diff=40922Talk:BIP 00212013-09-09T20:00:04Z<p>Michael S: Added short figure descriptions</p>
<hr />
<div>Marian on IRC reports: "The BNF [here] is erroneous, regarding the params, it says [ "?" bitcoinparams ] while bitcoinparams is just *bitcoinparam, thus with that BNF there are no separators between the parameters". --[[User:Gmaxwell|Gmaxwell]] ([[User talk:Gmaxwell|talk]]) 23:04, 23 April 2013 (GMT)<br />
<br />
--> ([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 8 Sept 2013) So should it rather be written something like this (I am not a BNF expert, just following my logic):<br />
bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparam [ bitcoinparams ] ]<br />
bitcoinparams = *bitcoinparamamp<br />
bitcoinparamamp = "&" bitcoinparam<br />
<br />
<br />
== Suggesting usability enhancement in BIP 0021 for paying tips in restaurant/bar conveniently ("tips w/o taps") ==<br />
([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 8 Sept 2013)<br />
<br />
I am suggesting a simple downward compatible enhancement of BIP 0021 to allow effortless tipping in restaurants, bars, pubs, etc.<br />
<br />
When watching bitpay's mobile checkout demo video "http://www.youtube.com/watch?v=YZ-pqo0cLcE" it is clear that paying tips is somewhat cumbersome for the customer with today's wallet and merchant solutions. This can be dramatically improved with some support by the client app and a minor enhancement of BIP 0021.<br />
<br />
<span style="color:#0000FF">'''Enhancement proposal'''</span>:<br />
<br />
bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparams ]<br />
bitcoinaddress = base58 *base58<br />
bitcoinparams = *bitcoinparam<br />
bitcoinparam = amountparam | labelparam | messageparam | <span style="color:#0000FF">'''tipparam |'''</span> otherparam | reqparam<br />
amountparam = "amount=" *digit [ "." *digit ]<br />
labelparam = "label=" *pchar<br />
messageparam = "message=" *pchar<br />
<span style="color:#0000FF">'''tipparam = "tip=" [ *digit [ "." *digit ] [ "%" [ "25" ] ] ]'''</span><br />
otherparam = pchar *pchar "=" *pchar<br />
reqparam = "req-" pchar *pchar "=" *pchar<br />
<br />
Actually, "tipparam" is just a special case of "otherparam", hence completely downwards compatible.<br />
<br />
The tip can be specified in BTC or in percent of the amount, and it acts as a recommended or default tip setting in the customer's wallet app.<br />
<br />
'''Examples''' for the following scenario:<br />
:Request 0.567 BTC from the customer of a restaurant and make the customer's bitcoin app show an advanced send dialog that allows adding a tip:<br />
<br />
Ex. 1a) The pre-set tip value in the send dialog is undefined (user must specify) or set to the client's pre-configured default tip value:<br />
<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip='''</span><br />
<br />
Ex. 1b) The pre-set tip value in the send dialog is explicitly set to zero (this restaurant is on "service charge included in 'amount'" policy and informs the client about this explicitly by "tip=0" in the URI):<br />
<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=0'''</span><br />
<br />
Ex. 2) The pre-set tip value is 15% of 0.567 BTC, i.e. 0.08508 BTC:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=0.08505'''</span><br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25'''</span><br />
[URI code of the percentage character is "%25"]<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%'''</span><br />
["lazy" notation, omitting the "25". Actually, this is NOT correct, not URI compliant (RFC 2396), hence such an URI<br />
should not be generated. But it is proposed that the wallet app that has to decode the URI is implemented to understand<br />
this "lazy" syntax in the "tip" field anyhow, as safeguard to avoid errors in case that the merchant app generates such<br />
a "lazy" URI]<br />
<br />
Ex. 3) The pre-set tip value is 0.08508 BTC, and the "notes" field in the client app is pre-occupied with the name of the restaurant:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25'''</span>&message=Charly%27s%20Bar<br />
<br />
Explanation:<br />
* The new parameter has no "req-" prefix, i.e. if an old bitcoin client app does not know it, it can safely ignore it.<br />
* Otherwise, the customer's bitcoin client will not open the normal but an enhanced send dialog where the customer can specify a tip that will be added to the bill to be paid. In examples 2 and 3 above the tip shall be pre-configured with the amount specified in the URI, so the customer can most conveniently just accept it by a simple tap, if the client app is well-written.<br />
<br />
The details are of course dependent on the client app implementation, a best practice-example is demonstrated in the following images.<br />
<br />
Standard send dialog (no tips):<br />
<br />
[[File:bitcoin-app-tipOFF_BIP_0021.png|border]]<br />
<br />
<br />
Advanced send dialog for giving tips:<br />
<br />
[[File:bitcoin-app-tipON_BIP_0021.png|border]]<br />
<br />
Discussion: It has been argued that the described improvement of the user experience for the scenario "make payment with a tip" can be achieved by sole improvement of the wallet app, without any protocol change.<br />
<br />
But this is only partly true. Certainly enhancement of the wallet app to provide an advanced "send" dialog for easy tipping is crucial. However, with the legacy BIP 0021 the wallet app cannot know whether it shall display the standard send dialog (no tip) or the advanced send dialog (with tip option) to the user. So the user has to select this manually. With the optional "tip" parameter in the URI, the wallet app can readily display the appropriate send dialog without extra user interaction, thereby providing ultimate user experience.<br />
<br />
== Further enhancement for paying tips in restaurant/bar: "tip address" ==<br />
([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 9 Sept 2013)<br />
<br />
Further enhancement: Sending billing amount and tip to separate addresses:<br />
<br />
(Note: This feature is typically invisible in the GUI of the customer's wallet app)<br />
<br />
bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparams ]<br />
bitcoinaddress = base58 *base58<br />
bitcoinparams = *bitcoinparam<br />
bitcoinparam = amountparam | labelparam | messageparam | <span style="color:#0000FF">'''tipparam |'''</span> <span style="color:#E20074">'''tipaddrparam |'''</span> otherparam | reqparam<br />
amountparam = "amount=" *digit [ "." *digit ]<br />
labelparam = "label=" *pchar<br />
messageparam = "message=" *pchar<br />
<span style="color:#0000FF">'''tipparam = "tip=" [ *digit [ "." *digit ] [ "%" [ "25" ] ] ]'''</span><br />
<span style="color:#E20074">'''tipaddrparam = "tipaddr=" bitcoinaddress'''</span><br />
otherparam = pchar *pchar "=" *pchar<br />
reqparam = "req-" pchar *pchar "=" *pchar<br />
<br />
Example:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25</span><span style="color:#E20074">&tipaddr=1waiter7b38klseWrTZm5sE8PrrupPB2Q2'''</span><br />
<br />
The "tipaddr" parameter specifies that if the wallet app sends a tip in addition to the "amount", it shall '''''preferably''''' send it to the specifed "tip address". However, this is not mandatory (because it is an optional parameter w/o "req-"), so if the wallet app sends amount and tip to the main address, the merchant shall still be able to figure this out.<br />
<br />
If the merchant cannot handle tips sent to the same address as the billing amount, he shall instead make use of this parameter:<br />
<br />
<span style="color:#a20024">'''reqtipaddrparam = "req-tipaddr=" bitcoinaddress'''</span><br />
<br />
Example:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25&</span><span style="color:#a20024">&req-tipaddr=1waiter7b38klseWrTZm5sE8PrrupPB2Q2'''</span><br />
<br />
In this case, the wallet app is guaranteed to send the tip to the separate address, or will otherwise reject the complete URI. Upon rejection, the waiter knows that the customer has a non-compliant wallet app and can start a second try showing the URI without any tip parameters (or with "tip=0"). The tip can then be paid in a separate transaction (or classically by cash).<br />
<br />
== Short parameter tags yielding shorter URIs for QR codes ==<br />
([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 10 Sept 2013)<br />
<br />
Another proposal: Allow short forms for the parameter tags, to shorten the URIs.<br />
<br />
This is not important for URIs when used in links on web pages, but it can become relevant when generating QR codes. The longer the URI, the more difficult it will be to scan and decode the QR code by a smartphone due to smaller QR code block size or lower error protection level.<br />
<br />
Hence a simple table of equivalent ALIASES is proposed, to shorten the URI:<br />
<br />
'''Parameter Tag Alias'''<br />
amount= a=<br />
label= l=<br />
message= m=<br />
tip= t=<br />
tipaddr= i=<br />
req- -<br />
req-tipaddr= -i=<br />
<br />
Hence, for example the following URIs are fully equivalent:<br />
<br />
155 characters:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567&tip=15%25&req-tipaddr=1waiter7b38klseWrTZm5sE8PrrupPB2Q2&message=Thank%20You&label=Charly%27s%20Bar</nowiki><br />
<br />
128 characters:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?a=.567&t=15%25&-i=1waiter7b38klseWrTZm5sE8PrrupPB2Q2&m=Thank%20You&l=Charly%27s%20Bar</nowiki></div>Michael Shttps://en.bitcoin.it/w/index.php?title=Talk:BIP_0021&diff=40921Talk:BIP 00212013-09-09T19:55:46Z<p>Michael S: Give reason why BIP 0021 protocol change complements sole wallet app improvement</p>
<hr />
<div>Marian on IRC reports: "The BNF [here] is erroneous, regarding the params, it says [ "?" bitcoinparams ] while bitcoinparams is just *bitcoinparam, thus with that BNF there are no separators between the parameters". --[[User:Gmaxwell|Gmaxwell]] ([[User talk:Gmaxwell|talk]]) 23:04, 23 April 2013 (GMT)<br />
<br />
--> ([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 8 Sept 2013) So should it rather be written something like this (I am not a BNF expert, just following my logic):<br />
bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparam [ bitcoinparams ] ]<br />
bitcoinparams = *bitcoinparamamp<br />
bitcoinparamamp = "&" bitcoinparam<br />
<br />
<br />
== Suggesting usability enhancement in BIP 0021 for paying tips in restaurant/bar conveniently ("tips w/o taps") ==<br />
([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 8 Sept 2013)<br />
<br />
I am suggesting a simple downward compatible enhancement of BIP 0021 to allow effortless tipping in restaurants, bars, pubs, etc.<br />
<br />
When watching bitpay's mobile checkout demo video "http://www.youtube.com/watch?v=YZ-pqo0cLcE" it is clear that paying tips is somewhat cumbersome for the customer with today's wallet and merchant solutions. This can be dramatically improved with some support by the client app and a minor enhancement of BIP 0021.<br />
<br />
<span style="color:#0000FF">'''Enhancement proposal'''</span>:<br />
<br />
bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparams ]<br />
bitcoinaddress = base58 *base58<br />
bitcoinparams = *bitcoinparam<br />
bitcoinparam = amountparam | labelparam | messageparam | <span style="color:#0000FF">'''tipparam |'''</span> otherparam | reqparam<br />
amountparam = "amount=" *digit [ "." *digit ]<br />
labelparam = "label=" *pchar<br />
messageparam = "message=" *pchar<br />
<span style="color:#0000FF">'''tipparam = "tip=" [ *digit [ "." *digit ] [ "%" [ "25" ] ] ]'''</span><br />
otherparam = pchar *pchar "=" *pchar<br />
reqparam = "req-" pchar *pchar "=" *pchar<br />
<br />
Actually, "tipparam" is just a special case of "otherparam", hence completely downwards compatible.<br />
<br />
The tip can be specified in BTC or in percent of the amount, and it acts as a recommended or default tip setting in the customer's wallet app.<br />
<br />
'''Examples''' for the following scenario:<br />
:Request 0.567 BTC from the customer of a restaurant and make the customer's bitcoin app show an advanced send dialog that allows adding a tip:<br />
<br />
Ex. 1a) The pre-set tip value in the send dialog is undefined (user must specify) or set to the client's pre-configured default tip value:<br />
<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip='''</span><br />
<br />
Ex. 1b) The pre-set tip value in the send dialog is explicitly set to zero (this restaurant is on "service charge included in 'amount'" policy and informs the client about this explicitly by "tip=0" in the URI):<br />
<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=0'''</span><br />
<br />
Ex. 2) The pre-set tip value is 15% of 0.567 BTC, i.e. 0.08508 BTC:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=0.08505'''</span><br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25'''</span><br />
[URI code of the percentage character is "%25"]<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%'''</span><br />
["lazy" notation, omitting the "25". Actually, this is NOT correct, not URI compliant (RFC 2396), hence such an URI<br />
should not be generated. But it is proposed that the wallet app that has to decode the URI is implemented to understand<br />
this "lazy" syntax in the "tip" field anyhow, as safeguard to avoid errors in case that the merchant app generates such<br />
a "lazy" URI]<br />
<br />
Ex. 3) The pre-set tip value is 0.08508 BTC, and the "notes" field in the client app is pre-occupied with the name of the restaurant:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25'''</span>&message=Charly%27s%20Bar<br />
<br />
Explanation:<br />
* The new parameter has no "req-" prefix, i.e. if an old bitcoin client app does not know it, it can safely ignore it.<br />
* Otherwise, the customer's bitcoin client will not open the normal but an enhanced send dialog where the customer can specify a tip that will be added to the bill to be paid. In examples 2 and 3 above the tip shall be pre-configured with the amount specified in the URI, so the customer can most conveniently just accept it by a simple tap, if the client app is well-written.<br />
<br />
The details are of course dependent on the client app implementation, a best practice-example is demonstrated in the following images.<br />
<br />
[[File:bitcoin-app-tipOFF_BIP_0021.png|border]]<br />
<br />
<br />
[[File:bitcoin-app-tipON_BIP_0021.png|border]]<br />
<br />
Discussion: It has been argued that the described improvement of the user experience for the scenario "make payment with a tip" can be achieved by sole improvement of the wallet app, without any protocol change.<br />
<br />
But this is only partly true. Certainly enhancement of the wallet app to provide an advanced "send" dialog for easy tipping is crucial. However, with the legacy BIP 0021 the wallet app cannot know whether it shall display the standard send dialog (no tip) or the advanced send dialog (with tip option) to the user. So the user has to select this manually. With the optional "tip" parameter in the URI, the wallet app can readily display the appropriate send dialog without extra user interaction, thereby providing ultimate user experience.<br />
<br />
== Further enhancement for paying tips in restaurant/bar: "tip address" ==<br />
([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 9 Sept 2013)<br />
<br />
Further enhancement: Sending billing amount and tip to separate addresses:<br />
<br />
(Note: This feature is typically invisible in the GUI of the customer's wallet app)<br />
<br />
bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparams ]<br />
bitcoinaddress = base58 *base58<br />
bitcoinparams = *bitcoinparam<br />
bitcoinparam = amountparam | labelparam | messageparam | <span style="color:#0000FF">'''tipparam |'''</span> <span style="color:#E20074">'''tipaddrparam |'''</span> otherparam | reqparam<br />
amountparam = "amount=" *digit [ "." *digit ]<br />
labelparam = "label=" *pchar<br />
messageparam = "message=" *pchar<br />
<span style="color:#0000FF">'''tipparam = "tip=" [ *digit [ "." *digit ] [ "%" [ "25" ] ] ]'''</span><br />
<span style="color:#E20074">'''tipaddrparam = "tipaddr=" bitcoinaddress'''</span><br />
otherparam = pchar *pchar "=" *pchar<br />
reqparam = "req-" pchar *pchar "=" *pchar<br />
<br />
Example:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25</span><span style="color:#E20074">&tipaddr=1waiter7b38klseWrTZm5sE8PrrupPB2Q2'''</span><br />
<br />
The "tipaddr" parameter specifies that if the wallet app sends a tip in addition to the "amount", it shall '''''preferably''''' send it to the specifed "tip address". However, this is not mandatory (because it is an optional parameter w/o "req-"), so if the wallet app sends amount and tip to the main address, the merchant shall still be able to figure this out.<br />
<br />
If the merchant cannot handle tips sent to the same address as the billing amount, he shall instead make use of this parameter:<br />
<br />
<span style="color:#a20024">'''reqtipaddrparam = "req-tipaddr=" bitcoinaddress'''</span><br />
<br />
Example:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25&</span><span style="color:#a20024">&req-tipaddr=1waiter7b38klseWrTZm5sE8PrrupPB2Q2'''</span><br />
<br />
In this case, the wallet app is guaranteed to send the tip to the separate address, or will otherwise reject the complete URI. Upon rejection, the waiter knows that the customer has a non-compliant wallet app and can start a second try showing the URI without any tip parameters (or with "tip=0"). The tip can then be paid in a separate transaction (or classically by cash).<br />
<br />
== Short parameter tags yielding shorter URIs for QR codes ==<br />
([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 10 Sept 2013)<br />
<br />
Another proposal: Allow short forms for the parameter tags, to shorten the URIs.<br />
<br />
This is not important for URIs when used in links on web pages, but it can become relevant when generating QR codes. The longer the URI, the more difficult it will be to scan and decode the QR code by a smartphone due to smaller QR code block size or lower error protection level.<br />
<br />
Hence a simple table of equivalent ALIASES is proposed, to shorten the URI:<br />
<br />
'''Parameter Tag Alias'''<br />
amount= a=<br />
label= l=<br />
message= m=<br />
tip= t=<br />
tipaddr= i=<br />
req- -<br />
req-tipaddr= -i=<br />
<br />
Hence, for example the following URIs are fully equivalent:<br />
<br />
155 characters:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567&tip=15%25&req-tipaddr=1waiter7b38klseWrTZm5sE8PrrupPB2Q2&message=Thank%20You&label=Charly%27s%20Bar</nowiki><br />
<br />
128 characters:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?a=.567&t=15%25&-i=1waiter7b38klseWrTZm5sE8PrrupPB2Q2&m=Thank%20You&l=Charly%27s%20Bar</nowiki></div>Michael Shttps://en.bitcoin.it/w/index.php?title=Talk:BIP_0021&diff=40910Talk:BIP 00212013-09-09T01:14:55Z<p>Michael S: /* Further enhancement for paying tips in restaurant/bar: "tip address" */</p>
<hr />
<div>Marian on IRC reports: "The BNF [here] is erroneous, regarding the params, it says [ "?" bitcoinparams ] while bitcoinparams is just *bitcoinparam, thus with that BNF there are no separators between the parameters". --[[User:Gmaxwell|Gmaxwell]] ([[User talk:Gmaxwell|talk]]) 23:04, 23 April 2013 (GMT)<br />
<br />
--> ([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 8 Sept 2013) So should it rather be written something like this (I am not a BNF expert, just following my logic):<br />
bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparam [ bitcoinparams ] ]<br />
bitcoinparams = *bitcoinparamamp<br />
bitcoinparamamp = "&" bitcoinparam<br />
<br />
<br />
== Suggesting usability enhancement in BIP 0021 for paying tips in restaurant/bar conveniently ("tips w/o taps") ==<br />
([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 8 Sept 2013)<br />
<br />
I am suggesting a simple downward compatible enhancement of BIP 0021 to allow effortless tipping in restaurants, bars, pubs, etc.<br />
<br />
When watching bitpay's mobile checkout demo video "http://www.youtube.com/watch?v=YZ-pqo0cLcE" it is clear that paying tips is somewhat cumbersome for the customer with today's wallet and merchant solutions. This can be dramatically improved with some support by the client app and a minor enhancement of BIP 0021.<br />
<br />
<span style="color:#0000FF">'''Enhancement proposal'''</span>:<br />
<br />
bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparams ]<br />
bitcoinaddress = base58 *base58<br />
bitcoinparams = *bitcoinparam<br />
bitcoinparam = amountparam | labelparam | messageparam | <span style="color:#0000FF">'''tipparam |'''</span> otherparam | reqparam<br />
amountparam = "amount=" *digit [ "." *digit ]<br />
labelparam = "label=" *pchar<br />
messageparam = "message=" *pchar<br />
<span style="color:#0000FF">'''tipparam = "tip=" [ *digit [ "." *digit ] [ "%" [ "25" ] ] ]'''</span><br />
otherparam = pchar *pchar "=" *pchar<br />
reqparam = "req-" pchar *pchar "=" *pchar<br />
<br />
Actually, "tipparam" is just a special case of "otherparam", hence completely downwards compatible.<br />
<br />
The tip can be specified in BTC or in percent of the amount, and it acts as a recommended or default tip setting in the customer's wallet app.<br />
<br />
'''Examples''' for the following scenario:<br />
:Request 0.567 BTC from the customer of a restaurant and make the customer's bitcoin app show an advanced send dialog that allows adding a tip:<br />
<br />
Ex. 1a) The pre-set tip value in the send dialog is undefined (user must specify) or set to the client's pre-configured default tip value:<br />
<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip='''</span><br />
<br />
Ex. 1b) The pre-set tip value in the send dialog is explicitly set to zero (this restaurant is on "service charge included in 'amount'" policy and informs the client about this explicitly by "tip=0" in the URI):<br />
<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=0'''</span><br />
<br />
Ex. 2) The pre-set tip value is 15% of 0.567 BTC, i.e. 0.08508 BTC:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=0.08505'''</span><br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25'''</span><br />
[URI code of the percentage character is "%25"]<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%'''</span><br />
["lazy" notation, omitting the "25". Actually, this is NOT correct, not URI compliant (RFC 2396), hence such an URI<br />
should not be generated. But it is proposed that the wallet app that has to decode the URI is implemented to understand<br />
this "lazy" syntax in the "tip" field anyhow, as safeguard to avoid errors in case that the merchant app generates such<br />
a "lazy" URI]<br />
<br />
Ex. 3) The pre-set tip value is 0.08508 BTC, and the "notes" field in the client app is pre-occupied with the name of the restaurant:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25'''</span>&message=Charly%27s%20Bar<br />
<br />
Explanation:<br />
* The new parameter has no "req-" prefix, i.e. if an old bitcoin client app does not know it, it can safely ignore it.<br />
* Otherwise, the customer's bitcoin client will not open the normal but an enhanced send dialog where the customer can specify a tip that will be added to the bill to be paid. In examples 2 and 3 above the tip shall be pre-configured with the amount specified in the URI, so the customer can most conveniently just accept it by a simple tap, if the client app is well-written.<br />
<br />
The details are of course dependent on the client app implementation, a best practice-example is demonstrated in the following images.<br />
<br />
[[File:bitcoin-app-tipOFF_BIP_0021.png|border]]<br />
<br />
<br />
[[File:bitcoin-app-tipON_BIP_0021.png|border]]<br />
<br />
<br />
== Further enhancement for paying tips in restaurant/bar: "tip address" ==<br />
([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 9 Sept 2013)<br />
<br />
Further enhancement: Sending billing amount and tip to separate addresses:<br />
<br />
(Note: This feature is typically invisible in the GUI of the customer's wallet app)<br />
<br />
bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparams ]<br />
bitcoinaddress = base58 *base58<br />
bitcoinparams = *bitcoinparam<br />
bitcoinparam = amountparam | labelparam | messageparam | <span style="color:#0000FF">'''tipparam |'''</span> <span style="color:#E20074">'''tipaddrparam |'''</span> otherparam | reqparam<br />
amountparam = "amount=" *digit [ "." *digit ]<br />
labelparam = "label=" *pchar<br />
messageparam = "message=" *pchar<br />
<span style="color:#0000FF">'''tipparam = "tip=" [ *digit [ "." *digit ] [ "%" [ "25" ] ] ]'''</span><br />
<span style="color:#E20074">'''tipaddrparam = "tipaddr=" bitcoinaddress'''</span><br />
otherparam = pchar *pchar "=" *pchar<br />
reqparam = "req-" pchar *pchar "=" *pchar<br />
<br />
Example:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25</span><span style="color:#E20074">&tipaddr=1waiter7b38klseWrTZm5sE8PrrupPB2Q2'''</span><br />
<br />
The "tipaddr" parameter specifies that if the wallet app sends a tip in addition to the "amount", it shall '''''preferably''''' send it to the specifed "tip address". However, this is not mandatory (because it is an optional parameter w/o "req-"), so if the wallet app sends amount and tip to the main address, the merchant shall still be able to figure this out.<br />
<br />
If the merchant cannot handle tips sent to the same address as the billing amount, he shall instead make use of this parameter:<br />
<br />
<span style="color:#a20024">'''reqtipaddrparam = "req-tipaddr=" bitcoinaddress'''</span><br />
<br />
Example:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25&</span><span style="color:#a20024">&req-tipaddr=1waiter7b38klseWrTZm5sE8PrrupPB2Q2'''</span><br />
<br />
In this case, the wallet app is guaranteed to send the tip to the separate address, or will otherwise reject the complete URI. Upon rejection, the waiter knows that the customer has a non-compliant wallet app and can start a second try showing the URI without any tip parameters (or with "tip=0"). The tip can then be paid in a separate transaction (or classically by cash).<br />
<br />
== Short parameter tags yielding shorter URIs for QR codes ==<br />
([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 10 Sept 2013)<br />
<br />
Another proposal: Allow short forms for the parameter tags, to shorten the URIs.<br />
<br />
This is not important for URIs when used in links on web pages, but it can become relevant when generating QR codes. The longer the URI, the more difficult it will be to scan and decode the QR code by a smartphone due to smaller QR code block size or lower error protection level.<br />
<br />
Hence a simple table of equivalent ALIASES is proposed, to shorten the URI:<br />
<br />
'''Parameter Tag Alias'''<br />
amount= a=<br />
label= l=<br />
message= m=<br />
tip= t=<br />
tipaddr= i=<br />
req- -<br />
req-tipaddr= -i=<br />
<br />
Hence, for example the following URIs are fully equivalent:<br />
<br />
155 characters:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567&tip=15%25&req-tipaddr=1waiter7b38klseWrTZm5sE8PrrupPB2Q2&message=Thank%20You&label=Charly%27s%20Bar</nowiki><br />
<br />
128 characters:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?a=.567&t=15%25&-i=1waiter7b38klseWrTZm5sE8PrrupPB2Q2&m=Thank%20You&l=Charly%27s%20Bar</nowiki></div>Michael Shttps://en.bitcoin.it/w/index.php?title=Talk:BIP_0021&diff=40909Talk:BIP 00212013-09-09T01:12:48Z<p>Michael S: /* Further enhancement for paying tips in restaurant/bar: "tip address" */</p>
<hr />
<div>Marian on IRC reports: "The BNF [here] is erroneous, regarding the params, it says [ "?" bitcoinparams ] while bitcoinparams is just *bitcoinparam, thus with that BNF there are no separators between the parameters". --[[User:Gmaxwell|Gmaxwell]] ([[User talk:Gmaxwell|talk]]) 23:04, 23 April 2013 (GMT)<br />
<br />
--> ([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 8 Sept 2013) So should it rather be written something like this (I am not a BNF expert, just following my logic):<br />
bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparam [ bitcoinparams ] ]<br />
bitcoinparams = *bitcoinparamamp<br />
bitcoinparamamp = "&" bitcoinparam<br />
<br />
<br />
== Suggesting usability enhancement in BIP 0021 for paying tips in restaurant/bar conveniently ("tips w/o taps") ==<br />
([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 8 Sept 2013)<br />
<br />
I am suggesting a simple downward compatible enhancement of BIP 0021 to allow effortless tipping in restaurants, bars, pubs, etc.<br />
<br />
When watching bitpay's mobile checkout demo video "http://www.youtube.com/watch?v=YZ-pqo0cLcE" it is clear that paying tips is somewhat cumbersome for the customer with today's wallet and merchant solutions. This can be dramatically improved with some support by the client app and a minor enhancement of BIP 0021.<br />
<br />
<span style="color:#0000FF">'''Enhancement proposal'''</span>:<br />
<br />
bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparams ]<br />
bitcoinaddress = base58 *base58<br />
bitcoinparams = *bitcoinparam<br />
bitcoinparam = amountparam | labelparam | messageparam | <span style="color:#0000FF">'''tipparam |'''</span> otherparam | reqparam<br />
amountparam = "amount=" *digit [ "." *digit ]<br />
labelparam = "label=" *pchar<br />
messageparam = "message=" *pchar<br />
<span style="color:#0000FF">'''tipparam = "tip=" [ *digit [ "." *digit ] [ "%" [ "25" ] ] ]'''</span><br />
otherparam = pchar *pchar "=" *pchar<br />
reqparam = "req-" pchar *pchar "=" *pchar<br />
<br />
Actually, "tipparam" is just a special case of "otherparam", hence completely downwards compatible.<br />
<br />
The tip can be specified in BTC or in percent of the amount, and it acts as a recommended or default tip setting in the customer's wallet app.<br />
<br />
'''Examples''' for the following scenario:<br />
:Request 0.567 BTC from the customer of a restaurant and make the customer's bitcoin app show an advanced send dialog that allows adding a tip:<br />
<br />
Ex. 1a) The pre-set tip value in the send dialog is undefined (user must specify) or set to the client's pre-configured default tip value:<br />
<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip='''</span><br />
<br />
Ex. 1b) The pre-set tip value in the send dialog is explicitly set to zero (this restaurant is on "service charge included in 'amount'" policy and informs the client about this explicitly by "tip=0" in the URI):<br />
<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=0'''</span><br />
<br />
Ex. 2) The pre-set tip value is 15% of 0.567 BTC, i.e. 0.08508 BTC:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=0.08505'''</span><br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25'''</span><br />
[URI code of the percentage character is "%25"]<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%'''</span><br />
["lazy" notation, omitting the "25". Actually, this is NOT correct, not URI compliant (RFC 2396), hence such an URI<br />
should not be generated. But it is proposed that the wallet app that has to decode the URI is implemented to understand<br />
this "lazy" syntax in the "tip" field anyhow, as safeguard to avoid errors in case that the merchant app generates such<br />
a "lazy" URI]<br />
<br />
Ex. 3) The pre-set tip value is 0.08508 BTC, and the "notes" field in the client app is pre-occupied with the name of the restaurant:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25'''</span>&message=Charly%27s%20Bar<br />
<br />
Explanation:<br />
* The new parameter has no "req-" prefix, i.e. if an old bitcoin client app does not know it, it can safely ignore it.<br />
* Otherwise, the customer's bitcoin client will not open the normal but an enhanced send dialog where the customer can specify a tip that will be added to the bill to be paid. In examples 2 and 3 above the tip shall be pre-configured with the amount specified in the URI, so the customer can most conveniently just accept it by a simple tap, if the client app is well-written.<br />
<br />
The details are of course dependent on the client app implementation, a best practice-example is demonstrated in the following images.<br />
<br />
[[File:bitcoin-app-tipOFF_BIP_0021.png|border]]<br />
<br />
<br />
[[File:bitcoin-app-tipON_BIP_0021.png|border]]<br />
<br />
<br />
== Further enhancement for paying tips in restaurant/bar: "tip address" ==<br />
([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 9 Sept 2013)<br />
<br />
Further enhancement: Sending billing amount and tip to separate addresses:<br />
<br />
(Note: This feature is typically invisible in the GUI of the customer's wallet app)<br />
<br />
bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparams ]<br />
bitcoinaddress = base58 *base58<br />
bitcoinparams = *bitcoinparam<br />
bitcoinparam = amountparam | labelparam | messageparam | <span style="color:#0000FF">'''tipparam |'''</span> <span style="color:#E20074">'''tipaddrparam |'''</span> otherparam | reqparam<br />
amountparam = "amount=" *digit [ "." *digit ]<br />
labelparam = "label=" *pchar<br />
messageparam = "message=" *pchar<br />
<span style="color:#0000FF">'''tipparam = "tip=" [ *digit [ "." *digit ] [ "%" [ "25" ] ] ]'''</span><br />
<span style="color:#E20074">'''tipaddrparam = "tipaddr=" bitcoinaddress'''</span><br />
otherparam = pchar *pchar "=" *pchar<br />
reqparam = "req-" pchar *pchar "=" *pchar<br />
<br />
Example:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25</span><span style="color:#E20074">&tipaddr=1waiter7b38klseWrTZm5sE8PrrupPB2Q2'''</span><br />
<br />
The "tipaddr" parameter specifies that if the wallet app sends a tip in addition to the "amount", it shall '''''preferably''''' send it to the specifed "tip address". However, this is not mandatory (because it is an optional parameter w/o "req-"), so if the wallet app sends amount and tip to the main address, the merchant shall still be able to figure this out.<br />
<br />
If the merchant cannot handle tips sent to the same address as the billing amount, he shall instead make use of this parameter:<br />
<br />
<span style="color:#a20024">'''reqtipaddrparam = "req-tipaddr=" bitcoinaddress'''</span><br />
<br />
Example:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25&</span><span style="color:#a20024">&req-tipaddr=1waiter7b38klseWrTZm5sE8PrrupPB2Q2'''</span><br />
<br />
In this case, the wallet app is guaranteed to send the tip to the separate address, or will otherwise reject the complete URI. Upon rejection, the waiter knows that the customer has a non-compliant wallet app and can start a second try showing the URI without any tip parameters (or with "tip=0". The tip can then be paid in a separate transaction (or classically by cash).<br />
<br />
== Short parameter tags yielding shorter URIs for QR codes ==<br />
([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 10 Sept 2013)<br />
<br />
Another proposal: Allow short forms for the parameter tags, to shorten the URIs.<br />
<br />
This is not important for URIs when used in links on web pages, but it can become relevant when generating QR codes. The longer the URI, the more difficult it will be to scan and decode the QR code by a smartphone due to smaller QR code block size or lower error protection level.<br />
<br />
Hence a simple table of equivalent ALIASES is proposed, to shorten the URI:<br />
<br />
'''Parameter Tag Alias'''<br />
amount= a=<br />
label= l=<br />
message= m=<br />
tip= t=<br />
tipaddr= i=<br />
req- -<br />
req-tipaddr= -i=<br />
<br />
Hence, for example the following URIs are fully equivalent:<br />
<br />
155 characters:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567&tip=15%25&req-tipaddr=1waiter7b38klseWrTZm5sE8PrrupPB2Q2&message=Thank%20You&label=Charly%27s%20Bar</nowiki><br />
<br />
128 characters:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?a=.567&t=15%25&-i=1waiter7b38klseWrTZm5sE8PrrupPB2Q2&m=Thank%20You&l=Charly%27s%20Bar</nowiki></div>Michael Shttps://en.bitcoin.it/w/index.php?title=Talk:BIP_0021&diff=40908Talk:BIP 00212013-09-09T01:07:54Z<p>Michael S: </p>
<hr />
<div>Marian on IRC reports: "The BNF [here] is erroneous, regarding the params, it says [ "?" bitcoinparams ] while bitcoinparams is just *bitcoinparam, thus with that BNF there are no separators between the parameters". --[[User:Gmaxwell|Gmaxwell]] ([[User talk:Gmaxwell|talk]]) 23:04, 23 April 2013 (GMT)<br />
<br />
--> ([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 8 Sept 2013) So should it rather be written something like this (I am not a BNF expert, just following my logic):<br />
bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparam [ bitcoinparams ] ]<br />
bitcoinparams = *bitcoinparamamp<br />
bitcoinparamamp = "&" bitcoinparam<br />
<br />
<br />
== Suggesting usability enhancement in BIP 0021 for paying tips in restaurant/bar conveniently ("tips w/o taps") ==<br />
([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 8 Sept 2013)<br />
<br />
I am suggesting a simple downward compatible enhancement of BIP 0021 to allow effortless tipping in restaurants, bars, pubs, etc.<br />
<br />
When watching bitpay's mobile checkout demo video "http://www.youtube.com/watch?v=YZ-pqo0cLcE" it is clear that paying tips is somewhat cumbersome for the customer with today's wallet and merchant solutions. This can be dramatically improved with some support by the client app and a minor enhancement of BIP 0021.<br />
<br />
<span style="color:#0000FF">'''Enhancement proposal'''</span>:<br />
<br />
bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparams ]<br />
bitcoinaddress = base58 *base58<br />
bitcoinparams = *bitcoinparam<br />
bitcoinparam = amountparam | labelparam | messageparam | <span style="color:#0000FF">'''tipparam |'''</span> otherparam | reqparam<br />
amountparam = "amount=" *digit [ "." *digit ]<br />
labelparam = "label=" *pchar<br />
messageparam = "message=" *pchar<br />
<span style="color:#0000FF">'''tipparam = "tip=" [ *digit [ "." *digit ] [ "%" [ "25" ] ] ]'''</span><br />
otherparam = pchar *pchar "=" *pchar<br />
reqparam = "req-" pchar *pchar "=" *pchar<br />
<br />
Actually, "tipparam" is just a special case of "otherparam", hence completely downwards compatible.<br />
<br />
The tip can be specified in BTC or in percent of the amount, and it acts as a recommended or default tip setting in the customer's wallet app.<br />
<br />
'''Examples''' for the following scenario:<br />
:Request 0.567 BTC from the customer of a restaurant and make the customer's bitcoin app show an advanced send dialog that allows adding a tip:<br />
<br />
Ex. 1a) The pre-set tip value in the send dialog is undefined (user must specify) or set to the client's pre-configured default tip value:<br />
<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip='''</span><br />
<br />
Ex. 1b) The pre-set tip value in the send dialog is explicitly set to zero (this restaurant is on "service charge included in 'amount'" policy and informs the client about this explicitly by "tip=0" in the URI):<br />
<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=0'''</span><br />
<br />
Ex. 2) The pre-set tip value is 15% of 0.567 BTC, i.e. 0.08508 BTC:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=0.08505'''</span><br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25'''</span><br />
[URI code of the percentage character is "%25"]<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%'''</span><br />
["lazy" notation, omitting the "25". Actually, this is NOT correct, not URI compliant (RFC 2396), hence such an URI<br />
should not be generated. But it is proposed that the wallet app that has to decode the URI is implemented to understand<br />
this "lazy" syntax in the "tip" field anyhow, as safeguard to avoid errors in case that the merchant app generates such<br />
a "lazy" URI]<br />
<br />
Ex. 3) The pre-set tip value is 0.08508 BTC, and the "notes" field in the client app is pre-occupied with the name of the restaurant:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25'''</span>&message=Charly%27s%20Bar<br />
<br />
Explanation:<br />
* The new parameter has no "req-" prefix, i.e. if an old bitcoin client app does not know it, it can safely ignore it.<br />
* Otherwise, the customer's bitcoin client will not open the normal but an enhanced send dialog where the customer can specify a tip that will be added to the bill to be paid. In examples 2 and 3 above the tip shall be pre-configured with the amount specified in the URI, so the customer can most conveniently just accept it by a simple tap, if the client app is well-written.<br />
<br />
The details are of course dependent on the client app implementation, a best practice-example is demonstrated in the following images.<br />
<br />
[[File:bitcoin-app-tipOFF_BIP_0021.png|border]]<br />
<br />
<br />
[[File:bitcoin-app-tipON_BIP_0021.png|border]]<br />
<br />
<br />
== Further enhancement for paying tips in restaurant/bar: "tip address" ==<br />
([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 9 Sept 2013)<br />
<br />
Further enhancement: Sending amount and tip to separate addresses:<br />
<br />
(Note: This feature is typically invisible in the GUI of the customer's wallet app)<br />
<br />
bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparams ]<br />
bitcoinaddress = base58 *base58<br />
bitcoinparams = *bitcoinparam<br />
bitcoinparam = amountparam | labelparam | messageparam | <span style="color:#0000FF">'''tipparam |'''</span> <span style="color:#E20074">'''tipaddrparam |'''</span> otherparam | reqparam<br />
amountparam = "amount=" *digit [ "." *digit ]<br />
labelparam = "label=" *pchar<br />
messageparam = "message=" *pchar<br />
<span style="color:#0000FF">'''tipparam = "tip=" [ *digit [ "." *digit ] [ "%" [ "25" ] ] ]'''</span><br />
<span style="color:#E20074">'''tipaddrparam = "tipaddr=" bitcoinaddress'''</span><br />
otherparam = pchar *pchar "=" *pchar<br />
reqparam = "req-" pchar *pchar "=" *pchar<br />
<br />
Example:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25</span><span style="color:#E20074">&tipaddr=1waiter7b38klseWrTZm5sE8PrrupPB2Q2'''</span><br />
<br />
The "tipaddr" parameter specifies that if the wallet app sends a tip in addition to the "amount", it shall '''''preferably''''' send it to the specifed "tip address". However, this is not mandatory (because it is an optional parameter w/o "req-"), so if the wallet app sends amount and tip to the main address, the merchant shall still be able to figure this out.<br />
<br />
If the merchant cannot handle tips sent to the same address as the billing amount, he shall instead make use of this parameter:<br />
<br />
<span style="color:#a20024">'''reqtipaddrparam = "req-tipaddr=" bitcoinaddress'''</span><br />
<br />
Example:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25&</span><span style="color:#a20024">&req-tipaddr=1waiter7b38klseWrTZm5sE8PrrupPB2Q2'''</span><br />
<br />
In this case, the wallet app is guaranteed to send the tip to the separate address, or will otherwise reject the complete URI. Upon rejection, the waiter knows that the customer has a non-compliant wallet app and can start a second try showing the URI without any tip parameters (or with "tip=0". The tip can then be paid in a separate transaction (or classically by cash).<br />
<br />
<br />
== Short parameter tags yielding shorter URIs for QR codes ==<br />
([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 10 Sept 2013)<br />
<br />
Another proposal: Allow short forms for the parameter tags, to shorten the URIs.<br />
<br />
This is not important for URIs when used in links on web pages, but it can become relevant when generating QR codes. The longer the URI, the more difficult it will be to scan and decode the QR code by a smartphone due to smaller QR code block size or lower error protection level.<br />
<br />
Hence a simple table of equivalent ALIASES is proposed, to shorten the URI:<br />
<br />
'''Parameter Tag Alias'''<br />
amount= a=<br />
label= l=<br />
message= m=<br />
tip= t=<br />
tipaddr= i=<br />
req- -<br />
req-tipaddr= -i=<br />
<br />
Hence, for example the following URIs are fully equivalent:<br />
<br />
155 characters:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567&tip=15%25&req-tipaddr=1waiter7b38klseWrTZm5sE8PrrupPB2Q2&message=Thank%20You&label=Charly%27s%20Bar</nowiki><br />
<br />
128 characters:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?a=.567&t=15%25&-i=1waiter7b38klseWrTZm5sE8PrrupPB2Q2&m=Thank%20You&l=Charly%27s%20Bar</nowiki></div>Michael Shttps://en.bitcoin.it/w/index.php?title=Talk:BIP_0021&diff=40907Talk:BIP 00212013-09-09T01:05:15Z<p>Michael S: Additional section: Short Aliases for Parameter Tags (making shorter URIs for QR codes)</p>
<hr />
<div>Marian on IRC reports: "The BNF [here] is erroneous, regarding the params, it says [ "?" bitcoinparams ] while bitcoinparams is just *bitcoinparam, thus with that BNF there are no separators between the parameters". --[[User:Gmaxwell|Gmaxwell]] ([[User talk:Gmaxwell|talk]]) 23:04, 23 April 2013 (GMT)<br />
<br />
--> ([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 8 Sept 2013) So should it rather be written something like this (I am not a BNF expert, just following my logic):<br />
bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparam [ bitcoinparams ] ]<br />
bitcoinparams = *bitcoinparamamp<br />
bitcoinparamamp = "&" bitcoinparam<br />
<br />
<br />
== Suggesting usability enhancement in BIP 0021 for paying tips in restaurant/bar conveniently ("tips w/o taps") ==<br />
([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 8 Sept 2013)<br />
<br />
I am suggesting a simple downward compatible enhancement of BIP 0021 to allow effortless tipping in restaurants, bars, pubs, etc.<br />
<br />
When watching bitpay's mobile checkout demo video "http://www.youtube.com/watch?v=YZ-pqo0cLcE" it is clear that paying tips is somewhat cumbersome for the customer with today's wallet and merchant solutions. This can be dramatically improved with some support by the client app and a minor enhancement of BIP 0021.<br />
<br />
<span style="color:#0000FF">'''Enhancement proposal'''</span>:<br />
<br />
bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparams ]<br />
bitcoinaddress = base58 *base58<br />
bitcoinparams = *bitcoinparam<br />
bitcoinparam = amountparam | labelparam | messageparam | <span style="color:#0000FF">'''tipparam |'''</span> otherparam | reqparam<br />
amountparam = "amount=" *digit [ "." *digit ]<br />
labelparam = "label=" *pchar<br />
messageparam = "message=" *pchar<br />
<span style="color:#0000FF">'''tipparam = "tip=" [ *digit [ "." *digit ] [ "%" [ "25" ] ] ]'''</span><br />
otherparam = pchar *pchar "=" *pchar<br />
reqparam = "req-" pchar *pchar "=" *pchar<br />
<br />
Actually, "tipparam" is just a special case of "otherparam", hence completely downwards compatible.<br />
<br />
The tip can be specified in BTC or in percent of the amount, and it acts as a recommended or default tip setting in the customer's wallet app.<br />
<br />
'''Examples''' for the following scenario:<br />
:Request 0.567 BTC from the customer of a restaurant and make the customer's bitcoin app show an advanced send dialog that allows adding a tip:<br />
<br />
Ex. 1a) The pre-set tip value in the send dialog is undefined (user must specify) or set to the client's pre-configured default tip value:<br />
<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip='''</span><br />
<br />
Ex. 1b) The pre-set tip value in the send dialog is explicitly set to zero (this restaurant is on "service charge included in 'amount'" policy and informs the client about this explicitly by "tip=0" in the URI):<br />
<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=0'''</span><br />
<br />
Ex. 2) The pre-set tip value is 15% of 0.567 BTC, i.e. 0.08508 BTC:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=0.08505'''</span><br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25'''</span><br />
[URI code of the percentage character is "%25"]<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%'''</span><br />
["lazy" notation, omitting the "25". Actually, this is NOT correct, not URI compliant (RFC 2396), hence such an URI<br />
should not be generated. But it is proposed that the wallet app that has to decode the URI is implemented to understand<br />
this "lazy" syntax in the "tip" field anyhow, as safeguard to avoid errors in case that the merchant app generates such<br />
a "lazy" URI]<br />
<br />
Ex. 3) The pre-set tip value is 0.08508 BTC, and the "notes" field in the client app is pre-occupied with the name of the restaurant:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25'''</span>&message=Charly%27s%20Bar<br />
<br />
Explanation:<br />
* The new parameter has no "req-" prefix, i.e. if an old bitcoin client app does not know it, it can safely ignore it.<br />
* Otherwise, the customer's bitcoin client will not open the normal but an enhanced send dialog where the customer can specify a tip that will be added to the bill to be paid. In examples 2 and 3 above the tip shall be pre-configured with the amount specified in the URI, so the customer can most conveniently just accept it by a simple tap, if the client app is well-written.<br />
<br />
The details are of course dependent on the client app implementation, a best practice-example is demonstrated in the following images.<br />
<br />
[[File:bitcoin-app-tipOFF_BIP_0021.png|border]]<br />
<br />
<br />
[[File:bitcoin-app-tipON_BIP_0021.png|border]]<br />
<br />
<br />
== Further enhancement for paying tips in restaurant/bar: "tip address" ==<br />
([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 9 Sept 2013)<br />
<br />
Further enhancement: Sending amount and tip to separate addresses:<br />
<br />
(Note: This feature is typically invisible in the GUI of the customer's wallet app)<br />
<br />
bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparams ]<br />
bitcoinaddress = base58 *base58<br />
bitcoinparams = *bitcoinparam<br />
bitcoinparam = amountparam | labelparam | messageparam | <span style="color:#0000FF">'''tipparam |'''</span> <span style="color:#E20074">'''tipaddrparam |'''</span> otherparam | reqparam<br />
amountparam = "amount=" *digit [ "." *digit ]<br />
labelparam = "label=" *pchar<br />
messageparam = "message=" *pchar<br />
<span style="color:#0000FF">'''tipparam = "tip=" [ *digit [ "." *digit ] [ "%" [ "25" ] ] ]'''</span><br />
<span style="color:#E20074">'''tipaddrparam = "tipaddr=" bitcoinaddress'''</span><br />
otherparam = pchar *pchar "=" *pchar<br />
reqparam = "req-" pchar *pchar "=" *pchar<br />
<br />
Example:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25</span><span style="color:#E20074">&tipaddr=1waiter7b38klseWrTZm5sE8PrrupPB2Q2'''</span><br />
<br />
The "tipaddr" parameter specifies that if the wallet app sends a tip in addition to the "amount", it shall '''''preferably''''' send it to the specifed "tip address". However, this is not mandatory (because it is an optional parameter w/o "req-"), so if the wallet app sends amount and tip to the main address, the merchant shall still be able to figure this out.<br />
<br />
If the merchant cannot handle tips sent to the same address as the billing amount, he shall instead make use of this parameter:<br />
<br />
<span style="color:#a20024">'''reqtipaddrparam = "req-tipaddr=" bitcoinaddress'''</span><br />
<br />
Example:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25&</span><span style="color:#a20024">&req-tipaddr=1waiter7b38klseWrTZm5sE8PrrupPB2Q2'''</span><br />
<br />
In this case, the wallet app is guaranteed to send the tip to the separate address, or will otherwise reject the complete URI. Upon rejection, the waiter knows that the customer has a non-compliant wallet app and can start a second try showing the URI without any tip parameters (or with "tip=0". The tip can then be paid in a separate transaction (or classically by cash).<br />
<br />
<br />
== Short parameter tags yielding shorter URIs for QR codes ==<br />
([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 10 Sept 2013)<br />
<br />
Another proposal: Allow short forms for the parameter tags, to shorten the URIs.<br />
<br />
This is not important for URIs when used in links on web pages, but it can become relevant when generating QR codes. The longer the URI, the more difficult it will be to scan and decode the QR code by a smartphone due to smaller QR code block size or lower error protection level.<br />
<br />
Hence a simple table of equivalent ALIASES is proposed, to shorten the URI:<br />
<br />
'''Parameter Tag Alias'''<br />
amount= a=<br />
label= l=<br />
message= m=<br />
tip= t=<br />
tipaddr= i=<br />
req- -<br />
req-tipaddr= -i=<br />
<br />
Hence, for example the following URIs are fully equivalent:<br />
<br />
151 characters:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567&tip=15%25&tipaddr=1waiter7b38klseWrTZm5sE8PrrupPB2Q2&message=Thank%20You&label=Charly%27s%20Bar</nowiki><br />
<br />
127 characters:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?a=.567&t=15%25&i=1waiter7b38klseWrTZm5sE8PrrupPB2Q2&m=Thank%20You&l=Charly%27s%20Bar</nowiki></div>Michael Shttps://en.bitcoin.it/w/index.php?title=Talk:BIP_0021&diff=40897Talk:BIP 00212013-09-08T22:56:14Z<p>Michael S: /* Further enhancement for paying tips in restaurant/bar: "tip address" */ added "tipaddrparam" to bitcoinparam list</p>
<hr />
<div>Marian on IRC reports: "The BNF [here] is erroneous, regarding the params, it says [ "?" bitcoinparams ] while bitcoinparams is just *bitcoinparam, thus with that BNF there are no separators between the parameters". --[[User:Gmaxwell|Gmaxwell]] ([[User talk:Gmaxwell|talk]]) 23:04, 23 April 2013 (GMT)<br />
<br />
--> ([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 8 Sept 2013) So should it rather be written something like this (I am not a BNF expert, just following my logic):<br />
bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparam [ bitcoinparams ] ]<br />
bitcoinparams = *bitcoinparamamp<br />
bitcoinparamamp = "&" bitcoinparam<br />
<br />
<br />
== Suggesting usability enhancement in BIP 0021 for paying tips in restaurant/bar conveniently ("tips w/o taps") ==<br />
([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 8 Sept 2013)<br />
<br />
I am suggesting a simple downward compatible enhancement of BIP 0021 to allow effortless tipping in restaurants, bars, pubs, etc.<br />
<br />
When watching bitpay's mobile checkout demo video "http://www.youtube.com/watch?v=YZ-pqo0cLcE" it is clear that paying tips is somewhat cumbersome for the customer with today's wallet and merchant solutions. This can be dramatically improved with some support by the client app and a minor enhancement of BIP 0021.<br />
<br />
<span style="color:#0000FF">'''Enhancement proposal'''</span>:<br />
<br />
bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparams ]<br />
bitcoinaddress = base58 *base58<br />
bitcoinparams = *bitcoinparam<br />
bitcoinparam = amountparam | labelparam | messageparam | <span style="color:#0000FF">'''tipparam |'''</span> otherparam | reqparam<br />
amountparam = "amount=" *digit [ "." *digit ]<br />
labelparam = "label=" *pchar<br />
messageparam = "message=" *pchar<br />
<span style="color:#0000FF">'''tipparam = "tip=" [ *digit [ "." *digit ] [ "%" [ "25" ] ] ]'''</span><br />
otherparam = pchar *pchar "=" *pchar<br />
reqparam = "req-" pchar *pchar "=" *pchar<br />
<br />
Actually, "tipparam" is just a special case of "otherparam", hence completely downwards compatible.<br />
<br />
The tip can be specified in BTC or in percent of the amount, and it acts as a recommended or default tip setting in the customer's wallet app.<br />
<br />
'''Examples''' for the following scenario:<br />
:Request 0.567 BTC from the customer of a restaurant and make the customer's bitcoin app show an advanced send dialog that allows adding a tip:<br />
<br />
Ex. 1a) The pre-set tip value in the send dialog is undefined (user must specify) or set to the client's pre-configured default tip value:<br />
<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip='''</span><br />
<br />
Ex. 1b) The pre-set tip value in the send dialog is explicitly set to zero (this restaurant is on "service charge included in 'amount'" policy and informs the client about this explicitly by "tip=0" in the URI):<br />
<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=0'''</span><br />
<br />
Ex. 2) The pre-set tip value is 15% of 0.567 BTC, i.e. 0.08508 BTC:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=0.08505'''</span><br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25'''</span><br />
[URI code of the percentage character is "%25"]<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%'''</span><br />
["lazy" notation, omitting the "25". Actually, this is NOT correct, not URI compliant (RFC 2396), hence such an URI<br />
should not be generated. But it is proposed that the wallet app that has to decode the URI is implemented to understand<br />
this "lazy" syntax in the "tip" field anyhow, as safeguard to avoid errors in case that the merchant app generates such<br />
a "lazy" URI]<br />
<br />
Ex. 3) The pre-set tip value is 0.08508 BTC, and the "notes" field in the client app is pre-occupied with the name of the restaurant:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25'''</span>&message=Charly%27s%20Bar<br />
<br />
Explanation:<br />
* The new parameter has no "req-" prefix, i.e. if an old bitcoin client app does not know it, it can safely ignore it.<br />
* Otherwise, the customer's bitcoin client will not open the normal but an enhanced send dialog where the customer can specify a tip that will be added to the bill to be paid. In examples 2 and 3 above the tip shall be pre-configured with the amount specified in the URI, so the customer can most conveniently just accept it by a simple tap, if the client app is well-written.<br />
<br />
The details are of course dependent on the client app implementation, a best practice-example is demonstrated in the following images.<br />
<br />
[[File:bitcoin-app-tipOFF_BIP_0021.png|border]]<br />
<br />
<br />
[[File:bitcoin-app-tipON_BIP_0021.png|border]]<br />
<br />
<br />
== Further enhancement for paying tips in restaurant/bar: "tip address" ==<br />
([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 9 Sept 2013)<br />
<br />
Further enhancement: Sending amount and tip to separate addresses:<br />
<br />
(Note: This feature is typically invisible in the GUI of the customer's wallet app)<br />
<br />
bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparams ]<br />
bitcoinaddress = base58 *base58<br />
bitcoinparams = *bitcoinparam<br />
bitcoinparam = amountparam | labelparam | messageparam | <span style="color:#0000FF">'''tipparam |'''</span> <span style="color:#E20074">'''tipaddrparam |'''</span> otherparam | reqparam<br />
amountparam = "amount=" *digit [ "." *digit ]<br />
labelparam = "label=" *pchar<br />
messageparam = "message=" *pchar<br />
<span style="color:#0000FF">'''tipparam = "tip=" [ *digit [ "." *digit ] [ "%" [ "25" ] ] ]'''</span><br />
<span style="color:#E20074">'''tipaddrparam = "tipaddr=" bitcoinaddress'''</span><br />
otherparam = pchar *pchar "=" *pchar<br />
reqparam = "req-" pchar *pchar "=" *pchar<br />
<br />
Example:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25&</span><span style="color:#E20074">&tipaddr=1waiter7b38klseWrTZm5sE8PrrupPB2Q2'''</span><br />
<br />
The "tipaddr" parameter specifies that if the wallet app sends a tip in addition to the "amount", it shall '''''preferably''''' send it to the specifed "tip address". However, this is not mandatory (because it is an optional parameter w/o "req-"), so if the wallet app sends amount and tip to the main address, the merchant shall still be able to figure this out.<br />
<br />
If the merchant cannot handle tips sent to the same address as the billing amount, he shall instead make use of this parameter:<br />
<br />
<span style="color:#a20024">'''reqtipaddrparam = "req-tipaddr=" bitcoinaddress'''</span><br />
<br />
Example:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25&</span><span style="color:#a20024">&req-tipaddr=1waiter7b38klseWrTZm5sE8PrrupPB2Q2'''</span><br />
<br />
In this case, the wallet app is guaranteed to send the tip to the separate address, or will otherwise reject the complete URI. Upon rejection, the waiter knows that the customer has a non-compliant wallet app and can start a second try showing the URI without any tip parameters (or with "tip=0". The tip can then be paid in a separate transaction (or classically by cash).</div>Michael Shttps://en.bitcoin.it/w/index.php?title=Talk:BIP_0021&diff=40896Talk:BIP 00212013-09-08T22:12:13Z<p>Michael S: Adding further section about "tipaddr" and "req-tipaddr" parameters</p>
<hr />
<div>Marian on IRC reports: "The BNF [here] is erroneous, regarding the params, it says [ "?" bitcoinparams ] while bitcoinparams is just *bitcoinparam, thus with that BNF there are no separators between the parameters". --[[User:Gmaxwell|Gmaxwell]] ([[User talk:Gmaxwell|talk]]) 23:04, 23 April 2013 (GMT)<br />
<br />
--> ([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 8 Sept 2013) So should it rather be written something like this (I am not a BNF expert, just following my logic):<br />
bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparam [ bitcoinparams ] ]<br />
bitcoinparams = *bitcoinparamamp<br />
bitcoinparamamp = "&" bitcoinparam<br />
<br />
<br />
== Suggesting usability enhancement in BIP 0021 for paying tips in restaurant/bar conveniently ("tips w/o taps") ==<br />
([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 8 Sept 2013)<br />
<br />
I am suggesting a simple downward compatible enhancement of BIP 0021 to allow effortless tipping in restaurants, bars, pubs, etc.<br />
<br />
When watching bitpay's mobile checkout demo video "http://www.youtube.com/watch?v=YZ-pqo0cLcE" it is clear that paying tips is somewhat cumbersome for the customer with today's wallet and merchant solutions. This can be dramatically improved with some support by the client app and a minor enhancement of BIP 0021.<br />
<br />
<span style="color:#0000FF">'''Enhancement proposal'''</span>:<br />
<br />
bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparams ]<br />
bitcoinaddress = base58 *base58<br />
bitcoinparams = *bitcoinparam<br />
bitcoinparam = amountparam | labelparam | messageparam | <span style="color:#0000FF">'''tipparam |'''</span> otherparam | reqparam<br />
amountparam = "amount=" *digit [ "." *digit ]<br />
labelparam = "label=" *pchar<br />
messageparam = "message=" *pchar<br />
<span style="color:#0000FF">'''tipparam = "tip=" [ *digit [ "." *digit ] [ "%" [ "25" ] ] ]'''</span><br />
otherparam = pchar *pchar "=" *pchar<br />
reqparam = "req-" pchar *pchar "=" *pchar<br />
<br />
Actually, "tipparam" is just a special case of "otherparam", hence completely downwards compatible.<br />
<br />
The tip can be specified in BTC or in percent of the amount, and it acts as a recommended or default tip setting in the customer's wallet app.<br />
<br />
'''Examples''' for the following scenario:<br />
:Request 0.567 BTC from the customer of a restaurant and make the customer's bitcoin app show an advanced send dialog that allows adding a tip:<br />
<br />
Ex. 1a) The pre-set tip value in the send dialog is undefined (user must specify) or set to the client's pre-configured default tip value:<br />
<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip='''</span><br />
<br />
Ex. 1b) The pre-set tip value in the send dialog is explicitly set to zero (this restaurant is on "service charge included in 'amount'" policy and informs the client about this explicitly by "tip=0" in the URI):<br />
<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=0'''</span><br />
<br />
Ex. 2) The pre-set tip value is 15% of 0.567 BTC, i.e. 0.08508 BTC:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=0.08505'''</span><br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25'''</span><br />
[URI code of the percentage character is "%25"]<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%'''</span><br />
["lazy" notation, omitting the "25". Actually, this is NOT correct, not URI compliant (RFC 2396), hence such an URI<br />
should not be generated. But it is proposed that the wallet app that has to decode the URI is implemented to understand<br />
this "lazy" syntax in the "tip" field anyhow, as safeguard to avoid errors in case that the merchant app generates such<br />
a "lazy" URI]<br />
<br />
Ex. 3) The pre-set tip value is 0.08508 BTC, and the "notes" field in the client app is pre-occupied with the name of the restaurant:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25'''</span>&message=Charly%27s%20Bar<br />
<br />
Explanation:<br />
* The new parameter has no "req-" prefix, i.e. if an old bitcoin client app does not know it, it can safely ignore it.<br />
* Otherwise, the customer's bitcoin client will not open the normal but an enhanced send dialog where the customer can specify a tip that will be added to the bill to be paid. In examples 2 and 3 above the tip shall be pre-configured with the amount specified in the URI, so the customer can most conveniently just accept it by a simple tap, if the client app is well-written.<br />
<br />
The details are of course dependent on the client app implementation, a best practice-example is demonstrated in the following images.<br />
<br />
[[File:bitcoin-app-tipOFF_BIP_0021.png|border]]<br />
<br />
<br />
[[File:bitcoin-app-tipON_BIP_0021.png|border]]<br />
<br />
<br />
== Further enhancement for paying tips in restaurant/bar: "tip address" ==<br />
([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 9 Sept 2013)<br />
<br />
Further enhancement: Sending amount and tip to separate addresses:<br />
<br />
(Note: This feature is typically invisible in the GUI of the customer's wallet app)<br />
<br />
bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparams ]<br />
bitcoinaddress = base58 *base58<br />
bitcoinparams = *bitcoinparam<br />
bitcoinparam = amountparam | labelparam | messageparam | <span style="color:#0000FF">'''tipparam |'''</span> otherparam | reqparam<br />
amountparam = "amount=" *digit [ "." *digit ]<br />
labelparam = "label=" *pchar<br />
messageparam = "message=" *pchar<br />
<span style="color:#0000FF">'''tipparam = "tip=" [ *digit [ "." *digit ] [ "%" [ "25" ] ] ]'''</span><br />
<span style="color:#E20074">'''tipaddrparam = "tipaddr=" bitcoinaddress'''</span><br />
otherparam = pchar *pchar "=" *pchar<br />
reqparam = "req-" pchar *pchar "=" *pchar<br />
<br />
Example:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25&</span><span style="color:#E20074">&tipaddr=1waiter7b38klseWrTZm5sE8PrrupPB2Q2'''</span><br />
<br />
The "tipaddr" parameter specifies that if the wallet app sends a tip in addition to the "amount", it shall '''''preferably''''' send it to the specifed "tip address". However, this is not mandatory (because it is an optional parameter w/o "req-"), so if the wallet app sends amount and tip to the main address, the merchant shall still be able to figure this out.<br />
<br />
If the merchant cannot handle tips sent to the same address as the billing amount, he shall instead make use of this parameter:<br />
<br />
<span style="color:#a20024">'''reqtipaddrparam = "req-tipaddr=" bitcoinaddress'''</span><br />
<br />
Example:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25&</span><span style="color:#a20024">&req-tipaddr=1waiter7b38klseWrTZm5sE8PrrupPB2Q2'''</span><br />
<br />
In this case, the wallet app is guaranteed to send the tip to the separate address, or will otherwise reject the complete URI. Upon rejection, the waiter knows that the customer has a non-compliant wallet app and can start a second try showing the URI without any tip parameters (or with "tip=0". The tip can then be paid in a separate transaction (or classically by cash).</div>Michael Shttps://en.bitcoin.it/w/index.php?title=Talk:BIP_0021&diff=40895Talk:BIP 00212013-09-08T21:03:29Z<p>Michael S: clarified difference of "tip=" vs. "tip=0" ("tip undefined" vs. "service included no tip expected")</p>
<hr />
<div>Marian on IRC reports: "The BNF [here] is erroneous, regarding the params, it says [ "?" bitcoinparams ] while bitcoinparams is just *bitcoinparam, thus with that BNF there are no separators between the parameters". --[[User:Gmaxwell|Gmaxwell]] ([[User talk:Gmaxwell|talk]]) 23:04, 23 April 2013 (GMT)<br />
<br />
--> ([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 8 Sept 2013) So should it rather be written something like this (I am not a BNF expert, just following my logic):<br />
bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparam [ bitcoinparams ] ]<br />
bitcoinparams = *bitcoinparamamp<br />
bitcoinparamamp = "&" bitcoinparam<br />
<br />
<br />
== Suggesting usability enhancement in BIP 0021 for paying tips in restaurant/bar conveniently ==<br />
([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 8 Sept 2013)<br />
<br />
I am suggesting a simple downward compatible enhancement of BIP 0021 to allow effortless tipping in restaurants, bars, pubs, etc.<br />
<br />
When watching bitpay's mobile checkout demo video "http://www.youtube.com/watch?v=YZ-pqo0cLcE" it is clear that paying tips is somewhat cumbersome for the customer with today's wallet and merchant solutions. This can be dramatically improved with some support by the client app and a minor enhancement of BIP 0021.<br />
<br />
<span style="color:#0000FF">'''Enhancement proposal'''</span>:<br />
<br />
bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparams ]<br />
bitcoinaddress = base58 *base58<br />
bitcoinparams = *bitcoinparam<br />
bitcoinparam = amountparam | labelparam | messageparam | <span style="color:#0000FF">'''tipparam |'''</span> otherparam | reqparam<br />
amountparam = "amount=" *digit [ "." *digit ]<br />
labelparam = "label=" *pchar<br />
messageparam = "message=" *pchar<br />
<span style="color:#0000FF">'''tipparam = "tip=" [ *digit [ "." *digit ] [ "%" [ "25" ] ] ]'''</span><br />
otherparam = pchar *pchar "=" *pchar<br />
reqparam = "req-" pchar *pchar "=" *pchar<br />
<br />
Actually, "tipparam" is just a special case of "otherparam", hence completely downwards compatible.<br />
<br />
The tip can be specified in BTC or in percent of the amount, and it acts as a recommended or default tip setting in the customer's wallet app.<br />
<br />
'''Examples''' for the following scenario:<br />
:Request 0.567 BTC from the customer of a restaurant and make the customer's bitcoin app show an advanced send dialog that allows adding a tip:<br />
<br />
Ex. 1a) The pre-set tip value in the send dialog is undefined (user must specify) or set to the client's pre-configured default tip value:<br />
<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip='''</span><br />
<br />
Ex. 1b) The pre-set tip value in the send dialog is explicitly set to zero (this restaurant is on "service charge included in 'amount'" policy and informs the client about this explicitly by "tip=0" in the URI):<br />
<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=0'''</span><br />
<br />
Ex. 2) The pre-set tip value is 15% of 0.567 BTC, i.e. 0.08508 BTC:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=0.08505'''</span><br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25'''</span><br />
[URI code of the percentage character is "%25"]<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%'''</span><br />
["lazy" notation, omitting the "25". Actually, this is NOT correct, not URI compliant (RFC 2396), hence such an URI<br />
should not be generated. But it is proposed that the wallet app that has to decode the URI is implemented to understand<br />
this "lazy" syntax in the "tip" field anyhow, as safeguard to avoid errors in case that the merchant app generates such<br />
a "lazy" URI]<br />
<br />
Ex. 3) The pre-set tip value is 0.08508 BTC, and the "notes" field in the client app is pre-occupied with the name of the restaurant:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25'''</span>&message=Charly%27s%20Bar<br />
<br />
Explanation:<br />
* The new parameter has no "req-" prefix, i.e. if an old bitcoin client app does not know it, it can safely ignore it.<br />
* Otherwise, the customer's bitcoin client will not open the normal but an enhanced send dialog where the customer can specify a tip that will be added to the bill to be paid. In examples 2 and 3 above the tip shall be pre-configured with the amount specified in the URI, so the customer can most conveniently just accept it by a simple tap, if the client app is well-written.<br />
<br />
The details are of course dependent on the client app implementation, a best practice-example is demonstrated in the following images.<br />
<br />
[[File:bitcoin-app-tipOFF_BIP_0021.png|border]]<br />
<br />
<br />
[[File:bitcoin-app-tipON_BIP_0021.png|border]]</div>Michael Shttps://en.bitcoin.it/w/index.php?title=User:Michael_S&diff=40894User:Michael S2013-09-08T20:10:06Z<p>Michael S: Created page with " -----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . I am the Michael_S known from "bitcointalk.org" forum. . . . . . ...."</p>
<hr />
<div> -----BEGIN PGP SIGNED MESSAGE-----<br />
Hash: SHA1<br />
<br />
. . . . . . . . . . . . . . . . . . . . . . . . . . . .<br />
I am the Michael_S known from "bitcointalk.org" forum.<br />
. . . . . . . . . . . . . . . . . . . . . . . . . . . .<br />
bitcoin:1MichaS16UMKFgNjanKrtfD51HpBkqPAwD<br />
. . . . . . . . . . . . . . . . . . . . . . . . . . . .<br />
-----BEGIN PGP SIGNATURE-----<br />
Version: GnuPG v1.4.6 (GNU/Linux)<br />
<br />
iD8DBQFSLNj13WH/l8x+fJkRAmffAKCt2LkQcnfCPmSCYFjJGLWOryDYKwCgtfHC<br />
1lt9RLNj5Y8ASkvI1yzL2fE=<br />
=e1S1<br />
-----END PGP SIGNATURE-----<br />
<br />
PGP Key 0xCC7E7C99<br />
<br />
http://pgp.mit.edu:11371/pks/lookup?search=0xCC7E7C99&op=index<br />
<br />
----</div>Michael Shttps://en.bitcoin.it/w/index.php?title=Vanitygen&diff=40893Vanitygen2013-09-08T19:59:06Z<p>Michael S: /* Vanity addresses for other crypto-coins */ - typo</p>
<hr />
<div>Vanitygen is a command-line vanity bitcoin address generator.<br />
<br />
If you're tired of the random, cryptic addresses generated by regular bitcoin clients, you can use vanitygen to create a more personalized address. Add unique flair when you tell people to send bitcoins to 1stDownqyMHHqnDPRSfiZ5GXJ8Gk9dbjL. Alternatively, vanitygen can be used to generate random addresses offline.<br />
<br />
Vanitygen accepts as input a pattern, or list of patterns to search for, and produces a list of addresses and private keys. Vanitygen's search is probabilistic, and the amount of time required to find a given pattern depends on how complex the pattern is, the speed of your computer, and whether you get lucky.<br />
<br />
The example below illustrates a session of vanitygen. It is typical, and took about 10 sec to finish, using my Core 2 Duo E6600 CPU on x86-64 Linux:<br />
<syntaxhighlight lang="bash"><br />
$ ./vanitygen 1Boat<br />
Difficulty: 4476342<br />
Pattern: 1Boat <br />
Address: 1BoatSLRHtKNngkdXEeobR76b53LETtpyT<br />
Privkey: 5J4XJRyLVgzbXEgh8VNi4qovLzxRftzMd8a18KkdXv4EqAwX3tS<br />
</syntaxhighlight><br />
<br />
Vanitygen includes components to perform address searching on your CPU (vanitygen) and your OpenCL-compatible GPU (oclvanitygen). Both can be built from source, and both are included in the Windows binary package. Also included is oclvanityminer, the vanity address mining client. Oclvanityminer can be used to automatically claim bounties on sites such as [[User:ThePiachu|ThePiachu]]'s [[Vanity Pool]].<br />
<br />
Current version: 0.22<br />
<br />
Windows x86+x64 binaries [https://github.com/downloads/samr7/vanitygen/vanitygen-0.20-win.zip here]. PGP signature [http://insight.gotdns.org/~samr7/vanitygen-0.20-win.zip.asc here].<br />
<br />
Get the source from [https://github.com/samr7/vanitygen GitHub]. Includes Makefiles for Linux and Mac OS X.<br />
<br />
Main discussion at [https://bitcointalk.org/index.php?topic=25804.0 BitCoinTalk]<br />
<br />
== Expected keysearch rate ==<br />
Main article: [[Vanitygen keysearch rate]]<br />
<br />
What key search rate can I expect from hardware X?<br />
<br />
Detailed list forthcoming. Some ballpark estimates are listed below.<br />
<br />
Dual-core desktop CPUs, 32-bit mode: 100-250 Kkey/s.<br />
Dual-core desktop CPUs, 64-bit mode: 150-450 Kkey/s.<br />
Quad-core desktop CPUs, 32-bit mode: 200-400 Kkey/s.<br />
Quad-core desktop CPUs, 64-bit mode: 300-750 Kkey/s.<br />
NVIDIA GT200 GPUs: up to 6.5 Mkey/s<br />
AMD Radeon 58XX, 68XX GPUs: up to 23.5 Mkey/s.<br />
AMD Radeon 69XX GPUs: up to 19.5 Mkey/s.<br />
<br />
As vanitygen performs a lot of large integer arithmetic, running it in 64-bit mode makes a huge difference in key search rate, easily a 50% improvement over 32-bit mode. If you are using a 64-bit edition of Windows, and not using a GPU, be sure to use vanitygen64.exe.<br />
<br />
Radeon 58XX outperforms Radeon 69XX by a very comfortable margin. Oclvanitygen is sensitive to integer multiply throughput, and Radeon 58XX can multiply concurrently with other operations. At similar clocks, a hobbled Radeon 5830 will outperform a Radeon 6970.<br />
<br />
In custom builds, CPU performance will be less than expected if the OpenSSL library is an older version (<1.0.0d) or is not built with the appropriate optimizations enabled.<br />
<br />
== Vanity addresses for other crypto-coins ==<br />
While all bitcoin addresses start with a "1" (one), some other crypto-coins use different address name spaces. Vanitygen (as of version 0.22) can be used to produce vanity addresses for these crypto coins as well (but not for [http://bitmessage.org bitmessage] addresses), by using the "-X" option. The following list provides some example command line calls and also indicates the address range for the respective coin:<br />
<br />
Generate '''Bitcoin''' (BTC), '''Devcoin''' (DVC), '''Freicoin''' (FRC), '''Terracoin''' (TRC) addresses:<br />
$ ./vanitygen -X 0 1 -k<br />
or simply just<br />
$ ./vanitygen 1 -k<br />
<br />
Generate '''Novacoin''' (NVC) addresses:<br />
$ ./vanitygen -X 8 4 -k<br />
$ ./vanitygen -X 8 4D -k<br />
$ ./vanitygen -X 8 4Z -k<br />
$ ./vanitygen -X 8 4a -k<br />
$ ./vanitygen -X 8 4d -k<br />
<br />
Generate '''Feathercoin''' (FTC) addresses:<br />
$ ./vanitygen -X 14 6 -k<br />
$ ./vanitygen -X 14 6d -k<br />
$ ./vanitygen -X 14 6z -k<br />
$ ./vanitygen -X 14 7 -k<br />
$ ./vanitygen -X 14 71 -k<br />
$ ./vanitygen -X 14 72 -k<br />
$ ./vanitygen -X 14 73 -k<br />
<br />
Generate '''Anoncoin''' (ANC) addresses:<br />
$ ./vanitygen -X 23 A -k<br />
$ ./vanitygen -X 23 AF -k<br />
$ ./vanitygen -X 23 AZ -k<br />
$ ./vanitygen -X 23 Aa -k<br />
$ ./vanitygen -X 23 Af -k<br />
<br />
Generate '''Chinacoin''' (CNC) addresses:<br />
$ ./vanitygen -X 28 C -k<br />
$ ./vanitygen -X 28 CG -k<br />
$ ./vanitygen -X 28 CZ -k<br />
$ ./vanitygen -X 28 Ca -k<br />
$ ./vanitygen -X 28 Cf -k<br />
<br />
Generate '''Digitalcoin''' (DGC) addresses:<br />
$ ./vanitygen -X 30 D -k<br />
$ ./vanitygen -X 30 D5 -k<br />
$ ./vanitygen -X 30 D9 -k<br />
$ ./vanitygen -X 30 DA -k<br />
$ ./vanitygen -X 30 DU -k<br />
<br />
Generate '''Litecoin''' (LTC) addresses:<br />
$ ./vanitygen -X 48 L -k<br />
$ ./vanitygen -X 48 LK -k<br />
$ ./vanitygen -X 48 LZ -k<br />
$ ./vanitygen -X 48 La -k<br />
$ ./vanitygen -X 48 Li -k<br />
<br />
Generate '''Namecoin''' (NMC) addresses:<br />
$ ./vanitygen -X 52 M -k<br />
$ ./vanitygen -X 52 Mv -k<br />
$ ./vanitygen -X 52 Mz -k<br />
$ ./vanitygen -X 52 N -k<br />
$ ./vanitygen -X 52 N1 -k<br />
$ ./vanitygen -X 52 N9 -k<br />
$ ./vanitygen -X 52 NA -k<br />
$ ./vanitygen -X 52 NK -k<br />
<br />
Generate '''PPCoin''' (PPC) addresses:<br />
$ ./vanitygen -X 55 P -k<br />
$ ./vanitygen -X 55 P8 -k<br />
$ ./vanitygen -X 55 P9 -k<br />
$ ./vanitygen -X 55 PA -k<br />
$ ./vanitygen -X 55 PX -k<br />
<br />
Generate '''YaCoin''' (YAC) addresses:<br />
$ ./vanitygen -X 77 X -k<br />
$ ./vanitygen -X 77 Xz -k<br />
$ ./vanitygen -X 77 Y -k<br />
$ ./vanitygen -X 77 Y1 -k<br />
$ ./vanitygen -X 77 Y9 -k<br />
$ ./vanitygen -X 77 YA -k<br />
$ ./vanitygen -X 77 YP -k<br />
<br />
Generate '''BBQcoin''' (BQC) addresses:<br />
$ ./vanitygen -X 85 b -k<br />
$ ./vanitygen -X 85 bC -k<br />
$ ./vanitygen -X 85 bZ -k<br />
$ ./vanitygen -X 85 ba -k<br />
$ ./vanitygen -X 85 bc -k<br />
<br />
Generate '''Ixcoin''' (IXC) addresses:<br />
$ ./vanitygen -X 138 x -k<br />
$ ./vanitygen -X 138 xX -k<br />
$ ./vanitygen -X 138 xZ -k<br />
$ ./vanitygen -X 138 xa -k<br />
$ ./vanitygen -X 138 xv -k<br />
<br />
Generally, to find out the address format of a given crypto-coin (i.e. the number after the -X option of vanitygen) one can use this service:<br />
<nowiki>http://darkgamex.ch:2751/q/decode_address/<Address></nowiki><br />
Example: Take any Litecoin address, e.g. "LNipKabgGoTPnzhxsyFwTZdjVSXybjWucp", and submit this URL:<br />
http://darkgamex.ch:2751/q/decode_address/LNipKabgGoTPnzhxsyFwTZdjVSXybjWucp<br />
The browser output will be:<br />
30:265dcf8616a9723d3b4ba35c246b041e20013597<br />
The '''30''' is Litecoin's address format in hex (!), i.e. 30 (hex) = 48 (decimal), i.e. use '''-X 48''' in vanitygen to generate Liteoin addresses.<br />
<br />
Some related info here: https://en.bitcoin.it/wiki/List_of_address_prefixes<br />
<br />
== See also ==<br />
* [[Firstbits]]<br />
* [[Bitcoin Vanity Generation Website]]<br />
<br />
[[Category:Vanity address]]</div>Michael Shttps://en.bitcoin.it/w/index.php?title=Vanitygen&diff=40892Vanitygen2013-09-08T19:58:01Z<p>Michael S: Added section: "Vanity addresses for other crypto-coins"</p>
<hr />
<div>Vanitygen is a command-line vanity bitcoin address generator.<br />
<br />
If you're tired of the random, cryptic addresses generated by regular bitcoin clients, you can use vanitygen to create a more personalized address. Add unique flair when you tell people to send bitcoins to 1stDownqyMHHqnDPRSfiZ5GXJ8Gk9dbjL. Alternatively, vanitygen can be used to generate random addresses offline.<br />
<br />
Vanitygen accepts as input a pattern, or list of patterns to search for, and produces a list of addresses and private keys. Vanitygen's search is probabilistic, and the amount of time required to find a given pattern depends on how complex the pattern is, the speed of your computer, and whether you get lucky.<br />
<br />
The example below illustrates a session of vanitygen. It is typical, and took about 10 sec to finish, using my Core 2 Duo E6600 CPU on x86-64 Linux:<br />
<syntaxhighlight lang="bash"><br />
$ ./vanitygen 1Boat<br />
Difficulty: 4476342<br />
Pattern: 1Boat <br />
Address: 1BoatSLRHtKNngkdXEeobR76b53LETtpyT<br />
Privkey: 5J4XJRyLVgzbXEgh8VNi4qovLzxRftzMd8a18KkdXv4EqAwX3tS<br />
</syntaxhighlight><br />
<br />
Vanitygen includes components to perform address searching on your CPU (vanitygen) and your OpenCL-compatible GPU (oclvanitygen). Both can be built from source, and both are included in the Windows binary package. Also included is oclvanityminer, the vanity address mining client. Oclvanityminer can be used to automatically claim bounties on sites such as [[User:ThePiachu|ThePiachu]]'s [[Vanity Pool]].<br />
<br />
Current version: 0.22<br />
<br />
Windows x86+x64 binaries [https://github.com/downloads/samr7/vanitygen/vanitygen-0.20-win.zip here]. PGP signature [http://insight.gotdns.org/~samr7/vanitygen-0.20-win.zip.asc here].<br />
<br />
Get the source from [https://github.com/samr7/vanitygen GitHub]. Includes Makefiles for Linux and Mac OS X.<br />
<br />
Main discussion at [https://bitcointalk.org/index.php?topic=25804.0 BitCoinTalk]<br />
<br />
== Expected keysearch rate ==<br />
Main article: [[Vanitygen keysearch rate]]<br />
<br />
What key search rate can I expect from hardware X?<br />
<br />
Detailed list forthcoming. Some ballpark estimates are listed below.<br />
<br />
Dual-core desktop CPUs, 32-bit mode: 100-250 Kkey/s.<br />
Dual-core desktop CPUs, 64-bit mode: 150-450 Kkey/s.<br />
Quad-core desktop CPUs, 32-bit mode: 200-400 Kkey/s.<br />
Quad-core desktop CPUs, 64-bit mode: 300-750 Kkey/s.<br />
NVIDIA GT200 GPUs: up to 6.5 Mkey/s<br />
AMD Radeon 58XX, 68XX GPUs: up to 23.5 Mkey/s.<br />
AMD Radeon 69XX GPUs: up to 19.5 Mkey/s.<br />
<br />
As vanitygen performs a lot of large integer arithmetic, running it in 64-bit mode makes a huge difference in key search rate, easily a 50% improvement over 32-bit mode. If you are using a 64-bit edition of Windows, and not using a GPU, be sure to use vanitygen64.exe.<br />
<br />
Radeon 58XX outperforms Radeon 69XX by a very comfortable margin. Oclvanitygen is sensitive to integer multiply throughput, and Radeon 58XX can multiply concurrently with other operations. At similar clocks, a hobbled Radeon 5830 will outperform a Radeon 6970.<br />
<br />
In custom builds, CPU performance will be less than expected if the OpenSSL library is an older version (<1.0.0d) or is not built with the appropriate optimizations enabled.<br />
<br />
== Vanity addresses for other crypto-coins ==<br />
While bitcoin all addresses start with a "1" (one), some other crypto-coins use different address name spaces. Vanitygen (as of version 0.22) can be used to produce vanity addresses for these crypto coins as well (but not for [http://bitmessage.org bitmessage] addresses), by using the "-X" option. The following list provides some example command line calls and also indicates the address range for the respective coin:<br />
<br />
Generate '''Bitcoin''' (BTC), '''Devcoin''' (DVC), '''Freicoin''' (FRC), '''Terracoin''' (TRC) addresses:<br />
$ ./vanitygen -X 0 1 -k<br />
or simply just<br />
$ ./vanitygen 1 -k<br />
<br />
Generate '''Novacoin''' (NVC) addresses:<br />
$ ./vanitygen -X 8 4 -k<br />
$ ./vanitygen -X 8 4D -k<br />
$ ./vanitygen -X 8 4Z -k<br />
$ ./vanitygen -X 8 4a -k<br />
$ ./vanitygen -X 8 4d -k<br />
<br />
Generate '''Feathercoin''' (FTC) addresses:<br />
$ ./vanitygen -X 14 6 -k<br />
$ ./vanitygen -X 14 6d -k<br />
$ ./vanitygen -X 14 6z -k<br />
$ ./vanitygen -X 14 7 -k<br />
$ ./vanitygen -X 14 71 -k<br />
$ ./vanitygen -X 14 72 -k<br />
$ ./vanitygen -X 14 73 -k<br />
<br />
Generate '''Anoncoin''' (ANC) addresses:<br />
$ ./vanitygen -X 23 A -k<br />
$ ./vanitygen -X 23 AF -k<br />
$ ./vanitygen -X 23 AZ -k<br />
$ ./vanitygen -X 23 Aa -k<br />
$ ./vanitygen -X 23 Af -k<br />
<br />
Generate '''Chinacoin''' (CNC) addresses:<br />
$ ./vanitygen -X 28 C -k<br />
$ ./vanitygen -X 28 CG -k<br />
$ ./vanitygen -X 28 CZ -k<br />
$ ./vanitygen -X 28 Ca -k<br />
$ ./vanitygen -X 28 Cf -k<br />
<br />
Generate '''Digitalcoin''' (DGC) addresses:<br />
$ ./vanitygen -X 30 D -k<br />
$ ./vanitygen -X 30 D5 -k<br />
$ ./vanitygen -X 30 D9 -k<br />
$ ./vanitygen -X 30 DA -k<br />
$ ./vanitygen -X 30 DU -k<br />
<br />
Generate '''Litecoin''' (LTC) addresses:<br />
$ ./vanitygen -X 48 L -k<br />
$ ./vanitygen -X 48 LK -k<br />
$ ./vanitygen -X 48 LZ -k<br />
$ ./vanitygen -X 48 La -k<br />
$ ./vanitygen -X 48 Li -k<br />
<br />
Generate '''Namecoin''' (NMC) addresses:<br />
$ ./vanitygen -X 52 M -k<br />
$ ./vanitygen -X 52 Mv -k<br />
$ ./vanitygen -X 52 Mz -k<br />
$ ./vanitygen -X 52 N -k<br />
$ ./vanitygen -X 52 N1 -k<br />
$ ./vanitygen -X 52 N9 -k<br />
$ ./vanitygen -X 52 NA -k<br />
$ ./vanitygen -X 52 NK -k<br />
<br />
Generate '''PPCoin''' (PPC) addresses:<br />
$ ./vanitygen -X 55 P -k<br />
$ ./vanitygen -X 55 P8 -k<br />
$ ./vanitygen -X 55 P9 -k<br />
$ ./vanitygen -X 55 PA -k<br />
$ ./vanitygen -X 55 PX -k<br />
<br />
Generate '''YaCoin''' (YAC) addresses:<br />
$ ./vanitygen -X 77 X -k<br />
$ ./vanitygen -X 77 Xz -k<br />
$ ./vanitygen -X 77 Y -k<br />
$ ./vanitygen -X 77 Y1 -k<br />
$ ./vanitygen -X 77 Y9 -k<br />
$ ./vanitygen -X 77 YA -k<br />
$ ./vanitygen -X 77 YP -k<br />
<br />
Generate '''BBQcoin''' (BQC) addresses:<br />
$ ./vanitygen -X 85 b -k<br />
$ ./vanitygen -X 85 bC -k<br />
$ ./vanitygen -X 85 bZ -k<br />
$ ./vanitygen -X 85 ba -k<br />
$ ./vanitygen -X 85 bc -k<br />
<br />
Generate '''Ixcoin''' (IXC) addresses:<br />
$ ./vanitygen -X 138 x -k<br />
$ ./vanitygen -X 138 xX -k<br />
$ ./vanitygen -X 138 xZ -k<br />
$ ./vanitygen -X 138 xa -k<br />
$ ./vanitygen -X 138 xv -k<br />
<br />
Generally, to find out the address format of a given crypto-coin (i.e. the number after the -X option of vanitygen) one can use this service:<br />
<nowiki>http://darkgamex.ch:2751/q/decode_address/<Address></nowiki><br />
Example: Take any Litecoin address, e.g. "LNipKabgGoTPnzhxsyFwTZdjVSXybjWucp", and submit this URL:<br />
http://darkgamex.ch:2751/q/decode_address/LNipKabgGoTPnzhxsyFwTZdjVSXybjWucp<br />
The browser output will be:<br />
30:265dcf8616a9723d3b4ba35c246b041e20013597<br />
The '''30''' is Litecoin's address format in hex (!), i.e. 30 (hex) = 48 (decimal), i.e. use '''-X 48''' in vanitygen to generate Liteoin addresses.<br />
<br />
Some related info here: https://en.bitcoin.it/wiki/List_of_address_prefixes<br />
<br />
== See also ==<br />
* [[Firstbits]]<br />
* [[Bitcoin Vanity Generation Website]]<br />
<br />
[[Category:Vanity address]]</div>Michael Shttps://en.bitcoin.it/w/index.php?title=Talk:BIP_0021&diff=40881Talk:BIP 00212013-09-08T02:24:44Z<p>Michael S: added own name tags</p>
<hr />
<div>Marian on IRC reports: "The BNF [here] is erroneous, regarding the params, it says [ "?" bitcoinparams ] while bitcoinparams is just *bitcoinparam, thus with that BNF there are no separators between the parameters". --[[User:Gmaxwell|Gmaxwell]] ([[User talk:Gmaxwell|talk]]) 23:04, 23 April 2013 (GMT)<br />
<br />
--> ([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 8 Sept 2013) So should it rather be written something like this (I am not a BNF expert, just following my logic):<br />
bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparam [ bitcoinparams ] ]<br />
bitcoinparams = *bitcoinparamamp<br />
bitcoinparamamp = "&" bitcoinparam<br />
<br />
<br />
== Suggesting usability enhancement in BIP 0021 for paying tips in restaurant/bar conveniently ==<br />
([[User:Michael_S|Michael_S]] ([[User talk:Michael_S|talk]]) 8 Sept 2013)<br />
<br />
I am suggesting a simple downward compatible enhancement of BIP 0021 to allow effortless tipping in restaurants, bars, pubs, etc.<br />
<br />
When watching bitpay's mobile checkout demo video "http://www.youtube.com/watch?v=YZ-pqo0cLcE" it is clear that paying tips is somewhat cumbersome for the customer with today's wallet and merchant solutions. This can be dramatically improved with some support by the client app and a minor enhancement of BIP 0021.<br />
<br />
<span style="color:#0000FF">'''Enhancement proposal'''</span>:<br />
<br />
bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparams ]<br />
bitcoinaddress = base58 *base58<br />
bitcoinparams = *bitcoinparam<br />
bitcoinparam = amountparam | labelparam | messageparam | <span style="color:#0000FF">'''tipparam |'''</span> otherparam | reqparam<br />
amountparam = "amount=" *digit [ "." *digit ]<br />
labelparam = "label=" *pchar<br />
messageparam = "message=" *pchar<br />
<span style="color:#0000FF">'''tipparam = "tip=" [ *digit [ "." *digit ] [ "%" [ "25" ] ] ]'''</span><br />
otherparam = pchar *pchar "=" *pchar<br />
reqparam = "req-" pchar *pchar "=" *pchar<br />
<br />
Actually, "tipparam" is just a special case of "otherparam", hence completely downwards compatible.<br />
<br />
The tip can be specified in BTC or in percent of the amount, and it acts as a recommended or default tip setting in the customer's wallet app.<br />
<br />
'''Examples''' for the following scenario:<br />
:Request 0.567 BTC from the customer of a restaurant and make the customer's bitcoin app show an advanced send dialog that allows adding a tip:<br />
<br />
Ex. 1) The pre-set tip value in the send dialog is set to zero (or to the client's pre-configured default tip value):<br />
<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip='''</span><br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=0'''</span><br />
<br />
Ex. 2) The pre-set tip value is 15% of 0.567 BTC, i.e. 0.08508 BTC:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=0.08505'''</span><br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25'''</span><br />
[URI code of the percentage character is "%25"]<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%'''</span><br />
["lazy" notation, omitting the "25". Actually, this is NOT correct, not URI compliant (RFC 2396), hence such an URI<br />
should not be generated. But it is proposed that the wallet app that has to decode the URI is implemented to understand<br />
this "lazy" syntax in the "tip" field anyhow, as safeguard to avoid errors in case that the merchant app generates such<br />
a "lazy" URI]<br />
<br />
Ex. 3) The pre-set tip value is 0.08508 BTC, and the "notes" field in the client app is pre-occupied with the name of the restaurant:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25'''</span>&message=Charly%27s%20Bar<br />
<br />
Explanation:<br />
* The new parameter has no "req-" prefix, i.e. if an old bitcoin client app does not know it, it can safely ignore it.<br />
* Otherwise, the customer's bitcoin client will not open the normal but an enhanced send dialog where the customer can specify a tip that will be added to the bill to be paid. In examples 2 and 3 above the tip shall be pre-configured with the amount specified in the URI, so the customer can most conveniently just accept it by a simple tap, if the client app is well-written.<br />
<br />
The details are of course dependent on the client app implementation, a best practice-example is demonstrated in the following images.<br />
<br />
[[File:bitcoin-app-tipOFF_BIP_0021.png|border]]<br />
<br />
<br />
[[File:bitcoin-app-tipON_BIP_0021.png|border]]</div>Michael Shttps://en.bitcoin.it/w/index.php?title=Talk:BIP_0021&diff=40880Talk:BIP 00212013-09-08T02:06:16Z<p>Michael S: added reply to original BNF syntax question</p>
<hr />
<div>Marian on IRC reports: "The BNF [here] is erroneous, regarding the params, it says [ "?" bitcoinparams ] while bitcoinparams is just *bitcoinparam, thus with that BNF there are no separators between the parameters". --[[User:Gmaxwell|Gmaxwell]] ([[User talk:Gmaxwell|talk]]) 23:04, 23 April 2013 (GMT)<br />
<br />
--> (Michael_S) So should it rather be written something like this (I am not a BNF expert, just following my logic):<br />
bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparam [ bitcoinparams ] ]<br />
bitcoinparams = *bitcoinparamamp<br />
bitcoinparamamp = "&" bitcoinparam<br />
<br />
<br />
== Suggesting usability enhancement in BIP 0021 for paying tips in restaurant/bar conveniently ==<br />
<br />
I am suggesting a simple downward compatible enhancement of BIP 0021 to allow effortless tipping in restaurants, bars, pubs, etc.<br />
<br />
When watching bitpay's mobile checkout demo video "http://www.youtube.com/watch?v=YZ-pqo0cLcE" it is clear that paying tips is somewhat cumbersome for the customer with today's wallet and merchant solutions. This can be dramatically improved with some support by the client app and a minor enhancement of BIP 0021.<br />
<br />
<span style="color:#0000FF">'''Enhancement proposal'''</span>:<br />
<br />
bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparams ]<br />
bitcoinaddress = base58 *base58<br />
bitcoinparams = *bitcoinparam<br />
bitcoinparam = amountparam | labelparam | messageparam | <span style="color:#0000FF">'''tipparam |'''</span> otherparam | reqparam<br />
amountparam = "amount=" *digit [ "." *digit ]<br />
labelparam = "label=" *pchar<br />
messageparam = "message=" *pchar<br />
<span style="color:#0000FF">'''tipparam = "tip=" [ *digit [ "." *digit ] [ "%" [ "25" ] ] ]'''</span><br />
otherparam = pchar *pchar "=" *pchar<br />
reqparam = "req-" pchar *pchar "=" *pchar<br />
<br />
Actually, "tipparam" is just a special case of "otherparam", hence completely downwards compatible.<br />
<br />
The tip can be specified in BTC or in percent of the amount, and it acts as a recommended or default tip setting in the customer's wallet app.<br />
<br />
'''Examples''' for the following scenario:<br />
:Request 0.567 BTC from the customer of a restaurant and make the customer's bitcoin app show an advanced send dialog that allows adding a tip:<br />
<br />
Ex. 1) The pre-set tip value in the send dialog is set to zero (or to the client's pre-configured default tip value):<br />
<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip='''</span><br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=0'''</span><br />
<br />
Ex. 2) The pre-set tip value is 15% of 0.567 BTC, i.e. 0.08508 BTC:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=0.08505'''</span><br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25'''</span><br />
[URI code of the percentage character is "%25"]<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%'''</span><br />
["lazy" notation, omitting the "25". Actually, this is NOT correct, not URI compliant (RFC 2396), hence such an URI<br />
should not be generated. But it is proposed that the wallet app that has to decode the URI is implemented to understand<br />
this "lazy" syntax in the "tip" field anyhow, as safeguard to avoid errors in case that the merchant app generates such<br />
a "lazy" URI]<br />
<br />
Ex. 3) The pre-set tip value is 0.08508 BTC, and the "notes" field in the client app is pre-occupied with the name of the restaurant:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25'''</span>&message=Charly%27s%20Bar<br />
<br />
Explanation:<br />
* The new parameter has no "req-" prefix, i.e. if an old bitcoin client app does not know it, it can safely ignore it.<br />
* Otherwise, the customer's bitcoin client will not open the normal but an enhanced send dialog where the customer can specify a tip that will be added to the bill to be paid. In examples 2 and 3 above the tip shall be pre-configured with the amount specified in the URI, so the customer can most conveniently just accept it by a simple tap, if the client app is well-written.<br />
<br />
The details are of course dependent on the client app implementation, a best practice-example is demonstrated in the following images.<br />
<br />
[[File:bitcoin-app-tipOFF_BIP_0021.png|border]]<br />
<br />
<br />
[[File:bitcoin-app-tipON_BIP_0021.png|border]]</div>Michael Shttps://en.bitcoin.it/w/index.php?title=Talk:BIP_0021&diff=40879Talk:BIP 00212013-09-08T01:29:48Z<p>Michael S: </p>
<hr />
<div>Marian on IRC reports: "The BNF [here] is erroneous, regarding the params, it says [ "?" bitcoinparams ] while bitcoinparams is just *bitcoinparam, thus with that BNF there are no separators between the parameters". --[[User:Gmaxwell|Gmaxwell]] ([[User talk:Gmaxwell|talk]]) 23:04, 23 April 2013 (GMT)<br />
<br />
== Suggesting usability enhancement in BIP 0021 for paying tips in restaurant/bar conveniently ==<br />
<br />
I am suggesting a simple downward compatible enhancement of BIP 0021 to allow effortless tipping in restaurants, bars, pubs, etc.<br />
<br />
When watching bitpay's mobile checkout demo video "http://www.youtube.com/watch?v=YZ-pqo0cLcE" it is clear that paying tips is somewhat cumbersome for the customer with today's wallet and merchant solutions. This can be dramatically improved with some support by the client app and a minor enhancement of BIP 0021.<br />
<br />
<span style="color:#0000FF">'''Enhancement proposal'''</span>:<br />
<br />
bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparams ]<br />
bitcoinaddress = base58 *base58<br />
bitcoinparams = *bitcoinparam<br />
bitcoinparam = amountparam | labelparam | messageparam | <span style="color:#0000FF">'''tipparam |'''</span> otherparam | reqparam<br />
amountparam = "amount=" *digit [ "." *digit ]<br />
labelparam = "label=" *pchar<br />
messageparam = "message=" *pchar<br />
<span style="color:#0000FF">'''tipparam = "tip=" [ *digit [ "." *digit ] [ "%" [ "25" ] ] ]'''</span><br />
otherparam = pchar *pchar "=" *pchar<br />
reqparam = "req-" pchar *pchar "=" *pchar<br />
<br />
Actually, "tipparam" is just a special case of "otherparam", hence completely downwards compatible.<br />
<br />
The tip can be specified in BTC or in percent of the amount, and it acts as a recommended or default tip setting in the customer's wallet app.<br />
<br />
'''Examples''' for the following scenario:<br />
:Request 0.567 BTC from the customer of a restaurant and make the customer's bitcoin app show an advanced send dialog that allows adding a tip:<br />
<br />
Ex. 1) The pre-set tip value in the send dialog is set to zero (or to the client's pre-configured default tip value):<br />
<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip='''</span><br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=0'''</span><br />
<br />
Ex. 2) The pre-set tip value is 15% of 0.567 BTC, i.e. 0.08508 BTC:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=0.08505'''</span><br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25'''</span><br />
[URI code of the percentage character is "%25"]<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%'''</span><br />
["lazy" notation, omitting the "25". Actually, this is NOT correct, not URI compliant (RFC 2396), hence such an URI<br />
should not be generated. But it is proposed that the wallet app that has to decode the URI is implemented to understand<br />
this "lazy" syntax in the "tip" field anyhow, as safeguard to avoid errors in case that the merchant app generates such<br />
a "lazy" URI]<br />
<br />
Ex. 3) The pre-set tip value is 0.08508 BTC, and the "notes" field in the client app is pre-occupied with the name of the restaurant:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25'''</span>&message=Charly%27s%20Bar<br />
<br />
Explanation:<br />
* The new parameter has no "req-" prefix, i.e. if an old bitcoin client app does not know it, it can safely ignore it.<br />
* Otherwise, the customer's bitcoin client will not open the normal but an enhanced send dialog where the customer can specify a tip that will be added to the bill to be paid. In examples 2 and 3 above the tip shall be pre-configured with the amount specified in the URI, so the customer can most conveniently just accept it by a simple tap, if the client app is well-written.<br />
<br />
The details are of course dependent on the client app implementation, a best practice-example is demonstrated in the following images.<br />
<br />
[[File:bitcoin-app-tipOFF_BIP_0021.png|border]]<br />
<br />
<br />
[[File:bitcoin-app-tipON_BIP_0021.png|border]]</div>Michael Shttps://en.bitcoin.it/w/index.php?title=Talk:BIP_0021&diff=40878Talk:BIP 00212013-09-08T01:27:24Z<p>Michael S: typo</p>
<hr />
<div>Marian on IRC reports: "The BNF [here] is erroneous, regarding the params, it says [ "?" bitcoinparams ] while bitcoinparams is just *bitcoinparam, thus with that BNF there are no separators between the parameters". --[[User:Gmaxwell|Gmaxwell]] ([[User talk:Gmaxwell|talk]]) 23:04, 23 April 2013 (GMT)<br />
<br />
== Suggesting usability enhancement in BIP 0021 for paying tips in restaurant/bar conveniently ==<br />
<br />
I am suggesting a simple downward compatible enhancement of BIP 0021 to allow effortless tipping in restaurants, bars, pubs, etc.<br />
<br />
When watching bitpay's mobile checkout demo video "http://www.youtube.com/watch?v=YZ-pqo0cLcE" it is clear that paying tips is somewhat cumbersome for the customer with today's wallet and merchant solutions. This can be dramatically improved with some support by the client app and a minor enhancement of BIP 0021.<br />
<br />
<span style="color:#0000FF">'''Enhancement proposal'''</span>:<br />
<br />
bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparams ]<br />
bitcoinaddress = base58 *base58<br />
bitcoinparams = *bitcoinparam<br />
bitcoinparam = amountparam | labelparam | messageparam | <span style="color:#0000FF">'''tipparam |'''</span> otherparam | reqparam<br />
amountparam = "amount=" *digit [ "." *digit ]<br />
labelparam = "label=" *pchar<br />
messageparam = "message=" *pchar<br />
<span style="color:#0000FF">'''tipparam = "tip=" [ *digit [ "." *digit ] [ "%" [ "25" ] ] ]'''</span><br />
otherparam = pchar *pchar "=" *pchar<br />
reqparam = "req-" pchar *pchar "=" *pchar<br />
<br />
Actually, "tipparam" is just a special case of "otherparam", hence completely downwards compatible.<br />
<br />
The tip can be specified in BTC or in percent of the amount, and it acts as a recommended or default tip setting in the customer's wallet app.<br />
<br />
'''Examples''' for the following scenario:<br />
:Request 0.567 BTC from the customer of a restaurant and make the customer's bitcoin app show an advanced send dialog that allows adding a tip:<br />
<br />
Ex. 1) The pre-set tip value in the send dialog is set to zero (or to the client's pre-configured default tip value):<br />
<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip='''</span><br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=0'''</span><br />
<br />
Ex. 2) The pre-set tip value is 15% of 0.567 BTC, i.e. 0.08508 BTC:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=0.08505'''</span><br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25'''</span><br />
[URI code of the percentage character is "%25"]<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%'''</span><br />
["lazy" notation, omitting the "25". Actually, this is NOT correct, not URI compliant (RFC 2396), hence such an URI<br />
should not be generated. But it is proposed that the wallet app that has to decode the URI is implemented to understand<br />
this "lazy" syntax in the "tip" field anyhow, as safeguard to avoid errors in case that the merchant app generates such<br />
a "lazy" URI]<br />
<br />
Ex. 3) The pre-set tip value is 0.08508 BTC, and the "notes" field in the client app is pre-occupied with the name of the restaurant:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%'''</span>&message=Charly%27s%20Bar<br />
<br />
Explanation:<br />
* The new parameter has no "req-" prefix, i.e. if an old bitcoin client app does not know it, it can safely ignore it.<br />
* Otherwise, the customer's bitcoin client will not open the normal but an enhanced send dialog where the customer can specify a tip that will be added to the bill to be paid. In examples 2 and 3 above the tip shall be pre-configured with the amount specified in the URI, so the customer can most conveniently just accept it by a simple tap, if the client app is well-written.<br />
<br />
The details are of course dependent on the client app implementation, a best practice-example is demonstrated in the following images.<br />
<br />
[[File:bitcoin-app-tipOFF_BIP_0021.png|border]]<br />
<br />
<br />
[[File:bitcoin-app-tipON_BIP_0021.png|border]]</div>Michael Shttps://en.bitcoin.it/w/index.php?title=Talk:BIP_0021&diff=40877Talk:BIP 00212013-09-08T01:25:47Z<p>Michael S: Added a note on an RFC 2396 uncompliant URI</p>
<hr />
<div>Marian on IRC reports: "The BNF [here] is erroneous, regarding the params, it says [ "?" bitcoinparams ] while bitcoinparams is just *bitcoinparam, thus with that BNF there are no separators between the parameters". --[[User:Gmaxwell|Gmaxwell]] ([[User talk:Gmaxwell|talk]]) 23:04, 23 April 2013 (GMT)<br />
<br />
== Suggesting usability enhancement in BIP 0021 for paying tips in restaurant/bar conveniently ==<br />
<br />
I am suggesting a simple downward compatible enhancement of BIP 0021 to allow effortless tipping in restaurants, bars, pubs, etc.<br />
<br />
When watching bitpay's mobile checkout demo video "http://www.youtube.com/watch?v=YZ-pqo0cLcE" it is clear that paying tips is somewhat cumbersome for the customer with today's wallet and merchant solutions. This can be dramatically improved with some support by the client app and a minor enhancement of BIP 0021.<br />
<br />
<span style="color:#0000FF">'''Enhancement proposal'''</span>:<br />
<br />
bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparams ]<br />
bitcoinaddress = base58 *base58<br />
bitcoinparams = *bitcoinparam<br />
bitcoinparam = amountparam | labelparam | messageparam | <span style="color:#0000FF">'''tipparam |'''</span> otherparam | reqparam<br />
amountparam = "amount=" *digit [ "." *digit ]<br />
labelparam = "label=" *pchar<br />
messageparam = "message=" *pchar<br />
<span style="color:#0000FF">'''tipparam = "tip=" [ *digit [ "." *digit ] [ "%" [ "25" ] ] ]'''</span><br />
otherparam = pchar *pchar "=" *pchar<br />
reqparam = "req-" pchar *pchar "=" *pchar<br />
<br />
Actually, "tipparam" is just a special case of "otherparam", hence completely downwards compatible.<br />
<br />
The tip can be specified in BTC or in percent of the amount, and it acts as a recommended or default tip setting in the customer's wallet app.<br />
<br />
'''Examples''' for the following scenario:<br />
:Request 0.567 BTC from the customer of a restaurant and make the customer's bitcoin app show an advanced send dialog that allows adding a tip:<br />
<br />
Ex. 1) The pre-set tip value in the send dialog is set to zero (or to the client's pre-configured default tip value):<br />
<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip='''</span><br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=0'''</span><br />
<br />
Ex. 2) The pre-set tip value is 15% of 0.567 BTC, i.e. 0.08508 BTC:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=0.08505'''</span><br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25'''</span><br />
[URI code of the percentage character is "%25"]<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%'''</span><br />
["lazy" notation, omitting the "25". Actually, this is NOT correct, not URI compiant (RFC 2396), hence such an URI<br />
should not be generated. But it is proposed that the wallet app that has to decode the URI is implemented to understand<br />
this "lazy" syntax in the "tip" field anyhow, as safeguard to avoid errors in case that the merchant app generates such<br />
a "lazy" URI]<br />
<br />
Ex. 3) The pre-set tip value is 0.08508 BTC, and the "notes" field in the client app is pre-occupied with the name of the restaurant:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%'''</span>&message=Charly%27s%20Bar<br />
<br />
Explanation:<br />
* The new parameter has no "req-" prefix, i.e. if an old bitcoin client app does not know it, it can safely ignore it.<br />
* Otherwise, the customer's bitcoin client will not open the normal but an enhanced send dialog where the customer can specify a tip that will be added to the bill to be paid. In examples 2 and 3 above the tip shall be pre-configured with the amount specified in the URI, so the customer can most conveniently just accept it by a simple tap, if the client app is well-written.<br />
<br />
The details are of course dependent on the client app implementation, a best practice-example is demonstrated in the following images.<br />
<br />
[[File:bitcoin-app-tipOFF_BIP_0021.png|border]]<br />
<br />
<br />
[[File:bitcoin-app-tipON_BIP_0021.png|border]]</div>Michael Shttps://en.bitcoin.it/w/index.php?title=Talk:BIP_0021&diff=40876Talk:BIP 00212013-09-08T00:47:16Z<p>Michael S: /* Suggesting usability enhancement in BIP 0021 for paying tips in restaurant/bar conveniently */ new section</p>
<hr />
<div>Marian on IRC reports: "The BNF [here] is erroneous, regarding the params, it says [ "?" bitcoinparams ] while bitcoinparams is just *bitcoinparam, thus with that BNF there are no separators between the parameters". --[[User:Gmaxwell|Gmaxwell]] ([[User talk:Gmaxwell|talk]]) 23:04, 23 April 2013 (GMT)<br />
<br />
== Suggesting usability enhancement in BIP 0021 for paying tips in restaurant/bar conveniently ==<br />
<br />
I am suggesting a simple downward compatible enhancement of BIP 0021 to allow effortless tipping in restaurants, bars, pubs, etc.<br />
<br />
When watching bitpay's mobile checkout demo video "http://www.youtube.com/watch?v=YZ-pqo0cLcE" it is clear that paying tips is somewhat cumbersome for the customer with today's wallet and merchant solutions. This can be dramatically improved with some support by the client app and a minor enhancement of BIP 0021.<br />
<br />
<span style="color:#0000FF">'''Enhancement proposal'''</span>:<br />
<br />
bitcoinurn = "bitcoin:" bitcoinaddress [ "?" bitcoinparams ]<br />
bitcoinaddress = base58 *base58<br />
bitcoinparams = *bitcoinparam<br />
bitcoinparam = amountparam | labelparam | messageparam | <span style="color:#0000FF">'''tipparam |'''</span> otherparam | reqparam<br />
amountparam = "amount=" *digit [ "." *digit ]<br />
labelparam = "label=" *pchar<br />
messageparam = "message=" *pchar<br />
<span style="color:#0000FF">'''tipparam = "tip=" [ *digit [ "." *digit ] [ "%" [ "25" ] ] ]'''</span><br />
otherparam = pchar *pchar "=" *pchar<br />
reqparam = "req-" pchar *pchar "=" *pchar<br />
<br />
Actually, "tipparam" is just a special case of "otherparam", hence completely downwards compatible.<br />
<br />
The tip can be specified in BTC or in percent of the amount, and it acts as a recommended or default tip setting in the customer's wallet app.<br />
<br />
'''Examples''' for the following scenario:<br />
:Request 0.567 BTC from the customer of a restaurant and make the customer's bitcoin app show an advanced send dialog that allows adding a tip:<br />
<br />
Ex. 1) The pre-set tip value in the send dialog is set to zero (or to the client's pre-configured default tip value):<br />
<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip='''</span><br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=0'''</span><br />
<br />
Ex. 2) The pre-set tip value is 15% of 0.567 BTC, i.e. 0.08508 BTC:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=0.08505'''</span><br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%25'''</span><br />
[URI code of the percentage character is "%25"]<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%'''</span><br />
["lazy" notation, omitting the "25"]<br />
<br />
Ex. 3) The pre-set tip value is 0.08508 BTC, and the "notes" field in the client app is pre-occupied with the name of the restaurant:<br />
<nowiki>bitcoin:175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W?amount=0.567</nowiki><span style="color:#0000FF">'''&tip=15%'''</span>&message=Charly%27s%20Bar<br />
<br />
Explanation:<br />
* The new parameter has no "req-" prefix, i.e. if an old bitcoin client app does not know it, it can safely ignore it.<br />
* Otherwise, the customer's bitcoin client will not open the normal but an enhanced send dialog where the customer can specify a tip that will be added to the bill to be paid. In examples 2 and 3 above the tip shall be pre-configured with the amount specified in the URI, so the customer can most conveniently just accept it by a simple tap, if the client app is well-written.<br />
<br />
The details are of course dependent on the client app implementation, a best practice-example is demonstrated in the following images.<br />
<br />
[[File:bitcoin-app-tipOFF_BIP_0021.png|border]]<br />
<br />
<br />
[[File:bitcoin-app-tipON_BIP_0021.png|border]]</div>Michael Shttps://en.bitcoin.it/w/index.php?title=File:Bitcoin-app-tipON_BIP_0021.png&diff=40875File:Bitcoin-app-tipON BIP 0021.png2013-09-08T00:37:42Z<p>Michael S: </p>
<hr />
<div></div>Michael Shttps://en.bitcoin.it/w/index.php?title=File:Bitcoin-app-tipOFF_BIP_0021.png&diff=40874File:Bitcoin-app-tipOFF BIP 0021.png2013-09-08T00:37:18Z<p>Michael S: </p>
<hr />
<div></div>Michael Shttps://en.bitcoin.it/w/index.php?title=Electrum/Documentation&diff=33180Electrum/Documentation2012-11-29T00:18:43Z<p>Michael S: /* Using Electrum through a HTTP proxy */ Typo: "erver" --> "server"</p>
<hr />
<div>==Documentation of Electrum Bitcoin Client (Focus on the GUI)==<br />
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.<br />
<br />
More documentation, especially with regard to command line parameters, can be found at the parent page of this Wiki, i.e. [[Electrum|here]].<br />
<br />
===Version Info===<br />
Unless stated otherwise in particular sub-sections, the present state of this documentation is based on<br />
* '''Electrum version 0.58'''<br />
As this documentation gets updated, this "version info" can be updated, too!<br />
<br />
Later versions of Electrum may add new features or deviate from this description to some extend.<br />
<br />
===Open/Unclear Points===<br />
<br />
Discussions about unclear points should take place on the [[Talk:Electrum/Documentation|Discussion page.]]<br />
<br />
==What is a "Wallet" and a "Bitcoin Address"?==<br />
* (General, not specific to Electrum)<br />
<br />
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.<br />
<br />
Your wallet's balance is the sum of all Bitcoins of all your wallet's Bitcoin addresses.<br />
<br />
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.<br />
<br />
===Normal Addresses===<br />
* (More or less general, not too specific to Electrum)<br />
====How are New "Normal Addresses" Created for my Wallet?====<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
===Change Addresses===<br />
* (More or less general, not too specific to Electrum)<br />
====What is a "Change Address", and why is it useful?====<br />
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.<br />
<br />
'''How it works:'''<br />
<br />
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.<br />
<br />
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.<br />
<br />
Exception: If all the Bitcoins of "A" are sent to "B", there is no need for creating a change address "C".<br />
<br />
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".<br />
<br />
'''Why the concept of "change addresses" is useful:'''<br />
<br />
* 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.<br />
* It also conceals which output is the "spend" and which is the "change".<br />
<br />
===Imported Addresses===<br />
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.<br />
<br />
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"]].<br />
<br />
===Deterministic Wallet===<br />
====What is a "Deterministic Wallet" in Electrum?====<br />
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).<br />
<br />
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).<br />
This is a big advantage when it comes to making wallet backups:<br />
* ''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.<br />
* ''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!<br />
<br />
===Seed===<br />
====What is the "Seed" of a Deterministic Wallet in Electrum?====<br />
The Seed of a [[#Deterministic Wallet|deterministic wallet]] is a series of 128 random bits in Electrum.<br />
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.<br />
<br />
So there are 2^128 possible seeds for a deterministic wallet in Electrum.<br />
For comparison, the total number of Bitcoin addresses is 2^160, and the number of atoms on earth is 2^166.<br />
So there exists one Bitcoin address per 64 atoms on earth, and there exists one seed of Electrum wallets per 4.3 Billion Bitcoin addresses.<br />
(By the way: The number of atoms in the complete universe is estimated as 2^266).<br />
<br />
===What is the "Gap Limit"?===<br />
<br />
The gap limit is the maximal number of contiguous unused addresses in your deterministic sequence of addresses.<br />
<br />
If you recover your wallet from seed, you will notice that the gap limit is asked by the recovery dialog.<br />
It is used in order to decide when to stop the recovery procedure.<br />
<br />
If you need to have more receiving addresses in your wallet, you may increase your gap limit (expert mode).<br />
This, however, means that you will need to remember the new limit in order to be able to recover your wallet from seed.<br />
<br />
==More on the Electrum GUI==<br />
<br />
===Send tab and completions===<br />
<br />
The "pay to" input line does not only accept bitcoin addresses. You may type a label from your list of contacts, or an alias.<br />
<br />
Completions are available based on the labels of your addressbook. Example: <br />
<br />
[[Image:Electrum completion 0.png|450px]]<br />
[[Image:Electrum completion 1.png|450px]]<br />
<br />
===What does it mean to "Prioritize" or "Freeze" Addresses in Electrum?===<br />
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.<br />
<br />
* 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.<br />
* 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. <br />
<br />
The user can (de)prioritize or (un)freeze both [[#Normal Addresses|normal]] and [[#Change Addresses|change]] addresses.<br />
<br />
Note: Clearly, an address can not be "prioritized" and "frozen" at the same time.<br />
<br />
===What does the "Tx" column mean in Electrum?===<br />
* Expert Mode only<br />
* Applies to "Receive" tab (own wallet's addresses) and "Contacts" tab (foreing addresses).<br />
<br />
Tx stands for "Transaction"<br />
<br />
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).<br />
<br />
'''In the "Receive" tab (own addresses):'''<br />
<br />
The number in the Tx column indicates the total number of _incoming_ Bitcoin transactions that have ever been sent to this address.<br />
<br />
<br />
'''In the "Contacts" tab (foreign addresses):'''<br />
<br />
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<br />
<br />
===What does the "Balance" column mean in Electrum?===<br />
* Expert Mode only<br />
* Applies to "Receive" tab only (i.e. own wallet's addresses).<br />
<br />
The balance column indicates the amount of Bitcoins belonging to the given address.<br />
The individual balances add up to the total balance of your wallet.<br />
<br />
===What does the "Flag" column mean in Electrum?===<br />
* Expert Mode only<br />
* Applies to "Receive" tab only (i.e. own wallet's addresses).<br />
<br />
This column indicates certain properties of the different addresses:<br />
* C = [[#Change Addresses|Change address]] (without a "C" it means it is a [[#Normal Addresses|normal address]])<br />
* P = Prioritized address<br />
* F = Frozen address<br />
* I = [[#Imported Addresses|Imported address]]<br />
<br />
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]].<br />
<br />
===What do colors mean?===<br />
In the Receive tab:<br />
*green = prioritized<br />
*blue = frozen<br />
In the Contacts tab:<br />
*gray = alias<br />
<br />
==Troubleshooting==<br />
<br />
=== 'transaction rejected by memorypool' errors ===<br />
<br />
When you send a transaction, there is a delay before the Electrum client displays the transaction in its history.<br />
This is because the server polls bitcoind's memorypool every 10 seconds.<br />
<br />
If you create another transaction during this interval, during which the first tx is not displayed,<br />
then your client will pick the same coins again, and the transaction will be rejected as a [[Double-spending|double spend]].<br />
<br />
<br />
=== Using Electrum through a HTTP proxy ===<br />
<br />
When you are behind a firewall you can use a HTTP proxy to connect to an Electrum server with some limitations¹.<br />
<br />
On Linux (and other POSIX-like systems) set the ''http_proxy'' variable and start the Electrum client, e.g.<br />
<pre><br />
$ export http_proxy="http://<proxyname>:<proxyport>/"<br />
$ ./electrum<br />
</pre><br />
Once the client comes up you need to change your server connection to 'http' and to adjust the port, afterwards your Electrum client should work as usual. <br />
<br />
¹ Limitations:<br />
* Electrum server selection won't work; you must manually enter the connection data (server, port & protocol) <br />
* Exchange rates cannot be fetched/displayed.<br />
<br />
==External Links==<br />
* [http://ecdsa.org/electrum Electrum] project website<br />
* [https://gitorious.org/electrum Electrum] project source (gitorius)<br />
* [https://bitcointalk.org/index.php?topic=50936.msg950497#msg950497 Electrum Forum] - here this documentation was started</div>Michael Shttps://en.bitcoin.it/w/index.php?title=Talk:Electrum/TODO&diff=29401Talk:Electrum/TODO2012-08-04T10:51:30Z<p>Michael S: Created page with "I think what would be nice: * offline wallet support *via GUI* (like Armory), so that I can do my BTC transfers via an offline PC running Electrum, and USB stick and an online..."</p>
<hr />
<div>I think what would be nice:<br />
* offline wallet support *via GUI* (like Armory), so that I can do my BTC transfers via an offline PC running Electrum, and USB stick and an online PC running Electrum, where my private keys are only on my offline PC.<br />
* import/backup of (non-deterministic) keys via GUI</div>Michael Shttps://en.bitcoin.it/w/index.php?title=Electrum/Documentation&diff=29369Electrum/Documentation2012-08-03T23:12:43Z<p>Michael S: /* Send tab and completions */ Editorial: Added one space character.</p>
<hr />
<div>==Documentation of Electrum Bitcoin Client (Focus on the GUI)==<br />
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.<br />
<br />
More documentation, especially with regard to command line parameters, can be found at the parent page of this Wiki, i.e. [[Electrum|here]].<br />
<br />
===Version Info===<br />
Unless stated otherwise in particular sub-sections, the present state of this documentation is based on<br />
* '''Electrum version 0.58'''<br />
As this documentation gets updated, this "version info" can be updated, too!<br />
<br />
Later versions of Electrum may add new features or deviate from this description to some extend.<br />
<br />
===Open/Unclear Points===<br />
<br />
Discussions about unclear points should take place on the [[Talk:Electrum/Documentation|Discussion page.]]<br />
<br />
==What is a "Wallet" and a "Bitcoin Address"?==<br />
* (General, not specific to Electrum)<br />
<br />
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.<br />
<br />
Your wallet's balance is the sum of all Bitcoins of all your wallet's Bitcoin addresses.<br />
<br />
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.<br />
<br />
===Normal Addresses===<br />
* (More or less general, not too specific to Electrum)<br />
====How are New "Normal Addresses" Created for my Wallet?====<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
===Change Addresses===<br />
* (More or less general, not too specific to Electrum)<br />
====What is a "Change Address", and why is it useful?====<br />
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.<br />
<br />
'''How it works:'''<br />
<br />
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.<br />
<br />
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.<br />
<br />
Exception: If all the Bitcoins of "A" are sent to "B", there is no need for creating a change address "C".<br />
<br />
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".<br />
<br />
'''Why the concept of "change addresses" is useful:'''<br />
<br />
* 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.<br />
* It also conceals which output is the "spend" and which is the "change".<br />
<br />
===Imported Addresses===<br />
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.<br />
<br />
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"]].<br />
<br />
===Deterministic Wallet===<br />
====What is a "Deterministic Wallet" in Electrum?====<br />
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).<br />
<br />
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).<br />
This is a big advantage when it comes to making wallet backups:<br />
* ''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.<br />
* ''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!<br />
<br />
===Seed===<br />
====What is the "Seed" of a Deterministic Wallet in Electrum?====<br />
The Seed of a [[#Deterministic Wallet|deterministic wallet]] is a series of 128 random bits in Electrum.<br />
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.<br />
<br />
So there are 2^128 possible seeds for a deterministic wallet in Electrum.<br />
For comparison, the total number of Bitcoin addresses is 2^160, and the number of atoms on earth is 2^166.<br />
So there exists one Bitcoin address per 64 atoms on earth, and there exists one seed of Electrum wallets per 4.3 Billion Bitcoin addresses.<br />
(By the way: The number of atoms in the complete universe is estimated as 2^266).<br />
<br />
===What is the "Gap Limit"?===<br />
<br />
The gap limit is the maximal number of contiguous unused addresses in your deterministic sequence of addresses.<br />
<br />
If you recover your wallet from seed, you will notice that the gap limit is asked by the recovery dialog.<br />
It is used in order to decide when to stop the recovery procedure.<br />
<br />
If you need to have more receiving addresses in your wallet, you may increase your gap limit (expert mode).<br />
This, however, means that you will need to remember the new limit in order to be able to recover your wallet from seed.<br />
<br />
==More on the Electrum GUI==<br />
<br />
===Send tab and completions===<br />
<br />
The "pay to" input line does not only accept bitcoin addresses. You may type a label from your list of contacts, or an alias.<br />
<br />
Completions are available based on the labels of your addressbook. Example: <br />
<br />
[[Image:Electrum completion 0.png|450px]]<br />
[[Image:Electrum completion 1.png|450px]]<br />
<br />
===What does it mean to "Prioritize" or "Freeze" Addresses in Electrum?===<br />
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.<br />
<br />
* 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.<br />
* 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. <br />
<br />
The user can (de)prioritize or (un)freeze both [[#Normal Addresses|normal]] and [[#Change Addresses|change]] addresses.<br />
<br />
Note: Clearly, an address can not be "prioritized" and "frozen" at the same time.<br />
<br />
===What does the "Tx" column mean in Electrum?===<br />
* Expert Mode only<br />
* Applies to "Receive" tab (own wallet's addresses) and "Contacts" tab (foreing addresses).<br />
<br />
Tx stands for "Transaction"<br />
<br />
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).<br />
<br />
'''In the "Receive" tab (own addresses):'''<br />
<br />
The number in the Tx column indicates the total number of _incoming_ Bitcoin transactions that have ever been sent to this address.<br />
<br />
<br />
'''In the "Contacts" tab (foreign addresses):'''<br />
<br />
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<br />
<br />
===What does the "Balance" column mean in Electrum?===<br />
* Expert Mode only<br />
* Applies to "Receive" tab only (i.e. own wallet's addresses).<br />
<br />
The balance column indicates the amount of Bitcoins belonging to the given address.<br />
The individual balances add up to the total balance of your wallet.<br />
<br />
===What does the "Flag" column mean in Electrum?===<br />
* Expert Mode only<br />
* Applies to "Receive" tab only (i.e. own wallet's addresses).<br />
<br />
This column indicates certain properties of the different addresses:<br />
* C = [[#Change Addresses|Change address]] (without a "C" it means it is a [[#Normal Addresses|normal address]])<br />
* P = Prioritized address<br />
* F = Frozen address<br />
* I = [[#Imported Addresses|Imported address]]<br />
<br />
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]].<br />
<br />
===What do colors mean?===<br />
In the Receive tab:<br />
*green = prioritized<br />
*blue = frozen<br />
In the Contacts tab:<br />
*gray = alias<br />
<br />
==Troubleshooting==<br />
<br />
=== 'transaction rejected by memorypool' errors ===<br />
<br />
When you send a transaction, there is a delay before the Electrum client displays the transaction in its history.<br />
This is because the server polls bitcoind's memorypool every 10 seconds.<br />
<br />
If you create another transaction during this interval, during which the first tx is not displayed,<br />
then your client will pick the same coins again, and the transaction will be rejected as a [[Double-spending|double spend]].<br />
<br />
==External Links==<br />
* [http://ecdsa.org/electrum Electrum] project website<br />
* [https://gitorious.org/electrum Electrum] project source (gitorius)<br />
* [https://bitcointalk.org/index.php?topic=50936.msg950497#msg950497 Electrum Forum] - here this documentation was started</div>Michael Shttps://en.bitcoin.it/w/index.php?title=Electrum/Documentation&diff=29368Electrum/Documentation2012-08-03T23:10:41Z<p>Michael S: 2^6 is 64, not 1 Million. I confused 2^6 with 10^6 in the original text - now corrected!</p>
<hr />
<div>==Documentation of Electrum Bitcoin Client (Focus on the GUI)==<br />
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.<br />
<br />
More documentation, especially with regard to command line parameters, can be found at the parent page of this Wiki, i.e. [[Electrum|here]].<br />
<br />
===Version Info===<br />
Unless stated otherwise in particular sub-sections, the present state of this documentation is based on<br />
* '''Electrum version 0.58'''<br />
As this documentation gets updated, this "version info" can be updated, too!<br />
<br />
Later versions of Electrum may add new features or deviate from this description to some extend.<br />
<br />
===Open/Unclear Points===<br />
<br />
Discussions about unclear points should take place on the [[Talk:Electrum/Documentation|Discussion page.]]<br />
<br />
==What is a "Wallet" and a "Bitcoin Address"?==<br />
* (General, not specific to Electrum)<br />
<br />
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.<br />
<br />
Your wallet's balance is the sum of all Bitcoins of all your wallet's Bitcoin addresses.<br />
<br />
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.<br />
<br />
===Normal Addresses===<br />
* (More or less general, not too specific to Electrum)<br />
====How are New "Normal Addresses" Created for my Wallet?====<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
===Change Addresses===<br />
* (More or less general, not too specific to Electrum)<br />
====What is a "Change Address", and why is it useful?====<br />
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.<br />
<br />
'''How it works:'''<br />
<br />
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.<br />
<br />
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.<br />
<br />
Exception: If all the Bitcoins of "A" are sent to "B", there is no need for creating a change address "C".<br />
<br />
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".<br />
<br />
'''Why the concept of "change addresses" is useful:'''<br />
<br />
* 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.<br />
* It also conceals which output is the "spend" and which is the "change".<br />
<br />
===Imported Addresses===<br />
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.<br />
<br />
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"]].<br />
<br />
===Deterministic Wallet===<br />
====What is a "Deterministic Wallet" in Electrum?====<br />
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).<br />
<br />
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).<br />
This is a big advantage when it comes to making wallet backups:<br />
* ''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.<br />
* ''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!<br />
<br />
===Seed===<br />
====What is the "Seed" of a Deterministic Wallet in Electrum?====<br />
The Seed of a [[#Deterministic Wallet|deterministic wallet]] is a series of 128 random bits in Electrum.<br />
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.<br />
<br />
So there are 2^128 possible seeds for a deterministic wallet in Electrum.<br />
For comparison, the total number of Bitcoin addresses is 2^160, and the number of atoms on earth is 2^166.<br />
So there exists one Bitcoin address per 64 atoms on earth, and there exists one seed of Electrum wallets per 4.3 Billion Bitcoin addresses.<br />
(By the way: The number of atoms in the complete universe is estimated as 2^266).<br />
<br />
===What is the "Gap Limit"?===<br />
<br />
The gap limit is the maximal number of contiguous unused addresses in your deterministic sequence of addresses.<br />
<br />
If you recover your wallet from seed, you will notice that the gap limit is asked by the recovery dialog.<br />
It is used in order to decide when to stop the recovery procedure.<br />
<br />
If you need to have more receiving addresses in your wallet, you may increase your gap limit (expert mode).<br />
This, however, means that you will need to remember the new limit in order to be able to recover your wallet from seed.<br />
<br />
==More on the Electrum GUI==<br />
<br />
===Send tab and completions===<br />
<br />
The "pay to" input line does not only accept bitcoin addresses. You may type a label from your list of contacts, or an alias.<br />
<br />
Completions are available based on the labels of your addressbook.Example: <br />
<br />
[[Image:Electrum completion 0.png|450px]]<br />
[[Image:Electrum completion 1.png|450px]]<br />
<br />
===What does it mean to "Prioritize" or "Freeze" Addresses in Electrum?===<br />
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.<br />
<br />
* 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.<br />
* 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. <br />
<br />
The user can (de)prioritize or (un)freeze both [[#Normal Addresses|normal]] and [[#Change Addresses|change]] addresses.<br />
<br />
Note: Clearly, an address can not be "prioritized" and "frozen" at the same time.<br />
<br />
===What does the "Tx" column mean in Electrum?===<br />
* Expert Mode only<br />
* Applies to "Receive" tab (own wallet's addresses) and "Contacts" tab (foreing addresses).<br />
<br />
Tx stands for "Transaction"<br />
<br />
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).<br />
<br />
'''In the "Receive" tab (own addresses):'''<br />
<br />
The number in the Tx column indicates the total number of _incoming_ Bitcoin transactions that have ever been sent to this address.<br />
<br />
<br />
'''In the "Contacts" tab (foreign addresses):'''<br />
<br />
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<br />
<br />
===What does the "Balance" column mean in Electrum?===<br />
* Expert Mode only<br />
* Applies to "Receive" tab only (i.e. own wallet's addresses).<br />
<br />
The balance column indicates the amount of Bitcoins belonging to the given address.<br />
The individual balances add up to the total balance of your wallet.<br />
<br />
===What does the "Flag" column mean in Electrum?===<br />
* Expert Mode only<br />
* Applies to "Receive" tab only (i.e. own wallet's addresses).<br />
<br />
This column indicates certain properties of the different addresses:<br />
* C = [[#Change Addresses|Change address]] (without a "C" it means it is a [[#Normal Addresses|normal address]])<br />
* P = Prioritized address<br />
* F = Frozen address<br />
* I = [[#Imported Addresses|Imported address]]<br />
<br />
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]].<br />
<br />
===What do colors mean?===<br />
In the Receive tab:<br />
*green = prioritized<br />
*blue = frozen<br />
In the Contacts tab:<br />
*gray = alias<br />
<br />
==Troubleshooting==<br />
<br />
=== 'transaction rejected by memorypool' errors ===<br />
<br />
When you send a transaction, there is a delay before the Electrum client displays the transaction in its history.<br />
This is because the server polls bitcoind's memorypool every 10 seconds.<br />
<br />
If you create another transaction during this interval, during which the first tx is not displayed,<br />
then your client will pick the same coins again, and the transaction will be rejected as a [[Double-spending|double spend]].<br />
<br />
==External Links==<br />
* [http://ecdsa.org/electrum Electrum] project website<br />
* [https://gitorious.org/electrum Electrum] project source (gitorius)<br />
* [https://bitcointalk.org/index.php?topic=50936.msg950497#msg950497 Electrum Forum] - here this documentation was started</div>Michael Shttps://en.bitcoin.it/w/index.php?title=Electrum/Documentation&diff=27791Electrum/Documentation2012-06-12T23:39:03Z<p>Michael S: /* What is the "Gap Limit"? */ clarified: no danger of BTC loss when forgetting gap limit - can always recover from seed when setting a very large gap limit value</p>
<hr />
<div>==Documentation of Electrum Bitcoin Client (Focus on the GUI)==<br />
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.<br />
<br />
More documentation, especially with regard to command line parameters, can be found at the parent page of this Wiki, i.e. [[Electrum|here]].<br />
<br />
===Version Info===<br />
Unless stated otherwise in particular sub-sections, the present state of this documentation is based on<br />
* '''Electrum version 0.58'''<br />
As this documentation gets updated, this "version info" can be updated, too!<br />
<br />
Later versions of Electrum may add new features or deviate from this description to some extend.<br />
<br />
===Open/Unclear Points===<br />
Text in curly brackets {like this} means that the author(s) of this documentation are not really sure about this...<br />
<br />
--> other authors are welcome to correct/clarify<br />
<br />
==What is a "Wallet" and a "Bitcoin Address"?==<br />
* (General, not specific to Electrum)<br />
<br />
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.<br />
<br />
Your wallet's balance is the sum of all Bitcoins of all your wallet's Bitcoin addresses.<br />
<br />
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.<br />
<br />
===Normal Addresses===<br />
* (More or less general, not too specific to Electrum)<br />
====How are New "Normal Addresses" Created for my Wallet?====<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
===Change Addresses===<br />
* (More or less general, not too specific to Electrum)<br />
====What is a "Change Address", and why is it useful?====<br />
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.<br />
<br />
'''How it works:'''<br />
<br />
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.<br />
<br />
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.<br />
<br />
Exception: If all the Bitcoins of "A" are sent to "B", there is no need for creating a change address "C".<br />
<br />
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".<br />
<br />
'''Why the concept of "change addresses" is useful:'''<br />
<br />
* 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.<br />
* It also conceals which output is the "spend" and which is the "change".<br />
<br />
===Imported Addresses===<br />
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.<br />
<br />
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"]].<br />
<br />
===Deterministic Wallet===<br />
====What is a "Deterministic Wallet" in Electrum?====<br />
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).<br />
<br />
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).<br />
This is a big advantage when it comes to making wallet backups:<br />
* ''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.<br />
* ''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!<br />
<br />
===Seed===<br />
====What is the "Seed" of a Deterministic Wallet in Electrum?====<br />
The Seed of a [[#Deterministic Wallet|deterministic wallet]] is a series of 128 random bits in Electrum.<br />
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.<br />
<br />
So there are 2^128 possible seeds for a deterministic wallet in Electrum.<br />
For comparison, the total number of Bitcoin addresses is 2^160, and the number of atoms on earth is 2^166.<br />
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.<br />
(By the way: The number of atoms in the complete universe is estimated as 2^266).<br />
<br />
{<br />
<br />
Open Point: It is _not clear_ whether the algorithm of deterministic address generation is designed such that for any two seeds "S1" and "S2" (out of the 2^128 possible different seeds) the following condition holds true:<br />
* If 4.3 Billion (2^32 to be exact) new addresses are calculated from each S1 and from S2, does the algorithm guarantee that there will be no collision between the set of 2^32 addresses from S1 and the set of 2^32 addresses from S2?<br />
If this condition does not hold true, it needs to be clarified whether the use of deterministic wallets still bares an acceptably low probability of address collisions.<br />
<br />
}<br />
<br />
===What is the "Gap Limit"?===<br />
<br />
The gap limit is the maximal number of contiguous unused addresses in your deterministic sequence of addresses.<br />
<br />
If you recover your wallet from seed, you will notice that the gap limit is asked by the recovery dialog.<br />
It is used in order to decide when to stop the recovery procedure.<br />
<br />
If you need to have more receiving addresses in your wallet, you may increase your gap limit (expert mode).<br />
This, however, means that you will need to remember the new limit in order to be able to recover your wallet from seed.<br />
<br />
{<br />
<br />
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:<br />
* 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.<br />
* 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.<br />
<br />
}<br />
<br />
==More on the Electrum GUI==<br />
===What does it mean to "Prioritize" or "Freeze" Addresses in Electrum?===<br />
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.<br />
<br />
* 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.<br />
* 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. <br />
<br />
The user can (de)prioritize or (un)freeze both [[#Normal Addresses|normal]] and [[#Change Addresses|change]] addresses.<br />
<br />
Note: Clearly, an address can not be "prioritized" and "frozen" at the same time.<br />
<br />
===What does the "Tx" column mean in Electrum?===<br />
* Expert Mode only<br />
* Applies to "Receive" tab (own wallet's addresses) and "Contacts" tab (foreing addresses).<br />
<br />
Tx stands for {... ?? "Transaction"? "Transmission" ?? ...}<br />
<br />
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).<br />
<br />
'''In the "Receive" tab (own addresses):'''<br />
<br />
The number in the Tx column indicates the total number of _incoming_ Bitcoin transactions that have ever been sent to this address.<br />
<br />
{<br />
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.<br />
Does this "Tx" come from blockchain/blockexplorer terminology? Or why is it called "Tx" ("transmit") and not "Rx" ("receive")? To be clarified.<br />
}<br />
<br />
'''In the "Contacts" tab (foreign addresses):'''<br />
<br />
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<br />
<br />
===What does the "Balance" column mean in Electrum?===<br />
* Expert Mode only<br />
* Applies to "Receive" tab only (i.e. own wallet's addresses).<br />
<br />
The balance column indicates the amount of Bitcoins belonging to the given address.<br />
The individual balances add up to the total balance of your wallet.<br />
<br />
===What does the "Flag" column mean in Electrum?===<br />
* Expert Mode only<br />
* Applies to "Receive" tab only (i.e. own wallet's addresses).<br />
<br />
This column indicates certain properties of the different addresses:<br />
* C = [[#Change Addresses|Change address]] (without a "C" it means it is a [[#Normal Addresses|normal address]])<br />
* P = Prioritized address<br />
* F = Frozen address<br />
* I = [[#Imported Addresses|Imported address]]<br />
<br />
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]].<br />
<br />
===What do colors mean?===<br />
In the Receive tab:<br />
*green = prioritized<br />
*blue = frozen<br />
In the Contacts tab:<br />
*gray = alias<br />
<br />
==Troubleshooting==<br />
<br />
=== 'transaction rejected by memorypool' errors ===<br />
<br />
When you send a transaction, there is a delay before the Electrum client displays the transaction in its history.<br />
This is because the server polls bitcoind's memorypool every 10 seconds.<br />
<br />
If you create another transaction during this interval, during which the first tx is not displayed,<br />
then your client will pick the same coins again, and the transaction will be rejected as a double spend.<br />
<br />
<br />
<br />
==External Links==<br />
* [http://ecdsa.org/electrum Electrum] project website<br />
* [https://gitorious.org/electrum Electrum] project source (gitorius)<br />
* [https://bitcointalk.org/index.php?topic=50936.msg950497#msg950497 Electrum Forum] - here this documentation was started</div>Michael Shttps://en.bitcoin.it/w/index.php?title=Electrum/Documentation&diff=27790Electrum/Documentation2012-06-12T23:11:11Z<p>Michael S: /* Imported Addresses */ editorial</p>
<hr />
<div>==Documentation of Electrum Bitcoin Client (Focus on the GUI)==<br />
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.<br />
<br />
More documentation, especially with regard to command line parameters, can be found at the parent page of this Wiki, i.e. [[Electrum|here]].<br />
<br />
===Version Info===<br />
Unless stated otherwise in particular sub-sections, the present state of this documentation is based on<br />
* '''Electrum version 0.58'''<br />
As this documentation gets updated, this "version info" can be updated, too!<br />
<br />
Later versions of Electrum may add new features or deviate from this description to some extend.<br />
<br />
===Open/Unclear Points===<br />
Text in curly brackets {like this} means that the author(s) of this documentation are not really sure about this...<br />
<br />
--> other authors are welcome to correct/clarify<br />
<br />
==What is a "Wallet" and a "Bitcoin Address"?==<br />
* (General, not specific to Electrum)<br />
<br />
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.<br />
<br />
Your wallet's balance is the sum of all Bitcoins of all your wallet's Bitcoin addresses.<br />
<br />
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.<br />
<br />
===Normal Addresses===<br />
* (More or less general, not too specific to Electrum)<br />
====How are New "Normal Addresses" Created for my Wallet?====<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
===Change Addresses===<br />
* (More or less general, not too specific to Electrum)<br />
====What is a "Change Address", and why is it useful?====<br />
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.<br />
<br />
'''How it works:'''<br />
<br />
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.<br />
<br />
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.<br />
<br />
Exception: If all the Bitcoins of "A" are sent to "B", there is no need for creating a change address "C".<br />
<br />
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".<br />
<br />
'''Why the concept of "change addresses" is useful:'''<br />
<br />
* 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.<br />
* It also conceals which output is the "spend" and which is the "change".<br />
<br />
===Imported Addresses===<br />
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.<br />
<br />
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"]].<br />
<br />
===Deterministic Wallet===<br />
====What is a "Deterministic Wallet" in Electrum?====<br />
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).<br />
<br />
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).<br />
This is a big advantage when it comes to making wallet backups:<br />
* ''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.<br />
* ''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!<br />
<br />
===Seed===<br />
====What is the "Seed" of a Deterministic Wallet in Electrum?====<br />
The Seed of a [[#Deterministic Wallet|deterministic wallet]] is a series of 128 random bits in Electrum.<br />
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.<br />
<br />
So there are 2^128 possible seeds for a deterministic wallet in Electrum.<br />
For comparison, the total number of Bitcoin addresses is 2^160, and the number of atoms on earth is 2^166.<br />
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.<br />
(By the way: The number of atoms in the complete universe is estimated as 2^266).<br />
<br />
{<br />
<br />
Open Point: It is _not clear_ whether the algorithm of deterministic address generation is designed such that for any two seeds "S1" and "S2" (out of the 2^128 possible different seeds) the following condition holds true:<br />
* If 4.3 Billion (2^32 to be exact) new addresses are calculated from each S1 and from S2, does the algorithm guarantee that there will be no collision between the set of 2^32 addresses from S1 and the set of 2^32 addresses from S2?<br />
If this condition does not hold true, it needs to be clarified whether the use of deterministic wallets still bares an acceptably low probability of address collisions.<br />
<br />
}<br />
<br />
===What is the "Gap Limit"?===<br />
<br />
The gap limit is the maximal number of contiguous unused addresses in your deterministic sequence of addresses.<br />
<br />
If you recover your wallet from seed, you will notice that the gap limit is asked by the recovery dialog.<br />
It is used in order to decide when to stop the recovery procedure.<br />
<br />
If you need to have more receiving addresses in your wallet, you may increase your gap limit (expert mode).<br />
This, however, means that you will need to remember the new limit in order to be able to recover your wallet from seed.<br />
<br />
==More on the Electrum GUI==<br />
===What does it mean to "Prioritize" or "Freeze" Addresses in Electrum?===<br />
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.<br />
<br />
* 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.<br />
* 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. <br />
<br />
The user can (de)prioritize or (un)freeze both [[#Normal Addresses|normal]] and [[#Change Addresses|change]] addresses.<br />
<br />
Note: Clearly, an address can not be "prioritized" and "frozen" at the same time.<br />
<br />
===What does the "Tx" column mean in Electrum?===<br />
* Expert Mode only<br />
* Applies to "Receive" tab (own wallet's addresses) and "Contacts" tab (foreing addresses).<br />
<br />
Tx stands for {... ?? "Transaction"? "Transmission" ?? ...}<br />
<br />
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).<br />
<br />
'''In the "Receive" tab (own addresses):'''<br />
<br />
The number in the Tx column indicates the total number of _incoming_ Bitcoin transactions that have ever been sent to this address.<br />
<br />
{<br />
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.<br />
Does this "Tx" come from blockchain/blockexplorer terminology? Or why is it called "Tx" ("transmit") and not "Rx" ("receive")? To be clarified.<br />
}<br />
<br />
'''In the "Contacts" tab (foreign addresses):'''<br />
<br />
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<br />
<br />
===What does the "Balance" column mean in Electrum?===<br />
* Expert Mode only<br />
* Applies to "Receive" tab only (i.e. own wallet's addresses).<br />
<br />
The balance column indicates the amount of Bitcoins belonging to the given address.<br />
The individual balances add up to the total balance of your wallet.<br />
<br />
===What does the "Flag" column mean in Electrum?===<br />
* Expert Mode only<br />
* Applies to "Receive" tab only (i.e. own wallet's addresses).<br />
<br />
This column indicates certain properties of the different addresses:<br />
* C = [[#Change Addresses|Change address]] (without a "C" it means it is a [[#Normal Addresses|normal address]])<br />
* P = Prioritized address<br />
* F = Frozen address<br />
* I = [[#Imported Addresses|Imported address]]<br />
<br />
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]].<br />
<br />
===What do colors mean?===<br />
In the Receive tab:<br />
*green = prioritized<br />
*blue = frozen<br />
In the Contacts tab:<br />
*gray = alias<br />
<br />
==Troubleshooting==<br />
<br />
=== 'transaction rejected by memorypool' errors ===<br />
<br />
When you send a transaction, there is a delay before the Electrum client displays the transaction in its history.<br />
This is because the server polls bitcoind's memorypool every 10 seconds.<br />
<br />
If you create another transaction during this interval, during which the first tx is not displayed,<br />
then your client will pick the same coins again, and the transaction will be rejected as a double spend.<br />
<br />
<br />
<br />
==External Links==<br />
* [http://ecdsa.org/electrum Electrum] project website<br />
* [https://gitorious.org/electrum Electrum] project source (gitorius)<br />
* [https://bitcointalk.org/index.php?topic=50936.msg950497#msg950497 Electrum Forum] - here this documentation was started</div>Michael Shttps://en.bitcoin.it/w/index.php?title=Electrum/Documentation&diff=27789Electrum/Documentation2012-06-12T23:06:01Z<p>Michael S: /* Version Info */ editorial</p>
<hr />
<div>==Documentation of Electrum Bitcoin Client (Focus on the GUI)==<br />
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.<br />
<br />
More documentation, especially with regard to command line parameters, can be found at the parent page of this Wiki, i.e. [[Electrum|here]].<br />
<br />
===Version Info===<br />
Unless stated otherwise in particular sub-sections, the present state of this documentation is based on<br />
* '''Electrum version 0.58'''<br />
As this documentation gets updated, this "version info" can be updated, too!<br />
<br />
Later versions of Electrum may add new features or deviate from this description to some extend.<br />
<br />
===Open/Unclear Points===<br />
Text in curly brackets {like this} means that the author(s) of this documentation are not really sure about this...<br />
<br />
--> other authors are welcome to correct/clarify<br />
<br />
==What is a "Wallet" and a "Bitcoin Address"?==<br />
* (General, not specific to Electrum)<br />
<br />
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.<br />
<br />
Your wallet's balance is the sum of all Bitcoins of all your wallet's Bitcoin addresses.<br />
<br />
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.<br />
<br />
===Normal Addresses===<br />
* (More or less general, not too specific to Electrum)<br />
====How are New "Normal Addresses" Created for my Wallet?====<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
===Change Addresses===<br />
* (More or less general, not too specific to Electrum)<br />
====What is a "Change Address", and why is it useful?====<br />
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.<br />
<br />
'''How it works:'''<br />
<br />
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.<br />
<br />
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.<br />
<br />
Exception: If all the Bitcoins of "A" are sent to "B", there is no need for creating a change address "C".<br />
<br />
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".<br />
<br />
'''Why the concept of "change addresses" is useful:'''<br />
<br />
* 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.<br />
* It also conceals which output is the "spend" and which is the "change".<br />
<br />
===Imported Addresses===<br />
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 derived from your wallet's [[#Seed|seed]] and therefore need to be secured separately for a complete backup of your wallet.<br />
<br />
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"]].<br />
<br />
===Deterministic Wallet===<br />
====What is a "Deterministic Wallet" in Electrum?====<br />
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).<br />
<br />
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).<br />
This is a big advantage when it comes to making wallet backups:<br />
* ''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.<br />
* ''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!<br />
<br />
===Seed===<br />
====What is the "Seed" of a Deterministic Wallet in Electrum?====<br />
The Seed of a [[#Deterministic Wallet|deterministic wallet]] is a series of 128 random bits in Electrum.<br />
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.<br />
<br />
So there are 2^128 possible seeds for a deterministic wallet in Electrum.<br />
For comparison, the total number of Bitcoin addresses is 2^160, and the number of atoms on earth is 2^166.<br />
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.<br />
(By the way: The number of atoms in the complete universe is estimated as 2^266).<br />
<br />
{<br />
<br />
Open Point: It is _not clear_ whether the algorithm of deterministic address generation is designed such that for any two seeds "S1" and "S2" (out of the 2^128 possible different seeds) the following condition holds true:<br />
* If 4.3 Billion (2^32 to be exact) new addresses are calculated from each S1 and from S2, does the algorithm guarantee that there will be no collision between the set of 2^32 addresses from S1 and the set of 2^32 addresses from S2?<br />
If this condition does not hold true, it needs to be clarified whether the use of deterministic wallets still bares an acceptably low probability of address collisions.<br />
<br />
}<br />
<br />
===What is the "Gap Limit"?===<br />
<br />
The gap limit is the maximal number of contiguous unused addresses in your deterministic sequence of addresses.<br />
<br />
If you recover your wallet from seed, you will notice that the gap limit is asked by the recovery dialog.<br />
It is used in order to decide when to stop the recovery procedure.<br />
<br />
If you need to have more receiving addresses in your wallet, you may increase your gap limit (expert mode).<br />
This, however, means that you will need to remember the new limit in order to be able to recover your wallet from seed.<br />
<br />
==More on the Electrum GUI==<br />
===What does it mean to "Prioritize" or "Freeze" Addresses in Electrum?===<br />
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.<br />
<br />
* 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.<br />
* 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. <br />
<br />
The user can (de)prioritize or (un)freeze both [[#Normal Addresses|normal]] and [[#Change Addresses|change]] addresses.<br />
<br />
Note: Clearly, an address can not be "prioritized" and "frozen" at the same time.<br />
<br />
===What does the "Tx" column mean in Electrum?===<br />
* Expert Mode only<br />
* Applies to "Receive" tab (own wallet's addresses) and "Contacts" tab (foreing addresses).<br />
<br />
Tx stands for {... ?? "Transaction"? "Transmission" ?? ...}<br />
<br />
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).<br />
<br />
'''In the "Receive" tab (own addresses):'''<br />
<br />
The number in the Tx column indicates the total number of _incoming_ Bitcoin transactions that have ever been sent to this address.<br />
<br />
{<br />
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.<br />
Does this "Tx" come from blockchain/blockexplorer terminology? Or why is it called "Tx" ("transmit") and not "Rx" ("receive")? To be clarified.<br />
}<br />
<br />
'''In the "Contacts" tab (foreign addresses):'''<br />
<br />
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<br />
<br />
===What does the "Balance" column mean in Electrum?===<br />
* Expert Mode only<br />
* Applies to "Receive" tab only (i.e. own wallet's addresses).<br />
<br />
The balance column indicates the amount of Bitcoins belonging to the given address.<br />
The individual balances add up to the total balance of your wallet.<br />
<br />
===What does the "Flag" column mean in Electrum?===<br />
* Expert Mode only<br />
* Applies to "Receive" tab only (i.e. own wallet's addresses).<br />
<br />
This column indicates certain properties of the different addresses:<br />
* C = [[#Change Addresses|Change address]] (without a "C" it means it is a [[#Normal Addresses|normal address]])<br />
* P = Prioritized address<br />
* F = Frozen address<br />
* I = [[#Imported Addresses|Imported address]]<br />
<br />
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]].<br />
<br />
===What do colors mean?===<br />
In the Receive tab:<br />
*green = prioritized<br />
*blue = frozen<br />
In the Contacts tab:<br />
*gray = alias<br />
<br />
==Troubleshooting==<br />
<br />
=== 'transaction rejected by memorypool' errors ===<br />
<br />
When you send a transaction, there is a delay before the Electrum client displays the transaction in its history.<br />
This is because the server polls bitcoind's memorypool every 10 seconds.<br />
<br />
If you create another transaction during this interval, during which the first tx is not displayed,<br />
then your client will pick the same coins again, and the transaction will be rejected as a double spend.<br />
<br />
<br />
<br />
==External Links==<br />
* [http://ecdsa.org/electrum Electrum] project website<br />
* [https://gitorious.org/electrum Electrum] project source (gitorius)<br />
* [https://bitcointalk.org/index.php?topic=50936.msg950497#msg950497 Electrum Forum] - here this documentation was started</div>Michael Shttps://en.bitcoin.it/w/index.php?title=Electrum/Documentation&diff=27788Electrum/Documentation2012-06-12T23:04:31Z<p>Michael S: /* How to Read this Documentation */ editorial, headline level changed from level 2 to level 3</p>
<hr />
<div>==Documentation of Electrum Bitcoin Client (Focus on the GUI)==<br />
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.<br />
<br />
More documentation, especially with regard to command line parameters, can be found at the parent page of this Wiki, i.e. [[Electrum|here]].<br />
<br />
===Version Info===<br />
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).<br />
<br />
Later versions of Electrum may add new features or deviate from this description to some extend.<br />
<br />
===Open/Unclear Points===<br />
Text in curly brackets {like this} means that the author(s) of this documentation are not really sure about this...<br />
<br />
--> other authors are welcome to correct/clarify<br />
<br />
==What is a "Wallet" and a "Bitcoin Address"?==<br />
* (General, not specific to Electrum)<br />
<br />
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.<br />
<br />
Your wallet's balance is the sum of all Bitcoins of all your wallet's Bitcoin addresses.<br />
<br />
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.<br />
<br />
===Normal Addresses===<br />
* (More or less general, not too specific to Electrum)<br />
====How are New "Normal Addresses" Created for my Wallet?====<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
===Change Addresses===<br />
* (More or less general, not too specific to Electrum)<br />
====What is a "Change Address", and why is it useful?====<br />
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.<br />
<br />
'''How it works:'''<br />
<br />
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.<br />
<br />
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.<br />
<br />
Exception: If all the Bitcoins of "A" are sent to "B", there is no need for creating a change address "C".<br />
<br />
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".<br />
<br />
'''Why the concept of "change addresses" is useful:'''<br />
<br />
* 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.<br />
* It also conceals which output is the "spend" and which is the "change".<br />
<br />
===Imported Addresses===<br />
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 derived from your wallet's [[#Seed|seed]] and therefore need to be secured separately for a complete backup of your wallet.<br />
<br />
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"]].<br />
<br />
===Deterministic Wallet===<br />
====What is a "Deterministic Wallet" in Electrum?====<br />
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).<br />
<br />
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).<br />
This is a big advantage when it comes to making wallet backups:<br />
* ''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.<br />
* ''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!<br />
<br />
===Seed===<br />
====What is the "Seed" of a Deterministic Wallet in Electrum?====<br />
The Seed of a [[#Deterministic Wallet|deterministic wallet]] is a series of 128 random bits in Electrum.<br />
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.<br />
<br />
So there are 2^128 possible seeds for a deterministic wallet in Electrum.<br />
For comparison, the total number of Bitcoin addresses is 2^160, and the number of atoms on earth is 2^166.<br />
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.<br />
(By the way: The number of atoms in the complete universe is estimated as 2^266).<br />
<br />
{<br />
<br />
Open Point: It is _not clear_ whether the algorithm of deterministic address generation is designed such that for any two seeds "S1" and "S2" (out of the 2^128 possible different seeds) the following condition holds true:<br />
* If 4.3 Billion (2^32 to be exact) new addresses are calculated from each S1 and from S2, does the algorithm guarantee that there will be no collision between the set of 2^32 addresses from S1 and the set of 2^32 addresses from S2?<br />
If this condition does not hold true, it needs to be clarified whether the use of deterministic wallets still bares an acceptably low probability of address collisions.<br />
<br />
}<br />
<br />
===What is the "Gap Limit"?===<br />
<br />
The gap limit is the maximal number of contiguous unused addresses in your deterministic sequence of addresses.<br />
<br />
If you recover your wallet from seed, you will notice that the gap limit is asked by the recovery dialog.<br />
It is used in order to decide when to stop the recovery procedure.<br />
<br />
If you need to have more receiving addresses in your wallet, you may increase your gap limit (expert mode).<br />
This, however, means that you will need to remember the new limit in order to be able to recover your wallet from seed.<br />
<br />
==More on the Electrum GUI==<br />
===What does it mean to "Prioritize" or "Freeze" Addresses in Electrum?===<br />
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.<br />
<br />
* 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.<br />
* 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. <br />
<br />
The user can (de)prioritize or (un)freeze both [[#Normal Addresses|normal]] and [[#Change Addresses|change]] addresses.<br />
<br />
Note: Clearly, an address can not be "prioritized" and "frozen" at the same time.<br />
<br />
===What does the "Tx" column mean in Electrum?===<br />
* Expert Mode only<br />
* Applies to "Receive" tab (own wallet's addresses) and "Contacts" tab (foreing addresses).<br />
<br />
Tx stands for {... ?? "Transaction"? "Transmission" ?? ...}<br />
<br />
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).<br />
<br />
'''In the "Receive" tab (own addresses):'''<br />
<br />
The number in the Tx column indicates the total number of _incoming_ Bitcoin transactions that have ever been sent to this address.<br />
<br />
{<br />
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.<br />
Does this "Tx" come from blockchain/blockexplorer terminology? Or why is it called "Tx" ("transmit") and not "Rx" ("receive")? To be clarified.<br />
}<br />
<br />
'''In the "Contacts" tab (foreign addresses):'''<br />
<br />
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<br />
<br />
===What does the "Balance" column mean in Electrum?===<br />
* Expert Mode only<br />
* Applies to "Receive" tab only (i.e. own wallet's addresses).<br />
<br />
The balance column indicates the amount of Bitcoins belonging to the given address.<br />
The individual balances add up to the total balance of your wallet.<br />
<br />
===What does the "Flag" column mean in Electrum?===<br />
* Expert Mode only<br />
* Applies to "Receive" tab only (i.e. own wallet's addresses).<br />
<br />
This column indicates certain properties of the different addresses:<br />
* C = [[#Change Addresses|Change address]] (without a "C" it means it is a [[#Normal Addresses|normal address]])<br />
* P = Prioritized address<br />
* F = Frozen address<br />
* I = [[#Imported Addresses|Imported address]]<br />
<br />
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]].<br />
<br />
===What do colors mean?===<br />
In the Receive tab:<br />
*green = prioritized<br />
*blue = frozen<br />
In the Contacts tab:<br />
*gray = alias<br />
<br />
==Troubleshooting==<br />
<br />
=== 'transaction rejected by memorypool' errors ===<br />
<br />
When you send a transaction, there is a delay before the Electrum client displays the transaction in its history.<br />
This is because the server polls bitcoind's memorypool every 10 seconds.<br />
<br />
If you create another transaction during this interval, during which the first tx is not displayed,<br />
then your client will pick the same coins again, and the transaction will be rejected as a double spend.<br />
<br />
<br />
<br />
==External Links==<br />
* [http://ecdsa.org/electrum Electrum] project website<br />
* [https://gitorious.org/electrum Electrum] project source (gitorius)<br />
* [https://bitcointalk.org/index.php?topic=50936.msg950497#msg950497 Electrum Forum] - here this documentation was started</div>Michael Shttps://en.bitcoin.it/w/index.php?title=Electrum/Documentation&diff=27785Electrum/Documentation2012-06-12T23:02:33Z<p>Michael S: /* Documentation of Electrum Bitcoin Client (Focus on the GUI) */ added version info (v0.58)</p>
<hr />
<div>==Documentation of Electrum Bitcoin Client (Focus on the GUI)==<br />
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.<br />
<br />
More documentation, especially with regard to command line parameters, can be found at the parent page of this Wiki, i.e. [[Electrum|here]].<br />
<br />
===Version Info===<br />
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).<br />
<br />
Later versions of Electrum may add new features or deviate from this description to some extend.<br />
<br />
==How to Read this Documentation==<br />
* Text in curly brackets {like this} means that the author(s) of this documentation are not really sure about this... --> other people are welcome to correct/clarify<br />
<br />
==What is a "Wallet" and a "Bitcoin Address"?==<br />
* (General, not specific to Electrum)<br />
<br />
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.<br />
<br />
Your wallet's balance is the sum of all Bitcoins of all your wallet's Bitcoin addresses.<br />
<br />
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.<br />
<br />
===Normal Addresses===<br />
* (More or less general, not too specific to Electrum)<br />
====How are New "Normal Addresses" Created for my Wallet?====<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
===Change Addresses===<br />
* (More or less general, not too specific to Electrum)<br />
====What is a "Change Address", and why is it useful?====<br />
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.<br />
<br />
'''How it works:'''<br />
<br />
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.<br />
<br />
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.<br />
<br />
Exception: If all the Bitcoins of "A" are sent to "B", there is no need for creating a change address "C".<br />
<br />
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".<br />
<br />
'''Why the concept of "change addresses" is useful:'''<br />
<br />
* 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.<br />
* It also conceals which output is the "spend" and which is the "change".<br />
<br />
===Imported Addresses===<br />
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 derived from your wallet's [[#Seed|seed]] and therefore need to be secured separately for a complete backup of your wallet.<br />
<br />
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"]].<br />
<br />
===Deterministic Wallet===<br />
====What is a "Deterministic Wallet" in Electrum?====<br />
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).<br />
<br />
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).<br />
This is a big advantage when it comes to making wallet backups:<br />
* ''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.<br />
* ''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!<br />
<br />
===Seed===<br />
====What is the "Seed" of a Deterministic Wallet in Electrum?====<br />
The Seed of a [[#Deterministic Wallet|deterministic wallet]] is a series of 128 random bits in Electrum.<br />
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.<br />
<br />
So there are 2^128 possible seeds for a deterministic wallet in Electrum.<br />
For comparison, the total number of Bitcoin addresses is 2^160, and the number of atoms on earth is 2^166.<br />
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.<br />
(By the way: The number of atoms in the complete universe is estimated as 2^266).<br />
<br />
{<br />
<br />
Open Point: It is _not clear_ whether the algorithm of deterministic address generation is designed such that for any two seeds "S1" and "S2" (out of the 2^128 possible different seeds) the following condition holds true:<br />
* If 4.3 Billion (2^32 to be exact) new addresses are calculated from each S1 and from S2, does the algorithm guarantee that there will be no collision between the set of 2^32 addresses from S1 and the set of 2^32 addresses from S2?<br />
If this condition does not hold true, it needs to be clarified whether the use of deterministic wallets still bares an acceptably low probability of address collisions.<br />
<br />
}<br />
<br />
===What is the "Gap Limit"?===<br />
<br />
The gap limit is the maximal number of contiguous unused addresses in your deterministic sequence of addresses.<br />
<br />
If you recover your wallet from seed, you will notice that the gap limit is asked by the recovery dialog.<br />
It is used in order to decide when to stop the recovery procedure.<br />
<br />
If you need to have more receiving addresses in your wallet, you may increase your gap limit (expert mode).<br />
This, however, means that you will need to remember the new limit in order to be able to recover your wallet from seed.<br />
<br />
==More on the Electrum GUI==<br />
===What does it mean to "Prioritize" or "Freeze" Addresses in Electrum?===<br />
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.<br />
<br />
* 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.<br />
* 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. <br />
<br />
The user can (de)prioritize or (un)freeze both [[#Normal Addresses|normal]] and [[#Change Addresses|change]] addresses.<br />
<br />
Note: Clearly, an address can not be "prioritized" and "frozen" at the same time.<br />
<br />
===What does the "Tx" column mean in Electrum?===<br />
* Expert Mode only<br />
* Applies to "Receive" tab (own wallet's addresses) and "Contacts" tab (foreing addresses).<br />
<br />
Tx stands for {... ?? "Transaction"? "Transmission" ?? ...}<br />
<br />
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).<br />
<br />
'''In the "Receive" tab (own addresses):'''<br />
<br />
The number in the Tx column indicates the total number of _incoming_ Bitcoin transactions that have ever been sent to this address.<br />
<br />
{<br />
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.<br />
Does this "Tx" come from blockchain/blockexplorer terminology? Or why is it called "Tx" ("transmit") and not "Rx" ("receive")? To be clarified.<br />
}<br />
<br />
'''In the "Contacts" tab (foreign addresses):'''<br />
<br />
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<br />
<br />
===What does the "Balance" column mean in Electrum?===<br />
* Expert Mode only<br />
* Applies to "Receive" tab only (i.e. own wallet's addresses).<br />
<br />
The balance column indicates the amount of Bitcoins belonging to the given address.<br />
The individual balances add up to the total balance of your wallet.<br />
<br />
===What does the "Flag" column mean in Electrum?===<br />
* Expert Mode only<br />
* Applies to "Receive" tab only (i.e. own wallet's addresses).<br />
<br />
This column indicates certain properties of the different addresses:<br />
* C = [[#Change Addresses|Change address]] (without a "C" it means it is a [[#Normal Addresses|normal address]])<br />
* P = Prioritized address<br />
* F = Frozen address<br />
* I = [[#Imported Addresses|Imported address]]<br />
<br />
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]].<br />
<br />
===What do colors mean?===<br />
In the Receive tab:<br />
*green = prioritized<br />
*blue = frozen<br />
In the Contacts tab:<br />
*gray = alias<br />
<br />
==Troubleshooting==<br />
<br />
=== 'transaction rejected by memorypool' errors ===<br />
<br />
When you send a transaction, there is a delay before the Electrum client displays the transaction in its history.<br />
This is because the server polls bitcoind's memorypool every 10 seconds.<br />
<br />
If you create another transaction during this interval, during which the first tx is not displayed,<br />
then your client will pick the same coins again, and the transaction will be rejected as a double spend.<br />
<br />
<br />
<br />
==External Links==<br />
* [http://ecdsa.org/electrum Electrum] project website<br />
* [https://gitorious.org/electrum Electrum] project source (gitorius)<br />
* [https://bitcointalk.org/index.php?topic=50936.msg950497#msg950497 Electrum Forum] - here this documentation was started</div>Michael Shttps://en.bitcoin.it/w/index.php?title=Electrum/Documentation&diff=27780Electrum/Documentation2012-06-12T22:49:06Z<p>Michael S: /* How are New "Normal Addresses" Created for my Wallet? */ corrected description of how the GUI creates new addresses (v0.58)</p>
<hr />
<div>==Documentation of Electrum Bitcoin Client (Focus on the GUI)==<br />
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.<br />
<br />
More documentation, especially with regard to command line parameters, can be found at the parent page of this Wiki, i.e. [[Electrum|here]].<br />
<br />
==How to Read this Documentation==<br />
* Text in curly brackets {like this} means that the author(s) of this documentation are not really sure about this... --> other people are welcome to correct/clarify<br />
<br />
==What is a "Wallet" and a "Bitcoin Address"?==<br />
* (General, not specific to Electrum)<br />
<br />
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.<br />
<br />
Your wallet's balance is the sum of all Bitcoins of all your wallet's Bitcoin addresses.<br />
<br />
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.<br />
<br />
===Normal Addresses===<br />
* (More or less general, not too specific to Electrum)<br />
====How are New "Normal Addresses" Created for my Wallet?====<br />
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.<br />
<br />
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.<br />
<br />
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.<br />
<br />
===Change Addresses===<br />
* (More or less general, not too specific to Electrum)<br />
====What is a "Change Address", and why is it useful?====<br />
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.<br />
<br />
'''How it works:'''<br />
<br />
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.<br />
<br />
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.<br />
<br />
Exception: If all the Bitcoins of "A" are sent to "B", there is no need for creating a change address "C".<br />
<br />
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".<br />
<br />
'''Why the concept of "change addresses" is useful:'''<br />
<br />
* 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.<br />
* It also conceals which output is the "spend" and which is the "change".<br />
<br />
===Imported Addresses===<br />
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 derived from your wallet's [[#Seed|seed]] and therefore need to be secured separately for a complete backup of your wallet.<br />
<br />
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"]].<br />
<br />
===Deterministic Wallet===<br />
====What is a "Deterministic Wallet" in Electrum?====<br />
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).<br />
<br />
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).<br />
This is a big advantage when it comes to making wallet backups:<br />
* ''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.<br />
* ''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!<br />
<br />
===Seed===<br />
====What is the "Seed" of a Deterministic Wallet in Electrum?====<br />
The Seed of a [[#Deterministic Wallet|deterministic wallet]] is a series of 128 random bits in Electrum.<br />
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.<br />
<br />
So there are 2^128 possible seeds for a deterministic wallet in Electrum.<br />
For comparison, the total number of Bitcoin addresses is 2^160, and the number of atoms on earth is 2^166.<br />
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.<br />
(By the way: The number of atoms in the complete universe is estimated as 2^266).<br />
<br />
{<br />
<br />
Open Point: It is _not clear_ whether the algorithm of deterministic address generation is designed such that for any two seeds "S1" and "S2" (out of the 2^128 possible different seeds) the following condition holds true:<br />
* If 4.3 Billion (2^32 to be exact) new addresses are calculated from each S1 and from S2, does the algorithm guarantee that there will be no collision between the set of 2^32 addresses from S1 and the set of 2^32 addresses from S2?<br />
If this condition does not hold true, it needs to be clarified whether the use of deterministic wallets still bares an acceptably low probability of address collisions.<br />
<br />
}<br />
<br />
===What is the "Gap Limit"?===<br />
<br />
The gap limit is the maximal number of contiguous unused addresses in your deterministic sequence of addresses.<br />
<br />
If you recover your wallet from seed, you will notice that the gap limit is asked by the recovery dialog.<br />
It is used in order to decide when to stop the recovery procedure.<br />
<br />
If you need to have more receiving addresses in your wallet, you may increase your gap limit (expert mode).<br />
This, however, means that you will need to remember the new limit in order to be able to recover your wallet from seed.<br />
<br />
==More on the Electrum GUI==<br />
===What does it mean to "Prioritize" or "Freeze" Addresses in Electrum?===<br />
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.<br />
<br />
* 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.<br />
* 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. <br />
<br />
The user can (de)prioritize or (un)freeze both [[#Normal Addresses|normal]] and [[#Change Addresses|change]] addresses.<br />
<br />
Note: Clearly, an address can not be "prioritized" and "frozen" at the same time.<br />
<br />
===What does the "Tx" column mean in Electrum?===<br />
* Expert Mode only<br />
* Applies to "Receive" tab (own wallet's addresses) and "Contacts" tab (foreing addresses).<br />
<br />
Tx stands for {... ?? "Transaction"? "Transmission" ?? ...}<br />
<br />
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).<br />
<br />
'''In the "Receive" tab (own addresses):'''<br />
<br />
The number in the Tx column indicates the total number of _incoming_ Bitcoin transactions that have ever been sent to this address.<br />
<br />
{<br />
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.<br />
Does this "Tx" come from blockchain/blockexplorer terminology? Or why is it called "Tx" ("transmit") and not "Rx" ("receive")? To be clarified.<br />
}<br />
<br />
'''In the "Contacts" tab (foreign addresses):'''<br />
<br />
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<br />
<br />
===What does the "Balance" column mean in Electrum?===<br />
* Expert Mode only<br />
* Applies to "Receive" tab only (i.e. own wallet's addresses).<br />
<br />
The balance column indicates the amount of Bitcoins belonging to the given address.<br />
The individual balances add up to the total balance of your wallet.<br />
<br />
===What does the "Flag" column mean in Electrum?===<br />
* Expert Mode only<br />
* Applies to "Receive" tab only (i.e. own wallet's addresses).<br />
<br />
This column indicates certain properties of the different addresses:<br />
* C = [[#Change Addresses|Change address]] (without a "C" it means it is a [[#Normal Addresses|normal address]])<br />
* P = Prioritized address<br />
* F = Frozen address<br />
* I = [[#Imported Addresses|Imported address]]<br />
<br />
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]].<br />
<br />
===What do colors mean?===<br />
In the Receive tab:<br />
*green = prioritized<br />
*blue = frozen<br />
In the Contacts tab:<br />
*gray = alias<br />
<br />
==Troubleshooting==<br />
<br />
=== 'transaction rejected by memorypool' errors ===<br />
<br />
When you send a transaction, there is a delay before the Electrum client displays the transaction in its history.<br />
This is because the server polls bitcoind's memorypool every 10 seconds.<br />
<br />
If you create another transaction during this interval, during which the first tx is not displayed,<br />
then your client will pick the same coins again, and the transaction will be rejected as a double spend.<br />
<br />
<br />
<br />
==External Links==<br />
* [http://ecdsa.org/electrum Electrum] project website<br />
* [https://gitorious.org/electrum Electrum] project source (gitorius)<br />
* [https://bitcointalk.org/index.php?topic=50936.msg950497#msg950497 Electrum Forum] - here this documentation was started</div>Michael Shttps://en.bitcoin.it/w/index.php?title=Electrum/Documentation&diff=27778Electrum/Documentation2012-06-12T22:35:09Z<p>Michael S: /* What does the "Flag" column mean in Electrum? */ added "Expert Mode only"</p>
<hr />
<div>==Documentation of Electrum Bitcoin Client (Focus on the GUI)==<br />
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.<br />
<br />
More documentation, especially with regard to command line parameters, can be found at the parent page of this Wiki, i.e. [[Electrum|here]].<br />
<br />
==How to Read this Documentation==<br />
* Text in curly brackets {like this} means that the author(s) of this documentation are not really sure about this... --> other people are welcome to correct/clarify<br />
<br />
==What is a "Wallet" and a "Bitcoin Address"?==<br />
* (General, not specific to Electrum)<br />
<br />
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.<br />
<br />
Your wallet's balance is the sum of all Bitcoins of all your wallet's Bitcoin addresses.<br />
<br />
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.<br />
<br />
===Normal Addresses===<br />
* (More or less general, not too specific to Electrum)<br />
====How are New "Normal Addresses" Created for my Wallet?====<br />
The Bitcoin client (e.g. Electrum) allows you to trigger manually the generation of a new Bitcoin address. You typically want to create a new address when you want to receive Bitcoins from somebody and do not want to use any of the wallet's present addresses that have already been used for earlier Bitcoin transfers, for privacy reasons (note that all transfers are publically visible in the blockchain).<br />
<br />
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.<br />
<br />
===Change Addresses===<br />
* (More or less general, not too specific to Electrum)<br />
====What is a "Change Address", and why is it useful?====<br />
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.<br />
<br />
'''How it works:'''<br />
<br />
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.<br />
<br />
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.<br />
<br />
Exception: If all the Bitcoins of "A" are sent to "B", there is no need for creating a change address "C".<br />
<br />
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".<br />
<br />
'''Why the concept of "change addresses" is useful:'''<br />
<br />
* 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.<br />
* It also conceals which output is the "spend" and which is the "change".<br />
<br />
===Imported Addresses===<br />
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 derived from your wallet's [[#Seed|seed]] and therefore need to be secured separately for a complete backup of your wallet.<br />
<br />
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"]].<br />
<br />
===Deterministic Wallet===<br />
====What is a "Deterministic Wallet" in Electrum?====<br />
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).<br />
<br />
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).<br />
This is a big advantage when it comes to making wallet backups:<br />
* ''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.<br />
* ''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!<br />
<br />
===Seed===<br />
====What is the "Seed" of a Deterministic Wallet in Electrum?====<br />
The Seed of a [[#Deterministic Wallet|deterministic wallet]] is a series of 128 random bits in Electrum.<br />
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.<br />
<br />
So there are 2^128 possible seeds for a deterministic wallet in Electrum.<br />
For comparison, the total number of Bitcoin addresses is 2^160, and the number of atoms on earth is 2^166.<br />
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.<br />
(By the way: The number of atoms in the complete universe is estimated as 2^266).<br />
<br />
{<br />
<br />
Open Point: It is _not clear_ whether the algorithm of deterministic address generation is designed such that for any two seeds "S1" and "S2" (out of the 2^128 possible different seeds) the following condition holds true:<br />
* If 4.3 Billion (2^32 to be exact) new addresses are calculated from each S1 and from S2, does the algorithm guarantee that there will be no collision between the set of 2^32 addresses from S1 and the set of 2^32 addresses from S2?<br />
If this condition does not hold true, it needs to be clarified whether the use of deterministic wallets still bares an acceptably low probability of address collisions.<br />
<br />
}<br />
<br />
===What is the "Gap Limit"?===<br />
<br />
The gap limit is the maximal number of contiguous unused addresses in your deterministic sequence of addresses.<br />
<br />
If you recover your wallet from seed, you will notice that the gap limit is asked by the recovery dialog.<br />
It is used in order to decide when to stop the recovery procedure.<br />
<br />
If you need to have more receiving addresses in your wallet, you may increase your gap limit (expert mode).<br />
This, however, means that you will need to remember the new limit in order to be able to recover your wallet from seed.<br />
<br />
==More on the Electrum GUI==<br />
===What does it mean to "Prioritize" or "Freeze" Addresses in Electrum?===<br />
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.<br />
<br />
* 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.<br />
* 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. <br />
<br />
The user can (de)prioritize or (un)freeze both [[#Normal Addresses|normal]] and [[#Change Addresses|change]] addresses.<br />
<br />
Note: Clearly, an address can not be "prioritized" and "frozen" at the same time.<br />
<br />
===What does the "Tx" column mean in Electrum?===<br />
* Expert Mode only<br />
* Applies to "Receive" tab (own wallet's addresses) and "Contacts" tab (foreing addresses).<br />
<br />
Tx stands for {... ?? "Transaction"? "Transmission" ?? ...}<br />
<br />
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).<br />
<br />
'''In the "Receive" tab (own addresses):'''<br />
<br />
The number in the Tx column indicates the total number of _incoming_ Bitcoin transactions that have ever been sent to this address.<br />
<br />
{<br />
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.<br />
Does this "Tx" come from blockchain/blockexplorer terminology? Or why is it called "Tx" ("transmit") and not "Rx" ("receive")? To be clarified.<br />
}<br />
<br />
'''In the "Contacts" tab (foreign addresses):'''<br />
<br />
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<br />
<br />
===What does the "Balance" column mean in Electrum?===<br />
* Expert Mode only<br />
* Applies to "Receive" tab only (i.e. own wallet's addresses).<br />
<br />
The balance column indicates the amount of Bitcoins belonging to the given address.<br />
The individual balances add up to the total balance of your wallet.<br />
<br />
===What does the "Flag" column mean in Electrum?===<br />
* Expert Mode only<br />
* Applies to "Receive" tab only (i.e. own wallet's addresses).<br />
<br />
This column indicates certain properties of the different addresses:<br />
* C = [[#Change Addresses|Change address]] (without a "C" it means it is a [[#Normal Addresses|normal address]])<br />
* P = Prioritized address<br />
* F = Frozen address<br />
* I = [[#Imported Addresses|Imported address]]<br />
<br />
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]].<br />
<br />
===What do colors mean?===<br />
In the Receive tab:<br />
*green = prioritized<br />
*blue = frozen<br />
In the Contacts tab:<br />
*gray = alias<br />
<br />
==Troubleshooting==<br />
<br />
=== 'transaction rejected by memorypool' errors ===<br />
<br />
When you send a transaction, there is a delay before the Electrum client displays the transaction in its history.<br />
This is because the server polls bitcoind's memorypool every 10 seconds.<br />
<br />
If you create another transaction during this interval, during which the first tx is not displayed,<br />
then your client will pick the same coins again, and the transaction will be rejected as a double spend.<br />
<br />
<br />
<br />
==External Links==<br />
* [http://ecdsa.org/electrum Electrum] project website<br />
* [https://gitorious.org/electrum Electrum] project source (gitorius)<br />
* [https://bitcointalk.org/index.php?topic=50936.msg950497#msg950497 Electrum Forum] - here this documentation was started</div>Michael Shttps://en.bitcoin.it/w/index.php?title=Electrum/Documentation&diff=27777Electrum/Documentation2012-06-12T22:34:38Z<p>Michael S: /* What does the "Balance" column mean in Electrum? */ added "Expert Mode only"</p>
<hr />
<div>==Documentation of Electrum Bitcoin Client (Focus on the GUI)==<br />
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.<br />
<br />
More documentation, especially with regard to command line parameters, can be found at the parent page of this Wiki, i.e. [[Electrum|here]].<br />
<br />
==How to Read this Documentation==<br />
* Text in curly brackets {like this} means that the author(s) of this documentation are not really sure about this... --> other people are welcome to correct/clarify<br />
<br />
==What is a "Wallet" and a "Bitcoin Address"?==<br />
* (General, not specific to Electrum)<br />
<br />
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.<br />
<br />
Your wallet's balance is the sum of all Bitcoins of all your wallet's Bitcoin addresses.<br />
<br />
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.<br />
<br />
===Normal Addresses===<br />
* (More or less general, not too specific to Electrum)<br />
====How are New "Normal Addresses" Created for my Wallet?====<br />
The Bitcoin client (e.g. Electrum) allows you to trigger manually the generation of a new Bitcoin address. You typically want to create a new address when you want to receive Bitcoins from somebody and do not want to use any of the wallet's present addresses that have already been used for earlier Bitcoin transfers, for privacy reasons (note that all transfers are publically visible in the blockchain).<br />
<br />
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.<br />
<br />
===Change Addresses===<br />
* (More or less general, not too specific to Electrum)<br />
====What is a "Change Address", and why is it useful?====<br />
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.<br />
<br />
'''How it works:'''<br />
<br />
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.<br />
<br />
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.<br />
<br />
Exception: If all the Bitcoins of "A" are sent to "B", there is no need for creating a change address "C".<br />
<br />
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".<br />
<br />
'''Why the concept of "change addresses" is useful:'''<br />
<br />
* 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.<br />
* It also conceals which output is the "spend" and which is the "change".<br />
<br />
===Imported Addresses===<br />
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 derived from your wallet's [[#Seed|seed]] and therefore need to be secured separately for a complete backup of your wallet.<br />
<br />
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"]].<br />
<br />
===Deterministic Wallet===<br />
====What is a "Deterministic Wallet" in Electrum?====<br />
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).<br />
<br />
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).<br />
This is a big advantage when it comes to making wallet backups:<br />
* ''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.<br />
* ''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!<br />
<br />
===Seed===<br />
====What is the "Seed" of a Deterministic Wallet in Electrum?====<br />
The Seed of a [[#Deterministic Wallet|deterministic wallet]] is a series of 128 random bits in Electrum.<br />
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.<br />
<br />
So there are 2^128 possible seeds for a deterministic wallet in Electrum.<br />
For comparison, the total number of Bitcoin addresses is 2^160, and the number of atoms on earth is 2^166.<br />
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.<br />
(By the way: The number of atoms in the complete universe is estimated as 2^266).<br />
<br />
{<br />
<br />
Open Point: It is _not clear_ whether the algorithm of deterministic address generation is designed such that for any two seeds "S1" and "S2" (out of the 2^128 possible different seeds) the following condition holds true:<br />
* If 4.3 Billion (2^32 to be exact) new addresses are calculated from each S1 and from S2, does the algorithm guarantee that there will be no collision between the set of 2^32 addresses from S1 and the set of 2^32 addresses from S2?<br />
If this condition does not hold true, it needs to be clarified whether the use of deterministic wallets still bares an acceptably low probability of address collisions.<br />
<br />
}<br />
<br />
===What is the "Gap Limit"?===<br />
<br />
The gap limit is the maximal number of contiguous unused addresses in your deterministic sequence of addresses.<br />
<br />
If you recover your wallet from seed, you will notice that the gap limit is asked by the recovery dialog.<br />
It is used in order to decide when to stop the recovery procedure.<br />
<br />
If you need to have more receiving addresses in your wallet, you may increase your gap limit (expert mode).<br />
This, however, means that you will need to remember the new limit in order to be able to recover your wallet from seed.<br />
<br />
==More on the Electrum GUI==<br />
===What does it mean to "Prioritize" or "Freeze" Addresses in Electrum?===<br />
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.<br />
<br />
* 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.<br />
* 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. <br />
<br />
The user can (de)prioritize or (un)freeze both [[#Normal Addresses|normal]] and [[#Change Addresses|change]] addresses.<br />
<br />
Note: Clearly, an address can not be "prioritized" and "frozen" at the same time.<br />
<br />
===What does the "Tx" column mean in Electrum?===<br />
* Expert Mode only<br />
* Applies to "Receive" tab (own wallet's addresses) and "Contacts" tab (foreing addresses).<br />
<br />
Tx stands for {... ?? "Transaction"? "Transmission" ?? ...}<br />
<br />
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).<br />
<br />
'''In the "Receive" tab (own addresses):'''<br />
<br />
The number in the Tx column indicates the total number of _incoming_ Bitcoin transactions that have ever been sent to this address.<br />
<br />
{<br />
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.<br />
Does this "Tx" come from blockchain/blockexplorer terminology? Or why is it called "Tx" ("transmit") and not "Rx" ("receive")? To be clarified.<br />
}<br />
<br />
'''In the "Contacts" tab (foreign addresses):'''<br />
<br />
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<br />
<br />
===What does the "Balance" column mean in Electrum?===<br />
* Expert Mode only<br />
* Applies to "Receive" tab only (i.e. own wallet's addresses).<br />
<br />
The balance column indicates the amount of Bitcoins belonging to the given address.<br />
The individual balances add up to the total balance of your wallet.<br />
<br />
===What does the "Flag" column mean in Electrum?===<br />
* Applies to "Receive" tab only (i.e. own wallet's addresses).<br />
<br />
This column indicates certain properties of the different addresses:<br />
* C = [[#Change Addresses|Change address]] (without a "C" it means it is a [[#Normal Addresses|normal address]])<br />
* P = Prioritized address<br />
* F = Frozen address<br />
* I = [[#Imported Addresses|Imported address]]<br />
<br />
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]].<br />
<br />
===What do colors mean?===<br />
In the Receive tab:<br />
*green = prioritized<br />
*blue = frozen<br />
In the Contacts tab:<br />
*gray = alias<br />
<br />
==Troubleshooting==<br />
<br />
=== 'transaction rejected by memorypool' errors ===<br />
<br />
When you send a transaction, there is a delay before the Electrum client displays the transaction in its history.<br />
This is because the server polls bitcoind's memorypool every 10 seconds.<br />
<br />
If you create another transaction during this interval, during which the first tx is not displayed,<br />
then your client will pick the same coins again, and the transaction will be rejected as a double spend.<br />
<br />
<br />
<br />
==External Links==<br />
* [http://ecdsa.org/electrum Electrum] project website<br />
* [https://gitorious.org/electrum Electrum] project source (gitorius)<br />
* [https://bitcointalk.org/index.php?topic=50936.msg950497#msg950497 Electrum Forum] - here this documentation was started</div>Michael Shttps://en.bitcoin.it/w/index.php?title=Electrum/Documentation&diff=27776Electrum/Documentation2012-06-12T22:34:18Z<p>Michael S: /* What does the "Tx" column mean in Electrum? */ added "expert mode only"</p>
<hr />
<div>==Documentation of Electrum Bitcoin Client (Focus on the GUI)==<br />
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.<br />
<br />
More documentation, especially with regard to command line parameters, can be found at the parent page of this Wiki, i.e. [[Electrum|here]].<br />
<br />
==How to Read this Documentation==<br />
* Text in curly brackets {like this} means that the author(s) of this documentation are not really sure about this... --> other people are welcome to correct/clarify<br />
<br />
==What is a "Wallet" and a "Bitcoin Address"?==<br />
* (General, not specific to Electrum)<br />
<br />
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.<br />
<br />
Your wallet's balance is the sum of all Bitcoins of all your wallet's Bitcoin addresses.<br />
<br />
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.<br />
<br />
===Normal Addresses===<br />
* (More or less general, not too specific to Electrum)<br />
====How are New "Normal Addresses" Created for my Wallet?====<br />
The Bitcoin client (e.g. Electrum) allows you to trigger manually the generation of a new Bitcoin address. You typically want to create a new address when you want to receive Bitcoins from somebody and do not want to use any of the wallet's present addresses that have already been used for earlier Bitcoin transfers, for privacy reasons (note that all transfers are publically visible in the blockchain).<br />
<br />
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.<br />
<br />
===Change Addresses===<br />
* (More or less general, not too specific to Electrum)<br />
====What is a "Change Address", and why is it useful?====<br />
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.<br />
<br />
'''How it works:'''<br />
<br />
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.<br />
<br />
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.<br />
<br />
Exception: If all the Bitcoins of "A" are sent to "B", there is no need for creating a change address "C".<br />
<br />
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".<br />
<br />
'''Why the concept of "change addresses" is useful:'''<br />
<br />
* 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.<br />
* It also conceals which output is the "spend" and which is the "change".<br />
<br />
===Imported Addresses===<br />
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 derived from your wallet's [[#Seed|seed]] and therefore need to be secured separately for a complete backup of your wallet.<br />
<br />
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"]].<br />
<br />
===Deterministic Wallet===<br />
====What is a "Deterministic Wallet" in Electrum?====<br />
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).<br />
<br />
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).<br />
This is a big advantage when it comes to making wallet backups:<br />
* ''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.<br />
* ''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!<br />
<br />
===Seed===<br />
====What is the "Seed" of a Deterministic Wallet in Electrum?====<br />
The Seed of a [[#Deterministic Wallet|deterministic wallet]] is a series of 128 random bits in Electrum.<br />
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.<br />
<br />
So there are 2^128 possible seeds for a deterministic wallet in Electrum.<br />
For comparison, the total number of Bitcoin addresses is 2^160, and the number of atoms on earth is 2^166.<br />
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.<br />
(By the way: The number of atoms in the complete universe is estimated as 2^266).<br />
<br />
{<br />
<br />
Open Point: It is _not clear_ whether the algorithm of deterministic address generation is designed such that for any two seeds "S1" and "S2" (out of the 2^128 possible different seeds) the following condition holds true:<br />
* If 4.3 Billion (2^32 to be exact) new addresses are calculated from each S1 and from S2, does the algorithm guarantee that there will be no collision between the set of 2^32 addresses from S1 and the set of 2^32 addresses from S2?<br />
If this condition does not hold true, it needs to be clarified whether the use of deterministic wallets still bares an acceptably low probability of address collisions.<br />
<br />
}<br />
<br />
===What is the "Gap Limit"?===<br />
<br />
The gap limit is the maximal number of contiguous unused addresses in your deterministic sequence of addresses.<br />
<br />
If you recover your wallet from seed, you will notice that the gap limit is asked by the recovery dialog.<br />
It is used in order to decide when to stop the recovery procedure.<br />
<br />
If you need to have more receiving addresses in your wallet, you may increase your gap limit (expert mode).<br />
This, however, means that you will need to remember the new limit in order to be able to recover your wallet from seed.<br />
<br />
==More on the Electrum GUI==<br />
===What does it mean to "Prioritize" or "Freeze" Addresses in Electrum?===<br />
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.<br />
<br />
* 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.<br />
* 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. <br />
<br />
The user can (de)prioritize or (un)freeze both [[#Normal Addresses|normal]] and [[#Change Addresses|change]] addresses.<br />
<br />
Note: Clearly, an address can not be "prioritized" and "frozen" at the same time.<br />
<br />
===What does the "Tx" column mean in Electrum?===<br />
* Expert Mode only<br />
* Applies to "Receive" tab (own wallet's addresses) and "Contacts" tab (foreing addresses).<br />
<br />
Tx stands for {... ?? "Transaction"? "Transmission" ?? ...}<br />
<br />
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).<br />
<br />
'''In the "Receive" tab (own addresses):'''<br />
<br />
The number in the Tx column indicates the total number of _incoming_ Bitcoin transactions that have ever been sent to this address.<br />
<br />
{<br />
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.<br />
Does this "Tx" come from blockchain/blockexplorer terminology? Or why is it called "Tx" ("transmit") and not "Rx" ("receive")? To be clarified.<br />
}<br />
<br />
'''In the "Contacts" tab (foreign addresses):'''<br />
<br />
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<br />
<br />
===What does the "Balance" column mean in Electrum?===<br />
* Applies to "Receive" tab only (i.e. own wallet's addresses).<br />
<br />
The balance column indicates the amount of Bitcoins belonging to the given address.<br />
The individual balances add up to the total balance of your wallet.<br />
<br />
===What does the "Flag" column mean in Electrum?===<br />
* Applies to "Receive" tab only (i.e. own wallet's addresses).<br />
<br />
This column indicates certain properties of the different addresses:<br />
* C = [[#Change Addresses|Change address]] (without a "C" it means it is a [[#Normal Addresses|normal address]])<br />
* P = Prioritized address<br />
* F = Frozen address<br />
* I = [[#Imported Addresses|Imported address]]<br />
<br />
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]].<br />
<br />
===What do colors mean?===<br />
In the Receive tab:<br />
*green = prioritized<br />
*blue = frozen<br />
In the Contacts tab:<br />
*gray = alias<br />
<br />
==Troubleshooting==<br />
<br />
=== 'transaction rejected by memorypool' errors ===<br />
<br />
When you send a transaction, there is a delay before the Electrum client displays the transaction in its history.<br />
This is because the server polls bitcoind's memorypool every 10 seconds.<br />
<br />
If you create another transaction during this interval, during which the first tx is not displayed,<br />
then your client will pick the same coins again, and the transaction will be rejected as a double spend.<br />
<br />
<br />
<br />
==External Links==<br />
* [http://ecdsa.org/electrum Electrum] project website<br />
* [https://gitorious.org/electrum Electrum] project source (gitorius)<br />
* [https://bitcointalk.org/index.php?topic=50936.msg950497#msg950497 Electrum Forum] - here this documentation was started</div>Michael Shttps://en.bitcoin.it/w/index.php?title=Electrum/Documentation&diff=27775Electrum/Documentation2012-06-12T22:32:03Z<p>Michael S: /* What does the "Tx" column mean in Electrum? */ clarified number in Tx column in "contacts" tab</p>
<hr />
<div>==Documentation of Electrum Bitcoin Client (Focus on the GUI)==<br />
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.<br />
<br />
More documentation, especially with regard to command line parameters, can be found at the parent page of this Wiki, i.e. [[Electrum|here]].<br />
<br />
==How to Read this Documentation==<br />
* Text in curly brackets {like this} means that the author(s) of this documentation are not really sure about this... --> other people are welcome to correct/clarify<br />
<br />
==What is a "Wallet" and a "Bitcoin Address"?==<br />
* (General, not specific to Electrum)<br />
<br />
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.<br />
<br />
Your wallet's balance is the sum of all Bitcoins of all your wallet's Bitcoin addresses.<br />
<br />
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.<br />
<br />
===Normal Addresses===<br />
* (More or less general, not too specific to Electrum)<br />
====How are New "Normal Addresses" Created for my Wallet?====<br />
The Bitcoin client (e.g. Electrum) allows you to trigger manually the generation of a new Bitcoin address. You typically want to create a new address when you want to receive Bitcoins from somebody and do not want to use any of the wallet's present addresses that have already been used for earlier Bitcoin transfers, for privacy reasons (note that all transfers are publically visible in the blockchain).<br />
<br />
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.<br />
<br />
===Change Addresses===<br />
* (More or less general, not too specific to Electrum)<br />
====What is a "Change Address", and why is it useful?====<br />
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.<br />
<br />
'''How it works:'''<br />
<br />
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.<br />
<br />
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.<br />
<br />
Exception: If all the Bitcoins of "A" are sent to "B", there is no need for creating a change address "C".<br />
<br />
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".<br />
<br />
'''Why the concept of "change addresses" is useful:'''<br />
<br />
* 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.<br />
* It also conceals which output is the "spend" and which is the "change".<br />
<br />
===Imported Addresses===<br />
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 derived from your wallet's [[#Seed|seed]] and therefore need to be secured separately for a complete backup of your wallet.<br />
<br />
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"]].<br />
<br />
===Deterministic Wallet===<br />
====What is a "Deterministic Wallet" in Electrum?====<br />
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).<br />
<br />
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).<br />
This is a big advantage when it comes to making wallet backups:<br />
* ''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.<br />
* ''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!<br />
<br />
===Seed===<br />
====What is the "Seed" of a Deterministic Wallet in Electrum?====<br />
The Seed of a [[#Deterministic Wallet|deterministic wallet]] is a series of 128 random bits in Electrum.<br />
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.<br />
<br />
So there are 2^128 possible seeds for a deterministic wallet in Electrum.<br />
For comparison, the total number of Bitcoin addresses is 2^160, and the number of atoms on earth is 2^166.<br />
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.<br />
(By the way: The number of atoms in the complete universe is estimated as 2^266).<br />
<br />
{<br />
<br />
Open Point: It is _not clear_ whether the algorithm of deterministic address generation is designed such that for any two seeds "S1" and "S2" (out of the 2^128 possible different seeds) the following condition holds true:<br />
* If 4.3 Billion (2^32 to be exact) new addresses are calculated from each S1 and from S2, does the algorithm guarantee that there will be no collision between the set of 2^32 addresses from S1 and the set of 2^32 addresses from S2?<br />
If this condition does not hold true, it needs to be clarified whether the use of deterministic wallets still bares an acceptably low probability of address collisions.<br />
<br />
}<br />
<br />
===What is the "Gap Limit"?===<br />
<br />
The gap limit is the maximal number of contiguous unused addresses in your deterministic sequence of addresses.<br />
<br />
If you recover your wallet from seed, you will notice that the gap limit is asked by the recovery dialog.<br />
It is used in order to decide when to stop the recovery procedure.<br />
<br />
If you need to have more receiving addresses in your wallet, you may increase your gap limit (expert mode).<br />
This, however, means that you will need to remember the new limit in order to be able to recover your wallet from seed.<br />
<br />
==More on the Electrum GUI==<br />
===What does it mean to "Prioritize" or "Freeze" Addresses in Electrum?===<br />
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.<br />
<br />
* 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.<br />
* 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. <br />
<br />
The user can (de)prioritize or (un)freeze both [[#Normal Addresses|normal]] and [[#Change Addresses|change]] addresses.<br />
<br />
Note: Clearly, an address can not be "prioritized" and "frozen" at the same time.<br />
<br />
===What does the "Tx" column mean in Electrum?===<br />
* Applies to "Receive" tab (own wallet's addresses) and "Contacts" tab (foreing addresses).<br />
<br />
Tx stands for {... ?? "Transaction"? "Transmission" ?? ...}<br />
<br />
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).<br />
<br />
'''In the "Receive" tab (own addresses):'''<br />
<br />
The number in the Tx column indicates the total number of _incoming_ Bitcoin transactions that have ever been sent to this address.<br />
<br />
{<br />
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.<br />
Does this "Tx" come from blockchain/blockexplorer terminology? Or why is it called "Tx" ("transmit") and not "Rx" ("receive")? To be clarified.<br />
}<br />
<br />
'''In the "Contacts" tab (foreign addresses):'''<br />
<br />
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<br />
<br />
===What does the "Balance" column mean in Electrum?===<br />
* Applies to "Receive" tab only (i.e. own wallet's addresses).<br />
<br />
The balance column indicates the amount of Bitcoins belonging to the given address.<br />
The individual balances add up to the total balance of your wallet.<br />
<br />
===What does the "Flag" column mean in Electrum?===<br />
* Applies to "Receive" tab only (i.e. own wallet's addresses).<br />
<br />
This column indicates certain properties of the different addresses:<br />
* C = [[#Change Addresses|Change address]] (without a "C" it means it is a [[#Normal Addresses|normal address]])<br />
* P = Prioritized address<br />
* F = Frozen address<br />
* I = [[#Imported Addresses|Imported address]]<br />
<br />
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]].<br />
<br />
===What do colors mean?===<br />
In the Receive tab:<br />
*green = prioritized<br />
*blue = frozen<br />
In the Contacts tab:<br />
*gray = alias<br />
<br />
==Troubleshooting==<br />
<br />
=== 'transaction rejected by memorypool' errors ===<br />
<br />
When you send a transaction, there is a delay before the Electrum client displays the transaction in its history.<br />
This is because the server polls bitcoind's memorypool every 10 seconds.<br />
<br />
If you create another transaction during this interval, during which the first tx is not displayed,<br />
then your client will pick the same coins again, and the transaction will be rejected as a double spend.<br />
<br />
<br />
<br />
==External Links==<br />
* [http://ecdsa.org/electrum Electrum] project website<br />
* [https://gitorious.org/electrum Electrum] project source (gitorius)<br />
* [https://bitcointalk.org/index.php?topic=50936.msg950497#msg950497 Electrum Forum] - here this documentation was started</div>Michael Shttps://en.bitcoin.it/w/index.php?title=Electrum/Documentation&diff=27773Electrum/Documentation2012-06-12T22:11:08Z<p>Michael S: /* What does the "Flag" column mean in Electrum? */ typo</p>
<hr />
<div>==Documentation of Electrum Bitcoin Client (Focus on the GUI)==<br />
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.<br />
<br />
More documentation, especially with regard to command line parameters, can be found at the parent page of this Wiki, i.e. [[Electrum|here]].<br />
<br />
==How to Read this Documentation==<br />
* Text in curly brackets {like this} means that the author(s) of this documentation are not really sure about this... --> other people are welcome to correct/clarify<br />
<br />
==What is a "Wallet" and a "Bitcoin Address"?==<br />
* (General, not specific to Electrum)<br />
<br />
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.<br />
<br />
Your wallet's balance is the sum of all Bitcoins of all your wallet's Bitcoin addresses.<br />
<br />
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.<br />
<br />
===Normal Addresses===<br />
* (More or less general, not too specific to Electrum)<br />
====How are New "Normal Addresses" Created for my Wallet?====<br />
The Bitcoin client (e.g. Electrum) allows you to trigger manually the generation of a new Bitcoin address. You typically want to create a new address when you want to receive Bitcoins from somebody and do not want to use any of the wallet's present addresses that have already been used for earlier Bitcoin transfers, for privacy reasons (note that all transfers are publically visible in the blockchain).<br />
<br />
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.<br />
<br />
===Change Addresses===<br />
* (More or less general, not too specific to Electrum)<br />
====What is a "Change Address", and why is it useful?====<br />
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.<br />
<br />
'''How it works:'''<br />
<br />
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.<br />
<br />
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.<br />
<br />
Exception: If all the Bitcoins of "A" are sent to "B", there is no need for creating a change address "C".<br />
<br />
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".<br />
<br />
'''Why the concept of "change addresses" is useful:'''<br />
<br />
* 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.<br />
* It also conceals which output is the "spend" and which is the "change".<br />
<br />
===Imported Addresses===<br />
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 derived from your wallet's [[#Seed|seed]] and therefore need to be secured separately for a complete backup of your wallet.<br />
<br />
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"]].<br />
<br />
===Deterministic Wallet===<br />
====What is a "Deterministic Wallet" in Electrum?====<br />
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).<br />
<br />
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).<br />
This is a big advantage when it comes to making wallet backups:<br />
* ''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.<br />
* ''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!<br />
<br />
===Seed===<br />
====What is the "Seed" of a Deterministic Wallet in Electrum?====<br />
The Seed of a [[#Deterministic Wallet|deterministic wallet]] is a series of 128 random bits in Electrum.<br />
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.<br />
<br />
So there are 2^128 possible seeds for a deterministic wallet in Electrum.<br />
For comparison, the total number of Bitcoin addresses is 2^160, and the number of atoms on earth is 2^166.<br />
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.<br />
(By the way: The number of atoms in the complete universe is estimated as 2^266).<br />
<br />
{<br />
<br />
Open Point: It is _not clear_ whether the algorithm of deterministic address generation is designed such that for any two seeds "S1" and "S2" (out of the 2^128 possible different seeds) the following condition holds true:<br />
* If 4.3 Billion (2^32 to be exact) new addresses are calculated from each S1 and from S2, does the algorithm guarantee that there will be no collision between the set of 2^32 addresses from S1 and the set of 2^32 addresses from S2?<br />
If this condition does not hold true, it needs to be clarified whether the use of deterministic wallets still bares an acceptably low probability of address collisions.<br />
<br />
}<br />
<br />
===What is the "Gap Limit"?===<br />
<br />
The gap limit is the maximal number of contiguous unused addresses in your deterministic sequence of addresses.<br />
<br />
If you recover your wallet from seed, you will notice that the gap limit is asked by the recovery dialog.<br />
It is used in order to decide when to stop the recovery procedure.<br />
<br />
If you need to have more receiving addresses in your wallet, you may increase your gap limit (expert mode).<br />
This, however, means that you will need to remember the new limit in order to be able to recover your wallet from seed.<br />
<br />
==More on the Electrum GUI==<br />
===What does it mean to "Prioritize" or "Freeze" Addresses in Electrum?===<br />
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.<br />
<br />
* 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.<br />
* 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. <br />
<br />
The user can (de)prioritize or (un)freeze both [[#Normal Addresses|normal]] and [[#Change Addresses|change]] addresses.<br />
<br />
Note: Clearly, an address can not be "prioritized" and "frozen" at the same time.<br />
<br />
===What does the "Tx" column mean in Electrum?===<br />
* Applies to "Receive" tab (own wallet's addresses) and "Contacts" tab (foreing addresses).<br />
<br />
Tx stands for {... ?? "Transaction"? "Transmission" ?? ...}<br />
<br />
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).<br />
<br />
'''In the "Receive" tab (own addresses):'''<br />
<br />
The number in the Tx column indicates the total number of _incoming_ Bitcoin transactions that have ever been sent to this address.<br />
<br />
{<br />
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.<br />
Does this "Tx" come from blockchain/blockexplorer terminology? Or why is it called "Tx" ("transmit") and not "Rx" ("receive")? To be clarified.<br />
}<br />
<br />
'''In the "Contacts" tab (foreign addresses):'''<br />
<br />
The number in the Tx column indicates the total number of Bitcoin transactions that have ever been received by this address<br />
{from anyobody? or just from myself, i.e. from addresses in my wallet? - Probably the latter - to be confirmed...}.<br />
<br />
===What does the "Balance" column mean in Electrum?===<br />
* Applies to "Receive" tab only (i.e. own wallet's addresses).<br />
<br />
The balance column indicates the amount of Bitcoins belonging to the given address.<br />
The individual balances add up to the total balance of your wallet.<br />
<br />
===What does the "Flag" column mean in Electrum?===<br />
* Applies to "Receive" tab only (i.e. own wallet's addresses).<br />
<br />
This column indicates certain properties of the different addresses:<br />
* C = [[#Change Addresses|Change address]] (without a "C" it means it is a [[#Normal Addresses|normal address]])<br />
* P = Prioritized address<br />
* F = Frozen address<br />
* I = [[#Imported Addresses|Imported address]]<br />
<br />
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]].<br />
<br />
===What do colors mean?===<br />
In the Receive tab:<br />
*green = prioritized<br />
*blue = frozen<br />
In the Contacts tab:<br />
*gray = alias<br />
<br />
==Troubleshooting==<br />
<br />
=== 'transaction rejected by memorypool' errors ===<br />
<br />
When you send a transaction, there is a delay before the Electrum client displays the transaction in its history.<br />
This is because the server polls bitcoind's memorypool every 10 seconds.<br />
<br />
If you create another transaction during this interval, during which the first tx is not displayed,<br />
then your client will pick the same coins again, and the transaction will be rejected as a double spend.<br />
<br />
<br />
<br />
==External Links==<br />
* [http://ecdsa.org/electrum Electrum] project website<br />
* [https://gitorious.org/electrum Electrum] project source (gitorius)<br />
* [https://bitcointalk.org/index.php?topic=50936.msg950497#msg950497 Electrum Forum] - here this documentation was started</div>Michael S