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  and  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

Install Berkeley database

Compile bitcoin

After , the script should create a , 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  and  dependencies.

To correctly install  dependency, I followed this solution:

To install  simply:

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

and a shiny new  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:

…this may take a while ☕☕☕

Ok! Let’s install it!

and now check if everything is in the right place…

Both items should be in 

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

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

Don’t forget to edit  and  fields, then save and quit ()

Start the bitcoin daemon 🧙‍

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

To see the listening process you can execute this command:

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:

Configure your social wallet

Once you correctly install the needed dependencies, we need to properly configure the  file, located under  folder.

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

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

Add  to the  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:

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

🔌 Connected!

Back to your  folder:

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  we cannot perform any operation if we are not authorized.
During the build process, happened when we launched the  command, a new file was silently generated in our social-wallet-api folder, called . It is a valid key that we can use to authenticate all the operations we will perform on the swagger.

it will return something like:

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 , 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:

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

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

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

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.