threshold

package
v1.22.78 Latest Latest
Warning

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

 Go to latest Published: Jan 1, 2026 License: BSD-3-Clause Imports: 12 Imported by: 0

Documentation

Overview

Package threshold provides EVM precompiles for threshold cryptography operations via the T-Chain (ThresholdVM). These precompiles enable smart contracts to request threshold signatures, DKG, and key management through Warp messaging.

Index

Constants

View Source 
const (
	// ThresholdAddress is the main threshold precompile address
	// Address: 0x0300000000000000000000000000000000000010
	ThresholdAddress = "0x0300000000000000000000000000000000000010"

	// Gas costs for operations
	GasCreateKey       uint64 = 100000 // DKG is expensive
	GasThresholdSign   uint64 = 50000  // Threshold signing
	GasVerifySignature uint64 = 3000   // Signature verification
	GasRefreshShares   uint64 = 75000  // Share refresh
	GasReshareKey      uint64 = 100000 // Key resharing
	GasGetPublicKey    uint64 = 200    // Simple read
	GasGetParticipants uint64 = 500    // Read participant list
)

Precompile addresses for threshold operations

View Source 
const (
	StatusPending   uint8 = 0
	StatusRunning   uint8 = 1
	StatusCompleted uint8 = 2
	StatusFailed    uint8 = 3
	StatusExpired   uint8 = 4
)

Session status codes

View Source 
const (
	ProtocolLSS      = "lss"
	ProtocolCGGMP21  = "cggmp21"
	ProtocolBLS      = "bls"
	ProtocolRingtail = "ringtail"
	ProtocolFrost    = "frost"
)

Protocol identifiers matching thresholdvm/protocols.go

View Source 
const (
	PayloadVersionV1 uint8 = 0x01

	// Threshold operation types
	PayloadTypeKeygenRequest  uint8 = 0x10
	PayloadTypeKeygenResult   uint8 = 0x11
	PayloadTypeSignRequest    uint8 = 0x12
	PayloadTypeSignResult     uint8 = 0x13
	PayloadTypeRefreshRequest uint8 = 0x14
	PayloadTypeRefreshResult  uint8 = 0x15
	PayloadTypeReshareRequest uint8 = 0x16
	PayloadTypeReshareResult  uint8 = 0x17
	PayloadTypeQueryRequest   uint8 = 0x18
	PayloadTypeQueryResult    uint8 = 0x19
)

Warp payload type identifiers for threshold operations

View Source 
const (
	ResultStatusSuccess uint8 = 0x00
	ResultStatusFailed  uint8 = 0x01
	ResultStatusPending uint8 = 0x02
	ResultStatusExpired uint8 = 0x03
)

Result status codes

Variables

View Source 
var (
	// createThresholdKey(bytes32 keyId, string protocol, uint8 threshold, uint8 totalParties) returns (bytes32 sessionId)
	SelectorCreateKey = [4]byte{0x12, 0x34, 0x56, 0x78}

	// thresholdSign(bytes32 keyId, bytes32 messageHash) returns (bytes32 sessionId)
	SelectorSign = [4]byte{0x23, 0x45, 0x67, 0x89}

	// verifyThresholdSignature(bytes publicKey, bytes32 messageHash, bytes signature) returns (bool)
	SelectorVerify = [4]byte{0x34, 0x56, 0x78, 0x9a}

	// refreshShares(bytes32 keyId) returns (bytes32 sessionId)
	SelectorRefresh = [4]byte{0x45, 0x67, 0x89, 0xab}

	// reshareKey(bytes32 keyId, address[] newParticipants, uint8 newThreshold) returns (bytes32 sessionId)
	SelectorReshare = [4]byte{0x56, 0x78, 0x9a, 0xbc}

	// getPublicKey(bytes32 keyId) returns (bytes)
	SelectorGetPublicKey = [4]byte{0x67, 0x89, 0xab, 0xcd}

	// getParticipants(bytes32 keyId) returns (address[])
	SelectorGetParticipants = [4]byte{0x78, 0x9a, 0xbc, 0xde}

	// getSignature(bytes32 sessionId) returns (bytes32 r, bytes32 s, uint8 v)
	SelectorGetSignature = [4]byte{0x89, 0xab, 0xcd, 0xef}

	// getSessionStatus(bytes32 sessionId) returns (uint8 status, string error)
	SelectorGetStatus = [4]byte{0x9a, 0xbc, 0xde, 0xf0}
)

Function selectors (first 4 bytes of keccak256 hash of function signature)

View Source 
var (
	ErrInvalidInput     = errors.New("invalid input")
	ErrInvalidSelector  = errors.New("invalid function selector")
	ErrUnauthorized     = errors.New("unauthorized caller")
	ErrSessionNotFound  = errors.New("session not found")
	ErrKeyNotFound      = errors.New("key not found")
	ErrInvalidProtocol  = errors.New("invalid protocol")
	ErrInvalidThreshold = errors.New("invalid threshold")
	ErrWarpSendFailed   = errors.New("warp message send failed")
)

Error definitions

View Source 
var (
	ErrPayloadTooShort       = errors.New("payload too short")
	ErrInvalidPayloadVersion = errors.New("invalid payload version")
	ErrInvalidPayloadType    = errors.New("invalid payload type")
)

Functions

func FormatSignature 

func FormatSignature(r, s [32]byte, v uint8) []byte

FormatSignature formats r, s, v into a 65-byte signature.

func HexToBytes32 

func HexToBytes32(hexStr string) ([32]byte, error)

HexToBytes32 converts a hex string to a 32-byte array.

func ParseSignature 

func ParseSignature(sig []byte) (r [32]byte, s [32]byte, v uint8, err error)

ParseSignature parses a 65-byte signature into r, s, v.

func PublicKeyToAddress 

func PublicKeyToAddress(pubKey []byte) [20]byte

PublicKeyToAddress converts a secp256k1 public key to an Ethereum address.

func RequestIDFromKeyAndMessage 

func RequestIDFromKeyAndMessage(keyID [32]byte, messageHash [32]byte) [32]byte

RequestIDFromKeyAndMessage generates a deterministic request ID.

func VerifySignature 

func VerifySignature(pubKey []byte, messageHash []byte, r, s *big.Int) bool

VerifySignature verifies an ECDSA signature using secp256k1.

Types

type CompletedSignature 

type CompletedSignature struct {
	RequestID    [32]byte
	KeyID        [32]byte
	R            [32]byte
	S            [32]byte
	V            uint8
	MessageHash  [32]byte
	CompletedAt  time.Time
	ValidatorSig [32]byte // Aggregated BLS signature from T-Chain validators
}

CompletedSignature holds a signature result from T-Chain.

type KeyInfo 

type KeyInfo struct {
	KeyID        [32]byte
	Protocol     string
	PublicKey    []byte
	Threshold    uint8
	TotalParties uint8
	Participants [][20]byte
	Generation   uint64
	CreatedAt    time.Time
	LastUsedAt   time.Time
}

KeyInfo caches threshold key information.

type KeygenRequestPayload 

type KeygenRequestPayload struct {
	RequestID     [32]byte
	KeyID         [32]byte
	SourceChainID [32]byte
	Protocol      uint8
	Threshold     uint8
	TotalParties  uint8
	Nonce         uint64
	Expiry        int64
	Requester     [20]byte
}

KeygenRequestPayload is the Warp payload for DKG requests to T-Chain. Wire format: 

[0]:      version (1 byte)
[1]:      type (1 byte) = 0x10
[2:34]:   request_id (32 bytes)
[34:66]:  key_id (32 bytes)
[66:98]:  source_chain_id (32 bytes)
[98]:     protocol (1 byte) - 0=LSS, 1=CMP, 2=BLS, 3=Ringtail, 4=FROST
[99]:     threshold (1 byte)
[100]:    total_parties (1 byte)
[101:109]: nonce (8 bytes)
[109:117]: expiry (8 bytes, unix timestamp)
[117:137]: requester (20 bytes, caller address)

func ParseKeygenRequestPayload 

func ParseKeygenRequestPayload(data []byte) (*KeygenRequestPayload, error)

ParseKeygenRequestPayload parses a keygen request from wire format.

func (*KeygenRequestPayload) Bytes 

func (p *KeygenRequestPayload) Bytes() []byte

Bytes serializes the keygen request to wire format.

type PendingRequest 

type PendingRequest struct {
	RequestID    [32]byte
	RequestType  uint8
	KeyID        [32]byte
	CreatedAt    time.Time
	ExpiresAt    time.Time
	Requester    [20]byte
	Callback     [20]byte
	CallbackData []byte
	Status       uint8
}

PendingRequest tracks a request waiting for T-Chain response.

type RefreshRequestPayload 

type RefreshRequestPayload struct {
	RequestID     [32]byte
	KeyID         [32]byte
	SourceChainID [32]byte
	Nonce         uint64
	Expiry        int64
	Requester     [20]byte
}

RefreshRequestPayload is the Warp payload for key share refresh requests.

func (*RefreshRequestPayload) Bytes 

func (p *RefreshRequestPayload) Bytes() []byte

Bytes serializes the refresh request to wire format.

type ReshareRequestPayload 

type ReshareRequestPayload struct {
	RequestID       [32]byte
	KeyID           [32]byte
	SourceChainID   [32]byte
	NewThreshold    uint8
	NumParticipants uint8
	Participants    [][20]byte // Variable length
	Nonce           uint64
	Expiry          int64
	Requester       [20]byte
}

ReshareRequestPayload is the Warp payload for key resharing requests.

func (*ReshareRequestPayload) Bytes 

func (p *ReshareRequestPayload) Bytes() []byte

Bytes serializes the reshare request to wire format.

type SignRequestPayload 

type SignRequestPayload struct {
	RequestID        [32]byte
	KeyID            [32]byte
	MessageHash      [32]byte
	SourceChainID    [32]byte
	Nonce            uint64
	Expiry           int64
	Requester        [20]byte
	Callback         [20]byte
	CallbackSelector [4]byte
}

SignRequestPayload is the Warp payload for threshold signing requests. Wire format: 

[0]:      version (1 byte)
[1]:      type (1 byte) = 0x12
[2:34]:   request_id (32 bytes)
[34:66]:  key_id (32 bytes)
[66:98]:  message_hash (32 bytes)
[98:130]: source_chain_id (32 bytes)
[130:138]: nonce (8 bytes)
[138:146]: expiry (8 bytes)
[146:166]: requester (20 bytes)
[166:186]: callback (20 bytes)
[186:190]: callback_selector (4 bytes)

func ParseSignRequestPayload 

func ParseSignRequestPayload(data []byte) (*SignRequestPayload, error)

ParseSignRequestPayload parses a sign request from wire format.

func (*SignRequestPayload) Bytes 

func (p *SignRequestPayload) Bytes() []byte

Bytes serializes the sign request to wire format.

type SignResultPayload 

type SignResultPayload struct {
	RequestID          [32]byte
	Status             uint8
	R                  [32]byte
	S                  [32]byte
	V                  uint8
	CommitteeSignature [32]byte
}

SignResultPayload is the Warp payload for signature results from T-Chain. Wire format: 

[0]:      version (1 byte)
[1]:      type (1 byte) = 0x13
[2:34]:   request_id (32 bytes)
[34]:     status (1 byte)
[35:67]:  r (32 bytes)
[67:99]:  s (32 bytes)
[99]:     v (1 byte)
[100:132]: committee_signature (32 bytes) - aggregated validator signature

func ParseSignResultPayload 

func ParseSignResultPayload(data []byte) (*SignResultPayload, error)

ParseSignResultPayload parses a sign result from wire format.

func (*SignResultPayload) Bytes 

func (p *SignResultPayload) Bytes() []byte

Bytes serializes the sign result to wire format.

type ThresholdPrecompile 

type ThresholdPrecompile struct {
	// TChainID is the subnet ID for the T-Chain
	TChainID ids.ID
	// contains filtered or unexported fields
}

ThresholdPrecompile implements the EVM precompile interface for threshold operations. It communicates with T-Chain via Warp messaging.

func NewThresholdPrecompile 

func NewThresholdPrecompile(tChainID ids.ID, sender WarpSender) *ThresholdPrecompile

NewThresholdPrecompile creates a new threshold precompile instance.

func (*ThresholdPrecompile) RequiredGas 

func (p *ThresholdPrecompile) RequiredGas(input []byte) uint64

RequiredGas returns the gas required for a given input.

func (*ThresholdPrecompile) Run 

func (p *ThresholdPrecompile) Run(input []byte) ([]byte, error)

Run executes the precompile function.

type WarpHandler 

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

WarpHandler handles incoming Warp messages from T-Chain and routes them to the appropriate callback contracts.

func NewWarpHandler 

func NewWarpHandler() *WarpHandler

NewWarpHandler creates a new Warp message handler.

func (*WarpHandler) AddPendingRequest 

func (h *WarpHandler) AddPendingRequest(req *PendingRequest) error

AddPendingRequest adds a new pending request.

func (*WarpHandler) CleanupExpired 

func (h *WarpHandler) CleanupExpired()

CleanupExpired removes expired pending requests.

func (*WarpHandler) GetKeyInfo 

func (h *WarpHandler) GetKeyInfo(keyID [32]byte) (*KeyInfo, error)

GetKeyInfo retrieves cached key information.

func (*WarpHandler) GetRequestStatus 

func (h *WarpHandler) GetRequestStatus(requestID [32]byte) (uint8, error)

GetRequestStatus returns the status of a request.

func (*WarpHandler) GetSignature 

func (h *WarpHandler) GetSignature(requestID [32]byte) (*CompletedSignature, error)

GetSignature retrieves a completed signature.

func (*WarpHandler) HandleWarpMessage 

func (h *WarpHandler) HandleWarpMessage(ctx context.Context, sourceChainID ids.ID, payload []byte) error

HandleWarpMessage processes an incoming Warp message from T-Chain.

type WarpSender 

type WarpSender interface {
	// SendCrossChainMessage sends a Warp message to the destination chain
	SendCrossChainMessage(destChainID ids.ID, payload []byte) error
}

WarpSender interface for sending Warp messages to T-Chain

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.