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.
