README.md

@@ -22,7 +22,7 @@ Feel welcome to join chan "bitmessage", BM-2cWy7cvHoq3f1rYMerRJp8PT653jjSuEdY
 References
 ----------
 * [Project Website](https://bitmessage.org)
-* [Protocol Specification](https://bitmessage.org/wiki/Protocol_specification)
+* [Protocol Specification](https://pybitmessage.rtfd.io/en/v0.6/protocol.html)
 * [Whitepaper](https://bitmessage.org/bitmessage.pdf)
 * [Installation](https://bitmessage.org/wiki/Compiling_instructions)
 * [Discuss on Reddit](https://www.reddit.com/r/bitmessage)

docs/encryption.rst

@@ -49,7 +49,7 @@ Encryption
     key_e as encryption key and the padded input text as payload. Call the
     output cipher text.
  9. Calculate a 32 byte MAC with HMACSHA256, using key_m as salt and
-    IV + R + cipher text as data. Call the output MAC.
+    IV + R [#f2]_ + cipher text as data. Call the output MAC.
 
 The resulting data is: IV + R + cipher text + MAC
 
@@ -129,11 +129,12 @@ Partial Example
 
        ::
 
-	  04
+	  02 ca 00 20
 	  02 93 21 3d  cf 13 88 b6
 	  1c 2a e5 cf  80 fe e6 ff
 	  ff c0 49 a2  f9 fe 73 65
 	  fe 38 67 81  3c a8 12 92
+	  00 20
 	  df 94 68 6c  6a fb 56 5a
 	  c6 14 9b 15  3d 61 b3 b2
 	  87 ee 2c 7f  99 7c 14 23
@@ -252,3 +253,5 @@ Partial Example
 
 .. [#f1] The pyelliptic implementation used in PyBitmessage takes unpadded data,
 	 see :obj:`.pyelliptic.Cipher.ciphering`.
+.. [#f2] The pyelliptic encodes the pubkey with curve and length,
+	 see :obj:`.pyelliptic.ECC.get_pubkey`

docs/protocol.rst

@@ -92,7 +92,7 @@ Variable length integer
 
 Integer can be encoded depending on the represented value to save space.
 Variable length integers always precede an array/vector of a type of data that
-may vary in length. Varints MUST use the minimum possible number of bytes to
+may vary in length. Varints **must** use the minimum possible number of bytes to
 encode a value. For example, the value 6 can be encoded with one byte therefore
 a varint that uses three bytes to encode the value 6 is malformed and the
 decoding task must be aborted.
@@ -480,12 +480,13 @@ only a :ref:`message header <Message structure>` 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
+If both sides announce that they support SSL, they **must** perform an SSL
-immediately after they both send and receive verack. During this SSL handshake,
+handshake immediately after they both send and receive verack. During this SSL
-the TCP client acts as a SSL client, and the TCP server acts as a SSL server.
+handshake, the TCP client acts as an SSL client, and the TCP server acts as an
-The current implementation (v0.5.4 or later) requires the AECDH-AES256-SHA
+SSL server. The current implementation (v0.5.4 or later) requires the
-cipher over TLSv1 protocol, and prefers the secp256k1 curve (but other curves
+AECDH-AES256-SHA cipher over TLSv1 protocol, and prefers the secp256k1 curve
-may be accepted, depending on the version of python and OpenSSL used).
+(but other curves may be accepted, depending on the version of python and
+OpenSSL used).
 
 addr
 ^^^^
@@ -517,7 +518,6 @@ Allows a node to advertise its knowledge of one or more objects. Payload
 | 32x?       | inventory   | inv_vect[] | Inventory vectors           |
 +------------+-------------+------------+-----------------------------+
 
-
 getdata
 ^^^^^^^
 
@@ -534,6 +534,50 @@ Payload (maximum payload length: 50000 entries):
 | 32x?       | inventory   | inv_vect[] | Inventory vectors           |
 +------------+-------------+------------+-----------------------------+
 
+error
+^^^^^
+.. note:: New in version 3
+
+This message may be silently ignored (and therefor handled like any other
+"unknown" message).
+
+The message is intended to inform the other node about protocol errors and
+can be used for debugging and improving code.
+
+.. list-table::
+   :header-rows: 1
+   :widths: auto
+
+   * - Field Size
+     - Description
+     - Data type
+     - Comments
+   * - 1+
+     - fatal
+     - |var_int|
+     - This qualifies the error. If set to 0, than its just a "warning".
+       You can expect, everything still worked fine. If set to 1, than
+       it's an error, so you may expect, something was going wrong
+       (e.g. an object got lost). If set to 2, it's a fatal error. The node
+       will drop the line for that error and maybe ban you for some time.
+   * - 1+
+     - ban time
+     - var_int
+     - If the error is fatal, you can specify the ban time in seconds, here.
+       You inform the other node, that you will not accept further connections
+       for this number of seconds. For non fatal errors this field has
+       no meaning and should be zero.
+   * - 1+
+     - inventory vector
+     - var_str
+     - If the error is related to an object, this Variable length string
+       contains the inventory vector of that object. If the error is not
+       related to an object, this string is empty.
+   * - 1+
+     - error text
+     - var_str
+     - A human readable string in English, which describes the error.
+
 
 object
 ^^^^^^
@@ -588,6 +632,19 @@ type, like 'msg', or 'broadcast'. To be a valid object, the
      - This field varies depending on the object type; see below.
 
 
+Unsupported messages
+^^^^^^^^^^^^^^^^^^^^
+
+If a node receives an unknown message it **must** silently ignore it. This is
+for further extensions of the protocol with other messages. Nodes that don't
+understand such a new message type shall be able to work correct with the
+message types they understand.
+
+Maybe some version 2 nodes did already implement it that way, but in version 3
+it is **part of the protocol specification**, that a node **must**
+silently ignore unsupported messages.
+
+
 Object types
 ------------
 

src/protocol.py

@@ -259,7 +259,7 @@ def isProofOfWorkSufficient(
         data, nonceTrialsPerByte=0, payloadLengthExtraBytes=0, recvTime=0):
     """
     Validate an object's Proof of Work using method described
-    `here <https://bitmessage.org/wiki/Proof_of_work>`_
+    :doc:`here </pow>`
 
     Arguments:
         int nonceTrialsPerByte (default: from `.defaults`)