OrbitDB API

The Sync Protocol for OrbitDB synchronizes the database operations module:Log between multiple peers.

The Sync Protocol sends and receives heads between multiple peers, both when opening a database and when a database is updated, ie. new entries are appended to the log.

When Sync is started, a peer subscribes to a pubsub topic of the log's id. Upon subscribing to the topic, peers already connected to the topic receive the subscription message and "dial" the subscribing peer using a libp2p custom protocol. Once connected to the subscribing peer on a direct peer-to-peer connection, the dialing peer and the subscribing peer exchange the heads of the Log each peer currently has. Once completed, the peers have the same "local state".

Once the initial sync has completed, peers notify one another of updates to the log, ie. updates to the database, using the initially opened pubsub topic subscription. A peer with new heads broadcasts changes to other peers by publishing the updated heads to the pubsub topic. Peers subscribed to the same topic will then receive the update and will update their log's state, the heads, accordingly.

The Sync Protocol is eventually consistent. It guarantees that once all messages have been sent and received, peers will observe the same log state and values. The Sync Protocol does not guarantee the order in which messages are received or even that a message is recieved at all, nor any timing on when messages are received.

Source:

sync.js, line 9

Examples

// Using defaults
const sync = await Sync({ ipfs, log, onSynced: (peerId, heads) => ... })

// Using all parameters
const sync = await Sync({ ipfs, log, events, onSynced: (peerId, heads) => ..., start: false })
sync.events.on('join', (peerId, heads) => ...)
sync.events.on('leave', (peerId) => ...)
sync.events.on('error', (err) => ...)
await sync.start()

Namespaces

Sync

Methods

(async) Sync(params) → {module:Sync~Sync}

Creates a Sync instance for sychronizing logs between multiple peers.

Parameters:

Name Type Description

params

Object

One or more parameters for configuring Sync.

Properties

Name	Type	Attributes	Description
`ipfs`	IPFS		An IPFS instance.
`log`	Log		The log instance to sync.
`events`	EventEmitter	<optional>	An event emitter to use. Events emitted are 'join', 'leave' and 'error'. If the parameter is not provided, an EventEmitter will be created.
`onSynced`	onSynced	<optional>	A callback function that is called after the peer has received heads from another peer.
`start`	Boolean	<optional>	True if sync should start automatically, false otherwise. Defaults to true.