OrbitDB

OrbitDB is a serverless, distributed, peer-to-peer database. OrbitDB uses IPFS as its data storage and Libp2p Pubsub to automatically sync databases with peers. It's an eventually consistent database that uses Merkle-CRDTs for conflict-free database writes and merges making OrbitDB an excellent choice for p2p and decentralized apps, blockchain applications and local-first web applications.

OrbitDB provides various types of databases for different data models and use cases:

events: an immutable (append-only) log with traversable history. Useful for "latest N" use cases or as a message queue.
documents: a document database to which JSON documents can be stored and indexed by a specified key. Useful for building search indices or version controlling documents and data.
keyvalue: a key-value database just like your favourite key-value database.
keyvalue-indexed: key-value data indexed in a Level key-value database.

All databases are implemented on top of OrbitDB's OpLog, an immutable, cryptographically verifiable, operation-based conflict-free replicated data structure (CRDT) for distributed systems. OpLog is formalized in the paper Merkle-CRDTs. You can also easily extend OrbitDB by implementing and using a custom data model benefitting from the same properties as the default data models provided by the underlying Merkle-CRDTs.

This is the Javascript implementation and it works both in Browsers and Node.js with support for Linux, OS X, and Windows.

A Go implementation is developed and maintained by the Berty project at berty/go-orbit-db.

Installation

Install OrbitDB and its dependencies:

npm install @orbitdb/core helia

Browser `<script>` tag

OrbitDB can be loaded in the browser using the distributed js file with the <script/> tag. OrbitDB is the global namespace and all external functions are available via this namespace:

<script>/path/to/orbitdb.min.js</script>

Quick Start

If you want to get up and running with OrbitDB quickly, install and follow the instructions in the @orbitdb/quickstart module.

Usage

If you're using @orbitdb/core to develop browser or Node.js applications, use it as a module with the javascript instance of IPFS.

import { createHelia } from 'helia'
import { createOrbitDB } from '@orbitdb/core'
import { gossipsub } from "@chainsafe/libp2p-gossipsub";
import { identify } from "@libp2p/identify";
import { createLibp2p } from 'libp2p'

const Libp2pOptions = {
  services: {
    pubsub: gossipsub({
      // neccessary to run a single peer
      allowPublishToZeroTopicPeers: true
    }),
    identify: identify()
  }
}

;(async function () {
  const libp2p = await createLibp2p({ ...Libp2pOptions })
  const ipfs = await createHelia({libp2p})
  const orbitdb = await createOrbitDB({ ipfs })

  // Create / Open a database. Defaults to db type "events".
  const db = await orbitdb.open("hello")
  
  const address = db.address
  console.log(address)
  // "/orbitdb/zdpuAkstgbTVGHQmMi5TC84auhJ8rL5qoaNEtXo2d5PHXs2To"
  // The above address can be used on another peer to open the same database

  // Listen for updates from peers
  db.events.on("update", async entry => {
    console.log(entry)
    const all = await db.all()
    console.log(all)
  })

  // Add an entry
  const hash = await db.add("world")
  console.log(hash)

  // Query
  for await (const record of db.iterator()) {
    console.log(record)
  }
  
  await db.close()
  await orbitdb.stop()
  await ipfs.stop()
})()