Network

Bitcoin uses a simple broadcast network to propagate transactions and blocks. All communications are done over TCP. Bitcoin is fully able to use ports other than 8333, but there is currently no option to change this. IPv6 is currently not supported.

Messages

• version - Information about program version and block count. Exchanged when first connecting.
• verack - Sent in response to a version message to acknowledge that we are willing to connect.
• addr - List of one or more IP addresses and ports.
• inv - "I have these blocks/transactions: ..." Normally sent only when a new block or transaction is being relayed. This is only a list, not the actual data.
• getdata - Request a single block or transaction by hash.
• getblocks - Request an inv of all blocks in a range.
• getheaders - Request a headers message containing all block headers in a range.
• tx - Send a transaction. This is only sent in response to a getdata request.
• block - Send a block. This is only sent in response to a getdata request.
• headers - Send up to 2,000 block headers. Non-generators can download the headers of blocks instead of entire blocks.
• getaddr - Request an addr message containing a bunch of known-active peers (for bootstrapping).
• submitorder, checkorder, and reply - Used when performing an IP transaction.
• alert - Send a network alert.
• ping - Does nothing. Used to check that the connection is still online. A TCP error will occur if the connection has died.

More information and in-depth technical information is in the Protocol Specification.

Connection

To connect to a peer, you send a version message containing your version number, block count, and current time. The remote peer will send back a verack message and his own version message if he is accepting connections from your version. You will respond with your own verack if you are accepting connections from his version.

The time data from all of your peers is collected, and the median is used by Bitcoin for all network tasks that use the time (except for other version messages).

You then exchange getaddr and addr messages, storing all addresses that you don't know about. Normally addr messages only contain one address, but in this initial exchange it contains many recent peers.

Standard relaying

When someone sends a transaction, they send an inv message containing it to all of their peers. Their peers will request the full transaction with getdata. If they consider the transaction valid after receiving it, they will also broadcast the transaction to all of their peers with an inv, and so on. Peers only ask for or relay transactions if they don't already have them. A peer will never rebroadcast a transaction that it already knows about, though transactions will eventually be forgotten if they don't get into a block after a while. The sender and receiver of the transaction will rebroadcast, however.

Anyone who is generating will collect valid received transactions and work on including them in a block. When someone does find a block, they send an inv containing it to all of their peers, as above. It works the same as transactions.

Everyone broadcasts an addr containing their own IP address every 24 hours. Nodes relay these messages to a couple of their peers and store the address if it's new to them. Through this system, everyone has a reasonably clear picture of which IPs are connected to the network at the moment. After connecting to the network, you get added to everyone's address database almost instantly because of your initial addr.

Network alerts are broadcast with alert messages. No inv-like system is used; these contain the entire alert. If a received alert is valid (signed by Satoshi), it is relayed to all peers. For as long as an alert is still in effect, it is rebroadcast at the start of every new connection.

Initial block download

At the start of a connection, you send a getblocks message containing the hash of the latest block you know about. If the peer doesn't think that this is the latest block, it will send an inv that contains up to 500 blocks ahead of the one you listed. You will then request all of these blocks with getdata, and the peer will send them to you with block messages. After you have downloaded and processed all of these blocks, you will send another getblocks, etc., until you have all of the blocks.

0.3.18 introduced new headers and getheaders messages. These are not currently used, but they will be used by non-generators to download block headers without the corresponding block bodies. Only the headers are necessary for verifying received transactions -- full blocks are only needed by generators. Instead of the getblocks/inv/getdata/block sequence, non-generators will send a getheaders message (very like getblocks), and the peer will immediately respond with a headers message containing up to 2,000 of the next headers. This will make initial block download much faster.

Bootstrapping

You choose which peers to connect to by sorting your address database by the time since you last saw the address and then adding a bit of randomization.

Bitcoin has two methods of finding peers.

IRC

Bitcoin joins the #bitcoin channel on irc.lfnet.org. Your nick is set to an encoded form of your IP address. By decoding all the nicks of all users on the channel, you get a list of all IP addresses currently connected to Bitcoin.

Addr

The addr messages described above create an effect similar to the IRC bootstrapping method. You know reasonably quickly whenever a peer joins, though you won't know for a while when they leave.

Bitcoin comes with an address database already populated by a few addresses. If you are unable to connect to IRC and you've never connected to the network before, you will get an updated address database by connecting to one of these "seednodes".

Heartbeat

If thirty minutes or more has passed since the client has transmitted any messages it will transmit a message to keep the connection to the peer node alive.

If ninety minutes has passed since a peer node has communicated any messages, then the client will assume that connection has closed.

See Also

• Protocol Specification