Bitcoin Wiki - User contributions [en]

Protocol rules

2011-05-27T03:45:52Z

X6763: /* "tx" messages */

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

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

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

These messages hold a single block.

# Check syntactic correctness
# Reject if duplicate of block we have in any of the three categories
# Transaction list must be non-empty
# Block hash must satisfy claimed ''nBits'' proof of work
# Block timestamp must not be more than two hours in the future
# First transaction must be coinbase (i.e. only 1 input, with hash=0, n=-1), the rest must not be
# For each transaction, apply "tx" checks 2-4
# For the coinbase (first) transaction, scriptSig length must be 2-100
# Reject if sum of transaction sig opcounts > MAX_BLOCK_SIGOPS
# Verify Merkle hash
# Check if prev block (matching ''prev'' hash) is in main branch or side branches. If not, add this to orphan blocks, then query peer we got this from for 1st missing orphan block in ''prev'' chain; done with block
# Check that ''nBits'' value matches the difficulty rules
# Reject if timestamp is before the median time of the last 11 blocks
# 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-05-27T03:26:14Z

X6763: /* "tx" messages */ The global blockchain (not the latency-vulnerable, potentially inconsistent between nodes, in-memory transaction pool) is what prevents double-spending.

'''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<ref>nLockTime must not exceed 31 bits, as some clients will interpret it incorrectly</ref>, size in bytes >= 100<ref>A valid transaction requires at least 100 bytes. If it's any less, the transaction is not valid</ref>, and sig opcount <= 2<ref>The number of signature operands in the signature (no, that is not redundant) for standard transactions will never exceed two</ref>
# Reject "nonstandard" transactions: scriptSig doing anything other than pushing numbers on the stack, or scriptPubkey not matching the two usual forms<ref>Note that this is not a hard requirement on clients.</ref>
# Reject if we already have matching tx in the pool, or in a block in the main branch
# 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<ref>This is the protection against double-spending</ref>
# Using the referenced output transactions to get input values, check that each input value, as well as the sum, are in legal money range
# Reject if the sum of input values < sum of output values
# Reject if transaction fee (defined as sum of input values minus sum of output values) would be too low to get into an empty block
# Add to transaction pool<ref>Note that when the transaction is accepted into the memory pool, an additional check is made to ensure that the coinbase value does not exceed the transaction fees plus the expected BTC value (50BTC as of this writing).</ref>
# "Add to wallet if mine"
# Relay transaction to peers
# For each orphan transaction that uses this one as one of its inputs, run all these steps (including this one) recursively on that orphan

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

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

These messages hold a single block.

# Check syntactic correctness
# Reject if duplicate of block we have in any of the three categories
# Transaction list must be non-empty
# Block hash must satisfy claimed ''nBits'' proof of work
# Block timestamp must not be more than two hours in the future
# First transaction must be coinbase (i.e. only 1 input, with hash=0, n=-1), the rest must not be
# For each transaction, apply "tx" checks 2-4
# For the coinbase (first) transaction, scriptSig length must be 2-100
# Reject if sum of transaction sig opcounts > MAX_BLOCK_SIGOPS
# Verify Merkle hash
# Check if prev block (matching ''prev'' hash) is in main branch or side branches. If not, add this to orphan blocks, then query peer we got this from for 1st missing orphan block in ''prev'' chain; done with block
# Check that ''nBits'' value matches the difficulty rules
# Reject if timestamp is before the median time of the last 11 blocks
# 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]]

PHP developer intro

2011-03-29T18:23:24Z

X6763: Added to Developer category

'''L'''inux '''A'''pache '''M'''ySQL '''P'''HP + Bitcoin tutorial.

For the sake of this tutorial we assume an Ubuntu server running with PHP. The use case here is integrating a shopping system to accept Bitcoins. We assume some knowledge of Bitcoin and experience in PHP.

You can substitute any other language here for PHP. See the associated [[API reference (JSON-RPC)|API reference]] pages for info on other languages.

You will run Bitcoin in daemon mode. The way PHP communicates is through localhost HTTP requests. You use a library called [http://jsonrpcphp.org/ JSON-RPC] to call the various functions. It will respond back with a [http://en.wikipedia.org/wiki/Json JSON object].

== Setting up Bitcoin ==

Bitcoins are stored internally as 64 bit integers. Because PHP's JSON implementation does not provide a way to use custom types for decimal numbers, we must use an alternative branch of Bitcoin which returns all decimal amounts as strings.

<source lang="bash">
# install needed packages
$ sudo apt-get install build-essential libboost-all-dev libdb4.7++-dev libssl-dev libglib2.0-dev
$ git clone git://github.com/genjix/bitcoin.git
$ cd bitcoin/
$ make -f makefile.unix bitcoind
</source>

Before running bitcoind you will need to create a file in ~/.bitcoin/bitcoin.conf
<source lang="bash">
rpcuser=user
rpcpassword=password
</source>

Now run bitcoind:
<source lang="bash">
$ ./bitcoind
# wait a few seconds for it to start up
$ ./bitcoind getinfo
# various info shown
$ ./bitcoind help
# help on commands
</source>

Bitcoin is now initialising and you must wait until "blocks" is at the [http://bitcoinwatch.com/ current count].

== First steps ==

Assuming Bitcoin has finished the initialisation process; download the file jsonRPCClient.php from [http://jsonrpcphp.org/ JSON-RPC PHP]. The other files can be safely discarded.

<source lang="php">
require_once 'jsonRPCClient.php';

$bitcoin = new jsonRPCClient('http://user:password@127.0.0.1:8332/');

echo "<pre>\n";
print_r($bitcoin->getinfo());
echo "</pre>";
</source>

== Precision ==

Because PHP has no option to JSON decode to accurate decimal class, you should internally use GMP. Treat each number like a large int with 8 decimal places (this can be trimmed for display).

Our version of Bitcoin treats every monetary value as int64 8 decimal strings. So 1 BTC will be "100000000". Use PHP's GMP functions to manipulate these values accurately.

For converting between internal GMP numbers and display/user input, you can use these functions:
<source lang="php">
# converts a user supplied number to our internal representation
# 3.14 => "314000000"
# accepts strings, floats and ints as input
function numstr_to_internal($numstr)
{
return bcmul($numstr, pow(10, 8), 0);
}
# converts an internal number to an end user number for display as defined by precision
# 314100000 => "3.14"
# accepts GMP numbers, ints and strings as input
function internal_to_numstr($num, $precision=2)
{
$repr = gmp_strval($num);
$repr = bcdiv($repr, pow(10, 8), $precision);
# now tidy output...
# trim trailing 0s
$repr = rtrim($repr, '0');
# and a trailing . if it exists
$repr = rtrim($repr, '.');
return $repr;
}

$num_internal = numstr_to_internal("3.141");
echo "<p>".$num_internal."</p>";
$num_display = internal_to_numstr($num_internal);
echo "<p>".$num_display."</p>";
</source>

If you need to do a decimal division in GMP, then GMP only supports integer division + a remainder ([http://php.net/manual/en/function.gmp-div-qr.php gmp_div_qr]). The work-around for this, is to use the bcmath module:
<source lang="php">
$a = gmp_init("100");
$b = gmp_init("3");
echo "<p>".bcdiv(gmp_strval($a), gmp_strval($b), 3)."</p>";
</source>

Note that bcdiv uses strings.

See also: [http://php.net/manual/en/ref.gmp.php GMP] and [http://php.net/manual/en/ref.bc.php BC Math] manuals.

== Accounts ==

In Bitcoin, money is sent to addresses. Your balance is the total of all the money in all the address in your wallet.

Bitcoin goes another step. You can have accounts. Each account holds multiple addresses and adds like a mini-Bitcoin.

<source lang="bash">
$ ./bitcoind listaccounts
# show list of accounts and various info for each one
$ ./bitcoind getaccountaddress user889
# get an address to receive money to that is unique for the account user889
$ ./bitcoind getbalance user889
# get the sum of all the money in the addresses owned by the account user889
</source>

In your shopping system, each user should have a unique username. You then query bitcoin for a unique address using $bitcoin->getaccountaddress("user889"); [gets the first address for user889] or $bitcoin->getnewaddress("user889"); [creates a new address for user889].

The customer then deposits to this address.

You can check the funds for that customer by doing $bitcoin->getbalance("user889", 4);. The 4 indicates the minimum number of confirmations we will accept before assuming this payment is valid.

=== getnewaddress vs getaccountaddress ===

Using getnewaddress helps increase the anonymity of your customers by making it hard to track their payments from the POV of a malicious agent. However running it too often will cause your wallet to become filled with many empty addresses.

I recommend that you run do something like:
<source lang="php">
<?php
require_once('jsonRPCClient.php');
$bitcoin = new jsonRPCClient('http://root:root@127.0.0.1:8332/');
# now check for appropriate funds in user account
try {
$username = ...
if(isset($_SESSION['sendaddress']))
$sendaddress = $_SESSION['sendaddress'];
else {
$sendaddress = $bitcoin->getnewaddress($username);
$_SESSION['sendaddress'] = $sendaddress;
}
$balance = $bitcoin->getbalance($username);
}
catch (Exception $e) {
die("<p>Server error! Please contact the admin.</p>");
}
?>
</source>

This creates a new address at the beginning of every new session, and stores it in the session variable.

[[Category:Developer]]

Original Bitcoin client/API calls list

2011-03-01T17:41:09Z

X6763: /* Full list */

Bitcoin API call list (as of version 0.3.19)

== Common operations ==

=== Listing my bitcoin addresses ===

Listing the bitcoin addresses in your wallet is easily done via ''listreceivedbyaddress''. It normally lists only addresses which already have received transactions, however you can list all the addresses by setting the first argument to 0, and the second one to true

== Full list ==

Required arguments are denoted inside < and > Optional arguments are inside [ and ].

{|class="wikitable"
! Command !! Parameters !! Description
|-
| backupwallet || <destination> || Safely copies wallet.dat to destination, which can be a directory or a path with filename.
|-
| getaccount || <bitcoinaddress> || Returns the account associated with the given address.
|-
| getaccountaddress || <account> || Returns the current bitcoin address for receiving payments to this account.
|-
| getaddressesbyaccount || <account> || Returns the list of addresses for the given account.
|-
| getbalance || [account] [minconf=1] || If [account] is not specified, returns the server's total available balance.<br/>If [account] is specified, returns the balance in the account.
|-
| getblockbycount || height || Dumps the block existing at specified height. '''Note: this is not available in the official release'''
|-
| getblockcount || || Returns the number of blocks in the longest block chain.
|-
| getblocknumber || || Returns the block number of the latest block in the longest block chain.
|-
| getconnectioncount || || Returns the number of connections to other nodes.
|-
| getdifficulty || || Returns the proof-of-work difficulty as a multiple of the minimum difficulty.
|-
| getgenerate || || Returns true or false whether bitcoind is currently generating hashes
|-
| gethashespersec || || Returns a recent hashes per second performance measurement while generating.
|-
| getinfo || || Returns an object containing various state info.
|-
| getnewaddress || [account] || Returns a new bitcoin address for receiving payments. If [account] is specified (recommended), it is added to the address book so payments received with the address will be credited to [account].
|-
| getreceivedbyaccount || <account> [minconf=1] [includeempty=false] || Returns the total amount received by addresses with <account> in transactions with at least [minconf] confirmations.
|-
| getreceivedbyaddress || <bitcoinaddress> [minconf=1] [includeempty=false] || Returns the total amount received by <bitcoinaddress> in transactions with at least [minconf] confirmations.
|-
| gettransaction || <txid> || Get detailed information about <txid>
|-
| [[getwork]] || [data] || If [data] is not specified, returns formatted hash data to work on:
* "midstate" : precomputed hash state after hashing the first half of the data
* "data" : block data
* "hash1" : formatted hash buffer for second hash
* "target" : little endian hash target
If [data] is specified, tries to solve the block and returns true if it was successful.
|-
| help || [command] || List commands, or get help for a command.
|-
| listreceivedbyaccount || [minconf=1] [includeempty=false] || Returns an array of objects containing:
* "account" : the account of the receiving addresses
* "amount" : total amount received by addresses with this account
* "confirmations" : number of confirmations of the most recent transaction included
|-
| listreceivedbyaddress || [minconf=1] [includeempty=false] || Returns an array of objects containing:
* "address" : receiving address
* "account" : the account of the receiving address
* "amount" : total amount received by the address
* "confirmations" : number of confirmations of the most recent transaction included
|-
| listtransactions || <account> [count=10] || Returns up to [count] most recent transactions for account <account>.
|-
| move || <fromaccount> <toaccount> <amount> [minconf=1] [comment] || Move from one account in your wallet to another.
|-
| sendfrom || <fromaccount> <tobitcoinaddress> <amount> [minconf=1] [comment] [comment-to] || <amount> is a real and is rounded to the nearest 0.01
|-
| sendtoaddress || <bitcoinaddress> <amount> [comment] [comment-to] || <amount> is a real and is rounded to the nearest 0.01
|-
| setaccount || <bitcoinaddress> <account> || Sets the account associated with the given address.
|-
| setgenerate || <generate> [genproclimit] || <generate> is true or false to turn generation on or off.<br/>Generation is limited to [genproclimit] processors, -1 is unlimited.
|-
| stop || || Stop bitcoin server.
|-
| validateaddress || <bitcoinaddress> || Return information about <bitcoinaddress>.
|}

==See Also==

* [[Original Bitcoin client]]

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

User:X6763

2011-02-28T14:42:56Z

X6763:

==Freelance==
I'm avaialble for software development work. I accept both Bitcoins and USD as payment.
* Languages - Clojure, Java, Python, JavaScript
* Web development frameworks - Ring/Compojure, Django, Drupal

==Interests==
* Bitcoin
* Decentralized DNS
* Software development
* Information security
* Android

==Products==
===BitcoinCrypto library===
* Forum post - http://www.bitcoin.org/smf/index.php?topic=3875.0
* Repository (docs) - https://github.com/x6763/BitcoinCrypto

==Contact==
* email: 0x6763@gmail.com

Contributors Award participant: 12FVT5Kduf6KSXFmGEAetsqxhMk22ngWpu

[[Category:Freelancers]]
[[Category:Freelancers-Software Development]]

User:X6763

2011-02-28T14:34:41Z

X6763: /* Freelance */

==Freelance==
* Programmer (Clojure, Java, Python, JavaScript)
* Web development (Django, Drupal)
* Accepting Bitcoins for freelance coding work

==Interests==
* Bitcoin
* Decentralized DNS

==Contact==
* email: 0x6763@gmail.com

Contributors Award participant: 12FVT5Kduf6KSXFmGEAetsqxhMk22ngWpu

[[Category:Freelancers]]
[[Category:Freelancers-Software Development]]

User:X6763

2011-01-29T04:53:04Z

X6763:

==Freelance==
* Programmer/web development (Clojure, Python/Django, PHP/Drupal, JavaScript)
* Accepting Bitcoins for freelance coding work

==Interests==
* Bitcoin
* Decentralized DNS

==Contact==
* email: 0x6763@gmail.com

Contributors Award participant: 12FVT5Kduf6KSXFmGEAetsqxhMk22ngWpu

[[Category:Freelancers]]
[[Category:Freelancers-Software Development]]

User:X6763

2011-01-29T04:42:08Z

X6763:

* Programmer/web development (Clojure, Python/Django, PHP/Drupal, JavaScript)
* Accepting Bitcoins for freelance coding work

==Contact==
* email: 0x6763@gmail.com

Contributors Award participant: 12FVT5Kduf6KSXFmGEAetsqxhMk22ngWpu

[[Category:Freelancers]]
[[Category:Freelancers-Software Development]]

User:X6763

2011-01-29T04:33:21Z

X6763:

OP CHECKSIG

2011-01-25T03:54:38Z

X6763: /* How it works */ Added table of Hashtype values

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 Values (from script.h):'''
{|class="wikitable"
! Name !! Value
|-
| SIGHASH_ALL || 0x01
|-
| SIGHASH_NONE || 0x02
|-
| SIGHASH_SINGLE || 0x03
|-
| SIGHASH_ANYONECANPAY || 0x80
|}

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

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

OP CHECKSIG

2011-01-25T03:43:22Z

X6763: Added to Technical and Developer categories

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.

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

Script

2011-01-24T21:07:57Z

X6763: /* Crypto */

Bitcoin uses a scripting system for [[transactions]]. [[Wikipedia:FORTH|Forth]]-like, Script is simple, stack-based, and processed from left to right. It is purposefully not Turing-complete, with no loops or nesting ''if'' statements.

A script is essentially a list of instructions recorded with each transaction that describe how the next person wanting to spend the Bitcoins being transferred can gain access to them. The script for a typical Bitcoin transfer to destination Bitcoin address D simply encumbers future spending of the bitcoins with two things: the spender must provide
# a public key that, when hashed, yields destination address D embedded in the script, and
# a signature to show evidence of the private key corresponding to the public key just provided.

Scripting provides the flexibility to change the parameters of what's needed to spend transferred Bitcoins. For example, the scripting system could be used to require two private keys, or a combination of several, or even no keys at all.

A transaction is valid if nothing in the combined script triggers failure and the top stack item is true (1). The party who originally ''sent'' the Bitcoins now being spent, dictates the script operations that will occur ''last'' in order to release them for use in another transaction. The party wanting to spend them must provide the input(s) to the previously recorded script that results in those operations occurring last leaving behind true (1).

Scripts are big-endian. (Is all data, also?)

== Words ==
This is a list of all Script words (commands/functions). Some are currently disabled for security reasons.

True=1 and False=0.

=== Constants ===
When talking about scripts, these value-pushing words are usually omitted.

{| class="wikitable"
|-
!Word
!Opcode
!Input
!Output
!Description
|-
|OP_0, OP_FALSE
|0
|Nothing.
|0
|The number 0 is pushed onto the stack.
|-
|N/A
|1-75
|(special)
|data
|The next ''opcode'' bytes is data to be pushed onto the stack
|-
|OP_PUSHDATA1
|76
|(special)
|data
|The next byte contains the number of bytes to be pushed onto the stack.
|-
|OP_PUSHDATA2
|77
|(special)
|data
|The next two bytes contain the number of bytes to be pushed onto the stack.
|-
|OP_PUSHDATA4
|78
|(special)
|data
|The next four bytes contain the number of bytes to be pushed onto the stack.
|-
|OP_1NEGATE
|79
|Nothing.
| -1
|The number -1 is pushed onto the stack.
|-
|OP_1, OP_TRUE
|81
|Nothing.
|1
|The number 1 is pushed onto the stack.
|-
|OP_2-OP_16
|82-96
|Nothing.
|2-16
|The number in the word name (2-16) is pushed onto the stack.
|}

=== Flow control ===

{| class="wikitable"
|-
!Word
!Opcode
!Input
!Output
!Description
|-
|OP_NOP
|97
|Nothing
|Nothing
|Does nothing.
|-
|OP_IF
|99
| colspan="2"|<expression> if [statements] [else [statements]] endif
|If the top stack value is 1, the statements are executed. The top stack value is removed.
|-
|OP_NOTIF
|100
| colspan="2"|<expression> if [statements] [else [statements]] endif
|If the top stack value is 0, the statements are executed. The top stack value is removed.
|-
|OP_ELSE
|103
| colspan="2"|<expression> if [statements] [else [statements]] endif
|If the preceding OP_IF or OP_NOTIF was not executed then these statements are.
|-
|OP_ENDIF
|104
| colspan="2"|<expression> if [statements] [else [statements]] endif
|Ends an if/else block.
|-
|OP_VERIFY
|105
|True / false
|Nothing / False
|'''Marks transaction as invalid''' if top stack value is not true. True is removed, but false is not.
|-
|OP_RETURN
|106
|Nothing
|Nothing
|'''Marks transaction as invalid'''.
|}

=== Stack ===

{| class="wikitable"
|-
!Word
!Opcode
!Input
!Output
!Description
|-
|OP_TOALTSTACK
|107
|x1
|(alt)x1
|Puts the input onto the top of the alt stack. Removes it from the main stack.
|-
|OP_FROMALTSTACK
|108
|(alt)x1
|x1
|Puts the input onto the top of the main stack. Removes it from the alt stack.
|-
|OP_IFDUP
|115
|x
|x / x x
|If the input is true or false, duplicate it.
|-
|OP_DEPTH
|116
|Nothing
|<Stack size>
|Puts the number of stack items onto the stack.
|-
|OP_DROP
|117
|x
|Nothing
|Removes the top stack item.
|-
|OP_DUP
|118
|x
|x x
|Duplicates the top stack item.
|-
|OP_NIP
|119
|x1 x2
|x2
|Removes the second-to-top stack item.
|-
|OP_OVER
|120
|x1 x2
|x1 x2 x1
|Copies the second-to-top stack item to the top.
|-
|OP_PICK
|121
|xn ... x2 x1 x0 <n>
|xn ... x2 x1 x0 xn
|The item ''n'' back in the stack is copied to the top.
|-
|OP_ROLL
|122
|xn ... x2 x1 x0 <n>
|... x2 x1 x0 xn
|The item ''n'' back in the stack is moved to the top.
|-
|OP_ROT
|123
|x1 x2 x3
|x2 x3 x1
|The top three items on the stack are rotated to the left.
|-
|OP_SWAP
|124
|x1 x2
|x2 x1
|The top two items on the stack are swapped.
|-
|OP_TUCK
|125
|x1 x2
|x2 x1 x2
|The item at the top of the stack is copied and inserted before the second-to-top item.
|-
|OP_2DROP
|109
|x1 x2
|Nothing
|Removes the top two stack items.
|-
|OP_2DUP
|110
|x1 x2
|x1 x2 x1 x2
|Duplicates the top two stack items.
|-
|OP_3DUP
|111
|x1 x2 x3
|x1 x2 x3 x1 x2 x3
|Duplicates the top three stack items.
|-
|OP_2OVER
|112
|x1 x2 x3 x4
|x1 x2 x3 x4 x1 x2
|Copies the pair of items two spaces back in the stack to the front.
|-
|OP_2ROT
|113
|x1 x2 x3 x4 x5 x6
|x3 x4 x5 x6 x1 x2
|The fifth and sixth items back are moved to the top of the stack.
|-
|OP_2SWAP
|114
|x1 x2 x3 x4
|x3 x4 x1 x2
|Swaps the top two pairs of items.
|}

=== Splice ===

{| class="wikitable"
|-
!Word
!Opcode
!Input
!Output
!Description
|-
|OP_CAT
|126
|x1 x2
|out
|Concatenates two strings. ''Currently disabled.''
|-
|OP_SUBSTR
|127
|in begin size
|out
|Returns a section of a string. ''Currently disabled.''
|-
|OP_LEFT
|128
|in size
|out
|Keeps only characters left of the specified point in a string. ''Currently disabled.''
|-
|OP_RIGHT
|129
|in size
|out
|Keeps only characters right of the specified point in a string. ''Currently disabled.''
|-
|OP_SIZE
|130
|in
|in size
|Returns the length of the input string.
|}

=== Bitwise logic ===

{| class="wikitable"
|-
!Word
!Input
!Output
!Description
|-
|OP_INVERT
|131
|in
|out
|Flips all of the bits in the input. ''Currently disabled.''
|-
|OP_AND
|132
|x1 x2
|out
|Boolean ''and'' between each bit in the inputs. ''Currently disabled.''
|-
|OP_OR
|133
|x1 x2
|out
|Boolean ''or'' between each bit in the inputs. ''Currently disabled.''
|-
|OP_XOR
|134
|x1 x2
|out
|Boolean ''exclusive or'' between each bit in the inputs. ''Currently disabled.''
|-
|OP_EQUAL
|135
|x1 x2
|True / false
|Returns 1 if the inputs are exactly equal, 0 otherwise.
|-
|OP_EQUALVERIFY
|136
|x1 x2
|True / false
|Same as OP_EQUAL, but runs OP_VERIFY afterward.
|}

=== Arithmetic ===

{| class="wikitable"
|-
!Word
!Opcode
!Input
!Output
!Description
|-
|OP_1ADD
|139
|in
|out
|1 is added to the input.
|-
|OP_1SUB
|140
|in
|out
|1 is subtracted from the input.
|-
|OP_2MUL
|141
|in
|out
|The input is multiplied by 2. ''Currently disabled.''
|-
|OP_2DIV
|142
|in
|out
|The input is divided by 2. ''Currently disabled.''
|-
|OP_NEGATE
|143
|in
|out
|The sign of the input is flipped.
|-
|OP_ABS
|144
|in
|out
|The input is made positive.
|-
|OP_NOT
|145
|in
|out
|If the input is 0 or 1, it is flipped. Otherwise the output will be 0.
|-
|OP_0NOTEQUAL
|146
|in
|out
|Returns 1 if the input is 0. 0 otherwise.
|-
|OP_ADD
|147
|a b
|out
|a is added to b.
|-
|OP_SUB
|148
|a b
|out
|b is subtracted from a.
|-
|OP_MUL
|149
|a b
|out
|a is multiplied by b. ''Currently disabled.''
|-
|OP_DIV
|150
|a b
|out
|a is divided by b. ''Currently disabled.''
|-
|OP_MOD
|151
|a b
|out
|Returns the remainder after dividing a by b. ''Currently disabled.''
|-
|OP_LSHIFT
|152
|a b
|out
|Shifts a left b bits, preserving sign. ''Currently disabled.''
|-
|OP_RSHIFT
|153
|a b
|out
|Shifts a right b bits, preserving sign. ''Currently disabled.''
|-
|OP_BOOLAND
|154
|a b
|out
|If both a and b are not 0, the output is 1. Otherwise 0.
|-
|OP_BOOLOR
|155
|a b
|out
|If a or b is not 0, the output is 1. Otherwise 0.
|-
|OP_NUMEQUAL
|156
|a b
|out
|Returns 1 if the numbers are equal, 0 otherwise.
|-
|OP_NUMEQUALVERIFY
|157
|a b
|out
|Same as OP_NUMEQUAL, but runs OP_VERIFY afterward.
|-
|OP_NUMNOTEQUAL
|158
|a b
|out
|Returns 1 if the numbers are not equal, 0 otherwise.
|-
|OP_LESSTHAN
|159
|a b
|out
|Returns 1 if a is less than b, 0 otherwise.
|-
|OP_GREATERTHAN
|160
|a b
|out
|Returns 1 if a is greater than b, 0 otherwise.
|-
|OP_LESSTHANOREQUAL
|161
|a b
|out
|Returns 1 if a is less than or equal to b, 0 otherwise.
|-
|OP_GREATERTHANOREQUAL
|162
|a b
|out
|Returns 1 if a is greater than or equal to b, 0 otherwise.
|-
|OP_MIN
|163
|a b
|out
|Returns the smaller of a and b.
|-
|OP_MAX
|164
|a b
|out
|Returns the larger of a and b.
|-
|OP_WITHIN
|165
|x min max
|out
|Returns 1 if x is within the specified range (left-inclusive), 0 otherwise.
|}

=== Crypto ===

{| class="wikitable"
|-
!Word
!Opcode
!Input
!Output
!Description
|-
|OP_RIPEMD160
|166
|in
|hash
|The input is hashed using RIPEMD-160.
|-
|OP_SHA1
|167
|in
|hash
|The input is hashed using SHA-1.
|-
|OP_SHA256
|168
|in
|hash
|The input is hashed using SHA-256.
|-
|OP_HASH160
|169
|in
|hash
|The input is hashed twice: first with SHA-256 and then with RIPEMD-160.
|-
|OP_HASH256
|170
|in
|hash
|The input is hashed two times with SHA-256.
|-
|OP_CODESEPARATOR
|171
|Nothing
|Nothing
|All of the signature checking words will only match signatures to the data after the most recently-executed OP_CODESEPARATOR.
|-
|[[OP_CHECKSIG]]
|172
|sig pubkey
|True / false
|The entire transaction's outputs, inputs, and script (from the most recently-executed OP_CODESEPARATOR to the end) are hashed. The signature used by OP_CHECKSIG must be a valid signature for this hash and public key. If it is, 1 is returned, 0 otherwise.
|-
|OP_CHECKSIGVERIFY
|173
|sig pubkey
|True / false
|Same as OP_CHECKSIG, but OP_VERIFY is executed afterward.
|-
|OP_CHECKMULTISIG
|174
|sig1 sig2 ... <number of signatures> pub1 pub2 <number of public keys>
|True / False
|For each signature and public key pair, OP_CHECKSIG is executed. If more public keys than signatures are listed, some key/sig pairs can fail. All signatures need to match a public key. If all signatures are valid, 1 is returned, 0 otherwise.
|-
|OP_CHECKMULTISIGVERIFY
|175
|sig1 sig2 ... <number of signatures> pub1 pub2 ... <number of public keys>
|True / False
|Same as OP_CHECKMULTISIG, but OP_VERIFY is executed afterward.
|}

===Pseudo-words===
These words are used internally for assisting with transaction matching. They are invalid if used in actual scripts.
{| class="wikitable"
|-
!Word
!Opcode
!Description
|-
|OP_PUBKEYHASH
|253
|Represents a public key hashed with OP_HASH160.
|-
|OP_PUBKEY
|254
|Represents a public key compatible with OP_CHECKSIG.
|-
|OP_INVALIDOPCODE
|255
|Matches any opcode that is not yet assigned.
|}

=== Reserved words ===
Any opcode not assigned is also reserved. Using an unassigned opcode makes the transaction invalid.

{| class="wikitable"
|-
!Word
!Opcode
!When used...
|-
|OP_RESERVED
|80
|Transaction is invalid
|-
|OP_VER
|98
|Transaction is invalid
|-
|OP_VERIF
|101
|Transaction is invalid
|-
|OP_VERNOTIF
|102
|Transaction is invalid
|-
|OP_RESERVED1
|137
|Transaction is invalid
|-
|OP_RESERVED2
|138
|Transaction is invalid
|-
|OP_NOP1-OP_NOP10
|176-185
|The word is ignored.
|}

== Scripts ==
Keep in mind that all constants actually use the data-pushing commands above.

=== Standard Transaction to Bitcoin address ===

scriptPubKey: OP_DUP OP_HASH160 <pubKeyHash> OP_EQUALVERIFY OP_CHECKSIG
scriptSig: <sig> <pubKey>

To demonstrate how scripts look on the wire, here is a raw scriptPubKey:
<pre> 76 A9 14
OP_DUP OP_HASH160 Bytes to push

89 AB CD EF AB BA AB BA AB BA AB BA AB BA AB BA AB BA AB BA 88 AC
Data to push OP_EQUALVERIFY OP_CHECKSIG</pre>

Here is how each word is processed:
{| 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.
|}

=== Standard Generation / transaction to IP address ===

scriptPubKey: <pubKey> OP_CHECKSIG
scriptSig: <sig>

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

=== Transaction with a message ===

It's possible to add arbitrary data to any transaction by just adding some data along with OP_DROP (or omitting OP_DROP and allowing the value to sit on the stack unused). Scripts are limited to 10,000 bytes and 201 instructions/values, and each individual instruction/value is limited to 520 bytes.

scriptPubKey: <message> OP_DROP <pubKey> OP_CHECKSIG
scriptSig: <sig>

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

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

Protocol documentation

2011-01-21T05:23:07Z

X6763: /* addr */

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)) (not included in version or verack)
|-
| ? || payload || char[] || The actual data
|}

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. Variable length integers always precede an array/vector of a type of data that may vary in length.

{|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. This protocol and structure supports IPv6, '''but note that the official client currently only supports IPv4 networking'''.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]?
|-
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The official client only supports IPv4 and only reads the last 4 bytes to get the IPv4 address. However, the official client writes the IPv4 address into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).
|-
| 2 || port || uint16_t || port number, network byte order
|}

Hexdump example of Network address structure

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

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

=== Inventory Vectors ===

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

Inventory vectors consist of the following data format:

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

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

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

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

Hexdump example of version message (note the message header for this version message does not have a checksum):
<pre>
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................
0040 DA F6 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,
0060 3A B4 57 13 00 55 81 01 00 :.W..U...

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

=== verack ===

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

Hexdump of the verack message:

<pre>
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......
0010 00 00 00 00 ....

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

=== addr ===

Provide information 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
|-
| 1+ || count || var_int || Number of address entries
|-
| 30x? || addr_list || (uint32_t + 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.

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

Message Header:
F9 BE B4 D9 - Main network magic bytes
61 64 64 72 00 00 00 00 00 00 00 00 - "addr"
1F 00 00 00 - payload is 31 bytes long
7F 85 39 C2 - checksum of payload

Payload:
01 - 1 address in this message

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

=== inv ===

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

Payload (maximum 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 || var_int || 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
|-
| 1+ || tx_in count || var_int || Number of Transaction inputs
|-
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins
|-
| 1+ || tx_out count || var_int || Number of Transaction outputs
|-
| 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
|-
| 1+ || script length || var_int || The length of the signature script
|-
| ? || signature script || char[] || 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
|-
| 1+ || pk_script length || var_int || Length of the pk_script
|-
| ? || pk_script || char[] || Usually contains the public key as a Bitcoin script setting up conditions to claim this output.
|}

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

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

Transaction:
01 00 00 00 - version

Inputs:
01 - number of transaction inputs

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

8B - script is 139 bytes long

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

FF FF FF FF - sequence

Outputs:
02 - 2 Output Transactions

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

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

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

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

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

=== block ===

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

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || 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 [[script]].

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

Protocol documentation

2011-01-21T05:22:37Z

X6763: /* verack */

Protocol documentation

2011-01-21T05:22:18Z

X6763: /* version */

Protocol documentation

2011-01-21T05:21:46Z

X6763: /* Network address */

Protocol documentation

2011-01-21T05:13:32Z

X6763: /* tx */

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)) (not included in version or verack)
|-
| ? || payload || char[] || The actual data
|}

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. Variable length integers always precede an array/vector of a type of data that may vary in length.

{|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. This protocol and structure supports IPv6, '''but note that the official client currently only supports IPv4 networking'''.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]?
|-
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The official client only supports IPv4 and only reads the last 4 bytes to get the IPv4 address. However, the official client writes the IPv4 address into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).
|-
| 2 || port || uint16_t || port number, network byte order
|}

Hexdump example of Network address structure

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

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

=== Inventory Vectors ===

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

Inventory vectors consist of the following data format:

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

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

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

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

Hexdump example of version message (note the message header for this version message does not have a checksum):
<pre>
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................
0040 DA F6 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,
0060 3A B4 57 13 00 55 81 01 00 :.W..U...

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

=== verack ===

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

Hexdump of the verack message:

<pre>
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......
0010 00 00 00 00 ....

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

=== addr ===

Provide information 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
|-
| 1+ || count || var_int || Number of address entries
|-
| 30x? || addr_list || (uint32_t + 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.

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

Message Header:
F9 BE B4 D9 - Main network magic bytes
61 64 64 72 00 00 00 00 00 00 00 00 - "addr"
1F 00 00 00 - payload is 31 bytes long
7F 85 39 C2 - checksum of payload

Payload:
01 - 1 address in this message

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

=== inv ===

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

Payload (maximum 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 || var_int || 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
|-
| 1+ || tx_in count || var_int || Number of Transaction inputs
|-
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins
|-
| 1+ || tx_out count || var_int || Number of Transaction outputs
|-
| 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
|-
| 1+ || script length || var_int || The length of the signature script
|-
| ? || signature script || char[] || 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
|-
| 1+ || pk_script length || var_int || Length of the pk_script
|-
| ? || pk_script || char[] || Usually contains the public key as a Bitcoin script setting up conditions to claim this output.
|}

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

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

Transaction:
01 00 00 00 - version

Inputs:
01 - number of transaction inputs

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

8B - script is 139 bytes long

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

FF FF FF FF - sequence

Outputs:
02 - 2 Output Transactions

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

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

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

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

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

=== block ===

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

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || 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 [[script]].

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

Protocol documentation

2011-01-13T23:08:44Z

X6763: /* Network address */

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. Variable length integers always precede an array/vector of a type of data that may vary in length.

{|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. This protocol and structure supports IPv6, '''but note that the official client currently only supports IPv4 networking'''.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]?
|-
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The official client only supports IPv4 and only reads the last 4 bytes to get the IPv4 address. However, the official client writes the IPv4 address into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).
|-
| 2 || port || uint16_t || port number, network byte order
|}

Hexdump example of Network address structure

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

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

=== Inventory Vectors ===

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

Inventory vectors consist of the following data format:

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

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

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

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

Hexdump example of version message (note the message header for this version message does not have a checksum):
<pre>
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................
0040 DA F6 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,
0060 3A B4 57 13 00 55 81 01 00 :.W..U...

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

=== verack ===

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

Hexdump of the verack message:

<pre>
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......
0010 00 00 00 00 ....

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

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

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

Message Header:
F9 BE B4 D9 - Main network magic bytes
61 64 64 72 00 00 00 00 00 00 00 00 - "addr"
1F 00 00 00 - payload is 31 bytes long
7F 85 39 C2 - checksum of payload

Payload:
01 - 1 address in this message

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

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

Payload (maximum 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 || var_int || 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
|-
| 1+ || tx_in count || var_int || Number of Transaction inputs
|-
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins
|-
| 1+ || tx_out count || var_int || Number of Transaction outputs
|-
| 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
|-
| 1+ || script length || var_int || The length of the signature script
|-
| ? || signature script || char[] || 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
|-
| 1+ || pk_script length || var_int || Length of the pk_script
|-
| ? || pk_script || char[] || 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.

'''Note: Even though this message does not contain a payload, the official client includes a checksum in the header anyway. Possibly a minor bug?'''

=== 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 [[script]].

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

Protocol documentation

2011-01-13T23:05:41Z

X6763: /* version */

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. Variable length integers always precede an array/vector of a type of data that may vary in length.

{|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. This protocol and structure supports IPv6, '''but note that the official client currently only supports IPv4 networking'''.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]?
|-
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The official client only supports IPv4 and only reads the last 4 bytes to get the IPv4 address. However, the official client writes the IPv4 address into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).
|-
| 2 || port || uint16_t || port number, network byte order
|}

Hexdump example of Network address structure

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

{|class="wikitable"
! Name !! Bytes !! Value || Description/Notes
|-
| Services || 01 00 00 00 00 00 00 00 || 1 || NODE_NETWORK? (see services listed in the [[#version|version]] command)
|-
| IP Address || 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 || IPv6: ::ffff:10.0.0.1 ([http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address])
IPv4: 10.0.0.1
||
Network byte order. The official client only uses the last 4 bytes as an IPv4 address.
|-
| Port || 20 8D || 8333 || 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.
|}

Hexdump example of version message (note the message header for this version message does not have a checksum):
<pre>
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................
0040 DA F6 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,
0060 3A B4 57 13 00 55 81 01 00 :.W..U...

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

=== verack ===

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

Hexdump of the verack message:

<pre>
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......
0010 00 00 00 00 ....

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

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

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

Message Header:
F9 BE B4 D9 - Main network magic bytes
61 64 64 72 00 00 00 00 00 00 00 00 - "addr"
1F 00 00 00 - payload is 31 bytes long
7F 85 39 C2 - checksum of payload

Payload:
01 - 1 address in this message

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

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

Payload (maximum 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 || var_int || 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
|-
| 1+ || tx_in count || var_int || Number of Transaction inputs
|-
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins
|-
| 1+ || tx_out count || var_int || Number of Transaction outputs
|-
| 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
|-
| 1+ || script length || var_int || The length of the signature script
|-
| ? || signature script || char[] || 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
|-
| 1+ || pk_script length || var_int || Length of the pk_script
|-
| ? || pk_script || char[] || 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.

'''Note: Even though this message does not contain a payload, the official client includes a checksum in the header anyway. Possibly a minor bug?'''

=== 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 [[script]].

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

Protocol documentation

2011-01-13T22:49:11Z

X6763: /* verack */

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. Variable length integers always precede an array/vector of a type of data that may vary in length.

{|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. This protocol and structure supports IPv6, '''but note that the official client currently only supports IPv4 networking'''.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]?
|-
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The official client only supports IPv4 and only reads the last 4 bytes to get the IPv4 address. However, the official client writes the IPv4 address into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).
|-
| 2 || port || uint16_t || port number, network byte order
|}

Hexdump example of Network address structure

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

{|class="wikitable"
! Name !! Bytes !! Value || Description/Notes
|-
| Services || 01 00 00 00 00 00 00 00 || 1 || NODE_NETWORK? (see services listed in the [[#version|version]] command)
|-
| IP Address || 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 || IPv6: ::ffff:10.0.0.1 ([http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address])
IPv4: 10.0.0.1
||
Network byte order. The official client only uses the last 4 bytes as an IPv4 address.
|-
| Port || 20 8D || 8333 || 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.
|}

Hexdump example of version message (note the message header for this version message does not have a checksum):
<pre>
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................
0040 DA F6 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,
0060 3A B4 57 13 00 55 81 01 00 :.W..U...
</pre>
{|class="wikitable"
! Name !! Bytes !! Value !! Description
|-
|colspan="4"| '''Message Header'''
|-
| Network || F9 BE B4 D9 || n/a || Main network magic bytes
|-
| Command || 76 65 72 73 69 6F 6E 00 00 00 00 00 || "version" || This is a version message
|-
| Length || 55 00 00 00 || 85 || Payload is 85 bytes long
|-
| Checksum || n/a || n/a || No checksum in version message
|-
|colspan="4"| '''Version payload'''
|-
| Version || 9C 7C 00 00 || 31900 || version 0.3.19 (client version? protocol version?)
|-
| Services || 01 00 00 00 00 00 00 00 || 1 || NODE_NETWORK
|-
| Timestamp || E6 15 10 4D 00 00 00 00 || 1292899814 || 1292899814 seconds since 1970 (Dec 20 21:50:14 EST 2010)
|-
| Sender Address || 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 DA F6 || Services: 1
IP/port: 10.0.0.1:8333
|| Address information of node that sent this message (see [[#Network address|Network address]])
|-
| Recipient Address || 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D || Services: 1
IP/port: 10.0.0.2:8333
|| Address information of node receiving this message (see [[#Network address|Network address]])
|-
| Nonce || DD 9D 20 2C 3A B4 57 13 || n/a || Node random unique id. This id is used to detect connections to self
|-
| Sub-version number || 00 || n/a || Empty sub-version string (sub-version info is 0 bytes long)
|-
| Start height || 55 81 01 00 || 98645 || The number of the last block received by the sending node
|}

=== verack ===

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

Hexdump of the verack message:

<pre>
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......
0010 00 00 00 00 ....

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

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

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

Message Header:
F9 BE B4 D9 - Main network magic bytes
61 64 64 72 00 00 00 00 00 00 00 00 - "addr"
1F 00 00 00 - payload is 31 bytes long
7F 85 39 C2 - checksum of payload

Payload:
01 - 1 address in this message

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

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

Payload (maximum 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 || var_int || 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
|-
| 1+ || tx_in count || var_int || Number of Transaction inputs
|-
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins
|-
| 1+ || tx_out count || var_int || Number of Transaction outputs
|-
| 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
|-
| 1+ || script length || var_int || The length of the signature script
|-
| ? || signature script || char[] || 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
|-
| 1+ || pk_script length || var_int || Length of the pk_script
|-
| ? || pk_script || char[] || 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.

'''Note: Even though this message does not contain a payload, the official client includes a checksum in the header anyway. Possibly a minor bug?'''

=== 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 [[script]].

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

Protocol documentation

2011-01-13T22:46:45Z

X6763: /* addr */

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. Variable length integers always precede an array/vector of a type of data that may vary in length.

{|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. This protocol and structure supports IPv6, '''but note that the official client currently only supports IPv4 networking'''.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]?
|-
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The official client only supports IPv4 and only reads the last 4 bytes to get the IPv4 address. However, the official client writes the IPv4 address into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).
|-
| 2 || port || uint16_t || port number, network byte order
|}

Hexdump example of Network address structure

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

{|class="wikitable"
! Name !! Bytes !! Value || Description/Notes
|-
| Services || 01 00 00 00 00 00 00 00 || 1 || NODE_NETWORK? (see services listed in the [[#version|version]] command)
|-
| IP Address || 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 || IPv6: ::ffff:10.0.0.1 ([http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address])
IPv4: 10.0.0.1
||
Network byte order. The official client only uses the last 4 bytes as an IPv4 address.
|-
| Port || 20 8D || 8333 || 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.
|}

Hexdump example of version message (note the message header for this version message does not have a checksum):
<pre>
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................
0040 DA F6 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,
0060 3A B4 57 13 00 55 81 01 00 :.W..U...
</pre>
{|class="wikitable"
! Name !! Bytes !! Value !! Description
|-
|colspan="4"| '''Message Header'''
|-
| Network || F9 BE B4 D9 || n/a || Main network magic bytes
|-
| Command || 76 65 72 73 69 6F 6E 00 00 00 00 00 || "version" || This is a version message
|-
| Length || 55 00 00 00 || 85 || Payload is 85 bytes long
|-
| Checksum || n/a || n/a || No checksum in version message
|-
|colspan="4"| '''Version payload'''
|-
| Version || 9C 7C 00 00 || 31900 || version 0.3.19 (client version? protocol version?)
|-
| Services || 01 00 00 00 00 00 00 00 || 1 || NODE_NETWORK
|-
| Timestamp || E6 15 10 4D 00 00 00 00 || 1292899814 || 1292899814 seconds since 1970 (Dec 20 21:50:14 EST 2010)
|-
| Sender Address || 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 DA F6 || Services: 1
IP/port: 10.0.0.1:8333
|| Address information of node that sent this message (see [[#Network address|Network address]])
|-
| Recipient Address || 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D || Services: 1
IP/port: 10.0.0.2:8333
|| Address information of node receiving this message (see [[#Network address|Network address]])
|-
| Nonce || DD 9D 20 2C 3A B4 57 13 || n/a || Node random unique id. This id is used to detect connections to self
|-
| Sub-version number || 00 || n/a || Empty sub-version string (sub-version info is 0 bytes long)
|-
| Start height || 55 81 01 00 || 98645 || The number of the last block received by the sending node
|}

=== verack ===

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

Hexdump of the verack message:

<pre>
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......
0010 00 00 00 00
</pre>

{|class="wikitable"
! Name !! Bytes !! Value !! Description
|-
|colspan="4"| '''Message Header'''
|-
| Network || F9 BE B4 D9 || n/a || Main network magic bytes
|-
| Command || 76 65 72 61 63 6B 00 00 00 00 00 00 || "verack" || This is a verack message
|-
| Length || 00 00 00 00 || 0 || Payload is 0 bytes long
|}

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

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

Message Header:
F9 BE B4 D9 - Main network magic bytes
61 64 64 72 00 00 00 00 00 00 00 00 - "addr"
1F 00 00 00 - payload is 31 bytes long
7F 85 39 C2 - checksum of payload

Payload:
01 - 1 address in this message

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

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

Payload (maximum 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 || var_int || 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
|-
| 1+ || tx_in count || var_int || Number of Transaction inputs
|-
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins
|-
| 1+ || tx_out count || var_int || Number of Transaction outputs
|-
| 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
|-
| 1+ || script length || var_int || The length of the signature script
|-
| ? || signature script || char[] || 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
|-
| 1+ || pk_script length || var_int || Length of the pk_script
|-
| ? || pk_script || char[] || 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.

'''Note: Even though this message does not contain a payload, the official client includes a checksum in the header anyway. Possibly a minor bug?'''

=== 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 [[script]].

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

Protocol documentation

2011-01-13T19:01:56Z

X6763: /* getaddr */

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. Variable length integers always precede an array/vector of a type of data that may vary in length.

{|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. This protocol and structure supports IPv6, '''but note that the official client currently only supports IPv4 networking'''.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]?
|-
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The official client only supports IPv4 and only reads the last 4 bytes to get the IPv4 address. However, the official client writes the IPv4 address into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).
|-
| 2 || port || uint16_t || port number, network byte order
|}

Hexdump example of Network address structure

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

{|class="wikitable"
! Name !! Bytes !! Value || Description/Notes
|-
| Services || 01 00 00 00 00 00 00 00 || 1 || NODE_NETWORK? (see services listed in the [[#version|version]] command)
|-
| IP Address || 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 || IPv6: ::ffff:10.0.0.1 ([http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address])
IPv4: 10.0.0.1
||
Network byte order. The official client only uses the last 4 bytes as an IPv4 address.
|-
| Port || 20 8D || 8333 || 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.
|}

Hexdump example of version message (note the message header for this version message does not have a checksum):
<pre>
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................
0040 DA F6 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,
0060 3A B4 57 13 00 55 81 01 00 :.W..U...
</pre>
{|class="wikitable"
! Name !! Bytes !! Value !! Description
|-
|colspan="4"| '''Message Header'''
|-
| Network || F9 BE B4 D9 || n/a || Main network magic bytes
|-
| Command || 76 65 72 73 69 6F 6E 00 00 00 00 00 || "version" || This is a version message
|-
| Length || 55 00 00 00 || 85 || Payload is 85 bytes long
|-
| Checksum || n/a || n/a || No checksum in version message
|-
|colspan="4"| '''Version payload'''
|-
| Version || 9C 7C 00 00 || 31900 || version 0.3.19 (client version? protocol version?)
|-
| Services || 01 00 00 00 00 00 00 00 || 1 || NODE_NETWORK
|-
| Timestamp || E6 15 10 4D 00 00 00 00 || 1292899814 || 1292899814 seconds since 1970 (Dec 20 21:50:14 EST 2010)
|-
| Sender Address || 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 DA F6 || Services: 1
IP/port: 10.0.0.1:8333
|| Address information of node that sent this message (see [[#Network address|Network address]])
|-
| Recipient Address || 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D || Services: 1
IP/port: 10.0.0.2:8333
|| Address information of node receiving this message (see [[#Network address|Network address]])
|-
| Nonce || DD 9D 20 2C 3A B4 57 13 || n/a || Node random unique id. This id is used to detect connections to self
|-
| Sub-version number || 00 || n/a || Empty sub-version string (sub-version info is 0 bytes long)
|-
| Start height || 55 81 01 00 || 98645 || The number of the last block received by the sending node
|}

=== verack ===

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

Hexdump of the verack message:

<pre>
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......
0010 00 00 00 00
</pre>

{|class="wikitable"
! Name !! Bytes !! Value !! Description
|-
|colspan="4"| '''Message Header'''
|-
| Network || F9 BE B4 D9 || n/a || Main network magic bytes
|-
| Command || 76 65 72 61 63 6B 00 00 00 00 00 00 || "verack" || This is a verack message
|-
| Length || 00 00 00 00 || 0 || Payload is 0 bytes long
|}

=== 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 || var_int || 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
|-
| 1+ || tx_in count || var_int || Number of Transaction inputs
|-
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins
|-
| 1+ || tx_out count || var_int || Number of Transaction outputs
|-
| 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
|-
| 1+ || script length || var_int || The length of the signature script
|-
| ? || signature script || char[] || 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
|-
| 1+ || pk_script length || var_int || Length of the pk_script
|-
| ? || pk_script || char[] || 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.

'''Note: Even though this message does not contain a payload, the official client includes a checksum in the header anyway. Possibly a minor bug?'''

=== 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 [[script]].

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

Protocol documentation

2011-01-13T18:27:43Z

X6763: /* version */

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. Variable length integers always precede an array/vector of a type of data that may vary in length.

{|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. This protocol and structure supports IPv6, '''but note that the official client currently only supports IPv4 networking'''.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]?
|-
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The official client only supports IPv4 and only reads the last 4 bytes to get the IPv4 address. However, the official client writes the IPv4 address into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).
|-
| 2 || port || uint16_t || port number, network byte order
|}

Hexdump example of Network address structure

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

{|class="wikitable"
! Name !! Bytes !! Value || Description/Notes
|-
| Services || 01 00 00 00 00 00 00 00 || 1 || NODE_NETWORK? (see services listed in the [[#version|version]] command)
|-
| IP Address || 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 || IPv6: ::ffff:10.0.0.1 ([http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address])
IPv4: 10.0.0.1
||
Network byte order. The official client only uses the last 4 bytes as an IPv4 address.
|-
| Port || 20 8D || 8333 || 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.
|}

Hexdump example of version message (note the message header for this version message does not have a checksum):
<pre>
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................
0040 DA F6 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,
0060 3A B4 57 13 00 55 81 01 00 :.W..U...
</pre>
{|class="wikitable"
! Name !! Bytes !! Value !! Description
|-
|colspan="4"| '''Message Header'''
|-
| Network || F9 BE B4 D9 || n/a || Main network magic bytes
|-
| Command || 76 65 72 73 69 6F 6E 00 00 00 00 00 || "version" || This is a version message
|-
| Length || 55 00 00 00 || 85 || Payload is 85 bytes long
|-
| Checksum || n/a || n/a || No checksum in version message
|-
|colspan="4"| '''Version payload'''
|-
| Version || 9C 7C 00 00 || 31900 || version 0.3.19 (client version? protocol version?)
|-
| Services || 01 00 00 00 00 00 00 00 || 1 || NODE_NETWORK
|-
| Timestamp || E6 15 10 4D 00 00 00 00 || 1292899814 || 1292899814 seconds since 1970 (Dec 20 21:50:14 EST 2010)
|-
| Sender Address || 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 DA F6 || Services: 1
IP/port: 10.0.0.1:8333
|| Address information of node that sent this message (see [[#Network address|Network address]])
|-
| Recipient Address || 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D || Services: 1
IP/port: 10.0.0.2:8333
|| Address information of node receiving this message (see [[#Network address|Network address]])
|-
| Nonce || DD 9D 20 2C 3A B4 57 13 || n/a || Node random unique id. This id is used to detect connections to self
|-
| Sub-version number || 00 || n/a || Empty sub-version string (sub-version info is 0 bytes long)
|-
| Start height || 55 81 01 00 || 98645 || The number of the last block received by the sending node
|}

=== verack ===

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

Hexdump of the verack message:

<pre>
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......
0010 00 00 00 00
</pre>

{|class="wikitable"
! Name !! Bytes !! Value !! Description
|-
|colspan="4"| '''Message Header'''
|-
| Network || F9 BE B4 D9 || n/a || Main network magic bytes
|-
| Command || 76 65 72 61 63 6B 00 00 00 00 00 00 || "verack" || This is a verack message
|-
| Length || 00 00 00 00 || 0 || Payload is 0 bytes long
|}

=== 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 || var_int || 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
|-
| 1+ || tx_in count || var_int || Number of Transaction inputs
|-
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins
|-
| 1+ || tx_out count || var_int || Number of Transaction outputs
|-
| 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
|-
| 1+ || script length || var_int || The length of the signature script
|-
| ? || signature script || char[] || 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
|-
| 1+ || pk_script length || var_int || Length of the pk_script
|-
| ? || pk_script || char[] || 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 [[script]].

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

Protocol documentation

2011-01-13T18:27:22Z

X6763: /* verack */

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. Variable length integers always precede an array/vector of a type of data that may vary in length.

{|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. This protocol and structure supports IPv6, '''but note that the official client currently only supports IPv4 networking'''.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]?
|-
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The official client only supports IPv4 and only reads the last 4 bytes to get the IPv4 address. However, the official client writes the IPv4 address into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).
|-
| 2 || port || uint16_t || port number, network byte order
|}

Hexdump example of Network address structure

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

{|class="wikitable"
! Name !! Bytes !! Value || Description/Notes
|-
| Services || 01 00 00 00 00 00 00 00 || 1 || NODE_NETWORK? (see services listed in the [[#version|version]] command)
|-
| IP Address || 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 || IPv6: ::ffff:10.0.0.1 ([http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address])
IPv4: 10.0.0.1
||
Network byte order. The official client only uses the last 4 bytes as an IPv4 address.
|-
| Port || 20 8D || 8333 || 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.
|}

Hexdump example of version message (note the message header for this version message does not have a checksum):
<pre>
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................
0040 DA F6 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,
0060 3A B4 57 13 00 55 81 01 00 :.W..U...
</pre>
{|class="wikitable"
! Name !! Bytes !! Value !! Description
|-
|colspan="3"| '''Message Header'''
|-
| Network || F9 BE B4 D9 || n/a || Main network magic bytes
|-
| Command || 76 65 72 73 69 6F 6E 00 00 00 00 00 || "version" || This is a version message
|-
| Length || 55 00 00 00 || 85 || Payload is 85 bytes long
|-
| Checksum || n/a || n/a || No checksum in version message
|-
|colspan="3"| '''Version payload'''
|-
| Version || 9C 7C 00 00 || 31900 || version 0.3.19 (client version? protocol version?)
|-
| Services || 01 00 00 00 00 00 00 00 || 1 || NODE_NETWORK
|-
| Timestamp || E6 15 10 4D 00 00 00 00 || 1292899814 || 1292899814 seconds since 1970 (Dec 20 21:50:14 EST 2010)
|-
| Sender Address || 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 DA F6 || Services: 1
IP/port: 10.0.0.1:8333
|| Address information of node that sent this message (see [[#Network address|Network address]])
|-
| Recipient Address || 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D || Services: 1
IP/port: 10.0.0.2:8333
|| Address information of node receiving this message (see [[#Network address|Network address]])
|-
| Nonce || DD 9D 20 2C 3A B4 57 13 || n/a || Node random unique id. This id is used to detect connections to self
|-
| Sub-version number || 00 || n/a || Empty sub-version string (sub-version info is 0 bytes long)
|-
| Start height || 55 81 01 00 || 98645 || The number of the last block received by the sending node
|}

=== verack ===

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

Hexdump of the verack message:

<pre>
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......
0010 00 00 00 00
</pre>

{|class="wikitable"
! Name !! Bytes !! Value !! Description
|-
|colspan="4"| '''Message Header'''
|-
| Network || F9 BE B4 D9 || n/a || Main network magic bytes
|-
| Command || 76 65 72 61 63 6B 00 00 00 00 00 00 || "verack" || This is a verack message
|-
| Length || 00 00 00 00 || 0 || Payload is 0 bytes long
|}

=== 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 || var_int || 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
|-
| 1+ || tx_in count || var_int || Number of Transaction inputs
|-
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins
|-
| 1+ || tx_out count || var_int || Number of Transaction outputs
|-
| 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
|-
| 1+ || script length || var_int || The length of the signature script
|-
| ? || signature script || char[] || 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
|-
| 1+ || pk_script length || var_int || Length of the pk_script
|-
| ? || pk_script || char[] || 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 [[script]].

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

Protocol documentation

2011-01-13T18:24:35Z

X6763: /* version */

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. Variable length integers always precede an array/vector of a type of data that may vary in length.

{|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. This protocol and structure supports IPv6, '''but note that the official client currently only supports IPv4 networking'''.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]?
|-
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The official client only supports IPv4 and only reads the last 4 bytes to get the IPv4 address. However, the official client writes the IPv4 address into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).
|-
| 2 || port || uint16_t || port number, network byte order
|}

Hexdump example of Network address structure

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

{|class="wikitable"
! Name !! Bytes !! Value || Description/Notes
|-
| Services || 01 00 00 00 00 00 00 00 || 1 || NODE_NETWORK? (see services listed in the [[#version|version]] command)
|-
| IP Address || 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 || IPv6: ::ffff:10.0.0.1 ([http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address])
IPv4: 10.0.0.1
||
Network byte order. The official client only uses the last 4 bytes as an IPv4 address.
|-
| Port || 20 8D || 8333 || 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.
|}

Hexdump example of version message (note the message header for this version message does not have a checksum):
<pre>
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................
0040 DA F6 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,
0060 3A B4 57 13 00 55 81 01 00 :.W..U...
</pre>
{|class="wikitable"
! Name !! Bytes !! Value !! Description
|-
|colspan="3"| '''Message Header'''
|-
| Network || F9 BE B4 D9 || n/a || Main network magic bytes
|-
| Command || 76 65 72 73 69 6F 6E 00 00 00 00 00 || "version" || This is a version message
|-
| Length || 55 00 00 00 || 85 || Payload is 85 bytes long
|-
| Checksum || n/a || n/a || No checksum in version message
|-
|colspan="3"| '''Version payload'''
|-
| Version || 9C 7C 00 00 || 31900 || version 0.3.19 (client version? protocol version?)
|-
| Services || 01 00 00 00 00 00 00 00 || 1 || NODE_NETWORK
|-
| Timestamp || E6 15 10 4D 00 00 00 00 || 1292899814 || 1292899814 seconds since 1970 (Dec 20 21:50:14 EST 2010)
|-
| Sender Address || 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 DA F6 || Services: 1
IP/port: 10.0.0.1:8333
|| Address information of node that sent this message (see [[#Network address|Network address]])
|-
| Recipient Address || 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D || Services: 1
IP/port: 10.0.0.2:8333
|| Address information of node receiving this message (see [[#Network address|Network address]])
|-
| Nonce || DD 9D 20 2C 3A B4 57 13 || n/a || Node random unique id. This id is used to detect connections to self
|-
| Sub-version number || 00 || n/a || Empty sub-version string (sub-version info is 0 bytes long)
|-
| Start height || 55 81 01 00 || 98645 || The number of the last block received by the sending node
|}

=== verack ===

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

Hexdump of the verack message:

<pre>
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......
0010 00 00 00 00
</pre>

{|class="wikitable"
! Name !! Bytes !! Value !! Description
|-
|colspan="3"| '''Message Header'''
|-
| Network || F9 BE B4 D9 || n/a || Main network magic bytes
|-
| Command || 76 65 72 61 63 6B 00 00 00 00 00 00 || "verack" || This is a verack message
|-
| Length || 00 00 00 00 || 0 || Payload is 0 bytes long
|}

=== 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 || var_int || 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
|-
| 1+ || tx_in count || var_int || Number of Transaction inputs
|-
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins
|-
| 1+ || tx_out count || var_int || Number of Transaction outputs
|-
| 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
|-
| 1+ || script length || var_int || The length of the signature script
|-
| ? || signature script || char[] || 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
|-
| 1+ || pk_script length || var_int || Length of the pk_script
|-
| ? || pk_script || char[] || 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 [[script]].

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

Protocol documentation

2011-01-13T18:15:17Z

X6763: /* version */

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. Variable length integers always precede an array/vector of a type of data that may vary in length.

{|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. This protocol and structure supports IPv6, '''but note that the official client currently only supports IPv4 networking'''.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]?
|-
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The official client only supports IPv4 and only reads the last 4 bytes to get the IPv4 address. However, the official client writes the IPv4 address into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).
|-
| 2 || port || uint16_t || port number, network byte order
|}

Hexdump example of Network address structure

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

{|class="wikitable"
! Name !! Bytes !! Value || Description/Notes
|-
| Services || 01 00 00 00 00 00 00 00 || 1 || NODE_NETWORK? (see services listed in the [[#version|version]] command)
|-
| IP Address || 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 || IPv6: ::ffff:10.0.0.1 ([http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address])
IPv4: 10.0.0.1
||
Network byte order. The official client only uses the last 4 bytes as an IPv4 address.
|-
| Port || 20 8D || 8333 || 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.
|}

Hexdump example of version message (note the message header for this version message does not have a checksum):
<pre>
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................
0040 DA F6 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,
0060 3A B4 57 13 00 55 81 01 00 :.W..U...
</pre>
{|class="wikitable"
! Name !! Bytes !! Description
|-
|colspan="3"| '''Message Header'''
|-
| Network || F9 BE B4 D9 || Main network magic bytes
|-
| Command || 76 65 72 73 69 6F 6E 00 00 00 00 00 || "version"
|-
| Length || 55 00 00 00 || Payload is 85 bytes
|-
| Checksum || n/a || No checksum in version message
|-
|colspan="3"| '''Version payload'''
|-
| Version || 9C 7C 00 00 || 31900 (version 0.3.19)
|-
| Services || 01 00 00 00 00 00 00 00 || NODE_NETWORK
|-
| Timestamp || E6 15 10 4D 00 00 00 00 || 1292899814 seconds since 1970 (Dec 20 21:50:14 EST 2010)
|-
| Sender Address || 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 DA F6 || Address information of node that sent this message (see [[#Network address|Network address]])
|-
| Recipient Address || 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D || Address information of node receiving this message (see [[#Network address|Network address]])
|-
| Nonce || DD 9D 20 2C 3A B4 57 13 || Node random unique id. This id is used to detect connections to self
|-
| Sub-version number || 00 || No sub-version info (sub-version info is 0 bytes long)
|-
| Start height || 55 81 01 00 || 98645 (The last block received by the sending node)
|}

=== verack ===

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

Hexdump of the verack message:

<pre>
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......
0010 00 00 00 00
</pre>

{|class="wikitable"
! Name !! Bytes !! Value !! Description
|-
|colspan="3"| '''Message Header'''
|-
| Network || F9 BE B4 D9 || n/a || Main network magic bytes
|-
| Command || 76 65 72 61 63 6B 00 00 00 00 00 00 || "verack" || This is a verack message
|-
| Length || 00 00 00 00 || 0 || Payload is 0 bytes long
|}

=== 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 || var_int || 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
|-
| 1+ || tx_in count || var_int || Number of Transaction inputs
|-
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins
|-
| 1+ || tx_out count || var_int || Number of Transaction outputs
|-
| 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
|-
| 1+ || script length || var_int || The length of the signature script
|-
| ? || signature script || char[] || 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
|-
| 1+ || pk_script length || var_int || Length of the pk_script
|-
| ? || pk_script || char[] || 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 [[script]].

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

Protocol documentation

2011-01-13T18:10:39Z

X6763: /* verack */

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. Variable length integers always precede an array/vector of a type of data that may vary in length.

{|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. This protocol and structure supports IPv6, '''but note that the official client currently only supports IPv4 networking'''.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]?
|-
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The official client only supports IPv4 and only reads the last 4 bytes to get the IPv4 address. However, the official client writes the IPv4 address into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).
|-
| 2 || port || uint16_t || port number, network byte order
|}

Hexdump example of Network address structure

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

{|class="wikitable"
! Name !! Bytes !! Value || Description/Notes
|-
| Services || 01 00 00 00 00 00 00 00 || 1 || NODE_NETWORK? (see services listed in the [[#version|version]] command)
|-
| IP Address || 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 || IPv6: ::ffff:10.0.0.1 ([http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address])
IPv4: 10.0.0.1
||
Network byte order. The official client only uses the last 4 bytes as an IPv4 address.
|-
| Port || 20 8D || 8333 || 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.
|}

Hexdump example of version message (note the message header for this version message does not have a checksum):
<pre>
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................
0040 DA F6 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,
0060 3A B4 57 13 00 55 81 01 00 :.W..U...
</pre>
{|class="wikitable"
! Name !! Value !! Description
|-
|colspan="3"| '''Message Header'''
|-
| Network || F9 BE B4 D9 || Main network magic bytes
|-
| Command || 76 65 72 73 69 6F 6E 00 00 00 00 00 || "version"
|-
| Length || 55 00 00 00 || Payload is 85 bytes
|-
| Checksum || n/a || No checksum in version message
|-
|colspan="3"| '''Version payload'''
|-
| Version || 9C 7C 00 00 || 31900 (version 0.3.19)
|-
| Services || 01 00 00 00 00 00 00 00 || NODE_NETWORK
|-
| Timestamp || E6 15 10 4D 00 00 00 00 || 1292899814 seconds since 1970 (Dec 20 21:50:14 EST 2010)
|-
| Sender Address || 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 DA F6 || Address information of node that sent this message (see [[#Network address|Network address]])
|-
| Recipient Address || 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D || Address information of node receiving this message (see [[#Network address|Network address]])
|-
| Nonce || DD 9D 20 2C 3A B4 57 13 || Node random unique id. This id is used to detect connections to self
|-
| Sub-version number || 00 || No sub-version info (sub-version info is 0 bytes long)
|-
| Start height || 55 81 01 00 || 98645 (The last block received by the sending node)
|}

=== verack ===

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

Hexdump of the verack message:

<pre>
0000 F9 BE B4 D9 76 65 72 61 63 6B 00 00 00 00 00 00 ....verack......
0010 00 00 00 00
</pre>

{|class="wikitable"
! Name !! Bytes !! Value !! Description
|-
|colspan="3"| '''Message Header'''
|-
| Network || F9 BE B4 D9 || n/a || Main network magic bytes
|-
| Command || 76 65 72 61 63 6B 00 00 00 00 00 00 || "verack" || This is a verack message
|-
| Length || 00 00 00 00 || 0 || Payload is 0 bytes long
|}

=== 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 || var_int || 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
|-
| 1+ || tx_in count || var_int || Number of Transaction inputs
|-
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins
|-
| 1+ || tx_out count || var_int || Number of Transaction outputs
|-
| 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
|-
| 1+ || script length || var_int || The length of the signature script
|-
| ? || signature script || char[] || 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
|-
| 1+ || pk_script length || var_int || Length of the pk_script
|-
| ? || pk_script || char[] || 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 [[script]].

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

Talk:Protocol documentation

2011-01-13T18:01:43Z

X6763: Created page with "I'm adding some hexdumps of messages and data structures and descriptions of how these are interpreted in order to help others understand these protocol and data structures. It'..."

I'm adding some hexdumps of messages and data structures and descriptions of how these are interpreted in order to help others understand these protocol and data structures. It's a bit redundant, so any ideas as to how to remove some of the redundancy while keeping the knowledge accessible are welcome (feel free to make the changes yourself!). -- [[User:X6763|X6763]]

Protocol documentation

2011-01-13T17:53:15Z

X6763: /* Network address */

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. Variable length integers always precede an array/vector of a type of data that may vary in length.

{|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. This protocol and structure supports IPv6, '''but note that the official client currently only supports IPv4 networking'''.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]?
|-
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The official client only supports IPv4 and only reads the last 4 bytes to get the IPv4 address. However, the official client writes the IPv4 address into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).
|-
| 2 || port || uint16_t || port number, network byte order
|}

Hexdump example of Network address structure

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

{|class="wikitable"
! Name !! Bytes !! Value || Description/Notes
|-
| Services || 01 00 00 00 00 00 00 00 || 1 || NODE_NETWORK? (see services listed in the [[#version|version]] command)
|-
| IP Address || 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 || IPv6: ::ffff:10.0.0.1 ([http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address])
IPv4: 10.0.0.1
||
Network byte order. The official client only uses the last 4 bytes as an IPv4 address.
|-
| Port || 20 8D || 8333 || 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.
|}

Hexdump example of version message (note the message header for this version message does not have a checksum):
<pre>
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................
0040 DA F6 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,
0060 3A B4 57 13 00 55 81 01 00 :.W..U...
</pre>
{|class="wikitable"
! Name !! Value !! Description
|-
|colspan="3"| '''Message Header'''
|-
| Network || F9 BE B4 D9 || Main network magic bytes
|-
| Command || 76 65 72 73 69 6F 6E 00 00 00 00 00 || "version"
|-
| Length || 55 00 00 00 || Payload is 85 bytes
|-
| Checksum || n/a || No checksum in version message
|-
|colspan="3"| '''Version payload'''
|-
| Version || 9C 7C 00 00 || 31900 (version 0.3.19)
|-
| Services || 01 00 00 00 00 00 00 00 || NODE_NETWORK
|-
| Timestamp || E6 15 10 4D 00 00 00 00 || 1292899814 seconds since 1970 (Dec 20 21:50:14 EST 2010)
|-
| Sender Address || 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 DA F6 || Address information of node that sent this message (see [[#Network address|Network address]])
|-
| Recipient Address || 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D || Address information of node receiving this message (see [[#Network address|Network address]])
|-
| Nonce || DD 9D 20 2C 3A B4 57 13 || Node random unique id. This id is used to detect connections to self
|-
| Sub-version number || 00 || No sub-version info (sub-version info is 0 bytes long)
|-
| Start height || 55 81 01 00 || 98645 (The last block received by the sending node)
|}

=== 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 || var_int || 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
|-
| 1+ || tx_in count || var_int || Number of Transaction inputs
|-
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins
|-
| 1+ || tx_out count || var_int || Number of Transaction outputs
|-
| 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
|-
| 1+ || script length || var_int || The length of the signature script
|-
| ? || signature script || char[] || 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
|-
| 1+ || pk_script length || var_int || Length of the pk_script
|-
| ? || pk_script || char[] || 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 [[script]].

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

Protocol documentation

2011-01-13T17:37:06Z

X6763: /* Variable length integer */

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. Variable length integers always precede an array/vector of a type of data that may vary in length.

{|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. This protocol and structure supports IPv6, '''but note that the official client currently only supports IPv4 networking'''.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]?
|-
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The official client only supports IPv4 and only reads the last 4 bytes to get the IPv4 address. However, the official client writes the IPv4 address into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).
|-
| 2 || port || uint16_t || port number, network byte order
|}

Hexdump example of Network address structure

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

{|class="wikitable"
! Name !! Value !! Description
|-
| Services || 01 00 00 00 00 00 00 00 || NODE_NETWORK? (see services listed in the [[#version|version]] command)
|-
| IP Address || 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 || 10.0.0.1 (or ::ffff:10.0.0.1 as an [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address])
When reading the message containing an address structure, the official client ignores first 12 bytes and uses last 4 bytes as IPv4 address.
|-
| Port || 20 8D || 8333
|}

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

Hexdump example of version message (note the message header for this version message does not have a checksum):
<pre>
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................
0040 DA F6 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,
0060 3A B4 57 13 00 55 81 01 00 :.W..U...
</pre>
{|class="wikitable"
! Name !! Value !! Description
|-
|colspan="3"| '''Message Header'''
|-
| Network || F9 BE B4 D9 || Main network magic bytes
|-
| Command || 76 65 72 73 69 6F 6E 00 00 00 00 00 || "version"
|-
| Length || 55 00 00 00 || Payload is 85 bytes
|-
| Checksum || n/a || No checksum in version message
|-
|colspan="3"| '''Version payload'''
|-
| Version || 9C 7C 00 00 || 31900 (version 0.3.19)
|-
| Services || 01 00 00 00 00 00 00 00 || NODE_NETWORK
|-
| Timestamp || E6 15 10 4D 00 00 00 00 || 1292899814 seconds since 1970 (Dec 20 21:50:14 EST 2010)
|-
| Sender Address || 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 DA F6 || Address information of node that sent this message (see [[#Network address|Network address]])
|-
| Recipient Address || 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D || Address information of node receiving this message (see [[#Network address|Network address]])
|-
| Nonce || DD 9D 20 2C 3A B4 57 13 || Node random unique id. This id is used to detect connections to self
|-
| Sub-version number || 00 || No sub-version info (sub-version info is 0 bytes long)
|-
| Start height || 55 81 01 00 || 98645 (The last block received by the sending node)
|}

=== 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 || var_int || 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
|-
| 1+ || tx_in count || var_int || Number of Transaction inputs
|-
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins
|-
| 1+ || tx_out count || var_int || Number of Transaction outputs
|-
| 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
|-
| 1+ || script length || var_int || The length of the signature script
|-
| ? || signature script || char[] || 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
|-
| 1+ || pk_script length || var_int || Length of the pk_script
|-
| ? || pk_script || char[] || 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 [[script]].

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

Protocol documentation

2011-01-13T17:35:21Z

X6763: /* Variable length integer */

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. Variable length integers always precede an array/vector of data (bytes/chars, blocks, transactions, etc).

{|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. This protocol and structure supports IPv6, '''but note that the official client currently only supports IPv4 networking'''.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]?
|-
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The official client only supports IPv4 and only reads the last 4 bytes to get the IPv4 address. However, the official client writes the IPv4 address into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).
|-
| 2 || port || uint16_t || port number, network byte order
|}

Hexdump example of Network address structure

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

{|class="wikitable"
! Name !! Value !! Description
|-
| Services || 01 00 00 00 00 00 00 00 || NODE_NETWORK? (see services listed in the [[#version|version]] command)
|-
| IP Address || 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 || 10.0.0.1 (or ::ffff:10.0.0.1 as an [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address])
When reading the message containing an address structure, the official client ignores first 12 bytes and uses last 4 bytes as IPv4 address.
|-
| Port || 20 8D || 8333
|}

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

Hexdump example of version message (note the message header for this version message does not have a checksum):
<pre>
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................
0040 DA F6 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,
0060 3A B4 57 13 00 55 81 01 00 :.W..U...
</pre>
{|class="wikitable"
! Name !! Value !! Description
|-
|colspan="3"| '''Message Header'''
|-
| Network || F9 BE B4 D9 || Main network magic bytes
|-
| Command || 76 65 72 73 69 6F 6E 00 00 00 00 00 || "version"
|-
| Length || 55 00 00 00 || Payload is 85 bytes
|-
| Checksum || n/a || No checksum in version message
|-
|colspan="3"| '''Version payload'''
|-
| Version || 9C 7C 00 00 || 31900 (version 0.3.19)
|-
| Services || 01 00 00 00 00 00 00 00 || NODE_NETWORK
|-
| Timestamp || E6 15 10 4D 00 00 00 00 || 1292899814 seconds since 1970 (Dec 20 21:50:14 EST 2010)
|-
| Sender Address || 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 DA F6 || Address information of node that sent this message (see [[#Network address|Network address]])
|-
| Recipient Address || 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D || Address information of node receiving this message (see [[#Network address|Network address]])
|-
| Nonce || DD 9D 20 2C 3A B4 57 13 || Node random unique id. This id is used to detect connections to self
|-
| Sub-version number || 00 || No sub-version info (sub-version info is 0 bytes long)
|-
| Start height || 55 81 01 00 || 98645 (The last block received by the sending node)
|}

=== 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 || var_int || 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
|-
| 1+ || tx_in count || var_int || Number of Transaction inputs
|-
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins
|-
| 1+ || tx_out count || var_int || Number of Transaction outputs
|-
| 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
|-
| 1+ || script length || var_int || The length of the signature script
|-
| ? || signature script || char[] || 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
|-
| 1+ || pk_script length || var_int || Length of the pk_script
|-
| ? || pk_script || char[] || 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 [[script]].

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

Protocol documentation

2011-01-13T17:09:13Z

X6763: /* Network address */

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. This protocol and structure supports IPv6, '''but note that the official client currently only supports IPv4 networking'''.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]?
|-
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The official client only supports IPv4 and only reads the last 4 bytes to get the IPv4 address. However, the official client writes the IPv4 address into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).
|-
| 2 || port || uint16_t || port number, network byte order
|}

Hexdump example of Network address structure

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

{|class="wikitable"
! Name !! Value !! Description
|-
| Services || 01 00 00 00 00 00 00 00 || NODE_NETWORK? (see services listed in the [[#version|version]] command)
|-
| IP Address || 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 || 10.0.0.1 (or ::ffff:10.0.0.1 as an [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address])
When reading the message containing an address structure, the official client ignores first 12 bytes and uses last 4 bytes as IPv4 address.
|-
| Port || 20 8D || 8333
|}

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

Hexdump example of version message (note the message header for this version message does not have a checksum):
<pre>
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................
0040 DA F6 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,
0060 3A B4 57 13 00 55 81 01 00 :.W..U...
</pre>
{|class="wikitable"
! Name !! Value !! Description
|-
|colspan="3"| '''Message Header'''
|-
| Network || F9 BE B4 D9 || Main network magic bytes
|-
| Command || 76 65 72 73 69 6F 6E 00 00 00 00 00 || "version"
|-
| Length || 55 00 00 00 || Payload is 85 bytes
|-
| Checksum || n/a || No checksum in version message
|-
|colspan="3"| '''Version payload'''
|-
| Version || 9C 7C 00 00 || 31900 (version 0.3.19)
|-
| Services || 01 00 00 00 00 00 00 00 || NODE_NETWORK
|-
| Timestamp || E6 15 10 4D 00 00 00 00 || 1292899814 seconds since 1970 (Dec 20 21:50:14 EST 2010)
|-
| Sender Address || 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 DA F6 || Address information of node that sent this message (see [[#Network address|Network address]])
|-
| Recipient Address || 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D || Address information of node receiving this message (see [[#Network address|Network address]])
|-
| Nonce || DD 9D 20 2C 3A B4 57 13 || Node random unique id. This id is used to detect connections to self
|-
| Sub-version number || 00 || No sub-version info (sub-version info is 0 bytes long)
|-
| Start height || 55 81 01 00 || 98645 (The last block received by the sending node)
|}

=== 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 || var_int || 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
|-
| 1+ || tx_in count || var_int || Number of Transaction inputs
|-
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins
|-
| 1+ || tx_out count || var_int || Number of Transaction outputs
|-
| 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
|-
| 1+ || script length || var_int || The length of the signature script
|-
| ? || signature script || char[] || 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
|-
| 1+ || pk_script length || var_int || Length of the pk_script
|-
| ? || pk_script || char[] || 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 [[script]].

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

Protocol documentation

2011-01-13T17:08:46Z

X6763: /* Network address */

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. This protocol and structure supports IPv6, '''but note that the official client currently only supports IPv4 networking'''.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]?
|-
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The official client only supports IPv4 and only reads the last 4 bytes to get the IPv4 address. However, the official client writes the IPv4 address into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).
|-
| 2 || port || uint16_t || port number, network byte order
|}

Hexdump example of Network address structure

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

{|class="wikitable"
! Name !! Value !! Description
|-
| Services || 01 00 00 00 00 00 00 00 || NODE_NETWORK? (see services listed in the [[#version|version]] command)
|-
| IP Address || 00 00 00 00 00 00 00 00 00 00 FF FF
0A 00 00 01
|| 10.0.0.1 (or ::ffff:10.0.0.1 as an [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address])
When reading the message containing an address structure, the official client ignores first 12 bytes and uses last 4 bytes as IPv4 address.
|-
| Port || 20 8D || 8333
|}

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

Hexdump example of version message (note the message header for this version message does not have a checksum):
<pre>
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................
0040 DA F6 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,
0060 3A B4 57 13 00 55 81 01 00 :.W..U...
</pre>
{|class="wikitable"
! Name !! Value !! Description
|-
|colspan="3"| '''Message Header'''
|-
| Network || F9 BE B4 D9 || Main network magic bytes
|-
| Command || 76 65 72 73 69 6F 6E 00 00 00 00 00 || "version"
|-
| Length || 55 00 00 00 || Payload is 85 bytes
|-
| Checksum || n/a || No checksum in version message
|-
|colspan="3"| '''Version payload'''
|-
| Version || 9C 7C 00 00 || 31900 (version 0.3.19)
|-
| Services || 01 00 00 00 00 00 00 00 || NODE_NETWORK
|-
| Timestamp || E6 15 10 4D 00 00 00 00 || 1292899814 seconds since 1970 (Dec 20 21:50:14 EST 2010)
|-
| Sender Address || 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 DA F6 || Address information of node that sent this message (see [[#Network address|Network address]])
|-
| Recipient Address || 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D || Address information of node receiving this message (see [[#Network address|Network address]])
|-
| Nonce || DD 9D 20 2C 3A B4 57 13 || Node random unique id. This id is used to detect connections to self
|-
| Sub-version number || 00 || No sub-version info (sub-version info is 0 bytes long)
|-
| Start height || 55 81 01 00 || 98645 (The last block received by the sending node)
|}

=== 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 || var_int || 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
|-
| 1+ || tx_in count || var_int || Number of Transaction inputs
|-
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins
|-
| 1+ || tx_out count || var_int || Number of Transaction outputs
|-
| 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
|-
| 1+ || script length || var_int || The length of the signature script
|-
| ? || signature script || char[] || 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
|-
| 1+ || pk_script length || var_int || Length of the pk_script
|-
| ? || pk_script || char[] || 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 [[script]].

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

Protocol documentation

2011-01-13T17:03:30Z

X6763: /* Network address */

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. This protocol and structure supports IPv6, '''but note that the official client currently only supports IPv4'''.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]?
|-
| 16 || IPv6/4 || char[16] || IPv6 address. Network byte order. The official client only supports IPv4 and uses the last 4 bytes as the IPv4 address. However, the official client writes the IPv4 address into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).
|-
| 2 || port || uint16_t || port number, network byte order
|}

Hexdump example of Network address structure

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

{|class="wikitable"
! Name !! Value !! Description
|-
| Services || 01 00 00 00 00 00 00 00 || NODE_NETWORK? (see services listed in [[#version|version]])
|-
| IP Address || 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 || 10.0.0.1 (or ::ffff:10.0.0.1 as an [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address])
When reading the message containing an address structure, the official client ignores first 12 bytes and uses last 4 bytes as IPv4 address.
|-
| Port || 20 8D || 8333
|}

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

Hexdump example of version message (note the message header for this version message does not have a checksum):
<pre>
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................
0040 DA F6 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,
0060 3A B4 57 13 00 55 81 01 00 :.W..U...
</pre>
{|class="wikitable"
! Name !! Value !! Description
|-
|colspan="3"| '''Message Header'''
|-
| Network || F9 BE B4 D9 || Main network magic bytes
|-
| Command || 76 65 72 73 69 6F 6E 00 00 00 00 00 || "version"
|-
| Length || 55 00 00 00 || Payload is 85 bytes
|-
| Checksum || n/a || No checksum in version message
|-
|colspan="3"| '''Version payload'''
|-
| Version || 9C 7C 00 00 || 31900 (version 0.3.19)
|-
| Services || 01 00 00 00 00 00 00 00 || NODE_NETWORK
|-
| Timestamp || E6 15 10 4D 00 00 00 00 || 1292899814 seconds since 1970 (Dec 20 21:50:14 EST 2010)
|-
| Sender Address || 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 DA F6 || Address information of node that sent this message (see [[#Network address|Network address]])
|-
| Recipient Address || 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D || Address information of node receiving this message (see [[#Network address|Network address]])
|-
| Nonce || DD 9D 20 2C 3A B4 57 13 || Node random unique id. This id is used to detect connections to self
|-
| Sub-version number || 00 || No sub-version info (sub-version info is 0 bytes long)
|-
| Start height || 55 81 01 00 || 98645 (The last block received by the sending node)
|}

=== 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 || var_int || 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
|-
| 1+ || tx_in count || var_int || Number of Transaction inputs
|-
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins
|-
| 1+ || tx_out count || var_int || Number of Transaction outputs
|-
| 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
|-
| 1+ || script length || var_int || The length of the signature script
|-
| ? || signature script || char[] || 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
|-
| 1+ || pk_script length || var_int || Length of the pk_script
|-
| ? || pk_script || char[] || 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 [[script]].

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

Protocol documentation

2011-01-13T16:04:42Z

X6763: /* version */ Added hexdump example of Version message

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

Hexdump example of version message (note the message header for this version message does not have a checksum):
<pre>
0000 F9 BE B4 D9 76 65 72 73 69 6F 6E 00 00 00 00 00 ....version.....
0010 55 00 00 00 9C 7C 00 00 01 00 00 00 00 00 00 00 U....|..........
0020 E6 15 10 4D 00 00 00 00 01 00 00 00 00 00 00 00 ...M............
0030 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 ................
0040 DA F6 01 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
0050 00 00 00 00 FF FF 0A 00 00 02 20 8D DD 9D 20 2C .......... ... ,
0060 3A B4 57 13 00 55 81 01 00 :.W..U...
</pre>
{|class="wikitable"
! Name !! Value !! Description
|-
|colspan="3"| '''Message Header'''
|-
| Network || F9 BE B4 D9 || Main network magic bytes
|-
| Command || 76 65 72 73 69 6F 6E 00 00 00 00 00 || "version"
|-
| Length || 55 00 00 00 || Payload is 85 bytes
|-
| Checksum || n/a || No checksum in version message
|-
|colspan="3"| '''Version payload'''
|-
| Version || 9C 7C 00 00 || 31900 (version 0.3.19)
|-
| Services || 01 00 00 00 00 00 00 00 || NODE_NETWORK
|-
| Timestamp || E6 15 10 4D 00 00 00 00 || 1292899814 seconds since 1970 (Dec 20 21:50:14 EST 2010)
|-
| Sender Address || 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 01 DA F6 || Address information of node that sent this message (see [[#Network address|Network address]])
|-
| Recipient Address || 01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 FF FF 0A 00 00 02 20 8D || Address information of node receiving this message (see [[#Network address|Network address]])
|-
| Nonce || DD 9D 20 2C 3A B4 57 13 || Node random unique id. This id is used to detect connections to self
|-
| Sub-version number || 00 || No sub-version info (sub-version info is 0 bytes long)
|-
| Start height || 55 81 01 00 || 98645 (The last block received by the sending node)
|}

=== 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 || var_int || 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
|-
| 1+ || tx_in count || var_int || Number of Transaction inputs
|-
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins
|-
| 1+ || tx_out count || var_int || Number of Transaction outputs
|-
| 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
|-
| 1+ || script length || var_int || The length of the signature script
|-
| ? || signature script || char[] || 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
|-
| 1+ || pk_script length || var_int || Length of the pk_script
|-
| ? || pk_script || char[] || 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 [[script]].

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

User:X6763

2011-01-13T15:23:30Z

X6763: Created page with "Contributors Award participant: 12FVT5Kduf6KSXFmGEAetsqxhMk22ngWpu"

Contributors Award participant: 12FVT5Kduf6KSXFmGEAetsqxhMk22ngWpu

Protocol documentation

2011-01-11T20:22:21Z

X6763: /* tx */

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 || var_int || 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
|-
| 1+ || tx_in count || var_int || Number of Transaction inputs
|-
| 41+ || tx_in || tx_in[] || A list of 1 or more transaction inputs or sources for coins
|-
| 1+ || tx_out count || var_int || Number of Transaction outputs
|-
| 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
|-
| 1+ || script length || var_int || The length of the signature script
|-
| ? || signature script || char[] || 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
|-
| 1+ || pk_script length || var_int || Length of the pk_script
|-
| ? || pk_script || char[] || 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 [[script]].

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

Protocol documentation

2011-01-11T20:18:00Z

X6763: /* getblocks */

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 || var_int || 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
|-
| 1+ || script length || var_int || The length of the signature script
|-
| ? || signature script || char[] || 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
|-
| 1+ || pk_script length || var_int || Length of the pk_script
|-
| ? || pk_script || char[] || 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 [[script]].

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

Protocol documentation

2011-01-11T20:08:29Z

X6763: /* tx */

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
|-
| 1+ || script length || var_int || The length of the signature script
|-
| ? || signature script || char[] || 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
|-
| 1+ || pk_script length || var_int || Length of the pk_script
|-
| ? || pk_script || char[] || 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 [[script]].

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

Protocol documentation

2010-12-29T17:02:59Z

X6763:

Main Page

2010-12-19T18:38:51Z

X6763:

{| id="mp-topbanner" style="width:100%; background:#f6f6f6; margin-top:1.2em; border:1px solid #ddd;"
| style="width:61%; color:#000;" |

{| style="width:100%; border:none; background:none;"
| style="text-align:center; white-space:nowrap; color:#000;" |
<div style="font-size:162%; border:none; margin:0; padding:.1em; color:#000;">Welcome to [[Bitcoin]] wiki,</div>
<div style="top:+0.2em; font-size:95%;">The one stop shop for all your bitcoin information needs.</div>
<div id="articlecount" style="width:100%; text-align:center; font-size:85%;">[[Special:Statistics|{{NUMBEROFARTICLES}}]] articles.</div>
'''Help improve this wiki. Add information [[:Category:Stubs|where needed]] and [[Bitcoin:Contributors Award|earn bitcoins]].'''
|}

| style="width:13%; font-size:95%;" |
* <span class="plainlinks">[http://bitcoin.org Official site]</span>.
* <span class="plainlinks">[http://bitcoinme.com Introduction]</span> to Bitcoin.
* [irc://irc.freenode.net/bitcoin #bitcoin-dev] on freenode
* <span class="plainlinks">[http://lwn.net/Articles/414452/ LWN on Bitcoin]</span>.
|}


{| id="mp-upper" style="width: 100%; margin:6px 0 0 0; background:none; border-spacing: 0px;"
| class="MainPageBG" style="width:55%; border:1px solid #cef2e0; background:#f6e5f1; vertical-align:top; color:#000;" |
{| id="mp-left" style="vertical-align:top; background:#f6e5f1;"
! style="padding:2px;" | <h2 id="mp-tfa-h2" style="margin:3px; background:#e9caef; font-size:120%; font-weight:bold; border:1px solid #a3bfb1; text-align:left; color:#000; padding:0.2em 0.4em;">Bitcoin</h2>
|-
| style="color:#000;" | <div id="mp-tfa" style="padding:2px 5px">{{MainPage_Intro}}</div>
|-
! style="padding:2px" | <h2 id="mp-dyk-h2" style="margin:3px; background:#e9caef; font-size:120%; font-weight:bold; border:1px solid #a3bfb1; text-align:left; color:#000; padding:0.2em 0.4em;">Why</h2>
|-
| style="color:#000;padding:2px 5px 5px" | <div id="mp-dyk">{{MainPage_Reasons}}</div>
|}
| style="border:1px solid transparent;" |

| class="MainPageBG" style="width:45%; border:1px solid #cedff2; background:#f6e5f1; vertical-align:top;"|
{| id="mp-right" style="width:100%; vertical-align:top; background:#f6e5f1;"
! style="padding:2px" | <h2 id="mp-otd-h2" style="margin:3px; background:#efc1e2; font-size:120%; font-weight:bold; border:1px solid #a3b0bf; text-align:left; color:#000; padding:0.2em 0.4em;">Topic central</h2>
|-
| style="color:#000;padding:2px 5px 5px" | <div id="mp-otd">{{MainPage_Topics}}</div>
|-
! style="padding:2px" | <h2 id="mp-otd-h2" style="margin:3px; background:#efc1e2; font-size:120%; font-weight:bold; border:1px solid #a3b0bf; text-align:left; color:#000; padding:0.2em 0.4em;">FAQ</h2>
|-
| style="color:#000;padding:2px 5px 5px" | <div id="mp-otd">{{MainPage_FAQ}}</div>
|}
|}

== Other pages ==

* '''[http://www.mediawiki.org/wiki/Help:Formatting Help]''' - Documentation on wiki editing.
* '''[[Bitcoin.it Wiki|About]]''' - Information on this site.

[[fr:Accueil]]

__NOTOC____NOEDITSECTION__

Deflationary spiral

2010-12-17T14:33:03Z

X6763: /* Economic history */

{{stub}}
'''Deflationary spiral''' is an economic argument that propose that price falling below cost in a runaway deflation would eventually lead to the collapse of the currency. It is a common criticism made against the viability of [[Bitcoin]].
==Effects==
Deflation, like inflation, include winners and losers.

The losers are borrowers, especially those who would have to pay principle plus interest rate. Since the value of loan increase due to inflation, that mean they will have to pay more in real term.

The winners include anybody who had saved. Thus, an deflationary environment would automatically encourage more people to save for the expectation of increasing purchasing power.

==Economic history==
The first deflationary phase is a phase of economic growth caused by the slashdot effect. From there, we see the the price of bitcoin rose to 0.06 USD. This price level remain stable until early October, when a rally cause the price to touch .50 USD before settling at the .20-30 USD equilibrium.

There will only be 21 million bitcoin in the world, ever. Thus, it is expected that the value of bitcoin to rise in correlation with the number of people using it, as well increase in productivity. Further deflation can occurs with people losing their wallet, thus all access to their bitcoin. While the destruction of bitcoin never occurs, the loss of key to access it effectively mean that bitcoin can never be used again.

Over the long term, as long as the combination of the two causes hold true, deflation will continue to an absurd level.

==Counterargument==
Opponents counter that the deflationary spiral is not possible because of the Time Preference theory and the necessary end goal of money; to purchase goods and services.

Opponents had argued that humans will prefer something now rather than latter, all things being equal. Thus, something that happen sooner is more valuable than what happens further down the road.

Furthermore, there is a natural limit to human's time preference. A human being cannot wait indefinitely to not spend money on food, milks, and other goods without suffering some kind of hit to a human being's health.
[[Category:Economics]]