README.md

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")   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
• 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.

• Log
  • Constructor
    • new Log(ipfs, [id])
  • Properties
    • id
    • values
    • length
    • clock
    • heads
    • tails
  • Methods
    • append(data)
    • join(log)
    • toMultihash()
    • toBuffer()
    • toString()
  • Static Methods
    • Log.expand()
    • Log.expandFrom()
    • Log.fromEntry()
    • Log.fromEntryHash()
    • Log.toMultihash()
    • Log.fromMultihash()

Tests

Run all tests:

npm test

Run tests with js-ipfs only (default):

mocha

Run tests with go-ipfs only:

TEST=go mocha

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 © 2016-2018 Protocol Labs Inc., Haja Networks Oy