Concepts & data model

The data model has four layers. It is worth ten minutes now, because every endpoint is shaped by it and none of it will make sense otherwise.

Sector

The unit of storage a provider deals in: 4 MiB. Every sector is addressed by its Merkle root, a 32-byte hash. That root is how you ask for it back and how integrity is verified — a provider that returns different bytes returns bytes that do not hash to the root you asked for, and your client rejects them.

Shard

One erasure-coded fragment of your data, stored as one or more sectors on one provider. With the default geometry a slab has 15 shards: 10 data, 5 parity. Shard size is ceil(sliceSize / minShards).

Slab

A slab is one erasure-coded stripe: a set of shards that decode together. It records:

A slab's ID is a content-addressed digest of its parameters — not a random identifier, and notably not a hash of the provider set. That is deliberate: repair can move a shard to a different provider without the slab ID changing, so your object references stay valid across repairs you never see.

Object

An object is an ordered list of slab segments, plus wrapped key material and signatures:

Because an object is a list of slab segments, several small objects can share a slab, and one large object can span many. Deduplication and packing are consequences of the model rather than features bolted onto it.

What the object model does not contain

There is no filename, no path, no directory, no content type, and no cleartext size. These are not fields we decline to populate; the columns do not exist.

This is the single most important thing to understand before you integrate. If your application needs a file browser, you build the naming layer:

// Your metadata blob, encrypted by you, opaque to us.
const metadata = {
  name: 'quarterly-report.pdf',
  contentType: 'application/pdf',
  size: 8_431_233,
  path: '/reports/2026/q1/',
  createdAt: '2026-04-02T09:14:00Z',
}
// encrypt(metadata) → encryptedMetadata

To list a directory you decrypt the metadata of the objects you know about, which means you keep a local index. The trade is explicit: you take on an index, and in exchange no one — including us, including anyone who compels us — can enumerate what you have stored or infer anything from its names.

Account

Your account is your credential — specifically the ed25519 public key you were issued. There is no separate account object, no username, and no email in the storage path.

Every slab and object is bound to the account that created it. A request signed by a different credential is refused with 403, not silently emptied. Provisioning a new credential creates a new and entirely separate namespace; there is no notion of a credential belonging to an account that owns objects.

How the layers stack

Object  "report.pdf"        ← your metadata says so; we do not know
  ├── slab A, offset 0,       length 4194304
  └── slab B, offset 0,       length 4236929
                 │
                 └── Slab B: minShards 10, 15 sectors
                       ├── shard  1 → provider ed25519:a1b2… root 9f3c…
                       ├── shard  2 → provider ed25519:c3d4… root 22ab…
                       ├── …
                       └── shard 15 → provider ed25519:e5f6… root 7c1d…

Repair

Slab health is scanned continuously. When a shard's provider goes away, the slab is queued for repair: the shard is reconstructed from parity and written to a replacement provider, and the slab record is updated in place. The slab ID does not change, so nothing referencing it breaks.

You do not trigger repair, pay for it as an event, or need to read the data for it to happen.

Encoding conventions