Bitcoin Wiki - User contributions [en]

Segwit support

2017-06-17T02:53:57Z

CodeShark:

<big><big>'''PLEASE NOTE:''' This list is not yet complete.</big></big>

'''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.'''

{| class="wikitable"
| {{No}} || doesn't support (but might or might not go along with it with sufficient community support)
|-
| {{Deficient}} || okay with the idea, but considers it to have insufficient community support
|-
| {{Evaluating}} || still evaluating the idea
|-
| {{AccJuly}} || it is a workable solution, provided it is activated before August 1 (and therefore BIP148-compatible)
|-
| {{Wanting}} || positively likes the idea, but considers it to have insufficient community support
|-
| {{Weak}} || better than nothing at all
|-
| {{Acceptable}} || it is a workable solution
|-
| {{Prefer}} || it is what he would choose if it was only up to him and no outside influences
|}



''Note that support for BIP148 does not mean developers support merging it into Core.''

{| class="wikitable sortable"
! rowspan=2 | Developer
! rowspan=2 | Aff* 
! Segwit itself
! colspan=3 | Deployment methods
! colspan=2 | Hardfork bundles (Silbert agreement)
|-
! [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]
|-
| Karl-Johan Alm || Core || {{Prefer}} || {{Acceptable}} || {{Acceptable}} || {{Acceptable}} || {{No}} || {{No}}
|-
| Bryan Bishop || Core || {{Prefer}} || {{Wanting}} || {{Acceptable}} || {{Weak}} || {{No}} || {{No}}
|-
| ฿tcDrak || Core || {{Prefer}} || {{Acceptable}} || {{Acceptable}} || {{No}} || {{No}} || {{No}}
|-
| Andrew Chow || Core || {{Prefer}} || {{Prefer}} || {{Acceptable}} || {{Weak}} || {{No}} || {{No}}
|-
| Matt Corallo || Core || {{Prefer}} || {{No}} || || {{Acceptable}} || {{No|LOL}} ||
|-
| Johnathan Corgan || Core || {{Prefer}} || {{Prefer}} || {{Acceptable}} || {{No}} || {{No}} || {{No}}
|-
| Luke Dashjr || Core || {{Prefer}} || {{Prefer}} || {{No}} || {{AccJuly}} || {{No}} || {{Deficient}}
|-
| Christian Decker || c-lightning || {{Prefer}} || {{Acceptable}} || || || ||
|-
| Nicolas Dorier || Core || {{Prefer}} || {{Deficient}} || {{Acceptable}} || {{AccJuly}} || ||
|-
| Thaddeus Dryja || lit || {{Prefer}} || {{No}} || {{Acceptable}} || {{Acceptable}} || {{No}} || {{No}}
|-
| Marco Falke || Core || {{Prefer}} || {{Deficient}} || {{Prefer}} || {{Deficient}} || ||
|-
| Mark Friedenbach || BIP 68/112 || {{Prefer}} || {{Prefer}} || {{No}} || {{AccJuly}} || {{No|LOL}} || {{No|Nope}}
|-
| Pavel Janik || Core || {{Prefer}} || {{No}} || {{Acceptable}} || {{No}} || {{No}} || {{No}}
|-
| Thomas Kerin || Core || {{Prefer}} || {{Wanting}} || {{Prefer}} || {{Weak}} || {{No}} || {{No}}
|-
| Johnson Lau || Core || {{Prefer}} || {{Wanting}} || {{Acceptable}} || {{Acceptable}} || ||
|-
| Eric Lombrozo || || {{Prefer}} || {{Acceptable}} || {{Weak}} || {{AccJuly}} || {{No}} || {{No}}
|-
| Greg Maxwell || Core || {{Prefer}} || {{Deficient}} || {{Acceptable}} || {{Weak}} || {{No}} || {{No}}
|-
| Alex Morcos || Core || {{Prefer}} || {{Deficient}} || {{Acceptable}} || {{Weak}} || {{No}} ||
|-
| Laolu "roasbeef" Osuntokun || lnd || {{Prefer}} || || || || {{No}} ||
|-
| Pavol "stick" Rusnak || Trezor || {{Prefer}} || {{Wanting}} || {{Acceptable}} || {{Acceptable}} || {{No}} || {{No}}
|-
| Rusty Russell || c-lightning || {{Prefer}} || {{Prefer}} || || || ||
|-
| Gregory Sanders || Core || {{Prefer}} || {{Wanting}} || {{Acceptable}} || {{Weak}} || {{No}} ||
|-
| Jonas Schnelli || Core || {{Prefer}} || {{Wanting}} || {{Acceptable}} || {{Acceptable}} || {{No}} || {{No}}
|-
| Paul Sztorc || || {{Prefer}} || {{Deficient}} || {{Wanting}} || {{AccJuly}} || {{Evaluating}} || {{No}}
|-
| Jorge Timon || Core || {{Prefer}} || {{No}} || {{Prefer}} || {{Deficient}} || {{No}} || {{No}}
|-
| Peter Todd || Core || {{Prefer}} || {{Acceptable}} || || || ||
|-
| Warren Togami || Elements || {{Prefer}} || {{Prefer}} || {{Acceptable}} || || ||
|-
| Wladimir van der Laan || Core || {{Prefer}} || {{Prefer}} || {{Acceptable}} || {{Acceptable}} || {{No}} || {{No}}
|-
| Leo Wandersleb || Mycelium || {{Prefer}} || {{Prefer}} || {{Acceptable}} || {{Weak}} || {{No}} || {{No}}
|-
| Pieter Wuille || Core || {{Prefer}} || || || || {{No}} ||
|}

* "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.

<hr>

'''When adding companies below, sources for each position MUST be provided.'''

{| class="wikitable sortable"
! rowspan=2 | Company
! rowspan=2 | Service
! Segwit itself
! colspan=3 | Deployment methods
! colspan=2 | Hardfork bundles (Silbert agreement)
|-
! [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]
|-
| Abra || wallet || {{Prefer}}<ref name="coindance" /> || {{Prefer}}<ref name="coindance" /> || || {{AccJuly}} || {{AccJuly}}<ref name="silbert" /> ||
|-
| Bitcoin India || exchange/miner || {{Prefer}}<ref name="coindance" /> || {{Prefer}}<ref name="coindance" /> || || || ||
|-
| BitcoinReminder.com || service || {{Prefer}}<ref name="bitcoinreminder_com">[https://bitcoinreminder.com/informations/poli BitcoinReminder.com's position on scaling proposals]</ref> || {{Prefer}}<ref name="bitcoinreminder_com"/> || {{Acceptable}}<ref name="bitcoinreminder_com"/> || {{Weak}}<ref name="bitcoinreminder_com"/> || {{No|LOL}}<ref name="bitcoinreminder_com"/> || {{No}}<ref name="bitcoinreminder_com"/>
|-
| Bitfinex || exchange || {{Acceptable}}<ref name="coindance" /> || {{Acceptable}} || || || ||
|-
| Bitfury || miner || {{Prefer}}<ref name="coindance" /> || {{Acceptable}} || || {{AccJuly}} || {{AccJuly}}<ref name="silbert" /> ||
|-
| 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" /> ||
|-
| 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|LOL}}<ref name="bitonic"/> || {{No}}
|-
| Bitpay || wallet || {{Prefer}}<ref name="bccore_swadoption"/> || {{No}} || || {{Prefer}} || {{Prefer}}<ref name="silbert" /> ||
|-
| Bitrated || || {{Prefer}}<ref name="coindance" /> || {{Prefer}}<ref name="coindance" /> || || || ||
|-
| Bitrefill || merchant || {{Prefer}}<ref name="coindance" /> || {{Prefer}}<ref name="coindance" /> || || || ||
|-
| 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"/> || || || ||
|-
| Bitstamp || exchange || || || || || ||
|-
| Bittylicious || exchange || {{Prefer}}<ref name="coindance" /> || {{Prefer}}<ref>[https://twitter.com/Bittylicious_/status/867305106668224513 Bittylicious answer on Twitter]</ref> || || || ||
|-
| Blockchain.info || wallet || {{Acceptable}}<ref name="bccore_swadoption"/> || || || {{AccJuly}} || {{AccJuly}}<ref name="silbert" /> ||
|-
| blockonomics || || {{Prefer}} || {{Prefer}}<ref>[https://twitter.com/blockonomics_co/status/851738251509497856 blockonomics announcement on Twitter]</ref> || || || ||
|-
| 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"/> ||
|-
| Ciphrex || wallet / dev stack || {{Prefer}}<ref name="coindance" /> || {{Acceptable}}<ref name="coindance" /> || || || ||
|-
| Coinbase || wallet || {{Acceptable}}<ref name="bccore_swadoption"/> || || || {{AccJuly}} || {{AccJuly}}<ref name="silbert" /> ||
|-
| CoinGate || exchange || {{Prefer}}<ref name="coindance" /> || {{Prefer}}<ref name="coindance" /> || || || ||
|-
| CoinJar || wallet || || {{Evaluating}}<ref>[https://twitter.com/GetCoinJar/status/875581525730787329 CoinJar answer on Twitter]</ref> || || || ||
|-
| Coinkite || || {{Prefer}}<ref name="coindance" /> || {{Prefer}}<ref name="coindance" /> || || || ||
|-
| coinomi || wallet || {{Prefer}}<ref name="coindance" /> || {{Prefer}}<ref name="coindance" /> || || || ||
|-
| DigitalBitbox || wallet(hardware) || {{Prefer}} || {{Acceptable}} || {{Prefer}}|| || ||
|-
| Electrum || wallet || {{Prefer}}<ref name="coindance" /> || {{Prefer}}<ref name="coindance" /> || || || ||
|-
| Kraken || exchange || || || || || ||
|-
| LightningASIC || miner || {{Prefer}}<ref name="coindance" /> || {{Prefer}}<ref name="coindance" /> || || || ||
|-
| OneHash || betting || {{Prefer}}<ref>[https://blog.onehash.com/sick-of-presidential-election-3f1a2defbbbf OneHash, "Sick of presidential election ?!"]</ref> || || || {{AccJuly}} || {{AccJuly}}<ref name="silbert" /> ||
|-
| Slushpool || miner || {{Prefer}}<ref name="coindance" /> || {{Acceptable}}<ref name="coindance" /> || || || ||
|-
| Vaultoro || exchange || {{Prefer}}<ref name="coindance" /> || {{Acceptable}}<ref name="coindance" /> || || {{AccJuly}} || {{AccJuly}}<ref name="silbert" /> ||
|-
| Walltime || || {{Prefer}}<ref name="coindance" /> || {{Prefer}}<ref name="coindance" /> || || || ||
|-
| Xapo || wallet || {{Prefer}}<ref name="coindance" /> || || || {{Prefer}} || {{Prefer}}<ref>[https://twitter.com/tedmrogers/status/867362691370954752 Tweet by president of Xapo]</ref> ||
|-
|}

<references>
<ref name="bccore_swadoption">[https://bitcoincore.org/en/segwit_adoption/ Bitcoin Core's Segwit adoption list]</ref>
<ref name="coindance">[https://coin.dance/poli Coin Dance, "Global Bitcoin Political Support & Public Opinion"]</ref>
<ref name="silbert">[https://medium.com/@DCGco/bitcoin-scaling-agreement-at-consensus-2017-133521fe9a77 Digital Currency Group, "Bitcoin Scaling Agreement at Consensus 2017"]</ref>
</references>

Segwit support

2017-06-16T01:32:37Z

CodeShark:

<big><big>'''PLEASE NOTE:''' This list is not yet complete.</big></big>

'''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.'''

{| class="wikitable"
| {{No}} || doesn't support (but might or might not go along with it with sufficient community support)
|-
| {{Deficient}} || okay with the idea, but considers it to have insufficient community support
|-
| {{Evaluating}} || still evaluating the idea
|-
| {{AccJuly}} || it is a workable solution, provided it is activated before August 1 (and therefore BIP148-compatible)
|-
| {{Wanting}} || positively likes the idea, but considers it to have insufficient community support
|-
| {{Weak}} || better than nothing at all
|-
| {{Acceptable}} || it is a workable solution
|-
| {{Prefer}} || it is what he would choose if it was only up to him and no outside influences
|}



''Note that support for BIP148 does not mean developers support merging it into Core.''

{| class="wikitable sortable"
! rowspan=2 colspan=2 | Developer & affiliation* 
! Segwit itself
! colspan=3 | Deployment methods
! colspan=2 | Hardfork bundles (Silbert agreement)
|-
! [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]
|-
| Karl-Johan Alm || Core || {{Prefer}} || {{Acceptable}} || {{Acceptable}} || {{Acceptable}} || {{No}} || {{No}}
|-
| Bryan Bishop || Core || {{Prefer}} || {{Wanting}} || {{Acceptable}} || {{Weak}} || {{No}} || {{No}}
|-
| ฿tcDrak || Core || {{Prefer}} || {{Acceptable}} || {{Acceptable}} || {{No}} || {{No}} || {{No}}
|-
| Andrew Chow || Core || {{Prefer}} || {{Prefer}} || {{Acceptable}} || {{Weak}} || {{No}} || {{No}}
|-
| Matt Corallo || Core || {{Prefer}} || {{No}} || || {{Acceptable}} || {{No|LOL}} ||
|-
| Johnathan Corgan || Core || {{Prefer}} || {{Prefer}} || {{Acceptable}} || {{No}} || {{No}} || {{No}}
|-
| Luke Dashjr || Core || {{Prefer}} || {{Prefer}} || {{No}} || {{AccJuly}} || {{Evaluating}} || {{Deficient}}
|-
| Christian Decker || Core || {{Prefer}} || {{Acceptable}} || || || ||
|-
| Nicolas Dorier || Core || {{Prefer}} || {{Deficient}} || {{Acceptable}} || {{AccJuly}} || ||
|-
| Thaddeus Dryja || lit || {{Prefer}} || {{No}} || {{Acceptable}} || {{Acceptable}} || {{No}} || {{No}}
|-
| Marco Falke || Core || {{Prefer}} || {{Deficient}} || {{Prefer}} || {{Deficient}} || ||
|-
| Mark Friedenbach || BIP 68/112 || {{Prefer}} || {{Prefer}} || {{No}} || {{AccJuly}} || {{No|LOL}} || {{No|Nope}}
|-
| Pavel Janik || Core || {{Prefer}} || {{No}} || {{Acceptable}} || {{No}} || {{No}} || {{No}}
|-
| Thomas Kerin || Core || {{Prefer}} || {{Wanting}} || {{Prefer}} || {{Weak}} || {{No}} || {{No}}
|-
| Johnson Lau || Core || {{Prefer}} || {{Wanting}} || {{Acceptable}} || {{Acceptable}} || ||
|-
| Eric Lombrozo || || {{Prefer}} || {{Acceptable}} || {{Weak}} || {{AccJuly}} || {{No}} || {{No}}
|-
| Greg Maxwell || Core || {{Prefer}} || {{Deficient}} || {{Acceptable}} || {{Weak}} || {{No}} || {{No}}
|-
| Alex Morcos || Core || {{Prefer}} || {{Deficient}} || {{Acceptable}} || {{Weak}} || {{No}} ||
|-
| Pavol "stick" Rusnak || Trezor || {{Prefer}} || {{Wanting}} || {{Acceptable}} || {{Acceptable}} || {{No}} || {{No}}
|-
| Rusty Russell || c-lightning || {{Prefer}} || {{Prefer}} || || || ||
|-
| Gregory Sanders || Core || {{Prefer}} || {{Wanting}} || {{Acceptable}} || {{Weak}} || {{No}} ||
|-
| Jonas Schnelli || Core || {{Prefer}} || {{Wanting}} || {{Acceptable}} || {{Acceptable}} || {{No}} || {{No}}
|-
| Jorge Timon || Core || {{Prefer}} || {{No}} || {{Prefer}} || {{Deficient}} || {{No}} || {{No}}
|-
| Peter Todd || Core || {{Prefer}} || {{Acceptable}} || || || ||
|-
| Warren Togami || Elements || {{Prefer}} || {{Prefer}} || {{Acceptable}} || || ||
|-
| Wladimir van der Laan || Core || {{Prefer}} || {{Prefer}} || {{Acceptable}} || {{Acceptable}} || {{No}} || {{No}}
|-
| Leo Wandersleb || Mycelium || {{Prefer}} || {{Prefer}} || {{Acceptable}} || {{Weak}} || {{No}} || {{No}}
|-
| Pieter Wuille || Core || {{Prefer}} || || || || {{No}} ||
|}

* "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.

<hr>
{| class="wikitable sortable"
! rowspan=2 colspan=2 | Company
! Segwit itself
! colspan=3 | Deployment methods
! colspan=2 | Hardfork bundles (Silbert agreement)
|-
! [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]
|-
| Bitfury || miner || {{Prefer}}[https://coin.dance/poli] || {{Acceptable}} || || || {{AccJuly}} ||
|-
| Bitsquare || exchange || {{Prefer}} || {{Prefer}}[https://forum.bitsquare.io/t/bitsquare-will-support-uasf-bitcoin-not-bitmaincoin/2265] || || || || ||
|-
| Coinbase || wallet || {{Prefer}}[https://bitcoincore.org/en/segwit_adoption/] || {{Evaluating}} || {{Weak}} || || {{AccJuly}}[https://medium.com/@DCGco/bitcoin-scaling-agreement-at-consensus-2017-133521fe9a77] ||
|-
| Xapo || wallet || {{Prefer}}[https://coin.dance/poli] || {{Evaluating}} || || || {{AccJuly}}[https://twitter.com/tedmrogers/status/867362691370954752] ||
|-
| Blockchain.info || wallet || {{Prefer}}[https://bitcoincore.org/en/segwit_adoption/] || {{Evaluating}} || {{Weak}} || || {{AccJuly}}[https://medium.com/@DCGco/bitcoin-scaling-agreement-at-consensus-2017-133521fe9a77] ||
|-
| Kraken || exchange || {{Prefer}}[https://coin.dance/poli] || {{Acceptable}} || || || {{AccJuly}}[https://medium.com/@DCGco/bitcoin-scaling-agreement-at-consensus-2017-133521fe9a77] ||
|-
| Bitstamp|| exchange || {{Prefer}}[https://coin.dance/poli] || {{Acceptable}} || || || {{Acceptable}}[https://medium.com/@DCGco/bitcoin-scaling-agreement-at-consensus-2017-133521fe9a77] ||
|-
| Bitfinex|| exchange || {{Prefer}}[https://coin.dance/poli] || {{Acceptable}} || || || {{Acceptable}}[https://medium.com/@DCGco/bitcoin-scaling-agreement-at-consensus-2017-133521fe9a77] ||
|-
| Bitonic/BL3P.eu || exchange || {{Prefer}} || {{Prefer}} || {{Acceptable}} || {{Weak}} || {{No|LOL}} || {{No}} 
|-
| Bitpay|| wallet || {{Prefer}}[https://bitcoincore.org/en/segwit_adoption/] || {{No}} || || || {{Prefer}} ||
|-
| Localbitcoins|| exchange || {{Prefer}}[https://bitcoincore.org/en/segwit_adoption/] || {{Acceptable}} || {{Weak}} || || {{AccJuly}} ||
|-
| Poloniex|| exchange || {{Prefer}}[https://coin.dance/poli] || {{Wanting}} || || || {{AccJuly}} ||
|-
| Bitmain|| miner || {{No}} || {{No}} || || || {{Prefer}} ||
|-

| Vaultoro|| gold exchange || {{Prefer}}[https://coin.dance/poli] || {{Acceptable}} || || || {{Acceptable}}[https://medium.com/@DCGco/bitcoin-scaling-agreement-at-consensus-2017-133521fe9a77] ||
|-
|}

Segwit support

2017-06-14T06:10:05Z

CodeShark:

Segwit support

2017-06-10T09:57:06Z

CodeShark:

<big><big>'''PLEASE NOTE:''' This list is not yet complete, nor completely vetted by the parties listed for accuracy.</big></big>

'''Developers: Please edit your row (add one if you're missing) 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 to give it access.'''

{| class="wikitable"
| {{No}} || doesn't support (but might or might not go along with it with sufficient community support)
|-
| {{Deficient}} || okay with the idea, but considers it to have insufficient community support
|-
| {{Evaluating}} || still evaluating the idea
|-
| {{Wanting}} || positively likes the idea, but considers it to have insufficient community support
|-
| {{Weak}} || better than nothing at all
|-
| {{Acceptable}} || it is a workable solution
|-
| {{Prefer}} || it is what he would choose if it was only up to him and no outside influences
|}



''Note that support for BIP148 does not mean developers support merging it into Core.''

{| class="wikitable sortable"
! rowspan=2 | Developer
! Segwit itself
! colspan=3 | Deployment methods
! colspan=2 | Hardfork bundles (Silbert agreement)
|-
! [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]
|-
| ฿tcDrak || {{Prefer}} || {{Acceptable}} || {{Acceptable}} || {{No}} || ||
|-
| Andrew Chow || {{Prefer}} || {{Prefer}} || {{Acceptable}} || {{Weak}} || {{No}} || {{No}}
|-
| Matt Corallo || {{Prefer}} || {{No}} || || {{Acceptable}} || ||
|-
| Johnathan Corgan || {{Prefer}} || {{Prefer}} || {{Acceptable}} || {{No}} || {{No}} || {{Evaluating}}
|-
| Suhas Daftuar || {{Prefer}} || {{No}} || || || ||
|-
| Luke Dashjr || {{Prefer}} || {{Prefer}} || {{No}} || {{Acceptable}} || {{No}} || {{Deficient}}
|-
| Christian Decker || {{Prefer}} || {{Acceptable}} || || || ||
|-
| Nicolas Dorier || {{Prefer}} || {{Deficient}} || || || ||
|-
| Marco Falke || {{Prefer}} || || || || ||
|-
| Michael Ford || {{Prefer}} || || || || ||
|-
| Mark Friedenbach || {{Prefer}} || {{Acceptable}} || || || ||
|-
| Pavel Janik || {{Prefer}} || || || || ||
|-
| Thomas Kerin || {{Prefer}} || {{Wanting}} || {{Prefer}} || {{Weak}} || {{No}} || {{No}}
|-
| Johnson Lau || {{Prefer}} || {{Wanting}} || {{Acceptable}} || {{Acceptable}} || ||
|-
| Eric Lombrozo || {{Prefer}} || {{Acceptable}} || {{Weak}} || {{Weak}} || {{No}} || {{No}}
|-
| Greg Maxwell || {{Prefer}} || {{Deficient}} || {{Acceptable}} || {{Weak}} || {{No}} || {{No}}
|-
| Alex Morcos || {{Prefer}} || {{Deficient}} || {{Acceptable}} || {{Weak}} || {{No}} ||
|-
| Rusty Russell || {{Prefer}} || {{Prefer}} || || || ||
|-
| Gregory Sanders || {{Prefer}} || {{Wanting}} || {{Acceptable}} || {{Weak}} || {{No}} ||
|-
| Jonas Schnelli || {{Prefer}} || {{Wanting}} || {{Acceptable}} || || ||
|-
| Patrick Strateman || {{Prefer}} || || || || ||
|-
| Jorge Timon || {{Prefer}} || {{No}} || {{Prefer}} || {{Deficient}} || {{Evaluating}} ||
|-
| Peter Todd || {{Prefer}} || {{Acceptable}} || || || ||
|-
| Wladimir van der Laan || {{Prefer}} || {{Prefer}} || {{Acceptable}} || {{Acceptable}} || {{No}} || {{No}}
|}

Segwit support

2017-06-10T09:55:04Z

CodeShark:

<big><big>'''PLEASE NOTE:''' This list is not yet complete, nor completely vetted by the parties listed for accuracy.</big></big>

'''Developers: Please edit your row (add one if you're missing) 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 to give it access.'''

{| class="wikitable"
| {{No}} || doesn't support (but might or might not go along with it with sufficient community support)
|-
| {{Deficient}} || okay with the idea, but considers it to have insufficient community support
|-
| {{Evaluating}} || still evaluating the idea
|-
| {{Wanting}} || positively likes the idea, but considers it to have insufficient community support
|-
| {{Weak}} || better than nothing at all
|-
| {{Acceptable}} || it is a workable solution
|-
| {{Prefer}} || it is what he would choose if it was only up to him and no outside influences
|}



''Note that support for BIP148 does not mean developers support merging it into Core.''

{| class="wikitable sortable"
! rowspan=2 | Developer
! Segwit itself
! colspan=3 | Deployment methods
! colspan=2 | Hardfork bundles (Silbert agreement)
|-
! [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]
|-
| ฿tcDrak || {{Prefer}} || {{Acceptable}} || {{Acceptable}} || {{No}} || ||
|-
| Andrew Chow || {{Prefer}} || {{Prefer}} || {{Acceptable}} || {{Weak}} || {{No}} || {{No}}
|-
| Matt Corallo || {{Prefer}} || {{No}} || || {{Acceptable}} || ||
|-
| Johnathan Corgan || {{Prefer}} || {{Prefer}} || {{Acceptable}} || {{No}} || {{No}} || {{Evaluating}}
|-
| Suhas Daftuar || {{Prefer}} || {{No}} || || || ||
|-
| Luke Dashjr || {{Prefer}} || {{Prefer}} || {{No}} || {{Acceptable}} || {{No}} || {{Deficient}}
|-
| Christian Decker || {{Prefer}} || {{Acceptable}} || || || ||
|-
| Nicolas Dorier || {{Prefer}} || {{Deficient}} || || || ||
|-
| Marco Falke || {{Prefer}} || || || || ||
|-
| Michael Ford || {{Prefer}} || || || || ||
|-
| Mark Friedenbach || {{Prefer}} || {{Acceptable}} || || || ||
|-
| Pavel Janik || {{Prefer}} || || || || ||
|-
| Thomas Kerin || {{Prefer}} || {{Wanting}} || {{Prefer}} || {{Weak}} || {{No}} || {{No}}
|-
| Johnson Lau || {{Prefer}} || {{Wanting}} || {{Acceptable}} || {{Acceptable}} || ||
|-
| Eric Lombrozo || {{Prefer}} || {{Acceptable}} || {{Weak}} || {{No}} || {{No}} || {{No}}
|-
| Greg Maxwell || {{Prefer}} || {{Deficient}} || {{Acceptable}} || {{Weak}} || {{No}} || {{No}}
|-
| Alex Morcos || {{Prefer}} || {{Deficient}} || {{Acceptable}} || {{Weak}} || {{No}} ||
|-
| Rusty Russell || {{Prefer}} || {{Prefer}} || || || ||
|-
| Gregory Sanders || {{Prefer}} || {{Wanting}} || {{Acceptable}} || {{Weak}} || {{No}} ||
|-
| Jonas Schnelli || {{Prefer}} || {{Wanting}} || {{Acceptable}} || || ||
|-
| Patrick Strateman || {{Prefer}} || || || || ||
|-
| Jorge Timon || {{Prefer}} || {{No}} || {{Prefer}} || {{Deficient}} || {{Evaluating}} ||
|-
| Peter Todd || {{Prefer}} || {{Acceptable}} || || || ||
|-
| Wladimir van der Laan || {{Prefer}} || {{Prefer}} || {{Acceptable}} || {{Acceptable}} || {{No}} || {{No}}
|}

Segwit support

2017-06-05T11:31:18Z

CodeShark:

<big><big>'''PLEASE NOTE:''' This list is not yet complete, nor completely vetted by the parties listed for accuracy.</big></big>

{| class="wikitable"
| {{No}} || doesn't support (but might or might not go along with it with sufficient community support)
|-
| {{Deficient}} || okay with the idea, but considers it to have insufficient community support
|-
| {{Evaluating}} || still evaluating the idea
|-
| {{Wanting}} || positively likes the idea, but considers it to have insufficient community support
|-
| {{Weak}} || better than nothing at all
|-
| {{Acceptable}} || it is a workable solution
|-
| {{Prefer}} || it is what he would choose if it was only up to him and no outside influences
|}



''Note that support for BIP148 does not mean developers support merging it into Core.''

{| class="wikitable sortable"
! rowspan=2 | Developer
! Segwit itself
! colspan=3 | Deployment methods
! colspan=2 | Hardfork bundles (Silbert agreement)
|-
! [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]
|-
| ฿tcDrak || {{Prefer}} || {{Acceptable}} || {{Acceptable}} || {{No}} || ||
|-
| Andrew Chow || {{Prefer}} || {{Prefer}} || || || ||
|-
| Matt Corallo || {{Prefer}} || {{No}} || || {{Acceptable}} || ||
|-
| Johnathan Corgan || {{Prefer}} || {{Prefer}} || {{Acceptable}} || {{Weak}} || {{No}} || {{Evaluating}}
|-
| Suhas Daftuar || {{Prefer}} || {{No}} || || || ||
|-
| Luke Dashjr || {{Prefer}} || {{Prefer}} || {{Weak}} || {{Acceptable}} || {{No}} || {{Deficient}}
|-
| Nicolas Dorier || {{Prefer}} || {{Acceptable}} || || || ||
|-
| Michael Ford || {{Prefer}} || || || || ||
|-
| Mark Friedenbach || {{Prefer}} || {{Acceptable}} || || || ||
|-
| Pavel Janik || {{Prefer}} || || || || ||
|-
| Johnson Lau || {{Prefer}} || || || || ||
|-
| Eric Lombrozo || {{Prefer}} || {{Acceptable}} || {{Evaluating}} || {{No}} || {{Evaluating}} || {{Evaluating}}
|-
| Greg Maxwell || {{Prefer}} || {{No}} || {{Acceptable}} || || ||
|-
| Alex Morcos || {{Prefer}} || {{No}} || || || ||
|-
| Rusty Russell || {{Prefer}} || {{Prefer}} || || || ||
|-
| Jonas Schnelli || {{Prefer}} || || || || ||
|-
| Patrick Strateman || {{Prefer}} || || || || ||
|-
| Jorge Timon || {{Prefer}} || || || || ||
|-
| Peter Todd || {{Prefer}} || {{Acceptable}} || || || ||
|-
| Pieter Wuille || {{Prefer}} || {{Wanting}} || || || ||
|-
| Wladimir van der Laan || {{Prefer}} || {{Acceptable}} || {{Acceptable}} || || ||
|}

Segwit support

2017-06-05T10:24:44Z

CodeShark:

<big><big>'''PLEASE NOTE:''' This list is not yet complete, nor completely vetted by the parties listed for accuracy.</big></big>

{| class="wikitable"
| {{No}} || doesn't support (but might or might not go along with it with sufficient community support)
|-
| {{Deficient}} || okay with the idea, but considers it to have insufficient community support
|-
| {{Evaluating}} || still evaluating the idea
|-
| {{Wanting}} || positively likes the idea, but considers it to have insufficient community support
|-
| {{Weak}} || better than nothing at all
|-
| {{Acceptable}} || it is a workable solution
|-
| {{Prefer}} || it is what he would choose if it was only up to him and no outside influences
|}



''Note that support for BIP148 does not mean developers support merging it into Core.''

{| class="wikitable sortable"
! rowspan=2 | Developer
! Segwit itself
! colspan=3 | Deployment methods
! colspan=2 | Hardfork bundles (Silbert agreement)
|-
! [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]
|-
| ฿tcDrak || {{Prefer}} || {{Acceptable}} || {{Acceptable}} || {{No}} || ||
|-
| Andrew Chow || {{Prefer}} || {{Prefer}} || || || ||
|-
| Matt Corallo || {{Prefer}} || {{No}} || || {{Acceptable}} || ||
|-
| Johnathan Corgan || {{Prefer}} || {{Prefer}} || {{Acceptable}} || {{Weak}} || {{No}} || {{Evaluating}}
|-
| Suhas Daftuar || {{Prefer}} || {{No}} || || || ||
|-
| Luke Dashjr || {{Prefer}} || {{Prefer}} || {{Weak}} || {{Acceptable}} || {{No}} || {{Deficient}}
|-
| Nicolas Dorier || {{Prefer}} || {{Acceptable}} || || || ||
|-
| Michael Ford || {{Prefer}} || || || || ||
|-
| Mark Friedenbach || {{Prefer}} || {{Acceptable}} || || || ||
|-
| Pavel Janik || {{Prefer}} || || || || ||
|-
| Johnson Lau || {{Prefer}} || || || || ||
|-
| Eric Lombrozo || {{Prefer}} || {{Prefer}} || {{Evaluating}} || {{Weak}} || {{Evaluating}} || {{Evaluating}}
|-
| Greg Maxwell || {{Prefer}} || {{No}} || {{Acceptable}} || || ||
|-
| Alex Morcos || {{Prefer}} || {{No}} || || || ||
|-
| Rusty Russell || {{Prefer}} || {{Prefer}} || || || ||
|-
| Jonas Schnelli || {{Prefer}} || || || || ||
|-
| Patrick Strateman || {{Prefer}} || || || || ||
|-
| Jorge Timon || {{Prefer}} || || || || ||
|-
| Peter Todd || {{Prefer}} || {{Acceptable}} || || || ||
|-
| Pieter Wuille || {{Prefer}} || {{Wanting}} || || || ||
|-
| Wladimir van der Laan || {{Prefer}} || {{Acceptable}} || {{Acceptable}} || || ||
|}

Segwit support

2017-06-04T04:39:28Z

CodeShark:

<big><big>'''PLEASE NOTE:''' This list is not yet complete, nor completely vetted by the parties listed for accuracy.</big></big>

{| class="wikitable"
| {{No}} || doesn't support
|-
| {{Weak}} || better than nothing at all
|-
| {{Yes}} || it is a workable solution
|-
| {{Prefer}} || it is what he would choose if it was only up to him and no outside influences
|-
| {{Evaluating}} || still evaluating the idea
|}

{| class="wikitable sortable"
! rowspan=2 | Developer
! Segwit itself
! colspan=3 | Deployment methods
! colspan=2 | Hardfork bundles (Silbert agreement)
|-
! [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]
|-
| ฿tcDrak || {{Prefer}} || {{Prefer}} || {{Yes}} || || ||
|-
| Andrew Chow || {{Prefer}} || {{Prefer}} || || || ||
|-
| Matt Corallo || {{Prefer}} || {{No}} || || {{Yes}} || ||
|-
| Suhas Daftuar || {{Prefer}} || {{No}} || || || ||
|-
| Luke Dashjr || {{Prefer}} || {{Prefer}} || {{Weak}} || {{Yes}} || {{No}} || {{Yes}}
|-
| Nicolas Dorier || {{Prefer}} || {{Yes}} || || || ||
|-
| Michael Ford || {{Prefer}} || || || || ||
|-
| Mark Friedenbach || {{Prefer}} || {{Yes}} || || || ||
|-
| Pavel Janik || {{Prefer}} || || || || ||
|-
| Johnson Lau || {{Prefer}} || || || || ||
|-
| Eric Lombrozo || {{Prefer}} || {{Prefer}} || {{Evaluating}} || {{Yes}} || {{Evaluating}} || {{Evaluating}}
|-
| Greg Maxwell || {{Prefer}} || {{No}} || {{Yes}} || || ||
|-
| Alex Morcos || {{Prefer}} || {{No}} || || || ||
|-
| Rusty Russell || {{Prefer}} || {{Prefer}} || || || ||
|-
| Jonas Schnelli || {{Prefer}} || || || || ||
|-
| Patrick Strateman || {{Prefer}} || || || || ||
|-
| Jorge Timon || {{Prefer}} || || || || ||
|-
| Peter Todd || {{Prefer}} || {{Yes}} || || || ||
|-
| Pieter Wuille || {{Prefer}} || {{No}} || || || ||
|-
| Wladimir van der Laan || {{Prefer}} || {{Yes}} || {{Yes}} || || ||
|}

Segwit support

2017-06-04T04:35:15Z

CodeShark:

<big><big>'''PLEASE NOTE:''' This list is not yet complete, nor completely vetted by the parties listed for accuracy.</big></big>

{| class="wikitable"
| {{No}} || doesn't support
|-
| {{Weak}} || better than nothing at all
|-
| {{Yes}} || it is a workable solution
|-
| {{Prefer}} || it is what he would choose if it was only up to him and no outside influences
|-
| {{Evaluating}} || still evaluating the idea
|}

{| class="wikitable sortable"
! rowspan=2 | Developer
! Segwit itself
! colspan=3 | Deployment methods
! colspan=2 | Hardfork bundles (Silbert agreement)
|-
! [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]
|-
| ฿tcDrak || {{Prefer}} || {{Prefer}} || {{Yes}} || || ||
|-
| Andrew Chow || {{Prefer}} || {{Prefer}} || || || ||
|-
| Matt Corallo || {{Prefer}} || {{No}} || || {{Yes}} || ||
|-
| Suhas Daftuar || {{Prefer}} || {{No}} || || || ||
|-
| Luke Dashjr || {{Prefer}} || {{Prefer}} || {{Weak}} || {{Yes}} || {{No}} || {{Yes}}
|-
| Nicolas Dorier || {{Prefer}} || {{Yes}} || || || ||
|-
| Michael Ford || {{Prefer}} || || || || ||
|-
| Mark Friedenbach || {{Prefer}} || {{Yes}} || || || ||
|-
| Pavel Janik || {{Prefer}} || || || || ||
|-
| Johnson Lau || {{Prefer}} || || || || ||
|-
| Eric Lombrozo || {{Prefer}} || {{Prefer}} || || || ||
|-
| Greg Maxwell || {{Prefer}} || {{No}} || {{Yes}} || || ||
|-
| Alex Morcos || {{Prefer}} || {{No}} || || || ||
|-
| Rusty Russell || {{Prefer}} || {{Prefer}} || || || ||
|-
| Jonas Schnelli || {{Prefer}} || || || || ||
|-
| Patrick Strateman || {{Prefer}} || || || || ||
|-
| Jorge Timon || {{Prefer}} || || || || ||
|-
| Peter Todd || {{Prefer}} || {{Yes}} || || || ||
|-
| Pieter Wuille || {{Prefer}} || {{No}} || || || ||
|-
| Wladimir van der Laan || {{Prefer}} || {{Yes}} || {{Yes}} || || ||
|}

BIP 0032

2013-10-09T10:12:43Z

CodeShark: /* Implementations */

{{bip}}

RECENT CHANGES:
* [16 Apr 2013] Added private derivation for i >= 0x80000000 (less risk of parent private key leakage)
* [30 Apr 2013] Switched from multiplication by I_L to addition of I_L (faster, easier implementation)
* [25 May 2013] Added test vectors

<pre>
BIP: 32
Title: Hierarchical Deterministic Wallets
Author: Pieter Wuille
Status: Accepted
Type: Informational
Created: 11-02-2012
</pre>

==Abstract==

This document describes [[Deterministic Wallet|hierarchical determinstic wallets]] (or "HD Wallets"): wallets which can be shared partially or entirely with different systems, each with or without the ability to spend coins.

The specification is intended to set a standard for deterministic wallets that can be interchanged between different clients. Although the wallets described here have many features, not all are required by supporting clients.

The specification consists of two parts. In a first part, a system for deriving a tree of keypairs from a single seed is presented. The second part demonstrates how to build a wallet structure on top of such a tree.

==Motivation==

The Bitcoin reference client uses randomly generated keys. In order to avoid the necessity for a backup after every transaction, (by default) 100 keys are cached in a pool of reserve keys. Still, these wallets are not intended to be shared and used on several systems simultaneously. They support hiding their private keys by using the wallet encrypt feature and not sharing the password, but such "neutered" wallets lose the power to generate public keys as well.

Deterministic wallets do not require such frequent backups, and elliptic curve mathematics permit schemes where one can calculate the public keys without revealing the private keys. This permits for example a webshop business to let its webserver generate fresh addresses (public key hashes) for each order or for each customer, without giving the webserver access to the corresponding private keys (which are required for spending the received funds).

However, deterministic wallets typically consist of a single "chain" of keypairs. The fact that there is only one chain means that sharing a wallet happens on an all-or-nothing basis. However, in some cases one only wants some (public) keys to be shared and recoverable. In the example of a webshop, the webserver does not need access to all public keys of the merchant's wallet; only to those addresses which are used to receive customer's payments, and not for example the change addresses that are generated when the merchant spends money. Hierarchical deterministic wallets allow such selective sharing by supporting multiple keypair chains, derived from a single root.

==Specification: Key derivation==

===Conventions===

In the rest of this text we will assume the public key cryptography used in Bitcoin, namely elliptic curve cryptography using the field and curve parameters defined by secp256k1 (http://www.secg.org/index.php?action=secg,docs_secg). Variables below are either:
* integers modulo the order of the curve (referred to as n), serialized as 32 bytes, most significant byte first.
* coordinates of points on the curve, serialized as specified in SEC1 in compressed form: [0x02 or 0x03] + 32 byte x coordinate), where the header byte depends on the parity of the omitted y coordinate.
* byte sequences

We shall denote the compressed form of point P by χ(P), which for secp256k1 will always be 33 bytes long.

Addition (+) of two coordinates is defined as application of the EC group operation. Multiplication (*) of an integer and a coordinate is defined as repeated application of the EC group operation. The generator element of the curve is called G. The public key K corresponding to the private key k is calculated as k*G. We do not distinguish between numbers or coordinates and their serialization as byte sequences.

===Extended keys===

In what follows, we will define a function that derives a number of child keys from a parent key. In order to prevent these from depending solely on the key itself, we extend both private and public keys first with an extra 256 bits of entropy. This extension, called the chain code, is identical for corresponding private and public keys, and consists of 32 bytes.

We represent an extended private key as (k, c), with k the normal private key, and c the chain code. An extended public key is represented as (K, c), with K = k*G and c the chain code.

===Child key derivation functions===

We allow for two different types of derivation: private and public.
* Private derivation: knowledge of the private key kpar and cpar is required to compute both ki and Ki.
* Public derivation: knowledge of the public key Kpar and cpar suffices to compute Ki (but not ki).

We define the private and public child key derivation functions:
* CKD((kpar, cpar), i) → (ki, ci), defined for both private and public derivation.
* CKD'((Kpar, cpar), i) → (Ki, ci), defined only for public derivation.

We use the most significant bit of i to specify which type of derivation to use. i is encoded as a 32 bit unsigned integer, most significant byte first; '||' represents concatenation.

====Private child key derivation====

To define CKD((kpar, cpar), i) → (ki, ci):
* Check whether the highest bit (0x80000000) of i is set:
** If 1, private derivation is used: let I = HMAC-SHA512(Key = cpar, Data = 0x00 || kpar || i) [Note: The 0x00 pads the private key to make it 33 bytes long.]
** If 0, public derivation is used: let I = HMAC-SHA512(Key = cpar, Data = χ(kpar*G) || i)
* Split I = IL || IR into two 32-byte sequences, IL and IR.
* ki = IL + kpar (mod n).
* ci = IR.
In case IL ≥ n or ki = 0, the resulting key is invalid, and one should proceed with the next value for i.
[Note: this has probability lower than 1 in 2127.]

====Public child key derivation====

To define CKD'((Kpar, cpar), i) → (Ki, ci):
* Check whether the highest bit (0x80000000) of i is set:
** If 1, return error
** If 0, let I = HMAC-SHA512(Key = cpar, Data = χ(Kpar) || i)
* Split I = IL || IR into two 32-byte sequences, IL and IR.
* Ki = (IL + Kpar)*G = IL*G + Kpar
* ci = IR.
In case IL ≥ n or Ki is the point at infinity, the resulting key is invalid, and one should proceed with the next value for i.

Note that the extended public key corresponding to the evaluation of CKD(kext, i) with public derivation (so with i < 0x80000000) is identical to the evaluation of CKD'(Kext, i), with Kext the extended public key corresponding to kext. Symbolically, CKD((k, c), i)*G = CKD'((k*G, c), i). This implies that CKD' can be used to derive all public keys corresponding to the private keys that CKD would find. It cannot be used to retrieve the private keys, however.

The HMAC-SHA512 function is specified in [http://tools.ietf.org/html/rfc4231 RFC 4231].

===The key tree===

The next step is cascading several CKD constructions to build a tree. We start with one root, the master extended key m. By evaluating CKD(m,i) for several values of i, we get a number of first-degree derivative nodes. As each of these is again an extended key, CKD can be applied to those as well. To shorten notation, we will write CKD(CKD(CKD(m,0x8000003),0x2),0x5) as m/3'/2/5 now.

Each leaf node in the tree corresponds to an actual keypair, while the internal nodes correspond to the collection of keypairs that descends from them. The chain codes of the leaf nodes are ignored, and only their embedded private or public key is used. Because of this construction, knowing an extended private key allows reconstruction of all descendant private keys and public keys, and knowing an extended public keys allows reconstruction of all descendant public keys derived using public derivation.

===Key identifiers===

Extended keys can be identified by the Hash160 (RIPEMD160 after SHA256) of the serialized public key, ignoring the chain code. This corresponds exactly to the data used in traditional Bitcoin addresses. It is not advised to represent this data in base58 format though, as it may be interpreted as an address that way (and wallet software is not required to accept payment to the chain key itself).

The first 32 bits of the identifier are called the fingerprint.

===Serialization format===

Extended public and private keys are serialized as follows:
* 4 byte: version bytes (mainnet: 0x0488B21E public, 0x0488ADE4 private; testnet: 0x043587CF public, 0x04358394 private)
* 1 byte: depth: 0x00 for master nodes, 0x01 for level-1 descendants, ....
* 4 bytes: the fingerprint of the parent's key (0x00000000 if master key)
* 4 bytes: child number. This is the number i in xi = xpar/i, with xi the key being serialized. This is encoded in MSB order. (0x00000000 if master key)
* 32 bytes: the chain code
* 33 bytes: the public key or private key data (0x02 + X or 0x03 + X for public keys, 0x00 + k for private keys)

This 78 byte structure can be encoded like other Bitcoin data in Base58, by first adding 32 checksum bits (derived from the double SHA-256 checksum), and then converting to the Base58 representation. This results in a Base58-encoded string of up to 112 characters. Because of the choice of the version bytes, the Base58 representation will start with "xprv" or "xpub" on mainnet, "tprv" or "tpub" on testnet.

Note that the fingerprint of the parent only serves as a fast way to detect parent and child nodes in software, and software must be willing to deal with collisions. Internally, the full 160-bit identifier could be used.

When importing a serialized extended public key, implementations must verify whether the X coordinate in the public key data corresponds to a point on the curve. If not, the extended public key is invalid.

===Master key generation===

The total number of possible extended keypairs is almost 2^512, but the produced keys are only 256 bits long, and offer about half of that in terms of security. Therefore, master keys are not generated directly, but instead from a potentially short seed value.

* Generate a seed S of a chosen length (at least 128 bits, but 256 is advised) from a (P)RNG.
* Calculate I = HMAC-SHA512(key="Bitcoin seed", msg=S)
* Split I into two 32-byte sequences, IL and IR.
* Use IL as master secret key, and IR as master chain code.
In case IL is 0 or >=n, the master key is invalid.

[[File:BIP32-derivation.png]]

==Specification: Wallet structure==

The previous sections specified key trees and their nodes. The next step is imposing a wallet structure on this tree. The layout defined in this section is a default only, though clients are encouraged to mimick it for compatibility, even if not all features are supported.

An HDW is organized as several 'accounts'. Accounts are numbered, the default account ("") being number 0. Clients are not required to support more than one account - if not, they only use the default account.

Each account is composed of two keypair chains: an internal and an external one. The external [[keychain]] is used to generate new public addresses, while the internal keychain is used for all other operations (change addresses, generation addresses, ..., anything that doesn't need to be communicated). Clients that do not support separate keychains for these should use the external one for everything.

* m/i'/0/k corresponds to the k'th keypair of the external chain of account number i of the HDW derived from master m.
* m/i'/1/k corresponds to the k'th keypair of the internal chain of account number i of the HDW derived from master m.

===Use cases===

====Full wallet sharing: m====

In cases where two systems need to access a single shared wallet, and both need to be able to perform spendings, one needs to share the master private extended key. Nodes can keep a pool of N look-ahead keys cached for external chains, to watch for incoming payments. The look-ahead for internal chains can be very small, as no gaps are to be expected here. An extra look-ahead could be active for the first unused account's chains - triggering the creation of a new account when used. Note that the name of the account will still need to be entered manually and cannot be synchronized via the block chain.

====Audits: M====

In case an auditor needs full access to the list of incoming and outgoing payments, one can share the master public extended key. This will allow the auditor to see all transactions from and to the wallet, in all accounts, but not a single secret key.

====Per-office balances: m/i'====

When a business has several independent offices, they can all use wallets derived from a single master. This will allow the headquarters to maintain a super-wallet that sees all incoming and outgoing transactions of all offices, and even permit moving money between the offices.

====Recurrent business-to-business transactions: M/i'/0====

In case two business partners often transfer money, one can use the extended public key for the external chain of a specific account (M/i'/0) as a sort of "super address", allowing frequent transactions that cannot (easily) be associated, but without needing to request a new address for each payment.
Such a mechanism could also be used by mining pool operators as variable payout address.

====Unsecure money receiver: M/i'/0====

When an unsecure webserver is used to run an e-commerce site, it needs to know public addresses that be used to receive payments. The webserver only needs to know the public extended key of the external chain of a single account. This means someone illegally obtaining access to the webserver can at most see all incoming payments, but will not (trivially) be able to distinguish outgoing transactions, nor see payments received by other webservers if there are several ones.

==Compatibility==

To comply with this standard, a client must at least be able to import an extended public or private key, to give access to its direct descendants as wallet keys. The wallet structure (master/account/chain/subchain) presented in the second part of the specification is advisory only, but is suggested as a minimal structure for easy compatibility - even when no separate accounts or distinction between internal and external chains is made. However, implementations may deviate from it for specific needs; more complex applications may call for a more complex tree structure.

==Security==

In addition to the expectations from the EC public-key cryptography itself:
* Given a public key K, an attacker cannot find the corresponding private key more efficiently than by solving the EC discrete logarithm problem (assumed to require 2128 group operations).
the intended security properties of this standard are:
* Given a child extended private key (ki,ci) and the integer i, an attacker cannot find the parent private key kpar more efficiently than a 2256 brute force of HMAC-SHA512.
* Given any number (2 <= N <= 232-1) of (index, extended private key) tuples (ij,(pj,cj)), with distinct ij's, determining whether they are derived from a common parent extended private key (i.e., whether there exists a (ppar,cpar) such that for each j in [0..N-1] CKD((ppar,cpar),ij)=(pj,cj)), cannot be done more efficiently than a 2256 brute force of HMAC-SHA512.
Note however that the following properties does not exist:
* Given a parent extended public key (Kpar,cpar) and a child public key (Ki), it is hard to find i.
* Given a parent extended public key (Kpar,cpar) and a child private key (ki) using public derivation, it is hard to find kpar.

Private and public keys must be kept safe as usual. Leaking a private key means access to coins - leaking a public key can mean loss of privacy.

Somewhat more care must be taken regarding extended keys, as these correspond to an entire (sub)tree of keys. One weakness that may not be immediately obvious, is that knowledge of the extended public key + a private key descending from it is equivalent to knowing the extended private key (i.e., every private and public key) in case public derivation is used. This means that extended public keys must be treated more carefully than regular public keys. This is the reason why accounts at the first level of the default wallet layout use private derivation, so a leak of account-specific (or below) private key never risks compromising the master.

==Test Vectors==

For more detailed information about these (such as intermediate values and other representations), see [[BIP_0032_TestVectors]]

Test vector 1

Master (hex): 000102030405060708090a0b0c0d0e0f
* [Chain m]
* ext pub: xpub661MyMwAqRbcFtXgS5sYJABqqG9YLmC4Q1Rdap9gSE8NqtwybGhePY2gZ29ESFjqJoCu1Rupje8YtGqsefD265TMg7usUDFdp6W1EGMcet8
* ext prv: xprv9s21ZrQH143K3QTDL4LXw2F7HEK3wJUD2nW2nRk4stbPy6cq3jPPqjiChkVvvNKmPGJxWUtg6LnF5kejMRNNU3TGtRBeJgk33yuGBxrMPHi
* [Chain m/0']
* ext pub: xpub68Gmy5EdvgibQVfPdqkBBCHxA5htiqg55crXYuXoQRKfDBFA1WEjWgP6LHhwBZeNK1VTsfTFUHCdrfp1bgwQ9xv5ski8PX9rL2dZXvgGDnw
* ext prv: xprv9uHRZZhk6KAJC1avXpDAp4MDc3sQKNxDiPvvkX8Br5ngLNv1TxvUxt4cV1rGL5hj6KCesnDYUhd7oWgT11eZG7XnxHrnYeSvkzY7d2bhkJ7
* [Chain m/0'/1]
* ext pub: xpub6ASuArnXKPbfEwhqN6e3mwBcDTgzisQN1wXN9BJcM47sSikHjJf3UFHKkNAWbWMiGj7Wf5uMash7SyYq527Hqck2AxYysAA7xmALppuCkwQ
* ext prv: xprv9wTYmMFdV23N2TdNG573QoEsfRrWKQgWeibmLntzniatZvR9BmLnvSxqu53Kw1UmYPxLgboyZQaXwTCg8MSY3H2EU4pWcQDnRnrVA1xe8fs
* [Chain m/0'/1/2']
* ext pub: xpub6D4BDPcP2GT577Vvch3R8wDkScZWzQzMMUm3PWbmWvVJrZwQY4VUNgqFJPMM3No2dFDFGTsxxpG5uJh7n7epu4trkrX7x7DogT5Uv6fcLW5
* ext prv: xprv9z4pot5VBttmtdRTWfWQmoH1taj2axGVzFqSb8C9xaxKymcFzXBDptWmT7FwuEzG3ryjH4ktypQSAewRiNMjANTtpgP4mLTj34bhnZX7UiM
* [Chain m/0'/1/2'/2]
* ext pub: xpub6FHa3pjLCk84BayeJxFW2SP4XRrFd1JYnxeLeU8EqN3vDfZmbqBqaGJAyiLjTAwm6ZLRQUMv1ZACTj37sR62cfN7fe5JnJ7dh8zL4fiyLHV
* ext prv: xprvA2JDeKCSNNZky6uBCviVfJSKyQ1mDYahRjijr5idH2WwLsEd4Hsb2Tyh8RfQMuPh7f7RtyzTtdrbdqqsunu5Mm3wDvUAKRHSC34sJ7in334
* [Chain m/0'/1/2'/2/1000000000]
* ext pub: xpub6H1LXWLaKsWFhvm6RVpEL9P4KfRZSW7abD2ttkWP3SSQvnyA8FSVqNTEcYFgJS2UaFcxupHiYkro49S8yGasTvXEYBVPamhGW6cFJodrTHy
* ext prv: xprvA41z7zogVVwxVSgdKUHDy1SKmdb533PjDz7J6N6mV6uS3ze1ai8FHa8kmHScGpWmj4WggLyQjgPie1rFSruoUihUZREPSL39UNdE3BBDu76

Test vector 2

Master (hex): fffcf9f6f3f0edeae7e4e1dedbd8d5d2cfccc9c6c3c0bdbab7b4b1aeaba8a5a29f9c999693908d8a8784817e7b7875726f6c696663605d5a5754514e4b484542
* [Chain m]
* ext pub: xpub661MyMwAqRbcFW31YEwpkMuc5THy2PSt5bDMsktWQcFF8syAmRUapSCGu8ED9W6oDMSgv6Zz8idoc4a6mr8BDzTJY47LJhkJ8UB7WEGuduB
* ext prv: xprv9s21ZrQH143K31xYSDQpPDxsXRTUcvj2iNHm5NUtrGiGG5e2DtALGdso3pGz6ssrdK4PFmM8NSpSBHNqPqm55Qn3LqFtT2emdEXVYsCzC2U
* [Chain m/0]
* ext pub: xpub69H7F5d8KSRgmmdJg2KhpAK8SR3DjMwAdkxj3ZuxV27CprR9LgpeyGmXUbC6wb7ERfvrnKZjXoUmmDznezpbZb7ap6r1D3tgFxHmwMkQTPH
* ext prv: xprv9vHkqa6EV4sPZHYqZznhT2NPtPCjKuDKGY38FBWLvgaDx45zo9WQRUT3dKYnjwih2yJD9mkrocEZXo1ex8G81dwSM1fwqWpWkeS3v86pgKt
* [Chain m/0/2147483647']
* ext pub: xpub6ASAVgeehLbnwdqV6UKMHVzgqAG8Gr6riv3Fxxpj8ksbH9ebxaEyBLZ85ySDhKiLDBrQSARLq1uNRts8RuJiHjaDMBU4Zn9h8LZNnBC5y4a
* ext prv: xprv9wSp6B7kry3Vj9m1zSnLvN3xH8RdsPP1Mh7fAaR7aRLcQMKTR2vidYEeEg2mUCTAwCd6vnxVrcjfy2kRgVsFawNzmjuHc2YmYRmagcEPdU9
* [Chain m/0/2147483647'/1]
* ext pub: xpub6DF8uhdarytz3FWdA8TvFSvvAh8dP3283MY7p2V4SeE2wyWmG5mg5EwVvmdMVCQcoNJxGoWaU9DCWh89LojfZ537wTfunKau47EL2dhHKon
* ext prv: xprv9zFnWC6h2cLgpmSA46vutJzBcfJ8yaJGg8cX1e5StJh45BBciYTRXSd25UEPVuesF9yog62tGAQtHjXajPPdbRCHuWS6T8XA2ECKADdw4Ef
* [Chain m/0/2147483647'/1/2147483646']
* ext pub: xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL
* ext prv: xprvA1RpRA33e1JQ7ifknakTFpgNXPmW2YvmhqLQYMmrj4xJXXWYpDPS3xz7iAxn8L39njGVyuoseXzU6rcxFLJ8HFsTjSyQbLYnMpCqE2VbFWc
* [Chain m/0/2147483647'/1/2147483646'/2]
* ext pub: xpub6FnCn6nSzZAw5Tw7cgR9bi15UV96gLZhjDstkXXxvCLsUXBGXPdSnLFbdpq8p9HmGsApME5hQTZ3emM2rnY5agb9rXpVGyy3bdW6EEgAtqt
* ext prv: xprvA2nrNbFZABcdryreWet9Ea4LvTJcGsqrMzxHx98MMrotbir7yrKCEXw7nadnHM8Dq38EGfSh6dqA9QWTyefMLEcBYJUuekgW4BYPJcr9E7j

==Implementations==

A Python implementation is available at https://github.com/richardkiss/pycoin

A Java implementation is available at https://github.com/bitsofproof/supernode/blob/1.1/api/src/main/java/com/bitsofproof/supernode/api/ExtendedKey.java

A C++ implementation is available at https://github.com/CodeShark/CoinClasses/tree/master/tests/hdwallets

==Acknowledgements==

* Gregory Maxwell for the original idea of type-2 deterministic wallets, and many discussions about it.
* Alan Reiner for the implementation of this scheme in Armory, and the suggestions that followed from that.
* Mike Caldwell for the version bytes to obtain human-recognizable Base58 strings.

BIP 0032

2013-10-08T10:48:13Z

CodeShark:

{{bip}}

RECENT CHANGES:
* [16 Apr 2013] Added private derivation for i >= 0x80000000 (less risk of parent private key leakage)
* [30 Apr 2013] Switched from multiplication by I_L to addition of I_L (faster, easier implementation)
* [25 May 2013] Added test vectors

<pre>
BIP: 32
Title: Hierarchical Deterministic Wallets
Author: Pieter Wuille
Status: Accepted
Type: Informational
Created: 11-02-2012
</pre>

==Abstract==

This document describes [[Deterministic Wallet|hierarchical determinstic wallets]] (or "HD Wallets"): wallets which can be shared partially or entirely with different systems, each with or without the ability to spend coins.

The specification is intended to set a standard for deterministic wallets that can be interchanged between different clients. Although the wallets described here have many features, not all are required by supporting clients.

The specification consists of two parts. In a first part, a system for deriving a tree of keypairs from a single seed is presented. The second part demonstrates how to build a wallet structure on top of such a tree.

==Motivation==

The Bitcoin reference client uses randomly generated keys. In order to avoid the necessity for a backup after every transaction, (by default) 100 keys are cached in a pool of reserve keys. Still, these wallets are not intended to be shared and used on several systems simultaneously. They support hiding their private keys by using the wallet encrypt feature and not sharing the password, but such "neutered" wallets lose the power to generate public keys as well.

Deterministic wallets do not require such frequent backups, and elliptic curve mathematics permit schemes where one can calculate the public keys without revealing the private keys. This permits for example a webshop business to let its webserver generate fresh addresses (public key hashes) for each order or for each customer, without giving the webserver access to the corresponding private keys (which are required for spending the received funds).

However, deterministic wallets typically consist of a single "chain" of keypairs. The fact that there is only one chain means that sharing a wallet happens on an all-or-nothing basis. However, in some cases one only wants some (public) keys to be shared and recoverable. In the example of a webshop, the webserver does not need access to all public keys of the merchant's wallet; only to those addresses which are used to receive customer's payments, and not for example the change addresses that are generated when the merchant spends money. Hierarchical deterministic wallets allow such selective sharing by supporting multiple keypair chains, derived from a single root.

==Specification: Key derivation==

===Conventions===

In the rest of this text we will assume the public key cryptography used in Bitcoin, namely elliptic curve cryptography using the field and curve parameters defined by secp256k1 (http://www.secg.org/index.php?action=secg,docs_secg). Variables below are either:
* integers modulo the order of the curve (referred to as n), serialized as 32 bytes, most significant byte first.
* coordinates of points on the curve, serialized as specified in SEC1 in compressed form: [0x02 or 0x03] + 32 byte x coordinate), where the header byte depends on the parity of the omitted y coordinate.
* byte sequences

We shall denote the compressed form of point P by χ(P), which for secp256k1 will always be 33 bytes long.

Addition (+) of two coordinates is defined as application of the EC group operation. Multiplication (*) of an integer and a coordinate is defined as repeated application of the EC group operation. The generator element of the curve is called G. The public key K corresponding to the private key k is calculated as k*G. We do not distinguish between numbers or coordinates and their serialization as byte sequences.

===Extended keys===

In what follows, we will define a function that derives a number of child keys from a parent key. In order to prevent these from depending solely on the key itself, we extend both private and public keys first with an extra 256 bits of entropy. This extension, called the chain code, is identical for corresponding private and public keys, and consists of 32 bytes.

We represent an extended private key as (k, c), with k the normal private key, and c the chain code. An extended public key is represented as (K, c), with K = k*G and c the chain code.

===Child key derivation functions===

We allow for two different types of derivation: private and public.
* Private derivation: knowledge of the private key kpar and cpar is required to compute both ki and Ki.
* Public derivation: knowledge of the public key Kpar and cpar suffices to compute Ki (but not ki).

We define the private and public child key derivation functions:
* CKD((kpar, cpar), i) → (ki, ci), defined for both private and public derivation.
* CKD'((Kpar, cpar), i) → (Ki, ci), defined only for public derivation.

We use the most significant bit of i to specify which type of derivation to use. i is encoded as a 32 bit unsigned integer, most significant byte first; '||' represents concatenation.

====Private child key derivation====

To define CKD((kpar, cpar), i) → (ki, ci):
* Check whether the highest bit (0x80000000) of i is set:
** If 1, private derivation is used: let I = HMAC-SHA512(Key = cpar, Data = 0x00 || kpar || i) [Note: The 0x00 pads the private key to make it 33 bytes long.]
** If 0, public derivation is used: let I = HMAC-SHA512(Key = cpar, Data = χ(kpar*G) || i)
* Split I = IL || IR into two 32-byte sequences, IL and IR.
* ki = IL + kpar (mod n).
* ci = IR.
In case IL ≥ n or ki = 0, the resulting key is invalid, and one should proceed with the next value for i.
[Note: this has probability lower than 1 in 2127.]

====Public child key derivation====

To define CKD'((Kpar, cpar), i) → (Ki, ci):
* Check whether the highest bit (0x80000000) of i is set:
** If 1, return error
** If 0, let I = HMAC-SHA512(Key = cpar, Data = χ(Kpar) || i)
* Split I = IL || IR into two 32-byte sequences, IL and IR.
* Ki = (IL + Kpar)*G = IL*G + Kpar
* ci = IR.
In case IL ≥ n or Ki is the point at infinity, the resulting key is invalid, and one should proceed with the next value for i.

Note that the extended public key corresponding to the evaluation of CKD(kext, i) with public derivation (so with i < 0x80000000) is identical to the evaluation of CKD'(Kext, i), with Kext the extended public key corresponding to kext. Symbolically, CKD((k, c), i)*G = CKD'((k*G, c), i). This implies that CKD' can be used to derive all public keys corresponding to the private keys that CKD would find. It cannot be used to retrieve the private keys, however.

The HMAC-SHA512 function is specified in [http://tools.ietf.org/html/rfc4231 RFC 4231].

===The key tree===

The next step is cascading several CKD constructions to build a tree. We start with one root, the master extended key m. By evaluating CKD(m,i) for several values of i, we get a number of first-degree derivative nodes. As each of these is again an extended key, CKD can be applied to those as well. To shorten notation, we will write CKD(CKD(CKD(m,0x8000003),0x2),0x5) as m/3'/2/5 now.

Each leaf node in the tree corresponds to an actual keypair, while the internal nodes correspond to the collection of keypairs that descends from them. The chain codes of the leaf nodes are ignored, and only their embedded private or public key is used. Because of this construction, knowing an extended private key allows reconstruction of all descendant private keys and public keys, and knowing an extended public keys allows reconstruction of all descendant public keys derived using public derivation.

===Key identifiers===

Extended keys can be identified by the Hash160 (RIPEMD160 after SHA256) of the serialized public key, ignoring the chain code. This corresponds exactly to the data used in traditional Bitcoin addresses. It is not advised to represent this data in base58 format though, as it may be interpreted as an address that way (and wallet software is not required to accept payment to the chain key itself).

The first 32 bits of the identifier are called the fingerprint.

===Serialization format===

Extended public and private keys are serialized as follows:
* 4 byte: version bytes (mainnet: 0x0488B21E public, 0x0488ADE4 private; testnet: 0x043587CF public, 0x04358394 private)
* 1 byte: depth: 0x00 for master nodes, 0x01 for level-1 descendants, ....
* 4 bytes: the fingerprint of the parent's key (0x00000000 if master key)
* 4 bytes: child number. This is the number i in xi = xpar/i, with xi the key being serialized. This is encoded in MSB order. (0x00000000 if master key)
* 32 bytes: the chain code
* 33 bytes: the public key or private key data (0x02 + X or 0x03 + X for public keys, 0x00 + k for private keys)

This 78 byte structure can be encoded like other Bitcoin data in Base58, by first adding 32 checksum bits (derived from the double SHA-256 checksum), and then converting to the Base58 representation. This results in a Base58-encoded string of up to 112 characters. Because of the choice of the version bytes, the Base58 representation will start with "xprv" or "xpub" on mainnet, "tprv" or "tpub" on testnet.

Note that the fingerprint of the parent only serves as a fast way to detect parent and child nodes in software, and software must be willing to deal with collisions. Internally, the full 160-bit identifier could be used.

When importing a serialized extended public key, implementations must verify whether the X coordinate in the public key data corresponds to a point on the curve. If not, the extended public key is invalid.

===Master key generation===

The total number of possible extended keypairs is almost 2^512, but the produced keys are only 256 bits long, and offer about half of that in terms of security. Therefore, master keys are not generated directly, but instead from a potentially short seed value.

* Generate a seed S of a chosen length (at least 128 bits, but 256 is advised) from a (P)RNG.
* Calculate I = HMAC-SHA512(key="Bitcoin seed", msg=S)
* Split I into two 32-byte sequences, IL and IR.
* Use IL as master secret key, and IR as master chain code.
In case IL is 0 or >=n, the master key is invalid.

[[File:BIP32-derivation.png]]

==Specification: Wallet structure==

The previous sections specified key trees and their nodes. The next step is imposing a wallet structure on this tree. The layout defined in this section is a default only, though clients are encouraged to mimick it for compatibility, even if not all features are supported.

An HDW is organized as several 'accounts'. Accounts are numbered, the default account ("") being number 0. Clients are not required to support more than one account - if not, they only use the default account.

Each account is composed of two keypair chains: an internal and an external one. The external [[keychain]] is used to generate new public addresses, while the internal keychain is used for all other operations (change addresses, generation addresses, ..., anything that doesn't need to be communicated). Clients that do not support separate keychains for these should use the external one for everything.

* m/i'/0/k corresponds to the k'th keypair of the external chain of account number i of the HDW derived from master m.
* m/i'/1/k corresponds to the k'th keypair of the internal chain of account number i of the HDW derived from master m.

===Use cases===

====Full wallet sharing: m====

In cases where two systems need to access a single shared wallet, and both need to be able to perform spendings, one needs to share the master private extended key. Nodes can keep a pool of N look-ahead keys cached for external chains, to watch for incoming payments. The look-ahead for internal chains can be very small, as no gaps are to be expected here. An extra look-ahead could be active for the first unused account's chains - triggering the creation of a new account when used. Note that the name of the account will still need to be entered manually and cannot be synchronized via the block chain.

====Audits: M====

In case an auditor needs full access to the list of incoming and outgoing payments, one can share the master public extended key. This will allow the auditor to see all transactions from and to the wallet, in all accounts, but not a single secret key.

====Per-office balances: m/i'====

When a business has several independent offices, they can all use wallets derived from a single master. This will allow the headquarters to maintain a super-wallet that sees all incoming and outgoing transactions of all offices, and even permit moving money between the offices.

====Recurrent business-to-business transactions: M/i'/0====

In case two business partners often transfer money, one can use the extended public key for the external chain of a specific account (M/i'/0) as a sort of "super address", allowing frequent transactions that cannot (easily) be associated, but without needing to request a new address for each payment.
Such a mechanism could also be used by mining pool operators as variable payout address.

====Unsecure money receiver: M/i'/0====

When an unsecure webserver is used to run an e-commerce site, it needs to know public addresses that be used to receive payments. The webserver only needs to know the public extended key of the external chain of a single account. This means someone illegally obtaining access to the webserver can at most see all incoming payments, but will not (trivially) be able to distinguish outgoing transactions, nor see payments received by other webservers if there are several ones.

==Compatibility==

To comply with this standard, a client must at least be able to import an extended public or private key, to give access to its direct descendants as wallet keys. The wallet structure (master/account/chain/subchain) presented in the second part of the specification is advisory only, but is suggested as a minimal structure for easy compatibility - even when no separate accounts or distinction between internal and external chains is made. However, implementations may deviate from it for specific needs; more complex applications may call for a more complex tree structure.

==Security==

In addition to the expectations from the EC public-key cryptography itself:
* Given a public key K, an attacker cannot find the corresponding private key more efficiently than by solving the EC discrete logarithm problem (assumed to require 2128 group operations).
the intended security properties of this standard are:
* Given a child extended private key (ki,ci) and the integer i, an attacker cannot find the parent private key kpar more efficiently than a 2256 brute force of HMAC-SHA512.
* Given any number (2 <= N <= 232-1) of (index, extended private key) tuples (ij,(pj,cj)), with distinct ij's, determining whether they are derived from a common parent extended private key (i.e., whether there exists a (ppar,cpar) such that for each j in [0..N-1] CKD((ppar,cpar),ij)=(pj,cj)), cannot be done more efficiently than a 2256 brute force of HMAC-SHA512.
Note however that the following properties does not exist:
* Given a parent extended public key (Kpar,cpar) and a child public key (Ki), it is hard to find i.
* Given a parent extended public key (Kpar,cpar) and a child private key (ki) using public derivation, it is hard to find kpar.

Private and public keys must be kept safe as usual. Leaking a private key means access to coins - leaking a public key can mean loss of privacy.

Somewhat more care must be taken regarding extended keys, as these correspond to an entire (sub)tree of keys. One weakness that may not be immediately obvious, is that knowledge of the extended public key + a private key descending from it is equivalent to knowing the extended private key (i.e., every private and public key) in case public derivation is used. This means that extended public keys must be treated more carefully than regular public keys. This is the reason why accounts at the first level of the default wallet layout use private derivation, so a leak of account-specific (or below) private key never risks compromising the master.

==Test Vectors==

For more detailed information about these (such as intermediate values and other representations), see [[BIP_0032_TestVectors]]

Test vector 1

Master (hex): 000102030405060708090a0b0c0d0e0f
* [Chain m]
* ext pub: xpub661MyMwAqRbcFtXgS5sYJABqqG9YLmC4Q1Rdap9gSE8NqtwybGhePY2gZ29ESFjqJoCu1Rupje8YtGqsefD265TMg7usUDFdp6W1EGMcet8
* ext prv: xprv9s21ZrQH143K3QTDL4LXw2F7HEK3wJUD2nW2nRk4stbPy6cq3jPPqjiChkVvvNKmPGJxWUtg6LnF5kejMRNNU3TGtRBeJgk33yuGBxrMPHi
* [Chain m/0']
* ext pub: xpub68Gmy5EdvgibQVfPdqkBBCHxA5htiqg55crXYuXoQRKfDBFA1WEjWgP6LHhwBZeNK1VTsfTFUHCdrfp1bgwQ9xv5ski8PX9rL2dZXvgGDnw
* ext prv: xprv9uHRZZhk6KAJC1avXpDAp4MDc3sQKNxDiPvvkX8Br5ngLNv1TxvUxt4cV1rGL5hj6KCesnDYUhd7oWgT11eZG7XnxHrnYeSvkzY7d2bhkJ7
* [Chain m/0'/1]
* ext pub: xpub6ASuArnXKPbfEwhqN6e3mwBcDTgzisQN1wXN9BJcM47sSikHjJf3UFHKkNAWbWMiGj7Wf5uMash7SyYq527Hqck2AxYysAA7xmALppuCkwQ
* ext prv: xprv9wTYmMFdV23N2TdNG573QoEsfRrWKQgWeibmLntzniatZvR9BmLnvSxqu53Kw1UmYPxLgboyZQaXwTCg8MSY3H2EU4pWcQDnRnrVA1xe8fs
* [Chain m/0'/1/2']
* ext pub: xpub6D4BDPcP2GT577Vvch3R8wDkScZWzQzMMUm3PWbmWvVJrZwQY4VUNgqFJPMM3No2dFDFGTsxxpG5uJh7n7epu4trkrX7x7DogT5Uv6fcLW5
* ext prv: xprv9z4pot5VBttmtdRTWfWQmoH1taj2axGVzFqSb8C9xaxKymcFzXBDptWmT7FwuEzG3ryjH4ktypQSAewRiNMjANTtpgP4mLTj34bhnZX7UiM
* [Chain m/0'/1/2'/2]
* ext pub: xpub6FHa3pjLCk84BayeJxFW2SP4XRrFd1JYnxeLeU8EqN3vDfZmbqBqaGJAyiLjTAwm6ZLRQUMv1ZACTj37sR62cfN7fe5JnJ7dh8zL4fiyLHV
* ext prv: xprvA2JDeKCSNNZky6uBCviVfJSKyQ1mDYahRjijr5idH2WwLsEd4Hsb2Tyh8RfQMuPh7f7RtyzTtdrbdqqsunu5Mm3wDvUAKRHSC34sJ7in334
* [Chain m/0'/1/2'/2/1000000000]
* ext pub: xpub6H1LXWLaKsWFhvm6RVpEL9P4KfRZSW7abD2ttkWP3SSQvnyA8FSVqNTEcYFgJS2UaFcxupHiYkro49S8yGasTvXEYBVPamhGW6cFJodrTHy
* ext prv: xprvA41z7zogVVwxVSgdKUHDy1SKmdb533PjDz7J6N6mV6uS3ze1ai8FHa8kmHScGpWmj4WggLyQjgPie1rFSruoUihUZREPSL39UNdE3BBDu76

Test vector 2

Master (hex): fffcf9f6f3f0edeae7e4e1dedbd8d5d2cfccc9c6c3c0bdbab7b4b1aeaba8a5a29f9c999693908d8a8784817e7b7875726f6c696663605d5a5754514e4b484542
* [Chain m]
* ext pub: xpub661MyMwAqRbcFW31YEwpkMuc5THy2PSt5bDMsktWQcFF8syAmRUapSCGu8ED9W6oDMSgv6Zz8idoc4a6mr8BDzTJY47LJhkJ8UB7WEGuduB
* ext prv: xprv9s21ZrQH143K31xYSDQpPDxsXRTUcvj2iNHm5NUtrGiGG5e2DtALGdso3pGz6ssrdK4PFmM8NSpSBHNqPqm55Qn3LqFtT2emdEXVYsCzC2U
* [Chain m/0]
* ext pub: xpub69H7F5d8KSRgmmdJg2KhpAK8SR3DjMwAdkxj3ZuxV27CprR9LgpeyGmXUbC6wb7ERfvrnKZjXoUmmDznezpbZb7ap6r1D3tgFxHmwMkQTPH
* ext prv: xprv9vHkqa6EV4sPZHYqZznhT2NPtPCjKuDKGY38FBWLvgaDx45zo9WQRUT3dKYnjwih2yJD9mkrocEZXo1ex8G81dwSM1fwqWpWkeS3v86pgKt
* [Chain m/0/2147483647']
* ext pub: xpub6ASAVgeehLbnwdqV6UKMHVzgqAG8Gr6riv3Fxxpj8ksbH9ebxaEyBLZ85ySDhKiLDBrQSARLq1uNRts8RuJiHjaDMBU4Zn9h8LZNnBC5y4a
* ext prv: xprv9wSp6B7kry3Vj9m1zSnLvN3xH8RdsPP1Mh7fAaR7aRLcQMKTR2vidYEeEg2mUCTAwCd6vnxVrcjfy2kRgVsFawNzmjuHc2YmYRmagcEPdU9
* [Chain m/0/2147483647'/1]
* ext pub: xpub6DF8uhdarytz3FWdA8TvFSvvAh8dP3283MY7p2V4SeE2wyWmG5mg5EwVvmdMVCQcoNJxGoWaU9DCWh89LojfZ537wTfunKau47EL2dhHKon
* ext prv: xprv9zFnWC6h2cLgpmSA46vutJzBcfJ8yaJGg8cX1e5StJh45BBciYTRXSd25UEPVuesF9yog62tGAQtHjXajPPdbRCHuWS6T8XA2ECKADdw4Ef
* [Chain m/0/2147483647'/1/2147483646']
* ext pub: xpub6ERApfZwUNrhLCkDtcHTcxd75RbzS1ed54G1LkBUHQVHQKqhMkhgbmJbZRkrgZw4koxb5JaHWkY4ALHY2grBGRjaDMzQLcgJvLJuZZvRcEL
* ext prv: xprvA1RpRA33e1JQ7ifknakTFpgNXPmW2YvmhqLQYMmrj4xJXXWYpDPS3xz7iAxn8L39njGVyuoseXzU6rcxFLJ8HFsTjSyQbLYnMpCqE2VbFWc
* [Chain m/0/2147483647'/1/2147483646'/2]
* ext pub: xpub6FnCn6nSzZAw5Tw7cgR9bi15UV96gLZhjDstkXXxvCLsUXBGXPdSnLFbdpq8p9HmGsApME5hQTZ3emM2rnY5agb9rXpVGyy3bdW6EEgAtqt
* ext prv: xprvA2nrNbFZABcdryreWet9Ea4LvTJcGsqrMzxHx98MMrotbir7yrKCEXw7nadnHM8Dq38EGfSh6dqA9QWTyefMLEcBYJUuekgW4BYPJcr9E7j

==Implementations==

A Python implementation is available at https://github.com/richardkiss/pycoin

A Java implementation is available at https://github.com/bitsofproof/supernode/blob/1.1/api/src/main/java/com/bitsofproof/supernode/api/ExtendedKey.java

A C++ implementation is available at https://github.com/CodeShark/CoinClasses/tree/master/tests

==Acknowledgements==

* Gregory Maxwell for the original idea of type-2 deterministic wallets, and many discussions about it.
* Alan Reiner for the implementation of this scheme in Armory, and the suggestions that followed from that.
* Mike Caldwell for the version bytes to obtain human-recognizable Base58 strings.

Protocol documentation

2013-08-28T09:19:06Z

CodeShark: /* pong */

Sources:
* [[Original Bitcoin client]] source

Type names used in this documentation are from the C99 standard.

For protocol used in mining, see [[Getwork]].

==Common standards==

=== Hashes ===

Usually, when a hash is computed within bitcoin, it is computed twice. Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-256] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when a shorter hash is desirable (for example when creating a bitcoin address).

Example of double-SHA-256 encoding of string "hello":

hello
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round of sha-256)
9595c9df90075148eb06860365df33584b75bff782a510c6cd4883a419833d50 (second round of sha-256)

For bitcoin addresses (RIPEMD-160) this would give:

hello
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round is sha-256)
b6a9c8c230722b7c748331a8b450f05566dc7d0f (with ripemd-160)

=== Merkle Trees ===

Merkle trees are binary trees of hashes. Merkle trees in bitcoin use a '''double''' SHA-256, the SHA-256 hash of the SHA-256 hash of something.

If, when forming a row in the tree (other than the root of the tree), it would have an odd number of elements, the final double-hash is duplicated to ensure that the row has an even number of hashes.

First form the bottom row of the tree with the ordered double-SHA-256 hashes of the byte streams of the transactions in the block.

Then the row above it consists of half that number of hashes. Each entry is the double-SHA-256 of the 64-byte concatenation of the corresponding two hashes below it in the tree.

This procedure repeats recursively until we reach a row consisting of just a single double-hash. This is the '''merkle root''' of the tree.

For example, imagine a block with three transactions ''a'', ''b'' and ''c''. The merkle tree is:

d1 = dhash(a)
d2 = dhash(b)
d3 = dhash(c)
d4 = dhash(c) # a, b, c are 3. that's an odd number, so we take the c twice

d5 = dhash(d1 concat d2)
d6 = dhash(d3 concat d4)

d7 = dhash(d5 concat d6)

where

dhash(a) = sha256(sha256(a))

''d7'' is the merkle root of the 3 transactions in this block.

Note: Hashes in Merkle Tree displayed in the [[Block Explorer]] are of little-endian notation. For some implementations and [http://www.fileformat.info/tool/hash.htm calculations], the bits need to be reversed before they are hashed, and again after the hashing operation.

=== Signatures ===

Bitcoin uses [http://en.wikipedia.org/wiki/Elliptic_curve_cryptography Elliptic Curve] [http://en.wikipedia.org/wiki/Digital_Signature_Algorithm Digital Signature Algorithm] ([http://en.wikipedia.org/wiki/Elliptic_Curve_DSA ECDSA]) to sign transactions.

For ECDSA the secp256k1 curve from http://www.secg.org/collateral/sec2_final.pdf is used.

Public keys (in scripts) are given as 04 <x> <y> where ''x'' and ''y'' are 32 byte big-endian integers representing the coordinates of a point on the curve or in compressed form given as <sign> <x> where <sign> is 0x02 if ''y'' is even and 0x03 if ''y'' is odd.

Signatures use [http://en.wikipedia.org/wiki/Distinguished_Encoding_Rules DER encoding] to pack the ''r'' and ''s'' components into a single byte stream (this is also what OpenSSL produces by default).

=== Transaction Verification ===
Transactions are cryptographically signed records that reassign ownership of Bitcoins to new addresses. Transactions have ''inputs'' - records which reference the funds from other previous transactions - and ''outputs'' - records which determine the new owner of the transferred Bitcoins, and which will be referenced as inputs in future transactions as those funds are respent.

Each ''input'' must have a cryptographic digital signature that unlocks the funds from the prior transaction. Only the person possessing the appropriate [[private key]] is able to create a satisfactory signature; this in effect ensures that funds can only be spent by their owners.

Each ''output'' determines which Bitcoin address (or other criteria, see [[Scripting]]) is the recipient of the funds.

In a transaction, the sum of all inputs must be equal to or greater than the sum of all outputs. If the inputs exceed the outputs, the difference is considered a [[transaction fee]], and is redeemable by whoever first includes the transaction into the block chain.

A special kind of transaction, called a [[coinbase transaction]], has no inputs. It is created by [[miners]], and there is one coinbase transaction per block. Because each block comes with a reward of newly created Bitcoins (e.g. 50 BTC for the first 210,000 blocks), the first transaction of a block is, with few exceptions, the transaction that grants those coins to their recipient (the miner). In addition to the newly created Bitcoins, the coinbase transaction is also used for assigning the recipient of any transaction fees that were paid within the other transactions being included in the same block. The coinbase transaction can assign the entire reward to a single Bitcoin address, or split it in portions among multiple addresses, just like any other transaction. Coinbase transactions always contain outputs totaling the sum of the block reward plus all transaction fees collected from the other transactions in the same block.

The [[coinbase transaction]] in block zero cannot be spent. This is due to a quirk of the reference client implementation that would open the potential for a block chain fork if some nodes accepted the spend and others did not<ref>[http://bitcointalk.org/index.php?topic=119645.msg1288552#msg1288552 Block 0 Network Fork]</ref>.

Most Bitcoin outputs encumber the newly transferred coins with a single ECDSA private key. The actual record saved with inputs and outputs isn't necessarily a key, but a ''script''. Bitcoin uses an interpreted scripting system to determine whether an output's criteria have been satisfied, with which more complex operations are possible, such as outputs that require two ECDSA signatures, or two-of-three-signature schemes. An output that references a single Bitcoin address is a ''typical'' output; an output actually contains this information in the form of a script that requires a single ECDSA signature (see [[OP_CHECKSIG]]). The output script specifies what must be provided to unlock the funds later, and when the time comes in the future to spend the transaction in another input, that input must provide all of the thing(s) that satisfy the requirements defined by the original output script.

=== Addresses ===

A bitcoin address is in fact the hash of a ECDSA public key, computed this way:

Version = 1 byte of 0 (zero); on the test network, this is 1 byte of 111
Key hash = Version concatenated with RIPEMD-160(SHA-256(public key))
Checksum = 1st 4 bytes of SHA-256(SHA-256(Key hash))
Bitcoin Address = Base58Encode(Key hash concatenated with Checksum)

The Base58 encoding used is home made, and has some differences. Especially, leading zeroes are kept as single zeroes when conversion happens.

== Common structures ==

Almost all integers are encoded in little endian. Only IP or port number are encoded big endian.

=== Message structure ===

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown
|-
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)
|-
| 4 || length || uint32_t || Length of payload in number of bytes
|-
| 4 || checksum || uint32_t || First 4 bytes of sha256(sha256(payload))
|-
| ? || payload || uchar[] || The actual data
|}

Known magic values:

{|class="wikitable"
! Network !! Magic value !! Sent over wire as
|-
| main || 0xD9B4BEF9 || F9 BE B4 D9
|-
| testnet || 0xDAB5BFFA || FA BF B5 DA
|-
| testnet3 || 0x0709110B || 0B 11 09 07
|-
| namecoin || 0xFEB4BEF9 || F9 BE B4 FE
|}

=== Variable length integer ===

Integer can be encoded depending on the represented value to save space.
Variable length integers always precede an array/vector of a type of data that may vary in length.
Longer numbers are encoded in little endian.

{|class="wikitable"
! Value !! Storage length !! Format
|-
| < 0xfd || 1 || uint8_t
|-
| <= 0xffff || 3 || 0xfd followed by the length as uint16_t
|-
| <= 0xffffffff || 5 || 0xfe followed by the length as uint32_t
|-
| - || 9 || 0xff followed by the length as uint64_t
|}

If you're reading the Satoshi client code (BitcoinQT) it refers to this as a "CompactSize". Modern BitcoinQT has also CVarInt class which implements even more compact integer for the purpose of local storage (which is incompatible with "CompactSize" described here). CVarInt is not a part of the protocol.

=== Variable length string ===

Variable length string can be stored using a variable length integer followed by the string itself.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || length || [[Protocol_specification#Variable_length_integer|var_int]] || Length of the string
|-
| ? || string || char[] || The string itself (can be empty)
|}

=== Network address ===

When a network address is needed somewhere, this structure is used. This protocol and structure supports IPv6, '''but note that the original client currently only supports IPv4 networking'''. Network addresses are not prefixed with a timestamp in the version message.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || time || uint32 || the Time (version >= 31402)
|-
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]
|-
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The original client only supports IPv4 and only reads the last 4 bytes to get the IPv4 address. However, the IPv4 address is written into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).
|-
| 2 || port || uint16_t || port number, network byte order
|}

Hexdump example of Network address structure

<pre>
0000 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
0010 00 00 FF FF 0A 00 00 01 20 8D ........ .

Network address:
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK: see services listed under version command)
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv6: ::ffff:10.0.0.1 or IPv4: 10.0.0.1
20 8D - Port 8333
</pre>

=== Inventory Vectors ===

Inventory vectors are used for notifying other nodes about objects they have or data which is being requested.

Inventory vectors consist of the following data format:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || type || uint32_t || Identifies the object type linked to this inventory
|-
| 32 || hash || char[32] || Hash of the object
|}

The object type is currently defined as one of the following possibilities:

{|class="wikitable"
! Value !! Name !! Description
|-
| 0 || ERROR || Any data of with this number may be ignored
|-
| 1 || MSG_TX || Hash is related to a transaction
|-
| 2 || MSG_BLOCK || Hash is related to a data block
|}

Other Data Type values are considered reserved for future implementations.

=== Block Headers ===

Block headers are sent in a headers packet in response to a getheaders message.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || uint32_t || Block version information, based upon the software version creating this block
|-
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references
|-
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block
|-
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Will overflow in 2106<ref>http://en.wikipedia.org/wiki/Unix_time#Notable.C2.A0events.C2.A0in.C2.A0Unix.C2.A0time</ref>)
|-
| 4 || bits || uint32_t || The calculated difficulty target being used for this block
|-
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes
|-
| 1 || txn_count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of transaction entries, this value is always 0
|}

== Message types ==

=== version ===

When a node creates an outgoing connection, it will immediately [[Version Handshake|advertise]] its version. The remote node will respond with its version. No futher communication is possible until both peers have exchanged their version.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || int32_t || Identifies protocol version being used by the node
|-
| 8 || services || uint64_t || bitfield of features to be enabled for this connection
|-
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds
|-
| 26 || addr_recv || net_addr || The network address of the node receiving this message
|-
|colspan="4"| version >= 106
|-
| 26 || addr_from || net_addr || The network address of the node emitting this message
|-
| 8 || nonce || uint64_t || Node random nonce, randomly generated every time a version packet is sent. This nonce is used to detect connections to self.
|-
| ? || user_agent || [[#Variable length string|var_str]] || [[BIP_0014|User Agent]] (0x00 if string is 0 bytes long)
|-
| 4 || start_height || int32_t || The last block received by the emitting node
|-
| 1 || relay || bool || Whether the remote peer should announce relayed transactions or not, see [[BIP 0037]], since version >= 70001
|}

A "verack" packet shall be sent if the version packet was accepted.

The following services are currently assigned:

{|class="wikitable"
! Value !! Name !! Description
|-
| 1 || NODE_NETWORK || This node can be asked for full blocks instead of just headers.
|}

Hexdump example of version message (OBSOLETE EXAMPLE. This example lacks a checksum and user-agent):
<pre>
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................
0040 20 8D 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,
0060 3A B4 57 13 00 55 81 01 00 :.W..U...

Message header:
F9 BE B4 D9 - Main network magic bytes
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command
55 00 00 00 - Payload is 85 bytes long
- No checksum in version message until 20 February 2012. See https://bitcointalk.org/index.php?topic=55852.0
Version message:
9C 7C 00 00 - 31900 (version 0.3.19)
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)
E6 15 10 4D 00 00 00 00 - Mon Dec 20 21:50:14 EST 2010
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 20 8D - Recipient address info - see Network Address
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D - Sender address info - see Network Address
DD 9D 20 2C 3A B4 57 13 - Node random unique ID
00 - "" sub-version string (string is 0 bytes long)
55 81 01 00 - Last block sending node has is block #98645
</pre>

And here's a modern (60002) protocol version client advertising itself to a local peer...

Newer protocol includes the checksum now, this is from a mainline (satoshi) client during
an outgoing connection to another local client, notice that it does not fill out the
address information at all when the source or destination is "unroutable".

<pre>

0000 f9 be b4 d9 76 65 72 73 69 6f 6e 00 00 00 00 00 ....version.....
0010 64 00 00 00 35 8d 49 32 62 ea 00 00 01 00 00 00 d...5.I2b.......
0020 00 00 00 00 11 b2 d0 50 00 00 00 00 01 00 00 00 .......P........
0030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ff ff ................
0040 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
0050 00 00 00 00 00 00 00 00 ff ff 00 00 00 00 00 00 ................
0060 3b 2e b3 5d 8c e6 17 65 0f 2f 53 61 74 6f 73 68 ;..]...e./Satosh
0070 69 3a 30 2e 37 2e 32 2f c0 3e 03 00 i:0.7.2/.>..

Message Header:
F9 BE B4 D9 - Main network magic bytes
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command
64 00 00 00 - Payload is 100 bytes long
3B 64 8D 5A - payload checksum

Version message:
62 EA 00 00 - 60002 (protocol version 60002)
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)
11 B2 D0 50 00 00 00 00 - Tue Dec 18 10:12:33 PST 2012
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Recipient address info - see Network Address
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Sender address info - see Network Address
3B 2E B3 5D 8C E6 17 65 - Node ID
0F 2F 53 61 74 6F 73 68 69 3A 30 2E 37 2E 32 2F - "/Satoshi:0.7.2/" sub-version string (string is 15 bytes long)
C0 3E 03 00 - Last block sending node has is block #212672
</pre>

=== verack ===

The ''verack'' message is sent in reply to ''version''. This message consists of only a [[#Message structure|message header]] with the command string "verack".

Hexdump of the verack message:

<pre>
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......
0010 00 00 00 00 5D F6 E0 E2 ........

Message header:
F9 BE B4 D9 - Main network magic bytes
76 65 72 61 63 6B 00 00 00 00 00 00 - "verack" command
00 00 00 00 - Payload is 0 bytes long
5D F6 E0 E2 - Checksum
</pre>

=== addr ===

Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours

Payload:
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+ || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of address entries (max: 1000)
|-
| 30x? || addr_list || (uint32_t + net_addr)[] || Address of other nodes on the network. version < 209 will only read the first one. The uint32_t is a timestamp (see note below).
|}

'''Note''': Starting version 31402, addresses are prefixed with a timestamp. If no timestamp is present, the addresses should not be relayed to other peers, unless it is indeed confirmed they are up.

Hexdump example of ''addr'' message:
<pre>
0000 F9 BE B4 D9 61 64 64 72 00 00 00 00 00 00 00 00 ....addr........
0010 1F 00 00 00 ED 52 39 9B 01 E2 15 10 4D 01 00 00 .....R9.....M...
0020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF ................
0030 FF 0A 00 00 01 20 8D ..... .

Message Header:
F9 BE B4 D9 - Main network magic bytes
61 64 64 72 00 00 00 00 00 00 00 00 - "addr"
1F 00 00 00 - payload is 31 bytes long
ED 52 39 9B - checksum of payload

Payload:
01 - 1 address in this message

Address:
E2 15 10 4D - Mon Dec 20 21:50:10 EST 2010 (only when version is >= 31402)
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK service - see version message)
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv4: 10.0.0.1, IPv6: ::ffff:10.0.0.1 (IPv4-mapped IPv6 address)
20 8D - port 8333
</pre>

=== inv ===

Allows a node to advertise its knowledge of one or more objects. It can be received unsolicited, or in reply to ''getblocks''.

Payload (maximum payload length: 1.8 Megabytes or 50000 entries):

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of inventory entries
|-
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors
|}

=== getdata ===

getdata is used in response to inv, to retrieve the content of a specific object, and is usually sent after receiving an ''inv'' packet, after filtering known elements. It can be used to retrieve transactions, but only if they are in the memory pool or relay set - arbitrary access to transactions in the chain is not allowed to avoid having clients start to depend on nodes having full transaction indexes (which modern nodes do not).

Payload (maximum payload length: 1.8 Megabytes or 50000 entries):

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of inventory entries
|-
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors
|}

=== notfound ===

notfound is a response to a getdata, sent if any requested data items could not be relayed, for example, because the requested transaction was not in the memory pool or relay set.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of inventory entries
|-
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors
|}

=== getblocks ===

Return an ''inv'' packet containing the list of blocks starting right after the last known hash in the block locator object, up to hash_stop or 500 blocks, whichever comes first.

The locator hashes are processed by a node in the order as they appear in the message. If a block hash if found in the node's main chain, the list of it's children is returned back via the ''inv'' message and the remaining locators are ignored, no matter if the requested limit was reached, or not.

To receive the next blocks hashes, one needs to issue getblocks again with a new block locator object. Keep in mind that some clients (specifically the Satoshi client) will gladly provide blocks which are invalid if the block locator object contains a hash on the invalid branch.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || uint32_t || the protocol version
|-
| 1+ || hash count || [[Protocol_specification#Variable_length_integer|var_int]] || number of block locator hash entries
|-
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)
|-
| 32 || hash_stop || char[32] || hash of the last desired block; set to zero to get as many blocks as possible (500)
|}

To create the block locator hashes, keep pushing hashes until you go back to the genesis block. After pushing 10 hashes back, the step backwards doubles every loop:

<pre>
// From libbitcoin which is under AGPL
std::vector<size_t> block_locator_indices(int top_depth)
{
// Start at max_depth
std::vector<size_t> indices;
// Push last 10 indices first
size_t step = 1, start = 0;
for (int i = top_depth; i > 0; i -= step, ++start)
{
if (start >= 10)
step *= 2;
indices.push_back(i);
}
indices.push_back(0);
return indices;
}
</pre>

Note that it is allowed to send in fewer known hashes down to a minimum of just one hash. However, the purpose of the block locator object is to detect a wrong branch in the caller's main chain. If the peer detects that you are off the main chain, it will send in block hashes which are earlier than your last known block. So if you just send in your last known hash and it is off the main chain, the peer starts over at block #1.

=== getheaders ===

Return a ''headers'' packet containing the headers of blocks starting right after the last known hash in the block locator object, up to hash_stop or 2000 blocks, whichever comes first. To receive the next block headers, one needs to issue getheaders again with a new block locator object. The ''getheaders'' command is used by thin clients to quickly download the blockchain where the contents of the transactions would be irrelevant (because they are not ours). Keep in mind that some clients (specifically the Satoshi client) will gladly provide headers of blocks which are invalid if the block locator object contains a hash on the invalid branch.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || uint32_t || the protocol version
|-
| 1+ || hash count || [[Protocol_specification#Variable_length_integer|var_int]] || number of block locator hash entries
|-
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)
|-
| 32 || hash_stop || char[32] || hash of the last desired block header; set to zero to get as many blocks as possible (2000)
|}

For the block locator object in this packet, the same rules apply as for the [[Protocol_specification#getblocks|getblocks]] packet.

=== tx ===

''tx'' describes a bitcoin transaction, in reply to ''getdata''

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || uint32_t || Transaction data format version
|-
| 1+ || tx_in count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of Transaction inputs
|-
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins
|-
| 1+ || tx_out count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of Transaction outputs
|-
| 9+ || tx_out || tx_out[] || A list of 1 or more transaction outputs or destinations for coins
|-
| 4 || lock_time || uint32_t || The block number or timestamp at which this transaction is locked:
{|class="wikitable"
! Value !! Description
|-
| 0 || Always locked
|-
| < 500000000 || Block number at which this transaction is locked
|-
| >= 500000000 || UNIX timestamp at which this transaction is locked
|}
If all TxIn inputs have final (0xffffffff) sequence numbers then lock_time is irrelevant. Otherwise, the transaction may not be added to a block until after lock_time.

|}

TxIn consists of the following fields:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 36 || previous_output || outpoint || The previous output transaction reference, as an OutPoint structure
|-
| 1+ || script length || [[Protocol_specification#Variable_length_integer|var_int]] || The length of the signature script
|-
| ? || signature script || uchar[] || Computational Script for confirming transaction authorization
|-
| 4 || [http://bitcoin.stackexchange.com/q/2025/323 sequence] || uint32_t || Transaction version as defined by the sender. Intended for "replacement" of transactions when information is updated before inclusion into a block.
|}

The OutPoint structure consists of the following fields:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 32 || hash || char[32] || The hash of the referenced transaction.
|-
| 4 || index || uint32_t || The index of the specific output in the transaction. The first output is 0, etc.
|}

The Script structure consists of a series of pieces of information and operations related to the value of the transaction.

(Structure to be expanded in the future… see script.h and script.cpp and [[Script]] for more information)

The TxOut structure consists of the following fields:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8 || value || int64_t || Transaction Value
|-
| 1+ || pk_script length || [[Protocol_specification#Variable_length_integer|var_int]] || Length of the pk_script
|-
| ? || pk_script || uchar[] || Usually contains the public key as a Bitcoin script setting up conditions to claim this output.
|}

Example ''tx'' message:
<pre>
000000 F9 BE B4 D9 74 78 00 00 00 00 00 00 00 00 00 00 ....tx..........
000010 02 01 00 00 E2 93 CD BE 01 00 00 00 01 6D BD DB .............m..
000020 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D 12 66 E9 .[...Q........f.
000030 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29 00 00 00 .;P......j.6)...
000040 00 8B 48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 ..H0E.!..X..r...
000050 C7 36 7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A .6zz%;..R#...h.:
000060 59 23 3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 Y#?E.W... Y.....
000070 0E 41 83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D .A.z.X.z...XN...
000080 35 BD 96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF 5...6..;...A....
000090 C9 7E F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 .~.6.m...@..!...
0000A0 2A CD 2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC *.+..].}Y... ...
0000B0 4E 02 53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F N.S..=7.o...Q...
0000C0 14 04 2F 46 61 4A 4C 70 C0 F1 4B EF F5 FF FF FF ../FaJLp..K.....
0000D0 FF 02 40 4B 4C 00 00 00 00 00 19 76 A9 14 1A A0 ..@KL......v....
0000E0 CD 1C BE A6 E7 45 8A 7A BA D5 12 A9 D9 EA 1A FB .....E.z........
0000F0 22 5E 88 AC 80 FA E9 C7 00 00 00 00 19 76 A9 14 "^...........v..
000100 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E FD A0 B7 ..[.Cj.....H^...
000110 8B 4E CC 52 88 AC 00 00 00 00 .N.R......

Message header:
F9 BE B4 D9 - main network magic bytes
74 78 00 00 00 00 00 00 00 00 00 00 - "tx" command
02 01 00 00 - payload is 258 bytes long
E2 93 CD BE - checksum of payload

Transaction:
01 00 00 00 - version

Inputs:
01 - number of transaction inputs

Input 1:
6D BD DB 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D - previous output (outpoint)
12 66 E9 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29
00 00 00 00

8B - script is 139 bytes long

48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 C7 36 - signature script (scriptSig)
7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A 59 23
3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 0E 41
83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D 35 BD
96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF C9 7E
F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 2A CD
2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC 4E 02
53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F 14 04
2F 46 61 4A 4C 70 C0 F1 4B EF F5

FF FF FF FF - sequence

Outputs:
02 - 2 Output Transactions

Output 1:
40 4B 4C 00 00 00 00 00 - 0.05 BTC (5000000)
19 - pk_script is 25 bytes long

76 A9 14 1A A0 CD 1C BE A6 E7 45 8A 7A BA D5 12 - pk_script
A9 D9 EA 1A FB 22 5E 88 AC

Output 2:
80 FA E9 C7 00 00 00 00 - 33.54 BTC (3354000000)
19 - pk_script is 25 bytes long

76 A9 14 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E - pk_script
FD A0 B7 8B 4E CC 52 88 AC

Locktime:
00 00 00 00 - lock time
</pre>

=== block ===

The '''block''' message is sent in response to a getdata message which requests transaction information from a block hash.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || uint32_t || Block version information, based upon the software version creating this block
|-
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references
|-
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block
|-
| 4 || timestamp || uint32_t || A unix timestamp recording when this block was created (Currently limited to dates before the year 2106!)
|-
| 4 || bits || uint32_t || The calculated [[Difficulty|difficulty target]] being used for this block
|-
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes
|-
| ? || txn_count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of transaction entries
|-
| ? || txns || tx[] || Block transactions, in format of "tx" command
|}

The SHA256 hash that identifies each block (and which must have a run of 0 bits) is calculated from the first 6 fields of this structure (version, prev_block, merkle_root, timestamp, bits, nonce, and standard SHA256 padding, making two 64-byte chunks in all) and ''not'' from the complete block. To calculate the hash, only two chunks need to be processed by the SHA256 algorithm. Since the ''nonce'' field is in the second chunk, the first chunk stays constant during mining and therefore only the second chunk needs to be processed. However, a Bitcoin hash is the hash of the hash, so two SHA256 rounds are needed for each mining iteration.
See [[Block hashing algorithm]] for details and an example.

=== headers ===

The ''headers'' packet returns block headers in response to a ''getheaders'' packet.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of block headers
|-
| 81x? || headers || [[Protocol_specification#Block_Headers|block_header]][] || [[Protocol_specification#Block_Headers|Block headers]]
|}

Note that the block headers in this packet include a transaction count (a var_int, so there can be more than 81 bytes per header) as opposed to the block headers which are sent to miners.

=== getaddr ===

The getaddr message sends a request to a node asking for information about known active peers to help with identifying potential nodes in the network. The response to receiving this message is to transmit an addr message with one or more peers from a database of known active peers. The typical presumption is that a node is likely to be active if it has been sending a message within the last three hours.

No additional data is transmitted with this message.

=== mempool ===

The mempool message sends a request to a node asking for information about transactions it has verified but which have not yet confirmed. The response to receiving this message is an inv message containing the transaction hashes for all the transactions in the node's mempool.

No additional data is transmitted with this message.

It is specified in [[BIP_0035|BIP 35]]. Since [[BIP_0037|BIP 37]], only transactions matching the filter are replied.

=== checkorder ===

This message is used for [[IP Transactions]], to ask the peer if it accepts such transactions and allow it to look at the content of the order.

It contains a CWalletTx object

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
|colspan="4"| Fields from CMerkleTx
|-
| ? || hashBlock
|-
| ? || vMerkleBranch
|-
| ? || nIndex
|-
|colspan="4"| Fields from CWalletTx
|-
| ? || vtxPrev
|-
| ? || mapValue
|-
| ? || vOrderForm
|-
| ? || fTimeReceivedIsTxTime
|-
| ? || nTimeReceived
|-
| ? || fFromMe
|-
| ? || fSpent
|}

=== submitorder ===

Confirms an order has been submitted.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 32 || hash || char[32] || Hash of the transaction
|-
| ? || wallet_entry || CWalletTx || Same payload as checkorder
|}

=== reply ===

Generic reply for [[IP Transactions]]

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || reply || uint32_t || reply code
|}

Possible values:

{|class="wikitable"
! Value !! Name !! Description
|-
| 0 || SUCCESS || The IP Transaction can proceed (''checkorder''), or has been accepted (''submitorder'')
|-
| 1 || WALLET_ERROR || AcceptWalletTransaction() failed
|-
| 2 || DENIED || IP Transactions are not accepted by this node
|}

=== ping ===

The ''ping'' message is sent primarily to confirm that the TCP/IP connection is still valid. An error in transmission is presumed to be a closed connection and the address is removed as a current peer.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8 || nonce || uint64_t || random nonce
|}

=== pong ===

The ''pong'' message is sent in response to a ''ping'' message. In modern protocol versions, a ''pong'' response is generated using a nonce included in the ping.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8 || nonce || uint64_t || nonce from ping
|}

=== filterload, filteradd, filterclear, merkleblock ===

These messages are related to Bloom filtering of connections and are defined in [[BIP 0037]].

=== alert ===

An '''alert''' is sent between nodes to send a general notification message throughout the network. If the alert can be confirmed with the signature as having come from the the core development group of the Bitcoin software, the message is suggested to be displayed for end-users. Attempts to perform transactions, particularly automated transactions through the client, are suggested to be halted. The text in the Message string should be relayed to log files and any user interfaces.

Alert format:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || payload || var_str || Serialized alert payload
|-
| ? || signature || var_str || An ECDSA signature of the message
|}

The developers of Satoshi's client use this public key for signing alerts:
04fc9702847840aaf195de8442ebecedf5b095cdbb9bc716bda9110971b28a49e0ead8564ff0db22209e0374782c093bb899692d524e9d6a6956e7c5ecbcd68284
(hash) 1AGRxqDa5WjUKBwHB9XYEjmkv1ucoUUy1s

The payload is serialized into a var_str to ensure that versions using incompatible alert formats can still relay alerts among one another. The current alert payload format is:
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || Version || int32_t || Alert format version
|-
| 8 || RelayUntil || int64_t || The timestamp beyond which nodes should stop relaying this alert
|-
| 8 || Expiration || int64_t || The timestamp beyond which this alert is no longer in effect and should be ignored
|-
| 4 || ID || int32_t || A unique ID number for this alert
|-
| 4 || Cancel || int32_t || All alerts with an ID number less than or equal to this number should be canceled: deleted and not accepted in the future
|-
| ? || setCancel || set<int> || All alert IDs contained in this set should be canceled as above
|-
| 4 || MinVer || int32_t || This alert only applies to versions greater than or equal to this version. Other versions should still relay it.
|-
| 4 || MaxVer || int32_t || This alert only applies to versions less than or equal to this version. Other versions should still relay it.
|-
| ? || setSubVer || set<string> || If this set contains any elements, then only nodes that have their subVer contained in this set are affected by the alert. Other versions should still relay it.
|-
| 4 || Priority || int32_t || Relative priority compared to other alerts
|-
| ? || Comment || string || A comment on the alert that is not displayed
|-
| ? || StatusBar || string || The alert message that is displayed to the user
|-
| ? || Reserved || string || Reserved
|}

Sample alert (no message header):
73010000003766404f00000000b305434f00000000f2030000f1030000001027000048ee0000
0064000000004653656520626974636f696e2e6f72672f666562323020696620796f75206861
76652074726f75626c6520636f6e6e656374696e672061667465722032302046656272756172
79004730450221008389df45f0703f39ec8c1cc42c13810ffcae14995bb648340219e353b63b
53eb022009ec65e1c1aaeec1fd334c6b684bde2b3f573060d5b70c3a46723326e4e8a4f1

Version: 1
RelayUntil: 1329620535
Expiration: 1329792435
ID: 1010
Cancel: 1009
setCancel: <empty>
MinVer: 10000
MaxVer: 61000
setSubVer: <empty>
Priority: 100
Comment: <empty>
StatusBar: "See bitcoin.org/feb20 if you have trouble connecting after 20 February"
Reserved: <empty>

== Scripting ==

See [[script]].

== Wireshark dissector ==
A dissector for wireshark is being developed at https://github.com/blueCommand/bitcoin-dissector

==See Also==

* [[Network]]
* [[Protocol rules]]
* [[Hardfork Wishlist]]

==References==
<references />

[[zh-cn:协议说明]]
[[Category:Technical]]
[[Category:Developer]]

Protocol documentation

2013-08-28T09:17:00Z

CodeShark: /* Message types */

Sources:
* [[Original Bitcoin client]] source

Type names used in this documentation are from the C99 standard.

For protocol used in mining, see [[Getwork]].

==Common standards==

=== Hashes ===

Usually, when a hash is computed within bitcoin, it is computed twice. Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-256] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when a shorter hash is desirable (for example when creating a bitcoin address).

Example of double-SHA-256 encoding of string "hello":

hello
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round of sha-256)
9595c9df90075148eb06860365df33584b75bff782a510c6cd4883a419833d50 (second round of sha-256)

For bitcoin addresses (RIPEMD-160) this would give:

hello
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round is sha-256)
b6a9c8c230722b7c748331a8b450f05566dc7d0f (with ripemd-160)

=== Merkle Trees ===

Merkle trees are binary trees of hashes. Merkle trees in bitcoin use a '''double''' SHA-256, the SHA-256 hash of the SHA-256 hash of something.

If, when forming a row in the tree (other than the root of the tree), it would have an odd number of elements, the final double-hash is duplicated to ensure that the row has an even number of hashes.

First form the bottom row of the tree with the ordered double-SHA-256 hashes of the byte streams of the transactions in the block.

Then the row above it consists of half that number of hashes. Each entry is the double-SHA-256 of the 64-byte concatenation of the corresponding two hashes below it in the tree.

This procedure repeats recursively until we reach a row consisting of just a single double-hash. This is the '''merkle root''' of the tree.

For example, imagine a block with three transactions ''a'', ''b'' and ''c''. The merkle tree is:

d1 = dhash(a)
d2 = dhash(b)
d3 = dhash(c)
d4 = dhash(c) # a, b, c are 3. that's an odd number, so we take the c twice

d5 = dhash(d1 concat d2)
d6 = dhash(d3 concat d4)

d7 = dhash(d5 concat d6)

where

dhash(a) = sha256(sha256(a))

''d7'' is the merkle root of the 3 transactions in this block.

Note: Hashes in Merkle Tree displayed in the [[Block Explorer]] are of little-endian notation. For some implementations and [http://www.fileformat.info/tool/hash.htm calculations], the bits need to be reversed before they are hashed, and again after the hashing operation.

=== Signatures ===

Bitcoin uses [http://en.wikipedia.org/wiki/Elliptic_curve_cryptography Elliptic Curve] [http://en.wikipedia.org/wiki/Digital_Signature_Algorithm Digital Signature Algorithm] ([http://en.wikipedia.org/wiki/Elliptic_Curve_DSA ECDSA]) to sign transactions.

For ECDSA the secp256k1 curve from http://www.secg.org/collateral/sec2_final.pdf is used.

Public keys (in scripts) are given as 04 <x> <y> where ''x'' and ''y'' are 32 byte big-endian integers representing the coordinates of a point on the curve or in compressed form given as <sign> <x> where <sign> is 0x02 if ''y'' is even and 0x03 if ''y'' is odd.

Signatures use [http://en.wikipedia.org/wiki/Distinguished_Encoding_Rules DER encoding] to pack the ''r'' and ''s'' components into a single byte stream (this is also what OpenSSL produces by default).

=== Transaction Verification ===
Transactions are cryptographically signed records that reassign ownership of Bitcoins to new addresses. Transactions have ''inputs'' - records which reference the funds from other previous transactions - and ''outputs'' - records which determine the new owner of the transferred Bitcoins, and which will be referenced as inputs in future transactions as those funds are respent.

Each ''input'' must have a cryptographic digital signature that unlocks the funds from the prior transaction. Only the person possessing the appropriate [[private key]] is able to create a satisfactory signature; this in effect ensures that funds can only be spent by their owners.

Each ''output'' determines which Bitcoin address (or other criteria, see [[Scripting]]) is the recipient of the funds.

In a transaction, the sum of all inputs must be equal to or greater than the sum of all outputs. If the inputs exceed the outputs, the difference is considered a [[transaction fee]], and is redeemable by whoever first includes the transaction into the block chain.

A special kind of transaction, called a [[coinbase transaction]], has no inputs. It is created by [[miners]], and there is one coinbase transaction per block. Because each block comes with a reward of newly created Bitcoins (e.g. 50 BTC for the first 210,000 blocks), the first transaction of a block is, with few exceptions, the transaction that grants those coins to their recipient (the miner). In addition to the newly created Bitcoins, the coinbase transaction is also used for assigning the recipient of any transaction fees that were paid within the other transactions being included in the same block. The coinbase transaction can assign the entire reward to a single Bitcoin address, or split it in portions among multiple addresses, just like any other transaction. Coinbase transactions always contain outputs totaling the sum of the block reward plus all transaction fees collected from the other transactions in the same block.

The [[coinbase transaction]] in block zero cannot be spent. This is due to a quirk of the reference client implementation that would open the potential for a block chain fork if some nodes accepted the spend and others did not<ref>[http://bitcointalk.org/index.php?topic=119645.msg1288552#msg1288552 Block 0 Network Fork]</ref>.

Most Bitcoin outputs encumber the newly transferred coins with a single ECDSA private key. The actual record saved with inputs and outputs isn't necessarily a key, but a ''script''. Bitcoin uses an interpreted scripting system to determine whether an output's criteria have been satisfied, with which more complex operations are possible, such as outputs that require two ECDSA signatures, or two-of-three-signature schemes. An output that references a single Bitcoin address is a ''typical'' output; an output actually contains this information in the form of a script that requires a single ECDSA signature (see [[OP_CHECKSIG]]). The output script specifies what must be provided to unlock the funds later, and when the time comes in the future to spend the transaction in another input, that input must provide all of the thing(s) that satisfy the requirements defined by the original output script.

=== Addresses ===

A bitcoin address is in fact the hash of a ECDSA public key, computed this way:

Version = 1 byte of 0 (zero); on the test network, this is 1 byte of 111
Key hash = Version concatenated with RIPEMD-160(SHA-256(public key))
Checksum = 1st 4 bytes of SHA-256(SHA-256(Key hash))
Bitcoin Address = Base58Encode(Key hash concatenated with Checksum)

The Base58 encoding used is home made, and has some differences. Especially, leading zeroes are kept as single zeroes when conversion happens.

== Common structures ==

Almost all integers are encoded in little endian. Only IP or port number are encoded big endian.

=== Message structure ===

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown
|-
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)
|-
| 4 || length || uint32_t || Length of payload in number of bytes
|-
| 4 || checksum || uint32_t || First 4 bytes of sha256(sha256(payload))
|-
| ? || payload || uchar[] || The actual data
|}

Known magic values:

{|class="wikitable"
! Network !! Magic value !! Sent over wire as
|-
| main || 0xD9B4BEF9 || F9 BE B4 D9
|-
| testnet || 0xDAB5BFFA || FA BF B5 DA
|-
| testnet3 || 0x0709110B || 0B 11 09 07
|-
| namecoin || 0xFEB4BEF9 || F9 BE B4 FE
|}

=== Variable length integer ===

Integer can be encoded depending on the represented value to save space.
Variable length integers always precede an array/vector of a type of data that may vary in length.
Longer numbers are encoded in little endian.

{|class="wikitable"
! Value !! Storage length !! Format
|-
| < 0xfd || 1 || uint8_t
|-
| <= 0xffff || 3 || 0xfd followed by the length as uint16_t
|-
| <= 0xffffffff || 5 || 0xfe followed by the length as uint32_t
|-
| - || 9 || 0xff followed by the length as uint64_t
|}

If you're reading the Satoshi client code (BitcoinQT) it refers to this as a "CompactSize". Modern BitcoinQT has also CVarInt class which implements even more compact integer for the purpose of local storage (which is incompatible with "CompactSize" described here). CVarInt is not a part of the protocol.

=== Variable length string ===

Variable length string can be stored using a variable length integer followed by the string itself.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || length || [[Protocol_specification#Variable_length_integer|var_int]] || Length of the string
|-
| ? || string || char[] || The string itself (can be empty)
|}

=== Network address ===

When a network address is needed somewhere, this structure is used. This protocol and structure supports IPv6, '''but note that the original client currently only supports IPv4 networking'''. Network addresses are not prefixed with a timestamp in the version message.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || time || uint32 || the Time (version >= 31402)
|-
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]
|-
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The original client only supports IPv4 and only reads the last 4 bytes to get the IPv4 address. However, the IPv4 address is written into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).
|-
| 2 || port || uint16_t || port number, network byte order
|}

Hexdump example of Network address structure

<pre>
0000 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
0010 00 00 FF FF 0A 00 00 01 20 8D ........ .

Network address:
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK: see services listed under version command)
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv6: ::ffff:10.0.0.1 or IPv4: 10.0.0.1
20 8D - Port 8333
</pre>

=== Inventory Vectors ===

Inventory vectors are used for notifying other nodes about objects they have or data which is being requested.

Inventory vectors consist of the following data format:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || type || uint32_t || Identifies the object type linked to this inventory
|-
| 32 || hash || char[32] || Hash of the object
|}

The object type is currently defined as one of the following possibilities:

{|class="wikitable"
! Value !! Name !! Description
|-
| 0 || ERROR || Any data of with this number may be ignored
|-
| 1 || MSG_TX || Hash is related to a transaction
|-
| 2 || MSG_BLOCK || Hash is related to a data block
|}

Other Data Type values are considered reserved for future implementations.

=== Block Headers ===

Block headers are sent in a headers packet in response to a getheaders message.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || uint32_t || Block version information, based upon the software version creating this block
|-
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references
|-
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block
|-
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Will overflow in 2106<ref>http://en.wikipedia.org/wiki/Unix_time#Notable.C2.A0events.C2.A0in.C2.A0Unix.C2.A0time</ref>)
|-
| 4 || bits || uint32_t || The calculated difficulty target being used for this block
|-
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes
|-
| 1 || txn_count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of transaction entries, this value is always 0
|}

== Message types ==

=== version ===

When a node creates an outgoing connection, it will immediately [[Version Handshake|advertise]] its version. The remote node will respond with its version. No futher communication is possible until both peers have exchanged their version.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || int32_t || Identifies protocol version being used by the node
|-
| 8 || services || uint64_t || bitfield of features to be enabled for this connection
|-
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds
|-
| 26 || addr_recv || net_addr || The network address of the node receiving this message
|-
|colspan="4"| version >= 106
|-
| 26 || addr_from || net_addr || The network address of the node emitting this message
|-
| 8 || nonce || uint64_t || Node random nonce, randomly generated every time a version packet is sent. This nonce is used to detect connections to self.
|-
| ? || user_agent || [[#Variable length string|var_str]] || [[BIP_0014|User Agent]] (0x00 if string is 0 bytes long)
|-
| 4 || start_height || int32_t || The last block received by the emitting node
|-
| 1 || relay || bool || Whether the remote peer should announce relayed transactions or not, see [[BIP 0037]], since version >= 70001
|}

A "verack" packet shall be sent if the version packet was accepted.

The following services are currently assigned:

{|class="wikitable"
! Value !! Name !! Description
|-
| 1 || NODE_NETWORK || This node can be asked for full blocks instead of just headers.
|}

Hexdump example of version message (OBSOLETE EXAMPLE. This example lacks a checksum and user-agent):
<pre>
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................
0040 20 8D 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,
0060 3A B4 57 13 00 55 81 01 00 :.W..U...

Message header:
F9 BE B4 D9 - Main network magic bytes
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command
55 00 00 00 - Payload is 85 bytes long
- No checksum in version message until 20 February 2012. See https://bitcointalk.org/index.php?topic=55852.0
Version message:
9C 7C 00 00 - 31900 (version 0.3.19)
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)
E6 15 10 4D 00 00 00 00 - Mon Dec 20 21:50:14 EST 2010
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 20 8D - Recipient address info - see Network Address
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D - Sender address info - see Network Address
DD 9D 20 2C 3A B4 57 13 - Node random unique ID
00 - "" sub-version string (string is 0 bytes long)
55 81 01 00 - Last block sending node has is block #98645
</pre>

And here's a modern (60002) protocol version client advertising itself to a local peer...

Newer protocol includes the checksum now, this is from a mainline (satoshi) client during
an outgoing connection to another local client, notice that it does not fill out the
address information at all when the source or destination is "unroutable".

<pre>

0000 f9 be b4 d9 76 65 72 73 69 6f 6e 00 00 00 00 00 ....version.....
0010 64 00 00 00 35 8d 49 32 62 ea 00 00 01 00 00 00 d...5.I2b.......
0020 00 00 00 00 11 b2 d0 50 00 00 00 00 01 00 00 00 .......P........
0030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ff ff ................
0040 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
0050 00 00 00 00 00 00 00 00 ff ff 00 00 00 00 00 00 ................
0060 3b 2e b3 5d 8c e6 17 65 0f 2f 53 61 74 6f 73 68 ;..]...e./Satosh
0070 69 3a 30 2e 37 2e 32 2f c0 3e 03 00 i:0.7.2/.>..

Message Header:
F9 BE B4 D9 - Main network magic bytes
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command
64 00 00 00 - Payload is 100 bytes long
3B 64 8D 5A - payload checksum

Version message:
62 EA 00 00 - 60002 (protocol version 60002)
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)
11 B2 D0 50 00 00 00 00 - Tue Dec 18 10:12:33 PST 2012
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Recipient address info - see Network Address
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Sender address info - see Network Address
3B 2E B3 5D 8C E6 17 65 - Node ID
0F 2F 53 61 74 6F 73 68 69 3A 30 2E 37 2E 32 2F - "/Satoshi:0.7.2/" sub-version string (string is 15 bytes long)
C0 3E 03 00 - Last block sending node has is block #212672
</pre>

=== verack ===

The ''verack'' message is sent in reply to ''version''. This message consists of only a [[#Message structure|message header]] with the command string "verack".

Hexdump of the verack message:

<pre>
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......
0010 00 00 00 00 5D F6 E0 E2 ........

Message header:
F9 BE B4 D9 - Main network magic bytes
76 65 72 61 63 6B 00 00 00 00 00 00 - "verack" command
00 00 00 00 - Payload is 0 bytes long
5D F6 E0 E2 - Checksum
</pre>

=== addr ===

Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours

Payload:
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+ || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of address entries (max: 1000)
|-
| 30x? || addr_list || (uint32_t + net_addr)[] || Address of other nodes on the network. version < 209 will only read the first one. The uint32_t is a timestamp (see note below).
|}

'''Note''': Starting version 31402, addresses are prefixed with a timestamp. If no timestamp is present, the addresses should not be relayed to other peers, unless it is indeed confirmed they are up.

Hexdump example of ''addr'' message:
<pre>
0000 F9 BE B4 D9 61 64 64 72 00 00 00 00 00 00 00 00 ....addr........
0010 1F 00 00 00 ED 52 39 9B 01 E2 15 10 4D 01 00 00 .....R9.....M...
0020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF ................
0030 FF 0A 00 00 01 20 8D ..... .

Message Header:
F9 BE B4 D9 - Main network magic bytes
61 64 64 72 00 00 00 00 00 00 00 00 - "addr"
1F 00 00 00 - payload is 31 bytes long
ED 52 39 9B - checksum of payload

Payload:
01 - 1 address in this message

Address:
E2 15 10 4D - Mon Dec 20 21:50:10 EST 2010 (only when version is >= 31402)
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK service - see version message)
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv4: 10.0.0.1, IPv6: ::ffff:10.0.0.1 (IPv4-mapped IPv6 address)
20 8D - port 8333
</pre>

=== inv ===

Allows a node to advertise its knowledge of one or more objects. It can be received unsolicited, or in reply to ''getblocks''.

Payload (maximum payload length: 1.8 Megabytes or 50000 entries):

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of inventory entries
|-
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors
|}

=== getdata ===

getdata is used in response to inv, to retrieve the content of a specific object, and is usually sent after receiving an ''inv'' packet, after filtering known elements. It can be used to retrieve transactions, but only if they are in the memory pool or relay set - arbitrary access to transactions in the chain is not allowed to avoid having clients start to depend on nodes having full transaction indexes (which modern nodes do not).

Payload (maximum payload length: 1.8 Megabytes or 50000 entries):

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of inventory entries
|-
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors
|}

=== notfound ===

notfound is a response to a getdata, sent if any requested data items could not be relayed, for example, because the requested transaction was not in the memory pool or relay set.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of inventory entries
|-
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors
|}

=== getblocks ===

Return an ''inv'' packet containing the list of blocks starting right after the last known hash in the block locator object, up to hash_stop or 500 blocks, whichever comes first.

The locator hashes are processed by a node in the order as they appear in the message. If a block hash if found in the node's main chain, the list of it's children is returned back via the ''inv'' message and the remaining locators are ignored, no matter if the requested limit was reached, or not.

To receive the next blocks hashes, one needs to issue getblocks again with a new block locator object. Keep in mind that some clients (specifically the Satoshi client) will gladly provide blocks which are invalid if the block locator object contains a hash on the invalid branch.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || uint32_t || the protocol version
|-
| 1+ || hash count || [[Protocol_specification#Variable_length_integer|var_int]] || number of block locator hash entries
|-
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)
|-
| 32 || hash_stop || char[32] || hash of the last desired block; set to zero to get as many blocks as possible (500)
|}

To create the block locator hashes, keep pushing hashes until you go back to the genesis block. After pushing 10 hashes back, the step backwards doubles every loop:

<pre>
// From libbitcoin which is under AGPL
std::vector<size_t> block_locator_indices(int top_depth)
{
// Start at max_depth
std::vector<size_t> indices;
// Push last 10 indices first
size_t step = 1, start = 0;
for (int i = top_depth; i > 0; i -= step, ++start)
{
if (start >= 10)
step *= 2;
indices.push_back(i);
}
indices.push_back(0);
return indices;
}
</pre>

Note that it is allowed to send in fewer known hashes down to a minimum of just one hash. However, the purpose of the block locator object is to detect a wrong branch in the caller's main chain. If the peer detects that you are off the main chain, it will send in block hashes which are earlier than your last known block. So if you just send in your last known hash and it is off the main chain, the peer starts over at block #1.

=== getheaders ===

Return a ''headers'' packet containing the headers of blocks starting right after the last known hash in the block locator object, up to hash_stop or 2000 blocks, whichever comes first. To receive the next block headers, one needs to issue getheaders again with a new block locator object. The ''getheaders'' command is used by thin clients to quickly download the blockchain where the contents of the transactions would be irrelevant (because they are not ours). Keep in mind that some clients (specifically the Satoshi client) will gladly provide headers of blocks which are invalid if the block locator object contains a hash on the invalid branch.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || uint32_t || the protocol version
|-
| 1+ || hash count || [[Protocol_specification#Variable_length_integer|var_int]] || number of block locator hash entries
|-
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)
|-
| 32 || hash_stop || char[32] || hash of the last desired block header; set to zero to get as many blocks as possible (2000)
|}

For the block locator object in this packet, the same rules apply as for the [[Protocol_specification#getblocks|getblocks]] packet.

=== tx ===

''tx'' describes a bitcoin transaction, in reply to ''getdata''

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || uint32_t || Transaction data format version
|-
| 1+ || tx_in count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of Transaction inputs
|-
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins
|-
| 1+ || tx_out count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of Transaction outputs
|-
| 9+ || tx_out || tx_out[] || A list of 1 or more transaction outputs or destinations for coins
|-
| 4 || lock_time || uint32_t || The block number or timestamp at which this transaction is locked:
{|class="wikitable"
! Value !! Description
|-
| 0 || Always locked
|-
| < 500000000 || Block number at which this transaction is locked
|-
| >= 500000000 || UNIX timestamp at which this transaction is locked
|}
If all TxIn inputs have final (0xffffffff) sequence numbers then lock_time is irrelevant. Otherwise, the transaction may not be added to a block until after lock_time.

|}

TxIn consists of the following fields:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 36 || previous_output || outpoint || The previous output transaction reference, as an OutPoint structure
|-
| 1+ || script length || [[Protocol_specification#Variable_length_integer|var_int]] || The length of the signature script
|-
| ? || signature script || uchar[] || Computational Script for confirming transaction authorization
|-
| 4 || [http://bitcoin.stackexchange.com/q/2025/323 sequence] || uint32_t || Transaction version as defined by the sender. Intended for "replacement" of transactions when information is updated before inclusion into a block.
|}

The OutPoint structure consists of the following fields:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 32 || hash || char[32] || The hash of the referenced transaction.
|-
| 4 || index || uint32_t || The index of the specific output in the transaction. The first output is 0, etc.
|}

The Script structure consists of a series of pieces of information and operations related to the value of the transaction.

(Structure to be expanded in the future… see script.h and script.cpp and [[Script]] for more information)

The TxOut structure consists of the following fields:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8 || value || int64_t || Transaction Value
|-
| 1+ || pk_script length || [[Protocol_specification#Variable_length_integer|var_int]] || Length of the pk_script
|-
| ? || pk_script || uchar[] || Usually contains the public key as a Bitcoin script setting up conditions to claim this output.
|}

Example ''tx'' message:
<pre>
000000 F9 BE B4 D9 74 78 00 00 00 00 00 00 00 00 00 00 ....tx..........
000010 02 01 00 00 E2 93 CD BE 01 00 00 00 01 6D BD DB .............m..
000020 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D 12 66 E9 .[...Q........f.
000030 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29 00 00 00 .;P......j.6)...
000040 00 8B 48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 ..H0E.!..X..r...
000050 C7 36 7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A .6zz%;..R#...h.:
000060 59 23 3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 Y#?E.W... Y.....
000070 0E 41 83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D .A.z.X.z...XN...
000080 35 BD 96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF 5...6..;...A....
000090 C9 7E F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 .~.6.m...@..!...
0000A0 2A CD 2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC *.+..].}Y... ...
0000B0 4E 02 53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F N.S..=7.o...Q...
0000C0 14 04 2F 46 61 4A 4C 70 C0 F1 4B EF F5 FF FF FF ../FaJLp..K.....
0000D0 FF 02 40 4B 4C 00 00 00 00 00 19 76 A9 14 1A A0 ..@KL......v....
0000E0 CD 1C BE A6 E7 45 8A 7A BA D5 12 A9 D9 EA 1A FB .....E.z........
0000F0 22 5E 88 AC 80 FA E9 C7 00 00 00 00 19 76 A9 14 "^...........v..
000100 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E FD A0 B7 ..[.Cj.....H^...
000110 8B 4E CC 52 88 AC 00 00 00 00 .N.R......

Message header:
F9 BE B4 D9 - main network magic bytes
74 78 00 00 00 00 00 00 00 00 00 00 - "tx" command
02 01 00 00 - payload is 258 bytes long
E2 93 CD BE - checksum of payload

Transaction:
01 00 00 00 - version

Inputs:
01 - number of transaction inputs

Input 1:
6D BD DB 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D - previous output (outpoint)
12 66 E9 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29
00 00 00 00

8B - script is 139 bytes long

48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 C7 36 - signature script (scriptSig)
7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A 59 23
3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 0E 41
83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D 35 BD
96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF C9 7E
F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 2A CD
2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC 4E 02
53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F 14 04
2F 46 61 4A 4C 70 C0 F1 4B EF F5

FF FF FF FF - sequence

Outputs:
02 - 2 Output Transactions

Output 1:
40 4B 4C 00 00 00 00 00 - 0.05 BTC (5000000)
19 - pk_script is 25 bytes long

76 A9 14 1A A0 CD 1C BE A6 E7 45 8A 7A BA D5 12 - pk_script
A9 D9 EA 1A FB 22 5E 88 AC

Output 2:
80 FA E9 C7 00 00 00 00 - 33.54 BTC (3354000000)
19 - pk_script is 25 bytes long

76 A9 14 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E - pk_script
FD A0 B7 8B 4E CC 52 88 AC

Locktime:
00 00 00 00 - lock time
</pre>

=== block ===

The '''block''' message is sent in response to a getdata message which requests transaction information from a block hash.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || uint32_t || Block version information, based upon the software version creating this block
|-
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references
|-
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block
|-
| 4 || timestamp || uint32_t || A unix timestamp recording when this block was created (Currently limited to dates before the year 2106!)
|-
| 4 || bits || uint32_t || The calculated [[Difficulty|difficulty target]] being used for this block
|-
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes
|-
| ? || txn_count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of transaction entries
|-
| ? || txns || tx[] || Block transactions, in format of "tx" command
|}

The SHA256 hash that identifies each block (and which must have a run of 0 bits) is calculated from the first 6 fields of this structure (version, prev_block, merkle_root, timestamp, bits, nonce, and standard SHA256 padding, making two 64-byte chunks in all) and ''not'' from the complete block. To calculate the hash, only two chunks need to be processed by the SHA256 algorithm. Since the ''nonce'' field is in the second chunk, the first chunk stays constant during mining and therefore only the second chunk needs to be processed. However, a Bitcoin hash is the hash of the hash, so two SHA256 rounds are needed for each mining iteration.
See [[Block hashing algorithm]] for details and an example.

=== headers ===

The ''headers'' packet returns block headers in response to a ''getheaders'' packet.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of block headers
|-
| 81x? || headers || [[Protocol_specification#Block_Headers|block_header]][] || [[Protocol_specification#Block_Headers|Block headers]]
|}

Note that the block headers in this packet include a transaction count (a var_int, so there can be more than 81 bytes per header) as opposed to the block headers which are sent to miners.

=== getaddr ===

The getaddr message sends a request to a node asking for information about known active peers to help with identifying potential nodes in the network. The response to receiving this message is to transmit an addr message with one or more peers from a database of known active peers. The typical presumption is that a node is likely to be active if it has been sending a message within the last three hours.

No additional data is transmitted with this message.

=== mempool ===

The mempool message sends a request to a node asking for information about transactions it has verified but which have not yet confirmed. The response to receiving this message is an inv message containing the transaction hashes for all the transactions in the node's mempool.

No additional data is transmitted with this message.

It is specified in [[BIP_0035|BIP 35]]. Since [[BIP_0037|BIP 37]], only transactions matching the filter are replied.

=== checkorder ===

This message is used for [[IP Transactions]], to ask the peer if it accepts such transactions and allow it to look at the content of the order.

It contains a CWalletTx object

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
|colspan="4"| Fields from CMerkleTx
|-
| ? || hashBlock
|-
| ? || vMerkleBranch
|-
| ? || nIndex
|-
|colspan="4"| Fields from CWalletTx
|-
| ? || vtxPrev
|-
| ? || mapValue
|-
| ? || vOrderForm
|-
| ? || fTimeReceivedIsTxTime
|-
| ? || nTimeReceived
|-
| ? || fFromMe
|-
| ? || fSpent
|}

=== submitorder ===

Confirms an order has been submitted.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 32 || hash || char[32] || Hash of the transaction
|-
| ? || wallet_entry || CWalletTx || Same payload as checkorder
|}

=== reply ===

Generic reply for [[IP Transactions]]

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || reply || uint32_t || reply code
|}

Possible values:

{|class="wikitable"
! Value !! Name !! Description
|-
| 0 || SUCCESS || The IP Transaction can proceed (''checkorder''), or has been accepted (''submitorder'')
|-
| 1 || WALLET_ERROR || AcceptWalletTransaction() failed
|-
| 2 || DENIED || IP Transactions are not accepted by this node
|}

=== ping ===

The ''ping'' message is sent primarily to confirm that the TCP/IP connection is still valid. An error in transmission is presumed to be a closed connection and the address is removed as a current peer.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8 || nonce || uint64_t || random nonce
|}

=== pong ===

The ''pong'' message is sent in response to a "ping" message. In modern protocol versions, a ''pong'' response is generated using a nonce included in the ping.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8 || nonce || uint64_t || nonce from ping
|}

=== filterload, filteradd, filterclear, merkleblock ===

These messages are related to Bloom filtering of connections and are defined in [[BIP 0037]].

=== alert ===

An '''alert''' is sent between nodes to send a general notification message throughout the network. If the alert can be confirmed with the signature as having come from the the core development group of the Bitcoin software, the message is suggested to be displayed for end-users. Attempts to perform transactions, particularly automated transactions through the client, are suggested to be halted. The text in the Message string should be relayed to log files and any user interfaces.

Alert format:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || payload || var_str || Serialized alert payload
|-
| ? || signature || var_str || An ECDSA signature of the message
|}

The developers of Satoshi's client use this public key for signing alerts:
04fc9702847840aaf195de8442ebecedf5b095cdbb9bc716bda9110971b28a49e0ead8564ff0db22209e0374782c093bb899692d524e9d6a6956e7c5ecbcd68284
(hash) 1AGRxqDa5WjUKBwHB9XYEjmkv1ucoUUy1s

The payload is serialized into a var_str to ensure that versions using incompatible alert formats can still relay alerts among one another. The current alert payload format is:
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || Version || int32_t || Alert format version
|-
| 8 || RelayUntil || int64_t || The timestamp beyond which nodes should stop relaying this alert
|-
| 8 || Expiration || int64_t || The timestamp beyond which this alert is no longer in effect and should be ignored
|-
| 4 || ID || int32_t || A unique ID number for this alert
|-
| 4 || Cancel || int32_t || All alerts with an ID number less than or equal to this number should be canceled: deleted and not accepted in the future
|-
| ? || setCancel || set<int> || All alert IDs contained in this set should be canceled as above
|-
| 4 || MinVer || int32_t || This alert only applies to versions greater than or equal to this version. Other versions should still relay it.
|-
| 4 || MaxVer || int32_t || This alert only applies to versions less than or equal to this version. Other versions should still relay it.
|-
| ? || setSubVer || set<string> || If this set contains any elements, then only nodes that have their subVer contained in this set are affected by the alert. Other versions should still relay it.
|-
| 4 || Priority || int32_t || Relative priority compared to other alerts
|-
| ? || Comment || string || A comment on the alert that is not displayed
|-
| ? || StatusBar || string || The alert message that is displayed to the user
|-
| ? || Reserved || string || Reserved
|}

Sample alert (no message header):
73010000003766404f00000000b305434f00000000f2030000f1030000001027000048ee0000
0064000000004653656520626974636f696e2e6f72672f666562323020696620796f75206861
76652074726f75626c6520636f6e6e656374696e672061667465722032302046656272756172
79004730450221008389df45f0703f39ec8c1cc42c13810ffcae14995bb648340219e353b63b
53eb022009ec65e1c1aaeec1fd334c6b684bde2b3f573060d5b70c3a46723326e4e8a4f1

Version: 1
RelayUntil: 1329620535
Expiration: 1329792435
ID: 1010
Cancel: 1009
setCancel: <empty>
MinVer: 10000
MaxVer: 61000
setSubVer: <empty>
Priority: 100
Comment: <empty>
StatusBar: "See bitcoin.org/feb20 if you have trouble connecting after 20 February"
Reserved: <empty>

== Scripting ==

See [[script]].

== Wireshark dissector ==
A dissector for wireshark is being developed at https://github.com/blueCommand/bitcoin-dissector

==See Also==

* [[Network]]
* [[Protocol rules]]
* [[Hardfork Wishlist]]

==References==
<references />

[[zh-cn:协议说明]]
[[Category:Technical]]
[[Category:Developer]]

Protocol documentation

2013-08-28T09:13:17Z

CodeShark: /* ping */

Sources:
* [[Original Bitcoin client]] source

Type names used in this documentation are from the C99 standard.

For protocol used in mining, see [[Getwork]].

==Common standards==

=== Hashes ===

Usually, when a hash is computed within bitcoin, it is computed twice. Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-256] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when a shorter hash is desirable (for example when creating a bitcoin address).

Example of double-SHA-256 encoding of string "hello":

hello
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round of sha-256)
9595c9df90075148eb06860365df33584b75bff782a510c6cd4883a419833d50 (second round of sha-256)

For bitcoin addresses (RIPEMD-160) this would give:

hello
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round is sha-256)
b6a9c8c230722b7c748331a8b450f05566dc7d0f (with ripemd-160)

=== Merkle Trees ===

Merkle trees are binary trees of hashes. Merkle trees in bitcoin use a '''double''' SHA-256, the SHA-256 hash of the SHA-256 hash of something.

If, when forming a row in the tree (other than the root of the tree), it would have an odd number of elements, the final double-hash is duplicated to ensure that the row has an even number of hashes.

First form the bottom row of the tree with the ordered double-SHA-256 hashes of the byte streams of the transactions in the block.

Then the row above it consists of half that number of hashes. Each entry is the double-SHA-256 of the 64-byte concatenation of the corresponding two hashes below it in the tree.

This procedure repeats recursively until we reach a row consisting of just a single double-hash. This is the '''merkle root''' of the tree.

For example, imagine a block with three transactions ''a'', ''b'' and ''c''. The merkle tree is:

d1 = dhash(a)
d2 = dhash(b)
d3 = dhash(c)
d4 = dhash(c) # a, b, c are 3. that's an odd number, so we take the c twice

d5 = dhash(d1 concat d2)
d6 = dhash(d3 concat d4)

d7 = dhash(d5 concat d6)

where

dhash(a) = sha256(sha256(a))

''d7'' is the merkle root of the 3 transactions in this block.

Note: Hashes in Merkle Tree displayed in the [[Block Explorer]] are of little-endian notation. For some implementations and [http://www.fileformat.info/tool/hash.htm calculations], the bits need to be reversed before they are hashed, and again after the hashing operation.

=== Signatures ===

Bitcoin uses [http://en.wikipedia.org/wiki/Elliptic_curve_cryptography Elliptic Curve] [http://en.wikipedia.org/wiki/Digital_Signature_Algorithm Digital Signature Algorithm] ([http://en.wikipedia.org/wiki/Elliptic_Curve_DSA ECDSA]) to sign transactions.

For ECDSA the secp256k1 curve from http://www.secg.org/collateral/sec2_final.pdf is used.

Public keys (in scripts) are given as 04 <x> <y> where ''x'' and ''y'' are 32 byte big-endian integers representing the coordinates of a point on the curve or in compressed form given as <sign> <x> where <sign> is 0x02 if ''y'' is even and 0x03 if ''y'' is odd.

Signatures use [http://en.wikipedia.org/wiki/Distinguished_Encoding_Rules DER encoding] to pack the ''r'' and ''s'' components into a single byte stream (this is also what OpenSSL produces by default).

=== Transaction Verification ===
Transactions are cryptographically signed records that reassign ownership of Bitcoins to new addresses. Transactions have ''inputs'' - records which reference the funds from other previous transactions - and ''outputs'' - records which determine the new owner of the transferred Bitcoins, and which will be referenced as inputs in future transactions as those funds are respent.

Each ''input'' must have a cryptographic digital signature that unlocks the funds from the prior transaction. Only the person possessing the appropriate [[private key]] is able to create a satisfactory signature; this in effect ensures that funds can only be spent by their owners.

Each ''output'' determines which Bitcoin address (or other criteria, see [[Scripting]]) is the recipient of the funds.

In a transaction, the sum of all inputs must be equal to or greater than the sum of all outputs. If the inputs exceed the outputs, the difference is considered a [[transaction fee]], and is redeemable by whoever first includes the transaction into the block chain.

A special kind of transaction, called a [[coinbase transaction]], has no inputs. It is created by [[miners]], and there is one coinbase transaction per block. Because each block comes with a reward of newly created Bitcoins (e.g. 50 BTC for the first 210,000 blocks), the first transaction of a block is, with few exceptions, the transaction that grants those coins to their recipient (the miner). In addition to the newly created Bitcoins, the coinbase transaction is also used for assigning the recipient of any transaction fees that were paid within the other transactions being included in the same block. The coinbase transaction can assign the entire reward to a single Bitcoin address, or split it in portions among multiple addresses, just like any other transaction. Coinbase transactions always contain outputs totaling the sum of the block reward plus all transaction fees collected from the other transactions in the same block.

The [[coinbase transaction]] in block zero cannot be spent. This is due to a quirk of the reference client implementation that would open the potential for a block chain fork if some nodes accepted the spend and others did not<ref>[http://bitcointalk.org/index.php?topic=119645.msg1288552#msg1288552 Block 0 Network Fork]</ref>.

Most Bitcoin outputs encumber the newly transferred coins with a single ECDSA private key. The actual record saved with inputs and outputs isn't necessarily a key, but a ''script''. Bitcoin uses an interpreted scripting system to determine whether an output's criteria have been satisfied, with which more complex operations are possible, such as outputs that require two ECDSA signatures, or two-of-three-signature schemes. An output that references a single Bitcoin address is a ''typical'' output; an output actually contains this information in the form of a script that requires a single ECDSA signature (see [[OP_CHECKSIG]]). The output script specifies what must be provided to unlock the funds later, and when the time comes in the future to spend the transaction in another input, that input must provide all of the thing(s) that satisfy the requirements defined by the original output script.

=== Addresses ===

A bitcoin address is in fact the hash of a ECDSA public key, computed this way:

Version = 1 byte of 0 (zero); on the test network, this is 1 byte of 111
Key hash = Version concatenated with RIPEMD-160(SHA-256(public key))
Checksum = 1st 4 bytes of SHA-256(SHA-256(Key hash))
Bitcoin Address = Base58Encode(Key hash concatenated with Checksum)

The Base58 encoding used is home made, and has some differences. Especially, leading zeroes are kept as single zeroes when conversion happens.

== Common structures ==

Almost all integers are encoded in little endian. Only IP or port number are encoded big endian.

=== Message structure ===

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown
|-
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)
|-
| 4 || length || uint32_t || Length of payload in number of bytes
|-
| 4 || checksum || uint32_t || First 4 bytes of sha256(sha256(payload))
|-
| ? || payload || uchar[] || The actual data
|}

Known magic values:

{|class="wikitable"
! Network !! Magic value !! Sent over wire as
|-
| main || 0xD9B4BEF9 || F9 BE B4 D9
|-
| testnet || 0xDAB5BFFA || FA BF B5 DA
|-
| testnet3 || 0x0709110B || 0B 11 09 07
|-
| namecoin || 0xFEB4BEF9 || F9 BE B4 FE
|}

=== Variable length integer ===

Integer can be encoded depending on the represented value to save space.
Variable length integers always precede an array/vector of a type of data that may vary in length.
Longer numbers are encoded in little endian.

{|class="wikitable"
! Value !! Storage length !! Format
|-
| < 0xfd || 1 || uint8_t
|-
| <= 0xffff || 3 || 0xfd followed by the length as uint16_t
|-
| <= 0xffffffff || 5 || 0xfe followed by the length as uint32_t
|-
| - || 9 || 0xff followed by the length as uint64_t
|}

If you're reading the Satoshi client code (BitcoinQT) it refers to this as a "CompactSize". Modern BitcoinQT has also CVarInt class which implements even more compact integer for the purpose of local storage (which is incompatible with "CompactSize" described here). CVarInt is not a part of the protocol.

=== Variable length string ===

Variable length string can be stored using a variable length integer followed by the string itself.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || length || [[Protocol_specification#Variable_length_integer|var_int]] || Length of the string
|-
| ? || string || char[] || The string itself (can be empty)
|}

=== Network address ===

When a network address is needed somewhere, this structure is used. This protocol and structure supports IPv6, '''but note that the original client currently only supports IPv4 networking'''. Network addresses are not prefixed with a timestamp in the version message.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || time || uint32 || the Time (version >= 31402)
|-
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]
|-
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The original client only supports IPv4 and only reads the last 4 bytes to get the IPv4 address. However, the IPv4 address is written into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).
|-
| 2 || port || uint16_t || port number, network byte order
|}

Hexdump example of Network address structure

<pre>
0000 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
0010 00 00 FF FF 0A 00 00 01 20 8D ........ .

Network address:
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK: see services listed under version command)
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv6: ::ffff:10.0.0.1 or IPv4: 10.0.0.1
20 8D - Port 8333
</pre>

=== Inventory Vectors ===

Inventory vectors are used for notifying other nodes about objects they have or data which is being requested.

Inventory vectors consist of the following data format:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || type || uint32_t || Identifies the object type linked to this inventory
|-
| 32 || hash || char[32] || Hash of the object
|}

The object type is currently defined as one of the following possibilities:

{|class="wikitable"
! Value !! Name !! Description
|-
| 0 || ERROR || Any data of with this number may be ignored
|-
| 1 || MSG_TX || Hash is related to a transaction
|-
| 2 || MSG_BLOCK || Hash is related to a data block
|}

Other Data Type values are considered reserved for future implementations.

=== Block Headers ===

Block headers are sent in a headers packet in response to a getheaders message.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || uint32_t || Block version information, based upon the software version creating this block
|-
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references
|-
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block
|-
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Will overflow in 2106<ref>http://en.wikipedia.org/wiki/Unix_time#Notable.C2.A0events.C2.A0in.C2.A0Unix.C2.A0time</ref>)
|-
| 4 || bits || uint32_t || The calculated difficulty target being used for this block
|-
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes
|-
| 1 || txn_count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of transaction entries, this value is always 0
|}

== Message types ==

=== version ===

When a node creates an outgoing connection, it will immediately [[Version Handshake|advertise]] its version. The remote node will respond with its version. No futher communication is possible until both peers have exchanged their version.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || int32_t || Identifies protocol version being used by the node
|-
| 8 || services || uint64_t || bitfield of features to be enabled for this connection
|-
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds
|-
| 26 || addr_recv || net_addr || The network address of the node receiving this message
|-
|colspan="4"| version >= 106
|-
| 26 || addr_from || net_addr || The network address of the node emitting this message
|-
| 8 || nonce || uint64_t || Node random nonce, randomly generated every time a version packet is sent. This nonce is used to detect connections to self.
|-
| ? || user_agent || [[#Variable length string|var_str]] || [[BIP_0014|User Agent]] (0x00 if string is 0 bytes long)
|-
| 4 || start_height || int32_t || The last block received by the emitting node
|-
| 1 || relay || bool || Whether the remote peer should announce relayed transactions or not, see [[BIP 0037]], since version >= 70001
|}

A "verack" packet shall be sent if the version packet was accepted.

The following services are currently assigned:

{|class="wikitable"
! Value !! Name !! Description
|-
| 1 || NODE_NETWORK || This node can be asked for full blocks instead of just headers.
|}

Hexdump example of version message (OBSOLETE EXAMPLE. This example lacks a checksum and user-agent):
<pre>
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................
0040 20 8D 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,
0060 3A B4 57 13 00 55 81 01 00 :.W..U...

Message header:
F9 BE B4 D9 - Main network magic bytes
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command
55 00 00 00 - Payload is 85 bytes long
- No checksum in version message until 20 February 2012. See https://bitcointalk.org/index.php?topic=55852.0
Version message:
9C 7C 00 00 - 31900 (version 0.3.19)
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)
E6 15 10 4D 00 00 00 00 - Mon Dec 20 21:50:14 EST 2010
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 20 8D - Recipient address info - see Network Address
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D - Sender address info - see Network Address
DD 9D 20 2C 3A B4 57 13 - Node random unique ID
00 - "" sub-version string (string is 0 bytes long)
55 81 01 00 - Last block sending node has is block #98645
</pre>

And here's a modern (60002) protocol version client advertising itself to a local peer...

Newer protocol includes the checksum now, this is from a mainline (satoshi) client during
an outgoing connection to another local client, notice that it does not fill out the
address information at all when the source or destination is "unroutable".

<pre>

0000 f9 be b4 d9 76 65 72 73 69 6f 6e 00 00 00 00 00 ....version.....
0010 64 00 00 00 35 8d 49 32 62 ea 00 00 01 00 00 00 d...5.I2b.......
0020 00 00 00 00 11 b2 d0 50 00 00 00 00 01 00 00 00 .......P........
0030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ff ff ................
0040 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
0050 00 00 00 00 00 00 00 00 ff ff 00 00 00 00 00 00 ................
0060 3b 2e b3 5d 8c e6 17 65 0f 2f 53 61 74 6f 73 68 ;..]...e./Satosh
0070 69 3a 30 2e 37 2e 32 2f c0 3e 03 00 i:0.7.2/.>..

Message Header:
F9 BE B4 D9 - Main network magic bytes
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command
64 00 00 00 - Payload is 100 bytes long
3B 64 8D 5A - payload checksum

Version message:
62 EA 00 00 - 60002 (protocol version 60002)
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)
11 B2 D0 50 00 00 00 00 - Tue Dec 18 10:12:33 PST 2012
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Recipient address info - see Network Address
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Sender address info - see Network Address
3B 2E B3 5D 8C E6 17 65 - Node ID
0F 2F 53 61 74 6F 73 68 69 3A 30 2E 37 2E 32 2F - "/Satoshi:0.7.2/" sub-version string (string is 15 bytes long)
C0 3E 03 00 - Last block sending node has is block #212672
</pre>

=== verack ===

The ''verack'' message is sent in reply to ''version''. This message consists of only a [[#Message structure|message header]] with the command string "verack".

Hexdump of the verack message:

<pre>
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......
0010 00 00 00 00 5D F6 E0 E2 ........

Message header:
F9 BE B4 D9 - Main network magic bytes
76 65 72 61 63 6B 00 00 00 00 00 00 - "verack" command
00 00 00 00 - Payload is 0 bytes long
5D F6 E0 E2 - Checksum
</pre>

=== addr ===

Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours

Payload:
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+ || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of address entries (max: 1000)
|-
| 30x? || addr_list || (uint32_t + net_addr)[] || Address of other nodes on the network. version < 209 will only read the first one. The uint32_t is a timestamp (see note below).
|}

'''Note''': Starting version 31402, addresses are prefixed with a timestamp. If no timestamp is present, the addresses should not be relayed to other peers, unless it is indeed confirmed they are up.

Hexdump example of ''addr'' message:
<pre>
0000 F9 BE B4 D9 61 64 64 72 00 00 00 00 00 00 00 00 ....addr........
0010 1F 00 00 00 ED 52 39 9B 01 E2 15 10 4D 01 00 00 .....R9.....M...
0020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF ................
0030 FF 0A 00 00 01 20 8D ..... .

Message Header:
F9 BE B4 D9 - Main network magic bytes
61 64 64 72 00 00 00 00 00 00 00 00 - "addr"
1F 00 00 00 - payload is 31 bytes long
ED 52 39 9B - checksum of payload

Payload:
01 - 1 address in this message

Address:
E2 15 10 4D - Mon Dec 20 21:50:10 EST 2010 (only when version is >= 31402)
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK service - see version message)
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv4: 10.0.0.1, IPv6: ::ffff:10.0.0.1 (IPv4-mapped IPv6 address)
20 8D - port 8333
</pre>

=== inv ===

Allows a node to advertise its knowledge of one or more objects. It can be received unsolicited, or in reply to ''getblocks''.

Payload (maximum payload length: 1.8 Megabytes or 50000 entries):

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of inventory entries
|-
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors
|}

=== getdata ===

getdata is used in response to inv, to retrieve the content of a specific object, and is usually sent after receiving an ''inv'' packet, after filtering known elements. It can be used to retrieve transactions, but only if they are in the memory pool or relay set - arbitrary access to transactions in the chain is not allowed to avoid having clients start to depend on nodes having full transaction indexes (which modern nodes do not).

Payload (maximum payload length: 1.8 Megabytes or 50000 entries):

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of inventory entries
|-
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors
|}

=== notfound ===

notfound is a response to a getdata, sent if any requested data items could not be relayed, for example, because the requested transaction was not in the memory pool or relay set.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of inventory entries
|-
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors
|}

=== getblocks ===

Return an ''inv'' packet containing the list of blocks starting right after the last known hash in the block locator object, up to hash_stop or 500 blocks, whichever comes first.

The locator hashes are processed by a node in the order as they appear in the message. If a block hash if found in the node's main chain, the list of it's children is returned back via the ''inv'' message and the remaining locators are ignored, no matter if the requested limit was reached, or not.

To receive the next blocks hashes, one needs to issue getblocks again with a new block locator object. Keep in mind that some clients (specifically the Satoshi client) will gladly provide blocks which are invalid if the block locator object contains a hash on the invalid branch.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || uint32_t || the protocol version
|-
| 1+ || hash count || [[Protocol_specification#Variable_length_integer|var_int]] || number of block locator hash entries
|-
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)
|-
| 32 || hash_stop || char[32] || hash of the last desired block; set to zero to get as many blocks as possible (500)
|}

To create the block locator hashes, keep pushing hashes until you go back to the genesis block. After pushing 10 hashes back, the step backwards doubles every loop:

<pre>
// From libbitcoin which is under AGPL
std::vector<size_t> block_locator_indices(int top_depth)
{
// Start at max_depth
std::vector<size_t> indices;
// Push last 10 indices first
size_t step = 1, start = 0;
for (int i = top_depth; i > 0; i -= step, ++start)
{
if (start >= 10)
step *= 2;
indices.push_back(i);
}
indices.push_back(0);
return indices;
}
</pre>

Note that it is allowed to send in fewer known hashes down to a minimum of just one hash. However, the purpose of the block locator object is to detect a wrong branch in the caller's main chain. If the peer detects that you are off the main chain, it will send in block hashes which are earlier than your last known block. So if you just send in your last known hash and it is off the main chain, the peer starts over at block #1.

=== getheaders ===

Return a ''headers'' packet containing the headers of blocks starting right after the last known hash in the block locator object, up to hash_stop or 2000 blocks, whichever comes first. To receive the next block headers, one needs to issue getheaders again with a new block locator object. The ''getheaders'' command is used by thin clients to quickly download the blockchain where the contents of the transactions would be irrelevant (because they are not ours). Keep in mind that some clients (specifically the Satoshi client) will gladly provide headers of blocks which are invalid if the block locator object contains a hash on the invalid branch.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || uint32_t || the protocol version
|-
| 1+ || hash count || [[Protocol_specification#Variable_length_integer|var_int]] || number of block locator hash entries
|-
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)
|-
| 32 || hash_stop || char[32] || hash of the last desired block header; set to zero to get as many blocks as possible (2000)
|}

For the block locator object in this packet, the same rules apply as for the [[Protocol_specification#getblocks|getblocks]] packet.

=== tx ===

''tx'' describes a bitcoin transaction, in reply to ''getdata''

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || uint32_t || Transaction data format version
|-
| 1+ || tx_in count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of Transaction inputs
|-
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins
|-
| 1+ || tx_out count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of Transaction outputs
|-
| 9+ || tx_out || tx_out[] || A list of 1 or more transaction outputs or destinations for coins
|-
| 4 || lock_time || uint32_t || The block number or timestamp at which this transaction is locked:
{|class="wikitable"
! Value !! Description
|-
| 0 || Always locked
|-
| < 500000000 || Block number at which this transaction is locked
|-
| >= 500000000 || UNIX timestamp at which this transaction is locked
|}
If all TxIn inputs have final (0xffffffff) sequence numbers then lock_time is irrelevant. Otherwise, the transaction may not be added to a block until after lock_time.

|}

TxIn consists of the following fields:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 36 || previous_output || outpoint || The previous output transaction reference, as an OutPoint structure
|-
| 1+ || script length || [[Protocol_specification#Variable_length_integer|var_int]] || The length of the signature script
|-
| ? || signature script || uchar[] || Computational Script for confirming transaction authorization
|-
| 4 || [http://bitcoin.stackexchange.com/q/2025/323 sequence] || uint32_t || Transaction version as defined by the sender. Intended for "replacement" of transactions when information is updated before inclusion into a block.
|}

The OutPoint structure consists of the following fields:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 32 || hash || char[32] || The hash of the referenced transaction.
|-
| 4 || index || uint32_t || The index of the specific output in the transaction. The first output is 0, etc.
|}

The Script structure consists of a series of pieces of information and operations related to the value of the transaction.

(Structure to be expanded in the future… see script.h and script.cpp and [[Script]] for more information)

The TxOut structure consists of the following fields:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8 || value || int64_t || Transaction Value
|-
| 1+ || pk_script length || [[Protocol_specification#Variable_length_integer|var_int]] || Length of the pk_script
|-
| ? || pk_script || uchar[] || Usually contains the public key as a Bitcoin script setting up conditions to claim this output.
|}

Example ''tx'' message:
<pre>
000000 F9 BE B4 D9 74 78 00 00 00 00 00 00 00 00 00 00 ....tx..........
000010 02 01 00 00 E2 93 CD BE 01 00 00 00 01 6D BD DB .............m..
000020 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D 12 66 E9 .[...Q........f.
000030 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29 00 00 00 .;P......j.6)...
000040 00 8B 48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 ..H0E.!..X..r...
000050 C7 36 7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A .6zz%;..R#...h.:
000060 59 23 3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 Y#?E.W... Y.....
000070 0E 41 83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D .A.z.X.z...XN...
000080 35 BD 96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF 5...6..;...A....
000090 C9 7E F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 .~.6.m...@..!...
0000A0 2A CD 2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC *.+..].}Y... ...
0000B0 4E 02 53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F N.S..=7.o...Q...
0000C0 14 04 2F 46 61 4A 4C 70 C0 F1 4B EF F5 FF FF FF ../FaJLp..K.....
0000D0 FF 02 40 4B 4C 00 00 00 00 00 19 76 A9 14 1A A0 ..@KL......v....
0000E0 CD 1C BE A6 E7 45 8A 7A BA D5 12 A9 D9 EA 1A FB .....E.z........
0000F0 22 5E 88 AC 80 FA E9 C7 00 00 00 00 19 76 A9 14 "^...........v..
000100 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E FD A0 B7 ..[.Cj.....H^...
000110 8B 4E CC 52 88 AC 00 00 00 00 .N.R......

Message header:
F9 BE B4 D9 - main network magic bytes
74 78 00 00 00 00 00 00 00 00 00 00 - "tx" command
02 01 00 00 - payload is 258 bytes long
E2 93 CD BE - checksum of payload

Transaction:
01 00 00 00 - version

Inputs:
01 - number of transaction inputs

Input 1:
6D BD DB 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D - previous output (outpoint)
12 66 E9 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29
00 00 00 00

8B - script is 139 bytes long

48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 C7 36 - signature script (scriptSig)
7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A 59 23
3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 0E 41
83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D 35 BD
96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF C9 7E
F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 2A CD
2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC 4E 02
53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F 14 04
2F 46 61 4A 4C 70 C0 F1 4B EF F5

FF FF FF FF - sequence

Outputs:
02 - 2 Output Transactions

Output 1:
40 4B 4C 00 00 00 00 00 - 0.05 BTC (5000000)
19 - pk_script is 25 bytes long

76 A9 14 1A A0 CD 1C BE A6 E7 45 8A 7A BA D5 12 - pk_script
A9 D9 EA 1A FB 22 5E 88 AC

Output 2:
80 FA E9 C7 00 00 00 00 - 33.54 BTC (3354000000)
19 - pk_script is 25 bytes long

76 A9 14 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E - pk_script
FD A0 B7 8B 4E CC 52 88 AC

Locktime:
00 00 00 00 - lock time
</pre>

=== block ===

The '''block''' message is sent in response to a getdata message which requests transaction information from a block hash.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || uint32_t || Block version information, based upon the software version creating this block
|-
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references
|-
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block
|-
| 4 || timestamp || uint32_t || A unix timestamp recording when this block was created (Currently limited to dates before the year 2106!)
|-
| 4 || bits || uint32_t || The calculated [[Difficulty|difficulty target]] being used for this block
|-
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes
|-
| ? || txn_count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of transaction entries
|-
| ? || txns || tx[] || Block transactions, in format of "tx" command
|}

The SHA256 hash that identifies each block (and which must have a run of 0 bits) is calculated from the first 6 fields of this structure (version, prev_block, merkle_root, timestamp, bits, nonce, and standard SHA256 padding, making two 64-byte chunks in all) and ''not'' from the complete block. To calculate the hash, only two chunks need to be processed by the SHA256 algorithm. Since the ''nonce'' field is in the second chunk, the first chunk stays constant during mining and therefore only the second chunk needs to be processed. However, a Bitcoin hash is the hash of the hash, so two SHA256 rounds are needed for each mining iteration.
See [[Block hashing algorithm]] for details and an example.

=== headers ===

The ''headers'' packet returns block headers in response to a ''getheaders'' packet.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of block headers
|-
| 81x? || headers || [[Protocol_specification#Block_Headers|block_header]][] || [[Protocol_specification#Block_Headers|Block headers]]
|}

Note that the block headers in this packet include a transaction count (a var_int, so there can be more than 81 bytes per header) as opposed to the block headers which are sent to miners.

=== getaddr ===

The getaddr message sends a request to a node asking for information about known active peers to help with identifying potential nodes in the network. The response to receiving this message is to transmit an addr message with one or more peers from a database of known active peers. The typical presumption is that a node is likely to be active if it has been sending a message within the last three hours.

No additional data is transmitted with this message.

=== mempool ===

The mempool message sends a request to a node asking for information about transactions it has verified but which have not yet confirmed. The response to receiving this message is an inv message containing the transaction hashes for all the transactions in the node's mempool.

No additional data is transmitted with this message.

It is specified in [[BIP_0035|BIP 35]]. Since [[BIP_0037|BIP 37]], only transactions matching the filter are replied.

=== checkorder ===

This message is used for [[IP Transactions]], to ask the peer if it accepts such transactions and allow it to look at the content of the order.

It contains a CWalletTx object

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
|colspan="4"| Fields from CMerkleTx
|-
| ? || hashBlock
|-
| ? || vMerkleBranch
|-
| ? || nIndex
|-
|colspan="4"| Fields from CWalletTx
|-
| ? || vtxPrev
|-
| ? || mapValue
|-
| ? || vOrderForm
|-
| ? || fTimeReceivedIsTxTime
|-
| ? || nTimeReceived
|-
| ? || fFromMe
|-
| ? || fSpent
|}

=== submitorder ===

Confirms an order has been submitted.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 32 || hash || char[32] || Hash of the transaction
|-
| ? || wallet_entry || CWalletTx || Same payload as checkorder
|}

=== reply ===

Generic reply for [[IP Transactions]]

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || reply || uint32_t || reply code
|}

Possible values:

{|class="wikitable"
! Value !! Name !! Description
|-
| 0 || SUCCESS || The IP Transaction can proceed (''checkorder''), or has been accepted (''submitorder'')
|-
| 1 || WALLET_ERROR || AcceptWalletTransaction() failed
|-
| 2 || DENIED || IP Transactions are not accepted by this node
|}

=== ping ===

The ''ping'' message is sent primarily to confirm that the TCP/IP connection is still valid. An error in transmission is presumed to be a closed connection and the address is removed as a current peer. In modern protocol versions, a ''pong'' response is generated using a nonce included in the ping.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8 || nonce || uint64_t || random nonce
|}

=== filterload, filteradd, filterclear, merkleblock ===

These messages are related to Bloom filtering of connections and are defined in [[BIP 0037]].

=== alert ===

An '''alert''' is sent between nodes to send a general notification message throughout the network. If the alert can be confirmed with the signature as having come from the the core development group of the Bitcoin software, the message is suggested to be displayed for end-users. Attempts to perform transactions, particularly automated transactions through the client, are suggested to be halted. The text in the Message string should be relayed to log files and any user interfaces.

Alert format:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || payload || var_str || Serialized alert payload
|-
| ? || signature || var_str || An ECDSA signature of the message
|}

The developers of Satoshi's client use this public key for signing alerts:
04fc9702847840aaf195de8442ebecedf5b095cdbb9bc716bda9110971b28a49e0ead8564ff0db22209e0374782c093bb899692d524e9d6a6956e7c5ecbcd68284
(hash) 1AGRxqDa5WjUKBwHB9XYEjmkv1ucoUUy1s

The payload is serialized into a var_str to ensure that versions using incompatible alert formats can still relay alerts among one another. The current alert payload format is:
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || Version || int32_t || Alert format version
|-
| 8 || RelayUntil || int64_t || The timestamp beyond which nodes should stop relaying this alert
|-
| 8 || Expiration || int64_t || The timestamp beyond which this alert is no longer in effect and should be ignored
|-
| 4 || ID || int32_t || A unique ID number for this alert
|-
| 4 || Cancel || int32_t || All alerts with an ID number less than or equal to this number should be canceled: deleted and not accepted in the future
|-
| ? || setCancel || set<int> || All alert IDs contained in this set should be canceled as above
|-
| 4 || MinVer || int32_t || This alert only applies to versions greater than or equal to this version. Other versions should still relay it.
|-
| 4 || MaxVer || int32_t || This alert only applies to versions less than or equal to this version. Other versions should still relay it.
|-
| ? || setSubVer || set<string> || If this set contains any elements, then only nodes that have their subVer contained in this set are affected by the alert. Other versions should still relay it.
|-
| 4 || Priority || int32_t || Relative priority compared to other alerts
|-
| ? || Comment || string || A comment on the alert that is not displayed
|-
| ? || StatusBar || string || The alert message that is displayed to the user
|-
| ? || Reserved || string || Reserved
|}

Sample alert (no message header):
73010000003766404f00000000b305434f00000000f2030000f1030000001027000048ee0000
0064000000004653656520626974636f696e2e6f72672f666562323020696620796f75206861
76652074726f75626c6520636f6e6e656374696e672061667465722032302046656272756172
79004730450221008389df45f0703f39ec8c1cc42c13810ffcae14995bb648340219e353b63b
53eb022009ec65e1c1aaeec1fd334c6b684bde2b3f573060d5b70c3a46723326e4e8a4f1

Version: 1
RelayUntil: 1329620535
Expiration: 1329792435
ID: 1010
Cancel: 1009
setCancel: <empty>
MinVer: 10000
MaxVer: 61000
setSubVer: <empty>
Priority: 100
Comment: <empty>
StatusBar: "See bitcoin.org/feb20 if you have trouble connecting after 20 February"
Reserved: <empty>

== Scripting ==

See [[script]].

== Wireshark dissector ==
A dissector for wireshark is being developed at https://github.com/blueCommand/bitcoin-dissector

==See Also==

* [[Network]]
* [[Protocol rules]]
* [[Hardfork Wishlist]]

==References==
<references />

[[zh-cn:协议说明]]
[[Category:Technical]]
[[Category:Developer]]

Protocol documentation

2013-08-17T18:49:14Z

CodeShark: /* Message types */

Sources:
* [[Original Bitcoin client]] source

Type names used in this documentation are from the C99 standard.

For protocol used in mining, see [[Getwork]].

==Common standards==

=== Hashes ===

Usually, when a hash is computed within bitcoin, it is computed twice. Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-256] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when a shorter hash is desirable (for example when creating a bitcoin address).

Example of double-SHA-256 encoding of string "hello":

hello
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round of sha-256)
9595c9df90075148eb06860365df33584b75bff782a510c6cd4883a419833d50 (second round of sha-256)

For bitcoin addresses (RIPEMD-160) this would give:

hello
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round is sha-256)
b6a9c8c230722b7c748331a8b450f05566dc7d0f (with ripemd-160)

=== Merkle Trees ===

Merkle trees are binary trees of hashes. Merkle trees in bitcoin use a '''double''' SHA-256, the SHA-256 hash of the SHA-256 hash of something.

If, when forming a row in the tree (other than the root of the tree), it would have an odd number of elements, the final double-hash is duplicated to ensure that the row has an even number of hashes.

First form the bottom row of the tree with the ordered double-SHA-256 hashes of the byte streams of the transactions in the block.

Then the row above it consists of half that number of hashes. Each entry is the double-SHA-256 of the 64-byte concatenation of the corresponding two hashes below it in the tree.

This procedure repeats recursively until we reach a row consisting of just a single double-hash. This is the '''merkle root''' of the tree.

For example, imagine a block with three transactions ''a'', ''b'' and ''c''. The merkle tree is:

d1 = dhash(a)
d2 = dhash(b)
d3 = dhash(c)
d4 = dhash(c) # a, b, c are 3. that's an odd number, so we take the c twice

d5 = dhash(d1 concat d2)
d6 = dhash(d3 concat d4)

d7 = dhash(d5 concat d6)

where

dhash(a) = sha256(sha256(a))

''d7'' is the merkle root of the 3 transactions in this block.

Note: Hashes in Merkle Tree displayed in the [[Block Explorer]] are of little-endian notation. For some implementations and [http://www.fileformat.info/tool/hash.htm calculations], the bits need to be reversed before they are hashed, and again after the hashing operation.

=== Signatures ===

Bitcoin uses [http://en.wikipedia.org/wiki/Elliptic_curve_cryptography Elliptic Curve] [http://en.wikipedia.org/wiki/Digital_Signature_Algorithm Digital Signature Algorithm] ([http://en.wikipedia.org/wiki/Elliptic_Curve_DSA ECDSA]) to sign transactions.

For ECDSA the secp256k1 curve from http://www.secg.org/collateral/sec2_final.pdf is used.

Public keys (in scripts) are given as 04 <x> <y> where ''x'' and ''y'' are 32 byte big-endian integers representing the coordinates of a point on the curve or in compressed form given as <sign> <x> where <sign> is 0x02 if ''y'' is even and 0x03 if ''y'' is odd.

Signatures use [http://en.wikipedia.org/wiki/Distinguished_Encoding_Rules DER encoding] to pack the ''r'' and ''s'' components into a single byte stream (this is also what OpenSSL produces by default).

=== Transaction Verification ===
Transactions are cryptographically signed records that reassign ownership of Bitcoins to new addresses. Transactions have ''inputs'' - records which reference the funds from other previous transactions - and ''outputs'' - records which determine the new owner of the transferred Bitcoins, and which will be referenced as inputs in future transactions as those funds are respent.

Each ''input'' must have a cryptographic digital signature that unlocks the funds from the prior transaction. Only the person possessing the appropriate [[private key]] is able to create a satisfactory signature; this in effect ensures that funds can only be spent by their owners.

Each ''output'' determines which Bitcoin address (or other criteria, see [[Scripting]]) is the recipient of the funds.

In a transaction, the sum of all inputs must be equal to or greater than the sum of all outputs. If the inputs exceed the outputs, the difference is considered a [[transaction fee]], and is redeemable by whoever first includes the transaction into the block chain.

A special kind of transaction, called a [[coinbase transaction]], has no inputs. It is created by [[miners]], and there is one coinbase transaction per block. Because each block comes with a reward of newly created Bitcoins (e.g. 50 BTC for the first 210,000 blocks), the first transaction of a block is, with few exceptions, the transaction that grants those coins to their recipient (the miner). In addition to the newly created Bitcoins, the coinbase transaction is also used for assigning the recipient of any transaction fees that were paid within the other transactions being included in the same block. The coinbase transaction can assign the entire reward to a single Bitcoin address, or split it in portions among multiple addresses, just like any other transaction. Coinbase transactions always contain outputs totaling the sum of the block reward plus all transaction fees collected from the other transactions in the same block.

The [[coinbase transaction]] in block zero cannot be spent. This is due to a quirk of the reference client implementation that would open the potential for a block chain fork if some nodes accepted the spend and others did not<ref>[http://bitcointalk.org/index.php?topic=119645.msg1288552#msg1288552 Block 0 Network Fork]</ref>.

Most Bitcoin outputs encumber the newly transferred coins with a single ECDSA private key. The actual record saved with inputs and outputs isn't necessarily a key, but a ''script''. Bitcoin uses an interpreted scripting system to determine whether an output's criteria have been satisfied, with which more complex operations are possible, such as outputs that require two ECDSA signatures, or two-of-three-signature schemes. An output that references a single Bitcoin address is a ''typical'' output; an output actually contains this information in the form of a script that requires a single ECDSA signature (see [[OP_CHECKSIG]]). The output script specifies what must be provided to unlock the funds later, and when the time comes in the future to spend the transaction in another input, that input must provide all of the thing(s) that satisfy the requirements defined by the original output script.

=== Addresses ===

A bitcoin address is in fact the hash of a ECDSA public key, computed this way:

Version = 1 byte of 0 (zero); on the test network, this is 1 byte of 111
Key hash = Version concatenated with RIPEMD-160(SHA-256(public key))
Checksum = 1st 4 bytes of SHA-256(SHA-256(Key hash))
Bitcoin Address = Base58Encode(Key hash concatenated with Checksum)

The Base58 encoding used is home made, and has some differences. Especially, leading zeroes are kept as single zeroes when conversion happens.

== Common structures ==

Almost all integers are encoded in little endian. Only IP or port number are encoded big endian.

=== Message structure ===

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown
|-
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)
|-
| 4 || length || uint32_t || Length of payload in number of bytes
|-
| 4 || checksum || uint32_t || First 4 bytes of sha256(sha256(payload))
|-
| ? || payload || uchar[] || The actual data
|}

Known magic values:

{|class="wikitable"
! Network !! Magic value !! Sent over wire as
|-
| main || 0xD9B4BEF9 || F9 BE B4 D9
|-
| testnet || 0xDAB5BFFA || FA BF B5 DA
|-
| testnet3 || 0x0709110B || 0B 11 09 07
|-
| namecoin || 0xFEB4BEF9 || F9 BE B4 FE
|}

=== Variable length integer ===

Integer can be encoded depending on the represented value to save space.
Variable length integers always precede an array/vector of a type of data that may vary in length.
Longer numbers are encoded in little endian.

{|class="wikitable"
! Value !! Storage length !! Format
|-
| < 0xfd || 1 || uint8_t
|-
| <= 0xffff || 3 || 0xfd followed by the length as uint16_t
|-
| <= 0xffffffff || 5 || 0xfe followed by the length as uint32_t
|-
| - || 9 || 0xff followed by the length as uint64_t
|}

If you're reading the Satoshi client code (BitcoinQT) it refers to this as a "CompactSize". Modern BitcoinQT has also CVarInt class which implements even more compact integer for the purpose of local storage (which is incompatible with "CompactSize" described here). CVarInt is not a part of the protocol.

=== Variable length string ===

Variable length string can be stored using a variable length integer followed by the string itself.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || length || [[Protocol_specification#Variable_length_integer|var_int]] || Length of the string
|-
| ? || string || char[] || The string itself (can be empty)
|}

=== Network address ===

When a network address is needed somewhere, this structure is used. This protocol and structure supports IPv6, '''but note that the original client currently only supports IPv4 networking'''. Network addresses are not prefixed with a timestamp in the version message.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || time || uint32 || the Time (version >= 31402)
|-
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]
|-
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The original client only supports IPv4 and only reads the last 4 bytes to get the IPv4 address. However, the IPv4 address is written into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).
|-
| 2 || port || uint16_t || port number, network byte order
|}

Hexdump example of Network address structure

<pre>
0000 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
0010 00 00 FF FF 0A 00 00 01 20 8D ........ .

Network address:
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK: see services listed under version command)
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv6: ::ffff:10.0.0.1 or IPv4: 10.0.0.1
20 8D - Port 8333
</pre>

=== Inventory Vectors ===

Inventory vectors are used for notifying other nodes about objects they have or data which is being requested.

Inventory vectors consist of the following data format:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || type || uint32_t || Identifies the object type linked to this inventory
|-
| 32 || hash || char[32] || Hash of the object
|}

The object type is currently defined as one of the following possibilities:

{|class="wikitable"
! Value !! Name !! Description
|-
| 0 || ERROR || Any data of with this number may be ignored
|-
| 1 || MSG_TX || Hash is related to a transaction
|-
| 2 || MSG_BLOCK || Hash is related to a data block
|}

Other Data Type values are considered reserved for future implementations.

=== Block Headers ===

Block headers are sent in a headers packet in response to a getheaders message.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || uint32_t || Block version information, based upon the software version creating this block
|-
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references
|-
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block
|-
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Will overflow in 2106<ref>http://en.wikipedia.org/wiki/Unix_time#Notable.C2.A0events.C2.A0in.C2.A0Unix.C2.A0time</ref>)
|-
| 4 || bits || uint32_t || The calculated difficulty target being used for this block
|-
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes
|-
| 1 || txn_count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of transaction entries, this value is always 0
|}

== Message types ==

=== version ===

When a node creates an outgoing connection, it will immediately [[Version Handshake|advertise]] its version. The remote node will respond with its version. No futher communication is possible until both peers have exchanged their version.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || int32_t || Identifies protocol version being used by the node
|-
| 8 || services || uint64_t || bitfield of features to be enabled for this connection
|-
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds
|-
| 26 || addr_recv || net_addr || The network address of the node receiving this message
|-
|colspan="4"| version >= 106
|-
| 26 || addr_from || net_addr || The network address of the node emitting this message
|-
| 8 || nonce || uint64_t || Node random nonce, randomly generated every time a version packet is sent. This nonce is used to detect connections to self.
|-
| ? || user_agent || [[#Variable length string|var_str]] || [[BIP_0014|User Agent]] (0x00 if string is 0 bytes long)
|-
| 4 || start_height || int32_t || The last block received by the emitting node
|-
| 1 || relay || bool || Whether the remote peer should announce relayed transactions or not, see [[BIP 0037]], since version >= 70001
|}

A "verack" packet shall be sent if the version packet was accepted.

The following services are currently assigned:

{|class="wikitable"
! Value !! Name !! Description
|-
| 1 || NODE_NETWORK || This node can be asked for full blocks instead of just headers.
|}

Hexdump example of version message (OBSOLETE EXAMPLE. This example lacks a checksum and user-agent):
<pre>
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................
0040 20 8D 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,
0060 3A B4 57 13 00 55 81 01 00 :.W..U...

Message header:
F9 BE B4 D9 - Main network magic bytes
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command
55 00 00 00 - Payload is 85 bytes long
- No checksum in version message until 20 February 2012. See https://bitcointalk.org/index.php?topic=55852.0
Version message:
9C 7C 00 00 - 31900 (version 0.3.19)
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)
E6 15 10 4D 00 00 00 00 - Mon Dec 20 21:50:14 EST 2010
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 20 8D - Recipient address info - see Network Address
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D - Sender address info - see Network Address
DD 9D 20 2C 3A B4 57 13 - Node random unique ID
00 - "" sub-version string (string is 0 bytes long)
55 81 01 00 - Last block sending node has is block #98645
</pre>

And here's a modern (60002) protocol version client advertising itself to a local peer...

Newer protocol includes the checksum now, this is from a mainline (satoshi) client during
an outgoing connection to another local client, notice that it does not fill out the
address information at all when the source or destination is "unroutable".

<pre>

0000 f9 be b4 d9 76 65 72 73 69 6f 6e 00 00 00 00 00 ....version.....
0010 64 00 00 00 35 8d 49 32 62 ea 00 00 01 00 00 00 d...5.I2b.......
0020 00 00 00 00 11 b2 d0 50 00 00 00 00 01 00 00 00 .......P........
0030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ff ff ................
0040 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
0050 00 00 00 00 00 00 00 00 ff ff 00 00 00 00 00 00 ................
0060 3b 2e b3 5d 8c e6 17 65 0f 2f 53 61 74 6f 73 68 ;..]...e./Satosh
0070 69 3a 30 2e 37 2e 32 2f c0 3e 03 00 i:0.7.2/.>..

Message Header:
F9 BE B4 D9 - Main network magic bytes
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command
64 00 00 00 - Payload is 100 bytes long
3B 64 8D 5A - payload checksum

Version message:
62 EA 00 00 - 60002 (protocol version 60002)
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)
11 B2 D0 50 00 00 00 00 - Tue Dec 18 10:12:33 PST 2012
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Recipient address info - see Network Address
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Sender address info - see Network Address
3B 2E B3 5D 8C E6 17 65 - Node ID
0F 2F 53 61 74 6F 73 68 69 3A 30 2E 37 2E 32 2F - "/Satoshi:0.7.2/" sub-version string (string is 15 bytes long)
C0 3E 03 00 - Last block sending node has is block #212672
</pre>

=== verack ===

The ''verack'' message is sent in reply to ''version''. This message consists of only a [[#Message structure|message header]] with the command string "verack".

Hexdump of the verack message:

<pre>
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......
0010 00 00 00 00 5D F6 E0 E2 ........

Message header:
F9 BE B4 D9 - Main network magic bytes
76 65 72 61 63 6B 00 00 00 00 00 00 - "verack" command
00 00 00 00 - Payload is 0 bytes long
5D F6 E0 E2 - Checksum
</pre>

=== addr ===

Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours

Payload:
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+ || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of address entries (max: 1000)
|-
| 30x? || addr_list || (uint32_t + net_addr)[] || Address of other nodes on the network. version < 209 will only read the first one. The uint32_t is a timestamp (see note below).
|}

'''Note''': Starting version 31402, addresses are prefixed with a timestamp. If no timestamp is present, the addresses should not be relayed to other peers, unless it is indeed confirmed they are up.

Hexdump example of ''addr'' message:
<pre>
0000 F9 BE B4 D9 61 64 64 72 00 00 00 00 00 00 00 00 ....addr........
0010 1F 00 00 00 ED 52 39 9B 01 E2 15 10 4D 01 00 00 .....R9.....M...
0020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF ................
0030 FF 0A 00 00 01 20 8D ..... .

Message Header:
F9 BE B4 D9 - Main network magic bytes
61 64 64 72 00 00 00 00 00 00 00 00 - "addr"
1F 00 00 00 - payload is 31 bytes long
ED 52 39 9B - checksum of payload

Payload:
01 - 1 address in this message

Address:
E2 15 10 4D - Mon Dec 20 21:50:10 EST 2010 (only when version is >= 31402)
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK service - see version message)
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv4: 10.0.0.1, IPv6: ::ffff:10.0.0.1 (IPv4-mapped IPv6 address)
20 8D - port 8333
</pre>

=== inv ===

Allows a node to advertise its knowledge of one or more objects. It can be received unsolicited, or in reply to ''getblocks''.

Payload (maximum payload length: 1.8 Megabytes or 50000 entries):

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of inventory entries
|-
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors
|}

=== getdata ===

getdata is used in response to inv, to retrieve the content of a specific object, and is usually sent after receiving an ''inv'' packet, after filtering known elements. It can be used to retrieve transactions, but only if they are in the memory pool or relay set - arbitrary access to transactions in the chain is not allowed to avoid having clients start to depend on nodes having full transaction indexes (which modern nodes do not).

Payload (maximum payload length: 1.8 Megabytes or 50000 entries):

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of inventory entries
|-
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors
|}

=== notfound ===

notfound is a response to a getdata, sent if any requested data items could not be relayed, for example, because the requested transaction was not in the memory pool or relay set.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of inventory entries
|-
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors
|}

=== getblocks ===

Return an ''inv'' packet containing the list of blocks starting right after the last known hash in the block locator object, up to hash_stop or 500 blocks, whichever comes first.

The locator hashes are processed by a node in the order as they appear in the message. If a block hash if found in the node's main chain, the list of it's children is returned back via the ''inv'' message and the remaining locators are ignored, no matter if the requested limit was reached, or not.

To receive the next blocks hashes, one needs to issue getblocks again with a new block locator object. Keep in mind that some clients (specifically the Satoshi client) will gladly provide blocks which are invalid if the block locator object contains a hash on the invalid branch.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || uint32_t || the protocol version
|-
| 1+ || hash count || [[Protocol_specification#Variable_length_integer|var_int]] || number of block locator hash entries
|-
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)
|-
| 32 || hash_stop || char[32] || hash of the last desired block; set to zero to get as many blocks as possible (500)
|}

To create the block locator hashes, keep pushing hashes until you go back to the genesis block. After pushing 10 hashes back, the step backwards doubles every loop:

<pre>
// From libbitcoin which is under AGPL
std::vector<size_t> block_locator_indices(int top_depth)
{
// Start at max_depth
std::vector<size_t> indices;
// Push last 10 indices first
size_t step = 1, start = 0;
for (int i = top_depth; i > 0; i -= step, ++start)
{
if (start >= 10)
step *= 2;
indices.push_back(i);
}
indices.push_back(0);
return indices;
}
</pre>

Note that it is allowed to send in fewer known hashes down to a minimum of just one hash. However, the purpose of the block locator object is to detect a wrong branch in the caller's main chain. If the peer detects that you are off the main chain, it will send in block hashes which are earlier than your last known block. So if you just send in your last known hash and it is off the main chain, the peer starts over at block #1.

=== getheaders ===

Return a ''headers'' packet containing the headers of blocks starting right after the last known hash in the block locator object, up to hash_stop or 2000 blocks, whichever comes first. To receive the next block headers, one needs to issue getheaders again with a new block locator object. The ''getheaders'' command is used by thin clients to quickly download the blockchain where the contents of the transactions would be irrelevant (because they are not ours). Keep in mind that some clients (specifically the Satoshi client) will gladly provide headers of blocks which are invalid if the block locator object contains a hash on the invalid branch.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || uint32_t || the protocol version
|-
| 1+ || hash count || [[Protocol_specification#Variable_length_integer|var_int]] || number of block locator hash entries
|-
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)
|-
| 32 || hash_stop || char[32] || hash of the last desired block header; set to zero to get as many blocks as possible (2000)
|}

For the block locator object in this packet, the same rules apply as for the [[Protocol_specification#getblocks|getblocks]] packet.

=== tx ===

''tx'' describes a bitcoin transaction, in reply to ''getdata''

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || uint32_t || Transaction data format version
|-
| 1+ || tx_in count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of Transaction inputs
|-
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins
|-
| 1+ || tx_out count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of Transaction outputs
|-
| 9+ || tx_out || tx_out[] || A list of 1 or more transaction outputs or destinations for coins
|-
| 4 || lock_time || uint32_t || The block number or timestamp at which this transaction is locked:
{|class="wikitable"
! Value !! Description
|-
| 0 || Always locked
|-
| < 500000000 || Block number at which this transaction is locked
|-
| >= 500000000 || UNIX timestamp at which this transaction is locked
|}
If all TxIn inputs have final (0xffffffff) sequence numbers then lock_time is irrelevant. Otherwise, the transaction may not be added to a block until after lock_time.

|}

TxIn consists of the following fields:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 36 || previous_output || outpoint || The previous output transaction reference, as an OutPoint structure
|-
| 1+ || script length || [[Protocol_specification#Variable_length_integer|var_int]] || The length of the signature script
|-
| ? || signature script || uchar[] || Computational Script for confirming transaction authorization
|-
| 4 || [http://bitcoin.stackexchange.com/q/2025/323 sequence] || uint32_t || Transaction version as defined by the sender. Intended for "replacement" of transactions when information is updated before inclusion into a block.
|}

The OutPoint structure consists of the following fields:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 32 || hash || char[32] || The hash of the referenced transaction.
|-
| 4 || index || uint32_t || The index of the specific output in the transaction. The first output is 0, etc.
|}

The Script structure consists of a series of pieces of information and operations related to the value of the transaction.

(Structure to be expanded in the future… see script.h and script.cpp and [[Script]] for more information)

The TxOut structure consists of the following fields:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8 || value || int64_t || Transaction Value
|-
| 1+ || pk_script length || [[Protocol_specification#Variable_length_integer|var_int]] || Length of the pk_script
|-
| ? || pk_script || uchar[] || Usually contains the public key as a Bitcoin script setting up conditions to claim this output.
|}

Example ''tx'' message:
<pre>
000000 F9 BE B4 D9 74 78 00 00 00 00 00 00 00 00 00 00 ....tx..........
000010 02 01 00 00 E2 93 CD BE 01 00 00 00 01 6D BD DB .............m..
000020 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D 12 66 E9 .[...Q........f.
000030 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29 00 00 00 .;P......j.6)...
000040 00 8B 48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 ..H0E.!..X..r...
000050 C7 36 7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A .6zz%;..R#...h.:
000060 59 23 3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 Y#?E.W... Y.....
000070 0E 41 83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D .A.z.X.z...XN...
000080 35 BD 96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF 5...6..;...A....
000090 C9 7E F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 .~.6.m...@..!...
0000A0 2A CD 2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC *.+..].}Y... ...
0000B0 4E 02 53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F N.S..=7.o...Q...
0000C0 14 04 2F 46 61 4A 4C 70 C0 F1 4B EF F5 FF FF FF ../FaJLp..K.....
0000D0 FF 02 40 4B 4C 00 00 00 00 00 19 76 A9 14 1A A0 ..@KL......v....
0000E0 CD 1C BE A6 E7 45 8A 7A BA D5 12 A9 D9 EA 1A FB .....E.z........
0000F0 22 5E 88 AC 80 FA E9 C7 00 00 00 00 19 76 A9 14 "^...........v..
000100 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E FD A0 B7 ..[.Cj.....H^...
000110 8B 4E CC 52 88 AC 00 00 00 00 .N.R......

Message header:
F9 BE B4 D9 - main network magic bytes
74 78 00 00 00 00 00 00 00 00 00 00 - "tx" command
02 01 00 00 - payload is 258 bytes long
E2 93 CD BE - checksum of payload

Transaction:
01 00 00 00 - version

Inputs:
01 - number of transaction inputs

Input 1:
6D BD DB 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D - previous output (outpoint)
12 66 E9 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29
00 00 00 00

8B - script is 139 bytes long

48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 C7 36 - signature script (scriptSig)
7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A 59 23
3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 0E 41
83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D 35 BD
96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF C9 7E
F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 2A CD
2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC 4E 02
53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F 14 04
2F 46 61 4A 4C 70 C0 F1 4B EF F5

FF FF FF FF - sequence

Outputs:
02 - 2 Output Transactions

Output 1:
40 4B 4C 00 00 00 00 00 - 0.05 BTC (5000000)
19 - pk_script is 25 bytes long

76 A9 14 1A A0 CD 1C BE A6 E7 45 8A 7A BA D5 12 - pk_script
A9 D9 EA 1A FB 22 5E 88 AC

Output 2:
80 FA E9 C7 00 00 00 00 - 33.54 BTC (3354000000)
19 - pk_script is 25 bytes long

76 A9 14 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E - pk_script
FD A0 B7 8B 4E CC 52 88 AC

Locktime:
00 00 00 00 - lock time
</pre>

=== block ===

The '''block''' message is sent in response to a getdata message which requests transaction information from a block hash.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || uint32_t || Block version information, based upon the software version creating this block
|-
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references
|-
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block
|-
| 4 || timestamp || uint32_t || A unix timestamp recording when this block was created (Currently limited to dates before the year 2106!)
|-
| 4 || bits || uint32_t || The calculated [[Difficulty|difficulty target]] being used for this block
|-
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes
|-
| ? || txn_count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of transaction entries
|-
| ? || txns || tx[] || Block transactions, in format of "tx" command
|}

The SHA256 hash that identifies each block (and which must have a run of 0 bits) is calculated from the first 6 fields of this structure (version, prev_block, merkle_root, timestamp, bits, nonce, and standard SHA256 padding, making two 64-byte chunks in all) and ''not'' from the complete block. To calculate the hash, only two chunks need to be processed by the SHA256 algorithm. Since the ''nonce'' field is in the second chunk, the first chunk stays constant during mining and therefore only the second chunk needs to be processed. However, a Bitcoin hash is the hash of the hash, so two SHA256 rounds are needed for each mining iteration.
See [[Block hashing algorithm]] for details and an example.

=== headers ===

The ''headers'' packet returns block headers in response to a ''getheaders'' packet.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of block headers
|-
| 81x? || headers || [[Protocol_specification#Block_Headers|block_header]][] || [[Protocol_specification#Block_Headers|Block headers]]
|}

Note that the block headers in this packet include a transaction count (a var_int, so there can be more than 81 bytes per header) as opposed to the block headers which are sent to miners.

=== getaddr ===

The getaddr message sends a request to a node asking for information about known active peers to help with identifying potential nodes in the network. The response to receiving this message is to transmit an addr message with one or more peers from a database of known active peers. The typical presumption is that a node is likely to be active if it has been sending a message within the last three hours.

No additional data is transmitted with this message.

=== mempool ===

The mempool message sends a request to a node asking for information about transactions it has verified but which have not yet confirmed. The response to receiving this message is an inv message containing the transaction hashes for all the transactions in the node's mempool.

No additional data is transmitted with this message.

=== checkorder ===

This message is used for [[IP Transactions]], to ask the peer if it accepts such transactions and allow it to look at the content of the order.

It contains a CWalletTx object

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
|colspan="4"| Fields from CMerkleTx
|-
| ? || hashBlock
|-
| ? || vMerkleBranch
|-
| ? || nIndex
|-
|colspan="4"| Fields from CWalletTx
|-
| ? || vtxPrev
|-
| ? || mapValue
|-
| ? || vOrderForm
|-
| ? || fTimeReceivedIsTxTime
|-
| ? || nTimeReceived
|-
| ? || fFromMe
|-
| ? || fSpent
|}

=== submitorder ===

Confirms an order has been submitted.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 32 || hash || char[32] || Hash of the transaction
|-
| ? || wallet_entry || CWalletTx || Same payload as checkorder
|}

=== reply ===

Generic reply for [[IP Transactions]]

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || reply || uint32_t || reply code
|}

Possible values:

{|class="wikitable"
! Value !! Name !! Description
|-
| 0 || SUCCESS || The IP Transaction can proceed (''checkorder''), or has been accepted (''submitorder'')
|-
| 1 || WALLET_ERROR || AcceptWalletTransaction() failed
|-
| 2 || DENIED || IP Transactions are not accepted by this node
|}

=== ping ===

The ''ping'' message is sent primarily to confirm that the TCP/IP connection is still valid. An error in transmission is presumed to be a closed connection and the address is removed as a current peer. In modern protocol versions, a ''pong'' response is generated using a nonce included in the ping.

=== filterload, filteradd, filterclear, merkleblock ===

These messages are related to Bloom filtering of connections and are defined in [[BIP 0037]].

=== alert ===

An '''alert''' is sent between nodes to send a general notification message throughout the network. If the alert can be confirmed with the signature as having come from the the core development group of the Bitcoin software, the message is suggested to be displayed for end-users. Attempts to perform transactions, particularly automated transactions through the client, are suggested to be halted. The text in the Message string should be relayed to log files and any user interfaces.

Alert format:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || payload || var_str || Serialized alert payload
|-
| ? || signature || var_str || An ECDSA signature of the message
|}

The developers of Satoshi's client use this public key for signing alerts:
04fc9702847840aaf195de8442ebecedf5b095cdbb9bc716bda9110971b28a49e0ead8564ff0db22209e0374782c093bb899692d524e9d6a6956e7c5ecbcd68284
(hash) 1AGRxqDa5WjUKBwHB9XYEjmkv1ucoUUy1s

The payload is serialized into a var_str to ensure that versions using incompatible alert formats can still relay alerts among one another. The current alert payload format is:
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || Version || int32_t || Alert format version
|-
| 8 || RelayUntil || int64_t || The timestamp beyond which nodes should stop relaying this alert
|-
| 8 || Expiration || int64_t || The timestamp beyond which this alert is no longer in effect and should be ignored
|-
| 4 || ID || int32_t || A unique ID number for this alert
|-
| 4 || Cancel || int32_t || All alerts with an ID number less than or equal to this number should be canceled: deleted and not accepted in the future
|-
| ? || setCancel || set<int> || All alert IDs contained in this set should be canceled as above
|-
| 4 || MinVer || int32_t || This alert only applies to versions greater than or equal to this version. Other versions should still relay it.
|-
| 4 || MaxVer || int32_t || This alert only applies to versions less than or equal to this version. Other versions should still relay it.
|-
| ? || setSubVer || set<string> || If this set contains any elements, then only nodes that have their subVer contained in this set are affected by the alert. Other versions should still relay it.
|-
| 4 || Priority || int32_t || Relative priority compared to other alerts
|-
| ? || Comment || string || A comment on the alert that is not displayed
|-
| ? || StatusBar || string || The alert message that is displayed to the user
|-
| ? || Reserved || string || Reserved
|}

Sample alert (no message header):
73010000003766404f00000000b305434f00000000f2030000f1030000001027000048ee0000
0064000000004653656520626974636f696e2e6f72672f666562323020696620796f75206861
76652074726f75626c6520636f6e6e656374696e672061667465722032302046656272756172
79004730450221008389df45f0703f39ec8c1cc42c13810ffcae14995bb648340219e353b63b
53eb022009ec65e1c1aaeec1fd334c6b684bde2b3f573060d5b70c3a46723326e4e8a4f1

Version: 1
RelayUntil: 1329620535
Expiration: 1329792435
ID: 1010
Cancel: 1009
setCancel: <empty>
MinVer: 10000
MaxVer: 61000
setSubVer: <empty>
Priority: 100
Comment: <empty>
StatusBar: "See bitcoin.org/feb20 if you have trouble connecting after 20 February"
Reserved: <empty>

== Scripting ==

See [[script]].

== Wireshark dissector ==
A dissector for wireshark is being developed at https://github.com/blueCommand/bitcoin-dissector

==See Also==

* [[Network]]
* [[Protocol rules]]
* [[Hardfork Wishlist]]

==References==
<references />

[[zh-cn:协议说明]]
[[Category:Technical]]
[[Category:Developer]]

List of address prefixes

2013-06-30T09:18:09Z

CodeShark:

Blockchain-based currencies use addresses, which are a [[Base58Check encoding]] of some hash, typically that of a public key. The encoding includes a version byte, which affects the first character in the address. The following is a list of some prefixes which are in use.

{| class="wikitable"
|-
!Initial byte(s)
!Leading symbol
!Use
!Example
|-
|0
|1
|Bitcoin pubkey hash
|<tt>12CPLrAUPvhVwjZqBgww3sLdEg4Z888R1j</tt>
|-
|5
|3
|Bitcoin script hash
|<tt>3EktnHQD7RiAE6uzMj2ZifT9YgRrkSgzQX</tt>
|-
|36
|F
|Friendly pubkey hash
|<tt>Ff361bCr7k8aFHjseFxaYWaSpjfq9hVswD</tt>
|-
|48
|L
|Litecoin pubkey hash
|<tt>LhK2kQwiaAvhjWY799cZvMyYwnQAcxkarr</tt>
|-
|52
|M or N
|Namecoin pubkey hash
|<tt>NATX6zEUNfxfvgVwz8qVnnw3hLhhYXhgQn</tt>
|-
|95
|f
|Fairbrix pubkey hash
|<tt>fF6o8LeDAfswEpMbCW8BqaqmzMWS7TGgew</tt>
|-
|97
|g
|GeistGeld pubkey hash
|<tt>gQ8YScyiMUTart6kUJpzhjPzAKfiYAwooc</tt>
|-
|105
|j
|i0coin pubkey hash
|<tt>jWmCr5cKeQjV4iyfUyipfLGwVML8MvXhF2</tt>
|-
|111
|m or n
|Bitcoin testnet pubkey hash
|<tt>mkJ7Bf5chdfw61d1m7gnDVAQV3EQQAb8iz</tt>
|-
|125
|s
|Solidcoin pubkey hash
|<tt>sXNaMoYBocjcQJRLK53dkaQ5mWuKfvHB9f</tt>
|-
|127
|t
|Tenebrix pubkey hash
|<tt>tUK2EQTMF6cN6vuNEfJtVf1BMqarvEZJBL</tt>
|-
|128
|5
|Bitcoin Private key (for uncompressed pubkey)
|<tt>5Htn3FzuH3b1X5VF2zLTsAQzBcyzkZNJsa2egXN8ZFJTCqQm3Rq</tt>
|-
|128
|K or L
|Bitcoin Private key (for compressed pubkey)
|<tt>L1aW4aubDFB7yfras2S1mN3bqg9nwySY8nkoLmJebSLD5BWv3ENZ</tt>
|-
|138
|x
|ixcoin pubkey hash
|<tt>xoKDFH4uWpyzxUcCC5jCLFujRKayv3HHcV</tt>
|-
|196
|2
|Testnet script hash
|
|-
|239
|9
|Testnet Private key (for uncompressed pubkey)
|<tt>91eWjgRmucdtYHpMdsHbn9h8UU8hdoMNSKj8p3QAj6VTLyBnjj6</tt>
|-
|239
|c
|Testnet Private key (for compressed pubkey)
|<tt>cNJFgo1driFnPcBdBX8BrJrpxchBWXwXCvNH5SoSkdcF6JXXwHMm</tt>
|
|-
|0x142, 0x143
|6P
|Encrypted private key ([[BIP 0038|BIP 38]])
|<tt> 6PRVWUbkzzsbcVac2qwfssoUJAN1Xhrg6bNk8J7Nzm5H7kxEbn2Nh2ZoGg </tt>
|}

Note that private keys for compressed and uncompressed bitcoin public keys use the same version byte. The reason for the compressed form starting with a different character is because a 0x01 byte is appended to the private key before base58 encoding.

The following table shows the leading symbol(s) and address length(s) for 160 bit hashes for each of the possible decimal version values:

{| class="wikitable"
|-
!Decimal version
!Leading symbol
!Address length
|-
|0
|1
|up to 34
|-
|1
|Q-Z, a-k, m-o
|33
|-
|2
|o-z, 2
|33 or 34
|-
|3
|2
|34
|-
|4
|2 or 3
|34
|-
|5-6
|3
|34
|-
|7
|3 or 4
|34
|-
|8
|4
|34
|-
|9
|4 or 5
|34
|-
|10-11
|5
|34
|-
|12
|5 or 6
|34
|-
|13
|6
|34
|-
|14
|6 or 7
|34
|-
|15-16
|7
|34
|-
|17
|7 or 8
|34
|-
|18
|8
|34
|-
|19
|8 or 9
|34
|-
|20-21
|9
|34
|-
|22
|9 or A
|34
|-
|23
|A
|34
|-
|24
|A or B
|34
|-
|25-26
|B
|34
|-
|27
|B or C
|34
|-
|28
|C
|34
|-
|29
|C or D
|34
|-
|30-31
|D
|34
|-
|32
|D or E
|34
|-
|33
|E
|34
|-
|34
|E or F
|34
|-
|35-36
|F
|34
|-
|37
|F or G
|34
|-
|38
|G
|34
|-
|39
|G or H
|34
|-
|40-41
|H
|34
|-
|42
|H or J
|34
|-
|43
|J
|34
|-
|44
|J or K
|34
|-
|45-46
|K
|34
|-
|47
|K or L
|34
|-
|48
|L
|34
|-
|49
|L or M
|34
|-
|50-51
|M
|34
|-
|52
|M or N
|34
|-
|53
|N
|34
|-
|54
|N or P
|34
|-
|55-56
|P
|34
|-
|57
|P or Q
|34
|-
|58
|Q
|34
|-
|59
|Q or R
|34
|-
|60-61
|R
|34
|-
|62
|R or S
|34
|-
|63
|S
|34
|-
|64
|S or T
|34
|-
|65-66
|T
|34
|-
|67
|T or U
|34
|-
|68
|U
|34
|-
|69
|U or V
|34
|-
|70-71
|V
|34
|-
|72
|V or W
|34
|-
|73
|W
|34
|-
|74
|W or X
|34
|-
|75-76
|X
|34
|-
|77
|X or Y
|34
|-
|78
|Y
|34
|-
|79
|Y or Z
|34
|-
|80-81
|Z
|34
|-
|82
|Z or a
|34
|-
|83
|a
|34
|-
|84
|a or b
|34
|-
|85
|b
|34
|-
|86
|b or c
|34
|-
|87-88
|c
|34
|-
|89
|c or d
|34
|-
|90
|d
|34
|-
|91
|d or e
|34
|-
|92-93
|e
|34
|-
|94
|e or f
|34
|-
|95
|f
|34
|-
|96
|f or g
|34
|-
|97-98
|g
|34
|-
|99
|g or h
|34
|-
|100
|h
|34
|-
|101
|h or i
|34
|-
|102-103
|i
|34
|-
|104
|i or j
|34
|-
|105
|j
|34
|-
|106
|j or k
|34
|-
|107-108
|k
|34
|-
|109
|k or m
|34
|-
|110
|m
|34
|-
|111
|m or n
|34
|-
|112-113
|n
|34
|-
|114
|n or o
|34
|-
|115
|o
|34
|-
|116
|o or p
|34
|-
|117-118
|p
|34
|-
|119
|p or q
|34
|-
|120
|q
|34
|-
|121
|q or r
|34
|-
|122-123
|r
|34
|-
|124
|r or s
|34
|-
|125
|s
|34
|-
|126
|s or t
|34
|-
|127-128
|t
|34
|-
|129
|t or u
|34
|-
|130
|u
|34
|-
|131
|u or v
|34
|-
|132-133
|v
|34
|-
|134
|v or w
|34
|-
|135
|w
|34
|-
|136
|w or x
|34
|-
|137-138
|x
|34
|-
|139
|x or y
|34
|-
|140
|y
|34
|-
|141
|y or z
|34
|-
|142-143
|z
|34
|-
|144
|z or 2
|34 or 35
|-
|145-255
|2
|35
|}

[[es:Lista de prefijos de direcciones]]

BIP 0032

2013-05-04T22:50:30Z

CodeShark: /* Conventions */

{{bip}}

<div style="color:red">
WARNING: please do not assume this specification is final.
</div>

RECENT CHANGES:
* [16 Apr 2013] Added private derivation for i >= 0x80000000 (less risk of parent private key leakage)
* [30 Apr 2013] Switched from multiplication by I_L to addition of I_L (faster, easier implementation)

<pre>
BIP: 32
Title: Hierarchical Deterministic Wallets
Author: Pieter Wuille
Status: Draft
Type: Informational
Created: 11-02-2012
</pre>

==Abstract==

This document describes hierarchical determinstic wallets (or "HD Wallets"): wallets which can be shared partially or entirely with different systems, each with or without the ability to spend coins.

The specification is intended to set a standard for deterministic wallets that can be interchanged between different clients. Although the wallets described here have many features, not all are required by supporting clients.

The specification consists of two parts. In a first part, a system for deriving a tree of keypairs from a single seed is presented. The second part demonstrates how to build a wallet structure on top of such a tree.

==Motivation==

The Bitcoin reference client uses randomly generated keys. In order to avoid the necessity for a backup after every transaction, (by default) 100 keys are cached in a pool of reserve keys. Still, these wallets are not intended to be shared and used on several systems simultaneously. They support hiding their private keys by using the wallet encrypt feature and not sharing the password, but such "neutered" wallets lose the power to generate public keys as well.

Deterministic wallets do not require such frequent backups, and elliptic curve mathematics permit schemes where one can calculate the public keys without revealing the private keys. This permits for example a webshop business to let its webserver generate a fresh addresses (public key hashes) for each order or for each customer, without giving the webserver access to the corresponding private keys (which are required for spending the received funds).

However, deterministic wallets typically consist of a single "chain" of keypairs. The fact that there is only one chain means that sharing a wallet happens on an all-or-nothing basis. However, in some cases one only wants some (public) keys to be shared and recoverable. In the example of a webshop, the webserver does not need access to all public keys of the merchant's wallet; only to those addresses which are used to receive customer's payments, and not for example the change addresses that are generated when the merchant spends money. Hierarchical deterministic wallets allow such selective sharing by supporting multiple keypair chains, derived from a single root.

==Specification: Key derivation==

===Conventions===

In the rest of this text we will assume the public key cryptography used in Bitcoin, namely elliptic curve cryptography using the field and curve parameters defined by secp256k1 (http://www.secg.org/index.php?action=secg,docs_secg). Variables below are either:
* integers modulo the order of the curve (referred to as n), serialized as 32 bytes, most significant byte first.
* coordinates of points on the curve, serialized as specified in SEC1 in compressed form: [0x02 or 0x03] + 32 byte x coordinate), where the header byte depends on the parity of the omitted y coordinate.
* byte sequences

We shall denote the compressed form of point P by χ(P), which for secp256k1 will always be 33 bytes long.

Addition (+) of two coordinates is defined as application of the EC group operation. Multiplication (*) of an integer and a coordinate is defined as repeated application of the EC group operation. The generator element of the curve is called G. The public key K corresponding to the private key k is calculated as k*G. We do not distinguish between numbers or coordinates and their serialization as byte sequences.

===Extended keys===

In what follows, we will define a function that derives a number of child keys from a parent key. In order to prevent these from depending solely on the key itself, we extend both private and public keys first with an extra 256 bits of entropy. This extension, called the chain code, is identical for corresponding private and public keys, and consists of 32 bytes.

We represent an extended private key as (k, c), with k the normal private key, and c the chain code. An extended public key is represented as (K, c), with K = k*G and c the chain code.

===Child key derivation functions===

We allow for two different types of derivation: private and public.
* Private derivation: knowledge of the private key kpar and cpar is required to compute both ki and Ki.
* Public derivation: knowledge of the public key Kpar and cpar suffices to compute Ki (but not ki).

We define the private and public child key derivation functions:
* CKD((kpar, cpar), i) → (ki, ci), defined for both private and public derivation.
* CKD'((Kpar, cpar), i) → (Ki, ci), defined only for public derivation.

We use the most significant bit of i to specify which type of derivation to use. i is encoded as a 32 bit unsigned integer, most significant byte first; '||' represents concatenation.

====Private child key derivation====

To define CKD((kpar, cpar), i) → (ki, ci):
* Check whether the highest bit (0x80000000) of i is set:
** If 1, private derivation is used: let I = HMAC-SHA512(Key = cpar, Data = 0x00 || kpar || i) [Note: The 0x00 pads the private key to make it 33 bytes long.]
** If 0, public derivation is used: let I = HMAC-SHA512(Key = cpar, Data = χ(kpar*G) || i)
* Split I = IL || IR into two 32-byte sequences, IL and IR.
* ki = IL + kpar (mod n).
* ci = IR.
In case IL ≥ n, the resulting key is invalid, and one should proceed with the next value for i.
[Note: this has probability lower than 1 in 2127.]

====Public child key derivation====

To define CKD'((Kpar, cpar), i) → (Ki, ci):
* Check whether the highest bit (0x80000000) of i is set:
** If 1, return error
** If 0, let I = HMAC-SHA512(Key = cpar, Data = χ(Kpar) || i)
* Split I = IL || IR into two 32-byte sequences, IL and IR.
* Ki = (IL + kpar)*G = IL*G + Kpar
* ci = IR.
In case IL ≥ n, the resulting key is invalid, and one should proceed with the next value for i.

Note that the extended public key corresponding to the evaluation of CKD(kext, i) with public derivation (so with i < 0x80000000) is identical to the evaluation of CKD'(Kext, i), with Kext the extended public key corresponding to kext. Symbolically, CKD((k, c), i)*G = CKD'((k*G, c), i). This implies that CKD' can be used to derive all public keys corresponding to the private keys that CKD would find. It cannot be used to retrieve the private keys, however.

The HMAC-SHA512 function is specified in [http://tools.ietf.org/html/rfc4231 RFC 4231].

===The key tree===

The next step is cascading several CKD constructions to build a tree. We start with one root, the master extended key m. By evaluating CKD(m,i) for several values of i, we get a number of first-degree derivative nodes. As each of these is again an extended key, CKD can be applied to those as well. To shorten notation, we will write CKD(CKD(CKD(m,0x8000003),0x2),0x5) as m/3'/2/5 now.

Each leaf node in the tree corresponds to an actual keypair, while the internal nodes correspond to the collection of keypairs that descends from them. The chain codes of the leaf nodes are ignored, and only their embedded private or public key is used. Because of this construction, knowing an extended private key allows reconstruction of all descendant private keys and public keys, and knowing an extended public keys allows reconstruction of all descendant public keys derived using public derivation.

===Key identifiers===

Extended keys can be identified by the Hash160 (RIPEMD160 after SHA256) of the serialized public key, ignoring the chain code. This corresponds exactly to the data used in traditional Bitcoin addresses. It is not advised to represent this data in base58 format though, as it may be interpreted as an address that way (and wallet software is not required to accept payment to the chain key itself).

The first 32 bits of the identifier are called the fingerprint.

===Serialization format===

Extended public and private keys are serialized as follows:
* 4 byte: version bytes (mainnet: 0x0488B21E public, 0x0488ADE4 private; testnet: 0x043587CF public, 0x04358394 private)
* 1 byte: depth: 0x00 for master nodes, 0x01 for level-1 descendants, ....
* 4 bytes: the fingerprint of the parent's key (0x00000000 if master key)
* 4 bytes: child number. This is the number i in xi = xpar/i, with xi the key being serialized. This is encoded in MSB order. (0x00000000 if master key)
* 32 bytes: the chain code
* 33 bytes: the public key or private key data (0x02 + X or 0x03 + X for public keys, 0x00 + k for private keys)

This 78 byte structure can be encoded like other Bitcoin data in Base58, by first adding 32 checksum bits (derived from the double SHA-256 checksum), and then converting to the Base58 representation. This results in a Base58-encoded string of up to 112 characters. Because of the choice of the version bytes, the Base58 representation will start with "xprv" or "xpub" on mainnet, "tprv" or "tpub" on testnet.

Note that the fingerprint of the parent only serves as a fast way to detect parent and child nodes in software, and software must be willing to deal with collisions. Internally, the full 160-bit identifier could be used.

When importing a serialized extended public key, implementations must verify whether the X coordinate in the public key data corresponds to a point on the curve. If not, the extended public key is invalid.

===Master key generation===

The total number of possible extended keypairs is almost 2^512, but the produced keys are only 256 bits long, and offer about half of that in terms of security. Therefore, master keys are not generated directly, but instead from a potentially short seed value.

* Generate a seed S of a chosen length (at least 128 bits, but 256 is advised) from a (P)RNG.
* Calculate I = HMAC-SHA512(key="Bitcoin seed", msg=S)
* Split I into two 32-byte sequences, IL and IR.
* Use IL (mod n) as master secret key, and IR as master chain code.
In case IL is 0 or >=n, the master key is invalid.

[[File:BIP32-derivation.png]]

==Specification: Wallet structure==

The previous sections specified key trees and their nodes. The next step is imposing a wallet structure on this tree. The layout defined in this section is a default only, though clients are encouraged to mimick it for compatibility, even if not all features are supported.

An HDW is organized as several 'accounts'. Accounts are numbered, the default account ("") being number 0. Clients are not required to support more than one account - if not, they only use the default account.

Each account is composed of two keypair chains: an internal and an external one. The external keychain is used to generate new public addresses, while the internal keychain is used for all other operations (change addresses, generation addresses, ..., anything that doesn't need to be communicated). Clients that do not support separate keychains for these should use the external one for everything.

* m/i'/0/k corresponds to the k'th keypair of the external chain of account number i of the HDW derived from master m.
* m/i'/1/k corresponds to the k'th keypair of the internal chain of account number i of the HDW derived from master m.

===Use cases===

====Full wallet sharing: m====

In cases where two systems need to access a single shared wallet, and both need to be able to perform spendings, one needs to share the master private extended key. Nodes can keep a pool of N look-ahead keys cached for external chains, to watch for incoming payments. The look-ahead for internal chains can be very small, as no gaps are to be expected here. An extra look-ahead could be active for the first unused account's chains - triggering the creation of a new account when used. Note that the name of the account will still need to be entered manually and cannot be synchronized via the block chain.

====Audits: M====

In case an auditor needs full access to the list of incoming and outgoing payments, one can share the master public extended key. This will allow the auditor to see all transactions from and to the wallet, in all accounts, but not a single secret key.

====Per-office balances: m/i'====

When a business has several independent offices, they can all use wallets derived from a single master. This will allow the headquarters to maintain a super-wallet that sees all incoming and outgoing transactions of all offices, and even permit moving money between the offices.

====Recurrent business-to-business transactions: M/i'/0====

In case two business partners often transfer money, one can use the extended public key for the external chain of a specific account (M/i'/0) as a sort of "super address", allowing frequent transactions that cannot (easily) be associated, but without needing to request a new address for each payment.
Such a mechanism could also be used by mining pool operators as variable payout address.

====Unsecure money receiver: M/i'/0====

When an unsecure webserver is used to run an e-commerce site, it needs to know public addresses that be used to receive payments. The webserver only needs to know the public extended key of the external chain of a single account. This means someone illegally obtaining access to the webserver can at most see all incoming payments, but will not (trivially) be able to distinguish outgoing transactions, nor see payments received by other webservers if there are several ones.

==Compatibility==

To comply with this standard, a client must at least be able to import an extended public or private key, to give access to its direct descendants as wallet keys. The wallet structure (master/account/chain/subchain) presented in the second part of the specification is advisory only, but is suggested as a minimal structure for easy compatibility - even when no separate accounts or distinction between internal and external chains is made. However, implementations may deviate from it for specific needs; more complex applications may call for a more complex tree structure.

==Security==

In addition to the expectations from the EC public-key cryptography itself:
* Given a public key K, an attacker cannot find the corresponding private key more efficiently than by solving the EC discrete logarithm problem (assumed to require 2128 group operations).
the intended security properties of this standard are:
* Given a child extended private key (ki,ci) and the integer i, an attacker cannot find the parent private key kpar more efficiently than a 2256 brute force of HMAC-SHA512.
* Given any number (2 <= N <= 232-1) of (index, extended private key) tuples (ij,(pj,cj)), with distinct ij's, determining whether they are derived from a common parent extended private key (i.e., whether there exists a (ppar,cpar) such that for each j in [0..N-1] CKD((ppar,cpar),ij)=(pj,cj)), cannot be done more efficiently than a 2256 brute force of HMAC-SHA512.
Note however that the following properties does not exist:
* Given a parent extended public key (Kpar,cpar) and a child public key (Ki), it is hard to find i.
* Given a parent extended public key (Kpar,cpar) and a child private key (ki) using public derivation, it is hard to find kpar.

Private and public keys must be kept safe as usual. Leaking a private key means access to coins - leaking a public key can mean loss of privacy.

Somewhat more care must be taken regarding extended keys, as these correspond to an entire (sub)tree of keys. One weakness that may not be immediately obvious, is that knowledge of the extended public key + a private key descending from it is equivalent to knowing the extended private key (i.e., every private and public key) in case public derivation is used. This means that extended public keys must be treated more carefully than regular public keys. This is the reason why accounts at the first level of the default wallet layout use private derivation, so a leak of account-specific (or below) private key never risks compromising the master.

We rely on resistance against (partial) preimages in HMAC-SHA512 to prevent IL in key derivation and master key generation from being zero.

==Test Vectors==

I'll publish test vectors as soon as the specification is assumed to be final.

==Acknowledgements==

* Gregory Maxwell for the original idea of type-2 deterministic wallets, and many discussions about it.
* Alan Reiner for the implementation of this scheme in Armory, and the suggestions that followed from that.
* Mike Caldwell for the version bytes to obtain human-recognizable Base58 strings.

BIP 0032

2013-05-04T22:48:57Z

CodeShark: /* Child key derivation functions */

{{bip}}

<div style="color:red">
WARNING: please do not assume this specification is final.
</div>

RECENT CHANGES:
* [16 Apr 2013] Added private derivation for i >= 0x80000000 (less risk of parent private key leakage)
* [30 Apr 2013] Switched from multiplication by I_L to addition of I_L (faster, easier implementation)

<pre>
BIP: 32
Title: Hierarchical Deterministic Wallets
Author: Pieter Wuille
Status: Draft
Type: Informational
Created: 11-02-2012
</pre>

==Abstract==

This document describes hierarchical determinstic wallets (or "HD Wallets"): wallets which can be shared partially or entirely with different systems, each with or without the ability to spend coins.

The specification is intended to set a standard for deterministic wallets that can be interchanged between different clients. Although the wallets described here have many features, not all are required by supporting clients.

The specification consists of two parts. In a first part, a system for deriving a tree of keypairs from a single seed is presented. The second part demonstrates how to build a wallet structure on top of such a tree.

==Motivation==

The Bitcoin reference client uses randomly generated keys. In order to avoid the necessity for a backup after every transaction, (by default) 100 keys are cached in a pool of reserve keys. Still, these wallets are not intended to be shared and used on several systems simultaneously. They support hiding their private keys by using the wallet encrypt feature and not sharing the password, but such "neutered" wallets lose the power to generate public keys as well.

Deterministic wallets do not require such frequent backups, and elliptic curve mathematics permit schemes where one can calculate the public keys without revealing the private keys. This permits for example a webshop business to let its webserver generate a fresh addresses (public key hashes) for each order or for each customer, without giving the webserver access to the corresponding private keys (which are required for spending the received funds).

However, deterministic wallets typically consist of a single "chain" of keypairs. The fact that there is only one chain means that sharing a wallet happens on an all-or-nothing basis. However, in some cases one only wants some (public) keys to be shared and recoverable. In the example of a webshop, the webserver does not need access to all public keys of the merchant's wallet; only to those addresses which are used to receive customer's payments, and not for example the change addresses that are generated when the merchant spends money. Hierarchical deterministic wallets allow such selective sharing by supporting multiple keypair chains, derived from a single root.

==Specification: Key derivation==

===Conventions===

In the rest of this text we will assume the public key cryptography used in Bitcoin, namely elliptic curve cryptography using the field and curve parameters defined by secp256k1 (http://www.secg.org/index.php?action=secg,docs_secg). Variables below are either:
* integers modulo the order of the curve (referred to as n), serialized as 32 bytes, most significant byte first.
* coordinates of points on the curve, serialized as specified in SEC1 in compressed form: [0x02 or 0x03] + 32 byte x coordinate), where the header byte depends on the parity of the omitted y coordinate.
* byte sequences

We shall represent the compressed form of point P by χ(P), which for secp256k1 will always be 33 bytes long.

Addition (+) of two coordinates is defined as application of the EC group operation. Multiplication (*) of an integer and a coordinate is defined as repeated application of the EC group operation. The generator element of the curve is called G. The public key K corresponding to the private key k is calculated as k*G. We do not distinguish between numbers or coordinates and their serialization as byte sequences.

===Extended keys===

In what follows, we will define a function that derives a number of child keys from a parent key. In order to prevent these from depending solely on the key itself, we extend both private and public keys first with an extra 256 bits of entropy. This extension, called the chain code, is identical for corresponding private and public keys, and consists of 32 bytes.

We represent an extended private key as (k, c), with k the normal private key, and c the chain code. An extended public key is represented as (K, c), with K = k*G and c the chain code.

===Child key derivation functions===

We allow for two different types of derivation: private and public.
* Private derivation: knowledge of the private key kpar and cpar is required to compute both ki and Ki.
* Public derivation: knowledge of the public key Kpar and cpar suffices to compute Ki (but not ki).

We define the private and public child key derivation functions:
* CKD((kpar, cpar), i) → (ki, ci), defined for both private and public derivation.
* CKD'((Kpar, cpar), i) → (Ki, ci), defined only for public derivation.

We use the most significant bit of i to specify which type of derivation to use. i is encoded as a 32 bit unsigned integer, most significant byte first; '||' represents concatenation.

====Private child key derivation====

To define CKD((kpar, cpar), i) → (ki, ci):
* Check whether the highest bit (0x80000000) of i is set:
** If 1, private derivation is used: let I = HMAC-SHA512(Key = cpar, Data = 0x00 || kpar || i) [Note: The 0x00 pads the private key to make it 33 bytes long.]
** If 0, public derivation is used: let I = HMAC-SHA512(Key = cpar, Data = χ(kpar*G) || i)
* Split I = IL || IR into two 32-byte sequences, IL and IR.
* ki = IL + kpar (mod n).
* ci = IR.
In case IL ≥ n, the resulting key is invalid, and one should proceed with the next value for i.
[Note: this has probability lower than 1 in 2127.]

====Public child key derivation====

To define CKD'((Kpar, cpar), i) → (Ki, ci):
* Check whether the highest bit (0x80000000) of i is set:
** If 1, return error
** If 0, let I = HMAC-SHA512(Key = cpar, Data = χ(Kpar) || i)
* Split I = IL || IR into two 32-byte sequences, IL and IR.
* Ki = (IL + kpar)*G = IL*G + Kpar
* ci = IR.
In case IL ≥ n, the resulting key is invalid, and one should proceed with the next value for i.

Note that the extended public key corresponding to the evaluation of CKD(kext, i) with public derivation (so with i < 0x80000000) is identical to the evaluation of CKD'(Kext, i), with Kext the extended public key corresponding to kext. Symbolically, CKD((k, c), i)*G = CKD'((k*G, c), i). This implies that CKD' can be used to derive all public keys corresponding to the private keys that CKD would find. It cannot be used to retrieve the private keys, however.

The HMAC-SHA512 function is specified in [http://tools.ietf.org/html/rfc4231 RFC 4231].

===The key tree===

The next step is cascading several CKD constructions to build a tree. We start with one root, the master extended key m. By evaluating CKD(m,i) for several values of i, we get a number of first-degree derivative nodes. As each of these is again an extended key, CKD can be applied to those as well. To shorten notation, we will write CKD(CKD(CKD(m,0x8000003),0x2),0x5) as m/3'/2/5 now.

Each leaf node in the tree corresponds to an actual keypair, while the internal nodes correspond to the collection of keypairs that descends from them. The chain codes of the leaf nodes are ignored, and only their embedded private or public key is used. Because of this construction, knowing an extended private key allows reconstruction of all descendant private keys and public keys, and knowing an extended public keys allows reconstruction of all descendant public keys derived using public derivation.

===Key identifiers===

Extended keys can be identified by the Hash160 (RIPEMD160 after SHA256) of the serialized public key, ignoring the chain code. This corresponds exactly to the data used in traditional Bitcoin addresses. It is not advised to represent this data in base58 format though, as it may be interpreted as an address that way (and wallet software is not required to accept payment to the chain key itself).

The first 32 bits of the identifier are called the fingerprint.

===Serialization format===

Extended public and private keys are serialized as follows:
* 4 byte: version bytes (mainnet: 0x0488B21E public, 0x0488ADE4 private; testnet: 0x043587CF public, 0x04358394 private)
* 1 byte: depth: 0x00 for master nodes, 0x01 for level-1 descendants, ....
* 4 bytes: the fingerprint of the parent's key (0x00000000 if master key)
* 4 bytes: child number. This is the number i in xi = xpar/i, with xi the key being serialized. This is encoded in MSB order. (0x00000000 if master key)
* 32 bytes: the chain code
* 33 bytes: the public key or private key data (0x02 + X or 0x03 + X for public keys, 0x00 + k for private keys)

This 78 byte structure can be encoded like other Bitcoin data in Base58, by first adding 32 checksum bits (derived from the double SHA-256 checksum), and then converting to the Base58 representation. This results in a Base58-encoded string of up to 112 characters. Because of the choice of the version bytes, the Base58 representation will start with "xprv" or "xpub" on mainnet, "tprv" or "tpub" on testnet.

Note that the fingerprint of the parent only serves as a fast way to detect parent and child nodes in software, and software must be willing to deal with collisions. Internally, the full 160-bit identifier could be used.

When importing a serialized extended public key, implementations must verify whether the X coordinate in the public key data corresponds to a point on the curve. If not, the extended public key is invalid.

===Master key generation===

The total number of possible extended keypairs is almost 2^512, but the produced keys are only 256 bits long, and offer about half of that in terms of security. Therefore, master keys are not generated directly, but instead from a potentially short seed value.

* Generate a seed S of a chosen length (at least 128 bits, but 256 is advised) from a (P)RNG.
* Calculate I = HMAC-SHA512(key="Bitcoin seed", msg=S)
* Split I into two 32-byte sequences, IL and IR.
* Use IL (mod n) as master secret key, and IR as master chain code.
In case IL is 0 or >=n, the master key is invalid.

[[File:BIP32-derivation.png]]

==Specification: Wallet structure==

The previous sections specified key trees and their nodes. The next step is imposing a wallet structure on this tree. The layout defined in this section is a default only, though clients are encouraged to mimick it for compatibility, even if not all features are supported.

An HDW is organized as several 'accounts'. Accounts are numbered, the default account ("") being number 0. Clients are not required to support more than one account - if not, they only use the default account.

Each account is composed of two keypair chains: an internal and an external one. The external keychain is used to generate new public addresses, while the internal keychain is used for all other operations (change addresses, generation addresses, ..., anything that doesn't need to be communicated). Clients that do not support separate keychains for these should use the external one for everything.

* m/i'/0/k corresponds to the k'th keypair of the external chain of account number i of the HDW derived from master m.
* m/i'/1/k corresponds to the k'th keypair of the internal chain of account number i of the HDW derived from master m.

===Use cases===

====Full wallet sharing: m====

In cases where two systems need to access a single shared wallet, and both need to be able to perform spendings, one needs to share the master private extended key. Nodes can keep a pool of N look-ahead keys cached for external chains, to watch for incoming payments. The look-ahead for internal chains can be very small, as no gaps are to be expected here. An extra look-ahead could be active for the first unused account's chains - triggering the creation of a new account when used. Note that the name of the account will still need to be entered manually and cannot be synchronized via the block chain.

====Audits: M====

In case an auditor needs full access to the list of incoming and outgoing payments, one can share the master public extended key. This will allow the auditor to see all transactions from and to the wallet, in all accounts, but not a single secret key.

====Per-office balances: m/i'====

When a business has several independent offices, they can all use wallets derived from a single master. This will allow the headquarters to maintain a super-wallet that sees all incoming and outgoing transactions of all offices, and even permit moving money between the offices.

====Recurrent business-to-business transactions: M/i'/0====

In case two business partners often transfer money, one can use the extended public key for the external chain of a specific account (M/i'/0) as a sort of "super address", allowing frequent transactions that cannot (easily) be associated, but without needing to request a new address for each payment.
Such a mechanism could also be used by mining pool operators as variable payout address.

====Unsecure money receiver: M/i'/0====

When an unsecure webserver is used to run an e-commerce site, it needs to know public addresses that be used to receive payments. The webserver only needs to know the public extended key of the external chain of a single account. This means someone illegally obtaining access to the webserver can at most see all incoming payments, but will not (trivially) be able to distinguish outgoing transactions, nor see payments received by other webservers if there are several ones.

==Compatibility==

To comply with this standard, a client must at least be able to import an extended public or private key, to give access to its direct descendants as wallet keys. The wallet structure (master/account/chain/subchain) presented in the second part of the specification is advisory only, but is suggested as a minimal structure for easy compatibility - even when no separate accounts or distinction between internal and external chains is made. However, implementations may deviate from it for specific needs; more complex applications may call for a more complex tree structure.

==Security==

In addition to the expectations from the EC public-key cryptography itself:
* Given a public key K, an attacker cannot find the corresponding private key more efficiently than by solving the EC discrete logarithm problem (assumed to require 2128 group operations).
the intended security properties of this standard are:
* Given a child extended private key (ki,ci) and the integer i, an attacker cannot find the parent private key kpar more efficiently than a 2256 brute force of HMAC-SHA512.
* Given any number (2 <= N <= 232-1) of (index, extended private key) tuples (ij,(pj,cj)), with distinct ij's, determining whether they are derived from a common parent extended private key (i.e., whether there exists a (ppar,cpar) such that for each j in [0..N-1] CKD((ppar,cpar),ij)=(pj,cj)), cannot be done more efficiently than a 2256 brute force of HMAC-SHA512.
Note however that the following properties does not exist:
* Given a parent extended public key (Kpar,cpar) and a child public key (Ki), it is hard to find i.
* Given a parent extended public key (Kpar,cpar) and a child private key (ki) using public derivation, it is hard to find kpar.

Private and public keys must be kept safe as usual. Leaking a private key means access to coins - leaking a public key can mean loss of privacy.

Somewhat more care must be taken regarding extended keys, as these correspond to an entire (sub)tree of keys. One weakness that may not be immediately obvious, is that knowledge of the extended public key + a private key descending from it is equivalent to knowing the extended private key (i.e., every private and public key) in case public derivation is used. This means that extended public keys must be treated more carefully than regular public keys. This is the reason why accounts at the first level of the default wallet layout use private derivation, so a leak of account-specific (or below) private key never risks compromising the master.

We rely on resistance against (partial) preimages in HMAC-SHA512 to prevent IL in key derivation and master key generation from being zero.

==Test Vectors==

I'll publish test vectors as soon as the specification is assumed to be final.

==Acknowledgements==

* Gregory Maxwell for the original idea of type-2 deterministic wallets, and many discussions about it.
* Alan Reiner for the implementation of this scheme in Armory, and the suggestions that followed from that.
* Mike Caldwell for the version bytes to obtain human-recognizable Base58 strings.

BIP 0032

2013-05-04T22:45:16Z

CodeShark: /* Child key derivation functions */

{{bip}}

<div style="color:red">
WARNING: please do not assume this specification is final.
</div>

RECENT CHANGES:
* [16 Apr 2013] Added private derivation for i >= 0x80000000 (less risk of parent private key leakage)
* [30 Apr 2013] Switched from multiplication by I_L to addition of I_L (faster, easier implementation)

<pre>
BIP: 32
Title: Hierarchical Deterministic Wallets
Author: Pieter Wuille
Status: Draft
Type: Informational
Created: 11-02-2012
</pre>

==Abstract==

This document describes hierarchical determinstic wallets (or "HD Wallets"): wallets which can be shared partially or entirely with different systems, each with or without the ability to spend coins.

The specification is intended to set a standard for deterministic wallets that can be interchanged between different clients. Although the wallets described here have many features, not all are required by supporting clients.

The specification consists of two parts. In a first part, a system for deriving a tree of keypairs from a single seed is presented. The second part demonstrates how to build a wallet structure on top of such a tree.

==Motivation==

The Bitcoin reference client uses randomly generated keys. In order to avoid the necessity for a backup after every transaction, (by default) 100 keys are cached in a pool of reserve keys. Still, these wallets are not intended to be shared and used on several systems simultaneously. They support hiding their private keys by using the wallet encrypt feature and not sharing the password, but such "neutered" wallets lose the power to generate public keys as well.

Deterministic wallets do not require such frequent backups, and elliptic curve mathematics permit schemes where one can calculate the public keys without revealing the private keys. This permits for example a webshop business to let its webserver generate a fresh addresses (public key hashes) for each order or for each customer, without giving the webserver access to the corresponding private keys (which are required for spending the received funds).

However, deterministic wallets typically consist of a single "chain" of keypairs. The fact that there is only one chain means that sharing a wallet happens on an all-or-nothing basis. However, in some cases one only wants some (public) keys to be shared and recoverable. In the example of a webshop, the webserver does not need access to all public keys of the merchant's wallet; only to those addresses which are used to receive customer's payments, and not for example the change addresses that are generated when the merchant spends money. Hierarchical deterministic wallets allow such selective sharing by supporting multiple keypair chains, derived from a single root.

==Specification: Key derivation==

===Conventions===

In the rest of this text we will assume the public key cryptography used in Bitcoin, namely elliptic curve cryptography using the field and curve parameters defined by secp256k1 (http://www.secg.org/index.php?action=secg,docs_secg). Variables below are either:
* integers modulo the order of the curve (referred to as n), serialized as 32 bytes, most significant byte first.
* coordinates of points on the curve, serialized as specified in SEC1 in compressed form: [0x02 or 0x03] + 32 byte x coordinate), where the header byte depends on the parity of the omitted y coordinate.
* byte sequences

We shall represent the compressed form of point P by χ(P), which for secp256k1 will always be 33 bytes long.

Addition (+) of two coordinates is defined as application of the EC group operation. Multiplication (*) of an integer and a coordinate is defined as repeated application of the EC group operation. The generator element of the curve is called G. The public key K corresponding to the private key k is calculated as k*G. We do not distinguish between numbers or coordinates and their serialization as byte sequences.

===Extended keys===

In what follows, we will define a function that derives a number of child keys from a parent key. In order to prevent these from depending solely on the key itself, we extend both private and public keys first with an extra 256 bits of entropy. This extension, called the chain code, is identical for corresponding private and public keys, and consists of 32 bytes.

We represent an extended private key as (k, c), with k the normal private key, and c the chain code. An extended public key is represented as (K, c), with K = k*G and c the chain code.

===Child key derivation functions===

We allow for two different types of derivation: public and private.
* Private derivation: knowledge of the private key kpar and cpar is required to compute both ki and Ki.
* Public derivation: knowledge of the public key Kpar and cpar suffices to compute Ki (but not ki).

We define the private and public child key derivation functions:
* CKD((kpar, cpar), i) → (ki, ci), defined for both private and public derivation.
* CKD'((Kpar, cpar), i) → (Ki, ci), defined only for public derivation.

We use the most significant bit of i to specify which type of derivation to use. i is encoded as a 32 bit unsigned integer, most significant byte first; '||' represents concatenation.

====Private child key derivation====

To define CKD((kpar, cpar), i) → (ki, ci):
* Check whether the highest bit (0x80000000) of i is set:
** If 1, private derivation is used: let I = HMAC-SHA512(Key = cpar, Data = 0x00 || kpar || i) [Note: The 0x00 pads the private key to make it 33 bytes long.]
** If 0, public derivation is used: let I = HMAC-SHA512(Key = cpar, Data = χ(kpar*G) || i)
* Split I = IL || IR into two 32-byte sequences, IL and IR.
* ki = IL + kpar (mod n).
* ci = IR.
In case IL ≥ n, the resulting key is invalid, and one should proceed with the next value for i.
[Note: this has probability lower than 1 in 2127.]

====Public child key derivation====

To define CKD'((Kpar, cpar), i) → (Ki, ci):
* Check whether the highest bit (0x80000000) of i is set:
** If 1, return error
** If 0, let I = HMAC-SHA512(Key = cpar, Data = χ(Kpar) || i)
* Split I = IL || IR into two 32-byte sequences, IL and IR.
* Ki = (IL + kpar)*G = IL*G + Kpar
* ci = IR.
In case IL ≥ n, the resulting key is invalid, and one should proceed with the next value for i.

Note that the extended public key corresponding to the evaluation of CKD(kext, i) with public derivation (so with i < 0x80000000) is identical to the evaluation of CKD'(Kext, i), with Kext the extended public key corresponding to kext. Symbolically, CKD((k, c), i)*G = CKD'((k*G, c), i). This implies that CKD' can be used to derive all public keys corresponding to the private keys that CKD would find. It cannot be used to retrieve the private keys, however.

The HMAC-SHA512 function is specified in [http://tools.ietf.org/html/rfc4231 RFC 4231].

===The key tree===

The next step is cascading several CKD constructions to build a tree. We start with one root, the master extended key m. By evaluating CKD(m,i) for several values of i, we get a number of first-degree derivative nodes. As each of these is again an extended key, CKD can be applied to those as well. To shorten notation, we will write CKD(CKD(CKD(m,0x8000003),0x2),0x5) as m/3'/2/5 now.

Each leaf node in the tree corresponds to an actual keypair, while the internal nodes correspond to the collection of keypairs that descends from them. The chain codes of the leaf nodes are ignored, and only their embedded private or public key is used. Because of this construction, knowing an extended private key allows reconstruction of all descendant private keys and public keys, and knowing an extended public keys allows reconstruction of all descendant public keys derived using public derivation.

===Key identifiers===

Extended keys can be identified by the Hash160 (RIPEMD160 after SHA256) of the serialized public key, ignoring the chain code. This corresponds exactly to the data used in traditional Bitcoin addresses. It is not advised to represent this data in base58 format though, as it may be interpreted as an address that way (and wallet software is not required to accept payment to the chain key itself).

The first 32 bits of the identifier are called the fingerprint.

===Serialization format===

Extended public and private keys are serialized as follows:
* 4 byte: version bytes (mainnet: 0x0488B21E public, 0x0488ADE4 private; testnet: 0x043587CF public, 0x04358394 private)
* 1 byte: depth: 0x00 for master nodes, 0x01 for level-1 descendants, ....
* 4 bytes: the fingerprint of the parent's key (0x00000000 if master key)
* 4 bytes: child number. This is the number i in xi = xpar/i, with xi the key being serialized. This is encoded in MSB order. (0x00000000 if master key)
* 32 bytes: the chain code
* 33 bytes: the public key or private key data (0x02 + X or 0x03 + X for public keys, 0x00 + k for private keys)

This 78 byte structure can be encoded like other Bitcoin data in Base58, by first adding 32 checksum bits (derived from the double SHA-256 checksum), and then converting to the Base58 representation. This results in a Base58-encoded string of up to 112 characters. Because of the choice of the version bytes, the Base58 representation will start with "xprv" or "xpub" on mainnet, "tprv" or "tpub" on testnet.

Note that the fingerprint of the parent only serves as a fast way to detect parent and child nodes in software, and software must be willing to deal with collisions. Internally, the full 160-bit identifier could be used.

When importing a serialized extended public key, implementations must verify whether the X coordinate in the public key data corresponds to a point on the curve. If not, the extended public key is invalid.

===Master key generation===

The total number of possible extended keypairs is almost 2^512, but the produced keys are only 256 bits long, and offer about half of that in terms of security. Therefore, master keys are not generated directly, but instead from a potentially short seed value.

* Generate a seed S of a chosen length (at least 128 bits, but 256 is advised) from a (P)RNG.
* Calculate I = HMAC-SHA512(key="Bitcoin seed", msg=S)
* Split I into two 32-byte sequences, IL and IR.
* Use IL (mod n) as master secret key, and IR as master chain code.
In case IL is 0 or >=n, the master key is invalid.

[[File:BIP32-derivation.png]]

==Specification: Wallet structure==

The previous sections specified key trees and their nodes. The next step is imposing a wallet structure on this tree. The layout defined in this section is a default only, though clients are encouraged to mimick it for compatibility, even if not all features are supported.

An HDW is organized as several 'accounts'. Accounts are numbered, the default account ("") being number 0. Clients are not required to support more than one account - if not, they only use the default account.

Each account is composed of two keypair chains: an internal and an external one. The external keychain is used to generate new public addresses, while the internal keychain is used for all other operations (change addresses, generation addresses, ..., anything that doesn't need to be communicated). Clients that do not support separate keychains for these should use the external one for everything.

* m/i'/0/k corresponds to the k'th keypair of the external chain of account number i of the HDW derived from master m.
* m/i'/1/k corresponds to the k'th keypair of the internal chain of account number i of the HDW derived from master m.

===Use cases===

====Full wallet sharing: m====

In cases where two systems need to access a single shared wallet, and both need to be able to perform spendings, one needs to share the master private extended key. Nodes can keep a pool of N look-ahead keys cached for external chains, to watch for incoming payments. The look-ahead for internal chains can be very small, as no gaps are to be expected here. An extra look-ahead could be active for the first unused account's chains - triggering the creation of a new account when used. Note that the name of the account will still need to be entered manually and cannot be synchronized via the block chain.

====Audits: M====

In case an auditor needs full access to the list of incoming and outgoing payments, one can share the master public extended key. This will allow the auditor to see all transactions from and to the wallet, in all accounts, but not a single secret key.

====Per-office balances: m/i'====

When a business has several independent offices, they can all use wallets derived from a single master. This will allow the headquarters to maintain a super-wallet that sees all incoming and outgoing transactions of all offices, and even permit moving money between the offices.

====Recurrent business-to-business transactions: M/i'/0====

In case two business partners often transfer money, one can use the extended public key for the external chain of a specific account (M/i'/0) as a sort of "super address", allowing frequent transactions that cannot (easily) be associated, but without needing to request a new address for each payment.
Such a mechanism could also be used by mining pool operators as variable payout address.

====Unsecure money receiver: M/i'/0====

When an unsecure webserver is used to run an e-commerce site, it needs to know public addresses that be used to receive payments. The webserver only needs to know the public extended key of the external chain of a single account. This means someone illegally obtaining access to the webserver can at most see all incoming payments, but will not (trivially) be able to distinguish outgoing transactions, nor see payments received by other webservers if there are several ones.

==Compatibility==

To comply with this standard, a client must at least be able to import an extended public or private key, to give access to its direct descendants as wallet keys. The wallet structure (master/account/chain/subchain) presented in the second part of the specification is advisory only, but is suggested as a minimal structure for easy compatibility - even when no separate accounts or distinction between internal and external chains is made. However, implementations may deviate from it for specific needs; more complex applications may call for a more complex tree structure.

==Security==

In addition to the expectations from the EC public-key cryptography itself:
* Given a public key K, an attacker cannot find the corresponding private key more efficiently than by solving the EC discrete logarithm problem (assumed to require 2128 group operations).
the intended security properties of this standard are:
* Given a child extended private key (ki,ci) and the integer i, an attacker cannot find the parent private key kpar more efficiently than a 2256 brute force of HMAC-SHA512.
* Given any number (2 <= N <= 232-1) of (index, extended private key) tuples (ij,(pj,cj)), with distinct ij's, determining whether they are derived from a common parent extended private key (i.e., whether there exists a (ppar,cpar) such that for each j in [0..N-1] CKD((ppar,cpar),ij)=(pj,cj)), cannot be done more efficiently than a 2256 brute force of HMAC-SHA512.
Note however that the following properties does not exist:
* Given a parent extended public key (Kpar,cpar) and a child public key (Ki), it is hard to find i.
* Given a parent extended public key (Kpar,cpar) and a child private key (ki) using public derivation, it is hard to find kpar.

Private and public keys must be kept safe as usual. Leaking a private key means access to coins - leaking a public key can mean loss of privacy.

Somewhat more care must be taken regarding extended keys, as these correspond to an entire (sub)tree of keys. One weakness that may not be immediately obvious, is that knowledge of the extended public key + a private key descending from it is equivalent to knowing the extended private key (i.e., every private and public key) in case public derivation is used. This means that extended public keys must be treated more carefully than regular public keys. This is the reason why accounts at the first level of the default wallet layout use private derivation, so a leak of account-specific (or below) private key never risks compromising the master.

We rely on resistance against (partial) preimages in HMAC-SHA512 to prevent IL in key derivation and master key generation from being zero.

==Test Vectors==

I'll publish test vectors as soon as the specification is assumed to be final.

==Acknowledgements==

* Gregory Maxwell for the original idea of type-2 deterministic wallets, and many discussions about it.
* Alan Reiner for the implementation of this scheme in Armory, and the suggestions that followed from that.
* Mike Caldwell for the version bytes to obtain human-recognizable Base58 strings.

BIP 0032

2013-05-04T22:44:38Z

CodeShark: /* Extended keys */

{{bip}}

<div style="color:red">
WARNING: please do not assume this specification is final.
</div>

RECENT CHANGES:
* [16 Apr 2013] Added private derivation for i >= 0x80000000 (less risk of parent private key leakage)
* [30 Apr 2013] Switched from multiplication by I_L to addition of I_L (faster, easier implementation)

<pre>
BIP: 32
Title: Hierarchical Deterministic Wallets
Author: Pieter Wuille
Status: Draft
Type: Informational
Created: 11-02-2012
</pre>

==Abstract==

This document describes hierarchical determinstic wallets (or "HD Wallets"): wallets which can be shared partially or entirely with different systems, each with or without the ability to spend coins.

The specification is intended to set a standard for deterministic wallets that can be interchanged between different clients. Although the wallets described here have many features, not all are required by supporting clients.

The specification consists of two parts. In a first part, a system for deriving a tree of keypairs from a single seed is presented. The second part demonstrates how to build a wallet structure on top of such a tree.

==Motivation==

The Bitcoin reference client uses randomly generated keys. In order to avoid the necessity for a backup after every transaction, (by default) 100 keys are cached in a pool of reserve keys. Still, these wallets are not intended to be shared and used on several systems simultaneously. They support hiding their private keys by using the wallet encrypt feature and not sharing the password, but such "neutered" wallets lose the power to generate public keys as well.

Deterministic wallets do not require such frequent backups, and elliptic curve mathematics permit schemes where one can calculate the public keys without revealing the private keys. This permits for example a webshop business to let its webserver generate a fresh addresses (public key hashes) for each order or for each customer, without giving the webserver access to the corresponding private keys (which are required for spending the received funds).

However, deterministic wallets typically consist of a single "chain" of keypairs. The fact that there is only one chain means that sharing a wallet happens on an all-or-nothing basis. However, in some cases one only wants some (public) keys to be shared and recoverable. In the example of a webshop, the webserver does not need access to all public keys of the merchant's wallet; only to those addresses which are used to receive customer's payments, and not for example the change addresses that are generated when the merchant spends money. Hierarchical deterministic wallets allow such selective sharing by supporting multiple keypair chains, derived from a single root.

==Specification: Key derivation==

===Conventions===

In the rest of this text we will assume the public key cryptography used in Bitcoin, namely elliptic curve cryptography using the field and curve parameters defined by secp256k1 (http://www.secg.org/index.php?action=secg,docs_secg). Variables below are either:
* integers modulo the order of the curve (referred to as n), serialized as 32 bytes, most significant byte first.
* coordinates of points on the curve, serialized as specified in SEC1 in compressed form: [0x02 or 0x03] + 32 byte x coordinate), where the header byte depends on the parity of the omitted y coordinate.
* byte sequences

We shall represent the compressed form of point P by χ(P), which for secp256k1 will always be 33 bytes long.

Addition (+) of two coordinates is defined as application of the EC group operation. Multiplication (*) of an integer and a coordinate is defined as repeated application of the EC group operation. The generator element of the curve is called G. The public key K corresponding to the private key k is calculated as k*G. We do not distinguish between numbers or coordinates and their serialization as byte sequences.

===Extended keys===

In what follows, we will define a function that derives a number of child keys from a parent key. In order to prevent these from depending solely on the key itself, we extend both private and public keys first with an extra 256 bits of entropy. This extension, called the chain code, is identical for corresponding private and public keys, and consists of 32 bytes.

We represent an extended private key as (k, c), with k the normal private key, and c the chain code. An extended public key is represented as (K, c), with K = k*G and c the chain code.

===Child key derivation functions===

We allow for two different types of derivation: public and private.
* Private derivation: knowledge of the private key kpar and cpar is required to compute both ki and Ki.
* Public derivation: knowledge of the public key Kpar and cpar suffices to compute Ki (but not ki).

We define the private and public child key derivation functions:
* CKD((kpar,cpar),i) → (ki,ci), defined for both private and public derivation.
* CKD'((Kpar,cpar),i) → (Ki,ci), defined only for public derivation.

We use the most significant bit of i to specify which type of derivation to use. i is encoded as a 32 bit unsigned integer, most significant byte first; '||' represents concatenation.

====Private child key derivation====

To define CKD((kpar, cpar), i) → (ki, ci):
* Check whether the highest bit (0x80000000) of i is set:
** If 1, private derivation is used: let I = HMAC-SHA512(Key = cpar, Data = 0x00 || kpar || i) [Note: The 0x00 pads the private key to make it 33 bytes long.]
** If 0, public derivation is used: let I = HMAC-SHA512(Key = cpar, Data = χ(kpar*G) || i)
* Split I = IL || IR into two 32-byte sequences, IL and IR.
* ki = IL + kpar (mod n).
* ci = IR.
In case IL ≥ n, the resulting key is invalid, and one should proceed with the next value for i.
[Note: this has probability lower than 1 in 2127.]

====Public child key derivation====

To define CKD'((Kpar, cpar), i) → (Ki, ci):
* Check whether the highest bit (0x80000000) of i is set:
** If 1, return error
** If 0, let I = HMAC-SHA512(Key = cpar, Data = χ(Kpar) || i)
* Split I = IL || IR into two 32-byte sequences, IL and IR.
* Ki = (IL + kpar)*G = IL*G + Kpar
* ci = IR.
In case IL ≥ n, the resulting key is invalid, and one should proceed with the next value for i.

Note that the extended public key corresponding to the evaluation of CKD(kext, i) with public derivation (so with i < 0x80000000) is identical to the evaluation of CKD'(Kext, i), with Kext the extended public key corresponding to kext. Symbolically, CKD((k, c), i)*G = CKD'((k*G, c), i). This implies that CKD' can be used to derive all public keys corresponding to the private keys that CKD would find. It cannot be used to retrieve the private keys, however.

The HMAC-SHA512 function is specified in [http://tools.ietf.org/html/rfc4231 RFC 4231].

===The key tree===

The next step is cascading several CKD constructions to build a tree. We start with one root, the master extended key m. By evaluating CKD(m,i) for several values of i, we get a number of first-degree derivative nodes. As each of these is again an extended key, CKD can be applied to those as well. To shorten notation, we will write CKD(CKD(CKD(m,0x8000003),0x2),0x5) as m/3'/2/5 now.

Each leaf node in the tree corresponds to an actual keypair, while the internal nodes correspond to the collection of keypairs that descends from them. The chain codes of the leaf nodes are ignored, and only their embedded private or public key is used. Because of this construction, knowing an extended private key allows reconstruction of all descendant private keys and public keys, and knowing an extended public keys allows reconstruction of all descendant public keys derived using public derivation.

===Key identifiers===

Extended keys can be identified by the Hash160 (RIPEMD160 after SHA256) of the serialized public key, ignoring the chain code. This corresponds exactly to the data used in traditional Bitcoin addresses. It is not advised to represent this data in base58 format though, as it may be interpreted as an address that way (and wallet software is not required to accept payment to the chain key itself).

The first 32 bits of the identifier are called the fingerprint.

===Serialization format===

Extended public and private keys are serialized as follows:
* 4 byte: version bytes (mainnet: 0x0488B21E public, 0x0488ADE4 private; testnet: 0x043587CF public, 0x04358394 private)
* 1 byte: depth: 0x00 for master nodes, 0x01 for level-1 descendants, ....
* 4 bytes: the fingerprint of the parent's key (0x00000000 if master key)
* 4 bytes: child number. This is the number i in xi = xpar/i, with xi the key being serialized. This is encoded in MSB order. (0x00000000 if master key)
* 32 bytes: the chain code
* 33 bytes: the public key or private key data (0x02 + X or 0x03 + X for public keys, 0x00 + k for private keys)

This 78 byte structure can be encoded like other Bitcoin data in Base58, by first adding 32 checksum bits (derived from the double SHA-256 checksum), and then converting to the Base58 representation. This results in a Base58-encoded string of up to 112 characters. Because of the choice of the version bytes, the Base58 representation will start with "xprv" or "xpub" on mainnet, "tprv" or "tpub" on testnet.

Note that the fingerprint of the parent only serves as a fast way to detect parent and child nodes in software, and software must be willing to deal with collisions. Internally, the full 160-bit identifier could be used.

When importing a serialized extended public key, implementations must verify whether the X coordinate in the public key data corresponds to a point on the curve. If not, the extended public key is invalid.

===Master key generation===

The total number of possible extended keypairs is almost 2^512, but the produced keys are only 256 bits long, and offer about half of that in terms of security. Therefore, master keys are not generated directly, but instead from a potentially short seed value.

* Generate a seed S of a chosen length (at least 128 bits, but 256 is advised) from a (P)RNG.
* Calculate I = HMAC-SHA512(key="Bitcoin seed", msg=S)
* Split I into two 32-byte sequences, IL and IR.
* Use IL (mod n) as master secret key, and IR as master chain code.
In case IL is 0 or >=n, the master key is invalid.

[[File:BIP32-derivation.png]]

==Specification: Wallet structure==

The previous sections specified key trees and their nodes. The next step is imposing a wallet structure on this tree. The layout defined in this section is a default only, though clients are encouraged to mimick it for compatibility, even if not all features are supported.

An HDW is organized as several 'accounts'. Accounts are numbered, the default account ("") being number 0. Clients are not required to support more than one account - if not, they only use the default account.

Each account is composed of two keypair chains: an internal and an external one. The external keychain is used to generate new public addresses, while the internal keychain is used for all other operations (change addresses, generation addresses, ..., anything that doesn't need to be communicated). Clients that do not support separate keychains for these should use the external one for everything.

* m/i'/0/k corresponds to the k'th keypair of the external chain of account number i of the HDW derived from master m.
* m/i'/1/k corresponds to the k'th keypair of the internal chain of account number i of the HDW derived from master m.

===Use cases===

====Full wallet sharing: m====

In cases where two systems need to access a single shared wallet, and both need to be able to perform spendings, one needs to share the master private extended key. Nodes can keep a pool of N look-ahead keys cached for external chains, to watch for incoming payments. The look-ahead for internal chains can be very small, as no gaps are to be expected here. An extra look-ahead could be active for the first unused account's chains - triggering the creation of a new account when used. Note that the name of the account will still need to be entered manually and cannot be synchronized via the block chain.

====Audits: M====

In case an auditor needs full access to the list of incoming and outgoing payments, one can share the master public extended key. This will allow the auditor to see all transactions from and to the wallet, in all accounts, but not a single secret key.

====Per-office balances: m/i'====

When a business has several independent offices, they can all use wallets derived from a single master. This will allow the headquarters to maintain a super-wallet that sees all incoming and outgoing transactions of all offices, and even permit moving money between the offices.

====Recurrent business-to-business transactions: M/i'/0====

In case two business partners often transfer money, one can use the extended public key for the external chain of a specific account (M/i'/0) as a sort of "super address", allowing frequent transactions that cannot (easily) be associated, but without needing to request a new address for each payment.
Such a mechanism could also be used by mining pool operators as variable payout address.

====Unsecure money receiver: M/i'/0====

When an unsecure webserver is used to run an e-commerce site, it needs to know public addresses that be used to receive payments. The webserver only needs to know the public extended key of the external chain of a single account. This means someone illegally obtaining access to the webserver can at most see all incoming payments, but will not (trivially) be able to distinguish outgoing transactions, nor see payments received by other webservers if there are several ones.

==Compatibility==

To comply with this standard, a client must at least be able to import an extended public or private key, to give access to its direct descendants as wallet keys. The wallet structure (master/account/chain/subchain) presented in the second part of the specification is advisory only, but is suggested as a minimal structure for easy compatibility - even when no separate accounts or distinction between internal and external chains is made. However, implementations may deviate from it for specific needs; more complex applications may call for a more complex tree structure.

==Security==

In addition to the expectations from the EC public-key cryptography itself:
* Given a public key K, an attacker cannot find the corresponding private key more efficiently than by solving the EC discrete logarithm problem (assumed to require 2128 group operations).
the intended security properties of this standard are:
* Given a child extended private key (ki,ci) and the integer i, an attacker cannot find the parent private key kpar more efficiently than a 2256 brute force of HMAC-SHA512.
* Given any number (2 <= N <= 232-1) of (index, extended private key) tuples (ij,(pj,cj)), with distinct ij's, determining whether they are derived from a common parent extended private key (i.e., whether there exists a (ppar,cpar) such that for each j in [0..N-1] CKD((ppar,cpar),ij)=(pj,cj)), cannot be done more efficiently than a 2256 brute force of HMAC-SHA512.
Note however that the following properties does not exist:
* Given a parent extended public key (Kpar,cpar) and a child public key (Ki), it is hard to find i.
* Given a parent extended public key (Kpar,cpar) and a child private key (ki) using public derivation, it is hard to find kpar.

Private and public keys must be kept safe as usual. Leaking a private key means access to coins - leaking a public key can mean loss of privacy.

Somewhat more care must be taken regarding extended keys, as these correspond to an entire (sub)tree of keys. One weakness that may not be immediately obvious, is that knowledge of the extended public key + a private key descending from it is equivalent to knowing the extended private key (i.e., every private and public key) in case public derivation is used. This means that extended public keys must be treated more carefully than regular public keys. This is the reason why accounts at the first level of the default wallet layout use private derivation, so a leak of account-specific (or below) private key never risks compromising the master.

We rely on resistance against (partial) preimages in HMAC-SHA512 to prevent IL in key derivation and master key generation from being zero.

==Test Vectors==

I'll publish test vectors as soon as the specification is assumed to be final.

==Acknowledgements==

* Gregory Maxwell for the original idea of type-2 deterministic wallets, and many discussions about it.
* Alan Reiner for the implementation of this scheme in Armory, and the suggestions that followed from that.
* Mike Caldwell for the version bytes to obtain human-recognizable Base58 strings.

BIP 0032

2013-05-04T22:41:15Z

CodeShark: /* Private child key derivation */

{{bip}}

<div style="color:red">
WARNING: please do not assume this specification is final.
</div>

RECENT CHANGES:
* [16 Apr 2013] Added private derivation for i >= 0x80000000 (less risk of parent private key leakage)
* [30 Apr 2013] Switched from multiplication by I_L to addition of I_L (faster, easier implementation)

<pre>
BIP: 32
Title: Hierarchical Deterministic Wallets
Author: Pieter Wuille
Status: Draft
Type: Informational
Created: 11-02-2012
</pre>

==Abstract==

This document describes hierarchical determinstic wallets (or "HD Wallets"): wallets which can be shared partially or entirely with different systems, each with or without the ability to spend coins.

The specification is intended to set a standard for deterministic wallets that can be interchanged between different clients. Although the wallets described here have many features, not all are required by supporting clients.

The specification consists of two parts. In a first part, a system for deriving a tree of keypairs from a single seed is presented. The second part demonstrates how to build a wallet structure on top of such a tree.

==Motivation==

The Bitcoin reference client uses randomly generated keys. In order to avoid the necessity for a backup after every transaction, (by default) 100 keys are cached in a pool of reserve keys. Still, these wallets are not intended to be shared and used on several systems simultaneously. They support hiding their private keys by using the wallet encrypt feature and not sharing the password, but such "neutered" wallets lose the power to generate public keys as well.

Deterministic wallets do not require such frequent backups, and elliptic curve mathematics permit schemes where one can calculate the public keys without revealing the private keys. This permits for example a webshop business to let its webserver generate a fresh addresses (public key hashes) for each order or for each customer, without giving the webserver access to the corresponding private keys (which are required for spending the received funds).

However, deterministic wallets typically consist of a single "chain" of keypairs. The fact that there is only one chain means that sharing a wallet happens on an all-or-nothing basis. However, in some cases one only wants some (public) keys to be shared and recoverable. In the example of a webshop, the webserver does not need access to all public keys of the merchant's wallet; only to those addresses which are used to receive customer's payments, and not for example the change addresses that are generated when the merchant spends money. Hierarchical deterministic wallets allow such selective sharing by supporting multiple keypair chains, derived from a single root.

==Specification: Key derivation==

===Conventions===

In the rest of this text we will assume the public key cryptography used in Bitcoin, namely elliptic curve cryptography using the field and curve parameters defined by secp256k1 (http://www.secg.org/index.php?action=secg,docs_secg). Variables below are either:
* integers modulo the order of the curve (referred to as n), serialized as 32 bytes, most significant byte first.
* coordinates of points on the curve, serialized as specified in SEC1 in compressed form: [0x02 or 0x03] + 32 byte x coordinate), where the header byte depends on the parity of the omitted y coordinate.
* byte sequences

We shall represent the compressed form of point P by χ(P), which for secp256k1 will always be 33 bytes long.

Addition (+) of two coordinates is defined as application of the EC group operation. Multiplication (*) of an integer and a coordinate is defined as repeated application of the EC group operation. The generator element of the curve is called G. The public key K corresponding to the private key k is calculated as k*G. We do not distinguish between numbers or coordinates and their serialization as byte sequences.

===Extended keys===

In what follows, we will define a function that derives a number of child keys from a parent key. In order to prevent these from depending solely on the key itself, we extend both private and public keys first with an extra 256 bits of entropy. This extension, called the chain code, is identical for corresponding private and public keys, and consists of 32 bytes.

We represent an extended private key as (k,c), with k the normal private key, and c the chain code. An extended public key is represented as (K,c), with K = k*G and c the chain code.

===Child key derivation functions===

We allow for two different types of derivation: public and private.
* Private derivation: knowledge of the private key kpar and cpar is required to compute both ki and Ki.
* Public derivation: knowledge of the public key Kpar and cpar suffices to compute Ki (but not ki).

We define the private and public child key derivation functions:
* CKD((kpar,cpar),i) → (ki,ci), defined for both private and public derivation.
* CKD'((Kpar,cpar),i) → (Ki,ci), defined only for public derivation.

We use the most significant bit of i to specify which type of derivation to use. i is encoded as a 32 bit unsigned integer, most significant byte first; '||' represents concatenation.

====Private child key derivation====

To define CKD((kpar, cpar), i) → (ki, ci):
* Check whether the highest bit (0x80000000) of i is set:
** If 1, private derivation is used: let I = HMAC-SHA512(Key = cpar, Data = 0x00 || kpar || i) [Note: The 0x00 pads the private key to make it 33 bytes long.]
** If 0, public derivation is used: let I = HMAC-SHA512(Key = cpar, Data = χ(kpar*G) || i)
* Split I = IL || IR into two 32-byte sequences, IL and IR.
* ki = IL + kpar (mod n).
* ci = IR.
In case IL ≥ n, the resulting key is invalid, and one should proceed with the next value for i.
[Note: this has probability lower than 1 in 2127.]

====Public child key derivation====

To define CKD'((Kpar, cpar), i) → (Ki, ci):
* Check whether the highest bit (0x80000000) of i is set:
** If 1, return error
** If 0, let I = HMAC-SHA512(Key = cpar, Data = χ(Kpar) || i)
* Split I = IL || IR into two 32-byte sequences, IL and IR.
* Ki = (IL + kpar)*G = IL*G + Kpar
* ci = IR.
In case IL ≥ n, the resulting key is invalid, and one should proceed with the next value for i.

Note that the extended public key corresponding to the evaluation of CKD(kext, i) with public derivation (so with i < 0x80000000) is identical to the evaluation of CKD'(Kext, i), with Kext the extended public key corresponding to kext. Symbolically, CKD((k, c), i)*G = CKD'((k*G, c), i). This implies that CKD' can be used to derive all public keys corresponding to the private keys that CKD would find. It cannot be used to retrieve the private keys, however.

The HMAC-SHA512 function is specified in [http://tools.ietf.org/html/rfc4231 RFC 4231].

===The key tree===

The next step is cascading several CKD constructions to build a tree. We start with one root, the master extended key m. By evaluating CKD(m,i) for several values of i, we get a number of first-degree derivative nodes. As each of these is again an extended key, CKD can be applied to those as well. To shorten notation, we will write CKD(CKD(CKD(m,0x8000003),0x2),0x5) as m/3'/2/5 now.

Each leaf node in the tree corresponds to an actual keypair, while the internal nodes correspond to the collection of keypairs that descends from them. The chain codes of the leaf nodes are ignored, and only their embedded private or public key is used. Because of this construction, knowing an extended private key allows reconstruction of all descendant private keys and public keys, and knowing an extended public keys allows reconstruction of all descendant public keys derived using public derivation.

===Key identifiers===

Extended keys can be identified by the Hash160 (RIPEMD160 after SHA256) of the serialized public key, ignoring the chain code. This corresponds exactly to the data used in traditional Bitcoin addresses. It is not advised to represent this data in base58 format though, as it may be interpreted as an address that way (and wallet software is not required to accept payment to the chain key itself).

The first 32 bits of the identifier are called the fingerprint.

===Serialization format===

Extended public and private keys are serialized as follows:
* 4 byte: version bytes (mainnet: 0x0488B21E public, 0x0488ADE4 private; testnet: 0x043587CF public, 0x04358394 private)
* 1 byte: depth: 0x00 for master nodes, 0x01 for level-1 descendants, ....
* 4 bytes: the fingerprint of the parent's key (0x00000000 if master key)
* 4 bytes: child number. This is the number i in xi = xpar/i, with xi the key being serialized. This is encoded in MSB order. (0x00000000 if master key)
* 32 bytes: the chain code
* 33 bytes: the public key or private key data (0x02 + X or 0x03 + X for public keys, 0x00 + k for private keys)

This 78 byte structure can be encoded like other Bitcoin data in Base58, by first adding 32 checksum bits (derived from the double SHA-256 checksum), and then converting to the Base58 representation. This results in a Base58-encoded string of up to 112 characters. Because of the choice of the version bytes, the Base58 representation will start with "xprv" or "xpub" on mainnet, "tprv" or "tpub" on testnet.

Note that the fingerprint of the parent only serves as a fast way to detect parent and child nodes in software, and software must be willing to deal with collisions. Internally, the full 160-bit identifier could be used.

When importing a serialized extended public key, implementations must verify whether the X coordinate in the public key data corresponds to a point on the curve. If not, the extended public key is invalid.

===Master key generation===

The total number of possible extended keypairs is almost 2^512, but the produced keys are only 256 bits long, and offer about half of that in terms of security. Therefore, master keys are not generated directly, but instead from a potentially short seed value.

* Generate a seed S of a chosen length (at least 128 bits, but 256 is advised) from a (P)RNG.
* Calculate I = HMAC-SHA512(key="Bitcoin seed", msg=S)
* Split I into two 32-byte sequences, IL and IR.
* Use IL (mod n) as master secret key, and IR as master chain code.
In case IL is 0 or >=n, the master key is invalid.

[[File:BIP32-derivation.png]]

==Specification: Wallet structure==

The previous sections specified key trees and their nodes. The next step is imposing a wallet structure on this tree. The layout defined in this section is a default only, though clients are encouraged to mimick it for compatibility, even if not all features are supported.

An HDW is organized as several 'accounts'. Accounts are numbered, the default account ("") being number 0. Clients are not required to support more than one account - if not, they only use the default account.

Each account is composed of two keypair chains: an internal and an external one. The external keychain is used to generate new public addresses, while the internal keychain is used for all other operations (change addresses, generation addresses, ..., anything that doesn't need to be communicated). Clients that do not support separate keychains for these should use the external one for everything.

* m/i'/0/k corresponds to the k'th keypair of the external chain of account number i of the HDW derived from master m.
* m/i'/1/k corresponds to the k'th keypair of the internal chain of account number i of the HDW derived from master m.

===Use cases===

====Full wallet sharing: m====

In cases where two systems need to access a single shared wallet, and both need to be able to perform spendings, one needs to share the master private extended key. Nodes can keep a pool of N look-ahead keys cached for external chains, to watch for incoming payments. The look-ahead for internal chains can be very small, as no gaps are to be expected here. An extra look-ahead could be active for the first unused account's chains - triggering the creation of a new account when used. Note that the name of the account will still need to be entered manually and cannot be synchronized via the block chain.

====Audits: M====

In case an auditor needs full access to the list of incoming and outgoing payments, one can share the master public extended key. This will allow the auditor to see all transactions from and to the wallet, in all accounts, but not a single secret key.

====Per-office balances: m/i'====

When a business has several independent offices, they can all use wallets derived from a single master. This will allow the headquarters to maintain a super-wallet that sees all incoming and outgoing transactions of all offices, and even permit moving money between the offices.

====Recurrent business-to-business transactions: M/i'/0====

In case two business partners often transfer money, one can use the extended public key for the external chain of a specific account (M/i'/0) as a sort of "super address", allowing frequent transactions that cannot (easily) be associated, but without needing to request a new address for each payment.
Such a mechanism could also be used by mining pool operators as variable payout address.

====Unsecure money receiver: M/i'/0====

When an unsecure webserver is used to run an e-commerce site, it needs to know public addresses that be used to receive payments. The webserver only needs to know the public extended key of the external chain of a single account. This means someone illegally obtaining access to the webserver can at most see all incoming payments, but will not (trivially) be able to distinguish outgoing transactions, nor see payments received by other webservers if there are several ones.

==Compatibility==

To comply with this standard, a client must at least be able to import an extended public or private key, to give access to its direct descendants as wallet keys. The wallet structure (master/account/chain/subchain) presented in the second part of the specification is advisory only, but is suggested as a minimal structure for easy compatibility - even when no separate accounts or distinction between internal and external chains is made. However, implementations may deviate from it for specific needs; more complex applications may call for a more complex tree structure.

==Security==

In addition to the expectations from the EC public-key cryptography itself:
* Given a public key K, an attacker cannot find the corresponding private key more efficiently than by solving the EC discrete logarithm problem (assumed to require 2128 group operations).
the intended security properties of this standard are:
* Given a child extended private key (ki,ci) and the integer i, an attacker cannot find the parent private key kpar more efficiently than a 2256 brute force of HMAC-SHA512.
* Given any number (2 <= N <= 232-1) of (index, extended private key) tuples (ij,(pj,cj)), with distinct ij's, determining whether they are derived from a common parent extended private key (i.e., whether there exists a (ppar,cpar) such that for each j in [0..N-1] CKD((ppar,cpar),ij)=(pj,cj)), cannot be done more efficiently than a 2256 brute force of HMAC-SHA512.
Note however that the following properties does not exist:
* Given a parent extended public key (Kpar,cpar) and a child public key (Ki), it is hard to find i.
* Given a parent extended public key (Kpar,cpar) and a child private key (ki) using public derivation, it is hard to find kpar.

Private and public keys must be kept safe as usual. Leaking a private key means access to coins - leaking a public key can mean loss of privacy.

Somewhat more care must be taken regarding extended keys, as these correspond to an entire (sub)tree of keys. One weakness that may not be immediately obvious, is that knowledge of the extended public key + a private key descending from it is equivalent to knowing the extended private key (i.e., every private and public key) in case public derivation is used. This means that extended public keys must be treated more carefully than regular public keys. This is the reason why accounts at the first level of the default wallet layout use private derivation, so a leak of account-specific (or below) private key never risks compromising the master.

We rely on resistance against (partial) preimages in HMAC-SHA512 to prevent IL in key derivation and master key generation from being zero.

==Test Vectors==

I'll publish test vectors as soon as the specification is assumed to be final.

==Acknowledgements==

* Gregory Maxwell for the original idea of type-2 deterministic wallets, and many discussions about it.
* Alan Reiner for the implementation of this scheme in Armory, and the suggestions that followed from that.
* Mike Caldwell for the version bytes to obtain human-recognizable Base58 strings.

BIP 0032

2013-05-04T22:38:58Z

CodeShark: /* Public child key derivation */

{{bip}}

<div style="color:red">
WARNING: please do not assume this specification is final.
</div>

RECENT CHANGES:
* [16 Apr 2013] Added private derivation for i >= 0x80000000 (less risk of parent private key leakage)
* [30 Apr 2013] Switched from multiplication by I_L to addition of I_L (faster, easier implementation)

<pre>
BIP: 32
Title: Hierarchical Deterministic Wallets
Author: Pieter Wuille
Status: Draft
Type: Informational
Created: 11-02-2012
</pre>

==Abstract==

This document describes hierarchical determinstic wallets (or "HD Wallets"): wallets which can be shared partially or entirely with different systems, each with or without the ability to spend coins.

The specification is intended to set a standard for deterministic wallets that can be interchanged between different clients. Although the wallets described here have many features, not all are required by supporting clients.

The specification consists of two parts. In a first part, a system for deriving a tree of keypairs from a single seed is presented. The second part demonstrates how to build a wallet structure on top of such a tree.

==Motivation==

The Bitcoin reference client uses randomly generated keys. In order to avoid the necessity for a backup after every transaction, (by default) 100 keys are cached in a pool of reserve keys. Still, these wallets are not intended to be shared and used on several systems simultaneously. They support hiding their private keys by using the wallet encrypt feature and not sharing the password, but such "neutered" wallets lose the power to generate public keys as well.

Deterministic wallets do not require such frequent backups, and elliptic curve mathematics permit schemes where one can calculate the public keys without revealing the private keys. This permits for example a webshop business to let its webserver generate a fresh addresses (public key hashes) for each order or for each customer, without giving the webserver access to the corresponding private keys (which are required for spending the received funds).

However, deterministic wallets typically consist of a single "chain" of keypairs. The fact that there is only one chain means that sharing a wallet happens on an all-or-nothing basis. However, in some cases one only wants some (public) keys to be shared and recoverable. In the example of a webshop, the webserver does not need access to all public keys of the merchant's wallet; only to those addresses which are used to receive customer's payments, and not for example the change addresses that are generated when the merchant spends money. Hierarchical deterministic wallets allow such selective sharing by supporting multiple keypair chains, derived from a single root.

==Specification: Key derivation==

===Conventions===

In the rest of this text we will assume the public key cryptography used in Bitcoin, namely elliptic curve cryptography using the field and curve parameters defined by secp256k1 (http://www.secg.org/index.php?action=secg,docs_secg). Variables below are either:
* integers modulo the order of the curve (referred to as n), serialized as 32 bytes, most significant byte first.
* coordinates of points on the curve, serialized as specified in SEC1 in compressed form: [0x02 or 0x03] + 32 byte x coordinate), where the header byte depends on the parity of the omitted y coordinate.
* byte sequences

We shall represent the compressed form of point P by χ(P), which for secp256k1 will always be 33 bytes long.

Addition (+) of two coordinates is defined as application of the EC group operation. Multiplication (*) of an integer and a coordinate is defined as repeated application of the EC group operation. The generator element of the curve is called G. The public key K corresponding to the private key k is calculated as k*G. We do not distinguish between numbers or coordinates and their serialization as byte sequences.

===Extended keys===

In what follows, we will define a function that derives a number of child keys from a parent key. In order to prevent these from depending solely on the key itself, we extend both private and public keys first with an extra 256 bits of entropy. This extension, called the chain code, is identical for corresponding private and public keys, and consists of 32 bytes.

We represent an extended private key as (k,c), with k the normal private key, and c the chain code. An extended public key is represented as (K,c), with K = k*G and c the chain code.

===Child key derivation functions===

We allow for two different types of derivation: public and private.
* Private derivation: knowledge of the private key kpar and cpar is required to compute both ki and Ki.
* Public derivation: knowledge of the public key Kpar and cpar suffices to compute Ki (but not ki).

We define the private and public child key derivation functions:
* CKD((kpar,cpar),i) → (ki,ci), defined for both private and public derivation.
* CKD'((Kpar,cpar),i) → (Ki,ci), defined only for public derivation.

We use the most significant bit of i to specify which type of derivation to use. i is encoded as a 32 bit unsigned integer, most significant byte first; '||' represents concatenation.

====Private child key derivation====

To define CKD((kpar,cpar),i) → (ki,ci):
* Check whether the highest bit (0x80000000) of i is set:
** If 1, private derivation is used: let I = HMAC-SHA512(Key = cpar, Data = 0x00 || kpar || i) [Note: The 0x00 pads the private key to make it 33 bytes long.]
** If 0, public derivation is used: let I = HMAC-SHA512(Key = cpar, Data = χ(kpar*G) || i)
* Split I into two 32-byte sequences, IL and IR.
* ki = IL + kpar (mod n).
* ci = IR.
In case IL ≥ n, the resulting key is invalid, and one should proceed with the next value for i (note that this has a chance lower than 1 in 2127).

====Public child key derivation====

To define CKD'((Kpar, cpar), i) → (Ki, ci):
* Check whether the highest bit (0x80000000) of i is set:
** If 1, return error
** If 0, let I = HMAC-SHA512(Key = cpar, Data = χ(Kpar) || i)
* Split I = IL || IR into two 32-byte sequences, IL and IR.
* Ki = (IL + kpar)*G = IL*G + Kpar
* ci = IR.
In case IL ≥ n, the resulting key is invalid, and one should proceed with the next value for i.

Note that the extended public key corresponding to the evaluation of CKD(kext, i) with public derivation (so with i < 0x80000000) is identical to the evaluation of CKD'(Kext, i), with Kext the extended public key corresponding to kext. Symbolically, CKD((k, c), i)*G = CKD'((k*G, c), i). This implies that CKD' can be used to derive all public keys corresponding to the private keys that CKD would find. It cannot be used to retrieve the private keys, however.

The HMAC-SHA512 function is specified in [http://tools.ietf.org/html/rfc4231 RFC 4231].

===The key tree===

The next step is cascading several CKD constructions to build a tree. We start with one root, the master extended key m. By evaluating CKD(m,i) for several values of i, we get a number of first-degree derivative nodes. As each of these is again an extended key, CKD can be applied to those as well. To shorten notation, we will write CKD(CKD(CKD(m,0x8000003),0x2),0x5) as m/3'/2/5 now.

Each leaf node in the tree corresponds to an actual keypair, while the internal nodes correspond to the collection of keypairs that descends from them. The chain codes of the leaf nodes are ignored, and only their embedded private or public key is used. Because of this construction, knowing an extended private key allows reconstruction of all descendant private keys and public keys, and knowing an extended public keys allows reconstruction of all descendant public keys derived using public derivation.

===Key identifiers===

Extended keys can be identified by the Hash160 (RIPEMD160 after SHA256) of the serialized public key, ignoring the chain code. This corresponds exactly to the data used in traditional Bitcoin addresses. It is not advised to represent this data in base58 format though, as it may be interpreted as an address that way (and wallet software is not required to accept payment to the chain key itself).

The first 32 bits of the identifier are called the fingerprint.

===Serialization format===

Extended public and private keys are serialized as follows:
* 4 byte: version bytes (mainnet: 0x0488B21E public, 0x0488ADE4 private; testnet: 0x043587CF public, 0x04358394 private)
* 1 byte: depth: 0x00 for master nodes, 0x01 for level-1 descendants, ....
* 4 bytes: the fingerprint of the parent's key (0x00000000 if master key)
* 4 bytes: child number. This is the number i in xi = xpar/i, with xi the key being serialized. This is encoded in MSB order. (0x00000000 if master key)
* 32 bytes: the chain code
* 33 bytes: the public key or private key data (0x02 + X or 0x03 + X for public keys, 0x00 + k for private keys)

This 78 byte structure can be encoded like other Bitcoin data in Base58, by first adding 32 checksum bits (derived from the double SHA-256 checksum), and then converting to the Base58 representation. This results in a Base58-encoded string of up to 112 characters. Because of the choice of the version bytes, the Base58 representation will start with "xprv" or "xpub" on mainnet, "tprv" or "tpub" on testnet.

Note that the fingerprint of the parent only serves as a fast way to detect parent and child nodes in software, and software must be willing to deal with collisions. Internally, the full 160-bit identifier could be used.

When importing a serialized extended public key, implementations must verify whether the X coordinate in the public key data corresponds to a point on the curve. If not, the extended public key is invalid.

===Master key generation===

The total number of possible extended keypairs is almost 2^512, but the produced keys are only 256 bits long, and offer about half of that in terms of security. Therefore, master keys are not generated directly, but instead from a potentially short seed value.

* Generate a seed S of a chosen length (at least 128 bits, but 256 is advised) from a (P)RNG.
* Calculate I = HMAC-SHA512(key="Bitcoin seed", msg=S)
* Split I into two 32-byte sequences, IL and IR.
* Use IL (mod n) as master secret key, and IR as master chain code.
In case IL is 0 or >=n, the master key is invalid.

[[File:BIP32-derivation.png]]

==Specification: Wallet structure==

The previous sections specified key trees and their nodes. The next step is imposing a wallet structure on this tree. The layout defined in this section is a default only, though clients are encouraged to mimick it for compatibility, even if not all features are supported.

An HDW is organized as several 'accounts'. Accounts are numbered, the default account ("") being number 0. Clients are not required to support more than one account - if not, they only use the default account.

Each account is composed of two keypair chains: an internal and an external one. The external keychain is used to generate new public addresses, while the internal keychain is used for all other operations (change addresses, generation addresses, ..., anything that doesn't need to be communicated). Clients that do not support separate keychains for these should use the external one for everything.

* m/i'/0/k corresponds to the k'th keypair of the external chain of account number i of the HDW derived from master m.
* m/i'/1/k corresponds to the k'th keypair of the internal chain of account number i of the HDW derived from master m.

===Use cases===

====Full wallet sharing: m====

In cases where two systems need to access a single shared wallet, and both need to be able to perform spendings, one needs to share the master private extended key. Nodes can keep a pool of N look-ahead keys cached for external chains, to watch for incoming payments. The look-ahead for internal chains can be very small, as no gaps are to be expected here. An extra look-ahead could be active for the first unused account's chains - triggering the creation of a new account when used. Note that the name of the account will still need to be entered manually and cannot be synchronized via the block chain.

====Audits: M====

In case an auditor needs full access to the list of incoming and outgoing payments, one can share the master public extended key. This will allow the auditor to see all transactions from and to the wallet, in all accounts, but not a single secret key.

====Per-office balances: m/i'====

When a business has several independent offices, they can all use wallets derived from a single master. This will allow the headquarters to maintain a super-wallet that sees all incoming and outgoing transactions of all offices, and even permit moving money between the offices.

====Recurrent business-to-business transactions: M/i'/0====

In case two business partners often transfer money, one can use the extended public key for the external chain of a specific account (M/i'/0) as a sort of "super address", allowing frequent transactions that cannot (easily) be associated, but without needing to request a new address for each payment.
Such a mechanism could also be used by mining pool operators as variable payout address.

====Unsecure money receiver: M/i'/0====

When an unsecure webserver is used to run an e-commerce site, it needs to know public addresses that be used to receive payments. The webserver only needs to know the public extended key of the external chain of a single account. This means someone illegally obtaining access to the webserver can at most see all incoming payments, but will not (trivially) be able to distinguish outgoing transactions, nor see payments received by other webservers if there are several ones.

==Compatibility==

To comply with this standard, a client must at least be able to import an extended public or private key, to give access to its direct descendants as wallet keys. The wallet structure (master/account/chain/subchain) presented in the second part of the specification is advisory only, but is suggested as a minimal structure for easy compatibility - even when no separate accounts or distinction between internal and external chains is made. However, implementations may deviate from it for specific needs; more complex applications may call for a more complex tree structure.

==Security==

In addition to the expectations from the EC public-key cryptography itself:
* Given a public key K, an attacker cannot find the corresponding private key more efficiently than by solving the EC discrete logarithm problem (assumed to require 2128 group operations).
the intended security properties of this standard are:
* Given a child extended private key (ki,ci) and the integer i, an attacker cannot find the parent private key kpar more efficiently than a 2256 brute force of HMAC-SHA512.
* Given any number (2 <= N <= 232-1) of (index, extended private key) tuples (ij,(pj,cj)), with distinct ij's, determining whether they are derived from a common parent extended private key (i.e., whether there exists a (ppar,cpar) such that for each j in [0..N-1] CKD((ppar,cpar),ij)=(pj,cj)), cannot be done more efficiently than a 2256 brute force of HMAC-SHA512.
Note however that the following properties does not exist:
* Given a parent extended public key (Kpar,cpar) and a child public key (Ki), it is hard to find i.
* Given a parent extended public key (Kpar,cpar) and a child private key (ki) using public derivation, it is hard to find kpar.

Private and public keys must be kept safe as usual. Leaking a private key means access to coins - leaking a public key can mean loss of privacy.

Somewhat more care must be taken regarding extended keys, as these correspond to an entire (sub)tree of keys. One weakness that may not be immediately obvious, is that knowledge of the extended public key + a private key descending from it is equivalent to knowing the extended private key (i.e., every private and public key) in case public derivation is used. This means that extended public keys must be treated more carefully than regular public keys. This is the reason why accounts at the first level of the default wallet layout use private derivation, so a leak of account-specific (or below) private key never risks compromising the master.

We rely on resistance against (partial) preimages in HMAC-SHA512 to prevent IL in key derivation and master key generation from being zero.

==Test Vectors==

I'll publish test vectors as soon as the specification is assumed to be final.

==Acknowledgements==

* Gregory Maxwell for the original idea of type-2 deterministic wallets, and many discussions about it.
* Alan Reiner for the implementation of this scheme in Armory, and the suggestions that followed from that.
* Mike Caldwell for the version bytes to obtain human-recognizable Base58 strings.

BIP 0032

2013-05-04T22:33:53Z

CodeShark: /* Private child key derivation */

{{bip}}

<div style="color:red">
WARNING: please do not assume this specification is final.
</div>

RECENT CHANGES:
* [16 Apr 2013] Added private derivation for i >= 0x80000000 (less risk of parent private key leakage)
* [30 Apr 2013] Switched from multiplication by I_L to addition of I_L (faster, easier implementation)

<pre>
BIP: 32
Title: Hierarchical Deterministic Wallets
Author: Pieter Wuille
Status: Draft
Type: Informational
Created: 11-02-2012
</pre>

==Abstract==

This document describes hierarchical determinstic wallets (or "HD Wallets"): wallets which can be shared partially or entirely with different systems, each with or without the ability to spend coins.

The specification is intended to set a standard for deterministic wallets that can be interchanged between different clients. Although the wallets described here have many features, not all are required by supporting clients.

The specification consists of two parts. In a first part, a system for deriving a tree of keypairs from a single seed is presented. The second part demonstrates how to build a wallet structure on top of such a tree.

==Motivation==

The Bitcoin reference client uses randomly generated keys. In order to avoid the necessity for a backup after every transaction, (by default) 100 keys are cached in a pool of reserve keys. Still, these wallets are not intended to be shared and used on several systems simultaneously. They support hiding their private keys by using the wallet encrypt feature and not sharing the password, but such "neutered" wallets lose the power to generate public keys as well.

Deterministic wallets do not require such frequent backups, and elliptic curve mathematics permit schemes where one can calculate the public keys without revealing the private keys. This permits for example a webshop business to let its webserver generate a fresh addresses (public key hashes) for each order or for each customer, without giving the webserver access to the corresponding private keys (which are required for spending the received funds).

However, deterministic wallets typically consist of a single "chain" of keypairs. The fact that there is only one chain means that sharing a wallet happens on an all-or-nothing basis. However, in some cases one only wants some (public) keys to be shared and recoverable. In the example of a webshop, the webserver does not need access to all public keys of the merchant's wallet; only to those addresses which are used to receive customer's payments, and not for example the change addresses that are generated when the merchant spends money. Hierarchical deterministic wallets allow such selective sharing by supporting multiple keypair chains, derived from a single root.

==Specification: Key derivation==

===Conventions===

In the rest of this text we will assume the public key cryptography used in Bitcoin, namely elliptic curve cryptography using the field and curve parameters defined by secp256k1 (http://www.secg.org/index.php?action=secg,docs_secg). Variables below are either:
* integers modulo the order of the curve (referred to as n), serialized as 32 bytes, most significant byte first.
* coordinates of points on the curve, serialized as specified in SEC1 in compressed form: [0x02 or 0x03] + 32 byte x coordinate), where the header byte depends on the parity of the omitted y coordinate.
* byte sequences

We shall represent the compressed form of point P by χ(P), which for secp256k1 will always be 33 bytes long.

Addition (+) of two coordinates is defined as application of the EC group operation. Multiplication (*) of an integer and a coordinate is defined as repeated application of the EC group operation. The generator element of the curve is called G. The public key K corresponding to the private key k is calculated as k*G. We do not distinguish between numbers or coordinates and their serialization as byte sequences.

===Extended keys===

In what follows, we will define a function that derives a number of child keys from a parent key. In order to prevent these from depending solely on the key itself, we extend both private and public keys first with an extra 256 bits of entropy. This extension, called the chain code, is identical for corresponding private and public keys, and consists of 32 bytes.

We represent an extended private key as (k,c), with k the normal private key, and c the chain code. An extended public key is represented as (K,c), with K = k*G and c the chain code.

===Child key derivation functions===

We allow for two different types of derivation: public and private.
* Private derivation: knowledge of the private key kpar and cpar is required to compute both ki and Ki.
* Public derivation: knowledge of the public key Kpar and cpar suffices to compute Ki (but not ki).

We define the private and public child key derivation functions:
* CKD((kpar,cpar),i) → (ki,ci), defined for both private and public derivation.
* CKD'((Kpar,cpar),i) → (Ki,ci), defined only for public derivation.

We use the most significant bit of i to specify which type of derivation to use. i is encoded as a 32 bit unsigned integer, most significant byte first; '||' represents concatenation.

====Private child key derivation====

To define CKD((kpar,cpar),i) → (ki,ci):
* Check whether the highest bit (0x80000000) of i is set:
** If 1, private derivation is used: let I = HMAC-SHA512(Key = cpar, Data = 0x00 || kpar || i) [Note: The 0x00 pads the private key to make it 33 bytes long.]
** If 0, public derivation is used: let I = HMAC-SHA512(Key = cpar, Data = χ(kpar*G) || i)
* Split I into two 32-byte sequences, IL and IR.
* ki = IL + kpar (mod n).
* ci = IR.
In case IL ≥ n, the resulting key is invalid, and one should proceed with the next value for i (note that this has a chance lower than 1 in 2127).

====Public child key derivation====

To define CKD'((Kpar,cpar),i) → (Ki,ci):
* Check whether the highest bit (0x80000000) of i is set:
** If 1, return error
** If 0, let I = HMAC-SHA512(Key = cpar, Data = parity byte || x coordinate(Kpar) || i)
* Split I into two 32-byte sequences, IL and IR.
* Ki = (IL + kpar)*G = IL*G + Kpar (EC operations).
* ci = IR.
In case IL ≥ n, the resulting key is invalid, and one should proceed with the next value for i.

Note that the extended public key corresponding to the evaluation of CKD(kext,i) with public derivation (so with i < 0x80000000) is identical to the evaluation of CKD'(Kext,i), with Kext the extended public key corresponding to kext. Symbolically, CKD((k,c),i)*G = CKD'((k*G,c),i). This implies that CKD' can be used to derive all public keys corresponding to the private keys that CKD would find. It cannot be used to retrieve the private keys, however.

The HMAC-SHA512 function is specified in [http://tools.ietf.org/html/rfc4231 RFC 4231].

===The key tree===

The next step is cascading several CKD constructions to build a tree. We start with one root, the master extended key m. By evaluating CKD(m,i) for several values of i, we get a number of first-degree derivative nodes. As each of these is again an extended key, CKD can be applied to those as well. To shorten notation, we will write CKD(CKD(CKD(m,0x8000003),0x2),0x5) as m/3'/2/5 now.

Each leaf node in the tree corresponds to an actual keypair, while the internal nodes correspond to the collection of keypairs that descends from them. The chain codes of the leaf nodes are ignored, and only their embedded private or public key is used. Because of this construction, knowing an extended private key allows reconstruction of all descendant private keys and public keys, and knowing an extended public keys allows reconstruction of all descendant public keys derived using public derivation.

===Key identifiers===

Extended keys can be identified by the Hash160 (RIPEMD160 after SHA256) of the serialized public key, ignoring the chain code. This corresponds exactly to the data used in traditional Bitcoin addresses. It is not advised to represent this data in base58 format though, as it may be interpreted as an address that way (and wallet software is not required to accept payment to the chain key itself).

The first 32 bits of the identifier are called the fingerprint.

===Serialization format===

Extended public and private keys are serialized as follows:
* 4 byte: version bytes (mainnet: 0x0488B21E public, 0x0488ADE4 private; testnet: 0x043587CF public, 0x04358394 private)
* 1 byte: depth: 0x00 for master nodes, 0x01 for level-1 descendants, ....
* 4 bytes: the fingerprint of the parent's key (0x00000000 if master key)
* 4 bytes: child number. This is the number i in xi = xpar/i, with xi the key being serialized. This is encoded in MSB order. (0x00000000 if master key)
* 32 bytes: the chain code
* 33 bytes: the public key or private key data (0x02 + X or 0x03 + X for public keys, 0x00 + k for private keys)

This 78 byte structure can be encoded like other Bitcoin data in Base58, by first adding 32 checksum bits (derived from the double SHA-256 checksum), and then converting to the Base58 representation. This results in a Base58-encoded string of up to 112 characters. Because of the choice of the version bytes, the Base58 representation will start with "xprv" or "xpub" on mainnet, "tprv" or "tpub" on testnet.

Note that the fingerprint of the parent only serves as a fast way to detect parent and child nodes in software, and software must be willing to deal with collisions. Internally, the full 160-bit identifier could be used.

When importing a serialized extended public key, implementations must verify whether the X coordinate in the public key data corresponds to a point on the curve. If not, the extended public key is invalid.

===Master key generation===

The total number of possible extended keypairs is almost 2^512, but the produced keys are only 256 bits long, and offer about half of that in terms of security. Therefore, master keys are not generated directly, but instead from a potentially short seed value.

* Generate a seed S of a chosen length (at least 128 bits, but 256 is advised) from a (P)RNG.
* Calculate I = HMAC-SHA512(key="Bitcoin seed", msg=S)
* Split I into two 32-byte sequences, IL and IR.
* Use IL (mod n) as master secret key, and IR as master chain code.
In case IL is 0 or >=n, the master key is invalid.

[[File:BIP32-derivation.png]]

==Specification: Wallet structure==

The previous sections specified key trees and their nodes. The next step is imposing a wallet structure on this tree. The layout defined in this section is a default only, though clients are encouraged to mimick it for compatibility, even if not all features are supported.

An HDW is organized as several 'accounts'. Accounts are numbered, the default account ("") being number 0. Clients are not required to support more than one account - if not, they only use the default account.

Each account is composed of two keypair chains: an internal and an external one. The external keychain is used to generate new public addresses, while the internal keychain is used for all other operations (change addresses, generation addresses, ..., anything that doesn't need to be communicated). Clients that do not support separate keychains for these should use the external one for everything.

* m/i'/0/k corresponds to the k'th keypair of the external chain of account number i of the HDW derived from master m.
* m/i'/1/k corresponds to the k'th keypair of the internal chain of account number i of the HDW derived from master m.

===Use cases===

====Full wallet sharing: m====

In cases where two systems need to access a single shared wallet, and both need to be able to perform spendings, one needs to share the master private extended key. Nodes can keep a pool of N look-ahead keys cached for external chains, to watch for incoming payments. The look-ahead for internal chains can be very small, as no gaps are to be expected here. An extra look-ahead could be active for the first unused account's chains - triggering the creation of a new account when used. Note that the name of the account will still need to be entered manually and cannot be synchronized via the block chain.

====Audits: M====

In case an auditor needs full access to the list of incoming and outgoing payments, one can share the master public extended key. This will allow the auditor to see all transactions from and to the wallet, in all accounts, but not a single secret key.

====Per-office balances: m/i'====

When a business has several independent offices, they can all use wallets derived from a single master. This will allow the headquarters to maintain a super-wallet that sees all incoming and outgoing transactions of all offices, and even permit moving money between the offices.

====Recurrent business-to-business transactions: M/i'/0====

In case two business partners often transfer money, one can use the extended public key for the external chain of a specific account (M/i'/0) as a sort of "super address", allowing frequent transactions that cannot (easily) be associated, but without needing to request a new address for each payment.
Such a mechanism could also be used by mining pool operators as variable payout address.

====Unsecure money receiver: M/i'/0====

When an unsecure webserver is used to run an e-commerce site, it needs to know public addresses that be used to receive payments. The webserver only needs to know the public extended key of the external chain of a single account. This means someone illegally obtaining access to the webserver can at most see all incoming payments, but will not (trivially) be able to distinguish outgoing transactions, nor see payments received by other webservers if there are several ones.

==Compatibility==

To comply with this standard, a client must at least be able to import an extended public or private key, to give access to its direct descendants as wallet keys. The wallet structure (master/account/chain/subchain) presented in the second part of the specification is advisory only, but is suggested as a minimal structure for easy compatibility - even when no separate accounts or distinction between internal and external chains is made. However, implementations may deviate from it for specific needs; more complex applications may call for a more complex tree structure.

==Security==

In addition to the expectations from the EC public-key cryptography itself:
* Given a public key K, an attacker cannot find the corresponding private key more efficiently than by solving the EC discrete logarithm problem (assumed to require 2128 group operations).
the intended security properties of this standard are:
* Given a child extended private key (ki,ci) and the integer i, an attacker cannot find the parent private key kpar more efficiently than a 2256 brute force of HMAC-SHA512.
* Given any number (2 <= N <= 232-1) of (index, extended private key) tuples (ij,(pj,cj)), with distinct ij's, determining whether they are derived from a common parent extended private key (i.e., whether there exists a (ppar,cpar) such that for each j in [0..N-1] CKD((ppar,cpar),ij)=(pj,cj)), cannot be done more efficiently than a 2256 brute force of HMAC-SHA512.
Note however that the following properties does not exist:
* Given a parent extended public key (Kpar,cpar) and a child public key (Ki), it is hard to find i.
* Given a parent extended public key (Kpar,cpar) and a child private key (ki) using public derivation, it is hard to find kpar.

Private and public keys must be kept safe as usual. Leaking a private key means access to coins - leaking a public key can mean loss of privacy.

Somewhat more care must be taken regarding extended keys, as these correspond to an entire (sub)tree of keys. One weakness that may not be immediately obvious, is that knowledge of the extended public key + a private key descending from it is equivalent to knowing the extended private key (i.e., every private and public key) in case public derivation is used. This means that extended public keys must be treated more carefully than regular public keys. This is the reason why accounts at the first level of the default wallet layout use private derivation, so a leak of account-specific (or below) private key never risks compromising the master.

We rely on resistance against (partial) preimages in HMAC-SHA512 to prevent IL in key derivation and master key generation from being zero.

==Test Vectors==

I'll publish test vectors as soon as the specification is assumed to be final.

==Acknowledgements==

* Gregory Maxwell for the original idea of type-2 deterministic wallets, and many discussions about it.
* Alan Reiner for the implementation of this scheme in Armory, and the suggestions that followed from that.
* Mike Caldwell for the version bytes to obtain human-recognizable Base58 strings.

BIP 0032

2013-05-04T22:33:33Z

CodeShark: /* Private child key derivation */

{{bip}}

<div style="color:red">
WARNING: please do not assume this specification is final.
</div>

RECENT CHANGES:
* [16 Apr 2013] Added private derivation for i >= 0x80000000 (less risk of parent private key leakage)
* [30 Apr 2013] Switched from multiplication by I_L to addition of I_L (faster, easier implementation)

<pre>
BIP: 32
Title: Hierarchical Deterministic Wallets
Author: Pieter Wuille
Status: Draft
Type: Informational
Created: 11-02-2012
</pre>

==Abstract==

This document describes hierarchical determinstic wallets (or "HD Wallets"): wallets which can be shared partially or entirely with different systems, each with or without the ability to spend coins.

The specification is intended to set a standard for deterministic wallets that can be interchanged between different clients. Although the wallets described here have many features, not all are required by supporting clients.

The specification consists of two parts. In a first part, a system for deriving a tree of keypairs from a single seed is presented. The second part demonstrates how to build a wallet structure on top of such a tree.

==Motivation==

The Bitcoin reference client uses randomly generated keys. In order to avoid the necessity for a backup after every transaction, (by default) 100 keys are cached in a pool of reserve keys. Still, these wallets are not intended to be shared and used on several systems simultaneously. They support hiding their private keys by using the wallet encrypt feature and not sharing the password, but such "neutered" wallets lose the power to generate public keys as well.

Deterministic wallets do not require such frequent backups, and elliptic curve mathematics permit schemes where one can calculate the public keys without revealing the private keys. This permits for example a webshop business to let its webserver generate a fresh addresses (public key hashes) for each order or for each customer, without giving the webserver access to the corresponding private keys (which are required for spending the received funds).

However, deterministic wallets typically consist of a single "chain" of keypairs. The fact that there is only one chain means that sharing a wallet happens on an all-or-nothing basis. However, in some cases one only wants some (public) keys to be shared and recoverable. In the example of a webshop, the webserver does not need access to all public keys of the merchant's wallet; only to those addresses which are used to receive customer's payments, and not for example the change addresses that are generated when the merchant spends money. Hierarchical deterministic wallets allow such selective sharing by supporting multiple keypair chains, derived from a single root.

==Specification: Key derivation==

===Conventions===

In the rest of this text we will assume the public key cryptography used in Bitcoin, namely elliptic curve cryptography using the field and curve parameters defined by secp256k1 (http://www.secg.org/index.php?action=secg,docs_secg). Variables below are either:
* integers modulo the order of the curve (referred to as n), serialized as 32 bytes, most significant byte first.
* coordinates of points on the curve, serialized as specified in SEC1 in compressed form: [0x02 or 0x03] + 32 byte x coordinate), where the header byte depends on the parity of the omitted y coordinate.
* byte sequences

We shall represent the compressed form of point P by χ(P), which for secp256k1 will always be 33 bytes long.

Addition (+) of two coordinates is defined as application of the EC group operation. Multiplication (*) of an integer and a coordinate is defined as repeated application of the EC group operation. The generator element of the curve is called G. The public key K corresponding to the private key k is calculated as k*G. We do not distinguish between numbers or coordinates and their serialization as byte sequences.

===Extended keys===

In what follows, we will define a function that derives a number of child keys from a parent key. In order to prevent these from depending solely on the key itself, we extend both private and public keys first with an extra 256 bits of entropy. This extension, called the chain code, is identical for corresponding private and public keys, and consists of 32 bytes.

We represent an extended private key as (k,c), with k the normal private key, and c the chain code. An extended public key is represented as (K,c), with K = k*G and c the chain code.

===Child key derivation functions===

We allow for two different types of derivation: public and private.
* Private derivation: knowledge of the private key kpar and cpar is required to compute both ki and Ki.
* Public derivation: knowledge of the public key Kpar and cpar suffices to compute Ki (but not ki).

We define the private and public child key derivation functions:
* CKD((kpar,cpar),i) → (ki,ci), defined for both private and public derivation.
* CKD'((Kpar,cpar),i) → (Ki,ci), defined only for public derivation.

We use the most significant bit of i to specify which type of derivation to use. i is encoded as a 32 bit unsigned integer, most significant byte first; '||' represents concatenation.

====Private child key derivation====

To define CKD((kpar,cpar),i) → (ki,ci):
* Check whether the highest bit (0x80000000) of i is set:
** If 1, private derivation is used: let I = HMAC-SHA512(Key = cpar, Data = 0x00 || kpar || i) [Note: The 0x00 pads the private key to make it 33 bytes.]
** If 0, public derivation is used: let I = HMAC-SHA512(Key = cpar, Data = χ(kpar*G) || i)
* Split I into two 32-byte sequences, IL and IR.
* ki = IL + kpar (mod n).
* ci = IR.
In case IL ≥ n, the resulting key is invalid, and one should proceed with the next value for i (note that this has a chance lower than 1 in 2127).

====Public child key derivation====

To define CKD'((Kpar,cpar),i) → (Ki,ci):
* Check whether the highest bit (0x80000000) of i is set:
** If 1, return error
** If 0, let I = HMAC-SHA512(Key = cpar, Data = parity byte || x coordinate(Kpar) || i)
* Split I into two 32-byte sequences, IL and IR.
* Ki = (IL + kpar)*G = IL*G + Kpar (EC operations).
* ci = IR.
In case IL ≥ n, the resulting key is invalid, and one should proceed with the next value for i.

Note that the extended public key corresponding to the evaluation of CKD(kext,i) with public derivation (so with i < 0x80000000) is identical to the evaluation of CKD'(Kext,i), with Kext the extended public key corresponding to kext. Symbolically, CKD((k,c),i)*G = CKD'((k*G,c),i). This implies that CKD' can be used to derive all public keys corresponding to the private keys that CKD would find. It cannot be used to retrieve the private keys, however.

The HMAC-SHA512 function is specified in [http://tools.ietf.org/html/rfc4231 RFC 4231].

===The key tree===

The next step is cascading several CKD constructions to build a tree. We start with one root, the master extended key m. By evaluating CKD(m,i) for several values of i, we get a number of first-degree derivative nodes. As each of these is again an extended key, CKD can be applied to those as well. To shorten notation, we will write CKD(CKD(CKD(m,0x8000003),0x2),0x5) as m/3'/2/5 now.

Each leaf node in the tree corresponds to an actual keypair, while the internal nodes correspond to the collection of keypairs that descends from them. The chain codes of the leaf nodes are ignored, and only their embedded private or public key is used. Because of this construction, knowing an extended private key allows reconstruction of all descendant private keys and public keys, and knowing an extended public keys allows reconstruction of all descendant public keys derived using public derivation.

===Key identifiers===

Extended keys can be identified by the Hash160 (RIPEMD160 after SHA256) of the serialized public key, ignoring the chain code. This corresponds exactly to the data used in traditional Bitcoin addresses. It is not advised to represent this data in base58 format though, as it may be interpreted as an address that way (and wallet software is not required to accept payment to the chain key itself).

The first 32 bits of the identifier are called the fingerprint.

===Serialization format===

Extended public and private keys are serialized as follows:
* 4 byte: version bytes (mainnet: 0x0488B21E public, 0x0488ADE4 private; testnet: 0x043587CF public, 0x04358394 private)
* 1 byte: depth: 0x00 for master nodes, 0x01 for level-1 descendants, ....
* 4 bytes: the fingerprint of the parent's key (0x00000000 if master key)
* 4 bytes: child number. This is the number i in xi = xpar/i, with xi the key being serialized. This is encoded in MSB order. (0x00000000 if master key)
* 32 bytes: the chain code
* 33 bytes: the public key or private key data (0x02 + X or 0x03 + X for public keys, 0x00 + k for private keys)

This 78 byte structure can be encoded like other Bitcoin data in Base58, by first adding 32 checksum bits (derived from the double SHA-256 checksum), and then converting to the Base58 representation. This results in a Base58-encoded string of up to 112 characters. Because of the choice of the version bytes, the Base58 representation will start with "xprv" or "xpub" on mainnet, "tprv" or "tpub" on testnet.

Note that the fingerprint of the parent only serves as a fast way to detect parent and child nodes in software, and software must be willing to deal with collisions. Internally, the full 160-bit identifier could be used.

When importing a serialized extended public key, implementations must verify whether the X coordinate in the public key data corresponds to a point on the curve. If not, the extended public key is invalid.

===Master key generation===

The total number of possible extended keypairs is almost 2^512, but the produced keys are only 256 bits long, and offer about half of that in terms of security. Therefore, master keys are not generated directly, but instead from a potentially short seed value.

* Generate a seed S of a chosen length (at least 128 bits, but 256 is advised) from a (P)RNG.
* Calculate I = HMAC-SHA512(key="Bitcoin seed", msg=S)
* Split I into two 32-byte sequences, IL and IR.
* Use IL (mod n) as master secret key, and IR as master chain code.
In case IL is 0 or >=n, the master key is invalid.

[[File:BIP32-derivation.png]]

==Specification: Wallet structure==

The previous sections specified key trees and their nodes. The next step is imposing a wallet structure on this tree. The layout defined in this section is a default only, though clients are encouraged to mimick it for compatibility, even if not all features are supported.

An HDW is organized as several 'accounts'. Accounts are numbered, the default account ("") being number 0. Clients are not required to support more than one account - if not, they only use the default account.

Each account is composed of two keypair chains: an internal and an external one. The external keychain is used to generate new public addresses, while the internal keychain is used for all other operations (change addresses, generation addresses, ..., anything that doesn't need to be communicated). Clients that do not support separate keychains for these should use the external one for everything.

* m/i'/0/k corresponds to the k'th keypair of the external chain of account number i of the HDW derived from master m.
* m/i'/1/k corresponds to the k'th keypair of the internal chain of account number i of the HDW derived from master m.

===Use cases===

====Full wallet sharing: m====

In cases where two systems need to access a single shared wallet, and both need to be able to perform spendings, one needs to share the master private extended key. Nodes can keep a pool of N look-ahead keys cached for external chains, to watch for incoming payments. The look-ahead for internal chains can be very small, as no gaps are to be expected here. An extra look-ahead could be active for the first unused account's chains - triggering the creation of a new account when used. Note that the name of the account will still need to be entered manually and cannot be synchronized via the block chain.

====Audits: M====

In case an auditor needs full access to the list of incoming and outgoing payments, one can share the master public extended key. This will allow the auditor to see all transactions from and to the wallet, in all accounts, but not a single secret key.

====Per-office balances: m/i'====

When a business has several independent offices, they can all use wallets derived from a single master. This will allow the headquarters to maintain a super-wallet that sees all incoming and outgoing transactions of all offices, and even permit moving money between the offices.

====Recurrent business-to-business transactions: M/i'/0====

In case two business partners often transfer money, one can use the extended public key for the external chain of a specific account (M/i'/0) as a sort of "super address", allowing frequent transactions that cannot (easily) be associated, but without needing to request a new address for each payment.
Such a mechanism could also be used by mining pool operators as variable payout address.

====Unsecure money receiver: M/i'/0====

When an unsecure webserver is used to run an e-commerce site, it needs to know public addresses that be used to receive payments. The webserver only needs to know the public extended key of the external chain of a single account. This means someone illegally obtaining access to the webserver can at most see all incoming payments, but will not (trivially) be able to distinguish outgoing transactions, nor see payments received by other webservers if there are several ones.

==Compatibility==

To comply with this standard, a client must at least be able to import an extended public or private key, to give access to its direct descendants as wallet keys. The wallet structure (master/account/chain/subchain) presented in the second part of the specification is advisory only, but is suggested as a minimal structure for easy compatibility - even when no separate accounts or distinction between internal and external chains is made. However, implementations may deviate from it for specific needs; more complex applications may call for a more complex tree structure.

==Security==

In addition to the expectations from the EC public-key cryptography itself:
* Given a public key K, an attacker cannot find the corresponding private key more efficiently than by solving the EC discrete logarithm problem (assumed to require 2128 group operations).
the intended security properties of this standard are:
* Given a child extended private key (ki,ci) and the integer i, an attacker cannot find the parent private key kpar more efficiently than a 2256 brute force of HMAC-SHA512.
* Given any number (2 <= N <= 232-1) of (index, extended private key) tuples (ij,(pj,cj)), with distinct ij's, determining whether they are derived from a common parent extended private key (i.e., whether there exists a (ppar,cpar) such that for each j in [0..N-1] CKD((ppar,cpar),ij)=(pj,cj)), cannot be done more efficiently than a 2256 brute force of HMAC-SHA512.
Note however that the following properties does not exist:
* Given a parent extended public key (Kpar,cpar) and a child public key (Ki), it is hard to find i.
* Given a parent extended public key (Kpar,cpar) and a child private key (ki) using public derivation, it is hard to find kpar.

Private and public keys must be kept safe as usual. Leaking a private key means access to coins - leaking a public key can mean loss of privacy.

Somewhat more care must be taken regarding extended keys, as these correspond to an entire (sub)tree of keys. One weakness that may not be immediately obvious, is that knowledge of the extended public key + a private key descending from it is equivalent to knowing the extended private key (i.e., every private and public key) in case public derivation is used. This means that extended public keys must be treated more carefully than regular public keys. This is the reason why accounts at the first level of the default wallet layout use private derivation, so a leak of account-specific (or below) private key never risks compromising the master.

We rely on resistance against (partial) preimages in HMAC-SHA512 to prevent IL in key derivation and master key generation from being zero.

==Test Vectors==

I'll publish test vectors as soon as the specification is assumed to be final.

==Acknowledgements==

* Gregory Maxwell for the original idea of type-2 deterministic wallets, and many discussions about it.
* Alan Reiner for the implementation of this scheme in Armory, and the suggestions that followed from that.
* Mike Caldwell for the version bytes to obtain human-recognizable Base58 strings.

BIP 0032

2013-05-04T22:33:16Z

CodeShark: /* Private child key derivation */

{{bip}}

<div style="color:red">
WARNING: please do not assume this specification is final.
</div>

RECENT CHANGES:
* [16 Apr 2013] Added private derivation for i >= 0x80000000 (less risk of parent private key leakage)
* [30 Apr 2013] Switched from multiplication by I_L to addition of I_L (faster, easier implementation)

<pre>
BIP: 32
Title: Hierarchical Deterministic Wallets
Author: Pieter Wuille
Status: Draft
Type: Informational
Created: 11-02-2012
</pre>

==Abstract==

This document describes hierarchical determinstic wallets (or "HD Wallets"): wallets which can be shared partially or entirely with different systems, each with or without the ability to spend coins.

The specification is intended to set a standard for deterministic wallets that can be interchanged between different clients. Although the wallets described here have many features, not all are required by supporting clients.

The specification consists of two parts. In a first part, a system for deriving a tree of keypairs from a single seed is presented. The second part demonstrates how to build a wallet structure on top of such a tree.

==Motivation==

The Bitcoin reference client uses randomly generated keys. In order to avoid the necessity for a backup after every transaction, (by default) 100 keys are cached in a pool of reserve keys. Still, these wallets are not intended to be shared and used on several systems simultaneously. They support hiding their private keys by using the wallet encrypt feature and not sharing the password, but such "neutered" wallets lose the power to generate public keys as well.

Deterministic wallets do not require such frequent backups, and elliptic curve mathematics permit schemes where one can calculate the public keys without revealing the private keys. This permits for example a webshop business to let its webserver generate a fresh addresses (public key hashes) for each order or for each customer, without giving the webserver access to the corresponding private keys (which are required for spending the received funds).

However, deterministic wallets typically consist of a single "chain" of keypairs. The fact that there is only one chain means that sharing a wallet happens on an all-or-nothing basis. However, in some cases one only wants some (public) keys to be shared and recoverable. In the example of a webshop, the webserver does not need access to all public keys of the merchant's wallet; only to those addresses which are used to receive customer's payments, and not for example the change addresses that are generated when the merchant spends money. Hierarchical deterministic wallets allow such selective sharing by supporting multiple keypair chains, derived from a single root.

==Specification: Key derivation==

===Conventions===

In the rest of this text we will assume the public key cryptography used in Bitcoin, namely elliptic curve cryptography using the field and curve parameters defined by secp256k1 (http://www.secg.org/index.php?action=secg,docs_secg). Variables below are either:
* integers modulo the order of the curve (referred to as n), serialized as 32 bytes, most significant byte first.
* coordinates of points on the curve, serialized as specified in SEC1 in compressed form: [0x02 or 0x03] + 32 byte x coordinate), where the header byte depends on the parity of the omitted y coordinate.
* byte sequences

We shall represent the compressed form of point P by χ(P), which for secp256k1 will always be 33 bytes long.

Addition (+) of two coordinates is defined as application of the EC group operation. Multiplication (*) of an integer and a coordinate is defined as repeated application of the EC group operation. The generator element of the curve is called G. The public key K corresponding to the private key k is calculated as k*G. We do not distinguish between numbers or coordinates and their serialization as byte sequences.

===Extended keys===

In what follows, we will define a function that derives a number of child keys from a parent key. In order to prevent these from depending solely on the key itself, we extend both private and public keys first with an extra 256 bits of entropy. This extension, called the chain code, is identical for corresponding private and public keys, and consists of 32 bytes.

We represent an extended private key as (k,c), with k the normal private key, and c the chain code. An extended public key is represented as (K,c), with K = k*G and c the chain code.

===Child key derivation functions===

We allow for two different types of derivation: public and private.
* Private derivation: knowledge of the private key kpar and cpar is required to compute both ki and Ki.
* Public derivation: knowledge of the public key Kpar and cpar suffices to compute Ki (but not ki).

We define the private and public child key derivation functions:
* CKD((kpar,cpar),i) → (ki,ci), defined for both private and public derivation.
* CKD'((Kpar,cpar),i) → (Ki,ci), defined only for public derivation.

We use the most significant bit of i to specify which type of derivation to use. i is encoded as a 32 bit unsigned integer, most significant byte first; '||' represents concatenation.

====Private child key derivation====

To define CKD((kpar,cpar),i) → (ki,ci):
* Check whether the highest bit (0x80000000) of i is set:
** If 1, private derivation is used: let I = HMAC-SHA512(Key = cpar, Data = 0x00 || kpar || i) (The 0x00 pads the private key to make it 33 bytes)
** If 0, public derivation is used: let I = HMAC-SHA512(Key = cpar, Data = χ(kpar*G) || i)
* Split I into two 32-byte sequences, IL and IR.
* ki = IL + kpar (mod n).
* ci = IR.
In case IL ≥ n, the resulting key is invalid, and one should proceed with the next value for i (note that this has a chance lower than 1 in 2127).

====Public child key derivation====

To define CKD'((Kpar,cpar),i) → (Ki,ci):
* Check whether the highest bit (0x80000000) of i is set:
** If 1, return error
** If 0, let I = HMAC-SHA512(Key = cpar, Data = parity byte || x coordinate(Kpar) || i)
* Split I into two 32-byte sequences, IL and IR.
* Ki = (IL + kpar)*G = IL*G + Kpar (EC operations).
* ci = IR.
In case IL ≥ n, the resulting key is invalid, and one should proceed with the next value for i.

Note that the extended public key corresponding to the evaluation of CKD(kext,i) with public derivation (so with i < 0x80000000) is identical to the evaluation of CKD'(Kext,i), with Kext the extended public key corresponding to kext. Symbolically, CKD((k,c),i)*G = CKD'((k*G,c),i). This implies that CKD' can be used to derive all public keys corresponding to the private keys that CKD would find. It cannot be used to retrieve the private keys, however.

The HMAC-SHA512 function is specified in [http://tools.ietf.org/html/rfc4231 RFC 4231].

===The key tree===

The next step is cascading several CKD constructions to build a tree. We start with one root, the master extended key m. By evaluating CKD(m,i) for several values of i, we get a number of first-degree derivative nodes. As each of these is again an extended key, CKD can be applied to those as well. To shorten notation, we will write CKD(CKD(CKD(m,0x8000003),0x2),0x5) as m/3'/2/5 now.

Each leaf node in the tree corresponds to an actual keypair, while the internal nodes correspond to the collection of keypairs that descends from them. The chain codes of the leaf nodes are ignored, and only their embedded private or public key is used. Because of this construction, knowing an extended private key allows reconstruction of all descendant private keys and public keys, and knowing an extended public keys allows reconstruction of all descendant public keys derived using public derivation.

===Key identifiers===

Extended keys can be identified by the Hash160 (RIPEMD160 after SHA256) of the serialized public key, ignoring the chain code. This corresponds exactly to the data used in traditional Bitcoin addresses. It is not advised to represent this data in base58 format though, as it may be interpreted as an address that way (and wallet software is not required to accept payment to the chain key itself).

The first 32 bits of the identifier are called the fingerprint.

===Serialization format===

Extended public and private keys are serialized as follows:
* 4 byte: version bytes (mainnet: 0x0488B21E public, 0x0488ADE4 private; testnet: 0x043587CF public, 0x04358394 private)
* 1 byte: depth: 0x00 for master nodes, 0x01 for level-1 descendants, ....
* 4 bytes: the fingerprint of the parent's key (0x00000000 if master key)
* 4 bytes: child number. This is the number i in xi = xpar/i, with xi the key being serialized. This is encoded in MSB order. (0x00000000 if master key)
* 32 bytes: the chain code
* 33 bytes: the public key or private key data (0x02 + X or 0x03 + X for public keys, 0x00 + k for private keys)

This 78 byte structure can be encoded like other Bitcoin data in Base58, by first adding 32 checksum bits (derived from the double SHA-256 checksum), and then converting to the Base58 representation. This results in a Base58-encoded string of up to 112 characters. Because of the choice of the version bytes, the Base58 representation will start with "xprv" or "xpub" on mainnet, "tprv" or "tpub" on testnet.

Note that the fingerprint of the parent only serves as a fast way to detect parent and child nodes in software, and software must be willing to deal with collisions. Internally, the full 160-bit identifier could be used.

When importing a serialized extended public key, implementations must verify whether the X coordinate in the public key data corresponds to a point on the curve. If not, the extended public key is invalid.

===Master key generation===

The total number of possible extended keypairs is almost 2^512, but the produced keys are only 256 bits long, and offer about half of that in terms of security. Therefore, master keys are not generated directly, but instead from a potentially short seed value.

* Generate a seed S of a chosen length (at least 128 bits, but 256 is advised) from a (P)RNG.
* Calculate I = HMAC-SHA512(key="Bitcoin seed", msg=S)
* Split I into two 32-byte sequences, IL and IR.
* Use IL (mod n) as master secret key, and IR as master chain code.
In case IL is 0 or >=n, the master key is invalid.

[[File:BIP32-derivation.png]]

==Specification: Wallet structure==

The previous sections specified key trees and their nodes. The next step is imposing a wallet structure on this tree. The layout defined in this section is a default only, though clients are encouraged to mimick it for compatibility, even if not all features are supported.

An HDW is organized as several 'accounts'. Accounts are numbered, the default account ("") being number 0. Clients are not required to support more than one account - if not, they only use the default account.

Each account is composed of two keypair chains: an internal and an external one. The external keychain is used to generate new public addresses, while the internal keychain is used for all other operations (change addresses, generation addresses, ..., anything that doesn't need to be communicated). Clients that do not support separate keychains for these should use the external one for everything.

* m/i'/0/k corresponds to the k'th keypair of the external chain of account number i of the HDW derived from master m.
* m/i'/1/k corresponds to the k'th keypair of the internal chain of account number i of the HDW derived from master m.

===Use cases===

====Full wallet sharing: m====

In cases where two systems need to access a single shared wallet, and both need to be able to perform spendings, one needs to share the master private extended key. Nodes can keep a pool of N look-ahead keys cached for external chains, to watch for incoming payments. The look-ahead for internal chains can be very small, as no gaps are to be expected here. An extra look-ahead could be active for the first unused account's chains - triggering the creation of a new account when used. Note that the name of the account will still need to be entered manually and cannot be synchronized via the block chain.

====Audits: M====

In case an auditor needs full access to the list of incoming and outgoing payments, one can share the master public extended key. This will allow the auditor to see all transactions from and to the wallet, in all accounts, but not a single secret key.

====Per-office balances: m/i'====

When a business has several independent offices, they can all use wallets derived from a single master. This will allow the headquarters to maintain a super-wallet that sees all incoming and outgoing transactions of all offices, and even permit moving money between the offices.

====Recurrent business-to-business transactions: M/i'/0====

In case two business partners often transfer money, one can use the extended public key for the external chain of a specific account (M/i'/0) as a sort of "super address", allowing frequent transactions that cannot (easily) be associated, but without needing to request a new address for each payment.
Such a mechanism could also be used by mining pool operators as variable payout address.

====Unsecure money receiver: M/i'/0====

When an unsecure webserver is used to run an e-commerce site, it needs to know public addresses that be used to receive payments. The webserver only needs to know the public extended key of the external chain of a single account. This means someone illegally obtaining access to the webserver can at most see all incoming payments, but will not (trivially) be able to distinguish outgoing transactions, nor see payments received by other webservers if there are several ones.

==Compatibility==

To comply with this standard, a client must at least be able to import an extended public or private key, to give access to its direct descendants as wallet keys. The wallet structure (master/account/chain/subchain) presented in the second part of the specification is advisory only, but is suggested as a minimal structure for easy compatibility - even when no separate accounts or distinction between internal and external chains is made. However, implementations may deviate from it for specific needs; more complex applications may call for a more complex tree structure.

==Security==

In addition to the expectations from the EC public-key cryptography itself:
* Given a public key K, an attacker cannot find the corresponding private key more efficiently than by solving the EC discrete logarithm problem (assumed to require 2128 group operations).
the intended security properties of this standard are:
* Given a child extended private key (ki,ci) and the integer i, an attacker cannot find the parent private key kpar more efficiently than a 2256 brute force of HMAC-SHA512.
* Given any number (2 <= N <= 232-1) of (index, extended private key) tuples (ij,(pj,cj)), with distinct ij's, determining whether they are derived from a common parent extended private key (i.e., whether there exists a (ppar,cpar) such that for each j in [0..N-1] CKD((ppar,cpar),ij)=(pj,cj)), cannot be done more efficiently than a 2256 brute force of HMAC-SHA512.
Note however that the following properties does not exist:
* Given a parent extended public key (Kpar,cpar) and a child public key (Ki), it is hard to find i.
* Given a parent extended public key (Kpar,cpar) and a child private key (ki) using public derivation, it is hard to find kpar.

Private and public keys must be kept safe as usual. Leaking a private key means access to coins - leaking a public key can mean loss of privacy.

Somewhat more care must be taken regarding extended keys, as these correspond to an entire (sub)tree of keys. One weakness that may not be immediately obvious, is that knowledge of the extended public key + a private key descending from it is equivalent to knowing the extended private key (i.e., every private and public key) in case public derivation is used. This means that extended public keys must be treated more carefully than regular public keys. This is the reason why accounts at the first level of the default wallet layout use private derivation, so a leak of account-specific (or below) private key never risks compromising the master.

We rely on resistance against (partial) preimages in HMAC-SHA512 to prevent IL in key derivation and master key generation from being zero.

==Test Vectors==

I'll publish test vectors as soon as the specification is assumed to be final.

==Acknowledgements==

* Gregory Maxwell for the original idea of type-2 deterministic wallets, and many discussions about it.
* Alan Reiner for the implementation of this scheme in Armory, and the suggestions that followed from that.
* Mike Caldwell for the version bytes to obtain human-recognizable Base58 strings.

BIP 0032

2013-05-04T22:31:49Z

CodeShark: /* Private child key derivation */

{{bip}}

<div style="color:red">
WARNING: please do not assume this specification is final.
</div>

RECENT CHANGES:
* [16 Apr 2013] Added private derivation for i >= 0x80000000 (less risk of parent private key leakage)
* [30 Apr 2013] Switched from multiplication by I_L to addition of I_L (faster, easier implementation)

<pre>
BIP: 32
Title: Hierarchical Deterministic Wallets
Author: Pieter Wuille
Status: Draft
Type: Informational
Created: 11-02-2012
</pre>

==Abstract==

This document describes hierarchical determinstic wallets (or "HD Wallets"): wallets which can be shared partially or entirely with different systems, each with or without the ability to spend coins.

The specification is intended to set a standard for deterministic wallets that can be interchanged between different clients. Although the wallets described here have many features, not all are required by supporting clients.

The specification consists of two parts. In a first part, a system for deriving a tree of keypairs from a single seed is presented. The second part demonstrates how to build a wallet structure on top of such a tree.

==Motivation==

The Bitcoin reference client uses randomly generated keys. In order to avoid the necessity for a backup after every transaction, (by default) 100 keys are cached in a pool of reserve keys. Still, these wallets are not intended to be shared and used on several systems simultaneously. They support hiding their private keys by using the wallet encrypt feature and not sharing the password, but such "neutered" wallets lose the power to generate public keys as well.

Deterministic wallets do not require such frequent backups, and elliptic curve mathematics permit schemes where one can calculate the public keys without revealing the private keys. This permits for example a webshop business to let its webserver generate a fresh addresses (public key hashes) for each order or for each customer, without giving the webserver access to the corresponding private keys (which are required for spending the received funds).

However, deterministic wallets typically consist of a single "chain" of keypairs. The fact that there is only one chain means that sharing a wallet happens on an all-or-nothing basis. However, in some cases one only wants some (public) keys to be shared and recoverable. In the example of a webshop, the webserver does not need access to all public keys of the merchant's wallet; only to those addresses which are used to receive customer's payments, and not for example the change addresses that are generated when the merchant spends money. Hierarchical deterministic wallets allow such selective sharing by supporting multiple keypair chains, derived from a single root.

==Specification: Key derivation==

===Conventions===

In the rest of this text we will assume the public key cryptography used in Bitcoin, namely elliptic curve cryptography using the field and curve parameters defined by secp256k1 (http://www.secg.org/index.php?action=secg,docs_secg). Variables below are either:
* integers modulo the order of the curve (referred to as n), serialized as 32 bytes, most significant byte first.
* coordinates of points on the curve, serialized as specified in SEC1 in compressed form: [0x02 or 0x03] + 32 byte x coordinate), where the header byte depends on the parity of the omitted y coordinate.
* byte sequences

We shall represent the compressed form of point P by χ(P), which for secp256k1 will always be 33 bytes long.

Addition (+) of two coordinates is defined as application of the EC group operation. Multiplication (*) of an integer and a coordinate is defined as repeated application of the EC group operation. The generator element of the curve is called G. The public key K corresponding to the private key k is calculated as k*G. We do not distinguish between numbers or coordinates and their serialization as byte sequences.

===Extended keys===

In what follows, we will define a function that derives a number of child keys from a parent key. In order to prevent these from depending solely on the key itself, we extend both private and public keys first with an extra 256 bits of entropy. This extension, called the chain code, is identical for corresponding private and public keys, and consists of 32 bytes.

We represent an extended private key as (k,c), with k the normal private key, and c the chain code. An extended public key is represented as (K,c), with K = k*G and c the chain code.

===Child key derivation functions===

We allow for two different types of derivation: public and private.
* Private derivation: knowledge of the private key kpar and cpar is required to compute both ki and Ki.
* Public derivation: knowledge of the public key Kpar and cpar suffices to compute Ki (but not ki).

We define the private and public child key derivation functions:
* CKD((kpar,cpar),i) → (ki,ci), defined for both private and public derivation.
* CKD'((Kpar,cpar),i) → (Ki,ci), defined only for public derivation.

We use the most significant bit of i to specify which type of derivation to use. i is encoded as a 32 bit unsigned integer, most significant byte first; '||' represents concatenation.

====Private child key derivation====

To define CKD((kpar,cpar),i) → (ki,ci):
* Check whether the highest bit (0x80000000) of i is set:
** If 1, private derivation is used: let I = HMAC-SHA512(Key = cpar, Data = 0x00 || kpar || i) (The 0x00 makes sure the data being hashed aligns with the public version)
** If 0, public derivation is used: let I = HMAC-SHA512(Key = cpar, Data = χ(kpar*G) || i)
* Split I into two 32-byte sequences, IL and IR.
* ki = IL + kpar (mod n).
* ci = IR.
In case IL ≥ n, the resulting key is invalid, and one should proceed with the next value for i (note that this has a chance lower than 1 in 2127).

====Public child key derivation====

To define CKD'((Kpar,cpar),i) → (Ki,ci):
* Check whether the highest bit (0x80000000) of i is set:
** If 1, return error
** If 0, let I = HMAC-SHA512(Key = cpar, Data = parity byte || x coordinate(Kpar) || i)
* Split I into two 32-byte sequences, IL and IR.
* Ki = (IL + kpar)*G = IL*G + Kpar (EC operations).
* ci = IR.
In case IL ≥ n, the resulting key is invalid, and one should proceed with the next value for i.

Note that the extended public key corresponding to the evaluation of CKD(kext,i) with public derivation (so with i < 0x80000000) is identical to the evaluation of CKD'(Kext,i), with Kext the extended public key corresponding to kext. Symbolically, CKD((k,c),i)*G = CKD'((k*G,c),i). This implies that CKD' can be used to derive all public keys corresponding to the private keys that CKD would find. It cannot be used to retrieve the private keys, however.

The HMAC-SHA512 function is specified in [http://tools.ietf.org/html/rfc4231 RFC 4231].

===The key tree===

The next step is cascading several CKD constructions to build a tree. We start with one root, the master extended key m. By evaluating CKD(m,i) for several values of i, we get a number of first-degree derivative nodes. As each of these is again an extended key, CKD can be applied to those as well. To shorten notation, we will write CKD(CKD(CKD(m,0x8000003),0x2),0x5) as m/3'/2/5 now.

Each leaf node in the tree corresponds to an actual keypair, while the internal nodes correspond to the collection of keypairs that descends from them. The chain codes of the leaf nodes are ignored, and only their embedded private or public key is used. Because of this construction, knowing an extended private key allows reconstruction of all descendant private keys and public keys, and knowing an extended public keys allows reconstruction of all descendant public keys derived using public derivation.

===Key identifiers===

Extended keys can be identified by the Hash160 (RIPEMD160 after SHA256) of the serialized public key, ignoring the chain code. This corresponds exactly to the data used in traditional Bitcoin addresses. It is not advised to represent this data in base58 format though, as it may be interpreted as an address that way (and wallet software is not required to accept payment to the chain key itself).

The first 32 bits of the identifier are called the fingerprint.

===Serialization format===

Extended public and private keys are serialized as follows:
* 4 byte: version bytes (mainnet: 0x0488B21E public, 0x0488ADE4 private; testnet: 0x043587CF public, 0x04358394 private)
* 1 byte: depth: 0x00 for master nodes, 0x01 for level-1 descendants, ....
* 4 bytes: the fingerprint of the parent's key (0x00000000 if master key)
* 4 bytes: child number. This is the number i in xi = xpar/i, with xi the key being serialized. This is encoded in MSB order. (0x00000000 if master key)
* 32 bytes: the chain code
* 33 bytes: the public key or private key data (0x02 + X or 0x03 + X for public keys, 0x00 + k for private keys)

This 78 byte structure can be encoded like other Bitcoin data in Base58, by first adding 32 checksum bits (derived from the double SHA-256 checksum), and then converting to the Base58 representation. This results in a Base58-encoded string of up to 112 characters. Because of the choice of the version bytes, the Base58 representation will start with "xprv" or "xpub" on mainnet, "tprv" or "tpub" on testnet.

Note that the fingerprint of the parent only serves as a fast way to detect parent and child nodes in software, and software must be willing to deal with collisions. Internally, the full 160-bit identifier could be used.

When importing a serialized extended public key, implementations must verify whether the X coordinate in the public key data corresponds to a point on the curve. If not, the extended public key is invalid.

===Master key generation===

The total number of possible extended keypairs is almost 2^512, but the produced keys are only 256 bits long, and offer about half of that in terms of security. Therefore, master keys are not generated directly, but instead from a potentially short seed value.

* Generate a seed S of a chosen length (at least 128 bits, but 256 is advised) from a (P)RNG.
* Calculate I = HMAC-SHA512(key="Bitcoin seed", msg=S)
* Split I into two 32-byte sequences, IL and IR.
* Use IL (mod n) as master secret key, and IR as master chain code.
In case IL is 0 or >=n, the master key is invalid.

[[File:BIP32-derivation.png]]

==Specification: Wallet structure==

The previous sections specified key trees and their nodes. The next step is imposing a wallet structure on this tree. The layout defined in this section is a default only, though clients are encouraged to mimick it for compatibility, even if not all features are supported.

An HDW is organized as several 'accounts'. Accounts are numbered, the default account ("") being number 0. Clients are not required to support more than one account - if not, they only use the default account.

Each account is composed of two keypair chains: an internal and an external one. The external keychain is used to generate new public addresses, while the internal keychain is used for all other operations (change addresses, generation addresses, ..., anything that doesn't need to be communicated). Clients that do not support separate keychains for these should use the external one for everything.

* m/i'/0/k corresponds to the k'th keypair of the external chain of account number i of the HDW derived from master m.
* m/i'/1/k corresponds to the k'th keypair of the internal chain of account number i of the HDW derived from master m.

===Use cases===

====Full wallet sharing: m====

In cases where two systems need to access a single shared wallet, and both need to be able to perform spendings, one needs to share the master private extended key. Nodes can keep a pool of N look-ahead keys cached for external chains, to watch for incoming payments. The look-ahead for internal chains can be very small, as no gaps are to be expected here. An extra look-ahead could be active for the first unused account's chains - triggering the creation of a new account when used. Note that the name of the account will still need to be entered manually and cannot be synchronized via the block chain.

====Audits: M====

In case an auditor needs full access to the list of incoming and outgoing payments, one can share the master public extended key. This will allow the auditor to see all transactions from and to the wallet, in all accounts, but not a single secret key.

====Per-office balances: m/i'====

When a business has several independent offices, they can all use wallets derived from a single master. This will allow the headquarters to maintain a super-wallet that sees all incoming and outgoing transactions of all offices, and even permit moving money between the offices.

====Recurrent business-to-business transactions: M/i'/0====

In case two business partners often transfer money, one can use the extended public key for the external chain of a specific account (M/i'/0) as a sort of "super address", allowing frequent transactions that cannot (easily) be associated, but without needing to request a new address for each payment.
Such a mechanism could also be used by mining pool operators as variable payout address.

====Unsecure money receiver: M/i'/0====

When an unsecure webserver is used to run an e-commerce site, it needs to know public addresses that be used to receive payments. The webserver only needs to know the public extended key of the external chain of a single account. This means someone illegally obtaining access to the webserver can at most see all incoming payments, but will not (trivially) be able to distinguish outgoing transactions, nor see payments received by other webservers if there are several ones.

==Compatibility==

To comply with this standard, a client must at least be able to import an extended public or private key, to give access to its direct descendants as wallet keys. The wallet structure (master/account/chain/subchain) presented in the second part of the specification is advisory only, but is suggested as a minimal structure for easy compatibility - even when no separate accounts or distinction between internal and external chains is made. However, implementations may deviate from it for specific needs; more complex applications may call for a more complex tree structure.

==Security==

In addition to the expectations from the EC public-key cryptography itself:
* Given a public key K, an attacker cannot find the corresponding private key more efficiently than by solving the EC discrete logarithm problem (assumed to require 2128 group operations).
the intended security properties of this standard are:
* Given a child extended private key (ki,ci) and the integer i, an attacker cannot find the parent private key kpar more efficiently than a 2256 brute force of HMAC-SHA512.
* Given any number (2 <= N <= 232-1) of (index, extended private key) tuples (ij,(pj,cj)), with distinct ij's, determining whether they are derived from a common parent extended private key (i.e., whether there exists a (ppar,cpar) such that for each j in [0..N-1] CKD((ppar,cpar),ij)=(pj,cj)), cannot be done more efficiently than a 2256 brute force of HMAC-SHA512.
Note however that the following properties does not exist:
* Given a parent extended public key (Kpar,cpar) and a child public key (Ki), it is hard to find i.
* Given a parent extended public key (Kpar,cpar) and a child private key (ki) using public derivation, it is hard to find kpar.

Private and public keys must be kept safe as usual. Leaking a private key means access to coins - leaking a public key can mean loss of privacy.

Somewhat more care must be taken regarding extended keys, as these correspond to an entire (sub)tree of keys. One weakness that may not be immediately obvious, is that knowledge of the extended public key + a private key descending from it is equivalent to knowing the extended private key (i.e., every private and public key) in case public derivation is used. This means that extended public keys must be treated more carefully than regular public keys. This is the reason why accounts at the first level of the default wallet layout use private derivation, so a leak of account-specific (or below) private key never risks compromising the master.

We rely on resistance against (partial) preimages in HMAC-SHA512 to prevent IL in key derivation and master key generation from being zero.

==Test Vectors==

I'll publish test vectors as soon as the specification is assumed to be final.

==Acknowledgements==

* Gregory Maxwell for the original idea of type-2 deterministic wallets, and many discussions about it.
* Alan Reiner for the implementation of this scheme in Armory, and the suggestions that followed from that.
* Mike Caldwell for the version bytes to obtain human-recognizable Base58 strings.

BIP 0032

2013-05-04T22:31:07Z

CodeShark: /* Conventions */

{{bip}}

<div style="color:red">
WARNING: please do not assume this specification is final.
</div>

RECENT CHANGES:
* [16 Apr 2013] Added private derivation for i >= 0x80000000 (less risk of parent private key leakage)
* [30 Apr 2013] Switched from multiplication by I_L to addition of I_L (faster, easier implementation)

<pre>
BIP: 32
Title: Hierarchical Deterministic Wallets
Author: Pieter Wuille
Status: Draft
Type: Informational
Created: 11-02-2012
</pre>

==Abstract==

This document describes hierarchical determinstic wallets (or "HD Wallets"): wallets which can be shared partially or entirely with different systems, each with or without the ability to spend coins.

The specification is intended to set a standard for deterministic wallets that can be interchanged between different clients. Although the wallets described here have many features, not all are required by supporting clients.

The specification consists of two parts. In a first part, a system for deriving a tree of keypairs from a single seed is presented. The second part demonstrates how to build a wallet structure on top of such a tree.

==Motivation==

The Bitcoin reference client uses randomly generated keys. In order to avoid the necessity for a backup after every transaction, (by default) 100 keys are cached in a pool of reserve keys. Still, these wallets are not intended to be shared and used on several systems simultaneously. They support hiding their private keys by using the wallet encrypt feature and not sharing the password, but such "neutered" wallets lose the power to generate public keys as well.

Deterministic wallets do not require such frequent backups, and elliptic curve mathematics permit schemes where one can calculate the public keys without revealing the private keys. This permits for example a webshop business to let its webserver generate a fresh addresses (public key hashes) for each order or for each customer, without giving the webserver access to the corresponding private keys (which are required for spending the received funds).

However, deterministic wallets typically consist of a single "chain" of keypairs. The fact that there is only one chain means that sharing a wallet happens on an all-or-nothing basis. However, in some cases one only wants some (public) keys to be shared and recoverable. In the example of a webshop, the webserver does not need access to all public keys of the merchant's wallet; only to those addresses which are used to receive customer's payments, and not for example the change addresses that are generated when the merchant spends money. Hierarchical deterministic wallets allow such selective sharing by supporting multiple keypair chains, derived from a single root.

==Specification: Key derivation==

===Conventions===

In the rest of this text we will assume the public key cryptography used in Bitcoin, namely elliptic curve cryptography using the field and curve parameters defined by secp256k1 (http://www.secg.org/index.php?action=secg,docs_secg). Variables below are either:
* integers modulo the order of the curve (referred to as n), serialized as 32 bytes, most significant byte first.
* coordinates of points on the curve, serialized as specified in SEC1 in compressed form: [0x02 or 0x03] + 32 byte x coordinate), where the header byte depends on the parity of the omitted y coordinate.
* byte sequences

We shall represent the compressed form of point P by χ(P), which for secp256k1 will always be 33 bytes long.

Addition (+) of two coordinates is defined as application of the EC group operation. Multiplication (*) of an integer and a coordinate is defined as repeated application of the EC group operation. The generator element of the curve is called G. The public key K corresponding to the private key k is calculated as k*G. We do not distinguish between numbers or coordinates and their serialization as byte sequences.

===Extended keys===

In what follows, we will define a function that derives a number of child keys from a parent key. In order to prevent these from depending solely on the key itself, we extend both private and public keys first with an extra 256 bits of entropy. This extension, called the chain code, is identical for corresponding private and public keys, and consists of 32 bytes.

We represent an extended private key as (k,c), with k the normal private key, and c the chain code. An extended public key is represented as (K,c), with K = k*G and c the chain code.

===Child key derivation functions===

We allow for two different types of derivation: public and private.
* Private derivation: knowledge of the private key kpar and cpar is required to compute both ki and Ki.
* Public derivation: knowledge of the public key Kpar and cpar suffices to compute Ki (but not ki).

We define the private and public child key derivation functions:
* CKD((kpar,cpar),i) → (ki,ci), defined for both private and public derivation.
* CKD'((Kpar,cpar),i) → (Ki,ci), defined only for public derivation.

We use the most significant bit of i to specify which type of derivation to use. i is encoded as a 32 bit unsigned integer, most significant byte first; '||' represents concatenation.

====Private child key derivation====

To define CKD((kpar,cpar),i) → (ki,ci):
* Check whether the highest bit (0x80000000) of i is set:
** If 1, private derivation is used: let I = HMAC-SHA512(Key = cpar, Data = 0x00 || kpar || i) (The 0x00 makes sure the data being hashed aligns with the public version)
** If 0, public derivation is used: let I = HMAC-SHA512(Key = cpar, Data = parity byte || x coordinate(kpar*G) || i)
* Split I into two 32-byte sequences, IL and IR.
* ki = IL + kpar (mod n).
* ci = IR.
In case IL ≥ n, the resulting key is invalid, and one should proceed with the next value for i (note that this has a chance lower than 1 in 2127).

====Public child key derivation====

To define CKD'((Kpar,cpar),i) → (Ki,ci):
* Check whether the highest bit (0x80000000) of i is set:
** If 1, return error
** If 0, let I = HMAC-SHA512(Key = cpar, Data = parity byte || x coordinate(Kpar) || i)
* Split I into two 32-byte sequences, IL and IR.
* Ki = (IL + kpar)*G = IL*G + Kpar (EC operations).
* ci = IR.
In case IL ≥ n, the resulting key is invalid, and one should proceed with the next value for i.

Note that the extended public key corresponding to the evaluation of CKD(kext,i) with public derivation (so with i < 0x80000000) is identical to the evaluation of CKD'(Kext,i), with Kext the extended public key corresponding to kext. Symbolically, CKD((k,c),i)*G = CKD'((k*G,c),i). This implies that CKD' can be used to derive all public keys corresponding to the private keys that CKD would find. It cannot be used to retrieve the private keys, however.

The HMAC-SHA512 function is specified in [http://tools.ietf.org/html/rfc4231 RFC 4231].

===The key tree===

The next step is cascading several CKD constructions to build a tree. We start with one root, the master extended key m. By evaluating CKD(m,i) for several values of i, we get a number of first-degree derivative nodes. As each of these is again an extended key, CKD can be applied to those as well. To shorten notation, we will write CKD(CKD(CKD(m,0x8000003),0x2),0x5) as m/3'/2/5 now.

Each leaf node in the tree corresponds to an actual keypair, while the internal nodes correspond to the collection of keypairs that descends from them. The chain codes of the leaf nodes are ignored, and only their embedded private or public key is used. Because of this construction, knowing an extended private key allows reconstruction of all descendant private keys and public keys, and knowing an extended public keys allows reconstruction of all descendant public keys derived using public derivation.

===Key identifiers===

Extended keys can be identified by the Hash160 (RIPEMD160 after SHA256) of the serialized public key, ignoring the chain code. This corresponds exactly to the data used in traditional Bitcoin addresses. It is not advised to represent this data in base58 format though, as it may be interpreted as an address that way (and wallet software is not required to accept payment to the chain key itself).

The first 32 bits of the identifier are called the fingerprint.

===Serialization format===

Extended public and private keys are serialized as follows:
* 4 byte: version bytes (mainnet: 0x0488B21E public, 0x0488ADE4 private; testnet: 0x043587CF public, 0x04358394 private)
* 1 byte: depth: 0x00 for master nodes, 0x01 for level-1 descendants, ....
* 4 bytes: the fingerprint of the parent's key (0x00000000 if master key)
* 4 bytes: child number. This is the number i in xi = xpar/i, with xi the key being serialized. This is encoded in MSB order. (0x00000000 if master key)
* 32 bytes: the chain code
* 33 bytes: the public key or private key data (0x02 + X or 0x03 + X for public keys, 0x00 + k for private keys)

This 78 byte structure can be encoded like other Bitcoin data in Base58, by first adding 32 checksum bits (derived from the double SHA-256 checksum), and then converting to the Base58 representation. This results in a Base58-encoded string of up to 112 characters. Because of the choice of the version bytes, the Base58 representation will start with "xprv" or "xpub" on mainnet, "tprv" or "tpub" on testnet.

Note that the fingerprint of the parent only serves as a fast way to detect parent and child nodes in software, and software must be willing to deal with collisions. Internally, the full 160-bit identifier could be used.

When importing a serialized extended public key, implementations must verify whether the X coordinate in the public key data corresponds to a point on the curve. If not, the extended public key is invalid.

===Master key generation===

The total number of possible extended keypairs is almost 2^512, but the produced keys are only 256 bits long, and offer about half of that in terms of security. Therefore, master keys are not generated directly, but instead from a potentially short seed value.

* Generate a seed S of a chosen length (at least 128 bits, but 256 is advised) from a (P)RNG.
* Calculate I = HMAC-SHA512(key="Bitcoin seed", msg=S)
* Split I into two 32-byte sequences, IL and IR.
* Use IL (mod n) as master secret key, and IR as master chain code.
In case IL is 0 or >=n, the master key is invalid.

[[File:BIP32-derivation.png]]

==Specification: Wallet structure==

The previous sections specified key trees and their nodes. The next step is imposing a wallet structure on this tree. The layout defined in this section is a default only, though clients are encouraged to mimick it for compatibility, even if not all features are supported.

An HDW is organized as several 'accounts'. Accounts are numbered, the default account ("") being number 0. Clients are not required to support more than one account - if not, they only use the default account.

Each account is composed of two keypair chains: an internal and an external one. The external keychain is used to generate new public addresses, while the internal keychain is used for all other operations (change addresses, generation addresses, ..., anything that doesn't need to be communicated). Clients that do not support separate keychains for these should use the external one for everything.

* m/i'/0/k corresponds to the k'th keypair of the external chain of account number i of the HDW derived from master m.
* m/i'/1/k corresponds to the k'th keypair of the internal chain of account number i of the HDW derived from master m.

===Use cases===

====Full wallet sharing: m====

In cases where two systems need to access a single shared wallet, and both need to be able to perform spendings, one needs to share the master private extended key. Nodes can keep a pool of N look-ahead keys cached for external chains, to watch for incoming payments. The look-ahead for internal chains can be very small, as no gaps are to be expected here. An extra look-ahead could be active for the first unused account's chains - triggering the creation of a new account when used. Note that the name of the account will still need to be entered manually and cannot be synchronized via the block chain.

====Audits: M====

In case an auditor needs full access to the list of incoming and outgoing payments, one can share the master public extended key. This will allow the auditor to see all transactions from and to the wallet, in all accounts, but not a single secret key.

====Per-office balances: m/i'====

When a business has several independent offices, they can all use wallets derived from a single master. This will allow the headquarters to maintain a super-wallet that sees all incoming and outgoing transactions of all offices, and even permit moving money between the offices.

====Recurrent business-to-business transactions: M/i'/0====

In case two business partners often transfer money, one can use the extended public key for the external chain of a specific account (M/i'/0) as a sort of "super address", allowing frequent transactions that cannot (easily) be associated, but without needing to request a new address for each payment.
Such a mechanism could also be used by mining pool operators as variable payout address.

====Unsecure money receiver: M/i'/0====

When an unsecure webserver is used to run an e-commerce site, it needs to know public addresses that be used to receive payments. The webserver only needs to know the public extended key of the external chain of a single account. This means someone illegally obtaining access to the webserver can at most see all incoming payments, but will not (trivially) be able to distinguish outgoing transactions, nor see payments received by other webservers if there are several ones.

==Compatibility==

To comply with this standard, a client must at least be able to import an extended public or private key, to give access to its direct descendants as wallet keys. The wallet structure (master/account/chain/subchain) presented in the second part of the specification is advisory only, but is suggested as a minimal structure for easy compatibility - even when no separate accounts or distinction between internal and external chains is made. However, implementations may deviate from it for specific needs; more complex applications may call for a more complex tree structure.

==Security==

In addition to the expectations from the EC public-key cryptography itself:
* Given a public key K, an attacker cannot find the corresponding private key more efficiently than by solving the EC discrete logarithm problem (assumed to require 2128 group operations).
the intended security properties of this standard are:
* Given a child extended private key (ki,ci) and the integer i, an attacker cannot find the parent private key kpar more efficiently than a 2256 brute force of HMAC-SHA512.
* Given any number (2 <= N <= 232-1) of (index, extended private key) tuples (ij,(pj,cj)), with distinct ij's, determining whether they are derived from a common parent extended private key (i.e., whether there exists a (ppar,cpar) such that for each j in [0..N-1] CKD((ppar,cpar),ij)=(pj,cj)), cannot be done more efficiently than a 2256 brute force of HMAC-SHA512.
Note however that the following properties does not exist:
* Given a parent extended public key (Kpar,cpar) and a child public key (Ki), it is hard to find i.
* Given a parent extended public key (Kpar,cpar) and a child private key (ki) using public derivation, it is hard to find kpar.

Private and public keys must be kept safe as usual. Leaking a private key means access to coins - leaking a public key can mean loss of privacy.

Somewhat more care must be taken regarding extended keys, as these correspond to an entire (sub)tree of keys. One weakness that may not be immediately obvious, is that knowledge of the extended public key + a private key descending from it is equivalent to knowing the extended private key (i.e., every private and public key) in case public derivation is used. This means that extended public keys must be treated more carefully than regular public keys. This is the reason why accounts at the first level of the default wallet layout use private derivation, so a leak of account-specific (or below) private key never risks compromising the master.

We rely on resistance against (partial) preimages in HMAC-SHA512 to prevent IL in key derivation and master key generation from being zero.

==Test Vectors==

I'll publish test vectors as soon as the specification is assumed to be final.

==Acknowledgements==

* Gregory Maxwell for the original idea of type-2 deterministic wallets, and many discussions about it.
* Alan Reiner for the implementation of this scheme in Armory, and the suggestions that followed from that.
* Mike Caldwell for the version bytes to obtain human-recognizable Base58 strings.

BIP 0032

2013-05-04T22:23:42Z

CodeShark: /* Extended keys */

{{bip}}

<div style="color:red">
WARNING: please do not assume this specification is final.
</div>

RECENT CHANGES:
* [16 Apr 2013] Added private derivation for i >= 0x80000000 (less risk of parent private key leakage)
* [30 Apr 2013] Switched from multiplication by I_L to addition of I_L (faster, easier implementation)

<pre>
BIP: 32
Title: Hierarchical Deterministic Wallets
Author: Pieter Wuille
Status: Draft
Type: Informational
Created: 11-02-2012
</pre>

==Abstract==

This document describes hierarchical determinstic wallets (or "HD Wallets"): wallets which can be shared partially or entirely with different systems, each with or without the ability to spend coins.

The specification is intended to set a standard for deterministic wallets that can be interchanged between different clients. Although the wallets described here have many features, not all are required by supporting clients.

The specification consists of two parts. In a first part, a system for deriving a tree of keypairs from a single seed is presented. The second part demonstrates how to build a wallet structure on top of such a tree.

==Motivation==

The Bitcoin reference client uses randomly generated keys. In order to avoid the necessity for a backup after every transaction, (by default) 100 keys are cached in a pool of reserve keys. Still, these wallets are not intended to be shared and used on several systems simultaneously. They support hiding their private keys by using the wallet encrypt feature and not sharing the password, but such "neutered" wallets lose the power to generate public keys as well.

Deterministic wallets do not require such frequent backups, and elliptic curve mathematics permit schemes where one can calculate the public keys without revealing the private keys. This permits for example a webshop business to let its webserver generate a fresh addresses (public key hashes) for each order or for each customer, without giving the webserver access to the corresponding private keys (which are required for spending the received funds).

However, deterministic wallets typically consist of a single "chain" of keypairs. The fact that there is only one chain means that sharing a wallet happens on an all-or-nothing basis. However, in some cases one only wants some (public) keys to be shared and recoverable. In the example of a webshop, the webserver does not need access to all public keys of the merchant's wallet; only to those addresses which are used to receive customer's payments, and not for example the change addresses that are generated when the merchant spends money. Hierarchical deterministic wallets allow such selective sharing by supporting multiple keypair chains, derived from a single root.

==Specification: Key derivation==

===Conventions===

In the rest of this text we will assume the public key cryptography used in Bitcoin, namely elliptic curve cryptography using the field and curve parameters defined by secp256k1 (http://www.secg.org/index.php?action=secg,docs_secg). Variables below are either:
* integers modulo the order of the curve (referred to as n), serialized as 32 bytes, most significant byte first.
* coordinates of points on the curve, serialized as specified in SEC1 in compressed form: [0x02 or 0x03] + 32 byte x coordinate), where the header byte depends on the parity of the omitted y coordinate.
* byte sequences

Addition (+) of two coordinates is defined as application of the EC group operation. Multiplication (*) of an integer and a coordinate is defined as repeated application of the EC group operation. The generator element of the curve is called G. The public key K corresponding to the private key k is calculated as k*G. We do not distinguish between numbers or coordinates and their serialization as byte sequences.

===Extended keys===

In what follows, we will define a function that derives a number of child keys from a parent key. In order to prevent these from depending solely on the key itself, we extend both private and public keys first with an extra 256 bits of entropy. This extension, called the chain code, is identical for corresponding private and public keys, and consists of 32 bytes.

We represent an extended private key as (k,c), with k the normal private key, and c the chain code. An extended public key is represented as (K,c), with K = k*G and c the chain code.

===Child key derivation functions===

We allow for two different types of derivation: public and private.
* Private derivation: knowledge of the private key kpar and cpar is required to compute both ki and Ki.
* Public derivation: knowledge of the public key Kpar and cpar suffices to compute Ki (but not ki).

We define the private and public child key derivation functions:
* CKD((kpar,cpar),i) → (ki,ci), defined for both private and public derivation.
* CKD'((Kpar,cpar),i) → (Ki,ci), defined only for public derivation.

We use the most significant bit of i to specify which type of derivation to use. i is encoded as a 32 bit unsigned integer, most significant byte first; '||' represents concatenation.

====Private child key derivation====

To define CKD((kpar,cpar),i) → (ki,ci):
* Check whether the highest bit (0x80000000) of i is set:
** If 1, private derivation is used: let I = HMAC-SHA512(Key = cpar, Data = 0x00 || kpar || i) (The 0x00 makes sure the data being hashed aligns with the public version)
** If 0, public derivation is used: let I = HMAC-SHA512(Key = cpar, Data = parity byte || x coordinate(kpar*G) || i)
* Split I into two 32-byte sequences, IL and IR.
* ki = IL + kpar (mod n).
* ci = IR.
In case IL ≥ n, the resulting key is invalid, and one should proceed with the next value for i (note that this has a chance lower than 1 in 2127).

====Public child key derivation====

To define CKD'((Kpar,cpar),i) → (Ki,ci):
* Check whether the highest bit (0x80000000) of i is set:
** If 1, return error
** If 0, let I = HMAC-SHA512(Key = cpar, Data = parity byte || x coordinate(Kpar) || i)
* Split I into two 32-byte sequences, IL and IR.
* Ki = (IL + kpar)*G = IL*G + Kpar (EC operations).
* ci = IR.
In case IL ≥ n, the resulting key is invalid, and one should proceed with the next value for i.

Note that the extended public key corresponding to the evaluation of CKD(kext,i) with public derivation (so with i < 0x80000000) is identical to the evaluation of CKD'(Kext,i), with Kext the extended public key corresponding to kext. Symbolically, CKD((k,c),i)*G = CKD'((k*G,c),i). This implies that CKD' can be used to derive all public keys corresponding to the private keys that CKD would find. It cannot be used to retrieve the private keys, however.

The HMAC-SHA512 function is specified in [http://tools.ietf.org/html/rfc4231 RFC 4231].

===The key tree===

The next step is cascading several CKD constructions to build a tree. We start with one root, the master extended key m. By evaluating CKD(m,i) for several values of i, we get a number of first-degree derivative nodes. As each of these is again an extended key, CKD can be applied to those as well. To shorten notation, we will write CKD(CKD(CKD(m,0x8000003),0x2),0x5) as m/3'/2/5 now.

Each leaf node in the tree corresponds to an actual keypair, while the internal nodes correspond to the collection of keypairs that descends from them. The chain codes of the leaf nodes are ignored, and only their embedded private or public key is used. Because of this construction, knowing an extended private key allows reconstruction of all descendant private keys and public keys, and knowing an extended public keys allows reconstruction of all descendant public keys derived using public derivation.

===Key identifiers===

Extended keys can be identified by the Hash160 (RIPEMD160 after SHA256) of the serialized public key, ignoring the chain code. This corresponds exactly to the data used in traditional Bitcoin addresses. It is not advised to represent this data in base58 format though, as it may be interpreted as an address that way (and wallet software is not required to accept payment to the chain key itself).

The first 32 bits of the identifier are called the fingerprint.

===Serialization format===

Extended public and private keys are serialized as follows:
* 4 byte: version bytes (mainnet: 0x0488B21E public, 0x0488ADE4 private; testnet: 0x043587CF public, 0x04358394 private)
* 1 byte: depth: 0x00 for master nodes, 0x01 for level-1 descendants, ....
* 4 bytes: the fingerprint of the parent's key (0x00000000 if master key)
* 4 bytes: child number. This is the number i in xi = xpar/i, with xi the key being serialized. This is encoded in MSB order. (0x00000000 if master key)
* 32 bytes: the chain code
* 33 bytes: the public key or private key data (0x02 + X or 0x03 + X for public keys, 0x00 + k for private keys)

This 78 byte structure can be encoded like other Bitcoin data in Base58, by first adding 32 checksum bits (derived from the double SHA-256 checksum), and then converting to the Base58 representation. This results in a Base58-encoded string of up to 112 characters. Because of the choice of the version bytes, the Base58 representation will start with "xprv" or "xpub" on mainnet, "tprv" or "tpub" on testnet.

Note that the fingerprint of the parent only serves as a fast way to detect parent and child nodes in software, and software must be willing to deal with collisions. Internally, the full 160-bit identifier could be used.

When importing a serialized extended public key, implementations must verify whether the X coordinate in the public key data corresponds to a point on the curve. If not, the extended public key is invalid.

===Master key generation===

The total number of possible extended keypairs is almost 2^512, but the produced keys are only 256 bits long, and offer about half of that in terms of security. Therefore, master keys are not generated directly, but instead from a potentially short seed value.

* Generate a seed S of a chosen length (at least 128 bits, but 256 is advised) from a (P)RNG.
* Calculate I = HMAC-SHA512(key="Bitcoin seed", msg=S)
* Split I into two 32-byte sequences, IL and IR.
* Use IL (mod n) as master secret key, and IR as master chain code.
In case IL is 0 or >=n, the master key is invalid.

[[File:BIP32-derivation.png]]

==Specification: Wallet structure==

The previous sections specified key trees and their nodes. The next step is imposing a wallet structure on this tree. The layout defined in this section is a default only, though clients are encouraged to mimick it for compatibility, even if not all features are supported.

An HDW is organized as several 'accounts'. Accounts are numbered, the default account ("") being number 0. Clients are not required to support more than one account - if not, they only use the default account.

Each account is composed of two keypair chains: an internal and an external one. The external keychain is used to generate new public addresses, while the internal keychain is used for all other operations (change addresses, generation addresses, ..., anything that doesn't need to be communicated). Clients that do not support separate keychains for these should use the external one for everything.

* m/i'/0/k corresponds to the k'th keypair of the external chain of account number i of the HDW derived from master m.
* m/i'/1/k corresponds to the k'th keypair of the internal chain of account number i of the HDW derived from master m.

===Use cases===

====Full wallet sharing: m====

In cases where two systems need to access a single shared wallet, and both need to be able to perform spendings, one needs to share the master private extended key. Nodes can keep a pool of N look-ahead keys cached for external chains, to watch for incoming payments. The look-ahead for internal chains can be very small, as no gaps are to be expected here. An extra look-ahead could be active for the first unused account's chains - triggering the creation of a new account when used. Note that the name of the account will still need to be entered manually and cannot be synchronized via the block chain.

====Audits: M====

In case an auditor needs full access to the list of incoming and outgoing payments, one can share the master public extended key. This will allow the auditor to see all transactions from and to the wallet, in all accounts, but not a single secret key.

====Per-office balances: m/i'====

When a business has several independent offices, they can all use wallets derived from a single master. This will allow the headquarters to maintain a super-wallet that sees all incoming and outgoing transactions of all offices, and even permit moving money between the offices.

====Recurrent business-to-business transactions: M/i'/0====

In case two business partners often transfer money, one can use the extended public key for the external chain of a specific account (M/i'/0) as a sort of "super address", allowing frequent transactions that cannot (easily) be associated, but without needing to request a new address for each payment.
Such a mechanism could also be used by mining pool operators as variable payout address.

====Unsecure money receiver: M/i'/0====

When an unsecure webserver is used to run an e-commerce site, it needs to know public addresses that be used to receive payments. The webserver only needs to know the public extended key of the external chain of a single account. This means someone illegally obtaining access to the webserver can at most see all incoming payments, but will not (trivially) be able to distinguish outgoing transactions, nor see payments received by other webservers if there are several ones.

==Compatibility==

To comply with this standard, a client must at least be able to import an extended public or private key, to give access to its direct descendants as wallet keys. The wallet structure (master/account/chain/subchain) presented in the second part of the specification is advisory only, but is suggested as a minimal structure for easy compatibility - even when no separate accounts or distinction between internal and external chains is made. However, implementations may deviate from it for specific needs; more complex applications may call for a more complex tree structure.

==Security==

In addition to the expectations from the EC public-key cryptography itself:
* Given a public key K, an attacker cannot find the corresponding private key more efficiently than by solving the EC discrete logarithm problem (assumed to require 2128 group operations).
the intended security properties of this standard are:
* Given a child extended private key (ki,ci) and the integer i, an attacker cannot find the parent private key kpar more efficiently than a 2256 brute force of HMAC-SHA512.
* Given any number (2 <= N <= 232-1) of (index, extended private key) tuples (ij,(pj,cj)), with distinct ij's, determining whether they are derived from a common parent extended private key (i.e., whether there exists a (ppar,cpar) such that for each j in [0..N-1] CKD((ppar,cpar),ij)=(pj,cj)), cannot be done more efficiently than a 2256 brute force of HMAC-SHA512.
Note however that the following properties does not exist:
* Given a parent extended public key (Kpar,cpar) and a child public key (Ki), it is hard to find i.
* Given a parent extended public key (Kpar,cpar) and a child private key (ki) using public derivation, it is hard to find kpar.

Private and public keys must be kept safe as usual. Leaking a private key means access to coins - leaking a public key can mean loss of privacy.

Somewhat more care must be taken regarding extended keys, as these correspond to an entire (sub)tree of keys. One weakness that may not be immediately obvious, is that knowledge of the extended public key + a private key descending from it is equivalent to knowing the extended private key (i.e., every private and public key) in case public derivation is used. This means that extended public keys must be treated more carefully than regular public keys. This is the reason why accounts at the first level of the default wallet layout use private derivation, so a leak of account-specific (or below) private key never risks compromising the master.

We rely on resistance against (partial) preimages in HMAC-SHA512 to prevent IL in key derivation and master key generation from being zero.

==Test Vectors==

I'll publish test vectors as soon as the specification is assumed to be final.

==Acknowledgements==

* Gregory Maxwell for the original idea of type-2 deterministic wallets, and many discussions about it.
* Alan Reiner for the implementation of this scheme in Armory, and the suggestions that followed from that.
* Mike Caldwell for the version bytes to obtain human-recognizable Base58 strings.

BIP 0032

2013-05-04T21:54:36Z

CodeShark: /* Private child key derivation */

{{bip}}

<div style="color:red">
WARNING: please do not assume this specification is final.
</div>

RECENT CHANGES:
* [16 Apr 2013] Added private derivation for i >= 0x80000000 (less risk of parent private key leakage)
* [30 Apr 2013] Switched from multiplication by I_L to addition of I_L (faster, easier implementation)

<pre>
BIP: 32
Title: Hierarchical Deterministic Wallets
Author: Pieter Wuille
Status: Draft
Type: Informational
Created: 11-02-2012
</pre>

==Abstract==

This document describes hierarchical determinstic wallets (or "HD Wallets"): wallets which can be shared partially or entirely with different systems, each with or without the ability to spend coins.

The specification is intended to set a standard for deterministic wallets that can be interchanged between different clients. Although the wallets described here have many features, not all are required by supporting clients.

The specification consists of two parts. In a first part, a system for deriving a tree of keypairs from a single seed is presented. The second part demonstrates how to build a wallet structure on top of such a tree.

==Motivation==

The Bitcoin reference client uses randomly generated keys. In order to avoid the necessity for a backup after every transaction, (by default) 100 keys are cached in a pool of reserve keys. Still, these wallets are not intended to be shared and used on several systems simultaneously. They support hiding their private keys by using the wallet encrypt feature and not sharing the password, but such "neutered" wallets lose the power to generate public keys as well.

Deterministic wallets do not require such frequent backups, and elliptic curve mathematics permit schemes where one can calculate the public keys without revealing the private keys. This permits for example a webshop business to let its webserver generate a fresh addresses (public key hashes) for each order or for each customer, without giving the webserver access to the corresponding private keys (which are required for spending the received funds).

However, deterministic wallets typically consist of a single "chain" of keypairs. The fact that there is only one chain means that sharing a wallet happens on an all-or-nothing basis. However, in some cases one only wants some (public) keys to be shared and recoverable. In the example of a webshop, the webserver does not need access to all public keys of the merchant's wallet; only to those addresses which are used to receive customer's payments, and not for example the change addresses that are generated when the merchant spends money. Hierarchical deterministic wallets allow such selective sharing by supporting multiple keypair chains, derived from a single root.

==Specification: Key derivation==

===Conventions===

In the rest of this text we will assume the public key cryptography used in Bitcoin, namely elliptic curve cryptography using the field and curve parameters defined by secp256k1 (http://www.secg.org/index.php?action=secg,docs_secg). Variables below are either:
* integers modulo the order of the curve (referred to as n), serialized as 32 bytes, most significant byte first.
* coordinates of points on the curve, serialized as specified in SEC1 in compressed form: [0x02 or 0x03] + 32 byte x coordinate), where the header byte depends on the parity of the omitted y coordinate.
* byte sequences

Addition (+) of two coordinates is defined as application of the EC group operation. Multiplication (*) of an integer and a coordinate is defined as repeated application of the EC group operation. The generator element of the curve is called G. The public key K corresponding to the private key k is calculated as k*G. We do not distinguish between numbers or coordinates and their serialization as byte sequences.

===Extended keys===

In what follows, we will define a function that derives a number of child keys from a parent key. In order to prevent these from depending solely on the key itself, we extend both private and public keys first with an extra 256 bits of entropy. This extension, called the chain code, is identical for corresponding private and public keys, and consists of 32 bytes.

We represent an extended private key as (k,c), with k the normal private key, and c the chain code. An extended public key is represented as (K,c), with K the normal public key and c the chain code.

===Child key derivation functions===

We allow for two different types of derivation: public and private.
* Private derivation: knowledge of the private key kpar and cpar is required to compute both ki and Ki.
* Public derivation: knowledge of the public key Kpar and cpar suffices to compute Ki (but not ki).

We define the private and public child key derivation functions:
* CKD((kpar,cpar),i) → (ki,ci), defined for both private and public derivation.
* CKD'((Kpar,cpar),i) → (Ki,ci), defined only for public derivation.

We use the most significant bit of i to specify which type of derivation to use. i is encoded as a 32 bit unsigned integer, most significant byte first; '||' represents concatenation.

====Private child key derivation====

To define CKD((kpar,cpar),i) → (ki,ci):
* Check whether the highest bit (0x80000000) of i is set:
** If 1, private derivation is used: let I = HMAC-SHA512(Key = cpar, Data = 0x00 || kpar || i) (The 0x00 makes sure the data being hashed aligns with the public version)
** If 0, public derivation is used: let I = HMAC-SHA512(Key = cpar, Data = parity byte || x coordinate(kpar*G) || i)
* Split I into two 32-byte sequences, IL and IR.
* ki = IL + kpar (mod n).
* ci = IR.
In case IL ≥ n, the resulting key is invalid, and one should proceed with the next value for i (note that this has a chance lower than 1 in 2127).

====Public child key derivation====

To define CKD'((Kpar,cpar),i) → (Ki,ci):
* Check whether the highest bit (0x80000000) of i is set:
** If 1, return error
** If 0, let I = HMAC-SHA512(Key = cpar, Data = parity byte || x coordinate(Kpar) || i)
* Split I into two 32-byte sequences, IL and IR.
* Ki = (IL + kpar)*G = IL*G + Kpar (EC operations).
* ci = IR.
In case IL ≥ n, the resulting key is invalid, and one should proceed with the next value for i.

Note that the extended public key corresponding to the evaluation of CKD(kext,i) with public derivation (so with i < 0x80000000) is identical to the evaluation of CKD'(Kext,i), with Kext the extended public key corresponding to kext. Symbolically, CKD((k,c),i)*G = CKD'((k*G,c),i). This implies that CKD' can be used to derive all public keys corresponding to the private keys that CKD would find. It cannot be used to retrieve the private keys, however.

The HMAC-SHA512 function is specified in [http://tools.ietf.org/html/rfc4231 RFC 4231].

===The key tree===

The next step is cascading several CKD constructions to build a tree. We start with one root, the master extended key m. By evaluating CKD(m,i) for several values of i, we get a number of first-degree derivative nodes. As each of these is again an extended key, CKD can be applied to those as well. To shorten notation, we will write CKD(CKD(CKD(m,0x8000003),0x2),0x5) as m/3'/2/5 now.

Each leaf node in the tree corresponds to an actual keypair, while the internal nodes correspond to the collection of keypairs that descends from them. The chain codes of the leaf nodes are ignored, and only their embedded private or public key is used. Because of this construction, knowing an extended private key allows reconstruction of all descendant private keys and public keys, and knowing an extended public keys allows reconstruction of all descendant public keys derived using public derivation.

===Key identifiers===

Extended keys can be identified by the Hash160 (RIPEMD160 after SHA256) of the serialized public key, ignoring the chain code. This corresponds exactly to the data used in traditional Bitcoin addresses. It is not advised to represent this data in base58 format though, as it may be interpreted as an address that way (and wallet software is not required to accept payment to the chain key itself).

The first 32 bits of the identifier are called the fingerprint.

===Serialization format===

Extended public and private keys are serialized as follows:
* 4 byte: version bytes (mainnet: 0x0488B21E public, 0x0488ADE4 private; testnet: 0x043587CF public, 0x04358394 private)
* 1 byte: depth: 0x00 for master nodes, 0x01 for level-1 descendants, ....
* 4 bytes: the fingerprint of the parent's key (0x00000000 if master key)
* 4 bytes: child number. This is the number i in xi = xpar/i, with xi the key being serialized. This is encoded in MSB order. (0x00000000 if master key)
* 32 bytes: the chain code
* 33 bytes: the public key or private key data (0x02 + X or 0x03 + X for public keys, 0x00 + k for private keys)

This 78 byte structure can be encoded like other Bitcoin data in Base58, by first adding 32 checksum bits (derived from the double SHA-256 checksum), and then converting to the Base58 representation. This results in a Base58-encoded string of up to 112 characters. Because of the choice of the version bytes, the Base58 representation will start with "xprv" or "xpub" on mainnet, "tprv" or "tpub" on testnet.

Note that the fingerprint of the parent only serves as a fast way to detect parent and child nodes in software, and software must be willing to deal with collisions. Internally, the full 160-bit identifier could be used.

When importing a serialized extended public key, implementations must verify whether the X coordinate in the public key data corresponds to a point on the curve. If not, the extended public key is invalid.

===Master key generation===

The total number of possible extended keypairs is almost 2^512, but the produced keys are only 256 bits long, and offer about half of that in terms of security. Therefore, master keys are not generated directly, but instead from a potentially short seed value.

* Generate a seed S of a chosen length (at least 128 bits, but 256 is advised) from a (P)RNG.
* Calculate I = HMAC-SHA512(key="Bitcoin seed", msg=S)
* Split I into two 32-byte sequences, IL and IR.
* Use IL (mod n) as master secret key, and IR as master chain code.
In case IL is 0 or >=n, the master key is invalid.

[[File:BIP32-derivation.png]]

==Specification: Wallet structure==

The previous sections specified key trees and their nodes. The next step is imposing a wallet structure on this tree. The layout defined in this section is a default only, though clients are encouraged to mimick it for compatibility, even if not all features are supported.

An HDW is organized as several 'accounts'. Accounts are numbered, the default account ("") being number 0. Clients are not required to support more than one account - if not, they only use the default account.

Each account is composed of two keypair chains: an internal and an external one. The external keychain is used to generate new public addresses, while the internal keychain is used for all other operations (change addresses, generation addresses, ..., anything that doesn't need to be communicated). Clients that do not support separate keychains for these should use the external one for everything.

* m/i'/0/k corresponds to the k'th keypair of the external chain of account number i of the HDW derived from master m.
* m/i'/1/k corresponds to the k'th keypair of the internal chain of account number i of the HDW derived from master m.

===Use cases===

====Full wallet sharing: m====

In cases where two systems need to access a single shared wallet, and both need to be able to perform spendings, one needs to share the master private extended key. Nodes can keep a pool of N look-ahead keys cached for external chains, to watch for incoming payments. The look-ahead for internal chains can be very small, as no gaps are to be expected here. An extra look-ahead could be active for the first unused account's chains - triggering the creation of a new account when used. Note that the name of the account will still need to be entered manually and cannot be synchronized via the block chain.

====Audits: M====

In case an auditor needs full access to the list of incoming and outgoing payments, one can share the master public extended key. This will allow the auditor to see all transactions from and to the wallet, in all accounts, but not a single secret key.

====Per-office balances: m/i'====

When a business has several independent offices, they can all use wallets derived from a single master. This will allow the headquarters to maintain a super-wallet that sees all incoming and outgoing transactions of all offices, and even permit moving money between the offices.

====Recurrent business-to-business transactions: M/i'/0====

In case two business partners often transfer money, one can use the extended public key for the external chain of a specific account (M/i'/0) as a sort of "super address", allowing frequent transactions that cannot (easily) be associated, but without needing to request a new address for each payment.
Such a mechanism could also be used by mining pool operators as variable payout address.

====Unsecure money receiver: M/i'/0====

When an unsecure webserver is used to run an e-commerce site, it needs to know public addresses that be used to receive payments. The webserver only needs to know the public extended key of the external chain of a single account. This means someone illegally obtaining access to the webserver can at most see all incoming payments, but will not (trivially) be able to distinguish outgoing transactions, nor see payments received by other webservers if there are several ones.

==Compatibility==

To comply with this standard, a client must at least be able to import an extended public or private key, to give access to its direct descendants as wallet keys. The wallet structure (master/account/chain/subchain) presented in the second part of the specification is advisory only, but is suggested as a minimal structure for easy compatibility - even when no separate accounts or distinction between internal and external chains is made. However, implementations may deviate from it for specific needs; more complex applications may call for a more complex tree structure.

==Security==

In addition to the expectations from the EC public-key cryptography itself:
* Given a public key K, an attacker cannot find the corresponding private key more efficiently than by solving the EC discrete logarithm problem (assumed to require 2128 group operations).
the intended security properties of this standard are:
* Given a child extended private key (ki,ci) and the integer i, an attacker cannot find the parent private key kpar more efficiently than a 2256 brute force of HMAC-SHA512.
* Given any number (2 <= N <= 232-1) of (index, extended private key) tuples (ij,(pj,cj)), with distinct ij's, determining whether they are derived from a common parent extended private key (i.e., whether there exists a (ppar,cpar) such that for each j in [0..N-1] CKD((ppar,cpar),ij)=(pj,cj)), cannot be done more efficiently than a 2256 brute force of HMAC-SHA512.
Note however that the following properties does not exist:
* Given a parent extended public key (Kpar,cpar) and a child public key (Ki), it is hard to find i.
* Given a parent extended public key (Kpar,cpar) and a child private key (ki) using public derivation, it is hard to find kpar.

Private and public keys must be kept safe as usual. Leaking a private key means access to coins - leaking a public key can mean loss of privacy.

Somewhat more care must be taken regarding extended keys, as these correspond to an entire (sub)tree of keys. One weakness that may not be immediately obvious, is that knowledge of the extended public key + a private key descending from it is equivalent to knowing the extended private key (i.e., every private and public key) in case public derivation is used. This means that extended public keys must be treated more carefully than regular public keys. This is the reason why accounts at the first level of the default wallet layout use private derivation, so a leak of account-specific (or below) private key never risks compromising the master.

We rely on resistance against (partial) preimages in HMAC-SHA512 to prevent IL in key derivation and master key generation from being zero.

==Test Vectors==

I'll publish test vectors as soon as the specification is assumed to be final.

==Acknowledgements==

* Gregory Maxwell for the original idea of type-2 deterministic wallets, and many discussions about it.
* Alan Reiner for the implementation of this scheme in Armory, and the suggestions that followed from that.
* Mike Caldwell for the version bytes to obtain human-recognizable Base58 strings.

BIP 0032

2013-05-04T21:52:22Z

CodeShark: /* Public child key derivation */

{{bip}}

<div style="color:red">
WARNING: please do not assume this specification is final.
</div>

RECENT CHANGES:
* [16 Apr 2013] Added private derivation for i >= 0x80000000 (less risk of parent private key leakage)
* [30 Apr 2013] Switched from multiplication by I_L to addition of I_L (faster, easier implementation)

<pre>
BIP: 32
Title: Hierarchical Deterministic Wallets
Author: Pieter Wuille
Status: Draft
Type: Informational
Created: 11-02-2012
</pre>

==Abstract==

This document describes hierarchical determinstic wallets (or "HD Wallets"): wallets which can be shared partially or entirely with different systems, each with or without the ability to spend coins.

The specification is intended to set a standard for deterministic wallets that can be interchanged between different clients. Although the wallets described here have many features, not all are required by supporting clients.

The specification consists of two parts. In a first part, a system for deriving a tree of keypairs from a single seed is presented. The second part demonstrates how to build a wallet structure on top of such a tree.

==Motivation==

The Bitcoin reference client uses randomly generated keys. In order to avoid the necessity for a backup after every transaction, (by default) 100 keys are cached in a pool of reserve keys. Still, these wallets are not intended to be shared and used on several systems simultaneously. They support hiding their private keys by using the wallet encrypt feature and not sharing the password, but such "neutered" wallets lose the power to generate public keys as well.

Deterministic wallets do not require such frequent backups, and elliptic curve mathematics permit schemes where one can calculate the public keys without revealing the private keys. This permits for example a webshop business to let its webserver generate a fresh addresses (public key hashes) for each order or for each customer, without giving the webserver access to the corresponding private keys (which are required for spending the received funds).

However, deterministic wallets typically consist of a single "chain" of keypairs. The fact that there is only one chain means that sharing a wallet happens on an all-or-nothing basis. However, in some cases one only wants some (public) keys to be shared and recoverable. In the example of a webshop, the webserver does not need access to all public keys of the merchant's wallet; only to those addresses which are used to receive customer's payments, and not for example the change addresses that are generated when the merchant spends money. Hierarchical deterministic wallets allow such selective sharing by supporting multiple keypair chains, derived from a single root.

==Specification: Key derivation==

===Conventions===

In the rest of this text we will assume the public key cryptography used in Bitcoin, namely elliptic curve cryptography using the field and curve parameters defined by secp256k1 (http://www.secg.org/index.php?action=secg,docs_secg). Variables below are either:
* integers modulo the order of the curve (referred to as n), serialized as 32 bytes, most significant byte first.
* coordinates of points on the curve, serialized as specified in SEC1 in compressed form: [0x02 or 0x03] + 32 byte x coordinate), where the header byte depends on the parity of the omitted y coordinate.
* byte sequences

Addition (+) of two coordinates is defined as application of the EC group operation. Multiplication (*) of an integer and a coordinate is defined as repeated application of the EC group operation. The generator element of the curve is called G. The public key K corresponding to the private key k is calculated as k*G. We do not distinguish between numbers or coordinates and their serialization as byte sequences.

===Extended keys===

In what follows, we will define a function that derives a number of child keys from a parent key. In order to prevent these from depending solely on the key itself, we extend both private and public keys first with an extra 256 bits of entropy. This extension, called the chain code, is identical for corresponding private and public keys, and consists of 32 bytes.

We represent an extended private key as (k,c), with k the normal private key, and c the chain code. An extended public key is represented as (K,c), with K the normal public key and c the chain code.

===Child key derivation functions===

We allow for two different types of derivation: public and private.
* Private derivation: knowledge of the private key kpar and cpar is required to compute both ki and Ki.
* Public derivation: knowledge of the public key Kpar and cpar suffices to compute Ki (but not ki).

We define the private and public child key derivation functions:
* CKD((kpar,cpar),i) → (ki,ci), defined for both private and public derivation.
* CKD'((Kpar,cpar),i) → (Ki,ci), defined only for public derivation.

We use the most significant bit of i to specify which type of derivation to use. i is encoded as a 32 bit unsigned integer, most significant byte first; '||' represents concatenation.

====Private child key derivation====

To define CKD((kpar,cpar),i) → (ki,ci):
* Check whether the highest bit (0x80000000) of i is set:
** If 1, private derivation is used: let I = HMAC-SHA512(Key=cpar, Data=0x00 || kpar || i) (The 0x00 makes sure the data being hashed aligns with the public version)
** If 0, public derivation is used: let I = HMAC-SHA512(Key=cpar, Data=parity byte || x coordinate(kpar*G) || i)
* Split I into two 32-byte sequences, IL and IR.
* ki = IL + kpar (mod n).
* ci = IR.
In case IL ≥ n, the resulting key is invalid, and one should proceed with the next value for i (note that this has a chance lower than 1 in 2127).

====Public child key derivation====

To define CKD'((Kpar,cpar),i) → (Ki,ci):
* Check whether the highest bit (0x80000000) of i is set:
** If 1, return error
** If 0, let I = HMAC-SHA512(Key = cpar, Data = parity byte || x coordinate(Kpar) || i)
* Split I into two 32-byte sequences, IL and IR.
* Ki = (IL + kpar)*G = IL*G + Kpar (EC operations).
* ci = IR.
In case IL ≥ n, the resulting key is invalid, and one should proceed with the next value for i.

Note that the extended public key corresponding to the evaluation of CKD(kext,i) with public derivation (so with i < 0x80000000) is identical to the evaluation of CKD'(Kext,i), with Kext the extended public key corresponding to kext. Symbolically, CKD((k,c),i)*G = CKD'((k*G,c),i). This implies that CKD' can be used to derive all public keys corresponding to the private keys that CKD would find. It cannot be used to retrieve the private keys, however.

The HMAC-SHA512 function is specified in [http://tools.ietf.org/html/rfc4231 RFC 4231].

===The key tree===

The next step is cascading several CKD constructions to build a tree. We start with one root, the master extended key m. By evaluating CKD(m,i) for several values of i, we get a number of first-degree derivative nodes. As each of these is again an extended key, CKD can be applied to those as well. To shorten notation, we will write CKD(CKD(CKD(m,0x8000003),0x2),0x5) as m/3'/2/5 now.

Each leaf node in the tree corresponds to an actual keypair, while the internal nodes correspond to the collection of keypairs that descends from them. The chain codes of the leaf nodes are ignored, and only their embedded private or public key is used. Because of this construction, knowing an extended private key allows reconstruction of all descendant private keys and public keys, and knowing an extended public keys allows reconstruction of all descendant public keys derived using public derivation.

===Key identifiers===

Extended keys can be identified by the Hash160 (RIPEMD160 after SHA256) of the serialized public key, ignoring the chain code. This corresponds exactly to the data used in traditional Bitcoin addresses. It is not advised to represent this data in base58 format though, as it may be interpreted as an address that way (and wallet software is not required to accept payment to the chain key itself).

The first 32 bits of the identifier are called the fingerprint.

===Serialization format===

Extended public and private keys are serialized as follows:
* 4 byte: version bytes (mainnet: 0x0488B21E public, 0x0488ADE4 private; testnet: 0x043587CF public, 0x04358394 private)
* 1 byte: depth: 0x00 for master nodes, 0x01 for level-1 descendants, ....
* 4 bytes: the fingerprint of the parent's key (0x00000000 if master key)
* 4 bytes: child number. This is the number i in xi = xpar/i, with xi the key being serialized. This is encoded in MSB order. (0x00000000 if master key)
* 32 bytes: the chain code
* 33 bytes: the public key or private key data (0x02 + X or 0x03 + X for public keys, 0x00 + k for private keys)

This 78 byte structure can be encoded like other Bitcoin data in Base58, by first adding 32 checksum bits (derived from the double SHA-256 checksum), and then converting to the Base58 representation. This results in a Base58-encoded string of up to 112 characters. Because of the choice of the version bytes, the Base58 representation will start with "xprv" or "xpub" on mainnet, "tprv" or "tpub" on testnet.

Note that the fingerprint of the parent only serves as a fast way to detect parent and child nodes in software, and software must be willing to deal with collisions. Internally, the full 160-bit identifier could be used.

When importing a serialized extended public key, implementations must verify whether the X coordinate in the public key data corresponds to a point on the curve. If not, the extended public key is invalid.

===Master key generation===

The total number of possible extended keypairs is almost 2^512, but the produced keys are only 256 bits long, and offer about half of that in terms of security. Therefore, master keys are not generated directly, but instead from a potentially short seed value.

* Generate a seed S of a chosen length (at least 128 bits, but 256 is advised) from a (P)RNG.
* Calculate I = HMAC-SHA512(key="Bitcoin seed", msg=S)
* Split I into two 32-byte sequences, IL and IR.
* Use IL (mod n) as master secret key, and IR as master chain code.
In case IL is 0 or >=n, the master key is invalid.

[[File:BIP32-derivation.png]]

==Specification: Wallet structure==

The previous sections specified key trees and their nodes. The next step is imposing a wallet structure on this tree. The layout defined in this section is a default only, though clients are encouraged to mimick it for compatibility, even if not all features are supported.

An HDW is organized as several 'accounts'. Accounts are numbered, the default account ("") being number 0. Clients are not required to support more than one account - if not, they only use the default account.

Each account is composed of two keypair chains: an internal and an external one. The external keychain is used to generate new public addresses, while the internal keychain is used for all other operations (change addresses, generation addresses, ..., anything that doesn't need to be communicated). Clients that do not support separate keychains for these should use the external one for everything.

* m/i'/0/k corresponds to the k'th keypair of the external chain of account number i of the HDW derived from master m.
* m/i'/1/k corresponds to the k'th keypair of the internal chain of account number i of the HDW derived from master m.

===Use cases===

====Full wallet sharing: m====

In cases where two systems need to access a single shared wallet, and both need to be able to perform spendings, one needs to share the master private extended key. Nodes can keep a pool of N look-ahead keys cached for external chains, to watch for incoming payments. The look-ahead for internal chains can be very small, as no gaps are to be expected here. An extra look-ahead could be active for the first unused account's chains - triggering the creation of a new account when used. Note that the name of the account will still need to be entered manually and cannot be synchronized via the block chain.

====Audits: M====

In case an auditor needs full access to the list of incoming and outgoing payments, one can share the master public extended key. This will allow the auditor to see all transactions from and to the wallet, in all accounts, but not a single secret key.

====Per-office balances: m/i'====

When a business has several independent offices, they can all use wallets derived from a single master. This will allow the headquarters to maintain a super-wallet that sees all incoming and outgoing transactions of all offices, and even permit moving money between the offices.

====Recurrent business-to-business transactions: M/i'/0====

In case two business partners often transfer money, one can use the extended public key for the external chain of a specific account (M/i'/0) as a sort of "super address", allowing frequent transactions that cannot (easily) be associated, but without needing to request a new address for each payment.
Such a mechanism could also be used by mining pool operators as variable payout address.

====Unsecure money receiver: M/i'/0====

When an unsecure webserver is used to run an e-commerce site, it needs to know public addresses that be used to receive payments. The webserver only needs to know the public extended key of the external chain of a single account. This means someone illegally obtaining access to the webserver can at most see all incoming payments, but will not (trivially) be able to distinguish outgoing transactions, nor see payments received by other webservers if there are several ones.

==Compatibility==

To comply with this standard, a client must at least be able to import an extended public or private key, to give access to its direct descendants as wallet keys. The wallet structure (master/account/chain/subchain) presented in the second part of the specification is advisory only, but is suggested as a minimal structure for easy compatibility - even when no separate accounts or distinction between internal and external chains is made. However, implementations may deviate from it for specific needs; more complex applications may call for a more complex tree structure.

==Security==

In addition to the expectations from the EC public-key cryptography itself:
* Given a public key K, an attacker cannot find the corresponding private key more efficiently than by solving the EC discrete logarithm problem (assumed to require 2128 group operations).
the intended security properties of this standard are:
* Given a child extended private key (ki,ci) and the integer i, an attacker cannot find the parent private key kpar more efficiently than a 2256 brute force of HMAC-SHA512.
* Given any number (2 <= N <= 232-1) of (index, extended private key) tuples (ij,(pj,cj)), with distinct ij's, determining whether they are derived from a common parent extended private key (i.e., whether there exists a (ppar,cpar) such that for each j in [0..N-1] CKD((ppar,cpar),ij)=(pj,cj)), cannot be done more efficiently than a 2256 brute force of HMAC-SHA512.
Note however that the following properties does not exist:
* Given a parent extended public key (Kpar,cpar) and a child public key (Ki), it is hard to find i.
* Given a parent extended public key (Kpar,cpar) and a child private key (ki) using public derivation, it is hard to find kpar.

Private and public keys must be kept safe as usual. Leaking a private key means access to coins - leaking a public key can mean loss of privacy.

Somewhat more care must be taken regarding extended keys, as these correspond to an entire (sub)tree of keys. One weakness that may not be immediately obvious, is that knowledge of the extended public key + a private key descending from it is equivalent to knowing the extended private key (i.e., every private and public key) in case public derivation is used. This means that extended public keys must be treated more carefully than regular public keys. This is the reason why accounts at the first level of the default wallet layout use private derivation, so a leak of account-specific (or below) private key never risks compromising the master.

We rely on resistance against (partial) preimages in HMAC-SHA512 to prevent IL in key derivation and master key generation from being zero.

==Test Vectors==

I'll publish test vectors as soon as the specification is assumed to be final.

==Acknowledgements==

* Gregory Maxwell for the original idea of type-2 deterministic wallets, and many discussions about it.
* Alan Reiner for the implementation of this scheme in Armory, and the suggestions that followed from that.
* Mike Caldwell for the version bytes to obtain human-recognizable Base58 strings.

BIP 0032

2013-05-04T21:49:32Z

CodeShark: /* Private child key derivation */

{{bip}}

<div style="color:red">
WARNING: please do not assume this specification is final.
</div>

RECENT CHANGES:
* [16 Apr 2013] Added private derivation for i >= 0x80000000 (less risk of parent private key leakage)
* [30 Apr 2013] Switched from multiplication by I_L to addition of I_L (faster, easier implementation)

<pre>
BIP: 32
Title: Hierarchical Deterministic Wallets
Author: Pieter Wuille
Status: Draft
Type: Informational
Created: 11-02-2012
</pre>

==Abstract==

This document describes hierarchical determinstic wallets (or "HD Wallets"): wallets which can be shared partially or entirely with different systems, each with or without the ability to spend coins.

The specification is intended to set a standard for deterministic wallets that can be interchanged between different clients. Although the wallets described here have many features, not all are required by supporting clients.

The specification consists of two parts. In a first part, a system for deriving a tree of keypairs from a single seed is presented. The second part demonstrates how to build a wallet structure on top of such a tree.

==Motivation==

The Bitcoin reference client uses randomly generated keys. In order to avoid the necessity for a backup after every transaction, (by default) 100 keys are cached in a pool of reserve keys. Still, these wallets are not intended to be shared and used on several systems simultaneously. They support hiding their private keys by using the wallet encrypt feature and not sharing the password, but such "neutered" wallets lose the power to generate public keys as well.

Deterministic wallets do not require such frequent backups, and elliptic curve mathematics permit schemes where one can calculate the public keys without revealing the private keys. This permits for example a webshop business to let its webserver generate a fresh addresses (public key hashes) for each order or for each customer, without giving the webserver access to the corresponding private keys (which are required for spending the received funds).

However, deterministic wallets typically consist of a single "chain" of keypairs. The fact that there is only one chain means that sharing a wallet happens on an all-or-nothing basis. However, in some cases one only wants some (public) keys to be shared and recoverable. In the example of a webshop, the webserver does not need access to all public keys of the merchant's wallet; only to those addresses which are used to receive customer's payments, and not for example the change addresses that are generated when the merchant spends money. Hierarchical deterministic wallets allow such selective sharing by supporting multiple keypair chains, derived from a single root.

==Specification: Key derivation==

===Conventions===

In the rest of this text we will assume the public key cryptography used in Bitcoin, namely elliptic curve cryptography using the field and curve parameters defined by secp256k1 (http://www.secg.org/index.php?action=secg,docs_secg). Variables below are either:
* integers modulo the order of the curve (referred to as n), serialized as 32 bytes, most significant byte first.
* coordinates of points on the curve, serialized as specified in SEC1 in compressed form: [0x02 or 0x03] + 32 byte x coordinate), where the header byte depends on the parity of the omitted y coordinate.
* byte sequences

Addition (+) of two coordinates is defined as application of the EC group operation. Multiplication (*) of an integer and a coordinate is defined as repeated application of the EC group operation. The generator element of the curve is called G. The public key K corresponding to the private key k is calculated as k*G. We do not distinguish between numbers or coordinates and their serialization as byte sequences.

===Extended keys===

In what follows, we will define a function that derives a number of child keys from a parent key. In order to prevent these from depending solely on the key itself, we extend both private and public keys first with an extra 256 bits of entropy. This extension, called the chain code, is identical for corresponding private and public keys, and consists of 32 bytes.

We represent an extended private key as (k,c), with k the normal private key, and c the chain code. An extended public key is represented as (K,c), with K the normal public key and c the chain code.

===Child key derivation functions===

We allow for two different types of derivation: public and private.
* Private derivation: knowledge of the private key kpar and cpar is required to compute both ki and Ki.
* Public derivation: knowledge of the public key Kpar and cpar suffices to compute Ki (but not ki).

We define the private and public child key derivation functions:
* CKD((kpar,cpar),i) → (ki,ci), defined for both private and public derivation.
* CKD'((Kpar,cpar),i) → (Ki,ci), defined only for public derivation.

We use the most significant bit of i to specify which type of derivation to use. i is encoded as a 32 bit unsigned integer, most significant byte first; '||' represents concatenation.

====Private child key derivation====

To define CKD((kpar,cpar),i) → (ki,ci):
* Check whether the highest bit (0x80000000) of i is set:
** If 1, private derivation is used: let I = HMAC-SHA512(Key=cpar, Data=0x00 || kpar || i) (The 0x00 makes sure the data being hashed aligns with the public version)
** If 0, public derivation is used: let I = HMAC-SHA512(Key=cpar, Data=parity byte || x coordinate(kpar*G) || i)
* Split I into two 32-byte sequences, IL and IR.
* ki = IL + kpar (mod n).
* ci = IR.
In case IL ≥ n, the resulting key is invalid, and one should proceed with the next value for i (note that this has a chance lower than 1 in 2127).

====Public child key derivation====

To define CKD'((Kpar,cpar),i) → (Ki,ci):
* Check whether the highest bit (0x80000000) of i is set:
** If 1, return error
** If 0, let I = HMAC-SHA512(Key=cpar, Data=Kpar || i)
* Split I into two 32-byte sequences, IL and IR.
* Ki = (IL + kpar)*G = IL*G + Kpar (EC operations).
* ci = IR.
In case IL ≥ n, the resulting key is invalid, and one should proceed with the next value for i.

Note that the extended public key corresponding to the evaluation of CKD(x,i) with public derivation (so with i < 0x80000000) is identical to the evaluation of CKD'(X,i), with X the extended public key corresponding to x. Symbolically, CKD(x,i)*G = CKD'(x*G,i). This implies that CKD' can be used to derive all public keys corresponding to the private keys that CKD would find. It cannot be used to retrieve the private keys, however.

The HMAC-SHA512 function is specified in [http://tools.ietf.org/html/rfc4231 RFC 4231].

===The key tree===

The next step is cascading several CKD constructions to build a tree. We start with one root, the master extended key m. By evaluating CKD(m,i) for several values of i, we get a number of first-degree derivative nodes. As each of these is again an extended key, CKD can be applied to those as well. To shorten notation, we will write CKD(CKD(CKD(m,0x8000003),0x2),0x5) as m/3'/2/5 now.

Each leaf node in the tree corresponds to an actual keypair, while the internal nodes correspond to the collection of keypairs that descends from them. The chain codes of the leaf nodes are ignored, and only their embedded private or public key is used. Because of this construction, knowing an extended private key allows reconstruction of all descendant private keys and public keys, and knowing an extended public keys allows reconstruction of all descendant public keys derived using public derivation.

===Key identifiers===

Extended keys can be identified by the Hash160 (RIPEMD160 after SHA256) of the serialized public key, ignoring the chain code. This corresponds exactly to the data used in traditional Bitcoin addresses. It is not advised to represent this data in base58 format though, as it may be interpreted as an address that way (and wallet software is not required to accept payment to the chain key itself).

The first 32 bits of the identifier are called the fingerprint.

===Serialization format===

Extended public and private keys are serialized as follows:
* 4 byte: version bytes (mainnet: 0x0488B21E public, 0x0488ADE4 private; testnet: 0x043587CF public, 0x04358394 private)
* 1 byte: depth: 0x00 for master nodes, 0x01 for level-1 descendants, ....
* 4 bytes: the fingerprint of the parent's key (0x00000000 if master key)
* 4 bytes: child number. This is the number i in xi = xpar/i, with xi the key being serialized. This is encoded in MSB order. (0x00000000 if master key)
* 32 bytes: the chain code
* 33 bytes: the public key or private key data (0x02 + X or 0x03 + X for public keys, 0x00 + k for private keys)

This 78 byte structure can be encoded like other Bitcoin data in Base58, by first adding 32 checksum bits (derived from the double SHA-256 checksum), and then converting to the Base58 representation. This results in a Base58-encoded string of up to 112 characters. Because of the choice of the version bytes, the Base58 representation will start with "xprv" or "xpub" on mainnet, "tprv" or "tpub" on testnet.

Note that the fingerprint of the parent only serves as a fast way to detect parent and child nodes in software, and software must be willing to deal with collisions. Internally, the full 160-bit identifier could be used.

When importing a serialized extended public key, implementations must verify whether the X coordinate in the public key data corresponds to a point on the curve. If not, the extended public key is invalid.

===Master key generation===

The total number of possible extended keypairs is almost 2^512, but the produced keys are only 256 bits long, and offer about half of that in terms of security. Therefore, master keys are not generated directly, but instead from a potentially short seed value.

* Generate a seed S of a chosen length (at least 128 bits, but 256 is advised) from a (P)RNG.
* Calculate I = HMAC-SHA512(key="Bitcoin seed", msg=S)
* Split I into two 32-byte sequences, IL and IR.
* Use IL (mod n) as master secret key, and IR as master chain code.
In case IL is 0 or >=n, the master key is invalid.

[[File:BIP32-derivation.png]]

==Specification: Wallet structure==

The previous sections specified key trees and their nodes. The next step is imposing a wallet structure on this tree. The layout defined in this section is a default only, though clients are encouraged to mimick it for compatibility, even if not all features are supported.

An HDW is organized as several 'accounts'. Accounts are numbered, the default account ("") being number 0. Clients are not required to support more than one account - if not, they only use the default account.

Each account is composed of two keypair chains: an internal and an external one. The external keychain is used to generate new public addresses, while the internal keychain is used for all other operations (change addresses, generation addresses, ..., anything that doesn't need to be communicated). Clients that do not support separate keychains for these should use the external one for everything.

* m/i'/0/k corresponds to the k'th keypair of the external chain of account number i of the HDW derived from master m.
* m/i'/1/k corresponds to the k'th keypair of the internal chain of account number i of the HDW derived from master m.

===Use cases===

====Full wallet sharing: m====

In cases where two systems need to access a single shared wallet, and both need to be able to perform spendings, one needs to share the master private extended key. Nodes can keep a pool of N look-ahead keys cached for external chains, to watch for incoming payments. The look-ahead for internal chains can be very small, as no gaps are to be expected here. An extra look-ahead could be active for the first unused account's chains - triggering the creation of a new account when used. Note that the name of the account will still need to be entered manually and cannot be synchronized via the block chain.

====Audits: M====

In case an auditor needs full access to the list of incoming and outgoing payments, one can share the master public extended key. This will allow the auditor to see all transactions from and to the wallet, in all accounts, but not a single secret key.

====Per-office balances: m/i'====

When a business has several independent offices, they can all use wallets derived from a single master. This will allow the headquarters to maintain a super-wallet that sees all incoming and outgoing transactions of all offices, and even permit moving money between the offices.

====Recurrent business-to-business transactions: M/i'/0====

In case two business partners often transfer money, one can use the extended public key for the external chain of a specific account (M/i'/0) as a sort of "super address", allowing frequent transactions that cannot (easily) be associated, but without needing to request a new address for each payment.
Such a mechanism could also be used by mining pool operators as variable payout address.

====Unsecure money receiver: M/i'/0====

When an unsecure webserver is used to run an e-commerce site, it needs to know public addresses that be used to receive payments. The webserver only needs to know the public extended key of the external chain of a single account. This means someone illegally obtaining access to the webserver can at most see all incoming payments, but will not (trivially) be able to distinguish outgoing transactions, nor see payments received by other webservers if there are several ones.

==Compatibility==

To comply with this standard, a client must at least be able to import an extended public or private key, to give access to its direct descendants as wallet keys. The wallet structure (master/account/chain/subchain) presented in the second part of the specification is advisory only, but is suggested as a minimal structure for easy compatibility - even when no separate accounts or distinction between internal and external chains is made. However, implementations may deviate from it for specific needs; more complex applications may call for a more complex tree structure.

==Security==

In addition to the expectations from the EC public-key cryptography itself:
* Given a public key K, an attacker cannot find the corresponding private key more efficiently than by solving the EC discrete logarithm problem (assumed to require 2128 group operations).
the intended security properties of this standard are:
* Given a child extended private key (ki,ci) and the integer i, an attacker cannot find the parent private key kpar more efficiently than a 2256 brute force of HMAC-SHA512.
* Given any number (2 <= N <= 232-1) of (index, extended private key) tuples (ij,(pj,cj)), with distinct ij's, determining whether they are derived from a common parent extended private key (i.e., whether there exists a (ppar,cpar) such that for each j in [0..N-1] CKD((ppar,cpar),ij)=(pj,cj)), cannot be done more efficiently than a 2256 brute force of HMAC-SHA512.
Note however that the following properties does not exist:
* Given a parent extended public key (Kpar,cpar) and a child public key (Ki), it is hard to find i.
* Given a parent extended public key (Kpar,cpar) and a child private key (ki) using public derivation, it is hard to find kpar.

Private and public keys must be kept safe as usual. Leaking a private key means access to coins - leaking a public key can mean loss of privacy.

Somewhat more care must be taken regarding extended keys, as these correspond to an entire (sub)tree of keys. One weakness that may not be immediately obvious, is that knowledge of the extended public key + a private key descending from it is equivalent to knowing the extended private key (i.e., every private and public key) in case public derivation is used. This means that extended public keys must be treated more carefully than regular public keys. This is the reason why accounts at the first level of the default wallet layout use private derivation, so a leak of account-specific (or below) private key never risks compromising the master.

We rely on resistance against (partial) preimages in HMAC-SHA512 to prevent IL in key derivation and master key generation from being zero.

==Test Vectors==

I'll publish test vectors as soon as the specification is assumed to be final.

==Acknowledgements==

* Gregory Maxwell for the original idea of type-2 deterministic wallets, and many discussions about it.
* Alan Reiner for the implementation of this scheme in Armory, and the suggestions that followed from that.
* Mike Caldwell for the version bytes to obtain human-recognizable Base58 strings.

BIP 0032

2013-05-04T21:48:48Z

CodeShark: /* Private child key derivation */

{{bip}}

<div style="color:red">
WARNING: please do not assume this specification is final.
</div>

RECENT CHANGES:
* [16 Apr 2013] Added private derivation for i >= 0x80000000 (less risk of parent private key leakage)
* [30 Apr 2013] Switched from multiplication by I_L to addition of I_L (faster, easier implementation)

<pre>
BIP: 32
Title: Hierarchical Deterministic Wallets
Author: Pieter Wuille
Status: Draft
Type: Informational
Created: 11-02-2012
</pre>

==Abstract==

This document describes hierarchical determinstic wallets (or "HD Wallets"): wallets which can be shared partially or entirely with different systems, each with or without the ability to spend coins.

The specification is intended to set a standard for deterministic wallets that can be interchanged between different clients. Although the wallets described here have many features, not all are required by supporting clients.

The specification consists of two parts. In a first part, a system for deriving a tree of keypairs from a single seed is presented. The second part demonstrates how to build a wallet structure on top of such a tree.

==Motivation==

The Bitcoin reference client uses randomly generated keys. In order to avoid the necessity for a backup after every transaction, (by default) 100 keys are cached in a pool of reserve keys. Still, these wallets are not intended to be shared and used on several systems simultaneously. They support hiding their private keys by using the wallet encrypt feature and not sharing the password, but such "neutered" wallets lose the power to generate public keys as well.

Deterministic wallets do not require such frequent backups, and elliptic curve mathematics permit schemes where one can calculate the public keys without revealing the private keys. This permits for example a webshop business to let its webserver generate a fresh addresses (public key hashes) for each order or for each customer, without giving the webserver access to the corresponding private keys (which are required for spending the received funds).

However, deterministic wallets typically consist of a single "chain" of keypairs. The fact that there is only one chain means that sharing a wallet happens on an all-or-nothing basis. However, in some cases one only wants some (public) keys to be shared and recoverable. In the example of a webshop, the webserver does not need access to all public keys of the merchant's wallet; only to those addresses which are used to receive customer's payments, and not for example the change addresses that are generated when the merchant spends money. Hierarchical deterministic wallets allow such selective sharing by supporting multiple keypair chains, derived from a single root.

==Specification: Key derivation==

===Conventions===

In the rest of this text we will assume the public key cryptography used in Bitcoin, namely elliptic curve cryptography using the field and curve parameters defined by secp256k1 (http://www.secg.org/index.php?action=secg,docs_secg). Variables below are either:
* integers modulo the order of the curve (referred to as n), serialized as 32 bytes, most significant byte first.
* coordinates of points on the curve, serialized as specified in SEC1 in compressed form: [0x02 or 0x03] + 32 byte x coordinate), where the header byte depends on the parity of the omitted y coordinate.
* byte sequences

Addition (+) of two coordinates is defined as application of the EC group operation. Multiplication (*) of an integer and a coordinate is defined as repeated application of the EC group operation. The generator element of the curve is called G. The public key K corresponding to the private key k is calculated as k*G. We do not distinguish between numbers or coordinates and their serialization as byte sequences.

===Extended keys===

In what follows, we will define a function that derives a number of child keys from a parent key. In order to prevent these from depending solely on the key itself, we extend both private and public keys first with an extra 256 bits of entropy. This extension, called the chain code, is identical for corresponding private and public keys, and consists of 32 bytes.

We represent an extended private key as (k,c), with k the normal private key, and c the chain code. An extended public key is represented as (K,c), with K the normal public key and c the chain code.

===Child key derivation functions===

We allow for two different types of derivation: public and private.
* Private derivation: knowledge of the private key kpar and cpar is required to compute both ki and Ki.
* Public derivation: knowledge of the public key Kpar and cpar suffices to compute Ki (but not ki).

We define the private and public child key derivation functions:
* CKD((kpar,cpar),i) → (ki,ci), defined for both private and public derivation.
* CKD'((Kpar,cpar),i) → (Ki,ci), defined only for public derivation.

We use the most significant bit of i to specify which type of derivation to use. i is encoded as a 32 bit unsigned integer, most significant byte first; '||' represents concatenation.

====Private child key derivation====

To define CKD((kpar,cpar),i) → (ki,ci):
* Check whether the highest bit (0x80000000) of i is set:
** If 1, private derivation is used: let I = HMAC-SHA512(Key=cpar, Data=0x00 || kpar || i) (The 0x00 makes sure the data being hashed aligns with the public version)
** If 0, public derivation is used: let I = HMAC-SHA512(Key=cpar, Data=signed x coordinate(kpar*G) || i)
* Split I into two 32-byte sequences, IL and IR.
* ki = IL + kpar (mod n).
* ci = IR.
In case IL ≥ n, the resulting key is invalid, and one should proceed with the next value for i (note that this has a chance lower than 1 in 2127).

====Public child key derivation====

To define CKD'((Kpar,cpar),i) → (Ki,ci):
* Check whether the highest bit (0x80000000) of i is set:
** If 1, return error
** If 0, let I = HMAC-SHA512(Key=cpar, Data=Kpar || i)
* Split I into two 32-byte sequences, IL and IR.
* Ki = (IL + kpar)*G = IL*G + Kpar (EC operations).
* ci = IR.
In case IL ≥ n, the resulting key is invalid, and one should proceed with the next value for i.

Note that the extended public key corresponding to the evaluation of CKD(x,i) with public derivation (so with i < 0x80000000) is identical to the evaluation of CKD'(X,i), with X the extended public key corresponding to x. Symbolically, CKD(x,i)*G = CKD'(x*G,i). This implies that CKD' can be used to derive all public keys corresponding to the private keys that CKD would find. It cannot be used to retrieve the private keys, however.

The HMAC-SHA512 function is specified in [http://tools.ietf.org/html/rfc4231 RFC 4231].

===The key tree===

The next step is cascading several CKD constructions to build a tree. We start with one root, the master extended key m. By evaluating CKD(m,i) for several values of i, we get a number of first-degree derivative nodes. As each of these is again an extended key, CKD can be applied to those as well. To shorten notation, we will write CKD(CKD(CKD(m,0x8000003),0x2),0x5) as m/3'/2/5 now.

Each leaf node in the tree corresponds to an actual keypair, while the internal nodes correspond to the collection of keypairs that descends from them. The chain codes of the leaf nodes are ignored, and only their embedded private or public key is used. Because of this construction, knowing an extended private key allows reconstruction of all descendant private keys and public keys, and knowing an extended public keys allows reconstruction of all descendant public keys derived using public derivation.

===Key identifiers===

Extended keys can be identified by the Hash160 (RIPEMD160 after SHA256) of the serialized public key, ignoring the chain code. This corresponds exactly to the data used in traditional Bitcoin addresses. It is not advised to represent this data in base58 format though, as it may be interpreted as an address that way (and wallet software is not required to accept payment to the chain key itself).

The first 32 bits of the identifier are called the fingerprint.

===Serialization format===

Extended public and private keys are serialized as follows:
* 4 byte: version bytes (mainnet: 0x0488B21E public, 0x0488ADE4 private; testnet: 0x043587CF public, 0x04358394 private)
* 1 byte: depth: 0x00 for master nodes, 0x01 for level-1 descendants, ....
* 4 bytes: the fingerprint of the parent's key (0x00000000 if master key)
* 4 bytes: child number. This is the number i in xi = xpar/i, with xi the key being serialized. This is encoded in MSB order. (0x00000000 if master key)
* 32 bytes: the chain code
* 33 bytes: the public key or private key data (0x02 + X or 0x03 + X for public keys, 0x00 + k for private keys)

This 78 byte structure can be encoded like other Bitcoin data in Base58, by first adding 32 checksum bits (derived from the double SHA-256 checksum), and then converting to the Base58 representation. This results in a Base58-encoded string of up to 112 characters. Because of the choice of the version bytes, the Base58 representation will start with "xprv" or "xpub" on mainnet, "tprv" or "tpub" on testnet.

Note that the fingerprint of the parent only serves as a fast way to detect parent and child nodes in software, and software must be willing to deal with collisions. Internally, the full 160-bit identifier could be used.

When importing a serialized extended public key, implementations must verify whether the X coordinate in the public key data corresponds to a point on the curve. If not, the extended public key is invalid.

===Master key generation===

The total number of possible extended keypairs is almost 2^512, but the produced keys are only 256 bits long, and offer about half of that in terms of security. Therefore, master keys are not generated directly, but instead from a potentially short seed value.

* Generate a seed S of a chosen length (at least 128 bits, but 256 is advised) from a (P)RNG.
* Calculate I = HMAC-SHA512(key="Bitcoin seed", msg=S)
* Split I into two 32-byte sequences, IL and IR.
* Use IL (mod n) as master secret key, and IR as master chain code.
In case IL is 0 or >=n, the master key is invalid.

[[File:BIP32-derivation.png]]

==Specification: Wallet structure==

The previous sections specified key trees and their nodes. The next step is imposing a wallet structure on this tree. The layout defined in this section is a default only, though clients are encouraged to mimick it for compatibility, even if not all features are supported.

An HDW is organized as several 'accounts'. Accounts are numbered, the default account ("") being number 0. Clients are not required to support more than one account - if not, they only use the default account.

Each account is composed of two keypair chains: an internal and an external one. The external keychain is used to generate new public addresses, while the internal keychain is used for all other operations (change addresses, generation addresses, ..., anything that doesn't need to be communicated). Clients that do not support separate keychains for these should use the external one for everything.

* m/i'/0/k corresponds to the k'th keypair of the external chain of account number i of the HDW derived from master m.
* m/i'/1/k corresponds to the k'th keypair of the internal chain of account number i of the HDW derived from master m.

===Use cases===

====Full wallet sharing: m====

In cases where two systems need to access a single shared wallet, and both need to be able to perform spendings, one needs to share the master private extended key. Nodes can keep a pool of N look-ahead keys cached for external chains, to watch for incoming payments. The look-ahead for internal chains can be very small, as no gaps are to be expected here. An extra look-ahead could be active for the first unused account's chains - triggering the creation of a new account when used. Note that the name of the account will still need to be entered manually and cannot be synchronized via the block chain.

====Audits: M====

In case an auditor needs full access to the list of incoming and outgoing payments, one can share the master public extended key. This will allow the auditor to see all transactions from and to the wallet, in all accounts, but not a single secret key.

====Per-office balances: m/i'====

When a business has several independent offices, they can all use wallets derived from a single master. This will allow the headquarters to maintain a super-wallet that sees all incoming and outgoing transactions of all offices, and even permit moving money between the offices.

====Recurrent business-to-business transactions: M/i'/0====

In case two business partners often transfer money, one can use the extended public key for the external chain of a specific account (M/i'/0) as a sort of "super address", allowing frequent transactions that cannot (easily) be associated, but without needing to request a new address for each payment.
Such a mechanism could also be used by mining pool operators as variable payout address.

====Unsecure money receiver: M/i'/0====

When an unsecure webserver is used to run an e-commerce site, it needs to know public addresses that be used to receive payments. The webserver only needs to know the public extended key of the external chain of a single account. This means someone illegally obtaining access to the webserver can at most see all incoming payments, but will not (trivially) be able to distinguish outgoing transactions, nor see payments received by other webservers if there are several ones.

==Compatibility==

To comply with this standard, a client must at least be able to import an extended public or private key, to give access to its direct descendants as wallet keys. The wallet structure (master/account/chain/subchain) presented in the second part of the specification is advisory only, but is suggested as a minimal structure for easy compatibility - even when no separate accounts or distinction between internal and external chains is made. However, implementations may deviate from it for specific needs; more complex applications may call for a more complex tree structure.

==Security==

In addition to the expectations from the EC public-key cryptography itself:
* Given a public key K, an attacker cannot find the corresponding private key more efficiently than by solving the EC discrete logarithm problem (assumed to require 2128 group operations).
the intended security properties of this standard are:
* Given a child extended private key (ki,ci) and the integer i, an attacker cannot find the parent private key kpar more efficiently than a 2256 brute force of HMAC-SHA512.
* Given any number (2 <= N <= 232-1) of (index, extended private key) tuples (ij,(pj,cj)), with distinct ij's, determining whether they are derived from a common parent extended private key (i.e., whether there exists a (ppar,cpar) such that for each j in [0..N-1] CKD((ppar,cpar),ij)=(pj,cj)), cannot be done more efficiently than a 2256 brute force of HMAC-SHA512.
Note however that the following properties does not exist:
* Given a parent extended public key (Kpar,cpar) and a child public key (Ki), it is hard to find i.
* Given a parent extended public key (Kpar,cpar) and a child private key (ki) using public derivation, it is hard to find kpar.

Private and public keys must be kept safe as usual. Leaking a private key means access to coins - leaking a public key can mean loss of privacy.

Somewhat more care must be taken regarding extended keys, as these correspond to an entire (sub)tree of keys. One weakness that may not be immediately obvious, is that knowledge of the extended public key + a private key descending from it is equivalent to knowing the extended private key (i.e., every private and public key) in case public derivation is used. This means that extended public keys must be treated more carefully than regular public keys. This is the reason why accounts at the first level of the default wallet layout use private derivation, so a leak of account-specific (or below) private key never risks compromising the master.

We rely on resistance against (partial) preimages in HMAC-SHA512 to prevent IL in key derivation and master key generation from being zero.

==Test Vectors==

I'll publish test vectors as soon as the specification is assumed to be final.

==Acknowledgements==

* Gregory Maxwell for the original idea of type-2 deterministic wallets, and many discussions about it.
* Alan Reiner for the implementation of this scheme in Armory, and the suggestions that followed from that.
* Mike Caldwell for the version bytes to obtain human-recognizable Base58 strings.

BIP 0032

2013-05-04T21:45:14Z

CodeShark: /* Child key derivation functions */

{{bip}}

<div style="color:red">
WARNING: please do not assume this specification is final.
</div>

RECENT CHANGES:
* [16 Apr 2013] Added private derivation for i >= 0x80000000 (less risk of parent private key leakage)
* [30 Apr 2013] Switched from multiplication by I_L to addition of I_L (faster, easier implementation)

<pre>
BIP: 32
Title: Hierarchical Deterministic Wallets
Author: Pieter Wuille
Status: Draft
Type: Informational
Created: 11-02-2012
</pre>

==Abstract==

This document describes hierarchical determinstic wallets (or "HD Wallets"): wallets which can be shared partially or entirely with different systems, each with or without the ability to spend coins.

The specification is intended to set a standard for deterministic wallets that can be interchanged between different clients. Although the wallets described here have many features, not all are required by supporting clients.

The specification consists of two parts. In a first part, a system for deriving a tree of keypairs from a single seed is presented. The second part demonstrates how to build a wallet structure on top of such a tree.

==Motivation==

The Bitcoin reference client uses randomly generated keys. In order to avoid the necessity for a backup after every transaction, (by default) 100 keys are cached in a pool of reserve keys. Still, these wallets are not intended to be shared and used on several systems simultaneously. They support hiding their private keys by using the wallet encrypt feature and not sharing the password, but such "neutered" wallets lose the power to generate public keys as well.

Deterministic wallets do not require such frequent backups, and elliptic curve mathematics permit schemes where one can calculate the public keys without revealing the private keys. This permits for example a webshop business to let its webserver generate a fresh addresses (public key hashes) for each order or for each customer, without giving the webserver access to the corresponding private keys (which are required for spending the received funds).

However, deterministic wallets typically consist of a single "chain" of keypairs. The fact that there is only one chain means that sharing a wallet happens on an all-or-nothing basis. However, in some cases one only wants some (public) keys to be shared and recoverable. In the example of a webshop, the webserver does not need access to all public keys of the merchant's wallet; only to those addresses which are used to receive customer's payments, and not for example the change addresses that are generated when the merchant spends money. Hierarchical deterministic wallets allow such selective sharing by supporting multiple keypair chains, derived from a single root.

==Specification: Key derivation==

===Conventions===

In the rest of this text we will assume the public key cryptography used in Bitcoin, namely elliptic curve cryptography using the field and curve parameters defined by secp256k1 (http://www.secg.org/index.php?action=secg,docs_secg). Variables below are either:
* integers modulo the order of the curve (referred to as n), serialized as 32 bytes, most significant byte first.
* coordinates of points on the curve, serialized as specified in SEC1 in compressed form: [0x02 or 0x03] + 32 byte x coordinate), where the header byte depends on the parity of the omitted y coordinate.
* byte sequences

Addition (+) of two coordinates is defined as application of the EC group operation. Multiplication (*) of an integer and a coordinate is defined as repeated application of the EC group operation. The generator element of the curve is called G. The public key K corresponding to the private key k is calculated as k*G. We do not distinguish between numbers or coordinates and their serialization as byte sequences.

===Extended keys===

In what follows, we will define a function that derives a number of child keys from a parent key. In order to prevent these from depending solely on the key itself, we extend both private and public keys first with an extra 256 bits of entropy. This extension, called the chain code, is identical for corresponding private and public keys, and consists of 32 bytes.

We represent an extended private key as (k,c), with k the normal private key, and c the chain code. An extended public key is represented as (K,c), with K the normal public key and c the chain code.

===Child key derivation functions===

We allow for two different types of derivation: public and private.
* Private derivation: knowledge of the private key kpar and cpar is required to compute both ki and Ki.
* Public derivation: knowledge of the public key Kpar and cpar suffices to compute Ki (but not ki).

We define the private and public child key derivation functions:
* CKD((kpar,cpar),i) → (ki,ci), defined for both private and public derivation.
* CKD'((Kpar,cpar),i) → (Ki,ci), defined only for public derivation.

We use the most significant bit of i to specify which type of derivation to use. i is encoded as a 32 bit unsigned integer, most significant byte first; '||' represents concatenation.

====Private child key derivation====

To define CKD((kpar,cpar),i) → (ki,ci):
* Check whether the highest bit (0x80000000) of i is set:
** If 1, private derivation is used: let I = HMAC-SHA512(Key=cpar, Data=0x00 || kpar || i) (The 0x00 makes sure the data being hashed aligns with the public version)
** If 0, public derivation is used: let I = HMAC-SHA512(Key=cpar, Data=kpar*G || i) (with Kpar = kpar*G, EC multiplication)
* Split I into two 32-byte sequences, IL and IR.
* ki = IL + kpar (mod n).
* ci = IR.
In case IL ≥ n, the resulting key is invalid, and one should proceed with the next value for i (note that this has a chance lower than 1 in 2127).

====Public child key derivation====

To define CKD'((Kpar,cpar),i) → (Ki,ci):
* Check whether the highest bit (0x80000000) of i is set:
** If 1, return error
** If 0, let I = HMAC-SHA512(Key=cpar, Data=Kpar || i)
* Split I into two 32-byte sequences, IL and IR.
* Ki = (IL + kpar)*G = IL*G + Kpar (EC operations).
* ci = IR.
In case IL ≥ n, the resulting key is invalid, and one should proceed with the next value for i.

Note that the extended public key corresponding to the evaluation of CKD(x,i) with public derivation (so with i < 0x80000000) is identical to the evaluation of CKD'(X,i), with X the extended public key corresponding to x. Symbolically, CKD(x,i)*G = CKD'(x*G,i). This implies that CKD' can be used to derive all public keys corresponding to the private keys that CKD would find. It cannot be used to retrieve the private keys, however.

The HMAC-SHA512 function is specified in [http://tools.ietf.org/html/rfc4231 RFC 4231].

===The key tree===

The next step is cascading several CKD constructions to build a tree. We start with one root, the master extended key m. By evaluating CKD(m,i) for several values of i, we get a number of first-degree derivative nodes. As each of these is again an extended key, CKD can be applied to those as well. To shorten notation, we will write CKD(CKD(CKD(m,0x8000003),0x2),0x5) as m/3'/2/5 now.

Each leaf node in the tree corresponds to an actual keypair, while the internal nodes correspond to the collection of keypairs that descends from them. The chain codes of the leaf nodes are ignored, and only their embedded private or public key is used. Because of this construction, knowing an extended private key allows reconstruction of all descendant private keys and public keys, and knowing an extended public keys allows reconstruction of all descendant public keys derived using public derivation.

===Key identifiers===

Extended keys can be identified by the Hash160 (RIPEMD160 after SHA256) of the serialized public key, ignoring the chain code. This corresponds exactly to the data used in traditional Bitcoin addresses. It is not advised to represent this data in base58 format though, as it may be interpreted as an address that way (and wallet software is not required to accept payment to the chain key itself).

The first 32 bits of the identifier are called the fingerprint.

===Serialization format===

Extended public and private keys are serialized as follows:
* 4 byte: version bytes (mainnet: 0x0488B21E public, 0x0488ADE4 private; testnet: 0x043587CF public, 0x04358394 private)
* 1 byte: depth: 0x00 for master nodes, 0x01 for level-1 descendants, ....
* 4 bytes: the fingerprint of the parent's key (0x00000000 if master key)
* 4 bytes: child number. This is the number i in xi = xpar/i, with xi the key being serialized. This is encoded in MSB order. (0x00000000 if master key)
* 32 bytes: the chain code
* 33 bytes: the public key or private key data (0x02 + X or 0x03 + X for public keys, 0x00 + k for private keys)

This 78 byte structure can be encoded like other Bitcoin data in Base58, by first adding 32 checksum bits (derived from the double SHA-256 checksum), and then converting to the Base58 representation. This results in a Base58-encoded string of up to 112 characters. Because of the choice of the version bytes, the Base58 representation will start with "xprv" or "xpub" on mainnet, "tprv" or "tpub" on testnet.

Note that the fingerprint of the parent only serves as a fast way to detect parent and child nodes in software, and software must be willing to deal with collisions. Internally, the full 160-bit identifier could be used.

When importing a serialized extended public key, implementations must verify whether the X coordinate in the public key data corresponds to a point on the curve. If not, the extended public key is invalid.

===Master key generation===

The total number of possible extended keypairs is almost 2^512, but the produced keys are only 256 bits long, and offer about half of that in terms of security. Therefore, master keys are not generated directly, but instead from a potentially short seed value.

* Generate a seed S of a chosen length (at least 128 bits, but 256 is advised) from a (P)RNG.
* Calculate I = HMAC-SHA512(key="Bitcoin seed", msg=S)
* Split I into two 32-byte sequences, IL and IR.
* Use IL (mod n) as master secret key, and IR as master chain code.
In case IL is 0 or >=n, the master key is invalid.

[[File:BIP32-derivation.png]]

==Specification: Wallet structure==

The previous sections specified key trees and their nodes. The next step is imposing a wallet structure on this tree. The layout defined in this section is a default only, though clients are encouraged to mimick it for compatibility, even if not all features are supported.

An HDW is organized as several 'accounts'. Accounts are numbered, the default account ("") being number 0. Clients are not required to support more than one account - if not, they only use the default account.

Each account is composed of two keypair chains: an internal and an external one. The external keychain is used to generate new public addresses, while the internal keychain is used for all other operations (change addresses, generation addresses, ..., anything that doesn't need to be communicated). Clients that do not support separate keychains for these should use the external one for everything.

* m/i'/0/k corresponds to the k'th keypair of the external chain of account number i of the HDW derived from master m.
* m/i'/1/k corresponds to the k'th keypair of the internal chain of account number i of the HDW derived from master m.

===Use cases===

====Full wallet sharing: m====

In cases where two systems need to access a single shared wallet, and both need to be able to perform spendings, one needs to share the master private extended key. Nodes can keep a pool of N look-ahead keys cached for external chains, to watch for incoming payments. The look-ahead for internal chains can be very small, as no gaps are to be expected here. An extra look-ahead could be active for the first unused account's chains - triggering the creation of a new account when used. Note that the name of the account will still need to be entered manually and cannot be synchronized via the block chain.

====Audits: M====

In case an auditor needs full access to the list of incoming and outgoing payments, one can share the master public extended key. This will allow the auditor to see all transactions from and to the wallet, in all accounts, but not a single secret key.

====Per-office balances: m/i'====

When a business has several independent offices, they can all use wallets derived from a single master. This will allow the headquarters to maintain a super-wallet that sees all incoming and outgoing transactions of all offices, and even permit moving money between the offices.

====Recurrent business-to-business transactions: M/i'/0====

In case two business partners often transfer money, one can use the extended public key for the external chain of a specific account (M/i'/0) as a sort of "super address", allowing frequent transactions that cannot (easily) be associated, but without needing to request a new address for each payment.
Such a mechanism could also be used by mining pool operators as variable payout address.

====Unsecure money receiver: M/i'/0====

When an unsecure webserver is used to run an e-commerce site, it needs to know public addresses that be used to receive payments. The webserver only needs to know the public extended key of the external chain of a single account. This means someone illegally obtaining access to the webserver can at most see all incoming payments, but will not (trivially) be able to distinguish outgoing transactions, nor see payments received by other webservers if there are several ones.

==Compatibility==

To comply with this standard, a client must at least be able to import an extended public or private key, to give access to its direct descendants as wallet keys. The wallet structure (master/account/chain/subchain) presented in the second part of the specification is advisory only, but is suggested as a minimal structure for easy compatibility - even when no separate accounts or distinction between internal and external chains is made. However, implementations may deviate from it for specific needs; more complex applications may call for a more complex tree structure.

==Security==

In addition to the expectations from the EC public-key cryptography itself:
* Given a public key K, an attacker cannot find the corresponding private key more efficiently than by solving the EC discrete logarithm problem (assumed to require 2128 group operations).
the intended security properties of this standard are:
* Given a child extended private key (ki,ci) and the integer i, an attacker cannot find the parent private key kpar more efficiently than a 2256 brute force of HMAC-SHA512.
* Given any number (2 <= N <= 232-1) of (index, extended private key) tuples (ij,(pj,cj)), with distinct ij's, determining whether they are derived from a common parent extended private key (i.e., whether there exists a (ppar,cpar) such that for each j in [0..N-1] CKD((ppar,cpar),ij)=(pj,cj)), cannot be done more efficiently than a 2256 brute force of HMAC-SHA512.
Note however that the following properties does not exist:
* Given a parent extended public key (Kpar,cpar) and a child public key (Ki), it is hard to find i.
* Given a parent extended public key (Kpar,cpar) and a child private key (ki) using public derivation, it is hard to find kpar.

Private and public keys must be kept safe as usual. Leaking a private key means access to coins - leaking a public key can mean loss of privacy.

Somewhat more care must be taken regarding extended keys, as these correspond to an entire (sub)tree of keys. One weakness that may not be immediately obvious, is that knowledge of the extended public key + a private key descending from it is equivalent to knowing the extended private key (i.e., every private and public key) in case public derivation is used. This means that extended public keys must be treated more carefully than regular public keys. This is the reason why accounts at the first level of the default wallet layout use private derivation, so a leak of account-specific (or below) private key never risks compromising the master.

We rely on resistance against (partial) preimages in HMAC-SHA512 to prevent IL in key derivation and master key generation from being zero.

==Test Vectors==

I'll publish test vectors as soon as the specification is assumed to be final.

==Acknowledgements==

* Gregory Maxwell for the original idea of type-2 deterministic wallets, and many discussions about it.
* Alan Reiner for the implementation of this scheme in Armory, and the suggestions that followed from that.
* Mike Caldwell for the version bytes to obtain human-recognizable Base58 strings.

BIP 0032

2013-05-04T21:05:07Z

CodeShark: /* Child key derivation functions */

{{bip}}

<div style="color:red">
WARNING: please do not assume this specification is final.
</div>

RECENT CHANGES:
* [16 Apr 2013] Added private derivation for i >= 0x80000000 (less risk of parent private key leakage)
* [30 Apr 2013] Switched from multiplication by I_L to addition of I_L (faster, easier implementation)

<pre>
BIP: 32
Title: Hierarchical Deterministic Wallets
Author: Pieter Wuille
Status: Draft
Type: Informational
Created: 11-02-2012
</pre>

==Abstract==

This document describes hierarchical determinstic wallets (or "HD Wallets"): wallets which can be shared partially or entirely with different systems, each with or without the ability to spend coins.

The specification is intended to set a standard for deterministic wallets that can be interchanged between different clients. Although the wallets described here have many features, not all are required by supporting clients.

The specification consists of two parts. In a first part, a system for deriving a tree of keypairs from a single seed is presented. The second part demonstrates how to build a wallet structure on top of such a tree.

==Motivation==

The Bitcoin reference client uses randomly generated keys. In order to avoid the necessity for a backup after every transaction, (by default) 100 keys are cached in a pool of reserve keys. Still, these wallets are not intended to be shared and used on several systems simultaneously. They support hiding their private keys by using the wallet encrypt feature and not sharing the password, but such "neutered" wallets lose the power to generate public keys as well.

Deterministic wallets do not require such frequent backups, and elliptic curve mathematics permit schemes where one can calculate the public keys without revealing the private keys. This permits for example a webshop business to let its webserver generate a fresh addresses (public key hashes) for each order or for each customer, without giving the webserver access to the corresponding private keys (which are required for spending the received funds).

However, deterministic wallets typically consist of a single "chain" of keypairs. The fact that there is only one chain means that sharing a wallet happens on an all-or-nothing basis. However, in some cases one only wants some (public) keys to be shared and recoverable. In the example of a webshop, the webserver does not need access to all public keys of the merchant's wallet; only to those addresses which are used to receive customer's payments, and not for example the change addresses that are generated when the merchant spends money. Hierarchical deterministic wallets allow such selective sharing by supporting multiple keypair chains, derived from a single root.

==Specification: Key derivation==

===Conventions===

In the rest of this text we will assume the public key cryptography used in Bitcoin, namely elliptic curve cryptography using the field and curve parameters defined by secp256k1 (http://www.secg.org/index.php?action=secg,docs_secg). Variables below are either:
* integers modulo the order of the curve (referred to as n), serialized as 32 bytes, most significant byte first.
* coordinates of points on the curve, serialized as specified in SEC1 in compressed form: [0x02 or 0x03] + 32 byte x coordinate), where the header byte depends on the parity of the omitted y coordinate.
* byte sequences

Addition (+) of two coordinates is defined as application of the EC group operation. Multiplication (*) of an integer and a coordinate is defined as repeated application of the EC group operation. The generator element of the curve is called G. The public key K corresponding to the private key k is calculated as k*G. We do not distinguish between numbers or coordinates and their serialization as byte sequences.

===Extended keys===

In what follows, we will define a function that derives a number of child keys from a parent key. In order to prevent these from depending solely on the key itself, we extend both private and public keys first with an extra 256 bits of entropy. This extension, called the chain code, is identical for corresponding private and public keys, and consists of 32 bytes.

We represent an extended private key as (k,c), with k the normal private key, and c the chain code. An extended public key is represented as (K,c), with K the normal public key and c the chain code.

===Child key derivation functions===

We allow for two different types of derivation: public and private.
* Private derivation: knowledge of the private key kpar and cpar is required to compute both ki and Ki.
* Public derivation: knowledge of the public key Kpar and cpar suffices to compute Ki (but not ki).

We define the private and public child key derivation functions:
* CKD((kpar,cpar),i) → (ki,ci), defined for both private and public derivation.
* CKD'((Kpar,cpar),i) → (Ki,ci), defined only for public derivation.

We use the most significant bit of i to specify which type of derivation to use. i is encoded as a 32 bits unsigned integer, most significant byte first; '||' represents concatenation.

====Private child key derivation====

To define CKD((kpar,cpar),i) → (ki,ci):
* Check whether the highest bit (0x80000000) of i is set:
** If 1, private derivation is used: let I = HMAC-SHA512(Key=cpar, Data=0x00 || kpar || i) (The 0x00 makes sure the data being hashed aligns with the public version)
** If 0, public derivation is used: let I = HMAC-SHA512(Key=cpar, Data=kpar*G || i) (with Kpar = kpar*G, EC multiplication)
* Split I into two 32-byte sequences, IL and IR.
* ki = IL + kpar (mod n).
* ci = IR.
In case IL ≥ n, the resulting key is invalid, and one should proceed with the next value for i (note that this has a chance lower than 1 in 2127).

====Public child key derivation====

To define CKD'((Kpar,cpar),i) → (Ki,ci):
* Check whether the highest bit (0x80000000) of i is set:
** If 1, return error
** If 0, let I = HMAC-SHA512(Key=cpar, Data=Kpar || i)
* Split I into two 32-byte sequences, IL and IR.
* Ki = (IL + kpar)*G = IL*G + Kpar (EC operations).
* ci = IR.
In case IL ≥ n, the resulting key is invalid, and one should proceed with the next value for i.

Note that the extended public key corresponding to the evaluation of CKD(x,i) with public derivation (so with i < 0x80000000) is identical to the evaluation of CKD'(X,i), with X the extended public key corresponding to x. Symbolically, CKD(x,i)*G = CKD'(x*G,i). This implies that CKD' can be used to derive all public keys corresponding to the private keys that CKD would find. It cannot be used to retrieve the private keys, however.

The HMAC-SHA512 function is specified in [http://tools.ietf.org/html/rfc4231 RFC 4231].

===The key tree===

The next step is cascading several CKD constructions to build a tree. We start with one root, the master extended key m. By evaluating CKD(m,i) for several values of i, we get a number of first-degree derivative nodes. As each of these is again an extended key, CKD can be applied to those as well. To shorten notation, we will write CKD(CKD(CKD(m,0x8000003),0x2),0x5) as m/3'/2/5 now.

Each leaf node in the tree corresponds to an actual keypair, while the internal nodes correspond to the collection of keypairs that descends from them. The chain codes of the leaf nodes are ignored, and only their embedded private or public key is used. Because of this construction, knowing an extended private key allows reconstruction of all descendant private keys and public keys, and knowing an extended public keys allows reconstruction of all descendant public keys derived using public derivation.

===Key identifiers===

Extended keys can be identified by the Hash160 (RIPEMD160 after SHA256) of the serialized public key, ignoring the chain code. This corresponds exactly to the data used in traditional Bitcoin addresses. It is not advised to represent this data in base58 format though, as it may be interpreted as an address that way (and wallet software is not required to accept payment to the chain key itself).

The first 32 bits of the identifier are called the fingerprint.

===Serialization format===

Extended public and private keys are serialized as follows:
* 4 byte: version bytes (mainnet: 0x0488B21E public, 0x0488ADE4 private; testnet: 0x043587CF public, 0x04358394 private)
* 1 byte: depth: 0x00 for master nodes, 0x01 for level-1 descendants, ....
* 4 bytes: the fingerprint of the parent's key (0x00000000 if master key)
* 4 bytes: child number. This is the number i in xi = xpar/i, with xi the key being serialized. This is encoded in MSB order. (0x00000000 if master key)
* 32 bytes: the chain code
* 33 bytes: the public key or private key data (0x02 + X or 0x03 + X for public keys, 0x00 + k for private keys)

This 78 byte structure can be encoded like other Bitcoin data in Base58, by first adding 32 checksum bits (derived from the double SHA-256 checksum), and then converting to the Base58 representation. This results in a Base58-encoded string of up to 112 characters. Because of the choice of the version bytes, the Base58 representation will start with "xprv" or "xpub" on mainnet, "tprv" or "tpub" on testnet.

Note that the fingerprint of the parent only serves as a fast way to detect parent and child nodes in software, and software must be willing to deal with collisions. Internally, the full 160-bit identifier could be used.

When importing a serialized extended public key, implementations must verify whether the X coordinate in the public key data corresponds to a point on the curve. If not, the extended public key is invalid.

===Master key generation===

The total number of possible extended keypairs is almost 2^512, but the produced keys are only 256 bits long, and offer about half of that in terms of security. Therefore, master keys are not generated directly, but instead from a potentially short seed value.

* Generate a seed S of a chosen length (at least 128 bits, but 256 is advised) from a (P)RNG.
* Calculate I = HMAC-SHA512(key="Bitcoin seed", msg=S)
* Split I into two 32-byte sequences, IL and IR.
* Use IL (mod n) as master secret key, and IR as master chain code.
In case IL is 0 or >=n, the master key is invalid.

[[File:BIP32-derivation.png]]

==Specification: Wallet structure==

The previous sections specified key trees and their nodes. The next step is imposing a wallet structure on this tree. The layout defined in this section is a default only, though clients are encouraged to mimick it for compatibility, even if not all features are supported.

An HDW is organized as several 'accounts'. Accounts are numbered, the default account ("") being number 0. Clients are not required to support more than one account - if not, they only use the default account.

Each account is composed of two keypair chains: an internal and an external one. The external keychain is used to generate new public addresses, while the internal keychain is used for all other operations (change addresses, generation addresses, ..., anything that doesn't need to be communicated). Clients that do not support separate keychains for these should use the external one for everything.

* m/i'/0/k corresponds to the k'th keypair of the external chain of account number i of the HDW derived from master m.
* m/i'/1/k corresponds to the k'th keypair of the internal chain of account number i of the HDW derived from master m.

===Use cases===

====Full wallet sharing: m====

In cases where two systems need to access a single shared wallet, and both need to be able to perform spendings, one needs to share the master private extended key. Nodes can keep a pool of N look-ahead keys cached for external chains, to watch for incoming payments. The look-ahead for internal chains can be very small, as no gaps are to be expected here. An extra look-ahead could be active for the first unused account's chains - triggering the creation of a new account when used. Note that the name of the account will still need to be entered manually and cannot be synchronized via the block chain.

====Audits: M====

In case an auditor needs full access to the list of incoming and outgoing payments, one can share the master public extended key. This will allow the auditor to see all transactions from and to the wallet, in all accounts, but not a single secret key.

====Per-office balances: m/i'====

When a business has several independent offices, they can all use wallets derived from a single master. This will allow the headquarters to maintain a super-wallet that sees all incoming and outgoing transactions of all offices, and even permit moving money between the offices.

====Recurrent business-to-business transactions: M/i'/0====

In case two business partners often transfer money, one can use the extended public key for the external chain of a specific account (M/i'/0) as a sort of "super address", allowing frequent transactions that cannot (easily) be associated, but without needing to request a new address for each payment.
Such a mechanism could also be used by mining pool operators as variable payout address.

====Unsecure money receiver: M/i'/0====

When an unsecure webserver is used to run an e-commerce site, it needs to know public addresses that be used to receive payments. The webserver only needs to know the public extended key of the external chain of a single account. This means someone illegally obtaining access to the webserver can at most see all incoming payments, but will not (trivially) be able to distinguish outgoing transactions, nor see payments received by other webservers if there are several ones.

==Compatibility==

To comply with this standard, a client must at least be able to import an extended public or private key, to give access to its direct descendants as wallet keys. The wallet structure (master/account/chain/subchain) presented in the second part of the specification is advisory only, but is suggested as a minimal structure for easy compatibility - even when no separate accounts or distinction between internal and external chains is made. However, implementations may deviate from it for specific needs; more complex applications may call for a more complex tree structure.

==Security==

In addition to the expectations from the EC public-key cryptography itself:
* Given a public key K, an attacker cannot find the corresponding private key more efficiently than by solving the EC discrete logarithm problem (assumed to require 2128 group operations).
the intended security properties of this standard are:
* Given a child extended private key (ki,ci) and the integer i, an attacker cannot find the parent private key kpar more efficiently than a 2256 brute force of HMAC-SHA512.
* Given any number (2 <= N <= 232-1) of (index, extended private key) tuples (ij,(pj,cj)), with distinct ij's, determining whether they are derived from a common parent extended private key (i.e., whether there exists a (ppar,cpar) such that for each j in [0..N-1] CKD((ppar,cpar),ij)=(pj,cj)), cannot be done more efficiently than a 2256 brute force of HMAC-SHA512.
Note however that the following properties does not exist:
* Given a parent extended public key (Kpar,cpar) and a child public key (Ki), it is hard to find i.
* Given a parent extended public key (Kpar,cpar) and a child private key (ki) using public derivation, it is hard to find kpar.

Private and public keys must be kept safe as usual. Leaking a private key means access to coins - leaking a public key can mean loss of privacy.

Somewhat more care must be taken regarding extended keys, as these correspond to an entire (sub)tree of keys. One weakness that may not be immediately obvious, is that knowledge of the extended public key + a private key descending from it is equivalent to knowing the extended private key (i.e., every private and public key) in case public derivation is used. This means that extended public keys must be treated more carefully than regular public keys. This is the reason why accounts at the first level of the default wallet layout use private derivation, so a leak of account-specific (or below) private key never risks compromising the master.

We rely on resistance against (partial) preimages in HMAC-SHA512 to prevent IL in key derivation and master key generation from being zero.

==Test Vectors==

I'll publish test vectors as soon as the specification is assumed to be final.

==Acknowledgements==

* Gregory Maxwell for the original idea of type-2 deterministic wallets, and many discussions about it.
* Alan Reiner for the implementation of this scheme in Armory, and the suggestions that followed from that.
* Mike Caldwell for the version bytes to obtain human-recognizable Base58 strings.

BIP 0032

2013-05-04T20:58:54Z

CodeShark: Clarification on the distinction between public and private derivation.

{{bip}}

<div style="color:red">
WARNING: please do not assume this specification is final.
</div>

RECENT CHANGES:
* [16 Apr 2013] Added private derivation for i >= 0x80000000 (less risk of parent private key leakage)
* [30 Apr 2013] Switched from multiplication by I_L to addition of I_L (faster, easier implementation)

<pre>
BIP: 32
Title: Hierarchical Deterministic Wallets
Author: Pieter Wuille
Status: Draft
Type: Informational
Created: 11-02-2012
</pre>

==Abstract==

This document describes hierarchical determinstic wallets (or "HD Wallets"): wallets which can be shared partially or entirely with different systems, each with or without the ability to spend coins.

The specification is intended to set a standard for deterministic wallets that can be interchanged between different clients. Although the wallets described here have many features, not all are required by supporting clients.

The specification consists of two parts. In a first part, a system for deriving a tree of keypairs from a single seed is presented. The second part demonstrates how to build a wallet structure on top of such a tree.

==Motivation==

The Bitcoin reference client uses randomly generated keys. In order to avoid the necessity for a backup after every transaction, (by default) 100 keys are cached in a pool of reserve keys. Still, these wallets are not intended to be shared and used on several systems simultaneously. They support hiding their private keys by using the wallet encrypt feature and not sharing the password, but such "neutered" wallets lose the power to generate public keys as well.

Deterministic wallets do not require such frequent backups, and elliptic curve mathematics permit schemes where one can calculate the public keys without revealing the private keys. This permits for example a webshop business to let its webserver generate a fresh addresses (public key hashes) for each order or for each customer, without giving the webserver access to the corresponding private keys (which are required for spending the received funds).

However, deterministic wallets typically consist of a single "chain" of keypairs. The fact that there is only one chain means that sharing a wallet happens on an all-or-nothing basis. However, in some cases one only wants some (public) keys to be shared and recoverable. In the example of a webshop, the webserver does not need access to all public keys of the merchant's wallet; only to those addresses which are used to receive customer's payments, and not for example the change addresses that are generated when the merchant spends money. Hierarchical deterministic wallets allow such selective sharing by supporting multiple keypair chains, derived from a single root.

==Specification: Key derivation==

===Conventions===

In the rest of this text we will assume the public key cryptography used in Bitcoin, namely elliptic curve cryptography using the field and curve parameters defined by secp256k1 (http://www.secg.org/index.php?action=secg,docs_secg). Variables below are either:
* integers modulo the order of the curve (referred to as n), serialized as 32 bytes, most significant byte first.
* coordinates of points on the curve, serialized as specified in SEC1 in compressed form: [0x02 or 0x03] + 32 byte x coordinate), where the header byte depends on the parity of the omitted y coordinate.
* byte sequences

Addition (+) of two coordinates is defined as application of the EC group operation. Multiplication (*) of an integer and a coordinate is defined as repeated application of the EC group operation. The generator element of the curve is called G. The public key K corresponding to the private key k is calculated as k*G. We do not distinguish between numbers or coordinates and their serialization as byte sequences.

===Extended keys===

In what follows, we will define a function that derives a number of child keys from a parent key. In order to prevent these from depending solely on the key itself, we extend both private and public keys first with an extra 256 bits of entropy. This extension, called the chain code, is identical for corresponding private and public keys, and consists of 32 bytes.

We represent an extended private key as (k,c), with k the normal private key, and c the chain code. An extended public key is represented as (K,c), with K the normal public key and c the chain code.

===Child key derivation function===

We allow for two different types of derivation: public and private.
* Private derivation: knowledge of the private key kpar and cpar is required to compute both ki and Ki.
* Public derivation: knowledge of the public key Kpar and cpar suffices to compute Ki (but not ki).

We define the private and public child key derivation functions:
* CKD((kpar,cpar),i) → (ki,ci), defined for both private and public derivation.
* CKD'((Kpar,cpar),i) → (Ki,ci), defined only for public derivation.

We use the most significant bit of i to specify which type of derivation to use. i is encoded as a 32 bits unsigned integer, most significant byte first; '||' represents concatenation.

====Private child key derivation====

To define CKD((kpar,cpar),i) → (ki,ci):
* Check whether the highest bit (0x80000000) of i is set:
** If 1, private derivation is used: let I = HMAC-SHA512(Key=cpar, Data=0x00 || kpar || i) (The 0x00 makes sure the data being hashed aligns with the public version)
** If 0, public derivation is used: let I = HMAC-SHA512(Key=cpar, Data=kpar*G || i) (with Kpar = kpar*G, EC multiplication)
* Split I into two 32-byte sequences, IL and IR.
* ki = IL + kpar (mod n).
* ci = IR.
In case IL ≥ n, the resulting key is invalid, and one should proceed with the next value for i (note that this has a chance lower than 1 in 2127).

====Public child key derivation====

To define CKD'((Kpar,cpar),i) → (Ki,ci):
* Check whether the highest bit (0x80000000) of i is set:
** If 1, return error
** If 0, let I = HMAC-SHA512(Key=cpar, Data=Kpar || i)
* Split I into two 32-byte sequences, IL and IR.
* Ki = (IL + kpar)*G = IL*G + Kpar (EC operations).
* ci = IR.
In case IL ≥ n, the resulting key is invalid, and one should proceed with the next value for i.

Note that the extended public key corresponding to the evaluation of CKD(x,i) with public derivation (so with i < 0x80000000) is identical to the evaluation of CKD'(X,i), with X the extended public key corresponding to x. Symbolically, CKD(x,i)*G = CKD'(x*G,i). This implies that CKD' can be used to derive all public keys corresponding to the private keys that CKD would find. It cannot be used to retrieve the private keys, however.

The HMAC-SHA512 function is specified in [http://tools.ietf.org/html/rfc4231 RFC 4231].

===The key tree===

The next step is cascading several CKD constructions to build a tree. We start with one root, the master extended key m. By evaluating CKD(m,i) for several values of i, we get a number of first-degree derivative nodes. As each of these is again an extended key, CKD can be applied to those as well. To shorten notation, we will write CKD(CKD(CKD(m,0x8000003),0x2),0x5) as m/3'/2/5 now.

Each leaf node in the tree corresponds to an actual keypair, while the internal nodes correspond to the collection of keypairs that descends from them. The chain codes of the leaf nodes are ignored, and only their embedded private or public key is used. Because of this construction, knowing an extended private key allows reconstruction of all descendant private keys and public keys, and knowing an extended public keys allows reconstruction of all descendant public keys derived using public derivation.

===Key identifiers===

Extended keys can be identified by the Hash160 (RIPEMD160 after SHA256) of the serialized public key, ignoring the chain code. This corresponds exactly to the data used in traditional Bitcoin addresses. It is not advised to represent this data in base58 format though, as it may be interpreted as an address that way (and wallet software is not required to accept payment to the chain key itself).

The first 32 bits of the identifier are called the fingerprint.

===Serialization format===

Extended public and private keys are serialized as follows:
* 4 byte: version bytes (mainnet: 0x0488B21E public, 0x0488ADE4 private; testnet: 0x043587CF public, 0x04358394 private)
* 1 byte: depth: 0x00 for master nodes, 0x01 for level-1 descendants, ....
* 4 bytes: the fingerprint of the parent's key (0x00000000 if master key)
* 4 bytes: child number. This is the number i in xi = xpar/i, with xi the key being serialized. This is encoded in MSB order. (0x00000000 if master key)
* 32 bytes: the chain code
* 33 bytes: the public key or private key data (0x02 + X or 0x03 + X for public keys, 0x00 + k for private keys)

This 78 byte structure can be encoded like other Bitcoin data in Base58, by first adding 32 checksum bits (derived from the double SHA-256 checksum), and then converting to the Base58 representation. This results in a Base58-encoded string of up to 112 characters. Because of the choice of the version bytes, the Base58 representation will start with "xprv" or "xpub" on mainnet, "tprv" or "tpub" on testnet.

Note that the fingerprint of the parent only serves as a fast way to detect parent and child nodes in software, and software must be willing to deal with collisions. Internally, the full 160-bit identifier could be used.

When importing a serialized extended public key, implementations must verify whether the X coordinate in the public key data corresponds to a point on the curve. If not, the extended public key is invalid.

===Master key generation===

The total number of possible extended keypairs is almost 2^512, but the produced keys are only 256 bits long, and offer about half of that in terms of security. Therefore, master keys are not generated directly, but instead from a potentially short seed value.

* Generate a seed S of a chosen length (at least 128 bits, but 256 is advised) from a (P)RNG.
* Calculate I = HMAC-SHA512(key="Bitcoin seed", msg=S)
* Split I into two 32-byte sequences, IL and IR.
* Use IL (mod n) as master secret key, and IR as master chain code.
In case IL is 0 or >=n, the master key is invalid.

[[File:BIP32-derivation.png]]

==Specification: Wallet structure==

The previous sections specified key trees and their nodes. The next step is imposing a wallet structure on this tree. The layout defined in this section is a default only, though clients are encouraged to mimick it for compatibility, even if not all features are supported.

An HDW is organized as several 'accounts'. Accounts are numbered, the default account ("") being number 0. Clients are not required to support more than one account - if not, they only use the default account.

Each account is composed of two keypair chains: an internal and an external one. The external keychain is used to generate new public addresses, while the internal keychain is used for all other operations (change addresses, generation addresses, ..., anything that doesn't need to be communicated). Clients that do not support separate keychains for these should use the external one for everything.

* m/i'/0/k corresponds to the k'th keypair of the external chain of account number i of the HDW derived from master m.
* m/i'/1/k corresponds to the k'th keypair of the internal chain of account number i of the HDW derived from master m.

===Use cases===

====Full wallet sharing: m====

In cases where two systems need to access a single shared wallet, and both need to be able to perform spendings, one needs to share the master private extended key. Nodes can keep a pool of N look-ahead keys cached for external chains, to watch for incoming payments. The look-ahead for internal chains can be very small, as no gaps are to be expected here. An extra look-ahead could be active for the first unused account's chains - triggering the creation of a new account when used. Note that the name of the account will still need to be entered manually and cannot be synchronized via the block chain.

====Audits: M====

In case an auditor needs full access to the list of incoming and outgoing payments, one can share the master public extended key. This will allow the auditor to see all transactions from and to the wallet, in all accounts, but not a single secret key.

====Per-office balances: m/i'====

When a business has several independent offices, they can all use wallets derived from a single master. This will allow the headquarters to maintain a super-wallet that sees all incoming and outgoing transactions of all offices, and even permit moving money between the offices.

====Recurrent business-to-business transactions: M/i'/0====

In case two business partners often transfer money, one can use the extended public key for the external chain of a specific account (M/i'/0) as a sort of "super address", allowing frequent transactions that cannot (easily) be associated, but without needing to request a new address for each payment.
Such a mechanism could also be used by mining pool operators as variable payout address.

====Unsecure money receiver: M/i'/0====

When an unsecure webserver is used to run an e-commerce site, it needs to know public addresses that be used to receive payments. The webserver only needs to know the public extended key of the external chain of a single account. This means someone illegally obtaining access to the webserver can at most see all incoming payments, but will not (trivially) be able to distinguish outgoing transactions, nor see payments received by other webservers if there are several ones.

==Compatibility==

To comply with this standard, a client must at least be able to import an extended public or private key, to give access to its direct descendants as wallet keys. The wallet structure (master/account/chain/subchain) presented in the second part of the specification is advisory only, but is suggested as a minimal structure for easy compatibility - even when no separate accounts or distinction between internal and external chains is made. However, implementations may deviate from it for specific needs; more complex applications may call for a more complex tree structure.

==Security==

In addition to the expectations from the EC public-key cryptography itself:
* Given a public key K, an attacker cannot find the corresponding private key more efficiently than by solving the EC discrete logarithm problem (assumed to require 2128 group operations).
the intended security properties of this standard are:
* Given a child extended private key (ki,ci) and the integer i, an attacker cannot find the parent private key kpar more efficiently than a 2256 brute force of HMAC-SHA512.
* Given any number (2 <= N <= 232-1) of (index, extended private key) tuples (ij,(pj,cj)), with distinct ij's, determining whether they are derived from a common parent extended private key (i.e., whether there exists a (ppar,cpar) such that for each j in [0..N-1] CKD((ppar,cpar),ij)=(pj,cj)), cannot be done more efficiently than a 2256 brute force of HMAC-SHA512.
Note however that the following properties does not exist:
* Given a parent extended public key (Kpar,cpar) and a child public key (Ki), it is hard to find i.
* Given a parent extended public key (Kpar,cpar) and a child private key (ki) using public derivation, it is hard to find kpar.

Private and public keys must be kept safe as usual. Leaking a private key means access to coins - leaking a public key can mean loss of privacy.

Somewhat more care must be taken regarding extended keys, as these correspond to an entire (sub)tree of keys. One weakness that may not be immediately obvious, is that knowledge of the extended public key + a private key descending from it is equivalent to knowing the extended private key (i.e., every private and public key) in case public derivation is used. This means that extended public keys must be treated more carefully than regular public keys. This is the reason why accounts at the first level of the default wallet layout use private derivation, so a leak of account-specific (or below) private key never risks compromising the master.

We rely on resistance against (partial) preimages in HMAC-SHA512 to prevent IL in key derivation and master key generation from being zero.

==Test Vectors==

I'll publish test vectors as soon as the specification is assumed to be final.

==Acknowledgements==

* Gregory Maxwell for the original idea of type-2 deterministic wallets, and many discussions about it.
* Alan Reiner for the implementation of this scheme in Armory, and the suggestions that followed from that.
* Mike Caldwell for the version bytes to obtain human-recognizable Base58 strings.

Pooled mining

2013-03-18T21:15:50Z

CodeShark: /* Luke-Jr's approach ("Eligius") */

'''Pooled mining''' is a [[Mining|mining]] approach where multiple generating clients contribute to the generation of a block, and then split the block reward according the contributed processing power. Pooled mining effectively reduces the granularity of the block generation reward, spreading it out more smoothly over time.

==Introduction==

With increasing generation difficulty, mining with lower-performance devices can take a very long time before block generation, on average. For example, with a mining speed of 1000 Khps, at a difficulty of 14484 (which was in effect at the end of December, 2010), the average time to generate a block is almost 2 years.

To provide a more smooth incentive to lower-performance miners, several pooled miners, using different approaches, have been created. With a mining pool, a lot of different people contribute to generating a block, and the reward is then split among them according to their processing contribution. This way, instead of waiting for years to generate 50btc in a block, a smaller miner may get a fraction of a bitcoin on a more regular basis.

A '''share''' is awarded by the mining pool to the clients who present a valid [[proof of work]] of the same type as the proof of work that is used for creating [[block|blocks]], but of lesser difficulty, so that it requires less time on average to generate.

==Pooled mining approaches==

The problem with pooled mining is that steps must be taken to prevent cheating by the clients and the server. Currently there are several different approaches used.

===The slush approach===

[[Bitcoin Pooled Mining]] (BPM), sometimes referred to as "slush's pool", follows a score-based method. Older shares (from beginning of the round) have lower weight than more recent shares, which reduces the motivation to cheat by switching between pools within a round.

===The puddinpop approach===

(As of February, 2011, there are no puddinpop pools running.)

Another approach is the 'metahash' technique, used by puddinpop's [[remote miner]]. Clients generate hashes, and also submit 'metahashes', which are hashes of a large chunk of generated hashes. The server checks that the metahashes are correct (in a round-robin fashion, picking up a metahash from a client that hasn't been checked on the longest), thus preventing clients from simply claiming that they have done work without actually doing it. The withholding of good blocks by the clients is prevented by the server's possession of the private key, just as in the previous approach. Rewards are distributed based on the number of metahashes submitted by the clients.

The generated blocks contain multiple keys in the generation transaction, giving fractional bitcoin amounts to each key in proportion to their hashing contribution for that block.

===The Pay-per-Share approach===

The Pay-per-Share (PPS) approach, first described by [[BitPenny]], is to offer an instant flat payout for each share that is solved. The payout is offered from the pool's existing balance and can therefore be withdrawn immediately, without waiting for a block to be solved or confirmed. The possibility of cheating the miners by the pool operator and by timing attacks is thus completely eliminated.

This method results in the least possible variance for miners while transferring all risk to the pool operator. The resulting possibility of loss for the server is offset by setting a payout lower than the full expected value.

===Luke-Jr's approach ("[[Eligius]]")===
[[User:Luke-Jr|Luke]] came up with a third approach borrowing strengths from the earlier two.
Like slush's approach, miners submit proofs-of-work to earn shares.
Like puddinpop's approach, the pool pays out immediately via block generation.
When distributing block rewards, it is divided equally among all shares since the last valid block.
Unlike any preexisting pool approach, this means that the shares contributed toward stale blocks are recycled into the next block's shares.
In order to spare participating miners from transaction fees, rewards are only paid out if a miner has earned at least 0.67108864 BTC (400 [[Tonal Bitcoin|TBC]]). If the amount owed is less, it will be added to the earnings of a later block (which may then total over the threshold amount).
If a miner does not submit a share for over a week, the pool sends any balance remaining, regardless of its size.

===The Triplemining approach===
The [[Triplemining]] approach is to bring together a medium-sized pool with no fees and clever redistribution of 1% of every found block to allow your share to grow more rapidly than on any other bitcoin mining pool.

For every found block, Triplemining redistributes 1% of the profits to all minipool owners (people with 1 or more friends mining with them). The redistribution is connected to the shares found by the members of the minipool. So if the hash rate of the minipool members equals or is bigger than yours, the part in the redistribution will be equally bigger.

===P2Pool approach===

[[P2Pool]] mining nodes work on a chain of shares similar to Bitcoin’s blockchain. When a block is found, the reward is divided among the most recent shares in this share-blockchain. Like the puddinpop and Luke-Jr approaches, p2pool pays via generation.

===Comparison===

The cooperative mining approach (slush and Luke-Jr) uses a lot less resources on the pool server, since rather than continuously checking metahashes, all that has to be checked is the validity of submitted shares. The number of shares sent can be adjusted by adjusting the artificial difficulty level.

Further, the cooperative mining approach allows the clients to use existing miners without any modification, while the puddinpop approach requires the custom pool miner, which are as of now not as efficient on GPU mining as the existing GPU miners.
[[File:Smallgeneration.png|thumb|Puddinpop miners receive coins directly.]]

Additionally, the puddinpop and Luke-Jr approaches of distributing the earnings by way of including precise sub-cent amounts in the generation transaction for the participants, results in the presence of sub-cent bitcoin amounts in your wallet, which are liable to disappear (as unnecessary fees) later due to a bug in old (before 0.3.21) bitcoin nodes. (E.g., if you have a transaction with 0.052 in your wallet, and you later send .05 to someone, your .002 will disappear.).

Puddinpop and Luke-Jr miners receive coins directly, which eliminates the delay in receiving earnings that is required on slush-based mining servers. However, using some [[eWallet]] services for generated coin will cause those coins to be lost.

==See Also==

* [[:Category:Miners|Miners]]
* [[Poolservers]]
* [[Comparison of mining pools]]
* [[:Category:Pool Operators|Pool Operators]]
* [[Why a GPU mines faster than a CPU]]
* [[Why pooled mining]]
* [[Mining pool reward FAQ]]

==External links==
* [http://btcserv.net BTCSERV.net - Bitcoin Pool]
* [http://21bitcoin.com/pool/ 21bitcoin mining pool, Chinese Interface]
* [http://mining.bitcoin.cz slush's mining pool]
* [http://www.bitcash.cz bitcash.cz - czech mining pool]
* [http://www.bitcoin.org/smf/index.php?topic=1458.0 puddinpop's mining pool thread]
* [http://blockexplorer.com/block/00000000000233334b157d901714baf59e5b9236227b2878844e52244da4195e example puddinpop block]
* [http://bitclockers.com bitclockers mining pool]
* [https://pool.itzod.ru pool.itzod.ru mining pool]
* [https://50btc.com 50btc.com mining pool]
* [http://forum.bitcoin.org/index.php?topic=18313 P2Pool forum]

==References==
<references />

[[Category:Mining]]

Base58Check encoding

2013-03-18T13:50:51Z

CodeShark: /* Encoding a Bitcoin address */

A modified Base 58 [http://en.wikipedia.org/wiki/Binary-to-text_encoding binary-to-text encoding] known as '''Base58Check''' is used for encoding [[Bitcoin address]]es.

More generically, Base58Check encoding is used for encoding byte arrays in Bitcoin into human-typable strings. A Bitcoin address is simply a Base58Check-encoded string with a 20-byte payload, the payload being the hash of the [[public key]] associated with the address.

The original Bitcoin client source code discusses the reasoning behind base58 encoding:

base58.h:
// Why base-58 instead of standard base-64 encoding?
// - Don't want 0OIl characters that look the same in some fonts and
// could be used to create visually identical looking account numbers.
// - A string with non-alphanumeric characters is not as easily accepted as an account number.
// - E-mail usually won't line-break if there's no punctuation to break at.
// - Doubleclicking selects the whole number as one word if it's all alphanumeric.

==Features of Base58Check==
Base58Check has the following features:
* An arbitrarily sized payload.
* A set of 58 alphanumeric symbols consisting of easily distinguished uppercase and lowercase letters (0OIl are not used)
* One byte of version/application information. Bitcoin addresses use 0x00 for this byte (future ones may use 0x05).
* Four bytes (32 bits) of SHA256-based error checking code. This code can be used to automatically detect and possibly correct typographical errors.
* An extra step for preservation of leading zeroes in the data.

==Creating a Base58Check string==
A Base58Check string is created from a version/application byte and payload as follows.
# Take the version/application byte and payload bytes, and concatenate them together (bytewise).
# Take the first four bytes of SHA256(SHA256(results of step 1))
# Concatenate the results of step 1 and the results of step 2 together (bytewise).
# Treating the results of step 3 - a series of bytes - as a single big-endian bignumber, convert to base-58 using normal mathematical steps (bignumber division) and the base-58 alphabet described below. The result should be normalized to not have any leading base-58 zeroes (character '1').
# The leading character '1', which has a value of zero in base58, is reserved for representing an entire leading zero '''byte''', as when it is in a leading position, has no value as a base-58 symbol. There can be one or more leading '1's when necessary to represent one or more leading zero bytes. Count the number of leading zero bytes that were the result of step 3 (for old Bitcoin addresses, there will always be at least one for the version/application byte; for new addresses, there will never be any). Each leading zero byte shall be represented by its own character '1' in the final result.
# Concatenate the 1's from step 5 with the results of step 4. '''This is the Base58Check result.'''

==Encoding a Bitcoin address==
A Bitcoin address is based on any [[ECDSA]] [[secp256k1]] public/private [[key pair]].

A Bitcoin address is the Base58Check encoding of the hash of the associated [[script]]. Specifically, it is Base58Check(version byte,[[RIPEMD160]]([[SHA256]]([[script]]))), with the following constraints:
* [[RIPEMD160]] and [[SHA256]] in this case are always exactly 20 and 32 unsigned bytes respectively. These are big-endian (most significant byte first). (Beware of [[bignumber]] implementations that clip leading 0x00 bytes, or prepend extra 0x00 bytes to indicate sign - your code must handle these cases properly or else you may generate valid-looking addresses which can be sent to, but cannot be spent from - which would lead to the permanent loss of coins.)
* version byte is 0x00 for pay-to-address, version byte is 0x05 for pay-to-script-hash.

Bitcoin addresses that use the version byte 0x00 start with the digit '1'. Bitcoin addresses that use the version byte 0x05 start with the digit '3'.

==Encoding a private key==
Base58Check encoding is also used for encoding [[private key]]s in the [[Wallet import format]]. This is formed exactly the same as a Bitcoin address, except that 0x80 is used for the version/application byte, and the payload is 32 bytes instead of 20 (a private key in Bitcoin is a single 32-byte unsigned big-endian integer). Such encodings will always yield a 51-character string that starts with '5', or more specifically, either '5H', '5J', or '5K'.

==Base58 symbol chart==
The Base58 symbol chart used in Bitcoin is specific to the Bitcoin project and is not intended to be the same as any other Base58 implementation used outside the context of Bitcoin.
{| class="wikitable"
|-
!Value
!Character
!Value
!Character
!Value
!Character
!Value
!Character
|-
|0
|1
|1
|2
|2
|3
|3
|4
|-
|4
|5
|5
|6
|6
|7
|7
|8
|-
|8
|9
|9
|A
|10
|B
|11
|C
|-
|12
|D
|13
|E
|14
|F
|15
|G
|-
|16
|H
|17
|J
|18
|K
|19
|L
|-
|20
|M
|21
|N
|22
|P
|23
|Q
|-
|24
|R
|25
|S
|26
|T
|27
|U
|-
|28
|V
|29
|W
|30
|X
|31
|Y
|-
|32
|Z
|33
|a
|34
|b
|35
|c
|-
|36
|d
|37
|e
|38
|f
|39
|g
|-
|40
|h
|41
|i
|42
|j
|43
|k
|-
|44
|m
|45
|n
|46
|o
|47
|p
|-
|48
|q
|49
|r
|50
|s
|51
|t
|-
|52
|u
|53
|v
|54
|w
|55
|x
|-
|56
|y
|57
|z
|}

The algorithm for encoding address_byte_string (consisting of 0x01 + hash + 4-byte_check_code) is

code_string = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
x = convert_bytes_to_big_integer(hash_result)

output_string = ""

while(x > 0)
{
(x, remainder) = divide(x, 58)
output_string.append(code_string[remainder])
}

repeat(number_of_leading_zero_bytes_in_hash)
{
output_string.append(code_string[0]);
}

output_string.reverse();

==Version bytes==
Here are some common version bytes:

{| class="wikitable"
|-
!Decimal version
!Leading symbol
!Use
|-
|0
|1
|Bitcoin pubkey hash
|-
|5
|3
|Bitcoin script hash
|-
|21
|4
|Bitcoin (compact) public key (proposed)
|-
|52
|M or N
|Namecoin pubkey hash
|-
|128
|5
|Private key
|-
|111
|m or n
|Bitcoin testnet pubkey hash
|-
|196
|2
|Bitcoin testnet script hash
|}
[[List of address prefixes]] is a more complete list.

== Source code ==
* [https://github.com/bitcoin/bitcoin/blob/master/src/base58.h "Satoshi" C++ codebase (encode/decode using BigNum library)]
* [https://gitorious.org/bitcoin/libblkmaker/blobs/master/base58.c libblkmaker C code (decode only, no external libraries needed)]

[[Category:Technical]]

[[es:Codificación Base58Check]]

Base58Check encoding

2013-03-18T13:50:28Z

CodeShark: /* Encoding a Bitcoin address */

A modified Base 58 [http://en.wikipedia.org/wiki/Binary-to-text_encoding binary-to-text encoding] known as '''Base58Check''' is used for encoding [[Bitcoin address]]es.

More generically, Base58Check encoding is used for encoding byte arrays in Bitcoin into human-typable strings. A Bitcoin address is simply a Base58Check-encoded string with a 20-byte payload, the payload being the hash of the [[public key]] associated with the address.

The original Bitcoin client source code discusses the reasoning behind base58 encoding:

base58.h:
// Why base-58 instead of standard base-64 encoding?
// - Don't want 0OIl characters that look the same in some fonts and
// could be used to create visually identical looking account numbers.
// - A string with non-alphanumeric characters is not as easily accepted as an account number.
// - E-mail usually won't line-break if there's no punctuation to break at.
// - Doubleclicking selects the whole number as one word if it's all alphanumeric.

==Features of Base58Check==
Base58Check has the following features:
* An arbitrarily sized payload.
* A set of 58 alphanumeric symbols consisting of easily distinguished uppercase and lowercase letters (0OIl are not used)
* One byte of version/application information. Bitcoin addresses use 0x00 for this byte (future ones may use 0x05).
* Four bytes (32 bits) of SHA256-based error checking code. This code can be used to automatically detect and possibly correct typographical errors.
* An extra step for preservation of leading zeroes in the data.

==Creating a Base58Check string==
A Base58Check string is created from a version/application byte and payload as follows.
# Take the version/application byte and payload bytes, and concatenate them together (bytewise).
# Take the first four bytes of SHA256(SHA256(results of step 1))
# Concatenate the results of step 1 and the results of step 2 together (bytewise).
# Treating the results of step 3 - a series of bytes - as a single big-endian bignumber, convert to base-58 using normal mathematical steps (bignumber division) and the base-58 alphabet described below. The result should be normalized to not have any leading base-58 zeroes (character '1').
# The leading character '1', which has a value of zero in base58, is reserved for representing an entire leading zero '''byte''', as when it is in a leading position, has no value as a base-58 symbol. There can be one or more leading '1's when necessary to represent one or more leading zero bytes. Count the number of leading zero bytes that were the result of step 3 (for old Bitcoin addresses, there will always be at least one for the version/application byte; for new addresses, there will never be any). Each leading zero byte shall be represented by its own character '1' in the final result.
# Concatenate the 1's from step 5 with the results of step 4. '''This is the Base58Check result.'''

==Encoding a Bitcoin address==
A Bitcoin address is based on any [[ECDSA]] [[secp256k1]] public/private [[key pair]].

A Bitcoin address is the Base58Check encoding of the hash of the associated [[script]]. Specifically, it is Base58Check(version byte,[[RIPEMD160]]([[SHA256]]([[script]]))), with the following constraints:
* [[RIPEMD160]] and [[SHA256]] in this case are always exactly 20 and 32 unsigned bytes respectively. These are big-endian (most significant byte first). (Beware of [[bignumber]] implementations that clip leading 0x00 bytes, or prepend extra 0x00 bytes to indicate sign - your code must handle these cases properly or else you may generate valid-looking addresses which can be sent to, but cannot be spent from - which would lead to the permanent loss of coins.)
* version byte is 0x00 for pay-to-address, version_byte is 0x05 for pay-to-script-hash.

Bitcoin addresses that use the version byte 0x00 start with the digit '1'. Bitcoin addresses that use the version byte 0x05 start with the digit '3'.

==Encoding a private key==
Base58Check encoding is also used for encoding [[private key]]s in the [[Wallet import format]]. This is formed exactly the same as a Bitcoin address, except that 0x80 is used for the version/application byte, and the payload is 32 bytes instead of 20 (a private key in Bitcoin is a single 32-byte unsigned big-endian integer). Such encodings will always yield a 51-character string that starts with '5', or more specifically, either '5H', '5J', or '5K'.

==Base58 symbol chart==
The Base58 symbol chart used in Bitcoin is specific to the Bitcoin project and is not intended to be the same as any other Base58 implementation used outside the context of Bitcoin.
{| class="wikitable"
|-
!Value
!Character
!Value
!Character
!Value
!Character
!Value
!Character
|-
|0
|1
|1
|2
|2
|3
|3
|4
|-
|4
|5
|5
|6
|6
|7
|7
|8
|-
|8
|9
|9
|A
|10
|B
|11
|C
|-
|12
|D
|13
|E
|14
|F
|15
|G
|-
|16
|H
|17
|J
|18
|K
|19
|L
|-
|20
|M
|21
|N
|22
|P
|23
|Q
|-
|24
|R
|25
|S
|26
|T
|27
|U
|-
|28
|V
|29
|W
|30
|X
|31
|Y
|-
|32
|Z
|33
|a
|34
|b
|35
|c
|-
|36
|d
|37
|e
|38
|f
|39
|g
|-
|40
|h
|41
|i
|42
|j
|43
|k
|-
|44
|m
|45
|n
|46
|o
|47
|p
|-
|48
|q
|49
|r
|50
|s
|51
|t
|-
|52
|u
|53
|v
|54
|w
|55
|x
|-
|56
|y
|57
|z
|}

The algorithm for encoding address_byte_string (consisting of 0x01 + hash + 4-byte_check_code) is

code_string = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
x = convert_bytes_to_big_integer(hash_result)

output_string = ""

while(x > 0)
{
(x, remainder) = divide(x, 58)
output_string.append(code_string[remainder])
}

repeat(number_of_leading_zero_bytes_in_hash)
{
output_string.append(code_string[0]);
}

output_string.reverse();

==Version bytes==
Here are some common version bytes:

{| class="wikitable"
|-
!Decimal version
!Leading symbol
!Use
|-
|0
|1
|Bitcoin pubkey hash
|-
|5
|3
|Bitcoin script hash
|-
|21
|4
|Bitcoin (compact) public key (proposed)
|-
|52
|M or N
|Namecoin pubkey hash
|-
|128
|5
|Private key
|-
|111
|m or n
|Bitcoin testnet pubkey hash
|-
|196
|2
|Bitcoin testnet script hash
|}
[[List of address prefixes]] is a more complete list.

== Source code ==
* [https://github.com/bitcoin/bitcoin/blob/master/src/base58.h "Satoshi" C++ codebase (encode/decode using BigNum library)]
* [https://gitorious.org/bitcoin/libblkmaker/blobs/master/base58.c libblkmaker C code (decode only, no external libraries needed)]

[[Category:Technical]]

[[es:Codificación Base58Check]]

Base58Check encoding

2013-03-18T13:47:24Z

CodeShark: /* Encoding a Bitcoin address */

A modified Base 58 [http://en.wikipedia.org/wiki/Binary-to-text_encoding binary-to-text encoding] known as '''Base58Check''' is used for encoding [[Bitcoin address]]es.

More generically, Base58Check encoding is used for encoding byte arrays in Bitcoin into human-typable strings. A Bitcoin address is simply a Base58Check-encoded string with a 20-byte payload, the payload being the hash of the [[public key]] associated with the address.

The original Bitcoin client source code discusses the reasoning behind base58 encoding:

base58.h:
// Why base-58 instead of standard base-64 encoding?
// - Don't want 0OIl characters that look the same in some fonts and
// could be used to create visually identical looking account numbers.
// - A string with non-alphanumeric characters is not as easily accepted as an account number.
// - E-mail usually won't line-break if there's no punctuation to break at.
// - Doubleclicking selects the whole number as one word if it's all alphanumeric.

==Features of Base58Check==
Base58Check has the following features:
* An arbitrarily sized payload.
* A set of 58 alphanumeric symbols consisting of easily distinguished uppercase and lowercase letters (0OIl are not used)
* One byte of version/application information. Bitcoin addresses use 0x00 for this byte (future ones may use 0x05).
* Four bytes (32 bits) of SHA256-based error checking code. This code can be used to automatically detect and possibly correct typographical errors.
* An extra step for preservation of leading zeroes in the data.

==Creating a Base58Check string==
A Base58Check string is created from a version/application byte and payload as follows.
# Take the version/application byte and payload bytes, and concatenate them together (bytewise).
# Take the first four bytes of SHA256(SHA256(results of step 1))
# Concatenate the results of step 1 and the results of step 2 together (bytewise).
# Treating the results of step 3 - a series of bytes - as a single big-endian bignumber, convert to base-58 using normal mathematical steps (bignumber division) and the base-58 alphabet described below. The result should be normalized to not have any leading base-58 zeroes (character '1').
# The leading character '1', which has a value of zero in base58, is reserved for representing an entire leading zero '''byte''', as when it is in a leading position, has no value as a base-58 symbol. There can be one or more leading '1's when necessary to represent one or more leading zero bytes. Count the number of leading zero bytes that were the result of step 3 (for old Bitcoin addresses, there will always be at least one for the version/application byte; for new addresses, there will never be any). Each leading zero byte shall be represented by its own character '1' in the final result.
# Concatenate the 1's from step 5 with the results of step 4. '''This is the Base58Check result.'''

==Encoding a Bitcoin address==
A Bitcoin address is based on any [[ECDSA]] [[secp256k1]] public/private [[key pair]].

A Bitcoin address is the Base58Check encoding of the hash of the associated [[script]]. Specifically, it is Base58Check(version_byte,[[RIPEMD160]]([[SHA256]]([[script]]))), with the following constraints:
* [[RIPEMD160]] and [[SHA256]] in this case are always exactly 20 and 32 unsigned bytes respectively. These are big-endian (most significant byte first). (Beware of [[bignumber]] implementations that clip leading 0x00 bytes, or prepend extra 0x00 bytes to indicate sign - your code must handle these cases properly or else you may generate valid-looking addresses which can be sent to, but cannot be spent from - which would lead to the permanent loss of coins.)
* version_byte is 0x00 for pay-to-address, version_byte is 0x05 for pay-to-script-hash.

Bitcoin addresses that use the version byte 0x00 start with the digit '1'. Bitcoin addresses that use the version byte 0x05 start with the digit '3'.

==Encoding a private key==
Base58Check encoding is also used for encoding [[private key]]s in the [[Wallet import format]]. This is formed exactly the same as a Bitcoin address, except that 0x80 is used for the version/application byte, and the payload is 32 bytes instead of 20 (a private key in Bitcoin is a single 32-byte unsigned big-endian integer). Such encodings will always yield a 51-character string that starts with '5', or more specifically, either '5H', '5J', or '5K'.

==Base58 symbol chart==
The Base58 symbol chart used in Bitcoin is specific to the Bitcoin project and is not intended to be the same as any other Base58 implementation used outside the context of Bitcoin.
{| class="wikitable"
|-
!Value
!Character
!Value
!Character
!Value
!Character
!Value
!Character
|-
|0
|1
|1
|2
|2
|3
|3
|4
|-
|4
|5
|5
|6
|6
|7
|7
|8
|-
|8
|9
|9
|A
|10
|B
|11
|C
|-
|12
|D
|13
|E
|14
|F
|15
|G
|-
|16
|H
|17
|J
|18
|K
|19
|L
|-
|20
|M
|21
|N
|22
|P
|23
|Q
|-
|24
|R
|25
|S
|26
|T
|27
|U
|-
|28
|V
|29
|W
|30
|X
|31
|Y
|-
|32
|Z
|33
|a
|34
|b
|35
|c
|-
|36
|d
|37
|e
|38
|f
|39
|g
|-
|40
|h
|41
|i
|42
|j
|43
|k
|-
|44
|m
|45
|n
|46
|o
|47
|p
|-
|48
|q
|49
|r
|50
|s
|51
|t
|-
|52
|u
|53
|v
|54
|w
|55
|x
|-
|56
|y
|57
|z
|}

The algorithm for encoding address_byte_string (consisting of 0x01 + hash + 4-byte_check_code) is

code_string = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
x = convert_bytes_to_big_integer(hash_result)

output_string = ""

while(x > 0)
{
(x, remainder) = divide(x, 58)
output_string.append(code_string[remainder])
}

repeat(number_of_leading_zero_bytes_in_hash)
{
output_string.append(code_string[0]);
}

output_string.reverse();

==Version bytes==
Here are some common version bytes:

{| class="wikitable"
|-
!Decimal version
!Leading symbol
!Use
|-
|0
|1
|Bitcoin pubkey hash
|-
|5
|3
|Bitcoin script hash
|-
|21
|4
|Bitcoin (compact) public key (proposed)
|-
|52
|M or N
|Namecoin pubkey hash
|-
|128
|5
|Private key
|-
|111
|m or n
|Bitcoin testnet pubkey hash
|-
|196
|2
|Bitcoin testnet script hash
|}
[[List of address prefixes]] is a more complete list.

== Source code ==
* [https://github.com/bitcoin/bitcoin/blob/master/src/base58.h "Satoshi" C++ codebase (encode/decode using BigNum library)]
* [https://gitorious.org/bitcoin/libblkmaker/blobs/master/base58.c libblkmaker C code (decode only, no external libraries needed)]

[[Category:Technical]]

[[es:Codificación Base58Check]]

Base58Check encoding

2013-03-18T13:46:43Z

CodeShark: /* Encoding a Bitcoin address */

A modified Base 58 [http://en.wikipedia.org/wiki/Binary-to-text_encoding binary-to-text encoding] known as '''Base58Check''' is used for encoding [[Bitcoin address]]es.

More generically, Base58Check encoding is used for encoding byte arrays in Bitcoin into human-typable strings. A Bitcoin address is simply a Base58Check-encoded string with a 20-byte payload, the payload being the hash of the [[public key]] associated with the address.

The original Bitcoin client source code discusses the reasoning behind base58 encoding:

base58.h:
// Why base-58 instead of standard base-64 encoding?
// - Don't want 0OIl characters that look the same in some fonts and
// could be used to create visually identical looking account numbers.
// - A string with non-alphanumeric characters is not as easily accepted as an account number.
// - E-mail usually won't line-break if there's no punctuation to break at.
// - Doubleclicking selects the whole number as one word if it's all alphanumeric.

==Features of Base58Check==
Base58Check has the following features:
* An arbitrarily sized payload.
* A set of 58 alphanumeric symbols consisting of easily distinguished uppercase and lowercase letters (0OIl are not used)
* One byte of version/application information. Bitcoin addresses use 0x00 for this byte (future ones may use 0x05).
* Four bytes (32 bits) of SHA256-based error checking code. This code can be used to automatically detect and possibly correct typographical errors.
* An extra step for preservation of leading zeroes in the data.

==Creating a Base58Check string==
A Base58Check string is created from a version/application byte and payload as follows.
# Take the version/application byte and payload bytes, and concatenate them together (bytewise).
# Take the first four bytes of SHA256(SHA256(results of step 1))
# Concatenate the results of step 1 and the results of step 2 together (bytewise).
# Treating the results of step 3 - a series of bytes - as a single big-endian bignumber, convert to base-58 using normal mathematical steps (bignumber division) and the base-58 alphabet described below. The result should be normalized to not have any leading base-58 zeroes (character '1').
# The leading character '1', which has a value of zero in base58, is reserved for representing an entire leading zero '''byte''', as when it is in a leading position, has no value as a base-58 symbol. There can be one or more leading '1's when necessary to represent one or more leading zero bytes. Count the number of leading zero bytes that were the result of step 3 (for old Bitcoin addresses, there will always be at least one for the version/application byte; for new addresses, there will never be any). Each leading zero byte shall be represented by its own character '1' in the final result.
# Concatenate the 1's from step 5 with the results of step 4. '''This is the Base58Check result.'''

==Encoding a Bitcoin address==
A Bitcoin address is based on any [[ECDSA]] [[secp256k1]] public/private [[key pair]].

A Bitcoin address is the Base58Check encoding of the hash of the associated [[script]]. Specifically, it is Base58Check(version_byte,[[RIPEMD160]]([[SHA256]]([[script]]))), with the following constraints:
* [[RIPEMD160]] and [[SHA256]] in this case are always exactly 20 and 32 unsigned bytes respectively. These are big-endian (most significant byte first). (Beware of [[bignumber]] implementations that clip leading 0x00 bytes, or prepend extra 0x00 bytes to indicate sign - your code must handle these cases properly or else you may generate valid-looking addresses which can be sent to, but cannot be spent from - which would lead to the permanent loss of coins.)
* version_byte is 0x00 for standard pay-to-address scripts, version_byte is 0x05 for pay-to-script-hash scripts.

Bitcoin addresses that use the version byte 0x00 start with the digit '1'. Bitcoin addresses that use the version byte 0x05 start with the digit '3'.

==Encoding a private key==
Base58Check encoding is also used for encoding [[private key]]s in the [[Wallet import format]]. This is formed exactly the same as a Bitcoin address, except that 0x80 is used for the version/application byte, and the payload is 32 bytes instead of 20 (a private key in Bitcoin is a single 32-byte unsigned big-endian integer). Such encodings will always yield a 51-character string that starts with '5', or more specifically, either '5H', '5J', or '5K'.

==Base58 symbol chart==
The Base58 symbol chart used in Bitcoin is specific to the Bitcoin project and is not intended to be the same as any other Base58 implementation used outside the context of Bitcoin.
{| class="wikitable"
|-
!Value
!Character
!Value
!Character
!Value
!Character
!Value
!Character
|-
|0
|1
|1
|2
|2
|3
|3
|4
|-
|4
|5
|5
|6
|6
|7
|7
|8
|-
|8
|9
|9
|A
|10
|B
|11
|C
|-
|12
|D
|13
|E
|14
|F
|15
|G
|-
|16
|H
|17
|J
|18
|K
|19
|L
|-
|20
|M
|21
|N
|22
|P
|23
|Q
|-
|24
|R
|25
|S
|26
|T
|27
|U
|-
|28
|V
|29
|W
|30
|X
|31
|Y
|-
|32
|Z
|33
|a
|34
|b
|35
|c
|-
|36
|d
|37
|e
|38
|f
|39
|g
|-
|40
|h
|41
|i
|42
|j
|43
|k
|-
|44
|m
|45
|n
|46
|o
|47
|p
|-
|48
|q
|49
|r
|50
|s
|51
|t
|-
|52
|u
|53
|v
|54
|w
|55
|x
|-
|56
|y
|57
|z
|}

The algorithm for encoding address_byte_string (consisting of 0x01 + hash + 4-byte_check_code) is

code_string = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
x = convert_bytes_to_big_integer(hash_result)

output_string = ""

while(x > 0)
{
(x, remainder) = divide(x, 58)
output_string.append(code_string[remainder])
}

repeat(number_of_leading_zero_bytes_in_hash)
{
output_string.append(code_string[0]);
}

output_string.reverse();

==Version bytes==
Here are some common version bytes:

{| class="wikitable"
|-
!Decimal version
!Leading symbol
!Use
|-
|0
|1
|Bitcoin pubkey hash
|-
|5
|3
|Bitcoin script hash
|-
|21
|4
|Bitcoin (compact) public key (proposed)
|-
|52
|M or N
|Namecoin pubkey hash
|-
|128
|5
|Private key
|-
|111
|m or n
|Bitcoin testnet pubkey hash
|-
|196
|2
|Bitcoin testnet script hash
|}
[[List of address prefixes]] is a more complete list.

== Source code ==
* [https://github.com/bitcoin/bitcoin/blob/master/src/base58.h "Satoshi" C++ codebase (encode/decode using BigNum library)]
* [https://gitorious.org/bitcoin/libblkmaker/blobs/master/base58.c libblkmaker C code (decode only, no external libraries needed)]

[[Category:Technical]]

[[es:Codificación Base58Check]]

Base58Check encoding

2013-03-18T13:42:23Z

CodeShark: /* Encoding a Bitcoin address */

A modified Base 58 [http://en.wikipedia.org/wiki/Binary-to-text_encoding binary-to-text encoding] known as '''Base58Check''' is used for encoding [[Bitcoin address]]es.

More generically, Base58Check encoding is used for encoding byte arrays in Bitcoin into human-typable strings. A Bitcoin address is simply a Base58Check-encoded string with a 20-byte payload, the payload being the hash of the [[public key]] associated with the address.

The original Bitcoin client source code discusses the reasoning behind base58 encoding:

base58.h:
// Why base-58 instead of standard base-64 encoding?
// - Don't want 0OIl characters that look the same in some fonts and
// could be used to create visually identical looking account numbers.
// - A string with non-alphanumeric characters is not as easily accepted as an account number.
// - E-mail usually won't line-break if there's no punctuation to break at.
// - Doubleclicking selects the whole number as one word if it's all alphanumeric.

==Features of Base58Check==
Base58Check has the following features:
* An arbitrarily sized payload.
* A set of 58 alphanumeric symbols consisting of easily distinguished uppercase and lowercase letters (0OIl are not used)
* One byte of version/application information. Bitcoin addresses use 0x00 for this byte (future ones may use 0x05).
* Four bytes (32 bits) of SHA256-based error checking code. This code can be used to automatically detect and possibly correct typographical errors.
* An extra step for preservation of leading zeroes in the data.

==Creating a Base58Check string==
A Base58Check string is created from a version/application byte and payload as follows.
# Take the version/application byte and payload bytes, and concatenate them together (bytewise).
# Take the first four bytes of SHA256(SHA256(results of step 1))
# Concatenate the results of step 1 and the results of step 2 together (bytewise).
# Treating the results of step 3 - a series of bytes - as a single big-endian bignumber, convert to base-58 using normal mathematical steps (bignumber division) and the base-58 alphabet described below. The result should be normalized to not have any leading base-58 zeroes (character '1').
# The leading character '1', which has a value of zero in base58, is reserved for representing an entire leading zero '''byte''', as when it is in a leading position, has no value as a base-58 symbol. There can be one or more leading '1's when necessary to represent one or more leading zero bytes. Count the number of leading zero bytes that were the result of step 3 (for old Bitcoin addresses, there will always be at least one for the version/application byte; for new addresses, there will never be any). Each leading zero byte shall be represented by its own character '1' in the final result.
# Concatenate the 1's from step 5 with the results of step 4. '''This is the Base58Check result.'''

==Encoding a Bitcoin address==
A Bitcoin address is based on any [[ECDSA]] [[secp256k1]] public/private [[key pair]].

A Bitcoin address is the Base58Check encoding of the hash of the associated [[script]]. Specifically, it is Base58Check(version_byte,[[RIPEMD160]]([[SHA256]]([[script]]))), with the following constraints:
* [[RIPEMD160]] and [[SHA256]] in this case are always exactly 20 and 32 unsigned bytes respectively. These are big-endian (most significant byte first). (Beware of [[bignumber]] implementations that clip leading 0x00 bytes, or prepend extra 0x00 bytes to indicate sign - your code must handle these cases properly or else you may generate valid-looking addresses which can be sent to, but cannot be spent from - which would lead to the permanent loss of coins.)
* 0 refers to the version/application byte.

Bitcoin addresses that use the version byte 0x00 start with the digit '1'. Bitcoin addresses that use the version byte 0x05 start with the digit '3'.

==Encoding a private key==
Base58Check encoding is also used for encoding [[private key]]s in the [[Wallet import format]]. This is formed exactly the same as a Bitcoin address, except that 0x80 is used for the version/application byte, and the payload is 32 bytes instead of 20 (a private key in Bitcoin is a single 32-byte unsigned big-endian integer). Such encodings will always yield a 51-character string that starts with '5', or more specifically, either '5H', '5J', or '5K'.

==Base58 symbol chart==
The Base58 symbol chart used in Bitcoin is specific to the Bitcoin project and is not intended to be the same as any other Base58 implementation used outside the context of Bitcoin.
{| class="wikitable"
|-
!Value
!Character
!Value
!Character
!Value
!Character
!Value
!Character
|-
|0
|1
|1
|2
|2
|3
|3
|4
|-
|4
|5
|5
|6
|6
|7
|7
|8
|-
|8
|9
|9
|A
|10
|B
|11
|C
|-
|12
|D
|13
|E
|14
|F
|15
|G
|-
|16
|H
|17
|J
|18
|K
|19
|L
|-
|20
|M
|21
|N
|22
|P
|23
|Q
|-
|24
|R
|25
|S
|26
|T
|27
|U
|-
|28
|V
|29
|W
|30
|X
|31
|Y
|-
|32
|Z
|33
|a
|34
|b
|35
|c
|-
|36
|d
|37
|e
|38
|f
|39
|g
|-
|40
|h
|41
|i
|42
|j
|43
|k
|-
|44
|m
|45
|n
|46
|o
|47
|p
|-
|48
|q
|49
|r
|50
|s
|51
|t
|-
|52
|u
|53
|v
|54
|w
|55
|x
|-
|56
|y
|57
|z
|}

The algorithm for encoding address_byte_string (consisting of 0x01 + hash + 4-byte_check_code) is

code_string = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
x = convert_bytes_to_big_integer(hash_result)

output_string = ""

while(x > 0)
{
(x, remainder) = divide(x, 58)
output_string.append(code_string[remainder])
}

repeat(number_of_leading_zero_bytes_in_hash)
{
output_string.append(code_string[0]);
}

output_string.reverse();

==Version bytes==
Here are some common version bytes:

{| class="wikitable"
|-
!Decimal version
!Leading symbol
!Use
|-
|0
|1
|Bitcoin pubkey hash
|-
|5
|3
|Bitcoin script hash
|-
|21
|4
|Bitcoin (compact) public key (proposed)
|-
|52
|M or N
|Namecoin pubkey hash
|-
|128
|5
|Private key
|-
|111
|m or n
|Bitcoin testnet pubkey hash
|-
|196
|2
|Bitcoin testnet script hash
|}
[[List of address prefixes]] is a more complete list.

== Source code ==
* [https://github.com/bitcoin/bitcoin/blob/master/src/base58.h "Satoshi" C++ codebase (encode/decode using BigNum library)]
* [https://gitorious.org/bitcoin/libblkmaker/blobs/master/base58.c libblkmaker C code (decode only, no external libraries needed)]

[[Category:Technical]]

[[es:Codificación Base58Check]]