# mystenlabs/seal architecture

> Architecture diagram of the GitHub repository mystenlabs/seal, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mystenlabs/seal
- Repository: https://github.com/mystenlabs/seal

## Overview

##### Project Type and Purpose
- Seal is a decentralized secrets management (DSM) service. It allows encryption of sensitive data using secret sharing mechanisms and controls access through the Sui blockchain.
- It combines components for on-chain (Move packages, Sui access control) and off-chain (cryptography libraries, key server, cli tools) operations to realize secure encryption/decryption workflows with threshold key-server setups.

##### Main Components from the File Structure
a. Crypto Library (crates/crypto):
- Contains cryptographic primitives, including ElGamal, GF256, IBE, polynomial operations, threshold secret sharing (tss) and others.
- This module is clearly foundational for all encryption/decryption functions.

b. Key Server (crates/key-server):
- Implements the off-chain service that validates access control via Sui and generates identity-based private keys.
- Contains subdirectories for testing and error handling, and exposes endpoints, cache management, and metrics tracking.

c. Seal CLI (crates/seal-cli):
- A command-line interface offering a way to interact with the protocol (e.g., to drive encryption workflows).

d. Frontend Examples (examples/frontend):
- Contains a demo full-stack integration implemented in TypeScript/React.
- Illustrates how applications would interact with Seal key servers to implement access control policies.

e. Move packages (examples/move, move/patterns, move/seal):
- Provide Move scripts or packages which show how applications integrate with Sui to enforce access control rules.
- These components are critical for on-chain validation and defining Seal conventions in Move.

f. Additional Supporting Files:
- Dockerfile, various configuration files (.cargo, rust-toolchain, etc.), GitHub workflows, and licensing/terms documents help automate builds, tests, and deployments.
- Design.md, UsingSeal.md, and TermsOfService.md further detail the design decisions and usage scenarios.

##### How to Represent Architecture
- Client Applications / Frontend (from examples/frontend) that initiate the encryption/decryption flows.
- Cryptographic Core (crates/crypto) responsible for the heavy lifting in encryption, secret sharing and other crypto functions.
- Key Server (crates/key-server) which verifies access policies and issues identity-based keys using threshold encryption.
- CLI Component (crates/seal-cli) which can act as a lightweight client.
- On-chain Access Control: Represent the Sui blockchain illustrating the Move packages (in examples/move and move sections) that define how access control policies are enforced.
- Storage Layer: Show interactions with decentralized storage (like Walrus or other storage systems) for off-chain data management.

b. Interactions and Data Flow:
- Crypto module as being leveraged by both the key server and the CLI.
- Communication between the client/CLI and decentralized storage when uploading or retrieving encrypted data.
- Relationship between the on-chain Move components and the key server—how the key server consults or verifies access control based on policies defined on Sui.

c. Important Architectural Patterns and Technologies:
- Threshold encryption model (t-out-of-n), where multiple key servers may work together.
- Client-side encryption approach (CSE) where encryption/decryption happens at the application or user level.
- Use of Rust for critical back-end components and the Move language for on-chain logic.
- For the frontend, mention the use of TypeScript, React, and related tooling (Vite, pnpm) for a clear separation of concerns.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Applications"
        FC["Frontend Client"]:::frontend
        CLI["Seal CLI"]:::cli
    end

    FC -->|"requests key"| KS["Key Server"]:::backend
    CLI -->|"issues commands"| KS

    KS -->|"performs encryption"| CL["Crypto Library"]:::crypto
    CLI -->|"invokes crypto"| CL

    KS -->|"validates access"| ME["Move Examples"]:::onchain
    KS -->|"validates access"| MS["Move Seal"]:::onchain
    KS -->|"validates access"| MP["Move Patterns"]:::onchain

    KS -->|"stores/retrieves"| DS["Decentralized Storage"]:::storage

    %% Click Events
    click CL "https://github.com/mystenlabs/seal/tree/main/crates/crypto"
    click KS "https://github.com/mystenlabs/seal/tree/main/crates/key-server"
    click CLI "https://github.com/mystenlabs/seal/tree/main/crates/seal-cli"
    click FC "https://github.com/mystenlabs/seal/tree/main/examples/frontend"
    click ME "https://github.com/mystenlabs/seal/tree/main/examples/move"
    click MS "https://github.com/mystenlabs/seal/tree/main/move/seal"
    click MP "https://github.com/mystenlabs/seal/tree/main/move/patterns"

    %% Styles
    classDef frontend fill:#FCE4EC,stroke:#AD1457,stroke-width:2px;
    classDef cli fill:#FFF3E0,stroke:#FB8C00,stroke-width:2px;
    classDef backend fill:#E8F5E9,stroke:#43A047,stroke-width:2px;
    classDef crypto fill:#FFF9C4,stroke:#F9A825,stroke-width:2px;
    classDef onchain fill:#E3F2FD,stroke:#1E88E5,stroke-width:2px;
    classDef storage fill:#F3E5F5,stroke:#8E24AA,stroke-width:2px;
```
