Skip to content
No description, website, or topics provided.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.

README.md

Bridge.ixi

Abstract

The vision of the IOTA eXtension Interface (IXI) is to enable cross-language support. It's describing a future in which modules can be written in any programming language desired. At the moment, however, modules for the Iota Controlled agenT (Ict) must be written in the same language as the core is written. It's a limitation, code written in other languages can not be injected into Ict. This can be solved in several ways: first, by rewriting Ict in all desired programming languages, second, by having a seperate, specific interface for each language (e.g. JNI, Jython, ...) , or third, by having one uniform, language-neutral interface. Since the first and second solutions are not well scalable, the third solution is preferred.

Bridge.ixi represents the interface which allows modules written in any programming language to interact with the underlying infrastructure. By giving everyone the opportunity to participate with their desired programming language, Bridge.ixi will help grow the module ecosystem as well as have positive impact on the overall development.

Architecture

Bridge.ixi provides a socket mechanism to allow external modules interact with IXI and its internal Environment-Entity-Effect (EEE) infrastructure. By acting like a proxy, Bridge.ixi will forward external requests and return internal responses. The interface should be as minimal and straightforward as the underlying IXI. Besides that, Bridge.ixi should serve as high-speed I/O engine and handle requests asynchronous.

Protocol

Bridge.ixi acts as a server and waits for clients (modules) to connect. The default port should be the same for every Bridge.ixi implementation. By this, external modules will be easily pluggable and don't need to know to what core implementation they're talking to. Each connection will be handled in its own service thread. As soon as a module is connected, it can submit requests. For each request, the service thread interacts with the underlying IXI and returns the appropriate response back to the module.

Serialization

Bridge.ixi makes use of protocol buffers, an efficient, language-neutral mechanism for serializing structured data. With protobuf3, the following languages are supported: Java, Python, Objective-C, C++, Dart, Go, Ruby, C#, JavaScript and PHP. Third-party implementations are also available for C, Rust, Elixir, Haskell, Swift and many more.

Installation

Step 1: Install Ict

Please find instructions on iotaledger/ict.

Make sure you are connected to the main network and not to an island, otherwise you won't be able to message anyone in the main network.

Step 2: Get Bridge.ixi

There are two ways to do this:

Simple Method

Go to releases and download the bridge-{VERSION}.jar from the most recent release.

Advanced Method

You can also build the .jar file from the source code yourself. You will need Git and Gradle.

# download the source code from github to your local machine
git clone https://github.com/iotaledger/bridge.ixi
# if you don't have git, you can also do this instead:
#   wget https://github.com/iotaledger/bridge.ixi/archive/master.zip
#   unzip master.zip

# change into the just created local copy of the repository
cd bridge.ixi

# build the bridge-{VERSION}.jar file
gradle ixi

Step 3: Install Bridge.ixi

Move bridge-{VERSION}.jar to the modules/ directory of your Ict:

mv bridge-{VERSION}.jar ict/modules

Step 4: Run Ict

Switch to Ict directory and run:

java -jar ict-{VERSION}.jar

Code your module

After you have installed Bridge.ixi for your Ict, you can start coding your module in your desired language. All you need to do is establish a tcp socket connection to the Bridge.ixi server running on port 7331. Once you have done this, you are able to send/receive protocol buffer messages.

To get a better feeling for the protocol buffers, it is a good idea to take a look at the official protocol buffer guide and the available module example.

Brief instructions for the protocol buffers

  1. Download and install the protocol buffer compiler (protoc).
  2. Run the protocol buffer compiler for your module's language on the .proto files to generate data access classes.
  3. Use these data access classes in your module project. They provide simple methods to build, serialize and deserialize your protocol buffer messages.

Note that each message must be sent within a wrapper message. This is necessary so that the participants easily know what kind of message it is. Take a look at the module example, which illustrates this better.

You can’t perform that action at this time.