- 1 Introduction
- 2 Acquire and Enable a Plugin
- 3 Using a Plugin
The Bitswift blockchain allows third-party software developers to add features to the Bitswift Client Interface.
This guide describes how to install and use a plugin. Plugins have unrestricted access to the local Bitswift 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.
Acquire and Enable a Plugin
Plugins are authored by third party developers. Some are free while others can be purchased. A good place to discover plugins and ask questions about them is the Nxt Plugins subforum.
- 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 NXt / Ardor / Bitswift community.
When the Bitswift 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.
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
Download the plugin zip file:
Validate the Downloaded Plugin File
Validating a plugin ensures that the downloaded zip file has not been modified since being zipped.
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.
Validate the Checksum
The checksum can be validated using the Bitswift Client as follows. First open the Bitswift Generate Token pop-up entry form by clicking on the gear graphic in the upper right corner, then clicking on Generate Token:
Next, click on the 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 NXT-6GMG-FC5F-YSX6-8CVEL, owned by mystcoin (the author of this guide).
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:
$ 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 mystcoin zipped.
Extract the Downloaded Plugin File
Now that the downloaded zip file has been validated, it can be extracted into the /Ardor/html/www/plugins/hello_world 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/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 Bitswift Client if you are logged in. The Bitswift Client will load all active plugins when you next log in, if plugins are enabled.
Using a Plugin
By default, plugins are disabled on the Bitswift client interface. You can ENABLE plugins by navigating to the settings option (gear icon - top right) in the Bitswift client interface and choosing the Account Settings option.
- 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 Bitswift client during login. Because plugins are potentially dangerous, the Bitswift Client login screen has several plugin security features explained below. These features will not appear when there are no active plugins.
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 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 Bitswift token 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 Bitswift 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 1.5.6e is major version 1.5.
- 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 Bitswift 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 Bitswift 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 Bitswift child chain client:
- Click on Hello World to open the example plugin, which displays the status of the Bitswift blockchain.