How to enable the "Report Misbehavior" plugin

The Report Misbehavior plugin provides automatic detection of a validator’s misbehavior and sends the reportMisbehavior transaction to the running node. This transaction contains two block headers that are necessary to prove that the validator who generated the blocks has violated the Klayr-BFT consensus protocol and is deemed to be punished[1] once proven guilty.

On this page, you’ll learn:

  • Registration of the Report Misbehavior plugin to a blockchain client.

  • Authorizing an account to report misbehavior on the network.

Using this guide, the Report Misbehavior plugin can be registered to a Klayr Core node or any Klayr-based blockchain client.

1. Plugin registration

With the latest version of Klayr Core v4 and Klayr SDK v6, the default plugins come pre-installed after a client is installed or initiated, respectively.

You can check the package.json file of the blockchain client to ensure the installation.

hello_client/package.json
"dependencies": {
  //[...]
	"@klayr/framework-report-misbehavior-plugin": "0.3.0",
	//[...]
},

Otherwise, you can install the Report Misbehavior plugin like this:

npm install --save @klayr/framework-report-misbehavior-plugin

There are various ways to enable the Report Misbehavior plugin. You can opt for any of the below-mentioned to register the plugin to the blockchain client.

It is essential to enable WS API and configure the allowedMethods property before registering the ReportMisbehaviorPlugin. For more information, see the configurations described in the configuration guide.

1.1. Registering via source

For blockchain clients that were initialized with Klayr Commander, it is possible to register the plugin through the plugins.ts file. Open the plugins.ts file, import the Report Misbehavior plugin, and register it with the application as shown below:

src/app/plugins.ts
/* eslint-disable @typescript-eslint/no-empty-function */
import { ReportMisbehaviorPlugin } from '@klayr/framework-report-misbehavior-plugin';
import { Application } from 'klayr-sdk';

export const registerPlugins = (app: Application): void => {
    app.registerPlugin(new ReportMisbehaviorPlugin());
};

Save and close the plugins.ts file.

After updating the plugins.ts file, build the blockchain client again:

npm run build

1.2. Enabling via environment variable

Add the environment variable KLAYR_ENABLE_REPORT_MISBEHAVIOR_PLUGIN to the PM2 configuration for the blockchain client:

  • Mainchain node

  • Sidechain node

pm2.conf.json
{
  "name": "klayr-core",
  "script": "klayr-core start --overwrite-config",
  "env": {
    "KLAYR_NETWORK": "testnet",
    "KLAYR_CONFIG_FILE": "/home/klayr/klayr-core/custom-config.json",
    "KLAYR_ENABLE_REPORT_MISBEHAVIOR_PLUGIN": true
  }
}
pm2.conf.json
{
  "name": "hello_client",
  "script": "/bin/run start --config=config/custom_config.json",
  "env": {
    "KLAYR_ENABLE_REPORT_MISBEHAVIOR_PLUGIN": true
  }
}

2. Starting the node

Depending on how you chose to register the plugin, start the blockchain client, accordingly.

  • Registered via built-in flag

  • Registered via Source

  • Registered via PM2

It is also possible to enable the Report Misbehavior plugin without updating the configuration, the plugins.ts file, or using PM2. This can be done simply by adding the --enable-report-misbehavior-plugin flag to the start command.

Mainchain

  • Start the blockchain client with designated flags on a mainchain node.

    klayr-core start --network testnet --enable-report-misbehavior-plugin
Sidechain

  • Or, start the blockchain client with designated flags on a sidechain node.

    ./bin/run start --config=config/custom_config.json --enable-report-misbehavior-plugin
Start the blockchain client with custom_config.json
./bin/run start --config=config/custom_config.json

After configuring the pm2.conf.json file, you can start the client like this:

Start blockchain client using the process manager PM2
pm2 start pm2.conf.json

3. Authorizing an account

3.1. Choose the sender account

The plugin uses a specified sender account to sign the reportMisbehavior transactions. To automatically sign the transaction, the encrypted private key of the account must be added to the plugin configuration.

Please note that the respective account should have a high enough account balance to be able to send a misbehavior report transaction.

Encrypt the private key of the sender account before adding it to the configuration:

  1. Pass an account’s privateKey to the message:encrypt command:

    • Mainchain node

    • Sidechain Node

    klayr-core message:encrypt "d0b159fe5a7cc3d5f4b39a97621b514bc55b0a0f1aca8adeed2dd1899d93f103a3f96c50d0446220ef2f98240898515cbba8155730679ca35326d98dcfb680f0" -stringify
    ./bin/run message:encrypt "d0b159fe5a7cc3d5f4b39a97621b514bc55b0a0f1aca8adeed2dd1899d93f103a3f96c50d0446220ef2f98240898515cbba8155730679ca35326d98dcfb680f0" -stringify

  2. Enter a password that will be used later for authorization.

    ? Please enter password:  [hidden]
? Please re-enter password:  [hidden]

  3. The node will output the corresponding encryptedPrivateKey.

    kdf=argon2id&cipher=aes-128-gcm&version=1&ciphertext=635c7a18537a0234469f4a256b5766a28a8717450912c176ec0130ce747a4fd94d9c5c0a4bbf42c96c28fad951dae1fc319a5752112f3deecceac7c5a1fcf51be5de6be279836cc55868c9947f36e708024f5f15f6272a595aaee75600c6004f1ba5e5d14868efcb32dd14a868224268a25da6bcf1c8f21b35177279295d67b3&mac=7c5a99f7ef438c534738a9a1b214cb009441b560eaf207cd3c8ca2e30f03e438&salt=1047c5944ada6fec&iv=1c0c1a463a1b027853028ccc0c344dee&tag=0acc6a9a2b61526ba4375e4905913ca6&iterations=1&parallelism=4&memorySize=2097023

3.2. Plugin configuration

Add the encrypted private key retrieved above under plugins.reportMisbehavior.encryptedPrivateKey to the node configuration:

  • Mainchain node

  • Sidechain Node

klayr-core/config/testnet/config.json
"plugins": {
    "reportMisbehavior": {
        "encryptedPrivateKey": "kdf=argon2id&cipher=aes-128-gcm&version=1&ciphertext=635c7a18537a0234469f4a256b5766a28a8717450912c176ec0130ce747a4fd94d9c5c0a4bbf42c96c28fad951dae1fc319a5752112f3deecceac7c5a1fcf51be5de6be279836cc55868c9947f36e708024f5f15f6272a595aaee75600c6004f1ba5e5d14868efcb32dd14a868224268a25da6bcf1c8f21b35177279295d67b3&mac=7c5a99f7ef438c534738a9a1b214cb009441b560eaf207cd3c8ca2e30f03e438&salt=1047c5944ada6fec&iv=1c0c1a463a1b027853028ccc0c344dee&tag=0acc6a9a2b61526ba4375e4905913ca6&iterations=1&parallelism=4&memorySize=2097023"
    },
}
hello_client/config/custom-config.json
"plugins": {
    "reportMisbehavior": {
        "encryptedPrivateKey": "kdf=argon2id&cipher=aes-128-gcm&version=1&ciphertext=635c7a18537a0234469f4a256b5766a28a8717450912c176ec0130ce747a4fd94d9c5c0a4bbf42c96c28fad951dae1fc319a5752112f3deecceac7c5a1fcf51be5de6be279836cc55868c9947f36e708024f5f15f6272a595aaee75600c6004f1ba5e5d14868efcb32dd14a868224268a25da6bcf1c8f21b35177279295d67b3&mac=7c5a99f7ef438c534738a9a1b214cb009441b560eaf207cd3c8ca2e30f03e438&salt=1047c5944ada6fec&iv=1c0c1a463a1b027853028ccc0c344dee&tag=0acc6a9a2b61526ba4375e4905913ca6&iterations=1&parallelism=4&memorySize=2097023"
    },
}
See more available configurations in the Config options of the plugin reference.

3.3. Authorization

The Report Misbehavior plugin provides a dedicated endpoint to authorize an account to act as a reporter of misbehavior on the network.

To authorize an account, you can invoke the reportMisbehavior_authorize endpoint. Make sure to use the password created at choosing sender account stage.

  • Mainchain node

  • Sidechain Node

klayr-core endpoint:invoke reportMisbehavior_authorize '{"password": "CorrectPassword", "enable":true}' --pretty
./bin/run endpoint:invoke reportMisbehavior_authorize '{"password": "CorrectPassword", "enable":true}' --pretty
Response
{
  "result": "Successfully enabled the reporting of misbehavior."
}

That’s it! The Report Misbehavior plugin is now successfully enabled on the node and an account has been authorized to report misbehavior on the network.

1. The LIP: Punish BFT violations provides the details regarding the implications of Report Misbehavior transaction.