16/05/2015

Developer Guide - Bitcoin

Bitcoin Developer Guide

FinddetailedinformationabouttheBitcoinprotocolandrelatedspecifications.

Searchtheglossary,RPCs,andmore
TheDeveloperGuideaimstoprovidetheinformationyouneedtounderstandBitcoinandstartbuildingBitcoinbasedapplications,
butitisnotaspecification.Tomakethebestuseofthisdocumentation,youmaywanttoinstallthecurrentversionofBitcoinCore,
eitherfromsourceorfromaprecompiledexecutable.
QuestionsaboutBitcoindevelopmentarebestaskedinoneoftheBitcoindevelopmentcommunities.Errorsorsuggestionsrelated
todocumentationonBitcoin.orgcanbesubmittedasanissueorpostedtothebitcoindocumentationmailinglist.
Inthefollowingdocumentation,somestringshavebeenshortenedorwrapped:[]indicatesextradatawasremoved,andlines
endinginasinglebackslash\arecontinuedbelow.Ifyouhoveryourmouseoveraparagraph,crossreferencelinkswillbe
showninblue.Ifyouhoveroveracrossreferencelink,abriefdefinitionofthetermwillbedisplayedinatooltip.

Block Chain
TheblockchainprovidesBitcoinspublicledger,anorderedandtimestampedrecordoftransactions.Thissystemisusedtoprotect
againstdoublespendingandmodificationofprevioustransactionrecords.
EachfullnodeintheBitcoinnetworkindependentlystoresablockchaincontainingonlyblocksvalidatedbythatnode.When
severalnodesallhavethesameblocksintheirblockchain,theyareconsideredtobeinconsensus.Thevalidationrulesthese
nodesfollowtomaintainconsensusarecalledconsensusrules.Thissectiondescribesmanyoftheconsensusrulesusedby
BitcoinCore.

BlockChainOverview

Block 1
Header

Block 2
Header

Block 3
Header

Hash Of Previous
Block Header

Hash Of Previous
Block Header

Hash Of Previous
Block Header

Merkle Root

Merkle Root

Merkle Root

Block 1
Transactions

Block 2
Transactions

Block 3
Transactions

Simplified Bitcoin Block Chain

Theillustrationaboveshowsasimplifiedversionofablockchain.Ablockofoneormorenewtransactionsiscollectedintothe
transactiondatapartofablock.Copiesofeachtransactionarehashed,andthehashesarethenpaired,hashed,pairedagain,and
hashedagainuntilasinglehashremains,themerklerootofamerkletree.
Themerklerootisstoredintheblockheader.Eachblockalsostoresthehashofthepreviousblocksheader,chainingtheblocks
together.Thisensuresatransactioncannotbemodifiedwithoutmodifyingtheblockthatrecordsitandallfollowingblocks.
https://bitcoin.org/en/developer-guide

1/55

16/05/2015

Developer Guide - Bitcoin

Transactionsarealsochainedtogether.Bitcoinwalletsoftwaregivestheimpressionthatsatoshisaresentfromandtowallets,but
bitcoinsreallymovefromtransactiontotransaction.Eachtransactionspendsthesatoshispreviouslyreceivedinoneormore
earliertransactions,sotheinputofonetransactionistheoutputofaprevioustransaction.

100,000
(100k)
satoshis

TX 1

Transaction 0
(TX 0)

input0
input0

TX 3

40k
output0

30k

input0

output0
TX 2
output1

50k

output0

input0

output0

20k Unspent TX
Output (UTXO)

TX 4
20k

output1

input0

output0

TX 6
10k
input0

20k
TX 5
input0

output0

input1
10k
output0

10k
UTXO

Triple-Entry Bookkeeping (Transaction-To-Transaction Payments) As Used By Bitcoin

Asingletransactioncancreatemultipleoutputs,aswouldbethecasewhensendingtomultipleaddresses,buteachoutputofa
particulartransactioncanonlybeusedasaninputonceintheblockchain.Anysubsequentreferenceisaforbiddendoublespend
anattempttospendthesamesatoshistwice.
Outputsaretiedtotransactionidentifiers(TXIDs),whicharethehashesofsignedtransactions.
Becauseeachoutputofaparticulartransactioncanonlybespentonce,theoutputsofalltransactionsincludedintheblockchain
canbecategorizedaseitherUnspentTransactionOutputs(UTXOs)orspenttransactionoutputs.Forapaymenttobevalid,itmust
onlyuseUTXOsasinputs.
Ignoringcoinbasetransactions(describedlater),ifthevalueofatransactionsoutputsexceeditsinputs,thetransactionwillbe
rejectedbutiftheinputsexceedthevalueoftheoutputs,anydifferenceinvaluemaybeclaimedasatransactionfeebythe
Bitcoinminerwhocreatestheblockcontainingthattransaction.Forexample,intheillustrationabove,eachtransactionspends
10,000satoshisfewerthanitreceivesfromitscombinedinputs,effectivelypayinga10,000satoshitransactionfee.

ProofOfWork
Theblockchainiscollaborativelymaintainedbyanonymouspeersonthenetwork,soBitcoinrequiresthateachblockprovea
significantamountofworkwasinvestedinitscreationtoensurethatuntrustworthypeerswhowanttomodifypastblockshaveto
workharderthanhonestpeerswhoonlywanttoaddnewblockstotheblockchain.
Chainingblockstogethermakesitimpossibletomodifytransactionsincludedinanyblockwithoutmodifyingallfollowingblocks.As
aresult,thecosttomodifyaparticularblockincreaseswitheverynewblockaddedtotheblockchain,magnifyingtheeffectofthe
proofofwork.
TheproofofworkusedinBitcointakesadvantageoftheapparentlyrandomnatureofcryptographichashes.Agoodcryptographic
hashalgorithmconvertsarbitrarydataintoaseeminglyrandomnumber.Ifthedataismodifiedinanywayandthehashrerun,a
https://bitcoin.org/en/developer-guide

2/55

16/05/2015

Developer Guide - Bitcoin

newseeminglyrandomnumberisproduced,sothereisnowaytomodifythedatatomakethehashnumberpredictable.
Toproveyoudidsomeextraworktocreateablock,youmustcreateahashoftheblockheaderwhichdoesnotexceedacertain
value.Forexample,ifthemaximumpossiblehashvalueis22561,youcanprovethatyoutrieduptotwocombinationsby
producingahashvaluelessthan2255.
Intheexamplegivenabove,youwillproduceasuccessfulhashonaverageeveryothertry.Youcanevenestimatetheprobability
thatagivenhashattemptwillgenerateanumberbelowthetargetthreshold.Bitcoinassumesalinearprobabilitythatthelowerit
makesthetargetthreshold,themorehashattempts(onaverage)willneedtobetried.
Newblockswillonlybeaddedtotheblockchainiftheirhashisatleastaschallengingasadifficultyvalueexpectedbythe
consensusprotocol.Every2,016blocks,thenetworkusestimestampsstoredineachblockheadertocalculatethenumberof
secondselapsedbetweengenerationofthefirstandlastofthoselast2,016blocks.Theidealvalueis1,209,600seconds(two
weeks).
Ifittookfewerthantwoweekstogeneratethe2,016blocks,theexpecteddifficultyvalueisincreasedproportionally(byasmuch
as300%)sothatthenext2,016blocksshouldtakeexactlytwoweekstogenerateifhashesarecheckedatthesamerate.
Ifittookmorethantwoweekstogeneratetheblocks,theexpecteddifficultyvalueisdecreasedproportionally(byasmuchas
75%)forthesamereason.
(Note:anoffbyoneerrorintheBitcoinCoreimplementationcausesthedifficultytobeupdatedevery2,016blocksusing
timestampsfromonly2,015blocks,creatingaslightskew.)
Becauseeachblockheadermusthashtoavaluebelowthetargetthreshold,andbecauseeachblockislinkedtotheblockthat
precededit,itrequires(onaverage)asmuchhashingpowertopropagateamodifiedblockastheentireBitcoinnetworkexpended
betweenthetimetheoriginalblockwascreatedandthepresenttime.Onlyifyouacquiredamajorityofthenetworkshashing
powercouldyoureliablyexecutesucha51percentattackagainsttransactionhistory(although,itshouldbenoted,thatevenless
than50%ofthehashingpowerstillhasagoodchanceofperformingsuchattacks).
Theblockheaderprovidesseveraleasytomodifyfields,suchasadedicatednoncefield,soobtainingnewhashesdoesntrequire
waitingfornewtransactions.Also,onlythe80byteblockheaderishashedforproofofwork,soincludingalargevolumeof
transactiondatainablockdoesnotslowdownhashingwithextraI/O,andaddingadditionaltransactiondataonlyrequiresthe
recalculationoftheancestorhashesinthemerkletree.

BlockHeightAndForking
AnyBitcoinminerwhosuccessfullyhashesablockheadertoavaluebelowthetargetthresholdcanaddtheentireblocktothe
blockchain(assumingtheblockisotherwisevalid).Theseblocksarecommonlyaddressedbytheirblockheightthenumberof
blocksbetweenthemandthefirstBitcoinblock(block0,mostcommonlyknownasthegenesisblock).Forexample,block2016is
wheredifficultycouldhavefirstbeenadjusted.
Normal Occasional Forking
block0

Header Hash

block1

block2

block3

block4

block2

block5

block6

block5

Rare Extended Forking

block0

Header Hash

block2

block3

block4

block5

block2

block3

block4

block5

block1
block6

Multipleblockscanallhavethesameblockheight,asiscommonwhentwoormoreminerseachproduceablockatroughlythe
https://bitcoin.org/en/developer-guide

3/55

16/05/2015

Developer Guide - Bitcoin

sametime.Thiscreatesanapparentforkintheblockchain,asshownintheillustrationabove.
Whenminersproducesimultaneousblocksattheendoftheblockchain,eachnodeindividuallychooseswhichblocktoaccept.In
theabsenceofotherconsiderations,discussedbelow,nodesusuallyusethefirstblocktheysee.
Eventuallyaminerproducesanotherblockwhichattachestoonlyoneofthecompetingsimultaneouslyminedblocks.Thismakes
thatsideoftheforkstrongerthantheotherside.Assumingaforkonlycontainsvalidblocks,normalpeersalwaysfollowthethe
mostdifficultchaintorecreateandthrowawaystaleblocksbelongingtoshorterforks.(Staleblocksarealsosometimescalled
orphansororphanblocks,butthosetermsarealsousedfortrueorphanblockswithoutaknownparentblock.)
Longtermforksarepossibleifdifferentminersworkatcrosspurposes,suchassomeminersdiligentlyworkingtoextendtheblock
chainatthesametimeotherminersareattemptinga51percentattacktorevisetransactionhistory.
Sincemultipleblockscanhavethesameheightduringablockchainfork,blockheightshouldnotbeusedasagloballyunique
identifier.Instead,blocksareusuallyreferencedbythehashoftheirheader(oftenwiththebyteorderreversed,andin
hexadecimal).

TransactionData
Everyblockmustincludeoneormoretransactions.Thefirstoneofthesetransactionsmustbeacoinbasetransaction,alsocalled
agenerationtransaction,whichshouldcollectandspendtheblockreward(comprisedofablocksubsidyandanytransactionfees
paidbytransactionsincludedinthisblock).
TheUTXOofacoinbasetransactionhasthespecialconditionthatitcannotbespent(usedasaninput)foratleast100blocks.
Thistemporarilypreventsaminerfromspendingthetransactionfeesandblockrewardfromablockthatmaylaterbedetermined
tobestale(andthereforethecoinbasetransactiondestroyed)afterablockchainfork.
Blocksarenotrequiredtoincludeanynoncoinbasetransactions,butminersalmostalwaysdoincludeadditionaltransactionsin
ordertocollecttheirtransactionfees.
Alltransactions,includingthecoinbasetransaction,areencodedintoblocksinbinaryrawtransactionformat.
Therawtransactionformatishashedtocreatethetransactionidentifier(txid).Fromthesetxids,themerkletreeisconstructedby
pairingeachtxidwithoneothertxidandthenhashingthemtogether.Ifthereareanoddnumberoftxids,thetxidwithoutapartner
ishashedwithacopyofitself.
Theresultinghashesthemselvesareeachpairedwithoneotherhashandhashedtogether.Anyhashwithoutapartnerishashed
withitself.Theprocessrepeatsuntilonlyonehashremains,themerkleroot.
Forexample,iftransactionsweremerelyjoined(nothashed),afivetransactionmerkletreewouldlooklikethefollowingtext
diagram:
ABCDEEEE .......Merkle root
/
\
ABCD
EEEE
/
\
/
AB
CD
EE .......E is paired with itself
/ \ / \ /
A B C D E .........Transactions

AsdiscussedintheSimplifiedPaymentVerification(SPV)subsection,themerkletreeallowsclientstoverifyforthemselvesthata
transactionwasincludedinablockbyobtainingthemerklerootfromablockheaderandalistoftheintermediatehashesfroma
fullpeer.Thefullpeerdoesnotneedtobetrusted:itisexpensivetofakeblockheadersandtheintermediatehashescannotbe
fakedortheverificationwillfail.
https://bitcoin.org/en/developer-guide

4/55

16/05/2015

Developer Guide - Bitcoin

Forexample,toverifytransactionDwasaddedtotheblock,anSPVclientonlyneedsacopyoftheC,AB,andEEEEhashesin
additiontothemerkleroottheclientdoesntneedtoknowanythingaboutanyoftheothertransactions.Ifthefivetransactionsin
thisblockwereallatthemaximumsize,downloadingtheentireblockwouldrequireover500,000bytesbutdownloadingthree
hashesplustheblockheaderrequiresonly140bytes.
Note:Ifidenticaltxidsarefoundwithinthesameblock,thereisapossibilitythatthemerkletreemaycollidewithablockwithsome
orallduplicatesremovedduetohowunbalancedmerkletreesareimplemented(duplicatingthelonehash).Sinceitisimpractical
tohaveseparatetransactionswithidenticaltxids,thisdoesnotimposeaburdenonhonestsoftware,butmustbecheckedifthe
invalidstatusofablockistobecachedotherwise,avalidblockwiththeduplicateseliminatedcouldhavethesamemerkleroot
andblockhash,butberejectedbythecachedinvalidoutcome,resultinginsecuritybugssuchasCVE20122459.

ConsensusRuleChanges
Tomaintainconsensus,allfullnodesvalidateblocksusingthesameconsensusrules.However,sometimestheconsensusrules
arechangedtointroducenewfeaturesorpreventnetworkabuse.Whenthenewrulesareimplemented,therewilllikelybeaperiod
oftimewhennonupgradednodesfollowtheoldrulesandupgradednodesfollowthenewrules,creatingtwopossibleways
consensuscanbreak:
1. Ablockfollowingthenewconsensusrulesisacceptedbyupgradednodesbutrejectedbynonupgradednodes.Forexample,a
newtransactionfeatureisusedwithinablock:upgradednodesunderstandthefeatureandacceptit,butnonupgradednodes
rejectitbecauseitviolatestheoldrules.
2. Ablockviolatingthenewconsensusrulesisrejectedbyupgradednodesbutacceptedbynonupgradednodes.Forexample,an
abusivetransactionfeatureisusedwithinablock:upgradednodesrejectitbecauseitviolatesthenewrules,butnonupgraded
nodesacceptitbecauseitfollowstheoldrules.
Inthefirstcase,rejectionbynonupgradednodes,miningsoftwarewhichgetsblockchaindatafromthosenonupgradednodes
refusestobuildonthesamechainasminingsoftwaregettingdatafromupgradednodes.Thiscreatespermanentlydivergent
chainsonefornonupgradednodesandoneforupgradednodescalledahardfork.
Blocks
From NonUpgraded
Nodes

Follows
Old
Rules

Follows
Old
Rules

Blocks
From
Upgraded
Nodes

Follows
Old
Rules

Follows
Old
Rules

Follows
New
Rules

Follows
New
Rules

Follows
New
Rules

Follows
New
Rules

A Hard Fork: Non-Upgraded Nodes Reject The New Rules, Diverging The Chain

Inthesecondcase,rejectionbyupgradednodes,itspossibletokeeptheblockchainfrompermanentlydivergingifupgraded
nodescontrolamajorityofthehashrate.Thatsbecause,inthiscase,nonupgradednodeswillacceptasvalidallthesameblocks
asupgradednodes,sotheupgradednodescanbuildastrongerchainthatthenonupgradednodeswillacceptasthebestvalid
blockchain.Thisiscalledasoftfork.
Blocks
From NonUpgraded
Nodes

Follows
Old
Rules

Follows
Old
Rules

Blocks
From
Upgraded
Nodes

Follows Old Rules

But Violates
New Rules
Follows
Old & New
Rules

Follows
Old
Rules
Follows
Old & New
Rules

A Soft Fork: Blocks Violating New Rules Are Made Stale By The Upgraded Mining Majority

https://bitcoin.org/en/developer-guide

5/55

16/05/2015

Developer Guide - Bitcoin

Althoughaforkisanactualdivergenceinblockchains,changestotheconsensusrulesareoftendescribedbytheirpotentialto
createeitherahardorsoftfork.Forexample,increasingtheblocksizeabove1MBrequiresahardfork.Inthisexample,an
actualblockchainforkisnotrequiredbutitisapossibleoutcome.
Resources:BIP16,BIP30,andBIP34wereimplementedaschangeswhichmighthaveleadtosoftforks.BIP50describesbothan
accidentalhardfork,resolvedbytemporarydowngradingthecapabilitiesofupgradednodes,andanintentionalhardforkwhenthe
temporarydowngradewasremoved.AdocumentfromGavinAndresenoutlineshowfuturerulechangesmaybeimplemented.

DetectingForks

Nonupgradednodesmayuseanddistributeincorrectinformationduringbothtypesofforks,creatingseveralsituationswhich
couldleadtofinancialloss.Inparticular,nonupgradednodesmayrelayandaccepttransactionsthatareconsideredinvalidby
upgradednodesandsowillneverbecomepartoftheuniversallyrecognizedbestblockchain.Nonupgradednodesmayalso
refusetorelayblocksortransactionswhichhavealreadybeenaddedtothebestblockchain,orsoonwillbe,andsoprovide
incompleteinformation.
BitcoinCoreincludescodethatdetectsahardforkbylookingatblockchainproofofwork.Ifanonupgradednodereceivesblock
chainheadersdemonstratingatleastsixblocksmoreproofofworkthanthebestchainitconsidersvalid,thenodereportsanerror
inthe getinfoRPCresultsandrunsthe -alertnotifycommandifset.Thiswarnstheoperatorthatthenonupgradednode
cantswitchtowhatislikelythebestblockchain.
Fullnodescanalsocheckblockandtransactionversionnumbers.Iftheblockortransactionversionnumbersseeninseveral
recentblocksarehigherthantheversionnumbersthenodeuses,itcanassumeitdoesntusethecurrentconsensusrules.Bitcoin
Core0.10.0reportsthissituationthroughthe getinfoRPCand -alertnotifycommandifset.
Ineithercase,blockandtransactiondatashouldnotberelieduponifitcomesfromanodethatapparentlyisntusingthecurrent
consensusrules.
SPVclientswhichconnecttofullnodescandetectalikelyhardforkbyconnectingtoseveralfullnodesandensuringthattheyreall
onthesamechainwiththesameblockheight,plusorminusseveralblockstoaccountfortransmissiondelaysandstaleblocks.If
theresadivergence,theclientcandisconnectfromnodeswithweakerchains.
SPVclientsshouldalsomonitorforblockandtransactionversionnumberincreasestoensuretheyprocessreceivedtransactions
andcreatenewtransactionsusingthecurrentconsensusrules.

Transactions
Transactionsletusersspendsatoshis.Eachtransactionisconstructedoutofseveralpartswhichenablebothsimpledirect
paymentsandcomplextransactions.Thissectionwilldescribeeachpartanddemonstratehowtousethemtogethertobuild
completetransactions.
Tokeepthingssimple,thissectionpretendscoinbasetransactionsdonotexist.Coinbasetransactionscanonlybecreatedby
Bitcoinminersandtheyreanexceptiontomanyoftheruleslistedbelow.Insteadofpointingoutthecoinbaseexceptiontoeach
rule,weinviteyoutoreadaboutcoinbasetransactionsintheblockchainsectionofthisguide.

https://bitcoin.org/en/developer-guide

6/55

16/05/2015

Developer Guide - Bitcoin

Each input spends a previous output

The Main Parts Of
Transaction 0

Version

Inputs

Outputs

Locktime

The Main Parts Of

Transaction 1

Version

Inputs

Outputs

Locktime

Each output waits as an Unspent TX Output (UTXO) until a later input spends it

ThefigureaboveshowsthemainpartsofaBitcointransaction.Eachtransactionhasatleastoneinputandoneoutput.Eachinput
spendsthesatoshispaidtoapreviousoutput.EachoutputthenwaitsasanUnspentTransactionOutput(UTXO)untilalaterinput
spendsit.WhenyourBitcoinwallettellsyouthatyouhavea10,000satoshibalance,itreallymeansthatyouhave10,000satoshis
waitinginoneormoreUTXOs.
EachtransactionisprefixedbyafourbytetransactionversionnumberwhichtellsBitcoinpeersandminerswhichsetofrulesto
usetovalidateit.Thisletsdeveloperscreatenewrulesforfuturetransactionswithoutinvalidatingprevioustransactions.

Example Output Paying A Pubkey Script

Transaction
0

Transaction
1

Output 0
(Implied)

Transaction
Identifier

Output
Index

Amount
(satoshis)

Sequence
Number

Pubkey
Script

Not Shown:
Version, Inputs,
Locktime

Signature
Script

Not Shown:
Version, Outputs,
Locktime

Example Input Spending The Example Output

Overview Of Transaction Spending

Anoutputhasanimpliedindexnumberbasedonitslocationinthetransactionthefirstoutputisoutputzero.Theoutputalsohas
anamountinsatoshiswhichitpaystoaconditionalpubkeyscript.Anyonewhocansatisfytheconditionsofthatpubkeyscriptcan
spenduptotheamountofsatoshispaidtoit.
Aninputusesatransactionidentifier(txid)andanoutputindexnumber(oftencalledvoutforoutputvector)toidentifyaparticular
outputtobespent.Italsohasasignaturescriptwhichallowsittoprovidedataparametersthatsatisfytheconditionalsinthe
pubkeyscript.(Thesequencenumberandlocktimearerelatedandwillbecoveredtogetherinalatersubsection.)
ThefiguresbelowhelpillustratehowthesefeaturesareusedbyshowingtheworkflowAliceusestosendBobatransactionand
whichBoblaterusestospendthattransaction.BothAliceandBobwillusethemostcommonformofthestandardPayToPublic
KeyHash(P2PKH)transactiontype.P2PKHletsAlicespendsatoshistoatypicalBitcoinaddress,andthenletsBobfurtherspend
thosesatoshisusingasimplecryptographickeypair.

Bob's Computer
Private
Key

Full
Public Key

Public Key
Hash

Alice's Computer

TX 1

Copy Of
Public Key
Hash

Copy Of
Public Key
Hash

Creating A P2PKH Public Key Hash To Receive Payment

Bobmustfirstgenerateaprivate/publickeypairbeforeAlicecancreatethefirsttransaction.BitcoinusestheEllipticCurveDigital
SignatureAlgorithm(ECDSA)withthesecp256k1curvesecp256k1privatekeysare256bitsofrandomdata.Acopyofthatdata
isdeterministicallytransformedintoansecp256k1publickey.Becausethetransformationcanbereliablyrepeatedlater,thepublic
https://bitcoin.org/en/developer-guide

7/55

16/05/2015

Developer Guide - Bitcoin

keydoesnotneedtobestored.
Thepublickey(pubkey)isthencryptographicallyhashed.Thispubkeyhashcanalsobereliablyrepeatedlater,soitalsodoesnot
needtobestored.Thehashshortensandobfuscatesthepublickey,makingmanualtranscriptioneasierandprovidingsecurity
againstunanticipatedproblemswhichmightallowreconstructionofprivatekeysfrompublickeydataatsomelaterpoint.
BobprovidesthepubkeyhashtoAlice.PubkeyhashesarealmostalwayssentencodedasBitcoinaddresses,whicharebase58
encodedstringscontaininganaddressversionnumber,thehash,andanerrordetectionchecksumtocatchtypos.Theaddress
canbetransmittedthroughanymedium,includingonewaymediumswhichpreventthespenderfromcommunicatingwiththe
receiver,anditcanbefurtherencodedintoanotherformat,suchasaQRcodecontaininga bitcoin:URI.
OnceAlicehastheaddressanddecodesitbackintoastandardhash,shecancreatethefirsttransaction.Shecreatesastandard
P2PKHtransactionoutputcontaininginstructionswhichallowanyonetospendthatoutputiftheycanprovetheycontroltheprivate
keycorrespondingtoBobshashedpublickey.TheseinstructionsarecalledthepubkeyscriptorscriptPubKey.
Alicebroadcaststhetransactionanditisaddedtotheblockchain.ThenetworkcategorizesitasanUnspentTransactionOutput
(UTXO),andBobswalletsoftwaredisplaysitasaspendablebalance.
When,sometimelater,BobdecidestospendtheUTXO,hemustcreateaninputwhichreferencesthetransactionAlicecreatedby
itshash,calledaTransactionIdentifier(txid),andthespecificoutputsheusedbyitsindexnumber(outputindex).Hemustthen
createasignaturescriptacollectionofdataparameterswhichsatisfytheconditionsAliceplacedinthepreviousoutputspubkey
script.SignaturescriptsarealsocalledscriptSigs.
Pubkeyscriptsandsignaturescriptscombinesecp256k1pubkeysandsignatureswithconditionallogic,creatingaprogramable
authorizationmechanism.

Signature Script

Bob's Computer

Signature

Private Key

Full Public Key

Full Public Key

TX 1 Output

Pubkey Script

Public Key Hash

Public Key Hash

Spending A P2PKH Output

ForaP2PKHstyleoutput,Bobssignaturescriptwillcontainthefollowingtwopiecesofdata:
1. Hisfull(unhashed)publickey,sothepubkeyscriptcancheckthatithashestothesamevalueasthepubkeyhashprovidedby
Alice.
2. Ansecp256k1signaturemadebyusingtheECDSAcryptographicformulatocombinecertaintransactiondata(describedbelow)
withBobsprivatekey.ThisletsthepubkeyscriptverifythatBobownstheprivatekeywhichcreatedthepublickey.
Bobssecp256k1signaturedoesntjustproveBobcontrolshisprivatekeyitalsomakesthenonsignaturescriptpartsofhis
transactiontamperproofsoBobcansafelybroadcastthemoverthepeertopeernetwork.

https://bitcoin.org/en/developer-guide

8/55

16/05/2015

Developer Guide - Bitcoin

Bob's Computer
Transaction 1 (TX 1)

TXID

Output Index Number

TX2 Template

Pubkey Script

Private Key

Pubkey Script

Amount

Signed Data

Transaction 2
TXID

Output Index Number

Full Public Key

Signature

Pubkey Script

Amount

Some Of The Data Signed By Default

Asillustratedinthefigureabove,thedataBobsignsincludesthetxidandoutputindexoftheprevioustransaction,theprevious
outputspubkeyscript,thepubkeyscriptBobcreateswhichwillletthenextrecipientspendthistransactionsoutput,andthe
amountofsatoshistospendtothenextrecipient.Inessence,theentiretransactionissignedexceptforanysignaturescripts,
whichholdthefullpublickeysandsecp256k1signatures.
Afterputtinghissignatureandpublickeyinthesignaturescript,BobbroadcaststhetransactiontoBitcoinminersthroughthepeer
topeernetwork.Eachpeerandminerindependentlyvalidatesthetransactionbeforebroadcastingitfurtherorattemptingtoinclude
itinanewblockoftransactions.

P2PKHScriptValidation
Thevalidationprocedurerequiresevaluationofthesignaturescriptandpubkeyscript.InaP2PKHoutput,thepubkeyscriptis:
OP_DUP OP_HASH160 <PubkeyHash> OP_EQUALVERIFY OP_CHECKSIG

Thespenderssignaturescriptisevaluatedandprefixedtothebeginningofthescript.InaP2PKHtransaction,thesignaturescript
containsansecp256k1signature(sig)andfullpublickey(pubkey),creatingthefollowingconcatenation:
<Sig> <PubKey> OP_DUP OP_HASH160 <PubkeyHash> OP_EQUALVERIFY OP_CHECKSIG

ThescriptlanguageisaForthlikestackbasedlanguagedeliberatelydesignedtobestatelessandnotTuringcomplete.
Statelessnessensuresthatonceatransactionisaddedtotheblockchain,thereisnoconditionwhichrendersitpermanently
unspendable.Turingincompleteness(specifically,alackofloopsorgotos)makesthescriptlanguagelessflexibleandmore
predictable,greatlysimplifyingthesecuritymodel.
Totestwhetherthetransactionisvalid,signaturescriptandpubkeyscriptoperationsareexecutedoneitematatime,startingwith
BobssignaturescriptandcontinuingtotheendofAlicespubkeyscript.Thefigurebelowshowstheevaluationofastandard
P2PKHpubkeyscriptbelowthefigureisadescriptionoftheprocess.

https://bitcoin.org/en/developer-guide

9/55

16/05/2015

Developer Guide - Bitcoin

Instructions And Data Provided By Alice In Transaction #1's Pubkey Script
OP_DUP

OP_HASH160

Pk Hash

OP_EQUALVERIFY

CHECKSIG

Data Provided By Bob In Transaction #2's Input Signature Script

Sig

PubKey

OP_EQUALVERIFY

Sig

OP_HASH160

Pk Hash

Pk Hash

OP_DUP

PubKey

Pk Hash

Pk Hash

OP_CHECKSIG

PubKey

PubKey

PubKey

PubKey

PubKey

PubKey

Sig

Sig

Sig

Sig

Sig

Sig

TRUE

Evaluation Stack Over Time During Succesful P2PKH Script Validation

Thesignature(fromBobssignaturescript)isadded(pushed)toanemptystack.Becauseitsjustdata,nothingisdoneexcept
addingittothestack.Thepublickey(alsofromthesignaturescript)ispushedontopofthesignature.
FromAlicespubkeyscript,the OP_DUPoperationisexecuted. OP_DUPpushesontothestackacopyofthedatacurrentlyatthe
topofitinthiscasecreatingacopyofthepublickeyBobprovided.
Theoperationexecutednext, OP_HASH160,pushesontothestackahashofthedatacurrentlyontopofitinthiscase,Bobs
publickey.ThiscreatesahashofBobspublickey.
AlicespubkeyscriptthenpushesthepubkeyhashthatBobgaveherforthefirsttransaction.Atthispoint,thereshouldbetwo
copiesofBobspubkeyhashatthetopofthestack.
Nowitgetsinteresting:Alicespubkeyscriptexecutes OP_EQUALVERIFY. OP_EQUALVERIFYisequivalenttoexecuting OP_EQUAL
followedby OP_VERIFY(notshown).
OP_EQUAL(notshown)checksthetwovaluesatthetopofthestackinthiscase,itcheckswhetherthepubkeyhashgenerated

fromthefullpublickeyBobprovidedequalsthepubkeyhashAliceprovidedwhenshecreatedtransaction#1. OP_EQUALpops
(removesfromthetopofthestack)thetwovaluesitcompared,andreplacesthemwiththeresultofthatcomparison:zero
(false)orone(true).
OP_VERIFY(notshown)checksthevalueatthetopofthestack.Ifthevalueisfalseitimmediatelyterminatesevaluationand

thetransactionvalidationfails.Otherwiseitpopsthetruevalueoffthestack.
Finally,Alicespubkeyscriptexecutes OP_CHECKSIG,whichchecksthesignatureBobprovidedagainstthenowauthenticated
publickeyhealsoprovided.Ifthesignaturematchesthepublickeyandwasgeneratedusingallofthedatarequiredtobe
signed, OP_CHECKSIGpushesthevaluetrueontothetopofthestack.
Iffalseisnotatthetopofthestackafterthepubkeyscripthasbeenevaluated,thetransactionisvalid(providedtherearenoother
problemswithit).

P2SHScripts
Pubkeyscriptsarecreatedbyspenderswhohavelittleinterestwhatthatscriptdoes.Receiversdocareaboutthescriptconditions
https://bitcoin.org/en/developer-guide

10/55

16/05/2015

Developer Guide - Bitcoin

and,iftheywant,theycanaskspenderstouseaparticularpubkeyscript.Unfortunately,custompubkeyscriptsarelessconvenient
thanshortBitcoinaddressesandtherewasnostandardwaytocommunicatethembetweenprogramspriortowidespread
implementationoftheBIP70PaymentProtocoldiscussedlater.
Tosolvetheseproblems,paytoscripthash(P2SH)transactionswerecreatedin2012toletaspendercreateapubkeyscript
containingahashofasecondscript,theredeemscript.
ThebasicP2SHworkflow,illustratedbelow,looksalmostidenticaltotheP2PKHworkflow.Bobcreatesaredeemscriptwith
whateverscripthewants,hashestheredeemscript,andprovidestheredeemscripthashtoAlice.AlicecreatesaP2SHstyle
outputcontainingBobsredeemscripthash.

Bob's Computer
Private
Key

Full
Public Key

Redeem Script

Alice's Computer

TX 1

Copy Of
Script
Hash

Copy Of
Script
Hash

Script
Hash

Creating A P2SH Redeem Script Hash To Receive Payment

WhenBobwantstospendtheoutput,heprovideshissignaturealongwiththefull(serialized)redeemscriptinthesignaturescript.
ThepeertopeernetworkensuresthefullredeemscripthashestothesamevalueasthescripthashAliceputinheroutputitthen
processestheredeemscriptexactlyasitwouldifitweretheprimarypubkeyscript,lettingBobspendtheoutputiftheredeem
scriptdoesnotreturnfalse.

Signature Script

Bob's Computer

Signature

Private Key

Full Redeem Script

Full Redeem Script

TX 1 Output

Pubkey Script

Redeem Script Hash

Redeem Script Hash

Spending A P2SH Output

ThehashoftheredeemscripthasthesamepropertiesasapubkeyhashsoitcanbetransformedintothestandardBitcoin
addressformatwithonlyonesmallchangetodifferentiateitfromastandardaddress.ThismakescollectingaP2SHstyleaddress
assimpleascollectingaP2PKHstyleaddress.Thehashalsoobfuscatesanypublickeysintheredeemscript,soP2SHscripts
areassecureasP2PKHpubkeyhashes.

StandardTransactions
AfterthediscoveryofseveraldangerousbugsinearlyversionsofBitcoin,atestwasaddedwhichonlyacceptedtransactionsfrom
thenetworkiftheirpubkeyscriptsandsignaturescriptsmatchedasmallsetofbelievedtobesafetemplates,andiftherestofthe
transactiondidntviolateanothersmallsetofrulesenforcinggoodnetworkbehavior.Thisisthe IsStandard()test,and
transactionswhichpassitarecalledstandardtransactions.
NonstandardtransactionsthosethatfailthetestmaybeacceptedbynodesnotusingthedefaultBitcoinCoresettings.Ifthey
areincludedinblocks,theywillalsoavoidtheIsStandardtestandbeprocessed.
BesidesmakingitmoredifficultforsomeonetoattackBitcoinforfreebybroadcastingharmfultransactions,thestandard
transactiontestalsohelpspreventusersfromcreatingtransactionstodaythatwouldmakeaddingnewtransactionfeaturesinthe
https://bitcoin.org/en/developer-guide

11/55

16/05/2015

Developer Guide - Bitcoin

futuremoredifficult.Forexample,asdescribedabove,eachtransactionincludesaversionnumberifusersstartedarbitrarily
changingtheversionnumber,itwouldbecomeuselessasatoolforintroducingbackwardsincompatiblefeatures.
AsofBitcoinCore0.9,thestandardpubkeyscripttypesare:

PayToPublicKeyHash(P2PKH)

P2PKHisthemostcommonformofpubkeyscriptusedtosendatransactiontooneormultipleBitcoinaddresses.
Pubkey script: OP_DUP OP_HASH160 <PubKeyHash> OP_EQUALVERIFY OP_CHECKSIG
Signature script: <sig> <pubkey>

PayToScriptHash(P2SH)

P2SHisusedtosendatransactiontoascripthash.EachofthestandardpubkeyscriptscanbeusedasaP2SHredeemscript,
butinpracticeonlythemultisigpubkeyscriptmakessenseuntilmoretransactiontypesaremadestandard.
Pubkey script: OP_HASH160 <Hash160(redeemScript)> OP_EQUAL
Signature script: <sig> [sig] [sig...] <redeemScript>

Multisig

AlthoughP2SHmultisigisnowgenerallyusedformultisigtransactions,thisbasescriptcanbeusedtorequiremultiplesignatures
beforeaUTXOcanbespent.
Inmultisigpubkeyscripts,calledmofn,mistheminimumnumberofsignatureswhichmustmatchapublickeynisthenumberof
publickeysbeingprovided.Bothmandnshouldbeopcodes OP_1through OP_16,correspondingtothenumberdesired.
BecauseofanoffbyoneerrorintheoriginalBitcoinimplementationwhichmustbepreservedforcompatibility, OP_CHECKMULTISIG
consumesonemorevaluefromthestackthanindicatedbym,sothelistofsecp256k1signaturesinthesignaturescriptmustbe
prefacedwithanextravalue( OP_0)whichwillbeconsumedbutnotused.
Thesignaturescriptmustprovidesignaturesinthesameorderasthecorrespondingpublickeysappearinthepubkeyscriptor
redeemscript.Seethedesciptionin OP_CHECKMULTISIGfordetails.
Pubkey script: <m> <A pubkey> [B pubkey] [C pubkey...] <n> OP_CHECKMULTISIG
Signature script: OP_0 <A sig> [B sig] [C sig...]

Althoughitsnotaseparatetransactiontype,thisisaP2SHmultisigwith2of3:
Pubkey script: OP_HASH160 <Hash160(redeemScript)> OP_EQUAL
Redeem script: <OP_2> <A pubkey> <B pubkey> <C pubkey> <OP_3> OP_CHECKMULTISIG
Signature script: OP_0 <A sig> <C sig> <redeemScript>

Pubkey

https://bitcoin.org/en/developer-guide

12/55

16/05/2015

Developer Guide - Bitcoin

PubkeyoutputsareasimplifiedformoftheP2PKHpubkeyscript,buttheyarentassecureasP2PKH,sotheygenerallyarent
usedinnewtransactionsanymore.
Pubkey script: <pubkey> OP_CHECKSIG
Signature script: <sig>

NullData

Nulldatapubkeyscriptsletyouaddasmallamountofarbitrarydatatotheblockchaininexchangeforpayingatransactionfee,
butdoingsoisdiscouraged.(Nulldataisastandardpubkeyscripttypeonlybecausesomepeoplewereaddingdatatotheblock
chaininmoreharmfulways.)
Pubkey Script: OP_RETURN <0 to 40 bytes of data>
(Null data scripts cannot be spent, so there's no signature script.)

NonStandardTransactions

Ifyouuseanythingbesidesastandardpubkeyscriptinanoutput,peersandminersusingthedefaultBitcoinCoresettingswill
neitheraccept,broadcast,normineyourtransaction.Whenyoutrytobroadcastyourtransactiontoapeerrunningthedefault
settings,youwillreceiveanerror.
Ifyoucreatearedeemscript,hashit,andusethehashinaP2SHoutput,thenetworkseesonlythehash,soitwillacceptthe
outputasvalidnomatterwhattheredeemscriptsays.Thisallowspaymenttononstandardpubkeyscriptalmostaseasilyas
paymenttostandardpubkeyscripts.However,whenyougotospendthatoutput,peersandminersusingthedefaultsettingswill
checktheredeemscripttoseewhetherornotitsastandardpubkeyscript.Ifitisnt,theywontprocessitfurthersoitwillbe
impossibletospendthatoutputuntilyoufindaminerwhodisablesthedefaultsettings.
Note:standardtransactionsaredesignedtoprotectandhelpthenetwork,notpreventyoufrommakingmistakes.Itseasyto
createstandardtransactionswhichmakethesatoshissenttothemunspendable.
AsofBitcoinCore0.9.3,standardtransactionsmustalsomeetthefollowingconditions:
Thetransactionmustbefinalized:eitheritslocktimemustbeinthepast(orlessthanorequaltothecurrentblockheight),orall
ofitssequencenumbersmustbe0xffffffff.
Thetransactionmustbesmallerthan100,000bytes.Thatsaround200timeslargerthanatypicalsingleinput,singleoutput
P2PKHtransaction.
Eachofthetransactionssignaturescriptsmustbesmallerthan1,650bytes.Thatslargeenoughtoallow15of15multisig
transactionsinP2SHusingcompressedpublickeys.
Bare(nonP2SH)multisigtransactionswhichrequiremorethan3publickeysarecurrentlynonstandard.
Thetransactionssignaturescriptmustonlypushdatatothescriptevaluationstack.ItcannotpushnewOPcodes,withthe
exceptionofOPcodeswhichsolelypushdatatothestack.
Thetransactionmustnotincludeanyoutputswhichreceivefewerthan1/3asmanysatoshisasitwouldtaketospenditina
typicalinput.Thatscurrently546satoshisforaP2PKHorP2SHoutputonaBitcoinCorenodewiththedefaultrelayfee.
Exception:standardnulldataoutputsmustreceivezerosatoshis.

https://bitcoin.org/en/developer-guide

13/55

16/05/2015

Developer Guide - Bitcoin

SignatureHashTypes
OP_CHECKSIGextractsanonstackargumentfromeachsignatureitevaluates,allowingthesignertodecidewhichpartsofthe

transactiontosign.Sincethesignatureprotectsthosepartsofthetransactionfrommodification,thisletssignersselectivelychoose
toletotherpeoplemodifytheirtransactions.
Thevariousoptionsforwhattosignarecalledsignaturehashtypes.TherearethreebaseSIGHASHtypescurrentlyavailable:
SIGHASH_ALL,thedefault,signsalltheinputsandoutputs,protectingeverythingexceptthesignaturescriptsagainst

modification.
SIGHASH_NONEsignsalloftheinputsbutnoneoftheoutputs,allowinganyonetochangewherethesatoshisaregoingunless

othersignaturesusingothersignaturehashflagsprotecttheoutputs.
SIGHASH_SINGLEsignsonlythisinputandonlyonecorrespondingoutput(theoutputwiththesameoutputindexnumberasthe
input),ensuringnobodycanchangeyourpartofthetransactionbutallowingothersignerstochangetheirpartofthetransaction.

Thecorrespondingoutputmustexistorthevalue1willbesigned,breakingthesecurityscheme.
Thebasetypescanbemodifiedwiththe SIGHASH_ANYONECANPAY(anyonecanpay)flag,creatingthreenewcombinedtypes:
SIGHASH_ALL|SIGHASH_ANYONECANPAYsignsalloftheoutputsbutonlythisoneinput,anditalsoallowsanyonetoaddorremove

otherinputs,soanyonecancontributeadditionalsatoshisbuttheycannotchangehowmanysatoshisaresentnorwherethey
go.
SIGHASH_NONE|SIGHASH_ANYONECANPAYsignsonlythisoneinputandallowsanyonetoaddorremoveotherinputsoroutputs,so

anyonewhogetsacopyofthisinputcanspendithowevertheydlike.
SIGHASH_SINGLE|SIGHASH_ANYONECANPAYsignsonlythisinputandonlyonecorrespondingoutput,butitalsoallowsanyoneto

addorremoveotherinputs.
Becauseeachinputissigned,atransactionwithmultipleinputscanhavemultiplesignaturehashtypessigningdifferentpartsof
thetransaction.Forexample,asingleinputtransactionsignedwith NONEcouldhaveitsoutputchangedbytheminerwhoaddsit
totheblockchain.Ontheotherhand,ifatwoinputtransactionhasoneinputsignedwith NONEandoneinputsignedwith ALL,
the ALLsignercanchoosewheretospendthesatoshiswithoutconsultingthe NONEsignerbutnobodyelsecanmodifythe
transaction.

LocktimeAndSequenceNumber
Onethingallsignaturehashtypessignisthetransactionslocktime.(CallednLockTimeintheBitcoinCoresourcecode.)The
locktimeindicatestheearliesttimeatransactioncanbeaddedtotheblockchain.
Locktimeallowssignerstocreatetimelockedtransactionswhichwillonlybecomevalidinthefuture,givingthesignersachanceto
changetheirminds.
Ifanyofthesignerschangetheirmind,theycancreateanewnonlocktimetransaction.Thenewtransactionwilluse,asoneofits
inputs,oneofthesameoutputswhichwasusedasaninputtothelocktimetransaction.Thismakesthelocktimetransactioninvalid
ifthenewtransactionisaddedtotheblockchainbeforethetimelockexpires.
Caremustbetakenneartheexpirytimeofatimelock.Thepeertopeernetworkallowsblocktimetobeuptotwohoursaheadof
realtime,soalocktimetransactioncanbeaddedtotheblockchainuptotwohoursbeforeitstimelockofficiallyexpires.Also,
blocksarenotcreatedatguaranteedintervals,soanyattempttocancelavaluabletransactionshouldbemadeafewhoursbefore
thetimelockexpires.
PreviousversionsofBitcoinCoreprovidedafeaturewhichpreventedtransactionsignersfromusingthemethoddescribedabove
https://bitcoin.org/en/developer-guide

14/55

16/05/2015

Developer Guide - Bitcoin

tocancelatimelockedtransaction,butanecessarypartofthisfeaturewasdisabledtopreventdenialofserviceattacks.Alegacy
ofthissystemarefourbytesequencenumbersineveryinput.Sequencenumbersweremeanttoallowmultiplesignerstoagreeto
updateatransactionwhentheyfinishedupdatingthetransaction,theycouldagreetoseteveryinputssequencenumbertothe
fourbyteunsignedmaximum(0xffffffff),allowingthetransactiontobeaddedtoablockevenifitstimelockhadnotexpired.
Eventoday,settingallsequencenumbersto0xffffffff(thedefaultinBitcoinCore)canstilldisablethetimelock,soifyouwantto
uselocktime,atleastoneinputmusthaveasequencenumberbelowthemaximum.Sincesequencenumbersarenotusedbythe
networkforanyotherpurpose,settinganysequencenumbertozeroissufficienttoenablelocktime.
Locktimeitselfisanunsigned4byteintegerwhichcanbeparsedtwoways:
Iflessthan500million,locktimeisparsedasablockheight.Thetransactioncanbeaddedtoanyblockwhichhasthisheightor
higher.
Ifgreaterthanorequalto500million,locktimeisparsedusingtheUnixepochtimeformat(thenumberofsecondselapsed
since19700101T00:00UTCcurrentlyover1.395billion).Thetransactioncanbeaddedtoanyblockwhoseblocktimeis
greaterthanthelocktime.

TransactionFeesAndChange
Transactionstypicallypaytransactionfeesbasedonthetotalbytesizeofthesignedtransaction.Thetransactionfeeisgiventothe
Bitcoinminer,asexplainedintheblockchainsection,andsoitisultimatelyuptoeachminertochoosetheminimumtransaction
feetheywillaccept.
Bydefault,minersreserve50KBofeachblockforhighprioritytransactionswhichspendsatoshisthathaventbeenspentfora
longtime.Theremainingspaceineachblockistypicallyallocatedtotransactionsbasedontheirfeeperbyte,withhigherpaying
transactionsbeingaddedinsequenceuntilalloftheavailablespaceisfilled.
AsofBitcoinCore0.9,transactionswhichdonotcountashighprioritytransactionsneedtopayaminimumfee(currently1,000
satoshis)tobebroadcastacrossthenetwork.Anytransactionpayingonlytheminimumfeeshouldbepreparedtowaitalongtime
beforetheresenoughsparespaceinablocktoincludeit.Pleaseseetheverifyingpaymentsectionforwhythiscouldbe
important.
SinceeachtransactionspendsUnspentTransactionOutputs(UTXOs)andbecauseaUTXOcanonlybespentonce,thefullvalue
oftheincludedUTXOsmustbespentorgiventoaminerasatransactionfee.FewpeoplewillhaveUTXOsthatexactlymatchthe
amounttheywanttopay,somosttransactionsincludeachangeoutput.
ChangeoutputsareregularoutputswhichspendthesurplussatoshisfromtheUTXOsbacktothespender.Theycanreusethe
sameP2PKHpubkeyhashorP2SHscripthashaswasusedintheUTXO,butforthereasonsdescribedinthenextsubsection,it
ishighlyrecommendedthatchangeoutputsbesenttoanewP2PKHorP2SHaddress.

AvoidingKeyReuse
Inatransaction,thespenderandreceivereachrevealtoeachotherallpublickeysoraddressesusedinthetransaction.This
allowseitherpersontousethepublicblockchaintotrackpastandfuturetransactionsinvolvingtheotherpersonssamepublic
keysoraddresses.
Ifthesamepublickeyisreusedoften,ashappenswhenpeopleuseBitcoinaddresses(hashedpublickeys)asstaticpayment
addresses,otherpeoplecaneasilytrackthereceivingandspendinghabitsofthatperson,includinghowmanysatoshisthey
controlinknownaddresses.
Itdoesnthavetobethatway.Ifeachpublickeyisusedexactlytwiceoncetoreceiveapaymentandoncetospendthatpayment
https://bitcoin.org/en/developer-guide

15/55

16/05/2015

Developer Guide - Bitcoin

theusercangainasignificantamountoffinancialprivacy.
Evenbetter,usingnewpublickeysoruniqueaddresseswhenacceptingpaymentsorcreatingchangeoutputscanbecombined
withothertechniquesdiscussedlater,suchasCoinJoinormergeavoidance,tomakeitextremelydifficulttousetheblockchainby
itselftoreliablytrackhowusersreceiveandspendtheirsatoshis.
Avoidingkeyreusecanalsoprovidesecurityagainstattackswhichmightallowreconstructionofprivatekeysfrompublickeys
(hypothesized)orfromsignaturecomparisons(possibletodayundercertaincircumstancesdescribedbelow,withmoregeneral
attackshypothesized).
1. Unique(nonreused)P2PKHandP2SHaddressesprotectagainstthefirsttypeofattackbykeepingECDSApublickeyshidden
(hashed)untilthefirsttimesatoshissenttothoseaddressesarespent,soattacksareeffectivelyuselessunlesstheycan
reconstructprivatekeysinlessthanthehourortwoittakesforatransactiontobewellprotectedbytheblockchain.
2. Unique(nonreused)privatekeysprotectagainstthesecondtypeofattackbyonlygeneratingonesignatureperprivatekey,so
attackersnevergetasubsequentsignaturetouseincomparisonbasedattacks.Existingcomparisonbasedattacksareonly
practicaltodaywheninsufficiententropyisusedinsigningorwhentheentropyusedisexposedbysomemeans,suchasa
sidechannelattack.
So,forbothprivacyandsecurity,weencourageyoutobuildyourapplicationstoavoidpublickeyreuseand,whenpossible,to
discourageusersfromreusingaddresses.IfyourapplicationneedstoprovideafixedURItowhichpaymentsshouldbesent,
pleaseseethe bitcoin:URIsectionbelow.

TransactionMalleability
NoneofBitcoinssignaturehashtypesprotectthesignaturescript,leavingthedooropenforalimiteddenialofserviceattackcalled
transactionmalleability.Thesignaturescriptcontainsthesecp256k1signature,whichcantsignitself,allowingattackerstomake
nonfunctionalmodificationstoatransactionwithoutrenderingitinvalid.Forexample,anattackercanaddsomedatatothe
signaturescriptwhichwillbedroppedbeforethepreviouspubkeyscriptisprocessed.
Althoughthemodificationsarenonfunctionalsotheydonotchangewhatinputsthetransactionusesnorwhatoutputsitpays
theydochangethecomputedhashofthetransaction.Sinceeachtransactionlinkstoprevioustransactionsusinghashesasa
transactionidentifier(txid),amodifiedtransactionwillnothavethetxiditscreatorexpected.
ThisisntaproblemformostBitcointransactionswhicharedesignedtobeaddedtotheblockchainimmediately.Butitdoes
becomeaproblemwhentheoutputfromatransactionisspentbeforethattransactionisaddedtotheblockchain.
Bitcoindevelopershavebeenworkingtoreducetransactionmalleabilityamongstandardtransactiontypes,butacompletefixis
stillonlyintheplanningstages.Atpresent,newtransactionsshouldnotdependonprevioustransactionswhichhavenotbeen
addedtotheblockchainyet,especiallyiflargeamountsofsatoshisareatstake.
Transactionmalleabilityalsoaffectspaymenttracking.BitcoinCoresRPCinterfaceletsyoutracktransactionsbytheirtxidbutif
thattxidchangesbecausethetransactionwasmodified,itmayappearthatthetransactionhasdisappearedfromthenetwork.
Currentbestpracticesfortransactiontrackingdictatethatatransactionshouldbetrackedbythetransactionoutputs(UTXOs)it
spendsasinputs,astheycannotbechangedwithoutinvalidatingthetransaction.
Bestpracticesfurtherdictatethatifatransactiondoesseemtodisappearfromthenetworkandneedstobereissued,thatitbe
reissuedinawaythatinvalidatesthelosttransaction.Onemethodwhichwillalwaysworkistoensurethereissuedpayment
spendsallofthesameoutputsthatthelosttransactionusedasinputs.

Contracts
https://bitcoin.org/en/developer-guide

16/55

16/05/2015

Developer Guide - Bitcoin

ContractsaretransactionswhichusethedecentralizedBitcoinsystemtoenforcefinancialagreements.Bitcoincontractscanoften
becraftedtominimizedependencyonoutsideagents,suchasthecourtsystem,whichsignificantlydecreasestheriskofdealing
withunknownentitiesinfinancialtransactions.
ThefollowingsubsectionswilldescribeavarietyofBitcoincontractsalreadyinuse.Becausecontractsdealwithrealpeople,not
justtransactions,theyareframedbelowinstoryformat.
Besidesthecontracttypesdescribedbelow,manyothercontracttypeshavebeenproposed.Severalofthemarecollectedonthe
ContractspageoftheBitcoinWiki.

EscrowAndArbitration
CharliethecustomerwantstobuyaproductfromBobthebusinessman,butneitherofthemtruststheotherperson,sotheyusea
contracttohelpensureCharliegetshismerchandiseandBobgetshispayment.
AsimplecontractcouldsaythatCharliewillspendsatoshistoanoutputwhichcanonlybespentifCharlieandBobbothsignthe
inputspendingit.ThatmeansBobwontgetpaidunlessCharliegetshismerchandise,butCharliecantgetthemerchandiseand
keephispayment.
Thissimplecontractisntmuchhelpiftheresadispute,soBobandCharlieenlistthehelpofAlicethearbitratortocreatean
escrowcontract.Charliespendshissatoshistoanoutputwhichcanonlybespentiftwoofthethreepeoplesigntheinput.Now
CharliecanpayBobifeverythingisok,BobcanrefundCharliesmoneyiftheresaproblem,orAlicecanarbitrateanddecidewho
shouldgetthesatoshisiftheresadispute.
Tocreateamultiplesignature(multisig)output,theyeachgivetheothersapublickey.ThenBobcreatesthefollowingP2SH
multisigredeemscript:
OP_2 [A's pubkey] [B's pubkey] [C's pubkey] OP_3 OP_CHECKMULTISIG

(Opcodestopushthepublickeysontothestackarenotshown.)
OP_2and OP_3pushtheactualnumbers2and3ontothestack. OP_2specifiesthat2signaturesarerequiredtosign OP_3
specifiesthat3publickeys(unhashed)arebeingprovided.Thisisa2of3multisigpubkeyscript,moregenericallycalledamofn

pubkeyscript(wheremistheminimummatchingsignaturesrequiredandninthenumberofpublickeysprovided).
BobgivestheredeemscripttoCharlie,whocheckstomakesurehispublickeyandAlicespublickeyareincluded.Thenhe
hashestheredeemscripttocreateaP2SHredeemscriptandpaysthesatoshistoit.Bobseesthepaymentgetaddedtotheblock
chainandshipsthemerchandise.
Unfortunately,themerchandisegetsslightlydamagedintransit.Charliewantsafullrefund,butBobthinksa10%refundis
sufficient.TheyturntoAlicetoresolvetheissue.AliceasksforphotoevidencefromCharliealongwithacopyoftheredeemscript
BobcreatedandCharliechecked.
Afterlookingattheevidence,Alicethinksa40%refundissufficient,soshecreatesandsignsatransactionwithtwooutputs,one
thatspends60%ofthesatoshistoBobspublickeyandonethatspendstheremaining40%toCharliespublickey.
InthesignaturescriptAliceputshersignatureandacopyoftheunhashedserializedredeemscriptthatBobcreated.Shegivesa
copyoftheincompletetransactiontobothBobandCharlie.Eitheroneofthemcancompleteitbyaddinghissignaturetocreatethe
followingsignaturescript:
OP_0 [A's signature] [B's or C's signature] [serialized redeem script]

https://bitcoin.org/en/developer-guide

17/55

16/05/2015

Developer Guide - Bitcoin

(Opcodestopushthesignaturesandredeemscriptontothestackarenotshown. OP_0isaworkaroundforanoffbyoneerrorin
theoriginalimplementationwhichmustbepreservedforcompatibility.Notethatthesignaturescriptmustprovidesignaturesinthe
sameorderasthecorrespondingpublickeysappearintheredeemscript.Seethedescriptionin OP_CHECKMULTISIGfordetails.)
Whenthetransactionisbroadcasttothenetwork,eachpeerchecksthesignaturescriptagainsttheP2SHoutputCharlie
previouslypaid,ensuringthattheredeemscriptmatchestheredeemscripthashpreviouslyprovided.Thentheredeemscriptis
evaluated,withthetwosignaturesbeingusedasinputdata.Assumingtheredeemscriptvalidates,thetwotransactionoutputs
showupinBobsandCharlieswalletsasspendablebalances.
However,ifAlicecreatedandsignedatransactionneitherofthemwouldagreeto,suchasspendingallthesatoshistoherself,Bob
andCharliecanfindanewarbitratorandsignatransactionspendingthesatoshistoanother2of3multisigredeemscripthash,
thisoneincludingapublickeyfromthatsecondarbitrator.ThismeansthatBobandCharlieneverneedtoworryabouttheir
arbitratorstealingtheirmoney.
Resource:BitRatedprovidesamultisigarbitrationserviceinterfaceusingHTML/JavaScriptonaGNUAGPLlicensedwebsite.

MicropaymentChannel
AlicealsoworksparttimemoderatingforumpostsforBob.EverytimesomeonepoststoBobsbusyforum,Aliceskimsthepostto
makesureitisntoffensiveorspam.Alas,Boboftenforgetstopayher,soAlicedemandstobepaidimmediatelyaftereachpost
sheapprovesorrejects.Bobsayshecantdothatbecausehundredsofsmallpaymentswillcosthimthousandsofsatoshisin
transactionfees,soAlicesuggeststheyuseamicropaymentchannel.
BobasksAliceforherpublickeyandthencreatestwotransactions.Thefirsttransactionpays100millibitcoinstoaP2SHoutput
whose2of2multisigredeemscriptrequiressignaturesfrombothAliceandBob.Thisisthebondtransaction.Broadcastingthis
transactionwouldletAliceholdthemillibitcoinshostage,soBobkeepsthistransactionprivatefornowandcreatesasecond
transaction.
Thesecondtransactionspendsallofthefirsttransactionsmillibitcoins(minusatransactionfee)backtoBobaftera24hourdelay
enforcedbylocktime.Thisistherefundtransaction.Bobcantsigntherefundtransactionbyhimself,sohegivesittoAlicetosign,
asshownintheillustrationbelow.

https://bitcoin.org/en/developer-guide

18/55

16/05/2015

Developer Guide - Bitcoin

B: Please sign refund version 1,

which is a full refund of the bond
that can't be spent for 24 hours
Alice's Computer
(Server)

A: Signed; please send me the bond to

prove you funded the account

Bob's Computer
(Client)
Refund v1
Bob: 100
Alice: 0
(Locktime)

B: Here's the bond; please start working

Bond
(2-of-2
multisig)

A: Some work done; please sign refund v2

reducing your refund by 1 mBTC
B: Signed; refund now pays Bob: 99; Alice: 1
A: More work done; please sign v3
reducing your refund by another 1 mBTC
B: Signed; refund now pays Bob: 98; Alice: 2

Refund v45
Bob: 66
Alice: 44
(No Lock)

A: [...]
B: [...]
A: I'm done for the day. I'm
going to broadcast refund v45

Alice broadcasts the bond to the Bitcoin network immediately.

She broadcasts the final version of the refund when she finishes work
or before the locktime. If she fails to broadcast before refund v1's time lock
expires, Bob can broadcast refund v1 to get a full refund.
Bitcoin Micropayment Channels (As Implemented In Bitcoinj)

Alicechecksthattherefundtransactionslocktimeis24hoursinthefuture,signsit,andgivesacopyofitbacktoBob.Shethen
asksBobforthebondtransactionandchecksthattherefundtransactionspendstheoutputofthebondtransaction.Shecannow
broadcastthebondtransactiontothenetworktoensureBobhastowaitforthetimelocktoexpirebeforefurtherspendinghis
millibitcoins.Bobhasntactuallyspentanythingsofar,exceptpossiblyasmalltransactionfee,andhellbeabletobroadcastthe
refundtransactionin24hoursforafullrefund.
Now,whenAlicedoessomeworkworth1millibitcoin,sheasksBobtocreateandsignanewversionoftherefundtransaction.
Versiontwoofthetransactionspends1millibitcointoAliceandtheother99backtoBobitdoesnothavealocktime,soAlicecan
signitandspenditwhenevershewants.(Butshedoesntdothatimmediately.)
AliceandBobrepeattheseworkandpaystepsuntilAlicefinishesfortheday,oruntilthetimelockisabouttoexpire.Alicesigns
thefinalversionoftherefundtransactionandbroadcastsit,payingherselfandrefundinganyremainingbalancetoBob.Thenext
day,whenAlicestartswork,theycreateanewmicropaymentchannel.
IfAlicefailstobroadcastaversionoftherefundtransactionbeforeitstimelockexpires,Bobcanbroadcastthefirstversionand
receiveafullrefund.ThisisonereasonmicropaymentchannelsarebestsuitedtosmallpaymentsifAlicesInternetservicegoes
outforafewhoursnearthetimelockexpiry,shecouldbecheatedoutofherpayment.
Transactionmalleability,discussedaboveintheTransactionssection,isanotherreasontolimitthevalueofmicropayment
channels.Ifsomeoneusestransactionmalleabilitytobreakthelinkbetweenthetwotransactions,AlicecouldholdBobs100
millibitcoinshostageevenifshehadntdoneanywork.
Forlargerpayments,Bitcointransactionfeesareverylowasapercentageofthetotaltransactionvalue,soitmakesmoresenseto
protectpaymentswithimmediatelybroadcastseparatetransactions.
Resource:ThebitcoinjJavalibraryprovidesacompletesetofmicropaymentfunctions,anexampleimplementation,andatutorial
allunderanApachelicense.

CoinJoin
https://bitcoin.org/en/developer-guide

19/55

16/05/2015

Developer Guide - Bitcoin

Aliceisconcernedaboutherprivacy.Sheknowseverytransactiongetsaddedtothepublicblockchain,sowhenBobandCharlie
payher,theycaneacheasilytrackthosesatoshistolearnwhatBitcoinaddressesshepays,howmuchshepaysthem,and
possiblyhowmanysatoshisshehasleft.
Aliceisntacriminal,shejustwantsplausibledeniabilityaboutwhereshehasspenthersatoshisandhowmanyshehasleft,so
shestartsuptheToranonymityserviceonhercomputerandlogsintoanIRCchatroomasAnonGirl.
AlsointhechatroomareNemoandNeminem.Theycollectivelyagreetotransfersatoshisbetweeneachothersonoone
besidesthemcanreliablydeterminewhocontrolswhichsatoshis.Buttheyrefacedwithadilemma:whotransferstheirsatoshisto
oneoftheothertwopseudonymouspersonsfirst?TheCoinJoinstylecontract,shownintheillustrationbelow,makesthisdecision
easy:theycreateasingletransactionwhichdoesallofthespendingsimultaneously,ensuringnoneofthemcanstealtheothers
satoshis.
Neminem's UTXOs
100 mBTC

CoinJoin Transaction
Inputs

AnonGirl's UTXOs
From Bob
From Charlie

55 mBTC
25 mBTC
20 mBTC
Nemo's UTXOs
10 mBTC
90 mBTC

Outputs
100 mBTC

Person 1

100 mBTC

Person 2

100 mBTC

Person 3

Example CoinJoin Transaction

Only the participants know who gets which output.

EachcontributorlooksthroughtheircollectionofUnspentTransactionOutputs(UTXOs)for100millibitcoinstheycanspend.They
theneachgenerateabrandnewpublickeyandgiveUTXOdetailsandpubkeyhashestothefacilitator.Inthiscase,thefacilitator
isAnonGirlshecreatesatransactionspendingeachoftheUTXOstothreeequallysizedoutputs.Oneoutputgoestoeachofthe
contributorspubkeyhashes.
AnonGirlthensignsherinputsusing SIGHASH_ALLtoensurenobodycanchangetheinputoroutputdetails.Shegivesthe
partiallysignedtransactiontoNemowhosignshisinputsthesamewayandpassesittoNeminem,whoalsosignsitthesameway.
Neminemthenbroadcaststhetransactiontothepeertopeernetwork,mixingallofthemillibitcoinsinasingletransaction.
Asyoucanseeintheillustration,theresnowayforanyonebesidesAnonGirl,Nemo,andNeminemtoconfidentlydeterminewho
receivedwhichoutput,sotheycaneachspendtheiroutputwithplausibledeniability.
NowwhenBoborCharlietrytotrackAlicestransactionsthroughtheblockchain,theyllalsoseetransactionsmadebyNemoand
https://bitcoin.org/en/developer-guide

20/55

16/05/2015

Developer Guide - Bitcoin

Neminem.IfAlicedoesafewmoreCoinJoins,BobandCharliemighthavetoguesswhichtransactionsmadebydozensor
hundredsofpeoplewereactuallymadebyAlice.
ThecompletehistoryofAlicessatoshisisstillintheblockchain,soadeterminedinvestigatorcouldtalktothepeopleAnonGirl
CoinJoinedwithtofindouttheultimateoriginofhersatoshisandpossiblyrevealAnonGirlasAlice.Butagainstanyonecasually
browsingblockchainhistory,Alicegainsplausibledeniability.
TheCoinJointechniquedescribedabovecoststheparticipantsasmallamountofsatoshistopaythetransactionfee.Analternative
technique,purchaserCoinJoin,canactuallysavethemsatoshisandimprovetheirprivacyatthesametime.
AnonGirlwaitsintheIRCchatroomuntilshewantstomakeapurchase.Sheannouncesherintentiontospendsatoshisandwaits
untilsomeoneelsewantstomakeapurchase,likelyfromadifferentmerchant.Thentheycombinetheirinputsthesamewayas
beforebutsettheoutputstotheseparatemerchantaddressessonobodywillbeabletofigureoutsolelyfromblockchainhistory
whichoneofthemboughtwhatfromthemerchants.
Sincetheywouldvehadtopayatransactionfeetomaketheirpurchasesanyway,AnonGirlandhercospendersdontpay
anythingextrabutbecausetheyreducedoverheadbycombiningmultipletransactions,savingbytes,theymaybeabletopaya
smalleraggregatetransactionfee,savingeachoneofthematinyamountofsatoshis.
Resource:Analphaquality(asofthiswriting)implementationofdecentralizedCoinJoinisCoinMux,availableundertheApache
license.

Wallets
ABitcoinwalletcanrefertoeitherawalletprogramorawalletfile.Walletprogramscreatepublickeystoreceivesatoshisanduse
thecorrespondingprivatekeystospendthosesatoshis.Walletfilesstoreprivatekeysand(optionally)otherinformationrelatedto
transactionsforthewalletprogram.
Walletprogramsandwalletfilesareaddressedbelowinseparatesubsections,andthisdocumentattemptstoalwaysmakeitclear
whetherweretalkingaboutwalletprogramsorwalletfiles.

WalletPrograms
Permittingreceivingandspendingofsatoshisistheonlyessentialfeatureofwalletsoftwarebutaparticularwalletprogram
doesntneedtodoboththings.Twowalletprogramscanworktogether,oneprogramdistributingpublickeysinordertoreceive
satoshisandanotherprogramsigningtransactionsspendingthosesatoshis.
Walletprogramsalsoneedtointeractwiththepeertopeernetworktogetinformationfromtheblockchainandtobroadcastnew
transactions.However,theprogramswhichdistributepublickeysorsigntransactionsdontneedtointeractwiththepeertopeer
networkthemselves.
Thisleavesuswiththreenecessary,butseparable,partsofawalletsystem:apublickeydistributionprogram,asigningprogram,
andanetworkedprogram.Inthesubsectionsbelow,wewilldescribecommoncombinationsoftheseparts.
Note:wespeakaboutdistributingpublickeysgenerically.Inmanycases,P2PKHorP2SHhasheswillbedistributedinsteadof
publickeys,withtheactualpublickeysonlybeingdistributedwhentheoutputstheycontrolarespent.

FullServiceWallets

Thesimplestwalletisaprogramwhichperformsallthreefunctions:itgeneratesprivatekeys,derivesthecorrespondingpublic
https://bitcoin.org/en/developer-guide

21/55

16/05/2015

Developer Guide - Bitcoin

keys,helpsdistributethosepublickeysasnecessary,monitorsforoutputsspenttothosepublickeys,createsandsigns
transactionsspendingthoseoutputs,andbroadcaststhesignedtransactions.

Full-Service Wallet
Create
Private
Keys

Derive
Public
Keys

Distribute
Public
Keys

Monitor
For
Outputs

Create
Unsigned
Txes

Sign
Txes

Broadcast
Txes

Asofthiswriting,almostallpopularwalletscanbeusedasfullservicewallets.
Themainadvantageoffullservicewalletsisthattheyareeasytouse.Asingleprogramdoeseverythingtheuserneedstoreceive
andspendsatoshis.
ThemaindisadvantageoffullservicewalletsisthattheystoretheprivatekeysonadeviceconnectedtotheInternet.The
compromiseofsuchdevicesisacommonoccurrence,andanInternetconnectionmakesiteasytotransmitprivatekeysfroma
compromiseddevicetoanattacker.
Tohelpprotectagainsttheft,manywalletprogramsofferuserstheoptionofencryptingthewalletfileswhichcontaintheprivate
keys.Thisprotectstheprivatekeyswhentheyarentbeingused,butitcannotprotectagainstanattackdesignedtocapturethe
encryptionkeyortoreadthedecryptedkeysfrommemory.

SigningOnlyWallets

Toincreasesecurity,privatekeyscanbegeneratedandstoredbyaseparatewalletprogramoperatinginamoresecure
environment.Thesesigningonlywalletsworkinconjunctionwithanetworkedwalletwhichinteractswiththepeertopeernetwork.
Signingonlywalletsprogramstypicallyusedeterministickeycreation(describedinalatersubsection)tocreateparentprivateand
publickeyswhichcancreatechildprivateandpublickeys.
Signing-Only Wallet
Create
Parent
Private
Key

Derive
Parent
Public
Key

Sign
Txes
Networked Wallet

Derive
Child
Public
Keys

Distribute
Public
Keys

Monitor
For
Outputs

Create
Unsigned
Txes

Broadcast
Txes

Whenfirstrun,thesigningonlywalletcreatesaparentprivatekeyandtransfersthecorrespondingparentpublickeytothe
networkedwallet.
Thenetworkedwalletusestheparentpublickeytoderivechildpublickeys,optionallyhelpsdistributethem,monitorsforoutputs
spenttothosepublickeys,createsunsignedtransactionsspendingthoseoutputs,andtransferstheunsignedtransactionstothe
signingonlywallet.
Often,usersaregivenachancetoreviewtheunsignedtransactionsdetails(particularlytheoutputdetails)usingthesigningonly
wallet.
Aftertheoptionalreviewstep,thesigningonlywalletusestheparentprivatekeytoderivetheappropriatechildprivatekeysand
signsthetransactions,givingthesignedtransactionsbacktothenetworkedwallet.
https://bitcoin.org/en/developer-guide

22/55

16/05/2015

Developer Guide - Bitcoin

Thenetworkedwalletthenbroadcaststhesignedtransactionstothepeertopeernetwork.
Thefollowingsubsectionsdescribethetwomostcommonvariantsofsigningonlywallets:offlinewalletsandhardwarewallets.

OfflineWallets

Severalfullservicewalletsprogramswillalsooperateastwoseparatewallets:oneprograminstanceactingasasigningonly
wallet(oftencalledanofflinewallet)andtheotherprograminstanceactingasthenetworkedwallet(oftencalledanonlinewallet
orwatchingonlywallet).
Theofflinewalletissonamedbecauseitisintendedtoberunonadevicewhichdoesnotconnecttoanynetwork,greatlyreducing
thenumberofattackvectors.Ifthisisthecase,itisusuallyuptotheusertohandlealldatatransferusingremovablemediasuch
asUSBdrives.Theusersworkflowissomethinglike:
1. (Offline)Disableallnetworkconnectionsonadeviceandinstallthewalletsoftware.Startthewalletsoftwareinofflinemodeto
createtheparentprivateandpublickeys.Copytheparentpublickeytoremovablemedia.
2. (Online)Installthewalletsoftwareonanotherdevice,thisoneconnectedtotheInternet,andimporttheparentpublickeyfrom
theremovablemedia.Asyouwouldwithafullservicewallet,distributepublickeystoreceivepayment.Whenreadytospend
satoshis,fillintheoutputdetailsandsavetheunsignedtransactiongeneratedbythewallettoremovablemedia.
3. (Offline)Opentheunsignedtransactionintheofflineinstance,reviewtheoutputdetailstomakesuretheyspendthecorrect
amounttothecorrectaddress.Thispreventsmalwareontheonlinewalletfromtrickingtheuserintosigningatransactionwhich
paysanattacker.Afterreview,signthetransactionandsaveittoremovablemedia.
4. (Online)Openthesignedtransactionintheonlineinstancesoitcanbroadcastittothepeertopeernetwork.
Theprimaryadvantageofofflinewalletsistheirpossibilityforgreatlyimprovedsecurityoverfullservicewallets.Aslongasthe
offlinewalletisnotcompromised(orflawed)andtheuserreviewsalloutgoingtransactionsbeforesigning,theuserssatoshisare
safeeveniftheonlinewalletiscompromised.
Theprimarydisadvantageofofflinewalletsishassle.Formaximumsecurity,theyrequiretheuserdedicateadevicetoonlyoffline
tasks.Theofflinedevicemustbebootedupwheneverfundsaretobespent,andtheusermustphysicallycopydatafromthe
onlinedevicetotheofflinedeviceandback.

HardwareWallets

Hardwarewalletsaredevicesdedicatedtorunningasigningonlywallet.Theirdedicationletsthemeliminatemanyofthe
vulnerabilitiespresentinoperatingsystemsdesignedforgeneraluse,allowingthemtosafelycommunicatedirectlywithother
devicessousersdontneedtotransferdatamanually.Theusersworkflowissomethinglike:
1. (Hardware)Createparentprivateandpublickeys.Connecthardwarewallettoanetworkeddevicesoitcangettheparentpublic
key.
2. (Networked)Asyouwouldwithafullservicewallet,distributepublickeystoreceivepayment.Whenreadytospendsatoshis,fill
inthetransactiondetails,connectthehardwarewallet,andclickSpend.Thenetworkedwalletwillautomaticallysendthe
transactiondetailstothehardwarewallet.
3. (Hardware)Reviewthetransactiondetailsonthehardwarewalletsscreen.Somehardwarewalletsmaypromptfora
passphraseorPINnumber.Thehardwarewalletsignsthetransactionanduploadsittothenetworkedwallet.
4. (Networked)Thenetworkedwalletreceivesthesignedtransactionfromthehardwarewalletandbroadcastsittothenetwork.

https://bitcoin.org/en/developer-guide

23/55

16/05/2015

Developer Guide - Bitcoin

Theprimaryadvantageofhardwarewalletsistheirpossibilityforgreatlyimprovedsecurityoverfullservicewalletswithmuchless
hasslethanofflinewallets.
Theprimarydisadvantageofhardwarewalletsistheirhassle.Eventhoughthehassleislessthanthatofofflinewallets,theuser
muststillpurchaseahardwarewalletdeviceandcarryitwiththemwhenevertheyneedtomakeatransactionusingthesigning
onlywallet.
Anadditional(hopefullytemporary)disadvantageisthat,asofthiswriting,veryfewpopularwalletprogramssupporthardware
walletsalthoughalmostallpopularwalletprogramshaveannouncedtheirintentiontosupportatleastonemodelofhardware
wallet.

DistributingOnlyWallets

Walletprogramswhichrunindifficulttosecureenvironments,suchaswebservers,canbedesignedtodistributepublickeys
(includingP2PKHorP2SHaddresses)andnothingmore.Therearetwocommonwaystodesigntheseminimalistwallets:
Distributing-Only Wallet
Derive
Child
Public
Keys

Distribute
Public
Keys
Other Wallet(s)

Create
Parent
Private
Key

Derive
Parent
Public
Key

Monitor
For
Outputs

Create
Unsigned
Txes

Sign
Txes

Broadcast
Txes

Prepopulateadatabasewithanumberofpublickeysoraddresses,andthendistributeonrequestapubkeyscriptoraddress
usingoneofthedatabaseentries.Toavoidkeyreuse,webserversshouldkeeptrackofusedkeysandneverrunoutofpublic
keys.Thiscanbemadeeasierbyusingparentpublickeysassuggestedinthenextmethod.
Useaparentpublickeytocreatechildpublickeys.Toavoidkeyreuse,amethodmustbeusedtoensurethesamepublickey
isntdistributedtwice.Thiscanbeadatabaseentryforeachkeydistributedoranincrementingpointertothekeyindexnumber.
Neithermethodaddsasignificantamountofoverhead,especiallyifadatabaseisusedanywaytoassociateeachincoming
paymentwithaseparatepublickeyforpaymenttracking.SeethePaymentProcessingsectionfordetails.

WalletFiles
Bitcoinwalletsattheircoreareacollectionofprivatekeys.Thesecollectionsarestoreddigitallyinafile,orcanevenbephysically
storedonpiecesofpaper.

PrivateKeyFormats

Privatekeysarewhatareusedtounlocksatoshisfromaparticularaddress.InBitcoin,aprivatekeyinstandardformatissimplya
256bitnumber,betweenthevalues:
0x01and0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364140,representing
nearlytheentirerangeof22561values.Therangeisgovernedbythesecp256k1ECDSAencryptionstandardusedbyBitcoin.

https://bitcoin.org/en/developer-guide

24/55

16/05/2015

Developer Guide - Bitcoin

WalletImportFormat(WIF)

Inordertomakecopyingofprivatekeyslesspronetoerror,WalletImportFormatmaybeutilized.WIFusesbase58Check
encodingonanprivatekey,greatlydecreasingthechanceofcopyingerror,muchlikestandardBitcoinaddresses.
1. Takeaprivatekey.
2. Adda0x80byteinfrontofitformainnetaddressesor0xeffortestnetaddresses.
3. Appenda0x01byteafteritifitshouldbeusedwithcompressedpublickeys(describedinalatersubsection).Nothingis
appendedifitisusedwithuncompressedpublickeys.
4. PerformaSHA256hashontheextendedkey.
5. PerformaSHA256hashonresultofSHA256hash.
6. TakethefirstfourbytesofthesecondSHA256hashthisisthechecksum.
7. Addthefourchecksumbytesfrompoint5attheendoftheextendedkeyfrompoint2.
8. ConverttheresultfromabytestringintoaBase58stringusingBase58Checkencoding.
Theprocessiseasilyreversible,usingtheBase58decodingfunction,andremovingthepadding.

MiniPrivateKeyFormat

Miniprivatekeyformatisamethodforencodingaprivatekeyinunder30characters,enablingkeystobeembeddedinasmall
physicalspace,suchasphysicalbitcointokens,andmoredamageresistantQRcodes.
1. ThefirstcharacterofminikeysisS.
2. Inordertodetermineifaminiprivatekeyiswellformatted,aquestionmarkisaddedtotheprivatekey.
3. TheSHA256hashiscalculated.Ifthefirstbyteproducedisa`00,itiswellformatted.Thiskeyrestrictionactsasatypo
checkingmechanism.Auserbruteforcestheprocessusingrandomnumbersuntilawellformattedminiprivatekeyisproduced.
4. Inordertoderivethefullprivatekey,theusersimplytakesasingleSHA256hashoftheoriginalminiprivatekey.Thisprocessis
oneway:itisintractabletocomputetheminiprivatekeyformatfromthederivedkey.
Manyimplementationsdisallowthecharacter1intheminiprivatekeyduetoitsvisualsimilaritytol.
Resource:AcommontooltocreateandredeemthesekeysistheCasasciusBitcoinAddressUtility.

PublicKeyFormats

BitcoinECDSApublickeysrepresentapointonaparticularEllipticCurve(EC)definedinsecp256k1.Intheirtraditional
uncompressedform,publickeyscontainanidentificationbyte,a32byteXcoordinate,anda32byteYcoordinate.Theextremely
simplifiedillustrationbelowshowssuchapointontheellipticcurveusedbyBitcoin,x2=y3+7,overafieldofcontiguousnumbers.

https://bitcoin.org/en/developer-guide

25/55

16/05/2015

Developer Guide - Bitcoin

4
3
2
1
0
-1
-2
-3
-4

sqrt(x**3+7)
-sqrt(x**3+7)
x,y=1.00,2.83

-2

(Secp256k1actuallymoduloscoordinatesbyalargeprime,whichproducesafieldofnoncontiguousintegersandasignificantly
lessclearplot,althoughtheprinciplesarethesame.)
Analmost50%reductioninpublickeysizecanberealizedwithoutchanginganyfundamentalsbydroppingtheYcoordinate.This
ispossiblebecauseonlytwopointsalongthecurveshareanyparticularXcoordinate,sothe32byteYcoordinatecanbereplaced
withasinglebitindicatingwhetherthepointisonwhatappearsintheillustrationasthetopsideorthebottomside.
NodataislostbycreatingthesecompressedpublickeysonlyasmallamountofCPUisnecessarytoreconstructtheY
coordinateandaccesstheuncompressedpublickey.Bothuncompressedandcompressedpublickeysaredescribedinofficial
secp256k1documentationandsupportedbydefaultinthewidelyusedOpenSSLlibrary.
Becausetheyreeasytouse,andbecausetheyreducealmostbyhalftheblockchainspaceusedtostorepublickeysforevery
spentoutput,compressedpublickeysarethedefaultinBitcoinCoreandaretherecommendeddefaultforallBitcoinsoftware.
However,BitcoinCorepriorto0.6useduncompressedkeys.Thiscreatesafewcomplications,asthehashedformofan
uncompressedkeyisdifferentthanthehashedformofacompressedkey,sothesamekeyworkswithtwodifferentP2PKH
addresses.Thisalsomeansthatthekeymustbesubmittedinthecorrectformatinthesignaturescriptsoitmatchesthehashin
thepreviousoutputspubkeyscript.
Forthisreason,BitcoinCoreusesseveraldifferentidentifierbytestohelpprogramsidentifyhowkeysshouldbeused:
Privatekeysmeanttobeusedwithcompressedpublickeyshave0x01appendedtothembeforebeingBase58encoded.(See
theprivatekeyencodingsectionabove.)
Uncompressedpublickeysstartwith0x04compressedpublickeysbeginwith0x03or0x02dependingonwhethertheyre
greaterorlessthanthemidpointofthecurve.Theseprefixbytesareallusedinofficialsecp256k1documentation.

HierarchicalDeterministicKeyCreation

Thehierarchicaldeterministickeycreationandtransferprotocol(HDprotocol)greatlysimplifieswalletbackups,eliminatestheneed
forrepeatedcommunicationbetweenmultipleprogramsusingthesamewallet,permitscreationofchildaccountswhichcan
operateindependently,giveseachparentaccounttheabilitytomonitororcontrolitschildrenevenifthechildaccountis
compromised,anddivideseachaccountintofullaccessandrestrictedaccesspartssountrustedusersorprogramscanbe
allowedtoreceiveormonitorpaymentswithoutbeingabletospendthem.
TheHDprotocoltakesadvantageoftheECDSApublickeycreationfunction, point(),whichtakesalargeinteger(theprivate
key)andturnsitintoagraphpoint(thepublickey):
point(private_key) == public_key

Becauseoftheway point()functions,itspossibletocreateachildpublickeybycombininganexisting(parent)publickeywith
anotherpublickeycreatedfromanyinteger(i)value.Thischildpublickeyisthesamepublickeywhichwouldbecreatedbythe
point()functionifyouaddedtheivaluetotheoriginal(parent)privatekeyandthenfoundtheremainderofthatsumdividedbya
https://bitcoin.org/en/developer-guide

26/55

16/05/2015

Developer Guide - Bitcoin

globalconstantusedbyallBitcoinsoftware(G):
point( (parent_private_key + i) % G ) == parent_public_key + point(i)

Thismeansthattwoormoreindependentprogramswhichagreeonasequenceofintegerscancreateaseriesofuniquechildkey
pairsfromasingleparentkeypairwithoutanyfurthercommunication.Moreover,theprogramwhichdistributesnewpublickeysfor
receivingpaymentcandosowithoutanyaccesstotheprivatekeys,allowingthepublickeydistributionprogramtorunona
possiblyinsecureplatformsuchasapublicwebserver.
Childpublickeyscanalsocreatetheirownchildpublickeys(grandchildpublickeys)byrepeatingthechildkeyderivation
operations:
point( (child_private_key + i) % G ) == child_public_key + point(i)

Whethercreatingchildpublickeysorfurtherdescendedpublickeys,apredictablesequenceofintegervalueswouldbenobetter
thanusingasinglepublickeyforalltransactions,asanyonewhoknewonechildpublickeycouldfindalloftheotherchildpublic
keyscreatedfromthesameparentpublickey.Instead,arandomseedcanbeusedtodeterministicallygeneratethesequenceof
integervaluessothattherelationshipbetweenthechildpublickeysisinvisibletoanyonewithoutthatseed.
TheHDprotocolusesasinglerootseedtocreateahierarchyofchild,grandchild,andotherdescendedkeyswithunlinkable
deterministicallygeneratedintegervalues.Eachchildkeyalsogetsadeterministicallygeneratedseedfromitsparent,calleda
chaincode,sothecompromisingofonechaincodedoesntnecessarycompromisetheintegersequenceforthewholehierarchy,
allowingthemasterchaincodetocontinuebeingusefulevenif,forexample,awebbasedpublickeydistributionprogramgets
hacked.

Parent Private Key

Mathematical
Relationship

Parent Chain Code

Parent Public Key

Child Private Key

One-Way Hash

Child Chain Code

Derived
Mathematical
Relationship

Child Public Key

Index Number
Normal Hierarchical Deterministic (HD) Key Derivation (BIP32)

Asillustratedabove,HDkeyderivationtakesfourinputs:
Theparentprivatekeyandparentpublickeyareregularuncompressed256bitECDSAkeys.
Theparentchaincodeis256bitsofseeminglyrandomdata.
Theindexnumberisa32bitintegerspecifiedbytheprogram.
Inthenormalformshownintheaboveillustration,theparentchaincode,theparentpublickey,andtheindexnumberarefedintoa
onewaycryptographichash(HMACSHA512)toproduce512bitsofdeterministicallygeneratedbutseeminglyrandomdata.The
seeminglyrandom256bitsontherighthandsideofthehashoutputareusedasanewchildchaincode.Theseeminglyrandom
256bitsonthelefthandsideofthehashoutputareusedastheintegervaluetobecombinedwitheithertheparentprivatekeyor
parentpublickeyto,respectively,createeitherachildprivatekeyorchildpublickey:
point( (parent_private_key + lefthand_hash_output) % G ) == child_public_key
point(child_private_key) == parent_public_key + point(lefthand_hash_output)

Specifyingdifferentindexnumberswillcreatedifferentunlinkablechildkeysfromthesameparentkeys.Repeatingtheprocedure
https://bitcoin.org/en/developer-guide

27/55

16/05/2015

Developer Guide - Bitcoin

forthechildkeysusingthechildchaincodewillcreateunlinkablegrandchildkeys.
Becausecreatingchildkeysrequiresbothakeyandachaincode,thekeyandchaincodetogetherarecalledtheextendedkey.
Anextendedprivatekeyanditscorrespondingextendedpublickeyhavethesamechaincode.The(toplevelparent)master
privatekeyandmasterchaincodearederivedfromrandomdata,asillustratedbelow.

128, 256,
Or 512 Bits
Of Entropy
(The Seed)

512-Bit
One-Way
Hash

256 Bits

Master
Private Key

Master
Public Key

256 Bits
Master
Chain Code

Master
Extended
Public Key
Master
Extended
Private Key

Creation Of The Master Keys

Arootseediscreatedfromeither128bits,256bits,or512bitsofrandomdata.Thisrootseedofaslittleas128bitsisthetheonly
datatheuserneedstobackupinordertoderiveeverykeycreatedbyaparticularwalletprogramusingparticularsettings.
Warning:Asofthiswriting,HDwalletprogramsarenotexpectedtobefullycompatible,sousersmustonlyusethesameHD
walletprogramwiththesameHDrelatedsettingsforaparticularrootseed.
Therootseedishashedtocreate512bitsofseeminglyrandomdata,fromwhichthemasterprivatekeyandmasterchaincode
arecreated(together,themasterextendedprivatekey).Themasterpublickeyisderivedfromthemasterprivatekeyusing
point(),which,togetherwiththemasterchaincode,isthemasterextendedpublickey.Themasterextendedkeysare

functionallyequivalenttootherextendedkeysitisonlytheirlocationatthetopofthehierarchywhichmakesthemspecial.

HardenedKeys

Hardenedextendedkeysfixapotentialproblemwithnormalextendedkeys.Ifanattackergetsanormalparentchaincodeand
parentpublickey,hecanbruteforceallchaincodesderivingfromit.Iftheattackeralsoobtainsachild,grandchild,orfurther
descendedprivatekey,hecanusethechaincodetogeneratealloftheextendedprivatekeysdescendingfromthatprivatekey,as
showninthegrandchildandgreatgrandchildgenerationsoftheillustrationbelow.
Parent

Private

Chain

Parent Key
Derivation
Normal Child
Key Derivation

Public

Child

Grandchild

GreatGrandchild

Private

Private

Private

Chain

Chain

Chain

Public

Public

Public

Cross-Generational Key Compromise

Perhapsworse,theattackercanreversethenormalchildprivatekeyderivationformulaandsubtractaparentchaincodefroma
childprivatekeytorecovertheparentprivatekey,asshowninthechildandparentgenerationsoftheillustrationabove.This
meansanattackerwhoacquiresanextendedpublickeyandanyprivatekeydescendedfromitcanrecoverthatpublickeys
privatekeyandallkeysdescendedfromit.
Forthisreason,thechaincodepartofanextendedpublickeyshouldbebettersecuredthanstandardpublickeysandusers
shouldbeadvisedagainstexportingevennonextendedprivatekeystopossiblyuntrustworthyenvironments.
https://bitcoin.org/en/developer-guide

28/55

16/05/2015

Developer Guide - Bitcoin

Thiscanbefixed,withsometradeoffs,byreplacingthethenormalkeyderivationformulawithahardenedkeyderivationformula.
Thenormalkeyderivationformula,describedinthesectionabove,combinestogethertheindexnumber,theparentchaincode,
andtheparentpublickeytocreatethechildchaincodeandtheintegervaluewhichiscombinedwiththeparentprivatekeyto
createthechildprivatekey.

Parent Private Key

Parent Chain Code

Child Private Key

One-Way
Hash

Child Chain Code

Parent Public Key

Index <0x80000000

Parent Private Key

Parent Chain Code

Child Private Key

One-Way
Hash

Child Chain Code

Index 0x80000000
Normal (Top) And Hardened (Bottom) Child Private Key Derivation

Thehardenedformula,illustratedabove,combinestogethertheindexnumber,theparentchaincode,andtheparentprivatekeyto
createthedatausedtogeneratethechildchaincodeandchildprivatekey.Thisformulamakesitimpossibletocreatechildpublic
keyswithoutknowingtheparentprivatekey.Inotherwords,parentextendedpublickeyscantcreatehardenedchildpublickeys.
Becauseofthat,ahardenedextendedprivatekeyismuchlessusefulthananormalextendedprivatekeyhowever,hardened
extendedprivatekeyscreateafirewallthroughwhichmultilevelkeyderivationcompromisescannothappen.Becausehardened
childextendedpublickeyscannotgenerategrandchildchaincodesontheirown,thecompromiseofaparentextendedpublickey
cannotbecombinedwiththecompromiseofagrandchildprivatekeytocreategreatgrandchildextendedprivatekeys.
TheHDprotocolusesdifferentindexnumberstoindicatewhetheranormalorhardenedkeyshouldbegenerated.Indexnumbers
from0x00to0x7fffffff(0to2311)willgenerateanormalkeyindexnumbersfrom0x80000000to0xffffffffwillgenerateahardened
key.Tomakedescriptionseasy,manydevelopersusetheprimesymboltoindicatehardenedkeys,sothefirstnormalkey(0x00)is
0andthefirsthardenedkey(0x80000000)is0.
(BitcoindeveloperstypicallyusetheASCIIapostropheratherthantheunicodeprimesymbol,aconventionwewillhenceforth
follow.)
ThiscompactdescriptionisfurthercombinedwithslashesprefixedbymorMtoindicatehierarchyandkeytype,withmbeinga
privatekeyandMbeingapublickey.Forexample,m/0/0/122referstothe123rdhardenedprivatechild(byindexnumber)ofthe
firstnormalchild(byindex)ofthefirsthardenedchild(byindex)ofthemasterprivatekey.Thefollowinghierarchyillustratesprime
notationandhardenedkeyfirewalls.

https://bitcoin.org/en/developer-guide

29/55

16/05/2015

Developer Guide - Bitcoin

Normal

Normal
m/0'/0

M/0'/0

Hardened
m/0'

Hardened
m/0'/1'

Normal extended
public keys
can derive child
public keys
Only derivation from
extended private keys
is possible for
hardened keys

m/0'/0/0

M/0'/0/0

Normal
m/0'/1'/0

M/0'
M/0'/1'

M/0'/1'/0

Hierarchical Deterministic Key Derivation

WalletsfollowingtheBIP32HDprotocolonlycreatehardenedchildrenofthemasterprivatekey(m)topreventacompromised
childkeyfromcompromisingthemasterkey.Astherearenonormalchildrenforthemasterkeys,themasterpublickeyisnotused
inHDwallets.Allotherkeyscanhavenormalchildren,sothecorrespondingextendedpublickeysmaybeusedinstead.
TheHDprotocolalsodescribesaserializationformatforextendedpublickeysandextendedprivatekeys.Fordetails,pleasesee
thewalletsectioninthedeveloperreferenceorBIP32forthefullHDprotocolspecification.

StoringRootSeeds

RootseedsintheHDprotocolare128,256,or512bitsofrandomdatawhichmustbebackedupprecisely.Tomakeitmore
convenienttousenondigitalbackupmethods,suchasmemorizationorhandcopying,BIP39definesamethodforcreatinga512
bitrootseedfromapseudosentence(mnemonic)ofcommonnaturallanguagewordswhichwasitselfcreatedfrom128to256bits
ofentropyandoptionallyprotectedbyapassword.
Thenumberofwordsgeneratedcorrelatestotheamountofentropyused:
EntropyBits

Words

128

12

160

15

192

18

224

21

256

24

Thepassphrasecanbeofanylength.Itissimplyappendedtothemnemonicpseudosentence,andthenboththemnemonicand
passwordarehashed2,048timesusingHMACSHA512,resultinginaseeminglyrandom512bitseed.Becauseanyinputtothe
hashfunctioncreatesaseeminglyrandom512bitseed,thereisnofundamentalwaytoprovetheuserenteredthecorrect
password,possiblyallowingtheusertoprotectaseedevenwhenunderduress.
Forimplementationdetails,pleaseseeBIP39.
https://bitcoin.org/en/developer-guide

30/55

16/05/2015

Developer Guide - Bitcoin

LooseKeyWallets

LooseKeywallets,alsocalledJustaBunchOfKeys(JBOK),areadeprecatedformofwalletthatoriginatedfromtheBitcoin
Coreclientwallet.TheBitcoinCoreclientwalletwouldcreate100privatekey/publickeypairsautomaticallyviaaPseudoRandom
NumberGenerator(PRNG)forlateruse.
Theseunusedprivatekeysarestoredinavirtualkeypool,withnewkeysbeinggeneratedwheneverapreviouslygeneratedkey
wasused,ensuringthepoolmaintained100unusedkeys.(Ifthewalletisencrypted,newkeysareonlygeneratedwhilethewallet
isunlocked.)
Thiscreatedconsiderabledifficultyinbackinguponeskeys,consideringbackupshavetoberunmanuallytosavethenewly
generatedprivatekeys.Ifanewkeypairsetisgenerated,used,andthenlostpriortoabackup,thestoredsatoshisarelikelylost
forever.Manyolderstylemobilewalletsfollowedasimilarformat,butonlygeneratedanewprivatekeyuponuserdemand.
Thiswallettypeisbeingactivelyphasedoutanddiscouragedfrombeingusedduetothebackuphassle.

Payment Processing
Paymentprocessingencompassesthestepsspendersandreceiversperformtomakeandacceptpaymentsinexchangefor
productsorservices.Thebasicstepshavenotchangedsincethedawnofcommerce,butthetechnologyhas.Thissectionwill
explainhowreceiversandspenderscan,respectively,requestandmakepaymentsusingBitcoinandhowtheycandealwith
complicationssuchasrefundsandrecurrentrebilling.
Bitcoinpaymentprocessingisbeingactivelydevelopedatthemoment,soeachsubsectionbelowattemptstodescribewhats
widelydeployednow,whatsnew,andwhatmightbecomingbeforetheendof2014.
New
Order

Price
Order
In
BTC

Request
Payment

Verify
Payment
& Fulfill
Order

Issue
Refund
(Sometimes)

Disburse
Income
(Optional)

Rebill
Recurring
(Optional)

Payment Processing With Bitcoin (From A Receiver's Perspective)

ThefigureaboveillustratespaymentprocessingusingBitcoinfromareceiversperspective,startingwithaneworder.The
followingsubsectionswilleachaddressthethreecommonstepsandthethreeoccasionaloroptionalsteps.
ItisworthmentioningthateachofthesestepscanbeoutsourcedbyusingthirdpartyAPIsandservices.

PricingOrders
Becauseofexchangeratevariabilitybetweensatoshisandnationalcurrencies(fiat),manyBitcoinordersarepricedinfiatbutpaid
insatoshis,necessitatingapriceconversion.
ExchangeratedataiswidelyavailablethroughHTTPbasedAPIsprovidedbycurrencyexchanges.Severalorganizationsalso
aggregatedatafrommultipleexchangestocreateindexprices,whicharealsoavailableusingHTTPbasedAPIs.
Anyapplicationswhichautomaticallycalculateordertotalsusingexchangeratedatamusttakestepstoensurethepricequoted
reflectsthecurrentgeneralmarketvalueofsatoshis,ortheapplicationscouldaccepttoofewsatoshisfortheproductorservice
beingsold.Alternatively,theycouldaskfortoomanysatoshis,drivingawaypotentialspenders.
Tominimizeproblems,yourapplicationsmaywanttocollectdatafromatleasttwoseparatesourcesandcomparethemtosee
https://bitcoin.org/en/developer-guide

31/55

16/05/2015

Developer Guide - Bitcoin

howmuchtheydiffer.Ifthedifferenceissubstantial,yourapplicationscanenterasafemodeuntilahumanisabletoevaluatethe
situation.
Youmayalsowanttoprogramyourapplicationstoenterasafemodeifexchangeratesarerapidlyincreasingordecreasing,
indicatingapossibleproblemintheBitcoinmarketwhichcouldmakeitdifficulttospendanysatoshisreceivedtoday.
ExchangerateslieoutsidethecontrolofBitcoinandrelatedtechnologies,sotherearenoneworplannedtechnologieswhichwill
makeitsignificantlyeasierforyourprogramtocorrectlyconvertordertotalsfromfiatintosatoshis.
Becausetheexchangeratefluctuatesovertime,ordertotalspeggedtofiatmustexpiretopreventspendersfromdelayingpayment
inthehopethatsatoshiswilldropinprice.Mostwidelyusedpaymentprocessingsystemscurrentlyexpiretheirinvoicesafter10to
20minutes.
Shorterexpirationperiodsincreasethechancetheinvoicewillexpirebeforepaymentisreceived,possiblynecessitatingmanual
interventiontorequestanadditionalpaymentortoissuearefund.Longerexpirationperiodsincreasethechancethattheexchange
ratewillfluctuateasignificantamountbeforepaymentisreceived.

RequestingPayments
Beforerequestingpayment,yourapplicationmustcreateaBitcoinaddress,oracquireanaddressfromanotherprogramsuchas
BitcoinCore.BitcoinaddressesaredescribedindetailintheTransactionssection.Alsodescribedinthatsectionaretwoimportant
reasonstoavoidusinganaddressmorethanoncebutathirdreasonappliesespeciallytopaymentrequests:
Usingaseparateaddressforeachincomingpaymentmakesittrivialtodeterminewhichcustomershavepaidtheirpayment
requests.Yourapplicationsneedonlytracktheassociationbetweenaparticularpaymentrequestandtheaddressusedinit,and
thenscantheblockchainfortransactionsmatchingthataddress.
Thenextsubsectionswilldescribeindetailthefollowingfourcompatiblewaystogivethespendertheaddressandamounttobe
paid.Forincreasedconvenienceandcompatibility,providingalloftheseoptionsinyourpaymentrequestsisrecommended.
1. Allwalletsoftwareletsitsuserspasteinormanuallyenteranaddressandamountintoapaymentscreen.Thisis,ofcourse,
inconvenientbutitmakesaneffectivefallbackoption.
2. Almostalldesktopwalletscanassociatewith bitcoin:URIs,sospenderscanclickalinktoprefillthepaymentscreen.This
alsoworkswithmanymobilewallets,butitgenerallydoesnotworkwithwebbasedwalletsunlessthespenderinstallsa
browserextensionormanuallyconfiguresaURIhandler.
3. Mostmobilewalletssupportscanning bitcoin:URIsencodedinaQRcode,andalmostallwalletscandisplaythemfor
acceptingpayment.Whilealsohandyforonlineorders,QRCodesareespeciallyusefulforinpersonpurchases.
4. Recentwalletupdatesaddsupportforthenewpaymentprotocolprovidingincreasedsecurity,authenticationofareceivers
identityusingX.509certificates,andotherimportantfeaturessuchasrefunds.
Warning:Specialcaremustbetakentoavoidthetheftofincomingpayments.Inparticular,privatekeysshouldnotbestored
onwebservers,andpaymentrequestsshouldbesentoverHTTPSorothersecuremethodstopreventmaninthemiddleattacks
fromreplacingyourBitcoinaddresswiththeattackersaddress.

PlainText

Tospecifyanamountdirectlyforcopyingandpasting,youmustprovidetheaddress,theamount,andthedenomination.An
expirationtimefortheoffermayalsobespecified.Forexample:
(Note:allexamplesinthissectionusetestnetaddresses.)
https://bitcoin.org/en/developer-guide

32/55

16/05/2015

Developer Guide - Bitcoin

Pay: mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN
Amount: 100 BTC
You must pay by: 2014-04-01 at 23:00 UTC

Indicatingthedenominationiscritical.Asofthiswriting,popularBitcoinwalletsoftwaredefaultstodenominatingamountsineither
bitcoins(BTC),millibitcoins(mBTC)ormicrobitcoins(uBTC,bits).Choosingbetweeneachunitiswidelysupported,butother
softwarealsoletsitsusersselectdenominationamountsfromsomeorallofthefollowingoptions:
Bitcoins

Unit(Abbreviation)

1.0

bitcoin(BTC)

0.01

bitcent(cBTC)

0.001

millibitcoin(mBTC)

0.000001

microbitcoin(uBTC,bits)

0.00000001

satoshi

bitcoin:URI

The bitcoin:URIschemedefinedinBIP21eliminatesdenominationconfusionandsavesthespenderfromcopyingandpasting
twoseparatevalues.Italsoletsthepaymentrequestprovidesomeadditionalinformationtothespender.Anexample:
bitcoin:mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN?amount=100

Onlytheaddressisrequired,andifitistheonlythingspecified,walletswillprefillapaymentrequestwithitandletthespender
enteranamount.Theamountspecifiedisalwaysindecimalbitcoins(BTC).
Twootherparametersarewidelysupported.The labelparameterisgenerallyusedtoprovidewalletsoftwarewiththerecipients
name.The messageparameterisgenerallyusedtodescribethepaymentrequesttothespender.Boththelabelandthemessage
arecommonlystoredbythespenderswalletsoftwarebuttheyareneveraddedtotheactualtransaction,sootherBitcoinusers
cannotseethem.BoththelabelandthemessagemustbeURIencoded.
Allfourparametersusedtogether,withappropriateURIencoding,canbeseeninthelinewrappedexamplebelow.
bitcoin:mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN\
?amount=0.10\
&label=Example+Merchant\
&message=Order+of+flowers+%26+chocolates

TheURIschemecanbeextended,aswillbeseeninthepaymentprotocolsectionbelow,withbothnewoptionalandrequired
parameters.Asofthiswriting,theonlywidelyusedparameterbesidesthefourdescribedaboveisthepaymentprotocols r
parameter.
ProgramsacceptingURIsinanyformmustasktheuserforpermissionbeforepayingunlesstheuserhasexplicitlydisabled
prompting(asmightbethecaseformicropayments).

https://bitcoin.org/en/developer-guide

33/55

16/05/2015

Developer Guide - Bitcoin

QRCodes

QRcodesareapopularwaytoexchange bitcoin:URIsinperson,inimages,orinvideos.MostmobileBitcoinwalletapps,and
somedesktopwallets,supportscanningQRcodestoprefilltheirpaymentscreens.
Thefigurebelowshowsthesame bitcoin:URIcodeencodedasfourdifferentBitcoinQRcodesatfourdifferenterrorcorrection
levels.TheQRcodecanincludethe labeland messageparametersandanyotheroptionalparametersbuttheywereomitted
heretokeeptheQRcodesmallandeasytoscanwithunsteadyorlowresolutionmobilecameras.

Low

Medium

Quartile

High

bitcoin:mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN?amount=.1

TheerrorcorrectioniscombinedwithachecksumtoensuretheBitcoinQRcodecannotbesuccessfullydecodedwithdatamissing
oraccidentallyaltered,soyourapplicationsshouldchoosetheappropriateleveloferrorcorrectionbasedonthespaceyouhave
availabletodisplaythecode.Lowleveldamagecorrectionworkswellwhenspaceislimited,andquartileleveldamagecorrection
helpsensurefastscanningwhendisplayedonhighresolutionscreens.

PaymentProtocol

BitcoinCore0.9supportsthenewpaymentprotocol.Thepaymentprotocoladdsmanyimportantfeaturestopaymentrequests:
SupportsX.509certificatesandSSLencryptiontoverifyreceiversidentityandhelppreventmaninthemiddleattacks.
Providesmoredetailabouttherequestedpaymenttospenders.
Allowsspenderstosubmittransactionsdirectlytoreceiverswithoutgoingthroughthepeertopeernetwork.Thiscanspeedup
paymentprocessingandworkwithplannedfeaturessuchaschildpaysforparenttransactionfeesandofflineNFCorBluetooth
basedpayments.
Insteadofbeingaskedtopayameaninglessaddress,suchasmjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN,spendersareasked
topaytheCommonName(CN)descriptionfromthereceiversX.509certificate,suchaswww.bitcoin.org.
Torequestpaymentusingthepaymentprotocol,youuseanextended(butbackwardscompatible) bitcoin:URI.Forexample:
bitcoin:mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN\
?amount=0.10\
&label=Example+Merchant\
&message=Order+of+flowers+%26+chocolates\
&r=https://example.com/pay/mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN

Noneoftheparametersprovidedabove,except r,arerequiredforthepaymentprotocolbutyourapplicationsmayincludethem
forbackwardscompatibilitywithwalletprogramswhichdontyethandlethepaymentprotocol.
The rparametertellspaymentprotocolawarewalletprogramstoignoretheotherparametersandfetchaPaymentRequestfrom
theURLprovided.Thebrowser,QRcodereader,orotherprogramprocessingtheURIopensthespendersBitcoinwalletprogram
ontheURI.

https://bitcoin.org/en/developer-guide

34/55

16/05/2015

Developer Guide - Bitcoin

Pay Now
Link/QR Code

Receiver
Payment
Request

bitcoin:
?r=http://example.com/pay/123

Spender

I clicked a
bitcoin: URI

Spender's
Wallet

Send the
invoice from
[...]/pay/123
Here's the invoice

Pay 10 mBTC
To example.com
(VERIFIED)
Exp. In 10 Min.
Memo: [...]

Do you agree to
the invoice terms?
Yes.
Pay the invoice

Payment accepted;
you can go do
something else

Payment
TX1
[TX...]
Memo
Refund
address(es)

TX(es) attached
with refund
addresses and
a memo
PaymentACK
Thanks!
payment accepted
for processing

Payment
Details
Outputs
Exp. Time
Memo
Pay URL
Ref #

X.509 Sig

TX1
[TX...]
Memo

The Bitcoin Payment Protocol As Described In BIP70

ThePaymentProtocolisdescribedindepthinBIP70,BIP71,andBIP72.AnexampleCGIprogramanddescriptionofallthe
parameterswhichcanbeusedinthePaymentProtocolisprovidedintheDeveloperExamplesPaymentProtocolsubsection.In
thissubsection,wewillbrieflydescribeinstoryformathowthePaymentProtocolistypicallyused.
Charlie,theclient,isshoppingonawebsiterunbyBob,thebusinessman.Charlieaddsafewitemstohisshoppingcartandclicks
theCheckoutWithBitcoinbutton.
Bobsserverautomaticallyaddsthefollowinginformationtoitsinvoicedatabase:
ThedetailsofCharliesorder,includingitemsorderedandshippingaddress.
Anordertotalinsatoshis,perhapscreatedbyconvertingpricesinfiattopricesinsatoshis.
Anexpirationtimewhenthattotalwillnolongerbeacceptable.
ApubkeyscripttowhichCharlieshouldsendpayment.TypicallythiswillbeaP2PKHorP2SHpubkeyscriptcontaininga
unique(neverbeforeused)secp256k1publickey.
Afteraddingallthatinformationtothedatabase,Bobsserverdisplaysa bitcoin:URIforCharlietoclicktopay.
Charlieclicksonthe bitcoin:URIinhisbrowser.HisbrowsersURIhandlersendstheURItohiswalletprogram.Thewalletis
awareofthePaymentProtocol,soitparsesthe rparameterandsendsanHTTPGETtothatURLlookingforaPaymentRequest
message.
ThePaymentRequestmessagereturnedmayincludeprivateinformation,suchasCharliesmailingaddress,butthewalletmustbe
abletoaccessitwithoutusingpriorauthentication,suchasHTTPcookies,soapubliclyaccessibleHTTPSURLwithaguess
resistantpartistypicallyused.Theuniquepublickeycreatedforthepaymentrequestcanbeusedtocreateauniqueidentifier.
Thisiswhy,intheexampleURIabove,thePaymentRequestURLcontainstheP2PKHaddress:
https://example.com/pay/mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN

AfterreceivingtheHTTPGETtotheURLabove,thePaymentRequestgeneratingCGIprogramonBobswebservertakesthe
uniqueidentifierfromtheURLandlooksupthecorrespondingdetailsinthedatabase.ItthencreatesaPaymentDetailsmessage
withthefollowinginformation:
https://bitcoin.org/en/developer-guide

35/55

16/05/2015

Developer Guide - Bitcoin

Theamountoftheorderinsatoshisandthepubkeyscripttobepaid.
Amemocontainingthelistofitemsordered,soCharlieknowswhathespayingfor.ItmayalsoincludeCharliesmailingaddress
sohecandoublecheckit.
ThetimethePaymentDetailsmessagewascreatedplusthetimeitexpires.
AURLtowhichCharlieswalletshouldsenditscompletedtransaction.
ThatPaymentDetailsmessageisputinsideaPaymentRequestmessage.ThepaymentrequestletsBobsserversigntheentire
RequestwiththeserversX.509SSLcertificate.(ThePaymentProtocolhasbeendesignedtoallowothersigningmethodsinthe
future.)BobsserversendsthepaymentrequesttoCharlieswalletinthereplytotheHTTPGET.

CharlieswalletreceivesthePaymentRequestmessage,checksitssignature,andthendisplaysthedetailsfromthe
PaymentDetailsmessagetoCharlie.Charlieagreestopay,sothewalletconstructsapaymenttothepubkeyscriptBobsserver
provided.UnlikeatraditionalBitcoinpayment,Charlieswalletdoesntnecessarilyautomaticallybroadcastthispaymenttothe
network.Instead,thewalletconstructsaPaymentmessageandsendsittotheURLprovidedinthePaymentDetailsmessageas
anHTTPPOST.Amongotherthings,thePaymentmessagecontains:
ThesignedtransactioninwhichCharliepaysBob.
AnoptionalmemoCharliecansendtoBob.(TheresnoguaranteethatBobwillreadit.)
Arefundaddress(pubkeyscript)whichBobcanpayifheneedstoreturnsomeorallofCharliessatoshis.
BobsserverreceivesthePaymentmessage,verifiesthetransactionpaystherequestedamounttotheaddressprovided,andthen
broadcaststhetransactiontothenetwork.ItalsorepliestotheHTTPPOSTedPaymentmessagewithaPaymentACKmessage,
whichincludesanoptionalmemofromBobsserverthankingCharlieforhispatronageandprovidingotherinformationaboutthe
order,suchastheexpectedarrivaldate.
CharlieswalletseesthePaymentACKandtellsCharliethatthepaymenthasbeensent.ThePaymentACKdoesntmeanthatBob
hasverifiedCharliespaymentseetheVerifyingPaymentsubsectionbelowbutitdoesmeanthatCharliecangodosomething
elsewhilethetransactiongetsconfirmed.AfterBobsserververifiesfromtheblockchainthatCharliestransactionhasbeen
suitablyconfirmed,itauthorizesshippingCharliesorder.
Inthecaseofadispute,Charliecangenerateacryptographicallyprovenreceiptoutofthevarioussignedorotherwiseproven
https://bitcoin.org/en/developer-guide

36/55

16/05/2015

Developer Guide - Bitcoin

information.
ThePaymentDetailsmessagesignedbyBobswebserverprovesCharliereceivedaninvoicetopayaspecifiedpubkeyscriptfor
aspecifiednumberofsatoshisforgoodsspecifiedinthememofield.
TheBitcoinblockchaincanprovethatthepubkeyscriptspecifiedbyBobwaspaidthespecifiednumberofsatoshis.
Ifarefundneedstobeissued,BobsservercansafelypaytherefundtopubkeyscriptprovidedbyCharlie.(Note:aproposalhas
beendiscussedtogiverefundtoaddressesanimplicitexpirationdatesousersandsoftwaredontneedtoworryaboutpayments
beingsenttoaddresseswhicharenolongermonitored.)SeetheRefundssectionbelowformoredetails.

VerifyingPayment
AsexplainedintheTransactionsandBlockChainsections,broadcastingatransactiontothenetworkdoesntensurethatthe
receivergetspaid.Amaliciousspendercancreateonetransactionthatpaysthereceiverandasecondonethatpaysthesame
inputbacktohimself.Onlyoneofthesetransactionswillbeaddedtotheblockchain,andnobodycansayforsurewhichoneitwill
be.
Twoormoretransactionsspendingthesameinputarecommonlyreferredtoasadoublespend.
Oncethetransactionisincludedinablock,doublespendsareimpossiblewithoutmodifyingblockchainhistorytoreplacethe
transaction,whichisquitedifficult.Usingthissystem,theBitcoinprotocolcangiveeachofyourtransactionsanupdating
confidencescorebasedonthenumberofblockswhichwouldneedtobemodifiedtoreplaceatransaction.Foreachblock,the
transactiongainsoneconfirmation.Sincemodifyingblocksisquitedifficult,higherconfirmationscoresindicategreaterprotection.
0confirmations:Thetransactionhasbeenbroadcastbutisstillnotincludedinanyblock.Zeroconfirmationtransactions
(unconfirmedtransactions)shouldgenerallynotbetrustedwithoutriskanalysis.Althoughminersusuallyconfirmthefirst
transactiontheyreceive,fraudstersmaybeabletomanipulatethenetworkintoincludingtheirversionofatransaction.
1confirmation:Thetransactionisincludedinthelatestblockanddoublespendriskdecreasesdramatically.Transactionswhich
paysufficienttransactionfeesneed10minutesonaveragetoreceiveoneconfirmation.However,themostrecentblockgets
replacedfairlyoftenbyaccident,soadoublespendisstillarealpossibility.
2confirmations:Themostrecentblockwaschainedtotheblockwhichincludesthetransaction.AsofMarch2014,twoblock
replacementswereexceedinglyrare,andatwoblockreplacementattackwasimpracticalwithoutexpensiveminingequipment.
6confirmations:Thenetworkhasspentaboutanhourworkingtoprotectthetransactionagainstdoublespendsandthe
transactionisburiedundersixblocks.Evenareasonablyluckyattackerwouldrequirealargepercentageofthetotalnetwork
hashingpowertoreplacesixblocks.Althoughthisnumberissomewhatarbitrary,softwarehandlinghighvaluetransactions,or
otherwiseatriskforfraud,shouldwaitforatleastsixconfirmationsbeforetreatingapaymentasaccepted.
BitcoinCoreprovidesseveralRPCswhichcanprovideyourprogramwiththeconfirmationscorefortransactionsinyourwalletor
arbitrarytransactions.Forexample,the listunspentRPCprovidesanarrayofeverysatoshiyoucanspendalongwithits
confirmationscore.
Althoughconfirmationsprovideexcellentdoublespendprotectionmostofthetime,thereareatleastthreecaseswheredouble
spendriskanalysiscanberequired:
1. Inthecasewhentheprogramoritsusercannotwaitforaconfirmationandwantstoacceptunconfirmedpayments.
2. Inthecasewhentheprogramoritsuserisacceptinghighvaluetransactionsandcannotwaitforatleastsixconfirmationsor
more.
3. InthecaseofanimplementationbugorprolongedattackagainstBitcoinwhichmakesthesystemlessreliablethanexpected.
https://bitcoin.org/en/developer-guide

37/55

16/05/2015

Developer Guide - Bitcoin

AninterestingsourceofdoublespendriskanalysiscanbeacquiredbyconnectingtolargenumbersofBitcoinpeerstotrackhow
transactionsandblocksdifferfromeachother.SomethirdpartyAPIscanprovideyouwiththistypeofservice.
Forexample,unconfirmedtransactionscanbecomparedamongallconnectedpeerstoseeifanyUTXOisusedinmultiple
unconfirmedtransactions,indicatingadoublespendattempt,inwhichcasethepaymentcanberefuseduntilitisconfirmed.
Transactionscanalsoberankedbytheirtransactionfeetoestimatetheamountoftimeuntiltheyreaddedtoablock.
Anotherexamplecouldbetodetectaforkwhenmultiplepeersreportdifferingblockheaderhashesatthesameblockheight.Your
programcangointoasafemodeiftheforkextendsformorethantwoblocks,indicatingapossibleproblemwiththeblockchain.
Formoredetails,seetheDetectingForkssubsection.
Anothergoodsourceofdoublespendprotectioncanbehumanintelligence.Forexample,fraudstersmayactdifferentlyfrom
legitimatecustomers,lettingsavvymerchantsmanuallyflagthemashighrisk.Yourprogramcanprovideasafemodewhichstops
automaticpaymentacceptanceonaglobalorpercustomerbasis.

IssuingRefunds
Occasionallyreceiversusingyourapplicationswillneedtoissuerefunds.Theobviouswaytodothat,whichisveryunsafe,is
simplytoreturnthesatoshistothepubkeyscriptfromwhichtheycame.Forexample:
AlicewantstobuyawidgetfromBob,soBobgivesAliceapriceandBitcoinaddress.
Aliceopensherwalletprogramandsendssomesatoshistothataddress.Herwalletprogramautomaticallychoosestospend
thosesatoshisfromoneofitsunspentoutputs,anoutputcorrespondingtotheBitcoinaddress
mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN.
BobdiscoversAlicepaidtoomanysatoshis.Beinganhonestfellow,BobrefundstheextrasatoshistothemjSkaddress.
Thisseemslikeitshouldwork,butAliceisusingacentralizedmultiuserwebwalletwhichdoesntgiveuniqueaddressestoeach
user,soithasnowaytoknowthatBobsrefundismeantforAlice.Nowtherefundisaunintentionaldonationtothecompany
behindthecentralizedwallet,unlessAliceopensasupportticketandprovesthosesatoshisweremeantforher.
Thisleavesreceiversonlytwocorrectwaystoissuerefunds:
Ifanaddresswascopyandpastedorabasic bitcoin:URIwasused,contactthespenderdirectlyandaskthemtoprovidea
refundaddress.
Ifthepaymentprotocolwasused,sendtherefundtotheoutputlistedinthe refund_tofieldofthePaymentmessage.
AsdiscussedinthePaymentsection, refund_toaddressesmaycomewithimplicitexpirationdates,soyoumayneedtorevertto
contactingthespenderdirectlyiftherefundisbeingissuedalongtimeaftertheoriginalpaymentwasmade.

DisbursingIncome(LimitingForexRisk)
Manyreceiversworrythattheirsatoshiswillbelessvaluableinthefuturethantheyarenow,calledforeignexchange(forex)risk.
Tolimitforexrisk,manyreceiverschoosetodisbursenewlyacquiredpaymentssoonaftertheyrereceived.
Ifyourapplicationprovidesthisbusinesslogic,itwillneedtochoosewhichoutputstospendfirst.Thereareafewdifferent
algorithmswhichcanleadtodifferentresults.
Amergeavoidancealgorithmmakesitharderforoutsiderslookingatblockchaindatatofigureouthowmanysatoshisthe
receiverhasearned,spent,andsaved.

https://bitcoin.org/en/developer-guide

38/55

16/05/2015

Developer Guide - Bitcoin

Alastinfirstout(LIFO)algorithmspendsnewlyacquiredsatoshiswhiletheresstilldoublespendrisk,possiblypushingthatrisk
ontoothers.Thiscanbegoodforthereceiversbalancesheetbutpossiblybadfortheirreputation.
Afirstinfirstout(FIFO)algorithmspendstheoldestsatoshisfirst,whichcanhelpensurethatthereceiverspaymentsalways
confirm,althoughthishasutilityonlyinafewedgecases.

MergeAvoidance

Whenareceiverreceivessatoshisinanoutput,thespendercantrack(inacrudeway)howthereceiverspendsthosesatoshis.
Butthespendercantautomaticallyseeothersatoshispaidtothereceiverbyotherspendersaslongasthereceiverusesunique
addressesforeachtransaction.
However,ifthereceiverspendssatoshisfromtwodifferentspendersinthesametransaction,eachofthosespenderscanseethe
otherspenderspayment.Thisiscalledamerge,andthemoreareceivermergesoutputs,theeasieritisforanoutsidertotrack
howmanysatoshisthereceiverhasearned,spent,andsaved.
Mergeavoidancemeanstryingtoavoidspendingunrelatedoutputsinthesametransaction.Forpersonsandbusinesseswhich
wanttokeeptheirtransactiondatasecretfromotherpeople,itcanbeanimportantstrategy.
Acrudemergeavoidancestrategyistotrytoalwayspaywiththesmallestoutputyouhavewhichislargerthantheamountbeing
requested.Forexample,ifyouhavefouroutputsholding,respectively,100,200,500,and900satoshis,youwouldpayabillfor
300satoshiswiththe500satoshioutput.Thisway,aslongasyouhaveoutputslargerthanyourbills,youavoidmerging.
Moreadvancedmergeavoidancestrategieslargelydependonenhancementstothepaymentprotocolwhichwillallowpayersto
avoidmergingbyintelligentlydistributingtheirpaymentsamongmultipleoutputsprovidedbythereceiver.

LastIn,FirstOut(LIFO)

Outputscanbespentassoonastheyrereceivedevenbeforetheyreconfirmed.Sincerecentoutputsareatthegreatestriskof
beingdoublespent,spendingthembeforeolderoutputsallowsthespendertoholdontoolderconfirmedoutputswhicharemuch
lesslikelytobedoublespent.
TherearetwocloselyrelateddownsidestoLIFO:
Ifyouspendanoutputfromoneunconfirmedtransactioninasecondtransaction,thesecondtransactionbecomesinvalidif
transactionmalleabilitychangesthefirsttransaction.
Ifyouspendanoutputfromoneunconfirmedtransactioninasecondtransactionandthefirsttransactionsoutputissuccessfully
doublespenttoanotheroutput,thesecondtransactionbecomesinvalid.
Ineitheroftheabovecases,thereceiverofthesecondtransactionwillseetheincomingtransactionnotificationdisappearorturn
intoanerrormessage.
BecauseLIFOputstherecipientofsecondarytransactionsinasmuchdoublespendriskastherecipientoftheprimary
transaction,theyrebestusedwhenthesecondaryrecipientdoesntcareabouttherisksuchasanexchangeorotherservice
whichisgoingtowaitforsixconfirmationswhetheryouspendoldoutputsornewoutputs.
LIFOshouldnotbeusedwhentheprimarytransactionrecipientsreputationmightbeatstake,suchaswhenpayingemployees.In
thesecases,itsbettertowaitfortransactionstobefullyverified(seetheVerificationsubsectionabove)beforeusingthemtomake
payments.

FirstIn,FirstOut(FIFO)
https://bitcoin.org/en/developer-guide

39/55

16/05/2015

Developer Guide - Bitcoin

Theoldestoutputsarethemostreliable,asthelongeritsbeensincetheywerereceived,themoreblockswouldneedtobe
modifiedtodoublespendthem.However,afterjustafewblocks,apointofrapidlydiminishingreturnsisreached.Theoriginal
Bitcoinpaperpredictsthechanceofanattackerbeingabletomodifyoldblocks,assumingtheattackerhas30%ofthetotal
networkhashingpower:
Blocks

Chanceofsuccessfulmodification

17.73523%

10

4.16605%

15

1.01008%

20

0.24804%

25

0.06132%

30

0.01522%

35

0.00379%

40

0.00095%

45

0.00024%

50

0.00006%

FIFOdoeshaveasmalladvantagewhenitcomestotransactionfees,asolderoutputsmaybeeligibleforinclusioninthe50,000
bytessetasidefornofeerequiredhighprioritytransactionsbyminersrunningthedefaultBitcoinCorecodebase.However,with
transactionfeesbeingsolow,thisisnotasignificantadvantage.
TheonlypracticaluseofFIFOisbyreceiverswhospendallormostoftheirincomewithinafewblocks,andwhowanttoreduce
thechanceoftheirpaymentsbecomingaccidentallyinvalid.Forexample,areceiverwhoholdseachpaymentforsixconfirmations,
andthenspends100%ofverifiedpaymentstovendorsandasavingsaccountonabihourlyschedule.

RebillingRecurringPayments
AutomatedrecurringpaymentsarenotpossiblewithdecentralizedBitcoinwallets.Evenifawalletsupportedautomaticallysending
nonreversiblepaymentsonaregularschedule,theuserwouldstillneedtostarttheprogramattheappointedtime,orleaveit
runningallthetimeunprotectedbyencryption.
ThismeansautomatedrecurringBitcoinpaymentscanonlybemadefromacentralizedserverwhichhandlessatoshisonbehalfof
itsspenders.Inpractice,receiverswhowanttosetpricesinfiattermsmustalsoletthesamecentralizedserverchoosethe
appropriateexchangerate.
Nonautomatedrebillingcanbemanagedbythesamemechanismusedbeforecreditcardrecurringpaymentsbecamecommon:
contactthespenderandaskthemtopayagainforexample,bysendingthemaPaymentRequest bitcoin:URIinanHTML
email.
Inthefuture,extensionstothepaymentprotocolandnewwalletfeaturesmayallowsomewalletprogramstomanagealistof
recurringtransactions.Thespenderwillstillneedtostarttheprogramonaregularbasisandauthorizepaymentbutitshouldbe
https://bitcoin.org/en/developer-guide

40/55

16/05/2015

Developer Guide - Bitcoin

easierandmoresecureforthespenderthanclickinganemailedinvoice,increasingthechancereceiversgetpaidontime.

Operating Modes
Currentlytherearetwoprimarymethodsofvalidatingtheblockchainasaclient:FullnodesandSPVclients.Othermethods,such
asservertrustingmethods,arenotdiscussedastheyarenotrecommended.

FullNode
ThefirstandmostsecuremodelistheonefollowedbyBitcoinCore,alsoknownasathickorfullchainclient.Thissecurity
modelassuresthevalidityoftheblockchainbydownloadingandvalidatingblocksfromthegenesisblockallthewaytothemost
recentlydiscoveredblock.Thisisknownasusingtheheightofaparticularblocktoverifytheclientsviewofthenetwork.
Foraclienttobefooled,anadversarywouldneedtogiveacompletealternativeblockchainhistorythatisofgreaterdifficultythan
thecurrenttruechain,whichisimpossibleduetothefactthatthelongestchainisbydefinitionthetruechain.Afterthesuggested
sixconfirmations,theabilitytofooltheclientbecomeintractable,asonlyasinglehonestnetworknodeisneededtohavethe
completestateoftheblockchain.

Block Height

Block Depth

Block 102

Depth 1

Block 101

Depth 2

Block 100

Depth 3

Block 1

Depth 100

Block 0

Depth 101

Block Height Compared

To Block Depth

SimplifiedPaymentVerification(SPV)
AnalternativeapproachdetailedintheoriginalBitcoinpaperisaclientthatonlydownloadstheheadersofblocksduringtheinitial
syncingprocessandthenrequeststransactionsfromfullnodesasneeded.Thisscaleslinearlywiththeheightoftheblockchainat
https://bitcoin.org/en/developer-guide

41/55

16/05/2015

Developer Guide - Bitcoin

only80bytesperblockheader,orupto4.2MBperyear,regardlessoftotalblocksize.
Asdescribedinthewhitepaper,themerklerootintheblockheaderalongwithamerklebranchcanprovetotheSPVclientthatthe
transactioninquestionisembeddedinablockintheblockchain.Thisdoesnotguaranteevalidityofthetransactionsthatare
embedded.Insteaditdemonstratestheamountofworkrequiredtoperformadoublespendattack.
Theblocksdepthintheblockchaincorrespondstothecumulativedifficultythathasbeenperformedtobuildontopofthat
particularblock.TheSPVclientknowsthemerklerootandassociatedtransactioninformation,andrequeststherespectivemerkle
branchfromafullnode.Oncethemerklebranchhasbeenretrieved,provingtheexistenceofthetransactionintheblock,theSPV
clientcanthenlooktoblockdepthasaproxyfortransactionvalidityandsecurity.Thecostofanattackonauserbyamalicious
nodewhoinsertsaninvalidtransactiongrowswiththecumulativedifficultybuiltontopofthatblock,sincethemaliciousnodealone
willbeminingthisforgedchain.

PotentialSPVWeaknesses

Ifimplementednaively,anSPVclienthasafewimportantweaknesses.
First,whiletheSPVclientcannotbeeasilyfooledintothinkingatransactionisinablockwhenitisnot,thereverseisnottrue.A
fullnodecansimplyliebyomission,leadinganSPVclienttobelieveatransactionhasnotoccurred.Thiscanbeconsideredaform
ofDenialofService.Onemitigationstrategyistoconnecttoanumberoffullnodes,andsendtherequeststoeachnode.However
thiscanbedefeatedbynetworkpartitioningorSybilattacks,sinceidentitiesareessentiallyfree,andcanbebandwidthintensive.
Caremustbetakentoensuretheclientisnotcutofffromhonestnodes.
Second,theSPVclientonlyrequeststransactionsfromfullnodescorrespondingtokeysitowns.IftheSPVclientdownloadsall
blocksandthendiscardsunneededones,thiscanbeextremelybandwidthintensive.Iftheysimplyaskfullnodesforblockswith
specifictransactions,thisallowsfullnodesacompleteviewofthepublicaddressesthatcorrespondtotheuser.Thisisalarge
privacyleak,andallowsfortacticssuchasdenialofserviceforclients,users,oraddressesthataredisfavoredbythoserunningfull
nodes,aswellastriviallinkingoffunds.Aclientcouldsimplyspammanyfaketransactionrequests,butthiscreatesalargestrain
ontheSPVclient,andcanendupdefeatingthepurposeofthinclientsaltogether.
Tomitigatethelatterissue,Bloomfiltershavebeenimplementedasamethodofobfuscationandcompressionofblockdata
requests.

BloomFilters

ABloomfilterisaspaceefficientprobabilisticdatastructurethatisusedtotestmembershipofanelement.Thedatastructure
achievesgreatdatacompressionattheexpenseofaprescribedfalsepositiverate.
ABloomfilterstartsoutasanarrayofnbitsallsetto0.Asetofkrandomhashfunctionsarechosen,eachofwhichoutputasingle
integerbetweentherangeof1andn.
WhenaddinganelementtotheBloomfilter,theelementishashedktimesseparately,andforeachofthekoutputs,the
correspondingBloomfilterbitatthatindexissetto1.
QueryingoftheBloomfilterisdonebyusingthesamehashfunctionsasbefore.Ifallkbitsaccessedinthebloomfilteraresetto
1,thisdemonstrateswithhighprobabilitythattheelementliesintheset.Clearly,thekindicescouldhavebeensetto1bythe
additionofacombinationofotherelementsinthedomain,buttheparametersallowtheusertochoosetheacceptablefalse
positiverate.
Removalofelementscanonlybedonebyscrappingthebloomfilterandrecreatingitfromscratch.

https://bitcoin.org/en/developer-guide

42/55

16/05/2015

Developer Guide - Bitcoin

ApplicationOfBloomFilters

Ratherthanviewingthefalsepositiveratesasaliability,itisusedtocreateatunableparameterthatrepresentsthedesiredprivacy
levelandbandwidthtradeoff.ASPVclientcreatestheirBloomfilterandsendsittoafullnodeusingthemessage filterload,
whichsetsthefilterforwhichtransactionsaredesired.Thecommand filteraddallowsadditionofdesireddatatothefilter
withoutneedingtosendatotallynewBloomfilter,and filterclearallowstheconnectiontoreverttostandardblockdiscovery
mechanisms.Ifthefilterhasbeenloaded,thenfullnodeswillsendamodifiedformofblocks,calledamerkleblock.Themerkle
blockissimplytheblockheaderwiththemerklebranchassociatedwiththesetBloomfilter.
AnSPVclientcannotonlyaddtransactionsaselementstothefilter,butalsopublickeys,datafromsignaturescriptsandpubkey
scripts,andmore.ThisenablesP2SHtransactionfinding.
Ifauserismoreprivacyconscious,hecansettheBloomfiltertoincludemorefalsepositives,attheexpenseofextrabandwidth
usedfortransactiondiscovery.Ifauserisonatightbandwidthbudget,hecansetthefalsepositiveratetolow,knowingthatthis
willallowfullnodesaclearviewofwhattransactionsareassociatedwithhisclient.
Resources:BitcoinJ,aJavaimplementationofBitcointhatisbasedontheSPVsecuritymodelandBloomfilters.Usedinmost
Androidwallets.
BloomfilterswerestandardizedforuseviaBIP37.ReviewtheBIPforimplementationdetails.

FutureProposals
TherearefutureproposalssuchasUnspentTransactionOutput(UTXO)commitmentsintheblockchaintofindamoresatisfactory
middlegroundforclientsbetweenneedingacompletecopyoftheblockchain,ortrustingthatamajorityofyourconnectedpeers
arenotlying.UTXOcommitmentswouldenableaverysecureclientusingafiniteamountofstorageusingadatastructurethatis
authenticatedintheblockchain.Thesetypeofproposalsare,however,inveryearlystages,andwillrequiresoftforksinthe
network.
Untilthesetypesofoperatingmodesareimplemented,modesshouldbechosenbasedonthelikelythreatmodel,computingand
bandwidthconstraints,andliabilityinbitcoinvalue.
Resources:OriginalThreadonUTXOCommitments,AuthenticatedPrefixTreesBIPProposal

P2P Network
TheBitcoinnetworkprotocolallowsfullnodes(peers)tocollaborativelymaintainapeertopeernetworkforblockandtransaction
exchange.ManySPVclientsalsousethisprotocoltoconnecttofullnodes.
Consensusrulesdonotcovernetworking,soBitcoinprogramsmayusealternativenetworksandprotocols,suchasthehigh
speedblockrelaynetworkusedbysomeminersandthededicatedtransactioninformationserversusedbysomewalletsthat
provideSPVlevelsecurity.
ToprovidepracticalexamplesoftheBitcoinpeertopeernetwork,thissectionusesBitcoinCoreasarepresentativefullnodeand
BitcoinJasarepresentativeSPVclient.Bothprogramsareflexible,soonlydefaultbehaviorisdescribed.Also,forprivacy,actual
IPaddressesintheexampleoutputbelowhavebeenreplacedwithRFC5737reservedIPaddresses.

PeerDiscovery

https://bitcoin.org/en/developer-guide

43/55

16/05/2015

Developer Guide - Bitcoin

Whenstartedforthefirsttime,programsdontknowtheIPaddressesofanyactivefullnodes.InordertodiscoversomeIP
addresses,theyqueryoneormoreDNSnames(calledDNSseeds)hardcodedintoBitcoinCoreandBitcoinJ.Theresponsetothe
lookupshouldincludeoneormoreDNSArecordswiththeIPaddressesoffullnodesthatmayacceptnewincomingconnections.
Forexample,usingtheUnix digcommand:
;; QUESTION SECTION:
;seed.bitcoin.sipa.be.
;; ANSWER SECTION:
seed.bitcoin.sipa.be.
seed.bitcoin.sipa.be.
seed.bitcoin.sipa.be.

IN A

60 IN A 192.0.2.113
60 IN A 198.51.100.231
60 IN A 203.0.113.183

[...]

TheDNSseedsaremaintainedbyBitcoincommunitymembers:someofthemprovidedynamicDNSseedserverswhich
automaticallygetIPaddressesofactivenodesbyscanningthenetworkothersprovidestaticDNSseedsthatareupdated
manuallyandaremorelikelytoprovideIPaddressesforinactivenodes.Ineithercase,nodesareaddedtotheDNSseedifthey
runonthedefaultBitcoinportsof8333formainnetor18333fortestnet.
DNSseedresultsarenotauthenticatedandamaliciousseedoperatorornetworkmaninthemiddleattackercanreturnonlyIP
addressesofnodescontrolledbytheattacker,isolatingaprogramontheattackersownnetworkandallowingtheattackertofeed
itbogustransactionsandblocks.Forthisreason,programsshouldnotrelyonDNSseedsexclusively.
Onceaprogramhasconnectedtothenetwork,itspeerscanbegintosendit addr(address)messageswiththeIPaddressesand
portnumbersofotherpeersonthenetwork,providingafullydecentralizedmethodofpeerdiscovery.BitcoinCorekeepsarecord
ofknownpeersinapersistentondiskdatabasewhichusuallyallowsittoconnectdirectlytothosepeersonsubsequentstartups
withouthavingtouseDNSseeds.
However,peersoftenleavethenetworkorchangeIPaddresses,soprogramsmayneedtomakeseveraldifferentconnection
attemptsatstartupbeforeasuccessfulconnectionismade.Thiscanaddasignificantdelaytotheamountoftimeittakesto
connecttothenetwork,forcingausertowaitbeforesendingatransactionorcheckingthestatusofpayment.
Toavoidthispossibledelay,BitcoinJalwaysusesdynamicDNSseedstogetIPaddressesfornodesbelievedtobecurrently
active.BitcoinCorealsotriestostrikeabalancebetweenminimizingdelaysandavoidingunnecessaryDNSseeduse:ifBitcoin
Corehasentriesinitspeerdatabase,itspendsupto11secondsattemptingtoconnecttoatleastoneofthembeforefallingback
toseedsifaconnectionismadewithinthattime,itdoesnotqueryanyseeds.
BothBitcoinCoreandBitcoinJalsoincludeahardcodedlistofIPaddressesandportnumberstoseveraldozennodeswhichwere
activearoundthetimethatparticularversionofthesoftwarewasfirstreleased.BitcoinCorewillstartattemptingtoconnectto
thesenodesifnoneoftheDNSseedservershaverespondedtoaquerywithin60seconds,providinganautomaticfallbackoption.
Asamanualfallbackoption,BitcoinCorealsoprovidesseveralcommandlineconnectionoptions,includingtheabilitytogetalist
ofpeersfromaspecificnodebyIPaddress,ortomakeapersistentconnectiontoaspecificnodebyIPaddress.Seethe -help
textfordetails.BitcoinJcanbeprogrammedtodothesamething.
Resources:BitcoinSeeder,theprogramrunbyseveraloftheseedsusedbyBitcoinCoreandBitcoinJ.TheBitcoinCoreDNS
SeedPolicy.ThehardcodedlistofIPaddressesusedbyBitcoinCoreandBitcoinJisgeneratedusingthemakeseedsscript.

ConnectingToPeers
Connectingtoapeerisdonebysendinga versionmessage,whichcontainsyourversionnumber,block,andcurrenttimetothe
remotenode.Theremotenoderespondswithitsown versionmessage.Thenbothnodessenda verackmessagetotheother
nodetoindicatetheconnectionhasbeenestablished.
https://bitcoin.org/en/developer-guide

44/55

16/05/2015

Developer Guide - Bitcoin

Onceconnected,theclientcansendtotheremotenode getaddrand addrmessagestogatheradditionalpeers.

Inordertomaintainaconnectionwithapeer,nodesbydefaultwillsendamessagetopeersbefore30minutesofinactivity.If90
minutespasswithoutamessagebeingreceivedbyapeer,theclientwillassumethatconnectionhasclosed.

InitialBlockDownload
Beforeafullnodecanvalidateunconfirmedtransactionsandrecentlyminedblocks,itmustdownloadandvalidateallblocksfrom
block1(theblockafterthehardcodedgenesisblock)tothecurrenttipofthebestblockchain.ThisistheInitialBlockDownload
(IBD)orinitialsync.
Althoughthewordinitialimpliesthismethodisonlyusedonce,itcanalsobeusedanytimealargenumberofblocksneedtobe
downloaded,suchaswhenapreviouslycaughtupnodehasbeenofflineforalongtime.Inthiscase,anodecanusetheIBD
methodtodownloadalltheblockswhichwereproducedsincethelasttimeitwasonline.
BitcoinCoreusestheIBDmethodanytimethelastblockonitslocalbestblockchainhasablockheadertimemorethan24hours
inthepast.BitcoinCore0.10.0willalsoperformIBDifitslocalbestblockchainismorethan144blockslowerthanitslocalbest
headerchain(thatis,thelocalblockchainismorethanabout24hoursinthepast).

BlocksFirst

BitcoinCore(upuntilversion0.9.3)usesasimpleinitialblockdownload(IBD)methodwellcallblocksfirst.Thegoalisto
downloadtheblocksfromthebestblockchaininsequence.
Yes

Fully-Synced Block Chain?

Listen For New Blocks (Inv)

No
Yes

Have Inventories?

Request Blocks (GetData)

No
Request Inventories (GetBlocks)
Overview Of Blocks-First Initial Blocks Download (IBD)

Thefirsttimeanodeisstarted,itonlyhasasingleblockinitslocalbestblockchainthehardcodedgenesisblock(block0).This
nodechoosesaremotepeer,calledthesyncnode,andsendsitthe getblocksmessageillustratedbelow.

IBD
Node

Sync
Node

GetBlocks Message
Message Header
Start String Command Size
f9beb4d9 getblocks 69

Checksum
f5fcbcad

Payload
Protocol Version
70002

Header Hash Count

1

Header Hashes (Highest-Height First)

6fe28c0ab6f1b3...d6190000000000
Stopping Hash (Zero Is "No Stop")
00000000000000...00000000000000
First getblocks message sent from Initial Blocks Download (IBD) node
https://bitcoin.org/en/developer-guide

45/55

16/05/2015

Developer Guide - Bitcoin

Intheheaderhashesfieldofthe getblocksmessage,thisnewnodesendstheheaderhashoftheonlyblockithas,thegenesis
block(6fe20000ininternalbyteorder).Italsosetsthestophashfieldtoallzeroestorequestamaximumsizeresponse.
Uponreceiptofthe getblocksmessage,thesyncnodetakesthefirst(andonly)headerhashandsearchesitslocalbestblock
chainforablockwiththatheaderhash.Itfindsthatblock0matches,soitreplieswith500blockinventories(themaximum
responsetoa getblocksmessage)startingfromblock1.Itsendstheseinventoriesinthe invmessageillustratedbelow.
IBD
Node

Sync
Node

Inv Message
Message Header
Start String
f9beb4d9

Command
inv

Size
18003

Checksum
25173c57

Payload
Number Of Inventories (Max 500 In Reply To GetBlocks)
500
Inventory Entries
Type
block

Unique Identifier (For Blocks, A Header Hash)

4860eb18bf1b1620...688e9a8300000000

block
bddd99ccfda39da1...065f626a00000000
...............498 more inventory entries...............
First inv message reply sent to Initial Blocks Download (IBD) node

Inventoriesareuniqueidentifiersforinformationonthenetwork.Eachinventorycontainsatypefieldandtheuniqueidentifierforan
instanceoftheobject.Forblocks,theuniqueidentifierisahashoftheblocksheader.
Theblockinventoriesappearinthe invmessageinthesameordertheyappearintheblockchain,sothisfirst invmessage
containsinventoriesforblocks1through501.(Forexample,thehashofblock1is48600000asseenintheillustrationabove.)
TheIBDnodeusesthereceivedinventoriestorequest128blocksfromthesyncnodeinthe getdatamessageillustratedbelow.
IBD
Node

Sync
Node

GetData Message
Message Header
Start String
f9beb4d9

Command
getdata

Size
4609

Checksum
33e41222

Payload
Number Of Objects Requested By Inventory
128
Objects Requested (Inventory Entries)
Type Unique Identifier (For Blocks, A Header Hash)
Block

4860eb18bf1b1620...688e9a8300000000

Block
bddd99ccfda39da1...065f626a00000000
...............126 more inventory entries...............
First getdata message sent from Initial Blocks Download (IBD) node

Itsimportanttoblocksfirstnodesthattheblocksberequestedandsentinorderbecauseeachblockheaderreferencestheheader
hashoftheprecedingblock.ThatmeanstheIBDnodecantfullyvalidateablockuntilitsparentblockhasbeenreceived.Blocks
thatcantbevalidatedbecausetheirparentshaventbeenreceivedarecalledorphanblocksasubsectionbelowdescribesthemin
moredetail.
Uponreceiptofthe getdatamessage,thesyncnodereplieswitheachoftheblocksrequested.Eachblockisputintoserialized
blockformatandsentinaseparate blockmessage.Thefirst blockmessagesent(forblock1)isillustratedbelow.

https://bitcoin.org/en/developer-guide

46/55

16/05/2015

IBD
Node

Developer Guide - Bitcoin

Sync
Node

Block Message
Message Header
Start String Command Size Checksum
f9beb4d9
block
215 934d270a
Payload
Serialized Block
010000006fe2...58eeac00000000

First block message sent to Initial Blocks Download (IBD) node

TheIBDnodedownloadseachblock,validatesit,andthenrequeststhenextblockithasntrequestedyet,maintainingaqueueof
upto128blockstodownload.Whenithasrequestedeveryblockforwhichithasaninventory,itsendsanother getblocks
messagetothesyncnoderequestingtheinventoriesofupto500moreblocks.Thissecond getblocksmessagecontains
multipleheaderhashesasillustratedbelow:

IBD
Node

Sync
Node

GetBlocks Message
Message Header
Start String Command Size
f9beb4d9 getblocks 677

Checksum
52be83ef

Payload
Protocol Version
70002

Header Hash Count

20

Header Hashes (Highest-Height First)

db773c8f3b90ef...64f64f00000000
459f16a1c695d0...f66d8000000000
......18 more header hashes......
Stopping Hash (Zero Is "No Stop")
00000000000000...00000000000000
Second getblocks message sent from Initial Blocks Download (IBD) node
Uponreceiptofthesecond getblocksmessage,thesyncnodesearchesitslocalbestblockchainforablockthatmatchesoneof
theheaderhashesinthemessage,tryingeachhashintheordertheywerereceived.Ifitfindsamatchinghash,itreplieswith500
blockinventoriesstartingwiththenextblockfromthatpoint.Butifthereisnomatchinghash(besidesthestoppinghash),it
assumestheonlyblockthetwonodeshaveincommonisblock0andsoitsendsan invstartingwithblock1(thesame inv
messageseenseveralillustrationsabove).
ThisrepeatedsearchallowsthesyncnodetosendusefulinventorieseveniftheIBDnodeslocalblockchainforkedfromthesync
nodeslocalblockchain.ThisforkdetectionbecomesincreasinglyusefultheclosertheIBDnodegetstothetipoftheblockchain.
WhentheIBDnodereceivesthesecond invmessage,itwillrequestthoseblocksusing getdatamessages.Thesyncnodewill
respondwith blockmessages.ThentheIBDnodewillrequestmoreinventorieswithanother getblocksmessageandthe
cyclewillrepeatuntiltheIBDnodeissyncedtothetipoftheblockchain.Atthatpoint,thenodewillacceptblockssentthroughthe
regularblockbroadcastingdescribedinalatersubsection.

BlocksFirstAdvantages&Disadvantages

TheprimaryadvantageofblocksfirstIBDisitssimplicity.TheprimarydisadvantageisthattheIBDnodereliesonasinglesync
nodeforallofitsdownloading.Thishasseveralimplications:
SpeedLimits:Allrequestsaremadetothesyncnode,soifthesyncnodehaslimiteduploadbandwidth,theIBDnodewillhave
slowdownloadspeeds.Note:ifthesyncnodegoesoffline,BitcoinCorewillcontinuedownloadingfromanothernodebutitwill
https://bitcoin.org/en/developer-guide

47/55

16/05/2015

Developer Guide - Bitcoin

stillonlydownloadfromasinglesyncnodeatatime.
DownloadRestarts:Thesyncnodecansendanonbest(butotherwisevalid)blockchaintotheIBDnode.TheIBDnodewont
beabletoidentifyitasnonbestuntiltheinitialblockdownloadnearscompletion,forcingtheIBDnodetorestartitsblockchain
downloadoveragainfromadifferentnode.BitcoinCoreshipswithseveralblockchaincheckpointsatvariousblockheights
selectedbydeveloperstohelpanIBDnodedetectthatitisbeingfedanalternativeblockchainhistoryallowingtheIBDnode
torestartitsdownloadearlierintheprocess.
DiskFillAttacks:Closelyrelatedtothedownloadrestarts,ifthesyncnodesendsanonbest(butotherwisevalid)blockchain,
thechainwillbestoredondisk,wastingspaceandpossiblyfillingupthediskdrivewithuselessdata.
HighMemoryUse:Whethermaliciouslyorbyaccident,thesyncnodecansendblocksoutoforder,creatingorphanblocks
whichcantbevalidateduntiltheirparentshavebeenreceivedandvalidated.Orphanblocksarestoredinmemorywhilethey
awaitvalidation,whichmayleadtohighmemoryuse.
AlloftheseproblemsareaddressedinpartorinfullbytheheadersfirstIBDmethodusedinBitcoinCore0.10.0.
Resources:Thetablebelowsummarizesthemessagesmentionedthroughoutthissubsection.Thelinksinthemessagefieldwill
takeyoutothereferencepageforthatmessage.
Message
FromTo
Payload

getblocks

inv

getdata

block

IBDSync

SyncIBD

IBDSync

SyncIBD

Oneormoreheader

Upto500blockinventories(unique

Oneormoreblock

Oneserialized

hashes

identifiers)

inventories

block

HeadersFirst

BitcoinCore0.10.0usesaninitialblockdownload(IBD)methodcalledheadersfirst.Thegoalistodownloadtheheadersforthe
bestheaderchain,partiallyvalidatethemasbestaspossible,andthendownloadthecorrespondingblocksinparallel.Thissolves
severalproblemswiththeolderblocksfirstIBDmethod.
Fully-Synced Block Chain?

Yes

Listen For New Blocks (Inv)

No
Fully-Synced Header Chain?
No
Request Headers (GetHeaders)

Yes
No

Request Blocks (GetData)

Yes
More Headers Than Blocks?

Overview Of Headers-First Initial Blocks Download (IBD)

Thefirsttimeanodeisstarted,itonlyhasasingleblockinitslocalbestblockchainthehardcodedgenesisblock(block0).The
nodechoosesaremotepeer,whichwellcallthesyncnode,andsendsitthe getheadersmessageillustratedbelow.

https://bitcoin.org/en/developer-guide

48/55

16/05/2015

Developer Guide - Bitcoin

IBD
Node

Sync
Node

GetHeaders Message
Message Header
Start String Command
Size
f9beb4d9 getheaders 69

Checksum
f5fcbcad

Payload
Protocol Version
Header Hash Count
70002
1
Header Hashes (Highest-Height First)
6fe28c0ab6f1b3...d6190000000000
Stopping Hash (Zero Is "No Stop")
00000000000000...00000000000000
First getheaders message sent from Initial Blocks Download (IBD) node
Intheheaderhashesfieldofthe getheadersmessage,thenewnodesendstheheaderhashoftheonlyblockithas,thegenesis
block(6fe20000ininternalbyteorder).Italsosetsthestophashfieldtoallzeroestorequestamaximumsizeresponse.
Uponreceiptofthe getheadersmessage,thesyncnodetakesthefirst(andonly)headerhashandsearchesitslocalbestblock
chainforablockwiththatheaderhash.Itfindsthatblock0matches,soitreplieswith2,000header(themaximumresponse)
startingfromblock1.Itsendstheseheaderhashesinthe headersmessageillustratedbelow.
IBD
Node

Sync
Node

Headers Message
Message Header
Start String
f9beb4d9

Command
headers

Size
162003

Checksum
a65b2b77

Payload
Number Of Headers (Max 2,000 In Reply To GetHeaders)
2000
80-byte Block Headers + 0x00 (The Empty Tx Count)
010000006fe28cab...ff001d01e3629900
010000004860eb18...ff001d08d2bd6100
...............1,998 more block headers...............
First headers message reply sent to Initial Blocks Download (IBD) node

TheIBDnodecanpartiallyvalidatetheseblockheadersbyensuringthatallfieldsfollowconsensusrulesandthatthehashofthe
headerisbelowthetargetthresholdaccordingtothenBitsfield.(Fullvalidationstillrequiresalltransactionsfromthecorresponding
block.)
AftertheIBDnodehaspartiallyvalidatedtheblockheaders,itcandotwothingsinparallel:
1. DownloadMoreHeaders:theIBDnodecansendanother getheadersmessagetothesyncnodetorequestthenext2,000
headersonthebestheaderchain.Thoseheaderscanbeimmediatelyvalidatedandanotherbatchrequestedrepeatedlyuntila
headersmessageisreceivedfromthesyncnodewithfewerthan2,000headers,indicatingthatithasnomoreheadersto

offer.Asofthiswriting,headerssynccanbecompletedinfewerthan200roundtrips,orabout32MBofdownloadeddata.
OncetheIBDnodereceivesa headersmessagewithfewerthan2,000headersfromthesyncnode,itsendsa getheaders
messagetoeachofitsoutboundpeerstogettheirviewofbestheaderchain.Bycomparingtheresponses,itcaneasily
determineiftheheadersithasdownloadedbelongtothebestheaderchainreportedbyanyofitsoutboundpeers.Thismeansa
dishonestsyncnodewillquicklybediscoveredevenifcheckpointsarentused(aslongastheIBDnodeconnectstoatleastone
honestpeerBitcoinCorewillcontinuetoprovidecheckpointsincasehonestpeerscantbefound).
2. DownloadBlocks:WhiletheIBDnodecontinuesdownloadingheaders,andaftertheheadersfinishdownloading,theIBDnode
willrequestanddownloadeachblock.TheIBDnodecanusetheblockheaderhashesitcomputedfromtheheaderchainto
create getdatamessagesthatrequesttheblocksitneedsbytheirinventory.Itdoesntneedtorequestthesefromthesync
https://bitcoin.org/en/developer-guide

49/55

16/05/2015

Developer Guide - Bitcoin

nodeitcanrequestthemfromanyofitsfullnodepeers.(Althoughnotallfullnodesmaystoreallblocks.)Thisallowsittofetch
blocksinparallelandavoidhavingitsdownloadspeedconstrainedtotheuploadspeedofasinglesyncnode.
Tospreadtheloadbetweenmultiplepeers,BitcoinCorewillonlyrequestupto16blocksatatimefromasinglepeer.Combined
withitsmaximumof8outboundconnections,thismeansheadersfirstBitcoinCorewillrequestamaximumof128blocks
simultaneouslyduringIBD(thesamemaximumnumberthatblocksfirstBitcoinCorerequestedfromitssyncnode).
Downloaded And Validated
1
Downloaded
From Node A

2
Downloaded
From Node B

Download Window
Blocks Not Validated Yet
3
Requested
From Node A

4
Downloaded
From Node B

5
Requested
From Node B

Simulated Headers-First Download Window (Real Window Is Much Larger)

BitcoinCoresheadersfirstmodeusesa1,024blockmovingdownloadwindowtomaximizedownloadspeed.Thelowestheight
blockinthewindowisthenextblocktobevalidatediftheblockhasntarrivedbythetimeBitcoinCoreisreadytovalidateit,
BitcoinCorewillwaitaminimumoftwomoresecondsforthestallingnodetosendtheblock.Iftheblockstillhasntarrived,Bitcoin
Corewilldisconnectfromthestallingnodeandattempttoconnecttoanothernode.Forexample,intheillustrationabove,NodeA
willbedisconnectedifitdoesntsendblock3withinatleasttwoseconds.
OncetheIBDnodeissyncedtothetipoftheblockchain,itwillacceptblockssentthroughtheregularblockbroadcasting
describedinalatersubsection.
Resources:Thetablebelowsummarizesthemessagesmentionedthroughoutthissubsection.Thelinksinthemessagefieldwill
takeyoutothereferencepageforthatmessage.
Message

getheaders

headers

getdata

block

FromTo

IBDSync

SyncIBD

IBDMany

ManyIBD

Payload

Oneormoreheader
hashes

Upto2,000block
headers

Oneormoreblockinventoriesderivedfrom
headerhashes

Oneserialized
block

BlockBroadcasting
Whenaminerdiscoversanewblock,itbroadcaststhenewblocktoitspeersusingoneofthefollowingmethods:
UnsolicitedBlockPush:theminersendsa blockmessagetoeachofitsfullnodepeerswiththenewblock.Theminercan
reasonablybypassthestandardrelaymethodinthiswaybecauseitknowsnoneofitspeersalreadyhavethejustdiscovered
block.
StandardBlockRelay:theminer,actingasastandardrelaynode,sendsan invmessagetoeachofitspeers(bothfullnode
andSPV)withaninventoryreferringtothenewblock.Themostcommonresponsesare:
Eachblocksfirst(BF)peerthatwantstheblockreplieswitha getdatamessagerequestingthefullblock.
Eachheadersfirst(HF)peerthatwantstheblockreplieswitha getheadersmessagecontainingtheheaderhashofthe
highestheightheaderonitsbestheaderchain,andlikelyalsosomeheadersfurtherbackonthebestheaderchaintoallow
forkdetection.Thatmessageisimmediatelyfollowedbya getdatamessagerequestingthefullblock.Byrequesting
headersfirst,aheadersfirstpeercanrefuseorphanblocksasdescribedinthesubsectionbelow.
EachSimplifiedPaymentVerification(SPV)clientthatwantstheblockreplieswitha getdatamessagetypicallyrequestinga
https://bitcoin.org/en/developer-guide

50/55

16/05/2015

Developer Guide - Bitcoin

merkleblock.
Theminerrepliestoeachrequestaccordinglybysendingtheblockina blockmessage,oneormoreheadersina headers
message,orthemerkleblockandtransactionsrelativetotheSPVclientsbloomfilterina merkleblockmessagefollowedby
zeroormore txmessages.
Fullnodesvalidatethereceivedblockandthenadvertiseittotheirpeersusingthestandardblockrelaymethoddescribedabove.
Thecondensedtablebelowhighlightstheoperationofthemessagesdescribedabove(Relay,BF,HF,andSPVrefertotherelay
node,ablocksfirstnode,aheadersfirstnode,andanSPVclientanyreferstoanodeusinganyblockretrievalmethod.)
Message
FromTo

inv

getdata

RelayAny
Theinventory

Payload

ofthenew
block

Message
FromTo

Payload

BFRelay
Theinventoryof
thenewblock

block

merkleblock

getheaders

headers

HFRelay

RelayHF

Oneormoreheaderhashesonthe

Upto2,000headersconnecting

HFnodesbestheaderchain

HFnodesBHCtorelaynodes

(BHC)

BHC

tx

RelayBF/HF

RelaySPV

RelaySPV

Thenewblock

Thenewblock

Serializedtransactionsfromthe

inserialized

filteredintoa

newblockthatmatchthebloom

format

merkleblock

filter

OrphanBlocks

Blocksfirstnodesmaydownloadorphanblocksblockswhosepreviousblockheaderhashfieldreferstoablockheaderthisnode
hasntseenyet.Inotherwords,orphanblockshavenoknownparent(unlikestaleblocks,whichhaveknownparentsbutwhich
arentpartofthebestblockchain).

Orphan blocks have no known parent, so they can't be validated

1
Parent: 0

2
Parent: 1

3
Parent: 2

5 (Orphan)
Parent: 4

2 (Stale)
Parent: 1
Stale blocks are valid but not part of the best block chain
Whenablocksfirstnodedownloadsanorphanblock,itwillnotvalidateit.Instead,itwillsenda getblocksmessagetothenode
whichsenttheorphanblockthebroadcastingnodewillrespondwithan invmessagecontaininginventoriesofanyblocksthe
downloadingnodeismissing(upto500)thedownloadingnodewillrequestthoseblockswitha getdatamessageandthe
broadcastingnodewillsendthoseblockswitha blockmessage.Thedownloadingnodewillvalidatethoseblocks,andoncethe
parentoftheformerorphanblockhasbeenvalidated,itwillvalidatetheformerorphanblock.
Headersfirstnodesavoidsomeofthiscomplexitybyalwaysrequestingblockheaderswiththe getheadersmessagebefore
requestingablockwiththe getdatamessage.Thebroadcastingnodewillsenda headersmessagecontainingalltheblock
https://bitcoin.org/en/developer-guide

51/55

16/05/2015

Developer Guide - Bitcoin

headers(upto2,000)itthinksthedownloadingnodeneedstoreachthetipofthebestheaderchaineachofthoseheaderswill
pointtoitsparent,sowhenthedownloadingnodereceivesthe blockmessage,theblockshouldntbeanorphanblockallofits
parentsshouldbeknown(eveniftheyhaventbeenvalidatedyet).If,despitethis,theblockreceivedinthe blockmessageisan
orphanblock,aheadersfirstnodewilldiscarditimmediately.
However,orphandiscardingdoesmeanthatheadersfirstnodeswillignoreorphanblockssentbyminersinanunsolicitedblock
push.

TransactionBroadcasting
Inordertosendatransactiontoapeer,an invmessageissent.Ifa getdataresponsemessageisreceived,thetransactionis
sentusing tx.Thepeerreceivingthistransactionalsoforwardsthetransactioninthesamemanner,giventhatitisavalid
transaction.

MemoryPool

Fullpeersmaykeeptrackofunconfirmedtransactionswhichareeligibletobeincludedinthenextblock.Thisisessentialfor
minerswhowillactuallyminesomeorallofthosetransactions,butitsalsousefulforanypeerwhowantstokeeptrackof
unconfirmedtransactions,suchaspeersservingunconfirmedtransactioninformationtoSPVclients.
BecauseunconfirmedtransactionshavenopermanentstatusinBitcoin,BitcoinCorestorestheminnonpersistentmemory,calling
themamemorypoolormempool.Whenapeershutsdown,itsmemorypoolislostexceptforanytransactionsstoredbyitswallet.
Thismeansthatneverminedunconfirmedtransactionstendtoslowlydisappearfromthenetworkaspeersrestartorastheypurge
sometransactionstomakeroominmemoryforothers.
Transactionswhichareminedintoblocksthatlaterbecomestaleblocksmaybeaddedbackintothememorypool.Thesereadded
transactionsmaybereremovedfromthepoolalmostimmediatelyifthereplacementblocksincludethem.Thisisthecasein
BitcoinCore,whichremovesstaleblocksfromthechainonebyone,startingwiththetip(highestblock).Aseachblockisremoved,
itstransactionsareaddedbacktothememorypool.Afterallofthestaleblocksareremoved,thereplacementblocksareaddedto
thechainonebyone,endingwiththenewtip.Aseachblockisadded,anytransactionsitconfirmsareremovedfromthememory
pool.
SPVclientsdonthaveamemorypoolforthesamereasontheydontrelaytransactions.Theycantindependentlyverifythata
transactionhasntyetbeenincludedinablockandthatitonlyspendsUTXOs,sotheycantknowwhichtransactionsareeligibleto
beincludedinthenextblock.

MisbehavingNodes
Takenotethatforbothtypesofbroadcasting,mechanismsareinplacetopunishmisbehavingpeerswhotakeupbandwidthand
computingresourcesbysendingfalseinformation.Ifapeergetsabanscoreabovethe -banscore=<n>threshold,hewillbe
bannedforthenumberofsecondsdefinedby -bantime=<n>,whichis86,400bydefault(24hours).

Alerts
Incaseofabugorattack,theBitcoinCoredevelopersprovideaBitcoinalertservicewithanRSSfeedandusersofBitcoinCore
canchecktheerrorfieldofthe getinfoRPCresultstogetcurrentlyactivealertsfortheirspecificversionofBitcoinCore.
Thesemessagesareaggressivelybroadcastusingthe alertmessage,beingsenttoeachpeeruponconnectforthedurationof
https://bitcoin.org/en/developer-guide

52/55

16/05/2015

Developer Guide - Bitcoin

thealert.
ThesemessagesaresignedbyaspecificECDSAprivatekeythatonlyasmallnumberofdeveloperscontrol.
Resource:MoredetailsaboutthestructureofmessagesandacompletelistofmessagetypescanbefoundintheP2Preference
section.

Mining
Miningaddsnewblockstotheblockchain,makingtransactionhistoryhardtomodify.Miningtodaytakesontwoforms:
Solomining,wheretheminerattemptstogeneratenewblocksonhisown,withtheproceedsfromtheblockrewardand
transactionfeesgoingentirelytohimself,allowinghimtoreceivelargepaymentswithahighervariance(longertimebetween
payments)
Pooledmining,wheretheminerpoolsresourceswithotherminerstofindblocksmoreoften,withtheproceedsbeingshared
amongthepoolminersinroughcorrelationtotheamountofhashingpowertheyeachcontributed,allowingtheminertoreceive
smallpaymentswithalowervariance(shortertimebetweenpayments).

SoloMining
Asillustratedbelow,solominerstypicallyuse bitcoindtogetnewtransactionsfromthenetwork.Theirminingsoftware
periodicallypolls bitcoindfornewtransactionsusingthe getblocktemplateRPC,whichprovidesthelistofnewtransactions
plusthepublickeytowhichthecoinbasetransactionshouldbesent.

P2P
Network

TXes

bitcoind

Blocks

Block
Template
Blocks

Mining
Software

Block
Headers &
Targets
Headers
Below
Target

ASIC

Solo Bitcoin Mining Workflow

Theminingsoftwareconstructsablockusingthetemplate(describedbelow)andcreatesablockheader.Itthensendsthe80byte
blockheadertoitsmininghardware(anASIC)alongwithatargetthreshold(difficultysetting).Themininghardwareiterates
througheverypossiblevaluefortheblockheadernonceandgeneratesthecorrespondinghash.
Ifnoneofthehashesarebelowthethreshold,themininghardwaregetsanupdatedblockheaderwithanewmerklerootfromthe
miningsoftwarethisnewblockheaderiscreatedbyaddingextranoncedatatothecoinbasefieldofthecoinbasetransaction.
Ontheotherhand,ifahashisfoundbelowthetargetthreshold,themininghardwarereturnstheblockheaderwiththesuccessful
noncetotheminingsoftware.Theminingsoftwarecombinestheheaderwiththeblockandsendsthecompletedblockto
bitcoindtobebroadcasttothenetworkforadditiontotheblockchain.

PoolMining
Poolminersfollowasimilarworkflow,illustratedbelow,whichallowsminingpooloperatorstopayminersbasedontheirshareof
theworkdone.Theminingpoolgetsnewtransactionsfromthenetworkusing bitcoind.Usingoneofthemethodsdiscussed
later,eachminersminingsoftwareconnectstothepoolandrequeststheinformationitneedstoconstructblockheaders.

https://bitcoin.org/en/developer-guide

53/55

16/05/2015

P2P
Network

Developer Guide - Bitcoin

TXes
Blocks

Mining
Pool

Prototype
Block
Shares

Mining
Software

Block
Headers &
Targets
Headers
Below
Target

ASIC

Pool-Based Bitcoin Mining Workflow

Inpooledmining,theminingpoolsetsthetargetthresholdafewordersofmagnitudehigher(lessdifficult)thanthenetwork
difficulty.Thiscausesthemininghardwaretoreturnmanyblockheaderswhichdonthashtoavalueeligibleforinclusiononthe
blockchainbutwhichdohashbelowthepoolstarget,proving(onaverage)thattheminercheckedapercentageofthepossible
hashvalues.
Theminerthensendstothepoolacopyoftheinformationthepoolneedstovalidatethattheheaderwillhashbelowthetargetand
thatthetheblockoftransactionsreferredtobytheheadermerklerootfieldisvalidforthepoolspurposes.(Thisusuallymeans
thatthecoinbasetransactionmustpaythepool.)
Theinformationtheminersendstothepooliscalledasharebecauseitprovestheminerdidashareofthework.Bychance,some
sharesthepoolreceiveswillalsobebelowthenetworktargettheminingpoolsendsthesetothenetworktobeaddedtothe
blockchain.
Theblockrewardandtransactionfeesthatcomefromminingthatblockarepaidtotheminingpool.Theminingpoolpaysouta
portionoftheseproceedstoindividualminersbasedonhowmanysharestheygenerated.Forexample,iftheminingpoolstarget
thresholdis100timeslowerthanthenetworktargetthreshold,100shareswillneedtobegeneratedonaveragetocreatea
successfulblock,sotheminingpoolcanpay1/100thofitspayoutforeachsharereceived.Differentminingpoolsusedifferent
rewarddistributionsystemsbasedonthisbasicsharesystem.

BlockPrototypes
Inbothsoloandpoolmining,theminingsoftwareneedstogettheinformationnecessarytoconstructblockheaders.This
subsectiondescribes,inalinearway,howthatinformationistransmittedandused.However,inactualimplementations,parallel
threadsandqueuingareusedtokeepASIChashersworkingatmaximumcapacity,

getworkRPC

ThesimplestandearliestmethodwasthenowdeprecatedBitcoinCore getworkRPC,whichconstructsaheaderfortheminer
directly.Sinceaheaderonlycontainsasingle4bytenoncegoodforabout4gigahashes,manymodernminersneedtomake
dozensorhundredsof getworkrequestsasecond.Solominersmaystilluse getwork,butmostpoolstodaydiscourageor
disallowitsuse.

getblocktemplateRPC

AnimprovedmethodistheBitcoinCore getblocktemplateRPC.Thisprovidestheminingsoftwarewithmuchmoreinformation:
1. Theinformationnecessarytoconstructacoinbasetransactionpayingthepoolorthesolominers bitcoindwallet.
2. Acompletedumpofthetransactions bitcoindortheminingpoolsuggestsincludingintheblock,allowingtheminingsoftware
toinspectthetransactions,optionallyaddadditionaltransactions,andoptionallyremovenonrequiredtransactions.
3. Otherinformationnecessarytoconstructablockheaderforthenextblock:theblockversion,previousblockhash,andbits
https://bitcoin.org/en/developer-guide

54/55

16/05/2015

Developer Guide - Bitcoin

(target).
4. Theminingpoolscurrenttargetthresholdforacceptingshares.(Forsolominers,thisisthenetworktarget.)
Usingthetransactionsreceived,theminingsoftwareaddsanoncetothecoinbaseextranoncefieldandthenconvertsallthe
transactionsintoamerkletreetoderiveamerklerootitcanuseinablockheader.Whenevertheextranoncefieldneedstobe
changed,theminingsoftwarerebuildsthenecessarypartsofthemerkletreeandupdatesthetimeandmerklerootfieldsinthe
blockheader.
Likeall bitcoindRPCs, getblocktemplateissentoverHTTP.Toensuretheygetthemostrecentwork,mostminersuseHTTP
longpolltoleavea getblocktemplaterequestopenatalltimes.Thisallowstheminingpooltopushanew getblocktemplateto
theminerassoonasanymineronthepeertopeernetworkpublishesanewblockorthepoolwantstosendmoretransactionsto
theminingsoftware.

Stratum

Awidelyusedalternativeto getblocktemplateistheStratumminingprotocol.Stratumfocusesongivingminerstheminimal
informationtheyneedtoconstructblockheadersontheirown:
1. Theinformationnecessarytoconstructacoinbasetransactionpayingthepool.
2. Thepartsofthemerkletreewhichneedtoberehashedtocreateanewmerklerootwhenthecoinbasetransactionisupdated
withanewextranonce.Theotherpartsofthemerkletree,ifany,arenotsent,effectivelylimitingtheamountofdatawhich
needstobesentto(atmost)aboutakilobyteatcurrenttransactionvolume.
3. Alloftheothernonmerklerootinformationnecessarytoconstructablockheaderforthenextblock.
4. Theminingpoolscurrenttargetthresholdforacceptingshares.
Usingthecoinbasetransactionreceived,theminingsoftwareaddsanoncetothecoinbaseextranoncefield,hashesthecoinbase
transaction,andaddsthehashtothereceivedpartsofthemerkletree.Thetreeishashedasnecessarytocreateamerkleroot,
whichisaddedtotheblockheaderinformationreceived.Whenevertheextranoncefieldneedstobechanged,theminingsoftware
updatesandrehashesthecoinbasetransaction,rebuildsthemerkleroot,andupdatestheheadermerklerootfield.
Unlike getblocktemplate,minersusingStratumcannotinspectoraddtransactionstotheblocktheyrecurrentlymining.Also
unlike getblocktemplate,theStratumprotocolusesatwowayTCPsocketdirectly,sominersdontneedtouseHTTPlongpollto
ensuretheyreceiveimmediateupdatesfromminingpoolswhenanewblockisbroadcasttothepeertopeernetwork.
Resources:TheGPLv3BFGMinerminingsoftwareandAGPLv3Eloipoolminingpoolsoftwarearewidelyusedamongminersand
pools.ThelibblkmakerClibraryandpythonblkmakerlibrary,bothMITlicensed,caninterpretGetBlockTemplateforyour
programs.

https://bitcoin.org/en/developer-guide

55/55