diff --git a/electrum/CONTRIBUTING.md b/electrum/CONTRIBUTING.md index 5cd9a13f3..afbdab959 100644 --- a/electrum/CONTRIBUTING.md +++ b/electrum/CONTRIBUTING.md @@ -1,176 +1,176 @@ # Contributing to Electrum ABC ## Main repository The Electrum ABC source repository has been merged into the Bitcoin ABC repository, and the development is now taking place at [reviews.bitcoinabc.org](https://reviews.bitcoinabc.org/). Please read the main [CONTRIBUTING.md](https://github.com/Bitcoin-ABC/bitcoin-abc/blob/master/CONTRIBUTING.md) document to familiarize yourself with the development philosophy and find out how to set up the Bitcoin ABC repository. The original Electrum ABC github repository is maintained as a mirror of the `electrum/` directory in the main repository. The rest of this document provides instructions that are specific to Electrum ABC. ## Contacting developers [Join the Electrum ABC telegram group](https://t.me/ElectrumABC) to get in contact with developers or to get help from the community. ## Installing dependencies All commands in this document assume that your current working directory is the `electrum/` directory that resides at the root of the Bitcoin ABC repository. ### Python Python 3.7 or above is required to run Electrum ABC. If your system lacks Python 3.7+, you can use `pyenv` to install newer versions, or install an [alternative python distribution](https://www.python.org/download/alternatives/) in addition to your system's version. ### Python packages The simplest way to install all needed packages is to run the following command: ``` pip install .[all] ``` This will install Electrum ABC and all its dependencies as a python package and application. This is equivalent to: ``` pip install . pip install .[gui] pip install .[hardware] ``` If you do not want to install Electrum ABC as a package, you can install only the dependencies using the following commands: ``` pip3 install -r contrib/requirements/requirements.txt pip3 install -r contrib/requirements/requirements-binaries.txt pip3 install -r contrib/requirements/requirements-hw.txt ``` ## Running Electrum ABC from source If you installed the application as a python package, you can run it from anywhere using `electrum-abc` (assuming that your system has the python script directory in its PATH). If you installed all dependencies, you can also start the application by invoking the `./electrum-abc` script. See the following sections for additional instructions and optional dependencies. ### Running from source on old Linux If your Linux distribution has a version of python 3 lower than the minimum required version, it is recommended to do a user dir install with [pyenv](https://github.com/pyenv/pyenv-installer). This allows Electrum ABC to run completely independently of your system configuration. 1. Install `pyenv` in your user account. Follow the printed instructions about updating your environment variables and `.bashrc`, and restart your shell to ensure that they are loaded. 2. Run `pyenv install 3.9.7`. This will download and compile that version of python, storing it under `.pyenv` in your home directory. 3. `cd` into the Electrum ABC directory. Run `pyenv local 3.9.7` which inserts a file `.python-version` into the current directory. 4. [Install Electrum ABC requirements](#python-packages) 5. [Compile libsecp256k1](#compiling-libsecp256k1) ### Running from source on macOS You need to install **either** [MacPorts](https://www.macports.org) **or** [HomeBrew](https://www.brew.sh). Follow the instructions on either site for installing (Xcode from [Apple's developer site](https://developer.apple.com) is required for either). 1. After installing either HomeBrew or MacPorts, clone this repository and switch to the directory: `git clone https://github.com/Bitcoin-ABC/ElectrumABC && cd ElectrumABC` 2. Install python 3.7+. For brew: `brew install python3` or if using MacPorts: `sudo port install python37` 3. Install PyQt5: `python3 -m pip install --user pyqt5` 4. [Install Electrum ABC requirements](#python-packages) 5. [Compile libsecp256k1](#compiling-libsecp256k1) ## Running tests Running unit tests: ``` python3 test_runner.py ``` This can also be run as a `ninja` target in the context of a Bitcoin ABC build: ``` ninja check-electrum ``` Functional tests can be run with the following command: ``` pytest electrumabc/tests/regtest ``` This requires `docker` and additional python dependencies: ``` pip3 install -r contrib/requirements/requirements-regtest.txt ``` ## Compiling libsecp256k1 Compiling libsecp256k1 is highly-recommended when running from source, to use fast cryptographic algorithms instead of using fallback pure-python algos. It is required when using CashFusion, as slow participants can cause a fusion round to fail. On Debian or Ubuntu linux: ``` sudo apt-get install libtool automake ./contrib/make_secp ``` On MacOS: ``` brew install coreutils automake ./contrib/make_secp ``` or if using MacPorts: `sudo port install coreutils automake` ## Compiling the icons file for Qt If you change or add any icons to the `icons` subdirectory, you need to run the following script before you can use them in the application: ``` contrib/gen_icons.sh ``` This requires the `pyrcc5` command which can be installed using your package manager. For instance for Ubuntu or Debian, run: ``` sudo apt-get install pyqt5-dev-tools ``` ## Creating translations <!-- FIXME: we are still relying on Electron Cash translations--> ``` sudo apt-get install python-requests gettext ./contrib/make_locale ``` ## Plugin development -For plugin development, see the [plugin documentation](electrumabc_plugins/README.rst). +For plugin development, see the [plugin documentation](electrumabc_plugins/README.md). ## Creating Binaries See the *Building the release files* section in [contrib/release.md](contrib/release.md) diff --git a/electrum/electrumabc_plugins/README.rst b/electrum/electrumabc_plugins/README.md similarity index 70% rename from electrum/electrumabc_plugins/README.rst rename to electrum/electrumabc_plugins/README.md index 60c7ccb48..982e2c972 100644 --- a/electrum/electrumabc_plugins/README.rst +++ b/electrum/electrumabc_plugins/README.md @@ -1,196 +1,186 @@ -Electrum ABC - Plugins -====================== +# Electrum ABC - Plugins The plugin system of Electrum ABC is designed to allow the development of new features without increasing the core code of Electrum ABC. Electrum ABC is written in pure python. if you want to add a feature that requires non-python libraries, then it must be submitted as a plugin. If the feature you want to add requires communication with a remote server (not an Electrum ABC server), then it should be a plugin as well. If the feature you want to add introduces new dependencies in the code, then it should probably be a plugin. There are two types of plugins supported by Electrum ABC. The first is the internal plugin, currently offered under "Optional Features" in the Tools menu of the QT client. The second is the external plugin, which the user has to manually install, currently managed under "Installed Plugins" in the Tools menu of the QT client. At this time, there is no documentation for the plugin API. What API there is, mostly consists of some limited hooks which provide notification on events and a base class which provides the basic plugin integration. **WARNING:** The plugin API will be upgraded at some point. Plugins will be required to specify their release plugin API version, and those that predate it will be assumed to be version 0. This will be used to first deprecate, and then over time, remove the existing API as plugin developers transition to any replacement API. Plenty of time and warning will be given before any removal, allowing plugin developers to upgrade. Given the extremely limited state of the Electrum plugin API we inherited, this may even reduce maintenance requirements as internals a plugin developer makes use of can easily get changed in the course of normal development. -Risks and Dangers -================= +## Risks and Dangers Plugins, like Electrum ABC, are written in pure Python, in the form of -PythonPackages_. This means they can access almost all of Electron -Cash's state, and change any behaviour, perhaps even in dishonest ways +[PythonPackages](https://docs.python.org/3/tutorial/modules.html#packages). +This means they can access almost all of Electrum ABC's state, +and change any behaviour, perhaps even in dishonest ways you might not even notice at first. They might even use Python's file system access, or other similar functionality, to damage whatever else they can access. If you plan to install plugins, you should ensure that they are fully vetted by someone trustworthy, and do so at your own risk, only installing them from official locations. If you plan to develop a plugin, it is in your best interest to get it reviewed by someone a plugin user knows and trusts, before releasing it, in order to have provable safety for potential users as a feature. -.. _PythonPackages: https://docs.python.org/3/tutorial/modules.html#packages -Types of Plugin -=============== +## Types of Plugin Optional features (internal plugins) are included with Electrum ABC, and are available to all users of Electrum ABC to enable and disable as they wish. They cannot be uninstalled, and no installation functionality is provided either. -User installable plugins (external plugins) are not included with Electron -Cash. The user must use the Plugin Manager to install these, through the +User installable plugins (external plugins) are not included with Electrum +ABC. The user must use the Plugin Manager to install these, through the user interface. In the QT UI, this is accessed through the Tools menu. The process of installation includes both warnings and required user confirmations that they accept the risks installing them incurs. -Internal Plugin Rules -===================== +## Internal Plugin Rules - We expect plugin developers to maintain their plugin code. However, once a plugin is merged in Electrum ABC, we will have to maintain it too, because changes in the Electrum ABC code often require updates in the plugin code. Therefore, plugins have to be easy to maintain. If we believe that a plugin will create too much maintenance work in the future, it will be rejected. - Plugins should be compatible with Electrum ABC's conventions. If your plugin does not fit with Electrum ABC's architecture, or if we believe that it will create too much maintenance work, it will not be accepted. In particular, do not duplicate existing Electrum ABC code in your plugin. - We may decide to remove a plugin after it has been merged in Electrum ABC. For this reason, a plugin must be easily removable, - without putting at risk the user's bitcoins. If we feel that a + without putting at risk the user's funds. If we feel that a plugin cannot be removed without threatening users who rely on it, we will not merge it. -External Plugins -================ +## External Plugins At this time, external plugins must be developed in the same way as an internal plugin. It might be that this can be done by placing a symbolic link -to your plugin's Python package directory, in the ``plugins`` directory within the +to your plugin's Python package directory, in the `plugins` directory within the clone of the Electrum ABC source you are developing within. Please be sure that you test your plugin with the same recommended version of Python for the version of Electrum ABC you intend to specify in your plugin's minimum Electrum ABC version. Not doing so, will cause you pain and potential users to avoid your plugin. -Packaging The Hard Way ----------------------- +### Packaging The Hard Way Once your plugin is ready for use by other users, you can package it for them so they can take advantage of the easy methods of plugin installation available in the QT user interface (drag and drop onto the plugin manager, or click -``Add Plugin`` and select the plugin zip archive). +`Add Plugin` and select the plugin zip archive). An external plugin must be constructed in the form of a zip archive that is -acceptable to the Python ``zipimport`` module. Within this archive must be two +acceptable to the Python `zipimport` module. Within this archive must be two things: -- The ``manifest.json`` file which provides plugin metadata. +- The `manifest.json` file which provides plugin metadata. - The Python package directory that contains your plugin code. It is recommended that your Python package directory contain precompiled Python bytecode files. Python includes -the `compileall module <https://docs.python.org/3/library/compileall.html#command-line-use>` +the [compileall module](https://docs.python.org/3/library/compileall.html#command-line-use) within it's standard library which can do this from the command line. This -is because ``zipimport`` does not support writing these back into the zip archive +is because `zipimport` does not support writing these back into the zip archive which encapulates your packaged plugin. -The ``manifest.json`` file has required fields: +The `manifest.json` file has required fields: -- ``display_name``: This is the name of your plugin. -- ``version``: This is the version of your plugin. Only numeric versions of the - form ``<integer>.<integer>`` (e.g. ``1.0``) or ``<integer>.<integer>.<integer>`` - (e.g. ``1.0.1``) are supported. -- ``project_url``: This is the official URL of your project. -- ``description``: A longer form description of how your plugin upgrades +- `display_name`: This is the name of your plugin. +- `version`: This is the version of your plugin. Only numeric versions of the + form `<integer>.<integer>` (e.g. `1.0`) or `<integer>.<integer>.<integer>` + (e.g. `1.0.1`) are supported. +- `project_url`: This is the official URL of your project. +- `description`: A longer form description of how your plugin upgrades Electrum ABC. -- ``minimum_ec_version``: This is the earliest version of Electrum ABC - which your plugin is known to work with. This will not be ``3.2`` or lower - as the external plugin functionality only arrived after that version. -- ``package_name``: This is the name of the Python package directory at the +- `minimum_ec_version`: This is the earliest version of Electrum ABC + which your plugin is known to work with. +- `package_name`: This is the name of the Python package directory at the top level of the zip archive, which contains your plugin code. It is necessary to formally specify this, to spare Electrum ABC confusion in the case of advanced plugin packages which contain multiple Python packages, or even looking around to distinguish between the one Python package and other data directories. -- ``available_for``: This is a list of keywords which map to supported - Electrum ABC plugin interfaces. Valid values to include are ``qt`` and - ``cmdline``. +- `available_for`: This is a list of keywords which map to supported + Electrum ABC plugin interfaces. Valid values to include are `qt` and + `cmdline`. If you do not include these fields in your manifest file, then the user will see an error message when they try and install it. -Example ``manifest.json`` -^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: json - - { - "display_name": "Scheduled Payments", - "version": "1.0", - "project_url": "https://github.com/rt121212121/electron_cash_scheduled_payments_plugin", - "description": "This allows a user to specify recurring payments to a number of recipients.", - "minimum_ec_version": "3.2", - "package_name": "scheduled_payments", - "available_for": [ - "qt" - ] - } - -The Easy Way ------------- - -In the ``contrib`` directory of the Electrum ABC source tree, you can find a script -named ``package_plugin.py``. Execute this script with the command-line -``py -3 package_plugin.py``. You must have ``PyQT5`` installed, which you will have +#### Example `manifest.json` + +```json +{ + "display_name": "Scheduled Payments", + "version": "1.0", + "project_url": "https://github.com/rt121212121/electron_cash_scheduled_payments_plugin", + "description": "This allows a user to specify recurring payments to a number of recipients.", + "minimum_ec_version": "3.2", + "package_name": "scheduled_payments", + "available_for": [ + "qt" + ] +} +``` + +### The Easy Way + +In the `contrib` directory of the Electrum ABC source tree, you can find a script +named `package_plugin.py`. Execute this script with the command-line +`py -3 package_plugin.py`. You must have `PyQT5` installed, which you will have if you are developing against a clone of the GIT repository. A window will be displayed with fields for all the required manifest fields, and when they have valid values, will allow you to generate the package zip archive automatically. This will create a zip archive with sha256 checksum which any user can then drag into their Electrum ABC wallet's plugin manager, to almost immediately install and run (sure they have to check a barrage of warnings about the damage you could do to them). -Advanced Python Packaging -------------------------- +### Advanced Python Packaging With a bit of thought a user can bundle additional supporting Python packages, or even binary data like icons, into their plugin archive. It is not possible to import Python extension modules (.pyd, .dll, .so, etc) -from within a ``ziparchive`` "mounted zip archive". +from within a `ziparchive` "mounted zip archive". If you need to extract data from the archive, to make use of it, please contact the Electrum ABC developers to work out a standard way to do so, so that if a user uninstalls your plugin, the extracted data can also be removed. For this initial external plugin feature release, this level of functionality is not officially supported or recommended.