A few days ago, I had a brief technical chat with a friend who finds the world of distributed systems fascinating, regarding the Bitcoin handshake process. Although our conversation initially revolved around the necessity of achieving consensus within systems, we soon focused on the necessary step for one system to start communicating with another, known as the handshake. We only touched on a few aspects, but later, with more time on my hands and out of curiosity, I decided to delve deeper into the Bitcoin network handshake. I realized it would be cool to try to implement it in Rust, more as a theoretical exercise than anything else.<\/p>\n
Since I enjoyed this topic, I got to work, and this little article is the result. The first thing to note is that the handshake is a fundamental process in communication between distributed systems, including computer networks and communication protocols like Bitcoin. The handshake has its roots in the early days of computing and telecommunications. In the first computer networks and telecommunications systems, the handshake was a fundamental mechanism for establishing connections between devices. As computer networks evolved, the handshake became a standard component of many communication protocols. For example, the TCP (Transmission Control Protocol), developed in the 1970s, uses a three-way handshake process to establish reliable connections between devices on a network. With the advent of the Internet, the handshake became even more important in security protocols (like SSL\/TLS (Secure Sockets Layer \/ Transport Layer Security).<\/p>\n
Here are some key reasons why the handshake is crucial (the following is gathered from ChatGPT, let’s not kid ourselves by saying that everything published is 100% original, although reviewed and corrected, as it sometimes makes significant errors):<\/p>\n
Now, the million-dollar question: how many steps does the Bitcoin handshake protocol have? To answer this, we would need to consult the Bitcoin Developer Reference and some of the BIPs dedicated to this topic, including BIP14 (versioning protocol) and BIP37 (bloom filtering for lightweight clients). It’s a lot of work to read them and gather all the documentation, so from my point of view, I’ve summarized all this into a nine-step process, with its implementation in Rust.<\/p>\n
You will see that the source code I share on Github has several approaches (5 plus the final one), and the README.md<\/a> only covers the latest implementation (main.rs<\/a>). The most important crates we will use are the following: Here’s a summary of each:<\/p>\n If you want to perform the handshake, you need to connect with a peer, sometimes if you have a trustful peer, you can use its IP, but is a better approach to use the Bitcoin seed DNS to retrieve this information. The code utilizes the trust-dns-resolver crate to perform DNS resolution. Here’s an explanation of how this process works:<\/p>\n The first step is to read the configuration file config.toml, which contains the DNS seeds. These seeds are domain names that resolve to the IP addresses of Bitcoin nodes.<\/p>\n In this example, the config.toml file might look like this:<\/p>\n Once the configuration is read, a seed is randomly chosen from the list of seeds provided.<\/p>\n The selected seed (a DNS name) is then resolved to a list of IP addresses using the trust-dns-resolver crate. This involves querying the DNS server for A (IPv4) or AAAA (IPv6) records associated with the seed domain name.<\/p>\n Here\u2019s what happens in detail:<\/p>\n With the list of resolved IP addresses, the next step is to attempt to connect to these peers. This involves trying to establish a TCP connection with each IP address.<\/p>\n OK. now we can connect with a peer and begin our handshake \ud83d\ude42<\/p>\n The first step is to create a version message that contains information about the node, such as the protocol version, services supported, timestamp, receiver’s address, sender’s address, nonce, user agent, start height, and relay flag.<\/p>\n Once the version message is created, it is sent to the peer.<\/p>\n The node waits to receive a version message from the peer. A timeout is used to ensure the process does not hang indefinitely.<\/p>\n After receiving the version message, the node checks if the peer’s protocol version is compatible.<\/p>\n The node also checks if the services supported by the peer are compatible.<\/p>\n If all checks are passed, the node sends a verack message to acknowledge the version message.<\/p>\n To avoid connecting to itself, the node verifies if the nonce in the version message indicates a loopback connection.<\/p>\n If all checks are passed, the node sends a verack message to acknowledge the version message.<\/p>\n The node waits to receive a verack message from the peer, confirming that the peer acknowledges the version message.<\/p>\n If the node successfully receives and decodes the verack message, the handshake is considered complete, and the node can now communicate with the peer.<\/p>\n This function decodes the version message received from the peer, extracting various fields such as version, services, timestamp, addresses, nonce, user agent, start height, and relay flag.<\/p>\n The verack message is simple and doesn’t need much decoding. The function just prints out the received message.<\/p>\n\n
DNS Process to Select a Bitcoin Peer<\/h3>\n
1. Reading the Configuration<\/h3>\n
#[derive(Deserialize)]\r\nstruct Config {\r\n nodes: Nodes,\r\n}\r\n\r\n#[derive(Deserialize)]\r\nstruct Nodes {\r\n seeds: Vec<String>,\r\n}\r\n\r\nfn read_config() -> Config {\r\n let config_content = fs::read_to_string(\"config.toml\").expect(\"Failed to read config file\");\r\n toml::from_str(&config_content).expect(\"Failed to parse config file\")\r\n}<\/pre>\n[nodes]\r\nseeds = [\"seed.bitcoin.sipa.be\", \"dnsseed.bluematt.me\"]<\/pre>\n
2. Selecting a Seed<\/h3>\n
let config = read_config();\r\nlet seeds = &config.nodes.seeds;\r\n\r\nlet seed = seeds.choose(&mut rand::thread_rng()).expect(\"No seed nodes found\");<\/pre>\n
3. Resolving the Seed to IP Addresses<\/h3>\n
use trust_dns_resolver::config::*;\r\nuse trust_dns_resolver::AsyncResolver;\r\n\r\nasync fn resolve_bitcoin_peers(seed: &str) -> Vec<SocketAddr> {\r\n let resolver = AsyncResolver::tokio(ResolverConfig::default(), ResolverOpts::default()).unwrap();\r\n let response = resolver.lookup_ip(seed).await.unwrap();\r\n let mut peers = Vec::new();\r\n for ip in response.iter() {\r\n let socket_addr = SocketAddr::new(ip, 8333); \/\/ 8333 is the default port for Bitcoin\r\n peers.push(socket_addr);\r\n }\r\n peers\r\n}<\/pre>\n\n
4. Connecting to a Peer<\/h3>\n
use tokio::net::TcpStream;\r\nuse tokio::time::timeout;\r\nuse std::time::Duration;\r\n\r\nasync fn connect_to_peer(peer: SocketAddr) -> Result<TcpStream, ()> {\r\n match timeout(Duration::from_secs(5), TcpStream::connect(peer)).await {\r\n Ok(Ok(stream)) => {\r\n println!(\"Connected to peer: {}\", peer);\r\n Ok(stream)\r\n }\r\n _ => {\r\n println!(\"Failed to connect to peer: {}\", peer);\r\n Err(())\r\n }\r\n }\r\n}<\/pre>\nMy 9 steps for the handshake<\/h2>\n
1. Create the version Message<\/h3>\n
fn create_version_message() -> Vec<u8> {\r\n let mut buf = Vec::new();\r\n\r\n \/\/ Version\r\n WriteBytesExt::write_u32::<LittleEndian>(&mut buf, 70015).unwrap();\r\n\r\n \/\/ Services\r\n WriteBytesExt::write_u64::<LittleEndian>(&mut buf, 0).unwrap();\r\n\r\n \/\/ Timestamp\r\n WriteBytesExt::write_u64::<LittleEndian>(&mut buf, Utc::now().timestamp() as u64).unwrap();\r\n\r\n \/\/ Addr_recv (Receiver's address)\r\n WriteBytesExt::write_u64::<LittleEndian>(&mut buf, 0).unwrap();\r\n let ip = Ipv4Addr::new(0, 0, 0, 0).octets();\r\n buf.extend_from_slice(&[0; 10]);\r\n buf.extend_from_slice(&ip);\r\n WriteBytesExt::write_u16::<BigEndian>(&mut buf, 8333).unwrap();\r\n\r\n \/\/ Addr_from (Sender's address)\r\n WriteBytesExt::write_u64::<LittleEndian>(&mut buf, 0).unwrap();\r\n let ip = Ipv4Addr::new(0, 0, 0, 0).octets();\r\n buf.extend_from_slice(&[0; 10]);\r\n buf.extend_from_slice(&ip);\r\n WriteBytesExt::write_u16::<BigEndian>(&mut buf, 8333).unwrap();\r\n\r\n \/\/ Nonce\r\n WriteBytesExt::write_u64::<LittleEndian>(&mut buf, rand::random()).unwrap();\r\n\r\n \/\/ User Agent\r\n let user_agent = \"\/Satoshi:0.7.2\/\".as_bytes();\r\n WriteBytesExt::write_u8(&mut buf, user_agent.len() as u8).unwrap();\r\n buf.extend_from_slice(user_agent);\r\n\r\n \/\/ Start Height\r\n WriteBytesExt::write_u32::<LittleEndian>(&mut buf, 0).unwrap();\r\n\r\n \/\/ Relay\r\n WriteBytesExt::write_u8(&mut buf, 1).unwrap();\r\n\r\n buf\r\n}<\/pre>\n2. Send the version Message<\/h3>\n
stream.write_all(&version_message).await.unwrap();<\/pre>\n
3. Receive the version Message from the Peer<\/h3>\n
let mut buf = [0; 1024];\r\nmatch timeout(Duration::from_secs(10), stream.read(&mut buf)).await {\r\n Ok(Ok(n)) if n > 0 => {\r\n let peer_version_message = &buf[..n];\r\n decode_version_message(peer_version_message);<\/pre>\n4. Verify Protocol Version Compatibility<\/h3>\n
if !is_version_compatible(peer_version_message) {\r\n return Err(());\r\n}<\/pre>\n5. Verify Supported Services<\/h3>\n
if !are_services_compatible(peer_version_message) {\r\n return Err(());\r\n}\r\n7. Send the verack Message<\/pre>\n6. Check for Loopback Connection<\/h3>\n
if is_loopback_connection(peer_version_message) {\r\n return Err(());\r\n}<\/pre>\n7. Send the verack Message<\/h3>\n
let verack_message = create_verack_message();\r\nstream.write_all(&verack_message).await.unwrap();<\/pre>\n
8. Receive the verack Message from the Peer<\/h3>\n
match timeout(Duration::from_secs(5), stream.read(&mut buf)).await {\r\n Ok(Ok(n)) if n > 0 => {\r\n let peer_verack_message = &buf[..n];\r\n decode_verack_message(peer_verack_message);\r\n Ok(())\r\n }\r\n _ => {\r\n Err(())\r\n }\r\n}<\/pre>\n9. Handshake Completed<\/h3>\n
println!(\"Handshake completed successfully\");<\/pre>\n
Detailed Explanation of Helper Functions<\/h3>\n
decode_version_message<\/h3>\n
fn decode_version_message(message: &[u8]) {\r\n let mut rdr = Cursor::new(message);\r\n\r\n let version = ReadBytesExt::read_u32::<LittleEndian>(&mut rdr).unwrap();\r\n let services = ReadBytesExt::read_u64::<LittleEndian>(&mut rdr).unwrap();\r\n let timestamp = ReadBytesExt::read_u64::<LittleEndian>(&mut rdr).unwrap();\r\n\r\n \/\/ Receiver's address\r\n let addr_recv_services = ReadBytesExt::read_u64::<LittleEndian>(&mut rdr).unwrap();\r\n let addr_recv_ip = {\r\n let mut buf = [0u8; 16];\r\n Read::read_exact(&mut rdr, &mut buf).unwrap();\r\n buf\r\n };\r\n let addr_recv_port = ReadBytesExt::read_u16::<BigEndian>(&mut rdr).unwrap();\r\n\r\n \/\/ Sender's address\r\n let addr_from_services = ReadBytesExt::read_u64::<LittleEndian>(&mut rdr).unwrap();\r\n let addr_from_ip = {\r\n let mut buf = [0u8; 16];\r\n Read::read_exact(&mut rdr, &mut buf).unwrap();\r\n buf\r\n };\r\n let addr_from_port = ReadBytesExt::read_u16::<BigEndian>(&mut rdr).unwrap();\r\n\r\n let nonce = ReadBytesExt::read_u64::<LittleEndian>(&mut rdr).unwrap();\r\n\r\n \/\/ User agent (variable length)\r\n let user_agent_length = ReadBytesExt::read_u8(&mut rdr).unwrap();\r\n let mut user_agent = vec![0u8; user_agent_length as usize];\r\n Read::read_exact(&mut rdr, &mut user_agent).unwrap();\r\n\r\n let start_height = ReadBytesExt::read_u32::<LittleEndian>(&mut rdr).unwrap();\r\n let relay = ReadBytesExt::read_u8(&mut rdr).unwrap_or(1);\r\n\r\n println!(\"Decoded version message:\");\r\n println!(\"Version: {}\", version);\r\n println!(\"Services: {}\", services);\r\n println!(\"Timestamp: {}\", timestamp);\r\n println!(\r\n \"Receiver Address: {}:{} with services {}\",\r\n addr_recv_ip.iter().map(|b| b.to_string()).collect::<Vec<_>>().join(\".\"),\r\n addr_recv_port,\r\n addr_recv_services\r\n );\r\n println!(\r\n \"Sender Address: {}:{} with services {}\",\r\n addr_from_ip.iter().map(|b| b.to_string()).collect::<Vec<_>>().join(\".\"),\r\n addr_from_port,\r\n addr_from_services\r\n );\r\n println!(\"Nonce: {}\", nonce);\r\n println!(\"User Agent: {}\", String::from_utf8(user_agent).unwrap_or_default());\r\n println!(\"Start Height: {}\", start_height);\r\n println!(\"Relay: {}\", relay);\r\n}<\/pre>\ndecode_verack_message<\/h3>\n
fn decode_verack_message(message: &[u8]) {\r\n println!(\"Decoded verack message: {:?}\", message);\r\n}<\/pre>\nGitHub Repository<\/h2>\n