From c7bf304c6d913d97ea642db70d8f64a96c67ffda Mon Sep 17 00:00:00 2001
From: Dmitri Bogomolov <4glitch@gmail.com>
Date: Sun, 31 Jan 2021 20:42:34 +0200
Subject: [PATCH] More headings

---
 docs/protocol.rst | 124 ++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 121 insertions(+), 3 deletions(-)

diff --git a/docs/protocol.rst b/docs/protocol.rst
index b96ff002..5a7045fb 100644
--- a/docs/protocol.rst
+++ b/docs/protocol.rst
@@ -74,8 +74,8 @@ All integers are encoded in big endian. (This is different from Bitcoin).
    * - ?
      - message_payload
      - uchar[]
-     - The actual data, a message or an object_. Not to be confused with
-       objectPayload.
+     - The actual data, a :ref:`message <msg-types>` or an object_.
+       Not to be confused with objectPayload.
 
 Known magic values:
 
@@ -168,7 +168,7 @@ addresses are not prefixed with a timestamp or stream in the version_ message.
    * - 8
      - services
      - uint64_t
-     - same service(s) listed in version
+     - same service(s) listed in version_
    * - 16
      - IPv6/4
      - char[16]
@@ -221,3 +221,121 @@ Bitmessage uses `ECIES <https://en.wikipedia.org/wiki/Integrated_Encryption_Sche
 | 32         | MAC         | uchar[]   | HMACSHA256 Message Authentication Code     |
 +------------+-------------+-----------+--------------------------------------------+
 
+Unencrypted Message Data
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+Message Encodings
+"""""""""""""""""
+
+Pubkey bitfield features
+""""""""""""""""""""""""
+
+
+.. _msg-types:
+
+Message types
+-------------
+
+Undefined messages received on the wire must be ignored.
+
+version
+^^^^^^^
+
+When a node creates an outgoing connection, it will immediately advertise its
+version. The remote node will respond with its version. No futher communication
+is possible until both peers have exchanged their version.
+
+
+verack
+^^^^^^
+
+The verack message is sent in reply to version. This message consists of only a
+message header with the command string "verack". The TCP timeout starts out at
+20 seconds; after verack messages are exchanged, the timeout is raised to
+10 minutes.
+
+If both sides announce that they support SSL, they MUST perform a SSL handshake
+immediately after they both send and receive verack. During this SSL handshake,
+the TCP client acts as a SSL client, and the TCP server acts as a SSL server.
+The current implementation (v0.5.4 or later) requires the AECDH-AES256-SHA
+cipher over TLSv1 protocol, and prefers the secp256k1 curve (but other curves
+may be accepted, depending on the version of python and OpenSSL used).
+
+addr
+^^^^
+
+Provide information on known nodes of the network. Non-advertised nodes should
+be forgotten after typically 3 hours
+
+inv
+^^^
+
+Allows a node to advertise its knowledge of one or more objects. Payload
+(maximum payload length: 50000 items):
+
+
+getdata
+^^^^^^^
+
+getdata is used in response to an inv message to retrieve the content of a
+specific object after filtering known elements.
+
+Payload (maximum payload length: 50000 entries):
+
+
+object
+^^^^^^
+
+An object is a message which is shared throughout a stream. It is the only
+message which propagates; all others are only between two nodes. Objects have a
+type, like 'msg', or 'broadcast'. To be a valid object, the Proof Of Work must
+be done. The maximum allowable length of an object (not to be confused with the
+objectPayload) is |2^18| bytes.
+
+.. |2^18| replace:: 2\ :sup:`18`\
+
+
+Object types
+------------
+
+Here are the payloads for various object types.
+
+getpubkey
+^^^^^^^^^
+
+When a node has the hash of a public key (from an address) but not the public
+key itself, it must send out a request for the public key.
+
+
+pubkey
+^^^^^^
+
+A version 2 pubkey. This is still in use and supported by current clients but
+new v2 addresses are not generated by clients.
+
+
+msg
+^^^
+
+Used for person-to-person messages. Note that msg objects won't contain a
+version in the object header until Sun, 16 Nov 2014 22:00:00 GMT.
+
+broadcast
+^^^^^^^^^
+
+Users who are subscribed to the sending address will see the message appear in
+their inbox. Broadcasts are version 4 or 5.
+
+Pubkey objects and v5 broadcast objects are encrypted the same way: The data
+encoded in the sender's Bitmessage address is hashed twice. The first 32 bytes
+of the resulting hash constitutes the "private" encryption key and the last
+32 bytes constitute a tag so that anyone listening can easily decide if this
+particular message is interesting. The sender calculates the public key from
+the private key and then encrypts the object with this public key. Thus anyone
+who knows the Bitmessage address of the sender of a broadcast or pubkey object
+can decrypt it.
+
+The version of broadcast objects was previously 2 or 3 but was changed to 4 or
+5 for protocol v3. Having a broadcast version of 5 indicates that a tag is used
+which, in turn, is used when the sender's address version is >=4.