service

Documentation

Overview

Package service provides functionality for creating proofs in dedicated rounds, so that they can be shared among arbitrary number of miners, and thus amortize the CPU cost per proof.

Each round starts by being open for receiving challenges (byte arrays) from miners. Once finalized (according to the configured duration), a hash digest is created from the received challenges, and is used as the input for the proof generation. Once completed, the proof is stored in a database and available for nodes via a GRPC query. In addition to the PoET, the proof also contains the list of received challenges, so that the membership of each challenge can be publicly verified.

Index

• Variables
• type Command
• type Config
• type InfoResponse
• type OptionFunc
  • func WithPowVerifier(v PowVerifier) OptionFunc
• type PowParams
  • func NewPowParams(challenge []byte, difficulty uint) PowParams
  • func (p PowParams) Equal(other PowParams) bool
• type PowVerifier
  • func NewPowVerifier(params PowParams) PowVerifier
• type ProofsDatabase
  • func NewProofsDatabase(dbPath string, proofs <-chan proofMessage) (*ProofsDatabase, error)
  • func (db *ProofsDatabase) Get(ctx context.Context, roundID string) (*proofMessage, error)
  • func (db *ProofsDatabase) Run(ctx context.Context) error
• type Service
  • func NewService(ctx context.Context, cfg *Config, datadir string, opts ...OptionFunc) (*Service, error)
  • func (s *Service) Info(ctx context.Context) (*InfoResponse, error)
  • func (s *Service) PowParams() PowParams
  • func (s *Service) ProofsChan() <-chan proofMessage
  • func (s *Service) Run(ctx context.Context) error
  • func (s *Service) Start(ctx context.Context) error
  • func (s *Service) Started() bool
  • func (s *Service) Submit(ctx context.Context, challenge, nodeID []byte, nonce uint64, ...) (*SubmitResult, error)
• type SubmitResult

Variables

var (
	ErrInvalidPow       = errors.New("invalid proof of work")
	ErrInvalidPowParams = errors.New("invalid proof of work parameters")
)

var (
	ErrNotStarted                = errors.New("service not started")
	ErrAlreadyStarted            = errors.New("already started")
	ErrChallengeAlreadySubmitted = errors.New("challenge is already submitted")
	ErrRoundNotFinished          = errors.New("round is not finished yet")
)

var ErrFileIsMissing = errors.New("file is missing")

var ErrNotFound = leveldb.ErrNotFound

var ErrRoundIsNotOpen = errors.New("round is not open")

Types

type Command

type Command func(*Service)

Command is a function that will be run in the main Service loop. Commands are run serially hence they don't require additional synchronization. The functions cannot block and should be kept short to not block the Service loop.

type Config

type Config struct {
	Genesis       string        `long:"genesis-time"   description:"Genesis timestamp"`
	EpochDuration time.Duration `long:"epoch-duration" description:"Epoch duration"`
	PhaseShift    time.Duration `long:"phase-shift"`
	CycleGap      time.Duration `long:"cycle-gap"`
	NoRecovery    bool          `long:"norecovery"     description:"whether to disable a potential recovery procedure"`
	Reset         bool          `long:"reset"          description:"whether to reset the service state by deleting the datadir"`

	InitialPowChallenge string `long:"pow-challenge"  description:"The initial PoW challenge for the first round"`
	PowDifficulty       uint   `long:"pow-difficulty" description:"PoW difficulty (in the number of leading zero bits)"`

	// Merkle-Tree related configuration:
	EstimatedLeavesPerSecond uint `long:"lps"              description:"Estimated number of leaves generated per second"`
	MemoryLayers             uint `long:"memory"           description:"Number of top Merkle tree layers to cache in-memory"`
	TreeFileBufferSize       uint `long:"tree-file-buffer" description:"The size of memory buffer for file-based tree layers"`
}

type InfoResponse

type InfoResponse struct {
	OpenRoundID        string
	ExecutingRoundsIds []string
}

type OptionFunc

type OptionFunc func(*option) error

func WithPowVerifier

func WithPowVerifier(v PowVerifier) OptionFunc

type PowParams

type PowParams struct {
	Challenge []byte
	// Difficulty is the number of leading zero bits required in the hash
	Difficulty uint
}

func NewPowParams

func NewPowParams(challenge []byte, difficulty uint) PowParams

func (PowParams) Equal

func (p PowParams) Equal(other PowParams) bool

type PowVerifier

type PowVerifier interface {
	// Verify the proof of work.
	//
	// PoW hash is ripemd256(powChallenge || nodeID || poetChallenge || nonce)
	Verify(poetChallenge, nodeID []byte, nonce uint64) error
	Params() PowParams
	SetParams(PowParams)
}

func NewPowVerifier

func NewPowVerifier(params PowParams) PowVerifier

type ProofsDatabase

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

func NewProofsDatabase

func NewProofsDatabase(dbPath string, proofs <-chan proofMessage) (*ProofsDatabase, error)

func (*ProofsDatabase) Get

func (db *ProofsDatabase) Get(ctx context.Context, roundID string) (*proofMessage, error)

func (*ProofsDatabase) Run

func (db *ProofsDatabase) Run(ctx context.Context) error

type Service

type Service struct {
	PubKey ed25519.PublicKey
	// contains filtered or unexported fields
}

Service orchestrates rounds functionality It is responsible for accepting challenges, generating a proof from their hash digest and persisting it.

`Service` is single-use, meaning it can be started with `Service::Run`. It is stopped by canceling the context provided to `Service::Run`. It mustn't be restarted. A new instance of `Service` must be created.

func NewService

func NewService(ctx context.Context, cfg *Config, datadir string, opts ...OptionFunc) (*Service, error)

NewService creates a new instance of Poet Service. It should be started with `Service::Run`.

func (*Service) Info

func (s *Service) Info(ctx context.Context) (*InfoResponse, error)

func (*Service) PowParams

func (s *Service) PowParams() PowParams

func (*Service) ProofsChan

func (s *Service) ProofsChan() <-chan proofMessage

func (*Service) Run

func (s *Service) Run(ctx context.Context) error

Run starts the Service's actor event loop. It stops when the `ctx` is canceled.

func (*Service) Start

func (s *Service) Start(ctx context.Context) error

Start starts proofs generation.

func (*Service) Started

func (s *Service) Started() bool

Started returns whether the `Service` is generating proofs.

func (*Service) Submit

func (s *Service) Submit(
	ctx context.Context,
	challenge, nodeID []byte,
	nonce uint64,
	powParams PowParams,
) (*SubmitResult, error)

type SubmitResult

type SubmitResult struct {
	Round    string
	RoundEnd time.Duration
}