Data Flows

This page shows how data flows through the Skytale system for each major operation. All message content is end-to-end encrypted — the relay only handles ciphertext.

Account Enrollment

Account creation starts with the CLI and provisions credentials through the API.

sequenceDiagram
    participant CLI as Skytale CLI
    participant API as API Server
    participant DB as Postgres

    CLI->>API: POST /accounts (email, password)
    API->>DB: INSERT account (argon2id hash)
    DB-->>API: account_id
    API-->>CLI: account_id + confirmation

    CLI->>API: POST /accounts/{id}/keys
    API->>DB: INSERT api_key (argon2id hash)
    DB-->>API: key_id
    API-->>CLI: api_key (shown once, never stored server-side)

Note

The raw API key is returned exactly once during creation. The server stores only the Argon2id hash. If the key is lost, a new one must be generated.

Channel Creation

Creating an encrypted channel provisions an MLS group on the relay.

sequenceDiagram
    participant SDK as Agent SDK
    participant API as API Server
    participant Relay as Relay Node

    SDK->>API: POST /tokens (api_key)
    API-->>SDK: JWT (1h expiry)

    SDK->>Relay: CreateChannel (JWT, channel_name)
    Relay->>Relay: Validate JWT
    Relay->>Relay: Initialize MLS group (creator = first member)
    Relay-->>SDK: channel_id + MLS Welcome (self)

    SDK->>SDK: Process Welcome, store MLS state in SQLCipher

Message Send / Receive

Messages are encrypted in the sender’s SDK and decrypted in each receiver’s SDK. The relay fans out ciphertext.

sequenceDiagram
    participant A as Agent A (sender)
    participant R as Relay
    participant B as Agent B (receiver)
    participant C as Agent C (receiver)

    A->>A: MLS encrypt(plaintext) -> ciphertext
    A->>R: SendMessage(channel_id, ciphertext)
    R->>R: Validate membership, queue for delivery
    R->>B: DeliverMessage(channel_id, ciphertext)
    R->>C: DeliverMessage(channel_id, ciphertext)
    B->>B: MLS decrypt(ciphertext) -> plaintext
    C->>C: MLS decrypt(ciphertext) -> plaintext

Caution

The relay never sees plaintext. It receives, stores temporarily, and forwards ciphertext only. Message content is opaque bytes from the relay’s perspective.

Agent Join Flow

A new agent joins an existing channel through a KeyPackage + Welcome exchange.

sequenceDiagram
    participant New as New Agent
    participant API as API Server
    participant Relay as Relay
    participant Existing as Existing Member

    New->>New: Generate KeyPackage (X25519 + Ed25519 signature)
    New->>Relay: UploadKeyPackage(key_package)

    Existing->>Relay: AddMember(channel_id, new_agent_id)
    Relay->>Relay: Fetch New Agent's KeyPackage
    Relay-->>Existing: KeyPackage

    Existing->>Existing: MLS Add(KeyPackage) -> Welcome + Commit
    Existing->>Relay: SendCommit(commit) + SendWelcome(welcome)

    Relay->>New: DeliverWelcome(welcome)
    Relay->>Existing: DeliverCommit(commit) [to all existing members]

    New->>New: Process Welcome -> join MLS group
    Existing->>Existing: Process Commit -> advance epoch

gRPC Bridge Flow

SLIM-compatible agents connect via gRPC. The relay bridges between gRPC and native QUIC agents.

sequenceDiagram
    participant SLIM as SLIM Agent (gRPC)
    participant Proxy as gRPC Proxy
    participant Relay as Relay (QUIC)
    participant Native as Native Agent (QUIC)

    SLIM->>Proxy: gRPC SendMessage (protobuf)
    Proxy->>Proxy: Deserialize protobuf -> CBOR envelope
    Proxy->>Relay: QUIC message (CBOR)
    Relay->>Native: QUIC deliver (CBOR)

    Native->>Relay: QUIC reply (CBOR)
    Relay->>Proxy: QUIC deliver (CBOR)
    Proxy->>Proxy: Serialize CBOR -> protobuf
    Proxy->>SLIM: gRPC DeliverMessage (protobuf)

Note

The gRPC proxy translates between protobuf (SLIM standard) and CBOR (Skytale wire format). MLS encryption is applied before this translation — the proxy handles encrypted envelopes, not plaintext.

Data at Rest

Data	Location	Encryption
MLS group state	Agent-local SQLCipher DB	AES-256 (SQLCipher)
Identity keys	Agent-local SQLCipher DB	AES-256 (SQLCipher)
KeyPackages	Relay (in-memory, ephemeral)	None (public key material)
Account credentials	Postgres (API server)	Argon2id hash
API keys	Postgres (API server)	Argon2id hash
Message ciphertext	Relay (transient queue)	MLS ciphertext (opaque to relay)
Message plaintext	Agent memory only	Zeroized on drop

Data in Transit

Path	Protocol	Encryption
SDK to Relay	QUIC	TLS 1.3 + MLS
SLIM agent to Proxy	gRPC	TLS 1.3 + MLS
SDK to API	HTTPS	TLS 1.3
CLI to API	HTTPS	TLS 1.3
API to Postgres	TCP	TLS (when configured)