Plugins

Introduction

Ardor Plugins is a feature that enables third-party software developers to add functionality to the Ardor Client Interface.

This guide describes how to install and use a plugin. Because plugins have unrestricted access to the local Ardor Server including sensitive data and functionality, it is vitally important to install only trusted plugins. If there is any doubt, install a plugin only on the Testnet or on Mainnet accounts with small balances.

This guide describes Ardor Plugins as of Ardor software release 2.0.14.

Developers Guide

Prior developing a Plugin, we recommend a look at the client source code and documentation to get an overview about the various javascript APIs and best practices and examples how to use them.

For a plugin to be valid it has to be delivered with a minimum set of files and come with a manifest.json plugin manifest file being compatible with the current major plugin version and providing some meta information about the plugin.

More details

File Structure

The following is the minimal file structure for a plugin:

[plugin_name]/
[plugin_name]/manifest.json
[plugin_name]/html/pages/[plugin_name].html
[plugin_name]/html/modals/[plugin_name].html
[plugin_name]/js/nrs.[plugin_name].js
[plugin_name]/css/[plugin_name].css

Manifest File

Meta information about the plugin is provided as a JSON dictionary in a manifest.json file in following format:

{
    //mandatory
    "pluginVersion": 1, //Integer, don't use parenthesis!

    "name": "Name of your plugin", //max. 20 characters
    "myVersion": "Your plugin version", //no format requirements
    "short_description": "A description of your plugin", //max. 200 characters
    "infoUrl": "http://infosaboutmyplugin.info",
    "startPage": "p_hello_world", //One of the pages used for NRS.pages.PAGENAME method(s)

    "nrsVersion": "2.0.14", //ALWAYS provide three sequence numbers, no additions like "e"!

    //optional
    "deactivated": true, //hard-set deactivation, default: false
    "sidebarOptOut": true //opt out of being listed under sidebar "Plugins" entry, default: false
}

Hint: Don't use comments in your own JSON file!

Plugin Compatibility/Valdation

Plugins are compatible when the manifest file is written for the same major plugin version supported by the installed client. Major plugin versions won't change very often, minor plugin version releases will remain compatible within the major version. After a detected plugin is determined as compatible the NRS client will be validating the manifest file format and file structure.

NRS Compatibility

Due to the broad scope of plugins the functional compatility of the plugin with various NRS versions can't be guaranteed by the plugin mechanism and is the responsibility of the plugin creator. The nrs_version attribute in the manifest file indicates the NRS version the plugin was written for. Due to possible changes in javascript API behaviour it is recommended to release a new plugin version for every new NRS release, though a plugin will still be running after minor release updates (e.g. a plugin written for "2.2.1" running under "2.2.2" client installation). After a major NRS update (e.g. from "1.5.9" to "1.6.0"), the plugin will stop working and has to be updated.

Best Practices for Development

• Namespace your function names, CSS IDs and classes and other possible identifiers to avoid collisions affecting core NRS behaviour
• Convention vor namespacing: "p_[PLUGINNAME]_[LOCALIDENTIFIER]", e.g. "p_hello_world_info_modal"
• Don't manipulate non-plugin HTML or CSS with your javascript code or CSS declarations

Acquire a Plugin

Plugins are authored by third party developers. Some are free while others can be purchased in the Ardor Marketplace under the tag plugin. A good place to discover plugins and ask questions about them is the Ardor forum.

• Unless you are an expert coder who is able to independently verify that a plugin is safe to use, only acquire plugins that have been signed by trusted members of the Ardor community.

Install a Plugin

When the Ardor Client Interface is launched, it automatically scans the directory Ardor/html/www/plugins for plugins. A plugin is a collection of files in a certain format, all contained within a subdirectory. For example, the Hello World plugin is already installed in the official Ardor Client as the subdirectory Ardor/html/www/plugins/hello_world.

Installation of a new plugin consists of downloading a zip file from a trusted source, validating the zip file, then extracting the zip file into the Ardor/html/www/plugins directory.

Following is an example reinstallation of the Hello World plugin using a terminal window on a Linux system. Details of the procedure may vary on other systems.

Download a Plugin

Navigate to the plugins directory:

$ cd Ardor/html/www/plugins

You can find the Hello World pluging under the plugins folder:

Validate the Downloaded Plugin File

Validating a plugin ensures that the downloaded zip file has not been modified since being zipped by a trusted Ardor account owner. Validation is a two step process requiring a checksum and a checksum signature.

Acquire the Checksum

In this example the sha256 checksum (also termed hash code or message digest) is:

ed8b1c197feadea428aaa4625e356eb84f3b2ae7f6ddc1320a9a76d742392313

• A checksum always should be provided by the author of the plugin. It uniquely identifies a particular version of the plugin and can validate that your downloaded copy of the plugin is identical to the official version.

Acquire the Checksum Signature

To ensure that the checksum itself is valid, it should be digitally signed. Ardor tokens provide a convenient digital signature mechanism.

In this example an Ardor token for the checksum was generated:

89urfe4danhu1g49c07l522l3pavesdk87kul769mcvsnfjjqob222u8ci7bsvg2b0udq54enfliv8r3isfu4tdabpijqgpn7foenhmf8sogji1g21bqansbd7pge8hl5bgr1m8qvh9rt6l1ihoutqn40e03fl0l

• Tokens should be provided by the author of the plugin and may additionally be provided by users of the plugin who are satisfied that it is safe to use. Several signatures generated by trusted code experts are better than one.
• The signature may apply to a text message that includes the checksum along with other data. It only matters that the checksum is present somewhere in the message.

Validate the Checksum

The checksum can be validated using the Ardor Client as follows. First open the Ardor Token Generation / Validation pop-up entry form by clicking on the gear graphic in the upper right corner, then clicking on Generate Token:

Next, click on the Validate Token tab of the entry form and enter the checksum, or whatever text containing the checksum was signed, into the Data field and the token into the Token field. Finally, click on Validate:

• The result of the validation check is displayed, indicating whether the checksum is properly signed and if so, which account signed it and when. A valid token implies that someone who knows the signing account's secret passphrase must have signed the checksum and that the checksum has not been altered since it was signed.
• In this example the signing account is ARDOR-6GMG-FC5F-YSX6-8CVEL

Validate the File

Returning to the terminal window, still in the Ardor/html/www/plugins directory where hello_world.zip resides, pipe the checksum and downloaded filename to the sha256sum utility as follows (example with unix operating system):

$ echo "ed8b1c197feadea428aaa4625e356eb84f3b2ae7f6ddc1320a9a76d742392313 hello_world.zip" | sha256sum -c

The utility should give the result:

hello_world.zip: OK

• This validates that the downloaded zip file is the same one that was zipped initially.

Extract the Downloaded Plugin File

Now that the downloaded zip file has been validated, it can be extracted into the Ardor/html/www/plugins directory. In this example, however, the plugin is already present since it is packaged with the Ardor software. For the sake of this example, rename the existing hello_world directory:

$ mv hello_world hw

Now, extract the downloaded zip file:

$ unzip hello_world.zip

To verify that the newly created hello_world directory is the same as the preexisting one:

$ diff -r hello_world hw

If there are no differences, the diff command produces no output; otherwise, it displays differences between the two directories. If the official plugin is someday upgraded, there will be differences and there is no need to trust the version just downloaded. Simply restore the preexisting version:

$ mv hw hello_world

But if you trust the new downloaded version, you may remove the preexisting version instead:

$ rm -r hw

• When updating an existing plugin, it is advisable to remove it before installing the new version.

Activate the Plugin

The Hello World plugin is initially deactivated. To activate it, edit the manifest.json file in the directory Ardor/html/www/plugins and set the deactivated parameter to false. Then, gzip the manifest.json file with gzip -k manifest.json. The gzipped file manifest.json.gz is optional but takes precedence if present; so you may optionally delete the old manifest.json.gz rather than update it by gzipping manifest.json.

• After installing a new plugin, log out from the Ardor Client if you are logged in. The Ardor Client will load all active plugins when you next log in, if plugins are enabled.

Use a Plugin

Enable Plugins

The Ardor Client Plugin System is controlled from the Settings screen. To enable plugins click on the gear graphic in the upper right corner of the Ardor Client, then click on Account Settings.

• On the Settings screen, select Yes from the Enable Plugins drop-down list to enable plugins.
• Changes to this control do not take effect until the next login, so log out.

Security Features

Plugins are loaded by the Ardor Client during login. Because plugins are potentially dangerous, the Ardor Client login screen has several plugin security features explained below. These features will not appear when there are no active plugins.

Security Notice

Hovering the cursor above the gold Security Notice box causes this warning to appear:

List of Active Plugins

Hovering the cursor above the gray Active Plugins box causes a list of all active plugins to appear:

Disable Plugins during Session

Check this box before logging in if you are using a client that anyone else has had access to, or if there is any doubt about the active plugins. This control overrides the Enable Plugins setting for the current login session.

Check a Plugin's Status

Click on the gear graphic in the upper right corner of the Ardor Client, then click on Plugins:

A Plugins screen appears listing each installed plugin and its status:

• During the login process, the Ardor/html/www/plugins directory is scanned for plugin subdirectories. Each plugin found is checked for validity, compatibility and launch status.
• A plugin is Valid if it conforms to the standard file structure and content requirements for all plugins.
• A plugin is compatible with the Ardor Client if its NRS Compatibility has the same major version number. Compatibility is indicated by a green background.
• The Ardor Client version is displayed in the upper right corner of the Ardor Client Dashboard. The major version is the first two numbers. For example, version 2.1.0e is major version 2.1.
• If the Ardor Client major version is smaller, the plugin is disabled and the Launch Status is Halted with a red background. The Ardor client should be updated.
• If the Ardor Client major version is larger, the plugin is enabled but the Launch Status is Running with a gold background, indicating that the plugin should be updated.

Remove or Deactivate a Plugin

A plugin can be removed by removing its subdirectory in the Ardor/html/www/plugins directory, then logging out of the Ardor Client.

A plugin can be deactivated without removing it by editing the manifest.json file in the plugin subdirectory. Simply change the JSON deactivated field from false to true. Then, update the manifest.json.gz file with gzip -k manifest.json. Finally, log out of the Ardor Client.

• A deactivated plugin appears on the Plugins Status screen with a Launch Status of Deactivated on a gold background.

Plugin Interface

For detailed instructions on the use of a plugin, refer to documentation provided by the author of the plugin. Typically, unless the author provides another means of access, the plugin is accessed through the Plugins menu item in the left-hand pane of the Ardor Client:

• Click on Hello World to open the example plugin, which displays the status of the Ardor blockchain.