A Condensation store holds a set of immutable objects, and a set of accounts with mutable boxes. It provides 5 functions to access the object store and the boxes.

put object get object list add ... remove Objects Accounts ...


The object store keeps a set of hash → object pairs (usually structured as a hash table) and exposes 2 functions.

Get object

getobject Object hash Object bytes Not found

Given a hash, this function returns the corresponding object, or a not found message.

Put object

putobject Object bytes OK

Stores an object. The object must exist when the function returns.

For efficiency, most protocols often offer an additional function to check for object existence prior to uploading its contents:

bookobject Object hash OK Not found


The account store keeps a set of accounts. An account is identified by the hash of the actor's public key object and consists of 3 boxes:

A box stores a set of hashes, each of which points to an existing envelope object in the object store.

Public and private box typically hold a 1-2 hashes, while the message box may contain thousands of hashes.

The account store exposes 3 functions.

List box

list Box label Set of hashes Account hash

Returns the set of hashes currently stored in the box. Each hash points to an envelope object. If the account or box does not exist, or has never been used before, an empty list is returned.

Add hash

add OK Envelope hash Box label Account hash

Adds a hash to a box. The hash is added before the function returns, but a concurrent removal request may remove it before the function returns. A store may refuse to add the hash if the corresponding object does not exist, or is not an envelope.

Remove hash

remove Envelope hash OK Box label Account hash

Removes a hash from a box. The function may return immediately, and defer the actual removal. An actor may only remove hashes from its own boxes, or envelopes that he sent.


Many stores offer a modify operation to put objects, add hashes, and remove hashes in a single request.

Access rights

A public store should authenticate actors, and enforce the following access rights:

get object everybody
put object registered actors
list box message box any actor mentioned on the account's public card, or everybody¹
private box any actor mentioned on the account's public card, or everybody¹
public box everybody
add hash
or envelope
message box everybody²
private box authenticated actor
public box authenticated actor
remove hash any sender or recipient mentioned on the envelope, and any actor mentioned on the account's public card
  1. Granting access to everybody does not undermine data security, but unnecessarily leaks side information about the user's behavior.
  2. For non-registered actors, the envelope size is usually limited to 16 KiB, and submissions may be rate-limited.


Any request may fail before or after its execution. Typical reasons for failure include:


Concurrent requests may be executed (and completed) in any order.

Add requests must behave atomically. If a list request sees the new object hash, all following list requests must see the hash as well, until it is removed.

Remove requests provide no such guarantees. Hashes may disappear in any order, and even reappear sporadically.

Garbage collection

At any time, a store may remove objects that are not referenced (directly or indirectly)

General-purpose stores should keep uploaded or booked objects with all their descendants for at least one hour. Stores for specific purposes may use shorter timeouts.

Stores are not obliged to carry out garbage collection in a regular fashion, or within a certain time.

Additional functions

The above functions are sufficient to run the Condensation protocol. A store implementation may offer additional functions, however, e.g. functions to create or remove accounts.