Extensions is a way to extend Specter Desktop in a way which does not need PRs in the core-project. They can be used to - create elaborated Frontends on top of Specter Desktop or even replace the whole Frontend - Add Additional Menu Items currently in Wallets and Settings - Create additional Devices with the functionality you would like to have
We currently rework the naming of extensions/plugins/services. If not otherwise stated, for now, they are used interchangeably
You can create an extension with an up to date Specter Desktop instance. Assuming that we're creating an extension called
rubberduck, it's as simple as this:
$ mkdir /tmp/rubberduck && cd /tmp/rubberduck $ virtualenv --python=python3 .env $ . ./.env/bin/activate $ pip3 install cryptoadvance.specter --upgrade $ python3 -m cryptoadvance.specter ext gen We need an id and a prefix for your extension. The id should be a short string. The prefix is usually your GitHub username or GitHub organisation name. Both will be used to to create a directory structure like this: ./src/mycorpname/specterext/myextension They will also be used when publishing this extension to pypi. Enter the id of your extension (lowercase only): rubberduck Enter the prefix: mynym Note: Isolated client mode means that the extensions won't share the session cookie with Specter Desktop and the integration only happens on the server side. Should the extension work in isolated client mode (y/n)?: n --> Created requirements.txt --> Created .gitignore --> Created src/mynym/specterext/rubberduck/service.py --> Created src/mynym/specterext/rubberduck/controller.py --> Created src/mynym/specterext/rubberduck/config.py --> Created src/mynym/specterext/rubberduck/__init__.py --> Created src/mynym/specterext/rubberduck/__main__.py --> Created src/mynym/specterext/rubberduck/templates/rubberduck/index.jinja --> Created src/mynym/specterext/rubberduck/static/rubberduck/css/styles.css --> Created src/mynym/specterext/rubberduck/static/rubberduck/img/ghost.png (via Github) --> Created src/mynym/specterext/rubberduck/static/rubberduck/img/logo.jpeg (via Github) --> Created src/mynym/specterext/rubberduck/templates/rubberduck/base.jinja --> Created src/mynym/specterext/rubberduck/templates/rubberduck/transactions.jinja --> Created src/mynym/specterext/rubberduck/templates/rubberduck/settings.jinja --> Created src/mynym/specterext/rubberduck/templates/rubberduck/components/rubberduck_menu.jinja --> Created src/mynym/specterext/rubberduck/templates/rubberduck/components/rubberduck_tab.jinja --> Created pytest.ini --> Created tests/conftest.py --> Created tests/fix_ghost_machine.py --> Created tests/fix_devices_and_wallets.py --> Created tests/fix_testnet.py --> Created tests/fix_keys_and_seeds.py --> Created pyproject.toml --> Created setup.py --> Created setup.cfg --> Created MANIFEST.in Congratulations, you've created a new extension! Here is how to get it to run in your development environment: pip3 install -e . python3 -m cryptoadvance.specter server --config DevelopmentConfig --debug # Point your browser to http://localhost:25441 # Click "Choose plugins" --> rubberduck If you want to package it, you can build it like this: python3 -m pip install --upgrade build python3 -m build # Install it like this: pip3 install dist/mynym_rubberduck-0.0.1-py3-none-any.whl If you want to bring your extension to production, please refer to the readme in the dummy-extension repo: https://github.com/cryptoadvance/specterext-dummy#how-to-get-this-to-production To publish your package python3 -m pip install --upgrade twine python3 -m twine upload --repository testpypi dist/* You can get all this information again via: python3 -m cryptoadvance.specter ext gen --help $
The created file structure looks like this and you will feel right at home if you have some knowledge about how Flask works:
Often enough, extension development goes hand in hand with the development of Specter Desktop iteself. Especially in the very beginning you need to constantly develop on the extension-concept on Specter Desktop while also using/consuming that functionality in an extension.
In such a case, the current best option is to "reuse" the virtualenv of Specter Desktop also for your extension. Other than what is described above, you would do something like the below. If you have checked out the Specter Desktop Code in parallel with the extension-code, you would ommit the creation of the virtualenv above and rather activate the existing one in your Specter Desktop Development Directory:
. ../specter-desktop/.env/bin/activate pip3 install -e . python3 -m cryptoadvance.specter server --config DevelopmentConfig --debug
Another, maybe even better option, would be to not reuse the Virtual Environment from specter-desktop to install the extension in editable mode, but to do it the other way around: Installing specter-desktop in editable mode in the virtualenv of the extension. However, that needs to be tested.
More information about the development of Specter Desktop can be found here.
As much as possible, each
extension should be entirely self-contained with little or no custom code altering core Specter functionality. There is a name for that: Extension framework.
extension will be used for all sorts of extensions whereas
plugin will be used as a component which can be de-/activated by a user.
All extensions are completely separated in a specific folder structure. There are internal extensions which SHOULD be located in
cryptoadvance.specterext.id_of_extension but at least 2 extensions are still at the deprecated location of
cryptoadvance.specter.services. However, that does not mean that an extension needs to be located in the same repository as Specter itself. Extensions can be located in their own repository even if they are incorporated into the official Specter release.
Independent of whether an extension is shipped with the official Specter-release binaries and whether it's an internal (which is shipped) or external extension (which might be shipped), the creation of extensions is already heavily supported and encouraged.
Whether an extension is shipped with the official binary is ultimately a choice of the Specter team. However, you can simply develop extensions and use them on production (only for technical personel) as described in
specterext-dummy (see below).
A description of how to create your own extension can be found above.
All the attributes of an extension are currently (json support is planned) defined as attributes of a class which is derived from the class
Service (should be renamed). That class has attributes which are essential. So let's discuss them briefly.
Here is an example. This class definition MUST be stored in a file called "service.py" within a package with the name
mynym.specterext.myextensionid. You don't have to create such files yourself. Please always use the extension generation procedure to create your extension.
class MyextensionidService(Service): id = "myextensionid" name = "A Nice name for my Extension" icon = "myextensionid/myextensionid_logo.png" logo = "myextensionid/myextensionid_logo.png" desc = "A nice description" has_blueprint = True blueprint_module = "mynym.specterext.myextensionid.controller" isolated_client = False devices = ["mynym.specterext.myextensionid.devices.mydevice"] devstatus = devstatus_alpha
This defines the base
Service class (to be renamed to "Extension") that all extensions must inherit from. This also enables
extension auto-discovery. Any feature that is common to most or all
Service integrations should be implemented here.
With inheriting from
Service you get some useful methods explained later.
id needs to be unique within a specific Specter instance where this extension is part of. The
name is the display name as shown to the user in the plugin-area (currently there is not yet a technical difference between extensions and plugins). The
icon will be used where labels are used to be diplayed if this extension is reserving addresses. The
logo and the
description is also used in the plugin area ("choose plugins").
If the extension has a UI (currently all of them have one),
has_blueprint is True.
The blueprint_module is referencing the controller module where endpoints are defined. It's recommended to follow the format
isolated_client should not be used yet. It is determining where in the url-path tree the blueprint will be mounted. This might have an impact on whether the extension's frontend client has access to the cookie used in Specter. Check
config.py for details.
devices, you can specify the modules where you're implementing new Devices.
devstatus is one of
devstatus_prod defined in
cryptoadvance.specter.services.service. Each Specter instance will have a config variable called
SERVICES_DEVSTATUS_THRESHOLD (prod in Production and alpha in Development) and depending on that, the plugin will be available to the user.
Address can be associated with an
Extension (e.g. addr X received a smash buy from
Service Foo) via the
Extension can also "reserve" an
Address for future use by setting
Address.service_id. The normal "Receive" UI will automatically skip any reserved
Address when generating a new receive address. The reserved addresses are interleaved with ready-to-use addresses so that we don't create any potentially confusing wallet gaps (e.g. addrs 4, 6, and 8 are reserved but addrs 3, 5, and 7 are available).
Users can also manually associate an existing
Address with a
Service (this is useful when the user has info that the particular
Service api can't provide for whatever reason).
Note: TODO: manually un-reserve an
Address from a