ipfs-log

An append-only log on IPFS.

ipfs-log is an immutable, operation-based conflict-free replicated data structure (CRDT) for distributed systems. It's an append-only log that can be used to model a mutable, shared state between peers in p2p applications.

Every entry in the log is saved in IPFS and each points to a hash of previous entry(ies) forming a graph. Logs can be forked and joined back together.

The module works in Node.js and Browsers.

           Log A                Log B
             |                    |
     logA.append("one")   logA.append("two")
             |                    |
             v                    v
          +-----+             +-------+
          |"one"|             |"hello"|
          +-----+             +-------+
             |                    |
     logA.append("two")   logA.append("world")
             |                    |
             v                    v
       +-----------+       +---------------+
       |"one","two"|       |"hello","world"|
       +-----------+       +---------------+
             |                    |
             |                    |
       logA.join(logB) <----------+
             |
             v
+---------------------------+
|"one","hello","two","world"|
+---------------------------+

Background
Install
Usage
API
Tests
Build
Contribute
License

Background

IPFS Log has a few use cases:

CRDTs
Database operations log
Feed of data
Track a version of a file
Messaging

It was originally created for, and currently used in, orbit-db - a distributed peer-to-peer database on IPFS.

Requirements

Node.js v8.0.0 or newer

Install

npm install ipfs-log

Usage

See the API documentation and examples for more details.

Quick Start

Install dependencies:

npm install ipfs-log ipfs

Run a simple program:

const IPFS = require('ipfs')
const Log  = require('ipfs-log')

const ipfs = new IPFS()
const log  = new Log(ipfs)

ipfs.on('ready' , () => {
  log.append({ some: 'data' })
    .then(log => log.append('text'))
    .then(log => console.log(log.values.map(e => e.payload)))
})

// [ { some: 'data' }, 'text' ]

Node.js

See examples for details.

If your platforms requires ES5-compatible JavaScript, there's a build in lib/es5/.

Browser

See examples/browser for details.

The distribution package for browsers is located in dist/ipfslog.min.js

If your platforms requires ES5-compatible JavaScript, there's a build in lib/es5/.

API

See API Documentation for full details.

Tests

npm test

Build

The build script will build the distribution file for browsers.

npm run build

Benchmarks

There's a benchmark suite in benchmarks/ that can be run with:

node benchmarks/benchmark-append.js
node benchmarks/benchmark-join.js
node benchmarks/benchmark-expand.js

There's append and join benchmarks for browsers in benchmarks/browser/ which you can run by opening the .html files in your browser.

Contribute

If you find a bug or something is broken, let us know! PRs and issues are gladly accepted too. Take a look at the open issues, too, to see if there is anything that you could do or someone else has already done. Here are some things I know I need:

TODO

Support for payload encryption

chrisdostert/ipfs-log