Unchained Plugins

Abstract

This document describes the basic idea, information and specs of the Unchained plugin system. Plugins are third-party modules that extend the functionality of Unchained. They can either run in standalone mode to directly interact with Brokers, or they can communicate with the official Unchained Worker client to perform actions on behalf of the Worker.

Motivation

The Unchained plugin system is designed to allow developers to extend the functionality of Unchained without modifying the core codebase. This enables developers to create custom features, integrations, and workflows that are specific to their use case.

Specification

Common

This section covers the common aspects of the Unchained plugin system, whether the plugin runs in standalone mode or communicates with a Worker.

Communication

All communication between the plugin and Unchained is done via websockets. The plugin must establish a websocket connection to the Unchained Broker or Worker and send messages according to the Unchained protocol.

Websockets provide a bi-directional, full-duplex communication channel; they are the only option available in browser-based applications. There are already-existing utilities to translate websockets to other protocols, such as TCP, if needed.

Serialization

All messages exchanged between the plugin and Unchained must be serialized using Sia. Sia is a binary serialization format that is used to encode and decode messages in a compact and efficient manner.

Sia is ultra fast and has a small memory footprint. It is usable in a wide range of applications, from embedded systems to high-performance servers.

Programming Language

Any programming language that supports websockets and Sia can be used to create Unchained plugins. The official Unchained SDKs provide helper functions for establishing websocket connections and serializing messages; however, developers are free to implement these functionalities in any language.

Plugin Manager

Plugins should be installable and manageable via a plugin manager. The plugin manager is responsible for downloading, installing, and updating plugins. It should also provide a way to enable, disable, and configure plugins:

Plugins should be hosted in and installed from a git repository. At the root of the repository, there should be a `plugin.yaml` file that contains metadata about the plugin, such as the name, version, description, and dependencies.

Preferreably, the plugin manager should not rely on Docker or any other containerization technology to run plugins. This allows plugins to run in the same environment as Unchained without any additional overhead. Security of such plugins should be ensured by code reviews and audits. Plugin developers should gain the trust of the community by providing open-source code and documentation.

Plugin Explorer

Timeleap should provide a Plugin Explorer that allows users to discover and install plugins from a central repository. The Plugin Explorer should display information about each plugin, such as the name, description, author, and version. Users should be able to install plugins with a single click.

API Marketplace

Timeleap should provide an API Marketplace that allows developers to publish and monetize their plugins. The API Marketplace should provide a way for developers to set pricing, manage subscriptions, and receive payments.

RPC Interface

Plugins should expose an RPC interface that allows Unchained consumers to interact with the plugin. The RPC interface must be defined using the Sia schema language and should be documented in the plugin's repository.

Sia Schema Intermediate Representation (SIR) is a language-agnostic way to define the structure of messages exchanged between the plugin and Unchained. It is used to generate code for serializing and deserializing messages in various programming languages.

Unchained should provide a tool that generates RPC client and server code from the Sia schema (through git repositories) or from SIR files (through the API Marketplace):

Standalone

In standalone mode, plugins directly interact with the Unchained Broker. In other words, they are the worker themselves. This mode is suitable for plugins that require the lowest latency and highest throughput. Develoeprs can use the official Unchained SDKs to create standalone plugins. They can also refer to the Unchained protocol documentation and worker implementation for more information.

Developers targeting standalone mode are encouraged to use the official Unchained SDKs. In case the SDKs do not support the desired functionality or the target programming language, developers should use a well-supported third-party SDK.

If an SDK is not available for the desired programming language, developers should implement a generic purpose SDK for public use instead of creating a monolithic plugin that embeds their implementation of Unchained SDK.

Through Unchained Worker

The Unchained Worker provides a set of basic functionalities for connecting to and interacting with the Unchained Broker. This includes establishing a websocket connection, handling authentication, cryptographic signatures, and message routing.

Plugins that do not want to implement these functionalities themselves can communicate with the Unchained Worker to perform actions on behalf of the Worker. The official Unchained Worker client provides a plugin interface that allows plugins to send and receive messages to and from the Worker.

Currently, the Unchained AI Plugin works in this mode and is a good example of how to create a plugin that communicates with the Unchained Worker.

Rationale

Initially, Unchained was designed to be a standalone application with a fixed set of features. However, as the ecosystem grows, it becomes clear that developers need a way to extend the functionality of Unchained without modifying the core codebase. The Unchained plugin system provides a way for developers to create custom features, integrations, and workflows that are specific to their use case.

For example, the UniSwap plugin (Price Feeds) is now removed from the core Unchained codebase and will be available as a plugin. This gives users the flexibility to choose which plugins they want to use and allows them to easily install, update, and manage plugins.

Plugins can also act as consumers; for example, a MongoDB plugin can store messages in a MongoDB database, or am EVM plugin can execute smart contracts on the Ethereum Virtual Machine (Oracles) and return the results to Unchained.

Backwards Compatibility

The current implementation of Unchained worker relies on UNIX sockets for communication with plugins. This is a legacy feature that will be deprecated in favor of websockets. The Unchained Worker will be updated to support websockets and the new plugin system. UNIX sockets are generally faster than websockets, but they are also more complex to use and less portable.

Reference Implementation

N/A

References

N/A