A Condensation store holds a set of immutable objects, and a set of accounts with mutable boxes. It offers 5 functions to access the object store and the boxes.
An object consists of a list of hashes and data:
H is a 4-byte big-endian integer denoting the number of hashes. Each following hash is a reference to another object. The data is simply a sequence of bytes, and usually encrypted.
Objects are identified by their SHA-256 hash:
Hashes are always 32 bytes long, and sometimes written as 64 hexadecimal digits. Through the hash list, an object may span a tree:
Since a single hash may refer to an arbitrarily large tree (with an arbitrarily large amount of data), the state of some data is entirely defined by its tree hash (root object hash). Such tree hashes are stored in boxes.
A box holds a small number of entries. A box entry consists of:
- a hash
- an optional store URL
Store URLs are used to point to objects on other stores.
An account consists of three boxes:
- The public box points to the users's public information. It should contain a single reference only.
- The private box points to the user's private data, and is writable by the user only. Implementations may choose to keep it publicly readable.
- The in-queue box is publicly writable. Other users can post messages here.
Object store interface
An object store keeps a set of hash → object pairs, usually structured as a hash table, and exposes 2 functions.
Given a hash, this function returns the corresponding object, or a not found message.
This function stores an object. The object must exist when the function returns. Depending on the protocol, one or both of the above versions of this function may be available.
Many stores offer an additional function to check for object existence prior to upload its contents:
Account store interface
The account store keeps a set of accounts with 3 boxes each (in-queue, private, public), and exposes 3 functions.
This function returns the set of references currently stored in the box. Each reported reference is either a hash, or an object URL. If the account or box does not exist, or has never been used before, an empty list is returned.
Add object reference
This function adds an object reference to a box. The reference must be added (or exist already) before the function returns. It however may not exist any more when the function returns, as a concurrent removal request may have deleted it.
Remove object hash
This function removes all object references with a given hash from a box. The function may return immediately, and defer the actual removal.
For increased efficiency, addition and removal are usually implemented as a single account modification function.
Any request may fail for technical reasons, such as storage system failures, full disks, or network errors. Note that requests may fail before or after their execution. Subsequent requests may again succeed.
Concurrent requests may be executed (and completed) in any order.
Add requests must behave atomically. If a list request sees the object reference, all following list requests must see the reference as well until its removal.
Remove requests provide no such guarantees. Affected object references may disappear one-by-one (in any order), and even reappear.
The above functions are sufficient to run the Condensation protocol. A store implementation may expose additional functions, however, e.g. functions to create or close accounts.
At any time, a store may remove objects that are not referenced (directly or indirectly) through any box. Stores should however avoid deleting objects created recently, as they may have been uploaded, but not referenced in any box yet.
When and how garbage collection is performed is up to the implementation.