sporedb

README

🍄 SporeDB

SporeDB is a work-in-progress to a highly scalable, fast, resilient, decentralized and flexible database engine, named by analogy with the Mycology science.

Idea

Extract from the full whitepaper

Distributed databases are very popular when it comes to service scalability and high availability. Such databases, like Apache Cassandra, MongoDB or Redis are able to handle node or network failures, but cannot handle nodes acting in a byzantine way.

Solving the Byzantine problem usually involves complex, costly or non-scalable consensus algorithms. We can mention the well-known PBFT, the Bitcoin Proof-of-Work , the Tendermint protocol or the Stellar CP among many others. Generally, these protocols require some strong coordination between nodes (leadership for example), or are mostly designed for a specific application (crypto-currencies for example). This strong coordination reduces scalability and performance of the global system.

We introduce SporeDB as a way to solve these problems using simple (but powerful) techniques.

To help the development effort, Bitcoin donations are welcome at 146VpSS56tkvt2ZSXLpwYBjjPR2grf5P9N. Thanks!

Overview

The SporeDB architecture is represented in the following figure :

• SporeDB nodes are connected through a P2P network using a home-made "Mycelium" protocol ;
• Every node store a whole copy of the database, ensuring data security ;
• Write operations are applied by the cluster with the SporeDB Consensus Algorithm, presented (and hopefully proved) in the whitepaper ;
• Nodes expose a GRPC API server that can be used by clients to access the data and to submit transactions.

Installation

With Go

$ go get gitlab.com/SporeDB/sporedb

Without Go (Docker)

$ docker pull registry.gitlab.com/sporedb/sporedb

We suggest that you use docker volumes to preserve SporeDB states, like this:

$ docker run --rm -it -e PASSWORD=******* -v $PWD:/sporedb registry.gitlab.com/sporedb/sporedb --help

Build from source

Go 1.8+ is required for source building:

$ make install-bolt

RocksDB v5.6.x is required to build SporeDB with RocksDB support (provides enhanced write performance):

$ make

Finally, some dependencies are required to build protobuf files:

• Protoc v3.1.x
  • With the Protoc-Gen-Go plugin

To setup a clean compilation environment please refer to the up-to-date continuous integration Dockerfile.

Configuration

Writing main configuration file

SporeDB needs a YAML configuration file. An example is available in sporedb.yaml and can be used as-is after edition of identity field that will identify you in your network.

You might also want to add some information about peers to connect to in this configuration file.

Please note that right now, network topology is mainly static. This will be upgraded to a full gossip network soon.

Setting-up crypto credentials

You will need some credentials to build a Trust Network. SporeDB uses a system very similar to OpenPGP, with some specific modifications. Basically, each node of the network holds a public/private Ed25519 keys pair for integrity verification.

First of all, you must set the PASSWORD environment variable. This password will be used to encrypt your private key. You might then want to send your public key to the other peers of your network.

$ export PASSWORD=********
$ sporedb keys init   # Will create your credentials
$ sporedb keys export # Will export your public key

You might also want to import other's public key with a specific trust level in your keyring. For example, the following command imports the Alice's public key, stored in alice.pem, with a High trust level.

$ cat alice.pem > sporedb keys import alice -t high

For more information and advanced features (like key's signatures), see sporedb keys -h.

Creating a policy

Policies define what nodes can and cannot do accross a network of nodes ("Mycelium"). We encourage you to read the full whitepaper to fully understand how policy are designed.

Policies are stored in JSON files, and can be created with a wizzard:

$ sporedb keys ls
+----------+----------+-----------+----------------+
| Identity |  Trust   | Certified |  Fingerprint   |
+----------+----------+-----------+----------------+
| <self>   | ultimate | ✔️️ yes     | 63:29:41:4A:B9 |
+----------+----------+-----------+----------------+
| bob      | high     | ✔️️ yes     | B1:D3:CD:91:07 |
+----------+----------+-----------+----------------+
| carol    | high     | ✔️️ yes     | 09:0F:86:26:E0 |
+----------+----------+-----------+----------------+

$ sporedb policy create
Name of the policy [6cfeddad-eaec-4e0b-abf8-4658f0297402]:
Comment []: A test policy
Shall this node be considered as an endorser? [y/n] [y]: y
Endorser #1 (blank to skip) []: bob
Endorser #2 (blank to skip) []: carol
Endorser #3 (blank to skip) []:
Maximum number of byzantine (faulty) endorsers [1]: 1
Quorum [3]: 3

The previous dialog will create a policy that will allow the current node, bob and carol to endorse (validate) spore submissions in the network.

Usage

Each SporeDB node will offer a GRPC API server, enabling Clients to connect to it. Right now, it is possible to send basic instructions to one Node using embedded client.

On first terminal:

$ sporedb server
Successfully loaded policy test
SporeDB is running on localhost:4000

On second terminal:

$ sporedb client -s localhost:4000 -p test
Now using policy test
SporeDB client is connected and ready to execute your luscious instructions!
localhost:4000> SET key value
Transaction: bbd5aa6b-7b56-4ce9-926a-ea0ce6175ca0
localhost:4000> GET key
value

Documentation is being written about client capabilities. You can though check the available commands here.

Adding a systemd service

If you want to start your SporeDB automatically at each boot, you should consider creating a systemd service.

First, copy the service skeleton in the systemd configuration directory:

$ sudo cp ./sporedb.service /etc/systemd/system

Now you'll have to edit the file /etc/systemd/system/sporedb.service according to your installation.

Finally you can use systemd commands to manage your sporedb installation

$ sudo systemctl start sporedb       #--- start sporedb now
$ sudo systemctl status sporedb      #--- check sporedb status
$ sudo systemctl enable sporedb      #--- start sporedb on boot
$ sudo journalctl -u sporedb         #--- show sporedb logs

Acknowledgements

SporeDB should NOT be used in production yet. It is very new and not stable enough.

Feedbacks about the project and the whitepaper will be very much appreciated! 😘

Implemented features

• Basic database management
  • SET operation
  • CONCAT operation
  • ADD operation (float)
  • MUL operation (float)
  • SADD operation (set)
  • SREM operation (set)
• Basic policy management
  • With disk usage quotas
• Integrity with Ed25519 signatures
  • CLI KeyRing management similar to OpenPGP
• P2P network
  • Gossip communications
  • Partial and Full State-Transfer support
• GRPC Server / Client API
• Pluggable underlying database drivers
  • BoltDB (default)
  • RocksDB

Documentation

Overview

Command sporedb is a decentralized and byzantine fault tolerant database client / server.