Concepts Specifications API Downloads
ConceptsStore

Store

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

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

Accounts

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 in-queue 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 or envelope

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.

To receive messages, public stores accept an envelope object, which is put onto the store before adding the hash:

add OK Envelope bytes Box label Account hash

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 protocols offer addition and removal as a single account modification function.

Access rights

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

get object everybody
put object registered actors
list box in-queue 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
in-queue 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.

Errors

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.

Concurrency

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

Add requests must behave atomically. If a list request sees the 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 close accounts.