search

GENERALBYTESCOM / batm_public

BATM Public Repository
www.generalbytes.com
Other
98 stars 241 forks source link

readme

BATM Public Repository - Open Extensions

This repository contains Bitcoin ATM related code used in BATMTwo, BATMThree, BATM Server (CAS) products.

More information about the products can be found here: https://www.generalbytes.com

All source code is released under GPL2.

Architecture

Architecture

Overview

Operators frequently request new features to be added to our BATM Server (CAS). Typically, the requests are for adding support for "cryptocurrency XYZ" or "digital asset exchange XY".

The purpose of this project is to give operators the desired power to add features themselves by extending CAS via this published Extensions mechanism.

Our software is written in Java and any Java developer may be recruited to create/implement these extensions. No unusual qualifications are required.

When the CAS services are started, they scan the /batm/app/master/extensions/ folder for all files that have the ".jar" extension. CAS then parses any "batm-extensions.xml" found in the JAR file to enumerate the extensions present within the JAR package.

Extension is a high level component - something like a plugin - that encapsulates and instantiates the rest of the features.

Extension can be asked to provide wallet X for currency Y etc. The best way to learn more about extensions is to read the sample code and examine how other people have implemented support for their wallet or cryptocurrency in the server_extensions_extra module. Additional examples can be found here.

Here is the list of some functionality that can be extended using Extensions API:

Content

Note for developers

Requirements:

When you implement support for a new crypto-coin, please add it to server_extensions_extra - so that it may get into the default CAS distribution ready to be used by other operators. Please use the appropriate Fork and Pull Request in the GitHub workflow when adding new functions, and bear in mind that your code will be reviewed prior to any merge with the master.

When adding new cryptocurrency support, please remember to provide its logo! This logo will later be downloaded by the BATM from CAS and displayed on the BATM screen. Both SVG and PNG logos are supported; however, only the SVG logo is used on newer BATM versions. A PNG logo is offered only for backward compatibility, and in the few cases where the SVG logo has an unusually large size. SVG logos must comply with following rules:

  1. SVG logos should not contain filters or bitmap images
  2. All SVG and PNG logos should be 120 x 120px. See other logos for examples.
  3. Preserve the unified BATM design: every SVG logo must contain the background from template.svg. An example background can be found here.

After you implement the extension make sure you test it with "Tester" (which you will find in server_extensions_test). If you want to implement an extension that you don't want to share with the rest of the world, then create a separate module (e.g. server_extensions_mycompany) and use a different jar name (server_extensions_mycompany.jar).

Build information

./gradlew build
cp server_extensions_extra/build/libs/batm_server_extensions_extra.jar /batm/app/master/extensions/

Note that on startup, CAS scans the: /batm/app/master/extensions/ folder for all files that have the .jar extension.

If you happen to add new cryptocurrency in CryptoCurrency class in currencies module then don't forget to make sure that you copy your version of currencies-1.0.XX-SNAPSHOT.jar to /batm/app/master/lib

Creating your own extension

When you want to develop your own operator specific extension please create a new module and implement your extension there. Use server_extensions_template module as a template for your first extension. Just copy this module and rename it. You will need to modify also settings.gradle file to contain your new extension module's name. See how is the server_extensions_template module mentioned and add line for your new extension module. After building the whole project your built extension shoud be in following file: yournewextension/build/libs/yournewextension.jar Copy it to CAS server at following location: /batm/app/master/extensions/ You may also want to modify build.gradle in your new module to change at least package names and final output filename.

How to run Tester

./gradlew :server_extensions_test:install
./server_extensions_test/build/install/server_extensions_test/bin/server_extensions_test

verification-site

It is standalone component that serves static verification website and little server that communicates with CAS. Its build around Onfido web SDK. If you need make any modifications to appearance or verification behavior please refer to this documentation first.

It can be build with:

./gradlew clean build

this produces verification-site-<version>.jar into build/libs directory, and you can run it simply with:

java -jar verification_site-<ver>.jar

By default, verification-site runs on port 8443. You should change it and most importantly configure HTTPS. Here is how to do it with letsencrypt:

  1. download letsenrypt certbot

    git clone https://github.com/certbot/certbot

  2. generate certificate for your domain with letsenrypt

    ./certbot-auto certonly -a standalone -d example.com -d www.example.com

  3. convert it to PKCS12 format for Spring Boot

    cd /etc/letsencrypt/live/example.com
openssl pkcs12 -export -in fullchain.pem -inkey privkey.pem -out keystore.p12 -name tomcat -CAfile chain.pem -caname root

  4. configure your application

    • edit application.properties before building application as follows: 
      server.port=443
security.require-ssl=true
server.ssl.key-store=/etc/letsencrypt/live/example.com/keystore.p12
server.ssl.key-store-password=<your-password>
server.ssl.keyStoreType=PKCS12
server.ssl.keyAlias=tomcat
    • or you can pass these parameters in run command as follows: 
      java -jar verification_site-<ver>.jar --server.port=443 --security.require-ssl=true --server.ssl.key-store=/etc/letsencrypt/live/example.com/keystore.p12 --server.ssl.key-store-password=<your-password> --server.ssl.keyStoreType=PKCS12 --server.ssl.keyAlias=tomcat

      How to enable extension hot reload feature

      You can turn on/off extension hot reaload feature to be able to replace extension classes without restarting CAS.

:warning: Use this feature with caution as it may allow anyone with access to the server to change extension code on the fly.

To enable hot reload feature you need to modify /batm/config/extensions configuration file and set:

hot-reload=true