ECHO Database

ECHO (The Eventually Consistent Hierarhical Object store) is a peer-to-peer graph database written in TypeScript.

• Secure, P2P data replication based on CRDTs.
• No servers or central authority, all the data is with the clients.
• Connectivity with peers via WebRTC.
• Support for multiple concurrent writers.
• Collaboration on key-value objects, bodies of text, and other "custom data models".
• Support for offline writes and conflict resolution when peers rejoin the network.

Tell us what you think

Join our Discord and talk to us about the kind of database you are looking for.

Spaces

Spaces are units of sharing and access control in ECHO. They are equivalent to "collections" in a document store.

A space is an instance of an ECHO database which can be replicated by a number of peers.

A given peer is typically a part of many spaces at any given time.

There are several steps to establishing a space between peers:

1. Peer A listens on the peer network for peers intereseted in a specific invite code it generated.
2. Peer B obtains the invite code and locates the listening Peer A via the signaling network.
3. Peer A and Peer B establish a secure connection via Diffie Hellmann key exchange.
4. Peer A generates an authorization code and sends it to Peer B via another safe channel (i.e.: shows a QR code).
5. Finally, Peer B provides the authorization code back to Peer A over the new connection.

This verifies that the connection is secure, and the identities of peers are mutually confirmed.

Tip

If you're using react, DXOS provides a simple UI flow that implements generating and accepting invitations to spaces.

Next steps:

• Create or join a space in TypeScript
• Create or join a space in React

Objects

Units of data are referred to as objects (like documents or rows in other databases). Objects always belong to a space. Objects can have fields with values, and strong relationships to other objects to form trees or graphs.

Glossary

See the glossary for definitions of other terms you'll find in this guide.

How to use ECHO

• Install the appropriate npm package @dxos/client or @dxos/react-client
• Create a Client (or a ClientProvider in react)
• Set up an identity with HALO
• Create or Join a Space
• Query objects (in react)
• Create objects (in react)
• Mutate objects (in react)

Local Vault Topology

ECHO is uniquely organized to give control over information to the end-user and their devices.

Browsers isolate web apps running on different domains, and this property is used to isolate the main vault of storage to a specific domain. By default that's HALO on halo.dxos.org but developers are free to operate their own copies of HALO on their local machine (e.g. using KUBE), their local network, or any other domain.

The vault domain is responsible for holding end-user identity (keys, credentials, metadata, ..., etc.) and all ECHO data in persistent browser or disk storage. It exposes this data to applications via an API over postMessage.

A service worker and the CRDT-based architecture of ECHO enable both offline and real-time collaboration.

HALO Vault Topology Diagram

This means that when apps request the user's identity (ask to log in), they are in fact obtaining a secure identifier from the local HALO application directly, without making any network calls. Any reads and writes end up storing data in a database owned by the halo.dxos.com application, which serves as an identity wallet and data vault where specific devices or applications can be revoked from accessing user data at any time.

Note

For Node.js applications, the vault is implemented by an in-process storage engine that persists to files on disk, and is not isolated from the consuming application the way it is in browser.

Next steps

• If using react see the React guide
• Otherwise, follow the TypeScript guide