https://en.bitcoin.it/w/api.php?action=feedcontributions&user=Tonikt&feedformat=atomBitcoin Wiki - User contributions [en]2024-03-19T08:08:18ZUser contributionsMediaWiki 1.30.0https://en.bitcoin.it/w/index.php?title=Transaction_broadcasting&diff=68646Transaction broadcasting2021-05-06T09:44:52Z<p>Tonikt: Added blockstream.info</p>
<hr />
<div>{{seealso|Satoshi Client Transaction Exchange}}<br />
<br />
==See Also==<br />
<br />
* [[Transaction accelerator]]<br />
<br />
Third party sites to (re-)submit a raw, signed transaction to the network; sometimes referred to as "pushtx":<br />
<br />
* https://coinb.in/#broadcast<br />
* https://www.smartbit.com.au/txs/pushtx<br />
* https://blockchair.com/broadcast<br />
* https://live.blockcypher.com/btc/pushtx/<br />
* https://btc.com/tools/tx/publish<br />
* https://www.viabtc.com/tools/broadcast<br />
* https://insight.bitpay.com/tx/send<br />
* https://blockchain.info/pushtx<br />
* https://www.f2pool.com/pushtx (Needs referral code from pool operator.)<br />
* https://chainquery.com/bitcoin-api/sendrawtransaction<br />
* https://blockstream.info/tx/push<br />
<br />
==Footnotes==<br />
[[Category:Developer]]</div>Tonikthttps://en.bitcoin.it/w/index.php?title=Gocoin&diff=64662Gocoin2017-12-28T21:56:54Z<p>Tonikt: /* Architecture */</p>
<hr />
<div>An open-source Bitcoin solution written in Go language (golang).<br />
It can be built for every platform that has a working Go compiler.<br />
It uses a proprietary license, though is free to use for non-commercial purposes.<br />
<br />
==Architecture==<br />
<br />
Gocoin's architecture is quite different from the reference implementation (of the Satoshi client).<br />
<br />
===Libraries===<br />
<br />
====btc / chain / script ====<br />
The core of the software is a library that essentially provides the blockchain protocol parser. That includes script parsing, ECDSA signature verification, but also things like address encoding, parsing of canonical signatures or extracting hashes that need to be signed for specific inputs of a given transaction.<br />
<br />
It is a relatively big library, that contains many useful bitcoin function.<br />
<br />
Inside the package, there is also a blocks persistent storage database (blockdb.go) - it is just a simple plain storage (that can only grow), with an index. It uses snappy compression, allowing to save about 30% of the disk space.<br />
<br />
====utxo====<br />
The core library interfaces directly with a UTXO database backed.<br />
For this purpose Gocoin uses its own database engine, that has been designed to deal with the specific characteristics of bitcoin's UTXO database.<br />
<br />
====secp256k1====<br />
To speed up the Elliptic Curve operations [https://github.com/bitcoin/secp256k1 the secp256k1 library by sipa] has been ported to Go.<br />
<br />
===Online client===<br />
The online client is a kind of a server software (or a peer-to-peer node) that is meant to be running all the time.<br />
<br />
It handles the network related communication, feeds the core lib with new incoming blockchain data, monitors balances on the wallets' addresses, manages transaction memory pool and the peers database. It also provides an interactive user interface.<br />
<br />
===Offline wallet===<br />
The wallet application is responsible for creating private keys (from a seed password) and for signing transactions with them.<br />
It can also sign text messages with private keys and decode raw transactions.<br />
<br />
Unlike the client, the wallet is not an app that is meant te be running continuously. <br />
A user runs it with the requested task - the wallet does the job and exits (back to the command prompt).<br />
<br />
===Other tools===<br />
There is also a set of more and less useful tools (''github.com/piotrnar/gocoin/tools'') that are an integral part of the Gocoin bitcoin software.<br />
<br />
For instance '''btcversig''' can verify a validity of a bitcoin signature - it is the substitute of the reference client's '''verifymessage''' RPC-API.<br />
<br />
The tool '''type2determ''' can, at the other hand, calculate Type-2 deterministic addresses, without a need to access the wallet (the private keys).<br />
<br />
==Features==<br />
<br />
Gocoin has a several unique features, that distinguish it from the original bitcoin client.<br />
===Node / Client===<br />
* All the unspent outputs are kept in system memory.<br />
* A current balances of any P2PKH, P2SH or P2WPKH address is kept in memory for a quick access.<br />
* Can be monitored and controlled through a web interface (from a web browser).<br />
* Works with its own implementation of a cold storage wallet.<br />
* Web interface allows a user to create raw transactions from specific inputs ([[Coin Control]]), as well as multisig transactions ([[P2SH]])<br />
* The blocks are stored on the disk in a compressed form (using [https://code.google.com/p/snappy/ snappy] compression) which saves ~20% of space. They can also be purged (entirely or partially) from the disk.<br />
* Up till version '''1.6.4''' it supported monitoring and fetching balance of stealth addresses (the ones implemented in [[Dark Wallet]])<br />
* From version 1.9.4 onward, both the wallet and the client, support native segwit addresses (P2WPKH encoded as bech32)<br />
<br />
===Wallet===<br />
* For security reasons, it is supposed to be used with a PC that has never been (and will never be) connected to a network.<br />
* The wallet is deterministic and a seed-password based. As long as you can remember the password, there is no need for any backups.<br />
* Additionally it can import private keys from an existing bitcoin wallet (must be in [[Private key#Base 58 Wallet Import format | Base 58 Wallet Import format]] format).<br />
* Has very low hardware requirements. Can be run on i.e. Raspberry Pi<br />
* Can generate [https://bitcointalk.org/index.php?topic=19137.0 Type-2] deterministic keys/addresses<br />
* Supports (partial) signing of [[P2SH]] multisig transactions (the ones that use [[Script#Crypto | OP_CHECKMULTISIG opcode]]).<br />
* Supports spending to stealth addresses as implemented in Dark Wallet<br />
<br />
===Node-less mode===<br />
It is possible to use Gocoin's wallet, without a need to have a running client node. This may come handy since the node requires quite an advanced hardware and a large amount of time for the initial bootstrap.<br />
<br />
In such a case the required balance files are fetched with a tool called '''balio''', from popular block explorers.<br />
<br />
==Requirements==<br />
===Client===<br />
Requires 64-bit platform and at least 8GB of system memory.<br />
<br />
The file system that stores the blockchain data must be able to handle files larger than 4GB.<br />
<br />
===Wallet===<br />
The wallet app has very little hardware requirements. As long as you can build it for a specific architecture, it should work there.<br />
<br />
Gocoin wallet has been even used on Raspberry Pi model A.<br />
<br />
For security reasons it is strongly recommended to run the wallet on an encrypted file system, with an encrypted swap file.<br />
<br />
==Limitations==<br />
* No GUI, though the online node has web interface which acts like a GUI<br />
* No IPv6<br />
* No UPnP<br />
* No support for non-confirmed transactions (they are invisible in the balance)<br />
* No support for [[Protocol_specification#filterload, filteradd, filterclear, merkleblock | bloom filters]] protocol ([[BIP 0037]]) and the [[Protocol_specification#mempool | mempool]] command<br />
* No routing of [[Protocol_specification#alert | alert]] messages<br />
* No support for multisig stealth addresses (yet)<br />
<br />
==History==<br />
<br />
Gocoin was written by a single person for a private purposes.<br />
<br />
The software's first public release was announced in May 2013 on Bitcointalk forum.<ref>https://bitcointalk.org/index.php?topic=199306.0</ref><br />
Ever since then, the software has been actively maintained and further developed, being armed with new features, further optimized and cleaned up from issues.<br />
<br />
It happened twice that the client wasn't able to catch up with the blockchain, because of the implementation difference of the chain parsing protocol that was causing it to reject a block (transaction) that the reference implementation would accept. In both cases the issue was fixed within single days. The fist case happened in July 2013 and the fix was introduced in version 0.5.7. The second time was in March 2014 - the fix came with release 0.9.3.<br />
<br />
==External Links==<br />
<br />
* [http://gocoin.pl Homepage]<br />
* [https://github.com/piotrnar/gocoin Github repo]<br />
* [https://bitcointalk.org/index.php?topic=199306.0 Bitcointalk forum topic]<br />
<br />
==References==<br />
<references /><br />
<br />
[[Category:Software]]<br />
[[Category:Clients]]<br />
[[Category:Open Source]]<br />
[[Category:Wallets]]<br />
[[Category:Google Go]]</div>Tonikthttps://en.bitcoin.it/w/index.php?title=Gocoin&diff=64661Gocoin2017-12-28T21:56:17Z<p>Tonikt: /* Node-less mode */</p>
<hr />
<div>An open-source Bitcoin solution written in Go language (golang).<br />
It can be built for every platform that has a working Go compiler.<br />
It uses a proprietary license, though is free to use for non-commercial purposes.<br />
<br />
==Architecture==<br />
<br />
Gocoin's architecture is quite different from the reference implementation (of the Satoshi client).<br />
<br />
===Libraries===<br />
<br />
====btc / chain / script ====<br />
The core of the software is a library that essentially provides the blockchain protocol parser. That includes script parsing, ECDSA signature verification, but also things like address encoding, parsing of canonical signatures or extracting hashes that need to be signed for specific inputs of a given transaction.<br />
<br />
It is a relatively big library, that contains many useful bitcoin function.<br />
<br />
Inside the package, there is also a blocks persistent storage database (blockdb.go) - it is just a simple plain storage (that can only grow), with an index. It uses snappy compression, allowing to save about 30% of the disk space.<br />
<br />
====utxo====<br />
The core library interfaces directly with a UTXO database backed.<br />
For this purpose Gocoin uses its own database engine, that has been designed to deal with the specific characteristics of bitcoin's UTXO database.<br />
<br />
====secp256k1====<br />
To speed up the Elliptic Curve operations [https://github.com/bitcoin/secp256k1 the secp256k1 library by sipa] has been ported to Go.<br />
<br />
===Online client===<br />
The online client is a kind of a server software (or a peer-to-peer node) that is meant to be running all the time.<br />
<br />
It handles the network related communication, feeds the core lib with new incoming blockchain data, monitors balances on the wallets' addresses, manages transaction memory pool and the peers database. It also provides an interactive user interface.<br />
<br />
===Offline wallet===<br />
The wallet application is responsible for creating private keys (from a seed password) and for signing transactions with them.<br />
It can also sign text messages with private keys and decode raw transactions.<br />
<br />
Unlike the client, the wallet is not an app that is meant te be running continuously. <br />
A user runs it with the requested task - the wallet does the job and exits (back to the command prompt).<br />
<br />
===Blockchain downloader===<br />
For optimized initial blockchain download, Gocoin has a dedicated application called '''downloader'''.<br />
<br />
Among other optimizations, the downloader allows a user to skip verification of all the blocks up to a certain one that he defines as trusted. This can speed up the bootstrap process significantly (e.g. from days to hours).<br />
<br />
After it finishes downloading of all the blocks, it will exit automatically. In that moment the client should be started and it will keep up with all the new blocks, that will appear in the network.<br />
<br />
===Other tools===<br />
There is also a set of more and less useful tools (''github.com/piotrnar/gocoin/tools'') that are an integral part of the Gocoin bitcoin software.<br />
<br />
For instance '''btcversig''' can verify a validity of a bitcoin signature - it is the substitute of the reference client's '''verifymessage''' RPC-API.<br />
<br />
The tool '''type2determ''' can, at the other hand, calculate Type-2 deterministic addresses, without a need to access the wallet (the private keys).<br />
<br />
<br />
==Features==<br />
<br />
Gocoin has a several unique features, that distinguish it from the original bitcoin client.<br />
===Node / Client===<br />
* All the unspent outputs are kept in system memory.<br />
* A current balances of any P2PKH, P2SH or P2WPKH address is kept in memory for a quick access.<br />
* Can be monitored and controlled through a web interface (from a web browser).<br />
* Works with its own implementation of a cold storage wallet.<br />
* Web interface allows a user to create raw transactions from specific inputs ([[Coin Control]]), as well as multisig transactions ([[P2SH]])<br />
* The blocks are stored on the disk in a compressed form (using [https://code.google.com/p/snappy/ snappy] compression) which saves ~20% of space. They can also be purged (entirely or partially) from the disk.<br />
* Up till version '''1.6.4''' it supported monitoring and fetching balance of stealth addresses (the ones implemented in [[Dark Wallet]])<br />
* From version 1.9.4 onward, both the wallet and the client, support native segwit addresses (P2WPKH encoded as bech32)<br />
<br />
===Wallet===<br />
* For security reasons, it is supposed to be used with a PC that has never been (and will never be) connected to a network.<br />
* The wallet is deterministic and a seed-password based. As long as you can remember the password, there is no need for any backups.<br />
* Additionally it can import private keys from an existing bitcoin wallet (must be in [[Private key#Base 58 Wallet Import format | Base 58 Wallet Import format]] format).<br />
* Has very low hardware requirements. Can be run on i.e. Raspberry Pi<br />
* Can generate [https://bitcointalk.org/index.php?topic=19137.0 Type-2] deterministic keys/addresses<br />
* Supports (partial) signing of [[P2SH]] multisig transactions (the ones that use [[Script#Crypto | OP_CHECKMULTISIG opcode]]).<br />
* Supports spending to stealth addresses as implemented in Dark Wallet<br />
<br />
===Node-less mode===<br />
It is possible to use Gocoin's wallet, without a need to have a running client node. This may come handy since the node requires quite an advanced hardware and a large amount of time for the initial bootstrap.<br />
<br />
In such a case the required balance files are fetched with a tool called '''balio''', from popular block explorers.<br />
<br />
==Requirements==<br />
===Client===<br />
Requires 64-bit platform and at least 8GB of system memory.<br />
<br />
The file system that stores the blockchain data must be able to handle files larger than 4GB.<br />
<br />
===Wallet===<br />
The wallet app has very little hardware requirements. As long as you can build it for a specific architecture, it should work there.<br />
<br />
Gocoin wallet has been even used on Raspberry Pi model A.<br />
<br />
For security reasons it is strongly recommended to run the wallet on an encrypted file system, with an encrypted swap file.<br />
<br />
==Limitations==<br />
* No GUI, though the online node has web interface which acts like a GUI<br />
* No IPv6<br />
* No UPnP<br />
* No support for non-confirmed transactions (they are invisible in the balance)<br />
* No support for [[Protocol_specification#filterload, filteradd, filterclear, merkleblock | bloom filters]] protocol ([[BIP 0037]]) and the [[Protocol_specification#mempool | mempool]] command<br />
* No routing of [[Protocol_specification#alert | alert]] messages<br />
* No support for multisig stealth addresses (yet)<br />
<br />
==History==<br />
<br />
Gocoin was written by a single person for a private purposes.<br />
<br />
The software's first public release was announced in May 2013 on Bitcointalk forum.<ref>https://bitcointalk.org/index.php?topic=199306.0</ref><br />
Ever since then, the software has been actively maintained and further developed, being armed with new features, further optimized and cleaned up from issues.<br />
<br />
It happened twice that the client wasn't able to catch up with the blockchain, because of the implementation difference of the chain parsing protocol that was causing it to reject a block (transaction) that the reference implementation would accept. In both cases the issue was fixed within single days. The fist case happened in July 2013 and the fix was introduced in version 0.5.7. The second time was in March 2014 - the fix came with release 0.9.3.<br />
<br />
==External Links==<br />
<br />
* [http://gocoin.pl Homepage]<br />
* [https://github.com/piotrnar/gocoin Github repo]<br />
* [https://bitcointalk.org/index.php?topic=199306.0 Bitcointalk forum topic]<br />
<br />
==References==<br />
<references /><br />
<br />
[[Category:Software]]<br />
[[Category:Clients]]<br />
[[Category:Open Source]]<br />
[[Category:Wallets]]<br />
[[Category:Google Go]]</div>Tonikthttps://en.bitcoin.it/w/index.php?title=Gocoin&diff=64660Gocoin2017-12-28T21:55:47Z<p>Tonikt: /* Node-less mode */</p>
<hr />
<div>An open-source Bitcoin solution written in Go language (golang).<br />
It can be built for every platform that has a working Go compiler.<br />
It uses a proprietary license, though is free to use for non-commercial purposes.<br />
<br />
==Architecture==<br />
<br />
Gocoin's architecture is quite different from the reference implementation (of the Satoshi client).<br />
<br />
===Libraries===<br />
<br />
====btc / chain / script ====<br />
The core of the software is a library that essentially provides the blockchain protocol parser. That includes script parsing, ECDSA signature verification, but also things like address encoding, parsing of canonical signatures or extracting hashes that need to be signed for specific inputs of a given transaction.<br />
<br />
It is a relatively big library, that contains many useful bitcoin function.<br />
<br />
Inside the package, there is also a blocks persistent storage database (blockdb.go) - it is just a simple plain storage (that can only grow), with an index. It uses snappy compression, allowing to save about 30% of the disk space.<br />
<br />
====utxo====<br />
The core library interfaces directly with a UTXO database backed.<br />
For this purpose Gocoin uses its own database engine, that has been designed to deal with the specific characteristics of bitcoin's UTXO database.<br />
<br />
====secp256k1====<br />
To speed up the Elliptic Curve operations [https://github.com/bitcoin/secp256k1 the secp256k1 library by sipa] has been ported to Go.<br />
<br />
===Online client===<br />
The online client is a kind of a server software (or a peer-to-peer node) that is meant to be running all the time.<br />
<br />
It handles the network related communication, feeds the core lib with new incoming blockchain data, monitors balances on the wallets' addresses, manages transaction memory pool and the peers database. It also provides an interactive user interface.<br />
<br />
===Offline wallet===<br />
The wallet application is responsible for creating private keys (from a seed password) and for signing transactions with them.<br />
It can also sign text messages with private keys and decode raw transactions.<br />
<br />
Unlike the client, the wallet is not an app that is meant te be running continuously. <br />
A user runs it with the requested task - the wallet does the job and exits (back to the command prompt).<br />
<br />
===Blockchain downloader===<br />
For optimized initial blockchain download, Gocoin has a dedicated application called '''downloader'''.<br />
<br />
Among other optimizations, the downloader allows a user to skip verification of all the blocks up to a certain one that he defines as trusted. This can speed up the bootstrap process significantly (e.g. from days to hours).<br />
<br />
After it finishes downloading of all the blocks, it will exit automatically. In that moment the client should be started and it will keep up with all the new blocks, that will appear in the network.<br />
<br />
===Other tools===<br />
There is also a set of more and less useful tools (''github.com/piotrnar/gocoin/tools'') that are an integral part of the Gocoin bitcoin software.<br />
<br />
For instance '''btcversig''' can verify a validity of a bitcoin signature - it is the substitute of the reference client's '''verifymessage''' RPC-API.<br />
<br />
The tool '''type2determ''' can, at the other hand, calculate Type-2 deterministic addresses, without a need to access the wallet (the private keys).<br />
<br />
<br />
==Features==<br />
<br />
Gocoin has a several unique features, that distinguish it from the original bitcoin client.<br />
===Node / Client===<br />
* All the unspent outputs are kept in system memory.<br />
* A current balances of any P2PKH, P2SH or P2WPKH address is kept in memory for a quick access.<br />
* Can be monitored and controlled through a web interface (from a web browser).<br />
* Works with its own implementation of a cold storage wallet.<br />
* Web interface allows a user to create raw transactions from specific inputs ([[Coin Control]]), as well as multisig transactions ([[P2SH]])<br />
* The blocks are stored on the disk in a compressed form (using [https://code.google.com/p/snappy/ snappy] compression) which saves ~20% of space. They can also be purged (entirely or partially) from the disk.<br />
* Up till version '''1.6.4''' it supported monitoring and fetching balance of stealth addresses (the ones implemented in [[Dark Wallet]])<br />
* From version 1.9.4 onward, both the wallet and the client, support native segwit addresses (P2WPKH encoded as bech32)<br />
<br />
===Wallet===<br />
* For security reasons, it is supposed to be used with a PC that has never been (and will never be) connected to a network.<br />
* The wallet is deterministic and a seed-password based. As long as you can remember the password, there is no need for any backups.<br />
* Additionally it can import private keys from an existing bitcoin wallet (must be in [[Private key#Base 58 Wallet Import format | Base 58 Wallet Import format]] format).<br />
* Has very low hardware requirements. Can be run on i.e. Raspberry Pi<br />
* Can generate [https://bitcointalk.org/index.php?topic=19137.0 Type-2] deterministic keys/addresses<br />
* Supports (partial) signing of [[P2SH]] multisig transactions (the ones that use [[Script#Crypto | OP_CHECKMULTISIG opcode]]).<br />
* Supports spending to stealth addresses as implemented in Dark Wallet<br />
<br />
===Node-less mode===<br />
It is possible to use Gocoin's wallet, without a need to have a running client node. This may come handy since the node requires quite an advanced hardware and a large amount of time for the initial bootstrap.<br />
<br />
In such a case the required balance files are fetched with a tool called '''balio''', from popular block explorers.<br />
<br />
''Note: using this tool you will not be able to monitor balance on your stealth addresses.''<br />
<br />
==Requirements==<br />
===Client===<br />
Requires 64-bit platform and at least 8GB of system memory.<br />
<br />
The file system that stores the blockchain data must be able to handle files larger than 4GB.<br />
<br />
===Wallet===<br />
The wallet app has very little hardware requirements. As long as you can build it for a specific architecture, it should work there.<br />
<br />
Gocoin wallet has been even used on Raspberry Pi model A.<br />
<br />
For security reasons it is strongly recommended to run the wallet on an encrypted file system, with an encrypted swap file.<br />
<br />
==Limitations==<br />
* No GUI, though the online node has web interface which acts like a GUI<br />
* No IPv6<br />
* No UPnP<br />
* No support for non-confirmed transactions (they are invisible in the balance)<br />
* No support for [[Protocol_specification#filterload, filteradd, filterclear, merkleblock | bloom filters]] protocol ([[BIP 0037]]) and the [[Protocol_specification#mempool | mempool]] command<br />
* No routing of [[Protocol_specification#alert | alert]] messages<br />
* No support for multisig stealth addresses (yet)<br />
<br />
==History==<br />
<br />
Gocoin was written by a single person for a private purposes.<br />
<br />
The software's first public release was announced in May 2013 on Bitcointalk forum.<ref>https://bitcointalk.org/index.php?topic=199306.0</ref><br />
Ever since then, the software has been actively maintained and further developed, being armed with new features, further optimized and cleaned up from issues.<br />
<br />
It happened twice that the client wasn't able to catch up with the blockchain, because of the implementation difference of the chain parsing protocol that was causing it to reject a block (transaction) that the reference implementation would accept. In both cases the issue was fixed within single days. The fist case happened in July 2013 and the fix was introduced in version 0.5.7. The second time was in March 2014 - the fix came with release 0.9.3.<br />
<br />
==External Links==<br />
<br />
* [http://gocoin.pl Homepage]<br />
* [https://github.com/piotrnar/gocoin Github repo]<br />
* [https://bitcointalk.org/index.php?topic=199306.0 Bitcointalk forum topic]<br />
<br />
==References==<br />
<references /><br />
<br />
[[Category:Software]]<br />
[[Category:Clients]]<br />
[[Category:Open Source]]<br />
[[Category:Wallets]]<br />
[[Category:Google Go]]</div>Tonikthttps://en.bitcoin.it/w/index.php?title=Gocoin&diff=64659Gocoin2017-12-28T21:52:32Z<p>Tonikt: /* Node / Client */</p>
<hr />
<div>An open-source Bitcoin solution written in Go language (golang).<br />
It can be built for every platform that has a working Go compiler.<br />
It uses a proprietary license, though is free to use for non-commercial purposes.<br />
<br />
==Architecture==<br />
<br />
Gocoin's architecture is quite different from the reference implementation (of the Satoshi client).<br />
<br />
===Libraries===<br />
<br />
====btc / chain / script ====<br />
The core of the software is a library that essentially provides the blockchain protocol parser. That includes script parsing, ECDSA signature verification, but also things like address encoding, parsing of canonical signatures or extracting hashes that need to be signed for specific inputs of a given transaction.<br />
<br />
It is a relatively big library, that contains many useful bitcoin function.<br />
<br />
Inside the package, there is also a blocks persistent storage database (blockdb.go) - it is just a simple plain storage (that can only grow), with an index. It uses snappy compression, allowing to save about 30% of the disk space.<br />
<br />
====utxo====<br />
The core library interfaces directly with a UTXO database backed.<br />
For this purpose Gocoin uses its own database engine, that has been designed to deal with the specific characteristics of bitcoin's UTXO database.<br />
<br />
====secp256k1====<br />
To speed up the Elliptic Curve operations [https://github.com/bitcoin/secp256k1 the secp256k1 library by sipa] has been ported to Go.<br />
<br />
===Online client===<br />
The online client is a kind of a server software (or a peer-to-peer node) that is meant to be running all the time.<br />
<br />
It handles the network related communication, feeds the core lib with new incoming blockchain data, monitors balances on the wallets' addresses, manages transaction memory pool and the peers database. It also provides an interactive user interface.<br />
<br />
===Offline wallet===<br />
The wallet application is responsible for creating private keys (from a seed password) and for signing transactions with them.<br />
It can also sign text messages with private keys and decode raw transactions.<br />
<br />
Unlike the client, the wallet is not an app that is meant te be running continuously. <br />
A user runs it with the requested task - the wallet does the job and exits (back to the command prompt).<br />
<br />
===Blockchain downloader===<br />
For optimized initial blockchain download, Gocoin has a dedicated application called '''downloader'''.<br />
<br />
Among other optimizations, the downloader allows a user to skip verification of all the blocks up to a certain one that he defines as trusted. This can speed up the bootstrap process significantly (e.g. from days to hours).<br />
<br />
After it finishes downloading of all the blocks, it will exit automatically. In that moment the client should be started and it will keep up with all the new blocks, that will appear in the network.<br />
<br />
===Other tools===<br />
There is also a set of more and less useful tools (''github.com/piotrnar/gocoin/tools'') that are an integral part of the Gocoin bitcoin software.<br />
<br />
For instance '''btcversig''' can verify a validity of a bitcoin signature - it is the substitute of the reference client's '''verifymessage''' RPC-API.<br />
<br />
The tool '''type2determ''' can, at the other hand, calculate Type-2 deterministic addresses, without a need to access the wallet (the private keys).<br />
<br />
<br />
==Features==<br />
<br />
Gocoin has a several unique features, that distinguish it from the original bitcoin client.<br />
===Node / Client===<br />
* All the unspent outputs are kept in system memory.<br />
* A current balances of any P2PKH, P2SH or P2WPKH address is kept in memory for a quick access.<br />
* Can be monitored and controlled through a web interface (from a web browser).<br />
* Works with its own implementation of a cold storage wallet.<br />
* Web interface allows a user to create raw transactions from specific inputs ([[Coin Control]]), as well as multisig transactions ([[P2SH]])<br />
* The blocks are stored on the disk in a compressed form (using [https://code.google.com/p/snappy/ snappy] compression) which saves ~20% of space. They can also be purged (entirely or partially) from the disk.<br />
* Up till version '''1.6.4''' it supported monitoring and fetching balance of stealth addresses (the ones implemented in [[Dark Wallet]])<br />
* From version 1.9.4 onward, both the wallet and the client, support native segwit addresses (P2WPKH encoded as bech32)<br />
<br />
===Wallet===<br />
* For security reasons, it is supposed to be used with a PC that has never been (and will never be) connected to a network.<br />
* The wallet is deterministic and a seed-password based. As long as you can remember the password, there is no need for any backups.<br />
* Additionally it can import private keys from an existing bitcoin wallet (must be in [[Private key#Base 58 Wallet Import format | Base 58 Wallet Import format]] format).<br />
* Has very low hardware requirements. Can be run on i.e. Raspberry Pi<br />
* Can generate [https://bitcointalk.org/index.php?topic=19137.0 Type-2] deterministic keys/addresses<br />
* Supports (partial) signing of [[P2SH]] multisig transactions (the ones that use [[Script#Crypto | OP_CHECKMULTISIG opcode]]).<br />
* Supports spending to stealth addresses as implemented in Dark Wallet<br />
<br />
===Node-less mode===<br />
It is possible to use Gocoin's wallet, without a need to have a running client node, which may come handy since the node requires quite a decent hardware and the block chain takes a lot of time for the initial download.<br />
<br />
In such a case the required balance files are fetched with a tool called '''balio''', from a popular block explorer '''blockr.io'''<br />
<br />
''Note: using this tool you will not be able to monitor balance on your stealth addresses.''<br />
<br />
==Requirements==<br />
===Client===<br />
Requires 64-bit platform and at least 8GB of system memory.<br />
<br />
The file system that stores the blockchain data must be able to handle files larger than 4GB.<br />
<br />
===Wallet===<br />
The wallet app has very little hardware requirements. As long as you can build it for a specific architecture, it should work there.<br />
<br />
Gocoin wallet has been even used on Raspberry Pi model A.<br />
<br />
For security reasons it is strongly recommended to run the wallet on an encrypted file system, with an encrypted swap file.<br />
<br />
==Limitations==<br />
* No GUI, though the online node has web interface which acts like a GUI<br />
* No IPv6<br />
* No UPnP<br />
* No support for non-confirmed transactions (they are invisible in the balance)<br />
* No support for [[Protocol_specification#filterload, filteradd, filterclear, merkleblock | bloom filters]] protocol ([[BIP 0037]]) and the [[Protocol_specification#mempool | mempool]] command<br />
* No routing of [[Protocol_specification#alert | alert]] messages<br />
* No support for multisig stealth addresses (yet)<br />
<br />
==History==<br />
<br />
Gocoin was written by a single person for a private purposes.<br />
<br />
The software's first public release was announced in May 2013 on Bitcointalk forum.<ref>https://bitcointalk.org/index.php?topic=199306.0</ref><br />
Ever since then, the software has been actively maintained and further developed, being armed with new features, further optimized and cleaned up from issues.<br />
<br />
It happened twice that the client wasn't able to catch up with the blockchain, because of the implementation difference of the chain parsing protocol that was causing it to reject a block (transaction) that the reference implementation would accept. In both cases the issue was fixed within single days. The fist case happened in July 2013 and the fix was introduced in version 0.5.7. The second time was in March 2014 - the fix came with release 0.9.3.<br />
<br />
==External Links==<br />
<br />
* [http://gocoin.pl Homepage]<br />
* [https://github.com/piotrnar/gocoin Github repo]<br />
* [https://bitcointalk.org/index.php?topic=199306.0 Bitcointalk forum topic]<br />
<br />
==References==<br />
<references /><br />
<br />
[[Category:Software]]<br />
[[Category:Clients]]<br />
[[Category:Open Source]]<br />
[[Category:Wallets]]<br />
[[Category:Google Go]]</div>Tonikthttps://en.bitcoin.it/w/index.php?title=Gocoin&diff=64658Gocoin2017-12-28T21:45:27Z<p>Tonikt: /* qdb */</p>
<hr />
<div>An open-source Bitcoin solution written in Go language (golang).<br />
It can be built for every platform that has a working Go compiler.<br />
It uses a proprietary license, though is free to use for non-commercial purposes.<br />
<br />
==Architecture==<br />
<br />
Gocoin's architecture is quite different from the reference implementation (of the Satoshi client).<br />
<br />
===Libraries===<br />
<br />
====btc / chain / script ====<br />
The core of the software is a library that essentially provides the blockchain protocol parser. That includes script parsing, ECDSA signature verification, but also things like address encoding, parsing of canonical signatures or extracting hashes that need to be signed for specific inputs of a given transaction.<br />
<br />
It is a relatively big library, that contains many useful bitcoin function.<br />
<br />
Inside the package, there is also a blocks persistent storage database (blockdb.go) - it is just a simple plain storage (that can only grow), with an index. It uses snappy compression, allowing to save about 30% of the disk space.<br />
<br />
====utxo====<br />
The core library interfaces directly with a UTXO database backed.<br />
For this purpose Gocoin uses its own database engine, that has been designed to deal with the specific characteristics of bitcoin's UTXO database.<br />
<br />
====secp256k1====<br />
To speed up the Elliptic Curve operations [https://github.com/bitcoin/secp256k1 the secp256k1 library by sipa] has been ported to Go.<br />
<br />
===Online client===<br />
The online client is a kind of a server software (or a peer-to-peer node) that is meant to be running all the time.<br />
<br />
It handles the network related communication, feeds the core lib with new incoming blockchain data, monitors balances on the wallets' addresses, manages transaction memory pool and the peers database. It also provides an interactive user interface.<br />
<br />
===Offline wallet===<br />
The wallet application is responsible for creating private keys (from a seed password) and for signing transactions with them.<br />
It can also sign text messages with private keys and decode raw transactions.<br />
<br />
Unlike the client, the wallet is not an app that is meant te be running continuously. <br />
A user runs it with the requested task - the wallet does the job and exits (back to the command prompt).<br />
<br />
===Blockchain downloader===<br />
For optimized initial blockchain download, Gocoin has a dedicated application called '''downloader'''.<br />
<br />
Among other optimizations, the downloader allows a user to skip verification of all the blocks up to a certain one that he defines as trusted. This can speed up the bootstrap process significantly (e.g. from days to hours).<br />
<br />
After it finishes downloading of all the blocks, it will exit automatically. In that moment the client should be started and it will keep up with all the new blocks, that will appear in the network.<br />
<br />
===Other tools===<br />
There is also a set of more and less useful tools (''github.com/piotrnar/gocoin/tools'') that are an integral part of the Gocoin bitcoin software.<br />
<br />
For instance '''btcversig''' can verify a validity of a bitcoin signature - it is the substitute of the reference client's '''verifymessage''' RPC-API.<br />
<br />
The tool '''type2determ''' can, at the other hand, calculate Type-2 deterministic addresses, without a need to access the wallet (the private keys).<br />
<br />
<br />
==Features==<br />
<br />
Gocoin has a several unique features, that distinguish it from the original bitcoin client.<br />
===Node / Client===<br />
* All the unspent outputs are kept in memory, which makes switching between different wallets, as well as checking a balance of any address, relatively fast (few seconds max).<br />
* Allows a user to limit the upload and download network bandwidth used by the client.<br />
* Can be monitored and controlled through a web interface (from a web browser).<br />
* Works with its own implementation of a cold storage wallet.<br />
* Web interface allows a user to create raw transactions from specific inputs ([[Coin Control]]), as well as multisig transactions ([[P2SH]])<br />
* The blocks are stored on the disk in a compressed form (using [https://code.google.com/p/snappy/ snappy] compression) which saves 20-30% of space.<br />
* Up till version '''1.6.4''' it supported monitoring and fetching balance of own stealth addresses (the ones implemented in [[Dark Wallet]])<br />
<br />
===Wallet===<br />
* For security reasons, it is supposed to be used with a PC that has never been (and will never be) connected to a network.<br />
* The wallet is deterministic and a seed-password based. As long as you can remember the password, there is no need for any backups.<br />
* Additionally it can import private keys from an existing bitcoin wallet (must be in [[Private key#Base 58 Wallet Import format | Base 58 Wallet Import format]] format).<br />
* Has very low hardware requirements. Can be run on i.e. Raspberry Pi<br />
* Can generate [https://bitcointalk.org/index.php?topic=19137.0 Type-2] deterministic keys/addresses<br />
* Supports (partial) signing of [[P2SH]] multisig transactions (the ones that use [[Script#Crypto | OP_CHECKMULTISIG opcode]]).<br />
* Supports spending to stealth addresses as implemented in Dark Wallet<br />
<br />
===Node-less mode===<br />
It is possible to use Gocoin's wallet, without a need to have a running client node, which may come handy since the node requires quite a decent hardware and the block chain takes a lot of time for the initial download.<br />
<br />
In such a case the required balance files are fetched with a tool called '''balio''', from a popular block explorer '''blockr.io'''<br />
<br />
''Note: using this tool you will not be able to monitor balance on your stealth addresses.''<br />
<br />
==Requirements==<br />
===Client===<br />
Requires 64-bit platform and at least 8GB of system memory.<br />
<br />
The file system that stores the blockchain data must be able to handle files larger than 4GB.<br />
<br />
===Wallet===<br />
The wallet app has very little hardware requirements. As long as you can build it for a specific architecture, it should work there.<br />
<br />
Gocoin wallet has been even used on Raspberry Pi model A.<br />
<br />
For security reasons it is strongly recommended to run the wallet on an encrypted file system, with an encrypted swap file.<br />
<br />
==Limitations==<br />
* No GUI, though the online node has web interface which acts like a GUI<br />
* No IPv6<br />
* No UPnP<br />
* No support for non-confirmed transactions (they are invisible in the balance)<br />
* No support for [[Protocol_specification#filterload, filteradd, filterclear, merkleblock | bloom filters]] protocol ([[BIP 0037]]) and the [[Protocol_specification#mempool | mempool]] command<br />
* No routing of [[Protocol_specification#alert | alert]] messages<br />
* No support for multisig stealth addresses (yet)<br />
<br />
==History==<br />
<br />
Gocoin was written by a single person for a private purposes.<br />
<br />
The software's first public release was announced in May 2013 on Bitcointalk forum.<ref>https://bitcointalk.org/index.php?topic=199306.0</ref><br />
Ever since then, the software has been actively maintained and further developed, being armed with new features, further optimized and cleaned up from issues.<br />
<br />
It happened twice that the client wasn't able to catch up with the blockchain, because of the implementation difference of the chain parsing protocol that was causing it to reject a block (transaction) that the reference implementation would accept. In both cases the issue was fixed within single days. The fist case happened in July 2013 and the fix was introduced in version 0.5.7. The second time was in March 2014 - the fix came with release 0.9.3.<br />
<br />
==External Links==<br />
<br />
* [http://gocoin.pl Homepage]<br />
* [https://github.com/piotrnar/gocoin Github repo]<br />
* [https://bitcointalk.org/index.php?topic=199306.0 Bitcointalk forum topic]<br />
<br />
==References==<br />
<references /><br />
<br />
[[Category:Software]]<br />
[[Category:Clients]]<br />
[[Category:Open Source]]<br />
[[Category:Wallets]]<br />
[[Category:Google Go]]</div>Tonikthttps://en.bitcoin.it/w/index.php?title=Protocol_documentation&diff=63714Protocol documentation2017-07-26T14:08:42Z<p>Tonikt: Undo revision 63713 by Tonikt (talk)</p>
<hr />
<div>This page ''describes'' the behavior of the [[Original Bitcoin client|reference client]]. The Bitcoin protocol is specified by the behavior of the reference client, not by this page. In particular, while this page is quite complete in describing the network protocol, it does not attempt to list all of the rules for block or transaction validity.<br />
<br />
Type names used in this documentation are from the C99 standard.<br />
<br />
For protocol used in mining, see [[getblocktemplate]].<br />
<br />
==Common standards==<br />
<br />
=== Hashes ===<br />
<br />
Usually, when a hash is computed within bitcoin, it is computed twice. Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-256] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when a shorter hash is desirable (for example when creating a bitcoin address).<br />
<br />
Example of double-SHA-256 encoding of string "hello":<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round of sha-256)<br />
9595c9df90075148eb06860365df33584b75bff782a510c6cd4883a419833d50 (second round of sha-256)<br />
<br />
For bitcoin addresses (RIPEMD-160) this would give:<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round is sha-256)<br />
b6a9c8c230722b7c748331a8b450f05566dc7d0f (with ripemd-160)<br />
<br />
=== Merkle Trees ===<br />
<br />
Merkle trees are binary trees of hashes. Merkle trees in bitcoin use a '''double''' SHA-256, the SHA-256 hash of the SHA-256 hash of something.<br />
<br />
If, when forming a row in the tree (other than the root of the tree), it would have an odd number of elements, the final double-hash is duplicated to ensure that the row has an even number of hashes.<br />
<br />
First form the bottom row of the tree with the ordered double-SHA-256 hashes of the byte streams of the transactions in the block.<br />
<br />
Then the row above it consists of half that number of hashes. Each entry is the double-SHA-256 of the 64-byte concatenation of the corresponding two hashes below it in the tree.<br />
<br />
This procedure repeats recursively until we reach a row consisting of just a single double-hash. This is the '''Merkle root''' of the tree.<br />
<br />
For example, imagine a block with three transactions ''a'', ''b'' and ''c''. The Merkle tree is: <br />
<br />
d1 = dhash(a)<br />
d2 = dhash(b)<br />
d3 = dhash(c)<br />
d4 = dhash(c) # a, b, c are 3. that's an odd number, so we take the c twice<br />
<br />
d5 = dhash(d1 concat d2)<br />
d6 = dhash(d3 concat d4)<br />
<br />
d7 = dhash(d5 concat d6)<br />
<br />
where<br />
<br />
dhash(a) = sha256(sha256(a))<br />
<br />
''d7'' is the Merkle root of the 3 transactions in this block.<br />
<br />
Note: Hashes in Merkle Tree displayed in the [[Block Explorer]] are of little-endian notation. For some implementations and [http://www.fileformat.info/tool/hash.htm calculations], the bits need to be reversed before they are hashed, and again after the hashing operation.<br />
<br />
=== Signatures ===<br />
<br />
Bitcoin uses [http://en.wikipedia.org/wiki/Elliptic_curve_cryptography Elliptic Curve] [http://en.wikipedia.org/wiki/Digital_Signature_Algorithm Digital Signature Algorithm] ([http://en.wikipedia.org/wiki/Elliptic_Curve_DSA ECDSA]) to sign transactions. <br />
<br />
For [[ECDSA]] the secp256k1 curve from http://www.secg.org/sec2-v2.pdf is used.<br />
<br />
Public keys (in scripts) are given as 04 <x> <y> where ''x'' and ''y'' are 32 byte big-endian integers representing the coordinates of a point on the curve or in compressed form given as <sign> <x> where <sign> is 0x02 if ''y'' is even and 0x03 if ''y'' is odd.<br />
<br />
Signatures use [http://en.wikipedia.org/wiki/Distinguished_Encoding_Rules DER encoding] to pack the ''r'' and ''s'' components into a single byte stream (this is also what OpenSSL produces by default).<br />
<br />
=== Transaction Verification ===<br />
Transactions are cryptographically signed records that reassign ownership of Bitcoins to new addresses. Transactions have ''inputs'' - records which reference the funds from other previous transactions - and ''outputs'' - records which determine the new owner of the transferred Bitcoins, and which will be referenced as inputs in future transactions as those funds are respent.<br />
<br />
Each ''input'' must have a cryptographic digital signature that unlocks the funds from the prior transaction. Only the person possessing the appropriate [[private key]] is able to create a satisfactory signature; this in effect ensures that funds can only be spent by their owners.<br />
<br />
Each ''output'' determines which Bitcoin address (or other criteria, see [[Script]]) is the recipient of the funds.<br />
<br />
In a transaction, the sum of all inputs must be equal to or greater than the sum of all outputs. If the inputs exceed the outputs, the difference is considered a [[transaction fee]], and is redeemable by whoever first includes the transaction into the block chain.<br />
<br />
A special kind of transaction, called a [[coinbase transaction]], has no inputs. It is created by [[miners]], and there is one coinbase transaction per block. Because each block comes with a reward of newly created Bitcoins (e.g. 50 BTC for the first 210,000 blocks), the first transaction of a block is, with few exceptions, the transaction that grants those coins to their recipient (the miner). In addition to the newly created Bitcoins, the coinbase transaction is also used for assigning the recipient of any transaction fees that were paid within the other transactions being included in the same block. The coinbase transaction can assign the entire reward to a single Bitcoin address, or split it in portions among multiple addresses, just like any other transaction. Coinbase transactions always contain outputs totalling the sum of the block reward plus all transaction fees collected from the other transactions in the same block.<br />
<br />
The [[coinbase transaction]] in block zero cannot be spent. This is due to a quirk of the reference client implementation that would open the potential for a block chain fork if some nodes accepted the spend and others did not<ref>[http://bitcointalk.org/index.php?topic=119645.msg1288552#msg1288552 Block 0 Network Fork]</ref>.<br />
<br />
Most Bitcoin outputs encumber the newly transferred coins with a single ECDSA private key. The actual record saved with inputs and outputs isn't necessarily a key, but a ''script''. Bitcoin uses an interpreted scripting system to determine whether an output's criteria have been satisfied, with which more complex operations are possible, such as outputs that require two ECDSA signatures, or two-of-three-signature schemes. An output that references a single Bitcoin address is a ''typical'' output; an output actually contains this information in the form of a script that requires a single ECDSA signature (see [[OP_CHECKSIG]]). The output script specifies what must be provided to unlock the funds later, and when the time comes in the future to spend the transaction in another input, that input must provide all of the thing(s) that satisfy the requirements defined by the original output script.<br />
<br />
=== Addresses ===<br />
<br />
A bitcoin address is in fact the hash of a ECDSA public key, computed this way:<br />
<br />
Version = 1 byte of 0 (zero); on the test network, this is 1 byte of 111<br />
Key hash = Version concatenated with RIPEMD-160(SHA-256(public key))<br />
Checksum = 1st 4 bytes of SHA-256(SHA-256(Key hash))<br />
Bitcoin Address = Base58Encode(Key hash concatenated with Checksum)<br />
<br />
The Base58 encoding used is home made, and has some differences. Especially, leading zeroes are kept as single zeroes when conversion happens.<br />
<br />
== Common structures ==<br />
<br />
Almost all integers are encoded in little endian. Only IP or port number are encoded big endian.<br />
<br />
=== Message structure ===<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown<br />
|-<br />
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| 4 || length || uint32_t || Length of payload in number of bytes<br />
|-<br />
| 4 || checksum || uint32_t || First 4 bytes of sha256(sha256(payload))<br />
|-<br />
| ? || payload || uchar[] || The actual data<br />
|}<br />
<br />
<br />
Known magic values:<br />
<br />
{|class="wikitable"<br />
! Network !! Magic value !! Sent over wire as<br />
|-<br />
| main || 0xD9B4BEF9 || F9 BE B4 D9<br />
|-<br />
| testnet || 0xDAB5BFFA || FA BF B5 DA<br />
|-<br />
| testnet3 || 0x0709110B || 0B 11 09 07<br />
|-<br />
| namecoin || 0xFEB4BEF9 || F9 BE B4 FE<br />
|}<br />
<br />
=== Variable length integer ===<br />
<br />
Integer can be encoded depending on the represented value to save space.<br />
Variable length integers always precede an array/vector of a type of data that may vary in length.<br />
Longer numbers are encoded in little endian.<br />
<br />
{|class="wikitable"<br />
! Value !! Storage length !! Format<br />
|-<br />
| < 0xFD || 1 || uint8_t<br />
|-<br />
| <= 0xFFFF || 3 || 0xFD followed by the length as uint16_t<br />
|-<br />
| <= 0xFFFF FFFF || 5 || 0xFE followed by the length as uint32_t<br />
|-<br />
| - || 9 || 0xFF followed by the length as uint64_t<br />
|}<br />
<br />
If you're reading the Satoshi client code (BitcoinQT) it refers to this encoding as a "CompactSize". Modern BitcoinQT also has the CVarInt class which implements an even more compact integer for the purpose of local storage (which is incompatible with "CompactSize" described here). CVarInt is not a part of the protocol.<br />
<br />
=== Variable length string ===<br />
<br />
Variable length string can be stored using a variable length integer followed by the string itself.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the string<br />
|-<br />
| ? || string || char[] || The string itself (can be empty)<br />
|}<br />
<br />
=== Network address ===<br />
<br />
When a network address is needed somewhere, this structure is used. Network addresses are not prefixed with a timestamp in the version message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || time || uint32 || the Time (version >= 31402). '''Not present in version message.'''<br />
|-<br />
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]<br />
|-<br />
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The original client only supported IPv4 and only read the last 4 bytes to get the IPv4 address. However, the IPv4 address is written into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]<br />
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).<br />
|-<br />
| 2 || port || uint16_t || port number, network byte order<br />
|}<br />
<br />
Hexdump example of Network address structure<br />
<br />
<pre><br />
0000 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0010 00 00 FF FF 0A 00 00 01 20 8D ........ .<br />
<br />
Network address:<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK: see services listed under version command)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv6: ::ffff:a00:1 or IPv4: 10.0.0.1<br />
20 8D - Port 8333<br />
</pre><br />
<br />
=== Inventory Vectors ===<br />
<br />
Inventory vectors are used for notifying other nodes about objects they have or data which is being requested.<br />
<br />
Inventory vectors consist of the following data format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || type || uint32_t || Identifies the object type linked to this inventory<br />
|-<br />
| 32 || hash || char[32] || Hash of the object<br />
|}<br />
<br />
<br />
The object type is currently defined as one of the following possibilities:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0 || ERROR || Any data of with this number may be ignored<br />
|-<br />
| 1 || MSG_TX || Hash is related to a transaction<br />
|-<br />
| 2 || MSG_BLOCK || Hash is related to a data block<br />
|-<br />
| 3 || MSG_FILTERED_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a merkleblock message rather than a block message; this only works if a bloom filter has been set.<br />
|-<br />
| 4 || MSG_CMPCT_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a cmpctblock message. See BIP 152 for more info.<br />
|}<br />
<br />
Other Data Type values are considered reserved for future implementations.<br />
<br />
=== Block Headers ===<br />
<br />
Block headers are sent in a headers packet in response to a getheaders message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Will overflow in 2106<ref>https://en.wikipedia.org/wiki/Unix_time#Notable_events_in_Unix_time</ref>)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 1 || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries, this value is always 0<br />
|}<br />
<br />
cf. [[Block hashing algorithm]]<br />
<br />
=== Differential encoding === <br />
Several uses of CompactSize below are "differentially encoded". For these, instead of using raw indexes, the number encoded is the difference between the current index and the previous index, minus one. For example, a first index of 0 implies a real index of 0, a second index of 0 thereafter refers to a real index of 1, etc.<br />
<br />
=== PrefilledTransaction ===<br />
<br />
A PrefilledTransaction structure is used in HeaderAndShortIDs to provide a list of a few transactions explicitly.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| index || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1, 3 bytes || Compact Size, differentially encoded since the last PrefilledTransaction in a list || The index into the block at which this transaction is<br />
|-<br />
| tx || Transaction || variable || As encoded in [[Protocol_documentation#tx|tx messages]] || The transaction which is in the block at index index.<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== HeaderAndShortIDs ===<br />
<br />
A HeaderAndShortIDs structure is used to relay a block header, the short transactions IDs used for matching already-available transactions, and a select few transactions which we expect a peer may be missing.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| header || Block header || 80 bytes || First 80 bytes of the block as defined by the encoding used by "block" messages || The header of the block being provided<br />
|-<br />
| nonce || uint64_t || 8 bytes || Little Endian || A nonce for use in short transaction ID calculations<br />
|-<br />
| shortids_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of short transaction IDs in shortids (ie block tx count - prefilledtxn_length)<br />
|-<br />
| shortids || List of 6-byte integers || 6*shortids_length bytes || Little Endian || The [[Protocol_documentation#Short_transaction_ID|short transaction IDs]] calculated from the transactions which were not provided explicitly in prefilledtxn<br />
|-<br />
| prefilledtxn_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of prefilled transactions in prefilledtxn (ie block tx count - shortids_length)<br />
|-<br />
| prefilledtxn || List of PrefilledTransactions || variable size*prefilledtxn_length || As defined by [[Protocol_documentation#PrefilledTransaction|PrefilledTransaction]] definition, above || Used to provide the coinbase transaction and a select few which we expect a peer may be missing<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== BlockTransactionsRequest ===<br />
<br />
A BlockTransactionsRequest structure is used to list transaction indexes in a block being requested.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| blockhash || Binary blob || 32 bytes || The output from a double-SHA256 of the block header, as used elsewhere || The blockhash of the block which the transactions being requested are in<br />
|-<br />
| indexes_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of transactions being requested<br />
|-<br />
| indexes || List of [[Protocol_documentation#Variable_length_integer|CompactSizes]] || 1 or 3 bytes*indexes_length || [[Protocol_documentation#Differential_encoding|Differentially encoded]] || The indexes of the transactions being requested in the block<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== BlockTransactions ===<br />
<br />
A BlockTransactions structure is used to provide some of the transactions in a block, as requested.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| blockhash || Binary blob || 32 bytes || The output from a double-SHA256 of the block header, as used elsewhere || The blockhash of the block which the transactions being provided are in<br />
|-<br />
| transactions_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of transactions provided<br />
|-<br />
| transactions || List of Transactions || variable || As encoded in [[Protocol_documentation#tx|tx messages]] || The transactions provided<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== Short transaction ID ===<br />
<br />
Short transaction IDs are used to represent a transaction without sending a full 256-bit hash. They are calculated by:<br />
<br />
# single-SHA256 hashing the block header with the nonce appended (in little-endian)<br />
# Running SipHash-2-4 with the input being the transaction ID and the keys (k0/k1) set to the first two little-endian 64-bit integers from the above hash, respectively.<br />
# Dropping the 2 most significant bytes from the SipHash output to make it 6 bytes.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
== Message types ==<br />
<br />
=== version ===<br />
<br />
When a node creates an outgoing connection, it will immediately [[Version Handshake|advertise]] its version. The remote node will respond with its version. No further communication is possible until both peers have exchanged their version.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Identifies protocol version being used by the node<br />
|-<br />
| 8 || services || uint64_t || bitfield of features to be enabled for this connection<br />
|-<br />
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds<br />
|-<br />
| 26 || addr_recv || [[#Network address|net_addr]] || The network address of the node receiving this message<br />
|-<br />
|colspan="4"| Fields below require version ≥ 106<br />
|-<br />
| 26 || addr_from || [[#Network address|net_addr]] || The network address of the node emitting this message<br />
|-<br />
| 8 || nonce || uint64_t || Node random nonce, randomly generated every time a version packet is sent. This nonce is used to detect connections to self.<br />
|-<br />
| ? || user_agent || [[#Variable length string|var_str]] || [https://github.com/bitcoin/bips/blob/master/bip-0014.mediawiki User Agent] (0x00 if string is 0 bytes long)<br />
|-<br />
| 4 || start_height || int32_t || The last block received by the emitting node<br />
|-<br />
|colspan="4"| Fields below require version ≥ 70001<br />
|-<br />
| 1 || relay || bool || Whether the remote peer should announce relayed transactions or not, see [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037]<br />
|}<br />
<br />
A "verack" packet shall be sent if the version packet was accepted.<br />
<br />
The following services are currently assigned:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 1 || NODE_NETWORK || This node can be asked for full blocks instead of just headers.<br />
|-<br />
| 2 || NODE_GETUTXO || See [https://github.com/bitcoin/bips/blob/master/bip-0064.mediawiki BIP 0064]<br />
|-<br />
| 4 || NODE_BLOOM || See [https://github.com/bitcoin/bips/blob/master/bip-0111.mediawiki BIP 0111]<br />
|}<br />
<br />
Hexdump example of version message (OBSOLETE EXAMPLE: This example lacks a checksum and user-agent):<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....<br />
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........<br />
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............<br />
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................<br />
0040 20 8D 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,<br />
0060 3A B4 57 13 00 55 81 01 00 :.W..U...<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
55 00 00 00 - Payload is 85 bytes long<br />
- No checksum in version message until 20 February 2012. See https://bitcointalk.org/index.php?topic=55852.0<br />
Version message:<br />
9C 7C 00 00 - 31900 (version 0.3.19)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
E6 15 10 4D 00 00 00 00 - Mon Dec 20 21:50:14 EST 2010<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 20 8D - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D - Sender address info - see Network Address<br />
DD 9D 20 2C 3A B4 57 13 - Node random unique ID<br />
00 - "" sub-version string (string is 0 bytes long)<br />
55 81 01 00 - Last block sending node has is block #98645<br />
</pre><br />
<br />
And here's a modern (60002) protocol version client advertising itself to a local peer...<br />
<br />
Newer protocol includes the checksum now, this is from a mainline (satoshi) client during <br />
an outgoing connection to another local client, notice that it does not fill out the <br />
address information at all when the source or destination is "unroutable".<br />
<br />
<pre><br />
<br />
0000 f9 be b4 d9 76 65 72 73 69 6f 6e 00 00 00 00 00 ....version.....<br />
0010 64 00 00 00 35 8d 49 32 62 ea 00 00 01 00 00 00 d...5.I2b.......<br />
0020 00 00 00 00 11 b2 d0 50 00 00 00 00 01 00 00 00 .......P........<br />
0030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ff ff ................<br />
0040 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 00 00 00 00 ff ff 00 00 00 00 00 00 ................<br />
0060 3b 2e b3 5d 8c e6 17 65 0f 2f 53 61 74 6f 73 68 ;..]...e./Satosh<br />
0070 69 3a 30 2e 37 2e 32 2f c0 3e 03 00 i:0.7.2/.>..<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
64 00 00 00 - Payload is 100 bytes long<br />
3B 64 8D 5A - payload checksum<br />
<br />
Version message:<br />
62 EA 00 00 - 60002 (protocol version 60002)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
11 B2 D0 50 00 00 00 00 - Tue Dec 18 10:12:33 PST 2012<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Sender address info - see Network Address<br />
3B 2E B3 5D 8C E6 17 65 - Node ID<br />
0F 2F 53 61 74 6F 73 68 69 3A 30 2E 37 2E 32 2F - "/Satoshi:0.7.2/" sub-version string (string is 15 bytes long)<br />
C0 3E 03 00 - Last block sending node has is block #212672<br />
</pre><br />
<br />
=== verack ===<br />
<br />
The ''verack'' message is sent in reply to ''[[#version|version]]''. This message consists of only a [[#Message structure|message header]] with the command string "verack".<br />
<br />
Hexdump of the verack message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......<br />
0010 00 00 00 00 5D F6 E0 E2 ........<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 61 63 6B 00 00 00 00 00 00 - "verack" command<br />
00 00 00 00 - Payload is 0 bytes long<br />
5D F6 E0 E2 - Checksum<br />
</pre><br />
<br />
=== addr ===<br />
<br />
Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours<br />
<br />
Payload:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of address entries (max: 1000)<br />
|-<br />
| 30x? || addr_list || (uint32_t + [[#Network address|net_addr]])[] || Address of other nodes on the network. version < 209 will only read the first one. The uint32_t is a timestamp (see note below).<br />
|}<br />
<br />
'''Note''': Starting version 31402, addresses are prefixed with a timestamp. If no timestamp is present, the addresses should not be relayed to other peers, unless it is indeed confirmed they are up.<br />
<br />
Hexdump example of ''addr'' message:<br />
<pre><br />
0000 F9 BE B4 D9 61 64 64 72 00 00 00 00 00 00 00 00 ....addr........<br />
0010 1F 00 00 00 ED 52 39 9B 01 E2 15 10 4D 01 00 00 .....R9.....M...<br />
0020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF ................<br />
0030 FF 0A 00 00 01 20 8D ..... .<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
61 64 64 72 00 00 00 00 00 00 00 00 - "addr"<br />
1F 00 00 00 - payload is 31 bytes long<br />
ED 52 39 9B - checksum of payload<br />
<br />
Payload:<br />
01 - 1 address in this message<br />
<br />
Address:<br />
E2 15 10 4D - Mon Dec 20 21:50:10 EST 2010 (only when version is >= 31402)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK service - see version message)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv4: 10.0.0.1, IPv6: ::ffff:10.0.0.1 (IPv4-mapped IPv6 address)<br />
20 8D - port 8333<br />
</pre><br />
<br />
=== inv ===<br />
<br />
Allows a node to advertise its knowledge of one or more objects. It can be received unsolicited, or in reply to ''getblocks''.<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getdata ===<br />
<br />
getdata is used in response to inv, to retrieve the content of a specific object, and is usually sent after receiving an ''inv'' packet, after filtering known elements. It can be used to retrieve transactions, but only if they are in the memory pool or relay set - arbitrary access to transactions in the chain is not allowed to avoid having clients start to depend on nodes having full transaction indexes (which modern nodes do not).<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== notfound ===<br />
<br />
notfound is a response to a getdata, sent if any requested data items could not be relayed, for example, because the requested transaction was not in the memory pool or relay set.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getblocks ===<br />
<br />
Return an ''inv'' packet containing the list of blocks starting right after the last known hash in the block locator object, up to hash_stop or 500 blocks, whichever comes first. <br />
<br />
The locator hashes are processed by a node in the order as they appear in the message. If a block hash is found in the node's main chain, the list of its children is returned back via the ''inv'' message and the remaining locators are ignored, no matter if the requested limit was reached, or not.<br />
<br />
To receive the next blocks hashes, one needs to issue getblocks again with a new block locator object. Keep in mind that some clients may provide blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block; set to zero to get as many blocks as possible (500)<br />
|}<br />
<br />
To create the block locator hashes, keep pushing hashes until you go back to the genesis block. After pushing 10 hashes back, the step backwards doubles every loop:<br />
<br />
<pre><br />
// From libbitcoin which is under AGPL<br />
std::vector<size_t> block_locator_indexes(size_t top_height)<br />
{<br />
std::vector<size_t> indexes;<br />
<br />
// Modify the step in the iteration.<br />
int64_t step = 1;<br />
<br />
// Start at the top of the chain and work backwards.<br />
for (auto index = (int64_t)top_height; index > 0; index -= step)<br />
{<br />
// Push top 10 indexes first, then back off exponentially.<br />
if (indexes.size() >= 10)<br />
step *= 2;<br />
<br />
indexes.push_back((size_t)index);<br />
}<br />
<br />
// Push the genesis block index.<br />
indexes.push_back(0);<br />
return indexes;<br />
}<br />
</pre><br />
<br />
Note that it is allowed to send in fewer known hashes down to a minimum of just one hash. However, the purpose of the block locator object is to detect a wrong branch in the caller's main chain. If the peer detects that you are off the main chain, it will send in block hashes which are earlier than your last known block. So if you just send in your last known hash and it is off the main chain, the peer starts over at block #1.<br />
<br />
=== getheaders ===<br />
<br />
Return a ''headers'' packet containing the headers of blocks starting right after the last known hash in the block locator object, up to hash_stop or 2000 blocks, whichever comes first. To receive the next block headers, one needs to issue getheaders again with a new block locator object. The ''getheaders'' command is used by thin clients to quickly download the block chain where the contents of the transactions would be irrelevant (because they are not ours). Keep in mind that some clients may provide headers of blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block header; set to zero to get as many blocks as possible (2000)<br />
|}<br />
<br />
For the block locator object in this packet, the same rules apply as for the [[Protocol_documentation#getblocks|getblocks]] packet.<br />
<br />
=== tx ===<br />
<br />
''tx'' describes a bitcoin transaction, in reply to ''[[#getdata|getdata]]''<br />
<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Transaction data format version (note, this is signed)<br />
|-<br />
| 1+ || tx_in count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction inputs<br />
|-<br />
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins<br />
|-<br />
| 1+ || tx_out count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction outputs<br />
|-<br />
| 9+ || tx_out || tx_out[] || A list of 1 or more transaction outputs or destinations for coins<br />
|-<br />
| 4 || lock_time || uint32_t || The block number or timestamp at which this transaction is unlocked:<br />
{|class="wikitable"<br />
! Value !! Description<br />
|-<br />
| 0 || Not locked<br />
|-<br />
| < 500000000 || Block number at which this transaction is unlocked<br />
|-<br />
| >= 500000000 || UNIX timestamp at which this transaction is unlocked<br />
|}<br />
If all TxIn inputs have final (0xffffffff) sequence numbers then lock_time is irrelevant. Otherwise, the transaction may not be added to a block until after lock_time (see [[NLockTime]]).<br />
<br />
|}<br />
<br />
TxIn consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 36 || previous_output || outpoint || The previous output transaction reference, as an OutPoint structure<br />
|-<br />
| 1+ || script length || [[Protocol_documentation#Variable_length_integer|var_int]] || The length of the signature script<br />
|-<br />
| ? || signature script || uchar[] || Computational Script for confirming transaction authorization<br />
|-<br />
| 4 || [http://bitcoin.stackexchange.com/q/2025/323 sequence] || uint32_t || Transaction version as defined by the sender. Intended for "replacement" of transactions when information is updated before inclusion into a block.<br />
|}<br />
<br />
The OutPoint structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 32 || hash || char[32] || The hash of the referenced transaction.<br />
|-<br />
| 4 || index || uint32_t || The index of the specific output in the transaction. The first output is 0, etc.<br />
|}<br />
<br />
The Script structure consists of a series of pieces of information and operations related to the value of the transaction.<br />
<br />
(Structure to be expanded in the future… see script.h and script.cpp and [[Script]] for more information)<br />
<br />
The TxOut structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || value || int64_t || Transaction Value<br />
|-<br />
| 1+ || pk_script length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the pk_script<br />
|-<br />
| ? || pk_script || uchar[] || Usually contains the public key as a Bitcoin script setting up conditions to claim this output.<br />
|}<br />
<br />
Example ''tx'' message:<br />
<pre><br />
000000 F9 BE B4 D9 74 78 00 00 00 00 00 00 00 00 00 00 ....tx..........<br />
000010 02 01 00 00 E2 93 CD BE 01 00 00 00 01 6D BD DB .............m..<br />
000020 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D 12 66 E9 .[...Q........f.<br />
000030 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29 00 00 00 .;P......j.6)...<br />
000040 00 8B 48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 ..H0E.!..X..r...<br />
000050 C7 36 7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A .6zz%;..R#...h.:<br />
000060 59 23 3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 Y#?E.W... Y.....<br />
000070 0E 41 83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D .A.z.X.z...XN...<br />
000080 35 BD 96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF 5...6..;...A....<br />
000090 C9 7E F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 .~.6.m...@..!...<br />
0000A0 2A CD 2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC *.+..].}Y... ...<br />
0000B0 4E 02 53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F N.S..=7.o...Q...<br />
0000C0 14 04 2F 46 61 4A 4C 70 C0 F1 4B EF F5 FF FF FF ../FaJLp..K.....<br />
0000D0 FF 02 40 4B 4C 00 00 00 00 00 19 76 A9 14 1A A0 ..@KL......v....<br />
0000E0 CD 1C BE A6 E7 45 8A 7A BA D5 12 A9 D9 EA 1A FB .....E.z........<br />
0000F0 22 5E 88 AC 80 FA E9 C7 00 00 00 00 19 76 A9 14 "^...........v..<br />
000100 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E FD A0 B7 ..[.Cj.....H^...<br />
000110 8B 4E CC 52 88 AC 00 00 00 00 .N.R......<br />
<br />
<br />
Message header:<br />
F9 BE B4 D9 - main network magic bytes<br />
74 78 00 00 00 00 00 00 00 00 00 00 - "tx" command<br />
02 01 00 00 - payload is 258 bytes long<br />
E2 93 CD BE - checksum of payload<br />
<br />
Transaction:<br />
01 00 00 00 - version<br />
<br />
Inputs:<br />
01 - number of transaction inputs<br />
<br />
Input 1:<br />
6D BD DB 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D - previous output (outpoint)<br />
12 66 E9 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29<br />
00 00 00 00<br />
<br />
8B - script is 139 bytes long<br />
<br />
48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 C7 36 - signature script (scriptSig)<br />
7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A 59 23<br />
3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 0E 41<br />
83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D 35 BD<br />
96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF C9 7E<br />
F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 2A CD<br />
2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC 4E 02<br />
53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F 14 04<br />
2F 46 61 4A 4C 70 C0 F1 4B EF F5<br />
<br />
FF FF FF FF - sequence<br />
<br />
Outputs:<br />
02 - 2 Output Transactions<br />
<br />
Output 1:<br />
40 4B 4C 00 00 00 00 00 - 0.05 BTC (5000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 1A A0 CD 1C BE A6 E7 45 8A 7A BA D5 12 - pk_script<br />
A9 D9 EA 1A FB 22 5E 88 AC<br />
<br />
Output 2:<br />
80 FA E9 C7 00 00 00 00 - 33.54 BTC (3354000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E - pk_script<br />
FD A0 B7 8B 4E CC 52 88 AC<br />
<br />
Locktime:<br />
00 00 00 00 - lock time<br />
</pre><br />
<br />
=== block ===<br />
<br />
The '''block''' message is sent in response to a getdata message which requests transaction information from a block hash.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A Unix timestamp recording when this block was created (Currently limited to dates before the year 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated [[Difficulty|difficulty target]] being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| ? || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries<br />
|-<br />
| ? || txns || tx[] || Block transactions, in format of "tx" command<br />
|}<br />
<br />
The SHA256 hash that identifies each block (and which must have a run of 0 bits) is calculated from the first 6 fields of this structure (version, prev_block, merkle_root, timestamp, bits, nonce, and standard SHA256 padding, making two 64-byte chunks in all) and ''not'' from the complete block. To calculate the hash, only two chunks need to be processed by the SHA256 algorithm. Since the ''nonce'' field is in the second chunk, the first chunk stays constant during mining and therefore only the second chunk needs to be processed. However, a Bitcoin hash is the hash of the hash, so two SHA256 rounds are needed for each mining iteration.<br />
See [[Block hashing algorithm]] for details and an example.<br />
<br />
=== headers ===<br />
<br />
The ''headers'' packet returns block headers in response to a ''getheaders'' packet. <br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of block headers<br />
|-<br />
| 81x? || headers || [[Protocol_documentation#Block_Headers|block_header]][] || [[Protocol_documentation#Block_Headers|Block headers]]<br />
|}<br />
<br />
Note that the block headers in this packet include a transaction count (a var_int, so there can be more than 81 bytes per header) as opposed to the block headers that are hashed by miners.<br />
<br />
=== getaddr ===<br />
<br />
The getaddr message sends a request to a node asking for information about known active peers to help with finding potential nodes in the network. The response to receiving this message is to transmit one or more addr messages with one or more peers from a database of known active peers. The typical presumption is that a node is likely to be active if it has been sending a message within the last three hours.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
=== mempool ===<br />
<br />
The mempool message sends a request to a node asking for information about transactions it has verified but which have not yet confirmed. The response to receiving this message is an inv message containing the transaction hashes for all the transactions in the node's mempool.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
It is specified in [https://github.com/bitcoin/bips/blob/master/bip-0035.mediawiki BIP 35]. Since [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 37], if a [[Protocol_documentation#filterload.2C_filteradd.2C_filterclear.2C_merkleblock|bloom filter]] is loaded, only transactions matching the filter are replied.<br />
<br />
=== checkorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== submitorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== reply ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== ping ===<br />
<br />
The ''ping'' message is sent primarily to confirm that the TCP/IP connection is still valid. An error in transmission is presumed to be a closed connection and the address is removed as a current peer.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || random nonce<br />
|}<br />
<br />
=== pong ===<br />
<br />
The ''pong'' message is sent in response to a ''ping'' message. In modern protocol versions, a ''pong'' response is generated using a nonce included in the ping.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || nonce from ping<br />
|}<br />
<br />
<br />
=== reject===<br />
<br />
The ''reject'' message is sent when messages are rejected.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || message || var_str || type of message rejected<br />
|-<br />
| 1 || ccode || char || code relating to rejected message<br />
|-<br />
| 1+ || reason || var_str || text version of reason for rejection<br />
|-<br />
| 0+ || data || char || Optional extra data provided by some errors. Currently, all errors which provide this field fill it with the TXID or block header hash of the object being rejected, so the field is 32 bytes.<br />
|}<br />
<br />
CCodes<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0x01 || REJECT_MALFORMED|| <br />
|-<br />
| 0x10 || REJECT_INVALID ||<br />
|-<br />
| 0x11 || REJECT_OBSOLETE ||<br />
|-<br />
| 0x12 || REJECT_DUPLICATE ||<br />
|-<br />
| 0x40 || REJECT_NONSTANDARD ||<br />
|-<br />
| 0x41 || REJECT_DUST ||<br />
|-<br />
| 0x42 || REJECT_INSUFFICIENTFEE ||<br />
|-<br />
| 0x43 || REJECT_CHECKPOINT ||<br />
|}<br />
<br />
=== filterload, filteradd, filterclear, merkleblock ===<br />
<br />
These messages are related to Bloom filtering of connections and are defined in [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037].<br />
<br />
<br />
The <code>filterload</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || filter || uint8_t[] || The filter itself is simply a bit field of arbitrary byte-aligned size. The maximum size is 36,000 bytes.<br />
|-<br />
| 4 || nHashFuncs || uint32_t || The number of hash functions to use in this filter. The maximum value allowed in this field is 50.<br />
|-<br />
| 4 || nTweak || uint32_t || A random value to add to the seed value in the hash function used by the bloom filter.<br />
|-<br />
| 1 || nFlags || uint8_t || A set of flags that control how matched items are added to the filter.<br />
|}<br />
<br />
See below for a description of the Bloom filter algorithm and how to select nHashFuncs and filter size for a desired false positive rate.<br />
<br />
Upon receiving a <code>filterload</code> command, the remote peer will immediately restrict the broadcast transactions it announces (in inv packets) to transactions matching the filter, where the matching algorithm is specified below. The flags control the update behaviour of the matching algorithm.<br />
<br />
The <code>filteradd</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || data || uint8_t[] || The data element to add to the current filter.<br />
|}<br />
<br />
The data field must be smaller than or equal to 520 bytes in size (the maximum size of any potentially matched object).<br />
<br />
The given data element will be added to the Bloom filter. A filter must have been previously provided using <code>filterload</code>. This command is useful if a new key or script is added to a clients wallet whilst it has connections to the network open, it avoids the need to re-calculate and send an entirely new filter to every peer (though doing so is usually advisable to maintain anonymity).<br />
<br />
The <code>filterclear</code> command has no arguments at all.<br />
<br />
After a filter has been set, nodes don't merely stop announcing non-matching transactions, they can also serve filtered blocks. A filtered block is defined by the <code>merkleblock</code> message and is defined like this:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information, based upon the software version creating this block (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Limited to 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 4 || total_transactions || uint32_t || Number of transactions in the block (including unmatched ones)<br />
|-<br />
| ? || hashes || uint256[] || hashes in depth-first order (including standard varint size prefix)<br />
|-<br />
| ? || flags || byte[] || flag bits, packed per 8 in a byte, least significant bit first (including standard varint size prefix)<br />
|}<br />
<br />
=== alert ===<br />
<br />
'''Note:''' Support for alert messages has been removed from bitcoin core in March 2016. Read more [https://github.com/bitcoin/bitcoin/pull/7692 here]<br />
<br />
<br />
An '''alert''' is sent between nodes to send a general notification message throughout the network. If the alert can be confirmed with the signature as having come from the core development group of the Bitcoin software, the message is suggested to be displayed for end-users. Attempts to perform transactions, particularly automated transactions through the client, are suggested to be halted. The text in the Message string should be relayed to log files and any user interfaces.<br />
<br />
Alert format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || payload || uchar[] || Serialized alert payload<br />
|-<br />
| ? || signature || uchar[] || An ECDSA signature of the message<br />
|}<br />
<br />
The developers of Satoshi's client use this public key for signing alerts:<br />
04fc9702847840aaf195de8442ebecedf5b095cdbb9bc716bda9110971b28a49e0ead8564ff0db22209e0374782c093bb899692d524e9d6a6956e7c5ecbcd68284<br />
(hash) 1AGRxqDa5WjUKBwHB9XYEjmkv1ucoUUy1s<br />
<br />
The payload is serialized into a uchar[] to ensure that versions using incompatible alert formats can still relay alerts among one another. The current alert payload format is:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || Version || int32_t || Alert format version<br />
|-<br />
| 8 || RelayUntil || int64_t || The timestamp beyond which nodes should stop relaying this alert<br />
|-<br />
| 8 || Expiration || int64_t || The timestamp beyond which this alert is no longer in effect and should be ignored<br />
|-<br />
| 4 || ID || int32_t || A unique ID number for this alert<br />
|-<br />
| 4 || Cancel || int32_t || All alerts with an ID number less than or equal to this number should be cancelled: deleted and not accepted in the future<br />
|-<br />
| ? || setCancel || set<int32_t> || All alert IDs contained in this set should be cancelled as above<br />
|-<br />
| 4 || MinVer || int32_t || This alert only applies to versions greater than or equal to this version. Other versions should still relay it.<br />
|-<br />
| 4 || MaxVer || int32_t || This alert only applies to versions less than or equal to this version. Other versions should still relay it.<br />
|-<br />
| ? || setSubVer || set<string> || If this set contains any elements, then only nodes that have their subVer contained in this set are affected by the alert. Other versions should still relay it.<br />
|-<br />
| 4 || Priority || int32_t || Relative priority compared to other alerts<br />
|-<br />
| ? || Comment || string || A comment on the alert that is not displayed<br />
|-<br />
| ? || StatusBar || string || The alert message that is displayed to the user<br />
|-<br />
| ? || Reserved || string || Reserved<br />
|}<br />
<br />
Note: '''set<''type''>''' in the table above is a [[#Variable length integer | variable length integer]] followed by the number of fields of the given ''type'' (either int32_t or [[#Variable length string | variable length string]])<br />
<br />
Sample alert (no message header):<br />
73010000003766404f00000000b305434f00000000f2030000f1030000001027000048ee0000<br />
0064000000004653656520626974636f696e2e6f72672f666562323020696620796f75206861<br />
76652074726f75626c6520636f6e6e656374696e672061667465722032302046656272756172<br />
79004730450221008389df45f0703f39ec8c1cc42c13810ffcae14995bb648340219e353b63b<br />
53eb022009ec65e1c1aaeec1fd334c6b684bde2b3f573060d5b70c3a46723326e4e8a4f1<br />
<br />
Version: 1<br />
RelayUntil: 1329620535<br />
Expiration: 1329792435<br />
ID: 1010<br />
Cancel: 1009<br />
setCancel: <empty><br />
MinVer: 10000<br />
MaxVer: 61000<br />
setSubVer: <empty><br />
Priority: 100<br />
Comment: <empty><br />
StatusBar: "See bitcoin.org/feb20 if you have trouble connecting after 20 February"<br />
Reserved: <empty><br />
<br />
=== sendheaders ===<br />
<br />
Request for Direct headers announcement. <br />
<br />
Upon receipt of this message, the node is be permitted, but not required, to announce new blocks by '''headers''' command (instead of '''inv''' command).<br />
<br />
This message is supported by the protocol version >= 70012 or Bitcoin Core version >= 0.12.0.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0130.mediawiki BIP 130] for more information.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
<br />
=== feefilter ===<br />
<br />
The payload is always 8 bytes long and it encodes 64 bit integer value (LSB / little endian) of '''feerate'''.<br />
The value represents a minimal fee and is expressed in satoshis per 1000 bytes.<br />
<br />
Upon receipt of a "feefilter" message, the node will be permitted, but not required, to filter transaction invs for transactions that fall below the feerate provided in the feefilter message interpreted as satoshis per kilobyte.<br />
<br />
The fee filter is additive with a bloom filter for transactions so if an SPV client were to load a bloom filter and send a feefilter message, transactions would only be relayed if they passed both filters.<br />
<br />
Inv's generated from a mempool message are also subject to a fee filter if it exists.<br />
<br />
Feature discovery is enabled by checking protocol version >= 70013<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0133.mediawiki BIP 133] for more information.<br />
<br />
=== sendcmpct ===<br />
<br />
# The sendcmpct message is defined as a message containing a 1-byte integer followed by a 8-byte integer where pchCommand == "sendcmpct".<br />
# The first integer SHALL be interpreted as a boolean (and MUST have a value of either 1 or 0)<br />
# The second integer SHALL be interpreted as a little-endian version number. Nodes sending a sendcmpct message MUST currently set this value to 1.<br />
# Upon receipt of a "sendcmpct" message with the first and second integers set to 1, the node SHOULD announce new blocks by sending a cmpctblock message.<br />
# Upon receipt of a "sendcmpct" message with the first integer set to 0, the node SHOULD NOT announce new blocks by sending a cmpctblock message, but SHOULD announce new blocks by sending invs or headers, as defined by BIP130.<br />
# Upon receipt of a "sendcmpct" message with the second integer set to something other than 1, nodes MUST treat the peer as if they had not received the message (as it indicates the peer will provide an unexpected encoding in <br />
# cmpctblock, and/or other, messages). This allows future versions to send duplicate sendcmpct messages with different versions as a part of a version handshake for future versions.<br />
# Nodes SHOULD check for a protocol version of >= 70014 before sending sendcmpct messages.<br />
# Nodes MUST NOT send a request for a MSG_CMPCT_BLOCK object to a peer before having received a sendcmpct message from that peer.<br />
<br />
This message is only supported by protocol version >= 70014<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== cmpctblock ===<br />
<br />
# The cmpctblock message is defined as as a message containing a serialized [[Protocol_documentation#HeaderAndShortIDs|HeaderAndShortIDs]] message and pchCommand == "cmpctblock".<br />
# Upon receipt of a cmpctblock message after sending a sendcmpct message, nodes SHOULD calculate the [[Protocol_documentation#Short_transaction_ID|short transaction ID]] for each unconfirmed transaction they have available (ie in their mempool) and compare each to each short transaction ID in the cmpctblock message.<br />
# After finding already-available transactions, nodes which do not have all transactions available to reconstruct the full block SHOULD request the missing transactions using a getblocktxn message.<br />
# A node MUST NOT send a cmpctblock message unless they are able to respond to a getblocktxn message which requests every transaction in the block.<br />
# A node MUST NOT send a cmpctblock message without having validated that the header properly commits to each transaction in the block, and properly builds on top of the existing chain with a valid proof-of-work. A node MAY send a cmpctblock before validating that each transaction in the block validly spends existing UTXO set entries.<br />
<br />
This message is only supported by protocol version >= 70014<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== getblocktxn ===<br />
<br />
# The getblocktxn message is defined as as a message containing a serialized [[Protocol_documentation#BlockTransactionsRequest|BlockTransactionsRequest]] message and pchCommand == "getblocktxn".<br />
# Upon receipt of a properly-formatted getblocktxnmessage, nodes which recently provided the sender of such a message a cmpctblock for the block hash identified in this message MUST respond with an appropriate [[Protocol_documentation#blocktxn|blocktxn]] message. Such a blocktxn message MUST contain exactly and only each transaction which is present in the appropriate block at the index specified in the getblocktxn indexes list, in the order requested.<br />
<br />
This message is only supported by protocol version >= 70014<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== blocktxn ===<br />
<br />
# The blocktxn message is defined as as a message containing a serialized [[Protocol_documentation#BlockTransactions|BlockTransactions]] message and pchCommand == "blocktxn".<br />
# Upon receipt of a properly-formatted requested blocktxn message, nodes SHOULD attempt to reconstruct the full block by:<br />
# Taking the prefilledtxn transactions from the original [[Protocol_documentation#cmpctblock|cmpctblock]] and placing them in the marked positions.<br />
# For each short transaction ID from the original [[Protocol_documentation#cmpctblock|cmpctblock]], in order, find the corresponding transaction either from the blocktxn message or from other sources and place it in the first available position in the block.<br />
# Once the block has been reconstructed, it shall be processed as normal, keeping in mind that short transaction IDs are expected to occasionally collide, and that nodes MUST NOT be penalized for such collisions, wherever they appear.<br />
<br />
This message is only supported by protocol version >= 70014<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
== Scripting ==<br />
<br />
See [[script]].<br />
<br />
==See Also==<br />
<br />
* [[Network]]<br />
* [[Protocol rules]]<br />
* [[Hardfork Wishlist]]<br />
* [https://bitcoin.org/en/developer-documentation Developer Documentation on bitcoin.org]<br />
* Bitcoin dissectors for Wireshark: https://github.com/lbotsch/wireshark-bitcoin https://github.com/op-sig/bitcoin-wireshark-dissector<br />
<br />
==References==<br />
<references /><br />
<br />
[[zh-cn:协议说明]]<br />
[[Category:Technical]]<br />
[[Category:Developer]]<br />
<br />
{{Bitcoin Core documentation}}</div>Tonikthttps://en.bitcoin.it/w/index.php?title=Protocol_documentation&diff=63713Protocol documentation2017-07-26T14:06:29Z<p>Tonikt: Each element in addr message is 34 bytes long, not 30</p>
<hr />
<div>This page ''describes'' the behavior of the [[Original Bitcoin client|reference client]]. The Bitcoin protocol is specified by the behavior of the reference client, not by this page. In particular, while this page is quite complete in describing the network protocol, it does not attempt to list all of the rules for block or transaction validity.<br />
<br />
Type names used in this documentation are from the C99 standard.<br />
<br />
For protocol used in mining, see [[getblocktemplate]].<br />
<br />
==Common standards==<br />
<br />
=== Hashes ===<br />
<br />
Usually, when a hash is computed within bitcoin, it is computed twice. Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-256] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when a shorter hash is desirable (for example when creating a bitcoin address).<br />
<br />
Example of double-SHA-256 encoding of string "hello":<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round of sha-256)<br />
9595c9df90075148eb06860365df33584b75bff782a510c6cd4883a419833d50 (second round of sha-256)<br />
<br />
For bitcoin addresses (RIPEMD-160) this would give:<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round is sha-256)<br />
b6a9c8c230722b7c748331a8b450f05566dc7d0f (with ripemd-160)<br />
<br />
=== Merkle Trees ===<br />
<br />
Merkle trees are binary trees of hashes. Merkle trees in bitcoin use a '''double''' SHA-256, the SHA-256 hash of the SHA-256 hash of something.<br />
<br />
If, when forming a row in the tree (other than the root of the tree), it would have an odd number of elements, the final double-hash is duplicated to ensure that the row has an even number of hashes.<br />
<br />
First form the bottom row of the tree with the ordered double-SHA-256 hashes of the byte streams of the transactions in the block.<br />
<br />
Then the row above it consists of half that number of hashes. Each entry is the double-SHA-256 of the 64-byte concatenation of the corresponding two hashes below it in the tree.<br />
<br />
This procedure repeats recursively until we reach a row consisting of just a single double-hash. This is the '''Merkle root''' of the tree.<br />
<br />
For example, imagine a block with three transactions ''a'', ''b'' and ''c''. The Merkle tree is: <br />
<br />
d1 = dhash(a)<br />
d2 = dhash(b)<br />
d3 = dhash(c)<br />
d4 = dhash(c) # a, b, c are 3. that's an odd number, so we take the c twice<br />
<br />
d5 = dhash(d1 concat d2)<br />
d6 = dhash(d3 concat d4)<br />
<br />
d7 = dhash(d5 concat d6)<br />
<br />
where<br />
<br />
dhash(a) = sha256(sha256(a))<br />
<br />
''d7'' is the Merkle root of the 3 transactions in this block.<br />
<br />
Note: Hashes in Merkle Tree displayed in the [[Block Explorer]] are of little-endian notation. For some implementations and [http://www.fileformat.info/tool/hash.htm calculations], the bits need to be reversed before they are hashed, and again after the hashing operation.<br />
<br />
=== Signatures ===<br />
<br />
Bitcoin uses [http://en.wikipedia.org/wiki/Elliptic_curve_cryptography Elliptic Curve] [http://en.wikipedia.org/wiki/Digital_Signature_Algorithm Digital Signature Algorithm] ([http://en.wikipedia.org/wiki/Elliptic_Curve_DSA ECDSA]) to sign transactions. <br />
<br />
For [[ECDSA]] the secp256k1 curve from http://www.secg.org/sec2-v2.pdf is used.<br />
<br />
Public keys (in scripts) are given as 04 <x> <y> where ''x'' and ''y'' are 32 byte big-endian integers representing the coordinates of a point on the curve or in compressed form given as <sign> <x> where <sign> is 0x02 if ''y'' is even and 0x03 if ''y'' is odd.<br />
<br />
Signatures use [http://en.wikipedia.org/wiki/Distinguished_Encoding_Rules DER encoding] to pack the ''r'' and ''s'' components into a single byte stream (this is also what OpenSSL produces by default).<br />
<br />
=== Transaction Verification ===<br />
Transactions are cryptographically signed records that reassign ownership of Bitcoins to new addresses. Transactions have ''inputs'' - records which reference the funds from other previous transactions - and ''outputs'' - records which determine the new owner of the transferred Bitcoins, and which will be referenced as inputs in future transactions as those funds are respent.<br />
<br />
Each ''input'' must have a cryptographic digital signature that unlocks the funds from the prior transaction. Only the person possessing the appropriate [[private key]] is able to create a satisfactory signature; this in effect ensures that funds can only be spent by their owners.<br />
<br />
Each ''output'' determines which Bitcoin address (or other criteria, see [[Script]]) is the recipient of the funds.<br />
<br />
In a transaction, the sum of all inputs must be equal to or greater than the sum of all outputs. If the inputs exceed the outputs, the difference is considered a [[transaction fee]], and is redeemable by whoever first includes the transaction into the block chain.<br />
<br />
A special kind of transaction, called a [[coinbase transaction]], has no inputs. It is created by [[miners]], and there is one coinbase transaction per block. Because each block comes with a reward of newly created Bitcoins (e.g. 50 BTC for the first 210,000 blocks), the first transaction of a block is, with few exceptions, the transaction that grants those coins to their recipient (the miner). In addition to the newly created Bitcoins, the coinbase transaction is also used for assigning the recipient of any transaction fees that were paid within the other transactions being included in the same block. The coinbase transaction can assign the entire reward to a single Bitcoin address, or split it in portions among multiple addresses, just like any other transaction. Coinbase transactions always contain outputs totalling the sum of the block reward plus all transaction fees collected from the other transactions in the same block.<br />
<br />
The [[coinbase transaction]] in block zero cannot be spent. This is due to a quirk of the reference client implementation that would open the potential for a block chain fork if some nodes accepted the spend and others did not<ref>[http://bitcointalk.org/index.php?topic=119645.msg1288552#msg1288552 Block 0 Network Fork]</ref>.<br />
<br />
Most Bitcoin outputs encumber the newly transferred coins with a single ECDSA private key. The actual record saved with inputs and outputs isn't necessarily a key, but a ''script''. Bitcoin uses an interpreted scripting system to determine whether an output's criteria have been satisfied, with which more complex operations are possible, such as outputs that require two ECDSA signatures, or two-of-three-signature schemes. An output that references a single Bitcoin address is a ''typical'' output; an output actually contains this information in the form of a script that requires a single ECDSA signature (see [[OP_CHECKSIG]]). The output script specifies what must be provided to unlock the funds later, and when the time comes in the future to spend the transaction in another input, that input must provide all of the thing(s) that satisfy the requirements defined by the original output script.<br />
<br />
=== Addresses ===<br />
<br />
A bitcoin address is in fact the hash of a ECDSA public key, computed this way:<br />
<br />
Version = 1 byte of 0 (zero); on the test network, this is 1 byte of 111<br />
Key hash = Version concatenated with RIPEMD-160(SHA-256(public key))<br />
Checksum = 1st 4 bytes of SHA-256(SHA-256(Key hash))<br />
Bitcoin Address = Base58Encode(Key hash concatenated with Checksum)<br />
<br />
The Base58 encoding used is home made, and has some differences. Especially, leading zeroes are kept as single zeroes when conversion happens.<br />
<br />
== Common structures ==<br />
<br />
Almost all integers are encoded in little endian. Only IP or port number are encoded big endian.<br />
<br />
=== Message structure ===<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown<br />
|-<br />
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| 4 || length || uint32_t || Length of payload in number of bytes<br />
|-<br />
| 4 || checksum || uint32_t || First 4 bytes of sha256(sha256(payload))<br />
|-<br />
| ? || payload || uchar[] || The actual data<br />
|}<br />
<br />
<br />
Known magic values:<br />
<br />
{|class="wikitable"<br />
! Network !! Magic value !! Sent over wire as<br />
|-<br />
| main || 0xD9B4BEF9 || F9 BE B4 D9<br />
|-<br />
| testnet || 0xDAB5BFFA || FA BF B5 DA<br />
|-<br />
| testnet3 || 0x0709110B || 0B 11 09 07<br />
|-<br />
| namecoin || 0xFEB4BEF9 || F9 BE B4 FE<br />
|}<br />
<br />
=== Variable length integer ===<br />
<br />
Integer can be encoded depending on the represented value to save space.<br />
Variable length integers always precede an array/vector of a type of data that may vary in length.<br />
Longer numbers are encoded in little endian.<br />
<br />
{|class="wikitable"<br />
! Value !! Storage length !! Format<br />
|-<br />
| < 0xFD || 1 || uint8_t<br />
|-<br />
| <= 0xFFFF || 3 || 0xFD followed by the length as uint16_t<br />
|-<br />
| <= 0xFFFF FFFF || 5 || 0xFE followed by the length as uint32_t<br />
|-<br />
| - || 9 || 0xFF followed by the length as uint64_t<br />
|}<br />
<br />
If you're reading the Satoshi client code (BitcoinQT) it refers to this encoding as a "CompactSize". Modern BitcoinQT also has the CVarInt class which implements an even more compact integer for the purpose of local storage (which is incompatible with "CompactSize" described here). CVarInt is not a part of the protocol.<br />
<br />
=== Variable length string ===<br />
<br />
Variable length string can be stored using a variable length integer followed by the string itself.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the string<br />
|-<br />
| ? || string || char[] || The string itself (can be empty)<br />
|}<br />
<br />
=== Network address ===<br />
<br />
When a network address is needed somewhere, this structure is used. Network addresses are not prefixed with a timestamp in the version message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || time || uint32 || the Time (version >= 31402). '''Not present in version message.'''<br />
|-<br />
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]<br />
|-<br />
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The original client only supported IPv4 and only read the last 4 bytes to get the IPv4 address. However, the IPv4 address is written into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]<br />
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).<br />
|-<br />
| 2 || port || uint16_t || port number, network byte order<br />
|}<br />
<br />
Hexdump example of Network address structure<br />
<br />
<pre><br />
0000 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0010 00 00 FF FF 0A 00 00 01 20 8D ........ .<br />
<br />
Network address:<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK: see services listed under version command)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv6: ::ffff:a00:1 or IPv4: 10.0.0.1<br />
20 8D - Port 8333<br />
</pre><br />
<br />
=== Inventory Vectors ===<br />
<br />
Inventory vectors are used for notifying other nodes about objects they have or data which is being requested.<br />
<br />
Inventory vectors consist of the following data format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || type || uint32_t || Identifies the object type linked to this inventory<br />
|-<br />
| 32 || hash || char[32] || Hash of the object<br />
|}<br />
<br />
<br />
The object type is currently defined as one of the following possibilities:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0 || ERROR || Any data of with this number may be ignored<br />
|-<br />
| 1 || MSG_TX || Hash is related to a transaction<br />
|-<br />
| 2 || MSG_BLOCK || Hash is related to a data block<br />
|-<br />
| 3 || MSG_FILTERED_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a merkleblock message rather than a block message; this only works if a bloom filter has been set.<br />
|-<br />
| 4 || MSG_CMPCT_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a cmpctblock message. See BIP 152 for more info.<br />
|}<br />
<br />
Other Data Type values are considered reserved for future implementations.<br />
<br />
=== Block Headers ===<br />
<br />
Block headers are sent in a headers packet in response to a getheaders message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Will overflow in 2106<ref>https://en.wikipedia.org/wiki/Unix_time#Notable_events_in_Unix_time</ref>)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 1 || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries, this value is always 0<br />
|}<br />
<br />
cf. [[Block hashing algorithm]]<br />
<br />
=== Differential encoding === <br />
Several uses of CompactSize below are "differentially encoded". For these, instead of using raw indexes, the number encoded is the difference between the current index and the previous index, minus one. For example, a first index of 0 implies a real index of 0, a second index of 0 thereafter refers to a real index of 1, etc.<br />
<br />
=== PrefilledTransaction ===<br />
<br />
A PrefilledTransaction structure is used in HeaderAndShortIDs to provide a list of a few transactions explicitly.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| index || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1, 3 bytes || Compact Size, differentially encoded since the last PrefilledTransaction in a list || The index into the block at which this transaction is<br />
|-<br />
| tx || Transaction || variable || As encoded in [[Protocol_documentation#tx|tx messages]] || The transaction which is in the block at index index.<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== HeaderAndShortIDs ===<br />
<br />
A HeaderAndShortIDs structure is used to relay a block header, the short transactions IDs used for matching already-available transactions, and a select few transactions which we expect a peer may be missing.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| header || Block header || 80 bytes || First 80 bytes of the block as defined by the encoding used by "block" messages || The header of the block being provided<br />
|-<br />
| nonce || uint64_t || 8 bytes || Little Endian || A nonce for use in short transaction ID calculations<br />
|-<br />
| shortids_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of short transaction IDs in shortids (ie block tx count - prefilledtxn_length)<br />
|-<br />
| shortids || List of 6-byte integers || 6*shortids_length bytes || Little Endian || The [[Protocol_documentation#Short_transaction_ID|short transaction IDs]] calculated from the transactions which were not provided explicitly in prefilledtxn<br />
|-<br />
| prefilledtxn_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of prefilled transactions in prefilledtxn (ie block tx count - shortids_length)<br />
|-<br />
| prefilledtxn || List of PrefilledTransactions || variable size*prefilledtxn_length || As defined by [[Protocol_documentation#PrefilledTransaction|PrefilledTransaction]] definition, above || Used to provide the coinbase transaction and a select few which we expect a peer may be missing<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== BlockTransactionsRequest ===<br />
<br />
A BlockTransactionsRequest structure is used to list transaction indexes in a block being requested.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| blockhash || Binary blob || 32 bytes || The output from a double-SHA256 of the block header, as used elsewhere || The blockhash of the block which the transactions being requested are in<br />
|-<br />
| indexes_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of transactions being requested<br />
|-<br />
| indexes || List of [[Protocol_documentation#Variable_length_integer|CompactSizes]] || 1 or 3 bytes*indexes_length || [[Protocol_documentation#Differential_encoding|Differentially encoded]] || The indexes of the transactions being requested in the block<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== BlockTransactions ===<br />
<br />
A BlockTransactions structure is used to provide some of the transactions in a block, as requested.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| blockhash || Binary blob || 32 bytes || The output from a double-SHA256 of the block header, as used elsewhere || The blockhash of the block which the transactions being provided are in<br />
|-<br />
| transactions_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of transactions provided<br />
|-<br />
| transactions || List of Transactions || variable || As encoded in [[Protocol_documentation#tx|tx messages]] || The transactions provided<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== Short transaction ID ===<br />
<br />
Short transaction IDs are used to represent a transaction without sending a full 256-bit hash. They are calculated by:<br />
<br />
# single-SHA256 hashing the block header with the nonce appended (in little-endian)<br />
# Running SipHash-2-4 with the input being the transaction ID and the keys (k0/k1) set to the first two little-endian 64-bit integers from the above hash, respectively.<br />
# Dropping the 2 most significant bytes from the SipHash output to make it 6 bytes.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
== Message types ==<br />
<br />
=== version ===<br />
<br />
When a node creates an outgoing connection, it will immediately [[Version Handshake|advertise]] its version. The remote node will respond with its version. No further communication is possible until both peers have exchanged their version.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Identifies protocol version being used by the node<br />
|-<br />
| 8 || services || uint64_t || bitfield of features to be enabled for this connection<br />
|-<br />
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds<br />
|-<br />
| 26 || addr_recv || [[#Network address|net_addr]] || The network address of the node receiving this message<br />
|-<br />
|colspan="4"| Fields below require version ≥ 106<br />
|-<br />
| 26 || addr_from || [[#Network address|net_addr]] || The network address of the node emitting this message<br />
|-<br />
| 8 || nonce || uint64_t || Node random nonce, randomly generated every time a version packet is sent. This nonce is used to detect connections to self.<br />
|-<br />
| ? || user_agent || [[#Variable length string|var_str]] || [https://github.com/bitcoin/bips/blob/master/bip-0014.mediawiki User Agent] (0x00 if string is 0 bytes long)<br />
|-<br />
| 4 || start_height || int32_t || The last block received by the emitting node<br />
|-<br />
|colspan="4"| Fields below require version ≥ 70001<br />
|-<br />
| 1 || relay || bool || Whether the remote peer should announce relayed transactions or not, see [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037]<br />
|}<br />
<br />
A "verack" packet shall be sent if the version packet was accepted.<br />
<br />
The following services are currently assigned:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 1 || NODE_NETWORK || This node can be asked for full blocks instead of just headers.<br />
|-<br />
| 2 || NODE_GETUTXO || See [https://github.com/bitcoin/bips/blob/master/bip-0064.mediawiki BIP 0064]<br />
|-<br />
| 4 || NODE_BLOOM || See [https://github.com/bitcoin/bips/blob/master/bip-0111.mediawiki BIP 0111]<br />
|}<br />
<br />
Hexdump example of version message (OBSOLETE EXAMPLE: This example lacks a checksum and user-agent):<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....<br />
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........<br />
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............<br />
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................<br />
0040 20 8D 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,<br />
0060 3A B4 57 13 00 55 81 01 00 :.W..U...<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
55 00 00 00 - Payload is 85 bytes long<br />
- No checksum in version message until 20 February 2012. See https://bitcointalk.org/index.php?topic=55852.0<br />
Version message:<br />
9C 7C 00 00 - 31900 (version 0.3.19)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
E6 15 10 4D 00 00 00 00 - Mon Dec 20 21:50:14 EST 2010<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 20 8D - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D - Sender address info - see Network Address<br />
DD 9D 20 2C 3A B4 57 13 - Node random unique ID<br />
00 - "" sub-version string (string is 0 bytes long)<br />
55 81 01 00 - Last block sending node has is block #98645<br />
</pre><br />
<br />
And here's a modern (60002) protocol version client advertising itself to a local peer...<br />
<br />
Newer protocol includes the checksum now, this is from a mainline (satoshi) client during <br />
an outgoing connection to another local client, notice that it does not fill out the <br />
address information at all when the source or destination is "unroutable".<br />
<br />
<pre><br />
<br />
0000 f9 be b4 d9 76 65 72 73 69 6f 6e 00 00 00 00 00 ....version.....<br />
0010 64 00 00 00 35 8d 49 32 62 ea 00 00 01 00 00 00 d...5.I2b.......<br />
0020 00 00 00 00 11 b2 d0 50 00 00 00 00 01 00 00 00 .......P........<br />
0030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ff ff ................<br />
0040 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 00 00 00 00 ff ff 00 00 00 00 00 00 ................<br />
0060 3b 2e b3 5d 8c e6 17 65 0f 2f 53 61 74 6f 73 68 ;..]...e./Satosh<br />
0070 69 3a 30 2e 37 2e 32 2f c0 3e 03 00 i:0.7.2/.>..<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
64 00 00 00 - Payload is 100 bytes long<br />
3B 64 8D 5A - payload checksum<br />
<br />
Version message:<br />
62 EA 00 00 - 60002 (protocol version 60002)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
11 B2 D0 50 00 00 00 00 - Tue Dec 18 10:12:33 PST 2012<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Sender address info - see Network Address<br />
3B 2E B3 5D 8C E6 17 65 - Node ID<br />
0F 2F 53 61 74 6F 73 68 69 3A 30 2E 37 2E 32 2F - "/Satoshi:0.7.2/" sub-version string (string is 15 bytes long)<br />
C0 3E 03 00 - Last block sending node has is block #212672<br />
</pre><br />
<br />
=== verack ===<br />
<br />
The ''verack'' message is sent in reply to ''[[#version|version]]''. This message consists of only a [[#Message structure|message header]] with the command string "verack".<br />
<br />
Hexdump of the verack message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......<br />
0010 00 00 00 00 5D F6 E0 E2 ........<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 61 63 6B 00 00 00 00 00 00 - "verack" command<br />
00 00 00 00 - Payload is 0 bytes long<br />
5D F6 E0 E2 - Checksum<br />
</pre><br />
<br />
=== addr ===<br />
<br />
Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours<br />
<br />
Payload:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of address entries (max: 1000)<br />
|-<br />
| 34 x count || addr_list || (uint32_t + [[#Network address|net_addr]])[] || Address of other nodes on the network. version < 209 will only read the first one. The uint32_t is a timestamp (see note below).<br />
|}<br />
<br />
'''Note''': Starting version 31402, addresses are prefixed with a timestamp. If no timestamp is present, the addresses should not be relayed to other peers, unless it is indeed confirmed they are up.<br />
<br />
Hexdump example of ''addr'' message:<br />
<pre><br />
0000 F9 BE B4 D9 61 64 64 72 00 00 00 00 00 00 00 00 ....addr........<br />
0010 1F 00 00 00 ED 52 39 9B 01 E2 15 10 4D 01 00 00 .....R9.....M...<br />
0020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF ................<br />
0030 FF 0A 00 00 01 20 8D ..... .<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
61 64 64 72 00 00 00 00 00 00 00 00 - "addr"<br />
1F 00 00 00 - payload is 31 bytes long<br />
ED 52 39 9B - checksum of payload<br />
<br />
Payload:<br />
01 - 1 address in this message<br />
<br />
Address:<br />
E2 15 10 4D - Mon Dec 20 21:50:10 EST 2010 (only when version is >= 31402)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK service - see version message)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv4: 10.0.0.1, IPv6: ::ffff:10.0.0.1 (IPv4-mapped IPv6 address)<br />
20 8D - port 8333<br />
</pre><br />
<br />
=== inv ===<br />
<br />
Allows a node to advertise its knowledge of one or more objects. It can be received unsolicited, or in reply to ''getblocks''.<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getdata ===<br />
<br />
getdata is used in response to inv, to retrieve the content of a specific object, and is usually sent after receiving an ''inv'' packet, after filtering known elements. It can be used to retrieve transactions, but only if they are in the memory pool or relay set - arbitrary access to transactions in the chain is not allowed to avoid having clients start to depend on nodes having full transaction indexes (which modern nodes do not).<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== notfound ===<br />
<br />
notfound is a response to a getdata, sent if any requested data items could not be relayed, for example, because the requested transaction was not in the memory pool or relay set.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getblocks ===<br />
<br />
Return an ''inv'' packet containing the list of blocks starting right after the last known hash in the block locator object, up to hash_stop or 500 blocks, whichever comes first. <br />
<br />
The locator hashes are processed by a node in the order as they appear in the message. If a block hash is found in the node's main chain, the list of its children is returned back via the ''inv'' message and the remaining locators are ignored, no matter if the requested limit was reached, or not.<br />
<br />
To receive the next blocks hashes, one needs to issue getblocks again with a new block locator object. Keep in mind that some clients may provide blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block; set to zero to get as many blocks as possible (500)<br />
|}<br />
<br />
To create the block locator hashes, keep pushing hashes until you go back to the genesis block. After pushing 10 hashes back, the step backwards doubles every loop:<br />
<br />
<pre><br />
// From libbitcoin which is under AGPL<br />
std::vector<size_t> block_locator_indexes(size_t top_height)<br />
{<br />
std::vector<size_t> indexes;<br />
<br />
// Modify the step in the iteration.<br />
int64_t step = 1;<br />
<br />
// Start at the top of the chain and work backwards.<br />
for (auto index = (int64_t)top_height; index > 0; index -= step)<br />
{<br />
// Push top 10 indexes first, then back off exponentially.<br />
if (indexes.size() >= 10)<br />
step *= 2;<br />
<br />
indexes.push_back((size_t)index);<br />
}<br />
<br />
// Push the genesis block index.<br />
indexes.push_back(0);<br />
return indexes;<br />
}<br />
</pre><br />
<br />
Note that it is allowed to send in fewer known hashes down to a minimum of just one hash. However, the purpose of the block locator object is to detect a wrong branch in the caller's main chain. If the peer detects that you are off the main chain, it will send in block hashes which are earlier than your last known block. So if you just send in your last known hash and it is off the main chain, the peer starts over at block #1.<br />
<br />
=== getheaders ===<br />
<br />
Return a ''headers'' packet containing the headers of blocks starting right after the last known hash in the block locator object, up to hash_stop or 2000 blocks, whichever comes first. To receive the next block headers, one needs to issue getheaders again with a new block locator object. The ''getheaders'' command is used by thin clients to quickly download the block chain where the contents of the transactions would be irrelevant (because they are not ours). Keep in mind that some clients may provide headers of blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block header; set to zero to get as many blocks as possible (2000)<br />
|}<br />
<br />
For the block locator object in this packet, the same rules apply as for the [[Protocol_documentation#getblocks|getblocks]] packet.<br />
<br />
=== tx ===<br />
<br />
''tx'' describes a bitcoin transaction, in reply to ''[[#getdata|getdata]]''<br />
<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Transaction data format version (note, this is signed)<br />
|-<br />
| 1+ || tx_in count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction inputs<br />
|-<br />
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins<br />
|-<br />
| 1+ || tx_out count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction outputs<br />
|-<br />
| 9+ || tx_out || tx_out[] || A list of 1 or more transaction outputs or destinations for coins<br />
|-<br />
| 4 || lock_time || uint32_t || The block number or timestamp at which this transaction is unlocked:<br />
{|class="wikitable"<br />
! Value !! Description<br />
|-<br />
| 0 || Not locked<br />
|-<br />
| < 500000000 || Block number at which this transaction is unlocked<br />
|-<br />
| >= 500000000 || UNIX timestamp at which this transaction is unlocked<br />
|}<br />
If all TxIn inputs have final (0xffffffff) sequence numbers then lock_time is irrelevant. Otherwise, the transaction may not be added to a block until after lock_time (see [[NLockTime]]).<br />
<br />
|}<br />
<br />
TxIn consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 36 || previous_output || outpoint || The previous output transaction reference, as an OutPoint structure<br />
|-<br />
| 1+ || script length || [[Protocol_documentation#Variable_length_integer|var_int]] || The length of the signature script<br />
|-<br />
| ? || signature script || uchar[] || Computational Script for confirming transaction authorization<br />
|-<br />
| 4 || [http://bitcoin.stackexchange.com/q/2025/323 sequence] || uint32_t || Transaction version as defined by the sender. Intended for "replacement" of transactions when information is updated before inclusion into a block.<br />
|}<br />
<br />
The OutPoint structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 32 || hash || char[32] || The hash of the referenced transaction.<br />
|-<br />
| 4 || index || uint32_t || The index of the specific output in the transaction. The first output is 0, etc.<br />
|}<br />
<br />
The Script structure consists of a series of pieces of information and operations related to the value of the transaction.<br />
<br />
(Structure to be expanded in the future… see script.h and script.cpp and [[Script]] for more information)<br />
<br />
The TxOut structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || value || int64_t || Transaction Value<br />
|-<br />
| 1+ || pk_script length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the pk_script<br />
|-<br />
| ? || pk_script || uchar[] || Usually contains the public key as a Bitcoin script setting up conditions to claim this output.<br />
|}<br />
<br />
Example ''tx'' message:<br />
<pre><br />
000000 F9 BE B4 D9 74 78 00 00 00 00 00 00 00 00 00 00 ....tx..........<br />
000010 02 01 00 00 E2 93 CD BE 01 00 00 00 01 6D BD DB .............m..<br />
000020 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D 12 66 E9 .[...Q........f.<br />
000030 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29 00 00 00 .;P......j.6)...<br />
000040 00 8B 48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 ..H0E.!..X..r...<br />
000050 C7 36 7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A .6zz%;..R#...h.:<br />
000060 59 23 3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 Y#?E.W... Y.....<br />
000070 0E 41 83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D .A.z.X.z...XN...<br />
000080 35 BD 96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF 5...6..;...A....<br />
000090 C9 7E F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 .~.6.m...@..!...<br />
0000A0 2A CD 2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC *.+..].}Y... ...<br />
0000B0 4E 02 53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F N.S..=7.o...Q...<br />
0000C0 14 04 2F 46 61 4A 4C 70 C0 F1 4B EF F5 FF FF FF ../FaJLp..K.....<br />
0000D0 FF 02 40 4B 4C 00 00 00 00 00 19 76 A9 14 1A A0 ..@KL......v....<br />
0000E0 CD 1C BE A6 E7 45 8A 7A BA D5 12 A9 D9 EA 1A FB .....E.z........<br />
0000F0 22 5E 88 AC 80 FA E9 C7 00 00 00 00 19 76 A9 14 "^...........v..<br />
000100 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E FD A0 B7 ..[.Cj.....H^...<br />
000110 8B 4E CC 52 88 AC 00 00 00 00 .N.R......<br />
<br />
<br />
Message header:<br />
F9 BE B4 D9 - main network magic bytes<br />
74 78 00 00 00 00 00 00 00 00 00 00 - "tx" command<br />
02 01 00 00 - payload is 258 bytes long<br />
E2 93 CD BE - checksum of payload<br />
<br />
Transaction:<br />
01 00 00 00 - version<br />
<br />
Inputs:<br />
01 - number of transaction inputs<br />
<br />
Input 1:<br />
6D BD DB 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D - previous output (outpoint)<br />
12 66 E9 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29<br />
00 00 00 00<br />
<br />
8B - script is 139 bytes long<br />
<br />
48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 C7 36 - signature script (scriptSig)<br />
7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A 59 23<br />
3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 0E 41<br />
83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D 35 BD<br />
96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF C9 7E<br />
F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 2A CD<br />
2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC 4E 02<br />
53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F 14 04<br />
2F 46 61 4A 4C 70 C0 F1 4B EF F5<br />
<br />
FF FF FF FF - sequence<br />
<br />
Outputs:<br />
02 - 2 Output Transactions<br />
<br />
Output 1:<br />
40 4B 4C 00 00 00 00 00 - 0.05 BTC (5000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 1A A0 CD 1C BE A6 E7 45 8A 7A BA D5 12 - pk_script<br />
A9 D9 EA 1A FB 22 5E 88 AC<br />
<br />
Output 2:<br />
80 FA E9 C7 00 00 00 00 - 33.54 BTC (3354000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E - pk_script<br />
FD A0 B7 8B 4E CC 52 88 AC<br />
<br />
Locktime:<br />
00 00 00 00 - lock time<br />
</pre><br />
<br />
=== block ===<br />
<br />
The '''block''' message is sent in response to a getdata message which requests transaction information from a block hash.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A Unix timestamp recording when this block was created (Currently limited to dates before the year 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated [[Difficulty|difficulty target]] being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| ? || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries<br />
|-<br />
| ? || txns || tx[] || Block transactions, in format of "tx" command<br />
|}<br />
<br />
The SHA256 hash that identifies each block (and which must have a run of 0 bits) is calculated from the first 6 fields of this structure (version, prev_block, merkle_root, timestamp, bits, nonce, and standard SHA256 padding, making two 64-byte chunks in all) and ''not'' from the complete block. To calculate the hash, only two chunks need to be processed by the SHA256 algorithm. Since the ''nonce'' field is in the second chunk, the first chunk stays constant during mining and therefore only the second chunk needs to be processed. However, a Bitcoin hash is the hash of the hash, so two SHA256 rounds are needed for each mining iteration.<br />
See [[Block hashing algorithm]] for details and an example.<br />
<br />
=== headers ===<br />
<br />
The ''headers'' packet returns block headers in response to a ''getheaders'' packet. <br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of block headers<br />
|-<br />
| 81x? || headers || [[Protocol_documentation#Block_Headers|block_header]][] || [[Protocol_documentation#Block_Headers|Block headers]]<br />
|}<br />
<br />
Note that the block headers in this packet include a transaction count (a var_int, so there can be more than 81 bytes per header) as opposed to the block headers that are hashed by miners.<br />
<br />
=== getaddr ===<br />
<br />
The getaddr message sends a request to a node asking for information about known active peers to help with finding potential nodes in the network. The response to receiving this message is to transmit one or more addr messages with one or more peers from a database of known active peers. The typical presumption is that a node is likely to be active if it has been sending a message within the last three hours.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
=== mempool ===<br />
<br />
The mempool message sends a request to a node asking for information about transactions it has verified but which have not yet confirmed. The response to receiving this message is an inv message containing the transaction hashes for all the transactions in the node's mempool.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
It is specified in [https://github.com/bitcoin/bips/blob/master/bip-0035.mediawiki BIP 35]. Since [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 37], if a [[Protocol_documentation#filterload.2C_filteradd.2C_filterclear.2C_merkleblock|bloom filter]] is loaded, only transactions matching the filter are replied.<br />
<br />
=== checkorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== submitorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== reply ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== ping ===<br />
<br />
The ''ping'' message is sent primarily to confirm that the TCP/IP connection is still valid. An error in transmission is presumed to be a closed connection and the address is removed as a current peer.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || random nonce<br />
|}<br />
<br />
=== pong ===<br />
<br />
The ''pong'' message is sent in response to a ''ping'' message. In modern protocol versions, a ''pong'' response is generated using a nonce included in the ping.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || nonce from ping<br />
|}<br />
<br />
<br />
=== reject===<br />
<br />
The ''reject'' message is sent when messages are rejected.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || message || var_str || type of message rejected<br />
|-<br />
| 1 || ccode || char || code relating to rejected message<br />
|-<br />
| 1+ || reason || var_str || text version of reason for rejection<br />
|-<br />
| 0+ || data || char || Optional extra data provided by some errors. Currently, all errors which provide this field fill it with the TXID or block header hash of the object being rejected, so the field is 32 bytes.<br />
|}<br />
<br />
CCodes<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0x01 || REJECT_MALFORMED|| <br />
|-<br />
| 0x10 || REJECT_INVALID ||<br />
|-<br />
| 0x11 || REJECT_OBSOLETE ||<br />
|-<br />
| 0x12 || REJECT_DUPLICATE ||<br />
|-<br />
| 0x40 || REJECT_NONSTANDARD ||<br />
|-<br />
| 0x41 || REJECT_DUST ||<br />
|-<br />
| 0x42 || REJECT_INSUFFICIENTFEE ||<br />
|-<br />
| 0x43 || REJECT_CHECKPOINT ||<br />
|}<br />
<br />
=== filterload, filteradd, filterclear, merkleblock ===<br />
<br />
These messages are related to Bloom filtering of connections and are defined in [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037].<br />
<br />
<br />
The <code>filterload</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || filter || uint8_t[] || The filter itself is simply a bit field of arbitrary byte-aligned size. The maximum size is 36,000 bytes.<br />
|-<br />
| 4 || nHashFuncs || uint32_t || The number of hash functions to use in this filter. The maximum value allowed in this field is 50.<br />
|-<br />
| 4 || nTweak || uint32_t || A random value to add to the seed value in the hash function used by the bloom filter.<br />
|-<br />
| 1 || nFlags || uint8_t || A set of flags that control how matched items are added to the filter.<br />
|}<br />
<br />
See below for a description of the Bloom filter algorithm and how to select nHashFuncs and filter size for a desired false positive rate.<br />
<br />
Upon receiving a <code>filterload</code> command, the remote peer will immediately restrict the broadcast transactions it announces (in inv packets) to transactions matching the filter, where the matching algorithm is specified below. The flags control the update behaviour of the matching algorithm.<br />
<br />
The <code>filteradd</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || data || uint8_t[] || The data element to add to the current filter.<br />
|}<br />
<br />
The data field must be smaller than or equal to 520 bytes in size (the maximum size of any potentially matched object).<br />
<br />
The given data element will be added to the Bloom filter. A filter must have been previously provided using <code>filterload</code>. This command is useful if a new key or script is added to a clients wallet whilst it has connections to the network open, it avoids the need to re-calculate and send an entirely new filter to every peer (though doing so is usually advisable to maintain anonymity).<br />
<br />
The <code>filterclear</code> command has no arguments at all.<br />
<br />
After a filter has been set, nodes don't merely stop announcing non-matching transactions, they can also serve filtered blocks. A filtered block is defined by the <code>merkleblock</code> message and is defined like this:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information, based upon the software version creating this block (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Limited to 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 4 || total_transactions || uint32_t || Number of transactions in the block (including unmatched ones)<br />
|-<br />
| ? || hashes || uint256[] || hashes in depth-first order (including standard varint size prefix)<br />
|-<br />
| ? || flags || byte[] || flag bits, packed per 8 in a byte, least significant bit first (including standard varint size prefix)<br />
|}<br />
<br />
=== alert ===<br />
<br />
'''Note:''' Support for alert messages has been removed from bitcoin core in March 2016. Read more [https://github.com/bitcoin/bitcoin/pull/7692 here]<br />
<br />
<br />
An '''alert''' is sent between nodes to send a general notification message throughout the network. If the alert can be confirmed with the signature as having come from the core development group of the Bitcoin software, the message is suggested to be displayed for end-users. Attempts to perform transactions, particularly automated transactions through the client, are suggested to be halted. The text in the Message string should be relayed to log files and any user interfaces.<br />
<br />
Alert format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || payload || uchar[] || Serialized alert payload<br />
|-<br />
| ? || signature || uchar[] || An ECDSA signature of the message<br />
|}<br />
<br />
The developers of Satoshi's client use this public key for signing alerts:<br />
04fc9702847840aaf195de8442ebecedf5b095cdbb9bc716bda9110971b28a49e0ead8564ff0db22209e0374782c093bb899692d524e9d6a6956e7c5ecbcd68284<br />
(hash) 1AGRxqDa5WjUKBwHB9XYEjmkv1ucoUUy1s<br />
<br />
The payload is serialized into a uchar[] to ensure that versions using incompatible alert formats can still relay alerts among one another. The current alert payload format is:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || Version || int32_t || Alert format version<br />
|-<br />
| 8 || RelayUntil || int64_t || The timestamp beyond which nodes should stop relaying this alert<br />
|-<br />
| 8 || Expiration || int64_t || The timestamp beyond which this alert is no longer in effect and should be ignored<br />
|-<br />
| 4 || ID || int32_t || A unique ID number for this alert<br />
|-<br />
| 4 || Cancel || int32_t || All alerts with an ID number less than or equal to this number should be cancelled: deleted and not accepted in the future<br />
|-<br />
| ? || setCancel || set<int32_t> || All alert IDs contained in this set should be cancelled as above<br />
|-<br />
| 4 || MinVer || int32_t || This alert only applies to versions greater than or equal to this version. Other versions should still relay it.<br />
|-<br />
| 4 || MaxVer || int32_t || This alert only applies to versions less than or equal to this version. Other versions should still relay it.<br />
|-<br />
| ? || setSubVer || set<string> || If this set contains any elements, then only nodes that have their subVer contained in this set are affected by the alert. Other versions should still relay it.<br />
|-<br />
| 4 || Priority || int32_t || Relative priority compared to other alerts<br />
|-<br />
| ? || Comment || string || A comment on the alert that is not displayed<br />
|-<br />
| ? || StatusBar || string || The alert message that is displayed to the user<br />
|-<br />
| ? || Reserved || string || Reserved<br />
|}<br />
<br />
Note: '''set<''type''>''' in the table above is a [[#Variable length integer | variable length integer]] followed by the number of fields of the given ''type'' (either int32_t or [[#Variable length string | variable length string]])<br />
<br />
Sample alert (no message header):<br />
73010000003766404f00000000b305434f00000000f2030000f1030000001027000048ee0000<br />
0064000000004653656520626974636f696e2e6f72672f666562323020696620796f75206861<br />
76652074726f75626c6520636f6e6e656374696e672061667465722032302046656272756172<br />
79004730450221008389df45f0703f39ec8c1cc42c13810ffcae14995bb648340219e353b63b<br />
53eb022009ec65e1c1aaeec1fd334c6b684bde2b3f573060d5b70c3a46723326e4e8a4f1<br />
<br />
Version: 1<br />
RelayUntil: 1329620535<br />
Expiration: 1329792435<br />
ID: 1010<br />
Cancel: 1009<br />
setCancel: <empty><br />
MinVer: 10000<br />
MaxVer: 61000<br />
setSubVer: <empty><br />
Priority: 100<br />
Comment: <empty><br />
StatusBar: "See bitcoin.org/feb20 if you have trouble connecting after 20 February"<br />
Reserved: <empty><br />
<br />
=== sendheaders ===<br />
<br />
Request for Direct headers announcement. <br />
<br />
Upon receipt of this message, the node is be permitted, but not required, to announce new blocks by '''headers''' command (instead of '''inv''' command).<br />
<br />
This message is supported by the protocol version >= 70012 or Bitcoin Core version >= 0.12.0.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0130.mediawiki BIP 130] for more information.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
<br />
=== feefilter ===<br />
<br />
The payload is always 8 bytes long and it encodes 64 bit integer value (LSB / little endian) of '''feerate'''.<br />
The value represents a minimal fee and is expressed in satoshis per 1000 bytes.<br />
<br />
Upon receipt of a "feefilter" message, the node will be permitted, but not required, to filter transaction invs for transactions that fall below the feerate provided in the feefilter message interpreted as satoshis per kilobyte.<br />
<br />
The fee filter is additive with a bloom filter for transactions so if an SPV client were to load a bloom filter and send a feefilter message, transactions would only be relayed if they passed both filters.<br />
<br />
Inv's generated from a mempool message are also subject to a fee filter if it exists.<br />
<br />
Feature discovery is enabled by checking protocol version >= 70013<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0133.mediawiki BIP 133] for more information.<br />
<br />
=== sendcmpct ===<br />
<br />
# The sendcmpct message is defined as a message containing a 1-byte integer followed by a 8-byte integer where pchCommand == "sendcmpct".<br />
# The first integer SHALL be interpreted as a boolean (and MUST have a value of either 1 or 0)<br />
# The second integer SHALL be interpreted as a little-endian version number. Nodes sending a sendcmpct message MUST currently set this value to 1.<br />
# Upon receipt of a "sendcmpct" message with the first and second integers set to 1, the node SHOULD announce new blocks by sending a cmpctblock message.<br />
# Upon receipt of a "sendcmpct" message with the first integer set to 0, the node SHOULD NOT announce new blocks by sending a cmpctblock message, but SHOULD announce new blocks by sending invs or headers, as defined by BIP130.<br />
# Upon receipt of a "sendcmpct" message with the second integer set to something other than 1, nodes MUST treat the peer as if they had not received the message (as it indicates the peer will provide an unexpected encoding in <br />
# cmpctblock, and/or other, messages). This allows future versions to send duplicate sendcmpct messages with different versions as a part of a version handshake for future versions.<br />
# Nodes SHOULD check for a protocol version of >= 70014 before sending sendcmpct messages.<br />
# Nodes MUST NOT send a request for a MSG_CMPCT_BLOCK object to a peer before having received a sendcmpct message from that peer.<br />
<br />
This message is only supported by protocol version >= 70014<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== cmpctblock ===<br />
<br />
# The cmpctblock message is defined as as a message containing a serialized [[Protocol_documentation#HeaderAndShortIDs|HeaderAndShortIDs]] message and pchCommand == "cmpctblock".<br />
# Upon receipt of a cmpctblock message after sending a sendcmpct message, nodes SHOULD calculate the [[Protocol_documentation#Short_transaction_ID|short transaction ID]] for each unconfirmed transaction they have available (ie in their mempool) and compare each to each short transaction ID in the cmpctblock message.<br />
# After finding already-available transactions, nodes which do not have all transactions available to reconstruct the full block SHOULD request the missing transactions using a getblocktxn message.<br />
# A node MUST NOT send a cmpctblock message unless they are able to respond to a getblocktxn message which requests every transaction in the block.<br />
# A node MUST NOT send a cmpctblock message without having validated that the header properly commits to each transaction in the block, and properly builds on top of the existing chain with a valid proof-of-work. A node MAY send a cmpctblock before validating that each transaction in the block validly spends existing UTXO set entries.<br />
<br />
This message is only supported by protocol version >= 70014<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== getblocktxn ===<br />
<br />
# The getblocktxn message is defined as as a message containing a serialized [[Protocol_documentation#BlockTransactionsRequest|BlockTransactionsRequest]] message and pchCommand == "getblocktxn".<br />
# Upon receipt of a properly-formatted getblocktxnmessage, nodes which recently provided the sender of such a message a cmpctblock for the block hash identified in this message MUST respond with an appropriate [[Protocol_documentation#blocktxn|blocktxn]] message. Such a blocktxn message MUST contain exactly and only each transaction which is present in the appropriate block at the index specified in the getblocktxn indexes list, in the order requested.<br />
<br />
This message is only supported by protocol version >= 70014<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== blocktxn ===<br />
<br />
# The blocktxn message is defined as as a message containing a serialized [[Protocol_documentation#BlockTransactions|BlockTransactions]] message and pchCommand == "blocktxn".<br />
# Upon receipt of a properly-formatted requested blocktxn message, nodes SHOULD attempt to reconstruct the full block by:<br />
# Taking the prefilledtxn transactions from the original [[Protocol_documentation#cmpctblock|cmpctblock]] and placing them in the marked positions.<br />
# For each short transaction ID from the original [[Protocol_documentation#cmpctblock|cmpctblock]], in order, find the corresponding transaction either from the blocktxn message or from other sources and place it in the first available position in the block.<br />
# Once the block has been reconstructed, it shall be processed as normal, keeping in mind that short transaction IDs are expected to occasionally collide, and that nodes MUST NOT be penalized for such collisions, wherever they appear.<br />
<br />
This message is only supported by protocol version >= 70014<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
== Scripting ==<br />
<br />
See [[script]].<br />
<br />
==See Also==<br />
<br />
* [[Network]]<br />
* [[Protocol rules]]<br />
* [[Hardfork Wishlist]]<br />
* [https://bitcoin.org/en/developer-documentation Developer Documentation on bitcoin.org]<br />
* Bitcoin dissectors for Wireshark: https://github.com/lbotsch/wireshark-bitcoin https://github.com/op-sig/bitcoin-wireshark-dissector<br />
<br />
==References==<br />
<references /><br />
<br />
[[zh-cn:协议说明]]<br />
[[Category:Technical]]<br />
[[Category:Developer]]<br />
<br />
{{Bitcoin Core documentation}}</div>Tonikthttps://en.bitcoin.it/w/index.php?title=Protocol_documentation&diff=61531Protocol documentation2016-09-05T19:07:04Z<p>Tonikt: added a note that alert messages are deprecated</p>
<hr />
<div>This page ''describes'' the behavior of the [[Original Bitcoin client|reference client]]. The Bitcoin protocol is specified by the behavior of the reference client, not by this page. In particular, while this page is quite complete in describing the network protocol, it does not attempt to list all of the rules for block or transaction validity.<br />
<br />
Type names used in this documentation are from the C99 standard.<br />
<br />
For protocol used in mining, see [[getblocktemplate]].<br />
<br />
==Common standards==<br />
<br />
=== Hashes ===<br />
<br />
Usually, when a hash is computed within bitcoin, it is computed twice. Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-256] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when a shorter hash is desirable (for example when creating a bitcoin address).<br />
<br />
Example of double-SHA-256 encoding of string "hello":<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round of sha-256)<br />
9595c9df90075148eb06860365df33584b75bff782a510c6cd4883a419833d50 (second round of sha-256)<br />
<br />
For bitcoin addresses (RIPEMD-160) this would give:<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round is sha-256)<br />
b6a9c8c230722b7c748331a8b450f05566dc7d0f (with ripemd-160)<br />
<br />
=== Merkle Trees ===<br />
<br />
Merkle trees are binary trees of hashes. Merkle trees in bitcoin use a '''double''' SHA-256, the SHA-256 hash of the SHA-256 hash of something.<br />
<br />
If, when forming a row in the tree (other than the root of the tree), it would have an odd number of elements, the final double-hash is duplicated to ensure that the row has an even number of hashes.<br />
<br />
First form the bottom row of the tree with the ordered double-SHA-256 hashes of the byte streams of the transactions in the block.<br />
<br />
Then the row above it consists of half that number of hashes. Each entry is the double-SHA-256 of the 64-byte concatenation of the corresponding two hashes below it in the tree.<br />
<br />
This procedure repeats recursively until we reach a row consisting of just a single double-hash. This is the '''Merkle root''' of the tree.<br />
<br />
For example, imagine a block with three transactions ''a'', ''b'' and ''c''. The Merkle tree is: <br />
<br />
d1 = dhash(a)<br />
d2 = dhash(b)<br />
d3 = dhash(c)<br />
d4 = dhash(c) # a, b, c are 3. that's an odd number, so we take the c twice<br />
<br />
d5 = dhash(d1 concat d2)<br />
d6 = dhash(d3 concat d4)<br />
<br />
d7 = dhash(d5 concat d6)<br />
<br />
where<br />
<br />
dhash(a) = sha256(sha256(a))<br />
<br />
''d7'' is the Merkle root of the 3 transactions in this block.<br />
<br />
Note: Hashes in Merkle Tree displayed in the [[Block Explorer]] are of little-endian notation. For some implementations and [http://www.fileformat.info/tool/hash.htm calculations], the bits need to be reversed before they are hashed, and again after the hashing operation.<br />
<br />
=== Signatures ===<br />
<br />
Bitcoin uses [http://en.wikipedia.org/wiki/Elliptic_curve_cryptography Elliptic Curve] [http://en.wikipedia.org/wiki/Digital_Signature_Algorithm Digital Signature Algorithm] ([http://en.wikipedia.org/wiki/Elliptic_Curve_DSA ECDSA]) to sign transactions. <br />
<br />
For [[ECDSA]] the secp256k1 curve from http://www.secg.org/collateral/sec2_final.pdf is used.<br />
<br />
Public keys (in scripts) are given as 04 <x> <y> where ''x'' and ''y'' are 32 byte big-endian integers representing the coordinates of a point on the curve or in compressed form given as <sign> <x> where <sign> is 0x02 if ''y'' is even and 0x03 if ''y'' is odd.<br />
<br />
Signatures use [http://en.wikipedia.org/wiki/Distinguished_Encoding_Rules DER encoding] to pack the ''r'' and ''s'' components into a single byte stream (this is also what OpenSSL produces by default).<br />
<br />
=== Transaction Verification ===<br />
Transactions are cryptographically signed records that reassign ownership of Bitcoins to new addresses. Transactions have ''inputs'' - records which reference the funds from other previous transactions - and ''outputs'' - records which determine the new owner of the transferred Bitcoins, and which will be referenced as inputs in future transactions as those funds are respent.<br />
<br />
Each ''input'' must have a cryptographic digital signature that unlocks the funds from the prior transaction. Only the person possessing the appropriate [[private key]] is able to create a satisfactory signature; this in effect ensures that funds can only be spent by their owners.<br />
<br />
Each ''output'' determines which Bitcoin address (or other criteria, see [[Script]]) is the recipient of the funds.<br />
<br />
In a transaction, the sum of all inputs must be equal to or greater than the sum of all outputs. If the inputs exceed the outputs, the difference is considered a [[transaction fee]], and is redeemable by whoever first includes the transaction into the block chain.<br />
<br />
A special kind of transaction, called a [[coinbase transaction]], has no inputs. It is created by [[miners]], and there is one coinbase transaction per block. Because each block comes with a reward of newly created Bitcoins (e.g. 50 BTC for the first 210,000 blocks), the first transaction of a block is, with few exceptions, the transaction that grants those coins to their recipient (the miner). In addition to the newly created Bitcoins, the coinbase transaction is also used for assigning the recipient of any transaction fees that were paid within the other transactions being included in the same block. The coinbase transaction can assign the entire reward to a single Bitcoin address, or split it in portions among multiple addresses, just like any other transaction. Coinbase transactions always contain outputs totalling the sum of the block reward plus all transaction fees collected from the other transactions in the same block.<br />
<br />
The [[coinbase transaction]] in block zero cannot be spent. This is due to a quirk of the reference client implementation that would open the potential for a block chain fork if some nodes accepted the spend and others did not<ref>[http://bitcointalk.org/index.php?topic=119645.msg1288552#msg1288552 Block 0 Network Fork]</ref>.<br />
<br />
Most Bitcoin outputs encumber the newly transferred coins with a single ECDSA private key. The actual record saved with inputs and outputs isn't necessarily a key, but a ''script''. Bitcoin uses an interpreted scripting system to determine whether an output's criteria have been satisfied, with which more complex operations are possible, such as outputs that require two ECDSA signatures, or two-of-three-signature schemes. An output that references a single Bitcoin address is a ''typical'' output; an output actually contains this information in the form of a script that requires a single ECDSA signature (see [[OP_CHECKSIG]]). The output script specifies what must be provided to unlock the funds later, and when the time comes in the future to spend the transaction in another input, that input must provide all of the thing(s) that satisfy the requirements defined by the original output script.<br />
<br />
=== Addresses ===<br />
<br />
A bitcoin address is in fact the hash of a ECDSA public key, computed this way:<br />
<br />
Version = 1 byte of 0 (zero); on the test network, this is 1 byte of 111<br />
Key hash = Version concatenated with RIPEMD-160(SHA-256(public key))<br />
Checksum = 1st 4 bytes of SHA-256(SHA-256(Key hash))<br />
Bitcoin Address = Base58Encode(Key hash concatenated with Checksum)<br />
<br />
The Base58 encoding used is home made, and has some differences. Especially, leading zeroes are kept as single zeroes when conversion happens.<br />
<br />
== Common structures ==<br />
<br />
Almost all integers are encoded in little endian. Only IP or port number are encoded big endian.<br />
<br />
=== Message structure ===<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown<br />
|-<br />
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| 4 || length || uint32_t || Length of payload in number of bytes<br />
|-<br />
| 4 || checksum || uint32_t || First 4 bytes of sha256(sha256(payload))<br />
|-<br />
| ? || payload || uchar[] || The actual data<br />
|}<br />
<br />
<br />
Known magic values:<br />
<br />
{|class="wikitable"<br />
! Network !! Magic value !! Sent over wire as<br />
|-<br />
| main || 0xD9B4BEF9 || F9 BE B4 D9<br />
|-<br />
| testnet || 0xDAB5BFFA || FA BF B5 DA<br />
|-<br />
| testnet3 || 0x0709110B || 0B 11 09 07<br />
|-<br />
| namecoin || 0xFEB4BEF9 || F9 BE B4 FE<br />
|}<br />
<br />
=== Variable length integer ===<br />
<br />
Integer can be encoded depending on the represented value to save space.<br />
Variable length integers always precede an array/vector of a type of data that may vary in length.<br />
Longer numbers are encoded in little endian.<br />
<br />
{|class="wikitable"<br />
! Value !! Storage length !! Format<br />
|-<br />
| < 0xFD || 1 || uint8_t<br />
|-<br />
| <= 0xFFFF || 3 || 0xFD followed by the length as uint16_t<br />
|-<br />
| <= 0xFFFF FFFF || 5 || 0xFE followed by the length as uint32_t<br />
|-<br />
| - || 9 || 0xFF followed by the length as uint64_t<br />
|}<br />
<br />
If you're reading the Satoshi client code (BitcoinQT) it refers to this encoding as a "CompactSize". Modern BitcoinQT also has the CVarInt class which implements an even more compact integer for the purpose of local storage (which is incompatible with "CompactSize" described here). CVarInt is not a part of the protocol.<br />
<br />
=== Variable length string ===<br />
<br />
Variable length string can be stored using a variable length integer followed by the string itself.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the string<br />
|-<br />
| ? || string || char[] || The string itself (can be empty)<br />
|}<br />
<br />
=== Network address ===<br />
<br />
When a network address is needed somewhere, this structure is used. Network addresses are not prefixed with a timestamp in the version message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || time || uint32 || the Time (version >= 31402). '''Not present in version message.'''<br />
|-<br />
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]<br />
|-<br />
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The original client only supported IPv4 and only read the last 4 bytes to get the IPv4 address. However, the IPv4 address is written into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]<br />
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).<br />
|-<br />
| 2 || port || uint16_t || port number, network byte order<br />
|}<br />
<br />
Hexdump example of Network address structure<br />
<br />
<pre><br />
0000 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0010 00 00 FF FF 0A 00 00 01 20 8D ........ .<br />
<br />
Network address:<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK: see services listed under version command)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv6: ::ffff:a00:1 or IPv4: 10.0.0.1<br />
20 8D - Port 8333<br />
</pre><br />
<br />
=== Inventory Vectors ===<br />
<br />
Inventory vectors are used for notifying other nodes about objects they have or data which is being requested.<br />
<br />
Inventory vectors consist of the following data format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || type || uint32_t || Identifies the object type linked to this inventory<br />
|-<br />
| 32 || hash || char[32] || Hash of the object<br />
|}<br />
<br />
<br />
The object type is currently defined as one of the following possibilities:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0 || ERROR || Any data of with this number may be ignored<br />
|-<br />
| 1 || MSG_TX || Hash is related to a transaction<br />
|-<br />
| 2 || MSG_BLOCK || Hash is related to a data block<br />
|-<br />
| 3 || MSG_FILTERED_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a merkleblock message rather than a block message; this only works if a bloom filter has been set.<br />
|-<br />
| 4 || MSG_CMPCT_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a cmpctblock message. See BIP 152 for more info.<br />
|}<br />
<br />
Other Data Type values are considered reserved for future implementations.<br />
<br />
=== Block Headers ===<br />
<br />
Block headers are sent in a headers packet in response to a getheaders message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Will overflow in 2106<ref>https://en.wikipedia.org/wiki/Unix_time#Notable_events_in_Unix_time</ref>)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 1 || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries, this value is always 0<br />
|}<br />
<br />
cf. [[Block hashing algorithm]]<br />
<br />
=== Differential encoding === <br />
Several uses of CompactSize below are "differentially encoded". For these, instead of using raw indexes, the number encoded is the difference between the current index and the previous index, minus one. For example, a first index of 0 implies a real index of 0, a second index of 0 thereafter refers to a real index of 1, etc.<br />
<br />
=== PrefilledTransaction ===<br />
<br />
A PrefilledTransaction structure is used in HeaderAndShortIDs to provide a list of a few transactions explicitly.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| index || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1, 3 bytes || Compact Size, differentially encoded since the last PrefilledTransaction in a list || The index into the block at which this transaction is<br />
|-<br />
| tx || Transaction || variable || As encoded in [[Protocol_documentation#tx|tx messages]] || The transaction which is in the block at index index.<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== HeaderAndShortIDs ===<br />
<br />
A HeaderAndShortIDs structure is used to relay a block header, the short transactions IDs used for matching already-available transactions, and a select few transactions which we expect a peer may be missing.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| header || Block header || 80 bytes || First 80 bytes of the block as defined by the encoding used by "block" messages || The header of the block being provided<br />
|-<br />
| nonce || uint64_t || 8 bytes || Little Endian || A nonce for use in short transaction ID calculations<br />
|-<br />
| shortids_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of short transaction IDs in shortids (ie block tx count - prefilledtxn_length)<br />
|-<br />
| shortids || List of 6-byte integers || 6*shortids_length bytes || Little Endian || The [[Protocol_documentation#Short_transaction_ID|short transaction IDs]] calculated from the transactions which were not provided explicitly in prefilledtxn<br />
|-<br />
| prefilledtxn_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of prefilled transactions in prefilledtxn (ie block tx count - shortids_length)<br />
|-<br />
| prefilledtxn || List of PrefilledTransactions || variable size*prefilledtxn_length || As defined by [[Protocol_documentation#PrefilledTransaction|PrefilledTransaction]] definition, above || Used to provide the coinbase transaction and a select few which we expect a peer may be missing<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== BlockTransactionsRequest ===<br />
<br />
A BlockTransactionsRequest structure is used to list transaction indexes in a block being requested.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| blockhash || Binary blob || 32 bytes || The output from a double-SHA256 of the block header, as used elsewhere || The blockhash of the block which the transactions being requested are in<br />
|-<br />
| indexes_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of transactions being requested<br />
|-<br />
| indexes || List of [[Protocol_documentation#Variable_length_integer|CompactSizes]] || 1 or 3 bytes*indexes_length || [[Protocol_documentation#Differential_encoding|Differentially encoded]] || The indexes of the transactions being requested in the block<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== BlockTransactions ===<br />
<br />
A BlockTransactions structure is used to provide some of the transactions in a block, as requested.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| blockhash || Binary blob || 32 bytes || The output from a double-SHA256 of the block header, as used elsewhere || The blockhash of the block which the transactions being provided are in<br />
|-<br />
| transactions_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of transactions provided<br />
|-<br />
| transactions || List of Transactions || variable || As encoded in [[Protocol_documentation#tx|tx messages]] || The transactions provided<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== Short transaction ID ===<br />
<br />
Short transaction IDs are used to represent a transaction without sending a full 256-bit hash. They are calculated by:<br />
<br />
# single-SHA256 hashing the block header with the nonce appended (in little-endian)<br />
# Running SipHash-2-4 with the input being the transaction ID and the keys (k0/k1) set to the first two little-endian 64-bit integers from the above hash, respectively.<br />
# Dropping the 2 most significant bytes from the SipHash output to make it 6 bytes.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
== Message types ==<br />
<br />
=== version ===<br />
<br />
When a node creates an outgoing connection, it will immediately [[Version Handshake|advertise]] its version. The remote node will respond with its version. No further communication is possible until both peers have exchanged their version.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Identifies protocol version being used by the node<br />
|-<br />
| 8 || services || uint64_t || bitfield of features to be enabled for this connection<br />
|-<br />
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds<br />
|-<br />
| 26 || addr_recv || [[#Network address|net_addr]] || The network address of the node receiving this message<br />
|-<br />
|colspan="4"| Fields below require version ≥ 106<br />
|-<br />
| 26 || addr_from || [[#Network address|net_addr]] || The network address of the node emitting this message<br />
|-<br />
| 8 || nonce || uint64_t || Node random nonce, randomly generated every time a version packet is sent. This nonce is used to detect connections to self.<br />
|-<br />
| ? || user_agent || [[#Variable length string|var_str]] || [https://github.com/bitcoin/bips/blob/master/bip-0014.mediawiki User Agent] (0x00 if string is 0 bytes long)<br />
|-<br />
| 4 || start_height || int32_t || The last block received by the emitting node<br />
|-<br />
|colspan="4"| Fields below require version ≥ 70001<br />
|-<br />
| 1 || relay || bool || Whether the remote peer should announce relayed transactions or not, see [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037]<br />
|}<br />
<br />
A "verack" packet shall be sent if the version packet was accepted.<br />
<br />
The following services are currently assigned:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 1 || NODE_NETWORK || This node can be asked for full blocks instead of just headers.<br />
|}<br />
<br />
Hexdump example of version message (OBSOLETE EXAMPLE: This example lacks a checksum and user-agent):<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....<br />
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........<br />
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............<br />
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................<br />
0040 20 8D 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,<br />
0060 3A B4 57 13 00 55 81 01 00 :.W..U...<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
55 00 00 00 - Payload is 85 bytes long<br />
- No checksum in version message until 20 February 2012. See https://bitcointalk.org/index.php?topic=55852.0<br />
Version message:<br />
9C 7C 00 00 - 31900 (version 0.3.19)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
E6 15 10 4D 00 00 00 00 - Mon Dec 20 21:50:14 EST 2010<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 20 8D - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D - Sender address info - see Network Address<br />
DD 9D 20 2C 3A B4 57 13 - Node random unique ID<br />
00 - "" sub-version string (string is 0 bytes long)<br />
55 81 01 00 - Last block sending node has is block #98645<br />
</pre><br />
<br />
And here's a modern (60002) protocol version client advertising itself to a local peer...<br />
<br />
Newer protocol includes the checksum now, this is from a mainline (satoshi) client during <br />
an outgoing connection to another local client, notice that it does not fill out the <br />
address information at all when the source or destination is "unroutable".<br />
<br />
<pre><br />
<br />
0000 f9 be b4 d9 76 65 72 73 69 6f 6e 00 00 00 00 00 ....version.....<br />
0010 64 00 00 00 35 8d 49 32 62 ea 00 00 01 00 00 00 d...5.I2b.......<br />
0020 00 00 00 00 11 b2 d0 50 00 00 00 00 01 00 00 00 .......P........<br />
0030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ff ff ................<br />
0040 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 00 00 00 00 ff ff 00 00 00 00 00 00 ................<br />
0060 3b 2e b3 5d 8c e6 17 65 0f 2f 53 61 74 6f 73 68 ;..]...e./Satosh<br />
0070 69 3a 30 2e 37 2e 32 2f c0 3e 03 00 i:0.7.2/.>..<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
64 00 00 00 - Payload is 100 bytes long<br />
3B 64 8D 5A - payload checksum<br />
<br />
Version message:<br />
62 EA 00 00 - 60002 (protocol version 60002)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
11 B2 D0 50 00 00 00 00 - Tue Dec 18 10:12:33 PST 2012<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Sender address info - see Network Address<br />
3B 2E B3 5D 8C E6 17 65 - Node ID<br />
0F 2F 53 61 74 6F 73 68 69 3A 30 2E 37 2E 32 2F - "/Satoshi:0.7.2/" sub-version string (string is 15 bytes long)<br />
C0 3E 03 00 - Last block sending node has is block #212672<br />
</pre><br />
<br />
=== verack ===<br />
<br />
The ''verack'' message is sent in reply to ''[[#version|version]]''. This message consists of only a [[#Message structure|message header]] with the command string "verack".<br />
<br />
Hexdump of the verack message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......<br />
0010 00 00 00 00 5D F6 E0 E2 ........<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 61 63 6B 00 00 00 00 00 00 - "verack" command<br />
00 00 00 00 - Payload is 0 bytes long<br />
5D F6 E0 E2 - Checksum<br />
</pre><br />
<br />
=== addr ===<br />
<br />
Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours<br />
<br />
Payload:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of address entries (max: 1000)<br />
|-<br />
| 30x? || addr_list || (uint32_t + [[#Network address|net_addr]])[] || Address of other nodes on the network. version < 209 will only read the first one. The uint32_t is a timestamp (see note below).<br />
|}<br />
<br />
'''Note''': Starting version 31402, addresses are prefixed with a timestamp. If no timestamp is present, the addresses should not be relayed to other peers, unless it is indeed confirmed they are up.<br />
<br />
Hexdump example of ''addr'' message:<br />
<pre><br />
0000 F9 BE B4 D9 61 64 64 72 00 00 00 00 00 00 00 00 ....addr........<br />
0010 1F 00 00 00 ED 52 39 9B 01 E2 15 10 4D 01 00 00 .....R9.....M...<br />
0020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF ................<br />
0030 FF 0A 00 00 01 20 8D ..... .<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
61 64 64 72 00 00 00 00 00 00 00 00 - "addr"<br />
1F 00 00 00 - payload is 31 bytes long<br />
ED 52 39 9B - checksum of payload<br />
<br />
Payload:<br />
01 - 1 address in this message<br />
<br />
Address:<br />
E2 15 10 4D - Mon Dec 20 21:50:10 EST 2010 (only when version is >= 31402)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK service - see version message)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv4: 10.0.0.1, IPv6: ::ffff:10.0.0.1 (IPv4-mapped IPv6 address)<br />
20 8D - port 8333<br />
</pre><br />
<br />
=== inv ===<br />
<br />
Allows a node to advertise its knowledge of one or more objects. It can be received unsolicited, or in reply to ''getblocks''.<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getdata ===<br />
<br />
getdata is used in response to inv, to retrieve the content of a specific object, and is usually sent after receiving an ''inv'' packet, after filtering known elements. It can be used to retrieve transactions, but only if they are in the memory pool or relay set - arbitrary access to transactions in the chain is not allowed to avoid having clients start to depend on nodes having full transaction indexes (which modern nodes do not).<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== notfound ===<br />
<br />
notfound is a response to a getdata, sent if any requested data items could not be relayed, for example, because the requested transaction was not in the memory pool or relay set.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getblocks ===<br />
<br />
Return an ''inv'' packet containing the list of blocks starting right after the last known hash in the block locator object, up to hash_stop or 500 blocks, whichever comes first. <br />
<br />
The locator hashes are processed by a node in the order as they appear in the message. If a block hash is found in the node's main chain, the list of its children is returned back via the ''inv'' message and the remaining locators are ignored, no matter if the requested limit was reached, or not.<br />
<br />
To receive the next blocks hashes, one needs to issue getblocks again with a new block locator object. Keep in mind that some clients may provide blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block; set to zero to get as many blocks as possible (500)<br />
|}<br />
<br />
To create the block locator hashes, keep pushing hashes until you go back to the genesis block. After pushing 10 hashes back, the step backwards doubles every loop:<br />
<br />
<pre><br />
// From libbitcoin which is under AGPL<br />
std::vector<size_t> block_locator_indexes(size_t top_height)<br />
{<br />
std::vector<size_t> indexes;<br />
<br />
// Modify the step in the iteration.<br />
int64_t step = 1;<br />
<br />
// Start at the top of the chain and work backwards.<br />
for (auto index = (int64_t)top_height; index > 0; index -= step)<br />
{<br />
// Push top 10 indexes first, then back off exponentially.<br />
if (indexes.size() >= 10)<br />
step *= 2;<br />
<br />
indexes.push_back((size_t)index);<br />
}<br />
<br />
// Push the genesis block index.<br />
indexes.push_back(0);<br />
return indexes;<br />
}<br />
</pre><br />
<br />
Note that it is allowed to send in fewer known hashes down to a minimum of just one hash. However, the purpose of the block locator object is to detect a wrong branch in the caller's main chain. If the peer detects that you are off the main chain, it will send in block hashes which are earlier than your last known block. So if you just send in your last known hash and it is off the main chain, the peer starts over at block #1.<br />
<br />
=== getheaders ===<br />
<br />
Return a ''headers'' packet containing the headers of blocks starting right after the last known hash in the block locator object, up to hash_stop or 2000 blocks, whichever comes first. To receive the next block headers, one needs to issue getheaders again with a new block locator object. The ''getheaders'' command is used by thin clients to quickly download the block chain where the contents of the transactions would be irrelevant (because they are not ours). Keep in mind that some clients may provide headers of blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block header; set to zero to get as many blocks as possible (2000)<br />
|}<br />
<br />
For the block locator object in this packet, the same rules apply as for the [[Protocol_documentation#getblocks|getblocks]] packet.<br />
<br />
=== tx ===<br />
<br />
''tx'' describes a bitcoin transaction, in reply to ''[[#getdata|getdata]]''<br />
<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Transaction data format version (note, this is signed)<br />
|-<br />
| 1+ || tx_in count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction inputs<br />
|-<br />
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins<br />
|-<br />
| 1+ || tx_out count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction outputs<br />
|-<br />
| 9+ || tx_out || tx_out[] || A list of 1 or more transaction outputs or destinations for coins<br />
|-<br />
| 4 || lock_time || uint32_t || The block number or timestamp at which this transaction is locked:<br />
{|class="wikitable"<br />
! Value !! Description<br />
|-<br />
| 0 || Not locked<br />
|-<br />
| < 500000000 || Block number at which this transaction is locked<br />
|-<br />
| >= 500000000 || UNIX timestamp at which this transaction is locked<br />
|}<br />
If all TxIn inputs have final (0xffffffff) sequence numbers then lock_time is irrelevant. Otherwise, the transaction may not be added to a block until after lock_time (see [[NLockTime]]).<br />
<br />
|}<br />
<br />
TxIn consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 36 || previous_output || outpoint || The previous output transaction reference, as an OutPoint structure<br />
|-<br />
| 1+ || script length || [[Protocol_documentation#Variable_length_integer|var_int]] || The length of the signature script<br />
|-<br />
| ? || signature script || uchar[] || Computational Script for confirming transaction authorization<br />
|-<br />
| 4 || [http://bitcoin.stackexchange.com/q/2025/323 sequence] || uint32_t || Transaction version as defined by the sender. Intended for "replacement" of transactions when information is updated before inclusion into a block.<br />
|}<br />
<br />
The OutPoint structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 32 || hash || char[32] || The hash of the referenced transaction.<br />
|-<br />
| 4 || index || uint32_t || The index of the specific output in the transaction. The first output is 0, etc.<br />
|}<br />
<br />
The Script structure consists of a series of pieces of information and operations related to the value of the transaction.<br />
<br />
(Structure to be expanded in the future… see script.h and script.cpp and [[Script]] for more information)<br />
<br />
The TxOut structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || value || int64_t || Transaction Value<br />
|-<br />
| 1+ || pk_script length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the pk_script<br />
|-<br />
| ? || pk_script || uchar[] || Usually contains the public key as a Bitcoin script setting up conditions to claim this output.<br />
|}<br />
<br />
Example ''tx'' message:<br />
<pre><br />
000000 F9 BE B4 D9 74 78 00 00 00 00 00 00 00 00 00 00 ....tx..........<br />
000010 02 01 00 00 E2 93 CD BE 01 00 00 00 01 6D BD DB .............m..<br />
000020 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D 12 66 E9 .[...Q........f.<br />
000030 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29 00 00 00 .;P......j.6)...<br />
000040 00 8B 48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 ..H0E.!..X..r...<br />
000050 C7 36 7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A .6zz%;..R#...h.:<br />
000060 59 23 3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 Y#?E.W... Y.....<br />
000070 0E 41 83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D .A.z.X.z...XN...<br />
000080 35 BD 96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF 5...6..;...A....<br />
000090 C9 7E F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 .~.6.m...@..!...<br />
0000A0 2A CD 2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC *.+..].}Y... ...<br />
0000B0 4E 02 53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F N.S..=7.o...Q...<br />
0000C0 14 04 2F 46 61 4A 4C 70 C0 F1 4B EF F5 FF FF FF ../FaJLp..K.....<br />
0000D0 FF 02 40 4B 4C 00 00 00 00 00 19 76 A9 14 1A A0 ..@KL......v....<br />
0000E0 CD 1C BE A6 E7 45 8A 7A BA D5 12 A9 D9 EA 1A FB .....E.z........<br />
0000F0 22 5E 88 AC 80 FA E9 C7 00 00 00 00 19 76 A9 14 "^...........v..<br />
000100 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E FD A0 B7 ..[.Cj.....H^...<br />
000110 8B 4E CC 52 88 AC 00 00 00 00 .N.R......<br />
<br />
<br />
Message header:<br />
F9 BE B4 D9 - main network magic bytes<br />
74 78 00 00 00 00 00 00 00 00 00 00 - "tx" command<br />
02 01 00 00 - payload is 258 bytes long<br />
E2 93 CD BE - checksum of payload<br />
<br />
Transaction:<br />
01 00 00 00 - version<br />
<br />
Inputs:<br />
01 - number of transaction inputs<br />
<br />
Input 1:<br />
6D BD DB 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D - previous output (outpoint)<br />
12 66 E9 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29<br />
00 00 00 00<br />
<br />
8B - script is 139 bytes long<br />
<br />
48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 C7 36 - signature script (scriptSig)<br />
7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A 59 23<br />
3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 0E 41<br />
83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D 35 BD<br />
96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF C9 7E<br />
F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 2A CD<br />
2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC 4E 02<br />
53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F 14 04<br />
2F 46 61 4A 4C 70 C0 F1 4B EF F5<br />
<br />
FF FF FF FF - sequence<br />
<br />
Outputs:<br />
02 - 2 Output Transactions<br />
<br />
Output 1:<br />
40 4B 4C 00 00 00 00 00 - 0.05 BTC (5000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 1A A0 CD 1C BE A6 E7 45 8A 7A BA D5 12 - pk_script<br />
A9 D9 EA 1A FB 22 5E 88 AC<br />
<br />
Output 2:<br />
80 FA E9 C7 00 00 00 00 - 33.54 BTC (3354000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E - pk_script<br />
FD A0 B7 8B 4E CC 52 88 AC<br />
<br />
Locktime:<br />
00 00 00 00 - lock time<br />
</pre><br />
<br />
=== block ===<br />
<br />
The '''block''' message is sent in response to a getdata message which requests transaction information from a block hash.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A Unix timestamp recording when this block was created (Currently limited to dates before the year 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated [[Difficulty|difficulty target]] being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| ? || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries<br />
|-<br />
| ? || txns || tx[] || Block transactions, in format of "tx" command<br />
|}<br />
<br />
The SHA256 hash that identifies each block (and which must have a run of 0 bits) is calculated from the first 6 fields of this structure (version, prev_block, merkle_root, timestamp, bits, nonce, and standard SHA256 padding, making two 64-byte chunks in all) and ''not'' from the complete block. To calculate the hash, only two chunks need to be processed by the SHA256 algorithm. Since the ''nonce'' field is in the second chunk, the first chunk stays constant during mining and therefore only the second chunk needs to be processed. However, a Bitcoin hash is the hash of the hash, so two SHA256 rounds are needed for each mining iteration.<br />
See [[Block hashing algorithm]] for details and an example.<br />
<br />
=== headers ===<br />
<br />
The ''headers'' packet returns block headers in response to a ''getheaders'' packet. <br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of block headers<br />
|-<br />
| 81x? || headers || [[Protocol_documentation#Block_Headers|block_header]][] || [[Protocol_documentation#Block_Headers|Block headers]]<br />
|}<br />
<br />
Note that the block headers in this packet include a transaction count (a var_int, so there can be more than 81 bytes per header) as opposed to the block headers that are hashed by miners.<br />
<br />
=== getaddr ===<br />
<br />
The getaddr message sends a request to a node asking for information about known active peers to help with finding potential nodes in the network. The response to receiving this message is to transmit one or more addr messages with one or more peers from a database of known active peers. The typical presumption is that a node is likely to be active if it has been sending a message within the last three hours.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
=== mempool ===<br />
<br />
The mempool message sends a request to a node asking for information about transactions it has verified but which have not yet confirmed. The response to receiving this message is an inv message containing the transaction hashes for all the transactions in the node's mempool.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
It is specified in [https://github.com/bitcoin/bips/blob/master/bip-0035.mediawiki BIP 35]. Since [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 37], if a [[Protocol_documentation#filterload.2C_filteradd.2C_filterclear.2C_merkleblock|bloom filter]] is loaded, only transactions matching the filter are replied.<br />
<br />
=== checkorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== submitorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== reply ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== ping ===<br />
<br />
The ''ping'' message is sent primarily to confirm that the TCP/IP connection is still valid. An error in transmission is presumed to be a closed connection and the address is removed as a current peer.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || random nonce<br />
|}<br />
<br />
=== pong ===<br />
<br />
The ''pong'' message is sent in response to a ''ping'' message. In modern protocol versions, a ''pong'' response is generated using a nonce included in the ping.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || nonce from ping<br />
|}<br />
<br />
<br />
=== reject===<br />
<br />
The ''reject'' message is sent when messages are rejected.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || message || var_str || type of message rejected<br />
|-<br />
| 1 || ccode || char || code relating to rejected message<br />
|-<br />
| 1+ || reason || var_str || text version of reason for rejection<br />
|-<br />
| 0+ || data || char || Optional extra data provided by some errors. Currently, all errors which provide this field fill it with the TXID or block header hash of the object being rejected, so the field is 32 bytes.<br />
|}<br />
<br />
CCodes<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0x01 || REJECT_MALFORMED|| <br />
|-<br />
| 0x10 || REJECT_INVALID ||<br />
|-<br />
| 0x11 || REJECT_OBSOLETE ||<br />
|-<br />
| 0x12 || REJECT_DUPLICATE ||<br />
|-<br />
| 0x40 || REJECT_NONSTANDARD ||<br />
|-<br />
| 0x41 || REJECT_DUST ||<br />
|-<br />
| 0x42 || REJECT_INSUFFICIENTFEE ||<br />
|-<br />
| 0x43 || REJECT_CHECKPOINT ||<br />
|}<br />
<br />
=== filterload, filteradd, filterclear, merkleblock ===<br />
<br />
These messages are related to Bloom filtering of connections and are defined in [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037].<br />
<br />
<br />
The <code>filterload</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || filter || uint8_t[] || The filter itself is simply a bit field of arbitrary byte-aligned size. The maximum size is 36,000 bytes.<br />
|-<br />
| 4 || nHashFuncs || uint32_t || The number of hash functions to use in this filter. The maximum value allowed in this field is 50.<br />
|-<br />
| 4 || nTweak || uint32_t || A random value to add to the seed value in the hash function used by the bloom filter.<br />
|-<br />
| 1 || nFlags || uint8_t || A set of flags that control how matched items are added to the filter.<br />
|}<br />
<br />
See below for a description of the Bloom filter algorithm and how to select nHashFuncs and filter size for a desired false positive rate.<br />
<br />
Upon receiving a <code>filterload</code> command, the remote peer will immediately restrict the broadcast transactions it announces (in inv packets) to transactions matching the filter, where the matching algorithm is specified below. The flags control the update behaviour of the matching algorithm.<br />
<br />
The <code>filteradd</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || data || uint8_t[] || The data element to add to the current filter.<br />
|}<br />
<br />
The data field must be smaller than or equal to 520 bytes in size (the maximum size of any potentially matched object).<br />
<br />
The given data element will be added to the Bloom filter. A filter must have been previously provided using <code>filterload</code>. This command is useful if a new key or script is added to a clients wallet whilst it has connections to the network open, it avoids the need to re-calculate and send an entirely new filter to every peer (though doing so is usually advisable to maintain anonymity).<br />
<br />
The <code>filterclear</code> command has no arguments at all.<br />
<br />
After a filter has been set, nodes don't merely stop announcing non-matching transactions, they can also serve filtered blocks. A filtered block is defined by the <code>merkleblock</code> message and is defined like this:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information, based upon the software version creating this block (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Limited to 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 4 || total_transactions || uint32_t || Number of transactions in the block (including unmatched ones)<br />
|-<br />
| ? || hashes || uint256[] || hashes in depth-first order (including standard varint size prefix)<br />
|-<br />
| ? || flags || byte[] || flag bits, packed per 8 in a byte, least significant bit first (including standard varint size prefix)<br />
|}<br />
<br />
=== alert ===<br />
<br />
'''Note:''' Support for alert messages has been removed from bitcoin core in March 2016. Read more [https://github.com/bitcoin/bitcoin/pull/7692 here]<br />
<br />
<br />
An '''alert''' is sent between nodes to send a general notification message throughout the network. If the alert can be confirmed with the signature as having come from the core development group of the Bitcoin software, the message is suggested to be displayed for end-users. Attempts to perform transactions, particularly automated transactions through the client, are suggested to be halted. The text in the Message string should be relayed to log files and any user interfaces.<br />
<br />
Alert format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || payload || uchar[] || Serialized alert payload<br />
|-<br />
| ? || signature || uchar[] || An ECDSA signature of the message<br />
|}<br />
<br />
The developers of Satoshi's client use this public key for signing alerts:<br />
04fc9702847840aaf195de8442ebecedf5b095cdbb9bc716bda9110971b28a49e0ead8564ff0db22209e0374782c093bb899692d524e9d6a6956e7c5ecbcd68284<br />
(hash) 1AGRxqDa5WjUKBwHB9XYEjmkv1ucoUUy1s<br />
<br />
The payload is serialized into a uchar[] to ensure that versions using incompatible alert formats can still relay alerts among one another. The current alert payload format is:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || Version || int32_t || Alert format version<br />
|-<br />
| 8 || RelayUntil || int64_t || The timestamp beyond which nodes should stop relaying this alert<br />
|-<br />
| 8 || Expiration || int64_t || The timestamp beyond which this alert is no longer in effect and should be ignored<br />
|-<br />
| 4 || ID || int32_t || A unique ID number for this alert<br />
|-<br />
| 4 || Cancel || int32_t || All alerts with an ID number less than or equal to this number should be cancelled: deleted and not accepted in the future<br />
|-<br />
| ? || setCancel || set<int32_t> || All alert IDs contained in this set should be cancelled as above<br />
|-<br />
| 4 || MinVer || int32_t || This alert only applies to versions greater than or equal to this version. Other versions should still relay it.<br />
|-<br />
| 4 || MaxVer || int32_t || This alert only applies to versions less than or equal to this version. Other versions should still relay it.<br />
|-<br />
| ? || setSubVer || set<string> || If this set contains any elements, then only nodes that have their subVer contained in this set are affected by the alert. Other versions should still relay it.<br />
|-<br />
| 4 || Priority || int32_t || Relative priority compared to other alerts<br />
|-<br />
| ? || Comment || string || A comment on the alert that is not displayed<br />
|-<br />
| ? || StatusBar || string || The alert message that is displayed to the user<br />
|-<br />
| ? || Reserved || string || Reserved<br />
|}<br />
<br />
Note: '''set<''type''>''' in the table above is a [[#Variable length integer | variable length integer]] followed by the number of fields of the given ''type'' (either int32_t or [[#Variable length string | variable length string]])<br />
<br />
Sample alert (no message header):<br />
73010000003766404f00000000b305434f00000000f2030000f1030000001027000048ee0000<br />
0064000000004653656520626974636f696e2e6f72672f666562323020696620796f75206861<br />
76652074726f75626c6520636f6e6e656374696e672061667465722032302046656272756172<br />
79004730450221008389df45f0703f39ec8c1cc42c13810ffcae14995bb648340219e353b63b<br />
53eb022009ec65e1c1aaeec1fd334c6b684bde2b3f573060d5b70c3a46723326e4e8a4f1<br />
<br />
Version: 1<br />
RelayUntil: 1329620535<br />
Expiration: 1329792435<br />
ID: 1010<br />
Cancel: 1009<br />
setCancel: <empty><br />
MinVer: 10000<br />
MaxVer: 61000<br />
setSubVer: <empty><br />
Priority: 100<br />
Comment: <empty><br />
StatusBar: "See bitcoin.org/feb20 if you have trouble connecting after 20 February"<br />
Reserved: <empty><br />
<br />
=== sendheaders ===<br />
<br />
Request for Direct headers announcement. <br />
<br />
Upon receipt of this message, the node is be permitted, but not required, to announce new blocks by '''headers''' command (instead of '''inv''' command).<br />
<br />
This message is supported by the protocol version >= 70012 or Bitcoin Core version >= 0.12.0.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0130.mediawiki BIP 130] for more information.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
<br />
=== feefilter ===<br />
<br />
The payload is always 8 bytes long and it encodes 64 bit integer value (LSB / little endian) of '''feerate'''.<br />
The value represents a minimal fee and is expressed in satoshis per 1000 bytes.<br />
<br />
Upon receipt of a "feefilter" message, the node will be permitted, but not required, to filter transaction invs for transactions that fall below the feerate provided in the feefilter message interpreted as satoshis per kilobyte.<br />
<br />
The fee filter is additive with a bloom filter for transactions so if an SPV client were to load a bloom filter and send a feefilter message, transactions would only be relayed if they passed both filters.<br />
<br />
Inv's generated from a mempool message are also subject to a fee filter if it exists.<br />
<br />
Feature discovery is enabled by checking protocol version >= 70013<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0133.mediawiki BIP 133] for more information.<br />
<br />
=== sendcmpct ===<br />
<br />
# The sendcmpct message is defined as a message containing a 1-byte integer followed by a 8-byte integer where pchCommand == "sendcmpct".<br />
# The first integer SHALL be interpreted as a boolean (and MUST have a value of either 1 or 0)<br />
# The second integer SHALL be interpreted as a little-endian version number. Nodes sending a sendcmpct message MUST currently set this value to 1.<br />
# Upon receipt of a "sendcmpct" message with the first and second integers set to 1, the node SHOULD announce new blocks by sending a cmpctblock message.<br />
# Upon receipt of a "sendcmpct" message with the first integer set to 0, the node SHOULD NOT announce new blocks by sending a cmpctblock message, but SHOULD announce new blocks by sending invs or headers, as defined by BIP130.<br />
# Upon receipt of a "sendcmpct" message with the second integer set to something other than 1, nodes MUST treat the peer as if they had not received the message (as it indicates the peer will provide an unexpected encoding in <br />
# cmpctblock, and/or other, messages). This allows future versions to send duplicate sendcmpct messages with different versions as a part of a version handshake for future versions.<br />
# Nodes SHOULD check for a protocol version of >= 70014 before sending sendcmpct messages.<br />
# Nodes MUST NOT send a request for a MSG_CMPCT_BLOCK object to a peer before having received a sendcmpct message from that peer.<br />
<br />
This message is only supported by protocol version >= 70014<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== cmpctblock ===<br />
<br />
# The cmpctblock message is defined as as a message containing a serialized [[Protocol_documentation#HeaderAndShortIDs|HeaderAndShortIDs]] message and pchCommand == "cmpctblock".<br />
# Upon receipt of a cmpctblock message after sending a sendcmpct message, nodes SHOULD calculate the [[Protocol_documentation#Short_transaction_ID|short transaction ID]] for each unconfirmed transaction they have available (ie in their mempool) and compare each to each short transaction ID in the cmpctblock message.<br />
# After finding already-available transactions, nodes which do not have all transactions available to reconstruct the full block SHOULD request the missing transactions using a getblocktxn message.<br />
# A node MUST NOT send a cmpctblock message unless they are able to respond to a getblocktxn message which requests every transaction in the block.<br />
# A node MUST NOT send a cmpctblock message without having validated that the header properly commits to each transaction in the block, and properly builds on top of the existing chain with a valid proof-of-work. A node MAY send a cmpctblock before validating that each transaction in the block validly spends existing UTXO set entries.<br />
<br />
This message is only supported by protocol version >= 70014<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== getblocktxn ===<br />
<br />
# The getblocktxn message is defined as as a message containing a serialized [[Protocol_documentation#BlockTransactionsRequest|BlockTransactionsRequest]] message and pchCommand == "getblocktxn".<br />
# Upon receipt of a properly-formatted getblocktxnmessage, nodes which recently provided the sender of such a message a cmpctblock for the block hash identified in this message MUST respond with an appropriate [[Protocol_documentation#blocktxn|blocktxn]] message. Such a blocktxn message MUST contain exactly and only each transaction which is present in the appropriate block at the index specified in the getblocktxn indexes list, in the order requested.<br />
<br />
This message is only supported by protocol version >= 70014<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== blocktxn ===<br />
<br />
# The blocktxn message is defined as as a message containing a serialized [[Protocol_documentation#BlockTransactions|BlockTransactions]] message and pchCommand == "blocktxn".<br />
# Upon receipt of a properly-formatted requested blocktxn message, nodes SHOULD attempt to reconstruct the full block by:<br />
# Taking the prefilledtxn transactions from the original [[Protocol_documentation#cmpctblock|cmpctblock]] and placing them in the marked positions.<br />
# For each short transaction ID from the original [[Protocol_documentation#cmpctblock|cmpctblock]], in order, find the corresponding transaction either from the blocktxn message or from other sources and place it in the first available position in the block.<br />
# Once the block has been reconstructed, it shall be processed as normal, keeping in mind that short transaction IDs are expected to occasionally collide, and that nodes MUST NOT be penalized for such collisions, wherever they appear.<br />
<br />
This message is only supported by protocol version >= 70014<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
== Scripting ==<br />
<br />
See [[script]].<br />
<br />
==See Also==<br />
<br />
* [[Network]]<br />
* [[Protocol rules]]<br />
* [[Hardfork Wishlist]]<br />
* [https://bitcoin.org/en/developer-documentation Developer Documentation on bitcoin.org]<br />
* Bitcoin dissectors for Wireshark: https://github.com/lbotsch/wireshark-bitcoin https://github.com/op-sig/bitcoin-wireshark-dissector<br />
<br />
==References==<br />
<references /><br />
<br />
[[zh-cn:协议说明]]<br />
[[Category:Technical]]<br />
[[Category:Developer]]<br />
<br />
{{Bitcoin Core documentation}}</div>Tonikthttps://en.bitcoin.it/w/index.php?title=Protocol_documentation&diff=61504Protocol documentation2016-08-25T13:19:46Z<p>Tonikt: /* blocktxn */</p>
<hr />
<div>This page ''describes'' the behavior of the [[Original Bitcoin client|reference client]]. The Bitcoin protocol is specified by the behavior of the reference client, not by this page. In particular, while this page is quite complete in describing the network protocol, it does not attempt to list all of the rules for block or transaction validity.<br />
<br />
Type names used in this documentation are from the C99 standard.<br />
<br />
For protocol used in mining, see [[getblocktemplate]].<br />
<br />
==Common standards==<br />
<br />
=== Hashes ===<br />
<br />
Usually, when a hash is computed within bitcoin, it is computed twice. Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-256] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when a shorter hash is desirable (for example when creating a bitcoin address).<br />
<br />
Example of double-SHA-256 encoding of string "hello":<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round of sha-256)<br />
9595c9df90075148eb06860365df33584b75bff782a510c6cd4883a419833d50 (second round of sha-256)<br />
<br />
For bitcoin addresses (RIPEMD-160) this would give:<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round is sha-256)<br />
b6a9c8c230722b7c748331a8b450f05566dc7d0f (with ripemd-160)<br />
<br />
=== Merkle Trees ===<br />
<br />
Merkle trees are binary trees of hashes. Merkle trees in bitcoin use a '''double''' SHA-256, the SHA-256 hash of the SHA-256 hash of something.<br />
<br />
If, when forming a row in the tree (other than the root of the tree), it would have an odd number of elements, the final double-hash is duplicated to ensure that the row has an even number of hashes.<br />
<br />
First form the bottom row of the tree with the ordered double-SHA-256 hashes of the byte streams of the transactions in the block.<br />
<br />
Then the row above it consists of half that number of hashes. Each entry is the double-SHA-256 of the 64-byte concatenation of the corresponding two hashes below it in the tree.<br />
<br />
This procedure repeats recursively until we reach a row consisting of just a single double-hash. This is the '''Merkle root''' of the tree.<br />
<br />
For example, imagine a block with three transactions ''a'', ''b'' and ''c''. The Merkle tree is: <br />
<br />
d1 = dhash(a)<br />
d2 = dhash(b)<br />
d3 = dhash(c)<br />
d4 = dhash(c) # a, b, c are 3. that's an odd number, so we take the c twice<br />
<br />
d5 = dhash(d1 concat d2)<br />
d6 = dhash(d3 concat d4)<br />
<br />
d7 = dhash(d5 concat d6)<br />
<br />
where<br />
<br />
dhash(a) = sha256(sha256(a))<br />
<br />
''d7'' is the Merkle root of the 3 transactions in this block.<br />
<br />
Note: Hashes in Merkle Tree displayed in the [[Block Explorer]] are of little-endian notation. For some implementations and [http://www.fileformat.info/tool/hash.htm calculations], the bits need to be reversed before they are hashed, and again after the hashing operation.<br />
<br />
=== Signatures ===<br />
<br />
Bitcoin uses [http://en.wikipedia.org/wiki/Elliptic_curve_cryptography Elliptic Curve] [http://en.wikipedia.org/wiki/Digital_Signature_Algorithm Digital Signature Algorithm] ([http://en.wikipedia.org/wiki/Elliptic_Curve_DSA ECDSA]) to sign transactions. <br />
<br />
For [[ECDSA]] the secp256k1 curve from http://www.secg.org/collateral/sec2_final.pdf is used.<br />
<br />
Public keys (in scripts) are given as 04 <x> <y> where ''x'' and ''y'' are 32 byte big-endian integers representing the coordinates of a point on the curve or in compressed form given as <sign> <x> where <sign> is 0x02 if ''y'' is even and 0x03 if ''y'' is odd.<br />
<br />
Signatures use [http://en.wikipedia.org/wiki/Distinguished_Encoding_Rules DER encoding] to pack the ''r'' and ''s'' components into a single byte stream (this is also what OpenSSL produces by default).<br />
<br />
=== Transaction Verification ===<br />
Transactions are cryptographically signed records that reassign ownership of Bitcoins to new addresses. Transactions have ''inputs'' - records which reference the funds from other previous transactions - and ''outputs'' - records which determine the new owner of the transferred Bitcoins, and which will be referenced as inputs in future transactions as those funds are respent.<br />
<br />
Each ''input'' must have a cryptographic digital signature that unlocks the funds from the prior transaction. Only the person possessing the appropriate [[private key]] is able to create a satisfactory signature; this in effect ensures that funds can only be spent by their owners.<br />
<br />
Each ''output'' determines which Bitcoin address (or other criteria, see [[Script]]) is the recipient of the funds.<br />
<br />
In a transaction, the sum of all inputs must be equal to or greater than the sum of all outputs. If the inputs exceed the outputs, the difference is considered a [[transaction fee]], and is redeemable by whoever first includes the transaction into the block chain.<br />
<br />
A special kind of transaction, called a [[coinbase transaction]], has no inputs. It is created by [[miners]], and there is one coinbase transaction per block. Because each block comes with a reward of newly created Bitcoins (e.g. 50 BTC for the first 210,000 blocks), the first transaction of a block is, with few exceptions, the transaction that grants those coins to their recipient (the miner). In addition to the newly created Bitcoins, the coinbase transaction is also used for assigning the recipient of any transaction fees that were paid within the other transactions being included in the same block. The coinbase transaction can assign the entire reward to a single Bitcoin address, or split it in portions among multiple addresses, just like any other transaction. Coinbase transactions always contain outputs totalling the sum of the block reward plus all transaction fees collected from the other transactions in the same block.<br />
<br />
The [[coinbase transaction]] in block zero cannot be spent. This is due to a quirk of the reference client implementation that would open the potential for a block chain fork if some nodes accepted the spend and others did not<ref>[http://bitcointalk.org/index.php?topic=119645.msg1288552#msg1288552 Block 0 Network Fork]</ref>.<br />
<br />
Most Bitcoin outputs encumber the newly transferred coins with a single ECDSA private key. The actual record saved with inputs and outputs isn't necessarily a key, but a ''script''. Bitcoin uses an interpreted scripting system to determine whether an output's criteria have been satisfied, with which more complex operations are possible, such as outputs that require two ECDSA signatures, or two-of-three-signature schemes. An output that references a single Bitcoin address is a ''typical'' output; an output actually contains this information in the form of a script that requires a single ECDSA signature (see [[OP_CHECKSIG]]). The output script specifies what must be provided to unlock the funds later, and when the time comes in the future to spend the transaction in another input, that input must provide all of the thing(s) that satisfy the requirements defined by the original output script.<br />
<br />
=== Addresses ===<br />
<br />
A bitcoin address is in fact the hash of a ECDSA public key, computed this way:<br />
<br />
Version = 1 byte of 0 (zero); on the test network, this is 1 byte of 111<br />
Key hash = Version concatenated with RIPEMD-160(SHA-256(public key))<br />
Checksum = 1st 4 bytes of SHA-256(SHA-256(Key hash))<br />
Bitcoin Address = Base58Encode(Key hash concatenated with Checksum)<br />
<br />
The Base58 encoding used is home made, and has some differences. Especially, leading zeroes are kept as single zeroes when conversion happens.<br />
<br />
== Common structures ==<br />
<br />
Almost all integers are encoded in little endian. Only IP or port number are encoded big endian.<br />
<br />
=== Message structure ===<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown<br />
|-<br />
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| 4 || length || uint32_t || Length of payload in number of bytes<br />
|-<br />
| 4 || checksum || uint32_t || First 4 bytes of sha256(sha256(payload))<br />
|-<br />
| ? || payload || uchar[] || The actual data<br />
|}<br />
<br />
<br />
Known magic values:<br />
<br />
{|class="wikitable"<br />
! Network !! Magic value !! Sent over wire as<br />
|-<br />
| main || 0xD9B4BEF9 || F9 BE B4 D9<br />
|-<br />
| testnet || 0xDAB5BFFA || FA BF B5 DA<br />
|-<br />
| testnet3 || 0x0709110B || 0B 11 09 07<br />
|-<br />
| namecoin || 0xFEB4BEF9 || F9 BE B4 FE<br />
|}<br />
<br />
=== Variable length integer ===<br />
<br />
Integer can be encoded depending on the represented value to save space.<br />
Variable length integers always precede an array/vector of a type of data that may vary in length.<br />
Longer numbers are encoded in little endian.<br />
<br />
{|class="wikitable"<br />
! Value !! Storage length !! Format<br />
|-<br />
| < 0xFD || 1 || uint8_t<br />
|-<br />
| <= 0xFFFF || 3 || 0xFD followed by the length as uint16_t<br />
|-<br />
| <= 0xFFFF FFFF || 5 || 0xFE followed by the length as uint32_t<br />
|-<br />
| - || 9 || 0xFF followed by the length as uint64_t<br />
|}<br />
<br />
If you're reading the Satoshi client code (BitcoinQT) it refers to this encoding as a "CompactSize". Modern BitcoinQT also has the CVarInt class which implements an even more compact integer for the purpose of local storage (which is incompatible with "CompactSize" described here). CVarInt is not a part of the protocol.<br />
<br />
=== Variable length string ===<br />
<br />
Variable length string can be stored using a variable length integer followed by the string itself.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the string<br />
|-<br />
| ? || string || char[] || The string itself (can be empty)<br />
|}<br />
<br />
=== Network address ===<br />
<br />
When a network address is needed somewhere, this structure is used. Network addresses are not prefixed with a timestamp in the version message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || time || uint32 || the Time (version >= 31402). '''Not present in version message.'''<br />
|-<br />
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]<br />
|-<br />
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The original client only supported IPv4 and only read the last 4 bytes to get the IPv4 address. However, the IPv4 address is written into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]<br />
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).<br />
|-<br />
| 2 || port || uint16_t || port number, network byte order<br />
|}<br />
<br />
Hexdump example of Network address structure<br />
<br />
<pre><br />
0000 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0010 00 00 FF FF 0A 00 00 01 20 8D ........ .<br />
<br />
Network address:<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK: see services listed under version command)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv6: ::ffff:a00:1 or IPv4: 10.0.0.1<br />
20 8D - Port 8333<br />
</pre><br />
<br />
=== Inventory Vectors ===<br />
<br />
Inventory vectors are used for notifying other nodes about objects they have or data which is being requested.<br />
<br />
Inventory vectors consist of the following data format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || type || uint32_t || Identifies the object type linked to this inventory<br />
|-<br />
| 32 || hash || char[32] || Hash of the object<br />
|}<br />
<br />
<br />
The object type is currently defined as one of the following possibilities:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0 || ERROR || Any data of with this number may be ignored<br />
|-<br />
| 1 || MSG_TX || Hash is related to a transaction<br />
|-<br />
| 2 || MSG_BLOCK || Hash is related to a data block<br />
|-<br />
| 3 || MSG_FILTERED_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a merkleblock message rather than a block message; this only works if a bloom filter has been set.<br />
|-<br />
| 4 || MSG_CMPCT_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a cmpctblock message. See BIP 152 for more info.<br />
|}<br />
<br />
Other Data Type values are considered reserved for future implementations.<br />
<br />
=== Block Headers ===<br />
<br />
Block headers are sent in a headers packet in response to a getheaders message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Will overflow in 2106<ref>https://en.wikipedia.org/wiki/Unix_time#Notable_events_in_Unix_time</ref>)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 1 || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries, this value is always 0<br />
|}<br />
<br />
cf. [[Block hashing algorithm]]<br />
<br />
=== Differential encoding === <br />
Several uses of CompactSize below are "differentially encoded". For these, instead of using raw indexes, the number encoded is the difference between the current index and the previous index, minus one. For example, a first index of 0 implies a real index of 0, a second index of 0 thereafter refers to a real index of 1, etc.<br />
<br />
=== PrefilledTransaction ===<br />
<br />
A PrefilledTransaction structure is used in HeaderAndShortIDs to provide a list of a few transactions explicitly.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| index || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1, 3 bytes || Compact Size, differentially encoded since the last PrefilledTransaction in a list || The index into the block at which this transaction is<br />
|-<br />
| tx || Transaction || variable || As encoded in [[Protocol_documentation#tx|tx messages]] || The transaction which is in the block at index index.<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== HeaderAndShortIDs ===<br />
<br />
A HeaderAndShortIDs structure is used to relay a block header, the short transactions IDs used for matching already-available transactions, and a select few transactions which we expect a peer may be missing.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| header || Block header || 80 bytes || First 80 bytes of the block as defined by the encoding used by "block" messages || The header of the block being provided<br />
|-<br />
| nonce || uint64_t || 8 bytes || Little Endian || A nonce for use in short transaction ID calculations<br />
|-<br />
| shortids_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of short transaction IDs in shortids (ie block tx count - prefilledtxn_length)<br />
|-<br />
| shortids || List of 6-byte integers || 6*shortids_length bytes || Little Endian || The [[Protocol_documentation#Short_transaction_ID|short transaction IDs]] calculated from the transactions which were not provided explicitly in prefilledtxn<br />
|-<br />
| prefilledtxn_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of prefilled transactions in prefilledtxn (ie block tx count - shortids_length)<br />
|-<br />
| prefilledtxn || List of PrefilledTransactions || variable size*prefilledtxn_length || As defined by [[Protocol_documentation#PrefilledTransaction|PrefilledTransaction]] definition, above || Used to provide the coinbase transaction and a select few which we expect a peer may be missing<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== BlockTransactionsRequest ===<br />
<br />
A BlockTransactionsRequest structure is used to list transaction indexes in a block being requested.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| blockhash || Binary blob || 32 bytes || The output from a double-SHA256 of the block header, as used elsewhere || The blockhash of the block which the transactions being requested are in<br />
|-<br />
| indexes_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of transactions being requested<br />
|-<br />
| indexes || List of [[Protocol_documentation#Variable_length_integer|CompactSizes]] || 1 or 3 bytes*indexes_length || [[Protocol_documentation#Differential_encoding|Differentially encoded]] || The indexes of the transactions being requested in the block<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== BlockTransactions ===<br />
<br />
A BlockTransactions structure is used to provide some of the transactions in a block, as requested.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| blockhash || Binary blob || 32 bytes || The output from a double-SHA256 of the block header, as used elsewhere || The blockhash of the block which the transactions being provided are in<br />
|-<br />
| transactions_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of transactions provided<br />
|-<br />
| transactions || List of Transactions || variable || As encoded in [[Protocol_documentation#tx|tx messages]] || The transactions provided<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== Short transaction ID ===<br />
<br />
Short transaction IDs are used to represent a transaction without sending a full 256-bit hash. They are calculated by:<br />
<br />
# single-SHA256 hashing the block header with the nonce appended (in little-endian)<br />
# Running SipHash-2-4 with the input being the transaction ID and the keys (k0/k1) set to the first two little-endian 64-bit integers from the above hash, respectively.<br />
# Dropping the 2 most significant bytes from the SipHash output to make it 6 bytes.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
== Message types ==<br />
<br />
=== version ===<br />
<br />
When a node creates an outgoing connection, it will immediately [[Version Handshake|advertise]] its version. The remote node will respond with its version. No further communication is possible until both peers have exchanged their version.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Identifies protocol version being used by the node<br />
|-<br />
| 8 || services || uint64_t || bitfield of features to be enabled for this connection<br />
|-<br />
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds<br />
|-<br />
| 26 || addr_recv || [[#Network address|net_addr]] || The network address of the node receiving this message<br />
|-<br />
|colspan="4"| Fields below require version ≥ 106<br />
|-<br />
| 26 || addr_from || [[#Network address|net_addr]] || The network address of the node emitting this message<br />
|-<br />
| 8 || nonce || uint64_t || Node random nonce, randomly generated every time a version packet is sent. This nonce is used to detect connections to self.<br />
|-<br />
| ? || user_agent || [[#Variable length string|var_str]] || [https://github.com/bitcoin/bips/blob/master/bip-0014.mediawiki User Agent] (0x00 if string is 0 bytes long)<br />
|-<br />
| 4 || start_height || int32_t || The last block received by the emitting node<br />
|-<br />
|colspan="4"| Fields below require version ≥ 70001<br />
|-<br />
| 1 || relay || bool || Whether the remote peer should announce relayed transactions or not, see [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037]<br />
|}<br />
<br />
A "verack" packet shall be sent if the version packet was accepted.<br />
<br />
The following services are currently assigned:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 1 || NODE_NETWORK || This node can be asked for full blocks instead of just headers.<br />
|}<br />
<br />
Hexdump example of version message (OBSOLETE EXAMPLE: This example lacks a checksum and user-agent):<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....<br />
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........<br />
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............<br />
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................<br />
0040 20 8D 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,<br />
0060 3A B4 57 13 00 55 81 01 00 :.W..U...<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
55 00 00 00 - Payload is 85 bytes long<br />
- No checksum in version message until 20 February 2012. See https://bitcointalk.org/index.php?topic=55852.0<br />
Version message:<br />
9C 7C 00 00 - 31900 (version 0.3.19)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
E6 15 10 4D 00 00 00 00 - Mon Dec 20 21:50:14 EST 2010<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 20 8D - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D - Sender address info - see Network Address<br />
DD 9D 20 2C 3A B4 57 13 - Node random unique ID<br />
00 - "" sub-version string (string is 0 bytes long)<br />
55 81 01 00 - Last block sending node has is block #98645<br />
</pre><br />
<br />
And here's a modern (60002) protocol version client advertising itself to a local peer...<br />
<br />
Newer protocol includes the checksum now, this is from a mainline (satoshi) client during <br />
an outgoing connection to another local client, notice that it does not fill out the <br />
address information at all when the source or destination is "unroutable".<br />
<br />
<pre><br />
<br />
0000 f9 be b4 d9 76 65 72 73 69 6f 6e 00 00 00 00 00 ....version.....<br />
0010 64 00 00 00 35 8d 49 32 62 ea 00 00 01 00 00 00 d...5.I2b.......<br />
0020 00 00 00 00 11 b2 d0 50 00 00 00 00 01 00 00 00 .......P........<br />
0030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ff ff ................<br />
0040 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 00 00 00 00 ff ff 00 00 00 00 00 00 ................<br />
0060 3b 2e b3 5d 8c e6 17 65 0f 2f 53 61 74 6f 73 68 ;..]...e./Satosh<br />
0070 69 3a 30 2e 37 2e 32 2f c0 3e 03 00 i:0.7.2/.>..<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
64 00 00 00 - Payload is 100 bytes long<br />
3B 64 8D 5A - payload checksum<br />
<br />
Version message:<br />
62 EA 00 00 - 60002 (protocol version 60002)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
11 B2 D0 50 00 00 00 00 - Tue Dec 18 10:12:33 PST 2012<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Sender address info - see Network Address<br />
3B 2E B3 5D 8C E6 17 65 - Node ID<br />
0F 2F 53 61 74 6F 73 68 69 3A 30 2E 37 2E 32 2F - "/Satoshi:0.7.2/" sub-version string (string is 15 bytes long)<br />
C0 3E 03 00 - Last block sending node has is block #212672<br />
</pre><br />
<br />
=== verack ===<br />
<br />
The ''verack'' message is sent in reply to ''[[#version|version]]''. This message consists of only a [[#Message structure|message header]] with the command string "verack".<br />
<br />
Hexdump of the verack message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......<br />
0010 00 00 00 00 5D F6 E0 E2 ........<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 61 63 6B 00 00 00 00 00 00 - "verack" command<br />
00 00 00 00 - Payload is 0 bytes long<br />
5D F6 E0 E2 - Checksum<br />
</pre><br />
<br />
=== addr ===<br />
<br />
Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours<br />
<br />
Payload:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of address entries (max: 1000)<br />
|-<br />
| 30x? || addr_list || (uint32_t + [[#Network address|net_addr]])[] || Address of other nodes on the network. version < 209 will only read the first one. The uint32_t is a timestamp (see note below).<br />
|}<br />
<br />
'''Note''': Starting version 31402, addresses are prefixed with a timestamp. If no timestamp is present, the addresses should not be relayed to other peers, unless it is indeed confirmed they are up.<br />
<br />
Hexdump example of ''addr'' message:<br />
<pre><br />
0000 F9 BE B4 D9 61 64 64 72 00 00 00 00 00 00 00 00 ....addr........<br />
0010 1F 00 00 00 ED 52 39 9B 01 E2 15 10 4D 01 00 00 .....R9.....M...<br />
0020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF ................<br />
0030 FF 0A 00 00 01 20 8D ..... .<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
61 64 64 72 00 00 00 00 00 00 00 00 - "addr"<br />
1F 00 00 00 - payload is 31 bytes long<br />
ED 52 39 9B - checksum of payload<br />
<br />
Payload:<br />
01 - 1 address in this message<br />
<br />
Address:<br />
E2 15 10 4D - Mon Dec 20 21:50:10 EST 2010 (only when version is >= 31402)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK service - see version message)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv4: 10.0.0.1, IPv6: ::ffff:10.0.0.1 (IPv4-mapped IPv6 address)<br />
20 8D - port 8333<br />
</pre><br />
<br />
=== inv ===<br />
<br />
Allows a node to advertise its knowledge of one or more objects. It can be received unsolicited, or in reply to ''getblocks''.<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getdata ===<br />
<br />
getdata is used in response to inv, to retrieve the content of a specific object, and is usually sent after receiving an ''inv'' packet, after filtering known elements. It can be used to retrieve transactions, but only if they are in the memory pool or relay set - arbitrary access to transactions in the chain is not allowed to avoid having clients start to depend on nodes having full transaction indexes (which modern nodes do not).<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== notfound ===<br />
<br />
notfound is a response to a getdata, sent if any requested data items could not be relayed, for example, because the requested transaction was not in the memory pool or relay set.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getblocks ===<br />
<br />
Return an ''inv'' packet containing the list of blocks starting right after the last known hash in the block locator object, up to hash_stop or 500 blocks, whichever comes first. <br />
<br />
The locator hashes are processed by a node in the order as they appear in the message. If a block hash is found in the node's main chain, the list of its children is returned back via the ''inv'' message and the remaining locators are ignored, no matter if the requested limit was reached, or not.<br />
<br />
To receive the next blocks hashes, one needs to issue getblocks again with a new block locator object. Keep in mind that some clients may provide blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block; set to zero to get as many blocks as possible (500)<br />
|}<br />
<br />
To create the block locator hashes, keep pushing hashes until you go back to the genesis block. After pushing 10 hashes back, the step backwards doubles every loop:<br />
<br />
<pre><br />
// From libbitcoin which is under AGPL<br />
std::vector<size_t> block_locator_indexes(size_t top_height)<br />
{<br />
std::vector<size_t> indexes;<br />
<br />
// Modify the step in the iteration.<br />
int64_t step = 1;<br />
<br />
// Start at the top of the chain and work backwards.<br />
for (auto index = (int64_t)top_height; index > 0; index -= step)<br />
{<br />
// Push top 10 indexes first, then back off exponentially.<br />
if (indexes.size() >= 10)<br />
step *= 2;<br />
<br />
indexes.push_back((size_t)index);<br />
}<br />
<br />
// Push the genesis block index.<br />
indexes.push_back(0);<br />
return indexes;<br />
}<br />
</pre><br />
<br />
Note that it is allowed to send in fewer known hashes down to a minimum of just one hash. However, the purpose of the block locator object is to detect a wrong branch in the caller's main chain. If the peer detects that you are off the main chain, it will send in block hashes which are earlier than your last known block. So if you just send in your last known hash and it is off the main chain, the peer starts over at block #1.<br />
<br />
=== getheaders ===<br />
<br />
Return a ''headers'' packet containing the headers of blocks starting right after the last known hash in the block locator object, up to hash_stop or 2000 blocks, whichever comes first. To receive the next block headers, one needs to issue getheaders again with a new block locator object. The ''getheaders'' command is used by thin clients to quickly download the block chain where the contents of the transactions would be irrelevant (because they are not ours). Keep in mind that some clients may provide headers of blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block header; set to zero to get as many blocks as possible (2000)<br />
|}<br />
<br />
For the block locator object in this packet, the same rules apply as for the [[Protocol_documentation#getblocks|getblocks]] packet.<br />
<br />
=== tx ===<br />
<br />
''tx'' describes a bitcoin transaction, in reply to ''[[#getdata|getdata]]''<br />
<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Transaction data format version (note, this is signed)<br />
|-<br />
| 1+ || tx_in count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction inputs<br />
|-<br />
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins<br />
|-<br />
| 1+ || tx_out count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction outputs<br />
|-<br />
| 9+ || tx_out || tx_out[] || A list of 1 or more transaction outputs or destinations for coins<br />
|-<br />
| 4 || lock_time || uint32_t || The block number or timestamp at which this transaction is locked:<br />
{|class="wikitable"<br />
! Value !! Description<br />
|-<br />
| 0 || Not locked<br />
|-<br />
| < 500000000 || Block number at which this transaction is locked<br />
|-<br />
| >= 500000000 || UNIX timestamp at which this transaction is locked<br />
|}<br />
If all TxIn inputs have final (0xffffffff) sequence numbers then lock_time is irrelevant. Otherwise, the transaction may not be added to a block until after lock_time (see [[NLockTime]]).<br />
<br />
|}<br />
<br />
TxIn consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 36 || previous_output || outpoint || The previous output transaction reference, as an OutPoint structure<br />
|-<br />
| 1+ || script length || [[Protocol_documentation#Variable_length_integer|var_int]] || The length of the signature script<br />
|-<br />
| ? || signature script || uchar[] || Computational Script for confirming transaction authorization<br />
|-<br />
| 4 || [http://bitcoin.stackexchange.com/q/2025/323 sequence] || uint32_t || Transaction version as defined by the sender. Intended for "replacement" of transactions when information is updated before inclusion into a block.<br />
|}<br />
<br />
The OutPoint structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 32 || hash || char[32] || The hash of the referenced transaction.<br />
|-<br />
| 4 || index || uint32_t || The index of the specific output in the transaction. The first output is 0, etc.<br />
|}<br />
<br />
The Script structure consists of a series of pieces of information and operations related to the value of the transaction.<br />
<br />
(Structure to be expanded in the future… see script.h and script.cpp and [[Script]] for more information)<br />
<br />
The TxOut structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || value || int64_t || Transaction Value<br />
|-<br />
| 1+ || pk_script length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the pk_script<br />
|-<br />
| ? || pk_script || uchar[] || Usually contains the public key as a Bitcoin script setting up conditions to claim this output.<br />
|}<br />
<br />
Example ''tx'' message:<br />
<pre><br />
000000 F9 BE B4 D9 74 78 00 00 00 00 00 00 00 00 00 00 ....tx..........<br />
000010 02 01 00 00 E2 93 CD BE 01 00 00 00 01 6D BD DB .............m..<br />
000020 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D 12 66 E9 .[...Q........f.<br />
000030 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29 00 00 00 .;P......j.6)...<br />
000040 00 8B 48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 ..H0E.!..X..r...<br />
000050 C7 36 7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A .6zz%;..R#...h.:<br />
000060 59 23 3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 Y#?E.W... Y.....<br />
000070 0E 41 83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D .A.z.X.z...XN...<br />
000080 35 BD 96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF 5...6..;...A....<br />
000090 C9 7E F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 .~.6.m...@..!...<br />
0000A0 2A CD 2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC *.+..].}Y... ...<br />
0000B0 4E 02 53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F N.S..=7.o...Q...<br />
0000C0 14 04 2F 46 61 4A 4C 70 C0 F1 4B EF F5 FF FF FF ../FaJLp..K.....<br />
0000D0 FF 02 40 4B 4C 00 00 00 00 00 19 76 A9 14 1A A0 ..@KL......v....<br />
0000E0 CD 1C BE A6 E7 45 8A 7A BA D5 12 A9 D9 EA 1A FB .....E.z........<br />
0000F0 22 5E 88 AC 80 FA E9 C7 00 00 00 00 19 76 A9 14 "^...........v..<br />
000100 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E FD A0 B7 ..[.Cj.....H^...<br />
000110 8B 4E CC 52 88 AC 00 00 00 00 .N.R......<br />
<br />
<br />
Message header:<br />
F9 BE B4 D9 - main network magic bytes<br />
74 78 00 00 00 00 00 00 00 00 00 00 - "tx" command<br />
02 01 00 00 - payload is 258 bytes long<br />
E2 93 CD BE - checksum of payload<br />
<br />
Transaction:<br />
01 00 00 00 - version<br />
<br />
Inputs:<br />
01 - number of transaction inputs<br />
<br />
Input 1:<br />
6D BD DB 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D - previous output (outpoint)<br />
12 66 E9 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29<br />
00 00 00 00<br />
<br />
8B - script is 139 bytes long<br />
<br />
48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 C7 36 - signature script (scriptSig)<br />
7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A 59 23<br />
3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 0E 41<br />
83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D 35 BD<br />
96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF C9 7E<br />
F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 2A CD<br />
2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC 4E 02<br />
53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F 14 04<br />
2F 46 61 4A 4C 70 C0 F1 4B EF F5<br />
<br />
FF FF FF FF - sequence<br />
<br />
Outputs:<br />
02 - 2 Output Transactions<br />
<br />
Output 1:<br />
40 4B 4C 00 00 00 00 00 - 0.05 BTC (5000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 1A A0 CD 1C BE A6 E7 45 8A 7A BA D5 12 - pk_script<br />
A9 D9 EA 1A FB 22 5E 88 AC<br />
<br />
Output 2:<br />
80 FA E9 C7 00 00 00 00 - 33.54 BTC (3354000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E - pk_script<br />
FD A0 B7 8B 4E CC 52 88 AC<br />
<br />
Locktime:<br />
00 00 00 00 - lock time<br />
</pre><br />
<br />
=== block ===<br />
<br />
The '''block''' message is sent in response to a getdata message which requests transaction information from a block hash.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A Unix timestamp recording when this block was created (Currently limited to dates before the year 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated [[Difficulty|difficulty target]] being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| ? || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries<br />
|-<br />
| ? || txns || tx[] || Block transactions, in format of "tx" command<br />
|}<br />
<br />
The SHA256 hash that identifies each block (and which must have a run of 0 bits) is calculated from the first 6 fields of this structure (version, prev_block, merkle_root, timestamp, bits, nonce, and standard SHA256 padding, making two 64-byte chunks in all) and ''not'' from the complete block. To calculate the hash, only two chunks need to be processed by the SHA256 algorithm. Since the ''nonce'' field is in the second chunk, the first chunk stays constant during mining and therefore only the second chunk needs to be processed. However, a Bitcoin hash is the hash of the hash, so two SHA256 rounds are needed for each mining iteration.<br />
See [[Block hashing algorithm]] for details and an example.<br />
<br />
=== headers ===<br />
<br />
The ''headers'' packet returns block headers in response to a ''getheaders'' packet. <br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of block headers<br />
|-<br />
| 81x? || headers || [[Protocol_documentation#Block_Headers|block_header]][] || [[Protocol_documentation#Block_Headers|Block headers]]<br />
|}<br />
<br />
Note that the block headers in this packet include a transaction count (a var_int, so there can be more than 81 bytes per header) as opposed to the block headers that are hashed by miners.<br />
<br />
=== getaddr ===<br />
<br />
The getaddr message sends a request to a node asking for information about known active peers to help with finding potential nodes in the network. The response to receiving this message is to transmit one or more addr messages with one or more peers from a database of known active peers. The typical presumption is that a node is likely to be active if it has been sending a message within the last three hours.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
=== mempool ===<br />
<br />
The mempool message sends a request to a node asking for information about transactions it has verified but which have not yet confirmed. The response to receiving this message is an inv message containing the transaction hashes for all the transactions in the node's mempool.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
It is specified in [https://github.com/bitcoin/bips/blob/master/bip-0035.mediawiki BIP 35]. Since [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 37], if a [[Protocol_documentation#filterload.2C_filteradd.2C_filterclear.2C_merkleblock|bloom filter]] is loaded, only transactions matching the filter are replied.<br />
<br />
=== checkorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== submitorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== reply ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== ping ===<br />
<br />
The ''ping'' message is sent primarily to confirm that the TCP/IP connection is still valid. An error in transmission is presumed to be a closed connection and the address is removed as a current peer.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || random nonce<br />
|}<br />
<br />
=== pong ===<br />
<br />
The ''pong'' message is sent in response to a ''ping'' message. In modern protocol versions, a ''pong'' response is generated using a nonce included in the ping.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || nonce from ping<br />
|}<br />
<br />
<br />
=== reject===<br />
<br />
The ''reject'' message is sent when messages are rejected.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || message || var_str || type of message rejected<br />
|-<br />
| 1 || ccode || char || code relating to rejected message<br />
|-<br />
| 1+ || reason || var_str || text version of reason for rejection<br />
|-<br />
| 0+ || data || char || Optional extra data provided by some errors. Currently, all errors which provide this field fill it with the TXID or block header hash of the object being rejected, so the field is 32 bytes.<br />
|}<br />
<br />
CCodes<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0x01 || REJECT_MALFORMED|| <br />
|-<br />
| 0x10 || REJECT_INVALID ||<br />
|-<br />
| 0x11 || REJECT_OBSOLETE ||<br />
|-<br />
| 0x12 || REJECT_DUPLICATE ||<br />
|-<br />
| 0x40 || REJECT_NONSTANDARD ||<br />
|-<br />
| 0x41 || REJECT_DUST ||<br />
|-<br />
| 0x42 || REJECT_INSUFFICIENTFEE ||<br />
|-<br />
| 0x43 || REJECT_CHECKPOINT ||<br />
|}<br />
<br />
=== filterload, filteradd, filterclear, merkleblock ===<br />
<br />
These messages are related to Bloom filtering of connections and are defined in [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037].<br />
<br />
<br />
The <code>filterload</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || filter || uint8_t[] || The filter itself is simply a bit field of arbitrary byte-aligned size. The maximum size is 36,000 bytes.<br />
|-<br />
| 4 || nHashFuncs || uint32_t || The number of hash functions to use in this filter. The maximum value allowed in this field is 50.<br />
|-<br />
| 4 || nTweak || uint32_t || A random value to add to the seed value in the hash function used by the bloom filter.<br />
|-<br />
| 1 || nFlags || uint8_t || A set of flags that control how matched items are added to the filter.<br />
|}<br />
<br />
See below for a description of the Bloom filter algorithm and how to select nHashFuncs and filter size for a desired false positive rate.<br />
<br />
Upon receiving a <code>filterload</code> command, the remote peer will immediately restrict the broadcast transactions it announces (in inv packets) to transactions matching the filter, where the matching algorithm is specified below. The flags control the update behaviour of the matching algorithm.<br />
<br />
The <code>filteradd</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || data || uint8_t[] || The data element to add to the current filter.<br />
|}<br />
<br />
The data field must be smaller than or equal to 520 bytes in size (the maximum size of any potentially matched object).<br />
<br />
The given data element will be added to the Bloom filter. A filter must have been previously provided using <code>filterload</code>. This command is useful if a new key or script is added to a clients wallet whilst it has connections to the network open, it avoids the need to re-calculate and send an entirely new filter to every peer (though doing so is usually advisable to maintain anonymity).<br />
<br />
The <code>filterclear</code> command has no arguments at all.<br />
<br />
After a filter has been set, nodes don't merely stop announcing non-matching transactions, they can also serve filtered blocks. A filtered block is defined by the <code>merkleblock</code> message and is defined like this:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information, based upon the software version creating this block (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Limited to 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 4 || total_transactions || uint32_t || Number of transactions in the block (including unmatched ones)<br />
|-<br />
| ? || hashes || uint256[] || hashes in depth-first order (including standard varint size prefix)<br />
|-<br />
| ? || flags || byte[] || flag bits, packed per 8 in a byte, least significant bit first (including standard varint size prefix)<br />
|}<br />
<br />
=== alert ===<br />
<br />
An '''alert''' is sent between nodes to send a general notification message throughout the network. If the alert can be confirmed with the signature as having come from the core development group of the Bitcoin software, the message is suggested to be displayed for end-users. Attempts to perform transactions, particularly automated transactions through the client, are suggested to be halted. The text in the Message string should be relayed to log files and any user interfaces.<br />
<br />
Alert format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || payload || uchar[] || Serialized alert payload<br />
|-<br />
| ? || signature || uchar[] || An ECDSA signature of the message<br />
|}<br />
<br />
The developers of Satoshi's client use this public key for signing alerts:<br />
04fc9702847840aaf195de8442ebecedf5b095cdbb9bc716bda9110971b28a49e0ead8564ff0db22209e0374782c093bb899692d524e9d6a6956e7c5ecbcd68284<br />
(hash) 1AGRxqDa5WjUKBwHB9XYEjmkv1ucoUUy1s<br />
<br />
The payload is serialized into a uchar[] to ensure that versions using incompatible alert formats can still relay alerts among one another. The current alert payload format is:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || Version || int32_t || Alert format version<br />
|-<br />
| 8 || RelayUntil || int64_t || The timestamp beyond which nodes should stop relaying this alert<br />
|-<br />
| 8 || Expiration || int64_t || The timestamp beyond which this alert is no longer in effect and should be ignored<br />
|-<br />
| 4 || ID || int32_t || A unique ID number for this alert<br />
|-<br />
| 4 || Cancel || int32_t || All alerts with an ID number less than or equal to this number should be cancelled: deleted and not accepted in the future<br />
|-<br />
| ? || setCancel || set<int32_t> || All alert IDs contained in this set should be cancelled as above<br />
|-<br />
| 4 || MinVer || int32_t || This alert only applies to versions greater than or equal to this version. Other versions should still relay it.<br />
|-<br />
| 4 || MaxVer || int32_t || This alert only applies to versions less than or equal to this version. Other versions should still relay it.<br />
|-<br />
| ? || setSubVer || set<string> || If this set contains any elements, then only nodes that have their subVer contained in this set are affected by the alert. Other versions should still relay it.<br />
|-<br />
| 4 || Priority || int32_t || Relative priority compared to other alerts<br />
|-<br />
| ? || Comment || string || A comment on the alert that is not displayed<br />
|-<br />
| ? || StatusBar || string || The alert message that is displayed to the user<br />
|-<br />
| ? || Reserved || string || Reserved<br />
|}<br />
<br />
Note: '''set<''type''>''' in the table above is a [[#Variable length integer | variable length integer]] followed by the number of fields of the given ''type'' (either int32_t or [[#Variable length string | variable length string]])<br />
<br />
Sample alert (no message header):<br />
73010000003766404f00000000b305434f00000000f2030000f1030000001027000048ee0000<br />
0064000000004653656520626974636f696e2e6f72672f666562323020696620796f75206861<br />
76652074726f75626c6520636f6e6e656374696e672061667465722032302046656272756172<br />
79004730450221008389df45f0703f39ec8c1cc42c13810ffcae14995bb648340219e353b63b<br />
53eb022009ec65e1c1aaeec1fd334c6b684bde2b3f573060d5b70c3a46723326e4e8a4f1<br />
<br />
Version: 1<br />
RelayUntil: 1329620535<br />
Expiration: 1329792435<br />
ID: 1010<br />
Cancel: 1009<br />
setCancel: <empty><br />
MinVer: 10000<br />
MaxVer: 61000<br />
setSubVer: <empty><br />
Priority: 100<br />
Comment: <empty><br />
StatusBar: "See bitcoin.org/feb20 if you have trouble connecting after 20 February"<br />
Reserved: <empty><br />
<br />
=== sendheaders ===<br />
<br />
Request for Direct headers announcement. <br />
<br />
Upon receipt of this message, the node is be permitted, but not required, to announce new blocks by '''headers''' command (instead of '''inv''' command).<br />
<br />
This message is supported by the protocol version >= 70012 or Bitcoin Core version >= 0.12.0.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0130.mediawiki BIP 130] for more information.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
<br />
=== feefilter ===<br />
<br />
The payload is always 8 bytes long and it encodes 64 bit integer value (LSB / little endian) of '''feerate'''.<br />
The value represents a minimal fee and is expressed in satoshis per 1000 bytes.<br />
<br />
Upon receipt of a "feefilter" message, the node will be permitted, but not required, to filter transaction invs for transactions that fall below the feerate provided in the feefilter message interpreted as satoshis per kilobyte.<br />
<br />
The fee filter is additive with a bloom filter for transactions so if an SPV client were to load a bloom filter and send a feefilter message, transactions would only be relayed if they passed both filters.<br />
<br />
Inv's generated from a mempool message are also subject to a fee filter if it exists.<br />
<br />
Feature discovery is enabled by checking protocol version >= 70013<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0133.mediawiki BIP 133] for more information.<br />
<br />
=== sendcmpct ===<br />
<br />
# The sendcmpct message is defined as a message containing a 1-byte integer followed by a 8-byte integer where pchCommand == "sendcmpct".<br />
# The first integer SHALL be interpreted as a boolean (and MUST have a value of either 1 or 0)<br />
# The second integer SHALL be interpreted as a little-endian version number. Nodes sending a sendcmpct message MUST currently set this value to 1.<br />
# Upon receipt of a "sendcmpct" message with the first and second integers set to 1, the node SHOULD announce new blocks by sending a cmpctblock message.<br />
# Upon receipt of a "sendcmpct" message with the first integer set to 0, the node SHOULD NOT announce new blocks by sending a cmpctblock message, but SHOULD announce new blocks by sending invs or headers, as defined by BIP130.<br />
# Upon receipt of a "sendcmpct" message with the second integer set to something other than 1, nodes MUST treat the peer as if they had not received the message (as it indicates the peer will provide an unexpected encoding in <br />
# cmpctblock, and/or other, messages). This allows future versions to send duplicate sendcmpct messages with different versions as a part of a version handshake for future versions.<br />
# Nodes SHOULD check for a protocol version of >= 70014 before sending sendcmpct messages.<br />
# Nodes MUST NOT send a request for a MSG_CMPCT_BLOCK object to a peer before having received a sendcmpct message from that peer.<br />
<br />
This message is only supported by protocol version >= 70014<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== cmpctblock ===<br />
<br />
# The cmpctblock message is defined as as a message containing a serialized [[Protocol_documentation#HeaderAndShortIDs|HeaderAndShortIDs]] message and pchCommand == "cmpctblock".<br />
# Upon receipt of a cmpctblock message after sending a sendcmpct message, nodes SHOULD calculate the [[Protocol_documentation#Short_transaction_ID|short transaction ID]] for each unconfirmed transaction they have available (ie in their mempool) and compare each to each short transaction ID in the cmpctblock message.<br />
# After finding already-available transactions, nodes which do not have all transactions available to reconstruct the full block SHOULD request the missing transactions using a getblocktxn message.<br />
# A node MUST NOT send a cmpctblock message unless they are able to respond to a getblocktxn message which requests every transaction in the block.<br />
# A node MUST NOT send a cmpctblock message without having validated that the header properly commits to each transaction in the block, and properly builds on top of the existing chain with a valid proof-of-work. A node MAY send a cmpctblock before validating that each transaction in the block validly spends existing UTXO set entries.<br />
<br />
This message is only supported by protocol version >= 70014<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== getblocktxn ===<br />
<br />
# The getblocktxn message is defined as as a message containing a serialized [[Protocol_documentation#BlockTransactionsRequest|BlockTransactionsRequest]] message and pchCommand == "getblocktxn".<br />
# Upon receipt of a properly-formatted getblocktxnmessage, nodes which recently provided the sender of such a message a cmpctblock for the block hash identified in this message MUST respond with an appropriate [[Protocol_documentation#blocktxn|blocktxn]] message. Such a blocktxn message MUST contain exactly and only each transaction which is present in the appropriate block at the index specified in the getblocktxn indexes list, in the order requested.<br />
<br />
This message is only supported by protocol version >= 70014<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== blocktxn ===<br />
<br />
# The blocktxn message is defined as as a message containing a serialized [[Protocol_documentation#BlockTransactions|BlockTransactions]] message and pchCommand == "blocktxn".<br />
# Upon receipt of a properly-formatted requested blocktxn message, nodes SHOULD attempt to reconstruct the full block by:<br />
# Taking the prefilledtxn transactions from the original [[Protocol_documentation#cmpctblock|cmpctblock]] and placing them in the marked positions.<br />
# For each short transaction ID from the original [[Protocol_documentation#cmpctblock|cmpctblock]], in order, find the corresponding transaction either from the blocktxn message or from other sources and place it in the first available position in the block.<br />
# Once the block has been reconstructed, it shall be processed as normal, keeping in mind that short transaction IDs are expected to occasionally collide, and that nodes MUST NOT be penalized for such collisions, wherever they appear.<br />
<br />
This message is only supported by protocol version >= 70014<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
== Scripting ==<br />
<br />
See [[script]].<br />
<br />
==See Also==<br />
<br />
* [[Network]]<br />
* [[Protocol rules]]<br />
* [[Hardfork Wishlist]]<br />
* [https://bitcoin.org/en/developer-documentation Developer Documentation on bitcoin.org]<br />
* Bitcoin dissectors for Wireshark: https://github.com/lbotsch/wireshark-bitcoin https://github.com/op-sig/bitcoin-wireshark-dissector<br />
<br />
==References==<br />
<references /><br />
<br />
[[zh-cn:协议说明]]<br />
[[Category:Technical]]<br />
[[Category:Developer]]<br />
<br />
{{Bitcoin Core documentation}}</div>Tonikthttps://en.bitcoin.it/w/index.php?title=Protocol_documentation&diff=61503Protocol documentation2016-08-25T13:18:04Z<p>Tonikt: /* getblocktxn */</p>
<hr />
<div>This page ''describes'' the behavior of the [[Original Bitcoin client|reference client]]. The Bitcoin protocol is specified by the behavior of the reference client, not by this page. In particular, while this page is quite complete in describing the network protocol, it does not attempt to list all of the rules for block or transaction validity.<br />
<br />
Type names used in this documentation are from the C99 standard.<br />
<br />
For protocol used in mining, see [[getblocktemplate]].<br />
<br />
==Common standards==<br />
<br />
=== Hashes ===<br />
<br />
Usually, when a hash is computed within bitcoin, it is computed twice. Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-256] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when a shorter hash is desirable (for example when creating a bitcoin address).<br />
<br />
Example of double-SHA-256 encoding of string "hello":<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round of sha-256)<br />
9595c9df90075148eb06860365df33584b75bff782a510c6cd4883a419833d50 (second round of sha-256)<br />
<br />
For bitcoin addresses (RIPEMD-160) this would give:<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round is sha-256)<br />
b6a9c8c230722b7c748331a8b450f05566dc7d0f (with ripemd-160)<br />
<br />
=== Merkle Trees ===<br />
<br />
Merkle trees are binary trees of hashes. Merkle trees in bitcoin use a '''double''' SHA-256, the SHA-256 hash of the SHA-256 hash of something.<br />
<br />
If, when forming a row in the tree (other than the root of the tree), it would have an odd number of elements, the final double-hash is duplicated to ensure that the row has an even number of hashes.<br />
<br />
First form the bottom row of the tree with the ordered double-SHA-256 hashes of the byte streams of the transactions in the block.<br />
<br />
Then the row above it consists of half that number of hashes. Each entry is the double-SHA-256 of the 64-byte concatenation of the corresponding two hashes below it in the tree.<br />
<br />
This procedure repeats recursively until we reach a row consisting of just a single double-hash. This is the '''Merkle root''' of the tree.<br />
<br />
For example, imagine a block with three transactions ''a'', ''b'' and ''c''. The Merkle tree is: <br />
<br />
d1 = dhash(a)<br />
d2 = dhash(b)<br />
d3 = dhash(c)<br />
d4 = dhash(c) # a, b, c are 3. that's an odd number, so we take the c twice<br />
<br />
d5 = dhash(d1 concat d2)<br />
d6 = dhash(d3 concat d4)<br />
<br />
d7 = dhash(d5 concat d6)<br />
<br />
where<br />
<br />
dhash(a) = sha256(sha256(a))<br />
<br />
''d7'' is the Merkle root of the 3 transactions in this block.<br />
<br />
Note: Hashes in Merkle Tree displayed in the [[Block Explorer]] are of little-endian notation. For some implementations and [http://www.fileformat.info/tool/hash.htm calculations], the bits need to be reversed before they are hashed, and again after the hashing operation.<br />
<br />
=== Signatures ===<br />
<br />
Bitcoin uses [http://en.wikipedia.org/wiki/Elliptic_curve_cryptography Elliptic Curve] [http://en.wikipedia.org/wiki/Digital_Signature_Algorithm Digital Signature Algorithm] ([http://en.wikipedia.org/wiki/Elliptic_Curve_DSA ECDSA]) to sign transactions. <br />
<br />
For [[ECDSA]] the secp256k1 curve from http://www.secg.org/collateral/sec2_final.pdf is used.<br />
<br />
Public keys (in scripts) are given as 04 <x> <y> where ''x'' and ''y'' are 32 byte big-endian integers representing the coordinates of a point on the curve or in compressed form given as <sign> <x> where <sign> is 0x02 if ''y'' is even and 0x03 if ''y'' is odd.<br />
<br />
Signatures use [http://en.wikipedia.org/wiki/Distinguished_Encoding_Rules DER encoding] to pack the ''r'' and ''s'' components into a single byte stream (this is also what OpenSSL produces by default).<br />
<br />
=== Transaction Verification ===<br />
Transactions are cryptographically signed records that reassign ownership of Bitcoins to new addresses. Transactions have ''inputs'' - records which reference the funds from other previous transactions - and ''outputs'' - records which determine the new owner of the transferred Bitcoins, and which will be referenced as inputs in future transactions as those funds are respent.<br />
<br />
Each ''input'' must have a cryptographic digital signature that unlocks the funds from the prior transaction. Only the person possessing the appropriate [[private key]] is able to create a satisfactory signature; this in effect ensures that funds can only be spent by their owners.<br />
<br />
Each ''output'' determines which Bitcoin address (or other criteria, see [[Script]]) is the recipient of the funds.<br />
<br />
In a transaction, the sum of all inputs must be equal to or greater than the sum of all outputs. If the inputs exceed the outputs, the difference is considered a [[transaction fee]], and is redeemable by whoever first includes the transaction into the block chain.<br />
<br />
A special kind of transaction, called a [[coinbase transaction]], has no inputs. It is created by [[miners]], and there is one coinbase transaction per block. Because each block comes with a reward of newly created Bitcoins (e.g. 50 BTC for the first 210,000 blocks), the first transaction of a block is, with few exceptions, the transaction that grants those coins to their recipient (the miner). In addition to the newly created Bitcoins, the coinbase transaction is also used for assigning the recipient of any transaction fees that were paid within the other transactions being included in the same block. The coinbase transaction can assign the entire reward to a single Bitcoin address, or split it in portions among multiple addresses, just like any other transaction. Coinbase transactions always contain outputs totalling the sum of the block reward plus all transaction fees collected from the other transactions in the same block.<br />
<br />
The [[coinbase transaction]] in block zero cannot be spent. This is due to a quirk of the reference client implementation that would open the potential for a block chain fork if some nodes accepted the spend and others did not<ref>[http://bitcointalk.org/index.php?topic=119645.msg1288552#msg1288552 Block 0 Network Fork]</ref>.<br />
<br />
Most Bitcoin outputs encumber the newly transferred coins with a single ECDSA private key. The actual record saved with inputs and outputs isn't necessarily a key, but a ''script''. Bitcoin uses an interpreted scripting system to determine whether an output's criteria have been satisfied, with which more complex operations are possible, such as outputs that require two ECDSA signatures, or two-of-three-signature schemes. An output that references a single Bitcoin address is a ''typical'' output; an output actually contains this information in the form of a script that requires a single ECDSA signature (see [[OP_CHECKSIG]]). The output script specifies what must be provided to unlock the funds later, and when the time comes in the future to spend the transaction in another input, that input must provide all of the thing(s) that satisfy the requirements defined by the original output script.<br />
<br />
=== Addresses ===<br />
<br />
A bitcoin address is in fact the hash of a ECDSA public key, computed this way:<br />
<br />
Version = 1 byte of 0 (zero); on the test network, this is 1 byte of 111<br />
Key hash = Version concatenated with RIPEMD-160(SHA-256(public key))<br />
Checksum = 1st 4 bytes of SHA-256(SHA-256(Key hash))<br />
Bitcoin Address = Base58Encode(Key hash concatenated with Checksum)<br />
<br />
The Base58 encoding used is home made, and has some differences. Especially, leading zeroes are kept as single zeroes when conversion happens.<br />
<br />
== Common structures ==<br />
<br />
Almost all integers are encoded in little endian. Only IP or port number are encoded big endian.<br />
<br />
=== Message structure ===<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown<br />
|-<br />
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| 4 || length || uint32_t || Length of payload in number of bytes<br />
|-<br />
| 4 || checksum || uint32_t || First 4 bytes of sha256(sha256(payload))<br />
|-<br />
| ? || payload || uchar[] || The actual data<br />
|}<br />
<br />
<br />
Known magic values:<br />
<br />
{|class="wikitable"<br />
! Network !! Magic value !! Sent over wire as<br />
|-<br />
| main || 0xD9B4BEF9 || F9 BE B4 D9<br />
|-<br />
| testnet || 0xDAB5BFFA || FA BF B5 DA<br />
|-<br />
| testnet3 || 0x0709110B || 0B 11 09 07<br />
|-<br />
| namecoin || 0xFEB4BEF9 || F9 BE B4 FE<br />
|}<br />
<br />
=== Variable length integer ===<br />
<br />
Integer can be encoded depending on the represented value to save space.<br />
Variable length integers always precede an array/vector of a type of data that may vary in length.<br />
Longer numbers are encoded in little endian.<br />
<br />
{|class="wikitable"<br />
! Value !! Storage length !! Format<br />
|-<br />
| < 0xFD || 1 || uint8_t<br />
|-<br />
| <= 0xFFFF || 3 || 0xFD followed by the length as uint16_t<br />
|-<br />
| <= 0xFFFF FFFF || 5 || 0xFE followed by the length as uint32_t<br />
|-<br />
| - || 9 || 0xFF followed by the length as uint64_t<br />
|}<br />
<br />
If you're reading the Satoshi client code (BitcoinQT) it refers to this encoding as a "CompactSize". Modern BitcoinQT also has the CVarInt class which implements an even more compact integer for the purpose of local storage (which is incompatible with "CompactSize" described here). CVarInt is not a part of the protocol.<br />
<br />
=== Variable length string ===<br />
<br />
Variable length string can be stored using a variable length integer followed by the string itself.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the string<br />
|-<br />
| ? || string || char[] || The string itself (can be empty)<br />
|}<br />
<br />
=== Network address ===<br />
<br />
When a network address is needed somewhere, this structure is used. Network addresses are not prefixed with a timestamp in the version message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || time || uint32 || the Time (version >= 31402). '''Not present in version message.'''<br />
|-<br />
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]<br />
|-<br />
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The original client only supported IPv4 and only read the last 4 bytes to get the IPv4 address. However, the IPv4 address is written into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]<br />
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).<br />
|-<br />
| 2 || port || uint16_t || port number, network byte order<br />
|}<br />
<br />
Hexdump example of Network address structure<br />
<br />
<pre><br />
0000 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0010 00 00 FF FF 0A 00 00 01 20 8D ........ .<br />
<br />
Network address:<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK: see services listed under version command)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv6: ::ffff:a00:1 or IPv4: 10.0.0.1<br />
20 8D - Port 8333<br />
</pre><br />
<br />
=== Inventory Vectors ===<br />
<br />
Inventory vectors are used for notifying other nodes about objects they have or data which is being requested.<br />
<br />
Inventory vectors consist of the following data format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || type || uint32_t || Identifies the object type linked to this inventory<br />
|-<br />
| 32 || hash || char[32] || Hash of the object<br />
|}<br />
<br />
<br />
The object type is currently defined as one of the following possibilities:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0 || ERROR || Any data of with this number may be ignored<br />
|-<br />
| 1 || MSG_TX || Hash is related to a transaction<br />
|-<br />
| 2 || MSG_BLOCK || Hash is related to a data block<br />
|-<br />
| 3 || MSG_FILTERED_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a merkleblock message rather than a block message; this only works if a bloom filter has been set.<br />
|-<br />
| 4 || MSG_CMPCT_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a cmpctblock message. See BIP 152 for more info.<br />
|}<br />
<br />
Other Data Type values are considered reserved for future implementations.<br />
<br />
=== Block Headers ===<br />
<br />
Block headers are sent in a headers packet in response to a getheaders message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Will overflow in 2106<ref>https://en.wikipedia.org/wiki/Unix_time#Notable_events_in_Unix_time</ref>)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 1 || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries, this value is always 0<br />
|}<br />
<br />
cf. [[Block hashing algorithm]]<br />
<br />
=== Differential encoding === <br />
Several uses of CompactSize below are "differentially encoded". For these, instead of using raw indexes, the number encoded is the difference between the current index and the previous index, minus one. For example, a first index of 0 implies a real index of 0, a second index of 0 thereafter refers to a real index of 1, etc.<br />
<br />
=== PrefilledTransaction ===<br />
<br />
A PrefilledTransaction structure is used in HeaderAndShortIDs to provide a list of a few transactions explicitly.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| index || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1, 3 bytes || Compact Size, differentially encoded since the last PrefilledTransaction in a list || The index into the block at which this transaction is<br />
|-<br />
| tx || Transaction || variable || As encoded in [[Protocol_documentation#tx|tx messages]] || The transaction which is in the block at index index.<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== HeaderAndShortIDs ===<br />
<br />
A HeaderAndShortIDs structure is used to relay a block header, the short transactions IDs used for matching already-available transactions, and a select few transactions which we expect a peer may be missing.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| header || Block header || 80 bytes || First 80 bytes of the block as defined by the encoding used by "block" messages || The header of the block being provided<br />
|-<br />
| nonce || uint64_t || 8 bytes || Little Endian || A nonce for use in short transaction ID calculations<br />
|-<br />
| shortids_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of short transaction IDs in shortids (ie block tx count - prefilledtxn_length)<br />
|-<br />
| shortids || List of 6-byte integers || 6*shortids_length bytes || Little Endian || The [[Protocol_documentation#Short_transaction_ID|short transaction IDs]] calculated from the transactions which were not provided explicitly in prefilledtxn<br />
|-<br />
| prefilledtxn_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of prefilled transactions in prefilledtxn (ie block tx count - shortids_length)<br />
|-<br />
| prefilledtxn || List of PrefilledTransactions || variable size*prefilledtxn_length || As defined by [[Protocol_documentation#PrefilledTransaction|PrefilledTransaction]] definition, above || Used to provide the coinbase transaction and a select few which we expect a peer may be missing<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== BlockTransactionsRequest ===<br />
<br />
A BlockTransactionsRequest structure is used to list transaction indexes in a block being requested.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| blockhash || Binary blob || 32 bytes || The output from a double-SHA256 of the block header, as used elsewhere || The blockhash of the block which the transactions being requested are in<br />
|-<br />
| indexes_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of transactions being requested<br />
|-<br />
| indexes || List of [[Protocol_documentation#Variable_length_integer|CompactSizes]] || 1 or 3 bytes*indexes_length || [[Protocol_documentation#Differential_encoding|Differentially encoded]] || The indexes of the transactions being requested in the block<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== BlockTransactions ===<br />
<br />
A BlockTransactions structure is used to provide some of the transactions in a block, as requested.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| blockhash || Binary blob || 32 bytes || The output from a double-SHA256 of the block header, as used elsewhere || The blockhash of the block which the transactions being provided are in<br />
|-<br />
| transactions_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of transactions provided<br />
|-<br />
| transactions || List of Transactions || variable || As encoded in [[Protocol_documentation#tx|tx messages]] || The transactions provided<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== Short transaction ID ===<br />
<br />
Short transaction IDs are used to represent a transaction without sending a full 256-bit hash. They are calculated by:<br />
<br />
# single-SHA256 hashing the block header with the nonce appended (in little-endian)<br />
# Running SipHash-2-4 with the input being the transaction ID and the keys (k0/k1) set to the first two little-endian 64-bit integers from the above hash, respectively.<br />
# Dropping the 2 most significant bytes from the SipHash output to make it 6 bytes.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
== Message types ==<br />
<br />
=== version ===<br />
<br />
When a node creates an outgoing connection, it will immediately [[Version Handshake|advertise]] its version. The remote node will respond with its version. No further communication is possible until both peers have exchanged their version.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Identifies protocol version being used by the node<br />
|-<br />
| 8 || services || uint64_t || bitfield of features to be enabled for this connection<br />
|-<br />
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds<br />
|-<br />
| 26 || addr_recv || [[#Network address|net_addr]] || The network address of the node receiving this message<br />
|-<br />
|colspan="4"| Fields below require version ≥ 106<br />
|-<br />
| 26 || addr_from || [[#Network address|net_addr]] || The network address of the node emitting this message<br />
|-<br />
| 8 || nonce || uint64_t || Node random nonce, randomly generated every time a version packet is sent. This nonce is used to detect connections to self.<br />
|-<br />
| ? || user_agent || [[#Variable length string|var_str]] || [https://github.com/bitcoin/bips/blob/master/bip-0014.mediawiki User Agent] (0x00 if string is 0 bytes long)<br />
|-<br />
| 4 || start_height || int32_t || The last block received by the emitting node<br />
|-<br />
|colspan="4"| Fields below require version ≥ 70001<br />
|-<br />
| 1 || relay || bool || Whether the remote peer should announce relayed transactions or not, see [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037]<br />
|}<br />
<br />
A "verack" packet shall be sent if the version packet was accepted.<br />
<br />
The following services are currently assigned:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 1 || NODE_NETWORK || This node can be asked for full blocks instead of just headers.<br />
|}<br />
<br />
Hexdump example of version message (OBSOLETE EXAMPLE: This example lacks a checksum and user-agent):<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....<br />
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........<br />
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............<br />
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................<br />
0040 20 8D 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,<br />
0060 3A B4 57 13 00 55 81 01 00 :.W..U...<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
55 00 00 00 - Payload is 85 bytes long<br />
- No checksum in version message until 20 February 2012. See https://bitcointalk.org/index.php?topic=55852.0<br />
Version message:<br />
9C 7C 00 00 - 31900 (version 0.3.19)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
E6 15 10 4D 00 00 00 00 - Mon Dec 20 21:50:14 EST 2010<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 20 8D - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D - Sender address info - see Network Address<br />
DD 9D 20 2C 3A B4 57 13 - Node random unique ID<br />
00 - "" sub-version string (string is 0 bytes long)<br />
55 81 01 00 - Last block sending node has is block #98645<br />
</pre><br />
<br />
And here's a modern (60002) protocol version client advertising itself to a local peer...<br />
<br />
Newer protocol includes the checksum now, this is from a mainline (satoshi) client during <br />
an outgoing connection to another local client, notice that it does not fill out the <br />
address information at all when the source or destination is "unroutable".<br />
<br />
<pre><br />
<br />
0000 f9 be b4 d9 76 65 72 73 69 6f 6e 00 00 00 00 00 ....version.....<br />
0010 64 00 00 00 35 8d 49 32 62 ea 00 00 01 00 00 00 d...5.I2b.......<br />
0020 00 00 00 00 11 b2 d0 50 00 00 00 00 01 00 00 00 .......P........<br />
0030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ff ff ................<br />
0040 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 00 00 00 00 ff ff 00 00 00 00 00 00 ................<br />
0060 3b 2e b3 5d 8c e6 17 65 0f 2f 53 61 74 6f 73 68 ;..]...e./Satosh<br />
0070 69 3a 30 2e 37 2e 32 2f c0 3e 03 00 i:0.7.2/.>..<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
64 00 00 00 - Payload is 100 bytes long<br />
3B 64 8D 5A - payload checksum<br />
<br />
Version message:<br />
62 EA 00 00 - 60002 (protocol version 60002)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
11 B2 D0 50 00 00 00 00 - Tue Dec 18 10:12:33 PST 2012<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Sender address info - see Network Address<br />
3B 2E B3 5D 8C E6 17 65 - Node ID<br />
0F 2F 53 61 74 6F 73 68 69 3A 30 2E 37 2E 32 2F - "/Satoshi:0.7.2/" sub-version string (string is 15 bytes long)<br />
C0 3E 03 00 - Last block sending node has is block #212672<br />
</pre><br />
<br />
=== verack ===<br />
<br />
The ''verack'' message is sent in reply to ''[[#version|version]]''. This message consists of only a [[#Message structure|message header]] with the command string "verack".<br />
<br />
Hexdump of the verack message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......<br />
0010 00 00 00 00 5D F6 E0 E2 ........<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 61 63 6B 00 00 00 00 00 00 - "verack" command<br />
00 00 00 00 - Payload is 0 bytes long<br />
5D F6 E0 E2 - Checksum<br />
</pre><br />
<br />
=== addr ===<br />
<br />
Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours<br />
<br />
Payload:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of address entries (max: 1000)<br />
|-<br />
| 30x? || addr_list || (uint32_t + [[#Network address|net_addr]])[] || Address of other nodes on the network. version < 209 will only read the first one. The uint32_t is a timestamp (see note below).<br />
|}<br />
<br />
'''Note''': Starting version 31402, addresses are prefixed with a timestamp. If no timestamp is present, the addresses should not be relayed to other peers, unless it is indeed confirmed they are up.<br />
<br />
Hexdump example of ''addr'' message:<br />
<pre><br />
0000 F9 BE B4 D9 61 64 64 72 00 00 00 00 00 00 00 00 ....addr........<br />
0010 1F 00 00 00 ED 52 39 9B 01 E2 15 10 4D 01 00 00 .....R9.....M...<br />
0020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF ................<br />
0030 FF 0A 00 00 01 20 8D ..... .<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
61 64 64 72 00 00 00 00 00 00 00 00 - "addr"<br />
1F 00 00 00 - payload is 31 bytes long<br />
ED 52 39 9B - checksum of payload<br />
<br />
Payload:<br />
01 - 1 address in this message<br />
<br />
Address:<br />
E2 15 10 4D - Mon Dec 20 21:50:10 EST 2010 (only when version is >= 31402)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK service - see version message)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv4: 10.0.0.1, IPv6: ::ffff:10.0.0.1 (IPv4-mapped IPv6 address)<br />
20 8D - port 8333<br />
</pre><br />
<br />
=== inv ===<br />
<br />
Allows a node to advertise its knowledge of one or more objects. It can be received unsolicited, or in reply to ''getblocks''.<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getdata ===<br />
<br />
getdata is used in response to inv, to retrieve the content of a specific object, and is usually sent after receiving an ''inv'' packet, after filtering known elements. It can be used to retrieve transactions, but only if they are in the memory pool or relay set - arbitrary access to transactions in the chain is not allowed to avoid having clients start to depend on nodes having full transaction indexes (which modern nodes do not).<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== notfound ===<br />
<br />
notfound is a response to a getdata, sent if any requested data items could not be relayed, for example, because the requested transaction was not in the memory pool or relay set.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getblocks ===<br />
<br />
Return an ''inv'' packet containing the list of blocks starting right after the last known hash in the block locator object, up to hash_stop or 500 blocks, whichever comes first. <br />
<br />
The locator hashes are processed by a node in the order as they appear in the message. If a block hash is found in the node's main chain, the list of its children is returned back via the ''inv'' message and the remaining locators are ignored, no matter if the requested limit was reached, or not.<br />
<br />
To receive the next blocks hashes, one needs to issue getblocks again with a new block locator object. Keep in mind that some clients may provide blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block; set to zero to get as many blocks as possible (500)<br />
|}<br />
<br />
To create the block locator hashes, keep pushing hashes until you go back to the genesis block. After pushing 10 hashes back, the step backwards doubles every loop:<br />
<br />
<pre><br />
// From libbitcoin which is under AGPL<br />
std::vector<size_t> block_locator_indexes(size_t top_height)<br />
{<br />
std::vector<size_t> indexes;<br />
<br />
// Modify the step in the iteration.<br />
int64_t step = 1;<br />
<br />
// Start at the top of the chain and work backwards.<br />
for (auto index = (int64_t)top_height; index > 0; index -= step)<br />
{<br />
// Push top 10 indexes first, then back off exponentially.<br />
if (indexes.size() >= 10)<br />
step *= 2;<br />
<br />
indexes.push_back((size_t)index);<br />
}<br />
<br />
// Push the genesis block index.<br />
indexes.push_back(0);<br />
return indexes;<br />
}<br />
</pre><br />
<br />
Note that it is allowed to send in fewer known hashes down to a minimum of just one hash. However, the purpose of the block locator object is to detect a wrong branch in the caller's main chain. If the peer detects that you are off the main chain, it will send in block hashes which are earlier than your last known block. So if you just send in your last known hash and it is off the main chain, the peer starts over at block #1.<br />
<br />
=== getheaders ===<br />
<br />
Return a ''headers'' packet containing the headers of blocks starting right after the last known hash in the block locator object, up to hash_stop or 2000 blocks, whichever comes first. To receive the next block headers, one needs to issue getheaders again with a new block locator object. The ''getheaders'' command is used by thin clients to quickly download the block chain where the contents of the transactions would be irrelevant (because they are not ours). Keep in mind that some clients may provide headers of blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block header; set to zero to get as many blocks as possible (2000)<br />
|}<br />
<br />
For the block locator object in this packet, the same rules apply as for the [[Protocol_documentation#getblocks|getblocks]] packet.<br />
<br />
=== tx ===<br />
<br />
''tx'' describes a bitcoin transaction, in reply to ''[[#getdata|getdata]]''<br />
<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Transaction data format version (note, this is signed)<br />
|-<br />
| 1+ || tx_in count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction inputs<br />
|-<br />
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins<br />
|-<br />
| 1+ || tx_out count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction outputs<br />
|-<br />
| 9+ || tx_out || tx_out[] || A list of 1 or more transaction outputs or destinations for coins<br />
|-<br />
| 4 || lock_time || uint32_t || The block number or timestamp at which this transaction is locked:<br />
{|class="wikitable"<br />
! Value !! Description<br />
|-<br />
| 0 || Not locked<br />
|-<br />
| < 500000000 || Block number at which this transaction is locked<br />
|-<br />
| >= 500000000 || UNIX timestamp at which this transaction is locked<br />
|}<br />
If all TxIn inputs have final (0xffffffff) sequence numbers then lock_time is irrelevant. Otherwise, the transaction may not be added to a block until after lock_time (see [[NLockTime]]).<br />
<br />
|}<br />
<br />
TxIn consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 36 || previous_output || outpoint || The previous output transaction reference, as an OutPoint structure<br />
|-<br />
| 1+ || script length || [[Protocol_documentation#Variable_length_integer|var_int]] || The length of the signature script<br />
|-<br />
| ? || signature script || uchar[] || Computational Script for confirming transaction authorization<br />
|-<br />
| 4 || [http://bitcoin.stackexchange.com/q/2025/323 sequence] || uint32_t || Transaction version as defined by the sender. Intended for "replacement" of transactions when information is updated before inclusion into a block.<br />
|}<br />
<br />
The OutPoint structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 32 || hash || char[32] || The hash of the referenced transaction.<br />
|-<br />
| 4 || index || uint32_t || The index of the specific output in the transaction. The first output is 0, etc.<br />
|}<br />
<br />
The Script structure consists of a series of pieces of information and operations related to the value of the transaction.<br />
<br />
(Structure to be expanded in the future… see script.h and script.cpp and [[Script]] for more information)<br />
<br />
The TxOut structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || value || int64_t || Transaction Value<br />
|-<br />
| 1+ || pk_script length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the pk_script<br />
|-<br />
| ? || pk_script || uchar[] || Usually contains the public key as a Bitcoin script setting up conditions to claim this output.<br />
|}<br />
<br />
Example ''tx'' message:<br />
<pre><br />
000000 F9 BE B4 D9 74 78 00 00 00 00 00 00 00 00 00 00 ....tx..........<br />
000010 02 01 00 00 E2 93 CD BE 01 00 00 00 01 6D BD DB .............m..<br />
000020 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D 12 66 E9 .[...Q........f.<br />
000030 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29 00 00 00 .;P......j.6)...<br />
000040 00 8B 48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 ..H0E.!..X..r...<br />
000050 C7 36 7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A .6zz%;..R#...h.:<br />
000060 59 23 3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 Y#?E.W... Y.....<br />
000070 0E 41 83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D .A.z.X.z...XN...<br />
000080 35 BD 96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF 5...6..;...A....<br />
000090 C9 7E F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 .~.6.m...@..!...<br />
0000A0 2A CD 2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC *.+..].}Y... ...<br />
0000B0 4E 02 53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F N.S..=7.o...Q...<br />
0000C0 14 04 2F 46 61 4A 4C 70 C0 F1 4B EF F5 FF FF FF ../FaJLp..K.....<br />
0000D0 FF 02 40 4B 4C 00 00 00 00 00 19 76 A9 14 1A A0 ..@KL......v....<br />
0000E0 CD 1C BE A6 E7 45 8A 7A BA D5 12 A9 D9 EA 1A FB .....E.z........<br />
0000F0 22 5E 88 AC 80 FA E9 C7 00 00 00 00 19 76 A9 14 "^...........v..<br />
000100 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E FD A0 B7 ..[.Cj.....H^...<br />
000110 8B 4E CC 52 88 AC 00 00 00 00 .N.R......<br />
<br />
<br />
Message header:<br />
F9 BE B4 D9 - main network magic bytes<br />
74 78 00 00 00 00 00 00 00 00 00 00 - "tx" command<br />
02 01 00 00 - payload is 258 bytes long<br />
E2 93 CD BE - checksum of payload<br />
<br />
Transaction:<br />
01 00 00 00 - version<br />
<br />
Inputs:<br />
01 - number of transaction inputs<br />
<br />
Input 1:<br />
6D BD DB 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D - previous output (outpoint)<br />
12 66 E9 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29<br />
00 00 00 00<br />
<br />
8B - script is 139 bytes long<br />
<br />
48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 C7 36 - signature script (scriptSig)<br />
7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A 59 23<br />
3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 0E 41<br />
83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D 35 BD<br />
96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF C9 7E<br />
F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 2A CD<br />
2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC 4E 02<br />
53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F 14 04<br />
2F 46 61 4A 4C 70 C0 F1 4B EF F5<br />
<br />
FF FF FF FF - sequence<br />
<br />
Outputs:<br />
02 - 2 Output Transactions<br />
<br />
Output 1:<br />
40 4B 4C 00 00 00 00 00 - 0.05 BTC (5000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 1A A0 CD 1C BE A6 E7 45 8A 7A BA D5 12 - pk_script<br />
A9 D9 EA 1A FB 22 5E 88 AC<br />
<br />
Output 2:<br />
80 FA E9 C7 00 00 00 00 - 33.54 BTC (3354000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E - pk_script<br />
FD A0 B7 8B 4E CC 52 88 AC<br />
<br />
Locktime:<br />
00 00 00 00 - lock time<br />
</pre><br />
<br />
=== block ===<br />
<br />
The '''block''' message is sent in response to a getdata message which requests transaction information from a block hash.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A Unix timestamp recording when this block was created (Currently limited to dates before the year 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated [[Difficulty|difficulty target]] being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| ? || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries<br />
|-<br />
| ? || txns || tx[] || Block transactions, in format of "tx" command<br />
|}<br />
<br />
The SHA256 hash that identifies each block (and which must have a run of 0 bits) is calculated from the first 6 fields of this structure (version, prev_block, merkle_root, timestamp, bits, nonce, and standard SHA256 padding, making two 64-byte chunks in all) and ''not'' from the complete block. To calculate the hash, only two chunks need to be processed by the SHA256 algorithm. Since the ''nonce'' field is in the second chunk, the first chunk stays constant during mining and therefore only the second chunk needs to be processed. However, a Bitcoin hash is the hash of the hash, so two SHA256 rounds are needed for each mining iteration.<br />
See [[Block hashing algorithm]] for details and an example.<br />
<br />
=== headers ===<br />
<br />
The ''headers'' packet returns block headers in response to a ''getheaders'' packet. <br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of block headers<br />
|-<br />
| 81x? || headers || [[Protocol_documentation#Block_Headers|block_header]][] || [[Protocol_documentation#Block_Headers|Block headers]]<br />
|}<br />
<br />
Note that the block headers in this packet include a transaction count (a var_int, so there can be more than 81 bytes per header) as opposed to the block headers that are hashed by miners.<br />
<br />
=== getaddr ===<br />
<br />
The getaddr message sends a request to a node asking for information about known active peers to help with finding potential nodes in the network. The response to receiving this message is to transmit one or more addr messages with one or more peers from a database of known active peers. The typical presumption is that a node is likely to be active if it has been sending a message within the last three hours.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
=== mempool ===<br />
<br />
The mempool message sends a request to a node asking for information about transactions it has verified but which have not yet confirmed. The response to receiving this message is an inv message containing the transaction hashes for all the transactions in the node's mempool.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
It is specified in [https://github.com/bitcoin/bips/blob/master/bip-0035.mediawiki BIP 35]. Since [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 37], if a [[Protocol_documentation#filterload.2C_filteradd.2C_filterclear.2C_merkleblock|bloom filter]] is loaded, only transactions matching the filter are replied.<br />
<br />
=== checkorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== submitorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== reply ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== ping ===<br />
<br />
The ''ping'' message is sent primarily to confirm that the TCP/IP connection is still valid. An error in transmission is presumed to be a closed connection and the address is removed as a current peer.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || random nonce<br />
|}<br />
<br />
=== pong ===<br />
<br />
The ''pong'' message is sent in response to a ''ping'' message. In modern protocol versions, a ''pong'' response is generated using a nonce included in the ping.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || nonce from ping<br />
|}<br />
<br />
<br />
=== reject===<br />
<br />
The ''reject'' message is sent when messages are rejected.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || message || var_str || type of message rejected<br />
|-<br />
| 1 || ccode || char || code relating to rejected message<br />
|-<br />
| 1+ || reason || var_str || text version of reason for rejection<br />
|-<br />
| 0+ || data || char || Optional extra data provided by some errors. Currently, all errors which provide this field fill it with the TXID or block header hash of the object being rejected, so the field is 32 bytes.<br />
|}<br />
<br />
CCodes<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0x01 || REJECT_MALFORMED|| <br />
|-<br />
| 0x10 || REJECT_INVALID ||<br />
|-<br />
| 0x11 || REJECT_OBSOLETE ||<br />
|-<br />
| 0x12 || REJECT_DUPLICATE ||<br />
|-<br />
| 0x40 || REJECT_NONSTANDARD ||<br />
|-<br />
| 0x41 || REJECT_DUST ||<br />
|-<br />
| 0x42 || REJECT_INSUFFICIENTFEE ||<br />
|-<br />
| 0x43 || REJECT_CHECKPOINT ||<br />
|}<br />
<br />
=== filterload, filteradd, filterclear, merkleblock ===<br />
<br />
These messages are related to Bloom filtering of connections and are defined in [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037].<br />
<br />
<br />
The <code>filterload</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || filter || uint8_t[] || The filter itself is simply a bit field of arbitrary byte-aligned size. The maximum size is 36,000 bytes.<br />
|-<br />
| 4 || nHashFuncs || uint32_t || The number of hash functions to use in this filter. The maximum value allowed in this field is 50.<br />
|-<br />
| 4 || nTweak || uint32_t || A random value to add to the seed value in the hash function used by the bloom filter.<br />
|-<br />
| 1 || nFlags || uint8_t || A set of flags that control how matched items are added to the filter.<br />
|}<br />
<br />
See below for a description of the Bloom filter algorithm and how to select nHashFuncs and filter size for a desired false positive rate.<br />
<br />
Upon receiving a <code>filterload</code> command, the remote peer will immediately restrict the broadcast transactions it announces (in inv packets) to transactions matching the filter, where the matching algorithm is specified below. The flags control the update behaviour of the matching algorithm.<br />
<br />
The <code>filteradd</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || data || uint8_t[] || The data element to add to the current filter.<br />
|}<br />
<br />
The data field must be smaller than or equal to 520 bytes in size (the maximum size of any potentially matched object).<br />
<br />
The given data element will be added to the Bloom filter. A filter must have been previously provided using <code>filterload</code>. This command is useful if a new key or script is added to a clients wallet whilst it has connections to the network open, it avoids the need to re-calculate and send an entirely new filter to every peer (though doing so is usually advisable to maintain anonymity).<br />
<br />
The <code>filterclear</code> command has no arguments at all.<br />
<br />
After a filter has been set, nodes don't merely stop announcing non-matching transactions, they can also serve filtered blocks. A filtered block is defined by the <code>merkleblock</code> message and is defined like this:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information, based upon the software version creating this block (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Limited to 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 4 || total_transactions || uint32_t || Number of transactions in the block (including unmatched ones)<br />
|-<br />
| ? || hashes || uint256[] || hashes in depth-first order (including standard varint size prefix)<br />
|-<br />
| ? || flags || byte[] || flag bits, packed per 8 in a byte, least significant bit first (including standard varint size prefix)<br />
|}<br />
<br />
=== alert ===<br />
<br />
An '''alert''' is sent between nodes to send a general notification message throughout the network. If the alert can be confirmed with the signature as having come from the core development group of the Bitcoin software, the message is suggested to be displayed for end-users. Attempts to perform transactions, particularly automated transactions through the client, are suggested to be halted. The text in the Message string should be relayed to log files and any user interfaces.<br />
<br />
Alert format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || payload || uchar[] || Serialized alert payload<br />
|-<br />
| ? || signature || uchar[] || An ECDSA signature of the message<br />
|}<br />
<br />
The developers of Satoshi's client use this public key for signing alerts:<br />
04fc9702847840aaf195de8442ebecedf5b095cdbb9bc716bda9110971b28a49e0ead8564ff0db22209e0374782c093bb899692d524e9d6a6956e7c5ecbcd68284<br />
(hash) 1AGRxqDa5WjUKBwHB9XYEjmkv1ucoUUy1s<br />
<br />
The payload is serialized into a uchar[] to ensure that versions using incompatible alert formats can still relay alerts among one another. The current alert payload format is:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || Version || int32_t || Alert format version<br />
|-<br />
| 8 || RelayUntil || int64_t || The timestamp beyond which nodes should stop relaying this alert<br />
|-<br />
| 8 || Expiration || int64_t || The timestamp beyond which this alert is no longer in effect and should be ignored<br />
|-<br />
| 4 || ID || int32_t || A unique ID number for this alert<br />
|-<br />
| 4 || Cancel || int32_t || All alerts with an ID number less than or equal to this number should be cancelled: deleted and not accepted in the future<br />
|-<br />
| ? || setCancel || set<int32_t> || All alert IDs contained in this set should be cancelled as above<br />
|-<br />
| 4 || MinVer || int32_t || This alert only applies to versions greater than or equal to this version. Other versions should still relay it.<br />
|-<br />
| 4 || MaxVer || int32_t || This alert only applies to versions less than or equal to this version. Other versions should still relay it.<br />
|-<br />
| ? || setSubVer || set<string> || If this set contains any elements, then only nodes that have their subVer contained in this set are affected by the alert. Other versions should still relay it.<br />
|-<br />
| 4 || Priority || int32_t || Relative priority compared to other alerts<br />
|-<br />
| ? || Comment || string || A comment on the alert that is not displayed<br />
|-<br />
| ? || StatusBar || string || The alert message that is displayed to the user<br />
|-<br />
| ? || Reserved || string || Reserved<br />
|}<br />
<br />
Note: '''set<''type''>''' in the table above is a [[#Variable length integer | variable length integer]] followed by the number of fields of the given ''type'' (either int32_t or [[#Variable length string | variable length string]])<br />
<br />
Sample alert (no message header):<br />
73010000003766404f00000000b305434f00000000f2030000f1030000001027000048ee0000<br />
0064000000004653656520626974636f696e2e6f72672f666562323020696620796f75206861<br />
76652074726f75626c6520636f6e6e656374696e672061667465722032302046656272756172<br />
79004730450221008389df45f0703f39ec8c1cc42c13810ffcae14995bb648340219e353b63b<br />
53eb022009ec65e1c1aaeec1fd334c6b684bde2b3f573060d5b70c3a46723326e4e8a4f1<br />
<br />
Version: 1<br />
RelayUntil: 1329620535<br />
Expiration: 1329792435<br />
ID: 1010<br />
Cancel: 1009<br />
setCancel: <empty><br />
MinVer: 10000<br />
MaxVer: 61000<br />
setSubVer: <empty><br />
Priority: 100<br />
Comment: <empty><br />
StatusBar: "See bitcoin.org/feb20 if you have trouble connecting after 20 February"<br />
Reserved: <empty><br />
<br />
=== sendheaders ===<br />
<br />
Request for Direct headers announcement. <br />
<br />
Upon receipt of this message, the node is be permitted, but not required, to announce new blocks by '''headers''' command (instead of '''inv''' command).<br />
<br />
This message is supported by the protocol version >= 70012 or Bitcoin Core version >= 0.12.0.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0130.mediawiki BIP 130] for more information.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
<br />
=== feefilter ===<br />
<br />
The payload is always 8 bytes long and it encodes 64 bit integer value (LSB / little endian) of '''feerate'''.<br />
The value represents a minimal fee and is expressed in satoshis per 1000 bytes.<br />
<br />
Upon receipt of a "feefilter" message, the node will be permitted, but not required, to filter transaction invs for transactions that fall below the feerate provided in the feefilter message interpreted as satoshis per kilobyte.<br />
<br />
The fee filter is additive with a bloom filter for transactions so if an SPV client were to load a bloom filter and send a feefilter message, transactions would only be relayed if they passed both filters.<br />
<br />
Inv's generated from a mempool message are also subject to a fee filter if it exists.<br />
<br />
Feature discovery is enabled by checking protocol version >= 70013<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0133.mediawiki BIP 133] for more information.<br />
<br />
=== sendcmpct ===<br />
<br />
# The sendcmpct message is defined as a message containing a 1-byte integer followed by a 8-byte integer where pchCommand == "sendcmpct".<br />
# The first integer SHALL be interpreted as a boolean (and MUST have a value of either 1 or 0)<br />
# The second integer SHALL be interpreted as a little-endian version number. Nodes sending a sendcmpct message MUST currently set this value to 1.<br />
# Upon receipt of a "sendcmpct" message with the first and second integers set to 1, the node SHOULD announce new blocks by sending a cmpctblock message.<br />
# Upon receipt of a "sendcmpct" message with the first integer set to 0, the node SHOULD NOT announce new blocks by sending a cmpctblock message, but SHOULD announce new blocks by sending invs or headers, as defined by BIP130.<br />
# Upon receipt of a "sendcmpct" message with the second integer set to something other than 1, nodes MUST treat the peer as if they had not received the message (as it indicates the peer will provide an unexpected encoding in <br />
# cmpctblock, and/or other, messages). This allows future versions to send duplicate sendcmpct messages with different versions as a part of a version handshake for future versions.<br />
# Nodes SHOULD check for a protocol version of >= 70014 before sending sendcmpct messages.<br />
# Nodes MUST NOT send a request for a MSG_CMPCT_BLOCK object to a peer before having received a sendcmpct message from that peer.<br />
<br />
This message is only supported by protocol version >= 70014<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== cmpctblock ===<br />
<br />
# The cmpctblock message is defined as as a message containing a serialized [[Protocol_documentation#HeaderAndShortIDs|HeaderAndShortIDs]] message and pchCommand == "cmpctblock".<br />
# Upon receipt of a cmpctblock message after sending a sendcmpct message, nodes SHOULD calculate the [[Protocol_documentation#Short_transaction_ID|short transaction ID]] for each unconfirmed transaction they have available (ie in their mempool) and compare each to each short transaction ID in the cmpctblock message.<br />
# After finding already-available transactions, nodes which do not have all transactions available to reconstruct the full block SHOULD request the missing transactions using a getblocktxn message.<br />
# A node MUST NOT send a cmpctblock message unless they are able to respond to a getblocktxn message which requests every transaction in the block.<br />
# A node MUST NOT send a cmpctblock message without having validated that the header properly commits to each transaction in the block, and properly builds on top of the existing chain with a valid proof-of-work. A node MAY send a cmpctblock before validating that each transaction in the block validly spends existing UTXO set entries.<br />
<br />
This message is only supported by protocol version >= 70014<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== getblocktxn ===<br />
<br />
# The getblocktxn message is defined as as a message containing a serialized [[Protocol_documentation#BlockTransactionsRequest|BlockTransactionsRequest]] message and pchCommand == "getblocktxn".<br />
# Upon receipt of a properly-formatted getblocktxnmessage, nodes which recently provided the sender of such a message a cmpctblock for the block hash identified in this message MUST respond with an appropriate [[Protocol_documentation#blocktxn|blocktxn]] message. Such a blocktxn message MUST contain exactly and only each transaction which is present in the appropriate block at the index specified in the getblocktxn indexes list, in the order requested.<br />
<br />
This message is only supported by protocol version >= 70014<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== blocktxn ===<br />
<br />
# The blocktxn message is defined as as a message containing a serialized BlockTransactions message and pchCommand == "blocktxn".<br />
# Upon receipt of a properly-formatted requested blocktxn message, nodes SHOULD attempt to reconstruct the full block by:<br />
# Taking the prefilledtxn transactions from the original cmpctblock and placing them in the marked positions.<br />
# For each short transaction ID from the original cmpctblock, in order, find the corresponding transaction either from the blocktxn message or from other sources and place it in the first available position in the block.<br />
# Once the block has been reconstructed, it shall be processed as normal, keeping in mind that short transaction IDs are expected to occasionally collide, and that nodes MUST NOT be penalized for such collisions, wherever they # appear.<br />
<br />
This message is only supported by protocol version >= 70014<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
== Scripting ==<br />
<br />
See [[script]].<br />
<br />
==See Also==<br />
<br />
* [[Network]]<br />
* [[Protocol rules]]<br />
* [[Hardfork Wishlist]]<br />
* [https://bitcoin.org/en/developer-documentation Developer Documentation on bitcoin.org]<br />
* Bitcoin dissectors for Wireshark: https://github.com/lbotsch/wireshark-bitcoin https://github.com/op-sig/bitcoin-wireshark-dissector<br />
<br />
==References==<br />
<references /><br />
<br />
[[zh-cn:协议说明]]<br />
[[Category:Technical]]<br />
[[Category:Developer]]<br />
<br />
{{Bitcoin Core documentation}}</div>Tonikthttps://en.bitcoin.it/w/index.php?title=Protocol_documentation&diff=61502Protocol documentation2016-08-25T13:16:45Z<p>Tonikt: /* cmpctblock */</p>
<hr />
<div>This page ''describes'' the behavior of the [[Original Bitcoin client|reference client]]. The Bitcoin protocol is specified by the behavior of the reference client, not by this page. In particular, while this page is quite complete in describing the network protocol, it does not attempt to list all of the rules for block or transaction validity.<br />
<br />
Type names used in this documentation are from the C99 standard.<br />
<br />
For protocol used in mining, see [[getblocktemplate]].<br />
<br />
==Common standards==<br />
<br />
=== Hashes ===<br />
<br />
Usually, when a hash is computed within bitcoin, it is computed twice. Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-256] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when a shorter hash is desirable (for example when creating a bitcoin address).<br />
<br />
Example of double-SHA-256 encoding of string "hello":<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round of sha-256)<br />
9595c9df90075148eb06860365df33584b75bff782a510c6cd4883a419833d50 (second round of sha-256)<br />
<br />
For bitcoin addresses (RIPEMD-160) this would give:<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round is sha-256)<br />
b6a9c8c230722b7c748331a8b450f05566dc7d0f (with ripemd-160)<br />
<br />
=== Merkle Trees ===<br />
<br />
Merkle trees are binary trees of hashes. Merkle trees in bitcoin use a '''double''' SHA-256, the SHA-256 hash of the SHA-256 hash of something.<br />
<br />
If, when forming a row in the tree (other than the root of the tree), it would have an odd number of elements, the final double-hash is duplicated to ensure that the row has an even number of hashes.<br />
<br />
First form the bottom row of the tree with the ordered double-SHA-256 hashes of the byte streams of the transactions in the block.<br />
<br />
Then the row above it consists of half that number of hashes. Each entry is the double-SHA-256 of the 64-byte concatenation of the corresponding two hashes below it in the tree.<br />
<br />
This procedure repeats recursively until we reach a row consisting of just a single double-hash. This is the '''Merkle root''' of the tree.<br />
<br />
For example, imagine a block with three transactions ''a'', ''b'' and ''c''. The Merkle tree is: <br />
<br />
d1 = dhash(a)<br />
d2 = dhash(b)<br />
d3 = dhash(c)<br />
d4 = dhash(c) # a, b, c are 3. that's an odd number, so we take the c twice<br />
<br />
d5 = dhash(d1 concat d2)<br />
d6 = dhash(d3 concat d4)<br />
<br />
d7 = dhash(d5 concat d6)<br />
<br />
where<br />
<br />
dhash(a) = sha256(sha256(a))<br />
<br />
''d7'' is the Merkle root of the 3 transactions in this block.<br />
<br />
Note: Hashes in Merkle Tree displayed in the [[Block Explorer]] are of little-endian notation. For some implementations and [http://www.fileformat.info/tool/hash.htm calculations], the bits need to be reversed before they are hashed, and again after the hashing operation.<br />
<br />
=== Signatures ===<br />
<br />
Bitcoin uses [http://en.wikipedia.org/wiki/Elliptic_curve_cryptography Elliptic Curve] [http://en.wikipedia.org/wiki/Digital_Signature_Algorithm Digital Signature Algorithm] ([http://en.wikipedia.org/wiki/Elliptic_Curve_DSA ECDSA]) to sign transactions. <br />
<br />
For [[ECDSA]] the secp256k1 curve from http://www.secg.org/collateral/sec2_final.pdf is used.<br />
<br />
Public keys (in scripts) are given as 04 <x> <y> where ''x'' and ''y'' are 32 byte big-endian integers representing the coordinates of a point on the curve or in compressed form given as <sign> <x> where <sign> is 0x02 if ''y'' is even and 0x03 if ''y'' is odd.<br />
<br />
Signatures use [http://en.wikipedia.org/wiki/Distinguished_Encoding_Rules DER encoding] to pack the ''r'' and ''s'' components into a single byte stream (this is also what OpenSSL produces by default).<br />
<br />
=== Transaction Verification ===<br />
Transactions are cryptographically signed records that reassign ownership of Bitcoins to new addresses. Transactions have ''inputs'' - records which reference the funds from other previous transactions - and ''outputs'' - records which determine the new owner of the transferred Bitcoins, and which will be referenced as inputs in future transactions as those funds are respent.<br />
<br />
Each ''input'' must have a cryptographic digital signature that unlocks the funds from the prior transaction. Only the person possessing the appropriate [[private key]] is able to create a satisfactory signature; this in effect ensures that funds can only be spent by their owners.<br />
<br />
Each ''output'' determines which Bitcoin address (or other criteria, see [[Script]]) is the recipient of the funds.<br />
<br />
In a transaction, the sum of all inputs must be equal to or greater than the sum of all outputs. If the inputs exceed the outputs, the difference is considered a [[transaction fee]], and is redeemable by whoever first includes the transaction into the block chain.<br />
<br />
A special kind of transaction, called a [[coinbase transaction]], has no inputs. It is created by [[miners]], and there is one coinbase transaction per block. Because each block comes with a reward of newly created Bitcoins (e.g. 50 BTC for the first 210,000 blocks), the first transaction of a block is, with few exceptions, the transaction that grants those coins to their recipient (the miner). In addition to the newly created Bitcoins, the coinbase transaction is also used for assigning the recipient of any transaction fees that were paid within the other transactions being included in the same block. The coinbase transaction can assign the entire reward to a single Bitcoin address, or split it in portions among multiple addresses, just like any other transaction. Coinbase transactions always contain outputs totalling the sum of the block reward plus all transaction fees collected from the other transactions in the same block.<br />
<br />
The [[coinbase transaction]] in block zero cannot be spent. This is due to a quirk of the reference client implementation that would open the potential for a block chain fork if some nodes accepted the spend and others did not<ref>[http://bitcointalk.org/index.php?topic=119645.msg1288552#msg1288552 Block 0 Network Fork]</ref>.<br />
<br />
Most Bitcoin outputs encumber the newly transferred coins with a single ECDSA private key. The actual record saved with inputs and outputs isn't necessarily a key, but a ''script''. Bitcoin uses an interpreted scripting system to determine whether an output's criteria have been satisfied, with which more complex operations are possible, such as outputs that require two ECDSA signatures, or two-of-three-signature schemes. An output that references a single Bitcoin address is a ''typical'' output; an output actually contains this information in the form of a script that requires a single ECDSA signature (see [[OP_CHECKSIG]]). The output script specifies what must be provided to unlock the funds later, and when the time comes in the future to spend the transaction in another input, that input must provide all of the thing(s) that satisfy the requirements defined by the original output script.<br />
<br />
=== Addresses ===<br />
<br />
A bitcoin address is in fact the hash of a ECDSA public key, computed this way:<br />
<br />
Version = 1 byte of 0 (zero); on the test network, this is 1 byte of 111<br />
Key hash = Version concatenated with RIPEMD-160(SHA-256(public key))<br />
Checksum = 1st 4 bytes of SHA-256(SHA-256(Key hash))<br />
Bitcoin Address = Base58Encode(Key hash concatenated with Checksum)<br />
<br />
The Base58 encoding used is home made, and has some differences. Especially, leading zeroes are kept as single zeroes when conversion happens.<br />
<br />
== Common structures ==<br />
<br />
Almost all integers are encoded in little endian. Only IP or port number are encoded big endian.<br />
<br />
=== Message structure ===<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown<br />
|-<br />
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| 4 || length || uint32_t || Length of payload in number of bytes<br />
|-<br />
| 4 || checksum || uint32_t || First 4 bytes of sha256(sha256(payload))<br />
|-<br />
| ? || payload || uchar[] || The actual data<br />
|}<br />
<br />
<br />
Known magic values:<br />
<br />
{|class="wikitable"<br />
! Network !! Magic value !! Sent over wire as<br />
|-<br />
| main || 0xD9B4BEF9 || F9 BE B4 D9<br />
|-<br />
| testnet || 0xDAB5BFFA || FA BF B5 DA<br />
|-<br />
| testnet3 || 0x0709110B || 0B 11 09 07<br />
|-<br />
| namecoin || 0xFEB4BEF9 || F9 BE B4 FE<br />
|}<br />
<br />
=== Variable length integer ===<br />
<br />
Integer can be encoded depending on the represented value to save space.<br />
Variable length integers always precede an array/vector of a type of data that may vary in length.<br />
Longer numbers are encoded in little endian.<br />
<br />
{|class="wikitable"<br />
! Value !! Storage length !! Format<br />
|-<br />
| < 0xFD || 1 || uint8_t<br />
|-<br />
| <= 0xFFFF || 3 || 0xFD followed by the length as uint16_t<br />
|-<br />
| <= 0xFFFF FFFF || 5 || 0xFE followed by the length as uint32_t<br />
|-<br />
| - || 9 || 0xFF followed by the length as uint64_t<br />
|}<br />
<br />
If you're reading the Satoshi client code (BitcoinQT) it refers to this encoding as a "CompactSize". Modern BitcoinQT also has the CVarInt class which implements an even more compact integer for the purpose of local storage (which is incompatible with "CompactSize" described here). CVarInt is not a part of the protocol.<br />
<br />
=== Variable length string ===<br />
<br />
Variable length string can be stored using a variable length integer followed by the string itself.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the string<br />
|-<br />
| ? || string || char[] || The string itself (can be empty)<br />
|}<br />
<br />
=== Network address ===<br />
<br />
When a network address is needed somewhere, this structure is used. Network addresses are not prefixed with a timestamp in the version message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || time || uint32 || the Time (version >= 31402). '''Not present in version message.'''<br />
|-<br />
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]<br />
|-<br />
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The original client only supported IPv4 and only read the last 4 bytes to get the IPv4 address. However, the IPv4 address is written into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]<br />
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).<br />
|-<br />
| 2 || port || uint16_t || port number, network byte order<br />
|}<br />
<br />
Hexdump example of Network address structure<br />
<br />
<pre><br />
0000 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0010 00 00 FF FF 0A 00 00 01 20 8D ........ .<br />
<br />
Network address:<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK: see services listed under version command)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv6: ::ffff:a00:1 or IPv4: 10.0.0.1<br />
20 8D - Port 8333<br />
</pre><br />
<br />
=== Inventory Vectors ===<br />
<br />
Inventory vectors are used for notifying other nodes about objects they have or data which is being requested.<br />
<br />
Inventory vectors consist of the following data format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || type || uint32_t || Identifies the object type linked to this inventory<br />
|-<br />
| 32 || hash || char[32] || Hash of the object<br />
|}<br />
<br />
<br />
The object type is currently defined as one of the following possibilities:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0 || ERROR || Any data of with this number may be ignored<br />
|-<br />
| 1 || MSG_TX || Hash is related to a transaction<br />
|-<br />
| 2 || MSG_BLOCK || Hash is related to a data block<br />
|-<br />
| 3 || MSG_FILTERED_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a merkleblock message rather than a block message; this only works if a bloom filter has been set.<br />
|-<br />
| 4 || MSG_CMPCT_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a cmpctblock message. See BIP 152 for more info.<br />
|}<br />
<br />
Other Data Type values are considered reserved for future implementations.<br />
<br />
=== Block Headers ===<br />
<br />
Block headers are sent in a headers packet in response to a getheaders message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Will overflow in 2106<ref>https://en.wikipedia.org/wiki/Unix_time#Notable_events_in_Unix_time</ref>)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 1 || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries, this value is always 0<br />
|}<br />
<br />
cf. [[Block hashing algorithm]]<br />
<br />
=== Differential encoding === <br />
Several uses of CompactSize below are "differentially encoded". For these, instead of using raw indexes, the number encoded is the difference between the current index and the previous index, minus one. For example, a first index of 0 implies a real index of 0, a second index of 0 thereafter refers to a real index of 1, etc.<br />
<br />
=== PrefilledTransaction ===<br />
<br />
A PrefilledTransaction structure is used in HeaderAndShortIDs to provide a list of a few transactions explicitly.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| index || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1, 3 bytes || Compact Size, differentially encoded since the last PrefilledTransaction in a list || The index into the block at which this transaction is<br />
|-<br />
| tx || Transaction || variable || As encoded in [[Protocol_documentation#tx|tx messages]] || The transaction which is in the block at index index.<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== HeaderAndShortIDs ===<br />
<br />
A HeaderAndShortIDs structure is used to relay a block header, the short transactions IDs used for matching already-available transactions, and a select few transactions which we expect a peer may be missing.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| header || Block header || 80 bytes || First 80 bytes of the block as defined by the encoding used by "block" messages || The header of the block being provided<br />
|-<br />
| nonce || uint64_t || 8 bytes || Little Endian || A nonce for use in short transaction ID calculations<br />
|-<br />
| shortids_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of short transaction IDs in shortids (ie block tx count - prefilledtxn_length)<br />
|-<br />
| shortids || List of 6-byte integers || 6*shortids_length bytes || Little Endian || The [[Protocol_documentation#Short_transaction_ID|short transaction IDs]] calculated from the transactions which were not provided explicitly in prefilledtxn<br />
|-<br />
| prefilledtxn_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of prefilled transactions in prefilledtxn (ie block tx count - shortids_length)<br />
|-<br />
| prefilledtxn || List of PrefilledTransactions || variable size*prefilledtxn_length || As defined by [[Protocol_documentation#PrefilledTransaction|PrefilledTransaction]] definition, above || Used to provide the coinbase transaction and a select few which we expect a peer may be missing<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== BlockTransactionsRequest ===<br />
<br />
A BlockTransactionsRequest structure is used to list transaction indexes in a block being requested.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| blockhash || Binary blob || 32 bytes || The output from a double-SHA256 of the block header, as used elsewhere || The blockhash of the block which the transactions being requested are in<br />
|-<br />
| indexes_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of transactions being requested<br />
|-<br />
| indexes || List of [[Protocol_documentation#Variable_length_integer|CompactSizes]] || 1 or 3 bytes*indexes_length || [[Protocol_documentation#Differential_encoding|Differentially encoded]] || The indexes of the transactions being requested in the block<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== BlockTransactions ===<br />
<br />
A BlockTransactions structure is used to provide some of the transactions in a block, as requested.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| blockhash || Binary blob || 32 bytes || The output from a double-SHA256 of the block header, as used elsewhere || The blockhash of the block which the transactions being provided are in<br />
|-<br />
| transactions_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of transactions provided<br />
|-<br />
| transactions || List of Transactions || variable || As encoded in [[Protocol_documentation#tx|tx messages]] || The transactions provided<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== Short transaction ID ===<br />
<br />
Short transaction IDs are used to represent a transaction without sending a full 256-bit hash. They are calculated by:<br />
<br />
# single-SHA256 hashing the block header with the nonce appended (in little-endian)<br />
# Running SipHash-2-4 with the input being the transaction ID and the keys (k0/k1) set to the first two little-endian 64-bit integers from the above hash, respectively.<br />
# Dropping the 2 most significant bytes from the SipHash output to make it 6 bytes.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
== Message types ==<br />
<br />
=== version ===<br />
<br />
When a node creates an outgoing connection, it will immediately [[Version Handshake|advertise]] its version. The remote node will respond with its version. No further communication is possible until both peers have exchanged their version.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Identifies protocol version being used by the node<br />
|-<br />
| 8 || services || uint64_t || bitfield of features to be enabled for this connection<br />
|-<br />
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds<br />
|-<br />
| 26 || addr_recv || [[#Network address|net_addr]] || The network address of the node receiving this message<br />
|-<br />
|colspan="4"| Fields below require version ≥ 106<br />
|-<br />
| 26 || addr_from || [[#Network address|net_addr]] || The network address of the node emitting this message<br />
|-<br />
| 8 || nonce || uint64_t || Node random nonce, randomly generated every time a version packet is sent. This nonce is used to detect connections to self.<br />
|-<br />
| ? || user_agent || [[#Variable length string|var_str]] || [https://github.com/bitcoin/bips/blob/master/bip-0014.mediawiki User Agent] (0x00 if string is 0 bytes long)<br />
|-<br />
| 4 || start_height || int32_t || The last block received by the emitting node<br />
|-<br />
|colspan="4"| Fields below require version ≥ 70001<br />
|-<br />
| 1 || relay || bool || Whether the remote peer should announce relayed transactions or not, see [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037]<br />
|}<br />
<br />
A "verack" packet shall be sent if the version packet was accepted.<br />
<br />
The following services are currently assigned:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 1 || NODE_NETWORK || This node can be asked for full blocks instead of just headers.<br />
|}<br />
<br />
Hexdump example of version message (OBSOLETE EXAMPLE: This example lacks a checksum and user-agent):<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....<br />
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........<br />
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............<br />
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................<br />
0040 20 8D 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,<br />
0060 3A B4 57 13 00 55 81 01 00 :.W..U...<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
55 00 00 00 - Payload is 85 bytes long<br />
- No checksum in version message until 20 February 2012. See https://bitcointalk.org/index.php?topic=55852.0<br />
Version message:<br />
9C 7C 00 00 - 31900 (version 0.3.19)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
E6 15 10 4D 00 00 00 00 - Mon Dec 20 21:50:14 EST 2010<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 20 8D - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D - Sender address info - see Network Address<br />
DD 9D 20 2C 3A B4 57 13 - Node random unique ID<br />
00 - "" sub-version string (string is 0 bytes long)<br />
55 81 01 00 - Last block sending node has is block #98645<br />
</pre><br />
<br />
And here's a modern (60002) protocol version client advertising itself to a local peer...<br />
<br />
Newer protocol includes the checksum now, this is from a mainline (satoshi) client during <br />
an outgoing connection to another local client, notice that it does not fill out the <br />
address information at all when the source or destination is "unroutable".<br />
<br />
<pre><br />
<br />
0000 f9 be b4 d9 76 65 72 73 69 6f 6e 00 00 00 00 00 ....version.....<br />
0010 64 00 00 00 35 8d 49 32 62 ea 00 00 01 00 00 00 d...5.I2b.......<br />
0020 00 00 00 00 11 b2 d0 50 00 00 00 00 01 00 00 00 .......P........<br />
0030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ff ff ................<br />
0040 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 00 00 00 00 ff ff 00 00 00 00 00 00 ................<br />
0060 3b 2e b3 5d 8c e6 17 65 0f 2f 53 61 74 6f 73 68 ;..]...e./Satosh<br />
0070 69 3a 30 2e 37 2e 32 2f c0 3e 03 00 i:0.7.2/.>..<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
64 00 00 00 - Payload is 100 bytes long<br />
3B 64 8D 5A - payload checksum<br />
<br />
Version message:<br />
62 EA 00 00 - 60002 (protocol version 60002)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
11 B2 D0 50 00 00 00 00 - Tue Dec 18 10:12:33 PST 2012<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Sender address info - see Network Address<br />
3B 2E B3 5D 8C E6 17 65 - Node ID<br />
0F 2F 53 61 74 6F 73 68 69 3A 30 2E 37 2E 32 2F - "/Satoshi:0.7.2/" sub-version string (string is 15 bytes long)<br />
C0 3E 03 00 - Last block sending node has is block #212672<br />
</pre><br />
<br />
=== verack ===<br />
<br />
The ''verack'' message is sent in reply to ''[[#version|version]]''. This message consists of only a [[#Message structure|message header]] with the command string "verack".<br />
<br />
Hexdump of the verack message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......<br />
0010 00 00 00 00 5D F6 E0 E2 ........<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 61 63 6B 00 00 00 00 00 00 - "verack" command<br />
00 00 00 00 - Payload is 0 bytes long<br />
5D F6 E0 E2 - Checksum<br />
</pre><br />
<br />
=== addr ===<br />
<br />
Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours<br />
<br />
Payload:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of address entries (max: 1000)<br />
|-<br />
| 30x? || addr_list || (uint32_t + [[#Network address|net_addr]])[] || Address of other nodes on the network. version < 209 will only read the first one. The uint32_t is a timestamp (see note below).<br />
|}<br />
<br />
'''Note''': Starting version 31402, addresses are prefixed with a timestamp. If no timestamp is present, the addresses should not be relayed to other peers, unless it is indeed confirmed they are up.<br />
<br />
Hexdump example of ''addr'' message:<br />
<pre><br />
0000 F9 BE B4 D9 61 64 64 72 00 00 00 00 00 00 00 00 ....addr........<br />
0010 1F 00 00 00 ED 52 39 9B 01 E2 15 10 4D 01 00 00 .....R9.....M...<br />
0020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF ................<br />
0030 FF 0A 00 00 01 20 8D ..... .<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
61 64 64 72 00 00 00 00 00 00 00 00 - "addr"<br />
1F 00 00 00 - payload is 31 bytes long<br />
ED 52 39 9B - checksum of payload<br />
<br />
Payload:<br />
01 - 1 address in this message<br />
<br />
Address:<br />
E2 15 10 4D - Mon Dec 20 21:50:10 EST 2010 (only when version is >= 31402)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK service - see version message)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv4: 10.0.0.1, IPv6: ::ffff:10.0.0.1 (IPv4-mapped IPv6 address)<br />
20 8D - port 8333<br />
</pre><br />
<br />
=== inv ===<br />
<br />
Allows a node to advertise its knowledge of one or more objects. It can be received unsolicited, or in reply to ''getblocks''.<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getdata ===<br />
<br />
getdata is used in response to inv, to retrieve the content of a specific object, and is usually sent after receiving an ''inv'' packet, after filtering known elements. It can be used to retrieve transactions, but only if they are in the memory pool or relay set - arbitrary access to transactions in the chain is not allowed to avoid having clients start to depend on nodes having full transaction indexes (which modern nodes do not).<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== notfound ===<br />
<br />
notfound is a response to a getdata, sent if any requested data items could not be relayed, for example, because the requested transaction was not in the memory pool or relay set.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getblocks ===<br />
<br />
Return an ''inv'' packet containing the list of blocks starting right after the last known hash in the block locator object, up to hash_stop or 500 blocks, whichever comes first. <br />
<br />
The locator hashes are processed by a node in the order as they appear in the message. If a block hash is found in the node's main chain, the list of its children is returned back via the ''inv'' message and the remaining locators are ignored, no matter if the requested limit was reached, or not.<br />
<br />
To receive the next blocks hashes, one needs to issue getblocks again with a new block locator object. Keep in mind that some clients may provide blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block; set to zero to get as many blocks as possible (500)<br />
|}<br />
<br />
To create the block locator hashes, keep pushing hashes until you go back to the genesis block. After pushing 10 hashes back, the step backwards doubles every loop:<br />
<br />
<pre><br />
// From libbitcoin which is under AGPL<br />
std::vector<size_t> block_locator_indexes(size_t top_height)<br />
{<br />
std::vector<size_t> indexes;<br />
<br />
// Modify the step in the iteration.<br />
int64_t step = 1;<br />
<br />
// Start at the top of the chain and work backwards.<br />
for (auto index = (int64_t)top_height; index > 0; index -= step)<br />
{<br />
// Push top 10 indexes first, then back off exponentially.<br />
if (indexes.size() >= 10)<br />
step *= 2;<br />
<br />
indexes.push_back((size_t)index);<br />
}<br />
<br />
// Push the genesis block index.<br />
indexes.push_back(0);<br />
return indexes;<br />
}<br />
</pre><br />
<br />
Note that it is allowed to send in fewer known hashes down to a minimum of just one hash. However, the purpose of the block locator object is to detect a wrong branch in the caller's main chain. If the peer detects that you are off the main chain, it will send in block hashes which are earlier than your last known block. So if you just send in your last known hash and it is off the main chain, the peer starts over at block #1.<br />
<br />
=== getheaders ===<br />
<br />
Return a ''headers'' packet containing the headers of blocks starting right after the last known hash in the block locator object, up to hash_stop or 2000 blocks, whichever comes first. To receive the next block headers, one needs to issue getheaders again with a new block locator object. The ''getheaders'' command is used by thin clients to quickly download the block chain where the contents of the transactions would be irrelevant (because they are not ours). Keep in mind that some clients may provide headers of blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block header; set to zero to get as many blocks as possible (2000)<br />
|}<br />
<br />
For the block locator object in this packet, the same rules apply as for the [[Protocol_documentation#getblocks|getblocks]] packet.<br />
<br />
=== tx ===<br />
<br />
''tx'' describes a bitcoin transaction, in reply to ''[[#getdata|getdata]]''<br />
<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Transaction data format version (note, this is signed)<br />
|-<br />
| 1+ || tx_in count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction inputs<br />
|-<br />
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins<br />
|-<br />
| 1+ || tx_out count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction outputs<br />
|-<br />
| 9+ || tx_out || tx_out[] || A list of 1 or more transaction outputs or destinations for coins<br />
|-<br />
| 4 || lock_time || uint32_t || The block number or timestamp at which this transaction is locked:<br />
{|class="wikitable"<br />
! Value !! Description<br />
|-<br />
| 0 || Not locked<br />
|-<br />
| < 500000000 || Block number at which this transaction is locked<br />
|-<br />
| >= 500000000 || UNIX timestamp at which this transaction is locked<br />
|}<br />
If all TxIn inputs have final (0xffffffff) sequence numbers then lock_time is irrelevant. Otherwise, the transaction may not be added to a block until after lock_time (see [[NLockTime]]).<br />
<br />
|}<br />
<br />
TxIn consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 36 || previous_output || outpoint || The previous output transaction reference, as an OutPoint structure<br />
|-<br />
| 1+ || script length || [[Protocol_documentation#Variable_length_integer|var_int]] || The length of the signature script<br />
|-<br />
| ? || signature script || uchar[] || Computational Script for confirming transaction authorization<br />
|-<br />
| 4 || [http://bitcoin.stackexchange.com/q/2025/323 sequence] || uint32_t || Transaction version as defined by the sender. Intended for "replacement" of transactions when information is updated before inclusion into a block.<br />
|}<br />
<br />
The OutPoint structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 32 || hash || char[32] || The hash of the referenced transaction.<br />
|-<br />
| 4 || index || uint32_t || The index of the specific output in the transaction. The first output is 0, etc.<br />
|}<br />
<br />
The Script structure consists of a series of pieces of information and operations related to the value of the transaction.<br />
<br />
(Structure to be expanded in the future… see script.h and script.cpp and [[Script]] for more information)<br />
<br />
The TxOut structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || value || int64_t || Transaction Value<br />
|-<br />
| 1+ || pk_script length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the pk_script<br />
|-<br />
| ? || pk_script || uchar[] || Usually contains the public key as a Bitcoin script setting up conditions to claim this output.<br />
|}<br />
<br />
Example ''tx'' message:<br />
<pre><br />
000000 F9 BE B4 D9 74 78 00 00 00 00 00 00 00 00 00 00 ....tx..........<br />
000010 02 01 00 00 E2 93 CD BE 01 00 00 00 01 6D BD DB .............m..<br />
000020 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D 12 66 E9 .[...Q........f.<br />
000030 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29 00 00 00 .;P......j.6)...<br />
000040 00 8B 48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 ..H0E.!..X..r...<br />
000050 C7 36 7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A .6zz%;..R#...h.:<br />
000060 59 23 3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 Y#?E.W... Y.....<br />
000070 0E 41 83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D .A.z.X.z...XN...<br />
000080 35 BD 96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF 5...6..;...A....<br />
000090 C9 7E F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 .~.6.m...@..!...<br />
0000A0 2A CD 2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC *.+..].}Y... ...<br />
0000B0 4E 02 53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F N.S..=7.o...Q...<br />
0000C0 14 04 2F 46 61 4A 4C 70 C0 F1 4B EF F5 FF FF FF ../FaJLp..K.....<br />
0000D0 FF 02 40 4B 4C 00 00 00 00 00 19 76 A9 14 1A A0 ..@KL......v....<br />
0000E0 CD 1C BE A6 E7 45 8A 7A BA D5 12 A9 D9 EA 1A FB .....E.z........<br />
0000F0 22 5E 88 AC 80 FA E9 C7 00 00 00 00 19 76 A9 14 "^...........v..<br />
000100 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E FD A0 B7 ..[.Cj.....H^...<br />
000110 8B 4E CC 52 88 AC 00 00 00 00 .N.R......<br />
<br />
<br />
Message header:<br />
F9 BE B4 D9 - main network magic bytes<br />
74 78 00 00 00 00 00 00 00 00 00 00 - "tx" command<br />
02 01 00 00 - payload is 258 bytes long<br />
E2 93 CD BE - checksum of payload<br />
<br />
Transaction:<br />
01 00 00 00 - version<br />
<br />
Inputs:<br />
01 - number of transaction inputs<br />
<br />
Input 1:<br />
6D BD DB 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D - previous output (outpoint)<br />
12 66 E9 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29<br />
00 00 00 00<br />
<br />
8B - script is 139 bytes long<br />
<br />
48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 C7 36 - signature script (scriptSig)<br />
7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A 59 23<br />
3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 0E 41<br />
83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D 35 BD<br />
96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF C9 7E<br />
F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 2A CD<br />
2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC 4E 02<br />
53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F 14 04<br />
2F 46 61 4A 4C 70 C0 F1 4B EF F5<br />
<br />
FF FF FF FF - sequence<br />
<br />
Outputs:<br />
02 - 2 Output Transactions<br />
<br />
Output 1:<br />
40 4B 4C 00 00 00 00 00 - 0.05 BTC (5000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 1A A0 CD 1C BE A6 E7 45 8A 7A BA D5 12 - pk_script<br />
A9 D9 EA 1A FB 22 5E 88 AC<br />
<br />
Output 2:<br />
80 FA E9 C7 00 00 00 00 - 33.54 BTC (3354000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E - pk_script<br />
FD A0 B7 8B 4E CC 52 88 AC<br />
<br />
Locktime:<br />
00 00 00 00 - lock time<br />
</pre><br />
<br />
=== block ===<br />
<br />
The '''block''' message is sent in response to a getdata message which requests transaction information from a block hash.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A Unix timestamp recording when this block was created (Currently limited to dates before the year 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated [[Difficulty|difficulty target]] being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| ? || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries<br />
|-<br />
| ? || txns || tx[] || Block transactions, in format of "tx" command<br />
|}<br />
<br />
The SHA256 hash that identifies each block (and which must have a run of 0 bits) is calculated from the first 6 fields of this structure (version, prev_block, merkle_root, timestamp, bits, nonce, and standard SHA256 padding, making two 64-byte chunks in all) and ''not'' from the complete block. To calculate the hash, only two chunks need to be processed by the SHA256 algorithm. Since the ''nonce'' field is in the second chunk, the first chunk stays constant during mining and therefore only the second chunk needs to be processed. However, a Bitcoin hash is the hash of the hash, so two SHA256 rounds are needed for each mining iteration.<br />
See [[Block hashing algorithm]] for details and an example.<br />
<br />
=== headers ===<br />
<br />
The ''headers'' packet returns block headers in response to a ''getheaders'' packet. <br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of block headers<br />
|-<br />
| 81x? || headers || [[Protocol_documentation#Block_Headers|block_header]][] || [[Protocol_documentation#Block_Headers|Block headers]]<br />
|}<br />
<br />
Note that the block headers in this packet include a transaction count (a var_int, so there can be more than 81 bytes per header) as opposed to the block headers that are hashed by miners.<br />
<br />
=== getaddr ===<br />
<br />
The getaddr message sends a request to a node asking for information about known active peers to help with finding potential nodes in the network. The response to receiving this message is to transmit one or more addr messages with one or more peers from a database of known active peers. The typical presumption is that a node is likely to be active if it has been sending a message within the last three hours.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
=== mempool ===<br />
<br />
The mempool message sends a request to a node asking for information about transactions it has verified but which have not yet confirmed. The response to receiving this message is an inv message containing the transaction hashes for all the transactions in the node's mempool.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
It is specified in [https://github.com/bitcoin/bips/blob/master/bip-0035.mediawiki BIP 35]. Since [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 37], if a [[Protocol_documentation#filterload.2C_filteradd.2C_filterclear.2C_merkleblock|bloom filter]] is loaded, only transactions matching the filter are replied.<br />
<br />
=== checkorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== submitorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== reply ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== ping ===<br />
<br />
The ''ping'' message is sent primarily to confirm that the TCP/IP connection is still valid. An error in transmission is presumed to be a closed connection and the address is removed as a current peer.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || random nonce<br />
|}<br />
<br />
=== pong ===<br />
<br />
The ''pong'' message is sent in response to a ''ping'' message. In modern protocol versions, a ''pong'' response is generated using a nonce included in the ping.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || nonce from ping<br />
|}<br />
<br />
<br />
=== reject===<br />
<br />
The ''reject'' message is sent when messages are rejected.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || message || var_str || type of message rejected<br />
|-<br />
| 1 || ccode || char || code relating to rejected message<br />
|-<br />
| 1+ || reason || var_str || text version of reason for rejection<br />
|-<br />
| 0+ || data || char || Optional extra data provided by some errors. Currently, all errors which provide this field fill it with the TXID or block header hash of the object being rejected, so the field is 32 bytes.<br />
|}<br />
<br />
CCodes<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0x01 || REJECT_MALFORMED|| <br />
|-<br />
| 0x10 || REJECT_INVALID ||<br />
|-<br />
| 0x11 || REJECT_OBSOLETE ||<br />
|-<br />
| 0x12 || REJECT_DUPLICATE ||<br />
|-<br />
| 0x40 || REJECT_NONSTANDARD ||<br />
|-<br />
| 0x41 || REJECT_DUST ||<br />
|-<br />
| 0x42 || REJECT_INSUFFICIENTFEE ||<br />
|-<br />
| 0x43 || REJECT_CHECKPOINT ||<br />
|}<br />
<br />
=== filterload, filteradd, filterclear, merkleblock ===<br />
<br />
These messages are related to Bloom filtering of connections and are defined in [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037].<br />
<br />
<br />
The <code>filterload</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || filter || uint8_t[] || The filter itself is simply a bit field of arbitrary byte-aligned size. The maximum size is 36,000 bytes.<br />
|-<br />
| 4 || nHashFuncs || uint32_t || The number of hash functions to use in this filter. The maximum value allowed in this field is 50.<br />
|-<br />
| 4 || nTweak || uint32_t || A random value to add to the seed value in the hash function used by the bloom filter.<br />
|-<br />
| 1 || nFlags || uint8_t || A set of flags that control how matched items are added to the filter.<br />
|}<br />
<br />
See below for a description of the Bloom filter algorithm and how to select nHashFuncs and filter size for a desired false positive rate.<br />
<br />
Upon receiving a <code>filterload</code> command, the remote peer will immediately restrict the broadcast transactions it announces (in inv packets) to transactions matching the filter, where the matching algorithm is specified below. The flags control the update behaviour of the matching algorithm.<br />
<br />
The <code>filteradd</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || data || uint8_t[] || The data element to add to the current filter.<br />
|}<br />
<br />
The data field must be smaller than or equal to 520 bytes in size (the maximum size of any potentially matched object).<br />
<br />
The given data element will be added to the Bloom filter. A filter must have been previously provided using <code>filterload</code>. This command is useful if a new key or script is added to a clients wallet whilst it has connections to the network open, it avoids the need to re-calculate and send an entirely new filter to every peer (though doing so is usually advisable to maintain anonymity).<br />
<br />
The <code>filterclear</code> command has no arguments at all.<br />
<br />
After a filter has been set, nodes don't merely stop announcing non-matching transactions, they can also serve filtered blocks. A filtered block is defined by the <code>merkleblock</code> message and is defined like this:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information, based upon the software version creating this block (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Limited to 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 4 || total_transactions || uint32_t || Number of transactions in the block (including unmatched ones)<br />
|-<br />
| ? || hashes || uint256[] || hashes in depth-first order (including standard varint size prefix)<br />
|-<br />
| ? || flags || byte[] || flag bits, packed per 8 in a byte, least significant bit first (including standard varint size prefix)<br />
|}<br />
<br />
=== alert ===<br />
<br />
An '''alert''' is sent between nodes to send a general notification message throughout the network. If the alert can be confirmed with the signature as having come from the core development group of the Bitcoin software, the message is suggested to be displayed for end-users. Attempts to perform transactions, particularly automated transactions through the client, are suggested to be halted. The text in the Message string should be relayed to log files and any user interfaces.<br />
<br />
Alert format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || payload || uchar[] || Serialized alert payload<br />
|-<br />
| ? || signature || uchar[] || An ECDSA signature of the message<br />
|}<br />
<br />
The developers of Satoshi's client use this public key for signing alerts:<br />
04fc9702847840aaf195de8442ebecedf5b095cdbb9bc716bda9110971b28a49e0ead8564ff0db22209e0374782c093bb899692d524e9d6a6956e7c5ecbcd68284<br />
(hash) 1AGRxqDa5WjUKBwHB9XYEjmkv1ucoUUy1s<br />
<br />
The payload is serialized into a uchar[] to ensure that versions using incompatible alert formats can still relay alerts among one another. The current alert payload format is:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || Version || int32_t || Alert format version<br />
|-<br />
| 8 || RelayUntil || int64_t || The timestamp beyond which nodes should stop relaying this alert<br />
|-<br />
| 8 || Expiration || int64_t || The timestamp beyond which this alert is no longer in effect and should be ignored<br />
|-<br />
| 4 || ID || int32_t || A unique ID number for this alert<br />
|-<br />
| 4 || Cancel || int32_t || All alerts with an ID number less than or equal to this number should be cancelled: deleted and not accepted in the future<br />
|-<br />
| ? || setCancel || set<int32_t> || All alert IDs contained in this set should be cancelled as above<br />
|-<br />
| 4 || MinVer || int32_t || This alert only applies to versions greater than or equal to this version. Other versions should still relay it.<br />
|-<br />
| 4 || MaxVer || int32_t || This alert only applies to versions less than or equal to this version. Other versions should still relay it.<br />
|-<br />
| ? || setSubVer || set<string> || If this set contains any elements, then only nodes that have their subVer contained in this set are affected by the alert. Other versions should still relay it.<br />
|-<br />
| 4 || Priority || int32_t || Relative priority compared to other alerts<br />
|-<br />
| ? || Comment || string || A comment on the alert that is not displayed<br />
|-<br />
| ? || StatusBar || string || The alert message that is displayed to the user<br />
|-<br />
| ? || Reserved || string || Reserved<br />
|}<br />
<br />
Note: '''set<''type''>''' in the table above is a [[#Variable length integer | variable length integer]] followed by the number of fields of the given ''type'' (either int32_t or [[#Variable length string | variable length string]])<br />
<br />
Sample alert (no message header):<br />
73010000003766404f00000000b305434f00000000f2030000f1030000001027000048ee0000<br />
0064000000004653656520626974636f696e2e6f72672f666562323020696620796f75206861<br />
76652074726f75626c6520636f6e6e656374696e672061667465722032302046656272756172<br />
79004730450221008389df45f0703f39ec8c1cc42c13810ffcae14995bb648340219e353b63b<br />
53eb022009ec65e1c1aaeec1fd334c6b684bde2b3f573060d5b70c3a46723326e4e8a4f1<br />
<br />
Version: 1<br />
RelayUntil: 1329620535<br />
Expiration: 1329792435<br />
ID: 1010<br />
Cancel: 1009<br />
setCancel: <empty><br />
MinVer: 10000<br />
MaxVer: 61000<br />
setSubVer: <empty><br />
Priority: 100<br />
Comment: <empty><br />
StatusBar: "See bitcoin.org/feb20 if you have trouble connecting after 20 February"<br />
Reserved: <empty><br />
<br />
=== sendheaders ===<br />
<br />
Request for Direct headers announcement. <br />
<br />
Upon receipt of this message, the node is be permitted, but not required, to announce new blocks by '''headers''' command (instead of '''inv''' command).<br />
<br />
This message is supported by the protocol version >= 70012 or Bitcoin Core version >= 0.12.0.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0130.mediawiki BIP 130] for more information.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
<br />
=== feefilter ===<br />
<br />
The payload is always 8 bytes long and it encodes 64 bit integer value (LSB / little endian) of '''feerate'''.<br />
The value represents a minimal fee and is expressed in satoshis per 1000 bytes.<br />
<br />
Upon receipt of a "feefilter" message, the node will be permitted, but not required, to filter transaction invs for transactions that fall below the feerate provided in the feefilter message interpreted as satoshis per kilobyte.<br />
<br />
The fee filter is additive with a bloom filter for transactions so if an SPV client were to load a bloom filter and send a feefilter message, transactions would only be relayed if they passed both filters.<br />
<br />
Inv's generated from a mempool message are also subject to a fee filter if it exists.<br />
<br />
Feature discovery is enabled by checking protocol version >= 70013<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0133.mediawiki BIP 133] for more information.<br />
<br />
=== sendcmpct ===<br />
<br />
# The sendcmpct message is defined as a message containing a 1-byte integer followed by a 8-byte integer where pchCommand == "sendcmpct".<br />
# The first integer SHALL be interpreted as a boolean (and MUST have a value of either 1 or 0)<br />
# The second integer SHALL be interpreted as a little-endian version number. Nodes sending a sendcmpct message MUST currently set this value to 1.<br />
# Upon receipt of a "sendcmpct" message with the first and second integers set to 1, the node SHOULD announce new blocks by sending a cmpctblock message.<br />
# Upon receipt of a "sendcmpct" message with the first integer set to 0, the node SHOULD NOT announce new blocks by sending a cmpctblock message, but SHOULD announce new blocks by sending invs or headers, as defined by BIP130.<br />
# Upon receipt of a "sendcmpct" message with the second integer set to something other than 1, nodes MUST treat the peer as if they had not received the message (as it indicates the peer will provide an unexpected encoding in <br />
# cmpctblock, and/or other, messages). This allows future versions to send duplicate sendcmpct messages with different versions as a part of a version handshake for future versions.<br />
# Nodes SHOULD check for a protocol version of >= 70014 before sending sendcmpct messages.<br />
# Nodes MUST NOT send a request for a MSG_CMPCT_BLOCK object to a peer before having received a sendcmpct message from that peer.<br />
<br />
This message is only supported by protocol version >= 70014<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== cmpctblock ===<br />
<br />
# The cmpctblock message is defined as as a message containing a serialized [[Protocol_documentation#HeaderAndShortIDs|HeaderAndShortIDs]] message and pchCommand == "cmpctblock".<br />
# Upon receipt of a cmpctblock message after sending a sendcmpct message, nodes SHOULD calculate the [[Protocol_documentation#Short_transaction_ID|short transaction ID]] for each unconfirmed transaction they have available (ie in their mempool) and compare each to each short transaction ID in the cmpctblock message.<br />
# After finding already-available transactions, nodes which do not have all transactions available to reconstruct the full block SHOULD request the missing transactions using a getblocktxn message.<br />
# A node MUST NOT send a cmpctblock message unless they are able to respond to a getblocktxn message which requests every transaction in the block.<br />
# A node MUST NOT send a cmpctblock message without having validated that the header properly commits to each transaction in the block, and properly builds on top of the existing chain with a valid proof-of-work. A node MAY send a cmpctblock before validating that each transaction in the block validly spends existing UTXO set entries.<br />
<br />
This message is only supported by protocol version >= 70014<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== getblocktxn ===<br />
<br />
# The getblocktxn message is defined as as a message containing a serialized BlockTransactionsRequest message and pchCommand == "getblocktxn".<br />
# Upon receipt of a properly-formatted getblocktxnmessage, nodes which recently provided the sender of such a message a cmpctblock for the block hash identified in this message MUST respond with an appropriate blocktxn message. Such a blocktxn message MUST contain exactly and only each transaction which is present in the appropriate block at the index specified in the getblocktxn indexes list, in the order requested.<br />
<br />
This message is only supported by protocol version >= 70014<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== blocktxn ===<br />
<br />
# The blocktxn message is defined as as a message containing a serialized BlockTransactions message and pchCommand == "blocktxn".<br />
# Upon receipt of a properly-formatted requested blocktxn message, nodes SHOULD attempt to reconstruct the full block by:<br />
# Taking the prefilledtxn transactions from the original cmpctblock and placing them in the marked positions.<br />
# For each short transaction ID from the original cmpctblock, in order, find the corresponding transaction either from the blocktxn message or from other sources and place it in the first available position in the block.<br />
# Once the block has been reconstructed, it shall be processed as normal, keeping in mind that short transaction IDs are expected to occasionally collide, and that nodes MUST NOT be penalized for such collisions, wherever they # appear.<br />
<br />
This message is only supported by protocol version >= 70014<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
== Scripting ==<br />
<br />
See [[script]].<br />
<br />
==See Also==<br />
<br />
* [[Network]]<br />
* [[Protocol rules]]<br />
* [[Hardfork Wishlist]]<br />
* [https://bitcoin.org/en/developer-documentation Developer Documentation on bitcoin.org]<br />
* Bitcoin dissectors for Wireshark: https://github.com/lbotsch/wireshark-bitcoin https://github.com/op-sig/bitcoin-wireshark-dissector<br />
<br />
==References==<br />
<references /><br />
<br />
[[zh-cn:协议说明]]<br />
[[Category:Technical]]<br />
[[Category:Developer]]<br />
<br />
{{Bitcoin Core documentation}}</div>Tonikthttps://en.bitcoin.it/w/index.php?title=Protocol_documentation&diff=61501Protocol documentation2016-08-25T13:16:24Z<p>Tonikt: /* cmpctblock */</p>
<hr />
<div>This page ''describes'' the behavior of the [[Original Bitcoin client|reference client]]. The Bitcoin protocol is specified by the behavior of the reference client, not by this page. In particular, while this page is quite complete in describing the network protocol, it does not attempt to list all of the rules for block or transaction validity.<br />
<br />
Type names used in this documentation are from the C99 standard.<br />
<br />
For protocol used in mining, see [[getblocktemplate]].<br />
<br />
==Common standards==<br />
<br />
=== Hashes ===<br />
<br />
Usually, when a hash is computed within bitcoin, it is computed twice. Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-256] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when a shorter hash is desirable (for example when creating a bitcoin address).<br />
<br />
Example of double-SHA-256 encoding of string "hello":<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round of sha-256)<br />
9595c9df90075148eb06860365df33584b75bff782a510c6cd4883a419833d50 (second round of sha-256)<br />
<br />
For bitcoin addresses (RIPEMD-160) this would give:<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round is sha-256)<br />
b6a9c8c230722b7c748331a8b450f05566dc7d0f (with ripemd-160)<br />
<br />
=== Merkle Trees ===<br />
<br />
Merkle trees are binary trees of hashes. Merkle trees in bitcoin use a '''double''' SHA-256, the SHA-256 hash of the SHA-256 hash of something.<br />
<br />
If, when forming a row in the tree (other than the root of the tree), it would have an odd number of elements, the final double-hash is duplicated to ensure that the row has an even number of hashes.<br />
<br />
First form the bottom row of the tree with the ordered double-SHA-256 hashes of the byte streams of the transactions in the block.<br />
<br />
Then the row above it consists of half that number of hashes. Each entry is the double-SHA-256 of the 64-byte concatenation of the corresponding two hashes below it in the tree.<br />
<br />
This procedure repeats recursively until we reach a row consisting of just a single double-hash. This is the '''Merkle root''' of the tree.<br />
<br />
For example, imagine a block with three transactions ''a'', ''b'' and ''c''. The Merkle tree is: <br />
<br />
d1 = dhash(a)<br />
d2 = dhash(b)<br />
d3 = dhash(c)<br />
d4 = dhash(c) # a, b, c are 3. that's an odd number, so we take the c twice<br />
<br />
d5 = dhash(d1 concat d2)<br />
d6 = dhash(d3 concat d4)<br />
<br />
d7 = dhash(d5 concat d6)<br />
<br />
where<br />
<br />
dhash(a) = sha256(sha256(a))<br />
<br />
''d7'' is the Merkle root of the 3 transactions in this block.<br />
<br />
Note: Hashes in Merkle Tree displayed in the [[Block Explorer]] are of little-endian notation. For some implementations and [http://www.fileformat.info/tool/hash.htm calculations], the bits need to be reversed before they are hashed, and again after the hashing operation.<br />
<br />
=== Signatures ===<br />
<br />
Bitcoin uses [http://en.wikipedia.org/wiki/Elliptic_curve_cryptography Elliptic Curve] [http://en.wikipedia.org/wiki/Digital_Signature_Algorithm Digital Signature Algorithm] ([http://en.wikipedia.org/wiki/Elliptic_Curve_DSA ECDSA]) to sign transactions. <br />
<br />
For [[ECDSA]] the secp256k1 curve from http://www.secg.org/collateral/sec2_final.pdf is used.<br />
<br />
Public keys (in scripts) are given as 04 <x> <y> where ''x'' and ''y'' are 32 byte big-endian integers representing the coordinates of a point on the curve or in compressed form given as <sign> <x> where <sign> is 0x02 if ''y'' is even and 0x03 if ''y'' is odd.<br />
<br />
Signatures use [http://en.wikipedia.org/wiki/Distinguished_Encoding_Rules DER encoding] to pack the ''r'' and ''s'' components into a single byte stream (this is also what OpenSSL produces by default).<br />
<br />
=== Transaction Verification ===<br />
Transactions are cryptographically signed records that reassign ownership of Bitcoins to new addresses. Transactions have ''inputs'' - records which reference the funds from other previous transactions - and ''outputs'' - records which determine the new owner of the transferred Bitcoins, and which will be referenced as inputs in future transactions as those funds are respent.<br />
<br />
Each ''input'' must have a cryptographic digital signature that unlocks the funds from the prior transaction. Only the person possessing the appropriate [[private key]] is able to create a satisfactory signature; this in effect ensures that funds can only be spent by their owners.<br />
<br />
Each ''output'' determines which Bitcoin address (or other criteria, see [[Script]]) is the recipient of the funds.<br />
<br />
In a transaction, the sum of all inputs must be equal to or greater than the sum of all outputs. If the inputs exceed the outputs, the difference is considered a [[transaction fee]], and is redeemable by whoever first includes the transaction into the block chain.<br />
<br />
A special kind of transaction, called a [[coinbase transaction]], has no inputs. It is created by [[miners]], and there is one coinbase transaction per block. Because each block comes with a reward of newly created Bitcoins (e.g. 50 BTC for the first 210,000 blocks), the first transaction of a block is, with few exceptions, the transaction that grants those coins to their recipient (the miner). In addition to the newly created Bitcoins, the coinbase transaction is also used for assigning the recipient of any transaction fees that were paid within the other transactions being included in the same block. The coinbase transaction can assign the entire reward to a single Bitcoin address, or split it in portions among multiple addresses, just like any other transaction. Coinbase transactions always contain outputs totalling the sum of the block reward plus all transaction fees collected from the other transactions in the same block.<br />
<br />
The [[coinbase transaction]] in block zero cannot be spent. This is due to a quirk of the reference client implementation that would open the potential for a block chain fork if some nodes accepted the spend and others did not<ref>[http://bitcointalk.org/index.php?topic=119645.msg1288552#msg1288552 Block 0 Network Fork]</ref>.<br />
<br />
Most Bitcoin outputs encumber the newly transferred coins with a single ECDSA private key. The actual record saved with inputs and outputs isn't necessarily a key, but a ''script''. Bitcoin uses an interpreted scripting system to determine whether an output's criteria have been satisfied, with which more complex operations are possible, such as outputs that require two ECDSA signatures, or two-of-three-signature schemes. An output that references a single Bitcoin address is a ''typical'' output; an output actually contains this information in the form of a script that requires a single ECDSA signature (see [[OP_CHECKSIG]]). The output script specifies what must be provided to unlock the funds later, and when the time comes in the future to spend the transaction in another input, that input must provide all of the thing(s) that satisfy the requirements defined by the original output script.<br />
<br />
=== Addresses ===<br />
<br />
A bitcoin address is in fact the hash of a ECDSA public key, computed this way:<br />
<br />
Version = 1 byte of 0 (zero); on the test network, this is 1 byte of 111<br />
Key hash = Version concatenated with RIPEMD-160(SHA-256(public key))<br />
Checksum = 1st 4 bytes of SHA-256(SHA-256(Key hash))<br />
Bitcoin Address = Base58Encode(Key hash concatenated with Checksum)<br />
<br />
The Base58 encoding used is home made, and has some differences. Especially, leading zeroes are kept as single zeroes when conversion happens.<br />
<br />
== Common structures ==<br />
<br />
Almost all integers are encoded in little endian. Only IP or port number are encoded big endian.<br />
<br />
=== Message structure ===<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown<br />
|-<br />
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| 4 || length || uint32_t || Length of payload in number of bytes<br />
|-<br />
| 4 || checksum || uint32_t || First 4 bytes of sha256(sha256(payload))<br />
|-<br />
| ? || payload || uchar[] || The actual data<br />
|}<br />
<br />
<br />
Known magic values:<br />
<br />
{|class="wikitable"<br />
! Network !! Magic value !! Sent over wire as<br />
|-<br />
| main || 0xD9B4BEF9 || F9 BE B4 D9<br />
|-<br />
| testnet || 0xDAB5BFFA || FA BF B5 DA<br />
|-<br />
| testnet3 || 0x0709110B || 0B 11 09 07<br />
|-<br />
| namecoin || 0xFEB4BEF9 || F9 BE B4 FE<br />
|}<br />
<br />
=== Variable length integer ===<br />
<br />
Integer can be encoded depending on the represented value to save space.<br />
Variable length integers always precede an array/vector of a type of data that may vary in length.<br />
Longer numbers are encoded in little endian.<br />
<br />
{|class="wikitable"<br />
! Value !! Storage length !! Format<br />
|-<br />
| < 0xFD || 1 || uint8_t<br />
|-<br />
| <= 0xFFFF || 3 || 0xFD followed by the length as uint16_t<br />
|-<br />
| <= 0xFFFF FFFF || 5 || 0xFE followed by the length as uint32_t<br />
|-<br />
| - || 9 || 0xFF followed by the length as uint64_t<br />
|}<br />
<br />
If you're reading the Satoshi client code (BitcoinQT) it refers to this encoding as a "CompactSize". Modern BitcoinQT also has the CVarInt class which implements an even more compact integer for the purpose of local storage (which is incompatible with "CompactSize" described here). CVarInt is not a part of the protocol.<br />
<br />
=== Variable length string ===<br />
<br />
Variable length string can be stored using a variable length integer followed by the string itself.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the string<br />
|-<br />
| ? || string || char[] || The string itself (can be empty)<br />
|}<br />
<br />
=== Network address ===<br />
<br />
When a network address is needed somewhere, this structure is used. Network addresses are not prefixed with a timestamp in the version message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || time || uint32 || the Time (version >= 31402). '''Not present in version message.'''<br />
|-<br />
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]<br />
|-<br />
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The original client only supported IPv4 and only read the last 4 bytes to get the IPv4 address. However, the IPv4 address is written into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]<br />
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).<br />
|-<br />
| 2 || port || uint16_t || port number, network byte order<br />
|}<br />
<br />
Hexdump example of Network address structure<br />
<br />
<pre><br />
0000 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0010 00 00 FF FF 0A 00 00 01 20 8D ........ .<br />
<br />
Network address:<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK: see services listed under version command)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv6: ::ffff:a00:1 or IPv4: 10.0.0.1<br />
20 8D - Port 8333<br />
</pre><br />
<br />
=== Inventory Vectors ===<br />
<br />
Inventory vectors are used for notifying other nodes about objects they have or data which is being requested.<br />
<br />
Inventory vectors consist of the following data format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || type || uint32_t || Identifies the object type linked to this inventory<br />
|-<br />
| 32 || hash || char[32] || Hash of the object<br />
|}<br />
<br />
<br />
The object type is currently defined as one of the following possibilities:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0 || ERROR || Any data of with this number may be ignored<br />
|-<br />
| 1 || MSG_TX || Hash is related to a transaction<br />
|-<br />
| 2 || MSG_BLOCK || Hash is related to a data block<br />
|-<br />
| 3 || MSG_FILTERED_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a merkleblock message rather than a block message; this only works if a bloom filter has been set.<br />
|-<br />
| 4 || MSG_CMPCT_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a cmpctblock message. See BIP 152 for more info.<br />
|}<br />
<br />
Other Data Type values are considered reserved for future implementations.<br />
<br />
=== Block Headers ===<br />
<br />
Block headers are sent in a headers packet in response to a getheaders message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Will overflow in 2106<ref>https://en.wikipedia.org/wiki/Unix_time#Notable_events_in_Unix_time</ref>)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 1 || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries, this value is always 0<br />
|}<br />
<br />
cf. [[Block hashing algorithm]]<br />
<br />
=== Differential encoding === <br />
Several uses of CompactSize below are "differentially encoded". For these, instead of using raw indexes, the number encoded is the difference between the current index and the previous index, minus one. For example, a first index of 0 implies a real index of 0, a second index of 0 thereafter refers to a real index of 1, etc.<br />
<br />
=== PrefilledTransaction ===<br />
<br />
A PrefilledTransaction structure is used in HeaderAndShortIDs to provide a list of a few transactions explicitly.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| index || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1, 3 bytes || Compact Size, differentially encoded since the last PrefilledTransaction in a list || The index into the block at which this transaction is<br />
|-<br />
| tx || Transaction || variable || As encoded in [[Protocol_documentation#tx|tx messages]] || The transaction which is in the block at index index.<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== HeaderAndShortIDs ===<br />
<br />
A HeaderAndShortIDs structure is used to relay a block header, the short transactions IDs used for matching already-available transactions, and a select few transactions which we expect a peer may be missing.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| header || Block header || 80 bytes || First 80 bytes of the block as defined by the encoding used by "block" messages || The header of the block being provided<br />
|-<br />
| nonce || uint64_t || 8 bytes || Little Endian || A nonce for use in short transaction ID calculations<br />
|-<br />
| shortids_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of short transaction IDs in shortids (ie block tx count - prefilledtxn_length)<br />
|-<br />
| shortids || List of 6-byte integers || 6*shortids_length bytes || Little Endian || The [[Protocol_documentation#Short_transaction_ID|short transaction IDs]] calculated from the transactions which were not provided explicitly in prefilledtxn<br />
|-<br />
| prefilledtxn_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of prefilled transactions in prefilledtxn (ie block tx count - shortids_length)<br />
|-<br />
| prefilledtxn || List of PrefilledTransactions || variable size*prefilledtxn_length || As defined by [[Protocol_documentation#PrefilledTransaction|PrefilledTransaction]] definition, above || Used to provide the coinbase transaction and a select few which we expect a peer may be missing<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== BlockTransactionsRequest ===<br />
<br />
A BlockTransactionsRequest structure is used to list transaction indexes in a block being requested.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| blockhash || Binary blob || 32 bytes || The output from a double-SHA256 of the block header, as used elsewhere || The blockhash of the block which the transactions being requested are in<br />
|-<br />
| indexes_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of transactions being requested<br />
|-<br />
| indexes || List of [[Protocol_documentation#Variable_length_integer|CompactSizes]] || 1 or 3 bytes*indexes_length || [[Protocol_documentation#Differential_encoding|Differentially encoded]] || The indexes of the transactions being requested in the block<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== BlockTransactions ===<br />
<br />
A BlockTransactions structure is used to provide some of the transactions in a block, as requested.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| blockhash || Binary blob || 32 bytes || The output from a double-SHA256 of the block header, as used elsewhere || The blockhash of the block which the transactions being provided are in<br />
|-<br />
| transactions_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of transactions provided<br />
|-<br />
| transactions || List of Transactions || variable || As encoded in [[Protocol_documentation#tx|tx messages]] || The transactions provided<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== Short transaction ID ===<br />
<br />
Short transaction IDs are used to represent a transaction without sending a full 256-bit hash. They are calculated by:<br />
<br />
# single-SHA256 hashing the block header with the nonce appended (in little-endian)<br />
# Running SipHash-2-4 with the input being the transaction ID and the keys (k0/k1) set to the first two little-endian 64-bit integers from the above hash, respectively.<br />
# Dropping the 2 most significant bytes from the SipHash output to make it 6 bytes.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
== Message types ==<br />
<br />
=== version ===<br />
<br />
When a node creates an outgoing connection, it will immediately [[Version Handshake|advertise]] its version. The remote node will respond with its version. No further communication is possible until both peers have exchanged their version.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Identifies protocol version being used by the node<br />
|-<br />
| 8 || services || uint64_t || bitfield of features to be enabled for this connection<br />
|-<br />
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds<br />
|-<br />
| 26 || addr_recv || [[#Network address|net_addr]] || The network address of the node receiving this message<br />
|-<br />
|colspan="4"| Fields below require version ≥ 106<br />
|-<br />
| 26 || addr_from || [[#Network address|net_addr]] || The network address of the node emitting this message<br />
|-<br />
| 8 || nonce || uint64_t || Node random nonce, randomly generated every time a version packet is sent. This nonce is used to detect connections to self.<br />
|-<br />
| ? || user_agent || [[#Variable length string|var_str]] || [https://github.com/bitcoin/bips/blob/master/bip-0014.mediawiki User Agent] (0x00 if string is 0 bytes long)<br />
|-<br />
| 4 || start_height || int32_t || The last block received by the emitting node<br />
|-<br />
|colspan="4"| Fields below require version ≥ 70001<br />
|-<br />
| 1 || relay || bool || Whether the remote peer should announce relayed transactions or not, see [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037]<br />
|}<br />
<br />
A "verack" packet shall be sent if the version packet was accepted.<br />
<br />
The following services are currently assigned:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 1 || NODE_NETWORK || This node can be asked for full blocks instead of just headers.<br />
|}<br />
<br />
Hexdump example of version message (OBSOLETE EXAMPLE: This example lacks a checksum and user-agent):<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....<br />
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........<br />
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............<br />
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................<br />
0040 20 8D 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,<br />
0060 3A B4 57 13 00 55 81 01 00 :.W..U...<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
55 00 00 00 - Payload is 85 bytes long<br />
- No checksum in version message until 20 February 2012. See https://bitcointalk.org/index.php?topic=55852.0<br />
Version message:<br />
9C 7C 00 00 - 31900 (version 0.3.19)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
E6 15 10 4D 00 00 00 00 - Mon Dec 20 21:50:14 EST 2010<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 20 8D - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D - Sender address info - see Network Address<br />
DD 9D 20 2C 3A B4 57 13 - Node random unique ID<br />
00 - "" sub-version string (string is 0 bytes long)<br />
55 81 01 00 - Last block sending node has is block #98645<br />
</pre><br />
<br />
And here's a modern (60002) protocol version client advertising itself to a local peer...<br />
<br />
Newer protocol includes the checksum now, this is from a mainline (satoshi) client during <br />
an outgoing connection to another local client, notice that it does not fill out the <br />
address information at all when the source or destination is "unroutable".<br />
<br />
<pre><br />
<br />
0000 f9 be b4 d9 76 65 72 73 69 6f 6e 00 00 00 00 00 ....version.....<br />
0010 64 00 00 00 35 8d 49 32 62 ea 00 00 01 00 00 00 d...5.I2b.......<br />
0020 00 00 00 00 11 b2 d0 50 00 00 00 00 01 00 00 00 .......P........<br />
0030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ff ff ................<br />
0040 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 00 00 00 00 ff ff 00 00 00 00 00 00 ................<br />
0060 3b 2e b3 5d 8c e6 17 65 0f 2f 53 61 74 6f 73 68 ;..]...e./Satosh<br />
0070 69 3a 30 2e 37 2e 32 2f c0 3e 03 00 i:0.7.2/.>..<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
64 00 00 00 - Payload is 100 bytes long<br />
3B 64 8D 5A - payload checksum<br />
<br />
Version message:<br />
62 EA 00 00 - 60002 (protocol version 60002)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
11 B2 D0 50 00 00 00 00 - Tue Dec 18 10:12:33 PST 2012<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Sender address info - see Network Address<br />
3B 2E B3 5D 8C E6 17 65 - Node ID<br />
0F 2F 53 61 74 6F 73 68 69 3A 30 2E 37 2E 32 2F - "/Satoshi:0.7.2/" sub-version string (string is 15 bytes long)<br />
C0 3E 03 00 - Last block sending node has is block #212672<br />
</pre><br />
<br />
=== verack ===<br />
<br />
The ''verack'' message is sent in reply to ''[[#version|version]]''. This message consists of only a [[#Message structure|message header]] with the command string "verack".<br />
<br />
Hexdump of the verack message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......<br />
0010 00 00 00 00 5D F6 E0 E2 ........<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 61 63 6B 00 00 00 00 00 00 - "verack" command<br />
00 00 00 00 - Payload is 0 bytes long<br />
5D F6 E0 E2 - Checksum<br />
</pre><br />
<br />
=== addr ===<br />
<br />
Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours<br />
<br />
Payload:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of address entries (max: 1000)<br />
|-<br />
| 30x? || addr_list || (uint32_t + [[#Network address|net_addr]])[] || Address of other nodes on the network. version < 209 will only read the first one. The uint32_t is a timestamp (see note below).<br />
|}<br />
<br />
'''Note''': Starting version 31402, addresses are prefixed with a timestamp. If no timestamp is present, the addresses should not be relayed to other peers, unless it is indeed confirmed they are up.<br />
<br />
Hexdump example of ''addr'' message:<br />
<pre><br />
0000 F9 BE B4 D9 61 64 64 72 00 00 00 00 00 00 00 00 ....addr........<br />
0010 1F 00 00 00 ED 52 39 9B 01 E2 15 10 4D 01 00 00 .....R9.....M...<br />
0020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF ................<br />
0030 FF 0A 00 00 01 20 8D ..... .<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
61 64 64 72 00 00 00 00 00 00 00 00 - "addr"<br />
1F 00 00 00 - payload is 31 bytes long<br />
ED 52 39 9B - checksum of payload<br />
<br />
Payload:<br />
01 - 1 address in this message<br />
<br />
Address:<br />
E2 15 10 4D - Mon Dec 20 21:50:10 EST 2010 (only when version is >= 31402)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK service - see version message)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv4: 10.0.0.1, IPv6: ::ffff:10.0.0.1 (IPv4-mapped IPv6 address)<br />
20 8D - port 8333<br />
</pre><br />
<br />
=== inv ===<br />
<br />
Allows a node to advertise its knowledge of one or more objects. It can be received unsolicited, or in reply to ''getblocks''.<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getdata ===<br />
<br />
getdata is used in response to inv, to retrieve the content of a specific object, and is usually sent after receiving an ''inv'' packet, after filtering known elements. It can be used to retrieve transactions, but only if they are in the memory pool or relay set - arbitrary access to transactions in the chain is not allowed to avoid having clients start to depend on nodes having full transaction indexes (which modern nodes do not).<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== notfound ===<br />
<br />
notfound is a response to a getdata, sent if any requested data items could not be relayed, for example, because the requested transaction was not in the memory pool or relay set.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getblocks ===<br />
<br />
Return an ''inv'' packet containing the list of blocks starting right after the last known hash in the block locator object, up to hash_stop or 500 blocks, whichever comes first. <br />
<br />
The locator hashes are processed by a node in the order as they appear in the message. If a block hash is found in the node's main chain, the list of its children is returned back via the ''inv'' message and the remaining locators are ignored, no matter if the requested limit was reached, or not.<br />
<br />
To receive the next blocks hashes, one needs to issue getblocks again with a new block locator object. Keep in mind that some clients may provide blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block; set to zero to get as many blocks as possible (500)<br />
|}<br />
<br />
To create the block locator hashes, keep pushing hashes until you go back to the genesis block. After pushing 10 hashes back, the step backwards doubles every loop:<br />
<br />
<pre><br />
// From libbitcoin which is under AGPL<br />
std::vector<size_t> block_locator_indexes(size_t top_height)<br />
{<br />
std::vector<size_t> indexes;<br />
<br />
// Modify the step in the iteration.<br />
int64_t step = 1;<br />
<br />
// Start at the top of the chain and work backwards.<br />
for (auto index = (int64_t)top_height; index > 0; index -= step)<br />
{<br />
// Push top 10 indexes first, then back off exponentially.<br />
if (indexes.size() >= 10)<br />
step *= 2;<br />
<br />
indexes.push_back((size_t)index);<br />
}<br />
<br />
// Push the genesis block index.<br />
indexes.push_back(0);<br />
return indexes;<br />
}<br />
</pre><br />
<br />
Note that it is allowed to send in fewer known hashes down to a minimum of just one hash. However, the purpose of the block locator object is to detect a wrong branch in the caller's main chain. If the peer detects that you are off the main chain, it will send in block hashes which are earlier than your last known block. So if you just send in your last known hash and it is off the main chain, the peer starts over at block #1.<br />
<br />
=== getheaders ===<br />
<br />
Return a ''headers'' packet containing the headers of blocks starting right after the last known hash in the block locator object, up to hash_stop or 2000 blocks, whichever comes first. To receive the next block headers, one needs to issue getheaders again with a new block locator object. The ''getheaders'' command is used by thin clients to quickly download the block chain where the contents of the transactions would be irrelevant (because they are not ours). Keep in mind that some clients may provide headers of blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block header; set to zero to get as many blocks as possible (2000)<br />
|}<br />
<br />
For the block locator object in this packet, the same rules apply as for the [[Protocol_documentation#getblocks|getblocks]] packet.<br />
<br />
=== tx ===<br />
<br />
''tx'' describes a bitcoin transaction, in reply to ''[[#getdata|getdata]]''<br />
<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Transaction data format version (note, this is signed)<br />
|-<br />
| 1+ || tx_in count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction inputs<br />
|-<br />
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins<br />
|-<br />
| 1+ || tx_out count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction outputs<br />
|-<br />
| 9+ || tx_out || tx_out[] || A list of 1 or more transaction outputs or destinations for coins<br />
|-<br />
| 4 || lock_time || uint32_t || The block number or timestamp at which this transaction is locked:<br />
{|class="wikitable"<br />
! Value !! Description<br />
|-<br />
| 0 || Not locked<br />
|-<br />
| < 500000000 || Block number at which this transaction is locked<br />
|-<br />
| >= 500000000 || UNIX timestamp at which this transaction is locked<br />
|}<br />
If all TxIn inputs have final (0xffffffff) sequence numbers then lock_time is irrelevant. Otherwise, the transaction may not be added to a block until after lock_time (see [[NLockTime]]).<br />
<br />
|}<br />
<br />
TxIn consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 36 || previous_output || outpoint || The previous output transaction reference, as an OutPoint structure<br />
|-<br />
| 1+ || script length || [[Protocol_documentation#Variable_length_integer|var_int]] || The length of the signature script<br />
|-<br />
| ? || signature script || uchar[] || Computational Script for confirming transaction authorization<br />
|-<br />
| 4 || [http://bitcoin.stackexchange.com/q/2025/323 sequence] || uint32_t || Transaction version as defined by the sender. Intended for "replacement" of transactions when information is updated before inclusion into a block.<br />
|}<br />
<br />
The OutPoint structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 32 || hash || char[32] || The hash of the referenced transaction.<br />
|-<br />
| 4 || index || uint32_t || The index of the specific output in the transaction. The first output is 0, etc.<br />
|}<br />
<br />
The Script structure consists of a series of pieces of information and operations related to the value of the transaction.<br />
<br />
(Structure to be expanded in the future… see script.h and script.cpp and [[Script]] for more information)<br />
<br />
The TxOut structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || value || int64_t || Transaction Value<br />
|-<br />
| 1+ || pk_script length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the pk_script<br />
|-<br />
| ? || pk_script || uchar[] || Usually contains the public key as a Bitcoin script setting up conditions to claim this output.<br />
|}<br />
<br />
Example ''tx'' message:<br />
<pre><br />
000000 F9 BE B4 D9 74 78 00 00 00 00 00 00 00 00 00 00 ....tx..........<br />
000010 02 01 00 00 E2 93 CD BE 01 00 00 00 01 6D BD DB .............m..<br />
000020 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D 12 66 E9 .[...Q........f.<br />
000030 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29 00 00 00 .;P......j.6)...<br />
000040 00 8B 48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 ..H0E.!..X..r...<br />
000050 C7 36 7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A .6zz%;..R#...h.:<br />
000060 59 23 3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 Y#?E.W... Y.....<br />
000070 0E 41 83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D .A.z.X.z...XN...<br />
000080 35 BD 96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF 5...6..;...A....<br />
000090 C9 7E F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 .~.6.m...@..!...<br />
0000A0 2A CD 2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC *.+..].}Y... ...<br />
0000B0 4E 02 53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F N.S..=7.o...Q...<br />
0000C0 14 04 2F 46 61 4A 4C 70 C0 F1 4B EF F5 FF FF FF ../FaJLp..K.....<br />
0000D0 FF 02 40 4B 4C 00 00 00 00 00 19 76 A9 14 1A A0 ..@KL......v....<br />
0000E0 CD 1C BE A6 E7 45 8A 7A BA D5 12 A9 D9 EA 1A FB .....E.z........<br />
0000F0 22 5E 88 AC 80 FA E9 C7 00 00 00 00 19 76 A9 14 "^...........v..<br />
000100 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E FD A0 B7 ..[.Cj.....H^...<br />
000110 8B 4E CC 52 88 AC 00 00 00 00 .N.R......<br />
<br />
<br />
Message header:<br />
F9 BE B4 D9 - main network magic bytes<br />
74 78 00 00 00 00 00 00 00 00 00 00 - "tx" command<br />
02 01 00 00 - payload is 258 bytes long<br />
E2 93 CD BE - checksum of payload<br />
<br />
Transaction:<br />
01 00 00 00 - version<br />
<br />
Inputs:<br />
01 - number of transaction inputs<br />
<br />
Input 1:<br />
6D BD DB 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D - previous output (outpoint)<br />
12 66 E9 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29<br />
00 00 00 00<br />
<br />
8B - script is 139 bytes long<br />
<br />
48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 C7 36 - signature script (scriptSig)<br />
7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A 59 23<br />
3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 0E 41<br />
83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D 35 BD<br />
96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF C9 7E<br />
F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 2A CD<br />
2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC 4E 02<br />
53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F 14 04<br />
2F 46 61 4A 4C 70 C0 F1 4B EF F5<br />
<br />
FF FF FF FF - sequence<br />
<br />
Outputs:<br />
02 - 2 Output Transactions<br />
<br />
Output 1:<br />
40 4B 4C 00 00 00 00 00 - 0.05 BTC (5000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 1A A0 CD 1C BE A6 E7 45 8A 7A BA D5 12 - pk_script<br />
A9 D9 EA 1A FB 22 5E 88 AC<br />
<br />
Output 2:<br />
80 FA E9 C7 00 00 00 00 - 33.54 BTC (3354000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E - pk_script<br />
FD A0 B7 8B 4E CC 52 88 AC<br />
<br />
Locktime:<br />
00 00 00 00 - lock time<br />
</pre><br />
<br />
=== block ===<br />
<br />
The '''block''' message is sent in response to a getdata message which requests transaction information from a block hash.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A Unix timestamp recording when this block was created (Currently limited to dates before the year 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated [[Difficulty|difficulty target]] being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| ? || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries<br />
|-<br />
| ? || txns || tx[] || Block transactions, in format of "tx" command<br />
|}<br />
<br />
The SHA256 hash that identifies each block (and which must have a run of 0 bits) is calculated from the first 6 fields of this structure (version, prev_block, merkle_root, timestamp, bits, nonce, and standard SHA256 padding, making two 64-byte chunks in all) and ''not'' from the complete block. To calculate the hash, only two chunks need to be processed by the SHA256 algorithm. Since the ''nonce'' field is in the second chunk, the first chunk stays constant during mining and therefore only the second chunk needs to be processed. However, a Bitcoin hash is the hash of the hash, so two SHA256 rounds are needed for each mining iteration.<br />
See [[Block hashing algorithm]] for details and an example.<br />
<br />
=== headers ===<br />
<br />
The ''headers'' packet returns block headers in response to a ''getheaders'' packet. <br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of block headers<br />
|-<br />
| 81x? || headers || [[Protocol_documentation#Block_Headers|block_header]][] || [[Protocol_documentation#Block_Headers|Block headers]]<br />
|}<br />
<br />
Note that the block headers in this packet include a transaction count (a var_int, so there can be more than 81 bytes per header) as opposed to the block headers that are hashed by miners.<br />
<br />
=== getaddr ===<br />
<br />
The getaddr message sends a request to a node asking for information about known active peers to help with finding potential nodes in the network. The response to receiving this message is to transmit one or more addr messages with one or more peers from a database of known active peers. The typical presumption is that a node is likely to be active if it has been sending a message within the last three hours.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
=== mempool ===<br />
<br />
The mempool message sends a request to a node asking for information about transactions it has verified but which have not yet confirmed. The response to receiving this message is an inv message containing the transaction hashes for all the transactions in the node's mempool.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
It is specified in [https://github.com/bitcoin/bips/blob/master/bip-0035.mediawiki BIP 35]. Since [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 37], if a [[Protocol_documentation#filterload.2C_filteradd.2C_filterclear.2C_merkleblock|bloom filter]] is loaded, only transactions matching the filter are replied.<br />
<br />
=== checkorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== submitorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== reply ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== ping ===<br />
<br />
The ''ping'' message is sent primarily to confirm that the TCP/IP connection is still valid. An error in transmission is presumed to be a closed connection and the address is removed as a current peer.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || random nonce<br />
|}<br />
<br />
=== pong ===<br />
<br />
The ''pong'' message is sent in response to a ''ping'' message. In modern protocol versions, a ''pong'' response is generated using a nonce included in the ping.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || nonce from ping<br />
|}<br />
<br />
<br />
=== reject===<br />
<br />
The ''reject'' message is sent when messages are rejected.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || message || var_str || type of message rejected<br />
|-<br />
| 1 || ccode || char || code relating to rejected message<br />
|-<br />
| 1+ || reason || var_str || text version of reason for rejection<br />
|-<br />
| 0+ || data || char || Optional extra data provided by some errors. Currently, all errors which provide this field fill it with the TXID or block header hash of the object being rejected, so the field is 32 bytes.<br />
|}<br />
<br />
CCodes<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0x01 || REJECT_MALFORMED|| <br />
|-<br />
| 0x10 || REJECT_INVALID ||<br />
|-<br />
| 0x11 || REJECT_OBSOLETE ||<br />
|-<br />
| 0x12 || REJECT_DUPLICATE ||<br />
|-<br />
| 0x40 || REJECT_NONSTANDARD ||<br />
|-<br />
| 0x41 || REJECT_DUST ||<br />
|-<br />
| 0x42 || REJECT_INSUFFICIENTFEE ||<br />
|-<br />
| 0x43 || REJECT_CHECKPOINT ||<br />
|}<br />
<br />
=== filterload, filteradd, filterclear, merkleblock ===<br />
<br />
These messages are related to Bloom filtering of connections and are defined in [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037].<br />
<br />
<br />
The <code>filterload</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || filter || uint8_t[] || The filter itself is simply a bit field of arbitrary byte-aligned size. The maximum size is 36,000 bytes.<br />
|-<br />
| 4 || nHashFuncs || uint32_t || The number of hash functions to use in this filter. The maximum value allowed in this field is 50.<br />
|-<br />
| 4 || nTweak || uint32_t || A random value to add to the seed value in the hash function used by the bloom filter.<br />
|-<br />
| 1 || nFlags || uint8_t || A set of flags that control how matched items are added to the filter.<br />
|}<br />
<br />
See below for a description of the Bloom filter algorithm and how to select nHashFuncs and filter size for a desired false positive rate.<br />
<br />
Upon receiving a <code>filterload</code> command, the remote peer will immediately restrict the broadcast transactions it announces (in inv packets) to transactions matching the filter, where the matching algorithm is specified below. The flags control the update behaviour of the matching algorithm.<br />
<br />
The <code>filteradd</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || data || uint8_t[] || The data element to add to the current filter.<br />
|}<br />
<br />
The data field must be smaller than or equal to 520 bytes in size (the maximum size of any potentially matched object).<br />
<br />
The given data element will be added to the Bloom filter. A filter must have been previously provided using <code>filterload</code>. This command is useful if a new key or script is added to a clients wallet whilst it has connections to the network open, it avoids the need to re-calculate and send an entirely new filter to every peer (though doing so is usually advisable to maintain anonymity).<br />
<br />
The <code>filterclear</code> command has no arguments at all.<br />
<br />
After a filter has been set, nodes don't merely stop announcing non-matching transactions, they can also serve filtered blocks. A filtered block is defined by the <code>merkleblock</code> message and is defined like this:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information, based upon the software version creating this block (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Limited to 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 4 || total_transactions || uint32_t || Number of transactions in the block (including unmatched ones)<br />
|-<br />
| ? || hashes || uint256[] || hashes in depth-first order (including standard varint size prefix)<br />
|-<br />
| ? || flags || byte[] || flag bits, packed per 8 in a byte, least significant bit first (including standard varint size prefix)<br />
|}<br />
<br />
=== alert ===<br />
<br />
An '''alert''' is sent between nodes to send a general notification message throughout the network. If the alert can be confirmed with the signature as having come from the core development group of the Bitcoin software, the message is suggested to be displayed for end-users. Attempts to perform transactions, particularly automated transactions through the client, are suggested to be halted. The text in the Message string should be relayed to log files and any user interfaces.<br />
<br />
Alert format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || payload || uchar[] || Serialized alert payload<br />
|-<br />
| ? || signature || uchar[] || An ECDSA signature of the message<br />
|}<br />
<br />
The developers of Satoshi's client use this public key for signing alerts:<br />
04fc9702847840aaf195de8442ebecedf5b095cdbb9bc716bda9110971b28a49e0ead8564ff0db22209e0374782c093bb899692d524e9d6a6956e7c5ecbcd68284<br />
(hash) 1AGRxqDa5WjUKBwHB9XYEjmkv1ucoUUy1s<br />
<br />
The payload is serialized into a uchar[] to ensure that versions using incompatible alert formats can still relay alerts among one another. The current alert payload format is:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || Version || int32_t || Alert format version<br />
|-<br />
| 8 || RelayUntil || int64_t || The timestamp beyond which nodes should stop relaying this alert<br />
|-<br />
| 8 || Expiration || int64_t || The timestamp beyond which this alert is no longer in effect and should be ignored<br />
|-<br />
| 4 || ID || int32_t || A unique ID number for this alert<br />
|-<br />
| 4 || Cancel || int32_t || All alerts with an ID number less than or equal to this number should be cancelled: deleted and not accepted in the future<br />
|-<br />
| ? || setCancel || set<int32_t> || All alert IDs contained in this set should be cancelled as above<br />
|-<br />
| 4 || MinVer || int32_t || This alert only applies to versions greater than or equal to this version. Other versions should still relay it.<br />
|-<br />
| 4 || MaxVer || int32_t || This alert only applies to versions less than or equal to this version. Other versions should still relay it.<br />
|-<br />
| ? || setSubVer || set<string> || If this set contains any elements, then only nodes that have their subVer contained in this set are affected by the alert. Other versions should still relay it.<br />
|-<br />
| 4 || Priority || int32_t || Relative priority compared to other alerts<br />
|-<br />
| ? || Comment || string || A comment on the alert that is not displayed<br />
|-<br />
| ? || StatusBar || string || The alert message that is displayed to the user<br />
|-<br />
| ? || Reserved || string || Reserved<br />
|}<br />
<br />
Note: '''set<''type''>''' in the table above is a [[#Variable length integer | variable length integer]] followed by the number of fields of the given ''type'' (either int32_t or [[#Variable length string | variable length string]])<br />
<br />
Sample alert (no message header):<br />
73010000003766404f00000000b305434f00000000f2030000f1030000001027000048ee0000<br />
0064000000004653656520626974636f696e2e6f72672f666562323020696620796f75206861<br />
76652074726f75626c6520636f6e6e656374696e672061667465722032302046656272756172<br />
79004730450221008389df45f0703f39ec8c1cc42c13810ffcae14995bb648340219e353b63b<br />
53eb022009ec65e1c1aaeec1fd334c6b684bde2b3f573060d5b70c3a46723326e4e8a4f1<br />
<br />
Version: 1<br />
RelayUntil: 1329620535<br />
Expiration: 1329792435<br />
ID: 1010<br />
Cancel: 1009<br />
setCancel: <empty><br />
MinVer: 10000<br />
MaxVer: 61000<br />
setSubVer: <empty><br />
Priority: 100<br />
Comment: <empty><br />
StatusBar: "See bitcoin.org/feb20 if you have trouble connecting after 20 February"<br />
Reserved: <empty><br />
<br />
=== sendheaders ===<br />
<br />
Request for Direct headers announcement. <br />
<br />
Upon receipt of this message, the node is be permitted, but not required, to announce new blocks by '''headers''' command (instead of '''inv''' command).<br />
<br />
This message is supported by the protocol version >= 70012 or Bitcoin Core version >= 0.12.0.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0130.mediawiki BIP 130] for more information.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
<br />
=== feefilter ===<br />
<br />
The payload is always 8 bytes long and it encodes 64 bit integer value (LSB / little endian) of '''feerate'''.<br />
The value represents a minimal fee and is expressed in satoshis per 1000 bytes.<br />
<br />
Upon receipt of a "feefilter" message, the node will be permitted, but not required, to filter transaction invs for transactions that fall below the feerate provided in the feefilter message interpreted as satoshis per kilobyte.<br />
<br />
The fee filter is additive with a bloom filter for transactions so if an SPV client were to load a bloom filter and send a feefilter message, transactions would only be relayed if they passed both filters.<br />
<br />
Inv's generated from a mempool message are also subject to a fee filter if it exists.<br />
<br />
Feature discovery is enabled by checking protocol version >= 70013<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0133.mediawiki BIP 133] for more information.<br />
<br />
=== sendcmpct ===<br />
<br />
# The sendcmpct message is defined as a message containing a 1-byte integer followed by a 8-byte integer where pchCommand == "sendcmpct".<br />
# The first integer SHALL be interpreted as a boolean (and MUST have a value of either 1 or 0)<br />
# The second integer SHALL be interpreted as a little-endian version number. Nodes sending a sendcmpct message MUST currently set this value to 1.<br />
# Upon receipt of a "sendcmpct" message with the first and second integers set to 1, the node SHOULD announce new blocks by sending a cmpctblock message.<br />
# Upon receipt of a "sendcmpct" message with the first integer set to 0, the node SHOULD NOT announce new blocks by sending a cmpctblock message, but SHOULD announce new blocks by sending invs or headers, as defined by BIP130.<br />
# Upon receipt of a "sendcmpct" message with the second integer set to something other than 1, nodes MUST treat the peer as if they had not received the message (as it indicates the peer will provide an unexpected encoding in <br />
# cmpctblock, and/or other, messages). This allows future versions to send duplicate sendcmpct messages with different versions as a part of a version handshake for future versions.<br />
# Nodes SHOULD check for a protocol version of >= 70014 before sending sendcmpct messages.<br />
# Nodes MUST NOT send a request for a MSG_CMPCT_BLOCK object to a peer before having received a sendcmpct message from that peer.<br />
<br />
This message is only supported by protocol version >= 70014<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== cmpctblock ===<br />
<br />
# The cmpctblock message is defined as as a message containing a serialized [[HeaderAndShortIDs|HeaderAndShortIDs]] message and pchCommand == "cmpctblock".<br />
# Upon receipt of a cmpctblock message after sending a sendcmpct message, nodes SHOULD calculate the [[Protocol_documentation#Short_transaction_ID|short transaction ID]] for each unconfirmed transaction they have available (ie in their mempool) and compare each to each short transaction ID in the cmpctblock message.<br />
# After finding already-available transactions, nodes which do not have all transactions available to reconstruct the full block SHOULD request the missing transactions using a getblocktxn message.<br />
# A node MUST NOT send a cmpctblock message unless they are able to respond to a getblocktxn message which requests every transaction in the block.<br />
# A node MUST NOT send a cmpctblock message without having validated that the header properly commits to each transaction in the block, and properly builds on top of the existing chain with a valid proof-of-work. A node MAY send a cmpctblock before validating that each transaction in the block validly spends existing UTXO set entries.<br />
<br />
This message is only supported by protocol version >= 70014<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== getblocktxn ===<br />
<br />
# The getblocktxn message is defined as as a message containing a serialized BlockTransactionsRequest message and pchCommand == "getblocktxn".<br />
# Upon receipt of a properly-formatted getblocktxnmessage, nodes which recently provided the sender of such a message a cmpctblock for the block hash identified in this message MUST respond with an appropriate blocktxn message. Such a blocktxn message MUST contain exactly and only each transaction which is present in the appropriate block at the index specified in the getblocktxn indexes list, in the order requested.<br />
<br />
This message is only supported by protocol version >= 70014<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== blocktxn ===<br />
<br />
# The blocktxn message is defined as as a message containing a serialized BlockTransactions message and pchCommand == "blocktxn".<br />
# Upon receipt of a properly-formatted requested blocktxn message, nodes SHOULD attempt to reconstruct the full block by:<br />
# Taking the prefilledtxn transactions from the original cmpctblock and placing them in the marked positions.<br />
# For each short transaction ID from the original cmpctblock, in order, find the corresponding transaction either from the blocktxn message or from other sources and place it in the first available position in the block.<br />
# Once the block has been reconstructed, it shall be processed as normal, keeping in mind that short transaction IDs are expected to occasionally collide, and that nodes MUST NOT be penalized for such collisions, wherever they # appear.<br />
<br />
This message is only supported by protocol version >= 70014<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
== Scripting ==<br />
<br />
See [[script]].<br />
<br />
==See Also==<br />
<br />
* [[Network]]<br />
* [[Protocol rules]]<br />
* [[Hardfork Wishlist]]<br />
* [https://bitcoin.org/en/developer-documentation Developer Documentation on bitcoin.org]<br />
* Bitcoin dissectors for Wireshark: https://github.com/lbotsch/wireshark-bitcoin https://github.com/op-sig/bitcoin-wireshark-dissector<br />
<br />
==References==<br />
<references /><br />
<br />
[[zh-cn:协议说明]]<br />
[[Category:Technical]]<br />
[[Category:Developer]]<br />
<br />
{{Bitcoin Core documentation}}</div>Tonikthttps://en.bitcoin.it/w/index.php?title=Protocol_documentation&diff=61500Protocol documentation2016-08-25T12:53:57Z<p>Tonikt: Added note "This message is only supported by protocol version >= 70014" to relevant messages</p>
<hr />
<div>This page ''describes'' the behavior of the [[Original Bitcoin client|reference client]]. The Bitcoin protocol is specified by the behavior of the reference client, not by this page. In particular, while this page is quite complete in describing the network protocol, it does not attempt to list all of the rules for block or transaction validity.<br />
<br />
Type names used in this documentation are from the C99 standard.<br />
<br />
For protocol used in mining, see [[getblocktemplate]].<br />
<br />
==Common standards==<br />
<br />
=== Hashes ===<br />
<br />
Usually, when a hash is computed within bitcoin, it is computed twice. Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-256] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when a shorter hash is desirable (for example when creating a bitcoin address).<br />
<br />
Example of double-SHA-256 encoding of string "hello":<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round of sha-256)<br />
9595c9df90075148eb06860365df33584b75bff782a510c6cd4883a419833d50 (second round of sha-256)<br />
<br />
For bitcoin addresses (RIPEMD-160) this would give:<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round is sha-256)<br />
b6a9c8c230722b7c748331a8b450f05566dc7d0f (with ripemd-160)<br />
<br />
=== Merkle Trees ===<br />
<br />
Merkle trees are binary trees of hashes. Merkle trees in bitcoin use a '''double''' SHA-256, the SHA-256 hash of the SHA-256 hash of something.<br />
<br />
If, when forming a row in the tree (other than the root of the tree), it would have an odd number of elements, the final double-hash is duplicated to ensure that the row has an even number of hashes.<br />
<br />
First form the bottom row of the tree with the ordered double-SHA-256 hashes of the byte streams of the transactions in the block.<br />
<br />
Then the row above it consists of half that number of hashes. Each entry is the double-SHA-256 of the 64-byte concatenation of the corresponding two hashes below it in the tree.<br />
<br />
This procedure repeats recursively until we reach a row consisting of just a single double-hash. This is the '''Merkle root''' of the tree.<br />
<br />
For example, imagine a block with three transactions ''a'', ''b'' and ''c''. The Merkle tree is: <br />
<br />
d1 = dhash(a)<br />
d2 = dhash(b)<br />
d3 = dhash(c)<br />
d4 = dhash(c) # a, b, c are 3. that's an odd number, so we take the c twice<br />
<br />
d5 = dhash(d1 concat d2)<br />
d6 = dhash(d3 concat d4)<br />
<br />
d7 = dhash(d5 concat d6)<br />
<br />
where<br />
<br />
dhash(a) = sha256(sha256(a))<br />
<br />
''d7'' is the Merkle root of the 3 transactions in this block.<br />
<br />
Note: Hashes in Merkle Tree displayed in the [[Block Explorer]] are of little-endian notation. For some implementations and [http://www.fileformat.info/tool/hash.htm calculations], the bits need to be reversed before they are hashed, and again after the hashing operation.<br />
<br />
=== Signatures ===<br />
<br />
Bitcoin uses [http://en.wikipedia.org/wiki/Elliptic_curve_cryptography Elliptic Curve] [http://en.wikipedia.org/wiki/Digital_Signature_Algorithm Digital Signature Algorithm] ([http://en.wikipedia.org/wiki/Elliptic_Curve_DSA ECDSA]) to sign transactions. <br />
<br />
For [[ECDSA]] the secp256k1 curve from http://www.secg.org/collateral/sec2_final.pdf is used.<br />
<br />
Public keys (in scripts) are given as 04 <x> <y> where ''x'' and ''y'' are 32 byte big-endian integers representing the coordinates of a point on the curve or in compressed form given as <sign> <x> where <sign> is 0x02 if ''y'' is even and 0x03 if ''y'' is odd.<br />
<br />
Signatures use [http://en.wikipedia.org/wiki/Distinguished_Encoding_Rules DER encoding] to pack the ''r'' and ''s'' components into a single byte stream (this is also what OpenSSL produces by default).<br />
<br />
=== Transaction Verification ===<br />
Transactions are cryptographically signed records that reassign ownership of Bitcoins to new addresses. Transactions have ''inputs'' - records which reference the funds from other previous transactions - and ''outputs'' - records which determine the new owner of the transferred Bitcoins, and which will be referenced as inputs in future transactions as those funds are respent.<br />
<br />
Each ''input'' must have a cryptographic digital signature that unlocks the funds from the prior transaction. Only the person possessing the appropriate [[private key]] is able to create a satisfactory signature; this in effect ensures that funds can only be spent by their owners.<br />
<br />
Each ''output'' determines which Bitcoin address (or other criteria, see [[Script]]) is the recipient of the funds.<br />
<br />
In a transaction, the sum of all inputs must be equal to or greater than the sum of all outputs. If the inputs exceed the outputs, the difference is considered a [[transaction fee]], and is redeemable by whoever first includes the transaction into the block chain.<br />
<br />
A special kind of transaction, called a [[coinbase transaction]], has no inputs. It is created by [[miners]], and there is one coinbase transaction per block. Because each block comes with a reward of newly created Bitcoins (e.g. 50 BTC for the first 210,000 blocks), the first transaction of a block is, with few exceptions, the transaction that grants those coins to their recipient (the miner). In addition to the newly created Bitcoins, the coinbase transaction is also used for assigning the recipient of any transaction fees that were paid within the other transactions being included in the same block. The coinbase transaction can assign the entire reward to a single Bitcoin address, or split it in portions among multiple addresses, just like any other transaction. Coinbase transactions always contain outputs totalling the sum of the block reward plus all transaction fees collected from the other transactions in the same block.<br />
<br />
The [[coinbase transaction]] in block zero cannot be spent. This is due to a quirk of the reference client implementation that would open the potential for a block chain fork if some nodes accepted the spend and others did not<ref>[http://bitcointalk.org/index.php?topic=119645.msg1288552#msg1288552 Block 0 Network Fork]</ref>.<br />
<br />
Most Bitcoin outputs encumber the newly transferred coins with a single ECDSA private key. The actual record saved with inputs and outputs isn't necessarily a key, but a ''script''. Bitcoin uses an interpreted scripting system to determine whether an output's criteria have been satisfied, with which more complex operations are possible, such as outputs that require two ECDSA signatures, or two-of-three-signature schemes. An output that references a single Bitcoin address is a ''typical'' output; an output actually contains this information in the form of a script that requires a single ECDSA signature (see [[OP_CHECKSIG]]). The output script specifies what must be provided to unlock the funds later, and when the time comes in the future to spend the transaction in another input, that input must provide all of the thing(s) that satisfy the requirements defined by the original output script.<br />
<br />
=== Addresses ===<br />
<br />
A bitcoin address is in fact the hash of a ECDSA public key, computed this way:<br />
<br />
Version = 1 byte of 0 (zero); on the test network, this is 1 byte of 111<br />
Key hash = Version concatenated with RIPEMD-160(SHA-256(public key))<br />
Checksum = 1st 4 bytes of SHA-256(SHA-256(Key hash))<br />
Bitcoin Address = Base58Encode(Key hash concatenated with Checksum)<br />
<br />
The Base58 encoding used is home made, and has some differences. Especially, leading zeroes are kept as single zeroes when conversion happens.<br />
<br />
== Common structures ==<br />
<br />
Almost all integers are encoded in little endian. Only IP or port number are encoded big endian.<br />
<br />
=== Message structure ===<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown<br />
|-<br />
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| 4 || length || uint32_t || Length of payload in number of bytes<br />
|-<br />
| 4 || checksum || uint32_t || First 4 bytes of sha256(sha256(payload))<br />
|-<br />
| ? || payload || uchar[] || The actual data<br />
|}<br />
<br />
<br />
Known magic values:<br />
<br />
{|class="wikitable"<br />
! Network !! Magic value !! Sent over wire as<br />
|-<br />
| main || 0xD9B4BEF9 || F9 BE B4 D9<br />
|-<br />
| testnet || 0xDAB5BFFA || FA BF B5 DA<br />
|-<br />
| testnet3 || 0x0709110B || 0B 11 09 07<br />
|-<br />
| namecoin || 0xFEB4BEF9 || F9 BE B4 FE<br />
|}<br />
<br />
=== Variable length integer ===<br />
<br />
Integer can be encoded depending on the represented value to save space.<br />
Variable length integers always precede an array/vector of a type of data that may vary in length.<br />
Longer numbers are encoded in little endian.<br />
<br />
{|class="wikitable"<br />
! Value !! Storage length !! Format<br />
|-<br />
| < 0xFD || 1 || uint8_t<br />
|-<br />
| <= 0xFFFF || 3 || 0xFD followed by the length as uint16_t<br />
|-<br />
| <= 0xFFFF FFFF || 5 || 0xFE followed by the length as uint32_t<br />
|-<br />
| - || 9 || 0xFF followed by the length as uint64_t<br />
|}<br />
<br />
If you're reading the Satoshi client code (BitcoinQT) it refers to this encoding as a "CompactSize". Modern BitcoinQT also has the CVarInt class which implements an even more compact integer for the purpose of local storage (which is incompatible with "CompactSize" described here). CVarInt is not a part of the protocol.<br />
<br />
=== Variable length string ===<br />
<br />
Variable length string can be stored using a variable length integer followed by the string itself.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the string<br />
|-<br />
| ? || string || char[] || The string itself (can be empty)<br />
|}<br />
<br />
=== Network address ===<br />
<br />
When a network address is needed somewhere, this structure is used. Network addresses are not prefixed with a timestamp in the version message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || time || uint32 || the Time (version >= 31402). '''Not present in version message.'''<br />
|-<br />
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]<br />
|-<br />
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The original client only supported IPv4 and only read the last 4 bytes to get the IPv4 address. However, the IPv4 address is written into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]<br />
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).<br />
|-<br />
| 2 || port || uint16_t || port number, network byte order<br />
|}<br />
<br />
Hexdump example of Network address structure<br />
<br />
<pre><br />
0000 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0010 00 00 FF FF 0A 00 00 01 20 8D ........ .<br />
<br />
Network address:<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK: see services listed under version command)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv6: ::ffff:a00:1 or IPv4: 10.0.0.1<br />
20 8D - Port 8333<br />
</pre><br />
<br />
=== Inventory Vectors ===<br />
<br />
Inventory vectors are used for notifying other nodes about objects they have or data which is being requested.<br />
<br />
Inventory vectors consist of the following data format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || type || uint32_t || Identifies the object type linked to this inventory<br />
|-<br />
| 32 || hash || char[32] || Hash of the object<br />
|}<br />
<br />
<br />
The object type is currently defined as one of the following possibilities:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0 || ERROR || Any data of with this number may be ignored<br />
|-<br />
| 1 || MSG_TX || Hash is related to a transaction<br />
|-<br />
| 2 || MSG_BLOCK || Hash is related to a data block<br />
|-<br />
| 3 || MSG_FILTERED_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a merkleblock message rather than a block message; this only works if a bloom filter has been set.<br />
|-<br />
| 4 || MSG_CMPCT_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a cmpctblock message. See BIP 152 for more info.<br />
|}<br />
<br />
Other Data Type values are considered reserved for future implementations.<br />
<br />
=== Block Headers ===<br />
<br />
Block headers are sent in a headers packet in response to a getheaders message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Will overflow in 2106<ref>https://en.wikipedia.org/wiki/Unix_time#Notable_events_in_Unix_time</ref>)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 1 || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries, this value is always 0<br />
|}<br />
<br />
cf. [[Block hashing algorithm]]<br />
<br />
=== Differential encoding === <br />
Several uses of CompactSize below are "differentially encoded". For these, instead of using raw indexes, the number encoded is the difference between the current index and the previous index, minus one. For example, a first index of 0 implies a real index of 0, a second index of 0 thereafter refers to a real index of 1, etc.<br />
<br />
=== PrefilledTransaction ===<br />
<br />
A PrefilledTransaction structure is used in HeaderAndShortIDs to provide a list of a few transactions explicitly.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| index || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1, 3 bytes || Compact Size, differentially encoded since the last PrefilledTransaction in a list || The index into the block at which this transaction is<br />
|-<br />
| tx || Transaction || variable || As encoded in [[Protocol_documentation#tx|tx messages]] || The transaction which is in the block at index index.<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== HeaderAndShortIDs ===<br />
<br />
A HeaderAndShortIDs structure is used to relay a block header, the short transactions IDs used for matching already-available transactions, and a select few transactions which we expect a peer may be missing.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| header || Block header || 80 bytes || First 80 bytes of the block as defined by the encoding used by "block" messages || The header of the block being provided<br />
|-<br />
| nonce || uint64_t || 8 bytes || Little Endian || A nonce for use in short transaction ID calculations<br />
|-<br />
| shortids_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of short transaction IDs in shortids (ie block tx count - prefilledtxn_length)<br />
|-<br />
| shortids || List of 6-byte integers || 6*shortids_length bytes || Little Endian || The [[Protocol_documentation#Short_transaction_ID|short transaction IDs]] calculated from the transactions which were not provided explicitly in prefilledtxn<br />
|-<br />
| prefilledtxn_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of prefilled transactions in prefilledtxn (ie block tx count - shortids_length)<br />
|-<br />
| prefilledtxn || List of PrefilledTransactions || variable size*prefilledtxn_length || As defined by [[Protocol_documentation#PrefilledTransaction|PrefilledTransaction]] definition, above || Used to provide the coinbase transaction and a select few which we expect a peer may be missing<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== BlockTransactionsRequest ===<br />
<br />
A BlockTransactionsRequest structure is used to list transaction indexes in a block being requested.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| blockhash || Binary blob || 32 bytes || The output from a double-SHA256 of the block header, as used elsewhere || The blockhash of the block which the transactions being requested are in<br />
|-<br />
| indexes_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of transactions being requested<br />
|-<br />
| indexes || List of [[Protocol_documentation#Variable_length_integer|CompactSizes]] || 1 or 3 bytes*indexes_length || [[Protocol_documentation#Differential_encoding|Differentially encoded]] || The indexes of the transactions being requested in the block<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== BlockTransactions ===<br />
<br />
A BlockTransactions structure is used to provide some of the transactions in a block, as requested.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| blockhash || Binary blob || 32 bytes || The output from a double-SHA256 of the block header, as used elsewhere || The blockhash of the block which the transactions being provided are in<br />
|-<br />
| transactions_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of transactions provided<br />
|-<br />
| transactions || List of Transactions || variable || As encoded in [[Protocol_documentation#tx|tx messages]] || The transactions provided<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== Short transaction ID ===<br />
<br />
Short transaction IDs are used to represent a transaction without sending a full 256-bit hash. They are calculated by:<br />
<br />
# single-SHA256 hashing the block header with the nonce appended (in little-endian)<br />
# Running SipHash-2-4 with the input being the transaction ID and the keys (k0/k1) set to the first two little-endian 64-bit integers from the above hash, respectively.<br />
# Dropping the 2 most significant bytes from the SipHash output to make it 6 bytes.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
== Message types ==<br />
<br />
=== version ===<br />
<br />
When a node creates an outgoing connection, it will immediately [[Version Handshake|advertise]] its version. The remote node will respond with its version. No further communication is possible until both peers have exchanged their version.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Identifies protocol version being used by the node<br />
|-<br />
| 8 || services || uint64_t || bitfield of features to be enabled for this connection<br />
|-<br />
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds<br />
|-<br />
| 26 || addr_recv || [[#Network address|net_addr]] || The network address of the node receiving this message<br />
|-<br />
|colspan="4"| Fields below require version ≥ 106<br />
|-<br />
| 26 || addr_from || [[#Network address|net_addr]] || The network address of the node emitting this message<br />
|-<br />
| 8 || nonce || uint64_t || Node random nonce, randomly generated every time a version packet is sent. This nonce is used to detect connections to self.<br />
|-<br />
| ? || user_agent || [[#Variable length string|var_str]] || [https://github.com/bitcoin/bips/blob/master/bip-0014.mediawiki User Agent] (0x00 if string is 0 bytes long)<br />
|-<br />
| 4 || start_height || int32_t || The last block received by the emitting node<br />
|-<br />
|colspan="4"| Fields below require version ≥ 70001<br />
|-<br />
| 1 || relay || bool || Whether the remote peer should announce relayed transactions or not, see [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037]<br />
|}<br />
<br />
A "verack" packet shall be sent if the version packet was accepted.<br />
<br />
The following services are currently assigned:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 1 || NODE_NETWORK || This node can be asked for full blocks instead of just headers.<br />
|}<br />
<br />
Hexdump example of version message (OBSOLETE EXAMPLE: This example lacks a checksum and user-agent):<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....<br />
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........<br />
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............<br />
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................<br />
0040 20 8D 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,<br />
0060 3A B4 57 13 00 55 81 01 00 :.W..U...<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
55 00 00 00 - Payload is 85 bytes long<br />
- No checksum in version message until 20 February 2012. See https://bitcointalk.org/index.php?topic=55852.0<br />
Version message:<br />
9C 7C 00 00 - 31900 (version 0.3.19)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
E6 15 10 4D 00 00 00 00 - Mon Dec 20 21:50:14 EST 2010<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 20 8D - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D - Sender address info - see Network Address<br />
DD 9D 20 2C 3A B4 57 13 - Node random unique ID<br />
00 - "" sub-version string (string is 0 bytes long)<br />
55 81 01 00 - Last block sending node has is block #98645<br />
</pre><br />
<br />
And here's a modern (60002) protocol version client advertising itself to a local peer...<br />
<br />
Newer protocol includes the checksum now, this is from a mainline (satoshi) client during <br />
an outgoing connection to another local client, notice that it does not fill out the <br />
address information at all when the source or destination is "unroutable".<br />
<br />
<pre><br />
<br />
0000 f9 be b4 d9 76 65 72 73 69 6f 6e 00 00 00 00 00 ....version.....<br />
0010 64 00 00 00 35 8d 49 32 62 ea 00 00 01 00 00 00 d...5.I2b.......<br />
0020 00 00 00 00 11 b2 d0 50 00 00 00 00 01 00 00 00 .......P........<br />
0030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ff ff ................<br />
0040 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 00 00 00 00 ff ff 00 00 00 00 00 00 ................<br />
0060 3b 2e b3 5d 8c e6 17 65 0f 2f 53 61 74 6f 73 68 ;..]...e./Satosh<br />
0070 69 3a 30 2e 37 2e 32 2f c0 3e 03 00 i:0.7.2/.>..<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
64 00 00 00 - Payload is 100 bytes long<br />
3B 64 8D 5A - payload checksum<br />
<br />
Version message:<br />
62 EA 00 00 - 60002 (protocol version 60002)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
11 B2 D0 50 00 00 00 00 - Tue Dec 18 10:12:33 PST 2012<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Sender address info - see Network Address<br />
3B 2E B3 5D 8C E6 17 65 - Node ID<br />
0F 2F 53 61 74 6F 73 68 69 3A 30 2E 37 2E 32 2F - "/Satoshi:0.7.2/" sub-version string (string is 15 bytes long)<br />
C0 3E 03 00 - Last block sending node has is block #212672<br />
</pre><br />
<br />
=== verack ===<br />
<br />
The ''verack'' message is sent in reply to ''[[#version|version]]''. This message consists of only a [[#Message structure|message header]] with the command string "verack".<br />
<br />
Hexdump of the verack message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......<br />
0010 00 00 00 00 5D F6 E0 E2 ........<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 61 63 6B 00 00 00 00 00 00 - "verack" command<br />
00 00 00 00 - Payload is 0 bytes long<br />
5D F6 E0 E2 - Checksum<br />
</pre><br />
<br />
=== addr ===<br />
<br />
Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours<br />
<br />
Payload:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of address entries (max: 1000)<br />
|-<br />
| 30x? || addr_list || (uint32_t + [[#Network address|net_addr]])[] || Address of other nodes on the network. version < 209 will only read the first one. The uint32_t is a timestamp (see note below).<br />
|}<br />
<br />
'''Note''': Starting version 31402, addresses are prefixed with a timestamp. If no timestamp is present, the addresses should not be relayed to other peers, unless it is indeed confirmed they are up.<br />
<br />
Hexdump example of ''addr'' message:<br />
<pre><br />
0000 F9 BE B4 D9 61 64 64 72 00 00 00 00 00 00 00 00 ....addr........<br />
0010 1F 00 00 00 ED 52 39 9B 01 E2 15 10 4D 01 00 00 .....R9.....M...<br />
0020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF ................<br />
0030 FF 0A 00 00 01 20 8D ..... .<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
61 64 64 72 00 00 00 00 00 00 00 00 - "addr"<br />
1F 00 00 00 - payload is 31 bytes long<br />
ED 52 39 9B - checksum of payload<br />
<br />
Payload:<br />
01 - 1 address in this message<br />
<br />
Address:<br />
E2 15 10 4D - Mon Dec 20 21:50:10 EST 2010 (only when version is >= 31402)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK service - see version message)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv4: 10.0.0.1, IPv6: ::ffff:10.0.0.1 (IPv4-mapped IPv6 address)<br />
20 8D - port 8333<br />
</pre><br />
<br />
=== inv ===<br />
<br />
Allows a node to advertise its knowledge of one or more objects. It can be received unsolicited, or in reply to ''getblocks''.<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getdata ===<br />
<br />
getdata is used in response to inv, to retrieve the content of a specific object, and is usually sent after receiving an ''inv'' packet, after filtering known elements. It can be used to retrieve transactions, but only if they are in the memory pool or relay set - arbitrary access to transactions in the chain is not allowed to avoid having clients start to depend on nodes having full transaction indexes (which modern nodes do not).<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== notfound ===<br />
<br />
notfound is a response to a getdata, sent if any requested data items could not be relayed, for example, because the requested transaction was not in the memory pool or relay set.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getblocks ===<br />
<br />
Return an ''inv'' packet containing the list of blocks starting right after the last known hash in the block locator object, up to hash_stop or 500 blocks, whichever comes first. <br />
<br />
The locator hashes are processed by a node in the order as they appear in the message. If a block hash is found in the node's main chain, the list of its children is returned back via the ''inv'' message and the remaining locators are ignored, no matter if the requested limit was reached, or not.<br />
<br />
To receive the next blocks hashes, one needs to issue getblocks again with a new block locator object. Keep in mind that some clients may provide blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block; set to zero to get as many blocks as possible (500)<br />
|}<br />
<br />
To create the block locator hashes, keep pushing hashes until you go back to the genesis block. After pushing 10 hashes back, the step backwards doubles every loop:<br />
<br />
<pre><br />
// From libbitcoin which is under AGPL<br />
std::vector<size_t> block_locator_indexes(size_t top_height)<br />
{<br />
std::vector<size_t> indexes;<br />
<br />
// Modify the step in the iteration.<br />
int64_t step = 1;<br />
<br />
// Start at the top of the chain and work backwards.<br />
for (auto index = (int64_t)top_height; index > 0; index -= step)<br />
{<br />
// Push top 10 indexes first, then back off exponentially.<br />
if (indexes.size() >= 10)<br />
step *= 2;<br />
<br />
indexes.push_back((size_t)index);<br />
}<br />
<br />
// Push the genesis block index.<br />
indexes.push_back(0);<br />
return indexes;<br />
}<br />
</pre><br />
<br />
Note that it is allowed to send in fewer known hashes down to a minimum of just one hash. However, the purpose of the block locator object is to detect a wrong branch in the caller's main chain. If the peer detects that you are off the main chain, it will send in block hashes which are earlier than your last known block. So if you just send in your last known hash and it is off the main chain, the peer starts over at block #1.<br />
<br />
=== getheaders ===<br />
<br />
Return a ''headers'' packet containing the headers of blocks starting right after the last known hash in the block locator object, up to hash_stop or 2000 blocks, whichever comes first. To receive the next block headers, one needs to issue getheaders again with a new block locator object. The ''getheaders'' command is used by thin clients to quickly download the block chain where the contents of the transactions would be irrelevant (because they are not ours). Keep in mind that some clients may provide headers of blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block header; set to zero to get as many blocks as possible (2000)<br />
|}<br />
<br />
For the block locator object in this packet, the same rules apply as for the [[Protocol_documentation#getblocks|getblocks]] packet.<br />
<br />
=== tx ===<br />
<br />
''tx'' describes a bitcoin transaction, in reply to ''[[#getdata|getdata]]''<br />
<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Transaction data format version (note, this is signed)<br />
|-<br />
| 1+ || tx_in count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction inputs<br />
|-<br />
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins<br />
|-<br />
| 1+ || tx_out count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction outputs<br />
|-<br />
| 9+ || tx_out || tx_out[] || A list of 1 or more transaction outputs or destinations for coins<br />
|-<br />
| 4 || lock_time || uint32_t || The block number or timestamp at which this transaction is locked:<br />
{|class="wikitable"<br />
! Value !! Description<br />
|-<br />
| 0 || Not locked<br />
|-<br />
| < 500000000 || Block number at which this transaction is locked<br />
|-<br />
| >= 500000000 || UNIX timestamp at which this transaction is locked<br />
|}<br />
If all TxIn inputs have final (0xffffffff) sequence numbers then lock_time is irrelevant. Otherwise, the transaction may not be added to a block until after lock_time (see [[NLockTime]]).<br />
<br />
|}<br />
<br />
TxIn consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 36 || previous_output || outpoint || The previous output transaction reference, as an OutPoint structure<br />
|-<br />
| 1+ || script length || [[Protocol_documentation#Variable_length_integer|var_int]] || The length of the signature script<br />
|-<br />
| ? || signature script || uchar[] || Computational Script for confirming transaction authorization<br />
|-<br />
| 4 || [http://bitcoin.stackexchange.com/q/2025/323 sequence] || uint32_t || Transaction version as defined by the sender. Intended for "replacement" of transactions when information is updated before inclusion into a block.<br />
|}<br />
<br />
The OutPoint structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 32 || hash || char[32] || The hash of the referenced transaction.<br />
|-<br />
| 4 || index || uint32_t || The index of the specific output in the transaction. The first output is 0, etc.<br />
|}<br />
<br />
The Script structure consists of a series of pieces of information and operations related to the value of the transaction.<br />
<br />
(Structure to be expanded in the future… see script.h and script.cpp and [[Script]] for more information)<br />
<br />
The TxOut structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || value || int64_t || Transaction Value<br />
|-<br />
| 1+ || pk_script length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the pk_script<br />
|-<br />
| ? || pk_script || uchar[] || Usually contains the public key as a Bitcoin script setting up conditions to claim this output.<br />
|}<br />
<br />
Example ''tx'' message:<br />
<pre><br />
000000 F9 BE B4 D9 74 78 00 00 00 00 00 00 00 00 00 00 ....tx..........<br />
000010 02 01 00 00 E2 93 CD BE 01 00 00 00 01 6D BD DB .............m..<br />
000020 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D 12 66 E9 .[...Q........f.<br />
000030 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29 00 00 00 .;P......j.6)...<br />
000040 00 8B 48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 ..H0E.!..X..r...<br />
000050 C7 36 7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A .6zz%;..R#...h.:<br />
000060 59 23 3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 Y#?E.W... Y.....<br />
000070 0E 41 83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D .A.z.X.z...XN...<br />
000080 35 BD 96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF 5...6..;...A....<br />
000090 C9 7E F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 .~.6.m...@..!...<br />
0000A0 2A CD 2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC *.+..].}Y... ...<br />
0000B0 4E 02 53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F N.S..=7.o...Q...<br />
0000C0 14 04 2F 46 61 4A 4C 70 C0 F1 4B EF F5 FF FF FF ../FaJLp..K.....<br />
0000D0 FF 02 40 4B 4C 00 00 00 00 00 19 76 A9 14 1A A0 ..@KL......v....<br />
0000E0 CD 1C BE A6 E7 45 8A 7A BA D5 12 A9 D9 EA 1A FB .....E.z........<br />
0000F0 22 5E 88 AC 80 FA E9 C7 00 00 00 00 19 76 A9 14 "^...........v..<br />
000100 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E FD A0 B7 ..[.Cj.....H^...<br />
000110 8B 4E CC 52 88 AC 00 00 00 00 .N.R......<br />
<br />
<br />
Message header:<br />
F9 BE B4 D9 - main network magic bytes<br />
74 78 00 00 00 00 00 00 00 00 00 00 - "tx" command<br />
02 01 00 00 - payload is 258 bytes long<br />
E2 93 CD BE - checksum of payload<br />
<br />
Transaction:<br />
01 00 00 00 - version<br />
<br />
Inputs:<br />
01 - number of transaction inputs<br />
<br />
Input 1:<br />
6D BD DB 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D - previous output (outpoint)<br />
12 66 E9 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29<br />
00 00 00 00<br />
<br />
8B - script is 139 bytes long<br />
<br />
48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 C7 36 - signature script (scriptSig)<br />
7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A 59 23<br />
3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 0E 41<br />
83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D 35 BD<br />
96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF C9 7E<br />
F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 2A CD<br />
2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC 4E 02<br />
53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F 14 04<br />
2F 46 61 4A 4C 70 C0 F1 4B EF F5<br />
<br />
FF FF FF FF - sequence<br />
<br />
Outputs:<br />
02 - 2 Output Transactions<br />
<br />
Output 1:<br />
40 4B 4C 00 00 00 00 00 - 0.05 BTC (5000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 1A A0 CD 1C BE A6 E7 45 8A 7A BA D5 12 - pk_script<br />
A9 D9 EA 1A FB 22 5E 88 AC<br />
<br />
Output 2:<br />
80 FA E9 C7 00 00 00 00 - 33.54 BTC (3354000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E - pk_script<br />
FD A0 B7 8B 4E CC 52 88 AC<br />
<br />
Locktime:<br />
00 00 00 00 - lock time<br />
</pre><br />
<br />
=== block ===<br />
<br />
The '''block''' message is sent in response to a getdata message which requests transaction information from a block hash.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A Unix timestamp recording when this block was created (Currently limited to dates before the year 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated [[Difficulty|difficulty target]] being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| ? || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries<br />
|-<br />
| ? || txns || tx[] || Block transactions, in format of "tx" command<br />
|}<br />
<br />
The SHA256 hash that identifies each block (and which must have a run of 0 bits) is calculated from the first 6 fields of this structure (version, prev_block, merkle_root, timestamp, bits, nonce, and standard SHA256 padding, making two 64-byte chunks in all) and ''not'' from the complete block. To calculate the hash, only two chunks need to be processed by the SHA256 algorithm. Since the ''nonce'' field is in the second chunk, the first chunk stays constant during mining and therefore only the second chunk needs to be processed. However, a Bitcoin hash is the hash of the hash, so two SHA256 rounds are needed for each mining iteration.<br />
See [[Block hashing algorithm]] for details and an example.<br />
<br />
=== headers ===<br />
<br />
The ''headers'' packet returns block headers in response to a ''getheaders'' packet. <br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of block headers<br />
|-<br />
| 81x? || headers || [[Protocol_documentation#Block_Headers|block_header]][] || [[Protocol_documentation#Block_Headers|Block headers]]<br />
|}<br />
<br />
Note that the block headers in this packet include a transaction count (a var_int, so there can be more than 81 bytes per header) as opposed to the block headers that are hashed by miners.<br />
<br />
=== getaddr ===<br />
<br />
The getaddr message sends a request to a node asking for information about known active peers to help with finding potential nodes in the network. The response to receiving this message is to transmit one or more addr messages with one or more peers from a database of known active peers. The typical presumption is that a node is likely to be active if it has been sending a message within the last three hours.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
=== mempool ===<br />
<br />
The mempool message sends a request to a node asking for information about transactions it has verified but which have not yet confirmed. The response to receiving this message is an inv message containing the transaction hashes for all the transactions in the node's mempool.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
It is specified in [https://github.com/bitcoin/bips/blob/master/bip-0035.mediawiki BIP 35]. Since [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 37], if a [[Protocol_documentation#filterload.2C_filteradd.2C_filterclear.2C_merkleblock|bloom filter]] is loaded, only transactions matching the filter are replied.<br />
<br />
=== checkorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== submitorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== reply ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== ping ===<br />
<br />
The ''ping'' message is sent primarily to confirm that the TCP/IP connection is still valid. An error in transmission is presumed to be a closed connection and the address is removed as a current peer.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || random nonce<br />
|}<br />
<br />
=== pong ===<br />
<br />
The ''pong'' message is sent in response to a ''ping'' message. In modern protocol versions, a ''pong'' response is generated using a nonce included in the ping.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || nonce from ping<br />
|}<br />
<br />
<br />
=== reject===<br />
<br />
The ''reject'' message is sent when messages are rejected.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || message || var_str || type of message rejected<br />
|-<br />
| 1 || ccode || char || code relating to rejected message<br />
|-<br />
| 1+ || reason || var_str || text version of reason for rejection<br />
|-<br />
| 0+ || data || char || Optional extra data provided by some errors. Currently, all errors which provide this field fill it with the TXID or block header hash of the object being rejected, so the field is 32 bytes.<br />
|}<br />
<br />
CCodes<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0x01 || REJECT_MALFORMED|| <br />
|-<br />
| 0x10 || REJECT_INVALID ||<br />
|-<br />
| 0x11 || REJECT_OBSOLETE ||<br />
|-<br />
| 0x12 || REJECT_DUPLICATE ||<br />
|-<br />
| 0x40 || REJECT_NONSTANDARD ||<br />
|-<br />
| 0x41 || REJECT_DUST ||<br />
|-<br />
| 0x42 || REJECT_INSUFFICIENTFEE ||<br />
|-<br />
| 0x43 || REJECT_CHECKPOINT ||<br />
|}<br />
<br />
=== filterload, filteradd, filterclear, merkleblock ===<br />
<br />
These messages are related to Bloom filtering of connections and are defined in [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037].<br />
<br />
<br />
The <code>filterload</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || filter || uint8_t[] || The filter itself is simply a bit field of arbitrary byte-aligned size. The maximum size is 36,000 bytes.<br />
|-<br />
| 4 || nHashFuncs || uint32_t || The number of hash functions to use in this filter. The maximum value allowed in this field is 50.<br />
|-<br />
| 4 || nTweak || uint32_t || A random value to add to the seed value in the hash function used by the bloom filter.<br />
|-<br />
| 1 || nFlags || uint8_t || A set of flags that control how matched items are added to the filter.<br />
|}<br />
<br />
See below for a description of the Bloom filter algorithm and how to select nHashFuncs and filter size for a desired false positive rate.<br />
<br />
Upon receiving a <code>filterload</code> command, the remote peer will immediately restrict the broadcast transactions it announces (in inv packets) to transactions matching the filter, where the matching algorithm is specified below. The flags control the update behaviour of the matching algorithm.<br />
<br />
The <code>filteradd</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || data || uint8_t[] || The data element to add to the current filter.<br />
|}<br />
<br />
The data field must be smaller than or equal to 520 bytes in size (the maximum size of any potentially matched object).<br />
<br />
The given data element will be added to the Bloom filter. A filter must have been previously provided using <code>filterload</code>. This command is useful if a new key or script is added to a clients wallet whilst it has connections to the network open, it avoids the need to re-calculate and send an entirely new filter to every peer (though doing so is usually advisable to maintain anonymity).<br />
<br />
The <code>filterclear</code> command has no arguments at all.<br />
<br />
After a filter has been set, nodes don't merely stop announcing non-matching transactions, they can also serve filtered blocks. A filtered block is defined by the <code>merkleblock</code> message and is defined like this:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information, based upon the software version creating this block (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Limited to 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 4 || total_transactions || uint32_t || Number of transactions in the block (including unmatched ones)<br />
|-<br />
| ? || hashes || uint256[] || hashes in depth-first order (including standard varint size prefix)<br />
|-<br />
| ? || flags || byte[] || flag bits, packed per 8 in a byte, least significant bit first (including standard varint size prefix)<br />
|}<br />
<br />
=== alert ===<br />
<br />
An '''alert''' is sent between nodes to send a general notification message throughout the network. If the alert can be confirmed with the signature as having come from the core development group of the Bitcoin software, the message is suggested to be displayed for end-users. Attempts to perform transactions, particularly automated transactions through the client, are suggested to be halted. The text in the Message string should be relayed to log files and any user interfaces.<br />
<br />
Alert format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || payload || uchar[] || Serialized alert payload<br />
|-<br />
| ? || signature || uchar[] || An ECDSA signature of the message<br />
|}<br />
<br />
The developers of Satoshi's client use this public key for signing alerts:<br />
04fc9702847840aaf195de8442ebecedf5b095cdbb9bc716bda9110971b28a49e0ead8564ff0db22209e0374782c093bb899692d524e9d6a6956e7c5ecbcd68284<br />
(hash) 1AGRxqDa5WjUKBwHB9XYEjmkv1ucoUUy1s<br />
<br />
The payload is serialized into a uchar[] to ensure that versions using incompatible alert formats can still relay alerts among one another. The current alert payload format is:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || Version || int32_t || Alert format version<br />
|-<br />
| 8 || RelayUntil || int64_t || The timestamp beyond which nodes should stop relaying this alert<br />
|-<br />
| 8 || Expiration || int64_t || The timestamp beyond which this alert is no longer in effect and should be ignored<br />
|-<br />
| 4 || ID || int32_t || A unique ID number for this alert<br />
|-<br />
| 4 || Cancel || int32_t || All alerts with an ID number less than or equal to this number should be cancelled: deleted and not accepted in the future<br />
|-<br />
| ? || setCancel || set<int32_t> || All alert IDs contained in this set should be cancelled as above<br />
|-<br />
| 4 || MinVer || int32_t || This alert only applies to versions greater than or equal to this version. Other versions should still relay it.<br />
|-<br />
| 4 || MaxVer || int32_t || This alert only applies to versions less than or equal to this version. Other versions should still relay it.<br />
|-<br />
| ? || setSubVer || set<string> || If this set contains any elements, then only nodes that have their subVer contained in this set are affected by the alert. Other versions should still relay it.<br />
|-<br />
| 4 || Priority || int32_t || Relative priority compared to other alerts<br />
|-<br />
| ? || Comment || string || A comment on the alert that is not displayed<br />
|-<br />
| ? || StatusBar || string || The alert message that is displayed to the user<br />
|-<br />
| ? || Reserved || string || Reserved<br />
|}<br />
<br />
Note: '''set<''type''>''' in the table above is a [[#Variable length integer | variable length integer]] followed by the number of fields of the given ''type'' (either int32_t or [[#Variable length string | variable length string]])<br />
<br />
Sample alert (no message header):<br />
73010000003766404f00000000b305434f00000000f2030000f1030000001027000048ee0000<br />
0064000000004653656520626974636f696e2e6f72672f666562323020696620796f75206861<br />
76652074726f75626c6520636f6e6e656374696e672061667465722032302046656272756172<br />
79004730450221008389df45f0703f39ec8c1cc42c13810ffcae14995bb648340219e353b63b<br />
53eb022009ec65e1c1aaeec1fd334c6b684bde2b3f573060d5b70c3a46723326e4e8a4f1<br />
<br />
Version: 1<br />
RelayUntil: 1329620535<br />
Expiration: 1329792435<br />
ID: 1010<br />
Cancel: 1009<br />
setCancel: <empty><br />
MinVer: 10000<br />
MaxVer: 61000<br />
setSubVer: <empty><br />
Priority: 100<br />
Comment: <empty><br />
StatusBar: "See bitcoin.org/feb20 if you have trouble connecting after 20 February"<br />
Reserved: <empty><br />
<br />
=== sendheaders ===<br />
<br />
Request for Direct headers announcement. <br />
<br />
Upon receipt of this message, the node is be permitted, but not required, to announce new blocks by '''headers''' command (instead of '''inv''' command).<br />
<br />
This message is supported by the protocol version >= 70012 or Bitcoin Core version >= 0.12.0.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0130.mediawiki BIP 130] for more information.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
<br />
=== feefilter ===<br />
<br />
The payload is always 8 bytes long and it encodes 64 bit integer value (LSB / little endian) of '''feerate'''.<br />
The value represents a minimal fee and is expressed in satoshis per 1000 bytes.<br />
<br />
Upon receipt of a "feefilter" message, the node will be permitted, but not required, to filter transaction invs for transactions that fall below the feerate provided in the feefilter message interpreted as satoshis per kilobyte.<br />
<br />
The fee filter is additive with a bloom filter for transactions so if an SPV client were to load a bloom filter and send a feefilter message, transactions would only be relayed if they passed both filters.<br />
<br />
Inv's generated from a mempool message are also subject to a fee filter if it exists.<br />
<br />
Feature discovery is enabled by checking protocol version >= 70013<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0133.mediawiki BIP 133] for more information.<br />
<br />
=== sendcmpct ===<br />
<br />
# The sendcmpct message is defined as a message containing a 1-byte integer followed by a 8-byte integer where pchCommand == "sendcmpct".<br />
# The first integer SHALL be interpreted as a boolean (and MUST have a value of either 1 or 0)<br />
# The second integer SHALL be interpreted as a little-endian version number. Nodes sending a sendcmpct message MUST currently set this value to 1.<br />
# Upon receipt of a "sendcmpct" message with the first and second integers set to 1, the node SHOULD announce new blocks by sending a cmpctblock message.<br />
# Upon receipt of a "sendcmpct" message with the first integer set to 0, the node SHOULD NOT announce new blocks by sending a cmpctblock message, but SHOULD announce new blocks by sending invs or headers, as defined by BIP130.<br />
# Upon receipt of a "sendcmpct" message with the second integer set to something other than 1, nodes MUST treat the peer as if they had not received the message (as it indicates the peer will provide an unexpected encoding in <br />
# cmpctblock, and/or other, messages). This allows future versions to send duplicate sendcmpct messages with different versions as a part of a version handshake for future versions.<br />
# Nodes SHOULD check for a protocol version of >= 70014 before sending sendcmpct messages.<br />
# Nodes MUST NOT send a request for a MSG_CMPCT_BLOCK object to a peer before having received a sendcmpct message from that peer.<br />
<br />
This message is only supported by protocol version >= 70014<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== cmpctblock ===<br />
<br />
# The cmpctblock message is defined as as a message containing a serialized HeaderAndShortIDs message and pchCommand == "cmpctblock".<br />
# Upon receipt of a cmpctblock message after sending a sendcmpct message, nodes SHOULD calculate the short transaction ID for each unconfirmed transaction they have available (ie in their mempool) and compare each to each short transaction ID in the cmpctblock message.<br />
# After finding already-available transactions, nodes which do not have all transactions available to reconstruct the full block SHOULD request the missing transactions using a getblocktxn message.<br />
# A node MUST NOT send a cmpctblock message unless they are able to respond to a getblocktxn message which requests every transaction in the block.<br />
# A node MUST NOT send a cmpctblock message without having validated that the header properly commits to each transaction in the block, and properly builds on top of the existing chain with a valid proof-of-work. A node MAY send a cmpctblock before validating that each transaction in the block validly spends existing UTXO set entries.<br />
<br />
This message is only supported by protocol version >= 70014<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== getblocktxn ===<br />
<br />
# The getblocktxn message is defined as as a message containing a serialized BlockTransactionsRequest message and pchCommand == "getblocktxn".<br />
# Upon receipt of a properly-formatted getblocktxnmessage, nodes which recently provided the sender of such a message a cmpctblock for the block hash identified in this message MUST respond with an appropriate blocktxn message. Such a blocktxn message MUST contain exactly and only each transaction which is present in the appropriate block at the index specified in the getblocktxn indexes list, in the order requested.<br />
<br />
This message is only supported by protocol version >= 70014<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== blocktxn ===<br />
<br />
# The blocktxn message is defined as as a message containing a serialized BlockTransactions message and pchCommand == "blocktxn".<br />
# Upon receipt of a properly-formatted requested blocktxn message, nodes SHOULD attempt to reconstruct the full block by:<br />
# Taking the prefilledtxn transactions from the original cmpctblock and placing them in the marked positions.<br />
# For each short transaction ID from the original cmpctblock, in order, find the corresponding transaction either from the blocktxn message or from other sources and place it in the first available position in the block.<br />
# Once the block has been reconstructed, it shall be processed as normal, keeping in mind that short transaction IDs are expected to occasionally collide, and that nodes MUST NOT be penalized for such collisions, wherever they # appear.<br />
<br />
This message is only supported by protocol version >= 70014<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
== Scripting ==<br />
<br />
See [[script]].<br />
<br />
==See Also==<br />
<br />
* [[Network]]<br />
* [[Protocol rules]]<br />
* [[Hardfork Wishlist]]<br />
* [https://bitcoin.org/en/developer-documentation Developer Documentation on bitcoin.org]<br />
* Bitcoin dissectors for Wireshark: https://github.com/lbotsch/wireshark-bitcoin https://github.com/op-sig/bitcoin-wireshark-dissector<br />
<br />
==References==<br />
<references /><br />
<br />
[[zh-cn:协议说明]]<br />
[[Category:Technical]]<br />
[[Category:Developer]]<br />
<br />
{{Bitcoin Core documentation}}</div>Tonikthttps://en.bitcoin.it/w/index.php?title=Protocol_documentation&diff=61499Protocol documentation2016-08-25T12:52:14Z<p>Tonikt: /* BlockTransactions */</p>
<hr />
<div>This page ''describes'' the behavior of the [[Original Bitcoin client|reference client]]. The Bitcoin protocol is specified by the behavior of the reference client, not by this page. In particular, while this page is quite complete in describing the network protocol, it does not attempt to list all of the rules for block or transaction validity.<br />
<br />
Type names used in this documentation are from the C99 standard.<br />
<br />
For protocol used in mining, see [[getblocktemplate]].<br />
<br />
==Common standards==<br />
<br />
=== Hashes ===<br />
<br />
Usually, when a hash is computed within bitcoin, it is computed twice. Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-256] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when a shorter hash is desirable (for example when creating a bitcoin address).<br />
<br />
Example of double-SHA-256 encoding of string "hello":<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round of sha-256)<br />
9595c9df90075148eb06860365df33584b75bff782a510c6cd4883a419833d50 (second round of sha-256)<br />
<br />
For bitcoin addresses (RIPEMD-160) this would give:<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round is sha-256)<br />
b6a9c8c230722b7c748331a8b450f05566dc7d0f (with ripemd-160)<br />
<br />
=== Merkle Trees ===<br />
<br />
Merkle trees are binary trees of hashes. Merkle trees in bitcoin use a '''double''' SHA-256, the SHA-256 hash of the SHA-256 hash of something.<br />
<br />
If, when forming a row in the tree (other than the root of the tree), it would have an odd number of elements, the final double-hash is duplicated to ensure that the row has an even number of hashes.<br />
<br />
First form the bottom row of the tree with the ordered double-SHA-256 hashes of the byte streams of the transactions in the block.<br />
<br />
Then the row above it consists of half that number of hashes. Each entry is the double-SHA-256 of the 64-byte concatenation of the corresponding two hashes below it in the tree.<br />
<br />
This procedure repeats recursively until we reach a row consisting of just a single double-hash. This is the '''Merkle root''' of the tree.<br />
<br />
For example, imagine a block with three transactions ''a'', ''b'' and ''c''. The Merkle tree is: <br />
<br />
d1 = dhash(a)<br />
d2 = dhash(b)<br />
d3 = dhash(c)<br />
d4 = dhash(c) # a, b, c are 3. that's an odd number, so we take the c twice<br />
<br />
d5 = dhash(d1 concat d2)<br />
d6 = dhash(d3 concat d4)<br />
<br />
d7 = dhash(d5 concat d6)<br />
<br />
where<br />
<br />
dhash(a) = sha256(sha256(a))<br />
<br />
''d7'' is the Merkle root of the 3 transactions in this block.<br />
<br />
Note: Hashes in Merkle Tree displayed in the [[Block Explorer]] are of little-endian notation. For some implementations and [http://www.fileformat.info/tool/hash.htm calculations], the bits need to be reversed before they are hashed, and again after the hashing operation.<br />
<br />
=== Signatures ===<br />
<br />
Bitcoin uses [http://en.wikipedia.org/wiki/Elliptic_curve_cryptography Elliptic Curve] [http://en.wikipedia.org/wiki/Digital_Signature_Algorithm Digital Signature Algorithm] ([http://en.wikipedia.org/wiki/Elliptic_Curve_DSA ECDSA]) to sign transactions. <br />
<br />
For [[ECDSA]] the secp256k1 curve from http://www.secg.org/collateral/sec2_final.pdf is used.<br />
<br />
Public keys (in scripts) are given as 04 <x> <y> where ''x'' and ''y'' are 32 byte big-endian integers representing the coordinates of a point on the curve or in compressed form given as <sign> <x> where <sign> is 0x02 if ''y'' is even and 0x03 if ''y'' is odd.<br />
<br />
Signatures use [http://en.wikipedia.org/wiki/Distinguished_Encoding_Rules DER encoding] to pack the ''r'' and ''s'' components into a single byte stream (this is also what OpenSSL produces by default).<br />
<br />
=== Transaction Verification ===<br />
Transactions are cryptographically signed records that reassign ownership of Bitcoins to new addresses. Transactions have ''inputs'' - records which reference the funds from other previous transactions - and ''outputs'' - records which determine the new owner of the transferred Bitcoins, and which will be referenced as inputs in future transactions as those funds are respent.<br />
<br />
Each ''input'' must have a cryptographic digital signature that unlocks the funds from the prior transaction. Only the person possessing the appropriate [[private key]] is able to create a satisfactory signature; this in effect ensures that funds can only be spent by their owners.<br />
<br />
Each ''output'' determines which Bitcoin address (or other criteria, see [[Script]]) is the recipient of the funds.<br />
<br />
In a transaction, the sum of all inputs must be equal to or greater than the sum of all outputs. If the inputs exceed the outputs, the difference is considered a [[transaction fee]], and is redeemable by whoever first includes the transaction into the block chain.<br />
<br />
A special kind of transaction, called a [[coinbase transaction]], has no inputs. It is created by [[miners]], and there is one coinbase transaction per block. Because each block comes with a reward of newly created Bitcoins (e.g. 50 BTC for the first 210,000 blocks), the first transaction of a block is, with few exceptions, the transaction that grants those coins to their recipient (the miner). In addition to the newly created Bitcoins, the coinbase transaction is also used for assigning the recipient of any transaction fees that were paid within the other transactions being included in the same block. The coinbase transaction can assign the entire reward to a single Bitcoin address, or split it in portions among multiple addresses, just like any other transaction. Coinbase transactions always contain outputs totalling the sum of the block reward plus all transaction fees collected from the other transactions in the same block.<br />
<br />
The [[coinbase transaction]] in block zero cannot be spent. This is due to a quirk of the reference client implementation that would open the potential for a block chain fork if some nodes accepted the spend and others did not<ref>[http://bitcointalk.org/index.php?topic=119645.msg1288552#msg1288552 Block 0 Network Fork]</ref>.<br />
<br />
Most Bitcoin outputs encumber the newly transferred coins with a single ECDSA private key. The actual record saved with inputs and outputs isn't necessarily a key, but a ''script''. Bitcoin uses an interpreted scripting system to determine whether an output's criteria have been satisfied, with which more complex operations are possible, such as outputs that require two ECDSA signatures, or two-of-three-signature schemes. An output that references a single Bitcoin address is a ''typical'' output; an output actually contains this information in the form of a script that requires a single ECDSA signature (see [[OP_CHECKSIG]]). The output script specifies what must be provided to unlock the funds later, and when the time comes in the future to spend the transaction in another input, that input must provide all of the thing(s) that satisfy the requirements defined by the original output script.<br />
<br />
=== Addresses ===<br />
<br />
A bitcoin address is in fact the hash of a ECDSA public key, computed this way:<br />
<br />
Version = 1 byte of 0 (zero); on the test network, this is 1 byte of 111<br />
Key hash = Version concatenated with RIPEMD-160(SHA-256(public key))<br />
Checksum = 1st 4 bytes of SHA-256(SHA-256(Key hash))<br />
Bitcoin Address = Base58Encode(Key hash concatenated with Checksum)<br />
<br />
The Base58 encoding used is home made, and has some differences. Especially, leading zeroes are kept as single zeroes when conversion happens.<br />
<br />
== Common structures ==<br />
<br />
Almost all integers are encoded in little endian. Only IP or port number are encoded big endian.<br />
<br />
=== Message structure ===<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown<br />
|-<br />
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| 4 || length || uint32_t || Length of payload in number of bytes<br />
|-<br />
| 4 || checksum || uint32_t || First 4 bytes of sha256(sha256(payload))<br />
|-<br />
| ? || payload || uchar[] || The actual data<br />
|}<br />
<br />
<br />
Known magic values:<br />
<br />
{|class="wikitable"<br />
! Network !! Magic value !! Sent over wire as<br />
|-<br />
| main || 0xD9B4BEF9 || F9 BE B4 D9<br />
|-<br />
| testnet || 0xDAB5BFFA || FA BF B5 DA<br />
|-<br />
| testnet3 || 0x0709110B || 0B 11 09 07<br />
|-<br />
| namecoin || 0xFEB4BEF9 || F9 BE B4 FE<br />
|}<br />
<br />
=== Variable length integer ===<br />
<br />
Integer can be encoded depending on the represented value to save space.<br />
Variable length integers always precede an array/vector of a type of data that may vary in length.<br />
Longer numbers are encoded in little endian.<br />
<br />
{|class="wikitable"<br />
! Value !! Storage length !! Format<br />
|-<br />
| < 0xFD || 1 || uint8_t<br />
|-<br />
| <= 0xFFFF || 3 || 0xFD followed by the length as uint16_t<br />
|-<br />
| <= 0xFFFF FFFF || 5 || 0xFE followed by the length as uint32_t<br />
|-<br />
| - || 9 || 0xFF followed by the length as uint64_t<br />
|}<br />
<br />
If you're reading the Satoshi client code (BitcoinQT) it refers to this encoding as a "CompactSize". Modern BitcoinQT also has the CVarInt class which implements an even more compact integer for the purpose of local storage (which is incompatible with "CompactSize" described here). CVarInt is not a part of the protocol.<br />
<br />
=== Variable length string ===<br />
<br />
Variable length string can be stored using a variable length integer followed by the string itself.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the string<br />
|-<br />
| ? || string || char[] || The string itself (can be empty)<br />
|}<br />
<br />
=== Network address ===<br />
<br />
When a network address is needed somewhere, this structure is used. Network addresses are not prefixed with a timestamp in the version message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || time || uint32 || the Time (version >= 31402). '''Not present in version message.'''<br />
|-<br />
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]<br />
|-<br />
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The original client only supported IPv4 and only read the last 4 bytes to get the IPv4 address. However, the IPv4 address is written into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]<br />
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).<br />
|-<br />
| 2 || port || uint16_t || port number, network byte order<br />
|}<br />
<br />
Hexdump example of Network address structure<br />
<br />
<pre><br />
0000 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0010 00 00 FF FF 0A 00 00 01 20 8D ........ .<br />
<br />
Network address:<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK: see services listed under version command)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv6: ::ffff:a00:1 or IPv4: 10.0.0.1<br />
20 8D - Port 8333<br />
</pre><br />
<br />
=== Inventory Vectors ===<br />
<br />
Inventory vectors are used for notifying other nodes about objects they have or data which is being requested.<br />
<br />
Inventory vectors consist of the following data format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || type || uint32_t || Identifies the object type linked to this inventory<br />
|-<br />
| 32 || hash || char[32] || Hash of the object<br />
|}<br />
<br />
<br />
The object type is currently defined as one of the following possibilities:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0 || ERROR || Any data of with this number may be ignored<br />
|-<br />
| 1 || MSG_TX || Hash is related to a transaction<br />
|-<br />
| 2 || MSG_BLOCK || Hash is related to a data block<br />
|-<br />
| 3 || MSG_FILTERED_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a merkleblock message rather than a block message; this only works if a bloom filter has been set.<br />
|-<br />
| 4 || MSG_CMPCT_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a cmpctblock message. See BIP 152 for more info.<br />
|}<br />
<br />
Other Data Type values are considered reserved for future implementations.<br />
<br />
=== Block Headers ===<br />
<br />
Block headers are sent in a headers packet in response to a getheaders message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Will overflow in 2106<ref>https://en.wikipedia.org/wiki/Unix_time#Notable_events_in_Unix_time</ref>)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 1 || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries, this value is always 0<br />
|}<br />
<br />
cf. [[Block hashing algorithm]]<br />
<br />
=== Differential encoding === <br />
Several uses of CompactSize below are "differentially encoded". For these, instead of using raw indexes, the number encoded is the difference between the current index and the previous index, minus one. For example, a first index of 0 implies a real index of 0, a second index of 0 thereafter refers to a real index of 1, etc.<br />
<br />
=== PrefilledTransaction ===<br />
<br />
A PrefilledTransaction structure is used in HeaderAndShortIDs to provide a list of a few transactions explicitly.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| index || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1, 3 bytes || Compact Size, differentially encoded since the last PrefilledTransaction in a list || The index into the block at which this transaction is<br />
|-<br />
| tx || Transaction || variable || As encoded in [[Protocol_documentation#tx|tx messages]] || The transaction which is in the block at index index.<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== HeaderAndShortIDs ===<br />
<br />
A HeaderAndShortIDs structure is used to relay a block header, the short transactions IDs used for matching already-available transactions, and a select few transactions which we expect a peer may be missing.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| header || Block header || 80 bytes || First 80 bytes of the block as defined by the encoding used by "block" messages || The header of the block being provided<br />
|-<br />
| nonce || uint64_t || 8 bytes || Little Endian || A nonce for use in short transaction ID calculations<br />
|-<br />
| shortids_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of short transaction IDs in shortids (ie block tx count - prefilledtxn_length)<br />
|-<br />
| shortids || List of 6-byte integers || 6*shortids_length bytes || Little Endian || The [[Protocol_documentation#Short_transaction_ID|short transaction IDs]] calculated from the transactions which were not provided explicitly in prefilledtxn<br />
|-<br />
| prefilledtxn_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of prefilled transactions in prefilledtxn (ie block tx count - shortids_length)<br />
|-<br />
| prefilledtxn || List of PrefilledTransactions || variable size*prefilledtxn_length || As defined by [[Protocol_documentation#PrefilledTransaction|PrefilledTransaction]] definition, above || Used to provide the coinbase transaction and a select few which we expect a peer may be missing<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== BlockTransactionsRequest ===<br />
<br />
A BlockTransactionsRequest structure is used to list transaction indexes in a block being requested.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| blockhash || Binary blob || 32 bytes || The output from a double-SHA256 of the block header, as used elsewhere || The blockhash of the block which the transactions being requested are in<br />
|-<br />
| indexes_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of transactions being requested<br />
|-<br />
| indexes || List of [[Protocol_documentation#Variable_length_integer|CompactSizes]] || 1 or 3 bytes*indexes_length || [[Protocol_documentation#Differential_encoding|Differentially encoded]] || The indexes of the transactions being requested in the block<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== BlockTransactions ===<br />
<br />
A BlockTransactions structure is used to provide some of the transactions in a block, as requested.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| blockhash || Binary blob || 32 bytes || The output from a double-SHA256 of the block header, as used elsewhere || The blockhash of the block which the transactions being provided are in<br />
|-<br />
| transactions_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of transactions provided<br />
|-<br />
| transactions || List of Transactions || variable || As encoded in [[Protocol_documentation#tx|tx messages]] || The transactions provided<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== Short transaction ID ===<br />
<br />
Short transaction IDs are used to represent a transaction without sending a full 256-bit hash. They are calculated by:<br />
<br />
# single-SHA256 hashing the block header with the nonce appended (in little-endian)<br />
# Running SipHash-2-4 with the input being the transaction ID and the keys (k0/k1) set to the first two little-endian 64-bit integers from the above hash, respectively.<br />
# Dropping the 2 most significant bytes from the SipHash output to make it 6 bytes.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
== Message types ==<br />
<br />
=== version ===<br />
<br />
When a node creates an outgoing connection, it will immediately [[Version Handshake|advertise]] its version. The remote node will respond with its version. No further communication is possible until both peers have exchanged their version.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Identifies protocol version being used by the node<br />
|-<br />
| 8 || services || uint64_t || bitfield of features to be enabled for this connection<br />
|-<br />
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds<br />
|-<br />
| 26 || addr_recv || [[#Network address|net_addr]] || The network address of the node receiving this message<br />
|-<br />
|colspan="4"| Fields below require version ≥ 106<br />
|-<br />
| 26 || addr_from || [[#Network address|net_addr]] || The network address of the node emitting this message<br />
|-<br />
| 8 || nonce || uint64_t || Node random nonce, randomly generated every time a version packet is sent. This nonce is used to detect connections to self.<br />
|-<br />
| ? || user_agent || [[#Variable length string|var_str]] || [https://github.com/bitcoin/bips/blob/master/bip-0014.mediawiki User Agent] (0x00 if string is 0 bytes long)<br />
|-<br />
| 4 || start_height || int32_t || The last block received by the emitting node<br />
|-<br />
|colspan="4"| Fields below require version ≥ 70001<br />
|-<br />
| 1 || relay || bool || Whether the remote peer should announce relayed transactions or not, see [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037]<br />
|}<br />
<br />
A "verack" packet shall be sent if the version packet was accepted.<br />
<br />
The following services are currently assigned:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 1 || NODE_NETWORK || This node can be asked for full blocks instead of just headers.<br />
|}<br />
<br />
Hexdump example of version message (OBSOLETE EXAMPLE: This example lacks a checksum and user-agent):<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....<br />
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........<br />
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............<br />
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................<br />
0040 20 8D 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,<br />
0060 3A B4 57 13 00 55 81 01 00 :.W..U...<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
55 00 00 00 - Payload is 85 bytes long<br />
- No checksum in version message until 20 February 2012. See https://bitcointalk.org/index.php?topic=55852.0<br />
Version message:<br />
9C 7C 00 00 - 31900 (version 0.3.19)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
E6 15 10 4D 00 00 00 00 - Mon Dec 20 21:50:14 EST 2010<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 20 8D - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D - Sender address info - see Network Address<br />
DD 9D 20 2C 3A B4 57 13 - Node random unique ID<br />
00 - "" sub-version string (string is 0 bytes long)<br />
55 81 01 00 - Last block sending node has is block #98645<br />
</pre><br />
<br />
And here's a modern (60002) protocol version client advertising itself to a local peer...<br />
<br />
Newer protocol includes the checksum now, this is from a mainline (satoshi) client during <br />
an outgoing connection to another local client, notice that it does not fill out the <br />
address information at all when the source or destination is "unroutable".<br />
<br />
<pre><br />
<br />
0000 f9 be b4 d9 76 65 72 73 69 6f 6e 00 00 00 00 00 ....version.....<br />
0010 64 00 00 00 35 8d 49 32 62 ea 00 00 01 00 00 00 d...5.I2b.......<br />
0020 00 00 00 00 11 b2 d0 50 00 00 00 00 01 00 00 00 .......P........<br />
0030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ff ff ................<br />
0040 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 00 00 00 00 ff ff 00 00 00 00 00 00 ................<br />
0060 3b 2e b3 5d 8c e6 17 65 0f 2f 53 61 74 6f 73 68 ;..]...e./Satosh<br />
0070 69 3a 30 2e 37 2e 32 2f c0 3e 03 00 i:0.7.2/.>..<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
64 00 00 00 - Payload is 100 bytes long<br />
3B 64 8D 5A - payload checksum<br />
<br />
Version message:<br />
62 EA 00 00 - 60002 (protocol version 60002)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
11 B2 D0 50 00 00 00 00 - Tue Dec 18 10:12:33 PST 2012<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Sender address info - see Network Address<br />
3B 2E B3 5D 8C E6 17 65 - Node ID<br />
0F 2F 53 61 74 6F 73 68 69 3A 30 2E 37 2E 32 2F - "/Satoshi:0.7.2/" sub-version string (string is 15 bytes long)<br />
C0 3E 03 00 - Last block sending node has is block #212672<br />
</pre><br />
<br />
=== verack ===<br />
<br />
The ''verack'' message is sent in reply to ''[[#version|version]]''. This message consists of only a [[#Message structure|message header]] with the command string "verack".<br />
<br />
Hexdump of the verack message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......<br />
0010 00 00 00 00 5D F6 E0 E2 ........<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 61 63 6B 00 00 00 00 00 00 - "verack" command<br />
00 00 00 00 - Payload is 0 bytes long<br />
5D F6 E0 E2 - Checksum<br />
</pre><br />
<br />
=== addr ===<br />
<br />
Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours<br />
<br />
Payload:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of address entries (max: 1000)<br />
|-<br />
| 30x? || addr_list || (uint32_t + [[#Network address|net_addr]])[] || Address of other nodes on the network. version < 209 will only read the first one. The uint32_t is a timestamp (see note below).<br />
|}<br />
<br />
'''Note''': Starting version 31402, addresses are prefixed with a timestamp. If no timestamp is present, the addresses should not be relayed to other peers, unless it is indeed confirmed they are up.<br />
<br />
Hexdump example of ''addr'' message:<br />
<pre><br />
0000 F9 BE B4 D9 61 64 64 72 00 00 00 00 00 00 00 00 ....addr........<br />
0010 1F 00 00 00 ED 52 39 9B 01 E2 15 10 4D 01 00 00 .....R9.....M...<br />
0020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF ................<br />
0030 FF 0A 00 00 01 20 8D ..... .<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
61 64 64 72 00 00 00 00 00 00 00 00 - "addr"<br />
1F 00 00 00 - payload is 31 bytes long<br />
ED 52 39 9B - checksum of payload<br />
<br />
Payload:<br />
01 - 1 address in this message<br />
<br />
Address:<br />
E2 15 10 4D - Mon Dec 20 21:50:10 EST 2010 (only when version is >= 31402)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK service - see version message)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv4: 10.0.0.1, IPv6: ::ffff:10.0.0.1 (IPv4-mapped IPv6 address)<br />
20 8D - port 8333<br />
</pre><br />
<br />
=== inv ===<br />
<br />
Allows a node to advertise its knowledge of one or more objects. It can be received unsolicited, or in reply to ''getblocks''.<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getdata ===<br />
<br />
getdata is used in response to inv, to retrieve the content of a specific object, and is usually sent after receiving an ''inv'' packet, after filtering known elements. It can be used to retrieve transactions, but only if they are in the memory pool or relay set - arbitrary access to transactions in the chain is not allowed to avoid having clients start to depend on nodes having full transaction indexes (which modern nodes do not).<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== notfound ===<br />
<br />
notfound is a response to a getdata, sent if any requested data items could not be relayed, for example, because the requested transaction was not in the memory pool or relay set.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getblocks ===<br />
<br />
Return an ''inv'' packet containing the list of blocks starting right after the last known hash in the block locator object, up to hash_stop or 500 blocks, whichever comes first. <br />
<br />
The locator hashes are processed by a node in the order as they appear in the message. If a block hash is found in the node's main chain, the list of its children is returned back via the ''inv'' message and the remaining locators are ignored, no matter if the requested limit was reached, or not.<br />
<br />
To receive the next blocks hashes, one needs to issue getblocks again with a new block locator object. Keep in mind that some clients may provide blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block; set to zero to get as many blocks as possible (500)<br />
|}<br />
<br />
To create the block locator hashes, keep pushing hashes until you go back to the genesis block. After pushing 10 hashes back, the step backwards doubles every loop:<br />
<br />
<pre><br />
// From libbitcoin which is under AGPL<br />
std::vector<size_t> block_locator_indexes(size_t top_height)<br />
{<br />
std::vector<size_t> indexes;<br />
<br />
// Modify the step in the iteration.<br />
int64_t step = 1;<br />
<br />
// Start at the top of the chain and work backwards.<br />
for (auto index = (int64_t)top_height; index > 0; index -= step)<br />
{<br />
// Push top 10 indexes first, then back off exponentially.<br />
if (indexes.size() >= 10)<br />
step *= 2;<br />
<br />
indexes.push_back((size_t)index);<br />
}<br />
<br />
// Push the genesis block index.<br />
indexes.push_back(0);<br />
return indexes;<br />
}<br />
</pre><br />
<br />
Note that it is allowed to send in fewer known hashes down to a minimum of just one hash. However, the purpose of the block locator object is to detect a wrong branch in the caller's main chain. If the peer detects that you are off the main chain, it will send in block hashes which are earlier than your last known block. So if you just send in your last known hash and it is off the main chain, the peer starts over at block #1.<br />
<br />
=== getheaders ===<br />
<br />
Return a ''headers'' packet containing the headers of blocks starting right after the last known hash in the block locator object, up to hash_stop or 2000 blocks, whichever comes first. To receive the next block headers, one needs to issue getheaders again with a new block locator object. The ''getheaders'' command is used by thin clients to quickly download the block chain where the contents of the transactions would be irrelevant (because they are not ours). Keep in mind that some clients may provide headers of blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block header; set to zero to get as many blocks as possible (2000)<br />
|}<br />
<br />
For the block locator object in this packet, the same rules apply as for the [[Protocol_documentation#getblocks|getblocks]] packet.<br />
<br />
=== tx ===<br />
<br />
''tx'' describes a bitcoin transaction, in reply to ''[[#getdata|getdata]]''<br />
<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Transaction data format version (note, this is signed)<br />
|-<br />
| 1+ || tx_in count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction inputs<br />
|-<br />
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins<br />
|-<br />
| 1+ || tx_out count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction outputs<br />
|-<br />
| 9+ || tx_out || tx_out[] || A list of 1 or more transaction outputs or destinations for coins<br />
|-<br />
| 4 || lock_time || uint32_t || The block number or timestamp at which this transaction is locked:<br />
{|class="wikitable"<br />
! Value !! Description<br />
|-<br />
| 0 || Not locked<br />
|-<br />
| < 500000000 || Block number at which this transaction is locked<br />
|-<br />
| >= 500000000 || UNIX timestamp at which this transaction is locked<br />
|}<br />
If all TxIn inputs have final (0xffffffff) sequence numbers then lock_time is irrelevant. Otherwise, the transaction may not be added to a block until after lock_time (see [[NLockTime]]).<br />
<br />
|}<br />
<br />
TxIn consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 36 || previous_output || outpoint || The previous output transaction reference, as an OutPoint structure<br />
|-<br />
| 1+ || script length || [[Protocol_documentation#Variable_length_integer|var_int]] || The length of the signature script<br />
|-<br />
| ? || signature script || uchar[] || Computational Script for confirming transaction authorization<br />
|-<br />
| 4 || [http://bitcoin.stackexchange.com/q/2025/323 sequence] || uint32_t || Transaction version as defined by the sender. Intended for "replacement" of transactions when information is updated before inclusion into a block.<br />
|}<br />
<br />
The OutPoint structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 32 || hash || char[32] || The hash of the referenced transaction.<br />
|-<br />
| 4 || index || uint32_t || The index of the specific output in the transaction. The first output is 0, etc.<br />
|}<br />
<br />
The Script structure consists of a series of pieces of information and operations related to the value of the transaction.<br />
<br />
(Structure to be expanded in the future… see script.h and script.cpp and [[Script]] for more information)<br />
<br />
The TxOut structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || value || int64_t || Transaction Value<br />
|-<br />
| 1+ || pk_script length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the pk_script<br />
|-<br />
| ? || pk_script || uchar[] || Usually contains the public key as a Bitcoin script setting up conditions to claim this output.<br />
|}<br />
<br />
Example ''tx'' message:<br />
<pre><br />
000000 F9 BE B4 D9 74 78 00 00 00 00 00 00 00 00 00 00 ....tx..........<br />
000010 02 01 00 00 E2 93 CD BE 01 00 00 00 01 6D BD DB .............m..<br />
000020 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D 12 66 E9 .[...Q........f.<br />
000030 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29 00 00 00 .;P......j.6)...<br />
000040 00 8B 48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 ..H0E.!..X..r...<br />
000050 C7 36 7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A .6zz%;..R#...h.:<br />
000060 59 23 3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 Y#?E.W... Y.....<br />
000070 0E 41 83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D .A.z.X.z...XN...<br />
000080 35 BD 96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF 5...6..;...A....<br />
000090 C9 7E F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 .~.6.m...@..!...<br />
0000A0 2A CD 2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC *.+..].}Y... ...<br />
0000B0 4E 02 53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F N.S..=7.o...Q...<br />
0000C0 14 04 2F 46 61 4A 4C 70 C0 F1 4B EF F5 FF FF FF ../FaJLp..K.....<br />
0000D0 FF 02 40 4B 4C 00 00 00 00 00 19 76 A9 14 1A A0 ..@KL......v....<br />
0000E0 CD 1C BE A6 E7 45 8A 7A BA D5 12 A9 D9 EA 1A FB .....E.z........<br />
0000F0 22 5E 88 AC 80 FA E9 C7 00 00 00 00 19 76 A9 14 "^...........v..<br />
000100 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E FD A0 B7 ..[.Cj.....H^...<br />
000110 8B 4E CC 52 88 AC 00 00 00 00 .N.R......<br />
<br />
<br />
Message header:<br />
F9 BE B4 D9 - main network magic bytes<br />
74 78 00 00 00 00 00 00 00 00 00 00 - "tx" command<br />
02 01 00 00 - payload is 258 bytes long<br />
E2 93 CD BE - checksum of payload<br />
<br />
Transaction:<br />
01 00 00 00 - version<br />
<br />
Inputs:<br />
01 - number of transaction inputs<br />
<br />
Input 1:<br />
6D BD DB 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D - previous output (outpoint)<br />
12 66 E9 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29<br />
00 00 00 00<br />
<br />
8B - script is 139 bytes long<br />
<br />
48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 C7 36 - signature script (scriptSig)<br />
7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A 59 23<br />
3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 0E 41<br />
83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D 35 BD<br />
96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF C9 7E<br />
F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 2A CD<br />
2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC 4E 02<br />
53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F 14 04<br />
2F 46 61 4A 4C 70 C0 F1 4B EF F5<br />
<br />
FF FF FF FF - sequence<br />
<br />
Outputs:<br />
02 - 2 Output Transactions<br />
<br />
Output 1:<br />
40 4B 4C 00 00 00 00 00 - 0.05 BTC (5000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 1A A0 CD 1C BE A6 E7 45 8A 7A BA D5 12 - pk_script<br />
A9 D9 EA 1A FB 22 5E 88 AC<br />
<br />
Output 2:<br />
80 FA E9 C7 00 00 00 00 - 33.54 BTC (3354000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E - pk_script<br />
FD A0 B7 8B 4E CC 52 88 AC<br />
<br />
Locktime:<br />
00 00 00 00 - lock time<br />
</pre><br />
<br />
=== block ===<br />
<br />
The '''block''' message is sent in response to a getdata message which requests transaction information from a block hash.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A Unix timestamp recording when this block was created (Currently limited to dates before the year 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated [[Difficulty|difficulty target]] being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| ? || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries<br />
|-<br />
| ? || txns || tx[] || Block transactions, in format of "tx" command<br />
|}<br />
<br />
The SHA256 hash that identifies each block (and which must have a run of 0 bits) is calculated from the first 6 fields of this structure (version, prev_block, merkle_root, timestamp, bits, nonce, and standard SHA256 padding, making two 64-byte chunks in all) and ''not'' from the complete block. To calculate the hash, only two chunks need to be processed by the SHA256 algorithm. Since the ''nonce'' field is in the second chunk, the first chunk stays constant during mining and therefore only the second chunk needs to be processed. However, a Bitcoin hash is the hash of the hash, so two SHA256 rounds are needed for each mining iteration.<br />
See [[Block hashing algorithm]] for details and an example.<br />
<br />
=== headers ===<br />
<br />
The ''headers'' packet returns block headers in response to a ''getheaders'' packet. <br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of block headers<br />
|-<br />
| 81x? || headers || [[Protocol_documentation#Block_Headers|block_header]][] || [[Protocol_documentation#Block_Headers|Block headers]]<br />
|}<br />
<br />
Note that the block headers in this packet include a transaction count (a var_int, so there can be more than 81 bytes per header) as opposed to the block headers that are hashed by miners.<br />
<br />
=== getaddr ===<br />
<br />
The getaddr message sends a request to a node asking for information about known active peers to help with finding potential nodes in the network. The response to receiving this message is to transmit one or more addr messages with one or more peers from a database of known active peers. The typical presumption is that a node is likely to be active if it has been sending a message within the last three hours.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
=== mempool ===<br />
<br />
The mempool message sends a request to a node asking for information about transactions it has verified but which have not yet confirmed. The response to receiving this message is an inv message containing the transaction hashes for all the transactions in the node's mempool.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
It is specified in [https://github.com/bitcoin/bips/blob/master/bip-0035.mediawiki BIP 35]. Since [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 37], if a [[Protocol_documentation#filterload.2C_filteradd.2C_filterclear.2C_merkleblock|bloom filter]] is loaded, only transactions matching the filter are replied.<br />
<br />
=== checkorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== submitorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== reply ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== ping ===<br />
<br />
The ''ping'' message is sent primarily to confirm that the TCP/IP connection is still valid. An error in transmission is presumed to be a closed connection and the address is removed as a current peer.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || random nonce<br />
|}<br />
<br />
=== pong ===<br />
<br />
The ''pong'' message is sent in response to a ''ping'' message. In modern protocol versions, a ''pong'' response is generated using a nonce included in the ping.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || nonce from ping<br />
|}<br />
<br />
<br />
=== reject===<br />
<br />
The ''reject'' message is sent when messages are rejected.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || message || var_str || type of message rejected<br />
|-<br />
| 1 || ccode || char || code relating to rejected message<br />
|-<br />
| 1+ || reason || var_str || text version of reason for rejection<br />
|-<br />
| 0+ || data || char || Optional extra data provided by some errors. Currently, all errors which provide this field fill it with the TXID or block header hash of the object being rejected, so the field is 32 bytes.<br />
|}<br />
<br />
CCodes<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0x01 || REJECT_MALFORMED|| <br />
|-<br />
| 0x10 || REJECT_INVALID ||<br />
|-<br />
| 0x11 || REJECT_OBSOLETE ||<br />
|-<br />
| 0x12 || REJECT_DUPLICATE ||<br />
|-<br />
| 0x40 || REJECT_NONSTANDARD ||<br />
|-<br />
| 0x41 || REJECT_DUST ||<br />
|-<br />
| 0x42 || REJECT_INSUFFICIENTFEE ||<br />
|-<br />
| 0x43 || REJECT_CHECKPOINT ||<br />
|}<br />
<br />
=== filterload, filteradd, filterclear, merkleblock ===<br />
<br />
These messages are related to Bloom filtering of connections and are defined in [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037].<br />
<br />
<br />
The <code>filterload</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || filter || uint8_t[] || The filter itself is simply a bit field of arbitrary byte-aligned size. The maximum size is 36,000 bytes.<br />
|-<br />
| 4 || nHashFuncs || uint32_t || The number of hash functions to use in this filter. The maximum value allowed in this field is 50.<br />
|-<br />
| 4 || nTweak || uint32_t || A random value to add to the seed value in the hash function used by the bloom filter.<br />
|-<br />
| 1 || nFlags || uint8_t || A set of flags that control how matched items are added to the filter.<br />
|}<br />
<br />
See below for a description of the Bloom filter algorithm and how to select nHashFuncs and filter size for a desired false positive rate.<br />
<br />
Upon receiving a <code>filterload</code> command, the remote peer will immediately restrict the broadcast transactions it announces (in inv packets) to transactions matching the filter, where the matching algorithm is specified below. The flags control the update behaviour of the matching algorithm.<br />
<br />
The <code>filteradd</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || data || uint8_t[] || The data element to add to the current filter.<br />
|}<br />
<br />
The data field must be smaller than or equal to 520 bytes in size (the maximum size of any potentially matched object).<br />
<br />
The given data element will be added to the Bloom filter. A filter must have been previously provided using <code>filterload</code>. This command is useful if a new key or script is added to a clients wallet whilst it has connections to the network open, it avoids the need to re-calculate and send an entirely new filter to every peer (though doing so is usually advisable to maintain anonymity).<br />
<br />
The <code>filterclear</code> command has no arguments at all.<br />
<br />
After a filter has been set, nodes don't merely stop announcing non-matching transactions, they can also serve filtered blocks. A filtered block is defined by the <code>merkleblock</code> message and is defined like this:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information, based upon the software version creating this block (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Limited to 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 4 || total_transactions || uint32_t || Number of transactions in the block (including unmatched ones)<br />
|-<br />
| ? || hashes || uint256[] || hashes in depth-first order (including standard varint size prefix)<br />
|-<br />
| ? || flags || byte[] || flag bits, packed per 8 in a byte, least significant bit first (including standard varint size prefix)<br />
|}<br />
<br />
=== alert ===<br />
<br />
An '''alert''' is sent between nodes to send a general notification message throughout the network. If the alert can be confirmed with the signature as having come from the core development group of the Bitcoin software, the message is suggested to be displayed for end-users. Attempts to perform transactions, particularly automated transactions through the client, are suggested to be halted. The text in the Message string should be relayed to log files and any user interfaces.<br />
<br />
Alert format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || payload || uchar[] || Serialized alert payload<br />
|-<br />
| ? || signature || uchar[] || An ECDSA signature of the message<br />
|}<br />
<br />
The developers of Satoshi's client use this public key for signing alerts:<br />
04fc9702847840aaf195de8442ebecedf5b095cdbb9bc716bda9110971b28a49e0ead8564ff0db22209e0374782c093bb899692d524e9d6a6956e7c5ecbcd68284<br />
(hash) 1AGRxqDa5WjUKBwHB9XYEjmkv1ucoUUy1s<br />
<br />
The payload is serialized into a uchar[] to ensure that versions using incompatible alert formats can still relay alerts among one another. The current alert payload format is:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || Version || int32_t || Alert format version<br />
|-<br />
| 8 || RelayUntil || int64_t || The timestamp beyond which nodes should stop relaying this alert<br />
|-<br />
| 8 || Expiration || int64_t || The timestamp beyond which this alert is no longer in effect and should be ignored<br />
|-<br />
| 4 || ID || int32_t || A unique ID number for this alert<br />
|-<br />
| 4 || Cancel || int32_t || All alerts with an ID number less than or equal to this number should be cancelled: deleted and not accepted in the future<br />
|-<br />
| ? || setCancel || set<int32_t> || All alert IDs contained in this set should be cancelled as above<br />
|-<br />
| 4 || MinVer || int32_t || This alert only applies to versions greater than or equal to this version. Other versions should still relay it.<br />
|-<br />
| 4 || MaxVer || int32_t || This alert only applies to versions less than or equal to this version. Other versions should still relay it.<br />
|-<br />
| ? || setSubVer || set<string> || If this set contains any elements, then only nodes that have their subVer contained in this set are affected by the alert. Other versions should still relay it.<br />
|-<br />
| 4 || Priority || int32_t || Relative priority compared to other alerts<br />
|-<br />
| ? || Comment || string || A comment on the alert that is not displayed<br />
|-<br />
| ? || StatusBar || string || The alert message that is displayed to the user<br />
|-<br />
| ? || Reserved || string || Reserved<br />
|}<br />
<br />
Note: '''set<''type''>''' in the table above is a [[#Variable length integer | variable length integer]] followed by the number of fields of the given ''type'' (either int32_t or [[#Variable length string | variable length string]])<br />
<br />
Sample alert (no message header):<br />
73010000003766404f00000000b305434f00000000f2030000f1030000001027000048ee0000<br />
0064000000004653656520626974636f696e2e6f72672f666562323020696620796f75206861<br />
76652074726f75626c6520636f6e6e656374696e672061667465722032302046656272756172<br />
79004730450221008389df45f0703f39ec8c1cc42c13810ffcae14995bb648340219e353b63b<br />
53eb022009ec65e1c1aaeec1fd334c6b684bde2b3f573060d5b70c3a46723326e4e8a4f1<br />
<br />
Version: 1<br />
RelayUntil: 1329620535<br />
Expiration: 1329792435<br />
ID: 1010<br />
Cancel: 1009<br />
setCancel: <empty><br />
MinVer: 10000<br />
MaxVer: 61000<br />
setSubVer: <empty><br />
Priority: 100<br />
Comment: <empty><br />
StatusBar: "See bitcoin.org/feb20 if you have trouble connecting after 20 February"<br />
Reserved: <empty><br />
<br />
=== sendheaders ===<br />
<br />
Request for Direct headers announcement. <br />
<br />
Upon receipt of this message, the node is be permitted, but not required, to announce new blocks by '''headers''' command (instead of '''inv''' command).<br />
<br />
This message is supported by the protocol version >= 70012 or Bitcoin Core version >= 0.12.0.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0130.mediawiki BIP 130] for more information.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
<br />
=== feefilter ===<br />
<br />
The payload is always 8 bytes long and it encodes 64 bit integer value (LSB / little endian) of '''feerate'''.<br />
The value represents a minimal fee and is expressed in satoshis per 1000 bytes.<br />
<br />
Upon receipt of a "feefilter" message, the node will be permitted, but not required, to filter transaction invs for transactions that fall below the feerate provided in the feefilter message interpreted as satoshis per kilobyte.<br />
<br />
The fee filter is additive with a bloom filter for transactions so if an SPV client were to load a bloom filter and send a feefilter message, transactions would only be relayed if they passed both filters.<br />
<br />
Inv's generated from a mempool message are also subject to a fee filter if it exists.<br />
<br />
Feature discovery is enabled by checking protocol version >= 70013<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0133.mediawiki BIP 133] for more information.<br />
<br />
=== sendcmpct ===<br />
<br />
# The sendcmpct message is defined as a message containing a 1-byte integer followed by a 8-byte integer where pchCommand == "sendcmpct".<br />
# The first integer SHALL be interpreted as a boolean (and MUST have a value of either 1 or 0)<br />
# The second integer SHALL be interpreted as a little-endian version number. Nodes sending a sendcmpct message MUST currently set this value to 1.<br />
# Upon receipt of a "sendcmpct" message with the first and second integers set to 1, the node SHOULD announce new blocks by sending a cmpctblock message.<br />
# Upon receipt of a "sendcmpct" message with the first integer set to 0, the node SHOULD NOT announce new blocks by sending a cmpctblock message, but SHOULD announce new blocks by sending invs or headers, as defined by BIP130.<br />
# Upon receipt of a "sendcmpct" message with the second integer set to something other than 1, nodes MUST treat the peer as if they had not received the message (as it indicates the peer will provide an unexpected encoding in <br />
# cmpctblock, and/or other, messages). This allows future versions to send duplicate sendcmpct messages with different versions as a part of a version handshake for future versions.<br />
# Nodes SHOULD check for a protocol version of >= 70014 before sending sendcmpct messages.<br />
# Nodes MUST NOT send a request for a MSG_CMPCT_BLOCK object to a peer before having received a sendcmpct message from that peer.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== cmpctblock ===<br />
<br />
# The cmpctblock message is defined as as a message containing a serialized HeaderAndShortIDs message and pchCommand == "cmpctblock".<br />
# Upon receipt of a cmpctblock message after sending a sendcmpct message, nodes SHOULD calculate the short transaction ID for each unconfirmed transaction they have available (ie in their mempool) and compare each to each short transaction ID in the cmpctblock message.<br />
# After finding already-available transactions, nodes which do not have all transactions available to reconstruct the full block SHOULD request the missing transactions using a getblocktxn message.<br />
# A node MUST NOT send a cmpctblock message unless they are able to respond to a getblocktxn message which requests every transaction in the block.<br />
# A node MUST NOT send a cmpctblock message without having validated that the header properly commits to each transaction in the block, and properly builds on top of the existing chain with a valid proof-of-work. A node MAY send a cmpctblock before validating that each transaction in the block validly spends existing UTXO set entries.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== getblocktxn ===<br />
<br />
# The getblocktxn message is defined as as a message containing a serialized BlockTransactionsRequest message and pchCommand == "getblocktxn".<br />
# Upon receipt of a properly-formatted getblocktxnmessage, nodes which recently provided the sender of such a message a cmpctblock for the block hash identified in this message MUST respond with an appropriate blocktxn message. Such a blocktxn message MUST contain exactly and only each transaction which is present in the appropriate block at the index specified in the getblocktxn indexes list, in the order requested.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== blocktxn ===<br />
<br />
# The blocktxn message is defined as as a message containing a serialized BlockTransactions message and pchCommand == "blocktxn".<br />
# Upon receipt of a properly-formatted requested blocktxn message, nodes SHOULD attempt to reconstruct the full block by:<br />
# Taking the prefilledtxn transactions from the original cmpctblock and placing them in the marked positions.<br />
# For each short transaction ID from the original cmpctblock, in order, find the corresponding transaction either from the blocktxn message or from other sources and place it in the first available position in the block.<br />
# Once the block has been reconstructed, it shall be processed as normal, keeping in mind that short transaction IDs are expected to occasionally collide, and that nodes MUST NOT be penalized for such collisions, wherever they # appear.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
== Scripting ==<br />
<br />
See [[script]].<br />
<br />
==See Also==<br />
<br />
* [[Network]]<br />
* [[Protocol rules]]<br />
* [[Hardfork Wishlist]]<br />
* [https://bitcoin.org/en/developer-documentation Developer Documentation on bitcoin.org]<br />
* Bitcoin dissectors for Wireshark: https://github.com/lbotsch/wireshark-bitcoin https://github.com/op-sig/bitcoin-wireshark-dissector<br />
<br />
==References==<br />
<references /><br />
<br />
[[zh-cn:协议说明]]<br />
[[Category:Technical]]<br />
[[Category:Developer]]<br />
<br />
{{Bitcoin Core documentation}}</div>Tonikthttps://en.bitcoin.it/w/index.php?title=Protocol_documentation&diff=61498Protocol documentation2016-08-25T12:51:19Z<p>Tonikt: /* BlockTransactionsRequest */</p>
<hr />
<div>This page ''describes'' the behavior of the [[Original Bitcoin client|reference client]]. The Bitcoin protocol is specified by the behavior of the reference client, not by this page. In particular, while this page is quite complete in describing the network protocol, it does not attempt to list all of the rules for block or transaction validity.<br />
<br />
Type names used in this documentation are from the C99 standard.<br />
<br />
For protocol used in mining, see [[getblocktemplate]].<br />
<br />
==Common standards==<br />
<br />
=== Hashes ===<br />
<br />
Usually, when a hash is computed within bitcoin, it is computed twice. Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-256] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when a shorter hash is desirable (for example when creating a bitcoin address).<br />
<br />
Example of double-SHA-256 encoding of string "hello":<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round of sha-256)<br />
9595c9df90075148eb06860365df33584b75bff782a510c6cd4883a419833d50 (second round of sha-256)<br />
<br />
For bitcoin addresses (RIPEMD-160) this would give:<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round is sha-256)<br />
b6a9c8c230722b7c748331a8b450f05566dc7d0f (with ripemd-160)<br />
<br />
=== Merkle Trees ===<br />
<br />
Merkle trees are binary trees of hashes. Merkle trees in bitcoin use a '''double''' SHA-256, the SHA-256 hash of the SHA-256 hash of something.<br />
<br />
If, when forming a row in the tree (other than the root of the tree), it would have an odd number of elements, the final double-hash is duplicated to ensure that the row has an even number of hashes.<br />
<br />
First form the bottom row of the tree with the ordered double-SHA-256 hashes of the byte streams of the transactions in the block.<br />
<br />
Then the row above it consists of half that number of hashes. Each entry is the double-SHA-256 of the 64-byte concatenation of the corresponding two hashes below it in the tree.<br />
<br />
This procedure repeats recursively until we reach a row consisting of just a single double-hash. This is the '''Merkle root''' of the tree.<br />
<br />
For example, imagine a block with three transactions ''a'', ''b'' and ''c''. The Merkle tree is: <br />
<br />
d1 = dhash(a)<br />
d2 = dhash(b)<br />
d3 = dhash(c)<br />
d4 = dhash(c) # a, b, c are 3. that's an odd number, so we take the c twice<br />
<br />
d5 = dhash(d1 concat d2)<br />
d6 = dhash(d3 concat d4)<br />
<br />
d7 = dhash(d5 concat d6)<br />
<br />
where<br />
<br />
dhash(a) = sha256(sha256(a))<br />
<br />
''d7'' is the Merkle root of the 3 transactions in this block.<br />
<br />
Note: Hashes in Merkle Tree displayed in the [[Block Explorer]] are of little-endian notation. For some implementations and [http://www.fileformat.info/tool/hash.htm calculations], the bits need to be reversed before they are hashed, and again after the hashing operation.<br />
<br />
=== Signatures ===<br />
<br />
Bitcoin uses [http://en.wikipedia.org/wiki/Elliptic_curve_cryptography Elliptic Curve] [http://en.wikipedia.org/wiki/Digital_Signature_Algorithm Digital Signature Algorithm] ([http://en.wikipedia.org/wiki/Elliptic_Curve_DSA ECDSA]) to sign transactions. <br />
<br />
For [[ECDSA]] the secp256k1 curve from http://www.secg.org/collateral/sec2_final.pdf is used.<br />
<br />
Public keys (in scripts) are given as 04 <x> <y> where ''x'' and ''y'' are 32 byte big-endian integers representing the coordinates of a point on the curve or in compressed form given as <sign> <x> where <sign> is 0x02 if ''y'' is even and 0x03 if ''y'' is odd.<br />
<br />
Signatures use [http://en.wikipedia.org/wiki/Distinguished_Encoding_Rules DER encoding] to pack the ''r'' and ''s'' components into a single byte stream (this is also what OpenSSL produces by default).<br />
<br />
=== Transaction Verification ===<br />
Transactions are cryptographically signed records that reassign ownership of Bitcoins to new addresses. Transactions have ''inputs'' - records which reference the funds from other previous transactions - and ''outputs'' - records which determine the new owner of the transferred Bitcoins, and which will be referenced as inputs in future transactions as those funds are respent.<br />
<br />
Each ''input'' must have a cryptographic digital signature that unlocks the funds from the prior transaction. Only the person possessing the appropriate [[private key]] is able to create a satisfactory signature; this in effect ensures that funds can only be spent by their owners.<br />
<br />
Each ''output'' determines which Bitcoin address (or other criteria, see [[Script]]) is the recipient of the funds.<br />
<br />
In a transaction, the sum of all inputs must be equal to or greater than the sum of all outputs. If the inputs exceed the outputs, the difference is considered a [[transaction fee]], and is redeemable by whoever first includes the transaction into the block chain.<br />
<br />
A special kind of transaction, called a [[coinbase transaction]], has no inputs. It is created by [[miners]], and there is one coinbase transaction per block. Because each block comes with a reward of newly created Bitcoins (e.g. 50 BTC for the first 210,000 blocks), the first transaction of a block is, with few exceptions, the transaction that grants those coins to their recipient (the miner). In addition to the newly created Bitcoins, the coinbase transaction is also used for assigning the recipient of any transaction fees that were paid within the other transactions being included in the same block. The coinbase transaction can assign the entire reward to a single Bitcoin address, or split it in portions among multiple addresses, just like any other transaction. Coinbase transactions always contain outputs totalling the sum of the block reward plus all transaction fees collected from the other transactions in the same block.<br />
<br />
The [[coinbase transaction]] in block zero cannot be spent. This is due to a quirk of the reference client implementation that would open the potential for a block chain fork if some nodes accepted the spend and others did not<ref>[http://bitcointalk.org/index.php?topic=119645.msg1288552#msg1288552 Block 0 Network Fork]</ref>.<br />
<br />
Most Bitcoin outputs encumber the newly transferred coins with a single ECDSA private key. The actual record saved with inputs and outputs isn't necessarily a key, but a ''script''. Bitcoin uses an interpreted scripting system to determine whether an output's criteria have been satisfied, with which more complex operations are possible, such as outputs that require two ECDSA signatures, or two-of-three-signature schemes. An output that references a single Bitcoin address is a ''typical'' output; an output actually contains this information in the form of a script that requires a single ECDSA signature (see [[OP_CHECKSIG]]). The output script specifies what must be provided to unlock the funds later, and when the time comes in the future to spend the transaction in another input, that input must provide all of the thing(s) that satisfy the requirements defined by the original output script.<br />
<br />
=== Addresses ===<br />
<br />
A bitcoin address is in fact the hash of a ECDSA public key, computed this way:<br />
<br />
Version = 1 byte of 0 (zero); on the test network, this is 1 byte of 111<br />
Key hash = Version concatenated with RIPEMD-160(SHA-256(public key))<br />
Checksum = 1st 4 bytes of SHA-256(SHA-256(Key hash))<br />
Bitcoin Address = Base58Encode(Key hash concatenated with Checksum)<br />
<br />
The Base58 encoding used is home made, and has some differences. Especially, leading zeroes are kept as single zeroes when conversion happens.<br />
<br />
== Common structures ==<br />
<br />
Almost all integers are encoded in little endian. Only IP or port number are encoded big endian.<br />
<br />
=== Message structure ===<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown<br />
|-<br />
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| 4 || length || uint32_t || Length of payload in number of bytes<br />
|-<br />
| 4 || checksum || uint32_t || First 4 bytes of sha256(sha256(payload))<br />
|-<br />
| ? || payload || uchar[] || The actual data<br />
|}<br />
<br />
<br />
Known magic values:<br />
<br />
{|class="wikitable"<br />
! Network !! Magic value !! Sent over wire as<br />
|-<br />
| main || 0xD9B4BEF9 || F9 BE B4 D9<br />
|-<br />
| testnet || 0xDAB5BFFA || FA BF B5 DA<br />
|-<br />
| testnet3 || 0x0709110B || 0B 11 09 07<br />
|-<br />
| namecoin || 0xFEB4BEF9 || F9 BE B4 FE<br />
|}<br />
<br />
=== Variable length integer ===<br />
<br />
Integer can be encoded depending on the represented value to save space.<br />
Variable length integers always precede an array/vector of a type of data that may vary in length.<br />
Longer numbers are encoded in little endian.<br />
<br />
{|class="wikitable"<br />
! Value !! Storage length !! Format<br />
|-<br />
| < 0xFD || 1 || uint8_t<br />
|-<br />
| <= 0xFFFF || 3 || 0xFD followed by the length as uint16_t<br />
|-<br />
| <= 0xFFFF FFFF || 5 || 0xFE followed by the length as uint32_t<br />
|-<br />
| - || 9 || 0xFF followed by the length as uint64_t<br />
|}<br />
<br />
If you're reading the Satoshi client code (BitcoinQT) it refers to this encoding as a "CompactSize". Modern BitcoinQT also has the CVarInt class which implements an even more compact integer for the purpose of local storage (which is incompatible with "CompactSize" described here). CVarInt is not a part of the protocol.<br />
<br />
=== Variable length string ===<br />
<br />
Variable length string can be stored using a variable length integer followed by the string itself.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the string<br />
|-<br />
| ? || string || char[] || The string itself (can be empty)<br />
|}<br />
<br />
=== Network address ===<br />
<br />
When a network address is needed somewhere, this structure is used. Network addresses are not prefixed with a timestamp in the version message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || time || uint32 || the Time (version >= 31402). '''Not present in version message.'''<br />
|-<br />
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]<br />
|-<br />
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The original client only supported IPv4 and only read the last 4 bytes to get the IPv4 address. However, the IPv4 address is written into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]<br />
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).<br />
|-<br />
| 2 || port || uint16_t || port number, network byte order<br />
|}<br />
<br />
Hexdump example of Network address structure<br />
<br />
<pre><br />
0000 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0010 00 00 FF FF 0A 00 00 01 20 8D ........ .<br />
<br />
Network address:<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK: see services listed under version command)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv6: ::ffff:a00:1 or IPv4: 10.0.0.1<br />
20 8D - Port 8333<br />
</pre><br />
<br />
=== Inventory Vectors ===<br />
<br />
Inventory vectors are used for notifying other nodes about objects they have or data which is being requested.<br />
<br />
Inventory vectors consist of the following data format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || type || uint32_t || Identifies the object type linked to this inventory<br />
|-<br />
| 32 || hash || char[32] || Hash of the object<br />
|}<br />
<br />
<br />
The object type is currently defined as one of the following possibilities:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0 || ERROR || Any data of with this number may be ignored<br />
|-<br />
| 1 || MSG_TX || Hash is related to a transaction<br />
|-<br />
| 2 || MSG_BLOCK || Hash is related to a data block<br />
|-<br />
| 3 || MSG_FILTERED_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a merkleblock message rather than a block message; this only works if a bloom filter has been set.<br />
|-<br />
| 4 || MSG_CMPCT_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a cmpctblock message. See BIP 152 for more info.<br />
|}<br />
<br />
Other Data Type values are considered reserved for future implementations.<br />
<br />
=== Block Headers ===<br />
<br />
Block headers are sent in a headers packet in response to a getheaders message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Will overflow in 2106<ref>https://en.wikipedia.org/wiki/Unix_time#Notable_events_in_Unix_time</ref>)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 1 || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries, this value is always 0<br />
|}<br />
<br />
cf. [[Block hashing algorithm]]<br />
<br />
=== Differential encoding === <br />
Several uses of CompactSize below are "differentially encoded". For these, instead of using raw indexes, the number encoded is the difference between the current index and the previous index, minus one. For example, a first index of 0 implies a real index of 0, a second index of 0 thereafter refers to a real index of 1, etc.<br />
<br />
=== PrefilledTransaction ===<br />
<br />
A PrefilledTransaction structure is used in HeaderAndShortIDs to provide a list of a few transactions explicitly.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| index || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1, 3 bytes || Compact Size, differentially encoded since the last PrefilledTransaction in a list || The index into the block at which this transaction is<br />
|-<br />
| tx || Transaction || variable || As encoded in [[Protocol_documentation#tx|tx messages]] || The transaction which is in the block at index index.<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== HeaderAndShortIDs ===<br />
<br />
A HeaderAndShortIDs structure is used to relay a block header, the short transactions IDs used for matching already-available transactions, and a select few transactions which we expect a peer may be missing.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| header || Block header || 80 bytes || First 80 bytes of the block as defined by the encoding used by "block" messages || The header of the block being provided<br />
|-<br />
| nonce || uint64_t || 8 bytes || Little Endian || A nonce for use in short transaction ID calculations<br />
|-<br />
| shortids_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of short transaction IDs in shortids (ie block tx count - prefilledtxn_length)<br />
|-<br />
| shortids || List of 6-byte integers || 6*shortids_length bytes || Little Endian || The [[Protocol_documentation#Short_transaction_ID|short transaction IDs]] calculated from the transactions which were not provided explicitly in prefilledtxn<br />
|-<br />
| prefilledtxn_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of prefilled transactions in prefilledtxn (ie block tx count - shortids_length)<br />
|-<br />
| prefilledtxn || List of PrefilledTransactions || variable size*prefilledtxn_length || As defined by [[Protocol_documentation#PrefilledTransaction|PrefilledTransaction]] definition, above || Used to provide the coinbase transaction and a select few which we expect a peer may be missing<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== BlockTransactionsRequest ===<br />
<br />
A BlockTransactionsRequest structure is used to list transaction indexes in a block being requested.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| blockhash || Binary blob || 32 bytes || The output from a double-SHA256 of the block header, as used elsewhere || The blockhash of the block which the transactions being requested are in<br />
|-<br />
| indexes_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of transactions being requested<br />
|-<br />
| indexes || List of [[Protocol_documentation#Variable_length_integer|CompactSizes]] || 1 or 3 bytes*indexes_length || [[Protocol_documentation#Differential_encoding|Differentially encoded]] || The indexes of the transactions being requested in the block<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== BlockTransactions ===<br />
<br />
A BlockTransactions structure is used to provide some of the transactions in a block, as requested.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| blockhash || Binary blob || 32 bytes || The output from a double-SHA256 of the block header, as used elsewhere || The blockhash of the block which the transactions being provided are in<br />
|-<br />
| transactions_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of transactions provided<br />
|-<br />
| transactions || List of Transactions || variable || As encoded in "tx" messages || The transactions provided<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== Short transaction ID ===<br />
<br />
Short transaction IDs are used to represent a transaction without sending a full 256-bit hash. They are calculated by:<br />
<br />
# single-SHA256 hashing the block header with the nonce appended (in little-endian)<br />
# Running SipHash-2-4 with the input being the transaction ID and the keys (k0/k1) set to the first two little-endian 64-bit integers from the above hash, respectively.<br />
# Dropping the 2 most significant bytes from the SipHash output to make it 6 bytes.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
== Message types ==<br />
<br />
=== version ===<br />
<br />
When a node creates an outgoing connection, it will immediately [[Version Handshake|advertise]] its version. The remote node will respond with its version. No further communication is possible until both peers have exchanged their version.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Identifies protocol version being used by the node<br />
|-<br />
| 8 || services || uint64_t || bitfield of features to be enabled for this connection<br />
|-<br />
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds<br />
|-<br />
| 26 || addr_recv || [[#Network address|net_addr]] || The network address of the node receiving this message<br />
|-<br />
|colspan="4"| Fields below require version ≥ 106<br />
|-<br />
| 26 || addr_from || [[#Network address|net_addr]] || The network address of the node emitting this message<br />
|-<br />
| 8 || nonce || uint64_t || Node random nonce, randomly generated every time a version packet is sent. This nonce is used to detect connections to self.<br />
|-<br />
| ? || user_agent || [[#Variable length string|var_str]] || [https://github.com/bitcoin/bips/blob/master/bip-0014.mediawiki User Agent] (0x00 if string is 0 bytes long)<br />
|-<br />
| 4 || start_height || int32_t || The last block received by the emitting node<br />
|-<br />
|colspan="4"| Fields below require version ≥ 70001<br />
|-<br />
| 1 || relay || bool || Whether the remote peer should announce relayed transactions or not, see [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037]<br />
|}<br />
<br />
A "verack" packet shall be sent if the version packet was accepted.<br />
<br />
The following services are currently assigned:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 1 || NODE_NETWORK || This node can be asked for full blocks instead of just headers.<br />
|}<br />
<br />
Hexdump example of version message (OBSOLETE EXAMPLE: This example lacks a checksum and user-agent):<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....<br />
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........<br />
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............<br />
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................<br />
0040 20 8D 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,<br />
0060 3A B4 57 13 00 55 81 01 00 :.W..U...<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
55 00 00 00 - Payload is 85 bytes long<br />
- No checksum in version message until 20 February 2012. See https://bitcointalk.org/index.php?topic=55852.0<br />
Version message:<br />
9C 7C 00 00 - 31900 (version 0.3.19)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
E6 15 10 4D 00 00 00 00 - Mon Dec 20 21:50:14 EST 2010<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 20 8D - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D - Sender address info - see Network Address<br />
DD 9D 20 2C 3A B4 57 13 - Node random unique ID<br />
00 - "" sub-version string (string is 0 bytes long)<br />
55 81 01 00 - Last block sending node has is block #98645<br />
</pre><br />
<br />
And here's a modern (60002) protocol version client advertising itself to a local peer...<br />
<br />
Newer protocol includes the checksum now, this is from a mainline (satoshi) client during <br />
an outgoing connection to another local client, notice that it does not fill out the <br />
address information at all when the source or destination is "unroutable".<br />
<br />
<pre><br />
<br />
0000 f9 be b4 d9 76 65 72 73 69 6f 6e 00 00 00 00 00 ....version.....<br />
0010 64 00 00 00 35 8d 49 32 62 ea 00 00 01 00 00 00 d...5.I2b.......<br />
0020 00 00 00 00 11 b2 d0 50 00 00 00 00 01 00 00 00 .......P........<br />
0030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ff ff ................<br />
0040 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 00 00 00 00 ff ff 00 00 00 00 00 00 ................<br />
0060 3b 2e b3 5d 8c e6 17 65 0f 2f 53 61 74 6f 73 68 ;..]...e./Satosh<br />
0070 69 3a 30 2e 37 2e 32 2f c0 3e 03 00 i:0.7.2/.>..<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
64 00 00 00 - Payload is 100 bytes long<br />
3B 64 8D 5A - payload checksum<br />
<br />
Version message:<br />
62 EA 00 00 - 60002 (protocol version 60002)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
11 B2 D0 50 00 00 00 00 - Tue Dec 18 10:12:33 PST 2012<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Sender address info - see Network Address<br />
3B 2E B3 5D 8C E6 17 65 - Node ID<br />
0F 2F 53 61 74 6F 73 68 69 3A 30 2E 37 2E 32 2F - "/Satoshi:0.7.2/" sub-version string (string is 15 bytes long)<br />
C0 3E 03 00 - Last block sending node has is block #212672<br />
</pre><br />
<br />
=== verack ===<br />
<br />
The ''verack'' message is sent in reply to ''[[#version|version]]''. This message consists of only a [[#Message structure|message header]] with the command string "verack".<br />
<br />
Hexdump of the verack message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......<br />
0010 00 00 00 00 5D F6 E0 E2 ........<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 61 63 6B 00 00 00 00 00 00 - "verack" command<br />
00 00 00 00 - Payload is 0 bytes long<br />
5D F6 E0 E2 - Checksum<br />
</pre><br />
<br />
=== addr ===<br />
<br />
Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours<br />
<br />
Payload:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of address entries (max: 1000)<br />
|-<br />
| 30x? || addr_list || (uint32_t + [[#Network address|net_addr]])[] || Address of other nodes on the network. version < 209 will only read the first one. The uint32_t is a timestamp (see note below).<br />
|}<br />
<br />
'''Note''': Starting version 31402, addresses are prefixed with a timestamp. If no timestamp is present, the addresses should not be relayed to other peers, unless it is indeed confirmed they are up.<br />
<br />
Hexdump example of ''addr'' message:<br />
<pre><br />
0000 F9 BE B4 D9 61 64 64 72 00 00 00 00 00 00 00 00 ....addr........<br />
0010 1F 00 00 00 ED 52 39 9B 01 E2 15 10 4D 01 00 00 .....R9.....M...<br />
0020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF ................<br />
0030 FF 0A 00 00 01 20 8D ..... .<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
61 64 64 72 00 00 00 00 00 00 00 00 - "addr"<br />
1F 00 00 00 - payload is 31 bytes long<br />
ED 52 39 9B - checksum of payload<br />
<br />
Payload:<br />
01 - 1 address in this message<br />
<br />
Address:<br />
E2 15 10 4D - Mon Dec 20 21:50:10 EST 2010 (only when version is >= 31402)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK service - see version message)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv4: 10.0.0.1, IPv6: ::ffff:10.0.0.1 (IPv4-mapped IPv6 address)<br />
20 8D - port 8333<br />
</pre><br />
<br />
=== inv ===<br />
<br />
Allows a node to advertise its knowledge of one or more objects. It can be received unsolicited, or in reply to ''getblocks''.<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getdata ===<br />
<br />
getdata is used in response to inv, to retrieve the content of a specific object, and is usually sent after receiving an ''inv'' packet, after filtering known elements. It can be used to retrieve transactions, but only if they are in the memory pool or relay set - arbitrary access to transactions in the chain is not allowed to avoid having clients start to depend on nodes having full transaction indexes (which modern nodes do not).<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== notfound ===<br />
<br />
notfound is a response to a getdata, sent if any requested data items could not be relayed, for example, because the requested transaction was not in the memory pool or relay set.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getblocks ===<br />
<br />
Return an ''inv'' packet containing the list of blocks starting right after the last known hash in the block locator object, up to hash_stop or 500 blocks, whichever comes first. <br />
<br />
The locator hashes are processed by a node in the order as they appear in the message. If a block hash is found in the node's main chain, the list of its children is returned back via the ''inv'' message and the remaining locators are ignored, no matter if the requested limit was reached, or not.<br />
<br />
To receive the next blocks hashes, one needs to issue getblocks again with a new block locator object. Keep in mind that some clients may provide blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block; set to zero to get as many blocks as possible (500)<br />
|}<br />
<br />
To create the block locator hashes, keep pushing hashes until you go back to the genesis block. After pushing 10 hashes back, the step backwards doubles every loop:<br />
<br />
<pre><br />
// From libbitcoin which is under AGPL<br />
std::vector<size_t> block_locator_indexes(size_t top_height)<br />
{<br />
std::vector<size_t> indexes;<br />
<br />
// Modify the step in the iteration.<br />
int64_t step = 1;<br />
<br />
// Start at the top of the chain and work backwards.<br />
for (auto index = (int64_t)top_height; index > 0; index -= step)<br />
{<br />
// Push top 10 indexes first, then back off exponentially.<br />
if (indexes.size() >= 10)<br />
step *= 2;<br />
<br />
indexes.push_back((size_t)index);<br />
}<br />
<br />
// Push the genesis block index.<br />
indexes.push_back(0);<br />
return indexes;<br />
}<br />
</pre><br />
<br />
Note that it is allowed to send in fewer known hashes down to a minimum of just one hash. However, the purpose of the block locator object is to detect a wrong branch in the caller's main chain. If the peer detects that you are off the main chain, it will send in block hashes which are earlier than your last known block. So if you just send in your last known hash and it is off the main chain, the peer starts over at block #1.<br />
<br />
=== getheaders ===<br />
<br />
Return a ''headers'' packet containing the headers of blocks starting right after the last known hash in the block locator object, up to hash_stop or 2000 blocks, whichever comes first. To receive the next block headers, one needs to issue getheaders again with a new block locator object. The ''getheaders'' command is used by thin clients to quickly download the block chain where the contents of the transactions would be irrelevant (because they are not ours). Keep in mind that some clients may provide headers of blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block header; set to zero to get as many blocks as possible (2000)<br />
|}<br />
<br />
For the block locator object in this packet, the same rules apply as for the [[Protocol_documentation#getblocks|getblocks]] packet.<br />
<br />
=== tx ===<br />
<br />
''tx'' describes a bitcoin transaction, in reply to ''[[#getdata|getdata]]''<br />
<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Transaction data format version (note, this is signed)<br />
|-<br />
| 1+ || tx_in count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction inputs<br />
|-<br />
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins<br />
|-<br />
| 1+ || tx_out count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction outputs<br />
|-<br />
| 9+ || tx_out || tx_out[] || A list of 1 or more transaction outputs or destinations for coins<br />
|-<br />
| 4 || lock_time || uint32_t || The block number or timestamp at which this transaction is locked:<br />
{|class="wikitable"<br />
! Value !! Description<br />
|-<br />
| 0 || Not locked<br />
|-<br />
| < 500000000 || Block number at which this transaction is locked<br />
|-<br />
| >= 500000000 || UNIX timestamp at which this transaction is locked<br />
|}<br />
If all TxIn inputs have final (0xffffffff) sequence numbers then lock_time is irrelevant. Otherwise, the transaction may not be added to a block until after lock_time (see [[NLockTime]]).<br />
<br />
|}<br />
<br />
TxIn consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 36 || previous_output || outpoint || The previous output transaction reference, as an OutPoint structure<br />
|-<br />
| 1+ || script length || [[Protocol_documentation#Variable_length_integer|var_int]] || The length of the signature script<br />
|-<br />
| ? || signature script || uchar[] || Computational Script for confirming transaction authorization<br />
|-<br />
| 4 || [http://bitcoin.stackexchange.com/q/2025/323 sequence] || uint32_t || Transaction version as defined by the sender. Intended for "replacement" of transactions when information is updated before inclusion into a block.<br />
|}<br />
<br />
The OutPoint structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 32 || hash || char[32] || The hash of the referenced transaction.<br />
|-<br />
| 4 || index || uint32_t || The index of the specific output in the transaction. The first output is 0, etc.<br />
|}<br />
<br />
The Script structure consists of a series of pieces of information and operations related to the value of the transaction.<br />
<br />
(Structure to be expanded in the future… see script.h and script.cpp and [[Script]] for more information)<br />
<br />
The TxOut structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || value || int64_t || Transaction Value<br />
|-<br />
| 1+ || pk_script length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the pk_script<br />
|-<br />
| ? || pk_script || uchar[] || Usually contains the public key as a Bitcoin script setting up conditions to claim this output.<br />
|}<br />
<br />
Example ''tx'' message:<br />
<pre><br />
000000 F9 BE B4 D9 74 78 00 00 00 00 00 00 00 00 00 00 ....tx..........<br />
000010 02 01 00 00 E2 93 CD BE 01 00 00 00 01 6D BD DB .............m..<br />
000020 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D 12 66 E9 .[...Q........f.<br />
000030 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29 00 00 00 .;P......j.6)...<br />
000040 00 8B 48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 ..H0E.!..X..r...<br />
000050 C7 36 7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A .6zz%;..R#...h.:<br />
000060 59 23 3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 Y#?E.W... Y.....<br />
000070 0E 41 83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D .A.z.X.z...XN...<br />
000080 35 BD 96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF 5...6..;...A....<br />
000090 C9 7E F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 .~.6.m...@..!...<br />
0000A0 2A CD 2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC *.+..].}Y... ...<br />
0000B0 4E 02 53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F N.S..=7.o...Q...<br />
0000C0 14 04 2F 46 61 4A 4C 70 C0 F1 4B EF F5 FF FF FF ../FaJLp..K.....<br />
0000D0 FF 02 40 4B 4C 00 00 00 00 00 19 76 A9 14 1A A0 ..@KL......v....<br />
0000E0 CD 1C BE A6 E7 45 8A 7A BA D5 12 A9 D9 EA 1A FB .....E.z........<br />
0000F0 22 5E 88 AC 80 FA E9 C7 00 00 00 00 19 76 A9 14 "^...........v..<br />
000100 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E FD A0 B7 ..[.Cj.....H^...<br />
000110 8B 4E CC 52 88 AC 00 00 00 00 .N.R......<br />
<br />
<br />
Message header:<br />
F9 BE B4 D9 - main network magic bytes<br />
74 78 00 00 00 00 00 00 00 00 00 00 - "tx" command<br />
02 01 00 00 - payload is 258 bytes long<br />
E2 93 CD BE - checksum of payload<br />
<br />
Transaction:<br />
01 00 00 00 - version<br />
<br />
Inputs:<br />
01 - number of transaction inputs<br />
<br />
Input 1:<br />
6D BD DB 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D - previous output (outpoint)<br />
12 66 E9 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29<br />
00 00 00 00<br />
<br />
8B - script is 139 bytes long<br />
<br />
48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 C7 36 - signature script (scriptSig)<br />
7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A 59 23<br />
3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 0E 41<br />
83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D 35 BD<br />
96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF C9 7E<br />
F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 2A CD<br />
2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC 4E 02<br />
53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F 14 04<br />
2F 46 61 4A 4C 70 C0 F1 4B EF F5<br />
<br />
FF FF FF FF - sequence<br />
<br />
Outputs:<br />
02 - 2 Output Transactions<br />
<br />
Output 1:<br />
40 4B 4C 00 00 00 00 00 - 0.05 BTC (5000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 1A A0 CD 1C BE A6 E7 45 8A 7A BA D5 12 - pk_script<br />
A9 D9 EA 1A FB 22 5E 88 AC<br />
<br />
Output 2:<br />
80 FA E9 C7 00 00 00 00 - 33.54 BTC (3354000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E - pk_script<br />
FD A0 B7 8B 4E CC 52 88 AC<br />
<br />
Locktime:<br />
00 00 00 00 - lock time<br />
</pre><br />
<br />
=== block ===<br />
<br />
The '''block''' message is sent in response to a getdata message which requests transaction information from a block hash.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A Unix timestamp recording when this block was created (Currently limited to dates before the year 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated [[Difficulty|difficulty target]] being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| ? || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries<br />
|-<br />
| ? || txns || tx[] || Block transactions, in format of "tx" command<br />
|}<br />
<br />
The SHA256 hash that identifies each block (and which must have a run of 0 bits) is calculated from the first 6 fields of this structure (version, prev_block, merkle_root, timestamp, bits, nonce, and standard SHA256 padding, making two 64-byte chunks in all) and ''not'' from the complete block. To calculate the hash, only two chunks need to be processed by the SHA256 algorithm. Since the ''nonce'' field is in the second chunk, the first chunk stays constant during mining and therefore only the second chunk needs to be processed. However, a Bitcoin hash is the hash of the hash, so two SHA256 rounds are needed for each mining iteration.<br />
See [[Block hashing algorithm]] for details and an example.<br />
<br />
=== headers ===<br />
<br />
The ''headers'' packet returns block headers in response to a ''getheaders'' packet. <br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of block headers<br />
|-<br />
| 81x? || headers || [[Protocol_documentation#Block_Headers|block_header]][] || [[Protocol_documentation#Block_Headers|Block headers]]<br />
|}<br />
<br />
Note that the block headers in this packet include a transaction count (a var_int, so there can be more than 81 bytes per header) as opposed to the block headers that are hashed by miners.<br />
<br />
=== getaddr ===<br />
<br />
The getaddr message sends a request to a node asking for information about known active peers to help with finding potential nodes in the network. The response to receiving this message is to transmit one or more addr messages with one or more peers from a database of known active peers. The typical presumption is that a node is likely to be active if it has been sending a message within the last three hours.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
=== mempool ===<br />
<br />
The mempool message sends a request to a node asking for information about transactions it has verified but which have not yet confirmed. The response to receiving this message is an inv message containing the transaction hashes for all the transactions in the node's mempool.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
It is specified in [https://github.com/bitcoin/bips/blob/master/bip-0035.mediawiki BIP 35]. Since [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 37], if a [[Protocol_documentation#filterload.2C_filteradd.2C_filterclear.2C_merkleblock|bloom filter]] is loaded, only transactions matching the filter are replied.<br />
<br />
=== checkorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== submitorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== reply ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== ping ===<br />
<br />
The ''ping'' message is sent primarily to confirm that the TCP/IP connection is still valid. An error in transmission is presumed to be a closed connection and the address is removed as a current peer.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || random nonce<br />
|}<br />
<br />
=== pong ===<br />
<br />
The ''pong'' message is sent in response to a ''ping'' message. In modern protocol versions, a ''pong'' response is generated using a nonce included in the ping.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || nonce from ping<br />
|}<br />
<br />
<br />
=== reject===<br />
<br />
The ''reject'' message is sent when messages are rejected.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || message || var_str || type of message rejected<br />
|-<br />
| 1 || ccode || char || code relating to rejected message<br />
|-<br />
| 1+ || reason || var_str || text version of reason for rejection<br />
|-<br />
| 0+ || data || char || Optional extra data provided by some errors. Currently, all errors which provide this field fill it with the TXID or block header hash of the object being rejected, so the field is 32 bytes.<br />
|}<br />
<br />
CCodes<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0x01 || REJECT_MALFORMED|| <br />
|-<br />
| 0x10 || REJECT_INVALID ||<br />
|-<br />
| 0x11 || REJECT_OBSOLETE ||<br />
|-<br />
| 0x12 || REJECT_DUPLICATE ||<br />
|-<br />
| 0x40 || REJECT_NONSTANDARD ||<br />
|-<br />
| 0x41 || REJECT_DUST ||<br />
|-<br />
| 0x42 || REJECT_INSUFFICIENTFEE ||<br />
|-<br />
| 0x43 || REJECT_CHECKPOINT ||<br />
|}<br />
<br />
=== filterload, filteradd, filterclear, merkleblock ===<br />
<br />
These messages are related to Bloom filtering of connections and are defined in [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037].<br />
<br />
<br />
The <code>filterload</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || filter || uint8_t[] || The filter itself is simply a bit field of arbitrary byte-aligned size. The maximum size is 36,000 bytes.<br />
|-<br />
| 4 || nHashFuncs || uint32_t || The number of hash functions to use in this filter. The maximum value allowed in this field is 50.<br />
|-<br />
| 4 || nTweak || uint32_t || A random value to add to the seed value in the hash function used by the bloom filter.<br />
|-<br />
| 1 || nFlags || uint8_t || A set of flags that control how matched items are added to the filter.<br />
|}<br />
<br />
See below for a description of the Bloom filter algorithm and how to select nHashFuncs and filter size for a desired false positive rate.<br />
<br />
Upon receiving a <code>filterload</code> command, the remote peer will immediately restrict the broadcast transactions it announces (in inv packets) to transactions matching the filter, where the matching algorithm is specified below. The flags control the update behaviour of the matching algorithm.<br />
<br />
The <code>filteradd</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || data || uint8_t[] || The data element to add to the current filter.<br />
|}<br />
<br />
The data field must be smaller than or equal to 520 bytes in size (the maximum size of any potentially matched object).<br />
<br />
The given data element will be added to the Bloom filter. A filter must have been previously provided using <code>filterload</code>. This command is useful if a new key or script is added to a clients wallet whilst it has connections to the network open, it avoids the need to re-calculate and send an entirely new filter to every peer (though doing so is usually advisable to maintain anonymity).<br />
<br />
The <code>filterclear</code> command has no arguments at all.<br />
<br />
After a filter has been set, nodes don't merely stop announcing non-matching transactions, they can also serve filtered blocks. A filtered block is defined by the <code>merkleblock</code> message and is defined like this:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information, based upon the software version creating this block (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Limited to 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 4 || total_transactions || uint32_t || Number of transactions in the block (including unmatched ones)<br />
|-<br />
| ? || hashes || uint256[] || hashes in depth-first order (including standard varint size prefix)<br />
|-<br />
| ? || flags || byte[] || flag bits, packed per 8 in a byte, least significant bit first (including standard varint size prefix)<br />
|}<br />
<br />
=== alert ===<br />
<br />
An '''alert''' is sent between nodes to send a general notification message throughout the network. If the alert can be confirmed with the signature as having come from the core development group of the Bitcoin software, the message is suggested to be displayed for end-users. Attempts to perform transactions, particularly automated transactions through the client, are suggested to be halted. The text in the Message string should be relayed to log files and any user interfaces.<br />
<br />
Alert format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || payload || uchar[] || Serialized alert payload<br />
|-<br />
| ? || signature || uchar[] || An ECDSA signature of the message<br />
|}<br />
<br />
The developers of Satoshi's client use this public key for signing alerts:<br />
04fc9702847840aaf195de8442ebecedf5b095cdbb9bc716bda9110971b28a49e0ead8564ff0db22209e0374782c093bb899692d524e9d6a6956e7c5ecbcd68284<br />
(hash) 1AGRxqDa5WjUKBwHB9XYEjmkv1ucoUUy1s<br />
<br />
The payload is serialized into a uchar[] to ensure that versions using incompatible alert formats can still relay alerts among one another. The current alert payload format is:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || Version || int32_t || Alert format version<br />
|-<br />
| 8 || RelayUntil || int64_t || The timestamp beyond which nodes should stop relaying this alert<br />
|-<br />
| 8 || Expiration || int64_t || The timestamp beyond which this alert is no longer in effect and should be ignored<br />
|-<br />
| 4 || ID || int32_t || A unique ID number for this alert<br />
|-<br />
| 4 || Cancel || int32_t || All alerts with an ID number less than or equal to this number should be cancelled: deleted and not accepted in the future<br />
|-<br />
| ? || setCancel || set<int32_t> || All alert IDs contained in this set should be cancelled as above<br />
|-<br />
| 4 || MinVer || int32_t || This alert only applies to versions greater than or equal to this version. Other versions should still relay it.<br />
|-<br />
| 4 || MaxVer || int32_t || This alert only applies to versions less than or equal to this version. Other versions should still relay it.<br />
|-<br />
| ? || setSubVer || set<string> || If this set contains any elements, then only nodes that have their subVer contained in this set are affected by the alert. Other versions should still relay it.<br />
|-<br />
| 4 || Priority || int32_t || Relative priority compared to other alerts<br />
|-<br />
| ? || Comment || string || A comment on the alert that is not displayed<br />
|-<br />
| ? || StatusBar || string || The alert message that is displayed to the user<br />
|-<br />
| ? || Reserved || string || Reserved<br />
|}<br />
<br />
Note: '''set<''type''>''' in the table above is a [[#Variable length integer | variable length integer]] followed by the number of fields of the given ''type'' (either int32_t or [[#Variable length string | variable length string]])<br />
<br />
Sample alert (no message header):<br />
73010000003766404f00000000b305434f00000000f2030000f1030000001027000048ee0000<br />
0064000000004653656520626974636f696e2e6f72672f666562323020696620796f75206861<br />
76652074726f75626c6520636f6e6e656374696e672061667465722032302046656272756172<br />
79004730450221008389df45f0703f39ec8c1cc42c13810ffcae14995bb648340219e353b63b<br />
53eb022009ec65e1c1aaeec1fd334c6b684bde2b3f573060d5b70c3a46723326e4e8a4f1<br />
<br />
Version: 1<br />
RelayUntil: 1329620535<br />
Expiration: 1329792435<br />
ID: 1010<br />
Cancel: 1009<br />
setCancel: <empty><br />
MinVer: 10000<br />
MaxVer: 61000<br />
setSubVer: <empty><br />
Priority: 100<br />
Comment: <empty><br />
StatusBar: "See bitcoin.org/feb20 if you have trouble connecting after 20 February"<br />
Reserved: <empty><br />
<br />
=== sendheaders ===<br />
<br />
Request for Direct headers announcement. <br />
<br />
Upon receipt of this message, the node is be permitted, but not required, to announce new blocks by '''headers''' command (instead of '''inv''' command).<br />
<br />
This message is supported by the protocol version >= 70012 or Bitcoin Core version >= 0.12.0.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0130.mediawiki BIP 130] for more information.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
<br />
=== feefilter ===<br />
<br />
The payload is always 8 bytes long and it encodes 64 bit integer value (LSB / little endian) of '''feerate'''.<br />
The value represents a minimal fee and is expressed in satoshis per 1000 bytes.<br />
<br />
Upon receipt of a "feefilter" message, the node will be permitted, but not required, to filter transaction invs for transactions that fall below the feerate provided in the feefilter message interpreted as satoshis per kilobyte.<br />
<br />
The fee filter is additive with a bloom filter for transactions so if an SPV client were to load a bloom filter and send a feefilter message, transactions would only be relayed if they passed both filters.<br />
<br />
Inv's generated from a mempool message are also subject to a fee filter if it exists.<br />
<br />
Feature discovery is enabled by checking protocol version >= 70013<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0133.mediawiki BIP 133] for more information.<br />
<br />
=== sendcmpct ===<br />
<br />
# The sendcmpct message is defined as a message containing a 1-byte integer followed by a 8-byte integer where pchCommand == "sendcmpct".<br />
# The first integer SHALL be interpreted as a boolean (and MUST have a value of either 1 or 0)<br />
# The second integer SHALL be interpreted as a little-endian version number. Nodes sending a sendcmpct message MUST currently set this value to 1.<br />
# Upon receipt of a "sendcmpct" message with the first and second integers set to 1, the node SHOULD announce new blocks by sending a cmpctblock message.<br />
# Upon receipt of a "sendcmpct" message with the first integer set to 0, the node SHOULD NOT announce new blocks by sending a cmpctblock message, but SHOULD announce new blocks by sending invs or headers, as defined by BIP130.<br />
# Upon receipt of a "sendcmpct" message with the second integer set to something other than 1, nodes MUST treat the peer as if they had not received the message (as it indicates the peer will provide an unexpected encoding in <br />
# cmpctblock, and/or other, messages). This allows future versions to send duplicate sendcmpct messages with different versions as a part of a version handshake for future versions.<br />
# Nodes SHOULD check for a protocol version of >= 70014 before sending sendcmpct messages.<br />
# Nodes MUST NOT send a request for a MSG_CMPCT_BLOCK object to a peer before having received a sendcmpct message from that peer.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== cmpctblock ===<br />
<br />
# The cmpctblock message is defined as as a message containing a serialized HeaderAndShortIDs message and pchCommand == "cmpctblock".<br />
# Upon receipt of a cmpctblock message after sending a sendcmpct message, nodes SHOULD calculate the short transaction ID for each unconfirmed transaction they have available (ie in their mempool) and compare each to each short transaction ID in the cmpctblock message.<br />
# After finding already-available transactions, nodes which do not have all transactions available to reconstruct the full block SHOULD request the missing transactions using a getblocktxn message.<br />
# A node MUST NOT send a cmpctblock message unless they are able to respond to a getblocktxn message which requests every transaction in the block.<br />
# A node MUST NOT send a cmpctblock message without having validated that the header properly commits to each transaction in the block, and properly builds on top of the existing chain with a valid proof-of-work. A node MAY send a cmpctblock before validating that each transaction in the block validly spends existing UTXO set entries.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== getblocktxn ===<br />
<br />
# The getblocktxn message is defined as as a message containing a serialized BlockTransactionsRequest message and pchCommand == "getblocktxn".<br />
# Upon receipt of a properly-formatted getblocktxnmessage, nodes which recently provided the sender of such a message a cmpctblock for the block hash identified in this message MUST respond with an appropriate blocktxn message. Such a blocktxn message MUST contain exactly and only each transaction which is present in the appropriate block at the index specified in the getblocktxn indexes list, in the order requested.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== blocktxn ===<br />
<br />
# The blocktxn message is defined as as a message containing a serialized BlockTransactions message and pchCommand == "blocktxn".<br />
# Upon receipt of a properly-formatted requested blocktxn message, nodes SHOULD attempt to reconstruct the full block by:<br />
# Taking the prefilledtxn transactions from the original cmpctblock and placing them in the marked positions.<br />
# For each short transaction ID from the original cmpctblock, in order, find the corresponding transaction either from the blocktxn message or from other sources and place it in the first available position in the block.<br />
# Once the block has been reconstructed, it shall be processed as normal, keeping in mind that short transaction IDs are expected to occasionally collide, and that nodes MUST NOT be penalized for such collisions, wherever they # appear.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
== Scripting ==<br />
<br />
See [[script]].<br />
<br />
==See Also==<br />
<br />
* [[Network]]<br />
* [[Protocol rules]]<br />
* [[Hardfork Wishlist]]<br />
* [https://bitcoin.org/en/developer-documentation Developer Documentation on bitcoin.org]<br />
* Bitcoin dissectors for Wireshark: https://github.com/lbotsch/wireshark-bitcoin https://github.com/op-sig/bitcoin-wireshark-dissector<br />
<br />
==References==<br />
<references /><br />
<br />
[[zh-cn:协议说明]]<br />
[[Category:Technical]]<br />
[[Category:Developer]]<br />
<br />
{{Bitcoin Core documentation}}</div>Tonikthttps://en.bitcoin.it/w/index.php?title=Protocol_documentation&diff=61497Protocol documentation2016-08-25T12:50:16Z<p>Tonikt: /* HeaderAndShortIDs */</p>
<hr />
<div>This page ''describes'' the behavior of the [[Original Bitcoin client|reference client]]. The Bitcoin protocol is specified by the behavior of the reference client, not by this page. In particular, while this page is quite complete in describing the network protocol, it does not attempt to list all of the rules for block or transaction validity.<br />
<br />
Type names used in this documentation are from the C99 standard.<br />
<br />
For protocol used in mining, see [[getblocktemplate]].<br />
<br />
==Common standards==<br />
<br />
=== Hashes ===<br />
<br />
Usually, when a hash is computed within bitcoin, it is computed twice. Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-256] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when a shorter hash is desirable (for example when creating a bitcoin address).<br />
<br />
Example of double-SHA-256 encoding of string "hello":<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round of sha-256)<br />
9595c9df90075148eb06860365df33584b75bff782a510c6cd4883a419833d50 (second round of sha-256)<br />
<br />
For bitcoin addresses (RIPEMD-160) this would give:<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round is sha-256)<br />
b6a9c8c230722b7c748331a8b450f05566dc7d0f (with ripemd-160)<br />
<br />
=== Merkle Trees ===<br />
<br />
Merkle trees are binary trees of hashes. Merkle trees in bitcoin use a '''double''' SHA-256, the SHA-256 hash of the SHA-256 hash of something.<br />
<br />
If, when forming a row in the tree (other than the root of the tree), it would have an odd number of elements, the final double-hash is duplicated to ensure that the row has an even number of hashes.<br />
<br />
First form the bottom row of the tree with the ordered double-SHA-256 hashes of the byte streams of the transactions in the block.<br />
<br />
Then the row above it consists of half that number of hashes. Each entry is the double-SHA-256 of the 64-byte concatenation of the corresponding two hashes below it in the tree.<br />
<br />
This procedure repeats recursively until we reach a row consisting of just a single double-hash. This is the '''Merkle root''' of the tree.<br />
<br />
For example, imagine a block with three transactions ''a'', ''b'' and ''c''. The Merkle tree is: <br />
<br />
d1 = dhash(a)<br />
d2 = dhash(b)<br />
d3 = dhash(c)<br />
d4 = dhash(c) # a, b, c are 3. that's an odd number, so we take the c twice<br />
<br />
d5 = dhash(d1 concat d2)<br />
d6 = dhash(d3 concat d4)<br />
<br />
d7 = dhash(d5 concat d6)<br />
<br />
where<br />
<br />
dhash(a) = sha256(sha256(a))<br />
<br />
''d7'' is the Merkle root of the 3 transactions in this block.<br />
<br />
Note: Hashes in Merkle Tree displayed in the [[Block Explorer]] are of little-endian notation. For some implementations and [http://www.fileformat.info/tool/hash.htm calculations], the bits need to be reversed before they are hashed, and again after the hashing operation.<br />
<br />
=== Signatures ===<br />
<br />
Bitcoin uses [http://en.wikipedia.org/wiki/Elliptic_curve_cryptography Elliptic Curve] [http://en.wikipedia.org/wiki/Digital_Signature_Algorithm Digital Signature Algorithm] ([http://en.wikipedia.org/wiki/Elliptic_Curve_DSA ECDSA]) to sign transactions. <br />
<br />
For [[ECDSA]] the secp256k1 curve from http://www.secg.org/collateral/sec2_final.pdf is used.<br />
<br />
Public keys (in scripts) are given as 04 <x> <y> where ''x'' and ''y'' are 32 byte big-endian integers representing the coordinates of a point on the curve or in compressed form given as <sign> <x> where <sign> is 0x02 if ''y'' is even and 0x03 if ''y'' is odd.<br />
<br />
Signatures use [http://en.wikipedia.org/wiki/Distinguished_Encoding_Rules DER encoding] to pack the ''r'' and ''s'' components into a single byte stream (this is also what OpenSSL produces by default).<br />
<br />
=== Transaction Verification ===<br />
Transactions are cryptographically signed records that reassign ownership of Bitcoins to new addresses. Transactions have ''inputs'' - records which reference the funds from other previous transactions - and ''outputs'' - records which determine the new owner of the transferred Bitcoins, and which will be referenced as inputs in future transactions as those funds are respent.<br />
<br />
Each ''input'' must have a cryptographic digital signature that unlocks the funds from the prior transaction. Only the person possessing the appropriate [[private key]] is able to create a satisfactory signature; this in effect ensures that funds can only be spent by their owners.<br />
<br />
Each ''output'' determines which Bitcoin address (or other criteria, see [[Script]]) is the recipient of the funds.<br />
<br />
In a transaction, the sum of all inputs must be equal to or greater than the sum of all outputs. If the inputs exceed the outputs, the difference is considered a [[transaction fee]], and is redeemable by whoever first includes the transaction into the block chain.<br />
<br />
A special kind of transaction, called a [[coinbase transaction]], has no inputs. It is created by [[miners]], and there is one coinbase transaction per block. Because each block comes with a reward of newly created Bitcoins (e.g. 50 BTC for the first 210,000 blocks), the first transaction of a block is, with few exceptions, the transaction that grants those coins to their recipient (the miner). In addition to the newly created Bitcoins, the coinbase transaction is also used for assigning the recipient of any transaction fees that were paid within the other transactions being included in the same block. The coinbase transaction can assign the entire reward to a single Bitcoin address, or split it in portions among multiple addresses, just like any other transaction. Coinbase transactions always contain outputs totalling the sum of the block reward plus all transaction fees collected from the other transactions in the same block.<br />
<br />
The [[coinbase transaction]] in block zero cannot be spent. This is due to a quirk of the reference client implementation that would open the potential for a block chain fork if some nodes accepted the spend and others did not<ref>[http://bitcointalk.org/index.php?topic=119645.msg1288552#msg1288552 Block 0 Network Fork]</ref>.<br />
<br />
Most Bitcoin outputs encumber the newly transferred coins with a single ECDSA private key. The actual record saved with inputs and outputs isn't necessarily a key, but a ''script''. Bitcoin uses an interpreted scripting system to determine whether an output's criteria have been satisfied, with which more complex operations are possible, such as outputs that require two ECDSA signatures, or two-of-three-signature schemes. An output that references a single Bitcoin address is a ''typical'' output; an output actually contains this information in the form of a script that requires a single ECDSA signature (see [[OP_CHECKSIG]]). The output script specifies what must be provided to unlock the funds later, and when the time comes in the future to spend the transaction in another input, that input must provide all of the thing(s) that satisfy the requirements defined by the original output script.<br />
<br />
=== Addresses ===<br />
<br />
A bitcoin address is in fact the hash of a ECDSA public key, computed this way:<br />
<br />
Version = 1 byte of 0 (zero); on the test network, this is 1 byte of 111<br />
Key hash = Version concatenated with RIPEMD-160(SHA-256(public key))<br />
Checksum = 1st 4 bytes of SHA-256(SHA-256(Key hash))<br />
Bitcoin Address = Base58Encode(Key hash concatenated with Checksum)<br />
<br />
The Base58 encoding used is home made, and has some differences. Especially, leading zeroes are kept as single zeroes when conversion happens.<br />
<br />
== Common structures ==<br />
<br />
Almost all integers are encoded in little endian. Only IP or port number are encoded big endian.<br />
<br />
=== Message structure ===<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown<br />
|-<br />
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| 4 || length || uint32_t || Length of payload in number of bytes<br />
|-<br />
| 4 || checksum || uint32_t || First 4 bytes of sha256(sha256(payload))<br />
|-<br />
| ? || payload || uchar[] || The actual data<br />
|}<br />
<br />
<br />
Known magic values:<br />
<br />
{|class="wikitable"<br />
! Network !! Magic value !! Sent over wire as<br />
|-<br />
| main || 0xD9B4BEF9 || F9 BE B4 D9<br />
|-<br />
| testnet || 0xDAB5BFFA || FA BF B5 DA<br />
|-<br />
| testnet3 || 0x0709110B || 0B 11 09 07<br />
|-<br />
| namecoin || 0xFEB4BEF9 || F9 BE B4 FE<br />
|}<br />
<br />
=== Variable length integer ===<br />
<br />
Integer can be encoded depending on the represented value to save space.<br />
Variable length integers always precede an array/vector of a type of data that may vary in length.<br />
Longer numbers are encoded in little endian.<br />
<br />
{|class="wikitable"<br />
! Value !! Storage length !! Format<br />
|-<br />
| < 0xFD || 1 || uint8_t<br />
|-<br />
| <= 0xFFFF || 3 || 0xFD followed by the length as uint16_t<br />
|-<br />
| <= 0xFFFF FFFF || 5 || 0xFE followed by the length as uint32_t<br />
|-<br />
| - || 9 || 0xFF followed by the length as uint64_t<br />
|}<br />
<br />
If you're reading the Satoshi client code (BitcoinQT) it refers to this encoding as a "CompactSize". Modern BitcoinQT also has the CVarInt class which implements an even more compact integer for the purpose of local storage (which is incompatible with "CompactSize" described here). CVarInt is not a part of the protocol.<br />
<br />
=== Variable length string ===<br />
<br />
Variable length string can be stored using a variable length integer followed by the string itself.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the string<br />
|-<br />
| ? || string || char[] || The string itself (can be empty)<br />
|}<br />
<br />
=== Network address ===<br />
<br />
When a network address is needed somewhere, this structure is used. Network addresses are not prefixed with a timestamp in the version message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || time || uint32 || the Time (version >= 31402). '''Not present in version message.'''<br />
|-<br />
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]<br />
|-<br />
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The original client only supported IPv4 and only read the last 4 bytes to get the IPv4 address. However, the IPv4 address is written into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]<br />
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).<br />
|-<br />
| 2 || port || uint16_t || port number, network byte order<br />
|}<br />
<br />
Hexdump example of Network address structure<br />
<br />
<pre><br />
0000 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0010 00 00 FF FF 0A 00 00 01 20 8D ........ .<br />
<br />
Network address:<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK: see services listed under version command)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv6: ::ffff:a00:1 or IPv4: 10.0.0.1<br />
20 8D - Port 8333<br />
</pre><br />
<br />
=== Inventory Vectors ===<br />
<br />
Inventory vectors are used for notifying other nodes about objects they have or data which is being requested.<br />
<br />
Inventory vectors consist of the following data format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || type || uint32_t || Identifies the object type linked to this inventory<br />
|-<br />
| 32 || hash || char[32] || Hash of the object<br />
|}<br />
<br />
<br />
The object type is currently defined as one of the following possibilities:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0 || ERROR || Any data of with this number may be ignored<br />
|-<br />
| 1 || MSG_TX || Hash is related to a transaction<br />
|-<br />
| 2 || MSG_BLOCK || Hash is related to a data block<br />
|-<br />
| 3 || MSG_FILTERED_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a merkleblock message rather than a block message; this only works if a bloom filter has been set.<br />
|-<br />
| 4 || MSG_CMPCT_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a cmpctblock message. See BIP 152 for more info.<br />
|}<br />
<br />
Other Data Type values are considered reserved for future implementations.<br />
<br />
=== Block Headers ===<br />
<br />
Block headers are sent in a headers packet in response to a getheaders message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Will overflow in 2106<ref>https://en.wikipedia.org/wiki/Unix_time#Notable_events_in_Unix_time</ref>)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 1 || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries, this value is always 0<br />
|}<br />
<br />
cf. [[Block hashing algorithm]]<br />
<br />
=== Differential encoding === <br />
Several uses of CompactSize below are "differentially encoded". For these, instead of using raw indexes, the number encoded is the difference between the current index and the previous index, minus one. For example, a first index of 0 implies a real index of 0, a second index of 0 thereafter refers to a real index of 1, etc.<br />
<br />
=== PrefilledTransaction ===<br />
<br />
A PrefilledTransaction structure is used in HeaderAndShortIDs to provide a list of a few transactions explicitly.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| index || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1, 3 bytes || Compact Size, differentially encoded since the last PrefilledTransaction in a list || The index into the block at which this transaction is<br />
|-<br />
| tx || Transaction || variable || As encoded in [[Protocol_documentation#tx|tx messages]] || The transaction which is in the block at index index.<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== HeaderAndShortIDs ===<br />
<br />
A HeaderAndShortIDs structure is used to relay a block header, the short transactions IDs used for matching already-available transactions, and a select few transactions which we expect a peer may be missing.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| header || Block header || 80 bytes || First 80 bytes of the block as defined by the encoding used by "block" messages || The header of the block being provided<br />
|-<br />
| nonce || uint64_t || 8 bytes || Little Endian || A nonce for use in short transaction ID calculations<br />
|-<br />
| shortids_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of short transaction IDs in shortids (ie block tx count - prefilledtxn_length)<br />
|-<br />
| shortids || List of 6-byte integers || 6*shortids_length bytes || Little Endian || The [[Protocol_documentation#Short_transaction_ID|short transaction IDs]] calculated from the transactions which were not provided explicitly in prefilledtxn<br />
|-<br />
| prefilledtxn_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of prefilled transactions in prefilledtxn (ie block tx count - shortids_length)<br />
|-<br />
| prefilledtxn || List of PrefilledTransactions || variable size*prefilledtxn_length || As defined by [[Protocol_documentation#PrefilledTransaction|PrefilledTransaction]] definition, above || Used to provide the coinbase transaction and a select few which we expect a peer may be missing<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== BlockTransactionsRequest ===<br />
<br />
A BlockTransactionsRequest structure is used to list transaction indexes in a block being requested.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| blockhash || Binary blob || 32 bytes || The output from a double-SHA256 of the block header, as used elsewhere || The blockhash of the block which the transactions being requested are in<br />
|-<br />
| indexes_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of transactions being requested<br />
|-<br />
| indexes || List of [[Protocol_documentation#Variable_length_integer|CompactSizes]] || 1 or 3 bytes*indexes_length || Differentially encoded || The indexes of the transactions being requested in the block<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== BlockTransactions ===<br />
<br />
A BlockTransactions structure is used to provide some of the transactions in a block, as requested.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| blockhash || Binary blob || 32 bytes || The output from a double-SHA256 of the block header, as used elsewhere || The blockhash of the block which the transactions being provided are in<br />
|-<br />
| transactions_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of transactions provided<br />
|-<br />
| transactions || List of Transactions || variable || As encoded in "tx" messages || The transactions provided<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== Short transaction ID ===<br />
<br />
Short transaction IDs are used to represent a transaction without sending a full 256-bit hash. They are calculated by:<br />
<br />
# single-SHA256 hashing the block header with the nonce appended (in little-endian)<br />
# Running SipHash-2-4 with the input being the transaction ID and the keys (k0/k1) set to the first two little-endian 64-bit integers from the above hash, respectively.<br />
# Dropping the 2 most significant bytes from the SipHash output to make it 6 bytes.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
== Message types ==<br />
<br />
=== version ===<br />
<br />
When a node creates an outgoing connection, it will immediately [[Version Handshake|advertise]] its version. The remote node will respond with its version. No further communication is possible until both peers have exchanged their version.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Identifies protocol version being used by the node<br />
|-<br />
| 8 || services || uint64_t || bitfield of features to be enabled for this connection<br />
|-<br />
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds<br />
|-<br />
| 26 || addr_recv || [[#Network address|net_addr]] || The network address of the node receiving this message<br />
|-<br />
|colspan="4"| Fields below require version ≥ 106<br />
|-<br />
| 26 || addr_from || [[#Network address|net_addr]] || The network address of the node emitting this message<br />
|-<br />
| 8 || nonce || uint64_t || Node random nonce, randomly generated every time a version packet is sent. This nonce is used to detect connections to self.<br />
|-<br />
| ? || user_agent || [[#Variable length string|var_str]] || [https://github.com/bitcoin/bips/blob/master/bip-0014.mediawiki User Agent] (0x00 if string is 0 bytes long)<br />
|-<br />
| 4 || start_height || int32_t || The last block received by the emitting node<br />
|-<br />
|colspan="4"| Fields below require version ≥ 70001<br />
|-<br />
| 1 || relay || bool || Whether the remote peer should announce relayed transactions or not, see [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037]<br />
|}<br />
<br />
A "verack" packet shall be sent if the version packet was accepted.<br />
<br />
The following services are currently assigned:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 1 || NODE_NETWORK || This node can be asked for full blocks instead of just headers.<br />
|}<br />
<br />
Hexdump example of version message (OBSOLETE EXAMPLE: This example lacks a checksum and user-agent):<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....<br />
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........<br />
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............<br />
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................<br />
0040 20 8D 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,<br />
0060 3A B4 57 13 00 55 81 01 00 :.W..U...<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
55 00 00 00 - Payload is 85 bytes long<br />
- No checksum in version message until 20 February 2012. See https://bitcointalk.org/index.php?topic=55852.0<br />
Version message:<br />
9C 7C 00 00 - 31900 (version 0.3.19)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
E6 15 10 4D 00 00 00 00 - Mon Dec 20 21:50:14 EST 2010<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 20 8D - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D - Sender address info - see Network Address<br />
DD 9D 20 2C 3A B4 57 13 - Node random unique ID<br />
00 - "" sub-version string (string is 0 bytes long)<br />
55 81 01 00 - Last block sending node has is block #98645<br />
</pre><br />
<br />
And here's a modern (60002) protocol version client advertising itself to a local peer...<br />
<br />
Newer protocol includes the checksum now, this is from a mainline (satoshi) client during <br />
an outgoing connection to another local client, notice that it does not fill out the <br />
address information at all when the source or destination is "unroutable".<br />
<br />
<pre><br />
<br />
0000 f9 be b4 d9 76 65 72 73 69 6f 6e 00 00 00 00 00 ....version.....<br />
0010 64 00 00 00 35 8d 49 32 62 ea 00 00 01 00 00 00 d...5.I2b.......<br />
0020 00 00 00 00 11 b2 d0 50 00 00 00 00 01 00 00 00 .......P........<br />
0030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ff ff ................<br />
0040 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 00 00 00 00 ff ff 00 00 00 00 00 00 ................<br />
0060 3b 2e b3 5d 8c e6 17 65 0f 2f 53 61 74 6f 73 68 ;..]...e./Satosh<br />
0070 69 3a 30 2e 37 2e 32 2f c0 3e 03 00 i:0.7.2/.>..<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
64 00 00 00 - Payload is 100 bytes long<br />
3B 64 8D 5A - payload checksum<br />
<br />
Version message:<br />
62 EA 00 00 - 60002 (protocol version 60002)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
11 B2 D0 50 00 00 00 00 - Tue Dec 18 10:12:33 PST 2012<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Sender address info - see Network Address<br />
3B 2E B3 5D 8C E6 17 65 - Node ID<br />
0F 2F 53 61 74 6F 73 68 69 3A 30 2E 37 2E 32 2F - "/Satoshi:0.7.2/" sub-version string (string is 15 bytes long)<br />
C0 3E 03 00 - Last block sending node has is block #212672<br />
</pre><br />
<br />
=== verack ===<br />
<br />
The ''verack'' message is sent in reply to ''[[#version|version]]''. This message consists of only a [[#Message structure|message header]] with the command string "verack".<br />
<br />
Hexdump of the verack message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......<br />
0010 00 00 00 00 5D F6 E0 E2 ........<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 61 63 6B 00 00 00 00 00 00 - "verack" command<br />
00 00 00 00 - Payload is 0 bytes long<br />
5D F6 E0 E2 - Checksum<br />
</pre><br />
<br />
=== addr ===<br />
<br />
Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours<br />
<br />
Payload:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of address entries (max: 1000)<br />
|-<br />
| 30x? || addr_list || (uint32_t + [[#Network address|net_addr]])[] || Address of other nodes on the network. version < 209 will only read the first one. The uint32_t is a timestamp (see note below).<br />
|}<br />
<br />
'''Note''': Starting version 31402, addresses are prefixed with a timestamp. If no timestamp is present, the addresses should not be relayed to other peers, unless it is indeed confirmed they are up.<br />
<br />
Hexdump example of ''addr'' message:<br />
<pre><br />
0000 F9 BE B4 D9 61 64 64 72 00 00 00 00 00 00 00 00 ....addr........<br />
0010 1F 00 00 00 ED 52 39 9B 01 E2 15 10 4D 01 00 00 .....R9.....M...<br />
0020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF ................<br />
0030 FF 0A 00 00 01 20 8D ..... .<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
61 64 64 72 00 00 00 00 00 00 00 00 - "addr"<br />
1F 00 00 00 - payload is 31 bytes long<br />
ED 52 39 9B - checksum of payload<br />
<br />
Payload:<br />
01 - 1 address in this message<br />
<br />
Address:<br />
E2 15 10 4D - Mon Dec 20 21:50:10 EST 2010 (only when version is >= 31402)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK service - see version message)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv4: 10.0.0.1, IPv6: ::ffff:10.0.0.1 (IPv4-mapped IPv6 address)<br />
20 8D - port 8333<br />
</pre><br />
<br />
=== inv ===<br />
<br />
Allows a node to advertise its knowledge of one or more objects. It can be received unsolicited, or in reply to ''getblocks''.<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getdata ===<br />
<br />
getdata is used in response to inv, to retrieve the content of a specific object, and is usually sent after receiving an ''inv'' packet, after filtering known elements. It can be used to retrieve transactions, but only if they are in the memory pool or relay set - arbitrary access to transactions in the chain is not allowed to avoid having clients start to depend on nodes having full transaction indexes (which modern nodes do not).<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== notfound ===<br />
<br />
notfound is a response to a getdata, sent if any requested data items could not be relayed, for example, because the requested transaction was not in the memory pool or relay set.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getblocks ===<br />
<br />
Return an ''inv'' packet containing the list of blocks starting right after the last known hash in the block locator object, up to hash_stop or 500 blocks, whichever comes first. <br />
<br />
The locator hashes are processed by a node in the order as they appear in the message. If a block hash is found in the node's main chain, the list of its children is returned back via the ''inv'' message and the remaining locators are ignored, no matter if the requested limit was reached, or not.<br />
<br />
To receive the next blocks hashes, one needs to issue getblocks again with a new block locator object. Keep in mind that some clients may provide blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block; set to zero to get as many blocks as possible (500)<br />
|}<br />
<br />
To create the block locator hashes, keep pushing hashes until you go back to the genesis block. After pushing 10 hashes back, the step backwards doubles every loop:<br />
<br />
<pre><br />
// From libbitcoin which is under AGPL<br />
std::vector<size_t> block_locator_indexes(size_t top_height)<br />
{<br />
std::vector<size_t> indexes;<br />
<br />
// Modify the step in the iteration.<br />
int64_t step = 1;<br />
<br />
// Start at the top of the chain and work backwards.<br />
for (auto index = (int64_t)top_height; index > 0; index -= step)<br />
{<br />
// Push top 10 indexes first, then back off exponentially.<br />
if (indexes.size() >= 10)<br />
step *= 2;<br />
<br />
indexes.push_back((size_t)index);<br />
}<br />
<br />
// Push the genesis block index.<br />
indexes.push_back(0);<br />
return indexes;<br />
}<br />
</pre><br />
<br />
Note that it is allowed to send in fewer known hashes down to a minimum of just one hash. However, the purpose of the block locator object is to detect a wrong branch in the caller's main chain. If the peer detects that you are off the main chain, it will send in block hashes which are earlier than your last known block. So if you just send in your last known hash and it is off the main chain, the peer starts over at block #1.<br />
<br />
=== getheaders ===<br />
<br />
Return a ''headers'' packet containing the headers of blocks starting right after the last known hash in the block locator object, up to hash_stop or 2000 blocks, whichever comes first. To receive the next block headers, one needs to issue getheaders again with a new block locator object. The ''getheaders'' command is used by thin clients to quickly download the block chain where the contents of the transactions would be irrelevant (because they are not ours). Keep in mind that some clients may provide headers of blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block header; set to zero to get as many blocks as possible (2000)<br />
|}<br />
<br />
For the block locator object in this packet, the same rules apply as for the [[Protocol_documentation#getblocks|getblocks]] packet.<br />
<br />
=== tx ===<br />
<br />
''tx'' describes a bitcoin transaction, in reply to ''[[#getdata|getdata]]''<br />
<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Transaction data format version (note, this is signed)<br />
|-<br />
| 1+ || tx_in count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction inputs<br />
|-<br />
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins<br />
|-<br />
| 1+ || tx_out count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction outputs<br />
|-<br />
| 9+ || tx_out || tx_out[] || A list of 1 or more transaction outputs or destinations for coins<br />
|-<br />
| 4 || lock_time || uint32_t || The block number or timestamp at which this transaction is locked:<br />
{|class="wikitable"<br />
! Value !! Description<br />
|-<br />
| 0 || Not locked<br />
|-<br />
| < 500000000 || Block number at which this transaction is locked<br />
|-<br />
| >= 500000000 || UNIX timestamp at which this transaction is locked<br />
|}<br />
If all TxIn inputs have final (0xffffffff) sequence numbers then lock_time is irrelevant. Otherwise, the transaction may not be added to a block until after lock_time (see [[NLockTime]]).<br />
<br />
|}<br />
<br />
TxIn consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 36 || previous_output || outpoint || The previous output transaction reference, as an OutPoint structure<br />
|-<br />
| 1+ || script length || [[Protocol_documentation#Variable_length_integer|var_int]] || The length of the signature script<br />
|-<br />
| ? || signature script || uchar[] || Computational Script for confirming transaction authorization<br />
|-<br />
| 4 || [http://bitcoin.stackexchange.com/q/2025/323 sequence] || uint32_t || Transaction version as defined by the sender. Intended for "replacement" of transactions when information is updated before inclusion into a block.<br />
|}<br />
<br />
The OutPoint structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 32 || hash || char[32] || The hash of the referenced transaction.<br />
|-<br />
| 4 || index || uint32_t || The index of the specific output in the transaction. The first output is 0, etc.<br />
|}<br />
<br />
The Script structure consists of a series of pieces of information and operations related to the value of the transaction.<br />
<br />
(Structure to be expanded in the future… see script.h and script.cpp and [[Script]] for more information)<br />
<br />
The TxOut structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || value || int64_t || Transaction Value<br />
|-<br />
| 1+ || pk_script length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the pk_script<br />
|-<br />
| ? || pk_script || uchar[] || Usually contains the public key as a Bitcoin script setting up conditions to claim this output.<br />
|}<br />
<br />
Example ''tx'' message:<br />
<pre><br />
000000 F9 BE B4 D9 74 78 00 00 00 00 00 00 00 00 00 00 ....tx..........<br />
000010 02 01 00 00 E2 93 CD BE 01 00 00 00 01 6D BD DB .............m..<br />
000020 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D 12 66 E9 .[...Q........f.<br />
000030 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29 00 00 00 .;P......j.6)...<br />
000040 00 8B 48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 ..H0E.!..X..r...<br />
000050 C7 36 7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A .6zz%;..R#...h.:<br />
000060 59 23 3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 Y#?E.W... Y.....<br />
000070 0E 41 83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D .A.z.X.z...XN...<br />
000080 35 BD 96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF 5...6..;...A....<br />
000090 C9 7E F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 .~.6.m...@..!...<br />
0000A0 2A CD 2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC *.+..].}Y... ...<br />
0000B0 4E 02 53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F N.S..=7.o...Q...<br />
0000C0 14 04 2F 46 61 4A 4C 70 C0 F1 4B EF F5 FF FF FF ../FaJLp..K.....<br />
0000D0 FF 02 40 4B 4C 00 00 00 00 00 19 76 A9 14 1A A0 ..@KL......v....<br />
0000E0 CD 1C BE A6 E7 45 8A 7A BA D5 12 A9 D9 EA 1A FB .....E.z........<br />
0000F0 22 5E 88 AC 80 FA E9 C7 00 00 00 00 19 76 A9 14 "^...........v..<br />
000100 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E FD A0 B7 ..[.Cj.....H^...<br />
000110 8B 4E CC 52 88 AC 00 00 00 00 .N.R......<br />
<br />
<br />
Message header:<br />
F9 BE B4 D9 - main network magic bytes<br />
74 78 00 00 00 00 00 00 00 00 00 00 - "tx" command<br />
02 01 00 00 - payload is 258 bytes long<br />
E2 93 CD BE - checksum of payload<br />
<br />
Transaction:<br />
01 00 00 00 - version<br />
<br />
Inputs:<br />
01 - number of transaction inputs<br />
<br />
Input 1:<br />
6D BD DB 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D - previous output (outpoint)<br />
12 66 E9 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29<br />
00 00 00 00<br />
<br />
8B - script is 139 bytes long<br />
<br />
48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 C7 36 - signature script (scriptSig)<br />
7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A 59 23<br />
3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 0E 41<br />
83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D 35 BD<br />
96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF C9 7E<br />
F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 2A CD<br />
2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC 4E 02<br />
53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F 14 04<br />
2F 46 61 4A 4C 70 C0 F1 4B EF F5<br />
<br />
FF FF FF FF - sequence<br />
<br />
Outputs:<br />
02 - 2 Output Transactions<br />
<br />
Output 1:<br />
40 4B 4C 00 00 00 00 00 - 0.05 BTC (5000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 1A A0 CD 1C BE A6 E7 45 8A 7A BA D5 12 - pk_script<br />
A9 D9 EA 1A FB 22 5E 88 AC<br />
<br />
Output 2:<br />
80 FA E9 C7 00 00 00 00 - 33.54 BTC (3354000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E - pk_script<br />
FD A0 B7 8B 4E CC 52 88 AC<br />
<br />
Locktime:<br />
00 00 00 00 - lock time<br />
</pre><br />
<br />
=== block ===<br />
<br />
The '''block''' message is sent in response to a getdata message which requests transaction information from a block hash.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A Unix timestamp recording when this block was created (Currently limited to dates before the year 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated [[Difficulty|difficulty target]] being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| ? || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries<br />
|-<br />
| ? || txns || tx[] || Block transactions, in format of "tx" command<br />
|}<br />
<br />
The SHA256 hash that identifies each block (and which must have a run of 0 bits) is calculated from the first 6 fields of this structure (version, prev_block, merkle_root, timestamp, bits, nonce, and standard SHA256 padding, making two 64-byte chunks in all) and ''not'' from the complete block. To calculate the hash, only two chunks need to be processed by the SHA256 algorithm. Since the ''nonce'' field is in the second chunk, the first chunk stays constant during mining and therefore only the second chunk needs to be processed. However, a Bitcoin hash is the hash of the hash, so two SHA256 rounds are needed for each mining iteration.<br />
See [[Block hashing algorithm]] for details and an example.<br />
<br />
=== headers ===<br />
<br />
The ''headers'' packet returns block headers in response to a ''getheaders'' packet. <br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of block headers<br />
|-<br />
| 81x? || headers || [[Protocol_documentation#Block_Headers|block_header]][] || [[Protocol_documentation#Block_Headers|Block headers]]<br />
|}<br />
<br />
Note that the block headers in this packet include a transaction count (a var_int, so there can be more than 81 bytes per header) as opposed to the block headers that are hashed by miners.<br />
<br />
=== getaddr ===<br />
<br />
The getaddr message sends a request to a node asking for information about known active peers to help with finding potential nodes in the network. The response to receiving this message is to transmit one or more addr messages with one or more peers from a database of known active peers. The typical presumption is that a node is likely to be active if it has been sending a message within the last three hours.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
=== mempool ===<br />
<br />
The mempool message sends a request to a node asking for information about transactions it has verified but which have not yet confirmed. The response to receiving this message is an inv message containing the transaction hashes for all the transactions in the node's mempool.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
It is specified in [https://github.com/bitcoin/bips/blob/master/bip-0035.mediawiki BIP 35]. Since [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 37], if a [[Protocol_documentation#filterload.2C_filteradd.2C_filterclear.2C_merkleblock|bloom filter]] is loaded, only transactions matching the filter are replied.<br />
<br />
=== checkorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== submitorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== reply ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== ping ===<br />
<br />
The ''ping'' message is sent primarily to confirm that the TCP/IP connection is still valid. An error in transmission is presumed to be a closed connection and the address is removed as a current peer.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || random nonce<br />
|}<br />
<br />
=== pong ===<br />
<br />
The ''pong'' message is sent in response to a ''ping'' message. In modern protocol versions, a ''pong'' response is generated using a nonce included in the ping.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || nonce from ping<br />
|}<br />
<br />
<br />
=== reject===<br />
<br />
The ''reject'' message is sent when messages are rejected.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || message || var_str || type of message rejected<br />
|-<br />
| 1 || ccode || char || code relating to rejected message<br />
|-<br />
| 1+ || reason || var_str || text version of reason for rejection<br />
|-<br />
| 0+ || data || char || Optional extra data provided by some errors. Currently, all errors which provide this field fill it with the TXID or block header hash of the object being rejected, so the field is 32 bytes.<br />
|}<br />
<br />
CCodes<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0x01 || REJECT_MALFORMED|| <br />
|-<br />
| 0x10 || REJECT_INVALID ||<br />
|-<br />
| 0x11 || REJECT_OBSOLETE ||<br />
|-<br />
| 0x12 || REJECT_DUPLICATE ||<br />
|-<br />
| 0x40 || REJECT_NONSTANDARD ||<br />
|-<br />
| 0x41 || REJECT_DUST ||<br />
|-<br />
| 0x42 || REJECT_INSUFFICIENTFEE ||<br />
|-<br />
| 0x43 || REJECT_CHECKPOINT ||<br />
|}<br />
<br />
=== filterload, filteradd, filterclear, merkleblock ===<br />
<br />
These messages are related to Bloom filtering of connections and are defined in [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037].<br />
<br />
<br />
The <code>filterload</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || filter || uint8_t[] || The filter itself is simply a bit field of arbitrary byte-aligned size. The maximum size is 36,000 bytes.<br />
|-<br />
| 4 || nHashFuncs || uint32_t || The number of hash functions to use in this filter. The maximum value allowed in this field is 50.<br />
|-<br />
| 4 || nTweak || uint32_t || A random value to add to the seed value in the hash function used by the bloom filter.<br />
|-<br />
| 1 || nFlags || uint8_t || A set of flags that control how matched items are added to the filter.<br />
|}<br />
<br />
See below for a description of the Bloom filter algorithm and how to select nHashFuncs and filter size for a desired false positive rate.<br />
<br />
Upon receiving a <code>filterload</code> command, the remote peer will immediately restrict the broadcast transactions it announces (in inv packets) to transactions matching the filter, where the matching algorithm is specified below. The flags control the update behaviour of the matching algorithm.<br />
<br />
The <code>filteradd</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || data || uint8_t[] || The data element to add to the current filter.<br />
|}<br />
<br />
The data field must be smaller than or equal to 520 bytes in size (the maximum size of any potentially matched object).<br />
<br />
The given data element will be added to the Bloom filter. A filter must have been previously provided using <code>filterload</code>. This command is useful if a new key or script is added to a clients wallet whilst it has connections to the network open, it avoids the need to re-calculate and send an entirely new filter to every peer (though doing so is usually advisable to maintain anonymity).<br />
<br />
The <code>filterclear</code> command has no arguments at all.<br />
<br />
After a filter has been set, nodes don't merely stop announcing non-matching transactions, they can also serve filtered blocks. A filtered block is defined by the <code>merkleblock</code> message and is defined like this:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information, based upon the software version creating this block (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Limited to 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 4 || total_transactions || uint32_t || Number of transactions in the block (including unmatched ones)<br />
|-<br />
| ? || hashes || uint256[] || hashes in depth-first order (including standard varint size prefix)<br />
|-<br />
| ? || flags || byte[] || flag bits, packed per 8 in a byte, least significant bit first (including standard varint size prefix)<br />
|}<br />
<br />
=== alert ===<br />
<br />
An '''alert''' is sent between nodes to send a general notification message throughout the network. If the alert can be confirmed with the signature as having come from the core development group of the Bitcoin software, the message is suggested to be displayed for end-users. Attempts to perform transactions, particularly automated transactions through the client, are suggested to be halted. The text in the Message string should be relayed to log files and any user interfaces.<br />
<br />
Alert format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || payload || uchar[] || Serialized alert payload<br />
|-<br />
| ? || signature || uchar[] || An ECDSA signature of the message<br />
|}<br />
<br />
The developers of Satoshi's client use this public key for signing alerts:<br />
04fc9702847840aaf195de8442ebecedf5b095cdbb9bc716bda9110971b28a49e0ead8564ff0db22209e0374782c093bb899692d524e9d6a6956e7c5ecbcd68284<br />
(hash) 1AGRxqDa5WjUKBwHB9XYEjmkv1ucoUUy1s<br />
<br />
The payload is serialized into a uchar[] to ensure that versions using incompatible alert formats can still relay alerts among one another. The current alert payload format is:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || Version || int32_t || Alert format version<br />
|-<br />
| 8 || RelayUntil || int64_t || The timestamp beyond which nodes should stop relaying this alert<br />
|-<br />
| 8 || Expiration || int64_t || The timestamp beyond which this alert is no longer in effect and should be ignored<br />
|-<br />
| 4 || ID || int32_t || A unique ID number for this alert<br />
|-<br />
| 4 || Cancel || int32_t || All alerts with an ID number less than or equal to this number should be cancelled: deleted and not accepted in the future<br />
|-<br />
| ? || setCancel || set<int32_t> || All alert IDs contained in this set should be cancelled as above<br />
|-<br />
| 4 || MinVer || int32_t || This alert only applies to versions greater than or equal to this version. Other versions should still relay it.<br />
|-<br />
| 4 || MaxVer || int32_t || This alert only applies to versions less than or equal to this version. Other versions should still relay it.<br />
|-<br />
| ? || setSubVer || set<string> || If this set contains any elements, then only nodes that have their subVer contained in this set are affected by the alert. Other versions should still relay it.<br />
|-<br />
| 4 || Priority || int32_t || Relative priority compared to other alerts<br />
|-<br />
| ? || Comment || string || A comment on the alert that is not displayed<br />
|-<br />
| ? || StatusBar || string || The alert message that is displayed to the user<br />
|-<br />
| ? || Reserved || string || Reserved<br />
|}<br />
<br />
Note: '''set<''type''>''' in the table above is a [[#Variable length integer | variable length integer]] followed by the number of fields of the given ''type'' (either int32_t or [[#Variable length string | variable length string]])<br />
<br />
Sample alert (no message header):<br />
73010000003766404f00000000b305434f00000000f2030000f1030000001027000048ee0000<br />
0064000000004653656520626974636f696e2e6f72672f666562323020696620796f75206861<br />
76652074726f75626c6520636f6e6e656374696e672061667465722032302046656272756172<br />
79004730450221008389df45f0703f39ec8c1cc42c13810ffcae14995bb648340219e353b63b<br />
53eb022009ec65e1c1aaeec1fd334c6b684bde2b3f573060d5b70c3a46723326e4e8a4f1<br />
<br />
Version: 1<br />
RelayUntil: 1329620535<br />
Expiration: 1329792435<br />
ID: 1010<br />
Cancel: 1009<br />
setCancel: <empty><br />
MinVer: 10000<br />
MaxVer: 61000<br />
setSubVer: <empty><br />
Priority: 100<br />
Comment: <empty><br />
StatusBar: "See bitcoin.org/feb20 if you have trouble connecting after 20 February"<br />
Reserved: <empty><br />
<br />
=== sendheaders ===<br />
<br />
Request for Direct headers announcement. <br />
<br />
Upon receipt of this message, the node is be permitted, but not required, to announce new blocks by '''headers''' command (instead of '''inv''' command).<br />
<br />
This message is supported by the protocol version >= 70012 or Bitcoin Core version >= 0.12.0.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0130.mediawiki BIP 130] for more information.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
<br />
=== feefilter ===<br />
<br />
The payload is always 8 bytes long and it encodes 64 bit integer value (LSB / little endian) of '''feerate'''.<br />
The value represents a minimal fee and is expressed in satoshis per 1000 bytes.<br />
<br />
Upon receipt of a "feefilter" message, the node will be permitted, but not required, to filter transaction invs for transactions that fall below the feerate provided in the feefilter message interpreted as satoshis per kilobyte.<br />
<br />
The fee filter is additive with a bloom filter for transactions so if an SPV client were to load a bloom filter and send a feefilter message, transactions would only be relayed if they passed both filters.<br />
<br />
Inv's generated from a mempool message are also subject to a fee filter if it exists.<br />
<br />
Feature discovery is enabled by checking protocol version >= 70013<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0133.mediawiki BIP 133] for more information.<br />
<br />
=== sendcmpct ===<br />
<br />
# The sendcmpct message is defined as a message containing a 1-byte integer followed by a 8-byte integer where pchCommand == "sendcmpct".<br />
# The first integer SHALL be interpreted as a boolean (and MUST have a value of either 1 or 0)<br />
# The second integer SHALL be interpreted as a little-endian version number. Nodes sending a sendcmpct message MUST currently set this value to 1.<br />
# Upon receipt of a "sendcmpct" message with the first and second integers set to 1, the node SHOULD announce new blocks by sending a cmpctblock message.<br />
# Upon receipt of a "sendcmpct" message with the first integer set to 0, the node SHOULD NOT announce new blocks by sending a cmpctblock message, but SHOULD announce new blocks by sending invs or headers, as defined by BIP130.<br />
# Upon receipt of a "sendcmpct" message with the second integer set to something other than 1, nodes MUST treat the peer as if they had not received the message (as it indicates the peer will provide an unexpected encoding in <br />
# cmpctblock, and/or other, messages). This allows future versions to send duplicate sendcmpct messages with different versions as a part of a version handshake for future versions.<br />
# Nodes SHOULD check for a protocol version of >= 70014 before sending sendcmpct messages.<br />
# Nodes MUST NOT send a request for a MSG_CMPCT_BLOCK object to a peer before having received a sendcmpct message from that peer.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== cmpctblock ===<br />
<br />
# The cmpctblock message is defined as as a message containing a serialized HeaderAndShortIDs message and pchCommand == "cmpctblock".<br />
# Upon receipt of a cmpctblock message after sending a sendcmpct message, nodes SHOULD calculate the short transaction ID for each unconfirmed transaction they have available (ie in their mempool) and compare each to each short transaction ID in the cmpctblock message.<br />
# After finding already-available transactions, nodes which do not have all transactions available to reconstruct the full block SHOULD request the missing transactions using a getblocktxn message.<br />
# A node MUST NOT send a cmpctblock message unless they are able to respond to a getblocktxn message which requests every transaction in the block.<br />
# A node MUST NOT send a cmpctblock message without having validated that the header properly commits to each transaction in the block, and properly builds on top of the existing chain with a valid proof-of-work. A node MAY send a cmpctblock before validating that each transaction in the block validly spends existing UTXO set entries.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== getblocktxn ===<br />
<br />
# The getblocktxn message is defined as as a message containing a serialized BlockTransactionsRequest message and pchCommand == "getblocktxn".<br />
# Upon receipt of a properly-formatted getblocktxnmessage, nodes which recently provided the sender of such a message a cmpctblock for the block hash identified in this message MUST respond with an appropriate blocktxn message. Such a blocktxn message MUST contain exactly and only each transaction which is present in the appropriate block at the index specified in the getblocktxn indexes list, in the order requested.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== blocktxn ===<br />
<br />
# The blocktxn message is defined as as a message containing a serialized BlockTransactions message and pchCommand == "blocktxn".<br />
# Upon receipt of a properly-formatted requested blocktxn message, nodes SHOULD attempt to reconstruct the full block by:<br />
# Taking the prefilledtxn transactions from the original cmpctblock and placing them in the marked positions.<br />
# For each short transaction ID from the original cmpctblock, in order, find the corresponding transaction either from the blocktxn message or from other sources and place it in the first available position in the block.<br />
# Once the block has been reconstructed, it shall be processed as normal, keeping in mind that short transaction IDs are expected to occasionally collide, and that nodes MUST NOT be penalized for such collisions, wherever they # appear.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
== Scripting ==<br />
<br />
See [[script]].<br />
<br />
==See Also==<br />
<br />
* [[Network]]<br />
* [[Protocol rules]]<br />
* [[Hardfork Wishlist]]<br />
* [https://bitcoin.org/en/developer-documentation Developer Documentation on bitcoin.org]<br />
* Bitcoin dissectors for Wireshark: https://github.com/lbotsch/wireshark-bitcoin https://github.com/op-sig/bitcoin-wireshark-dissector<br />
<br />
==References==<br />
<references /><br />
<br />
[[zh-cn:协议说明]]<br />
[[Category:Technical]]<br />
[[Category:Developer]]<br />
<br />
{{Bitcoin Core documentation}}</div>Tonikthttps://en.bitcoin.it/w/index.php?title=Protocol_documentation&diff=61496Protocol documentation2016-08-25T12:47:00Z<p>Tonikt: Added Differential encoding</p>
<hr />
<div>This page ''describes'' the behavior of the [[Original Bitcoin client|reference client]]. The Bitcoin protocol is specified by the behavior of the reference client, not by this page. In particular, while this page is quite complete in describing the network protocol, it does not attempt to list all of the rules for block or transaction validity.<br />
<br />
Type names used in this documentation are from the C99 standard.<br />
<br />
For protocol used in mining, see [[getblocktemplate]].<br />
<br />
==Common standards==<br />
<br />
=== Hashes ===<br />
<br />
Usually, when a hash is computed within bitcoin, it is computed twice. Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-256] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when a shorter hash is desirable (for example when creating a bitcoin address).<br />
<br />
Example of double-SHA-256 encoding of string "hello":<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round of sha-256)<br />
9595c9df90075148eb06860365df33584b75bff782a510c6cd4883a419833d50 (second round of sha-256)<br />
<br />
For bitcoin addresses (RIPEMD-160) this would give:<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round is sha-256)<br />
b6a9c8c230722b7c748331a8b450f05566dc7d0f (with ripemd-160)<br />
<br />
=== Merkle Trees ===<br />
<br />
Merkle trees are binary trees of hashes. Merkle trees in bitcoin use a '''double''' SHA-256, the SHA-256 hash of the SHA-256 hash of something.<br />
<br />
If, when forming a row in the tree (other than the root of the tree), it would have an odd number of elements, the final double-hash is duplicated to ensure that the row has an even number of hashes.<br />
<br />
First form the bottom row of the tree with the ordered double-SHA-256 hashes of the byte streams of the transactions in the block.<br />
<br />
Then the row above it consists of half that number of hashes. Each entry is the double-SHA-256 of the 64-byte concatenation of the corresponding two hashes below it in the tree.<br />
<br />
This procedure repeats recursively until we reach a row consisting of just a single double-hash. This is the '''Merkle root''' of the tree.<br />
<br />
For example, imagine a block with three transactions ''a'', ''b'' and ''c''. The Merkle tree is: <br />
<br />
d1 = dhash(a)<br />
d2 = dhash(b)<br />
d3 = dhash(c)<br />
d4 = dhash(c) # a, b, c are 3. that's an odd number, so we take the c twice<br />
<br />
d5 = dhash(d1 concat d2)<br />
d6 = dhash(d3 concat d4)<br />
<br />
d7 = dhash(d5 concat d6)<br />
<br />
where<br />
<br />
dhash(a) = sha256(sha256(a))<br />
<br />
''d7'' is the Merkle root of the 3 transactions in this block.<br />
<br />
Note: Hashes in Merkle Tree displayed in the [[Block Explorer]] are of little-endian notation. For some implementations and [http://www.fileformat.info/tool/hash.htm calculations], the bits need to be reversed before they are hashed, and again after the hashing operation.<br />
<br />
=== Signatures ===<br />
<br />
Bitcoin uses [http://en.wikipedia.org/wiki/Elliptic_curve_cryptography Elliptic Curve] [http://en.wikipedia.org/wiki/Digital_Signature_Algorithm Digital Signature Algorithm] ([http://en.wikipedia.org/wiki/Elliptic_Curve_DSA ECDSA]) to sign transactions. <br />
<br />
For [[ECDSA]] the secp256k1 curve from http://www.secg.org/collateral/sec2_final.pdf is used.<br />
<br />
Public keys (in scripts) are given as 04 <x> <y> where ''x'' and ''y'' are 32 byte big-endian integers representing the coordinates of a point on the curve or in compressed form given as <sign> <x> where <sign> is 0x02 if ''y'' is even and 0x03 if ''y'' is odd.<br />
<br />
Signatures use [http://en.wikipedia.org/wiki/Distinguished_Encoding_Rules DER encoding] to pack the ''r'' and ''s'' components into a single byte stream (this is also what OpenSSL produces by default).<br />
<br />
=== Transaction Verification ===<br />
Transactions are cryptographically signed records that reassign ownership of Bitcoins to new addresses. Transactions have ''inputs'' - records which reference the funds from other previous transactions - and ''outputs'' - records which determine the new owner of the transferred Bitcoins, and which will be referenced as inputs in future transactions as those funds are respent.<br />
<br />
Each ''input'' must have a cryptographic digital signature that unlocks the funds from the prior transaction. Only the person possessing the appropriate [[private key]] is able to create a satisfactory signature; this in effect ensures that funds can only be spent by their owners.<br />
<br />
Each ''output'' determines which Bitcoin address (or other criteria, see [[Script]]) is the recipient of the funds.<br />
<br />
In a transaction, the sum of all inputs must be equal to or greater than the sum of all outputs. If the inputs exceed the outputs, the difference is considered a [[transaction fee]], and is redeemable by whoever first includes the transaction into the block chain.<br />
<br />
A special kind of transaction, called a [[coinbase transaction]], has no inputs. It is created by [[miners]], and there is one coinbase transaction per block. Because each block comes with a reward of newly created Bitcoins (e.g. 50 BTC for the first 210,000 blocks), the first transaction of a block is, with few exceptions, the transaction that grants those coins to their recipient (the miner). In addition to the newly created Bitcoins, the coinbase transaction is also used for assigning the recipient of any transaction fees that were paid within the other transactions being included in the same block. The coinbase transaction can assign the entire reward to a single Bitcoin address, or split it in portions among multiple addresses, just like any other transaction. Coinbase transactions always contain outputs totalling the sum of the block reward plus all transaction fees collected from the other transactions in the same block.<br />
<br />
The [[coinbase transaction]] in block zero cannot be spent. This is due to a quirk of the reference client implementation that would open the potential for a block chain fork if some nodes accepted the spend and others did not<ref>[http://bitcointalk.org/index.php?topic=119645.msg1288552#msg1288552 Block 0 Network Fork]</ref>.<br />
<br />
Most Bitcoin outputs encumber the newly transferred coins with a single ECDSA private key. The actual record saved with inputs and outputs isn't necessarily a key, but a ''script''. Bitcoin uses an interpreted scripting system to determine whether an output's criteria have been satisfied, with which more complex operations are possible, such as outputs that require two ECDSA signatures, or two-of-three-signature schemes. An output that references a single Bitcoin address is a ''typical'' output; an output actually contains this information in the form of a script that requires a single ECDSA signature (see [[OP_CHECKSIG]]). The output script specifies what must be provided to unlock the funds later, and when the time comes in the future to spend the transaction in another input, that input must provide all of the thing(s) that satisfy the requirements defined by the original output script.<br />
<br />
=== Addresses ===<br />
<br />
A bitcoin address is in fact the hash of a ECDSA public key, computed this way:<br />
<br />
Version = 1 byte of 0 (zero); on the test network, this is 1 byte of 111<br />
Key hash = Version concatenated with RIPEMD-160(SHA-256(public key))<br />
Checksum = 1st 4 bytes of SHA-256(SHA-256(Key hash))<br />
Bitcoin Address = Base58Encode(Key hash concatenated with Checksum)<br />
<br />
The Base58 encoding used is home made, and has some differences. Especially, leading zeroes are kept as single zeroes when conversion happens.<br />
<br />
== Common structures ==<br />
<br />
Almost all integers are encoded in little endian. Only IP or port number are encoded big endian.<br />
<br />
=== Message structure ===<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown<br />
|-<br />
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| 4 || length || uint32_t || Length of payload in number of bytes<br />
|-<br />
| 4 || checksum || uint32_t || First 4 bytes of sha256(sha256(payload))<br />
|-<br />
| ? || payload || uchar[] || The actual data<br />
|}<br />
<br />
<br />
Known magic values:<br />
<br />
{|class="wikitable"<br />
! Network !! Magic value !! Sent over wire as<br />
|-<br />
| main || 0xD9B4BEF9 || F9 BE B4 D9<br />
|-<br />
| testnet || 0xDAB5BFFA || FA BF B5 DA<br />
|-<br />
| testnet3 || 0x0709110B || 0B 11 09 07<br />
|-<br />
| namecoin || 0xFEB4BEF9 || F9 BE B4 FE<br />
|}<br />
<br />
=== Variable length integer ===<br />
<br />
Integer can be encoded depending on the represented value to save space.<br />
Variable length integers always precede an array/vector of a type of data that may vary in length.<br />
Longer numbers are encoded in little endian.<br />
<br />
{|class="wikitable"<br />
! Value !! Storage length !! Format<br />
|-<br />
| < 0xFD || 1 || uint8_t<br />
|-<br />
| <= 0xFFFF || 3 || 0xFD followed by the length as uint16_t<br />
|-<br />
| <= 0xFFFF FFFF || 5 || 0xFE followed by the length as uint32_t<br />
|-<br />
| - || 9 || 0xFF followed by the length as uint64_t<br />
|}<br />
<br />
If you're reading the Satoshi client code (BitcoinQT) it refers to this encoding as a "CompactSize". Modern BitcoinQT also has the CVarInt class which implements an even more compact integer for the purpose of local storage (which is incompatible with "CompactSize" described here). CVarInt is not a part of the protocol.<br />
<br />
=== Variable length string ===<br />
<br />
Variable length string can be stored using a variable length integer followed by the string itself.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the string<br />
|-<br />
| ? || string || char[] || The string itself (can be empty)<br />
|}<br />
<br />
=== Network address ===<br />
<br />
When a network address is needed somewhere, this structure is used. Network addresses are not prefixed with a timestamp in the version message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || time || uint32 || the Time (version >= 31402). '''Not present in version message.'''<br />
|-<br />
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]<br />
|-<br />
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The original client only supported IPv4 and only read the last 4 bytes to get the IPv4 address. However, the IPv4 address is written into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]<br />
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).<br />
|-<br />
| 2 || port || uint16_t || port number, network byte order<br />
|}<br />
<br />
Hexdump example of Network address structure<br />
<br />
<pre><br />
0000 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0010 00 00 FF FF 0A 00 00 01 20 8D ........ .<br />
<br />
Network address:<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK: see services listed under version command)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv6: ::ffff:a00:1 or IPv4: 10.0.0.1<br />
20 8D - Port 8333<br />
</pre><br />
<br />
=== Inventory Vectors ===<br />
<br />
Inventory vectors are used for notifying other nodes about objects they have or data which is being requested.<br />
<br />
Inventory vectors consist of the following data format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || type || uint32_t || Identifies the object type linked to this inventory<br />
|-<br />
| 32 || hash || char[32] || Hash of the object<br />
|}<br />
<br />
<br />
The object type is currently defined as one of the following possibilities:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0 || ERROR || Any data of with this number may be ignored<br />
|-<br />
| 1 || MSG_TX || Hash is related to a transaction<br />
|-<br />
| 2 || MSG_BLOCK || Hash is related to a data block<br />
|-<br />
| 3 || MSG_FILTERED_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a merkleblock message rather than a block message; this only works if a bloom filter has been set.<br />
|-<br />
| 4 || MSG_CMPCT_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a cmpctblock message. See BIP 152 for more info.<br />
|}<br />
<br />
Other Data Type values are considered reserved for future implementations.<br />
<br />
=== Block Headers ===<br />
<br />
Block headers are sent in a headers packet in response to a getheaders message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Will overflow in 2106<ref>https://en.wikipedia.org/wiki/Unix_time#Notable_events_in_Unix_time</ref>)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 1 || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries, this value is always 0<br />
|}<br />
<br />
cf. [[Block hashing algorithm]]<br />
<br />
=== Differential encoding === <br />
Several uses of CompactSize below are "differentially encoded". For these, instead of using raw indexes, the number encoded is the difference between the current index and the previous index, minus one. For example, a first index of 0 implies a real index of 0, a second index of 0 thereafter refers to a real index of 1, etc.<br />
<br />
=== PrefilledTransaction ===<br />
<br />
A PrefilledTransaction structure is used in HeaderAndShortIDs to provide a list of a few transactions explicitly.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| index || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1, 3 bytes || Compact Size, differentially encoded since the last PrefilledTransaction in a list || The index into the block at which this transaction is<br />
|-<br />
| tx || Transaction || variable || As encoded in [[Protocol_documentation#tx|tx messages]] || The transaction which is in the block at index index.<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== HeaderAndShortIDs ===<br />
<br />
A HeaderAndShortIDs structure is used to relay a block header, the short transactions IDs used for matching already-available transactions, and a select few transactions which we expect a peer may be missing.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| header || Block header || 80 bytes || First 80 bytes of the block as defined by the encoding used by "block" messages || The header of the block being provided<br />
|-<br />
| nonce || uint64_t || 8 bytes || Little Endian || A nonce for use in short transaction ID calculations<br />
|-<br />
| shortids_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of short transaction IDs in shortids (ie block tx count - prefilledtxn_length)<br />
|-<br />
| shortids || List of 6-byte integers || 6*shortids_length bytes || Little Endian || The short transaction IDs calculated from the transactions which were not provided explicitly in prefilledtxn<br />
|-<br />
| prefilledtxn_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of prefilled transactions in prefilledtxn (ie block tx count - shortids_length)<br />
|-<br />
| prefilledtxn || List of PrefilledTransactions || variable size*prefilledtxn_length || As defined by PrefilledTransaction definition, above || Used to provide the coinbase transaction and a select few which we expect a peer may be missing<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== BlockTransactionsRequest ===<br />
<br />
A BlockTransactionsRequest structure is used to list transaction indexes in a block being requested.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| blockhash || Binary blob || 32 bytes || The output from a double-SHA256 of the block header, as used elsewhere || The blockhash of the block which the transactions being requested are in<br />
|-<br />
| indexes_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of transactions being requested<br />
|-<br />
| indexes || List of [[Protocol_documentation#Variable_length_integer|CompactSizes]] || 1 or 3 bytes*indexes_length || Differentially encoded || The indexes of the transactions being requested in the block<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== BlockTransactions ===<br />
<br />
A BlockTransactions structure is used to provide some of the transactions in a block, as requested.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| blockhash || Binary blob || 32 bytes || The output from a double-SHA256 of the block header, as used elsewhere || The blockhash of the block which the transactions being provided are in<br />
|-<br />
| transactions_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of transactions provided<br />
|-<br />
| transactions || List of Transactions || variable || As encoded in "tx" messages || The transactions provided<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== Short transaction ID ===<br />
<br />
Short transaction IDs are used to represent a transaction without sending a full 256-bit hash. They are calculated by:<br />
<br />
# single-SHA256 hashing the block header with the nonce appended (in little-endian)<br />
# Running SipHash-2-4 with the input being the transaction ID and the keys (k0/k1) set to the first two little-endian 64-bit integers from the above hash, respectively.<br />
# Dropping the 2 most significant bytes from the SipHash output to make it 6 bytes.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
== Message types ==<br />
<br />
=== version ===<br />
<br />
When a node creates an outgoing connection, it will immediately [[Version Handshake|advertise]] its version. The remote node will respond with its version. No further communication is possible until both peers have exchanged their version.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Identifies protocol version being used by the node<br />
|-<br />
| 8 || services || uint64_t || bitfield of features to be enabled for this connection<br />
|-<br />
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds<br />
|-<br />
| 26 || addr_recv || [[#Network address|net_addr]] || The network address of the node receiving this message<br />
|-<br />
|colspan="4"| Fields below require version ≥ 106<br />
|-<br />
| 26 || addr_from || [[#Network address|net_addr]] || The network address of the node emitting this message<br />
|-<br />
| 8 || nonce || uint64_t || Node random nonce, randomly generated every time a version packet is sent. This nonce is used to detect connections to self.<br />
|-<br />
| ? || user_agent || [[#Variable length string|var_str]] || [https://github.com/bitcoin/bips/blob/master/bip-0014.mediawiki User Agent] (0x00 if string is 0 bytes long)<br />
|-<br />
| 4 || start_height || int32_t || The last block received by the emitting node<br />
|-<br />
|colspan="4"| Fields below require version ≥ 70001<br />
|-<br />
| 1 || relay || bool || Whether the remote peer should announce relayed transactions or not, see [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037]<br />
|}<br />
<br />
A "verack" packet shall be sent if the version packet was accepted.<br />
<br />
The following services are currently assigned:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 1 || NODE_NETWORK || This node can be asked for full blocks instead of just headers.<br />
|}<br />
<br />
Hexdump example of version message (OBSOLETE EXAMPLE: This example lacks a checksum and user-agent):<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....<br />
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........<br />
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............<br />
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................<br />
0040 20 8D 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,<br />
0060 3A B4 57 13 00 55 81 01 00 :.W..U...<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
55 00 00 00 - Payload is 85 bytes long<br />
- No checksum in version message until 20 February 2012. See https://bitcointalk.org/index.php?topic=55852.0<br />
Version message:<br />
9C 7C 00 00 - 31900 (version 0.3.19)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
E6 15 10 4D 00 00 00 00 - Mon Dec 20 21:50:14 EST 2010<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 20 8D - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D - Sender address info - see Network Address<br />
DD 9D 20 2C 3A B4 57 13 - Node random unique ID<br />
00 - "" sub-version string (string is 0 bytes long)<br />
55 81 01 00 - Last block sending node has is block #98645<br />
</pre><br />
<br />
And here's a modern (60002) protocol version client advertising itself to a local peer...<br />
<br />
Newer protocol includes the checksum now, this is from a mainline (satoshi) client during <br />
an outgoing connection to another local client, notice that it does not fill out the <br />
address information at all when the source or destination is "unroutable".<br />
<br />
<pre><br />
<br />
0000 f9 be b4 d9 76 65 72 73 69 6f 6e 00 00 00 00 00 ....version.....<br />
0010 64 00 00 00 35 8d 49 32 62 ea 00 00 01 00 00 00 d...5.I2b.......<br />
0020 00 00 00 00 11 b2 d0 50 00 00 00 00 01 00 00 00 .......P........<br />
0030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ff ff ................<br />
0040 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 00 00 00 00 ff ff 00 00 00 00 00 00 ................<br />
0060 3b 2e b3 5d 8c e6 17 65 0f 2f 53 61 74 6f 73 68 ;..]...e./Satosh<br />
0070 69 3a 30 2e 37 2e 32 2f c0 3e 03 00 i:0.7.2/.>..<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
64 00 00 00 - Payload is 100 bytes long<br />
3B 64 8D 5A - payload checksum<br />
<br />
Version message:<br />
62 EA 00 00 - 60002 (protocol version 60002)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
11 B2 D0 50 00 00 00 00 - Tue Dec 18 10:12:33 PST 2012<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Sender address info - see Network Address<br />
3B 2E B3 5D 8C E6 17 65 - Node ID<br />
0F 2F 53 61 74 6F 73 68 69 3A 30 2E 37 2E 32 2F - "/Satoshi:0.7.2/" sub-version string (string is 15 bytes long)<br />
C0 3E 03 00 - Last block sending node has is block #212672<br />
</pre><br />
<br />
=== verack ===<br />
<br />
The ''verack'' message is sent in reply to ''[[#version|version]]''. This message consists of only a [[#Message structure|message header]] with the command string "verack".<br />
<br />
Hexdump of the verack message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......<br />
0010 00 00 00 00 5D F6 E0 E2 ........<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 61 63 6B 00 00 00 00 00 00 - "verack" command<br />
00 00 00 00 - Payload is 0 bytes long<br />
5D F6 E0 E2 - Checksum<br />
</pre><br />
<br />
=== addr ===<br />
<br />
Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours<br />
<br />
Payload:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of address entries (max: 1000)<br />
|-<br />
| 30x? || addr_list || (uint32_t + [[#Network address|net_addr]])[] || Address of other nodes on the network. version < 209 will only read the first one. The uint32_t is a timestamp (see note below).<br />
|}<br />
<br />
'''Note''': Starting version 31402, addresses are prefixed with a timestamp. If no timestamp is present, the addresses should not be relayed to other peers, unless it is indeed confirmed they are up.<br />
<br />
Hexdump example of ''addr'' message:<br />
<pre><br />
0000 F9 BE B4 D9 61 64 64 72 00 00 00 00 00 00 00 00 ....addr........<br />
0010 1F 00 00 00 ED 52 39 9B 01 E2 15 10 4D 01 00 00 .....R9.....M...<br />
0020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF ................<br />
0030 FF 0A 00 00 01 20 8D ..... .<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
61 64 64 72 00 00 00 00 00 00 00 00 - "addr"<br />
1F 00 00 00 - payload is 31 bytes long<br />
ED 52 39 9B - checksum of payload<br />
<br />
Payload:<br />
01 - 1 address in this message<br />
<br />
Address:<br />
E2 15 10 4D - Mon Dec 20 21:50:10 EST 2010 (only when version is >= 31402)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK service - see version message)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv4: 10.0.0.1, IPv6: ::ffff:10.0.0.1 (IPv4-mapped IPv6 address)<br />
20 8D - port 8333<br />
</pre><br />
<br />
=== inv ===<br />
<br />
Allows a node to advertise its knowledge of one or more objects. It can be received unsolicited, or in reply to ''getblocks''.<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getdata ===<br />
<br />
getdata is used in response to inv, to retrieve the content of a specific object, and is usually sent after receiving an ''inv'' packet, after filtering known elements. It can be used to retrieve transactions, but only if they are in the memory pool or relay set - arbitrary access to transactions in the chain is not allowed to avoid having clients start to depend on nodes having full transaction indexes (which modern nodes do not).<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== notfound ===<br />
<br />
notfound is a response to a getdata, sent if any requested data items could not be relayed, for example, because the requested transaction was not in the memory pool or relay set.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getblocks ===<br />
<br />
Return an ''inv'' packet containing the list of blocks starting right after the last known hash in the block locator object, up to hash_stop or 500 blocks, whichever comes first. <br />
<br />
The locator hashes are processed by a node in the order as they appear in the message. If a block hash is found in the node's main chain, the list of its children is returned back via the ''inv'' message and the remaining locators are ignored, no matter if the requested limit was reached, or not.<br />
<br />
To receive the next blocks hashes, one needs to issue getblocks again with a new block locator object. Keep in mind that some clients may provide blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block; set to zero to get as many blocks as possible (500)<br />
|}<br />
<br />
To create the block locator hashes, keep pushing hashes until you go back to the genesis block. After pushing 10 hashes back, the step backwards doubles every loop:<br />
<br />
<pre><br />
// From libbitcoin which is under AGPL<br />
std::vector<size_t> block_locator_indexes(size_t top_height)<br />
{<br />
std::vector<size_t> indexes;<br />
<br />
// Modify the step in the iteration.<br />
int64_t step = 1;<br />
<br />
// Start at the top of the chain and work backwards.<br />
for (auto index = (int64_t)top_height; index > 0; index -= step)<br />
{<br />
// Push top 10 indexes first, then back off exponentially.<br />
if (indexes.size() >= 10)<br />
step *= 2;<br />
<br />
indexes.push_back((size_t)index);<br />
}<br />
<br />
// Push the genesis block index.<br />
indexes.push_back(0);<br />
return indexes;<br />
}<br />
</pre><br />
<br />
Note that it is allowed to send in fewer known hashes down to a minimum of just one hash. However, the purpose of the block locator object is to detect a wrong branch in the caller's main chain. If the peer detects that you are off the main chain, it will send in block hashes which are earlier than your last known block. So if you just send in your last known hash and it is off the main chain, the peer starts over at block #1.<br />
<br />
=== getheaders ===<br />
<br />
Return a ''headers'' packet containing the headers of blocks starting right after the last known hash in the block locator object, up to hash_stop or 2000 blocks, whichever comes first. To receive the next block headers, one needs to issue getheaders again with a new block locator object. The ''getheaders'' command is used by thin clients to quickly download the block chain where the contents of the transactions would be irrelevant (because they are not ours). Keep in mind that some clients may provide headers of blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block header; set to zero to get as many blocks as possible (2000)<br />
|}<br />
<br />
For the block locator object in this packet, the same rules apply as for the [[Protocol_documentation#getblocks|getblocks]] packet.<br />
<br />
=== tx ===<br />
<br />
''tx'' describes a bitcoin transaction, in reply to ''[[#getdata|getdata]]''<br />
<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Transaction data format version (note, this is signed)<br />
|-<br />
| 1+ || tx_in count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction inputs<br />
|-<br />
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins<br />
|-<br />
| 1+ || tx_out count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction outputs<br />
|-<br />
| 9+ || tx_out || tx_out[] || A list of 1 or more transaction outputs or destinations for coins<br />
|-<br />
| 4 || lock_time || uint32_t || The block number or timestamp at which this transaction is locked:<br />
{|class="wikitable"<br />
! Value !! Description<br />
|-<br />
| 0 || Not locked<br />
|-<br />
| < 500000000 || Block number at which this transaction is locked<br />
|-<br />
| >= 500000000 || UNIX timestamp at which this transaction is locked<br />
|}<br />
If all TxIn inputs have final (0xffffffff) sequence numbers then lock_time is irrelevant. Otherwise, the transaction may not be added to a block until after lock_time (see [[NLockTime]]).<br />
<br />
|}<br />
<br />
TxIn consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 36 || previous_output || outpoint || The previous output transaction reference, as an OutPoint structure<br />
|-<br />
| 1+ || script length || [[Protocol_documentation#Variable_length_integer|var_int]] || The length of the signature script<br />
|-<br />
| ? || signature script || uchar[] || Computational Script for confirming transaction authorization<br />
|-<br />
| 4 || [http://bitcoin.stackexchange.com/q/2025/323 sequence] || uint32_t || Transaction version as defined by the sender. Intended for "replacement" of transactions when information is updated before inclusion into a block.<br />
|}<br />
<br />
The OutPoint structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 32 || hash || char[32] || The hash of the referenced transaction.<br />
|-<br />
| 4 || index || uint32_t || The index of the specific output in the transaction. The first output is 0, etc.<br />
|}<br />
<br />
The Script structure consists of a series of pieces of information and operations related to the value of the transaction.<br />
<br />
(Structure to be expanded in the future… see script.h and script.cpp and [[Script]] for more information)<br />
<br />
The TxOut structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || value || int64_t || Transaction Value<br />
|-<br />
| 1+ || pk_script length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the pk_script<br />
|-<br />
| ? || pk_script || uchar[] || Usually contains the public key as a Bitcoin script setting up conditions to claim this output.<br />
|}<br />
<br />
Example ''tx'' message:<br />
<pre><br />
000000 F9 BE B4 D9 74 78 00 00 00 00 00 00 00 00 00 00 ....tx..........<br />
000010 02 01 00 00 E2 93 CD BE 01 00 00 00 01 6D BD DB .............m..<br />
000020 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D 12 66 E9 .[...Q........f.<br />
000030 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29 00 00 00 .;P......j.6)...<br />
000040 00 8B 48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 ..H0E.!..X..r...<br />
000050 C7 36 7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A .6zz%;..R#...h.:<br />
000060 59 23 3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 Y#?E.W... Y.....<br />
000070 0E 41 83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D .A.z.X.z...XN...<br />
000080 35 BD 96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF 5...6..;...A....<br />
000090 C9 7E F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 .~.6.m...@..!...<br />
0000A0 2A CD 2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC *.+..].}Y... ...<br />
0000B0 4E 02 53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F N.S..=7.o...Q...<br />
0000C0 14 04 2F 46 61 4A 4C 70 C0 F1 4B EF F5 FF FF FF ../FaJLp..K.....<br />
0000D0 FF 02 40 4B 4C 00 00 00 00 00 19 76 A9 14 1A A0 ..@KL......v....<br />
0000E0 CD 1C BE A6 E7 45 8A 7A BA D5 12 A9 D9 EA 1A FB .....E.z........<br />
0000F0 22 5E 88 AC 80 FA E9 C7 00 00 00 00 19 76 A9 14 "^...........v..<br />
000100 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E FD A0 B7 ..[.Cj.....H^...<br />
000110 8B 4E CC 52 88 AC 00 00 00 00 .N.R......<br />
<br />
<br />
Message header:<br />
F9 BE B4 D9 - main network magic bytes<br />
74 78 00 00 00 00 00 00 00 00 00 00 - "tx" command<br />
02 01 00 00 - payload is 258 bytes long<br />
E2 93 CD BE - checksum of payload<br />
<br />
Transaction:<br />
01 00 00 00 - version<br />
<br />
Inputs:<br />
01 - number of transaction inputs<br />
<br />
Input 1:<br />
6D BD DB 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D - previous output (outpoint)<br />
12 66 E9 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29<br />
00 00 00 00<br />
<br />
8B - script is 139 bytes long<br />
<br />
48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 C7 36 - signature script (scriptSig)<br />
7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A 59 23<br />
3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 0E 41<br />
83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D 35 BD<br />
96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF C9 7E<br />
F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 2A CD<br />
2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC 4E 02<br />
53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F 14 04<br />
2F 46 61 4A 4C 70 C0 F1 4B EF F5<br />
<br />
FF FF FF FF - sequence<br />
<br />
Outputs:<br />
02 - 2 Output Transactions<br />
<br />
Output 1:<br />
40 4B 4C 00 00 00 00 00 - 0.05 BTC (5000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 1A A0 CD 1C BE A6 E7 45 8A 7A BA D5 12 - pk_script<br />
A9 D9 EA 1A FB 22 5E 88 AC<br />
<br />
Output 2:<br />
80 FA E9 C7 00 00 00 00 - 33.54 BTC (3354000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E - pk_script<br />
FD A0 B7 8B 4E CC 52 88 AC<br />
<br />
Locktime:<br />
00 00 00 00 - lock time<br />
</pre><br />
<br />
=== block ===<br />
<br />
The '''block''' message is sent in response to a getdata message which requests transaction information from a block hash.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A Unix timestamp recording when this block was created (Currently limited to dates before the year 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated [[Difficulty|difficulty target]] being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| ? || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries<br />
|-<br />
| ? || txns || tx[] || Block transactions, in format of "tx" command<br />
|}<br />
<br />
The SHA256 hash that identifies each block (and which must have a run of 0 bits) is calculated from the first 6 fields of this structure (version, prev_block, merkle_root, timestamp, bits, nonce, and standard SHA256 padding, making two 64-byte chunks in all) and ''not'' from the complete block. To calculate the hash, only two chunks need to be processed by the SHA256 algorithm. Since the ''nonce'' field is in the second chunk, the first chunk stays constant during mining and therefore only the second chunk needs to be processed. However, a Bitcoin hash is the hash of the hash, so two SHA256 rounds are needed for each mining iteration.<br />
See [[Block hashing algorithm]] for details and an example.<br />
<br />
=== headers ===<br />
<br />
The ''headers'' packet returns block headers in response to a ''getheaders'' packet. <br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of block headers<br />
|-<br />
| 81x? || headers || [[Protocol_documentation#Block_Headers|block_header]][] || [[Protocol_documentation#Block_Headers|Block headers]]<br />
|}<br />
<br />
Note that the block headers in this packet include a transaction count (a var_int, so there can be more than 81 bytes per header) as opposed to the block headers that are hashed by miners.<br />
<br />
=== getaddr ===<br />
<br />
The getaddr message sends a request to a node asking for information about known active peers to help with finding potential nodes in the network. The response to receiving this message is to transmit one or more addr messages with one or more peers from a database of known active peers. The typical presumption is that a node is likely to be active if it has been sending a message within the last three hours.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
=== mempool ===<br />
<br />
The mempool message sends a request to a node asking for information about transactions it has verified but which have not yet confirmed. The response to receiving this message is an inv message containing the transaction hashes for all the transactions in the node's mempool.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
It is specified in [https://github.com/bitcoin/bips/blob/master/bip-0035.mediawiki BIP 35]. Since [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 37], if a [[Protocol_documentation#filterload.2C_filteradd.2C_filterclear.2C_merkleblock|bloom filter]] is loaded, only transactions matching the filter are replied.<br />
<br />
=== checkorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== submitorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== reply ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== ping ===<br />
<br />
The ''ping'' message is sent primarily to confirm that the TCP/IP connection is still valid. An error in transmission is presumed to be a closed connection and the address is removed as a current peer.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || random nonce<br />
|}<br />
<br />
=== pong ===<br />
<br />
The ''pong'' message is sent in response to a ''ping'' message. In modern protocol versions, a ''pong'' response is generated using a nonce included in the ping.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || nonce from ping<br />
|}<br />
<br />
<br />
=== reject===<br />
<br />
The ''reject'' message is sent when messages are rejected.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || message || var_str || type of message rejected<br />
|-<br />
| 1 || ccode || char || code relating to rejected message<br />
|-<br />
| 1+ || reason || var_str || text version of reason for rejection<br />
|-<br />
| 0+ || data || char || Optional extra data provided by some errors. Currently, all errors which provide this field fill it with the TXID or block header hash of the object being rejected, so the field is 32 bytes.<br />
|}<br />
<br />
CCodes<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0x01 || REJECT_MALFORMED|| <br />
|-<br />
| 0x10 || REJECT_INVALID ||<br />
|-<br />
| 0x11 || REJECT_OBSOLETE ||<br />
|-<br />
| 0x12 || REJECT_DUPLICATE ||<br />
|-<br />
| 0x40 || REJECT_NONSTANDARD ||<br />
|-<br />
| 0x41 || REJECT_DUST ||<br />
|-<br />
| 0x42 || REJECT_INSUFFICIENTFEE ||<br />
|-<br />
| 0x43 || REJECT_CHECKPOINT ||<br />
|}<br />
<br />
=== filterload, filteradd, filterclear, merkleblock ===<br />
<br />
These messages are related to Bloom filtering of connections and are defined in [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037].<br />
<br />
<br />
The <code>filterload</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || filter || uint8_t[] || The filter itself is simply a bit field of arbitrary byte-aligned size. The maximum size is 36,000 bytes.<br />
|-<br />
| 4 || nHashFuncs || uint32_t || The number of hash functions to use in this filter. The maximum value allowed in this field is 50.<br />
|-<br />
| 4 || nTweak || uint32_t || A random value to add to the seed value in the hash function used by the bloom filter.<br />
|-<br />
| 1 || nFlags || uint8_t || A set of flags that control how matched items are added to the filter.<br />
|}<br />
<br />
See below for a description of the Bloom filter algorithm and how to select nHashFuncs and filter size for a desired false positive rate.<br />
<br />
Upon receiving a <code>filterload</code> command, the remote peer will immediately restrict the broadcast transactions it announces (in inv packets) to transactions matching the filter, where the matching algorithm is specified below. The flags control the update behaviour of the matching algorithm.<br />
<br />
The <code>filteradd</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || data || uint8_t[] || The data element to add to the current filter.<br />
|}<br />
<br />
The data field must be smaller than or equal to 520 bytes in size (the maximum size of any potentially matched object).<br />
<br />
The given data element will be added to the Bloom filter. A filter must have been previously provided using <code>filterload</code>. This command is useful if a new key or script is added to a clients wallet whilst it has connections to the network open, it avoids the need to re-calculate and send an entirely new filter to every peer (though doing so is usually advisable to maintain anonymity).<br />
<br />
The <code>filterclear</code> command has no arguments at all.<br />
<br />
After a filter has been set, nodes don't merely stop announcing non-matching transactions, they can also serve filtered blocks. A filtered block is defined by the <code>merkleblock</code> message and is defined like this:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information, based upon the software version creating this block (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Limited to 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 4 || total_transactions || uint32_t || Number of transactions in the block (including unmatched ones)<br />
|-<br />
| ? || hashes || uint256[] || hashes in depth-first order (including standard varint size prefix)<br />
|-<br />
| ? || flags || byte[] || flag bits, packed per 8 in a byte, least significant bit first (including standard varint size prefix)<br />
|}<br />
<br />
=== alert ===<br />
<br />
An '''alert''' is sent between nodes to send a general notification message throughout the network. If the alert can be confirmed with the signature as having come from the core development group of the Bitcoin software, the message is suggested to be displayed for end-users. Attempts to perform transactions, particularly automated transactions through the client, are suggested to be halted. The text in the Message string should be relayed to log files and any user interfaces.<br />
<br />
Alert format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || payload || uchar[] || Serialized alert payload<br />
|-<br />
| ? || signature || uchar[] || An ECDSA signature of the message<br />
|}<br />
<br />
The developers of Satoshi's client use this public key for signing alerts:<br />
04fc9702847840aaf195de8442ebecedf5b095cdbb9bc716bda9110971b28a49e0ead8564ff0db22209e0374782c093bb899692d524e9d6a6956e7c5ecbcd68284<br />
(hash) 1AGRxqDa5WjUKBwHB9XYEjmkv1ucoUUy1s<br />
<br />
The payload is serialized into a uchar[] to ensure that versions using incompatible alert formats can still relay alerts among one another. The current alert payload format is:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || Version || int32_t || Alert format version<br />
|-<br />
| 8 || RelayUntil || int64_t || The timestamp beyond which nodes should stop relaying this alert<br />
|-<br />
| 8 || Expiration || int64_t || The timestamp beyond which this alert is no longer in effect and should be ignored<br />
|-<br />
| 4 || ID || int32_t || A unique ID number for this alert<br />
|-<br />
| 4 || Cancel || int32_t || All alerts with an ID number less than or equal to this number should be cancelled: deleted and not accepted in the future<br />
|-<br />
| ? || setCancel || set<int32_t> || All alert IDs contained in this set should be cancelled as above<br />
|-<br />
| 4 || MinVer || int32_t || This alert only applies to versions greater than or equal to this version. Other versions should still relay it.<br />
|-<br />
| 4 || MaxVer || int32_t || This alert only applies to versions less than or equal to this version. Other versions should still relay it.<br />
|-<br />
| ? || setSubVer || set<string> || If this set contains any elements, then only nodes that have their subVer contained in this set are affected by the alert. Other versions should still relay it.<br />
|-<br />
| 4 || Priority || int32_t || Relative priority compared to other alerts<br />
|-<br />
| ? || Comment || string || A comment on the alert that is not displayed<br />
|-<br />
| ? || StatusBar || string || The alert message that is displayed to the user<br />
|-<br />
| ? || Reserved || string || Reserved<br />
|}<br />
<br />
Note: '''set<''type''>''' in the table above is a [[#Variable length integer | variable length integer]] followed by the number of fields of the given ''type'' (either int32_t or [[#Variable length string | variable length string]])<br />
<br />
Sample alert (no message header):<br />
73010000003766404f00000000b305434f00000000f2030000f1030000001027000048ee0000<br />
0064000000004653656520626974636f696e2e6f72672f666562323020696620796f75206861<br />
76652074726f75626c6520636f6e6e656374696e672061667465722032302046656272756172<br />
79004730450221008389df45f0703f39ec8c1cc42c13810ffcae14995bb648340219e353b63b<br />
53eb022009ec65e1c1aaeec1fd334c6b684bde2b3f573060d5b70c3a46723326e4e8a4f1<br />
<br />
Version: 1<br />
RelayUntil: 1329620535<br />
Expiration: 1329792435<br />
ID: 1010<br />
Cancel: 1009<br />
setCancel: <empty><br />
MinVer: 10000<br />
MaxVer: 61000<br />
setSubVer: <empty><br />
Priority: 100<br />
Comment: <empty><br />
StatusBar: "See bitcoin.org/feb20 if you have trouble connecting after 20 February"<br />
Reserved: <empty><br />
<br />
=== sendheaders ===<br />
<br />
Request for Direct headers announcement. <br />
<br />
Upon receipt of this message, the node is be permitted, but not required, to announce new blocks by '''headers''' command (instead of '''inv''' command).<br />
<br />
This message is supported by the protocol version >= 70012 or Bitcoin Core version >= 0.12.0.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0130.mediawiki BIP 130] for more information.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
<br />
=== feefilter ===<br />
<br />
The payload is always 8 bytes long and it encodes 64 bit integer value (LSB / little endian) of '''feerate'''.<br />
The value represents a minimal fee and is expressed in satoshis per 1000 bytes.<br />
<br />
Upon receipt of a "feefilter" message, the node will be permitted, but not required, to filter transaction invs for transactions that fall below the feerate provided in the feefilter message interpreted as satoshis per kilobyte.<br />
<br />
The fee filter is additive with a bloom filter for transactions so if an SPV client were to load a bloom filter and send a feefilter message, transactions would only be relayed if they passed both filters.<br />
<br />
Inv's generated from a mempool message are also subject to a fee filter if it exists.<br />
<br />
Feature discovery is enabled by checking protocol version >= 70013<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0133.mediawiki BIP 133] for more information.<br />
<br />
=== sendcmpct ===<br />
<br />
# The sendcmpct message is defined as a message containing a 1-byte integer followed by a 8-byte integer where pchCommand == "sendcmpct".<br />
# The first integer SHALL be interpreted as a boolean (and MUST have a value of either 1 or 0)<br />
# The second integer SHALL be interpreted as a little-endian version number. Nodes sending a sendcmpct message MUST currently set this value to 1.<br />
# Upon receipt of a "sendcmpct" message with the first and second integers set to 1, the node SHOULD announce new blocks by sending a cmpctblock message.<br />
# Upon receipt of a "sendcmpct" message with the first integer set to 0, the node SHOULD NOT announce new blocks by sending a cmpctblock message, but SHOULD announce new blocks by sending invs or headers, as defined by BIP130.<br />
# Upon receipt of a "sendcmpct" message with the second integer set to something other than 1, nodes MUST treat the peer as if they had not received the message (as it indicates the peer will provide an unexpected encoding in <br />
# cmpctblock, and/or other, messages). This allows future versions to send duplicate sendcmpct messages with different versions as a part of a version handshake for future versions.<br />
# Nodes SHOULD check for a protocol version of >= 70014 before sending sendcmpct messages.<br />
# Nodes MUST NOT send a request for a MSG_CMPCT_BLOCK object to a peer before having received a sendcmpct message from that peer.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== cmpctblock ===<br />
<br />
# The cmpctblock message is defined as as a message containing a serialized HeaderAndShortIDs message and pchCommand == "cmpctblock".<br />
# Upon receipt of a cmpctblock message after sending a sendcmpct message, nodes SHOULD calculate the short transaction ID for each unconfirmed transaction they have available (ie in their mempool) and compare each to each short transaction ID in the cmpctblock message.<br />
# After finding already-available transactions, nodes which do not have all transactions available to reconstruct the full block SHOULD request the missing transactions using a getblocktxn message.<br />
# A node MUST NOT send a cmpctblock message unless they are able to respond to a getblocktxn message which requests every transaction in the block.<br />
# A node MUST NOT send a cmpctblock message without having validated that the header properly commits to each transaction in the block, and properly builds on top of the existing chain with a valid proof-of-work. A node MAY send a cmpctblock before validating that each transaction in the block validly spends existing UTXO set entries.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== getblocktxn ===<br />
<br />
# The getblocktxn message is defined as as a message containing a serialized BlockTransactionsRequest message and pchCommand == "getblocktxn".<br />
# Upon receipt of a properly-formatted getblocktxnmessage, nodes which recently provided the sender of such a message a cmpctblock for the block hash identified in this message MUST respond with an appropriate blocktxn message. Such a blocktxn message MUST contain exactly and only each transaction which is present in the appropriate block at the index specified in the getblocktxn indexes list, in the order requested.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== blocktxn ===<br />
<br />
# The blocktxn message is defined as as a message containing a serialized BlockTransactions message and pchCommand == "blocktxn".<br />
# Upon receipt of a properly-formatted requested blocktxn message, nodes SHOULD attempt to reconstruct the full block by:<br />
# Taking the prefilledtxn transactions from the original cmpctblock and placing them in the marked positions.<br />
# For each short transaction ID from the original cmpctblock, in order, find the corresponding transaction either from the blocktxn message or from other sources and place it in the first available position in the block.<br />
# Once the block has been reconstructed, it shall be processed as normal, keeping in mind that short transaction IDs are expected to occasionally collide, and that nodes MUST NOT be penalized for such collisions, wherever they # appear.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
== Scripting ==<br />
<br />
See [[script]].<br />
<br />
==See Also==<br />
<br />
* [[Network]]<br />
* [[Protocol rules]]<br />
* [[Hardfork Wishlist]]<br />
* [https://bitcoin.org/en/developer-documentation Developer Documentation on bitcoin.org]<br />
* Bitcoin dissectors for Wireshark: https://github.com/lbotsch/wireshark-bitcoin https://github.com/op-sig/bitcoin-wireshark-dissector<br />
<br />
==References==<br />
<references /><br />
<br />
[[zh-cn:协议说明]]<br />
[[Category:Technical]]<br />
[[Category:Developer]]<br />
<br />
{{Bitcoin Core documentation}}</div>Tonikthttps://en.bitcoin.it/w/index.php?title=Protocol_documentation&diff=61495Protocol documentation2016-08-25T12:44:56Z<p>Tonikt: /* BlockTransactionsRequest */</p>
<hr />
<div>This page ''describes'' the behavior of the [[Original Bitcoin client|reference client]]. The Bitcoin protocol is specified by the behavior of the reference client, not by this page. In particular, while this page is quite complete in describing the network protocol, it does not attempt to list all of the rules for block or transaction validity.<br />
<br />
Type names used in this documentation are from the C99 standard.<br />
<br />
For protocol used in mining, see [[getblocktemplate]].<br />
<br />
==Common standards==<br />
<br />
=== Hashes ===<br />
<br />
Usually, when a hash is computed within bitcoin, it is computed twice. Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-256] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when a shorter hash is desirable (for example when creating a bitcoin address).<br />
<br />
Example of double-SHA-256 encoding of string "hello":<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round of sha-256)<br />
9595c9df90075148eb06860365df33584b75bff782a510c6cd4883a419833d50 (second round of sha-256)<br />
<br />
For bitcoin addresses (RIPEMD-160) this would give:<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round is sha-256)<br />
b6a9c8c230722b7c748331a8b450f05566dc7d0f (with ripemd-160)<br />
<br />
=== Merkle Trees ===<br />
<br />
Merkle trees are binary trees of hashes. Merkle trees in bitcoin use a '''double''' SHA-256, the SHA-256 hash of the SHA-256 hash of something.<br />
<br />
If, when forming a row in the tree (other than the root of the tree), it would have an odd number of elements, the final double-hash is duplicated to ensure that the row has an even number of hashes.<br />
<br />
First form the bottom row of the tree with the ordered double-SHA-256 hashes of the byte streams of the transactions in the block.<br />
<br />
Then the row above it consists of half that number of hashes. Each entry is the double-SHA-256 of the 64-byte concatenation of the corresponding two hashes below it in the tree.<br />
<br />
This procedure repeats recursively until we reach a row consisting of just a single double-hash. This is the '''Merkle root''' of the tree.<br />
<br />
For example, imagine a block with three transactions ''a'', ''b'' and ''c''. The Merkle tree is: <br />
<br />
d1 = dhash(a)<br />
d2 = dhash(b)<br />
d3 = dhash(c)<br />
d4 = dhash(c) # a, b, c are 3. that's an odd number, so we take the c twice<br />
<br />
d5 = dhash(d1 concat d2)<br />
d6 = dhash(d3 concat d4)<br />
<br />
d7 = dhash(d5 concat d6)<br />
<br />
where<br />
<br />
dhash(a) = sha256(sha256(a))<br />
<br />
''d7'' is the Merkle root of the 3 transactions in this block.<br />
<br />
Note: Hashes in Merkle Tree displayed in the [[Block Explorer]] are of little-endian notation. For some implementations and [http://www.fileformat.info/tool/hash.htm calculations], the bits need to be reversed before they are hashed, and again after the hashing operation.<br />
<br />
=== Signatures ===<br />
<br />
Bitcoin uses [http://en.wikipedia.org/wiki/Elliptic_curve_cryptography Elliptic Curve] [http://en.wikipedia.org/wiki/Digital_Signature_Algorithm Digital Signature Algorithm] ([http://en.wikipedia.org/wiki/Elliptic_Curve_DSA ECDSA]) to sign transactions. <br />
<br />
For [[ECDSA]] the secp256k1 curve from http://www.secg.org/collateral/sec2_final.pdf is used.<br />
<br />
Public keys (in scripts) are given as 04 <x> <y> where ''x'' and ''y'' are 32 byte big-endian integers representing the coordinates of a point on the curve or in compressed form given as <sign> <x> where <sign> is 0x02 if ''y'' is even and 0x03 if ''y'' is odd.<br />
<br />
Signatures use [http://en.wikipedia.org/wiki/Distinguished_Encoding_Rules DER encoding] to pack the ''r'' and ''s'' components into a single byte stream (this is also what OpenSSL produces by default).<br />
<br />
=== Transaction Verification ===<br />
Transactions are cryptographically signed records that reassign ownership of Bitcoins to new addresses. Transactions have ''inputs'' - records which reference the funds from other previous transactions - and ''outputs'' - records which determine the new owner of the transferred Bitcoins, and which will be referenced as inputs in future transactions as those funds are respent.<br />
<br />
Each ''input'' must have a cryptographic digital signature that unlocks the funds from the prior transaction. Only the person possessing the appropriate [[private key]] is able to create a satisfactory signature; this in effect ensures that funds can only be spent by their owners.<br />
<br />
Each ''output'' determines which Bitcoin address (or other criteria, see [[Script]]) is the recipient of the funds.<br />
<br />
In a transaction, the sum of all inputs must be equal to or greater than the sum of all outputs. If the inputs exceed the outputs, the difference is considered a [[transaction fee]], and is redeemable by whoever first includes the transaction into the block chain.<br />
<br />
A special kind of transaction, called a [[coinbase transaction]], has no inputs. It is created by [[miners]], and there is one coinbase transaction per block. Because each block comes with a reward of newly created Bitcoins (e.g. 50 BTC for the first 210,000 blocks), the first transaction of a block is, with few exceptions, the transaction that grants those coins to their recipient (the miner). In addition to the newly created Bitcoins, the coinbase transaction is also used for assigning the recipient of any transaction fees that were paid within the other transactions being included in the same block. The coinbase transaction can assign the entire reward to a single Bitcoin address, or split it in portions among multiple addresses, just like any other transaction. Coinbase transactions always contain outputs totalling the sum of the block reward plus all transaction fees collected from the other transactions in the same block.<br />
<br />
The [[coinbase transaction]] in block zero cannot be spent. This is due to a quirk of the reference client implementation that would open the potential for a block chain fork if some nodes accepted the spend and others did not<ref>[http://bitcointalk.org/index.php?topic=119645.msg1288552#msg1288552 Block 0 Network Fork]</ref>.<br />
<br />
Most Bitcoin outputs encumber the newly transferred coins with a single ECDSA private key. The actual record saved with inputs and outputs isn't necessarily a key, but a ''script''. Bitcoin uses an interpreted scripting system to determine whether an output's criteria have been satisfied, with which more complex operations are possible, such as outputs that require two ECDSA signatures, or two-of-three-signature schemes. An output that references a single Bitcoin address is a ''typical'' output; an output actually contains this information in the form of a script that requires a single ECDSA signature (see [[OP_CHECKSIG]]). The output script specifies what must be provided to unlock the funds later, and when the time comes in the future to spend the transaction in another input, that input must provide all of the thing(s) that satisfy the requirements defined by the original output script.<br />
<br />
=== Addresses ===<br />
<br />
A bitcoin address is in fact the hash of a ECDSA public key, computed this way:<br />
<br />
Version = 1 byte of 0 (zero); on the test network, this is 1 byte of 111<br />
Key hash = Version concatenated with RIPEMD-160(SHA-256(public key))<br />
Checksum = 1st 4 bytes of SHA-256(SHA-256(Key hash))<br />
Bitcoin Address = Base58Encode(Key hash concatenated with Checksum)<br />
<br />
The Base58 encoding used is home made, and has some differences. Especially, leading zeroes are kept as single zeroes when conversion happens.<br />
<br />
== Common structures ==<br />
<br />
Almost all integers are encoded in little endian. Only IP or port number are encoded big endian.<br />
<br />
=== Message structure ===<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown<br />
|-<br />
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| 4 || length || uint32_t || Length of payload in number of bytes<br />
|-<br />
| 4 || checksum || uint32_t || First 4 bytes of sha256(sha256(payload))<br />
|-<br />
| ? || payload || uchar[] || The actual data<br />
|}<br />
<br />
<br />
Known magic values:<br />
<br />
{|class="wikitable"<br />
! Network !! Magic value !! Sent over wire as<br />
|-<br />
| main || 0xD9B4BEF9 || F9 BE B4 D9<br />
|-<br />
| testnet || 0xDAB5BFFA || FA BF B5 DA<br />
|-<br />
| testnet3 || 0x0709110B || 0B 11 09 07<br />
|-<br />
| namecoin || 0xFEB4BEF9 || F9 BE B4 FE<br />
|}<br />
<br />
=== Variable length integer ===<br />
<br />
Integer can be encoded depending on the represented value to save space.<br />
Variable length integers always precede an array/vector of a type of data that may vary in length.<br />
Longer numbers are encoded in little endian.<br />
<br />
{|class="wikitable"<br />
! Value !! Storage length !! Format<br />
|-<br />
| < 0xFD || 1 || uint8_t<br />
|-<br />
| <= 0xFFFF || 3 || 0xFD followed by the length as uint16_t<br />
|-<br />
| <= 0xFFFF FFFF || 5 || 0xFE followed by the length as uint32_t<br />
|-<br />
| - || 9 || 0xFF followed by the length as uint64_t<br />
|}<br />
<br />
If you're reading the Satoshi client code (BitcoinQT) it refers to this encoding as a "CompactSize". Modern BitcoinQT also has the CVarInt class which implements an even more compact integer for the purpose of local storage (which is incompatible with "CompactSize" described here). CVarInt is not a part of the protocol.<br />
<br />
=== Variable length string ===<br />
<br />
Variable length string can be stored using a variable length integer followed by the string itself.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the string<br />
|-<br />
| ? || string || char[] || The string itself (can be empty)<br />
|}<br />
<br />
=== Network address ===<br />
<br />
When a network address is needed somewhere, this structure is used. Network addresses are not prefixed with a timestamp in the version message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || time || uint32 || the Time (version >= 31402). '''Not present in version message.'''<br />
|-<br />
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]<br />
|-<br />
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The original client only supported IPv4 and only read the last 4 bytes to get the IPv4 address. However, the IPv4 address is written into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]<br />
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).<br />
|-<br />
| 2 || port || uint16_t || port number, network byte order<br />
|}<br />
<br />
Hexdump example of Network address structure<br />
<br />
<pre><br />
0000 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0010 00 00 FF FF 0A 00 00 01 20 8D ........ .<br />
<br />
Network address:<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK: see services listed under version command)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv6: ::ffff:a00:1 or IPv4: 10.0.0.1<br />
20 8D - Port 8333<br />
</pre><br />
<br />
=== Inventory Vectors ===<br />
<br />
Inventory vectors are used for notifying other nodes about objects they have or data which is being requested.<br />
<br />
Inventory vectors consist of the following data format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || type || uint32_t || Identifies the object type linked to this inventory<br />
|-<br />
| 32 || hash || char[32] || Hash of the object<br />
|}<br />
<br />
<br />
The object type is currently defined as one of the following possibilities:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0 || ERROR || Any data of with this number may be ignored<br />
|-<br />
| 1 || MSG_TX || Hash is related to a transaction<br />
|-<br />
| 2 || MSG_BLOCK || Hash is related to a data block<br />
|-<br />
| 3 || MSG_FILTERED_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a merkleblock message rather than a block message; this only works if a bloom filter has been set.<br />
|-<br />
| 4 || MSG_CMPCT_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a cmpctblock message. See BIP 152 for more info.<br />
|}<br />
<br />
Other Data Type values are considered reserved for future implementations.<br />
<br />
=== Block Headers ===<br />
<br />
Block headers are sent in a headers packet in response to a getheaders message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Will overflow in 2106<ref>https://en.wikipedia.org/wiki/Unix_time#Notable_events_in_Unix_time</ref>)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 1 || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries, this value is always 0<br />
|}<br />
<br />
cf. [[Block hashing algorithm]]<br />
<br />
=== PrefilledTransaction ===<br />
<br />
A PrefilledTransaction structure is used in HeaderAndShortIDs to provide a list of a few transactions explicitly.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| index || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1, 3 bytes || Compact Size, differentially encoded since the last PrefilledTransaction in a list || The index into the block at which this transaction is<br />
|-<br />
| tx || Transaction || variable || As encoded in [[Protocol_documentation#tx|tx messages]] || The transaction which is in the block at index index.<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== HeaderAndShortIDs ===<br />
<br />
A HeaderAndShortIDs structure is used to relay a block header, the short transactions IDs used for matching already-available transactions, and a select few transactions which we expect a peer may be missing.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| header || Block header || 80 bytes || First 80 bytes of the block as defined by the encoding used by "block" messages || The header of the block being provided<br />
|-<br />
| nonce || uint64_t || 8 bytes || Little Endian || A nonce for use in short transaction ID calculations<br />
|-<br />
| shortids_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of short transaction IDs in shortids (ie block tx count - prefilledtxn_length)<br />
|-<br />
| shortids || List of 6-byte integers || 6*shortids_length bytes || Little Endian || The short transaction IDs calculated from the transactions which were not provided explicitly in prefilledtxn<br />
|-<br />
| prefilledtxn_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of prefilled transactions in prefilledtxn (ie block tx count - shortids_length)<br />
|-<br />
| prefilledtxn || List of PrefilledTransactions || variable size*prefilledtxn_length || As defined by PrefilledTransaction definition, above || Used to provide the coinbase transaction and a select few which we expect a peer may be missing<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== BlockTransactionsRequest ===<br />
<br />
A BlockTransactionsRequest structure is used to list transaction indexes in a block being requested.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| blockhash || Binary blob || 32 bytes || The output from a double-SHA256 of the block header, as used elsewhere || The blockhash of the block which the transactions being requested are in<br />
|-<br />
| indexes_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of transactions being requested<br />
|-<br />
| indexes || List of [[Protocol_documentation#Variable_length_integer|CompactSizes]] || 1 or 3 bytes*indexes_length || Differentially encoded || The indexes of the transactions being requested in the block<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== BlockTransactions ===<br />
<br />
A BlockTransactions structure is used to provide some of the transactions in a block, as requested.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| blockhash || Binary blob || 32 bytes || The output from a double-SHA256 of the block header, as used elsewhere || The blockhash of the block which the transactions being provided are in<br />
|-<br />
| transactions_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of transactions provided<br />
|-<br />
| transactions || List of Transactions || variable || As encoded in "tx" messages || The transactions provided<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== Short transaction ID ===<br />
<br />
Short transaction IDs are used to represent a transaction without sending a full 256-bit hash. They are calculated by:<br />
<br />
# single-SHA256 hashing the block header with the nonce appended (in little-endian)<br />
# Running SipHash-2-4 with the input being the transaction ID and the keys (k0/k1) set to the first two little-endian 64-bit integers from the above hash, respectively.<br />
# Dropping the 2 most significant bytes from the SipHash output to make it 6 bytes.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
== Message types ==<br />
<br />
=== version ===<br />
<br />
When a node creates an outgoing connection, it will immediately [[Version Handshake|advertise]] its version. The remote node will respond with its version. No further communication is possible until both peers have exchanged their version.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Identifies protocol version being used by the node<br />
|-<br />
| 8 || services || uint64_t || bitfield of features to be enabled for this connection<br />
|-<br />
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds<br />
|-<br />
| 26 || addr_recv || [[#Network address|net_addr]] || The network address of the node receiving this message<br />
|-<br />
|colspan="4"| Fields below require version ≥ 106<br />
|-<br />
| 26 || addr_from || [[#Network address|net_addr]] || The network address of the node emitting this message<br />
|-<br />
| 8 || nonce || uint64_t || Node random nonce, randomly generated every time a version packet is sent. This nonce is used to detect connections to self.<br />
|-<br />
| ? || user_agent || [[#Variable length string|var_str]] || [https://github.com/bitcoin/bips/blob/master/bip-0014.mediawiki User Agent] (0x00 if string is 0 bytes long)<br />
|-<br />
| 4 || start_height || int32_t || The last block received by the emitting node<br />
|-<br />
|colspan="4"| Fields below require version ≥ 70001<br />
|-<br />
| 1 || relay || bool || Whether the remote peer should announce relayed transactions or not, see [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037]<br />
|}<br />
<br />
A "verack" packet shall be sent if the version packet was accepted.<br />
<br />
The following services are currently assigned:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 1 || NODE_NETWORK || This node can be asked for full blocks instead of just headers.<br />
|}<br />
<br />
Hexdump example of version message (OBSOLETE EXAMPLE: This example lacks a checksum and user-agent):<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....<br />
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........<br />
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............<br />
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................<br />
0040 20 8D 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,<br />
0060 3A B4 57 13 00 55 81 01 00 :.W..U...<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
55 00 00 00 - Payload is 85 bytes long<br />
- No checksum in version message until 20 February 2012. See https://bitcointalk.org/index.php?topic=55852.0<br />
Version message:<br />
9C 7C 00 00 - 31900 (version 0.3.19)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
E6 15 10 4D 00 00 00 00 - Mon Dec 20 21:50:14 EST 2010<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 20 8D - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D - Sender address info - see Network Address<br />
DD 9D 20 2C 3A B4 57 13 - Node random unique ID<br />
00 - "" sub-version string (string is 0 bytes long)<br />
55 81 01 00 - Last block sending node has is block #98645<br />
</pre><br />
<br />
And here's a modern (60002) protocol version client advertising itself to a local peer...<br />
<br />
Newer protocol includes the checksum now, this is from a mainline (satoshi) client during <br />
an outgoing connection to another local client, notice that it does not fill out the <br />
address information at all when the source or destination is "unroutable".<br />
<br />
<pre><br />
<br />
0000 f9 be b4 d9 76 65 72 73 69 6f 6e 00 00 00 00 00 ....version.....<br />
0010 64 00 00 00 35 8d 49 32 62 ea 00 00 01 00 00 00 d...5.I2b.......<br />
0020 00 00 00 00 11 b2 d0 50 00 00 00 00 01 00 00 00 .......P........<br />
0030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ff ff ................<br />
0040 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 00 00 00 00 ff ff 00 00 00 00 00 00 ................<br />
0060 3b 2e b3 5d 8c e6 17 65 0f 2f 53 61 74 6f 73 68 ;..]...e./Satosh<br />
0070 69 3a 30 2e 37 2e 32 2f c0 3e 03 00 i:0.7.2/.>..<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
64 00 00 00 - Payload is 100 bytes long<br />
3B 64 8D 5A - payload checksum<br />
<br />
Version message:<br />
62 EA 00 00 - 60002 (protocol version 60002)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
11 B2 D0 50 00 00 00 00 - Tue Dec 18 10:12:33 PST 2012<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Sender address info - see Network Address<br />
3B 2E B3 5D 8C E6 17 65 - Node ID<br />
0F 2F 53 61 74 6F 73 68 69 3A 30 2E 37 2E 32 2F - "/Satoshi:0.7.2/" sub-version string (string is 15 bytes long)<br />
C0 3E 03 00 - Last block sending node has is block #212672<br />
</pre><br />
<br />
=== verack ===<br />
<br />
The ''verack'' message is sent in reply to ''[[#version|version]]''. This message consists of only a [[#Message structure|message header]] with the command string "verack".<br />
<br />
Hexdump of the verack message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......<br />
0010 00 00 00 00 5D F6 E0 E2 ........<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 61 63 6B 00 00 00 00 00 00 - "verack" command<br />
00 00 00 00 - Payload is 0 bytes long<br />
5D F6 E0 E2 - Checksum<br />
</pre><br />
<br />
=== addr ===<br />
<br />
Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours<br />
<br />
Payload:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of address entries (max: 1000)<br />
|-<br />
| 30x? || addr_list || (uint32_t + [[#Network address|net_addr]])[] || Address of other nodes on the network. version < 209 will only read the first one. The uint32_t is a timestamp (see note below).<br />
|}<br />
<br />
'''Note''': Starting version 31402, addresses are prefixed with a timestamp. If no timestamp is present, the addresses should not be relayed to other peers, unless it is indeed confirmed they are up.<br />
<br />
Hexdump example of ''addr'' message:<br />
<pre><br />
0000 F9 BE B4 D9 61 64 64 72 00 00 00 00 00 00 00 00 ....addr........<br />
0010 1F 00 00 00 ED 52 39 9B 01 E2 15 10 4D 01 00 00 .....R9.....M...<br />
0020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF ................<br />
0030 FF 0A 00 00 01 20 8D ..... .<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
61 64 64 72 00 00 00 00 00 00 00 00 - "addr"<br />
1F 00 00 00 - payload is 31 bytes long<br />
ED 52 39 9B - checksum of payload<br />
<br />
Payload:<br />
01 - 1 address in this message<br />
<br />
Address:<br />
E2 15 10 4D - Mon Dec 20 21:50:10 EST 2010 (only when version is >= 31402)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK service - see version message)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv4: 10.0.0.1, IPv6: ::ffff:10.0.0.1 (IPv4-mapped IPv6 address)<br />
20 8D - port 8333<br />
</pre><br />
<br />
=== inv ===<br />
<br />
Allows a node to advertise its knowledge of one or more objects. It can be received unsolicited, or in reply to ''getblocks''.<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getdata ===<br />
<br />
getdata is used in response to inv, to retrieve the content of a specific object, and is usually sent after receiving an ''inv'' packet, after filtering known elements. It can be used to retrieve transactions, but only if they are in the memory pool or relay set - arbitrary access to transactions in the chain is not allowed to avoid having clients start to depend on nodes having full transaction indexes (which modern nodes do not).<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== notfound ===<br />
<br />
notfound is a response to a getdata, sent if any requested data items could not be relayed, for example, because the requested transaction was not in the memory pool or relay set.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getblocks ===<br />
<br />
Return an ''inv'' packet containing the list of blocks starting right after the last known hash in the block locator object, up to hash_stop or 500 blocks, whichever comes first. <br />
<br />
The locator hashes are processed by a node in the order as they appear in the message. If a block hash is found in the node's main chain, the list of its children is returned back via the ''inv'' message and the remaining locators are ignored, no matter if the requested limit was reached, or not.<br />
<br />
To receive the next blocks hashes, one needs to issue getblocks again with a new block locator object. Keep in mind that some clients may provide blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block; set to zero to get as many blocks as possible (500)<br />
|}<br />
<br />
To create the block locator hashes, keep pushing hashes until you go back to the genesis block. After pushing 10 hashes back, the step backwards doubles every loop:<br />
<br />
<pre><br />
// From libbitcoin which is under AGPL<br />
std::vector<size_t> block_locator_indexes(size_t top_height)<br />
{<br />
std::vector<size_t> indexes;<br />
<br />
// Modify the step in the iteration.<br />
int64_t step = 1;<br />
<br />
// Start at the top of the chain and work backwards.<br />
for (auto index = (int64_t)top_height; index > 0; index -= step)<br />
{<br />
// Push top 10 indexes first, then back off exponentially.<br />
if (indexes.size() >= 10)<br />
step *= 2;<br />
<br />
indexes.push_back((size_t)index);<br />
}<br />
<br />
// Push the genesis block index.<br />
indexes.push_back(0);<br />
return indexes;<br />
}<br />
</pre><br />
<br />
Note that it is allowed to send in fewer known hashes down to a minimum of just one hash. However, the purpose of the block locator object is to detect a wrong branch in the caller's main chain. If the peer detects that you are off the main chain, it will send in block hashes which are earlier than your last known block. So if you just send in your last known hash and it is off the main chain, the peer starts over at block #1.<br />
<br />
=== getheaders ===<br />
<br />
Return a ''headers'' packet containing the headers of blocks starting right after the last known hash in the block locator object, up to hash_stop or 2000 blocks, whichever comes first. To receive the next block headers, one needs to issue getheaders again with a new block locator object. The ''getheaders'' command is used by thin clients to quickly download the block chain where the contents of the transactions would be irrelevant (because they are not ours). Keep in mind that some clients may provide headers of blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block header; set to zero to get as many blocks as possible (2000)<br />
|}<br />
<br />
For the block locator object in this packet, the same rules apply as for the [[Protocol_documentation#getblocks|getblocks]] packet.<br />
<br />
=== tx ===<br />
<br />
''tx'' describes a bitcoin transaction, in reply to ''[[#getdata|getdata]]''<br />
<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Transaction data format version (note, this is signed)<br />
|-<br />
| 1+ || tx_in count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction inputs<br />
|-<br />
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins<br />
|-<br />
| 1+ || tx_out count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction outputs<br />
|-<br />
| 9+ || tx_out || tx_out[] || A list of 1 or more transaction outputs or destinations for coins<br />
|-<br />
| 4 || lock_time || uint32_t || The block number or timestamp at which this transaction is locked:<br />
{|class="wikitable"<br />
! Value !! Description<br />
|-<br />
| 0 || Not locked<br />
|-<br />
| < 500000000 || Block number at which this transaction is locked<br />
|-<br />
| >= 500000000 || UNIX timestamp at which this transaction is locked<br />
|}<br />
If all TxIn inputs have final (0xffffffff) sequence numbers then lock_time is irrelevant. Otherwise, the transaction may not be added to a block until after lock_time (see [[NLockTime]]).<br />
<br />
|}<br />
<br />
TxIn consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 36 || previous_output || outpoint || The previous output transaction reference, as an OutPoint structure<br />
|-<br />
| 1+ || script length || [[Protocol_documentation#Variable_length_integer|var_int]] || The length of the signature script<br />
|-<br />
| ? || signature script || uchar[] || Computational Script for confirming transaction authorization<br />
|-<br />
| 4 || [http://bitcoin.stackexchange.com/q/2025/323 sequence] || uint32_t || Transaction version as defined by the sender. Intended for "replacement" of transactions when information is updated before inclusion into a block.<br />
|}<br />
<br />
The OutPoint structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 32 || hash || char[32] || The hash of the referenced transaction.<br />
|-<br />
| 4 || index || uint32_t || The index of the specific output in the transaction. The first output is 0, etc.<br />
|}<br />
<br />
The Script structure consists of a series of pieces of information and operations related to the value of the transaction.<br />
<br />
(Structure to be expanded in the future… see script.h and script.cpp and [[Script]] for more information)<br />
<br />
The TxOut structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || value || int64_t || Transaction Value<br />
|-<br />
| 1+ || pk_script length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the pk_script<br />
|-<br />
| ? || pk_script || uchar[] || Usually contains the public key as a Bitcoin script setting up conditions to claim this output.<br />
|}<br />
<br />
Example ''tx'' message:<br />
<pre><br />
000000 F9 BE B4 D9 74 78 00 00 00 00 00 00 00 00 00 00 ....tx..........<br />
000010 02 01 00 00 E2 93 CD BE 01 00 00 00 01 6D BD DB .............m..<br />
000020 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D 12 66 E9 .[...Q........f.<br />
000030 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29 00 00 00 .;P......j.6)...<br />
000040 00 8B 48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 ..H0E.!..X..r...<br />
000050 C7 36 7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A .6zz%;..R#...h.:<br />
000060 59 23 3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 Y#?E.W... Y.....<br />
000070 0E 41 83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D .A.z.X.z...XN...<br />
000080 35 BD 96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF 5...6..;...A....<br />
000090 C9 7E F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 .~.6.m...@..!...<br />
0000A0 2A CD 2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC *.+..].}Y... ...<br />
0000B0 4E 02 53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F N.S..=7.o...Q...<br />
0000C0 14 04 2F 46 61 4A 4C 70 C0 F1 4B EF F5 FF FF FF ../FaJLp..K.....<br />
0000D0 FF 02 40 4B 4C 00 00 00 00 00 19 76 A9 14 1A A0 ..@KL......v....<br />
0000E0 CD 1C BE A6 E7 45 8A 7A BA D5 12 A9 D9 EA 1A FB .....E.z........<br />
0000F0 22 5E 88 AC 80 FA E9 C7 00 00 00 00 19 76 A9 14 "^...........v..<br />
000100 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E FD A0 B7 ..[.Cj.....H^...<br />
000110 8B 4E CC 52 88 AC 00 00 00 00 .N.R......<br />
<br />
<br />
Message header:<br />
F9 BE B4 D9 - main network magic bytes<br />
74 78 00 00 00 00 00 00 00 00 00 00 - "tx" command<br />
02 01 00 00 - payload is 258 bytes long<br />
E2 93 CD BE - checksum of payload<br />
<br />
Transaction:<br />
01 00 00 00 - version<br />
<br />
Inputs:<br />
01 - number of transaction inputs<br />
<br />
Input 1:<br />
6D BD DB 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D - previous output (outpoint)<br />
12 66 E9 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29<br />
00 00 00 00<br />
<br />
8B - script is 139 bytes long<br />
<br />
48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 C7 36 - signature script (scriptSig)<br />
7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A 59 23<br />
3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 0E 41<br />
83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D 35 BD<br />
96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF C9 7E<br />
F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 2A CD<br />
2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC 4E 02<br />
53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F 14 04<br />
2F 46 61 4A 4C 70 C0 F1 4B EF F5<br />
<br />
FF FF FF FF - sequence<br />
<br />
Outputs:<br />
02 - 2 Output Transactions<br />
<br />
Output 1:<br />
40 4B 4C 00 00 00 00 00 - 0.05 BTC (5000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 1A A0 CD 1C BE A6 E7 45 8A 7A BA D5 12 - pk_script<br />
A9 D9 EA 1A FB 22 5E 88 AC<br />
<br />
Output 2:<br />
80 FA E9 C7 00 00 00 00 - 33.54 BTC (3354000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E - pk_script<br />
FD A0 B7 8B 4E CC 52 88 AC<br />
<br />
Locktime:<br />
00 00 00 00 - lock time<br />
</pre><br />
<br />
=== block ===<br />
<br />
The '''block''' message is sent in response to a getdata message which requests transaction information from a block hash.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A Unix timestamp recording when this block was created (Currently limited to dates before the year 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated [[Difficulty|difficulty target]] being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| ? || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries<br />
|-<br />
| ? || txns || tx[] || Block transactions, in format of "tx" command<br />
|}<br />
<br />
The SHA256 hash that identifies each block (and which must have a run of 0 bits) is calculated from the first 6 fields of this structure (version, prev_block, merkle_root, timestamp, bits, nonce, and standard SHA256 padding, making two 64-byte chunks in all) and ''not'' from the complete block. To calculate the hash, only two chunks need to be processed by the SHA256 algorithm. Since the ''nonce'' field is in the second chunk, the first chunk stays constant during mining and therefore only the second chunk needs to be processed. However, a Bitcoin hash is the hash of the hash, so two SHA256 rounds are needed for each mining iteration.<br />
See [[Block hashing algorithm]] for details and an example.<br />
<br />
=== headers ===<br />
<br />
The ''headers'' packet returns block headers in response to a ''getheaders'' packet. <br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of block headers<br />
|-<br />
| 81x? || headers || [[Protocol_documentation#Block_Headers|block_header]][] || [[Protocol_documentation#Block_Headers|Block headers]]<br />
|}<br />
<br />
Note that the block headers in this packet include a transaction count (a var_int, so there can be more than 81 bytes per header) as opposed to the block headers that are hashed by miners.<br />
<br />
=== getaddr ===<br />
<br />
The getaddr message sends a request to a node asking for information about known active peers to help with finding potential nodes in the network. The response to receiving this message is to transmit one or more addr messages with one or more peers from a database of known active peers. The typical presumption is that a node is likely to be active if it has been sending a message within the last three hours.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
=== mempool ===<br />
<br />
The mempool message sends a request to a node asking for information about transactions it has verified but which have not yet confirmed. The response to receiving this message is an inv message containing the transaction hashes for all the transactions in the node's mempool.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
It is specified in [https://github.com/bitcoin/bips/blob/master/bip-0035.mediawiki BIP 35]. Since [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 37], if a [[Protocol_documentation#filterload.2C_filteradd.2C_filterclear.2C_merkleblock|bloom filter]] is loaded, only transactions matching the filter are replied.<br />
<br />
=== checkorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== submitorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== reply ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== ping ===<br />
<br />
The ''ping'' message is sent primarily to confirm that the TCP/IP connection is still valid. An error in transmission is presumed to be a closed connection and the address is removed as a current peer.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || random nonce<br />
|}<br />
<br />
=== pong ===<br />
<br />
The ''pong'' message is sent in response to a ''ping'' message. In modern protocol versions, a ''pong'' response is generated using a nonce included in the ping.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || nonce from ping<br />
|}<br />
<br />
<br />
=== reject===<br />
<br />
The ''reject'' message is sent when messages are rejected.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || message || var_str || type of message rejected<br />
|-<br />
| 1 || ccode || char || code relating to rejected message<br />
|-<br />
| 1+ || reason || var_str || text version of reason for rejection<br />
|-<br />
| 0+ || data || char || Optional extra data provided by some errors. Currently, all errors which provide this field fill it with the TXID or block header hash of the object being rejected, so the field is 32 bytes.<br />
|}<br />
<br />
CCodes<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0x01 || REJECT_MALFORMED|| <br />
|-<br />
| 0x10 || REJECT_INVALID ||<br />
|-<br />
| 0x11 || REJECT_OBSOLETE ||<br />
|-<br />
| 0x12 || REJECT_DUPLICATE ||<br />
|-<br />
| 0x40 || REJECT_NONSTANDARD ||<br />
|-<br />
| 0x41 || REJECT_DUST ||<br />
|-<br />
| 0x42 || REJECT_INSUFFICIENTFEE ||<br />
|-<br />
| 0x43 || REJECT_CHECKPOINT ||<br />
|}<br />
<br />
=== filterload, filteradd, filterclear, merkleblock ===<br />
<br />
These messages are related to Bloom filtering of connections and are defined in [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037].<br />
<br />
<br />
The <code>filterload</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || filter || uint8_t[] || The filter itself is simply a bit field of arbitrary byte-aligned size. The maximum size is 36,000 bytes.<br />
|-<br />
| 4 || nHashFuncs || uint32_t || The number of hash functions to use in this filter. The maximum value allowed in this field is 50.<br />
|-<br />
| 4 || nTweak || uint32_t || A random value to add to the seed value in the hash function used by the bloom filter.<br />
|-<br />
| 1 || nFlags || uint8_t || A set of flags that control how matched items are added to the filter.<br />
|}<br />
<br />
See below for a description of the Bloom filter algorithm and how to select nHashFuncs and filter size for a desired false positive rate.<br />
<br />
Upon receiving a <code>filterload</code> command, the remote peer will immediately restrict the broadcast transactions it announces (in inv packets) to transactions matching the filter, where the matching algorithm is specified below. The flags control the update behaviour of the matching algorithm.<br />
<br />
The <code>filteradd</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || data || uint8_t[] || The data element to add to the current filter.<br />
|}<br />
<br />
The data field must be smaller than or equal to 520 bytes in size (the maximum size of any potentially matched object).<br />
<br />
The given data element will be added to the Bloom filter. A filter must have been previously provided using <code>filterload</code>. This command is useful if a new key or script is added to a clients wallet whilst it has connections to the network open, it avoids the need to re-calculate and send an entirely new filter to every peer (though doing so is usually advisable to maintain anonymity).<br />
<br />
The <code>filterclear</code> command has no arguments at all.<br />
<br />
After a filter has been set, nodes don't merely stop announcing non-matching transactions, they can also serve filtered blocks. A filtered block is defined by the <code>merkleblock</code> message and is defined like this:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information, based upon the software version creating this block (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Limited to 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 4 || total_transactions || uint32_t || Number of transactions in the block (including unmatched ones)<br />
|-<br />
| ? || hashes || uint256[] || hashes in depth-first order (including standard varint size prefix)<br />
|-<br />
| ? || flags || byte[] || flag bits, packed per 8 in a byte, least significant bit first (including standard varint size prefix)<br />
|}<br />
<br />
=== alert ===<br />
<br />
An '''alert''' is sent between nodes to send a general notification message throughout the network. If the alert can be confirmed with the signature as having come from the core development group of the Bitcoin software, the message is suggested to be displayed for end-users. Attempts to perform transactions, particularly automated transactions through the client, are suggested to be halted. The text in the Message string should be relayed to log files and any user interfaces.<br />
<br />
Alert format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || payload || uchar[] || Serialized alert payload<br />
|-<br />
| ? || signature || uchar[] || An ECDSA signature of the message<br />
|}<br />
<br />
The developers of Satoshi's client use this public key for signing alerts:<br />
04fc9702847840aaf195de8442ebecedf5b095cdbb9bc716bda9110971b28a49e0ead8564ff0db22209e0374782c093bb899692d524e9d6a6956e7c5ecbcd68284<br />
(hash) 1AGRxqDa5WjUKBwHB9XYEjmkv1ucoUUy1s<br />
<br />
The payload is serialized into a uchar[] to ensure that versions using incompatible alert formats can still relay alerts among one another. The current alert payload format is:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || Version || int32_t || Alert format version<br />
|-<br />
| 8 || RelayUntil || int64_t || The timestamp beyond which nodes should stop relaying this alert<br />
|-<br />
| 8 || Expiration || int64_t || The timestamp beyond which this alert is no longer in effect and should be ignored<br />
|-<br />
| 4 || ID || int32_t || A unique ID number for this alert<br />
|-<br />
| 4 || Cancel || int32_t || All alerts with an ID number less than or equal to this number should be cancelled: deleted and not accepted in the future<br />
|-<br />
| ? || setCancel || set<int32_t> || All alert IDs contained in this set should be cancelled as above<br />
|-<br />
| 4 || MinVer || int32_t || This alert only applies to versions greater than or equal to this version. Other versions should still relay it.<br />
|-<br />
| 4 || MaxVer || int32_t || This alert only applies to versions less than or equal to this version. Other versions should still relay it.<br />
|-<br />
| ? || setSubVer || set<string> || If this set contains any elements, then only nodes that have their subVer contained in this set are affected by the alert. Other versions should still relay it.<br />
|-<br />
| 4 || Priority || int32_t || Relative priority compared to other alerts<br />
|-<br />
| ? || Comment || string || A comment on the alert that is not displayed<br />
|-<br />
| ? || StatusBar || string || The alert message that is displayed to the user<br />
|-<br />
| ? || Reserved || string || Reserved<br />
|}<br />
<br />
Note: '''set<''type''>''' in the table above is a [[#Variable length integer | variable length integer]] followed by the number of fields of the given ''type'' (either int32_t or [[#Variable length string | variable length string]])<br />
<br />
Sample alert (no message header):<br />
73010000003766404f00000000b305434f00000000f2030000f1030000001027000048ee0000<br />
0064000000004653656520626974636f696e2e6f72672f666562323020696620796f75206861<br />
76652074726f75626c6520636f6e6e656374696e672061667465722032302046656272756172<br />
79004730450221008389df45f0703f39ec8c1cc42c13810ffcae14995bb648340219e353b63b<br />
53eb022009ec65e1c1aaeec1fd334c6b684bde2b3f573060d5b70c3a46723326e4e8a4f1<br />
<br />
Version: 1<br />
RelayUntil: 1329620535<br />
Expiration: 1329792435<br />
ID: 1010<br />
Cancel: 1009<br />
setCancel: <empty><br />
MinVer: 10000<br />
MaxVer: 61000<br />
setSubVer: <empty><br />
Priority: 100<br />
Comment: <empty><br />
StatusBar: "See bitcoin.org/feb20 if you have trouble connecting after 20 February"<br />
Reserved: <empty><br />
<br />
=== sendheaders ===<br />
<br />
Request for Direct headers announcement. <br />
<br />
Upon receipt of this message, the node is be permitted, but not required, to announce new blocks by '''headers''' command (instead of '''inv''' command).<br />
<br />
This message is supported by the protocol version >= 70012 or Bitcoin Core version >= 0.12.0.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0130.mediawiki BIP 130] for more information.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
<br />
=== feefilter ===<br />
<br />
The payload is always 8 bytes long and it encodes 64 bit integer value (LSB / little endian) of '''feerate'''.<br />
The value represents a minimal fee and is expressed in satoshis per 1000 bytes.<br />
<br />
Upon receipt of a "feefilter" message, the node will be permitted, but not required, to filter transaction invs for transactions that fall below the feerate provided in the feefilter message interpreted as satoshis per kilobyte.<br />
<br />
The fee filter is additive with a bloom filter for transactions so if an SPV client were to load a bloom filter and send a feefilter message, transactions would only be relayed if they passed both filters.<br />
<br />
Inv's generated from a mempool message are also subject to a fee filter if it exists.<br />
<br />
Feature discovery is enabled by checking protocol version >= 70013<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0133.mediawiki BIP 133] for more information.<br />
<br />
=== sendcmpct ===<br />
<br />
# The sendcmpct message is defined as a message containing a 1-byte integer followed by a 8-byte integer where pchCommand == "sendcmpct".<br />
# The first integer SHALL be interpreted as a boolean (and MUST have a value of either 1 or 0)<br />
# The second integer SHALL be interpreted as a little-endian version number. Nodes sending a sendcmpct message MUST currently set this value to 1.<br />
# Upon receipt of a "sendcmpct" message with the first and second integers set to 1, the node SHOULD announce new blocks by sending a cmpctblock message.<br />
# Upon receipt of a "sendcmpct" message with the first integer set to 0, the node SHOULD NOT announce new blocks by sending a cmpctblock message, but SHOULD announce new blocks by sending invs or headers, as defined by BIP130.<br />
# Upon receipt of a "sendcmpct" message with the second integer set to something other than 1, nodes MUST treat the peer as if they had not received the message (as it indicates the peer will provide an unexpected encoding in <br />
# cmpctblock, and/or other, messages). This allows future versions to send duplicate sendcmpct messages with different versions as a part of a version handshake for future versions.<br />
# Nodes SHOULD check for a protocol version of >= 70014 before sending sendcmpct messages.<br />
# Nodes MUST NOT send a request for a MSG_CMPCT_BLOCK object to a peer before having received a sendcmpct message from that peer.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== cmpctblock ===<br />
<br />
# The cmpctblock message is defined as as a message containing a serialized HeaderAndShortIDs message and pchCommand == "cmpctblock".<br />
# Upon receipt of a cmpctblock message after sending a sendcmpct message, nodes SHOULD calculate the short transaction ID for each unconfirmed transaction they have available (ie in their mempool) and compare each to each short transaction ID in the cmpctblock message.<br />
# After finding already-available transactions, nodes which do not have all transactions available to reconstruct the full block SHOULD request the missing transactions using a getblocktxn message.<br />
# A node MUST NOT send a cmpctblock message unless they are able to respond to a getblocktxn message which requests every transaction in the block.<br />
# A node MUST NOT send a cmpctblock message without having validated that the header properly commits to each transaction in the block, and properly builds on top of the existing chain with a valid proof-of-work. A node MAY send a cmpctblock before validating that each transaction in the block validly spends existing UTXO set entries.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== getblocktxn ===<br />
<br />
# The getblocktxn message is defined as as a message containing a serialized BlockTransactionsRequest message and pchCommand == "getblocktxn".<br />
# Upon receipt of a properly-formatted getblocktxnmessage, nodes which recently provided the sender of such a message a cmpctblock for the block hash identified in this message MUST respond with an appropriate blocktxn message. Such a blocktxn message MUST contain exactly and only each transaction which is present in the appropriate block at the index specified in the getblocktxn indexes list, in the order requested.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== blocktxn ===<br />
<br />
# The blocktxn message is defined as as a message containing a serialized BlockTransactions message and pchCommand == "blocktxn".<br />
# Upon receipt of a properly-formatted requested blocktxn message, nodes SHOULD attempt to reconstruct the full block by:<br />
# Taking the prefilledtxn transactions from the original cmpctblock and placing them in the marked positions.<br />
# For each short transaction ID from the original cmpctblock, in order, find the corresponding transaction either from the blocktxn message or from other sources and place it in the first available position in the block.<br />
# Once the block has been reconstructed, it shall be processed as normal, keeping in mind that short transaction IDs are expected to occasionally collide, and that nodes MUST NOT be penalized for such collisions, wherever they # appear.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
== Scripting ==<br />
<br />
See [[script]].<br />
<br />
==See Also==<br />
<br />
* [[Network]]<br />
* [[Protocol rules]]<br />
* [[Hardfork Wishlist]]<br />
* [https://bitcoin.org/en/developer-documentation Developer Documentation on bitcoin.org]<br />
* Bitcoin dissectors for Wireshark: https://github.com/lbotsch/wireshark-bitcoin https://github.com/op-sig/bitcoin-wireshark-dissector<br />
<br />
==References==<br />
<references /><br />
<br />
[[zh-cn:协议说明]]<br />
[[Category:Technical]]<br />
[[Category:Developer]]<br />
<br />
{{Bitcoin Core documentation}}</div>Tonikthttps://en.bitcoin.it/w/index.php?title=Protocol_documentation&diff=61494Protocol documentation2016-08-25T12:44:27Z<p>Tonikt: /* Short transaction IDs */</p>
<hr />
<div>This page ''describes'' the behavior of the [[Original Bitcoin client|reference client]]. The Bitcoin protocol is specified by the behavior of the reference client, not by this page. In particular, while this page is quite complete in describing the network protocol, it does not attempt to list all of the rules for block or transaction validity.<br />
<br />
Type names used in this documentation are from the C99 standard.<br />
<br />
For protocol used in mining, see [[getblocktemplate]].<br />
<br />
==Common standards==<br />
<br />
=== Hashes ===<br />
<br />
Usually, when a hash is computed within bitcoin, it is computed twice. Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-256] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when a shorter hash is desirable (for example when creating a bitcoin address).<br />
<br />
Example of double-SHA-256 encoding of string "hello":<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round of sha-256)<br />
9595c9df90075148eb06860365df33584b75bff782a510c6cd4883a419833d50 (second round of sha-256)<br />
<br />
For bitcoin addresses (RIPEMD-160) this would give:<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round is sha-256)<br />
b6a9c8c230722b7c748331a8b450f05566dc7d0f (with ripemd-160)<br />
<br />
=== Merkle Trees ===<br />
<br />
Merkle trees are binary trees of hashes. Merkle trees in bitcoin use a '''double''' SHA-256, the SHA-256 hash of the SHA-256 hash of something.<br />
<br />
If, when forming a row in the tree (other than the root of the tree), it would have an odd number of elements, the final double-hash is duplicated to ensure that the row has an even number of hashes.<br />
<br />
First form the bottom row of the tree with the ordered double-SHA-256 hashes of the byte streams of the transactions in the block.<br />
<br />
Then the row above it consists of half that number of hashes. Each entry is the double-SHA-256 of the 64-byte concatenation of the corresponding two hashes below it in the tree.<br />
<br />
This procedure repeats recursively until we reach a row consisting of just a single double-hash. This is the '''Merkle root''' of the tree.<br />
<br />
For example, imagine a block with three transactions ''a'', ''b'' and ''c''. The Merkle tree is: <br />
<br />
d1 = dhash(a)<br />
d2 = dhash(b)<br />
d3 = dhash(c)<br />
d4 = dhash(c) # a, b, c are 3. that's an odd number, so we take the c twice<br />
<br />
d5 = dhash(d1 concat d2)<br />
d6 = dhash(d3 concat d4)<br />
<br />
d7 = dhash(d5 concat d6)<br />
<br />
where<br />
<br />
dhash(a) = sha256(sha256(a))<br />
<br />
''d7'' is the Merkle root of the 3 transactions in this block.<br />
<br />
Note: Hashes in Merkle Tree displayed in the [[Block Explorer]] are of little-endian notation. For some implementations and [http://www.fileformat.info/tool/hash.htm calculations], the bits need to be reversed before they are hashed, and again after the hashing operation.<br />
<br />
=== Signatures ===<br />
<br />
Bitcoin uses [http://en.wikipedia.org/wiki/Elliptic_curve_cryptography Elliptic Curve] [http://en.wikipedia.org/wiki/Digital_Signature_Algorithm Digital Signature Algorithm] ([http://en.wikipedia.org/wiki/Elliptic_Curve_DSA ECDSA]) to sign transactions. <br />
<br />
For [[ECDSA]] the secp256k1 curve from http://www.secg.org/collateral/sec2_final.pdf is used.<br />
<br />
Public keys (in scripts) are given as 04 <x> <y> where ''x'' and ''y'' are 32 byte big-endian integers representing the coordinates of a point on the curve or in compressed form given as <sign> <x> where <sign> is 0x02 if ''y'' is even and 0x03 if ''y'' is odd.<br />
<br />
Signatures use [http://en.wikipedia.org/wiki/Distinguished_Encoding_Rules DER encoding] to pack the ''r'' and ''s'' components into a single byte stream (this is also what OpenSSL produces by default).<br />
<br />
=== Transaction Verification ===<br />
Transactions are cryptographically signed records that reassign ownership of Bitcoins to new addresses. Transactions have ''inputs'' - records which reference the funds from other previous transactions - and ''outputs'' - records which determine the new owner of the transferred Bitcoins, and which will be referenced as inputs in future transactions as those funds are respent.<br />
<br />
Each ''input'' must have a cryptographic digital signature that unlocks the funds from the prior transaction. Only the person possessing the appropriate [[private key]] is able to create a satisfactory signature; this in effect ensures that funds can only be spent by their owners.<br />
<br />
Each ''output'' determines which Bitcoin address (or other criteria, see [[Script]]) is the recipient of the funds.<br />
<br />
In a transaction, the sum of all inputs must be equal to or greater than the sum of all outputs. If the inputs exceed the outputs, the difference is considered a [[transaction fee]], and is redeemable by whoever first includes the transaction into the block chain.<br />
<br />
A special kind of transaction, called a [[coinbase transaction]], has no inputs. It is created by [[miners]], and there is one coinbase transaction per block. Because each block comes with a reward of newly created Bitcoins (e.g. 50 BTC for the first 210,000 blocks), the first transaction of a block is, with few exceptions, the transaction that grants those coins to their recipient (the miner). In addition to the newly created Bitcoins, the coinbase transaction is also used for assigning the recipient of any transaction fees that were paid within the other transactions being included in the same block. The coinbase transaction can assign the entire reward to a single Bitcoin address, or split it in portions among multiple addresses, just like any other transaction. Coinbase transactions always contain outputs totalling the sum of the block reward plus all transaction fees collected from the other transactions in the same block.<br />
<br />
The [[coinbase transaction]] in block zero cannot be spent. This is due to a quirk of the reference client implementation that would open the potential for a block chain fork if some nodes accepted the spend and others did not<ref>[http://bitcointalk.org/index.php?topic=119645.msg1288552#msg1288552 Block 0 Network Fork]</ref>.<br />
<br />
Most Bitcoin outputs encumber the newly transferred coins with a single ECDSA private key. The actual record saved with inputs and outputs isn't necessarily a key, but a ''script''. Bitcoin uses an interpreted scripting system to determine whether an output's criteria have been satisfied, with which more complex operations are possible, such as outputs that require two ECDSA signatures, or two-of-three-signature schemes. An output that references a single Bitcoin address is a ''typical'' output; an output actually contains this information in the form of a script that requires a single ECDSA signature (see [[OP_CHECKSIG]]). The output script specifies what must be provided to unlock the funds later, and when the time comes in the future to spend the transaction in another input, that input must provide all of the thing(s) that satisfy the requirements defined by the original output script.<br />
<br />
=== Addresses ===<br />
<br />
A bitcoin address is in fact the hash of a ECDSA public key, computed this way:<br />
<br />
Version = 1 byte of 0 (zero); on the test network, this is 1 byte of 111<br />
Key hash = Version concatenated with RIPEMD-160(SHA-256(public key))<br />
Checksum = 1st 4 bytes of SHA-256(SHA-256(Key hash))<br />
Bitcoin Address = Base58Encode(Key hash concatenated with Checksum)<br />
<br />
The Base58 encoding used is home made, and has some differences. Especially, leading zeroes are kept as single zeroes when conversion happens.<br />
<br />
== Common structures ==<br />
<br />
Almost all integers are encoded in little endian. Only IP or port number are encoded big endian.<br />
<br />
=== Message structure ===<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown<br />
|-<br />
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| 4 || length || uint32_t || Length of payload in number of bytes<br />
|-<br />
| 4 || checksum || uint32_t || First 4 bytes of sha256(sha256(payload))<br />
|-<br />
| ? || payload || uchar[] || The actual data<br />
|}<br />
<br />
<br />
Known magic values:<br />
<br />
{|class="wikitable"<br />
! Network !! Magic value !! Sent over wire as<br />
|-<br />
| main || 0xD9B4BEF9 || F9 BE B4 D9<br />
|-<br />
| testnet || 0xDAB5BFFA || FA BF B5 DA<br />
|-<br />
| testnet3 || 0x0709110B || 0B 11 09 07<br />
|-<br />
| namecoin || 0xFEB4BEF9 || F9 BE B4 FE<br />
|}<br />
<br />
=== Variable length integer ===<br />
<br />
Integer can be encoded depending on the represented value to save space.<br />
Variable length integers always precede an array/vector of a type of data that may vary in length.<br />
Longer numbers are encoded in little endian.<br />
<br />
{|class="wikitable"<br />
! Value !! Storage length !! Format<br />
|-<br />
| < 0xFD || 1 || uint8_t<br />
|-<br />
| <= 0xFFFF || 3 || 0xFD followed by the length as uint16_t<br />
|-<br />
| <= 0xFFFF FFFF || 5 || 0xFE followed by the length as uint32_t<br />
|-<br />
| - || 9 || 0xFF followed by the length as uint64_t<br />
|}<br />
<br />
If you're reading the Satoshi client code (BitcoinQT) it refers to this encoding as a "CompactSize". Modern BitcoinQT also has the CVarInt class which implements an even more compact integer for the purpose of local storage (which is incompatible with "CompactSize" described here). CVarInt is not a part of the protocol.<br />
<br />
=== Variable length string ===<br />
<br />
Variable length string can be stored using a variable length integer followed by the string itself.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the string<br />
|-<br />
| ? || string || char[] || The string itself (can be empty)<br />
|}<br />
<br />
=== Network address ===<br />
<br />
When a network address is needed somewhere, this structure is used. Network addresses are not prefixed with a timestamp in the version message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || time || uint32 || the Time (version >= 31402). '''Not present in version message.'''<br />
|-<br />
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]<br />
|-<br />
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The original client only supported IPv4 and only read the last 4 bytes to get the IPv4 address. However, the IPv4 address is written into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]<br />
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).<br />
|-<br />
| 2 || port || uint16_t || port number, network byte order<br />
|}<br />
<br />
Hexdump example of Network address structure<br />
<br />
<pre><br />
0000 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0010 00 00 FF FF 0A 00 00 01 20 8D ........ .<br />
<br />
Network address:<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK: see services listed under version command)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv6: ::ffff:a00:1 or IPv4: 10.0.0.1<br />
20 8D - Port 8333<br />
</pre><br />
<br />
=== Inventory Vectors ===<br />
<br />
Inventory vectors are used for notifying other nodes about objects they have or data which is being requested.<br />
<br />
Inventory vectors consist of the following data format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || type || uint32_t || Identifies the object type linked to this inventory<br />
|-<br />
| 32 || hash || char[32] || Hash of the object<br />
|}<br />
<br />
<br />
The object type is currently defined as one of the following possibilities:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0 || ERROR || Any data of with this number may be ignored<br />
|-<br />
| 1 || MSG_TX || Hash is related to a transaction<br />
|-<br />
| 2 || MSG_BLOCK || Hash is related to a data block<br />
|-<br />
| 3 || MSG_FILTERED_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a merkleblock message rather than a block message; this only works if a bloom filter has been set.<br />
|-<br />
| 4 || MSG_CMPCT_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a cmpctblock message. See BIP 152 for more info.<br />
|}<br />
<br />
Other Data Type values are considered reserved for future implementations.<br />
<br />
=== Block Headers ===<br />
<br />
Block headers are sent in a headers packet in response to a getheaders message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Will overflow in 2106<ref>https://en.wikipedia.org/wiki/Unix_time#Notable_events_in_Unix_time</ref>)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 1 || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries, this value is always 0<br />
|}<br />
<br />
cf. [[Block hashing algorithm]]<br />
<br />
=== PrefilledTransaction ===<br />
<br />
A PrefilledTransaction structure is used in HeaderAndShortIDs to provide a list of a few transactions explicitly.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| index || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1, 3 bytes || Compact Size, differentially encoded since the last PrefilledTransaction in a list || The index into the block at which this transaction is<br />
|-<br />
| tx || Transaction || variable || As encoded in [[Protocol_documentation#tx|tx messages]] || The transaction which is in the block at index index.<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== HeaderAndShortIDs ===<br />
<br />
A HeaderAndShortIDs structure is used to relay a block header, the short transactions IDs used for matching already-available transactions, and a select few transactions which we expect a peer may be missing.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| header || Block header || 80 bytes || First 80 bytes of the block as defined by the encoding used by "block" messages || The header of the block being provided<br />
|-<br />
| nonce || uint64_t || 8 bytes || Little Endian || A nonce for use in short transaction ID calculations<br />
|-<br />
| shortids_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of short transaction IDs in shortids (ie block tx count - prefilledtxn_length)<br />
|-<br />
| shortids || List of 6-byte integers || 6*shortids_length bytes || Little Endian || The short transaction IDs calculated from the transactions which were not provided explicitly in prefilledtxn<br />
|-<br />
| prefilledtxn_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of prefilled transactions in prefilledtxn (ie block tx count - shortids_length)<br />
|-<br />
| prefilledtxn || List of PrefilledTransactions || variable size*prefilledtxn_length || As defined by PrefilledTransaction definition, above || Used to provide the coinbase transaction and a select few which we expect a peer may be missing<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== BlockTransactionsRequest ===<br />
<br />
A BlockTransactionsRequest structure is used to list transaction indexes in a block being requested.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| blockhash || Binary blob || 32 bytes || The output from a double-SHA256 of the block header, as used elsewhere || The blockhash of the block which the transactions being requested are in<br />
|-<br />
| indexes_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of transactions being requested<br />
|-<br />
| indexes || List of CompactSizes || 1 or 3 bytes*indexes_length || Differentially encoded || The indexes of the transactions being requested in the block<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== BlockTransactions ===<br />
<br />
A BlockTransactions structure is used to provide some of the transactions in a block, as requested.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| blockhash || Binary blob || 32 bytes || The output from a double-SHA256 of the block header, as used elsewhere || The blockhash of the block which the transactions being provided are in<br />
|-<br />
| transactions_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of transactions provided<br />
|-<br />
| transactions || List of Transactions || variable || As encoded in "tx" messages || The transactions provided<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== Short transaction ID ===<br />
<br />
Short transaction IDs are used to represent a transaction without sending a full 256-bit hash. They are calculated by:<br />
<br />
# single-SHA256 hashing the block header with the nonce appended (in little-endian)<br />
# Running SipHash-2-4 with the input being the transaction ID and the keys (k0/k1) set to the first two little-endian 64-bit integers from the above hash, respectively.<br />
# Dropping the 2 most significant bytes from the SipHash output to make it 6 bytes.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
== Message types ==<br />
<br />
=== version ===<br />
<br />
When a node creates an outgoing connection, it will immediately [[Version Handshake|advertise]] its version. The remote node will respond with its version. No further communication is possible until both peers have exchanged their version.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Identifies protocol version being used by the node<br />
|-<br />
| 8 || services || uint64_t || bitfield of features to be enabled for this connection<br />
|-<br />
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds<br />
|-<br />
| 26 || addr_recv || [[#Network address|net_addr]] || The network address of the node receiving this message<br />
|-<br />
|colspan="4"| Fields below require version ≥ 106<br />
|-<br />
| 26 || addr_from || [[#Network address|net_addr]] || The network address of the node emitting this message<br />
|-<br />
| 8 || nonce || uint64_t || Node random nonce, randomly generated every time a version packet is sent. This nonce is used to detect connections to self.<br />
|-<br />
| ? || user_agent || [[#Variable length string|var_str]] || [https://github.com/bitcoin/bips/blob/master/bip-0014.mediawiki User Agent] (0x00 if string is 0 bytes long)<br />
|-<br />
| 4 || start_height || int32_t || The last block received by the emitting node<br />
|-<br />
|colspan="4"| Fields below require version ≥ 70001<br />
|-<br />
| 1 || relay || bool || Whether the remote peer should announce relayed transactions or not, see [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037]<br />
|}<br />
<br />
A "verack" packet shall be sent if the version packet was accepted.<br />
<br />
The following services are currently assigned:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 1 || NODE_NETWORK || This node can be asked for full blocks instead of just headers.<br />
|}<br />
<br />
Hexdump example of version message (OBSOLETE EXAMPLE: This example lacks a checksum and user-agent):<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....<br />
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........<br />
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............<br />
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................<br />
0040 20 8D 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,<br />
0060 3A B4 57 13 00 55 81 01 00 :.W..U...<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
55 00 00 00 - Payload is 85 bytes long<br />
- No checksum in version message until 20 February 2012. See https://bitcointalk.org/index.php?topic=55852.0<br />
Version message:<br />
9C 7C 00 00 - 31900 (version 0.3.19)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
E6 15 10 4D 00 00 00 00 - Mon Dec 20 21:50:14 EST 2010<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 20 8D - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D - Sender address info - see Network Address<br />
DD 9D 20 2C 3A B4 57 13 - Node random unique ID<br />
00 - "" sub-version string (string is 0 bytes long)<br />
55 81 01 00 - Last block sending node has is block #98645<br />
</pre><br />
<br />
And here's a modern (60002) protocol version client advertising itself to a local peer...<br />
<br />
Newer protocol includes the checksum now, this is from a mainline (satoshi) client during <br />
an outgoing connection to another local client, notice that it does not fill out the <br />
address information at all when the source or destination is "unroutable".<br />
<br />
<pre><br />
<br />
0000 f9 be b4 d9 76 65 72 73 69 6f 6e 00 00 00 00 00 ....version.....<br />
0010 64 00 00 00 35 8d 49 32 62 ea 00 00 01 00 00 00 d...5.I2b.......<br />
0020 00 00 00 00 11 b2 d0 50 00 00 00 00 01 00 00 00 .......P........<br />
0030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ff ff ................<br />
0040 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 00 00 00 00 ff ff 00 00 00 00 00 00 ................<br />
0060 3b 2e b3 5d 8c e6 17 65 0f 2f 53 61 74 6f 73 68 ;..]...e./Satosh<br />
0070 69 3a 30 2e 37 2e 32 2f c0 3e 03 00 i:0.7.2/.>..<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
64 00 00 00 - Payload is 100 bytes long<br />
3B 64 8D 5A - payload checksum<br />
<br />
Version message:<br />
62 EA 00 00 - 60002 (protocol version 60002)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
11 B2 D0 50 00 00 00 00 - Tue Dec 18 10:12:33 PST 2012<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Sender address info - see Network Address<br />
3B 2E B3 5D 8C E6 17 65 - Node ID<br />
0F 2F 53 61 74 6F 73 68 69 3A 30 2E 37 2E 32 2F - "/Satoshi:0.7.2/" sub-version string (string is 15 bytes long)<br />
C0 3E 03 00 - Last block sending node has is block #212672<br />
</pre><br />
<br />
=== verack ===<br />
<br />
The ''verack'' message is sent in reply to ''[[#version|version]]''. This message consists of only a [[#Message structure|message header]] with the command string "verack".<br />
<br />
Hexdump of the verack message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......<br />
0010 00 00 00 00 5D F6 E0 E2 ........<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 61 63 6B 00 00 00 00 00 00 - "verack" command<br />
00 00 00 00 - Payload is 0 bytes long<br />
5D F6 E0 E2 - Checksum<br />
</pre><br />
<br />
=== addr ===<br />
<br />
Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours<br />
<br />
Payload:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of address entries (max: 1000)<br />
|-<br />
| 30x? || addr_list || (uint32_t + [[#Network address|net_addr]])[] || Address of other nodes on the network. version < 209 will only read the first one. The uint32_t is a timestamp (see note below).<br />
|}<br />
<br />
'''Note''': Starting version 31402, addresses are prefixed with a timestamp. If no timestamp is present, the addresses should not be relayed to other peers, unless it is indeed confirmed they are up.<br />
<br />
Hexdump example of ''addr'' message:<br />
<pre><br />
0000 F9 BE B4 D9 61 64 64 72 00 00 00 00 00 00 00 00 ....addr........<br />
0010 1F 00 00 00 ED 52 39 9B 01 E2 15 10 4D 01 00 00 .....R9.....M...<br />
0020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF ................<br />
0030 FF 0A 00 00 01 20 8D ..... .<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
61 64 64 72 00 00 00 00 00 00 00 00 - "addr"<br />
1F 00 00 00 - payload is 31 bytes long<br />
ED 52 39 9B - checksum of payload<br />
<br />
Payload:<br />
01 - 1 address in this message<br />
<br />
Address:<br />
E2 15 10 4D - Mon Dec 20 21:50:10 EST 2010 (only when version is >= 31402)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK service - see version message)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv4: 10.0.0.1, IPv6: ::ffff:10.0.0.1 (IPv4-mapped IPv6 address)<br />
20 8D - port 8333<br />
</pre><br />
<br />
=== inv ===<br />
<br />
Allows a node to advertise its knowledge of one or more objects. It can be received unsolicited, or in reply to ''getblocks''.<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getdata ===<br />
<br />
getdata is used in response to inv, to retrieve the content of a specific object, and is usually sent after receiving an ''inv'' packet, after filtering known elements. It can be used to retrieve transactions, but only if they are in the memory pool or relay set - arbitrary access to transactions in the chain is not allowed to avoid having clients start to depend on nodes having full transaction indexes (which modern nodes do not).<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== notfound ===<br />
<br />
notfound is a response to a getdata, sent if any requested data items could not be relayed, for example, because the requested transaction was not in the memory pool or relay set.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getblocks ===<br />
<br />
Return an ''inv'' packet containing the list of blocks starting right after the last known hash in the block locator object, up to hash_stop or 500 blocks, whichever comes first. <br />
<br />
The locator hashes are processed by a node in the order as they appear in the message. If a block hash is found in the node's main chain, the list of its children is returned back via the ''inv'' message and the remaining locators are ignored, no matter if the requested limit was reached, or not.<br />
<br />
To receive the next blocks hashes, one needs to issue getblocks again with a new block locator object. Keep in mind that some clients may provide blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block; set to zero to get as many blocks as possible (500)<br />
|}<br />
<br />
To create the block locator hashes, keep pushing hashes until you go back to the genesis block. After pushing 10 hashes back, the step backwards doubles every loop:<br />
<br />
<pre><br />
// From libbitcoin which is under AGPL<br />
std::vector<size_t> block_locator_indexes(size_t top_height)<br />
{<br />
std::vector<size_t> indexes;<br />
<br />
// Modify the step in the iteration.<br />
int64_t step = 1;<br />
<br />
// Start at the top of the chain and work backwards.<br />
for (auto index = (int64_t)top_height; index > 0; index -= step)<br />
{<br />
// Push top 10 indexes first, then back off exponentially.<br />
if (indexes.size() >= 10)<br />
step *= 2;<br />
<br />
indexes.push_back((size_t)index);<br />
}<br />
<br />
// Push the genesis block index.<br />
indexes.push_back(0);<br />
return indexes;<br />
}<br />
</pre><br />
<br />
Note that it is allowed to send in fewer known hashes down to a minimum of just one hash. However, the purpose of the block locator object is to detect a wrong branch in the caller's main chain. If the peer detects that you are off the main chain, it will send in block hashes which are earlier than your last known block. So if you just send in your last known hash and it is off the main chain, the peer starts over at block #1.<br />
<br />
=== getheaders ===<br />
<br />
Return a ''headers'' packet containing the headers of blocks starting right after the last known hash in the block locator object, up to hash_stop or 2000 blocks, whichever comes first. To receive the next block headers, one needs to issue getheaders again with a new block locator object. The ''getheaders'' command is used by thin clients to quickly download the block chain where the contents of the transactions would be irrelevant (because they are not ours). Keep in mind that some clients may provide headers of blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block header; set to zero to get as many blocks as possible (2000)<br />
|}<br />
<br />
For the block locator object in this packet, the same rules apply as for the [[Protocol_documentation#getblocks|getblocks]] packet.<br />
<br />
=== tx ===<br />
<br />
''tx'' describes a bitcoin transaction, in reply to ''[[#getdata|getdata]]''<br />
<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Transaction data format version (note, this is signed)<br />
|-<br />
| 1+ || tx_in count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction inputs<br />
|-<br />
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins<br />
|-<br />
| 1+ || tx_out count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction outputs<br />
|-<br />
| 9+ || tx_out || tx_out[] || A list of 1 or more transaction outputs or destinations for coins<br />
|-<br />
| 4 || lock_time || uint32_t || The block number or timestamp at which this transaction is locked:<br />
{|class="wikitable"<br />
! Value !! Description<br />
|-<br />
| 0 || Not locked<br />
|-<br />
| < 500000000 || Block number at which this transaction is locked<br />
|-<br />
| >= 500000000 || UNIX timestamp at which this transaction is locked<br />
|}<br />
If all TxIn inputs have final (0xffffffff) sequence numbers then lock_time is irrelevant. Otherwise, the transaction may not be added to a block until after lock_time (see [[NLockTime]]).<br />
<br />
|}<br />
<br />
TxIn consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 36 || previous_output || outpoint || The previous output transaction reference, as an OutPoint structure<br />
|-<br />
| 1+ || script length || [[Protocol_documentation#Variable_length_integer|var_int]] || The length of the signature script<br />
|-<br />
| ? || signature script || uchar[] || Computational Script for confirming transaction authorization<br />
|-<br />
| 4 || [http://bitcoin.stackexchange.com/q/2025/323 sequence] || uint32_t || Transaction version as defined by the sender. Intended for "replacement" of transactions when information is updated before inclusion into a block.<br />
|}<br />
<br />
The OutPoint structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 32 || hash || char[32] || The hash of the referenced transaction.<br />
|-<br />
| 4 || index || uint32_t || The index of the specific output in the transaction. The first output is 0, etc.<br />
|}<br />
<br />
The Script structure consists of a series of pieces of information and operations related to the value of the transaction.<br />
<br />
(Structure to be expanded in the future… see script.h and script.cpp and [[Script]] for more information)<br />
<br />
The TxOut structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || value || int64_t || Transaction Value<br />
|-<br />
| 1+ || pk_script length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the pk_script<br />
|-<br />
| ? || pk_script || uchar[] || Usually contains the public key as a Bitcoin script setting up conditions to claim this output.<br />
|}<br />
<br />
Example ''tx'' message:<br />
<pre><br />
000000 F9 BE B4 D9 74 78 00 00 00 00 00 00 00 00 00 00 ....tx..........<br />
000010 02 01 00 00 E2 93 CD BE 01 00 00 00 01 6D BD DB .............m..<br />
000020 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D 12 66 E9 .[...Q........f.<br />
000030 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29 00 00 00 .;P......j.6)...<br />
000040 00 8B 48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 ..H0E.!..X..r...<br />
000050 C7 36 7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A .6zz%;..R#...h.:<br />
000060 59 23 3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 Y#?E.W... Y.....<br />
000070 0E 41 83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D .A.z.X.z...XN...<br />
000080 35 BD 96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF 5...6..;...A....<br />
000090 C9 7E F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 .~.6.m...@..!...<br />
0000A0 2A CD 2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC *.+..].}Y... ...<br />
0000B0 4E 02 53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F N.S..=7.o...Q...<br />
0000C0 14 04 2F 46 61 4A 4C 70 C0 F1 4B EF F5 FF FF FF ../FaJLp..K.....<br />
0000D0 FF 02 40 4B 4C 00 00 00 00 00 19 76 A9 14 1A A0 ..@KL......v....<br />
0000E0 CD 1C BE A6 E7 45 8A 7A BA D5 12 A9 D9 EA 1A FB .....E.z........<br />
0000F0 22 5E 88 AC 80 FA E9 C7 00 00 00 00 19 76 A9 14 "^...........v..<br />
000100 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E FD A0 B7 ..[.Cj.....H^...<br />
000110 8B 4E CC 52 88 AC 00 00 00 00 .N.R......<br />
<br />
<br />
Message header:<br />
F9 BE B4 D9 - main network magic bytes<br />
74 78 00 00 00 00 00 00 00 00 00 00 - "tx" command<br />
02 01 00 00 - payload is 258 bytes long<br />
E2 93 CD BE - checksum of payload<br />
<br />
Transaction:<br />
01 00 00 00 - version<br />
<br />
Inputs:<br />
01 - number of transaction inputs<br />
<br />
Input 1:<br />
6D BD DB 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D - previous output (outpoint)<br />
12 66 E9 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29<br />
00 00 00 00<br />
<br />
8B - script is 139 bytes long<br />
<br />
48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 C7 36 - signature script (scriptSig)<br />
7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A 59 23<br />
3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 0E 41<br />
83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D 35 BD<br />
96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF C9 7E<br />
F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 2A CD<br />
2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC 4E 02<br />
53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F 14 04<br />
2F 46 61 4A 4C 70 C0 F1 4B EF F5<br />
<br />
FF FF FF FF - sequence<br />
<br />
Outputs:<br />
02 - 2 Output Transactions<br />
<br />
Output 1:<br />
40 4B 4C 00 00 00 00 00 - 0.05 BTC (5000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 1A A0 CD 1C BE A6 E7 45 8A 7A BA D5 12 - pk_script<br />
A9 D9 EA 1A FB 22 5E 88 AC<br />
<br />
Output 2:<br />
80 FA E9 C7 00 00 00 00 - 33.54 BTC (3354000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E - pk_script<br />
FD A0 B7 8B 4E CC 52 88 AC<br />
<br />
Locktime:<br />
00 00 00 00 - lock time<br />
</pre><br />
<br />
=== block ===<br />
<br />
The '''block''' message is sent in response to a getdata message which requests transaction information from a block hash.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A Unix timestamp recording when this block was created (Currently limited to dates before the year 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated [[Difficulty|difficulty target]] being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| ? || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries<br />
|-<br />
| ? || txns || tx[] || Block transactions, in format of "tx" command<br />
|}<br />
<br />
The SHA256 hash that identifies each block (and which must have a run of 0 bits) is calculated from the first 6 fields of this structure (version, prev_block, merkle_root, timestamp, bits, nonce, and standard SHA256 padding, making two 64-byte chunks in all) and ''not'' from the complete block. To calculate the hash, only two chunks need to be processed by the SHA256 algorithm. Since the ''nonce'' field is in the second chunk, the first chunk stays constant during mining and therefore only the second chunk needs to be processed. However, a Bitcoin hash is the hash of the hash, so two SHA256 rounds are needed for each mining iteration.<br />
See [[Block hashing algorithm]] for details and an example.<br />
<br />
=== headers ===<br />
<br />
The ''headers'' packet returns block headers in response to a ''getheaders'' packet. <br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of block headers<br />
|-<br />
| 81x? || headers || [[Protocol_documentation#Block_Headers|block_header]][] || [[Protocol_documentation#Block_Headers|Block headers]]<br />
|}<br />
<br />
Note that the block headers in this packet include a transaction count (a var_int, so there can be more than 81 bytes per header) as opposed to the block headers that are hashed by miners.<br />
<br />
=== getaddr ===<br />
<br />
The getaddr message sends a request to a node asking for information about known active peers to help with finding potential nodes in the network. The response to receiving this message is to transmit one or more addr messages with one or more peers from a database of known active peers. The typical presumption is that a node is likely to be active if it has been sending a message within the last three hours.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
=== mempool ===<br />
<br />
The mempool message sends a request to a node asking for information about transactions it has verified but which have not yet confirmed. The response to receiving this message is an inv message containing the transaction hashes for all the transactions in the node's mempool.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
It is specified in [https://github.com/bitcoin/bips/blob/master/bip-0035.mediawiki BIP 35]. Since [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 37], if a [[Protocol_documentation#filterload.2C_filteradd.2C_filterclear.2C_merkleblock|bloom filter]] is loaded, only transactions matching the filter are replied.<br />
<br />
=== checkorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== submitorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== reply ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== ping ===<br />
<br />
The ''ping'' message is sent primarily to confirm that the TCP/IP connection is still valid. An error in transmission is presumed to be a closed connection and the address is removed as a current peer.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || random nonce<br />
|}<br />
<br />
=== pong ===<br />
<br />
The ''pong'' message is sent in response to a ''ping'' message. In modern protocol versions, a ''pong'' response is generated using a nonce included in the ping.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || nonce from ping<br />
|}<br />
<br />
<br />
=== reject===<br />
<br />
The ''reject'' message is sent when messages are rejected.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || message || var_str || type of message rejected<br />
|-<br />
| 1 || ccode || char || code relating to rejected message<br />
|-<br />
| 1+ || reason || var_str || text version of reason for rejection<br />
|-<br />
| 0+ || data || char || Optional extra data provided by some errors. Currently, all errors which provide this field fill it with the TXID or block header hash of the object being rejected, so the field is 32 bytes.<br />
|}<br />
<br />
CCodes<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0x01 || REJECT_MALFORMED|| <br />
|-<br />
| 0x10 || REJECT_INVALID ||<br />
|-<br />
| 0x11 || REJECT_OBSOLETE ||<br />
|-<br />
| 0x12 || REJECT_DUPLICATE ||<br />
|-<br />
| 0x40 || REJECT_NONSTANDARD ||<br />
|-<br />
| 0x41 || REJECT_DUST ||<br />
|-<br />
| 0x42 || REJECT_INSUFFICIENTFEE ||<br />
|-<br />
| 0x43 || REJECT_CHECKPOINT ||<br />
|}<br />
<br />
=== filterload, filteradd, filterclear, merkleblock ===<br />
<br />
These messages are related to Bloom filtering of connections and are defined in [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037].<br />
<br />
<br />
The <code>filterload</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || filter || uint8_t[] || The filter itself is simply a bit field of arbitrary byte-aligned size. The maximum size is 36,000 bytes.<br />
|-<br />
| 4 || nHashFuncs || uint32_t || The number of hash functions to use in this filter. The maximum value allowed in this field is 50.<br />
|-<br />
| 4 || nTweak || uint32_t || A random value to add to the seed value in the hash function used by the bloom filter.<br />
|-<br />
| 1 || nFlags || uint8_t || A set of flags that control how matched items are added to the filter.<br />
|}<br />
<br />
See below for a description of the Bloom filter algorithm and how to select nHashFuncs and filter size for a desired false positive rate.<br />
<br />
Upon receiving a <code>filterload</code> command, the remote peer will immediately restrict the broadcast transactions it announces (in inv packets) to transactions matching the filter, where the matching algorithm is specified below. The flags control the update behaviour of the matching algorithm.<br />
<br />
The <code>filteradd</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || data || uint8_t[] || The data element to add to the current filter.<br />
|}<br />
<br />
The data field must be smaller than or equal to 520 bytes in size (the maximum size of any potentially matched object).<br />
<br />
The given data element will be added to the Bloom filter. A filter must have been previously provided using <code>filterload</code>. This command is useful if a new key or script is added to a clients wallet whilst it has connections to the network open, it avoids the need to re-calculate and send an entirely new filter to every peer (though doing so is usually advisable to maintain anonymity).<br />
<br />
The <code>filterclear</code> command has no arguments at all.<br />
<br />
After a filter has been set, nodes don't merely stop announcing non-matching transactions, they can also serve filtered blocks. A filtered block is defined by the <code>merkleblock</code> message and is defined like this:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information, based upon the software version creating this block (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Limited to 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 4 || total_transactions || uint32_t || Number of transactions in the block (including unmatched ones)<br />
|-<br />
| ? || hashes || uint256[] || hashes in depth-first order (including standard varint size prefix)<br />
|-<br />
| ? || flags || byte[] || flag bits, packed per 8 in a byte, least significant bit first (including standard varint size prefix)<br />
|}<br />
<br />
=== alert ===<br />
<br />
An '''alert''' is sent between nodes to send a general notification message throughout the network. If the alert can be confirmed with the signature as having come from the core development group of the Bitcoin software, the message is suggested to be displayed for end-users. Attempts to perform transactions, particularly automated transactions through the client, are suggested to be halted. The text in the Message string should be relayed to log files and any user interfaces.<br />
<br />
Alert format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || payload || uchar[] || Serialized alert payload<br />
|-<br />
| ? || signature || uchar[] || An ECDSA signature of the message<br />
|}<br />
<br />
The developers of Satoshi's client use this public key for signing alerts:<br />
04fc9702847840aaf195de8442ebecedf5b095cdbb9bc716bda9110971b28a49e0ead8564ff0db22209e0374782c093bb899692d524e9d6a6956e7c5ecbcd68284<br />
(hash) 1AGRxqDa5WjUKBwHB9XYEjmkv1ucoUUy1s<br />
<br />
The payload is serialized into a uchar[] to ensure that versions using incompatible alert formats can still relay alerts among one another. The current alert payload format is:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || Version || int32_t || Alert format version<br />
|-<br />
| 8 || RelayUntil || int64_t || The timestamp beyond which nodes should stop relaying this alert<br />
|-<br />
| 8 || Expiration || int64_t || The timestamp beyond which this alert is no longer in effect and should be ignored<br />
|-<br />
| 4 || ID || int32_t || A unique ID number for this alert<br />
|-<br />
| 4 || Cancel || int32_t || All alerts with an ID number less than or equal to this number should be cancelled: deleted and not accepted in the future<br />
|-<br />
| ? || setCancel || set<int32_t> || All alert IDs contained in this set should be cancelled as above<br />
|-<br />
| 4 || MinVer || int32_t || This alert only applies to versions greater than or equal to this version. Other versions should still relay it.<br />
|-<br />
| 4 || MaxVer || int32_t || This alert only applies to versions less than or equal to this version. Other versions should still relay it.<br />
|-<br />
| ? || setSubVer || set<string> || If this set contains any elements, then only nodes that have their subVer contained in this set are affected by the alert. Other versions should still relay it.<br />
|-<br />
| 4 || Priority || int32_t || Relative priority compared to other alerts<br />
|-<br />
| ? || Comment || string || A comment on the alert that is not displayed<br />
|-<br />
| ? || StatusBar || string || The alert message that is displayed to the user<br />
|-<br />
| ? || Reserved || string || Reserved<br />
|}<br />
<br />
Note: '''set<''type''>''' in the table above is a [[#Variable length integer | variable length integer]] followed by the number of fields of the given ''type'' (either int32_t or [[#Variable length string | variable length string]])<br />
<br />
Sample alert (no message header):<br />
73010000003766404f00000000b305434f00000000f2030000f1030000001027000048ee0000<br />
0064000000004653656520626974636f696e2e6f72672f666562323020696620796f75206861<br />
76652074726f75626c6520636f6e6e656374696e672061667465722032302046656272756172<br />
79004730450221008389df45f0703f39ec8c1cc42c13810ffcae14995bb648340219e353b63b<br />
53eb022009ec65e1c1aaeec1fd334c6b684bde2b3f573060d5b70c3a46723326e4e8a4f1<br />
<br />
Version: 1<br />
RelayUntil: 1329620535<br />
Expiration: 1329792435<br />
ID: 1010<br />
Cancel: 1009<br />
setCancel: <empty><br />
MinVer: 10000<br />
MaxVer: 61000<br />
setSubVer: <empty><br />
Priority: 100<br />
Comment: <empty><br />
StatusBar: "See bitcoin.org/feb20 if you have trouble connecting after 20 February"<br />
Reserved: <empty><br />
<br />
=== sendheaders ===<br />
<br />
Request for Direct headers announcement. <br />
<br />
Upon receipt of this message, the node is be permitted, but not required, to announce new blocks by '''headers''' command (instead of '''inv''' command).<br />
<br />
This message is supported by the protocol version >= 70012 or Bitcoin Core version >= 0.12.0.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0130.mediawiki BIP 130] for more information.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
<br />
=== feefilter ===<br />
<br />
The payload is always 8 bytes long and it encodes 64 bit integer value (LSB / little endian) of '''feerate'''.<br />
The value represents a minimal fee and is expressed in satoshis per 1000 bytes.<br />
<br />
Upon receipt of a "feefilter" message, the node will be permitted, but not required, to filter transaction invs for transactions that fall below the feerate provided in the feefilter message interpreted as satoshis per kilobyte.<br />
<br />
The fee filter is additive with a bloom filter for transactions so if an SPV client were to load a bloom filter and send a feefilter message, transactions would only be relayed if they passed both filters.<br />
<br />
Inv's generated from a mempool message are also subject to a fee filter if it exists.<br />
<br />
Feature discovery is enabled by checking protocol version >= 70013<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0133.mediawiki BIP 133] for more information.<br />
<br />
=== sendcmpct ===<br />
<br />
# The sendcmpct message is defined as a message containing a 1-byte integer followed by a 8-byte integer where pchCommand == "sendcmpct".<br />
# The first integer SHALL be interpreted as a boolean (and MUST have a value of either 1 or 0)<br />
# The second integer SHALL be interpreted as a little-endian version number. Nodes sending a sendcmpct message MUST currently set this value to 1.<br />
# Upon receipt of a "sendcmpct" message with the first and second integers set to 1, the node SHOULD announce new blocks by sending a cmpctblock message.<br />
# Upon receipt of a "sendcmpct" message with the first integer set to 0, the node SHOULD NOT announce new blocks by sending a cmpctblock message, but SHOULD announce new blocks by sending invs or headers, as defined by BIP130.<br />
# Upon receipt of a "sendcmpct" message with the second integer set to something other than 1, nodes MUST treat the peer as if they had not received the message (as it indicates the peer will provide an unexpected encoding in <br />
# cmpctblock, and/or other, messages). This allows future versions to send duplicate sendcmpct messages with different versions as a part of a version handshake for future versions.<br />
# Nodes SHOULD check for a protocol version of >= 70014 before sending sendcmpct messages.<br />
# Nodes MUST NOT send a request for a MSG_CMPCT_BLOCK object to a peer before having received a sendcmpct message from that peer.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== cmpctblock ===<br />
<br />
# The cmpctblock message is defined as as a message containing a serialized HeaderAndShortIDs message and pchCommand == "cmpctblock".<br />
# Upon receipt of a cmpctblock message after sending a sendcmpct message, nodes SHOULD calculate the short transaction ID for each unconfirmed transaction they have available (ie in their mempool) and compare each to each short transaction ID in the cmpctblock message.<br />
# After finding already-available transactions, nodes which do not have all transactions available to reconstruct the full block SHOULD request the missing transactions using a getblocktxn message.<br />
# A node MUST NOT send a cmpctblock message unless they are able to respond to a getblocktxn message which requests every transaction in the block.<br />
# A node MUST NOT send a cmpctblock message without having validated that the header properly commits to each transaction in the block, and properly builds on top of the existing chain with a valid proof-of-work. A node MAY send a cmpctblock before validating that each transaction in the block validly spends existing UTXO set entries.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== getblocktxn ===<br />
<br />
# The getblocktxn message is defined as as a message containing a serialized BlockTransactionsRequest message and pchCommand == "getblocktxn".<br />
# Upon receipt of a properly-formatted getblocktxnmessage, nodes which recently provided the sender of such a message a cmpctblock for the block hash identified in this message MUST respond with an appropriate blocktxn message. Such a blocktxn message MUST contain exactly and only each transaction which is present in the appropriate block at the index specified in the getblocktxn indexes list, in the order requested.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== blocktxn ===<br />
<br />
# The blocktxn message is defined as as a message containing a serialized BlockTransactions message and pchCommand == "blocktxn".<br />
# Upon receipt of a properly-formatted requested blocktxn message, nodes SHOULD attempt to reconstruct the full block by:<br />
# Taking the prefilledtxn transactions from the original cmpctblock and placing them in the marked positions.<br />
# For each short transaction ID from the original cmpctblock, in order, find the corresponding transaction either from the blocktxn message or from other sources and place it in the first available position in the block.<br />
# Once the block has been reconstructed, it shall be processed as normal, keeping in mind that short transaction IDs are expected to occasionally collide, and that nodes MUST NOT be penalized for such collisions, wherever they # appear.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
== Scripting ==<br />
<br />
See [[script]].<br />
<br />
==See Also==<br />
<br />
* [[Network]]<br />
* [[Protocol rules]]<br />
* [[Hardfork Wishlist]]<br />
* [https://bitcoin.org/en/developer-documentation Developer Documentation on bitcoin.org]<br />
* Bitcoin dissectors for Wireshark: https://github.com/lbotsch/wireshark-bitcoin https://github.com/op-sig/bitcoin-wireshark-dissector<br />
<br />
==References==<br />
<references /><br />
<br />
[[zh-cn:协议说明]]<br />
[[Category:Technical]]<br />
[[Category:Developer]]<br />
<br />
{{Bitcoin Core documentation}}</div>Tonikthttps://en.bitcoin.it/w/index.php?title=Protocol_documentation&diff=61493Protocol documentation2016-08-25T12:43:53Z<p>Tonikt: /* PrefilledTransaction */</p>
<hr />
<div>This page ''describes'' the behavior of the [[Original Bitcoin client|reference client]]. The Bitcoin protocol is specified by the behavior of the reference client, not by this page. In particular, while this page is quite complete in describing the network protocol, it does not attempt to list all of the rules for block or transaction validity.<br />
<br />
Type names used in this documentation are from the C99 standard.<br />
<br />
For protocol used in mining, see [[getblocktemplate]].<br />
<br />
==Common standards==<br />
<br />
=== Hashes ===<br />
<br />
Usually, when a hash is computed within bitcoin, it is computed twice. Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-256] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when a shorter hash is desirable (for example when creating a bitcoin address).<br />
<br />
Example of double-SHA-256 encoding of string "hello":<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round of sha-256)<br />
9595c9df90075148eb06860365df33584b75bff782a510c6cd4883a419833d50 (second round of sha-256)<br />
<br />
For bitcoin addresses (RIPEMD-160) this would give:<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round is sha-256)<br />
b6a9c8c230722b7c748331a8b450f05566dc7d0f (with ripemd-160)<br />
<br />
=== Merkle Trees ===<br />
<br />
Merkle trees are binary trees of hashes. Merkle trees in bitcoin use a '''double''' SHA-256, the SHA-256 hash of the SHA-256 hash of something.<br />
<br />
If, when forming a row in the tree (other than the root of the tree), it would have an odd number of elements, the final double-hash is duplicated to ensure that the row has an even number of hashes.<br />
<br />
First form the bottom row of the tree with the ordered double-SHA-256 hashes of the byte streams of the transactions in the block.<br />
<br />
Then the row above it consists of half that number of hashes. Each entry is the double-SHA-256 of the 64-byte concatenation of the corresponding two hashes below it in the tree.<br />
<br />
This procedure repeats recursively until we reach a row consisting of just a single double-hash. This is the '''Merkle root''' of the tree.<br />
<br />
For example, imagine a block with three transactions ''a'', ''b'' and ''c''. The Merkle tree is: <br />
<br />
d1 = dhash(a)<br />
d2 = dhash(b)<br />
d3 = dhash(c)<br />
d4 = dhash(c) # a, b, c are 3. that's an odd number, so we take the c twice<br />
<br />
d5 = dhash(d1 concat d2)<br />
d6 = dhash(d3 concat d4)<br />
<br />
d7 = dhash(d5 concat d6)<br />
<br />
where<br />
<br />
dhash(a) = sha256(sha256(a))<br />
<br />
''d7'' is the Merkle root of the 3 transactions in this block.<br />
<br />
Note: Hashes in Merkle Tree displayed in the [[Block Explorer]] are of little-endian notation. For some implementations and [http://www.fileformat.info/tool/hash.htm calculations], the bits need to be reversed before they are hashed, and again after the hashing operation.<br />
<br />
=== Signatures ===<br />
<br />
Bitcoin uses [http://en.wikipedia.org/wiki/Elliptic_curve_cryptography Elliptic Curve] [http://en.wikipedia.org/wiki/Digital_Signature_Algorithm Digital Signature Algorithm] ([http://en.wikipedia.org/wiki/Elliptic_Curve_DSA ECDSA]) to sign transactions. <br />
<br />
For [[ECDSA]] the secp256k1 curve from http://www.secg.org/collateral/sec2_final.pdf is used.<br />
<br />
Public keys (in scripts) are given as 04 <x> <y> where ''x'' and ''y'' are 32 byte big-endian integers representing the coordinates of a point on the curve or in compressed form given as <sign> <x> where <sign> is 0x02 if ''y'' is even and 0x03 if ''y'' is odd.<br />
<br />
Signatures use [http://en.wikipedia.org/wiki/Distinguished_Encoding_Rules DER encoding] to pack the ''r'' and ''s'' components into a single byte stream (this is also what OpenSSL produces by default).<br />
<br />
=== Transaction Verification ===<br />
Transactions are cryptographically signed records that reassign ownership of Bitcoins to new addresses. Transactions have ''inputs'' - records which reference the funds from other previous transactions - and ''outputs'' - records which determine the new owner of the transferred Bitcoins, and which will be referenced as inputs in future transactions as those funds are respent.<br />
<br />
Each ''input'' must have a cryptographic digital signature that unlocks the funds from the prior transaction. Only the person possessing the appropriate [[private key]] is able to create a satisfactory signature; this in effect ensures that funds can only be spent by their owners.<br />
<br />
Each ''output'' determines which Bitcoin address (or other criteria, see [[Script]]) is the recipient of the funds.<br />
<br />
In a transaction, the sum of all inputs must be equal to or greater than the sum of all outputs. If the inputs exceed the outputs, the difference is considered a [[transaction fee]], and is redeemable by whoever first includes the transaction into the block chain.<br />
<br />
A special kind of transaction, called a [[coinbase transaction]], has no inputs. It is created by [[miners]], and there is one coinbase transaction per block. Because each block comes with a reward of newly created Bitcoins (e.g. 50 BTC for the first 210,000 blocks), the first transaction of a block is, with few exceptions, the transaction that grants those coins to their recipient (the miner). In addition to the newly created Bitcoins, the coinbase transaction is also used for assigning the recipient of any transaction fees that were paid within the other transactions being included in the same block. The coinbase transaction can assign the entire reward to a single Bitcoin address, or split it in portions among multiple addresses, just like any other transaction. Coinbase transactions always contain outputs totalling the sum of the block reward plus all transaction fees collected from the other transactions in the same block.<br />
<br />
The [[coinbase transaction]] in block zero cannot be spent. This is due to a quirk of the reference client implementation that would open the potential for a block chain fork if some nodes accepted the spend and others did not<ref>[http://bitcointalk.org/index.php?topic=119645.msg1288552#msg1288552 Block 0 Network Fork]</ref>.<br />
<br />
Most Bitcoin outputs encumber the newly transferred coins with a single ECDSA private key. The actual record saved with inputs and outputs isn't necessarily a key, but a ''script''. Bitcoin uses an interpreted scripting system to determine whether an output's criteria have been satisfied, with which more complex operations are possible, such as outputs that require two ECDSA signatures, or two-of-three-signature schemes. An output that references a single Bitcoin address is a ''typical'' output; an output actually contains this information in the form of a script that requires a single ECDSA signature (see [[OP_CHECKSIG]]). The output script specifies what must be provided to unlock the funds later, and when the time comes in the future to spend the transaction in another input, that input must provide all of the thing(s) that satisfy the requirements defined by the original output script.<br />
<br />
=== Addresses ===<br />
<br />
A bitcoin address is in fact the hash of a ECDSA public key, computed this way:<br />
<br />
Version = 1 byte of 0 (zero); on the test network, this is 1 byte of 111<br />
Key hash = Version concatenated with RIPEMD-160(SHA-256(public key))<br />
Checksum = 1st 4 bytes of SHA-256(SHA-256(Key hash))<br />
Bitcoin Address = Base58Encode(Key hash concatenated with Checksum)<br />
<br />
The Base58 encoding used is home made, and has some differences. Especially, leading zeroes are kept as single zeroes when conversion happens.<br />
<br />
== Common structures ==<br />
<br />
Almost all integers are encoded in little endian. Only IP or port number are encoded big endian.<br />
<br />
=== Message structure ===<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown<br />
|-<br />
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| 4 || length || uint32_t || Length of payload in number of bytes<br />
|-<br />
| 4 || checksum || uint32_t || First 4 bytes of sha256(sha256(payload))<br />
|-<br />
| ? || payload || uchar[] || The actual data<br />
|}<br />
<br />
<br />
Known magic values:<br />
<br />
{|class="wikitable"<br />
! Network !! Magic value !! Sent over wire as<br />
|-<br />
| main || 0xD9B4BEF9 || F9 BE B4 D9<br />
|-<br />
| testnet || 0xDAB5BFFA || FA BF B5 DA<br />
|-<br />
| testnet3 || 0x0709110B || 0B 11 09 07<br />
|-<br />
| namecoin || 0xFEB4BEF9 || F9 BE B4 FE<br />
|}<br />
<br />
=== Variable length integer ===<br />
<br />
Integer can be encoded depending on the represented value to save space.<br />
Variable length integers always precede an array/vector of a type of data that may vary in length.<br />
Longer numbers are encoded in little endian.<br />
<br />
{|class="wikitable"<br />
! Value !! Storage length !! Format<br />
|-<br />
| < 0xFD || 1 || uint8_t<br />
|-<br />
| <= 0xFFFF || 3 || 0xFD followed by the length as uint16_t<br />
|-<br />
| <= 0xFFFF FFFF || 5 || 0xFE followed by the length as uint32_t<br />
|-<br />
| - || 9 || 0xFF followed by the length as uint64_t<br />
|}<br />
<br />
If you're reading the Satoshi client code (BitcoinQT) it refers to this encoding as a "CompactSize". Modern BitcoinQT also has the CVarInt class which implements an even more compact integer for the purpose of local storage (which is incompatible with "CompactSize" described here). CVarInt is not a part of the protocol.<br />
<br />
=== Variable length string ===<br />
<br />
Variable length string can be stored using a variable length integer followed by the string itself.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the string<br />
|-<br />
| ? || string || char[] || The string itself (can be empty)<br />
|}<br />
<br />
=== Network address ===<br />
<br />
When a network address is needed somewhere, this structure is used. Network addresses are not prefixed with a timestamp in the version message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || time || uint32 || the Time (version >= 31402). '''Not present in version message.'''<br />
|-<br />
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]<br />
|-<br />
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The original client only supported IPv4 and only read the last 4 bytes to get the IPv4 address. However, the IPv4 address is written into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]<br />
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).<br />
|-<br />
| 2 || port || uint16_t || port number, network byte order<br />
|}<br />
<br />
Hexdump example of Network address structure<br />
<br />
<pre><br />
0000 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0010 00 00 FF FF 0A 00 00 01 20 8D ........ .<br />
<br />
Network address:<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK: see services listed under version command)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv6: ::ffff:a00:1 or IPv4: 10.0.0.1<br />
20 8D - Port 8333<br />
</pre><br />
<br />
=== Inventory Vectors ===<br />
<br />
Inventory vectors are used for notifying other nodes about objects they have or data which is being requested.<br />
<br />
Inventory vectors consist of the following data format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || type || uint32_t || Identifies the object type linked to this inventory<br />
|-<br />
| 32 || hash || char[32] || Hash of the object<br />
|}<br />
<br />
<br />
The object type is currently defined as one of the following possibilities:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0 || ERROR || Any data of with this number may be ignored<br />
|-<br />
| 1 || MSG_TX || Hash is related to a transaction<br />
|-<br />
| 2 || MSG_BLOCK || Hash is related to a data block<br />
|-<br />
| 3 || MSG_FILTERED_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a merkleblock message rather than a block message; this only works if a bloom filter has been set.<br />
|-<br />
| 4 || MSG_CMPCT_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a cmpctblock message. See BIP 152 for more info.<br />
|}<br />
<br />
Other Data Type values are considered reserved for future implementations.<br />
<br />
=== Block Headers ===<br />
<br />
Block headers are sent in a headers packet in response to a getheaders message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Will overflow in 2106<ref>https://en.wikipedia.org/wiki/Unix_time#Notable_events_in_Unix_time</ref>)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 1 || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries, this value is always 0<br />
|}<br />
<br />
cf. [[Block hashing algorithm]]<br />
<br />
=== PrefilledTransaction ===<br />
<br />
A PrefilledTransaction structure is used in HeaderAndShortIDs to provide a list of a few transactions explicitly.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| index || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1, 3 bytes || Compact Size, differentially encoded since the last PrefilledTransaction in a list || The index into the block at which this transaction is<br />
|-<br />
| tx || Transaction || variable || As encoded in [[Protocol_documentation#tx|tx messages]] || The transaction which is in the block at index index.<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== HeaderAndShortIDs ===<br />
<br />
A HeaderAndShortIDs structure is used to relay a block header, the short transactions IDs used for matching already-available transactions, and a select few transactions which we expect a peer may be missing.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| header || Block header || 80 bytes || First 80 bytes of the block as defined by the encoding used by "block" messages || The header of the block being provided<br />
|-<br />
| nonce || uint64_t || 8 bytes || Little Endian || A nonce for use in short transaction ID calculations<br />
|-<br />
| shortids_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of short transaction IDs in shortids (ie block tx count - prefilledtxn_length)<br />
|-<br />
| shortids || List of 6-byte integers || 6*shortids_length bytes || Little Endian || The short transaction IDs calculated from the transactions which were not provided explicitly in prefilledtxn<br />
|-<br />
| prefilledtxn_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of prefilled transactions in prefilledtxn (ie block tx count - shortids_length)<br />
|-<br />
| prefilledtxn || List of PrefilledTransactions || variable size*prefilledtxn_length || As defined by PrefilledTransaction definition, above || Used to provide the coinbase transaction and a select few which we expect a peer may be missing<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== BlockTransactionsRequest ===<br />
<br />
A BlockTransactionsRequest structure is used to list transaction indexes in a block being requested.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| blockhash || Binary blob || 32 bytes || The output from a double-SHA256 of the block header, as used elsewhere || The blockhash of the block which the transactions being requested are in<br />
|-<br />
| indexes_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of transactions being requested<br />
|-<br />
| indexes || List of CompactSizes || 1 or 3 bytes*indexes_length || Differentially encoded || The indexes of the transactions being requested in the block<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== BlockTransactions ===<br />
<br />
A BlockTransactions structure is used to provide some of the transactions in a block, as requested.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| blockhash || Binary blob || 32 bytes || The output from a double-SHA256 of the block header, as used elsewhere || The blockhash of the block which the transactions being provided are in<br />
|-<br />
| transactions_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of transactions provided<br />
|-<br />
| transactions || List of Transactions || variable || As encoded in "tx" messages || The transactions provided<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== Short transaction IDs ===<br />
<br />
Short transaction IDs are used to represent a transaction without sending a full 256-bit hash. They are calculated by:<br />
<br />
# single-SHA256 hashing the block header with the nonce appended (in little-endian)<br />
# Running SipHash-2-4 with the input being the transaction ID and the keys (k0/k1) set to the first two little-endian 64-bit integers from the above hash, respectively.<br />
# Dropping the 2 most significant bytes from the SipHash output to make it 6 bytes.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
== Message types ==<br />
<br />
=== version ===<br />
<br />
When a node creates an outgoing connection, it will immediately [[Version Handshake|advertise]] its version. The remote node will respond with its version. No further communication is possible until both peers have exchanged their version.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Identifies protocol version being used by the node<br />
|-<br />
| 8 || services || uint64_t || bitfield of features to be enabled for this connection<br />
|-<br />
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds<br />
|-<br />
| 26 || addr_recv || [[#Network address|net_addr]] || The network address of the node receiving this message<br />
|-<br />
|colspan="4"| Fields below require version ≥ 106<br />
|-<br />
| 26 || addr_from || [[#Network address|net_addr]] || The network address of the node emitting this message<br />
|-<br />
| 8 || nonce || uint64_t || Node random nonce, randomly generated every time a version packet is sent. This nonce is used to detect connections to self.<br />
|-<br />
| ? || user_agent || [[#Variable length string|var_str]] || [https://github.com/bitcoin/bips/blob/master/bip-0014.mediawiki User Agent] (0x00 if string is 0 bytes long)<br />
|-<br />
| 4 || start_height || int32_t || The last block received by the emitting node<br />
|-<br />
|colspan="4"| Fields below require version ≥ 70001<br />
|-<br />
| 1 || relay || bool || Whether the remote peer should announce relayed transactions or not, see [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037]<br />
|}<br />
<br />
A "verack" packet shall be sent if the version packet was accepted.<br />
<br />
The following services are currently assigned:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 1 || NODE_NETWORK || This node can be asked for full blocks instead of just headers.<br />
|}<br />
<br />
Hexdump example of version message (OBSOLETE EXAMPLE: This example lacks a checksum and user-agent):<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....<br />
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........<br />
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............<br />
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................<br />
0040 20 8D 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,<br />
0060 3A B4 57 13 00 55 81 01 00 :.W..U...<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
55 00 00 00 - Payload is 85 bytes long<br />
- No checksum in version message until 20 February 2012. See https://bitcointalk.org/index.php?topic=55852.0<br />
Version message:<br />
9C 7C 00 00 - 31900 (version 0.3.19)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
E6 15 10 4D 00 00 00 00 - Mon Dec 20 21:50:14 EST 2010<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 20 8D - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D - Sender address info - see Network Address<br />
DD 9D 20 2C 3A B4 57 13 - Node random unique ID<br />
00 - "" sub-version string (string is 0 bytes long)<br />
55 81 01 00 - Last block sending node has is block #98645<br />
</pre><br />
<br />
And here's a modern (60002) protocol version client advertising itself to a local peer...<br />
<br />
Newer protocol includes the checksum now, this is from a mainline (satoshi) client during <br />
an outgoing connection to another local client, notice that it does not fill out the <br />
address information at all when the source or destination is "unroutable".<br />
<br />
<pre><br />
<br />
0000 f9 be b4 d9 76 65 72 73 69 6f 6e 00 00 00 00 00 ....version.....<br />
0010 64 00 00 00 35 8d 49 32 62 ea 00 00 01 00 00 00 d...5.I2b.......<br />
0020 00 00 00 00 11 b2 d0 50 00 00 00 00 01 00 00 00 .......P........<br />
0030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ff ff ................<br />
0040 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 00 00 00 00 ff ff 00 00 00 00 00 00 ................<br />
0060 3b 2e b3 5d 8c e6 17 65 0f 2f 53 61 74 6f 73 68 ;..]...e./Satosh<br />
0070 69 3a 30 2e 37 2e 32 2f c0 3e 03 00 i:0.7.2/.>..<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
64 00 00 00 - Payload is 100 bytes long<br />
3B 64 8D 5A - payload checksum<br />
<br />
Version message:<br />
62 EA 00 00 - 60002 (protocol version 60002)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
11 B2 D0 50 00 00 00 00 - Tue Dec 18 10:12:33 PST 2012<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Sender address info - see Network Address<br />
3B 2E B3 5D 8C E6 17 65 - Node ID<br />
0F 2F 53 61 74 6F 73 68 69 3A 30 2E 37 2E 32 2F - "/Satoshi:0.7.2/" sub-version string (string is 15 bytes long)<br />
C0 3E 03 00 - Last block sending node has is block #212672<br />
</pre><br />
<br />
=== verack ===<br />
<br />
The ''verack'' message is sent in reply to ''[[#version|version]]''. This message consists of only a [[#Message structure|message header]] with the command string "verack".<br />
<br />
Hexdump of the verack message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......<br />
0010 00 00 00 00 5D F6 E0 E2 ........<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 61 63 6B 00 00 00 00 00 00 - "verack" command<br />
00 00 00 00 - Payload is 0 bytes long<br />
5D F6 E0 E2 - Checksum<br />
</pre><br />
<br />
=== addr ===<br />
<br />
Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours<br />
<br />
Payload:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of address entries (max: 1000)<br />
|-<br />
| 30x? || addr_list || (uint32_t + [[#Network address|net_addr]])[] || Address of other nodes on the network. version < 209 will only read the first one. The uint32_t is a timestamp (see note below).<br />
|}<br />
<br />
'''Note''': Starting version 31402, addresses are prefixed with a timestamp. If no timestamp is present, the addresses should not be relayed to other peers, unless it is indeed confirmed they are up.<br />
<br />
Hexdump example of ''addr'' message:<br />
<pre><br />
0000 F9 BE B4 D9 61 64 64 72 00 00 00 00 00 00 00 00 ....addr........<br />
0010 1F 00 00 00 ED 52 39 9B 01 E2 15 10 4D 01 00 00 .....R9.....M...<br />
0020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF ................<br />
0030 FF 0A 00 00 01 20 8D ..... .<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
61 64 64 72 00 00 00 00 00 00 00 00 - "addr"<br />
1F 00 00 00 - payload is 31 bytes long<br />
ED 52 39 9B - checksum of payload<br />
<br />
Payload:<br />
01 - 1 address in this message<br />
<br />
Address:<br />
E2 15 10 4D - Mon Dec 20 21:50:10 EST 2010 (only when version is >= 31402)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK service - see version message)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv4: 10.0.0.1, IPv6: ::ffff:10.0.0.1 (IPv4-mapped IPv6 address)<br />
20 8D - port 8333<br />
</pre><br />
<br />
=== inv ===<br />
<br />
Allows a node to advertise its knowledge of one or more objects. It can be received unsolicited, or in reply to ''getblocks''.<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getdata ===<br />
<br />
getdata is used in response to inv, to retrieve the content of a specific object, and is usually sent after receiving an ''inv'' packet, after filtering known elements. It can be used to retrieve transactions, but only if they are in the memory pool or relay set - arbitrary access to transactions in the chain is not allowed to avoid having clients start to depend on nodes having full transaction indexes (which modern nodes do not).<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== notfound ===<br />
<br />
notfound is a response to a getdata, sent if any requested data items could not be relayed, for example, because the requested transaction was not in the memory pool or relay set.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getblocks ===<br />
<br />
Return an ''inv'' packet containing the list of blocks starting right after the last known hash in the block locator object, up to hash_stop or 500 blocks, whichever comes first. <br />
<br />
The locator hashes are processed by a node in the order as they appear in the message. If a block hash is found in the node's main chain, the list of its children is returned back via the ''inv'' message and the remaining locators are ignored, no matter if the requested limit was reached, or not.<br />
<br />
To receive the next blocks hashes, one needs to issue getblocks again with a new block locator object. Keep in mind that some clients may provide blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block; set to zero to get as many blocks as possible (500)<br />
|}<br />
<br />
To create the block locator hashes, keep pushing hashes until you go back to the genesis block. After pushing 10 hashes back, the step backwards doubles every loop:<br />
<br />
<pre><br />
// From libbitcoin which is under AGPL<br />
std::vector<size_t> block_locator_indexes(size_t top_height)<br />
{<br />
std::vector<size_t> indexes;<br />
<br />
// Modify the step in the iteration.<br />
int64_t step = 1;<br />
<br />
// Start at the top of the chain and work backwards.<br />
for (auto index = (int64_t)top_height; index > 0; index -= step)<br />
{<br />
// Push top 10 indexes first, then back off exponentially.<br />
if (indexes.size() >= 10)<br />
step *= 2;<br />
<br />
indexes.push_back((size_t)index);<br />
}<br />
<br />
// Push the genesis block index.<br />
indexes.push_back(0);<br />
return indexes;<br />
}<br />
</pre><br />
<br />
Note that it is allowed to send in fewer known hashes down to a minimum of just one hash. However, the purpose of the block locator object is to detect a wrong branch in the caller's main chain. If the peer detects that you are off the main chain, it will send in block hashes which are earlier than your last known block. So if you just send in your last known hash and it is off the main chain, the peer starts over at block #1.<br />
<br />
=== getheaders ===<br />
<br />
Return a ''headers'' packet containing the headers of blocks starting right after the last known hash in the block locator object, up to hash_stop or 2000 blocks, whichever comes first. To receive the next block headers, one needs to issue getheaders again with a new block locator object. The ''getheaders'' command is used by thin clients to quickly download the block chain where the contents of the transactions would be irrelevant (because they are not ours). Keep in mind that some clients may provide headers of blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block header; set to zero to get as many blocks as possible (2000)<br />
|}<br />
<br />
For the block locator object in this packet, the same rules apply as for the [[Protocol_documentation#getblocks|getblocks]] packet.<br />
<br />
=== tx ===<br />
<br />
''tx'' describes a bitcoin transaction, in reply to ''[[#getdata|getdata]]''<br />
<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Transaction data format version (note, this is signed)<br />
|-<br />
| 1+ || tx_in count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction inputs<br />
|-<br />
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins<br />
|-<br />
| 1+ || tx_out count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction outputs<br />
|-<br />
| 9+ || tx_out || tx_out[] || A list of 1 or more transaction outputs or destinations for coins<br />
|-<br />
| 4 || lock_time || uint32_t || The block number or timestamp at which this transaction is locked:<br />
{|class="wikitable"<br />
! Value !! Description<br />
|-<br />
| 0 || Not locked<br />
|-<br />
| < 500000000 || Block number at which this transaction is locked<br />
|-<br />
| >= 500000000 || UNIX timestamp at which this transaction is locked<br />
|}<br />
If all TxIn inputs have final (0xffffffff) sequence numbers then lock_time is irrelevant. Otherwise, the transaction may not be added to a block until after lock_time (see [[NLockTime]]).<br />
<br />
|}<br />
<br />
TxIn consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 36 || previous_output || outpoint || The previous output transaction reference, as an OutPoint structure<br />
|-<br />
| 1+ || script length || [[Protocol_documentation#Variable_length_integer|var_int]] || The length of the signature script<br />
|-<br />
| ? || signature script || uchar[] || Computational Script for confirming transaction authorization<br />
|-<br />
| 4 || [http://bitcoin.stackexchange.com/q/2025/323 sequence] || uint32_t || Transaction version as defined by the sender. Intended for "replacement" of transactions when information is updated before inclusion into a block.<br />
|}<br />
<br />
The OutPoint structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 32 || hash || char[32] || The hash of the referenced transaction.<br />
|-<br />
| 4 || index || uint32_t || The index of the specific output in the transaction. The first output is 0, etc.<br />
|}<br />
<br />
The Script structure consists of a series of pieces of information and operations related to the value of the transaction.<br />
<br />
(Structure to be expanded in the future… see script.h and script.cpp and [[Script]] for more information)<br />
<br />
The TxOut structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || value || int64_t || Transaction Value<br />
|-<br />
| 1+ || pk_script length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the pk_script<br />
|-<br />
| ? || pk_script || uchar[] || Usually contains the public key as a Bitcoin script setting up conditions to claim this output.<br />
|}<br />
<br />
Example ''tx'' message:<br />
<pre><br />
000000 F9 BE B4 D9 74 78 00 00 00 00 00 00 00 00 00 00 ....tx..........<br />
000010 02 01 00 00 E2 93 CD BE 01 00 00 00 01 6D BD DB .............m..<br />
000020 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D 12 66 E9 .[...Q........f.<br />
000030 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29 00 00 00 .;P......j.6)...<br />
000040 00 8B 48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 ..H0E.!..X..r...<br />
000050 C7 36 7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A .6zz%;..R#...h.:<br />
000060 59 23 3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 Y#?E.W... Y.....<br />
000070 0E 41 83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D .A.z.X.z...XN...<br />
000080 35 BD 96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF 5...6..;...A....<br />
000090 C9 7E F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 .~.6.m...@..!...<br />
0000A0 2A CD 2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC *.+..].}Y... ...<br />
0000B0 4E 02 53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F N.S..=7.o...Q...<br />
0000C0 14 04 2F 46 61 4A 4C 70 C0 F1 4B EF F5 FF FF FF ../FaJLp..K.....<br />
0000D0 FF 02 40 4B 4C 00 00 00 00 00 19 76 A9 14 1A A0 ..@KL......v....<br />
0000E0 CD 1C BE A6 E7 45 8A 7A BA D5 12 A9 D9 EA 1A FB .....E.z........<br />
0000F0 22 5E 88 AC 80 FA E9 C7 00 00 00 00 19 76 A9 14 "^...........v..<br />
000100 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E FD A0 B7 ..[.Cj.....H^...<br />
000110 8B 4E CC 52 88 AC 00 00 00 00 .N.R......<br />
<br />
<br />
Message header:<br />
F9 BE B4 D9 - main network magic bytes<br />
74 78 00 00 00 00 00 00 00 00 00 00 - "tx" command<br />
02 01 00 00 - payload is 258 bytes long<br />
E2 93 CD BE - checksum of payload<br />
<br />
Transaction:<br />
01 00 00 00 - version<br />
<br />
Inputs:<br />
01 - number of transaction inputs<br />
<br />
Input 1:<br />
6D BD DB 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D - previous output (outpoint)<br />
12 66 E9 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29<br />
00 00 00 00<br />
<br />
8B - script is 139 bytes long<br />
<br />
48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 C7 36 - signature script (scriptSig)<br />
7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A 59 23<br />
3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 0E 41<br />
83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D 35 BD<br />
96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF C9 7E<br />
F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 2A CD<br />
2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC 4E 02<br />
53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F 14 04<br />
2F 46 61 4A 4C 70 C0 F1 4B EF F5<br />
<br />
FF FF FF FF - sequence<br />
<br />
Outputs:<br />
02 - 2 Output Transactions<br />
<br />
Output 1:<br />
40 4B 4C 00 00 00 00 00 - 0.05 BTC (5000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 1A A0 CD 1C BE A6 E7 45 8A 7A BA D5 12 - pk_script<br />
A9 D9 EA 1A FB 22 5E 88 AC<br />
<br />
Output 2:<br />
80 FA E9 C7 00 00 00 00 - 33.54 BTC (3354000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E - pk_script<br />
FD A0 B7 8B 4E CC 52 88 AC<br />
<br />
Locktime:<br />
00 00 00 00 - lock time<br />
</pre><br />
<br />
=== block ===<br />
<br />
The '''block''' message is sent in response to a getdata message which requests transaction information from a block hash.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A Unix timestamp recording when this block was created (Currently limited to dates before the year 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated [[Difficulty|difficulty target]] being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| ? || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries<br />
|-<br />
| ? || txns || tx[] || Block transactions, in format of "tx" command<br />
|}<br />
<br />
The SHA256 hash that identifies each block (and which must have a run of 0 bits) is calculated from the first 6 fields of this structure (version, prev_block, merkle_root, timestamp, bits, nonce, and standard SHA256 padding, making two 64-byte chunks in all) and ''not'' from the complete block. To calculate the hash, only two chunks need to be processed by the SHA256 algorithm. Since the ''nonce'' field is in the second chunk, the first chunk stays constant during mining and therefore only the second chunk needs to be processed. However, a Bitcoin hash is the hash of the hash, so two SHA256 rounds are needed for each mining iteration.<br />
See [[Block hashing algorithm]] for details and an example.<br />
<br />
=== headers ===<br />
<br />
The ''headers'' packet returns block headers in response to a ''getheaders'' packet. <br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of block headers<br />
|-<br />
| 81x? || headers || [[Protocol_documentation#Block_Headers|block_header]][] || [[Protocol_documentation#Block_Headers|Block headers]]<br />
|}<br />
<br />
Note that the block headers in this packet include a transaction count (a var_int, so there can be more than 81 bytes per header) as opposed to the block headers that are hashed by miners.<br />
<br />
=== getaddr ===<br />
<br />
The getaddr message sends a request to a node asking for information about known active peers to help with finding potential nodes in the network. The response to receiving this message is to transmit one or more addr messages with one or more peers from a database of known active peers. The typical presumption is that a node is likely to be active if it has been sending a message within the last three hours.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
=== mempool ===<br />
<br />
The mempool message sends a request to a node asking for information about transactions it has verified but which have not yet confirmed. The response to receiving this message is an inv message containing the transaction hashes for all the transactions in the node's mempool.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
It is specified in [https://github.com/bitcoin/bips/blob/master/bip-0035.mediawiki BIP 35]. Since [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 37], if a [[Protocol_documentation#filterload.2C_filteradd.2C_filterclear.2C_merkleblock|bloom filter]] is loaded, only transactions matching the filter are replied.<br />
<br />
=== checkorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== submitorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== reply ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== ping ===<br />
<br />
The ''ping'' message is sent primarily to confirm that the TCP/IP connection is still valid. An error in transmission is presumed to be a closed connection and the address is removed as a current peer.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || random nonce<br />
|}<br />
<br />
=== pong ===<br />
<br />
The ''pong'' message is sent in response to a ''ping'' message. In modern protocol versions, a ''pong'' response is generated using a nonce included in the ping.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || nonce from ping<br />
|}<br />
<br />
<br />
=== reject===<br />
<br />
The ''reject'' message is sent when messages are rejected.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || message || var_str || type of message rejected<br />
|-<br />
| 1 || ccode || char || code relating to rejected message<br />
|-<br />
| 1+ || reason || var_str || text version of reason for rejection<br />
|-<br />
| 0+ || data || char || Optional extra data provided by some errors. Currently, all errors which provide this field fill it with the TXID or block header hash of the object being rejected, so the field is 32 bytes.<br />
|}<br />
<br />
CCodes<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0x01 || REJECT_MALFORMED|| <br />
|-<br />
| 0x10 || REJECT_INVALID ||<br />
|-<br />
| 0x11 || REJECT_OBSOLETE ||<br />
|-<br />
| 0x12 || REJECT_DUPLICATE ||<br />
|-<br />
| 0x40 || REJECT_NONSTANDARD ||<br />
|-<br />
| 0x41 || REJECT_DUST ||<br />
|-<br />
| 0x42 || REJECT_INSUFFICIENTFEE ||<br />
|-<br />
| 0x43 || REJECT_CHECKPOINT ||<br />
|}<br />
<br />
=== filterload, filteradd, filterclear, merkleblock ===<br />
<br />
These messages are related to Bloom filtering of connections and are defined in [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037].<br />
<br />
<br />
The <code>filterload</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || filter || uint8_t[] || The filter itself is simply a bit field of arbitrary byte-aligned size. The maximum size is 36,000 bytes.<br />
|-<br />
| 4 || nHashFuncs || uint32_t || The number of hash functions to use in this filter. The maximum value allowed in this field is 50.<br />
|-<br />
| 4 || nTweak || uint32_t || A random value to add to the seed value in the hash function used by the bloom filter.<br />
|-<br />
| 1 || nFlags || uint8_t || A set of flags that control how matched items are added to the filter.<br />
|}<br />
<br />
See below for a description of the Bloom filter algorithm and how to select nHashFuncs and filter size for a desired false positive rate.<br />
<br />
Upon receiving a <code>filterload</code> command, the remote peer will immediately restrict the broadcast transactions it announces (in inv packets) to transactions matching the filter, where the matching algorithm is specified below. The flags control the update behaviour of the matching algorithm.<br />
<br />
The <code>filteradd</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || data || uint8_t[] || The data element to add to the current filter.<br />
|}<br />
<br />
The data field must be smaller than or equal to 520 bytes in size (the maximum size of any potentially matched object).<br />
<br />
The given data element will be added to the Bloom filter. A filter must have been previously provided using <code>filterload</code>. This command is useful if a new key or script is added to a clients wallet whilst it has connections to the network open, it avoids the need to re-calculate and send an entirely new filter to every peer (though doing so is usually advisable to maintain anonymity).<br />
<br />
The <code>filterclear</code> command has no arguments at all.<br />
<br />
After a filter has been set, nodes don't merely stop announcing non-matching transactions, they can also serve filtered blocks. A filtered block is defined by the <code>merkleblock</code> message and is defined like this:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information, based upon the software version creating this block (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Limited to 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 4 || total_transactions || uint32_t || Number of transactions in the block (including unmatched ones)<br />
|-<br />
| ? || hashes || uint256[] || hashes in depth-first order (including standard varint size prefix)<br />
|-<br />
| ? || flags || byte[] || flag bits, packed per 8 in a byte, least significant bit first (including standard varint size prefix)<br />
|}<br />
<br />
=== alert ===<br />
<br />
An '''alert''' is sent between nodes to send a general notification message throughout the network. If the alert can be confirmed with the signature as having come from the core development group of the Bitcoin software, the message is suggested to be displayed for end-users. Attempts to perform transactions, particularly automated transactions through the client, are suggested to be halted. The text in the Message string should be relayed to log files and any user interfaces.<br />
<br />
Alert format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || payload || uchar[] || Serialized alert payload<br />
|-<br />
| ? || signature || uchar[] || An ECDSA signature of the message<br />
|}<br />
<br />
The developers of Satoshi's client use this public key for signing alerts:<br />
04fc9702847840aaf195de8442ebecedf5b095cdbb9bc716bda9110971b28a49e0ead8564ff0db22209e0374782c093bb899692d524e9d6a6956e7c5ecbcd68284<br />
(hash) 1AGRxqDa5WjUKBwHB9XYEjmkv1ucoUUy1s<br />
<br />
The payload is serialized into a uchar[] to ensure that versions using incompatible alert formats can still relay alerts among one another. The current alert payload format is:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || Version || int32_t || Alert format version<br />
|-<br />
| 8 || RelayUntil || int64_t || The timestamp beyond which nodes should stop relaying this alert<br />
|-<br />
| 8 || Expiration || int64_t || The timestamp beyond which this alert is no longer in effect and should be ignored<br />
|-<br />
| 4 || ID || int32_t || A unique ID number for this alert<br />
|-<br />
| 4 || Cancel || int32_t || All alerts with an ID number less than or equal to this number should be cancelled: deleted and not accepted in the future<br />
|-<br />
| ? || setCancel || set<int32_t> || All alert IDs contained in this set should be cancelled as above<br />
|-<br />
| 4 || MinVer || int32_t || This alert only applies to versions greater than or equal to this version. Other versions should still relay it.<br />
|-<br />
| 4 || MaxVer || int32_t || This alert only applies to versions less than or equal to this version. Other versions should still relay it.<br />
|-<br />
| ? || setSubVer || set<string> || If this set contains any elements, then only nodes that have their subVer contained in this set are affected by the alert. Other versions should still relay it.<br />
|-<br />
| 4 || Priority || int32_t || Relative priority compared to other alerts<br />
|-<br />
| ? || Comment || string || A comment on the alert that is not displayed<br />
|-<br />
| ? || StatusBar || string || The alert message that is displayed to the user<br />
|-<br />
| ? || Reserved || string || Reserved<br />
|}<br />
<br />
Note: '''set<''type''>''' in the table above is a [[#Variable length integer | variable length integer]] followed by the number of fields of the given ''type'' (either int32_t or [[#Variable length string | variable length string]])<br />
<br />
Sample alert (no message header):<br />
73010000003766404f00000000b305434f00000000f2030000f1030000001027000048ee0000<br />
0064000000004653656520626974636f696e2e6f72672f666562323020696620796f75206861<br />
76652074726f75626c6520636f6e6e656374696e672061667465722032302046656272756172<br />
79004730450221008389df45f0703f39ec8c1cc42c13810ffcae14995bb648340219e353b63b<br />
53eb022009ec65e1c1aaeec1fd334c6b684bde2b3f573060d5b70c3a46723326e4e8a4f1<br />
<br />
Version: 1<br />
RelayUntil: 1329620535<br />
Expiration: 1329792435<br />
ID: 1010<br />
Cancel: 1009<br />
setCancel: <empty><br />
MinVer: 10000<br />
MaxVer: 61000<br />
setSubVer: <empty><br />
Priority: 100<br />
Comment: <empty><br />
StatusBar: "See bitcoin.org/feb20 if you have trouble connecting after 20 February"<br />
Reserved: <empty><br />
<br />
=== sendheaders ===<br />
<br />
Request for Direct headers announcement. <br />
<br />
Upon receipt of this message, the node is be permitted, but not required, to announce new blocks by '''headers''' command (instead of '''inv''' command).<br />
<br />
This message is supported by the protocol version >= 70012 or Bitcoin Core version >= 0.12.0.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0130.mediawiki BIP 130] for more information.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
<br />
=== feefilter ===<br />
<br />
The payload is always 8 bytes long and it encodes 64 bit integer value (LSB / little endian) of '''feerate'''.<br />
The value represents a minimal fee and is expressed in satoshis per 1000 bytes.<br />
<br />
Upon receipt of a "feefilter" message, the node will be permitted, but not required, to filter transaction invs for transactions that fall below the feerate provided in the feefilter message interpreted as satoshis per kilobyte.<br />
<br />
The fee filter is additive with a bloom filter for transactions so if an SPV client were to load a bloom filter and send a feefilter message, transactions would only be relayed if they passed both filters.<br />
<br />
Inv's generated from a mempool message are also subject to a fee filter if it exists.<br />
<br />
Feature discovery is enabled by checking protocol version >= 70013<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0133.mediawiki BIP 133] for more information.<br />
<br />
=== sendcmpct ===<br />
<br />
# The sendcmpct message is defined as a message containing a 1-byte integer followed by a 8-byte integer where pchCommand == "sendcmpct".<br />
# The first integer SHALL be interpreted as a boolean (and MUST have a value of either 1 or 0)<br />
# The second integer SHALL be interpreted as a little-endian version number. Nodes sending a sendcmpct message MUST currently set this value to 1.<br />
# Upon receipt of a "sendcmpct" message with the first and second integers set to 1, the node SHOULD announce new blocks by sending a cmpctblock message.<br />
# Upon receipt of a "sendcmpct" message with the first integer set to 0, the node SHOULD NOT announce new blocks by sending a cmpctblock message, but SHOULD announce new blocks by sending invs or headers, as defined by BIP130.<br />
# Upon receipt of a "sendcmpct" message with the second integer set to something other than 1, nodes MUST treat the peer as if they had not received the message (as it indicates the peer will provide an unexpected encoding in <br />
# cmpctblock, and/or other, messages). This allows future versions to send duplicate sendcmpct messages with different versions as a part of a version handshake for future versions.<br />
# Nodes SHOULD check for a protocol version of >= 70014 before sending sendcmpct messages.<br />
# Nodes MUST NOT send a request for a MSG_CMPCT_BLOCK object to a peer before having received a sendcmpct message from that peer.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== cmpctblock ===<br />
<br />
# The cmpctblock message is defined as as a message containing a serialized HeaderAndShortIDs message and pchCommand == "cmpctblock".<br />
# Upon receipt of a cmpctblock message after sending a sendcmpct message, nodes SHOULD calculate the short transaction ID for each unconfirmed transaction they have available (ie in their mempool) and compare each to each short transaction ID in the cmpctblock message.<br />
# After finding already-available transactions, nodes which do not have all transactions available to reconstruct the full block SHOULD request the missing transactions using a getblocktxn message.<br />
# A node MUST NOT send a cmpctblock message unless they are able to respond to a getblocktxn message which requests every transaction in the block.<br />
# A node MUST NOT send a cmpctblock message without having validated that the header properly commits to each transaction in the block, and properly builds on top of the existing chain with a valid proof-of-work. A node MAY send a cmpctblock before validating that each transaction in the block validly spends existing UTXO set entries.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== getblocktxn ===<br />
<br />
# The getblocktxn message is defined as as a message containing a serialized BlockTransactionsRequest message and pchCommand == "getblocktxn".<br />
# Upon receipt of a properly-formatted getblocktxnmessage, nodes which recently provided the sender of such a message a cmpctblock for the block hash identified in this message MUST respond with an appropriate blocktxn message. Such a blocktxn message MUST contain exactly and only each transaction which is present in the appropriate block at the index specified in the getblocktxn indexes list, in the order requested.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== blocktxn ===<br />
<br />
# The blocktxn message is defined as as a message containing a serialized BlockTransactions message and pchCommand == "blocktxn".<br />
# Upon receipt of a properly-formatted requested blocktxn message, nodes SHOULD attempt to reconstruct the full block by:<br />
# Taking the prefilledtxn transactions from the original cmpctblock and placing them in the marked positions.<br />
# For each short transaction ID from the original cmpctblock, in order, find the corresponding transaction either from the blocktxn message or from other sources and place it in the first available position in the block.<br />
# Once the block has been reconstructed, it shall be processed as normal, keeping in mind that short transaction IDs are expected to occasionally collide, and that nodes MUST NOT be penalized for such collisions, wherever they # appear.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
== Scripting ==<br />
<br />
See [[script]].<br />
<br />
==See Also==<br />
<br />
* [[Network]]<br />
* [[Protocol rules]]<br />
* [[Hardfork Wishlist]]<br />
* [https://bitcoin.org/en/developer-documentation Developer Documentation on bitcoin.org]<br />
* Bitcoin dissectors for Wireshark: https://github.com/lbotsch/wireshark-bitcoin https://github.com/op-sig/bitcoin-wireshark-dissector<br />
<br />
==References==<br />
<references /><br />
<br />
[[zh-cn:协议说明]]<br />
[[Category:Technical]]<br />
[[Category:Developer]]<br />
<br />
{{Bitcoin Core documentation}}</div>Tonikthttps://en.bitcoin.it/w/index.php?title=Protocol_documentation&diff=61492Protocol documentation2016-08-25T12:42:22Z<p>Tonikt: /* BlockTransactions */</p>
<hr />
<div>This page ''describes'' the behavior of the [[Original Bitcoin client|reference client]]. The Bitcoin protocol is specified by the behavior of the reference client, not by this page. In particular, while this page is quite complete in describing the network protocol, it does not attempt to list all of the rules for block or transaction validity.<br />
<br />
Type names used in this documentation are from the C99 standard.<br />
<br />
For protocol used in mining, see [[getblocktemplate]].<br />
<br />
==Common standards==<br />
<br />
=== Hashes ===<br />
<br />
Usually, when a hash is computed within bitcoin, it is computed twice. Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-256] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when a shorter hash is desirable (for example when creating a bitcoin address).<br />
<br />
Example of double-SHA-256 encoding of string "hello":<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round of sha-256)<br />
9595c9df90075148eb06860365df33584b75bff782a510c6cd4883a419833d50 (second round of sha-256)<br />
<br />
For bitcoin addresses (RIPEMD-160) this would give:<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round is sha-256)<br />
b6a9c8c230722b7c748331a8b450f05566dc7d0f (with ripemd-160)<br />
<br />
=== Merkle Trees ===<br />
<br />
Merkle trees are binary trees of hashes. Merkle trees in bitcoin use a '''double''' SHA-256, the SHA-256 hash of the SHA-256 hash of something.<br />
<br />
If, when forming a row in the tree (other than the root of the tree), it would have an odd number of elements, the final double-hash is duplicated to ensure that the row has an even number of hashes.<br />
<br />
First form the bottom row of the tree with the ordered double-SHA-256 hashes of the byte streams of the transactions in the block.<br />
<br />
Then the row above it consists of half that number of hashes. Each entry is the double-SHA-256 of the 64-byte concatenation of the corresponding two hashes below it in the tree.<br />
<br />
This procedure repeats recursively until we reach a row consisting of just a single double-hash. This is the '''Merkle root''' of the tree.<br />
<br />
For example, imagine a block with three transactions ''a'', ''b'' and ''c''. The Merkle tree is: <br />
<br />
d1 = dhash(a)<br />
d2 = dhash(b)<br />
d3 = dhash(c)<br />
d4 = dhash(c) # a, b, c are 3. that's an odd number, so we take the c twice<br />
<br />
d5 = dhash(d1 concat d2)<br />
d6 = dhash(d3 concat d4)<br />
<br />
d7 = dhash(d5 concat d6)<br />
<br />
where<br />
<br />
dhash(a) = sha256(sha256(a))<br />
<br />
''d7'' is the Merkle root of the 3 transactions in this block.<br />
<br />
Note: Hashes in Merkle Tree displayed in the [[Block Explorer]] are of little-endian notation. For some implementations and [http://www.fileformat.info/tool/hash.htm calculations], the bits need to be reversed before they are hashed, and again after the hashing operation.<br />
<br />
=== Signatures ===<br />
<br />
Bitcoin uses [http://en.wikipedia.org/wiki/Elliptic_curve_cryptography Elliptic Curve] [http://en.wikipedia.org/wiki/Digital_Signature_Algorithm Digital Signature Algorithm] ([http://en.wikipedia.org/wiki/Elliptic_Curve_DSA ECDSA]) to sign transactions. <br />
<br />
For [[ECDSA]] the secp256k1 curve from http://www.secg.org/collateral/sec2_final.pdf is used.<br />
<br />
Public keys (in scripts) are given as 04 <x> <y> where ''x'' and ''y'' are 32 byte big-endian integers representing the coordinates of a point on the curve or in compressed form given as <sign> <x> where <sign> is 0x02 if ''y'' is even and 0x03 if ''y'' is odd.<br />
<br />
Signatures use [http://en.wikipedia.org/wiki/Distinguished_Encoding_Rules DER encoding] to pack the ''r'' and ''s'' components into a single byte stream (this is also what OpenSSL produces by default).<br />
<br />
=== Transaction Verification ===<br />
Transactions are cryptographically signed records that reassign ownership of Bitcoins to new addresses. Transactions have ''inputs'' - records which reference the funds from other previous transactions - and ''outputs'' - records which determine the new owner of the transferred Bitcoins, and which will be referenced as inputs in future transactions as those funds are respent.<br />
<br />
Each ''input'' must have a cryptographic digital signature that unlocks the funds from the prior transaction. Only the person possessing the appropriate [[private key]] is able to create a satisfactory signature; this in effect ensures that funds can only be spent by their owners.<br />
<br />
Each ''output'' determines which Bitcoin address (or other criteria, see [[Script]]) is the recipient of the funds.<br />
<br />
In a transaction, the sum of all inputs must be equal to or greater than the sum of all outputs. If the inputs exceed the outputs, the difference is considered a [[transaction fee]], and is redeemable by whoever first includes the transaction into the block chain.<br />
<br />
A special kind of transaction, called a [[coinbase transaction]], has no inputs. It is created by [[miners]], and there is one coinbase transaction per block. Because each block comes with a reward of newly created Bitcoins (e.g. 50 BTC for the first 210,000 blocks), the first transaction of a block is, with few exceptions, the transaction that grants those coins to their recipient (the miner). In addition to the newly created Bitcoins, the coinbase transaction is also used for assigning the recipient of any transaction fees that were paid within the other transactions being included in the same block. The coinbase transaction can assign the entire reward to a single Bitcoin address, or split it in portions among multiple addresses, just like any other transaction. Coinbase transactions always contain outputs totalling the sum of the block reward plus all transaction fees collected from the other transactions in the same block.<br />
<br />
The [[coinbase transaction]] in block zero cannot be spent. This is due to a quirk of the reference client implementation that would open the potential for a block chain fork if some nodes accepted the spend and others did not<ref>[http://bitcointalk.org/index.php?topic=119645.msg1288552#msg1288552 Block 0 Network Fork]</ref>.<br />
<br />
Most Bitcoin outputs encumber the newly transferred coins with a single ECDSA private key. The actual record saved with inputs and outputs isn't necessarily a key, but a ''script''. Bitcoin uses an interpreted scripting system to determine whether an output's criteria have been satisfied, with which more complex operations are possible, such as outputs that require two ECDSA signatures, or two-of-three-signature schemes. An output that references a single Bitcoin address is a ''typical'' output; an output actually contains this information in the form of a script that requires a single ECDSA signature (see [[OP_CHECKSIG]]). The output script specifies what must be provided to unlock the funds later, and when the time comes in the future to spend the transaction in another input, that input must provide all of the thing(s) that satisfy the requirements defined by the original output script.<br />
<br />
=== Addresses ===<br />
<br />
A bitcoin address is in fact the hash of a ECDSA public key, computed this way:<br />
<br />
Version = 1 byte of 0 (zero); on the test network, this is 1 byte of 111<br />
Key hash = Version concatenated with RIPEMD-160(SHA-256(public key))<br />
Checksum = 1st 4 bytes of SHA-256(SHA-256(Key hash))<br />
Bitcoin Address = Base58Encode(Key hash concatenated with Checksum)<br />
<br />
The Base58 encoding used is home made, and has some differences. Especially, leading zeroes are kept as single zeroes when conversion happens.<br />
<br />
== Common structures ==<br />
<br />
Almost all integers are encoded in little endian. Only IP or port number are encoded big endian.<br />
<br />
=== Message structure ===<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown<br />
|-<br />
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| 4 || length || uint32_t || Length of payload in number of bytes<br />
|-<br />
| 4 || checksum || uint32_t || First 4 bytes of sha256(sha256(payload))<br />
|-<br />
| ? || payload || uchar[] || The actual data<br />
|}<br />
<br />
<br />
Known magic values:<br />
<br />
{|class="wikitable"<br />
! Network !! Magic value !! Sent over wire as<br />
|-<br />
| main || 0xD9B4BEF9 || F9 BE B4 D9<br />
|-<br />
| testnet || 0xDAB5BFFA || FA BF B5 DA<br />
|-<br />
| testnet3 || 0x0709110B || 0B 11 09 07<br />
|-<br />
| namecoin || 0xFEB4BEF9 || F9 BE B4 FE<br />
|}<br />
<br />
=== Variable length integer ===<br />
<br />
Integer can be encoded depending on the represented value to save space.<br />
Variable length integers always precede an array/vector of a type of data that may vary in length.<br />
Longer numbers are encoded in little endian.<br />
<br />
{|class="wikitable"<br />
! Value !! Storage length !! Format<br />
|-<br />
| < 0xFD || 1 || uint8_t<br />
|-<br />
| <= 0xFFFF || 3 || 0xFD followed by the length as uint16_t<br />
|-<br />
| <= 0xFFFF FFFF || 5 || 0xFE followed by the length as uint32_t<br />
|-<br />
| - || 9 || 0xFF followed by the length as uint64_t<br />
|}<br />
<br />
If you're reading the Satoshi client code (BitcoinQT) it refers to this encoding as a "CompactSize". Modern BitcoinQT also has the CVarInt class which implements an even more compact integer for the purpose of local storage (which is incompatible with "CompactSize" described here). CVarInt is not a part of the protocol.<br />
<br />
=== Variable length string ===<br />
<br />
Variable length string can be stored using a variable length integer followed by the string itself.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the string<br />
|-<br />
| ? || string || char[] || The string itself (can be empty)<br />
|}<br />
<br />
=== Network address ===<br />
<br />
When a network address is needed somewhere, this structure is used. Network addresses are not prefixed with a timestamp in the version message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || time || uint32 || the Time (version >= 31402). '''Not present in version message.'''<br />
|-<br />
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]<br />
|-<br />
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The original client only supported IPv4 and only read the last 4 bytes to get the IPv4 address. However, the IPv4 address is written into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]<br />
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).<br />
|-<br />
| 2 || port || uint16_t || port number, network byte order<br />
|}<br />
<br />
Hexdump example of Network address structure<br />
<br />
<pre><br />
0000 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0010 00 00 FF FF 0A 00 00 01 20 8D ........ .<br />
<br />
Network address:<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK: see services listed under version command)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv6: ::ffff:a00:1 or IPv4: 10.0.0.1<br />
20 8D - Port 8333<br />
</pre><br />
<br />
=== Inventory Vectors ===<br />
<br />
Inventory vectors are used for notifying other nodes about objects they have or data which is being requested.<br />
<br />
Inventory vectors consist of the following data format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || type || uint32_t || Identifies the object type linked to this inventory<br />
|-<br />
| 32 || hash || char[32] || Hash of the object<br />
|}<br />
<br />
<br />
The object type is currently defined as one of the following possibilities:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0 || ERROR || Any data of with this number may be ignored<br />
|-<br />
| 1 || MSG_TX || Hash is related to a transaction<br />
|-<br />
| 2 || MSG_BLOCK || Hash is related to a data block<br />
|-<br />
| 3 || MSG_FILTERED_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a merkleblock message rather than a block message; this only works if a bloom filter has been set.<br />
|-<br />
| 4 || MSG_CMPCT_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a cmpctblock message. See BIP 152 for more info.<br />
|}<br />
<br />
Other Data Type values are considered reserved for future implementations.<br />
<br />
=== Block Headers ===<br />
<br />
Block headers are sent in a headers packet in response to a getheaders message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Will overflow in 2106<ref>https://en.wikipedia.org/wiki/Unix_time#Notable_events_in_Unix_time</ref>)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 1 || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries, this value is always 0<br />
|}<br />
<br />
cf. [[Block hashing algorithm]]<br />
<br />
=== PrefilledTransaction ===<br />
<br />
A PrefilledTransaction structure is used in HeaderAndShortIDs to provide a list of a few transactions explicitly.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| index || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1, 3 bytes || Compact Size, differentially encoded since the last PrefilledTransaction in a list || The index into the block at which this transaction is<br />
|-<br />
| tx || Transaction || variable || As encoded in "tx" messages || The transaction which is in the block at index index.<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== HeaderAndShortIDs ===<br />
<br />
A HeaderAndShortIDs structure is used to relay a block header, the short transactions IDs used for matching already-available transactions, and a select few transactions which we expect a peer may be missing.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| header || Block header || 80 bytes || First 80 bytes of the block as defined by the encoding used by "block" messages || The header of the block being provided<br />
|-<br />
| nonce || uint64_t || 8 bytes || Little Endian || A nonce for use in short transaction ID calculations<br />
|-<br />
| shortids_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of short transaction IDs in shortids (ie block tx count - prefilledtxn_length)<br />
|-<br />
| shortids || List of 6-byte integers || 6*shortids_length bytes || Little Endian || The short transaction IDs calculated from the transactions which were not provided explicitly in prefilledtxn<br />
|-<br />
| prefilledtxn_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of prefilled transactions in prefilledtxn (ie block tx count - shortids_length)<br />
|-<br />
| prefilledtxn || List of PrefilledTransactions || variable size*prefilledtxn_length || As defined by PrefilledTransaction definition, above || Used to provide the coinbase transaction and a select few which we expect a peer may be missing<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== BlockTransactionsRequest ===<br />
<br />
A BlockTransactionsRequest structure is used to list transaction indexes in a block being requested.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| blockhash || Binary blob || 32 bytes || The output from a double-SHA256 of the block header, as used elsewhere || The blockhash of the block which the transactions being requested are in<br />
|-<br />
| indexes_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of transactions being requested<br />
|-<br />
| indexes || List of CompactSizes || 1 or 3 bytes*indexes_length || Differentially encoded || The indexes of the transactions being requested in the block<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== BlockTransactions ===<br />
<br />
A BlockTransactions structure is used to provide some of the transactions in a block, as requested.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| blockhash || Binary blob || 32 bytes || The output from a double-SHA256 of the block header, as used elsewhere || The blockhash of the block which the transactions being provided are in<br />
|-<br />
| transactions_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of transactions provided<br />
|-<br />
| transactions || List of Transactions || variable || As encoded in "tx" messages || The transactions provided<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== Short transaction IDs ===<br />
<br />
Short transaction IDs are used to represent a transaction without sending a full 256-bit hash. They are calculated by:<br />
<br />
# single-SHA256 hashing the block header with the nonce appended (in little-endian)<br />
# Running SipHash-2-4 with the input being the transaction ID and the keys (k0/k1) set to the first two little-endian 64-bit integers from the above hash, respectively.<br />
# Dropping the 2 most significant bytes from the SipHash output to make it 6 bytes.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
== Message types ==<br />
<br />
=== version ===<br />
<br />
When a node creates an outgoing connection, it will immediately [[Version Handshake|advertise]] its version. The remote node will respond with its version. No further communication is possible until both peers have exchanged their version.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Identifies protocol version being used by the node<br />
|-<br />
| 8 || services || uint64_t || bitfield of features to be enabled for this connection<br />
|-<br />
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds<br />
|-<br />
| 26 || addr_recv || [[#Network address|net_addr]] || The network address of the node receiving this message<br />
|-<br />
|colspan="4"| Fields below require version ≥ 106<br />
|-<br />
| 26 || addr_from || [[#Network address|net_addr]] || The network address of the node emitting this message<br />
|-<br />
| 8 || nonce || uint64_t || Node random nonce, randomly generated every time a version packet is sent. This nonce is used to detect connections to self.<br />
|-<br />
| ? || user_agent || [[#Variable length string|var_str]] || [https://github.com/bitcoin/bips/blob/master/bip-0014.mediawiki User Agent] (0x00 if string is 0 bytes long)<br />
|-<br />
| 4 || start_height || int32_t || The last block received by the emitting node<br />
|-<br />
|colspan="4"| Fields below require version ≥ 70001<br />
|-<br />
| 1 || relay || bool || Whether the remote peer should announce relayed transactions or not, see [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037]<br />
|}<br />
<br />
A "verack" packet shall be sent if the version packet was accepted.<br />
<br />
The following services are currently assigned:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 1 || NODE_NETWORK || This node can be asked for full blocks instead of just headers.<br />
|}<br />
<br />
Hexdump example of version message (OBSOLETE EXAMPLE: This example lacks a checksum and user-agent):<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....<br />
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........<br />
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............<br />
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................<br />
0040 20 8D 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,<br />
0060 3A B4 57 13 00 55 81 01 00 :.W..U...<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
55 00 00 00 - Payload is 85 bytes long<br />
- No checksum in version message until 20 February 2012. See https://bitcointalk.org/index.php?topic=55852.0<br />
Version message:<br />
9C 7C 00 00 - 31900 (version 0.3.19)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
E6 15 10 4D 00 00 00 00 - Mon Dec 20 21:50:14 EST 2010<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 20 8D - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D - Sender address info - see Network Address<br />
DD 9D 20 2C 3A B4 57 13 - Node random unique ID<br />
00 - "" sub-version string (string is 0 bytes long)<br />
55 81 01 00 - Last block sending node has is block #98645<br />
</pre><br />
<br />
And here's a modern (60002) protocol version client advertising itself to a local peer...<br />
<br />
Newer protocol includes the checksum now, this is from a mainline (satoshi) client during <br />
an outgoing connection to another local client, notice that it does not fill out the <br />
address information at all when the source or destination is "unroutable".<br />
<br />
<pre><br />
<br />
0000 f9 be b4 d9 76 65 72 73 69 6f 6e 00 00 00 00 00 ....version.....<br />
0010 64 00 00 00 35 8d 49 32 62 ea 00 00 01 00 00 00 d...5.I2b.......<br />
0020 00 00 00 00 11 b2 d0 50 00 00 00 00 01 00 00 00 .......P........<br />
0030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ff ff ................<br />
0040 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 00 00 00 00 ff ff 00 00 00 00 00 00 ................<br />
0060 3b 2e b3 5d 8c e6 17 65 0f 2f 53 61 74 6f 73 68 ;..]...e./Satosh<br />
0070 69 3a 30 2e 37 2e 32 2f c0 3e 03 00 i:0.7.2/.>..<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
64 00 00 00 - Payload is 100 bytes long<br />
3B 64 8D 5A - payload checksum<br />
<br />
Version message:<br />
62 EA 00 00 - 60002 (protocol version 60002)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
11 B2 D0 50 00 00 00 00 - Tue Dec 18 10:12:33 PST 2012<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Sender address info - see Network Address<br />
3B 2E B3 5D 8C E6 17 65 - Node ID<br />
0F 2F 53 61 74 6F 73 68 69 3A 30 2E 37 2E 32 2F - "/Satoshi:0.7.2/" sub-version string (string is 15 bytes long)<br />
C0 3E 03 00 - Last block sending node has is block #212672<br />
</pre><br />
<br />
=== verack ===<br />
<br />
The ''verack'' message is sent in reply to ''[[#version|version]]''. This message consists of only a [[#Message structure|message header]] with the command string "verack".<br />
<br />
Hexdump of the verack message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......<br />
0010 00 00 00 00 5D F6 E0 E2 ........<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 61 63 6B 00 00 00 00 00 00 - "verack" command<br />
00 00 00 00 - Payload is 0 bytes long<br />
5D F6 E0 E2 - Checksum<br />
</pre><br />
<br />
=== addr ===<br />
<br />
Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours<br />
<br />
Payload:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of address entries (max: 1000)<br />
|-<br />
| 30x? || addr_list || (uint32_t + [[#Network address|net_addr]])[] || Address of other nodes on the network. version < 209 will only read the first one. The uint32_t is a timestamp (see note below).<br />
|}<br />
<br />
'''Note''': Starting version 31402, addresses are prefixed with a timestamp. If no timestamp is present, the addresses should not be relayed to other peers, unless it is indeed confirmed they are up.<br />
<br />
Hexdump example of ''addr'' message:<br />
<pre><br />
0000 F9 BE B4 D9 61 64 64 72 00 00 00 00 00 00 00 00 ....addr........<br />
0010 1F 00 00 00 ED 52 39 9B 01 E2 15 10 4D 01 00 00 .....R9.....M...<br />
0020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF ................<br />
0030 FF 0A 00 00 01 20 8D ..... .<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
61 64 64 72 00 00 00 00 00 00 00 00 - "addr"<br />
1F 00 00 00 - payload is 31 bytes long<br />
ED 52 39 9B - checksum of payload<br />
<br />
Payload:<br />
01 - 1 address in this message<br />
<br />
Address:<br />
E2 15 10 4D - Mon Dec 20 21:50:10 EST 2010 (only when version is >= 31402)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK service - see version message)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv4: 10.0.0.1, IPv6: ::ffff:10.0.0.1 (IPv4-mapped IPv6 address)<br />
20 8D - port 8333<br />
</pre><br />
<br />
=== inv ===<br />
<br />
Allows a node to advertise its knowledge of one or more objects. It can be received unsolicited, or in reply to ''getblocks''.<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getdata ===<br />
<br />
getdata is used in response to inv, to retrieve the content of a specific object, and is usually sent after receiving an ''inv'' packet, after filtering known elements. It can be used to retrieve transactions, but only if they are in the memory pool or relay set - arbitrary access to transactions in the chain is not allowed to avoid having clients start to depend on nodes having full transaction indexes (which modern nodes do not).<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== notfound ===<br />
<br />
notfound is a response to a getdata, sent if any requested data items could not be relayed, for example, because the requested transaction was not in the memory pool or relay set.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getblocks ===<br />
<br />
Return an ''inv'' packet containing the list of blocks starting right after the last known hash in the block locator object, up to hash_stop or 500 blocks, whichever comes first. <br />
<br />
The locator hashes are processed by a node in the order as they appear in the message. If a block hash is found in the node's main chain, the list of its children is returned back via the ''inv'' message and the remaining locators are ignored, no matter if the requested limit was reached, or not.<br />
<br />
To receive the next blocks hashes, one needs to issue getblocks again with a new block locator object. Keep in mind that some clients may provide blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block; set to zero to get as many blocks as possible (500)<br />
|}<br />
<br />
To create the block locator hashes, keep pushing hashes until you go back to the genesis block. After pushing 10 hashes back, the step backwards doubles every loop:<br />
<br />
<pre><br />
// From libbitcoin which is under AGPL<br />
std::vector<size_t> block_locator_indexes(size_t top_height)<br />
{<br />
std::vector<size_t> indexes;<br />
<br />
// Modify the step in the iteration.<br />
int64_t step = 1;<br />
<br />
// Start at the top of the chain and work backwards.<br />
for (auto index = (int64_t)top_height; index > 0; index -= step)<br />
{<br />
// Push top 10 indexes first, then back off exponentially.<br />
if (indexes.size() >= 10)<br />
step *= 2;<br />
<br />
indexes.push_back((size_t)index);<br />
}<br />
<br />
// Push the genesis block index.<br />
indexes.push_back(0);<br />
return indexes;<br />
}<br />
</pre><br />
<br />
Note that it is allowed to send in fewer known hashes down to a minimum of just one hash. However, the purpose of the block locator object is to detect a wrong branch in the caller's main chain. If the peer detects that you are off the main chain, it will send in block hashes which are earlier than your last known block. So if you just send in your last known hash and it is off the main chain, the peer starts over at block #1.<br />
<br />
=== getheaders ===<br />
<br />
Return a ''headers'' packet containing the headers of blocks starting right after the last known hash in the block locator object, up to hash_stop or 2000 blocks, whichever comes first. To receive the next block headers, one needs to issue getheaders again with a new block locator object. The ''getheaders'' command is used by thin clients to quickly download the block chain where the contents of the transactions would be irrelevant (because they are not ours). Keep in mind that some clients may provide headers of blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block header; set to zero to get as many blocks as possible (2000)<br />
|}<br />
<br />
For the block locator object in this packet, the same rules apply as for the [[Protocol_documentation#getblocks|getblocks]] packet.<br />
<br />
=== tx ===<br />
<br />
''tx'' describes a bitcoin transaction, in reply to ''[[#getdata|getdata]]''<br />
<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Transaction data format version (note, this is signed)<br />
|-<br />
| 1+ || tx_in count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction inputs<br />
|-<br />
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins<br />
|-<br />
| 1+ || tx_out count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction outputs<br />
|-<br />
| 9+ || tx_out || tx_out[] || A list of 1 or more transaction outputs or destinations for coins<br />
|-<br />
| 4 || lock_time || uint32_t || The block number or timestamp at which this transaction is locked:<br />
{|class="wikitable"<br />
! Value !! Description<br />
|-<br />
| 0 || Not locked<br />
|-<br />
| < 500000000 || Block number at which this transaction is locked<br />
|-<br />
| >= 500000000 || UNIX timestamp at which this transaction is locked<br />
|}<br />
If all TxIn inputs have final (0xffffffff) sequence numbers then lock_time is irrelevant. Otherwise, the transaction may not be added to a block until after lock_time (see [[NLockTime]]).<br />
<br />
|}<br />
<br />
TxIn consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 36 || previous_output || outpoint || The previous output transaction reference, as an OutPoint structure<br />
|-<br />
| 1+ || script length || [[Protocol_documentation#Variable_length_integer|var_int]] || The length of the signature script<br />
|-<br />
| ? || signature script || uchar[] || Computational Script for confirming transaction authorization<br />
|-<br />
| 4 || [http://bitcoin.stackexchange.com/q/2025/323 sequence] || uint32_t || Transaction version as defined by the sender. Intended for "replacement" of transactions when information is updated before inclusion into a block.<br />
|}<br />
<br />
The OutPoint structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 32 || hash || char[32] || The hash of the referenced transaction.<br />
|-<br />
| 4 || index || uint32_t || The index of the specific output in the transaction. The first output is 0, etc.<br />
|}<br />
<br />
The Script structure consists of a series of pieces of information and operations related to the value of the transaction.<br />
<br />
(Structure to be expanded in the future… see script.h and script.cpp and [[Script]] for more information)<br />
<br />
The TxOut structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || value || int64_t || Transaction Value<br />
|-<br />
| 1+ || pk_script length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the pk_script<br />
|-<br />
| ? || pk_script || uchar[] || Usually contains the public key as a Bitcoin script setting up conditions to claim this output.<br />
|}<br />
<br />
Example ''tx'' message:<br />
<pre><br />
000000 F9 BE B4 D9 74 78 00 00 00 00 00 00 00 00 00 00 ....tx..........<br />
000010 02 01 00 00 E2 93 CD BE 01 00 00 00 01 6D BD DB .............m..<br />
000020 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D 12 66 E9 .[...Q........f.<br />
000030 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29 00 00 00 .;P......j.6)...<br />
000040 00 8B 48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 ..H0E.!..X..r...<br />
000050 C7 36 7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A .6zz%;..R#...h.:<br />
000060 59 23 3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 Y#?E.W... Y.....<br />
000070 0E 41 83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D .A.z.X.z...XN...<br />
000080 35 BD 96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF 5...6..;...A....<br />
000090 C9 7E F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 .~.6.m...@..!...<br />
0000A0 2A CD 2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC *.+..].}Y... ...<br />
0000B0 4E 02 53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F N.S..=7.o...Q...<br />
0000C0 14 04 2F 46 61 4A 4C 70 C0 F1 4B EF F5 FF FF FF ../FaJLp..K.....<br />
0000D0 FF 02 40 4B 4C 00 00 00 00 00 19 76 A9 14 1A A0 ..@KL......v....<br />
0000E0 CD 1C BE A6 E7 45 8A 7A BA D5 12 A9 D9 EA 1A FB .....E.z........<br />
0000F0 22 5E 88 AC 80 FA E9 C7 00 00 00 00 19 76 A9 14 "^...........v..<br />
000100 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E FD A0 B7 ..[.Cj.....H^...<br />
000110 8B 4E CC 52 88 AC 00 00 00 00 .N.R......<br />
<br />
<br />
Message header:<br />
F9 BE B4 D9 - main network magic bytes<br />
74 78 00 00 00 00 00 00 00 00 00 00 - "tx" command<br />
02 01 00 00 - payload is 258 bytes long<br />
E2 93 CD BE - checksum of payload<br />
<br />
Transaction:<br />
01 00 00 00 - version<br />
<br />
Inputs:<br />
01 - number of transaction inputs<br />
<br />
Input 1:<br />
6D BD DB 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D - previous output (outpoint)<br />
12 66 E9 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29<br />
00 00 00 00<br />
<br />
8B - script is 139 bytes long<br />
<br />
48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 C7 36 - signature script (scriptSig)<br />
7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A 59 23<br />
3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 0E 41<br />
83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D 35 BD<br />
96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF C9 7E<br />
F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 2A CD<br />
2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC 4E 02<br />
53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F 14 04<br />
2F 46 61 4A 4C 70 C0 F1 4B EF F5<br />
<br />
FF FF FF FF - sequence<br />
<br />
Outputs:<br />
02 - 2 Output Transactions<br />
<br />
Output 1:<br />
40 4B 4C 00 00 00 00 00 - 0.05 BTC (5000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 1A A0 CD 1C BE A6 E7 45 8A 7A BA D5 12 - pk_script<br />
A9 D9 EA 1A FB 22 5E 88 AC<br />
<br />
Output 2:<br />
80 FA E9 C7 00 00 00 00 - 33.54 BTC (3354000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E - pk_script<br />
FD A0 B7 8B 4E CC 52 88 AC<br />
<br />
Locktime:<br />
00 00 00 00 - lock time<br />
</pre><br />
<br />
=== block ===<br />
<br />
The '''block''' message is sent in response to a getdata message which requests transaction information from a block hash.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A Unix timestamp recording when this block was created (Currently limited to dates before the year 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated [[Difficulty|difficulty target]] being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| ? || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries<br />
|-<br />
| ? || txns || tx[] || Block transactions, in format of "tx" command<br />
|}<br />
<br />
The SHA256 hash that identifies each block (and which must have a run of 0 bits) is calculated from the first 6 fields of this structure (version, prev_block, merkle_root, timestamp, bits, nonce, and standard SHA256 padding, making two 64-byte chunks in all) and ''not'' from the complete block. To calculate the hash, only two chunks need to be processed by the SHA256 algorithm. Since the ''nonce'' field is in the second chunk, the first chunk stays constant during mining and therefore only the second chunk needs to be processed. However, a Bitcoin hash is the hash of the hash, so two SHA256 rounds are needed for each mining iteration.<br />
See [[Block hashing algorithm]] for details and an example.<br />
<br />
=== headers ===<br />
<br />
The ''headers'' packet returns block headers in response to a ''getheaders'' packet. <br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of block headers<br />
|-<br />
| 81x? || headers || [[Protocol_documentation#Block_Headers|block_header]][] || [[Protocol_documentation#Block_Headers|Block headers]]<br />
|}<br />
<br />
Note that the block headers in this packet include a transaction count (a var_int, so there can be more than 81 bytes per header) as opposed to the block headers that are hashed by miners.<br />
<br />
=== getaddr ===<br />
<br />
The getaddr message sends a request to a node asking for information about known active peers to help with finding potential nodes in the network. The response to receiving this message is to transmit one or more addr messages with one or more peers from a database of known active peers. The typical presumption is that a node is likely to be active if it has been sending a message within the last three hours.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
=== mempool ===<br />
<br />
The mempool message sends a request to a node asking for information about transactions it has verified but which have not yet confirmed. The response to receiving this message is an inv message containing the transaction hashes for all the transactions in the node's mempool.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
It is specified in [https://github.com/bitcoin/bips/blob/master/bip-0035.mediawiki BIP 35]. Since [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 37], if a [[Protocol_documentation#filterload.2C_filteradd.2C_filterclear.2C_merkleblock|bloom filter]] is loaded, only transactions matching the filter are replied.<br />
<br />
=== checkorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== submitorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== reply ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== ping ===<br />
<br />
The ''ping'' message is sent primarily to confirm that the TCP/IP connection is still valid. An error in transmission is presumed to be a closed connection and the address is removed as a current peer.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || random nonce<br />
|}<br />
<br />
=== pong ===<br />
<br />
The ''pong'' message is sent in response to a ''ping'' message. In modern protocol versions, a ''pong'' response is generated using a nonce included in the ping.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || nonce from ping<br />
|}<br />
<br />
<br />
=== reject===<br />
<br />
The ''reject'' message is sent when messages are rejected.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || message || var_str || type of message rejected<br />
|-<br />
| 1 || ccode || char || code relating to rejected message<br />
|-<br />
| 1+ || reason || var_str || text version of reason for rejection<br />
|-<br />
| 0+ || data || char || Optional extra data provided by some errors. Currently, all errors which provide this field fill it with the TXID or block header hash of the object being rejected, so the field is 32 bytes.<br />
|}<br />
<br />
CCodes<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0x01 || REJECT_MALFORMED|| <br />
|-<br />
| 0x10 || REJECT_INVALID ||<br />
|-<br />
| 0x11 || REJECT_OBSOLETE ||<br />
|-<br />
| 0x12 || REJECT_DUPLICATE ||<br />
|-<br />
| 0x40 || REJECT_NONSTANDARD ||<br />
|-<br />
| 0x41 || REJECT_DUST ||<br />
|-<br />
| 0x42 || REJECT_INSUFFICIENTFEE ||<br />
|-<br />
| 0x43 || REJECT_CHECKPOINT ||<br />
|}<br />
<br />
=== filterload, filteradd, filterclear, merkleblock ===<br />
<br />
These messages are related to Bloom filtering of connections and are defined in [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037].<br />
<br />
<br />
The <code>filterload</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || filter || uint8_t[] || The filter itself is simply a bit field of arbitrary byte-aligned size. The maximum size is 36,000 bytes.<br />
|-<br />
| 4 || nHashFuncs || uint32_t || The number of hash functions to use in this filter. The maximum value allowed in this field is 50.<br />
|-<br />
| 4 || nTweak || uint32_t || A random value to add to the seed value in the hash function used by the bloom filter.<br />
|-<br />
| 1 || nFlags || uint8_t || A set of flags that control how matched items are added to the filter.<br />
|}<br />
<br />
See below for a description of the Bloom filter algorithm and how to select nHashFuncs and filter size for a desired false positive rate.<br />
<br />
Upon receiving a <code>filterload</code> command, the remote peer will immediately restrict the broadcast transactions it announces (in inv packets) to transactions matching the filter, where the matching algorithm is specified below. The flags control the update behaviour of the matching algorithm.<br />
<br />
The <code>filteradd</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || data || uint8_t[] || The data element to add to the current filter.<br />
|}<br />
<br />
The data field must be smaller than or equal to 520 bytes in size (the maximum size of any potentially matched object).<br />
<br />
The given data element will be added to the Bloom filter. A filter must have been previously provided using <code>filterload</code>. This command is useful if a new key or script is added to a clients wallet whilst it has connections to the network open, it avoids the need to re-calculate and send an entirely new filter to every peer (though doing so is usually advisable to maintain anonymity).<br />
<br />
The <code>filterclear</code> command has no arguments at all.<br />
<br />
After a filter has been set, nodes don't merely stop announcing non-matching transactions, they can also serve filtered blocks. A filtered block is defined by the <code>merkleblock</code> message and is defined like this:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information, based upon the software version creating this block (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Limited to 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 4 || total_transactions || uint32_t || Number of transactions in the block (including unmatched ones)<br />
|-<br />
| ? || hashes || uint256[] || hashes in depth-first order (including standard varint size prefix)<br />
|-<br />
| ? || flags || byte[] || flag bits, packed per 8 in a byte, least significant bit first (including standard varint size prefix)<br />
|}<br />
<br />
=== alert ===<br />
<br />
An '''alert''' is sent between nodes to send a general notification message throughout the network. If the alert can be confirmed with the signature as having come from the core development group of the Bitcoin software, the message is suggested to be displayed for end-users. Attempts to perform transactions, particularly automated transactions through the client, are suggested to be halted. The text in the Message string should be relayed to log files and any user interfaces.<br />
<br />
Alert format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || payload || uchar[] || Serialized alert payload<br />
|-<br />
| ? || signature || uchar[] || An ECDSA signature of the message<br />
|}<br />
<br />
The developers of Satoshi's client use this public key for signing alerts:<br />
04fc9702847840aaf195de8442ebecedf5b095cdbb9bc716bda9110971b28a49e0ead8564ff0db22209e0374782c093bb899692d524e9d6a6956e7c5ecbcd68284<br />
(hash) 1AGRxqDa5WjUKBwHB9XYEjmkv1ucoUUy1s<br />
<br />
The payload is serialized into a uchar[] to ensure that versions using incompatible alert formats can still relay alerts among one another. The current alert payload format is:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || Version || int32_t || Alert format version<br />
|-<br />
| 8 || RelayUntil || int64_t || The timestamp beyond which nodes should stop relaying this alert<br />
|-<br />
| 8 || Expiration || int64_t || The timestamp beyond which this alert is no longer in effect and should be ignored<br />
|-<br />
| 4 || ID || int32_t || A unique ID number for this alert<br />
|-<br />
| 4 || Cancel || int32_t || All alerts with an ID number less than or equal to this number should be cancelled: deleted and not accepted in the future<br />
|-<br />
| ? || setCancel || set<int32_t> || All alert IDs contained in this set should be cancelled as above<br />
|-<br />
| 4 || MinVer || int32_t || This alert only applies to versions greater than or equal to this version. Other versions should still relay it.<br />
|-<br />
| 4 || MaxVer || int32_t || This alert only applies to versions less than or equal to this version. Other versions should still relay it.<br />
|-<br />
| ? || setSubVer || set<string> || If this set contains any elements, then only nodes that have their subVer contained in this set are affected by the alert. Other versions should still relay it.<br />
|-<br />
| 4 || Priority || int32_t || Relative priority compared to other alerts<br />
|-<br />
| ? || Comment || string || A comment on the alert that is not displayed<br />
|-<br />
| ? || StatusBar || string || The alert message that is displayed to the user<br />
|-<br />
| ? || Reserved || string || Reserved<br />
|}<br />
<br />
Note: '''set<''type''>''' in the table above is a [[#Variable length integer | variable length integer]] followed by the number of fields of the given ''type'' (either int32_t or [[#Variable length string | variable length string]])<br />
<br />
Sample alert (no message header):<br />
73010000003766404f00000000b305434f00000000f2030000f1030000001027000048ee0000<br />
0064000000004653656520626974636f696e2e6f72672f666562323020696620796f75206861<br />
76652074726f75626c6520636f6e6e656374696e672061667465722032302046656272756172<br />
79004730450221008389df45f0703f39ec8c1cc42c13810ffcae14995bb648340219e353b63b<br />
53eb022009ec65e1c1aaeec1fd334c6b684bde2b3f573060d5b70c3a46723326e4e8a4f1<br />
<br />
Version: 1<br />
RelayUntil: 1329620535<br />
Expiration: 1329792435<br />
ID: 1010<br />
Cancel: 1009<br />
setCancel: <empty><br />
MinVer: 10000<br />
MaxVer: 61000<br />
setSubVer: <empty><br />
Priority: 100<br />
Comment: <empty><br />
StatusBar: "See bitcoin.org/feb20 if you have trouble connecting after 20 February"<br />
Reserved: <empty><br />
<br />
=== sendheaders ===<br />
<br />
Request for Direct headers announcement. <br />
<br />
Upon receipt of this message, the node is be permitted, but not required, to announce new blocks by '''headers''' command (instead of '''inv''' command).<br />
<br />
This message is supported by the protocol version >= 70012 or Bitcoin Core version >= 0.12.0.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0130.mediawiki BIP 130] for more information.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
<br />
=== feefilter ===<br />
<br />
The payload is always 8 bytes long and it encodes 64 bit integer value (LSB / little endian) of '''feerate'''.<br />
The value represents a minimal fee and is expressed in satoshis per 1000 bytes.<br />
<br />
Upon receipt of a "feefilter" message, the node will be permitted, but not required, to filter transaction invs for transactions that fall below the feerate provided in the feefilter message interpreted as satoshis per kilobyte.<br />
<br />
The fee filter is additive with a bloom filter for transactions so if an SPV client were to load a bloom filter and send a feefilter message, transactions would only be relayed if they passed both filters.<br />
<br />
Inv's generated from a mempool message are also subject to a fee filter if it exists.<br />
<br />
Feature discovery is enabled by checking protocol version >= 70013<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0133.mediawiki BIP 133] for more information.<br />
<br />
=== sendcmpct ===<br />
<br />
# The sendcmpct message is defined as a message containing a 1-byte integer followed by a 8-byte integer where pchCommand == "sendcmpct".<br />
# The first integer SHALL be interpreted as a boolean (and MUST have a value of either 1 or 0)<br />
# The second integer SHALL be interpreted as a little-endian version number. Nodes sending a sendcmpct message MUST currently set this value to 1.<br />
# Upon receipt of a "sendcmpct" message with the first and second integers set to 1, the node SHOULD announce new blocks by sending a cmpctblock message.<br />
# Upon receipt of a "sendcmpct" message with the first integer set to 0, the node SHOULD NOT announce new blocks by sending a cmpctblock message, but SHOULD announce new blocks by sending invs or headers, as defined by BIP130.<br />
# Upon receipt of a "sendcmpct" message with the second integer set to something other than 1, nodes MUST treat the peer as if they had not received the message (as it indicates the peer will provide an unexpected encoding in <br />
# cmpctblock, and/or other, messages). This allows future versions to send duplicate sendcmpct messages with different versions as a part of a version handshake for future versions.<br />
# Nodes SHOULD check for a protocol version of >= 70014 before sending sendcmpct messages.<br />
# Nodes MUST NOT send a request for a MSG_CMPCT_BLOCK object to a peer before having received a sendcmpct message from that peer.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== cmpctblock ===<br />
<br />
# The cmpctblock message is defined as as a message containing a serialized HeaderAndShortIDs message and pchCommand == "cmpctblock".<br />
# Upon receipt of a cmpctblock message after sending a sendcmpct message, nodes SHOULD calculate the short transaction ID for each unconfirmed transaction they have available (ie in their mempool) and compare each to each short transaction ID in the cmpctblock message.<br />
# After finding already-available transactions, nodes which do not have all transactions available to reconstruct the full block SHOULD request the missing transactions using a getblocktxn message.<br />
# A node MUST NOT send a cmpctblock message unless they are able to respond to a getblocktxn message which requests every transaction in the block.<br />
# A node MUST NOT send a cmpctblock message without having validated that the header properly commits to each transaction in the block, and properly builds on top of the existing chain with a valid proof-of-work. A node MAY send a cmpctblock before validating that each transaction in the block validly spends existing UTXO set entries.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== getblocktxn ===<br />
<br />
# The getblocktxn message is defined as as a message containing a serialized BlockTransactionsRequest message and pchCommand == "getblocktxn".<br />
# Upon receipt of a properly-formatted getblocktxnmessage, nodes which recently provided the sender of such a message a cmpctblock for the block hash identified in this message MUST respond with an appropriate blocktxn message. Such a blocktxn message MUST contain exactly and only each transaction which is present in the appropriate block at the index specified in the getblocktxn indexes list, in the order requested.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== blocktxn ===<br />
<br />
# The blocktxn message is defined as as a message containing a serialized BlockTransactions message and pchCommand == "blocktxn".<br />
# Upon receipt of a properly-formatted requested blocktxn message, nodes SHOULD attempt to reconstruct the full block by:<br />
# Taking the prefilledtxn transactions from the original cmpctblock and placing them in the marked positions.<br />
# For each short transaction ID from the original cmpctblock, in order, find the corresponding transaction either from the blocktxn message or from other sources and place it in the first available position in the block.<br />
# Once the block has been reconstructed, it shall be processed as normal, keeping in mind that short transaction IDs are expected to occasionally collide, and that nodes MUST NOT be penalized for such collisions, wherever they # appear.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
== Scripting ==<br />
<br />
See [[script]].<br />
<br />
==See Also==<br />
<br />
* [[Network]]<br />
* [[Protocol rules]]<br />
* [[Hardfork Wishlist]]<br />
* [https://bitcoin.org/en/developer-documentation Developer Documentation on bitcoin.org]<br />
* Bitcoin dissectors for Wireshark: https://github.com/lbotsch/wireshark-bitcoin https://github.com/op-sig/bitcoin-wireshark-dissector<br />
<br />
==References==<br />
<references /><br />
<br />
[[zh-cn:协议说明]]<br />
[[Category:Technical]]<br />
[[Category:Developer]]<br />
<br />
{{Bitcoin Core documentation}}</div>Tonikthttps://en.bitcoin.it/w/index.php?title=Protocol_documentation&diff=61491Protocol documentation2016-08-25T12:39:51Z<p>Tonikt: /* BlockTransactionsRequest */</p>
<hr />
<div>This page ''describes'' the behavior of the [[Original Bitcoin client|reference client]]. The Bitcoin protocol is specified by the behavior of the reference client, not by this page. In particular, while this page is quite complete in describing the network protocol, it does not attempt to list all of the rules for block or transaction validity.<br />
<br />
Type names used in this documentation are from the C99 standard.<br />
<br />
For protocol used in mining, see [[getblocktemplate]].<br />
<br />
==Common standards==<br />
<br />
=== Hashes ===<br />
<br />
Usually, when a hash is computed within bitcoin, it is computed twice. Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-256] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when a shorter hash is desirable (for example when creating a bitcoin address).<br />
<br />
Example of double-SHA-256 encoding of string "hello":<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round of sha-256)<br />
9595c9df90075148eb06860365df33584b75bff782a510c6cd4883a419833d50 (second round of sha-256)<br />
<br />
For bitcoin addresses (RIPEMD-160) this would give:<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round is sha-256)<br />
b6a9c8c230722b7c748331a8b450f05566dc7d0f (with ripemd-160)<br />
<br />
=== Merkle Trees ===<br />
<br />
Merkle trees are binary trees of hashes. Merkle trees in bitcoin use a '''double''' SHA-256, the SHA-256 hash of the SHA-256 hash of something.<br />
<br />
If, when forming a row in the tree (other than the root of the tree), it would have an odd number of elements, the final double-hash is duplicated to ensure that the row has an even number of hashes.<br />
<br />
First form the bottom row of the tree with the ordered double-SHA-256 hashes of the byte streams of the transactions in the block.<br />
<br />
Then the row above it consists of half that number of hashes. Each entry is the double-SHA-256 of the 64-byte concatenation of the corresponding two hashes below it in the tree.<br />
<br />
This procedure repeats recursively until we reach a row consisting of just a single double-hash. This is the '''Merkle root''' of the tree.<br />
<br />
For example, imagine a block with three transactions ''a'', ''b'' and ''c''. The Merkle tree is: <br />
<br />
d1 = dhash(a)<br />
d2 = dhash(b)<br />
d3 = dhash(c)<br />
d4 = dhash(c) # a, b, c are 3. that's an odd number, so we take the c twice<br />
<br />
d5 = dhash(d1 concat d2)<br />
d6 = dhash(d3 concat d4)<br />
<br />
d7 = dhash(d5 concat d6)<br />
<br />
where<br />
<br />
dhash(a) = sha256(sha256(a))<br />
<br />
''d7'' is the Merkle root of the 3 transactions in this block.<br />
<br />
Note: Hashes in Merkle Tree displayed in the [[Block Explorer]] are of little-endian notation. For some implementations and [http://www.fileformat.info/tool/hash.htm calculations], the bits need to be reversed before they are hashed, and again after the hashing operation.<br />
<br />
=== Signatures ===<br />
<br />
Bitcoin uses [http://en.wikipedia.org/wiki/Elliptic_curve_cryptography Elliptic Curve] [http://en.wikipedia.org/wiki/Digital_Signature_Algorithm Digital Signature Algorithm] ([http://en.wikipedia.org/wiki/Elliptic_Curve_DSA ECDSA]) to sign transactions. <br />
<br />
For [[ECDSA]] the secp256k1 curve from http://www.secg.org/collateral/sec2_final.pdf is used.<br />
<br />
Public keys (in scripts) are given as 04 <x> <y> where ''x'' and ''y'' are 32 byte big-endian integers representing the coordinates of a point on the curve or in compressed form given as <sign> <x> where <sign> is 0x02 if ''y'' is even and 0x03 if ''y'' is odd.<br />
<br />
Signatures use [http://en.wikipedia.org/wiki/Distinguished_Encoding_Rules DER encoding] to pack the ''r'' and ''s'' components into a single byte stream (this is also what OpenSSL produces by default).<br />
<br />
=== Transaction Verification ===<br />
Transactions are cryptographically signed records that reassign ownership of Bitcoins to new addresses. Transactions have ''inputs'' - records which reference the funds from other previous transactions - and ''outputs'' - records which determine the new owner of the transferred Bitcoins, and which will be referenced as inputs in future transactions as those funds are respent.<br />
<br />
Each ''input'' must have a cryptographic digital signature that unlocks the funds from the prior transaction. Only the person possessing the appropriate [[private key]] is able to create a satisfactory signature; this in effect ensures that funds can only be spent by their owners.<br />
<br />
Each ''output'' determines which Bitcoin address (or other criteria, see [[Script]]) is the recipient of the funds.<br />
<br />
In a transaction, the sum of all inputs must be equal to or greater than the sum of all outputs. If the inputs exceed the outputs, the difference is considered a [[transaction fee]], and is redeemable by whoever first includes the transaction into the block chain.<br />
<br />
A special kind of transaction, called a [[coinbase transaction]], has no inputs. It is created by [[miners]], and there is one coinbase transaction per block. Because each block comes with a reward of newly created Bitcoins (e.g. 50 BTC for the first 210,000 blocks), the first transaction of a block is, with few exceptions, the transaction that grants those coins to their recipient (the miner). In addition to the newly created Bitcoins, the coinbase transaction is also used for assigning the recipient of any transaction fees that were paid within the other transactions being included in the same block. The coinbase transaction can assign the entire reward to a single Bitcoin address, or split it in portions among multiple addresses, just like any other transaction. Coinbase transactions always contain outputs totalling the sum of the block reward plus all transaction fees collected from the other transactions in the same block.<br />
<br />
The [[coinbase transaction]] in block zero cannot be spent. This is due to a quirk of the reference client implementation that would open the potential for a block chain fork if some nodes accepted the spend and others did not<ref>[http://bitcointalk.org/index.php?topic=119645.msg1288552#msg1288552 Block 0 Network Fork]</ref>.<br />
<br />
Most Bitcoin outputs encumber the newly transferred coins with a single ECDSA private key. The actual record saved with inputs and outputs isn't necessarily a key, but a ''script''. Bitcoin uses an interpreted scripting system to determine whether an output's criteria have been satisfied, with which more complex operations are possible, such as outputs that require two ECDSA signatures, or two-of-three-signature schemes. An output that references a single Bitcoin address is a ''typical'' output; an output actually contains this information in the form of a script that requires a single ECDSA signature (see [[OP_CHECKSIG]]). The output script specifies what must be provided to unlock the funds later, and when the time comes in the future to spend the transaction in another input, that input must provide all of the thing(s) that satisfy the requirements defined by the original output script.<br />
<br />
=== Addresses ===<br />
<br />
A bitcoin address is in fact the hash of a ECDSA public key, computed this way:<br />
<br />
Version = 1 byte of 0 (zero); on the test network, this is 1 byte of 111<br />
Key hash = Version concatenated with RIPEMD-160(SHA-256(public key))<br />
Checksum = 1st 4 bytes of SHA-256(SHA-256(Key hash))<br />
Bitcoin Address = Base58Encode(Key hash concatenated with Checksum)<br />
<br />
The Base58 encoding used is home made, and has some differences. Especially, leading zeroes are kept as single zeroes when conversion happens.<br />
<br />
== Common structures ==<br />
<br />
Almost all integers are encoded in little endian. Only IP or port number are encoded big endian.<br />
<br />
=== Message structure ===<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown<br />
|-<br />
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| 4 || length || uint32_t || Length of payload in number of bytes<br />
|-<br />
| 4 || checksum || uint32_t || First 4 bytes of sha256(sha256(payload))<br />
|-<br />
| ? || payload || uchar[] || The actual data<br />
|}<br />
<br />
<br />
Known magic values:<br />
<br />
{|class="wikitable"<br />
! Network !! Magic value !! Sent over wire as<br />
|-<br />
| main || 0xD9B4BEF9 || F9 BE B4 D9<br />
|-<br />
| testnet || 0xDAB5BFFA || FA BF B5 DA<br />
|-<br />
| testnet3 || 0x0709110B || 0B 11 09 07<br />
|-<br />
| namecoin || 0xFEB4BEF9 || F9 BE B4 FE<br />
|}<br />
<br />
=== Variable length integer ===<br />
<br />
Integer can be encoded depending on the represented value to save space.<br />
Variable length integers always precede an array/vector of a type of data that may vary in length.<br />
Longer numbers are encoded in little endian.<br />
<br />
{|class="wikitable"<br />
! Value !! Storage length !! Format<br />
|-<br />
| < 0xFD || 1 || uint8_t<br />
|-<br />
| <= 0xFFFF || 3 || 0xFD followed by the length as uint16_t<br />
|-<br />
| <= 0xFFFF FFFF || 5 || 0xFE followed by the length as uint32_t<br />
|-<br />
| - || 9 || 0xFF followed by the length as uint64_t<br />
|}<br />
<br />
If you're reading the Satoshi client code (BitcoinQT) it refers to this encoding as a "CompactSize". Modern BitcoinQT also has the CVarInt class which implements an even more compact integer for the purpose of local storage (which is incompatible with "CompactSize" described here). CVarInt is not a part of the protocol.<br />
<br />
=== Variable length string ===<br />
<br />
Variable length string can be stored using a variable length integer followed by the string itself.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the string<br />
|-<br />
| ? || string || char[] || The string itself (can be empty)<br />
|}<br />
<br />
=== Network address ===<br />
<br />
When a network address is needed somewhere, this structure is used. Network addresses are not prefixed with a timestamp in the version message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || time || uint32 || the Time (version >= 31402). '''Not present in version message.'''<br />
|-<br />
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]<br />
|-<br />
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The original client only supported IPv4 and only read the last 4 bytes to get the IPv4 address. However, the IPv4 address is written into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]<br />
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).<br />
|-<br />
| 2 || port || uint16_t || port number, network byte order<br />
|}<br />
<br />
Hexdump example of Network address structure<br />
<br />
<pre><br />
0000 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0010 00 00 FF FF 0A 00 00 01 20 8D ........ .<br />
<br />
Network address:<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK: see services listed under version command)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv6: ::ffff:a00:1 or IPv4: 10.0.0.1<br />
20 8D - Port 8333<br />
</pre><br />
<br />
=== Inventory Vectors ===<br />
<br />
Inventory vectors are used for notifying other nodes about objects they have or data which is being requested.<br />
<br />
Inventory vectors consist of the following data format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || type || uint32_t || Identifies the object type linked to this inventory<br />
|-<br />
| 32 || hash || char[32] || Hash of the object<br />
|}<br />
<br />
<br />
The object type is currently defined as one of the following possibilities:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0 || ERROR || Any data of with this number may be ignored<br />
|-<br />
| 1 || MSG_TX || Hash is related to a transaction<br />
|-<br />
| 2 || MSG_BLOCK || Hash is related to a data block<br />
|-<br />
| 3 || MSG_FILTERED_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a merkleblock message rather than a block message; this only works if a bloom filter has been set.<br />
|-<br />
| 4 || MSG_CMPCT_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a cmpctblock message. See BIP 152 for more info.<br />
|}<br />
<br />
Other Data Type values are considered reserved for future implementations.<br />
<br />
=== Block Headers ===<br />
<br />
Block headers are sent in a headers packet in response to a getheaders message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Will overflow in 2106<ref>https://en.wikipedia.org/wiki/Unix_time#Notable_events_in_Unix_time</ref>)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 1 || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries, this value is always 0<br />
|}<br />
<br />
cf. [[Block hashing algorithm]]<br />
<br />
=== PrefilledTransaction ===<br />
<br />
A PrefilledTransaction structure is used in HeaderAndShortIDs to provide a list of a few transactions explicitly.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| index || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1, 3 bytes || Compact Size, differentially encoded since the last PrefilledTransaction in a list || The index into the block at which this transaction is<br />
|-<br />
| tx || Transaction || variable || As encoded in "tx" messages || The transaction which is in the block at index index.<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== HeaderAndShortIDs ===<br />
<br />
A HeaderAndShortIDs structure is used to relay a block header, the short transactions IDs used for matching already-available transactions, and a select few transactions which we expect a peer may be missing.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| header || Block header || 80 bytes || First 80 bytes of the block as defined by the encoding used by "block" messages || The header of the block being provided<br />
|-<br />
| nonce || uint64_t || 8 bytes || Little Endian || A nonce for use in short transaction ID calculations<br />
|-<br />
| shortids_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of short transaction IDs in shortids (ie block tx count - prefilledtxn_length)<br />
|-<br />
| shortids || List of 6-byte integers || 6*shortids_length bytes || Little Endian || The short transaction IDs calculated from the transactions which were not provided explicitly in prefilledtxn<br />
|-<br />
| prefilledtxn_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of prefilled transactions in prefilledtxn (ie block tx count - shortids_length)<br />
|-<br />
| prefilledtxn || List of PrefilledTransactions || variable size*prefilledtxn_length || As defined by PrefilledTransaction definition, above || Used to provide the coinbase transaction and a select few which we expect a peer may be missing<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== BlockTransactionsRequest ===<br />
<br />
A BlockTransactionsRequest structure is used to list transaction indexes in a block being requested.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| blockhash || Binary blob || 32 bytes || The output from a double-SHA256 of the block header, as used elsewhere || The blockhash of the block which the transactions being requested are in<br />
|-<br />
| indexes_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of transactions being requested<br />
|-<br />
| indexes || List of CompactSizes || 1 or 3 bytes*indexes_length || Differentially encoded || The indexes of the transactions being requested in the block<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== BlockTransactions ===<br />
<br />
A BlockTransactions structure is used to provide some of the transactions in a block, as requested.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== Short transaction IDs ===<br />
<br />
Short transaction IDs are used to represent a transaction without sending a full 256-bit hash. They are calculated by:<br />
<br />
# single-SHA256 hashing the block header with the nonce appended (in little-endian)<br />
# Running SipHash-2-4 with the input being the transaction ID and the keys (k0/k1) set to the first two little-endian 64-bit integers from the above hash, respectively.<br />
# Dropping the 2 most significant bytes from the SipHash output to make it 6 bytes.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
== Message types ==<br />
<br />
=== version ===<br />
<br />
When a node creates an outgoing connection, it will immediately [[Version Handshake|advertise]] its version. The remote node will respond with its version. No further communication is possible until both peers have exchanged their version.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Identifies protocol version being used by the node<br />
|-<br />
| 8 || services || uint64_t || bitfield of features to be enabled for this connection<br />
|-<br />
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds<br />
|-<br />
| 26 || addr_recv || [[#Network address|net_addr]] || The network address of the node receiving this message<br />
|-<br />
|colspan="4"| Fields below require version ≥ 106<br />
|-<br />
| 26 || addr_from || [[#Network address|net_addr]] || The network address of the node emitting this message<br />
|-<br />
| 8 || nonce || uint64_t || Node random nonce, randomly generated every time a version packet is sent. This nonce is used to detect connections to self.<br />
|-<br />
| ? || user_agent || [[#Variable length string|var_str]] || [https://github.com/bitcoin/bips/blob/master/bip-0014.mediawiki User Agent] (0x00 if string is 0 bytes long)<br />
|-<br />
| 4 || start_height || int32_t || The last block received by the emitting node<br />
|-<br />
|colspan="4"| Fields below require version ≥ 70001<br />
|-<br />
| 1 || relay || bool || Whether the remote peer should announce relayed transactions or not, see [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037]<br />
|}<br />
<br />
A "verack" packet shall be sent if the version packet was accepted.<br />
<br />
The following services are currently assigned:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 1 || NODE_NETWORK || This node can be asked for full blocks instead of just headers.<br />
|}<br />
<br />
Hexdump example of version message (OBSOLETE EXAMPLE: This example lacks a checksum and user-agent):<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....<br />
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........<br />
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............<br />
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................<br />
0040 20 8D 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,<br />
0060 3A B4 57 13 00 55 81 01 00 :.W..U...<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
55 00 00 00 - Payload is 85 bytes long<br />
- No checksum in version message until 20 February 2012. See https://bitcointalk.org/index.php?topic=55852.0<br />
Version message:<br />
9C 7C 00 00 - 31900 (version 0.3.19)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
E6 15 10 4D 00 00 00 00 - Mon Dec 20 21:50:14 EST 2010<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 20 8D - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D - Sender address info - see Network Address<br />
DD 9D 20 2C 3A B4 57 13 - Node random unique ID<br />
00 - "" sub-version string (string is 0 bytes long)<br />
55 81 01 00 - Last block sending node has is block #98645<br />
</pre><br />
<br />
And here's a modern (60002) protocol version client advertising itself to a local peer...<br />
<br />
Newer protocol includes the checksum now, this is from a mainline (satoshi) client during <br />
an outgoing connection to another local client, notice that it does not fill out the <br />
address information at all when the source or destination is "unroutable".<br />
<br />
<pre><br />
<br />
0000 f9 be b4 d9 76 65 72 73 69 6f 6e 00 00 00 00 00 ....version.....<br />
0010 64 00 00 00 35 8d 49 32 62 ea 00 00 01 00 00 00 d...5.I2b.......<br />
0020 00 00 00 00 11 b2 d0 50 00 00 00 00 01 00 00 00 .......P........<br />
0030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ff ff ................<br />
0040 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 00 00 00 00 ff ff 00 00 00 00 00 00 ................<br />
0060 3b 2e b3 5d 8c e6 17 65 0f 2f 53 61 74 6f 73 68 ;..]...e./Satosh<br />
0070 69 3a 30 2e 37 2e 32 2f c0 3e 03 00 i:0.7.2/.>..<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
64 00 00 00 - Payload is 100 bytes long<br />
3B 64 8D 5A - payload checksum<br />
<br />
Version message:<br />
62 EA 00 00 - 60002 (protocol version 60002)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
11 B2 D0 50 00 00 00 00 - Tue Dec 18 10:12:33 PST 2012<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Sender address info - see Network Address<br />
3B 2E B3 5D 8C E6 17 65 - Node ID<br />
0F 2F 53 61 74 6F 73 68 69 3A 30 2E 37 2E 32 2F - "/Satoshi:0.7.2/" sub-version string (string is 15 bytes long)<br />
C0 3E 03 00 - Last block sending node has is block #212672<br />
</pre><br />
<br />
=== verack ===<br />
<br />
The ''verack'' message is sent in reply to ''[[#version|version]]''. This message consists of only a [[#Message structure|message header]] with the command string "verack".<br />
<br />
Hexdump of the verack message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......<br />
0010 00 00 00 00 5D F6 E0 E2 ........<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 61 63 6B 00 00 00 00 00 00 - "verack" command<br />
00 00 00 00 - Payload is 0 bytes long<br />
5D F6 E0 E2 - Checksum<br />
</pre><br />
<br />
=== addr ===<br />
<br />
Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours<br />
<br />
Payload:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of address entries (max: 1000)<br />
|-<br />
| 30x? || addr_list || (uint32_t + [[#Network address|net_addr]])[] || Address of other nodes on the network. version < 209 will only read the first one. The uint32_t is a timestamp (see note below).<br />
|}<br />
<br />
'''Note''': Starting version 31402, addresses are prefixed with a timestamp. If no timestamp is present, the addresses should not be relayed to other peers, unless it is indeed confirmed they are up.<br />
<br />
Hexdump example of ''addr'' message:<br />
<pre><br />
0000 F9 BE B4 D9 61 64 64 72 00 00 00 00 00 00 00 00 ....addr........<br />
0010 1F 00 00 00 ED 52 39 9B 01 E2 15 10 4D 01 00 00 .....R9.....M...<br />
0020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF ................<br />
0030 FF 0A 00 00 01 20 8D ..... .<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
61 64 64 72 00 00 00 00 00 00 00 00 - "addr"<br />
1F 00 00 00 - payload is 31 bytes long<br />
ED 52 39 9B - checksum of payload<br />
<br />
Payload:<br />
01 - 1 address in this message<br />
<br />
Address:<br />
E2 15 10 4D - Mon Dec 20 21:50:10 EST 2010 (only when version is >= 31402)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK service - see version message)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv4: 10.0.0.1, IPv6: ::ffff:10.0.0.1 (IPv4-mapped IPv6 address)<br />
20 8D - port 8333<br />
</pre><br />
<br />
=== inv ===<br />
<br />
Allows a node to advertise its knowledge of one or more objects. It can be received unsolicited, or in reply to ''getblocks''.<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getdata ===<br />
<br />
getdata is used in response to inv, to retrieve the content of a specific object, and is usually sent after receiving an ''inv'' packet, after filtering known elements. It can be used to retrieve transactions, but only if they are in the memory pool or relay set - arbitrary access to transactions in the chain is not allowed to avoid having clients start to depend on nodes having full transaction indexes (which modern nodes do not).<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== notfound ===<br />
<br />
notfound is a response to a getdata, sent if any requested data items could not be relayed, for example, because the requested transaction was not in the memory pool or relay set.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getblocks ===<br />
<br />
Return an ''inv'' packet containing the list of blocks starting right after the last known hash in the block locator object, up to hash_stop or 500 blocks, whichever comes first. <br />
<br />
The locator hashes are processed by a node in the order as they appear in the message. If a block hash is found in the node's main chain, the list of its children is returned back via the ''inv'' message and the remaining locators are ignored, no matter if the requested limit was reached, or not.<br />
<br />
To receive the next blocks hashes, one needs to issue getblocks again with a new block locator object. Keep in mind that some clients may provide blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block; set to zero to get as many blocks as possible (500)<br />
|}<br />
<br />
To create the block locator hashes, keep pushing hashes until you go back to the genesis block. After pushing 10 hashes back, the step backwards doubles every loop:<br />
<br />
<pre><br />
// From libbitcoin which is under AGPL<br />
std::vector<size_t> block_locator_indexes(size_t top_height)<br />
{<br />
std::vector<size_t> indexes;<br />
<br />
// Modify the step in the iteration.<br />
int64_t step = 1;<br />
<br />
// Start at the top of the chain and work backwards.<br />
for (auto index = (int64_t)top_height; index > 0; index -= step)<br />
{<br />
// Push top 10 indexes first, then back off exponentially.<br />
if (indexes.size() >= 10)<br />
step *= 2;<br />
<br />
indexes.push_back((size_t)index);<br />
}<br />
<br />
// Push the genesis block index.<br />
indexes.push_back(0);<br />
return indexes;<br />
}<br />
</pre><br />
<br />
Note that it is allowed to send in fewer known hashes down to a minimum of just one hash. However, the purpose of the block locator object is to detect a wrong branch in the caller's main chain. If the peer detects that you are off the main chain, it will send in block hashes which are earlier than your last known block. So if you just send in your last known hash and it is off the main chain, the peer starts over at block #1.<br />
<br />
=== getheaders ===<br />
<br />
Return a ''headers'' packet containing the headers of blocks starting right after the last known hash in the block locator object, up to hash_stop or 2000 blocks, whichever comes first. To receive the next block headers, one needs to issue getheaders again with a new block locator object. The ''getheaders'' command is used by thin clients to quickly download the block chain where the contents of the transactions would be irrelevant (because they are not ours). Keep in mind that some clients may provide headers of blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block header; set to zero to get as many blocks as possible (2000)<br />
|}<br />
<br />
For the block locator object in this packet, the same rules apply as for the [[Protocol_documentation#getblocks|getblocks]] packet.<br />
<br />
=== tx ===<br />
<br />
''tx'' describes a bitcoin transaction, in reply to ''[[#getdata|getdata]]''<br />
<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Transaction data format version (note, this is signed)<br />
|-<br />
| 1+ || tx_in count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction inputs<br />
|-<br />
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins<br />
|-<br />
| 1+ || tx_out count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction outputs<br />
|-<br />
| 9+ || tx_out || tx_out[] || A list of 1 or more transaction outputs or destinations for coins<br />
|-<br />
| 4 || lock_time || uint32_t || The block number or timestamp at which this transaction is locked:<br />
{|class="wikitable"<br />
! Value !! Description<br />
|-<br />
| 0 || Not locked<br />
|-<br />
| < 500000000 || Block number at which this transaction is locked<br />
|-<br />
| >= 500000000 || UNIX timestamp at which this transaction is locked<br />
|}<br />
If all TxIn inputs have final (0xffffffff) sequence numbers then lock_time is irrelevant. Otherwise, the transaction may not be added to a block until after lock_time (see [[NLockTime]]).<br />
<br />
|}<br />
<br />
TxIn consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 36 || previous_output || outpoint || The previous output transaction reference, as an OutPoint structure<br />
|-<br />
| 1+ || script length || [[Protocol_documentation#Variable_length_integer|var_int]] || The length of the signature script<br />
|-<br />
| ? || signature script || uchar[] || Computational Script for confirming transaction authorization<br />
|-<br />
| 4 || [http://bitcoin.stackexchange.com/q/2025/323 sequence] || uint32_t || Transaction version as defined by the sender. Intended for "replacement" of transactions when information is updated before inclusion into a block.<br />
|}<br />
<br />
The OutPoint structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 32 || hash || char[32] || The hash of the referenced transaction.<br />
|-<br />
| 4 || index || uint32_t || The index of the specific output in the transaction. The first output is 0, etc.<br />
|}<br />
<br />
The Script structure consists of a series of pieces of information and operations related to the value of the transaction.<br />
<br />
(Structure to be expanded in the future… see script.h and script.cpp and [[Script]] for more information)<br />
<br />
The TxOut structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || value || int64_t || Transaction Value<br />
|-<br />
| 1+ || pk_script length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the pk_script<br />
|-<br />
| ? || pk_script || uchar[] || Usually contains the public key as a Bitcoin script setting up conditions to claim this output.<br />
|}<br />
<br />
Example ''tx'' message:<br />
<pre><br />
000000 F9 BE B4 D9 74 78 00 00 00 00 00 00 00 00 00 00 ....tx..........<br />
000010 02 01 00 00 E2 93 CD BE 01 00 00 00 01 6D BD DB .............m..<br />
000020 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D 12 66 E9 .[...Q........f.<br />
000030 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29 00 00 00 .;P......j.6)...<br />
000040 00 8B 48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 ..H0E.!..X..r...<br />
000050 C7 36 7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A .6zz%;..R#...h.:<br />
000060 59 23 3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 Y#?E.W... Y.....<br />
000070 0E 41 83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D .A.z.X.z...XN...<br />
000080 35 BD 96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF 5...6..;...A....<br />
000090 C9 7E F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 .~.6.m...@..!...<br />
0000A0 2A CD 2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC *.+..].}Y... ...<br />
0000B0 4E 02 53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F N.S..=7.o...Q...<br />
0000C0 14 04 2F 46 61 4A 4C 70 C0 F1 4B EF F5 FF FF FF ../FaJLp..K.....<br />
0000D0 FF 02 40 4B 4C 00 00 00 00 00 19 76 A9 14 1A A0 ..@KL......v....<br />
0000E0 CD 1C BE A6 E7 45 8A 7A BA D5 12 A9 D9 EA 1A FB .....E.z........<br />
0000F0 22 5E 88 AC 80 FA E9 C7 00 00 00 00 19 76 A9 14 "^...........v..<br />
000100 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E FD A0 B7 ..[.Cj.....H^...<br />
000110 8B 4E CC 52 88 AC 00 00 00 00 .N.R......<br />
<br />
<br />
Message header:<br />
F9 BE B4 D9 - main network magic bytes<br />
74 78 00 00 00 00 00 00 00 00 00 00 - "tx" command<br />
02 01 00 00 - payload is 258 bytes long<br />
E2 93 CD BE - checksum of payload<br />
<br />
Transaction:<br />
01 00 00 00 - version<br />
<br />
Inputs:<br />
01 - number of transaction inputs<br />
<br />
Input 1:<br />
6D BD DB 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D - previous output (outpoint)<br />
12 66 E9 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29<br />
00 00 00 00<br />
<br />
8B - script is 139 bytes long<br />
<br />
48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 C7 36 - signature script (scriptSig)<br />
7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A 59 23<br />
3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 0E 41<br />
83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D 35 BD<br />
96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF C9 7E<br />
F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 2A CD<br />
2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC 4E 02<br />
53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F 14 04<br />
2F 46 61 4A 4C 70 C0 F1 4B EF F5<br />
<br />
FF FF FF FF - sequence<br />
<br />
Outputs:<br />
02 - 2 Output Transactions<br />
<br />
Output 1:<br />
40 4B 4C 00 00 00 00 00 - 0.05 BTC (5000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 1A A0 CD 1C BE A6 E7 45 8A 7A BA D5 12 - pk_script<br />
A9 D9 EA 1A FB 22 5E 88 AC<br />
<br />
Output 2:<br />
80 FA E9 C7 00 00 00 00 - 33.54 BTC (3354000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E - pk_script<br />
FD A0 B7 8B 4E CC 52 88 AC<br />
<br />
Locktime:<br />
00 00 00 00 - lock time<br />
</pre><br />
<br />
=== block ===<br />
<br />
The '''block''' message is sent in response to a getdata message which requests transaction information from a block hash.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A Unix timestamp recording when this block was created (Currently limited to dates before the year 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated [[Difficulty|difficulty target]] being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| ? || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries<br />
|-<br />
| ? || txns || tx[] || Block transactions, in format of "tx" command<br />
|}<br />
<br />
The SHA256 hash that identifies each block (and which must have a run of 0 bits) is calculated from the first 6 fields of this structure (version, prev_block, merkle_root, timestamp, bits, nonce, and standard SHA256 padding, making two 64-byte chunks in all) and ''not'' from the complete block. To calculate the hash, only two chunks need to be processed by the SHA256 algorithm. Since the ''nonce'' field is in the second chunk, the first chunk stays constant during mining and therefore only the second chunk needs to be processed. However, a Bitcoin hash is the hash of the hash, so two SHA256 rounds are needed for each mining iteration.<br />
See [[Block hashing algorithm]] for details and an example.<br />
<br />
=== headers ===<br />
<br />
The ''headers'' packet returns block headers in response to a ''getheaders'' packet. <br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of block headers<br />
|-<br />
| 81x? || headers || [[Protocol_documentation#Block_Headers|block_header]][] || [[Protocol_documentation#Block_Headers|Block headers]]<br />
|}<br />
<br />
Note that the block headers in this packet include a transaction count (a var_int, so there can be more than 81 bytes per header) as opposed to the block headers that are hashed by miners.<br />
<br />
=== getaddr ===<br />
<br />
The getaddr message sends a request to a node asking for information about known active peers to help with finding potential nodes in the network. The response to receiving this message is to transmit one or more addr messages with one or more peers from a database of known active peers. The typical presumption is that a node is likely to be active if it has been sending a message within the last three hours.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
=== mempool ===<br />
<br />
The mempool message sends a request to a node asking for information about transactions it has verified but which have not yet confirmed. The response to receiving this message is an inv message containing the transaction hashes for all the transactions in the node's mempool.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
It is specified in [https://github.com/bitcoin/bips/blob/master/bip-0035.mediawiki BIP 35]. Since [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 37], if a [[Protocol_documentation#filterload.2C_filteradd.2C_filterclear.2C_merkleblock|bloom filter]] is loaded, only transactions matching the filter are replied.<br />
<br />
=== checkorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== submitorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== reply ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== ping ===<br />
<br />
The ''ping'' message is sent primarily to confirm that the TCP/IP connection is still valid. An error in transmission is presumed to be a closed connection and the address is removed as a current peer.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || random nonce<br />
|}<br />
<br />
=== pong ===<br />
<br />
The ''pong'' message is sent in response to a ''ping'' message. In modern protocol versions, a ''pong'' response is generated using a nonce included in the ping.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || nonce from ping<br />
|}<br />
<br />
<br />
=== reject===<br />
<br />
The ''reject'' message is sent when messages are rejected.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || message || var_str || type of message rejected<br />
|-<br />
| 1 || ccode || char || code relating to rejected message<br />
|-<br />
| 1+ || reason || var_str || text version of reason for rejection<br />
|-<br />
| 0+ || data || char || Optional extra data provided by some errors. Currently, all errors which provide this field fill it with the TXID or block header hash of the object being rejected, so the field is 32 bytes.<br />
|}<br />
<br />
CCodes<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0x01 || REJECT_MALFORMED|| <br />
|-<br />
| 0x10 || REJECT_INVALID ||<br />
|-<br />
| 0x11 || REJECT_OBSOLETE ||<br />
|-<br />
| 0x12 || REJECT_DUPLICATE ||<br />
|-<br />
| 0x40 || REJECT_NONSTANDARD ||<br />
|-<br />
| 0x41 || REJECT_DUST ||<br />
|-<br />
| 0x42 || REJECT_INSUFFICIENTFEE ||<br />
|-<br />
| 0x43 || REJECT_CHECKPOINT ||<br />
|}<br />
<br />
=== filterload, filteradd, filterclear, merkleblock ===<br />
<br />
These messages are related to Bloom filtering of connections and are defined in [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037].<br />
<br />
<br />
The <code>filterload</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || filter || uint8_t[] || The filter itself is simply a bit field of arbitrary byte-aligned size. The maximum size is 36,000 bytes.<br />
|-<br />
| 4 || nHashFuncs || uint32_t || The number of hash functions to use in this filter. The maximum value allowed in this field is 50.<br />
|-<br />
| 4 || nTweak || uint32_t || A random value to add to the seed value in the hash function used by the bloom filter.<br />
|-<br />
| 1 || nFlags || uint8_t || A set of flags that control how matched items are added to the filter.<br />
|}<br />
<br />
See below for a description of the Bloom filter algorithm and how to select nHashFuncs and filter size for a desired false positive rate.<br />
<br />
Upon receiving a <code>filterload</code> command, the remote peer will immediately restrict the broadcast transactions it announces (in inv packets) to transactions matching the filter, where the matching algorithm is specified below. The flags control the update behaviour of the matching algorithm.<br />
<br />
The <code>filteradd</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || data || uint8_t[] || The data element to add to the current filter.<br />
|}<br />
<br />
The data field must be smaller than or equal to 520 bytes in size (the maximum size of any potentially matched object).<br />
<br />
The given data element will be added to the Bloom filter. A filter must have been previously provided using <code>filterload</code>. This command is useful if a new key or script is added to a clients wallet whilst it has connections to the network open, it avoids the need to re-calculate and send an entirely new filter to every peer (though doing so is usually advisable to maintain anonymity).<br />
<br />
The <code>filterclear</code> command has no arguments at all.<br />
<br />
After a filter has been set, nodes don't merely stop announcing non-matching transactions, they can also serve filtered blocks. A filtered block is defined by the <code>merkleblock</code> message and is defined like this:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information, based upon the software version creating this block (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Limited to 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 4 || total_transactions || uint32_t || Number of transactions in the block (including unmatched ones)<br />
|-<br />
| ? || hashes || uint256[] || hashes in depth-first order (including standard varint size prefix)<br />
|-<br />
| ? || flags || byte[] || flag bits, packed per 8 in a byte, least significant bit first (including standard varint size prefix)<br />
|}<br />
<br />
=== alert ===<br />
<br />
An '''alert''' is sent between nodes to send a general notification message throughout the network. If the alert can be confirmed with the signature as having come from the core development group of the Bitcoin software, the message is suggested to be displayed for end-users. Attempts to perform transactions, particularly automated transactions through the client, are suggested to be halted. The text in the Message string should be relayed to log files and any user interfaces.<br />
<br />
Alert format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || payload || uchar[] || Serialized alert payload<br />
|-<br />
| ? || signature || uchar[] || An ECDSA signature of the message<br />
|}<br />
<br />
The developers of Satoshi's client use this public key for signing alerts:<br />
04fc9702847840aaf195de8442ebecedf5b095cdbb9bc716bda9110971b28a49e0ead8564ff0db22209e0374782c093bb899692d524e9d6a6956e7c5ecbcd68284<br />
(hash) 1AGRxqDa5WjUKBwHB9XYEjmkv1ucoUUy1s<br />
<br />
The payload is serialized into a uchar[] to ensure that versions using incompatible alert formats can still relay alerts among one another. The current alert payload format is:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || Version || int32_t || Alert format version<br />
|-<br />
| 8 || RelayUntil || int64_t || The timestamp beyond which nodes should stop relaying this alert<br />
|-<br />
| 8 || Expiration || int64_t || The timestamp beyond which this alert is no longer in effect and should be ignored<br />
|-<br />
| 4 || ID || int32_t || A unique ID number for this alert<br />
|-<br />
| 4 || Cancel || int32_t || All alerts with an ID number less than or equal to this number should be cancelled: deleted and not accepted in the future<br />
|-<br />
| ? || setCancel || set<int32_t> || All alert IDs contained in this set should be cancelled as above<br />
|-<br />
| 4 || MinVer || int32_t || This alert only applies to versions greater than or equal to this version. Other versions should still relay it.<br />
|-<br />
| 4 || MaxVer || int32_t || This alert only applies to versions less than or equal to this version. Other versions should still relay it.<br />
|-<br />
| ? || setSubVer || set<string> || If this set contains any elements, then only nodes that have their subVer contained in this set are affected by the alert. Other versions should still relay it.<br />
|-<br />
| 4 || Priority || int32_t || Relative priority compared to other alerts<br />
|-<br />
| ? || Comment || string || A comment on the alert that is not displayed<br />
|-<br />
| ? || StatusBar || string || The alert message that is displayed to the user<br />
|-<br />
| ? || Reserved || string || Reserved<br />
|}<br />
<br />
Note: '''set<''type''>''' in the table above is a [[#Variable length integer | variable length integer]] followed by the number of fields of the given ''type'' (either int32_t or [[#Variable length string | variable length string]])<br />
<br />
Sample alert (no message header):<br />
73010000003766404f00000000b305434f00000000f2030000f1030000001027000048ee0000<br />
0064000000004653656520626974636f696e2e6f72672f666562323020696620796f75206861<br />
76652074726f75626c6520636f6e6e656374696e672061667465722032302046656272756172<br />
79004730450221008389df45f0703f39ec8c1cc42c13810ffcae14995bb648340219e353b63b<br />
53eb022009ec65e1c1aaeec1fd334c6b684bde2b3f573060d5b70c3a46723326e4e8a4f1<br />
<br />
Version: 1<br />
RelayUntil: 1329620535<br />
Expiration: 1329792435<br />
ID: 1010<br />
Cancel: 1009<br />
setCancel: <empty><br />
MinVer: 10000<br />
MaxVer: 61000<br />
setSubVer: <empty><br />
Priority: 100<br />
Comment: <empty><br />
StatusBar: "See bitcoin.org/feb20 if you have trouble connecting after 20 February"<br />
Reserved: <empty><br />
<br />
=== sendheaders ===<br />
<br />
Request for Direct headers announcement. <br />
<br />
Upon receipt of this message, the node is be permitted, but not required, to announce new blocks by '''headers''' command (instead of '''inv''' command).<br />
<br />
This message is supported by the protocol version >= 70012 or Bitcoin Core version >= 0.12.0.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0130.mediawiki BIP 130] for more information.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
<br />
=== feefilter ===<br />
<br />
The payload is always 8 bytes long and it encodes 64 bit integer value (LSB / little endian) of '''feerate'''.<br />
The value represents a minimal fee and is expressed in satoshis per 1000 bytes.<br />
<br />
Upon receipt of a "feefilter" message, the node will be permitted, but not required, to filter transaction invs for transactions that fall below the feerate provided in the feefilter message interpreted as satoshis per kilobyte.<br />
<br />
The fee filter is additive with a bloom filter for transactions so if an SPV client were to load a bloom filter and send a feefilter message, transactions would only be relayed if they passed both filters.<br />
<br />
Inv's generated from a mempool message are also subject to a fee filter if it exists.<br />
<br />
Feature discovery is enabled by checking protocol version >= 70013<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0133.mediawiki BIP 133] for more information.<br />
<br />
=== sendcmpct ===<br />
<br />
# The sendcmpct message is defined as a message containing a 1-byte integer followed by a 8-byte integer where pchCommand == "sendcmpct".<br />
# The first integer SHALL be interpreted as a boolean (and MUST have a value of either 1 or 0)<br />
# The second integer SHALL be interpreted as a little-endian version number. Nodes sending a sendcmpct message MUST currently set this value to 1.<br />
# Upon receipt of a "sendcmpct" message with the first and second integers set to 1, the node SHOULD announce new blocks by sending a cmpctblock message.<br />
# Upon receipt of a "sendcmpct" message with the first integer set to 0, the node SHOULD NOT announce new blocks by sending a cmpctblock message, but SHOULD announce new blocks by sending invs or headers, as defined by BIP130.<br />
# Upon receipt of a "sendcmpct" message with the second integer set to something other than 1, nodes MUST treat the peer as if they had not received the message (as it indicates the peer will provide an unexpected encoding in <br />
# cmpctblock, and/or other, messages). This allows future versions to send duplicate sendcmpct messages with different versions as a part of a version handshake for future versions.<br />
# Nodes SHOULD check for a protocol version of >= 70014 before sending sendcmpct messages.<br />
# Nodes MUST NOT send a request for a MSG_CMPCT_BLOCK object to a peer before having received a sendcmpct message from that peer.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== cmpctblock ===<br />
<br />
# The cmpctblock message is defined as as a message containing a serialized HeaderAndShortIDs message and pchCommand == "cmpctblock".<br />
# Upon receipt of a cmpctblock message after sending a sendcmpct message, nodes SHOULD calculate the short transaction ID for each unconfirmed transaction they have available (ie in their mempool) and compare each to each short transaction ID in the cmpctblock message.<br />
# After finding already-available transactions, nodes which do not have all transactions available to reconstruct the full block SHOULD request the missing transactions using a getblocktxn message.<br />
# A node MUST NOT send a cmpctblock message unless they are able to respond to a getblocktxn message which requests every transaction in the block.<br />
# A node MUST NOT send a cmpctblock message without having validated that the header properly commits to each transaction in the block, and properly builds on top of the existing chain with a valid proof-of-work. A node MAY send a cmpctblock before validating that each transaction in the block validly spends existing UTXO set entries.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== getblocktxn ===<br />
<br />
# The getblocktxn message is defined as as a message containing a serialized BlockTransactionsRequest message and pchCommand == "getblocktxn".<br />
# Upon receipt of a properly-formatted getblocktxnmessage, nodes which recently provided the sender of such a message a cmpctblock for the block hash identified in this message MUST respond with an appropriate blocktxn message. Such a blocktxn message MUST contain exactly and only each transaction which is present in the appropriate block at the index specified in the getblocktxn indexes list, in the order requested.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== blocktxn ===<br />
<br />
# The blocktxn message is defined as as a message containing a serialized BlockTransactions message and pchCommand == "blocktxn".<br />
# Upon receipt of a properly-formatted requested blocktxn message, nodes SHOULD attempt to reconstruct the full block by:<br />
# Taking the prefilledtxn transactions from the original cmpctblock and placing them in the marked positions.<br />
# For each short transaction ID from the original cmpctblock, in order, find the corresponding transaction either from the blocktxn message or from other sources and place it in the first available position in the block.<br />
# Once the block has been reconstructed, it shall be processed as normal, keeping in mind that short transaction IDs are expected to occasionally collide, and that nodes MUST NOT be penalized for such collisions, wherever they # appear.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
== Scripting ==<br />
<br />
See [[script]].<br />
<br />
==See Also==<br />
<br />
* [[Network]]<br />
* [[Protocol rules]]<br />
* [[Hardfork Wishlist]]<br />
* [https://bitcoin.org/en/developer-documentation Developer Documentation on bitcoin.org]<br />
* Bitcoin dissectors for Wireshark: https://github.com/lbotsch/wireshark-bitcoin https://github.com/op-sig/bitcoin-wireshark-dissector<br />
<br />
==References==<br />
<references /><br />
<br />
[[zh-cn:协议说明]]<br />
[[Category:Technical]]<br />
[[Category:Developer]]<br />
<br />
{{Bitcoin Core documentation}}</div>Tonikthttps://en.bitcoin.it/w/index.php?title=Protocol_documentation&diff=61490Protocol documentation2016-08-25T12:39:42Z<p>Tonikt: /* HeaderAndShortIDs */</p>
<hr />
<div>This page ''describes'' the behavior of the [[Original Bitcoin client|reference client]]. The Bitcoin protocol is specified by the behavior of the reference client, not by this page. In particular, while this page is quite complete in describing the network protocol, it does not attempt to list all of the rules for block or transaction validity.<br />
<br />
Type names used in this documentation are from the C99 standard.<br />
<br />
For protocol used in mining, see [[getblocktemplate]].<br />
<br />
==Common standards==<br />
<br />
=== Hashes ===<br />
<br />
Usually, when a hash is computed within bitcoin, it is computed twice. Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-256] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when a shorter hash is desirable (for example when creating a bitcoin address).<br />
<br />
Example of double-SHA-256 encoding of string "hello":<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round of sha-256)<br />
9595c9df90075148eb06860365df33584b75bff782a510c6cd4883a419833d50 (second round of sha-256)<br />
<br />
For bitcoin addresses (RIPEMD-160) this would give:<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round is sha-256)<br />
b6a9c8c230722b7c748331a8b450f05566dc7d0f (with ripemd-160)<br />
<br />
=== Merkle Trees ===<br />
<br />
Merkle trees are binary trees of hashes. Merkle trees in bitcoin use a '''double''' SHA-256, the SHA-256 hash of the SHA-256 hash of something.<br />
<br />
If, when forming a row in the tree (other than the root of the tree), it would have an odd number of elements, the final double-hash is duplicated to ensure that the row has an even number of hashes.<br />
<br />
First form the bottom row of the tree with the ordered double-SHA-256 hashes of the byte streams of the transactions in the block.<br />
<br />
Then the row above it consists of half that number of hashes. Each entry is the double-SHA-256 of the 64-byte concatenation of the corresponding two hashes below it in the tree.<br />
<br />
This procedure repeats recursively until we reach a row consisting of just a single double-hash. This is the '''Merkle root''' of the tree.<br />
<br />
For example, imagine a block with three transactions ''a'', ''b'' and ''c''. The Merkle tree is: <br />
<br />
d1 = dhash(a)<br />
d2 = dhash(b)<br />
d3 = dhash(c)<br />
d4 = dhash(c) # a, b, c are 3. that's an odd number, so we take the c twice<br />
<br />
d5 = dhash(d1 concat d2)<br />
d6 = dhash(d3 concat d4)<br />
<br />
d7 = dhash(d5 concat d6)<br />
<br />
where<br />
<br />
dhash(a) = sha256(sha256(a))<br />
<br />
''d7'' is the Merkle root of the 3 transactions in this block.<br />
<br />
Note: Hashes in Merkle Tree displayed in the [[Block Explorer]] are of little-endian notation. For some implementations and [http://www.fileformat.info/tool/hash.htm calculations], the bits need to be reversed before they are hashed, and again after the hashing operation.<br />
<br />
=== Signatures ===<br />
<br />
Bitcoin uses [http://en.wikipedia.org/wiki/Elliptic_curve_cryptography Elliptic Curve] [http://en.wikipedia.org/wiki/Digital_Signature_Algorithm Digital Signature Algorithm] ([http://en.wikipedia.org/wiki/Elliptic_Curve_DSA ECDSA]) to sign transactions. <br />
<br />
For [[ECDSA]] the secp256k1 curve from http://www.secg.org/collateral/sec2_final.pdf is used.<br />
<br />
Public keys (in scripts) are given as 04 <x> <y> where ''x'' and ''y'' are 32 byte big-endian integers representing the coordinates of a point on the curve or in compressed form given as <sign> <x> where <sign> is 0x02 if ''y'' is even and 0x03 if ''y'' is odd.<br />
<br />
Signatures use [http://en.wikipedia.org/wiki/Distinguished_Encoding_Rules DER encoding] to pack the ''r'' and ''s'' components into a single byte stream (this is also what OpenSSL produces by default).<br />
<br />
=== Transaction Verification ===<br />
Transactions are cryptographically signed records that reassign ownership of Bitcoins to new addresses. Transactions have ''inputs'' - records which reference the funds from other previous transactions - and ''outputs'' - records which determine the new owner of the transferred Bitcoins, and which will be referenced as inputs in future transactions as those funds are respent.<br />
<br />
Each ''input'' must have a cryptographic digital signature that unlocks the funds from the prior transaction. Only the person possessing the appropriate [[private key]] is able to create a satisfactory signature; this in effect ensures that funds can only be spent by their owners.<br />
<br />
Each ''output'' determines which Bitcoin address (or other criteria, see [[Script]]) is the recipient of the funds.<br />
<br />
In a transaction, the sum of all inputs must be equal to or greater than the sum of all outputs. If the inputs exceed the outputs, the difference is considered a [[transaction fee]], and is redeemable by whoever first includes the transaction into the block chain.<br />
<br />
A special kind of transaction, called a [[coinbase transaction]], has no inputs. It is created by [[miners]], and there is one coinbase transaction per block. Because each block comes with a reward of newly created Bitcoins (e.g. 50 BTC for the first 210,000 blocks), the first transaction of a block is, with few exceptions, the transaction that grants those coins to their recipient (the miner). In addition to the newly created Bitcoins, the coinbase transaction is also used for assigning the recipient of any transaction fees that were paid within the other transactions being included in the same block. The coinbase transaction can assign the entire reward to a single Bitcoin address, or split it in portions among multiple addresses, just like any other transaction. Coinbase transactions always contain outputs totalling the sum of the block reward plus all transaction fees collected from the other transactions in the same block.<br />
<br />
The [[coinbase transaction]] in block zero cannot be spent. This is due to a quirk of the reference client implementation that would open the potential for a block chain fork if some nodes accepted the spend and others did not<ref>[http://bitcointalk.org/index.php?topic=119645.msg1288552#msg1288552 Block 0 Network Fork]</ref>.<br />
<br />
Most Bitcoin outputs encumber the newly transferred coins with a single ECDSA private key. The actual record saved with inputs and outputs isn't necessarily a key, but a ''script''. Bitcoin uses an interpreted scripting system to determine whether an output's criteria have been satisfied, with which more complex operations are possible, such as outputs that require two ECDSA signatures, or two-of-three-signature schemes. An output that references a single Bitcoin address is a ''typical'' output; an output actually contains this information in the form of a script that requires a single ECDSA signature (see [[OP_CHECKSIG]]). The output script specifies what must be provided to unlock the funds later, and when the time comes in the future to spend the transaction in another input, that input must provide all of the thing(s) that satisfy the requirements defined by the original output script.<br />
<br />
=== Addresses ===<br />
<br />
A bitcoin address is in fact the hash of a ECDSA public key, computed this way:<br />
<br />
Version = 1 byte of 0 (zero); on the test network, this is 1 byte of 111<br />
Key hash = Version concatenated with RIPEMD-160(SHA-256(public key))<br />
Checksum = 1st 4 bytes of SHA-256(SHA-256(Key hash))<br />
Bitcoin Address = Base58Encode(Key hash concatenated with Checksum)<br />
<br />
The Base58 encoding used is home made, and has some differences. Especially, leading zeroes are kept as single zeroes when conversion happens.<br />
<br />
== Common structures ==<br />
<br />
Almost all integers are encoded in little endian. Only IP or port number are encoded big endian.<br />
<br />
=== Message structure ===<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown<br />
|-<br />
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| 4 || length || uint32_t || Length of payload in number of bytes<br />
|-<br />
| 4 || checksum || uint32_t || First 4 bytes of sha256(sha256(payload))<br />
|-<br />
| ? || payload || uchar[] || The actual data<br />
|}<br />
<br />
<br />
Known magic values:<br />
<br />
{|class="wikitable"<br />
! Network !! Magic value !! Sent over wire as<br />
|-<br />
| main || 0xD9B4BEF9 || F9 BE B4 D9<br />
|-<br />
| testnet || 0xDAB5BFFA || FA BF B5 DA<br />
|-<br />
| testnet3 || 0x0709110B || 0B 11 09 07<br />
|-<br />
| namecoin || 0xFEB4BEF9 || F9 BE B4 FE<br />
|}<br />
<br />
=== Variable length integer ===<br />
<br />
Integer can be encoded depending on the represented value to save space.<br />
Variable length integers always precede an array/vector of a type of data that may vary in length.<br />
Longer numbers are encoded in little endian.<br />
<br />
{|class="wikitable"<br />
! Value !! Storage length !! Format<br />
|-<br />
| < 0xFD || 1 || uint8_t<br />
|-<br />
| <= 0xFFFF || 3 || 0xFD followed by the length as uint16_t<br />
|-<br />
| <= 0xFFFF FFFF || 5 || 0xFE followed by the length as uint32_t<br />
|-<br />
| - || 9 || 0xFF followed by the length as uint64_t<br />
|}<br />
<br />
If you're reading the Satoshi client code (BitcoinQT) it refers to this encoding as a "CompactSize". Modern BitcoinQT also has the CVarInt class which implements an even more compact integer for the purpose of local storage (which is incompatible with "CompactSize" described here). CVarInt is not a part of the protocol.<br />
<br />
=== Variable length string ===<br />
<br />
Variable length string can be stored using a variable length integer followed by the string itself.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the string<br />
|-<br />
| ? || string || char[] || The string itself (can be empty)<br />
|}<br />
<br />
=== Network address ===<br />
<br />
When a network address is needed somewhere, this structure is used. Network addresses are not prefixed with a timestamp in the version message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || time || uint32 || the Time (version >= 31402). '''Not present in version message.'''<br />
|-<br />
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]<br />
|-<br />
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The original client only supported IPv4 and only read the last 4 bytes to get the IPv4 address. However, the IPv4 address is written into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]<br />
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).<br />
|-<br />
| 2 || port || uint16_t || port number, network byte order<br />
|}<br />
<br />
Hexdump example of Network address structure<br />
<br />
<pre><br />
0000 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0010 00 00 FF FF 0A 00 00 01 20 8D ........ .<br />
<br />
Network address:<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK: see services listed under version command)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv6: ::ffff:a00:1 or IPv4: 10.0.0.1<br />
20 8D - Port 8333<br />
</pre><br />
<br />
=== Inventory Vectors ===<br />
<br />
Inventory vectors are used for notifying other nodes about objects they have or data which is being requested.<br />
<br />
Inventory vectors consist of the following data format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || type || uint32_t || Identifies the object type linked to this inventory<br />
|-<br />
| 32 || hash || char[32] || Hash of the object<br />
|}<br />
<br />
<br />
The object type is currently defined as one of the following possibilities:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0 || ERROR || Any data of with this number may be ignored<br />
|-<br />
| 1 || MSG_TX || Hash is related to a transaction<br />
|-<br />
| 2 || MSG_BLOCK || Hash is related to a data block<br />
|-<br />
| 3 || MSG_FILTERED_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a merkleblock message rather than a block message; this only works if a bloom filter has been set.<br />
|-<br />
| 4 || MSG_CMPCT_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a cmpctblock message. See BIP 152 for more info.<br />
|}<br />
<br />
Other Data Type values are considered reserved for future implementations.<br />
<br />
=== Block Headers ===<br />
<br />
Block headers are sent in a headers packet in response to a getheaders message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Will overflow in 2106<ref>https://en.wikipedia.org/wiki/Unix_time#Notable_events_in_Unix_time</ref>)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 1 || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries, this value is always 0<br />
|}<br />
<br />
cf. [[Block hashing algorithm]]<br />
<br />
=== PrefilledTransaction ===<br />
<br />
A PrefilledTransaction structure is used in HeaderAndShortIDs to provide a list of a few transactions explicitly.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| index || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1, 3 bytes || Compact Size, differentially encoded since the last PrefilledTransaction in a list || The index into the block at which this transaction is<br />
|-<br />
| tx || Transaction || variable || As encoded in "tx" messages || The transaction which is in the block at index index.<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== HeaderAndShortIDs ===<br />
<br />
A HeaderAndShortIDs structure is used to relay a block header, the short transactions IDs used for matching already-available transactions, and a select few transactions which we expect a peer may be missing.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| header || Block header || 80 bytes || First 80 bytes of the block as defined by the encoding used by "block" messages || The header of the block being provided<br />
|-<br />
| nonce || uint64_t || 8 bytes || Little Endian || A nonce for use in short transaction ID calculations<br />
|-<br />
| shortids_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of short transaction IDs in shortids (ie block tx count - prefilledtxn_length)<br />
|-<br />
| shortids || List of 6-byte integers || 6*shortids_length bytes || Little Endian || The short transaction IDs calculated from the transactions which were not provided explicitly in prefilledtxn<br />
|-<br />
| prefilledtxn_length || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of prefilled transactions in prefilledtxn (ie block tx count - shortids_length)<br />
|-<br />
| prefilledtxn || List of PrefilledTransactions || variable size*prefilledtxn_length || As defined by PrefilledTransaction definition, above || Used to provide the coinbase transaction and a select few which we expect a peer may be missing<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== BlockTransactionsRequest ===<br />
<br />
A BlockTransactionsRequest structure is used to list transaction indexes in a block being requested.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| blockhash || Binary blob || 32 bytes || The output from a double-SHA256 of the block header, as used elsewhere || The blockhash of the block which the transactions being requested are in<br />
|-<br />
| indexes_length || CompactSize || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of transactions being requested<br />
|-<br />
| indexes || List of CompactSizes || 1 or 3 bytes*indexes_length || Differentially encoded || The indexes of the transactions being requested in the block<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== BlockTransactions ===<br />
<br />
A BlockTransactions structure is used to provide some of the transactions in a block, as requested.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== Short transaction IDs ===<br />
<br />
Short transaction IDs are used to represent a transaction without sending a full 256-bit hash. They are calculated by:<br />
<br />
# single-SHA256 hashing the block header with the nonce appended (in little-endian)<br />
# Running SipHash-2-4 with the input being the transaction ID and the keys (k0/k1) set to the first two little-endian 64-bit integers from the above hash, respectively.<br />
# Dropping the 2 most significant bytes from the SipHash output to make it 6 bytes.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
== Message types ==<br />
<br />
=== version ===<br />
<br />
When a node creates an outgoing connection, it will immediately [[Version Handshake|advertise]] its version. The remote node will respond with its version. No further communication is possible until both peers have exchanged their version.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Identifies protocol version being used by the node<br />
|-<br />
| 8 || services || uint64_t || bitfield of features to be enabled for this connection<br />
|-<br />
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds<br />
|-<br />
| 26 || addr_recv || [[#Network address|net_addr]] || The network address of the node receiving this message<br />
|-<br />
|colspan="4"| Fields below require version ≥ 106<br />
|-<br />
| 26 || addr_from || [[#Network address|net_addr]] || The network address of the node emitting this message<br />
|-<br />
| 8 || nonce || uint64_t || Node random nonce, randomly generated every time a version packet is sent. This nonce is used to detect connections to self.<br />
|-<br />
| ? || user_agent || [[#Variable length string|var_str]] || [https://github.com/bitcoin/bips/blob/master/bip-0014.mediawiki User Agent] (0x00 if string is 0 bytes long)<br />
|-<br />
| 4 || start_height || int32_t || The last block received by the emitting node<br />
|-<br />
|colspan="4"| Fields below require version ≥ 70001<br />
|-<br />
| 1 || relay || bool || Whether the remote peer should announce relayed transactions or not, see [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037]<br />
|}<br />
<br />
A "verack" packet shall be sent if the version packet was accepted.<br />
<br />
The following services are currently assigned:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 1 || NODE_NETWORK || This node can be asked for full blocks instead of just headers.<br />
|}<br />
<br />
Hexdump example of version message (OBSOLETE EXAMPLE: This example lacks a checksum and user-agent):<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....<br />
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........<br />
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............<br />
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................<br />
0040 20 8D 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,<br />
0060 3A B4 57 13 00 55 81 01 00 :.W..U...<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
55 00 00 00 - Payload is 85 bytes long<br />
- No checksum in version message until 20 February 2012. See https://bitcointalk.org/index.php?topic=55852.0<br />
Version message:<br />
9C 7C 00 00 - 31900 (version 0.3.19)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
E6 15 10 4D 00 00 00 00 - Mon Dec 20 21:50:14 EST 2010<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 20 8D - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D - Sender address info - see Network Address<br />
DD 9D 20 2C 3A B4 57 13 - Node random unique ID<br />
00 - "" sub-version string (string is 0 bytes long)<br />
55 81 01 00 - Last block sending node has is block #98645<br />
</pre><br />
<br />
And here's a modern (60002) protocol version client advertising itself to a local peer...<br />
<br />
Newer protocol includes the checksum now, this is from a mainline (satoshi) client during <br />
an outgoing connection to another local client, notice that it does not fill out the <br />
address information at all when the source or destination is "unroutable".<br />
<br />
<pre><br />
<br />
0000 f9 be b4 d9 76 65 72 73 69 6f 6e 00 00 00 00 00 ....version.....<br />
0010 64 00 00 00 35 8d 49 32 62 ea 00 00 01 00 00 00 d...5.I2b.......<br />
0020 00 00 00 00 11 b2 d0 50 00 00 00 00 01 00 00 00 .......P........<br />
0030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ff ff ................<br />
0040 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 00 00 00 00 ff ff 00 00 00 00 00 00 ................<br />
0060 3b 2e b3 5d 8c e6 17 65 0f 2f 53 61 74 6f 73 68 ;..]...e./Satosh<br />
0070 69 3a 30 2e 37 2e 32 2f c0 3e 03 00 i:0.7.2/.>..<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
64 00 00 00 - Payload is 100 bytes long<br />
3B 64 8D 5A - payload checksum<br />
<br />
Version message:<br />
62 EA 00 00 - 60002 (protocol version 60002)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
11 B2 D0 50 00 00 00 00 - Tue Dec 18 10:12:33 PST 2012<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Sender address info - see Network Address<br />
3B 2E B3 5D 8C E6 17 65 - Node ID<br />
0F 2F 53 61 74 6F 73 68 69 3A 30 2E 37 2E 32 2F - "/Satoshi:0.7.2/" sub-version string (string is 15 bytes long)<br />
C0 3E 03 00 - Last block sending node has is block #212672<br />
</pre><br />
<br />
=== verack ===<br />
<br />
The ''verack'' message is sent in reply to ''[[#version|version]]''. This message consists of only a [[#Message structure|message header]] with the command string "verack".<br />
<br />
Hexdump of the verack message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......<br />
0010 00 00 00 00 5D F6 E0 E2 ........<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 61 63 6B 00 00 00 00 00 00 - "verack" command<br />
00 00 00 00 - Payload is 0 bytes long<br />
5D F6 E0 E2 - Checksum<br />
</pre><br />
<br />
=== addr ===<br />
<br />
Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours<br />
<br />
Payload:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of address entries (max: 1000)<br />
|-<br />
| 30x? || addr_list || (uint32_t + [[#Network address|net_addr]])[] || Address of other nodes on the network. version < 209 will only read the first one. The uint32_t is a timestamp (see note below).<br />
|}<br />
<br />
'''Note''': Starting version 31402, addresses are prefixed with a timestamp. If no timestamp is present, the addresses should not be relayed to other peers, unless it is indeed confirmed they are up.<br />
<br />
Hexdump example of ''addr'' message:<br />
<pre><br />
0000 F9 BE B4 D9 61 64 64 72 00 00 00 00 00 00 00 00 ....addr........<br />
0010 1F 00 00 00 ED 52 39 9B 01 E2 15 10 4D 01 00 00 .....R9.....M...<br />
0020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF ................<br />
0030 FF 0A 00 00 01 20 8D ..... .<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
61 64 64 72 00 00 00 00 00 00 00 00 - "addr"<br />
1F 00 00 00 - payload is 31 bytes long<br />
ED 52 39 9B - checksum of payload<br />
<br />
Payload:<br />
01 - 1 address in this message<br />
<br />
Address:<br />
E2 15 10 4D - Mon Dec 20 21:50:10 EST 2010 (only when version is >= 31402)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK service - see version message)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv4: 10.0.0.1, IPv6: ::ffff:10.0.0.1 (IPv4-mapped IPv6 address)<br />
20 8D - port 8333<br />
</pre><br />
<br />
=== inv ===<br />
<br />
Allows a node to advertise its knowledge of one or more objects. It can be received unsolicited, or in reply to ''getblocks''.<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getdata ===<br />
<br />
getdata is used in response to inv, to retrieve the content of a specific object, and is usually sent after receiving an ''inv'' packet, after filtering known elements. It can be used to retrieve transactions, but only if they are in the memory pool or relay set - arbitrary access to transactions in the chain is not allowed to avoid having clients start to depend on nodes having full transaction indexes (which modern nodes do not).<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== notfound ===<br />
<br />
notfound is a response to a getdata, sent if any requested data items could not be relayed, for example, because the requested transaction was not in the memory pool or relay set.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getblocks ===<br />
<br />
Return an ''inv'' packet containing the list of blocks starting right after the last known hash in the block locator object, up to hash_stop or 500 blocks, whichever comes first. <br />
<br />
The locator hashes are processed by a node in the order as they appear in the message. If a block hash is found in the node's main chain, the list of its children is returned back via the ''inv'' message and the remaining locators are ignored, no matter if the requested limit was reached, or not.<br />
<br />
To receive the next blocks hashes, one needs to issue getblocks again with a new block locator object. Keep in mind that some clients may provide blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block; set to zero to get as many blocks as possible (500)<br />
|}<br />
<br />
To create the block locator hashes, keep pushing hashes until you go back to the genesis block. After pushing 10 hashes back, the step backwards doubles every loop:<br />
<br />
<pre><br />
// From libbitcoin which is under AGPL<br />
std::vector<size_t> block_locator_indexes(size_t top_height)<br />
{<br />
std::vector<size_t> indexes;<br />
<br />
// Modify the step in the iteration.<br />
int64_t step = 1;<br />
<br />
// Start at the top of the chain and work backwards.<br />
for (auto index = (int64_t)top_height; index > 0; index -= step)<br />
{<br />
// Push top 10 indexes first, then back off exponentially.<br />
if (indexes.size() >= 10)<br />
step *= 2;<br />
<br />
indexes.push_back((size_t)index);<br />
}<br />
<br />
// Push the genesis block index.<br />
indexes.push_back(0);<br />
return indexes;<br />
}<br />
</pre><br />
<br />
Note that it is allowed to send in fewer known hashes down to a minimum of just one hash. However, the purpose of the block locator object is to detect a wrong branch in the caller's main chain. If the peer detects that you are off the main chain, it will send in block hashes which are earlier than your last known block. So if you just send in your last known hash and it is off the main chain, the peer starts over at block #1.<br />
<br />
=== getheaders ===<br />
<br />
Return a ''headers'' packet containing the headers of blocks starting right after the last known hash in the block locator object, up to hash_stop or 2000 blocks, whichever comes first. To receive the next block headers, one needs to issue getheaders again with a new block locator object. The ''getheaders'' command is used by thin clients to quickly download the block chain where the contents of the transactions would be irrelevant (because they are not ours). Keep in mind that some clients may provide headers of blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block header; set to zero to get as many blocks as possible (2000)<br />
|}<br />
<br />
For the block locator object in this packet, the same rules apply as for the [[Protocol_documentation#getblocks|getblocks]] packet.<br />
<br />
=== tx ===<br />
<br />
''tx'' describes a bitcoin transaction, in reply to ''[[#getdata|getdata]]''<br />
<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Transaction data format version (note, this is signed)<br />
|-<br />
| 1+ || tx_in count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction inputs<br />
|-<br />
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins<br />
|-<br />
| 1+ || tx_out count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction outputs<br />
|-<br />
| 9+ || tx_out || tx_out[] || A list of 1 or more transaction outputs or destinations for coins<br />
|-<br />
| 4 || lock_time || uint32_t || The block number or timestamp at which this transaction is locked:<br />
{|class="wikitable"<br />
! Value !! Description<br />
|-<br />
| 0 || Not locked<br />
|-<br />
| < 500000000 || Block number at which this transaction is locked<br />
|-<br />
| >= 500000000 || UNIX timestamp at which this transaction is locked<br />
|}<br />
If all TxIn inputs have final (0xffffffff) sequence numbers then lock_time is irrelevant. Otherwise, the transaction may not be added to a block until after lock_time (see [[NLockTime]]).<br />
<br />
|}<br />
<br />
TxIn consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 36 || previous_output || outpoint || The previous output transaction reference, as an OutPoint structure<br />
|-<br />
| 1+ || script length || [[Protocol_documentation#Variable_length_integer|var_int]] || The length of the signature script<br />
|-<br />
| ? || signature script || uchar[] || Computational Script for confirming transaction authorization<br />
|-<br />
| 4 || [http://bitcoin.stackexchange.com/q/2025/323 sequence] || uint32_t || Transaction version as defined by the sender. Intended for "replacement" of transactions when information is updated before inclusion into a block.<br />
|}<br />
<br />
The OutPoint structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 32 || hash || char[32] || The hash of the referenced transaction.<br />
|-<br />
| 4 || index || uint32_t || The index of the specific output in the transaction. The first output is 0, etc.<br />
|}<br />
<br />
The Script structure consists of a series of pieces of information and operations related to the value of the transaction.<br />
<br />
(Structure to be expanded in the future… see script.h and script.cpp and [[Script]] for more information)<br />
<br />
The TxOut structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || value || int64_t || Transaction Value<br />
|-<br />
| 1+ || pk_script length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the pk_script<br />
|-<br />
| ? || pk_script || uchar[] || Usually contains the public key as a Bitcoin script setting up conditions to claim this output.<br />
|}<br />
<br />
Example ''tx'' message:<br />
<pre><br />
000000 F9 BE B4 D9 74 78 00 00 00 00 00 00 00 00 00 00 ....tx..........<br />
000010 02 01 00 00 E2 93 CD BE 01 00 00 00 01 6D BD DB .............m..<br />
000020 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D 12 66 E9 .[...Q........f.<br />
000030 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29 00 00 00 .;P......j.6)...<br />
000040 00 8B 48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 ..H0E.!..X..r...<br />
000050 C7 36 7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A .6zz%;..R#...h.:<br />
000060 59 23 3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 Y#?E.W... Y.....<br />
000070 0E 41 83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D .A.z.X.z...XN...<br />
000080 35 BD 96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF 5...6..;...A....<br />
000090 C9 7E F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 .~.6.m...@..!...<br />
0000A0 2A CD 2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC *.+..].}Y... ...<br />
0000B0 4E 02 53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F N.S..=7.o...Q...<br />
0000C0 14 04 2F 46 61 4A 4C 70 C0 F1 4B EF F5 FF FF FF ../FaJLp..K.....<br />
0000D0 FF 02 40 4B 4C 00 00 00 00 00 19 76 A9 14 1A A0 ..@KL......v....<br />
0000E0 CD 1C BE A6 E7 45 8A 7A BA D5 12 A9 D9 EA 1A FB .....E.z........<br />
0000F0 22 5E 88 AC 80 FA E9 C7 00 00 00 00 19 76 A9 14 "^...........v..<br />
000100 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E FD A0 B7 ..[.Cj.....H^...<br />
000110 8B 4E CC 52 88 AC 00 00 00 00 .N.R......<br />
<br />
<br />
Message header:<br />
F9 BE B4 D9 - main network magic bytes<br />
74 78 00 00 00 00 00 00 00 00 00 00 - "tx" command<br />
02 01 00 00 - payload is 258 bytes long<br />
E2 93 CD BE - checksum of payload<br />
<br />
Transaction:<br />
01 00 00 00 - version<br />
<br />
Inputs:<br />
01 - number of transaction inputs<br />
<br />
Input 1:<br />
6D BD DB 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D - previous output (outpoint)<br />
12 66 E9 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29<br />
00 00 00 00<br />
<br />
8B - script is 139 bytes long<br />
<br />
48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 C7 36 - signature script (scriptSig)<br />
7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A 59 23<br />
3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 0E 41<br />
83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D 35 BD<br />
96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF C9 7E<br />
F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 2A CD<br />
2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC 4E 02<br />
53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F 14 04<br />
2F 46 61 4A 4C 70 C0 F1 4B EF F5<br />
<br />
FF FF FF FF - sequence<br />
<br />
Outputs:<br />
02 - 2 Output Transactions<br />
<br />
Output 1:<br />
40 4B 4C 00 00 00 00 00 - 0.05 BTC (5000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 1A A0 CD 1C BE A6 E7 45 8A 7A BA D5 12 - pk_script<br />
A9 D9 EA 1A FB 22 5E 88 AC<br />
<br />
Output 2:<br />
80 FA E9 C7 00 00 00 00 - 33.54 BTC (3354000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E - pk_script<br />
FD A0 B7 8B 4E CC 52 88 AC<br />
<br />
Locktime:<br />
00 00 00 00 - lock time<br />
</pre><br />
<br />
=== block ===<br />
<br />
The '''block''' message is sent in response to a getdata message which requests transaction information from a block hash.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A Unix timestamp recording when this block was created (Currently limited to dates before the year 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated [[Difficulty|difficulty target]] being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| ? || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries<br />
|-<br />
| ? || txns || tx[] || Block transactions, in format of "tx" command<br />
|}<br />
<br />
The SHA256 hash that identifies each block (and which must have a run of 0 bits) is calculated from the first 6 fields of this structure (version, prev_block, merkle_root, timestamp, bits, nonce, and standard SHA256 padding, making two 64-byte chunks in all) and ''not'' from the complete block. To calculate the hash, only two chunks need to be processed by the SHA256 algorithm. Since the ''nonce'' field is in the second chunk, the first chunk stays constant during mining and therefore only the second chunk needs to be processed. However, a Bitcoin hash is the hash of the hash, so two SHA256 rounds are needed for each mining iteration.<br />
See [[Block hashing algorithm]] for details and an example.<br />
<br />
=== headers ===<br />
<br />
The ''headers'' packet returns block headers in response to a ''getheaders'' packet. <br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of block headers<br />
|-<br />
| 81x? || headers || [[Protocol_documentation#Block_Headers|block_header]][] || [[Protocol_documentation#Block_Headers|Block headers]]<br />
|}<br />
<br />
Note that the block headers in this packet include a transaction count (a var_int, so there can be more than 81 bytes per header) as opposed to the block headers that are hashed by miners.<br />
<br />
=== getaddr ===<br />
<br />
The getaddr message sends a request to a node asking for information about known active peers to help with finding potential nodes in the network. The response to receiving this message is to transmit one or more addr messages with one or more peers from a database of known active peers. The typical presumption is that a node is likely to be active if it has been sending a message within the last three hours.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
=== mempool ===<br />
<br />
The mempool message sends a request to a node asking for information about transactions it has verified but which have not yet confirmed. The response to receiving this message is an inv message containing the transaction hashes for all the transactions in the node's mempool.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
It is specified in [https://github.com/bitcoin/bips/blob/master/bip-0035.mediawiki BIP 35]. Since [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 37], if a [[Protocol_documentation#filterload.2C_filteradd.2C_filterclear.2C_merkleblock|bloom filter]] is loaded, only transactions matching the filter are replied.<br />
<br />
=== checkorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== submitorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== reply ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== ping ===<br />
<br />
The ''ping'' message is sent primarily to confirm that the TCP/IP connection is still valid. An error in transmission is presumed to be a closed connection and the address is removed as a current peer.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || random nonce<br />
|}<br />
<br />
=== pong ===<br />
<br />
The ''pong'' message is sent in response to a ''ping'' message. In modern protocol versions, a ''pong'' response is generated using a nonce included in the ping.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || nonce from ping<br />
|}<br />
<br />
<br />
=== reject===<br />
<br />
The ''reject'' message is sent when messages are rejected.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || message || var_str || type of message rejected<br />
|-<br />
| 1 || ccode || char || code relating to rejected message<br />
|-<br />
| 1+ || reason || var_str || text version of reason for rejection<br />
|-<br />
| 0+ || data || char || Optional extra data provided by some errors. Currently, all errors which provide this field fill it with the TXID or block header hash of the object being rejected, so the field is 32 bytes.<br />
|}<br />
<br />
CCodes<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0x01 || REJECT_MALFORMED|| <br />
|-<br />
| 0x10 || REJECT_INVALID ||<br />
|-<br />
| 0x11 || REJECT_OBSOLETE ||<br />
|-<br />
| 0x12 || REJECT_DUPLICATE ||<br />
|-<br />
| 0x40 || REJECT_NONSTANDARD ||<br />
|-<br />
| 0x41 || REJECT_DUST ||<br />
|-<br />
| 0x42 || REJECT_INSUFFICIENTFEE ||<br />
|-<br />
| 0x43 || REJECT_CHECKPOINT ||<br />
|}<br />
<br />
=== filterload, filteradd, filterclear, merkleblock ===<br />
<br />
These messages are related to Bloom filtering of connections and are defined in [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037].<br />
<br />
<br />
The <code>filterload</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || filter || uint8_t[] || The filter itself is simply a bit field of arbitrary byte-aligned size. The maximum size is 36,000 bytes.<br />
|-<br />
| 4 || nHashFuncs || uint32_t || The number of hash functions to use in this filter. The maximum value allowed in this field is 50.<br />
|-<br />
| 4 || nTweak || uint32_t || A random value to add to the seed value in the hash function used by the bloom filter.<br />
|-<br />
| 1 || nFlags || uint8_t || A set of flags that control how matched items are added to the filter.<br />
|}<br />
<br />
See below for a description of the Bloom filter algorithm and how to select nHashFuncs and filter size for a desired false positive rate.<br />
<br />
Upon receiving a <code>filterload</code> command, the remote peer will immediately restrict the broadcast transactions it announces (in inv packets) to transactions matching the filter, where the matching algorithm is specified below. The flags control the update behaviour of the matching algorithm.<br />
<br />
The <code>filteradd</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || data || uint8_t[] || The data element to add to the current filter.<br />
|}<br />
<br />
The data field must be smaller than or equal to 520 bytes in size (the maximum size of any potentially matched object).<br />
<br />
The given data element will be added to the Bloom filter. A filter must have been previously provided using <code>filterload</code>. This command is useful if a new key or script is added to a clients wallet whilst it has connections to the network open, it avoids the need to re-calculate and send an entirely new filter to every peer (though doing so is usually advisable to maintain anonymity).<br />
<br />
The <code>filterclear</code> command has no arguments at all.<br />
<br />
After a filter has been set, nodes don't merely stop announcing non-matching transactions, they can also serve filtered blocks. A filtered block is defined by the <code>merkleblock</code> message and is defined like this:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information, based upon the software version creating this block (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Limited to 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 4 || total_transactions || uint32_t || Number of transactions in the block (including unmatched ones)<br />
|-<br />
| ? || hashes || uint256[] || hashes in depth-first order (including standard varint size prefix)<br />
|-<br />
| ? || flags || byte[] || flag bits, packed per 8 in a byte, least significant bit first (including standard varint size prefix)<br />
|}<br />
<br />
=== alert ===<br />
<br />
An '''alert''' is sent between nodes to send a general notification message throughout the network. If the alert can be confirmed with the signature as having come from the core development group of the Bitcoin software, the message is suggested to be displayed for end-users. Attempts to perform transactions, particularly automated transactions through the client, are suggested to be halted. The text in the Message string should be relayed to log files and any user interfaces.<br />
<br />
Alert format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || payload || uchar[] || Serialized alert payload<br />
|-<br />
| ? || signature || uchar[] || An ECDSA signature of the message<br />
|}<br />
<br />
The developers of Satoshi's client use this public key for signing alerts:<br />
04fc9702847840aaf195de8442ebecedf5b095cdbb9bc716bda9110971b28a49e0ead8564ff0db22209e0374782c093bb899692d524e9d6a6956e7c5ecbcd68284<br />
(hash) 1AGRxqDa5WjUKBwHB9XYEjmkv1ucoUUy1s<br />
<br />
The payload is serialized into a uchar[] to ensure that versions using incompatible alert formats can still relay alerts among one another. The current alert payload format is:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || Version || int32_t || Alert format version<br />
|-<br />
| 8 || RelayUntil || int64_t || The timestamp beyond which nodes should stop relaying this alert<br />
|-<br />
| 8 || Expiration || int64_t || The timestamp beyond which this alert is no longer in effect and should be ignored<br />
|-<br />
| 4 || ID || int32_t || A unique ID number for this alert<br />
|-<br />
| 4 || Cancel || int32_t || All alerts with an ID number less than or equal to this number should be cancelled: deleted and not accepted in the future<br />
|-<br />
| ? || setCancel || set<int32_t> || All alert IDs contained in this set should be cancelled as above<br />
|-<br />
| 4 || MinVer || int32_t || This alert only applies to versions greater than or equal to this version. Other versions should still relay it.<br />
|-<br />
| 4 || MaxVer || int32_t || This alert only applies to versions less than or equal to this version. Other versions should still relay it.<br />
|-<br />
| ? || setSubVer || set<string> || If this set contains any elements, then only nodes that have their subVer contained in this set are affected by the alert. Other versions should still relay it.<br />
|-<br />
| 4 || Priority || int32_t || Relative priority compared to other alerts<br />
|-<br />
| ? || Comment || string || A comment on the alert that is not displayed<br />
|-<br />
| ? || StatusBar || string || The alert message that is displayed to the user<br />
|-<br />
| ? || Reserved || string || Reserved<br />
|}<br />
<br />
Note: '''set<''type''>''' in the table above is a [[#Variable length integer | variable length integer]] followed by the number of fields of the given ''type'' (either int32_t or [[#Variable length string | variable length string]])<br />
<br />
Sample alert (no message header):<br />
73010000003766404f00000000b305434f00000000f2030000f1030000001027000048ee0000<br />
0064000000004653656520626974636f696e2e6f72672f666562323020696620796f75206861<br />
76652074726f75626c6520636f6e6e656374696e672061667465722032302046656272756172<br />
79004730450221008389df45f0703f39ec8c1cc42c13810ffcae14995bb648340219e353b63b<br />
53eb022009ec65e1c1aaeec1fd334c6b684bde2b3f573060d5b70c3a46723326e4e8a4f1<br />
<br />
Version: 1<br />
RelayUntil: 1329620535<br />
Expiration: 1329792435<br />
ID: 1010<br />
Cancel: 1009<br />
setCancel: <empty><br />
MinVer: 10000<br />
MaxVer: 61000<br />
setSubVer: <empty><br />
Priority: 100<br />
Comment: <empty><br />
StatusBar: "See bitcoin.org/feb20 if you have trouble connecting after 20 February"<br />
Reserved: <empty><br />
<br />
=== sendheaders ===<br />
<br />
Request for Direct headers announcement. <br />
<br />
Upon receipt of this message, the node is be permitted, but not required, to announce new blocks by '''headers''' command (instead of '''inv''' command).<br />
<br />
This message is supported by the protocol version >= 70012 or Bitcoin Core version >= 0.12.0.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0130.mediawiki BIP 130] for more information.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
<br />
=== feefilter ===<br />
<br />
The payload is always 8 bytes long and it encodes 64 bit integer value (LSB / little endian) of '''feerate'''.<br />
The value represents a minimal fee and is expressed in satoshis per 1000 bytes.<br />
<br />
Upon receipt of a "feefilter" message, the node will be permitted, but not required, to filter transaction invs for transactions that fall below the feerate provided in the feefilter message interpreted as satoshis per kilobyte.<br />
<br />
The fee filter is additive with a bloom filter for transactions so if an SPV client were to load a bloom filter and send a feefilter message, transactions would only be relayed if they passed both filters.<br />
<br />
Inv's generated from a mempool message are also subject to a fee filter if it exists.<br />
<br />
Feature discovery is enabled by checking protocol version >= 70013<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0133.mediawiki BIP 133] for more information.<br />
<br />
=== sendcmpct ===<br />
<br />
# The sendcmpct message is defined as a message containing a 1-byte integer followed by a 8-byte integer where pchCommand == "sendcmpct".<br />
# The first integer SHALL be interpreted as a boolean (and MUST have a value of either 1 or 0)<br />
# The second integer SHALL be interpreted as a little-endian version number. Nodes sending a sendcmpct message MUST currently set this value to 1.<br />
# Upon receipt of a "sendcmpct" message with the first and second integers set to 1, the node SHOULD announce new blocks by sending a cmpctblock message.<br />
# Upon receipt of a "sendcmpct" message with the first integer set to 0, the node SHOULD NOT announce new blocks by sending a cmpctblock message, but SHOULD announce new blocks by sending invs or headers, as defined by BIP130.<br />
# Upon receipt of a "sendcmpct" message with the second integer set to something other than 1, nodes MUST treat the peer as if they had not received the message (as it indicates the peer will provide an unexpected encoding in <br />
# cmpctblock, and/or other, messages). This allows future versions to send duplicate sendcmpct messages with different versions as a part of a version handshake for future versions.<br />
# Nodes SHOULD check for a protocol version of >= 70014 before sending sendcmpct messages.<br />
# Nodes MUST NOT send a request for a MSG_CMPCT_BLOCK object to a peer before having received a sendcmpct message from that peer.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== cmpctblock ===<br />
<br />
# The cmpctblock message is defined as as a message containing a serialized HeaderAndShortIDs message and pchCommand == "cmpctblock".<br />
# Upon receipt of a cmpctblock message after sending a sendcmpct message, nodes SHOULD calculate the short transaction ID for each unconfirmed transaction they have available (ie in their mempool) and compare each to each short transaction ID in the cmpctblock message.<br />
# After finding already-available transactions, nodes which do not have all transactions available to reconstruct the full block SHOULD request the missing transactions using a getblocktxn message.<br />
# A node MUST NOT send a cmpctblock message unless they are able to respond to a getblocktxn message which requests every transaction in the block.<br />
# A node MUST NOT send a cmpctblock message without having validated that the header properly commits to each transaction in the block, and properly builds on top of the existing chain with a valid proof-of-work. A node MAY send a cmpctblock before validating that each transaction in the block validly spends existing UTXO set entries.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== getblocktxn ===<br />
<br />
# The getblocktxn message is defined as as a message containing a serialized BlockTransactionsRequest message and pchCommand == "getblocktxn".<br />
# Upon receipt of a properly-formatted getblocktxnmessage, nodes which recently provided the sender of such a message a cmpctblock for the block hash identified in this message MUST respond with an appropriate blocktxn message. Such a blocktxn message MUST contain exactly and only each transaction which is present in the appropriate block at the index specified in the getblocktxn indexes list, in the order requested.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== blocktxn ===<br />
<br />
# The blocktxn message is defined as as a message containing a serialized BlockTransactions message and pchCommand == "blocktxn".<br />
# Upon receipt of a properly-formatted requested blocktxn message, nodes SHOULD attempt to reconstruct the full block by:<br />
# Taking the prefilledtxn transactions from the original cmpctblock and placing them in the marked positions.<br />
# For each short transaction ID from the original cmpctblock, in order, find the corresponding transaction either from the blocktxn message or from other sources and place it in the first available position in the block.<br />
# Once the block has been reconstructed, it shall be processed as normal, keeping in mind that short transaction IDs are expected to occasionally collide, and that nodes MUST NOT be penalized for such collisions, wherever they # appear.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
== Scripting ==<br />
<br />
See [[script]].<br />
<br />
==See Also==<br />
<br />
* [[Network]]<br />
* [[Protocol rules]]<br />
* [[Hardfork Wishlist]]<br />
* [https://bitcoin.org/en/developer-documentation Developer Documentation on bitcoin.org]<br />
* Bitcoin dissectors for Wireshark: https://github.com/lbotsch/wireshark-bitcoin https://github.com/op-sig/bitcoin-wireshark-dissector<br />
<br />
==References==<br />
<references /><br />
<br />
[[zh-cn:协议说明]]<br />
[[Category:Technical]]<br />
[[Category:Developer]]<br />
<br />
{{Bitcoin Core documentation}}</div>Tonikthttps://en.bitcoin.it/w/index.php?title=Protocol_documentation&diff=61489Protocol documentation2016-08-25T12:39:28Z<p>Tonikt: /* PrefilledTransaction */</p>
<hr />
<div>This page ''describes'' the behavior of the [[Original Bitcoin client|reference client]]. The Bitcoin protocol is specified by the behavior of the reference client, not by this page. In particular, while this page is quite complete in describing the network protocol, it does not attempt to list all of the rules for block or transaction validity.<br />
<br />
Type names used in this documentation are from the C99 standard.<br />
<br />
For protocol used in mining, see [[getblocktemplate]].<br />
<br />
==Common standards==<br />
<br />
=== Hashes ===<br />
<br />
Usually, when a hash is computed within bitcoin, it is computed twice. Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-256] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when a shorter hash is desirable (for example when creating a bitcoin address).<br />
<br />
Example of double-SHA-256 encoding of string "hello":<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round of sha-256)<br />
9595c9df90075148eb06860365df33584b75bff782a510c6cd4883a419833d50 (second round of sha-256)<br />
<br />
For bitcoin addresses (RIPEMD-160) this would give:<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round is sha-256)<br />
b6a9c8c230722b7c748331a8b450f05566dc7d0f (with ripemd-160)<br />
<br />
=== Merkle Trees ===<br />
<br />
Merkle trees are binary trees of hashes. Merkle trees in bitcoin use a '''double''' SHA-256, the SHA-256 hash of the SHA-256 hash of something.<br />
<br />
If, when forming a row in the tree (other than the root of the tree), it would have an odd number of elements, the final double-hash is duplicated to ensure that the row has an even number of hashes.<br />
<br />
First form the bottom row of the tree with the ordered double-SHA-256 hashes of the byte streams of the transactions in the block.<br />
<br />
Then the row above it consists of half that number of hashes. Each entry is the double-SHA-256 of the 64-byte concatenation of the corresponding two hashes below it in the tree.<br />
<br />
This procedure repeats recursively until we reach a row consisting of just a single double-hash. This is the '''Merkle root''' of the tree.<br />
<br />
For example, imagine a block with three transactions ''a'', ''b'' and ''c''. The Merkle tree is: <br />
<br />
d1 = dhash(a)<br />
d2 = dhash(b)<br />
d3 = dhash(c)<br />
d4 = dhash(c) # a, b, c are 3. that's an odd number, so we take the c twice<br />
<br />
d5 = dhash(d1 concat d2)<br />
d6 = dhash(d3 concat d4)<br />
<br />
d7 = dhash(d5 concat d6)<br />
<br />
where<br />
<br />
dhash(a) = sha256(sha256(a))<br />
<br />
''d7'' is the Merkle root of the 3 transactions in this block.<br />
<br />
Note: Hashes in Merkle Tree displayed in the [[Block Explorer]] are of little-endian notation. For some implementations and [http://www.fileformat.info/tool/hash.htm calculations], the bits need to be reversed before they are hashed, and again after the hashing operation.<br />
<br />
=== Signatures ===<br />
<br />
Bitcoin uses [http://en.wikipedia.org/wiki/Elliptic_curve_cryptography Elliptic Curve] [http://en.wikipedia.org/wiki/Digital_Signature_Algorithm Digital Signature Algorithm] ([http://en.wikipedia.org/wiki/Elliptic_Curve_DSA ECDSA]) to sign transactions. <br />
<br />
For [[ECDSA]] the secp256k1 curve from http://www.secg.org/collateral/sec2_final.pdf is used.<br />
<br />
Public keys (in scripts) are given as 04 <x> <y> where ''x'' and ''y'' are 32 byte big-endian integers representing the coordinates of a point on the curve or in compressed form given as <sign> <x> where <sign> is 0x02 if ''y'' is even and 0x03 if ''y'' is odd.<br />
<br />
Signatures use [http://en.wikipedia.org/wiki/Distinguished_Encoding_Rules DER encoding] to pack the ''r'' and ''s'' components into a single byte stream (this is also what OpenSSL produces by default).<br />
<br />
=== Transaction Verification ===<br />
Transactions are cryptographically signed records that reassign ownership of Bitcoins to new addresses. Transactions have ''inputs'' - records which reference the funds from other previous transactions - and ''outputs'' - records which determine the new owner of the transferred Bitcoins, and which will be referenced as inputs in future transactions as those funds are respent.<br />
<br />
Each ''input'' must have a cryptographic digital signature that unlocks the funds from the prior transaction. Only the person possessing the appropriate [[private key]] is able to create a satisfactory signature; this in effect ensures that funds can only be spent by their owners.<br />
<br />
Each ''output'' determines which Bitcoin address (or other criteria, see [[Script]]) is the recipient of the funds.<br />
<br />
In a transaction, the sum of all inputs must be equal to or greater than the sum of all outputs. If the inputs exceed the outputs, the difference is considered a [[transaction fee]], and is redeemable by whoever first includes the transaction into the block chain.<br />
<br />
A special kind of transaction, called a [[coinbase transaction]], has no inputs. It is created by [[miners]], and there is one coinbase transaction per block. Because each block comes with a reward of newly created Bitcoins (e.g. 50 BTC for the first 210,000 blocks), the first transaction of a block is, with few exceptions, the transaction that grants those coins to their recipient (the miner). In addition to the newly created Bitcoins, the coinbase transaction is also used for assigning the recipient of any transaction fees that were paid within the other transactions being included in the same block. The coinbase transaction can assign the entire reward to a single Bitcoin address, or split it in portions among multiple addresses, just like any other transaction. Coinbase transactions always contain outputs totalling the sum of the block reward plus all transaction fees collected from the other transactions in the same block.<br />
<br />
The [[coinbase transaction]] in block zero cannot be spent. This is due to a quirk of the reference client implementation that would open the potential for a block chain fork if some nodes accepted the spend and others did not<ref>[http://bitcointalk.org/index.php?topic=119645.msg1288552#msg1288552 Block 0 Network Fork]</ref>.<br />
<br />
Most Bitcoin outputs encumber the newly transferred coins with a single ECDSA private key. The actual record saved with inputs and outputs isn't necessarily a key, but a ''script''. Bitcoin uses an interpreted scripting system to determine whether an output's criteria have been satisfied, with which more complex operations are possible, such as outputs that require two ECDSA signatures, or two-of-three-signature schemes. An output that references a single Bitcoin address is a ''typical'' output; an output actually contains this information in the form of a script that requires a single ECDSA signature (see [[OP_CHECKSIG]]). The output script specifies what must be provided to unlock the funds later, and when the time comes in the future to spend the transaction in another input, that input must provide all of the thing(s) that satisfy the requirements defined by the original output script.<br />
<br />
=== Addresses ===<br />
<br />
A bitcoin address is in fact the hash of a ECDSA public key, computed this way:<br />
<br />
Version = 1 byte of 0 (zero); on the test network, this is 1 byte of 111<br />
Key hash = Version concatenated with RIPEMD-160(SHA-256(public key))<br />
Checksum = 1st 4 bytes of SHA-256(SHA-256(Key hash))<br />
Bitcoin Address = Base58Encode(Key hash concatenated with Checksum)<br />
<br />
The Base58 encoding used is home made, and has some differences. Especially, leading zeroes are kept as single zeroes when conversion happens.<br />
<br />
== Common structures ==<br />
<br />
Almost all integers are encoded in little endian. Only IP or port number are encoded big endian.<br />
<br />
=== Message structure ===<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown<br />
|-<br />
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| 4 || length || uint32_t || Length of payload in number of bytes<br />
|-<br />
| 4 || checksum || uint32_t || First 4 bytes of sha256(sha256(payload))<br />
|-<br />
| ? || payload || uchar[] || The actual data<br />
|}<br />
<br />
<br />
Known magic values:<br />
<br />
{|class="wikitable"<br />
! Network !! Magic value !! Sent over wire as<br />
|-<br />
| main || 0xD9B4BEF9 || F9 BE B4 D9<br />
|-<br />
| testnet || 0xDAB5BFFA || FA BF B5 DA<br />
|-<br />
| testnet3 || 0x0709110B || 0B 11 09 07<br />
|-<br />
| namecoin || 0xFEB4BEF9 || F9 BE B4 FE<br />
|}<br />
<br />
=== Variable length integer ===<br />
<br />
Integer can be encoded depending on the represented value to save space.<br />
Variable length integers always precede an array/vector of a type of data that may vary in length.<br />
Longer numbers are encoded in little endian.<br />
<br />
{|class="wikitable"<br />
! Value !! Storage length !! Format<br />
|-<br />
| < 0xFD || 1 || uint8_t<br />
|-<br />
| <= 0xFFFF || 3 || 0xFD followed by the length as uint16_t<br />
|-<br />
| <= 0xFFFF FFFF || 5 || 0xFE followed by the length as uint32_t<br />
|-<br />
| - || 9 || 0xFF followed by the length as uint64_t<br />
|}<br />
<br />
If you're reading the Satoshi client code (BitcoinQT) it refers to this encoding as a "CompactSize". Modern BitcoinQT also has the CVarInt class which implements an even more compact integer for the purpose of local storage (which is incompatible with "CompactSize" described here). CVarInt is not a part of the protocol.<br />
<br />
=== Variable length string ===<br />
<br />
Variable length string can be stored using a variable length integer followed by the string itself.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the string<br />
|-<br />
| ? || string || char[] || The string itself (can be empty)<br />
|}<br />
<br />
=== Network address ===<br />
<br />
When a network address is needed somewhere, this structure is used. Network addresses are not prefixed with a timestamp in the version message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || time || uint32 || the Time (version >= 31402). '''Not present in version message.'''<br />
|-<br />
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]<br />
|-<br />
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The original client only supported IPv4 and only read the last 4 bytes to get the IPv4 address. However, the IPv4 address is written into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]<br />
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).<br />
|-<br />
| 2 || port || uint16_t || port number, network byte order<br />
|}<br />
<br />
Hexdump example of Network address structure<br />
<br />
<pre><br />
0000 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0010 00 00 FF FF 0A 00 00 01 20 8D ........ .<br />
<br />
Network address:<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK: see services listed under version command)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv6: ::ffff:a00:1 or IPv4: 10.0.0.1<br />
20 8D - Port 8333<br />
</pre><br />
<br />
=== Inventory Vectors ===<br />
<br />
Inventory vectors are used for notifying other nodes about objects they have or data which is being requested.<br />
<br />
Inventory vectors consist of the following data format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || type || uint32_t || Identifies the object type linked to this inventory<br />
|-<br />
| 32 || hash || char[32] || Hash of the object<br />
|}<br />
<br />
<br />
The object type is currently defined as one of the following possibilities:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0 || ERROR || Any data of with this number may be ignored<br />
|-<br />
| 1 || MSG_TX || Hash is related to a transaction<br />
|-<br />
| 2 || MSG_BLOCK || Hash is related to a data block<br />
|-<br />
| 3 || MSG_FILTERED_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a merkleblock message rather than a block message; this only works if a bloom filter has been set.<br />
|-<br />
| 4 || MSG_CMPCT_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a cmpctblock message. See BIP 152 for more info.<br />
|}<br />
<br />
Other Data Type values are considered reserved for future implementations.<br />
<br />
=== Block Headers ===<br />
<br />
Block headers are sent in a headers packet in response to a getheaders message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Will overflow in 2106<ref>https://en.wikipedia.org/wiki/Unix_time#Notable_events_in_Unix_time</ref>)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 1 || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries, this value is always 0<br />
|}<br />
<br />
cf. [[Block hashing algorithm]]<br />
<br />
=== PrefilledTransaction ===<br />
<br />
A PrefilledTransaction structure is used in HeaderAndShortIDs to provide a list of a few transactions explicitly.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| index || [[Protocol_documentation#Variable_length_integer|CompactSize]] || 1, 3 bytes || Compact Size, differentially encoded since the last PrefilledTransaction in a list || The index into the block at which this transaction is<br />
|-<br />
| tx || Transaction || variable || As encoded in "tx" messages || The transaction which is in the block at index index.<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== HeaderAndShortIDs ===<br />
<br />
A HeaderAndShortIDs structure is used to relay a block header, the short transactions IDs used for matching already-available transactions, and a select few transactions which we expect a peer may be missing.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| header || Block header || 80 bytes || First 80 bytes of the block as defined by the encoding used by "block" messages || The header of the block being provided<br />
|-<br />
| nonce || uint64_t || 8 bytes || Little Endian || A nonce for use in short transaction ID calculations<br />
|-<br />
| shortids_length || CompactSize || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of short transaction IDs in shortids (ie block tx count - prefilledtxn_length)<br />
|-<br />
| shortids || List of 6-byte integers || 6*shortids_length bytes || Little Endian || The short transaction IDs calculated from the transactions which were not provided explicitly in prefilledtxn<br />
|-<br />
| prefilledtxn_length || CompactSize || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of prefilled transactions in prefilledtxn (ie block tx count - shortids_length)<br />
|-<br />
| prefilledtxn || List of PrefilledTransactions || variable size*prefilledtxn_length || As defined by PrefilledTransaction definition, above || Used to provide the coinbase transaction and a select few which we expect a peer may be missing<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== BlockTransactionsRequest ===<br />
<br />
A BlockTransactionsRequest structure is used to list transaction indexes in a block being requested.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| blockhash || Binary blob || 32 bytes || The output from a double-SHA256 of the block header, as used elsewhere || The blockhash of the block which the transactions being requested are in<br />
|-<br />
| indexes_length || CompactSize || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of transactions being requested<br />
|-<br />
| indexes || List of CompactSizes || 1 or 3 bytes*indexes_length || Differentially encoded || The indexes of the transactions being requested in the block<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== BlockTransactions ===<br />
<br />
A BlockTransactions structure is used to provide some of the transactions in a block, as requested.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== Short transaction IDs ===<br />
<br />
Short transaction IDs are used to represent a transaction without sending a full 256-bit hash. They are calculated by:<br />
<br />
# single-SHA256 hashing the block header with the nonce appended (in little-endian)<br />
# Running SipHash-2-4 with the input being the transaction ID and the keys (k0/k1) set to the first two little-endian 64-bit integers from the above hash, respectively.<br />
# Dropping the 2 most significant bytes from the SipHash output to make it 6 bytes.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
== Message types ==<br />
<br />
=== version ===<br />
<br />
When a node creates an outgoing connection, it will immediately [[Version Handshake|advertise]] its version. The remote node will respond with its version. No further communication is possible until both peers have exchanged their version.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Identifies protocol version being used by the node<br />
|-<br />
| 8 || services || uint64_t || bitfield of features to be enabled for this connection<br />
|-<br />
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds<br />
|-<br />
| 26 || addr_recv || [[#Network address|net_addr]] || The network address of the node receiving this message<br />
|-<br />
|colspan="4"| Fields below require version ≥ 106<br />
|-<br />
| 26 || addr_from || [[#Network address|net_addr]] || The network address of the node emitting this message<br />
|-<br />
| 8 || nonce || uint64_t || Node random nonce, randomly generated every time a version packet is sent. This nonce is used to detect connections to self.<br />
|-<br />
| ? || user_agent || [[#Variable length string|var_str]] || [https://github.com/bitcoin/bips/blob/master/bip-0014.mediawiki User Agent] (0x00 if string is 0 bytes long)<br />
|-<br />
| 4 || start_height || int32_t || The last block received by the emitting node<br />
|-<br />
|colspan="4"| Fields below require version ≥ 70001<br />
|-<br />
| 1 || relay || bool || Whether the remote peer should announce relayed transactions or not, see [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037]<br />
|}<br />
<br />
A "verack" packet shall be sent if the version packet was accepted.<br />
<br />
The following services are currently assigned:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 1 || NODE_NETWORK || This node can be asked for full blocks instead of just headers.<br />
|}<br />
<br />
Hexdump example of version message (OBSOLETE EXAMPLE: This example lacks a checksum and user-agent):<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....<br />
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........<br />
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............<br />
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................<br />
0040 20 8D 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,<br />
0060 3A B4 57 13 00 55 81 01 00 :.W..U...<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
55 00 00 00 - Payload is 85 bytes long<br />
- No checksum in version message until 20 February 2012. See https://bitcointalk.org/index.php?topic=55852.0<br />
Version message:<br />
9C 7C 00 00 - 31900 (version 0.3.19)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
E6 15 10 4D 00 00 00 00 - Mon Dec 20 21:50:14 EST 2010<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 20 8D - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D - Sender address info - see Network Address<br />
DD 9D 20 2C 3A B4 57 13 - Node random unique ID<br />
00 - "" sub-version string (string is 0 bytes long)<br />
55 81 01 00 - Last block sending node has is block #98645<br />
</pre><br />
<br />
And here's a modern (60002) protocol version client advertising itself to a local peer...<br />
<br />
Newer protocol includes the checksum now, this is from a mainline (satoshi) client during <br />
an outgoing connection to another local client, notice that it does not fill out the <br />
address information at all when the source or destination is "unroutable".<br />
<br />
<pre><br />
<br />
0000 f9 be b4 d9 76 65 72 73 69 6f 6e 00 00 00 00 00 ....version.....<br />
0010 64 00 00 00 35 8d 49 32 62 ea 00 00 01 00 00 00 d...5.I2b.......<br />
0020 00 00 00 00 11 b2 d0 50 00 00 00 00 01 00 00 00 .......P........<br />
0030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ff ff ................<br />
0040 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 00 00 00 00 ff ff 00 00 00 00 00 00 ................<br />
0060 3b 2e b3 5d 8c e6 17 65 0f 2f 53 61 74 6f 73 68 ;..]...e./Satosh<br />
0070 69 3a 30 2e 37 2e 32 2f c0 3e 03 00 i:0.7.2/.>..<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
64 00 00 00 - Payload is 100 bytes long<br />
3B 64 8D 5A - payload checksum<br />
<br />
Version message:<br />
62 EA 00 00 - 60002 (protocol version 60002)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
11 B2 D0 50 00 00 00 00 - Tue Dec 18 10:12:33 PST 2012<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Sender address info - see Network Address<br />
3B 2E B3 5D 8C E6 17 65 - Node ID<br />
0F 2F 53 61 74 6F 73 68 69 3A 30 2E 37 2E 32 2F - "/Satoshi:0.7.2/" sub-version string (string is 15 bytes long)<br />
C0 3E 03 00 - Last block sending node has is block #212672<br />
</pre><br />
<br />
=== verack ===<br />
<br />
The ''verack'' message is sent in reply to ''[[#version|version]]''. This message consists of only a [[#Message structure|message header]] with the command string "verack".<br />
<br />
Hexdump of the verack message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......<br />
0010 00 00 00 00 5D F6 E0 E2 ........<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 61 63 6B 00 00 00 00 00 00 - "verack" command<br />
00 00 00 00 - Payload is 0 bytes long<br />
5D F6 E0 E2 - Checksum<br />
</pre><br />
<br />
=== addr ===<br />
<br />
Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours<br />
<br />
Payload:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of address entries (max: 1000)<br />
|-<br />
| 30x? || addr_list || (uint32_t + [[#Network address|net_addr]])[] || Address of other nodes on the network. version < 209 will only read the first one. The uint32_t is a timestamp (see note below).<br />
|}<br />
<br />
'''Note''': Starting version 31402, addresses are prefixed with a timestamp. If no timestamp is present, the addresses should not be relayed to other peers, unless it is indeed confirmed they are up.<br />
<br />
Hexdump example of ''addr'' message:<br />
<pre><br />
0000 F9 BE B4 D9 61 64 64 72 00 00 00 00 00 00 00 00 ....addr........<br />
0010 1F 00 00 00 ED 52 39 9B 01 E2 15 10 4D 01 00 00 .....R9.....M...<br />
0020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF ................<br />
0030 FF 0A 00 00 01 20 8D ..... .<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
61 64 64 72 00 00 00 00 00 00 00 00 - "addr"<br />
1F 00 00 00 - payload is 31 bytes long<br />
ED 52 39 9B - checksum of payload<br />
<br />
Payload:<br />
01 - 1 address in this message<br />
<br />
Address:<br />
E2 15 10 4D - Mon Dec 20 21:50:10 EST 2010 (only when version is >= 31402)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK service - see version message)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv4: 10.0.0.1, IPv6: ::ffff:10.0.0.1 (IPv4-mapped IPv6 address)<br />
20 8D - port 8333<br />
</pre><br />
<br />
=== inv ===<br />
<br />
Allows a node to advertise its knowledge of one or more objects. It can be received unsolicited, or in reply to ''getblocks''.<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getdata ===<br />
<br />
getdata is used in response to inv, to retrieve the content of a specific object, and is usually sent after receiving an ''inv'' packet, after filtering known elements. It can be used to retrieve transactions, but only if they are in the memory pool or relay set - arbitrary access to transactions in the chain is not allowed to avoid having clients start to depend on nodes having full transaction indexes (which modern nodes do not).<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== notfound ===<br />
<br />
notfound is a response to a getdata, sent if any requested data items could not be relayed, for example, because the requested transaction was not in the memory pool or relay set.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getblocks ===<br />
<br />
Return an ''inv'' packet containing the list of blocks starting right after the last known hash in the block locator object, up to hash_stop or 500 blocks, whichever comes first. <br />
<br />
The locator hashes are processed by a node in the order as they appear in the message. If a block hash is found in the node's main chain, the list of its children is returned back via the ''inv'' message and the remaining locators are ignored, no matter if the requested limit was reached, or not.<br />
<br />
To receive the next blocks hashes, one needs to issue getblocks again with a new block locator object. Keep in mind that some clients may provide blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block; set to zero to get as many blocks as possible (500)<br />
|}<br />
<br />
To create the block locator hashes, keep pushing hashes until you go back to the genesis block. After pushing 10 hashes back, the step backwards doubles every loop:<br />
<br />
<pre><br />
// From libbitcoin which is under AGPL<br />
std::vector<size_t> block_locator_indexes(size_t top_height)<br />
{<br />
std::vector<size_t> indexes;<br />
<br />
// Modify the step in the iteration.<br />
int64_t step = 1;<br />
<br />
// Start at the top of the chain and work backwards.<br />
for (auto index = (int64_t)top_height; index > 0; index -= step)<br />
{<br />
// Push top 10 indexes first, then back off exponentially.<br />
if (indexes.size() >= 10)<br />
step *= 2;<br />
<br />
indexes.push_back((size_t)index);<br />
}<br />
<br />
// Push the genesis block index.<br />
indexes.push_back(0);<br />
return indexes;<br />
}<br />
</pre><br />
<br />
Note that it is allowed to send in fewer known hashes down to a minimum of just one hash. However, the purpose of the block locator object is to detect a wrong branch in the caller's main chain. If the peer detects that you are off the main chain, it will send in block hashes which are earlier than your last known block. So if you just send in your last known hash and it is off the main chain, the peer starts over at block #1.<br />
<br />
=== getheaders ===<br />
<br />
Return a ''headers'' packet containing the headers of blocks starting right after the last known hash in the block locator object, up to hash_stop or 2000 blocks, whichever comes first. To receive the next block headers, one needs to issue getheaders again with a new block locator object. The ''getheaders'' command is used by thin clients to quickly download the block chain where the contents of the transactions would be irrelevant (because they are not ours). Keep in mind that some clients may provide headers of blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block header; set to zero to get as many blocks as possible (2000)<br />
|}<br />
<br />
For the block locator object in this packet, the same rules apply as for the [[Protocol_documentation#getblocks|getblocks]] packet.<br />
<br />
=== tx ===<br />
<br />
''tx'' describes a bitcoin transaction, in reply to ''[[#getdata|getdata]]''<br />
<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Transaction data format version (note, this is signed)<br />
|-<br />
| 1+ || tx_in count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction inputs<br />
|-<br />
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins<br />
|-<br />
| 1+ || tx_out count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction outputs<br />
|-<br />
| 9+ || tx_out || tx_out[] || A list of 1 or more transaction outputs or destinations for coins<br />
|-<br />
| 4 || lock_time || uint32_t || The block number or timestamp at which this transaction is locked:<br />
{|class="wikitable"<br />
! Value !! Description<br />
|-<br />
| 0 || Not locked<br />
|-<br />
| < 500000000 || Block number at which this transaction is locked<br />
|-<br />
| >= 500000000 || UNIX timestamp at which this transaction is locked<br />
|}<br />
If all TxIn inputs have final (0xffffffff) sequence numbers then lock_time is irrelevant. Otherwise, the transaction may not be added to a block until after lock_time (see [[NLockTime]]).<br />
<br />
|}<br />
<br />
TxIn consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 36 || previous_output || outpoint || The previous output transaction reference, as an OutPoint structure<br />
|-<br />
| 1+ || script length || [[Protocol_documentation#Variable_length_integer|var_int]] || The length of the signature script<br />
|-<br />
| ? || signature script || uchar[] || Computational Script for confirming transaction authorization<br />
|-<br />
| 4 || [http://bitcoin.stackexchange.com/q/2025/323 sequence] || uint32_t || Transaction version as defined by the sender. Intended for "replacement" of transactions when information is updated before inclusion into a block.<br />
|}<br />
<br />
The OutPoint structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 32 || hash || char[32] || The hash of the referenced transaction.<br />
|-<br />
| 4 || index || uint32_t || The index of the specific output in the transaction. The first output is 0, etc.<br />
|}<br />
<br />
The Script structure consists of a series of pieces of information and operations related to the value of the transaction.<br />
<br />
(Structure to be expanded in the future… see script.h and script.cpp and [[Script]] for more information)<br />
<br />
The TxOut structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || value || int64_t || Transaction Value<br />
|-<br />
| 1+ || pk_script length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the pk_script<br />
|-<br />
| ? || pk_script || uchar[] || Usually contains the public key as a Bitcoin script setting up conditions to claim this output.<br />
|}<br />
<br />
Example ''tx'' message:<br />
<pre><br />
000000 F9 BE B4 D9 74 78 00 00 00 00 00 00 00 00 00 00 ....tx..........<br />
000010 02 01 00 00 E2 93 CD BE 01 00 00 00 01 6D BD DB .............m..<br />
000020 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D 12 66 E9 .[...Q........f.<br />
000030 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29 00 00 00 .;P......j.6)...<br />
000040 00 8B 48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 ..H0E.!..X..r...<br />
000050 C7 36 7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A .6zz%;..R#...h.:<br />
000060 59 23 3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 Y#?E.W... Y.....<br />
000070 0E 41 83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D .A.z.X.z...XN...<br />
000080 35 BD 96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF 5...6..;...A....<br />
000090 C9 7E F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 .~.6.m...@..!...<br />
0000A0 2A CD 2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC *.+..].}Y... ...<br />
0000B0 4E 02 53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F N.S..=7.o...Q...<br />
0000C0 14 04 2F 46 61 4A 4C 70 C0 F1 4B EF F5 FF FF FF ../FaJLp..K.....<br />
0000D0 FF 02 40 4B 4C 00 00 00 00 00 19 76 A9 14 1A A0 ..@KL......v....<br />
0000E0 CD 1C BE A6 E7 45 8A 7A BA D5 12 A9 D9 EA 1A FB .....E.z........<br />
0000F0 22 5E 88 AC 80 FA E9 C7 00 00 00 00 19 76 A9 14 "^...........v..<br />
000100 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E FD A0 B7 ..[.Cj.....H^...<br />
000110 8B 4E CC 52 88 AC 00 00 00 00 .N.R......<br />
<br />
<br />
Message header:<br />
F9 BE B4 D9 - main network magic bytes<br />
74 78 00 00 00 00 00 00 00 00 00 00 - "tx" command<br />
02 01 00 00 - payload is 258 bytes long<br />
E2 93 CD BE - checksum of payload<br />
<br />
Transaction:<br />
01 00 00 00 - version<br />
<br />
Inputs:<br />
01 - number of transaction inputs<br />
<br />
Input 1:<br />
6D BD DB 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D - previous output (outpoint)<br />
12 66 E9 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29<br />
00 00 00 00<br />
<br />
8B - script is 139 bytes long<br />
<br />
48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 C7 36 - signature script (scriptSig)<br />
7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A 59 23<br />
3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 0E 41<br />
83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D 35 BD<br />
96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF C9 7E<br />
F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 2A CD<br />
2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC 4E 02<br />
53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F 14 04<br />
2F 46 61 4A 4C 70 C0 F1 4B EF F5<br />
<br />
FF FF FF FF - sequence<br />
<br />
Outputs:<br />
02 - 2 Output Transactions<br />
<br />
Output 1:<br />
40 4B 4C 00 00 00 00 00 - 0.05 BTC (5000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 1A A0 CD 1C BE A6 E7 45 8A 7A BA D5 12 - pk_script<br />
A9 D9 EA 1A FB 22 5E 88 AC<br />
<br />
Output 2:<br />
80 FA E9 C7 00 00 00 00 - 33.54 BTC (3354000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E - pk_script<br />
FD A0 B7 8B 4E CC 52 88 AC<br />
<br />
Locktime:<br />
00 00 00 00 - lock time<br />
</pre><br />
<br />
=== block ===<br />
<br />
The '''block''' message is sent in response to a getdata message which requests transaction information from a block hash.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A Unix timestamp recording when this block was created (Currently limited to dates before the year 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated [[Difficulty|difficulty target]] being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| ? || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries<br />
|-<br />
| ? || txns || tx[] || Block transactions, in format of "tx" command<br />
|}<br />
<br />
The SHA256 hash that identifies each block (and which must have a run of 0 bits) is calculated from the first 6 fields of this structure (version, prev_block, merkle_root, timestamp, bits, nonce, and standard SHA256 padding, making two 64-byte chunks in all) and ''not'' from the complete block. To calculate the hash, only two chunks need to be processed by the SHA256 algorithm. Since the ''nonce'' field is in the second chunk, the first chunk stays constant during mining and therefore only the second chunk needs to be processed. However, a Bitcoin hash is the hash of the hash, so two SHA256 rounds are needed for each mining iteration.<br />
See [[Block hashing algorithm]] for details and an example.<br />
<br />
=== headers ===<br />
<br />
The ''headers'' packet returns block headers in response to a ''getheaders'' packet. <br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of block headers<br />
|-<br />
| 81x? || headers || [[Protocol_documentation#Block_Headers|block_header]][] || [[Protocol_documentation#Block_Headers|Block headers]]<br />
|}<br />
<br />
Note that the block headers in this packet include a transaction count (a var_int, so there can be more than 81 bytes per header) as opposed to the block headers that are hashed by miners.<br />
<br />
=== getaddr ===<br />
<br />
The getaddr message sends a request to a node asking for information about known active peers to help with finding potential nodes in the network. The response to receiving this message is to transmit one or more addr messages with one or more peers from a database of known active peers. The typical presumption is that a node is likely to be active if it has been sending a message within the last three hours.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
=== mempool ===<br />
<br />
The mempool message sends a request to a node asking for information about transactions it has verified but which have not yet confirmed. The response to receiving this message is an inv message containing the transaction hashes for all the transactions in the node's mempool.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
It is specified in [https://github.com/bitcoin/bips/blob/master/bip-0035.mediawiki BIP 35]. Since [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 37], if a [[Protocol_documentation#filterload.2C_filteradd.2C_filterclear.2C_merkleblock|bloom filter]] is loaded, only transactions matching the filter are replied.<br />
<br />
=== checkorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== submitorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== reply ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== ping ===<br />
<br />
The ''ping'' message is sent primarily to confirm that the TCP/IP connection is still valid. An error in transmission is presumed to be a closed connection and the address is removed as a current peer.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || random nonce<br />
|}<br />
<br />
=== pong ===<br />
<br />
The ''pong'' message is sent in response to a ''ping'' message. In modern protocol versions, a ''pong'' response is generated using a nonce included in the ping.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || nonce from ping<br />
|}<br />
<br />
<br />
=== reject===<br />
<br />
The ''reject'' message is sent when messages are rejected.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || message || var_str || type of message rejected<br />
|-<br />
| 1 || ccode || char || code relating to rejected message<br />
|-<br />
| 1+ || reason || var_str || text version of reason for rejection<br />
|-<br />
| 0+ || data || char || Optional extra data provided by some errors. Currently, all errors which provide this field fill it with the TXID or block header hash of the object being rejected, so the field is 32 bytes.<br />
|}<br />
<br />
CCodes<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0x01 || REJECT_MALFORMED|| <br />
|-<br />
| 0x10 || REJECT_INVALID ||<br />
|-<br />
| 0x11 || REJECT_OBSOLETE ||<br />
|-<br />
| 0x12 || REJECT_DUPLICATE ||<br />
|-<br />
| 0x40 || REJECT_NONSTANDARD ||<br />
|-<br />
| 0x41 || REJECT_DUST ||<br />
|-<br />
| 0x42 || REJECT_INSUFFICIENTFEE ||<br />
|-<br />
| 0x43 || REJECT_CHECKPOINT ||<br />
|}<br />
<br />
=== filterload, filteradd, filterclear, merkleblock ===<br />
<br />
These messages are related to Bloom filtering of connections and are defined in [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037].<br />
<br />
<br />
The <code>filterload</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || filter || uint8_t[] || The filter itself is simply a bit field of arbitrary byte-aligned size. The maximum size is 36,000 bytes.<br />
|-<br />
| 4 || nHashFuncs || uint32_t || The number of hash functions to use in this filter. The maximum value allowed in this field is 50.<br />
|-<br />
| 4 || nTweak || uint32_t || A random value to add to the seed value in the hash function used by the bloom filter.<br />
|-<br />
| 1 || nFlags || uint8_t || A set of flags that control how matched items are added to the filter.<br />
|}<br />
<br />
See below for a description of the Bloom filter algorithm and how to select nHashFuncs and filter size for a desired false positive rate.<br />
<br />
Upon receiving a <code>filterload</code> command, the remote peer will immediately restrict the broadcast transactions it announces (in inv packets) to transactions matching the filter, where the matching algorithm is specified below. The flags control the update behaviour of the matching algorithm.<br />
<br />
The <code>filteradd</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || data || uint8_t[] || The data element to add to the current filter.<br />
|}<br />
<br />
The data field must be smaller than or equal to 520 bytes in size (the maximum size of any potentially matched object).<br />
<br />
The given data element will be added to the Bloom filter. A filter must have been previously provided using <code>filterload</code>. This command is useful if a new key or script is added to a clients wallet whilst it has connections to the network open, it avoids the need to re-calculate and send an entirely new filter to every peer (though doing so is usually advisable to maintain anonymity).<br />
<br />
The <code>filterclear</code> command has no arguments at all.<br />
<br />
After a filter has been set, nodes don't merely stop announcing non-matching transactions, they can also serve filtered blocks. A filtered block is defined by the <code>merkleblock</code> message and is defined like this:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information, based upon the software version creating this block (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Limited to 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 4 || total_transactions || uint32_t || Number of transactions in the block (including unmatched ones)<br />
|-<br />
| ? || hashes || uint256[] || hashes in depth-first order (including standard varint size prefix)<br />
|-<br />
| ? || flags || byte[] || flag bits, packed per 8 in a byte, least significant bit first (including standard varint size prefix)<br />
|}<br />
<br />
=== alert ===<br />
<br />
An '''alert''' is sent between nodes to send a general notification message throughout the network. If the alert can be confirmed with the signature as having come from the core development group of the Bitcoin software, the message is suggested to be displayed for end-users. Attempts to perform transactions, particularly automated transactions through the client, are suggested to be halted. The text in the Message string should be relayed to log files and any user interfaces.<br />
<br />
Alert format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || payload || uchar[] || Serialized alert payload<br />
|-<br />
| ? || signature || uchar[] || An ECDSA signature of the message<br />
|}<br />
<br />
The developers of Satoshi's client use this public key for signing alerts:<br />
04fc9702847840aaf195de8442ebecedf5b095cdbb9bc716bda9110971b28a49e0ead8564ff0db22209e0374782c093bb899692d524e9d6a6956e7c5ecbcd68284<br />
(hash) 1AGRxqDa5WjUKBwHB9XYEjmkv1ucoUUy1s<br />
<br />
The payload is serialized into a uchar[] to ensure that versions using incompatible alert formats can still relay alerts among one another. The current alert payload format is:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || Version || int32_t || Alert format version<br />
|-<br />
| 8 || RelayUntil || int64_t || The timestamp beyond which nodes should stop relaying this alert<br />
|-<br />
| 8 || Expiration || int64_t || The timestamp beyond which this alert is no longer in effect and should be ignored<br />
|-<br />
| 4 || ID || int32_t || A unique ID number for this alert<br />
|-<br />
| 4 || Cancel || int32_t || All alerts with an ID number less than or equal to this number should be cancelled: deleted and not accepted in the future<br />
|-<br />
| ? || setCancel || set<int32_t> || All alert IDs contained in this set should be cancelled as above<br />
|-<br />
| 4 || MinVer || int32_t || This alert only applies to versions greater than or equal to this version. Other versions should still relay it.<br />
|-<br />
| 4 || MaxVer || int32_t || This alert only applies to versions less than or equal to this version. Other versions should still relay it.<br />
|-<br />
| ? || setSubVer || set<string> || If this set contains any elements, then only nodes that have their subVer contained in this set are affected by the alert. Other versions should still relay it.<br />
|-<br />
| 4 || Priority || int32_t || Relative priority compared to other alerts<br />
|-<br />
| ? || Comment || string || A comment on the alert that is not displayed<br />
|-<br />
| ? || StatusBar || string || The alert message that is displayed to the user<br />
|-<br />
| ? || Reserved || string || Reserved<br />
|}<br />
<br />
Note: '''set<''type''>''' in the table above is a [[#Variable length integer | variable length integer]] followed by the number of fields of the given ''type'' (either int32_t or [[#Variable length string | variable length string]])<br />
<br />
Sample alert (no message header):<br />
73010000003766404f00000000b305434f00000000f2030000f1030000001027000048ee0000<br />
0064000000004653656520626974636f696e2e6f72672f666562323020696620796f75206861<br />
76652074726f75626c6520636f6e6e656374696e672061667465722032302046656272756172<br />
79004730450221008389df45f0703f39ec8c1cc42c13810ffcae14995bb648340219e353b63b<br />
53eb022009ec65e1c1aaeec1fd334c6b684bde2b3f573060d5b70c3a46723326e4e8a4f1<br />
<br />
Version: 1<br />
RelayUntil: 1329620535<br />
Expiration: 1329792435<br />
ID: 1010<br />
Cancel: 1009<br />
setCancel: <empty><br />
MinVer: 10000<br />
MaxVer: 61000<br />
setSubVer: <empty><br />
Priority: 100<br />
Comment: <empty><br />
StatusBar: "See bitcoin.org/feb20 if you have trouble connecting after 20 February"<br />
Reserved: <empty><br />
<br />
=== sendheaders ===<br />
<br />
Request for Direct headers announcement. <br />
<br />
Upon receipt of this message, the node is be permitted, but not required, to announce new blocks by '''headers''' command (instead of '''inv''' command).<br />
<br />
This message is supported by the protocol version >= 70012 or Bitcoin Core version >= 0.12.0.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0130.mediawiki BIP 130] for more information.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
<br />
=== feefilter ===<br />
<br />
The payload is always 8 bytes long and it encodes 64 bit integer value (LSB / little endian) of '''feerate'''.<br />
The value represents a minimal fee and is expressed in satoshis per 1000 bytes.<br />
<br />
Upon receipt of a "feefilter" message, the node will be permitted, but not required, to filter transaction invs for transactions that fall below the feerate provided in the feefilter message interpreted as satoshis per kilobyte.<br />
<br />
The fee filter is additive with a bloom filter for transactions so if an SPV client were to load a bloom filter and send a feefilter message, transactions would only be relayed if they passed both filters.<br />
<br />
Inv's generated from a mempool message are also subject to a fee filter if it exists.<br />
<br />
Feature discovery is enabled by checking protocol version >= 70013<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0133.mediawiki BIP 133] for more information.<br />
<br />
=== sendcmpct ===<br />
<br />
# The sendcmpct message is defined as a message containing a 1-byte integer followed by a 8-byte integer where pchCommand == "sendcmpct".<br />
# The first integer SHALL be interpreted as a boolean (and MUST have a value of either 1 or 0)<br />
# The second integer SHALL be interpreted as a little-endian version number. Nodes sending a sendcmpct message MUST currently set this value to 1.<br />
# Upon receipt of a "sendcmpct" message with the first and second integers set to 1, the node SHOULD announce new blocks by sending a cmpctblock message.<br />
# Upon receipt of a "sendcmpct" message with the first integer set to 0, the node SHOULD NOT announce new blocks by sending a cmpctblock message, but SHOULD announce new blocks by sending invs or headers, as defined by BIP130.<br />
# Upon receipt of a "sendcmpct" message with the second integer set to something other than 1, nodes MUST treat the peer as if they had not received the message (as it indicates the peer will provide an unexpected encoding in <br />
# cmpctblock, and/or other, messages). This allows future versions to send duplicate sendcmpct messages with different versions as a part of a version handshake for future versions.<br />
# Nodes SHOULD check for a protocol version of >= 70014 before sending sendcmpct messages.<br />
# Nodes MUST NOT send a request for a MSG_CMPCT_BLOCK object to a peer before having received a sendcmpct message from that peer.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== cmpctblock ===<br />
<br />
# The cmpctblock message is defined as as a message containing a serialized HeaderAndShortIDs message and pchCommand == "cmpctblock".<br />
# Upon receipt of a cmpctblock message after sending a sendcmpct message, nodes SHOULD calculate the short transaction ID for each unconfirmed transaction they have available (ie in their mempool) and compare each to each short transaction ID in the cmpctblock message.<br />
# After finding already-available transactions, nodes which do not have all transactions available to reconstruct the full block SHOULD request the missing transactions using a getblocktxn message.<br />
# A node MUST NOT send a cmpctblock message unless they are able to respond to a getblocktxn message which requests every transaction in the block.<br />
# A node MUST NOT send a cmpctblock message without having validated that the header properly commits to each transaction in the block, and properly builds on top of the existing chain with a valid proof-of-work. A node MAY send a cmpctblock before validating that each transaction in the block validly spends existing UTXO set entries.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== getblocktxn ===<br />
<br />
# The getblocktxn message is defined as as a message containing a serialized BlockTransactionsRequest message and pchCommand == "getblocktxn".<br />
# Upon receipt of a properly-formatted getblocktxnmessage, nodes which recently provided the sender of such a message a cmpctblock for the block hash identified in this message MUST respond with an appropriate blocktxn message. Such a blocktxn message MUST contain exactly and only each transaction which is present in the appropriate block at the index specified in the getblocktxn indexes list, in the order requested.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== blocktxn ===<br />
<br />
# The blocktxn message is defined as as a message containing a serialized BlockTransactions message and pchCommand == "blocktxn".<br />
# Upon receipt of a properly-formatted requested blocktxn message, nodes SHOULD attempt to reconstruct the full block by:<br />
# Taking the prefilledtxn transactions from the original cmpctblock and placing them in the marked positions.<br />
# For each short transaction ID from the original cmpctblock, in order, find the corresponding transaction either from the blocktxn message or from other sources and place it in the first available position in the block.<br />
# Once the block has been reconstructed, it shall be processed as normal, keeping in mind that short transaction IDs are expected to occasionally collide, and that nodes MUST NOT be penalized for such collisions, wherever they # appear.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
== Scripting ==<br />
<br />
See [[script]].<br />
<br />
==See Also==<br />
<br />
* [[Network]]<br />
* [[Protocol rules]]<br />
* [[Hardfork Wishlist]]<br />
* [https://bitcoin.org/en/developer-documentation Developer Documentation on bitcoin.org]<br />
* Bitcoin dissectors for Wireshark: https://github.com/lbotsch/wireshark-bitcoin https://github.com/op-sig/bitcoin-wireshark-dissector<br />
<br />
==References==<br />
<references /><br />
<br />
[[zh-cn:协议说明]]<br />
[[Category:Technical]]<br />
[[Category:Developer]]<br />
<br />
{{Bitcoin Core documentation}}</div>Tonikthttps://en.bitcoin.it/w/index.php?title=Protocol_documentation&diff=61488Protocol documentation2016-08-25T12:36:57Z<p>Tonikt: /* BlockTransactionsRequest */</p>
<hr />
<div>This page ''describes'' the behavior of the [[Original Bitcoin client|reference client]]. The Bitcoin protocol is specified by the behavior of the reference client, not by this page. In particular, while this page is quite complete in describing the network protocol, it does not attempt to list all of the rules for block or transaction validity.<br />
<br />
Type names used in this documentation are from the C99 standard.<br />
<br />
For protocol used in mining, see [[getblocktemplate]].<br />
<br />
==Common standards==<br />
<br />
=== Hashes ===<br />
<br />
Usually, when a hash is computed within bitcoin, it is computed twice. Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-256] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when a shorter hash is desirable (for example when creating a bitcoin address).<br />
<br />
Example of double-SHA-256 encoding of string "hello":<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round of sha-256)<br />
9595c9df90075148eb06860365df33584b75bff782a510c6cd4883a419833d50 (second round of sha-256)<br />
<br />
For bitcoin addresses (RIPEMD-160) this would give:<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round is sha-256)<br />
b6a9c8c230722b7c748331a8b450f05566dc7d0f (with ripemd-160)<br />
<br />
=== Merkle Trees ===<br />
<br />
Merkle trees are binary trees of hashes. Merkle trees in bitcoin use a '''double''' SHA-256, the SHA-256 hash of the SHA-256 hash of something.<br />
<br />
If, when forming a row in the tree (other than the root of the tree), it would have an odd number of elements, the final double-hash is duplicated to ensure that the row has an even number of hashes.<br />
<br />
First form the bottom row of the tree with the ordered double-SHA-256 hashes of the byte streams of the transactions in the block.<br />
<br />
Then the row above it consists of half that number of hashes. Each entry is the double-SHA-256 of the 64-byte concatenation of the corresponding two hashes below it in the tree.<br />
<br />
This procedure repeats recursively until we reach a row consisting of just a single double-hash. This is the '''Merkle root''' of the tree.<br />
<br />
For example, imagine a block with three transactions ''a'', ''b'' and ''c''. The Merkle tree is: <br />
<br />
d1 = dhash(a)<br />
d2 = dhash(b)<br />
d3 = dhash(c)<br />
d4 = dhash(c) # a, b, c are 3. that's an odd number, so we take the c twice<br />
<br />
d5 = dhash(d1 concat d2)<br />
d6 = dhash(d3 concat d4)<br />
<br />
d7 = dhash(d5 concat d6)<br />
<br />
where<br />
<br />
dhash(a) = sha256(sha256(a))<br />
<br />
''d7'' is the Merkle root of the 3 transactions in this block.<br />
<br />
Note: Hashes in Merkle Tree displayed in the [[Block Explorer]] are of little-endian notation. For some implementations and [http://www.fileformat.info/tool/hash.htm calculations], the bits need to be reversed before they are hashed, and again after the hashing operation.<br />
<br />
=== Signatures ===<br />
<br />
Bitcoin uses [http://en.wikipedia.org/wiki/Elliptic_curve_cryptography Elliptic Curve] [http://en.wikipedia.org/wiki/Digital_Signature_Algorithm Digital Signature Algorithm] ([http://en.wikipedia.org/wiki/Elliptic_Curve_DSA ECDSA]) to sign transactions. <br />
<br />
For [[ECDSA]] the secp256k1 curve from http://www.secg.org/collateral/sec2_final.pdf is used.<br />
<br />
Public keys (in scripts) are given as 04 <x> <y> where ''x'' and ''y'' are 32 byte big-endian integers representing the coordinates of a point on the curve or in compressed form given as <sign> <x> where <sign> is 0x02 if ''y'' is even and 0x03 if ''y'' is odd.<br />
<br />
Signatures use [http://en.wikipedia.org/wiki/Distinguished_Encoding_Rules DER encoding] to pack the ''r'' and ''s'' components into a single byte stream (this is also what OpenSSL produces by default).<br />
<br />
=== Transaction Verification ===<br />
Transactions are cryptographically signed records that reassign ownership of Bitcoins to new addresses. Transactions have ''inputs'' - records which reference the funds from other previous transactions - and ''outputs'' - records which determine the new owner of the transferred Bitcoins, and which will be referenced as inputs in future transactions as those funds are respent.<br />
<br />
Each ''input'' must have a cryptographic digital signature that unlocks the funds from the prior transaction. Only the person possessing the appropriate [[private key]] is able to create a satisfactory signature; this in effect ensures that funds can only be spent by their owners.<br />
<br />
Each ''output'' determines which Bitcoin address (or other criteria, see [[Script]]) is the recipient of the funds.<br />
<br />
In a transaction, the sum of all inputs must be equal to or greater than the sum of all outputs. If the inputs exceed the outputs, the difference is considered a [[transaction fee]], and is redeemable by whoever first includes the transaction into the block chain.<br />
<br />
A special kind of transaction, called a [[coinbase transaction]], has no inputs. It is created by [[miners]], and there is one coinbase transaction per block. Because each block comes with a reward of newly created Bitcoins (e.g. 50 BTC for the first 210,000 blocks), the first transaction of a block is, with few exceptions, the transaction that grants those coins to their recipient (the miner). In addition to the newly created Bitcoins, the coinbase transaction is also used for assigning the recipient of any transaction fees that were paid within the other transactions being included in the same block. The coinbase transaction can assign the entire reward to a single Bitcoin address, or split it in portions among multiple addresses, just like any other transaction. Coinbase transactions always contain outputs totalling the sum of the block reward plus all transaction fees collected from the other transactions in the same block.<br />
<br />
The [[coinbase transaction]] in block zero cannot be spent. This is due to a quirk of the reference client implementation that would open the potential for a block chain fork if some nodes accepted the spend and others did not<ref>[http://bitcointalk.org/index.php?topic=119645.msg1288552#msg1288552 Block 0 Network Fork]</ref>.<br />
<br />
Most Bitcoin outputs encumber the newly transferred coins with a single ECDSA private key. The actual record saved with inputs and outputs isn't necessarily a key, but a ''script''. Bitcoin uses an interpreted scripting system to determine whether an output's criteria have been satisfied, with which more complex operations are possible, such as outputs that require two ECDSA signatures, or two-of-three-signature schemes. An output that references a single Bitcoin address is a ''typical'' output; an output actually contains this information in the form of a script that requires a single ECDSA signature (see [[OP_CHECKSIG]]). The output script specifies what must be provided to unlock the funds later, and when the time comes in the future to spend the transaction in another input, that input must provide all of the thing(s) that satisfy the requirements defined by the original output script.<br />
<br />
=== Addresses ===<br />
<br />
A bitcoin address is in fact the hash of a ECDSA public key, computed this way:<br />
<br />
Version = 1 byte of 0 (zero); on the test network, this is 1 byte of 111<br />
Key hash = Version concatenated with RIPEMD-160(SHA-256(public key))<br />
Checksum = 1st 4 bytes of SHA-256(SHA-256(Key hash))<br />
Bitcoin Address = Base58Encode(Key hash concatenated with Checksum)<br />
<br />
The Base58 encoding used is home made, and has some differences. Especially, leading zeroes are kept as single zeroes when conversion happens.<br />
<br />
== Common structures ==<br />
<br />
Almost all integers are encoded in little endian. Only IP or port number are encoded big endian.<br />
<br />
=== Message structure ===<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown<br />
|-<br />
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| 4 || length || uint32_t || Length of payload in number of bytes<br />
|-<br />
| 4 || checksum || uint32_t || First 4 bytes of sha256(sha256(payload))<br />
|-<br />
| ? || payload || uchar[] || The actual data<br />
|}<br />
<br />
<br />
Known magic values:<br />
<br />
{|class="wikitable"<br />
! Network !! Magic value !! Sent over wire as<br />
|-<br />
| main || 0xD9B4BEF9 || F9 BE B4 D9<br />
|-<br />
| testnet || 0xDAB5BFFA || FA BF B5 DA<br />
|-<br />
| testnet3 || 0x0709110B || 0B 11 09 07<br />
|-<br />
| namecoin || 0xFEB4BEF9 || F9 BE B4 FE<br />
|}<br />
<br />
=== Variable length integer ===<br />
<br />
Integer can be encoded depending on the represented value to save space.<br />
Variable length integers always precede an array/vector of a type of data that may vary in length.<br />
Longer numbers are encoded in little endian.<br />
<br />
{|class="wikitable"<br />
! Value !! Storage length !! Format<br />
|-<br />
| < 0xFD || 1 || uint8_t<br />
|-<br />
| <= 0xFFFF || 3 || 0xFD followed by the length as uint16_t<br />
|-<br />
| <= 0xFFFF FFFF || 5 || 0xFE followed by the length as uint32_t<br />
|-<br />
| - || 9 || 0xFF followed by the length as uint64_t<br />
|}<br />
<br />
If you're reading the Satoshi client code (BitcoinQT) it refers to this encoding as a "CompactSize". Modern BitcoinQT also has the CVarInt class which implements an even more compact integer for the purpose of local storage (which is incompatible with "CompactSize" described here). CVarInt is not a part of the protocol.<br />
<br />
=== Variable length string ===<br />
<br />
Variable length string can be stored using a variable length integer followed by the string itself.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the string<br />
|-<br />
| ? || string || char[] || The string itself (can be empty)<br />
|}<br />
<br />
=== Network address ===<br />
<br />
When a network address is needed somewhere, this structure is used. Network addresses are not prefixed with a timestamp in the version message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || time || uint32 || the Time (version >= 31402). '''Not present in version message.'''<br />
|-<br />
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]<br />
|-<br />
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The original client only supported IPv4 and only read the last 4 bytes to get the IPv4 address. However, the IPv4 address is written into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]<br />
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).<br />
|-<br />
| 2 || port || uint16_t || port number, network byte order<br />
|}<br />
<br />
Hexdump example of Network address structure<br />
<br />
<pre><br />
0000 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0010 00 00 FF FF 0A 00 00 01 20 8D ........ .<br />
<br />
Network address:<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK: see services listed under version command)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv6: ::ffff:a00:1 or IPv4: 10.0.0.1<br />
20 8D - Port 8333<br />
</pre><br />
<br />
=== Inventory Vectors ===<br />
<br />
Inventory vectors are used for notifying other nodes about objects they have or data which is being requested.<br />
<br />
Inventory vectors consist of the following data format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || type || uint32_t || Identifies the object type linked to this inventory<br />
|-<br />
| 32 || hash || char[32] || Hash of the object<br />
|}<br />
<br />
<br />
The object type is currently defined as one of the following possibilities:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0 || ERROR || Any data of with this number may be ignored<br />
|-<br />
| 1 || MSG_TX || Hash is related to a transaction<br />
|-<br />
| 2 || MSG_BLOCK || Hash is related to a data block<br />
|-<br />
| 3 || MSG_FILTERED_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a merkleblock message rather than a block message; this only works if a bloom filter has been set.<br />
|-<br />
| 4 || MSG_CMPCT_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a cmpctblock message. See BIP 152 for more info.<br />
|}<br />
<br />
Other Data Type values are considered reserved for future implementations.<br />
<br />
=== Block Headers ===<br />
<br />
Block headers are sent in a headers packet in response to a getheaders message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Will overflow in 2106<ref>https://en.wikipedia.org/wiki/Unix_time#Notable_events_in_Unix_time</ref>)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 1 || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries, this value is always 0<br />
|}<br />
<br />
cf. [[Block hashing algorithm]]<br />
<br />
=== PrefilledTransaction ===<br />
<br />
A PrefilledTransaction structure is used in HeaderAndShortIDs to provide a list of a few transactions explicitly.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| index || CompactSize || 1, 3 bytes || Compact Size, differentially encoded since the last PrefilledTransaction in a list || The index into the block at which this transaction is<br />
|-<br />
| tx || Transaction || variable || As encoded in "tx" messages || The transaction which is in the block at index index.<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== HeaderAndShortIDs ===<br />
<br />
A HeaderAndShortIDs structure is used to relay a block header, the short transactions IDs used for matching already-available transactions, and a select few transactions which we expect a peer may be missing.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| header || Block header || 80 bytes || First 80 bytes of the block as defined by the encoding used by "block" messages || The header of the block being provided<br />
|-<br />
| nonce || uint64_t || 8 bytes || Little Endian || A nonce for use in short transaction ID calculations<br />
|-<br />
| shortids_length || CompactSize || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of short transaction IDs in shortids (ie block tx count - prefilledtxn_length)<br />
|-<br />
| shortids || List of 6-byte integers || 6*shortids_length bytes || Little Endian || The short transaction IDs calculated from the transactions which were not provided explicitly in prefilledtxn<br />
|-<br />
| prefilledtxn_length || CompactSize || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of prefilled transactions in prefilledtxn (ie block tx count - shortids_length)<br />
|-<br />
| prefilledtxn || List of PrefilledTransactions || variable size*prefilledtxn_length || As defined by PrefilledTransaction definition, above || Used to provide the coinbase transaction and a select few which we expect a peer may be missing<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== BlockTransactionsRequest ===<br />
<br />
A BlockTransactionsRequest structure is used to list transaction indexes in a block being requested.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| blockhash || Binary blob || 32 bytes || The output from a double-SHA256 of the block header, as used elsewhere || The blockhash of the block which the transactions being requested are in<br />
|-<br />
| indexes_length || CompactSize || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of transactions being requested<br />
|-<br />
| indexes || List of CompactSizes || 1 or 3 bytes*indexes_length || Differentially encoded || The indexes of the transactions being requested in the block<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== BlockTransactions ===<br />
<br />
A BlockTransactions structure is used to provide some of the transactions in a block, as requested.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== Short transaction IDs ===<br />
<br />
Short transaction IDs are used to represent a transaction without sending a full 256-bit hash. They are calculated by:<br />
<br />
# single-SHA256 hashing the block header with the nonce appended (in little-endian)<br />
# Running SipHash-2-4 with the input being the transaction ID and the keys (k0/k1) set to the first two little-endian 64-bit integers from the above hash, respectively.<br />
# Dropping the 2 most significant bytes from the SipHash output to make it 6 bytes.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
== Message types ==<br />
<br />
=== version ===<br />
<br />
When a node creates an outgoing connection, it will immediately [[Version Handshake|advertise]] its version. The remote node will respond with its version. No further communication is possible until both peers have exchanged their version.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Identifies protocol version being used by the node<br />
|-<br />
| 8 || services || uint64_t || bitfield of features to be enabled for this connection<br />
|-<br />
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds<br />
|-<br />
| 26 || addr_recv || [[#Network address|net_addr]] || The network address of the node receiving this message<br />
|-<br />
|colspan="4"| Fields below require version ≥ 106<br />
|-<br />
| 26 || addr_from || [[#Network address|net_addr]] || The network address of the node emitting this message<br />
|-<br />
| 8 || nonce || uint64_t || Node random nonce, randomly generated every time a version packet is sent. This nonce is used to detect connections to self.<br />
|-<br />
| ? || user_agent || [[#Variable length string|var_str]] || [https://github.com/bitcoin/bips/blob/master/bip-0014.mediawiki User Agent] (0x00 if string is 0 bytes long)<br />
|-<br />
| 4 || start_height || int32_t || The last block received by the emitting node<br />
|-<br />
|colspan="4"| Fields below require version ≥ 70001<br />
|-<br />
| 1 || relay || bool || Whether the remote peer should announce relayed transactions or not, see [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037]<br />
|}<br />
<br />
A "verack" packet shall be sent if the version packet was accepted.<br />
<br />
The following services are currently assigned:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 1 || NODE_NETWORK || This node can be asked for full blocks instead of just headers.<br />
|}<br />
<br />
Hexdump example of version message (OBSOLETE EXAMPLE: This example lacks a checksum and user-agent):<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....<br />
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........<br />
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............<br />
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................<br />
0040 20 8D 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,<br />
0060 3A B4 57 13 00 55 81 01 00 :.W..U...<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
55 00 00 00 - Payload is 85 bytes long<br />
- No checksum in version message until 20 February 2012. See https://bitcointalk.org/index.php?topic=55852.0<br />
Version message:<br />
9C 7C 00 00 - 31900 (version 0.3.19)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
E6 15 10 4D 00 00 00 00 - Mon Dec 20 21:50:14 EST 2010<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 20 8D - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D - Sender address info - see Network Address<br />
DD 9D 20 2C 3A B4 57 13 - Node random unique ID<br />
00 - "" sub-version string (string is 0 bytes long)<br />
55 81 01 00 - Last block sending node has is block #98645<br />
</pre><br />
<br />
And here's a modern (60002) protocol version client advertising itself to a local peer...<br />
<br />
Newer protocol includes the checksum now, this is from a mainline (satoshi) client during <br />
an outgoing connection to another local client, notice that it does not fill out the <br />
address information at all when the source or destination is "unroutable".<br />
<br />
<pre><br />
<br />
0000 f9 be b4 d9 76 65 72 73 69 6f 6e 00 00 00 00 00 ....version.....<br />
0010 64 00 00 00 35 8d 49 32 62 ea 00 00 01 00 00 00 d...5.I2b.......<br />
0020 00 00 00 00 11 b2 d0 50 00 00 00 00 01 00 00 00 .......P........<br />
0030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ff ff ................<br />
0040 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 00 00 00 00 ff ff 00 00 00 00 00 00 ................<br />
0060 3b 2e b3 5d 8c e6 17 65 0f 2f 53 61 74 6f 73 68 ;..]...e./Satosh<br />
0070 69 3a 30 2e 37 2e 32 2f c0 3e 03 00 i:0.7.2/.>..<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
64 00 00 00 - Payload is 100 bytes long<br />
3B 64 8D 5A - payload checksum<br />
<br />
Version message:<br />
62 EA 00 00 - 60002 (protocol version 60002)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
11 B2 D0 50 00 00 00 00 - Tue Dec 18 10:12:33 PST 2012<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Sender address info - see Network Address<br />
3B 2E B3 5D 8C E6 17 65 - Node ID<br />
0F 2F 53 61 74 6F 73 68 69 3A 30 2E 37 2E 32 2F - "/Satoshi:0.7.2/" sub-version string (string is 15 bytes long)<br />
C0 3E 03 00 - Last block sending node has is block #212672<br />
</pre><br />
<br />
=== verack ===<br />
<br />
The ''verack'' message is sent in reply to ''[[#version|version]]''. This message consists of only a [[#Message structure|message header]] with the command string "verack".<br />
<br />
Hexdump of the verack message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......<br />
0010 00 00 00 00 5D F6 E0 E2 ........<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 61 63 6B 00 00 00 00 00 00 - "verack" command<br />
00 00 00 00 - Payload is 0 bytes long<br />
5D F6 E0 E2 - Checksum<br />
</pre><br />
<br />
=== addr ===<br />
<br />
Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours<br />
<br />
Payload:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of address entries (max: 1000)<br />
|-<br />
| 30x? || addr_list || (uint32_t + [[#Network address|net_addr]])[] || Address of other nodes on the network. version < 209 will only read the first one. The uint32_t is a timestamp (see note below).<br />
|}<br />
<br />
'''Note''': Starting version 31402, addresses are prefixed with a timestamp. If no timestamp is present, the addresses should not be relayed to other peers, unless it is indeed confirmed they are up.<br />
<br />
Hexdump example of ''addr'' message:<br />
<pre><br />
0000 F9 BE B4 D9 61 64 64 72 00 00 00 00 00 00 00 00 ....addr........<br />
0010 1F 00 00 00 ED 52 39 9B 01 E2 15 10 4D 01 00 00 .....R9.....M...<br />
0020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF ................<br />
0030 FF 0A 00 00 01 20 8D ..... .<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
61 64 64 72 00 00 00 00 00 00 00 00 - "addr"<br />
1F 00 00 00 - payload is 31 bytes long<br />
ED 52 39 9B - checksum of payload<br />
<br />
Payload:<br />
01 - 1 address in this message<br />
<br />
Address:<br />
E2 15 10 4D - Mon Dec 20 21:50:10 EST 2010 (only when version is >= 31402)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK service - see version message)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv4: 10.0.0.1, IPv6: ::ffff:10.0.0.1 (IPv4-mapped IPv6 address)<br />
20 8D - port 8333<br />
</pre><br />
<br />
=== inv ===<br />
<br />
Allows a node to advertise its knowledge of one or more objects. It can be received unsolicited, or in reply to ''getblocks''.<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getdata ===<br />
<br />
getdata is used in response to inv, to retrieve the content of a specific object, and is usually sent after receiving an ''inv'' packet, after filtering known elements. It can be used to retrieve transactions, but only if they are in the memory pool or relay set - arbitrary access to transactions in the chain is not allowed to avoid having clients start to depend on nodes having full transaction indexes (which modern nodes do not).<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== notfound ===<br />
<br />
notfound is a response to a getdata, sent if any requested data items could not be relayed, for example, because the requested transaction was not in the memory pool or relay set.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getblocks ===<br />
<br />
Return an ''inv'' packet containing the list of blocks starting right after the last known hash in the block locator object, up to hash_stop or 500 blocks, whichever comes first. <br />
<br />
The locator hashes are processed by a node in the order as they appear in the message. If a block hash is found in the node's main chain, the list of its children is returned back via the ''inv'' message and the remaining locators are ignored, no matter if the requested limit was reached, or not.<br />
<br />
To receive the next blocks hashes, one needs to issue getblocks again with a new block locator object. Keep in mind that some clients may provide blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block; set to zero to get as many blocks as possible (500)<br />
|}<br />
<br />
To create the block locator hashes, keep pushing hashes until you go back to the genesis block. After pushing 10 hashes back, the step backwards doubles every loop:<br />
<br />
<pre><br />
// From libbitcoin which is under AGPL<br />
std::vector<size_t> block_locator_indexes(size_t top_height)<br />
{<br />
std::vector<size_t> indexes;<br />
<br />
// Modify the step in the iteration.<br />
int64_t step = 1;<br />
<br />
// Start at the top of the chain and work backwards.<br />
for (auto index = (int64_t)top_height; index > 0; index -= step)<br />
{<br />
// Push top 10 indexes first, then back off exponentially.<br />
if (indexes.size() >= 10)<br />
step *= 2;<br />
<br />
indexes.push_back((size_t)index);<br />
}<br />
<br />
// Push the genesis block index.<br />
indexes.push_back(0);<br />
return indexes;<br />
}<br />
</pre><br />
<br />
Note that it is allowed to send in fewer known hashes down to a minimum of just one hash. However, the purpose of the block locator object is to detect a wrong branch in the caller's main chain. If the peer detects that you are off the main chain, it will send in block hashes which are earlier than your last known block. So if you just send in your last known hash and it is off the main chain, the peer starts over at block #1.<br />
<br />
=== getheaders ===<br />
<br />
Return a ''headers'' packet containing the headers of blocks starting right after the last known hash in the block locator object, up to hash_stop or 2000 blocks, whichever comes first. To receive the next block headers, one needs to issue getheaders again with a new block locator object. The ''getheaders'' command is used by thin clients to quickly download the block chain where the contents of the transactions would be irrelevant (because they are not ours). Keep in mind that some clients may provide headers of blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block header; set to zero to get as many blocks as possible (2000)<br />
|}<br />
<br />
For the block locator object in this packet, the same rules apply as for the [[Protocol_documentation#getblocks|getblocks]] packet.<br />
<br />
=== tx ===<br />
<br />
''tx'' describes a bitcoin transaction, in reply to ''[[#getdata|getdata]]''<br />
<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Transaction data format version (note, this is signed)<br />
|-<br />
| 1+ || tx_in count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction inputs<br />
|-<br />
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins<br />
|-<br />
| 1+ || tx_out count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction outputs<br />
|-<br />
| 9+ || tx_out || tx_out[] || A list of 1 or more transaction outputs or destinations for coins<br />
|-<br />
| 4 || lock_time || uint32_t || The block number or timestamp at which this transaction is locked:<br />
{|class="wikitable"<br />
! Value !! Description<br />
|-<br />
| 0 || Not locked<br />
|-<br />
| < 500000000 || Block number at which this transaction is locked<br />
|-<br />
| >= 500000000 || UNIX timestamp at which this transaction is locked<br />
|}<br />
If all TxIn inputs have final (0xffffffff) sequence numbers then lock_time is irrelevant. Otherwise, the transaction may not be added to a block until after lock_time (see [[NLockTime]]).<br />
<br />
|}<br />
<br />
TxIn consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 36 || previous_output || outpoint || The previous output transaction reference, as an OutPoint structure<br />
|-<br />
| 1+ || script length || [[Protocol_documentation#Variable_length_integer|var_int]] || The length of the signature script<br />
|-<br />
| ? || signature script || uchar[] || Computational Script for confirming transaction authorization<br />
|-<br />
| 4 || [http://bitcoin.stackexchange.com/q/2025/323 sequence] || uint32_t || Transaction version as defined by the sender. Intended for "replacement" of transactions when information is updated before inclusion into a block.<br />
|}<br />
<br />
The OutPoint structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 32 || hash || char[32] || The hash of the referenced transaction.<br />
|-<br />
| 4 || index || uint32_t || The index of the specific output in the transaction. The first output is 0, etc.<br />
|}<br />
<br />
The Script structure consists of a series of pieces of information and operations related to the value of the transaction.<br />
<br />
(Structure to be expanded in the future… see script.h and script.cpp and [[Script]] for more information)<br />
<br />
The TxOut structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || value || int64_t || Transaction Value<br />
|-<br />
| 1+ || pk_script length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the pk_script<br />
|-<br />
| ? || pk_script || uchar[] || Usually contains the public key as a Bitcoin script setting up conditions to claim this output.<br />
|}<br />
<br />
Example ''tx'' message:<br />
<pre><br />
000000 F9 BE B4 D9 74 78 00 00 00 00 00 00 00 00 00 00 ....tx..........<br />
000010 02 01 00 00 E2 93 CD BE 01 00 00 00 01 6D BD DB .............m..<br />
000020 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D 12 66 E9 .[...Q........f.<br />
000030 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29 00 00 00 .;P......j.6)...<br />
000040 00 8B 48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 ..H0E.!..X..r...<br />
000050 C7 36 7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A .6zz%;..R#...h.:<br />
000060 59 23 3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 Y#?E.W... Y.....<br />
000070 0E 41 83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D .A.z.X.z...XN...<br />
000080 35 BD 96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF 5...6..;...A....<br />
000090 C9 7E F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 .~.6.m...@..!...<br />
0000A0 2A CD 2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC *.+..].}Y... ...<br />
0000B0 4E 02 53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F N.S..=7.o...Q...<br />
0000C0 14 04 2F 46 61 4A 4C 70 C0 F1 4B EF F5 FF FF FF ../FaJLp..K.....<br />
0000D0 FF 02 40 4B 4C 00 00 00 00 00 19 76 A9 14 1A A0 ..@KL......v....<br />
0000E0 CD 1C BE A6 E7 45 8A 7A BA D5 12 A9 D9 EA 1A FB .....E.z........<br />
0000F0 22 5E 88 AC 80 FA E9 C7 00 00 00 00 19 76 A9 14 "^...........v..<br />
000100 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E FD A0 B7 ..[.Cj.....H^...<br />
000110 8B 4E CC 52 88 AC 00 00 00 00 .N.R......<br />
<br />
<br />
Message header:<br />
F9 BE B4 D9 - main network magic bytes<br />
74 78 00 00 00 00 00 00 00 00 00 00 - "tx" command<br />
02 01 00 00 - payload is 258 bytes long<br />
E2 93 CD BE - checksum of payload<br />
<br />
Transaction:<br />
01 00 00 00 - version<br />
<br />
Inputs:<br />
01 - number of transaction inputs<br />
<br />
Input 1:<br />
6D BD DB 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D - previous output (outpoint)<br />
12 66 E9 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29<br />
00 00 00 00<br />
<br />
8B - script is 139 bytes long<br />
<br />
48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 C7 36 - signature script (scriptSig)<br />
7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A 59 23<br />
3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 0E 41<br />
83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D 35 BD<br />
96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF C9 7E<br />
F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 2A CD<br />
2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC 4E 02<br />
53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F 14 04<br />
2F 46 61 4A 4C 70 C0 F1 4B EF F5<br />
<br />
FF FF FF FF - sequence<br />
<br />
Outputs:<br />
02 - 2 Output Transactions<br />
<br />
Output 1:<br />
40 4B 4C 00 00 00 00 00 - 0.05 BTC (5000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 1A A0 CD 1C BE A6 E7 45 8A 7A BA D5 12 - pk_script<br />
A9 D9 EA 1A FB 22 5E 88 AC<br />
<br />
Output 2:<br />
80 FA E9 C7 00 00 00 00 - 33.54 BTC (3354000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E - pk_script<br />
FD A0 B7 8B 4E CC 52 88 AC<br />
<br />
Locktime:<br />
00 00 00 00 - lock time<br />
</pre><br />
<br />
=== block ===<br />
<br />
The '''block''' message is sent in response to a getdata message which requests transaction information from a block hash.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A Unix timestamp recording when this block was created (Currently limited to dates before the year 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated [[Difficulty|difficulty target]] being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| ? || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries<br />
|-<br />
| ? || txns || tx[] || Block transactions, in format of "tx" command<br />
|}<br />
<br />
The SHA256 hash that identifies each block (and which must have a run of 0 bits) is calculated from the first 6 fields of this structure (version, prev_block, merkle_root, timestamp, bits, nonce, and standard SHA256 padding, making two 64-byte chunks in all) and ''not'' from the complete block. To calculate the hash, only two chunks need to be processed by the SHA256 algorithm. Since the ''nonce'' field is in the second chunk, the first chunk stays constant during mining and therefore only the second chunk needs to be processed. However, a Bitcoin hash is the hash of the hash, so two SHA256 rounds are needed for each mining iteration.<br />
See [[Block hashing algorithm]] for details and an example.<br />
<br />
=== headers ===<br />
<br />
The ''headers'' packet returns block headers in response to a ''getheaders'' packet. <br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of block headers<br />
|-<br />
| 81x? || headers || [[Protocol_documentation#Block_Headers|block_header]][] || [[Protocol_documentation#Block_Headers|Block headers]]<br />
|}<br />
<br />
Note that the block headers in this packet include a transaction count (a var_int, so there can be more than 81 bytes per header) as opposed to the block headers that are hashed by miners.<br />
<br />
=== getaddr ===<br />
<br />
The getaddr message sends a request to a node asking for information about known active peers to help with finding potential nodes in the network. The response to receiving this message is to transmit one or more addr messages with one or more peers from a database of known active peers. The typical presumption is that a node is likely to be active if it has been sending a message within the last three hours.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
=== mempool ===<br />
<br />
The mempool message sends a request to a node asking for information about transactions it has verified but which have not yet confirmed. The response to receiving this message is an inv message containing the transaction hashes for all the transactions in the node's mempool.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
It is specified in [https://github.com/bitcoin/bips/blob/master/bip-0035.mediawiki BIP 35]. Since [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 37], if a [[Protocol_documentation#filterload.2C_filteradd.2C_filterclear.2C_merkleblock|bloom filter]] is loaded, only transactions matching the filter are replied.<br />
<br />
=== checkorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== submitorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== reply ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== ping ===<br />
<br />
The ''ping'' message is sent primarily to confirm that the TCP/IP connection is still valid. An error in transmission is presumed to be a closed connection and the address is removed as a current peer.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || random nonce<br />
|}<br />
<br />
=== pong ===<br />
<br />
The ''pong'' message is sent in response to a ''ping'' message. In modern protocol versions, a ''pong'' response is generated using a nonce included in the ping.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || nonce from ping<br />
|}<br />
<br />
<br />
=== reject===<br />
<br />
The ''reject'' message is sent when messages are rejected.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || message || var_str || type of message rejected<br />
|-<br />
| 1 || ccode || char || code relating to rejected message<br />
|-<br />
| 1+ || reason || var_str || text version of reason for rejection<br />
|-<br />
| 0+ || data || char || Optional extra data provided by some errors. Currently, all errors which provide this field fill it with the TXID or block header hash of the object being rejected, so the field is 32 bytes.<br />
|}<br />
<br />
CCodes<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0x01 || REJECT_MALFORMED|| <br />
|-<br />
| 0x10 || REJECT_INVALID ||<br />
|-<br />
| 0x11 || REJECT_OBSOLETE ||<br />
|-<br />
| 0x12 || REJECT_DUPLICATE ||<br />
|-<br />
| 0x40 || REJECT_NONSTANDARD ||<br />
|-<br />
| 0x41 || REJECT_DUST ||<br />
|-<br />
| 0x42 || REJECT_INSUFFICIENTFEE ||<br />
|-<br />
| 0x43 || REJECT_CHECKPOINT ||<br />
|}<br />
<br />
=== filterload, filteradd, filterclear, merkleblock ===<br />
<br />
These messages are related to Bloom filtering of connections and are defined in [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037].<br />
<br />
<br />
The <code>filterload</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || filter || uint8_t[] || The filter itself is simply a bit field of arbitrary byte-aligned size. The maximum size is 36,000 bytes.<br />
|-<br />
| 4 || nHashFuncs || uint32_t || The number of hash functions to use in this filter. The maximum value allowed in this field is 50.<br />
|-<br />
| 4 || nTweak || uint32_t || A random value to add to the seed value in the hash function used by the bloom filter.<br />
|-<br />
| 1 || nFlags || uint8_t || A set of flags that control how matched items are added to the filter.<br />
|}<br />
<br />
See below for a description of the Bloom filter algorithm and how to select nHashFuncs and filter size for a desired false positive rate.<br />
<br />
Upon receiving a <code>filterload</code> command, the remote peer will immediately restrict the broadcast transactions it announces (in inv packets) to transactions matching the filter, where the matching algorithm is specified below. The flags control the update behaviour of the matching algorithm.<br />
<br />
The <code>filteradd</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || data || uint8_t[] || The data element to add to the current filter.<br />
|}<br />
<br />
The data field must be smaller than or equal to 520 bytes in size (the maximum size of any potentially matched object).<br />
<br />
The given data element will be added to the Bloom filter. A filter must have been previously provided using <code>filterload</code>. This command is useful if a new key or script is added to a clients wallet whilst it has connections to the network open, it avoids the need to re-calculate and send an entirely new filter to every peer (though doing so is usually advisable to maintain anonymity).<br />
<br />
The <code>filterclear</code> command has no arguments at all.<br />
<br />
After a filter has been set, nodes don't merely stop announcing non-matching transactions, they can also serve filtered blocks. A filtered block is defined by the <code>merkleblock</code> message and is defined like this:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information, based upon the software version creating this block (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Limited to 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 4 || total_transactions || uint32_t || Number of transactions in the block (including unmatched ones)<br />
|-<br />
| ? || hashes || uint256[] || hashes in depth-first order (including standard varint size prefix)<br />
|-<br />
| ? || flags || byte[] || flag bits, packed per 8 in a byte, least significant bit first (including standard varint size prefix)<br />
|}<br />
<br />
=== alert ===<br />
<br />
An '''alert''' is sent between nodes to send a general notification message throughout the network. If the alert can be confirmed with the signature as having come from the core development group of the Bitcoin software, the message is suggested to be displayed for end-users. Attempts to perform transactions, particularly automated transactions through the client, are suggested to be halted. The text in the Message string should be relayed to log files and any user interfaces.<br />
<br />
Alert format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || payload || uchar[] || Serialized alert payload<br />
|-<br />
| ? || signature || uchar[] || An ECDSA signature of the message<br />
|}<br />
<br />
The developers of Satoshi's client use this public key for signing alerts:<br />
04fc9702847840aaf195de8442ebecedf5b095cdbb9bc716bda9110971b28a49e0ead8564ff0db22209e0374782c093bb899692d524e9d6a6956e7c5ecbcd68284<br />
(hash) 1AGRxqDa5WjUKBwHB9XYEjmkv1ucoUUy1s<br />
<br />
The payload is serialized into a uchar[] to ensure that versions using incompatible alert formats can still relay alerts among one another. The current alert payload format is:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || Version || int32_t || Alert format version<br />
|-<br />
| 8 || RelayUntil || int64_t || The timestamp beyond which nodes should stop relaying this alert<br />
|-<br />
| 8 || Expiration || int64_t || The timestamp beyond which this alert is no longer in effect and should be ignored<br />
|-<br />
| 4 || ID || int32_t || A unique ID number for this alert<br />
|-<br />
| 4 || Cancel || int32_t || All alerts with an ID number less than or equal to this number should be cancelled: deleted and not accepted in the future<br />
|-<br />
| ? || setCancel || set<int32_t> || All alert IDs contained in this set should be cancelled as above<br />
|-<br />
| 4 || MinVer || int32_t || This alert only applies to versions greater than or equal to this version. Other versions should still relay it.<br />
|-<br />
| 4 || MaxVer || int32_t || This alert only applies to versions less than or equal to this version. Other versions should still relay it.<br />
|-<br />
| ? || setSubVer || set<string> || If this set contains any elements, then only nodes that have their subVer contained in this set are affected by the alert. Other versions should still relay it.<br />
|-<br />
| 4 || Priority || int32_t || Relative priority compared to other alerts<br />
|-<br />
| ? || Comment || string || A comment on the alert that is not displayed<br />
|-<br />
| ? || StatusBar || string || The alert message that is displayed to the user<br />
|-<br />
| ? || Reserved || string || Reserved<br />
|}<br />
<br />
Note: '''set<''type''>''' in the table above is a [[#Variable length integer | variable length integer]] followed by the number of fields of the given ''type'' (either int32_t or [[#Variable length string | variable length string]])<br />
<br />
Sample alert (no message header):<br />
73010000003766404f00000000b305434f00000000f2030000f1030000001027000048ee0000<br />
0064000000004653656520626974636f696e2e6f72672f666562323020696620796f75206861<br />
76652074726f75626c6520636f6e6e656374696e672061667465722032302046656272756172<br />
79004730450221008389df45f0703f39ec8c1cc42c13810ffcae14995bb648340219e353b63b<br />
53eb022009ec65e1c1aaeec1fd334c6b684bde2b3f573060d5b70c3a46723326e4e8a4f1<br />
<br />
Version: 1<br />
RelayUntil: 1329620535<br />
Expiration: 1329792435<br />
ID: 1010<br />
Cancel: 1009<br />
setCancel: <empty><br />
MinVer: 10000<br />
MaxVer: 61000<br />
setSubVer: <empty><br />
Priority: 100<br />
Comment: <empty><br />
StatusBar: "See bitcoin.org/feb20 if you have trouble connecting after 20 February"<br />
Reserved: <empty><br />
<br />
=== sendheaders ===<br />
<br />
Request for Direct headers announcement. <br />
<br />
Upon receipt of this message, the node is be permitted, but not required, to announce new blocks by '''headers''' command (instead of '''inv''' command).<br />
<br />
This message is supported by the protocol version >= 70012 or Bitcoin Core version >= 0.12.0.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0130.mediawiki BIP 130] for more information.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
<br />
=== feefilter ===<br />
<br />
The payload is always 8 bytes long and it encodes 64 bit integer value (LSB / little endian) of '''feerate'''.<br />
The value represents a minimal fee and is expressed in satoshis per 1000 bytes.<br />
<br />
Upon receipt of a "feefilter" message, the node will be permitted, but not required, to filter transaction invs for transactions that fall below the feerate provided in the feefilter message interpreted as satoshis per kilobyte.<br />
<br />
The fee filter is additive with a bloom filter for transactions so if an SPV client were to load a bloom filter and send a feefilter message, transactions would only be relayed if they passed both filters.<br />
<br />
Inv's generated from a mempool message are also subject to a fee filter if it exists.<br />
<br />
Feature discovery is enabled by checking protocol version >= 70013<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0133.mediawiki BIP 133] for more information.<br />
<br />
=== sendcmpct ===<br />
<br />
# The sendcmpct message is defined as a message containing a 1-byte integer followed by a 8-byte integer where pchCommand == "sendcmpct".<br />
# The first integer SHALL be interpreted as a boolean (and MUST have a value of either 1 or 0)<br />
# The second integer SHALL be interpreted as a little-endian version number. Nodes sending a sendcmpct message MUST currently set this value to 1.<br />
# Upon receipt of a "sendcmpct" message with the first and second integers set to 1, the node SHOULD announce new blocks by sending a cmpctblock message.<br />
# Upon receipt of a "sendcmpct" message with the first integer set to 0, the node SHOULD NOT announce new blocks by sending a cmpctblock message, but SHOULD announce new blocks by sending invs or headers, as defined by BIP130.<br />
# Upon receipt of a "sendcmpct" message with the second integer set to something other than 1, nodes MUST treat the peer as if they had not received the message (as it indicates the peer will provide an unexpected encoding in <br />
# cmpctblock, and/or other, messages). This allows future versions to send duplicate sendcmpct messages with different versions as a part of a version handshake for future versions.<br />
# Nodes SHOULD check for a protocol version of >= 70014 before sending sendcmpct messages.<br />
# Nodes MUST NOT send a request for a MSG_CMPCT_BLOCK object to a peer before having received a sendcmpct message from that peer.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== cmpctblock ===<br />
<br />
# The cmpctblock message is defined as as a message containing a serialized HeaderAndShortIDs message and pchCommand == "cmpctblock".<br />
# Upon receipt of a cmpctblock message after sending a sendcmpct message, nodes SHOULD calculate the short transaction ID for each unconfirmed transaction they have available (ie in their mempool) and compare each to each short transaction ID in the cmpctblock message.<br />
# After finding already-available transactions, nodes which do not have all transactions available to reconstruct the full block SHOULD request the missing transactions using a getblocktxn message.<br />
# A node MUST NOT send a cmpctblock message unless they are able to respond to a getblocktxn message which requests every transaction in the block.<br />
# A node MUST NOT send a cmpctblock message without having validated that the header properly commits to each transaction in the block, and properly builds on top of the existing chain with a valid proof-of-work. A node MAY send a cmpctblock before validating that each transaction in the block validly spends existing UTXO set entries.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== getblocktxn ===<br />
<br />
# The getblocktxn message is defined as as a message containing a serialized BlockTransactionsRequest message and pchCommand == "getblocktxn".<br />
# Upon receipt of a properly-formatted getblocktxnmessage, nodes which recently provided the sender of such a message a cmpctblock for the block hash identified in this message MUST respond with an appropriate blocktxn message. Such a blocktxn message MUST contain exactly and only each transaction which is present in the appropriate block at the index specified in the getblocktxn indexes list, in the order requested.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== blocktxn ===<br />
<br />
# The blocktxn message is defined as as a message containing a serialized BlockTransactions message and pchCommand == "blocktxn".<br />
# Upon receipt of a properly-formatted requested blocktxn message, nodes SHOULD attempt to reconstruct the full block by:<br />
# Taking the prefilledtxn transactions from the original cmpctblock and placing them in the marked positions.<br />
# For each short transaction ID from the original cmpctblock, in order, find the corresponding transaction either from the blocktxn message or from other sources and place it in the first available position in the block.<br />
# Once the block has been reconstructed, it shall be processed as normal, keeping in mind that short transaction IDs are expected to occasionally collide, and that nodes MUST NOT be penalized for such collisions, wherever they # appear.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
== Scripting ==<br />
<br />
See [[script]].<br />
<br />
==See Also==<br />
<br />
* [[Network]]<br />
* [[Protocol rules]]<br />
* [[Hardfork Wishlist]]<br />
* [https://bitcoin.org/en/developer-documentation Developer Documentation on bitcoin.org]<br />
* Bitcoin dissectors for Wireshark: https://github.com/lbotsch/wireshark-bitcoin https://github.com/op-sig/bitcoin-wireshark-dissector<br />
<br />
==References==<br />
<references /><br />
<br />
[[zh-cn:协议说明]]<br />
[[Category:Technical]]<br />
[[Category:Developer]]<br />
<br />
{{Bitcoin Core documentation}}</div>Tonikthttps://en.bitcoin.it/w/index.php?title=Protocol_documentation&diff=61487Protocol documentation2016-08-25T12:35:34Z<p>Tonikt: /* HeaderAndShortIDs */</p>
<hr />
<div>This page ''describes'' the behavior of the [[Original Bitcoin client|reference client]]. The Bitcoin protocol is specified by the behavior of the reference client, not by this page. In particular, while this page is quite complete in describing the network protocol, it does not attempt to list all of the rules for block or transaction validity.<br />
<br />
Type names used in this documentation are from the C99 standard.<br />
<br />
For protocol used in mining, see [[getblocktemplate]].<br />
<br />
==Common standards==<br />
<br />
=== Hashes ===<br />
<br />
Usually, when a hash is computed within bitcoin, it is computed twice. Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-256] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when a shorter hash is desirable (for example when creating a bitcoin address).<br />
<br />
Example of double-SHA-256 encoding of string "hello":<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round of sha-256)<br />
9595c9df90075148eb06860365df33584b75bff782a510c6cd4883a419833d50 (second round of sha-256)<br />
<br />
For bitcoin addresses (RIPEMD-160) this would give:<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round is sha-256)<br />
b6a9c8c230722b7c748331a8b450f05566dc7d0f (with ripemd-160)<br />
<br />
=== Merkle Trees ===<br />
<br />
Merkle trees are binary trees of hashes. Merkle trees in bitcoin use a '''double''' SHA-256, the SHA-256 hash of the SHA-256 hash of something.<br />
<br />
If, when forming a row in the tree (other than the root of the tree), it would have an odd number of elements, the final double-hash is duplicated to ensure that the row has an even number of hashes.<br />
<br />
First form the bottom row of the tree with the ordered double-SHA-256 hashes of the byte streams of the transactions in the block.<br />
<br />
Then the row above it consists of half that number of hashes. Each entry is the double-SHA-256 of the 64-byte concatenation of the corresponding two hashes below it in the tree.<br />
<br />
This procedure repeats recursively until we reach a row consisting of just a single double-hash. This is the '''Merkle root''' of the tree.<br />
<br />
For example, imagine a block with three transactions ''a'', ''b'' and ''c''. The Merkle tree is: <br />
<br />
d1 = dhash(a)<br />
d2 = dhash(b)<br />
d3 = dhash(c)<br />
d4 = dhash(c) # a, b, c are 3. that's an odd number, so we take the c twice<br />
<br />
d5 = dhash(d1 concat d2)<br />
d6 = dhash(d3 concat d4)<br />
<br />
d7 = dhash(d5 concat d6)<br />
<br />
where<br />
<br />
dhash(a) = sha256(sha256(a))<br />
<br />
''d7'' is the Merkle root of the 3 transactions in this block.<br />
<br />
Note: Hashes in Merkle Tree displayed in the [[Block Explorer]] are of little-endian notation. For some implementations and [http://www.fileformat.info/tool/hash.htm calculations], the bits need to be reversed before they are hashed, and again after the hashing operation.<br />
<br />
=== Signatures ===<br />
<br />
Bitcoin uses [http://en.wikipedia.org/wiki/Elliptic_curve_cryptography Elliptic Curve] [http://en.wikipedia.org/wiki/Digital_Signature_Algorithm Digital Signature Algorithm] ([http://en.wikipedia.org/wiki/Elliptic_Curve_DSA ECDSA]) to sign transactions. <br />
<br />
For [[ECDSA]] the secp256k1 curve from http://www.secg.org/collateral/sec2_final.pdf is used.<br />
<br />
Public keys (in scripts) are given as 04 <x> <y> where ''x'' and ''y'' are 32 byte big-endian integers representing the coordinates of a point on the curve or in compressed form given as <sign> <x> where <sign> is 0x02 if ''y'' is even and 0x03 if ''y'' is odd.<br />
<br />
Signatures use [http://en.wikipedia.org/wiki/Distinguished_Encoding_Rules DER encoding] to pack the ''r'' and ''s'' components into a single byte stream (this is also what OpenSSL produces by default).<br />
<br />
=== Transaction Verification ===<br />
Transactions are cryptographically signed records that reassign ownership of Bitcoins to new addresses. Transactions have ''inputs'' - records which reference the funds from other previous transactions - and ''outputs'' - records which determine the new owner of the transferred Bitcoins, and which will be referenced as inputs in future transactions as those funds are respent.<br />
<br />
Each ''input'' must have a cryptographic digital signature that unlocks the funds from the prior transaction. Only the person possessing the appropriate [[private key]] is able to create a satisfactory signature; this in effect ensures that funds can only be spent by their owners.<br />
<br />
Each ''output'' determines which Bitcoin address (or other criteria, see [[Script]]) is the recipient of the funds.<br />
<br />
In a transaction, the sum of all inputs must be equal to or greater than the sum of all outputs. If the inputs exceed the outputs, the difference is considered a [[transaction fee]], and is redeemable by whoever first includes the transaction into the block chain.<br />
<br />
A special kind of transaction, called a [[coinbase transaction]], has no inputs. It is created by [[miners]], and there is one coinbase transaction per block. Because each block comes with a reward of newly created Bitcoins (e.g. 50 BTC for the first 210,000 blocks), the first transaction of a block is, with few exceptions, the transaction that grants those coins to their recipient (the miner). In addition to the newly created Bitcoins, the coinbase transaction is also used for assigning the recipient of any transaction fees that were paid within the other transactions being included in the same block. The coinbase transaction can assign the entire reward to a single Bitcoin address, or split it in portions among multiple addresses, just like any other transaction. Coinbase transactions always contain outputs totalling the sum of the block reward plus all transaction fees collected from the other transactions in the same block.<br />
<br />
The [[coinbase transaction]] in block zero cannot be spent. This is due to a quirk of the reference client implementation that would open the potential for a block chain fork if some nodes accepted the spend and others did not<ref>[http://bitcointalk.org/index.php?topic=119645.msg1288552#msg1288552 Block 0 Network Fork]</ref>.<br />
<br />
Most Bitcoin outputs encumber the newly transferred coins with a single ECDSA private key. The actual record saved with inputs and outputs isn't necessarily a key, but a ''script''. Bitcoin uses an interpreted scripting system to determine whether an output's criteria have been satisfied, with which more complex operations are possible, such as outputs that require two ECDSA signatures, or two-of-three-signature schemes. An output that references a single Bitcoin address is a ''typical'' output; an output actually contains this information in the form of a script that requires a single ECDSA signature (see [[OP_CHECKSIG]]). The output script specifies what must be provided to unlock the funds later, and when the time comes in the future to spend the transaction in another input, that input must provide all of the thing(s) that satisfy the requirements defined by the original output script.<br />
<br />
=== Addresses ===<br />
<br />
A bitcoin address is in fact the hash of a ECDSA public key, computed this way:<br />
<br />
Version = 1 byte of 0 (zero); on the test network, this is 1 byte of 111<br />
Key hash = Version concatenated with RIPEMD-160(SHA-256(public key))<br />
Checksum = 1st 4 bytes of SHA-256(SHA-256(Key hash))<br />
Bitcoin Address = Base58Encode(Key hash concatenated with Checksum)<br />
<br />
The Base58 encoding used is home made, and has some differences. Especially, leading zeroes are kept as single zeroes when conversion happens.<br />
<br />
== Common structures ==<br />
<br />
Almost all integers are encoded in little endian. Only IP or port number are encoded big endian.<br />
<br />
=== Message structure ===<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown<br />
|-<br />
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| 4 || length || uint32_t || Length of payload in number of bytes<br />
|-<br />
| 4 || checksum || uint32_t || First 4 bytes of sha256(sha256(payload))<br />
|-<br />
| ? || payload || uchar[] || The actual data<br />
|}<br />
<br />
<br />
Known magic values:<br />
<br />
{|class="wikitable"<br />
! Network !! Magic value !! Sent over wire as<br />
|-<br />
| main || 0xD9B4BEF9 || F9 BE B4 D9<br />
|-<br />
| testnet || 0xDAB5BFFA || FA BF B5 DA<br />
|-<br />
| testnet3 || 0x0709110B || 0B 11 09 07<br />
|-<br />
| namecoin || 0xFEB4BEF9 || F9 BE B4 FE<br />
|}<br />
<br />
=== Variable length integer ===<br />
<br />
Integer can be encoded depending on the represented value to save space.<br />
Variable length integers always precede an array/vector of a type of data that may vary in length.<br />
Longer numbers are encoded in little endian.<br />
<br />
{|class="wikitable"<br />
! Value !! Storage length !! Format<br />
|-<br />
| < 0xFD || 1 || uint8_t<br />
|-<br />
| <= 0xFFFF || 3 || 0xFD followed by the length as uint16_t<br />
|-<br />
| <= 0xFFFF FFFF || 5 || 0xFE followed by the length as uint32_t<br />
|-<br />
| - || 9 || 0xFF followed by the length as uint64_t<br />
|}<br />
<br />
If you're reading the Satoshi client code (BitcoinQT) it refers to this encoding as a "CompactSize". Modern BitcoinQT also has the CVarInt class which implements an even more compact integer for the purpose of local storage (which is incompatible with "CompactSize" described here). CVarInt is not a part of the protocol.<br />
<br />
=== Variable length string ===<br />
<br />
Variable length string can be stored using a variable length integer followed by the string itself.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the string<br />
|-<br />
| ? || string || char[] || The string itself (can be empty)<br />
|}<br />
<br />
=== Network address ===<br />
<br />
When a network address is needed somewhere, this structure is used. Network addresses are not prefixed with a timestamp in the version message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || time || uint32 || the Time (version >= 31402). '''Not present in version message.'''<br />
|-<br />
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]<br />
|-<br />
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The original client only supported IPv4 and only read the last 4 bytes to get the IPv4 address. However, the IPv4 address is written into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]<br />
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).<br />
|-<br />
| 2 || port || uint16_t || port number, network byte order<br />
|}<br />
<br />
Hexdump example of Network address structure<br />
<br />
<pre><br />
0000 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0010 00 00 FF FF 0A 00 00 01 20 8D ........ .<br />
<br />
Network address:<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK: see services listed under version command)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv6: ::ffff:a00:1 or IPv4: 10.0.0.1<br />
20 8D - Port 8333<br />
</pre><br />
<br />
=== Inventory Vectors ===<br />
<br />
Inventory vectors are used for notifying other nodes about objects they have or data which is being requested.<br />
<br />
Inventory vectors consist of the following data format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || type || uint32_t || Identifies the object type linked to this inventory<br />
|-<br />
| 32 || hash || char[32] || Hash of the object<br />
|}<br />
<br />
<br />
The object type is currently defined as one of the following possibilities:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0 || ERROR || Any data of with this number may be ignored<br />
|-<br />
| 1 || MSG_TX || Hash is related to a transaction<br />
|-<br />
| 2 || MSG_BLOCK || Hash is related to a data block<br />
|-<br />
| 3 || MSG_FILTERED_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a merkleblock message rather than a block message; this only works if a bloom filter has been set.<br />
|-<br />
| 4 || MSG_CMPCT_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a cmpctblock message. See BIP 152 for more info.<br />
|}<br />
<br />
Other Data Type values are considered reserved for future implementations.<br />
<br />
=== Block Headers ===<br />
<br />
Block headers are sent in a headers packet in response to a getheaders message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Will overflow in 2106<ref>https://en.wikipedia.org/wiki/Unix_time#Notable_events_in_Unix_time</ref>)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 1 || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries, this value is always 0<br />
|}<br />
<br />
cf. [[Block hashing algorithm]]<br />
<br />
=== PrefilledTransaction ===<br />
<br />
A PrefilledTransaction structure is used in HeaderAndShortIDs to provide a list of a few transactions explicitly.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| index || CompactSize || 1, 3 bytes || Compact Size, differentially encoded since the last PrefilledTransaction in a list || The index into the block at which this transaction is<br />
|-<br />
| tx || Transaction || variable || As encoded in "tx" messages || The transaction which is in the block at index index.<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== HeaderAndShortIDs ===<br />
<br />
A HeaderAndShortIDs structure is used to relay a block header, the short transactions IDs used for matching already-available transactions, and a select few transactions which we expect a peer may be missing.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| header || Block header || 80 bytes || First 80 bytes of the block as defined by the encoding used by "block" messages || The header of the block being provided<br />
|-<br />
| nonce || uint64_t || 8 bytes || Little Endian || A nonce for use in short transaction ID calculations<br />
|-<br />
| shortids_length || CompactSize || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of short transaction IDs in shortids (ie block tx count - prefilledtxn_length)<br />
|-<br />
| shortids || List of 6-byte integers || 6*shortids_length bytes || Little Endian || The short transaction IDs calculated from the transactions which were not provided explicitly in prefilledtxn<br />
|-<br />
| prefilledtxn_length || CompactSize || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of prefilled transactions in prefilledtxn (ie block tx count - shortids_length)<br />
|-<br />
| prefilledtxn || List of PrefilledTransactions || variable size*prefilledtxn_length || As defined by PrefilledTransaction definition, above || Used to provide the coinbase transaction and a select few which we expect a peer may be missing<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== BlockTransactionsRequest ===<br />
<br />
A BlockTransactionsRequest structure is used to list transaction indexes in a block being requested.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== BlockTransactions ===<br />
<br />
A BlockTransactions structure is used to provide some of the transactions in a block, as requested.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== Short transaction IDs ===<br />
<br />
Short transaction IDs are used to represent a transaction without sending a full 256-bit hash. They are calculated by:<br />
<br />
# single-SHA256 hashing the block header with the nonce appended (in little-endian)<br />
# Running SipHash-2-4 with the input being the transaction ID and the keys (k0/k1) set to the first two little-endian 64-bit integers from the above hash, respectively.<br />
# Dropping the 2 most significant bytes from the SipHash output to make it 6 bytes.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
== Message types ==<br />
<br />
=== version ===<br />
<br />
When a node creates an outgoing connection, it will immediately [[Version Handshake|advertise]] its version. The remote node will respond with its version. No further communication is possible until both peers have exchanged their version.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Identifies protocol version being used by the node<br />
|-<br />
| 8 || services || uint64_t || bitfield of features to be enabled for this connection<br />
|-<br />
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds<br />
|-<br />
| 26 || addr_recv || [[#Network address|net_addr]] || The network address of the node receiving this message<br />
|-<br />
|colspan="4"| Fields below require version ≥ 106<br />
|-<br />
| 26 || addr_from || [[#Network address|net_addr]] || The network address of the node emitting this message<br />
|-<br />
| 8 || nonce || uint64_t || Node random nonce, randomly generated every time a version packet is sent. This nonce is used to detect connections to self.<br />
|-<br />
| ? || user_agent || [[#Variable length string|var_str]] || [https://github.com/bitcoin/bips/blob/master/bip-0014.mediawiki User Agent] (0x00 if string is 0 bytes long)<br />
|-<br />
| 4 || start_height || int32_t || The last block received by the emitting node<br />
|-<br />
|colspan="4"| Fields below require version ≥ 70001<br />
|-<br />
| 1 || relay || bool || Whether the remote peer should announce relayed transactions or not, see [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037]<br />
|}<br />
<br />
A "verack" packet shall be sent if the version packet was accepted.<br />
<br />
The following services are currently assigned:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 1 || NODE_NETWORK || This node can be asked for full blocks instead of just headers.<br />
|}<br />
<br />
Hexdump example of version message (OBSOLETE EXAMPLE: This example lacks a checksum and user-agent):<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....<br />
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........<br />
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............<br />
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................<br />
0040 20 8D 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,<br />
0060 3A B4 57 13 00 55 81 01 00 :.W..U...<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
55 00 00 00 - Payload is 85 bytes long<br />
- No checksum in version message until 20 February 2012. See https://bitcointalk.org/index.php?topic=55852.0<br />
Version message:<br />
9C 7C 00 00 - 31900 (version 0.3.19)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
E6 15 10 4D 00 00 00 00 - Mon Dec 20 21:50:14 EST 2010<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 20 8D - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D - Sender address info - see Network Address<br />
DD 9D 20 2C 3A B4 57 13 - Node random unique ID<br />
00 - "" sub-version string (string is 0 bytes long)<br />
55 81 01 00 - Last block sending node has is block #98645<br />
</pre><br />
<br />
And here's a modern (60002) protocol version client advertising itself to a local peer...<br />
<br />
Newer protocol includes the checksum now, this is from a mainline (satoshi) client during <br />
an outgoing connection to another local client, notice that it does not fill out the <br />
address information at all when the source or destination is "unroutable".<br />
<br />
<pre><br />
<br />
0000 f9 be b4 d9 76 65 72 73 69 6f 6e 00 00 00 00 00 ....version.....<br />
0010 64 00 00 00 35 8d 49 32 62 ea 00 00 01 00 00 00 d...5.I2b.......<br />
0020 00 00 00 00 11 b2 d0 50 00 00 00 00 01 00 00 00 .......P........<br />
0030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ff ff ................<br />
0040 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 00 00 00 00 ff ff 00 00 00 00 00 00 ................<br />
0060 3b 2e b3 5d 8c e6 17 65 0f 2f 53 61 74 6f 73 68 ;..]...e./Satosh<br />
0070 69 3a 30 2e 37 2e 32 2f c0 3e 03 00 i:0.7.2/.>..<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
64 00 00 00 - Payload is 100 bytes long<br />
3B 64 8D 5A - payload checksum<br />
<br />
Version message:<br />
62 EA 00 00 - 60002 (protocol version 60002)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
11 B2 D0 50 00 00 00 00 - Tue Dec 18 10:12:33 PST 2012<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Sender address info - see Network Address<br />
3B 2E B3 5D 8C E6 17 65 - Node ID<br />
0F 2F 53 61 74 6F 73 68 69 3A 30 2E 37 2E 32 2F - "/Satoshi:0.7.2/" sub-version string (string is 15 bytes long)<br />
C0 3E 03 00 - Last block sending node has is block #212672<br />
</pre><br />
<br />
=== verack ===<br />
<br />
The ''verack'' message is sent in reply to ''[[#version|version]]''. This message consists of only a [[#Message structure|message header]] with the command string "verack".<br />
<br />
Hexdump of the verack message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......<br />
0010 00 00 00 00 5D F6 E0 E2 ........<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 61 63 6B 00 00 00 00 00 00 - "verack" command<br />
00 00 00 00 - Payload is 0 bytes long<br />
5D F6 E0 E2 - Checksum<br />
</pre><br />
<br />
=== addr ===<br />
<br />
Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours<br />
<br />
Payload:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of address entries (max: 1000)<br />
|-<br />
| 30x? || addr_list || (uint32_t + [[#Network address|net_addr]])[] || Address of other nodes on the network. version < 209 will only read the first one. The uint32_t is a timestamp (see note below).<br />
|}<br />
<br />
'''Note''': Starting version 31402, addresses are prefixed with a timestamp. If no timestamp is present, the addresses should not be relayed to other peers, unless it is indeed confirmed they are up.<br />
<br />
Hexdump example of ''addr'' message:<br />
<pre><br />
0000 F9 BE B4 D9 61 64 64 72 00 00 00 00 00 00 00 00 ....addr........<br />
0010 1F 00 00 00 ED 52 39 9B 01 E2 15 10 4D 01 00 00 .....R9.....M...<br />
0020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF ................<br />
0030 FF 0A 00 00 01 20 8D ..... .<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
61 64 64 72 00 00 00 00 00 00 00 00 - "addr"<br />
1F 00 00 00 - payload is 31 bytes long<br />
ED 52 39 9B - checksum of payload<br />
<br />
Payload:<br />
01 - 1 address in this message<br />
<br />
Address:<br />
E2 15 10 4D - Mon Dec 20 21:50:10 EST 2010 (only when version is >= 31402)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK service - see version message)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv4: 10.0.0.1, IPv6: ::ffff:10.0.0.1 (IPv4-mapped IPv6 address)<br />
20 8D - port 8333<br />
</pre><br />
<br />
=== inv ===<br />
<br />
Allows a node to advertise its knowledge of one or more objects. It can be received unsolicited, or in reply to ''getblocks''.<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getdata ===<br />
<br />
getdata is used in response to inv, to retrieve the content of a specific object, and is usually sent after receiving an ''inv'' packet, after filtering known elements. It can be used to retrieve transactions, but only if they are in the memory pool or relay set - arbitrary access to transactions in the chain is not allowed to avoid having clients start to depend on nodes having full transaction indexes (which modern nodes do not).<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== notfound ===<br />
<br />
notfound is a response to a getdata, sent if any requested data items could not be relayed, for example, because the requested transaction was not in the memory pool or relay set.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getblocks ===<br />
<br />
Return an ''inv'' packet containing the list of blocks starting right after the last known hash in the block locator object, up to hash_stop or 500 blocks, whichever comes first. <br />
<br />
The locator hashes are processed by a node in the order as they appear in the message. If a block hash is found in the node's main chain, the list of its children is returned back via the ''inv'' message and the remaining locators are ignored, no matter if the requested limit was reached, or not.<br />
<br />
To receive the next blocks hashes, one needs to issue getblocks again with a new block locator object. Keep in mind that some clients may provide blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block; set to zero to get as many blocks as possible (500)<br />
|}<br />
<br />
To create the block locator hashes, keep pushing hashes until you go back to the genesis block. After pushing 10 hashes back, the step backwards doubles every loop:<br />
<br />
<pre><br />
// From libbitcoin which is under AGPL<br />
std::vector<size_t> block_locator_indexes(size_t top_height)<br />
{<br />
std::vector<size_t> indexes;<br />
<br />
// Modify the step in the iteration.<br />
int64_t step = 1;<br />
<br />
// Start at the top of the chain and work backwards.<br />
for (auto index = (int64_t)top_height; index > 0; index -= step)<br />
{<br />
// Push top 10 indexes first, then back off exponentially.<br />
if (indexes.size() >= 10)<br />
step *= 2;<br />
<br />
indexes.push_back((size_t)index);<br />
}<br />
<br />
// Push the genesis block index.<br />
indexes.push_back(0);<br />
return indexes;<br />
}<br />
</pre><br />
<br />
Note that it is allowed to send in fewer known hashes down to a minimum of just one hash. However, the purpose of the block locator object is to detect a wrong branch in the caller's main chain. If the peer detects that you are off the main chain, it will send in block hashes which are earlier than your last known block. So if you just send in your last known hash and it is off the main chain, the peer starts over at block #1.<br />
<br />
=== getheaders ===<br />
<br />
Return a ''headers'' packet containing the headers of blocks starting right after the last known hash in the block locator object, up to hash_stop or 2000 blocks, whichever comes first. To receive the next block headers, one needs to issue getheaders again with a new block locator object. The ''getheaders'' command is used by thin clients to quickly download the block chain where the contents of the transactions would be irrelevant (because they are not ours). Keep in mind that some clients may provide headers of blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block header; set to zero to get as many blocks as possible (2000)<br />
|}<br />
<br />
For the block locator object in this packet, the same rules apply as for the [[Protocol_documentation#getblocks|getblocks]] packet.<br />
<br />
=== tx ===<br />
<br />
''tx'' describes a bitcoin transaction, in reply to ''[[#getdata|getdata]]''<br />
<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Transaction data format version (note, this is signed)<br />
|-<br />
| 1+ || tx_in count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction inputs<br />
|-<br />
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins<br />
|-<br />
| 1+ || tx_out count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction outputs<br />
|-<br />
| 9+ || tx_out || tx_out[] || A list of 1 or more transaction outputs or destinations for coins<br />
|-<br />
| 4 || lock_time || uint32_t || The block number or timestamp at which this transaction is locked:<br />
{|class="wikitable"<br />
! Value !! Description<br />
|-<br />
| 0 || Not locked<br />
|-<br />
| < 500000000 || Block number at which this transaction is locked<br />
|-<br />
| >= 500000000 || UNIX timestamp at which this transaction is locked<br />
|}<br />
If all TxIn inputs have final (0xffffffff) sequence numbers then lock_time is irrelevant. Otherwise, the transaction may not be added to a block until after lock_time (see [[NLockTime]]).<br />
<br />
|}<br />
<br />
TxIn consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 36 || previous_output || outpoint || The previous output transaction reference, as an OutPoint structure<br />
|-<br />
| 1+ || script length || [[Protocol_documentation#Variable_length_integer|var_int]] || The length of the signature script<br />
|-<br />
| ? || signature script || uchar[] || Computational Script for confirming transaction authorization<br />
|-<br />
| 4 || [http://bitcoin.stackexchange.com/q/2025/323 sequence] || uint32_t || Transaction version as defined by the sender. Intended for "replacement" of transactions when information is updated before inclusion into a block.<br />
|}<br />
<br />
The OutPoint structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 32 || hash || char[32] || The hash of the referenced transaction.<br />
|-<br />
| 4 || index || uint32_t || The index of the specific output in the transaction. The first output is 0, etc.<br />
|}<br />
<br />
The Script structure consists of a series of pieces of information and operations related to the value of the transaction.<br />
<br />
(Structure to be expanded in the future… see script.h and script.cpp and [[Script]] for more information)<br />
<br />
The TxOut structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || value || int64_t || Transaction Value<br />
|-<br />
| 1+ || pk_script length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the pk_script<br />
|-<br />
| ? || pk_script || uchar[] || Usually contains the public key as a Bitcoin script setting up conditions to claim this output.<br />
|}<br />
<br />
Example ''tx'' message:<br />
<pre><br />
000000 F9 BE B4 D9 74 78 00 00 00 00 00 00 00 00 00 00 ....tx..........<br />
000010 02 01 00 00 E2 93 CD BE 01 00 00 00 01 6D BD DB .............m..<br />
000020 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D 12 66 E9 .[...Q........f.<br />
000030 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29 00 00 00 .;P......j.6)...<br />
000040 00 8B 48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 ..H0E.!..X..r...<br />
000050 C7 36 7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A .6zz%;..R#...h.:<br />
000060 59 23 3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 Y#?E.W... Y.....<br />
000070 0E 41 83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D .A.z.X.z...XN...<br />
000080 35 BD 96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF 5...6..;...A....<br />
000090 C9 7E F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 .~.6.m...@..!...<br />
0000A0 2A CD 2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC *.+..].}Y... ...<br />
0000B0 4E 02 53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F N.S..=7.o...Q...<br />
0000C0 14 04 2F 46 61 4A 4C 70 C0 F1 4B EF F5 FF FF FF ../FaJLp..K.....<br />
0000D0 FF 02 40 4B 4C 00 00 00 00 00 19 76 A9 14 1A A0 ..@KL......v....<br />
0000E0 CD 1C BE A6 E7 45 8A 7A BA D5 12 A9 D9 EA 1A FB .....E.z........<br />
0000F0 22 5E 88 AC 80 FA E9 C7 00 00 00 00 19 76 A9 14 "^...........v..<br />
000100 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E FD A0 B7 ..[.Cj.....H^...<br />
000110 8B 4E CC 52 88 AC 00 00 00 00 .N.R......<br />
<br />
<br />
Message header:<br />
F9 BE B4 D9 - main network magic bytes<br />
74 78 00 00 00 00 00 00 00 00 00 00 - "tx" command<br />
02 01 00 00 - payload is 258 bytes long<br />
E2 93 CD BE - checksum of payload<br />
<br />
Transaction:<br />
01 00 00 00 - version<br />
<br />
Inputs:<br />
01 - number of transaction inputs<br />
<br />
Input 1:<br />
6D BD DB 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D - previous output (outpoint)<br />
12 66 E9 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29<br />
00 00 00 00<br />
<br />
8B - script is 139 bytes long<br />
<br />
48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 C7 36 - signature script (scriptSig)<br />
7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A 59 23<br />
3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 0E 41<br />
83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D 35 BD<br />
96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF C9 7E<br />
F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 2A CD<br />
2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC 4E 02<br />
53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F 14 04<br />
2F 46 61 4A 4C 70 C0 F1 4B EF F5<br />
<br />
FF FF FF FF - sequence<br />
<br />
Outputs:<br />
02 - 2 Output Transactions<br />
<br />
Output 1:<br />
40 4B 4C 00 00 00 00 00 - 0.05 BTC (5000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 1A A0 CD 1C BE A6 E7 45 8A 7A BA D5 12 - pk_script<br />
A9 D9 EA 1A FB 22 5E 88 AC<br />
<br />
Output 2:<br />
80 FA E9 C7 00 00 00 00 - 33.54 BTC (3354000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E - pk_script<br />
FD A0 B7 8B 4E CC 52 88 AC<br />
<br />
Locktime:<br />
00 00 00 00 - lock time<br />
</pre><br />
<br />
=== block ===<br />
<br />
The '''block''' message is sent in response to a getdata message which requests transaction information from a block hash.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A Unix timestamp recording when this block was created (Currently limited to dates before the year 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated [[Difficulty|difficulty target]] being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| ? || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries<br />
|-<br />
| ? || txns || tx[] || Block transactions, in format of "tx" command<br />
|}<br />
<br />
The SHA256 hash that identifies each block (and which must have a run of 0 bits) is calculated from the first 6 fields of this structure (version, prev_block, merkle_root, timestamp, bits, nonce, and standard SHA256 padding, making two 64-byte chunks in all) and ''not'' from the complete block. To calculate the hash, only two chunks need to be processed by the SHA256 algorithm. Since the ''nonce'' field is in the second chunk, the first chunk stays constant during mining and therefore only the second chunk needs to be processed. However, a Bitcoin hash is the hash of the hash, so two SHA256 rounds are needed for each mining iteration.<br />
See [[Block hashing algorithm]] for details and an example.<br />
<br />
=== headers ===<br />
<br />
The ''headers'' packet returns block headers in response to a ''getheaders'' packet. <br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of block headers<br />
|-<br />
| 81x? || headers || [[Protocol_documentation#Block_Headers|block_header]][] || [[Protocol_documentation#Block_Headers|Block headers]]<br />
|}<br />
<br />
Note that the block headers in this packet include a transaction count (a var_int, so there can be more than 81 bytes per header) as opposed to the block headers that are hashed by miners.<br />
<br />
=== getaddr ===<br />
<br />
The getaddr message sends a request to a node asking for information about known active peers to help with finding potential nodes in the network. The response to receiving this message is to transmit one or more addr messages with one or more peers from a database of known active peers. The typical presumption is that a node is likely to be active if it has been sending a message within the last three hours.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
=== mempool ===<br />
<br />
The mempool message sends a request to a node asking for information about transactions it has verified but which have not yet confirmed. The response to receiving this message is an inv message containing the transaction hashes for all the transactions in the node's mempool.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
It is specified in [https://github.com/bitcoin/bips/blob/master/bip-0035.mediawiki BIP 35]. Since [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 37], if a [[Protocol_documentation#filterload.2C_filteradd.2C_filterclear.2C_merkleblock|bloom filter]] is loaded, only transactions matching the filter are replied.<br />
<br />
=== checkorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== submitorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== reply ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== ping ===<br />
<br />
The ''ping'' message is sent primarily to confirm that the TCP/IP connection is still valid. An error in transmission is presumed to be a closed connection and the address is removed as a current peer.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || random nonce<br />
|}<br />
<br />
=== pong ===<br />
<br />
The ''pong'' message is sent in response to a ''ping'' message. In modern protocol versions, a ''pong'' response is generated using a nonce included in the ping.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || nonce from ping<br />
|}<br />
<br />
<br />
=== reject===<br />
<br />
The ''reject'' message is sent when messages are rejected.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || message || var_str || type of message rejected<br />
|-<br />
| 1 || ccode || char || code relating to rejected message<br />
|-<br />
| 1+ || reason || var_str || text version of reason for rejection<br />
|-<br />
| 0+ || data || char || Optional extra data provided by some errors. Currently, all errors which provide this field fill it with the TXID or block header hash of the object being rejected, so the field is 32 bytes.<br />
|}<br />
<br />
CCodes<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0x01 || REJECT_MALFORMED|| <br />
|-<br />
| 0x10 || REJECT_INVALID ||<br />
|-<br />
| 0x11 || REJECT_OBSOLETE ||<br />
|-<br />
| 0x12 || REJECT_DUPLICATE ||<br />
|-<br />
| 0x40 || REJECT_NONSTANDARD ||<br />
|-<br />
| 0x41 || REJECT_DUST ||<br />
|-<br />
| 0x42 || REJECT_INSUFFICIENTFEE ||<br />
|-<br />
| 0x43 || REJECT_CHECKPOINT ||<br />
|}<br />
<br />
=== filterload, filteradd, filterclear, merkleblock ===<br />
<br />
These messages are related to Bloom filtering of connections and are defined in [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037].<br />
<br />
<br />
The <code>filterload</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || filter || uint8_t[] || The filter itself is simply a bit field of arbitrary byte-aligned size. The maximum size is 36,000 bytes.<br />
|-<br />
| 4 || nHashFuncs || uint32_t || The number of hash functions to use in this filter. The maximum value allowed in this field is 50.<br />
|-<br />
| 4 || nTweak || uint32_t || A random value to add to the seed value in the hash function used by the bloom filter.<br />
|-<br />
| 1 || nFlags || uint8_t || A set of flags that control how matched items are added to the filter.<br />
|}<br />
<br />
See below for a description of the Bloom filter algorithm and how to select nHashFuncs and filter size for a desired false positive rate.<br />
<br />
Upon receiving a <code>filterload</code> command, the remote peer will immediately restrict the broadcast transactions it announces (in inv packets) to transactions matching the filter, where the matching algorithm is specified below. The flags control the update behaviour of the matching algorithm.<br />
<br />
The <code>filteradd</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || data || uint8_t[] || The data element to add to the current filter.<br />
|}<br />
<br />
The data field must be smaller than or equal to 520 bytes in size (the maximum size of any potentially matched object).<br />
<br />
The given data element will be added to the Bloom filter. A filter must have been previously provided using <code>filterload</code>. This command is useful if a new key or script is added to a clients wallet whilst it has connections to the network open, it avoids the need to re-calculate and send an entirely new filter to every peer (though doing so is usually advisable to maintain anonymity).<br />
<br />
The <code>filterclear</code> command has no arguments at all.<br />
<br />
After a filter has been set, nodes don't merely stop announcing non-matching transactions, they can also serve filtered blocks. A filtered block is defined by the <code>merkleblock</code> message and is defined like this:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information, based upon the software version creating this block (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Limited to 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 4 || total_transactions || uint32_t || Number of transactions in the block (including unmatched ones)<br />
|-<br />
| ? || hashes || uint256[] || hashes in depth-first order (including standard varint size prefix)<br />
|-<br />
| ? || flags || byte[] || flag bits, packed per 8 in a byte, least significant bit first (including standard varint size prefix)<br />
|}<br />
<br />
=== alert ===<br />
<br />
An '''alert''' is sent between nodes to send a general notification message throughout the network. If the alert can be confirmed with the signature as having come from the core development group of the Bitcoin software, the message is suggested to be displayed for end-users. Attempts to perform transactions, particularly automated transactions through the client, are suggested to be halted. The text in the Message string should be relayed to log files and any user interfaces.<br />
<br />
Alert format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || payload || uchar[] || Serialized alert payload<br />
|-<br />
| ? || signature || uchar[] || An ECDSA signature of the message<br />
|}<br />
<br />
The developers of Satoshi's client use this public key for signing alerts:<br />
04fc9702847840aaf195de8442ebecedf5b095cdbb9bc716bda9110971b28a49e0ead8564ff0db22209e0374782c093bb899692d524e9d6a6956e7c5ecbcd68284<br />
(hash) 1AGRxqDa5WjUKBwHB9XYEjmkv1ucoUUy1s<br />
<br />
The payload is serialized into a uchar[] to ensure that versions using incompatible alert formats can still relay alerts among one another. The current alert payload format is:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || Version || int32_t || Alert format version<br />
|-<br />
| 8 || RelayUntil || int64_t || The timestamp beyond which nodes should stop relaying this alert<br />
|-<br />
| 8 || Expiration || int64_t || The timestamp beyond which this alert is no longer in effect and should be ignored<br />
|-<br />
| 4 || ID || int32_t || A unique ID number for this alert<br />
|-<br />
| 4 || Cancel || int32_t || All alerts with an ID number less than or equal to this number should be cancelled: deleted and not accepted in the future<br />
|-<br />
| ? || setCancel || set<int32_t> || All alert IDs contained in this set should be cancelled as above<br />
|-<br />
| 4 || MinVer || int32_t || This alert only applies to versions greater than or equal to this version. Other versions should still relay it.<br />
|-<br />
| 4 || MaxVer || int32_t || This alert only applies to versions less than or equal to this version. Other versions should still relay it.<br />
|-<br />
| ? || setSubVer || set<string> || If this set contains any elements, then only nodes that have their subVer contained in this set are affected by the alert. Other versions should still relay it.<br />
|-<br />
| 4 || Priority || int32_t || Relative priority compared to other alerts<br />
|-<br />
| ? || Comment || string || A comment on the alert that is not displayed<br />
|-<br />
| ? || StatusBar || string || The alert message that is displayed to the user<br />
|-<br />
| ? || Reserved || string || Reserved<br />
|}<br />
<br />
Note: '''set<''type''>''' in the table above is a [[#Variable length integer | variable length integer]] followed by the number of fields of the given ''type'' (either int32_t or [[#Variable length string | variable length string]])<br />
<br />
Sample alert (no message header):<br />
73010000003766404f00000000b305434f00000000f2030000f1030000001027000048ee0000<br />
0064000000004653656520626974636f696e2e6f72672f666562323020696620796f75206861<br />
76652074726f75626c6520636f6e6e656374696e672061667465722032302046656272756172<br />
79004730450221008389df45f0703f39ec8c1cc42c13810ffcae14995bb648340219e353b63b<br />
53eb022009ec65e1c1aaeec1fd334c6b684bde2b3f573060d5b70c3a46723326e4e8a4f1<br />
<br />
Version: 1<br />
RelayUntil: 1329620535<br />
Expiration: 1329792435<br />
ID: 1010<br />
Cancel: 1009<br />
setCancel: <empty><br />
MinVer: 10000<br />
MaxVer: 61000<br />
setSubVer: <empty><br />
Priority: 100<br />
Comment: <empty><br />
StatusBar: "See bitcoin.org/feb20 if you have trouble connecting after 20 February"<br />
Reserved: <empty><br />
<br />
=== sendheaders ===<br />
<br />
Request for Direct headers announcement. <br />
<br />
Upon receipt of this message, the node is be permitted, but not required, to announce new blocks by '''headers''' command (instead of '''inv''' command).<br />
<br />
This message is supported by the protocol version >= 70012 or Bitcoin Core version >= 0.12.0.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0130.mediawiki BIP 130] for more information.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
<br />
=== feefilter ===<br />
<br />
The payload is always 8 bytes long and it encodes 64 bit integer value (LSB / little endian) of '''feerate'''.<br />
The value represents a minimal fee and is expressed in satoshis per 1000 bytes.<br />
<br />
Upon receipt of a "feefilter" message, the node will be permitted, but not required, to filter transaction invs for transactions that fall below the feerate provided in the feefilter message interpreted as satoshis per kilobyte.<br />
<br />
The fee filter is additive with a bloom filter for transactions so if an SPV client were to load a bloom filter and send a feefilter message, transactions would only be relayed if they passed both filters.<br />
<br />
Inv's generated from a mempool message are also subject to a fee filter if it exists.<br />
<br />
Feature discovery is enabled by checking protocol version >= 70013<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0133.mediawiki BIP 133] for more information.<br />
<br />
=== sendcmpct ===<br />
<br />
# The sendcmpct message is defined as a message containing a 1-byte integer followed by a 8-byte integer where pchCommand == "sendcmpct".<br />
# The first integer SHALL be interpreted as a boolean (and MUST have a value of either 1 or 0)<br />
# The second integer SHALL be interpreted as a little-endian version number. Nodes sending a sendcmpct message MUST currently set this value to 1.<br />
# Upon receipt of a "sendcmpct" message with the first and second integers set to 1, the node SHOULD announce new blocks by sending a cmpctblock message.<br />
# Upon receipt of a "sendcmpct" message with the first integer set to 0, the node SHOULD NOT announce new blocks by sending a cmpctblock message, but SHOULD announce new blocks by sending invs or headers, as defined by BIP130.<br />
# Upon receipt of a "sendcmpct" message with the second integer set to something other than 1, nodes MUST treat the peer as if they had not received the message (as it indicates the peer will provide an unexpected encoding in <br />
# cmpctblock, and/or other, messages). This allows future versions to send duplicate sendcmpct messages with different versions as a part of a version handshake for future versions.<br />
# Nodes SHOULD check for a protocol version of >= 70014 before sending sendcmpct messages.<br />
# Nodes MUST NOT send a request for a MSG_CMPCT_BLOCK object to a peer before having received a sendcmpct message from that peer.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== cmpctblock ===<br />
<br />
# The cmpctblock message is defined as as a message containing a serialized HeaderAndShortIDs message and pchCommand == "cmpctblock".<br />
# Upon receipt of a cmpctblock message after sending a sendcmpct message, nodes SHOULD calculate the short transaction ID for each unconfirmed transaction they have available (ie in their mempool) and compare each to each short transaction ID in the cmpctblock message.<br />
# After finding already-available transactions, nodes which do not have all transactions available to reconstruct the full block SHOULD request the missing transactions using a getblocktxn message.<br />
# A node MUST NOT send a cmpctblock message unless they are able to respond to a getblocktxn message which requests every transaction in the block.<br />
# A node MUST NOT send a cmpctblock message without having validated that the header properly commits to each transaction in the block, and properly builds on top of the existing chain with a valid proof-of-work. A node MAY send a cmpctblock before validating that each transaction in the block validly spends existing UTXO set entries.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== getblocktxn ===<br />
<br />
# The getblocktxn message is defined as as a message containing a serialized BlockTransactionsRequest message and pchCommand == "getblocktxn".<br />
# Upon receipt of a properly-formatted getblocktxnmessage, nodes which recently provided the sender of such a message a cmpctblock for the block hash identified in this message MUST respond with an appropriate blocktxn message. Such a blocktxn message MUST contain exactly and only each transaction which is present in the appropriate block at the index specified in the getblocktxn indexes list, in the order requested.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== blocktxn ===<br />
<br />
# The blocktxn message is defined as as a message containing a serialized BlockTransactions message and pchCommand == "blocktxn".<br />
# Upon receipt of a properly-formatted requested blocktxn message, nodes SHOULD attempt to reconstruct the full block by:<br />
# Taking the prefilledtxn transactions from the original cmpctblock and placing them in the marked positions.<br />
# For each short transaction ID from the original cmpctblock, in order, find the corresponding transaction either from the blocktxn message or from other sources and place it in the first available position in the block.<br />
# Once the block has been reconstructed, it shall be processed as normal, keeping in mind that short transaction IDs are expected to occasionally collide, and that nodes MUST NOT be penalized for such collisions, wherever they # appear.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
== Scripting ==<br />
<br />
See [[script]].<br />
<br />
==See Also==<br />
<br />
* [[Network]]<br />
* [[Protocol rules]]<br />
* [[Hardfork Wishlist]]<br />
* [https://bitcoin.org/en/developer-documentation Developer Documentation on bitcoin.org]<br />
* Bitcoin dissectors for Wireshark: https://github.com/lbotsch/wireshark-bitcoin https://github.com/op-sig/bitcoin-wireshark-dissector<br />
<br />
==References==<br />
<references /><br />
<br />
[[zh-cn:协议说明]]<br />
[[Category:Technical]]<br />
[[Category:Developer]]<br />
<br />
{{Bitcoin Core documentation}}</div>Tonikthttps://en.bitcoin.it/w/index.php?title=Protocol_documentation&diff=61486Protocol documentation2016-08-25T12:35:23Z<p>Tonikt: /* HeaderAndShortIDs */</p>
<hr />
<div>This page ''describes'' the behavior of the [[Original Bitcoin client|reference client]]. The Bitcoin protocol is specified by the behavior of the reference client, not by this page. In particular, while this page is quite complete in describing the network protocol, it does not attempt to list all of the rules for block or transaction validity.<br />
<br />
Type names used in this documentation are from the C99 standard.<br />
<br />
For protocol used in mining, see [[getblocktemplate]].<br />
<br />
==Common standards==<br />
<br />
=== Hashes ===<br />
<br />
Usually, when a hash is computed within bitcoin, it is computed twice. Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-256] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when a shorter hash is desirable (for example when creating a bitcoin address).<br />
<br />
Example of double-SHA-256 encoding of string "hello":<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round of sha-256)<br />
9595c9df90075148eb06860365df33584b75bff782a510c6cd4883a419833d50 (second round of sha-256)<br />
<br />
For bitcoin addresses (RIPEMD-160) this would give:<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round is sha-256)<br />
b6a9c8c230722b7c748331a8b450f05566dc7d0f (with ripemd-160)<br />
<br />
=== Merkle Trees ===<br />
<br />
Merkle trees are binary trees of hashes. Merkle trees in bitcoin use a '''double''' SHA-256, the SHA-256 hash of the SHA-256 hash of something.<br />
<br />
If, when forming a row in the tree (other than the root of the tree), it would have an odd number of elements, the final double-hash is duplicated to ensure that the row has an even number of hashes.<br />
<br />
First form the bottom row of the tree with the ordered double-SHA-256 hashes of the byte streams of the transactions in the block.<br />
<br />
Then the row above it consists of half that number of hashes. Each entry is the double-SHA-256 of the 64-byte concatenation of the corresponding two hashes below it in the tree.<br />
<br />
This procedure repeats recursively until we reach a row consisting of just a single double-hash. This is the '''Merkle root''' of the tree.<br />
<br />
For example, imagine a block with three transactions ''a'', ''b'' and ''c''. The Merkle tree is: <br />
<br />
d1 = dhash(a)<br />
d2 = dhash(b)<br />
d3 = dhash(c)<br />
d4 = dhash(c) # a, b, c are 3. that's an odd number, so we take the c twice<br />
<br />
d5 = dhash(d1 concat d2)<br />
d6 = dhash(d3 concat d4)<br />
<br />
d7 = dhash(d5 concat d6)<br />
<br />
where<br />
<br />
dhash(a) = sha256(sha256(a))<br />
<br />
''d7'' is the Merkle root of the 3 transactions in this block.<br />
<br />
Note: Hashes in Merkle Tree displayed in the [[Block Explorer]] are of little-endian notation. For some implementations and [http://www.fileformat.info/tool/hash.htm calculations], the bits need to be reversed before they are hashed, and again after the hashing operation.<br />
<br />
=== Signatures ===<br />
<br />
Bitcoin uses [http://en.wikipedia.org/wiki/Elliptic_curve_cryptography Elliptic Curve] [http://en.wikipedia.org/wiki/Digital_Signature_Algorithm Digital Signature Algorithm] ([http://en.wikipedia.org/wiki/Elliptic_Curve_DSA ECDSA]) to sign transactions. <br />
<br />
For [[ECDSA]] the secp256k1 curve from http://www.secg.org/collateral/sec2_final.pdf is used.<br />
<br />
Public keys (in scripts) are given as 04 <x> <y> where ''x'' and ''y'' are 32 byte big-endian integers representing the coordinates of a point on the curve or in compressed form given as <sign> <x> where <sign> is 0x02 if ''y'' is even and 0x03 if ''y'' is odd.<br />
<br />
Signatures use [http://en.wikipedia.org/wiki/Distinguished_Encoding_Rules DER encoding] to pack the ''r'' and ''s'' components into a single byte stream (this is also what OpenSSL produces by default).<br />
<br />
=== Transaction Verification ===<br />
Transactions are cryptographically signed records that reassign ownership of Bitcoins to new addresses. Transactions have ''inputs'' - records which reference the funds from other previous transactions - and ''outputs'' - records which determine the new owner of the transferred Bitcoins, and which will be referenced as inputs in future transactions as those funds are respent.<br />
<br />
Each ''input'' must have a cryptographic digital signature that unlocks the funds from the prior transaction. Only the person possessing the appropriate [[private key]] is able to create a satisfactory signature; this in effect ensures that funds can only be spent by their owners.<br />
<br />
Each ''output'' determines which Bitcoin address (or other criteria, see [[Script]]) is the recipient of the funds.<br />
<br />
In a transaction, the sum of all inputs must be equal to or greater than the sum of all outputs. If the inputs exceed the outputs, the difference is considered a [[transaction fee]], and is redeemable by whoever first includes the transaction into the block chain.<br />
<br />
A special kind of transaction, called a [[coinbase transaction]], has no inputs. It is created by [[miners]], and there is one coinbase transaction per block. Because each block comes with a reward of newly created Bitcoins (e.g. 50 BTC for the first 210,000 blocks), the first transaction of a block is, with few exceptions, the transaction that grants those coins to their recipient (the miner). In addition to the newly created Bitcoins, the coinbase transaction is also used for assigning the recipient of any transaction fees that were paid within the other transactions being included in the same block. The coinbase transaction can assign the entire reward to a single Bitcoin address, or split it in portions among multiple addresses, just like any other transaction. Coinbase transactions always contain outputs totalling the sum of the block reward plus all transaction fees collected from the other transactions in the same block.<br />
<br />
The [[coinbase transaction]] in block zero cannot be spent. This is due to a quirk of the reference client implementation that would open the potential for a block chain fork if some nodes accepted the spend and others did not<ref>[http://bitcointalk.org/index.php?topic=119645.msg1288552#msg1288552 Block 0 Network Fork]</ref>.<br />
<br />
Most Bitcoin outputs encumber the newly transferred coins with a single ECDSA private key. The actual record saved with inputs and outputs isn't necessarily a key, but a ''script''. Bitcoin uses an interpreted scripting system to determine whether an output's criteria have been satisfied, with which more complex operations are possible, such as outputs that require two ECDSA signatures, or two-of-three-signature schemes. An output that references a single Bitcoin address is a ''typical'' output; an output actually contains this information in the form of a script that requires a single ECDSA signature (see [[OP_CHECKSIG]]). The output script specifies what must be provided to unlock the funds later, and when the time comes in the future to spend the transaction in another input, that input must provide all of the thing(s) that satisfy the requirements defined by the original output script.<br />
<br />
=== Addresses ===<br />
<br />
A bitcoin address is in fact the hash of a ECDSA public key, computed this way:<br />
<br />
Version = 1 byte of 0 (zero); on the test network, this is 1 byte of 111<br />
Key hash = Version concatenated with RIPEMD-160(SHA-256(public key))<br />
Checksum = 1st 4 bytes of SHA-256(SHA-256(Key hash))<br />
Bitcoin Address = Base58Encode(Key hash concatenated with Checksum)<br />
<br />
The Base58 encoding used is home made, and has some differences. Especially, leading zeroes are kept as single zeroes when conversion happens.<br />
<br />
== Common structures ==<br />
<br />
Almost all integers are encoded in little endian. Only IP or port number are encoded big endian.<br />
<br />
=== Message structure ===<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown<br />
|-<br />
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| 4 || length || uint32_t || Length of payload in number of bytes<br />
|-<br />
| 4 || checksum || uint32_t || First 4 bytes of sha256(sha256(payload))<br />
|-<br />
| ? || payload || uchar[] || The actual data<br />
|}<br />
<br />
<br />
Known magic values:<br />
<br />
{|class="wikitable"<br />
! Network !! Magic value !! Sent over wire as<br />
|-<br />
| main || 0xD9B4BEF9 || F9 BE B4 D9<br />
|-<br />
| testnet || 0xDAB5BFFA || FA BF B5 DA<br />
|-<br />
| testnet3 || 0x0709110B || 0B 11 09 07<br />
|-<br />
| namecoin || 0xFEB4BEF9 || F9 BE B4 FE<br />
|}<br />
<br />
=== Variable length integer ===<br />
<br />
Integer can be encoded depending on the represented value to save space.<br />
Variable length integers always precede an array/vector of a type of data that may vary in length.<br />
Longer numbers are encoded in little endian.<br />
<br />
{|class="wikitable"<br />
! Value !! Storage length !! Format<br />
|-<br />
| < 0xFD || 1 || uint8_t<br />
|-<br />
| <= 0xFFFF || 3 || 0xFD followed by the length as uint16_t<br />
|-<br />
| <= 0xFFFF FFFF || 5 || 0xFE followed by the length as uint32_t<br />
|-<br />
| - || 9 || 0xFF followed by the length as uint64_t<br />
|}<br />
<br />
If you're reading the Satoshi client code (BitcoinQT) it refers to this encoding as a "CompactSize". Modern BitcoinQT also has the CVarInt class which implements an even more compact integer for the purpose of local storage (which is incompatible with "CompactSize" described here). CVarInt is not a part of the protocol.<br />
<br />
=== Variable length string ===<br />
<br />
Variable length string can be stored using a variable length integer followed by the string itself.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the string<br />
|-<br />
| ? || string || char[] || The string itself (can be empty)<br />
|}<br />
<br />
=== Network address ===<br />
<br />
When a network address is needed somewhere, this structure is used. Network addresses are not prefixed with a timestamp in the version message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || time || uint32 || the Time (version >= 31402). '''Not present in version message.'''<br />
|-<br />
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]<br />
|-<br />
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The original client only supported IPv4 and only read the last 4 bytes to get the IPv4 address. However, the IPv4 address is written into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]<br />
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).<br />
|-<br />
| 2 || port || uint16_t || port number, network byte order<br />
|}<br />
<br />
Hexdump example of Network address structure<br />
<br />
<pre><br />
0000 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0010 00 00 FF FF 0A 00 00 01 20 8D ........ .<br />
<br />
Network address:<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK: see services listed under version command)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv6: ::ffff:a00:1 or IPv4: 10.0.0.1<br />
20 8D - Port 8333<br />
</pre><br />
<br />
=== Inventory Vectors ===<br />
<br />
Inventory vectors are used for notifying other nodes about objects they have or data which is being requested.<br />
<br />
Inventory vectors consist of the following data format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || type || uint32_t || Identifies the object type linked to this inventory<br />
|-<br />
| 32 || hash || char[32] || Hash of the object<br />
|}<br />
<br />
<br />
The object type is currently defined as one of the following possibilities:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0 || ERROR || Any data of with this number may be ignored<br />
|-<br />
| 1 || MSG_TX || Hash is related to a transaction<br />
|-<br />
| 2 || MSG_BLOCK || Hash is related to a data block<br />
|-<br />
| 3 || MSG_FILTERED_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a merkleblock message rather than a block message; this only works if a bloom filter has been set.<br />
|-<br />
| 4 || MSG_CMPCT_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a cmpctblock message. See BIP 152 for more info.<br />
|}<br />
<br />
Other Data Type values are considered reserved for future implementations.<br />
<br />
=== Block Headers ===<br />
<br />
Block headers are sent in a headers packet in response to a getheaders message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Will overflow in 2106<ref>https://en.wikipedia.org/wiki/Unix_time#Notable_events_in_Unix_time</ref>)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 1 || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries, this value is always 0<br />
|}<br />
<br />
cf. [[Block hashing algorithm]]<br />
<br />
=== PrefilledTransaction ===<br />
<br />
A PrefilledTransaction structure is used in HeaderAndShortIDs to provide a list of a few transactions explicitly.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| index || CompactSize || 1, 3 bytes || Compact Size, differentially encoded since the last PrefilledTransaction in a list || The index into the block at which this transaction is<br />
|-<br />
| tx || Transaction || variable || As encoded in "tx" messages || The transaction which is in the block at index index.<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== HeaderAndShortIDs ===<br />
<br />
A HeaderAndShortIDs structure is used to relay a block header, the short transactions IDs used for matching already-available transactions, and a select few transactions which we expect a peer may be missing.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| header || Block header || 80 bytes || First 80 bytes of the block as defined by the encoding used by "block" messages || The header of the block being provided<br />
|-<br />
| nonce || uint64_t || 8 bytes || Little Endian || A nonce for use in short transaction ID calculations<br />
|-<br />
| shortids_length || CompactSize || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of short transaction IDs in shortids (ie block tx count - prefilledtxn_length)<br />
|-<br />
| shortids || List of 6-byte integers || 6*shortids_length bytes || Little Endian || The short transaction IDs calculated from the transactions which were not provided explicitly in prefilledtxn<br />
|-<br />
| prefilledtxn_length || CompactSize || 1 or 3 bytes || As used to encode array lengths elsewhere || The number of prefilled transactions in prefilledtxn (ie block tx count - shortids_length)<br />
|-<br />
| prefilledtxn || List of PrefilledTransactions || variable size*prefilledtxn_length || As defined by PrefilledTransaction definition, above || Used to provide the coinbase transaction and a select few which we expect a peer may be missing<br />
|}<br />
<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== BlockTransactionsRequest ===<br />
<br />
A BlockTransactionsRequest structure is used to list transaction indexes in a block being requested.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== BlockTransactions ===<br />
<br />
A BlockTransactions structure is used to provide some of the transactions in a block, as requested.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== Short transaction IDs ===<br />
<br />
Short transaction IDs are used to represent a transaction without sending a full 256-bit hash. They are calculated by:<br />
<br />
# single-SHA256 hashing the block header with the nonce appended (in little-endian)<br />
# Running SipHash-2-4 with the input being the transaction ID and the keys (k0/k1) set to the first two little-endian 64-bit integers from the above hash, respectively.<br />
# Dropping the 2 most significant bytes from the SipHash output to make it 6 bytes.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
== Message types ==<br />
<br />
=== version ===<br />
<br />
When a node creates an outgoing connection, it will immediately [[Version Handshake|advertise]] its version. The remote node will respond with its version. No further communication is possible until both peers have exchanged their version.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Identifies protocol version being used by the node<br />
|-<br />
| 8 || services || uint64_t || bitfield of features to be enabled for this connection<br />
|-<br />
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds<br />
|-<br />
| 26 || addr_recv || [[#Network address|net_addr]] || The network address of the node receiving this message<br />
|-<br />
|colspan="4"| Fields below require version ≥ 106<br />
|-<br />
| 26 || addr_from || [[#Network address|net_addr]] || The network address of the node emitting this message<br />
|-<br />
| 8 || nonce || uint64_t || Node random nonce, randomly generated every time a version packet is sent. This nonce is used to detect connections to self.<br />
|-<br />
| ? || user_agent || [[#Variable length string|var_str]] || [https://github.com/bitcoin/bips/blob/master/bip-0014.mediawiki User Agent] (0x00 if string is 0 bytes long)<br />
|-<br />
| 4 || start_height || int32_t || The last block received by the emitting node<br />
|-<br />
|colspan="4"| Fields below require version ≥ 70001<br />
|-<br />
| 1 || relay || bool || Whether the remote peer should announce relayed transactions or not, see [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037]<br />
|}<br />
<br />
A "verack" packet shall be sent if the version packet was accepted.<br />
<br />
The following services are currently assigned:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 1 || NODE_NETWORK || This node can be asked for full blocks instead of just headers.<br />
|}<br />
<br />
Hexdump example of version message (OBSOLETE EXAMPLE: This example lacks a checksum and user-agent):<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....<br />
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........<br />
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............<br />
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................<br />
0040 20 8D 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,<br />
0060 3A B4 57 13 00 55 81 01 00 :.W..U...<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
55 00 00 00 - Payload is 85 bytes long<br />
- No checksum in version message until 20 February 2012. See https://bitcointalk.org/index.php?topic=55852.0<br />
Version message:<br />
9C 7C 00 00 - 31900 (version 0.3.19)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
E6 15 10 4D 00 00 00 00 - Mon Dec 20 21:50:14 EST 2010<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 20 8D - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D - Sender address info - see Network Address<br />
DD 9D 20 2C 3A B4 57 13 - Node random unique ID<br />
00 - "" sub-version string (string is 0 bytes long)<br />
55 81 01 00 - Last block sending node has is block #98645<br />
</pre><br />
<br />
And here's a modern (60002) protocol version client advertising itself to a local peer...<br />
<br />
Newer protocol includes the checksum now, this is from a mainline (satoshi) client during <br />
an outgoing connection to another local client, notice that it does not fill out the <br />
address information at all when the source or destination is "unroutable".<br />
<br />
<pre><br />
<br />
0000 f9 be b4 d9 76 65 72 73 69 6f 6e 00 00 00 00 00 ....version.....<br />
0010 64 00 00 00 35 8d 49 32 62 ea 00 00 01 00 00 00 d...5.I2b.......<br />
0020 00 00 00 00 11 b2 d0 50 00 00 00 00 01 00 00 00 .......P........<br />
0030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ff ff ................<br />
0040 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 00 00 00 00 ff ff 00 00 00 00 00 00 ................<br />
0060 3b 2e b3 5d 8c e6 17 65 0f 2f 53 61 74 6f 73 68 ;..]...e./Satosh<br />
0070 69 3a 30 2e 37 2e 32 2f c0 3e 03 00 i:0.7.2/.>..<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
64 00 00 00 - Payload is 100 bytes long<br />
3B 64 8D 5A - payload checksum<br />
<br />
Version message:<br />
62 EA 00 00 - 60002 (protocol version 60002)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
11 B2 D0 50 00 00 00 00 - Tue Dec 18 10:12:33 PST 2012<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Sender address info - see Network Address<br />
3B 2E B3 5D 8C E6 17 65 - Node ID<br />
0F 2F 53 61 74 6F 73 68 69 3A 30 2E 37 2E 32 2F - "/Satoshi:0.7.2/" sub-version string (string is 15 bytes long)<br />
C0 3E 03 00 - Last block sending node has is block #212672<br />
</pre><br />
<br />
=== verack ===<br />
<br />
The ''verack'' message is sent in reply to ''[[#version|version]]''. This message consists of only a [[#Message structure|message header]] with the command string "verack".<br />
<br />
Hexdump of the verack message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......<br />
0010 00 00 00 00 5D F6 E0 E2 ........<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 61 63 6B 00 00 00 00 00 00 - "verack" command<br />
00 00 00 00 - Payload is 0 bytes long<br />
5D F6 E0 E2 - Checksum<br />
</pre><br />
<br />
=== addr ===<br />
<br />
Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours<br />
<br />
Payload:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of address entries (max: 1000)<br />
|-<br />
| 30x? || addr_list || (uint32_t + [[#Network address|net_addr]])[] || Address of other nodes on the network. version < 209 will only read the first one. The uint32_t is a timestamp (see note below).<br />
|}<br />
<br />
'''Note''': Starting version 31402, addresses are prefixed with a timestamp. If no timestamp is present, the addresses should not be relayed to other peers, unless it is indeed confirmed they are up.<br />
<br />
Hexdump example of ''addr'' message:<br />
<pre><br />
0000 F9 BE B4 D9 61 64 64 72 00 00 00 00 00 00 00 00 ....addr........<br />
0010 1F 00 00 00 ED 52 39 9B 01 E2 15 10 4D 01 00 00 .....R9.....M...<br />
0020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF ................<br />
0030 FF 0A 00 00 01 20 8D ..... .<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
61 64 64 72 00 00 00 00 00 00 00 00 - "addr"<br />
1F 00 00 00 - payload is 31 bytes long<br />
ED 52 39 9B - checksum of payload<br />
<br />
Payload:<br />
01 - 1 address in this message<br />
<br />
Address:<br />
E2 15 10 4D - Mon Dec 20 21:50:10 EST 2010 (only when version is >= 31402)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK service - see version message)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv4: 10.0.0.1, IPv6: ::ffff:10.0.0.1 (IPv4-mapped IPv6 address)<br />
20 8D - port 8333<br />
</pre><br />
<br />
=== inv ===<br />
<br />
Allows a node to advertise its knowledge of one or more objects. It can be received unsolicited, or in reply to ''getblocks''.<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getdata ===<br />
<br />
getdata is used in response to inv, to retrieve the content of a specific object, and is usually sent after receiving an ''inv'' packet, after filtering known elements. It can be used to retrieve transactions, but only if they are in the memory pool or relay set - arbitrary access to transactions in the chain is not allowed to avoid having clients start to depend on nodes having full transaction indexes (which modern nodes do not).<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== notfound ===<br />
<br />
notfound is a response to a getdata, sent if any requested data items could not be relayed, for example, because the requested transaction was not in the memory pool or relay set.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getblocks ===<br />
<br />
Return an ''inv'' packet containing the list of blocks starting right after the last known hash in the block locator object, up to hash_stop or 500 blocks, whichever comes first. <br />
<br />
The locator hashes are processed by a node in the order as they appear in the message. If a block hash is found in the node's main chain, the list of its children is returned back via the ''inv'' message and the remaining locators are ignored, no matter if the requested limit was reached, or not.<br />
<br />
To receive the next blocks hashes, one needs to issue getblocks again with a new block locator object. Keep in mind that some clients may provide blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block; set to zero to get as many blocks as possible (500)<br />
|}<br />
<br />
To create the block locator hashes, keep pushing hashes until you go back to the genesis block. After pushing 10 hashes back, the step backwards doubles every loop:<br />
<br />
<pre><br />
// From libbitcoin which is under AGPL<br />
std::vector<size_t> block_locator_indexes(size_t top_height)<br />
{<br />
std::vector<size_t> indexes;<br />
<br />
// Modify the step in the iteration.<br />
int64_t step = 1;<br />
<br />
// Start at the top of the chain and work backwards.<br />
for (auto index = (int64_t)top_height; index > 0; index -= step)<br />
{<br />
// Push top 10 indexes first, then back off exponentially.<br />
if (indexes.size() >= 10)<br />
step *= 2;<br />
<br />
indexes.push_back((size_t)index);<br />
}<br />
<br />
// Push the genesis block index.<br />
indexes.push_back(0);<br />
return indexes;<br />
}<br />
</pre><br />
<br />
Note that it is allowed to send in fewer known hashes down to a minimum of just one hash. However, the purpose of the block locator object is to detect a wrong branch in the caller's main chain. If the peer detects that you are off the main chain, it will send in block hashes which are earlier than your last known block. So if you just send in your last known hash and it is off the main chain, the peer starts over at block #1.<br />
<br />
=== getheaders ===<br />
<br />
Return a ''headers'' packet containing the headers of blocks starting right after the last known hash in the block locator object, up to hash_stop or 2000 blocks, whichever comes first. To receive the next block headers, one needs to issue getheaders again with a new block locator object. The ''getheaders'' command is used by thin clients to quickly download the block chain where the contents of the transactions would be irrelevant (because they are not ours). Keep in mind that some clients may provide headers of blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block header; set to zero to get as many blocks as possible (2000)<br />
|}<br />
<br />
For the block locator object in this packet, the same rules apply as for the [[Protocol_documentation#getblocks|getblocks]] packet.<br />
<br />
=== tx ===<br />
<br />
''tx'' describes a bitcoin transaction, in reply to ''[[#getdata|getdata]]''<br />
<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Transaction data format version (note, this is signed)<br />
|-<br />
| 1+ || tx_in count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction inputs<br />
|-<br />
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins<br />
|-<br />
| 1+ || tx_out count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction outputs<br />
|-<br />
| 9+ || tx_out || tx_out[] || A list of 1 or more transaction outputs or destinations for coins<br />
|-<br />
| 4 || lock_time || uint32_t || The block number or timestamp at which this transaction is locked:<br />
{|class="wikitable"<br />
! Value !! Description<br />
|-<br />
| 0 || Not locked<br />
|-<br />
| < 500000000 || Block number at which this transaction is locked<br />
|-<br />
| >= 500000000 || UNIX timestamp at which this transaction is locked<br />
|}<br />
If all TxIn inputs have final (0xffffffff) sequence numbers then lock_time is irrelevant. Otherwise, the transaction may not be added to a block until after lock_time (see [[NLockTime]]).<br />
<br />
|}<br />
<br />
TxIn consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 36 || previous_output || outpoint || The previous output transaction reference, as an OutPoint structure<br />
|-<br />
| 1+ || script length || [[Protocol_documentation#Variable_length_integer|var_int]] || The length of the signature script<br />
|-<br />
| ? || signature script || uchar[] || Computational Script for confirming transaction authorization<br />
|-<br />
| 4 || [http://bitcoin.stackexchange.com/q/2025/323 sequence] || uint32_t || Transaction version as defined by the sender. Intended for "replacement" of transactions when information is updated before inclusion into a block.<br />
|}<br />
<br />
The OutPoint structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 32 || hash || char[32] || The hash of the referenced transaction.<br />
|-<br />
| 4 || index || uint32_t || The index of the specific output in the transaction. The first output is 0, etc.<br />
|}<br />
<br />
The Script structure consists of a series of pieces of information and operations related to the value of the transaction.<br />
<br />
(Structure to be expanded in the future… see script.h and script.cpp and [[Script]] for more information)<br />
<br />
The TxOut structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || value || int64_t || Transaction Value<br />
|-<br />
| 1+ || pk_script length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the pk_script<br />
|-<br />
| ? || pk_script || uchar[] || Usually contains the public key as a Bitcoin script setting up conditions to claim this output.<br />
|}<br />
<br />
Example ''tx'' message:<br />
<pre><br />
000000 F9 BE B4 D9 74 78 00 00 00 00 00 00 00 00 00 00 ....tx..........<br />
000010 02 01 00 00 E2 93 CD BE 01 00 00 00 01 6D BD DB .............m..<br />
000020 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D 12 66 E9 .[...Q........f.<br />
000030 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29 00 00 00 .;P......j.6)...<br />
000040 00 8B 48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 ..H0E.!..X..r...<br />
000050 C7 36 7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A .6zz%;..R#...h.:<br />
000060 59 23 3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 Y#?E.W... Y.....<br />
000070 0E 41 83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D .A.z.X.z...XN...<br />
000080 35 BD 96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF 5...6..;...A....<br />
000090 C9 7E F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 .~.6.m...@..!...<br />
0000A0 2A CD 2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC *.+..].}Y... ...<br />
0000B0 4E 02 53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F N.S..=7.o...Q...<br />
0000C0 14 04 2F 46 61 4A 4C 70 C0 F1 4B EF F5 FF FF FF ../FaJLp..K.....<br />
0000D0 FF 02 40 4B 4C 00 00 00 00 00 19 76 A9 14 1A A0 ..@KL......v....<br />
0000E0 CD 1C BE A6 E7 45 8A 7A BA D5 12 A9 D9 EA 1A FB .....E.z........<br />
0000F0 22 5E 88 AC 80 FA E9 C7 00 00 00 00 19 76 A9 14 "^...........v..<br />
000100 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E FD A0 B7 ..[.Cj.....H^...<br />
000110 8B 4E CC 52 88 AC 00 00 00 00 .N.R......<br />
<br />
<br />
Message header:<br />
F9 BE B4 D9 - main network magic bytes<br />
74 78 00 00 00 00 00 00 00 00 00 00 - "tx" command<br />
02 01 00 00 - payload is 258 bytes long<br />
E2 93 CD BE - checksum of payload<br />
<br />
Transaction:<br />
01 00 00 00 - version<br />
<br />
Inputs:<br />
01 - number of transaction inputs<br />
<br />
Input 1:<br />
6D BD DB 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D - previous output (outpoint)<br />
12 66 E9 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29<br />
00 00 00 00<br />
<br />
8B - script is 139 bytes long<br />
<br />
48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 C7 36 - signature script (scriptSig)<br />
7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A 59 23<br />
3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 0E 41<br />
83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D 35 BD<br />
96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF C9 7E<br />
F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 2A CD<br />
2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC 4E 02<br />
53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F 14 04<br />
2F 46 61 4A 4C 70 C0 F1 4B EF F5<br />
<br />
FF FF FF FF - sequence<br />
<br />
Outputs:<br />
02 - 2 Output Transactions<br />
<br />
Output 1:<br />
40 4B 4C 00 00 00 00 00 - 0.05 BTC (5000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 1A A0 CD 1C BE A6 E7 45 8A 7A BA D5 12 - pk_script<br />
A9 D9 EA 1A FB 22 5E 88 AC<br />
<br />
Output 2:<br />
80 FA E9 C7 00 00 00 00 - 33.54 BTC (3354000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E - pk_script<br />
FD A0 B7 8B 4E CC 52 88 AC<br />
<br />
Locktime:<br />
00 00 00 00 - lock time<br />
</pre><br />
<br />
=== block ===<br />
<br />
The '''block''' message is sent in response to a getdata message which requests transaction information from a block hash.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A Unix timestamp recording when this block was created (Currently limited to dates before the year 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated [[Difficulty|difficulty target]] being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| ? || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries<br />
|-<br />
| ? || txns || tx[] || Block transactions, in format of "tx" command<br />
|}<br />
<br />
The SHA256 hash that identifies each block (and which must have a run of 0 bits) is calculated from the first 6 fields of this structure (version, prev_block, merkle_root, timestamp, bits, nonce, and standard SHA256 padding, making two 64-byte chunks in all) and ''not'' from the complete block. To calculate the hash, only two chunks need to be processed by the SHA256 algorithm. Since the ''nonce'' field is in the second chunk, the first chunk stays constant during mining and therefore only the second chunk needs to be processed. However, a Bitcoin hash is the hash of the hash, so two SHA256 rounds are needed for each mining iteration.<br />
See [[Block hashing algorithm]] for details and an example.<br />
<br />
=== headers ===<br />
<br />
The ''headers'' packet returns block headers in response to a ''getheaders'' packet. <br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of block headers<br />
|-<br />
| 81x? || headers || [[Protocol_documentation#Block_Headers|block_header]][] || [[Protocol_documentation#Block_Headers|Block headers]]<br />
|}<br />
<br />
Note that the block headers in this packet include a transaction count (a var_int, so there can be more than 81 bytes per header) as opposed to the block headers that are hashed by miners.<br />
<br />
=== getaddr ===<br />
<br />
The getaddr message sends a request to a node asking for information about known active peers to help with finding potential nodes in the network. The response to receiving this message is to transmit one or more addr messages with one or more peers from a database of known active peers. The typical presumption is that a node is likely to be active if it has been sending a message within the last three hours.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
=== mempool ===<br />
<br />
The mempool message sends a request to a node asking for information about transactions it has verified but which have not yet confirmed. The response to receiving this message is an inv message containing the transaction hashes for all the transactions in the node's mempool.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
It is specified in [https://github.com/bitcoin/bips/blob/master/bip-0035.mediawiki BIP 35]. Since [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 37], if a [[Protocol_documentation#filterload.2C_filteradd.2C_filterclear.2C_merkleblock|bloom filter]] is loaded, only transactions matching the filter are replied.<br />
<br />
=== checkorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== submitorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== reply ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== ping ===<br />
<br />
The ''ping'' message is sent primarily to confirm that the TCP/IP connection is still valid. An error in transmission is presumed to be a closed connection and the address is removed as a current peer.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || random nonce<br />
|}<br />
<br />
=== pong ===<br />
<br />
The ''pong'' message is sent in response to a ''ping'' message. In modern protocol versions, a ''pong'' response is generated using a nonce included in the ping.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || nonce from ping<br />
|}<br />
<br />
<br />
=== reject===<br />
<br />
The ''reject'' message is sent when messages are rejected.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || message || var_str || type of message rejected<br />
|-<br />
| 1 || ccode || char || code relating to rejected message<br />
|-<br />
| 1+ || reason || var_str || text version of reason for rejection<br />
|-<br />
| 0+ || data || char || Optional extra data provided by some errors. Currently, all errors which provide this field fill it with the TXID or block header hash of the object being rejected, so the field is 32 bytes.<br />
|}<br />
<br />
CCodes<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0x01 || REJECT_MALFORMED|| <br />
|-<br />
| 0x10 || REJECT_INVALID ||<br />
|-<br />
| 0x11 || REJECT_OBSOLETE ||<br />
|-<br />
| 0x12 || REJECT_DUPLICATE ||<br />
|-<br />
| 0x40 || REJECT_NONSTANDARD ||<br />
|-<br />
| 0x41 || REJECT_DUST ||<br />
|-<br />
| 0x42 || REJECT_INSUFFICIENTFEE ||<br />
|-<br />
| 0x43 || REJECT_CHECKPOINT ||<br />
|}<br />
<br />
=== filterload, filteradd, filterclear, merkleblock ===<br />
<br />
These messages are related to Bloom filtering of connections and are defined in [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037].<br />
<br />
<br />
The <code>filterload</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || filter || uint8_t[] || The filter itself is simply a bit field of arbitrary byte-aligned size. The maximum size is 36,000 bytes.<br />
|-<br />
| 4 || nHashFuncs || uint32_t || The number of hash functions to use in this filter. The maximum value allowed in this field is 50.<br />
|-<br />
| 4 || nTweak || uint32_t || A random value to add to the seed value in the hash function used by the bloom filter.<br />
|-<br />
| 1 || nFlags || uint8_t || A set of flags that control how matched items are added to the filter.<br />
|}<br />
<br />
See below for a description of the Bloom filter algorithm and how to select nHashFuncs and filter size for a desired false positive rate.<br />
<br />
Upon receiving a <code>filterload</code> command, the remote peer will immediately restrict the broadcast transactions it announces (in inv packets) to transactions matching the filter, where the matching algorithm is specified below. The flags control the update behaviour of the matching algorithm.<br />
<br />
The <code>filteradd</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || data || uint8_t[] || The data element to add to the current filter.<br />
|}<br />
<br />
The data field must be smaller than or equal to 520 bytes in size (the maximum size of any potentially matched object).<br />
<br />
The given data element will be added to the Bloom filter. A filter must have been previously provided using <code>filterload</code>. This command is useful if a new key or script is added to a clients wallet whilst it has connections to the network open, it avoids the need to re-calculate and send an entirely new filter to every peer (though doing so is usually advisable to maintain anonymity).<br />
<br />
The <code>filterclear</code> command has no arguments at all.<br />
<br />
After a filter has been set, nodes don't merely stop announcing non-matching transactions, they can also serve filtered blocks. A filtered block is defined by the <code>merkleblock</code> message and is defined like this:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information, based upon the software version creating this block (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Limited to 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 4 || total_transactions || uint32_t || Number of transactions in the block (including unmatched ones)<br />
|-<br />
| ? || hashes || uint256[] || hashes in depth-first order (including standard varint size prefix)<br />
|-<br />
| ? || flags || byte[] || flag bits, packed per 8 in a byte, least significant bit first (including standard varint size prefix)<br />
|}<br />
<br />
=== alert ===<br />
<br />
An '''alert''' is sent between nodes to send a general notification message throughout the network. If the alert can be confirmed with the signature as having come from the core development group of the Bitcoin software, the message is suggested to be displayed for end-users. Attempts to perform transactions, particularly automated transactions through the client, are suggested to be halted. The text in the Message string should be relayed to log files and any user interfaces.<br />
<br />
Alert format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || payload || uchar[] || Serialized alert payload<br />
|-<br />
| ? || signature || uchar[] || An ECDSA signature of the message<br />
|}<br />
<br />
The developers of Satoshi's client use this public key for signing alerts:<br />
04fc9702847840aaf195de8442ebecedf5b095cdbb9bc716bda9110971b28a49e0ead8564ff0db22209e0374782c093bb899692d524e9d6a6956e7c5ecbcd68284<br />
(hash) 1AGRxqDa5WjUKBwHB9XYEjmkv1ucoUUy1s<br />
<br />
The payload is serialized into a uchar[] to ensure that versions using incompatible alert formats can still relay alerts among one another. The current alert payload format is:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || Version || int32_t || Alert format version<br />
|-<br />
| 8 || RelayUntil || int64_t || The timestamp beyond which nodes should stop relaying this alert<br />
|-<br />
| 8 || Expiration || int64_t || The timestamp beyond which this alert is no longer in effect and should be ignored<br />
|-<br />
| 4 || ID || int32_t || A unique ID number for this alert<br />
|-<br />
| 4 || Cancel || int32_t || All alerts with an ID number less than or equal to this number should be cancelled: deleted and not accepted in the future<br />
|-<br />
| ? || setCancel || set<int32_t> || All alert IDs contained in this set should be cancelled as above<br />
|-<br />
| 4 || MinVer || int32_t || This alert only applies to versions greater than or equal to this version. Other versions should still relay it.<br />
|-<br />
| 4 || MaxVer || int32_t || This alert only applies to versions less than or equal to this version. Other versions should still relay it.<br />
|-<br />
| ? || setSubVer || set<string> || If this set contains any elements, then only nodes that have their subVer contained in this set are affected by the alert. Other versions should still relay it.<br />
|-<br />
| 4 || Priority || int32_t || Relative priority compared to other alerts<br />
|-<br />
| ? || Comment || string || A comment on the alert that is not displayed<br />
|-<br />
| ? || StatusBar || string || The alert message that is displayed to the user<br />
|-<br />
| ? || Reserved || string || Reserved<br />
|}<br />
<br />
Note: '''set<''type''>''' in the table above is a [[#Variable length integer | variable length integer]] followed by the number of fields of the given ''type'' (either int32_t or [[#Variable length string | variable length string]])<br />
<br />
Sample alert (no message header):<br />
73010000003766404f00000000b305434f00000000f2030000f1030000001027000048ee0000<br />
0064000000004653656520626974636f696e2e6f72672f666562323020696620796f75206861<br />
76652074726f75626c6520636f6e6e656374696e672061667465722032302046656272756172<br />
79004730450221008389df45f0703f39ec8c1cc42c13810ffcae14995bb648340219e353b63b<br />
53eb022009ec65e1c1aaeec1fd334c6b684bde2b3f573060d5b70c3a46723326e4e8a4f1<br />
<br />
Version: 1<br />
RelayUntil: 1329620535<br />
Expiration: 1329792435<br />
ID: 1010<br />
Cancel: 1009<br />
setCancel: <empty><br />
MinVer: 10000<br />
MaxVer: 61000<br />
setSubVer: <empty><br />
Priority: 100<br />
Comment: <empty><br />
StatusBar: "See bitcoin.org/feb20 if you have trouble connecting after 20 February"<br />
Reserved: <empty><br />
<br />
=== sendheaders ===<br />
<br />
Request for Direct headers announcement. <br />
<br />
Upon receipt of this message, the node is be permitted, but not required, to announce new blocks by '''headers''' command (instead of '''inv''' command).<br />
<br />
This message is supported by the protocol version >= 70012 or Bitcoin Core version >= 0.12.0.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0130.mediawiki BIP 130] for more information.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
<br />
=== feefilter ===<br />
<br />
The payload is always 8 bytes long and it encodes 64 bit integer value (LSB / little endian) of '''feerate'''.<br />
The value represents a minimal fee and is expressed in satoshis per 1000 bytes.<br />
<br />
Upon receipt of a "feefilter" message, the node will be permitted, but not required, to filter transaction invs for transactions that fall below the feerate provided in the feefilter message interpreted as satoshis per kilobyte.<br />
<br />
The fee filter is additive with a bloom filter for transactions so if an SPV client were to load a bloom filter and send a feefilter message, transactions would only be relayed if they passed both filters.<br />
<br />
Inv's generated from a mempool message are also subject to a fee filter if it exists.<br />
<br />
Feature discovery is enabled by checking protocol version >= 70013<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0133.mediawiki BIP 133] for more information.<br />
<br />
=== sendcmpct ===<br />
<br />
# The sendcmpct message is defined as a message containing a 1-byte integer followed by a 8-byte integer where pchCommand == "sendcmpct".<br />
# The first integer SHALL be interpreted as a boolean (and MUST have a value of either 1 or 0)<br />
# The second integer SHALL be interpreted as a little-endian version number. Nodes sending a sendcmpct message MUST currently set this value to 1.<br />
# Upon receipt of a "sendcmpct" message with the first and second integers set to 1, the node SHOULD announce new blocks by sending a cmpctblock message.<br />
# Upon receipt of a "sendcmpct" message with the first integer set to 0, the node SHOULD NOT announce new blocks by sending a cmpctblock message, but SHOULD announce new blocks by sending invs or headers, as defined by BIP130.<br />
# Upon receipt of a "sendcmpct" message with the second integer set to something other than 1, nodes MUST treat the peer as if they had not received the message (as it indicates the peer will provide an unexpected encoding in <br />
# cmpctblock, and/or other, messages). This allows future versions to send duplicate sendcmpct messages with different versions as a part of a version handshake for future versions.<br />
# Nodes SHOULD check for a protocol version of >= 70014 before sending sendcmpct messages.<br />
# Nodes MUST NOT send a request for a MSG_CMPCT_BLOCK object to a peer before having received a sendcmpct message from that peer.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== cmpctblock ===<br />
<br />
# The cmpctblock message is defined as as a message containing a serialized HeaderAndShortIDs message and pchCommand == "cmpctblock".<br />
# Upon receipt of a cmpctblock message after sending a sendcmpct message, nodes SHOULD calculate the short transaction ID for each unconfirmed transaction they have available (ie in their mempool) and compare each to each short transaction ID in the cmpctblock message.<br />
# After finding already-available transactions, nodes which do not have all transactions available to reconstruct the full block SHOULD request the missing transactions using a getblocktxn message.<br />
# A node MUST NOT send a cmpctblock message unless they are able to respond to a getblocktxn message which requests every transaction in the block.<br />
# A node MUST NOT send a cmpctblock message without having validated that the header properly commits to each transaction in the block, and properly builds on top of the existing chain with a valid proof-of-work. A node MAY send a cmpctblock before validating that each transaction in the block validly spends existing UTXO set entries.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== getblocktxn ===<br />
<br />
# The getblocktxn message is defined as as a message containing a serialized BlockTransactionsRequest message and pchCommand == "getblocktxn".<br />
# Upon receipt of a properly-formatted getblocktxnmessage, nodes which recently provided the sender of such a message a cmpctblock for the block hash identified in this message MUST respond with an appropriate blocktxn message. Such a blocktxn message MUST contain exactly and only each transaction which is present in the appropriate block at the index specified in the getblocktxn indexes list, in the order requested.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== blocktxn ===<br />
<br />
# The blocktxn message is defined as as a message containing a serialized BlockTransactions message and pchCommand == "blocktxn".<br />
# Upon receipt of a properly-formatted requested blocktxn message, nodes SHOULD attempt to reconstruct the full block by:<br />
# Taking the prefilledtxn transactions from the original cmpctblock and placing them in the marked positions.<br />
# For each short transaction ID from the original cmpctblock, in order, find the corresponding transaction either from the blocktxn message or from other sources and place it in the first available position in the block.<br />
# Once the block has been reconstructed, it shall be processed as normal, keeping in mind that short transaction IDs are expected to occasionally collide, and that nodes MUST NOT be penalized for such collisions, wherever they # appear.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
== Scripting ==<br />
<br />
See [[script]].<br />
<br />
==See Also==<br />
<br />
* [[Network]]<br />
* [[Protocol rules]]<br />
* [[Hardfork Wishlist]]<br />
* [https://bitcoin.org/en/developer-documentation Developer Documentation on bitcoin.org]<br />
* Bitcoin dissectors for Wireshark: https://github.com/lbotsch/wireshark-bitcoin https://github.com/op-sig/bitcoin-wireshark-dissector<br />
<br />
==References==<br />
<references /><br />
<br />
[[zh-cn:协议说明]]<br />
[[Category:Technical]]<br />
[[Category:Developer]]<br />
<br />
{{Bitcoin Core documentation}}</div>Tonikthttps://en.bitcoin.it/w/index.php?title=Protocol_documentation&diff=61485Protocol documentation2016-08-25T12:32:33Z<p>Tonikt: /* PrefilledTransaction */</p>
<hr />
<div>This page ''describes'' the behavior of the [[Original Bitcoin client|reference client]]. The Bitcoin protocol is specified by the behavior of the reference client, not by this page. In particular, while this page is quite complete in describing the network protocol, it does not attempt to list all of the rules for block or transaction validity.<br />
<br />
Type names used in this documentation are from the C99 standard.<br />
<br />
For protocol used in mining, see [[getblocktemplate]].<br />
<br />
==Common standards==<br />
<br />
=== Hashes ===<br />
<br />
Usually, when a hash is computed within bitcoin, it is computed twice. Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-256] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when a shorter hash is desirable (for example when creating a bitcoin address).<br />
<br />
Example of double-SHA-256 encoding of string "hello":<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round of sha-256)<br />
9595c9df90075148eb06860365df33584b75bff782a510c6cd4883a419833d50 (second round of sha-256)<br />
<br />
For bitcoin addresses (RIPEMD-160) this would give:<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round is sha-256)<br />
b6a9c8c230722b7c748331a8b450f05566dc7d0f (with ripemd-160)<br />
<br />
=== Merkle Trees ===<br />
<br />
Merkle trees are binary trees of hashes. Merkle trees in bitcoin use a '''double''' SHA-256, the SHA-256 hash of the SHA-256 hash of something.<br />
<br />
If, when forming a row in the tree (other than the root of the tree), it would have an odd number of elements, the final double-hash is duplicated to ensure that the row has an even number of hashes.<br />
<br />
First form the bottom row of the tree with the ordered double-SHA-256 hashes of the byte streams of the transactions in the block.<br />
<br />
Then the row above it consists of half that number of hashes. Each entry is the double-SHA-256 of the 64-byte concatenation of the corresponding two hashes below it in the tree.<br />
<br />
This procedure repeats recursively until we reach a row consisting of just a single double-hash. This is the '''Merkle root''' of the tree.<br />
<br />
For example, imagine a block with three transactions ''a'', ''b'' and ''c''. The Merkle tree is: <br />
<br />
d1 = dhash(a)<br />
d2 = dhash(b)<br />
d3 = dhash(c)<br />
d4 = dhash(c) # a, b, c are 3. that's an odd number, so we take the c twice<br />
<br />
d5 = dhash(d1 concat d2)<br />
d6 = dhash(d3 concat d4)<br />
<br />
d7 = dhash(d5 concat d6)<br />
<br />
where<br />
<br />
dhash(a) = sha256(sha256(a))<br />
<br />
''d7'' is the Merkle root of the 3 transactions in this block.<br />
<br />
Note: Hashes in Merkle Tree displayed in the [[Block Explorer]] are of little-endian notation. For some implementations and [http://www.fileformat.info/tool/hash.htm calculations], the bits need to be reversed before they are hashed, and again after the hashing operation.<br />
<br />
=== Signatures ===<br />
<br />
Bitcoin uses [http://en.wikipedia.org/wiki/Elliptic_curve_cryptography Elliptic Curve] [http://en.wikipedia.org/wiki/Digital_Signature_Algorithm Digital Signature Algorithm] ([http://en.wikipedia.org/wiki/Elliptic_Curve_DSA ECDSA]) to sign transactions. <br />
<br />
For [[ECDSA]] the secp256k1 curve from http://www.secg.org/collateral/sec2_final.pdf is used.<br />
<br />
Public keys (in scripts) are given as 04 <x> <y> where ''x'' and ''y'' are 32 byte big-endian integers representing the coordinates of a point on the curve or in compressed form given as <sign> <x> where <sign> is 0x02 if ''y'' is even and 0x03 if ''y'' is odd.<br />
<br />
Signatures use [http://en.wikipedia.org/wiki/Distinguished_Encoding_Rules DER encoding] to pack the ''r'' and ''s'' components into a single byte stream (this is also what OpenSSL produces by default).<br />
<br />
=== Transaction Verification ===<br />
Transactions are cryptographically signed records that reassign ownership of Bitcoins to new addresses. Transactions have ''inputs'' - records which reference the funds from other previous transactions - and ''outputs'' - records which determine the new owner of the transferred Bitcoins, and which will be referenced as inputs in future transactions as those funds are respent.<br />
<br />
Each ''input'' must have a cryptographic digital signature that unlocks the funds from the prior transaction. Only the person possessing the appropriate [[private key]] is able to create a satisfactory signature; this in effect ensures that funds can only be spent by their owners.<br />
<br />
Each ''output'' determines which Bitcoin address (or other criteria, see [[Script]]) is the recipient of the funds.<br />
<br />
In a transaction, the sum of all inputs must be equal to or greater than the sum of all outputs. If the inputs exceed the outputs, the difference is considered a [[transaction fee]], and is redeemable by whoever first includes the transaction into the block chain.<br />
<br />
A special kind of transaction, called a [[coinbase transaction]], has no inputs. It is created by [[miners]], and there is one coinbase transaction per block. Because each block comes with a reward of newly created Bitcoins (e.g. 50 BTC for the first 210,000 blocks), the first transaction of a block is, with few exceptions, the transaction that grants those coins to their recipient (the miner). In addition to the newly created Bitcoins, the coinbase transaction is also used for assigning the recipient of any transaction fees that were paid within the other transactions being included in the same block. The coinbase transaction can assign the entire reward to a single Bitcoin address, or split it in portions among multiple addresses, just like any other transaction. Coinbase transactions always contain outputs totalling the sum of the block reward plus all transaction fees collected from the other transactions in the same block.<br />
<br />
The [[coinbase transaction]] in block zero cannot be spent. This is due to a quirk of the reference client implementation that would open the potential for a block chain fork if some nodes accepted the spend and others did not<ref>[http://bitcointalk.org/index.php?topic=119645.msg1288552#msg1288552 Block 0 Network Fork]</ref>.<br />
<br />
Most Bitcoin outputs encumber the newly transferred coins with a single ECDSA private key. The actual record saved with inputs and outputs isn't necessarily a key, but a ''script''. Bitcoin uses an interpreted scripting system to determine whether an output's criteria have been satisfied, with which more complex operations are possible, such as outputs that require two ECDSA signatures, or two-of-three-signature schemes. An output that references a single Bitcoin address is a ''typical'' output; an output actually contains this information in the form of a script that requires a single ECDSA signature (see [[OP_CHECKSIG]]). The output script specifies what must be provided to unlock the funds later, and when the time comes in the future to spend the transaction in another input, that input must provide all of the thing(s) that satisfy the requirements defined by the original output script.<br />
<br />
=== Addresses ===<br />
<br />
A bitcoin address is in fact the hash of a ECDSA public key, computed this way:<br />
<br />
Version = 1 byte of 0 (zero); on the test network, this is 1 byte of 111<br />
Key hash = Version concatenated with RIPEMD-160(SHA-256(public key))<br />
Checksum = 1st 4 bytes of SHA-256(SHA-256(Key hash))<br />
Bitcoin Address = Base58Encode(Key hash concatenated with Checksum)<br />
<br />
The Base58 encoding used is home made, and has some differences. Especially, leading zeroes are kept as single zeroes when conversion happens.<br />
<br />
== Common structures ==<br />
<br />
Almost all integers are encoded in little endian. Only IP or port number are encoded big endian.<br />
<br />
=== Message structure ===<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown<br />
|-<br />
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| 4 || length || uint32_t || Length of payload in number of bytes<br />
|-<br />
| 4 || checksum || uint32_t || First 4 bytes of sha256(sha256(payload))<br />
|-<br />
| ? || payload || uchar[] || The actual data<br />
|}<br />
<br />
<br />
Known magic values:<br />
<br />
{|class="wikitable"<br />
! Network !! Magic value !! Sent over wire as<br />
|-<br />
| main || 0xD9B4BEF9 || F9 BE B4 D9<br />
|-<br />
| testnet || 0xDAB5BFFA || FA BF B5 DA<br />
|-<br />
| testnet3 || 0x0709110B || 0B 11 09 07<br />
|-<br />
| namecoin || 0xFEB4BEF9 || F9 BE B4 FE<br />
|}<br />
<br />
=== Variable length integer ===<br />
<br />
Integer can be encoded depending on the represented value to save space.<br />
Variable length integers always precede an array/vector of a type of data that may vary in length.<br />
Longer numbers are encoded in little endian.<br />
<br />
{|class="wikitable"<br />
! Value !! Storage length !! Format<br />
|-<br />
| < 0xFD || 1 || uint8_t<br />
|-<br />
| <= 0xFFFF || 3 || 0xFD followed by the length as uint16_t<br />
|-<br />
| <= 0xFFFF FFFF || 5 || 0xFE followed by the length as uint32_t<br />
|-<br />
| - || 9 || 0xFF followed by the length as uint64_t<br />
|}<br />
<br />
If you're reading the Satoshi client code (BitcoinQT) it refers to this encoding as a "CompactSize". Modern BitcoinQT also has the CVarInt class which implements an even more compact integer for the purpose of local storage (which is incompatible with "CompactSize" described here). CVarInt is not a part of the protocol.<br />
<br />
=== Variable length string ===<br />
<br />
Variable length string can be stored using a variable length integer followed by the string itself.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the string<br />
|-<br />
| ? || string || char[] || The string itself (can be empty)<br />
|}<br />
<br />
=== Network address ===<br />
<br />
When a network address is needed somewhere, this structure is used. Network addresses are not prefixed with a timestamp in the version message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || time || uint32 || the Time (version >= 31402). '''Not present in version message.'''<br />
|-<br />
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]<br />
|-<br />
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The original client only supported IPv4 and only read the last 4 bytes to get the IPv4 address. However, the IPv4 address is written into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]<br />
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).<br />
|-<br />
| 2 || port || uint16_t || port number, network byte order<br />
|}<br />
<br />
Hexdump example of Network address structure<br />
<br />
<pre><br />
0000 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0010 00 00 FF FF 0A 00 00 01 20 8D ........ .<br />
<br />
Network address:<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK: see services listed under version command)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv6: ::ffff:a00:1 or IPv4: 10.0.0.1<br />
20 8D - Port 8333<br />
</pre><br />
<br />
=== Inventory Vectors ===<br />
<br />
Inventory vectors are used for notifying other nodes about objects they have or data which is being requested.<br />
<br />
Inventory vectors consist of the following data format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || type || uint32_t || Identifies the object type linked to this inventory<br />
|-<br />
| 32 || hash || char[32] || Hash of the object<br />
|}<br />
<br />
<br />
The object type is currently defined as one of the following possibilities:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0 || ERROR || Any data of with this number may be ignored<br />
|-<br />
| 1 || MSG_TX || Hash is related to a transaction<br />
|-<br />
| 2 || MSG_BLOCK || Hash is related to a data block<br />
|-<br />
| 3 || MSG_FILTERED_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a merkleblock message rather than a block message; this only works if a bloom filter has been set.<br />
|-<br />
| 4 || MSG_CMPCT_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a cmpctblock message. See BIP 152 for more info.<br />
|}<br />
<br />
Other Data Type values are considered reserved for future implementations.<br />
<br />
=== Block Headers ===<br />
<br />
Block headers are sent in a headers packet in response to a getheaders message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Will overflow in 2106<ref>https://en.wikipedia.org/wiki/Unix_time#Notable_events_in_Unix_time</ref>)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 1 || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries, this value is always 0<br />
|}<br />
<br />
cf. [[Block hashing algorithm]]<br />
<br />
=== PrefilledTransaction ===<br />
<br />
A PrefilledTransaction structure is used in HeaderAndShortIDs to provide a list of a few transactions explicitly.<br />
<br />
{|class="wikitable"<br />
! Field Name !! Type !! Size !! Encoding || Purpose<br />
|-<br />
| index || CompactSize || 1, 3 bytes || Compact Size, differentially encoded since the last PrefilledTransaction in a list || The index into the block at which this transaction is<br />
|-<br />
| tx || Transaction || variable || As encoded in "tx" messages || The transaction which is in the block at index index.<br />
|}<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== HeaderAndShortIDs ===<br />
<br />
A HeaderAndShortIDs structure is used to relay a block header, the short transactions IDs used for matching already-available transactions, and a select few transactions which we expect a peer may be missing.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== BlockTransactionsRequest ===<br />
<br />
A BlockTransactionsRequest structure is used to list transaction indexes in a block being requested.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== BlockTransactions ===<br />
<br />
A BlockTransactions structure is used to provide some of the transactions in a block, as requested.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== Short transaction IDs ===<br />
<br />
Short transaction IDs are used to represent a transaction without sending a full 256-bit hash. They are calculated by:<br />
<br />
# single-SHA256 hashing the block header with the nonce appended (in little-endian)<br />
# Running SipHash-2-4 with the input being the transaction ID and the keys (k0/k1) set to the first two little-endian 64-bit integers from the above hash, respectively.<br />
# Dropping the 2 most significant bytes from the SipHash output to make it 6 bytes.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
== Message types ==<br />
<br />
=== version ===<br />
<br />
When a node creates an outgoing connection, it will immediately [[Version Handshake|advertise]] its version. The remote node will respond with its version. No further communication is possible until both peers have exchanged their version.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Identifies protocol version being used by the node<br />
|-<br />
| 8 || services || uint64_t || bitfield of features to be enabled for this connection<br />
|-<br />
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds<br />
|-<br />
| 26 || addr_recv || [[#Network address|net_addr]] || The network address of the node receiving this message<br />
|-<br />
|colspan="4"| Fields below require version ≥ 106<br />
|-<br />
| 26 || addr_from || [[#Network address|net_addr]] || The network address of the node emitting this message<br />
|-<br />
| 8 || nonce || uint64_t || Node random nonce, randomly generated every time a version packet is sent. This nonce is used to detect connections to self.<br />
|-<br />
| ? || user_agent || [[#Variable length string|var_str]] || [https://github.com/bitcoin/bips/blob/master/bip-0014.mediawiki User Agent] (0x00 if string is 0 bytes long)<br />
|-<br />
| 4 || start_height || int32_t || The last block received by the emitting node<br />
|-<br />
|colspan="4"| Fields below require version ≥ 70001<br />
|-<br />
| 1 || relay || bool || Whether the remote peer should announce relayed transactions or not, see [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037]<br />
|}<br />
<br />
A "verack" packet shall be sent if the version packet was accepted.<br />
<br />
The following services are currently assigned:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 1 || NODE_NETWORK || This node can be asked for full blocks instead of just headers.<br />
|}<br />
<br />
Hexdump example of version message (OBSOLETE EXAMPLE: This example lacks a checksum and user-agent):<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....<br />
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........<br />
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............<br />
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................<br />
0040 20 8D 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,<br />
0060 3A B4 57 13 00 55 81 01 00 :.W..U...<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
55 00 00 00 - Payload is 85 bytes long<br />
- No checksum in version message until 20 February 2012. See https://bitcointalk.org/index.php?topic=55852.0<br />
Version message:<br />
9C 7C 00 00 - 31900 (version 0.3.19)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
E6 15 10 4D 00 00 00 00 - Mon Dec 20 21:50:14 EST 2010<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 20 8D - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D - Sender address info - see Network Address<br />
DD 9D 20 2C 3A B4 57 13 - Node random unique ID<br />
00 - "" sub-version string (string is 0 bytes long)<br />
55 81 01 00 - Last block sending node has is block #98645<br />
</pre><br />
<br />
And here's a modern (60002) protocol version client advertising itself to a local peer...<br />
<br />
Newer protocol includes the checksum now, this is from a mainline (satoshi) client during <br />
an outgoing connection to another local client, notice that it does not fill out the <br />
address information at all when the source or destination is "unroutable".<br />
<br />
<pre><br />
<br />
0000 f9 be b4 d9 76 65 72 73 69 6f 6e 00 00 00 00 00 ....version.....<br />
0010 64 00 00 00 35 8d 49 32 62 ea 00 00 01 00 00 00 d...5.I2b.......<br />
0020 00 00 00 00 11 b2 d0 50 00 00 00 00 01 00 00 00 .......P........<br />
0030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ff ff ................<br />
0040 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 00 00 00 00 ff ff 00 00 00 00 00 00 ................<br />
0060 3b 2e b3 5d 8c e6 17 65 0f 2f 53 61 74 6f 73 68 ;..]...e./Satosh<br />
0070 69 3a 30 2e 37 2e 32 2f c0 3e 03 00 i:0.7.2/.>..<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
64 00 00 00 - Payload is 100 bytes long<br />
3B 64 8D 5A - payload checksum<br />
<br />
Version message:<br />
62 EA 00 00 - 60002 (protocol version 60002)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
11 B2 D0 50 00 00 00 00 - Tue Dec 18 10:12:33 PST 2012<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Sender address info - see Network Address<br />
3B 2E B3 5D 8C E6 17 65 - Node ID<br />
0F 2F 53 61 74 6F 73 68 69 3A 30 2E 37 2E 32 2F - "/Satoshi:0.7.2/" sub-version string (string is 15 bytes long)<br />
C0 3E 03 00 - Last block sending node has is block #212672<br />
</pre><br />
<br />
=== verack ===<br />
<br />
The ''verack'' message is sent in reply to ''[[#version|version]]''. This message consists of only a [[#Message structure|message header]] with the command string "verack".<br />
<br />
Hexdump of the verack message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......<br />
0010 00 00 00 00 5D F6 E0 E2 ........<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 61 63 6B 00 00 00 00 00 00 - "verack" command<br />
00 00 00 00 - Payload is 0 bytes long<br />
5D F6 E0 E2 - Checksum<br />
</pre><br />
<br />
=== addr ===<br />
<br />
Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours<br />
<br />
Payload:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of address entries (max: 1000)<br />
|-<br />
| 30x? || addr_list || (uint32_t + [[#Network address|net_addr]])[] || Address of other nodes on the network. version < 209 will only read the first one. The uint32_t is a timestamp (see note below).<br />
|}<br />
<br />
'''Note''': Starting version 31402, addresses are prefixed with a timestamp. If no timestamp is present, the addresses should not be relayed to other peers, unless it is indeed confirmed they are up.<br />
<br />
Hexdump example of ''addr'' message:<br />
<pre><br />
0000 F9 BE B4 D9 61 64 64 72 00 00 00 00 00 00 00 00 ....addr........<br />
0010 1F 00 00 00 ED 52 39 9B 01 E2 15 10 4D 01 00 00 .....R9.....M...<br />
0020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF ................<br />
0030 FF 0A 00 00 01 20 8D ..... .<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
61 64 64 72 00 00 00 00 00 00 00 00 - "addr"<br />
1F 00 00 00 - payload is 31 bytes long<br />
ED 52 39 9B - checksum of payload<br />
<br />
Payload:<br />
01 - 1 address in this message<br />
<br />
Address:<br />
E2 15 10 4D - Mon Dec 20 21:50:10 EST 2010 (only when version is >= 31402)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK service - see version message)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv4: 10.0.0.1, IPv6: ::ffff:10.0.0.1 (IPv4-mapped IPv6 address)<br />
20 8D - port 8333<br />
</pre><br />
<br />
=== inv ===<br />
<br />
Allows a node to advertise its knowledge of one or more objects. It can be received unsolicited, or in reply to ''getblocks''.<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getdata ===<br />
<br />
getdata is used in response to inv, to retrieve the content of a specific object, and is usually sent after receiving an ''inv'' packet, after filtering known elements. It can be used to retrieve transactions, but only if they are in the memory pool or relay set - arbitrary access to transactions in the chain is not allowed to avoid having clients start to depend on nodes having full transaction indexes (which modern nodes do not).<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== notfound ===<br />
<br />
notfound is a response to a getdata, sent if any requested data items could not be relayed, for example, because the requested transaction was not in the memory pool or relay set.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getblocks ===<br />
<br />
Return an ''inv'' packet containing the list of blocks starting right after the last known hash in the block locator object, up to hash_stop or 500 blocks, whichever comes first. <br />
<br />
The locator hashes are processed by a node in the order as they appear in the message. If a block hash is found in the node's main chain, the list of its children is returned back via the ''inv'' message and the remaining locators are ignored, no matter if the requested limit was reached, or not.<br />
<br />
To receive the next blocks hashes, one needs to issue getblocks again with a new block locator object. Keep in mind that some clients may provide blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block; set to zero to get as many blocks as possible (500)<br />
|}<br />
<br />
To create the block locator hashes, keep pushing hashes until you go back to the genesis block. After pushing 10 hashes back, the step backwards doubles every loop:<br />
<br />
<pre><br />
// From libbitcoin which is under AGPL<br />
std::vector<size_t> block_locator_indexes(size_t top_height)<br />
{<br />
std::vector<size_t> indexes;<br />
<br />
// Modify the step in the iteration.<br />
int64_t step = 1;<br />
<br />
// Start at the top of the chain and work backwards.<br />
for (auto index = (int64_t)top_height; index > 0; index -= step)<br />
{<br />
// Push top 10 indexes first, then back off exponentially.<br />
if (indexes.size() >= 10)<br />
step *= 2;<br />
<br />
indexes.push_back((size_t)index);<br />
}<br />
<br />
// Push the genesis block index.<br />
indexes.push_back(0);<br />
return indexes;<br />
}<br />
</pre><br />
<br />
Note that it is allowed to send in fewer known hashes down to a minimum of just one hash. However, the purpose of the block locator object is to detect a wrong branch in the caller's main chain. If the peer detects that you are off the main chain, it will send in block hashes which are earlier than your last known block. So if you just send in your last known hash and it is off the main chain, the peer starts over at block #1.<br />
<br />
=== getheaders ===<br />
<br />
Return a ''headers'' packet containing the headers of blocks starting right after the last known hash in the block locator object, up to hash_stop or 2000 blocks, whichever comes first. To receive the next block headers, one needs to issue getheaders again with a new block locator object. The ''getheaders'' command is used by thin clients to quickly download the block chain where the contents of the transactions would be irrelevant (because they are not ours). Keep in mind that some clients may provide headers of blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block header; set to zero to get as many blocks as possible (2000)<br />
|}<br />
<br />
For the block locator object in this packet, the same rules apply as for the [[Protocol_documentation#getblocks|getblocks]] packet.<br />
<br />
=== tx ===<br />
<br />
''tx'' describes a bitcoin transaction, in reply to ''[[#getdata|getdata]]''<br />
<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Transaction data format version (note, this is signed)<br />
|-<br />
| 1+ || tx_in count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction inputs<br />
|-<br />
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins<br />
|-<br />
| 1+ || tx_out count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction outputs<br />
|-<br />
| 9+ || tx_out || tx_out[] || A list of 1 or more transaction outputs or destinations for coins<br />
|-<br />
| 4 || lock_time || uint32_t || The block number or timestamp at which this transaction is locked:<br />
{|class="wikitable"<br />
! Value !! Description<br />
|-<br />
| 0 || Not locked<br />
|-<br />
| < 500000000 || Block number at which this transaction is locked<br />
|-<br />
| >= 500000000 || UNIX timestamp at which this transaction is locked<br />
|}<br />
If all TxIn inputs have final (0xffffffff) sequence numbers then lock_time is irrelevant. Otherwise, the transaction may not be added to a block until after lock_time (see [[NLockTime]]).<br />
<br />
|}<br />
<br />
TxIn consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 36 || previous_output || outpoint || The previous output transaction reference, as an OutPoint structure<br />
|-<br />
| 1+ || script length || [[Protocol_documentation#Variable_length_integer|var_int]] || The length of the signature script<br />
|-<br />
| ? || signature script || uchar[] || Computational Script for confirming transaction authorization<br />
|-<br />
| 4 || [http://bitcoin.stackexchange.com/q/2025/323 sequence] || uint32_t || Transaction version as defined by the sender. Intended for "replacement" of transactions when information is updated before inclusion into a block.<br />
|}<br />
<br />
The OutPoint structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 32 || hash || char[32] || The hash of the referenced transaction.<br />
|-<br />
| 4 || index || uint32_t || The index of the specific output in the transaction. The first output is 0, etc.<br />
|}<br />
<br />
The Script structure consists of a series of pieces of information and operations related to the value of the transaction.<br />
<br />
(Structure to be expanded in the future… see script.h and script.cpp and [[Script]] for more information)<br />
<br />
The TxOut structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || value || int64_t || Transaction Value<br />
|-<br />
| 1+ || pk_script length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the pk_script<br />
|-<br />
| ? || pk_script || uchar[] || Usually contains the public key as a Bitcoin script setting up conditions to claim this output.<br />
|}<br />
<br />
Example ''tx'' message:<br />
<pre><br />
000000 F9 BE B4 D9 74 78 00 00 00 00 00 00 00 00 00 00 ....tx..........<br />
000010 02 01 00 00 E2 93 CD BE 01 00 00 00 01 6D BD DB .............m..<br />
000020 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D 12 66 E9 .[...Q........f.<br />
000030 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29 00 00 00 .;P......j.6)...<br />
000040 00 8B 48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 ..H0E.!..X..r...<br />
000050 C7 36 7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A .6zz%;..R#...h.:<br />
000060 59 23 3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 Y#?E.W... Y.....<br />
000070 0E 41 83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D .A.z.X.z...XN...<br />
000080 35 BD 96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF 5...6..;...A....<br />
000090 C9 7E F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 .~.6.m...@..!...<br />
0000A0 2A CD 2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC *.+..].}Y... ...<br />
0000B0 4E 02 53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F N.S..=7.o...Q...<br />
0000C0 14 04 2F 46 61 4A 4C 70 C0 F1 4B EF F5 FF FF FF ../FaJLp..K.....<br />
0000D0 FF 02 40 4B 4C 00 00 00 00 00 19 76 A9 14 1A A0 ..@KL......v....<br />
0000E0 CD 1C BE A6 E7 45 8A 7A BA D5 12 A9 D9 EA 1A FB .....E.z........<br />
0000F0 22 5E 88 AC 80 FA E9 C7 00 00 00 00 19 76 A9 14 "^...........v..<br />
000100 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E FD A0 B7 ..[.Cj.....H^...<br />
000110 8B 4E CC 52 88 AC 00 00 00 00 .N.R......<br />
<br />
<br />
Message header:<br />
F9 BE B4 D9 - main network magic bytes<br />
74 78 00 00 00 00 00 00 00 00 00 00 - "tx" command<br />
02 01 00 00 - payload is 258 bytes long<br />
E2 93 CD BE - checksum of payload<br />
<br />
Transaction:<br />
01 00 00 00 - version<br />
<br />
Inputs:<br />
01 - number of transaction inputs<br />
<br />
Input 1:<br />
6D BD DB 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D - previous output (outpoint)<br />
12 66 E9 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29<br />
00 00 00 00<br />
<br />
8B - script is 139 bytes long<br />
<br />
48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 C7 36 - signature script (scriptSig)<br />
7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A 59 23<br />
3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 0E 41<br />
83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D 35 BD<br />
96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF C9 7E<br />
F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 2A CD<br />
2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC 4E 02<br />
53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F 14 04<br />
2F 46 61 4A 4C 70 C0 F1 4B EF F5<br />
<br />
FF FF FF FF - sequence<br />
<br />
Outputs:<br />
02 - 2 Output Transactions<br />
<br />
Output 1:<br />
40 4B 4C 00 00 00 00 00 - 0.05 BTC (5000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 1A A0 CD 1C BE A6 E7 45 8A 7A BA D5 12 - pk_script<br />
A9 D9 EA 1A FB 22 5E 88 AC<br />
<br />
Output 2:<br />
80 FA E9 C7 00 00 00 00 - 33.54 BTC (3354000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E - pk_script<br />
FD A0 B7 8B 4E CC 52 88 AC<br />
<br />
Locktime:<br />
00 00 00 00 - lock time<br />
</pre><br />
<br />
=== block ===<br />
<br />
The '''block''' message is sent in response to a getdata message which requests transaction information from a block hash.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A Unix timestamp recording when this block was created (Currently limited to dates before the year 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated [[Difficulty|difficulty target]] being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| ? || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries<br />
|-<br />
| ? || txns || tx[] || Block transactions, in format of "tx" command<br />
|}<br />
<br />
The SHA256 hash that identifies each block (and which must have a run of 0 bits) is calculated from the first 6 fields of this structure (version, prev_block, merkle_root, timestamp, bits, nonce, and standard SHA256 padding, making two 64-byte chunks in all) and ''not'' from the complete block. To calculate the hash, only two chunks need to be processed by the SHA256 algorithm. Since the ''nonce'' field is in the second chunk, the first chunk stays constant during mining and therefore only the second chunk needs to be processed. However, a Bitcoin hash is the hash of the hash, so two SHA256 rounds are needed for each mining iteration.<br />
See [[Block hashing algorithm]] for details and an example.<br />
<br />
=== headers ===<br />
<br />
The ''headers'' packet returns block headers in response to a ''getheaders'' packet. <br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of block headers<br />
|-<br />
| 81x? || headers || [[Protocol_documentation#Block_Headers|block_header]][] || [[Protocol_documentation#Block_Headers|Block headers]]<br />
|}<br />
<br />
Note that the block headers in this packet include a transaction count (a var_int, so there can be more than 81 bytes per header) as opposed to the block headers that are hashed by miners.<br />
<br />
=== getaddr ===<br />
<br />
The getaddr message sends a request to a node asking for information about known active peers to help with finding potential nodes in the network. The response to receiving this message is to transmit one or more addr messages with one or more peers from a database of known active peers. The typical presumption is that a node is likely to be active if it has been sending a message within the last three hours.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
=== mempool ===<br />
<br />
The mempool message sends a request to a node asking for information about transactions it has verified but which have not yet confirmed. The response to receiving this message is an inv message containing the transaction hashes for all the transactions in the node's mempool.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
It is specified in [https://github.com/bitcoin/bips/blob/master/bip-0035.mediawiki BIP 35]. Since [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 37], if a [[Protocol_documentation#filterload.2C_filteradd.2C_filterclear.2C_merkleblock|bloom filter]] is loaded, only transactions matching the filter are replied.<br />
<br />
=== checkorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== submitorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== reply ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== ping ===<br />
<br />
The ''ping'' message is sent primarily to confirm that the TCP/IP connection is still valid. An error in transmission is presumed to be a closed connection and the address is removed as a current peer.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || random nonce<br />
|}<br />
<br />
=== pong ===<br />
<br />
The ''pong'' message is sent in response to a ''ping'' message. In modern protocol versions, a ''pong'' response is generated using a nonce included in the ping.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || nonce from ping<br />
|}<br />
<br />
<br />
=== reject===<br />
<br />
The ''reject'' message is sent when messages are rejected.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || message || var_str || type of message rejected<br />
|-<br />
| 1 || ccode || char || code relating to rejected message<br />
|-<br />
| 1+ || reason || var_str || text version of reason for rejection<br />
|-<br />
| 0+ || data || char || Optional extra data provided by some errors. Currently, all errors which provide this field fill it with the TXID or block header hash of the object being rejected, so the field is 32 bytes.<br />
|}<br />
<br />
CCodes<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0x01 || REJECT_MALFORMED|| <br />
|-<br />
| 0x10 || REJECT_INVALID ||<br />
|-<br />
| 0x11 || REJECT_OBSOLETE ||<br />
|-<br />
| 0x12 || REJECT_DUPLICATE ||<br />
|-<br />
| 0x40 || REJECT_NONSTANDARD ||<br />
|-<br />
| 0x41 || REJECT_DUST ||<br />
|-<br />
| 0x42 || REJECT_INSUFFICIENTFEE ||<br />
|-<br />
| 0x43 || REJECT_CHECKPOINT ||<br />
|}<br />
<br />
=== filterload, filteradd, filterclear, merkleblock ===<br />
<br />
These messages are related to Bloom filtering of connections and are defined in [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037].<br />
<br />
<br />
The <code>filterload</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || filter || uint8_t[] || The filter itself is simply a bit field of arbitrary byte-aligned size. The maximum size is 36,000 bytes.<br />
|-<br />
| 4 || nHashFuncs || uint32_t || The number of hash functions to use in this filter. The maximum value allowed in this field is 50.<br />
|-<br />
| 4 || nTweak || uint32_t || A random value to add to the seed value in the hash function used by the bloom filter.<br />
|-<br />
| 1 || nFlags || uint8_t || A set of flags that control how matched items are added to the filter.<br />
|}<br />
<br />
See below for a description of the Bloom filter algorithm and how to select nHashFuncs and filter size for a desired false positive rate.<br />
<br />
Upon receiving a <code>filterload</code> command, the remote peer will immediately restrict the broadcast transactions it announces (in inv packets) to transactions matching the filter, where the matching algorithm is specified below. The flags control the update behaviour of the matching algorithm.<br />
<br />
The <code>filteradd</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || data || uint8_t[] || The data element to add to the current filter.<br />
|}<br />
<br />
The data field must be smaller than or equal to 520 bytes in size (the maximum size of any potentially matched object).<br />
<br />
The given data element will be added to the Bloom filter. A filter must have been previously provided using <code>filterload</code>. This command is useful if a new key or script is added to a clients wallet whilst it has connections to the network open, it avoids the need to re-calculate and send an entirely new filter to every peer (though doing so is usually advisable to maintain anonymity).<br />
<br />
The <code>filterclear</code> command has no arguments at all.<br />
<br />
After a filter has been set, nodes don't merely stop announcing non-matching transactions, they can also serve filtered blocks. A filtered block is defined by the <code>merkleblock</code> message and is defined like this:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information, based upon the software version creating this block (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Limited to 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 4 || total_transactions || uint32_t || Number of transactions in the block (including unmatched ones)<br />
|-<br />
| ? || hashes || uint256[] || hashes in depth-first order (including standard varint size prefix)<br />
|-<br />
| ? || flags || byte[] || flag bits, packed per 8 in a byte, least significant bit first (including standard varint size prefix)<br />
|}<br />
<br />
=== alert ===<br />
<br />
An '''alert''' is sent between nodes to send a general notification message throughout the network. If the alert can be confirmed with the signature as having come from the core development group of the Bitcoin software, the message is suggested to be displayed for end-users. Attempts to perform transactions, particularly automated transactions through the client, are suggested to be halted. The text in the Message string should be relayed to log files and any user interfaces.<br />
<br />
Alert format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || payload || uchar[] || Serialized alert payload<br />
|-<br />
| ? || signature || uchar[] || An ECDSA signature of the message<br />
|}<br />
<br />
The developers of Satoshi's client use this public key for signing alerts:<br />
04fc9702847840aaf195de8442ebecedf5b095cdbb9bc716bda9110971b28a49e0ead8564ff0db22209e0374782c093bb899692d524e9d6a6956e7c5ecbcd68284<br />
(hash) 1AGRxqDa5WjUKBwHB9XYEjmkv1ucoUUy1s<br />
<br />
The payload is serialized into a uchar[] to ensure that versions using incompatible alert formats can still relay alerts among one another. The current alert payload format is:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || Version || int32_t || Alert format version<br />
|-<br />
| 8 || RelayUntil || int64_t || The timestamp beyond which nodes should stop relaying this alert<br />
|-<br />
| 8 || Expiration || int64_t || The timestamp beyond which this alert is no longer in effect and should be ignored<br />
|-<br />
| 4 || ID || int32_t || A unique ID number for this alert<br />
|-<br />
| 4 || Cancel || int32_t || All alerts with an ID number less than or equal to this number should be cancelled: deleted and not accepted in the future<br />
|-<br />
| ? || setCancel || set<int32_t> || All alert IDs contained in this set should be cancelled as above<br />
|-<br />
| 4 || MinVer || int32_t || This alert only applies to versions greater than or equal to this version. Other versions should still relay it.<br />
|-<br />
| 4 || MaxVer || int32_t || This alert only applies to versions less than or equal to this version. Other versions should still relay it.<br />
|-<br />
| ? || setSubVer || set<string> || If this set contains any elements, then only nodes that have their subVer contained in this set are affected by the alert. Other versions should still relay it.<br />
|-<br />
| 4 || Priority || int32_t || Relative priority compared to other alerts<br />
|-<br />
| ? || Comment || string || A comment on the alert that is not displayed<br />
|-<br />
| ? || StatusBar || string || The alert message that is displayed to the user<br />
|-<br />
| ? || Reserved || string || Reserved<br />
|}<br />
<br />
Note: '''set<''type''>''' in the table above is a [[#Variable length integer | variable length integer]] followed by the number of fields of the given ''type'' (either int32_t or [[#Variable length string | variable length string]])<br />
<br />
Sample alert (no message header):<br />
73010000003766404f00000000b305434f00000000f2030000f1030000001027000048ee0000<br />
0064000000004653656520626974636f696e2e6f72672f666562323020696620796f75206861<br />
76652074726f75626c6520636f6e6e656374696e672061667465722032302046656272756172<br />
79004730450221008389df45f0703f39ec8c1cc42c13810ffcae14995bb648340219e353b63b<br />
53eb022009ec65e1c1aaeec1fd334c6b684bde2b3f573060d5b70c3a46723326e4e8a4f1<br />
<br />
Version: 1<br />
RelayUntil: 1329620535<br />
Expiration: 1329792435<br />
ID: 1010<br />
Cancel: 1009<br />
setCancel: <empty><br />
MinVer: 10000<br />
MaxVer: 61000<br />
setSubVer: <empty><br />
Priority: 100<br />
Comment: <empty><br />
StatusBar: "See bitcoin.org/feb20 if you have trouble connecting after 20 February"<br />
Reserved: <empty><br />
<br />
=== sendheaders ===<br />
<br />
Request for Direct headers announcement. <br />
<br />
Upon receipt of this message, the node is be permitted, but not required, to announce new blocks by '''headers''' command (instead of '''inv''' command).<br />
<br />
This message is supported by the protocol version >= 70012 or Bitcoin Core version >= 0.12.0.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0130.mediawiki BIP 130] for more information.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
<br />
=== feefilter ===<br />
<br />
The payload is always 8 bytes long and it encodes 64 bit integer value (LSB / little endian) of '''feerate'''.<br />
The value represents a minimal fee and is expressed in satoshis per 1000 bytes.<br />
<br />
Upon receipt of a "feefilter" message, the node will be permitted, but not required, to filter transaction invs for transactions that fall below the feerate provided in the feefilter message interpreted as satoshis per kilobyte.<br />
<br />
The fee filter is additive with a bloom filter for transactions so if an SPV client were to load a bloom filter and send a feefilter message, transactions would only be relayed if they passed both filters.<br />
<br />
Inv's generated from a mempool message are also subject to a fee filter if it exists.<br />
<br />
Feature discovery is enabled by checking protocol version >= 70013<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0133.mediawiki BIP 133] for more information.<br />
<br />
=== sendcmpct ===<br />
<br />
# The sendcmpct message is defined as a message containing a 1-byte integer followed by a 8-byte integer where pchCommand == "sendcmpct".<br />
# The first integer SHALL be interpreted as a boolean (and MUST have a value of either 1 or 0)<br />
# The second integer SHALL be interpreted as a little-endian version number. Nodes sending a sendcmpct message MUST currently set this value to 1.<br />
# Upon receipt of a "sendcmpct" message with the first and second integers set to 1, the node SHOULD announce new blocks by sending a cmpctblock message.<br />
# Upon receipt of a "sendcmpct" message with the first integer set to 0, the node SHOULD NOT announce new blocks by sending a cmpctblock message, but SHOULD announce new blocks by sending invs or headers, as defined by BIP130.<br />
# Upon receipt of a "sendcmpct" message with the second integer set to something other than 1, nodes MUST treat the peer as if they had not received the message (as it indicates the peer will provide an unexpected encoding in <br />
# cmpctblock, and/or other, messages). This allows future versions to send duplicate sendcmpct messages with different versions as a part of a version handshake for future versions.<br />
# Nodes SHOULD check for a protocol version of >= 70014 before sending sendcmpct messages.<br />
# Nodes MUST NOT send a request for a MSG_CMPCT_BLOCK object to a peer before having received a sendcmpct message from that peer.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== cmpctblock ===<br />
<br />
# The cmpctblock message is defined as as a message containing a serialized HeaderAndShortIDs message and pchCommand == "cmpctblock".<br />
# Upon receipt of a cmpctblock message after sending a sendcmpct message, nodes SHOULD calculate the short transaction ID for each unconfirmed transaction they have available (ie in their mempool) and compare each to each short transaction ID in the cmpctblock message.<br />
# After finding already-available transactions, nodes which do not have all transactions available to reconstruct the full block SHOULD request the missing transactions using a getblocktxn message.<br />
# A node MUST NOT send a cmpctblock message unless they are able to respond to a getblocktxn message which requests every transaction in the block.<br />
# A node MUST NOT send a cmpctblock message without having validated that the header properly commits to each transaction in the block, and properly builds on top of the existing chain with a valid proof-of-work. A node MAY send a cmpctblock before validating that each transaction in the block validly spends existing UTXO set entries.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== getblocktxn ===<br />
<br />
# The getblocktxn message is defined as as a message containing a serialized BlockTransactionsRequest message and pchCommand == "getblocktxn".<br />
# Upon receipt of a properly-formatted getblocktxnmessage, nodes which recently provided the sender of such a message a cmpctblock for the block hash identified in this message MUST respond with an appropriate blocktxn message. Such a blocktxn message MUST contain exactly and only each transaction which is present in the appropriate block at the index specified in the getblocktxn indexes list, in the order requested.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== blocktxn ===<br />
<br />
# The blocktxn message is defined as as a message containing a serialized BlockTransactions message and pchCommand == "blocktxn".<br />
# Upon receipt of a properly-formatted requested blocktxn message, nodes SHOULD attempt to reconstruct the full block by:<br />
# Taking the prefilledtxn transactions from the original cmpctblock and placing them in the marked positions.<br />
# For each short transaction ID from the original cmpctblock, in order, find the corresponding transaction either from the blocktxn message or from other sources and place it in the first available position in the block.<br />
# Once the block has been reconstructed, it shall be processed as normal, keeping in mind that short transaction IDs are expected to occasionally collide, and that nodes MUST NOT be penalized for such collisions, wherever they # appear.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
== Scripting ==<br />
<br />
See [[script]].<br />
<br />
==See Also==<br />
<br />
* [[Network]]<br />
* [[Protocol rules]]<br />
* [[Hardfork Wishlist]]<br />
* [https://bitcoin.org/en/developer-documentation Developer Documentation on bitcoin.org]<br />
* Bitcoin dissectors for Wireshark: https://github.com/lbotsch/wireshark-bitcoin https://github.com/op-sig/bitcoin-wireshark-dissector<br />
<br />
==References==<br />
<references /><br />
<br />
[[zh-cn:协议说明]]<br />
[[Category:Technical]]<br />
[[Category:Developer]]<br />
<br />
{{Bitcoin Core documentation}}</div>Tonikthttps://en.bitcoin.it/w/index.php?title=Protocol_documentation&diff=61484Protocol documentation2016-08-25T12:29:35Z<p>Tonikt: New structures used by BIP 152</p>
<hr />
<div>This page ''describes'' the behavior of the [[Original Bitcoin client|reference client]]. The Bitcoin protocol is specified by the behavior of the reference client, not by this page. In particular, while this page is quite complete in describing the network protocol, it does not attempt to list all of the rules for block or transaction validity.<br />
<br />
Type names used in this documentation are from the C99 standard.<br />
<br />
For protocol used in mining, see [[getblocktemplate]].<br />
<br />
==Common standards==<br />
<br />
=== Hashes ===<br />
<br />
Usually, when a hash is computed within bitcoin, it is computed twice. Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-256] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when a shorter hash is desirable (for example when creating a bitcoin address).<br />
<br />
Example of double-SHA-256 encoding of string "hello":<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round of sha-256)<br />
9595c9df90075148eb06860365df33584b75bff782a510c6cd4883a419833d50 (second round of sha-256)<br />
<br />
For bitcoin addresses (RIPEMD-160) this would give:<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round is sha-256)<br />
b6a9c8c230722b7c748331a8b450f05566dc7d0f (with ripemd-160)<br />
<br />
=== Merkle Trees ===<br />
<br />
Merkle trees are binary trees of hashes. Merkle trees in bitcoin use a '''double''' SHA-256, the SHA-256 hash of the SHA-256 hash of something.<br />
<br />
If, when forming a row in the tree (other than the root of the tree), it would have an odd number of elements, the final double-hash is duplicated to ensure that the row has an even number of hashes.<br />
<br />
First form the bottom row of the tree with the ordered double-SHA-256 hashes of the byte streams of the transactions in the block.<br />
<br />
Then the row above it consists of half that number of hashes. Each entry is the double-SHA-256 of the 64-byte concatenation of the corresponding two hashes below it in the tree.<br />
<br />
This procedure repeats recursively until we reach a row consisting of just a single double-hash. This is the '''Merkle root''' of the tree.<br />
<br />
For example, imagine a block with three transactions ''a'', ''b'' and ''c''. The Merkle tree is: <br />
<br />
d1 = dhash(a)<br />
d2 = dhash(b)<br />
d3 = dhash(c)<br />
d4 = dhash(c) # a, b, c are 3. that's an odd number, so we take the c twice<br />
<br />
d5 = dhash(d1 concat d2)<br />
d6 = dhash(d3 concat d4)<br />
<br />
d7 = dhash(d5 concat d6)<br />
<br />
where<br />
<br />
dhash(a) = sha256(sha256(a))<br />
<br />
''d7'' is the Merkle root of the 3 transactions in this block.<br />
<br />
Note: Hashes in Merkle Tree displayed in the [[Block Explorer]] are of little-endian notation. For some implementations and [http://www.fileformat.info/tool/hash.htm calculations], the bits need to be reversed before they are hashed, and again after the hashing operation.<br />
<br />
=== Signatures ===<br />
<br />
Bitcoin uses [http://en.wikipedia.org/wiki/Elliptic_curve_cryptography Elliptic Curve] [http://en.wikipedia.org/wiki/Digital_Signature_Algorithm Digital Signature Algorithm] ([http://en.wikipedia.org/wiki/Elliptic_Curve_DSA ECDSA]) to sign transactions. <br />
<br />
For [[ECDSA]] the secp256k1 curve from http://www.secg.org/collateral/sec2_final.pdf is used.<br />
<br />
Public keys (in scripts) are given as 04 <x> <y> where ''x'' and ''y'' are 32 byte big-endian integers representing the coordinates of a point on the curve or in compressed form given as <sign> <x> where <sign> is 0x02 if ''y'' is even and 0x03 if ''y'' is odd.<br />
<br />
Signatures use [http://en.wikipedia.org/wiki/Distinguished_Encoding_Rules DER encoding] to pack the ''r'' and ''s'' components into a single byte stream (this is also what OpenSSL produces by default).<br />
<br />
=== Transaction Verification ===<br />
Transactions are cryptographically signed records that reassign ownership of Bitcoins to new addresses. Transactions have ''inputs'' - records which reference the funds from other previous transactions - and ''outputs'' - records which determine the new owner of the transferred Bitcoins, and which will be referenced as inputs in future transactions as those funds are respent.<br />
<br />
Each ''input'' must have a cryptographic digital signature that unlocks the funds from the prior transaction. Only the person possessing the appropriate [[private key]] is able to create a satisfactory signature; this in effect ensures that funds can only be spent by their owners.<br />
<br />
Each ''output'' determines which Bitcoin address (or other criteria, see [[Script]]) is the recipient of the funds.<br />
<br />
In a transaction, the sum of all inputs must be equal to or greater than the sum of all outputs. If the inputs exceed the outputs, the difference is considered a [[transaction fee]], and is redeemable by whoever first includes the transaction into the block chain.<br />
<br />
A special kind of transaction, called a [[coinbase transaction]], has no inputs. It is created by [[miners]], and there is one coinbase transaction per block. Because each block comes with a reward of newly created Bitcoins (e.g. 50 BTC for the first 210,000 blocks), the first transaction of a block is, with few exceptions, the transaction that grants those coins to their recipient (the miner). In addition to the newly created Bitcoins, the coinbase transaction is also used for assigning the recipient of any transaction fees that were paid within the other transactions being included in the same block. The coinbase transaction can assign the entire reward to a single Bitcoin address, or split it in portions among multiple addresses, just like any other transaction. Coinbase transactions always contain outputs totalling the sum of the block reward plus all transaction fees collected from the other transactions in the same block.<br />
<br />
The [[coinbase transaction]] in block zero cannot be spent. This is due to a quirk of the reference client implementation that would open the potential for a block chain fork if some nodes accepted the spend and others did not<ref>[http://bitcointalk.org/index.php?topic=119645.msg1288552#msg1288552 Block 0 Network Fork]</ref>.<br />
<br />
Most Bitcoin outputs encumber the newly transferred coins with a single ECDSA private key. The actual record saved with inputs and outputs isn't necessarily a key, but a ''script''. Bitcoin uses an interpreted scripting system to determine whether an output's criteria have been satisfied, with which more complex operations are possible, such as outputs that require two ECDSA signatures, or two-of-three-signature schemes. An output that references a single Bitcoin address is a ''typical'' output; an output actually contains this information in the form of a script that requires a single ECDSA signature (see [[OP_CHECKSIG]]). The output script specifies what must be provided to unlock the funds later, and when the time comes in the future to spend the transaction in another input, that input must provide all of the thing(s) that satisfy the requirements defined by the original output script.<br />
<br />
=== Addresses ===<br />
<br />
A bitcoin address is in fact the hash of a ECDSA public key, computed this way:<br />
<br />
Version = 1 byte of 0 (zero); on the test network, this is 1 byte of 111<br />
Key hash = Version concatenated with RIPEMD-160(SHA-256(public key))<br />
Checksum = 1st 4 bytes of SHA-256(SHA-256(Key hash))<br />
Bitcoin Address = Base58Encode(Key hash concatenated with Checksum)<br />
<br />
The Base58 encoding used is home made, and has some differences. Especially, leading zeroes are kept as single zeroes when conversion happens.<br />
<br />
== Common structures ==<br />
<br />
Almost all integers are encoded in little endian. Only IP or port number are encoded big endian.<br />
<br />
=== Message structure ===<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown<br />
|-<br />
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| 4 || length || uint32_t || Length of payload in number of bytes<br />
|-<br />
| 4 || checksum || uint32_t || First 4 bytes of sha256(sha256(payload))<br />
|-<br />
| ? || payload || uchar[] || The actual data<br />
|}<br />
<br />
<br />
Known magic values:<br />
<br />
{|class="wikitable"<br />
! Network !! Magic value !! Sent over wire as<br />
|-<br />
| main || 0xD9B4BEF9 || F9 BE B4 D9<br />
|-<br />
| testnet || 0xDAB5BFFA || FA BF B5 DA<br />
|-<br />
| testnet3 || 0x0709110B || 0B 11 09 07<br />
|-<br />
| namecoin || 0xFEB4BEF9 || F9 BE B4 FE<br />
|}<br />
<br />
=== Variable length integer ===<br />
<br />
Integer can be encoded depending on the represented value to save space.<br />
Variable length integers always precede an array/vector of a type of data that may vary in length.<br />
Longer numbers are encoded in little endian.<br />
<br />
{|class="wikitable"<br />
! Value !! Storage length !! Format<br />
|-<br />
| < 0xFD || 1 || uint8_t<br />
|-<br />
| <= 0xFFFF || 3 || 0xFD followed by the length as uint16_t<br />
|-<br />
| <= 0xFFFF FFFF || 5 || 0xFE followed by the length as uint32_t<br />
|-<br />
| - || 9 || 0xFF followed by the length as uint64_t<br />
|}<br />
<br />
If you're reading the Satoshi client code (BitcoinQT) it refers to this encoding as a "CompactSize". Modern BitcoinQT also has the CVarInt class which implements an even more compact integer for the purpose of local storage (which is incompatible with "CompactSize" described here). CVarInt is not a part of the protocol.<br />
<br />
=== Variable length string ===<br />
<br />
Variable length string can be stored using a variable length integer followed by the string itself.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the string<br />
|-<br />
| ? || string || char[] || The string itself (can be empty)<br />
|}<br />
<br />
=== Network address ===<br />
<br />
When a network address is needed somewhere, this structure is used. Network addresses are not prefixed with a timestamp in the version message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || time || uint32 || the Time (version >= 31402). '''Not present in version message.'''<br />
|-<br />
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]<br />
|-<br />
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The original client only supported IPv4 and only read the last 4 bytes to get the IPv4 address. However, the IPv4 address is written into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]<br />
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).<br />
|-<br />
| 2 || port || uint16_t || port number, network byte order<br />
|}<br />
<br />
Hexdump example of Network address structure<br />
<br />
<pre><br />
0000 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0010 00 00 FF FF 0A 00 00 01 20 8D ........ .<br />
<br />
Network address:<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK: see services listed under version command)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv6: ::ffff:a00:1 or IPv4: 10.0.0.1<br />
20 8D - Port 8333<br />
</pre><br />
<br />
=== Inventory Vectors ===<br />
<br />
Inventory vectors are used for notifying other nodes about objects they have or data which is being requested.<br />
<br />
Inventory vectors consist of the following data format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || type || uint32_t || Identifies the object type linked to this inventory<br />
|-<br />
| 32 || hash || char[32] || Hash of the object<br />
|}<br />
<br />
<br />
The object type is currently defined as one of the following possibilities:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0 || ERROR || Any data of with this number may be ignored<br />
|-<br />
| 1 || MSG_TX || Hash is related to a transaction<br />
|-<br />
| 2 || MSG_BLOCK || Hash is related to a data block<br />
|-<br />
| 3 || MSG_FILTERED_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a merkleblock message rather than a block message; this only works if a bloom filter has been set.<br />
|-<br />
| 4 || MSG_CMPCT_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a cmpctblock message. See BIP 152 for more info.<br />
|}<br />
<br />
Other Data Type values are considered reserved for future implementations.<br />
<br />
=== Block Headers ===<br />
<br />
Block headers are sent in a headers packet in response to a getheaders message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Will overflow in 2106<ref>https://en.wikipedia.org/wiki/Unix_time#Notable_events_in_Unix_time</ref>)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 1 || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries, this value is always 0<br />
|}<br />
<br />
cf. [[Block hashing algorithm]]<br />
<br />
=== PrefilledTransaction ===<br />
<br />
A PrefilledTransaction structure is used in HeaderAndShortIDs to provide a list of a few transactions explicitly.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== HeaderAndShortIDs ===<br />
<br />
A HeaderAndShortIDs structure is used to relay a block header, the short transactions IDs used for matching already-available transactions, and a select few transactions which we expect a peer may be missing.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== BlockTransactionsRequest ===<br />
<br />
A BlockTransactionsRequest structure is used to list transaction indexes in a block being requested.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== BlockTransactions ===<br />
<br />
A BlockTransactions structure is used to provide some of the transactions in a block, as requested.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== Short transaction IDs ===<br />
<br />
Short transaction IDs are used to represent a transaction without sending a full 256-bit hash. They are calculated by:<br />
<br />
# single-SHA256 hashing the block header with the nonce appended (in little-endian)<br />
# Running SipHash-2-4 with the input being the transaction ID and the keys (k0/k1) set to the first two little-endian 64-bit integers from the above hash, respectively.<br />
# Dropping the 2 most significant bytes from the SipHash output to make it 6 bytes.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
== Message types ==<br />
<br />
=== version ===<br />
<br />
When a node creates an outgoing connection, it will immediately [[Version Handshake|advertise]] its version. The remote node will respond with its version. No further communication is possible until both peers have exchanged their version.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Identifies protocol version being used by the node<br />
|-<br />
| 8 || services || uint64_t || bitfield of features to be enabled for this connection<br />
|-<br />
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds<br />
|-<br />
| 26 || addr_recv || [[#Network address|net_addr]] || The network address of the node receiving this message<br />
|-<br />
|colspan="4"| Fields below require version ≥ 106<br />
|-<br />
| 26 || addr_from || [[#Network address|net_addr]] || The network address of the node emitting this message<br />
|-<br />
| 8 || nonce || uint64_t || Node random nonce, randomly generated every time a version packet is sent. This nonce is used to detect connections to self.<br />
|-<br />
| ? || user_agent || [[#Variable length string|var_str]] || [https://github.com/bitcoin/bips/blob/master/bip-0014.mediawiki User Agent] (0x00 if string is 0 bytes long)<br />
|-<br />
| 4 || start_height || int32_t || The last block received by the emitting node<br />
|-<br />
|colspan="4"| Fields below require version ≥ 70001<br />
|-<br />
| 1 || relay || bool || Whether the remote peer should announce relayed transactions or not, see [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037]<br />
|}<br />
<br />
A "verack" packet shall be sent if the version packet was accepted.<br />
<br />
The following services are currently assigned:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 1 || NODE_NETWORK || This node can be asked for full blocks instead of just headers.<br />
|}<br />
<br />
Hexdump example of version message (OBSOLETE EXAMPLE: This example lacks a checksum and user-agent):<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....<br />
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........<br />
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............<br />
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................<br />
0040 20 8D 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,<br />
0060 3A B4 57 13 00 55 81 01 00 :.W..U...<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
55 00 00 00 - Payload is 85 bytes long<br />
- No checksum in version message until 20 February 2012. See https://bitcointalk.org/index.php?topic=55852.0<br />
Version message:<br />
9C 7C 00 00 - 31900 (version 0.3.19)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
E6 15 10 4D 00 00 00 00 - Mon Dec 20 21:50:14 EST 2010<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 20 8D - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D - Sender address info - see Network Address<br />
DD 9D 20 2C 3A B4 57 13 - Node random unique ID<br />
00 - "" sub-version string (string is 0 bytes long)<br />
55 81 01 00 - Last block sending node has is block #98645<br />
</pre><br />
<br />
And here's a modern (60002) protocol version client advertising itself to a local peer...<br />
<br />
Newer protocol includes the checksum now, this is from a mainline (satoshi) client during <br />
an outgoing connection to another local client, notice that it does not fill out the <br />
address information at all when the source or destination is "unroutable".<br />
<br />
<pre><br />
<br />
0000 f9 be b4 d9 76 65 72 73 69 6f 6e 00 00 00 00 00 ....version.....<br />
0010 64 00 00 00 35 8d 49 32 62 ea 00 00 01 00 00 00 d...5.I2b.......<br />
0020 00 00 00 00 11 b2 d0 50 00 00 00 00 01 00 00 00 .......P........<br />
0030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ff ff ................<br />
0040 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 00 00 00 00 ff ff 00 00 00 00 00 00 ................<br />
0060 3b 2e b3 5d 8c e6 17 65 0f 2f 53 61 74 6f 73 68 ;..]...e./Satosh<br />
0070 69 3a 30 2e 37 2e 32 2f c0 3e 03 00 i:0.7.2/.>..<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
64 00 00 00 - Payload is 100 bytes long<br />
3B 64 8D 5A - payload checksum<br />
<br />
Version message:<br />
62 EA 00 00 - 60002 (protocol version 60002)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
11 B2 D0 50 00 00 00 00 - Tue Dec 18 10:12:33 PST 2012<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Sender address info - see Network Address<br />
3B 2E B3 5D 8C E6 17 65 - Node ID<br />
0F 2F 53 61 74 6F 73 68 69 3A 30 2E 37 2E 32 2F - "/Satoshi:0.7.2/" sub-version string (string is 15 bytes long)<br />
C0 3E 03 00 - Last block sending node has is block #212672<br />
</pre><br />
<br />
=== verack ===<br />
<br />
The ''verack'' message is sent in reply to ''[[#version|version]]''. This message consists of only a [[#Message structure|message header]] with the command string "verack".<br />
<br />
Hexdump of the verack message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......<br />
0010 00 00 00 00 5D F6 E0 E2 ........<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 61 63 6B 00 00 00 00 00 00 - "verack" command<br />
00 00 00 00 - Payload is 0 bytes long<br />
5D F6 E0 E2 - Checksum<br />
</pre><br />
<br />
=== addr ===<br />
<br />
Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours<br />
<br />
Payload:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of address entries (max: 1000)<br />
|-<br />
| 30x? || addr_list || (uint32_t + [[#Network address|net_addr]])[] || Address of other nodes on the network. version < 209 will only read the first one. The uint32_t is a timestamp (see note below).<br />
|}<br />
<br />
'''Note''': Starting version 31402, addresses are prefixed with a timestamp. If no timestamp is present, the addresses should not be relayed to other peers, unless it is indeed confirmed they are up.<br />
<br />
Hexdump example of ''addr'' message:<br />
<pre><br />
0000 F9 BE B4 D9 61 64 64 72 00 00 00 00 00 00 00 00 ....addr........<br />
0010 1F 00 00 00 ED 52 39 9B 01 E2 15 10 4D 01 00 00 .....R9.....M...<br />
0020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF ................<br />
0030 FF 0A 00 00 01 20 8D ..... .<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
61 64 64 72 00 00 00 00 00 00 00 00 - "addr"<br />
1F 00 00 00 - payload is 31 bytes long<br />
ED 52 39 9B - checksum of payload<br />
<br />
Payload:<br />
01 - 1 address in this message<br />
<br />
Address:<br />
E2 15 10 4D - Mon Dec 20 21:50:10 EST 2010 (only when version is >= 31402)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK service - see version message)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv4: 10.0.0.1, IPv6: ::ffff:10.0.0.1 (IPv4-mapped IPv6 address)<br />
20 8D - port 8333<br />
</pre><br />
<br />
=== inv ===<br />
<br />
Allows a node to advertise its knowledge of one or more objects. It can be received unsolicited, or in reply to ''getblocks''.<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getdata ===<br />
<br />
getdata is used in response to inv, to retrieve the content of a specific object, and is usually sent after receiving an ''inv'' packet, after filtering known elements. It can be used to retrieve transactions, but only if they are in the memory pool or relay set - arbitrary access to transactions in the chain is not allowed to avoid having clients start to depend on nodes having full transaction indexes (which modern nodes do not).<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== notfound ===<br />
<br />
notfound is a response to a getdata, sent if any requested data items could not be relayed, for example, because the requested transaction was not in the memory pool or relay set.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getblocks ===<br />
<br />
Return an ''inv'' packet containing the list of blocks starting right after the last known hash in the block locator object, up to hash_stop or 500 blocks, whichever comes first. <br />
<br />
The locator hashes are processed by a node in the order as they appear in the message. If a block hash is found in the node's main chain, the list of its children is returned back via the ''inv'' message and the remaining locators are ignored, no matter if the requested limit was reached, or not.<br />
<br />
To receive the next blocks hashes, one needs to issue getblocks again with a new block locator object. Keep in mind that some clients may provide blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block; set to zero to get as many blocks as possible (500)<br />
|}<br />
<br />
To create the block locator hashes, keep pushing hashes until you go back to the genesis block. After pushing 10 hashes back, the step backwards doubles every loop:<br />
<br />
<pre><br />
// From libbitcoin which is under AGPL<br />
std::vector<size_t> block_locator_indexes(size_t top_height)<br />
{<br />
std::vector<size_t> indexes;<br />
<br />
// Modify the step in the iteration.<br />
int64_t step = 1;<br />
<br />
// Start at the top of the chain and work backwards.<br />
for (auto index = (int64_t)top_height; index > 0; index -= step)<br />
{<br />
// Push top 10 indexes first, then back off exponentially.<br />
if (indexes.size() >= 10)<br />
step *= 2;<br />
<br />
indexes.push_back((size_t)index);<br />
}<br />
<br />
// Push the genesis block index.<br />
indexes.push_back(0);<br />
return indexes;<br />
}<br />
</pre><br />
<br />
Note that it is allowed to send in fewer known hashes down to a minimum of just one hash. However, the purpose of the block locator object is to detect a wrong branch in the caller's main chain. If the peer detects that you are off the main chain, it will send in block hashes which are earlier than your last known block. So if you just send in your last known hash and it is off the main chain, the peer starts over at block #1.<br />
<br />
=== getheaders ===<br />
<br />
Return a ''headers'' packet containing the headers of blocks starting right after the last known hash in the block locator object, up to hash_stop or 2000 blocks, whichever comes first. To receive the next block headers, one needs to issue getheaders again with a new block locator object. The ''getheaders'' command is used by thin clients to quickly download the block chain where the contents of the transactions would be irrelevant (because they are not ours). Keep in mind that some clients may provide headers of blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block header; set to zero to get as many blocks as possible (2000)<br />
|}<br />
<br />
For the block locator object in this packet, the same rules apply as for the [[Protocol_documentation#getblocks|getblocks]] packet.<br />
<br />
=== tx ===<br />
<br />
''tx'' describes a bitcoin transaction, in reply to ''[[#getdata|getdata]]''<br />
<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Transaction data format version (note, this is signed)<br />
|-<br />
| 1+ || tx_in count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction inputs<br />
|-<br />
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins<br />
|-<br />
| 1+ || tx_out count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction outputs<br />
|-<br />
| 9+ || tx_out || tx_out[] || A list of 1 or more transaction outputs or destinations for coins<br />
|-<br />
| 4 || lock_time || uint32_t || The block number or timestamp at which this transaction is locked:<br />
{|class="wikitable"<br />
! Value !! Description<br />
|-<br />
| 0 || Not locked<br />
|-<br />
| < 500000000 || Block number at which this transaction is locked<br />
|-<br />
| >= 500000000 || UNIX timestamp at which this transaction is locked<br />
|}<br />
If all TxIn inputs have final (0xffffffff) sequence numbers then lock_time is irrelevant. Otherwise, the transaction may not be added to a block until after lock_time (see [[NLockTime]]).<br />
<br />
|}<br />
<br />
TxIn consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 36 || previous_output || outpoint || The previous output transaction reference, as an OutPoint structure<br />
|-<br />
| 1+ || script length || [[Protocol_documentation#Variable_length_integer|var_int]] || The length of the signature script<br />
|-<br />
| ? || signature script || uchar[] || Computational Script for confirming transaction authorization<br />
|-<br />
| 4 || [http://bitcoin.stackexchange.com/q/2025/323 sequence] || uint32_t || Transaction version as defined by the sender. Intended for "replacement" of transactions when information is updated before inclusion into a block.<br />
|}<br />
<br />
The OutPoint structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 32 || hash || char[32] || The hash of the referenced transaction.<br />
|-<br />
| 4 || index || uint32_t || The index of the specific output in the transaction. The first output is 0, etc.<br />
|}<br />
<br />
The Script structure consists of a series of pieces of information and operations related to the value of the transaction.<br />
<br />
(Structure to be expanded in the future… see script.h and script.cpp and [[Script]] for more information)<br />
<br />
The TxOut structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || value || int64_t || Transaction Value<br />
|-<br />
| 1+ || pk_script length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the pk_script<br />
|-<br />
| ? || pk_script || uchar[] || Usually contains the public key as a Bitcoin script setting up conditions to claim this output.<br />
|}<br />
<br />
Example ''tx'' message:<br />
<pre><br />
000000 F9 BE B4 D9 74 78 00 00 00 00 00 00 00 00 00 00 ....tx..........<br />
000010 02 01 00 00 E2 93 CD BE 01 00 00 00 01 6D BD DB .............m..<br />
000020 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D 12 66 E9 .[...Q........f.<br />
000030 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29 00 00 00 .;P......j.6)...<br />
000040 00 8B 48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 ..H0E.!..X..r...<br />
000050 C7 36 7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A .6zz%;..R#...h.:<br />
000060 59 23 3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 Y#?E.W... Y.....<br />
000070 0E 41 83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D .A.z.X.z...XN...<br />
000080 35 BD 96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF 5...6..;...A....<br />
000090 C9 7E F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 .~.6.m...@..!...<br />
0000A0 2A CD 2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC *.+..].}Y... ...<br />
0000B0 4E 02 53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F N.S..=7.o...Q...<br />
0000C0 14 04 2F 46 61 4A 4C 70 C0 F1 4B EF F5 FF FF FF ../FaJLp..K.....<br />
0000D0 FF 02 40 4B 4C 00 00 00 00 00 19 76 A9 14 1A A0 ..@KL......v....<br />
0000E0 CD 1C BE A6 E7 45 8A 7A BA D5 12 A9 D9 EA 1A FB .....E.z........<br />
0000F0 22 5E 88 AC 80 FA E9 C7 00 00 00 00 19 76 A9 14 "^...........v..<br />
000100 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E FD A0 B7 ..[.Cj.....H^...<br />
000110 8B 4E CC 52 88 AC 00 00 00 00 .N.R......<br />
<br />
<br />
Message header:<br />
F9 BE B4 D9 - main network magic bytes<br />
74 78 00 00 00 00 00 00 00 00 00 00 - "tx" command<br />
02 01 00 00 - payload is 258 bytes long<br />
E2 93 CD BE - checksum of payload<br />
<br />
Transaction:<br />
01 00 00 00 - version<br />
<br />
Inputs:<br />
01 - number of transaction inputs<br />
<br />
Input 1:<br />
6D BD DB 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D - previous output (outpoint)<br />
12 66 E9 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29<br />
00 00 00 00<br />
<br />
8B - script is 139 bytes long<br />
<br />
48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 C7 36 - signature script (scriptSig)<br />
7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A 59 23<br />
3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 0E 41<br />
83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D 35 BD<br />
96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF C9 7E<br />
F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 2A CD<br />
2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC 4E 02<br />
53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F 14 04<br />
2F 46 61 4A 4C 70 C0 F1 4B EF F5<br />
<br />
FF FF FF FF - sequence<br />
<br />
Outputs:<br />
02 - 2 Output Transactions<br />
<br />
Output 1:<br />
40 4B 4C 00 00 00 00 00 - 0.05 BTC (5000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 1A A0 CD 1C BE A6 E7 45 8A 7A BA D5 12 - pk_script<br />
A9 D9 EA 1A FB 22 5E 88 AC<br />
<br />
Output 2:<br />
80 FA E9 C7 00 00 00 00 - 33.54 BTC (3354000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E - pk_script<br />
FD A0 B7 8B 4E CC 52 88 AC<br />
<br />
Locktime:<br />
00 00 00 00 - lock time<br />
</pre><br />
<br />
=== block ===<br />
<br />
The '''block''' message is sent in response to a getdata message which requests transaction information from a block hash.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A Unix timestamp recording when this block was created (Currently limited to dates before the year 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated [[Difficulty|difficulty target]] being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| ? || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries<br />
|-<br />
| ? || txns || tx[] || Block transactions, in format of "tx" command<br />
|}<br />
<br />
The SHA256 hash that identifies each block (and which must have a run of 0 bits) is calculated from the first 6 fields of this structure (version, prev_block, merkle_root, timestamp, bits, nonce, and standard SHA256 padding, making two 64-byte chunks in all) and ''not'' from the complete block. To calculate the hash, only two chunks need to be processed by the SHA256 algorithm. Since the ''nonce'' field is in the second chunk, the first chunk stays constant during mining and therefore only the second chunk needs to be processed. However, a Bitcoin hash is the hash of the hash, so two SHA256 rounds are needed for each mining iteration.<br />
See [[Block hashing algorithm]] for details and an example.<br />
<br />
=== headers ===<br />
<br />
The ''headers'' packet returns block headers in response to a ''getheaders'' packet. <br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of block headers<br />
|-<br />
| 81x? || headers || [[Protocol_documentation#Block_Headers|block_header]][] || [[Protocol_documentation#Block_Headers|Block headers]]<br />
|}<br />
<br />
Note that the block headers in this packet include a transaction count (a var_int, so there can be more than 81 bytes per header) as opposed to the block headers that are hashed by miners.<br />
<br />
=== getaddr ===<br />
<br />
The getaddr message sends a request to a node asking for information about known active peers to help with finding potential nodes in the network. The response to receiving this message is to transmit one or more addr messages with one or more peers from a database of known active peers. The typical presumption is that a node is likely to be active if it has been sending a message within the last three hours.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
=== mempool ===<br />
<br />
The mempool message sends a request to a node asking for information about transactions it has verified but which have not yet confirmed. The response to receiving this message is an inv message containing the transaction hashes for all the transactions in the node's mempool.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
It is specified in [https://github.com/bitcoin/bips/blob/master/bip-0035.mediawiki BIP 35]. Since [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 37], if a [[Protocol_documentation#filterload.2C_filteradd.2C_filterclear.2C_merkleblock|bloom filter]] is loaded, only transactions matching the filter are replied.<br />
<br />
=== checkorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== submitorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== reply ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== ping ===<br />
<br />
The ''ping'' message is sent primarily to confirm that the TCP/IP connection is still valid. An error in transmission is presumed to be a closed connection and the address is removed as a current peer.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || random nonce<br />
|}<br />
<br />
=== pong ===<br />
<br />
The ''pong'' message is sent in response to a ''ping'' message. In modern protocol versions, a ''pong'' response is generated using a nonce included in the ping.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || nonce from ping<br />
|}<br />
<br />
<br />
=== reject===<br />
<br />
The ''reject'' message is sent when messages are rejected.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || message || var_str || type of message rejected<br />
|-<br />
| 1 || ccode || char || code relating to rejected message<br />
|-<br />
| 1+ || reason || var_str || text version of reason for rejection<br />
|-<br />
| 0+ || data || char || Optional extra data provided by some errors. Currently, all errors which provide this field fill it with the TXID or block header hash of the object being rejected, so the field is 32 bytes.<br />
|}<br />
<br />
CCodes<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0x01 || REJECT_MALFORMED|| <br />
|-<br />
| 0x10 || REJECT_INVALID ||<br />
|-<br />
| 0x11 || REJECT_OBSOLETE ||<br />
|-<br />
| 0x12 || REJECT_DUPLICATE ||<br />
|-<br />
| 0x40 || REJECT_NONSTANDARD ||<br />
|-<br />
| 0x41 || REJECT_DUST ||<br />
|-<br />
| 0x42 || REJECT_INSUFFICIENTFEE ||<br />
|-<br />
| 0x43 || REJECT_CHECKPOINT ||<br />
|}<br />
<br />
=== filterload, filteradd, filterclear, merkleblock ===<br />
<br />
These messages are related to Bloom filtering of connections and are defined in [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037].<br />
<br />
<br />
The <code>filterload</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || filter || uint8_t[] || The filter itself is simply a bit field of arbitrary byte-aligned size. The maximum size is 36,000 bytes.<br />
|-<br />
| 4 || nHashFuncs || uint32_t || The number of hash functions to use in this filter. The maximum value allowed in this field is 50.<br />
|-<br />
| 4 || nTweak || uint32_t || A random value to add to the seed value in the hash function used by the bloom filter.<br />
|-<br />
| 1 || nFlags || uint8_t || A set of flags that control how matched items are added to the filter.<br />
|}<br />
<br />
See below for a description of the Bloom filter algorithm and how to select nHashFuncs and filter size for a desired false positive rate.<br />
<br />
Upon receiving a <code>filterload</code> command, the remote peer will immediately restrict the broadcast transactions it announces (in inv packets) to transactions matching the filter, where the matching algorithm is specified below. The flags control the update behaviour of the matching algorithm.<br />
<br />
The <code>filteradd</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || data || uint8_t[] || The data element to add to the current filter.<br />
|}<br />
<br />
The data field must be smaller than or equal to 520 bytes in size (the maximum size of any potentially matched object).<br />
<br />
The given data element will be added to the Bloom filter. A filter must have been previously provided using <code>filterload</code>. This command is useful if a new key or script is added to a clients wallet whilst it has connections to the network open, it avoids the need to re-calculate and send an entirely new filter to every peer (though doing so is usually advisable to maintain anonymity).<br />
<br />
The <code>filterclear</code> command has no arguments at all.<br />
<br />
After a filter has been set, nodes don't merely stop announcing non-matching transactions, they can also serve filtered blocks. A filtered block is defined by the <code>merkleblock</code> message and is defined like this:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information, based upon the software version creating this block (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Limited to 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 4 || total_transactions || uint32_t || Number of transactions in the block (including unmatched ones)<br />
|-<br />
| ? || hashes || uint256[] || hashes in depth-first order (including standard varint size prefix)<br />
|-<br />
| ? || flags || byte[] || flag bits, packed per 8 in a byte, least significant bit first (including standard varint size prefix)<br />
|}<br />
<br />
=== alert ===<br />
<br />
An '''alert''' is sent between nodes to send a general notification message throughout the network. If the alert can be confirmed with the signature as having come from the core development group of the Bitcoin software, the message is suggested to be displayed for end-users. Attempts to perform transactions, particularly automated transactions through the client, are suggested to be halted. The text in the Message string should be relayed to log files and any user interfaces.<br />
<br />
Alert format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || payload || uchar[] || Serialized alert payload<br />
|-<br />
| ? || signature || uchar[] || An ECDSA signature of the message<br />
|}<br />
<br />
The developers of Satoshi's client use this public key for signing alerts:<br />
04fc9702847840aaf195de8442ebecedf5b095cdbb9bc716bda9110971b28a49e0ead8564ff0db22209e0374782c093bb899692d524e9d6a6956e7c5ecbcd68284<br />
(hash) 1AGRxqDa5WjUKBwHB9XYEjmkv1ucoUUy1s<br />
<br />
The payload is serialized into a uchar[] to ensure that versions using incompatible alert formats can still relay alerts among one another. The current alert payload format is:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || Version || int32_t || Alert format version<br />
|-<br />
| 8 || RelayUntil || int64_t || The timestamp beyond which nodes should stop relaying this alert<br />
|-<br />
| 8 || Expiration || int64_t || The timestamp beyond which this alert is no longer in effect and should be ignored<br />
|-<br />
| 4 || ID || int32_t || A unique ID number for this alert<br />
|-<br />
| 4 || Cancel || int32_t || All alerts with an ID number less than or equal to this number should be cancelled: deleted and not accepted in the future<br />
|-<br />
| ? || setCancel || set<int32_t> || All alert IDs contained in this set should be cancelled as above<br />
|-<br />
| 4 || MinVer || int32_t || This alert only applies to versions greater than or equal to this version. Other versions should still relay it.<br />
|-<br />
| 4 || MaxVer || int32_t || This alert only applies to versions less than or equal to this version. Other versions should still relay it.<br />
|-<br />
| ? || setSubVer || set<string> || If this set contains any elements, then only nodes that have their subVer contained in this set are affected by the alert. Other versions should still relay it.<br />
|-<br />
| 4 || Priority || int32_t || Relative priority compared to other alerts<br />
|-<br />
| ? || Comment || string || A comment on the alert that is not displayed<br />
|-<br />
| ? || StatusBar || string || The alert message that is displayed to the user<br />
|-<br />
| ? || Reserved || string || Reserved<br />
|}<br />
<br />
Note: '''set<''type''>''' in the table above is a [[#Variable length integer | variable length integer]] followed by the number of fields of the given ''type'' (either int32_t or [[#Variable length string | variable length string]])<br />
<br />
Sample alert (no message header):<br />
73010000003766404f00000000b305434f00000000f2030000f1030000001027000048ee0000<br />
0064000000004653656520626974636f696e2e6f72672f666562323020696620796f75206861<br />
76652074726f75626c6520636f6e6e656374696e672061667465722032302046656272756172<br />
79004730450221008389df45f0703f39ec8c1cc42c13810ffcae14995bb648340219e353b63b<br />
53eb022009ec65e1c1aaeec1fd334c6b684bde2b3f573060d5b70c3a46723326e4e8a4f1<br />
<br />
Version: 1<br />
RelayUntil: 1329620535<br />
Expiration: 1329792435<br />
ID: 1010<br />
Cancel: 1009<br />
setCancel: <empty><br />
MinVer: 10000<br />
MaxVer: 61000<br />
setSubVer: <empty><br />
Priority: 100<br />
Comment: <empty><br />
StatusBar: "See bitcoin.org/feb20 if you have trouble connecting after 20 February"<br />
Reserved: <empty><br />
<br />
=== sendheaders ===<br />
<br />
Request for Direct headers announcement. <br />
<br />
Upon receipt of this message, the node is be permitted, but not required, to announce new blocks by '''headers''' command (instead of '''inv''' command).<br />
<br />
This message is supported by the protocol version >= 70012 or Bitcoin Core version >= 0.12.0.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0130.mediawiki BIP 130] for more information.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
<br />
=== feefilter ===<br />
<br />
The payload is always 8 bytes long and it encodes 64 bit integer value (LSB / little endian) of '''feerate'''.<br />
The value represents a minimal fee and is expressed in satoshis per 1000 bytes.<br />
<br />
Upon receipt of a "feefilter" message, the node will be permitted, but not required, to filter transaction invs for transactions that fall below the feerate provided in the feefilter message interpreted as satoshis per kilobyte.<br />
<br />
The fee filter is additive with a bloom filter for transactions so if an SPV client were to load a bloom filter and send a feefilter message, transactions would only be relayed if they passed both filters.<br />
<br />
Inv's generated from a mempool message are also subject to a fee filter if it exists.<br />
<br />
Feature discovery is enabled by checking protocol version >= 70013<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0133.mediawiki BIP 133] for more information.<br />
<br />
=== sendcmpct ===<br />
<br />
# The sendcmpct message is defined as a message containing a 1-byte integer followed by a 8-byte integer where pchCommand == "sendcmpct".<br />
# The first integer SHALL be interpreted as a boolean (and MUST have a value of either 1 or 0)<br />
# The second integer SHALL be interpreted as a little-endian version number. Nodes sending a sendcmpct message MUST currently set this value to 1.<br />
# Upon receipt of a "sendcmpct" message with the first and second integers set to 1, the node SHOULD announce new blocks by sending a cmpctblock message.<br />
# Upon receipt of a "sendcmpct" message with the first integer set to 0, the node SHOULD NOT announce new blocks by sending a cmpctblock message, but SHOULD announce new blocks by sending invs or headers, as defined by BIP130.<br />
# Upon receipt of a "sendcmpct" message with the second integer set to something other than 1, nodes MUST treat the peer as if they had not received the message (as it indicates the peer will provide an unexpected encoding in <br />
# cmpctblock, and/or other, messages). This allows future versions to send duplicate sendcmpct messages with different versions as a part of a version handshake for future versions.<br />
# Nodes SHOULD check for a protocol version of >= 70014 before sending sendcmpct messages.<br />
# Nodes MUST NOT send a request for a MSG_CMPCT_BLOCK object to a peer before having received a sendcmpct message from that peer.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== cmpctblock ===<br />
<br />
# The cmpctblock message is defined as as a message containing a serialized HeaderAndShortIDs message and pchCommand == "cmpctblock".<br />
# Upon receipt of a cmpctblock message after sending a sendcmpct message, nodes SHOULD calculate the short transaction ID for each unconfirmed transaction they have available (ie in their mempool) and compare each to each short transaction ID in the cmpctblock message.<br />
# After finding already-available transactions, nodes which do not have all transactions available to reconstruct the full block SHOULD request the missing transactions using a getblocktxn message.<br />
# A node MUST NOT send a cmpctblock message unless they are able to respond to a getblocktxn message which requests every transaction in the block.<br />
# A node MUST NOT send a cmpctblock message without having validated that the header properly commits to each transaction in the block, and properly builds on top of the existing chain with a valid proof-of-work. A node MAY send a cmpctblock before validating that each transaction in the block validly spends existing UTXO set entries.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== getblocktxn ===<br />
<br />
# The getblocktxn message is defined as as a message containing a serialized BlockTransactionsRequest message and pchCommand == "getblocktxn".<br />
# Upon receipt of a properly-formatted getblocktxnmessage, nodes which recently provided the sender of such a message a cmpctblock for the block hash identified in this message MUST respond with an appropriate blocktxn message. Such a blocktxn message MUST contain exactly and only each transaction which is present in the appropriate block at the index specified in the getblocktxn indexes list, in the order requested.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== blocktxn ===<br />
<br />
# The blocktxn message is defined as as a message containing a serialized BlockTransactions message and pchCommand == "blocktxn".<br />
# Upon receipt of a properly-formatted requested blocktxn message, nodes SHOULD attempt to reconstruct the full block by:<br />
# Taking the prefilledtxn transactions from the original cmpctblock and placing them in the marked positions.<br />
# For each short transaction ID from the original cmpctblock, in order, find the corresponding transaction either from the blocktxn message or from other sources and place it in the first available position in the block.<br />
# Once the block has been reconstructed, it shall be processed as normal, keeping in mind that short transaction IDs are expected to occasionally collide, and that nodes MUST NOT be penalized for such collisions, wherever they # appear.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
== Scripting ==<br />
<br />
See [[script]].<br />
<br />
==See Also==<br />
<br />
* [[Network]]<br />
* [[Protocol rules]]<br />
* [[Hardfork Wishlist]]<br />
* [https://bitcoin.org/en/developer-documentation Developer Documentation on bitcoin.org]<br />
* Bitcoin dissectors for Wireshark: https://github.com/lbotsch/wireshark-bitcoin https://github.com/op-sig/bitcoin-wireshark-dissector<br />
<br />
==References==<br />
<references /><br />
<br />
[[zh-cn:协议说明]]<br />
[[Category:Technical]]<br />
[[Category:Developer]]<br />
<br />
{{Bitcoin Core documentation}}</div>Tonikthttps://en.bitcoin.it/w/index.php?title=Protocol_documentation&diff=61483Protocol documentation2016-08-25T12:22:48Z<p>Tonikt: BIP152 commands: cmpctblock, getblocktxn, blocktxn</p>
<hr />
<div>This page ''describes'' the behavior of the [[Original Bitcoin client|reference client]]. The Bitcoin protocol is specified by the behavior of the reference client, not by this page. In particular, while this page is quite complete in describing the network protocol, it does not attempt to list all of the rules for block or transaction validity.<br />
<br />
Type names used in this documentation are from the C99 standard.<br />
<br />
For protocol used in mining, see [[getblocktemplate]].<br />
<br />
==Common standards==<br />
<br />
=== Hashes ===<br />
<br />
Usually, when a hash is computed within bitcoin, it is computed twice. Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-256] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when a shorter hash is desirable (for example when creating a bitcoin address).<br />
<br />
Example of double-SHA-256 encoding of string "hello":<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round of sha-256)<br />
9595c9df90075148eb06860365df33584b75bff782a510c6cd4883a419833d50 (second round of sha-256)<br />
<br />
For bitcoin addresses (RIPEMD-160) this would give:<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round is sha-256)<br />
b6a9c8c230722b7c748331a8b450f05566dc7d0f (with ripemd-160)<br />
<br />
=== Merkle Trees ===<br />
<br />
Merkle trees are binary trees of hashes. Merkle trees in bitcoin use a '''double''' SHA-256, the SHA-256 hash of the SHA-256 hash of something.<br />
<br />
If, when forming a row in the tree (other than the root of the tree), it would have an odd number of elements, the final double-hash is duplicated to ensure that the row has an even number of hashes.<br />
<br />
First form the bottom row of the tree with the ordered double-SHA-256 hashes of the byte streams of the transactions in the block.<br />
<br />
Then the row above it consists of half that number of hashes. Each entry is the double-SHA-256 of the 64-byte concatenation of the corresponding two hashes below it in the tree.<br />
<br />
This procedure repeats recursively until we reach a row consisting of just a single double-hash. This is the '''Merkle root''' of the tree.<br />
<br />
For example, imagine a block with three transactions ''a'', ''b'' and ''c''. The Merkle tree is: <br />
<br />
d1 = dhash(a)<br />
d2 = dhash(b)<br />
d3 = dhash(c)<br />
d4 = dhash(c) # a, b, c are 3. that's an odd number, so we take the c twice<br />
<br />
d5 = dhash(d1 concat d2)<br />
d6 = dhash(d3 concat d4)<br />
<br />
d7 = dhash(d5 concat d6)<br />
<br />
where<br />
<br />
dhash(a) = sha256(sha256(a))<br />
<br />
''d7'' is the Merkle root of the 3 transactions in this block.<br />
<br />
Note: Hashes in Merkle Tree displayed in the [[Block Explorer]] are of little-endian notation. For some implementations and [http://www.fileformat.info/tool/hash.htm calculations], the bits need to be reversed before they are hashed, and again after the hashing operation.<br />
<br />
=== Signatures ===<br />
<br />
Bitcoin uses [http://en.wikipedia.org/wiki/Elliptic_curve_cryptography Elliptic Curve] [http://en.wikipedia.org/wiki/Digital_Signature_Algorithm Digital Signature Algorithm] ([http://en.wikipedia.org/wiki/Elliptic_Curve_DSA ECDSA]) to sign transactions. <br />
<br />
For [[ECDSA]] the secp256k1 curve from http://www.secg.org/collateral/sec2_final.pdf is used.<br />
<br />
Public keys (in scripts) are given as 04 <x> <y> where ''x'' and ''y'' are 32 byte big-endian integers representing the coordinates of a point on the curve or in compressed form given as <sign> <x> where <sign> is 0x02 if ''y'' is even and 0x03 if ''y'' is odd.<br />
<br />
Signatures use [http://en.wikipedia.org/wiki/Distinguished_Encoding_Rules DER encoding] to pack the ''r'' and ''s'' components into a single byte stream (this is also what OpenSSL produces by default).<br />
<br />
=== Transaction Verification ===<br />
Transactions are cryptographically signed records that reassign ownership of Bitcoins to new addresses. Transactions have ''inputs'' - records which reference the funds from other previous transactions - and ''outputs'' - records which determine the new owner of the transferred Bitcoins, and which will be referenced as inputs in future transactions as those funds are respent.<br />
<br />
Each ''input'' must have a cryptographic digital signature that unlocks the funds from the prior transaction. Only the person possessing the appropriate [[private key]] is able to create a satisfactory signature; this in effect ensures that funds can only be spent by their owners.<br />
<br />
Each ''output'' determines which Bitcoin address (or other criteria, see [[Script]]) is the recipient of the funds.<br />
<br />
In a transaction, the sum of all inputs must be equal to or greater than the sum of all outputs. If the inputs exceed the outputs, the difference is considered a [[transaction fee]], and is redeemable by whoever first includes the transaction into the block chain.<br />
<br />
A special kind of transaction, called a [[coinbase transaction]], has no inputs. It is created by [[miners]], and there is one coinbase transaction per block. Because each block comes with a reward of newly created Bitcoins (e.g. 50 BTC for the first 210,000 blocks), the first transaction of a block is, with few exceptions, the transaction that grants those coins to their recipient (the miner). In addition to the newly created Bitcoins, the coinbase transaction is also used for assigning the recipient of any transaction fees that were paid within the other transactions being included in the same block. The coinbase transaction can assign the entire reward to a single Bitcoin address, or split it in portions among multiple addresses, just like any other transaction. Coinbase transactions always contain outputs totalling the sum of the block reward plus all transaction fees collected from the other transactions in the same block.<br />
<br />
The [[coinbase transaction]] in block zero cannot be spent. This is due to a quirk of the reference client implementation that would open the potential for a block chain fork if some nodes accepted the spend and others did not<ref>[http://bitcointalk.org/index.php?topic=119645.msg1288552#msg1288552 Block 0 Network Fork]</ref>.<br />
<br />
Most Bitcoin outputs encumber the newly transferred coins with a single ECDSA private key. The actual record saved with inputs and outputs isn't necessarily a key, but a ''script''. Bitcoin uses an interpreted scripting system to determine whether an output's criteria have been satisfied, with which more complex operations are possible, such as outputs that require two ECDSA signatures, or two-of-three-signature schemes. An output that references a single Bitcoin address is a ''typical'' output; an output actually contains this information in the form of a script that requires a single ECDSA signature (see [[OP_CHECKSIG]]). The output script specifies what must be provided to unlock the funds later, and when the time comes in the future to spend the transaction in another input, that input must provide all of the thing(s) that satisfy the requirements defined by the original output script.<br />
<br />
=== Addresses ===<br />
<br />
A bitcoin address is in fact the hash of a ECDSA public key, computed this way:<br />
<br />
Version = 1 byte of 0 (zero); on the test network, this is 1 byte of 111<br />
Key hash = Version concatenated with RIPEMD-160(SHA-256(public key))<br />
Checksum = 1st 4 bytes of SHA-256(SHA-256(Key hash))<br />
Bitcoin Address = Base58Encode(Key hash concatenated with Checksum)<br />
<br />
The Base58 encoding used is home made, and has some differences. Especially, leading zeroes are kept as single zeroes when conversion happens.<br />
<br />
== Common structures ==<br />
<br />
Almost all integers are encoded in little endian. Only IP or port number are encoded big endian.<br />
<br />
=== Message structure ===<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown<br />
|-<br />
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| 4 || length || uint32_t || Length of payload in number of bytes<br />
|-<br />
| 4 || checksum || uint32_t || First 4 bytes of sha256(sha256(payload))<br />
|-<br />
| ? || payload || uchar[] || The actual data<br />
|}<br />
<br />
<br />
Known magic values:<br />
<br />
{|class="wikitable"<br />
! Network !! Magic value !! Sent over wire as<br />
|-<br />
| main || 0xD9B4BEF9 || F9 BE B4 D9<br />
|-<br />
| testnet || 0xDAB5BFFA || FA BF B5 DA<br />
|-<br />
| testnet3 || 0x0709110B || 0B 11 09 07<br />
|-<br />
| namecoin || 0xFEB4BEF9 || F9 BE B4 FE<br />
|}<br />
<br />
=== Variable length integer ===<br />
<br />
Integer can be encoded depending on the represented value to save space.<br />
Variable length integers always precede an array/vector of a type of data that may vary in length.<br />
Longer numbers are encoded in little endian.<br />
<br />
{|class="wikitable"<br />
! Value !! Storage length !! Format<br />
|-<br />
| < 0xFD || 1 || uint8_t<br />
|-<br />
| <= 0xFFFF || 3 || 0xFD followed by the length as uint16_t<br />
|-<br />
| <= 0xFFFF FFFF || 5 || 0xFE followed by the length as uint32_t<br />
|-<br />
| - || 9 || 0xFF followed by the length as uint64_t<br />
|}<br />
<br />
If you're reading the Satoshi client code (BitcoinQT) it refers to this encoding as a "CompactSize". Modern BitcoinQT also has the CVarInt class which implements an even more compact integer for the purpose of local storage (which is incompatible with "CompactSize" described here). CVarInt is not a part of the protocol.<br />
<br />
=== Variable length string ===<br />
<br />
Variable length string can be stored using a variable length integer followed by the string itself.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the string<br />
|-<br />
| ? || string || char[] || The string itself (can be empty)<br />
|}<br />
<br />
=== Network address ===<br />
<br />
When a network address is needed somewhere, this structure is used. Network addresses are not prefixed with a timestamp in the version message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || time || uint32 || the Time (version >= 31402). '''Not present in version message.'''<br />
|-<br />
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]<br />
|-<br />
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The original client only supported IPv4 and only read the last 4 bytes to get the IPv4 address. However, the IPv4 address is written into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]<br />
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).<br />
|-<br />
| 2 || port || uint16_t || port number, network byte order<br />
|}<br />
<br />
Hexdump example of Network address structure<br />
<br />
<pre><br />
0000 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0010 00 00 FF FF 0A 00 00 01 20 8D ........ .<br />
<br />
Network address:<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK: see services listed under version command)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv6: ::ffff:a00:1 or IPv4: 10.0.0.1<br />
20 8D - Port 8333<br />
</pre><br />
<br />
=== Inventory Vectors ===<br />
<br />
Inventory vectors are used for notifying other nodes about objects they have or data which is being requested.<br />
<br />
Inventory vectors consist of the following data format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || type || uint32_t || Identifies the object type linked to this inventory<br />
|-<br />
| 32 || hash || char[32] || Hash of the object<br />
|}<br />
<br />
<br />
The object type is currently defined as one of the following possibilities:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0 || ERROR || Any data of with this number may be ignored<br />
|-<br />
| 1 || MSG_TX || Hash is related to a transaction<br />
|-<br />
| 2 || MSG_BLOCK || Hash is related to a data block<br />
|-<br />
| 3 || MSG_FILTERED_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a merkleblock message rather than a block message; this only works if a bloom filter has been set.<br />
|-<br />
| 4 || MSG_CMPCT_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a cmpctblock message. See BIP 152 for more info.<br />
|}<br />
<br />
Other Data Type values are considered reserved for future implementations.<br />
<br />
=== Block Headers ===<br />
<br />
Block headers are sent in a headers packet in response to a getheaders message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Will overflow in 2106<ref>https://en.wikipedia.org/wiki/Unix_time#Notable_events_in_Unix_time</ref>)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 1 || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries, this value is always 0<br />
|}<br />
<br />
cf. [[Block hashing algorithm]]<br />
<br />
== Message types ==<br />
<br />
=== version ===<br />
<br />
When a node creates an outgoing connection, it will immediately [[Version Handshake|advertise]] its version. The remote node will respond with its version. No further communication is possible until both peers have exchanged their version.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Identifies protocol version being used by the node<br />
|-<br />
| 8 || services || uint64_t || bitfield of features to be enabled for this connection<br />
|-<br />
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds<br />
|-<br />
| 26 || addr_recv || [[#Network address|net_addr]] || The network address of the node receiving this message<br />
|-<br />
|colspan="4"| Fields below require version ≥ 106<br />
|-<br />
| 26 || addr_from || [[#Network address|net_addr]] || The network address of the node emitting this message<br />
|-<br />
| 8 || nonce || uint64_t || Node random nonce, randomly generated every time a version packet is sent. This nonce is used to detect connections to self.<br />
|-<br />
| ? || user_agent || [[#Variable length string|var_str]] || [https://github.com/bitcoin/bips/blob/master/bip-0014.mediawiki User Agent] (0x00 if string is 0 bytes long)<br />
|-<br />
| 4 || start_height || int32_t || The last block received by the emitting node<br />
|-<br />
|colspan="4"| Fields below require version ≥ 70001<br />
|-<br />
| 1 || relay || bool || Whether the remote peer should announce relayed transactions or not, see [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037]<br />
|}<br />
<br />
A "verack" packet shall be sent if the version packet was accepted.<br />
<br />
The following services are currently assigned:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 1 || NODE_NETWORK || This node can be asked for full blocks instead of just headers.<br />
|}<br />
<br />
Hexdump example of version message (OBSOLETE EXAMPLE: This example lacks a checksum and user-agent):<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....<br />
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........<br />
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............<br />
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................<br />
0040 20 8D 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,<br />
0060 3A B4 57 13 00 55 81 01 00 :.W..U...<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
55 00 00 00 - Payload is 85 bytes long<br />
- No checksum in version message until 20 February 2012. See https://bitcointalk.org/index.php?topic=55852.0<br />
Version message:<br />
9C 7C 00 00 - 31900 (version 0.3.19)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
E6 15 10 4D 00 00 00 00 - Mon Dec 20 21:50:14 EST 2010<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 20 8D - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D - Sender address info - see Network Address<br />
DD 9D 20 2C 3A B4 57 13 - Node random unique ID<br />
00 - "" sub-version string (string is 0 bytes long)<br />
55 81 01 00 - Last block sending node has is block #98645<br />
</pre><br />
<br />
And here's a modern (60002) protocol version client advertising itself to a local peer...<br />
<br />
Newer protocol includes the checksum now, this is from a mainline (satoshi) client during <br />
an outgoing connection to another local client, notice that it does not fill out the <br />
address information at all when the source or destination is "unroutable".<br />
<br />
<pre><br />
<br />
0000 f9 be b4 d9 76 65 72 73 69 6f 6e 00 00 00 00 00 ....version.....<br />
0010 64 00 00 00 35 8d 49 32 62 ea 00 00 01 00 00 00 d...5.I2b.......<br />
0020 00 00 00 00 11 b2 d0 50 00 00 00 00 01 00 00 00 .......P........<br />
0030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ff ff ................<br />
0040 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 00 00 00 00 ff ff 00 00 00 00 00 00 ................<br />
0060 3b 2e b3 5d 8c e6 17 65 0f 2f 53 61 74 6f 73 68 ;..]...e./Satosh<br />
0070 69 3a 30 2e 37 2e 32 2f c0 3e 03 00 i:0.7.2/.>..<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
64 00 00 00 - Payload is 100 bytes long<br />
3B 64 8D 5A - payload checksum<br />
<br />
Version message:<br />
62 EA 00 00 - 60002 (protocol version 60002)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
11 B2 D0 50 00 00 00 00 - Tue Dec 18 10:12:33 PST 2012<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Sender address info - see Network Address<br />
3B 2E B3 5D 8C E6 17 65 - Node ID<br />
0F 2F 53 61 74 6F 73 68 69 3A 30 2E 37 2E 32 2F - "/Satoshi:0.7.2/" sub-version string (string is 15 bytes long)<br />
C0 3E 03 00 - Last block sending node has is block #212672<br />
</pre><br />
<br />
=== verack ===<br />
<br />
The ''verack'' message is sent in reply to ''[[#version|version]]''. This message consists of only a [[#Message structure|message header]] with the command string "verack".<br />
<br />
Hexdump of the verack message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......<br />
0010 00 00 00 00 5D F6 E0 E2 ........<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 61 63 6B 00 00 00 00 00 00 - "verack" command<br />
00 00 00 00 - Payload is 0 bytes long<br />
5D F6 E0 E2 - Checksum<br />
</pre><br />
<br />
=== addr ===<br />
<br />
Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours<br />
<br />
Payload:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of address entries (max: 1000)<br />
|-<br />
| 30x? || addr_list || (uint32_t + [[#Network address|net_addr]])[] || Address of other nodes on the network. version < 209 will only read the first one. The uint32_t is a timestamp (see note below).<br />
|}<br />
<br />
'''Note''': Starting version 31402, addresses are prefixed with a timestamp. If no timestamp is present, the addresses should not be relayed to other peers, unless it is indeed confirmed they are up.<br />
<br />
Hexdump example of ''addr'' message:<br />
<pre><br />
0000 F9 BE B4 D9 61 64 64 72 00 00 00 00 00 00 00 00 ....addr........<br />
0010 1F 00 00 00 ED 52 39 9B 01 E2 15 10 4D 01 00 00 .....R9.....M...<br />
0020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF ................<br />
0030 FF 0A 00 00 01 20 8D ..... .<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
61 64 64 72 00 00 00 00 00 00 00 00 - "addr"<br />
1F 00 00 00 - payload is 31 bytes long<br />
ED 52 39 9B - checksum of payload<br />
<br />
Payload:<br />
01 - 1 address in this message<br />
<br />
Address:<br />
E2 15 10 4D - Mon Dec 20 21:50:10 EST 2010 (only when version is >= 31402)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK service - see version message)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv4: 10.0.0.1, IPv6: ::ffff:10.0.0.1 (IPv4-mapped IPv6 address)<br />
20 8D - port 8333<br />
</pre><br />
<br />
=== inv ===<br />
<br />
Allows a node to advertise its knowledge of one or more objects. It can be received unsolicited, or in reply to ''getblocks''.<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getdata ===<br />
<br />
getdata is used in response to inv, to retrieve the content of a specific object, and is usually sent after receiving an ''inv'' packet, after filtering known elements. It can be used to retrieve transactions, but only if they are in the memory pool or relay set - arbitrary access to transactions in the chain is not allowed to avoid having clients start to depend on nodes having full transaction indexes (which modern nodes do not).<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== notfound ===<br />
<br />
notfound is a response to a getdata, sent if any requested data items could not be relayed, for example, because the requested transaction was not in the memory pool or relay set.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getblocks ===<br />
<br />
Return an ''inv'' packet containing the list of blocks starting right after the last known hash in the block locator object, up to hash_stop or 500 blocks, whichever comes first. <br />
<br />
The locator hashes are processed by a node in the order as they appear in the message. If a block hash is found in the node's main chain, the list of its children is returned back via the ''inv'' message and the remaining locators are ignored, no matter if the requested limit was reached, or not.<br />
<br />
To receive the next blocks hashes, one needs to issue getblocks again with a new block locator object. Keep in mind that some clients may provide blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block; set to zero to get as many blocks as possible (500)<br />
|}<br />
<br />
To create the block locator hashes, keep pushing hashes until you go back to the genesis block. After pushing 10 hashes back, the step backwards doubles every loop:<br />
<br />
<pre><br />
// From libbitcoin which is under AGPL<br />
std::vector<size_t> block_locator_indexes(size_t top_height)<br />
{<br />
std::vector<size_t> indexes;<br />
<br />
// Modify the step in the iteration.<br />
int64_t step = 1;<br />
<br />
// Start at the top of the chain and work backwards.<br />
for (auto index = (int64_t)top_height; index > 0; index -= step)<br />
{<br />
// Push top 10 indexes first, then back off exponentially.<br />
if (indexes.size() >= 10)<br />
step *= 2;<br />
<br />
indexes.push_back((size_t)index);<br />
}<br />
<br />
// Push the genesis block index.<br />
indexes.push_back(0);<br />
return indexes;<br />
}<br />
</pre><br />
<br />
Note that it is allowed to send in fewer known hashes down to a minimum of just one hash. However, the purpose of the block locator object is to detect a wrong branch in the caller's main chain. If the peer detects that you are off the main chain, it will send in block hashes which are earlier than your last known block. So if you just send in your last known hash and it is off the main chain, the peer starts over at block #1.<br />
<br />
=== getheaders ===<br />
<br />
Return a ''headers'' packet containing the headers of blocks starting right after the last known hash in the block locator object, up to hash_stop or 2000 blocks, whichever comes first. To receive the next block headers, one needs to issue getheaders again with a new block locator object. The ''getheaders'' command is used by thin clients to quickly download the block chain where the contents of the transactions would be irrelevant (because they are not ours). Keep in mind that some clients may provide headers of blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block header; set to zero to get as many blocks as possible (2000)<br />
|}<br />
<br />
For the block locator object in this packet, the same rules apply as for the [[Protocol_documentation#getblocks|getblocks]] packet.<br />
<br />
=== tx ===<br />
<br />
''tx'' describes a bitcoin transaction, in reply to ''[[#getdata|getdata]]''<br />
<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Transaction data format version (note, this is signed)<br />
|-<br />
| 1+ || tx_in count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction inputs<br />
|-<br />
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins<br />
|-<br />
| 1+ || tx_out count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction outputs<br />
|-<br />
| 9+ || tx_out || tx_out[] || A list of 1 or more transaction outputs or destinations for coins<br />
|-<br />
| 4 || lock_time || uint32_t || The block number or timestamp at which this transaction is locked:<br />
{|class="wikitable"<br />
! Value !! Description<br />
|-<br />
| 0 || Not locked<br />
|-<br />
| < 500000000 || Block number at which this transaction is locked<br />
|-<br />
| >= 500000000 || UNIX timestamp at which this transaction is locked<br />
|}<br />
If all TxIn inputs have final (0xffffffff) sequence numbers then lock_time is irrelevant. Otherwise, the transaction may not be added to a block until after lock_time (see [[NLockTime]]).<br />
<br />
|}<br />
<br />
TxIn consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 36 || previous_output || outpoint || The previous output transaction reference, as an OutPoint structure<br />
|-<br />
| 1+ || script length || [[Protocol_documentation#Variable_length_integer|var_int]] || The length of the signature script<br />
|-<br />
| ? || signature script || uchar[] || Computational Script for confirming transaction authorization<br />
|-<br />
| 4 || [http://bitcoin.stackexchange.com/q/2025/323 sequence] || uint32_t || Transaction version as defined by the sender. Intended for "replacement" of transactions when information is updated before inclusion into a block.<br />
|}<br />
<br />
The OutPoint structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 32 || hash || char[32] || The hash of the referenced transaction.<br />
|-<br />
| 4 || index || uint32_t || The index of the specific output in the transaction. The first output is 0, etc.<br />
|}<br />
<br />
The Script structure consists of a series of pieces of information and operations related to the value of the transaction.<br />
<br />
(Structure to be expanded in the future… see script.h and script.cpp and [[Script]] for more information)<br />
<br />
The TxOut structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || value || int64_t || Transaction Value<br />
|-<br />
| 1+ || pk_script length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the pk_script<br />
|-<br />
| ? || pk_script || uchar[] || Usually contains the public key as a Bitcoin script setting up conditions to claim this output.<br />
|}<br />
<br />
Example ''tx'' message:<br />
<pre><br />
000000 F9 BE B4 D9 74 78 00 00 00 00 00 00 00 00 00 00 ....tx..........<br />
000010 02 01 00 00 E2 93 CD BE 01 00 00 00 01 6D BD DB .............m..<br />
000020 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D 12 66 E9 .[...Q........f.<br />
000030 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29 00 00 00 .;P......j.6)...<br />
000040 00 8B 48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 ..H0E.!..X..r...<br />
000050 C7 36 7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A .6zz%;..R#...h.:<br />
000060 59 23 3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 Y#?E.W... Y.....<br />
000070 0E 41 83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D .A.z.X.z...XN...<br />
000080 35 BD 96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF 5...6..;...A....<br />
000090 C9 7E F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 .~.6.m...@..!...<br />
0000A0 2A CD 2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC *.+..].}Y... ...<br />
0000B0 4E 02 53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F N.S..=7.o...Q...<br />
0000C0 14 04 2F 46 61 4A 4C 70 C0 F1 4B EF F5 FF FF FF ../FaJLp..K.....<br />
0000D0 FF 02 40 4B 4C 00 00 00 00 00 19 76 A9 14 1A A0 ..@KL......v....<br />
0000E0 CD 1C BE A6 E7 45 8A 7A BA D5 12 A9 D9 EA 1A FB .....E.z........<br />
0000F0 22 5E 88 AC 80 FA E9 C7 00 00 00 00 19 76 A9 14 "^...........v..<br />
000100 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E FD A0 B7 ..[.Cj.....H^...<br />
000110 8B 4E CC 52 88 AC 00 00 00 00 .N.R......<br />
<br />
<br />
Message header:<br />
F9 BE B4 D9 - main network magic bytes<br />
74 78 00 00 00 00 00 00 00 00 00 00 - "tx" command<br />
02 01 00 00 - payload is 258 bytes long<br />
E2 93 CD BE - checksum of payload<br />
<br />
Transaction:<br />
01 00 00 00 - version<br />
<br />
Inputs:<br />
01 - number of transaction inputs<br />
<br />
Input 1:<br />
6D BD DB 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D - previous output (outpoint)<br />
12 66 E9 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29<br />
00 00 00 00<br />
<br />
8B - script is 139 bytes long<br />
<br />
48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 C7 36 - signature script (scriptSig)<br />
7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A 59 23<br />
3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 0E 41<br />
83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D 35 BD<br />
96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF C9 7E<br />
F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 2A CD<br />
2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC 4E 02<br />
53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F 14 04<br />
2F 46 61 4A 4C 70 C0 F1 4B EF F5<br />
<br />
FF FF FF FF - sequence<br />
<br />
Outputs:<br />
02 - 2 Output Transactions<br />
<br />
Output 1:<br />
40 4B 4C 00 00 00 00 00 - 0.05 BTC (5000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 1A A0 CD 1C BE A6 E7 45 8A 7A BA D5 12 - pk_script<br />
A9 D9 EA 1A FB 22 5E 88 AC<br />
<br />
Output 2:<br />
80 FA E9 C7 00 00 00 00 - 33.54 BTC (3354000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E - pk_script<br />
FD A0 B7 8B 4E CC 52 88 AC<br />
<br />
Locktime:<br />
00 00 00 00 - lock time<br />
</pre><br />
<br />
=== block ===<br />
<br />
The '''block''' message is sent in response to a getdata message which requests transaction information from a block hash.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A Unix timestamp recording when this block was created (Currently limited to dates before the year 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated [[Difficulty|difficulty target]] being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| ? || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries<br />
|-<br />
| ? || txns || tx[] || Block transactions, in format of "tx" command<br />
|}<br />
<br />
The SHA256 hash that identifies each block (and which must have a run of 0 bits) is calculated from the first 6 fields of this structure (version, prev_block, merkle_root, timestamp, bits, nonce, and standard SHA256 padding, making two 64-byte chunks in all) and ''not'' from the complete block. To calculate the hash, only two chunks need to be processed by the SHA256 algorithm. Since the ''nonce'' field is in the second chunk, the first chunk stays constant during mining and therefore only the second chunk needs to be processed. However, a Bitcoin hash is the hash of the hash, so two SHA256 rounds are needed for each mining iteration.<br />
See [[Block hashing algorithm]] for details and an example.<br />
<br />
=== headers ===<br />
<br />
The ''headers'' packet returns block headers in response to a ''getheaders'' packet. <br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of block headers<br />
|-<br />
| 81x? || headers || [[Protocol_documentation#Block_Headers|block_header]][] || [[Protocol_documentation#Block_Headers|Block headers]]<br />
|}<br />
<br />
Note that the block headers in this packet include a transaction count (a var_int, so there can be more than 81 bytes per header) as opposed to the block headers that are hashed by miners.<br />
<br />
=== getaddr ===<br />
<br />
The getaddr message sends a request to a node asking for information about known active peers to help with finding potential nodes in the network. The response to receiving this message is to transmit one or more addr messages with one or more peers from a database of known active peers. The typical presumption is that a node is likely to be active if it has been sending a message within the last three hours.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
=== mempool ===<br />
<br />
The mempool message sends a request to a node asking for information about transactions it has verified but which have not yet confirmed. The response to receiving this message is an inv message containing the transaction hashes for all the transactions in the node's mempool.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
It is specified in [https://github.com/bitcoin/bips/blob/master/bip-0035.mediawiki BIP 35]. Since [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 37], if a [[Protocol_documentation#filterload.2C_filteradd.2C_filterclear.2C_merkleblock|bloom filter]] is loaded, only transactions matching the filter are replied.<br />
<br />
=== checkorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== submitorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== reply ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== ping ===<br />
<br />
The ''ping'' message is sent primarily to confirm that the TCP/IP connection is still valid. An error in transmission is presumed to be a closed connection and the address is removed as a current peer.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || random nonce<br />
|}<br />
<br />
=== pong ===<br />
<br />
The ''pong'' message is sent in response to a ''ping'' message. In modern protocol versions, a ''pong'' response is generated using a nonce included in the ping.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || nonce from ping<br />
|}<br />
<br />
<br />
=== reject===<br />
<br />
The ''reject'' message is sent when messages are rejected.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || message || var_str || type of message rejected<br />
|-<br />
| 1 || ccode || char || code relating to rejected message<br />
|-<br />
| 1+ || reason || var_str || text version of reason for rejection<br />
|-<br />
| 0+ || data || char || Optional extra data provided by some errors. Currently, all errors which provide this field fill it with the TXID or block header hash of the object being rejected, so the field is 32 bytes.<br />
|}<br />
<br />
CCodes<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0x01 || REJECT_MALFORMED|| <br />
|-<br />
| 0x10 || REJECT_INVALID ||<br />
|-<br />
| 0x11 || REJECT_OBSOLETE ||<br />
|-<br />
| 0x12 || REJECT_DUPLICATE ||<br />
|-<br />
| 0x40 || REJECT_NONSTANDARD ||<br />
|-<br />
| 0x41 || REJECT_DUST ||<br />
|-<br />
| 0x42 || REJECT_INSUFFICIENTFEE ||<br />
|-<br />
| 0x43 || REJECT_CHECKPOINT ||<br />
|}<br />
<br />
=== filterload, filteradd, filterclear, merkleblock ===<br />
<br />
These messages are related to Bloom filtering of connections and are defined in [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037].<br />
<br />
<br />
The <code>filterload</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || filter || uint8_t[] || The filter itself is simply a bit field of arbitrary byte-aligned size. The maximum size is 36,000 bytes.<br />
|-<br />
| 4 || nHashFuncs || uint32_t || The number of hash functions to use in this filter. The maximum value allowed in this field is 50.<br />
|-<br />
| 4 || nTweak || uint32_t || A random value to add to the seed value in the hash function used by the bloom filter.<br />
|-<br />
| 1 || nFlags || uint8_t || A set of flags that control how matched items are added to the filter.<br />
|}<br />
<br />
See below for a description of the Bloom filter algorithm and how to select nHashFuncs and filter size for a desired false positive rate.<br />
<br />
Upon receiving a <code>filterload</code> command, the remote peer will immediately restrict the broadcast transactions it announces (in inv packets) to transactions matching the filter, where the matching algorithm is specified below. The flags control the update behaviour of the matching algorithm.<br />
<br />
The <code>filteradd</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || data || uint8_t[] || The data element to add to the current filter.<br />
|}<br />
<br />
The data field must be smaller than or equal to 520 bytes in size (the maximum size of any potentially matched object).<br />
<br />
The given data element will be added to the Bloom filter. A filter must have been previously provided using <code>filterload</code>. This command is useful if a new key or script is added to a clients wallet whilst it has connections to the network open, it avoids the need to re-calculate and send an entirely new filter to every peer (though doing so is usually advisable to maintain anonymity).<br />
<br />
The <code>filterclear</code> command has no arguments at all.<br />
<br />
After a filter has been set, nodes don't merely stop announcing non-matching transactions, they can also serve filtered blocks. A filtered block is defined by the <code>merkleblock</code> message and is defined like this:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information, based upon the software version creating this block (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Limited to 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 4 || total_transactions || uint32_t || Number of transactions in the block (including unmatched ones)<br />
|-<br />
| ? || hashes || uint256[] || hashes in depth-first order (including standard varint size prefix)<br />
|-<br />
| ? || flags || byte[] || flag bits, packed per 8 in a byte, least significant bit first (including standard varint size prefix)<br />
|}<br />
<br />
=== alert ===<br />
<br />
An '''alert''' is sent between nodes to send a general notification message throughout the network. If the alert can be confirmed with the signature as having come from the core development group of the Bitcoin software, the message is suggested to be displayed for end-users. Attempts to perform transactions, particularly automated transactions through the client, are suggested to be halted. The text in the Message string should be relayed to log files and any user interfaces.<br />
<br />
Alert format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || payload || uchar[] || Serialized alert payload<br />
|-<br />
| ? || signature || uchar[] || An ECDSA signature of the message<br />
|}<br />
<br />
The developers of Satoshi's client use this public key for signing alerts:<br />
04fc9702847840aaf195de8442ebecedf5b095cdbb9bc716bda9110971b28a49e0ead8564ff0db22209e0374782c093bb899692d524e9d6a6956e7c5ecbcd68284<br />
(hash) 1AGRxqDa5WjUKBwHB9XYEjmkv1ucoUUy1s<br />
<br />
The payload is serialized into a uchar[] to ensure that versions using incompatible alert formats can still relay alerts among one another. The current alert payload format is:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || Version || int32_t || Alert format version<br />
|-<br />
| 8 || RelayUntil || int64_t || The timestamp beyond which nodes should stop relaying this alert<br />
|-<br />
| 8 || Expiration || int64_t || The timestamp beyond which this alert is no longer in effect and should be ignored<br />
|-<br />
| 4 || ID || int32_t || A unique ID number for this alert<br />
|-<br />
| 4 || Cancel || int32_t || All alerts with an ID number less than or equal to this number should be cancelled: deleted and not accepted in the future<br />
|-<br />
| ? || setCancel || set<int32_t> || All alert IDs contained in this set should be cancelled as above<br />
|-<br />
| 4 || MinVer || int32_t || This alert only applies to versions greater than or equal to this version. Other versions should still relay it.<br />
|-<br />
| 4 || MaxVer || int32_t || This alert only applies to versions less than or equal to this version. Other versions should still relay it.<br />
|-<br />
| ? || setSubVer || set<string> || If this set contains any elements, then only nodes that have their subVer contained in this set are affected by the alert. Other versions should still relay it.<br />
|-<br />
| 4 || Priority || int32_t || Relative priority compared to other alerts<br />
|-<br />
| ? || Comment || string || A comment on the alert that is not displayed<br />
|-<br />
| ? || StatusBar || string || The alert message that is displayed to the user<br />
|-<br />
| ? || Reserved || string || Reserved<br />
|}<br />
<br />
Note: '''set<''type''>''' in the table above is a [[#Variable length integer | variable length integer]] followed by the number of fields of the given ''type'' (either int32_t or [[#Variable length string | variable length string]])<br />
<br />
Sample alert (no message header):<br />
73010000003766404f00000000b305434f00000000f2030000f1030000001027000048ee0000<br />
0064000000004653656520626974636f696e2e6f72672f666562323020696620796f75206861<br />
76652074726f75626c6520636f6e6e656374696e672061667465722032302046656272756172<br />
79004730450221008389df45f0703f39ec8c1cc42c13810ffcae14995bb648340219e353b63b<br />
53eb022009ec65e1c1aaeec1fd334c6b684bde2b3f573060d5b70c3a46723326e4e8a4f1<br />
<br />
Version: 1<br />
RelayUntil: 1329620535<br />
Expiration: 1329792435<br />
ID: 1010<br />
Cancel: 1009<br />
setCancel: <empty><br />
MinVer: 10000<br />
MaxVer: 61000<br />
setSubVer: <empty><br />
Priority: 100<br />
Comment: <empty><br />
StatusBar: "See bitcoin.org/feb20 if you have trouble connecting after 20 February"<br />
Reserved: <empty><br />
<br />
=== sendheaders ===<br />
<br />
Request for Direct headers announcement. <br />
<br />
Upon receipt of this message, the node is be permitted, but not required, to announce new blocks by '''headers''' command (instead of '''inv''' command).<br />
<br />
This message is supported by the protocol version >= 70012 or Bitcoin Core version >= 0.12.0.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0130.mediawiki BIP 130] for more information.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
<br />
=== feefilter ===<br />
<br />
The payload is always 8 bytes long and it encodes 64 bit integer value (LSB / little endian) of '''feerate'''.<br />
The value represents a minimal fee and is expressed in satoshis per 1000 bytes.<br />
<br />
Upon receipt of a "feefilter" message, the node will be permitted, but not required, to filter transaction invs for transactions that fall below the feerate provided in the feefilter message interpreted as satoshis per kilobyte.<br />
<br />
The fee filter is additive with a bloom filter for transactions so if an SPV client were to load a bloom filter and send a feefilter message, transactions would only be relayed if they passed both filters.<br />
<br />
Inv's generated from a mempool message are also subject to a fee filter if it exists.<br />
<br />
Feature discovery is enabled by checking protocol version >= 70013<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0133.mediawiki BIP 133] for more information.<br />
<br />
=== sendcmpct ===<br />
<br />
# The sendcmpct message is defined as a message containing a 1-byte integer followed by a 8-byte integer where pchCommand == "sendcmpct".<br />
# The first integer SHALL be interpreted as a boolean (and MUST have a value of either 1 or 0)<br />
# The second integer SHALL be interpreted as a little-endian version number. Nodes sending a sendcmpct message MUST currently set this value to 1.<br />
# Upon receipt of a "sendcmpct" message with the first and second integers set to 1, the node SHOULD announce new blocks by sending a cmpctblock message.<br />
# Upon receipt of a "sendcmpct" message with the first integer set to 0, the node SHOULD NOT announce new blocks by sending a cmpctblock message, but SHOULD announce new blocks by sending invs or headers, as defined by BIP130.<br />
# Upon receipt of a "sendcmpct" message with the second integer set to something other than 1, nodes MUST treat the peer as if they had not received the message (as it indicates the peer will provide an unexpected encoding in <br />
# cmpctblock, and/or other, messages). This allows future versions to send duplicate sendcmpct messages with different versions as a part of a version handshake for future versions.<br />
# Nodes SHOULD check for a protocol version of >= 70014 before sending sendcmpct messages.<br />
# Nodes MUST NOT send a request for a MSG_CMPCT_BLOCK object to a peer before having received a sendcmpct message from that peer.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== cmpctblock ===<br />
<br />
# The cmpctblock message is defined as as a message containing a serialized HeaderAndShortIDs message and pchCommand == "cmpctblock".<br />
# Upon receipt of a cmpctblock message after sending a sendcmpct message, nodes SHOULD calculate the short transaction ID for each unconfirmed transaction they have available (ie in their mempool) and compare each to each short transaction ID in the cmpctblock message.<br />
# After finding already-available transactions, nodes which do not have all transactions available to reconstruct the full block SHOULD request the missing transactions using a getblocktxn message.<br />
# A node MUST NOT send a cmpctblock message unless they are able to respond to a getblocktxn message which requests every transaction in the block.<br />
# A node MUST NOT send a cmpctblock message without having validated that the header properly commits to each transaction in the block, and properly builds on top of the existing chain with a valid proof-of-work. A node MAY send a cmpctblock before validating that each transaction in the block validly spends existing UTXO set entries.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== getblocktxn ===<br />
<br />
# The getblocktxn message is defined as as a message containing a serialized BlockTransactionsRequest message and pchCommand == "getblocktxn".<br />
# Upon receipt of a properly-formatted getblocktxnmessage, nodes which recently provided the sender of such a message a cmpctblock for the block hash identified in this message MUST respond with an appropriate blocktxn message. Such a blocktxn message MUST contain exactly and only each transaction which is present in the appropriate block at the index specified in the getblocktxn indexes list, in the order requested.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
=== blocktxn ===<br />
<br />
# The blocktxn message is defined as as a message containing a serialized BlockTransactions message and pchCommand == "blocktxn".<br />
# Upon receipt of a properly-formatted requested blocktxn message, nodes SHOULD attempt to reconstruct the full block by:<br />
# Taking the prefilledtxn transactions from the original cmpctblock and placing them in the marked positions.<br />
# For each short transaction ID from the original cmpctblock, in order, find the corresponding transaction either from the blocktxn message or from other sources and place it in the first available position in the block.<br />
# Once the block has been reconstructed, it shall be processed as normal, keeping in mind that short transaction IDs are expected to occasionally collide, and that nodes MUST NOT be penalized for such collisions, wherever they # appear.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0152.mediawiki BIP 152] for more information.<br />
<br />
== Scripting ==<br />
<br />
See [[script]].<br />
<br />
==See Also==<br />
<br />
* [[Network]]<br />
* [[Protocol rules]]<br />
* [[Hardfork Wishlist]]<br />
* [https://bitcoin.org/en/developer-documentation Developer Documentation on bitcoin.org]<br />
* Bitcoin dissectors for Wireshark: https://github.com/lbotsch/wireshark-bitcoin https://github.com/op-sig/bitcoin-wireshark-dissector<br />
<br />
==References==<br />
<references /><br />
<br />
[[zh-cn:协议说明]]<br />
[[Category:Technical]]<br />
[[Category:Developer]]<br />
<br />
{{Bitcoin Core documentation}}</div>Tonikthttps://en.bitcoin.it/w/index.php?title=Protocol_documentation&diff=61482Protocol documentation2016-08-25T12:17:41Z<p>Tonikt: Added getdata type MSG_CMPCT_BLOCK</p>
<hr />
<div>This page ''describes'' the behavior of the [[Original Bitcoin client|reference client]]. The Bitcoin protocol is specified by the behavior of the reference client, not by this page. In particular, while this page is quite complete in describing the network protocol, it does not attempt to list all of the rules for block or transaction validity.<br />
<br />
Type names used in this documentation are from the C99 standard.<br />
<br />
For protocol used in mining, see [[getblocktemplate]].<br />
<br />
==Common standards==<br />
<br />
=== Hashes ===<br />
<br />
Usually, when a hash is computed within bitcoin, it is computed twice. Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-256] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when a shorter hash is desirable (for example when creating a bitcoin address).<br />
<br />
Example of double-SHA-256 encoding of string "hello":<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round of sha-256)<br />
9595c9df90075148eb06860365df33584b75bff782a510c6cd4883a419833d50 (second round of sha-256)<br />
<br />
For bitcoin addresses (RIPEMD-160) this would give:<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round is sha-256)<br />
b6a9c8c230722b7c748331a8b450f05566dc7d0f (with ripemd-160)<br />
<br />
=== Merkle Trees ===<br />
<br />
Merkle trees are binary trees of hashes. Merkle trees in bitcoin use a '''double''' SHA-256, the SHA-256 hash of the SHA-256 hash of something.<br />
<br />
If, when forming a row in the tree (other than the root of the tree), it would have an odd number of elements, the final double-hash is duplicated to ensure that the row has an even number of hashes.<br />
<br />
First form the bottom row of the tree with the ordered double-SHA-256 hashes of the byte streams of the transactions in the block.<br />
<br />
Then the row above it consists of half that number of hashes. Each entry is the double-SHA-256 of the 64-byte concatenation of the corresponding two hashes below it in the tree.<br />
<br />
This procedure repeats recursively until we reach a row consisting of just a single double-hash. This is the '''Merkle root''' of the tree.<br />
<br />
For example, imagine a block with three transactions ''a'', ''b'' and ''c''. The Merkle tree is: <br />
<br />
d1 = dhash(a)<br />
d2 = dhash(b)<br />
d3 = dhash(c)<br />
d4 = dhash(c) # a, b, c are 3. that's an odd number, so we take the c twice<br />
<br />
d5 = dhash(d1 concat d2)<br />
d6 = dhash(d3 concat d4)<br />
<br />
d7 = dhash(d5 concat d6)<br />
<br />
where<br />
<br />
dhash(a) = sha256(sha256(a))<br />
<br />
''d7'' is the Merkle root of the 3 transactions in this block.<br />
<br />
Note: Hashes in Merkle Tree displayed in the [[Block Explorer]] are of little-endian notation. For some implementations and [http://www.fileformat.info/tool/hash.htm calculations], the bits need to be reversed before they are hashed, and again after the hashing operation.<br />
<br />
=== Signatures ===<br />
<br />
Bitcoin uses [http://en.wikipedia.org/wiki/Elliptic_curve_cryptography Elliptic Curve] [http://en.wikipedia.org/wiki/Digital_Signature_Algorithm Digital Signature Algorithm] ([http://en.wikipedia.org/wiki/Elliptic_Curve_DSA ECDSA]) to sign transactions. <br />
<br />
For [[ECDSA]] the secp256k1 curve from http://www.secg.org/collateral/sec2_final.pdf is used.<br />
<br />
Public keys (in scripts) are given as 04 <x> <y> where ''x'' and ''y'' are 32 byte big-endian integers representing the coordinates of a point on the curve or in compressed form given as <sign> <x> where <sign> is 0x02 if ''y'' is even and 0x03 if ''y'' is odd.<br />
<br />
Signatures use [http://en.wikipedia.org/wiki/Distinguished_Encoding_Rules DER encoding] to pack the ''r'' and ''s'' components into a single byte stream (this is also what OpenSSL produces by default).<br />
<br />
=== Transaction Verification ===<br />
Transactions are cryptographically signed records that reassign ownership of Bitcoins to new addresses. Transactions have ''inputs'' - records which reference the funds from other previous transactions - and ''outputs'' - records which determine the new owner of the transferred Bitcoins, and which will be referenced as inputs in future transactions as those funds are respent.<br />
<br />
Each ''input'' must have a cryptographic digital signature that unlocks the funds from the prior transaction. Only the person possessing the appropriate [[private key]] is able to create a satisfactory signature; this in effect ensures that funds can only be spent by their owners.<br />
<br />
Each ''output'' determines which Bitcoin address (or other criteria, see [[Script]]) is the recipient of the funds.<br />
<br />
In a transaction, the sum of all inputs must be equal to or greater than the sum of all outputs. If the inputs exceed the outputs, the difference is considered a [[transaction fee]], and is redeemable by whoever first includes the transaction into the block chain.<br />
<br />
A special kind of transaction, called a [[coinbase transaction]], has no inputs. It is created by [[miners]], and there is one coinbase transaction per block. Because each block comes with a reward of newly created Bitcoins (e.g. 50 BTC for the first 210,000 blocks), the first transaction of a block is, with few exceptions, the transaction that grants those coins to their recipient (the miner). In addition to the newly created Bitcoins, the coinbase transaction is also used for assigning the recipient of any transaction fees that were paid within the other transactions being included in the same block. The coinbase transaction can assign the entire reward to a single Bitcoin address, or split it in portions among multiple addresses, just like any other transaction. Coinbase transactions always contain outputs totalling the sum of the block reward plus all transaction fees collected from the other transactions in the same block.<br />
<br />
The [[coinbase transaction]] in block zero cannot be spent. This is due to a quirk of the reference client implementation that would open the potential for a block chain fork if some nodes accepted the spend and others did not<ref>[http://bitcointalk.org/index.php?topic=119645.msg1288552#msg1288552 Block 0 Network Fork]</ref>.<br />
<br />
Most Bitcoin outputs encumber the newly transferred coins with a single ECDSA private key. The actual record saved with inputs and outputs isn't necessarily a key, but a ''script''. Bitcoin uses an interpreted scripting system to determine whether an output's criteria have been satisfied, with which more complex operations are possible, such as outputs that require two ECDSA signatures, or two-of-three-signature schemes. An output that references a single Bitcoin address is a ''typical'' output; an output actually contains this information in the form of a script that requires a single ECDSA signature (see [[OP_CHECKSIG]]). The output script specifies what must be provided to unlock the funds later, and when the time comes in the future to spend the transaction in another input, that input must provide all of the thing(s) that satisfy the requirements defined by the original output script.<br />
<br />
=== Addresses ===<br />
<br />
A bitcoin address is in fact the hash of a ECDSA public key, computed this way:<br />
<br />
Version = 1 byte of 0 (zero); on the test network, this is 1 byte of 111<br />
Key hash = Version concatenated with RIPEMD-160(SHA-256(public key))<br />
Checksum = 1st 4 bytes of SHA-256(SHA-256(Key hash))<br />
Bitcoin Address = Base58Encode(Key hash concatenated with Checksum)<br />
<br />
The Base58 encoding used is home made, and has some differences. Especially, leading zeroes are kept as single zeroes when conversion happens.<br />
<br />
== Common structures ==<br />
<br />
Almost all integers are encoded in little endian. Only IP or port number are encoded big endian.<br />
<br />
=== Message structure ===<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown<br />
|-<br />
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| 4 || length || uint32_t || Length of payload in number of bytes<br />
|-<br />
| 4 || checksum || uint32_t || First 4 bytes of sha256(sha256(payload))<br />
|-<br />
| ? || payload || uchar[] || The actual data<br />
|}<br />
<br />
<br />
Known magic values:<br />
<br />
{|class="wikitable"<br />
! Network !! Magic value !! Sent over wire as<br />
|-<br />
| main || 0xD9B4BEF9 || F9 BE B4 D9<br />
|-<br />
| testnet || 0xDAB5BFFA || FA BF B5 DA<br />
|-<br />
| testnet3 || 0x0709110B || 0B 11 09 07<br />
|-<br />
| namecoin || 0xFEB4BEF9 || F9 BE B4 FE<br />
|}<br />
<br />
=== Variable length integer ===<br />
<br />
Integer can be encoded depending on the represented value to save space.<br />
Variable length integers always precede an array/vector of a type of data that may vary in length.<br />
Longer numbers are encoded in little endian.<br />
<br />
{|class="wikitable"<br />
! Value !! Storage length !! Format<br />
|-<br />
| < 0xFD || 1 || uint8_t<br />
|-<br />
| <= 0xFFFF || 3 || 0xFD followed by the length as uint16_t<br />
|-<br />
| <= 0xFFFF FFFF || 5 || 0xFE followed by the length as uint32_t<br />
|-<br />
| - || 9 || 0xFF followed by the length as uint64_t<br />
|}<br />
<br />
If you're reading the Satoshi client code (BitcoinQT) it refers to this encoding as a "CompactSize". Modern BitcoinQT also has the CVarInt class which implements an even more compact integer for the purpose of local storage (which is incompatible with "CompactSize" described here). CVarInt is not a part of the protocol.<br />
<br />
=== Variable length string ===<br />
<br />
Variable length string can be stored using a variable length integer followed by the string itself.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the string<br />
|-<br />
| ? || string || char[] || The string itself (can be empty)<br />
|}<br />
<br />
=== Network address ===<br />
<br />
When a network address is needed somewhere, this structure is used. Network addresses are not prefixed with a timestamp in the version message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || time || uint32 || the Time (version >= 31402). '''Not present in version message.'''<br />
|-<br />
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]<br />
|-<br />
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The original client only supported IPv4 and only read the last 4 bytes to get the IPv4 address. However, the IPv4 address is written into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]<br />
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).<br />
|-<br />
| 2 || port || uint16_t || port number, network byte order<br />
|}<br />
<br />
Hexdump example of Network address structure<br />
<br />
<pre><br />
0000 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0010 00 00 FF FF 0A 00 00 01 20 8D ........ .<br />
<br />
Network address:<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK: see services listed under version command)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv6: ::ffff:a00:1 or IPv4: 10.0.0.1<br />
20 8D - Port 8333<br />
</pre><br />
<br />
=== Inventory Vectors ===<br />
<br />
Inventory vectors are used for notifying other nodes about objects they have or data which is being requested.<br />
<br />
Inventory vectors consist of the following data format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || type || uint32_t || Identifies the object type linked to this inventory<br />
|-<br />
| 32 || hash || char[32] || Hash of the object<br />
|}<br />
<br />
<br />
The object type is currently defined as one of the following possibilities:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0 || ERROR || Any data of with this number may be ignored<br />
|-<br />
| 1 || MSG_TX || Hash is related to a transaction<br />
|-<br />
| 2 || MSG_BLOCK || Hash is related to a data block<br />
|-<br />
| 3 || MSG_FILTERED_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a merkleblock message rather than a block message; this only works if a bloom filter has been set.<br />
|-<br />
| 4 || MSG_CMPCT_BLOCK || Hash of a block header; identical to MSG_BLOCK. Only to be used in getdata message. Indicates the reply should be a cmpctblock message. See BIP 152 for more info.<br />
|}<br />
<br />
Other Data Type values are considered reserved for future implementations.<br />
<br />
=== Block Headers ===<br />
<br />
Block headers are sent in a headers packet in response to a getheaders message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Will overflow in 2106<ref>https://en.wikipedia.org/wiki/Unix_time#Notable_events_in_Unix_time</ref>)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 1 || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries, this value is always 0<br />
|}<br />
<br />
cf. [[Block hashing algorithm]]<br />
<br />
== Message types ==<br />
<br />
=== version ===<br />
<br />
When a node creates an outgoing connection, it will immediately [[Version Handshake|advertise]] its version. The remote node will respond with its version. No further communication is possible until both peers have exchanged their version.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Identifies protocol version being used by the node<br />
|-<br />
| 8 || services || uint64_t || bitfield of features to be enabled for this connection<br />
|-<br />
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds<br />
|-<br />
| 26 || addr_recv || [[#Network address|net_addr]] || The network address of the node receiving this message<br />
|-<br />
|colspan="4"| Fields below require version ≥ 106<br />
|-<br />
| 26 || addr_from || [[#Network address|net_addr]] || The network address of the node emitting this message<br />
|-<br />
| 8 || nonce || uint64_t || Node random nonce, randomly generated every time a version packet is sent. This nonce is used to detect connections to self.<br />
|-<br />
| ? || user_agent || [[#Variable length string|var_str]] || [https://github.com/bitcoin/bips/blob/master/bip-0014.mediawiki User Agent] (0x00 if string is 0 bytes long)<br />
|-<br />
| 4 || start_height || int32_t || The last block received by the emitting node<br />
|-<br />
|colspan="4"| Fields below require version ≥ 70001<br />
|-<br />
| 1 || relay || bool || Whether the remote peer should announce relayed transactions or not, see [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037]<br />
|}<br />
<br />
A "verack" packet shall be sent if the version packet was accepted.<br />
<br />
The following services are currently assigned:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 1 || NODE_NETWORK || This node can be asked for full blocks instead of just headers.<br />
|}<br />
<br />
Hexdump example of version message (OBSOLETE EXAMPLE: This example lacks a checksum and user-agent):<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....<br />
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........<br />
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............<br />
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................<br />
0040 20 8D 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,<br />
0060 3A B4 57 13 00 55 81 01 00 :.W..U...<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
55 00 00 00 - Payload is 85 bytes long<br />
- No checksum in version message until 20 February 2012. See https://bitcointalk.org/index.php?topic=55852.0<br />
Version message:<br />
9C 7C 00 00 - 31900 (version 0.3.19)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
E6 15 10 4D 00 00 00 00 - Mon Dec 20 21:50:14 EST 2010<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 20 8D - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D - Sender address info - see Network Address<br />
DD 9D 20 2C 3A B4 57 13 - Node random unique ID<br />
00 - "" sub-version string (string is 0 bytes long)<br />
55 81 01 00 - Last block sending node has is block #98645<br />
</pre><br />
<br />
And here's a modern (60002) protocol version client advertising itself to a local peer...<br />
<br />
Newer protocol includes the checksum now, this is from a mainline (satoshi) client during <br />
an outgoing connection to another local client, notice that it does not fill out the <br />
address information at all when the source or destination is "unroutable".<br />
<br />
<pre><br />
<br />
0000 f9 be b4 d9 76 65 72 73 69 6f 6e 00 00 00 00 00 ....version.....<br />
0010 64 00 00 00 35 8d 49 32 62 ea 00 00 01 00 00 00 d...5.I2b.......<br />
0020 00 00 00 00 11 b2 d0 50 00 00 00 00 01 00 00 00 .......P........<br />
0030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ff ff ................<br />
0040 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 00 00 00 00 ff ff 00 00 00 00 00 00 ................<br />
0060 3b 2e b3 5d 8c e6 17 65 0f 2f 53 61 74 6f 73 68 ;..]...e./Satosh<br />
0070 69 3a 30 2e 37 2e 32 2f c0 3e 03 00 i:0.7.2/.>..<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
64 00 00 00 - Payload is 100 bytes long<br />
3B 64 8D 5A - payload checksum<br />
<br />
Version message:<br />
62 EA 00 00 - 60002 (protocol version 60002)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
11 B2 D0 50 00 00 00 00 - Tue Dec 18 10:12:33 PST 2012<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Sender address info - see Network Address<br />
3B 2E B3 5D 8C E6 17 65 - Node ID<br />
0F 2F 53 61 74 6F 73 68 69 3A 30 2E 37 2E 32 2F - "/Satoshi:0.7.2/" sub-version string (string is 15 bytes long)<br />
C0 3E 03 00 - Last block sending node has is block #212672<br />
</pre><br />
<br />
=== verack ===<br />
<br />
The ''verack'' message is sent in reply to ''[[#version|version]]''. This message consists of only a [[#Message structure|message header]] with the command string "verack".<br />
<br />
Hexdump of the verack message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......<br />
0010 00 00 00 00 5D F6 E0 E2 ........<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 61 63 6B 00 00 00 00 00 00 - "verack" command<br />
00 00 00 00 - Payload is 0 bytes long<br />
5D F6 E0 E2 - Checksum<br />
</pre><br />
<br />
=== addr ===<br />
<br />
Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours<br />
<br />
Payload:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of address entries (max: 1000)<br />
|-<br />
| 30x? || addr_list || (uint32_t + [[#Network address|net_addr]])[] || Address of other nodes on the network. version < 209 will only read the first one. The uint32_t is a timestamp (see note below).<br />
|}<br />
<br />
'''Note''': Starting version 31402, addresses are prefixed with a timestamp. If no timestamp is present, the addresses should not be relayed to other peers, unless it is indeed confirmed they are up.<br />
<br />
Hexdump example of ''addr'' message:<br />
<pre><br />
0000 F9 BE B4 D9 61 64 64 72 00 00 00 00 00 00 00 00 ....addr........<br />
0010 1F 00 00 00 ED 52 39 9B 01 E2 15 10 4D 01 00 00 .....R9.....M...<br />
0020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF ................<br />
0030 FF 0A 00 00 01 20 8D ..... .<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
61 64 64 72 00 00 00 00 00 00 00 00 - "addr"<br />
1F 00 00 00 - payload is 31 bytes long<br />
ED 52 39 9B - checksum of payload<br />
<br />
Payload:<br />
01 - 1 address in this message<br />
<br />
Address:<br />
E2 15 10 4D - Mon Dec 20 21:50:10 EST 2010 (only when version is >= 31402)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK service - see version message)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv4: 10.0.0.1, IPv6: ::ffff:10.0.0.1 (IPv4-mapped IPv6 address)<br />
20 8D - port 8333<br />
</pre><br />
<br />
=== inv ===<br />
<br />
Allows a node to advertise its knowledge of one or more objects. It can be received unsolicited, or in reply to ''getblocks''.<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getdata ===<br />
<br />
getdata is used in response to inv, to retrieve the content of a specific object, and is usually sent after receiving an ''inv'' packet, after filtering known elements. It can be used to retrieve transactions, but only if they are in the memory pool or relay set - arbitrary access to transactions in the chain is not allowed to avoid having clients start to depend on nodes having full transaction indexes (which modern nodes do not).<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== notfound ===<br />
<br />
notfound is a response to a getdata, sent if any requested data items could not be relayed, for example, because the requested transaction was not in the memory pool or relay set.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getblocks ===<br />
<br />
Return an ''inv'' packet containing the list of blocks starting right after the last known hash in the block locator object, up to hash_stop or 500 blocks, whichever comes first. <br />
<br />
The locator hashes are processed by a node in the order as they appear in the message. If a block hash is found in the node's main chain, the list of its children is returned back via the ''inv'' message and the remaining locators are ignored, no matter if the requested limit was reached, or not.<br />
<br />
To receive the next blocks hashes, one needs to issue getblocks again with a new block locator object. Keep in mind that some clients may provide blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block; set to zero to get as many blocks as possible (500)<br />
|}<br />
<br />
To create the block locator hashes, keep pushing hashes until you go back to the genesis block. After pushing 10 hashes back, the step backwards doubles every loop:<br />
<br />
<pre><br />
// From libbitcoin which is under AGPL<br />
std::vector<size_t> block_locator_indexes(size_t top_height)<br />
{<br />
std::vector<size_t> indexes;<br />
<br />
// Modify the step in the iteration.<br />
int64_t step = 1;<br />
<br />
// Start at the top of the chain and work backwards.<br />
for (auto index = (int64_t)top_height; index > 0; index -= step)<br />
{<br />
// Push top 10 indexes first, then back off exponentially.<br />
if (indexes.size() >= 10)<br />
step *= 2;<br />
<br />
indexes.push_back((size_t)index);<br />
}<br />
<br />
// Push the genesis block index.<br />
indexes.push_back(0);<br />
return indexes;<br />
}<br />
</pre><br />
<br />
Note that it is allowed to send in fewer known hashes down to a minimum of just one hash. However, the purpose of the block locator object is to detect a wrong branch in the caller's main chain. If the peer detects that you are off the main chain, it will send in block hashes which are earlier than your last known block. So if you just send in your last known hash and it is off the main chain, the peer starts over at block #1.<br />
<br />
=== getheaders ===<br />
<br />
Return a ''headers'' packet containing the headers of blocks starting right after the last known hash in the block locator object, up to hash_stop or 2000 blocks, whichever comes first. To receive the next block headers, one needs to issue getheaders again with a new block locator object. The ''getheaders'' command is used by thin clients to quickly download the block chain where the contents of the transactions would be irrelevant (because they are not ours). Keep in mind that some clients may provide headers of blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block header; set to zero to get as many blocks as possible (2000)<br />
|}<br />
<br />
For the block locator object in this packet, the same rules apply as for the [[Protocol_documentation#getblocks|getblocks]] packet.<br />
<br />
=== tx ===<br />
<br />
''tx'' describes a bitcoin transaction, in reply to ''[[#getdata|getdata]]''<br />
<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Transaction data format version (note, this is signed)<br />
|-<br />
| 1+ || tx_in count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction inputs<br />
|-<br />
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins<br />
|-<br />
| 1+ || tx_out count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction outputs<br />
|-<br />
| 9+ || tx_out || tx_out[] || A list of 1 or more transaction outputs or destinations for coins<br />
|-<br />
| 4 || lock_time || uint32_t || The block number or timestamp at which this transaction is locked:<br />
{|class="wikitable"<br />
! Value !! Description<br />
|-<br />
| 0 || Not locked<br />
|-<br />
| < 500000000 || Block number at which this transaction is locked<br />
|-<br />
| >= 500000000 || UNIX timestamp at which this transaction is locked<br />
|}<br />
If all TxIn inputs have final (0xffffffff) sequence numbers then lock_time is irrelevant. Otherwise, the transaction may not be added to a block until after lock_time (see [[NLockTime]]).<br />
<br />
|}<br />
<br />
TxIn consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 36 || previous_output || outpoint || The previous output transaction reference, as an OutPoint structure<br />
|-<br />
| 1+ || script length || [[Protocol_documentation#Variable_length_integer|var_int]] || The length of the signature script<br />
|-<br />
| ? || signature script || uchar[] || Computational Script for confirming transaction authorization<br />
|-<br />
| 4 || [http://bitcoin.stackexchange.com/q/2025/323 sequence] || uint32_t || Transaction version as defined by the sender. Intended for "replacement" of transactions when information is updated before inclusion into a block.<br />
|}<br />
<br />
The OutPoint structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 32 || hash || char[32] || The hash of the referenced transaction.<br />
|-<br />
| 4 || index || uint32_t || The index of the specific output in the transaction. The first output is 0, etc.<br />
|}<br />
<br />
The Script structure consists of a series of pieces of information and operations related to the value of the transaction.<br />
<br />
(Structure to be expanded in the future… see script.h and script.cpp and [[Script]] for more information)<br />
<br />
The TxOut structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || value || int64_t || Transaction Value<br />
|-<br />
| 1+ || pk_script length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the pk_script<br />
|-<br />
| ? || pk_script || uchar[] || Usually contains the public key as a Bitcoin script setting up conditions to claim this output.<br />
|}<br />
<br />
Example ''tx'' message:<br />
<pre><br />
000000 F9 BE B4 D9 74 78 00 00 00 00 00 00 00 00 00 00 ....tx..........<br />
000010 02 01 00 00 E2 93 CD BE 01 00 00 00 01 6D BD DB .............m..<br />
000020 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D 12 66 E9 .[...Q........f.<br />
000030 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29 00 00 00 .;P......j.6)...<br />
000040 00 8B 48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 ..H0E.!..X..r...<br />
000050 C7 36 7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A .6zz%;..R#...h.:<br />
000060 59 23 3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 Y#?E.W... Y.....<br />
000070 0E 41 83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D .A.z.X.z...XN...<br />
000080 35 BD 96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF 5...6..;...A....<br />
000090 C9 7E F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 .~.6.m...@..!...<br />
0000A0 2A CD 2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC *.+..].}Y... ...<br />
0000B0 4E 02 53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F N.S..=7.o...Q...<br />
0000C0 14 04 2F 46 61 4A 4C 70 C0 F1 4B EF F5 FF FF FF ../FaJLp..K.....<br />
0000D0 FF 02 40 4B 4C 00 00 00 00 00 19 76 A9 14 1A A0 ..@KL......v....<br />
0000E0 CD 1C BE A6 E7 45 8A 7A BA D5 12 A9 D9 EA 1A FB .....E.z........<br />
0000F0 22 5E 88 AC 80 FA E9 C7 00 00 00 00 19 76 A9 14 "^...........v..<br />
000100 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E FD A0 B7 ..[.Cj.....H^...<br />
000110 8B 4E CC 52 88 AC 00 00 00 00 .N.R......<br />
<br />
<br />
Message header:<br />
F9 BE B4 D9 - main network magic bytes<br />
74 78 00 00 00 00 00 00 00 00 00 00 - "tx" command<br />
02 01 00 00 - payload is 258 bytes long<br />
E2 93 CD BE - checksum of payload<br />
<br />
Transaction:<br />
01 00 00 00 - version<br />
<br />
Inputs:<br />
01 - number of transaction inputs<br />
<br />
Input 1:<br />
6D BD DB 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D - previous output (outpoint)<br />
12 66 E9 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29<br />
00 00 00 00<br />
<br />
8B - script is 139 bytes long<br />
<br />
48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 C7 36 - signature script (scriptSig)<br />
7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A 59 23<br />
3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 0E 41<br />
83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D 35 BD<br />
96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF C9 7E<br />
F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 2A CD<br />
2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC 4E 02<br />
53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F 14 04<br />
2F 46 61 4A 4C 70 C0 F1 4B EF F5<br />
<br />
FF FF FF FF - sequence<br />
<br />
Outputs:<br />
02 - 2 Output Transactions<br />
<br />
Output 1:<br />
40 4B 4C 00 00 00 00 00 - 0.05 BTC (5000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 1A A0 CD 1C BE A6 E7 45 8A 7A BA D5 12 - pk_script<br />
A9 D9 EA 1A FB 22 5E 88 AC<br />
<br />
Output 2:<br />
80 FA E9 C7 00 00 00 00 - 33.54 BTC (3354000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E - pk_script<br />
FD A0 B7 8B 4E CC 52 88 AC<br />
<br />
Locktime:<br />
00 00 00 00 - lock time<br />
</pre><br />
<br />
=== block ===<br />
<br />
The '''block''' message is sent in response to a getdata message which requests transaction information from a block hash.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A Unix timestamp recording when this block was created (Currently limited to dates before the year 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated [[Difficulty|difficulty target]] being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| ? || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries<br />
|-<br />
| ? || txns || tx[] || Block transactions, in format of "tx" command<br />
|}<br />
<br />
The SHA256 hash that identifies each block (and which must have a run of 0 bits) is calculated from the first 6 fields of this structure (version, prev_block, merkle_root, timestamp, bits, nonce, and standard SHA256 padding, making two 64-byte chunks in all) and ''not'' from the complete block. To calculate the hash, only two chunks need to be processed by the SHA256 algorithm. Since the ''nonce'' field is in the second chunk, the first chunk stays constant during mining and therefore only the second chunk needs to be processed. However, a Bitcoin hash is the hash of the hash, so two SHA256 rounds are needed for each mining iteration.<br />
See [[Block hashing algorithm]] for details and an example.<br />
<br />
=== headers ===<br />
<br />
The ''headers'' packet returns block headers in response to a ''getheaders'' packet. <br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of block headers<br />
|-<br />
| 81x? || headers || [[Protocol_documentation#Block_Headers|block_header]][] || [[Protocol_documentation#Block_Headers|Block headers]]<br />
|}<br />
<br />
Note that the block headers in this packet include a transaction count (a var_int, so there can be more than 81 bytes per header) as opposed to the block headers that are hashed by miners.<br />
<br />
=== getaddr ===<br />
<br />
The getaddr message sends a request to a node asking for information about known active peers to help with finding potential nodes in the network. The response to receiving this message is to transmit one or more addr messages with one or more peers from a database of known active peers. The typical presumption is that a node is likely to be active if it has been sending a message within the last three hours.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
=== mempool ===<br />
<br />
The mempool message sends a request to a node asking for information about transactions it has verified but which have not yet confirmed. The response to receiving this message is an inv message containing the transaction hashes for all the transactions in the node's mempool.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
It is specified in [https://github.com/bitcoin/bips/blob/master/bip-0035.mediawiki BIP 35]. Since [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 37], if a [[Protocol_documentation#filterload.2C_filteradd.2C_filterclear.2C_merkleblock|bloom filter]] is loaded, only transactions matching the filter are replied.<br />
<br />
=== checkorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== submitorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== reply ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== ping ===<br />
<br />
The ''ping'' message is sent primarily to confirm that the TCP/IP connection is still valid. An error in transmission is presumed to be a closed connection and the address is removed as a current peer.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || random nonce<br />
|}<br />
<br />
=== pong ===<br />
<br />
The ''pong'' message is sent in response to a ''ping'' message. In modern protocol versions, a ''pong'' response is generated using a nonce included in the ping.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || nonce from ping<br />
|}<br />
<br />
<br />
=== reject===<br />
<br />
The ''reject'' message is sent when messages are rejected.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || message || var_str || type of message rejected<br />
|-<br />
| 1 || ccode || char || code relating to rejected message<br />
|-<br />
| 1+ || reason || var_str || text version of reason for rejection<br />
|-<br />
| 0+ || data || char || Optional extra data provided by some errors. Currently, all errors which provide this field fill it with the TXID or block header hash of the object being rejected, so the field is 32 bytes.<br />
|}<br />
<br />
CCodes<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0x01 || REJECT_MALFORMED|| <br />
|-<br />
| 0x10 || REJECT_INVALID ||<br />
|-<br />
| 0x11 || REJECT_OBSOLETE ||<br />
|-<br />
| 0x12 || REJECT_DUPLICATE ||<br />
|-<br />
| 0x40 || REJECT_NONSTANDARD ||<br />
|-<br />
| 0x41 || REJECT_DUST ||<br />
|-<br />
| 0x42 || REJECT_INSUFFICIENTFEE ||<br />
|-<br />
| 0x43 || REJECT_CHECKPOINT ||<br />
|}<br />
<br />
=== filterload, filteradd, filterclear, merkleblock ===<br />
<br />
These messages are related to Bloom filtering of connections and are defined in [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037].<br />
<br />
<br />
The <code>filterload</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || filter || uint8_t[] || The filter itself is simply a bit field of arbitrary byte-aligned size. The maximum size is 36,000 bytes.<br />
|-<br />
| 4 || nHashFuncs || uint32_t || The number of hash functions to use in this filter. The maximum value allowed in this field is 50.<br />
|-<br />
| 4 || nTweak || uint32_t || A random value to add to the seed value in the hash function used by the bloom filter.<br />
|-<br />
| 1 || nFlags || uint8_t || A set of flags that control how matched items are added to the filter.<br />
|}<br />
<br />
See below for a description of the Bloom filter algorithm and how to select nHashFuncs and filter size for a desired false positive rate.<br />
<br />
Upon receiving a <code>filterload</code> command, the remote peer will immediately restrict the broadcast transactions it announces (in inv packets) to transactions matching the filter, where the matching algorithm is specified below. The flags control the update behaviour of the matching algorithm.<br />
<br />
The <code>filteradd</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || data || uint8_t[] || The data element to add to the current filter.<br />
|}<br />
<br />
The data field must be smaller than or equal to 520 bytes in size (the maximum size of any potentially matched object).<br />
<br />
The given data element will be added to the Bloom filter. A filter must have been previously provided using <code>filterload</code>. This command is useful if a new key or script is added to a clients wallet whilst it has connections to the network open, it avoids the need to re-calculate and send an entirely new filter to every peer (though doing so is usually advisable to maintain anonymity).<br />
<br />
The <code>filterclear</code> command has no arguments at all.<br />
<br />
After a filter has been set, nodes don't merely stop announcing non-matching transactions, they can also serve filtered blocks. A filtered block is defined by the <code>merkleblock</code> message and is defined like this:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information, based upon the software version creating this block (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Limited to 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 4 || total_transactions || uint32_t || Number of transactions in the block (including unmatched ones)<br />
|-<br />
| ? || hashes || uint256[] || hashes in depth-first order (including standard varint size prefix)<br />
|-<br />
| ? || flags || byte[] || flag bits, packed per 8 in a byte, least significant bit first (including standard varint size prefix)<br />
|}<br />
<br />
=== alert ===<br />
<br />
An '''alert''' is sent between nodes to send a general notification message throughout the network. If the alert can be confirmed with the signature as having come from the core development group of the Bitcoin software, the message is suggested to be displayed for end-users. Attempts to perform transactions, particularly automated transactions through the client, are suggested to be halted. The text in the Message string should be relayed to log files and any user interfaces.<br />
<br />
Alert format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || payload || uchar[] || Serialized alert payload<br />
|-<br />
| ? || signature || uchar[] || An ECDSA signature of the message<br />
|}<br />
<br />
The developers of Satoshi's client use this public key for signing alerts:<br />
04fc9702847840aaf195de8442ebecedf5b095cdbb9bc716bda9110971b28a49e0ead8564ff0db22209e0374782c093bb899692d524e9d6a6956e7c5ecbcd68284<br />
(hash) 1AGRxqDa5WjUKBwHB9XYEjmkv1ucoUUy1s<br />
<br />
The payload is serialized into a uchar[] to ensure that versions using incompatible alert formats can still relay alerts among one another. The current alert payload format is:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || Version || int32_t || Alert format version<br />
|-<br />
| 8 || RelayUntil || int64_t || The timestamp beyond which nodes should stop relaying this alert<br />
|-<br />
| 8 || Expiration || int64_t || The timestamp beyond which this alert is no longer in effect and should be ignored<br />
|-<br />
| 4 || ID || int32_t || A unique ID number for this alert<br />
|-<br />
| 4 || Cancel || int32_t || All alerts with an ID number less than or equal to this number should be cancelled: deleted and not accepted in the future<br />
|-<br />
| ? || setCancel || set<int32_t> || All alert IDs contained in this set should be cancelled as above<br />
|-<br />
| 4 || MinVer || int32_t || This alert only applies to versions greater than or equal to this version. Other versions should still relay it.<br />
|-<br />
| 4 || MaxVer || int32_t || This alert only applies to versions less than or equal to this version. Other versions should still relay it.<br />
|-<br />
| ? || setSubVer || set<string> || If this set contains any elements, then only nodes that have their subVer contained in this set are affected by the alert. Other versions should still relay it.<br />
|-<br />
| 4 || Priority || int32_t || Relative priority compared to other alerts<br />
|-<br />
| ? || Comment || string || A comment on the alert that is not displayed<br />
|-<br />
| ? || StatusBar || string || The alert message that is displayed to the user<br />
|-<br />
| ? || Reserved || string || Reserved<br />
|}<br />
<br />
Note: '''set<''type''>''' in the table above is a [[#Variable length integer | variable length integer]] followed by the number of fields of the given ''type'' (either int32_t or [[#Variable length string | variable length string]])<br />
<br />
Sample alert (no message header):<br />
73010000003766404f00000000b305434f00000000f2030000f1030000001027000048ee0000<br />
0064000000004653656520626974636f696e2e6f72672f666562323020696620796f75206861<br />
76652074726f75626c6520636f6e6e656374696e672061667465722032302046656272756172<br />
79004730450221008389df45f0703f39ec8c1cc42c13810ffcae14995bb648340219e353b63b<br />
53eb022009ec65e1c1aaeec1fd334c6b684bde2b3f573060d5b70c3a46723326e4e8a4f1<br />
<br />
Version: 1<br />
RelayUntil: 1329620535<br />
Expiration: 1329792435<br />
ID: 1010<br />
Cancel: 1009<br />
setCancel: <empty><br />
MinVer: 10000<br />
MaxVer: 61000<br />
setSubVer: <empty><br />
Priority: 100<br />
Comment: <empty><br />
StatusBar: "See bitcoin.org/feb20 if you have trouble connecting after 20 February"<br />
Reserved: <empty><br />
<br />
=== sendheaders ===<br />
<br />
Request for Direct headers announcement. <br />
<br />
Upon receipt of this message, the node is be permitted, but not required, to announce new blocks by '''headers''' command (instead of '''inv''' command).<br />
<br />
This message is supported by the protocol version >= 70012 or Bitcoin Core version >= 0.12.0.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0130.mediawiki BIP 130] for more information.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
<br />
=== feefilter ===<br />
<br />
The payload is always 8 bytes long and it encodes 64 bit integer value (LSB / little endian) of '''feerate'''.<br />
The value represents a minimal fee and is expressed in satoshis per 1000 bytes.<br />
<br />
Upon receipt of a "feefilter" message, the node will be permitted, but not required, to filter transaction invs for transactions that fall below the feerate provided in the feefilter message interpreted as satoshis per kilobyte.<br />
<br />
The fee filter is additive with a bloom filter for transactions so if an SPV client were to load a bloom filter and send a feefilter message, transactions would only be relayed if they passed both filters.<br />
<br />
Inv's generated from a mempool message are also subject to a fee filter if it exists.<br />
<br />
Feature discovery is enabled by checking protocol version >= 70013<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0133.mediawiki BIP 133] for more information.<br />
<br />
== Scripting ==<br />
<br />
See [[script]].<br />
<br />
==See Also==<br />
<br />
* [[Network]]<br />
* [[Protocol rules]]<br />
* [[Hardfork Wishlist]]<br />
* [https://bitcoin.org/en/developer-documentation Developer Documentation on bitcoin.org]<br />
* Bitcoin dissectors for Wireshark: https://github.com/lbotsch/wireshark-bitcoin https://github.com/op-sig/bitcoin-wireshark-dissector<br />
<br />
==References==<br />
<references /><br />
<br />
[[zh-cn:协议说明]]<br />
[[Category:Technical]]<br />
[[Category:Developer]]<br />
<br />
{{Bitcoin Core documentation}}</div>Tonikthttps://en.bitcoin.it/w/index.php?title=Protocol_documentation&diff=61451Protocol documentation2016-08-15T11:51:34Z<p>Tonikt: /* feefilter */</p>
<hr />
<div>This page ''describes'' the behavior of the [[Original Bitcoin client|reference client]]. The Bitcoin protocol is specified by the behavior of the reference client, not by this page. In particular, while this page is quite complete in describing the network protocol, it does not attempt to list all of the rules for block or transaction validity.<br />
<br />
Type names used in this documentation are from the C99 standard.<br />
<br />
For protocol used in mining, see [[getblocktemplate]].<br />
<br />
==Common standards==<br />
<br />
=== Hashes ===<br />
<br />
Usually, when a hash is computed within bitcoin, it is computed twice. Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-256] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when a shorter hash is desirable (for example when creating a bitcoin address).<br />
<br />
Example of double-SHA-256 encoding of string "hello":<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round of sha-256)<br />
9595c9df90075148eb06860365df33584b75bff782a510c6cd4883a419833d50 (second round of sha-256)<br />
<br />
For bitcoin addresses (RIPEMD-160) this would give:<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round is sha-256)<br />
b6a9c8c230722b7c748331a8b450f05566dc7d0f (with ripemd-160)<br />
<br />
=== Merkle Trees ===<br />
<br />
Merkle trees are binary trees of hashes. Merkle trees in bitcoin use a '''double''' SHA-256, the SHA-256 hash of the SHA-256 hash of something.<br />
<br />
If, when forming a row in the tree (other than the root of the tree), it would have an odd number of elements, the final double-hash is duplicated to ensure that the row has an even number of hashes.<br />
<br />
First form the bottom row of the tree with the ordered double-SHA-256 hashes of the byte streams of the transactions in the block.<br />
<br />
Then the row above it consists of half that number of hashes. Each entry is the double-SHA-256 of the 64-byte concatenation of the corresponding two hashes below it in the tree.<br />
<br />
This procedure repeats recursively until we reach a row consisting of just a single double-hash. This is the '''Merkle root''' of the tree.<br />
<br />
For example, imagine a block with three transactions ''a'', ''b'' and ''c''. The Merkle tree is: <br />
<br />
d1 = dhash(a)<br />
d2 = dhash(b)<br />
d3 = dhash(c)<br />
d4 = dhash(c) # a, b, c are 3. that's an odd number, so we take the c twice<br />
<br />
d5 = dhash(d1 concat d2)<br />
d6 = dhash(d3 concat d4)<br />
<br />
d7 = dhash(d5 concat d6)<br />
<br />
where<br />
<br />
dhash(a) = sha256(sha256(a))<br />
<br />
''d7'' is the Merkle root of the 3 transactions in this block.<br />
<br />
Note: Hashes in Merkle Tree displayed in the [[Block Explorer]] are of little-endian notation. For some implementations and [http://www.fileformat.info/tool/hash.htm calculations], the bits need to be reversed before they are hashed, and again after the hashing operation.<br />
<br />
=== Signatures ===<br />
<br />
Bitcoin uses [http://en.wikipedia.org/wiki/Elliptic_curve_cryptography Elliptic Curve] [http://en.wikipedia.org/wiki/Digital_Signature_Algorithm Digital Signature Algorithm] ([http://en.wikipedia.org/wiki/Elliptic_Curve_DSA ECDSA]) to sign transactions. <br />
<br />
For [[ECDSA]] the secp256k1 curve from http://www.secg.org/collateral/sec2_final.pdf is used.<br />
<br />
Public keys (in scripts) are given as 04 <x> <y> where ''x'' and ''y'' are 32 byte big-endian integers representing the coordinates of a point on the curve or in compressed form given as <sign> <x> where <sign> is 0x02 if ''y'' is even and 0x03 if ''y'' is odd.<br />
<br />
Signatures use [http://en.wikipedia.org/wiki/Distinguished_Encoding_Rules DER encoding] to pack the ''r'' and ''s'' components into a single byte stream (this is also what OpenSSL produces by default).<br />
<br />
=== Transaction Verification ===<br />
Transactions are cryptographically signed records that reassign ownership of Bitcoins to new addresses. Transactions have ''inputs'' - records which reference the funds from other previous transactions - and ''outputs'' - records which determine the new owner of the transferred Bitcoins, and which will be referenced as inputs in future transactions as those funds are respent.<br />
<br />
Each ''input'' must have a cryptographic digital signature that unlocks the funds from the prior transaction. Only the person possessing the appropriate [[private key]] is able to create a satisfactory signature; this in effect ensures that funds can only be spent by their owners.<br />
<br />
Each ''output'' determines which Bitcoin address (or other criteria, see [[Script]]) is the recipient of the funds.<br />
<br />
In a transaction, the sum of all inputs must be equal to or greater than the sum of all outputs. If the inputs exceed the outputs, the difference is considered a [[transaction fee]], and is redeemable by whoever first includes the transaction into the block chain.<br />
<br />
A special kind of transaction, called a [[coinbase transaction]], has no inputs. It is created by [[miners]], and there is one coinbase transaction per block. Because each block comes with a reward of newly created Bitcoins (e.g. 50 BTC for the first 210,000 blocks), the first transaction of a block is, with few exceptions, the transaction that grants those coins to their recipient (the miner). In addition to the newly created Bitcoins, the coinbase transaction is also used for assigning the recipient of any transaction fees that were paid within the other transactions being included in the same block. The coinbase transaction can assign the entire reward to a single Bitcoin address, or split it in portions among multiple addresses, just like any other transaction. Coinbase transactions always contain outputs totalling the sum of the block reward plus all transaction fees collected from the other transactions in the same block.<br />
<br />
The [[coinbase transaction]] in block zero cannot be spent. This is due to a quirk of the reference client implementation that would open the potential for a block chain fork if some nodes accepted the spend and others did not<ref>[http://bitcointalk.org/index.php?topic=119645.msg1288552#msg1288552 Block 0 Network Fork]</ref>.<br />
<br />
Most Bitcoin outputs encumber the newly transferred coins with a single ECDSA private key. The actual record saved with inputs and outputs isn't necessarily a key, but a ''script''. Bitcoin uses an interpreted scripting system to determine whether an output's criteria have been satisfied, with which more complex operations are possible, such as outputs that require two ECDSA signatures, or two-of-three-signature schemes. An output that references a single Bitcoin address is a ''typical'' output; an output actually contains this information in the form of a script that requires a single ECDSA signature (see [[OP_CHECKSIG]]). The output script specifies what must be provided to unlock the funds later, and when the time comes in the future to spend the transaction in another input, that input must provide all of the thing(s) that satisfy the requirements defined by the original output script.<br />
<br />
=== Addresses ===<br />
<br />
A bitcoin address is in fact the hash of a ECDSA public key, computed this way:<br />
<br />
Version = 1 byte of 0 (zero); on the test network, this is 1 byte of 111<br />
Key hash = Version concatenated with RIPEMD-160(SHA-256(public key))<br />
Checksum = 1st 4 bytes of SHA-256(SHA-256(Key hash))<br />
Bitcoin Address = Base58Encode(Key hash concatenated with Checksum)<br />
<br />
The Base58 encoding used is home made, and has some differences. Especially, leading zeroes are kept as single zeroes when conversion happens.<br />
<br />
== Common structures ==<br />
<br />
Almost all integers are encoded in little endian. Only IP or port number are encoded big endian.<br />
<br />
=== Message structure ===<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown<br />
|-<br />
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| 4 || length || uint32_t || Length of payload in number of bytes<br />
|-<br />
| 4 || checksum || uint32_t || First 4 bytes of sha256(sha256(payload))<br />
|-<br />
| ? || payload || uchar[] || The actual data<br />
|}<br />
<br />
<br />
Known magic values:<br />
<br />
{|class="wikitable"<br />
! Network !! Magic value !! Sent over wire as<br />
|-<br />
| main || 0xD9B4BEF9 || F9 BE B4 D9<br />
|-<br />
| testnet || 0xDAB5BFFA || FA BF B5 DA<br />
|-<br />
| testnet3 || 0x0709110B || 0B 11 09 07<br />
|-<br />
| namecoin || 0xFEB4BEF9 || F9 BE B4 FE<br />
|}<br />
<br />
=== Variable length integer ===<br />
<br />
Integer can be encoded depending on the represented value to save space.<br />
Variable length integers always precede an array/vector of a type of data that may vary in length.<br />
Longer numbers are encoded in little endian.<br />
<br />
{|class="wikitable"<br />
! Value !! Storage length !! Format<br />
|-<br />
| < 0xFD || 1 || uint8_t<br />
|-<br />
| <= 0xFFFF || 3 || 0xFD followed by the length as uint16_t<br />
|-<br />
| <= 0xFFFF FFFF || 5 || 0xFE followed by the length as uint32_t<br />
|-<br />
| - || 9 || 0xFF followed by the length as uint64_t<br />
|}<br />
<br />
If you're reading the Satoshi client code (BitcoinQT) it refers to this encoding as a "CompactSize". Modern BitcoinQT also has the CVarInt class which implements an even more compact integer for the purpose of local storage (which is incompatible with "CompactSize" described here). CVarInt is not a part of the protocol.<br />
<br />
=== Variable length string ===<br />
<br />
Variable length string can be stored using a variable length integer followed by the string itself.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the string<br />
|-<br />
| ? || string || char[] || The string itself (can be empty)<br />
|}<br />
<br />
=== Network address ===<br />
<br />
When a network address is needed somewhere, this structure is used. Network addresses are not prefixed with a timestamp in the version message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || time || uint32 || the Time (version >= 31402). '''Not present in version message.'''<br />
|-<br />
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]<br />
|-<br />
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The original client only supported IPv4 and only read the last 4 bytes to get the IPv4 address. However, the IPv4 address is written into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]<br />
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).<br />
|-<br />
| 2 || port || uint16_t || port number, network byte order<br />
|}<br />
<br />
Hexdump example of Network address structure<br />
<br />
<pre><br />
0000 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0010 00 00 FF FF 0A 00 00 01 20 8D ........ .<br />
<br />
Network address:<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK: see services listed under version command)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv6: ::ffff:a00:1 or IPv4: 10.0.0.1<br />
20 8D - Port 8333<br />
</pre><br />
<br />
=== Inventory Vectors ===<br />
<br />
Inventory vectors are used for notifying other nodes about objects they have or data which is being requested.<br />
<br />
Inventory vectors consist of the following data format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || type || uint32_t || Identifies the object type linked to this inventory<br />
|-<br />
| 32 || hash || char[32] || Hash of the object<br />
|}<br />
<br />
<br />
The object type is currently defined as one of the following possibilities:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0 || ERROR || Any data of with this number may be ignored<br />
|-<br />
| 1 || MSG_TX || Hash is related to a transaction<br />
|-<br />
| 2 || MSG_BLOCK || Hash is related to a data block<br />
|-<br />
| 3 || MSG_FILTERED_BLOCK || Hash of a block header; identical to MSG_BLOCK. When used in a getdata message, this indicates the reply should be a merkleblock message rather than a block message; this only works if a bloom filter has been set.<br />
|}<br />
<br />
Other Data Type values are considered reserved for future implementations.<br />
<br />
=== Block Headers ===<br />
<br />
Block headers are sent in a headers packet in response to a getheaders message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Will overflow in 2106<ref>https://en.wikipedia.org/wiki/Unix_time#Notable_events_in_Unix_time</ref>)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 1 || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries, this value is always 0<br />
|}<br />
<br />
cf. [[Block hashing algorithm]]<br />
<br />
== Message types ==<br />
<br />
=== version ===<br />
<br />
When a node creates an outgoing connection, it will immediately [[Version Handshake|advertise]] its version. The remote node will respond with its version. No further communication is possible until both peers have exchanged their version.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Identifies protocol version being used by the node<br />
|-<br />
| 8 || services || uint64_t || bitfield of features to be enabled for this connection<br />
|-<br />
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds<br />
|-<br />
| 26 || addr_recv || [[#Network address|net_addr]] || The network address of the node receiving this message<br />
|-<br />
|colspan="4"| Fields below require version ≥ 106<br />
|-<br />
| 26 || addr_from || [[#Network address|net_addr]] || The network address of the node emitting this message<br />
|-<br />
| 8 || nonce || uint64_t || Node random nonce, randomly generated every time a version packet is sent. This nonce is used to detect connections to self.<br />
|-<br />
| ? || user_agent || [[#Variable length string|var_str]] || [https://github.com/bitcoin/bips/blob/master/bip-0014.mediawiki User Agent] (0x00 if string is 0 bytes long)<br />
|-<br />
| 4 || start_height || int32_t || The last block received by the emitting node<br />
|-<br />
|colspan="4"| Fields below require version ≥ 70001<br />
|-<br />
| 1 || relay || bool || Whether the remote peer should announce relayed transactions or not, see [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037]<br />
|}<br />
<br />
A "verack" packet shall be sent if the version packet was accepted.<br />
<br />
The following services are currently assigned:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 1 || NODE_NETWORK || This node can be asked for full blocks instead of just headers.<br />
|}<br />
<br />
Hexdump example of version message (OBSOLETE EXAMPLE: This example lacks a checksum and user-agent):<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....<br />
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........<br />
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............<br />
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................<br />
0040 20 8D 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,<br />
0060 3A B4 57 13 00 55 81 01 00 :.W..U...<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
55 00 00 00 - Payload is 85 bytes long<br />
- No checksum in version message until 20 February 2012. See https://bitcointalk.org/index.php?topic=55852.0<br />
Version message:<br />
9C 7C 00 00 - 31900 (version 0.3.19)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
E6 15 10 4D 00 00 00 00 - Mon Dec 20 21:50:14 EST 2010<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 20 8D - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D - Sender address info - see Network Address<br />
DD 9D 20 2C 3A B4 57 13 - Node random unique ID<br />
00 - "" sub-version string (string is 0 bytes long)<br />
55 81 01 00 - Last block sending node has is block #98645<br />
</pre><br />
<br />
And here's a modern (60002) protocol version client advertising itself to a local peer...<br />
<br />
Newer protocol includes the checksum now, this is from a mainline (satoshi) client during <br />
an outgoing connection to another local client, notice that it does not fill out the <br />
address information at all when the source or destination is "unroutable".<br />
<br />
<pre><br />
<br />
0000 f9 be b4 d9 76 65 72 73 69 6f 6e 00 00 00 00 00 ....version.....<br />
0010 64 00 00 00 35 8d 49 32 62 ea 00 00 01 00 00 00 d...5.I2b.......<br />
0020 00 00 00 00 11 b2 d0 50 00 00 00 00 01 00 00 00 .......P........<br />
0030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ff ff ................<br />
0040 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 00 00 00 00 ff ff 00 00 00 00 00 00 ................<br />
0060 3b 2e b3 5d 8c e6 17 65 0f 2f 53 61 74 6f 73 68 ;..]...e./Satosh<br />
0070 69 3a 30 2e 37 2e 32 2f c0 3e 03 00 i:0.7.2/.>..<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
64 00 00 00 - Payload is 100 bytes long<br />
3B 64 8D 5A - payload checksum<br />
<br />
Version message:<br />
62 EA 00 00 - 60002 (protocol version 60002)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
11 B2 D0 50 00 00 00 00 - Tue Dec 18 10:12:33 PST 2012<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Sender address info - see Network Address<br />
3B 2E B3 5D 8C E6 17 65 - Node ID<br />
0F 2F 53 61 74 6F 73 68 69 3A 30 2E 37 2E 32 2F - "/Satoshi:0.7.2/" sub-version string (string is 15 bytes long)<br />
C0 3E 03 00 - Last block sending node has is block #212672<br />
</pre><br />
<br />
=== verack ===<br />
<br />
The ''verack'' message is sent in reply to ''[[#version|version]]''. This message consists of only a [[#Message structure|message header]] with the command string "verack".<br />
<br />
Hexdump of the verack message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......<br />
0010 00 00 00 00 5D F6 E0 E2 ........<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 61 63 6B 00 00 00 00 00 00 - "verack" command<br />
00 00 00 00 - Payload is 0 bytes long<br />
5D F6 E0 E2 - Checksum<br />
</pre><br />
<br />
=== addr ===<br />
<br />
Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours<br />
<br />
Payload:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of address entries (max: 1000)<br />
|-<br />
| 30x? || addr_list || (uint32_t + [[#Network address|net_addr]])[] || Address of other nodes on the network. version < 209 will only read the first one. The uint32_t is a timestamp (see note below).<br />
|}<br />
<br />
'''Note''': Starting version 31402, addresses are prefixed with a timestamp. If no timestamp is present, the addresses should not be relayed to other peers, unless it is indeed confirmed they are up.<br />
<br />
Hexdump example of ''addr'' message:<br />
<pre><br />
0000 F9 BE B4 D9 61 64 64 72 00 00 00 00 00 00 00 00 ....addr........<br />
0010 1F 00 00 00 ED 52 39 9B 01 E2 15 10 4D 01 00 00 .....R9.....M...<br />
0020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF ................<br />
0030 FF 0A 00 00 01 20 8D ..... .<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
61 64 64 72 00 00 00 00 00 00 00 00 - "addr"<br />
1F 00 00 00 - payload is 31 bytes long<br />
ED 52 39 9B - checksum of payload<br />
<br />
Payload:<br />
01 - 1 address in this message<br />
<br />
Address:<br />
E2 15 10 4D - Mon Dec 20 21:50:10 EST 2010 (only when version is >= 31402)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK service - see version message)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv4: 10.0.0.1, IPv6: ::ffff:10.0.0.1 (IPv4-mapped IPv6 address)<br />
20 8D - port 8333<br />
</pre><br />
<br />
=== inv ===<br />
<br />
Allows a node to advertise its knowledge of one or more objects. It can be received unsolicited, or in reply to ''getblocks''.<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getdata ===<br />
<br />
getdata is used in response to inv, to retrieve the content of a specific object, and is usually sent after receiving an ''inv'' packet, after filtering known elements. It can be used to retrieve transactions, but only if they are in the memory pool or relay set - arbitrary access to transactions in the chain is not allowed to avoid having clients start to depend on nodes having full transaction indexes (which modern nodes do not).<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== notfound ===<br />
<br />
notfound is a response to a getdata, sent if any requested data items could not be relayed, for example, because the requested transaction was not in the memory pool or relay set.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getblocks ===<br />
<br />
Return an ''inv'' packet containing the list of blocks starting right after the last known hash in the block locator object, up to hash_stop or 500 blocks, whichever comes first. <br />
<br />
The locator hashes are processed by a node in the order as they appear in the message. If a block hash is found in the node's main chain, the list of its children is returned back via the ''inv'' message and the remaining locators are ignored, no matter if the requested limit was reached, or not.<br />
<br />
To receive the next blocks hashes, one needs to issue getblocks again with a new block locator object. Keep in mind that some clients may provide blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block; set to zero to get as many blocks as possible (500)<br />
|}<br />
<br />
To create the block locator hashes, keep pushing hashes until you go back to the genesis block. After pushing 10 hashes back, the step backwards doubles every loop:<br />
<br />
<pre><br />
// From libbitcoin which is under AGPL<br />
std::vector<size_t> block_locator_indexes(size_t top_height)<br />
{<br />
std::vector<size_t> indexes;<br />
<br />
// Modify the step in the iteration.<br />
int64_t step = 1;<br />
<br />
// Start at the top of the chain and work backwards.<br />
for (auto index = (int64_t)top_height; index > 0; index -= step)<br />
{<br />
// Push top 10 indexes first, then back off exponentially.<br />
if (indexes.size() >= 10)<br />
step *= 2;<br />
<br />
indexes.push_back((size_t)index);<br />
}<br />
<br />
// Push the genesis block index.<br />
indexes.push_back(0);<br />
return indexes;<br />
}<br />
</pre><br />
<br />
Note that it is allowed to send in fewer known hashes down to a minimum of just one hash. However, the purpose of the block locator object is to detect a wrong branch in the caller's main chain. If the peer detects that you are off the main chain, it will send in block hashes which are earlier than your last known block. So if you just send in your last known hash and it is off the main chain, the peer starts over at block #1.<br />
<br />
=== getheaders ===<br />
<br />
Return a ''headers'' packet containing the headers of blocks starting right after the last known hash in the block locator object, up to hash_stop or 2000 blocks, whichever comes first. To receive the next block headers, one needs to issue getheaders again with a new block locator object. The ''getheaders'' command is used by thin clients to quickly download the block chain where the contents of the transactions would be irrelevant (because they are not ours). Keep in mind that some clients may provide headers of blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block header; set to zero to get as many blocks as possible (2000)<br />
|}<br />
<br />
For the block locator object in this packet, the same rules apply as for the [[Protocol_documentation#getblocks|getblocks]] packet.<br />
<br />
=== tx ===<br />
<br />
''tx'' describes a bitcoin transaction, in reply to ''[[#getdata|getdata]]''<br />
<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Transaction data format version (note, this is signed)<br />
|-<br />
| 1+ || tx_in count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction inputs<br />
|-<br />
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins<br />
|-<br />
| 1+ || tx_out count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction outputs<br />
|-<br />
| 9+ || tx_out || tx_out[] || A list of 1 or more transaction outputs or destinations for coins<br />
|-<br />
| 4 || lock_time || uint32_t || The block number or timestamp at which this transaction is locked:<br />
{|class="wikitable"<br />
! Value !! Description<br />
|-<br />
| 0 || Not locked<br />
|-<br />
| < 500000000 || Block number at which this transaction is locked<br />
|-<br />
| >= 500000000 || UNIX timestamp at which this transaction is locked<br />
|}<br />
If all TxIn inputs have final (0xffffffff) sequence numbers then lock_time is irrelevant. Otherwise, the transaction may not be added to a block until after lock_time (see [[NLockTime]]).<br />
<br />
|}<br />
<br />
TxIn consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 36 || previous_output || outpoint || The previous output transaction reference, as an OutPoint structure<br />
|-<br />
| 1+ || script length || [[Protocol_documentation#Variable_length_integer|var_int]] || The length of the signature script<br />
|-<br />
| ? || signature script || uchar[] || Computational Script for confirming transaction authorization<br />
|-<br />
| 4 || [http://bitcoin.stackexchange.com/q/2025/323 sequence] || uint32_t || Transaction version as defined by the sender. Intended for "replacement" of transactions when information is updated before inclusion into a block.<br />
|}<br />
<br />
The OutPoint structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 32 || hash || char[32] || The hash of the referenced transaction.<br />
|-<br />
| 4 || index || uint32_t || The index of the specific output in the transaction. The first output is 0, etc.<br />
|}<br />
<br />
The Script structure consists of a series of pieces of information and operations related to the value of the transaction.<br />
<br />
(Structure to be expanded in the future… see script.h and script.cpp and [[Script]] for more information)<br />
<br />
The TxOut structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || value || int64_t || Transaction Value<br />
|-<br />
| 1+ || pk_script length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the pk_script<br />
|-<br />
| ? || pk_script || uchar[] || Usually contains the public key as a Bitcoin script setting up conditions to claim this output.<br />
|}<br />
<br />
Example ''tx'' message:<br />
<pre><br />
000000 F9 BE B4 D9 74 78 00 00 00 00 00 00 00 00 00 00 ....tx..........<br />
000010 02 01 00 00 E2 93 CD BE 01 00 00 00 01 6D BD DB .............m..<br />
000020 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D 12 66 E9 .[...Q........f.<br />
000030 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29 00 00 00 .;P......j.6)...<br />
000040 00 8B 48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 ..H0E.!..X..r...<br />
000050 C7 36 7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A .6zz%;..R#...h.:<br />
000060 59 23 3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 Y#?E.W... Y.....<br />
000070 0E 41 83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D .A.z.X.z...XN...<br />
000080 35 BD 96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF 5...6..;...A....<br />
000090 C9 7E F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 .~.6.m...@..!...<br />
0000A0 2A CD 2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC *.+..].}Y... ...<br />
0000B0 4E 02 53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F N.S..=7.o...Q...<br />
0000C0 14 04 2F 46 61 4A 4C 70 C0 F1 4B EF F5 FF FF FF ../FaJLp..K.....<br />
0000D0 FF 02 40 4B 4C 00 00 00 00 00 19 76 A9 14 1A A0 ..@KL......v....<br />
0000E0 CD 1C BE A6 E7 45 8A 7A BA D5 12 A9 D9 EA 1A FB .....E.z........<br />
0000F0 22 5E 88 AC 80 FA E9 C7 00 00 00 00 19 76 A9 14 "^...........v..<br />
000100 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E FD A0 B7 ..[.Cj.....H^...<br />
000110 8B 4E CC 52 88 AC 00 00 00 00 .N.R......<br />
<br />
<br />
Message header:<br />
F9 BE B4 D9 - main network magic bytes<br />
74 78 00 00 00 00 00 00 00 00 00 00 - "tx" command<br />
02 01 00 00 - payload is 258 bytes long<br />
E2 93 CD BE - checksum of payload<br />
<br />
Transaction:<br />
01 00 00 00 - version<br />
<br />
Inputs:<br />
01 - number of transaction inputs<br />
<br />
Input 1:<br />
6D BD DB 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D - previous output (outpoint)<br />
12 66 E9 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29<br />
00 00 00 00<br />
<br />
8B - script is 139 bytes long<br />
<br />
48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 C7 36 - signature script (scriptSig)<br />
7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A 59 23<br />
3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 0E 41<br />
83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D 35 BD<br />
96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF C9 7E<br />
F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 2A CD<br />
2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC 4E 02<br />
53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F 14 04<br />
2F 46 61 4A 4C 70 C0 F1 4B EF F5<br />
<br />
FF FF FF FF - sequence<br />
<br />
Outputs:<br />
02 - 2 Output Transactions<br />
<br />
Output 1:<br />
40 4B 4C 00 00 00 00 00 - 0.05 BTC (5000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 1A A0 CD 1C BE A6 E7 45 8A 7A BA D5 12 - pk_script<br />
A9 D9 EA 1A FB 22 5E 88 AC<br />
<br />
Output 2:<br />
80 FA E9 C7 00 00 00 00 - 33.54 BTC (3354000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E - pk_script<br />
FD A0 B7 8B 4E CC 52 88 AC<br />
<br />
Locktime:<br />
00 00 00 00 - lock time<br />
</pre><br />
<br />
=== block ===<br />
<br />
The '''block''' message is sent in response to a getdata message which requests transaction information from a block hash.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A Unix timestamp recording when this block was created (Currently limited to dates before the year 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated [[Difficulty|difficulty target]] being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| ? || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries<br />
|-<br />
| ? || txns || tx[] || Block transactions, in format of "tx" command<br />
|}<br />
<br />
The SHA256 hash that identifies each block (and which must have a run of 0 bits) is calculated from the first 6 fields of this structure (version, prev_block, merkle_root, timestamp, bits, nonce, and standard SHA256 padding, making two 64-byte chunks in all) and ''not'' from the complete block. To calculate the hash, only two chunks need to be processed by the SHA256 algorithm. Since the ''nonce'' field is in the second chunk, the first chunk stays constant during mining and therefore only the second chunk needs to be processed. However, a Bitcoin hash is the hash of the hash, so two SHA256 rounds are needed for each mining iteration.<br />
See [[Block hashing algorithm]] for details and an example.<br />
<br />
=== headers ===<br />
<br />
The ''headers'' packet returns block headers in response to a ''getheaders'' packet. <br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of block headers<br />
|-<br />
| 81x? || headers || [[Protocol_documentation#Block_Headers|block_header]][] || [[Protocol_documentation#Block_Headers|Block headers]]<br />
|}<br />
<br />
Note that the block headers in this packet include a transaction count (a var_int, so there can be more than 81 bytes per header) as opposed to the block headers that are hashed by miners.<br />
<br />
=== getaddr ===<br />
<br />
The getaddr message sends a request to a node asking for information about known active peers to help with finding potential nodes in the network. The response to receiving this message is to transmit one or more addr messages with one or more peers from a database of known active peers. The typical presumption is that a node is likely to be active if it has been sending a message within the last three hours.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
=== mempool ===<br />
<br />
The mempool message sends a request to a node asking for information about transactions it has verified but which have not yet confirmed. The response to receiving this message is an inv message containing the transaction hashes for all the transactions in the node's mempool.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
It is specified in [https://github.com/bitcoin/bips/blob/master/bip-0035.mediawiki BIP 35]. Since [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 37], if a [[Protocol_documentation#filterload.2C_filteradd.2C_filterclear.2C_merkleblock|bloom filter]] is loaded, only transactions matching the filter are replied.<br />
<br />
=== checkorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== submitorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== reply ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== ping ===<br />
<br />
The ''ping'' message is sent primarily to confirm that the TCP/IP connection is still valid. An error in transmission is presumed to be a closed connection and the address is removed as a current peer.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || random nonce<br />
|}<br />
<br />
=== pong ===<br />
<br />
The ''pong'' message is sent in response to a ''ping'' message. In modern protocol versions, a ''pong'' response is generated using a nonce included in the ping.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || nonce from ping<br />
|}<br />
<br />
<br />
=== reject===<br />
<br />
The ''reject'' message is sent when messages are rejected.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || message || var_str || type of message rejected<br />
|-<br />
| 1 || ccode || char || code relating to rejected message<br />
|-<br />
| 1+ || reason || var_str || text version of reason for rejection<br />
|-<br />
| 0+ || data || char || Optional extra data provided by some errors. Currently, all errors which provide this field fill it with the TXID or block header hash of the object being rejected, so the field is 32 bytes.<br />
|}<br />
<br />
CCodes<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0x01 || REJECT_MALFORMED|| <br />
|-<br />
| 0x10 || REJECT_INVALID ||<br />
|-<br />
| 0x11 || REJECT_OBSOLETE ||<br />
|-<br />
| 0x12 || REJECT_DUPLICATE ||<br />
|-<br />
| 0x40 || REJECT_NONSTANDARD ||<br />
|-<br />
| 0x41 || REJECT_DUST ||<br />
|-<br />
| 0x42 || REJECT_INSUFFICIENTFEE ||<br />
|-<br />
| 0x43 || REJECT_CHECKPOINT ||<br />
|}<br />
<br />
=== filterload, filteradd, filterclear, merkleblock ===<br />
<br />
These messages are related to Bloom filtering of connections and are defined in [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037].<br />
<br />
<br />
The <code>filterload</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || filter || uint8_t[] || The filter itself is simply a bit field of arbitrary byte-aligned size. The maximum size is 36,000 bytes.<br />
|-<br />
| 4 || nHashFuncs || uint32_t || The number of hash functions to use in this filter. The maximum value allowed in this field is 50.<br />
|-<br />
| 4 || nTweak || uint32_t || A random value to add to the seed value in the hash function used by the bloom filter.<br />
|-<br />
| 1 || nFlags || uint8_t || A set of flags that control how matched items are added to the filter.<br />
|}<br />
<br />
See below for a description of the Bloom filter algorithm and how to select nHashFuncs and filter size for a desired false positive rate.<br />
<br />
Upon receiving a <code>filterload</code> command, the remote peer will immediately restrict the broadcast transactions it announces (in inv packets) to transactions matching the filter, where the matching algorithm is specified below. The flags control the update behaviour of the matching algorithm.<br />
<br />
The <code>filteradd</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || data || uint8_t[] || The data element to add to the current filter.<br />
|}<br />
<br />
The data field must be smaller than or equal to 520 bytes in size (the maximum size of any potentially matched object).<br />
<br />
The given data element will be added to the Bloom filter. A filter must have been previously provided using <code>filterload</code>. This command is useful if a new key or script is added to a clients wallet whilst it has connections to the network open, it avoids the need to re-calculate and send an entirely new filter to every peer (though doing so is usually advisable to maintain anonymity).<br />
<br />
The <code>filterclear</code> command has no arguments at all.<br />
<br />
After a filter has been set, nodes don't merely stop announcing non-matching transactions, they can also serve filtered blocks. A filtered block is defined by the <code>merkleblock</code> message and is defined like this:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information, based upon the software version creating this block (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Limited to 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 4 || total_transactions || uint32_t || Number of transactions in the block (including unmatched ones)<br />
|-<br />
| ? || hashes || uint256[] || hashes in depth-first order (including standard varint size prefix)<br />
|-<br />
| ? || flags || byte[] || flag bits, packed per 8 in a byte, least significant bit first (including standard varint size prefix)<br />
|}<br />
<br />
=== alert ===<br />
<br />
An '''alert''' is sent between nodes to send a general notification message throughout the network. If the alert can be confirmed with the signature as having come from the core development group of the Bitcoin software, the message is suggested to be displayed for end-users. Attempts to perform transactions, particularly automated transactions through the client, are suggested to be halted. The text in the Message string should be relayed to log files and any user interfaces.<br />
<br />
Alert format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || payload || uchar[] || Serialized alert payload<br />
|-<br />
| ? || signature || uchar[] || An ECDSA signature of the message<br />
|}<br />
<br />
The developers of Satoshi's client use this public key for signing alerts:<br />
04fc9702847840aaf195de8442ebecedf5b095cdbb9bc716bda9110971b28a49e0ead8564ff0db22209e0374782c093bb899692d524e9d6a6956e7c5ecbcd68284<br />
(hash) 1AGRxqDa5WjUKBwHB9XYEjmkv1ucoUUy1s<br />
<br />
The payload is serialized into a uchar[] to ensure that versions using incompatible alert formats can still relay alerts among one another. The current alert payload format is:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || Version || int32_t || Alert format version<br />
|-<br />
| 8 || RelayUntil || int64_t || The timestamp beyond which nodes should stop relaying this alert<br />
|-<br />
| 8 || Expiration || int64_t || The timestamp beyond which this alert is no longer in effect and should be ignored<br />
|-<br />
| 4 || ID || int32_t || A unique ID number for this alert<br />
|-<br />
| 4 || Cancel || int32_t || All alerts with an ID number less than or equal to this number should be cancelled: deleted and not accepted in the future<br />
|-<br />
| ? || setCancel || set<int32_t> || All alert IDs contained in this set should be cancelled as above<br />
|-<br />
| 4 || MinVer || int32_t || This alert only applies to versions greater than or equal to this version. Other versions should still relay it.<br />
|-<br />
| 4 || MaxVer || int32_t || This alert only applies to versions less than or equal to this version. Other versions should still relay it.<br />
|-<br />
| ? || setSubVer || set<string> || If this set contains any elements, then only nodes that have their subVer contained in this set are affected by the alert. Other versions should still relay it.<br />
|-<br />
| 4 || Priority || int32_t || Relative priority compared to other alerts<br />
|-<br />
| ? || Comment || string || A comment on the alert that is not displayed<br />
|-<br />
| ? || StatusBar || string || The alert message that is displayed to the user<br />
|-<br />
| ? || Reserved || string || Reserved<br />
|}<br />
<br />
Note: '''set<''type''>''' in the table above is a [[#Variable length integer | variable length integer]] followed by the number of fields of the given ''type'' (either int32_t or [[#Variable length string | variable length string]])<br />
<br />
Sample alert (no message header):<br />
73010000003766404f00000000b305434f00000000f2030000f1030000001027000048ee0000<br />
0064000000004653656520626974636f696e2e6f72672f666562323020696620796f75206861<br />
76652074726f75626c6520636f6e6e656374696e672061667465722032302046656272756172<br />
79004730450221008389df45f0703f39ec8c1cc42c13810ffcae14995bb648340219e353b63b<br />
53eb022009ec65e1c1aaeec1fd334c6b684bde2b3f573060d5b70c3a46723326e4e8a4f1<br />
<br />
Version: 1<br />
RelayUntil: 1329620535<br />
Expiration: 1329792435<br />
ID: 1010<br />
Cancel: 1009<br />
setCancel: <empty><br />
MinVer: 10000<br />
MaxVer: 61000<br />
setSubVer: <empty><br />
Priority: 100<br />
Comment: <empty><br />
StatusBar: "See bitcoin.org/feb20 if you have trouble connecting after 20 February"<br />
Reserved: <empty><br />
<br />
=== sendheaders ===<br />
<br />
Request for Direct headers announcement. <br />
<br />
Upon receipt of this message, the node is be permitted, but not required, to announce new blocks by '''headers''' command (instead of '''inv''' command).<br />
<br />
This message is supported by the protocol version >= 70012 or Bitcoin Core version >= 0.12.0.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0130.mediawiki BIP 130] for more information.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
<br />
=== feefilter ===<br />
<br />
The payload is always 8 bytes long and it encodes 64 bit integer value (LSB / little endian) of '''feerate'''.<br />
The value represents a minimal fee and is expressed in satoshis per 1000 bytes.<br />
<br />
Upon receipt of a "feefilter" message, the node will be permitted, but not required, to filter transaction invs for transactions that fall below the feerate provided in the feefilter message interpreted as satoshis per kilobyte.<br />
<br />
The fee filter is additive with a bloom filter for transactions so if an SPV client were to load a bloom filter and send a feefilter message, transactions would only be relayed if they passed both filters.<br />
<br />
Inv's generated from a mempool message are also subject to a fee filter if it exists.<br />
<br />
Feature discovery is enabled by checking protocol version >= 70013<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0133.mediawiki BIP 133] for more information.<br />
<br />
== Scripting ==<br />
<br />
See [[script]].<br />
<br />
==See Also==<br />
<br />
* [[Network]]<br />
* [[Protocol rules]]<br />
* [[Hardfork Wishlist]]<br />
* [https://bitcoin.org/en/developer-documentation Developer Documentation on bitcoin.org]<br />
* Bitcoin dissectors for Wireshark: https://github.com/lbotsch/wireshark-bitcoin https://github.com/op-sig/bitcoin-wireshark-dissector<br />
<br />
==References==<br />
<references /><br />
<br />
[[zh-cn:协议说明]]<br />
[[Category:Technical]]<br />
[[Category:Developer]]<br />
<br />
{{Bitcoin Core documentation}}</div>Tonikthttps://en.bitcoin.it/w/index.php?title=Protocol_documentation&diff=61450Protocol documentation2016-08-15T11:47:47Z<p>Tonikt: /* feefilter */</p>
<hr />
<div>This page ''describes'' the behavior of the [[Original Bitcoin client|reference client]]. The Bitcoin protocol is specified by the behavior of the reference client, not by this page. In particular, while this page is quite complete in describing the network protocol, it does not attempt to list all of the rules for block or transaction validity.<br />
<br />
Type names used in this documentation are from the C99 standard.<br />
<br />
For protocol used in mining, see [[getblocktemplate]].<br />
<br />
==Common standards==<br />
<br />
=== Hashes ===<br />
<br />
Usually, when a hash is computed within bitcoin, it is computed twice. Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-256] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when a shorter hash is desirable (for example when creating a bitcoin address).<br />
<br />
Example of double-SHA-256 encoding of string "hello":<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round of sha-256)<br />
9595c9df90075148eb06860365df33584b75bff782a510c6cd4883a419833d50 (second round of sha-256)<br />
<br />
For bitcoin addresses (RIPEMD-160) this would give:<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round is sha-256)<br />
b6a9c8c230722b7c748331a8b450f05566dc7d0f (with ripemd-160)<br />
<br />
=== Merkle Trees ===<br />
<br />
Merkle trees are binary trees of hashes. Merkle trees in bitcoin use a '''double''' SHA-256, the SHA-256 hash of the SHA-256 hash of something.<br />
<br />
If, when forming a row in the tree (other than the root of the tree), it would have an odd number of elements, the final double-hash is duplicated to ensure that the row has an even number of hashes.<br />
<br />
First form the bottom row of the tree with the ordered double-SHA-256 hashes of the byte streams of the transactions in the block.<br />
<br />
Then the row above it consists of half that number of hashes. Each entry is the double-SHA-256 of the 64-byte concatenation of the corresponding two hashes below it in the tree.<br />
<br />
This procedure repeats recursively until we reach a row consisting of just a single double-hash. This is the '''Merkle root''' of the tree.<br />
<br />
For example, imagine a block with three transactions ''a'', ''b'' and ''c''. The Merkle tree is: <br />
<br />
d1 = dhash(a)<br />
d2 = dhash(b)<br />
d3 = dhash(c)<br />
d4 = dhash(c) # a, b, c are 3. that's an odd number, so we take the c twice<br />
<br />
d5 = dhash(d1 concat d2)<br />
d6 = dhash(d3 concat d4)<br />
<br />
d7 = dhash(d5 concat d6)<br />
<br />
where<br />
<br />
dhash(a) = sha256(sha256(a))<br />
<br />
''d7'' is the Merkle root of the 3 transactions in this block.<br />
<br />
Note: Hashes in Merkle Tree displayed in the [[Block Explorer]] are of little-endian notation. For some implementations and [http://www.fileformat.info/tool/hash.htm calculations], the bits need to be reversed before they are hashed, and again after the hashing operation.<br />
<br />
=== Signatures ===<br />
<br />
Bitcoin uses [http://en.wikipedia.org/wiki/Elliptic_curve_cryptography Elliptic Curve] [http://en.wikipedia.org/wiki/Digital_Signature_Algorithm Digital Signature Algorithm] ([http://en.wikipedia.org/wiki/Elliptic_Curve_DSA ECDSA]) to sign transactions. <br />
<br />
For [[ECDSA]] the secp256k1 curve from http://www.secg.org/collateral/sec2_final.pdf is used.<br />
<br />
Public keys (in scripts) are given as 04 <x> <y> where ''x'' and ''y'' are 32 byte big-endian integers representing the coordinates of a point on the curve or in compressed form given as <sign> <x> where <sign> is 0x02 if ''y'' is even and 0x03 if ''y'' is odd.<br />
<br />
Signatures use [http://en.wikipedia.org/wiki/Distinguished_Encoding_Rules DER encoding] to pack the ''r'' and ''s'' components into a single byte stream (this is also what OpenSSL produces by default).<br />
<br />
=== Transaction Verification ===<br />
Transactions are cryptographically signed records that reassign ownership of Bitcoins to new addresses. Transactions have ''inputs'' - records which reference the funds from other previous transactions - and ''outputs'' - records which determine the new owner of the transferred Bitcoins, and which will be referenced as inputs in future transactions as those funds are respent.<br />
<br />
Each ''input'' must have a cryptographic digital signature that unlocks the funds from the prior transaction. Only the person possessing the appropriate [[private key]] is able to create a satisfactory signature; this in effect ensures that funds can only be spent by their owners.<br />
<br />
Each ''output'' determines which Bitcoin address (or other criteria, see [[Script]]) is the recipient of the funds.<br />
<br />
In a transaction, the sum of all inputs must be equal to or greater than the sum of all outputs. If the inputs exceed the outputs, the difference is considered a [[transaction fee]], and is redeemable by whoever first includes the transaction into the block chain.<br />
<br />
A special kind of transaction, called a [[coinbase transaction]], has no inputs. It is created by [[miners]], and there is one coinbase transaction per block. Because each block comes with a reward of newly created Bitcoins (e.g. 50 BTC for the first 210,000 blocks), the first transaction of a block is, with few exceptions, the transaction that grants those coins to their recipient (the miner). In addition to the newly created Bitcoins, the coinbase transaction is also used for assigning the recipient of any transaction fees that were paid within the other transactions being included in the same block. The coinbase transaction can assign the entire reward to a single Bitcoin address, or split it in portions among multiple addresses, just like any other transaction. Coinbase transactions always contain outputs totalling the sum of the block reward plus all transaction fees collected from the other transactions in the same block.<br />
<br />
The [[coinbase transaction]] in block zero cannot be spent. This is due to a quirk of the reference client implementation that would open the potential for a block chain fork if some nodes accepted the spend and others did not<ref>[http://bitcointalk.org/index.php?topic=119645.msg1288552#msg1288552 Block 0 Network Fork]</ref>.<br />
<br />
Most Bitcoin outputs encumber the newly transferred coins with a single ECDSA private key. The actual record saved with inputs and outputs isn't necessarily a key, but a ''script''. Bitcoin uses an interpreted scripting system to determine whether an output's criteria have been satisfied, with which more complex operations are possible, such as outputs that require two ECDSA signatures, or two-of-three-signature schemes. An output that references a single Bitcoin address is a ''typical'' output; an output actually contains this information in the form of a script that requires a single ECDSA signature (see [[OP_CHECKSIG]]). The output script specifies what must be provided to unlock the funds later, and when the time comes in the future to spend the transaction in another input, that input must provide all of the thing(s) that satisfy the requirements defined by the original output script.<br />
<br />
=== Addresses ===<br />
<br />
A bitcoin address is in fact the hash of a ECDSA public key, computed this way:<br />
<br />
Version = 1 byte of 0 (zero); on the test network, this is 1 byte of 111<br />
Key hash = Version concatenated with RIPEMD-160(SHA-256(public key))<br />
Checksum = 1st 4 bytes of SHA-256(SHA-256(Key hash))<br />
Bitcoin Address = Base58Encode(Key hash concatenated with Checksum)<br />
<br />
The Base58 encoding used is home made, and has some differences. Especially, leading zeroes are kept as single zeroes when conversion happens.<br />
<br />
== Common structures ==<br />
<br />
Almost all integers are encoded in little endian. Only IP or port number are encoded big endian.<br />
<br />
=== Message structure ===<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown<br />
|-<br />
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| 4 || length || uint32_t || Length of payload in number of bytes<br />
|-<br />
| 4 || checksum || uint32_t || First 4 bytes of sha256(sha256(payload))<br />
|-<br />
| ? || payload || uchar[] || The actual data<br />
|}<br />
<br />
<br />
Known magic values:<br />
<br />
{|class="wikitable"<br />
! Network !! Magic value !! Sent over wire as<br />
|-<br />
| main || 0xD9B4BEF9 || F9 BE B4 D9<br />
|-<br />
| testnet || 0xDAB5BFFA || FA BF B5 DA<br />
|-<br />
| testnet3 || 0x0709110B || 0B 11 09 07<br />
|-<br />
| namecoin || 0xFEB4BEF9 || F9 BE B4 FE<br />
|}<br />
<br />
=== Variable length integer ===<br />
<br />
Integer can be encoded depending on the represented value to save space.<br />
Variable length integers always precede an array/vector of a type of data that may vary in length.<br />
Longer numbers are encoded in little endian.<br />
<br />
{|class="wikitable"<br />
! Value !! Storage length !! Format<br />
|-<br />
| < 0xFD || 1 || uint8_t<br />
|-<br />
| <= 0xFFFF || 3 || 0xFD followed by the length as uint16_t<br />
|-<br />
| <= 0xFFFF FFFF || 5 || 0xFE followed by the length as uint32_t<br />
|-<br />
| - || 9 || 0xFF followed by the length as uint64_t<br />
|}<br />
<br />
If you're reading the Satoshi client code (BitcoinQT) it refers to this encoding as a "CompactSize". Modern BitcoinQT also has the CVarInt class which implements an even more compact integer for the purpose of local storage (which is incompatible with "CompactSize" described here). CVarInt is not a part of the protocol.<br />
<br />
=== Variable length string ===<br />
<br />
Variable length string can be stored using a variable length integer followed by the string itself.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the string<br />
|-<br />
| ? || string || char[] || The string itself (can be empty)<br />
|}<br />
<br />
=== Network address ===<br />
<br />
When a network address is needed somewhere, this structure is used. Network addresses are not prefixed with a timestamp in the version message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || time || uint32 || the Time (version >= 31402). '''Not present in version message.'''<br />
|-<br />
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]<br />
|-<br />
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The original client only supported IPv4 and only read the last 4 bytes to get the IPv4 address. However, the IPv4 address is written into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]<br />
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).<br />
|-<br />
| 2 || port || uint16_t || port number, network byte order<br />
|}<br />
<br />
Hexdump example of Network address structure<br />
<br />
<pre><br />
0000 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0010 00 00 FF FF 0A 00 00 01 20 8D ........ .<br />
<br />
Network address:<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK: see services listed under version command)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv6: ::ffff:a00:1 or IPv4: 10.0.0.1<br />
20 8D - Port 8333<br />
</pre><br />
<br />
=== Inventory Vectors ===<br />
<br />
Inventory vectors are used for notifying other nodes about objects they have or data which is being requested.<br />
<br />
Inventory vectors consist of the following data format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || type || uint32_t || Identifies the object type linked to this inventory<br />
|-<br />
| 32 || hash || char[32] || Hash of the object<br />
|}<br />
<br />
<br />
The object type is currently defined as one of the following possibilities:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0 || ERROR || Any data of with this number may be ignored<br />
|-<br />
| 1 || MSG_TX || Hash is related to a transaction<br />
|-<br />
| 2 || MSG_BLOCK || Hash is related to a data block<br />
|-<br />
| 3 || MSG_FILTERED_BLOCK || Hash of a block header; identical to MSG_BLOCK. When used in a getdata message, this indicates the reply should be a merkleblock message rather than a block message; this only works if a bloom filter has been set.<br />
|}<br />
<br />
Other Data Type values are considered reserved for future implementations.<br />
<br />
=== Block Headers ===<br />
<br />
Block headers are sent in a headers packet in response to a getheaders message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Will overflow in 2106<ref>https://en.wikipedia.org/wiki/Unix_time#Notable_events_in_Unix_time</ref>)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 1 || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries, this value is always 0<br />
|}<br />
<br />
cf. [[Block hashing algorithm]]<br />
<br />
== Message types ==<br />
<br />
=== version ===<br />
<br />
When a node creates an outgoing connection, it will immediately [[Version Handshake|advertise]] its version. The remote node will respond with its version. No further communication is possible until both peers have exchanged their version.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Identifies protocol version being used by the node<br />
|-<br />
| 8 || services || uint64_t || bitfield of features to be enabled for this connection<br />
|-<br />
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds<br />
|-<br />
| 26 || addr_recv || [[#Network address|net_addr]] || The network address of the node receiving this message<br />
|-<br />
|colspan="4"| Fields below require version ≥ 106<br />
|-<br />
| 26 || addr_from || [[#Network address|net_addr]] || The network address of the node emitting this message<br />
|-<br />
| 8 || nonce || uint64_t || Node random nonce, randomly generated every time a version packet is sent. This nonce is used to detect connections to self.<br />
|-<br />
| ? || user_agent || [[#Variable length string|var_str]] || [https://github.com/bitcoin/bips/blob/master/bip-0014.mediawiki User Agent] (0x00 if string is 0 bytes long)<br />
|-<br />
| 4 || start_height || int32_t || The last block received by the emitting node<br />
|-<br />
|colspan="4"| Fields below require version ≥ 70001<br />
|-<br />
| 1 || relay || bool || Whether the remote peer should announce relayed transactions or not, see [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037]<br />
|}<br />
<br />
A "verack" packet shall be sent if the version packet was accepted.<br />
<br />
The following services are currently assigned:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 1 || NODE_NETWORK || This node can be asked for full blocks instead of just headers.<br />
|}<br />
<br />
Hexdump example of version message (OBSOLETE EXAMPLE: This example lacks a checksum and user-agent):<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....<br />
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........<br />
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............<br />
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................<br />
0040 20 8D 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,<br />
0060 3A B4 57 13 00 55 81 01 00 :.W..U...<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
55 00 00 00 - Payload is 85 bytes long<br />
- No checksum in version message until 20 February 2012. See https://bitcointalk.org/index.php?topic=55852.0<br />
Version message:<br />
9C 7C 00 00 - 31900 (version 0.3.19)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
E6 15 10 4D 00 00 00 00 - Mon Dec 20 21:50:14 EST 2010<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 20 8D - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D - Sender address info - see Network Address<br />
DD 9D 20 2C 3A B4 57 13 - Node random unique ID<br />
00 - "" sub-version string (string is 0 bytes long)<br />
55 81 01 00 - Last block sending node has is block #98645<br />
</pre><br />
<br />
And here's a modern (60002) protocol version client advertising itself to a local peer...<br />
<br />
Newer protocol includes the checksum now, this is from a mainline (satoshi) client during <br />
an outgoing connection to another local client, notice that it does not fill out the <br />
address information at all when the source or destination is "unroutable".<br />
<br />
<pre><br />
<br />
0000 f9 be b4 d9 76 65 72 73 69 6f 6e 00 00 00 00 00 ....version.....<br />
0010 64 00 00 00 35 8d 49 32 62 ea 00 00 01 00 00 00 d...5.I2b.......<br />
0020 00 00 00 00 11 b2 d0 50 00 00 00 00 01 00 00 00 .......P........<br />
0030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ff ff ................<br />
0040 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 00 00 00 00 ff ff 00 00 00 00 00 00 ................<br />
0060 3b 2e b3 5d 8c e6 17 65 0f 2f 53 61 74 6f 73 68 ;..]...e./Satosh<br />
0070 69 3a 30 2e 37 2e 32 2f c0 3e 03 00 i:0.7.2/.>..<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
64 00 00 00 - Payload is 100 bytes long<br />
3B 64 8D 5A - payload checksum<br />
<br />
Version message:<br />
62 EA 00 00 - 60002 (protocol version 60002)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
11 B2 D0 50 00 00 00 00 - Tue Dec 18 10:12:33 PST 2012<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Sender address info - see Network Address<br />
3B 2E B3 5D 8C E6 17 65 - Node ID<br />
0F 2F 53 61 74 6F 73 68 69 3A 30 2E 37 2E 32 2F - "/Satoshi:0.7.2/" sub-version string (string is 15 bytes long)<br />
C0 3E 03 00 - Last block sending node has is block #212672<br />
</pre><br />
<br />
=== verack ===<br />
<br />
The ''verack'' message is sent in reply to ''[[#version|version]]''. This message consists of only a [[#Message structure|message header]] with the command string "verack".<br />
<br />
Hexdump of the verack message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......<br />
0010 00 00 00 00 5D F6 E0 E2 ........<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 61 63 6B 00 00 00 00 00 00 - "verack" command<br />
00 00 00 00 - Payload is 0 bytes long<br />
5D F6 E0 E2 - Checksum<br />
</pre><br />
<br />
=== addr ===<br />
<br />
Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours<br />
<br />
Payload:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of address entries (max: 1000)<br />
|-<br />
| 30x? || addr_list || (uint32_t + [[#Network address|net_addr]])[] || Address of other nodes on the network. version < 209 will only read the first one. The uint32_t is a timestamp (see note below).<br />
|}<br />
<br />
'''Note''': Starting version 31402, addresses are prefixed with a timestamp. If no timestamp is present, the addresses should not be relayed to other peers, unless it is indeed confirmed they are up.<br />
<br />
Hexdump example of ''addr'' message:<br />
<pre><br />
0000 F9 BE B4 D9 61 64 64 72 00 00 00 00 00 00 00 00 ....addr........<br />
0010 1F 00 00 00 ED 52 39 9B 01 E2 15 10 4D 01 00 00 .....R9.....M...<br />
0020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF ................<br />
0030 FF 0A 00 00 01 20 8D ..... .<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
61 64 64 72 00 00 00 00 00 00 00 00 - "addr"<br />
1F 00 00 00 - payload is 31 bytes long<br />
ED 52 39 9B - checksum of payload<br />
<br />
Payload:<br />
01 - 1 address in this message<br />
<br />
Address:<br />
E2 15 10 4D - Mon Dec 20 21:50:10 EST 2010 (only when version is >= 31402)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK service - see version message)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv4: 10.0.0.1, IPv6: ::ffff:10.0.0.1 (IPv4-mapped IPv6 address)<br />
20 8D - port 8333<br />
</pre><br />
<br />
=== inv ===<br />
<br />
Allows a node to advertise its knowledge of one or more objects. It can be received unsolicited, or in reply to ''getblocks''.<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getdata ===<br />
<br />
getdata is used in response to inv, to retrieve the content of a specific object, and is usually sent after receiving an ''inv'' packet, after filtering known elements. It can be used to retrieve transactions, but only if they are in the memory pool or relay set - arbitrary access to transactions in the chain is not allowed to avoid having clients start to depend on nodes having full transaction indexes (which modern nodes do not).<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== notfound ===<br />
<br />
notfound is a response to a getdata, sent if any requested data items could not be relayed, for example, because the requested transaction was not in the memory pool or relay set.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getblocks ===<br />
<br />
Return an ''inv'' packet containing the list of blocks starting right after the last known hash in the block locator object, up to hash_stop or 500 blocks, whichever comes first. <br />
<br />
The locator hashes are processed by a node in the order as they appear in the message. If a block hash is found in the node's main chain, the list of its children is returned back via the ''inv'' message and the remaining locators are ignored, no matter if the requested limit was reached, or not.<br />
<br />
To receive the next blocks hashes, one needs to issue getblocks again with a new block locator object. Keep in mind that some clients may provide blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block; set to zero to get as many blocks as possible (500)<br />
|}<br />
<br />
To create the block locator hashes, keep pushing hashes until you go back to the genesis block. After pushing 10 hashes back, the step backwards doubles every loop:<br />
<br />
<pre><br />
// From libbitcoin which is under AGPL<br />
std::vector<size_t> block_locator_indexes(size_t top_height)<br />
{<br />
std::vector<size_t> indexes;<br />
<br />
// Modify the step in the iteration.<br />
int64_t step = 1;<br />
<br />
// Start at the top of the chain and work backwards.<br />
for (auto index = (int64_t)top_height; index > 0; index -= step)<br />
{<br />
// Push top 10 indexes first, then back off exponentially.<br />
if (indexes.size() >= 10)<br />
step *= 2;<br />
<br />
indexes.push_back((size_t)index);<br />
}<br />
<br />
// Push the genesis block index.<br />
indexes.push_back(0);<br />
return indexes;<br />
}<br />
</pre><br />
<br />
Note that it is allowed to send in fewer known hashes down to a minimum of just one hash. However, the purpose of the block locator object is to detect a wrong branch in the caller's main chain. If the peer detects that you are off the main chain, it will send in block hashes which are earlier than your last known block. So if you just send in your last known hash and it is off the main chain, the peer starts over at block #1.<br />
<br />
=== getheaders ===<br />
<br />
Return a ''headers'' packet containing the headers of blocks starting right after the last known hash in the block locator object, up to hash_stop or 2000 blocks, whichever comes first. To receive the next block headers, one needs to issue getheaders again with a new block locator object. The ''getheaders'' command is used by thin clients to quickly download the block chain where the contents of the transactions would be irrelevant (because they are not ours). Keep in mind that some clients may provide headers of blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block header; set to zero to get as many blocks as possible (2000)<br />
|}<br />
<br />
For the block locator object in this packet, the same rules apply as for the [[Protocol_documentation#getblocks|getblocks]] packet.<br />
<br />
=== tx ===<br />
<br />
''tx'' describes a bitcoin transaction, in reply to ''[[#getdata|getdata]]''<br />
<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Transaction data format version (note, this is signed)<br />
|-<br />
| 1+ || tx_in count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction inputs<br />
|-<br />
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins<br />
|-<br />
| 1+ || tx_out count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction outputs<br />
|-<br />
| 9+ || tx_out || tx_out[] || A list of 1 or more transaction outputs or destinations for coins<br />
|-<br />
| 4 || lock_time || uint32_t || The block number or timestamp at which this transaction is locked:<br />
{|class="wikitable"<br />
! Value !! Description<br />
|-<br />
| 0 || Not locked<br />
|-<br />
| < 500000000 || Block number at which this transaction is locked<br />
|-<br />
| >= 500000000 || UNIX timestamp at which this transaction is locked<br />
|}<br />
If all TxIn inputs have final (0xffffffff) sequence numbers then lock_time is irrelevant. Otherwise, the transaction may not be added to a block until after lock_time (see [[NLockTime]]).<br />
<br />
|}<br />
<br />
TxIn consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 36 || previous_output || outpoint || The previous output transaction reference, as an OutPoint structure<br />
|-<br />
| 1+ || script length || [[Protocol_documentation#Variable_length_integer|var_int]] || The length of the signature script<br />
|-<br />
| ? || signature script || uchar[] || Computational Script for confirming transaction authorization<br />
|-<br />
| 4 || [http://bitcoin.stackexchange.com/q/2025/323 sequence] || uint32_t || Transaction version as defined by the sender. Intended for "replacement" of transactions when information is updated before inclusion into a block.<br />
|}<br />
<br />
The OutPoint structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 32 || hash || char[32] || The hash of the referenced transaction.<br />
|-<br />
| 4 || index || uint32_t || The index of the specific output in the transaction. The first output is 0, etc.<br />
|}<br />
<br />
The Script structure consists of a series of pieces of information and operations related to the value of the transaction.<br />
<br />
(Structure to be expanded in the future… see script.h and script.cpp and [[Script]] for more information)<br />
<br />
The TxOut structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || value || int64_t || Transaction Value<br />
|-<br />
| 1+ || pk_script length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the pk_script<br />
|-<br />
| ? || pk_script || uchar[] || Usually contains the public key as a Bitcoin script setting up conditions to claim this output.<br />
|}<br />
<br />
Example ''tx'' message:<br />
<pre><br />
000000 F9 BE B4 D9 74 78 00 00 00 00 00 00 00 00 00 00 ....tx..........<br />
000010 02 01 00 00 E2 93 CD BE 01 00 00 00 01 6D BD DB .............m..<br />
000020 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D 12 66 E9 .[...Q........f.<br />
000030 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29 00 00 00 .;P......j.6)...<br />
000040 00 8B 48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 ..H0E.!..X..r...<br />
000050 C7 36 7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A .6zz%;..R#...h.:<br />
000060 59 23 3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 Y#?E.W... Y.....<br />
000070 0E 41 83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D .A.z.X.z...XN...<br />
000080 35 BD 96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF 5...6..;...A....<br />
000090 C9 7E F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 .~.6.m...@..!...<br />
0000A0 2A CD 2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC *.+..].}Y... ...<br />
0000B0 4E 02 53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F N.S..=7.o...Q...<br />
0000C0 14 04 2F 46 61 4A 4C 70 C0 F1 4B EF F5 FF FF FF ../FaJLp..K.....<br />
0000D0 FF 02 40 4B 4C 00 00 00 00 00 19 76 A9 14 1A A0 ..@KL......v....<br />
0000E0 CD 1C BE A6 E7 45 8A 7A BA D5 12 A9 D9 EA 1A FB .....E.z........<br />
0000F0 22 5E 88 AC 80 FA E9 C7 00 00 00 00 19 76 A9 14 "^...........v..<br />
000100 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E FD A0 B7 ..[.Cj.....H^...<br />
000110 8B 4E CC 52 88 AC 00 00 00 00 .N.R......<br />
<br />
<br />
Message header:<br />
F9 BE B4 D9 - main network magic bytes<br />
74 78 00 00 00 00 00 00 00 00 00 00 - "tx" command<br />
02 01 00 00 - payload is 258 bytes long<br />
E2 93 CD BE - checksum of payload<br />
<br />
Transaction:<br />
01 00 00 00 - version<br />
<br />
Inputs:<br />
01 - number of transaction inputs<br />
<br />
Input 1:<br />
6D BD DB 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D - previous output (outpoint)<br />
12 66 E9 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29<br />
00 00 00 00<br />
<br />
8B - script is 139 bytes long<br />
<br />
48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 C7 36 - signature script (scriptSig)<br />
7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A 59 23<br />
3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 0E 41<br />
83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D 35 BD<br />
96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF C9 7E<br />
F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 2A CD<br />
2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC 4E 02<br />
53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F 14 04<br />
2F 46 61 4A 4C 70 C0 F1 4B EF F5<br />
<br />
FF FF FF FF - sequence<br />
<br />
Outputs:<br />
02 - 2 Output Transactions<br />
<br />
Output 1:<br />
40 4B 4C 00 00 00 00 00 - 0.05 BTC (5000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 1A A0 CD 1C BE A6 E7 45 8A 7A BA D5 12 - pk_script<br />
A9 D9 EA 1A FB 22 5E 88 AC<br />
<br />
Output 2:<br />
80 FA E9 C7 00 00 00 00 - 33.54 BTC (3354000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E - pk_script<br />
FD A0 B7 8B 4E CC 52 88 AC<br />
<br />
Locktime:<br />
00 00 00 00 - lock time<br />
</pre><br />
<br />
=== block ===<br />
<br />
The '''block''' message is sent in response to a getdata message which requests transaction information from a block hash.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A Unix timestamp recording when this block was created (Currently limited to dates before the year 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated [[Difficulty|difficulty target]] being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| ? || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries<br />
|-<br />
| ? || txns || tx[] || Block transactions, in format of "tx" command<br />
|}<br />
<br />
The SHA256 hash that identifies each block (and which must have a run of 0 bits) is calculated from the first 6 fields of this structure (version, prev_block, merkle_root, timestamp, bits, nonce, and standard SHA256 padding, making two 64-byte chunks in all) and ''not'' from the complete block. To calculate the hash, only two chunks need to be processed by the SHA256 algorithm. Since the ''nonce'' field is in the second chunk, the first chunk stays constant during mining and therefore only the second chunk needs to be processed. However, a Bitcoin hash is the hash of the hash, so two SHA256 rounds are needed for each mining iteration.<br />
See [[Block hashing algorithm]] for details and an example.<br />
<br />
=== headers ===<br />
<br />
The ''headers'' packet returns block headers in response to a ''getheaders'' packet. <br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of block headers<br />
|-<br />
| 81x? || headers || [[Protocol_documentation#Block_Headers|block_header]][] || [[Protocol_documentation#Block_Headers|Block headers]]<br />
|}<br />
<br />
Note that the block headers in this packet include a transaction count (a var_int, so there can be more than 81 bytes per header) as opposed to the block headers that are hashed by miners.<br />
<br />
=== getaddr ===<br />
<br />
The getaddr message sends a request to a node asking for information about known active peers to help with finding potential nodes in the network. The response to receiving this message is to transmit one or more addr messages with one or more peers from a database of known active peers. The typical presumption is that a node is likely to be active if it has been sending a message within the last three hours.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
=== mempool ===<br />
<br />
The mempool message sends a request to a node asking for information about transactions it has verified but which have not yet confirmed. The response to receiving this message is an inv message containing the transaction hashes for all the transactions in the node's mempool.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
It is specified in [https://github.com/bitcoin/bips/blob/master/bip-0035.mediawiki BIP 35]. Since [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 37], if a [[Protocol_documentation#filterload.2C_filteradd.2C_filterclear.2C_merkleblock|bloom filter]] is loaded, only transactions matching the filter are replied.<br />
<br />
=== checkorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== submitorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== reply ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== ping ===<br />
<br />
The ''ping'' message is sent primarily to confirm that the TCP/IP connection is still valid. An error in transmission is presumed to be a closed connection and the address is removed as a current peer.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || random nonce<br />
|}<br />
<br />
=== pong ===<br />
<br />
The ''pong'' message is sent in response to a ''ping'' message. In modern protocol versions, a ''pong'' response is generated using a nonce included in the ping.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || nonce from ping<br />
|}<br />
<br />
<br />
=== reject===<br />
<br />
The ''reject'' message is sent when messages are rejected.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || message || var_str || type of message rejected<br />
|-<br />
| 1 || ccode || char || code relating to rejected message<br />
|-<br />
| 1+ || reason || var_str || text version of reason for rejection<br />
|-<br />
| 0+ || data || char || Optional extra data provided by some errors. Currently, all errors which provide this field fill it with the TXID or block header hash of the object being rejected, so the field is 32 bytes.<br />
|}<br />
<br />
CCodes<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0x01 || REJECT_MALFORMED|| <br />
|-<br />
| 0x10 || REJECT_INVALID ||<br />
|-<br />
| 0x11 || REJECT_OBSOLETE ||<br />
|-<br />
| 0x12 || REJECT_DUPLICATE ||<br />
|-<br />
| 0x40 || REJECT_NONSTANDARD ||<br />
|-<br />
| 0x41 || REJECT_DUST ||<br />
|-<br />
| 0x42 || REJECT_INSUFFICIENTFEE ||<br />
|-<br />
| 0x43 || REJECT_CHECKPOINT ||<br />
|}<br />
<br />
=== filterload, filteradd, filterclear, merkleblock ===<br />
<br />
These messages are related to Bloom filtering of connections and are defined in [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037].<br />
<br />
<br />
The <code>filterload</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || filter || uint8_t[] || The filter itself is simply a bit field of arbitrary byte-aligned size. The maximum size is 36,000 bytes.<br />
|-<br />
| 4 || nHashFuncs || uint32_t || The number of hash functions to use in this filter. The maximum value allowed in this field is 50.<br />
|-<br />
| 4 || nTweak || uint32_t || A random value to add to the seed value in the hash function used by the bloom filter.<br />
|-<br />
| 1 || nFlags || uint8_t || A set of flags that control how matched items are added to the filter.<br />
|}<br />
<br />
See below for a description of the Bloom filter algorithm and how to select nHashFuncs and filter size for a desired false positive rate.<br />
<br />
Upon receiving a <code>filterload</code> command, the remote peer will immediately restrict the broadcast transactions it announces (in inv packets) to transactions matching the filter, where the matching algorithm is specified below. The flags control the update behaviour of the matching algorithm.<br />
<br />
The <code>filteradd</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || data || uint8_t[] || The data element to add to the current filter.<br />
|}<br />
<br />
The data field must be smaller than or equal to 520 bytes in size (the maximum size of any potentially matched object).<br />
<br />
The given data element will be added to the Bloom filter. A filter must have been previously provided using <code>filterload</code>. This command is useful if a new key or script is added to a clients wallet whilst it has connections to the network open, it avoids the need to re-calculate and send an entirely new filter to every peer (though doing so is usually advisable to maintain anonymity).<br />
<br />
The <code>filterclear</code> command has no arguments at all.<br />
<br />
After a filter has been set, nodes don't merely stop announcing non-matching transactions, they can also serve filtered blocks. A filtered block is defined by the <code>merkleblock</code> message and is defined like this:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information, based upon the software version creating this block (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Limited to 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 4 || total_transactions || uint32_t || Number of transactions in the block (including unmatched ones)<br />
|-<br />
| ? || hashes || uint256[] || hashes in depth-first order (including standard varint size prefix)<br />
|-<br />
| ? || flags || byte[] || flag bits, packed per 8 in a byte, least significant bit first (including standard varint size prefix)<br />
|}<br />
<br />
=== alert ===<br />
<br />
An '''alert''' is sent between nodes to send a general notification message throughout the network. If the alert can be confirmed with the signature as having come from the core development group of the Bitcoin software, the message is suggested to be displayed for end-users. Attempts to perform transactions, particularly automated transactions through the client, are suggested to be halted. The text in the Message string should be relayed to log files and any user interfaces.<br />
<br />
Alert format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || payload || uchar[] || Serialized alert payload<br />
|-<br />
| ? || signature || uchar[] || An ECDSA signature of the message<br />
|}<br />
<br />
The developers of Satoshi's client use this public key for signing alerts:<br />
04fc9702847840aaf195de8442ebecedf5b095cdbb9bc716bda9110971b28a49e0ead8564ff0db22209e0374782c093bb899692d524e9d6a6956e7c5ecbcd68284<br />
(hash) 1AGRxqDa5WjUKBwHB9XYEjmkv1ucoUUy1s<br />
<br />
The payload is serialized into a uchar[] to ensure that versions using incompatible alert formats can still relay alerts among one another. The current alert payload format is:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || Version || int32_t || Alert format version<br />
|-<br />
| 8 || RelayUntil || int64_t || The timestamp beyond which nodes should stop relaying this alert<br />
|-<br />
| 8 || Expiration || int64_t || The timestamp beyond which this alert is no longer in effect and should be ignored<br />
|-<br />
| 4 || ID || int32_t || A unique ID number for this alert<br />
|-<br />
| 4 || Cancel || int32_t || All alerts with an ID number less than or equal to this number should be cancelled: deleted and not accepted in the future<br />
|-<br />
| ? || setCancel || set<int32_t> || All alert IDs contained in this set should be cancelled as above<br />
|-<br />
| 4 || MinVer || int32_t || This alert only applies to versions greater than or equal to this version. Other versions should still relay it.<br />
|-<br />
| 4 || MaxVer || int32_t || This alert only applies to versions less than or equal to this version. Other versions should still relay it.<br />
|-<br />
| ? || setSubVer || set<string> || If this set contains any elements, then only nodes that have their subVer contained in this set are affected by the alert. Other versions should still relay it.<br />
|-<br />
| 4 || Priority || int32_t || Relative priority compared to other alerts<br />
|-<br />
| ? || Comment || string || A comment on the alert that is not displayed<br />
|-<br />
| ? || StatusBar || string || The alert message that is displayed to the user<br />
|-<br />
| ? || Reserved || string || Reserved<br />
|}<br />
<br />
Note: '''set<''type''>''' in the table above is a [[#Variable length integer | variable length integer]] followed by the number of fields of the given ''type'' (either int32_t or [[#Variable length string | variable length string]])<br />
<br />
Sample alert (no message header):<br />
73010000003766404f00000000b305434f00000000f2030000f1030000001027000048ee0000<br />
0064000000004653656520626974636f696e2e6f72672f666562323020696620796f75206861<br />
76652074726f75626c6520636f6e6e656374696e672061667465722032302046656272756172<br />
79004730450221008389df45f0703f39ec8c1cc42c13810ffcae14995bb648340219e353b63b<br />
53eb022009ec65e1c1aaeec1fd334c6b684bde2b3f573060d5b70c3a46723326e4e8a4f1<br />
<br />
Version: 1<br />
RelayUntil: 1329620535<br />
Expiration: 1329792435<br />
ID: 1010<br />
Cancel: 1009<br />
setCancel: <empty><br />
MinVer: 10000<br />
MaxVer: 61000<br />
setSubVer: <empty><br />
Priority: 100<br />
Comment: <empty><br />
StatusBar: "See bitcoin.org/feb20 if you have trouble connecting after 20 February"<br />
Reserved: <empty><br />
<br />
=== sendheaders ===<br />
<br />
Request for Direct headers announcement. <br />
<br />
Upon receipt of this message, the node is be permitted, but not required, to announce new blocks by '''headers''' command (instead of '''inv''' command).<br />
<br />
This message is supported by the protocol version >= 70012 or Bitcoin Core version >= 0.12.0.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0130.mediawiki BIP 130] for more information.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
<br />
=== feefilter ===<br />
<br />
The payload is always 8 bytes long and it encodes 64 bit integer value (LSB / little endian) of '''feerate'''.<br />
The value represents a minimal fee and is expressed in satoshis per 1000 bytes.<br />
<br />
Upon receipt of a "feefilter" message, the node will be permitted, but not required, to filter transaction invs for transactions that fall below the feerate provided in the feefilter message interpreted as satoshis per kilobyte.<br />
<br />
The fee filter is additive with a bloom filter for transactions so if an SPV client were to load a bloom filter and send a feefilter message, transactions would only be relayed if they passed both filters.<br />
<br />
Inv's generated from a mempool message are also subject to a fee filter if it exists.<br />
<br />
Feature discovery is enabled by checking protocol version >= 70013<br />
<br />
== Scripting ==<br />
<br />
See [[script]].<br />
<br />
==See Also==<br />
<br />
* [[Network]]<br />
* [[Protocol rules]]<br />
* [[Hardfork Wishlist]]<br />
* [https://bitcoin.org/en/developer-documentation Developer Documentation on bitcoin.org]<br />
* Bitcoin dissectors for Wireshark: https://github.com/lbotsch/wireshark-bitcoin https://github.com/op-sig/bitcoin-wireshark-dissector<br />
<br />
==References==<br />
<references /><br />
<br />
[[zh-cn:协议说明]]<br />
[[Category:Technical]]<br />
[[Category:Developer]]<br />
<br />
{{Bitcoin Core documentation}}</div>Tonikthttps://en.bitcoin.it/w/index.php?title=Protocol_documentation&diff=61449Protocol documentation2016-08-15T11:43:05Z<p>Tonikt: added feefilter</p>
<hr />
<div>This page ''describes'' the behavior of the [[Original Bitcoin client|reference client]]. The Bitcoin protocol is specified by the behavior of the reference client, not by this page. In particular, while this page is quite complete in describing the network protocol, it does not attempt to list all of the rules for block or transaction validity.<br />
<br />
Type names used in this documentation are from the C99 standard.<br />
<br />
For protocol used in mining, see [[getblocktemplate]].<br />
<br />
==Common standards==<br />
<br />
=== Hashes ===<br />
<br />
Usually, when a hash is computed within bitcoin, it is computed twice. Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-256] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when a shorter hash is desirable (for example when creating a bitcoin address).<br />
<br />
Example of double-SHA-256 encoding of string "hello":<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round of sha-256)<br />
9595c9df90075148eb06860365df33584b75bff782a510c6cd4883a419833d50 (second round of sha-256)<br />
<br />
For bitcoin addresses (RIPEMD-160) this would give:<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round is sha-256)<br />
b6a9c8c230722b7c748331a8b450f05566dc7d0f (with ripemd-160)<br />
<br />
=== Merkle Trees ===<br />
<br />
Merkle trees are binary trees of hashes. Merkle trees in bitcoin use a '''double''' SHA-256, the SHA-256 hash of the SHA-256 hash of something.<br />
<br />
If, when forming a row in the tree (other than the root of the tree), it would have an odd number of elements, the final double-hash is duplicated to ensure that the row has an even number of hashes.<br />
<br />
First form the bottom row of the tree with the ordered double-SHA-256 hashes of the byte streams of the transactions in the block.<br />
<br />
Then the row above it consists of half that number of hashes. Each entry is the double-SHA-256 of the 64-byte concatenation of the corresponding two hashes below it in the tree.<br />
<br />
This procedure repeats recursively until we reach a row consisting of just a single double-hash. This is the '''Merkle root''' of the tree.<br />
<br />
For example, imagine a block with three transactions ''a'', ''b'' and ''c''. The Merkle tree is: <br />
<br />
d1 = dhash(a)<br />
d2 = dhash(b)<br />
d3 = dhash(c)<br />
d4 = dhash(c) # a, b, c are 3. that's an odd number, so we take the c twice<br />
<br />
d5 = dhash(d1 concat d2)<br />
d6 = dhash(d3 concat d4)<br />
<br />
d7 = dhash(d5 concat d6)<br />
<br />
where<br />
<br />
dhash(a) = sha256(sha256(a))<br />
<br />
''d7'' is the Merkle root of the 3 transactions in this block.<br />
<br />
Note: Hashes in Merkle Tree displayed in the [[Block Explorer]] are of little-endian notation. For some implementations and [http://www.fileformat.info/tool/hash.htm calculations], the bits need to be reversed before they are hashed, and again after the hashing operation.<br />
<br />
=== Signatures ===<br />
<br />
Bitcoin uses [http://en.wikipedia.org/wiki/Elliptic_curve_cryptography Elliptic Curve] [http://en.wikipedia.org/wiki/Digital_Signature_Algorithm Digital Signature Algorithm] ([http://en.wikipedia.org/wiki/Elliptic_Curve_DSA ECDSA]) to sign transactions. <br />
<br />
For [[ECDSA]] the secp256k1 curve from http://www.secg.org/collateral/sec2_final.pdf is used.<br />
<br />
Public keys (in scripts) are given as 04 <x> <y> where ''x'' and ''y'' are 32 byte big-endian integers representing the coordinates of a point on the curve or in compressed form given as <sign> <x> where <sign> is 0x02 if ''y'' is even and 0x03 if ''y'' is odd.<br />
<br />
Signatures use [http://en.wikipedia.org/wiki/Distinguished_Encoding_Rules DER encoding] to pack the ''r'' and ''s'' components into a single byte stream (this is also what OpenSSL produces by default).<br />
<br />
=== Transaction Verification ===<br />
Transactions are cryptographically signed records that reassign ownership of Bitcoins to new addresses. Transactions have ''inputs'' - records which reference the funds from other previous transactions - and ''outputs'' - records which determine the new owner of the transferred Bitcoins, and which will be referenced as inputs in future transactions as those funds are respent.<br />
<br />
Each ''input'' must have a cryptographic digital signature that unlocks the funds from the prior transaction. Only the person possessing the appropriate [[private key]] is able to create a satisfactory signature; this in effect ensures that funds can only be spent by their owners.<br />
<br />
Each ''output'' determines which Bitcoin address (or other criteria, see [[Script]]) is the recipient of the funds.<br />
<br />
In a transaction, the sum of all inputs must be equal to or greater than the sum of all outputs. If the inputs exceed the outputs, the difference is considered a [[transaction fee]], and is redeemable by whoever first includes the transaction into the block chain.<br />
<br />
A special kind of transaction, called a [[coinbase transaction]], has no inputs. It is created by [[miners]], and there is one coinbase transaction per block. Because each block comes with a reward of newly created Bitcoins (e.g. 50 BTC for the first 210,000 blocks), the first transaction of a block is, with few exceptions, the transaction that grants those coins to their recipient (the miner). In addition to the newly created Bitcoins, the coinbase transaction is also used for assigning the recipient of any transaction fees that were paid within the other transactions being included in the same block. The coinbase transaction can assign the entire reward to a single Bitcoin address, or split it in portions among multiple addresses, just like any other transaction. Coinbase transactions always contain outputs totalling the sum of the block reward plus all transaction fees collected from the other transactions in the same block.<br />
<br />
The [[coinbase transaction]] in block zero cannot be spent. This is due to a quirk of the reference client implementation that would open the potential for a block chain fork if some nodes accepted the spend and others did not<ref>[http://bitcointalk.org/index.php?topic=119645.msg1288552#msg1288552 Block 0 Network Fork]</ref>.<br />
<br />
Most Bitcoin outputs encumber the newly transferred coins with a single ECDSA private key. The actual record saved with inputs and outputs isn't necessarily a key, but a ''script''. Bitcoin uses an interpreted scripting system to determine whether an output's criteria have been satisfied, with which more complex operations are possible, such as outputs that require two ECDSA signatures, or two-of-three-signature schemes. An output that references a single Bitcoin address is a ''typical'' output; an output actually contains this information in the form of a script that requires a single ECDSA signature (see [[OP_CHECKSIG]]). The output script specifies what must be provided to unlock the funds later, and when the time comes in the future to spend the transaction in another input, that input must provide all of the thing(s) that satisfy the requirements defined by the original output script.<br />
<br />
=== Addresses ===<br />
<br />
A bitcoin address is in fact the hash of a ECDSA public key, computed this way:<br />
<br />
Version = 1 byte of 0 (zero); on the test network, this is 1 byte of 111<br />
Key hash = Version concatenated with RIPEMD-160(SHA-256(public key))<br />
Checksum = 1st 4 bytes of SHA-256(SHA-256(Key hash))<br />
Bitcoin Address = Base58Encode(Key hash concatenated with Checksum)<br />
<br />
The Base58 encoding used is home made, and has some differences. Especially, leading zeroes are kept as single zeroes when conversion happens.<br />
<br />
== Common structures ==<br />
<br />
Almost all integers are encoded in little endian. Only IP or port number are encoded big endian.<br />
<br />
=== Message structure ===<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown<br />
|-<br />
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| 4 || length || uint32_t || Length of payload in number of bytes<br />
|-<br />
| 4 || checksum || uint32_t || First 4 bytes of sha256(sha256(payload))<br />
|-<br />
| ? || payload || uchar[] || The actual data<br />
|}<br />
<br />
<br />
Known magic values:<br />
<br />
{|class="wikitable"<br />
! Network !! Magic value !! Sent over wire as<br />
|-<br />
| main || 0xD9B4BEF9 || F9 BE B4 D9<br />
|-<br />
| testnet || 0xDAB5BFFA || FA BF B5 DA<br />
|-<br />
| testnet3 || 0x0709110B || 0B 11 09 07<br />
|-<br />
| namecoin || 0xFEB4BEF9 || F9 BE B4 FE<br />
|}<br />
<br />
=== Variable length integer ===<br />
<br />
Integer can be encoded depending on the represented value to save space.<br />
Variable length integers always precede an array/vector of a type of data that may vary in length.<br />
Longer numbers are encoded in little endian.<br />
<br />
{|class="wikitable"<br />
! Value !! Storage length !! Format<br />
|-<br />
| < 0xFD || 1 || uint8_t<br />
|-<br />
| <= 0xFFFF || 3 || 0xFD followed by the length as uint16_t<br />
|-<br />
| <= 0xFFFF FFFF || 5 || 0xFE followed by the length as uint32_t<br />
|-<br />
| - || 9 || 0xFF followed by the length as uint64_t<br />
|}<br />
<br />
If you're reading the Satoshi client code (BitcoinQT) it refers to this encoding as a "CompactSize". Modern BitcoinQT also has the CVarInt class which implements an even more compact integer for the purpose of local storage (which is incompatible with "CompactSize" described here). CVarInt is not a part of the protocol.<br />
<br />
=== Variable length string ===<br />
<br />
Variable length string can be stored using a variable length integer followed by the string itself.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the string<br />
|-<br />
| ? || string || char[] || The string itself (can be empty)<br />
|}<br />
<br />
=== Network address ===<br />
<br />
When a network address is needed somewhere, this structure is used. Network addresses are not prefixed with a timestamp in the version message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || time || uint32 || the Time (version >= 31402). '''Not present in version message.'''<br />
|-<br />
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]<br />
|-<br />
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The original client only supported IPv4 and only read the last 4 bytes to get the IPv4 address. However, the IPv4 address is written into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]<br />
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).<br />
|-<br />
| 2 || port || uint16_t || port number, network byte order<br />
|}<br />
<br />
Hexdump example of Network address structure<br />
<br />
<pre><br />
0000 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0010 00 00 FF FF 0A 00 00 01 20 8D ........ .<br />
<br />
Network address:<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK: see services listed under version command)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv6: ::ffff:a00:1 or IPv4: 10.0.0.1<br />
20 8D - Port 8333<br />
</pre><br />
<br />
=== Inventory Vectors ===<br />
<br />
Inventory vectors are used for notifying other nodes about objects they have or data which is being requested.<br />
<br />
Inventory vectors consist of the following data format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || type || uint32_t || Identifies the object type linked to this inventory<br />
|-<br />
| 32 || hash || char[32] || Hash of the object<br />
|}<br />
<br />
<br />
The object type is currently defined as one of the following possibilities:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0 || ERROR || Any data of with this number may be ignored<br />
|-<br />
| 1 || MSG_TX || Hash is related to a transaction<br />
|-<br />
| 2 || MSG_BLOCK || Hash is related to a data block<br />
|-<br />
| 3 || MSG_FILTERED_BLOCK || Hash of a block header; identical to MSG_BLOCK. When used in a getdata message, this indicates the reply should be a merkleblock message rather than a block message; this only works if a bloom filter has been set.<br />
|}<br />
<br />
Other Data Type values are considered reserved for future implementations.<br />
<br />
=== Block Headers ===<br />
<br />
Block headers are sent in a headers packet in response to a getheaders message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Will overflow in 2106<ref>https://en.wikipedia.org/wiki/Unix_time#Notable_events_in_Unix_time</ref>)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 1 || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries, this value is always 0<br />
|}<br />
<br />
cf. [[Block hashing algorithm]]<br />
<br />
== Message types ==<br />
<br />
=== version ===<br />
<br />
When a node creates an outgoing connection, it will immediately [[Version Handshake|advertise]] its version. The remote node will respond with its version. No further communication is possible until both peers have exchanged their version.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Identifies protocol version being used by the node<br />
|-<br />
| 8 || services || uint64_t || bitfield of features to be enabled for this connection<br />
|-<br />
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds<br />
|-<br />
| 26 || addr_recv || [[#Network address|net_addr]] || The network address of the node receiving this message<br />
|-<br />
|colspan="4"| Fields below require version ≥ 106<br />
|-<br />
| 26 || addr_from || [[#Network address|net_addr]] || The network address of the node emitting this message<br />
|-<br />
| 8 || nonce || uint64_t || Node random nonce, randomly generated every time a version packet is sent. This nonce is used to detect connections to self.<br />
|-<br />
| ? || user_agent || [[#Variable length string|var_str]] || [https://github.com/bitcoin/bips/blob/master/bip-0014.mediawiki User Agent] (0x00 if string is 0 bytes long)<br />
|-<br />
| 4 || start_height || int32_t || The last block received by the emitting node<br />
|-<br />
|colspan="4"| Fields below require version ≥ 70001<br />
|-<br />
| 1 || relay || bool || Whether the remote peer should announce relayed transactions or not, see [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037]<br />
|}<br />
<br />
A "verack" packet shall be sent if the version packet was accepted.<br />
<br />
The following services are currently assigned:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 1 || NODE_NETWORK || This node can be asked for full blocks instead of just headers.<br />
|}<br />
<br />
Hexdump example of version message (OBSOLETE EXAMPLE: This example lacks a checksum and user-agent):<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....<br />
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........<br />
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............<br />
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................<br />
0040 20 8D 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,<br />
0060 3A B4 57 13 00 55 81 01 00 :.W..U...<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
55 00 00 00 - Payload is 85 bytes long<br />
- No checksum in version message until 20 February 2012. See https://bitcointalk.org/index.php?topic=55852.0<br />
Version message:<br />
9C 7C 00 00 - 31900 (version 0.3.19)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
E6 15 10 4D 00 00 00 00 - Mon Dec 20 21:50:14 EST 2010<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 20 8D - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D - Sender address info - see Network Address<br />
DD 9D 20 2C 3A B4 57 13 - Node random unique ID<br />
00 - "" sub-version string (string is 0 bytes long)<br />
55 81 01 00 - Last block sending node has is block #98645<br />
</pre><br />
<br />
And here's a modern (60002) protocol version client advertising itself to a local peer...<br />
<br />
Newer protocol includes the checksum now, this is from a mainline (satoshi) client during <br />
an outgoing connection to another local client, notice that it does not fill out the <br />
address information at all when the source or destination is "unroutable".<br />
<br />
<pre><br />
<br />
0000 f9 be b4 d9 76 65 72 73 69 6f 6e 00 00 00 00 00 ....version.....<br />
0010 64 00 00 00 35 8d 49 32 62 ea 00 00 01 00 00 00 d...5.I2b.......<br />
0020 00 00 00 00 11 b2 d0 50 00 00 00 00 01 00 00 00 .......P........<br />
0030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ff ff ................<br />
0040 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 00 00 00 00 ff ff 00 00 00 00 00 00 ................<br />
0060 3b 2e b3 5d 8c e6 17 65 0f 2f 53 61 74 6f 73 68 ;..]...e./Satosh<br />
0070 69 3a 30 2e 37 2e 32 2f c0 3e 03 00 i:0.7.2/.>..<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
64 00 00 00 - Payload is 100 bytes long<br />
3B 64 8D 5A - payload checksum<br />
<br />
Version message:<br />
62 EA 00 00 - 60002 (protocol version 60002)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
11 B2 D0 50 00 00 00 00 - Tue Dec 18 10:12:33 PST 2012<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Sender address info - see Network Address<br />
3B 2E B3 5D 8C E6 17 65 - Node ID<br />
0F 2F 53 61 74 6F 73 68 69 3A 30 2E 37 2E 32 2F - "/Satoshi:0.7.2/" sub-version string (string is 15 bytes long)<br />
C0 3E 03 00 - Last block sending node has is block #212672<br />
</pre><br />
<br />
=== verack ===<br />
<br />
The ''verack'' message is sent in reply to ''[[#version|version]]''. This message consists of only a [[#Message structure|message header]] with the command string "verack".<br />
<br />
Hexdump of the verack message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......<br />
0010 00 00 00 00 5D F6 E0 E2 ........<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 61 63 6B 00 00 00 00 00 00 - "verack" command<br />
00 00 00 00 - Payload is 0 bytes long<br />
5D F6 E0 E2 - Checksum<br />
</pre><br />
<br />
=== addr ===<br />
<br />
Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours<br />
<br />
Payload:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of address entries (max: 1000)<br />
|-<br />
| 30x? || addr_list || (uint32_t + [[#Network address|net_addr]])[] || Address of other nodes on the network. version < 209 will only read the first one. The uint32_t is a timestamp (see note below).<br />
|}<br />
<br />
'''Note''': Starting version 31402, addresses are prefixed with a timestamp. If no timestamp is present, the addresses should not be relayed to other peers, unless it is indeed confirmed they are up.<br />
<br />
Hexdump example of ''addr'' message:<br />
<pre><br />
0000 F9 BE B4 D9 61 64 64 72 00 00 00 00 00 00 00 00 ....addr........<br />
0010 1F 00 00 00 ED 52 39 9B 01 E2 15 10 4D 01 00 00 .....R9.....M...<br />
0020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF ................<br />
0030 FF 0A 00 00 01 20 8D ..... .<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
61 64 64 72 00 00 00 00 00 00 00 00 - "addr"<br />
1F 00 00 00 - payload is 31 bytes long<br />
ED 52 39 9B - checksum of payload<br />
<br />
Payload:<br />
01 - 1 address in this message<br />
<br />
Address:<br />
E2 15 10 4D - Mon Dec 20 21:50:10 EST 2010 (only when version is >= 31402)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK service - see version message)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv4: 10.0.0.1, IPv6: ::ffff:10.0.0.1 (IPv4-mapped IPv6 address)<br />
20 8D - port 8333<br />
</pre><br />
<br />
=== inv ===<br />
<br />
Allows a node to advertise its knowledge of one or more objects. It can be received unsolicited, or in reply to ''getblocks''.<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getdata ===<br />
<br />
getdata is used in response to inv, to retrieve the content of a specific object, and is usually sent after receiving an ''inv'' packet, after filtering known elements. It can be used to retrieve transactions, but only if they are in the memory pool or relay set - arbitrary access to transactions in the chain is not allowed to avoid having clients start to depend on nodes having full transaction indexes (which modern nodes do not).<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== notfound ===<br />
<br />
notfound is a response to a getdata, sent if any requested data items could not be relayed, for example, because the requested transaction was not in the memory pool or relay set.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getblocks ===<br />
<br />
Return an ''inv'' packet containing the list of blocks starting right after the last known hash in the block locator object, up to hash_stop or 500 blocks, whichever comes first. <br />
<br />
The locator hashes are processed by a node in the order as they appear in the message. If a block hash is found in the node's main chain, the list of its children is returned back via the ''inv'' message and the remaining locators are ignored, no matter if the requested limit was reached, or not.<br />
<br />
To receive the next blocks hashes, one needs to issue getblocks again with a new block locator object. Keep in mind that some clients may provide blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block; set to zero to get as many blocks as possible (500)<br />
|}<br />
<br />
To create the block locator hashes, keep pushing hashes until you go back to the genesis block. After pushing 10 hashes back, the step backwards doubles every loop:<br />
<br />
<pre><br />
// From libbitcoin which is under AGPL<br />
std::vector<size_t> block_locator_indexes(size_t top_height)<br />
{<br />
std::vector<size_t> indexes;<br />
<br />
// Modify the step in the iteration.<br />
int64_t step = 1;<br />
<br />
// Start at the top of the chain and work backwards.<br />
for (auto index = (int64_t)top_height; index > 0; index -= step)<br />
{<br />
// Push top 10 indexes first, then back off exponentially.<br />
if (indexes.size() >= 10)<br />
step *= 2;<br />
<br />
indexes.push_back((size_t)index);<br />
}<br />
<br />
// Push the genesis block index.<br />
indexes.push_back(0);<br />
return indexes;<br />
}<br />
</pre><br />
<br />
Note that it is allowed to send in fewer known hashes down to a minimum of just one hash. However, the purpose of the block locator object is to detect a wrong branch in the caller's main chain. If the peer detects that you are off the main chain, it will send in block hashes which are earlier than your last known block. So if you just send in your last known hash and it is off the main chain, the peer starts over at block #1.<br />
<br />
=== getheaders ===<br />
<br />
Return a ''headers'' packet containing the headers of blocks starting right after the last known hash in the block locator object, up to hash_stop or 2000 blocks, whichever comes first. To receive the next block headers, one needs to issue getheaders again with a new block locator object. The ''getheaders'' command is used by thin clients to quickly download the block chain where the contents of the transactions would be irrelevant (because they are not ours). Keep in mind that some clients may provide headers of blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block header; set to zero to get as many blocks as possible (2000)<br />
|}<br />
<br />
For the block locator object in this packet, the same rules apply as for the [[Protocol_documentation#getblocks|getblocks]] packet.<br />
<br />
=== tx ===<br />
<br />
''tx'' describes a bitcoin transaction, in reply to ''[[#getdata|getdata]]''<br />
<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Transaction data format version (note, this is signed)<br />
|-<br />
| 1+ || tx_in count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction inputs<br />
|-<br />
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins<br />
|-<br />
| 1+ || tx_out count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction outputs<br />
|-<br />
| 9+ || tx_out || tx_out[] || A list of 1 or more transaction outputs or destinations for coins<br />
|-<br />
| 4 || lock_time || uint32_t || The block number or timestamp at which this transaction is locked:<br />
{|class="wikitable"<br />
! Value !! Description<br />
|-<br />
| 0 || Not locked<br />
|-<br />
| < 500000000 || Block number at which this transaction is locked<br />
|-<br />
| >= 500000000 || UNIX timestamp at which this transaction is locked<br />
|}<br />
If all TxIn inputs have final (0xffffffff) sequence numbers then lock_time is irrelevant. Otherwise, the transaction may not be added to a block until after lock_time (see [[NLockTime]]).<br />
<br />
|}<br />
<br />
TxIn consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 36 || previous_output || outpoint || The previous output transaction reference, as an OutPoint structure<br />
|-<br />
| 1+ || script length || [[Protocol_documentation#Variable_length_integer|var_int]] || The length of the signature script<br />
|-<br />
| ? || signature script || uchar[] || Computational Script for confirming transaction authorization<br />
|-<br />
| 4 || [http://bitcoin.stackexchange.com/q/2025/323 sequence] || uint32_t || Transaction version as defined by the sender. Intended for "replacement" of transactions when information is updated before inclusion into a block.<br />
|}<br />
<br />
The OutPoint structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 32 || hash || char[32] || The hash of the referenced transaction.<br />
|-<br />
| 4 || index || uint32_t || The index of the specific output in the transaction. The first output is 0, etc.<br />
|}<br />
<br />
The Script structure consists of a series of pieces of information and operations related to the value of the transaction.<br />
<br />
(Structure to be expanded in the future… see script.h and script.cpp and [[Script]] for more information)<br />
<br />
The TxOut structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || value || int64_t || Transaction Value<br />
|-<br />
| 1+ || pk_script length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the pk_script<br />
|-<br />
| ? || pk_script || uchar[] || Usually contains the public key as a Bitcoin script setting up conditions to claim this output.<br />
|}<br />
<br />
Example ''tx'' message:<br />
<pre><br />
000000 F9 BE B4 D9 74 78 00 00 00 00 00 00 00 00 00 00 ....tx..........<br />
000010 02 01 00 00 E2 93 CD BE 01 00 00 00 01 6D BD DB .............m..<br />
000020 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D 12 66 E9 .[...Q........f.<br />
000030 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29 00 00 00 .;P......j.6)...<br />
000040 00 8B 48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 ..H0E.!..X..r...<br />
000050 C7 36 7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A .6zz%;..R#...h.:<br />
000060 59 23 3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 Y#?E.W... Y.....<br />
000070 0E 41 83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D .A.z.X.z...XN...<br />
000080 35 BD 96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF 5...6..;...A....<br />
000090 C9 7E F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 .~.6.m...@..!...<br />
0000A0 2A CD 2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC *.+..].}Y... ...<br />
0000B0 4E 02 53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F N.S..=7.o...Q...<br />
0000C0 14 04 2F 46 61 4A 4C 70 C0 F1 4B EF F5 FF FF FF ../FaJLp..K.....<br />
0000D0 FF 02 40 4B 4C 00 00 00 00 00 19 76 A9 14 1A A0 ..@KL......v....<br />
0000E0 CD 1C BE A6 E7 45 8A 7A BA D5 12 A9 D9 EA 1A FB .....E.z........<br />
0000F0 22 5E 88 AC 80 FA E9 C7 00 00 00 00 19 76 A9 14 "^...........v..<br />
000100 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E FD A0 B7 ..[.Cj.....H^...<br />
000110 8B 4E CC 52 88 AC 00 00 00 00 .N.R......<br />
<br />
<br />
Message header:<br />
F9 BE B4 D9 - main network magic bytes<br />
74 78 00 00 00 00 00 00 00 00 00 00 - "tx" command<br />
02 01 00 00 - payload is 258 bytes long<br />
E2 93 CD BE - checksum of payload<br />
<br />
Transaction:<br />
01 00 00 00 - version<br />
<br />
Inputs:<br />
01 - number of transaction inputs<br />
<br />
Input 1:<br />
6D BD DB 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D - previous output (outpoint)<br />
12 66 E9 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29<br />
00 00 00 00<br />
<br />
8B - script is 139 bytes long<br />
<br />
48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 C7 36 - signature script (scriptSig)<br />
7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A 59 23<br />
3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 0E 41<br />
83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D 35 BD<br />
96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF C9 7E<br />
F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 2A CD<br />
2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC 4E 02<br />
53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F 14 04<br />
2F 46 61 4A 4C 70 C0 F1 4B EF F5<br />
<br />
FF FF FF FF - sequence<br />
<br />
Outputs:<br />
02 - 2 Output Transactions<br />
<br />
Output 1:<br />
40 4B 4C 00 00 00 00 00 - 0.05 BTC (5000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 1A A0 CD 1C BE A6 E7 45 8A 7A BA D5 12 - pk_script<br />
A9 D9 EA 1A FB 22 5E 88 AC<br />
<br />
Output 2:<br />
80 FA E9 C7 00 00 00 00 - 33.54 BTC (3354000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E - pk_script<br />
FD A0 B7 8B 4E CC 52 88 AC<br />
<br />
Locktime:<br />
00 00 00 00 - lock time<br />
</pre><br />
<br />
=== block ===<br />
<br />
The '''block''' message is sent in response to a getdata message which requests transaction information from a block hash.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A Unix timestamp recording when this block was created (Currently limited to dates before the year 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated [[Difficulty|difficulty target]] being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| ? || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries<br />
|-<br />
| ? || txns || tx[] || Block transactions, in format of "tx" command<br />
|}<br />
<br />
The SHA256 hash that identifies each block (and which must have a run of 0 bits) is calculated from the first 6 fields of this structure (version, prev_block, merkle_root, timestamp, bits, nonce, and standard SHA256 padding, making two 64-byte chunks in all) and ''not'' from the complete block. To calculate the hash, only two chunks need to be processed by the SHA256 algorithm. Since the ''nonce'' field is in the second chunk, the first chunk stays constant during mining and therefore only the second chunk needs to be processed. However, a Bitcoin hash is the hash of the hash, so two SHA256 rounds are needed for each mining iteration.<br />
See [[Block hashing algorithm]] for details and an example.<br />
<br />
=== headers ===<br />
<br />
The ''headers'' packet returns block headers in response to a ''getheaders'' packet. <br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of block headers<br />
|-<br />
| 81x? || headers || [[Protocol_documentation#Block_Headers|block_header]][] || [[Protocol_documentation#Block_Headers|Block headers]]<br />
|}<br />
<br />
Note that the block headers in this packet include a transaction count (a var_int, so there can be more than 81 bytes per header) as opposed to the block headers that are hashed by miners.<br />
<br />
=== getaddr ===<br />
<br />
The getaddr message sends a request to a node asking for information about known active peers to help with finding potential nodes in the network. The response to receiving this message is to transmit one or more addr messages with one or more peers from a database of known active peers. The typical presumption is that a node is likely to be active if it has been sending a message within the last three hours.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
=== mempool ===<br />
<br />
The mempool message sends a request to a node asking for information about transactions it has verified but which have not yet confirmed. The response to receiving this message is an inv message containing the transaction hashes for all the transactions in the node's mempool.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
It is specified in [https://github.com/bitcoin/bips/blob/master/bip-0035.mediawiki BIP 35]. Since [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 37], if a [[Protocol_documentation#filterload.2C_filteradd.2C_filterclear.2C_merkleblock|bloom filter]] is loaded, only transactions matching the filter are replied.<br />
<br />
=== checkorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== submitorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== reply ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== ping ===<br />
<br />
The ''ping'' message is sent primarily to confirm that the TCP/IP connection is still valid. An error in transmission is presumed to be a closed connection and the address is removed as a current peer.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || random nonce<br />
|}<br />
<br />
=== pong ===<br />
<br />
The ''pong'' message is sent in response to a ''ping'' message. In modern protocol versions, a ''pong'' response is generated using a nonce included in the ping.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || nonce from ping<br />
|}<br />
<br />
<br />
=== reject===<br />
<br />
The ''reject'' message is sent when messages are rejected.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || message || var_str || type of message rejected<br />
|-<br />
| 1 || ccode || char || code relating to rejected message<br />
|-<br />
| 1+ || reason || var_str || text version of reason for rejection<br />
|-<br />
| 0+ || data || char || Optional extra data provided by some errors. Currently, all errors which provide this field fill it with the TXID or block header hash of the object being rejected, so the field is 32 bytes.<br />
|}<br />
<br />
CCodes<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0x01 || REJECT_MALFORMED|| <br />
|-<br />
| 0x10 || REJECT_INVALID ||<br />
|-<br />
| 0x11 || REJECT_OBSOLETE ||<br />
|-<br />
| 0x12 || REJECT_DUPLICATE ||<br />
|-<br />
| 0x40 || REJECT_NONSTANDARD ||<br />
|-<br />
| 0x41 || REJECT_DUST ||<br />
|-<br />
| 0x42 || REJECT_INSUFFICIENTFEE ||<br />
|-<br />
| 0x43 || REJECT_CHECKPOINT ||<br />
|}<br />
<br />
=== filterload, filteradd, filterclear, merkleblock ===<br />
<br />
These messages are related to Bloom filtering of connections and are defined in [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037].<br />
<br />
<br />
The <code>filterload</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || filter || uint8_t[] || The filter itself is simply a bit field of arbitrary byte-aligned size. The maximum size is 36,000 bytes.<br />
|-<br />
| 4 || nHashFuncs || uint32_t || The number of hash functions to use in this filter. The maximum value allowed in this field is 50.<br />
|-<br />
| 4 || nTweak || uint32_t || A random value to add to the seed value in the hash function used by the bloom filter.<br />
|-<br />
| 1 || nFlags || uint8_t || A set of flags that control how matched items are added to the filter.<br />
|}<br />
<br />
See below for a description of the Bloom filter algorithm and how to select nHashFuncs and filter size for a desired false positive rate.<br />
<br />
Upon receiving a <code>filterload</code> command, the remote peer will immediately restrict the broadcast transactions it announces (in inv packets) to transactions matching the filter, where the matching algorithm is specified below. The flags control the update behaviour of the matching algorithm.<br />
<br />
The <code>filteradd</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || data || uint8_t[] || The data element to add to the current filter.<br />
|}<br />
<br />
The data field must be smaller than or equal to 520 bytes in size (the maximum size of any potentially matched object).<br />
<br />
The given data element will be added to the Bloom filter. A filter must have been previously provided using <code>filterload</code>. This command is useful if a new key or script is added to a clients wallet whilst it has connections to the network open, it avoids the need to re-calculate and send an entirely new filter to every peer (though doing so is usually advisable to maintain anonymity).<br />
<br />
The <code>filterclear</code> command has no arguments at all.<br />
<br />
After a filter has been set, nodes don't merely stop announcing non-matching transactions, they can also serve filtered blocks. A filtered block is defined by the <code>merkleblock</code> message and is defined like this:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information, based upon the software version creating this block (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Limited to 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 4 || total_transactions || uint32_t || Number of transactions in the block (including unmatched ones)<br />
|-<br />
| ? || hashes || uint256[] || hashes in depth-first order (including standard varint size prefix)<br />
|-<br />
| ? || flags || byte[] || flag bits, packed per 8 in a byte, least significant bit first (including standard varint size prefix)<br />
|}<br />
<br />
=== alert ===<br />
<br />
An '''alert''' is sent between nodes to send a general notification message throughout the network. If the alert can be confirmed with the signature as having come from the core development group of the Bitcoin software, the message is suggested to be displayed for end-users. Attempts to perform transactions, particularly automated transactions through the client, are suggested to be halted. The text in the Message string should be relayed to log files and any user interfaces.<br />
<br />
Alert format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || payload || uchar[] || Serialized alert payload<br />
|-<br />
| ? || signature || uchar[] || An ECDSA signature of the message<br />
|}<br />
<br />
The developers of Satoshi's client use this public key for signing alerts:<br />
04fc9702847840aaf195de8442ebecedf5b095cdbb9bc716bda9110971b28a49e0ead8564ff0db22209e0374782c093bb899692d524e9d6a6956e7c5ecbcd68284<br />
(hash) 1AGRxqDa5WjUKBwHB9XYEjmkv1ucoUUy1s<br />
<br />
The payload is serialized into a uchar[] to ensure that versions using incompatible alert formats can still relay alerts among one another. The current alert payload format is:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || Version || int32_t || Alert format version<br />
|-<br />
| 8 || RelayUntil || int64_t || The timestamp beyond which nodes should stop relaying this alert<br />
|-<br />
| 8 || Expiration || int64_t || The timestamp beyond which this alert is no longer in effect and should be ignored<br />
|-<br />
| 4 || ID || int32_t || A unique ID number for this alert<br />
|-<br />
| 4 || Cancel || int32_t || All alerts with an ID number less than or equal to this number should be cancelled: deleted and not accepted in the future<br />
|-<br />
| ? || setCancel || set<int32_t> || All alert IDs contained in this set should be cancelled as above<br />
|-<br />
| 4 || MinVer || int32_t || This alert only applies to versions greater than or equal to this version. Other versions should still relay it.<br />
|-<br />
| 4 || MaxVer || int32_t || This alert only applies to versions less than or equal to this version. Other versions should still relay it.<br />
|-<br />
| ? || setSubVer || set<string> || If this set contains any elements, then only nodes that have their subVer contained in this set are affected by the alert. Other versions should still relay it.<br />
|-<br />
| 4 || Priority || int32_t || Relative priority compared to other alerts<br />
|-<br />
| ? || Comment || string || A comment on the alert that is not displayed<br />
|-<br />
| ? || StatusBar || string || The alert message that is displayed to the user<br />
|-<br />
| ? || Reserved || string || Reserved<br />
|}<br />
<br />
Note: '''set<''type''>''' in the table above is a [[#Variable length integer | variable length integer]] followed by the number of fields of the given ''type'' (either int32_t or [[#Variable length string | variable length string]])<br />
<br />
Sample alert (no message header):<br />
73010000003766404f00000000b305434f00000000f2030000f1030000001027000048ee0000<br />
0064000000004653656520626974636f696e2e6f72672f666562323020696620796f75206861<br />
76652074726f75626c6520636f6e6e656374696e672061667465722032302046656272756172<br />
79004730450221008389df45f0703f39ec8c1cc42c13810ffcae14995bb648340219e353b63b<br />
53eb022009ec65e1c1aaeec1fd334c6b684bde2b3f573060d5b70c3a46723326e4e8a4f1<br />
<br />
Version: 1<br />
RelayUntil: 1329620535<br />
Expiration: 1329792435<br />
ID: 1010<br />
Cancel: 1009<br />
setCancel: <empty><br />
MinVer: 10000<br />
MaxVer: 61000<br />
setSubVer: <empty><br />
Priority: 100<br />
Comment: <empty><br />
StatusBar: "See bitcoin.org/feb20 if you have trouble connecting after 20 February"<br />
Reserved: <empty><br />
<br />
=== sendheaders ===<br />
<br />
Request for Direct headers announcement. <br />
<br />
Upon receipt of this message, the node is be permitted, but not required, to announce new blocks by '''headers''' command (instead of '''inv''' command).<br />
<br />
This message is supported by the protocol version >= 70012 or Bitcoin Core version >= 0.12.0.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0130.mediawiki BIP 130] for more information.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
<br />
=== feefilter ===<br />
<br />
The payload is always 8 bytes long and it encodes 64 bit integer value (LSB / little endian).<br />
The value represents a minimal fee, expressed in satoshis (units of 0.00000001 BTC) per kilobyte.<br />
<br />
Upon receipt of a "feefilter" message, the node will be permitted, but not required, to filter transaction invs for transactions that fall below the feerate provided in the feefilter message interpreted as satoshis per kilobyte.<br />
<br />
The fee filter is additive with a bloom filter for transactions so if an SPV client were to load a bloom filter and send a feefilter message, transactions would only be relayed if they passed both filters.<br />
<br />
Inv's generated from a mempool message are also subject to a fee filter if it exists.<br />
<br />
Feature discovery is enabled by checking protocol version >= 70013<br />
<br />
== Scripting ==<br />
<br />
See [[script]].<br />
<br />
==See Also==<br />
<br />
* [[Network]]<br />
* [[Protocol rules]]<br />
* [[Hardfork Wishlist]]<br />
* [https://bitcoin.org/en/developer-documentation Developer Documentation on bitcoin.org]<br />
* Bitcoin dissectors for Wireshark: https://github.com/lbotsch/wireshark-bitcoin https://github.com/op-sig/bitcoin-wireshark-dissector<br />
<br />
==References==<br />
<references /><br />
<br />
[[zh-cn:协议说明]]<br />
[[Category:Technical]]<br />
[[Category:Developer]]<br />
<br />
{{Bitcoin Core documentation}}</div>Tonikthttps://en.bitcoin.it/w/index.php?title=Gocoin&diff=61235Gocoin2016-06-28T12:39:50Z<p>Tonikt: stealth addresses are no longer supported, after version 1.6.4</p>
<hr />
<div>An open-source Bitcoin solution written in Go language (golang).<br />
It can be built for every platform that has a working Go compiler.<br />
It uses a proprietary license, though is free to use for non-commercial purposes.<br />
<br />
==Architecture==<br />
<br />
Gocoin's architecture is quite different from the reference implementation (of the Satoshi client).<br />
<br />
===Libraries===<br />
<br />
====btc / chain / script ====<br />
The core of the software is a library that essentially provides the blockchain protocol parser. That includes script parsing, ECDSA signature verification, but also things like address encoding, parsing of canonical signatures or extracting hashes that need to be signed for specific inputs of a given transaction.<br />
<br />
It is a relatively big library, that contains many useful bitcoin function.<br />
<br />
Inside the package, there is also a blocks persistent storage database (blockdb.go) - it is just a simple plain storage (that can only grow), with an index. It uses snappy compression, allowing to save about 30% of the disk space.<br />
<br />
====qdb====<br />
The core library interfaces directly with a UTXO database backed.<br />
For this purpose Gocoin uses its own database engine, that has been designed to deal with the specific characteristics of bitcoin's UTXO database. <br />
<br />
====secp256k1====<br />
To speed up the Elliptic Curve operations [https://github.com/bitcoin/secp256k1 the secp256k1 library by sipa] has been ported to Go.<br />
<br />
===Online client===<br />
The online client is a kind of a server software (or a peer-to-peer node) that is meant to be running all the time.<br />
<br />
It handles the network related communication, feeds the core lib with new incoming blockchain data, monitors balances on the wallets' addresses, manages transaction memory pool and the peers database. It also provides an interactive user interface.<br />
<br />
===Offline wallet===<br />
The wallet application is responsible for creating private keys (from a seed password) and for signing transactions with them.<br />
It can also sign text messages with private keys and decode raw transactions.<br />
<br />
Unlike the client, the wallet is not an app that is meant te be running continuously. <br />
A user runs it with the requested task - the wallet does the job and exits (back to the command prompt).<br />
<br />
===Blockchain downloader===<br />
For optimized initial blockchain download, Gocoin has a dedicated application called '''downloader'''.<br />
<br />
Among other optimizations, the downloader allows a user to skip verification of all the blocks up to a certain one that he defines as trusted. This can speed up the bootstrap process significantly (e.g. from days to hours).<br />
<br />
After it finishes downloading of all the blocks, it will exit automatically. In that moment the client should be started and it will keep up with all the new blocks, that will appear in the network.<br />
<br />
===Other tools===<br />
There is also a set of more and less useful tools (''github.com/piotrnar/gocoin/tools'') that are an integral part of the Gocoin bitcoin software.<br />
<br />
For instance '''btcversig''' can verify a validity of a bitcoin signature - it is the substitute of the reference client's '''verifymessage''' RPC-API.<br />
<br />
The tool '''type2determ''' can, at the other hand, calculate Type-2 deterministic addresses, without a need to access the wallet (the private keys).<br />
<br />
<br />
==Features==<br />
<br />
Gocoin has a several unique features, that distinguish it from the original bitcoin client.<br />
===Node / Client===<br />
* All the unspent outputs are kept in memory, which makes switching between different wallets, as well as checking a balance of any address, relatively fast (few seconds max).<br />
* Allows a user to limit the upload and download network bandwidth used by the client.<br />
* Can be monitored and controlled through a web interface (from a web browser).<br />
* Works with its own implementation of a cold storage wallet.<br />
* Web interface allows a user to create raw transactions from specific inputs ([[Coin Control]]), as well as multisig transactions ([[P2SH]])<br />
* The blocks are stored on the disk in a compressed form (using [https://code.google.com/p/snappy/ snappy] compression) which saves 20-30% of space.<br />
* Up till version '''1.6.4''' it supported monitoring and fetching balance of own stealth addresses (the ones implemented in [[Dark Wallet]])<br />
<br />
===Wallet===<br />
* For security reasons, it is supposed to be used with a PC that has never been (and will never be) connected to a network.<br />
* The wallet is deterministic and a seed-password based. As long as you can remember the password, there is no need for any backups.<br />
* Additionally it can import private keys from an existing bitcoin wallet (must be in [[Private key#Base 58 Wallet Import format | Base 58 Wallet Import format]] format).<br />
* Has very low hardware requirements. Can be run on i.e. Raspberry Pi<br />
* Can generate [https://bitcointalk.org/index.php?topic=19137.0 Type-2] deterministic keys/addresses<br />
* Supports (partial) signing of [[P2SH]] multisig transactions (the ones that use [[Script#Crypto | OP_CHECKMULTISIG opcode]]).<br />
* Supports spending to stealth addresses as implemented in Dark Wallet<br />
<br />
===Node-less mode===<br />
It is possible to use Gocoin's wallet, without a need to have a running client node, which may come handy since the node requires quite a decent hardware and the block chain takes a lot of time for the initial download.<br />
<br />
In such a case the required balance files are fetched with a tool called '''balio''', from a popular block explorer '''blockr.io'''<br />
<br />
''Note: using this tool you will not be able to monitor balance on your stealth addresses.''<br />
<br />
==Requirements==<br />
===Client===<br />
Requires 64-bit platform and at least 8GB of system memory.<br />
<br />
The file system that stores the blockchain data must be able to handle files larger than 4GB.<br />
<br />
===Wallet===<br />
The wallet app has very little hardware requirements. As long as you can build it for a specific architecture, it should work there.<br />
<br />
Gocoin wallet has been even used on Raspberry Pi model A.<br />
<br />
For security reasons it is strongly recommended to run the wallet on an encrypted file system, with an encrypted swap file.<br />
<br />
==Limitations==<br />
* No GUI, though the online node has web interface which acts like a GUI<br />
* No IPv6<br />
* No UPnP<br />
* No support for non-confirmed transactions (they are invisible in the balance)<br />
* No support for [[Protocol_specification#filterload, filteradd, filterclear, merkleblock | bloom filters]] protocol ([[BIP 0037]]) and the [[Protocol_specification#mempool | mempool]] command<br />
* No routing of [[Protocol_specification#alert | alert]] messages<br />
* No support for multisig stealth addresses (yet)<br />
<br />
==History==<br />
<br />
Gocoin was written by a single person for a private purposes.<br />
<br />
The software's first public release was announced in May 2013 on Bitcointalk forum.<ref>https://bitcointalk.org/index.php?topic=199306.0</ref><br />
Ever since then, the software has been actively maintained and further developed, being armed with new features, further optimized and cleaned up from issues.<br />
<br />
It happened twice that the client wasn't able to catch up with the blockchain, because of the implementation difference of the chain parsing protocol that was causing it to reject a block (transaction) that the reference implementation would accept. In both cases the issue was fixed within single days. The fist case happened in July 2013 and the fix was introduced in version 0.5.7. The second time was in March 2014 - the fix came with release 0.9.3.<br />
<br />
==External Links==<br />
<br />
* [http://gocoin.pl Homepage]<br />
* [https://github.com/piotrnar/gocoin Github repo]<br />
* [https://bitcointalk.org/index.php?topic=199306.0 Bitcointalk forum topic]<br />
<br />
==References==<br />
<references /><br />
<br />
[[Category:Software]]<br />
[[Category:Clients]]<br />
[[Category:Open Source]]<br />
[[Category:Wallets]]<br />
[[Category:Google Go]]</div>Tonikthttps://en.bitcoin.it/w/index.php?title=Gocoin&diff=61234Gocoin2016-06-28T12:38:42Z<p>Tonikt: Client node requires 8GB of RAM now</p>
<hr />
<div>An open-source Bitcoin solution written in Go language (golang).<br />
It can be built for every platform that has a working Go compiler.<br />
It uses a proprietary license, though is free to use for non-commercial purposes.<br />
<br />
==Architecture==<br />
<br />
Gocoin's architecture is quite different from the reference implementation (of the Satoshi client).<br />
<br />
===Libraries===<br />
<br />
====btc / chain / script ====<br />
The core of the software is a library that essentially provides the blockchain protocol parser. That includes script parsing, ECDSA signature verification, but also things like address encoding, parsing of canonical signatures or extracting hashes that need to be signed for specific inputs of a given transaction.<br />
<br />
It is a relatively big library, that contains many useful bitcoin function.<br />
<br />
Inside the package, there is also a blocks persistent storage database (blockdb.go) - it is just a simple plain storage (that can only grow), with an index. It uses snappy compression, allowing to save about 30% of the disk space.<br />
<br />
====qdb====<br />
The core library interfaces directly with a UTXO database backed.<br />
For this purpose Gocoin uses its own database engine, that has been designed to deal with the specific characteristics of bitcoin's UTXO database. <br />
<br />
====secp256k1====<br />
To speed up the Elliptic Curve operations [https://github.com/bitcoin/secp256k1 the secp256k1 library by sipa] has been ported to Go.<br />
<br />
===Online client===<br />
The online client is a kind of a server software (or a peer-to-peer node) that is meant to be running all the time.<br />
<br />
It handles the network related communication, feeds the core lib with new incoming blockchain data, monitors balances on the wallets' addresses, manages transaction memory pool and the peers database. It also provides an interactive user interface.<br />
<br />
===Offline wallet===<br />
The wallet application is responsible for creating private keys (from a seed password) and for signing transactions with them.<br />
It can also sign text messages with private keys and decode raw transactions.<br />
<br />
Unlike the client, the wallet is not an app that is meant te be running continuously. <br />
A user runs it with the requested task - the wallet does the job and exits (back to the command prompt).<br />
<br />
===Blockchain downloader===<br />
For optimized initial blockchain download, Gocoin has a dedicated application called '''downloader'''.<br />
<br />
Among other optimizations, the downloader allows a user to skip verification of all the blocks up to a certain one that he defines as trusted. This can speed up the bootstrap process significantly (e.g. from days to hours).<br />
<br />
After it finishes downloading of all the blocks, it will exit automatically. In that moment the client should be started and it will keep up with all the new blocks, that will appear in the network.<br />
<br />
===Other tools===<br />
There is also a set of more and less useful tools (''github.com/piotrnar/gocoin/tools'') that are an integral part of the Gocoin bitcoin software.<br />
<br />
For instance '''btcversig''' can verify a validity of a bitcoin signature - it is the substitute of the reference client's '''verifymessage''' RPC-API.<br />
<br />
The tool '''type2determ''' can, at the other hand, calculate Type-2 deterministic addresses, without a need to access the wallet (the private keys).<br />
<br />
<br />
==Features==<br />
<br />
Gocoin has a several unique features, that distinguish it from the original bitcoin client.<br />
===Node / Client===<br />
* All the unspent outputs are kept in memory, which makes switching between different wallets, as well as checking a balance of any address, relatively fast (few seconds max).<br />
* Allows a user to limit the upload and download network bandwidth used by the client.<br />
* Can be monitored and controlled through a web interface (from a web browser).<br />
* Works with its own implementation of a cold storage wallet.<br />
* Web interface allows a user to create raw transactions from specific inputs ([[Coin Control]]), as well as multisig transactions ([[P2SH]])<br />
* The blocks are stored on the disk in a compressed form (using [https://code.google.com/p/snappy/ snappy] compression) which saves 20-30% of space.<br />
* Supports monitoring and fetching balance of own stealth addresses (the ones implemented in [[Dark Wallet]])<br />
<br />
===Wallet===<br />
* For security reasons, it is supposed to be used with a PC that has never been (and will never be) connected to a network.<br />
* The wallet is deterministic and a seed-password based. As long as you can remember the password, there is no need for any backups.<br />
* Additionally it can import private keys from an existing bitcoin wallet (must be in [[Private key#Base 58 Wallet Import format | Base 58 Wallet Import format]] format).<br />
* Has very low hardware requirements. Can be run on i.e. Raspberry Pi<br />
* Can generate [https://bitcointalk.org/index.php?topic=19137.0 Type-2] deterministic keys/addresses<br />
* Supports (partial) signing of [[P2SH]] multisig transactions (the ones that use [[Script#Crypto | OP_CHECKMULTISIG opcode]]).<br />
* Supports spending to stealth addresses as implemented in Dark Wallet<br />
<br />
===Node-less mode===<br />
It is possible to use Gocoin's wallet, without a need to have a running client node, which may come handy since the node requires quite a decent hardware and the block chain takes a lot of time for the initial download.<br />
<br />
In such a case the required balance files are fetched with a tool called '''balio''', from a popular block explorer '''blockr.io'''<br />
<br />
''Note: using this tool you will not be able to monitor balance on your stealth addresses.''<br />
<br />
==Requirements==<br />
===Client===<br />
Requires 64-bit platform and at least 8GB of system memory.<br />
<br />
The file system that stores the blockchain data must be able to handle files larger than 4GB.<br />
<br />
===Wallet===<br />
The wallet app has very little hardware requirements. As long as you can build it for a specific architecture, it should work there.<br />
<br />
Gocoin wallet has been even used on Raspberry Pi model A.<br />
<br />
For security reasons it is strongly recommended to run the wallet on an encrypted file system, with an encrypted swap file.<br />
<br />
==Limitations==<br />
* No GUI, though the online node has web interface which acts like a GUI<br />
* No IPv6<br />
* No UPnP<br />
* No support for non-confirmed transactions (they are invisible in the balance)<br />
* No support for [[Protocol_specification#filterload, filteradd, filterclear, merkleblock | bloom filters]] protocol ([[BIP 0037]]) and the [[Protocol_specification#mempool | mempool]] command<br />
* No routing of [[Protocol_specification#alert | alert]] messages<br />
* No support for multisig stealth addresses (yet)<br />
<br />
==History==<br />
<br />
Gocoin was written by a single person for a private purposes.<br />
<br />
The software's first public release was announced in May 2013 on Bitcointalk forum.<ref>https://bitcointalk.org/index.php?topic=199306.0</ref><br />
Ever since then, the software has been actively maintained and further developed, being armed with new features, further optimized and cleaned up from issues.<br />
<br />
It happened twice that the client wasn't able to catch up with the blockchain, because of the implementation difference of the chain parsing protocol that was causing it to reject a block (transaction) that the reference implementation would accept. In both cases the issue was fixed within single days. The fist case happened in July 2013 and the fix was introduced in version 0.5.7. The second time was in March 2014 - the fix came with release 0.9.3.<br />
<br />
==External Links==<br />
<br />
* [http://gocoin.pl Homepage]<br />
* [https://github.com/piotrnar/gocoin Github repo]<br />
* [https://bitcointalk.org/index.php?topic=199306.0 Bitcointalk forum topic]<br />
<br />
==References==<br />
<references /><br />
<br />
[[Category:Software]]<br />
[[Category:Clients]]<br />
[[Category:Open Source]]<br />
[[Category:Wallets]]<br />
[[Category:Google Go]]</div>Tonikthttps://en.bitcoin.it/w/index.php?title=Gocoin&diff=60694Gocoin2016-03-30T16:22:32Z<p>Tonikt: /* Limitations */</p>
<hr />
<div>An open-source Bitcoin solution written in Go language (golang).<br />
It can be built for every platform that has a working Go compiler.<br />
It uses a proprietary license, though is free to use for non-commercial purposes.<br />
<br />
==Architecture==<br />
<br />
Gocoin's architecture is quite different from the reference implementation (of the Satoshi client).<br />
<br />
===Libraries===<br />
<br />
====btc / chain / script ====<br />
The core of the software is a library that essentially provides the blockchain protocol parser. That includes script parsing, ECDSA signature verification, but also things like address encoding, parsing of canonical signatures or extracting hashes that need to be signed for specific inputs of a given transaction.<br />
<br />
It is a relatively big library, that contains many useful bitcoin function.<br />
<br />
Inside the package, there is also a blocks persistent storage database (blockdb.go) - it is just a simple plain storage (that can only grow), with an index. It uses snappy compression, allowing to save about 30% of the disk space.<br />
<br />
====qdb====<br />
The core library interfaces directly with a UTXO database backed.<br />
For this purpose Gocoin uses its own database engine, that has been designed to deal with the specific characteristics of bitcoin's UTXO database. <br />
<br />
====secp256k1====<br />
To speed up the Elliptic Curve operations [https://github.com/bitcoin/secp256k1 the secp256k1 library by sipa] has been ported to Go.<br />
<br />
===Online client===<br />
The online client is a kind of a server software (or a peer-to-peer node) that is meant to be running all the time.<br />
<br />
It handles the network related communication, feeds the core lib with new incoming blockchain data, monitors balances on the wallets' addresses, manages transaction memory pool and the peers database. It also provides an interactive user interface.<br />
<br />
===Offline wallet===<br />
The wallet application is responsible for creating private keys (from a seed password) and for signing transactions with them.<br />
It can also sign text messages with private keys and decode raw transactions.<br />
<br />
Unlike the client, the wallet is not an app that is meant te be running continuously. <br />
A user runs it with the requested task - the wallet does the job and exits (back to the command prompt).<br />
<br />
===Blockchain downloader===<br />
For optimized initial blockchain download, Gocoin has a dedicated application called '''downloader'''.<br />
<br />
Among other optimizations, the downloader allows a user to skip verification of all the blocks up to a certain one that he defines as trusted. This can speed up the bootstrap process significantly (e.g. from days to hours).<br />
<br />
After it finishes downloading of all the blocks, it will exit automatically. In that moment the client should be started and it will keep up with all the new blocks, that will appear in the network.<br />
<br />
===Other tools===<br />
There is also a set of more and less useful tools (''github.com/piotrnar/gocoin/tools'') that are an integral part of the Gocoin bitcoin software.<br />
<br />
For instance '''btcversig''' can verify a validity of a bitcoin signature - it is the substitute of the reference client's '''verifymessage''' RPC-API.<br />
<br />
The tool '''type2determ''' can, at the other hand, calculate Type-2 deterministic addresses, without a need to access the wallet (the private keys).<br />
<br />
<br />
==Features==<br />
<br />
Gocoin has a several unique features, that distinguish it from the original bitcoin client.<br />
===Node / Client===<br />
* All the unspent outputs are kept in memory, which makes switching between different wallets, as well as checking a balance of any address, relatively fast (few seconds max).<br />
* Allows a user to limit the upload and download network bandwidth used by the client.<br />
* Can be monitored and controlled through a web interface (from a web browser).<br />
* Works with its own implementation of a cold storage wallet.<br />
* Web interface allows a user to create raw transactions from specific inputs ([[Coin Control]]), as well as multisig transactions ([[P2SH]])<br />
* The blocks are stored on the disk in a compressed form (using [https://code.google.com/p/snappy/ snappy] compression) which saves 20-30% of space.<br />
* Supports monitoring and fetching balance of own stealth addresses (the ones implemented in Dark Wallet)<br />
<br />
===Wallet===<br />
* For security reasons, it is supposed to be used with a PC that has never been (and will never be) connected to a network.<br />
* The wallet is deterministic and a seed-password based. As long as you can remember the password, there is no need for any backups.<br />
* Additionally it can import private keys from an existing bitcoin wallet (must be in [[Private key#Base 58 Wallet Import format | Base 58 Wallet Import format]] format).<br />
* Has very low hardware requirements. Can be run on i.e. Raspberry Pi<br />
* Can generate [https://bitcointalk.org/index.php?topic=19137.0 Type-2] deterministic keys/addresses<br />
* Supports (partial) signing of [[P2SH]] multisig transactions (the ones that use [[Script#Crypto | OP_CHECKMULTISIG opcode]]).<br />
* Supports spending to stealth addresses as implemented in Dark Wallet<br />
<br />
===Node-less mode===<br />
It is possible to use Gocoin's wallet, without a need to have a running client node, which may come handy since the node requires quite a decent hardware and the block chain takes a lot of time for the initial download.<br />
<br />
In such a case the required balance files are fetched with a tool called '''balio''', from a popular block explorer '''blockr.io'''<br />
<br />
''Note: using this tool you will not be able to monitor balance on your stealth addresses.''<br />
<br />
==Requirements==<br />
===Client===<br />
Requires 64-bit platform and at least 4GB of system memory.<br />
<br />
The file system that stores the blockchain data must be able to handle files larger than 4GB.<br />
<br />
===Wallet===<br />
The wallet app has very little hardware requirements. As long as you can build it for a specific architecture, it should work there.<br />
<br />
Gocoin wallet has been even used on Raspberry Pi model A.<br />
<br />
For security reasons it is strongly recommended to run the wallet on an encrypted file system, with an encrypted swap file.<br />
<br />
==Limitations==<br />
* No GUI, though the online node has web interface which acts like a GUI<br />
* No IPv6<br />
* No UPnP<br />
* No support for non-confirmed transactions (they are invisible in the balance)<br />
* No support for [[Protocol_specification#filterload, filteradd, filterclear, merkleblock | bloom filters]] protocol ([[BIP 0037]]) and the [[Protocol_specification#mempool | mempool]] command<br />
* No routing of [[Protocol_specification#alert | alert]] messages<br />
* No support for multisig stealth addresses (yet)<br />
<br />
==History==<br />
<br />
Gocoin was written by a single person for a private purposes.<br />
<br />
The software's first public release was announced in May 2013 on Bitcointalk forum.<ref>https://bitcointalk.org/index.php?topic=199306.0</ref><br />
Ever since then, the software has been actively maintained and further developed, being armed with new features, further optimized and cleaned up from issues.<br />
<br />
It happened twice that the client wasn't able to catch up with the blockchain, because of the implementation difference of the chain parsing protocol that was causing it to reject a block (transaction) that the reference implementation would accept. In both cases the issue was fixed within single days. The fist case happened in July 2013 and the fix was introduced in version 0.5.7. The second time was in March 2014 - the fix came with release 0.9.3.<br />
<br />
==External Links==<br />
<br />
* [http://gocoin.pl Homepage]<br />
* [https://github.com/piotrnar/gocoin Github repo]<br />
* [https://bitcointalk.org/index.php?topic=199306.0 Bitcointalk forum topic]<br />
<br />
==References==<br />
<references /><br />
<br />
[[Category:Software]]<br />
[[Category:Clients]]<br />
[[Category:Open Source]]<br />
[[Category:Wallets]]<br />
[[Category:Google Go]]</div>Tonikthttps://en.bitcoin.it/w/index.php?title=Protocol_documentation&diff=60482Protocol documentation2016-02-24T14:01:20Z<p>Tonikt: /* sendheaders */</p>
<hr />
<div>This page ''describes'' the behavior of the [[Original Bitcoin client|reference client]]. The Bitcoin protocol is specified by the behavior of the reference client, not by this page. In particular, while this page is quite complete in describing the network protocol, it does not attempt to list all of the rules for block or transaction validity.<br />
<br />
Type names used in this documentation are from the C99 standard.<br />
<br />
For protocol used in mining, see [[getblocktemplate]].<br />
<br />
==Common standards==<br />
<br />
=== Hashes ===<br />
<br />
Usually, when a hash is computed within bitcoin, it is computed twice. Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-256] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when a shorter hash is desirable (for example when creating a bitcoin address).<br />
<br />
Example of double-SHA-256 encoding of string "hello":<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round of sha-256)<br />
9595c9df90075148eb06860365df33584b75bff782a510c6cd4883a419833d50 (second round of sha-256)<br />
<br />
For bitcoin addresses (RIPEMD-160) this would give:<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round is sha-256)<br />
b6a9c8c230722b7c748331a8b450f05566dc7d0f (with ripemd-160)<br />
<br />
=== Merkle Trees ===<br />
<br />
Merkle trees are binary trees of hashes. Merkle trees in bitcoin use a '''double''' SHA-256, the SHA-256 hash of the SHA-256 hash of something.<br />
<br />
If, when forming a row in the tree (other than the root of the tree), it would have an odd number of elements, the final double-hash is duplicated to ensure that the row has an even number of hashes.<br />
<br />
First form the bottom row of the tree with the ordered double-SHA-256 hashes of the byte streams of the transactions in the block.<br />
<br />
Then the row above it consists of half that number of hashes. Each entry is the double-SHA-256 of the 64-byte concatenation of the corresponding two hashes below it in the tree.<br />
<br />
This procedure repeats recursively until we reach a row consisting of just a single double-hash. This is the '''Merkle root''' of the tree.<br />
<br />
For example, imagine a block with three transactions ''a'', ''b'' and ''c''. The Merkle tree is: <br />
<br />
d1 = dhash(a)<br />
d2 = dhash(b)<br />
d3 = dhash(c)<br />
d4 = dhash(c) # a, b, c are 3. that's an odd number, so we take the c twice<br />
<br />
d5 = dhash(d1 concat d2)<br />
d6 = dhash(d3 concat d4)<br />
<br />
d7 = dhash(d5 concat d6)<br />
<br />
where<br />
<br />
dhash(a) = sha256(sha256(a))<br />
<br />
''d7'' is the Merkle root of the 3 transactions in this block.<br />
<br />
Note: Hashes in Merkle Tree displayed in the [[Block Explorer]] are of little-endian notation. For some implementations and [http://www.fileformat.info/tool/hash.htm calculations], the bits need to be reversed before they are hashed, and again after the hashing operation.<br />
<br />
=== Signatures ===<br />
<br />
Bitcoin uses [http://en.wikipedia.org/wiki/Elliptic_curve_cryptography Elliptic Curve] [http://en.wikipedia.org/wiki/Digital_Signature_Algorithm Digital Signature Algorithm] ([http://en.wikipedia.org/wiki/Elliptic_Curve_DSA ECDSA]) to sign transactions. <br />
<br />
For [[ECDSA]] the secp256k1 curve from http://www.secg.org/collateral/sec2_final.pdf is used.<br />
<br />
Public keys (in scripts) are given as 04 <x> <y> where ''x'' and ''y'' are 32 byte big-endian integers representing the coordinates of a point on the curve or in compressed form given as <sign> <x> where <sign> is 0x02 if ''y'' is even and 0x03 if ''y'' is odd.<br />
<br />
Signatures use [http://en.wikipedia.org/wiki/Distinguished_Encoding_Rules DER encoding] to pack the ''r'' and ''s'' components into a single byte stream (this is also what OpenSSL produces by default).<br />
<br />
=== Transaction Verification ===<br />
Transactions are cryptographically signed records that reassign ownership of Bitcoins to new addresses. Transactions have ''inputs'' - records which reference the funds from other previous transactions - and ''outputs'' - records which determine the new owner of the transferred Bitcoins, and which will be referenced as inputs in future transactions as those funds are respent.<br />
<br />
Each ''input'' must have a cryptographic digital signature that unlocks the funds from the prior transaction. Only the person possessing the appropriate [[private key]] is able to create a satisfactory signature; this in effect ensures that funds can only be spent by their owners.<br />
<br />
Each ''output'' determines which Bitcoin address (or other criteria, see [[Script]]) is the recipient of the funds.<br />
<br />
In a transaction, the sum of all inputs must be equal to or greater than the sum of all outputs. If the inputs exceed the outputs, the difference is considered a [[transaction fee]], and is redeemable by whoever first includes the transaction into the block chain.<br />
<br />
A special kind of transaction, called a [[coinbase transaction]], has no inputs. It is created by [[miners]], and there is one coinbase transaction per block. Because each block comes with a reward of newly created Bitcoins (e.g. 50 BTC for the first 210,000 blocks), the first transaction of a block is, with few exceptions, the transaction that grants those coins to their recipient (the miner). In addition to the newly created Bitcoins, the coinbase transaction is also used for assigning the recipient of any transaction fees that were paid within the other transactions being included in the same block. The coinbase transaction can assign the entire reward to a single Bitcoin address, or split it in portions among multiple addresses, just like any other transaction. Coinbase transactions always contain outputs totalling the sum of the block reward plus all transaction fees collected from the other transactions in the same block.<br />
<br />
The [[coinbase transaction]] in block zero cannot be spent. This is due to a quirk of the reference client implementation that would open the potential for a block chain fork if some nodes accepted the spend and others did not<ref>[http://bitcointalk.org/index.php?topic=119645.msg1288552#msg1288552 Block 0 Network Fork]</ref>.<br />
<br />
Most Bitcoin outputs encumber the newly transferred coins with a single ECDSA private key. The actual record saved with inputs and outputs isn't necessarily a key, but a ''script''. Bitcoin uses an interpreted scripting system to determine whether an output's criteria have been satisfied, with which more complex operations are possible, such as outputs that require two ECDSA signatures, or two-of-three-signature schemes. An output that references a single Bitcoin address is a ''typical'' output; an output actually contains this information in the form of a script that requires a single ECDSA signature (see [[OP_CHECKSIG]]). The output script specifies what must be provided to unlock the funds later, and when the time comes in the future to spend the transaction in another input, that input must provide all of the thing(s) that satisfy the requirements defined by the original output script.<br />
<br />
=== Addresses ===<br />
<br />
A bitcoin address is in fact the hash of a ECDSA public key, computed this way:<br />
<br />
Version = 1 byte of 0 (zero); on the test network, this is 1 byte of 111<br />
Key hash = Version concatenated with RIPEMD-160(SHA-256(public key))<br />
Checksum = 1st 4 bytes of SHA-256(SHA-256(Key hash))<br />
Bitcoin Address = Base58Encode(Key hash concatenated with Checksum)<br />
<br />
The Base58 encoding used is home made, and has some differences. Especially, leading zeroes are kept as single zeroes when conversion happens.<br />
<br />
== Common structures ==<br />
<br />
Almost all integers are encoded in little endian. Only IP or port number are encoded big endian.<br />
<br />
=== Message structure ===<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown<br />
|-<br />
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| 4 || length || uint32_t || Length of payload in number of bytes<br />
|-<br />
| 4 || checksum || uint32_t || First 4 bytes of sha256(sha256(payload))<br />
|-<br />
| ? || payload || uchar[] || The actual data<br />
|}<br />
<br />
<br />
Known magic values:<br />
<br />
{|class="wikitable"<br />
! Network !! Magic value !! Sent over wire as<br />
|-<br />
| main || 0xD9B4BEF9 || F9 BE B4 D9<br />
|-<br />
| testnet || 0xDAB5BFFA || FA BF B5 DA<br />
|-<br />
| testnet3 || 0x0709110B || 0B 11 09 07<br />
|-<br />
| namecoin || 0xFEB4BEF9 || F9 BE B4 FE<br />
|}<br />
<br />
=== Variable length integer ===<br />
<br />
Integer can be encoded depending on the represented value to save space.<br />
Variable length integers always precede an array/vector of a type of data that may vary in length.<br />
Longer numbers are encoded in little endian.<br />
<br />
{|class="wikitable"<br />
! Value !! Storage length !! Format<br />
|-<br />
| < 0xFD || 1 || uint8_t<br />
|-<br />
| <= 0xFFFF || 3 || 0xFD followed by the length as uint16_t<br />
|-<br />
| <= 0xFFFF FFFF || 5 || 0xFE followed by the length as uint32_t<br />
|-<br />
| - || 9 || 0xFF followed by the length as uint64_t<br />
|}<br />
<br />
If you're reading the Satoshi client code (BitcoinQT) it refers to this encoding as a "CompactSize". Modern BitcoinQT also has the CVarInt class which implements an even more compact integer for the purpose of local storage (which is incompatible with "CompactSize" described here). CVarInt is not a part of the protocol.<br />
<br />
=== Variable length string ===<br />
<br />
Variable length string can be stored using a variable length integer followed by the string itself.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the string<br />
|-<br />
| ? || string || char[] || The string itself (can be empty)<br />
|}<br />
<br />
=== Network address ===<br />
<br />
When a network address is needed somewhere, this structure is used. Network addresses are not prefixed with a timestamp in the version message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || time || uint32 || the Time (version >= 31402). '''Not present in version message.'''<br />
|-<br />
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]<br />
|-<br />
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The original client only supported IPv4 and only read the last 4 bytes to get the IPv4 address. However, the IPv4 address is written into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]<br />
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).<br />
|-<br />
| 2 || port || uint16_t || port number, network byte order<br />
|}<br />
<br />
Hexdump example of Network address structure<br />
<br />
<pre><br />
0000 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0010 00 00 FF FF 0A 00 00 01 20 8D ........ .<br />
<br />
Network address:<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK: see services listed under version command)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv6: ::ffff:a00:1 or IPv4: 10.0.0.1<br />
20 8D - Port 8333<br />
</pre><br />
<br />
=== Inventory Vectors ===<br />
<br />
Inventory vectors are used for notifying other nodes about objects they have or data which is being requested.<br />
<br />
Inventory vectors consist of the following data format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || type || uint32_t || Identifies the object type linked to this inventory<br />
|-<br />
| 32 || hash || char[32] || Hash of the object<br />
|}<br />
<br />
<br />
The object type is currently defined as one of the following possibilities:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0 || ERROR || Any data of with this number may be ignored<br />
|-<br />
| 1 || MSG_TX || Hash is related to a transaction<br />
|-<br />
| 2 || MSG_BLOCK || Hash is related to a data block<br />
|-<br />
| 3 || MSG_FILTERED_BLOCK || Hash of a block header; identical to MSG_BLOCK. When used in a getdata message, this indicates the reply should be a merkleblock message rather than a block message; this only works if a bloom filter has been set.<br />
|}<br />
<br />
Other Data Type values are considered reserved for future implementations.<br />
<br />
=== Block Headers ===<br />
<br />
Block headers are sent in a headers packet in response to a getheaders message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Will overflow in 2106<ref>https://en.wikipedia.org/wiki/Unix_time#Notable_events_in_Unix_time</ref>)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 1 || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries, this value is always 0<br />
|}<br />
<br />
cf. [[Block hashing algorithm]]<br />
<br />
== Message types ==<br />
<br />
=== version ===<br />
<br />
When a node creates an outgoing connection, it will immediately [[Version Handshake|advertise]] its version. The remote node will respond with its version. No further communication is possible until both peers have exchanged their version.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Identifies protocol version being used by the node<br />
|-<br />
| 8 || services || uint64_t || bitfield of features to be enabled for this connection<br />
|-<br />
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds<br />
|-<br />
| 26 || addr_recv || [[#Network address|net_addr]] || The network address of the node receiving this message<br />
|-<br />
|colspan="4"| Fields below require version ≥ 106<br />
|-<br />
| 26 || addr_from || [[#Network address|net_addr]] || The network address of the node emitting this message<br />
|-<br />
| 8 || nonce || uint64_t || Node random nonce, randomly generated every time a version packet is sent. This nonce is used to detect connections to self.<br />
|-<br />
| ? || user_agent || [[#Variable length string|var_str]] || [https://github.com/bitcoin/bips/blob/master/bip-0014.mediawiki User Agent] (0x00 if string is 0 bytes long)<br />
|-<br />
| 4 || start_height || int32_t || The last block received by the emitting node<br />
|-<br />
|colspan="4"| Fields below require version ≥ 70001<br />
|-<br />
| 1 || relay || bool || Whether the remote peer should announce relayed transactions or not, see [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037]<br />
|}<br />
<br />
A "verack" packet shall be sent if the version packet was accepted.<br />
<br />
The following services are currently assigned:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 1 || NODE_NETWORK || This node can be asked for full blocks instead of just headers.<br />
|}<br />
<br />
Hexdump example of version message (OBSOLETE EXAMPLE: This example lacks a checksum and user-agent):<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....<br />
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........<br />
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............<br />
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................<br />
0040 20 8D 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,<br />
0060 3A B4 57 13 00 55 81 01 00 :.W..U...<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
55 00 00 00 - Payload is 85 bytes long<br />
- No checksum in version message until 20 February 2012. See https://bitcointalk.org/index.php?topic=55852.0<br />
Version message:<br />
9C 7C 00 00 - 31900 (version 0.3.19)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
E6 15 10 4D 00 00 00 00 - Mon Dec 20 21:50:14 EST 2010<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 20 8D - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D - Sender address info - see Network Address<br />
DD 9D 20 2C 3A B4 57 13 - Node random unique ID<br />
00 - "" sub-version string (string is 0 bytes long)<br />
55 81 01 00 - Last block sending node has is block #98645<br />
</pre><br />
<br />
And here's a modern (60002) protocol version client advertising itself to a local peer...<br />
<br />
Newer protocol includes the checksum now, this is from a mainline (satoshi) client during <br />
an outgoing connection to another local client, notice that it does not fill out the <br />
address information at all when the source or destination is "unroutable".<br />
<br />
<pre><br />
<br />
0000 f9 be b4 d9 76 65 72 73 69 6f 6e 00 00 00 00 00 ....version.....<br />
0010 64 00 00 00 35 8d 49 32 62 ea 00 00 01 00 00 00 d...5.I2b.......<br />
0020 00 00 00 00 11 b2 d0 50 00 00 00 00 01 00 00 00 .......P........<br />
0030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ff ff ................<br />
0040 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 00 00 00 00 ff ff 00 00 00 00 00 00 ................<br />
0060 3b 2e b3 5d 8c e6 17 65 0f 2f 53 61 74 6f 73 68 ;..]...e./Satosh<br />
0070 69 3a 30 2e 37 2e 32 2f c0 3e 03 00 i:0.7.2/.>..<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
64 00 00 00 - Payload is 100 bytes long<br />
3B 64 8D 5A - payload checksum<br />
<br />
Version message:<br />
62 EA 00 00 - 60002 (protocol version 60002)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
11 B2 D0 50 00 00 00 00 - Tue Dec 18 10:12:33 PST 2012<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Sender address info - see Network Address<br />
3B 2E B3 5D 8C E6 17 65 - Node ID<br />
0F 2F 53 61 74 6F 73 68 69 3A 30 2E 37 2E 32 2F - "/Satoshi:0.7.2/" sub-version string (string is 15 bytes long)<br />
C0 3E 03 00 - Last block sending node has is block #212672<br />
</pre><br />
<br />
=== verack ===<br />
<br />
The ''verack'' message is sent in reply to ''[[#version|version]]''. This message consists of only a [[#Message structure|message header]] with the command string "verack".<br />
<br />
Hexdump of the verack message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......<br />
0010 00 00 00 00 5D F6 E0 E2 ........<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 61 63 6B 00 00 00 00 00 00 - "verack" command<br />
00 00 00 00 - Payload is 0 bytes long<br />
5D F6 E0 E2 - Checksum<br />
</pre><br />
<br />
=== addr ===<br />
<br />
Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours<br />
<br />
Payload:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of address entries (max: 1000)<br />
|-<br />
| 30x? || addr_list || (uint32_t + [[#Network address|net_addr]])[] || Address of other nodes on the network. version < 209 will only read the first one. The uint32_t is a timestamp (see note below).<br />
|}<br />
<br />
'''Note''': Starting version 31402, addresses are prefixed with a timestamp. If no timestamp is present, the addresses should not be relayed to other peers, unless it is indeed confirmed they are up.<br />
<br />
Hexdump example of ''addr'' message:<br />
<pre><br />
0000 F9 BE B4 D9 61 64 64 72 00 00 00 00 00 00 00 00 ....addr........<br />
0010 1F 00 00 00 ED 52 39 9B 01 E2 15 10 4D 01 00 00 .....R9.....M...<br />
0020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF ................<br />
0030 FF 0A 00 00 01 20 8D ..... .<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
61 64 64 72 00 00 00 00 00 00 00 00 - "addr"<br />
1F 00 00 00 - payload is 31 bytes long<br />
ED 52 39 9B - checksum of payload<br />
<br />
Payload:<br />
01 - 1 address in this message<br />
<br />
Address:<br />
E2 15 10 4D - Mon Dec 20 21:50:10 EST 2010 (only when version is >= 31402)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK service - see version message)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv4: 10.0.0.1, IPv6: ::ffff:10.0.0.1 (IPv4-mapped IPv6 address)<br />
20 8D - port 8333<br />
</pre><br />
<br />
=== inv ===<br />
<br />
Allows a node to advertise its knowledge of one or more objects. It can be received unsolicited, or in reply to ''getblocks''.<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getdata ===<br />
<br />
getdata is used in response to inv, to retrieve the content of a specific object, and is usually sent after receiving an ''inv'' packet, after filtering known elements. It can be used to retrieve transactions, but only if they are in the memory pool or relay set - arbitrary access to transactions in the chain is not allowed to avoid having clients start to depend on nodes having full transaction indexes (which modern nodes do not).<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== notfound ===<br />
<br />
notfound is a response to a getdata, sent if any requested data items could not be relayed, for example, because the requested transaction was not in the memory pool or relay set.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getblocks ===<br />
<br />
Return an ''inv'' packet containing the list of blocks starting right after the last known hash in the block locator object, up to hash_stop or 500 blocks, whichever comes first. <br />
<br />
The locator hashes are processed by a node in the order as they appear in the message. If a block hash is found in the node's main chain, the list of its children is returned back via the ''inv'' message and the remaining locators are ignored, no matter if the requested limit was reached, or not.<br />
<br />
To receive the next blocks hashes, one needs to issue getblocks again with a new block locator object. Keep in mind that some clients may provide blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block; set to zero to get as many blocks as possible (500)<br />
|}<br />
<br />
To create the block locator hashes, keep pushing hashes until you go back to the genesis block. After pushing 10 hashes back, the step backwards doubles every loop:<br />
<br />
<pre><br />
// From libbitcoin which is under AGPL<br />
std::vector<size_t> block_locator_indexes(size_t top_height)<br />
{<br />
std::vector<size_t> indexes;<br />
<br />
// Modify the step in the iteration.<br />
int64_t step = 1;<br />
<br />
// Start at the top of the chain and work backwards.<br />
for (auto index = (int64_t)top_height; index > 0; index -= step)<br />
{<br />
// Push top 10 indexes first, then back off exponentially.<br />
if (indexes.size() >= 10)<br />
step *= 2;<br />
<br />
indexes.push_back((size_t)index);<br />
}<br />
<br />
// Push the genesis block index.<br />
indexes.push_back(0);<br />
return indexes;<br />
}<br />
</pre><br />
<br />
Note that it is allowed to send in fewer known hashes down to a minimum of just one hash. However, the purpose of the block locator object is to detect a wrong branch in the caller's main chain. If the peer detects that you are off the main chain, it will send in block hashes which are earlier than your last known block. So if you just send in your last known hash and it is off the main chain, the peer starts over at block #1.<br />
<br />
=== getheaders ===<br />
<br />
Return a ''headers'' packet containing the headers of blocks starting right after the last known hash in the block locator object, up to hash_stop or 2000 blocks, whichever comes first. To receive the next block headers, one needs to issue getheaders again with a new block locator object. The ''getheaders'' command is used by thin clients to quickly download the block chain where the contents of the transactions would be irrelevant (because they are not ours). Keep in mind that some clients may provide headers of blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block header; set to zero to get as many blocks as possible (2000)<br />
|}<br />
<br />
For the block locator object in this packet, the same rules apply as for the [[Protocol_documentation#getblocks|getblocks]] packet.<br />
<br />
=== tx ===<br />
<br />
''tx'' describes a bitcoin transaction, in reply to ''[[#getdata|getdata]]''<br />
<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Transaction data format version (note, this is signed)<br />
|-<br />
| 1+ || tx_in count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction inputs<br />
|-<br />
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins<br />
|-<br />
| 1+ || tx_out count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction outputs<br />
|-<br />
| 9+ || tx_out || tx_out[] || A list of 1 or more transaction outputs or destinations for coins<br />
|-<br />
| 4 || lock_time || uint32_t || The block number or timestamp at which this transaction is locked:<br />
{|class="wikitable"<br />
! Value !! Description<br />
|-<br />
| 0 || Not locked<br />
|-<br />
| < 500000000 || Block number at which this transaction is locked<br />
|-<br />
| >= 500000000 || UNIX timestamp at which this transaction is locked<br />
|}<br />
If all TxIn inputs have final (0xffffffff) sequence numbers then lock_time is irrelevant. Otherwise, the transaction may not be added to a block until after lock_time (see [[NLockTime]]).<br />
<br />
|}<br />
<br />
TxIn consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 36 || previous_output || outpoint || The previous output transaction reference, as an OutPoint structure<br />
|-<br />
| 1+ || script length || [[Protocol_documentation#Variable_length_integer|var_int]] || The length of the signature script<br />
|-<br />
| ? || signature script || uchar[] || Computational Script for confirming transaction authorization<br />
|-<br />
| 4 || [http://bitcoin.stackexchange.com/q/2025/323 sequence] || uint32_t || Transaction version as defined by the sender. Intended for "replacement" of transactions when information is updated before inclusion into a block.<br />
|}<br />
<br />
The OutPoint structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 32 || hash || char[32] || The hash of the referenced transaction.<br />
|-<br />
| 4 || index || uint32_t || The index of the specific output in the transaction. The first output is 0, etc.<br />
|}<br />
<br />
The Script structure consists of a series of pieces of information and operations related to the value of the transaction.<br />
<br />
(Structure to be expanded in the future… see script.h and script.cpp and [[Script]] for more information)<br />
<br />
The TxOut structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || value || int64_t || Transaction Value<br />
|-<br />
| 1+ || pk_script length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the pk_script<br />
|-<br />
| ? || pk_script || uchar[] || Usually contains the public key as a Bitcoin script setting up conditions to claim this output.<br />
|}<br />
<br />
Example ''tx'' message:<br />
<pre><br />
000000 F9 BE B4 D9 74 78 00 00 00 00 00 00 00 00 00 00 ....tx..........<br />
000010 02 01 00 00 E2 93 CD BE 01 00 00 00 01 6D BD DB .............m..<br />
000020 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D 12 66 E9 .[...Q........f.<br />
000030 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29 00 00 00 .;P......j.6)...<br />
000040 00 8B 48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 ..H0E.!..X..r...<br />
000050 C7 36 7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A .6zz%;..R#...h.:<br />
000060 59 23 3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 Y#?E.W... Y.....<br />
000070 0E 41 83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D .A.z.X.z...XN...<br />
000080 35 BD 96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF 5...6..;...A....<br />
000090 C9 7E F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 .~.6.m...@..!...<br />
0000A0 2A CD 2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC *.+..].}Y... ...<br />
0000B0 4E 02 53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F N.S..=7.o...Q...<br />
0000C0 14 04 2F 46 61 4A 4C 70 C0 F1 4B EF F5 FF FF FF ../FaJLp..K.....<br />
0000D0 FF 02 40 4B 4C 00 00 00 00 00 19 76 A9 14 1A A0 ..@KL......v....<br />
0000E0 CD 1C BE A6 E7 45 8A 7A BA D5 12 A9 D9 EA 1A FB .....E.z........<br />
0000F0 22 5E 88 AC 80 FA E9 C7 00 00 00 00 19 76 A9 14 "^...........v..<br />
000100 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E FD A0 B7 ..[.Cj.....H^...<br />
000110 8B 4E CC 52 88 AC 00 00 00 00 .N.R......<br />
<br />
<br />
Message header:<br />
F9 BE B4 D9 - main network magic bytes<br />
74 78 00 00 00 00 00 00 00 00 00 00 - "tx" command<br />
02 01 00 00 - payload is 258 bytes long<br />
E2 93 CD BE - checksum of payload<br />
<br />
Transaction:<br />
01 00 00 00 - version<br />
<br />
Inputs:<br />
01 - number of transaction inputs<br />
<br />
Input 1:<br />
6D BD DB 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D - previous output (outpoint)<br />
12 66 E9 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29<br />
00 00 00 00<br />
<br />
8B - script is 139 bytes long<br />
<br />
48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 C7 36 - signature script (scriptSig)<br />
7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A 59 23<br />
3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 0E 41<br />
83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D 35 BD<br />
96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF C9 7E<br />
F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 2A CD<br />
2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC 4E 02<br />
53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F 14 04<br />
2F 46 61 4A 4C 70 C0 F1 4B EF F5<br />
<br />
FF FF FF FF - sequence<br />
<br />
Outputs:<br />
02 - 2 Output Transactions<br />
<br />
Output 1:<br />
40 4B 4C 00 00 00 00 00 - 0.05 BTC (5000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 1A A0 CD 1C BE A6 E7 45 8A 7A BA D5 12 - pk_script<br />
A9 D9 EA 1A FB 22 5E 88 AC<br />
<br />
Output 2:<br />
80 FA E9 C7 00 00 00 00 - 33.54 BTC (3354000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E - pk_script<br />
FD A0 B7 8B 4E CC 52 88 AC<br />
<br />
Locktime:<br />
00 00 00 00 - lock time<br />
</pre><br />
<br />
=== block ===<br />
<br />
The '''block''' message is sent in response to a getdata message which requests transaction information from a block hash.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A Unix timestamp recording when this block was created (Currently limited to dates before the year 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated [[Difficulty|difficulty target]] being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| ? || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries<br />
|-<br />
| ? || txns || tx[] || Block transactions, in format of "tx" command<br />
|}<br />
<br />
The SHA256 hash that identifies each block (and which must have a run of 0 bits) is calculated from the first 6 fields of this structure (version, prev_block, merkle_root, timestamp, bits, nonce, and standard SHA256 padding, making two 64-byte chunks in all) and ''not'' from the complete block. To calculate the hash, only two chunks need to be processed by the SHA256 algorithm. Since the ''nonce'' field is in the second chunk, the first chunk stays constant during mining and therefore only the second chunk needs to be processed. However, a Bitcoin hash is the hash of the hash, so two SHA256 rounds are needed for each mining iteration.<br />
See [[Block hashing algorithm]] for details and an example.<br />
<br />
=== headers ===<br />
<br />
The ''headers'' packet returns block headers in response to a ''getheaders'' packet. <br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of block headers<br />
|-<br />
| 81x? || headers || [[Protocol_documentation#Block_Headers|block_header]][] || [[Protocol_documentation#Block_Headers|Block headers]]<br />
|}<br />
<br />
Note that the block headers in this packet include a transaction count (a var_int, so there can be more than 81 bytes per header) as opposed to the block headers which are sent to miners.<br />
<br />
=== getaddr ===<br />
<br />
The getaddr message sends a request to a node asking for information about known active peers to help with finding potential nodes in the network. The response to receiving this message is to transmit one or more addr messages with one or more peers from a database of known active peers. The typical presumption is that a node is likely to be active if it has been sending a message within the last three hours.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
=== mempool ===<br />
<br />
The mempool message sends a request to a node asking for information about transactions it has verified but which have not yet confirmed. The response to receiving this message is an inv message containing the transaction hashes for all the transactions in the node's mempool.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
It is specified in [https://github.com/bitcoin/bips/blob/master/bip-0035.mediawiki BIP 35]. Since [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 37], if a [[Protocol_documentation#filterload.2C_filteradd.2C_filterclear.2C_merkleblock|bloom filter]] is loaded, only transactions matching the filter are replied.<br />
<br />
=== checkorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== submitorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== reply ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== ping ===<br />
<br />
The ''ping'' message is sent primarily to confirm that the TCP/IP connection is still valid. An error in transmission is presumed to be a closed connection and the address is removed as a current peer.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || random nonce<br />
|}<br />
<br />
=== pong ===<br />
<br />
The ''pong'' message is sent in response to a ''ping'' message. In modern protocol versions, a ''pong'' response is generated using a nonce included in the ping.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || nonce from ping<br />
|}<br />
<br />
<br />
=== reject===<br />
<br />
The ''reject'' message is sent when messages are rejected.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || message || var_str || type of message rejected<br />
|-<br />
| 1 || ccode || char || code relating to rejected message<br />
|-<br />
| 1+ || reason || var_str || text version of reason for rejection<br />
|-<br />
| 0+ || data || char || Optional extra data provided by some errors. Currently, all errors which provide this field fill it with the TXID or block header hash of the object being rejected, so the field is 32 bytes.<br />
|}<br />
<br />
CCodes<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0x01 || REJECT_MALFORMED|| <br />
|-<br />
| 0x10 || REJECT_INVALID ||<br />
|-<br />
| 0x11 || REJECT_OBSOLETE ||<br />
|-<br />
| 0x12 || REJECT_DUPLICATE ||<br />
|-<br />
| 0x40 || REJECT_NONSTANDARD ||<br />
|-<br />
| 0x41 || REJECT_DUST ||<br />
|-<br />
| 0x42 || REJECT_INSUFFICIENTFEE ||<br />
|-<br />
| 0x43 || REJECT_CHECKPOINT ||<br />
|}<br />
<br />
=== filterload, filteradd, filterclear, merkleblock ===<br />
<br />
These messages are related to Bloom filtering of connections and are defined in [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037].<br />
<br />
<br />
The <code>filterload</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || filter || uint8_t[] || The filter itself is simply a bit field of arbitrary byte-aligned size. The maximum size is 36,000 bytes.<br />
|-<br />
| 4 || nHashFuncs || uint32_t || The number of hash functions to use in this filter. The maximum value allowed in this field is 50.<br />
|-<br />
| 4 || nTweak || uint32_t || A random value to add to the seed value in the hash function used by the bloom filter.<br />
|-<br />
| 1 || nFlags || uint8_t || A set of flags that control how matched items are added to the filter.<br />
|}<br />
<br />
See below for a description of the Bloom filter algorithm and how to select nHashFuncs and filter size for a desired false positive rate.<br />
<br />
Upon receiving a <code>filterload</code> command, the remote peer will immediately restrict the broadcast transactions it announces (in inv packets) to transactions matching the filter, where the matching algorithm is specified below. The flags control the update behaviour of the matching algorithm.<br />
<br />
The <code>filteradd</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || data || uint8_t[] || The data element to add to the current filter.<br />
|}<br />
<br />
The data field must be smaller than or equal to 520 bytes in size (the maximum size of any potentially matched object).<br />
<br />
The given data element will be added to the Bloom filter. A filter must have been previously provided using <code>filterload</code>. This command is useful if a new key or script is added to a clients wallet whilst it has connections to the network open, it avoids the need to re-calculate and send an entirely new filter to every peer (though doing so is usually advisable to maintain anonymity).<br />
<br />
The <code>filterclear</code> command has no arguments at all.<br />
<br />
After a filter has been set, nodes don't merely stop announcing non-matching transactions, they can also serve filtered blocks. A filtered block is defined by the <code>merkleblock</code> message and is defined like this:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || Block version information, based upon the software version creating this block<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Limited to 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 4 || total_transactions || uint32_t || Number of transactions in the block (including unmatched ones)<br />
|-<br />
| ? || hashes || uint256[] || hashes in depth-first order (including standard varint size prefix)<br />
|-<br />
| ? || flags || byte[] || flag bits, packed per 8 in a byte, least significant bit first (including standard varint size prefix)<br />
|}<br />
<br />
=== alert ===<br />
<br />
An '''alert''' is sent between nodes to send a general notification message throughout the network. If the alert can be confirmed with the signature as having come from the core development group of the Bitcoin software, the message is suggested to be displayed for end-users. Attempts to perform transactions, particularly automated transactions through the client, are suggested to be halted. The text in the Message string should be relayed to log files and any user interfaces.<br />
<br />
Alert format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || payload || uchar[] || Serialized alert payload<br />
|-<br />
| ? || signature || uchar[] || An ECDSA signature of the message<br />
|}<br />
<br />
The developers of Satoshi's client use this public key for signing alerts:<br />
04fc9702847840aaf195de8442ebecedf5b095cdbb9bc716bda9110971b28a49e0ead8564ff0db22209e0374782c093bb899692d524e9d6a6956e7c5ecbcd68284<br />
(hash) 1AGRxqDa5WjUKBwHB9XYEjmkv1ucoUUy1s<br />
<br />
The payload is serialized into a uchar[] to ensure that versions using incompatible alert formats can still relay alerts among one another. The current alert payload format is:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || Version || int32_t || Alert format version<br />
|-<br />
| 8 || RelayUntil || int64_t || The timestamp beyond which nodes should stop relaying this alert<br />
|-<br />
| 8 || Expiration || int64_t || The timestamp beyond which this alert is no longer in effect and should be ignored<br />
|-<br />
| 4 || ID || int32_t || A unique ID number for this alert<br />
|-<br />
| 4 || Cancel || int32_t || All alerts with an ID number less than or equal to this number should be cancelled: deleted and not accepted in the future<br />
|-<br />
| ? || setCancel || set<int32_t> || All alert IDs contained in this set should be cancelled as above<br />
|-<br />
| 4 || MinVer || int32_t || This alert only applies to versions greater than or equal to this version. Other versions should still relay it.<br />
|-<br />
| 4 || MaxVer || int32_t || This alert only applies to versions less than or equal to this version. Other versions should still relay it.<br />
|-<br />
| ? || setSubVer || set<string> || If this set contains any elements, then only nodes that have their subVer contained in this set are affected by the alert. Other versions should still relay it.<br />
|-<br />
| 4 || Priority || int32_t || Relative priority compared to other alerts<br />
|-<br />
| ? || Comment || string || A comment on the alert that is not displayed<br />
|-<br />
| ? || StatusBar || string || The alert message that is displayed to the user<br />
|-<br />
| ? || Reserved || string || Reserved<br />
|}<br />
<br />
Note: '''set<''type''>''' in the table above is a [[#Variable length integer | variable length integer]] followed by the number of fields of the given ''type'' (either int32_t or [[#Variable length string | variable length string]])<br />
<br />
Sample alert (no message header):<br />
73010000003766404f00000000b305434f00000000f2030000f1030000001027000048ee0000<br />
0064000000004653656520626974636f696e2e6f72672f666562323020696620796f75206861<br />
76652074726f75626c6520636f6e6e656374696e672061667465722032302046656272756172<br />
79004730450221008389df45f0703f39ec8c1cc42c13810ffcae14995bb648340219e353b63b<br />
53eb022009ec65e1c1aaeec1fd334c6b684bde2b3f573060d5b70c3a46723326e4e8a4f1<br />
<br />
Version: 1<br />
RelayUntil: 1329620535<br />
Expiration: 1329792435<br />
ID: 1010<br />
Cancel: 1009<br />
setCancel: <empty><br />
MinVer: 10000<br />
MaxVer: 61000<br />
setSubVer: <empty><br />
Priority: 100<br />
Comment: <empty><br />
StatusBar: "See bitcoin.org/feb20 if you have trouble connecting after 20 February"<br />
Reserved: <empty><br />
<br />
=== sendheaders ===<br />
<br />
Request for Direct headers announcement. <br />
<br />
Upon receipt of this message, the node is be permitted, but not required, to announce new blocks by '''headers''' command (instead of '''inv''' command).<br />
<br />
This message is supported by the protocol version >= 70012 or Bitcoin Core version >= 0.12.0.<br />
<br />
See [https://github.com/bitcoin/bips/blob/master/bip-0130.mediawiki BIP 130] for more information.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
== Scripting ==<br />
<br />
See [[script]].<br />
<br />
==See Also==<br />
<br />
* [[Network]]<br />
* [[Protocol rules]]<br />
* [[Hardfork Wishlist]]<br />
* [https://bitcoin.org/en/developer-documentation Developer Documentation on bitcoin.org]<br />
* Bitcoin dissectors for Wireshark: https://github.com/lbotsch/wireshark-bitcoin https://github.com/op-sig/bitcoin-wireshark-dissector<br />
<br />
==References==<br />
<references /><br />
<br />
[[zh-cn:协议说明]]<br />
[[Category:Technical]]<br />
[[Category:Developer]]<br />
<br />
{{Bitcoin Core documentation}}</div>Tonikthttps://en.bitcoin.it/w/index.php?title=Protocol_documentation&diff=60481Protocol documentation2016-02-24T13:54:54Z<p>Tonikt: added sendheaders</p>
<hr />
<div>This page ''describes'' the behavior of the [[Original Bitcoin client|reference client]]. The Bitcoin protocol is specified by the behavior of the reference client, not by this page. In particular, while this page is quite complete in describing the network protocol, it does not attempt to list all of the rules for block or transaction validity.<br />
<br />
Type names used in this documentation are from the C99 standard.<br />
<br />
For protocol used in mining, see [[getblocktemplate]].<br />
<br />
==Common standards==<br />
<br />
=== Hashes ===<br />
<br />
Usually, when a hash is computed within bitcoin, it is computed twice. Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-256] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when a shorter hash is desirable (for example when creating a bitcoin address).<br />
<br />
Example of double-SHA-256 encoding of string "hello":<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round of sha-256)<br />
9595c9df90075148eb06860365df33584b75bff782a510c6cd4883a419833d50 (second round of sha-256)<br />
<br />
For bitcoin addresses (RIPEMD-160) this would give:<br />
<br />
hello<br />
2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 (first round is sha-256)<br />
b6a9c8c230722b7c748331a8b450f05566dc7d0f (with ripemd-160)<br />
<br />
=== Merkle Trees ===<br />
<br />
Merkle trees are binary trees of hashes. Merkle trees in bitcoin use a '''double''' SHA-256, the SHA-256 hash of the SHA-256 hash of something.<br />
<br />
If, when forming a row in the tree (other than the root of the tree), it would have an odd number of elements, the final double-hash is duplicated to ensure that the row has an even number of hashes.<br />
<br />
First form the bottom row of the tree with the ordered double-SHA-256 hashes of the byte streams of the transactions in the block.<br />
<br />
Then the row above it consists of half that number of hashes. Each entry is the double-SHA-256 of the 64-byte concatenation of the corresponding two hashes below it in the tree.<br />
<br />
This procedure repeats recursively until we reach a row consisting of just a single double-hash. This is the '''Merkle root''' of the tree.<br />
<br />
For example, imagine a block with three transactions ''a'', ''b'' and ''c''. The Merkle tree is: <br />
<br />
d1 = dhash(a)<br />
d2 = dhash(b)<br />
d3 = dhash(c)<br />
d4 = dhash(c) # a, b, c are 3. that's an odd number, so we take the c twice<br />
<br />
d5 = dhash(d1 concat d2)<br />
d6 = dhash(d3 concat d4)<br />
<br />
d7 = dhash(d5 concat d6)<br />
<br />
where<br />
<br />
dhash(a) = sha256(sha256(a))<br />
<br />
''d7'' is the Merkle root of the 3 transactions in this block.<br />
<br />
Note: Hashes in Merkle Tree displayed in the [[Block Explorer]] are of little-endian notation. For some implementations and [http://www.fileformat.info/tool/hash.htm calculations], the bits need to be reversed before they are hashed, and again after the hashing operation.<br />
<br />
=== Signatures ===<br />
<br />
Bitcoin uses [http://en.wikipedia.org/wiki/Elliptic_curve_cryptography Elliptic Curve] [http://en.wikipedia.org/wiki/Digital_Signature_Algorithm Digital Signature Algorithm] ([http://en.wikipedia.org/wiki/Elliptic_Curve_DSA ECDSA]) to sign transactions. <br />
<br />
For [[ECDSA]] the secp256k1 curve from http://www.secg.org/collateral/sec2_final.pdf is used.<br />
<br />
Public keys (in scripts) are given as 04 <x> <y> where ''x'' and ''y'' are 32 byte big-endian integers representing the coordinates of a point on the curve or in compressed form given as <sign> <x> where <sign> is 0x02 if ''y'' is even and 0x03 if ''y'' is odd.<br />
<br />
Signatures use [http://en.wikipedia.org/wiki/Distinguished_Encoding_Rules DER encoding] to pack the ''r'' and ''s'' components into a single byte stream (this is also what OpenSSL produces by default).<br />
<br />
=== Transaction Verification ===<br />
Transactions are cryptographically signed records that reassign ownership of Bitcoins to new addresses. Transactions have ''inputs'' - records which reference the funds from other previous transactions - and ''outputs'' - records which determine the new owner of the transferred Bitcoins, and which will be referenced as inputs in future transactions as those funds are respent.<br />
<br />
Each ''input'' must have a cryptographic digital signature that unlocks the funds from the prior transaction. Only the person possessing the appropriate [[private key]] is able to create a satisfactory signature; this in effect ensures that funds can only be spent by their owners.<br />
<br />
Each ''output'' determines which Bitcoin address (or other criteria, see [[Script]]) is the recipient of the funds.<br />
<br />
In a transaction, the sum of all inputs must be equal to or greater than the sum of all outputs. If the inputs exceed the outputs, the difference is considered a [[transaction fee]], and is redeemable by whoever first includes the transaction into the block chain.<br />
<br />
A special kind of transaction, called a [[coinbase transaction]], has no inputs. It is created by [[miners]], and there is one coinbase transaction per block. Because each block comes with a reward of newly created Bitcoins (e.g. 50 BTC for the first 210,000 blocks), the first transaction of a block is, with few exceptions, the transaction that grants those coins to their recipient (the miner). In addition to the newly created Bitcoins, the coinbase transaction is also used for assigning the recipient of any transaction fees that were paid within the other transactions being included in the same block. The coinbase transaction can assign the entire reward to a single Bitcoin address, or split it in portions among multiple addresses, just like any other transaction. Coinbase transactions always contain outputs totalling the sum of the block reward plus all transaction fees collected from the other transactions in the same block.<br />
<br />
The [[coinbase transaction]] in block zero cannot be spent. This is due to a quirk of the reference client implementation that would open the potential for a block chain fork if some nodes accepted the spend and others did not<ref>[http://bitcointalk.org/index.php?topic=119645.msg1288552#msg1288552 Block 0 Network Fork]</ref>.<br />
<br />
Most Bitcoin outputs encumber the newly transferred coins with a single ECDSA private key. The actual record saved with inputs and outputs isn't necessarily a key, but a ''script''. Bitcoin uses an interpreted scripting system to determine whether an output's criteria have been satisfied, with which more complex operations are possible, such as outputs that require two ECDSA signatures, or two-of-three-signature schemes. An output that references a single Bitcoin address is a ''typical'' output; an output actually contains this information in the form of a script that requires a single ECDSA signature (see [[OP_CHECKSIG]]). The output script specifies what must be provided to unlock the funds later, and when the time comes in the future to spend the transaction in another input, that input must provide all of the thing(s) that satisfy the requirements defined by the original output script.<br />
<br />
=== Addresses ===<br />
<br />
A bitcoin address is in fact the hash of a ECDSA public key, computed this way:<br />
<br />
Version = 1 byte of 0 (zero); on the test network, this is 1 byte of 111<br />
Key hash = Version concatenated with RIPEMD-160(SHA-256(public key))<br />
Checksum = 1st 4 bytes of SHA-256(SHA-256(Key hash))<br />
Bitcoin Address = Base58Encode(Key hash concatenated with Checksum)<br />
<br />
The Base58 encoding used is home made, and has some differences. Especially, leading zeroes are kept as single zeroes when conversion happens.<br />
<br />
== Common structures ==<br />
<br />
Almost all integers are encoded in little endian. Only IP or port number are encoded big endian.<br />
<br />
=== Message structure ===<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown<br />
|-<br />
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)<br />
|-<br />
| 4 || length || uint32_t || Length of payload in number of bytes<br />
|-<br />
| 4 || checksum || uint32_t || First 4 bytes of sha256(sha256(payload))<br />
|-<br />
| ? || payload || uchar[] || The actual data<br />
|}<br />
<br />
<br />
Known magic values:<br />
<br />
{|class="wikitable"<br />
! Network !! Magic value !! Sent over wire as<br />
|-<br />
| main || 0xD9B4BEF9 || F9 BE B4 D9<br />
|-<br />
| testnet || 0xDAB5BFFA || FA BF B5 DA<br />
|-<br />
| testnet3 || 0x0709110B || 0B 11 09 07<br />
|-<br />
| namecoin || 0xFEB4BEF9 || F9 BE B4 FE<br />
|}<br />
<br />
=== Variable length integer ===<br />
<br />
Integer can be encoded depending on the represented value to save space.<br />
Variable length integers always precede an array/vector of a type of data that may vary in length.<br />
Longer numbers are encoded in little endian.<br />
<br />
{|class="wikitable"<br />
! Value !! Storage length !! Format<br />
|-<br />
| < 0xFD || 1 || uint8_t<br />
|-<br />
| <= 0xFFFF || 3 || 0xFD followed by the length as uint16_t<br />
|-<br />
| <= 0xFFFF FFFF || 5 || 0xFE followed by the length as uint32_t<br />
|-<br />
| - || 9 || 0xFF followed by the length as uint64_t<br />
|}<br />
<br />
If you're reading the Satoshi client code (BitcoinQT) it refers to this encoding as a "CompactSize". Modern BitcoinQT also has the CVarInt class which implements an even more compact integer for the purpose of local storage (which is incompatible with "CompactSize" described here). CVarInt is not a part of the protocol.<br />
<br />
=== Variable length string ===<br />
<br />
Variable length string can be stored using a variable length integer followed by the string itself.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the string<br />
|-<br />
| ? || string || char[] || The string itself (can be empty)<br />
|}<br />
<br />
=== Network address ===<br />
<br />
When a network address is needed somewhere, this structure is used. Network addresses are not prefixed with a timestamp in the version message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || time || uint32 || the Time (version >= 31402). '''Not present in version message.'''<br />
|-<br />
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]<br />
|-<br />
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The original client only supported IPv4 and only read the last 4 bytes to get the IPv4 address. However, the IPv4 address is written into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]<br />
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).<br />
|-<br />
| 2 || port || uint16_t || port number, network byte order<br />
|}<br />
<br />
Hexdump example of Network address structure<br />
<br />
<pre><br />
0000 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0010 00 00 FF FF 0A 00 00 01 20 8D ........ .<br />
<br />
Network address:<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK: see services listed under version command)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv6: ::ffff:a00:1 or IPv4: 10.0.0.1<br />
20 8D - Port 8333<br />
</pre><br />
<br />
=== Inventory Vectors ===<br />
<br />
Inventory vectors are used for notifying other nodes about objects they have or data which is being requested.<br />
<br />
Inventory vectors consist of the following data format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || type || uint32_t || Identifies the object type linked to this inventory<br />
|-<br />
| 32 || hash || char[32] || Hash of the object<br />
|}<br />
<br />
<br />
The object type is currently defined as one of the following possibilities:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0 || ERROR || Any data of with this number may be ignored<br />
|-<br />
| 1 || MSG_TX || Hash is related to a transaction<br />
|-<br />
| 2 || MSG_BLOCK || Hash is related to a data block<br />
|-<br />
| 3 || MSG_FILTERED_BLOCK || Hash of a block header; identical to MSG_BLOCK. When used in a getdata message, this indicates the reply should be a merkleblock message rather than a block message; this only works if a bloom filter has been set.<br />
|}<br />
<br />
Other Data Type values are considered reserved for future implementations.<br />
<br />
=== Block Headers ===<br />
<br />
Block headers are sent in a headers packet in response to a getheaders message.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Will overflow in 2106<ref>https://en.wikipedia.org/wiki/Unix_time#Notable_events_in_Unix_time</ref>)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 1 || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries, this value is always 0<br />
|}<br />
<br />
cf. [[Block hashing algorithm]]<br />
<br />
== Message types ==<br />
<br />
=== version ===<br />
<br />
When a node creates an outgoing connection, it will immediately [[Version Handshake|advertise]] its version. The remote node will respond with its version. No further communication is possible until both peers have exchanged their version.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Identifies protocol version being used by the node<br />
|-<br />
| 8 || services || uint64_t || bitfield of features to be enabled for this connection<br />
|-<br />
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds<br />
|-<br />
| 26 || addr_recv || [[#Network address|net_addr]] || The network address of the node receiving this message<br />
|-<br />
|colspan="4"| Fields below require version ≥ 106<br />
|-<br />
| 26 || addr_from || [[#Network address|net_addr]] || The network address of the node emitting this message<br />
|-<br />
| 8 || nonce || uint64_t || Node random nonce, randomly generated every time a version packet is sent. This nonce is used to detect connections to self.<br />
|-<br />
| ? || user_agent || [[#Variable length string|var_str]] || [https://github.com/bitcoin/bips/blob/master/bip-0014.mediawiki User Agent] (0x00 if string is 0 bytes long)<br />
|-<br />
| 4 || start_height || int32_t || The last block received by the emitting node<br />
|-<br />
|colspan="4"| Fields below require version ≥ 70001<br />
|-<br />
| 1 || relay || bool || Whether the remote peer should announce relayed transactions or not, see [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037]<br />
|}<br />
<br />
A "verack" packet shall be sent if the version packet was accepted.<br />
<br />
The following services are currently assigned:<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 1 || NODE_NETWORK || This node can be asked for full blocks instead of just headers.<br />
|}<br />
<br />
Hexdump example of version message (OBSOLETE EXAMPLE: This example lacks a checksum and user-agent):<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....<br />
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........<br />
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............<br />
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................<br />
0040 20 8D 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,<br />
0060 3A B4 57 13 00 55 81 01 00 :.W..U...<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
55 00 00 00 - Payload is 85 bytes long<br />
- No checksum in version message until 20 February 2012. See https://bitcointalk.org/index.php?topic=55852.0<br />
Version message:<br />
9C 7C 00 00 - 31900 (version 0.3.19)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
E6 15 10 4D 00 00 00 00 - Mon Dec 20 21:50:14 EST 2010<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 20 8D - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D - Sender address info - see Network Address<br />
DD 9D 20 2C 3A B4 57 13 - Node random unique ID<br />
00 - "" sub-version string (string is 0 bytes long)<br />
55 81 01 00 - Last block sending node has is block #98645<br />
</pre><br />
<br />
And here's a modern (60002) protocol version client advertising itself to a local peer...<br />
<br />
Newer protocol includes the checksum now, this is from a mainline (satoshi) client during <br />
an outgoing connection to another local client, notice that it does not fill out the <br />
address information at all when the source or destination is "unroutable".<br />
<br />
<pre><br />
<br />
0000 f9 be b4 d9 76 65 72 73 69 6f 6e 00 00 00 00 00 ....version.....<br />
0010 64 00 00 00 35 8d 49 32 62 ea 00 00 01 00 00 00 d...5.I2b.......<br />
0020 00 00 00 00 11 b2 d0 50 00 00 00 00 01 00 00 00 .......P........<br />
0030 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ff ff ................<br />
0040 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................<br />
0050 00 00 00 00 00 00 00 00 ff ff 00 00 00 00 00 00 ................<br />
0060 3b 2e b3 5d 8c e6 17 65 0f 2f 53 61 74 6f 73 68 ;..]...e./Satosh<br />
0070 69 3a 30 2e 37 2e 32 2f c0 3e 03 00 i:0.7.2/.>..<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 73 69 6F 6E 00 00 00 00 00 - "version" command<br />
64 00 00 00 - Payload is 100 bytes long<br />
3B 64 8D 5A - payload checksum<br />
<br />
Version message:<br />
62 EA 00 00 - 60002 (protocol version 60002)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK services)<br />
11 B2 D0 50 00 00 00 00 - Tue Dec 18 10:12:33 PST 2012<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Recipient address info - see Network Address<br />
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 00 00 00 00 00 00 - Sender address info - see Network Address<br />
3B 2E B3 5D 8C E6 17 65 - Node ID<br />
0F 2F 53 61 74 6F 73 68 69 3A 30 2E 37 2E 32 2F - "/Satoshi:0.7.2/" sub-version string (string is 15 bytes long)<br />
C0 3E 03 00 - Last block sending node has is block #212672<br />
</pre><br />
<br />
=== verack ===<br />
<br />
The ''verack'' message is sent in reply to ''[[#version|version]]''. This message consists of only a [[#Message structure|message header]] with the command string "verack".<br />
<br />
Hexdump of the verack message:<br />
<br />
<pre><br />
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......<br />
0010 00 00 00 00 5D F6 E0 E2 ........<br />
<br />
Message header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
76 65 72 61 63 6B 00 00 00 00 00 00 - "verack" command<br />
00 00 00 00 - Payload is 0 bytes long<br />
5D F6 E0 E2 - Checksum<br />
</pre><br />
<br />
=== addr ===<br />
<br />
Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours<br />
<br />
Payload:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of address entries (max: 1000)<br />
|-<br />
| 30x? || addr_list || (uint32_t + [[#Network address|net_addr]])[] || Address of other nodes on the network. version < 209 will only read the first one. The uint32_t is a timestamp (see note below).<br />
|}<br />
<br />
'''Note''': Starting version 31402, addresses are prefixed with a timestamp. If no timestamp is present, the addresses should not be relayed to other peers, unless it is indeed confirmed they are up.<br />
<br />
Hexdump example of ''addr'' message:<br />
<pre><br />
0000 F9 BE B4 D9 61 64 64 72 00 00 00 00 00 00 00 00 ....addr........<br />
0010 1F 00 00 00 ED 52 39 9B 01 E2 15 10 4D 01 00 00 .....R9.....M...<br />
0020 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF ................<br />
0030 FF 0A 00 00 01 20 8D ..... .<br />
<br />
Message Header:<br />
F9 BE B4 D9 - Main network magic bytes<br />
61 64 64 72 00 00 00 00 00 00 00 00 - "addr"<br />
1F 00 00 00 - payload is 31 bytes long<br />
ED 52 39 9B - checksum of payload<br />
<br />
Payload:<br />
01 - 1 address in this message<br />
<br />
Address:<br />
E2 15 10 4D - Mon Dec 20 21:50:10 EST 2010 (only when version is >= 31402)<br />
01 00 00 00 00 00 00 00 - 1 (NODE_NETWORK service - see version message)<br />
00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 - IPv4: 10.0.0.1, IPv6: ::ffff:10.0.0.1 (IPv4-mapped IPv6 address)<br />
20 8D - port 8333<br />
</pre><br />
<br />
=== inv ===<br />
<br />
Allows a node to advertise its knowledge of one or more objects. It can be received unsolicited, or in reply to ''getblocks''.<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getdata ===<br />
<br />
getdata is used in response to inv, to retrieve the content of a specific object, and is usually sent after receiving an ''inv'' packet, after filtering known elements. It can be used to retrieve transactions, but only if they are in the memory pool or relay set - arbitrary access to transactions in the chain is not allowed to avoid having clients start to depend on nodes having full transaction indexes (which modern nodes do not).<br />
<br />
Payload (maximum 50,000 entries, which is just over 1.8 megabytes):<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== notfound ===<br />
<br />
notfound is a response to a getdata, sent if any requested data items could not be relayed, for example, because the requested transaction was not in the memory pool or relay set.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of inventory entries<br />
|-<br />
| 36x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors<br />
|}<br />
<br />
=== getblocks ===<br />
<br />
Return an ''inv'' packet containing the list of blocks starting right after the last known hash in the block locator object, up to hash_stop or 500 blocks, whichever comes first. <br />
<br />
The locator hashes are processed by a node in the order as they appear in the message. If a block hash is found in the node's main chain, the list of its children is returned back via the ''inv'' message and the remaining locators are ignored, no matter if the requested limit was reached, or not.<br />
<br />
To receive the next blocks hashes, one needs to issue getblocks again with a new block locator object. Keep in mind that some clients may provide blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block; set to zero to get as many blocks as possible (500)<br />
|}<br />
<br />
To create the block locator hashes, keep pushing hashes until you go back to the genesis block. After pushing 10 hashes back, the step backwards doubles every loop:<br />
<br />
<pre><br />
// From libbitcoin which is under AGPL<br />
std::vector<size_t> block_locator_indexes(size_t top_height)<br />
{<br />
std::vector<size_t> indexes;<br />
<br />
// Modify the step in the iteration.<br />
int64_t step = 1;<br />
<br />
// Start at the top of the chain and work backwards.<br />
for (auto index = (int64_t)top_height; index > 0; index -= step)<br />
{<br />
// Push top 10 indexes first, then back off exponentially.<br />
if (indexes.size() >= 10)<br />
step *= 2;<br />
<br />
indexes.push_back((size_t)index);<br />
}<br />
<br />
// Push the genesis block index.<br />
indexes.push_back(0);<br />
return indexes;<br />
}<br />
</pre><br />
<br />
Note that it is allowed to send in fewer known hashes down to a minimum of just one hash. However, the purpose of the block locator object is to detect a wrong branch in the caller's main chain. If the peer detects that you are off the main chain, it will send in block hashes which are earlier than your last known block. So if you just send in your last known hash and it is off the main chain, the peer starts over at block #1.<br />
<br />
=== getheaders ===<br />
<br />
Return a ''headers'' packet containing the headers of blocks starting right after the last known hash in the block locator object, up to hash_stop or 2000 blocks, whichever comes first. To receive the next block headers, one needs to issue getheaders again with a new block locator object. The ''getheaders'' command is used by thin clients to quickly download the block chain where the contents of the transactions would be irrelevant (because they are not ours). Keep in mind that some clients may provide headers of blocks which are invalid if the block locator object contains a hash on the invalid branch.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || the protocol version<br />
|-<br />
| 1+ || hash count || [[Protocol_documentation#Variable_length_integer|var_int]] || number of block locator hash entries<br />
|-<br />
| 32+ || block locator hashes || char[32] || block locator object; newest back to genesis block (dense to start, but then sparse)<br />
|-<br />
| 32 || hash_stop || char[32] || hash of the last desired block header; set to zero to get as many blocks as possible (2000)<br />
|}<br />
<br />
For the block locator object in this packet, the same rules apply as for the [[Protocol_documentation#getblocks|getblocks]] packet.<br />
<br />
=== tx ===<br />
<br />
''tx'' describes a bitcoin transaction, in reply to ''[[#getdata|getdata]]''<br />
<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Transaction data format version (note, this is signed)<br />
|-<br />
| 1+ || tx_in count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction inputs<br />
|-<br />
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins<br />
|-<br />
| 1+ || tx_out count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of Transaction outputs<br />
|-<br />
| 9+ || tx_out || tx_out[] || A list of 1 or more transaction outputs or destinations for coins<br />
|-<br />
| 4 || lock_time || uint32_t || The block number or timestamp at which this transaction is locked:<br />
{|class="wikitable"<br />
! Value !! Description<br />
|-<br />
| 0 || Not locked<br />
|-<br />
| < 500000000 || Block number at which this transaction is locked<br />
|-<br />
| >= 500000000 || UNIX timestamp at which this transaction is locked<br />
|}<br />
If all TxIn inputs have final (0xffffffff) sequence numbers then lock_time is irrelevant. Otherwise, the transaction may not be added to a block until after lock_time (see [[NLockTime]]).<br />
<br />
|}<br />
<br />
TxIn consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 36 || previous_output || outpoint || The previous output transaction reference, as an OutPoint structure<br />
|-<br />
| 1+ || script length || [[Protocol_documentation#Variable_length_integer|var_int]] || The length of the signature script<br />
|-<br />
| ? || signature script || uchar[] || Computational Script for confirming transaction authorization<br />
|-<br />
| 4 || [http://bitcoin.stackexchange.com/q/2025/323 sequence] || uint32_t || Transaction version as defined by the sender. Intended for "replacement" of transactions when information is updated before inclusion into a block.<br />
|}<br />
<br />
The OutPoint structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 32 || hash || char[32] || The hash of the referenced transaction.<br />
|-<br />
| 4 || index || uint32_t || The index of the specific output in the transaction. The first output is 0, etc.<br />
|}<br />
<br />
The Script structure consists of a series of pieces of information and operations related to the value of the transaction.<br />
<br />
(Structure to be expanded in the future… see script.h and script.cpp and [[Script]] for more information)<br />
<br />
The TxOut structure consists of the following fields:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || value || int64_t || Transaction Value<br />
|-<br />
| 1+ || pk_script length || [[Protocol_documentation#Variable_length_integer|var_int]] || Length of the pk_script<br />
|-<br />
| ? || pk_script || uchar[] || Usually contains the public key as a Bitcoin script setting up conditions to claim this output.<br />
|}<br />
<br />
Example ''tx'' message:<br />
<pre><br />
000000 F9 BE B4 D9 74 78 00 00 00 00 00 00 00 00 00 00 ....tx..........<br />
000010 02 01 00 00 E2 93 CD BE 01 00 00 00 01 6D BD DB .............m..<br />
000020 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D 12 66 E9 .[...Q........f.<br />
000030 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29 00 00 00 .;P......j.6)...<br />
000040 00 8B 48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 ..H0E.!..X..r...<br />
000050 C7 36 7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A .6zz%;..R#...h.:<br />
000060 59 23 3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 Y#?E.W... Y.....<br />
000070 0E 41 83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D .A.z.X.z...XN...<br />
000080 35 BD 96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF 5...6..;...A....<br />
000090 C9 7E F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 .~.6.m...@..!...<br />
0000A0 2A CD 2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC *.+..].}Y... ...<br />
0000B0 4E 02 53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F N.S..=7.o...Q...<br />
0000C0 14 04 2F 46 61 4A 4C 70 C0 F1 4B EF F5 FF FF FF ../FaJLp..K.....<br />
0000D0 FF 02 40 4B 4C 00 00 00 00 00 19 76 A9 14 1A A0 ..@KL......v....<br />
0000E0 CD 1C BE A6 E7 45 8A 7A BA D5 12 A9 D9 EA 1A FB .....E.z........<br />
0000F0 22 5E 88 AC 80 FA E9 C7 00 00 00 00 19 76 A9 14 "^...........v..<br />
000100 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E FD A0 B7 ..[.Cj.....H^...<br />
000110 8B 4E CC 52 88 AC 00 00 00 00 .N.R......<br />
<br />
<br />
Message header:<br />
F9 BE B4 D9 - main network magic bytes<br />
74 78 00 00 00 00 00 00 00 00 00 00 - "tx" command<br />
02 01 00 00 - payload is 258 bytes long<br />
E2 93 CD BE - checksum of payload<br />
<br />
Transaction:<br />
01 00 00 00 - version<br />
<br />
Inputs:<br />
01 - number of transaction inputs<br />
<br />
Input 1:<br />
6D BD DB 08 5B 1D 8A F7 51 84 F0 BC 01 FA D5 8D - previous output (outpoint)<br />
12 66 E9 B6 3B 50 88 19 90 E4 B4 0D 6A EE 36 29<br />
00 00 00 00<br />
<br />
8B - script is 139 bytes long<br />
<br />
48 30 45 02 21 00 F3 58 1E 19 72 AE 8A C7 C7 36 - signature script (scriptSig)<br />
7A 7A 25 3B C1 13 52 23 AD B9 A4 68 BB 3A 59 23<br />
3F 45 BC 57 83 80 02 20 59 AF 01 CA 17 D0 0E 41<br />
83 7A 1D 58 E9 7A A3 1B AE 58 4E DE C2 8D 35 BD<br />
96 92 36 90 91 3B AE 9A 01 41 04 9C 02 BF C9 7E<br />
F2 36 CE 6D 8F E5 D9 40 13 C7 21 E9 15 98 2A CD<br />
2B 12 B6 5D 9B 7D 59 E2 0A 84 20 05 F8 FC 4E 02<br />
53 2E 87 3D 37 B9 6F 09 D6 D4 51 1A DA 8F 14 04<br />
2F 46 61 4A 4C 70 C0 F1 4B EF F5<br />
<br />
FF FF FF FF - sequence<br />
<br />
Outputs:<br />
02 - 2 Output Transactions<br />
<br />
Output 1:<br />
40 4B 4C 00 00 00 00 00 - 0.05 BTC (5000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 1A A0 CD 1C BE A6 E7 45 8A 7A BA D5 12 - pk_script<br />
A9 D9 EA 1A FB 22 5E 88 AC<br />
<br />
Output 2:<br />
80 FA E9 C7 00 00 00 00 - 33.54 BTC (3354000000)<br />
19 - pk_script is 25 bytes long<br />
<br />
76 A9 14 0E AB 5B EA 43 6A 04 84 CF AB 12 48 5E - pk_script<br />
FD A0 B7 8B 4E CC 52 88 AC<br />
<br />
Locktime:<br />
00 00 00 00 - lock time<br />
</pre><br />
<br />
=== block ===<br />
<br />
The '''block''' message is sent in response to a getdata message which requests transaction information from a block hash.<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || int32_t || Block version information (note, this is signed)<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A Unix timestamp recording when this block was created (Currently limited to dates before the year 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated [[Difficulty|difficulty target]] being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| ? || txn_count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of transaction entries<br />
|-<br />
| ? || txns || tx[] || Block transactions, in format of "tx" command<br />
|}<br />
<br />
The SHA256 hash that identifies each block (and which must have a run of 0 bits) is calculated from the first 6 fields of this structure (version, prev_block, merkle_root, timestamp, bits, nonce, and standard SHA256 padding, making two 64-byte chunks in all) and ''not'' from the complete block. To calculate the hash, only two chunks need to be processed by the SHA256 algorithm. Since the ''nonce'' field is in the second chunk, the first chunk stays constant during mining and therefore only the second chunk needs to be processed. However, a Bitcoin hash is the hash of the hash, so two SHA256 rounds are needed for each mining iteration.<br />
See [[Block hashing algorithm]] for details and an example.<br />
<br />
=== headers ===<br />
<br />
The ''headers'' packet returns block headers in response to a ''getheaders'' packet. <br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of block headers<br />
|-<br />
| 81x? || headers || [[Protocol_documentation#Block_Headers|block_header]][] || [[Protocol_documentation#Block_Headers|Block headers]]<br />
|}<br />
<br />
Note that the block headers in this packet include a transaction count (a var_int, so there can be more than 81 bytes per header) as opposed to the block headers which are sent to miners.<br />
<br />
=== getaddr ===<br />
<br />
The getaddr message sends a request to a node asking for information about known active peers to help with finding potential nodes in the network. The response to receiving this message is to transmit one or more addr messages with one or more peers from a database of known active peers. The typical presumption is that a node is likely to be active if it has been sending a message within the last three hours.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
=== mempool ===<br />
<br />
The mempool message sends a request to a node asking for information about transactions it has verified but which have not yet confirmed. The response to receiving this message is an inv message containing the transaction hashes for all the transactions in the node's mempool.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
It is specified in [https://github.com/bitcoin/bips/blob/master/bip-0035.mediawiki BIP 35]. Since [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 37], if a [[Protocol_documentation#filterload.2C_filteradd.2C_filterclear.2C_merkleblock|bloom filter]] is loaded, only transactions matching the filter are replied.<br />
<br />
=== checkorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== submitorder ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== reply ===<br />
<br />
This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.<br />
<br />
=== ping ===<br />
<br />
The ''ping'' message is sent primarily to confirm that the TCP/IP connection is still valid. An error in transmission is presumed to be a closed connection and the address is removed as a current peer.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || random nonce<br />
|}<br />
<br />
=== pong ===<br />
<br />
The ''pong'' message is sent in response to a ''ping'' message. In modern protocol versions, a ''pong'' response is generated using a nonce included in the ping.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 8 || nonce || uint64_t || nonce from ping<br />
|}<br />
<br />
<br />
=== reject===<br />
<br />
The ''reject'' message is sent when messages are rejected.<br />
<br />
Payload:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 1+ || message || var_str || type of message rejected<br />
|-<br />
| 1 || ccode || char || code relating to rejected message<br />
|-<br />
| 1+ || reason || var_str || text version of reason for rejection<br />
|-<br />
| 0+ || data || char || Optional extra data provided by some errors. Currently, all errors which provide this field fill it with the TXID or block header hash of the object being rejected, so the field is 32 bytes.<br />
|}<br />
<br />
CCodes<br />
<br />
{|class="wikitable"<br />
! Value !! Name !! Description<br />
|-<br />
| 0x01 || REJECT_MALFORMED|| <br />
|-<br />
| 0x10 || REJECT_INVALID ||<br />
|-<br />
| 0x11 || REJECT_OBSOLETE ||<br />
|-<br />
| 0x12 || REJECT_DUPLICATE ||<br />
|-<br />
| 0x40 || REJECT_NONSTANDARD ||<br />
|-<br />
| 0x41 || REJECT_DUST ||<br />
|-<br />
| 0x42 || REJECT_INSUFFICIENTFEE ||<br />
|-<br />
| 0x43 || REJECT_CHECKPOINT ||<br />
|}<br />
<br />
=== filterload, filteradd, filterclear, merkleblock ===<br />
<br />
These messages are related to Bloom filtering of connections and are defined in [https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki BIP 0037].<br />
<br />
<br />
The <code>filterload</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || filter || uint8_t[] || The filter itself is simply a bit field of arbitrary byte-aligned size. The maximum size is 36,000 bytes.<br />
|-<br />
| 4 || nHashFuncs || uint32_t || The number of hash functions to use in this filter. The maximum value allowed in this field is 50.<br />
|-<br />
| 4 || nTweak || uint32_t || A random value to add to the seed value in the hash function used by the bloom filter.<br />
|-<br />
| 1 || nFlags || uint8_t || A set of flags that control how matched items are added to the filter.<br />
|}<br />
<br />
See below for a description of the Bloom filter algorithm and how to select nHashFuncs and filter size for a desired false positive rate.<br />
<br />
Upon receiving a <code>filterload</code> command, the remote peer will immediately restrict the broadcast transactions it announces (in inv packets) to transactions matching the filter, where the matching algorithm is specified below. The flags control the update behaviour of the matching algorithm.<br />
<br />
The <code>filteradd</code> command is defined as follows:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || data || uint8_t[] || The data element to add to the current filter.<br />
|}<br />
<br />
The data field must be smaller than or equal to 520 bytes in size (the maximum size of any potentially matched object).<br />
<br />
The given data element will be added to the Bloom filter. A filter must have been previously provided using <code>filterload</code>. This command is useful if a new key or script is added to a clients wallet whilst it has connections to the network open, it avoids the need to re-calculate and send an entirely new filter to every peer (though doing so is usually advisable to maintain anonymity).<br />
<br />
The <code>filterclear</code> command has no arguments at all.<br />
<br />
After a filter has been set, nodes don't merely stop announcing non-matching transactions, they can also serve filtered blocks. A filtered block is defined by the <code>merkleblock</code> message and is defined like this:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || version || uint32_t || Block version information, based upon the software version creating this block<br />
|-<br />
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references<br />
|-<br />
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block<br />
|-<br />
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Limited to 2106!)<br />
|-<br />
| 4 || bits || uint32_t || The calculated difficulty target being used for this block<br />
|-<br />
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes<br />
|-<br />
| 4 || total_transactions || uint32_t || Number of transactions in the block (including unmatched ones)<br />
|-<br />
| ? || hashes || uint256[] || hashes in depth-first order (including standard varint size prefix)<br />
|-<br />
| ? || flags || byte[] || flag bits, packed per 8 in a byte, least significant bit first (including standard varint size prefix)<br />
|}<br />
<br />
=== alert ===<br />
<br />
An '''alert''' is sent between nodes to send a general notification message throughout the network. If the alert can be confirmed with the signature as having come from the core development group of the Bitcoin software, the message is suggested to be displayed for end-users. Attempts to perform transactions, particularly automated transactions through the client, are suggested to be halted. The text in the Message string should be relayed to log files and any user interfaces.<br />
<br />
Alert format:<br />
<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| ? || payload || uchar[] || Serialized alert payload<br />
|-<br />
| ? || signature || uchar[] || An ECDSA signature of the message<br />
|}<br />
<br />
The developers of Satoshi's client use this public key for signing alerts:<br />
04fc9702847840aaf195de8442ebecedf5b095cdbb9bc716bda9110971b28a49e0ead8564ff0db22209e0374782c093bb899692d524e9d6a6956e7c5ecbcd68284<br />
(hash) 1AGRxqDa5WjUKBwHB9XYEjmkv1ucoUUy1s<br />
<br />
The payload is serialized into a uchar[] to ensure that versions using incompatible alert formats can still relay alerts among one another. The current alert payload format is:<br />
{|class="wikitable"<br />
! Field Size !! Description !! Data type !! Comments<br />
|-<br />
| 4 || Version || int32_t || Alert format version<br />
|-<br />
| 8 || RelayUntil || int64_t || The timestamp beyond which nodes should stop relaying this alert<br />
|-<br />
| 8 || Expiration || int64_t || The timestamp beyond which this alert is no longer in effect and should be ignored<br />
|-<br />
| 4 || ID || int32_t || A unique ID number for this alert<br />
|-<br />
| 4 || Cancel || int32_t || All alerts with an ID number less than or equal to this number should be cancelled: deleted and not accepted in the future<br />
|-<br />
| ? || setCancel || set<int32_t> || All alert IDs contained in this set should be cancelled as above<br />
|-<br />
| 4 || MinVer || int32_t || This alert only applies to versions greater than or equal to this version. Other versions should still relay it.<br />
|-<br />
| 4 || MaxVer || int32_t || This alert only applies to versions less than or equal to this version. Other versions should still relay it.<br />
|-<br />
| ? || setSubVer || set<string> || If this set contains any elements, then only nodes that have their subVer contained in this set are affected by the alert. Other versions should still relay it.<br />
|-<br />
| 4 || Priority || int32_t || Relative priority compared to other alerts<br />
|-<br />
| ? || Comment || string || A comment on the alert that is not displayed<br />
|-<br />
| ? || StatusBar || string || The alert message that is displayed to the user<br />
|-<br />
| ? || Reserved || string || Reserved<br />
|}<br />
<br />
Note: '''set<''type''>''' in the table above is a [[#Variable length integer | variable length integer]] followed by the number of fields of the given ''type'' (either int32_t or [[#Variable length string | variable length string]])<br />
<br />
Sample alert (no message header):<br />
73010000003766404f00000000b305434f00000000f2030000f1030000001027000048ee0000<br />
0064000000004653656520626974636f696e2e6f72672f666562323020696620796f75206861<br />
76652074726f75626c6520636f6e6e656374696e672061667465722032302046656272756172<br />
79004730450221008389df45f0703f39ec8c1cc42c13810ffcae14995bb648340219e353b63b<br />
53eb022009ec65e1c1aaeec1fd334c6b684bde2b3f573060d5b70c3a46723326e4e8a4f1<br />
<br />
Version: 1<br />
RelayUntil: 1329620535<br />
Expiration: 1329792435<br />
ID: 1010<br />
Cancel: 1009<br />
setCancel: <empty><br />
MinVer: 10000<br />
MaxVer: 61000<br />
setSubVer: <empty><br />
Priority: 100<br />
Comment: <empty><br />
StatusBar: "See bitcoin.org/feb20 if you have trouble connecting after 20 February"<br />
Reserved: <empty><br />
<br />
=== sendheaders ===<br />
<br />
Request for Direct headers announcement. See [https://github.com/bitcoin/bips/blob/master/bip-0130.mediawiki BIP 130] for more information.<br />
<br />
No additional data is transmitted with this message.<br />
<br />
This message is supported by the protocol version >= 70012 or Bitcoin Core version >= 0.12.0<br />
<br />
== Scripting ==<br />
<br />
See [[script]].<br />
<br />
==See Also==<br />
<br />
* [[Network]]<br />
* [[Protocol rules]]<br />
* [[Hardfork Wishlist]]<br />
* [https://bitcoin.org/en/developer-documentation Developer Documentation on bitcoin.org]<br />
* Bitcoin dissectors for Wireshark: https://github.com/lbotsch/wireshark-bitcoin https://github.com/op-sig/bitcoin-wireshark-dissector<br />
<br />
==References==<br />
<references /><br />
<br />
[[zh-cn:协议说明]]<br />
[[Category:Technical]]<br />
[[Category:Developer]]<br />
<br />
{{Bitcoin Core documentation}}</div>Tonikthttps://en.bitcoin.it/w/index.php?title=Gocoin&diff=56852Gocoin2015-06-05T14:52:00Z<p>Tonikt: new homepage at gocoin.pl</p>
<hr />
<div>An open-source Bitcoin solution written in Go language (golang).<br />
It can be built for every platform that has a working Go compiler.<br />
It uses a proprietary license, though is free to use for non-commercial purposes.<br />
<br />
==Architecture==<br />
<br />
Gocoin's architecture is quite different from the reference implementation (of the Satoshi client).<br />
<br />
===Libraries===<br />
<br />
====btc / chain / script ====<br />
The core of the software is a library that essentially provides the blockchain protocol parser. That includes script parsing, ECDSA signature verification, but also things like address encoding, parsing of canonical signatures or extracting hashes that need to be signed for specific inputs of a given transaction.<br />
<br />
It is a relatively big library, that contains many useful bitcoin function.<br />
<br />
Inside the package, there is also a blocks persistent storage database (blockdb.go) - it is just a simple plain storage (that can only grow), with an index. It uses snappy compression, allowing to save about 30% of the disk space.<br />
<br />
====qdb====<br />
The core library interfaces directly with a UTXO database backed.<br />
For this purpose Gocoin uses its own database engine, that has been designed to deal with the specific characteristics of bitcoin's UTXO database. <br />
<br />
====secp256k1====<br />
To speed up the Elliptic Curve operations [https://github.com/bitcoin/secp256k1 the secp256k1 library by sipa] has been ported to Go.<br />
<br />
===Online client===<br />
The online client is a kind of a server software (or a peer-to-peer node) that is meant to be running all the time.<br />
<br />
It handles the network related communication, feeds the core lib with new incoming blockchain data, monitors balances on the wallets' addresses, manages transaction memory pool and the peers database. It also provides an interactive user interface.<br />
<br />
===Offline wallet===<br />
The wallet application is responsible for creating private keys (from a seed password) and for signing transactions with them.<br />
It can also sign text messages with private keys and decode raw transactions.<br />
<br />
Unlike the client, the wallet is not an app that is meant te be running continuously. <br />
A user runs it with the requested task - the wallet does the job and exits (back to the command prompt).<br />
<br />
===Blockchain downloader===<br />
For optimized initial blockchain download, Gocoin has a dedicated application called '''downloader'''.<br />
<br />
Among other optimizations, the downloader allows a user to skip verification of all the blocks up to a certain one that he defines as trusted. This can speed up the bootstrap process significantly (e.g. from days to hours).<br />
<br />
After it finishes downloading of all the blocks, it will exit automatically. In that moment the client should be started and it will keep up with all the new blocks, that will appear in the network.<br />
<br />
===Other tools===<br />
There is also a set of more and less useful tools (''github.com/piotrnar/gocoin/tools'') that are an integral part of the Gocoin bitcoin software.<br />
<br />
For instance '''btcversig''' can verify a validity of a bitcoin signature - it is the substitute of the reference client's '''verifymessage''' RPC-API.<br />
<br />
The tool '''type2determ''' can, at the other hand, calculate Type-2 deterministic addresses, without a need to access the wallet (the private keys).<br />
<br />
<br />
==Features==<br />
<br />
Gocoin has a several unique features, that distinguish it from the original bitcoin client.<br />
===Node / Client===<br />
* All the unspent outputs are kept in memory, which makes switching between different wallets, as well as checking a balance of any address, relatively fast (few seconds max).<br />
* Allows a user to limit the upload and download network bandwidth used by the client.<br />
* Can be monitored and controlled through a web interface (from a web browser).<br />
* Works with its own implementation of a cold storage wallet.<br />
* Web interface allows a user to create raw transactions from specific inputs ([[Coin Control]]), as well as multisig transactions ([[P2SH]])<br />
* The blocks are stored on the disk in a compressed form (using [https://code.google.com/p/snappy/ snappy] compression) which saves 20-30% of space.<br />
* Supports monitoring and fetching balance of own stealth addresses (the ones implemented in Dark Wallet)<br />
<br />
===Wallet===<br />
* For security reasons, it is supposed to be used with a PC that has never been (and will never be) connected to a network.<br />
* The wallet is deterministic and a seed-password based. As long as you can remember the password, there is no need for any backups.<br />
* Additionally it can import private keys from an existing bitcoin wallet (must be in [[Private key#Base 58 Wallet Import format | Base 58 Wallet Import format]] format).<br />
* Has very low hardware requirements. Can be run on i.e. Raspberry Pi<br />
* Can generate [https://bitcointalk.org/index.php?topic=19137.0 Type-2] deterministic keys/addresses<br />
* Supports (partial) signing of [[P2SH]] multisig transactions (the ones that use [[Script#Crypto | OP_CHECKMULTISIG opcode]]).<br />
* Supports spending to stealth addresses as implemented in Dark Wallet<br />
<br />
===Node-less mode===<br />
It is possible to use Gocoin's wallet, without a need to have a running client node, which may come handy since the node requires quite a decent hardware and the block chain takes a lot of time for the initial download.<br />
<br />
In such a case the required balance files are fetched with a tool called '''balio''', from a popular block explorer '''blockr.io'''<br />
<br />
''Note: using this tool you will not be able to monitor balance on your stealth addresses.''<br />
<br />
==Requirements==<br />
===Client===<br />
Requires 64-bit platform and at least 4GB of system memory.<br />
<br />
The file system that stores the blockchain data must be able to handle files larger than 4GB.<br />
<br />
===Wallet===<br />
The wallet app has very little hardware requirements. As long as you can build it for a specific architecture, it should work there.<br />
<br />
Gocoin wallet has been even used on Raspberry Pi model A.<br />
<br />
For security reasons it is strongly recommended to run the wallet on an encrypted file system, with an encrypted swap file.<br />
<br />
==Limitations==<br />
* No GUI, though the online node has web interface<br />
* No RPC API<br />
* No IPv6<br />
* No UPnP<br />
* No support for non-confirmed transactions (they are invisible in the balance)<br />
* No support for [[Protocol_specification#filterload, filteradd, filterclear, merkleblock | bloom filters]] protocol ([[BIP 0037]]) and the [[Protocol_specification#mempool | mempool]] command<br />
* No routing of [[Protocol_specification#alert | alert]] messages<br />
* No support for multisig stealth addresses (yet)<br />
<br />
==History==<br />
<br />
Gocoin was written by a single person for a private purposes.<br />
<br />
The software's first public release was announced in May 2013 on Bitcointalk forum.<ref>https://bitcointalk.org/index.php?topic=199306.0</ref><br />
Ever since then, the software has been actively maintained and further developed, being armed with new features, further optimized and cleaned up from issues.<br />
<br />
It happened twice that the client wasn't able to catch up with the blockchain, because of the implementation difference of the chain parsing protocol that was causing it to reject a block (transaction) that the reference implementation would accept. In both cases the issue was fixed within single days. The fist case happened in July 2013 and the fix was introduced in version 0.5.7. The second time was in March 2014 - the fix came with release 0.9.3.<br />
<br />
==External Links==<br />
<br />
* [http://gocoin.pl Homepage]<br />
* [https://github.com/piotrnar/gocoin Github repo]<br />
* [https://bitcointalk.org/index.php?topic=199306.0 Bitcointalk forum topic]<br />
<br />
==References==<br />
<references /><br />
<br />
[[Category:Software]]<br />
[[Category:Clients]]<br />
[[Category:Open Source]]<br />
[[Category:Wallets]]<br />
[[Category:Google Go]]</div>Tonikthttps://en.bitcoin.it/w/index.php?title=Gocoin&diff=47810Gocoin2014-05-31T21:13:50Z<p>Tonikt: /* Wallet */</p>
<hr />
<div>An open-source Bitcoin solution written in Go language (golang).<br />
It can be built for every platform that has a working Go compiler.<br />
It uses a proprietary license, though is free to use for non-commercial purposes.<br />
<br />
==Architecture==<br />
<br />
Gocoin's architecture is quite different from the reference implementation (of the Satoshi client).<br />
<br />
===Libraries===<br />
<br />
====btc / chain / script ====<br />
The core of the software is a library that essentially provides the blockchain protocol parser. That includes script parsing, ECDSA signature verification, but also things like address encoding, parsing of canonical signatures or extracting hashes that need to be signed for specific inputs of a given transaction.<br />
<br />
It is a relatively big library, that contains many useful bitcoin function.<br />
<br />
Inside the package, there is also a blocks persistent storage database (blockdb.go) - it is just a simple plain storage (that can only grow), with an index. It uses snappy compression, allowing to save about 30% of the disk space.<br />
<br />
====qdb====<br />
The core library interfaces directly with a UTXO database backed.<br />
For this purpose Gocoin uses its own database engine, that has been designed to deal with the specific characteristics of bitcoin's UTXO database. <br />
<br />
====secp256k1====<br />
To speed up the Elliptic Curve operations [https://github.com/bitcoin/secp256k1 the secp256k1 library by sipa] has been ported to Go.<br />
<br />
===Online client===<br />
The online client is a kind of a server software (or a peer-to-peer node) that is meant to be running all the time.<br />
<br />
It handles the network related communication, feeds the core lib with new incoming blockchain data, monitors balances on the wallets' addresses, manages transaction memory pool and the peers database. It also provides an interactive user interface.<br />
<br />
===Offline wallet===<br />
The wallet application is responsible for creating private keys (from a seed password) and for signing transactions with them.<br />
It can also sign text messages with private keys and decode raw transactions.<br />
<br />
Unlike the client, the wallet is not an app that is meant te be running continuously. <br />
A user runs it with the requested task - the wallet does the job and exits (back to the command prompt).<br />
<br />
===Blockchain downloader===<br />
For optimized initial blockchain download, Gocoin has a dedicated application called '''downloader'''.<br />
<br />
Among other optimizations, the downloader allows a user to skip verification of all the blocks up to a certain one that he defines as trusted. This can speed up the bootstrap process significantly (e.g. from days to hours).<br />
<br />
After it finishes downloading of all the blocks, it will exit automatically. In that moment the client should be started and it will keep up with all the new blocks, that will appear in the network.<br />
<br />
===Other tools===<br />
There is also a set of more and less useful tools (''github.com/piotrnar/gocoin/tools'') that are an integral part of the Gocoin bitcoin software.<br />
<br />
For instance '''btcversig''' can verify a validity of a bitcoin signature - it is the substitute of the reference client's '''verifymessage''' RPC-API.<br />
<br />
The tool '''type2determ''' can, at the other hand, calculate Type-2 deterministic addresses, without a need to access the wallet (the private keys).<br />
<br />
<br />
==Features==<br />
<br />
Gocoin has a several unique features, that distinguish it from the original bitcoin client.<br />
===Node / Client===<br />
* All the unspent outputs are kept in memory, which makes switching between different wallets, as well as checking a balance of any address, relatively fast (few seconds max).<br />
* Allows a user to limit the upload and download network bandwidth used by the client.<br />
* Can be monitored and controlled through a web interface (from a web browser).<br />
* Works with its own implementation of a cold storage wallet.<br />
* Web interface allows a user to create raw transactions from specific inputs ([[Coin Control]]), as well as multisig transactions ([[P2SH]])<br />
* The blocks are stored on the disk in a compressed form (using [https://code.google.com/p/snappy/ snappy] compression) which saves 20-30% of space.<br />
* Supports monitoring and fetching balance of own stealth addresses (the ones implemented in Dark Wallet)<br />
<br />
===Wallet===<br />
* For security reasons, it is supposed to be used with a PC that has never been (and will never be) connected to a network.<br />
* The wallet is deterministic and a seed-password based. As long as you can remember the password, there is no need for any backups.<br />
* Additionally it can import private keys from an existing bitcoin wallet (must be in [[Private key#Base 58 Wallet Import format | Base 58 Wallet Import format]] format).<br />
* Has very low hardware requirements. Can be run on i.e. Raspberry Pi<br />
* Can generate [https://bitcointalk.org/index.php?topic=19137.0 Type-2] deterministic keys/addresses<br />
* Supports (partial) signing of [[P2SH]] multisig transactions (the ones that use [[Script#Crypto | OP_CHECKMULTISIG opcode]]).<br />
* Supports spending to stealth addresses as implemented in Dark Wallet<br />
* Supports Litecoin<br />
<br />
===Node-less mode===<br />
It is possible to use Gocoin's wallet, without a need to have a running client node, which may come handy since the node requires quite a decent hardware and the block chain takes a lot of time for the initial download.<br />
<br />
In such a case the required balance files are fetched with a tool called '''balio''', from a popular block explorer '''blockr.io'''<br />
<br />
''Note: using this tool you will not be able to monitor balance on your stealth addresses.''<br />
<br />
==Requirements==<br />
===Client===<br />
Requires 64-bit platform and at least 4GB of system memory.<br />
<br />
The file system that stores the blockchain data must be able to handle files larger than 4GB.<br />
<br />
===Wallet===<br />
The wallet app has very little hardware requirements. As long as you can build it for a specific architecture, it should work there.<br />
<br />
Gocoin wallet has been even used on Raspberry Pi model A.<br />
<br />
For security reasons it is strongly recommended to run the wallet on an encrypted file system, with an encrypted swap file.<br />
<br />
==Limitations==<br />
* No GUI, though the online node has web interface<br />
* No RPC API<br />
* No IPv6<br />
* No UPnP<br />
* No support for non-confirmed transactions (they are invisible in the balance)<br />
* No support for [[Protocol_specification#filterload, filteradd, filterclear, merkleblock | bloom filters]] protocol ([[BIP 0037]]) and the [[Protocol_specification#mempool | mempool]] command<br />
* No routing of [[Protocol_specification#alert | alert]] messages<br />
* No support for multisig stealth addresses (yet)<br />
<br />
==History==<br />
<br />
Gocoin was written by a single person for a private purposes.<br />
<br />
The software's first public release was announced in May 2013 on Bitcointalk forum.<ref>https://bitcointalk.org/index.php?topic=199306.0</ref><br />
Ever since then, the software has been actively maintained and further developed, being armed with new features, further optimized and cleaned up from issues.<br />
<br />
It happened twice that the client wasn't able to catch up with the blockchain, because of the implementation difference of the chain parsing protocol that was causing it to reject a block (transaction) that the reference implementation would accept. In both cases the issue was fixed within single days. The fist case happened in July 2013 and the fix was introduced in version 0.5.7. The second time was in March 2014 - the fix came with release 0.9.3.<br />
<br />
==External Links==<br />
<br />
* [http://www.assets-otc.com/gocoin Homepage]<br />
* [https://github.com/piotrnar/gocoin Github repo]<br />
* [https://bitcointalk.org/index.php?topic=199306.0 Bitcointalk forum topic]<br />
<br />
==References==<br />
<references /><br />
<br />
[[Category:Software]]<br />
[[Category:Clients]]<br />
[[Category:Open Source]]<br />
[[Category:Wallets]]</div>Tonikthttps://en.bitcoin.it/w/index.php?title=Gocoin&diff=47809Gocoin2014-05-31T21:12:50Z<p>Tonikt: /* Node / Client */</p>
<hr />
<div>An open-source Bitcoin solution written in Go language (golang).<br />
It can be built for every platform that has a working Go compiler.<br />
It uses a proprietary license, though is free to use for non-commercial purposes.<br />
<br />
==Architecture==<br />
<br />
Gocoin's architecture is quite different from the reference implementation (of the Satoshi client).<br />
<br />
===Libraries===<br />
<br />
====btc / chain / script ====<br />
The core of the software is a library that essentially provides the blockchain protocol parser. That includes script parsing, ECDSA signature verification, but also things like address encoding, parsing of canonical signatures or extracting hashes that need to be signed for specific inputs of a given transaction.<br />
<br />
It is a relatively big library, that contains many useful bitcoin function.<br />
<br />
Inside the package, there is also a blocks persistent storage database (blockdb.go) - it is just a simple plain storage (that can only grow), with an index. It uses snappy compression, allowing to save about 30% of the disk space.<br />
<br />
====qdb====<br />
The core library interfaces directly with a UTXO database backed.<br />
For this purpose Gocoin uses its own database engine, that has been designed to deal with the specific characteristics of bitcoin's UTXO database. <br />
<br />
====secp256k1====<br />
To speed up the Elliptic Curve operations [https://github.com/bitcoin/secp256k1 the secp256k1 library by sipa] has been ported to Go.<br />
<br />
===Online client===<br />
The online client is a kind of a server software (or a peer-to-peer node) that is meant to be running all the time.<br />
<br />
It handles the network related communication, feeds the core lib with new incoming blockchain data, monitors balances on the wallets' addresses, manages transaction memory pool and the peers database. It also provides an interactive user interface.<br />
<br />
===Offline wallet===<br />
The wallet application is responsible for creating private keys (from a seed password) and for signing transactions with them.<br />
It can also sign text messages with private keys and decode raw transactions.<br />
<br />
Unlike the client, the wallet is not an app that is meant te be running continuously. <br />
A user runs it with the requested task - the wallet does the job and exits (back to the command prompt).<br />
<br />
===Blockchain downloader===<br />
For optimized initial blockchain download, Gocoin has a dedicated application called '''downloader'''.<br />
<br />
Among other optimizations, the downloader allows a user to skip verification of all the blocks up to a certain one that he defines as trusted. This can speed up the bootstrap process significantly (e.g. from days to hours).<br />
<br />
After it finishes downloading of all the blocks, it will exit automatically. In that moment the client should be started and it will keep up with all the new blocks, that will appear in the network.<br />
<br />
===Other tools===<br />
There is also a set of more and less useful tools (''github.com/piotrnar/gocoin/tools'') that are an integral part of the Gocoin bitcoin software.<br />
<br />
For instance '''btcversig''' can verify a validity of a bitcoin signature - it is the substitute of the reference client's '''verifymessage''' RPC-API.<br />
<br />
The tool '''type2determ''' can, at the other hand, calculate Type-2 deterministic addresses, without a need to access the wallet (the private keys).<br />
<br />
<br />
==Features==<br />
<br />
Gocoin has a several unique features, that distinguish it from the original bitcoin client.<br />
===Node / Client===<br />
* All the unspent outputs are kept in memory, which makes switching between different wallets, as well as checking a balance of any address, relatively fast (few seconds max).<br />
* Allows a user to limit the upload and download network bandwidth used by the client.<br />
* Can be monitored and controlled through a web interface (from a web browser).<br />
* Works with its own implementation of a cold storage wallet.<br />
* Web interface allows a user to create raw transactions from specific inputs ([[Coin Control]]), as well as multisig transactions ([[P2SH]])<br />
* The blocks are stored on the disk in a compressed form (using [https://code.google.com/p/snappy/ snappy] compression) which saves 20-30% of space.<br />
* Supports monitoring and fetching balance of own stealth addresses (the ones implemented in Dark Wallet)<br />
<br />
===Wallet===<br />
* For security reasons, it is supposed to be used with a PC that has never been (and will never be) connected to a network.<br />
* The wallet is deterministic and a seed-password based. As long as you can remember the password, there is no need for any backups.<br />
* Additionally it can import private keys from an existing bitcoin wallet (must be in [[Private key#Base 58 Wallet Import format | Base 58 Wallet Import format]] format).<br />
* Has very low hardware requirements. Can be run on i.e. Raspberry Pi<br />
* Can generate [https://bitcointalk.org/index.php?topic=19137.0 Type-2] deterministic keys/addresses<br />
* Supports signing of [[P2SH]] multisig transactions (the ones that use [[Script#Crypto | OP_CHECKMULTISIG opcode]]).<br />
* Supports spending to stealth addresses as implemented in Dark Wallet<br />
* Supports Litecoin<br />
<br />
===Node-less mode===<br />
It is possible to use Gocoin's wallet, without a need to have a running client node, which may come handy since the node requires quite a decent hardware and the block chain takes a lot of time for the initial download.<br />
<br />
In such a case the required balance files are fetched with a tool called '''balio''', from a popular block explorer '''blockr.io'''<br />
<br />
''Note: using this tool you will not be able to monitor balance on your stealth addresses.''<br />
<br />
==Requirements==<br />
===Client===<br />
Requires 64-bit platform and at least 4GB of system memory.<br />
<br />
The file system that stores the blockchain data must be able to handle files larger than 4GB.<br />
<br />
===Wallet===<br />
The wallet app has very little hardware requirements. As long as you can build it for a specific architecture, it should work there.<br />
<br />
Gocoin wallet has been even used on Raspberry Pi model A.<br />
<br />
For security reasons it is strongly recommended to run the wallet on an encrypted file system, with an encrypted swap file.<br />
<br />
==Limitations==<br />
* No GUI, though the online node has web interface<br />
* No RPC API<br />
* No IPv6<br />
* No UPnP<br />
* No support for non-confirmed transactions (they are invisible in the balance)<br />
* No support for [[Protocol_specification#filterload, filteradd, filterclear, merkleblock | bloom filters]] protocol ([[BIP 0037]]) and the [[Protocol_specification#mempool | mempool]] command<br />
* No routing of [[Protocol_specification#alert | alert]] messages<br />
* No support for multisig stealth addresses (yet)<br />
<br />
==History==<br />
<br />
Gocoin was written by a single person for a private purposes.<br />
<br />
The software's first public release was announced in May 2013 on Bitcointalk forum.<ref>https://bitcointalk.org/index.php?topic=199306.0</ref><br />
Ever since then, the software has been actively maintained and further developed, being armed with new features, further optimized and cleaned up from issues.<br />
<br />
It happened twice that the client wasn't able to catch up with the blockchain, because of the implementation difference of the chain parsing protocol that was causing it to reject a block (transaction) that the reference implementation would accept. In both cases the issue was fixed within single days. The fist case happened in July 2013 and the fix was introduced in version 0.5.7. The second time was in March 2014 - the fix came with release 0.9.3.<br />
<br />
==External Links==<br />
<br />
* [http://www.assets-otc.com/gocoin Homepage]<br />
* [https://github.com/piotrnar/gocoin Github repo]<br />
* [https://bitcointalk.org/index.php?topic=199306.0 Bitcointalk forum topic]<br />
<br />
==References==<br />
<references /><br />
<br />
[[Category:Software]]<br />
[[Category:Clients]]<br />
[[Category:Open Source]]<br />
[[Category:Wallets]]</div>Tonikthttps://en.bitcoin.it/w/index.php?title=Gocoin&diff=47808Gocoin2014-05-31T21:10:53Z<p>Tonikt: /* btc */</p>
<hr />
<div>An open-source Bitcoin solution written in Go language (golang).<br />
It can be built for every platform that has a working Go compiler.<br />
It uses a proprietary license, though is free to use for non-commercial purposes.<br />
<br />
==Architecture==<br />
<br />
Gocoin's architecture is quite different from the reference implementation (of the Satoshi client).<br />
<br />
===Libraries===<br />
<br />
====btc / chain / script ====<br />
The core of the software is a library that essentially provides the blockchain protocol parser. That includes script parsing, ECDSA signature verification, but also things like address encoding, parsing of canonical signatures or extracting hashes that need to be signed for specific inputs of a given transaction.<br />
<br />
It is a relatively big library, that contains many useful bitcoin function.<br />
<br />
Inside the package, there is also a blocks persistent storage database (blockdb.go) - it is just a simple plain storage (that can only grow), with an index. It uses snappy compression, allowing to save about 30% of the disk space.<br />
<br />
====qdb====<br />
The core library interfaces directly with a UTXO database backed.<br />
For this purpose Gocoin uses its own database engine, that has been designed to deal with the specific characteristics of bitcoin's UTXO database. <br />
<br />
====secp256k1====<br />
To speed up the Elliptic Curve operations [https://github.com/bitcoin/secp256k1 the secp256k1 library by sipa] has been ported to Go.<br />
<br />
===Online client===<br />
The online client is a kind of a server software (or a peer-to-peer node) that is meant to be running all the time.<br />
<br />
It handles the network related communication, feeds the core lib with new incoming blockchain data, monitors balances on the wallets' addresses, manages transaction memory pool and the peers database. It also provides an interactive user interface.<br />
<br />
===Offline wallet===<br />
The wallet application is responsible for creating private keys (from a seed password) and for signing transactions with them.<br />
It can also sign text messages with private keys and decode raw transactions.<br />
<br />
Unlike the client, the wallet is not an app that is meant te be running continuously. <br />
A user runs it with the requested task - the wallet does the job and exits (back to the command prompt).<br />
<br />
===Blockchain downloader===<br />
For optimized initial blockchain download, Gocoin has a dedicated application called '''downloader'''.<br />
<br />
Among other optimizations, the downloader allows a user to skip verification of all the blocks up to a certain one that he defines as trusted. This can speed up the bootstrap process significantly (e.g. from days to hours).<br />
<br />
After it finishes downloading of all the blocks, it will exit automatically. In that moment the client should be started and it will keep up with all the new blocks, that will appear in the network.<br />
<br />
===Other tools===<br />
There is also a set of more and less useful tools (''github.com/piotrnar/gocoin/tools'') that are an integral part of the Gocoin bitcoin software.<br />
<br />
For instance '''btcversig''' can verify a validity of a bitcoin signature - it is the substitute of the reference client's '''verifymessage''' RPC-API.<br />
<br />
The tool '''type2determ''' can, at the other hand, calculate Type-2 deterministic addresses, without a need to access the wallet (the private keys).<br />
<br />
<br />
==Features==<br />
<br />
Gocoin has a several unique features, that distinguish it from the original bitcoin client.<br />
===Node / Client===<br />
* All the unspent outputs are kept in memory, which makes switching between different wallets, as well as checking a balance of any address, relatively fast (few seconds max).<br />
* Allows a user to limit the upload and download network bandwidth used by the client.<br />
* Can be monitored and controlled through a web interface (from a web browser).<br />
* Works with its own implementation of a cold storage wallet.<br />
* Web interface allows a user to create raw transactions from specific inputs ([[Coin Control]]), as well as multisig transactions ([[P2SH]])<br />
* The blocks are stored on the disk in a compressed form (using [https://code.google.com/p/snappy/ snappy] compression) which saves about 30% of space.<br />
* Supports monitoring and fetching balance of own stealth addresses (the ones implemented in Dark Wallet)<br />
<br />
===Wallet===<br />
* For security reasons, it is supposed to be used with a PC that has never been (and will never be) connected to a network.<br />
* The wallet is deterministic and a seed-password based. As long as you can remember the password, there is no need for any backups.<br />
* Additionally it can import private keys from an existing bitcoin wallet (must be in [[Private key#Base 58 Wallet Import format | Base 58 Wallet Import format]] format).<br />
* Has very low hardware requirements. Can be run on i.e. Raspberry Pi<br />
* Can generate [https://bitcointalk.org/index.php?topic=19137.0 Type-2] deterministic keys/addresses<br />
* Supports signing of [[P2SH]] multisig transactions (the ones that use [[Script#Crypto | OP_CHECKMULTISIG opcode]]).<br />
* Supports spending to stealth addresses as implemented in Dark Wallet<br />
* Supports Litecoin<br />
<br />
===Node-less mode===<br />
It is possible to use Gocoin's wallet, without a need to have a running client node, which may come handy since the node requires quite a decent hardware and the block chain takes a lot of time for the initial download.<br />
<br />
In such a case the required balance files are fetched with a tool called '''balio''', from a popular block explorer '''blockr.io'''<br />
<br />
''Note: using this tool you will not be able to monitor balance on your stealth addresses.''<br />
<br />
==Requirements==<br />
===Client===<br />
Requires 64-bit platform and at least 4GB of system memory.<br />
<br />
The file system that stores the blockchain data must be able to handle files larger than 4GB.<br />
<br />
===Wallet===<br />
The wallet app has very little hardware requirements. As long as you can build it for a specific architecture, it should work there.<br />
<br />
Gocoin wallet has been even used on Raspberry Pi model A.<br />
<br />
For security reasons it is strongly recommended to run the wallet on an encrypted file system, with an encrypted swap file.<br />
<br />
==Limitations==<br />
* No GUI, though the online node has web interface<br />
* No RPC API<br />
* No IPv6<br />
* No UPnP<br />
* No support for non-confirmed transactions (they are invisible in the balance)<br />
* No support for [[Protocol_specification#filterload, filteradd, filterclear, merkleblock | bloom filters]] protocol ([[BIP 0037]]) and the [[Protocol_specification#mempool | mempool]] command<br />
* No routing of [[Protocol_specification#alert | alert]] messages<br />
* No support for multisig stealth addresses (yet)<br />
<br />
==History==<br />
<br />
Gocoin was written by a single person for a private purposes.<br />
<br />
The software's first public release was announced in May 2013 on Bitcointalk forum.<ref>https://bitcointalk.org/index.php?topic=199306.0</ref><br />
Ever since then, the software has been actively maintained and further developed, being armed with new features, further optimized and cleaned up from issues.<br />
<br />
It happened twice that the client wasn't able to catch up with the blockchain, because of the implementation difference of the chain parsing protocol that was causing it to reject a block (transaction) that the reference implementation would accept. In both cases the issue was fixed within single days. The fist case happened in July 2013 and the fix was introduced in version 0.5.7. The second time was in March 2014 - the fix came with release 0.9.3.<br />
<br />
==External Links==<br />
<br />
* [http://www.assets-otc.com/gocoin Homepage]<br />
* [https://github.com/piotrnar/gocoin Github repo]<br />
* [https://bitcointalk.org/index.php?topic=199306.0 Bitcointalk forum topic]<br />
<br />
==References==<br />
<references /><br />
<br />
[[Category:Software]]<br />
[[Category:Clients]]<br />
[[Category:Open Source]]<br />
[[Category:Wallets]]</div>Tonikthttps://en.bitcoin.it/w/index.php?title=Gocoin&diff=47807Gocoin2014-05-31T21:08:59Z<p>Tonikt: /* Wallet */</p>
<hr />
<div>An open-source Bitcoin solution written in Go language (golang).<br />
It can be built for every platform that has a working Go compiler.<br />
It uses a proprietary license, though is free to use for non-commercial purposes.<br />
<br />
==Architecture==<br />
<br />
Gocoin's architecture is quite different from the reference implementation (of the Satoshi client).<br />
<br />
===Libraries===<br />
<br />
====btc====<br />
The core of the software is a library that essentially provides the blockchain protocol parser. That includes script parsing, ECDSA signature verification, but also things like address encoding, parsing of canonical signatures or extracting hashes that need to be signed for specific inputs of a given transaction.<br />
<br />
It is a relatively big library, that contains many useful bitcoin function.<br />
<br />
Inside the package, there is also a blocks persistent storage database (blockdb.go) - it is just a simple plain storage (that can only grow), with an index. It uses snappy compression, allowing to save about 30% of the disk space.<br />
<br />
====qdb====<br />
The core library interfaces directly with a UTXO database backed.<br />
For this purpose Gocoin uses its own database engine, that has been designed to deal with the specific characteristics of bitcoin's UTXO database. <br />
<br />
====secp256k1====<br />
To speed up the Elliptic Curve operations [https://github.com/bitcoin/secp256k1 the secp256k1 library by sipa] has been ported to Go.<br />
<br />
===Online client===<br />
The online client is a kind of a server software (or a peer-to-peer node) that is meant to be running all the time.<br />
<br />
It handles the network related communication, feeds the core lib with new incoming blockchain data, monitors balances on the wallets' addresses, manages transaction memory pool and the peers database. It also provides an interactive user interface.<br />
<br />
===Offline wallet===<br />
The wallet application is responsible for creating private keys (from a seed password) and for signing transactions with them.<br />
It can also sign text messages with private keys and decode raw transactions.<br />
<br />
Unlike the client, the wallet is not an app that is meant te be running continuously. <br />
A user runs it with the requested task - the wallet does the job and exits (back to the command prompt).<br />
<br />
===Blockchain downloader===<br />
For optimized initial blockchain download, Gocoin has a dedicated application called '''downloader'''.<br />
<br />
Among other optimizations, the downloader allows a user to skip verification of all the blocks up to a certain one that he defines as trusted. This can speed up the bootstrap process significantly (e.g. from days to hours).<br />
<br />
After it finishes downloading of all the blocks, it will exit automatically. In that moment the client should be started and it will keep up with all the new blocks, that will appear in the network.<br />
<br />
===Other tools===<br />
There is also a set of more and less useful tools (''github.com/piotrnar/gocoin/tools'') that are an integral part of the Gocoin bitcoin software.<br />
<br />
For instance '''btcversig''' can verify a validity of a bitcoin signature - it is the substitute of the reference client's '''verifymessage''' RPC-API.<br />
<br />
The tool '''type2determ''' can, at the other hand, calculate Type-2 deterministic addresses, without a need to access the wallet (the private keys).<br />
<br />
<br />
==Features==<br />
<br />
Gocoin has a several unique features, that distinguish it from the original bitcoin client.<br />
===Node / Client===<br />
* All the unspent outputs are kept in memory, which makes switching between different wallets, as well as checking a balance of any address, relatively fast (few seconds max).<br />
* Allows a user to limit the upload and download network bandwidth used by the client.<br />
* Can be monitored and controlled through a web interface (from a web browser).<br />
* Works with its own implementation of a cold storage wallet.<br />
* Web interface allows a user to create raw transactions from specific inputs ([[Coin Control]]), as well as multisig transactions ([[P2SH]])<br />
* The blocks are stored on the disk in a compressed form (using [https://code.google.com/p/snappy/ snappy] compression) which saves about 30% of space.<br />
* Supports monitoring and fetching balance of own stealth addresses (the ones implemented in Dark Wallet)<br />
<br />
===Wallet===<br />
* For security reasons, it is supposed to be used with a PC that has never been (and will never be) connected to a network.<br />
* The wallet is deterministic and a seed-password based. As long as you can remember the password, there is no need for any backups.<br />
* Additionally it can import private keys from an existing bitcoin wallet (must be in [[Private key#Base 58 Wallet Import format | Base 58 Wallet Import format]] format).<br />
* Has very low hardware requirements. Can be run on i.e. Raspberry Pi<br />
* Can generate [https://bitcointalk.org/index.php?topic=19137.0 Type-2] deterministic keys/addresses<br />
* Supports signing of [[P2SH]] multisig transactions (the ones that use [[Script#Crypto | OP_CHECKMULTISIG opcode]]).<br />
* Supports spending to stealth addresses as implemented in Dark Wallet<br />
* Supports Litecoin<br />
<br />
===Node-less mode===<br />
It is possible to use Gocoin's wallet, without a need to have a running client node, which may come handy since the node requires quite a decent hardware and the block chain takes a lot of time for the initial download.<br />
<br />
In such a case the required balance files are fetched with a tool called '''balio''', from a popular block explorer '''blockr.io'''<br />
<br />
''Note: using this tool you will not be able to monitor balance on your stealth addresses.''<br />
<br />
==Requirements==<br />
===Client===<br />
Requires 64-bit platform and at least 4GB of system memory.<br />
<br />
The file system that stores the blockchain data must be able to handle files larger than 4GB.<br />
<br />
===Wallet===<br />
The wallet app has very little hardware requirements. As long as you can build it for a specific architecture, it should work there.<br />
<br />
Gocoin wallet has been even used on Raspberry Pi model A.<br />
<br />
For security reasons it is strongly recommended to run the wallet on an encrypted file system, with an encrypted swap file.<br />
<br />
==Limitations==<br />
* No GUI, though the online node has web interface<br />
* No RPC API<br />
* No IPv6<br />
* No UPnP<br />
* No support for non-confirmed transactions (they are invisible in the balance)<br />
* No support for [[Protocol_specification#filterload, filteradd, filterclear, merkleblock | bloom filters]] protocol ([[BIP 0037]]) and the [[Protocol_specification#mempool | mempool]] command<br />
* No routing of [[Protocol_specification#alert | alert]] messages<br />
* No support for multisig stealth addresses (yet)<br />
<br />
==History==<br />
<br />
Gocoin was written by a single person for a private purposes.<br />
<br />
The software's first public release was announced in May 2013 on Bitcointalk forum.<ref>https://bitcointalk.org/index.php?topic=199306.0</ref><br />
Ever since then, the software has been actively maintained and further developed, being armed with new features, further optimized and cleaned up from issues.<br />
<br />
It happened twice that the client wasn't able to catch up with the blockchain, because of the implementation difference of the chain parsing protocol that was causing it to reject a block (transaction) that the reference implementation would accept. In both cases the issue was fixed within single days. The fist case happened in July 2013 and the fix was introduced in version 0.5.7. The second time was in March 2014 - the fix came with release 0.9.3.<br />
<br />
==External Links==<br />
<br />
* [http://www.assets-otc.com/gocoin Homepage]<br />
* [https://github.com/piotrnar/gocoin Github repo]<br />
* [https://bitcointalk.org/index.php?topic=199306.0 Bitcointalk forum topic]<br />
<br />
==References==<br />
<references /><br />
<br />
[[Category:Software]]<br />
[[Category:Clients]]<br />
[[Category:Open Source]]<br />
[[Category:Wallets]]</div>Tonikthttps://en.bitcoin.it/w/index.php?title=Gocoin&diff=47806Gocoin2014-05-31T21:08:03Z<p>Tonikt: /* Requirements */</p>
<hr />
<div>An open-source Bitcoin solution written in Go language (golang).<br />
It can be built for every platform that has a working Go compiler.<br />
It uses a proprietary license, though is free to use for non-commercial purposes.<br />
<br />
==Architecture==<br />
<br />
Gocoin's architecture is quite different from the reference implementation (of the Satoshi client).<br />
<br />
===Libraries===<br />
<br />
====btc====<br />
The core of the software is a library that essentially provides the blockchain protocol parser. That includes script parsing, ECDSA signature verification, but also things like address encoding, parsing of canonical signatures or extracting hashes that need to be signed for specific inputs of a given transaction.<br />
<br />
It is a relatively big library, that contains many useful bitcoin function.<br />
<br />
Inside the package, there is also a blocks persistent storage database (blockdb.go) - it is just a simple plain storage (that can only grow), with an index. It uses snappy compression, allowing to save about 30% of the disk space.<br />
<br />
====qdb====<br />
The core library interfaces directly with a UTXO database backed.<br />
For this purpose Gocoin uses its own database engine, that has been designed to deal with the specific characteristics of bitcoin's UTXO database. <br />
<br />
====secp256k1====<br />
To speed up the Elliptic Curve operations [https://github.com/bitcoin/secp256k1 the secp256k1 library by sipa] has been ported to Go.<br />
<br />
===Online client===<br />
The online client is a kind of a server software (or a peer-to-peer node) that is meant to be running all the time.<br />
<br />
It handles the network related communication, feeds the core lib with new incoming blockchain data, monitors balances on the wallets' addresses, manages transaction memory pool and the peers database. It also provides an interactive user interface.<br />
<br />
===Offline wallet===<br />
The wallet application is responsible for creating private keys (from a seed password) and for signing transactions with them.<br />
It can also sign text messages with private keys and decode raw transactions.<br />
<br />
Unlike the client, the wallet is not an app that is meant te be running continuously. <br />
A user runs it with the requested task - the wallet does the job and exits (back to the command prompt).<br />
<br />
===Blockchain downloader===<br />
For optimized initial blockchain download, Gocoin has a dedicated application called '''downloader'''.<br />
<br />
Among other optimizations, the downloader allows a user to skip verification of all the blocks up to a certain one that he defines as trusted. This can speed up the bootstrap process significantly (e.g. from days to hours).<br />
<br />
After it finishes downloading of all the blocks, it will exit automatically. In that moment the client should be started and it will keep up with all the new blocks, that will appear in the network.<br />
<br />
===Other tools===<br />
There is also a set of more and less useful tools (''github.com/piotrnar/gocoin/tools'') that are an integral part of the Gocoin bitcoin software.<br />
<br />
For instance '''btcversig''' can verify a validity of a bitcoin signature - it is the substitute of the reference client's '''verifymessage''' RPC-API.<br />
<br />
The tool '''type2determ''' can, at the other hand, calculate Type-2 deterministic addresses, without a need to access the wallet (the private keys).<br />
<br />
<br />
==Features==<br />
<br />
Gocoin has a several unique features, that distinguish it from the original bitcoin client.<br />
===Node / Client===<br />
* All the unspent outputs are kept in memory, which makes switching between different wallets, as well as checking a balance of any address, relatively fast (few seconds max).<br />
* Allows a user to limit the upload and download network bandwidth used by the client.<br />
* Can be monitored and controlled through a web interface (from a web browser).<br />
* Works with its own implementation of a cold storage wallet.<br />
* Web interface allows a user to create raw transactions from specific inputs ([[Coin Control]]), as well as multisig transactions ([[P2SH]])<br />
* The blocks are stored on the disk in a compressed form (using [https://code.google.com/p/snappy/ snappy] compression) which saves about 30% of space.<br />
* Supports monitoring and fetching balance of own stealth addresses (the ones implemented in Dark Wallet)<br />
<br />
===Wallet===<br />
* For security reasons, it is supposed to be used with a PC that has never been (and will never be) connected to a network.<br />
* The wallet is deterministic and a seed-password based. As long as you can remember the password, there is no need for any backups.<br />
* Additionally it can import private keys from an existing bitcoin wallet (must be in [[Private key#Base 58 Wallet Import format | Base 58 Wallet Import format]] format).<br />
* Has very low hardware requirements. Can be run on i.e. Raspberry Pi<br />
* Can generate [https://bitcointalk.org/index.php?topic=19137.0 Type-2] deterministic keys/addresses<br />
* Supports signing of [[P2SH]] multisig transactions (the ones that use [[Script#Crypto | OP_CHECKMULTISIG opcode]]).<br />
* Supports spending to stealth addresses as implemented in Dark Wallet<br />
* Supports Litecoin<br />
<br />
===Node-less mode===<br />
It is possible to use Gocoin's wallet, without a need to have a running client node, which may come handy since the node requires quite a decent hardware and the block chain takes a lot of time for the initial download.<br />
<br />
In such a case the required balance files are fetched with a tool called '''balio''', from a popular block explorer '''blockr.io'''<br />
<br />
''Note: using this tool you will not be able to monitor balance on your stealth addresses.''<br />
<br />
==Requirements==<br />
===Client===<br />
Requires 64-bit platform and at least 4GB of system memory.<br />
<br />
The file system that stores the blockchain data must be able to handle files larger than 4GB.<br />
<br />
===Wallet===<br />
The wallet app has very little hardware requirements. As long as you can build it for a specific architecture, it should work there.<br />
<br />
There is no knowledge of Gocoin wallet to be tested on platforms like Raspberry Pi, but theoretically there is no reason why it would not work there.<br />
<br />
For security reasons it is strongly recommended to run the wallet on an encrypted file system, with an encrypted swap file.<br />
<br />
==Limitations==<br />
* No GUI, though the online node has web interface<br />
* No RPC API<br />
* No IPv6<br />
* No UPnP<br />
* No support for non-confirmed transactions (they are invisible in the balance)<br />
* No support for [[Protocol_specification#filterload, filteradd, filterclear, merkleblock | bloom filters]] protocol ([[BIP 0037]]) and the [[Protocol_specification#mempool | mempool]] command<br />
* No routing of [[Protocol_specification#alert | alert]] messages<br />
* No support for multisig stealth addresses (yet)<br />
<br />
==History==<br />
<br />
Gocoin was written by a single person for a private purposes.<br />
<br />
The software's first public release was announced in May 2013 on Bitcointalk forum.<ref>https://bitcointalk.org/index.php?topic=199306.0</ref><br />
Ever since then, the software has been actively maintained and further developed, being armed with new features, further optimized and cleaned up from issues.<br />
<br />
It happened twice that the client wasn't able to catch up with the blockchain, because of the implementation difference of the chain parsing protocol that was causing it to reject a block (transaction) that the reference implementation would accept. In both cases the issue was fixed within single days. The fist case happened in July 2013 and the fix was introduced in version 0.5.7. The second time was in March 2014 - the fix came with release 0.9.3.<br />
<br />
==External Links==<br />
<br />
* [http://www.assets-otc.com/gocoin Homepage]<br />
* [https://github.com/piotrnar/gocoin Github repo]<br />
* [https://bitcointalk.org/index.php?topic=199306.0 Bitcointalk forum topic]<br />
<br />
==References==<br />
<references /><br />
<br />
[[Category:Software]]<br />
[[Category:Clients]]<br />
[[Category:Open Source]]<br />
[[Category:Wallets]]</div>Tonikthttps://en.bitcoin.it/w/index.php?title=Gocoin&diff=47805Gocoin2014-05-31T21:07:12Z<p>Tonikt: /* Node-less mode */</p>
<hr />
<div>An open-source Bitcoin solution written in Go language (golang).<br />
It can be built for every platform that has a working Go compiler.<br />
It uses a proprietary license, though is free to use for non-commercial purposes.<br />
<br />
==Architecture==<br />
<br />
Gocoin's architecture is quite different from the reference implementation (of the Satoshi client).<br />
<br />
===Libraries===<br />
<br />
====btc====<br />
The core of the software is a library that essentially provides the blockchain protocol parser. That includes script parsing, ECDSA signature verification, but also things like address encoding, parsing of canonical signatures or extracting hashes that need to be signed for specific inputs of a given transaction.<br />
<br />
It is a relatively big library, that contains many useful bitcoin function.<br />
<br />
Inside the package, there is also a blocks persistent storage database (blockdb.go) - it is just a simple plain storage (that can only grow), with an index. It uses snappy compression, allowing to save about 30% of the disk space.<br />
<br />
====qdb====<br />
The core library interfaces directly with a UTXO database backed.<br />
For this purpose Gocoin uses its own database engine, that has been designed to deal with the specific characteristics of bitcoin's UTXO database. <br />
<br />
====secp256k1====<br />
To speed up the Elliptic Curve operations [https://github.com/bitcoin/secp256k1 the secp256k1 library by sipa] has been ported to Go.<br />
<br />
===Online client===<br />
The online client is a kind of a server software (or a peer-to-peer node) that is meant to be running all the time.<br />
<br />
It handles the network related communication, feeds the core lib with new incoming blockchain data, monitors balances on the wallets' addresses, manages transaction memory pool and the peers database. It also provides an interactive user interface.<br />
<br />
===Offline wallet===<br />
The wallet application is responsible for creating private keys (from a seed password) and for signing transactions with them.<br />
It can also sign text messages with private keys and decode raw transactions.<br />
<br />
Unlike the client, the wallet is not an app that is meant te be running continuously. <br />
A user runs it with the requested task - the wallet does the job and exits (back to the command prompt).<br />
<br />
===Blockchain downloader===<br />
For optimized initial blockchain download, Gocoin has a dedicated application called '''downloader'''.<br />
<br />
Among other optimizations, the downloader allows a user to skip verification of all the blocks up to a certain one that he defines as trusted. This can speed up the bootstrap process significantly (e.g. from days to hours).<br />
<br />
After it finishes downloading of all the blocks, it will exit automatically. In that moment the client should be started and it will keep up with all the new blocks, that will appear in the network.<br />
<br />
===Other tools===<br />
There is also a set of more and less useful tools (''github.com/piotrnar/gocoin/tools'') that are an integral part of the Gocoin bitcoin software.<br />
<br />
For instance '''btcversig''' can verify a validity of a bitcoin signature - it is the substitute of the reference client's '''verifymessage''' RPC-API.<br />
<br />
The tool '''type2determ''' can, at the other hand, calculate Type-2 deterministic addresses, without a need to access the wallet (the private keys).<br />
<br />
<br />
==Features==<br />
<br />
Gocoin has a several unique features, that distinguish it from the original bitcoin client.<br />
===Node / Client===<br />
* All the unspent outputs are kept in memory, which makes switching between different wallets, as well as checking a balance of any address, relatively fast (few seconds max).<br />
* Allows a user to limit the upload and download network bandwidth used by the client.<br />
* Can be monitored and controlled through a web interface (from a web browser).<br />
* Works with its own implementation of a cold storage wallet.<br />
* Web interface allows a user to create raw transactions from specific inputs ([[Coin Control]]), as well as multisig transactions ([[P2SH]])<br />
* The blocks are stored on the disk in a compressed form (using [https://code.google.com/p/snappy/ snappy] compression) which saves about 30% of space.<br />
* Supports monitoring and fetching balance of own stealth addresses (the ones implemented in Dark Wallet)<br />
<br />
===Wallet===<br />
* For security reasons, it is supposed to be used with a PC that has never been (and will never be) connected to a network.<br />
* The wallet is deterministic and a seed-password based. As long as you can remember the password, there is no need for any backups.<br />
* Additionally it can import private keys from an existing bitcoin wallet (must be in [[Private key#Base 58 Wallet Import format | Base 58 Wallet Import format]] format).<br />
* Has very low hardware requirements. Can be run on i.e. Raspberry Pi<br />
* Can generate [https://bitcointalk.org/index.php?topic=19137.0 Type-2] deterministic keys/addresses<br />
* Supports signing of [[P2SH]] multisig transactions (the ones that use [[Script#Crypto | OP_CHECKMULTISIG opcode]]).<br />
* Supports spending to stealth addresses as implemented in Dark Wallet<br />
* Supports Litecoin<br />
<br />
===Node-less mode===<br />
It is possible to use Gocoin's wallet, without a need to have a running client node, which may come handy since the node requires quite a decent hardware and the block chain takes a lot of time for the initial download.<br />
<br />
In such a case the required balance files are fetched with a tool called '''balio''', from a popular block explorer '''blockr.io'''<br />
<br />
''Note: using this tool you will not be able to monitor balance on your stealth addresses.''<br />
<br />
==Requirements==<br />
===Client===<br />
Requires 64-bit platform and at least 4GB of system memory, though these days rather 8GB is recommended.<br />
<br />
The file system that stores the blockchain data must be able to handle files larger than 4GB.<br />
<br />
===Wallet===<br />
The wallet app has very little hardware requirements. As long as you can build it for a specific architecture, it should work there.<br />
<br />
There is no knowledge of Gocoin wallet to be tested on platforms like Raspberry Pi, but theoretically there is no reason why it would not work there.<br />
<br />
For security reasons it is strongly recommended to run the wallet on an encrypted file system, with an encrypted swap file.<br />
<br />
==Limitations==<br />
* No GUI, though the online node has web interface<br />
* No RPC API<br />
* No IPv6<br />
* No UPnP<br />
* No support for non-confirmed transactions (they are invisible in the balance)<br />
* No support for [[Protocol_specification#filterload, filteradd, filterclear, merkleblock | bloom filters]] protocol ([[BIP 0037]]) and the [[Protocol_specification#mempool | mempool]] command<br />
* No routing of [[Protocol_specification#alert | alert]] messages<br />
* No support for multisig stealth addresses (yet)<br />
<br />
==History==<br />
<br />
Gocoin was written by a single person for a private purposes.<br />
<br />
The software's first public release was announced in May 2013 on Bitcointalk forum.<ref>https://bitcointalk.org/index.php?topic=199306.0</ref><br />
Ever since then, the software has been actively maintained and further developed, being armed with new features, further optimized and cleaned up from issues.<br />
<br />
It happened twice that the client wasn't able to catch up with the blockchain, because of the implementation difference of the chain parsing protocol that was causing it to reject a block (transaction) that the reference implementation would accept. In both cases the issue was fixed within single days. The fist case happened in July 2013 and the fix was introduced in version 0.5.7. The second time was in March 2014 - the fix came with release 0.9.3.<br />
<br />
==External Links==<br />
<br />
* [http://www.assets-otc.com/gocoin Homepage]<br />
* [https://github.com/piotrnar/gocoin Github repo]<br />
* [https://bitcointalk.org/index.php?topic=199306.0 Bitcointalk forum topic]<br />
<br />
==References==<br />
<references /><br />
<br />
[[Category:Software]]<br />
[[Category:Clients]]<br />
[[Category:Open Source]]<br />
[[Category:Wallets]]</div>Tonikthttps://en.bitcoin.it/w/index.php?title=Gocoin&diff=47804Gocoin2014-05-31T21:06:05Z<p>Tonikt: /* Wallet */</p>
<hr />
<div>An open-source Bitcoin solution written in Go language (golang).<br />
It can be built for every platform that has a working Go compiler.<br />
It uses a proprietary license, though is free to use for non-commercial purposes.<br />
<br />
==Architecture==<br />
<br />
Gocoin's architecture is quite different from the reference implementation (of the Satoshi client).<br />
<br />
===Libraries===<br />
<br />
====btc====<br />
The core of the software is a library that essentially provides the blockchain protocol parser. That includes script parsing, ECDSA signature verification, but also things like address encoding, parsing of canonical signatures or extracting hashes that need to be signed for specific inputs of a given transaction.<br />
<br />
It is a relatively big library, that contains many useful bitcoin function.<br />
<br />
Inside the package, there is also a blocks persistent storage database (blockdb.go) - it is just a simple plain storage (that can only grow), with an index. It uses snappy compression, allowing to save about 30% of the disk space.<br />
<br />
====qdb====<br />
The core library interfaces directly with a UTXO database backed.<br />
For this purpose Gocoin uses its own database engine, that has been designed to deal with the specific characteristics of bitcoin's UTXO database. <br />
<br />
====secp256k1====<br />
To speed up the Elliptic Curve operations [https://github.com/bitcoin/secp256k1 the secp256k1 library by sipa] has been ported to Go.<br />
<br />
===Online client===<br />
The online client is a kind of a server software (or a peer-to-peer node) that is meant to be running all the time.<br />
<br />
It handles the network related communication, feeds the core lib with new incoming blockchain data, monitors balances on the wallets' addresses, manages transaction memory pool and the peers database. It also provides an interactive user interface.<br />
<br />
===Offline wallet===<br />
The wallet application is responsible for creating private keys (from a seed password) and for signing transactions with them.<br />
It can also sign text messages with private keys and decode raw transactions.<br />
<br />
Unlike the client, the wallet is not an app that is meant te be running continuously. <br />
A user runs it with the requested task - the wallet does the job and exits (back to the command prompt).<br />
<br />
===Blockchain downloader===<br />
For optimized initial blockchain download, Gocoin has a dedicated application called '''downloader'''.<br />
<br />
Among other optimizations, the downloader allows a user to skip verification of all the blocks up to a certain one that he defines as trusted. This can speed up the bootstrap process significantly (e.g. from days to hours).<br />
<br />
After it finishes downloading of all the blocks, it will exit automatically. In that moment the client should be started and it will keep up with all the new blocks, that will appear in the network.<br />
<br />
===Other tools===<br />
There is also a set of more and less useful tools (''github.com/piotrnar/gocoin/tools'') that are an integral part of the Gocoin bitcoin software.<br />
<br />
For instance '''btcversig''' can verify a validity of a bitcoin signature - it is the substitute of the reference client's '''verifymessage''' RPC-API.<br />
<br />
The tool '''type2determ''' can, at the other hand, calculate Type-2 deterministic addresses, without a need to access the wallet (the private keys).<br />
<br />
<br />
==Features==<br />
<br />
Gocoin has a several unique features, that distinguish it from the original bitcoin client.<br />
===Node / Client===<br />
* All the unspent outputs are kept in memory, which makes switching between different wallets, as well as checking a balance of any address, relatively fast (few seconds max).<br />
* Allows a user to limit the upload and download network bandwidth used by the client.<br />
* Can be monitored and controlled through a web interface (from a web browser).<br />
* Works with its own implementation of a cold storage wallet.<br />
* Web interface allows a user to create raw transactions from specific inputs ([[Coin Control]]), as well as multisig transactions ([[P2SH]])<br />
* The blocks are stored on the disk in a compressed form (using [https://code.google.com/p/snappy/ snappy] compression) which saves about 30% of space.<br />
* Supports monitoring and fetching balance of own stealth addresses (the ones implemented in Dark Wallet)<br />
<br />
===Wallet===<br />
* For security reasons, it is supposed to be used with a PC that has never been (and will never be) connected to a network.<br />
* The wallet is deterministic and a seed-password based. As long as you can remember the password, there is no need for any backups.<br />
* Additionally it can import private keys from an existing bitcoin wallet (must be in [[Private key#Base 58 Wallet Import format | Base 58 Wallet Import format]] format).<br />
* Has very low hardware requirements. Can be run on i.e. Raspberry Pi<br />
* Can generate [https://bitcointalk.org/index.php?topic=19137.0 Type-2] deterministic keys/addresses<br />
* Supports signing of [[P2SH]] multisig transactions (the ones that use [[Script#Crypto | OP_CHECKMULTISIG opcode]]).<br />
* Supports spending to stealth addresses as implemented in Dark Wallet<br />
* Supports Litecoin<br />
<br />
===Node-less mode===<br />
It is possible to use Gocoin's wallet, without a need to have a running client node, which may come handy since the node requires quite a decent hardware and the block chain takes a lot of time for the initial download.<br />
<br />
In such a case the required balance files are fetched with a tool called '''FetchBal''', from two popular block explorer services. The list of unspent outputs is first fetched from [[BlockChain.info]] and then the raw transaction data (for these outputs) are downloaded from either [http://webbtc.com webbtc.com], [http://btc.blockr.io/ blockr.io] or [[BlockExplorer.com]] (in that order).<br />
<br />
Using this tool you will not be able to monitor balance on your own stealth addresses.<br />
<br />
==Requirements==<br />
===Client===<br />
Requires 64-bit platform and at least 4GB of system memory, though these days rather 8GB is recommended.<br />
<br />
The file system that stores the blockchain data must be able to handle files larger than 4GB.<br />
<br />
===Wallet===<br />
The wallet app has very little hardware requirements. As long as you can build it for a specific architecture, it should work there.<br />
<br />
There is no knowledge of Gocoin wallet to be tested on platforms like Raspberry Pi, but theoretically there is no reason why it would not work there.<br />
<br />
For security reasons it is strongly recommended to run the wallet on an encrypted file system, with an encrypted swap file.<br />
<br />
==Limitations==<br />
* No GUI, though the online node has web interface<br />
* No RPC API<br />
* No IPv6<br />
* No UPnP<br />
* No support for non-confirmed transactions (they are invisible in the balance)<br />
* No support for [[Protocol_specification#filterload, filteradd, filterclear, merkleblock | bloom filters]] protocol ([[BIP 0037]]) and the [[Protocol_specification#mempool | mempool]] command<br />
* No routing of [[Protocol_specification#alert | alert]] messages<br />
* No support for multisig stealth addresses (yet)<br />
<br />
==History==<br />
<br />
Gocoin was written by a single person for a private purposes.<br />
<br />
The software's first public release was announced in May 2013 on Bitcointalk forum.<ref>https://bitcointalk.org/index.php?topic=199306.0</ref><br />
Ever since then, the software has been actively maintained and further developed, being armed with new features, further optimized and cleaned up from issues.<br />
<br />
It happened twice that the client wasn't able to catch up with the blockchain, because of the implementation difference of the chain parsing protocol that was causing it to reject a block (transaction) that the reference implementation would accept. In both cases the issue was fixed within single days. The fist case happened in July 2013 and the fix was introduced in version 0.5.7. The second time was in March 2014 - the fix came with release 0.9.3.<br />
<br />
==External Links==<br />
<br />
* [http://www.assets-otc.com/gocoin Homepage]<br />
* [https://github.com/piotrnar/gocoin Github repo]<br />
* [https://bitcointalk.org/index.php?topic=199306.0 Bitcointalk forum topic]<br />
<br />
==References==<br />
<references /><br />
<br />
[[Category:Software]]<br />
[[Category:Clients]]<br />
[[Category:Open Source]]<br />
[[Category:Wallets]]</div>Tonikthttps://en.bitcoin.it/w/index.php?title=Base58Check_encoding&diff=47431Base58Check encoding2014-05-17T21:27:11Z<p>Tonikt: 0x01 as a fixed address_version_byte was misleading. and it does not need to be a hash (e.g. for base58 encoded private keys)</p>
<hr />
<div>A modified Base 58 [http://en.wikipedia.org/wiki/Binary-to-text_encoding binary-to-text encoding] known as '''Base58Check''' is used for encoding [[Bitcoin address]]es.<br />
<br />
More generically, Base58Check encoding is used for encoding byte arrays in Bitcoin into human-typable strings. A Bitcoin address is simply a Base58Check-encoded string with a 20-byte payload, the payload being the hash of the [[public key]] associated with the address.<br />
<br />
The original Bitcoin client source code discusses the reasoning behind base58 encoding:<br />
<br />
base58.h:<br />
// Why base-58 instead of standard base-64 encoding?<br />
// - Don't want 0OIl characters that look the same in some fonts and<br />
// could be used to create visually identical looking account numbers.<br />
// - A string with non-alphanumeric characters is not as easily accepted as an account number.<br />
// - E-mail usually won't line-break if there's no punctuation to break at.<br />
// - Doubleclicking selects the whole number as one word if it's all alphanumeric.<br />
<br />
==Features of Base58Check==<br />
Base58Check has the following features:<br />
* An arbitrarily sized payload.<br />
* A set of 58 alphanumeric symbols consisting of easily distinguished uppercase and lowercase letters (0OIl are not used) <br />
* One byte of version/application information. Bitcoin addresses use 0x00 for this byte (future ones may use 0x05).<br />
* Four bytes (32 bits) of SHA256-based error checking code. This code can be used to automatically detect and possibly correct typographical errors.<br />
* An extra step for preservation of leading zeroes in the data.<br />
<br />
==Creating a Base58Check string==<br />
A Base58Check string is created from a version/application byte and payload as follows.<br />
# Take the version/application byte and payload bytes, and concatenate them together (bytewise).<br />
# Take the first four bytes of SHA256(SHA256(results of step 1))<br />
# Concatenate the results of step 1 and the results of step 2 together (bytewise).<br />
# Treating the results of step 3 - a series of bytes - as a single big-endian bignumber, convert to base-58 using normal mathematical steps (bignumber division) and the base-58 alphabet described below. The result should be normalized to not have any leading base-58 zeroes (character '1').<br />
# The leading character '1', which has a value of zero in base58, is reserved for representing an entire leading zero '''byte''', as when it is in a leading position, has no value as a base-58 symbol. There can be one or more leading '1's when necessary to represent one or more leading zero bytes. Count the number of leading zero bytes that were the result of step 3 (for old Bitcoin addresses, there will always be at least one for the version/application byte; for new addresses, there will never be any). Each leading zero byte shall be represented by its own character '1' in the final result.<br />
# Concatenate the 1's from step 5 with the results of step 4. '''This is the Base58Check result.'''<br />
<br />
==Encoding a Bitcoin address==<br />
A Bitcoin address is based on any [[ECDSA]] [[secp256k1]] public/private [[key pair]].<br />
<br />
A Bitcoin address is the Base58Check encoding of the hash of the associated [[script]]. Specifically, it is Base58Check(version byte,[[RIPEMD160]]([[SHA256]]([[script]]))), with the following constraints:<br />
* [[RIPEMD160]] and [[SHA256]] in this case are always exactly 20 and 32 unsigned bytes respectively. These are big-endian (most significant byte first). (Beware of [[bignumber]] implementations that clip leading 0x00 bytes, or prepend extra 0x00 bytes to indicate sign - your code must handle these cases properly or else you may generate valid-looking addresses which can be sent to, but cannot be spent from - which would lead to the permanent loss of coins.)<br />
* version byte is 0x00 for pay-to-address, version byte is 0x05 for pay-to-script-hash.<br />
<br />
Bitcoin addresses that use the version byte 0x00 start with the digit '1'. Bitcoin addresses that use the version byte 0x05 start with the digit '3'.<br />
<br />
==Encoding a private key==<br />
Base58Check encoding is also used for encoding [[private key]]s in the [[Wallet import format]]. This is formed exactly the same as a Bitcoin address, except that 0x80 is used for the version/application byte, and the payload is 32 bytes instead of 20 (a private key in Bitcoin is a single 32-byte unsigned big-endian integer). Such encodings will always yield a 51-character string that starts with '5', or more specifically, either '5H', '5J', or '5K'.<br />
<br />
==Base58 symbol chart==<br />
The Base58 symbol chart used in Bitcoin is specific to the Bitcoin project and is not intended to be the same as any other Base58 implementation used outside the context of Bitcoin.<br />
{| class="wikitable" <br />
|-<br />
!Value<br />
!Character<br />
!Value<br />
!Character<br />
!Value<br />
!Character<br />
!Value<br />
!Character<br />
|-<br />
|0<br />
|1<br />
|1<br />
|2<br />
|2<br />
|3<br />
|3<br />
|4<br />
|-<br />
|4<br />
|5<br />
|5<br />
|6<br />
|6<br />
|7<br />
|7<br />
|8<br />
|-<br />
|8<br />
|9<br />
|9<br />
|A<br />
|10<br />
|B<br />
|11<br />
|C<br />
|-<br />
|12<br />
|D<br />
|13<br />
|E<br />
|14<br />
|F<br />
|15<br />
|G<br />
|-<br />
|16<br />
|H<br />
|17<br />
|J<br />
|18<br />
|K<br />
|19<br />
|L<br />
|-<br />
|20<br />
|M<br />
|21<br />
|N<br />
|22<br />
|P<br />
|23<br />
|Q<br />
|-<br />
|24<br />
|R<br />
|25<br />
|S<br />
|26<br />
|T<br />
|27<br />
|U<br />
|-<br />
|28<br />
|V<br />
|29<br />
|W<br />
|30<br />
|X<br />
|31<br />
|Y<br />
|-<br />
|32<br />
|Z<br />
|33<br />
|a<br />
|34<br />
|b<br />
|35<br />
|c<br />
|-<br />
|36<br />
|d<br />
|37<br />
|e<br />
|38<br />
|f<br />
|39<br />
|g<br />
|-<br />
|40<br />
|h<br />
|41<br />
|i<br />
|42<br />
|j<br />
|43<br />
|k<br />
|-<br />
|44<br />
|m<br />
|45<br />
|n<br />
|46<br />
|o<br />
|47<br />
|p<br />
|-<br />
|48<br />
|q<br />
|49<br />
|r<br />
|50<br />
|s<br />
|51<br />
|t<br />
|-<br />
|52<br />
|u<br />
|53<br />
|v<br />
|54<br />
|w<br />
|55<br />
|x<br />
|-<br />
|56<br />
|y<br />
|57<br />
|z<br />
|}<br />
<br />
The algorithm for encoding address_byte_string (consisting of 1-byte_version + hash_or_other_data + 4-byte_check_code) is<br />
<br />
code_string = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"<br />
x = convert_bytes_to_big_integer(hash_result)<br />
<br />
output_string = ""<br />
<br />
while(x > 0) <br />
{<br />
(x, remainder) = divide(x, 58)<br />
output_string.append(code_string[remainder])<br />
}<br />
<br />
repeat(number_of_leading_zero_bytes_in_hash)<br />
{<br />
output_string.append(code_string[0]);<br />
}<br />
<br />
output_string.reverse();<br />
<br />
==Version bytes==<br />
Here are some common version bytes:<br />
<br />
{| class="wikitable" <br />
|-<br />
!Decimal version<br />
!Leading symbol<br />
!Use<br />
|-<br />
|0<br />
|1<br />
|Bitcoin pubkey hash<br />
|-<br />
|5<br />
|3<br />
|Bitcoin script hash<br />
|-<br />
|21<br />
|4<br />
|Bitcoin (compact) public key (proposed)<br />
|-<br />
|52<br />
|M or N<br />
|Namecoin pubkey hash<br />
|-<br />
|128<br />
|5<br />
|Private key<br />
|-<br />
|111<br />
|m or n<br />
|Bitcoin testnet pubkey hash<br />
|-<br />
|196<br />
|2<br />
|Bitcoin testnet script hash<br />
|}<br />
[[List of address prefixes]] is a more complete list.<br />
<br />
== Source code ==<br />
* [https://github.com/bitcoin/bitcoin/blob/master/src/base58.h "Satoshi" C++ codebase (encode/decode using BigNum library)]<br />
* [https://gitorious.org/bitcoin/libblkmaker/blobs/master/base58.c libblkmaker C code (decode only, no external libraries needed)]<br />
<br />
[[Category:Technical]]<br />
<br />
[[es:Codificación Base58Check]]</div>Tonikthttps://en.bitcoin.it/w/index.php?title=User:Tonikt&diff=47224User:Tonikt2014-05-10T18:37:43Z<p>Tonikt: </p>
<hr />
<div>My name is Piotr Narewski, I was born in Poland, in the 70s, and currently I live in Holland.<br />
<br />
I am the author of [[Gocoin]] (the bitcoin software, not a payment processor, in case if anyone was confused).<br />
<br />
My home page: http://assets-otc.com/<br />
<br />
My PGP key's fingerprint: AB9E A551 E262 A87A 13BB 9059 1BE7 B545 CDF3 FD0E</div>Tonikt