Bitcoin Wiki - User contributions [en]

Lazy API

2011-04-04T01:50:21Z

Hal: Add recheck step for safety

For the incredibly lazy and/or incompetent web developer, I present the lazy man's bitcoin API (copied from [http://www.bitcoin.org/smf/index.php?topic=4324.msg77187#msg77187 a forum post]):

'''Problem:'''

Lazy web designer (me) wants to use bitcoins without dealing with installing bitcoin on a server, installing a shopping card interface, or using ugly merchant services with callbacks.

'''Solution for sending bitcoins:'''

Use the [https://mtgox.com/support/tradeAPI MtGox API]

'''Solution for receiving bitcoins:'''
# Input a list of bitcoin receiving addresses to your database
# Give a bitcoin address to a potential customer
# Have the customer tell you when they have sent the coins and have at least 1 confirmation
# Check blockexplorer to see if they sent the right amount (i.e. http://blockexplorer.com/q/getreceivedbyaddress/19hMEAaRMbEhfSkeU4GT8mgSuyR4t4M6TH)
# Wait for more blocks (confirmations) if paranoid (look for the latest block number to go up here: http://blockexplorer.com/q/getblockcount)
# Recheck blockexplorer to make sure the address still shows the right amount, in case the block chain reorganizes
# Give them what they paid for
# After a reasonable amount of time has passed, you can re-use the address for another customer

You could avoid having a list of addresses and reusing them if one of the wallet services someday lets you get a new address via API call, but this will work for now.

'''Bad idea:'''

Selling bars of gold this way (owner of blockexplorer.com could rip you off)

'''Good(?) idea:'''

Selling naked pictures of your grandma this way (owner of blockexplorer.com won't bother)

'''Shameless begging:'''

If this info is useful to you, please consider a donation: 19hMEAaRMbEhfSkeU4GT8mgSuyR4t4M6TH

[[Category:Developer]]

Protocol rules

2011-03-16T22:44:17Z

Hal: /* "block" messages */ Add orphan block recursion

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

== [[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, size in bytes >= 100, and sig opcount <= 2
# Reject "nonstandard" transactions: scriptSig doing anything other than pushing numbers on the stack, or scriptPubkey not matching the two usual forms
# Reject if we already have matching tx in the pool, or in a block in the main branch
# Reject if any other tx in the pool uses the same transaction output as one used by this tx.
# 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 we are using the ''n''th output of the earlier transaction, but it has fewer than n+1 outputs, reject this transaction
# 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
# 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 this transaction
# 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
# Add to transaction pool
# "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

== [[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
# For the other transactions, reject if any input has hash=0, n=-1
# 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 before prev block (for a complicated definition of "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 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 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]]

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

Protocol rules

2011-03-16T22:19:43Z

Hal: First cut at final block rules

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

== [[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, size in bytes >= 100, and sig opcount <= 2
# Reject "nonstandard" transactions: scriptSig doing anything other than pushing numbers on the stack, or scriptPubkey not matching the two usual forms
# Reject if we already have matching tx in the pool, or in a block in the main branch
# Reject if any other tx in the pool uses the same transaction output as one used by this tx.
# 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 we are using the ''n''th output of the earlier transaction, but it has fewer than n+1 outputs, reject this transaction
# 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
# 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 this transaction
# 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
# Add to transaction pool
# "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

== [[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
# For the other transactions, reject if any input has hash=0, n=-1
# 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 before prev block (for a complicated definition of "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 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 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

== See Also ==

* [[Protocol specification]]

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

Protocol rules

2011-03-15T22:17:55Z

Hal: Add some links

Protocol rules

2011-03-15T01:19:49Z

Hal: Call the main chain the main branch

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

# 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, size in bytes >= 100, and sig opcount <= 2
# Reject "nonstandard" transactions: scriptSig doing anything other than pushing numbers on the stack, or scriptPubkey not matching the two usual forms
# Reject if we already have matching tx in the pool, or in a block in the main branch
# Reject if any other tx in the pool uses the same transaction output as one used by this tx.
# 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 we are using the ''n''th output of the earlier transaction, but it has fewer than n+1 outputs, reject this transaction
# 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
# 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 or the transaction pool, reject this transaction
# 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
# Add to transaction pool
# 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

=== "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
# For the other transactions, reject if any input has hash=0, n=-1
# 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 before prev block (for a complicated definition of "before")
# For certain blocks, on initial block download, check that hash is what it should be

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

Protocol rules

2011-03-14T03:28:28Z

Hal: More on blocks

== 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 and next 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 chain
: the transactions in these blocks are considered at least tentatively confirmed

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

;orphan blocks
: these are blocks which don't link into the main chain, 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.) Following the next pointers from the root defines the main chain.

=== "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, size in bytes >= 100, and sig opcount <= 2
# Reject "nonstandard" transactions: scriptSig doing anything other than pushing numbers on the stack, or scriptPubkey not matching the two usual forms
# Reject if we already have matching tx in the pool, or in a block in the main chain
# Reject if any other tx in the pool uses the same transaction output as one used by this tx.
# For each input, look in the main chain 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 we are using the ''n''th output of the earlier transaction, but it has fewer than n+1 outputs, reject this transaction
# 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
# 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 chain or the transaction pool, reject this transaction
# 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
# Add to transaction pool
# 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

=== "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
# For the other transactions, reject if any input has hash=0, n=-1
# Reject if sum of transaction sig opcounts > MAX_BLOCK_SIGOPS
# Verify Merkle hash
# Check if prev block (matching ''prev'' hash) is in main chain or side chains. 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 before prev block (for a complicated definition of "before")
# For certain blocks, on initial block download, check that hash is what it should be

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

Protocol rules

2011-03-14T01:09:15Z

Hal: Starting blocks

== 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 and next 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 chain
: the transactions in these blocks are considered at least tentatively confirmed

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

;orphan blocks
: these are blocks which don't link into the main chain, 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.) Following the next pointers from the root defines the main chain.

=== "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, size in bytes >= 100, and sig opcount <= 2
# Reject "nonstandard" transactions: scriptSig doing anything other than pushing numbers on the stack, or scriptPubkey not matching the two usual forms
# Reject if we already have matching tx in the pool, or in a block in the main chain
# Reject if any other tx in the pool uses the same transaction output as one used by this tx.
# For each input, look in the main chain 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 we are using the ''n''th output of the earlier transaction, but it has fewer than n+1 outputs, reject this transaction
# 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
# 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 chain or the transaction pool, reject this transaction
# 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
# Add to transaction pool
# 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

=== "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
# For the other transactions, reject if any input has hash=0, n=-1
# Reject if sum of transaction sig opcounts > MAX_BLOCK_SIGOPS
# Verify Merkle hash
# Apply the following tests to all but the coinbase transactions:
## For each input, look in the main chain for the referenced output transaction

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

Protocol rules

2011-03-14T00:39:05Z

Hal: Finish first cut at tx 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 and next 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 chain
: the transactions in these blocks are considered at least tentatively confirmed

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

;orphan blocks
: these are blocks which don't link into the main chain, 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.) Following the next pointers from the root defines the main chain.

=== "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, size in bytes >= 100, and sig opcount <= 2
# Reject "nonstandard" transactions: scriptSig doing anything other than pushing numbers on the stack, or scriptPubkey not matching the two usual forms
# Reject if we already have matching tx in the pool, or in a block in the main chain
# Reject if any other tx in the pool uses the same transaction output as one used by this tx.
# For each input, look in the main chain 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 we are using the ''n''th output of the earlier transaction, but it has fewer than n+1 outputs, reject this transaction
# 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
# 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 chain or the transaction pool, reject this transaction
# 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
# Add to transaction pool
# 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

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

Protocol rules

2011-03-13T22:59:34Z

Hal: Initially, about half the tx rules are done

Transaction

2011-02-09T19:06:42Z

Hal: /* Verification */ Clarify that scripts are not concatenated

A transaction is a signed section of data that is broadcast to the [[network]] and collected into [[block|blocks]]. They reference a previous transaction and dedicate a certain number of bitcoins from it to a new public key (Bitcoin address). They are not encrypted (nothing in Bitcoin is encrypted).

[[Block Explorer]] is a site where every transaction included within the block chain can be view/browsed. This is useful for seeing the technical details of transaction in action, and for payment verification purposes.

=== Example Bitcoin Transaction ===

==== 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 in a different transaction. Multiple inputs are often listed in a transaction. The values of the referenced outputs are added up, and the total is usable in the outputs of this 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 belongs to the redeemer of the output transaction and proves the creator is allowed to redeem the outputs value. The other 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 nanocoins that this output will be worth when claimed (1 bitcoin = 100,000,000 nanocoins). '''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 an output can only ever be referenced by a single input, 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 B'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 only creates three different scriptSig/scriptPubKey pairs, however. These are:

==== Transfer to IP address ====

scriptPubKey: <pubKey> OP_CHECKSIG
scriptSig: <sig>
The sender gets the public key when talking to the recipient over IP. When redeeming coins that have been sent to an IP address, the recipient provides only a signature. The signature is checked against the public key in scriptPubKey.

Checking process:
{| class="wikitable"
|-
! Stack
! Script
! Description
|-
|Empty.
|<sig> <pubKey> OP_CHECKSIG
|scriptSig and scriptPubKey are combined.
|-
|<sig> <pubKey>
| OP_CHECKSIG
|Constants are added to the stack.
|-
|true
|Empty.
|Signature is checked for top two stack items.
|}

==== Transfer to Bitcoin address ====

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

==== Generation ====

Generations have a single input, and this input has a "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.

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

OP CHECKSIG

2011-01-25T00:36:33Z

Hal: Add SIGHASH_ALL, other minor changes

OP_CHECKSIG is used to verify that a signature for a tx output is valid

== Parameters ==

In addition to the script code itself, to operate OP_CHECKSIG needs to know the current transaction, the current transaction input, and the current hashtype (discussed later)

== How it works ==

# the public key and the signature are popped from the stack, in that order.
# A new subscript is created from the instruction from the most recent OP_CODESEPARATOR to the end of the script. If there is no OP_CODESEPARATOR the entire script becomes the subscript (hereby referred to as subScript)
# The sig is deleted from subScript.
# The hashtype is removed from the last byte of the sig and stored
# A deep copy is made of the current transaction (hereby referred to txCopy)
# All OP_CODESEPARATORS are removed from subScript
# The scripts for all transaction inputs in txCopy are set to empty scripts
# The script for the current transaction input in txCopy is set to subScript

Now depending on the hashtype various things can happen to txCopy, these will be discussed individually

=== Hashtype SIGHASH_ALL (default) ===

No special handling occurs in the default case

=== Hashtype SIGHASH_NONE ===

# The output of txCopy is set to a vector of zero size.
# All other inputs aside from the current input in txCopy have their nSequence index set to zero

=== Hashtype SIGHASH_SINGLE ===

# The output of txCopy is resized to the size of the current input index+1
# All other txCopy outputs aside from the output that is the same as the current input index are set to a blank script and a value of (long) -1;
# All other txCopy inputs aside from the current input are set to have an nSequence index of zero

=== Hashtype SIGHASH_ANYONECANPAY ===

# The txCopy input vector is resized to a length of one
# The current input is set as the first and only member of this vector

== Final signature ==

An array of bytes is constructed from the serialized txCopy + four bytes for the hash type. This array is sha256 hashed twice, then the public key is used to to check the supplied signature against the hash.

== Return values ==

OP_CHECKSIG will push true to the stack if the check passed, false otherwise.
OP_CHECKSIG_VERIFY leaves nothing on the stack but will cause the script eval to fail immediately if the check does not pass.

Protocol documentation

2011-01-03T23:56:19Z

Hal: /* block */ Add transactions

Sources:
* [[Original Bitcoin client]] source
* [http://www.bitcoin.org/wiki/doku.php?id=bitcoins_draft_spec_0_0_1 Draft spec on bitcoin wiki]

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

== 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 desireable (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)

=== Signatures ===

Bitcoin uses [http://en.wikipedia.org/wiki/Elliptic_curve_cryptography Elliptic Curve] [http://en.wikipedia.org/wiki/Digital_Signature_Algorithm Digital Signature Algorithm] (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 strings representing the coordinates of a point on the curve.

=== Transaction Verification ===

The first transaction of a block is usually the generating transaction, which do not include any "in" transaction, and generate bitcoins (from fees for example) usually received by whoever solved the block containing this transaction.
Such transactions are called a "coinbase transaction" and are accepted by bitcoin clients without any need to execute scripts, provided there is only one per block.

If a transaction is not a coinbase, it references previous transaction hashes as input, and the index of the other transaction's output used as input for this transaction.
The script from the in part of this transaction is executed.
Then the script from the out part of the referenced transaction is executed.
It is considered valid if the top element of the stack is true.

=== 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
|-
| 4 || checksum || uint32_t || First 4 bytes of sha256(sha256(payload))
|-
| ? || payload || char[] || The actual data (can be empty, in which case checksum is excluded, and length is set to 0
|}

Known magic values:

{|class="wikitable"
! Network !! Magic value
|-
| main || F9BEB4D9
|-
| testnet || FABFB5DA
|}

=== Variable length integer ===

Integer can be encoded depending on the represented value to save space.

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

=== 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 || 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 (currently only supports ipv4).

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8 || services || uint64_t || ?
|-
| 12 || reserved || char[12] || Reserved for ipv6 support
|-
| 4 || ipv4 || uint32_t || IPv4 address, network byte order
|-
| 2 || port || uint16_t || port number, network byte order
|}

=== Inventory Vectors ===

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

Inventory vectors consist of the following data format:

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

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

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

Other Data Type values are considered reserved for future implementations.

== Message types ==

=== version ===

When a node receives an incoming connection, it will immediatly advertise its version. No futher communication is possible until both peers have exchanged their version.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || uint32_t || Identifies protocol version being used by the node
|-
| 8 || services || uint64_t || bitfield of features to be enabled for this connection
|-
| 8 || timestamp || uint64_t || standard UNIX timestamp in seconds
|-
| 26 || addr_me || net_addr || The network address of the node emitting this message
|-
|colspan="4"| version >= 106
|-
| 26 || addr_you || net_addr || The network address seen by the node emitting this message (ie, the address of the receiving node)
|-
| 8 || nonce || uint64_t || Node random unique id. This id is used to detect connections to self
|-
| ? || sub_version_num || var_str || Secondary Version information (null terminated?)
|-
|colspan="4"| version >= 209
|-
| 4 || start_height || uint32_t || The last block received by the emitting node
|}

If the emitter of the packet has version >= 209, 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.
|}

=== verack ===

The ''verack'' packet is sent in reply to ''version'' for clients >= 209.

=== addr ===

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

Payload (maximum payload length: 1000 bytes):

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || count || var_int || Number of address entries
|-
| 26x? || addr_list || net_addr[] || Address of other nodes on the network. version < 209 will only read the first one
|}

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

=== inv ===

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

Payload (maximum payload length: 50000 bytes):

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || count || var_int || Number of inventory entries
|-
| 36x? || inventory || 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.

Payload (maximum payload length: 50000 bytes):

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

=== getblocks ===

Return an ''inv'' packet containing the list of blocks starting at hash_start, up to hash_stop or 500 blocks, whichever comes first. To receive the next blocks hashes, one needs to issue getblocks again with the last known hash.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || uint32_t || only present if nType has SER_GETHASH set (purpose unknown)
|-
| 1+ || start count || variable length integer || number of hash_start entries
|-
| 32+ || hash_start || char[32] || hash of the last known block of the emitting node
|-
| 32 || hash_stop || char[32] || hash of the last desired block. Set to zero to get as many blocks as possible (500)
|}

=== tx ===

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

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || uint32_t || Transaction data format version
|-
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins
|-
| 8+ || 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, or 0 if the transaction is always locked. A non-locked transaction must not be included in blocks, and it can be modified by broadcasting a new version before the time has expired (replacement is currently disabled in Bitcoin, however, so this is useless).
|}

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
|-
| ? || signature || script || Computational Script for confirming transaction authorization
|-
| 4 || 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 for more information)

The TxOut structure consists of the following fields:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8 || value || uint64_t || Transaction Value
|-
| ? || pk_script || script || Usually contains the public key as a Bitcoin script setting up conditions to claim this output.
|}

=== block ===

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

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || uint32_t || Block version information, based upon the software version creating this block
|-
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references
|-
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block
|-
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Limited to 2038!)
|-
| 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
|-
| ? || txn_count || var_int || Number of transaction entries
|-
| ? || txns || tx[] || Block transactions, in format of "tx" command
|}

=== getaddr ===

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

No additional data is transmitted with this message.

=== checkorder ===

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

It contains a CWalletTx object

Payload:

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

=== submitorder ===

Confirms an order has been submitted.

Payload:

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

=== reply ===

Generic reply for [[IP Transactions]]

Payload:

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

Possible values:

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

=== ping ===

The ''ping'' message is sent primarily to confirm that the TCP/IP connection is still valid. An error in transmission is presumed to be a closed connection and the address is removed as a current peer. No reply is expected as a result of this message being sent nor any sort of action expected on the part of a client when it is used.

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

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || message || var_str || System message which is coded to convey some information to all nodes in the network
|-
| ? || signature || var_str || A signature which can be confirmed with a public key verifying that it is Satoshi (the originator of Bitcoins) who has "authorized" or created the message
|}

The signature is to be compared to this ECDSA public key:

04fc9702847840aaf195de8442ebecedf5b095cdbb9bc716bda9110971b28a49e0ead8564ff0db22209e0374782c093bb899692d524e9d6a6956e7c5ecbcd68284
(hash) 1AGRxqDa5WjUKBwHB9XYEjmkv1ucoUUy1s

Source: [http://www.bitcoin.org/smf/index.php?topic=898.0]

== Scripting ==

See [http://www.bitcoin.org/wiki/doku.php?id=script] (TODO)

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

Protocol documentation

2011-01-03T23:50:12Z

Hal: /* addr */ Preceded by count

Sources:
* [[Original Bitcoin client]] source
* [http://www.bitcoin.org/wiki/doku.php?id=bitcoins_draft_spec_0_0_1 Draft spec on bitcoin wiki]

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

== 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 desireable (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)

=== Signatures ===

Bitcoin uses [http://en.wikipedia.org/wiki/Elliptic_curve_cryptography Elliptic Curve] [http://en.wikipedia.org/wiki/Digital_Signature_Algorithm Digital Signature Algorithm] (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 strings representing the coordinates of a point on the curve.

=== Transaction Verification ===

The first transaction of a block is usually the generating transaction, which do not include any "in" transaction, and generate bitcoins (from fees for example) usually received by whoever solved the block containing this transaction.
Such transactions are called a "coinbase transaction" and are accepted by bitcoin clients without any need to execute scripts, provided there is only one per block.

If a transaction is not a coinbase, it references previous transaction hashes as input, and the index of the other transaction's output used as input for this transaction.
The script from the in part of this transaction is executed.
Then the script from the out part of the referenced transaction is executed.
It is considered valid if the top element of the stack is true.

=== 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
|-
| 4 || checksum || uint32_t || First 4 bytes of sha256(sha256(payload))
|-
| ? || payload || char[] || The actual data (can be empty, in which case checksum is excluded, and length is set to 0
|}

Known magic values:

{|class="wikitable"
! Network !! Magic value
|-
| main || F9BEB4D9
|-
| testnet || FABFB5DA
|}

=== Variable length integer ===

Integer can be encoded depending on the represented value to save space.

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

=== 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 || 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 (currently only supports ipv4).

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8 || services || uint64_t || ?
|-
| 12 || reserved || char[12] || Reserved for ipv6 support
|-
| 4 || ipv4 || uint32_t || IPv4 address, network byte order
|-
| 2 || port || uint16_t || port number, network byte order
|}

=== Inventory Vectors ===

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

Inventory vectors consist of the following data format:

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

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

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

Other Data Type values are considered reserved for future implementations.

== Message types ==

=== version ===

When a node receives an incoming connection, it will immediatly advertise its version. No futher communication is possible until both peers have exchanged their version.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || uint32_t || Identifies protocol version being used by the node
|-
| 8 || services || uint64_t || bitfield of features to be enabled for this connection
|-
| 8 || timestamp || uint64_t || standard UNIX timestamp in seconds
|-
| 26 || addr_me || net_addr || The network address of the node emitting this message
|-
|colspan="4"| version >= 106
|-
| 26 || addr_you || net_addr || The network address seen by the node emitting this message (ie, the address of the receiving node)
|-
| 8 || nonce || uint64_t || Node random unique id. This id is used to detect connections to self
|-
| ? || sub_version_num || var_str || Secondary Version information (null terminated?)
|-
|colspan="4"| version >= 209
|-
| 4 || start_height || uint32_t || The last block received by the emitting node
|}

If the emitter of the packet has version >= 209, 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.
|}

=== verack ===

The ''verack'' packet is sent in reply to ''version'' for clients >= 209.

=== addr ===

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

Payload (maximum payload length: 1000 bytes):

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || count || var_int || Number of address entries
|-
| 26x? || addr_list || net_addr[] || Address of other nodes on the network. version < 209 will only read the first one
|}

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

=== inv ===

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

Payload (maximum payload length: 50000 bytes):

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || count || var_int || Number of inventory entries
|-
| 36x? || inventory || 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.

Payload (maximum payload length: 50000 bytes):

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

=== getblocks ===

Return an ''inv'' packet containing the list of blocks starting at hash_start, up to hash_stop or 500 blocks, whichever comes first. To receive the next blocks hashes, one needs to issue getblocks again with the last known hash.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || uint32_t || only present if nType has SER_GETHASH set (purpose unknown)
|-
| 1+ || start count || variable length integer || number of hash_start entries
|-
| 32+ || hash_start || char[32] || hash of the last known block of the emitting node
|-
| 32 || hash_stop || char[32] || hash of the last desired block. Set to zero to get as many blocks as possible (500)
|}

=== tx ===

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

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || uint32_t || Transaction data format version
|-
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins
|-
| 8+ || 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, or 0 if the transaction is always locked. A non-locked transaction must not be included in blocks, and it can be modified by broadcasting a new version before the time has expired (replacement is currently disabled in Bitcoin, however, so this is useless).
|}

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
|-
| ? || signature || script || Computational Script for confirming transaction authorization
|-
| 4 || 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 for more information)

The TxOut structure consists of the following fields:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8 || value || uint64_t || Transaction Value
|-
| ? || pk_script || script || Usually contains the public key as a Bitcoin script setting up conditions to claim this output.
|}

=== block ===

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

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || uint32_t || Block version information, based upon the software version creating this block
|-
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references
|-
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block
|-
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Limited to 2038!)
|-
| 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
|}

=== getaddr ===

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

No additional data is transmitted with this message.

=== checkorder ===

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

It contains a CWalletTx object

Payload:

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

=== submitorder ===

Confirms an order has been submitted.

Payload:

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

=== reply ===

Generic reply for [[IP Transactions]]

Payload:

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

Possible values:

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

=== ping ===

The ''ping'' message is sent primarily to confirm that the TCP/IP connection is still valid. An error in transmission is presumed to be a closed connection and the address is removed as a current peer. No reply is expected as a result of this message being sent nor any sort of action expected on the part of a client when it is used.

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

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || message || var_str || System message which is coded to convey some information to all nodes in the network
|-
| ? || signature || var_str || A signature which can be confirmed with a public key verifying that it is Satoshi (the originator of Bitcoins) who has "authorized" or created the message
|}

The signature is to be compared to this ECDSA public key:

04fc9702847840aaf195de8442ebecedf5b095cdbb9bc716bda9110971b28a49e0ead8564ff0db22209e0374782c093bb899692d524e9d6a6956e7c5ecbcd68284
(hash) 1AGRxqDa5WjUKBwHB9XYEjmkv1ucoUUy1s

Source: [http://www.bitcoin.org/smf/index.php?topic=898.0]

== Scripting ==

See [http://www.bitcoin.org/wiki/doku.php?id=script] (TODO)

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

Protocol documentation

2011-01-01T20:09:15Z

Hal: /* Addresses */ Add version byte

Sources:
* [[Original Bitcoin client]] source
* [http://www.bitcoin.org/wiki/doku.php?id=bitcoins_draft_spec_0_0_1 Draft spec on bitcoin wiki]

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

== 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 desireable (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)

=== Signatures ===

Bitcoin uses [http://en.wikipedia.org/wiki/Elliptic_curve_cryptography Elliptic Curve] [http://en.wikipedia.org/wiki/Digital_Signature_Algorithm Digital Signature Algorithm] (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 strings representing the coordinates of a point on the curve.

=== Transaction Verification ===

The first transaction of a block is usually the generating transaction, which do not include any "in" transaction, and generate bitcoins (from fees for example) usually received by whoever solved the block containing this transaction.
Such transactions are called a "coinbase transaction" and are accepted by bitcoin clients without any need to execute scripts, provided there is only one per block.

If a transaction is not a coinbase, it references previous transaction hashes as input, and the index of the other transaction's output used as input for this transaction.
The script from the in part of this transaction is executed.
Then the script from the out part of the referenced transaction is executed.
It is considered valid if the top element of the stack is true.

=== 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
|-
| 4 || checksum || uint32_t || First 4 bytes of sha256(sha256(payload))
|-
| ? || payload || char[] || The actual data (can be empty, in which case checksum is excluded, and length is set to 0
|}

Known magic values:

{|class="wikitable"
! Network !! Magic value
|-
| main || F9BEB4D9
|-
| testnet || FABFB5DA
|}

=== Variable length integer ===

Integer can be encoded depending on the represented value to save space.

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

=== 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 || 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 (currently only supports ipv4).

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8 || services || uint64_t || ?
|-
| 12 || reserved || char[12] || Reserved for ipv6 support
|-
| 4 || ipv4 || uint32_t || IPv4 address, network byte order
|-
| 2 || port || uint16_t || port number, network byte order
|}

=== Inventory Vectors ===

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

Inventory vectors consist of the following data format:

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

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

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

Other Data Type values are considered reserved for future implementations.

== Message types ==

=== version ===

When a node receives an incoming connection, it will immediatly advertise its version. No futher communication is possible until both peers have exchanged their version.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || uint32_t || Identifies protocol version being used by the node
|-
| 8 || services || uint64_t || bitfield of features to be enabled for this connection
|-
| 8 || timestamp || uint64_t || standard UNIX timestamp in seconds
|-
| 26 || addr_me || net_addr || The network address of the node emitting this message
|-
|colspan="4"| version >= 106
|-
| 26 || addr_you || net_addr || The network address seen by the node emitting this message (ie, the address of the receiving node)
|-
| 8 || nonce || uint64_t || Node random unique id. This id is used to detect connections to self
|-
| ? || sub_version_num || var_str || Secondary Version information (null terminated?)
|-
|colspan="4"| version >= 209
|-
| 4 || start_height || uint32_t || The last block received by the emitting node
|}

If the emitter of the packet has version >= 209, 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.
|}

=== verack ===

The ''verack'' packet is sent in reply to ''version'' for clients >= 209.

=== addr ===

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

Payload (maximum payload length: 1000 bytes):

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 26x? || addr_list || net_addr[] || Address of other nodes on the network. version < 209 will only read the first one
|}

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

=== inv ===

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

Payload (maximum payload length: 50000 bytes):

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || count || var_int || Number of inventory entries
|-
| 36x? || inventory || 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.

Payload (maximum payload length: 50000 bytes):

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

=== getblocks ===

Return an ''inv'' packet containing the list of blocks starting at hash_start, up to hash_stop or 500 blocks, whichever comes first. To receive the next blocks hashes, one needs to issue getblocks again with the last known hash.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || uint32_t || only present if nType has SER_GETHASH set (purpose unknown)
|-
| 1+ || start count || variable length integer || number of hash_start entries
|-
| 32+ || hash_start || char[32] || hash of the last known block of the emitting node
|-
| 32 || hash_stop || char[32] || hash of the last desired block. Set to zero to get as many blocks as possible (500)
|}

=== tx ===

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

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || uint32_t || Transaction data format version
|-
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins
|-
| 8+ || 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, or 0 if the transaction is always locked. A non-locked transaction must not be included in blocks, and it can be modified by broadcasting a new version before the time has expired (replacement is currently disabled in Bitcoin, however, so this is useless).
|}

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
|-
| ? || signature || script || Computational Script for confirming transaction authorization
|-
| 4 || 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 for more information)

The TxOut structure consists of the following fields:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8 || value || uint64_t || Transaction Value
|-
| ? || pk_script || script || Usually contains the public key as a Bitcoin script setting up conditions to claim this output.
|}

=== block ===

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

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || uint32_t || Block version information, based upon the software version creating this block
|-
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references
|-
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block
|-
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Limited to 2038!)
|-
| 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
|}

=== getaddr ===

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

No additional data is transmitted with this message.

=== checkorder ===

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

It contains a CWalletTx object

Payload:

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

=== submitorder ===

Confirms an order has been submitted.

Payload:

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

=== reply ===

Generic reply for [[IP Transactions]]

Payload:

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

Possible values:

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

=== ping ===

The ''ping'' message is sent primarily to confirm that the TCP/IP connection is still valid. An error in transmission is presumed to be a closed connection and the address is removed as a current peer. No reply is expected as a result of this message being sent nor any sort of action expected on the part of a client when it is used.

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

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || message || var_str || System message which is coded to convey some information to all nodes in the network
|-
| ? || signature || var_str || A signature which can be confirmed with a public key verifying that it is Satoshi (the originator of Bitcoins) who has "authorized" or created the message
|}

The signature is to be compared to this ECDSA public key:

04fc9702847840aaf195de8442ebecedf5b095cdbb9bc716bda9110971b28a49e0ead8564ff0db22209e0374782c093bb899692d524e9d6a6956e7c5ecbcd68284
(hash) 1AGRxqDa5WjUKBwHB9XYEjmkv1ucoUUy1s

Source: [http://www.bitcoin.org/smf/index.php?topic=898.0]

== Scripting ==

See [http://www.bitcoin.org/wiki/doku.php?id=script] (TODO)

[[Category:Technical]]

Protocol documentation

2011-01-01T19:54:32Z

Hal: /* Addresses */ Describe checksum

Sources:
* [[Original Bitcoin client]] source
* [http://www.bitcoin.org/wiki/doku.php?id=bitcoins_draft_spec_0_0_1 Draft spec on bitcoin wiki]

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

== 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 desireable (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)

=== Signatures ===

Bitcoin uses [http://en.wikipedia.org/wiki/Elliptic_curve_cryptography Elliptic Curve] [http://en.wikipedia.org/wiki/Digital_Signature_Algorithm Digital Signature Algorithm] (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 strings representing the coordinates of a point on the curve.

=== Transaction Verification ===

The first transaction of a block is usually the generating transaction, which do not include any "in" transaction, and generate bitcoins (from fees for example) usually received by whoever solved the block containing this transaction.
Such transactions are called a "coinbase transaction" and are accepted by bitcoin clients without any need to execute scripts, provided there is only one per block.

If a transaction is not a coinbase, it references previous transaction hashes as input, and the index of the other transaction's output used as input for this transaction.
The script from the in part of this transaction is executed.
Then the script from the out part of the referenced transaction is executed.
It is considered valid if the top element of the stack is true.

=== Addresses ===

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

Key hash = 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
|-
| 4 || checksum || uint32_t || First 4 bytes of sha256(sha256(payload))
|-
| ? || payload || char[] || The actual data (can be empty, in which case checksum is excluded, and length is set to 0
|}

Known magic values:

{|class="wikitable"
! Network !! Magic value
|-
| main || F9BEB4D9
|-
| testnet || FABFB5DA
|}

=== Variable length integer ===

Integer can be encoded depending on the represented value to save space.

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

=== 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 || 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 (currently only supports ipv4).

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8 || services || uint64_t || ?
|-
| 12 || reserved || char[12] || Reserved for ipv6 support
|-
| 4 || ipv4 || uint32_t || IPv4 address, network byte order
|-
| 2 || port || uint16_t || port number, network byte order
|}

=== Inventory Vectors ===

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

Inventory vectors consist of the following data format:

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

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

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

Other Data Type values are considered reserved for future implementations.

== Message types ==

=== version ===

When a node receives an incoming connection, it will immediatly advertise its version. No futher communication is possible until both peers have exchanged their version.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || uint32_t || Identifies protocol version being used by the node
|-
| 8 || services || uint64_t || bitfield of features to be enabled for this connection
|-
| 8 || timestamp || uint64_t || standard UNIX timestamp in seconds
|-
| 26 || addr_me || net_addr || The network address of the node emitting this message
|-
|colspan="4"| version >= 106
|-
| 26 || addr_you || net_addr || The network address seen by the node emitting this message (ie, the address of the receiving node)
|-
| 8 || nonce || uint64_t || Node random unique id. This id is used to detect connections to self
|-
| ? || sub_version_num || var_str || Secondary Version information (null terminated?)
|-
|colspan="4"| version >= 209
|-
| 4 || start_height || uint32_t || The last block received by the emitting node
|}

If the emitter of the packet has version >= 209, 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.
|}

=== verack ===

The ''verack'' packet is sent in reply to ''version'' for clients >= 209.

=== addr ===

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

Payload (maximum payload length: 1000 bytes):

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 26x? || addr_list || net_addr[] || Address of other nodes on the network. version < 209 will only read the first one
|}

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

=== inv ===

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

Payload (maximum payload length: 50000 bytes):

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || count || var_int || Number of inventory entries
|-
| 36x? || inventory || 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.

Payload (maximum payload length: 50000 bytes):

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

=== getblocks ===

Return an ''inv'' packet containing the list of blocks starting at hash_start, up to hash_stop or 500 blocks, whichever comes first. To receive the next blocks hashes, one needs to issue getblocks again with the last known hash.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || uint32_t || only present if nType has SER_GETHASH set (purpose unknown)
|-
| 1+ || start count || variable length integer || number of hash_start entries
|-
| 32+ || hash_start || char[32] || hash of the last known block of the emitting node
|-
| 32 || hash_stop || char[32] || hash of the last desired block. Set to zero to get as many blocks as possible (500)
|}

=== tx ===

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

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || uint32_t || Transaction data format version
|-
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins
|-
| 8+ || 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, or 0 if the transaction is always locked. A non-locked transaction must not be included in blocks, and it can be modified by broadcasting a new version before the time has expired (replacement is currently disabled in Bitcoin, however, so this is useless).
|}

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
|-
| ? || signature || script || Computational Script for confirming transaction authorization
|-
| 4 || 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 for more information)

The TxOut structure consists of the following fields:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8 || value || uint64_t || Transaction Value
|-
| ? || pk_script || script || Usually contains the public key as a Bitcoin script setting up conditions to claim this output.
|}

=== block ===

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

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || uint32_t || Block version information, based upon the software version creating this block
|-
| 32 || prev_block || char[32] || The hash value of the previous block this particular block references
|-
| 32 || merkle_root || char[32] || The reference to a Merkle tree collection which is a hash of all transactions related to this block
|-
| 4 || timestamp || uint32_t || A timestamp recording when this block was created (Limited to 2038!)
|-
| 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
|}

=== getaddr ===

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

No additional data is transmitted with this message.

=== checkorder ===

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

It contains a CWalletTx object

Payload:

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

=== submitorder ===

Confirms an order has been submitted.

Payload:

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

=== reply ===

Generic reply for [[IP Transactions]]

Payload:

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

Possible values:

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

=== ping ===

The ''ping'' message is sent primarily to confirm that the TCP/IP connection is still valid. An error in transmission is presumed to be a closed connection and the address is removed as a current peer. No reply is expected as a result of this message being sent nor any sort of action expected on the part of a client when it is used.

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

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || message || var_str || System message which is coded to convey some information to all nodes in the network
|-
| ? || signature || var_str || A signature which can be confirmed with a public key verifying that it is Satoshi (the originator of Bitcoins) who has "authorized" or created the message
|}

The signature is to be compared to this ECDSA public key:

04fc9702847840aaf195de8442ebecedf5b095cdbb9bc716bda9110971b28a49e0ead8564ff0db22209e0374782c093bb899692d524e9d6a6956e7c5ecbcd68284
(hash) 1AGRxqDa5WjUKBwHB9XYEjmkv1ucoUUy1s

Source: [http://www.bitcoin.org/smf/index.php?topic=898.0]

== Scripting ==

See [http://www.bitcoin.org/wiki/doku.php?id=script] (TODO)

[[Category:Technical]]