Bitmessage Wiki - User contributions [en]

Main Page

2018-02-17T03:50:58Z

Atheros: Updated red text and added link to binary releases

__NOTOC__
{{Infobox
|name=Bitmessage
|downloadsite=https://github.com/Bitmessage/PyBitmessage/releases/download/v0.6.1/Bitmessage-0.6.1.exe
|release caption=Previous Version (Beta)
|latest release date=Aug 21, 2016
|version=0.6.1
}}
A remote code execution vulnerability has been spotted in use against some users running PyBitmessage v0.6.2. The cause was identified and a fix has been added and released as 0.6.3.2 [https://github.com/Bitmessage/PyBitmessage/releases/ here]. If you run PyBitmessage via code, we highly recommend that you upgrade to 0.6.3.2. Alternatively you may downgrade to 0.6.1 which is unaffected. .

Bitmessage developer Peter Šurda's Bitmessage addresses are to be considered compromised.

Bitmessage is a P2P communications [[Protocol specification|protocol]] used to send encrypted messages to another person or to many subscribers. It is decentralized and trustless, meaning that you need-not inherently trust any entities like root certificate authorities. It uses strong authentication which means that the sender of a message cannot be spoofed, and it aims to hide "non-content" data, like the sender and receiver of messages, from passive eavesdroppers like those running warrantless wiretapping programs. If Bitmessage is completely new to you, you may wish to start by reading the [https://bitmessage.org/bitmessage.pdf whitepaper].

=== Download ===
An open source client is available for free under the very liberal [http://opensource.org/licenses/mit-license.php MIT license]. For screenshots and a description of the client, see this CryptoJunky article: [http://cryptojunky.com/blog/2013/03/09/setting-up-and-using-bitmessage-an-encrypted-communications-platform-based-on-bitcoin/ "Setting Up And Using Bitmessage"].

[[File:windows_icon.png|link=https://github.com/Bitmessage/PyBitmessage/releases/download/v0.6.1/Bitmessage-0.6.1.exe]] [https://github.com/Bitmessage/PyBitmessage/releases/download/v0.6.1/Bitmessage-0.6.1.exe Download for Windows (32bit)] [https://github.com/Bitmessage/PyBitmessage/releases/download/v0.6.1/Bitmessage-0.6.1_64.exe (64bit)]

[[File:apple_icon.png|link=https://github.com/Bitmessage/PyBitmessage/releases/download/v0.6.1/bitmessage-v0.6.1.dmg]] [https://github.com/Bitmessage/PyBitmessage/releases/download/v0.6.1/bitmessage-v0.6.1.dmg Download for OS X]

[[File:tux.png|link=Compiling_instructions]] [[Compiling instructions|Run the source code]]

=== Source code ===
You may view the Python [https://github.com/Bitmessage/PyBitmessage source code on Github]. Bitmessage requires PyQt and OpenSSL. Step-by-step instructions on how to run the source code on Linux, Windows, or OSX is [[Compiling instructions|available here]].

=== Contribute ===
Please follow the [[Contribute|contribution guidelines]] when contributing code or translations.

=== Security audit needed ===
Bitmessage is in need of an independent audit to verify its security. If you are a researcher capable of reviewing the source code, please [https://bitmessage.org/misc/emailaddress.png email] the lead developer. You will be helping to create a great privacy option for people everywhere!

=== Forum ===
* Visit or subscribe to the [https://pay.reddit.com/r/bitmessage Bitmessage subreddit].
* A community-based forum for questions, feedback, and discussion is also available at [https://bitmessage.org/forum Bitmessage.org/forum].

Main Page

2018-02-13T23:55:11Z

Atheros: move text to top and update version number

__NOTOC__
{{Infobox
|name=Bitmessage
|downloadsite=https://github.com/Bitmessage/PyBitmessage/releases/download/v0.6.1/Bitmessage-0.6.1.exe
|release caption=Previous Version (Beta)
|latest release date=Aug 21, 2016
|version=0.6.1
}}
A remote code execution vulnerability has been spotted in use against some users running PyBitmessage v0.6.2. The cause was identified and a fix has been added and released as 0.6.3.2. If you run PyBitmessage via code, we highly recommend that you upgrade to 0.6.3.2. Alternatively you may downgrade to 0.6.1 which is unaffected. We will release binary files for Windows and macOS tomorrow (2018-02-14). In the mean time, users who use binaries should downgrade to 0.6.1 using the links below.

Bitmessage developer Peter Šurda's Bitmessage addresses are to be considered compromised.

We greatly apologize for the issue and we hope to release more information as it becomes available.

Bitmessage is a P2P communications [[Protocol specification|protocol]] used to send encrypted messages to another person or to many subscribers. It is decentralized and trustless, meaning that you need-not inherently trust any entities like root certificate authorities. It uses strong authentication which means that the sender of a message cannot be spoofed, and it aims to hide "non-content" data, like the sender and receiver of messages, from passive eavesdroppers like those running warrantless wiretapping programs. If Bitmessage is completely new to you, you may wish to start by reading the [https://bitmessage.org/bitmessage.pdf whitepaper].

=== Download ===
An open source client is available for free under the very liberal [http://opensource.org/licenses/mit-license.php MIT license]. For screenshots and a description of the client, see this CryptoJunky article: [http://cryptojunky.com/blog/2013/03/09/setting-up-and-using-bitmessage-an-encrypted-communications-platform-based-on-bitcoin/ "Setting Up And Using Bitmessage"].

[[File:windows_icon.png|link=https://github.com/Bitmessage/PyBitmessage/releases/download/v0.6.1/Bitmessage-0.6.1.exe]] [https://github.com/Bitmessage/PyBitmessage/releases/download/v0.6.1/Bitmessage-0.6.1.exe Download for Windows (32bit)] [https://github.com/Bitmessage/PyBitmessage/releases/download/v0.6.1/Bitmessage-0.6.1_64.exe (64bit)]

[[File:apple_icon.png|link=https://github.com/Bitmessage/PyBitmessage/releases/download/v0.6.1/bitmessage-v0.6.1.dmg]] [https://github.com/Bitmessage/PyBitmessage/releases/download/v0.6.1/bitmessage-v0.6.1.dmg Download for OS X]

[[File:tux.png|link=Compiling_instructions]] [[Compiling instructions|Run the source code]]

=== Source code ===
You may view the Python [https://github.com/Bitmessage/PyBitmessage source code on Github]. Bitmessage requires PyQt and OpenSSL. Step-by-step instructions on how to run the source code on Linux, Windows, or OSX is [[Compiling instructions|available here]].

=== Contribute ===
Please follow the [[Contribute|contribution guidelines]] when contributing code or translations.

=== Security audit needed ===
Bitmessage is in need of an independent audit to verify its security. If you are a researcher capable of reviewing the source code, please [https://bitmessage.org/misc/emailaddress.png email] the lead developer. You will be helping to create a great privacy option for people everywhere!

=== Forum ===
* Visit or subscribe to the [https://pay.reddit.com/r/bitmessage Bitmessage subreddit].
* A community-based forum for questions, feedback, and discussion is also available at [https://bitmessage.org/forum Bitmessage.org/forum].

Main Page

2018-02-13T22:53:08Z

Atheros: Probably shouldn't imply that OSX is invulnerable without proof.

__NOTOC__
{{Infobox
|name=Bitmessage
|downloadsite=https://github.com/Bitmessage/PyBitmessage/releases/download/v0.6.1/Bitmessage-0.6.1.exe
|release caption=Previous Version (Beta)
|latest release date=Aug 21, 2016
|version=0.6.1
}}
Bitmessage is a P2P communications [[Protocol specification|protocol]] used to send encrypted messages to another person or to many subscribers. It is decentralized and trustless, meaning that you need-not inherently trust any entities like root certificate authorities. It uses strong authentication which means that the sender of a message cannot be spoofed, and it aims to hide "non-content" data, like the sender and receiver of messages, from passive eavesdroppers like those running warrantless wiretapping programs. If Bitmessage is completely new to you, you may wish to start by reading the [https://bitmessage.org/bitmessage.pdf whitepaper].

=== Download ===
An open source client is available for free under the very liberal [http://opensource.org/licenses/mit-license.php MIT license]. For screenshots and a description of the client, see this CryptoJunky article: [http://cryptojunky.com/blog/2013/03/09/setting-up-and-using-bitmessage-an-encrypted-communications-platform-based-on-bitcoin/ "Setting Up And Using Bitmessage"].

A remote code execution vulnerability has been spotted in use against some users running PyBitmessage v0.6.2. The cause was identified and a temporary fix has been added and released as 0.6.3. If you run PyBitmessage via code, we highly recommend that you upgrade to 0.6.3. Alternatively you may downgrade to 0.6.1 which is unaffected. We will release binary files for Windows and macOS tomorrow (2018-02-14). In the mean time, users who use binaries should downgrade to 0.6.1 using the links below.

Bitmessage developer Peter Šurda's Bitmessage addresses are to be considered compromised.

We greatly apologize for the issue and we hope to release more information as it becomes available.

[[File:windows_icon.png|link=https://github.com/Bitmessage/PyBitmessage/releases/download/v0.6.1/Bitmessage-0.6.1.exe]] [https://github.com/Bitmessage/PyBitmessage/releases/download/v0.6.1/Bitmessage-0.6.1.exe Download for Windows (32bit)] [https://github.com/Bitmessage/PyBitmessage/releases/download/v0.6.1/Bitmessage-0.6.1_64.exe (64bit)]

[[File:apple_icon.png|link=https://github.com/Bitmessage/PyBitmessage/releases/download/v0.6.1/bitmessage-v0.6.1.dmg]] [https://github.com/Bitmessage/PyBitmessage/releases/download/v0.6.1/bitmessage-v0.6.1.dmg Download for OS X]

[[File:tux.png|link=Compiling_instructions]] [[Compiling instructions|Run the source code]]

=== Source code ===
You may view the Python [https://github.com/Bitmessage/PyBitmessage source code on Github]. Bitmessage requires PyQt and OpenSSL. Step-by-step instructions on how to run the source code on Linux, Windows, or OSX is [[Compiling instructions|available here]].

=== Contribute ===
Please follow the [[Contribute|contribution guidelines]] when contributing code or translations.

=== Security audit needed ===
Bitmessage is in need of an independent audit to verify its security. If you are a researcher capable of reviewing the source code, please [https://bitmessage.org/misc/emailaddress.png email] the lead developer. You will be helping to create a great privacy option for people everywhere!

=== Forum ===
* Visit or subscribe to the [https://pay.reddit.com/r/bitmessage Bitmessage subreddit].
* A community-based forum for questions, feedback, and discussion is also available at [https://bitmessage.org/forum Bitmessage.org/forum].

Main Page

2018-02-13T22:44:58Z

Atheros: Also change top Infobox

__NOTOC__
{{Infobox
|name=Bitmessage
|downloadsite=https://github.com/Bitmessage/PyBitmessage/releases/download/v0.6.1/Bitmessage-0.6.1.exe
|release caption=Previous Version (Beta)
|latest release date=Aug 21, 2016
|version=0.6.1
}}
Bitmessage is a P2P communications [[Protocol specification|protocol]] used to send encrypted messages to another person or to many subscribers. It is decentralized and trustless, meaning that you need-not inherently trust any entities like root certificate authorities. It uses strong authentication which means that the sender of a message cannot be spoofed, and it aims to hide "non-content" data, like the sender and receiver of messages, from passive eavesdroppers like those running warrantless wiretapping programs. If Bitmessage is completely new to you, you may wish to start by reading the [https://bitmessage.org/bitmessage.pdf whitepaper].

=== Download ===
An open source client is available for free under the very liberal [http://opensource.org/licenses/mit-license.php MIT license]. For screenshots and a description of the client, see this CryptoJunky article: [http://cryptojunky.com/blog/2013/03/09/setting-up-and-using-bitmessage-an-encrypted-communications-platform-based-on-bitcoin/ "Setting Up And Using Bitmessage"].

A remote code execution vulnerability has been spotted in use against Windows and Linux machines running PyBitmessage v0.6.2. The cause was identified and a temporary fix has been added and released as 0.6.3. If you run PyBitmessage via code, we highly recommend that you upgrade to 0.6.3. Alternatively you may downgrade to 0.6.1 which is unaffected. We will release binary files for Windows and OSX tomorrow (2018-02-14).

[[File:windows_icon.png|link=https://github.com/Bitmessage/PyBitmessage/releases/download/v0.6.1/Bitmessage-0.6.1.exe]] [https://github.com/Bitmessage/PyBitmessage/releases/download/v0.6.1/Bitmessage-0.6.1.exe Download for Windows (32bit)] [https://github.com/Bitmessage/PyBitmessage/releases/download/v0.6.1/Bitmessage-0.6.1_64.exe (64bit)]

[[File:apple_icon.png|link=https://github.com/Bitmessage/PyBitmessage/releases/download/v0.6.1/bitmessage-v0.6.1.dmg]] [https://github.com/Bitmessage/PyBitmessage/releases/download/v0.6.1/bitmessage-v0.6.1.dmg Download for OS X]

[[File:tux.png|link=Compiling_instructions]] [[Compiling instructions|Run the source code]]

=== Source code ===
You may view the Python [https://github.com/Bitmessage/PyBitmessage source code on Github]. Bitmessage requires PyQt and OpenSSL. Step-by-step instructions on how to run the source code on Linux, Windows, or OSX is [[Compiling instructions|available here]].

=== Contribute ===
Please follow the [[Contribute|contribution guidelines]] when contributing code or translations.

=== Security audit needed ===
Bitmessage is in need of an independent audit to verify its security. If you are a researcher capable of reviewing the source code, please [https://bitmessage.org/misc/emailaddress.png email] the lead developer. You will be helping to create a great privacy option for people everywhere!

=== Forum ===
* Visit or subscribe to the [https://pay.reddit.com/r/bitmessage Bitmessage subreddit].
* A community-based forum for questions, feedback, and discussion is also available at [https://bitmessage.org/forum Bitmessage.org/forum].

Main Page

2018-02-13T22:38:22Z

Atheros: Added message about vuln and downgrade to 0.6.1

__NOTOC__
{{Infobox
|name=Bitmessage
|downloadsite=https://github.com/Bitmessage/PyBitmessage/releases/download/v0.6.2/Bitmessage_x86_0.6.2.exe
|release caption=Current version (Beta)
|latest release date=Mar 1, 2017
|version=0.6.2
}}
Bitmessage is a P2P communications [[Protocol specification|protocol]] used to send encrypted messages to another person or to many subscribers. It is decentralized and trustless, meaning that you need-not inherently trust any entities like root certificate authorities. It uses strong authentication which means that the sender of a message cannot be spoofed, and it aims to hide "non-content" data, like the sender and receiver of messages, from passive eavesdroppers like those running warrantless wiretapping programs. If Bitmessage is completely new to you, you may wish to start by reading the [https://bitmessage.org/bitmessage.pdf whitepaper].

=== Download ===
An open source client is available for free under the very liberal [http://opensource.org/licenses/mit-license.php MIT license]. For screenshots and a description of the client, see this CryptoJunky article: [http://cryptojunky.com/blog/2013/03/09/setting-up-and-using-bitmessage-an-encrypted-communications-platform-based-on-bitcoin/ "Setting Up And Using Bitmessage"].

A remote code execution vulnerability has been spotted in use against Windows and Linux machines running PyBitmessage v0.6.2. The cause was identified and a temporary fix has been added and released as 0.6.3. If you run PyBitmessage via code, we highly recommend that you upgrade to 0.6.3. Alternatively you may downgrade to 0.6.1 which is unaffected. We will release binary files for Windows and OSX tomorrow (2018-02-14).

[[File:windows_icon.png|link=https://github.com/Bitmessage/PyBitmessage/releases/download/v0.6.1/Bitmessage-0.6.1.exe]] [https://github.com/Bitmessage/PyBitmessage/releases/download/v0.6.1/Bitmessage-0.6.1.exe Download for Windows (32bit)] [https://github.com/Bitmessage/PyBitmessage/releases/download/v0.6.1/Bitmessage-0.6.1_64.exe (64bit)]

[[File:apple_icon.png|link=https://github.com/Bitmessage/PyBitmessage/releases/download/v0.6.1/bitmessage-v0.6.1.dmg]] [https://github.com/Bitmessage/PyBitmessage/releases/download/v0.6.1/bitmessage-v0.6.1.dmg Download for OS X]

[[File:tux.png|link=Compiling_instructions]] [[Compiling instructions|Run the source code]]

=== Source code ===
You may view the Python [https://github.com/Bitmessage/PyBitmessage source code on Github]. Bitmessage requires PyQt and OpenSSL. Step-by-step instructions on how to run the source code on Linux, Windows, or OSX is [[Compiling instructions|available here]].

=== Contribute ===
Please follow the [[Contribute|contribution guidelines]] when contributing code or translations.

=== Security audit needed ===
Bitmessage is in need of an independent audit to verify its security. If you are a researcher capable of reviewing the source code, please [https://bitmessage.org/misc/emailaddress.png email] the lead developer. You will be helping to create a great privacy option for people everywhere!

=== Forum ===
* Visit or subscribe to the [https://pay.reddit.com/r/bitmessage Bitmessage subreddit].
* A community-based forum for questions, feedback, and discussion is also available at [https://bitmessage.org/forum Bitmessage.org/forum].

Template:Infobox

2016-05-02T23:56:54Z

Atheros:

<div style="float:right; margin-left:5px; margin-bottom:5px; padding:0px; border:1px solid #676702; width:15em; margin-bottom: 1em;">
<div style="font-size:105%; line-height:120%; padding: 0.4em; background-color:#D5D590; border-bottom:1px solid #676702; font-weight: bold;">
[[Image:32px-Package.png|right|32px|link=|{{#if: {{{downloadsite}}}|{{{downloadsite}}} | Bitmessage_Download }}]] {{#if: {{{release caption|}}} | {{{release caption}}} | Latest stable version}}
</div>
<center>

'''{{{version}}}'''

 

{{#if: {{{latest release date}}} | {{{latest release date}}} | {{Bitmessage Current Release Date}}}} [[Changelog]]

</center>
</div>
{|
|[[Image:bitmessagelogo-reduced.png|link=]]
| <div style="font-size:150%;">{{#if: {{{name|}}} | {{{name}}} | Bitmessage}}</div>
|}<noinclude>
== Usage ==
<pre>
{{Infobox
|name=
|downloadsite=
|release caption=
|latest release date=
|version=
}}
</pre>
</noinclude>

Template:Bitmessage Current Version Number

2016-05-02T23:56:26Z

Atheros:

page is obsolete

Template:Infobox

2016-05-02T23:55:59Z

Atheros:

Main Page

2016-05-02T23:55:32Z

Atheros:

__NOTOC__
{{Infobox
|name=Bitmessage
|downloadsite=https://bitmessage.org/download/windows/Bitmessage.exe
|release caption=Current version (Beta)
|latest release date=May 2, 2016
|version=0.6.0
}}
Bitmessage is a P2P communications [[Protocol specification|protocol]] used to send encrypted messages to another person or to many subscribers. It is decentralized and trustless, meaning that you need-not inherently trust any entities like root certificate authorities. It uses strong authentication which means that the sender of a message cannot be spoofed, and it aims to hide "non-content" data, like the sender and receiver of messages, from passive eavesdroppers like those running warrantless wiretapping programs. If Bitmessage is completely new to you, you may wish to start by reading the [https://bitmessage.org/bitmessage.pdf whitepaper].

=== Download ===
An open source client is available for free under the very liberal [http://opensource.org/licenses/mit-license.php MIT license]. For screenshots and a description of the client, see this CryptoJunky article: [http://cryptojunky.com/blog/2013/03/09/setting-up-and-using-bitmessage-an-encrypted-communications-platform-based-on-bitcoin/ "Setting Up And Using Bitmessage"].

[[File:windows_icon.png|link=https://bitmessage.org/download/windows/Bitmessage.exe]] [https://bitmessage.org/download/windows/Bitmessage.exe Download for Windows]

[[File:apple_icon.png|link=https://bitmessage.org/download/osx/Bitmessage.dmg]] [https://bitmessage.org/download/osx/Bitmessage.dmg Download for OS X]

[[File:tux.png|link=Compiling_instructions]] [[Compiling instructions|Run the source code]]

=== Source code ===
You may view the Python [https://github.com/Bitmessage/PyBitmessage source code on Github]. Bitmessage requires PyQt and OpenSSL. Step-by-step instructions on how to run the source code on Linux, Windows, or OSX is [[Compiling instructions|available here]].

=== Security audit needed ===
Bitmessage is in need of an independent audit to verify its security. If you are a researcher capable of reviewing the source code, please [https://bitmessage.org/misc/emailaddress.png email] the lead developer. You will be helping to create a great privacy option for people everywhere!

=== Forum ===
* Visit or subscribe to the [https://pay.reddit.com/r/bitmessage Bitmessage subreddit].
* A community-based forum for questions, feedback, and discussion is also available at [https://bitmessage.org/forum Bitmessage.org/forum].

Template:Infobox

2016-05-02T23:51:15Z

Atheros: Undo revision 45492 by Atheros (talk)

<div style="float:right; margin-left:5px; margin-bottom:5px; padding:0px; border:1px solid #676702; width:15em; margin-bottom: 1em;">
<div style="font-size:105%; line-height:120%; padding: 0.4em; background-color:#D5D590; border-bottom:1px solid #676702; font-weight: bold;">
[[Image:32px-Package.png|right|32px|link=|{{#if: {{{downloadsite}}}|{{{downloadsite}}} | Bitmessage_Download }}]] {{#if: {{{release caption|}}} | {{{release caption}}} | Latest stable version}}
</div>
<center>

'''{{Bitmessage Current Version Number}}'''

 

{{#if: {{{latest release date}}} | {{{latest release date}}} | {{Bitmessage Current Release Date}}}} [[Changelog]]

</center>
</div>
{|
|[[Image:bitmessagelogo-reduced.png|link=]]
| <div style="font-size:150%;">{{#if: {{{name|}}} | {{{name}}} | Bitmessage}}</div>
|}<noinclude>
== Usage ==
<pre>
{{Infobox
|name=
|downloadsite=
|release caption=
|latest release date=
}}
</pre>
</noinclude>

Template:Infobox

2016-05-02T23:49:46Z

Atheros: test

<div style="float:right; margin-left:5px; margin-bottom:5px; padding:0px; border:1px solid #676702; width:15em; margin-bottom: 1em;">
<div style="font-size:105%; line-height:120%; padding: 0.4em; background-color:#D5D590; border-bottom:1px solid #676702; font-weight: bold;">
[[Image:32px-Package.png|right|32px|link=|{{#if: {{{downloadsite}}}|{{{downloadsite}}} | Bitmessage_Download }}]] {{#if: {{{release caption|}}} | {{{release caption}}} | Latest stable version}}
</div>
<center>

0.6.0

 

{{#if: {{{latest release date}}} | {{{latest release date}}} | {{Bitmessage Current Release Date}}}} [[Changelog]]

</center>
</div>
{|
|[[Image:bitmessagelogo-reduced.png|link=]]
| <div style="font-size:150%;">{{#if: {{{name|}}} | {{{name}}} | Bitmessage}}</div>
|}<noinclude>
== Usage ==
<pre>
{{Infobox
|name=
|downloadsite=
|release caption=
|latest release date=
}}
</pre>
</noinclude>

Template:Bitmessage Current Version Number

2016-05-02T23:41:41Z

Atheros: 0.6.0

0.6.0

Main Page

2016-05-02T23:38:23Z

Atheros: release 0.6.0

__NOTOC__
{{Infobox
|name=Bitmessage
|downloadsite=https://bitmessage.org/download/windows/Bitmessage.exe
|release caption=Current version (Beta)
|latest release date=May 2, 2016
}}
Bitmessage is a P2P communications [[Protocol specification|protocol]] used to send encrypted messages to another person or to many subscribers. It is decentralized and trustless, meaning that you need-not inherently trust any entities like root certificate authorities. It uses strong authentication which means that the sender of a message cannot be spoofed, and it aims to hide "non-content" data, like the sender and receiver of messages, from passive eavesdroppers like those running warrantless wiretapping programs. If Bitmessage is completely new to you, you may wish to start by reading the [https://bitmessage.org/bitmessage.pdf whitepaper].

=== Download ===
An open source client is available for free under the very liberal [http://opensource.org/licenses/mit-license.php MIT license]. For screenshots and a description of the client, see this CryptoJunky article: [http://cryptojunky.com/blog/2013/03/09/setting-up-and-using-bitmessage-an-encrypted-communications-platform-based-on-bitcoin/ "Setting Up And Using Bitmessage"].

[[File:windows_icon.png|link=https://bitmessage.org/download/windows/Bitmessage.exe]] [https://bitmessage.org/download/windows/Bitmessage.exe Download for Windows]

[[File:apple_icon.png|link=https://bitmessage.org/download/osx/Bitmessage.dmg]] [https://bitmessage.org/download/osx/Bitmessage.dmg Download for OS X]

[[File:tux.png|link=Compiling_instructions]] [[Compiling instructions|Run the source code]]

=== Source code ===
You may view the Python [https://github.com/Bitmessage/PyBitmessage source code on Github]. Bitmessage requires PyQt and OpenSSL. Step-by-step instructions on how to run the source code on Linux, Windows, or OSX is [[Compiling instructions|available here]].

=== Security audit needed ===
Bitmessage is in need of an independent audit to verify its security. If you are a researcher capable of reviewing the source code, please [https://bitmessage.org/misc/emailaddress.png email] the lead developer. You will be helping to create a great privacy option for people everywhere!

=== Forum ===
* Visit or subscribe to the [https://pay.reddit.com/r/bitmessage Bitmessage subreddit].
* A community-based forum for questions, feedback, and discussion is also available at [https://bitmessage.org/forum Bitmessage.org/forum].

User:Atheros

2015-12-29T07:47:55Z

Atheros:

test13

Тест международных символов .
国际字符测试。

User:Atheros

2015-11-10T22:44:11Z

Atheros:

test12

Тест международных символов .
国际字符测试。

Example pyinstaller spec file

2015-10-22T22:48:12Z

Atheros: Update spec file to reflect and work with pyinstaller updates

{{Stub}}
<pre>
# -*- mode: python -*-

block_cipher = None

a = Analysis(['..\\src\\bitmessagemain.py'],
pathex=['C:\\example\\pyinstaller\\bitmessagemain'],
binaries=None,
datas=None,
hiddenimports=[],
hookspath=None,
runtime_hooks=None,
excludes=None,
win_no_prefer_redirects=None,
win_private_assemblies=None,
cipher=block_cipher)

def addTranslations():
import os
extraDatas = []
for file in os.listdir('src\\translations'):
extraDatas.append(('translations\\'+file, 'src\\translations\\' + file, 'DATA'))
return extraDatas

# append the translations directory
a.datas += addTranslations()

pyz = PYZ(a.pure, a.zipped_data,
cipher=block_cipher)
exe = EXE(pyz,
a.scripts,
a.binaries,
a.zipfiles,
a.datas,
a.binaries + [('libeay32.dll', 'c:\\windows\\system32\\libeay32.dll', 'BINARY')],
name='bitmessagemain',
debug=False,
strip=None,
upx=True,
console=False , icon='src\\images\\can-icon.ico')

</pre>

Compiling instructions

2015-10-22T22:21:34Z

Atheros: /* Windows */ Python 2.7.10 exists now.

This page should help novice users run Bitmessage from the source code files.

= Linux =

== Resolve dependencies ==
{| class="wikitable" border="1" width="80%"
|-
! Distribuion
! Instructions
|-
! scope="row"| Debian-based
(Ubuntu, Raspbian, PiBang, others)
| ''Note for Debian Squeeze (6.0) users: Debian Squeeze does not offer packages (like Python, OpenSSL) in versions that are needed for Bitmessage. You can still try to [https://github.com/Bitmessage/PyBitmessage/issues/47#issuecomment-17774377 work around these problems]. Debian 7 "wheezy" works without problems.''
sudo apt-get install python openssl git python-qt4
|-
! scope="row"| Arch Linux
|
sudo pacman -S python2 openssl git python2-pyqt4
|-
! scope="row"| Fedora
| ''Fedora and RHEL6 do not support EC in OpenSSL. Therefore we need [http://linux.ringingliberty.com/bitcoin/ Ringing Liberty's bitcoin repository] to get a compatible library.''

su -c 'yum install -y http://linux.ringingliberty.com/bitcoin/f18/x86_64/bitcoin-release-1-4.noarch.rpm'
su -c 'yum install -y python python-qt4 git openssl-compat-bitcoin-libs'

Tell your system where to look for the library:
echo 'LD_LIBRARY_PATH="/opt/openssl-compat-bitcoin/lib/"' >> ~/.bashrc && source ~/.bashrc
Note for Fedora 20 users: Due to inconsistent behavior encountered by declaring the above variable globally, the following "wrapper script" will declare the LD_LIBRARY_PATH variable correctly and only when running bitmessage. Name the script something like "bitmessage", mark it as executable (probably something like 755) and put it in /usr/bin so it's accessible without the full path.
export LD_LIBRARY_PATH="/opt/openssl-compat-bitcoin/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
/home/<yourusername>/PyBitmessage/src/bitmessagemain.py > /dev/null 2>&1 &
|-
! scope="row"| Red Hat Enterprise Linux (RHEL)
| ''Fedora and RHEL6 do not support EC in OpenSSL. Therefore we need [http://linux.ringingliberty.com/bitcoin/ Ringing Liberty's bitcoin repository] to get a compatible library.''

su -c 'yum install -y http://linux.ringingliberty.com/bitcoin/el6/x86_64/bitcoin-release-1-4.noarch.rpm'
su -c 'yum install -y python python-qt4 git openssl-compat-bitcoin-libs'
Tell your system where to look for the library:
echo 'LD_LIBRARY_PATH="/opt/openssl-compat-bitcoin/lib/"' >> ~/.bashrc && source ~/.bashrc
|}

== Download and run PyBitmessage ==
# Download the source code from github: <code>git clone <nowiki>https://github.com/Bitmessage/PyBitmessage $HOME/PyBitmessage</nowiki></code>
# Run PyBitmessage: <code>~/PyBitmessage/src/bitmessagemain.py</code>
Check the wiki for more information on how to run Bitmessage [https://bitmessage.org/wiki/Daemon as a daemon].

If you receive a warning that you need to use python 2.7.3 or greater, and have followed the above instructions to upgrade it, your system may be attemping to run PyBitmessage with python 3. In this case, run <code>python2 ~/PyBitmessage/src/bitmessagemain.py</code>

== Upgrading ==
To upgrade Bitmessage run the following commands:
:<code>cd $HOME/PyBitmessage</code>
:<code>git pull</code>

= OS X =
== With Homebrew package manager ==
; Setup
First, make sure you have not already installed Macports. Having both macports and homebrew on the same system is a recipe for disaster.
Install Homebrew:
ruby -e "$(curl -fsSL https://raw.github.com/mxcl/homebrew/go)"

; Update Python:
brew install python

; Install dependencies:
brew install pyqt openssl

; Download and run
cd ~/Desktop
git clone git://github.com/Bitmessage/PyBitmessage.git
cd PyBitmessage
python src/bitmessagemain.py

== With macports package manager ==
First, make sure you have not already installed Homebrew. Having both macports and homebrew on the same system is a recipe for disaster.
Installing with macports or homebrew essentially has the same effect. Homebrew does some things better than ports, and ports does some things better than brew. If old-school floats your boat, these instructions are for you.

; Select the macports installation that is right for your version of osx
Read the instructions or take this as a reminder: Apple's XCode and their Command Line Tools are a prerequiste for Macports, go: https://www.macports.org/install.php

; Install dependencies and needed tools
sudo port install python27 py27-pyqt4 openssl
sudo port install git-core +svn +doc +bash_completion +gitweb

; Download and run
cd ~/Desktop
git clone git://github.com/Bitmessage/PyBitmessage.git
cd PyBitmessage
python2.7 src/bitmessagemain.py

= Windows =
# Download and install the latest revision of Python 2.7 (currently Python 2.7.10 from [https://www.python.org/downloads/ here]). The ''Windows x86 MSI Installer'' is the right choice for most people. (64-bit users may want the 64-bit version).
## Test that it installed:
### Open a command prompt by going to Start > Run. Type 'cmd' then press enter.
### type 'python'. If python is installed, you should see the python version and the prompt: '>>>'
### If you see a message such as: "'Python is not recognized as an internal or external command..." then you must add the python path to your path environmental variable:
#### Find the location where Python was installed (in particular, the location where python.exe exists). It might simply be in c:\Python2.7
#### Follow [http://www.computerhope.com/issues/ch000549.htm these directions] to add the Python path to your path variable.
#### Close the command prompt window and reopen it.
### Try running 'python' again.
###Press Ctrl-Z to exit Python.
# Download PyQt from [http://www.riverbankcomputing.com/software/pyqt/download here]. ''PyQt is one of Bitmessage's two dependencies.'' Look for the links to downloads under the heading labeled "Binary Package;" the binary package versions are already compiled for you. Select the version for Python 2.7 (look for "Py2.7" in the file name). Install PyQt.
# Download OpenSSL from [http://slproweb.com/products/Win32OpenSSL.html here]. ''OpenSSL is the second of Bitmessage's two dependencies.'' Install OpenSSL. If an error message appears during installation of OpenSSL, download and install Visual C++ 2008. A link is provided on the OpenSSL download page.
# Download the source code for PyBitmessage from GitHub. If it is in a zip file, you will need to extract it. There should be a few files and a few folders where one of the folders is 'src'.
# To run Bitmessage, navigate into the 'src' folder and then double click on the bitmessagemain.py file, or in a command prompt, change directories to the 'src' directory which holds bitmessagemain.py and type 'python bitmessagemain.py'.

== If you change user interface files ==
You can use Qt's Designer application to modify the user interface. After you do this, you will need to 'compile' .ui files into .py files.
# In a command prompt, change directories to the directory of your .ui file.
# Run 'pyuic4 example.ui > example.py' If you get a message similar to 'pyuic4 is not recognized as an internal or external command' then you must add the PyQt directory to your system's path variable. This directory should hold pyuic4.bat. It might be in C:\Python27\Lib\site-packages\PyQt4. Remember to close the command window and reopen it after you change your path variable.

If you add icons to bitmessage_icons.qrc, then you must run this command:
pyrcc4 bitmessage_icons.qrc -o bitmessage_icons_rc.py

== Optional: Compile into a stand-alone EXE ==
# Download and install PyWin32
# Download [http://www.pyinstaller.org/ PyInstaller].
# Copy Bitmessage's 'src' directory to the PyInstaller directory (which contains pyinstaller.py).
# Run 'pyinstaller.py --onefile --noconsole --icon="src\images\can-icon.ico" src\bitmessagemain.py'
This won't include the OpenSSL DLL file in the EXE; if you send it to someone who doesn't have OpenSSL installed, it will not run. To include the DLL file in the EXE, you must follow these steps:
# After following the steps above, you will see that pyinstaller created a folder called bitmessagemain. In that folder is a file: bitmessagemain.spec. Open it with a text editor.
# Below the line "a.datas," add this line: <code>a.binaries + [('libeay32.dll', 'c:\\windows\\system32\\libeay32.dll', 'BINARY')],</code>
# Optionally also include the translations by modifying this file further by adding the lines shown in [[Example_pyinstaller_spec_file|this]] example file.
# Save and close
# Run this command: pyinstaller.py bitmessagemain/bitmessagemain.spec

If you do not have the libeay32.dll you can download it here. http://www.dll-files.com/dllindex/dll-files.shtml?libeay32

API Reference

2015-03-07T07:37:03Z

Atheros: /* List of Operations */ Added TTL to sendBroadcast

=== Introduction ===

The PyBitmessage API uses [http://en.wikipedia.org/wiki/XML-RPC XML-RPC].

=== Enable the API ===
To enable the API, copy and paste these lines into the bitmessagesettings section of the [[keys.dat]] file.
Note that the values "username" and "password" below are merely examples, and should be replaced by values that cannot feasibly be guessed:
<pre>
apienabled = true
apiport = 8442
apiinterface = 127.0.0.1
apiusername = username
apipassword = password
</pre>
Additionally, you may optionally include an additional entry which will specify a program which Bitmessage will run when certain events occur.
<pre>
apinotifypath = c:\\example\\example.exe
</pre>
One of these arguments will be passed to your program: startingUp, newMessage, newBroadcast. Be sure your program doesn't crash when given newer arguments introduced in the future as this list will likely expand.

=== Remote Access ===
To access the Bitmessage API from a remote location, change the apiinterface value from '''127.0.0.1''' to '''0.0.0.0'''.

The following Python code offers a demonstration of how to create a client that can connect to the PyBitmessage API.

In this example, the username is "username", the password is "password", the IP address of the server running PyBitmessage is 105.168.1.0 (a random example), and the port number which PyBitmessage has been configured to listen on is 8442. In order to connect with the remote copy of PyBitmessage, these settings must match those in PyBitmessage's "keys.dat" file.
<pre>
import xmlrpclib
import json
import time

api = xmlrpclib.ServerProxy("http://username:password@105.168.1.0:8442/")
print api.add(2,3)
</pre>

A more complete example can be found in the [https://github.com/Bitmessage/PyBitmessage/blob/master/src/api_client.py api_client.py] file in the PyBitmessage source code.

=== List of Operations ===
Required arguments are denoted inside < and > Optional arguments are inside [ and ].
{|class="wikitable"
! Command !! Parameters !! Minimum Version !! Description
|-
| helloWorld || <firstWord> <secondWord> || 0.2.7 || returns 'firstWord-secondWord'. Used as a simple test of the API.
|-
| add || <integer> <integer> || 0.2.7 || returns the sum of the integers. Used as a simple test of the API.
|-
| statusBar || <message> || 0.2.7 || Displays the message in the status bar on the GUI
|-
| listAddresses2|| || 0.4.0 || Lists all addresses shown on the Your Identities tab. Returns a list of objects with these properties:
* label (base64, decodes into utf-8)
* address (ascii/utf-8)
* stream (integer)
* enabled (bool)
* chan (bool)

This is called listAddresses'''2''' because 'listAddresses' is obsolete.
|-
| createRandomAddress || <label> [eighteenByteRipe] [totalDifficulty] [smallMessageDifficulty] || 0.2.7 || Creates one address using the random number generator. label should be base64 encoded. eighteenByteRipe is a boolean telling Bitmessage whether to generate an address with an 18 byte RIPE hash(as opposed to a 19 byte hash). This is the same setting as the "Do extra work to make the address 1 or 2 characters shorter" in the user interface. Using False is recommended if you are running some sort of website and will be generating a lot of addresses. Note that even if you don't ask for it, there is still a 1 in 256 chance that you will get an address with an 18 byte RIPE hash so if you actually ''need'' an address with a 19 byte RIPE hash for some reason, you will need to check for it. eighteenByteRipe defaults to False. totalDifficulty and smallMessageDifficulty default to 1.

Returns the address.

Warning: At present, Bitmessage gets confused if you use both the API and the UI to make an address at the same time.
|-
|createDeterministicAddresses ||<passphrase> [numberOfAddresses] [addressVersionNumber] [streamNumber] [eighteenByteRipe] [totalDifficulty] [smallMessageDifficulty] || 0.3.4 || Similar to createRandomAddress except that you may generate many addresses in one go. passphrase should be base64 encoded. numberOfAddresses defaults to 1. addressVersionNumber and streamNumber may be set to 0 which will tell Bitmessage to use the most up-to-date addressVersionNumber and the most available streamNumber. Using zero for each of these fields is recommended. eighteenByteRipe defaults to False. totalDifficulty and smallMessageDifficulty default to 1.

Returns a list of new addresses. This list will be empty if the addresses already existed.

Warning: At present, Bitmessage gets confused if you use both the API and the UI to make addresses at the same time.
|-
|getDeterministicAddress ||<passphrase> <addressVersionNumber> <streamNumber> || 0.3.1 || Similar to createDeterministicAddresses except that the one address that is returned will not be added to the Bitmessage user interface or the keys.dat file. passphrase should be base64 encoded. addressVersionNumber should be set to 3 or 4 as these are the only ones currently supported. streamNumber must be set to 1 as this is the only one currently supported.

Returns a single address.

Warning: At present, Bitmessage gets confused if you use both this API command and the UI to make addresses at the same time.
|-
|<code>getAllInboxMessages</code>|| || 0.2.7 || Does not include trashed messages. Returns a list of objects with these properties:
* msgid (hex)
* toAddress (ascii/utf-8)
* fromAddress (ascii/utf-8)
* subject (base64, decodes into utf-8)
* message (base64, decodes into utf-8)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* receivedTime (integer, Unix time)
* read (integer representing binary state (0 or 1))

The msgid is the same as the hash of the message (analogous to the TXID in Bitcoin) thus it is shown in hex as that is the de facto standard. The base64 encoding Bitmessage uses includes line breaks including one on the end of the string.
|-
|<code>getAllInboxMessageIDs</code>|| || 0.2.7 || Returns a list of msgids of all Inbox messages with there properties:
* msgid (hex)
|-
| getInboxMessageByID || <msgid> [read] || 0.4.0 || Returns an object with these properties:
* msgid (hex)
* toAddress (ascii/utf-8)
* fromAddress (ascii/utf-8)
* subject (base64, decodes into utf-8)
* message (base64, decodes into utf-8)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* receivedTime (integer, Unix time)
* read (integer representing binary state (0 or 1))

Optionally sets the specific message to have a read status of 'read' (bool).

The msgid is the same as the hash of the message (analogous to the TXID in Bitcoin) thus it should be given in hex as that is the de facto standard. The base64 encoding Bitmessage uses includes line breaks including one on the end of the string.
|-
| getSentMessageByAckData || <ackData> || 0.3.4 || Returns an object with these properties:
* msgid (hex)
* toAddress (ascii/utf-8)
* fromAddress (ascii/utf-8)
* subject (base64, decodes into utf-8)
* message (base64, decodes into utf-8)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* lastActionTime (integer, Unix time)
* status (ascii/utf-8)
* ackData (hex)
|-
| getAllSentMessages || || 0.3.4 || Returns an object with these properties:
* msgid (hex)
* toAddress (ascii/utf-8)
* fromAddress (ascii/utf-8)
* subject (base64, decodes into utf-8)
* message (base64, decodes into utf-8)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* lastActionTime (integer, Unix time)
* status (ascii/utf-8)
* ackData (hex)
|-
| getSentMessageByID || <msgid> || 0.3.4 || Returns an object with these properties:
* msgid (hex)
* toAddress (ascii/utf-8)
* fromAddress (ascii/utf-8)
* subject (base64, decodes into utf-8)
* message (base64, decodes into utf-8)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* lastActionTime (integer, Unix time)
* status (ascii/utf-8)
* ackData (hex)
|-
| getSentMessagesBySender|| <fromAddress> || 0.3.4 || Returns a list of objects with these properties:
* msgid (hex)
* toAddress (ascii/utf-8)
* fromAddress (ascii/utf-8)
* subject (base64, decodes into utf-8)
* message (base64, decodes into utf-8)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* lastActionTime (integer, Unix time)
* status (ascii/utf-8)
* ackData (hex)
|-
| trashMessage || <msgid> || 0.2.7 || returns a simple message saying that the message was trashed assuming it ever even existed. Prior existence is not checked. msgid is encoded in hex just like in the getAllInboxMessages function.
|-
| sendMessage || <toAddress> <fromAddress> <subject> <message> [encodingType] [TTL] || 0.2.7 or 0.4.5 || returns ackdata encoded in hex. subject and message must be encoded in base64 which may optionally include line breaks. If used, the encodingType must be set to 2; this is included for forwards compatibility. TTL is specified in seconds; values outside the bounds of 3600 to 2419200 will be moved to be within those bounds. TTL defaults to 4 days. TTL is only available in PyBitmessage version 0.4.5 and higher.
|-
| sendBroadcast || <fromAddress> <subject> <message> [encodingType] [TTL] || 0.2.7 or 0.4.5 || returns ackData encoded in hex. subject and message must be encoded in base64. If used, the encodingType must be set to 2; this is included for forwards compatibility. TTL is specified in seconds; values outside the bounds of 3600 to 2419200 will be moved to be within those bounds. TTL defaults to 4 days. TTL is only available in PyBitmessage version 0.4.5 and higher.
|-
| getStatus || <ackData> || 0.3.0 || returns one of these strings: <strike>notFound, findingPubkey, doingPOW, sentMessage, or ackReceived</strike> notfound, msgqueued, broadcastqueued, broadcastsent, doingpubkeypow, awaitingpubkey, doingmsgpow, forcepow, msgsent, msgsentnoackexpected, or ackreceived.
|-
| listSubscriptions|| || 0.4.0 || Returns a list of objects with these properties:
* label (base64, decodes into utf-8)
* address (ascii/utf-8)
* enabled (bool)
|-
| addSubscription|| <address> [label] || 0.3.1 || Subscribe to an address. label must be base64-encoded.
|-
| deleteSubscription|| <address> || 0.3.1 || Unsubscribe from an address. The program does not check to see whether you were subscribed in the first place.
|-
| listAddressBookEntries|| || 0.4.0 ||Returns a list of objects with these properties:
* address (ascii/utf-8)
* label (base64, decodes into utf-8)
|-
| addAddressBookEntry|| <address> <label> || 0.4.0 || Add an entry to your address book. label must be base64-encoded.
|-
| deleteAddressBookEntry|| <address> || 0.4.0 || Delete an entry from your address book. The program does not check to see whether it was there in the first place.
|-
| trashSentMessageByAckData|| <ackData> || 0.4.0 || Trashes a sent message based on its ackdata. ackData should be encoded in hex. Returns a simple message saying that the message was trashed assuming it ever even existed. Prior existence is not checked.
|-
| createChan|| <passphrase> || 0.4.2 || Creates a new chan. passphrase must be base64 encoded. Outputs the corresponding Bitmessage address.
|-
| joinChan|| <passphrase> <address> || 0.4.2 || Join a chan. passphrase must be base64 encoded. Outputs "success"
|-
| leaveChan|| <address> || 0.4.2 || Leave a chan. Outputs "success". Note that at this time, the address is still shown in the UI until a restart.
|-
| deleteAddress|| <address> || 0.4.2 || Permanently delete an address from Your Identities and your keys.dat file. Outputs "success". Note that at this time, the address is still shown in the UI until a restart.
|-
| decodeAddress|| <address> || 0.4.2 || Returns an object with these properties:
* status (ascii/utf-8)
* addressVersion (ascii integer)
* streamNumber (ascii integer)
* ripe (base64, decodes into binary data)
|-
| addAddressToBlackWhiteList || <address> [label] || 0.4.5 || Add an entry to your black or white list- whichever you are currently using. label must be base64-encoded.
|-
| removeAddressFromBlackWhiteList || <address> || 0.4.5 || Delete an entry from your black or white list- whichever you are currently using (but not both).
|-
| clientStatus || || 0.4.0 || Returns the softwareName, softwareVersion, networkStatus, networkConnections, numberOfPubkeysProcessed, numberOfMessagesProcessed, and numberOfBroadcastsProcessed. networkStatus will be one of these strings: "notConnected", "connectedButHaveNotReceivedIncomingConnections", or "connectedAndReceivingIncomingConnections".
|}

'''Note:''' If the minimum required version is higher than {{Bitmessage Current Version Number}} then the code is available in source but not yet available in a compiled binary.

==== Possible error values ====

Here are the various error numbers and descriptions you might see.

{|class="wikitable"
! Error Number!! Message
|-
|0000 || API Error 0000: I need parameters!
|-
| 0001 || API Error 0001: The specified passphrase is blank.
|-
| 0002 || API Error 0002: The address version number currently must be 3 or 4 (or 0 which means auto-select).
|-
| 0003 || API Error 0003: The stream number must be 1 (or 0 which means auto-select). Others aren't supported.
|-
| 0004 || API Error 0004: Why would you ask me to generate 0 addresses for you?
|-
| 0005 || API Error 0005: You have (accidentally?) specified too many addresses to make. Maximum 999. This check only exists to prevent mischief; if you really want to create more addresses than this, contact the Bitmessage developers and we can modify the check or you can do it yourself by searching the source code for this message.
|-
| 0006 || API Error 0006: The encoding type must be 2 because that is the only one this program currently supports.
|-
| 0007 || API Error 0007: Could not decode address
|-
| 0008 || API Error 0008: Checksum failed for address
|-
| 0009 || API Error 0009: Invalid characters in address
|-
| 0010 || API Error 0010: Address version number too high (or zero) in address
|-
| 0011 || API Error 0011: The address version number currently must be 2, 3, or 4. Others aren't supported.
|-
| 0012 || API Error 0012: The stream number must be 1. Others aren't supported.
|-
| 0013 || API Error 0013: Could not find your fromAddress in the keys.dat file.
|-
| 0014 || API Error 0014: Your fromAddress is disabled. Cannot send.
|-
| 0015 || API Error 0015: The length of ackData should be 32 bytes (encoded in hex thus 64 characters).
|-
| 0016 || API Error 0016: You are already subscribed to that address.
|-
| 0017 || API Error 0017: Label is not valid UTF-8 data.
|-
| 0018 || API Error 0018: Chan name does not match address.
|-
| 0019 || API Error 0019: The length of hash should be 20 bytes (encoded in hex thus 40 characters).
|-
| 0020 || API Error 0020: Invalid method: <method_name_you_tried_to_execute>
|-
| 0021 || API Error 0021: Unexpected API Failure
|-
| 0022 || API Error 0022: Decode Error
|-
| 0023 || API Error 0023: Bool expected
|-
| 0024 || API Error 0024: Chan address is already present.
|-
| 0025 || API Error 0025: Specified address is not a chan address. Use deleteAddress API call instead.
|-
| 0026 || API Error 0026: Varint encoded in address is malformed.
|-
| 0027 || API Error 0027: Message is too long.
|-
| 0028 || API Error 0028: You have already black-/white-listed that address.
|-
| 0029 || API Error 0029: That entry does not exist in the black-/white-list.
|}

API Reference

2015-03-07T07:24:33Z

Atheros: /* List of Operations */ Added TTL to sendMessage

=== Introduction ===

The PyBitmessage API uses [http://en.wikipedia.org/wiki/XML-RPC XML-RPC].

=== Enable the API ===
To enable the API, copy and paste these lines into the bitmessagesettings section of the [[keys.dat]] file.
Note that the values "username" and "password" below are merely examples, and should be replaced by values that cannot feasibly be guessed:
<pre>
apienabled = true
apiport = 8442
apiinterface = 127.0.0.1
apiusername = username
apipassword = password
</pre>
Additionally, you may optionally include an additional entry which will specify a program which Bitmessage will run when certain events occur.
<pre>
apinotifypath = c:\\example\\example.exe
</pre>
One of these arguments will be passed to your program: startingUp, newMessage, newBroadcast. Be sure your program doesn't crash when given newer arguments introduced in the future as this list will likely expand.

=== Remote Access ===
To access the Bitmessage API from a remote location, change the apiinterface value from '''127.0.0.1''' to '''0.0.0.0'''.

The following Python code offers a demonstration of how to create a client that can connect to the PyBitmessage API.

In this example, the username is "username", the password is "password", the IP address of the server running PyBitmessage is 105.168.1.0 (a random example), and the port number which PyBitmessage has been configured to listen on is 8442. In order to connect with the remote copy of PyBitmessage, these settings must match those in PyBitmessage's "keys.dat" file.
<pre>
import xmlrpclib
import json
import time

api = xmlrpclib.ServerProxy("http://username:password@105.168.1.0:8442/")
print api.add(2,3)
</pre>

A more complete example can be found in the [https://github.com/Bitmessage/PyBitmessage/blob/master/src/api_client.py api_client.py] file in the PyBitmessage source code.

=== List of Operations ===
Required arguments are denoted inside < and > Optional arguments are inside [ and ].
{|class="wikitable"
! Command !! Parameters !! Minimum Version !! Description
|-
| helloWorld || <firstWord> <secondWord> || 0.2.7 || returns 'firstWord-secondWord'. Used as a simple test of the API.
|-
| add || <integer> <integer> || 0.2.7 || returns the sum of the integers. Used as a simple test of the API.
|-
| statusBar || <message> || 0.2.7 || Displays the message in the status bar on the GUI
|-
| listAddresses2|| || 0.4.0 || Lists all addresses shown on the Your Identities tab. Returns a list of objects with these properties:
* label (base64, decodes into utf-8)
* address (ascii/utf-8)
* stream (integer)
* enabled (bool)
* chan (bool)

This is called listAddresses'''2''' because 'listAddresses' is obsolete.
|-
| createRandomAddress || <label> [eighteenByteRipe] [totalDifficulty] [smallMessageDifficulty] || 0.2.7 || Creates one address using the random number generator. label should be base64 encoded. eighteenByteRipe is a boolean telling Bitmessage whether to generate an address with an 18 byte RIPE hash(as opposed to a 19 byte hash). This is the same setting as the "Do extra work to make the address 1 or 2 characters shorter" in the user interface. Using False is recommended if you are running some sort of website and will be generating a lot of addresses. Note that even if you don't ask for it, there is still a 1 in 256 chance that you will get an address with an 18 byte RIPE hash so if you actually ''need'' an address with a 19 byte RIPE hash for some reason, you will need to check for it. eighteenByteRipe defaults to False. totalDifficulty and smallMessageDifficulty default to 1.

Returns the address.

Warning: At present, Bitmessage gets confused if you use both the API and the UI to make an address at the same time.
|-
|createDeterministicAddresses ||<passphrase> [numberOfAddresses] [addressVersionNumber] [streamNumber] [eighteenByteRipe] [totalDifficulty] [smallMessageDifficulty] || 0.3.4 || Similar to createRandomAddress except that you may generate many addresses in one go. passphrase should be base64 encoded. numberOfAddresses defaults to 1. addressVersionNumber and streamNumber may be set to 0 which will tell Bitmessage to use the most up-to-date addressVersionNumber and the most available streamNumber. Using zero for each of these fields is recommended. eighteenByteRipe defaults to False. totalDifficulty and smallMessageDifficulty default to 1.

Returns a list of new addresses. This list will be empty if the addresses already existed.

Warning: At present, Bitmessage gets confused if you use both the API and the UI to make addresses at the same time.
|-
|getDeterministicAddress ||<passphrase> <addressVersionNumber> <streamNumber> || 0.3.1 || Similar to createDeterministicAddresses except that the one address that is returned will not be added to the Bitmessage user interface or the keys.dat file. passphrase should be base64 encoded. addressVersionNumber should be set to 3 or 4 as these are the only ones currently supported. streamNumber must be set to 1 as this is the only one currently supported.

Returns a single address.

Warning: At present, Bitmessage gets confused if you use both this API command and the UI to make addresses at the same time.
|-
|<code>getAllInboxMessages</code>|| || 0.2.7 || Does not include trashed messages. Returns a list of objects with these properties:
* msgid (hex)
* toAddress (ascii/utf-8)
* fromAddress (ascii/utf-8)
* subject (base64, decodes into utf-8)
* message (base64, decodes into utf-8)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* receivedTime (integer, Unix time)
* read (integer representing binary state (0 or 1))

The msgid is the same as the hash of the message (analogous to the TXID in Bitcoin) thus it is shown in hex as that is the de facto standard. The base64 encoding Bitmessage uses includes line breaks including one on the end of the string.
|-
|<code>getAllInboxMessageIDs</code>|| || 0.2.7 || Returns a list of msgids of all Inbox messages with there properties:
* msgid (hex)
|-
| getInboxMessageByID || <msgid> [read] || 0.4.0 || Returns an object with these properties:
* msgid (hex)
* toAddress (ascii/utf-8)
* fromAddress (ascii/utf-8)
* subject (base64, decodes into utf-8)
* message (base64, decodes into utf-8)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* receivedTime (integer, Unix time)
* read (integer representing binary state (0 or 1))

Optionally sets the specific message to have a read status of 'read' (bool).

The msgid is the same as the hash of the message (analogous to the TXID in Bitcoin) thus it should be given in hex as that is the de facto standard. The base64 encoding Bitmessage uses includes line breaks including one on the end of the string.
|-
| getSentMessageByAckData || <ackData> || 0.3.4 || Returns an object with these properties:
* msgid (hex)
* toAddress (ascii/utf-8)
* fromAddress (ascii/utf-8)
* subject (base64, decodes into utf-8)
* message (base64, decodes into utf-8)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* lastActionTime (integer, Unix time)
* status (ascii/utf-8)
* ackData (hex)
|-
| getAllSentMessages || || 0.3.4 || Returns an object with these properties:
* msgid (hex)
* toAddress (ascii/utf-8)
* fromAddress (ascii/utf-8)
* subject (base64, decodes into utf-8)
* message (base64, decodes into utf-8)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* lastActionTime (integer, Unix time)
* status (ascii/utf-8)
* ackData (hex)
|-
| getSentMessageByID || <msgid> || 0.3.4 || Returns an object with these properties:
* msgid (hex)
* toAddress (ascii/utf-8)
* fromAddress (ascii/utf-8)
* subject (base64, decodes into utf-8)
* message (base64, decodes into utf-8)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* lastActionTime (integer, Unix time)
* status (ascii/utf-8)
* ackData (hex)
|-
| getSentMessagesBySender|| <fromAddress> || 0.3.4 || Returns a list of objects with these properties:
* msgid (hex)
* toAddress (ascii/utf-8)
* fromAddress (ascii/utf-8)
* subject (base64, decodes into utf-8)
* message (base64, decodes into utf-8)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* lastActionTime (integer, Unix time)
* status (ascii/utf-8)
* ackData (hex)
|-
| trashMessage || <msgid> || 0.2.7 || returns a simple message saying that the message was trashed assuming it ever even existed. Prior existence is not checked. msgid is encoded in hex just like in the getAllInboxMessages function.
|-
| sendMessage || <toAddress> <fromAddress> <subject> <message> [encodingType] [TTL] || 0.2.7 - 0.4.5 || returns ackdata encoded in hex. subject and message must be encoded in base64 which may optionally include line breaks. If used, the encodingType must be set to 2; this is included for forwards compatibility. TTL is specified in seconds; values outside the bounds of 3600 to 2419200 will be moved to be within those bounds. TTL defaults to 4 days. TTL is only available in PyBitmessage version 0.4.5 and higher.
|-
| sendBroadcast || <fromAddress> <subject> <message> [encodingType] || 0.2.7 || returns ackData encoded in hex. subject and message must be encoded in base64. If used, the encodingType must be set to 2; this is included for forwards compatibility.
|-
| getStatus || <ackData> || 0.3.0 || returns one of these strings: <strike>notFound, findingPubkey, doingPOW, sentMessage, or ackReceived</strike> notfound, msgqueued, broadcastqueued, broadcastsent, doingpubkeypow, awaitingpubkey, doingmsgpow, forcepow, msgsent, msgsentnoackexpected, or ackreceived.
|-
| listSubscriptions|| || 0.4.0 || Returns a list of objects with these properties:
* label (base64, decodes into utf-8)
* address (ascii/utf-8)
* enabled (bool)
|-
| addSubscription|| <address> [label] || 0.3.1 || Subscribe to an address. label must be base64-encoded.
|-
| deleteSubscription|| <address> || 0.3.1 || Unsubscribe from an address. The program does not check to see whether you were subscribed in the first place.
|-
| listAddressBookEntries|| || 0.4.0 ||Returns a list of objects with these properties:
* address (ascii/utf-8)
* label (base64, decodes into utf-8)
|-
| addAddressBookEntry|| <address> <label> || 0.4.0 || Add an entry to your address book. label must be base64-encoded.
|-
| deleteAddressBookEntry|| <address> || 0.4.0 || Delete an entry from your address book. The program does not check to see whether it was there in the first place.
|-
| trashSentMessageByAckData|| <ackData> || 0.4.0 || Trashes a sent message based on its ackdata. ackData should be encoded in hex. Returns a simple message saying that the message was trashed assuming it ever even existed. Prior existence is not checked.
|-
| createChan|| <passphrase> || 0.4.2 || Creates a new chan. passphrase must be base64 encoded. Outputs the corresponding Bitmessage address.
|-
| joinChan|| <passphrase> <address> || 0.4.2 || Join a chan. passphrase must be base64 encoded. Outputs "success"
|-
| leaveChan|| <address> || 0.4.2 || Leave a chan. Outputs "success". Note that at this time, the address is still shown in the UI until a restart.
|-
| deleteAddress|| <address> || 0.4.2 || Permanently delete an address from Your Identities and your keys.dat file. Outputs "success". Note that at this time, the address is still shown in the UI until a restart.
|-
| decodeAddress|| <address> || 0.4.2 || Returns an object with these properties:
* status (ascii/utf-8)
* addressVersion (ascii integer)
* streamNumber (ascii integer)
* ripe (base64, decodes into binary data)
|-
| addAddressToBlackWhiteList || <address> [label] || 0.4.5 || Add an entry to your black or white list- whichever you are currently using. label must be base64-encoded.
|-
| removeAddressFromBlackWhiteList || <address> || 0.4.5 || Delete an entry from your black or white list- whichever you are currently using (but not both).
|-
| clientStatus || || 0.4.0 || Returns the softwareName, softwareVersion, networkStatus, networkConnections, numberOfPubkeysProcessed, numberOfMessagesProcessed, and numberOfBroadcastsProcessed. networkStatus will be one of these strings: "notConnected", "connectedButHaveNotReceivedIncomingConnections", or "connectedAndReceivingIncomingConnections".
|}

'''Note:''' If the minimum required version is higher than {{Bitmessage Current Version Number}} then the code is available in source but not yet available in a compiled binary.

==== Possible error values ====

Here are the various error numbers and descriptions you might see.

{|class="wikitable"
! Error Number!! Message
|-
|0000 || API Error 0000: I need parameters!
|-
| 0001 || API Error 0001: The specified passphrase is blank.
|-
| 0002 || API Error 0002: The address version number currently must be 3 or 4 (or 0 which means auto-select).
|-
| 0003 || API Error 0003: The stream number must be 1 (or 0 which means auto-select). Others aren't supported.
|-
| 0004 || API Error 0004: Why would you ask me to generate 0 addresses for you?
|-
| 0005 || API Error 0005: You have (accidentally?) specified too many addresses to make. Maximum 999. This check only exists to prevent mischief; if you really want to create more addresses than this, contact the Bitmessage developers and we can modify the check or you can do it yourself by searching the source code for this message.
|-
| 0006 || API Error 0006: The encoding type must be 2 because that is the only one this program currently supports.
|-
| 0007 || API Error 0007: Could not decode address
|-
| 0008 || API Error 0008: Checksum failed for address
|-
| 0009 || API Error 0009: Invalid characters in address
|-
| 0010 || API Error 0010: Address version number too high (or zero) in address
|-
| 0011 || API Error 0011: The address version number currently must be 2, 3, or 4. Others aren't supported.
|-
| 0012 || API Error 0012: The stream number must be 1. Others aren't supported.
|-
| 0013 || API Error 0013: Could not find your fromAddress in the keys.dat file.
|-
| 0014 || API Error 0014: Your fromAddress is disabled. Cannot send.
|-
| 0015 || API Error 0015: The length of ackData should be 32 bytes (encoded in hex thus 64 characters).
|-
| 0016 || API Error 0016: You are already subscribed to that address.
|-
| 0017 || API Error 0017: Label is not valid UTF-8 data.
|-
| 0018 || API Error 0018: Chan name does not match address.
|-
| 0019 || API Error 0019: The length of hash should be 20 bytes (encoded in hex thus 40 characters).
|-
| 0020 || API Error 0020: Invalid method: <method_name_you_tried_to_execute>
|-
| 0021 || API Error 0021: Unexpected API Failure
|-
| 0022 || API Error 0022: Decode Error
|-
| 0023 || API Error 0023: Bool expected
|-
| 0024 || API Error 0024: Chan address is already present.
|-
| 0025 || API Error 0025: Specified address is not a chan address. Use deleteAddress API call instead.
|-
| 0026 || API Error 0026: Varint encoded in address is malformed.
|-
| 0027 || API Error 0027: Message is too long.
|-
| 0028 || API Error 0028: You have already black-/white-listed that address.
|-
| 0029 || API Error 0029: That entry does not exist in the black-/white-list.
|}

Protocol specification

2015-02-08T01:44:00Z

Atheros: /* version */ Added length limit to user_agent and stream_numbers within version message

All objects sent on the network should support protocol v3 starting on Sun, 16 Nov 2014 22:00:00 GMT. 

==Common standards==

=== Hashes ===

Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-512] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when creating an address.

A double-round of SHA-512 is used for the Proof Of Work. Example of double-SHA-512 encoding of string "hello":

hello
9b71d224bd62f3785d96d46ad3ea3d73319bfbc2890caadae2dff72519673ca72323c3d99ba5c11d7c7acc6e14b8c5da0c4663475c2e5c3adef46f73bcdec043(first round of sha-512)
0592a10584ffabf96539f3d780d776828c67da1ab5b169e9e8aed838aaecc9ed36d49ff1423c55f019e050c66c6324f53588be88894fef4dcffdb74b98e2b200(second round of sha-512)

For Bitmessage addresses (RIPEMD-160) this would give:

hello
9b71d224bd62f3785d96d46ad3ea3d73319bfbc2890caadae2dff72519673ca72323c3d99ba5c11d7c7acc6e14b8c5da0c4663475c2e5c3adef46f73bcdec043(first round is sha-512)
79a324faeebcbf9849f310545ed531556882487e (with ripemd-160)

== Common structures ==

All integers are encoded in big endian. (This is different from Bitcoin).

=== Message structure ===

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown
|-
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)
|-
| 4 || length || uint32_t || Length of payload in number of bytes. Because of other restrictions, there is no reason why this length would ever be larger than 1600003 bytes. Some clients include a sanity-check to avoid processing messages which are larger than this.
|-
| 4 || checksum || uint32_t || First 4 bytes of sha512(payload)
|-
| ? || message_payload || uchar[] || The actual data, a [[#Message_types|message]] or an [[#object|object]]. Not to be confused with objectPayload.
|}

Known magic values:

{|class="wikitable"
! Magic value !! Sent over wire as
|-
| 0xE9BEB4D9 || E9 BE B4 D9
|}

=== 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 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.

{|class="wikitable"
! Value !! Storage length !! Format
|-
| < 0xfd || 1 || uint8_t
|-
| <= 0xffff || 3 || 0xfd followed by the integer as uint16_t
|-
| <= 0xffffffff || 5 || 0xfe followed by the integer as uint32_t
|-
| - || 9 || 0xff followed by the integer as uint64_t
|}

=== Variable length string ===

Variable length string can be stored using a variable length integer followed by the string itself.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+ || length || [[Protocol_specification#Variable_length_integer|var_int]] || Length of the string
|-
| ? || string || char[] || The string itself (can be empty)
|}

=== Variable length list of integers===

n integers can be stored using n+1 [[Protocol_specification#Variable_length_integer|variable length integers]] where the first var_int equals n.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+ || count|| [[Protocol_specification#Variable_length_integer|var_int]] || Number of var_ints below
|-
| 1+ || || var_int || The first value stored
|-
| 1+ || || var_int || The second value stored...
|-
| 1+ || || var_int || etc...
|}

=== Network address ===

When a network address is needed somewhere, this structure is used. Network addresses are not prefixed with a timestamp or stream in the version message.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8 || time || uint32 || the Time.
|-
| 4 || stream|| uint32 || Stream number for this node
|-
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]
|-
| 16 || IPv6/4 || char[16] || IPv6 address. IPv4 addresses are written into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).
|-
| 2 || port || uint16_t || port number
|}

=== Inventory Vectors ===

Inventory vectors are used for notifying other nodes about objects they have or data which is being requested. Two rounds of SHA-512 are used, resulting in a 64 byte hash. Only the first 32 bytes are used; the later 32 bytes are ignored.

Inventory vectors consist of the following data format:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 32 || hash || char[32] || Hash of the object
|}

=== Encrypted payload ===

Bitmessage uses [https://en.wikipedia.org/wiki/Integrated_Encryption_Scheme ECIES] to encrypt its messages. For more information see [[Encryption]]

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 16||IV||uchar[]||Initialization Vector used for AES-256-CBC
|-
| 2||uint16_t||Curve type||Elliptic Curve type 0x02CA (714)
|-
| 2||uint16_t||X length||Length of X component of public key R
|-
| X length||uchar[]||X||X component of public key R
|-
| 2||uint16_t||Y length||Length of Y component of public key R
|-
| Y length||uchar[]||Y||Y component of public key R
|-
| ?||encrypted||uchar[]||Cipher text
|-
| 32||MAC|| uchar[]||HMACSHA256 Message Authentication Code
|}

=== Unencrypted Message Data ===

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+||msg_version||var_int||Message format version. This field is not included after the protocol v3 upgrade period.
|-
| 1+||address_version||var_int||Sender's address version number. This is needed in order to calculate the sender's address to show in the UI, and also to allow for forwards compatible changes to the public-key data included below.
|-
| 1+||stream||var_int||Sender's stream number
|-
| 4||behavior bitfield||uint32_t||A bitfield of optional behaviors and features that can be expected from the node with this pubkey included in this msg message (the sender's pubkey).
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|-
| 1+||nonce_trials_per_byte||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is the average number of nonce trials a node will have to perform to meet the Proof of Work requirement. 1000 is the network minimum so any lower values will be automatically raised to 1000. '''This field is new and is only included when the address_version >= 3.'''
|-
| 1+||extra_bytes||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is added to the data length to make sending small messages more difficult. 1000 is the network minimum so any lower values will be automatically raised to 1000. '''This field is new and is only included when the address_version >= 3.'''
|-
| 20||destination ripe||uchar[]||The ripe hash of the public key of the receiver of the message
|-
| 1+||encoding||var_int||[[Protocol_specification#Message_Encodings|Message Encoding]] type
|-
| 1+||message_length||var_int||Message Length
|-
| message_length||message||uchar[]||The message.
|-
| 1+||ack_length||var_int||Length of the acknowledgement data
|-
| ack_length||ack_data||uchar[]||The acknowledgement data to be transmitted. This takes the form of a Bitmessage protocol message, like another msg message. The POW therein must already be completed.
|-
| 1+||sig_length||var_int||Length of the signature
|-
| sig_length||signature||uchar[]||The ECDSA signature which covers everything from the msg_version to the ack_data.
|}

====Message Encodings====
{|class="wikitable"
! Value !! Name !! Description
|-
| 0 || IGNORE || Any data with this number may be ignored. The sending node might simply be sharing its public key with you.
|-
| 1 || TRIVIAL|| UTF-8. No 'Subject' or 'Body' sections. Useful for simple strings of data, like URIs or magnet links.
|-
| 2 || SIMPLE || UTF-8. Uses 'Subject' and 'Body' sections. No MIME is used.
<code>messageToTransmit = 'Subject:' + subject + '\n' + 'Body:' + message</code>
|}

Further values for the message encodings can be decided upon by the community. Any MIME or MIME-like encoding format, should they be used, should make use of Bitmessage's 8-bit bytes.

====Pubkey bitfield features====
{|class="wikitable"
! Bit!! Name !! Description
|-
| 0 || undefined || The most significant bit at the beginning of the structure. Undefined
|-
| 1 || undefined || The next most significant bit. Undefined
|-
| ... || ... || ...
|-
| 30 || include_destination || Receiving node expects that the RIPE hash encoded in their address preceedes the encrypted message data of msg messages bound for them.
|-
| 31 || does_ack|| If true, the receiving node does send acknowledgements (rather than dropping them).
|}

== 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.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || int32_t || Identifies protocol version being used by the node. Should equal 3. Nodes should disconnect if the remote node's version is lower but continue with the connection if it is higher.
|-
| 8 || services || uint64_t || bitfield of features to be enabled for this connection
|-
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds
|-
| 26 || addr_recv || net_addr || The network address of the node receiving this message (not including the time or stream number)
|-
| 26 || addr_from || net_addr || The network address of the node emitting this message (not including the time or stream number and the ip itself is ignored by the receiver)
|-
| 8 || nonce || uint64_t || Random nonce used to detect connections to self.
|-
| 1+ || user_agent || [[#Variable length string|var_str]] || [[User Agent]] (0x00 if string is 0 bytes long). Sending nodes must not include a user_agent longer than 5000 bytes.
|-
| 1+ || stream_numbers || [[#Variable length list of integers|var_int_list]] || The stream numbers that the emitting node is interested in. Sending nodes must not include more than 160000 stream numbers.
|}

A "verack" packet shall be sent if the version packet was accepted. Once you have sent and received a verack messages with the remote node, send an addr message advertising up to 1000 peers of which you are aware, and one or more inv messages advertising all of the valid objects of which you are aware.

The following services are currently assigned:

{|class="wikitable"
! Value !! Name !! Description
|-
| 1 || NODE_NETWORK || This is a normal network node.
|}

=== verack ===

The ''verack'' message is sent in reply to ''version''. This message consists of only a [[#Message structure|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.

=== addr ===

Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours

Payload:
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+ || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of address entries (max: 1000)
|-
| 38 || addr_list || [[Protocol_specification#Network_address|net_addr]] || Address of other nodes on the network.
|}

=== inv ===

Allows a node to advertise its knowledge of one or more objects.
Payload (maximum payload length: 50000 items):

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of inventory entries
|-
| 32x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors
|}

=== 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):

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of inventory entries
|-
| 32x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors
|}

=== 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|Proof Of Work]] must be done. The maximum allowable length of an object (not to be confused with the objectPayload) is 218 bytes.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8||nonce||uint64_t||
Random nonce used for the [[Proof of work|Proof Of Work]]
|-
| 8||expiresTime||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 shared with peers until its end-of-life time has been reached. The node should store the inventory vector of that object for some extra period of time to avoid reloading it from another node with a small time delay. The time may be no further than 28 days + 3 hours in the future.
|-
| 4||objectType||uint32_t||
Four values are currently defined: 0-"getpubkey", 1-"pubkey", 2-"msg", 3-"broadcast". All other values are reserved. Nodes should relay objects even if they use an undefined object type.
|-
| 1+||version||var_int||The object's version. Note that msg objects won't contain a version until Sun, 16 Nov 2014 22:00:00 GMT.
|-
| 1+||stream number||var_int||The stream number in which this object may propagate
|-
| ?||objectPayload||uchar[]||
This field varies depending on the object type; see below.
|-
|}

== 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.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 20||ripe||uchar[]||The ripemd hash of the public key. This field is only included when the address version is <= 3.
|-
| 32||tag||uchar[]||The tag derived from the address version, stream number, and ripe. This field is only included when the address version is >= 4.
|}

=== pubkey ===

A version 2 pubkey. This is still in use and supported by current clients but ''new'' v2 addresses are not generated by clients.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4||[[Protocol_specification#Pubkey_bitfield_features|behavior bitfield]]||uint32_t||A bitfield of optional behaviors and features that can be expected from the node receiving the message.
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|}

A version 3 pubkey

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4||[[Protocol_specification#Pubkey_bitfield_features|behavior bitfield]]||uint32_t||A bitfield of optional behaviors and features that can be expected from the node receiving the message.
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|-
| 1+||nonce_trials_per_byte||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is the average number of nonce trials a node will have to perform to meet the Proof of Work requirement. 1000 is the network minimum so any lower values will be automatically raised to 1000.
|-
| 1+||extra_bytes||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is added to the data length to make sending small messages more difficult. 1000 is the network minimum so any lower values will be automatically raised to 1000.
|-
| 1+||sig_length||var_int||Length of the signature
|-
| sig_length||signature||uchar[]||The ECDSA signature which, as of protocol v3, covers the object header starting with the time, appended with the data described in this table down to the extra_bytes.
|}

A version 4 pubkey

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 32||tag||uchar[]||The tag, made up of bytes 32-64 of the double hash of the address data (see example python code below)
|-
| ?||encrypted||uchar[]||Encrypted pubkey data.
|-
|}

When version 4 pubkeys are created, most of the data in the pubkey is encrypted. This is done in such a way that only someone who has the Bitmessage address which corresponds to a pubkey can decrypt and use that pubkey. This prevents people from gathering pubkeys sent around the network and using the data from them to create messages to be used in spam or in flooding attacks.

In order to encrypt the pubkey data, a double SHA-512 hash is calculated from the address version number, stream number, and ripe hash of the Bitmessage address that the pubkey corresponds to. The first 32 bytes of this hash are used to create a public and private key pair with which to encrypt and decrypt the pubkey data, using the same algorithm as message encryption (see [[Encryption]]). The remaining 32 bytes of this hash are added to the unencrypted part of the pubkey and used as a tag, as above. This allows nodes to determine which pubkey to decrypt when they wish to send a message.

In PyBitmessage, the double hash of the address data is calculated using the python code below:

doubleHashOfAddressData = hashlib.sha512(hashlib.sha512(encodeVarint(addressVersionNumber) + encodeVarint(streamNumber) + hash).digest()).digest()

Encrypted data in version 4 pubkeys:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
|-
| 4||[[Protocol_specification#Pubkey_bitfield_features|behavior bitfield]]||uint32_t||A bitfield of optional behaviors and features that can be expected from the node receiving the message.
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|-
| 1+||nonce_trials_per_byte||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is the average number of nonce trials a node will have to perform to meet the Proof of Work requirement. 1000 is the network minimum so any lower values will be automatically raised to 1000.
|-
| 1+||extra_bytes||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is added to the data length to make sending small messages more difficult. 1000 is the network minimum so any lower values will be automatically raised to 1000.
|-
| 1+||sig_length||var_int||Length of the signature
|-
| sig_length||signature||uchar[]||The ECDSA signature which covers everything from the object header starting with the time, then appended with the decrypted data down to the extra_bytes. This was changed in protocol v3. 
|}

=== 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.
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ?||encrypted||uchar[]||Encrypted data. See [[Protocol_specification#Encrypted_payload|Encrypted payload]]. See also [[Protocol_specification#Unencrypted_Message_Data|Unencrypted Message Data Format]]
|}

=== 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.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 32 || tag|| uchar[]||The tag. This field is new and only included when the broadcast version is >= 5. Changed in protocol v3
|-
| ?||encrypted||uchar[]||Encrypted broadcast data. The keys are derived as described in the paragraph above. See [[Protocol_specification#Encrypted_payload|Encrypted payload]] for details about the encryption algorithm itself.
|}

Unencrypted data format:
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+|| broadcast version|| var_int||The version number of this broadcast protocol message which is equal to 2 or 3. This is included here so that it can be signed. This is no longer included in protocol v3
|-
| 1+ || address version|| var_int||The sender's address version
|-
| 1+ || stream number|| var_int||The sender's stream number
|-
| 4||[[Protocol_specification#Pubkey_bitfield_features|behavior bitfield]]||uint32_t||A bitfield of optional behaviors and features that can be expected from the owner of this pubkey.
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|-
| 1+||nonce_trials_per_byte||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is the average number of nonce trials a node will have to perform to meet the Proof of Work requirement. 1000 is the network minimum so any lower values will be automatically raised to 1000. This field is new and is only included when the address_version >= 3.
|-
| 1+||extra_bytes||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is added to the data length to make sending small messages more difficult. 1000 is the network minimum so any lower values will be automatically raised to 1000. This field is new and is only included when the address_version >= 3.
|-
| 1+ || [[Protocol_specification#Message_Encodings|encoding]]|| var_int||The [[Protocol_specification#Message_Encodings|encoding type]] of the message
|-
| 1+ ||messageLength || var_int||The message length in bytes
|-
| messageLength || message||uchar[] ||The message
|-
| 1+||sig_length||var_int||Length of the signature
|-
| sig_length|| signature||uchar[] ||The signature which did cover the unencrypted data from the broadcast version down through the message. In protocol v3, it covers the unencrypted object header starting with the time, all appended with the decrypted data.
|}

Protocol specification

2015-01-21T19:57:19Z

Atheros: /* Message structure */ Mistake fix: There is no explicit message length limit.

All objects sent on the network should support protocol v3 starting on Sun, 16 Nov 2014 22:00:00 GMT. 

==Common standards==

=== Hashes ===

Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-512] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when creating an address.

A double-round of SHA-512 is used for the Proof Of Work. Example of double-SHA-512 encoding of string "hello":

hello
9b71d224bd62f3785d96d46ad3ea3d73319bfbc2890caadae2dff72519673ca72323c3d99ba5c11d7c7acc6e14b8c5da0c4663475c2e5c3adef46f73bcdec043(first round of sha-512)
0592a10584ffabf96539f3d780d776828c67da1ab5b169e9e8aed838aaecc9ed36d49ff1423c55f019e050c66c6324f53588be88894fef4dcffdb74b98e2b200(second round of sha-512)

For Bitmessage addresses (RIPEMD-160) this would give:

hello
9b71d224bd62f3785d96d46ad3ea3d73319bfbc2890caadae2dff72519673ca72323c3d99ba5c11d7c7acc6e14b8c5da0c4663475c2e5c3adef46f73bcdec043(first round is sha-512)
79a324faeebcbf9849f310545ed531556882487e (with ripemd-160)

== Common structures ==

All integers are encoded in big endian. (This is different from Bitcoin).

=== Message structure ===

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown
|-
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)
|-
| 4 || length || uint32_t || Length of payload in number of bytes. Because of other restrictions, there is no reason why this length would ever be larger than 1600003 bytes. Some clients include a sanity-check to avoid processing messages which are larger than this.
|-
| 4 || checksum || uint32_t || First 4 bytes of sha512(payload)
|-
| ? || message_payload || uchar[] || The actual data, a [[#Message_types|message]] or an [[#object|object]]. Not to be confused with objectPayload.
|}

Known magic values:

{|class="wikitable"
! Magic value !! Sent over wire as
|-
| 0xE9BEB4D9 || E9 BE B4 D9
|}

=== 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 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.

{|class="wikitable"
! Value !! Storage length !! Format
|-
| < 0xfd || 1 || uint8_t
|-
| <= 0xffff || 3 || 0xfd followed by the integer as uint16_t
|-
| <= 0xffffffff || 5 || 0xfe followed by the integer as uint32_t
|-
| - || 9 || 0xff followed by the integer as uint64_t
|}

=== Variable length string ===

Variable length string can be stored using a variable length integer followed by the string itself.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+ || length || [[Protocol_specification#Variable_length_integer|var_int]] || Length of the string
|-
| ? || string || char[] || The string itself (can be empty)
|}

=== Variable length list of integers===

n integers can be stored using n+1 [[Protocol_specification#Variable_length_integer|variable length integers]] where the first var_int equals n.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+ || count|| [[Protocol_specification#Variable_length_integer|var_int]] || Number of var_ints below
|-
| 1+ || || var_int || The first value stored
|-
| 1+ || || var_int || The second value stored...
|-
| 1+ || || var_int || etc...
|}

=== Network address ===

When a network address is needed somewhere, this structure is used. Network addresses are not prefixed with a timestamp or stream in the version message.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8 || time || uint32 || the Time.
|-
| 4 || stream|| uint32 || Stream number for this node
|-
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]
|-
| 16 || IPv6/4 || char[16] || IPv6 address. IPv4 addresses are written into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).
|-
| 2 || port || uint16_t || port number
|}

=== Inventory Vectors ===

Inventory vectors are used for notifying other nodes about objects they have or data which is being requested. Two rounds of SHA-512 are used, resulting in a 64 byte hash. Only the first 32 bytes are used; the later 32 bytes are ignored.

Inventory vectors consist of the following data format:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 32 || hash || char[32] || Hash of the object
|}

=== Encrypted payload ===

Bitmessage uses [https://en.wikipedia.org/wiki/Integrated_Encryption_Scheme ECIES] to encrypt its messages. For more information see [[Encryption]]

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 16||IV||uchar[]||Initialization Vector used for AES-256-CBC
|-
| 2||uint16_t||Curve type||Elliptic Curve type 0x02CA (714)
|-
| 2||uint16_t||X length||Length of X component of public key R
|-
| X length||uchar[]||X||X component of public key R
|-
| 2||uint16_t||Y length||Length of Y component of public key R
|-
| Y length||uchar[]||Y||Y component of public key R
|-
| ?||encrypted||uchar[]||Cipher text
|-
| 32||MAC|| uchar[]||HMACSHA256 Message Authentication Code
|}

=== Unencrypted Message Data ===

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+||msg_version||var_int||Message format version. This field is not included after the protocol v3 upgrade period.
|-
| 1+||address_version||var_int||Sender's address version number. This is needed in order to calculate the sender's address to show in the UI, and also to allow for forwards compatible changes to the public-key data included below.
|-
| 1+||stream||var_int||Sender's stream number
|-
| 4||behavior bitfield||uint32_t||A bitfield of optional behaviors and features that can be expected from the node with this pubkey included in this msg message (the sender's pubkey).
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|-
| 1+||nonce_trials_per_byte||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is the average number of nonce trials a node will have to perform to meet the Proof of Work requirement. 1000 is the network minimum so any lower values will be automatically raised to 1000. '''This field is new and is only included when the address_version >= 3.'''
|-
| 1+||extra_bytes||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is added to the data length to make sending small messages more difficult. 1000 is the network minimum so any lower values will be automatically raised to 1000. '''This field is new and is only included when the address_version >= 3.'''
|-
| 20||destination ripe||uchar[]||The ripe hash of the public key of the receiver of the message
|-
| 1+||encoding||var_int||[[Protocol_specification#Message_Encodings|Message Encoding]] type
|-
| 1+||message_length||var_int||Message Length
|-
| message_length||message||uchar[]||The message.
|-
| 1+||ack_length||var_int||Length of the acknowledgement data
|-
| ack_length||ack_data||uchar[]||The acknowledgement data to be transmitted. This takes the form of a Bitmessage protocol message, like another msg message. The POW therein must already be completed.
|-
| 1+||sig_length||var_int||Length of the signature
|-
| sig_length||signature||uchar[]||The ECDSA signature which covers everything from the msg_version to the ack_data.
|}

====Message Encodings====
{|class="wikitable"
! Value !! Name !! Description
|-
| 0 || IGNORE || Any data with this number may be ignored. The sending node might simply be sharing its public key with you.
|-
| 1 || TRIVIAL|| UTF-8. No 'Subject' or 'Body' sections. Useful for simple strings of data, like URIs or magnet links.
|-
| 2 || SIMPLE || UTF-8. Uses 'Subject' and 'Body' sections. No MIME is used.
<code>messageToTransmit = 'Subject:' + subject + '\n' + 'Body:' + message</code>
|}

Further values for the message encodings can be decided upon by the community. Any MIME or MIME-like encoding format, should they be used, should make use of Bitmessage's 8-bit bytes.

====Pubkey bitfield features====
{|class="wikitable"
! Bit!! Name !! Description
|-
| 0 || undefined || The most significant bit at the beginning of the structure. Undefined
|-
| 1 || undefined || The next most significant bit. Undefined
|-
| ... || ... || ...
|-
| 30 || include_destination || Receiving node expects that the RIPE hash encoded in their address preceedes the encrypted message data of msg messages bound for them.
|-
| 31 || does_ack|| If true, the receiving node does send acknowledgements (rather than dropping them).
|}

== 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.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || int32_t || Identifies protocol version being used by the node. Should equal 3. Nodes should disconnect if the remote node's version is lower but continue with the connection if it is higher.
|-
| 8 || services || uint64_t || bitfield of features to be enabled for this connection
|-
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds
|-
| 26 || addr_recv || net_addr || The network address of the node receiving this message (not including the time or stream number)
|-
| 26 || addr_from || net_addr || The network address of the node emitting this message (not including the time or stream number and the ip itself is ignored by the receiver)
|-
| 8 || nonce || uint64_t || Random nonce used to detect connections to self.
|-
| 1+ || user_agent || [[#Variable length string|var_str]] || [[User Agent]] (0x00 if string is 0 bytes long)
|-
| 1+ || stream numbers || [[#Variable length list of integers|var_int_list]] || The stream numbers that the emitting node is interested in.
|}

A "verack" packet shall be sent if the version packet was accepted. Once you have sent and received a verack messages with the remote node, send an addr message advertising up to 1000 peers of which you are aware, and one or more inv messages advertising all of the valid objects of which you are aware.

The following services are currently assigned:

{|class="wikitable"
! Value !! Name !! Description
|-
| 1 || NODE_NETWORK || This is a normal network node.
|}

=== verack ===

The ''verack'' message is sent in reply to ''version''. This message consists of only a [[#Message structure|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.

=== addr ===

Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours

Payload:
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+ || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of address entries (max: 1000)
|-
| 38 || addr_list || [[Protocol_specification#Network_address|net_addr]] || Address of other nodes on the network.
|}

=== inv ===

Allows a node to advertise its knowledge of one or more objects.
Payload (maximum payload length: 50000 items):

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of inventory entries
|-
| 32x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors
|}

=== 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):

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of inventory entries
|-
| 32x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors
|}

=== 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|Proof Of Work]] must be done. The maximum allowable length of an object (not to be confused with the objectPayload) is 218 bytes.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8||nonce||uint64_t||
Random nonce used for the [[Proof of work|Proof Of Work]]
|-
| 8||expiresTime||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 shared with peers until its end-of-life time has been reached. The node should store the inventory vector of that object for some extra period of time to avoid reloading it from another node with a small time delay. The time may be no further than 28 days + 3 hours in the future.
|-
| 4||objectType||uint32_t||
Four values are currently defined: 0-"getpubkey", 1-"pubkey", 2-"msg", 3-"broadcast". All other values are reserved. Nodes should relay objects even if they use an undefined object type.
|-
| 1+||version||var_int||The object's version. Note that msg objects won't contain a version until Sun, 16 Nov 2014 22:00:00 GMT.
|-
| 1+||stream number||var_int||The stream number in which this object may propagate
|-
| ?||objectPayload||uchar[]||
This field varies depending on the object type; see below.
|-
|}

== 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.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 20||ripe||uchar[]||The ripemd hash of the public key. This field is only included when the address version is <= 3.
|-
| 32||tag||uchar[]||The tag derived from the address version, stream number, and ripe. This field is only included when the address version is >= 4.
|}

=== pubkey ===

A version 2 pubkey. This is still in use and supported by current clients but ''new'' v2 addresses are not generated by clients.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4||[[Protocol_specification#Pubkey_bitfield_features|behavior bitfield]]||uint32_t||A bitfield of optional behaviors and features that can be expected from the node receiving the message.
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|}

A version 3 pubkey

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4||[[Protocol_specification#Pubkey_bitfield_features|behavior bitfield]]||uint32_t||A bitfield of optional behaviors and features that can be expected from the node receiving the message.
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|-
| 1+||nonce_trials_per_byte||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is the average number of nonce trials a node will have to perform to meet the Proof of Work requirement. 1000 is the network minimum so any lower values will be automatically raised to 1000.
|-
| 1+||extra_bytes||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is added to the data length to make sending small messages more difficult. 1000 is the network minimum so any lower values will be automatically raised to 1000.
|-
| 1+||sig_length||var_int||Length of the signature
|-
| sig_length||signature||uchar[]||The ECDSA signature which, as of protocol v3, covers the object header starting with the time, appended with the data described in this table down to the extra_bytes.
|}

A version 4 pubkey

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 32||tag||uchar[]||The tag, made up of bytes 32-64 of the double hash of the address data (see example python code below)
|-
| ?||encrypted||uchar[]||Encrypted pubkey data.
|-
|}

When version 4 pubkeys are created, most of the data in the pubkey is encrypted. This is done in such a way that only someone who has the Bitmessage address which corresponds to a pubkey can decrypt and use that pubkey. This prevents people from gathering pubkeys sent around the network and using the data from them to create messages to be used in spam or in flooding attacks.

In order to encrypt the pubkey data, a double SHA-512 hash is calculated from the address version number, stream number, and ripe hash of the Bitmessage address that the pubkey corresponds to. The first 32 bytes of this hash are used to create a public and private key pair with which to encrypt and decrypt the pubkey data, using the same algorithm as message encryption (see [[Encryption]]). The remaining 32 bytes of this hash are added to the unencrypted part of the pubkey and used as a tag, as above. This allows nodes to determine which pubkey to decrypt when they wish to send a message.

In PyBitmessage, the double hash of the address data is calculated using the python code below:

doubleHashOfAddressData = hashlib.sha512(hashlib.sha512(encodeVarint(addressVersionNumber) + encodeVarint(streamNumber) + hash).digest()).digest()

Encrypted data in version 4 pubkeys:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
|-
| 4||[[Protocol_specification#Pubkey_bitfield_features|behavior bitfield]]||uint32_t||A bitfield of optional behaviors and features that can be expected from the node receiving the message.
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|-
| 1+||nonce_trials_per_byte||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is the average number of nonce trials a node will have to perform to meet the Proof of Work requirement. 1000 is the network minimum so any lower values will be automatically raised to 1000.
|-
| 1+||extra_bytes||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is added to the data length to make sending small messages more difficult. 1000 is the network minimum so any lower values will be automatically raised to 1000.
|-
| 1+||sig_length||var_int||Length of the signature
|-
| sig_length||signature||uchar[]||The ECDSA signature which covers everything from the object header starting with the time, then appended with the decrypted data down to the extra_bytes. This was changed in protocol v3. 
|}

=== 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.
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ?||encrypted||uchar[]||Encrypted data. See [[Protocol_specification#Encrypted_payload|Encrypted payload]]. See also [[Protocol_specification#Unencrypted_Message_Data|Unencrypted Message Data Format]]
|}

=== 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.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 32 || tag|| uchar[]||The tag. This field is new and only included when the broadcast version is >= 5. Changed in protocol v3
|-
| ?||encrypted||uchar[]||Encrypted broadcast data. The keys are derived as described in the paragraph above. See [[Protocol_specification#Encrypted_payload|Encrypted payload]] for details about the encryption algorithm itself.
|}

Unencrypted data format:
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+|| broadcast version|| var_int||The version number of this broadcast protocol message which is equal to 2 or 3. This is included here so that it can be signed. This is no longer included in protocol v3
|-
| 1+ || address version|| var_int||The sender's address version
|-
| 1+ || stream number|| var_int||The sender's stream number
|-
| 4||[[Protocol_specification#Pubkey_bitfield_features|behavior bitfield]]||uint32_t||A bitfield of optional behaviors and features that can be expected from the owner of this pubkey.
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|-
| 1+||nonce_trials_per_byte||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is the average number of nonce trials a node will have to perform to meet the Proof of Work requirement. 1000 is the network minimum so any lower values will be automatically raised to 1000. This field is new and is only included when the address_version >= 3.
|-
| 1+||extra_bytes||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is added to the data length to make sending small messages more difficult. 1000 is the network minimum so any lower values will be automatically raised to 1000. This field is new and is only included when the address_version >= 3.
|-
| 1+ || [[Protocol_specification#Message_Encodings|encoding]]|| var_int||The [[Protocol_specification#Message_Encodings|encoding type]] of the message
|-
| 1+ ||messageLength || var_int||The message length in bytes
|-
| messageLength || message||uchar[] ||The message
|-
| 1+||sig_length||var_int||Length of the signature
|-
| sig_length|| signature||uchar[] ||The signature which did cover the unencrypted data from the broadcast version down through the message. In protocol v3, it covers the unencrypted object header starting with the time, all appended with the decrypted data.
|}

Protocol specification

2015-01-21T19:40:50Z

Atheros: net_addr is always 38 bytes now.

All objects sent on the network should support protocol v3 starting on Sun, 16 Nov 2014 22:00:00 GMT. 

==Common standards==

=== Hashes ===

Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-512] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when creating an address.

A double-round of SHA-512 is used for the Proof Of Work. Example of double-SHA-512 encoding of string "hello":

hello
9b71d224bd62f3785d96d46ad3ea3d73319bfbc2890caadae2dff72519673ca72323c3d99ba5c11d7c7acc6e14b8c5da0c4663475c2e5c3adef46f73bcdec043(first round of sha-512)
0592a10584ffabf96539f3d780d776828c67da1ab5b169e9e8aed838aaecc9ed36d49ff1423c55f019e050c66c6324f53588be88894fef4dcffdb74b98e2b200(second round of sha-512)

For Bitmessage addresses (RIPEMD-160) this would give:

hello
9b71d224bd62f3785d96d46ad3ea3d73319bfbc2890caadae2dff72519673ca72323c3d99ba5c11d7c7acc6e14b8c5da0c4663475c2e5c3adef46f73bcdec043(first round is sha-512)
79a324faeebcbf9849f310545ed531556882487e (with ripemd-160)

== Common structures ==

All integers are encoded in big endian. (This is different from Bitcoin).

=== Message structure ===

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown
|-
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)
|-
| 4 || length || uint32_t || Length of payload in number of bytes. The length may not exceed 2^18 bytes. Longer messages must be ignored.
|-
| 4 || checksum || uint32_t || First 4 bytes of sha512(payload)
|-
| ? || message_payload || uchar[] || The actual data, a [[#Message_types|message]] or an [[#object|object]]. Not to be confused with objectPayload.
|}

Known magic values:

{|class="wikitable"
! Magic value !! Sent over wire as
|-
| 0xE9BEB4D9 || E9 BE B4 D9
|}

=== 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 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.

{|class="wikitable"
! Value !! Storage length !! Format
|-
| < 0xfd || 1 || uint8_t
|-
| <= 0xffff || 3 || 0xfd followed by the integer as uint16_t
|-
| <= 0xffffffff || 5 || 0xfe followed by the integer as uint32_t
|-
| - || 9 || 0xff followed by the integer as uint64_t
|}

=== Variable length string ===

Variable length string can be stored using a variable length integer followed by the string itself.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+ || length || [[Protocol_specification#Variable_length_integer|var_int]] || Length of the string
|-
| ? || string || char[] || The string itself (can be empty)
|}

=== Variable length list of integers===

n integers can be stored using n+1 [[Protocol_specification#Variable_length_integer|variable length integers]] where the first var_int equals n.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+ || count|| [[Protocol_specification#Variable_length_integer|var_int]] || Number of var_ints below
|-
| 1+ || || var_int || The first value stored
|-
| 1+ || || var_int || The second value stored...
|-
| 1+ || || var_int || etc...
|}

=== Network address ===

When a network address is needed somewhere, this structure is used. Network addresses are not prefixed with a timestamp or stream in the version message.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8 || time || uint32 || the Time.
|-
| 4 || stream|| uint32 || Stream number for this node
|-
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]
|-
| 16 || IPv6/4 || char[16] || IPv6 address. IPv4 addresses are written into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).
|-
| 2 || port || uint16_t || port number
|}

=== Inventory Vectors ===

Inventory vectors are used for notifying other nodes about objects they have or data which is being requested. Two rounds of SHA-512 are used, resulting in a 64 byte hash. Only the first 32 bytes are used; the later 32 bytes are ignored.

Inventory vectors consist of the following data format:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 32 || hash || char[32] || Hash of the object
|}

=== Encrypted payload ===

Bitmessage uses [https://en.wikipedia.org/wiki/Integrated_Encryption_Scheme ECIES] to encrypt its messages. For more information see [[Encryption]]

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 16||IV||uchar[]||Initialization Vector used for AES-256-CBC
|-
| 2||uint16_t||Curve type||Elliptic Curve type 0x02CA (714)
|-
| 2||uint16_t||X length||Length of X component of public key R
|-
| X length||uchar[]||X||X component of public key R
|-
| 2||uint16_t||Y length||Length of Y component of public key R
|-
| Y length||uchar[]||Y||Y component of public key R
|-
| ?||encrypted||uchar[]||Cipher text
|-
| 32||MAC|| uchar[]||HMACSHA256 Message Authentication Code
|}

=== Unencrypted Message Data ===

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+||msg_version||var_int||Message format version. This field is not included after the protocol v3 upgrade period.
|-
| 1+||address_version||var_int||Sender's address version number. This is needed in order to calculate the sender's address to show in the UI, and also to allow for forwards compatible changes to the public-key data included below.
|-
| 1+||stream||var_int||Sender's stream number
|-
| 4||behavior bitfield||uint32_t||A bitfield of optional behaviors and features that can be expected from the node with this pubkey included in this msg message (the sender's pubkey).
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|-
| 1+||nonce_trials_per_byte||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is the average number of nonce trials a node will have to perform to meet the Proof of Work requirement. 1000 is the network minimum so any lower values will be automatically raised to 1000. '''This field is new and is only included when the address_version >= 3.'''
|-
| 1+||extra_bytes||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is added to the data length to make sending small messages more difficult. 1000 is the network minimum so any lower values will be automatically raised to 1000. '''This field is new and is only included when the address_version >= 3.'''
|-
| 20||destination ripe||uchar[]||The ripe hash of the public key of the receiver of the message
|-
| 1+||encoding||var_int||[[Protocol_specification#Message_Encodings|Message Encoding]] type
|-
| 1+||message_length||var_int||Message Length
|-
| message_length||message||uchar[]||The message.
|-
| 1+||ack_length||var_int||Length of the acknowledgement data
|-
| ack_length||ack_data||uchar[]||The acknowledgement data to be transmitted. This takes the form of a Bitmessage protocol message, like another msg message. The POW therein must already be completed.
|-
| 1+||sig_length||var_int||Length of the signature
|-
| sig_length||signature||uchar[]||The ECDSA signature which covers everything from the msg_version to the ack_data.
|}

====Message Encodings====
{|class="wikitable"
! Value !! Name !! Description
|-
| 0 || IGNORE || Any data with this number may be ignored. The sending node might simply be sharing its public key with you.
|-
| 1 || TRIVIAL|| UTF-8. No 'Subject' or 'Body' sections. Useful for simple strings of data, like URIs or magnet links.
|-
| 2 || SIMPLE || UTF-8. Uses 'Subject' and 'Body' sections. No MIME is used.
<code>messageToTransmit = 'Subject:' + subject + '\n' + 'Body:' + message</code>
|}

Further values for the message encodings can be decided upon by the community. Any MIME or MIME-like encoding format, should they be used, should make use of Bitmessage's 8-bit bytes.

====Pubkey bitfield features====
{|class="wikitable"
! Bit!! Name !! Description
|-
| 0 || undefined || The most significant bit at the beginning of the structure. Undefined
|-
| 1 || undefined || The next most significant bit. Undefined
|-
| ... || ... || ...
|-
| 30 || include_destination || Receiving node expects that the RIPE hash encoded in their address preceedes the encrypted message data of msg messages bound for them.
|-
| 31 || does_ack|| If true, the receiving node does send acknowledgements (rather than dropping them).
|}

== 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.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || int32_t || Identifies protocol version being used by the node. Should equal 3. Nodes should disconnect if the remote node's version is lower but continue with the connection if it is higher.
|-
| 8 || services || uint64_t || bitfield of features to be enabled for this connection
|-
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds
|-
| 26 || addr_recv || net_addr || The network address of the node receiving this message (not including the time or stream number)
|-
| 26 || addr_from || net_addr || The network address of the node emitting this message (not including the time or stream number and the ip itself is ignored by the receiver)
|-
| 8 || nonce || uint64_t || Random nonce used to detect connections to self.
|-
| 1+ || user_agent || [[#Variable length string|var_str]] || [[User Agent]] (0x00 if string is 0 bytes long)
|-
| 1+ || stream numbers || [[#Variable length list of integers|var_int_list]] || The stream numbers that the emitting node is interested in.
|}

A "verack" packet shall be sent if the version packet was accepted. Once you have sent and received a verack messages with the remote node, send an addr message advertising up to 1000 peers of which you are aware, and one or more inv messages advertising all of the valid objects of which you are aware.

The following services are currently assigned:

{|class="wikitable"
! Value !! Name !! Description
|-
| 1 || NODE_NETWORK || This is a normal network node.
|}

=== verack ===

The ''verack'' message is sent in reply to ''version''. This message consists of only a [[#Message structure|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.

=== addr ===

Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours

Payload:
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+ || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of address entries (max: 1000)
|-
| 38 || addr_list || [[Protocol_specification#Network_address|net_addr]] || Address of other nodes on the network.
|}

=== inv ===

Allows a node to advertise its knowledge of one or more objects.
Payload (maximum payload length: 50000 items):

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of inventory entries
|-
| 32x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors
|}

=== 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):

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of inventory entries
|-
| 32x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors
|}

=== 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|Proof Of Work]] must be done. The maximum allowable length of an object (not to be confused with the objectPayload) is 218 bytes.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8||nonce||uint64_t||
Random nonce used for the [[Proof of work|Proof Of Work]]
|-
| 8||expiresTime||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 shared with peers until its end-of-life time has been reached. The node should store the inventory vector of that object for some extra period of time to avoid reloading it from another node with a small time delay. The time may be no further than 28 days + 3 hours in the future.
|-
| 4||objectType||uint32_t||
Four values are currently defined: 0-"getpubkey", 1-"pubkey", 2-"msg", 3-"broadcast". All other values are reserved. Nodes should relay objects even if they use an undefined object type.
|-
| 1+||version||var_int||The object's version. Note that msg objects won't contain a version until Sun, 16 Nov 2014 22:00:00 GMT.
|-
| 1+||stream number||var_int||The stream number in which this object may propagate
|-
| ?||objectPayload||uchar[]||
This field varies depending on the object type; see below.
|-
|}

== 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.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 20||ripe||uchar[]||The ripemd hash of the public key. This field is only included when the address version is <= 3.
|-
| 32||tag||uchar[]||The tag derived from the address version, stream number, and ripe. This field is only included when the address version is >= 4.
|}

=== pubkey ===

A version 2 pubkey. This is still in use and supported by current clients but ''new'' v2 addresses are not generated by clients.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4||[[Protocol_specification#Pubkey_bitfield_features|behavior bitfield]]||uint32_t||A bitfield of optional behaviors and features that can be expected from the node receiving the message.
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|}

A version 3 pubkey

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4||[[Protocol_specification#Pubkey_bitfield_features|behavior bitfield]]||uint32_t||A bitfield of optional behaviors and features that can be expected from the node receiving the message.
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|-
| 1+||nonce_trials_per_byte||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is the average number of nonce trials a node will have to perform to meet the Proof of Work requirement. 1000 is the network minimum so any lower values will be automatically raised to 1000.
|-
| 1+||extra_bytes||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is added to the data length to make sending small messages more difficult. 1000 is the network minimum so any lower values will be automatically raised to 1000.
|-
| 1+||sig_length||var_int||Length of the signature
|-
| sig_length||signature||uchar[]||The ECDSA signature which, as of protocol v3, covers the object header starting with the time, appended with the data described in this table down to the extra_bytes.
|}

A version 4 pubkey

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 32||tag||uchar[]||The tag, made up of bytes 32-64 of the double hash of the address data (see example python code below)
|-
| ?||encrypted||uchar[]||Encrypted pubkey data.
|-
|}

When version 4 pubkeys are created, most of the data in the pubkey is encrypted. This is done in such a way that only someone who has the Bitmessage address which corresponds to a pubkey can decrypt and use that pubkey. This prevents people from gathering pubkeys sent around the network and using the data from them to create messages to be used in spam or in flooding attacks.

In order to encrypt the pubkey data, a double SHA-512 hash is calculated from the address version number, stream number, and ripe hash of the Bitmessage address that the pubkey corresponds to. The first 32 bytes of this hash are used to create a public and private key pair with which to encrypt and decrypt the pubkey data, using the same algorithm as message encryption (see [[Encryption]]). The remaining 32 bytes of this hash are added to the unencrypted part of the pubkey and used as a tag, as above. This allows nodes to determine which pubkey to decrypt when they wish to send a message.

In PyBitmessage, the double hash of the address data is calculated using the python code below:

doubleHashOfAddressData = hashlib.sha512(hashlib.sha512(encodeVarint(addressVersionNumber) + encodeVarint(streamNumber) + hash).digest()).digest()

Encrypted data in version 4 pubkeys:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
|-
| 4||[[Protocol_specification#Pubkey_bitfield_features|behavior bitfield]]||uint32_t||A bitfield of optional behaviors and features that can be expected from the node receiving the message.
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|-
| 1+||nonce_trials_per_byte||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is the average number of nonce trials a node will have to perform to meet the Proof of Work requirement. 1000 is the network minimum so any lower values will be automatically raised to 1000.
|-
| 1+||extra_bytes||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is added to the data length to make sending small messages more difficult. 1000 is the network minimum so any lower values will be automatically raised to 1000.
|-
| 1+||sig_length||var_int||Length of the signature
|-
| sig_length||signature||uchar[]||The ECDSA signature which covers everything from the object header starting with the time, then appended with the decrypted data down to the extra_bytes. This was changed in protocol v3. 
|}

=== 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.
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ?||encrypted||uchar[]||Encrypted data. See [[Protocol_specification#Encrypted_payload|Encrypted payload]]. See also [[Protocol_specification#Unencrypted_Message_Data|Unencrypted Message Data Format]]
|}

=== 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.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 32 || tag|| uchar[]||The tag. This field is new and only included when the broadcast version is >= 5. Changed in protocol v3
|-
| ?||encrypted||uchar[]||Encrypted broadcast data. The keys are derived as described in the paragraph above. See [[Protocol_specification#Encrypted_payload|Encrypted payload]] for details about the encryption algorithm itself.
|}

Unencrypted data format:
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+|| broadcast version|| var_int||The version number of this broadcast protocol message which is equal to 2 or 3. This is included here so that it can be signed. This is no longer included in protocol v3
|-
| 1+ || address version|| var_int||The sender's address version
|-
| 1+ || stream number|| var_int||The sender's stream number
|-
| 4||[[Protocol_specification#Pubkey_bitfield_features|behavior bitfield]]||uint32_t||A bitfield of optional behaviors and features that can be expected from the owner of this pubkey.
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|-
| 1+||nonce_trials_per_byte||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is the average number of nonce trials a node will have to perform to meet the Proof of Work requirement. 1000 is the network minimum so any lower values will be automatically raised to 1000. This field is new and is only included when the address_version >= 3.
|-
| 1+||extra_bytes||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is added to the data length to make sending small messages more difficult. 1000 is the network minimum so any lower values will be automatically raised to 1000. This field is new and is only included when the address_version >= 3.
|-
| 1+ || [[Protocol_specification#Message_Encodings|encoding]]|| var_int||The [[Protocol_specification#Message_Encodings|encoding type]] of the message
|-
| 1+ ||messageLength || var_int||The message length in bytes
|-
| messageLength || message||uchar[] ||The message
|-
| 1+||sig_length||var_int||Length of the signature
|-
| sig_length|| signature||uchar[] ||The signature which did cover the unencrypted data from the broadcast version down through the message. In protocol v3, it covers the unencrypted object header starting with the time, all appended with the decrypted data.
|}

Protocol specification

2015-01-21T18:05:31Z

Atheros: /* object */

All objects sent on the network should support protocol v3 starting on Sun, 16 Nov 2014 22:00:00 GMT. 

==Common standards==

=== Hashes ===

Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-512] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when creating an address.

A double-round of SHA-512 is used for the Proof Of Work. Example of double-SHA-512 encoding of string "hello":

hello
9b71d224bd62f3785d96d46ad3ea3d73319bfbc2890caadae2dff72519673ca72323c3d99ba5c11d7c7acc6e14b8c5da0c4663475c2e5c3adef46f73bcdec043(first round of sha-512)
0592a10584ffabf96539f3d780d776828c67da1ab5b169e9e8aed838aaecc9ed36d49ff1423c55f019e050c66c6324f53588be88894fef4dcffdb74b98e2b200(second round of sha-512)

For Bitmessage addresses (RIPEMD-160) this would give:

hello
9b71d224bd62f3785d96d46ad3ea3d73319bfbc2890caadae2dff72519673ca72323c3d99ba5c11d7c7acc6e14b8c5da0c4663475c2e5c3adef46f73bcdec043(first round is sha-512)
79a324faeebcbf9849f310545ed531556882487e (with ripemd-160)

== Common structures ==

All integers are encoded in big endian. (This is different from Bitcoin).

=== Message structure ===

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown
|-
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)
|-
| 4 || length || uint32_t || Length of payload in number of bytes. The length may not exceed 2^18 bytes. Longer messages must be ignored.
|-
| 4 || checksum || uint32_t || First 4 bytes of sha512(payload)
|-
| ? || message_payload || uchar[] || The actual data, a [[#Message_types|message]] or an [[#object|object]]. Not to be confused with objectPayload.
|}

Known magic values:

{|class="wikitable"
! Magic value !! Sent over wire as
|-
| 0xE9BEB4D9 || E9 BE B4 D9
|}

=== 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 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.

{|class="wikitable"
! Value !! Storage length !! Format
|-
| < 0xfd || 1 || uint8_t
|-
| <= 0xffff || 3 || 0xfd followed by the integer as uint16_t
|-
| <= 0xffffffff || 5 || 0xfe followed by the integer as uint32_t
|-
| - || 9 || 0xff followed by the integer as uint64_t
|}

=== Variable length string ===

Variable length string can be stored using a variable length integer followed by the string itself.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+ || length || [[Protocol_specification#Variable_length_integer|var_int]] || Length of the string
|-
| ? || string || char[] || The string itself (can be empty)
|}

=== Variable length list of integers===

n integers can be stored using n+1 [[Protocol_specification#Variable_length_integer|variable length integers]] where the first var_int equals n.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+ || count|| [[Protocol_specification#Variable_length_integer|var_int]] || Number of var_ints below
|-
| 1+ || || var_int || The first value stored
|-
| 1+ || || var_int || The second value stored...
|-
| 1+ || || var_int || etc...
|}

=== Network address ===

When a network address is needed somewhere, this structure is used. Network addresses are not prefixed with a timestamp or stream in the version message.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 (or 8)|| time || uint32 || the Time. Protocol version 1 clients use 4 byte time while protocol version 2 clients use 8 byte time.
|-
| 4 || stream|| uint32 || Stream number for this node
|-
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]
|-
| 16 || IPv6/4 || char[16] || IPv6 address. IPv4 addresses are written into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).
|-
| 2 || port || uint16_t || port number
|}

=== Inventory Vectors ===

Inventory vectors are used for notifying other nodes about objects they have or data which is being requested. Two rounds of SHA-512 are used, resulting in a 64 byte hash. Only the first 32 bytes are used; the later 32 bytes are ignored.

Inventory vectors consist of the following data format:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 32 || hash || char[32] || Hash of the object
|}

=== Encrypted payload ===

Bitmessage uses [https://en.wikipedia.org/wiki/Integrated_Encryption_Scheme ECIES] to encrypt its messages. For more information see [[Encryption]]

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 16||IV||uchar[]||Initialization Vector used for AES-256-CBC
|-
| 2||uint16_t||Curve type||Elliptic Curve type 0x02CA (714)
|-
| 2||uint16_t||X length||Length of X component of public key R
|-
| X length||uchar[]||X||X component of public key R
|-
| 2||uint16_t||Y length||Length of Y component of public key R
|-
| Y length||uchar[]||Y||Y component of public key R
|-
| ?||encrypted||uchar[]||Cipher text
|-
| 32||MAC|| uchar[]||HMACSHA256 Message Authentication Code
|}

=== Unencrypted Message Data ===

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+||msg_version||var_int||Message format version. This field is not included after the protocol v3 upgrade period.
|-
| 1+||address_version||var_int||Sender's address version number. This is needed in order to calculate the sender's address to show in the UI, and also to allow for forwards compatible changes to the public-key data included below.
|-
| 1+||stream||var_int||Sender's stream number
|-
| 4||behavior bitfield||uint32_t||A bitfield of optional behaviors and features that can be expected from the node with this pubkey included in this msg message (the sender's pubkey).
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|-
| 1+||nonce_trials_per_byte||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is the average number of nonce trials a node will have to perform to meet the Proof of Work requirement. 1000 is the network minimum so any lower values will be automatically raised to 1000. '''This field is new and is only included when the address_version >= 3.'''
|-
| 1+||extra_bytes||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is added to the data length to make sending small messages more difficult. 1000 is the network minimum so any lower values will be automatically raised to 1000. '''This field is new and is only included when the address_version >= 3.'''
|-
| 20||destination ripe||uchar[]||The ripe hash of the public key of the receiver of the message
|-
| 1+||encoding||var_int||[[Protocol_specification#Message_Encodings|Message Encoding]] type
|-
| 1+||message_length||var_int||Message Length
|-
| message_length||message||uchar[]||The message.
|-
| 1+||ack_length||var_int||Length of the acknowledgement data
|-
| ack_length||ack_data||uchar[]||The acknowledgement data to be transmitted. This takes the form of a Bitmessage protocol message, like another msg message. The POW therein must already be completed.
|-
| 1+||sig_length||var_int||Length of the signature
|-
| sig_length||signature||uchar[]||The ECDSA signature which covers everything from the msg_version to the ack_data.
|}

====Message Encodings====
{|class="wikitable"
! Value !! Name !! Description
|-
| 0 || IGNORE || Any data with this number may be ignored. The sending node might simply be sharing its public key with you.
|-
| 1 || TRIVIAL|| UTF-8. No 'Subject' or 'Body' sections. Useful for simple strings of data, like URIs or magnet links.
|-
| 2 || SIMPLE || UTF-8. Uses 'Subject' and 'Body' sections. No MIME is used.
<code>messageToTransmit = 'Subject:' + subject + '\n' + 'Body:' + message</code>
|}

Further values for the message encodings can be decided upon by the community. Any MIME or MIME-like encoding format, should they be used, should make use of Bitmessage's 8-bit bytes.

====Pubkey bitfield features====
{|class="wikitable"
! Bit!! Name !! Description
|-
| 0 || undefined || The most significant bit at the beginning of the structure. Undefined
|-
| 1 || undefined || The next most significant bit. Undefined
|-
| ... || ... || ...
|-
| 30 || include_destination || Receiving node expects that the RIPE hash encoded in their address preceedes the encrypted message data of msg messages bound for them.
|-
| 31 || does_ack|| If true, the receiving node does send acknowledgements (rather than dropping them).
|}

== 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.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || int32_t || Identifies protocol version being used by the node. Should equal 3. Nodes should disconnect if the remote node's version is lower but continue with the connection if it is higher.
|-
| 8 || services || uint64_t || bitfield of features to be enabled for this connection
|-
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds
|-
| 26 || addr_recv || net_addr || The network address of the node receiving this message (not including the time or stream number)
|-
| 26 || addr_from || net_addr || The network address of the node emitting this message (not including the time or stream number and the ip itself is ignored by the receiver)
|-
| 8 || nonce || uint64_t || Random nonce used to detect connections to self.
|-
| 1+ || user_agent || [[#Variable length string|var_str]] || [[User Agent]] (0x00 if string is 0 bytes long)
|-
| 1+ || stream numbers || [[#Variable length list of integers|var_int_list]] || The stream numbers that the emitting node is interested in.
|}

A "verack" packet shall be sent if the version packet was accepted. Once you have sent and received a verack messages with the remote node, send an addr message advertising up to 1000 peers of which you are aware, and one or more inv messages advertising all of the valid objects of which you are aware.

The following services are currently assigned:

{|class="wikitable"
! Value !! Name !! Description
|-
| 1 || NODE_NETWORK || This is a normal network node.
|}

=== verack ===

The ''verack'' message is sent in reply to ''version''. This message consists of only a [[#Message structure|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.

=== addr ===

Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours

Payload:
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+ || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of address entries (max: 1000)
|-
| 34x? || addr_list || [[Protocol_specification#Network_address|net_addr]] || Address of other nodes on the network.
|}

=== inv ===

Allows a node to advertise its knowledge of one or more objects.
Payload (maximum payload length: 50000 items):

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of inventory entries
|-
| 32x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors
|}

=== 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):

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of inventory entries
|-
| 32x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors
|}

=== 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|Proof Of Work]] must be done. The maximum allowable length of an object (not to be confused with the objectPayload) is 218 bytes.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8||nonce||uint64_t||
Random nonce used for the [[Proof of work|Proof Of Work]]
|-
| 8||expiresTime||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 shared with peers until its end-of-life time has been reached. The node should store the inventory vector of that object for some extra period of time to avoid reloading it from another node with a small time delay. The time may be no further than 28 days + 3 hours in the future.
|-
| 4||objectType||uint32_t||
Four values are currently defined: 0-"getpubkey", 1-"pubkey", 2-"msg", 3-"broadcast". All other values are reserved. Nodes should relay objects even if they use an undefined object type.
|-
| 1+||version||var_int||The object's version. Note that msg objects won't contain a version until Sun, 16 Nov 2014 22:00:00 GMT.
|-
| 1+||stream number||var_int||The stream number in which this object may propagate
|-
| ?||objectPayload||uchar[]||
This field varies depending on the object type; see below.
|-
|}

== 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.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 20||ripe||uchar[]||The ripemd hash of the public key. This field is only included when the address version is <= 3.
|-
| 32||tag||uchar[]||The tag derived from the address version, stream number, and ripe. This field is only included when the address version is >= 4.
|}

=== pubkey ===

A version 2 pubkey. This is still in use and supported by current clients but ''new'' v2 addresses are not generated by clients.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4||[[Protocol_specification#Pubkey_bitfield_features|behavior bitfield]]||uint32_t||A bitfield of optional behaviors and features that can be expected from the node receiving the message.
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|}

A version 3 pubkey

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4||[[Protocol_specification#Pubkey_bitfield_features|behavior bitfield]]||uint32_t||A bitfield of optional behaviors and features that can be expected from the node receiving the message.
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|-
| 1+||nonce_trials_per_byte||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is the average number of nonce trials a node will have to perform to meet the Proof of Work requirement. 1000 is the network minimum so any lower values will be automatically raised to 1000.
|-
| 1+||extra_bytes||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is added to the data length to make sending small messages more difficult. 1000 is the network minimum so any lower values will be automatically raised to 1000.
|-
| 1+||sig_length||var_int||Length of the signature
|-
| sig_length||signature||uchar[]||The ECDSA signature which, as of protocol v3, covers the object header starting with the time, appended with the data described in this table down to the extra_bytes.
|}

A version 4 pubkey

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 32||tag||uchar[]||The tag, made up of bytes 32-64 of the double hash of the address data (see example python code below)
|-
| ?||encrypted||uchar[]||Encrypted pubkey data.
|-
|}

When version 4 pubkeys are created, most of the data in the pubkey is encrypted. This is done in such a way that only someone who has the Bitmessage address which corresponds to a pubkey can decrypt and use that pubkey. This prevents people from gathering pubkeys sent around the network and using the data from them to create messages to be used in spam or in flooding attacks.

In order to encrypt the pubkey data, a double SHA-512 hash is calculated from the address version number, stream number, and ripe hash of the Bitmessage address that the pubkey corresponds to. The first 32 bytes of this hash are used to create a public and private key pair with which to encrypt and decrypt the pubkey data, using the same algorithm as message encryption (see [[Encryption]]). The remaining 32 bytes of this hash are added to the unencrypted part of the pubkey and used as a tag, as above. This allows nodes to determine which pubkey to decrypt when they wish to send a message.

In PyBitmessage, the double hash of the address data is calculated using the python code below:

doubleHashOfAddressData = hashlib.sha512(hashlib.sha512(encodeVarint(addressVersionNumber) + encodeVarint(streamNumber) + hash).digest()).digest()

Encrypted data in version 4 pubkeys:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
|-
| 4||[[Protocol_specification#Pubkey_bitfield_features|behavior bitfield]]||uint32_t||A bitfield of optional behaviors and features that can be expected from the node receiving the message.
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|-
| 1+||nonce_trials_per_byte||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is the average number of nonce trials a node will have to perform to meet the Proof of Work requirement. 1000 is the network minimum so any lower values will be automatically raised to 1000.
|-
| 1+||extra_bytes||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is added to the data length to make sending small messages more difficult. 1000 is the network minimum so any lower values will be automatically raised to 1000.
|-
| 1+||sig_length||var_int||Length of the signature
|-
| sig_length||signature||uchar[]||The ECDSA signature which covers everything from the object header starting with the time, then appended with the decrypted data down to the extra_bytes. This was changed in protocol v3. 
|}

=== 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.
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ?||encrypted||uchar[]||Encrypted data. See [[Protocol_specification#Encrypted_payload|Encrypted payload]]. See also [[Protocol_specification#Unencrypted_Message_Data|Unencrypted Message Data Format]]
|}

=== 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.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 32 || tag|| uchar[]||The tag. This field is new and only included when the broadcast version is >= 5. Changed in protocol v3
|-
| ?||encrypted||uchar[]||Encrypted broadcast data. The keys are derived as described in the paragraph above. See [[Protocol_specification#Encrypted_payload|Encrypted payload]] for details about the encryption algorithm itself.
|}

Unencrypted data format:
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+|| broadcast version|| var_int||The version number of this broadcast protocol message which is equal to 2 or 3. This is included here so that it can be signed. This is no longer included in protocol v3
|-
| 1+ || address version|| var_int||The sender's address version
|-
| 1+ || stream number|| var_int||The sender's stream number
|-
| 4||[[Protocol_specification#Pubkey_bitfield_features|behavior bitfield]]||uint32_t||A bitfield of optional behaviors and features that can be expected from the owner of this pubkey.
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|-
| 1+||nonce_trials_per_byte||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is the average number of nonce trials a node will have to perform to meet the Proof of Work requirement. 1000 is the network minimum so any lower values will be automatically raised to 1000. This field is new and is only included when the address_version >= 3.
|-
| 1+||extra_bytes||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is added to the data length to make sending small messages more difficult. 1000 is the network minimum so any lower values will be automatically raised to 1000. This field is new and is only included when the address_version >= 3.
|-
| 1+ || [[Protocol_specification#Message_Encodings|encoding]]|| var_int||The [[Protocol_specification#Message_Encodings|encoding type]] of the message
|-
| 1+ ||messageLength || var_int||The message length in bytes
|-
| messageLength || message||uchar[] ||The message
|-
| 1+||sig_length||var_int||Length of the signature
|-
| sig_length|| signature||uchar[] ||The signature which did cover the unencrypted data from the broadcast version down through the message. In protocol v3, it covers the unencrypted object header starting with the time, all appended with the decrypted data.
|}

Protocol specification

2015-01-21T18:01:06Z

Atheros:

All objects sent on the network should support protocol v3 starting on Sun, 16 Nov 2014 22:00:00 GMT. 

==Common standards==

=== Hashes ===

Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-512] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when creating an address.

A double-round of SHA-512 is used for the Proof Of Work. Example of double-SHA-512 encoding of string "hello":

hello
9b71d224bd62f3785d96d46ad3ea3d73319bfbc2890caadae2dff72519673ca72323c3d99ba5c11d7c7acc6e14b8c5da0c4663475c2e5c3adef46f73bcdec043(first round of sha-512)
0592a10584ffabf96539f3d780d776828c67da1ab5b169e9e8aed838aaecc9ed36d49ff1423c55f019e050c66c6324f53588be88894fef4dcffdb74b98e2b200(second round of sha-512)

For Bitmessage addresses (RIPEMD-160) this would give:

hello
9b71d224bd62f3785d96d46ad3ea3d73319bfbc2890caadae2dff72519673ca72323c3d99ba5c11d7c7acc6e14b8c5da0c4663475c2e5c3adef46f73bcdec043(first round is sha-512)
79a324faeebcbf9849f310545ed531556882487e (with ripemd-160)

== Common structures ==

All integers are encoded in big endian. (This is different from Bitcoin).

=== Message structure ===

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown
|-
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)
|-
| 4 || length || uint32_t || Length of payload in number of bytes. The length may not exceed 2^18 bytes. Longer messages must be ignored.
|-
| 4 || checksum || uint32_t || First 4 bytes of sha512(payload)
|-
| ? || message_payload || uchar[] || The actual data, a [[#Message_types|message]] or an [[#object|object]]. Not to be confused with objectPayload.
|}

Known magic values:

{|class="wikitable"
! Magic value !! Sent over wire as
|-
| 0xE9BEB4D9 || E9 BE B4 D9
|}

=== 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 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.

{|class="wikitable"
! Value !! Storage length !! Format
|-
| < 0xfd || 1 || uint8_t
|-
| <= 0xffff || 3 || 0xfd followed by the integer as uint16_t
|-
| <= 0xffffffff || 5 || 0xfe followed by the integer as uint32_t
|-
| - || 9 || 0xff followed by the integer as uint64_t
|}

=== Variable length string ===

Variable length string can be stored using a variable length integer followed by the string itself.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+ || length || [[Protocol_specification#Variable_length_integer|var_int]] || Length of the string
|-
| ? || string || char[] || The string itself (can be empty)
|}

=== Variable length list of integers===

n integers can be stored using n+1 [[Protocol_specification#Variable_length_integer|variable length integers]] where the first var_int equals n.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+ || count|| [[Protocol_specification#Variable_length_integer|var_int]] || Number of var_ints below
|-
| 1+ || || var_int || The first value stored
|-
| 1+ || || var_int || The second value stored...
|-
| 1+ || || var_int || etc...
|}

=== Network address ===

When a network address is needed somewhere, this structure is used. Network addresses are not prefixed with a timestamp or stream in the version message.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 (or 8)|| time || uint32 || the Time. Protocol version 1 clients use 4 byte time while protocol version 2 clients use 8 byte time.
|-
| 4 || stream|| uint32 || Stream number for this node
|-
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]
|-
| 16 || IPv6/4 || char[16] || IPv6 address. IPv4 addresses are written into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).
|-
| 2 || port || uint16_t || port number
|}

=== Inventory Vectors ===

Inventory vectors are used for notifying other nodes about objects they have or data which is being requested. Two rounds of SHA-512 are used, resulting in a 64 byte hash. Only the first 32 bytes are used; the later 32 bytes are ignored.

Inventory vectors consist of the following data format:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 32 || hash || char[32] || Hash of the object
|}

=== Encrypted payload ===

Bitmessage uses [https://en.wikipedia.org/wiki/Integrated_Encryption_Scheme ECIES] to encrypt its messages. For more information see [[Encryption]]

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 16||IV||uchar[]||Initialization Vector used for AES-256-CBC
|-
| 2||uint16_t||Curve type||Elliptic Curve type 0x02CA (714)
|-
| 2||uint16_t||X length||Length of X component of public key R
|-
| X length||uchar[]||X||X component of public key R
|-
| 2||uint16_t||Y length||Length of Y component of public key R
|-
| Y length||uchar[]||Y||Y component of public key R
|-
| ?||encrypted||uchar[]||Cipher text
|-
| 32||MAC|| uchar[]||HMACSHA256 Message Authentication Code
|}

=== Unencrypted Message Data ===

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+||msg_version||var_int||Message format version. This field is not included after the protocol v3 upgrade period.
|-
| 1+||address_version||var_int||Sender's address version number. This is needed in order to calculate the sender's address to show in the UI, and also to allow for forwards compatible changes to the public-key data included below.
|-
| 1+||stream||var_int||Sender's stream number
|-
| 4||behavior bitfield||uint32_t||A bitfield of optional behaviors and features that can be expected from the node with this pubkey included in this msg message (the sender's pubkey).
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|-
| 1+||nonce_trials_per_byte||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is the average number of nonce trials a node will have to perform to meet the Proof of Work requirement. 1000 is the network minimum so any lower values will be automatically raised to 1000. '''This field is new and is only included when the address_version >= 3.'''
|-
| 1+||extra_bytes||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is added to the data length to make sending small messages more difficult. 1000 is the network minimum so any lower values will be automatically raised to 1000. '''This field is new and is only included when the address_version >= 3.'''
|-
| 20||destination ripe||uchar[]||The ripe hash of the public key of the receiver of the message
|-
| 1+||encoding||var_int||[[Protocol_specification#Message_Encodings|Message Encoding]] type
|-
| 1+||message_length||var_int||Message Length
|-
| message_length||message||uchar[]||The message.
|-
| 1+||ack_length||var_int||Length of the acknowledgement data
|-
| ack_length||ack_data||uchar[]||The acknowledgement data to be transmitted. This takes the form of a Bitmessage protocol message, like another msg message. The POW therein must already be completed.
|-
| 1+||sig_length||var_int||Length of the signature
|-
| sig_length||signature||uchar[]||The ECDSA signature which covers everything from the msg_version to the ack_data.
|}

====Message Encodings====
{|class="wikitable"
! Value !! Name !! Description
|-
| 0 || IGNORE || Any data with this number may be ignored. The sending node might simply be sharing its public key with you.
|-
| 1 || TRIVIAL|| UTF-8. No 'Subject' or 'Body' sections. Useful for simple strings of data, like URIs or magnet links.
|-
| 2 || SIMPLE || UTF-8. Uses 'Subject' and 'Body' sections. No MIME is used.
<code>messageToTransmit = 'Subject:' + subject + '\n' + 'Body:' + message</code>
|}

Further values for the message encodings can be decided upon by the community. Any MIME or MIME-like encoding format, should they be used, should make use of Bitmessage's 8-bit bytes.

====Pubkey bitfield features====
{|class="wikitable"
! Bit!! Name !! Description
|-
| 0 || undefined || The most significant bit at the beginning of the structure. Undefined
|-
| 1 || undefined || The next most significant bit. Undefined
|-
| ... || ... || ...
|-
| 30 || include_destination || Receiving node expects that the RIPE hash encoded in their address preceedes the encrypted message data of msg messages bound for them.
|-
| 31 || does_ack|| If true, the receiving node does send acknowledgements (rather than dropping them).
|}

== 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.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || int32_t || Identifies protocol version being used by the node. Should equal 3. Nodes should disconnect if the remote node's version is lower but continue with the connection if it is higher.
|-
| 8 || services || uint64_t || bitfield of features to be enabled for this connection
|-
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds
|-
| 26 || addr_recv || net_addr || The network address of the node receiving this message (not including the time or stream number)
|-
| 26 || addr_from || net_addr || The network address of the node emitting this message (not including the time or stream number and the ip itself is ignored by the receiver)
|-
| 8 || nonce || uint64_t || Random nonce used to detect connections to self.
|-
| 1+ || user_agent || [[#Variable length string|var_str]] || [[User Agent]] (0x00 if string is 0 bytes long)
|-
| 1+ || stream numbers || [[#Variable length list of integers|var_int_list]] || The stream numbers that the emitting node is interested in.
|}

A "verack" packet shall be sent if the version packet was accepted. Once you have sent and received a verack messages with the remote node, send an addr message advertising up to 1000 peers of which you are aware, and one or more inv messages advertising all of the valid objects of which you are aware.

The following services are currently assigned:

{|class="wikitable"
! Value !! Name !! Description
|-
| 1 || NODE_NETWORK || This is a normal network node.
|}

=== verack ===

The ''verack'' message is sent in reply to ''version''. This message consists of only a [[#Message structure|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.

=== addr ===

Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours

Payload:
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+ || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of address entries (max: 1000)
|-
| 34x? || addr_list || [[Protocol_specification#Network_address|net_addr]] || Address of other nodes on the network.
|}

=== inv ===

Allows a node to advertise its knowledge of one or more objects.
Payload (maximum payload length: 50000 items):

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of inventory entries
|-
| 32x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors
|}

=== 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):

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of inventory entries
|-
| 32x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors
|}

=== 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|Proof Of Work]] must be done.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8||nonce||uint64_t||
Random nonce used for the [[Proof of work|Proof Of Work]]
|-
| 8||expiresTime||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 shared with peers until its end-of-life time has been reached. The node should store the inventory vector of that object for some extra period of time to avoid reloading it from another node with a small time delay. The time may be no further than 28 days + 3 hours in the future.
|-
| 4||objectType||uint32_t||
Four values are currently defined: 0-"getpubkey", 1-"pubkey", 2-"msg", 3-"broadcast". All other values are reserved. Nodes should relay objects even if they use an undefined object type.
|-
| 1+||version||var_int||The object's version. Note that msg objects won't contain a version until Sun, 16 Nov 2014 22:00:00 GMT.
|-
| 1+||stream number||var_int||The stream number in which this object may propagate
|-
| ?||objectPayload||uchar[]||
This field varies depending on the object type; see below.
|-
|}

== 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.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 20||ripe||uchar[]||The ripemd hash of the public key. This field is only included when the address version is <= 3.
|-
| 32||tag||uchar[]||The tag derived from the address version, stream number, and ripe. This field is only included when the address version is >= 4.
|}

=== pubkey ===

A version 2 pubkey. This is still in use and supported by current clients but ''new'' v2 addresses are not generated by clients.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4||[[Protocol_specification#Pubkey_bitfield_features|behavior bitfield]]||uint32_t||A bitfield of optional behaviors and features that can be expected from the node receiving the message.
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|}

A version 3 pubkey

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4||[[Protocol_specification#Pubkey_bitfield_features|behavior bitfield]]||uint32_t||A bitfield of optional behaviors and features that can be expected from the node receiving the message.
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|-
| 1+||nonce_trials_per_byte||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is the average number of nonce trials a node will have to perform to meet the Proof of Work requirement. 1000 is the network minimum so any lower values will be automatically raised to 1000.
|-
| 1+||extra_bytes||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is added to the data length to make sending small messages more difficult. 1000 is the network minimum so any lower values will be automatically raised to 1000.
|-
| 1+||sig_length||var_int||Length of the signature
|-
| sig_length||signature||uchar[]||The ECDSA signature which, as of protocol v3, covers the object header starting with the time, appended with the data described in this table down to the extra_bytes.
|}

A version 4 pubkey

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 32||tag||uchar[]||The tag, made up of bytes 32-64 of the double hash of the address data (see example python code below)
|-
| ?||encrypted||uchar[]||Encrypted pubkey data.
|-
|}

When version 4 pubkeys are created, most of the data in the pubkey is encrypted. This is done in such a way that only someone who has the Bitmessage address which corresponds to a pubkey can decrypt and use that pubkey. This prevents people from gathering pubkeys sent around the network and using the data from them to create messages to be used in spam or in flooding attacks.

In order to encrypt the pubkey data, a double SHA-512 hash is calculated from the address version number, stream number, and ripe hash of the Bitmessage address that the pubkey corresponds to. The first 32 bytes of this hash are used to create a public and private key pair with which to encrypt and decrypt the pubkey data, using the same algorithm as message encryption (see [[Encryption]]). The remaining 32 bytes of this hash are added to the unencrypted part of the pubkey and used as a tag, as above. This allows nodes to determine which pubkey to decrypt when they wish to send a message.

In PyBitmessage, the double hash of the address data is calculated using the python code below:

doubleHashOfAddressData = hashlib.sha512(hashlib.sha512(encodeVarint(addressVersionNumber) + encodeVarint(streamNumber) + hash).digest()).digest()

Encrypted data in version 4 pubkeys:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
|-
| 4||[[Protocol_specification#Pubkey_bitfield_features|behavior bitfield]]||uint32_t||A bitfield of optional behaviors and features that can be expected from the node receiving the message.
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|-
| 1+||nonce_trials_per_byte||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is the average number of nonce trials a node will have to perform to meet the Proof of Work requirement. 1000 is the network minimum so any lower values will be automatically raised to 1000.
|-
| 1+||extra_bytes||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is added to the data length to make sending small messages more difficult. 1000 is the network minimum so any lower values will be automatically raised to 1000.
|-
| 1+||sig_length||var_int||Length of the signature
|-
| sig_length||signature||uchar[]||The ECDSA signature which covers everything from the object header starting with the time, then appended with the decrypted data down to the extra_bytes. This was changed in protocol v3. 
|}

=== 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.
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ?||encrypted||uchar[]||Encrypted data. See [[Protocol_specification#Encrypted_payload|Encrypted payload]]. See also [[Protocol_specification#Unencrypted_Message_Data|Unencrypted Message Data Format]]
|}

=== 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.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 32 || tag|| uchar[]||The tag. This field is new and only included when the broadcast version is >= 5. Changed in protocol v3
|-
| ?||encrypted||uchar[]||Encrypted broadcast data. The keys are derived as described in the paragraph above. See [[Protocol_specification#Encrypted_payload|Encrypted payload]] for details about the encryption algorithm itself.
|}

Unencrypted data format:
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+|| broadcast version|| var_int||The version number of this broadcast protocol message which is equal to 2 or 3. This is included here so that it can be signed. This is no longer included in protocol v3
|-
| 1+ || address version|| var_int||The sender's address version
|-
| 1+ || stream number|| var_int||The sender's stream number
|-
| 4||[[Protocol_specification#Pubkey_bitfield_features|behavior bitfield]]||uint32_t||A bitfield of optional behaviors and features that can be expected from the owner of this pubkey.
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|-
| 1+||nonce_trials_per_byte||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is the average number of nonce trials a node will have to perform to meet the Proof of Work requirement. 1000 is the network minimum so any lower values will be automatically raised to 1000. This field is new and is only included when the address_version >= 3.
|-
| 1+||extra_bytes||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is added to the data length to make sending small messages more difficult. 1000 is the network minimum so any lower values will be automatically raised to 1000. This field is new and is only included when the address_version >= 3.
|-
| 1+ || [[Protocol_specification#Message_Encodings|encoding]]|| var_int||The [[Protocol_specification#Message_Encodings|encoding type]] of the message
|-
| 1+ ||messageLength || var_int||The message length in bytes
|-
| messageLength || message||uchar[] ||The message
|-
| 1+||sig_length||var_int||Length of the signature
|-
| sig_length|| signature||uchar[] ||The signature which did cover the unencrypted data from the broadcast version down through the message. In protocol v3, it covers the unencrypted object header starting with the time, all appended with the decrypted data.
|}

Protocol specification

2015-01-21T17:59:46Z

Atheros: /* Message structure */

All objects sent on the network should support protocol v3 starting on Sun, 16 Nov 2014 22:00:00 GMT. 

==Common standards==

=== Hashes ===

Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-512] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when creating an address.

A double-round of SHA-512 is used for the Proof Of Work. Example of double-SHA-512 encoding of string "hello":

hello
9b71d224bd62f3785d96d46ad3ea3d73319bfbc2890caadae2dff72519673ca72323c3d99ba5c11d7c7acc6e14b8c5da0c4663475c2e5c3adef46f73bcdec043(first round of sha-512)
0592a10584ffabf96539f3d780d776828c67da1ab5b169e9e8aed838aaecc9ed36d49ff1423c55f019e050c66c6324f53588be88894fef4dcffdb74b98e2b200(second round of sha-512)

For Bitmessage addresses (RIPEMD-160) this would give:

hello
9b71d224bd62f3785d96d46ad3ea3d73319bfbc2890caadae2dff72519673ca72323c3d99ba5c11d7c7acc6e14b8c5da0c4663475c2e5c3adef46f73bcdec043(first round is sha-512)
79a324faeebcbf9849f310545ed531556882487e (with ripemd-160)

== Common structures ==

All integers are encoded in big endian. (This is different from Bitcoin).

=== Message structure ===

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown
|-
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)
|-
| 4 || length || uint32_t || Length of payload in number of bytes. The length may not exceed 2^18 bytes. Longer messages must be ignored.
|-
| 4 || checksum || uint32_t || First 4 bytes of sha512(payload)
|-
| ? || message_payload || uchar[] || The actual data, a [[#Message_types|message]] or an [[#object|object]]. Not to be confused with object_payload.
|}

Known magic values:

{|class="wikitable"
! Magic value !! Sent over wire as
|-
| 0xE9BEB4D9 || E9 BE B4 D9
|}

=== 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 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.

{|class="wikitable"
! Value !! Storage length !! Format
|-
| < 0xfd || 1 || uint8_t
|-
| <= 0xffff || 3 || 0xfd followed by the integer as uint16_t
|-
| <= 0xffffffff || 5 || 0xfe followed by the integer as uint32_t
|-
| - || 9 || 0xff followed by the integer as uint64_t
|}

=== Variable length string ===

Variable length string can be stored using a variable length integer followed by the string itself.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+ || length || [[Protocol_specification#Variable_length_integer|var_int]] || Length of the string
|-
| ? || string || char[] || The string itself (can be empty)
|}

=== Variable length list of integers===

n integers can be stored using n+1 [[Protocol_specification#Variable_length_integer|variable length integers]] where the first var_int equals n.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+ || count|| [[Protocol_specification#Variable_length_integer|var_int]] || Number of var_ints below
|-
| 1+ || || var_int || The first value stored
|-
| 1+ || || var_int || The second value stored...
|-
| 1+ || || var_int || etc...
|}

=== Network address ===

When a network address is needed somewhere, this structure is used. Network addresses are not prefixed with a timestamp or stream in the version message.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 (or 8)|| time || uint32 || the Time. Protocol version 1 clients use 4 byte time while protocol version 2 clients use 8 byte time.
|-
| 4 || stream|| uint32 || Stream number for this node
|-
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]
|-
| 16 || IPv6/4 || char[16] || IPv6 address. IPv4 addresses are written into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).
|-
| 2 || port || uint16_t || port number
|}

=== Inventory Vectors ===

Inventory vectors are used for notifying other nodes about objects they have or data which is being requested. Two rounds of SHA-512 are used, resulting in a 64 byte hash. Only the first 32 bytes are used; the later 32 bytes are ignored.

Inventory vectors consist of the following data format:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 32 || hash || char[32] || Hash of the object
|}

=== Encrypted payload ===

Bitmessage uses [https://en.wikipedia.org/wiki/Integrated_Encryption_Scheme ECIES] to encrypt its messages. For more information see [[Encryption]]

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 16||IV||uchar[]||Initialization Vector used for AES-256-CBC
|-
| 2||uint16_t||Curve type||Elliptic Curve type 0x02CA (714)
|-
| 2||uint16_t||X length||Length of X component of public key R
|-
| X length||uchar[]||X||X component of public key R
|-
| 2||uint16_t||Y length||Length of Y component of public key R
|-
| Y length||uchar[]||Y||Y component of public key R
|-
| ?||encrypted||uchar[]||Cipher text
|-
| 32||MAC|| uchar[]||HMACSHA256 Message Authentication Code
|}

=== Unencrypted Message Data ===

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+||msg_version||var_int||Message format version. This field is not included after the protocol v3 upgrade period.
|-
| 1+||address_version||var_int||Sender's address version number. This is needed in order to calculate the sender's address to show in the UI, and also to allow for forwards compatible changes to the public-key data included below.
|-
| 1+||stream||var_int||Sender's stream number
|-
| 4||behavior bitfield||uint32_t||A bitfield of optional behaviors and features that can be expected from the node with this pubkey included in this msg message (the sender's pubkey).
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|-
| 1+||nonce_trials_per_byte||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is the average number of nonce trials a node will have to perform to meet the Proof of Work requirement. 1000 is the network minimum so any lower values will be automatically raised to 1000. '''This field is new and is only included when the address_version >= 3.'''
|-
| 1+||extra_bytes||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is added to the data length to make sending small messages more difficult. 1000 is the network minimum so any lower values will be automatically raised to 1000. '''This field is new and is only included when the address_version >= 3.'''
|-
| 20||destination ripe||uchar[]||The ripe hash of the public key of the receiver of the message
|-
| 1+||encoding||var_int||[[Protocol_specification#Message_Encodings|Message Encoding]] type
|-
| 1+||message_length||var_int||Message Length
|-
| message_length||message||uchar[]||The message.
|-
| 1+||ack_length||var_int||Length of the acknowledgement data
|-
| ack_length||ack_data||uchar[]||The acknowledgement data to be transmitted. This takes the form of a Bitmessage protocol message, like another msg message. The POW therein must already be completed.
|-
| 1+||sig_length||var_int||Length of the signature
|-
| sig_length||signature||uchar[]||The ECDSA signature which covers everything from the msg_version to the ack_data.
|}

====Message Encodings====
{|class="wikitable"
! Value !! Name !! Description
|-
| 0 || IGNORE || Any data with this number may be ignored. The sending node might simply be sharing its public key with you.
|-
| 1 || TRIVIAL|| UTF-8. No 'Subject' or 'Body' sections. Useful for simple strings of data, like URIs or magnet links.
|-
| 2 || SIMPLE || UTF-8. Uses 'Subject' and 'Body' sections. No MIME is used.
<code>messageToTransmit = 'Subject:' + subject + '\n' + 'Body:' + message</code>
|}

Further values for the message encodings can be decided upon by the community. Any MIME or MIME-like encoding format, should they be used, should make use of Bitmessage's 8-bit bytes.

====Pubkey bitfield features====
{|class="wikitable"
! Bit!! Name !! Description
|-
| 0 || undefined || The most significant bit at the beginning of the structure. Undefined
|-
| 1 || undefined || The next most significant bit. Undefined
|-
| ... || ... || ...
|-
| 30 || include_destination || Receiving node expects that the RIPE hash encoded in their address preceedes the encrypted message data of msg messages bound for them.
|-
| 31 || does_ack|| If true, the receiving node does send acknowledgements (rather than dropping them).
|}

== 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.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || int32_t || Identifies protocol version being used by the node. Should equal 3. Nodes should disconnect if the remote node's version is lower but continue with the connection if it is higher.
|-
| 8 || services || uint64_t || bitfield of features to be enabled for this connection
|-
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds
|-
| 26 || addr_recv || net_addr || The network address of the node receiving this message (not including the time or stream number)
|-
| 26 || addr_from || net_addr || The network address of the node emitting this message (not including the time or stream number and the ip itself is ignored by the receiver)
|-
| 8 || nonce || uint64_t || Random nonce used to detect connections to self.
|-
| 1+ || user_agent || [[#Variable length string|var_str]] || [[User Agent]] (0x00 if string is 0 bytes long)
|-
| 1+ || stream numbers || [[#Variable length list of integers|var_int_list]] || The stream numbers that the emitting node is interested in.
|}

A "verack" packet shall be sent if the version packet was accepted. Once you have sent and received a verack messages with the remote node, send an addr message advertising up to 1000 peers of which you are aware, and one or more inv messages advertising all of the valid objects of which you are aware.

The following services are currently assigned:

{|class="wikitable"
! Value !! Name !! Description
|-
| 1 || NODE_NETWORK || This is a normal network node.
|}

=== verack ===

The ''verack'' message is sent in reply to ''version''. This message consists of only a [[#Message structure|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.

=== addr ===

Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours

Payload:
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+ || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of address entries (max: 1000)
|-
| 34x? || addr_list || [[Protocol_specification#Network_address|net_addr]] || Address of other nodes on the network.
|}

=== inv ===

Allows a node to advertise its knowledge of one or more objects.
Payload (maximum payload length: 50000 items):

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of inventory entries
|-
| 32x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors
|}

=== 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):

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of inventory entries
|-
| 32x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors
|}

=== 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|Proof Of Work]] must be done.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8||nonce||uint64_t||
Random nonce used for the [[Proof of work|Proof Of Work]]
|-
| 8||expiresTime||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 shared with peers until its end-of-life time has been reached. The node should store the inventory vector of that object for some extra period of time to avoid reloading it from another node with a small time delay. The time may be no further than 28 days + 3 hours in the future.
|-
| 4||objectType||uint32_t||
Four values are currently defined: 0-"getpubkey", 1-"pubkey", 2-"msg", 3-"broadcast". All other values are reserved. Nodes should relay objects even if they use an undefined object type.
|-
| 1+||version||var_int||The object's version. Note that msg objects won't contain a version until Sun, 16 Nov 2014 22:00:00 GMT.
|-
| 1+||stream number||var_int||The stream number in which this object may propagate
|-
| ?||payload||uchar[]||
This field varies depending on the object type; see below.
|-
|}

== 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.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 20||ripe||uchar[]||The ripemd hash of the public key. This field is only included when the address version is <= 3.
|-
| 32||tag||uchar[]||The tag derived from the address version, stream number, and ripe. This field is only included when the address version is >= 4.
|}

=== pubkey ===

A version 2 pubkey. This is still in use and supported by current clients but ''new'' v2 addresses are not generated by clients.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4||[[Protocol_specification#Pubkey_bitfield_features|behavior bitfield]]||uint32_t||A bitfield of optional behaviors and features that can be expected from the node receiving the message.
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|}

A version 3 pubkey

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4||[[Protocol_specification#Pubkey_bitfield_features|behavior bitfield]]||uint32_t||A bitfield of optional behaviors and features that can be expected from the node receiving the message.
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|-
| 1+||nonce_trials_per_byte||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is the average number of nonce trials a node will have to perform to meet the Proof of Work requirement. 1000 is the network minimum so any lower values will be automatically raised to 1000.
|-
| 1+||extra_bytes||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is added to the data length to make sending small messages more difficult. 1000 is the network minimum so any lower values will be automatically raised to 1000.
|-
| 1+||sig_length||var_int||Length of the signature
|-
| sig_length||signature||uchar[]||The ECDSA signature which, as of protocol v3, covers the object header starting with the time, appended with the data described in this table down to the extra_bytes.
|}

A version 4 pubkey

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 32||tag||uchar[]||The tag, made up of bytes 32-64 of the double hash of the address data (see example python code below)
|-
| ?||encrypted||uchar[]||Encrypted pubkey data.
|-
|}

When version 4 pubkeys are created, most of the data in the pubkey is encrypted. This is done in such a way that only someone who has the Bitmessage address which corresponds to a pubkey can decrypt and use that pubkey. This prevents people from gathering pubkeys sent around the network and using the data from them to create messages to be used in spam or in flooding attacks.

In order to encrypt the pubkey data, a double SHA-512 hash is calculated from the address version number, stream number, and ripe hash of the Bitmessage address that the pubkey corresponds to. The first 32 bytes of this hash are used to create a public and private key pair with which to encrypt and decrypt the pubkey data, using the same algorithm as message encryption (see [[Encryption]]). The remaining 32 bytes of this hash are added to the unencrypted part of the pubkey and used as a tag, as above. This allows nodes to determine which pubkey to decrypt when they wish to send a message.

In PyBitmessage, the double hash of the address data is calculated using the python code below:

doubleHashOfAddressData = hashlib.sha512(hashlib.sha512(encodeVarint(addressVersionNumber) + encodeVarint(streamNumber) + hash).digest()).digest()

Encrypted data in version 4 pubkeys:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
|-
| 4||[[Protocol_specification#Pubkey_bitfield_features|behavior bitfield]]||uint32_t||A bitfield of optional behaviors and features that can be expected from the node receiving the message.
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|-
| 1+||nonce_trials_per_byte||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is the average number of nonce trials a node will have to perform to meet the Proof of Work requirement. 1000 is the network minimum so any lower values will be automatically raised to 1000.
|-
| 1+||extra_bytes||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is added to the data length to make sending small messages more difficult. 1000 is the network minimum so any lower values will be automatically raised to 1000.
|-
| 1+||sig_length||var_int||Length of the signature
|-
| sig_length||signature||uchar[]||The ECDSA signature which covers everything from the object header starting with the time, then appended with the decrypted data down to the extra_bytes. This was changed in protocol v3. 
|}

=== 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.
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ?||encrypted||uchar[]||Encrypted data. See [[Protocol_specification#Encrypted_payload|Encrypted payload]]. See also [[Protocol_specification#Unencrypted_Message_Data|Unencrypted Message Data Format]]
|}

=== 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.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 32 || tag|| uchar[]||The tag. This field is new and only included when the broadcast version is >= 5. Changed in protocol v3
|-
| ?||encrypted||uchar[]||Encrypted broadcast data. The keys are derived as described in the paragraph above. See [[Protocol_specification#Encrypted_payload|Encrypted payload]] for details about the encryption algorithm itself.
|}

Unencrypted data format:
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+|| broadcast version|| var_int||The version number of this broadcast protocol message which is equal to 2 or 3. This is included here so that it can be signed. This is no longer included in protocol v3
|-
| 1+ || address version|| var_int||The sender's address version
|-
| 1+ || stream number|| var_int||The sender's stream number
|-
| 4||[[Protocol_specification#Pubkey_bitfield_features|behavior bitfield]]||uint32_t||A bitfield of optional behaviors and features that can be expected from the owner of this pubkey.
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|-
| 1+||nonce_trials_per_byte||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is the average number of nonce trials a node will have to perform to meet the Proof of Work requirement. 1000 is the network minimum so any lower values will be automatically raised to 1000. This field is new and is only included when the address_version >= 3.
|-
| 1+||extra_bytes||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is added to the data length to make sending small messages more difficult. 1000 is the network minimum so any lower values will be automatically raised to 1000. This field is new and is only included when the address_version >= 3.
|-
| 1+ || [[Protocol_specification#Message_Encodings|encoding]]|| var_int||The [[Protocol_specification#Message_Encodings|encoding type]] of the message
|-
| 1+ ||messageLength || var_int||The message length in bytes
|-
| messageLength || message||uchar[] ||The message
|-
| 1+||sig_length||var_int||Length of the signature
|-
| sig_length|| signature||uchar[] ||The signature which did cover the unencrypted data from the broadcast version down through the message. In protocol v3, it covers the unencrypted object header starting with the time, all appended with the decrypted data.
|}

Protocol specification

2015-01-21T17:58:49Z

Atheros: /* Message structure */

All objects sent on the network should support protocol v3 starting on Sun, 16 Nov 2014 22:00:00 GMT. 

==Common standards==

=== Hashes ===

Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-512] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when creating an address.

A double-round of SHA-512 is used for the Proof Of Work. Example of double-SHA-512 encoding of string "hello":

hello
9b71d224bd62f3785d96d46ad3ea3d73319bfbc2890caadae2dff72519673ca72323c3d99ba5c11d7c7acc6e14b8c5da0c4663475c2e5c3adef46f73bcdec043(first round of sha-512)
0592a10584ffabf96539f3d780d776828c67da1ab5b169e9e8aed838aaecc9ed36d49ff1423c55f019e050c66c6324f53588be88894fef4dcffdb74b98e2b200(second round of sha-512)

For Bitmessage addresses (RIPEMD-160) this would give:

hello
9b71d224bd62f3785d96d46ad3ea3d73319bfbc2890caadae2dff72519673ca72323c3d99ba5c11d7c7acc6e14b8c5da0c4663475c2e5c3adef46f73bcdec043(first round is sha-512)
79a324faeebcbf9849f310545ed531556882487e (with ripemd-160)

== Common structures ==

All integers are encoded in big endian. (This is different from Bitcoin).

=== Message structure ===

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown
|-
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)
|-
| 4 || length || uint32_t || Length of payload in number of bytes. The length may not exceed 2^18 bytes. Longer messages must be ignored.
|-
| 4 || checksum || uint32_t || First 4 bytes of sha512(payload)
|-
| ? || message_payload || uchar[] || The actual data, a [[#Message_types|message]] or an [[#Object_types|object]]. Not to be confused with object_payload.
|}

Known magic values:

{|class="wikitable"
! Magic value !! Sent over wire as
|-
| 0xE9BEB4D9 || E9 BE B4 D9
|}

=== 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 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.

{|class="wikitable"
! Value !! Storage length !! Format
|-
| < 0xfd || 1 || uint8_t
|-
| <= 0xffff || 3 || 0xfd followed by the integer as uint16_t
|-
| <= 0xffffffff || 5 || 0xfe followed by the integer as uint32_t
|-
| - || 9 || 0xff followed by the integer as uint64_t
|}

=== Variable length string ===

Variable length string can be stored using a variable length integer followed by the string itself.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+ || length || [[Protocol_specification#Variable_length_integer|var_int]] || Length of the string
|-
| ? || string || char[] || The string itself (can be empty)
|}

=== Variable length list of integers===

n integers can be stored using n+1 [[Protocol_specification#Variable_length_integer|variable length integers]] where the first var_int equals n.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+ || count|| [[Protocol_specification#Variable_length_integer|var_int]] || Number of var_ints below
|-
| 1+ || || var_int || The first value stored
|-
| 1+ || || var_int || The second value stored...
|-
| 1+ || || var_int || etc...
|}

=== Network address ===

When a network address is needed somewhere, this structure is used. Network addresses are not prefixed with a timestamp or stream in the version message.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 (or 8)|| time || uint32 || the Time. Protocol version 1 clients use 4 byte time while protocol version 2 clients use 8 byte time.
|-
| 4 || stream|| uint32 || Stream number for this node
|-
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]
|-
| 16 || IPv6/4 || char[16] || IPv6 address. IPv4 addresses are written into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).
|-
| 2 || port || uint16_t || port number
|}

=== Inventory Vectors ===

Inventory vectors are used for notifying other nodes about objects they have or data which is being requested. Two rounds of SHA-512 are used, resulting in a 64 byte hash. Only the first 32 bytes are used; the later 32 bytes are ignored.

Inventory vectors consist of the following data format:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 32 || hash || char[32] || Hash of the object
|}

=== Encrypted payload ===

Bitmessage uses [https://en.wikipedia.org/wiki/Integrated_Encryption_Scheme ECIES] to encrypt its messages. For more information see [[Encryption]]

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 16||IV||uchar[]||Initialization Vector used for AES-256-CBC
|-
| 2||uint16_t||Curve type||Elliptic Curve type 0x02CA (714)
|-
| 2||uint16_t||X length||Length of X component of public key R
|-
| X length||uchar[]||X||X component of public key R
|-
| 2||uint16_t||Y length||Length of Y component of public key R
|-
| Y length||uchar[]||Y||Y component of public key R
|-
| ?||encrypted||uchar[]||Cipher text
|-
| 32||MAC|| uchar[]||HMACSHA256 Message Authentication Code
|}

=== Unencrypted Message Data ===

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+||msg_version||var_int||Message format version. This field is not included after the protocol v3 upgrade period.
|-
| 1+||address_version||var_int||Sender's address version number. This is needed in order to calculate the sender's address to show in the UI, and also to allow for forwards compatible changes to the public-key data included below.
|-
| 1+||stream||var_int||Sender's stream number
|-
| 4||behavior bitfield||uint32_t||A bitfield of optional behaviors and features that can be expected from the node with this pubkey included in this msg message (the sender's pubkey).
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|-
| 1+||nonce_trials_per_byte||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is the average number of nonce trials a node will have to perform to meet the Proof of Work requirement. 1000 is the network minimum so any lower values will be automatically raised to 1000. '''This field is new and is only included when the address_version >= 3.'''
|-
| 1+||extra_bytes||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is added to the data length to make sending small messages more difficult. 1000 is the network minimum so any lower values will be automatically raised to 1000. '''This field is new and is only included when the address_version >= 3.'''
|-
| 20||destination ripe||uchar[]||The ripe hash of the public key of the receiver of the message
|-
| 1+||encoding||var_int||[[Protocol_specification#Message_Encodings|Message Encoding]] type
|-
| 1+||message_length||var_int||Message Length
|-
| message_length||message||uchar[]||The message.
|-
| 1+||ack_length||var_int||Length of the acknowledgement data
|-
| ack_length||ack_data||uchar[]||The acknowledgement data to be transmitted. This takes the form of a Bitmessage protocol message, like another msg message. The POW therein must already be completed.
|-
| 1+||sig_length||var_int||Length of the signature
|-
| sig_length||signature||uchar[]||The ECDSA signature which covers everything from the msg_version to the ack_data.
|}

====Message Encodings====
{|class="wikitable"
! Value !! Name !! Description
|-
| 0 || IGNORE || Any data with this number may be ignored. The sending node might simply be sharing its public key with you.
|-
| 1 || TRIVIAL|| UTF-8. No 'Subject' or 'Body' sections. Useful for simple strings of data, like URIs or magnet links.
|-
| 2 || SIMPLE || UTF-8. Uses 'Subject' and 'Body' sections. No MIME is used.
<code>messageToTransmit = 'Subject:' + subject + '\n' + 'Body:' + message</code>
|}

Further values for the message encodings can be decided upon by the community. Any MIME or MIME-like encoding format, should they be used, should make use of Bitmessage's 8-bit bytes.

====Pubkey bitfield features====
{|class="wikitable"
! Bit!! Name !! Description
|-
| 0 || undefined || The most significant bit at the beginning of the structure. Undefined
|-
| 1 || undefined || The next most significant bit. Undefined
|-
| ... || ... || ...
|-
| 30 || include_destination || Receiving node expects that the RIPE hash encoded in their address preceedes the encrypted message data of msg messages bound for them.
|-
| 31 || does_ack|| If true, the receiving node does send acknowledgements (rather than dropping them).
|}

== 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.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || int32_t || Identifies protocol version being used by the node. Should equal 3. Nodes should disconnect if the remote node's version is lower but continue with the connection if it is higher.
|-
| 8 || services || uint64_t || bitfield of features to be enabled for this connection
|-
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds
|-
| 26 || addr_recv || net_addr || The network address of the node receiving this message (not including the time or stream number)
|-
| 26 || addr_from || net_addr || The network address of the node emitting this message (not including the time or stream number and the ip itself is ignored by the receiver)
|-
| 8 || nonce || uint64_t || Random nonce used to detect connections to self.
|-
| 1+ || user_agent || [[#Variable length string|var_str]] || [[User Agent]] (0x00 if string is 0 bytes long)
|-
| 1+ || stream numbers || [[#Variable length list of integers|var_int_list]] || The stream numbers that the emitting node is interested in.
|}

A "verack" packet shall be sent if the version packet was accepted. Once you have sent and received a verack messages with the remote node, send an addr message advertising up to 1000 peers of which you are aware, and one or more inv messages advertising all of the valid objects of which you are aware.

The following services are currently assigned:

{|class="wikitable"
! Value !! Name !! Description
|-
| 1 || NODE_NETWORK || This is a normal network node.
|}

=== verack ===

The ''verack'' message is sent in reply to ''version''. This message consists of only a [[#Message structure|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.

=== addr ===

Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours

Payload:
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+ || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of address entries (max: 1000)
|-
| 34x? || addr_list || [[Protocol_specification#Network_address|net_addr]] || Address of other nodes on the network.
|}

=== inv ===

Allows a node to advertise its knowledge of one or more objects.
Payload (maximum payload length: 50000 items):

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of inventory entries
|-
| 32x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors
|}

=== 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):

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of inventory entries
|-
| 32x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors
|}

=== 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|Proof Of Work]] must be done.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8||nonce||uint64_t||
Random nonce used for the [[Proof of work|Proof Of Work]]
|-
| 8||expiresTime||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 shared with peers until its end-of-life time has been reached. The node should store the inventory vector of that object for some extra period of time to avoid reloading it from another node with a small time delay. The time may be no further than 28 days + 3 hours in the future.
|-
| 4||objectType||uint32_t||
Four values are currently defined: 0-"getpubkey", 1-"pubkey", 2-"msg", 3-"broadcast". All other values are reserved. Nodes should relay objects even if they use an undefined object type.
|-
| 1+||version||var_int||The object's version. Note that msg objects won't contain a version until Sun, 16 Nov 2014 22:00:00 GMT.
|-
| 1+||stream number||var_int||The stream number in which this object may propagate
|-
| ?||payload||uchar[]||
This field varies depending on the object type; see below.
|-
|}

== 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.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 20||ripe||uchar[]||The ripemd hash of the public key. This field is only included when the address version is <= 3.
|-
| 32||tag||uchar[]||The tag derived from the address version, stream number, and ripe. This field is only included when the address version is >= 4.
|}

=== pubkey ===

A version 2 pubkey. This is still in use and supported by current clients but ''new'' v2 addresses are not generated by clients.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4||[[Protocol_specification#Pubkey_bitfield_features|behavior bitfield]]||uint32_t||A bitfield of optional behaviors and features that can be expected from the node receiving the message.
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|}

A version 3 pubkey

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4||[[Protocol_specification#Pubkey_bitfield_features|behavior bitfield]]||uint32_t||A bitfield of optional behaviors and features that can be expected from the node receiving the message.
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|-
| 1+||nonce_trials_per_byte||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is the average number of nonce trials a node will have to perform to meet the Proof of Work requirement. 1000 is the network minimum so any lower values will be automatically raised to 1000.
|-
| 1+||extra_bytes||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is added to the data length to make sending small messages more difficult. 1000 is the network minimum so any lower values will be automatically raised to 1000.
|-
| 1+||sig_length||var_int||Length of the signature
|-
| sig_length||signature||uchar[]||The ECDSA signature which, as of protocol v3, covers the object header starting with the time, appended with the data described in this table down to the extra_bytes.
|}

A version 4 pubkey

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 32||tag||uchar[]||The tag, made up of bytes 32-64 of the double hash of the address data (see example python code below)
|-
| ?||encrypted||uchar[]||Encrypted pubkey data.
|-
|}

When version 4 pubkeys are created, most of the data in the pubkey is encrypted. This is done in such a way that only someone who has the Bitmessage address which corresponds to a pubkey can decrypt and use that pubkey. This prevents people from gathering pubkeys sent around the network and using the data from them to create messages to be used in spam or in flooding attacks.

In order to encrypt the pubkey data, a double SHA-512 hash is calculated from the address version number, stream number, and ripe hash of the Bitmessage address that the pubkey corresponds to. The first 32 bytes of this hash are used to create a public and private key pair with which to encrypt and decrypt the pubkey data, using the same algorithm as message encryption (see [[Encryption]]). The remaining 32 bytes of this hash are added to the unencrypted part of the pubkey and used as a tag, as above. This allows nodes to determine which pubkey to decrypt when they wish to send a message.

In PyBitmessage, the double hash of the address data is calculated using the python code below:

doubleHashOfAddressData = hashlib.sha512(hashlib.sha512(encodeVarint(addressVersionNumber) + encodeVarint(streamNumber) + hash).digest()).digest()

Encrypted data in version 4 pubkeys:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
|-
| 4||[[Protocol_specification#Pubkey_bitfield_features|behavior bitfield]]||uint32_t||A bitfield of optional behaviors and features that can be expected from the node receiving the message.
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|-
| 1+||nonce_trials_per_byte||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is the average number of nonce trials a node will have to perform to meet the Proof of Work requirement. 1000 is the network minimum so any lower values will be automatically raised to 1000.
|-
| 1+||extra_bytes||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is added to the data length to make sending small messages more difficult. 1000 is the network minimum so any lower values will be automatically raised to 1000.
|-
| 1+||sig_length||var_int||Length of the signature
|-
| sig_length||signature||uchar[]||The ECDSA signature which covers everything from the object header starting with the time, then appended with the decrypted data down to the extra_bytes. This was changed in protocol v3. 
|}

=== 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.
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ?||encrypted||uchar[]||Encrypted data. See [[Protocol_specification#Encrypted_payload|Encrypted payload]]. See also [[Protocol_specification#Unencrypted_Message_Data|Unencrypted Message Data Format]]
|}

=== 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.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 32 || tag|| uchar[]||The tag. This field is new and only included when the broadcast version is >= 5. Changed in protocol v3
|-
| ?||encrypted||uchar[]||Encrypted broadcast data. The keys are derived as described in the paragraph above. See [[Protocol_specification#Encrypted_payload|Encrypted payload]] for details about the encryption algorithm itself.
|}

Unencrypted data format:
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+|| broadcast version|| var_int||The version number of this broadcast protocol message which is equal to 2 or 3. This is included here so that it can be signed. This is no longer included in protocol v3
|-
| 1+ || address version|| var_int||The sender's address version
|-
| 1+ || stream number|| var_int||The sender's stream number
|-
| 4||[[Protocol_specification#Pubkey_bitfield_features|behavior bitfield]]||uint32_t||A bitfield of optional behaviors and features that can be expected from the owner of this pubkey.
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|-
| 1+||nonce_trials_per_byte||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is the average number of nonce trials a node will have to perform to meet the Proof of Work requirement. 1000 is the network minimum so any lower values will be automatically raised to 1000. This field is new and is only included when the address_version >= 3.
|-
| 1+||extra_bytes||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is added to the data length to make sending small messages more difficult. 1000 is the network minimum so any lower values will be automatically raised to 1000. This field is new and is only included when the address_version >= 3.
|-
| 1+ || [[Protocol_specification#Message_Encodings|encoding]]|| var_int||The [[Protocol_specification#Message_Encodings|encoding type]] of the message
|-
| 1+ ||messageLength || var_int||The message length in bytes
|-
| messageLength || message||uchar[] ||The message
|-
| 1+||sig_length||var_int||Length of the signature
|-
| sig_length|| signature||uchar[] ||The signature which did cover the unencrypted data from the broadcast version down through the message. In protocol v3, it covers the unencrypted object header starting with the time, all appended with the decrypted data.
|}

Keys.dat options

2015-01-15T22:31:11Z

Atheros: added maxcores

This page lists the extra 'hidden' options of which you can make use by adding them to your [[keys.dat]] file in the bitmessagesettings section. These options are either not set by default or are not documented at all.



== Possible options ==

{|class="wikitable"
! Version !! Name !! Values !! Documentation !! Description
|-
| ? || maxcores || integer || undocumented || Use no more than this many threads/cores to calculate proofs of work.
|-
| ? || trustedpeer || IP:Port || undocumented || Connect to the specified node and only the specified node. Useful if you trust a node on your local network and want to sync to it quickly. Disallows incoming connections. Disables the built-in timing attack mitigation mechanism.
|-
| 0.2.7 || apienabled || true/false || [[API|API Reference]] || Turns the [[API]] on or off
|-
| 0.2.7 || apiport || integer || [[API|API Reference]] || Port number to listen on (0-65535)
|-
| 0.2.7 || apiinterface || IP || [[API|API Reference]] || IP address of a local interface. 127.0.0.1 for localhost only access and 0.0.0.0 for all interfaces.
|-
| 0.2.7 || apiusername || string || [[API|API Reference]] || Username to access the API
|-
| 0.2.7 || apipassword || string || [[API|API Reference]] || password to access the API
|}

== enabling options ==
To enable an option, the [[keys.dat]] must be edited.
Lines of the format
<pre>name = Value</pre>
can be added. '''Please be aware of the spacing around the equal sign'''

API Reference

2014-12-26T04:01:32Z

Atheros: /* List of Operations */

=== Introduction ===

The PyBitmessage API uses [http://en.wikipedia.org/wiki/XML-RPC XML-RPC].

=== Enable the API ===
To enable the API, copy and paste these lines into the bitmessagesettings section of the [[keys.dat]] file.
Note that the values "username" and "password" below are merely examples, and should be replaced by values that cannot feasibly be guessed:
<pre>
apienabled = true
apiport = 8442
apiinterface = 127.0.0.1
apiusername = username
apipassword = password
</pre>
Additionally, you may optionally include an additional entry which will specify a program which Bitmessage will run when certain events occur.
<pre>
apinotifypath = c:\\example\\example.exe
</pre>
One of these arguments will be passed to your program: startingUp, newMessage, newBroadcast. Be sure your program doesn't crash when given newer arguments introduced in the future as this list will likely expand.

=== Remote Access ===
To access the Bitmessage API from a remote location, change the apiinterface value from '''127.0.0.1''' to '''0.0.0.0'''.

The following Python code offers a demonstration of how to create a client that can connect to the PyBitmessage API.

In this example, the username is "username", the password is "password", the IP address of the server running PyBitmessage is 105.168.1.0 (a random example), and the port number which PyBitmessage has been configured to listen on is 8442. In order to connect with the remote copy of PyBitmessage, these settings must match those in PyBitmessage's "keys.dat" file.
<pre>
import xmlrpclib
import json
import time

api = xmlrpclib.ServerProxy("http://username:password@105.168.1.0:8442/")
print api.add(2,3)
</pre>

A more complete example can be found in the [https://github.com/Bitmessage/PyBitmessage/blob/master/src/api_client.py api_client.py] file in the PyBitmessage source code.

=== List of Operations ===
Required arguments are denoted inside < and > Optional arguments are inside [ and ].
{|class="wikitable"
! Command !! Parameters !! Minimum Version !! Description
|-
| helloWorld || <firstWord> <secondWord> || 0.2.7 || returns 'firstWord-secondWord'. Used as a simple test of the API.
|-
| add || <integer> <integer> || 0.2.7 || returns the sum of the integers. Used as a simple test of the API.
|-
| statusBar || <message> || 0.2.7 || Displays the message in the status bar on the GUI
|-
| listAddresses2|| || 0.4.0 || Lists all addresses shown on the Your Identities tab. Returns a list of objects with these properties:
* label (base64, decodes into utf-8)
* address (ascii/utf-8)
* stream (integer)
* enabled (bool)
* chan (bool)

This is called listAddresses'''2''' because 'listAddresses' is obsolete.
|-
| createRandomAddress || <label> [eighteenByteRipe] [totalDifficulty] [smallMessageDifficulty] || 0.2.7 || Creates one address using the random number generator. label should be base64 encoded. eighteenByteRipe is a boolean telling Bitmessage whether to generate an address with an 18 byte RIPE hash(as opposed to a 19 byte hash). This is the same setting as the "Do extra work to make the address 1 or 2 characters shorter" in the user interface. Using False is recommended if you are running some sort of website and will be generating a lot of addresses. Note that even if you don't ask for it, there is still a 1 in 256 chance that you will get an address with an 18 byte RIPE hash so if you actually ''need'' an address with a 19 byte RIPE hash for some reason, you will need to check for it. eighteenByteRipe defaults to False. totalDifficulty and smallMessageDifficulty default to 1.

Returns the address.

Warning: At present, Bitmessage gets confused if you use both the API and the UI to make an address at the same time.
|-
|createDeterministicAddresses ||<passphrase> [numberOfAddresses] [addressVersionNumber] [streamNumber] [eighteenByteRipe] [totalDifficulty] [smallMessageDifficulty] || 0.3.4 || Similar to createRandomAddress except that you may generate many addresses in one go. passphrase should be base64 encoded. numberOfAddresses defaults to 1. addressVersionNumber and streamNumber may be set to 0 which will tell Bitmessage to use the most up-to-date addressVersionNumber and the most available streamNumber. Using zero for each of these fields is recommended. eighteenByteRipe defaults to False. totalDifficulty and smallMessageDifficulty default to 1.

Returns a list of new addresses. This list will be empty if the addresses already existed.

Warning: At present, Bitmessage gets confused if you use both the API and the UI to make addresses at the same time.
|-
|getDeterministicAddress ||<passphrase> <addressVersionNumber> <streamNumber> || 0.3.1 || Similar to createDeterministicAddresses except that the one address that is returned will not be added to the Bitmessage user interface or the keys.dat file. passphrase should be base64 encoded. addressVersionNumber should be set to 3 or 4 as these are the only ones currently supported. streamNumber must be set to 1 as this is the only one currently supported.

Returns a single address.

Warning: At present, Bitmessage gets confused if you use both this API command and the UI to make addresses at the same time.
|-
|<code>getAllInboxMessages</code>|| || 0.2.7 || Does not include trashed messages. Returns a list of objects with these properties:
* msgid (hex)
* toAddress (ascii/utf-8)
* fromAddress (ascii/utf-8)
* subject (base64, decodes into utf-8)
* message (base64, decodes into utf-8)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* receivedTime (integer, Unix time)
* read (integer representing binary state (0 or 1))

The msgid is the same as the hash of the message (analogous to the TXID in Bitcoin) thus it is shown in hex as that is the de facto standard. The base64 encoding Bitmessage uses includes line breaks including one on the end of the string.
|-
|<code>getAllInboxMessageIDs</code>|| || 0.2.7 || Returns a list of msgids of all Inbox messages with there properties:
* msgid (hex)
|-
| getInboxMessageByID || <msgid> [read] || 0.4.0 || Returns an object with these properties:
* msgid (hex)
* toAddress (ascii/utf-8)
* fromAddress (ascii/utf-8)
* subject (base64, decodes into utf-8)
* message (base64, decodes into utf-8)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* receivedTime (integer, Unix time)
* read (integer representing binary state (0 or 1))

Optionally sets the specific message to have a read status of 'read' (bool).

The msgid is the same as the hash of the message (analogous to the TXID in Bitcoin) thus it should be given in hex as that is the de facto standard. The base64 encoding Bitmessage uses includes line breaks including one on the end of the string.
|-
| getSentMessageByAckData || <ackData> || 0.3.4 || Returns an object with these properties:
* msgid (hex)
* toAddress (ascii/utf-8)
* fromAddress (ascii/utf-8)
* subject (base64, decodes into utf-8)
* message (base64, decodes into utf-8)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* lastActionTime (integer, Unix time)
* status (ascii/utf-8)
* ackData (hex)
|-
| getAllSentMessages || || 0.3.4 || Returns an object with these properties:
* msgid (hex)
* toAddress (ascii/utf-8)
* fromAddress (ascii/utf-8)
* subject (base64, decodes into utf-8)
* message (base64, decodes into utf-8)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* lastActionTime (integer, Unix time)
* status (ascii/utf-8)
* ackData (hex)
|-
| getSentMessageByID || <msgid> || 0.3.4 || Returns an object with these properties:
* msgid (hex)
* toAddress (ascii/utf-8)
* fromAddress (ascii/utf-8)
* subject (base64, decodes into utf-8)
* message (base64, decodes into utf-8)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* lastActionTime (integer, Unix time)
* status (ascii/utf-8)
* ackData (hex)
|-
| getSentMessagesBySender|| <fromAddress> || 0.3.4 || Returns a list of objects with these properties:
* msgid (hex)
* toAddress (ascii/utf-8)
* fromAddress (ascii/utf-8)
* subject (base64, decodes into utf-8)
* message (base64, decodes into utf-8)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* lastActionTime (integer, Unix time)
* status (ascii/utf-8)
* ackData (hex)
|-
| trashMessage || <msgid> || 0.2.7 || returns a simple message saying that the message was trashed assuming it ever even existed. Prior existence is not checked. msgid is encoded in hex just like in the getAllInboxMessages function.
|-
| sendMessage || <toAddress> <fromAddress> <subject> <message> [encodingType] || 0.2.7 || returns ackdata encoded in hex. subject and message must be encoded in base64 which may optionally include line breaks. If used, the encodingType must be set to 2; this is included for forwards compatibility.
|-
| sendBroadcast || <fromAddress> <subject> <message> [encodingType] || 0.2.7 || returns ackData encoded in hex. subject and message must be encoded in base64. If used, the encodingType must be set to 2; this is included for forwards compatibility.
|-
| getStatus || <ackData> || 0.3.0 || returns one of these strings: <strike>notFound, findingPubkey, doingPOW, sentMessage, or ackReceived</strike> notfound, msgqueued, broadcastqueued, broadcastsent, doingpubkeypow, awaitingpubkey, doingmsgpow, forcepow, msgsent, msgsentnoackexpected, or ackreceived.
|-
| listSubscriptions|| || 0.4.0 || Returns a list of objects with these properties:
* label (base64, decodes into utf-8)
* address (ascii/utf-8)
* enabled (bool)
|-
| addSubscription|| <address> [label] || 0.3.1 || Subscribe to an address. label must be base64-encoded.
|-
| deleteSubscription|| <address> || 0.3.1 || Unsubscribe from an address. The program does not check to see whether you were subscribed in the first place.
|-
| listAddressBookEntries|| || 0.4.0 ||Returns a list of objects with these properties:
* address (ascii/utf-8)
* label (base64, decodes into utf-8)
|-
| addAddressBookEntry|| <address> <label> || 0.4.0 || Add an entry to your address book. label must be base64-encoded.
|-
| deleteAddressBookEntry|| <address> || 0.4.0 || Delete an entry from your address book. The program does not check to see whether it was there in the first place.
|-
| trashSentMessageByAckData|| <ackData> || 0.4.0 || Trashes a sent message based on its ackdata. ackData should be encoded in hex. Returns a simple message saying that the message was trashed assuming it ever even existed. Prior existence is not checked.
|-
| createChan|| <passphrase> || 0.4.2 || Creates a new chan. passphrase must be base64 encoded. Outputs the corresponding Bitmessage address.
|-
| joinChan|| <passphrase> <address> || 0.4.2 || Join a chan. passphrase must be base64 encoded. Outputs "success"
|-
| leaveChan|| <address> || 0.4.2 || Leave a chan. Outputs "success". Note that at this time, the address is still shown in the UI until a restart.
|-
| deleteAddress|| <address> || 0.4.2 || Permanently delete an address from Your Identities and your keys.dat file. Outputs "success". Note that at this time, the address is still shown in the UI until a restart.
|-
| decodeAddress|| <address> || 0.4.2 || Returns an object with these properties:
* status (ascii/utf-8)
* addressVersion (ascii integer)
* streamNumber (ascii integer)
* ripe (base64, decodes into binary data)
|-
| addAddressToBlackWhiteList || <address> [label] || 0.4.5 || Add an entry to your black or white list- whichever you are currently using. label must be base64-encoded.
|-
| removeAddressFromBlackWhiteList || <address> || 0.4.5 || Delete an entry from your black or white list- whichever you are currently using (but not both).
|-
| clientStatus || || 0.4.0 || Returns the softwareName, softwareVersion, networkStatus, networkConnections, numberOfPubkeysProcessed, numberOfMessagesProcessed, and numberOfBroadcastsProcessed. networkStatus will be one of these strings: "notConnected", "connectedButHaveNotReceivedIncomingConnections", or "connectedAndReceivingIncomingConnections".
|}

'''Note:''' If the minimum required version is higher than {{Bitmessage Current Version Number}} then the code is available in source but not yet available in a compiled binary.

==== Possible error values ====

Here are the various error numbers and descriptions you might see.

{|class="wikitable"
! Error Number!! Message
|-
|0000 || API Error 0000: I need parameters!
|-
| 0001 || API Error 0001: The specified passphrase is blank.
|-
| 0002 || API Error 0002: The address version number currently must be 3 or 4 (or 0 which means auto-select).
|-
| 0003 || API Error 0003: The stream number must be 1 (or 0 which means auto-select). Others aren't supported.
|-
| 0004 || API Error 0004: Why would you ask me to generate 0 addresses for you?
|-
| 0005 || API Error 0005: You have (accidentally?) specified too many addresses to make. Maximum 999. This check only exists to prevent mischief; if you really want to create more addresses than this, contact the Bitmessage developers and we can modify the check or you can do it yourself by searching the source code for this message.
|-
| 0006 || API Error 0006: The encoding type must be 2 because that is the only one this program currently supports.
|-
| 0007 || API Error 0007: Could not decode address
|-
| 0008 || API Error 0008: Checksum failed for address
|-
| 0009 || API Error 0009: Invalid characters in address
|-
| 0010 || API Error 0010: Address version number too high (or zero) in address
|-
| 0011 || API Error 0011: The address version number currently must be 2, 3, or 4. Others aren't supported.
|-
| 0012 || API Error 0012: The stream number must be 1. Others aren't supported.
|-
| 0013 || API Error 0013: Could not find your fromAddress in the keys.dat file.
|-
| 0014 || API Error 0014: Your fromAddress is disabled. Cannot send.
|-
| 0015 || API Error 0015: The length of ackData should be 32 bytes (encoded in hex thus 64 characters).
|-
| 0016 || API Error 0016: You are already subscribed to that address.
|-
| 0017 || API Error 0017: Label is not valid UTF-8 data.
|-
| 0018 || API Error 0018: Chan name does not match address.
|-
| 0019 || API Error 0019: The length of hash should be 20 bytes (encoded in hex thus 40 characters).
|-
| 0020 || API Error 0020: Invalid method: <method_name_you_tried_to_execute>
|-
| 0021 || API Error 0021: Unexpected API Failure
|-
| 0022 || API Error 0022: Decode Error
|-
| 0023 || API Error 0023: Bool expected
|-
| 0024 || API Error 0024: Chan address is already present.
|-
| 0025 || API Error 0025: Specified address is not a chan address. Use deleteAddress API call instead.
|-
| 0026 || API Error 0026: Varint encoded in address is malformed.
|-
| 0027 || API Error 0027: Message is too long.
|-
| 0028 || API Error 0028: You have already black-/white-listed that address.
|-
| 0029 || API Error 0029: That entry does not exist in the black-/white-list.
|}

API Reference

2014-12-26T04:00:37Z

Atheros: /* List of Operations */ Added clientStatus. This was implemented in August 2013.

=== Introduction ===

The PyBitmessage API uses [http://en.wikipedia.org/wiki/XML-RPC XML-RPC].

=== Enable the API ===
To enable the API, copy and paste these lines into the bitmessagesettings section of the [[keys.dat]] file.
Note that the values "username" and "password" below are merely examples, and should be replaced by values that cannot feasibly be guessed:
<pre>
apienabled = true
apiport = 8442
apiinterface = 127.0.0.1
apiusername = username
apipassword = password
</pre>
Additionally, you may optionally include an additional entry which will specify a program which Bitmessage will run when certain events occur.
<pre>
apinotifypath = c:\\example\\example.exe
</pre>
One of these arguments will be passed to your program: startingUp, newMessage, newBroadcast. Be sure your program doesn't crash when given newer arguments introduced in the future as this list will likely expand.

=== Remote Access ===
To access the Bitmessage API from a remote location, change the apiinterface value from '''127.0.0.1''' to '''0.0.0.0'''.

The following Python code offers a demonstration of how to create a client that can connect to the PyBitmessage API.

In this example, the username is "username", the password is "password", the IP address of the server running PyBitmessage is 105.168.1.0 (a random example), and the port number which PyBitmessage has been configured to listen on is 8442. In order to connect with the remote copy of PyBitmessage, these settings must match those in PyBitmessage's "keys.dat" file.
<pre>
import xmlrpclib
import json
import time

api = xmlrpclib.ServerProxy("http://username:password@105.168.1.0:8442/")
print api.add(2,3)
</pre>

A more complete example can be found in the [https://github.com/Bitmessage/PyBitmessage/blob/master/src/api_client.py api_client.py] file in the PyBitmessage source code.

=== List of Operations ===
Required arguments are denoted inside < and > Optional arguments are inside [ and ].
{|class="wikitable"
! Command !! Parameters !! Minimum Version !! Description
|-
| helloWorld || <firstWord> <secondWord> || 0.2.7 || returns 'firstWord-secondWord'. Used as a simple test of the API.
|-
| add || <integer> <integer> || 0.2.7 || returns the sum of the integers. Used as a simple test of the API.
|-
| statusBar || <message> || 0.2.7 || Displays the message in the status bar on the GUI
|-
| listAddresses2|| || 0.4.0 || Lists all addresses shown on the Your Identities tab. Returns a list of objects with these properties:
* label (base64, decodes into utf-8)
* address (ascii/utf-8)
* stream (integer)
* enabled (bool)
* chan (bool)

This is called listAddresses'''2''' because 'listAddresses' is obsolete.
|-
| createRandomAddress || <label> [eighteenByteRipe] [totalDifficulty] [smallMessageDifficulty] || 0.2.7 || Creates one address using the random number generator. label should be base64 encoded. eighteenByteRipe is a boolean telling Bitmessage whether to generate an address with an 18 byte RIPE hash(as opposed to a 19 byte hash). This is the same setting as the "Do extra work to make the address 1 or 2 characters shorter" in the user interface. Using False is recommended if you are running some sort of website and will be generating a lot of addresses. Note that even if you don't ask for it, there is still a 1 in 256 chance that you will get an address with an 18 byte RIPE hash so if you actually ''need'' an address with a 19 byte RIPE hash for some reason, you will need to check for it. eighteenByteRipe defaults to False. totalDifficulty and smallMessageDifficulty default to 1.

Returns the address.

Warning: At present, Bitmessage gets confused if you use both the API and the UI to make an address at the same time.
|-
|createDeterministicAddresses ||<passphrase> [numberOfAddresses] [addressVersionNumber] [streamNumber] [eighteenByteRipe] [totalDifficulty] [smallMessageDifficulty] || 0.3.4 || Similar to createRandomAddress except that you may generate many addresses in one go. passphrase should be base64 encoded. numberOfAddresses defaults to 1. addressVersionNumber and streamNumber may be set to 0 which will tell Bitmessage to use the most up-to-date addressVersionNumber and the most available streamNumber. Using zero for each of these fields is recommended. eighteenByteRipe defaults to False. totalDifficulty and smallMessageDifficulty default to 1.

Returns a list of new addresses. This list will be empty if the addresses already existed.

Warning: At present, Bitmessage gets confused if you use both the API and the UI to make addresses at the same time.
|-
|getDeterministicAddress ||<passphrase> <addressVersionNumber> <streamNumber> || 0.3.1 || Similar to createDeterministicAddresses except that the one address that is returned will not be added to the Bitmessage user interface or the keys.dat file. passphrase should be base64 encoded. addressVersionNumber should be set to 3 or 4 as these are the only ones currently supported. streamNumber must be set to 1 as this is the only one currently supported.

Returns a single address.

Warning: At present, Bitmessage gets confused if you use both this API command and the UI to make addresses at the same time.
|-
|<code>getAllInboxMessages</code>|| || 0.2.7 || Does not include trashed messages. Returns a list of objects with these properties:
* msgid (hex)
* toAddress (ascii/utf-8)
* fromAddress (ascii/utf-8)
* subject (base64, decodes into utf-8)
* message (base64, decodes into utf-8)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* receivedTime (integer, Unix time)
* read (integer representing binary state (0 or 1))

The msgid is the same as the hash of the message (analogous to the TXID in Bitcoin) thus it is shown in hex as that is the de facto standard. The base64 encoding Bitmessage uses includes line breaks including one on the end of the string.
|-
|<code>getAllInboxMessageIDs</code>|| || 0.2.7 || Returns a list of msgids of all Inbox messages with there properties:
* msgid (hex)
|-
| getInboxMessageByID || <msgid> [read] || 0.4.0 || Returns an object with these properties:
* msgid (hex)
* toAddress (ascii/utf-8)
* fromAddress (ascii/utf-8)
* subject (base64, decodes into utf-8)
* message (base64, decodes into utf-8)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* receivedTime (integer, Unix time)
* read (integer representing binary state (0 or 1))

Optionally sets the specific message to have a read status of 'read' (bool).

The msgid is the same as the hash of the message (analogous to the TXID in Bitcoin) thus it should be given in hex as that is the de facto standard. The base64 encoding Bitmessage uses includes line breaks including one on the end of the string.
|-
| getSentMessageByAckData || <ackData> || 0.3.4 || Returns an object with these properties:
* msgid (hex)
* toAddress (ascii/utf-8)
* fromAddress (ascii/utf-8)
* subject (base64, decodes into utf-8)
* message (base64, decodes into utf-8)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* lastActionTime (integer, Unix time)
* status (ascii/utf-8)
* ackData (hex)
|-
| getAllSentMessages || || 0.3.4 || Returns an object with these properties:
* msgid (hex)
* toAddress (ascii/utf-8)
* fromAddress (ascii/utf-8)
* subject (base64, decodes into utf-8)
* message (base64, decodes into utf-8)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* lastActionTime (integer, Unix time)
* status (ascii/utf-8)
* ackData (hex)
|-
| getSentMessageByID || <msgid> || 0.3.4 || Returns an object with these properties:
* msgid (hex)
* toAddress (ascii/utf-8)
* fromAddress (ascii/utf-8)
* subject (base64, decodes into utf-8)
* message (base64, decodes into utf-8)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* lastActionTime (integer, Unix time)
* status (ascii/utf-8)
* ackData (hex)
|-
| getSentMessagesBySender|| <fromAddress> || 0.3.4 || Returns a list of objects with these properties:
* msgid (hex)
* toAddress (ascii/utf-8)
* fromAddress (ascii/utf-8)
* subject (base64, decodes into utf-8)
* message (base64, decodes into utf-8)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* lastActionTime (integer, Unix time)
* status (ascii/utf-8)
* ackData (hex)
|-
| trashMessage || <msgid> || 0.2.7 || returns a simple message saying that the message was trashed assuming it ever even existed. Prior existence is not checked. msgid is encoded in hex just like in the getAllInboxMessages function.
|-
| sendMessage || <toAddress> <fromAddress> <subject> <message> [encodingType] || 0.2.7 || returns ackdata encoded in hex. subject and message must be encoded in base64 which may optionally include line breaks. If used, the encodingType must be set to 2; this is included for forwards compatibility.
|-
| sendBroadcast || <fromAddress> <subject> <message> [encodingType] || 0.2.7 || returns ackData encoded in hex. subject and message must be encoded in base64. If used, the encodingType must be set to 2; this is included for forwards compatibility.
|-
| getStatus || <ackData> || 0.3.0 || returns one of these strings: <strike>notFound, findingPubkey, doingPOW, sentMessage, or ackReceived</strike> notfound, msgqueued, broadcastqueued, broadcastsent, doingpubkeypow, awaitingpubkey, doingmsgpow, forcepow, msgsent, msgsentnoackexpected, or ackreceived.
|-
| listSubscriptions|| || 0.4.0 || Returns a list of objects with these properties:
* label (base64, decodes into utf-8)
* address (ascii/utf-8)
* enabled (bool)
|-
| addSubscription|| <address> [label] || 0.3.1 || Subscribe to an address. label must be base64-encoded.
|-
| deleteSubscription|| <address> || 0.3.1 || Unsubscribe from an address. The program does not check to see whether you were subscribed in the first place.
|-
| listAddressBookEntries|| || 0.4.0 ||Returns a list of objects with these properties:
* address (ascii/utf-8)
* label (base64, decodes into utf-8)
|-
| addAddressBookEntry|| <address> <label> || 0.4.0 || Add an entry to your address book. label must be base64-encoded.
|-
| deleteAddressBookEntry|| <address> || 0.4.0 || Delete an entry from your address book. The program does not check to see whether it was there in the first place.
|-
| trashSentMessageByAckData|| <ackData> || 0.4.0 || Trashes a sent message based on its ackdata. ackData should be encoded in hex. Returns a simple message saying that the message was trashed assuming it ever even existed. Prior existence is not checked.
|-
| createChan|| <passphrase> || 0.4.2 || Creates a new chan. passphrase must be base64 encoded. Outputs the corresponding Bitmessage address.
|-
| joinChan|| <passphrase> <address> || 0.4.2 || Join a chan. passphrase must be base64 encoded. Outputs "success"
|-
| leaveChan|| <address> || 0.4.2 || Leave a chan. Outputs "success". Note that at this time, the address is still shown in the UI until a restart.
|-
| deleteAddress|| <address> || 0.4.2 || Permanently delete an address from Your Identities and your keys.dat file. Outputs "success". Note that at this time, the address is still shown in the UI until a restart.
|-
| decodeAddress|| <address> || 0.4.2 || Returns an object with these properties:
* status (ascii/utf-8)
* addressVersion (ascii integer)
* streamNumber (ascii integer)
* ripe (base64, decodes into binary data)
|-
| addAddressToBlackWhiteList || <address> [label] || 0.4.5 || Add an entry to your black or white list- whichever you are currently using. label must be base64-encoded.
|-
| removeAddressFromBlackWhiteList || <address> || 0.4.5 || Delete an entry from your black or white list- whichever you are currently using (but not both).
|-
| clientStatus || || 0.3.5 || Returns the softwareName, softwareVersion, networkStatus, networkConnections, numberOfPubkeysProcessed, numberOfMessagesProcessed, and numberOfBroadcastsProcessed. networkStatus will be one of these strings: "notConnected", "connectedButHaveNotReceivedIncomingConnections", or "connectedAndReceivingIncomingConnections".
|}

'''Note:''' If the minimum required version is higher than {{Bitmessage Current Version Number}} then the code is available in source but not yet available in a compiled binary.

==== Possible error values ====

Here are the various error numbers and descriptions you might see.

{|class="wikitable"
! Error Number!! Message
|-
|0000 || API Error 0000: I need parameters!
|-
| 0001 || API Error 0001: The specified passphrase is blank.
|-
| 0002 || API Error 0002: The address version number currently must be 3 or 4 (or 0 which means auto-select).
|-
| 0003 || API Error 0003: The stream number must be 1 (or 0 which means auto-select). Others aren't supported.
|-
| 0004 || API Error 0004: Why would you ask me to generate 0 addresses for you?
|-
| 0005 || API Error 0005: You have (accidentally?) specified too many addresses to make. Maximum 999. This check only exists to prevent mischief; if you really want to create more addresses than this, contact the Bitmessage developers and we can modify the check or you can do it yourself by searching the source code for this message.
|-
| 0006 || API Error 0006: The encoding type must be 2 because that is the only one this program currently supports.
|-
| 0007 || API Error 0007: Could not decode address
|-
| 0008 || API Error 0008: Checksum failed for address
|-
| 0009 || API Error 0009: Invalid characters in address
|-
| 0010 || API Error 0010: Address version number too high (or zero) in address
|-
| 0011 || API Error 0011: The address version number currently must be 2, 3, or 4. Others aren't supported.
|-
| 0012 || API Error 0012: The stream number must be 1. Others aren't supported.
|-
| 0013 || API Error 0013: Could not find your fromAddress in the keys.dat file.
|-
| 0014 || API Error 0014: Your fromAddress is disabled. Cannot send.
|-
| 0015 || API Error 0015: The length of ackData should be 32 bytes (encoded in hex thus 64 characters).
|-
| 0016 || API Error 0016: You are already subscribed to that address.
|-
| 0017 || API Error 0017: Label is not valid UTF-8 data.
|-
| 0018 || API Error 0018: Chan name does not match address.
|-
| 0019 || API Error 0019: The length of hash should be 20 bytes (encoded in hex thus 40 characters).
|-
| 0020 || API Error 0020: Invalid method: <method_name_you_tried_to_execute>
|-
| 0021 || API Error 0021: Unexpected API Failure
|-
| 0022 || API Error 0022: Decode Error
|-
| 0023 || API Error 0023: Bool expected
|-
| 0024 || API Error 0024: Chan address is already present.
|-
| 0025 || API Error 0025: Specified address is not a chan address. Use deleteAddress API call instead.
|-
| 0026 || API Error 0026: Varint encoded in address is malformed.
|-
| 0027 || API Error 0027: Message is too long.
|-
| 0028 || API Error 0028: You have already black-/white-listed that address.
|-
| 0029 || API Error 0029: That entry does not exist in the black-/white-list.
|}

API Reference

2014-12-26T03:11:37Z

Atheros: /* List of Operations */ Added addAddressToBlackWhiteList and removeAddressFromBlackWhiteList

=== Introduction ===

The PyBitmessage API uses [http://en.wikipedia.org/wiki/XML-RPC XML-RPC].

=== Enable the API ===
To enable the API, copy and paste these lines into the bitmessagesettings section of the [[keys.dat]] file.
Note that the values "username" and "password" below are merely examples, and should be replaced by values that cannot feasibly be guessed:
<pre>
apienabled = true
apiport = 8442
apiinterface = 127.0.0.1
apiusername = username
apipassword = password
</pre>
Additionally, you may optionally include an additional entry which will specify a program which Bitmessage will run when certain events occur.
<pre>
apinotifypath = c:\\example\\example.exe
</pre>
One of these arguments will be passed to your program: startingUp, newMessage, newBroadcast. Be sure your program doesn't crash when given newer arguments introduced in the future as this list will likely expand.

=== Remote Access ===
To access the Bitmessage API from a remote location, change the apiinterface value from '''127.0.0.1''' to '''0.0.0.0'''.

The following Python code offers a demonstration of how to create a client that can connect to the PyBitmessage API.

In this example, the username is "username", the password is "password", the IP address of the server running PyBitmessage is 105.168.1.0 (a random example), and the port number which PyBitmessage has been configured to listen on is 8442. In order to connect with the remote copy of PyBitmessage, these settings must match those in PyBitmessage's "keys.dat" file.
<pre>
import xmlrpclib
import json
import time

api = xmlrpclib.ServerProxy("http://username:password@105.168.1.0:8442/")
print api.add(2,3)
</pre>

A more complete example can be found in the [https://github.com/Bitmessage/PyBitmessage/blob/master/src/api_client.py api_client.py] file in the PyBitmessage source code.

=== List of Operations ===
Required arguments are denoted inside < and > Optional arguments are inside [ and ].
{|class="wikitable"
! Command !! Parameters !! Minimum Version !! Description
|-
| helloWorld || <firstWord> <secondWord> || 0.2.7 || returns 'firstWord-secondWord'. Used as a simple test of the API.
|-
| add || <integer> <integer> || 0.2.7 || returns the sum of the integers. Used as a simple test of the API.
|-
| statusBar || <message> || 0.2.7 || Displays the message in the status bar on the GUI
|-
| listAddresses2|| || 0.4.0 || Lists all addresses shown on the Your Identities tab. Returns a list of objects with these properties:
* label (base64, decodes into utf-8)
* address (ascii/utf-8)
* stream (integer)
* enabled (bool)
* chan (bool)

This is called listAddresses'''2''' because 'listAddresses' is obsolete.
|-
| createRandomAddress || <label> [eighteenByteRipe] [totalDifficulty] [smallMessageDifficulty] || 0.2.7 || Creates one address using the random number generator. label should be base64 encoded. eighteenByteRipe is a boolean telling Bitmessage whether to generate an address with an 18 byte RIPE hash(as opposed to a 19 byte hash). This is the same setting as the "Do extra work to make the address 1 or 2 characters shorter" in the user interface. Using False is recommended if you are running some sort of website and will be generating a lot of addresses. Note that even if you don't ask for it, there is still a 1 in 256 chance that you will get an address with an 18 byte RIPE hash so if you actually ''need'' an address with a 19 byte RIPE hash for some reason, you will need to check for it. eighteenByteRipe defaults to False. totalDifficulty and smallMessageDifficulty default to 1.

Returns the address.

Warning: At present, Bitmessage gets confused if you use both the API and the UI to make an address at the same time.
|-
|createDeterministicAddresses ||<passphrase> [numberOfAddresses] [addressVersionNumber] [streamNumber] [eighteenByteRipe] [totalDifficulty] [smallMessageDifficulty] || 0.3.4 || Similar to createRandomAddress except that you may generate many addresses in one go. passphrase should be base64 encoded. numberOfAddresses defaults to 1. addressVersionNumber and streamNumber may be set to 0 which will tell Bitmessage to use the most up-to-date addressVersionNumber and the most available streamNumber. Using zero for each of these fields is recommended. eighteenByteRipe defaults to False. totalDifficulty and smallMessageDifficulty default to 1.

Returns a list of new addresses. This list will be empty if the addresses already existed.

Warning: At present, Bitmessage gets confused if you use both the API and the UI to make addresses at the same time.
|-
|getDeterministicAddress ||<passphrase> <addressVersionNumber> <streamNumber> || 0.3.1 || Similar to createDeterministicAddresses except that the one address that is returned will not be added to the Bitmessage user interface or the keys.dat file. passphrase should be base64 encoded. addressVersionNumber should be set to 3 or 4 as these are the only ones currently supported. streamNumber must be set to 1 as this is the only one currently supported.

Returns a single address.

Warning: At present, Bitmessage gets confused if you use both this API command and the UI to make addresses at the same time.
|-
|<code>getAllInboxMessages</code>|| || 0.2.7 || Does not include trashed messages. Returns a list of objects with these properties:
* msgid (hex)
* toAddress (ascii/utf-8)
* fromAddress (ascii/utf-8)
* subject (base64, decodes into utf-8)
* message (base64, decodes into utf-8)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* receivedTime (integer, Unix time)
* read (integer representing binary state (0 or 1))

The msgid is the same as the hash of the message (analogous to the TXID in Bitcoin) thus it is shown in hex as that is the de facto standard. The base64 encoding Bitmessage uses includes line breaks including one on the end of the string.
|-
|<code>getAllInboxMessageIDs</code>|| || 0.2.7 || Returns a list of msgids of all Inbox messages with there properties:
* msgid (hex)
|-
| getInboxMessageByID || <msgid> [read] || 0.4.0 || Returns an object with these properties:
* msgid (hex)
* toAddress (ascii/utf-8)
* fromAddress (ascii/utf-8)
* subject (base64, decodes into utf-8)
* message (base64, decodes into utf-8)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* receivedTime (integer, Unix time)
* read (integer representing binary state (0 or 1))

Optionally sets the specific message to have a read status of 'read' (bool).

The msgid is the same as the hash of the message (analogous to the TXID in Bitcoin) thus it should be given in hex as that is the de facto standard. The base64 encoding Bitmessage uses includes line breaks including one on the end of the string.
|-
| getSentMessageByAckData || <ackData> || 0.3.4 || Returns an object with these properties:
* msgid (hex)
* toAddress (ascii/utf-8)
* fromAddress (ascii/utf-8)
* subject (base64, decodes into utf-8)
* message (base64, decodes into utf-8)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* lastActionTime (integer, Unix time)
* status (ascii/utf-8)
* ackData (hex)
|-
| getAllSentMessages || || 0.3.4 || Returns an object with these properties:
* msgid (hex)
* toAddress (ascii/utf-8)
* fromAddress (ascii/utf-8)
* subject (base64, decodes into utf-8)
* message (base64, decodes into utf-8)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* lastActionTime (integer, Unix time)
* status (ascii/utf-8)
* ackData (hex)
|-
| getSentMessageByID || <msgid> || 0.3.4 || Returns an object with these properties:
* msgid (hex)
* toAddress (ascii/utf-8)
* fromAddress (ascii/utf-8)
* subject (base64, decodes into utf-8)
* message (base64, decodes into utf-8)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* lastActionTime (integer, Unix time)
* status (ascii/utf-8)
* ackData (hex)
|-
| getSentMessagesBySender|| <fromAddress> || 0.3.4 || Returns a list of objects with these properties:
* msgid (hex)
* toAddress (ascii/utf-8)
* fromAddress (ascii/utf-8)
* subject (base64, decodes into utf-8)
* message (base64, decodes into utf-8)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* lastActionTime (integer, Unix time)
* status (ascii/utf-8)
* ackData (hex)
|-
| trashMessage || <msgid> || 0.2.7 || returns a simple message saying that the message was trashed assuming it ever even existed. Prior existence is not checked. msgid is encoded in hex just like in the getAllInboxMessages function.
|-
| sendMessage || <toAddress> <fromAddress> <subject> <message> [encodingType] || 0.2.7 || returns ackdata encoded in hex. subject and message must be encoded in base64 which may optionally include line breaks. If used, the encodingType must be set to 2; this is included for forwards compatibility.
|-
| sendBroadcast || <fromAddress> <subject> <message> [encodingType] || 0.2.7 || returns ackData encoded in hex. subject and message must be encoded in base64. If used, the encodingType must be set to 2; this is included for forwards compatibility.
|-
| getStatus || <ackData> || 0.3.0 || returns one of these strings: <strike>notFound, findingPubkey, doingPOW, sentMessage, or ackReceived</strike> notfound, msgqueued, broadcastqueued, broadcastsent, doingpubkeypow, awaitingpubkey, doingmsgpow, forcepow, msgsent, msgsentnoackexpected, or ackreceived.
|-
| listSubscriptions|| || 0.4.0 || Returns a list of objects with these properties:
* label (base64, decodes into utf-8)
* address (ascii/utf-8)
* enabled (bool)
|-
| addSubscription|| <address> [label] || 0.3.1 || Subscribe to an address. label must be base64-encoded.
|-
| deleteSubscription|| <address> || 0.3.1 || Unsubscribe from an address. The program does not check to see whether you were subscribed in the first place.
|-
| listAddressBookEntries|| || 0.4.0 ||Returns a list of objects with these properties:
* address (ascii/utf-8)
* label (base64, decodes into utf-8)
|-
| addAddressBookEntry|| <address> <label> || 0.4.0 || Add an entry to your address book. label must be base64-encoded.
|-
| deleteAddressBookEntry|| <address> || 0.4.0 || Delete an entry from your address book. The program does not check to see whether it was there in the first place.
|-
| trashSentMessageByAckData|| <ackData> || 0.4.0 || Trashes a sent message based on its ackdata. ackData should be encoded in hex. Returns a simple message saying that the message was trashed assuming it ever even existed. Prior existence is not checked.
|-
| createChan|| <passphrase> || 0.4.2 || Creates a new chan. passphrase must be base64 encoded. Outputs the corresponding Bitmessage address.
|-
| joinChan|| <passphrase> <address> || 0.4.2 || Join a chan. passphrase must be base64 encoded. Outputs "success"
|-
| leaveChan|| <address> || 0.4.2 || Leave a chan. Outputs "success". Note that at this time, the address is still shown in the UI until a restart.
|-
| deleteAddress|| <address> || 0.4.2 || Permanently delete an address from Your Identities and your keys.dat file. Outputs "success". Note that at this time, the address is still shown in the UI until a restart.
|-
| decodeAddress|| <address> || 0.4.2 || Returns an object with these properties:
* status (ascii/utf-8)
* addressVersion (ascii integer)
* streamNumber (ascii integer)
* ripe (base64, decodes into binary data)
|-
| addAddressToBlackWhiteList || <address> [label] || 0.4.5 || Add an entry to your black or white list- whichever you are currently using. label must be base64-encoded.
|-
| removeAddressFromBlackWhiteList || <address> || 0.4.5 || Delete an entry from your black or white list- whichever you are currently using (but not both).
|}

'''Note:''' If the minimum required version is higher than {{Bitmessage Current Version Number}} then the code is available in source but not yet available in a compiled binary.

==== Possible error values ====

Here are the various error numbers and descriptions you might see.

{|class="wikitable"
! Error Number!! Message
|-
|0000 || API Error 0000: I need parameters!
|-
| 0001 || API Error 0001: The specified passphrase is blank.
|-
| 0002 || API Error 0002: The address version number currently must be 3 or 4 (or 0 which means auto-select).
|-
| 0003 || API Error 0003: The stream number must be 1 (or 0 which means auto-select). Others aren't supported.
|-
| 0004 || API Error 0004: Why would you ask me to generate 0 addresses for you?
|-
| 0005 || API Error 0005: You have (accidentally?) specified too many addresses to make. Maximum 999. This check only exists to prevent mischief; if you really want to create more addresses than this, contact the Bitmessage developers and we can modify the check or you can do it yourself by searching the source code for this message.
|-
| 0006 || API Error 0006: The encoding type must be 2 because that is the only one this program currently supports.
|-
| 0007 || API Error 0007: Could not decode address
|-
| 0008 || API Error 0008: Checksum failed for address
|-
| 0009 || API Error 0009: Invalid characters in address
|-
| 0010 || API Error 0010: Address version number too high (or zero) in address
|-
| 0011 || API Error 0011: The address version number currently must be 2, 3, or 4. Others aren't supported.
|-
| 0012 || API Error 0012: The stream number must be 1. Others aren't supported.
|-
| 0013 || API Error 0013: Could not find your fromAddress in the keys.dat file.
|-
| 0014 || API Error 0014: Your fromAddress is disabled. Cannot send.
|-
| 0015 || API Error 0015: The length of ackData should be 32 bytes (encoded in hex thus 64 characters).
|-
| 0016 || API Error 0016: You are already subscribed to that address.
|-
| 0017 || API Error 0017: Label is not valid UTF-8 data.
|-
| 0018 || API Error 0018: Chan name does not match address.
|-
| 0019 || API Error 0019: The length of hash should be 20 bytes (encoded in hex thus 40 characters).
|-
| 0020 || API Error 0020: Invalid method: <method_name_you_tried_to_execute>
|-
| 0021 || API Error 0021: Unexpected API Failure
|-
| 0022 || API Error 0022: Decode Error
|-
| 0023 || API Error 0023: Bool expected
|-
| 0024 || API Error 0024: Chan address is already present.
|-
| 0025 || API Error 0025: Specified address is not a chan address. Use deleteAddress API call instead.
|-
| 0026 || API Error 0026: Varint encoded in address is malformed.
|-
| 0027 || API Error 0027: Message is too long.
|-
| 0028 || API Error 0028: You have already black-/white-listed that address.
|-
| 0029 || API Error 0029: That entry does not exist in the black-/white-list.
|}

API Reference

2014-12-26T03:03:41Z

Atheros: /* Possible error values */ Added 28 and 29

=== Introduction ===

The PyBitmessage API uses [http://en.wikipedia.org/wiki/XML-RPC XML-RPC].

=== Enable the API ===
To enable the API, copy and paste these lines into the bitmessagesettings section of the [[keys.dat]] file.
Note that the values "username" and "password" below are merely examples, and should be replaced by values that cannot feasibly be guessed:
<pre>
apienabled = true
apiport = 8442
apiinterface = 127.0.0.1
apiusername = username
apipassword = password
</pre>
Additionally, you may optionally include an additional entry which will specify a program which Bitmessage will run when certain events occur.
<pre>
apinotifypath = c:\\example\\example.exe
</pre>
One of these arguments will be passed to your program: startingUp, newMessage, newBroadcast. Be sure your program doesn't crash when given newer arguments introduced in the future as this list will likely expand.

=== Remote Access ===
To access the Bitmessage API from a remote location, change the apiinterface value from '''127.0.0.1''' to '''0.0.0.0'''.

The following Python code offers a demonstration of how to create a client that can connect to the PyBitmessage API.

In this example, the username is "username", the password is "password", the IP address of the server running PyBitmessage is 105.168.1.0 (a random example), and the port number which PyBitmessage has been configured to listen on is 8442. In order to connect with the remote copy of PyBitmessage, these settings must match those in PyBitmessage's "keys.dat" file.
<pre>
import xmlrpclib
import json
import time

api = xmlrpclib.ServerProxy("http://username:password@105.168.1.0:8442/")
print api.add(2,3)
</pre>

A more complete example can be found in the [https://github.com/Bitmessage/PyBitmessage/blob/master/src/api_client.py api_client.py] file in the PyBitmessage source code.

=== List of Operations ===
Required arguments are denoted inside < and > Optional arguments are inside [ and ].
{|class="wikitable"
! Command !! Parameters !! Minimum Version !! Description
|-
| helloWorld || <firstWord> <secondWord> || 0.2.7 || returns 'firstWord-secondWord'. Used as a simple test of the API.
|-
| add || <integer> <integer> || 0.2.7 || returns the sum of the integers. Used as a simple test of the API.
|-
| statusBar || <message> || 0.2.7 || Displays the message in the status bar on the GUI
|-
| listAddresses2|| || 0.4.0 || Lists all addresses shown on the Your Identities tab. Returns a list of objects with these properties:
* label (base64, decodes into utf-8)
* address (ascii/utf-8)
* stream (integer)
* enabled (bool)
* chan (bool)

This is called listAddresses'''2''' because 'listAddresses' is obsolete.
|-
| createRandomAddress || <label> [eighteenByteRipe] [totalDifficulty] [smallMessageDifficulty] || 0.2.7 || Creates one address using the random number generator. label should be base64 encoded. eighteenByteRipe is a boolean telling Bitmessage whether to generate an address with an 18 byte RIPE hash(as opposed to a 19 byte hash). This is the same setting as the "Do extra work to make the address 1 or 2 characters shorter" in the user interface. Using False is recommended if you are running some sort of website and will be generating a lot of addresses. Note that even if you don't ask for it, there is still a 1 in 256 chance that you will get an address with an 18 byte RIPE hash so if you actually ''need'' an address with a 19 byte RIPE hash for some reason, you will need to check for it. eighteenByteRipe defaults to False. totalDifficulty and smallMessageDifficulty default to 1.

Returns the address.

Warning: At present, Bitmessage gets confused if you use both the API and the UI to make an address at the same time.
|-
|createDeterministicAddresses ||<passphrase> [numberOfAddresses] [addressVersionNumber] [streamNumber] [eighteenByteRipe] [totalDifficulty] [smallMessageDifficulty] || 0.3.4 || Similar to createRandomAddress except that you may generate many addresses in one go. passphrase should be base64 encoded. numberOfAddresses defaults to 1. addressVersionNumber and streamNumber may be set to 0 which will tell Bitmessage to use the most up-to-date addressVersionNumber and the most available streamNumber. Using zero for each of these fields is recommended. eighteenByteRipe defaults to False. totalDifficulty and smallMessageDifficulty default to 1.

Returns a list of new addresses. This list will be empty if the addresses already existed.

Warning: At present, Bitmessage gets confused if you use both the API and the UI to make addresses at the same time.
|-
|getDeterministicAddress ||<passphrase> <addressVersionNumber> <streamNumber> || 0.3.1 || Similar to createDeterministicAddresses except that the one address that is returned will not be added to the Bitmessage user interface or the keys.dat file. passphrase should be base64 encoded. addressVersionNumber should be set to 3 or 4 as these are the only ones currently supported. streamNumber must be set to 1 as this is the only one currently supported.

Returns a single address.

Warning: At present, Bitmessage gets confused if you use both this API command and the UI to make addresses at the same time.
|-
|<code>getAllInboxMessages</code>|| || 0.2.7 || Does not include trashed messages. Returns a list of objects with these properties:
* msgid (hex)
* toAddress (ascii/utf-8)
* fromAddress (ascii/utf-8)
* subject (base64, decodes into utf-8)
* message (base64, decodes into utf-8)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* receivedTime (integer, Unix time)
* read (integer representing binary state (0 or 1))

The msgid is the same as the hash of the message (analogous to the TXID in Bitcoin) thus it is shown in hex as that is the de facto standard. The base64 encoding Bitmessage uses includes line breaks including one on the end of the string.
|-
|<code>getAllInboxMessageIDs</code>|| || 0.2.7 || Returns a list of msgids of all Inbox messages with there properties:
* msgid (hex)
|-
| getInboxMessageByID || <msgid> [read] || 0.4.0 || Returns an object with these properties:
* msgid (hex)
* toAddress (ascii/utf-8)
* fromAddress (ascii/utf-8)
* subject (base64, decodes into utf-8)
* message (base64, decodes into utf-8)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* receivedTime (integer, Unix time)
* read (integer representing binary state (0 or 1))

Optionally sets the specific message to have a read status of 'read' (bool).

The msgid is the same as the hash of the message (analogous to the TXID in Bitcoin) thus it should be given in hex as that is the de facto standard. The base64 encoding Bitmessage uses includes line breaks including one on the end of the string.
|-
| getSentMessageByAckData || <ackData> || 0.3.4 || Returns an object with these properties:
* msgid (hex)
* toAddress (ascii/utf-8)
* fromAddress (ascii/utf-8)
* subject (base64, decodes into utf-8)
* message (base64, decodes into utf-8)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* lastActionTime (integer, Unix time)
* status (ascii/utf-8)
* ackData (hex)
|-
| getAllSentMessages || || 0.3.4 || Returns an object with these properties:
* msgid (hex)
* toAddress (ascii/utf-8)
* fromAddress (ascii/utf-8)
* subject (base64, decodes into utf-8)
* message (base64, decodes into utf-8)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* lastActionTime (integer, Unix time)
* status (ascii/utf-8)
* ackData (hex)
|-
| getSentMessageByID || <msgid> || 0.3.4 || Returns an object with these properties:
* msgid (hex)
* toAddress (ascii/utf-8)
* fromAddress (ascii/utf-8)
* subject (base64, decodes into utf-8)
* message (base64, decodes into utf-8)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* lastActionTime (integer, Unix time)
* status (ascii/utf-8)
* ackData (hex)
|-
| getSentMessagesBySender|| <fromAddress> || 0.3.4 || Returns a list of objects with these properties:
* msgid (hex)
* toAddress (ascii/utf-8)
* fromAddress (ascii/utf-8)
* subject (base64, decodes into utf-8)
* message (base64, decodes into utf-8)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* lastActionTime (integer, Unix time)
* status (ascii/utf-8)
* ackData (hex)
|-
| trashMessage || <msgid> || 0.2.7 || returns a simple message saying that the message was trashed assuming it ever even existed. Prior existence is not checked. msgid is encoded in hex just like in the getAllInboxMessages function.
|-
| sendMessage || <toAddress> <fromAddress> <subject> <message> [encodingType] || 0.2.7 || returns ackdata encoded in hex. subject and message must be encoded in base64 which may optionally include line breaks. If used, the encodingType must be set to 2; this is included for forwards compatibility.
|-
| sendBroadcast || <fromAddress> <subject> <message> [encodingType] || 0.2.7 || returns ackData encoded in hex. subject and message must be encoded in base64. If used, the encodingType must be set to 2; this is included for forwards compatibility.
|-
| getStatus || <ackData> || 0.3.0 || returns one of these strings: <strike>notFound, findingPubkey, doingPOW, sentMessage, or ackReceived</strike> notfound, msgqueued, broadcastqueued, broadcastsent, doingpubkeypow, awaitingpubkey, doingmsgpow, forcepow, msgsent, msgsentnoackexpected, or ackreceived.
|-
| listSubscriptions|| || 0.4.0 || Returns a list of objects with these properties:
* label (base64, decodes into utf-8)
* address (ascii/utf-8)
* enabled (bool)
|-
| addSubscription|| <address> [label] || 0.3.1 || Subscribe to an address. label must be base64-encoded.
|-
| deleteSubscription|| <address> || 0.3.1 || Unsubscribe from an address. The program does not check to see whether you were subscribed in the first place.
|-
| listAddressBookEntries|| || 0.4.0 ||Returns a list of objects with these properties:
* address (ascii/utf-8)
* label (base64, decodes into utf-8)
|-
| addAddressBookEntry|| <address> <label> || 0.4.0 || Add an entry to your address book. label must be base64-encoded.
|-
| deleteAddressBookEntry|| <address> || 0.4.0 || Delete an entry from your address book. The program does not check to see whether it was there in the first place.
|-
| trashSentMessageByAckData|| <ackData> || 0.4.0 || Trashes a sent message based on its ackdata. ackData should be encoded in hex. Returns a simple message saying that the message was trashed assuming it ever even existed. Prior existence is not checked.
|-
| createChan|| <passphrase> || 0.4.2 || Creates a new chan. passphrase must be base64 encoded. Outputs the corresponding Bitmessage address.
|-
| joinChan|| <passphrase> <address> || 0.4.2 || Join a chan. passphrase must be base64 encoded. Outputs "success"
|-
| leaveChan|| <address> || 0.4.2 || Leave a chan. Outputs "success". Note that at this time, the address is still shown in the UI until a restart.
|-
| deleteAddress|| <address> || 0.4.2 || Permanently delete an address from Your Identities and your keys.dat file. Outputs "success". Note that at this time, the address is still shown in the UI until a restart.
|-
| decodeAddress|| <address> || 0.4.2 || Returns an object with these properties:
* status (ascii/utf-8)
* addressVersion (ascii integer)
* streamNumber (ascii integer)
* ripe (base64, decodes into binary data)
|}

'''Note:''' If the minimum required version is higher than {{Bitmessage Current Version Number}} then the code is available in source but not yet available in a compiled binary.

==== Possible error values ====

Here are the various error numbers and descriptions you might see.

{|class="wikitable"
! Error Number!! Message
|-
|0000 || API Error 0000: I need parameters!
|-
| 0001 || API Error 0001: The specified passphrase is blank.
|-
| 0002 || API Error 0002: The address version number currently must be 3 or 4 (or 0 which means auto-select).
|-
| 0003 || API Error 0003: The stream number must be 1 (or 0 which means auto-select). Others aren't supported.
|-
| 0004 || API Error 0004: Why would you ask me to generate 0 addresses for you?
|-
| 0005 || API Error 0005: You have (accidentally?) specified too many addresses to make. Maximum 999. This check only exists to prevent mischief; if you really want to create more addresses than this, contact the Bitmessage developers and we can modify the check or you can do it yourself by searching the source code for this message.
|-
| 0006 || API Error 0006: The encoding type must be 2 because that is the only one this program currently supports.
|-
| 0007 || API Error 0007: Could not decode address
|-
| 0008 || API Error 0008: Checksum failed for address
|-
| 0009 || API Error 0009: Invalid characters in address
|-
| 0010 || API Error 0010: Address version number too high (or zero) in address
|-
| 0011 || API Error 0011: The address version number currently must be 2, 3, or 4. Others aren't supported.
|-
| 0012 || API Error 0012: The stream number must be 1. Others aren't supported.
|-
| 0013 || API Error 0013: Could not find your fromAddress in the keys.dat file.
|-
| 0014 || API Error 0014: Your fromAddress is disabled. Cannot send.
|-
| 0015 || API Error 0015: The length of ackData should be 32 bytes (encoded in hex thus 64 characters).
|-
| 0016 || API Error 0016: You are already subscribed to that address.
|-
| 0017 || API Error 0017: Label is not valid UTF-8 data.
|-
| 0018 || API Error 0018: Chan name does not match address.
|-
| 0019 || API Error 0019: The length of hash should be 20 bytes (encoded in hex thus 40 characters).
|-
| 0020 || API Error 0020: Invalid method: <method_name_you_tried_to_execute>
|-
| 0021 || API Error 0021: Unexpected API Failure
|-
| 0022 || API Error 0022: Decode Error
|-
| 0023 || API Error 0023: Bool expected
|-
| 0024 || API Error 0024: Chan address is already present.
|-
| 0025 || API Error 0025: Specified address is not a chan address. Use deleteAddress API call instead.
|-
| 0026 || API Error 0026: Varint encoded in address is malformed.
|-
| 0027 || API Error 0027: Message is too long.
|-
| 0028 || API Error 0028: You have already black-/white-listed that address.
|-
| 0029 || API Error 0029: That entry does not exist in the black-/white-list.
|}

Encryption

2014-11-21T22:16:36Z

Atheros: MAC calculation change to match pyelliptic

Bitmessage uses the Elliptic Curve Integrated Encryption Scheme (ECIES)[http://en.wikipedia.org/wiki/Integrated_Encryption_Scheme] to encrypt the payload of the Message and Broadcast objects.

The scheme uses Elliptic Curve Diffie-Hellman (ECDH)[http://en.wikipedia.org/wiki/ECDH] to generate a shared secret used to generate the encryption parameters for Advanced Encryption Standard with 256bit key and Cipher-Block Chaining (AES-256-CBC)[http://en.wikipedia.org/wiki/Advanced_Encryption_Standard]. The encrypted data will be padded to a 16 byte boundary in accordance to PKCS7[http://en.wikipedia.org/wiki/Cryptographic_Message_Syntax]. This means that the data is padded with N bytes of value N.

The Key Derivation Function (KDF)[http://en.wikipedia.org/wiki/Key_derivation_function] used to generate the key material for AES is SHA512[http://en.wikipedia.org/wiki/Sha512]. The Message Authentication Code (MAC) scheme used is HMACSHA256[http://en.wikipedia.org/wiki/Hmac].

== Format ==

(See also: [[Protocol specification]])

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 16||IV||uchar[]||Initialization Vector used for AES-256-CBC
|-
| 2||uint16_t||Curve type||Elliptic Curve type 0x02CA (714)
|-
| 2||uint16_t||X length||Length of X component of public key R
|-
| X length||uchar[]||X||X component of public key R
|-
| 2||uint16_t||Y length||Length of Y component of public key R
|-
| Y length||uchar[]||Y||Y component of public key R
|-
| ?||encrypted||uchar[]||Cipher text
|-
| 32||MAC|| uchar[]||HMACSHA256 Message Authentication Code
|}

In order to reconstitute a usable (65 byte) public key (starting with 0x04), the X and Y components need to be expanded by prepending them with 0x00 bytes until the individual component lengths are 32 bytes.

== Encryption ==

# The destination public key is called K.
# Generate 16 random bytes using a secure random number generator. Call them IV.
# Generate a new random EC key pair with private key called r and public key called R.
# Do an EC point multiply with public key K and private key r. This gives you public key P.
# Use the X component of public key P and calculate the SHA512 hash H.
# The first 32 bytes of H are called key_e and the last 32 bytes are called key_m.
# Pad the input text to a multiple of 16 bytes, in accordance to PKCS7.
# Encrypt the data with AES-256-CBC, using IV as initialization vector, key_e as encryption key and the padded input text as payload. Call the output cipher text.
# Calculate a 32 byte MAC with HMACSHA256, using key_m as salt and IV + R + cipher text as data. Call the output MAC.

The resulting data is: IV + R + cipher text + MAC

== Decryption ==

# The private key used to decrypt is called k.
# Do an EC point multiply with private key k and public key R. This gives you public key P.
# Use the X component of public key P and calculate the SHA512 hash H.
# The first 32 bytes of H are called key_e and the last 32 bytes are called key_m.
# Calculate MAC' with HMACSHA256, using key_m as salt and IV + R + cipher text as data.
# Compare MAC with MAC'. If not equal, decryption will fail.
# Decrypt the cipher text with AES-256-CBC, using IV as initialization vector, key_e as decryption key and the cipher text as payload. The output is the padded input text.

== Partial Example ==

Public key K:

{|class="wikitable"
! Data !! Comments
|-
|<pre>
04 09 d4 e5 c0 ab 3d 25
fe 04 8c 64 c9 da 1a 24
2c 7f 19 41 7e 95 17 cd
26 69 50 d7 2c 75 57 13
58 5c 61 78 e9 7f e0 92
fc 89 7c 9a 1f 17 20 d5
77 0a e8 ea ad 2f a8 fc
bd 08 e9 32 4a 5d de 18
57</pre>||Public key, 0x04 prefix, then 32 bytes X and 32 bytes Y.
|}

Initialization Vector IV:

{|class="wikitable"
! Data !! Comments
|-
|<pre>bd db 7c 28 29 b0 80 38
75 30 84 a2 f3 99 16 81</pre>||16 bytes generated with a secure random number generator.
|}

Randomly generated key pair with private key r and public key R:

{|class="wikitable"
! Data !! Comments
|-
|<pre>5b e6 fa cd 94 1b 76 e9
d3 ea d0 30 29 fb db 6b
6e 08 09 29 3f 7f b1 97
d0 c5 1f 84 e9 6b 8b a4</pre>||Private key r
|-
|<pre>04 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 df 94 68 6c 6a fb 56
5a c6 14 9b 15 3d 61 b3
b2 87 ee 2c 7f 99 7c 14
23 87 96 c1 2b 43 a3 86
5a</pre>||Public key R
|}

Derived public key P (point multiply r with K):

{|class="wikitable"
! Data !! Comments
|-
|<pre>04 0d b8 e3 ad 8c 0c d7
3f a2 b3 46 71 b7 b2 47
72 9b 10 11 41 57 9d 19
9e 0d c0 bd 02 4e ae fd
89 ca c8 f5 28 dc 90 b6
68 11 ab ac 51 7d 74 97
be 52 92 93 12 29 be 0b
74 3e 05 03 f4 43 c3 d2
96</pre>||Public key P
|-
|<pre>0d b8 e3 ad 8c 0c d7 3f
a2 b3 46 71 b7 b2 47 72
9b 10 11 41 57 9d 19 9e
0d c0 bd 02 4e ae fd 89</pre>||X component of public key P
|}

SHA512 of public key P X component (H):

{|class="wikitable"
! Data !! Comments
|-
|<pre>17 05 43 82 82 67 86 71
05 26 3d 48 28 ef ff 82
d9 d5 9c bf 08 74 3b 69
6b cc 5d 69 fa 18 97 b4</pre>||First 32 bytes of H called key_e
|-
|<pre>f8 3f 1e 9c c5 d6 b8 44
8d 39 dc 6a 9d 5f 5b 7f
46 0e 4a 78 e9 28 6e e8
d9 1c e1 66 0a 53 ea cd</pre>||Last 32 bytes of H called key_m
|}

Padded input:

{|class="wikitable"
! Data !! Comments
|-
|<pre>54 68 65 20 71 75 69 63
6b 20 62 72 6f 77 6e 20
66 6f 78 20 6a 75 6d 70
73 20 6f 76 65 72 20 74
68 65 20 6c 61 7a 79 20
64 6f 67 2e 04 04 04 04</pre>||The quick brown fox jumps over the lazy dog.0x04,0x04,0x04,0x04
|}

Cipher text:

{|class="wikitable"
! Data !! Comments
|-
|<pre>64 20 3d 5b 24 68 8e 25
47 bb a3 45 fa 13 9a 5a
1d 96 22 20 d4 d4 8a 0c
f3 b1 57 2c 0d 95 b6 16
43 a6 f9 a0 d7 5a f7 ea
cc 1b d9 57 14 7b f7 23</pre>||3 blocks of 16 bytes of encrypted data.
|}

Proof of work

2014-10-17T21:46:38Z

Atheros: updated for Protocol V3

This page describes Bitmessage's Proof of work ("POW") mechanism as it exists in Protocol Version 3. In this document, hash() means SHA512(). SHA512 was chosen as it is widely supported and so that Bitcoin POW hardware cannot trivially be used for Bitmessage POWs. The author acknowledges that they are essentially the same algorithm with a different key size.

Both averageProofOfWorkNonceTrialsPerByte and payloadLengthExtraBytes are set by the owner of a Bitmessage address. The default and minimum for each is 1000. (This is the same as difficulty 1. If the difficulty is 2, then this value is 2000). The purpose of payloadLengthExtraBytes is to add some extra weight to small messages.

=== Do a POW ===

Let us use a msg message as an example.

payload = embeddedTime + encodedObjectVersion + encodedStreamNumber + encrypted

payloadLength = the length of payload, in bytes, + 8 (to account for the nonce which we will append later)

TTL = the number of seconds in between now and the object expiresTime.

[[File:POW forumla 2.png|none|caption]]

initialHash = hash(payload)

start with trialValue = 99999999999999999999

also start with nonce = 0 where nonce is 8 bytes in length and can be hashed as if it is a string.

while trialValue > target:
nonce = nonce + 1
resultHash = hash(hash( nonce || initialHash ))
trialValue = the first 8 bytes of resultHash, converted to an integer

When this loop finishes, you will have your 8 byte nonce value which you can prepend onto the front of the payload. The message is then ready to send.

=== Check a POW ===

Let us assume that 'payload' contains the payload for a msg message (the nonce down through the encrypted message data).

nonce = the first 8 bytes of payload

dataToCheck = the ninth byte of payload on down (thus it is everything except the nonce)

initialHash = hash(dataToCheck)

resultHash = hash(hash( nonce || initialHash ))

POWValue = the first eight bytes of resultHash converted to an integer

TTL = the number of seconds in between now and the object expiresTime.

[[File:POW forumla 2.png|none|caption]]

If POWValue is less than or equal to target, then the POW check passes.

Protocol specification

2014-10-17T20:41:56Z

Atheros: /* broadcast */

All objects sent on the network should support protocol v3 starting on Sun, 16 Nov 2014 22:00:00 GMT. 

==Common standards==

=== Hashes ===

Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-512] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when creating an address.

A double-round of SHA-512 is used for the Proof Of Work. Example of double-SHA-512 encoding of string "hello":

hello
9b71d224bd62f3785d96d46ad3ea3d73319bfbc2890caadae2dff72519673ca72323c3d99ba5c11d7c7acc6e14b8c5da0c4663475c2e5c3adef46f73bcdec043(first round of sha-512)
0592a10584ffabf96539f3d780d776828c67da1ab5b169e9e8aed838aaecc9ed36d49ff1423c55f019e050c66c6324f53588be88894fef4dcffdb74b98e2b200(second round of sha-512)

For Bitmessage addresses (RIPEMD-160) this would give:

hello
9b71d224bd62f3785d96d46ad3ea3d73319bfbc2890caadae2dff72519673ca72323c3d99ba5c11d7c7acc6e14b8c5da0c4663475c2e5c3adef46f73bcdec043(first round is sha-512)
79a324faeebcbf9849f310545ed531556882487e (with ripemd-160)

== Common structures ==

All integers are encoded in big endian. (This is different from Bitcoin).

=== Message structure ===

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown
|-
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)
|-
| 4 || length || uint32_t || Length of payload in number of bytes. The length may not exceed 2^18 bytes. Longer messages must be ignored.
|-
| 4 || checksum || uint32_t || First 4 bytes of sha512(payload)
|-
| ? || payload || uchar[] || The actual data, a [[#Message_types|message]] or an [[#Object_types|object]]
|}

Known magic values:

{|class="wikitable"
! Magic value !! Sent over wire as
|-
| 0xE9BEB4D9 || E9 BE B4 D9
|}

=== 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 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.

{|class="wikitable"
! Value !! Storage length !! Format
|-
| < 0xfd || 1 || uint8_t
|-
| <= 0xffff || 3 || 0xfd followed by the integer as uint16_t
|-
| <= 0xffffffff || 5 || 0xfe followed by the integer as uint32_t
|-
| - || 9 || 0xff followed by the integer as uint64_t
|}

=== Variable length string ===

Variable length string can be stored using a variable length integer followed by the string itself.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+ || length || [[Protocol_specification#Variable_length_integer|var_int]] || Length of the string
|-
| ? || string || char[] || The string itself (can be empty)
|}

=== Variable length list of integers===

n integers can be stored using n+1 [[Protocol_specification#Variable_length_integer|variable length integers]] where the first var_int equals n.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+ || count|| [[Protocol_specification#Variable_length_integer|var_int]] || Number of var_ints below
|-
| 1+ || || var_int || The first value stored
|-
| 1+ || || var_int || The second value stored...
|-
| 1+ || || var_int || etc...
|}

=== Network address ===

When a network address is needed somewhere, this structure is used. Network addresses are not prefixed with a timestamp or stream in the version message.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 (or 8)|| time || uint32 || the Time. Protocol version 1 clients use 4 byte time while protocol version 2 clients use 8 byte time.
|-
| 4 || stream|| uint32 || Stream number for this node
|-
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]
|-
| 16 || IPv6/4 || char[16] || IPv6 address. IPv4 addresses are written into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).
|-
| 2 || port || uint16_t || port number
|}

=== Inventory Vectors ===

Inventory vectors are used for notifying other nodes about objects they have or data which is being requested. Two rounds of SHA-512 are used, resulting in a 64 byte hash. Only the first 32 bytes are used; the later 32 bytes are ignored.

Inventory vectors consist of the following data format:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 32 || hash || char[32] || Hash of the object
|}

=== Encrypted payload ===

Bitmessage uses [https://en.wikipedia.org/wiki/Integrated_Encryption_Scheme ECIES] to encrypt its messages. For more information see [[Encryption]]

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 16||IV||uchar[]||Initialization Vector used for AES-256-CBC
|-
| 2||uint16_t||Curve type||Elliptic Curve type 0x02CA (714)
|-
| 2||uint16_t||X length||Length of X component of public key R
|-
| X length||uchar[]||X||X component of public key R
|-
| 2||uint16_t||Y length||Length of Y component of public key R
|-
| Y length||uchar[]||Y||Y component of public key R
|-
| ?||encrypted||uchar[]||Cipher text
|-
| 32||MAC|| uchar[]||HMACSHA256 Message Authentication Code
|}

=== Unencrypted Message Data ===

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+||msg_version||var_int||Message format version. This field is not included after the protocol v3 upgrade period.
|-
| 1+||address_version||var_int||Sender's address version number. This is needed in order to calculate the sender's address to show in the UI, and also to allow for forwards compatible changes to the public-key data included below.
|-
| 1+||stream||var_int||Sender's stream number
|-
| 4||behavior bitfield||uint32_t||A bitfield of optional behaviors and features that can be expected from the node with this pubkey included in this msg message (the sender's pubkey).
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|-
| 1+||nonce_trials_per_byte||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is the average number of nonce trials a node will have to perform to meet the Proof of Work requirement. 1000 is the network minimum so any lower values will be automatically raised to 1000. '''This field is new and is only included when the address_version >= 3.'''
|-
| 1+||extra_bytes||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is added to the data length to make sending small messages more difficult. 1000 is the network minimum so any lower values will be automatically raised to 1000. '''This field is new and is only included when the address_version >= 3.'''
|-
| 20||destination ripe||uchar[]||The ripe hash of the public key of the receiver of the message
|-
| 1+||encoding||var_int||[[Protocol_specification#Message_Encodings|Message Encoding]] type
|-
| 1+||message_length||var_int||Message Length
|-
| message_length||message||uchar[]||The message.
|-
| 1+||ack_length||var_int||Length of the acknowledgement data
|-
| ack_length||ack_data||uchar[]||The acknowledgement data to be transmitted. This takes the form of a Bitmessage protocol message, like another msg message. The POW therein must already be completed.
|-
| 1+||sig_length||var_int||Length of the signature
|-
| sig_length||signature||uchar[]||The ECDSA signature which covers everything from the msg_version to the ack_data.
|}

====Message Encodings====
{|class="wikitable"
! Value !! Name !! Description
|-
| 0 || IGNORE || Any data with this number may be ignored. The sending node might simply be sharing its public key with you.
|-
| 1 || TRIVIAL|| UTF-8. No 'Subject' or 'Body' sections. Useful for simple strings of data, like URIs or magnet links.
|-
| 2 || SIMPLE || UTF-8. Uses 'Subject' and 'Body' sections. No MIME is used.
<code>messageToTransmit = 'Subject:' + subject + '\n' + 'Body:' + message</code>
|}

Further values for the message encodings can be decided upon by the community. Any MIME or MIME-like encoding format, should they be used, should make use of Bitmessage's 8-bit bytes.

====Pubkey bitfield features====
{|class="wikitable"
! Bit!! Name !! Description
|-
| 0 || undefined || The most significant bit at the beginning of the structure. Undefined
|-
| 1 || undefined || The next most significant bit. Undefined
|-
| ... || ... || ...
|-
| 30 || include_destination || Receiving node expects that the RIPE hash encoded in their address preceedes the encrypted message data of msg messages bound for them.
|-
| 31 || does_ack|| If true, the receiving node does send acknowledgements (rather than dropping them).
|}

== 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.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || int32_t || Identifies protocol version being used by the node. Should equal 3. Nodes should disconnect if the remote node's version is lower but continue with the connection if it is higher.
|-
| 8 || services || uint64_t || bitfield of features to be enabled for this connection
|-
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds
|-
| 26 || addr_recv || net_addr || The network address of the node receiving this message (not including the time or stream number)
|-
| 26 || addr_from || net_addr || The network address of the node emitting this message (not including the time or stream number and the ip itself is ignored by the receiver)
|-
| 8 || nonce || uint64_t || Random nonce used to detect connections to self.
|-
| 1+ || user_agent || [[#Variable length string|var_str]] || [[User Agent]] (0x00 if string is 0 bytes long)
|-
| 1+ || stream numbers || [[#Variable length list of integers|var_int_list]] || The stream numbers that the emitting node is interested in.
|}

A "verack" packet shall be sent if the version packet was accepted. Once you have sent and received a verack messages with the remote node, send an addr message advertising up to 1000 peers of which you are aware, and one or more inv messages advertising all of the valid objects of which you are aware.

The following services are currently assigned:

{|class="wikitable"
! Value !! Name !! Description
|-
| 1 || NODE_NETWORK || This is a normal network node.
|}

=== verack ===

The ''verack'' message is sent in reply to ''version''. This message consists of only a [[#Message structure|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.

=== addr ===

Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours

Payload:
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+ || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of address entries (max: 1000)
|-
| 34x? || addr_list || [[Protocol_specification#Network_address|net_addr]] || Address of other nodes on the network.
|}

=== inv ===

Allows a node to advertise its knowledge of one or more objects.
Payload (maximum payload length: 50000 items):

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of inventory entries
|-
| 32x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors
|}

=== 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):

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of inventory entries
|-
| 32x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors
|}

=== 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|Proof Of Work]] must be done.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8||nonce||uint64_t||
Random nonce used for the [[Proof of work|Proof Of Work]]
|-
| 8||expiresTime||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 shared with peers until its end-of-life time has been reached. The node should store the inventory vector of that object for some extra period of time to avoid reloading it from another node with a small time delay. The time may be no further than 28 days + 3 hours in the future.
|-
| 4||objectType||uint32_t||
Four values are currently defined: 0-"getpubkey", 1-"pubkey", 2-"msg", 3-"broadcast". All other values are reserved. Nodes should relay objects even if they use an undefined object type.
|-
| 1+||version||var_int||The object's version. Note that msg objects won't contain a version until Sun, 16 Nov 2014 22:00:00 GMT.
|-
| 1+||stream number||var_int||The stream number in which this object may propagate
|-
| ?||payload||uchar[]||
This field varies depending on the object type; see below.
|-
|}

== 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.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 20||ripe||uchar[]||The ripemd hash of the public key. This field is only included when the address version is <= 3.
|-
| 32||tag||uchar[]||The tag derived from the address version, stream number, and ripe. This field is only included when the address version is >= 4.
|}

=== pubkey ===

A version 2 pubkey. This is still in use and supported by current clients but ''new'' v2 addresses are not generated by clients.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4||[[Protocol_specification#Pubkey_bitfield_features|behavior bitfield]]||uint32_t||A bitfield of optional behaviors and features that can be expected from the node receiving the message.
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|}

A version 3 pubkey

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4||[[Protocol_specification#Pubkey_bitfield_features|behavior bitfield]]||uint32_t||A bitfield of optional behaviors and features that can be expected from the node receiving the message.
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|-
| 1+||nonce_trials_per_byte||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is the average number of nonce trials a node will have to perform to meet the Proof of Work requirement. 1000 is the network minimum so any lower values will be automatically raised to 1000.
|-
| 1+||extra_bytes||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is added to the data length to make sending small messages more difficult. 1000 is the network minimum so any lower values will be automatically raised to 1000.
|-
| 1+||sig_length||var_int||Length of the signature
|-
| sig_length||signature||uchar[]||The ECDSA signature which, as of protocol v3, covers the object header starting with the time, appended with the data described in this table down to the extra_bytes.
|}

A version 4 pubkey

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 32||tag||uchar[]||The tag, made up of bytes 32-64 of the double hash of the address data (see example python code below)
|-
| ?||encrypted||uchar[]||Encrypted pubkey data.
|-
|}

When version 4 pubkeys are created, most of the data in the pubkey is encrypted. This is done in such a way that only someone who has the Bitmessage address which corresponds to a pubkey can decrypt and use that pubkey. This prevents people from gathering pubkeys sent around the network and using the data from them to create messages to be used in spam or in flooding attacks.

In order to encrypt the pubkey data, a double SHA-512 hash is calculated from the address version number, stream number, and ripe hash of the Bitmessage address that the pubkey corresponds to. The first 32 bytes of this hash are used to create a public and private key pair with which to encrypt and decrypt the pubkey data, using the same algorithm as message encryption (see [[Encryption]]). The remaining 32 bytes of this hash are added to the unencrypted part of the pubkey and used as a tag, as above. This allows nodes to determine which pubkey to decrypt when they wish to send a message.

In PyBitmessage, the double hash of the address data is calculated using the python code below:

doubleHashOfAddressData = hashlib.sha512(hashlib.sha512(encodeVarint(addressVersionNumber) + encodeVarint(streamNumber) + hash).digest()).digest()

Encrypted data in version 4 pubkeys:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
|-
| 4||[[Protocol_specification#Pubkey_bitfield_features|behavior bitfield]]||uint32_t||A bitfield of optional behaviors and features that can be expected from the node receiving the message.
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|-
| 1+||nonce_trials_per_byte||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is the average number of nonce trials a node will have to perform to meet the Proof of Work requirement. 1000 is the network minimum so any lower values will be automatically raised to 1000.
|-
| 1+||extra_bytes||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is added to the data length to make sending small messages more difficult. 1000 is the network minimum so any lower values will be automatically raised to 1000.
|-
| 1+||sig_length||var_int||Length of the signature
|-
| sig_length||signature||uchar[]||The ECDSA signature which covers everything from the object header starting with the time, then appended with the decrypted data down to the extra_bytes. This was changed in protocol v3. 
|}

=== 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.
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ?||encrypted||uchar[]||Encrypted data. See [[Protocol_specification#Encrypted_payload|Encrypted payload]]. See also [[Protocol_specification#Unencrypted_Message_Data|Unencrypted Message Data Format]]
|}

=== 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.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 32 || tag|| uchar[]||The tag. This field is new and only included when the broadcast version is >= 5. Changed in protocol v3
|-
| ?||encrypted||uchar[]||Encrypted broadcast data. The keys are derived as described in the paragraph above. See [[Protocol_specification#Encrypted_payload|Encrypted payload]] for details about the encryption algorithm itself.
|}

Unencrypted data format:
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+|| broadcast version|| var_int||The version number of this broadcast protocol message which is equal to 2 or 3. This is included here so that it can be signed. This is no longer included in protocol v3
|-
| 1+ || address version|| var_int||The sender's address version
|-
| 1+ || stream number|| var_int||The sender's stream number
|-
| 4||[[Protocol_specification#Pubkey_bitfield_features|behavior bitfield]]||uint32_t||A bitfield of optional behaviors and features that can be expected from the owner of this pubkey.
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|-
| 1+||nonce_trials_per_byte||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is the average number of nonce trials a node will have to perform to meet the Proof of Work requirement. 1000 is the network minimum so any lower values will be automatically raised to 1000. This field is new and is only included when the address_version >= 3.
|-
| 1+||extra_bytes||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is added to the data length to make sending small messages more difficult. 1000 is the network minimum so any lower values will be automatically raised to 1000. This field is new and is only included when the address_version >= 3.
|-
| 1+ || [[Protocol_specification#Message_Encodings|encoding]]|| var_int||The [[Protocol_specification#Message_Encodings|encoding type]] of the message
|-
| 1+ ||messageLength || var_int||The message length in bytes
|-
| messageLength || message||uchar[] ||The message
|-
| 1+||sig_length||var_int||Length of the signature
|-
| sig_length|| signature||uchar[] ||The signature which did cover the unencrypted data from the broadcast version down through the message. In protocol v3, it covers the unencrypted object header starting with the time, all appended with the decrypted data.
|}

Protocol specification

2014-10-17T20:24:25Z

Atheros: Updated minimum necessary nonce_trials_per_byte and extra_bytes from 320 and 14000 to 1000.

All objects sent on the network should support protocol v3 starting on Sun, 16 Nov 2014 22:00:00 GMT. 

==Common standards==

=== Hashes ===

Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-512] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when creating an address.

A double-round of SHA-512 is used for the Proof Of Work. Example of double-SHA-512 encoding of string "hello":

hello
9b71d224bd62f3785d96d46ad3ea3d73319bfbc2890caadae2dff72519673ca72323c3d99ba5c11d7c7acc6e14b8c5da0c4663475c2e5c3adef46f73bcdec043(first round of sha-512)
0592a10584ffabf96539f3d780d776828c67da1ab5b169e9e8aed838aaecc9ed36d49ff1423c55f019e050c66c6324f53588be88894fef4dcffdb74b98e2b200(second round of sha-512)

For Bitmessage addresses (RIPEMD-160) this would give:

hello
9b71d224bd62f3785d96d46ad3ea3d73319bfbc2890caadae2dff72519673ca72323c3d99ba5c11d7c7acc6e14b8c5da0c4663475c2e5c3adef46f73bcdec043(first round is sha-512)
79a324faeebcbf9849f310545ed531556882487e (with ripemd-160)

== Common structures ==

All integers are encoded in big endian. (This is different from Bitcoin).

=== Message structure ===

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown
|-
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)
|-
| 4 || length || uint32_t || Length of payload in number of bytes. The length may not exceed 2^18 bytes. Longer messages must be ignored.
|-
| 4 || checksum || uint32_t || First 4 bytes of sha512(payload)
|-
| ? || payload || uchar[] || The actual data, a [[#Message_types|message]] or an [[#Object_types|object]]
|}

Known magic values:

{|class="wikitable"
! Magic value !! Sent over wire as
|-
| 0xE9BEB4D9 || E9 BE B4 D9
|}

=== 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 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.

{|class="wikitable"
! Value !! Storage length !! Format
|-
| < 0xfd || 1 || uint8_t
|-
| <= 0xffff || 3 || 0xfd followed by the integer as uint16_t
|-
| <= 0xffffffff || 5 || 0xfe followed by the integer as uint32_t
|-
| - || 9 || 0xff followed by the integer as uint64_t
|}

=== Variable length string ===

Variable length string can be stored using a variable length integer followed by the string itself.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+ || length || [[Protocol_specification#Variable_length_integer|var_int]] || Length of the string
|-
| ? || string || char[] || The string itself (can be empty)
|}

=== Variable length list of integers===

n integers can be stored using n+1 [[Protocol_specification#Variable_length_integer|variable length integers]] where the first var_int equals n.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+ || count|| [[Protocol_specification#Variable_length_integer|var_int]] || Number of var_ints below
|-
| 1+ || || var_int || The first value stored
|-
| 1+ || || var_int || The second value stored...
|-
| 1+ || || var_int || etc...
|}

=== Network address ===

When a network address is needed somewhere, this structure is used. Network addresses are not prefixed with a timestamp or stream in the version message.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 (or 8)|| time || uint32 || the Time. Protocol version 1 clients use 4 byte time while protocol version 2 clients use 8 byte time.
|-
| 4 || stream|| uint32 || Stream number for this node
|-
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]
|-
| 16 || IPv6/4 || char[16] || IPv6 address. IPv4 addresses are written into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).
|-
| 2 || port || uint16_t || port number
|}

=== Inventory Vectors ===

Inventory vectors are used for notifying other nodes about objects they have or data which is being requested. Two rounds of SHA-512 are used, resulting in a 64 byte hash. Only the first 32 bytes are used; the later 32 bytes are ignored.

Inventory vectors consist of the following data format:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 32 || hash || char[32] || Hash of the object
|}

=== Encrypted payload ===

Bitmessage uses [https://en.wikipedia.org/wiki/Integrated_Encryption_Scheme ECIES] to encrypt its messages. For more information see [[Encryption]]

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 16||IV||uchar[]||Initialization Vector used for AES-256-CBC
|-
| 2||uint16_t||Curve type||Elliptic Curve type 0x02CA (714)
|-
| 2||uint16_t||X length||Length of X component of public key R
|-
| X length||uchar[]||X||X component of public key R
|-
| 2||uint16_t||Y length||Length of Y component of public key R
|-
| Y length||uchar[]||Y||Y component of public key R
|-
| ?||encrypted||uchar[]||Cipher text
|-
| 32||MAC|| uchar[]||HMACSHA256 Message Authentication Code
|}

=== Unencrypted Message Data ===

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+||msg_version||var_int||Message format version. This field is not included after the protocol v3 upgrade period.
|-
| 1+||address_version||var_int||Sender's address version number. This is needed in order to calculate the sender's address to show in the UI, and also to allow for forwards compatible changes to the public-key data included below.
|-
| 1+||stream||var_int||Sender's stream number
|-
| 4||behavior bitfield||uint32_t||A bitfield of optional behaviors and features that can be expected from the node with this pubkey included in this msg message (the sender's pubkey).
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|-
| 1+||nonce_trials_per_byte||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is the average number of nonce trials a node will have to perform to meet the Proof of Work requirement. 1000 is the network minimum so any lower values will be automatically raised to 1000. '''This field is new and is only included when the address_version >= 3.'''
|-
| 1+||extra_bytes||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is added to the data length to make sending small messages more difficult. 1000 is the network minimum so any lower values will be automatically raised to 1000. '''This field is new and is only included when the address_version >= 3.'''
|-
| 20||destination ripe||uchar[]||The ripe hash of the public key of the receiver of the message
|-
| 1+||encoding||var_int||[[Protocol_specification#Message_Encodings|Message Encoding]] type
|-
| 1+||message_length||var_int||Message Length
|-
| message_length||message||uchar[]||The message.
|-
| 1+||ack_length||var_int||Length of the acknowledgement data
|-
| ack_length||ack_data||uchar[]||The acknowledgement data to be transmitted. This takes the form of a Bitmessage protocol message, like another msg message. The POW therein must already be completed.
|-
| 1+||sig_length||var_int||Length of the signature
|-
| sig_length||signature||uchar[]||The ECDSA signature which covers everything from the msg_version to the ack_data.
|}

====Message Encodings====
{|class="wikitable"
! Value !! Name !! Description
|-
| 0 || IGNORE || Any data with this number may be ignored. The sending node might simply be sharing its public key with you.
|-
| 1 || TRIVIAL|| UTF-8. No 'Subject' or 'Body' sections. Useful for simple strings of data, like URIs or magnet links.
|-
| 2 || SIMPLE || UTF-8. Uses 'Subject' and 'Body' sections. No MIME is used.
<code>messageToTransmit = 'Subject:' + subject + '\n' + 'Body:' + message</code>
|}

Further values for the message encodings can be decided upon by the community. Any MIME or MIME-like encoding format, should they be used, should make use of Bitmessage's 8-bit bytes.

====Pubkey bitfield features====
{|class="wikitable"
! Bit!! Name !! Description
|-
| 0 || undefined || The most significant bit at the beginning of the structure. Undefined
|-
| 1 || undefined || The next most significant bit. Undefined
|-
| ... || ... || ...
|-
| 30 || include_destination || Receiving node expects that the RIPE hash encoded in their address preceedes the encrypted message data of msg messages bound for them.
|-
| 31 || does_ack|| If true, the receiving node does send acknowledgements (rather than dropping them).
|}

== 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.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || int32_t || Identifies protocol version being used by the node. Should equal 3. Nodes should disconnect if the remote node's version is lower but continue with the connection if it is higher.
|-
| 8 || services || uint64_t || bitfield of features to be enabled for this connection
|-
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds
|-
| 26 || addr_recv || net_addr || The network address of the node receiving this message (not including the time or stream number)
|-
| 26 || addr_from || net_addr || The network address of the node emitting this message (not including the time or stream number and the ip itself is ignored by the receiver)
|-
| 8 || nonce || uint64_t || Random nonce used to detect connections to self.
|-
| 1+ || user_agent || [[#Variable length string|var_str]] || [[User Agent]] (0x00 if string is 0 bytes long)
|-
| 1+ || stream numbers || [[#Variable length list of integers|var_int_list]] || The stream numbers that the emitting node is interested in.
|}

A "verack" packet shall be sent if the version packet was accepted. Once you have sent and received a verack messages with the remote node, send an addr message advertising up to 1000 peers of which you are aware, and one or more inv messages advertising all of the valid objects of which you are aware.

The following services are currently assigned:

{|class="wikitable"
! Value !! Name !! Description
|-
| 1 || NODE_NETWORK || This is a normal network node.
|}

=== verack ===

The ''verack'' message is sent in reply to ''version''. This message consists of only a [[#Message structure|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.

=== addr ===

Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours

Payload:
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+ || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of address entries (max: 1000)
|-
| 34x? || addr_list || [[Protocol_specification#Network_address|net_addr]] || Address of other nodes on the network.
|}

=== inv ===

Allows a node to advertise its knowledge of one or more objects.
Payload (maximum payload length: 50000 items):

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of inventory entries
|-
| 32x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors
|}

=== 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):

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of inventory entries
|-
| 32x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors
|}

=== 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|Proof Of Work]] must be done.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8||nonce||uint64_t||
Random nonce used for the [[Proof of work|Proof Of Work]]
|-
| 8||expiresTime||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 shared with peers until its end-of-life time has been reached. The node should store the inventory vector of that object for some extra period of time to avoid reloading it from another node with a small time delay. The time may be no further than 28 days + 3 hours in the future.
|-
| 4||objectType||uint32_t||
Four values are currently defined: 0-"getpubkey", 1-"pubkey", 2-"msg", 3-"broadcast". All other values are reserved. Nodes should relay objects even if they use an undefined object type.
|-
| 1+||version||var_int||The object's version. Note that msg objects won't contain a version until Sun, 16 Nov 2014 22:00:00 GMT.
|-
| 1+||stream number||var_int||The stream number in which this object may propagate
|-
| ?||payload||uchar[]||
This field varies depending on the object type; see below.
|-
|}

== 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.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 20||ripe||uchar[]||The ripemd hash of the public key. This field is only included when the address version is <= 3.
|-
| 32||tag||uchar[]||The tag derived from the address version, stream number, and ripe. This field is only included when the address version is >= 4.
|}

=== pubkey ===

A version 2 pubkey. This is still in use and supported by current clients but ''new'' v2 addresses are not generated by clients.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4||[[Protocol_specification#Pubkey_bitfield_features|behavior bitfield]]||uint32_t||A bitfield of optional behaviors and features that can be expected from the node receiving the message.
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|}

A version 3 pubkey

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4||[[Protocol_specification#Pubkey_bitfield_features|behavior bitfield]]||uint32_t||A bitfield of optional behaviors and features that can be expected from the node receiving the message.
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|-
| 1+||nonce_trials_per_byte||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is the average number of nonce trials a node will have to perform to meet the Proof of Work requirement. 1000 is the network minimum so any lower values will be automatically raised to 1000.
|-
| 1+||extra_bytes||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is added to the data length to make sending small messages more difficult. 1000 is the network minimum so any lower values will be automatically raised to 1000.
|-
| 1+||sig_length||var_int||Length of the signature
|-
| sig_length||signature||uchar[]||The ECDSA signature which, as of protocol v3, covers the object header starting with the time, appended with the data described in this table down to the extra_bytes.
|}

A version 4 pubkey

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 32||tag||uchar[]||The tag, made up of bytes 32-64 of the double hash of the address data (see example python code below)
|-
| ?||encrypted||uchar[]||Encrypted pubkey data.
|-
|}

When version 4 pubkeys are created, most of the data in the pubkey is encrypted. This is done in such a way that only someone who has the Bitmessage address which corresponds to a pubkey can decrypt and use that pubkey. This prevents people from gathering pubkeys sent around the network and using the data from them to create messages to be used in spam or in flooding attacks.

In order to encrypt the pubkey data, a double SHA-512 hash is calculated from the address version number, stream number, and ripe hash of the Bitmessage address that the pubkey corresponds to. The first 32 bytes of this hash are used to create a public and private key pair with which to encrypt and decrypt the pubkey data, using the same algorithm as message encryption (see [[Encryption]]). The remaining 32 bytes of this hash are added to the unencrypted part of the pubkey and used as a tag, as above. This allows nodes to determine which pubkey to decrypt when they wish to send a message.

In PyBitmessage, the double hash of the address data is calculated using the python code below:

doubleHashOfAddressData = hashlib.sha512(hashlib.sha512(encodeVarint(addressVersionNumber) + encodeVarint(streamNumber) + hash).digest()).digest()

Encrypted data in version 4 pubkeys:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
|-
| 4||[[Protocol_specification#Pubkey_bitfield_features|behavior bitfield]]||uint32_t||A bitfield of optional behaviors and features that can be expected from the node receiving the message.
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|-
| 1+||nonce_trials_per_byte||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is the average number of nonce trials a node will have to perform to meet the Proof of Work requirement. 1000 is the network minimum so any lower values will be automatically raised to 1000.
|-
| 1+||extra_bytes||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is added to the data length to make sending small messages more difficult. 1000 is the network minimum so any lower values will be automatically raised to 1000.
|-
| 1+||sig_length||var_int||Length of the signature
|-
| sig_length||signature||uchar[]||The ECDSA signature which covers everything from the object header starting with the time, then appended with the decrypted data down to the extra_bytes. This was changed in protocol v3. 
|}

=== 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.
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ?||encrypted||uchar[]||Encrypted data. See [[Protocol_specification#Encrypted_payload|Encrypted payload]]. See also [[Protocol_specification#Unencrypted_Message_Data|Unencrypted Message Data Format]]
|}

=== 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.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8 || POW nonce|| uint64_t|| The [[Proof of work|Proof Of Work]] nonce
|-
| 8 || time|| uint64_t|| The time that the message was broadcast.
|-
| 1+|| broadcast version|| var_int||The version number of this broadcast protocol message which is equal to 2 or 3. Changed to 4 or 5 for protocol v3.
|-
| 1+ || stream number|| var_int||The sender's stream number
|-
| 32 || tag|| uchar[]||The tag. This field is new and only included when the broadcast version is >= 5. Changed in protocol v3
|-
| ?||encrypted||uchar[]||Encrypted broadcast data. The keys are derived as described in the paragraph above. See [[Protocol_specification#Encrypted_payload|Encrypted payload]] for details about the encryption algorithm itself.
|}

Unencrypted data format:
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+|| broadcast version|| var_int||The version number of this broadcast protocol message which is equal to 2 or 3. This is included here so that it can be signed. This is no longer included in protocol v3
|-
| 1+ || address version|| var_int||The sender's address version
|-
| 1+ || stream number|| var_int||The sender's stream number
|-
| 4||[[Protocol_specification#Pubkey_bitfield_features|behavior bitfield]]||uint32_t||A bitfield of optional behaviors and features that can be expected from the owner of this pubkey.
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|-
| 1+||nonce_trials_per_byte||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is the average number of nonce trials a node will have to perform to meet the Proof of Work requirement. 1000 is the network minimum so any lower values will be automatically raised to 1000. This field is new and is only included when the address_version >= 3.
|-
| 1+||extra_bytes||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is added to the data length to make sending small messages more difficult. 1000 is the network minimum so any lower values will be automatically raised to 1000. This field is new and is only included when the address_version >= 3.
|-
| 1+ || [[Protocol_specification#Message_Encodings|encoding]]|| var_int||The [[Protocol_specification#Message_Encodings|encoding type]] of the message
|-
| 1+ ||messageLength || var_int||The message length in bytes
|-
| messageLength || message||uchar[] ||The message
|-
| 1+||sig_length||var_int||Length of the signature
|-
| sig_length|| signature||uchar[] ||The signature which did cover the unencrypted data from the broadcast version down through the message. In protocol v3, it covers the unencrypted object header starting with the time, all appended with the decrypted data.
|}

Protocol specification

2014-10-17T20:19:37Z

Atheros:

All objects sent on the network should support protocol v3 starting on Sun, 16 Nov 2014 22:00:00 GMT. 

==Common standards==

=== Hashes ===

Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-512] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when creating an address.

A double-round of SHA-512 is used for the Proof Of Work. Example of double-SHA-512 encoding of string "hello":

hello
9b71d224bd62f3785d96d46ad3ea3d73319bfbc2890caadae2dff72519673ca72323c3d99ba5c11d7c7acc6e14b8c5da0c4663475c2e5c3adef46f73bcdec043(first round of sha-512)
0592a10584ffabf96539f3d780d776828c67da1ab5b169e9e8aed838aaecc9ed36d49ff1423c55f019e050c66c6324f53588be88894fef4dcffdb74b98e2b200(second round of sha-512)

For Bitmessage addresses (RIPEMD-160) this would give:

hello
9b71d224bd62f3785d96d46ad3ea3d73319bfbc2890caadae2dff72519673ca72323c3d99ba5c11d7c7acc6e14b8c5da0c4663475c2e5c3adef46f73bcdec043(first round is sha-512)
79a324faeebcbf9849f310545ed531556882487e (with ripemd-160)

== Common structures ==

All integers are encoded in big endian. (This is different from Bitcoin).

=== Message structure ===

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown
|-
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)
|-
| 4 || length || uint32_t || Length of payload in number of bytes. The length may not exceed 2^18 bytes. Longer messages must be ignored.
|-
| 4 || checksum || uint32_t || First 4 bytes of sha512(payload)
|-
| ? || payload || uchar[] || The actual data, a [[#Message_types|message]] or an [[#Object_types|object]]
|}

Known magic values:

{|class="wikitable"
! Magic value !! Sent over wire as
|-
| 0xE9BEB4D9 || E9 BE B4 D9
|}

=== 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 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.

{|class="wikitable"
! Value !! Storage length !! Format
|-
| < 0xfd || 1 || uint8_t
|-
| <= 0xffff || 3 || 0xfd followed by the integer as uint16_t
|-
| <= 0xffffffff || 5 || 0xfe followed by the integer as uint32_t
|-
| - || 9 || 0xff followed by the integer as uint64_t
|}

=== Variable length string ===

Variable length string can be stored using a variable length integer followed by the string itself.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+ || length || [[Protocol_specification#Variable_length_integer|var_int]] || Length of the string
|-
| ? || string || char[] || The string itself (can be empty)
|}

=== Variable length list of integers===

n integers can be stored using n+1 [[Protocol_specification#Variable_length_integer|variable length integers]] where the first var_int equals n.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+ || count|| [[Protocol_specification#Variable_length_integer|var_int]] || Number of var_ints below
|-
| 1+ || || var_int || The first value stored
|-
| 1+ || || var_int || The second value stored...
|-
| 1+ || || var_int || etc...
|}

=== Network address ===

When a network address is needed somewhere, this structure is used. Network addresses are not prefixed with a timestamp or stream in the version message.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 (or 8)|| time || uint32 || the Time. Protocol version 1 clients use 4 byte time while protocol version 2 clients use 8 byte time.
|-
| 4 || stream|| uint32 || Stream number for this node
|-
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]
|-
| 16 || IPv6/4 || char[16] || IPv6 address. IPv4 addresses are written into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).
|-
| 2 || port || uint16_t || port number
|}

=== Inventory Vectors ===

Inventory vectors are used for notifying other nodes about objects they have or data which is being requested. Two rounds of SHA-512 are used, resulting in a 64 byte hash. Only the first 32 bytes are used; the later 32 bytes are ignored.

Inventory vectors consist of the following data format:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 32 || hash || char[32] || Hash of the object
|}

=== Encrypted payload ===

Bitmessage uses [https://en.wikipedia.org/wiki/Integrated_Encryption_Scheme ECIES] to encrypt its messages. For more information see [[Encryption]]

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 16||IV||uchar[]||Initialization Vector used for AES-256-CBC
|-
| 2||uint16_t||Curve type||Elliptic Curve type 0x02CA (714)
|-
| 2||uint16_t||X length||Length of X component of public key R
|-
| X length||uchar[]||X||X component of public key R
|-
| 2||uint16_t||Y length||Length of Y component of public key R
|-
| Y length||uchar[]||Y||Y component of public key R
|-
| ?||encrypted||uchar[]||Cipher text
|-
| 32||MAC|| uchar[]||HMACSHA256 Message Authentication Code
|}

=== Unencrypted Message Data ===

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+||msg_version||var_int||Message format version. This field is not included after the protocol v3 upgrade period.
|-
| 1+||address_version||var_int||Sender's address version number. This is needed in order to calculate the sender's address to show in the UI, and also to allow for forwards compatible changes to the public-key data included below.
|-
| 1+||stream||var_int||Sender's stream number
|-
| 4||behavior bitfield||uint32_t||A bitfield of optional behaviors and features that can be expected from the node with this pubkey included in this msg message (the sender's pubkey).
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|-
| 1+||nonce_trials_per_byte||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is the average number of nonce trials a node will have to perform to meet the Proof of Work requirement. 320 is the network minimum so any lower values will be automatically raised to 320. '''This field is new and is only included when the address_version >= 3.'''
|-
| 1+||extra_bytes||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is added to the data length to make sending small messages more difficult. 14000 is the network minimum so any lower values will be automatically raised to 14000. '''This field is new and is only included when the address_version >= 3.'''
|-
| 20||destination ripe||uchar[]||The ripe hash of the public key of the receiver of the message
|-
| 1+||encoding||var_int||[[Protocol_specification#Message_Encodings|Message Encoding]] type
|-
| 1+||message_length||var_int||Message Length
|-
| message_length||message||uchar[]||The message.
|-
| 1+||ack_length||var_int||Length of the acknowledgement data
|-
| ack_length||ack_data||uchar[]||The acknowledgement data to be transmitted. This takes the form of a Bitmessage protocol message, like another msg message. The POW therein must already be completed.
|-
| 1+||sig_length||var_int||Length of the signature
|-
| sig_length||signature||uchar[]||The ECDSA signature which covers everything from the msg_version to the ack_data.
|}

====Message Encodings====
{|class="wikitable"
! Value !! Name !! Description
|-
| 0 || IGNORE || Any data with this number may be ignored. The sending node might simply be sharing its public key with you.
|-
| 1 || TRIVIAL|| UTF-8. No 'Subject' or 'Body' sections. Useful for simple strings of data, like URIs or magnet links.
|-
| 2 || SIMPLE || UTF-8. Uses 'Subject' and 'Body' sections. No MIME is used.
<code>messageToTransmit = 'Subject:' + subject + '\n' + 'Body:' + message</code>
|}

Further values for the message encodings can be decided upon by the community. Any MIME or MIME-like encoding format, should they be used, should make use of Bitmessage's 8-bit bytes.

====Pubkey bitfield features====
{|class="wikitable"
! Bit!! Name !! Description
|-
| 0 || undefined || The most significant bit at the beginning of the structure. Undefined
|-
| 1 || undefined || The next most significant bit. Undefined
|-
| ... || ... || ...
|-
| 30 || include_destination || Receiving node expects that the RIPE hash encoded in their address preceedes the encrypted message data of msg messages bound for them.
|-
| 31 || does_ack|| If true, the receiving node does send acknowledgements (rather than dropping them).
|}

== 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.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || int32_t || Identifies protocol version being used by the node. Should equal 3. Nodes should disconnect if the remote node's version is lower but continue with the connection if it is higher.
|-
| 8 || services || uint64_t || bitfield of features to be enabled for this connection
|-
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds
|-
| 26 || addr_recv || net_addr || The network address of the node receiving this message (not including the time or stream number)
|-
| 26 || addr_from || net_addr || The network address of the node emitting this message (not including the time or stream number and the ip itself is ignored by the receiver)
|-
| 8 || nonce || uint64_t || Random nonce used to detect connections to self.
|-
| 1+ || user_agent || [[#Variable length string|var_str]] || [[User Agent]] (0x00 if string is 0 bytes long)
|-
| 1+ || stream numbers || [[#Variable length list of integers|var_int_list]] || The stream numbers that the emitting node is interested in.
|}

A "verack" packet shall be sent if the version packet was accepted. Once you have sent and received a verack messages with the remote node, send an addr message advertising up to 1000 peers of which you are aware, and one or more inv messages advertising all of the valid objects of which you are aware.

The following services are currently assigned:

{|class="wikitable"
! Value !! Name !! Description
|-
| 1 || NODE_NETWORK || This is a normal network node.
|}

=== verack ===

The ''verack'' message is sent in reply to ''version''. This message consists of only a [[#Message structure|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.

=== addr ===

Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours

Payload:
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+ || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of address entries (max: 1000)
|-
| 34x? || addr_list || [[Protocol_specification#Network_address|net_addr]] || Address of other nodes on the network.
|}

=== inv ===

Allows a node to advertise its knowledge of one or more objects.
Payload (maximum payload length: 50000 items):

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of inventory entries
|-
| 32x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors
|}

=== 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):

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of inventory entries
|-
| 32x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors
|}

=== 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|Proof Of Work]] must be done.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8||nonce||uint64_t||
Random nonce used for the [[Proof of work|Proof Of Work]]
|-
| 8||expiresTime||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 shared with peers until its end-of-life time has been reached. The node should store the inventory vector of that object for some extra period of time to avoid reloading it from another node with a small time delay. The time may be no further than 28 days + 3 hours in the future.
|-
| 4||objectType||uint32_t||
Four values are currently defined: 0-"getpubkey", 1-"pubkey", 2-"msg", 3-"broadcast". All other values are reserved. Nodes should relay objects even if they use an undefined object type.
|-
| 1+||version||var_int||The object's version. Note that msg objects won't contain a version until Sun, 16 Nov 2014 22:00:00 GMT.
|-
| 1+||stream number||var_int||The stream number in which this object may propagate
|-
| ?||payload||uchar[]||
This field varies depending on the object type; see below.
|-
|}

== 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.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 20||ripe||uchar[]||The ripemd hash of the public key. This field is only included when the address version is <= 3.
|-
| 32||tag||uchar[]||The tag derived from the address version, stream number, and ripe. This field is only included when the address version is >= 4.
|}

=== pubkey ===

A version 2 pubkey. This is still in use and supported by current clients but ''new'' v2 addresses are not generated by clients.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4||[[Protocol_specification#Pubkey_bitfield_features|behavior bitfield]]||uint32_t||A bitfield of optional behaviors and features that can be expected from the node receiving the message.
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|}

A version 3 pubkey

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4||[[Protocol_specification#Pubkey_bitfield_features|behavior bitfield]]||uint32_t||A bitfield of optional behaviors and features that can be expected from the node receiving the message.
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|-
| 1+||nonce_trials_per_byte||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is the average number of nonce trials a node will have to perform to meet the Proof of Work requirement. 320 is the network minimum so any lower values will be automatically raised to 320.
|-
| 1+||extra_bytes||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is added to the data length to make sending small messages more difficult. 14000 is the network minimum so any lower values will be automatically raised to 14000.
|-
| 1+||sig_length||var_int||Length of the signature
|-
| sig_length||signature||uchar[]||The ECDSA signature which, as of protocol v3, covers the object header starting with the time, appended with the data described in this table down to the extra_bytes.
|}

A version 4 pubkey

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 32||tag||uchar[]||The tag, made up of bytes 32-64 of the double hash of the address data (see example python code below)
|-
| ?||encrypted||uchar[]||Encrypted pubkey data.
|-
|}

When version 4 pubkeys are created, most of the data in the pubkey is encrypted. This is done in such a way that only someone who has the Bitmessage address which corresponds to a pubkey can decrypt and use that pubkey. This prevents people from gathering pubkeys sent around the network and using the data from them to create messages to be used in spam or in flooding attacks.

In order to encrypt the pubkey data, a double SHA-512 hash is calculated from the address version number, stream number, and ripe hash of the Bitmessage address that the pubkey corresponds to. The first 32 bytes of this hash are used to create a public and private key pair with which to encrypt and decrypt the pubkey data, using the same algorithm as message encryption (see [[Encryption]]). The remaining 32 bytes of this hash are added to the unencrypted part of the pubkey and used as a tag, as above. This allows nodes to determine which pubkey to decrypt when they wish to send a message.

In PyBitmessage, the double hash of the address data is calculated using the python code below:

doubleHashOfAddressData = hashlib.sha512(hashlib.sha512(encodeVarint(addressVersionNumber) + encodeVarint(streamNumber) + hash).digest()).digest()

Encrypted data in version 4 pubkeys:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
|-
| 4||[[Protocol_specification#Pubkey_bitfield_features|behavior bitfield]]||uint32_t||A bitfield of optional behaviors and features that can be expected from the node receiving the message.
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|-
| 1+||nonce_trials_per_byte||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is the average number of nonce trials a node will have to perform to meet the Proof of Work requirement. 320 is the network minimum so any lower values will be automatically raised to 320.
|-
| 1+||extra_bytes||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is added to the data length to make sending small messages more difficult. 14000 is the network minimum so any lower values will be automatically raised to 14000.
|-
| 1+||sig_length||var_int||Length of the signature
|-
| sig_length||signature||uchar[]||The ECDSA signature which covers everything from the object header starting with the time, then appended with the decrypted data down to the extra_bytes. This was changed in protocol v3. 
|}

=== 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.
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ?||encrypted||uchar[]||Encrypted data. See [[Protocol_specification#Encrypted_payload|Encrypted payload]]. See also [[Protocol_specification#Unencrypted_Message_Data|Unencrypted Message Data Format]]
|}

=== 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.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8 || POW nonce|| uint64_t|| The [[Proof of work|Proof Of Work]] nonce
|-
| 8 || time|| uint64_t|| The time that the message was broadcast.
|-
| 1+|| broadcast version|| var_int||The version number of this broadcast protocol message which is equal to 2 or 3. Changed to 4 or 5 for protocol v3.
|-
| 1+ || stream number|| var_int||The sender's stream number
|-
| 32 || tag|| uchar[]||The tag. This field is new and only included when the broadcast version is >= 5. Changed in protocol v3
|-
| ?||encrypted||uchar[]||Encrypted broadcast data. The keys are derived as described in the paragraph above. See [[Protocol_specification#Encrypted_payload|Encrypted payload]] for details about the encryption algorithm itself.
|}

Unencrypted data format:
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+|| broadcast version|| var_int||The version number of this broadcast protocol message which is equal to 2 or 3. This is included here so that it can be signed. This is no longer included in protocol v3
|-
| 1+ || address version|| var_int||The sender's address version
|-
| 1+ || stream number|| var_int||The sender's stream number
|-
| 4||[[Protocol_specification#Pubkey_bitfield_features|behavior bitfield]]||uint32_t||A bitfield of optional behaviors and features that can be expected from the owner of this pubkey.
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|-
| 1+||nonce_trials_per_byte||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is the average number of nonce trials a node will have to perform to meet the Proof of Work requirement. 320 is the network minimum so any lower values will be automatically raised to 320. This field is new and is only included when the address_version >= 3.
|-
| 1+||extra_bytes||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is added to the data length to make sending small messages more difficult. 14000 is the network minimum so any lower values will be automatically raised to 14000. This field is new and is only included when the address_version >= 3.
|-
| 1+ || [[Protocol_specification#Message_Encodings|encoding]]|| var_int||The [[Protocol_specification#Message_Encodings|encoding type]] of the message
|-
| 1+ ||messageLength || var_int||The message length in bytes
|-
| messageLength || message||uchar[] ||The message
|-
| 1+||sig_length||var_int||Length of the signature
|-
| sig_length|| signature||uchar[] ||The signature which did cover the unencrypted data from the broadcast version down through the message. In protocol v3, it covers the unencrypted object header starting with the time, all appended with the decrypted data.
|}

Protocol specification v3

2014-10-17T20:14:21Z

Atheros:

{{Template:Stub}}

{{Template:Proposal}}

== 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 the [[Protocol specification|current protocol specification]], which includes the version 3 changes, 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.

Here is an example address which uses malformed varints: BM-CVA3RC7Mvy7JDNSpQChktwrSe4KNMaEdDdcymfUo. This address is invalid.

== 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 specification#version|version 2 version message]].

=== verack ===

The verack message is identical to [[Protocol specification#verack|version 2 verack message]].

=== addr ===

The addr message is identical to [[Protocol specification#addr|version 2 addr message]].

=== inv ===

The inv message is identical to [[Protocol specification#inv|version 2 inv message]].

=== getdata ===

The getdata message is identical to [[Protocol specification#getdata|version 2 getdata message]].

=== error ===

Version 3 of the protocol defined a special error (or debug) message. 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.

{|class="wikitable"
! 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.
|-

|}

=== 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|Proof Of Work]] has to be done.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8||POW nonce||uint64_t||
Random nonce used for the [[Proof of work|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 refer to [[Protocol specification#Object_types|version 2 object types]]
|-
|}

== Proof of Work ==

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 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.

[[File:POW forumla 2.png|none|caption]]

payloadLengthExtraBytes = 1000

nonceTrialsPerByte = 1000

== 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 256 KiB(the payload of the object, starting from the POW nonce can have 262144 bytes at maximum).

Changelog

2014-10-17T20:13:09Z

Atheros:

== PyBitmessage Changelog ==

0.4.4

* Added ability to limit network transfer rate
* Updated to [[Protocol_specification_v3|Protocol Version 3]]
* Removed use of memoryview so that we can support python 2.7.3
* Make use of l10n for localizations

0.4.3

* Support pyelliptic's updated HMAC algorithm. We'll remove support for the old method after an upgrade period.
* Improved version check
* Refactored decodeBase58 function
* Ignore duplicate messages
* Added bytes received/sent counts and rate on the network information tab
* Fix unicode handling in 'View HTML code as formatted text'
* Refactor handling of packet headers
* Use pointMult function instead of arithmetic.privtopub since it is faster
* Fixed issue where client wasn't waiting for a verack before continuing on with the conversation
* Fixed CPU hogging by implementing tab-based refresh improvements
* Added curses interface
* Added support for IPv6
* Added a 'trustedpeer' option to keys.dat
* Limit maximum object size to 20 MB
* Support email-like > quote characters and reply-below-quote
* Added Japanese and Dutch language files; updated Norwegian and Russian languages files

0.4.2

* Added Norwegian, Chinese, and Arabic translations
* sock.sendall function isn't atomic. Let sendDataThread be the only thread which sends data.
* Moved API code to api.py
* Populate comboBoxSendFrom when replying
* Added option to show recent broadcasts when subscribing
* Fixed issue: If Windows username contained an international character, Bitmessage wouldn't start
* Added some code for FreeBSD compatibility
* Moved responsibility for processing network objects to the new ObjectProcessorThread
* Refactored main QT module
** Moved popup menus initialization to separate methods
** Simplified inbox loading
** Moved magic strings to the model scope constants so they won't be created every time.
* Updated list of defaultKnownNodes
* Fixed issue: [Linux] When too many messages arrive too quickly, exception occurs: "Exceeded maximum number of notifications"
* Fixed issue: creating then deleting an Address in short time crashes class_singleWorker.py
* Refactored code which displays messages to improve code readability
* load "Sent To" label from subscriptions if available
* Removed code to add chans to our address book as it is no longer necessary
* Added identicons
* Modified addresses.decodeAddress so that API command decodeAddress works properly
* Added API commands createChan, joinChan, leaveChan, deleteAddress
* In pyelliptic, check the return value of RAND_bytes to make sure enough random data was generated
* Don't store messages in UI table (and thus in memory), pull from SQL inventory as needed
* Fix typos in API commands addSubscription and getInboxMessagesByAddress
* Add feature in settings menu to give up resending a message after a specified period of time

0.4.1

* Fixed whitelist bug
* Fixed chan bug
** Added addressversion field to pubkeys table
** Sending messages to a chan no longer uses anything in the pubkeys table
** Sending messages to yourself is now fully supported
* Change _verifyAddress function to support v4 addresses

0.4.0

* Raised default demanded difficulty from 1 to 2 for new addresses
* Added v4 addresses: pubkeys are now encrypted and tagged in the inventory
* Use locks when accessing dictionary inventory
* Refactored the way inv and addr messages are shared
* Give user feedback when disk is full
* Added chan true/false to listAddresses results
* When replying using chan address, send to whole chan not just sender
* Refactored of the way PyBitmessage looks for interesting new objects in large inv messages from peers
* Show inventory lookup rate on Network Status tab
* Added SqlBulkExecute class so we can update inventory with only one commit
* Updated Russian translations
* Move duplicated SQL code into helper
* Allow specification of alternate settings dir via BITMESSAGE_HOME environment variable
* Removed use of gevent. Removed class_bgWorker.py
* Added Sip and PyQt to includes in build_osx.py
* Show number of each message type processed in the API command clientStatus
* Use fast PoW unless we're explicitly a frozen (binary) version of the code
* Enable user-set localization in settings
* Fix Archlinux package creation
* Fallback to language only localization when region doesn't match
* Fixed brew install instructions
* Added German translation
* Made inbox and sent messages table panels read-only
* Allow inbox and sent preview panels to resize
* Count RE: as a reply header, just like Re: so we don't chain Re: RE:
* Fix for traceback on OSX
* Added backend ability to understand shorter addresses
* Convert 'API Error' to raise APIError()
* Added option in settings to allow sending to a mobile device (app not yet done)
* Added ability to start daemon mode when using Bitmessage as a module
* Improved the way client detects locale
* Added API commands: getInboxMessageIds, getSentMessageIds, listAddressBookEntries, trashSentMessageByAckData, addAddressBookEntry, deleteAddressBookEntry, listAddresses2, listSubscriptions
* Set a maximum frequency for playing sounds
* Show Invalid Method error in same format as other API errors
* Update status of separate broadcasts separately even if the sent data is identical
* Added Namecoin integration
* Internally distinguish peers by IP and port
* Inbox message retrieval API functions now also returns read status

0.3.5

* Added right-click option to mark a message as unread
* Prompt user to connect at first startup
* Install into /usr/local by default
* Add a missing `rm -f` to the uninstall task.
* Use system text color for enabled addresses instead of black
* Added support for Chans
* Start storing msgid in sent table
* Optionally play sounds on connection/disconnection or when messages arrive
* Adding configuration option to listen for connections when using SOCKS
* Added packaging for multiple distros (Arch, Puppy, Slack, etc.)
* Added Russian translation
* Added search support in the UI
* Added 'make uninstall'
* To improve OSX support, use PKCS5_PBKDF2_HMAC_SHA1 if PKCS5_PBKDF2_HMAC is unavailable
* Added better warnings for OSX users who are using old versions of Python
* Repaired debian packaging
* Altered Makefile to avoid needing to chase changes
* Added logger module
* Added bgWorker class for background tasks
* Added use of gevent module
* On not-Windows: Fix insecure keyfile permissions
* Fix 100% CPU usage issue

0.3.4

* Linux: Store config files in $XDG_CONFIG_HOME
* Added a new global variable user option: doTimingAttackMitigation
* Moved a variety of classes and functions out of bitmessagemain.py and to their own modules
* New API command: getSentMessageByAckData
* Modified the getAllSentMessages and getSentMessageById commands to return ackData
* API commands to get messages now return actual encoding type
* Bugfix: Unicode chars in localtime prevented the gui from starting
* Added 'Save message as...' option in Inbox
* Added OS X Build scripts
* Added option to subscribe to an address in your address book
* Added getInboxMessageById API command
* Updated icons to have sRGB profile to prevent warnings
* Added French translation
* Switched addr, msg, broadcast, and getpubkey message types to 8 byte time. Last remaining type is pubkey.
* Added tooltips to show the full subject of messages
* Added Maximum Acceptable Difficulty fields in the settings
* Send out pubkey immediately after generating deterministic addresses rather than waiting for a request

0.3.3
* Remove inbox item from GUI when using API command trashMessage
* Add missing trailing semicolons to pybitmessage.desktop
* Ensure $(DESTDIR)/usr/bin exists
* Update Makefile to correct sandbox violations when built via Portage (Gentoo)
* Fix message authentication bug

0.3.211

* Removed multi-core proof of work as the multiprocessing module does not work well with pyinstaller's --onefile option.

0.3.2

* Bugfix: Remove remaining references to the old myapp.trayIcon
* Refactored message status-related code. API function getStatus now returns one of these strings: notfound, msgqueued, broadcastqueued, broadcastsent, doingpubkeypow, awaitingpubkey, doingmsgpow, msgsent, or ackreceived
* Moved proof of work to low-priority multi-threaded child processes
* Added menu option to delete all trashed messages
* Added inv flooding attack mitigation
* On Linux, when selecting Show Bitmessage, do not maximize automatically
* Store tray icons in bitmessage_icons_rc.py

0.3.1

* Added new API commands: getDeterministicAddress, addSubscription, deleteSubscription
* TCP Connection timeout for non-fully-established connections now 20 seconds
* Don't update the time we last communicated with a node unless the connection is fully established. This will allow us to forget about active but non-Bitmessage nodes which have made it into our knownNodes file.
* Prevent incoming connection flooding from crashing singleListener thread. Client will now only accept one connection per remote node IP
* Bugfix: Worker thread crashed when doing a POW to send out a v2 pubkey (bug introduced in 0.3.0)
* Wrap all sock.shutdown functions in error handlers
* Put all 'commit' commands within SQLLocks
* Bugfix: If address book label is blank, Bitmessage wouldn't show message (bug introduced in 0.3.0)
* Messaging menu item selects the oldest unread message
* Standardize on 'Quit' rather than 'Exit'
* [OSX] Try to seek homebrew installation of OpenSSL
* Prevent multiple instances of the application from running
* Show 'Connected' or 'Connection Lost' indicators
* Use only 9 half-open connections on Windows but 32 for everyone else
* Added appIndicator (a more functional tray icon) and Ubuntu Messaging Menu integration
* Changed Debian install directory and run script name based on Github issue #135

0.3.0

* Added new API function: getStatus
* Added error-handling around all sock.sendall() functions in the receiveData thread so that if there is a problem sending data, the threads will close gracefully
* Abandoned and removed the connectionsCount data structure; use the connectedHostsList instead because it has proved to be more accurate than trying to maintain the connectionsCount
* Added daemon mode. All UI code moved into a module and many shared objects moved into shared.py
* Truncate display of very long messages to avoid freezing the UI
* Added encrypted broadcasts for v3 addresses or v2 addresses after 2013-05-28 10:00 UTC
* No longer self.sock.close() from within receiveDataThreads, let the sendDataThreads do it
* Swapped out the v2 announcements subscription address for a v3 announcements subscription address
* Vacuum the messages.dat file once a month: will greatly reduce the file size
* Added a settings table in message.dat
* Implemented v3 addresses: pubkey messages must now include two var_ints: nonce_trials_per_byte and extra_bytes, and also be signed. When sending a message to a v3 address, the sender must use these values in calculating its POW or else the message will not be accepted by the receiver.
* Display a privacy warning when selecting 'Send Broadcast from this address'
* Added gitignore file
* Added code in preparation for a switch from 32-bit time to 64-bit time. Nodes will now advertise themselves as using protocol version 2.
* Don't necessarily delete entries from the inventory after 2.5 days; leave pubkeys there for 28 days so that we don't process the same ones many times throughout a month. This was causing the 'pubkeys processed' indicator on the 'Network Status' tab to not accurately reflect the number of truly new addresses on the network.
* Use 32 threads for outgoing connections in order to connect quickly
* Fix typo when calling os.environ in the sys.platform=='darwin' case
* Allow the cancelling of a message which is in the process of being sent by trashing it then restarting Bitmessage
* Bug fix: can't delete address from address book

0.2.8

* Fixed Ubuntu & OS X issue: Bitmessage wouldn't receive any objects from peers after restart.
* Inventory flush to disk when exiting program now vastly faster.
* Fixed address generation bug (kept Bitmessage from restarting).
* Improve deserialization of messages before processing.
* Change to help Macs find OpenSSL the way Unix systems find it.
* Do not share or accept IPs which are in the private IP ranges.
* Added time-fuzzing to the embedded time in pubkey and getpubkey messages.
* Added a knownNodes lock to prevent an exception from sometimes occurring when saving the data-structure to disk.
* Show unread messages in bold and do not display new messages automatically; let user click it.
* Support selecting multiple items in the inbox, sent box, and address book.
* Use delete key to trash Inbox or Sent messages.
* Display richtext(HTML) messages from senders in address book or subscriptions (although not pseudo-mailing-lists; use new right-click option).
* Support enabling and disabling subscriptions.
* Trim spaces from the beginning and end of addresses when adding to address book, subscriptions, and blacklist.
* Improved the display of the time for foreign language users.

0.2.7
* Added API. See [[API_Reference|API Reference]].
* Added error handling for the case where the client tries to send a message from an address for which the human has deleted the keys.
* Improved GUI messages when doing work (or pending work) for broadcast messages.
* Added error handling for the case where the proof of work takes no measurable time (caused a divide by zero error).

0.2.6
* New Feature: Pseudo-mailing-lists (available by right-clicking one of your addresses)
* New Feature: Portable Mode (available in the settings)
* Added missing context menu on the blacklist tab

0.2.5
* Bugfix-only release: Program improperly handles other nodes claiming to be in stream 0 (issue appeared when implementing IPv6). UI Freezes.

0.2.4
* Prevent user from sending messages to themselves since the client cannot process its own getpubkey or msg messages
* Do the pubkey POW and broadcast it directly after generating a new address

0.2.3
* Defined rules for nodes to follow for storing and relaying pubkeys. Nodes now store keys for 4 weeks then delete them. They also will not accept pubkeys older than 4 weeks; the owner will have to retransmit them if they are needed.
* Added 'fuzzing' to the time embedded in msg and broadcast messages.
* Added timing attack mitigation to the function that processes incoming pubkeys
* Added a new file: ''messages.dat reader.py'' which can be independently used to print information stored in the messages.dat file to the console.
* Users who run the software for the first time will now be subscribed by default to a Bitmessage address used to send announcements.

0.2.2
* Don't use DNS-based bootstrapping method if user is connecting via SOCKS; just skip it. Hopefully the nodes listed in defaultKnownNodes are still up.
* Implemented timing attack mitigation measure

0.2.1
* Added ability to send Sent items to the trash
* Keep track of which objects each peer is already aware and don't advertise objects that they already know about

0.2.0
* Major upgrade to ECC:
** Elliptic curve secp256k1 is used for Bitmessage's signing and asymetric encryption. Keys are interchangable between Bitmessage and Bitcoin.
** Keys stored in Wallet Import Format in the keys.dat file
** Deterministic addresses
** Addresses are now shorter: Bitmessage now supports 18 and 19 byte RIPE addresses where the missing 1 or 2 bytes are assumed to be zeros.
* Moved pubkey POW responsibility from the receiveData thread to the singleWorker thread

0.1.6
* Added DNS-based bootstrap method so that updating defaultKnownNodes doesn't require a code push.

0.1.5
* Client now checks whether a getpubkey message has the correct time before storing in inventory and also uses embeddedTime rather than system time (the way it is done for all other messages). This was a bug that didn't cause any ill-effect.
* Fix so that today's Bitmessage client will properly handle future versions of Bitmessage addresses
* Updated defaultKnownNodes
0.1.4
* Added support for SOCKS4a and SOCKS5 proxies
* Adjusted UI so that it looks appropriate on OS X
* Changed UI to accept Bitmessage addresses which lack a "BM-". This makes copying and pasting easier.
* Fixed OS X issue: if user minimized client to tray then restored, segmentation fault occured
* Added locks to prevent ill-effect if the client receives the same object from two different nodes at the exact same time
* Commented out code that prevents the client from accepting a second connection from the same IP since this prevents users from running two clients within the same local network. When the Bitmessage network grows, this code will be re-enabled.

0.1.3
* Updated defaultKnownNodes so people who download Bitmessage on a fresh machine can bootstrap
* Sort received-message-time by actual time rather than by time-interpreted-alphabetically

0.1.2
* Fixed line break display issue
* Updated defaultKnownNodes so people who download Bitmessage on a fresh machine can bootstrap
* Bug fix: If subject in received message contained international characters, reply button wouldn't work completely

0.1.1
* Fixed bug that prevented user from deleting a recently received message
* On the "Send" tab, select your address automatically if you have only one
* Rewrote the SQLite version check more liberally accept SQLite revision numbers
* Fixed "reply" functionality
* Removed PyObjc dependency for OSX

0.1.0
* Initial release

Changelog

2014-10-17T20:10:10Z

Atheros: v0.4.4

== PyBitmessage Changelog ==

0.4.4

* Added ability to limit network transfer rate
* Updated to Protocol Version 3
* Removed use of memoryview so that we can support python 2.7.3
* Make use of l10n for localizations

0.4.3

* Support pyelliptic's updated HMAC algorithm. We'll remove support for the old method after an upgrade period.
* Improved version check
* Refactored decodeBase58 function
* Ignore duplicate messages
* Added bytes received/sent counts and rate on the network information tab
* Fix unicode handling in 'View HTML code as formatted text'
* Refactor handling of packet headers
* Use pointMult function instead of arithmetic.privtopub since it is faster
* Fixed issue where client wasn't waiting for a verack before continuing on with the conversation
* Fixed CPU hogging by implementing tab-based refresh improvements
* Added curses interface
* Added support for IPv6
* Added a 'trustedpeer' option to keys.dat
* Limit maximum object size to 20 MB
* Support email-like > quote characters and reply-below-quote
* Added Japanese and Dutch language files; updated Norwegian and Russian languages files

0.4.2

* Added Norwegian, Chinese, and Arabic translations
* sock.sendall function isn't atomic. Let sendDataThread be the only thread which sends data.
* Moved API code to api.py
* Populate comboBoxSendFrom when replying
* Added option to show recent broadcasts when subscribing
* Fixed issue: If Windows username contained an international character, Bitmessage wouldn't start
* Added some code for FreeBSD compatibility
* Moved responsibility for processing network objects to the new ObjectProcessorThread
* Refactored main QT module
** Moved popup menus initialization to separate methods
** Simplified inbox loading
** Moved magic strings to the model scope constants so they won't be created every time.
* Updated list of defaultKnownNodes
* Fixed issue: [Linux] When too many messages arrive too quickly, exception occurs: "Exceeded maximum number of notifications"
* Fixed issue: creating then deleting an Address in short time crashes class_singleWorker.py
* Refactored code which displays messages to improve code readability
* load "Sent To" label from subscriptions if available
* Removed code to add chans to our address book as it is no longer necessary
* Added identicons
* Modified addresses.decodeAddress so that API command decodeAddress works properly
* Added API commands createChan, joinChan, leaveChan, deleteAddress
* In pyelliptic, check the return value of RAND_bytes to make sure enough random data was generated
* Don't store messages in UI table (and thus in memory), pull from SQL inventory as needed
* Fix typos in API commands addSubscription and getInboxMessagesByAddress
* Add feature in settings menu to give up resending a message after a specified period of time

0.4.1

* Fixed whitelist bug
* Fixed chan bug
** Added addressversion field to pubkeys table
** Sending messages to a chan no longer uses anything in the pubkeys table
** Sending messages to yourself is now fully supported
* Change _verifyAddress function to support v4 addresses

0.4.0

* Raised default demanded difficulty from 1 to 2 for new addresses
* Added v4 addresses: pubkeys are now encrypted and tagged in the inventory
* Use locks when accessing dictionary inventory
* Refactored the way inv and addr messages are shared
* Give user feedback when disk is full
* Added chan true/false to listAddresses results
* When replying using chan address, send to whole chan not just sender
* Refactored of the way PyBitmessage looks for interesting new objects in large inv messages from peers
* Show inventory lookup rate on Network Status tab
* Added SqlBulkExecute class so we can update inventory with only one commit
* Updated Russian translations
* Move duplicated SQL code into helper
* Allow specification of alternate settings dir via BITMESSAGE_HOME environment variable
* Removed use of gevent. Removed class_bgWorker.py
* Added Sip and PyQt to includes in build_osx.py
* Show number of each message type processed in the API command clientStatus
* Use fast PoW unless we're explicitly a frozen (binary) version of the code
* Enable user-set localization in settings
* Fix Archlinux package creation
* Fallback to language only localization when region doesn't match
* Fixed brew install instructions
* Added German translation
* Made inbox and sent messages table panels read-only
* Allow inbox and sent preview panels to resize
* Count RE: as a reply header, just like Re: so we don't chain Re: RE:
* Fix for traceback on OSX
* Added backend ability to understand shorter addresses
* Convert 'API Error' to raise APIError()
* Added option in settings to allow sending to a mobile device (app not yet done)
* Added ability to start daemon mode when using Bitmessage as a module
* Improved the way client detects locale
* Added API commands: getInboxMessageIds, getSentMessageIds, listAddressBookEntries, trashSentMessageByAckData, addAddressBookEntry, deleteAddressBookEntry, listAddresses2, listSubscriptions
* Set a maximum frequency for playing sounds
* Show Invalid Method error in same format as other API errors
* Update status of separate broadcasts separately even if the sent data is identical
* Added Namecoin integration
* Internally distinguish peers by IP and port
* Inbox message retrieval API functions now also returns read status

0.3.5

* Added right-click option to mark a message as unread
* Prompt user to connect at first startup
* Install into /usr/local by default
* Add a missing `rm -f` to the uninstall task.
* Use system text color for enabled addresses instead of black
* Added support for Chans
* Start storing msgid in sent table
* Optionally play sounds on connection/disconnection or when messages arrive
* Adding configuration option to listen for connections when using SOCKS
* Added packaging for multiple distros (Arch, Puppy, Slack, etc.)
* Added Russian translation
* Added search support in the UI
* Added 'make uninstall'
* To improve OSX support, use PKCS5_PBKDF2_HMAC_SHA1 if PKCS5_PBKDF2_HMAC is unavailable
* Added better warnings for OSX users who are using old versions of Python
* Repaired debian packaging
* Altered Makefile to avoid needing to chase changes
* Added logger module
* Added bgWorker class for background tasks
* Added use of gevent module
* On not-Windows: Fix insecure keyfile permissions
* Fix 100% CPU usage issue

0.3.4

* Linux: Store config files in $XDG_CONFIG_HOME
* Added a new global variable user option: doTimingAttackMitigation
* Moved a variety of classes and functions out of bitmessagemain.py and to their own modules
* New API command: getSentMessageByAckData
* Modified the getAllSentMessages and getSentMessageById commands to return ackData
* API commands to get messages now return actual encoding type
* Bugfix: Unicode chars in localtime prevented the gui from starting
* Added 'Save message as...' option in Inbox
* Added OS X Build scripts
* Added option to subscribe to an address in your address book
* Added getInboxMessageById API command
* Updated icons to have sRGB profile to prevent warnings
* Added French translation
* Switched addr, msg, broadcast, and getpubkey message types to 8 byte time. Last remaining type is pubkey.
* Added tooltips to show the full subject of messages
* Added Maximum Acceptable Difficulty fields in the settings
* Send out pubkey immediately after generating deterministic addresses rather than waiting for a request

0.3.3
* Remove inbox item from GUI when using API command trashMessage
* Add missing trailing semicolons to pybitmessage.desktop
* Ensure $(DESTDIR)/usr/bin exists
* Update Makefile to correct sandbox violations when built via Portage (Gentoo)
* Fix message authentication bug

0.3.211

* Removed multi-core proof of work as the multiprocessing module does not work well with pyinstaller's --onefile option.

0.3.2

* Bugfix: Remove remaining references to the old myapp.trayIcon
* Refactored message status-related code. API function getStatus now returns one of these strings: notfound, msgqueued, broadcastqueued, broadcastsent, doingpubkeypow, awaitingpubkey, doingmsgpow, msgsent, or ackreceived
* Moved proof of work to low-priority multi-threaded child processes
* Added menu option to delete all trashed messages
* Added inv flooding attack mitigation
* On Linux, when selecting Show Bitmessage, do not maximize automatically
* Store tray icons in bitmessage_icons_rc.py

0.3.1

* Added new API commands: getDeterministicAddress, addSubscription, deleteSubscription
* TCP Connection timeout for non-fully-established connections now 20 seconds
* Don't update the time we last communicated with a node unless the connection is fully established. This will allow us to forget about active but non-Bitmessage nodes which have made it into our knownNodes file.
* Prevent incoming connection flooding from crashing singleListener thread. Client will now only accept one connection per remote node IP
* Bugfix: Worker thread crashed when doing a POW to send out a v2 pubkey (bug introduced in 0.3.0)
* Wrap all sock.shutdown functions in error handlers
* Put all 'commit' commands within SQLLocks
* Bugfix: If address book label is blank, Bitmessage wouldn't show message (bug introduced in 0.3.0)
* Messaging menu item selects the oldest unread message
* Standardize on 'Quit' rather than 'Exit'
* [OSX] Try to seek homebrew installation of OpenSSL
* Prevent multiple instances of the application from running
* Show 'Connected' or 'Connection Lost' indicators
* Use only 9 half-open connections on Windows but 32 for everyone else
* Added appIndicator (a more functional tray icon) and Ubuntu Messaging Menu integration
* Changed Debian install directory and run script name based on Github issue #135

0.3.0

* Added new API function: getStatus
* Added error-handling around all sock.sendall() functions in the receiveData thread so that if there is a problem sending data, the threads will close gracefully
* Abandoned and removed the connectionsCount data structure; use the connectedHostsList instead because it has proved to be more accurate than trying to maintain the connectionsCount
* Added daemon mode. All UI code moved into a module and many shared objects moved into shared.py
* Truncate display of very long messages to avoid freezing the UI
* Added encrypted broadcasts for v3 addresses or v2 addresses after 2013-05-28 10:00 UTC
* No longer self.sock.close() from within receiveDataThreads, let the sendDataThreads do it
* Swapped out the v2 announcements subscription address for a v3 announcements subscription address
* Vacuum the messages.dat file once a month: will greatly reduce the file size
* Added a settings table in message.dat
* Implemented v3 addresses: pubkey messages must now include two var_ints: nonce_trials_per_byte and extra_bytes, and also be signed. When sending a message to a v3 address, the sender must use these values in calculating its POW or else the message will not be accepted by the receiver.
* Display a privacy warning when selecting 'Send Broadcast from this address'
* Added gitignore file
* Added code in preparation for a switch from 32-bit time to 64-bit time. Nodes will now advertise themselves as using protocol version 2.
* Don't necessarily delete entries from the inventory after 2.5 days; leave pubkeys there for 28 days so that we don't process the same ones many times throughout a month. This was causing the 'pubkeys processed' indicator on the 'Network Status' tab to not accurately reflect the number of truly new addresses on the network.
* Use 32 threads for outgoing connections in order to connect quickly
* Fix typo when calling os.environ in the sys.platform=='darwin' case
* Allow the cancelling of a message which is in the process of being sent by trashing it then restarting Bitmessage
* Bug fix: can't delete address from address book

0.2.8

* Fixed Ubuntu & OS X issue: Bitmessage wouldn't receive any objects from peers after restart.
* Inventory flush to disk when exiting program now vastly faster.
* Fixed address generation bug (kept Bitmessage from restarting).
* Improve deserialization of messages before processing.
* Change to help Macs find OpenSSL the way Unix systems find it.
* Do not share or accept IPs which are in the private IP ranges.
* Added time-fuzzing to the embedded time in pubkey and getpubkey messages.
* Added a knownNodes lock to prevent an exception from sometimes occurring when saving the data-structure to disk.
* Show unread messages in bold and do not display new messages automatically; let user click it.
* Support selecting multiple items in the inbox, sent box, and address book.
* Use delete key to trash Inbox or Sent messages.
* Display richtext(HTML) messages from senders in address book or subscriptions (although not pseudo-mailing-lists; use new right-click option).
* Support enabling and disabling subscriptions.
* Trim spaces from the beginning and end of addresses when adding to address book, subscriptions, and blacklist.
* Improved the display of the time for foreign language users.

0.2.7
* Added API. See [[API_Reference|API Reference]].
* Added error handling for the case where the client tries to send a message from an address for which the human has deleted the keys.
* Improved GUI messages when doing work (or pending work) for broadcast messages.
* Added error handling for the case where the proof of work takes no measurable time (caused a divide by zero error).

0.2.6
* New Feature: Pseudo-mailing-lists (available by right-clicking one of your addresses)
* New Feature: Portable Mode (available in the settings)
* Added missing context menu on the blacklist tab

0.2.5
* Bugfix-only release: Program improperly handles other nodes claiming to be in stream 0 (issue appeared when implementing IPv6). UI Freezes.

0.2.4
* Prevent user from sending messages to themselves since the client cannot process its own getpubkey or msg messages
* Do the pubkey POW and broadcast it directly after generating a new address

0.2.3
* Defined rules for nodes to follow for storing and relaying pubkeys. Nodes now store keys for 4 weeks then delete them. They also will not accept pubkeys older than 4 weeks; the owner will have to retransmit them if they are needed.
* Added 'fuzzing' to the time embedded in msg and broadcast messages.
* Added timing attack mitigation to the function that processes incoming pubkeys
* Added a new file: ''messages.dat reader.py'' which can be independently used to print information stored in the messages.dat file to the console.
* Users who run the software for the first time will now be subscribed by default to a Bitmessage address used to send announcements.

0.2.2
* Don't use DNS-based bootstrapping method if user is connecting via SOCKS; just skip it. Hopefully the nodes listed in defaultKnownNodes are still up.
* Implemented timing attack mitigation measure

0.2.1
* Added ability to send Sent items to the trash
* Keep track of which objects each peer is already aware and don't advertise objects that they already know about

0.2.0
* Major upgrade to ECC:
** Elliptic curve secp256k1 is used for Bitmessage's signing and asymetric encryption. Keys are interchangable between Bitmessage and Bitcoin.
** Keys stored in Wallet Import Format in the keys.dat file
** Deterministic addresses
** Addresses are now shorter: Bitmessage now supports 18 and 19 byte RIPE addresses where the missing 1 or 2 bytes are assumed to be zeros.
* Moved pubkey POW responsibility from the receiveData thread to the singleWorker thread

0.1.6
* Added DNS-based bootstrap method so that updating defaultKnownNodes doesn't require a code push.

0.1.5
* Client now checks whether a getpubkey message has the correct time before storing in inventory and also uses embeddedTime rather than system time (the way it is done for all other messages). This was a bug that didn't cause any ill-effect.
* Fix so that today's Bitmessage client will properly handle future versions of Bitmessage addresses
* Updated defaultKnownNodes
0.1.4
* Added support for SOCKS4a and SOCKS5 proxies
* Adjusted UI so that it looks appropriate on OS X
* Changed UI to accept Bitmessage addresses which lack a "BM-". This makes copying and pasting easier.
* Fixed OS X issue: if user minimized client to tray then restored, segmentation fault occured
* Added locks to prevent ill-effect if the client receives the same object from two different nodes at the exact same time
* Commented out code that prevents the client from accepting a second connection from the same IP since this prevents users from running two clients within the same local network. When the Bitmessage network grows, this code will be re-enabled.

0.1.3
* Updated defaultKnownNodes so people who download Bitmessage on a fresh machine can bootstrap
* Sort received-message-time by actual time rather than by time-interpreted-alphabetically

0.1.2
* Fixed line break display issue
* Updated defaultKnownNodes so people who download Bitmessage on a fresh machine can bootstrap
* Bug fix: If subject in received message contained international characters, reply button wouldn't work completely

0.1.1
* Fixed bug that prevented user from deleting a recently received message
* On the "Send" tab, select your address automatically if you have only one
* Rewrote the SQLite version check more liberally accept SQLite revision numbers
* Fixed "reply" functionality
* Removed PyObjc dependency for OSX

0.1.0
* Initial release

Template:Bitmessage Current Version Number

2014-10-17T19:59:45Z

Atheros: v0.4.4

0.4.4

Main Page

2014-10-17T19:59:24Z

Atheros:

__NOTOC__
{{Infobox
|name=Bitmessage
|downloadsite=https://bitmessage.org/download/windows/Bitmessage.exe
|release caption=Current version (Beta)
|latest release date=October 17, 2014
}}
Bitmessage is a P2P communications [[Protocol specification|protocol]] used to send encrypted messages to another person or to many subscribers. It is decentralized and trustless, meaning that you need-not inherently trust any entities like root certificate authorities. It uses strong authentication which means that the sender of a message cannot be spoofed, and it aims to hide "non-content" data, like the sender and receiver of messages, from passive eavesdroppers like those running warrantless wiretapping programs. If Bitmessage is completely new to you, you may wish to start by reading the [https://bitmessage.org/bitmessage.pdf whitepaper].

=== Download ===
An open source client is available for free under the very liberal [http://opensource.org/licenses/mit-license.php MIT license]. For screenshots and a description of the client, see this CryptoJunky article: [http://cryptojunky.com/blog/2013/03/09/setting-up-and-using-bitmessage-an-encrypted-communications-platform-based-on-bitcoin/ "Setting Up And Using Bitmessage"].

[[File:windows_icon.png|link=https://bitmessage.org/download/windows/Bitmessage.exe]] [https://bitmessage.org/download/windows/Bitmessage.exe Download for Windows]

[[File:apple_icon.png|link=https://bitmessage.org/download/osx/Bitmessage.dmg]] [https://bitmessage.org/download/osx/Bitmessage.dmg Download for OS X]

[[File:tux.png|link=Compiling_instructions]] [[Compiling instructions|Run the source code]]

=== Source code ===
You may view the Python [https://github.com/Bitmessage/PyBitmessage source code on Github]. Bitmessage requires PyQt and OpenSSL. Step-by-step instructions on how to run the source code on Linux, Windows, or OSX is [[Compiling instructions|available here]].

=== Security audit needed ===
Bitmessage is in need of an independent audit to verify its security. If you are a researcher capable of reviewing the source code, please [https://bitmessage.org/misc/emailaddress.png email] the lead developer. You will be helping to create a great privacy option for people everywhere!

=== Forum ===
* Visit or subscribe to the [https://pay.reddit.com/r/bitmessage Bitmessage subreddit].
* A community-based forum for questions, feedback, and discussion is also available at [https://bitmessage.org/forum Bitmessage.org/forum].

Main Page

2014-10-17T19:59:04Z

Atheros: Not necessary to show version numbers in the 'Download' section since they are all v0.4.4

__NOTOC__
{{Infobox
|name=Bitmessage
|downloadsite=https://bitmessage.org/download/windows/Bitmessage.exe
|release caption=Current version (Beta)
|latest release date=August 06, 2014
}}
Bitmessage is a P2P communications [[Protocol specification|protocol]] used to send encrypted messages to another person or to many subscribers. It is decentralized and trustless, meaning that you need-not inherently trust any entities like root certificate authorities. It uses strong authentication which means that the sender of a message cannot be spoofed, and it aims to hide "non-content" data, like the sender and receiver of messages, from passive eavesdroppers like those running warrantless wiretapping programs. If Bitmessage is completely new to you, you may wish to start by reading the [https://bitmessage.org/bitmessage.pdf whitepaper].

=== Download ===
An open source client is available for free under the very liberal [http://opensource.org/licenses/mit-license.php MIT license]. For screenshots and a description of the client, see this CryptoJunky article: [http://cryptojunky.com/blog/2013/03/09/setting-up-and-using-bitmessage-an-encrypted-communications-platform-based-on-bitcoin/ "Setting Up And Using Bitmessage"].

[[File:windows_icon.png|link=https://bitmessage.org/download/windows/Bitmessage.exe]] [https://bitmessage.org/download/windows/Bitmessage.exe Download for Windows]

[[File:apple_icon.png|link=https://bitmessage.org/download/osx/Bitmessage.dmg]] [https://bitmessage.org/download/osx/Bitmessage.dmg Download for OS X]

[[File:tux.png|link=Compiling_instructions]] [[Compiling instructions|Run the source code]]

=== Source code ===
You may view the Python [https://github.com/Bitmessage/PyBitmessage source code on Github]. Bitmessage requires PyQt and OpenSSL. Step-by-step instructions on how to run the source code on Linux, Windows, or OSX is [[Compiling instructions|available here]].

=== Security audit needed ===
Bitmessage is in need of an independent audit to verify its security. If you are a researcher capable of reviewing the source code, please [https://bitmessage.org/misc/emailaddress.png email] the lead developer. You will be helping to create a great privacy option for people everywhere!

=== Forum ===
* Visit or subscribe to the [https://pay.reddit.com/r/bitmessage Bitmessage subreddit].
* A community-based forum for questions, feedback, and discussion is also available at [https://bitmessage.org/forum Bitmessage.org/forum].

User:Atheros

2014-10-03T22:06:11Z

Atheros:

test11

Тест международных символов .
国际字符测试。

User:Atheros

2014-10-03T22:04:53Z

Atheros:

test11

Main Page

2014-08-29T18:28:40Z

Atheros: remove echo server since it doesn't seem to be working

__NOTOC__
{{Infobox
|name=Bitmessage
|downloadsite=https://bitmessage.org/download/windows/Bitmessage.exe
|release caption=Current version (Beta)
|latest release date=August 06, 2014
}}
Bitmessage is a P2P communications [[Protocol specification|protocol]] used to send encrypted messages to another person or to many subscribers. It is decentralized and trustless, meaning that you need-not inherently trust any entities like root certificate authorities. It uses strong authentication which means that the sender of a message cannot be spoofed, and it aims to hide "non-content" data, like the sender and receiver of messages, from passive eavesdroppers like those running warrantless wiretapping programs. If Bitmessage is completely new to you, you may wish to start by reading the [https://bitmessage.org/bitmessage.pdf whitepaper].

=== Download ===
An open source client is available for free under the very liberal [http://opensource.org/licenses/mit-license.php MIT license]. For screenshots and a description of the client, see this CryptoJunky article: [http://cryptojunky.com/blog/2013/03/09/setting-up-and-using-bitmessage-an-encrypted-communications-platform-based-on-bitcoin/ "Setting Up And Using Bitmessage"].

[[File:windows_icon.png|link=https://bitmessage.org/download/windows/Bitmessage.exe]] [https://bitmessage.org/download/windows/Bitmessage.exe Download for Windows] (v0.4.3)

[[File:apple_icon.png|link=https://bitmessage.org/download/osx/Bitmessage.dmg]] [https://bitmessage.org/download/osx/Bitmessage.dmg Download for OS X] (v0.4.2)

[[File:tux.png|link=Compiling_instructions]] [[Compiling instructions|Run the source code]] (v0.4.3)

=== Source code ===
You may view the Python [https://github.com/Bitmessage/PyBitmessage source code on Github]. Bitmessage requires PyQt and OpenSSL. Step-by-step instructions on how to run the source code on Linux, Windows, or OSX is [[Compiling instructions|available here]].

=== Security audit needed ===
Bitmessage is in need of an independent audit to verify its security. If you are a researcher capable of reviewing the source code, please [https://bitmessage.org/misc/emailaddress.png email] the lead developer. You will be helping to create a great privacy option for people everywhere!

=== Forum ===
* Visit or subscribe to the [https://pay.reddit.com/r/bitmessage Bitmessage subreddit].
* A community-based forum for questions, feedback, and discussion is also available at [https://bitmessage.org/forum Bitmessage.org/forum].

Protocol specification

2014-08-27T23:20:14Z

Atheros: Protocol V3 upgrade

All objects sent on the network should support protocol v3 starting on Sun, 16 Nov 2014 22:00:00 GMT. 

==Common standards==

=== Hashes ===

Most of the time [http://en.wikipedia.org/wiki/SHA-2 SHA-512] hashes are used, however [http://en.wikipedia.org/wiki/RIPEMD RIPEMD-160] is also used when creating an address.

A double-round of SHA-512 is used for the Proof Of Work. Example of double-SHA-512 encoding of string "hello":

hello
9b71d224bd62f3785d96d46ad3ea3d73319bfbc2890caadae2dff72519673ca72323c3d99ba5c11d7c7acc6e14b8c5da0c4663475c2e5c3adef46f73bcdec043(first round of sha-512)
0592a10584ffabf96539f3d780d776828c67da1ab5b169e9e8aed838aaecc9ed36d49ff1423c55f019e050c66c6324f53588be88894fef4dcffdb74b98e2b200(second round of sha-512)

For Bitmessage addresses (RIPEMD-160) this would give:

hello
9b71d224bd62f3785d96d46ad3ea3d73319bfbc2890caadae2dff72519673ca72323c3d99ba5c11d7c7acc6e14b8c5da0c4663475c2e5c3adef46f73bcdec043(first round is sha-512)
79a324faeebcbf9849f310545ed531556882487e (with ripemd-160)

== Common structures ==

All integers are encoded in big endian. (This is different from Bitcoin).

=== Message structure ===

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || magic || uint32_t || Magic value indicating message origin network, and used to seek to next message when stream state is unknown
|-
| 12 || command || char[12] || ASCII string identifying the packet content, NULL padded (non-NULL padding results in packet rejected)
|-
| 4 || length || uint32_t || Length of payload in number of bytes. The length may not exceed 2^18 bytes. Longer messages must be ignored.
|-
| 4 || checksum || uint32_t || First 4 bytes of sha512(payload)
|-
| ? || payload || uchar[] || The actual data, a [[#Message_types|message]] or an [[#Object_types|object]]
|}

Known magic values:

{|class="wikitable"
! Magic value !! Sent over wire as
|-
| 0xE9BEB4D9 || E9 BE B4 D9
|}

=== 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 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.

{|class="wikitable"
! Value !! Storage length !! Format
|-
| < 0xfd || 1 || uint8_t
|-
| <= 0xffff || 3 || 0xfd followed by the integer as uint16_t
|-
| <= 0xffffffff || 5 || 0xfe followed by the integer as uint32_t
|-
| - || 9 || 0xff followed by the integer as uint64_t
|}

=== Variable length string ===

Variable length string can be stored using a variable length integer followed by the string itself.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+ || length || [[Protocol_specification#Variable_length_integer|var_int]] || Length of the string
|-
| ? || string || char[] || The string itself (can be empty)
|}

=== Variable length list of integers===

n integers can be stored using n+1 [[Protocol_specification#Variable_length_integer|variable length integers]] where the first var_int equals n.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+ || count|| [[Protocol_specification#Variable_length_integer|var_int]] || Number of var_ints below
|-
| 1+ || || var_int || The first value stored
|-
| 1+ || || var_int || The second value stored...
|-
| 1+ || || var_int || etc...
|}

=== Network address ===

When a network address is needed somewhere, this structure is used. Network addresses are not prefixed with a timestamp or stream in the version message.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 (or 8)|| time || uint32 || the Time. Protocol version 1 clients use 4 byte time while protocol version 2 clients use 8 byte time.
|-
| 4 || stream|| uint32 || Stream number for this node
|-
| 8 || services || uint64_t || same service(s) listed in [[#version|version]]
|-
| 16 || IPv6/4 || char[16] || IPv6 address. IPv4 addresses are written into the message as a 16 byte [http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses IPv4-mapped IPv6 address]
(12 bytes ''00 00 00 00 00 00 00 00 00 00 FF FF'', followed by the 4 bytes of the IPv4 address).
|-
| 2 || port || uint16_t || port number
|}

=== Inventory Vectors ===

Inventory vectors are used for notifying other nodes about objects they have or data which is being requested. Two rounds of SHA-512 are used, resulting in a 64 byte hash. Only the first 32 bytes are used; the later 32 bytes are ignored.

Inventory vectors consist of the following data format:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 32 || hash || char[32] || Hash of the object
|}

=== Encrypted payload ===

Bitmessage uses [https://en.wikipedia.org/wiki/Integrated_Encryption_Scheme ECIES] to encrypt its messages. For more information see [[Encryption]]

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 16||IV||uchar[]||Initialization Vector used for AES-256-CBC
|-
| 2||uint16_t||Curve type||Elliptic Curve type 0x02CA (714)
|-
| 2||uint16_t||X length||Length of X component of public key R
|-
| X length||uchar[]||X||X component of public key R
|-
| 2||uint16_t||Y length||Length of Y component of public key R
|-
| Y length||uchar[]||Y||Y component of public key R
|-
| ?||encrypted||uchar[]||Cipher text
|-
| 32||MAC|| uchar[]||HMACSHA256 Message Authentication Code
|}

=== Unencrypted Message Data ===

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+||msg_version||var_int||Message format version. This field is not included after the protocol v3 upgrade period.
|-
| 1+||address_version||var_int||Sender's address version number. This is needed in order to calculate the sender's address to show in the UI, and also to allow for forwards compatible changes to the public-key data included below.
|-
| 1+||stream||var_int||Sender's stream number
|-
| 4||behavior bitfield||uint32_t||A bitfield of optional behaviors and features that can be expected from the node with this pubkey included in this msg message (the sender's pubkey).
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|-
| 1+||nonce_trials_per_byte||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is the average number of nonce trials a node will have to perform to meet the Proof of Work requirement. 320 is the network minimum so any lower values will be automatically raised to 320. '''This field is new and is only included when the address_version >= 3.'''
|-
| 1+||extra_bytes||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is added to the data length to make sending small messages more difficult. 14000 is the network minimum so any lower values will be automatically raised to 14000. '''This field is new and is only included when the address_version >= 3.'''
|-
| 20||destination ripe||uchar[]||The ripe hash of the public key of the receiver of the message
|-
| 1+||encoding||var_int||[[Protocol_specification#Message_Encodings|Message Encoding]] type
|-
| 1+||message_length||var_int||Message Length
|-
| message_length||message||uchar[]||The message.
|-
| 1+||ack_length||var_int||Length of the acknowledgement data
|-
| ack_length||ack_data||uchar[]||The acknowledgement data to be transmitted. This takes the form of a Bitmessage protocol message, like another msg message. The POW therein must already be completed.
|-
| 1+||sig_length||var_int||Length of the signature
|-
| sig_length||signature||uchar[]||The ECDSA signature which covers everything from the msg_version to the ack_data.
|}

====Message Encodings====
{|class="wikitable"
! Value !! Name !! Description
|-
| 0 || IGNORE || Any data with this number may be ignored. The sending node might simply be sharing its public key with you.
|-
| 1 || TRIVIAL|| UTF-8. No 'Subject' or 'Body' sections. Useful for simple strings of data, like URIs or magnet links.
|-
| 2 || SIMPLE || UTF-8. Uses 'Subject' and 'Body' sections. No MIME is used.
<code>messageToTransmit = 'Subject:' + subject + '\n' + 'Body:' + message</code>
|}

Further values for the message encodings can be decided upon by the community. Any MIME or MIME-like encoding format, should they be used, should make use of Bitmessage's 8-bit bytes.

====Pubkey bitfield features====
{|class="wikitable"
! Bit!! Name !! Description
|-
| 0 || undefined || The most significant bit at the beginning of the structure. Undefined
|-
| 1 || undefined || The next most significant bit. Undefined
|-
| ... || ... || ...
|-
| 30 || include_destination || Receiving node expects that the RIPE hash encoded in their address preceedes the encrypted message data of msg messages bound for them.
|-
| 31 || does_ack|| If true, the receiving node does send acknowledgements (rather than dropping them).
|}

== 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.

Payload:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4 || version || int32_t || Identifies protocol version being used by the node. Should equal 3. Nodes should disconnect if the remote node's version is lower but continue with the connection if it is higher.
|-
| 8 || services || uint64_t || bitfield of features to be enabled for this connection
|-
| 8 || timestamp || int64_t || standard UNIX timestamp in seconds
|-
| 26 || addr_recv || net_addr || The network address of the node receiving this message (not including the time or stream number)
|-
| 26 || addr_from || net_addr || The network address of the node emitting this message (not including the time or stream number and the ip itself is ignored by the receiver)
|-
| 8 || nonce || uint64_t || Random nonce used to detect connections to self.
|-
| 1+ || user_agent || [[#Variable length string|var_str]] || [[User Agent]] (0x00 if string is 0 bytes long)
|-
| 1+ || stream numbers || [[#Variable length list of integers|var_int_list]] || The stream numbers that the emitting node is interested in.
|}

A "verack" packet shall be sent if the version packet was accepted. Once you have sent and received a verack messages with the remote node, send an addr message advertising up to 1000 peers of which you are aware, and one or more inv messages advertising all of the valid objects of which you are aware.

The following services are currently assigned:

{|class="wikitable"
! Value !! Name !! Description
|-
| 1 || NODE_NETWORK || This is a normal network node.
|}

=== verack ===

The ''verack'' message is sent in reply to ''version''. This message consists of only a [[#Message structure|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.

=== addr ===

Provide information on known nodes of the network. Non-advertised nodes should be forgotten after typically 3 hours

Payload:
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+ || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of address entries (max: 1000)
|-
| 34x? || addr_list || [[Protocol_specification#Network_address|net_addr]] || Address of other nodes on the network.
|}

=== inv ===

Allows a node to advertise its knowledge of one or more objects.
Payload (maximum payload length: 50000 items):

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of inventory entries
|-
| 32x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors
|}

=== 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):

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ? || count || [[Protocol_specification#Variable_length_integer|var_int]] || Number of inventory entries
|-
| 32x? || inventory || [[Protocol specification#Inventory Vectors|inv_vect]][] || Inventory vectors
|}

=== 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|Proof Of Work]] must be done.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8||nonce||uint64_t||
Random nonce used for the [[Proof of work|Proof Of Work]]
|-
| 8||expiresTime||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 shared with peers until its end-of-life time has been reached. The node should store the inventory vector of that object for some extra period of time to avoid reloading it from another node with a small time delay. The time may be no further than 28 days + 3 hours in the future.
|-
| 4||objectType||uint32_t||
Four values are currently defined: 0-"getpubkey", 1-"pubkey", 2-"msg", 3-"broadcast". All other values are reserved. Nodes should relay objects even if they use an undefined object type.
|-
| 1+||version||var_int||The object's version. Note that msg objects won't contain a version until Sun, 16 Nov 2014 22:00:00 GMT.
|-
| 1+||stream number||var_int||The stream number in which this object may propagate
|-
| ?||payload||uchar[]||
This field varies depending on the object type; see below.
|-
|}

== 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.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 20||ripe||uchar[]||The ripemd hash of the public key. This field is only included when the address version is <= 3.
|-
| 32||tag||uchar[]||The tag derived from the address version, stream number, and ripe. This field is only included when the address version is >= 4.
|}

=== pubkey ===

A version 2 pubkey. This is still in use and supported by current clients but ''new'' v2 addresses are not generated by clients.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4||[[Protocol_specification#Pubkey_bitfield_features|behavior bitfield]]||uint32_t||A bitfield of optional behaviors and features that can be expected from the node receiving the message.
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|}

A version 3 pubkey

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 4||[[Protocol_specification#Pubkey_bitfield_features|behavior bitfield]]||uint32_t||A bitfield of optional behaviors and features that can be expected from the node receiving the message.
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|-
| 1+||nonce_trials_per_byte||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is the average number of nonce trials a node will have to perform to meet the Proof of Work requirement. 320 is the network minimum so any lower values will be automatically raised to 320.
|-
| 1+||extra_bytes||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is added to the data length to make sending small messages more difficult. 14000 is the network minimum so any lower values will be automatically raised to 14000.
|-
| 1+||sig_length||var_int||Length of the signature
|-
| sig_length||signature||uchar[]||The ECDSA signature which, as of protocol v3, covers the object header starting with the time, appended with the data described in this table down to the extra_bytes.
|}

A version 4 pubkey

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 32||tag||uchar[]||The tag, made up of bytes 32-64 of the double hash of the address data (see example python code below)
|-
| ?||encrypted||uchar[]||Encrypted pubkey data.
|-
|}

When version 4 pubkeys are created, most of the data in the pubkey is encrypted. This is done in such a way that only someone who has the Bitmessage address which corresponds to a pubkey can decrypt and use that pubkey. This prevents people from gathering pubkeys sent around the network and using the data from them to create messages to be used in spam or in flooding attacks.

In order to encrypt the pubkey data, a double SHA-512 hash is calculated from the address version number, stream number, and ripe hash of the Bitmessage address that the pubkey corresponds to. The first 32 bytes of this hash are used to create a public and private key pair with which to encrypt and decrypt the pubkey data, using the same algorithm as message encryption (see [[Encryption]]). The remaining 32 bytes of this hash are added to the unencrypted part of the pubkey and used as a tag, as above. This allows nodes to determine which pubkey to decrypt when they wish to send a message.

In PyBitmessage, the double hash of the address data is calculated using the python code below:

doubleHashOfAddressData = hashlib.sha512(hashlib.sha512(encodeVarint(addressVersionNumber) + encodeVarint(streamNumber) + hash).digest()).digest()

Encrypted data in version 4 pubkeys:

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
|-
| 4||[[Protocol_specification#Pubkey_bitfield_features|behavior bitfield]]||uint32_t||A bitfield of optional behaviors and features that can be expected from the node receiving the message.
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|-
| 1+||nonce_trials_per_byte||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is the average number of nonce trials a node will have to perform to meet the Proof of Work requirement. 320 is the network minimum so any lower values will be automatically raised to 320.
|-
| 1+||extra_bytes||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is added to the data length to make sending small messages more difficult. 14000 is the network minimum so any lower values will be automatically raised to 14000.
|-
| 1+||sig_length||var_int||Length of the signature
|-
| sig_length||signature||uchar[]||The ECDSA signature which covers everything from the object header starting with the time, then appended with the decrypted data down to the extra_bytes. This was changed in protocol v3. 
|}

=== 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.
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| ?||encrypted||uchar[]||Encrypted data. See [[Protocol_specification#Encrypted_payload|Encrypted payload]]. See also [[Protocol_specification#Unencrypted_Message_Data|Unencrypted Message Data Format]]
|}

=== 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 v3 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.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8 || POW nonce|| uint64_t|| The [[Proof of work|Proof Of Work]] nonce
|-
| 8 || time|| uint64_t|| The time that the message was broadcast.
|-
| 1+|| broadcast version|| var_int||The version number of this broadcast protocol message which is equal to 2 or 3. Changed to 4 or 5 for protocol v3.
|-
| 1+ || stream number|| var_int||The sender's stream number
|-
| 32 || tag|| uchar[]||The tag. This field is new and only included when the broadcast version is >= 5. Changed in protocol v3
|-
| ?||encrypted||uchar[]||Encrypted broadcast data. The keys are derived as described in the paragraph above. See [[Protocol_specification#Encrypted_payload|Encrypted payload]] for details about the encryption algorithm itself.
|}

Unencrypted data format:
{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 1+|| broadcast version|| var_int||The version number of this broadcast protocol message which is equal to 2 or 3. This is included here so that it can be signed. This is no longer included in protocol v3
|-
| 1+ || address version|| var_int||The sender's address version
|-
| 1+ || stream number|| var_int||The sender's stream number
|-
| 4||[[Protocol_specification#Pubkey_bitfield_features|behavior bitfield]]||uint32_t||A bitfield of optional behaviors and features that can be expected from the owner of this pubkey.
|-
| 64||public signing key||uchar[]||The ECC public key used for signing (uncompressed format; normally prepended with \x04 )
|-
| 64||public encryption key||uchar[]||The ECC public key used for encryption (uncompressed format; normally prepended with \x04 )
|-
| 1+||nonce_trials_per_byte||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is the average number of nonce trials a node will have to perform to meet the Proof of Work requirement. 320 is the network minimum so any lower values will be automatically raised to 320. This field is new and is only included when the address_version >= 3.
|-
| 1+||extra_bytes||var_int||Used to calculate the difficulty target of messages accepted by this node. The higher this value, the more difficult the Proof of Work must be before this individual will accept the message. This number is added to the data length to make sending small messages more difficult. 14000 is the network minimum so any lower values will be automatically raised to 14000. This field is new and is only included when the address_version >= 3.
|-
| 1+ || [[Protocol_specification#Message_Encodings|encoding]]|| var_int||The [[Protocol_specification#Message_Encodings|encoding type]] of the message
|-
| 1+ ||messageLength || var_int||The message length in bytes
|-
| messageLength || message||uchar[] ||The message
|-
| 1+||sig_length||var_int||Length of the signature
|-
| sig_length|| signature||uchar[] ||The signature which did cover the unencrypted data from the broadcast version down through the message. In protocol v3, it covers the unencrypted object header starting with the time, all appended with the decrypted data.
|}

API Reference

2014-08-27T20:09:35Z

Atheros: API Error 0027: Message is too long.

=== Introduction ===

The PyBitmessage API uses [http://en.wikipedia.org/wiki/XML-RPC XML-RPC].

=== Enable the API ===
To enable the API, copy and paste these lines into the bitmessagesettings section of the [[keys.dat]] file.
Note that the values "username" and "password" below are merely examples, and should be replaced by values that cannot feasibly be guessed:
<pre>
apienabled = true
apiport = 8442
apiinterface = 127.0.0.1
apiusername = username
apipassword = password
</pre>
Additionally, you may optionally include an additional entry which will specify a program which Bitmessage will run when certain events occur.
<pre>
apinotifypath = c:\\example\\example.exe
</pre>
One of these arguments will be passed to your program: startingUp, newMessage, newBroadcast. Be sure your program doesn't crash when given newer arguments introduced in the future as this list will likely expand.

=== Remote Access ===
To access the Bitmessage API from a remote location, change the apiinterface value from '''127.0.0.1''' to '''0.0.0.0'''.

The following Python code offers a demonstration of how to create a client that can connect to the PyBitmessage API.

In this example, the username is "username", the password is "password", the IP address of the server running PyBitmessage is 105.168.1.0 (a random example), and the port number which PyBitmessage has been configured to listen on is 8442. In order to connect with the remote copy of PyBitmessage, these settings must match those in PyBitmessage's "keys.dat" file.
<pre>
import xmlrpclib
import json
import time

api = xmlrpclib.ServerProxy("http://username:password@105.168.1.0:8442/")
print api.add(2,3)
</pre>

A more complete example can be found in the [https://github.com/Bitmessage/PyBitmessage/blob/master/src/api_client.py api_client.py] file in the PyBitmessage source code.

=== List of Operations ===
Required arguments are denoted inside < and > Optional arguments are inside [ and ].
{|class="wikitable"
! Command !! Parameters !! Minimum Version !! Description
|-
| helloWorld || <firstWord> <secondWord> || 0.2.7 || returns 'firstWord-secondWord'. Used as a simple test of the API.
|-
| add || <integer> <integer> || 0.2.7 || returns the sum of the integers. Used as a simple test of the API.
|-
| statusBar || <message> || 0.2.7 || Displays the message in the status bar on the GUI
|-
| listAddresses2|| || 0.4.0 || Lists all addresses shown on the Your Identities tab. Returns a list of objects with these properties:
* label (base64, decodes into utf-8)
* address (ascii/utf-8)
* stream (integer)
* enabled (bool)
* chan (bool)

This is called listAddresses'''2''' because 'listAddresses' is obsolete.
|-
| createRandomAddress || <label> [eighteenByteRipe] [totalDifficulty] [smallMessageDifficulty] || 0.2.7 || Creates one address using the random number generator. label should be base64 encoded. eighteenByteRipe is a boolean telling Bitmessage whether to generate an address with an 18 byte RIPE hash(as opposed to a 19 byte hash). This is the same setting as the "Do extra work to make the address 1 or 2 characters shorter" in the user interface. Using False is recommended if you are running some sort of website and will be generating a lot of addresses. Note that even if you don't ask for it, there is still a 1 in 256 chance that you will get an address with an 18 byte RIPE hash so if you actually ''need'' an address with a 19 byte RIPE hash for some reason, you will need to check for it. eighteenByteRipe defaults to False. totalDifficulty and smallMessageDifficulty default to 1.

Returns the address.

Warning: At present, Bitmessage gets confused if you use both the API and the UI to make an address at the same time.
|-
|createDeterministicAddresses ||<passphrase> [numberOfAddresses] [addressVersionNumber] [streamNumber] [eighteenByteRipe] [totalDifficulty] [smallMessageDifficulty] || 0.3.4 || Similar to createRandomAddress except that you may generate many addresses in one go. passphrase should be base64 encoded. numberOfAddresses defaults to 1. addressVersionNumber and streamNumber may be set to 0 which will tell Bitmessage to use the most up-to-date addressVersionNumber and the most available streamNumber. Using zero for each of these fields is recommended. eighteenByteRipe defaults to False. totalDifficulty and smallMessageDifficulty default to 1.

Returns a list of new addresses. This list will be empty if the addresses already existed.

Warning: At present, Bitmessage gets confused if you use both the API and the UI to make addresses at the same time.
|-
|getDeterministicAddress ||<passphrase> <addressVersionNumber> <streamNumber> || 0.3.1 || Similar to createDeterministicAddresses except that the one address that is returned will not be added to the Bitmessage user interface or the keys.dat file. passphrase should be base64 encoded. addressVersionNumber should be set to 3 or 4 as these are the only ones currently supported. streamNumber must be set to 1 as this is the only one currently supported.

Returns a single address.

Warning: At present, Bitmessage gets confused if you use both this API command and the UI to make addresses at the same time.
|-
|<code>getAllInboxMessages</code>|| || 0.2.7 || Does not include trashed messages. Returns a list of objects with these properties:
* msgid (hex)
* toAddress (ascii/utf-8)
* fromAddress (ascii/utf-8)
* subject (base64, decodes into utf-8)
* message (base64, decodes into utf-8)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* receivedTime (integer, Unix time)
* read (integer representing binary state (0 or 1))

The msgid is the same as the hash of the message (analogous to the TXID in Bitcoin) thus it is shown in hex as that is the de facto standard. The base64 encoding Bitmessage uses includes line breaks including one on the end of the string.
|-
|<code>getAllInboxMessageIDs</code>|| || 0.2.7 || Returns a list of msgids of all Inbox messages with there properties:
* msgid (hex)
|-
| getInboxMessageByID || <msgid> [read] || 0.4.0 || Returns an object with these properties:
* msgid (hex)
* toAddress (ascii/utf-8)
* fromAddress (ascii/utf-8)
* subject (base64, decodes into utf-8)
* message (base64, decodes into utf-8)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* receivedTime (integer, Unix time)
* read (integer representing binary state (0 or 1))

Optionally sets the specific message to have a read status of 'read' (bool).

The msgid is the same as the hash of the message (analogous to the TXID in Bitcoin) thus it should be given in hex as that is the de facto standard. The base64 encoding Bitmessage uses includes line breaks including one on the end of the string.
|-
| getSentMessageByAckData || <ackData> || 0.3.4 || Returns an object with these properties:
* msgid (hex)
* toAddress (ascii/utf-8)
* fromAddress (ascii/utf-8)
* subject (base64, decodes into utf-8)
* message (base64, decodes into utf-8)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* lastActionTime (integer, Unix time)
* status (ascii/utf-8)
* ackData (hex)
|-
| getAllSentMessages || || 0.3.4 || Returns an object with these properties:
* msgid (hex)
* toAddress (ascii/utf-8)
* fromAddress (ascii/utf-8)
* subject (base64, decodes into utf-8)
* message (base64, decodes into utf-8)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* lastActionTime (integer, Unix time)
* status (ascii/utf-8)
* ackData (hex)
|-
| getSentMessageByID || <msgid> || 0.3.4 || Returns an object with these properties:
* msgid (hex)
* toAddress (ascii/utf-8)
* fromAddress (ascii/utf-8)
* subject (base64, decodes into utf-8)
* message (base64, decodes into utf-8)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* lastActionTime (integer, Unix time)
* status (ascii/utf-8)
* ackData (hex)
|-
| getSentMessagesBySender|| <fromAddress> || 0.3.4 || Returns a list of objects with these properties:
* msgid (hex)
* toAddress (ascii/utf-8)
* fromAddress (ascii/utf-8)
* subject (base64, decodes into utf-8)
* message (base64, decodes into utf-8)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* lastActionTime (integer, Unix time)
* status (ascii/utf-8)
* ackData (hex)
|-
| trashMessage || <msgid> || 0.2.7 || returns a simple message saying that the message was trashed assuming it ever even existed. Prior existence is not checked. msgid is encoded in hex just like in the getAllInboxMessages function.
|-
| sendMessage || <toAddress> <fromAddress> <subject> <message> [encodingType] || 0.2.7 || returns ackdata encoded in hex. subject and message must be encoded in base64 which may optionally include line breaks. If used, the encodingType must be set to 2; this is included for forwards compatibility.
|-
| sendBroadcast || <fromAddress> <subject> <message> [encodingType] || 0.2.7 || returns ackData encoded in hex. subject and message must be encoded in base64. If used, the encodingType must be set to 2; this is included for forwards compatibility.
|-
| getStatus || <ackData> || 0.3.0 || returns one of these strings: <strike>notFound, findingPubkey, doingPOW, sentMessage, or ackReceived</strike> notfound, msgqueued, broadcastqueued, broadcastsent, doingpubkeypow, awaitingpubkey, doingmsgpow, forcepow, msgsent, msgsentnoackexpected, or ackreceived.
|-
| listSubscriptions|| || 0.4.0 || Returns a list of objects with these properties:
* label (base64, decodes into utf-8)
* address (ascii/utf-8)
* enabled (bool)
|-
| addSubscription|| <address> [label] || 0.3.1 || Subscribe to an address. label must be base64-encoded.
|-
| deleteSubscription|| <address> || 0.3.1 || Unsubscribe from an address. The program does not check to see whether you were subscribed in the first place.
|-
| listAddressBookEntries|| || 0.4.0 ||Returns a list of objects with these properties:
* address (ascii/utf-8)
* label (base64, decodes into utf-8)
|-
| addAddressBookEntry|| <address> <label> || 0.4.0 || Add an entry to your address book. label must be base64-encoded.
|-
| deleteAddressBookEntry|| <address> || 0.4.0 || Delete an entry from your address book. The program does not check to see whether it was there in the first place.
|-
| trashSentMessageByAckData|| <ackData> || 0.4.0 || Trashes a sent message based on its ackdata. ackData should be encoded in hex. Returns a simple message saying that the message was trashed assuming it ever even existed. Prior existence is not checked.
|-
| createChan|| <passphrase> || 0.4.2 || Creates a new chan. passphrase must be base64 encoded. Outputs the corresponding Bitmessage address.
|-
| joinChan|| <passphrase> <address> || 0.4.2 || Join a chan. passphrase must be base64 encoded. Outputs "success"
|-
| leaveChan|| <address> || 0.4.2 || Leave a chan. Outputs "success". Note that at this time, the address is still shown in the UI until a restart.
|-
| deleteAddress|| <address> || 0.4.2 || Permanently delete an address from Your Identities and your keys.dat file. Outputs "success". Note that at this time, the address is still shown in the UI until a restart.
|-
| decodeAddress|| <address> || 0.4.2 || Returns an object with these properties:
* status (ascii/utf-8)
* addressVersion (ascii integer)
* streamNumber (ascii integer)
* ripe (base64, decodes into binary data)
|}

'''Note:''' If the minimum required version is higher than {{Bitmessage Current Version Number}} then the code is available in source but not yet available in a compiled binary.

==== Possible error values ====

Here are the various error numbers and descriptions you might see.

{|class="wikitable"
! Error Number!! Message
|-
|0000 || API Error 0000: I need parameters!
|-
| 0001 || API Error 0001: The specified passphrase is blank.
|-
| 0002 || API Error 0002: The address version number currently must be 3 or 4 (or 0 which means auto-select).
|-
| 0003 || API Error 0003: The stream number must be 1 (or 0 which means auto-select). Others aren't supported.
|-
| 0004 || API Error 0004: Why would you ask me to generate 0 addresses for you?
|-
| 0005 || API Error 0005: You have (accidentally?) specified too many addresses to make. Maximum 999. This check only exists to prevent mischief; if you really want to create more addresses than this, contact the Bitmessage developers and we can modify the check or you can do it yourself by searching the source code for this message.
|-
| 0006 || API Error 0006: The encoding type must be 2 because that is the only one this program currently supports.
|-
| 0007 || API Error 0007: Could not decode address
|-
| 0008 || API Error 0008: Checksum failed for address
|-
| 0009 || API Error 0009: Invalid characters in address
|-
| 0010 || API Error 0010: Address version number too high (or zero) in address
|-
| 0011 || API Error 0011: The address version number currently must be 2, 3, or 4. Others aren't supported.
|-
| 0012 || API Error 0012: The stream number must be 1. Others aren't supported.
|-
| 0013 || API Error 0013: Could not find your fromAddress in the keys.dat file.
|-
| 0014 || API Error 0014: Your fromAddress is disabled. Cannot send.
|-
| 0015 || API Error 0015: The length of ackData should be 32 bytes (encoded in hex thus 64 characters).
|-
| 0016 || API Error 0016: You are already subscribed to that address.
|-
| 0017 || API Error 0017: Label is not valid UTF-8 data.
|-
| 0018 || API Error 0018: Chan name does not match address.
|-
| 0019 || API Error 0019: The length of hash should be 20 bytes (encoded in hex thus 40 characters).
|-
| 0020 || API Error 0020: Invalid method: <method_name_you_tried_to_execute>
|-
| 0021 || API Error 0021: Unexpected API Failure
|-
| 0022 || API Error 0022: Decode Error
|-
| 0023 || API Error 0023: Bool expected
|-
| 0024 || API Error 0024: Chan address is already present.
|-
| 0025 || API Error 0025: Specified address is not a chan address. Use deleteAddress API call instead.
|-
| 0026 || API Error 0026: Varint encoded in address is malformed.
|-
| 0027 || API Error 0027: Message is too long.
|}

Protocol specification v3

2014-08-27T00:20:04Z

Atheros:

{{Template:Stub}}

{{Template:Proposal}}

== 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 the [[Protocol specification|version 2 protocol specification]] 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.

Here is an example address which uses malformed varints: BM-CVA3RC7Mvy7JDNSpQChktwrSe4KNMaEdDdcymfUo. This address is invalid.

== 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 specification#version|version 2 version message]].

=== verack ===

The verack message is identical to [[Protocol specification#verack|version 2 verack message]].

=== addr ===

The addr message is identical to [[Protocol specification#addr|version 2 addr message]].

=== inv ===

The inv message is identical to [[Protocol specification#inv|version 2 inv message]].

=== getdata ===

The getdata message is identical to [[Protocol specification#getdata|version 2 getdata message]].

=== 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|Proof Of Work]] has to be done.

{|class="wikitable"
! Field Size !! Description !! Data type !! Comments
|-
| 8||POW nonce||uint64_t||
Random nonce used for the [[Proof of work|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 refer to [[Protocol specification#Object_types|version 2 object types]]
|-
|}

== Proof of Work ==

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 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 256 KiB(the payload of the object, starting from the POW nonce can have 262144 bytes at maximum).

API Reference

2014-08-25T21:00:41Z

Atheros: /* Possible error values */ Added API Error 0026: Varint encoded in address is malformed.

=== Introduction ===

The PyBitmessage API uses [http://en.wikipedia.org/wiki/XML-RPC XML-RPC].

=== Enable the API ===
To enable the API, copy and paste these lines into the bitmessagesettings section of the [[keys.dat]] file.
Note that the values "username" and "password" below are merely examples, and should be replaced by values that cannot feasibly be guessed:
<pre>
apienabled = true
apiport = 8442
apiinterface = 127.0.0.1
apiusername = username
apipassword = password
</pre>
Additionally, you may optionally include an additional entry which will specify a program which Bitmessage will run when certain events occur.
<pre>
apinotifypath = c:\\example\\example.exe
</pre>
One of these arguments will be passed to your program: startingUp, newMessage, newBroadcast. Be sure your program doesn't crash when given newer arguments introduced in the future as this list will likely expand.

=== Remote Access ===
To access the Bitmessage API from a remote location, change the apiinterface value from '''127.0.0.1''' to '''0.0.0.0'''.

The following Python code offers a demonstration of how to create a client that can connect to the PyBitmessage API.

In this example, the username is "username", the password is "password", the IP address of the server running PyBitmessage is 105.168.1.0 (a random example), and the port number which PyBitmessage has been configured to listen on is 8442. In order to connect with the remote copy of PyBitmessage, these settings must match those in PyBitmessage's "keys.dat" file.
<pre>
import xmlrpclib
import json
import time

api = xmlrpclib.ServerProxy("http://username:password@105.168.1.0:8442/")
print api.add(2,3)
</pre>

A more complete example can be found in the [https://github.com/Bitmessage/PyBitmessage/blob/master/src/api_client.py api_client.py] file in the PyBitmessage source code.

=== List of Operations ===
Required arguments are denoted inside < and > Optional arguments are inside [ and ].
{|class="wikitable"
! Command !! Parameters !! Minimum Version !! Description
|-
| helloWorld || <firstWord> <secondWord> || 0.2.7 || returns 'firstWord-secondWord'. Used as a simple test of the API.
|-
| add || <integer> <integer> || 0.2.7 || returns the sum of the integers. Used as a simple test of the API.
|-
| statusBar || <message> || 0.2.7 || Displays the message in the status bar on the GUI
|-
| listAddresses2|| || 0.4.0 || Lists all addresses shown on the Your Identities tab. Returns a list of objects with these properties:
* label (base64, decodes into utf-8)
* address (ascii/utf-8)
* stream (integer)
* enabled (bool)
* chan (bool)

This is called listAddresses'''2''' because 'listAddresses' is obsolete.
|-
| createRandomAddress || <label> [eighteenByteRipe] [totalDifficulty] [smallMessageDifficulty] || 0.2.7 || Creates one address using the random number generator. label should be base64 encoded. eighteenByteRipe is a boolean telling Bitmessage whether to generate an address with an 18 byte RIPE hash(as opposed to a 19 byte hash). This is the same setting as the "Do extra work to make the address 1 or 2 characters shorter" in the user interface. Using False is recommended if you are running some sort of website and will be generating a lot of addresses. Note that even if you don't ask for it, there is still a 1 in 256 chance that you will get an address with an 18 byte RIPE hash so if you actually ''need'' an address with a 19 byte RIPE hash for some reason, you will need to check for it. eighteenByteRipe defaults to False. totalDifficulty and smallMessageDifficulty default to 1.

Returns the address.

Warning: At present, Bitmessage gets confused if you use both the API and the UI to make an address at the same time.
|-
|createDeterministicAddresses ||<passphrase> [numberOfAddresses] [addressVersionNumber] [streamNumber] [eighteenByteRipe] [totalDifficulty] [smallMessageDifficulty] || 0.3.4 || Similar to createRandomAddress except that you may generate many addresses in one go. passphrase should be base64 encoded. numberOfAddresses defaults to 1. addressVersionNumber and streamNumber may be set to 0 which will tell Bitmessage to use the most up-to-date addressVersionNumber and the most available streamNumber. Using zero for each of these fields is recommended. eighteenByteRipe defaults to False. totalDifficulty and smallMessageDifficulty default to 1.

Returns a list of new addresses. This list will be empty if the addresses already existed.

Warning: At present, Bitmessage gets confused if you use both the API and the UI to make addresses at the same time.
|-
|getDeterministicAddress ||<passphrase> <addressVersionNumber> <streamNumber> || 0.3.1 || Similar to createDeterministicAddresses except that the one address that is returned will not be added to the Bitmessage user interface or the keys.dat file. passphrase should be base64 encoded. addressVersionNumber should be set to 3 or 4 as these are the only ones currently supported. streamNumber must be set to 1 as this is the only one currently supported.

Returns a single address.

Warning: At present, Bitmessage gets confused if you use both this API command and the UI to make addresses at the same time.
|-
|<code>getAllInboxMessages</code>|| || 0.2.7 || Does not include trashed messages. Returns a list of objects with these properties:
* msgid (hex)
* toAddress (ascii/utf-8)
* fromAddress (ascii/utf-8)
* subject (base64, decodes into utf-8)
* message (base64, decodes into utf-8)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* receivedTime (integer, Unix time)
* read (integer representing binary state (0 or 1))

The msgid is the same as the hash of the message (analogous to the TXID in Bitcoin) thus it is shown in hex as that is the de facto standard. The base64 encoding Bitmessage uses includes line breaks including one on the end of the string.
|-
|<code>getAllInboxMessageIDs</code>|| || 0.2.7 || Returns a list of msgids of all Inbox messages with there properties:
* msgid (hex)
|-
| getInboxMessageByID || <msgid> [read] || 0.4.0 || Returns an object with these properties:
* msgid (hex)
* toAddress (ascii/utf-8)
* fromAddress (ascii/utf-8)
* subject (base64, decodes into utf-8)
* message (base64, decodes into utf-8)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* receivedTime (integer, Unix time)
* read (integer representing binary state (0 or 1))

Optionally sets the specific message to have a read status of 'read' (bool).

The msgid is the same as the hash of the message (analogous to the TXID in Bitcoin) thus it should be given in hex as that is the de facto standard. The base64 encoding Bitmessage uses includes line breaks including one on the end of the string.
|-
| getSentMessageByAckData || <ackData> || 0.3.4 || Returns an object with these properties:
* msgid (hex)
* toAddress (ascii/utf-8)
* fromAddress (ascii/utf-8)
* subject (base64, decodes into utf-8)
* message (base64, decodes into utf-8)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* lastActionTime (integer, Unix time)
* status (ascii/utf-8)
* ackData (hex)
|-
| getAllSentMessages || || 0.3.4 || Returns an object with these properties:
* msgid (hex)
* toAddress (ascii/utf-8)
* fromAddress (ascii/utf-8)
* subject (base64, decodes into utf-8)
* message (base64, decodes into utf-8)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* lastActionTime (integer, Unix time)
* status (ascii/utf-8)
* ackData (hex)
|-
| getSentMessageByID || <msgid> || 0.3.4 || Returns an object with these properties:
* msgid (hex)
* toAddress (ascii/utf-8)
* fromAddress (ascii/utf-8)
* subject (base64, decodes into utf-8)
* message (base64, decodes into utf-8)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* lastActionTime (integer, Unix time)
* status (ascii/utf-8)
* ackData (hex)
|-
| getSentMessagesBySender|| <fromAddress> || 0.3.4 || Returns a list of objects with these properties:
* msgid (hex)
* toAddress (ascii/utf-8)
* fromAddress (ascii/utf-8)
* subject (base64, decodes into utf-8)
* message (base64, decodes into utf-8)
* [[Protocol_specification#Message_Encodings|encodingType]] (integer)
* lastActionTime (integer, Unix time)
* status (ascii/utf-8)
* ackData (hex)
|-
| trashMessage || <msgid> || 0.2.7 || returns a simple message saying that the message was trashed assuming it ever even existed. Prior existence is not checked. msgid is encoded in hex just like in the getAllInboxMessages function.
|-
| sendMessage || <toAddress> <fromAddress> <subject> <message> [encodingType] || 0.2.7 || returns ackdata encoded in hex. subject and message must be encoded in base64 which may optionally include line breaks. If used, the encodingType must be set to 2; this is included for forwards compatibility.
|-
| sendBroadcast || <fromAddress> <subject> <message> [encodingType] || 0.2.7 || returns ackData encoded in hex. subject and message must be encoded in base64. If used, the encodingType must be set to 2; this is included for forwards compatibility.
|-
| getStatus || <ackData> || 0.3.0 || returns one of these strings: <strike>notFound, findingPubkey, doingPOW, sentMessage, or ackReceived</strike> notfound, msgqueued, broadcastqueued, broadcastsent, doingpubkeypow, awaitingpubkey, doingmsgpow, forcepow, msgsent, msgsentnoackexpected, or ackreceived.
|-
| listSubscriptions|| || 0.4.0 || Returns a list of objects with these properties:
* label (base64, decodes into utf-8)
* address (ascii/utf-8)
* enabled (bool)
|-
| addSubscription|| <address> [label] || 0.3.1 || Subscribe to an address. label must be base64-encoded.
|-
| deleteSubscription|| <address> || 0.3.1 || Unsubscribe from an address. The program does not check to see whether you were subscribed in the first place.
|-
| listAddressBookEntries|| || 0.4.0 ||Returns a list of objects with these properties:
* address (ascii/utf-8)
* label (base64, decodes into utf-8)
|-
| addAddressBookEntry|| <address> <label> || 0.4.0 || Add an entry to your address book. label must be base64-encoded.
|-
| deleteAddressBookEntry|| <address> || 0.4.0 || Delete an entry from your address book. The program does not check to see whether it was there in the first place.
|-
| trashSentMessageByAckData|| <ackData> || 0.4.0 || Trashes a sent message based on its ackdata. ackData should be encoded in hex. Returns a simple message saying that the message was trashed assuming it ever even existed. Prior existence is not checked.
|-
| createChan|| <passphrase> || 0.4.2 || Creates a new chan. passphrase must be base64 encoded. Outputs the corresponding Bitmessage address.
|-
| joinChan|| <passphrase> <address> || 0.4.2 || Join a chan. passphrase must be base64 encoded. Outputs "success"
|-
| leaveChan|| <address> || 0.4.2 || Leave a chan. Outputs "success". Note that at this time, the address is still shown in the UI until a restart.
|-
| deleteAddress|| <address> || 0.4.2 || Permanently delete an address from Your Identities and your keys.dat file. Outputs "success". Note that at this time, the address is still shown in the UI until a restart.
|-
| decodeAddress|| <address> || 0.4.2 || Returns an object with these properties:
* status (ascii/utf-8)
* addressVersion (ascii integer)
* streamNumber (ascii integer)
* ripe (base64, decodes into binary data)
|}

'''Note:''' If the minimum required version is higher than {{Bitmessage Current Version Number}} then the code is available in source but not yet available in a compiled binary.

==== Possible error values ====

Here are the various error numbers and descriptions you might see.

{|class="wikitable"
! Error Number!! Message
|-
|0000 || API Error 0000: I need parameters!
|-
| 0001 || API Error 0001: The specified passphrase is blank.
|-
| 0002 || API Error 0002: The address version number currently must be 3 or 4 (or 0 which means auto-select).
|-
| 0003 || API Error 0003: The stream number must be 1 (or 0 which means auto-select). Others aren't supported.
|-
| 0004 || API Error 0004: Why would you ask me to generate 0 addresses for you?
|-
| 0005 || API Error 0005: You have (accidentally?) specified too many addresses to make. Maximum 999. This check only exists to prevent mischief; if you really want to create more addresses than this, contact the Bitmessage developers and we can modify the check or you can do it yourself by searching the source code for this message.
|-
| 0006 || API Error 0006: The encoding type must be 2 because that is the only one this program currently supports.
|-
| 0007 || API Error 0007: Could not decode address
|-
| 0008 || API Error 0008: Checksum failed for address
|-
| 0009 || API Error 0009: Invalid characters in address
|-
| 0010 || API Error 0010: Address version number too high (or zero) in address
|-
| 0011 || API Error 0011: The address version number currently must be 2, 3, or 4. Others aren't supported.
|-
| 0012 || API Error 0012: The stream number must be 1. Others aren't supported.
|-
| 0013 || API Error 0013: Could not find your fromAddress in the keys.dat file.
|-
| 0014 || API Error 0014: Your fromAddress is disabled. Cannot send.
|-
| 0015 || API Error 0015: The length of ackData should be 32 bytes (encoded in hex thus 64 characters).
|-
| 0016 || API Error 0016: You are already subscribed to that address.
|-
| 0017 || API Error 0017: Label is not valid UTF-8 data.
|-
| 0018 || API Error 0018: Chan name does not match address.
|-
| 0019 || API Error 0019: The length of hash should be 20 bytes (encoded in hex thus 40 characters).
|-
| 0020 || API Error 0020: Invalid method: <method_name_you_tried_to_execute>
|-
| 0021 || API Error 0021: Unexpected API Failure
|-
| 0022 || API Error 0022: Decode Error
|-
| 0023 || API Error 0023: Bool expected
|-
| 0024 || API Error 0024: Chan address is already present.
|-
| 0025 || API Error 0025: Specified address is not a chan address. Use deleteAddress API call instead.
|-
| 0026 || API Error 0026: Varint encoded in address is malformed.
|}

Compiling instructions

2014-08-07T16:38:41Z

Atheros: /* Windows */

This page should help novice users run Bitmessage from the source code files.

= Linux =

== Resolve dependencies ==
{| class="wikitable" border="1" width="80%"
|-
! Distribuion
! Instructions
|-
! scope="row"| Debian-based
(Ubuntu, Raspbian, PiBang, others)
| ''Note for Debian Squeeze (6.0) users: Debian Squeeze does not offer packages (like Python, OpenSSL) in versions that are needed for Bitmessage. You can still try to [https://github.com/Bitmessage/PyBitmessage/issues/47#issuecomment-17774377 work around these problems]. Debian 7 "wheezy" works without problems.''
sudo apt-get install python openssl git python-qt4
|-
! scope="row"| Arch Linux
|
sudo pacman -S python2 openssl git python2-pyqt4
|-
! scope="row"| Fedora
| ''Fedora and RHEL6 do not support EC in OpenSSL. Therefore we need [http://linux.ringingliberty.com/bitcoin/ Ringing Liberty's bitcoin repository] to get a compatible library.''

su -c 'yum install -y http://linux.ringingliberty.com/bitcoin/f18/x86_64/bitcoin-release-1-4.noarch.rpm'
su -c 'yum install -y python python-qt4 git openssl-compat-bitcoin-libs'

Tell your system where to look for the library:
echo 'LD_LIBRARY_PATH="/opt/openssl-compat-bitcoin/lib/"' >> ~/.bashrc && source ~/.bashrc
Note for Fedora 20 users: Due to inconsistent behavior encountered by declaring the above variable globally, the following "wrapper script" will declare the LD_LIBRARY_PATH variable correctly and only when running bitmessage. Name the script something like "bitmessage", mark it as executable (probably something like 755) and put it in /usr/bin so it's accessible without the full path.
export LD_LIBRARY_PATH="/opt/openssl-compat-bitcoin/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"
/home/<yourusername>/PyBitmessage/src/bitmessagemain.py > /dev/null 2>&1 &
|-
! scope="row"| Red Hat Enterprise Linux (RHEL)
| ''Fedora and RHEL6 do not support EC in OpenSSL. Therefore we need [http://linux.ringingliberty.com/bitcoin/ Ringing Liberty's bitcoin repository] to get a compatible library.''

su -c 'yum install -y http://linux.ringingliberty.com/bitcoin/el6/x86_64/bitcoin-release-1-4.noarch.rpm'
su -c 'yum install -y python python-qt4 git openssl-compat-bitcoin-libs'
Tell your system where to look for the library:
echo 'LD_LIBRARY_PATH="/opt/openssl-compat-bitcoin/lib/"' >> ~/.bashrc && source ~/.bashrc
|}

== Download and run PyBitmessage ==
# Download the source code from github: <code>git clone <nowiki>https://github.com/Bitmessage/PyBitmessage $HOME/PyBitmessage</nowiki></code>
# Run PyBitmessage: <code>~/PyBitmessage/src/bitmessagemain.py</code>
Check the wiki for more information on how to run Bitmessage [https://bitmessage.org/wiki/Daemon as a daemon].

If you receive a warning that you need to use python 2.7.3 or greater, and have followed the above instructions to upgrade it, your system may be attemping to run PyBitmessage with python 3. In this case, run <code>python2 ~/PyBitmessage/src/bitmessagemain.py</code>

== Upgrading ==
To upgrade Bitmessage run the following commands:
:<code>cd $HOME/PyBitmessage</code>
:<code>git pull</code>

= OS X =
== With Homebrew package manager ==
; Setup
First, make sure you have not already installed Macports. Having both macports and homebrew on the same system is a recipe for disaster.
Install Homebrew:
ruby -e "$(curl -fsSL https://raw.github.com/mxcl/homebrew/go)"

; Update Python:
brew install python

; Install dependencies:
brew install pyqt openssl

; Download and run
cd ~/Desktop
git clone git://github.com/Bitmessage/PyBitmessage.git
cd PyBitmessage
python src/bitmessagemain.py

== With macports package manager ==
First, make sure you have not already installed Homebrew. Having both macports and homebrew on the same system is a recipe for disaster.
Installing with macports or homebrew essentially has the same effect. Homebrew does some things better than ports, and ports does some things better than brew. If old-school floats your boat, these instructions are for you.

; Select the macports installation that is right for your version of osx
Read the instructions or take this as a reminder: Apple's XCode and their Command Line Tools are a prerequiste for Macports, go: https://www.macports.org/install.php

; Install dependencies and needed tools
sudo port install python27 py27-pyqt4 openssl
sudo port install git-core +svn +doc +bash_completion +gitweb

; Download and run
cd ~/Desktop
git clone git://github.com/Bitmessage/PyBitmessage.git
cd PyBitmessage
python2.7 src/bitmessagemain.py

= Windows =
# Download and install the latest revision of Python 2.7 (currently Python 2.7.8 from [https://www.python.org/download/releases/2.7.8/ here]). The ''Windows x86 MSI Installer'' is the right choice for most people. (64-bit users may want the 64-bit version).
## Test that it installed:
### Open a command prompt by going to Start > Run. Type 'cmd' then press enter.
### type 'python'. If python is installed, you should see the python version and the prompt: '>>>'
### If you see a message such as: "'Python is not recognized as an internal or external command..." then you must add the python path to your path environmental variable:
#### Find the location where Python was installed (in particular, the location where python.exe exists). It might simply be in c:\Python2.7
#### Follow [http://www.computerhope.com/issues/ch000549.htm these directions] to add the Python path to your path variable.
#### Close the command prompt window and reopen it.
### Try running 'python' again.
###Press Ctrl-Z to exit Python.
# Download PyQt from [http://www.riverbankcomputing.com/software/pyqt/download here]. ''PyQt is one of Bitmessage's two dependencies.'' Look for the links to downloads under the heading labeled "Binary Package;" the binary package versions are already compiled for you. Select the version for Python 2.7 (look for "Py2.7" in the file name). Install PyQt.
# Download OpenSSL from [http://slproweb.com/products/Win32OpenSSL.html here]. ''OpenSSL is the second of Bitmessage's two dependencies.'' Install OpenSSL. If an error message appears during installation of OpenSSL, download and install Visual C++ 2008. A link is provided on the OpenSSL download page.
# Download the source code for PyBitmessage from GitHub. If it is in a zip file, you will need to extract it. There should be a few files and a few folders where one of the folders is 'src'.
# To run Bitmessage, navigate into the 'src' folder and then double click on the bitmessagemain.py file, or in a command prompt, change directories to the 'src' directory which holds bitmessagemain.py and type 'python bitmessagemain.py'.

== If you change user interface files ==
You can use Qt's Designer application to modify the user interface. After you do this, you will need to 'compile' .ui files into .py files.
# In a command prompt, change directories to the directory of your .ui file.
# Run 'pyuic4 example.ui > example.py' If you get a message similar to 'pyuic4 is not recognized as an internal or external command' then you must add the PyQt directory to your system's path variable. This directory should hold pyuic4.bat. It might be in C:\Python27\Lib\site-packages\PyQt4. Remember to close the command window and reopen it after you change your path variable.

If you add icons to bitmessage_icons.qrc, then you must run this command:
pyrcc4 bitmessage_icons.qrc -o bitmessage_icons_rc.py

== Optional: Compile into a stand-alone EXE ==
# Download [http://www.pyinstaller.org/ PyInstaller].
# Copy Bitmessage's 'src' directory to the PyInstaller directory (which contains pyinstaller.py).
# Run 'pyinstaller.py --onefile --noconsole --icon="src\images\can-icon.ico" src\bitmessagemain.py'
This won't include the OpenSSL DLL file in the EXE; if you send it to someone who doesn't have OpenSSL installed, it will not run. To include the DLL file in the EXE, you must follow these steps:
# After following the steps above, you will see that pyinstaller created a folder called bitmessagemain. In that folder is a file: bitmessagemain.spec. Open it with a text editor.
# Below the line "a.datas," add this line: <code>a.binaries + [('libeay32.dll', 'c:\\windows\\system32\\libeay32.dll', 'BINARY')],</code>
# Optionally also include the translations by modifying this file further by adding the lines shown in [[Example_pyinstaller_spec_file|this]] example file.
# Save and close
# Run this command: pyinstaller.py bitmessagemain/bitmessagemain.spec

If you do not have the libeay32.dll you can download it here. http://www.dll-files.com/dllindex/dll-files.shtml?libeay32