Rholang Foreign Function Interface - WIP

Use Cases

1. Developer Doe wants to deploy an DApp on RChain that uses a different coin as the basis for transactions on his application.  He would like to have different signatures from those offered natively on RChain. He chooses a cryptographic function from the Rholang documentation and authors his smart contract.

2. Developer Smith has a Java application that returns some interesting data that he wants to expose to the blockchain via a Rholang contract.  He installs the Jar file on his RChain node and then runs a command to 'Add Oracle' , which returns back a channel name.  He applies the channel name in his Rholang contract and observes that his contract can now expose and use the data from his Java application. 

Traceability Matrix

The work for the FFI is captured in:  CORE-192 - Getting issue details... STATUS

Design Considerations

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

• How does the FFI know where on the system the jar files exist?  Do we implement a 'path' parameter that needs to be set?
• Economics of exposing a jar file to Rholang.  How will execution cost & cost bounding be applied to a foreign process?  Michael Stay (Unlicensed)
  • If the economics of Oracles cannot be figured out, we will not support Oracles in the Mercury time frame.

Interfaces  

Describe how the software will interface with other software components.

• It will expose the Cryptography primitives to Rholang via a system channel – > Michael Stay (Unlicensed) - we need to begin specifying what the system powerbox contracts are in detail.
• It will expose FFI objects to the system powerbox in some fashion (needs to be specified)

• The FFI will take a function out of the jar and then wrap it in a process that is waiting for input, passes it along, computes it and then sends it along to a channel.  The jar file will be exposed via the Java class loader.

System Interface

• The FFI will need a location on the system where it reads Jar files from.  Installation / deployment of upgraded RChain software should not impact this directory - therefore the directory should exist outside of the RChain folder.  See Design considerations.

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

• The FFI will only support jar files.  All other binaries are not supported.

Assumptions and Dependencies

Depends on:

• System powerbox needs to create channels and provide 'capabilities' to Rholang for the library.  The FFI exposes the class objects to the powerbox, but cannot create the channels for Rholang to access.
• Cryptography won't be available to use in Rholang until the FFI is in place.
• The P2P Communications layer and the storage layer will not use the FFI to interact with Cryptographic functions.  These components will talk directly to Cryptographic API's 

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

new fsRet in {
  system!("getFs", fsRet) |
  for (fs <- fsRet) {
    fs!("load", "MyJar.jar", myJarRet) |
    for (myJar <- myJarRet) new ffiRet in {
      system!("getFFI", ffiRet) |
      for (ffi <- ffiRet) new myClassCtorRet in {
        ffi!("link", myJar, "MyClass", myClassCtorRet) |
        for (myClassCtor <- myClassCtorRet) new myClassInstanceRet in {
          myClassCtor!(arg1, ..., argn, myClassInstanceRet) |
          for (myClassInstance <- myClassInstanceRet) new ret in {
            myClassInstance!("method", arg1, ..., argn, ret) |
            for (val <- ret) {
              // do something with val, etc.
            }
          }
        }
      }
    }
  }
}