Communications Specification

Use Cases

When an RChain node starts up, one of the first things it has to do is find an RChain network to connect with.  The node should start by looking for bootstrap nodes that represent a starting point of an RChain network. Each of the bootstrap nodes should have an associated RChain network name. When a network is selected, the node locates a bootstrap node in that network (fastest response time) and connects to it.  Then the node downloads the information it needs from the bootstrap node to connect to the network.

Basic Networking

• The RChain system has to operate over a peer to peer network. 
• Each node should have a limited number of peers.  This means that all nodes must not connect to all other nodes necessarily, unless the network size is small.
  • An arbitrary limit of 50 peers was implemented by Chris Kirkwood.  ToDo: Validate if this is the right number. Need to determine how rapidly slashing messages need to be propagated through the network.
• The IP address of any given node is not material to the network.
• Nodes can come and go from the network randomly, and this should not matter to the robustness and functioning of the network.
• The Communications subsystem should allow for a generic message packet, where the calling process can define the message data structure.
• The system should implement an industry standard protocol, that is generally accepted for its security, speed and reliability.
• Users running geth (Ethereum Mist) on their local network should also be able to run an RChain node on their local network.
  • The communications subsystem has to support NAT busting and UPnP as an option, so that users are not required to have a public IP address in order to connect to the network.

Bootstrap Node:

• There have to be multiple bootstrap nodes that will provide the initial configuration for the network, so that there is geographical redundancy and speed around on boarding nodes on to the network.
• The bootstrap nodes need to have a static IP address.
• The option to configure a node as a bootstrap or non-bootstrap should be in a configuration file, not code, so that new bootstrap nodes can easily be created.
• The node software will accept a DNS name such as testnet.rchain.coop as the bootstrap location. 
• There is no economic incentive for being a bootstrap node.
• The bootstrap nodes will reside behind DNS. 
• The addresses of bootstrap nodes can be published on the rchain.coop website.  This way the addresses of the nodes need not be hard coded into the package.

Security and Identities

• A node must have a unique identity, which is a cryptographic signature, comprising of public and private keys.  Also known as nonce.  This ID is separate from the communications keys & identity
• Node communications must be encrypted for security.
• When 2 nodes connect for the first time, the nodes must exchange public keys and a shared secret.
• If the node does not have a certificate (public key & identity) then the system must generate one upon startup.  The Communications software should store the certificate in the data directory where application data is stored.  If a certificate is not found in the designated location, then a certificate should be generated by the system.
• Messages from a node must be encrypted.
• A node knows where a message came from by virtue of the node's identity (public key). No other identification is required.
• A node can have only a single identity.  
• In order for a node to be a validator, it must have a certificate that is signed with its validator key.
• The communications subsystem has to check the validator key against the list of bonded validators in the Casper PoS contract.  This prevents a Man in the middle attack.  

Starting up the Communications subsystem

Design Considerations

Describe the issues which need to be addressed or resolved before attempting to devise a complete design.

Interfaces  

Describe how the software will interface with other software components.

System Interface

TODO - sort this section out.

Hardware Interface

Describe how the software will interface with physical systems, ex: ports for communication, which devices are to be supported and any hardware protocols used.

Software Interface

Will software be used in creating the system? If so, indicate what software (name and version), how it is to be used, and any details about how it interfaces with the software being specified.

User Interface

What is the user interface for the software? How will users interact with the software?  List out all the aspects involved in making the UI better for all users that will interact or support the software.

Communications Interface

System Overview

Provide a description of the software system, including its functionality and matters relating to the overall system and design.  Feel free to split this up into subsections, or use data flow diagrams or process flow diagrams.  

Limitations

Assumptions and Dependencies

Architectural Strategies

Describe any design decisions and/or strategies that affect the overall organization of the system and its higher-level structures. These strategies should provide insight into the key abstractions and mechanisms used in the system architecture. Describe the reasoning employed for each decision and/or strategy (possibly referring to previously stated design goals and principles) and how any design goals or priorities were balanced or traded-off. Such decisions might concern (but are not limited to) things like the following:

• Use of a particular type of product (programming language, database, library, etc. ...)
• Reuse of existing software components to implement various parts/features of the system
• Future plans for extending or enhancing the software
• User interface paradigms (or system input and output models)
• Hardware and/or software interface paradigms
• Error detection and recovery
• Memory management policies
• External databases and/or data storage management and persistence
• Distributed data or control over a network
• Generalized approaches to control
• Concurrency and synchronization
• Communication mechanisms
• Management of other resources

System Architecture