Node Specification -WIP

Use Cases

User Experience of setting up a Node from scratch: 

• Download the RChain software
• Install the software. 
  • Installation should include the following configuration options:
    • Does the user have a set of ETH keys they wish to use?  If so, then they need to have them ready.
      • If they want to use existing keys, need to provide the key pair, so TLS can be set up with these keys. Todo: Need to see if Sebastian is able to generate a certificate from a set of keys that will work with TLS or not.
      • If not, the system will generate a set of keys. 
    • Node connecting to an existing network or setting up a new one?
      • Setting up a new network configures the node as a bootstrap.  User will need to enter static IP address + network name
    • Select the network to join.  Node connects to bootstrap node & sets up.
• When the installation is complete, the user is presented with a browser window where they can observe the node signature keys  (Node ID), and configure the node.
• Register the node:
  
  • Select the namespace(s) where you wish to run your node. (Is there a way to see the transaction fees / namespace?)
  • Observe the keys for the node (Needed as wallet for bonding / rewards) & transfer funds from another address.
  • Determine what kind of node it is: bonded validator or watcher.  or read only node (unbonded)
  • Join the namespace (includes your stake for consensus), download contracts, Obtain the data needed to match state with other validators, compile locally (create any private names for these contracts)
  • Start validating

Startup

• As a Node operator I need to be able to start my node, and know that the node started up properly.
  • Requires that the startup process ensures that all components are instantiated correctly and have the necessary resources to function.
• The RChain node will run as a process in systemd.  The installation process registers the RChain node as a daemon in systemd.
• A Node has to have a public / private key that represents the node's identity.
• Present a web interface that the user can interact with that shows all the features available via the gRPC API (details in API specification)

Connecting to a Network

• As a DApp Developer, I need the ability to start the node in disconnected mode, so that I can develop and test my smart contract locally without incurring any costs.
• As a DApp Developer, I need the ability to connect the node to a test net of my choosing, so that I can test my smart contract against a blockchain. 
• As a DApp Developer, I need the ability to connect the node to the production RChain network so I can deploy my smart contract.

Monitoring & Logging

• As a Node operator I want metrics on my node's performance.
  • Demonstrate Prometheus charts for each of these metrics.
    
    • CPU % utilization for the rNode process
    • RAM (in MB)
      • amount of memory being Utilized by rNode.
      • amount being consumed by rSpace
    • Disk consumption (in MB)
      • by rNode (blockchain storage) 
      • by rSpace (tuplespace storage)
    • Network core metrics at the core level
      
      • Messages by message type (include the message type in the metric)
      • Response time for network messages - raw numbers only
    • JVM performance
    • Garbage collection
    • Size of memory pools
    • Consumption of memory pools
• As a Node operator I want all the logs to land in a place where I am used to finding system logs (follow best practice - use syslogs & apachelog4j)

Running Contracts

• As a contract author, I want my contracts to be persisted on Nodes.
• As a dApp developer, I want to run a contract and receive output from running that contract.
• As a dApp developer, I have to know if there are syntax errors in my contracts.
• The Node must process requests to run contracts.  These messages will contain a contract, a rev→ phlogiston exchange rate and some phlogiston to pay for execution.
  
  • The node accepts the message and runs the contract. Either the contract runs to completion, or pauses for input (continuation) or phlogiston runs out.
• As a Node Operator I want to know how many contracts are running on my node.
• As a Node Operator, I want to be able to configure my node to prioritize contract execution based upon the Rev→ phlogiston exchange rate so that I can make the most money from fees.

Consensus

• As a Node operator I need a way to opt into becoming a bonded validator.
• As a Node operator I need a wallet that can hold my staking tokens so I can become a bonded validator.
• As a Node operator I need a way to switch from being a bonded to unbonded validator and back.
• As a Node operator I need a way to opt into becoming a bonded watcher.
• A node has to listen for new blocks (state updates).
• A node has to implement the state transition when it accepts a block.  This involves deducing what the state should be based on transactions it has received, and those in the block. 
• When a node leaves a namespace, the local blockchain data should persist on the node.
• Validators must be able to join and leave the network and a namespace at will.

User Interface -

• As a Node operator, I want a Web Interface that shows me all the ways in which I can configure and interact with my node.  This interface will consume a gRPC API.
• As a dApp developer, I want to query the blockchain data on the node so that I can get analytics on my dApp.
• As a Node operator I need to know which RChain network my node has connected to.
• As a Node operator I would like to know how many peers my node has connected to.

• As a Node operator I need to  select a namespace or set of namespaces to join.

• A node needs to set a starting state when it joins the network.  The node should retrieve a set of recently finalized blocks and apply that state.  Then the node can start processing transactions.

Traceability Matrix

Monitoring

Startup

Web Interface

Design Considerations

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

• At some point in the future, the node will support multiple instances of the RChain execution engine.  These instances will all share a single storage subsystem.
• Similarly, these multiple execution engines will all share a single communications subsystem.
• The node will need cryptography in order to generate a public and private key. 
• Currently the communications subsystem determines 'proximity' based upon response time, does this need to be re-visited for any reason.  Are there requirements lurking when namespaces / geography becomes a factor? (For example, geographical namespaces that are restricted for some reason due to international trade law/ treaties)
• The Node API must be forwards and backwards compatible.

Interfaces  

Describe how the software will interface with other software components.

System Interface

The RChain Node installation software will register itself with systemd, and integrate properly systemd as a daemon such that the systemd-ui works properly with the node software.

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.

The RChain team has received feedback from exchanges that they would like to integrate with a JSON API, however, experience has shown that JSON will not meet the forwards/backwards compatibility requirements listed above. Therefore, Protocol Buffers have been selected as the base API.  The Protocol buffer API will have the largest surface area of all the API's.  Other API's can be created as special projects, as consumers of the Protobuf API by taking its output and passing it to a REST API or JSON API.

Users may interact with the RChain API interface, the Protobuf interface or a REST API interface.   

Ethereum API Reference: https://github.com/ethereum/go-ethereum/wiki/Management-APIs   (Use to see obvious api's that we will likely need to support also)

User Interface

Insert the screen specification for the Web Interface here.

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.  

The node will run on a linux system as a systemd process (daemon).  The primary user interface for the node will be a GRPC Protobuf API.  It is desirable to create a utilitarian web interface that will interact with management functions in the API.  

The main function of the node implements the System Powerbox -in that there is a block of code that instantiates all the components that make up the RChain Node.  These components are:

• Communications subsystem
• Scala libraries that interface with the local file system, SDTOUT and other system processes - aka Powerbox
• Storage subsystem
• Execution engine (Interpreter or Virtual Machine)
• API servers for JSON API, GRPC API

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