Documents

Authors create and join documents: mutable key-value stores that multiple users read from, write to, and sync with, subscribing to live updates in real time.

Document Namespaces

A document is a namespace that is uniquely identified by a keypair.

A key in a document is just a sequence of bytes. In practice keys are almost always UTF-8 strings. A value in a document is always a hash that points to a blob. Conceptually, a document looks like this when written in JSON notation:

{
  "bar": "bafkr4iebxyldaiwztn5kwt6bap5e5bnzeru5lgc64w6lns644ir6ky5soi",
  "bananas": "bafkr4ihr5vpp33v5ufos2dneywofls3gx67b5jmraxcn77odsu3yqcsohq",
  "foo": "bafkr4ic3ywkoq5k2bn7kaiz6lovehgkpfqk4kwstepcbs7pw256dtxutme",
  "slashes/are/also/ok": "bafkr4ic3ywkoq5k2bn7kaiz6lovehgkpfqk4kwstepcbs7pw256dtxutme",
  "so.are.dots": "bafkr4ic3ywkoq5k2bn7kaiz6lovehgkpfqk4kwstepcbs7pw256dtxutme",
  // ...
}

An entry in the document is a key-value pair. When an author writes an entry they first create a blob, then use the hash of the blob as the value, then pick a label to use as the key.

Authors & Permissions

Authors are users who have write access to a document. Every author has a keypair that represents their identity. The public side of a keypair identifies the user & validates the edits they make to the document, the private side of the keypair is used to sign edits.

Read access to a document is granted by sharing the document public key. Write access to a document is granted by sharing the document private key.

Document Identifiers

Documents are referred to within iroh by their document identifier or DocID. They look like this:

ktrygcpxealfdtfmohw66nb2keivu52opk65cyj4j7jy7wior7ea

Document IDs are base32-lower serialization of the public key of the document. They do not change as the document changes.

Synchronizing Documents

When an author wants to sync with a document, they first find the document's current state, then they perform a range-based set reconciliation to fill in any changes in the keyspace.

When two nodes want to sync, they perform a range-based set reconciliation to fill in any changes in the keyspace. Any node with the read key (document ID) can read & sync the latest state of the document. Having the read key denotes read access. All entries in the document are double-signed, once with an authorID (keypair) and the write key of the document.

After this synchronization step, we know the hashes of all the content the document references. By default iroh documents will fetch all content associated with the document.

Document PubSub

Every document is its own pubsub swarm, keyed by the public key of the document. Iroh pubsub swarms implement techniques described in HyParView & PlumTree to keep a bounded number of active nodes any one node in the swarm needs to push to.

As authors write to a document, they publish these changes as pubsub messages that other peers pick up on & apply to their local state.

Storage

Iroh docs can be used with in-memory or file-system based storage. The store is used to keep track of all relevant metadata necessary for management of documents, authors and keys. The contents associated to keys is managed by iroh-blobs, which stores data in a optimized, content-addressed manner. Data can be imported and exported out of Iroh's storage using doc import and doc export.

API

Documents can be manipulated and queried using the docs API, also available via our various official SDKs.