- 1 Introduction
- 2 Acquire a Plugin
- 3 Install a Plugin
- 4 Use a Plugin
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.
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 [hhttps://ardorforum.org/ 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/wwww/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/wwww/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/wwww/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/wwww/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:
- 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:
- 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/wwww/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:
- 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/wwww/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/wwww/plugins/hello_world 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
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.
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.
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/wwww/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/wwww/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.
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.