tbtc

package
v0.0.0-...-369a1d7 Latest Latest
Warning

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

 Go to latest Published: Aug 6, 2024 License: MIT Imports: 45 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// DKGSeedCachePeriod is the time period the cache maintains
	// the DKG seed corresponding to a DKG instance.
	DKGSeedCachePeriod = 7 * 24 * time.Hour
	// DKGResultHashCachePeriod is the time period the cache maintains
	// the given DKG result hash.
	DKGResultHashCachePeriod = 7 * 24 * time.Hour
	// WalletClosedCachePeriod is the time period the cache maintains the ID of
	// a closed wallet.
	WalletClosedCachePeriod = 7 * 24 * time.Hour
)
View Source 
const (
	DefaultPreParamsPoolSize              = 1000
	DefaultPreParamsGenerationTimeout     = 2 * time.Minute
	DefaultPreParamsGenerationDelay       = 10 * time.Second
	DefaultPreParamsGenerationConcurrency = 1
)
View Source 
const (

	// DepositSweepRequiredFundingTxConfirmations determines the minimum
	// number of confirmations that are needed for a deposit funding Bitcoin
	// transaction in order to consider it a valid part of the deposit sweep
	// proposal.
	DepositSweepRequiredFundingTxConfirmations = 6
)
View Source 
const MovingFundsCommitmentLookBackBlocks = uint64(216000)

MovingFundsCommitmentLookBackBlocks is the look-back period in blocks used when searching for submitted moving funds commitment events. It's equal to 30 days assuming 12 seconds per block.

View Source 
const ProtocolName = "tbtc"

ProtocolName denotes the name of the protocol defined by this package.

Variables

View Source 
var DefaultKeyGenerationConcurrency = runtime.GOMAXPROCS(0)

Functions

func DetermineWalletMainUtxo 

func DetermineWalletMainUtxo(
	walletPublicKeyHash [20]byte,
	bridgeChain BridgeChain,
	btcChain bitcoin.Chain,
) (*bitcoin.UnspentTransactionOutput, error)

DetermineWalletMainUtxo determines the plain-text wallet main UTXO currently registered in the Bridge on-chain contract. The returned main UTXO can be nil if the wallet does not have a main UTXO registered in the Bridge at the moment.

func EnsureWalletSyncedBetweenChains 

func EnsureWalletSyncedBetweenChains(
	walletPublicKeyHash [20]byte,
	walletMainUtxo *bitcoin.UnspentTransactionOutput,
	bridgeChain BridgeChain,
	btcChain bitcoin.Chain,
) error

EnsureWalletSyncedBetweenChains makes sure all actions taken by the wallet on the Bitcoin chain are reflected in the host chain Bridge.

func Initialize 

func Initialize(
	ctx context.Context,
	chain Chain,
	btcChain bitcoin.Chain,
	netProvider net.Provider,
	keyStorePersistence persistence.ProtectedHandle,
	workPersistence persistence.BasicHandle,
	scheduler *generator.Scheduler,
	proposalGenerator CoordinationProposalGenerator,
	config Config,
	clientInfo *clientinfo.Registry,
) error

Initialize kicks off the TBTC by initializing internal state, ensuring preconditions like staking are met, and then kicking off the internal TBTC implementation. Returns an error if this failed.

func ValidateMovedFundsSweepProposal 

func ValidateMovedFundsSweepProposal(
	validateProposalLogger log.StandardLogger,
	walletPublicKeyHash [20]byte,
	proposal *MovedFundsSweepProposal,
	chain interface {
		// ValidateMovedFundsSweepProposal validates the given moved funds sweep
		// proposal against the chain. Returns an error if the proposal is not
		// valid or nil otherwise.
		ValidateMovedFundsSweepProposal(
			walletPublicKeyHash [20]byte,
			proposal *MovedFundsSweepProposal,
		) error
	},
) error

ValidateMovedFundsSweepProposal checks the moved funds sweep proposal with on-chain validation rules.

func ValidateMovingFundsProposal 

func ValidateMovingFundsProposal(
	validateProposalLogger log.StandardLogger,
	walletPublicKeyHash [20]byte,
	mainUTXO *bitcoin.UnspentTransactionOutput,
	proposal *MovingFundsProposal,
	chain interface {
		// ValidateMovingFundsProposal validates the given moving funds proposal
		// against the chain. Returns an error if the proposal is not valid or
		// nil otherwise.
		ValidateMovingFundsProposal(
			walletPublicKeyHash [20]byte,
			mainUTXO *bitcoin.UnspentTransactionOutput,
			proposal *MovingFundsProposal,
		) error

		BlockCounter() (chain.BlockCounter, error)

		GetWallet(walletPublicKeyHash [20]byte) (*WalletChainData, error)

		GetMovingFundsParameters() (
			txMaxTotalFee uint64,
			dustThreshold uint64,
			timeoutResetDelay uint32,
			timeout uint32,
			timeoutSlashingAmount *big.Int,
			timeoutNotifierRewardMultiplier uint32,
			commitmentGasOffset uint16,
			sweepTxMaxTotalFee uint64,
			sweepTimeout uint32,
			sweepTimeoutSlashingAmount *big.Int,
			sweepTimeoutNotifierRewardMultiplier uint32,
			err error,
		)

		PastMovingFundsCommitmentSubmittedEvents(
			filter *MovingFundsCommitmentSubmittedEventFilter,
		) ([]*MovingFundsCommitmentSubmittedEvent, error)
	},
) error

ValidateMovingFundsProposal checks the moving funds proposal with on-chain validation rules.

func ValidateMovingFundsSafetyMargin 

func ValidateMovingFundsSafetyMargin(
	walletPublicKeyHash [20]byte,
	chain interface {
		BlockCounter() (chain.BlockCounter, error)

		GetWallet(walletPublicKeyHash [20]byte) (*WalletChainData, error)

		GetMovingFundsParameters() (
			txMaxTotalFee uint64,
			dustThreshold uint64,
			timeoutResetDelay uint32,
			timeout uint32,
			timeoutSlashingAmount *big.Int,
			timeoutNotifierRewardMultiplier uint32,
			commitmentGasOffset uint16,
			sweepTxMaxTotalFee uint64,
			sweepTimeout uint32,
			sweepTimeoutSlashingAmount *big.Int,
			sweepTimeoutNotifierRewardMultiplier uint32,
			err error,
		)

		PastMovingFundsCommitmentSubmittedEvents(
			filter *MovingFundsCommitmentSubmittedEventFilter,
		) ([]*MovingFundsCommitmentSubmittedEvent, error)
	},
) error

ValidateMovingFundsSafetyMargin checks if the moving funds safety margin is in force.

Wallets that just entered the MovingFunds state may have received some last minute deposits just before. Even though deposit sweep typically occurs before moving funds, such deposits may not be mature enough or have enough confirmations to be swept yet. MovingFunds wallets cannot receive new deposits so, it makes sense to preserve a safety margin before moving funds to give the last minute deposits a chance to become eligible for deposit sweep.

Similarly, wallets that just entered the MovingFunds state may have become target wallets for another moving funds wallets. It makes sense to preserve a safety margin to allow the wallet to merge the moved funds from another wallets. In this case a longer safety margin should be used.

Types

type BridgeChain 

type BridgeChain interface {
	// CalculateWalletID calculates the wallet's ECDSA ID based on the provided
	// wallet public key.
	CalculateWalletID(walletPublicKey *ecdsa.PublicKey) ([32]byte, error)

	// IsWalletRegistered checks whether the given wallet is registered in the
	// ECDSA wallet registry.
	IsWalletRegistered(EcdsaWalletID [32]byte) (bool, error)

	// GetWallet gets the on-chain data for the given wallet. Returns an error
	// if the wallet was not found.
	GetWallet(walletPublicKeyHash [20]byte) (*WalletChainData, error)

	// OnWalletClosed registers a callback that is invoked when an on-chain
	// notification of the wallet closed is seen. The notification occurs when
	// the wallet is closed or terminated.
	OnWalletClosed(
		func(event *WalletClosedEvent),
	) subscription.EventSubscription

	// ComputeMainUtxoHash computes the hash of the provided main UTXO
	// according to the on-chain Bridge rules.
	ComputeMainUtxoHash(mainUtxo *bitcoin.UnspentTransactionOutput) [32]byte

	// PastDepositRevealedEvents fetches past deposit reveal events according
	// to the provided filter or unfiltered if the filter is nil. Returned
	// events are sorted by the block number in the ascending order, i.e. the
	// latest event is at the end of the slice.
	PastDepositRevealedEvents(
		filter *DepositRevealedEventFilter,
	) ([]*DepositRevealedEvent, error)

	// GetPendingRedemptionRequest gets the on-chain pending redemption request
	// for the given wallet public key hash and redeemer output script.
	// The returned bool value indicates whether the request was found or not.
	GetPendingRedemptionRequest(
		walletPublicKeyHash [20]byte,
		redeemerOutputScript bitcoin.Script,
	) (*RedemptionRequest, bool, error)

	// GetDepositRequest gets the on-chain deposit request for the given
	// funding transaction hash and output index. The returned bool value
	// indicates whether the request was found or not.
	GetDepositRequest(
		fundingTxHash bitcoin.Hash,
		fundingOutputIndex uint32,
	) (*DepositChainRequest, bool, error)

	// GetMovedFundsSweepRequest gets the on-chain moved funds sweep request for
	// the given moving funds transaction hash and output index.
	// The returned bool value indicates whether the request was found or not.
	GetMovedFundsSweepRequest(
		movingFundsTxHash bitcoin.Hash,
		movingFundsTxOutpointIndex uint32,
	) (*MovedFundsSweepRequest, bool, error)

	// GetMovingFundsParameters gets the current value of parameters relevant
	// for the moving funds process.
	GetMovingFundsParameters() (
		txMaxTotalFee uint64,
		dustThreshold uint64,
		timeoutResetDelay uint32,
		timeout uint32,
		timeoutSlashingAmount *big.Int,
		timeoutNotifierRewardMultiplier uint32,
		commitmentGasOffset uint16,
		sweepTxMaxTotalFee uint64,
		sweepTimeout uint32,
		sweepTimeoutSlashingAmount *big.Int,
		sweepTimeoutNotifierRewardMultiplier uint32,
		err error,
	)

	// PastMovingFundsCommitmentSubmittedEvents fetches past moving funds
	// commitment submitted events according to the provided filter or
	// unfiltered if the filter is nil. Returned events are sorted by the block
	// number in the ascending order, i.e. the latest event is at the end of the
	// slice.
	PastMovingFundsCommitmentSubmittedEvents(
		filter *MovingFundsCommitmentSubmittedEventFilter,
	) ([]*MovingFundsCommitmentSubmittedEvent, error)
}

BridgeChain defines the subset of the TBTC chain interface that pertains specifically to the tBTC Bridge operations.

type CalculateWalletIdFunc 

type CalculateWalletIdFunc func(walletPublicKey *ecdsa.PublicKey) ([32]byte, error)

CalculateWalletIDFunc calculates the ECDSA wallet ID based on the provided wallet public key.

type Chain 

type Chain interface {
	// BlockCounter returns the chain's block counter.
	BlockCounter() (chain.BlockCounter, error)
	// Signing returns the chain's signer.
	Signing() chain.Signing
	// OperatorKeyPair returns the key pair of the operator assigned to this
	// chain handle.
	OperatorKeyPair() (*operator.PrivateKey, *operator.PublicKey, error)
	// GetBlockNumberByTimestamp gets the block number for the given timestamp.
	// In the best case, the block with the exact same timestamp is returned.
	// If the aforementioned is not possible, it tries to return the closest
	// possible block.
	GetBlockNumberByTimestamp(timestamp uint64) (uint64, error)
	// GetBlockHashByNumber gets the block hash for the given block number.
	GetBlockHashByNumber(blockNumber uint64) ([32]byte, error)

	sortition.Chain
	GroupSelectionChain
	DistributedKeyGenerationChain
	InactivityClaimChain
	BridgeChain
	WalletProposalValidatorChain
}

Chain represents the interface that the TBTC module expects to interact with the anchoring blockchain on.

type Config 

type Config struct {
	// The size of the pre-parameters pool for tECDSA.
	PreParamsPoolSize int
	// Timeout for pre-parameters generation for tECDSA.
	PreParamsGenerationTimeout time.Duration
	// The delay between generating new pre-params for tECDSA.
	PreParamsGenerationDelay time.Duration
	// Concurrency level for pre-parameters generation for tECDSA.
	PreParamsGenerationConcurrency int
	// Concurrency level for key-generation for tECDSA.
	KeyGenerationConcurrency int
}

Config carries the config for tBTC protocol.

type CoordinationFaultType 

type CoordinationFaultType uint8

CoordinationFaultType represents a type of the coordination fault. 

const (
	// FaultUnknown is a fault type used when the fault type is unknown.
	FaultUnknown CoordinationFaultType = iota
	// FaultLeaderIdleness is a fault type used when the leader was idle, i.e.
	// missed their turn to propose a wallet action.
	FaultLeaderIdleness
	// FaultLeaderMistake is a fault type used when the leader's proposal
	// turned out to be invalid.
	FaultLeaderMistake
	// FaultLeaderImpersonation is a fault type used when the leader was
	// impersonated by another operator who raised their own proposal.
	FaultLeaderImpersonation
)

func (CoordinationFaultType) String 

func (cft CoordinationFaultType) String() string

type CoordinationProposal 

type CoordinationProposal interface {
	pb.Marshaler
	pb.Unmarshaler

	// ActionType returns the specific type of the walletAction being subject
	// of this proposal.
	ActionType() WalletActionType
	// ValidityBlocks returns the number of blocks for which the proposal is
	// valid. This value SHOULD NOT be marshaled/unmarshaled.
	ValidityBlocks() uint64
}

CoordinationProposal represents a single action proposal for the given wallet.

type CoordinationProposalGenerator 

type CoordinationProposalGenerator interface {
	// Generate generates a coordination proposal based on the given checklist
	// of possible wallet actions. The checklist is a list of actions that
	// should be checked for the given coordination window. The generator is
	// expected to return a proposal for the first action from the checklist
	// that is valid for the given wallet's state. If none of the actions are
	// valid, the generator should return a no-op proposal.
	Generate(request *CoordinationProposalRequest) (CoordinationProposal, error)
}

CoordinationProposalGenerator is a component responsible for generating coordination proposals.

type CoordinationProposalRequest 

type CoordinationProposalRequest struct {
	WalletPublicKeyHash [20]byte
	WalletOperators     []chain.Address
	ExecutingOperator   chain.Address
	ActionsChecklist    []WalletActionType
}

CoordinationProposalRequest represents a request for a coordination proposal.

type DKGChainResult 

type DKGChainResult struct {
	SubmitterMemberIndex     group.MemberIndex
	GroupPublicKey           []byte
	MisbehavedMembersIndexes []group.MemberIndex
	Signatures               []byte
	SigningMembersIndexes    []group.MemberIndex
	Members                  chain.OperatorIDs
	MembersHash              [32]byte
}

DKGChainResult represents a DKG result submitted to the chain.

type DKGChainResultHash 

type DKGChainResultHash [32]byte

DKGChainResultHash represents a hash of the DKGChainResult. The algorithm used is specific to the chain.

type DKGParameters 

type DKGParameters struct {
	SubmissionTimeoutBlocks       uint64
	ChallengePeriodBlocks         uint64
	ApprovePrecedencePeriodBlocks uint64
}

DKGParameters contains values of DKG-specific control parameters.

type DKGResultApprovedEvent 

type DKGResultApprovedEvent struct {
	ResultHash  DKGChainResultHash
	Approver    chain.Address
	BlockNumber uint64
}

DKGResultApprovedEvent represents a DKG result approval event. It is emitted after a submitted DKG result is approved as a valid result.

type DKGResultChallengedEvent 

type DKGResultChallengedEvent struct {
	ResultHash  DKGChainResultHash
	Challenger  chain.Address
	Reason      string
	BlockNumber uint64
}

DKGResultChallengedEvent represents a DKG result challenge event. It is emitted after a submitted DKG result is challenged as an invalid result.

type DKGResultSubmittedEvent 

type DKGResultSubmittedEvent struct {
	Seed        *big.Int
	ResultHash  DKGChainResultHash
	Result      *DKGChainResult
	BlockNumber uint64
}

DKGResultSubmittedEvent represents a DKG result submission event. It is emitted after a submitted DKG result lands on the chain.

type DKGStartedEvent 

type DKGStartedEvent struct {
	Seed        *big.Int
	BlockNumber uint64
}

DKGStartedEvent represents a DKG start event.

type DKGStartedEventFilter 

type DKGStartedEventFilter struct {
	StartBlock uint64
	EndBlock   *uint64
	Seed       []*big.Int
}

DKGStartedEventFilter is a component allowing to filter DKGStartedEvent.

type DKGState 

type DKGState int
const (
	Idle DKGState = iota
	AwaitingSeed
	AwaitingResult
	Challenge
)

type Deposit 

type Deposit struct {
	// Utxo is the unspent output of the deposit funding transaction that
	// represents the deposit on the Bitcoin chain.
	Utxo *bitcoin.UnspentTransactionOutput
	// Depositor is the depositor's address on the host chain.
	Depositor chain.Address
	// BlindingFactor is an 8-byte arbitrary value that allows to distinguish
	// deposits from the same depositor.
	BlindingFactor [8]byte
	// WalletPublicKeyHash is a 20-byte hash of the target wallet public key.
	WalletPublicKeyHash [20]byte
	// RefundPublicKeyHash is a 20-byte hash of the refund public key.
	RefundPublicKeyHash [20]byte
	// RefundLocktime is a 4-byte value representing the refund locktime.
	RefundLocktime [4]byte
	// Vault is an optional field that holds the host chain address of the
	// target vault.
	Vault *chain.Address
	// ExtraData is an optional field that holds 32 bytes of extra data
	// embedded in the deposit script.
	ExtraData *[32]byte
}

Deposit represents a tBTC deposit.

func ValidateDepositSweepProposal 

func ValidateDepositSweepProposal(
	validateProposalLogger log.StandardLogger,
	walletPublicKeyHash [20]byte,
	proposal *DepositSweepProposal,
	requiredFundingTxConfirmations uint,
	chain interface {
		// PastDepositRevealedEvents fetches past deposit reveal events according
		// to the provided filter or unfiltered if the filter is nil. Returned
		// events are sorted by the block number in the ascending order, i.e. the
		// latest event is at the end of the slice.
		PastDepositRevealedEvents(
			filter *DepositRevealedEventFilter,
		) ([]*DepositRevealedEvent, error)

		// ValidateDepositSweepProposal validates the given deposit sweep proposal
		// against the chain. It requires some additional data about the deposits
		// that must be fetched externally. Returns an error if the proposal is
		// not valid or nil otherwise.
		ValidateDepositSweepProposal(
			walletPublicKeyHash [20]byte,
			proposal *DepositSweepProposal,
			depositsExtraInfo []struct {
				*Deposit
				FundingTx *bitcoin.Transaction
			},
		) error

		// GetDepositRequest gets the on-chain deposit request for the given
		// funding transaction hash and output index.The returned values represent:
		// - deposit request which is non-nil only when the deposit request was
		//   found,
		// - boolean value which is true if the deposit request was found, false
		//   otherwise,
		// - error which is non-nil only when the function execution failed. It will
		//   be nil if the deposit request was not found, but the function execution
		//   succeeded.
		GetDepositRequest(
			fundingTxHash bitcoin.Hash,
			fundingOutputIndex uint32,
		) (*DepositChainRequest, bool, error)
	},
	btcChain bitcoin.Chain,
) ([]*Deposit, error)

ValidateDepositSweepProposal checks the deposit sweep proposal with on-chain validation rules and verifies transactions on the Bitcoin chain.

func (*Deposit) Script 

func (d *Deposit) Script() ([]byte, error)

Script constructs the deposit P2(W)SH Bitcoin script. This function assumes the deposit's fields are correctly set.

type DepositChainRequest 

type DepositChainRequest struct {
	Depositor   chain.Address
	Amount      uint64
	RevealedAt  time.Time
	Vault       *chain.Address
	TreasuryFee uint64
	SweptAt     time.Time
	ExtraData   *[32]byte
}

DepositChainRequest represents a deposit request stored on-chain. This is a deposit revealed to the Bridge and recorded on-chain. There is no guarantee this deposit actually happened on the Bitcoin side.

The Vault field is nil if the deposit does not target any vault on-chain.

type DepositRevealedEvent 

type DepositRevealedEvent struct {
	FundingTxHash       bitcoin.Hash
	FundingOutputIndex  uint32
	Depositor           chain.Address
	Amount              uint64
	BlindingFactor      [8]byte
	WalletPublicKeyHash [20]byte
	RefundPublicKeyHash [20]byte
	RefundLocktime      [4]byte
	Vault               *chain.Address
	BlockNumber         uint64
}

DepositRevealedEvent represents a deposit reveal event.

The Vault field is nil if the deposit does not target any vault on-chain.

func (*DepositRevealedEvent) GetWalletPublicKeyHash 

func (dre *DepositRevealedEvent) GetWalletPublicKeyHash() [20]byte

type DepositRevealedEventFilter 

type DepositRevealedEventFilter struct {
	StartBlock          uint64
	EndBlock            *uint64
	Depositor           []chain.Address
	WalletPublicKeyHash [][20]byte
}

DepositRevealedEventFilter is a component allowing to filter DepositRevealedEvent.

type DepositSweepProposal 

type DepositSweepProposal struct {
	DepositsKeys []struct {
		FundingTxHash      bitcoin.Hash
		FundingOutputIndex uint32
	}
	SweepTxFee           *big.Int
	DepositsRevealBlocks []*big.Int
}

DepositSweepProposal represents a deposit sweep proposal issued by a wallet's coordination leader.

func (*DepositSweepProposal) ActionType 

func (dsp *DepositSweepProposal) ActionType() WalletActionType

func (*DepositSweepProposal) Marshal 

func (dsp *DepositSweepProposal) Marshal() ([]byte, error)

Marshal converts the depositSweepProposal to a byte array.

func (*DepositSweepProposal) Unmarshal 

func (dsp *DepositSweepProposal) Unmarshal(bytes []byte) error

Unmarshal converts a byte array back to the depositSweepProposal.

func (*DepositSweepProposal) ValidityBlocks 

func (dsp *DepositSweepProposal) ValidityBlocks() uint64

type DistributedKeyGenerationChain 

type DistributedKeyGenerationChain interface {
	// OnDKGStarted registers a callback that is invoked when an on-chain
	// notification of the DKG process start is seen.
	OnDKGStarted(
		func(event *DKGStartedEvent),
	) subscription.EventSubscription

	// PastDKGStartedEvents fetches past DKG started events according to the
	// provided filter or unfiltered if the filter is nil. Returned events
	// are sorted by the block number in the ascending order, i.e. the latest
	// event is at the end of the slice.
	PastDKGStartedEvents(
		filter *DKGStartedEventFilter,
	) ([]*DKGStartedEvent, error)

	// OnDKGResultSubmitted registers a callback that is invoked when an on-chain
	// notification of the DKG result submission is seen.
	OnDKGResultSubmitted(
		func(event *DKGResultSubmittedEvent),
	) subscription.EventSubscription

	// OnDKGResultChallenged registers a callback that is invoked when an
	// on-chain notification of the DKG result challenge is seen.
	OnDKGResultChallenged(
		func(event *DKGResultChallengedEvent),
	) subscription.EventSubscription

	// OnDKGResultApproved registers a callback that is invoked when an on-chain
	// notification of the DKG result approval is seen.
	OnDKGResultApproved(
		func(event *DKGResultApprovedEvent),
	) subscription.EventSubscription

	// AssembleDKGResult assembles the DKG chain result according to the rules
	// expected by the given chain.
	AssembleDKGResult(
		submitterMemberIndex group.MemberIndex,
		groupPublicKey *ecdsa.PublicKey,
		operatingMembersIndexes []group.MemberIndex,
		misbehavedMembersIndexes []group.MemberIndex,
		signatures map[group.MemberIndex][]byte,
		groupSelectionResult *GroupSelectionResult,
	) (*DKGChainResult, error)

	// SubmitDKGResult submits the DKG result to the chain.
	SubmitDKGResult(dkgResult *DKGChainResult) error

	// GetDKGState returns the current state of the DKG procedure.
	GetDKGState() (DKGState, error)

	// CalculateDKGResultSignatureHash calculates a 32-byte hash that is used
	// to produce a signature supporting the given groupPublicKey computed
	// as result of the given DKG process. The misbehavedMembersIndexes parameter
	// should contain indexes of members that were considered as misbehaved
	// during the DKG process. The startBlock argument is the block at which
	// the given DKG process started.
	CalculateDKGResultSignatureHash(
		groupPublicKey *ecdsa.PublicKey,
		misbehavedMembersIndexes []group.MemberIndex,
		startBlock uint64,
	) (dkg.ResultSignatureHash, error)

	// IsDKGResultValid checks whether the submitted DKG result is valid from
	// the on-chain contract standpoint.
	IsDKGResultValid(dkgResult *DKGChainResult) (bool, error)

	// ChallengeDKGResult challenges the submitted DKG result.
	ChallengeDKGResult(dkgResult *DKGChainResult) error

	// ApproveDKGResult approves the submitted DKG result.
	ApproveDKGResult(dkgResult *DKGChainResult) error

	// DKGParameters gets the current value of DKG-specific control parameters.
	DKGParameters() (*DKGParameters, error)
}

DistributedKeyGenerationChain defines the subset of the TBTC chain interface that pertains specifically to group formation's distributed key generation process.

type GroupParameters 

type GroupParameters struct {
	// GroupSize is the target size of a group in TBTC.
	GroupSize int
	// GroupQuorum is the minimum number of active participants behaving
	// according to the protocol needed to generate a group in TBTC. This value
	// is smaller than the GroupSize and bigger than the HonestThreshold.
	GroupQuorum int
	// HonestThreshold is the minimum number of active participants behaving
	// according to the protocol needed to generate a signature.
	HonestThreshold int
}

GroupParameters is a structure grouping TBTC group parameters.

func (*GroupParameters) DishonestThreshold 

func (gp *GroupParameters) DishonestThreshold() int

DishonestThreshold is the maximum number of misbehaving participants for which it is still possible to generate a signature. Misbehaviour is any misconduct to the protocol, including inactivity.

type GroupSelectionChain 

type GroupSelectionChain interface {
	// SelectGroup returns the group members selected for the current group
	// selection. The function returns an error if the chain's state does not
	// allow for group selection at the moment.
	SelectGroup() (*GroupSelectionResult, error)
}

GroupSelectionChain defines the subset of the TBTC chain interface that pertains to the group selection activities.

type GroupSelectionResult 

type GroupSelectionResult struct {
	OperatorsIDs       chain.OperatorIDs
	OperatorsAddresses chain.Addresses
}

GroupSelectionResult represents a group selection result, i.e. operators selected to perform the DKG protocol. The result consists of two slices of equal length holding the chain.OperatorID and chain.Address for each selected operator.

type HeartbeatProposal 

type HeartbeatProposal struct {
	Message [16]byte
}

func (*HeartbeatProposal) ActionType 

func (hp *HeartbeatProposal) ActionType() WalletActionType

func (*HeartbeatProposal) Marshal 

func (hp *HeartbeatProposal) Marshal() ([]byte, error)

Marshal converts the heartbeatProposal to a byte array.

func (*HeartbeatProposal) Unmarshal 

func (hp *HeartbeatProposal) Unmarshal(bytes []byte) error

Unmarshal converts a byte array back to the heartbeatProposal.

func (*HeartbeatProposal) ValidityBlocks 

func (hp *HeartbeatProposal) ValidityBlocks() uint64

type HeartbeatRequestedEvent 

type HeartbeatRequestedEvent struct {
	WalletPublicKey []byte
	Messages        []*big.Int
	BlockNumber     uint64
}

HeartbeatRequestedEvent represents a Bridge heartbeat request event.

type InactivityClaim 

type InactivityClaim struct {
	WalletID               [32]byte
	InactiveMembersIndices []group.MemberIndex
	HeartbeatFailed        bool
	Signatures             []byte
	SigningMembersIndices  []group.MemberIndex
}

InactivityClaim represents an inactivity claim submitted to the chain.

type InactivityClaimChain 

type InactivityClaimChain interface {
	// OnInactivityClaimed registers a callback that is invoked when an on-chain
	// notification of the inactivity claim submission is seen.
	OnInactivityClaimed(
		func(event *InactivityClaimedEvent),
	) subscription.EventSubscription

	// AssembleInactivityClaim assembles the inactivity chain claim according to
	// the rules expected by the given chain.
	AssembleInactivityClaim(
		walletID [32]byte,
		inactiveMembersIndices []group.MemberIndex,
		signatures map[group.MemberIndex][]byte,
		heartbeatFailed bool,
	) (*InactivityClaim, error)

	// SubmitInactivityClaim submits the inactivity claim to the chain.
	SubmitInactivityClaim(
		claim *InactivityClaim,
		nonce *big.Int,
		groupMembers []uint32,
	) error

	// CalculateInactivityClaimHash calculates hash for the given inactivity
	// claim.
	CalculateInactivityClaimHash(claim *inactivity.ClaimPreimage) (
		inactivity.ClaimHash,
		error,
	)

	// GetInactivityClaimNonce returns inactivity claim nonce for the given
	// wallet.
	GetInactivityClaimNonce(walletID [32]byte) (*big.Int, error)
}

type InactivityClaimedEvent 

type InactivityClaimedEvent struct {
	WalletID    [32]byte
	Nonce       *big.Int
	Notifier    chain.Address
	BlockNumber uint64
}

InactivityClaimedEvent represents an inactivity claimed event. It is emitted after a submitted inactivity claim lands on the chain.

type MovedFundsSweepProposal 

type MovedFundsSweepProposal struct {
	MovingFundsTxHash        [32]byte
	MovingFundsTxOutputIndex uint32
	SweepTxFee               *big.Int
}

MovedFundsSweepProposal represents a moved funds sweep proposal issued by a wallet's coordination leader.

func (*MovedFundsSweepProposal) ActionType 

func (mfsp *MovedFundsSweepProposal) ActionType() WalletActionType

func (*MovedFundsSweepProposal) Marshal 

func (mfsp *MovedFundsSweepProposal) Marshal() ([]byte, error)

Marshal converts the movingFundsProposal to a byte array.

func (*MovedFundsSweepProposal) Unmarshal 

func (mfsp *MovedFundsSweepProposal) Unmarshal(data []byte) error

Unmarshal converts a byte array back to the movingFundsProposal.

func (*MovedFundsSweepProposal) ValidityBlocks 

func (mfsp *MovedFundsSweepProposal) ValidityBlocks() uint64

type MovedFundsSweepRequest 

type MovedFundsSweepRequest struct {
	WalletPublicKeyHash [20]byte
	Value               uint64
	CreatedAt           time.Time
	State               MovedFundsSweepRequestState
}

MovedFundsSweepRequest represents a moved funds sweep request.

type MovedFundsSweepRequestState 

type MovedFundsSweepRequestState uint8

MovedFundsSweepRequestState represents the state of a moved funds request. 

const (
	MovedFundsStateUnknown MovedFundsSweepRequestState = iota
	MovedFundsStatePending
	MovedFundsStateProcessed
	MovedFundsStateTimedOut
)

type MovingFundsCommitmentSubmittedEvent 

type MovingFundsCommitmentSubmittedEvent struct {
	WalletPublicKeyHash [20]byte
	TargetWallets       [][20]byte
	Submitter           chain.Address
	BlockNumber         uint64
}

MovingFundsCommitmentSubmittedEvent represents a moving funds commitment submitted event.

func (*MovingFundsCommitmentSubmittedEvent) GetTargetWallets 

func (mfcse *MovingFundsCommitmentSubmittedEvent) GetTargetWallets() [][20]byte

func (*MovingFundsCommitmentSubmittedEvent) GetWalletPublicKeyHash 

func (mfcse *MovingFundsCommitmentSubmittedEvent) GetWalletPublicKeyHash() [20]byte

type MovingFundsCommitmentSubmittedEventFilter 

type MovingFundsCommitmentSubmittedEventFilter struct {
	StartBlock          uint64
	EndBlock            *uint64
	WalletPublicKeyHash [][20]byte
}

MovingFundsCommitmentSubmittedEventFilter is a component allowing to filter MovingFundsCommitmentSubmittedEvent.

type MovingFundsCompletedEvent 

type MovingFundsCompletedEvent struct {
	WalletPublicKeyHash [20]byte
	MovingFundsTxHash   bitcoin.Hash
	BlockNumber         uint64
}

MovingFundsCompletedEvent represents a moving funds completed event.

type MovingFundsCompletedEventFilter 

type MovingFundsCompletedEventFilter struct {
	StartBlock          uint64
	EndBlock            *uint64
	WalletPublicKeyHash [][20]byte
}

MovingFundsCompletedEventFilter is a component allowing to filter MovingFundsCompletedEvent.

type MovingFundsProposal 

type MovingFundsProposal struct {
	TargetWallets    [][20]byte
	MovingFundsTxFee *big.Int
}

MovingFundsProposal represents a moving funds proposal issued by a wallet's coordination leader.

func (*MovingFundsProposal) ActionType 

func (mfp *MovingFundsProposal) ActionType() WalletActionType

func (*MovingFundsProposal) Marshal 

func (mfp *MovingFundsProposal) Marshal() ([]byte, error)

Marshal converts the movingFundsProposal to a byte array.

func (*MovingFundsProposal) Unmarshal 

func (mfp *MovingFundsProposal) Unmarshal(data []byte) error

Unmarshal converts a byte array back to the movingFundsProposal.

func (*MovingFundsProposal) ValidityBlocks 

func (mfp *MovingFundsProposal) ValidityBlocks() uint64

type NewWalletRegisteredEvent 

type NewWalletRegisteredEvent struct {
	EcdsaWalletID       [32]byte
	WalletPublicKeyHash [20]byte
	BlockNumber         uint64
}

NewWalletRegisteredEvent represents a new wallet registered event.

type NewWalletRegisteredEventFilter 

type NewWalletRegisteredEventFilter struct {
	StartBlock          uint64
	EndBlock            *uint64
	EcdsaWalletID       [][32]byte
	WalletPublicKeyHash [][20]byte
}

NewWalletRegisteredEventFilter is a component allowing to filter NewWalletRegisteredEvent.

type NoopProposal 

type NoopProposal struct{}

NoopProposal is a proposal that does not propose any action.

func (*NoopProposal) ActionType 

func (np *NoopProposal) ActionType() WalletActionType

func (*NoopProposal) Marshal 

func (np *NoopProposal) Marshal() ([]byte, error)

Marshal converts the noopProposal to a byte array.

func (*NoopProposal) Unmarshal 

func (np *NoopProposal) Unmarshal([]byte) error

Unmarshal converts a byte array back to the noopProposal.

func (*NoopProposal) ValidityBlocks 

func (np *NoopProposal) ValidityBlocks() uint64

type RedemptionProposal 

type RedemptionProposal struct {
	RedeemersOutputScripts []bitcoin.Script
	RedemptionTxFee        *big.Int
}

RedemptionProposal represents a redemption proposal issued by a wallet's coordination leader.

func (*RedemptionProposal) ActionType 

func (rp *RedemptionProposal) ActionType() WalletActionType

func (*RedemptionProposal) Marshal 

func (rp *RedemptionProposal) Marshal() ([]byte, error)

Marshal converts the redemptionProposal to a byte array.

func (*RedemptionProposal) Unmarshal 

func (rp *RedemptionProposal) Unmarshal(bytes []byte) error

Unmarshal converts a byte array back to the redemptionProposal.

func (*RedemptionProposal) ValidityBlocks 

func (rp *RedemptionProposal) ValidityBlocks() uint64

type RedemptionRequest 

type RedemptionRequest struct {
	// Redeemer is the redeemer's address on the host chain.
	Redeemer chain.Address
	// RedeemerOutputScript is the output script the redeemed Bitcoin funds are
	// locked to. As stated in the bitcoin.Script docstring, this field is not
	// prepended with the byte-length of the script.
	RedeemerOutputScript bitcoin.Script
	// RequestedAmount is the TBTC amount (in satoshi) requested for redemption.
	RequestedAmount uint64
	// TreasuryFee is the treasury TBTC fee (in satoshi) at the moment of
	// request creation.
	TreasuryFee uint64
	// TxMaxFee is the maximum value of the per-redemption BTC tx fee (in satoshi)
	// that can be incurred by this request, determined at the moment of
	// request creation.
	TxMaxFee uint64
	// RequestedAt is the time the request was created at.
	RequestedAt time.Time
}

RedemptionRequest represents a tBTC redemption request.

func ValidateRedemptionProposal 

func ValidateRedemptionProposal(
	validateProposalLogger log.StandardLogger,
	walletPublicKeyHash [20]byte,
	proposal *RedemptionProposal,
	chain interface {
		// GetPendingRedemptionRequest gets the on-chain pending redemption request
		// for the given wallet public key hash and redeemer output script.
		// The returned bool value indicates whether the request was found or not.
		GetPendingRedemptionRequest(
			walletPublicKeyHash [20]byte,
			redeemerOutputScript bitcoin.Script,
		) (*RedemptionRequest, bool, error)

		// ValidateRedemptionProposal validates the given redemption proposal
		// against the chain. Returns an error if the proposal is not valid or
		// nil otherwise.
		ValidateRedemptionProposal(
			walletPublicKeyHash [20]byte,
			proposal *RedemptionProposal,
		) error
	},
) ([]*RedemptionRequest, error)

ValidateRedemptionProposal checks the redemption proposal with on-chain validation rules.

type RedemptionRequestedEvent 

type RedemptionRequestedEvent struct {
	WalletPublicKeyHash  [20]byte
	RedeemerOutputScript bitcoin.Script
	Redeemer             chain.Address
	RequestedAmount      uint64
	TreasuryFee          uint64
	TxMaxFee             uint64
	BlockNumber          uint64
}

RedemptionRequestedEvent represents a redemption requested event.

func (*RedemptionRequestedEvent) GetWalletPublicKeyHash 

func (rre *RedemptionRequestedEvent) GetWalletPublicKeyHash() [20]byte

type RedemptionRequestedEventFilter 

type RedemptionRequestedEventFilter struct {
	StartBlock          uint64
	EndBlock            *uint64
	WalletPublicKeyHash [][20]byte
	Redeemer            []chain.Address
}

RedemptionRequestedEventFilter is a component allowing to filter RedemptionRequestedEvent.

type RedemptionTransactionShape 

type RedemptionTransactionShape uint8

RedemptionTransactionShape is an enum describing the shape of a Bitcoin redemption transaction. 

const (
	// RedemptionChangeFirst is a shape where the change output is the first one
	// in the transaction output vector. This shape makes the change's position
	// fixed and leverages some SPV proof cost optimizations made in the Bridge
	// implementation.
	RedemptionChangeFirst RedemptionTransactionShape = iota
	// RedemptionChangeLast is a shape where the change output is the last one
	// in the transaction output vector.
	RedemptionChangeLast
)

type WalletActionType 

type WalletActionType uint8

WalletActionType represents actions types that can be performed by a wallet. 

const (
	ActionNoop WalletActionType = iota
	ActionHeartbeat
	ActionDepositSweep
	ActionRedemption
	ActionMovingFunds
	ActionMovedFundsSweep
)

func ParseWalletActionType 

func ParseWalletActionType(value uint8) (WalletActionType, error)

ParseWalletActionType parses the given value into a WalletActionType.

func (WalletActionType) String 

func (wat WalletActionType) String() string

type WalletChainData 

type WalletChainData struct {
	EcdsaWalletID                          [32]byte
	MainUtxoHash                           [32]byte
	PendingRedemptionsValue                uint64
	CreatedAt                              time.Time
	MovingFundsRequestedAt                 time.Time
	ClosingStartedAt                       time.Time
	PendingMovedFundsSweepRequestsCount    uint32
	State                                  WalletState
	MovingFundsTargetWalletsCommitmentHash [32]byte
}

WalletChainData represents wallet data stored on-chain.

type WalletClosedEvent 

type WalletClosedEvent struct {
	WalletID    [32]byte
	BlockNumber uint64
}

WalletClosedEvent represents a wallet closed event. It is emitted when the wallet is closed in the wallet registry.

type WalletProposalValidatorChain 

type WalletProposalValidatorChain interface {
	// ValidateDepositSweepProposal validates the given deposit sweep proposal
	// against the chain. It requires some additional data about the deposits
	// that must be fetched externally. Returns an error if the proposal is
	// not valid or nil otherwise.
	ValidateDepositSweepProposal(
		walletPublicKeyHash [20]byte,
		proposal *DepositSweepProposal,
		depositsExtraInfo []struct {
			*Deposit
			FundingTx *bitcoin.Transaction
		},
	) error

	// ValidateRedemptionProposal validates the given redemption proposal
	// against the chain. Returns an error if the proposal is not valid or
	// nil otherwise.
	ValidateRedemptionProposal(
		walletPublicKeyHash [20]byte,
		proposal *RedemptionProposal,
	) error

	// ValidateHeartbeatProposal validates the given heartbeat proposal
	// against the chain. Returns an error if the proposal is not valid or
	// nil otherwise.
	ValidateHeartbeatProposal(
		walletPublicKeyHash [20]byte,
		proposal *HeartbeatProposal,
	) error

	// ValidateMovingFundsProposal validates the given moving funds proposal
	// against the chain. Returns an error if the proposal is not valid or
	// nil otherwise.
	ValidateMovingFundsProposal(
		walletPublicKeyHash [20]byte,
		mainUTXO *bitcoin.UnspentTransactionOutput,
		proposal *MovingFundsProposal,
	) error

	// ValidateMovedFundsSweepProposal validates the given moved funds sweep
	// proposal against the chain. Returns an error if the proposal is not valid
	// or nil otherwise.
	ValidateMovedFundsSweepProposal(
		walletPublicKeyHash [20]byte,
		proposal *MovedFundsSweepProposal,
	) error
}

WalletProposalValidatorChain defines the subset of the TBTC chain interface that pertains specifically to the tBTC wallet proposal validator.

type WalletState 

type WalletState uint8

WalletState represents the state of a wallet. 

const (
	StateUnknown WalletState = iota
	StateLive
	StateMovingFunds
	StateClosing
	StateClosed
	StateTerminated
)

func (WalletState) String 

func (ws WalletState) String() string

Source Files

View all Source files

Directories

Path Synopsis
gen
pb
internal
test
Package tbtctest contains scenarios meant to be used for Bitcoin-related tests in the pkg/tbtc package.
 Package tbtctest contains scenarios meant to be used for Bitcoin-related tests in the pkg/tbtc package.

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.