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.6.0 or newer (uses
...spread syntax) - Preferably you should use an LTS version of node.js (even numbered 8, 10, etc)
This project uses npm and nodejs.
npm install ipfs-log
See the API documentation and examples for more details.
Install dependencies:
npm install ipfs-log ipfs
Run a simple program:
// For js-ipfs >= 0.38
const Log = require("ipfs-log");
const IdentityProvider = require("orbit-db-identity-provider");
const IPFS = require("ipfs");
const start = async () => {
const identity = await IdentityProvider.createIdentity({ id: "peerid" });
const ipfs = await IPFS.create({ repo: "./path-for-js-ipfs-repo" });
const log = new Log(ipfs, identity);
await log.append({ some: "data" });
await log.append("text");
console.log(log.values.map((e) => e.payload));
};
start();
// [ { 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
To use the benchmark runner:
node --expose-gc benchmarks/runner/index.js -r --grep append-stress --stress-limit InfinityThis will run the append-stress benchmarks until it is canceled. For more information, see the Benchmarking README.
Run the following command before you commit.
make rebuild
This will ensure that dependencies and built files are all based on the current code base.
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., 2016-2019 Haja Networks Oy