Documentation
¶
Overview ¶
Package activation is responsible for creating activation transactions and running the mining flow, coordinating Post building, sending proofs to PoET and building NIPost structs.
nolint
Index ¶
- Variables
- func SignAtx(signer signer, atx *types.ActivationTx) error
- type Builder
- func (b *Builder) Coinbase() types.Address
- func (b *Builder) GetPositioningAtxInfo() (types.ATXID, types.LayerID, error)
- func (b *Builder) MinGas() uint64
- func (b *Builder) PublishActivationTx(ctx context.Context) error
- func (b *Builder) SetCoinbase(rewardAddress types.Address)
- func (b *Builder) SetMinGas(value uint64)
- func (b *Builder) SignAtx(atx *types.ActivationTx) error
- func (b *Builder) SmesherID() types.NodeID
- func (b *Builder) Smeshing() bool
- func (b *Builder) StartSmeshing(coinbase types.Address, opts PostSetupOpts) error
- func (b *Builder) StopSmeshing(deleteFiles bool) error
- func (b *Builder) UpdatePoETServer(ctx context.Context, target string) error
- type BuilderOption
- type BuilderState
- type Config
- type GetInfoResponse
- type HTTPPoetClient
- type HTTPPoetHarness
- type Handler
- func (h *Handler) AwaitAtx(id types.ATXID) chan struct{}
- func (h *Handler) ContextuallyValidateAtx(atx *types.VerifiedActivationTx) error
- func (h *Handler) FetchAtxReferences(ctx context.Context, atx *types.ActivationTx) error
- func (h *Handler) GetEpochAtxs(epochID types.EpochID) (ids []types.ATXID, err error)
- func (h *Handler) GetPosAtxID() (types.ATXID, error)
- func (h *Handler) HandleAtxData(ctx context.Context, data []byte) error
- func (h *Handler) HandleGossipAtx(ctx context.Context, _ p2p.Peer, msg []byte) pubsub.ValidationResult
- func (h *Handler) ProcessAtx(ctx context.Context, atx *types.VerifiedActivationTx) error
- func (h *Handler) StoreAtx(ctx context.Context, atx *types.VerifiedActivationTx) error
- func (h *Handler) SyntacticallyValidateAtx(ctx context.Context, atx *types.ActivationTx) (*types.VerifiedActivationTx, error)
- func (h *Handler) UnsubscribeAtx(id types.ATXID)
- type NIPostBuilder
- type PoETClientInitializer
- type PoetConfig
- type PoetDb
- func (db *PoetDb) GetMembershipMap(proofRef types.PoetProofRef) (map[types.Hash32]bool, error)
- func (db *PoetDb) GetProof(proofRef types.PoetProofRef) (*types.PoetProof, error)
- func (db *PoetDb) GetProofMessage(proofRef types.PoetProofRef) ([]byte, error)
- func (db *PoetDb) HasProof(proofRef types.PoetProofRef) bool
- func (db *PoetDb) StoreProof(ref types.PoetProofRef, proofMessage *types.PoetProofMessage) error
- func (db *PoetDb) SubscribeToProofRef(poetID []byte, roundID string) chan types.PoetProofRef
- func (db *PoetDb) UnsubscribeFromProofRef(poetID []byte, roundID string)
- func (db *PoetDb) Validate(proof types.PoetProof, poetID []byte, roundID string, signature []byte) error
- func (db *PoetDb) ValidateAndStore(proofMessage *types.PoetProofMessage) error
- func (db *PoetDb) ValidateAndStoreMsg(data []byte) error
- type PoetListener
- type PoetProvingServiceClient
- type PostConfig
- type PostSetupComputeProvider
- type PostSetupManager
- func (mgr *PostSetupManager) Benchmark(p PostSetupComputeProvider) (int, error)
- func (mgr *PostSetupManager) BestProvider() (*PostSetupComputeProvider, error)
- func (mgr *PostSetupManager) ComputeProviders() []PostSetupComputeProvider
- func (mgr *PostSetupManager) Config() PostConfig
- func (mgr *PostSetupManager) GenerateProof(challenge []byte) (*types.Post, *types.PostMetadata, error)
- func (mgr *PostSetupManager) LastError() error
- func (mgr *PostSetupManager) LastOpts() *PostSetupOpts
- func (mgr *PostSetupManager) StartSession(opts PostSetupOpts) (chan struct{}, error)
- func (mgr *PostSetupManager) Status() *PostSetupStatus
- func (mgr *PostSetupManager) StatusChan() <-chan *PostSetupStatus
- func (mgr *PostSetupManager) StopSession(deleteFiles bool) error
- type PostSetupOpts
- type PostSetupProvider
- type PostSetupStatus
- type SmeshingProvider
- type StartRequest
- type SubmitRequest
- type SubmitResponse
- type Validator
Constants ¶
This section is empty.
Variables ¶
var ( // ErrStopRequested is returned when builder is stopped. ErrStopRequested = errors.New("builder: stop requested") // ErrATXChallengeExpired is returned when atx missed its publication window and needs to be regenerated. ErrATXChallengeExpired = errors.New("builder: atx expired") // ErrPoetServiceUnstable is returned when poet quality of service is low. ErrPoetServiceUnstable = errors.New("builder: poet service is unstable") )
Functions ¶
func SignAtx ¶
func SignAtx(signer signer, atx *types.ActivationTx) error
SignAtx signs the atx with specified signer and assigns the signature into atx.Sig this function returns an error if atx could not be converted to bytes.
Types ¶
type Builder ¶
type Builder struct {
// contains filtered or unexported fields
}
Builder struct is the struct that orchestrates the creation of activation transactions it is responsible for initializing post, receiving poet proof and orchestrating nipst. after which it will calculate total weight and providing relevant view as proof.
func NewBuilder ¶
func NewBuilder(conf Config, nodeID types.NodeID, signer signer, cdb *datastore.CachedDB, hdlr atxHandler, publisher pubsub.Publisher, nipostBuilder nipostBuilder, postSetupProvider PostSetupProvider, layerClock layerClock, syncer syncer, log log.Log, opts ...BuilderOption, ) *Builder
NewBuilder returns an atx builder that will start a routine that will attempt to create an atx upon each new layer.
func (*Builder) GetPositioningAtxInfo ¶
GetPositioningAtxInfo returns id and publication layer from the best observed atx.
func (*Builder) PublishActivationTx ¶
PublishActivationTx attempts to publish an atx, it returns an error if an atx cannot be created.
func (*Builder) SetCoinbase ¶ added in v1.0.0
SetCoinbase sets the address rewardAddress to be the coinbase account written into the activation transaction the rewards for blocks made by this miner will go to this address.
func (*Builder) SignAtx ¶
func (b *Builder) SignAtx(atx *types.ActivationTx) error
SignAtx signs the atx and assigns the signature into atx.Sig this function returns an error if atx could not be converted to bytes.
func (*Builder) SmesherID ¶ added in v1.0.0
SmesherID returns the ID of the smesher that created this activation.
func (*Builder) StartSmeshing ¶ added in v1.0.0
func (b *Builder) StartSmeshing(coinbase types.Address, opts PostSetupOpts) error
StartSmeshing is the main entry point of the atx builder. It runs the main loop of the builder and shouldn't be called more than once. If the post data is incomplete or missing, data creation session will be preceded. Changing of the post potions (e.g., number of labels), after initial setup, is supported.
func (*Builder) StopSmeshing ¶ added in v1.0.0
StopSmeshing stops the atx builder.
type BuilderOption ¶ added in v1.0.0
type BuilderOption func(*Builder)
BuilderOption ...
func WithContext ¶ added in v1.0.0
func WithContext(ctx context.Context) BuilderOption
WithContext modifies parent context for background job.
func WithPoETClientInitializer ¶ added in v1.0.0
func WithPoETClientInitializer(initializer PoETClientInitializer) BuilderOption
WithPoETClientInitializer modifies initialization logic for PoET client. Used during client update.
func WithPoetConfig ¶ added in v1.0.0
func WithPoetConfig(c PoetConfig) BuilderOption
WithPoetConfig sets the poet config.
func WithPoetRetryInterval ¶ added in v1.0.0
func WithPoetRetryInterval(interval time.Duration) BuilderOption
WithPoetRetryInterval modifies time that builder will have to wait before retrying ATX build process if it failed due to issues with PoET server.
type BuilderState ¶
type BuilderState struct { Challenge types.Hash32 NIPost *types.NIPost // PoetRound is the round of the PoET proving service in which the PoET challenge was included in. PoetRound *types.PoetRound // PoetServiceID returns the public key of the PoET proving service. PoetServiceID []byte // PoetProofRef is the root of the proof received from the PoET service. PoetProofRef []byte }
BuilderState is a builder state.
func (*BuilderState) DecodeScale ¶
func (t *BuilderState) DecodeScale(dec *scale.Decoder) (total int, err error)
func (*BuilderState) EncodeScale ¶
func (t *BuilderState) EncodeScale(enc *scale.Encoder) (total int, err error)
type GetInfoResponse ¶
GetInfoResponse is the response object for the get-info endpoint.
type HTTPPoetClient ¶
type HTTPPoetClient struct {
// contains filtered or unexported fields
}
HTTPPoetClient implements PoetProvingServiceClient interface.
func NewHTTPPoetClient ¶
func NewHTTPPoetClient(target string) *HTTPPoetClient
NewHTTPPoetClient returns new instance of HTTPPoetClient for the specified target.
func (*HTTPPoetClient) PoetServiceID ¶ added in v0.1.11
func (c *HTTPPoetClient) PoetServiceID(ctx context.Context) ([]byte, error)
PoetServiceID returns the public key of the PoET proving service.
type HTTPPoetHarness ¶
type HTTPPoetHarness struct { *HTTPPoetClient Stdout io.Reader Stderr io.Reader ErrChan <-chan error Teardown func(cleanup bool) error // contains filtered or unexported fields }
HTTPPoetHarness utilizes a local self-contained poet server instance targeted by an HTTP client, in order to exercise functionality.
func NewHTTPPoetHarness ¶
func NewHTTPPoetHarness(disableBroadcast bool) (*HTTPPoetHarness, error)
NewHTTPPoetHarness returns a new instance of HTTPPoetHarness.
type Handler ¶ added in v1.0.0
Handler processes the atxs received from all nodes and their validity status.
func NewHandler ¶ added in v1.0.0
func NewHandler(cdb *datastore.CachedDB, fetcher system.Fetcher, layersPerEpoch uint32, tickSize uint64, goldenATXID types.ATXID, nipostValidator nipostValidator, log log.Log) *Handler
NewHandler returns a data handler for ATX.
func (*Handler) AwaitAtx ¶ added in v1.0.0
AwaitAtx returns a channel that will receive notification when the specified atx with id id is received via gossip.
func (*Handler) ContextuallyValidateAtx ¶ added in v1.0.0
func (h *Handler) ContextuallyValidateAtx(atx *types.VerifiedActivationTx) error
ContextuallyValidateAtx ensures that the previous ATX referenced is the last known ATX for the referenced miner ID. If a previous ATX is not referenced, it validates that indeed there's no previous known ATX for that miner ID.
func (*Handler) FetchAtxReferences ¶ added in v1.0.0
FetchAtxReferences fetches positioning and prev atxs from peers if they are not found in db.
func (*Handler) GetEpochAtxs ¶ added in v1.0.0
GetEpochAtxs returns all valid ATXs received in the epoch epochID.
func (*Handler) GetPosAtxID ¶
GetPosAtxID returns the best (highest layer id), currently known to this node, pos atx id.
func (*Handler) HandleAtxData ¶ added in v1.0.0
HandleAtxData handles atxs received either by gossip or sync.
func (*Handler) HandleGossipAtx ¶ added in v1.0.0
func (h *Handler) HandleGossipAtx(ctx context.Context, _ p2p.Peer, msg []byte) pubsub.ValidationResult
HandleGossipAtx handles the atx gossip data channel.
func (*Handler) ProcessAtx ¶ added in v1.0.0
ProcessAtx validates the active set size declared in the atx, and contextually validates the atx according to atx validation rules it then stores the atx with flag set to validity of the atx.
ATXs received as input must be already syntactically valid. Only contextual validation is performed.
func (*Handler) SyntacticallyValidateAtx ¶ added in v1.0.0
func (h *Handler) SyntacticallyValidateAtx(ctx context.Context, atx *types.ActivationTx) (*types.VerifiedActivationTx, error)
SyntacticallyValidateAtx ensures the following conditions apply, otherwise it returns an error.
- If the sequence number is non-zero: PrevATX points to a syntactically valid ATX whose sequence number is one less than the current ATXs sequence number.
- If the sequence number is zero: PrevATX is empty.
- Positioning ATX points to a syntactically valid ATX.
- NIPost challenge is a hash of the serialization of the following fields: NodeID, SequenceNumber, PrevATXID, LayerID, StartTick, PositioningATX.
- The NIPost is valid.
- ATX LayerID is NIPostLayerTime or less after the PositioningATX LayerID.
- The ATX view of the previous epoch contains ActiveSetSize activations.
func (*Handler) UnsubscribeAtx ¶ added in v1.0.0
UnsubscribeAtx un subscribes the waiting for a specific atx with atx id id to arrive via gossip.
type NIPostBuilder ¶ added in v1.0.0
type NIPostBuilder struct {
// contains filtered or unexported fields
}
NIPostBuilder holds the required state and dependencies to create Non-Interactive Proofs of Space-Time (NIPost).
func NewNIPostBuilder ¶ added in v1.0.0
func NewNIPostBuilder( minerID []byte, postSetupProvider PostSetupProvider, poetProver PoetProvingServiceClient, poetDB poetDbAPI, db *sql.Database, log log.Log, ) *NIPostBuilder
NewNIPostBuilder returns a NIPostBuilder.
func (*NIPostBuilder) BuildNIPost ¶ added in v1.0.0
func (nb *NIPostBuilder) BuildNIPost(ctx context.Context, challenge *types.Hash32, atxExpired chan struct{}) (*types.NIPost, error)
BuildNIPost uses the given challenge to build a NIPost. "atxExpired" and "stop" are channels for early termination of the building process. The process can take considerable time, because it includes waiting for the poet service to publish a proof - a process that takes about an epoch.
type PoETClientInitializer ¶ added in v1.0.0
type PoETClientInitializer func(string) PoetProvingServiceClient
PoETClientInitializer interfaces for creating PoetProvingServiceClient.
type PoetConfig ¶ added in v1.0.0
type PoetConfig struct { PhaseShift time.Duration `mapstructure:"phase-shift"` CycleGap time.Duration `mapstructure:"cycle-gap"` GracePeriod time.Duration `mapstructure:"grace-period"` }
PoetConfig is the configuration to interact with the poet server.
func DefaultPoetConfig ¶ added in v1.0.0
func DefaultPoetConfig() PoetConfig
type PoetDb ¶
type PoetDb struct {
// contains filtered or unexported fields
}
PoetDb is a database for PoET proofs.
func (*PoetDb) GetMembershipMap ¶
GetMembershipMap returns the map of memberships in the requested PoET proof.
func (*PoetDb) GetProofMessage ¶
func (db *PoetDb) GetProofMessage(proofRef types.PoetProofRef) ([]byte, error)
GetProofMessage returns the originally received PoET proof message.
func (*PoetDb) HasProof ¶
func (db *PoetDb) HasProof(proofRef types.PoetProofRef) bool
HasProof returns true if the database contains a proof with the given reference, or false otherwise.
func (*PoetDb) StoreProof ¶ added in v1.0.0
func (db *PoetDb) StoreProof(ref types.PoetProofRef, proofMessage *types.PoetProofMessage) error
StoreProof saves the poet proof in local db.
func (*PoetDb) SubscribeToProofRef ¶
func (db *PoetDb) SubscribeToProofRef(poetID []byte, roundID string) chan types.PoetProofRef
SubscribeToProofRef returns a channel that PoET proof ref for the requested PoET ID and round ID will be sent. If the proof is already available it will be sent immediately, otherwise it will be sent when available.
func (*PoetDb) UnsubscribeFromProofRef ¶
UnsubscribeFromProofRef removes all subscriptions from a given poetID and roundID. This method should be used with caution since any subscribers still waiting will now hang forever. TODO: only cancel specific subscription.
func (*PoetDb) Validate ¶
func (db *PoetDb) Validate(proof types.PoetProof, poetID []byte, roundID string, signature []byte) error
Validate validates a new PoET proof.
func (*PoetDb) ValidateAndStore ¶
func (db *PoetDb) ValidateAndStore(proofMessage *types.PoetProofMessage) error
ValidateAndStore validates and stores a new PoET proof.
func (*PoetDb) ValidateAndStoreMsg ¶ added in v0.1.16
ValidateAndStoreMsg validates and stores a new PoET proof.
type PoetListener ¶
type PoetListener struct {
// contains filtered or unexported fields
}
PoetListener handles PoET gossip messages.
func NewPoetListener ¶
func NewPoetListener(poetDb poetValidatorPersistor, logger log.Log) *PoetListener
NewPoetListener returns a new PoetListener.
func (*PoetListener) HandlePoetProofMessage ¶
func (l *PoetListener) HandlePoetProofMessage(ctx context.Context, _ p2p.Peer, msg []byte) pubsub.ValidationResult
HandlePoetProofMessage is a receiver for broadcast messages.
type PoetProvingServiceClient ¶
type PoetProvingServiceClient interface { // Submit registers a challenge in the proving service current open round. Submit(ctx context.Context, challenge types.Hash32) (*types.PoetRound, error) // PoetServiceID returns the public key of the PoET proving service. PoetServiceID(context.Context) ([]byte, error) }
PoetProvingServiceClient provides a gateway to a trust-less public proving service, which may serve many PoET proving clients, and thus enormously reduce the cost-per-proof for PoET since each additional proof adds only a small number of hash evaluations to the total cost.
type PostConfig ¶ added in v1.0.0
type PostConfig struct { BitsPerLabel uint `mapstructure:"post-bits-per-label"` LabelsPerUnit uint `mapstructure:"post-labels-per-unit"` MinNumUnits uint `mapstructure:"post-min-numunits"` MaxNumUnits uint `mapstructure:"post-max-numunits"` K1 uint `mapstructure:"post-k1"` K2 uint `mapstructure:"post-k2"` }
PostConfig is the configuration of the Post protocol, used for data creation, proofs generation and validation.
func DefaultPostConfig ¶ added in v1.0.0
func DefaultPostConfig() PostConfig
DefaultPostConfig defines the default configuration for Post.
type PostSetupComputeProvider ¶
type PostSetupComputeProvider initialization.ComputeProvider
PostSetupComputeProvider represent a compute provider for Post setup data creation.
type PostSetupManager ¶ added in v1.0.0
type PostSetupManager struct {
// contains filtered or unexported fields
}
PostSetupManager implements the PostProvider interface.
func NewPostSetupManager ¶ added in v1.0.0
func NewPostSetupManager(id []byte, cfg PostConfig, logger log.Log) (*PostSetupManager, error)
NewPostSetupManager creates a new instance of PostSetupManager.
func (*PostSetupManager) Benchmark ¶ added in v1.0.0
func (mgr *PostSetupManager) Benchmark(p PostSetupComputeProvider) (int, error)
Benchmark runs a short benchmarking session for a given provider to evaluate its performance.
func (*PostSetupManager) BestProvider ¶ added in v1.0.0
func (mgr *PostSetupManager) BestProvider() (*PostSetupComputeProvider, error)
BestProvider returns the most performant compute provider based on a short benchmarking session.
func (*PostSetupManager) ComputeProviders ¶
func (mgr *PostSetupManager) ComputeProviders() []PostSetupComputeProvider
ComputeProviders returns a list of available compute providers for Post setup.
func (*PostSetupManager) Config ¶ added in v1.0.0
func (mgr *PostSetupManager) Config() PostConfig
Config returns the Post protocol config.
func (*PostSetupManager) GenerateProof ¶ added in v1.0.0
func (mgr *PostSetupManager) GenerateProof(challenge []byte) (*types.Post, *types.PostMetadata, error)
GenerateProof generates a new Post.
func (*PostSetupManager) LastError ¶
func (mgr *PostSetupManager) LastError() error
LastError returns the Post setup last error.
func (*PostSetupManager) LastOpts ¶ added in v1.0.0
func (mgr *PostSetupManager) LastOpts() *PostSetupOpts
LastOpts returns the Post setup last session options.
func (*PostSetupManager) StartSession ¶ added in v1.0.0
func (mgr *PostSetupManager) StartSession(opts PostSetupOpts) (chan struct{}, error)
StartSession starts (or continues) a data creation session. It supports resuming a previously started session, as well as changing the Post setup options (e.g., number of units) after initial setup.
func (*PostSetupManager) Status ¶ added in v1.0.0
func (mgr *PostSetupManager) Status() *PostSetupStatus
Status returns the setup current status.
func (*PostSetupManager) StatusChan ¶
func (mgr *PostSetupManager) StatusChan() <-chan *PostSetupStatus
StatusChan returns a channel with status updates of the setup current or the upcoming session.
func (*PostSetupManager) StopSession ¶
func (mgr *PostSetupManager) StopSession(deleteFiles bool) error
StopSession stops the current Post setup data creation session and optionally attempts to delete the data file(s).
type PostSetupOpts ¶ added in v1.0.0
type PostSetupOpts struct { DataDir string `mapstructure:"smeshing-opts-datadir"` NumUnits uint `mapstructure:"smeshing-opts-numunits"` NumFiles uint `mapstructure:"smeshing-opts-numfiles"` ComputeProviderID int `mapstructure:"smeshing-opts-provider"` Throttle bool `mapstructure:"smeshing-opts-throttle"` }
PostSetupOpts are the options used to initiate a Post setup data creation session, either via the public smesher API, or on node launch (via cmd args).
func DefaultPostSetupOpts ¶ added in v1.0.0
func DefaultPostSetupOpts() PostSetupOpts
DefaultPostSetupOpts defines the default options for Post setup.
type PostSetupProvider ¶ added in v1.0.0
type PostSetupProvider interface { Status() *PostSetupStatus StatusChan() <-chan *PostSetupStatus ComputeProviders() []PostSetupComputeProvider Benchmark(p PostSetupComputeProvider) (int, error) StartSession(opts PostSetupOpts) (chan struct{}, error) StopSession(deleteFiles bool) error GenerateProof(challenge []byte) (*types.Post, *types.PostMetadata, error) LastError() error LastOpts() *PostSetupOpts Config() PostConfig }
PostSetupProvider defines the functionality required for Post setup.
type PostSetupStatus ¶ added in v1.0.0
type PostSetupStatus struct { State postSetupState NumLabelsWritten uint64 LastOpts *PostSetupOpts LastError error }
PostSetupStatus represents a status snapshot of the Post setup.
type SmeshingProvider ¶ added in v1.0.0
type SmeshingProvider interface { Smeshing() bool StartSmeshing(types.Address, PostSetupOpts) error StopSmeshing(bool) error SmesherID() types.NodeID Coinbase() types.Address SetCoinbase(coinbase types.Address) MinGas() uint64 SetMinGas(value uint64) }
SmeshingProvider defines the functionality required for the node's Smesher API.
type StartRequest ¶
type StartRequest struct { GatewayAddresses []string `json:"gatewayAddresses,omitempty"` DisableBroadcast bool `json:"disableBroadcast,omitempty"` ConnAcksThreshold int `json:"connAcksThreshold,omitempty"` BroadcastAcksThreshold int `json:"broadcastAcksThreshold,omitempty"` }
StartRequest is the request object for the start endpoint.
type SubmitRequest ¶
type SubmitRequest struct {
Challenge []byte `json:"challenge,omitempty"`
}
SubmitRequest is the request object for the submit endpoint.
type SubmitResponse ¶
type SubmitResponse struct {
RoundID string
}
SubmitResponse is the response object for the submit endpoint.
type Validator ¶
type Validator struct {
// contains filtered or unexported fields
}
Validator contains the dependencies required to validate NIPosts.
func NewValidator ¶
func NewValidator(poetDb poetDbAPI, cfg PostConfig) *Validator
NewValidator returns a new NIPost validator.
func (*Validator) Validate ¶
func (v *Validator) Validate(minerID signing.PublicKey, nipost *types.NIPost, expectedChallenge types.Hash32, numUnits uint) (uint64, error)
Validate validates a NIPost, given a miner id and expected challenge. It returns an error if an issue is found or nil if the NIPost is valid. Some of the Post metadata fields validation values is ought to eventually be derived from consensus instead of local configuration. If so, their validation should be removed to contextual validation, while still syntactically-validate them here according to locally configured min/max values.
func (*Validator) ValidatePost ¶
func (v *Validator) ValidatePost(id []byte, PoST *types.Post, PostMetadata *types.PostMetadata, numUnits uint) error
ValidatePost validates a Proof of Space-Time (PoST). It returns nil if validation passed or an error indicating why validation failed.