Join and earn Bitcoin Cash for participation

On Bitcoin Messaging Terminology

0 67 boost
Avatar for phil.wilson
Written by   2
7 months ago

Stream-of-Consciousness for choosing codebase terminology to help structure the code for a node repository

Most networking applications lay out a code structure for making RESTful API requests and responses.

There's a huge difference between RESTful request/ response calls and Bitcoin node messaging

When making a REST call, you make a request and wait for either the response or a timeout

A synchronous call

Bitcoin messaging is more like Send-and-Don't-Wait

An Asynchronous call

So there isn't a direct correlation between a specific request and its response.

There are some messages which are paired, i.e. Version/ VerAck, Ping/ Pong.

Though every message is treated as a stream of outputting and inputting data.

You may send a Version message but don't wait for the VerAck response

You may send a Ping message but don't wait for the Pong response

You may never receive the corresponding VerAck or Pong message

In REST calls, a request is made by a client program to a server, requesting data.

The request may include what type of data is being requested

There is a header and parameters.

For GET requests the fields in the parameters are appended to the URL.

For POST requests the fields in the parameters are inside the body field

For Bitcoin messages, the Payload is similar to the Body of a POST call

The Bitcoin message header,

the Magic Number, Type, Length, Checksum,

are analogous to a REST Post header, though one which is of fixed length and fixed parameters.

REST headers can have custom fields.

In Bitcoin messaging, the header is purposefully rigid in its design

We cannot use the term Request for an outgoing Bitcoin message, as the node could be making either a Request to another node for data or sending a Response to another node from that nodes previous Request.

Using Write to and Read from the wire is not correct either

The functions could be doubled up.

So we'd have:

  • SendRequest

  • SendResponse

  • ReadRequest

  • ReadResponse

That is quite doable, as each node is connected either client=>server or server=>client

However that is only for the initial connection.

Sockets need a "server" to be listening on a port, and "clients" to connect to it

Bitcoin messaging goes both ways on that connection

You don't need both client=>server and server=>client to get two-way communication between nodes

If there's only the one connection between nodes, then it's not possible to know whether the next incoming message will be a response to one of our requests, or a request from that other node wanting our response to it.

This means dropping the Request/ Response terminology

This is when we pull out the thesaurus and attempt to find words which could be used in place of Request/Response for Bitcoin messaging


The words must be verbs, not nouns.

Doing words, action words.

You're requesting

You're waiting for a response

You're responding

From this we could use words similar to

Write, Read, Send, Receive, Get, Post, etc

"Dispatch" seems a reasonable choice for sending data out on the wire.

Maybe "Push" and "Pop" data ?

We're definitely pushing data to the other node.

Not really popping data back from it though.

Transmit, broadcast ?

What's really happening is that a server Vends data

and a client Consumes that data.

In a peer node network,

the sender is Vending data

the receiver is Consuming that data


  • Vend, Vending, Vendor, for writing/ sending

  • Consume, Consuming, Consumer, for reading/ receiving

Each node in a peer network is both a Vendor and Consumer of data.

$ 0.15
$ 0.10 from @Steve-Patterson
$ 0.05 from @unitedstatian
Avatar for phil.wilson
Written by   2
7 months ago
Enjoyed this article?  Earn Bitcoin Cash by sharing it! Explain
...and you will also help the author collect more tips.