Joinmarket Messaging Protocol

JoinMarket messaging protocol

The purpose of this document is to unambiguously define how joinmarket participants communicate. The messaging substrate may change in the future (see this class ), for now it is IRC.

All messages are split into fields. Fields are separated with a single whitespace character (more than one whitespace char is not allowed).

Messages have format:

!command [[msg field 1] [msg field 2] ...]

Messages are sent in two modes: public (broadcast to all other agents) or private (directed to a specific agent and not seen by others).

The first field always starts with the command prefix, currently '!' and is completed with one of the following commands:

Command word		mode
relorder		public or private
absorder		public or private
orderbook		public
relorder		public or private
cancel		public
fill		private
pubkey		private
auth		private
ioauth		private
tx		private
sig		private
error		private
push		private

Private messages not starting with a command from this list are to be explicitly rejected. Public messages not starting with a command from this list are to be ignored. The initial command field is followed with zero or more message fields.

Chunks

Messages are split into chunks for passing over the messaging channel. Chunks are terminated with the chunk delimiter ';', unless it is the final chunk, which case the chunk delimiter is '~'.

Messages are split into chunks before sending over the messaging channel, and the decision for chunk size is set globally as a function of the messaging implementation (currently: approx 400 characters for IRC).

Encryption

Public messages (broadcast to all other participants) are never encrypted.

Private messages of command-type 'fill', 'pubkey' and 'error', 'orderbook, 'push, 'relorder' and 'absorder' are sent in plaintext. Messages of command-type 'ioauth', 'auth', 'tx' and 'sig' are sent encrypted.

These rules are currently enforced here (TODO: although this should be moved to the message_channel class).

All encrypted messages are base64 encoded before being passed onto the message channel.

For encrypted messages, the entire set of message fields are sent as a single encrypted block (including the whitespace delimiters between the message fields). The command field and the chunk indicator field are sent in plaintext. (TODO: to improve privacy padding should be added to some or all of these messages).

For clarification, the sequence for sending of encrypted messages is therefore plaintext-->encryption-->base64encoding-->chunking--> prepend !command to first chunk and add chunk delimiters -->send to message channel (private message for encryption). And the reverse for receiving.

Valid conversation sequences:

TAKER		MAKER
	<<<	![rel|abs]order (public)

TAKER		MAKER
!orderbook(public)	>>>
	<<<	![rel|abs]order (private)

TAKER		MAKER
!fill(private)	>>>
	<<<	!pubkey(private)
!ioauth(private)	>>>
	<<<	!auth(private)
!tx(private)	>>>
	<<<	!sig(private)

Each taker may speak to many makers simultaneously and each maker may speak to many takers simultaneously in private.

This document is not yet complete. Edit proposals welcomed.