Secure scuttlebutt core (similar to [ssb-server]) in a browser.
Last updated 2 days ago by arj03 .
Beerware · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install ssb-browser-core 
SYNC missed versions from official npm registry.

SSB browser core

Secure scuttlebutt core (similar to ssb-server) in a browser.

This is a full implementation of ssb running in the browser only (but not limited to, of course). The key of your feed is stored in the browser together with the log, indexes and smaller images. To reduce storage and network requirements, partial replication has been implemented. Wasm is used for crypto and is around 90% the speed of the C implementation. A WebSocket is used to connect to pubs or rooms. The bundle-core.js file in dist/ is roughly 2mb.

Replication in the browser is quite a bit slower than in node, around 2x. There doesn't seem to be a single cause, it appears to be all the diferrent layers that are slower: end-to-end encryption, database write etc.

SSB conn is used for connections and rooms are supported. Partial replication is implemented which allows two connected browsers to do a partial sync.

Partial replication speed on a fast laptop is roughly 425 feeds in 56 seconds, and roughly half of that on a slow laptop or when running on battery.


Boxes represent modules, some internal to browser-core and some external. Ellipses in gray represents overall areas and are thus not modules.

3`graphviz digraph hierarchy { nodesep=0.6 node [shape=record];

{ rank=same SSBBrowserCore Validate Keys } { rank=same SSBBrowserCore MultiServer MuxRPC }

Network [shape=ellipse style=filled] Connections [shape=ellipse style=filled] Sync [shape=ellipse style=filled] Feed [shape=ellipse style=filled]

SSBBrowserCore->{Network Connections Sync SSBDB2 Feed} Feed->{Validate Keys} Connections->{SSBConn Rooms} Network->{MultiServer MuxRPC SecretHandshake} Sync->{FeedSyncer EBT Blobs} SSBDB2->{Indexes JITDB AsyncAppendOnlyLog } } 3`


Once you load the bundle-core.js file in a browser a global SSB object will be available.

The api is not meant to be 100% compatible with regular ssb-db. Overall there are two major parts: db and net.

I highly recommend looking at ssb-browser-demo for an example of how this library can be used to build applications.


Loading the bundle-core file as above will use browser.js, meaning default options. It is also possible to overwrite config options, like:

require('../core.js').init(dir, { blobs: { max: 512 * 1024 } })

Default config options are defined in net.js.

Runtime configurations


The number of hops from which to store feeds in full. Hops + 1 will be stored in partial state, meaning profiles, contacts and latest messages will be stored.

Default is 1.


This is the ssb-db2 module.


The contacts index for the friends graph.

Contains the method getGraphForFeed(feed, cb) that will return an object of: following, blocking and extended given the feed.


Returns the profiles index.


This is the secret-stack module with a few extra modules loaded. ssb-ws is used to create web socket connections to pubs.


The public key of the current user

rpc:connect event

Example:'rpc:connect', (rpc) => {
  rpc.on('closed', () => console.log("bye"))

connectAndRemember(addr, data)

Will connect and store as to automatically reconnect on reload. Options are as described in ssb-conn.

connect(addr, cb)

Connect to addr only once. Cb is (err, rpc)


This is where the blobs api can be found. The module implements the blobs protocol and so can exchange blobs with connection peers. It also contains with the the following extra methods:

hash(data, cb)

Hashes data and returns the digest or err


onFileSelect: function(ev) {
  const file =[0]
  file.arrayBuffer().then(function (buffer) { Uint8Array(buffer), (err, digest) => {

add(blobId, file, cb)

Adds the file (such as one obtained from when using a file select) to the blob store using the blobId name. BlobId is & + hash.


Returns a http URL string for the current connection. This is useful in a browser for images that you don't want to store directly on the device.

privateGet(blobId, unbox, cb)

Callback with err or a url that works for e.g images that was received in a private message.

localGet(blobId, unbox, cb)

If blob already exists will callback with err or a url that can be used for images for a blob. Otherwise the blob will get requested and if size is smaller than the maximum size, the blob will be stored locally and used for callback, otherwise the callback will return a remoteURL link.


The ssb-ooo module

Browser specific methods on net

For partial replication a special plugin has been created and implemented in browser core, other clients such as a pub needs to have the ssb-partial-replication plugin installed.

Once a rpc connection has been established, a few extra methods are available under See plugin for documentation.


Other things directly on the global SSB object


The path to where the database and blobs are stored.


Gets one of the connected peers that is not a room server.


box method from ssb-keys. Useful for private messages.


The ssb-blob-files module.

SSB: loaded event

Because loading wasm is async, an event will be fired when SSB is ready to use. Example:'SSB: loaded', function() {
  console.log("ready to rock!")


There are a few other undocumented methods, these will probably be moved to another module in a later version as they are quite tied to ssb-browser-demo.

Browser compatibility

Tested with Chrome and Firefox. Chrome is faster because it uses fs instead of indexeddb. Also tested on android using Chrome and iOS using safari.


Run npm run build for debugging and npm run release for a smaller dist file.

For a smaller bundle file you can apply (patch -p0 < x.patch):

  • patches/sodium-browserify.patch

Current Tags

  • 6.0.5                                ...           latest (2 days ago)

44 Versions

  • 6.0.5                                ...           2 days ago
  • 6.0.4                                ...           6 days ago
  • 6.0.3                                ...           8 days ago
  • 6.0.2                                ...           10 days ago
  • 6.0.1                                ...           12 days ago
  • 6.0.0                                ...           22 days ago
  • 5.1.1                                ...           3 months ago
  • 5.1.0                                ...           3 months ago
  • 5.0.0                                ...           3 months ago
  • 4.0.11                                ...           5 months ago
  • 4.0.10                                ...           5 months ago
  • 4.0.9                                ...           5 months ago
  • 4.0.8                                ...           5 months ago
  • 4.0.7                                ...           5 months ago
  • 4.0.6                                ...           6 months ago
  • 4.0.5                                ...           6 months ago
  • 4.0.4                                ...           6 months ago
  • 4.0.3                                ...           6 months ago
  • 4.0.2                                ...           6 months ago
  • 4.0.1                                ...           6 months ago
  • 4.0.0                                ...           6 months ago
  • 3.1.1                                ...           9 months ago
  • 3.1.0                                ...           10 months ago
  • 3.0.0                                ...           10 months ago
  • 2.4.0                                ...           10 months ago
  • 2.3.1                                ...           a year ago
  • 2.3.0                                ...           a year ago
  • 2.2.1                                ...           a year ago
  • 2.2.0                                ...           a year ago
  • 2.1.1                                ...           a year ago
  • 2.1.0                                ...           a year ago
  • 2.0.2                                ...           a year ago
  • 2.0.1                                ...           a year ago
  • 2.0.0                                ...           a year ago
  • 1.4.2                                ...           a year ago
  • 1.4.1                                ...           a year ago
  • 1.4.0                                ...           a year ago
  • 1.3.0                                ...           a year ago
  • 1.2.3                                ...           a year ago
  • 1.2.2                                ...           a year ago
  • 1.2.1                                ...           a year ago
  • 1.2.0                                ...           a year ago
  • 1.1.0                                ...           a year ago
  • 1.0.0                                ...           a year ago
Maintainers (1)
Today 0
This Week 12
This Month 122
Last Day 0
Last Week 98
Last Month 2
Dependencies (27)
Dev Dependencies (5)
Dependents (0)

Copyright 2014 - 2016 © |