Node API Specification

Owned by Medha Parlikar (Unlicensed)
Last updated: May 08, 2018


Introduction

Purpose:

Describe the purpose, scope and intended audience of the document.

To specify the Node API, its' functions and its' behavior such that the Core development team can implement the API. 

References:

Call out any related documents, pre-requisite documents, and documents that provide context or background.

Definitions:

Define any important terms or acronyms or abbreviations.

Scope

The API will serve as the primary interface into the RChain Node. 


Use Cases


API 

  • Must provide backward and forward compatibility (please implement using Google protocol buffers (gRPC Service)
  • Generate API documentation through code, rather than writing documentation. 
  • Runs as an http service, and can be configured to be called from another server if desired.
  • There should be some security check for calling the Node API.   https://grpc.io/docs/guides/auth.html - It should not be possible for 'anyone' to simply interrogate a node's API without passing a security check.

Authoring & Running Contracts (Separate from blockchain)

  • Expose the Interpreter REPL interface
  • Accept a Rholang text file for evaluation by the interpreter, validate that the file contains text only, and then pass the contents of the file to the Interpreter.
    • Throw an error if the file contains non-text data.
    • Return the results of evaluation.


Invoking blessed Contracts

It isn't clear right now if the invocation of a blessed contract and the invocation of a user contract can use the same API call or not.  For the purposes of this specification, I will separate them.

  • An API to invoke the blessed Proof of Stake contract in the root namespace to support Validator Bonding.
    • Takes in a reference to a purse, the namespace the validator is wanting to bond into and the Validator public key.
      • The public key is retrieved from the system.  There isn't a way for the caller to pass in a key manually.  Provides for additional guarantees that each node runs only a single validator.
      • Returns a result, request accepted or rejected 
      • Validator status - active or queued.
  • An API to invoke the blessed Proof of Stake contract in the root namespace to support Validator Unbonding.
    • Takes in the validator public key (retrieved from the system) and the namespace(s) the validator is wanting to unbond from
      • Returns an unforgeable name to a purse, which the validator can check for bond to appear in after the wait time has expired.
  • An API to send rewards to an RChain wallet address.

I cannot see any reason why the local Proof of Stake contract should be called by the Node Operator.

Validator Actions

Node Operators that are running a validating node will need to perform specific operations around validator functions.

  • Return the rewards accrued for a given date range for the node (Validator)
  • View the list of contracts the node is processing 


User Actions with the Blockchain

  • Return a block given its hash
  • Return the code at a given block hash and namespace (address) 
  • View a transaction at a given block hash and namespace (address)
  • Create a transaction (includes the deployment of new contracts / code) and sign it with the user's private key

Exchanges

Exchanges are an example of a specific type of RChain user, that will operate RChain nodes of any type (Validator, Watcher or Bystander), depending on what functions the exchange needs the node to perform.  These API calls are described at a high level only

  • Return a list of functions available in the API
  • Create an account - offline.  This is an API that the exchange will want to run separate to the node for security reasons. 
    • Accounts are created outside of the node software with an address format compatible with the blockchain, and then a broadcast message is sent to transmit a transaction to the blockchain separately.  
    • Michael Birch (Unlicensed): This requirement specifically talks about creating addresses (wallets and purses in RChain) separately from the node - for security reasons.  There does not appear to be a straightforward mechanism to meet this requirement.
    • Option: Generate an Ethereum like key and pass this key to a contract that creates the RChain wallet and purse offline?
  • Sign transactions (offline) - Transactions are signed separate from the node software for security reasons.  Signed transactions are created and sent to the exchange wallet and then broadcast to the blockchain.
  • Broadcast the transaction to the blockchain
  • Obtain the transaction status from the blockchain - After a transaction has been sent to the node, exchanges have to provide a processing status.
    • Retrieve the block id for a given transaction id.
    • Retrieve the block fault level (justifications and validators) for a given block id.
  • Observe balance within an account on the blockchain 
    • This would be a call to a wallet contract on the RChain blockchain with a reference to the purse (the unforgeable name)


Error Messages:

Every API needs to return error messages, to ensure a good user experience.

  • Authentication error.  Since we want to provide some kind of security for the API, if a request is made without prior authentication, the API should return an 'Http 401 'Unauthorized error' 

Design Considerations

  • The API must not accept files directly, as this presents a security risk.


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