peer-crdt

An extensible collection of operation-based CRDTs that are meant to work over a p2p network.

Index

• API
• Composing
• Dynamic composition
• Built-in types
• Extending types
• Read-only nodes
• Zero-knowledge replication
• signAndEncrypt/decryptAndVerify contract
• Interfaces
• Internals
• License

API

CRDT.defaults(options)

Returns a CRDT collection that has these defaults for the crdt.create() options.

CRDT.create(type, id[, options])

• type: string representing the CRDT type
• id: string representing the identifier of this CRDT. This ID will be passed down into the Log constructor, identifying this CRDT to all peers.
• options: optional options. See options.

Returns an new instance of the CRDT type.

crdt.on('change', () => {})

Emitted when the CRDT value has changed.

crdt.value()

Returns the latest computed CRDT value.

Other crdt methods

Different CRDT types can define different methods for manipulating the CRDT.

For instance, a G-Counter CRDT can define an increment method.

Composing

Allows the user to define high-level schemas, composing these low and high-level CRDTs into their own (observable) high-level structure classes.

CRDT.compose(schema)

Composes a new CRDT based on a schema.

Returns a constructor function for this composed CRDT.

const MyCRDT = CRDT.compose(schema)
const myCrdtInstance = MyCRDT(id)

• schema: an object defining a schema. Example:

const schema = {
  a: 'g-set',
  b: 'lww-set'
}

(Internally, the IDs of the sub-CRDTs will be composed by appending the key to the CRDT ID. Ex: 'id-of-my-crdt/a')

Instead of a key-value map, you can create a schema based on an array. The keys for these values will be the array indexes. Example:

const schema = [
  'g-set',
  'lww-set'
]

Any change in a nested object will trigger a change event in the container CRDT.

You can then get the current value by doing:

const value = myCrdtInstance.value()

Full example:

const schema = {
  a: 'g-set',
  b: 'lww-set'
}
const MyCRDT = CRDT.compose(schema)
const myCrdtInstance = MyCRDT(id)
 
myCrdtInstance.on('deep change', () => {
  console.log('new value:', myCrdtInstance.value())
})

Dynamic composition

You can use a CRDT as a value of another CRDT. For that, you should use crdt.createForEmbed(type) like this:

const array = myCRDT.create('rga', 'embedding-test', options)
 
const counter = array.createForEmbed('g-counter')
array.push(counter)
 
array.once('change', (event) => {
  console.log(array.value()) // [0]
 
  array.on('deep change', () => {
    console.log(array.value()) // [1]
  })
 
  event.value.increment()
})

Options

Here are the options for the CRDT.create and composed CRDT constructor are:

• network: a network plugin constructor. Should be a function with the following signature: function (id, log, onRemoteHead) and return an instance of Network
• store: a constructor function with thw following signature: function (id), which returns an implementation of the Store interface
• authenticate: a function that's used to generate the authentication data for a certain log entry. It will be called with the log entry (Object) and an array of parent entry ids (string), like this:

async function authenticate (entry, parents) {
  return await authenticateSomehow(entry, parents)
}

• signAndEncrypt: an optional function that accepts a value object and resolves to a buffer, someting like this:

async function signAndEncrypt(value) {
  const serialized = Buffer.from(JSON.stringify(value))
  const buffer = signAndEncryptSomehow(serialized)
  return buffer
}

(if no options.signAndEncrypt is provided, the node is on read-only mode and cannot create entries).

• decryptAndVerify: a function that accepts an encrypted message buffer and resolves to a value object, something like this:

async function decryptAndVerify(buffer) {
  const serialized = await decryptAndVerifySomehow(buffer)
  return JSON.parse(Buffer.from(serialized).toString())
}

signAndEncrypt/decryptAndVerify contract

The options.decryptAndVerify function should be the inverse of options.signAndEncrypt.

const value = 'some value'
const signedAndEncrypted = await options.signAndEncrypt(value)
const decryptedValue = await options.decryptAndVerify(signedAndEncrypted)
 
assert(value === decryptedValue)

Errors

If options.decryptAndVerify(buffer) cannot verify a message, it should resolve to an error.

Built-in types

All the types in this package are operation-based CRDTs.

The following types are built-in:

Counters

Name	Identifier	Mutators	Value Type
Increment-only Counter	g-counter	.increment()	int
PN-Counter	pn-counter	.increment(),.decrement()	int

Sets

Name	Identifier	Mutators	Value Type
Grow-Only Set	g-set	.add(element)	Set
Two-Phase Set	2p-set	.add(element), .remove(element)	Set
Last-Write-Wins Set	lww-set	.add(element), .remove(element)	Set
Observerd-Remove Set	or-set	.add(element), .remove(element)	Set

Arrays

Name	Identifier	Mutators	Value Type
Replicable Growable Array	rga	.push(element), .insertAt(pos, element), .removeAt(pos), .set(pos, element)	Array
TreeDoc	treedoc	.push(element), .insertAt(pos, element), .removeAt(pos, length), .set(pos, element)	Array

Registers

Name	Identifier	Mutators	Value Type
Last-Write-Wins Register	lww-register	.set(key, value)	Map
Multi-Value Register	mv-register	.set(key, value)	Map (maps a key to an array of concurrent values)

(TreeDoc is explained in this document)

(For the other types, a detailed explanation is in this document.)

Text

Name	Identifier	Mutators	Value Type
Text based on Treedoc	treedoc-text	.push(string), .insertAt(pos, string), .removeAt(pos, length)	String

Extending types

This package allows you to define new CRDT types.

CRDT.define(name, definition)

Defines a new CRDT type with a given name and definition.

The definition is an object with the following attributes:

• first: a function that returns the initial value
• reduce: a function that accepts a message and the previous value and returns the new value
• mutators: an object containing named mutator functions, which should return the generated message for each mutation

Example of a G-Counter:

{
  first: () => 0,
  reduce: (message, previous) => message + previous,
  mutators: {
    increment: () => 1
  }
}

Read-only nodes

You can create a read-only node if you don't pass it an options.encrypt function.

const readOnlyNode = crdt.create('g-counter', 'some-id', {
  network, store, decrypt
})
 
await readOnlyNode.network.start()

Zero-knowledge replication

A node can be setup as a replicating node, while not being able to decrypt any of the CRDT operation data, thus not being able to track state.

Example:

const replicatingNode = crdt.replicate('some-id')
 
await replicatingNode.network.start()

Interfaces

Store

A store instance should expose the following methods:

• async empty (): resovles to a boolean indicating if this store has no entries
• async put (entry): puts an arbitrary JS object and resolves to a unique identifier for that object. The same object should generate the exact same id.
• async get (id): gets an object from the store. Resolves to undefined if entry couldn't be found.
• async setHead(id): stores the current head (string).
• async getHead(): retrieves the current head.

Network

A network constructor should return a network instance and have the following signature:

function createNetwork(id, log, onRemoteHead) {
  return new SomeKindOfNetwork()
}

onRemoteHead is a function that should be called once a remote head is detected. It should be called with one argument: the remote head id.

A network instance should expose the following interface:

• async start(): starts the network
• async stop(): stops the network
• async get(id): tries retrieveing a specific entry from the network
• setHead(headId): sets the current log head

Internals

docs/INTERNAL.md

License

MIT