SPV Channels CE
Readme version 1.1.1.
Contents | Version |
---|---|
SPV Channels Community Edition | 1.1.0 |
This repository contains SPV Channels CE, which is an implementation of the BRFC specification for SPV channels. In addition to a server side implementation, it also contains the JavaScript client libraries for interacting with the server. See Client libraries readme for more details about the client side libraries.
SPV Channels provides a mechanism via which counterparties can communicate in a secure manner even in circumstances where one of the parties is temporarily offline.
Swagger UI
The REST API can be reviewed in Swagger UI.
Deploying SPV Channels CE API Server as docker containers on Linux
Pre Requirements:
A SSL server certificate is required for installation. Obtain the certificate from your IT support team. There are are also services that issue free SSL certificates such as letsencrypt.org
. The certificate must be issued for the host with a fully qualified domain name. To use the server side certificate, you need to export it (including the corresponding private key) in PFX file format (*.pfx).
API Clients must trust the Certification Authority (CA) that issued the server side SSL certificate.
Initial setup
The distribution is shared and run using Docker.
-
Open the terminal.
-
Create a directory where the spvchannels docker images, config and database will be stored (e.g. spvchannels) and navigate to it:
mkdir spvchannels cd spvchannels
-
Download the distribution of SPV Channels Server into the directory created in the previous step and extract the contents.
-
Check that the following files are present:
docker-compose.yml
.env
-
Create a
config
folder and copy the SSL server certificate file (<certificate_file_name>.pfx) into it. This server certificate is required to setup TLS (SSL). -
Before running the SPV Channels API Server containers (spvchannels-db and spvchannels), replace some values in the
.env
file.
Parameter | Description |
---|---|
CERTIFICATEFILENAME | File name of the SSL server certificate (e.g. <certificate_file_name.pfx>) copied in step 5. |
CERTIFICATESPASSWORD | Password of the *.pfx file copied in step 5. |
Note: The remaining setting are explaned in the section Settings.
Running application
-
After the
.env
is set up, launch the spvchannels-db and spvchannels containers using the command:docker-compose up –d
The docker images as specified by the docker-compose.yml
file, are automatically pulled from Docker Hub.
-
Verify that all the SPV Channels Server containers are running using:
docker ps
The list should include
bitcoinsv/spvchannels-db
andbitcoinsv/spvchannels
. -
If everything is running you can continue to section Account manager to create an account.
Note: If you were provided with an account id and its credentials then you can skip Setting up an account and proceed to REST interface
Setting up an account
To be able to call SPV Channels Server API, an account must be added into the database using the following command:
docker exec spvchannels ./SPVChannels.API.Rest -createaccount [accountname] [username] [password]
Parameter description:
Parameter | Description |
---|---|
[accountname] | name of the account, any whitespaces in accountname must be replaced with '_' |
[username] | username of the account |
[password] | password of the username |
Note: This command can also be used to add new users to an existing account (e.g. running
docker exec spvchannels ./SPVChannels.API.Rest -createaccount Accountname User1 OtherP@ssword
will return the account-id of Accountname).
Setting up mobile push notifications
To enable mobile push notifications from SPV Channels, a Firebase service account key is required. Copy the *.json file containing the Firebase service account key into the config folder and set FIREBASECREDENTIALSFILENAME in the .env
file.
To get a Firebase service account *.json file, log in to your Firebase console and from Project Setting -> Service account -> Click on generate new private key. This will generate a *.json file with your Firebase service account key.
REST interface
The reference implementation exposes different REST APIs:
- an API for managing channels
- an API for managing messages
This interfaces can be accessed on https://<servername>:<port>/api/v1
. A Swagger page with the interface description can be accessed at https://<servername>:<port>/swagger/index.html
Note:
<servername>
should be replaced with the name of the server where docker is running.<port>
is set to 5010 by default in the.env
file.
Settings
Parameter | Data type (allowed value) | Description |
---|---|---|
NPGSQLLOGMANAGER | <bool> (`True |
False`) |
HTTPSPORT | <number> |
Port number on which SPV Channels API is running. By default it's set to 5010 . |
CERTIFICATEFILENAME | <text> |
File name of the SSL server certificate (e.g. <certificate_file_name.pfx>) |
CERTIFICATESPASSWORD | <text> |
Password of the *.pfx file |
NOTIFICATIONTEXTNEWMESSAGE | <text> |
Notification text upon arrival of a new message. By default it's set to New message arrived . |
MAXMESSAGECONTENTLENGTH | <number> |
Maximum size of any single message in bytes. By default it's set to its maximum size 65536 . |
CHUNKEDBUFFERSIZE | <number> |
If a message is sent in chunks, this sets the size of a chunk. By default it's set to 1024 . |
TOKENSIZE | <number> |
Length of bearer token. By default it's set to 64 . |
CACHESIZE | <number> |
Number of records in memorycache. By default it's set to 1048576 . |
CACHESLIDINGEXPIRATIONTIME | <number> |
Time in which a record is removed from memorycache if it is not accessed. By default it's set to 60 seconds. |
CACHEABSOLUTEEXPIRATIONTIME | <number> |
Time in which a record is removed from memorycache. By default it's set to 600 secunds. |
FIREBASECREDENTIALSFILENAME | <text> |
Fully qualified file name of the Firebase service account key. This setting is only required if you wish to enable mobile push notifications. See Setting up mobile push notifications |
Terminating application
-
Open the terminal and navigate to spvchannels folder:
cd spvchannels
-
To shutdown SPV Channels Server containers use the following command:
docker-compose down