Protocol rules

Rules for clients

The wiki substantially documents the 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 transactions and blocks. 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.

"tx" messages

These messages hold a single transaction.

1. Check syntactic correctness
2. Make sure neither in or out lists are empty
3. Size in bytes < MAX_BLOCK_SIZE
4. Each output value, as well as the total, must be in legal money range
5. Make sure none of the inputs have hash=0, n=-1 (coinbase transactions)
6. Check that nLockTime <= INT_MAX, size in bytes >= 100, and sig opcount <= 2
7. Reject "nonstandard" transactions: scriptSig doing anything other than pushing numbers on the stack, or scriptPubkey not matching the two usual forms
8. Reject if we already have matching tx in the pool, or in a block in the main branch
9. Reject if any other tx in the pool uses the same transaction output as one used by this tx.
10. 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.
11. For each input, if we are using the nth output of the earlier transaction, but it has fewer than n+1 outputs, reject this transaction
12. 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 confirmations; else reject this transaction
13. Verify crypto signatures for each input; reject if any are bad
14. For each input, if the referenced output has already been spent by a transaction in the main branch or the transaction pool, reject this transaction
15. Using the referenced output transactions to get input values, check that each input value, as well as the sum, are in legal money range
16. Reject if the sum of input values < sum of output values
17. 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
18. Add to transaction pool
19. Add to wallet if mine
20. Relay transaction to peers
21. For each orphan transaction that uses this one as one of its inputs, run all these steps (including this one) recursively on that orphan

"block" messages

These messages hold a single block.

1. Check syntactic correctness
2. Reject if duplicate of block we have in any of the three categories
3. Transaction list must be non-empty
4. Block hash must satisfy claimed nBits proof of work
5. Block timestamp must not be more than two hours in the future
6. First transaction must be coinbase (i.e. only 1 input, with hash=0, n=-1), the rest must not be
7. For each transaction, apply "tx" checks 2-4
8. For the coinbase (first) transaction, scriptSig length must be 2-100
9. For the other transactions, reject if any input has hash=0, n=-1
10. Reject if sum of transaction sig opcounts > MAX_BLOCK_SIGOPS
11. Verify Merkle hash
12. 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
13. Check that nBits value matches the difficulty rules
14. Reject if timestamp is before prev block (for a complicated definition of "before")
15. For certain blocks, on initial block download, check that hash is what it should be