pm

package
v0.5.3 Latest Latest
Warning

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

 Go to latest Published: Jan 13, 2020 License: MIT Imports: 19 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func RandAddress 

func RandAddress() ethcommon.Address

RandAddress returns a random ETH address

func RandBytes 

func RandBytes(size uint) []byte

RandBytes returns a slice of random bytes with the size specified by the caller

func RandHash 

func RandHash() ethcommon.Hash

RandHash returns a random keccak256 hash

func VerifySig 

func VerifySig(addr ethcommon.Address, msg, sig []byte) bool

VerifySig verifies that a ETH ECDSA signature over a given message is produced by a given ETH address

TODO refactor to a package that both eth and pm can import

Types

type Broker 

type Broker interface {
	// FundDepositAndReserve funds a sender's deposit and reserve
	FundDepositAndReserve(depositAmount, reserveAmount *big.Int) (*types.Transaction, error)

	// FundDeposit funds a sender's deposit
	FundDeposit(amount *big.Int) (*types.Transaction, error)

	// FundReserve funds a sender's reserve
	FundReserve(amount *big.Int) (*types.Transaction, error)

	// Unlock initiates the unlock period for a sender after which a sender can withdraw its
	// deposit and penalty escrow
	Unlock() (*types.Transaction, error)

	// CancelUnlock stops a sender's active unlock period
	CancelUnlock() (*types.Transaction, error)

	// Withdraw credits a sender with its deposit and penalty escrow after the sender
	// waits through the unlock period
	Withdraw() (*types.Transaction, error)

	// RedeemWinningTicket submits a ticket to be validated by the broker and if a valid winning ticket
	// the broker pays the ticket's face value to the ticket's recipient
	RedeemWinningTicket(ticket *Ticket, sig []byte, recipientRand *big.Int) (*types.Transaction, error)

	// IsUsedTicket checks if a ticket has been used
	IsUsedTicket(ticket *Ticket) (bool, error)

	// CheckTx waits for a transaction to confirm on-chain and returns an error
	// if the transaction failed
	CheckTx(tx *types.Transaction) error
}

Broker is an interface which serves as an abstraction over an on-chain smart contract that handles the administrative tasks in a probabilistic micropayment protocol including processing deposits and pay outs

type DefaultSigVerifier 

type DefaultSigVerifier struct {
}

DefaultSigVerifier is client-side-only implementation of sig verification, i.e. not relying on any smart contract inputs.

func (*DefaultSigVerifier) Verify 

func (sv *DefaultSigVerifier) Verify(addr ethcommon.Address, msg, sig []byte) bool

Verify checks if a provided signature over a message is valid for a given ETH address

type ErrorMonitor 

type ErrorMonitor interface {
	AcceptErr(sender ethcommon.Address) bool
	ClearErrCount(sender ethcommon.Address)
}

ErrorMonitor is an interface that describes methods used to monitor acceptable pm ticket errors as well as acceptable price errors

type GasPriceMonitor 

type GasPriceMonitor interface {
	GasPrice() *big.Int
}

GasPriceMonitor defines methods for monitoring gas prices

type MockReceiveError 

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

MockReceiveError is for testing acceptable/unacceptable PM ticket errors

func NewMockReceiveError 

func NewMockReceiveError(err error, acceptable bool) *MockReceiveError

NewMockReceiveError creates a new acceptable/unacceptable MocKReceiveError

func (*MockReceiveError) Acceptable 

func (re *MockReceiveError) Acceptable() bool

Acceptable returns whether the error is acceptable

func (*MockReceiveError) Error 

func (re *MockReceiveError) Error() string

Error returns the underlying error as a string

type MockRecipient 

type MockRecipient struct {
	mock.Mock
}

MockRecipient is useful for testing components that depend on pm.Recipient

func (*MockRecipient) EV 

func (m *MockRecipient) EV() *big.Rat

EV Returns the recipient's request ticket EV

func (*MockRecipient) ReceiveTicket 

func (m *MockRecipient) ReceiveTicket(ticket *Ticket, sig []byte, seed *big.Int) (sessionID string, won bool, err error)

ReceiveTicket validates and processes a received ticket

func (*MockRecipient) RedeemWinningTicket 

func (m *MockRecipient) RedeemWinningTicket(ticket *Ticket, sig []byte, seed *big.Int) error

RedeemWinningTicket redeems a single winning ticket

func (*MockRecipient) RedeemWinningTickets 

func (m *MockRecipient) RedeemWinningTickets(sessionIDs []string) error

RedeemWinningTickets redeems all winning tickets with the broker for a all sessionIDs

func (*MockRecipient) Start 

func (m *MockRecipient) Start()

Start initiates the helper goroutines for the recipient

func (*MockRecipient) Stop 

func (m *MockRecipient) Stop()

Stop signals the recipient to exit gracefully

func (*MockRecipient) TicketParams 

func (m *MockRecipient) TicketParams(sender ethcommon.Address) (*TicketParams, error)

TicketParams returns the recipient's currently accepted ticket parameters for a provided sender ETH adddress

func (*MockRecipient) TxCostMultiplier 

func (m *MockRecipient) TxCostMultiplier(sender ethcommon.Address) (*big.Rat, error)

TxCostMultiplier returns the transaction cost multiplier for a sender based on sender's MaxFloat

type MockSender 

type MockSender struct {
	mock.Mock
}

MockSender is useful for testing components that depend on pm.Sender

func (*MockSender) CreateTicketBatch 

func (m *MockSender) CreateTicketBatch(sessionID string, size int) (*TicketBatch, error)

CreateTicketBatch returns a ticket batch of the specified size

func (*MockSender) EV 

func (m *MockSender) EV(sessionID string) (*big.Rat, error)

EV returns the ticket EV for a session

func (*MockSender) StartSession 

func (m *MockSender) StartSession(ticketParams TicketParams) string

StartSession creates a session for a given set of ticket params which tracks information for creating new tickets

func (*MockSender) ValidateTicketParams 

func (m *MockSender) ValidateTicketParams(ticketParams *TicketParams) error

ValidateTicketParams checks if ticket params are acceptable

type Recipient 

type Recipient interface {
	// Start initiates the helper goroutines for the recipient
	Start()

	// Stop signals the recipient to exit gracefully
	Stop()

	// ReceiveTicket validates and processes a received ticket
	ReceiveTicket(ticket *Ticket, sig []byte, seed *big.Int) (sessionID string, won bool, err error)

	// RedeemWinningTickets redeems all winning tickets with the broker
	// for a all sessionIDs
	RedeemWinningTickets(sessionIDs []string) error

	// RedeemWinningTicket redeems a single winning ticket
	RedeemWinningTicket(ticket *Ticket, sig []byte, seed *big.Int) error

	// TicketParams returns the recipient's currently accepted ticket parameters
	// for a provided sender ETH adddress
	TicketParams(sender ethcommon.Address) (*TicketParams, error)

	// TxCostMultiplier returns the multiplier -
	TxCostMultiplier(sender ethcommon.Address) (*big.Rat, error)

	// EV returns the recipients EV requirement for a ticket as configured on startup
	EV() *big.Rat
}

Recipient is an interface which describes an object capable of receiving tickets

func NewRecipient 

func NewRecipient(addr ethcommon.Address, broker Broker, val Validator, store TicketStore, gpm GasPriceMonitor, sm SenderMonitor, em ErrorMonitor, cfg TicketParamsConfig) (Recipient, error)

NewRecipient creates an instance of a recipient with an automatically generated random secret

func NewRecipientWithSecret 

func NewRecipientWithSecret(addr ethcommon.Address, broker Broker, val Validator, store TicketStore, gpm GasPriceMonitor, sm SenderMonitor, em ErrorMonitor, secret [32]byte, cfg TicketParamsConfig) Recipient

NewRecipientWithSecret creates an instance of a recipient with a user provided secret. In most cases, NewRecipient should be used instead which will automatically generate a random secret

type RedeemableEmitter 

type RedeemableEmitter interface {
	// Redeemable returns a channel that a consumer can use to receive tickets that
	// should be redeemed
	Redeemable() chan *SignedTicket
}

RedeemableEmitter is an interface that describes methods for emitting redeemable tickets

type ReserveInfo 

type ReserveInfo struct {
	// FundsRemaining is the amount of funds the sender has left in its reserve
	FundsRemaining *big.Int

	// ClaimedInCurrentRound is the total amount of funds claimed from the sender's reserve in the current round
	ClaimedInCurrentRound *big.Int
}

ReserveInfo holds information about a sender's reserve

type RoundsManager 

type RoundsManager interface {
	// LastInitializedRound returns the last initialized round of the Livepeer protocol
	LastInitializedRound() *big.Int
	// LastInitializedBlockHash returns the blockhash of the block the last round was initiated in
	LastInitializedBlockHash() [32]byte
	// GetTranscoderPoolSize returns the size of the active transcoder set for a round
	GetTranscoderPoolSize() *big.Int
}

RoundsManager defines the methods for fetching the last initialized round and associated block hash of the Livepeer protocol

type Sender 

type Sender interface {
	// StartSession creates a session for a given set of ticket params which tracks information
	// for creating new tickets
	StartSession(ticketParams TicketParams) string

	// CreateTicketBatch returns a ticket batch of the specified size
	CreateTicketBatch(sessionID string, size int) (*TicketBatch, error)

	// ValidateTicketParams checks if ticket params are acceptable
	ValidateTicketParams(ticketParams *TicketParams) error

	// EV returns the ticket EV for a session
	EV(sessionID string) (*big.Rat, error)
}

Sender enables starting multiple probabilistic micropayment sessions with multiple recipients and create tickets that adhere to each session's params and unique nonce requirements.

func NewSender 

func NewSender(signer Signer, roundsManager RoundsManager, senderManager SenderManager, maxEV *big.Rat, depositMultiplier int) Sender

NewSender creates a new Sender instance.

type SenderInfo 

type SenderInfo struct {
	// Deposit is the amount of funds the sender has in its deposit
	Deposit *big.Int

	// WithdrawRound is the round that the sender can withdraw its deposit and reserve
	WithdrawRound *big.Int

	// ReserveInfo is a struct containing details about a sender's reserve
	Reserve *ReserveInfo
}

SenderInfo contains information about a sender tracked by a Broker

type SenderManager 

type SenderManager interface {
	// GetSenderInfo returns a sender's information
	GetSenderInfo(addr ethcommon.Address) (*SenderInfo, error)
	// ClaimedReserve returns the amount claimed from a sender's reserve
	ClaimedReserve(reserveHolder ethcommon.Address, claimant ethcommon.Address) (*big.Int, error)
	// Clear clears the cached values for a sender
	Clear(addr ethcommon.Address)
}

SenderManager defines the methods for fetching sender information

type SenderMonitor 

type SenderMonitor interface {
	RedeemableEmitter

	// Start initiates the helper goroutines for the monitor
	Start()

	// Stop signals the monitor to exit gracefully
	Stop()

	// QueueTicket adds a ticket to the queue for a remote sender
	QueueTicket(addr ethcommon.Address, ticket *SignedTicket)

	// AddFloat adds to a remote sender's max float
	AddFloat(addr ethcommon.Address, amount *big.Int) error

	// SubFloat subtracts from a remote sender's max float
	SubFloat(addr ethcommon.Address, amount *big.Int)

	// MaxFloat returns a remote sender's max float
	MaxFloat(addr ethcommon.Address) (*big.Int, error)

	// ValidateSender checks whether a sender's unlock period ends the round after the next round
	ValidateSender(addr ethcommon.Address) error
}

SenderMonitor is an interface that describes methods used to monitor remote senders

func NewSenderMonitor 

func NewSenderMonitor(claimant ethcommon.Address, broker Broker, smgr SenderManager, rm RoundsManager, cleanupInterval time.Duration, ttl int, em ErrorMonitor) SenderMonitor

NewSenderMonitor returns a new SenderMonitor

type SigVerifier 

type SigVerifier interface {
	// Verify checks if a provided signature over a message
	// is valid for a given ETH address
	Verify(addr ethcommon.Address, msg, sig []byte) bool
}

SigVerifier is an interface which describes an object capable of verification of ECDSA signatures produced by ETH addresses

type SignedTicket 

type SignedTicket struct {
	// Ticket contains ticket fields that are directly
	// accessible on SignedTicket since it is embedded
	*Ticket

	// Sig is the sender's signature over the ticket
	Sig []byte

	// RecipientRand is the recipient's random value that should be
	// the preimage for the ticket's recipientRandHash
	RecipientRand *big.Int
}

SignedTicket is a wrapper around a Ticket with the sender's signature over the ticket and the recipient recipientRand

type Signer 

type Signer interface {
	Sign(msg []byte) ([]byte, error)
	Account() accounts.Account
}

Signer supports identifying as an Ethereum account owner, by providing the Account and enabling message signing.

type Ticket 

type Ticket struct {
	// Recipient is the ETH address of recipient
	Recipient ethcommon.Address

	// Sender is the ETH address of sender
	Sender ethcommon.Address

	// FaceValue represents the pay out to
	// the recipient if the ticket wins
	FaceValue *big.Int

	// WinProb represents how likely a ticket will win
	WinProb *big.Int

	// SenderNonce is the monotonically increasing counter that makes
	// each ticket unique given a particular recipientRand value
	SenderNonce uint32

	// RecipientRandHash is the 32 byte keccak-256 hash commitment to a random number
	// provided by the recipient. In order for the recipient to redeem
	// a winning ticket, it must reveal the preimage to this hash
	RecipientRandHash ethcommon.Hash

	// CreationRound is the round during which the ticket is created
	CreationRound int64

	// CreationRoundBlockHash is the block hash associated with CreationRound
	CreationRoundBlockHash ethcommon.Hash
}

Ticket is lottery ticket payment in a probabilistic micropayment protocol The expected value of the ticket constitutes the payment and can be calculated using the ticket's face value and winning probability

func NewTicket 

func NewTicket(params *TicketParams, expirationParams *TicketExpirationParams, sender ethcommon.Address, senderNonce uint32) *Ticket

NewTicket creates a Ticket instance

func (*Ticket) AuxData 

func (t *Ticket) AuxData() []byte

AuxData returns the ticket's CreationRound and CreationRoundBlockHash encoded into a byte array: [0:31] = CreationRound (left padded with zero bytes) [32..63] = CreationRoundBlockHash See: https://github.com/livepeer/protocol/blob/pm/contracts/pm/mixins/MixinTicketProcessor.sol#L94

func (*Ticket) EV 

func (t *Ticket) EV() *big.Rat

EV returns the expected value of a ticket

func (*Ticket) Hash 

func (t *Ticket) Hash() ethcommon.Hash

Hash returns the keccak-256 hash of the ticket's fields as tightly packed arguments as described in the Solidity documentation See: https://solidity.readthedocs.io/en/v0.4.25/units-and-global-variables.html#mathematical-and-cryptographic-functions

func (*Ticket) WinProbRat 

func (t *Ticket) WinProbRat() *big.Rat

WinProbRat returns the ticket WinProb as a percentage represented as a big.Rat

type TicketBatch 

type TicketBatch struct {
	*TicketParams
	*TicketExpirationParams

	Sender ethcommon.Address

	SenderParams []*TicketSenderParams
}

TicketBatch is a group of tickets that share the same TicketParams, TicketExpirationParams and Sender Each ticket in a batch is identified by a unique TicketSenderParams

func (*TicketBatch) Tickets 

func (b *TicketBatch) Tickets() []*Ticket

Tickets returns the tickets in the batch

type TicketExpirationParams 

type TicketExpirationParams struct {
	CreationRound int64

	CreationRoundBlockHash ethcommon.Hash
}

TicketExpirationParams indicates when/how a ticket expires

type TicketParams 

type TicketParams struct {
	Recipient ethcommon.Address

	FaceValue *big.Int

	WinProb *big.Int

	RecipientRandHash ethcommon.Hash

	Seed *big.Int
}

TicketParams represents the parameters defined by a receiver that a sender must adhere to when sending tickets to receiver.

type TicketParamsConfig 

type TicketParamsConfig struct {
	// EV is the desired expected value of tickets
	EV *big.Int

	// RedeemGas is the expected gas required to redeem a ticket
	RedeemGas int

	// TxCostMultiplier is the desired multiplier of the transaction
	// cost for redemption
	TxCostMultiplier int
}

TicketParamsConfig contains config information for a recipient to determine the parameters to use for tickets

type TicketSenderParams 

type TicketSenderParams struct {
	SenderNonce uint32

	Sig []byte
}

TicketSenderParams identifies a unique ticket based on a sender's nonce and signature over a ticket hash

type TicketStore 

type TicketStore interface {
	// Store persists a ticket with its signature and recipientRand
	// for a session ID
	StoreWinningTicket(sessionID string, ticket *Ticket, sig []byte, recipientRand *big.Int) error

	// Load fetches all persisted tickets in the store with their signatures and recipientRands
	// for a session ID
	LoadWinningTickets(sessionIDs []string) (tickets []*Ticket, sigs [][]byte, recipientRands []*big.Int, err error)
}

TicketStore is an interface which describes an object capable of persisting tickets

type Validator 

type Validator interface {
	// ValidateTicket checks if a ticket is valid
	ValidateTicket(recipient ethcommon.Address, ticket *Ticket, sig []byte, recipientRand *big.Int) error

	// IsWinningTicket checks if a ticket won
	// Note: This method does not check if a ticket is valid which is done using ValidateTicket
	IsWinningTicket(ticket *Ticket, sig []byte, recipientRand *big.Int) bool
}

Validator is an interface which describes an object capable of validating tickets

func NewValidator 

func NewValidator(sigVerifier SigVerifier, roundsManager RoundsManager) Validator

NewValidator returns an instance of a validator

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.