Core Concepts

Understand the fundamentals.

The vocabulary you need to read the rest of the docs.

Convergent encryption

Every file is encrypted with a key derived deterministically from its plaintext (HMAC-SHA256 + AES-256-GCM with the nonce derived from the same hash). Property: identical input → identical ciphertext → automatic deduplication across users + retransmission safety.

The trade-off: an attacker who already has a candidate plaintext can verify whether you've stored it. For most threat models (your photos, your documents) that's fine; for "is this person storing X" attacks specifically you'd want random-nonce mode (planned, not shipped).

Replication factor

Each vault has replication_factor: N. The mesh keeps trying to land each block on at least N reliable peers through periodic gossip. RF is achieved per-block, not per-vault — small files don't pay the cost of large ones.

A reliable node is one whose config declares reliable: true. Phones default to false — they help seed but don't count.

Trusted vs. untrusted

Trust = "does this node have the vault key". Untrusted nodes happily store ciphertext blocks and participate in replication; they never see plaintext. This is what lets a €5/month VPS be redundancy without needing to trust the provider.

Vaults, blocks, hash-chains

• Vault = a name + a key + a policy (RF, storage path, type).
• Block = a chunk of ciphertext addressed by SHA-256. Sizes: ≤ 512 KiB for small files, 4 MiB for large.
• Hash-chain versioning = each new version of a file carries a parent_hash pointer to the previous version. Same file edited on two nodes simultaneously → the mesh detects the fork on next gossip.

Mesh topology + gossip

There is no central directory. Every node holds a partial view of the mesh, gossipped via the /meshhold/hello/1.0 protocol. A first handshake brings back every other node currently online — any of them can be your bootstrap on the next reconnect.

Three encryption layers

1. Swarm key — 256-bit shared secret; without it, nodes can't even open a libp2p connection.
2. Per-connection Noise session key — fresh on every TCP stream, forward-secret, ChaCha20-Poly1305 AEAD.
3. Per-vault / chat / tunnel / agent content key — independently shareable; one capability doesn't unlock another.

See the diagram on the home page for the visual.