JavaScript HTML Makefile
Clone or download
Latest commit 0c2d383 Jul 12, 2018

README.md

ipfs-log

npm CircleCI Status

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")   logB.append("hello")
             |                    |
             v                    v
          +-----+             +-------+
          |"one"|             |"hello"|
          +-----+             +-------+
             |                    |
     logA.append("two")   logB.append("world")
             |                    |
             v                    v
       +-----------+       +---------------+
       |"one","two"|       |"hello","world"|
       +-----------+       +---------------+
             |                    |
             |                    |
       logA.join(logB) <----------+
             |
             v
+---------------------------+
|"one","hello","two","world"|
+---------------------------+

Table of Contents

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

License

MIT © 2017 Haadcode