How bnb-chain/tss-lib works
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: party.go Party and round runtime · keygen/local_party.go ECDSA key generation · signing/local_party.go ECDSA signing · keygen/local_party.go EdDSA key generation
Components 18
Embedding application
Supplies transport, storage, and asynchronous orchestration.
- Consumer application · Creates parties and owns networking, sessions, timeouts, and secure storage.
- Host transport · Relays routed broadcast and point-to-point protocol messages.
- Sensitive share 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 · Drives local parties, rounds, identities, parameters, and errors.
tss/party.go - Message wire boundary · Encodes outbound messages and routes inbound updates to parties.
tss/message.go - Protocol message schemas · Defines wire message structures shared by protocol participants.
protob/message.proto
ECDSA protocols
Independent keygen, signing, and resharing state machines.
- ECDSA key generation · Creates ECDSA share material through coordinated rounds.
ecdsa/keygen/local_party.go - ECDSA keygen rounds · Performs distributed key-generation exchanges and validation.
ecdsa/keygen/rounds.go - ECDSA signing · Consumes saved shares and completes a standard ECDSA signature.
ecdsa/signing/local_party.go - ECDSA signing rounds · Runs the multi-round threshold signing flow.
ecdsa/signing/rounds.go - ECDSA resharing · Replaces or creates share material after successful completion.
ecdsa/resharing/local_party.go - ECDSA preparameters · 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 · Creates EdDSA-specific saved share data.
eddsa/keygen/local_party.go - EdDSA signing · Runs threshold signing using EdDSA share data.
eddsa/signing/local_party.go - EdDSA resharing · Updates EdDSA membership or threshold share material.
eddsa/resharing/local_party.go - Curve support · Provides curve operations used by the EdDSA family.
tss/curve.go
Cryptographic primitives
Internal proofs, sharing, encryption, and commitment building blocks.
- Threshold proof primitives · MTA, VSS, commitments, Schnorr, factorization, and discrete-log proofs.
crypto/mta/share_protocol.go - Paillier encryption · Supports ECDSA threshold computations and preparameters.
crypto/paillier/paillier.go
Connections 31
- 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