Bitcoin Wiki - User contributions [en]

Protocol rules

2016-03-04T19:27:37Z

Nayuki: Added and improved links to internal pages

'''Rules''' for [[:Category:Clients|clients]].

The wiki substantially documents the [[Protocol_specification|Bitcoin protocol]], but equally important are the rules used by the client to process messages. It's crucial that clients follow certain rules in order to maintain consistency across the network, and to protect the Bitcoin security guarantees.

Here, the focus is on handling tx and block messages, because that is the tricky logic. This will skip over the method of requesting and forwarding these messages for now, and describe what to do when they are received. Also, this will describe the minimal data structures in rather abstract terms, ignoring the client's various indexes, maps and hash tables used for efficiency. This will be a conceptual description. This is all based on a fairly literal reading of the source code.

Mining (block generation) rules are not yet presented.

== Data structures ==

The main data structures are [[transaction]]s and [[block]]s. Blocks are composed of the ''block header'' followed by transactions in the block. Transactions are identified by their hash; blocks by the hash of their header. Blocks have prev pointers that link them into a graph.

Conceptually, the client has the following data structures:

=== Transactions ===

There are two collections of transactions:

;transaction pool
: an unordered collection of transactions that are not in blocks in the main chain, but for which we have input transactions

;orphan transactions
: transactions that can't go into the pool due to one or more missing input transactions

=== Blocks ===

There are 3 categories of blocks:

;blocks in the main branch
: the transactions in these blocks are considered at least tentatively confirmed

;blocks on side branches off the main branch
: these blocks have at least tentatively lost the race to be in the main branch

;orphan blocks
: these are blocks which don't link into the main branch, normally because of a missing predecessor or nth-level predecessor

Blocks in the first two categories form a tree rooted at the [[genesis block]], linked by the prev pointer, which points toward the root. (It is a very linear tree with few and short branches off the main branch.) The main branch is defined as the branch with highest total difficulty, summing the difficulties for each block in the branch.

See also [[Block Status]].

== Difficulty change ==

The difficulty changes every 2016 blocks. This choice is designed to occur approximately every two weeks.

: 2 weeks / 10 minutes = 14 * 24 * 60 / 10 = 2016

Once 2016 blocks has been reached we loop back until we hit the 2016th block before the current one. We find the difference in time between the current block and that one. This difference (called the actual timespan) is limited in bounds between [2 weeks/4, 2 weeks*4].

Then we get the last target for this old 2 week window and multiply it by the ratio of the actual timespan / the target timespan (2 weeks in secs).

: new target = old target * time for 2016 blocks / 2 weeks.

If the old set of blocks completed too fast then the target is lowered (difficulty goes up) ensuring it takes longer to solve these new blocks... and vice versa. This way the difficulty oscillates around the ideal of 2 weeks (and 10 mins per block).

== Block creation fee ==

The block creation fee changes at every 210000 blocks.
The block creation fee is a function of block height on the chain (genesis=0), and is calculated using 64 bit integer operations
(in satoshis) as:

(50 * 100000000) >> (height / 210000)

The block creation fee started with 50 BTC, has fallen to 25 BTC at block 210000, will fall to 12.5 BTC at block 420000, and finally down to 0 satoshi with block 6930000.
The block creation fee of all coinbase transactions will sum up to 2099999997690000 satoshis, practically 21million BTC.

== [[Protocol_specification#tx|"tx"]] messages ==

These messages hold a single [[transaction]].

# Check syntactic correctness
# Make sure neither in or out lists are empty
# Size in bytes < MAX_BLOCK_SIZE
# Each output value, as well as the total, must be in legal money range
# Make sure none of the inputs have hash=0, n=-1 (''coinbase'' transactions)
# Check that nLockTime <= INT_MAX<ref>nLockTime must not exceed 31 bits, as some clients will interpret it incorrectly</ref>, size in bytes >= 100<ref>A valid transaction requires at least 100 bytes. If it's any less, the transaction is not valid</ref>, and sig opcount <= 2<ref>The number of signature operands in the signature (no, that is not redundant) for standard transactions will never exceed two</ref>
# Reject "nonstandard" transactions: scriptSig doing anything other than pushing numbers on the stack, or scriptPubkey not matching the two usual forms<ref>Note that this is not a hard requirement on clients.</ref>
# Reject if we already have matching tx in the pool, or in a block in the main branch
# For each input, if the referenced output exists in any other tx in the pool, reject this transaction.<ref>Note that this is not a hard requirement on clients. The network-enforced rule is that only <i>one</i> transaction spending a particular output can be in the blockchain, thus preventing double-spending. Technically miners can choose which one they want to put into the block they're working on as long as no other transaction has spent that output either previously in the blockchain, or in the same block. The in-memory transaction pool can technically be managed in whatever way the miner is willing to implement.</ref>
# For each input, look in the main branch and the transaction pool to find the referenced output transaction. If the output transaction is missing for any input, this will be an orphan transaction. Add to the orphan transactions, if a matching transaction is not in there already.
# For each input, if the referenced output transaction is coinbase (i.e. only 1 input, with hash=0, n=-1), it must have at least COINBASE_MATURITY (100) confirmations; else reject this transaction
# For each input, if the referenced output does not exist (e.g. never existed or has already been spent), reject this transaction<ref>This is the protection against double-spending</ref>
# Using the referenced output transactions to get input values, check that each input value, as well as the sum, are in legal money range
# Reject if the sum of input values < sum of output values
# Reject if transaction fee (defined as sum of input values minus sum of output values) would be too low to get into an empty block
# Verify the [[Script|scriptPubKey]] accepts for each input; reject if any are bad
# Add to transaction pool<ref>Note that when the transaction is accepted into the memory pool, an additional check is made to ensure that the coinbase value does not exceed the transaction fees plus the expected BTC value (25BTC as of this writing).</ref>
# "Add to wallet if mine"
# Relay transaction to peers
# For each orphan transaction that uses this one as one of its inputs, run all these steps (including this one) recursively on that orphan

===Explanation of Some Rules===
Most rules are self-explanatory. This section explains why some of the less obvious rules are in place.

== [[Protocol_specification#block|"block"]] messages ==

These messages hold a single [[block]].

# Check syntactic correctness
# Reject if duplicate of block we have in any of the three categories
# Transaction list must be non-empty
# Block hash must satisfy claimed ''nBits'' proof of work
# Block timestamp must not be more than two hours in the future
# First transaction must be coinbase (i.e. only 1 input, with hash=0, n=-1), the rest must not be
# For each transaction, apply "tx" checks 2-4
# For the coinbase (first) transaction, scriptSig length must be 2-100
# Reject if sum of transaction sig opcounts > MAX_BLOCK_SIGOPS
# Verify Merkle hash
# Check if prev block (matching ''prev'' hash) is in main branch or side branches. If not, add this to orphan blocks, then query peer we got this from for 1st missing orphan block in ''prev'' chain; done with block
# Check that ''nBits'' value matches the difficulty rules
# Reject if timestamp is the median time of the last 11 blocks or before
# For certain old blocks (i.e. on initial block download) check that hash matches known values
# Add block into the tree. There are three cases: 1. block further extends the main branch; 2. block extends a side branch but does not add enough difficulty to make it become the new main branch; 3. block extends a side branch and makes it the new main branch.
# For case 1, adding to main branch:
## For all but the coinbase transaction, apply the following:
### For each input, look in the main branch to find the referenced output transaction. Reject if the output transaction is missing for any input.
### For each input, if we are using the ''n''th output of the earlier transaction, but it has fewer than n+1 outputs, reject.
### For each input, if the referenced output transaction is coinbase (i.e. only 1 input, with hash=0, n=-1), it must have at least COINBASE_MATURITY (100) confirmations; else reject.
### Verify crypto signatures for each input; reject if any are bad
### For each input, if the referenced output has already been spent by a transaction in the main branch, reject
### Using the referenced output transactions to get input values, check that each input value, as well as the sum, are in legal money range
### Reject if the sum of input values < sum of output values
## Reject if coinbase value > sum of block creation fee and transaction fees
## (If we have not rejected):
## For each transaction, "Add to wallet if mine"
## For each transaction in the block, delete any matching transaction from the transaction pool
## Relay block to our peers
## If we rejected, the block is not counted as part of the main branch
# For case 2, adding to a side branch, we don't do anything.
# For case 3, a side branch becoming the main branch:
## Find the ''fork'' block on the main branch which this side branch forks off of
## Redefine the main branch to only go up to this ''fork'' block
## For each block on the side branch, from the child of the ''fork'' block to the leaf, add to the main branch:
### Do "branch" checks 3-11
### For all but the coinbase transaction, apply the following:
#### For each input, look in the main branch to find the referenced output transaction. Reject if the output transaction is missing for any input.
#### For each input, if we are using the ''n''th output of the earlier transaction, but it has fewer than n+1 outputs, reject.
#### For each input, if the referenced output transaction is coinbase (i.e. only 1 input, with hash=0, n=-1), it must have at least COINBASE_MATURITY (100) confirmations; else reject.
#### Verify crypto signatures for each input; reject if any are bad
#### For each input, if the referenced output has already been spent by a transaction in the main branch, reject
#### Using the referenced output transactions to get input values, check that each input value, as well as the sum, are in legal money range
#### Reject if the sum of input values < sum of output values
### Reject if coinbase value > sum of block creation fee and transaction fees
### (If we have not rejected):
### For each transaction, "Add to wallet if mine"
## If we reject at any point, leave the main branch as what it was originally, done with block
## For each block in the old main branch, from the leaf down to the child of the ''fork'' block:
### For each non-coinbase transaction in the block:
#### Apply "tx" checks 2-9, except in step 8, only look in the transaction pool for duplicates, not the main branch
#### Add to transaction pool if accepted, else go on to next transaction
## For each block in the new main branch, from the child of the ''fork'' node to the leaf:
### For each transaction in the block, delete any matching transaction from the transaction pool
## Relay block to our peers
# For each orphan block for which this block is its ''prev'', run all these steps (including this one) recursively on that orphan

== See Also ==

* [[Protocol specification]]
* [[Bitcoin Improvement Proposals]]
* [[Hardfork Wishlist]]

==References==
<references />

[[Category:Technical]][[Category:Developer]]

Block

2016-03-04T19:25:05Z

Nayuki: Added related link, copyedit

Transaction data is permanently recorded in files called '''blocks'''. They can be thought of as the individual pages of a city recorder's recordbook (where changes to title to real estate are recorded) or a stock transaction ledger. Blocks are organized into a linear sequence over time (also known as the [[block chain]]). New transactions are constantly being processes by [[Mining|miners]] into new blocks which are added to the end of the chain and can never be changed or removed once accepted by the network (although some software will remove orphaned blocks).

===Block structure===
{| class="wikitable"
|-
! Field
! Description
! Size
|-
|Magic no
|value always 0xD9B4BEF9
|4 bytes
|-
|Blocksize
|number of bytes following up to end of block
|4 bytes
|-
|Blockheader
|[[Block hashing algorithm| consists of 6 items]]
|80 bytes
|-
|Transaction counter
| positive integer [[ Protocol_specification#Variable_length_integer|VI = VarInt]]
| 1 - 9 bytes
|-
|[[transactions]]
|the (non empty) list of transactions
|<Transaction counter>-many transactions
|}
==Description==
Each block contains, among other things, a record of some or all recent [[transactions]], and a reference to the block that came immediately before it. It also contains an answer to a difficult-to-solve mathematical puzzle - the answer to which is unique to each block. New blocks cannot be submitted to the network without the correct answer - the process of "[[mining]]" is essentially the process of competing to be the next to find the answer that "solves" the current block. The mathematical problem in each block is extremely [[difficulty|difficult]] to solve, but once a valid solution is found, it is very easy for the rest of the network to confirm that the solution is correct. There are multiple valid solutions for any given block - only one of the solutions needs to be found for the block to be solved.

Because there is a reward of brand new bitcoins for solving each block, every block also contains a record of which [[Bitcoin address]]es or [[script]]s are entitled to receive the reward. This record is known as a generation transaction, or a [[coinbase]] transaction, and is always the first transaction appearing in every block. The number of [[Bitcoins]] generated per block starts at 50 and is [[controlled supply|halved]] every 210,000 blocks (about four years).

Bitcoin transactions are [[transaction broadcasting|broadcast]] to the [[network]] by the sender, and all peers trying to solve blocks collect the transaction records and add them to the block they are working to solve. Miners get incentive to include transactions in their blocks because of attached transaction fees.

The [[difficulty]] of the mathematical problem is automatically adjusted by the network, such that it targets a goal of solving an average of 6 blocks per hour. Every 2016 blocks (solved in about two weeks), all Bitcoin clients compare the actual number created with this goal and modify the target by the percentage that it varied. The network comes to a consensus and automatically increases (or decreases) the difficulty of generating blocks.

Because each block contains a reference to the prior block, the collection of all blocks in existence can be said to form a chain. However, it's possible for the chain to have temporary splits - for example, if two miners arrive at two different valid solutions for the same block at the same time, unbeknownst to one another. The peer-to-peer network is designed to resolve these splits within a short period of time, so that only one branch of the chain survives.

The client accepts the 'longest' chain of blocks as valid. The 'length' of the entire [[block chain]] refers to the chain with the most combined difficulty, not the one with the most blocks. This prevents someone from forking the chain and creating a large number of low-difficulty blocks, and having it accepted by the network as 'longest'.

== Common Questions about Blocks ==

=== How many blocks are there? ===
[http://blockexplorer.com/q/getblockcount Current block count]

=== What is the maximum number of blocks? ===
There is no maximum number, blocks just keep getting added to the end of the chain at an average rate of one every 10 minutes.

==== Even when all 21 million coins have been generated? ====
Yes. The blocks are for proving that transactions existed at a particular time. Transactions will still occur once all the coins have been generated, so blocks will still be created as long as people are trading Bitcoins.

=== How long will it take me to generate a block? ===
No one can say exactly. There is a [[Generation Calculator|generation calculator]] that will tell you how long it '''might''' take.

=== What if I'm 1% towards calculating a block and...? ===
There's no such thing as being 1% towards solving a block. You don't make progress towards solving it. After working on it for 24 hours, your chances of solving it are equal to what your chances were at the start or at any moment. Believing otherwise is what's known as the Gambler's fallacy [http://en.wikipedia.org/wiki/Gambler's_fallacy].

It's like trying to flip 53 coins at once and have them all come up heads. Each time you try, your chances of success are the same.

=== Where can I find more technical detail? ===
There is more technical detail on the [[block hashing algorithm]] page.

==See Also==

* [[Protocol rules#"block" messages|Protocol rules - "block" messages]]
* [https://bitcointalk.org/index.php?topic=101514.0 Format of the BDB-style block files]

[[Category:Technical]]
[[Category:Vocabulary]]

[[fr:Blocs]][[pl:Bloki]][[zh-cn:Block]]
[[de:Block]]

Transaction

2016-03-04T19:21:54Z

Nayuki: /* See Also */ - Added related links, rearranged external links

[[File:TxBinaryMap.png|thumb|right|Byte-map of Transaction with each type of TxIn and TxOut]]
A '''transaction''' is a transfer of Bitcoin value that is broadcast to the [[network]] and collected into [[block|blocks]]. A transaction typically references previous transaction outputs as new transaction inputs and dedicates all input Bitcoin values to new outputs. Transactions are not encrypted, so it is possible to browse and view every transaction ever collected into a block.

Standard transaction outputs nominate [[address|addresses]], and the redemption of any future inputs requires a relevant signature.

All transactions are visible in the [[block chain]], and can be viewed with a hex editor. A [[block chain browser]] is a site where every transaction included within the block chain can be viewed in human-readable terms. This is useful for seeing the technical details of transactions in action and for verifying payments.

=== general format of a Bitcoin transaction (inside a block) ===
{| class="wikitable"
|-
! Field
! Description
! Size
|-
|Version no
|currently 1
|4 bytes
|-
|In-counter
| positive integer [[ Protocol_specification#Variable_length_integer|VI = VarInt]]
| 1 - 9 bytes
|-
|list of inputs
|[[Transaction#general_format_.28inside_a_block.29_of_each_input_of_a_transaction_-_Txin|the first input of the first transaction is also called "coinbase" (its content was ignored in earlier versions)]]
|<in-counter>-many inputs
|-
|Out-counter
| positive integer [[ Protocol_specification#Variable_length_integer|VI = VarInt]]
| 1 - 9 bytes
|-
|list of outputs
|[[Transaction#general_format_.28inside_a_block.29_of_each_output_of_a_transaction_-_Txout|the outputs of the first transaction spend the mined bitcoins for the block]]
|<out-counter>-many outputs
|-
|lock_time
|if non-zero and sequence numbers are < 0xFFFFFFFF: block height or timestamp when transaction is final
|4 bytes
|}

=== Principle example of a Bitcoin transaction with 1 input and 1 output only ===

==== Data ====

<pre>Input:
Previous tx: f5d8ee39a430901c91a5917b9f2dc19d6d1a0e9cea205b009ca73dd04470b9a6
Index: 0
scriptSig: 304502206e21798a42fae0e854281abd38bacd1aeed3ee3738d9e1446618c4571d10
90db022100e2ac980643b0b82c0e88ffdfec6b64e3e6ba35e7ba5fdd7d5d6cc8d25c6b241501

Output:
Value: 5000000000
scriptPubKey: OP_DUP OP_HASH160 404371705fa9bd789a2fcd52d2c580b65d35549d
OP_EQUALVERIFY OP_CHECKSIG</pre>

==== Explanation ====

The input in this transaction imports 50 BTC from output #0 in transaction f5d8... Then the output sends 50 BTC to a Bitcoin address (expressed here in hexadecimal 4043... instead of the normal base58). When the recipient wants to spend this money, he will reference output #0 of this transaction in an input of his own transaction.

===== Input =====

An '''input''' is a reference to an output from a previous transaction. Multiple inputs are often listed in a transaction. All of the new transaction's input values (that is, the total coin value of the previous outputs referenced by the new transaction's inputs) are added up, and the total (less any transaction fee) is completely used by the outputs of the new transaction. '''Previous tx''' is a [[hash]] of a previous transaction. '''Index''' is the specific output in the referenced transaction. '''ScriptSig''' is the first half of a [[script]] (discussed in more detail later).

The script contains two components, a signature and a public key. The public key must match the hash given in the script of the redeemed output. The public key is used to verify the redeemers signature, which is the second component. More precisely, the second component is an [[ECDSA]] signature over a hash of a simplified version of the transaction. It, combined with the public key, proves the transaction was created by the real owner of the address in question. Various flags define how the transaction is simplified and can be used to create different types of payment.

===== Output =====

An '''output''' contains instructions for sending bitcoins. '''Value''' is the number of Satoshi (1 BTC = 100,000,000 Satoshi) that this output will be worth when claimed. '''ScriptPubKey''' is the second half of a script (discussed later). There can be more than one output, and they share the combined value of the inputs. Because each output from one transaction can only ever be referenced once by an input of a subsequent transaction, the entire combined input value needs to be sent in an output if you don't want to lose it. If the input is worth 50 BTC but you only want to send 25 BTC, Bitcoin will create two outputs worth 25 BTC: one to the destination, and one back to you (known as "[[change]]", though you send it to yourself). Any input bitcoins not redeemed in an output is considered a [[transaction fee]]; whoever generates the block will get it.
[[File:transaction.png|thumb|A sends 100 BTC to C and C generates 50 BTC. C sends 101 BTC to D, and he needs to send himself some change. D sends the 101 BTC to someone else, but they haven't redeemed it yet. Only D's output and C's change are capable of being spent in the current state.]]

===== Verification =====

To verify that inputs are authorized to collect the values of referenced outputs, Bitcoin uses a custom Forth-like [[script|scripting]] system. The input's scriptSig and the ''referenced'' output's scriptPubKey are evaluated (in that order), with scriptPubKey using the values left on the stack by scriptSig. The input is authorized if scriptPubKey returns true. Through the scripting system, the sender can create very complex conditions that people have to meet in order to claim the output's value. For example, it's possible to create an output that can be claimed by anyone without any authorization. It's also possible to require that an input be signed by ten different keys, or be redeemable with a password instead of a key.

=== Types of Transaction ===
Bitcoin currently creates two different scriptSig/scriptPubKey pairs. These are described below.

It is possible to design more complex types of transactions, and link them together into cryptographically enforced agreements. These are known as [[Contracts]].

==== Pay-to-PubkeyHash ====

scriptPubKey: OP_DUP OP_HASH160 <pubKeyHash> OP_EQUALVERIFY OP_CHECKSIG
scriptSig: <sig> <pubKey>
A Bitcoin [[address]] is only a hash, so the sender can't provide a full public key in scriptPubKey. When redeeming coins that have been sent to a Bitcoin address, the recipient provides both the signature and the public key. The script verifies that the provided public key does hash to the hash in scriptPubKey, and then it also checks the signature against the public key.

Checking process:
{| class="wikitable"
|-
! Stack
! Script
! Description
|-
|Empty.
| <sig> <pubKey> OP_DUP OP_HASH160 <pubKeyHash> OP_EQUALVERIFY OP_CHECKSIG
| scriptSig and scriptPubKey are combined.
|-
|<sig> <pubKey>
| OP_DUP OP_HASH160 <pubKeyHash> OP_EQUALVERIFY OP_CHECKSIG
| Constants are added to the stack.
|-
|<sig> <pubKey> <pubKey>
| OP_HASH160 <pubKeyHash> OP_EQUALVERIFY OP_CHECKSIG
| Top stack item is duplicated.
|-
|<sig> <pubKey> <pubHashA>
|<pubKeyHash> OP_EQUALVERIFY OP_CHECKSIG
| Top stack item is hashed.
|-
|<sig> <pubKey> <pubHashA> <pubKeyHash>
|OP_EQUALVERIFY OP_CHECKSIG
| Constant added.
|-
|<sig> <pubKey>
|OP_CHECKSIG
| Equality is checked between the top two stack items.
|-
|true
|Empty.
|Signature is checked for top two stack items.
|}

==== Pay-to-Script-Hash ====

scriptPubKey: OP_HASH160 <scriptHash> OP_EQUAL
scriptSig: ..signatures... <serialized script>

m-of-n multi-signature transaction:
scriptSig: 0 <sig1> ... <script>
script: OP_m <pubKey1> ... OP_n OP_CHECKMULTISIG

P2SH addresses were created with the motivation of moving "the responsibility for supplying the conditions to redeem a transaction from the sender of the funds to the redeemer. They allow the sender to fund an arbitrary transaction, no matter how complicated, using a 20-byte hash"[https://github.com/bitcoin/bips/blob/master/bip-0016.mediawiki#motivation 1]. Pay-to-Pubkey-hash addresses are similarly a 20-byte hash of the public key.

Pay-to-script-hash provides a means for complicated transactions, unlike the Pay-to-pubkey-hash, which has a specific definition for scriptPubKey, and scriptSig. The specification places no limitations on the script, and hence absolutely any contract can be funded using these addresses.

The scriptPubKey in the funding transaction is script which ensures that the script supplied in the redeeming transaction hashes to the script used to create the address.

In the scriptSig above, 'signatures' refers to any script which is sufficient to satisfy the following serialized script.

Checking process:
{| class="wikitable"
|-
! Stack
! Script
! Description
|-
|Empty.
| 0 <sig1> <sig2> OP_2 <pubKey1> <pubKey2> <pubKey3> OP_3 OP_CHECKMULTISIG
| Only the scriptSig is used.
|-
| 0 <sig1> <sig2> OP_2 <pubKey1> <pubKey2> <pubKey3> OP_3
| OP_CHECKMULTISIG
| Constants are added to the stack.
|-
| true
| Empty
| Signatures validated in the order of the keys in the script.
|}

See also [[BIP 0016]]

==== Generation ====

Generations have a single input, and this input has a "[[Coinbase |coinbase]]" parameter instead of a scriptSig. The data in "coinbase" can be anything; it isn't used. Bitcoin puts the current compact-format [[target]] and the arbitrary-precision "extraNonce" number there, which increments every time the Nonce field in the [[block_hashing_algorithm|block header]] overflows. Outputs can be anything, but Bitcoin creates one exactly like an IP address transaction.
The extranonce contributes to enlarge the domain for the proof of work function. Miners can easily modify nonce (4byte), timestamp and extranonce (2 to 100bytes).

=== general format (inside a block) of each input of a transaction - Txin ===
{| class="wikitable"
|-
! Field
! Description
! Size
|-
|Previous Transaction hash
| doubled [[Wikipedia:SHA-256|SHA256]]-[[hash|hashed]] of a (previous) to-be-used transaction
|32 bytes
|-
|Previous Txout-index
| non negative integer indexing an output of the to-be-used transaction
|4 bytes
|-
|Txin-script length
|non negative integer [[ Protocol_specification#Variable_length_integer|VI = VarInt]]
|1 - 9 bytes
|-
|Txin-script / scriptSig
|[[Script]]
|<in-script length>-many bytes
|-
|sequence_no
|normally 0xFFFFFFFF; irrelevant unless transaction's lock_time is > 0
|4 bytes
|}

The input sufficiently describes where and how to get the bitcoin amout to be redeemed.
If it is the (only) input of the first transaction of a block, it is called the generation transaction input and its content completely ignored. (Historically the Previous Transaction hash is 0 and the Previous Txout-index is -1.)

=== general format (inside a block) of each output of a transaction - Txout ===
{| class="wikitable"
|-
! Field
! Description
! Size
|-
|value
|non negative integer giving the number of [[FAQ#What_do_I_call_the_various_denominations_of_bitcoins.3F|Satoshis(BTC/10^8)]] to be transfered
|8 bytes
|-
|Txout-script length
|non negative integer
|1 - 9 bytes [[ Protocol_specification#Variable_length_integer|VI = VarInt]]
|-
|Txout-script / scriptPubKey
|[[Script]]
|<out-script length>-many bytes
|}
The output sets the conditions to release this bitcoin amount later. The sum of the output values of the first transaction is the value of the mined bitcoins for the block plus possible transactions fees of the other transactions in the block.

==See Also==

* [[Script]]
* [[Protocol rules#"tx" messages|Protocol rules - "tx" messages]]
* [[Protocol documentation#Transaction Verification|Protocol documentation - Transaction Verification]]
* [[Raw Transactions]]
* [[Transaction Malleability]]
* [https://coinb.in/#newTransaction coinb.in's] raw transaction tool
* [[BTC Sender]] Transmit raw, hand-crafted transactions

[[Category:Technical]]
[[Category:Vocabulary]]
[[de:Transaktion]]
[[es:Transacción]]
[[pl:Transakcje]]

Protocol documentation

2015-07-25T02:32:19Z

Nayuki: /* Message types - version */ - Improved formatting

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.

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

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

==Common standards==

=== Hashes ===

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

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

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

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

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

=== Merkle Trees ===

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

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

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

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

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

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

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

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

d7 = dhash(d5 concat d6)

where

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

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

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

=== Signatures ===

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

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

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

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

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

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

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

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

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

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

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

=== Addresses ===

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

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

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

== Common structures ==

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

=== Message structure ===

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

Known magic values:

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

=== Variable length integer ===

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

{|class="wikitable"
! Value !! Storage length !! Format
|-
| < 0xFD || 1 || uint8_t
|-
| <= 0xFFFF || 3 || 0xFD followed by the length as uint16_t
|-
| <= 0xFFFF FFFF || 5 || 0xFE followed by the length as uint32_t
|-
| - || 9 || 0xFF followed by the length as uint64_t
|}

If you're reading the Satoshi client code (BitcoinQT) it refers to this 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.

=== Variable length string ===

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

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

=== Network address ===

When a network address is needed somewhere, this structure is used. Network addresses are not prefixed with a timestamp in the version message.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || time || uint32 || the Time (version >= 31402). '''Not present in version message.'''
|-
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]
|-
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The original client only 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]
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).
|-
| 2 || port || uint16_t || port number, network byte order
|}

Hexdump example of Network address structure

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

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

=== Inventory Vectors ===

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

Inventory vectors consist of the following data format:

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

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

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

Other Data Type values are considered reserved for future implementations.

=== Block Headers ===

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

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

== Message types ==

=== version ===

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

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || int32_t || Identifies protocol version being used by the node
|-
| 8 || services || uint64_t || bitfield of features to be enabled for this connection
|-
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds
|-
| 26 || addr_recv || [[#Network address|net_addr]] || The network address of the node receiving this message
|-
|colspan="4"| Fields below require version ≥ 106
|-
| 26 || addr_from || [[#Network address|net_addr]] || The network address of the node emitting this message
|-
| 8 || nonce || uint64_t || Node random nonce, randomly generated every time a version packet is sent. This nonce is used to detect connections to self.
|-
| ? || user_agent || [[#Variable length string|var_str]] || [https://github.com/bitcoin/bips/blob/master/bip-0014.mediawiki User Agent] (0x00 if string is 0 bytes long)
|-
| 4 || start_height || int32_t || The last block received by the emitting node
|-
|colspan="4"| Fields below require version ≥ 70001
|-
| 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]
|}

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

The following services are currently assigned:

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

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

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

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

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

<pre>

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

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

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

=== verack ===

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

Hexdump of the verack message:

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

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

=== addr ===

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

Payload:
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+ || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of address entries (max: 1000)
|-
| 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).
|}

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

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

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

Payload:
01 - 1 address in this message

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

=== inv ===

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

Payload (maximum 50,000 entries, which is just over 1.8 megabytes):

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

=== getdata ===

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

Payload (maximum 50,000 entries, which is just over 1.8 megabytes):

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

=== notfound ===

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

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

=== getblocks ===

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

The locator hashes are processed by a node in the order as they appear in the message. If a block hash 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.

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.

Payload:

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

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

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

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

=== getheaders ===

Return a ''headers'' packet containing the headers of blocks starting right after the last known hash in the block locator object, up to hash_stop or 2000 blocks, whichever comes first. To receive the next block headers, one needs to issue getheaders again with a new block locator object. The ''getheaders'' command is used by thin clients to quickly download the 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.

Payload:

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

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

=== tx ===

''tx'' describes a bitcoin transaction, in reply to ''[[#getdata|getdata]]''

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

|}

TxIn consists of the following fields:

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

The OutPoint structure consists of the following fields:

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

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

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

The TxOut structure consists of the following fields:

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

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

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

Transaction:
01 00 00 00 - version

Inputs:
01 - number of transaction inputs

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

8B - script is 139 bytes long

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

FF FF FF FF - sequence

Outputs:
02 - 2 Output Transactions

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

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

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

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

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

=== block ===

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

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

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

=== headers ===

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

Payload:

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

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

=== getaddr ===

The getaddr message sends a request to a node asking for information about known active peers to help with 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.

No additional data is transmitted with this message.

=== mempool ===

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

No additional data is transmitted with this message.

It is specified in [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.

=== checkorder ===

This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.

=== submitorder ===

This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.

=== reply ===

This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.

=== ping ===

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

Payload:

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

=== pong ===

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

Payload:

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

=== reject===

The ''reject'' message is sent when messages are rejected.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+ || message || var_str || type of message rejected
|-
| 1 || ccode || char || code relating to rejected message
|-
| 1+ || reason || var_str || text version of reason for rejection
|-
| 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.
|}

CCodes

{|class="wikitable"
! Value !! Name !! Description
|-
| 0x01 || REJECT_MALFORMED||
|-
| 0x10 || REJECT_INVALID ||
|-
| 0x11 || REJECT_OBSOLETE ||
|-
| 0x12 || REJECT_DUPLICATE ||
|-
| 0x40 || REJECT_NONSTANDARD ||
|-
| 0x41 || REJECT_DUST ||
|-
| 0x42 || REJECT_INSUFFICIENTFEE ||
|-
| 0x43 || REJECT_CHECKPOINT ||
|}

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

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

The <code>filterload</code> command is defined as follows:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || filter || uint8_t[] || The filter itself is simply a bit field of arbitrary byte-aligned size. The maximum size is 36,000 bytes.
|-
| 4 || nHashFuncs || uint32_t || The number of hash functions to use in this filter. The maximum value allowed in this field is 50.
|-
| 4 || nTweak || uint32_t || A random value to add to the seed value in the hash function used by the bloom filter.
|-
| 1 || nFlags || uint8_t || A set of flags that control how matched items are added to the filter.
|}

See below for a description of the Bloom filter algorithm and how to select nHashFuncs and filter size for a desired false positive rate.

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.

The <code>filteradd</code> command is defined as follows:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || data || uint8_t[] || The data element to add to the current filter.
|}

The data field must be smaller than or equal to 520 bytes in size (the maximum size of any potentially matched object).

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

The <code>filterclear</code> command has no arguments at all.

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:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || uint32_t || Block version information, based upon the software version creating this block
|-
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references
|-
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block
|-
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Limited to 2106!)
|-
| 4 || bits || uint32_t || The calculated difficulty target being used for this block
|-
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes
|-
| 4 || total_transactions || uint32_t || Number of transactions in the block (including unmatched ones)
|-
| ? || hashes || uint256[] || hashes in depth-first order (including standard varint size prefix)
|-
| ? || flags || byte[] || flag bits, packed per 8 in a byte, least significant bit first (including standard varint size prefix)
|}

=== alert ===

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

Alert format:

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

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

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

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]])

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

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

== Scripting ==

See [[script]].

==See Also==

* [[Network]]
* [[Protocol rules]]
* [[Hardfork Wishlist]]
* [https://bitcoin.org/en/developer-documentation Developer Documentation on bitcoin.org]
* Bitcoin dissectors for Wireshark: https://github.com/lbotsch/wireshark-bitcoin https://github.com/op-sig/bitcoin-wireshark-dissector

==References==
<references />

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

Protocol documentation

2015-07-25T02:30:17Z

Nayuki: /* Variable length integer */ - Improved readability of hexadecimal numbers and text

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.

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

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

==Common standards==

=== Hashes ===

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

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

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

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

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

=== Merkle Trees ===

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

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

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

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

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

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

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

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

d7 = dhash(d5 concat d6)

where

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

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

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

=== Signatures ===

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

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

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

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

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

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

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

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

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

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

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

=== Addresses ===

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

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

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

== Common structures ==

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

=== Message structure ===

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

Known magic values:

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

=== Variable length integer ===

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

{|class="wikitable"
! Value !! Storage length !! Format
|-
| < 0xFD || 1 || uint8_t
|-
| <= 0xFFFF || 3 || 0xFD followed by the length as uint16_t
|-
| <= 0xFFFF FFFF || 5 || 0xFE followed by the length as uint32_t
|-
| - || 9 || 0xFF followed by the length as uint64_t
|}

If you're reading the Satoshi client code (BitcoinQT) it refers to this 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.

=== Variable length string ===

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

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

=== Network address ===

When a network address is needed somewhere, this structure is used. Network addresses are not prefixed with a timestamp in the version message.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || time || uint32 || the Time (version >= 31402). '''Not present in version message.'''
|-
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]
|-
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The original client only 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]
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).
|-
| 2 || port || uint16_t || port number, network byte order
|}

Hexdump example of Network address structure

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

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

=== Inventory Vectors ===

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

Inventory vectors consist of the following data format:

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

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

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

Other Data Type values are considered reserved for future implementations.

=== Block Headers ===

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

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

== Message types ==

=== version ===

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

Payload:

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

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

The following services are currently assigned:

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

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

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

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

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

<pre>

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

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

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

=== verack ===

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

Hexdump of the verack message:

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

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

=== addr ===

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

Payload:
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+ || count || [[Protocol_documentation#Variable_length_integer|var_int]] || Number of address entries (max: 1000)
|-
| 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).
|}

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

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

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

Payload:
01 - 1 address in this message

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

=== inv ===

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

Payload (maximum 50,000 entries, which is just over 1.8 megabytes):

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

=== getdata ===

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

Payload (maximum 50,000 entries, which is just over 1.8 megabytes):

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

=== notfound ===

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

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

=== getblocks ===

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

The locator hashes are processed by a node in the order as they appear in the message. If a block hash 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.

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.

Payload:

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

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

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

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

=== getheaders ===

Return a ''headers'' packet containing the headers of blocks starting right after the last known hash in the block locator object, up to hash_stop or 2000 blocks, whichever comes first. To receive the next block headers, one needs to issue getheaders again with a new block locator object. The ''getheaders'' command is used by thin clients to quickly download the 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.

Payload:

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

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

=== tx ===

''tx'' describes a bitcoin transaction, in reply to ''[[#getdata|getdata]]''

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

|}

TxIn consists of the following fields:

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

The OutPoint structure consists of the following fields:

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

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

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

The TxOut structure consists of the following fields:

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

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

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

Transaction:
01 00 00 00 - version

Inputs:
01 - number of transaction inputs

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

8B - script is 139 bytes long

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

FF FF FF FF - sequence

Outputs:
02 - 2 Output Transactions

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

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

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

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

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

=== block ===

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

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

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

=== headers ===

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

Payload:

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

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

=== getaddr ===

The getaddr message sends a request to a node asking for information about known active peers to help with 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.

No additional data is transmitted with this message.

=== mempool ===

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

No additional data is transmitted with this message.

It is specified in [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.

=== checkorder ===

This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.

=== submitorder ===

This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.

=== reply ===

This message was used for [[IP Transactions]]. As IP transactions have been deprecated, it is no longer used.

=== ping ===

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

Payload:

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

=== pong ===

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

Payload:

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

=== reject===

The ''reject'' message is sent when messages are rejected.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+ || message || var_str || type of message rejected
|-
| 1 || ccode || char || code relating to rejected message
|-
| 1+ || reason || var_str || text version of reason for rejection
|-
| 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.
|}

CCodes

{|class="wikitable"
! Value !! Name !! Description
|-
| 0x01 || REJECT_MALFORMED||
|-
| 0x10 || REJECT_INVALID ||
|-
| 0x11 || REJECT_OBSOLETE ||
|-
| 0x12 || REJECT_DUPLICATE ||
|-
| 0x40 || REJECT_NONSTANDARD ||
|-
| 0x41 || REJECT_DUST ||
|-
| 0x42 || REJECT_INSUFFICIENTFEE ||
|-
| 0x43 || REJECT_CHECKPOINT ||
|}

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

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

The <code>filterload</code> command is defined as follows:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || filter || uint8_t[] || The filter itself is simply a bit field of arbitrary byte-aligned size. The maximum size is 36,000 bytes.
|-
| 4 || nHashFuncs || uint32_t || The number of hash functions to use in this filter. The maximum value allowed in this field is 50.
|-
| 4 || nTweak || uint32_t || A random value to add to the seed value in the hash function used by the bloom filter.
|-
| 1 || nFlags || uint8_t || A set of flags that control how matched items are added to the filter.
|}

See below for a description of the Bloom filter algorithm and how to select nHashFuncs and filter size for a desired false positive rate.

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.

The <code>filteradd</code> command is defined as follows:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || data || uint8_t[] || The data element to add to the current filter.
|}

The data field must be smaller than or equal to 520 bytes in size (the maximum size of any potentially matched object).

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

The <code>filterclear</code> command has no arguments at all.

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:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || uint32_t || Block version information, based upon the software version creating this block
|-
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references
|-
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block
|-
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Limited to 2106!)
|-
| 4 || bits || uint32_t || The calculated difficulty target being used for this block
|-
| 4 || nonce || uint32_t || The nonce used to generate this block… to allow variations of the header and compute different hashes
|-
| 4 || total_transactions || uint32_t || Number of transactions in the block (including unmatched ones)
|-
| ? || hashes || uint256[] || hashes in depth-first order (including standard varint size prefix)
|-
| ? || flags || byte[] || flag bits, packed per 8 in a byte, least significant bit first (including standard varint size prefix)
|}

=== alert ===

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

Alert format:

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

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

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

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]])

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

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

== Scripting ==

See [[script]].

==See Also==

* [[Network]]
* [[Protocol rules]]
* [[Hardfork Wishlist]]
* [https://bitcoin.org/en/developer-documentation Developer Documentation on bitcoin.org]
* Bitcoin dissectors for Wireshark: https://github.com/lbotsch/wireshark-bitcoin https://github.com/op-sig/bitcoin-wireshark-dissector

==References==
<references />

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

Protocol Specification

2015-04-15T19:52:48Z

Nayuki: Made the redirect more direct (removing the intermediary)

#REDIRECT [[Protocol documentation]]

Privacy

2015-04-12T19:50:35Z

Nayuki: Corrected spelling, removed redundant links

While the Bitcoin technology [http://www.bitcointalk.org/index.php?topic=241.0 can support] strong anonymity, the current implementation is usually not very anonymous.

__TOC__

The main problem is that every transaction is publicly logged. Anyone can see the flow of Bitcoins from address to address (see first image). Alone, this information can't identify anyone because the addresses are just random numbers. However, if ''any'' of the addresses in a transaction's past or future can be tied to an actual identity, it might be possible to work from that point and guess who may own all of the other addresses. This identity information might come from network analysis, surveillance, or just Googling the address. The officially encouraged practice of using a new address for every transaction is designed to make this attack more difficult.
[[File:Unknownaddress.png|thumb|The flow of Bitcoins is highly public.]]

The second image shows a simple example. Someone runs both a money exchanger and a site meant to trap people. When Mr. Doe buys from the exchanger and uses those same coins to buy something from the trap site, the attacker can '''prove''' that these two transactions were made by the same person. The block chain would show:
[[File:knownaddress.png|thumb|Finding an "identity anchor" allows you to ruin the anonymity of the system.]]
* Import coins from address A. Send 100 to B. Authorized by (signature).
* Import coins from address B. Send 100 to C. Authorized by (signature).
Bitcoin transactions do not have a [[From_address|"from" address]] but if the attacker believes that address B is controlled by Mr. Doe because the attacker received $5 from Mr. Doe's PayPal account and then sent 100 BTC to that address then they can infer the identity of the party sending to C. This assumption is not always correct because address B may have been an address held on behalf of Mr. Doe by a third party and the transaction to C may have been unrelated.

Another example: someone is scammed and posts the address they were using on the Bitcoin forum. It is possible to see which address they sent coins to. When coins are sent which were previously send to this (the scammer's) address, the addresses that receive them can also be easily found and posted on the forum. In this way, all of these coins are marked as "dirty", potentially over an infinite number of future transactions. When some smart and honest person notices that his address is now listed, he can reveal who he received those coins from. The Bitcoin community can now ask some pointed questions, "Who did you receive these coins from? What did you create this address for?" Eventually the original scammer will be found. Clearly, this becomes more difficult the more addresses that exist between the "target" and the "identity point".

You might be thinking that this attack is not feasible. But consider this case:
* You live in China and want to buy a "real" newspaper for Bitcoins.
* You join the Bitcoin forum and use your address as a signature. Since you are very helpful, you manage to get 30 BTC after a few months.
* Unfortunately, you choose poorly in who you buy the newspaper from: you've chosen a government agent! Maybe you are under the mistaken impression that Bitcoin is perfectly anonymous.
* The government agent looks at the block chain and Googles (or Baidus) every address in it. He finds your address in your signature on the Bitcoin forum. You've left enough personal information in your posts to be identified, so you are now scheduled to be "reeducated".

You need to protect yourself from both forward attacks (getting something that identifies you using coins that you got with methods that must remain secret, like the scammer example) and reverse attacks (getting something that must remain secret using coins that identify you, like the newspaper example).

==Staying Anonymous==

By necessity the history of all the bitcoins must be highly public. However, if one has bitcoins on paid to address, one can theoretically choose the coins they spend in a way that will minimize the amount of information they leak. Choosing personally generated coins or an address that you know doesn't reveal information would protect you. Unfortunately, the default Bitcoin client doesn't support this currently, so you must assume that your entire balance can identify you if any of the addresses can.

You may consider a bitcoin to be "less-anonymous" when an attacker could feasibly find the true identity of a very recent owner of the bitcoin, perhaps because one of the bitcoin addresses was posted to a website, or because he knows some identifying information through other means.

If your balance has been contaminated by both anonymous and non-anonymous coins, you may take action to make it "clean".

Recommended way of anonymizing your balance:
* Send however many coins you want to anonymize to a new [[eWallet]] account as a lump sum. There are other eWallet services however the more widely used the greater the potential for anonymity. <font color="red">This is not an endorsement of trust in the use of eWallet services. There are no guarantees that any eWallet service won't one day take all your bitcoins and disappear. Use at your own risk.</font>

With this method an attacker will have to gain access to the eWallet service's transaction logs to continue to follow you in the transaction history.

The protection that this method offers is significantly reduced if you are trying to anonymize more than about 10% of the total number of Bitcoins that the eWallet service holds. You'll end up getting your own coins back instead of other users' coins. Withdrawing Bitcoins more slowly and in smaller increments will help reduce this problem. Sending coins to an eWallet service in the largest single transfer possible will also help.

To further enhance your anonymity, you can:
* Send Bitcoins from one eWallet sevice to another and ''then'' to yourself. Each transfer needs to be painstakingly investigated and many transfers will present insurmountable difficulty.

Once you have an anonymous balance set up, be sure to keep your anonymous and non-anonymous balances completely separate.

A future version of the client will have more control which will allow the sender to specify which coins to use in a transaction<ref>[http://bitcointalk.org/index.php?topic=24784.msg307661#msg307661 Patching The Bitcoin Client To Make It More Anonymous]</ref>.

In the future, trusted relay servers operating on the [[friendly addresses with enhanced privacy]] protocol could provide bitcoin users strong anonymity with increased convenience, thereby eliminating the need to make a trade-off between privacy and ease of use.

===Helping other people stay anonymous===
* Set up a real [http://www.bitcointalk.org/index.php?topic=241.0 external mixing service]. Make it like an eWallet service but make sure that a user never withdraws the same coins that are put in. Also delete empty addresses and transaction logs.
* Even if you're not a programmer, you can make a slightly less secure version of an external mixing service (as a Tor hidden service, preferably):
** Set up two Bitcoin installations.
** Put some amount of BTC in installation B. This is the maximum amount of BTC you can deal with at once (for all customers).
** Customers send BTC to installation A. You send them an equal number of coins (or minus a fee) from installation B. Send as 10 to 50 BTC increments.
** Send all coins from A to B when '''all''' orders are satisfied. You can't send coins from A to B if you have any orders that have not been satisfied from B.
** This can be automated, or you can do everything manually.
* Put lots of bitcoins in an eWallet service and keep it there. If anyone uses the anonymization method described in "staying anonymous" above, this will enhance it. Send in smaller increments if a large amount is transferred.

==Legality==
Obviously, using Bitcoin anonymity techniques for the purposes of [[Wikipedia:money laundering|money laundering]] is illegal, but participating or running schemes which others use for money laundering may also be illegal or at least leave the participant vulnerable to accusations of aiding criminals and terrorists. Bitcoin anonymity techniques involving bitcoins worth large amounts of money (over some value between FJ$1,100 and US$58,000, depending on your jurisdiction) is illegal in most jurisdictions, being in violation of [[Wikipedia:Structuring|anti-structuring laws]].

==See Also==

* [[Anonymity & Security]]
* [[CoinJoin]]
* [[:Category:Mixing Services|Mixing Services]] category
* [http://www.bitcointalk.org/index.php?topic=2893.0 RFC: Bitcoin Mixnet]
* [http://www.bitcointalk.org/index.php?topic=241.0 anonymity]
* [http://www.bitcointalk.org/index.php?topic=24784.0 Patching The Bitcoin Client To Make It More Anonymous]
* [http://arxiv.org/abs/1107.4524 An Analysis of Anonymity in the Bitcoin System] research by Fergal Reid, Martin Harrigan ([http://bitcointalk.org/index.php?topic=31539.0 discussion])
* [http://bitcoinhelp.net/know/more/top-seven-ways-your-identity-can-be-linked-to-your-bitcoin-address Top Seven Ways Your Identity Can Be Linked to Your Bitcoin Address]

==References==
<references />

[[Category:Technical]]
[[Category:Anonymity]]

Transaction malleability

2015-04-12T19:43:15Z

Nayuki: Added link, corrected spelling

While [[transaction]]s are signed, the signature does not currently cover all the data in a transaction that is hashed to create the transaction hash. Thus while uncommon it is possible for a node on the network to change a transaction you send in such a way that the hash is invalidated. Note that this just changes the hash, the output of the transaction remains the same and the bitcoins will go to their intended recipient. However this does mean that, for instance, it is not safe to accept a chain of unconfirmed transactions under any circumstance because the later transactions will depend on the hashes of the previous transactions, and those hashes can be changed until they are confirmed in a block (and potentially even after a confirmation if the block chain is reorganized). In addition clients must always actively scan for transactions to them; assuming a txout exists because the client created it previously is unsafe.

== Signature Malleability ==

The first form of malleability is in the signatures themselves. Each signature has exactly one DER-encoded ASN.1 octet representation, but OpenSSL does not enforce this, and as long as a signature isn't horribly malformed, it will be accepted.<ref>https://bitcointalk.org/index.php?topic=8392.msg122410#msg122410</ref> In addition for every ECDSA signature (r,s), the signature (r, -s (mod N)) is a valid signature of the same message.<ref>https://bitcointalk.org/index.php?topic=8392.msg1245898#msg1245898</ref>

Efforts are underway to first make Bitcoin nodes not relay non-standard signatures, and eventually disallow them from being included in new blocks entirely.

== scriptSig Malleability ==

The [[OP_CHECKSIG|signature algorithm]] used in Bitcoin does not sign any of the scriptSig to create the signature. While signing the whole scriptSig would be impossible - the signature would be signing itself - this does mean that additional data can be added such that it will be pushed on the stack prior to the required signatures and public keys. Similarly OP_DROP can be added to leave the stack exactly as before prior to scriptPubKey execution.

Preventing scriptSig malleability is being considered as well. Currently transactions with anything other than data push operations in their scriptSig are considered non-standard and are not relayed, and eventually this rule may extend to enforcing that the stack have exactly one item after execution. However doing that may interfere with later extensions to Bitcoin.

==References==
<references/>

[[Category:Technical]]
[[Category:Developer]]