Architecture

Velum has six layers. Each one knows just enough to do its job and nothing more.

The layers

Layer Sees Doesn't see
App Your messages in plain text, your contacts, your recovery phrase Nothing about other users
Envelope An encrypted message for one specific device Never leaves the phone unsplit
Fragments Equal-size pieces, with their receipt hash Content, sender, real size
Nodes Opaque fragments, today's mailboxes, receipts Who sends, who receives, what it says
Gateway Connections and the JSON frames it forwards Content; identities never travel in plain text
Chain Payments, tokens, orders, receipts, rewards Messages and who talks to whom

App

The app generates the recovery phrase, derives the keys (identity, wallet, mailbox) and creates a device key that never leaves the phone. It stores chats in SQLite encrypted with SQLCipher; the key lives in the Keychain with WHEN_UNLOCKED_THIS_DEVICE_ONLY, so it isn't included in iCloud backups.

When you send, the app:

  1. Signs the content with the device key.
  2. Seals it for each of the recipient's devices and for your other devices (so your history is the same everywhere).
  3. Pads each envelope to a fixed size and splits it into 5 fragments.
  4. Sends each fragment through a different node, to the recipient's mailbox for the day.

Envelope

An envelope is a message encrypted for one device. Format:

[1 byte version = 2][32 B ephemeral X25519 key][1088 B ML-KEM-768 kemCt][24 B nonce][ciphertext]

Outside the envelope there is nothing that identifies the sender (sealed sender). Inside are the content signed by the sending device, the sender's identity and the signature that binds that device to that identity. Details in Cryptography.

Fragments

Each envelope is padded to a bucket (2 KB, 8 KB, 32 KB, 128 KB, 512 KB, 2 MB or 8 MB) and split with Reed–Solomon 3 of 5: any three pieces are enough to rebuild it. Each piece carries the SHA-512 hash of its receipt secret. Details in Fragments and receipts.

Nodes

A node is a program running on a community computer. It does three jobs:

  • Open bridges. A bridge is a route the node opens and keeps up between senders and mailboxes: it accepts pieces (it's their carrier), keeps them and delivers them when the owner opens the mailbox (it's their courier).
  • Produce blocks. Full nodes take turns building blocks, with a target of 2 seconds per turn; the actual pace is measured.
  • Discover VEL. Every epoch the node publishes an aggregated claim for its bridges' work; once it's checked by sampling, the node discovers its share of the epoch's VEL.

There are full nodes (a computer, they produce blocks) and light nodes (the phone app, they only deliver fragments). For each piece, a public lottery picks 3 candidates and the app uses the closest one. See Run a node.

Gateway

The public gateway (wss://velum.consultorabim.com/hub) is the meeting point: nodes check in by signing a greeting, apps send RPC requests and the explorer receives blocks live. The gateway only forwards frames; it has no key that would let it read anything.

To resist blocking there are several gateways on different domains with ECH, nodes connect to each other directly (ws://host:7420/ws) and each node announces its address on the chain (endpoint). See Resisting blocks.

App  ──ws──▶ Gateway /hub?role=client ──▶ Chosen node (RPC)     or direct: ws://node:7420/ws?role=client
Node ──ws──▶ Gateway /hub?role=node   ◀─▶ other nodes            and node to node: ?role=node
Web  ──ws──▶ Gateway /hub?role=watch  ◀── live blocks and stats

Chain

A blockchain of its own, with no external dependencies. It stores:

  • Balances in VEL and in tokens, and each wallet's nonce.
  • Node sign-ups, their tier and their delivery credits.
  • Work claims (Merkle roots), sampling checks and rewards.
  • The oracle price for each epoch and the Network Reserve balance.
  • Public aliases (name.register).
  • Tokens, token pools for nodes, market orders and trades.
  • Attested devices (only the hash of their key, with no identity).

It never stores messages, contacts, device lists or chat identities. See Consensus and blocks.

What is kept apart, and why

Separation Why
Identity key ≠ wallet key So nobody can link your chats to your payments.
Each device has its own device key Remove a device without rebuilding the account.
A different mailbox each day and per device So nodes can't follow anyone over time.
Receipts with no signature or address So discovering VEL doesn't reveal the recipient.