Skip to content
Start here!
Branch: master
Clone or download

Latest commit

Fetching latest commit…
Cannot retrieve the latest commit at this time.


Type Name Latest commit message Commit time
Failed to load latest commit information.

Freechains: Peer-to-peer Content Dissemination

  • Local-first publish-subscribe topic-based model
  • Unstructured peer-to-peer gossip dissemination
  • Happened-before best-effort partial order
  • Per-topic reputation system for healthiness
  • Multiple flavors of public and private communication (1->N, 1<-N, N<->N, 1<-)
  • Free in all senses

(In bold we highlight what we believe is particular to Freechains.)

A user posts a message to a chain (a topic) and all other users subscribed to the same chain eventually receive the message. Users spend their reputation to post new messages and gain reputation from consolidated posts. Users can like and dislike messages from other users, which transfer reputation between them.


First, you need to install java and libsodium:

$ sudo apt install default-jre libsodium23

Then, you are ready to install freechains:

$ wget

# choose one:
$ sh .                    # either unzip to current directory (must be in the PATH)
$ sudo sh /usr/local/bin  # or     unzip to system  directory


The basic API of Freechains is very straightforward:

  • host create: instantiates a peer locally (executed only once)
  • host start: starts the local peer to serve requests (executed on every restart)
  • crypto create: creates an identity
  • chains join: joins a chain locally to post and read content
  • chain post: posts to a chain locally
  • chain get: reads a post locally
  • chain traverse: iterates over (discovers) local posts
  • peer send/recv: synchronizes a local chain with a remote peer

Follows a step-by-step execution:

  • Create a freechains host:
$ freechains host create /tmp/myhost
  • Start host:
$ freechains host start /tmp/myhost
  • Switch to another terminal.

  • Join the /chat chain:

$ freechains chains join /chat
  • Create an identity:
$ freechains crypto create pubpvt "My very strong passphrase"
EB172ED6C782145B8D4FD043252206192C302E164C0BD16D49EB9D36D5188070 96700ACD1128035FFEF5DC264DF87D5FEE45FF15E2A880708AE40675C9AD039EEB172ED6C782145B8D4FD043252206192C302E164C0BD16D49EB9D36D5188070
$ PVT=96700ACD1128035FFEF5DC264DF87D5FEE45FF15E2A880708AE40675C9AD039EEB172ED6C782145B8D4FD043252206192C302E164C0BD16D49EB9D36D5188070
  • Post some content:
$ freechains chain post /chat inline "Hello World!" --sign=$PVT
$ freechains chain post /chat inline "I am here!"   --sign=$PVT
  • Communicate with other peers:
    • Create another freechains host.
    • Start new host.
    • Join the /chat chain.
    • Synchronize from the first host.
$ freechains host create /tmp/othost 8331
$ freechains host start /tmp/othost
# switch to another terminal
$ freechains --host=localhost:8331 chains join /chat
$ freechains --host=localhost:8330 peer send localhost:8331 /chat

The last command sends all new posts from 8330 to 8331, which can then be traversed as follows: - Identify the predefined "genesis" post of /chat. - Acquire it to see what comes next. - Iterate over its fronts posts recursively.

$ freechains --host=localhost:8331 chain genesis /chat
$ freechains --host=localhost:8331 chain get /chat block 0_A80B5390F7CF66A8781F42AEB68912F2745FC026A71885D7A3CB70AB81764FB2
    "fronts": [
$ freechains --host=localhost:8331 chain get /chat block 1_1D5D2B146B49AF22F7E738778F08E678D48C6DAAF84AF4128A17D058B6F0D852
    "immut": {
        "backs": [
    "fronts": [
$ freechains --host=localhost:8331 chain get /chat payload 1_1D5D2B146B49AF22F7E738778F08E678D48C6DAAF84AF4128A17D058B6F0D852
Hello World!
You can’t perform that action at this time.