Skip to content
You are reading GoQuorum development version documentation and some displayed features may not be available in the stable release. You can switch to stable version using the version box at screen bottom.

Updated on April 29, 2021

GoQuorum Plugins

The GoQuorum client is a modified geth client.

One of the unique enhancement is the pluggable architecture which allows adding additional features as plugins to the core geth, providing extensibility, flexibility, and isolation of GoQuorum features.

Benefits

This enhancement provides a number of benefits, including:

  1. Allowing the implementation of certain components of the GoQuorum client to be changed at configuration time.
  2. Supporting our community to improve the GoQuorum client with their own innovative implementations of the supported pluggable components.
  3. Decoupling new GoQuorum-specific features from core geth thereby simplifying the process of pulling in changes from upstream geth.

How it works?

Each plugin exposes an implementation for a specific plugin interface (or see Pluggable Architecture -> Plugins for more details)

Plugins are executed as a separate process and communicate with the main GoQuorum client geth process over a gRPC interface.

The plugin implementation must adhere to certain gRPC services defined in a .proto file corresponding to the plugin interface. Plugins can be written in different languages as gRPC provides a mechanism to generate stub code from .proto files.

The network communication and RPC are handled automatically by the high-level plugin library.

Installing Plugins

Currently plugins must be manually installed into a directory (defaults to plugins directory inside geth data directory - default can be overridden by setting baseDir in plugins settings).

Using Plugins

Plugins settings file contains a JSON that describes what plugins to be used. Then start geth using the --plugins command line option:

geth <other parameters> \
     --plugins file:///<path>/<to>/plugins.json

Plugin Integrity Verification

Plugin Central Server can be used to download and verify plugin integrity using PGP. The architecture enables the same verification process locally via --plugins.localverify and --plugins.publickey options or remotely with custom plugin central - reference the Settings section for more information on how to support custom plugin central.

To disable the plugin verification process, use the --plugins.skipverify command line option.

Warning

Using --plugins.skipverify introduces security risks and isn’t recommended for production environments.

Important

Before GoQuorum 21.4.1, the default Plugin Central Server configuration used Bintray to distribute the official plugins. As Bintray will stop working on May 1st 2020, configure plugin central to use ConsenSys Cloudsmith repository to override the default:

{
    "central": {
        "baseURL": "https://provisional-plugins-repo.quorum.consensys.net",
        "publicKeyURI": ".pgp/Central.pgp.pk"
    },
    ...
}

Example: HelloWorld plugin

The plugin interface is implemented in Go and Java. In this example, HelloWorld plugin exposes a JSON RPC endpoint to return a greeting message in the configured language. This plugin can reload changes from its JSON configuration.

Build plugin distribution file

  1. Clone plugin repository

    git clone --recursive https://github.com/ConsenSys/quorum-plugin-hello-world.git
    cd quorum-plugin-hello-world
    
  2. Here we will use Go implementation of the plugin

    cd go
    make
    

quorum-plugin-hello-world-1.0.0.zip is now created in build directory. Noticed that there’s a file hello-world-plugin-config.json which is the JSON configuration file for the plugin.

Start GoQuorum with plugin support

  1. Build Quorum

    git clone https://github.com/ConsenSys/quorum.git
    cd quorum
    make geth
    
  2. Copy HelloWorld plugin distribution file and its JSON configuration hello-world-plugin-config.json to build/bin

  3. Create geth-plugin-settings.json

    cat > build/bin/geth-plugin-settings.json <<EOF
    {
     "baseDir": "./build/bin",
     "providers": {
       "helloworld": {
         "name":"quorum-plugin-hello-world",
         "version":"1.0.0",
         "config": "file://./build/bin/hello-world-plugin-config.json"
       }
     }
    }
    EOF
    
  4. Run geth with plugin

    PRIVATE_CONFIG=ignore \
    geth \
        --nodiscover \
        --verbosity 5 \
        --networkid 10 \
        --raft \
        --raftjoinexisting 1 \
        --datadir ./build/_workspace/test \
        --rpc \
        --rpcapi eth,debug,admin,net,web3,plugin@helloworld \
        --plugins file://./build/bin/geth-plugin-settings.json \
        --plugins.skipverify
    

    ps -ef | grep helloworld would reveal the HelloWorld plugin process

Test the plugin

  1. Call the JSON RPC Run the following command in the shell console:

    curl -X POST http://localhost:8545 \
        -H "Content-type: application/json" \
        --data '{"jsonrpc":"2.0","method":"plugin@helloworld_greeting","params":["Quorum Plugin"],"id":1}'
    

    Result is:

    {"jsonrpc":"2.0","id":1,"result":"Hello Quorum Plugin!"}
    
  2. Update build/bin/hello-world-plugin-config.json plugin configuration to support es language

  3. Reload the plugin Run the following command in the shell console:

    curl -X POST http://localhost:8545 \
        -H "Content-type: application/json" \
        --data '{"jsonrpc":"2.0","method":"admin_reloadPlugin","params":["helloworld"],"id":1}'
    

    Result is:

    {"jsonrpc":"2.0","id":1,"result":true}
    
  4. Call the JSON RPC Run the following command in the shell console:

    curl -X POST http://localhost:8545 \
        -H "Content-type: application/json" \
        --data '{"jsonrpc":"2.0","method":"plugin@helloworld_greeting","params":["Quorum Plugin"],"id":1}'
    

    Result is:

    {"jsonrpc":"2.0","id":1,"result":"Hola Quorum Plugin!"}
    
ConsenSys has acquired Quorum from J.P. Morgan. Please read the FAQ.
Questions or feedback? You can discuss issues and obtain free support on GoQuorum Slack channel.
For paid professional support by ConsenSys, contact us at quorum@consensys.net