diff --git a/docs/Concepts/Plugins.md b/docs/Concepts/Plugins.md new file mode 100644 index 00000000000..798118a89fc --- /dev/null +++ b/docs/Concepts/Plugins.md @@ -0,0 +1,48 @@ +description: Plugins + + +# Plugins + +You can extend Hyperledger Besu functionality by building Java plugins. Use the +Plugin API to take data from any Besu network, public or permissioned, and feed +it into an application or system. + +For example, create a plugin to add additional monitoring functionality or +stream event data to a third-party application. The API exposes data about the +following components: + +* Blocks +* Balances +* Transactions +* Smart contracts +* Execution results +* Logs +* Syncing state + +![Besu Plugin API](../images/Hyperledger-Besu-Plugin-API.png) + +The Plugin API provides access to [interfaces](../Reference/Plugin-API-Interfaces.md) that allow you to build +the plugin. + +!!! tip + View the [Plugin API webinar](https://youtu.be/78sa2WuA1rg) for an example of how to build a plugin. + + The [Plugin API Javadoc](https://javadoc.io/doc/org.hyperledger.besu/plugin-api/latest/index.html) provides additional information about the available interfaces. + +## Install Plugins + +The plugin (`.jar`) must be copied to the `plugins` directory to allow Besu +access and use the plugin. + +!!! important + If not already present, the `plugins` directory must be created one directory + level below (`../`) the `besu` executable. + +Each plugin in the directory has the following lifecycle events: + +* **Register** - Executed when Besu starts. Besu checks plugin compatibility and registers plugins. +* **Start** - Plugins are started after being successfully registered. +* **Stop** - Plugins are stopped by Besu. + +!!! note + Besu does not guarantee the order plugins are called during lifecycle events. diff --git a/docs/Reference/Plugin-API-Interfaces.md b/docs/Reference/Plugin-API-Interfaces.md new file mode 100644 index 00000000000..05e685cce26 --- /dev/null +++ b/docs/Reference/Plugin-API-Interfaces.md @@ -0,0 +1,38 @@ +description: Plugin interfaces + + +# Plugin API Interfaces + +API interfaces in Hyperledger Besu allow users to [build plugins](../Concepts/Plugins.md) to +extend Besu functionality. + +The [Plugin API Javadoc](https://javadoc.io/doc/org.hyperledger.besu/plugin-api/latest/index.html) provides additional information about the available interfaces. + +## Core Plugin Classes + +The following interfaces provide core plugin classes. + +| Interface | Description | +|--------------------|----------------------------------------------------------| +| [**BesuContext**](https://javadoc.io/doc/org.hyperledger.besu/plugin-api/latest/org/hyperledger/besu/plugin/BesuContext.html) | Allows plugins to access Besu services. | +| [**BesuPlugin**](https://javadoc.io/doc/org.hyperledger.besu/plugin-api/latest/org/hyperledger/besu/plugin/BesuPlugin.html) | Used to manage the plugin lifecycle. | + + +## Plugin Services + +The following interfaces provide services that can be retrieved. + +| Interface | Description | +|--------------------|----------------------------------------------------------| +| [**BesuEvents**](https://javadoc.io/doc/org.hyperledger.besu/plugin-api/latest/org/hyperledger/besu/plugin/services/BesuEvents.html) | Allows plugins to attach to various events during Besu operation. | +| [**BesuConfiguration**](https://javadoc.io/doc/org.hyperledger.besu/plugin-api/latest/org/hyperledger/besu/plugin/services/BesuConfiguration.html) | Provides file system locations of Besu's storage. | +| [**IbftQueryService**](https://javadoc.io/doc/org.hyperledger.besu/plugin-api/latest/org/hyperledger/besu/plugin/services/query/IbftQueryService.html) | Allows IBFT 2.0 aspects of the blockchain to be queried. | +| [**MetricCategoryRegistry**](https://javadoc.io/static/org.hyperledger.besu/plugin-api/1.3.4/org/hyperledger/besu/plugin/services/metrics/MetricCategoryRegistry.html) | Adds a new metrics category to the CLI. | +| [**MetricsSystem**](https://javadoc.io/doc/org.hyperledger.besu/plugin-api/latest/org/hyperledger/besu/plugin/services/MetricsSystem.html) | Register metrics with the Prometheus endpoint. | +| [**PoaQueryService**](https://javadoc.io/static/org.hyperledger.besu/plugin-api/1.3.4/org/hyperledger/besu/plugin/services/query/PoaQueryService.html) | Query the current state of Clique and IBFT 2.0 consensus protocols. | +| [**PicoCLIOptions**](https://javadoc.io/static/org.hyperledger.besu/plugin-api/1.3.4/org/hyperledger/besu/plugin/services/PicoCLIOptions.html) | Adds CLI commands to the Besu command line. | +| [**StorageService**](https://javadoc.io/static/org.hyperledger.besu/plugin-api/1.3.4/org/hyperledger/besu/plugin/services/StorageService.html) | Allows plugins to register as a storage engine. | + +To use the interfaces in your plugin, ensure the [Gradle build file](https://github.com/PegaSysEng/PluginsAPIDemo/blob/master/build.gradle) contains +the `https://hyperledger-org.bintray.com/besu-repo` repository and the +`plugin-api` dependency. \ No newline at end of file diff --git a/docs/Reference/Resources.md b/docs/Reference/Resources.md index 987b0037422..58b34d23d2c 100644 --- a/docs/Reference/Resources.md +++ b/docs/Reference/Resources.md @@ -17,6 +17,8 @@ description: Hyperledger Besu resources including blog posts, webinars, and meet ## Webinars +[Besu Plugin API: Learn How to Leverage Plugin APIs on Hyperledger Besu](https://youtu.be/78sa2WuA1rg) + [Permissioning in Blockchain: A Technical Look at Benefits and Best Practices](https://www.youtube.com/watch?v=CD0pHtNDqZs) [Privacy in Besu: How PegaSys Redefined Blockchain for Enterprises](https://www.youtube.com/watch?v=8l7SSZLyFL8) diff --git a/docs/images/Hyperledger-Besu-Plugin-API.png b/docs/images/Hyperledger-Besu-Plugin-API.png new file mode 100644 index 00000000000..b5c4e56ac98 Binary files /dev/null and b/docs/images/Hyperledger-Besu-Plugin-API.png differ diff --git a/mkdocs.yml b/mkdocs.yml index c20856dee72..9ba33c527b8 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -149,6 +149,7 @@ nav: - Overview: Concepts/Consensus-Protocols/Overview-Consensus.md - Comparing PoA Consensus Protocols: Concepts/Consensus-Protocols/Comparing-PoA.md - Client Libraries: Concepts/Client-Libraries.md + - Plugins: Concepts/Plugins.md - Privacy: - Overview: Concepts/Privacy/Privacy-Overview.md - Private Transactions: Concepts/Privacy/Private-Transactions.md @@ -179,6 +180,7 @@ nav: - Besu API Objects: Reference/API-Objects.md - Genesis File Items: Reference/Config-Items.md - web3.js-eaa Methods: Reference/web3js-eea-Methods.md + - Plugin API Interfaces: Reference/Plugin-API-Interfaces.md - Accounts for Testing: Reference/Accounts-for-Testing.md - Security Disclosure Policy: Reference/Responsible-Disclosure.md - Blog Posts and Webinars: Reference/Resources.md