diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/ANONYMITY_NETWORKS.md | 236 | ||||
| -rw-r--r-- | docs/CONTRIBUTING.md | 172 | ||||
| -rw-r--r-- | docs/LEVIN_PROTOCOL.md | 165 | ||||
| -rw-r--r-- | docs/README.i18n.md | 56 | ||||
| -rw-r--r-- | docs/ZMQ.md | 61 |
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. + + |