Node Specification -WIP

Use Cases

User Experience of setting up a Validating Node from scratch: 

• Acquire the required Validator bond amount (out of protocol, needs to be done via an exchange or other means).
• Create a purse / ETH style account in the shard of choice.
• Send the bonding request
• Download the RChain software
• Install the RNode software. 
  • Create the configuration file for the node & include the options that you want.
  • Include your public validator key as part of your configuration file. 
  • Start the software (validating node)
    • When the software starts up, it will generate a TLS certificate.
    • System prompts the user for the location/access to the private key.  User provides the location of the private key.  If a password is required, user is prompted to enter a password.
    • The software signs the certificate with the validator private key.
    • The system now waits to bond.
  • If the bonding request is approved, the node begins to receive blocks from its peers.
  • The node is ready to start processing transactions.

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.  System will display an error if it does not have the necessary components to start.
• 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.  
• If a public key is not present on the node in the directory where it expects it, one is generated at startup.
• A validator key is required at startup, for certificate signing.
• Provide a configuration file option which will hold all the server configuration options in TOML format.
• Start up a http web service where the user can interact with the Node.  Present a message to the user with a url - http://rnode/UI where they can go and interact with the node.

Selecting a Network

• As a DApp Developer, I need the ability to start the node in standalone mode, so that I can set up a mini net, to test my smart contract locally without incurring any costs.
• As a DApp Developer, I need the ability to connect the node to the network of my choosing, so that I can test my smart contract against a blockchain. 

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)
• As a Node Operator I want to know how many contracts are running on my node.

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 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.
• 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 validator, I want to see the rewards I have earned for a given time period.
• As a validator, I want to see which shard I'm validating so I know which machine is doing what.
• As a validator, I want to see if I have been slashed, and what the offence is.
• As a validator, I want to see what my bond amount is.
• 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.

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.

• 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