# bnb-chain/tss-lib architecture

> Architecture diagram of the GitHub repository bnb-chain/tss-lib, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bnb-chain/tss-lib
- Repository: https://github.com/bnb-chain/tss-lib

## Overview

#### Purpose and Consumer Entry Points
Go library implementing dealerless `{t,n}` threshold signatures for ECDSA and EdDSA. Consumers instantiate protocol-specific `LocalParty`, call `Start`, relay outbound messages, feed inbound messages back, and persist terminal key data or signatures. Main entry points are `ecdsa/keygen/local_party.go`, `ecdsa/signing/local_party.go`, `ecdsa/resharing/local_party.go`, with parallel EdDSA implementations under `eddsa/`.

#### Shared TSS Execution Framework
The `tss` package defines the protocol runtime contract: parties, round progression, participant identities, parameter/context construction, errors, and message wire handling. Protocol implementations depend on this layer rather than on a built-in network.
- `tss/party.go`
- `tss/round.go`
- `tss/params.go`
- `tss/message.go`
- `tss/wire.go`

#### Message and Transport Boundary
Each local party emits routed `tss.Message` values through application-provided channels. The host transport serializes with `WireBytes`, delivers broadcast or point-to-point traffic, resolves the sender `PartyID`, and invokes `UpdateFromBytes`/`Update`. Protocol message schemas are protobuf definitions with generated Go bindings.
- `tss/message.pb.go`
- `protob/message.proto`
- `ecdsa/signing/messages.go`
- `eddsa/keygen/messages.go`

Networking, session isolation, authenticated encryption, reliable broadcast, timeouts, and durable storage are explicitly outside this repository and must be supplied by the embedding application.

#### ECDSA Protocol Family
ECDSA has separate state-machine implementations for distributed key generation, multi-round signing, and membership/threshold resharing. `LocalParty` coordinates round objects, validates inbound messages, publishes outbound messages, and completes via an end channel. Keygen produces persisted share material; signing consumes it and emits a standard signature; resharing replaces or creates share material only on successful completion.
- `ecdsa/keygen/local_party.go`
- `ecdsa/keygen/rounds.go`
- `ecdsa/signing/local_party.go`
- `ecdsa/signing/rounds.go`
- `ecdsa/resharing/local_party.go`
- `ecdsa/resharing/rounds.go`

#### EdDSA Protocol Family
EdDSA mirrors the same integration model and lifecycle—keygen, signing, and resharing—but uses Edwards-curve operations and shorter protocol round sequences where applicable. Its save-data and generated message types are distinct from ECDSA and should not be mixed.
- `eddsa/keygen/local_party.go`
- `eddsa/keygen/save_data.go`
- `eddsa/signing/local_party.go`
- `eddsa/resharing/local_party.go`
- `tss/curve.go`

#### Cryptographic Building Blocks
The ECDSA protocols compose threshold-specific primitives: Paillier encryption, multiplicative-to-additive sharing/range proofs, verifiable secret sharing, commitments, Schnorr proofs, and factorization/discrete-log proofs. These are internal cryptographic boundaries that enforce correctness and privacy across protocol rounds.
- `crypto/paillier/paillier.go`
- `crypto/mta/share_protocol.go`
- `crypto/vss/feldman_vss.go`
- `crypto/commitments/commitment.go`
- `crypto/dlnproof/proof.go`
- `crypto/facproof/proof.go`

#### Persistent and Runtime Inputs
Each participant locally retains key-generation/resharing save data; it is an application-owned sensitive-storage boundary. ECDSA keygen also requires expensive safe-prime and Paillier preparameters, optionally generated before the protocol to reduce round-one latency. Go channels and goroutines provide the asynchronous execution interface; there is no service process, database, or network infrastructure in the library.
- `ecdsa/keygen/prepare.go`
- `ecdsa/keygen/save_data.go`
- `ecdsa/signing/prepare.go`
- `common/safe_prime.go`
- `crypto/ckd/child_key_derivation.go`

Main entry points: [`tss/party.go`](https://github.com/bnb-chain/tss-lib/blob/master/tss/party.go) (Party and round runtime), [`ecdsa/keygen/local_party.go`](https://github.com/bnb-chain/tss-lib/blob/master/ecdsa/keygen/local_party.go) (ECDSA key generation), [`ecdsa/signing/local_party.go`](https://github.com/bnb-chain/tss-lib/blob/master/ecdsa/signing/local_party.go) (ECDSA signing), [`eddsa/keygen/local_party.go`](https://github.com/bnb-chain/tss-lib/blob/master/eddsa/keygen/local_party.go) (EdDSA key generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["Embedding application"]
  node_consumer["Consumer application<br/>host integration"]
  node_transport["Host transport<br/>transport boundary"]
  node_storage[("Sensitive share storage<br/>application storage")]
end

subgraph group_runtime["Shared TSS runtime"]
  node_party_runtime["Party and round runtime<br/>TSS execution contract<br/>[party.go]"]
  node_message_wire["Message wire boundary<br/>message API<br/>[message.go]"]
  node_protobuf["Protocol message schemas<br/>protobuf bindings<br/>[message.proto]"]
end

subgraph group_ecdsa["ECDSA protocols"]
  node_ecdsa_keygen["ECDSA key generation<br/>LocalParty state machine<br/>[local_party.go]"]
  node_ecdsa_keygen_rounds["ECDSA keygen rounds<br/>round implementations<br/>[rounds.go]"]
  node_ecdsa_signing["ECDSA signing<br/>LocalParty state machine<br/>[local_party.go]"]
  node_ecdsa_signing_rounds["ECDSA signing rounds<br/>round implementations<br/>[rounds.go]"]
  node_ecdsa_resharing["ECDSA resharing<br/>LocalParty state machine<br/>[local_party.go]"]
  node_ecdsa_prepare["ECDSA preparameters<br/>runtime input preparation<br/>[prepare.go]"]
end

subgraph group_eddsa["EdDSA protocols"]
  node_eddsa_keygen["EdDSA key generation<br/>LocalParty state machine<br/>[local_party.go]"]
  node_eddsa_signing["EdDSA signing<br/>LocalParty state machine<br/>[local_party.go]"]
  node_eddsa_resharing["EdDSA resharing<br/>LocalParty state machine<br/>[local_party.go]"]
  node_curve_support["Curve support<br/>curve abstraction<br/>[curve.go]"]
end

subgraph group_crypto["Cryptographic primitives"]
  node_threshold_primitives["Threshold proof primitives<br/>cryptographic protocols<br/>[share_protocol.go]"]
  node_paillier["Paillier encryption<br/>homomorphic encryption<br/>[paillier.go]"]
end

node_consumer -->|"creates and starts"| node_ecdsa_keygen
node_consumer -->|"creates and starts"| node_ecdsa_signing
node_consumer -->|"creates and starts"| node_ecdsa_resharing
node_consumer -->|"creates and starts"| node_eddsa_keygen
node_consumer -->|"creates and starts"| node_eddsa_signing
node_consumer -->|"creates and starts"| node_eddsa_resharing
node_party_runtime -->|"uses message contract"| node_message_wire
node_message_wire -->|"serializes schemas"| node_protobuf
node_transport -->|"WireBytes and Update"| node_message_wire
node_consumer -->|"provides"| node_transport
node_ecdsa_keygen -->|"implements"| node_party_runtime
node_ecdsa_signing -->|"implements"| node_party_runtime
node_ecdsa_resharing -->|"implements"| node_party_runtime
node_ecdsa_keygen -->|"coordinates"| node_ecdsa_keygen_rounds
node_ecdsa_signing -->|"coordinates"| node_ecdsa_signing_rounds
node_ecdsa_keygen -.->|"uses preparameters"| node_ecdsa_prepare
node_ecdsa_prepare -->|"generates inputs for"| node_paillier
node_ecdsa_keygen_rounds -->|"uses"| node_threshold_primitives
node_ecdsa_signing_rounds -->|"uses"| node_threshold_primitives
node_threshold_primitives -->|"includes encryption operations"| node_paillier
node_ecdsa_keygen -->|"writes share data"| node_storage
node_ecdsa_signing -->|"reads share data"| node_storage
node_ecdsa_resharing -->|"replaces share data"| node_storage
node_eddsa_keygen -->|"implements"| node_party_runtime
node_eddsa_signing -->|"implements"| node_party_runtime
node_eddsa_resharing -->|"implements"| node_party_runtime
node_eddsa_keygen -->|"uses"| node_curve_support
node_eddsa_signing -->|"uses"| node_curve_support
node_eddsa_keygen -->|"writes EdDSA share data"| node_storage
node_eddsa_signing -->|"reads EdDSA share data"| node_storage
node_eddsa_resharing -->|"replaces EdDSA share data"| node_storage

click node_party_runtime "https://github.com/bnb-chain/tss-lib/blob/master/tss/party.go"
click node_message_wire "https://github.com/bnb-chain/tss-lib/blob/master/tss/message.go"
click node_protobuf "https://github.com/bnb-chain/tss-lib/blob/master/protob/message.proto"
click node_ecdsa_keygen "https://github.com/bnb-chain/tss-lib/blob/master/ecdsa/keygen/local_party.go"
click node_ecdsa_keygen_rounds "https://github.com/bnb-chain/tss-lib/blob/master/ecdsa/keygen/rounds.go"
click node_ecdsa_signing "https://github.com/bnb-chain/tss-lib/blob/master/ecdsa/signing/local_party.go"
click node_ecdsa_signing_rounds "https://github.com/bnb-chain/tss-lib/blob/master/ecdsa/signing/rounds.go"
click node_ecdsa_resharing "https://github.com/bnb-chain/tss-lib/blob/master/ecdsa/resharing/local_party.go"
click node_ecdsa_prepare "https://github.com/bnb-chain/tss-lib/blob/master/ecdsa/keygen/prepare.go"
click node_eddsa_keygen "https://github.com/bnb-chain/tss-lib/blob/master/eddsa/keygen/local_party.go"
click node_eddsa_signing "https://github.com/bnb-chain/tss-lib/blob/master/eddsa/signing/local_party.go"
click node_eddsa_resharing "https://github.com/bnb-chain/tss-lib/blob/master/eddsa/resharing/local_party.go"
click node_curve_support "https://github.com/bnb-chain/tss-lib/blob/master/tss/curve.go"
click node_threshold_primitives "https://github.com/bnb-chain/tss-lib/blob/master/crypto/mta/share_protocol.go"
click node_paillier "https://github.com/bnb-chain/tss-lib/blob/master/crypto/paillier/paillier.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_consumer,node_transport,node_storage toneBlue
class node_party_runtime,node_message_wire,node_protobuf toneAmber
class node_ecdsa_keygen,node_ecdsa_keygen_rounds,node_ecdsa_signing,node_ecdsa_signing_rounds,node_ecdsa_resharing,node_ecdsa_prepare toneMint
class node_eddsa_keygen,node_eddsa_signing,node_eddsa_resharing,node_curve_support toneRose
class node_threshold_primitives,node_paillier toneIndigo
```

## Components

### Embedding application

Supplies transport, storage, and asynchronous orchestration.

- **Consumer application**: host integration · Creates parties and owns networking, sessions, timeouts, and secure storage.
- **Host transport**: transport boundary · Relays routed broadcast and point-to-point protocol messages.
- **Sensitive share storage**: application storage · Persists locally retained keygen and resharing save data.

### Shared TSS runtime

Protocol-neutral party, round, identity, parameter, and wire contracts.

- [Party and round runtime](https://github.com/bnb-chain/tss-lib/blob/master/tss/party.go): TSS execution contract · Drives local parties, rounds, identities, parameters, and errors. · `tss/party.go`
- [Message wire boundary](https://github.com/bnb-chain/tss-lib/blob/master/tss/message.go): message API · Encodes outbound messages and routes inbound updates to parties. · `tss/message.go`
- [Protocol message schemas](https://github.com/bnb-chain/tss-lib/blob/master/protob/message.proto): protobuf bindings · Defines wire message structures shared by protocol participants. · `protob/message.proto`

### ECDSA protocols

Independent keygen, signing, and resharing state machines.

- [ECDSA key generation](https://github.com/bnb-chain/tss-lib/blob/master/ecdsa/keygen/local_party.go): LocalParty state machine · Creates ECDSA share material through coordinated rounds. · `ecdsa/keygen/local_party.go`
- [ECDSA keygen rounds](https://github.com/bnb-chain/tss-lib/blob/master/ecdsa/keygen/rounds.go): round implementations · Performs distributed key-generation exchanges and validation. · `ecdsa/keygen/rounds.go`
- [ECDSA signing](https://github.com/bnb-chain/tss-lib/blob/master/ecdsa/signing/local_party.go): LocalParty state machine · Consumes saved shares and completes a standard ECDSA signature. · `ecdsa/signing/local_party.go`
- [ECDSA signing rounds](https://github.com/bnb-chain/tss-lib/blob/master/ecdsa/signing/rounds.go): round implementations · Runs the multi-round threshold signing flow. · `ecdsa/signing/rounds.go`
- [ECDSA resharing](https://github.com/bnb-chain/tss-lib/blob/master/ecdsa/resharing/local_party.go): LocalParty state machine · Replaces or creates share material after successful completion. · `ecdsa/resharing/local_party.go`
- [ECDSA preparameters](https://github.com/bnb-chain/tss-lib/blob/master/ecdsa/keygen/prepare.go): runtime input preparation · Precomputes safe-prime and Paillier inputs to reduce keygen latency. · `ecdsa/keygen/prepare.go`

### EdDSA protocols

Edwards-curve protocol family with distinct state and messages.

- [EdDSA key generation](https://github.com/bnb-chain/tss-lib/blob/master/eddsa/keygen/local_party.go): LocalParty state machine · Creates EdDSA-specific saved share data. · `eddsa/keygen/local_party.go`
- [EdDSA signing](https://github.com/bnb-chain/tss-lib/blob/master/eddsa/signing/local_party.go): LocalParty state machine · Runs threshold signing using EdDSA share data. · `eddsa/signing/local_party.go`
- [EdDSA resharing](https://github.com/bnb-chain/tss-lib/blob/master/eddsa/resharing/local_party.go): LocalParty state machine · Updates EdDSA membership or threshold share material. · `eddsa/resharing/local_party.go`
- [Curve support](https://github.com/bnb-chain/tss-lib/blob/master/tss/curve.go): curve abstraction · Provides curve operations used by the EdDSA family. · `tss/curve.go`

### Cryptographic primitives

Internal proofs, sharing, encryption, and commitment building blocks.

- [Threshold proof primitives](https://github.com/bnb-chain/tss-lib/blob/master/crypto/mta/share_protocol.go): cryptographic protocols · MTA, VSS, commitments, Schnorr, factorization, and discrete-log proofs. · `crypto/mta/share_protocol.go`
- [Paillier encryption](https://github.com/bnb-chain/tss-lib/blob/master/crypto/paillier/paillier.go): homomorphic encryption · Supports ECDSA threshold computations and preparameters. · `crypto/paillier/paillier.go`

## Connections

- Consumer application → ECDSA key generation: creates and starts
- Consumer application → ECDSA signing: creates and starts
- Consumer application → ECDSA resharing: creates and starts
- Consumer application → EdDSA key generation: creates and starts
- Consumer application → EdDSA signing: creates and starts
- Consumer application → EdDSA resharing: creates and starts
- Party and round runtime → Message wire boundary: uses message contract
- Message wire boundary → Protocol message schemas: serializes schemas
- Host transport → Message wire boundary: WireBytes and Update
- Consumer application → Host transport: provides
- ECDSA key generation → Party and round runtime: implements
- ECDSA signing → Party and round runtime: implements
- ECDSA resharing → Party and round runtime: implements
- ECDSA key generation → ECDSA keygen rounds: coordinates
- ECDSA signing → ECDSA signing rounds: coordinates
- ECDSA key generation → ECDSA preparameters: uses preparameters
- ECDSA preparameters → Paillier encryption: generates inputs for
- ECDSA keygen rounds → Threshold proof primitives: uses
- ECDSA signing rounds → Threshold proof primitives: uses
- Threshold proof primitives → Paillier encryption: includes encryption operations
- ECDSA key generation → Sensitive share storage: writes share data
- ECDSA signing → Sensitive share storage: reads share data
- ECDSA resharing → Sensitive share storage: replaces share data
- EdDSA key generation → Party and round runtime: implements
- EdDSA signing → Party and round runtime: implements
- EdDSA resharing → Party and round runtime: implements
- EdDSA key generation → Curve support: uses
- EdDSA signing → Curve support: uses
- EdDSA key generation → Sensitive share storage: writes EdDSA share data
- EdDSA signing → Sensitive share storage: reads EdDSA share data
- EdDSA resharing → Sensitive share storage: replaces EdDSA share data
