CROWDs

Conflict-free Reinterpretable Ordered Washed Data (Secure) - Delta based CRDT with additional abilities.

Key Properties

Conflict-free

Any states can be merged without conflicts.
Convergent merge.
Strong Eventual Consistency.
Total Available Real-Time Causal Consistency.
Merge result is independent of merge order (except auth units).
Merge is semilattice.

Reinterpretable

Same state can be reinterpreted as any Type (weak typing).
Type of data can be changed dynamicaly without data migration.
Cross-merge between different types is available.

Ordered

Every data have a stable place in the document.
Wiped data inside some Head stays tombstone to hold place.
Interleaving-free.

Washed

Wiped data comptely removed from state.
Past state can't be reproduced. Snapshots/layers/changelog should be used for that.
Garbage collection isn't required.
But metadata size (binary, with signs) ~28x of user data size (~14x without signs).

Data

All deltas are idempotent.
Every token is just one unit.
Delta is simply slice of full state (array of units).
Deltas can be merged together to reduce transmit size.

Secure

Every unit is crypto signed separately.
Every peer checks signs and rights and rejects incorrect units.
Every unit can be encrypted (not yet).
Conflict-free merge without decrypt.
Merging doesn't invalidate signs.
Security features can be ommited if decentralization isn't required.

Real World Usages

$hyoo_page - decentralized real-time wiki.
$hyoo_talks - decentralized secure messanger.
$hyoo_draw - infinity collaborative whiteboard.
$hyoo_sketch - fast UI mockups.
BenZen - Conflict-Free Version Control System

Articles

Consistent about Consensus.
The Whole Point of Conflict-Free Data Tyes (Coming soon).
CROWD - Secure Universal CRDT (Coming soon).

Vocabulary

World - Whole state as graph of Lands.
Node - A single subtree which represented by few Units with same Self in different Heads.
Unit - Minimal atomic unit of data with metadata. Actually it's edge between Nodes. And it's extended CvRDT LWW-Register.
- Land - Document direct graph which consists of (real) Units and (virtual) Nodes over them and syncs entirely.
- Self - Node id
- Head - Parent Node id.
- Prev - Previous Node id in the siblings list.
- Next - Next Node id in the siblings list.
- Auth - Global unique identifier of independent actor.
- Time - Monotonic time as count of 100ms intervals from Aeon start.
- Aeon - number of 7-year epochs from ~2022-08-04 (not yet).
- Data - Any JSON or Binary data. Size is limited by 32KB.
- Sign - Crypto sign of whole Unit data.
- kind - Type of unit (👑 grab, 🏅 give, 🔑 join, 📦 data) with different acceptance criterias.
- group - Priority of synchronization (auth, data).
Level - Access level (law, mod, add, get).
Peer - Any actor who have private key to make and sign Units.
- Lord - Any Peer who have law level for Land.
- King - Peer with same id as Land. He has law level in that Land by default.
- Knight - Temporary King to grab Land and grant level for current Peer and/or for all Peers.
Home - Land where Peer is King (with same id).
Delta - Difference of two Land states as list of Units.
Clock - Vector clock. Dictionary which maps Peer to Time.
Token - Minimal meaningfull part of text (space + single word / spaces / punctuation etc).
Point - Place inside Unit. Usefull for caret position.
Range - Range between two Points. Usefull for selection.
Offset - Count of letters from beginning.
Seat - Position in the list.
Channel - Geter/Setter method. foo() - read. foo(123) - write and return written.

Internals

State/Delta Format

type Unit = Readonly<{
    land: int62
    auth: int62
    head: int62
    self: int62
    next: int62
    prev: int62
    time: int31
    data: json | bin
    sign: bin64
}>

type State = Unit[]
type Delta = readonly Unit[]

Internally Units may be stored in RDBMS. Example:

CREATE TABLE units (
	land int(8),
	auth int(8),
	head int(8),
	self int(8),
	next int(8),
	prev int(8),
	time int(4),
	data json,
	sign byte(64),
)

Single Unit structure

Primary key for Units: [ Land, Head, Self ]

Sync Flow

Delta

Delta is array of 8-byte aligned binary serialized Units of same Land ordered by Aeon+Time.

Unit

Unit contains data, it global position, time of creation, authorship and sign of all of this.

Clocks

Contains last seen Times for each Peer+Group of already known Units.

Data Types Representation

Atomic CROWD Register

Single value store. Just CvRDT LWW-Register. Value is any JSON or Binary data with size <= 32KB.

$hyoo_crowd_reg

value( next?: unknown ) Channel for raw value. Returns null by default.
bool( next?: boolean ) Channel for boolean value. Returns false by default.
numb( next?: number ) Channel for number value. Returns NaN by default.
str( next?: string ) Channel for string value. Returns "" by default.

CROWD Struct

Struct is completely virtual thing. No one Unit is stored for it. Only for field values (except it's structs too, etc).

Lookup agorithm

Make derived Head by formula:

field_head = hash_62bit( field_name, struct_self )

So each Peer writes to the same Node when uses the same key.

$hyoo_crowd_struct

sub( key: string ) Returns inner Node for field name.
yoke( key: string, Node, king_level, base_level ) Makes or reuse Land which Self is stored inside register.

CROWD Ordered List

Properties

New Unit is created for every item.
Left precedence. Position of item relies on left item, then right.
No interleaving. Sequence of left-to-right inserted items will stay together after merge.
Removed item is remain as tombstone for ordering purposes.

Ordering Algorithm

Input: Head value.
Select all Units with given Head.
Make queue as sorted found Units by Time asc, Peer asc.
Make empty list for result.
Iterate over all queue while it isn't empty.
- If Prev == 0, then place it at the begin.
- If Prev != 0, then locate existen Prev in the result list.
  - If Prev is located, place after that.
  - if Prev isn't located, then check Next:
    - If Next == 0, then place it at the end.
    - If Next != 0, then locate existen Prev in the result list.
      - If Next is located, place before that.
      - if Next isn't located, then skip unit and proceed followed.
- If unit is placed remove it from queue and start from begin of queue.

$hyoo_crowd_list

list( next?: unknown[] ) Channel for list of raw values. Uses insert to replace content.
set( next?: unknown[] ) Channel for list of unique raw values.
insert( next?: unknown[], from?: number, to?: number ) Replaces range of items with reconciliation. Appends to the end when range isn't defined.
move( from?: number, to?: number ) Moves item to another seat.
cut( seat: number ) Removes item by seat.
has( val: unknown ) Checks for value existence.
add( val: unknown ) Adds value if doesn't exist.
drop( val: unknown ) Removes value if exists.

CROWD Ordered Dictionary

It's both Struct and List:

As list it contains keys.
As struct it stores every key in Unit with derived Self. So, every key is Node for value.

$hyoo_crowd_dict

keys() Channel for list of keys.
sub( key: string, Node ) Returns inner Node for key.
has( val: unknown ) Checks for key existence.
add( val: unknown ) Adds key if doesn't exist.
drop( val: unknown ) Removes key if exists.

CROWD JSON

It's recursive version of Dictionary. Special values which marks inner structures:

{} - inner JSON.
[] - inner List.

$hyoo_crowd_json

json( json ) Channel for JSON.

CROWD Plain Text

Under the hood, String is just List of Tokens. So, entering word letter by letter changes same Unit instead of creating new. Text is the List of Strings which represents multiline text.

Properties

Can be simply bound to native <textarea> with real-time synchronization.
Merge never produces unreadable token value. Only one of valid (LWW).
No interleaving. The typed text will not be interrupted after merging.
Weight of unsecure CROWD representation of text 3x..9x of raw text snapshot (and 11x..27x for secure).

Online sandbox

Write Algorithm

Input: new text and range of existen text.
Locate Tokens which relate to the range.
Before and after new text append substrings of first and last tokens which should be untouched.
Split new text using tokenizer.
Reconciliate list of tokens unsing the List insertion algorithm.

$hyoo_crowd_text

str( next?: string ) Channel for String representation. Uses write to replace content.
text( next?: string ) Channel for Text representation.
selection( peer, next?: [ number, number ] ) Channel for selection Offsets of given Peer inside this Text. Stored inside Peer Home Land with anchoring to most inner token.
write( next?: string, from?, to? ) Replaces range of String with reconciliation. Writes to the end when range isn't defined.

CROWD Rich Text

Under the hood, tokens are stored in the same form as in plain text. There may be elements between them in form ["div"], which can contain the same content. Every token is represented as SPAN. Every DOM element has id equal to Self. This id is using to reuse existing Units and track Nodes moving.

$hyoo_crowd_dom

dom( next?: Element | DocumentFragment ) Channel for DOM representation of subtree.
html( next?: string ) Channel for XHTML serialization of DOM.

CROWD Document

Delta Algorithm

Input: Clocks, received from Peer.
Iterate over all Unit in Land.
- Skip Units which Time less then Clock Time for same Peer.
Return all remainig Units ordered by Time.

Example with SQL:

SELECT *
FROM Unit
WHERE
	NOT( peer = 1 AND time <= 123 )
	AND NOT( peer = 2 AND time <= 456 )
	AND NOT( peer = 3 AND time <= 789 )
	...
ORDER BY
	time ASC,
	peer ASC

Apply Algorithm

Input: list of Units.
Iterate over Units from Delta.
- Locate Unit from Land with same Head and Self.
- If Unit doesn't exists, add Unit to Land.
- If Unit exists and Time of new Unit is greater, replace old by new.
- If Unit exists and Time of new Unit is same, but Peer is greater, replace old by new.
- Otherwise skip this Unit.

$hyoo_crowd_land

chief Returns chief Node with Head = 0.
delta( clocks? ) Returns delta between past clock and now.
apply( delta ) Merges delta to current state.
fork( peer ) Makes independent clone with another Peer for testing purposes.

Reinterpretations

need update

✅ Expected behaviour.
⭕ Unexpected but acceptable behaviour.
❌ Unacceptable behaviour in most cases.

What\As	Atom	Struct	List	Dictionary	Text	DOM
Atom	✅ Same	⭕ Nullish fields	✅ As single item	✅ As key	✅ String as tokens, other ignored	✅ String as tokens, other ignored
Struct	⭕ first field value	✅ Same	⭕ Field values	❌ Field values as keys	⭕ Empty	⭕ Empty
List	⭕ fist item	⭕ Nullish fields	✅ Same	✅ Items as keys	⭕ Strings as tokens, other ignored	⭕ Items as spans
Dictionary	⭕ first key	✅ keys values as fields values	✅ Keys	✅ Same	✅ Keys as tokens	✅ Keys as tokens
Text	❌ first token	⭕ Nullish fields	✅ Tokens	❌ Tokens as keys	✅ Same	✅ Tokens as spans
DOM	❌ first token	⭕ Nullish fields	✅ Top level items	❌ Tokens as keys	⭕ Text from top level tokens	✅ Same

Usage Example

// // Usage from NPM. Isn't required in MAM.
// import {
//   $hyoo_crowd_land,
//   $hyoo_crowd_reg,
//   $hyoo_crowd_list,
//   $hyoo_crowd_text,
// } from 'hyoo_crowd_lib'

// Create document
const base = new $hyoo_crowd_land;

// Make independent forks for testng
const alice = base.fork({ id: '1_1' });
const bob = base.fork({ id: '2_2' });
const carol = base.fork({ id: '3_3' });

// Twice change register named "foo"
alice.chief.sub("foo", $hyoo_crowd_reg).str("A1");
alice.chief.sub("foo", $hyoo_crowd_reg).str("A2");

// Change register named "foo"
// Then converts it to sequence and insert some values
bob.chief.sub("foo", $hyoo_crowd_reg).str("B1");
bob.chief.sub("foo", $hyoo_crowd_list).insert(["B2", "B3"]);

// Replace text named "foo"
carol.chief.sub("foo", $hyoo_crowd_text).str("C1 C2");

// Make deltas
const alice_delta = alice.delta(base.clock);
const bob_delta = bob.delta(base.clock);
const carol_delta = carol.delta(base.clock);

// Cross merge all of them
alice.apply(bob_delta).apply(carol_delta);
bob.apply(alice_delta).apply(carol_delta);
carol.apply(bob_delta).apply(alice_delta);

console.log(
  ["A2", "C1", " C2", "B1", "B2", "B3"],
  alice.chief.sub("foo", $hyoo_crowd_list).list(),
  bob.chief.sub("foo", $hyoo_crowd_list).list(),
  carol.chief.sub("foo", $hyoo_crowd_list).list()
);

Sandbox

Comparison of CRDT Libraries

	$hyoo_crowd	Automerge	YJS	delta-crdt
Approach	delta-state	op-log	delta-state	delta-state
Garbage Collection	Doesn't required	Stores full history	Enabled by default	❓
Changes signing	✅ Support	❌	❌	❓
Merge without decrypt	✅ Support	❌	❌	❓
Gzipped Bundle Size	15 KB	46 KB	24 KB	43 KB
Sequence: 500 Push + 500 Shift Perf	17 ms	420 ms	21 ms
Sequence: 500 Push + 500 Shift Mem	84 KB	986 KB	3.84 KB
Text: 500 Append + 500 Crop Perf	21 ms	480 ms	18 ms
Text: 500 Append + 500 Crop Mem	86 KB	1_080 KB	5 KB

Name		Name	Last commit message	Last commit date
Latest commit History 405 Commits
.github/workflows		.github/workflows
app		app
blob		blob
clock		clock
counter		counter
diagram		diagram
dict		dict
dom		dom
fund		fund
json		json
land		land
lib		lib
list		list
logo		logo
node		node
peer		peer
refs		refs
reg		reg
struct		struct
text		text
time		time
tokenizer		tokenizer
unit		unit
world		world
.gitattributes		.gitattributes
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md

License

hyoo-ru/crowd.hyoo.ru

Folders and files

Latest commit

History

Repository files navigation

CROWDs

Key Properties

Conflict-free

Reinterpretable

Ordered

Washed

Data

Secure

Real World Usages

Articles

Vocabulary

Internals

State/Delta Format

Single Unit structure

Sync Flow

Delta

Unit

Clocks

Data Types Representation

Atomic CROWD Register

$hyoo_crowd_reg

CROWD Struct

Lookup agorithm

$hyoo_crowd_struct

CROWD Ordered List

Properties

Ordering Algorithm

$hyoo_crowd_list

CROWD Ordered Dictionary

$hyoo_crowd_dict

CROWD JSON

$hyoo_crowd_json

CROWD Plain Text

Properties

Online sandbox

Write Algorithm

$hyoo_crowd_text

CROWD Rich Text

$hyoo_crowd_dom

CROWD Document

Delta Algorithm

Apply Algorithm

$hyoo_crowd_land

Reinterpretations

Usage Example

Comparison of CRDT Libraries

Benchmarks

Sequence: Push + Shift

Chrome 104

FireFox 104

Text: Append + Crop

Chrome 104

FireFox 104

crdt-benchmarks

Support the Project

About

Topics

Resources

License

Stars

Watchers

Forks

Sponsor this project

Contributors 3

Languages