chain

package
v1.8.1 Latest Latest
Warning

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

 Go to latest Published: Dec 15, 2021 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package chain contains interface for interaction with a blockchain that implements ECDSA keep functionality, along with structures reflecting events needed for that functionality.

Index

Constants

This section is empty.

Variables

View Source 
var ErrDepositNotFunded = errors.New("deposit not funded")

ErrDepositNotFunded is an error returned when a deposit has not been funded.

Functions

func ParseUtxoOutpoint added in v1.8.0 

func ParseUtxoOutpoint(utxoOutpoint []uint8) (string, uint32, error)

ParseUtxoOutpoint parses a 36-byte utxo outpoint into a transaction hash and an output index. The first 32 bytes in reverse represet the transaction hash, and the last 4 bytes are a little-endian represention of the output index.

func SerializePublicKey 

func SerializePublicKey(publicKey *cecdsa.PublicKey) ([64]byte, error)

SerializePublicKey takes X and Y coordinates of a signer's public key and concatenates it to a 64-byte long array. If any of coordinates is shorter than 32-byte it is preceded with zeros.

func UtxoValueBytesToUint32 added in v1.8.0 

func UtxoValueBytesToUint32(utxoValueBytes [8]uint8) uint32

UtxoValueBytesToUint32 converts utxo value from little endian bytes8 that is returned from chain to uin32.

Types

type BondedECDSAKeepApplicationHandle added in v1.8.0 

type BondedECDSAKeepApplicationHandle interface {
	// ID returns the id of this application in a host chain-agnostic format.
	ID() ID

	// RegisterAsMemberCandidate registers this instance's operator as a
	// candidate to be selected to a keep.
	RegisterAsMemberCandidate() error

	// IsRegisteredForApplication checks if this instance's operator is
	// registered as a signer candidate in the factory for the given
	// application.
	IsRegisteredForApplication() (bool, error)

	// IsEligibleForApplication checks if this instance's operator is eligible
	// to register as a signer candidate for the given application.
	IsEligibleForApplication() (bool, error)

	// IsStatusUpToDateForApplication checks if this instance's operator's
	// status is up to date in the signers' pool of the given application.
	IsStatusUpToDateForApplication() (bool, error)

	// UpdateStatusForApplication updates this instance's operator's status in
	// the signers' pool for the given application.
	UpdateStatusForApplication() error
}

BondedECDSAKeepApplicationHandle is a handle to a specific application that is allowed to use ECDSA keeps and their respective bonds for operations. Such applications may require keeping the host chain up-to-date on the operator's available bond for sortition purposes, and generally each operator's authorizer will need to authorize the specific application to operate on their stake. The BondedECDSAKeepApplicationHandle provides methods that wrap this on-chain functionality.

type BondedECDSAKeepCreatedEvent 

type BondedECDSAKeepCreatedEvent struct {
	Keep                 BondedECDSAKeepHandle
	MemberIDs            []ID // keep member ids
	HonestThreshold      uint64
	BlockNumber          uint64
	ThisOperatorIsMember bool
}

BondedECDSAKeepCreatedEvent is an event emitted on a new keep creation.

type BondedECDSAKeepFactory 

type BondedECDSAKeepFactory interface {
	// TBTCApplicationHandle returns a handle for interacting with the tBTC
	// application associated with this BondedECDSAKeepManager. Returns nil with
	// an error if no tBTC application exists for this manager.
	TBTCApplicationHandle() (TBTCHandle, error)

	// OnBondedECDSAKeepCreated installs a callback that is invoked when an
	// on-chain notification of a new bonded ECDSA keep creation is seen.
	OnBondedECDSAKeepCreated(
		handler func(event *BondedECDSAKeepCreatedEvent),
	) subscription.EventSubscription

	// IsOperatorAuthorized checks if the factory has the authorization to
	// operate on stake represented by the provided operator.
	IsOperatorAuthorized(operator ID) (bool, error)

	// GetKeepCount returns number of keeps.
	GetKeepCount() (*big.Int, error)

	// GetKeepAtIndex returns a handle to the keep at the given index.
	GetKeepAtIndex(keepIndex *big.Int) (BondedECDSAKeepHandle, error)
	// GetKeepWithID returns a handle to the keep with the given ID.
	GetKeepWithID(keepID ID) (BondedECDSAKeepHandle, error)
}

BondedECDSAKeepFactory is an interface that provides ability to interact with BondedECDSAKeepFactory ethereum contracts.

type BondedECDSAKeepHandle added in v1.8.0 

type BondedECDSAKeepHandle interface {
	// ID returns the id of this keep in a host chain-agnostic format.
	ID() ID

	// OnSignatureRequested installs a callback that is invoked when an on-chain
	// notification of a new signing request for a given keep is seen.
	OnSignatureRequested(
		handler func(event *SignatureRequestedEvent),
	) (subscription.EventSubscription, error)

	// OnConflictingPublicKeySubmitted installs a callback that is invoked upon
	// notification of mismatched public keys that were submitted by keep members.
	OnConflictingPublicKeySubmitted(
		handler func(event *ConflictingPublicKeySubmittedEvent),
	) (subscription.EventSubscription, error)

	// OnPublicKeyPublished installs a callback that is invoked upon
	// notification of a published public key, which means that all members have
	// submitted the same key.
	OnPublicKeyPublished(
		handler func(event *PublicKeyPublishedEvent),
	) (subscription.EventSubscription, error)

	// SubmitKeepPublicKey submits a 64-byte serialized public key to a keep
	// contract deployed under a given address.
	SubmitKeepPublicKey(publicKey [64]byte) error

	// SubmitSignature submits a signature to a keep contract deployed under a
	// given address.
	SubmitSignature(signature *ecdsa.Signature) error

	// OnKeepClosed installs a callback that will be called on closing the
	// given keep.
	OnKeepClosed(
		handler func(event *KeepClosedEvent),
	) (subscription.EventSubscription, error)

	// OnKeepTerminated installs a callback that will be called on terminating
	// the given keep.
	OnKeepTerminated(
		handler func(event *KeepTerminatedEvent),
	) (subscription.EventSubscription, error)

	// IsAwaitingSignature checks if the keep is waiting for a signature to be
	// calculated for the given digest.
	IsAwaitingSignature(digest [32]byte) (bool, error)

	// IsActive checks if the keep with the given address is active and responds
	// to signing request. This function returns false only for closed keeps.
	IsActive() (bool, error)

	// LatestDigest returns the latest digest requested to be signed.
	LatestDigest() ([32]byte, error)

	// SignatureRequestedBlock returns block number from the moment when a
	// signature was requested for the given digest from a keep.
	// If a signature was not requested for the given digest, returns 0.
	SignatureRequestedBlock(digest [32]byte) (uint64, error)

	// GetPublicKey returns keep's public key. If there is no public key yet,
	// an empty slice is returned.
	GetPublicKey() ([]uint8, error)

	// GetMembers returns keep's members.
	GetMembers() ([]ID, error)

	// GetOwner returns the keep's owner.
	GetOwner() (ID, error)

	// IsThisOperatorMember returns true if the current operator belongs to the
	// BondedECDSAKeep represented by this handle, false otherwise, or an error
	// if the process of determining this fails.
	IsThisOperatorMember() (bool, error)

	// OperatorIndex returns the index of the current operator in this keep's
	// set of members, or an error if the process of determining this fails. If
	// the operator is not a member this will return -1 (and no error) and
	// IsOperatorMember will return false.
	OperatorIndex() (int, error)

	// GetHonestThreshold returns keep's honest threshold.
	GetHonestThreshold() (uint64, error)

	// GetOpenedTimestamp returns timestamp when the keep was created.
	GetOpenedTimestamp() (time.Time, error)

	// PastSignatureSubmittedEvents returns all signature submitted events
	// for the given keep which occurred after the provided start block.
	// All implementations should returns those events sorted by the
	// block number in the ascending order.
	PastSignatureSubmittedEvents(
		startBlock uint64,
	) ([]*SignatureSubmittedEvent, error)
}

BondedECDSAKeepHandle is an interface that provides ability to interact with a single bonded ECDSA keep's on-chain component. A bonded ECDSA keep is a threshold signing group that has a corresponding bond amount securing its honest cooperation in the threshold signature application that the keep corresponds to.

type Config added in v1.8.0 

type Config struct {
	TBTCSystem string
}

Config stores configuration of application extension responsible for executing signer actions specific for TBTC application.

type ConflictingPublicKeySubmittedEvent 

type ConflictingPublicKeySubmittedEvent struct {
	SubmittingMember     ID
	ConflictingPublicKey []byte
	BlockNumber          uint64
}

ConflictingPublicKeySubmittedEvent is an event emitted each time when one of the members of a keep has submitted a key that does not match the keys submitted so far by other members.

type Deposit added in v1.5.0 

type Deposit interface {
	// Keep returns the underlying keep for the provided deposit.
	Keep(depositAddress string) (BondedECDSAKeepHandle, error)

	// RetrieveSignerPubkey retrieves the signer public key for the
	// provided deposit.
	RetrieveSignerPubkey(depositAddress string) error

	// ProvideRedemptionSignature provides the redemption signature for the
	// provided deposit.
	ProvideRedemptionSignature(
		depositAddress string,
		v uint8,
		r [32]uint8,
		s [32]uint8,
	) error

	// IncreaseRedemptionFee increases the redemption fee for the
	// provided deposit.
	IncreaseRedemptionFee(
		depositAddress string,
		previousOutputValueBytes [8]uint8,
		newOutputValueBytes [8]uint8,
	) error

	// ProvideRedemptionProof provides the redemption proof for the
	// provided deposit.
	ProvideRedemptionProof(
		depositAddress string,
		txVersion [4]uint8,
		txInputVector []uint8,
		txOutputVector []uint8,
		txLocktime [4]uint8,
		merkleProof []uint8,
		txIndexInBlock *big.Int,
		bitcoinHeaders []uint8,
	) error

	// CurrentState returns the current state for the provided deposit.
	CurrentState(depositAddress string) (DepositState, error)
}

Deposit is an interface that provides ability to interact with Deposit contracts.

type DepositRedemptionRequestedEvent added in v1.5.0 

type DepositRedemptionRequestedEvent struct {
	DepositAddress       string
	RequesterAddress     string
	Digest               [32]byte
	UtxoValue            *big.Int
	RedeemerOutputScript []byte
	RequestedFee         *big.Int
	Outpoint             []byte
	BlockNumber          uint64
}

DepositRedemptionRequestedEvent is an event emitted when a deposit redemption has been requested or the redemption fee has been increased.

type DepositState added in v1.5.0 

type DepositState int

DepositState represents the deposit state. 

const (
	// Start is initial deposit state
	Start DepositState = iota
	// AwaitingSignerSetup represents that the system is awaiting the signers to set up
	AwaitingSignerSetup
	// AwaitingBtcFundingProof represents that the system is awaiting proof that BTC funding has occured
	AwaitingBtcFundingProof
	// FailedSetup represents that the setup has failed
	FailedSetup
	// Active represents that the BTC has been secured and the TDT has been issued
	Active
	// AwaitingWithdrawalSignature represents that the redemption process has started, and is waiting on a signature
	AwaitingWithdrawalSignature
	// AwaitingWithdrawalProof represents that the remption process is waiting on proof of redemption on the BTC blockchain
	AwaitingWithdrawalProof
	// Redeemed represents that the BTC has been dispersed and the TDT/TBTC has been destroyed
	Redeemed
	// CourtesyCall represents that the keep is in danger of being liquidated, and so should be redeemed immediately
	CourtesyCall
	// FraudLiquidationInProgress means that fraud was detected, and so the keep is being liquidated
	FraudLiquidationInProgress
	// LiquidationInProgress means that the system has seized the eth collateral and the signers are trying to recover the held BTC
	LiquidationInProgress
	// Liquidated means that the system seized the eth collateral and the signers recovered the held BTC
	Liquidated
)

type FundingInfo added in v1.8.0 

type FundingInfo struct {
	UtxoValueBytes  [8]uint8
	FundedAt        *big.Int
	TransactionHash string
	OutputIndex     uint32
}

FundingInfo represents the funding information for a tbtc deposit

type Handle 

type Handle interface {
	OfflineHandle

	// StakeMonitor returns a stake monitor.
	StakeMonitor() (chain.StakeMonitor, error)
	// BlockCounter returns a block counter.
	BlockCounter() chain.BlockCounter
	// Signing returns a signer interface allowing to sign and verify messages
	// using the chain implementation-specific mechanism as well as to
	// convert between public key and address.
	Signing() chain.Signing
	// BlockTimestamp returns given block's timestamp.
	// In case the block is not yet mined, an error should be returned.
	BlockTimestamp(blockNumber *big.Int) (uint64, error)

	BondedECDSAKeepFactory
}

Handle represents a handle to a host chain that anchors ECDSA client applications.

type ID added in v1.8.0 

type ID interface {
	fmt.Stringer

	ChainName() string
	IsForChain(handle Handle) bool
}

ID represents a generic id on a given chain. The underlying chain's name is provided by the ChainName func, and a method is provided to check whether the ID is for a particular chain.

IDs should not be considered interchangeable between different chain instances, and generally uses on a given chain should guard using a `ForChain` call.

type KeepClosedEvent 

type KeepClosedEvent struct {
	BlockNumber uint64
}

KeepClosedEvent is an event emitted when a keep has been closed.

type KeepTerminatedEvent 

type KeepTerminatedEvent struct {
	BlockNumber uint64
}

KeepTerminatedEvent is an event emitted when a keep has been terminated.

type OfflineHandle added in v1.8.0 

type OfflineHandle interface {
	// Return a simple name for this chain handle. This name should consist only
	// of lowercase letters, numbers, and - or _, and should start with a letter
	// (that is, it should conform to the regular expression [a-z][a-z0-9-_]*).
	// It should describe the chain in a way distinguishable from other chains,
	// and generally should be the name of the underlying chain. It can include
	// additional information such as the name of the specific network (e.g.
	// mainnet or the name of a testnet) if desired, but should be stable for a
	// given network indefinitely once the chain has been used in production.
	//
	// This name may be used to construct persistence paths that need to work
	// across node instances, and in general is expected to be stable across
	// executable instances and different remote chain nodes.
	Name() string

	// OperatorID returns operator ID for the client this handle represents on chain.
	OperatorID() ID

	// PublicKeyToOperatorID takes a public key in Go crypto package format and
	// returns an OperatorID suitable for use with any component interacting
	// with this chain handle.
	PublicKeyToOperatorID(publicKey *cecdsa.PublicKey) ID

	// UnmarshalID takes an ID string produced by this chain in the past and
	// unmarshals it into a KeepID object for this chain. Returns an error if
	// the ID string was invalid. It should be safe to call this function from
	// multiple goroutines.
	//
	// Note that unmarshaling the ID used by one chain from a string produced by
	// a different chain is not supported and could lead to unexpected behavior.
	UnmarshalID(idString string) (ID, error)
}

OfflineHandle represents a handle to a host chain without a backing chain connection. It cannot perform any actions that require state information from the host chain, but provides access to functionality used for interfacing with other parts of the system such as persistence and Keep network connections.

type PublicKeyPublishedEvent 

type PublicKeyPublishedEvent struct {
	PublicKey   []byte
	BlockNumber uint64
}

PublicKeyPublishedEvent is an event emitted once all the members have submitted the same public key and it was accepted by keep as its public key.

type SignatureRequestedEvent 

type SignatureRequestedEvent struct {
	Digest      [32]byte
	BlockNumber uint64
}

SignatureRequestedEvent is an event emitted when a user requests a digest to be signed.

type SignatureSubmittedEvent added in v1.5.0 

type SignatureSubmittedEvent struct {
	Digest      [32]byte
	R           [32]byte
	S           [32]byte
	RecoveryID  uint8
	BlockNumber uint64
}

SignatureSubmittedEvent is an event emitted when a keep submits a signature.

type TBTCHandle added in v1.5.0 

type TBTCHandle interface {
	BondedECDSAKeepApplicationHandle

	Deposit
	TBTCSystem
}

TBTCHandle represents handle to the tBTC on-chain application. It extends the BondedECDSAKeepApplicationHandle interface with tBTC-specific functionality.

type TBTCSystem added in v1.5.0 

type TBTCSystem interface {
	// OnDepositCreated installs a callback that is invoked when an
	// on-chain notification of a new deposit creation is seen.
	OnDepositCreated(
		handler func(depositAddress string),
	) subscription.EventSubscription

	// OnDepositRegisteredPubkey installs a callback that is invoked when an
	// on-chain notification of a deposit's pubkey registration is seen.
	OnDepositRegisteredPubkey(
		handler func(depositAddress string),
	) subscription.EventSubscription

	// OnDepositRedemptionRequested installs a callback that is invoked when an
	// on-chain notification of a deposit redemption request is seen.
	OnDepositRedemptionRequested(
		handler func(depositAddress string),
	) subscription.EventSubscription

	// OnDepositGotRedemptionSignature installs a callback that is invoked
	// when an on-chain notification of a deposit receiving a redemption
	// signature is seen.
	OnDepositGotRedemptionSignature(
		handler func(depositAddress string),
	) subscription.EventSubscription

	// OnDepositRedeemed installs a callback that is invoked when an
	// on-chain notification of a deposit redemption is seen.
	OnDepositRedeemed(
		handler func(depositAddress string),
	) subscription.EventSubscription

	// PastDepositRedemptionRequestedEvents returns all redemption requested
	// events for the given deposit which occurred after the provided start block.
	// All implementations should return those events sorted by the
	// block number in the ascending order.
	PastDepositRedemptionRequestedEvents(
		startBlock uint64,
		depositAddress string,
	) ([]*DepositRedemptionRequestedEvent, error)

	// FundingInfo retrieves the funding info for a particular deposit address
	//
	// Returns ErrDepositNotFunded error if the deposit has not been funded.
	FundingInfo(
		depositAddress string,
	) (*FundingInfo, error)
}

TBTCSystem is an interface that provides ability to interact with TBTCSystem contract.

Source Files

View all Source files

Directories

Path Synopsis
Package ethereum contains implementation of ethereum chain interface.
 Package ethereum contains implementation of ethereum chain interface.
gen
celo
celo/abi
celo/cmd
celo/contract
ethereum
ethereum/abi
ethereum/cmd
ethereum/contract

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.