User:Zhangqianxun/sandbox

Sources:
 * Original Bitcoin client source
 * Draft spec on bitcoin wiki

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

Hashes
Usually, when a hash is computed within bitcoin, it is computed twice. Most of the time SHA-256 hashes are used, however 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 Elliptic Curve 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   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:

Bitcoin Address = Base58Encode(RIPEMD-160(SHA-256(public key)))

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
Known magic values:

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

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

Network address
When a network address is needed somewhere, this structure is used (currently only supports ipv4).

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:

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

Other Data Type values are considered reserved for future implementations.

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:

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:

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

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

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

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:

tx
tx describes a bitcoin transaction, in reply to getdata

TxIn consists of the following fields:

The OutPoint structure consists of the following fields:

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:

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

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:

submitorder
Confirms an order has been submitted.

Payload:

reply
Generic reply for IP Transactions

Payload:

Possible values:

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:

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

04fc9702847840aaf195de8442ebecedf5b095cdbb9bc716bda9110971b28a49e0ead8564ff0db22209e0374782c093bb899692d524e9d6a6956e7c5ecbcd68284 (hash) 1AGRxqDa5WjUKBwHB9XYEjmkv1ucoUUy1s

Source:

Scripting
See (TODO)