Swapi (acronym of Social Wallet API) makes it easy to deal with digital currencies backed, created and/or managed by groups in a reliable, simple and secure way.
It gives the possibilities to experiment with different economic models, without lot of the burden of implementing a reliable and scalable infrastructure.
It aims to be minimal and modular, to be used in different scenarios and with different results, as implement a mutual credit system, manage a crypto fund, design a basic income redistribution and way beyond…

In this tutorial we will install and configure swapi to work together with the current version of the bitcoin node (v.0.18), and we will ensure to have a fully operational setup, able to perform operation both on bitcoin mainnet and regtest mode, to have a local testing environment in which developers can almost instantly generate blocks on demand for testing events, and can create private satoshis with no real-world value.

This guide is tested on a GNU/Linux system, and it assumes a basic understanding of bitcoin blockchain fundamentals and how to work with a terminal.

Install and run bitcoin node v.0.18

(ps. you can find the official bitcoin installation guide here)

Prerequisites

• Git installed
• At least 2gb of RAM

Install dependencies

$ sudo apt-get install autoconf libboost-all-dev libssl-dev libprotobuf-dev protobuf-compiler libqt4-dev libqrencode-dev libtool -y

$ sudo apt-get install libdb5.1++-dev libevent-dev pkg-config -y 

Install Berkeley database

$ wget http://download.oracle.com/berkeley-db/db-4.8.30.NC.tar.gz
$ tar -xvf db-4.8.30.NC.tar.gz
$ cd db-4.8.30.NC/build_unix
$ mkdir -p build
$ BDB_PREFIX=$(pwd)/build
$ ../dist/configure --disable-shared --enable-cxx --with-pic --prefix=$BDB_PREFIX
$ make install
$ cd ../..

Compile bitcoin

$ git clone https://github.com/bitcoin/bitcoin.git
$ cd bitcoin
$ git checkout v0.18
$ ./autogen.sh
$ ./configure --with-incompatible-bdb

After ./configure --with-incompatible-bdb, the script should create a makefile, located at the source path of bitcoin directory.
If the Makefile is not correctly generated, you may have encountered some issues with some missing dependencies.
The ones I experienced were related libdb4.8++-dev and libevent 16.04 dependencies.

To correctly install libd4.8++-dev dependency, I followed this solution:

$ sudo apt-get install software-properties-common
$ sudo add-apt-repository ppa:bitcoin/bitcoin
$ sudo apt-get update
$ sudo apt-get install libdb4.8-dev libdb4.8++-dev

To install libevent 16.04 simply:

$ sudo apt-get install libevent-dev

At this point, you can launch again the configuration script:

$ ./configure --with-incompatible-bdb

and a shiny new Makefile should be generated for you.
At this point, we’re pretty much close to have our bitcoin node up and running, we just have to launch the makefile:

$ make

…this may take a while ☕☕☕

Ok! Let’s install it!

$ sudo make install

and now check if everything is in the right place…

$ which bitcoind
$ which bitcoin-cli

Both items should be in /usr/local/bin

We now need to create a bitcoin config file, that will be used both from bitcoind and bitcoin-cli commands, and it will be essential when we will connect bitcoin to the social wallet.

$ cd
$ mkdir .bitcoin # we need to manually create the .bitcoin folder
$ vi bitcoin.conf # it will create an empty file

Here the simplest config we can live with.
Copy and paste the following code on your bitcoin.conf

### bitcoin.conf configuration file.

daemon=1
txindex=1
rpcuser=yourusername
rpcpassword=astrongpassword
rpchost=http://127.0.0.1
rpcport=18443

# Run on the test network instead of the real bitcoin network.
#testnet=1
#regtest=1

debug=0

Don’t forget to edit rpcuser and rpcpassword fields, then save and quit (:wq)

Start the bitcoin daemon 🧙‍

$ bitcoind -regtest -daemon

High five! You have a running daemon of bitcoin to play with 👏👏👏

To see the listening process you can execute this command:

$ netstat -pant

As you can see the bitcoin daemon is listening on port 18444, the custom regtest port. The main bitcoin network listens on port 8333, and the public test network listens on port 18333.
To know more about the differences between regtest, testnet and mainnet, the official bitcoin developer glossary is a great reference.

Another useful resource is the v.0.18 bitcoin release document.

This tutorial is based on a Sam Bowne one, the one I followed to install bitcoin node on my machine, you can find it here, big thanks to his work.

Install and run the social wallet api

With a fresh bitcoin node up and running on our machine, we can proceed to install and run the social wallet.
Same as before, the official guide to run swapi are available on the repository (You may also want to consider the docker image ).
In this guide, we will install swapi from the source code 🤟

Install needed dependencies

Swapi is written in clojure, a functional dialect of Lisp hosted on the java virtual machine.
In order to work with clojure, we need

• a JDK. The software is tested to work with openJDK versions 7 and 8 as well as with oracleJDK 8 and 10.
  If you don’t have any JDK installed on your machine, you can install the openJDK version 8 with:

jdk8 sudo apt install openjdk-8-jre-headless

• MongoDB Community edition to backup all the data registered on the blockchain, plus extended metadata
• Leiningen: Clojure de-facto dependencies management and build tool

Configure your social wallet

Once you correctly install the needed dependencies, we need to properly configure the social-wallet-api.yaml file, located under resources folder.

Here a sample configuration to use both a mongo database and the bitcoin node we just created.

log-level: debug

freecoin:
  apikey: device-id
  mongo:
    host: localhost
    port: 27017
    db:   freecoin
    currency: santamaria
  bitcoin:
    currency: btc
    number-confirmations: 6
    frequency-confirmations-millis: 20000
    rpc-config-path: /home/{user}/.bitcoin/bitcoin.conf
    deposit-expiration-millis: 3600000
    frequency-deposit-millis: 60000

You may want to customize some fields here, like the currency name, both under mongo and bitcoin, and the rpc-config-path
If you don’t know the absolute path of your bitcoin.conf

$ cd
$ cd .bitcoin
$ pwd

Add /bitcoin.conf to the pwd result.

Run Run Run!

We’re almost there!
Now it’s time to run our social wallet api instance.
The social wallet will first try to connect to a mongodb shell, open a new terminal tab and start up a mongod process:

$ sudo service mongod start
$ mongo

If you omit any other command after mongo, it will connect to the mongod that is running on localhost with default port 27017

🔌 Connected!

Back to your social-wallet-api folder:

$ lein ring server # which will start and spawn a browser on it

Pay attention to the logs, the last 5 lines will give you usefull informations about the status of your instance:

• Initialising app with name: social-wallet-api
• Creating the freecoin mongo stores
• MongoDB backend connected.
• bitcoin config is loaded
• Started server on port 3000

Great! it seems we have finally our social wallet working correctly…
Let’s test it!

Navigate to http://localhost:3000

🎉🎉🎉🎉

Test the swagger

Since we used an api-key we cannot perform any operation if we are not authorized.
During the build process, happened when we launched the lein ring server command, a new file was silently generated in our social-wallet-api folder, called apikey.yaml. It is a valid key that we can use to authenticate all the operations we will perform on the swagger.

$ cat apikey.yaml

it will return something like:

device-id:
K8trtGu4mF76OFqcZhJhgtxhqs5FluM

Go back to your browser, click on the top right authorize button, on the swagger, and paste there only the key value.

Once you inserted the key, you will be able to perform any kind of operations, both on the mongodb and on the bitcoin node.

Let’s try to launch a query to be sure all is working as expected.

Retrieve the currencies labels

When we customized our social-wallet-api.yaml, we defined 2 instances of freecoin: mongo and bitcoin.
The currency backed only by mongodb I decided to call it santamaria, as a medieval local currency used where I currently live, and labelled btc the one backed by our bitcoin blockchain.

From the swagger, click on LABEL and fill the query field with:

{
  "connection": "bitcoin",
  "type": "blockchain-and-db"
}

Execute the query clicking on the Try it out button, the result should be:

{
  "currency": "btc"
}

To retrieve the mongo backed currency, we need to change the query field with:

{
  "connection": "mongo",
  "type": "db-only"
}

This time, you should see the name of your local currency, in my case:

{
  "currency": "santamaria"
}

Awesome, isn’t it? 😍

Conclusions

We did a lot, and now it would be a perfect timing to step back from the terminal and go through some documentations of the several working part of our setup.

On the next tutorial, we will actually start to play around with our bitcoin regtest environment, creating addresses and mining some blocks in order to have some fake bitcoins to move around.
We will see how the swapi can be used to transfer currencies within a group, check balances and transactions and lotta more.