BTCPay E̴x̴t̴e̴n̴s̴i̴o̴n̴s̴ Plugins

[Kukks]

With the introduction of plugins, we need to outline what will be extendable and how.

Creating a plugin

• Create a C# .NET core library project
• reference BTCPay.Abstractions (either by using git submodules or eventually through a nuget package),
• Create a class inheriting BaseBTCPayServerPlugin
• Create a file under Views named _ViewImports.cshtml with @addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers as its contents.
  Edit the project's csproj file and include the following:

  <PropertyGroup>
    <TargetFramework>netcoreapp3.1</TargetFramework>
    <AddRazorSupportForMvc>true</AddRazorSupportForMvc>
    <PreserveCompilationContext>false</PreserveCompilationContext>
    <GenerateEmbeddedFilesManifest>true</GenerateEmbeddedFilesManifest>
    <AssemblyVersion>1.0.0</AssemblyVersion>

  </PropertyGroup>
  <ItemGroup>
     <EmbeddedResource Include="Resources\**" />
   </ItemGroup>

• Use BTCPayServer.PluginPacker on your project's output to pack the plugin and create the info file
• Open a pull request to https://github.com/btcpayserver/btcpayserver-plugins with the two files .btcpay .btcpay.json. Be sure to include a link to the source code so that we can verify that there is no malicious code. We should probably find a good automated way to verify plugins vs src

What can you build?

Backend Services

• Inn your BaseBTCPayServerPlugin implementation, in the Execute(IServiceCollection services) override method

        public override void Execute(IServiceCollection services)
        {
            ...
        }

you are able to initiate and register any services you want. This could be new a new feature, extension points, etc.

UI Extension Points

The most obvious plugin is being able to inject additional UI into the current Ui in specific places. Wherever you see <vc:ui-extension-point location="xxx" /> in the BTCPay Server codebase indicates a UI extension point with the location named xxx. You can inject an unlimited number of Razor partial views by:

• Create a partial view in your plugin project under Views/Shared
• Define your ui extension point In your BaseBTCPayServerPlugin implementation, in the Execute(IServiceCollection services) override method

        public override void Execute(IServiceCollection services)
        {
            services.AddSingleton<IUIExtension>(new UIExtension("MyOwnUIExtension", "x"));
        }

where MyOwnUIExtension is the name of the partial you created (minus the cshtml file extension) and x is the location.

The current (this may not be updated, check the latest src code) available locations are:

• user-nav
• server-nav
• header-nav
• store-nav
• wallet-nav

Interestingly enough, in your UI extension partial, you can define your own locations!
For example, you could do the following:

<select>
<option>item1</option>
<vc:ui-extension-point location="dropdown-items" />
</select>

This means that other plugins can extend your own plugins!

System plugins

System plugins are plugins which are directly referenced andbuilt with BTCPay. They cannot be removed.

Developing your plugin

Load the BTCPay Dev env, import your plugin project to the btcpay solution and reference the plugin project in BTCPay. It will be loaded as if it were a system plugin.

Next steps

Dependencies

We need a way for plugins to depend on a specific version of BTCPay. BaseBTCPayServerPlugin contains a string[] Dependencies which will hold the formatpackage:{semver}. Semver will be used to determine version compatibility
BTCPay will present itself to the plugin system as if it were a system plugin itself under the name BTCPayServer
BTCPayServer:^1.0.5.8 indicates that it requires BTCPay to be at least 1.0.5.8 but less than 2.x. (see https://semver.npmjs.com/ to learn the full syntax) ---- #2020 enables this

Docker Dependencies

Some extensions may require additional external services to be running. We currently manage external services through btcpayserver-docker, a docker-compose generator on steroids in that it has a plugin architecture to expand what is run.

Let's come up with an example:
Imagine a new plugin has been created: BTCPay Wasabi Bridge - a plugin that lets you connect to a wasabi daemon to synchronize a store's wallet to a wasabi wallet in that it will share labels between the 2 labelling systems, allow you to participate in a ZeroLink Chaumian coinjoin directly from the BTCPay UI. This plugin requires that you run a Wasabi daemon, in which we have create a plugin(fragment) for the docker deployment to be able to do so.

• If a user installs the BTCPay Server Wasabi plugin, we need to make the docker deployment to include the wasabi docker plugin/fragment
• If a user installs the Wasabi docker plugin/fragment, BTCPay needs to install the BTCPay Server Wasabi plugin.

To achieve the first scenario, we can utilize the SSH service we have available inside BTCPay, add the fragments needed, and run the setup.

To achieve the second scenario, we will need to add some sort of config option to BTCPay, BTCPAY_REQUIRED_PLUGINS which would say which plugins are required to start with. the fragment would add it to the btcpay container docker compose section.

Data

Currently, ISettingsRepository allows you to set/read generic data to the db. This may be enough for small plugins that only need to save a small configuration but for those that need to keep a complicated state, with complex relations, we will need a more sophisticated approach. We should allow plugins to create their own DbContext with their own migrations, but sitll using the same database as BTCPay, provided that they have the plugin identifier prefixed to all their tables.

if there is data being persisted by plugins, exclusively for plugins, we need a way to also clean up this data. I propose that BaseBTCPayServerPlugin also has Task Uninstall( ) signature which can be implemented to clean up before it is uninstalled.

Crazy shit

Looking at the current BTCPay codebase, there are many, many parts that make sense to move to a separate plugin. This, however, comes with many challenges. Moving Payment Requests, Pull Payments, Apps to a plugin requires a huge undertaking. We must consider that these are features that have been released, use many services which are not decoupled properly and may or may not have other features utilziing them AND have dedicated tables, columns and properties in Blobs to them.
A high-level plan consists of

• Decouple feature from the system so that it can live as a separate project (system plugin). This does not include the data: we will use the current DbContext from these plugins.
• Create a new database storage service within the plugin. We will need to find a way to create a migration system on both solutions in that the data from the old format (bundled directly inside BTCpay.Data) is moved to the new (new db tabels prefixed with plugin identifier) and then the old deleted.

Moving an existing feature from a system plugin to an installable one

This will be tricky. While the abopve upgarde path ensures that the plugin can do the migration before the original data is deleted, removing a system plugin will require some forward thinking. Some logic must live inside BTCPay for each time we do this in that: If a migration is pending, automatically install plugin before this migration runs.

[dennisreimann]

Just an idea regarding the plugin creation: I think we should either have some scaffolding for this or better yet, offer a blueprint plugin with everything set up and some sample code, which plugin devs can fork. This would ease getting started and we could offer a coded solution with versioning instead of lengthy documentation for such a boilerplate. (also +1 for the BTCPay.Abstractions NuGet package instead of using submodules)

We also need a namespace for plugin routes and assets, so that different plugins do not interfere. I saw that the test plugin is using the extensions/test route, guess that's something you already thought about :)

[Kukks]

Just an idea regarding the plugin creation: I think we should either have some scaffolding for this or better yet, offer a blueprint plugin with everything set up and some sample code, which plugin devs can fork. This would ease getting started and we could offer a coded solution with versioning instead of lengthy documentation for such a boilerplate. (also +1 for the BTCPay.Abstractions NuGet package instead of using submodules)

We also need a namespace for plugin routes and assets, so that different plugins do not interfere. I saw that the test plugin is using the extensions/test route, guess that's something you already thought about :)

One reason to opt for a sunmodule is that you would also want the PluginPacker project available so that you can create the package.

I dont think we can do much in terms of routes, some plugins would be designed to inject and work inside existing features and endpoints. Obviously, plugins should try and be sensible and not try to use obvious paths. Namespacing, BTCpayServer.Plugins.XXX is ideal

[Eskyee]

excellent stuff .. this feels good @Kukks