Move documentation files to their own directory

5 files changed, 690 insertions, 0 deletions

diff --git a/docs/ANONYMITY_NETWORKS.md b/docs/ANONYMITY_NETWORKS.md
new file mode 100644
index 000000000..3337b5fc3
--- /dev/null
+++ b/docs/ANONYMITY_NETWORKS.md
@@ -0,0 +1,236 @@
+# Anonymity Networks with Monero
+
+Currently only Tor and I2P have been integrated into Monero. The usage of
+these networks is still considered experimental - there are a few pessimistic
+cases where privacy is leaked. The design is intended to maximize privacy of
+the source of a transaction by broadcasting it over an anonymity network, while
+relying on IPv4 for the remainder of messages to make surrounding node attacks
+(via sybil) more difficult.
+
+
+## Behavior
+
+If _any_ anonymity network is enabled, transactions being broadcast that lack
+a valid "context" (i.e. the transaction did not come from a p2p connection),
+will only be sent to peers on anonymity networks. If an anonymity network is
+enabled but no peers over an anonymity network are available, an error is
+logged and the transaction is kept for future broadcasting over an anonymity
+network. The transaction will not be broadcast unless an anonymity connection
+is made or until `monerod` is shutdown and restarted with only public
+connections enabled.
+
+Anonymity networks can also be used with `monero-wallet-cli` and
+`monero-wallet-rpc` - the wallets will connect to a daemon through a proxy. The
+daemon must provide a hidden service for the RPC itself, which is separate from
+the hidden service for P2P connections.
+
+
+## P2P Commands
+
+Only handshakes, peer timed syncs and transaction broadcast messages are
+supported over anonymity networks. If one `--add-exclusive-node` p2p address
+is specified, then no syncing will take place and only transaction broadcasting
+can occur. It is therefore recommended that `--add-exclusive-node` be combined
+with additional exclusive IPv4 address(es).
+
+
+## Usage
+
+Anonymity networks have no seed nodes (the feature is still considered
+experimental), so a user must specify an address. If configured properly,
+additional peers can be found through typical p2p peerlist sharing.
+
+### Outbound Connections
+
+Connecting to an anonymous address requires the command line option
+`--tx-proxy` which tells `monerod` the ip/port of a socks proxy provided by a
+separate process. On most systems the configuration will look like:
+
+```
+--tx-proxy tor,127.0.0.1:9050,10
+--tx-proxy i2p,127.0.0.1:9000
+```
+
+which tells `monerod` that ".onion" p2p addresses can be forwarded to a socks
+proxy at IP 127.0.0.1 port 9050 with a max of 10 outgoing connections and
+".b32.i2p" p2p addresses can be forwarded to a socks proxy at IP 127.0.0.1 port
+9000 with the default max outgoing connections. Since there are no seed nodes
+for anonymity connections, peers must be manually specified:
+
+```
+--add-exclusive-node rveahdfho7wo4b2m.onion:28083
+--add-peer rveahdfho7wo4b2m.onion:28083
+```
+
+Either option can be listed multiple times, and can specify any mix of Tor,
+I2P, and IPv4 addresses. Using `--add-exclusive-node` will prevent the usage of
+seed nodes on ALL networks, which will typically be undesirable.
+
+### Inbound Connections
+
+Receiving anonymity connections is done through the option
+`--anonymous-inbound`. This option tells `monerod` the inbound address, network
+type, and max connections:
+
+```
+--anonymous-inbound rveahdfho7wo4b2m.onion:28083,127.0.0.1:28083,25
+--anonymous-inbound cmeua5767mz2q5jsaelk2rxhf67agrwuetaso5dzbenyzwlbkg2q.b32.i2p:5000,127.0.0.1:30000
+```
+
+which tells `monerod` that a max of 25 inbound Tor connections are being
+received at address "rveahdfho7wo4b2m.onion:28083" and forwarded to `monerod`
+localhost port 28083, and a default max I2P connections are being received at
+address "cmeua5767mz2q5jsaelk2rxhf67agrwuetaso5dzbenyzwlbkg2q.b32.i2p:5000" and
+forwarded to `monerod` localhost port 30000.
+These addresses will be shared with outgoing peers, over the same network type,
+otherwise the peer will not be notified of the peer address by the proxy.
+
+### Wallet RPC
+
+An anonymity network can be configured to forward incoming connections to a
+`monerod` RPC port - which is independent from the configuration for incoming
+P2P anonymity connections. The anonymity network (Tor/i2p) is
+[configured in the same manner](#configuration), except the localhost port
+must be the RPC port (typically 18081 for mainnet) instead of the p2p port:
+
+```
+HiddenServiceDir /var/lib/tor/data/monero
+HiddenServicePort 18081 127.0.0.1:18081
+```
+
+Then the wallet will be configured to use a Tor/i2p address:
+```
+--proxy 127.0.0.1:9050
+--daemon-address rveahdfho7wo4b2m.onion
+```
+
+The proxy must match the address type - a Tor proxy will not work properly with
+i2p addresses, etc.
+
+i2p and onion addresses provide the information necessary to authenticate and
+encrypt the connection from end-to-end. If desired, SSL can also be applied to
+the connection with `--daemon-address https://rveahdfho7wo4b2m.onion` which
+requires a server certificate that is signed by a "root" certificate on the
+machine running the wallet. Alternatively, `--daemon-cert-file` can be used to
+specify a certificate to authenticate the server.
+
+Proxies can also be used to connect to "clearnet" (ipv4 addresses or ICANN
+domains), but `--daemon-cert-file` _must_ be used for authentication and
+encryption.
+
+### Network Types
+
+#### Tor & I2P
+
+Options `--add-exclusive-node` and `--add-peer` recognize ".onion" and
+".b32.i2p" addresses, and will properly forward those addresses to the proxy
+provided with `--tx-proxy tor,...` or `--tx-proxy i2p,...`.
+
+Option `--anonymous-inbound` also recognizes ".onion" and ".b32.i2p" addresses,
+and will automatically be sent out to outgoing Tor/I2P connections so the peer
+can distribute the address to its other peers.
+
+##### Configuration
+
+Tor must be configured for hidden services. An example configuration ("torrc")
+might look like:
+
+```
+HiddenServiceDir /var/lib/tor/data/monero
+HiddenServicePort 28083 127.0.0.1:28083
+```
+
+This will store key information in `/var/lib/tor/data/monero` and will forward
+"Tor port" 28083 to port 28083 of ip 127.0.0.1. The file
+`/usr/lib/tor/data/monero/hostname` will contain the ".onion" address for use
+with `--anonymous-inbound`.
+
+I2P must be configured with a standard server tunnel. Configuration differs by
+I2P implementation.
+
+## Privacy Limitations
+
+There are currently some techniques that could be used to _possibly_ identify
+the machine that broadcast a transaction over an anonymity network.
+
+### Timestamps
+
+The peer timed sync command sends the current time in the message. This value
+can be used to link an onion address to an IPv4/IPv6 address. If a peer first
+sees a transaction over Tor, it could _assume_ (possibly incorrectly) that the
+transaction originated from the peer. If both the Tor connection and an
+IPv4/IPv6 connection have timestamps that are approximately close in value they
+could be used to link the two connections. This is less likely to happen if the
+system clock is fairly accurate - many peers on the Monero network should have
+similar timestamps.
+
+#### Mitigation
+
+Keep the system clock accurate so that fingerprinting is more difficult. In
+the future a random offset might be applied to anonymity networks so that if
+the system clock is noticeably off (and therefore more fingerprintable),
+linking the public IPv4/IPv6 connections with the anonymity networks will be
+more difficult.
+
+### Intermittent Monero Syncing
+
+If a user only runs `monerod` to send a transaction then quit, this can also
+be used by an ISP to link a user to a transaction.
+
+#### Mitigation
+
+Run `monerod` as often as possible to conceal when transactions are being sent.
+Future versions will also have peers that first receive a transaction over an
+anonymity network delay the broadcast to public peers by a randomized amount.
+This will not completely mitigate a user who syncs up sends then quits, in
+part because this rule is not enforceable, so this mitigation strategy is
+simply a best effort attempt.
+
+### Active Bandwidth Shaping
+
+An attacker could attempt to bandwidth shape traffic in an attempt to determine
+the source of a Tor/I2P connection. There isn't great mitigation against
+this, but I2P should provide better protection against this attack since
+the connections are not circuit based.
+
+#### Mitigation
+
+The best mitigation is to use I2P instead of Tor. However, I2P
+has a smaller set of users (less cover traffic) and academic reviews, so there
+is a trade off in potential issues. Also, anyone attempting this strategy really
+wants to uncover a user, it seems unlikely that this would be performed against
+every Tor/I2P user.
+
+### I2P/Tor Stream Used Twice
+
+If a single I2P/Tor stream is used 2+ times for transmitting a transaction, the
+operator of the hidden service can conclude that both transactions came from the
+same source. If the subsequent transactions spend a change output from the
+earlier transactions, this will also reveal the "real" spend in the ring
+signature. This issue was (primarily) raised by @secparam on Twitter.
+
+#### Mitigation
+
+`monerod` currently selects two outgoing connections every 5 minutes for
+transmitting transactions over I2P/Tor. Using outgoing connections prevents an
+adversary from making many incoming connections to obtain information (this
+technique was taken from Dandelion). Outgoing connections also do not have a
+persistent public key identity - the creation of a new circuit will generate
+a new public key identity. The lock time on a change address is ~20 minutes, so
+`monerod` will have rotated its selected outgoing connections several times in
+most cases. However, the number of outgoing connections is typically a small
+fixed number, so there is a decent probability of re-use with the same public
+key identity.
+
+@secparam (twitter) recommended changing circuits (Tor) as an additional
+precaution. This is likely not a good idea - forcibly requesting Tor to change
+circuits is observable by the ISP. Instead, `monerod` should likely disconnect
+from peers occasionally. Tor will rotate circuits every ~10 minutes, so
+establishing new connections will use a new public key identity and make it
+more difficult for the hidden service to link information. This process will
+have to be done carefully because closing/reconnecting connections can also
+leak information to hidden services if done improperly.
+
+At the current time, if users need to frequently make transactions, I2P/Tor
+will improve privacy from ISPs and other common adversaries, but still have
+some metadata leakages to unknown hidden service operators.
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
new file mode 100644
index 000000000..7b184c00a
--- /dev/null
+++ b/docs/CONTRIBUTING.md
@@ -0,0 +1,172 @@
+# Contributing to Monero
+
+A good way to help is to test, and report bugs. See
+[How to Report Bugs Effectively (by Simon Tatham)](https://www.chiark.greenend.org.uk/~sgtatham/bugs.html)
+if you want to help that way. Testing is invaluable in making a piece
+of software solid and usable.
+
+
+## General guidelines
+
+* Comments are encouraged.
+* If modifying code for which Doxygen headers exist, that header must be modified to match.
+* Tests would be nice to have if you're adding functionality.
+
+Patches are preferably to be sent via a Github pull request. If that
+can't be done, patches in "git format-patch" format can be sent
+(eg, posted to fpaste.org with a long enough timeout and a link
+posted to #monero-dev on irc.freenode.net).
+
+Patches should be self contained. A good rule of thumb is to have
+one patch per separate issue, feature, or logical change. Also, no
+other changes, such as random whitespace changes, reindentation,
+or fixing typoes, spelling, or wording, unless user visible.
+Following the code style of the particular chunk of code you're
+modifying is encouraged. Proper squashing should be done (eg, if
+you're making a buggy patch, then a later patch to fix the bug,
+both patches should be merged).
+
+If you've made random unrelated changes (either because your editor
+is annoying or you made them for other reasons), you can select
+what changes go into the coming commit using git add -p, which
+walks you through all the changes and asks whether or not to
+include this particular change. This helps create clean patches
+without any irrelevant changes. git diff will show you the changes
+in your tree. git diff --cached will show what is currently staged
+for commit. As you add hunks with git add -p, those hunks will
+"move" from the git diff output to the git diff --cached output,
+so you can see clearly what your commit is going to look like.
+
+## Commits and pull requests
+
+Commit messages should be sensible. That means a subject line that
+describes the patch, with an optional longer body that gives details,
+documentation, etc.
+
+When submitting a pull request on Github, make sure your branch is
+rebased. No merge commits nor stray commits from other people in
+your submitted branch, please. You may be asked to rebase if there
+are conflicts (even trivially resolvable ones).
+
+PGP signing commits is strongly encouraged. That should explain why
+the previous paragraph is here.
+
+# [Code of Conduct (22/C4.1)](http://rfc.zeromq.org/spec:22)
+
+## License
+
+Copyright (c) 2009-2015 Pieter Hintjens.
+Copyright (c) 2017-2018 The Monero Project.
+
+This Specification is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.
+
+This Specification is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along with this program; if not, see <http://www.gnu.org/licenses>.
+
+## Language
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
+
+The "Monero Maintainer Team" is defined in this document as the following users:
+- fluffypony
+- moneromooo
+- hyc
+
+## Goals
+
+C4 is meant to provide a reusable optimal collaboration model for open source software projects. It has these specific goals:
+
+- To maximize the scale and diversity of the community around a project, by reducing the friction for new Contributors and creating a scaled participation model with strong positive feedbacks;
+- To relieve dependencies on key individuals by separating different skill sets so that there is a larger pool of competence in any required domain;
+- To allow the project to develop faster and more accurately, by increasing the diversity of the decision making process;
+- To support the natural life cycle of project versions from experimental through to stable, by allowing safe experimentation, rapid failure, and isolation of stable code;
+- To reduce the internal complexity of project repositories, thus making it easier for Contributors to participate and reducing the scope for error;
+- To enforce collective ownership of the project, which increases economic incentive to Contributors and reduces the risk of hijack by hostile entities.
+
+## Design
+
+### Preliminaries
+
+- The project MUST use the git distributed revision control system.
+- The project MUST be hosted on github.com or equivalent, herein called the "Platform".
+- The project MUST use the Platform issue tracker.
+  - Non-GitHub example:
+    - "Platform" could be a vanilla git repo and Trac hosted on the same machine/network.
+    - The Platform issue tracker would be Trac.
+- The project SHOULD have clearly documented guidelines for code style.
+- A "Contributor" is a person who wishes to provide a patch, being a set of commits that solve some clearly identified problem.
+- A "Maintainer" is a person who merges patches to the project. Maintainers are not developers; their job is to enforce process.
+- Contributors MUST NOT have commit access to the repository unless they are also Maintainers.
+- Maintainers MUST have commit access to the repository.
+- Everyone, without distinction or discrimination, MUST have an equal right to become a Contributor under the terms of this contract.
+
+### Licensing and ownership
+
+- The project MUST use a share-alike license, such as BSD-3, the GPLv3 or a variant thereof (LGPL, AGPL), or the MPLv2.
+- All contributions to the project source code ("patches") MUST use the same license as the project.
+- All patches are owned by their authors. There MUST NOT be any copyright assignment process.
+- The copyrights in the project MUST be owned collectively by all its Contributors.
+- Each Contributor MUST be responsible for identifying themselves in the project Contributor list.
+
+### Patch requirements
+
+- Maintainers MUST have a Platform account and SHOULD use their real names or a well-known alias.
+- Contributors SHOULD have a Platform account and MAY use their real names or a well-known alias.
+- A patch SHOULD be a minimal and accurate answer to exactly one identified and agreed problem.
+- A patch MUST adhere to the code style guidelines of the project if these are defined.
+- A patch MUST adhere to the "Evolution of Public Contracts" guidelines defined below.
+- A patch MUST NOT include non-trivial code from other projects unless the Contributor is the original author of that code.
+- A patch MUST compile cleanly and pass project self-tests on at least the principle target platform.
+- A patch commit message SHOULD consist of a single short (less than 50 character) line summarizing the change, optionally followed by a blank line and then a more thorough description.
+- A "Correct Patch" is one that satisfies the above requirements.
+
+### Development process
+
+- Change on the project MUST be governed by the pattern of accurately identifying problems and applying minimal, accurate solutions to these problems.
+- To request changes, a user SHOULD log an issue on the project Platform issue tracker.
+- The user or Contributor SHOULD write the issue by describing the problem they face or observe.
+- The user or Contributor SHOULD seek consensus on the accuracy of their observation, and the value of solving the problem.
+- Users MUST NOT log feature requests, ideas, or suggestions unrelated to Monero code or Monero's dependency code or Monero's potential/future dependency code or research which successfully implements Monero.
+- Users MUST NOT log any solutions to problems (verifiable or hypothetical) of which are not explicitly documented and/or not provable and/or cannot be reasonably proven.
+- Thus, the release history of the project MUST be a list of meaningful issues logged and solved.
+- To work on an issue, a Contributor MUST fork the project repository and then work on their forked repository.
+- To submit a patch, a Contributor MUST create a Platform pull request back to the project.
+- A Contributor MUST NOT commit changes directly to the project.
+- To discuss a patch, people MAY comment on the Platform pull request, on the commit, or elsewhere.
+- To accept or reject a patch, a Maintainer MUST use the Platform interface.
+- Maintainers SHOULD NOT merge their own patches except in exceptional cases, such as non-responsiveness from other Maintainers for an extended period (more than 30 days) or unless urgent as defined by the Monero Maintainers Team.
+- Maintainers MUST NOT make value judgments on correct patches unless the Maintainer (as may happen in rare circumstances) is a core code developer.
+- Maintainers MUST NOT merge pull requests in less than 168 hours (1 week) unless deemed urgent by at least 2 people from the Monero Maintainer Team.
+- The Contributor MAY tag an issue as "Ready" after making a pull request for the issue.
+- The user who created an issue SHOULD close the issue after checking the patch is successful.
+- Maintainers SHOULD ask for improvements to incorrect patches and SHOULD reject incorrect patches if the Contributor does not respond constructively.
+- Any Contributor who has value judgments on a correct patch SHOULD express these via their own patches.
+- Maintainers MAY commit changes to non-source documentation directly to the project.
+
+### Creating stable releases
+
+- The project MUST have one branch ("master") that always holds the latest in-progress version and SHOULD always build.
+- The project MUST NOT use topic branches for any reason. Personal forks MAY use topic branches.
+- To make a stable release someone MUST fork the repository by copying it and thus become maintainer of this repository.
+- Forking a project for stabilization MAY be done unilaterally and without agreement of project maintainers.
+- A patch to a stabilization project declared "stable" MUST be accompanied by a reproducible test case.
+
+### Evolution of public contracts
+
+- All Public Contracts (APIs or protocols) MUST be documented.
+- All Public Contracts SHOULD have space for extensibility and experimentation.
+- A patch that modifies a stable Public Contract SHOULD not break existing applications unless there is overriding consensus on the value of doing this.
+- A patch that introduces new features to a Public Contract SHOULD do so using new names.
+- Old names SHOULD be deprecated in a systematic fashion by marking new names as "experimental" until they are stable, then marking the old names as "deprecated".
+- When sufficient time has passed, old deprecated names SHOULD be marked "legacy" and eventually removed.
+- Old names MUST NOT be reused by new features.
+- When old names are removed, their implementations MUST provoke an exception (assertion) if used by applications.
+
+### Project administration
+
+- The project founders MUST act as Administrators to manage the set of project Maintainers.
+- The Administrators MUST ensure their own succession over time by promoting the most effective Maintainers.
+- A new Contributor who makes a correct patch MUST be invited to become a Maintainer.
+- Administrators MAY remove Maintainers who are inactive for an extended period of time, or who repeatedly fail to apply this process accurately.
+- Administrators SHOULD block or ban "bad actors" who cause stress and pain to others in the project. This should be done after public discussion, with a chance for all parties to speak. A bad actor is someone who repeatedly ignores the rules and culture of the project, who is needlessly argumentative or hostile, or who is offensive, and who is unable to self-correct their behavior when asked to do so by others.
diff --git a/docs/LEVIN_PROTOCOL.md b/docs/LEVIN_PROTOCOL.md
new file mode 100644
index 000000000..43500fd06
--- /dev/null
+++ b/docs/LEVIN_PROTOCOL.md
@@ -0,0 +1,165 @@
+# Levin Protocol
+This is a document explaining the current design of the levin protocol, as
+used by Monero. The protocol is largely inherited from cryptonote, but has
+undergone some changes.
+
+This document also may differ from the `struct bucket_head2` in Monero's
+code slightly - the spec here is slightly more strict to allow for
+extensibility.
+
+One of the goals of this document is to clearly indicate what is being sent
+"on the wire" to identify metadata that could de-anonymize users over I2P/Tor.
+These issues will be addressed as they are found. See `ANONMITY_NETWORKS.md` in
+the `docs` folder for any outstanding issues.
+
+> This document does not currently list all data being sent by the monero
+> protocol, that portion is a work-in-progress. Please take the time to do it
+> if interested in learning about Monero p2p traffic!
+
+
+## Header
+This header is sent for every Monero p2p message.
+
+```
+ 0               1               2               3
+ 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7 0 1 2 3 4 5 6 7
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|      0x01     |      0x21     |      0x01     |      0x01     |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|      0x01     |      0x01     |      0x01     |      0x01     |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|                             Length                            |
+|                                                               |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|  E. Response  |                   Command
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+                |                 Return Code
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+                |Q|S|B|E|               Reserved
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+                |      0x01     |      0x00     |      0x00     |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|     0x00      |
++-+-+-+-+-+-+-+-+
+```
+
+### Signature
+The first 8 bytes are the "signature" which helps identify the protocol (in
+case someone connected to the wrong port, etc). The comments indicate that byte
+sequence is from "benders nightmare".
+
+This also can be used by deep packet inspection (DPI) engines to identify
+Monero when the link is not encrypted. SSL has been proposed as a means to
+mitigate this issue, but BIP-151 or the Noise protocol should also be considered.
+
+### Length
+The length is an unsigned 64-bit little endian integer. The length does _not_
+include the header.
+
+The implementation currently rejects received messages that exceed 100 MB
+(base 10) by default.
+
+### Expect Response
+A zero-byte if no response is expected from the peer, and a non-zero byte if a
+response is expected from the peer. Peers must respond to requests with this
+flag in the same order that they were received, however, other messages can be
+sent between responses.
+
+There are some commands in the
+[cryptonote protocol](#cryptonote-protocol-commands) where a response is
+expected from the peer, but this flag is not set. Those responses are returned
+as notify messages and can be sent in any order by the peer.
+
+### Command
+An unsigned 32-bit little endian integer representing the Monero specific
+command being invoked.
+
+### Return Code
+A signed 32-bit little integer integer representing the response from the peer
+from the last command that was invoked. This is `0` for request messages.
+
+### Flags
+ * `Q` - Bit is set if the message is a request.
+ * `S` - Bit is set if the message is a response.
+ * `B` - Bit is set if this is a the beginning of a [fragmented message](#fragmented-messages).
+ * `E` - Bit is set if this is the end of a [fragmented message](#fragmented-messages).
+
+### Version
+A fixed value of `1` as an unsigned 32-bit little endian integer.
+
+
+## Message Flow
+The protocol can be subdivided into: (1) notifications, (2) requests,
+(3) responses, (4) fragmented messages, and (5) dummy messages. Response
+messages must be sent in the same order that a peer issued a request message.
+A peer does not have to send a response immediately following a request - any
+other message type can be sent instead.
+
+### Notifications
+Notifications are one-way messages that can be sent at any time without
+an expectation of a response from the peer. The `Q` bit must be set, the `S`,
+`B` and `E` bits must be unset, and the `Expect Response` field must be zeroed.
+
+Some notifications must be in response to other notifications. This is not
+part of the levin messaging layer, and is described in the
+[commands](#commands) section.
+
+### Requests
+Requests are the basis of the admin protocol for Monero. The `Q` bit must be
+set, the `S`, `B` and `E` bits must be unset, and the `Expect Response` field
+must be non-zero. The peer is expected to send a response message with the same
+`command` number.
+
+### Responses
+Response message can only be sent after a peer first issues a request message.
+Responses must have the `S` bit set, the `Q`, `B` and `E` bits unset, and have
+a zeroed `Expect Response` field. The `Command` field must be the same value
+that was sent in the request message. The `Return Code` is specific to the
+`Command` being issued (see [commands])(#commands)).
+
+### Fragmented
+Fragmented messages were introduced for the "white noise" feature for i2p/tor.
+A transaction can be sent in fragments to conceal when "real" data is being
+sent instead of dummy messages. Only one fragmented message can be sent at a
+time, and bits `B` and `E` are never set at the same time
+(see [dummy messages](#dummy)). The re-constructed message must contain a
+levin header for a different (non-fragment) message type.
+
+The `Q` and `S` bits are never set and the `Expect Response` field must always
+be zero. The first fragment has the `B` bit set, neither `B` nor `E` is set for
+"middle" fragments, and `E` is set for the last fragment.
+
+### Dummy
+Dummy messages have the `B` and `E` bits set, the `Q` and `S` bits unset, and
+the `Expect Reponse` field zeroed. When a message of this type is received, the
+contents can be safely ignored.
+
+
+## Commands
+### P2P (Admin) Commands
+
+#### (`1001` Request) Handshake
+#### (`1001` Response) Handshake
+#### (`1002` Request) Timed Sync
+#### (`1002` Response) Timed Sync
+#### (`1003` Request) Ping
+#### (`1003` Response) Ping
+#### (`1004` Request) Stat Info
+#### (`1004` Response) Stat Info
+#### (`1005` Request) Network State
+#### (`1005` Response) Network State
+#### (`1006` Request) Peer ID
+#### (`1006` Reponse) Peer ID
+#### (`1007` Request) Support Flags
+#### (`1007` Response) Support Flags
+
+### Cryptonote Protocol Commands
+
+#### (`2001` Notification) New Block
+#### (`2002` Notification) New Transactions
+#### (`2003` Notification) Request Get Objects
+#### (`2004` Notification) Response Get Objects
+#### (`2006` Notification) Request Chain
+#### (`2007` Notification) Response Chain Entry
+#### (`2008` Notification) New Fluffy Block
+#### (`2009` Notification) Request Fluffy Missing TX
diff --git a/docs/README.i18n.md b/docs/README.i18n.md
new file mode 100644
index 000000000..5df277624
--- /dev/null
+++ b/docs/README.i18n.md
@@ -0,0 +1,56 @@
+Monero daemon internationalization
+==================================
+
+The Monero command line tools can be translated in various languages. If you wish to contribute and need help/support, contact the [Monero Localization Workgroup on Taiga](https://taiga.getmonero.org/project/erciccione-monero-localization/) or come chat on `#monero-translations` (Freenode/IRC, riot/matrix, MatterMost)
+
+In order to use the same translation workflow as the [Monero Core GUI](https://github.com/monero-project/monero-gui), they use Qt Linguist translation files.  However, to avoid the dependencies on Qt this normally implies, they use a custom loader to read those files at runtime.
+
+### Tools for translators
+
+In order to create, update or build translations files, you need to have Qt tools installed. For translating, you need either the **Qt Linguist GUI** ([part of Qt Creator](https://www.qt.io/download) or a [3rd-party standalone version](https://github.com/lelegard/qtlinguist-installers/releases)), or another tool that supports Qt ts files, such as Transifex.  The files are XML, so they can be edited in any plain text editor if needed.
+
+### Creating / modifying translations
+
+You do not need anything from Qt in order to use the final translations.
+
+To update ts files after changing source code:
+
+```bash
+./utils/translations/update-translations.sh
+```
+
+To add a new language, eg Spanish (ISO code es):
+
+```bash
+cp translations/monero.ts translations/monero_es.ts
+```
+
+To edit translations for Spanish:
+
+```bash
+linguist translations/monero_es.ts
+```
+
+To build translations after modifying them:
+
+```bash
+./utils/translations/build-translations.sh
+```
+
+To test a translation:
+
+```bash
+LANG=es ./build/release/bin/monero-wallet-cli
+```
+
+To add new translatable strings in the source code:
+
+Use the `tr(string)` function if possible. If the code is in a class, and this class doesn't already have a `tr()` static function, add one, which uses a context named after what `lupdate` uses for the context, usually the fully qualified class name (eg, `cryptonote::simple_wallet`).  If you need to use `tr()` in code that's not in a class, you can use the fully qualified version (eg, `simple_wallet::tr`) of the one matching the context you want. Use `QT_TRANSLATE_NOOP(string)` if you want to specify a context manually.
+
+If you're getting messages of the form:
+
+```
+Class 'cryptonote::simple_wallet' lacks Q_OBJECT macro
+```
+
+all is fine, we don't actually need that here.
diff --git a/docs/ZMQ.md b/docs/ZMQ.md
new file mode 100644
index 000000000..9128ff2ad
--- /dev/null
+++ b/docs/ZMQ.md
@@ -0,0 +1,61 @@
+# The Current/Future Status of ZMQ in Monero
+
+## ZMQ Pub/Sub
+Client `ZMQ_SUB` sockets must "subscribe" to topics before it receives any data.
+This allows filtering on the server side, so network traffic is reduced. Monero
+allows for filtering on: (1) format, (2) context, and (3) event.
+
+ * **format** refers to the _wire_ format (i.e. JSON) used to send event
+   information.
+ * **context** allows for a reduction in fields for the event, so the
+   daemon doesn't waste cycles serializing fields that get ignored.
+ * **event** refers to status changes occurring within the daemon (i.e. new
+   block to main chain).
+
+ * Formats:
+   * `json`
+ * Contexts:
+   * `full` - the entire block or transaction is transmitted (the hash can be
+     computed remotely).
+   * `minimal` - the bare minimum for a remote client to react to an event is
+     sent.
+ * Events:
+   * `chain_main` - changes to the primary/main blockchain.
+   * `txpool_add` - new _publicly visible_ transactions in the mempool.
+     Includes previously unseen transactions in a block but _not_ the
+     `miner_tx`. Does not "re-publish" after a reorg. Includes `do_not_relay`
+     transactions.
+
+The subscription topics are formatted as `format-context-event`, with prefix
+matching supported by both Monero and ZMQ. The `format`, `context` and `event`
+will _never_ have hyphens or colons in their name. For example, subscribing to
+`json-minimal-chain_main` will send minimal information in JSON when changes
+to the main/primary blockchain occur. Whereas, subscribing to `json-minimal`
+will send minimal information in JSON on all available events supported by the
+daemon.
+
+The Monero daemon will ensure that events prefixed by `chain` will be sent in
+"chain-order" - the `prev_id` (hash) field will _always_ refer to a previous
+block. On rollbacks/reorgs, the event will reference an earlier block in the
+chain instead of the last block. The Monero daemon also ensures that
+`txpool_add` events are sent before `chain_*` events - the `chain_*` messages
+will only serialize miner transactions since the other transactions were
+previously published via `txpool_add`. This prevents transactions from being
+serialized twice, even when the transaction was first observed in a block.
+
+ZMQ Pub/Sub will drop messages if the network is congested, so the above rules
+for send order are used for detecting lost messages. A missing gap in `height`
+or `prev_id` for `chain_*` events indicates a lost pub message. Missing
+`txpool_add` messages can only be detected at the next `chain_` message.
+
+Since blockchain events can be dropped, clients will likely want to have a
+timeout against `chain_main` events. The `GetLastBlockHeader` RPC is useful
+for checking the current chain state. Dropped messages should be rare in most
+conditions.
+
+The Monero daemon will send a `txpool_add` pub exactly once for each
+transaction, even after a reorg or restarts. Clients should use the
+`GetTransactionPool` after a reorg to get all transactions that have been put
+back into the tx pool or been invalidated due to a double-spend.
+
+