coordinator

package
v0.0.48 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 11, 2026 License: MIT Imports: 26 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// PerChainCap is the max in-flight SIGN events per destination chain
	// (default 16; below EVM mempool accountqueue 64).
	// EVM-only: bypassed for non-EVM chains (e.g. SVM has no nonce queueing,
	// so in-flight events don't block each other).
	PerChainCap = 16
	// ConsecutiveWaitThreshold: after this many consecutive polls where a chain
	// has in-flight events, use finalized nonce to recover from stuck nonces
	// (~200s at 10s poll).
	// EVM-only: SVM doesn't use a nonce, so stuck-nonce recovery is meaningless.
	ConsecutiveWaitThreshold = 20
)

Variables

This section is empty.

Functions

func CalculateThreshold 

func CalculateThreshold(numParticipants int) int

CalculateThreshold calculates the threshold as > 2/3 of participants. Formula: threshold = floor((2 * n) / 3) + 1 This ensures threshold > 2/3 * n

func DeriveEVMAddressFromPubkey added in v0.0.28 

func DeriveEVMAddressFromPubkey(pubkeyHex string) (string, error)

DeriveEVMAddressFromPubkey derives an EVM address from a hex-encoded compressed secp256k1 public key.

Types

type Coordinator 

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

Coordinator handles coordinator logic for TSS events.

func NewCoordinator 

func NewCoordinator(
	eventStore *eventstore.Store,
	pushCore PushCoreClient,
	keyshareManager *keyshare.Manager,
	chains *externalchains.Chains,
	validatorAddress string,
	coordinatorRange uint64,
	pollInterval time.Duration,
	send SendFunc,
	logger zerolog.Logger,
) *Coordinator

NewCoordinator creates a new coordinator.

func (*Coordinator) CancelTracking added in v0.0.40 

func (c *Coordinator) CancelTracking(eventID string)

CancelTracking drops the ackTracking entry for the event if present. Used by sessionmanager when a signature_broadcast arrives for an event this UV is also coordinating, so no further BEGIN is sent.

func (*Coordinator) FundMigrateEligible added in v0.0.48 

func (c *Coordinator) FundMigrateEligible(
	ctx context.Context,
	event store.Event,
) ([]*types.UniversalValidator, int, error)

FundMigrateEligible returns the validators that may sign a fund migration, and how many of them are required.

Used by the coordinator to select signers and by every participant to validate the selection it receives. Both derive the answer from the same chain state, so a set the coordinator can legitimately pick is a set the participants accept.

func (*Coordinator) GetCurrentTSSKey added in v0.0.13 

func (c *Coordinator) GetCurrentTSSKey(ctx context.Context) (string, string, error)

GetCurrentTSSKey gets the current TSS key ID and public key from pushCore.

func (*Coordinator) GetEligibleUV 

func (c *Coordinator) GetEligibleUV(protocolType string) []*types.UniversalValidator

GetEligibleUV returns ALL eligible validators for the given protocol type (no random selection). Used by the session manager to check whether a setup-message sender is eligible to participate. For SIGN coordinator setup the coordinator calls getSignParticipants (random threshold subset).

func (*Coordinator) GetLatestBlockNum 

func (c *Coordinator) GetLatestBlockNum(ctx context.Context) (uint64, error)

GetLatestBlockNum gets the latest block number from pushCore.

func (*Coordinator) GetMultiAddrsFromPeerID 

func (c *Coordinator) GetMultiAddrsFromPeerID(_ context.Context, peerID string) ([]string, error)

GetMultiAddrsFromPeerID gets the multiaddrs for a given peerID.

func (*Coordinator) GetPartyIDFromPeerID 

func (c *Coordinator) GetPartyIDFromPeerID(_ context.Context, peerID string) (string, error)

GetPartyIDFromPeerID gets the partyID (validator address) for a given peerID.

func (*Coordinator) GetPeerIDFromPartyID 

func (c *Coordinator) GetPeerIDFromPartyID(_ context.Context, partyID string) (string, error)

GetPeerIDFromPartyID gets the peerID for a given partyID (validator address).

func (*Coordinator) GetTSSAddress added in v0.0.13 

func (c *Coordinator) GetTSSAddress(ctx context.Context) (string, error)

GetTSSAddress returns the TSS ECDSA address derived from the current TSS public key (compressed secp256k1).

func (*Coordinator) HandleIncomingMessage added in v0.0.40 

func (c *Coordinator) HandleIncomingMessage(ctx context.Context, peerID string, msg *Message) error

HandleIncomingMessage routes a coordinator-bound message. Caller unmarshals.

func (*Coordinator) IsKnownPeer added in v0.0.48 

func (c *Coordinator) IsKnownPeer(peerID string) bool

IsKnownPeer reports whether peerID belongs to a Universal Validator that can participate in some TSS protocol (Active, Pending Join, or Pending Leave). Fails closed when the cache is empty or stale.

func (*Coordinator) IsPeerCoordinator 

func (c *Coordinator) IsPeerCoordinator(ctx context.Context, peerID string) (bool, error)

IsPeerCoordinator reports whether the given peerID is the coordinator for the current block. Used by the session manager to validate that an incoming setup message comes from the coordinator.

func (*Coordinator) SelectParticipants added in v0.0.48 

func (c *Coordinator) SelectParticipants(
	ctx context.Context,
	event store.Event,
	allValidators []*types.UniversalValidator,
) ([]*types.UniversalValidator, error)

SelectParticipants picks who takes part in an event.

For SIGN a random threshold subset (>2/3 of eligible) suffices and is more resilient when some nodes are offline. For all other protocols (keygen, keyrefresh, quorum change) every eligible validator must participate.

func (*Coordinator) Start 

func (c *Coordinator) Start(ctx context.Context)

Start starts the coordinator loop.

func (*Coordinator) Stop 

func (c *Coordinator) Stop()

Stop stops the coordinator loop.

func (*Coordinator) Validators added in v0.0.40 

func (c *Coordinator) Validators() []*types.UniversalValidator

Validators returns the cached validator set snapshot, or nil if stale. Exposed for sessionmanager broadcast fanout.

func (*Coordinator) VerifySignedData added in v0.0.40 

func (c *Coordinator) VerifySignedData(ctx context.Context, event *store.Event, signedData *SignedDataPayload) error

VerifySignedData checks that signedData is a valid signature for event: rebuilds the expected signing hash from event data, compares it to the announced hash, then ECDSA-verifies the signature against the correct TSS pubkey (current for SIGN_OUTBOUND, OldTssPubkey for SIGN_FUND_MIGRATE). The sender's announced hash is not trusted — only the event-bound rebuild is.

type Message 

type Message struct {
	Type         MessageType `json:"type"`
	EventID      string      `json:"eventId"`
	Payload      []byte      `json:"payload"`
	Participants []string    `json:"participants"` // PartyIDs (validator addresses)

	// UnsignedSigningReq is set on SIGN setup messages so participants can
	// verify the signing hash independently.
	UnsignedSigningReq *common.UnsignedSigningReq `json:"unsigned_outbound_tx_req,omitempty"`

	// SignedData is set on an ACK to report a prior signature for this event.
	SignedData *SignedDataPayload `json:"signed_data,omitempty"`
}

Message is the wire format for all TSS coordination messages.

type MessageType added in v0.0.40 

type MessageType string

MessageType discriminates inter-node TSS coordination messages. 

const (
	MessageTypeSetup              MessageType = "setup"               // coordinator → participants: start a session
	MessageTypeACK                MessageType = "ack"                 // participant → coordinator: ready (or SignedData attached → already signed)
	MessageTypeBegin              MessageType = "begin"               // coordinator → participants: all ACKed, run
	MessageTypeStep               MessageType = "step"                // participant ↔ participant: DKLS protocol round
	MessageTypeSignatureBroadcast MessageType = "signature_broadcast" // participant → all UVs: signature ready, persist & participate in voting
)

type PushCoreClient added in v0.0.40 

type PushCoreClient interface {
	GetLatestBlock(ctx context.Context) (uint64, error)
	GetCurrentKey(ctx context.Context) (*utsstypes.TssKey, error)
	GetKeyByID(ctx context.Context, keyID string) (*utsstypes.TssKey, error)
	GetAllUniversalValidators(ctx context.Context) ([]*types.UniversalValidator, error)
}

PushCoreClient is the subset of pushcore.Client the coordinator depends on. Defined as an interface so tests can inject a mock without spinning up a real Push Chain RPC endpoint. *pushcore.Client satisfies this interface.

type SendFunc 

type SendFunc func(ctx context.Context, peerID string, data []byte) error

SendFunc sends `data` to `peerID` over the p2p network.

type SignedDataPayload added in v0.0.40 

type SignedDataPayload struct {
	Signature   []byte `json:"signature"`    // ECDSA (r || s [|| v])
	SigningHash []byte `json:"signing_hash"` // 32-byte message hash
	Nonce       uint64 `json:"nonce"`        // EVM nonce; ignored by SVM
}

SignedDataPayload is an already-produced signature. Attached to an ACK when the participant already holds a valid signature for this event, letting the coordinator skip a fresh DKLS run.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.