Difference between revisions of "Protocol specification v3"

From Bitmessage Wiki
Jump to navigation Jump to search
m (Variable length integer encoding constraint)
m (Formatting, spelling corrections)
Line 4: Line 4:
  
 
== Introduction ==
 
== Introduction ==
This is a DRAFT for the protocol version 3. It describes the changes in protocol version 3 versus version 2. Things which are unchanged from version 2 are not described in detail. So you should use  [https://bitmessage.org/wiki/Protocol_specification this] as a reference for all formates which are not mentioned in this description.
+
This is a DRAFT for the protocol version 3. It describes the changes in protocol version 3 versus version 2. Things which are unchanged from version 2 are not described in detail. So you should use  [https://bitmessage.org/wiki/Protocol_specification this] as a reference for all formats which are not mentioned in this description.
  
== new features in version 3 ==
+
== New features in version 3 ==
  
 
Here are the new features of the version 3 of Bitmessage protocol in keywords:
 
Here are the new features of the version 3 of Bitmessage protocol in keywords:
Line 27: Line 27:
 
== Message types ==
 
== Message types ==
  
Most message types are unchanged from version 2 to version 3. Only the four "objecttype" messages are not valid any more. They are summerized into one single message.
+
Most message types are unchanged from version 2 to version 3. Only the four "objecttype" messages are not valid any more. They are summarized into one single message.
  
 
=== version ===
 
=== version ===
  
The version message is identically to protocol version 2. you can lookup details [https://bitmessage.org/wiki/Protocol_specification#version here]
+
The version message is identical to protocol version 2. you can look up details [https://bitmessage.org/wiki/Protocol_specification#version here]
  
 
=== verack ===
 
=== verack ===
  
The verack message is identically to protocol version 2. you can lookup details [https://bitmessage.org/wiki/Protocol_specification#verack here]
+
The verack message is identical to protocol version 2. you can look up details [https://bitmessage.org/wiki/Protocol_specification#verack here]
  
 
=== addr ===
 
=== addr ===
  
The addr message is identically to protocol version 2. you can lookup details [https://bitmessage.org/wiki/Protocol_specification#addr here]
+
The addr message is identical to protocol version 2. you can look up details [https://bitmessage.org/wiki/Protocol_specification#addr here]
  
 
=== inv ===
 
=== inv ===
  
The inv message is identically to protocol version 2. you can lookup details [https://bitmessage.org/wiki/Protocol_specification#inv here]
+
The inv message is identical to protocol version 2. you can look up details [https://bitmessage.org/wiki/Protocol_specification#inv here]
  
 
=== getdata ===
 
=== getdata ===
  
The getdata message is identically to protocol version 2. you can lookup details [https://bitmessage.org/wiki/Protocol_specification#getdata here]
+
The getdata message is identical to protocol version 2. you can look up details [https://bitmessage.org/wiki/Protocol_specification#getdata here]
  
=== unsupported messages ===
+
=== Unsupported messages ===
 
If a node receives an unknown message it <u>must</u> 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.
 
If a node receives an unknown message it <u>must</u> 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.
  
Line 56: Line 56:
 
== Object type ==
 
== Object type ==
  
The four former object types "getpubkey", "pubkey", "msg" and "broadcast" are summarizes into a single Message type "object". The four Messages as they did exist in version 2 protocol are not valid any more.
+
The four former object types "getpubkey", "pubkey", "msg" and "broadcast" are summarized into a single Message type "object". The four Messages as they did exist in version 2 protocol are not valid any more.
  
 
Objects are shared throughout a stream.  A client should advertise objects until their end of life time is reached. To be a valid object, the [[Proof of work|Proof Of Work]] has to be done.
 
Objects are shared throughout a stream.  A client should advertise objects until their end of life time is reached. To be a valid object, the [[Proof of work|Proof Of Work]] has to be done.
Line 81: Line 81:
  
  
=== Do a POW ===
+
== Proof of Work ==
  
 
Generally the POW is done exactly like in [[Proof of work|version 2]]
 
Generally the POW is done exactly like in [[Proof of work|version 2]]
  
The "target" (the difficulty of the POW) is defined a little bit lower (more difficult) in version 3. This is, because practice did show, it is to easy to float the network with data.
+
The "target" (the difficulty of the POW) is defined a little bit lower (more difficult) in version 3. This is, because practice did show, it is to easy to flood the network with data.
In addition to that it is possible in version 3 to lower the time to life of a message (for example when doing a life chat) and getting an easier POW for that.
+
In addition to that it is possible in version 3 to lower the time to live of a message (for example when doing a live chat) and getting an easier POW for that.
  
Setting the live time e.g. to 360 seconds (6 Minutes), which is totally suffient for a life chat, the POW will be 10 times easier than in version 2.
+
Setting the live time e.g. to 360 seconds (6 Minutes), which is totally sufficient for a live chat, the POW will be 10 times easier than in version 2.
  
The "time to live" is the difference between the current time and the "end of life" time. For POW check and generation the "time to live" value is considered to be at least 300 seconds, even if the object has to life less than 300 seconds.
+
The "time to live" is the difference between the current time and the "end of life" time. For POW check and generation the "time to live" value is considered to be at least 300 seconds, even if the object has to live less than 300 seconds.
  
  
Line 103: Line 103:
 
             loadvalue * averageProofOfWorkNonceTrialsPerByte
 
             loadvalue * averageProofOfWorkNonceTrialsPerByte
  
=== Maximum object size ===
+
== Maximum object size ==
  
 
In version 2 the maximum object size was defined to be 170 MBytes. This object size is totally unrealistic for a normal use (POW), but is perfectly for a network attack. It will be to big to handle for clients with low bandwidth.
 
In version 2 the maximum object size was defined to be 170 MBytes. This object size is totally unrealistic for a normal use (POW), but is perfectly for a network attack. It will be to big to handle for clients with low bandwidth.
 
Currently an average bitmessage "msg" object has the size of 2 kBytes.
 
Currently an average bitmessage "msg" object has the size of 2 kBytes.
 
So version 3 limits the objects to a maximum size of 64 kBytes.
 
So version 3 limits the objects to a maximum size of 64 kBytes.

Revision as of 10:56, 18 July 2014

Introduction

This is a DRAFT for the protocol version 3. It describes the changes in protocol version 3 versus version 2. Things which are unchanged from version 2 are not described in detail. So you should use this as a reference for all formats which are not mentioned in this description.

New features in version 3

Here are the new features of the version 3 of Bitmessage protocol in keywords:

  • object type is now coded inside the message
  • objects may have a variable time to live
  • The POW is more difficult but can be easier if you lower the time to live
  • The protocol is tolerant for further message extension
  • The protocol is tolerant for further object extension
  • A lower maximum object size


Common structures

Variable length integer

The shortest possible encoding MUST be used. In version 2 the decimal value 10 could be encoded as 0x0A, 0xFD000A, 0xFE0000000A, or 0xFF000000000000000A. In version 3 only the shortest representation, 0x0A, is allowed. The 9-byte form is no longer useful and SHOULD NOT be used.


Message types

Most message types are unchanged from version 2 to version 3. Only the four "objecttype" messages are not valid any more. They are summarized into one single message.

version

The version message is identical to protocol version 2. you can look up details here

verack

The verack message is identical to protocol version 2. you can look up details here

addr

The addr message is identical to protocol version 2. you can look up details here

inv

The inv message is identical to protocol version 2. you can look up details here

getdata

The getdata message is identical to protocol version 2. you can look up details here

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 type

The four former object types "getpubkey", "pubkey", "msg" and "broadcast" are summarized into a single Message type "object". The four Messages as they did exist in version 2 protocol are not valid any more.

Objects are shared throughout a stream. A client should advertise objects until their end of life time is reached. To be a valid object, the Proof Of Work has to be done.

Field Size Description Data type Comments
8 POW nonce uint64_t

Random nonce used for the Proof Of Work

8 time uint64_t

The "end of life" time of this object (be aware, in version 2 of the protocol this was the generation time). Objects shall be broadcast until its end of life time has been reached. The node shall store the inventory vector of that object for at least another hour to avoid reloading it from another node with a small time delay. The maximum value for the "time to life" of an object is 28 days. so the "end of life time" is 28 days in the future at maximum.

4 object type uint32_t

This field specifies the content of the object. Valid values are (at the moment) 0-"getpubkey", 1-"pubkey", 2-"msg", 3-"broadcast". all other values are reserved. Nodes shall transport objects with unknown types, too. This will make further protocol changes more easy.

? payload uchar[]

This field varies depending on the object type. For a detailed description of their content look here


Proof of Work

Generally the POW is done exactly like in version 2

The "target" (the difficulty of the POW) is defined a little bit lower (more difficult) in version 3. This is, because practice did show, it is to easy to flood the network with data. In addition to that it is possible in version 3 to lower the time to live of a message (for example when doing a live chat) and getting an easier POW for that.

Setting the live time e.g. to 360 seconds (6 Minutes), which is totally sufficient for a live chat, the POW will be 10 times easier than in version 2.

The "time to live" is the difference between the current time and the "end of life" time. For POW check and generation the "time to live" value is considered to be at least 300 seconds, even if the object has to live less than 300 seconds.


   payload = EndOfLifeTime + ObjectType + payload
               PayloadLenInBytes * TimeToLiveInSeconds
   loadvalue = ---------------------------------------  +  payloadLengthExtraBytes + 8
                               3600
                               2^64 
   target = ------------------------------------------------
            loadvalue * averageProofOfWorkNonceTrialsPerByte

Maximum object size

In version 2 the maximum object size was defined to be 170 MBytes. This object size is totally unrealistic for a normal use (POW), but is perfectly for a network attack. It will be to big to handle for clients with low bandwidth. Currently an average bitmessage "msg" object has the size of 2 kBytes. So version 3 limits the objects to a maximum size of 64 kBytes.