# ibm/tss architecture

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

- Interactive diagram: https://gitdiagram.com/ibm/tss
- Repository: https://github.com/ibm/tss

## Overview

##### Project type and purpose
- This is a Go-based cryptographic library (“TSS”) that implements Threshold Signature Schemes. It is not a web or full-stack application but a pluggable library composed of multiple modules:
- A discovery/synchronization layer (“disc”)
- A reliable broadcast layer (“rbc”)
- An optional networking layer (“net”)
- Pluggable MPC backends for different signature schemes (“mpc/binance/…”, “mpc/bls”, “mpc/ps”)
- A top-level orchestrator (“threshold”) that wires these pieces together
- Common types (“types”) and test utilities.

##### File structure
- Top-level directories:
- disc/        – discovery protocol
- rbc/         – reliable byzantine broadcast
- net/         – encrypted/authenticated messaging implementation
- mpc/         – multiple submodules, each a Go module wrapping or implementing a TSS scheme:
– binance/ecdsa
– binance/eddsa
– bls
– ps
- threshold/   – orchestration of disc, rbc, net, mpc; implements Scheme interface
- types/       – interface and shared type definitions
- testutil/    – TLS key generation for tests
- test/        – integration tests across backends
- Configuration/build:
- go.mod at root and in each mpc submodule
- CI workflow under .github/workflows/CI.yml
- Test scripts under scripts/

##### README for additional insights
- The README describes:
- How threshold.Scheme is constructed (LoudScheme vs. SilentScheme)
- Dependency injection pattern for passing custom disc, rbc, net, mpc implementations
- Separation of UniversalID vs. PartyID domains
- Flow of key generation vs. signature phases
- How each module’s API looks and interacts

##### Main components & their relationships
a. Components:
1. Client code / consumer (initializes threshold.Scheme, feeds messages, retrieves signatures)
2. threshold.Scheme (orchestrator)
3. disc (member discovery, bootstrapping)
4. rbc (reliable broadcast layer)
5. net (optional secure transport, implements send/receive)
6. mpc backends (binance-ecdsa, binance-eddsa, bls, ps)
7. types (shared structs like IncMessage)
b. Interactions / Data flow:
- Consumer invokes Scheme.KeyGen or Scheme.Sign
- Scheme uses disc to establish membership (UniversalID → PartyID mapping)
- Scheme wires up rbc and net (or user-provided transport) to multicast messages
- MPC backend is initialized via a callback (sendMsg) for sending partial msgs to other parties
- Incoming messages from net are dispatched by Scheme.HandleMessage to the correct module (disc, rbc, mpc)
- rbc ensures non-equivocation; disc ensures all parties are present; mpc executes threshold protocol
- Results (key shares, partial signatures) bubble up to Scheme, which returns bytes to consumer
c. Architectural patterns and principles:
- Dependency Injection – Scheme receives interfaces for disc/rbc/net/mpc
- Modular design – each TSS variant lives in its own Go module, no circular imports
- Pluggable pipeline – discovery → broadcast → MPC
- Separation of concerns – network vs. protocol vs. orchestration
d. Key technologies/frameworks:
- Go modules, standard Go testing
- Binance tss-lib for ECDSA/EdDSA
- gnark-crypto bn254 for BLS
- IBM Pointcheval‐Sanders for PS
- Simple in-memory TLS generator in testutil

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Consumer and Orchestrator
    Consumer["Consumer\n(initializes Scheme,\nfeeds messages,\nretrieves signatures)"]:::client
    Scheme["threshold.Scheme\n(Orchestrator)"]:::orchestrator

    Consumer -->|"KeyGen/Sign()"| Scheme

    %% Core Modules
    subgraph "Discovery Layer"
        Disc1["disc/discovery.go"]:::infra
        Disc2["disc/silent.go"]:::infra
    end

    subgraph "Broadcast Layer"
        RBC["rbc/rbc.go"]:::infra
    end

    subgraph "Networking Layer"
        Net["net/net.go"]:::infra
    end

    MsgBox["msg/msgbox.go\n(Message Dispatch Helper)"]:::infra

    %% Wiring
    Scheme -->|"uses"| Disc1
    Scheme -->|"uses"| Disc2
    Scheme -->|"uses"| RBC
    Scheme -->|"uses"| Net
    Scheme -->|"dispatch via"| MsgBox

    %% MPC Backends
    subgraph "MPC Backends" 
        BinanceECDSA["mpc/binance/ecdsa/mpc.go"]:::mpc
        BinanceEdDSA["mpc/binance/eddsa/mpc.go"]:::mpc
        BLS["mpc/bls/mpc.go"]:::mpc
        PS["mpc/ps/ps.go"]:::mpc
    end

    Scheme -->|"init via sendMsg callback"| BinanceECDSA
    Scheme -->|"init via sendMsg callback"| BinanceEdDSA
    Scheme -->|"init via sendMsg callback"| BLS
    Scheme -->|"init via sendMsg callback"| PS

    %% Message flows between net and MPC
    BinanceECDSA -->|"partial msgs over net"| Net
    BinanceEdDSA -->|"partial msgs over net"| Net
    BLS -->|"partial msgs over net"| Net
    PS -->|"partial msgs over net"| Net

    Net -->|"incoming msgs"| Scheme

    %% Results back to Consumer
    Scheme -->|"returns key shares/partial sigs"| Consumer

    %% Auxiliary Modules
    Types["types/types.go\n(Shared Types)"]:::aux
    subgraph "Test Utilities"
        CA["testutil/tlsgen/ca.go"]:::aux
        KeyGen["testutil/tlsgen/key.go"]:::aux
    end

    %% Dependency Injection Annotation
    Scheme -.->|"inject disc/rbc/net/mpc"| Disc1
    Scheme -.-> Disc2
    Scheme -.-> RBC
    Scheme -.-> Net
    Scheme -.-> BinanceECDSA
    Scheme -.-> BinanceEdDSA
    Scheme -.-> BLS
    Scheme -.-> PS

    %% Click Events
    click Disc1 "https://github.com/ibm/tss/blob/main/disc/discovery.go"
    click Disc2 "https://github.com/ibm/tss/blob/main/disc/silent.go"
    click RBC "https://github.com/ibm/tss/blob/main/rbc/rbc.go"
    click Net "https://github.com/ibm/tss/blob/main/net/net.go"
    click MsgBox "https://github.com/ibm/tss/blob/main/msg/msgbox.go"
    click BinanceECDSA "https://github.com/ibm/tss/blob/main/mpc/binance/ecdsa/mpc.go"
    click BinanceEdDSA "https://github.com/ibm/tss/blob/main/mpc/binance/eddsa/mpc.go"
    click BLS "https://github.com/ibm/tss/blob/main/mpc/bls/mpc.go"
    click PS "https://github.com/ibm/tss/blob/main/mpc/ps/ps.go"
    click Scheme "https://github.com/ibm/tss/blob/main/threshold/threshold.go"
    click Types "https://github.com/ibm/tss/blob/main/types/types.go"
    click CA "https://github.com/ibm/tss/blob/main/testutil/tlsgen/ca.go"
    click KeyGen "https://github.com/ibm/tss/blob/main/testutil/tlsgen/key.go"

    %% Styles
    classDef client fill:#FFD580,stroke:#333,stroke-width:1px
    classDef orchestrator fill:#FFB6C1,stroke:#333,stroke-width:1px
    classDef infra fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef mpc fill:#90EE90,stroke:#333,stroke-width:1px
    classDef aux fill:#E0E0E0,stroke:#333,stroke-width:1px
```
