tss

README

Zetaclient TSS Overview

(Threshold Signature Scheme)

This package wraps the go-tss library, providing a high-level API for signing arbitrary digests using TSS. The underlying go-tss library relies on tss-lib.

What is a Digest?

A digest is simply a byte slice ([]byte), typically representing a transaction hash or other cryptographic input. The API allows secure signing of these digests in a distributed manner.

Architecture Overview

This is the approximate structure of the TSS implementation within Zetaclient:

zetaclientd(
    tss.Service(
        gotss.Server(libp2p()) 
    )
)

Package Structure

• setup.go: Initializes the go-tss TSS server and the Service wrapper of this package.
• keygen.go: Manages the key generation ceremony, creating keys used by TSS.
• service.go: Implements the Service struct, offering methods for signing and verifying digests.
• Other Files: Utilities and supporting tools for TSS operations.

Links

• go-tss: https://github.com/zeta-chain/go-tss
• tss-lib: https://github.com/zeta-chain/tss-lib

Documentation

Index

• Constants
• func HealthcheckWorker(ctx context.Context, server *tss.TssServer, p HealthcheckProps, ...) error
• func KeygenCeremony(ctx context.Context, server *tss.TssServer, zc Zetacore, logger zerolog.Logger) (observertypes.TSS, error)
• func MultiAddressFromString(peer string) ([]multiaddr.Multiaddr, error)
• func NewTSSServer(bootstrapPeers []multiaddr.Multiaddr, whitelistPeers []peer.ID, ...) (*tss.TssServer, error)
• func ResolvePreParamsFromPath(path string) (*keygen.LocalPreParams, error)
• func SignatureToBytes(input keysign.Signature) (sig [65]byte, err error)
• func TestKeySign(keySigner KeySigner, tssPubKeyBec32 string, logger zerolog.Logger) error
• func VerifySignature(sig keysign.Signature, pk PubKey, hash []byte) ([65]byte, error)
• type HealthcheckProps
• type KeySigner
• type Metrics
• type Opt
  • func WithMetrics(ctx context.Context, zetacore Zetacore, m *Metrics) Opt
  • func WithPostBlame(postBlame bool) Opt
• type PubKey
  • func NewPubKeyFromBech32(bech32 string) (PubKey, error)
  • func NewPubKeyFromECDSA(pk ecdsa.PublicKey) (PubKey, error)
  • func NewPubKeyFromECDSAHexString(raw string) (PubKey, error)
  • func ParsePubKeysFromPath(tssPath string, logger zerolog.Logger) ([]PubKey, error)
  • func (k PubKey) AddressBTC(chainID int64) (*btcutil.AddressWitnessPubKeyHash, error)
  • func (k PubKey) AddressEVM() eth.Address
  • func (k PubKey) Bech32String() string
  • func (k PubKey) Bytes(compress bool) []byte
• type Service
  • func NewService(keySigner KeySigner, tssPubKeyBech32 string, zetacore Zetacore, ...) (*Service, error)
  • func Setup(ctx context.Context, p SetupProps, logger zerolog.Logger) (*Service, error)
  • func (s *Service) PubKey() PubKey
  • func (s *Service) Sign(ctx context.Context, digest []byte, height, nonce uint64, chainID int64) ([65]byte, error)
  • func (s *Service) SignBatch(ctx context.Context, digests [][]byte, height, nonce uint64, chainID int64) ([][65]byte, error)
• type SetupProps
• type Telemetry
• type Zetacore

Constants

const (
	// Port is the default port for go-tss server.
	Port    = 6668
	Version = "0.14.0"
	Algo    = tsscommon.ECDSA
)

Functions

func HealthcheckWorker

func HealthcheckWorker(ctx context.Context, server *tss.TssServer, p HealthcheckProps, logger zerolog.Logger) error

HealthcheckWorker checks the health of the TSS server and its peers.

func KeygenCeremony

func KeygenCeremony(
	ctx context.Context,
	server *tss.TssServer,
	zc Zetacore,
	logger zerolog.Logger,
) (observertypes.TSS, error)

KeygenCeremony runs TSS keygen ceremony as a blocking thread. Most likely the keygen is already generated, so this function will be a noop. Returns the TSS key if generated, or error.

func MultiAddressFromString

func MultiAddressFromString(peer string) ([]multiaddr.Multiaddr, error)

MultiAddressFromString parses a string into a slice of addresses (for convenience).

func NewTSSServer

func NewTSSServer(
	bootstrapPeers []multiaddr.Multiaddr,
	whitelistPeers []peer.ID,
	preParams *keygen.LocalPreParams,
	privateKey crypto.PrivKey,
	cfg config.Config,
	tssPassword string,
	logger zerolog.Logger,
) (*tss.TssServer, error)

NewTSSServer creates a new tss.TssServer (go-tss) instance for key signing. - bootstrapPeers are used to discover other peers - whitelistPeers are the only peers that are allowed in p2p key signing. - preParams are the TSS pre-params required for key generation

func ResolvePreParamsFromPath

func ResolvePreParamsFromPath(path string) (*keygen.LocalPreParams, error)

ResolvePreParamsFromPath resolves TSS pre-params from json config by path. Error indicates that the pre-params file is not found or invalid. FYI: pre-params are generated by keygen.GeneratePreParams.

func SignatureToBytes

func SignatureToBytes(input keysign.Signature) (sig [65]byte, err error)

SignatureToBytes converts keysign.Signature to [65]byte (R, S, V)

func TestKeySign

func TestKeySign(keySigner KeySigner, tssPubKeyBec32 string, logger zerolog.Logger) error

TestKeySign performs a TSS key-sign test of sample data.

func VerifySignature

func VerifySignature(sig keysign.Signature, pk PubKey, hash []byte) ([65]byte, error)

VerifySignature checks that keysign.Signature is valid and origins from expected TSS public key. Also returns signature as [65]byte (R, S, V)

Types

type HealthcheckProps

type HealthcheckProps struct {
	Telemetry               Telemetry
	Interval                time.Duration
	WhitelistPeers          []peer.ID
	NumConnectedPeersMetric prometheus.Gauge
}

HealthcheckProps represents options for HealthcheckWorker.

type KeySigner

type KeySigner interface {
	KeySign(req keysign.Request) (keysign.Response, error)
}

KeySigner signs messages using TSS (subset of go-tss)

type Metrics

type Metrics struct {
	ActiveMsgsSigns    prometheus.Gauge
	SignLatency        *prometheus.HistogramVec
	NodeBlamePerPubKey *prometheus.CounterVec
}

Metrics Prometheus metrics for the TSS service.

type Opt

type Opt func(cfg *serviceConfig, logger zerolog.Logger) error

Opt Service option.

func WithMetrics

func WithMetrics(ctx context.Context, zetacore Zetacore, m *Metrics) Opt

WithMetrics registers Prometheus metrics for the TSS service. Otherwise, no metrics will be collected.

func WithPostBlame

func WithPostBlame(postBlame bool) Opt

WithPostBlame configures the TSS service to post blame in case of failed key signatures.

type PubKey

type PubKey struct {
	// contains filtered or unexported fields
}

PubKey represents TSS public key in various formats.

func NewPubKeyFromBech32

func NewPubKeyFromBech32(bech32 string) (PubKey, error)

NewPubKeyFromBech32 creates a new PubKey from a bech32 address. Example: `zetapub1addwnpepq2fdhcmfyv07s86djjca835l4f2n2ta0c7le6vnl508mseca2s9g6slj0gm`

func NewPubKeyFromECDSA

func NewPubKeyFromECDSA(pk ecdsa.PublicKey) (PubKey, error)

NewPubKeyFromECDSA creates a new PubKey from an ECDSA public key.

func NewPubKeyFromECDSAHexString

func NewPubKeyFromECDSAHexString(raw string) (PubKey, error)

NewPubKeyFromECDSAHexString creates PubKey from 0xABC12...

func ParsePubKeysFromPath

func ParsePubKeysFromPath(tssPath string, logger zerolog.Logger) ([]PubKey, error)

ParsePubKeysFromPath extracts public keys from tss directory. Example: `tssPath="~/.tss"`. Contents: localstate-zetapub1addwnpepq2fdhcmfyv07s86djjca835l4f2n2ta0c7le6vnl508mseca2s9g6slj0gm.json Output: `zetapub1addwnpepq2fdhcmfyv07s86djjca835l4f2n2ta0c7le6vnl508mseca2s9g6slj0gm`

func (PubKey) AddressBTC

func (k PubKey) AddressBTC(chainID int64) (*btcutil.AddressWitnessPubKeyHash, error)

AddressBTC returns the bitcoin address of the public key.

func (PubKey) AddressEVM

func (k PubKey) AddressEVM() eth.Address

AddressEVM returns the ethereum address of the public key.

func (PubKey) Bech32String

func (k PubKey) Bech32String() string

Bech32String returns the bech32 string of the public key. Example: `zetapub1addwnpepq2fdhcmfyv07s86djjca835l4f2n2ta0c7le6vnl508mseca2s9g6slj0gm`

func (PubKey) Bytes

func (k PubKey) Bytes(compress bool) []byte

Bytes marshals pubKey to bytes either as compressed or uncompressed slice.

In ECDSA, a compressed pubKey includes only the X and a parity bit for the Y, allowing the full Y to be reconstructed using the elliptic curve equation, thus reducing the key size while maintaining the ability to fully recover the pubKey.

type Service

type Service struct {
	// contains filtered or unexported fields
}

Service TSS service

func NewService

func NewService(
	keySigner KeySigner,
	tssPubKeyBech32 string,
	zetacore Zetacore,
	logger zerolog.Logger,
	opts ...Opt,
) (*Service, error)

NewService Service constructor. TODO LRU cache

func Setup

func Setup(ctx context.Context, p SetupProps, logger zerolog.Logger) (*Service, error)

Setup beefy function that does all the logic for bootstrapping tss-server, tss signer, generating TSS key is needed, etc...

func (*Service) PubKey

func (s *Service) PubKey() PubKey

PubKey returns current TSS PubKey.

func (*Service) Sign

func (s *Service) Sign(ctx context.Context, digest []byte, height, nonce uint64, chainID int64) ([65]byte, error)

Sign signs msg digest (hash). Returns signature in the format of R (32B), S (32B), V (1B).

func (*Service) SignBatch

func (s *Service) SignBatch(
	ctx context.Context,
	digests [][]byte,
	height, nonce uint64,
	chainID int64,
) ([][65]byte, error)

SignBatch signs msgs digests (hash). Returns list of signatures in the format of R (32B), S (32B), V (1B).

type SetupProps

type SetupProps struct {
	Config              config.Config
	Zetacore            Zetacore
	GranteePubKeyBech32 string
	HotKeyPassword      string
	TSSKeyPassword      string
	BitcoinChainIDs     []int64
	PostBlame           bool
	Telemetry           Telemetry
}

SetupProps represents options for Setup.

type Telemetry

type Telemetry interface {
	SetP2PID(id string)
	SetConnectedPeers(peers []peer.AddrInfo)
	SetKnownPeers(peers []peer.AddrInfo)
	SetPingRTT(peers map[peer.ID]int64)
}

type Zetacore

type Zetacore interface {
	GetKeys() keyinterfaces.ObserverKeys

	Chain() chains.Chain
	GetBlockHeight(ctx context.Context) (int64, error)

	GetKeyGen(ctx context.Context) (observertypes.Keygen, error)
	GetTSS(ctx context.Context) (observertypes.TSS, error)
	GetTSSHistory(ctx context.Context) ([]observertypes.TSS, error)
	PostVoteTSS(
		ctx context.Context,
		tssPubKey string,
		keyGenZetaHeight int64,
		status chains.ReceiveStatus,
	) (string, error)

	PostVoteBlameData(ctx context.Context, blame *blame.Blame, chainID int64, index string) (string, error)
}

Zetacore zeta core client.