diff --git a/peer/README b/peer/README
deleted file mode 100644
index 51b7e2582..000000000
--- a/peer/README
+++ /dev/null
@@ -1,35 +0,0 @@
-////////////////////////////
-// All client impl internal messages
-// No filter
-** Channel ""
-
-* NewFilterMsg
-* ...?
-
-
-////////////////////////////
-// All blocks
-// Requires a custom simple filter
-** Channel "block"
-
-* BlockMsg
-* HeaderMsg
-
-
-////////////////////////////
-// New transactions that haven't been committed
-// e.g. the mempool
-// n:10k, p:0.02 -> k:6, m:10KB
-** Channel "newtx"
-
-* NewTxMsg
-
-
-////////////////////////////
-// All about the consensus
-// No filter
-** Channel "consensus"
-
-* ProposalMsg
-* VoteMsg
-* NewBlockMsg
diff --git a/peer/README.md b/peer/README.md
new file mode 100644
index 000000000..766b5c5c0
--- /dev/null
+++ b/peer/README.md
@@ -0,0 +1,38 @@
+## Channel ""
+
+Filter: None
+
+Messages:
+* RefreshFilterMsg
+* PeerExchangeMsg
+
+
+## Channel "block"
+
+Filter: Custom filter.
+
+Messages:
+* BlockMsg
+* HeaderMsg
+
+
+## Channel "mempool"
+
+Filter: Bloom filter (n:10k, p:0.02 -> k:6, m:10KB)
+
+FilterRefresh: Every new block.
+
+Messages:
+* MempoolTxMsg
+
+
+## Channel "consensus"                                                                                                                                                                                                                                                                                                                                                    
+
+Filter: Bitarray filter
+
+FilterRefresh: Every new block.
+
+Messages:
+* ProposalMsg
+* VoteMsg
+* NewBlockMsg