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"|
+---------------------------+
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.
- Node.js v8.0.0 or newer
npm install ipfs-log
See the API documentation and examples for more details.
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' ]See examples for details.
If your platforms requires ES5-compatible JavaScript, there's a build in lib/es5/.
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/.
See API Documentation for full details.
Run all tests:
npm test
Run tests with js-ipfs only (default):
mocha
Run tests with go-ipfs only:
TEST=go mocha
The build script will build the distribution file for browsers.
npm run build
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.
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:
- Support for payload encryption
MIT © 2016-2018 Protocol Labs Inc., Haja Networks Oy