Complementary currency toolkit
Clojure Shell Other
Latest commit e62e6be Feb 10, 2017 @jaromil jaromil committed on GitHub Merge pull request #11 from aspasia/feature/timbre-logging
Replaced logging with timbre

Freecoin - digital social currency toolkit

software by

Freecoin aims to be a framework for remuneration and authentication supporting multi-sig and off-line transactions on top of multiple blockchain backends. It is open source, written in Clojure and comprising of a REST API and a clean user interface.

Build Status


The design of Freecoin is informed by an extensive economic and user-centered research conducted by the D-CENT project and documented in deliverables that are available to the public:

More resources can be found on the D-CENT webpage:


Freecoin identity management is delegated to Stonecutter, the D-CENT SSO. To run Freecoin one also needs to configure integration with a running instance of Stonecutter configured to accept the Freecoin application. The configuration locations are:

  • Freecoin: profiles.clj
  • Stonecutter: resources/client-credentials.yml

Running the app inside a Vagrant virtual machine

Install the latest version of Vagrant and VirtualboxISO (be warned, most distributions have outdated packages which won't function well)

Then go into the ops/ directory in Freecoin and run vagrant up, this will create and provision a new virtual machine running Freecoin.

Inside ops/stonecutter there is another setup to create and run a local Stonecutter SSO with the same command vagrant up given inside it. Once the Stonecutter SSO box is up and running, you should vagrant ssh into it and:

  • edit the /home/vagrant/stonecutter/resources/client-credentials.yml to add the Freecoin client ID and secret in your project.clj
  • run the application with /home/vagrant/stonecutter/
  • verify that Stonecutter is up and running at http://localhost:5000

Running the app locally

Install all necessary dependencies, for instance using the following packages found on APT based systems:

openjdk-7-jdk mongodb libversioneer-clojure haveged

then install Leiningen which will take care of all Clojure dependencies

mkdir ~/bin
wget -O ~/bin/lein
chmod +x ~/bin/lein

then from inside the Freecoin source, start it with

lein ring server

This command will open a browser on localhost port 8000

Running the app from a live repl (for developers)

The server can be started and stopped from the repl by doing the following

$ lein repl
freecoin.core=> (start) ;; starts the server
freecoin.core=> (stop) ;; stops the server
freecoin.core=> (use 'freecoin.handlers.debug :reload) (stop) (start) ;; refresh specific namespaces

Live reloading of .clj modules in the repl

Every time you change a file, the tracker will reload it in the running VM and show a message in the corner of your screen (using notify-send; Linux only for now):

lein repl
user=> (use '
user=> (start-nstracker) ;; starts the file change tracker

Running the tests

Freecoin comes complete with test units which are run by the CI but can also be run locally.

For the purpose we use Clojure's midje package, to be run with:

lein midje

See: for advanced testing features.


API design is work in progress on


Part of Decentralized Citizen Engagement Technologies (D-CENT)

R&D funded by the European Commission (FP7/CAPS 610349)

Copyright (C) 2015-2016 foundation

Copyright (C) 2015 Thoughtworks, Inc.

Designed and maintained by Denis Roio

With contributions by:

  • Marco Sachy
  • Gareth Rogers
  • Duncan Mortimer
  • Andrei Biasprozvanny
  • Arjan Scherpenisse
  • Amy Welch
  • Joonas Pekkanen
  • Carlo Sciolla
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <>.