An append-only log on IPFS.
ipfs-log is a partially ordered linked list of IPFS objects.
This module provides a data-agnostic transport mechanism using IPFS with the ability to traverse the history. Every entry in the log is saved in IPFS and each points to a hash of previous entry(ies). Logs can be forked and joined back together.
entry0 <-- entry1 <-- entry2 ...
The module works in Node.js and Browsers.
Originally created for, and currently used in, orbit-db - a distributed peer-to-peer database on IPFS
npm install ipfs-log
See examples for more details.
const IPFS = require('ipfs')
const Log = require('ipfs-log');
const ipfs = new IPFS();
const log = new Log(ipfs, 'A');
log.add({ some: 'data' })
.then(() => log.add('text'))
.then(() => console.log(log.items))
// [Entry {
// payload: { some: 'data' },
// hash: 'QmYiefTHzCLNroCfKw7YTUy9Yo53sCfwzyU5p7SBBxTcmD',
// next: []
// },
// Entry {
// payload: 'text',
// hash: 'QmdNFpoyXLNdR8Wx5LYZBLcXH8aAEopSMnnubWLn4AciCZ',
// next: [ 'QmYiefTHzCLNroCfKw7YTUy9Yo53sCfwzyU5p7SBBxTcmD' ]
// }]
const IPFS = require('ipfs')
const Log = require('ipfs-log');
const log = new Log(new IPFS(), 'A', 'db name', { maxHistory: 1000 });
log.add('one')
.then((entry1) => {
console.log('Entry1:', entry1.hash, entry1.payload);
return log.add('two');
})
.then((entry2) => {
console.log('Entry2:', entry2.hash, entry2.payload);
console.log('Entry2.next:', entry2.next[0]); // == entry1.hash
});
The distribution package for browsers is located in dist/ipfslog.min.js
<html>
<head>
<meta charset="utf-8">
</head>
<body>
<script type="text/javascript" src="../../dist/ipfslog.min.js" charset="utf-8"></script>
<script type="text/javascript" src="../../node_modules/ipfs/dist/index.js" charset="utf-8"></script>
<script type="text/javascript">
const ipfs = new window.Ipfs();
const log = new Log(ipfs, 'A')
log.add('one')
.then((entry1) => {
console.log('Entry1:', entry1.hash, entry1.payload, entry1);
return log.add('two')
})
.then((entry2) => {
console.log('Entry2:', entry2.hash, entry2.payload, entry2);
console.log("Entry2.next:", entry2.next[0]);
});
</script>
</body>
</html>
const Log = require('ipfs-log');
Create a log. The first argument is an ipfs instance which can be of type js-ipfs or js-ipfs-api. See https://github.com/ipfs/js-ipfs-api for IPFS api documentation.
const ipfs = require('ipfs')(); // ipfs javascript implementation
// Or
const ipfs = require('ipfs-api')(); // local ipfs daemon (go-ipfs)
const log = new Log(ipfs, 'userid', 'name of the log');
ipfs is an instance of IPFS (ipfs or ipfs-api)
id is a unique log identifier. Usually this should be a user id or similar.
name is the name of the log for convenience purposes.
options are the following:
{
maxHistory: 1000 // number of item to fetch at sync
}
Add a log entry. The new entry gets the references to previous entries automatically. Returns a Promise that resolves to the added Entry.
data can be any type of data: Number, String, Object, etc. It can also be an instance of Entry.
log.add({ some: 'data' })
.then(() => log.add('text'))
.then(() => console.log(log.items))
// [Entry {
// payload: { some: 'data' },
// hash: 'QmYiefTHzCLNroCfKw7YTUy9Yo53sCfwzyU5p7SBBxTcmD',
// next: []
// },
// Entry {
// payload: 'text',
// hash: 'QmdNFpoyXLNdR8Wx5LYZBLcXH8aAEopSMnnubWLn4AciCZ',
// next: [ 'QmYiefTHzCLNroCfKw7YTUy9Yo53sCfwzyU5p7SBBxTcmD' ]
// }]
Joins the log with other log. Fetches history up to options.maxHistory items, ie. items that are not in this log but referred to in items in other. Returns a Promise that resolves to an Array of items that were added.
// log1.items ==> ['A', 'B', 'C']
// log2.items ==> ['C', 'D', 'E']
log1.join(log2).then((added) => console.log(added)); // ==> ['D', 'E']
// log1.items ==> ['A', 'B', 'C', 'D', 'E']
Returns an Array of all items in the log.
const items = log.items;
// items ==> ['A', 'B', 'C']
Returns a snapshot of the log with items in the current batch. Current batch are the items in the log that have been added locally after the latest join with another log.
const snapshot = log.snapshot;
// snapshot ==> { id: 'log id', items: ['A', 'B', 'C']}
All class methods take an ipfs instance as the first parameter. The ipfs can be of js-ipfs or js-ipfs-api. See https://github.com/ipfs/js-ipfs-api for IPFS api documentation.
const ipfs = require('ipfs')(); // js-ipfs
// Or
const ipfs = require('ipfs-api')(); // local ipfs daemon
See Instance methods on how to use the log instance
Get the IPFS hash of this log. Returns a Promise that resolves to an IPFS hash.
Log.getIpfsHash(ipfs, log).then((hash) => console.log(hash));
// ==> 'Qm...abc123'
Create a log from an IPFS hash. Returns a Promise that resolves to a Log instance.
Log.fromIpfsHash(ipfs, hash).then((log) => console.log(log));
// ==> instance of Log
Create a log from a log snapshot. Returns a Promise that resolves a Log instance.
const original = new Log(ipfs, 'id')
// Add items to the original log
// ...
const snapshot = original.snapshot;
Log.fromSnapshot(ipfs, snapshot).then((log) => console.log(log));
// ==> log is instance of Log and contains the same entries as original log
TODO: document Entry.
npm install
npm test
The build script will build the distribution file for browsers.
npm run build
FAQs
Append-only log CRDT on IPFS
The npm package ipfs-log receives a total of 459 weekly downloads. As such, ipfs-log popularity was classified as not popular.
We found that ipfs-log demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 4 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
Security News
NVD’s backlog surpasses 20,000 CVEs as analysis slows and NIST announces new system updates to address ongoing delays.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.