pool

Documentation

Overview

Package pool implements the open Bitcoin 09 remote-solo mining protocol.

Index

• Variables
• func NewHTTPHandler(coordinator *Coordinator, config HTTPConfig) http.Handler
• func NewHTTPServer(address string, handler http.Handler) *http.Server
• func ParseWork(work Work, params *core.Params) (core.Header, *big.Int, error)
• type Coordinator
  • func NewCoordinator(chain *core.Chain, config CoordinatorConfig) (*Coordinator, error)
  • func (c *Coordinator) Issue(address, worker string) (Work, error)
  • func (c *Coordinator) Submit(jobID string, nonce uint64) (SubmitResult, error)
• type CoordinatorConfig
• type HTTPConfig
• type MineResult
  • func MineWork(ctx context.Context, work Work, params *core.Params, workers int) (MineResult, error)
• type RemoteAPIError
  • func (e *RemoteAPIError) Error() string
• type RemoteClient
  • func NewRemoteClient(config RemoteClientConfig) (*RemoteClient, error)
  • func (c *RemoteClient) MineOnce(ctx context.Context) (MineResult, SubmitResult, error)
  • func (c *RemoteClient) RequestWork(ctx context.Context) (Work, error)
  • func (c *RemoteClient) Run(ctx context.Context, accepted func(MineResult, SubmitResult)) error
  • func (c *RemoteClient) Submit(ctx context.Context, jobID string, nonce uint64) (SubmitResult, error)
• type RemoteClientConfig
• type SubmitResult
• type Work

Variables

var (
	ErrUnknownJob          = errors.New("unknown mining job")
	ErrExpiredJob          = errors.New("mining job expired")
	ErrStaleJob            = errors.New("mining job is stale")
	ErrDuplicateSubmission = errors.New("duplicate nonce submission")
	ErrLowDifficulty       = errors.New("nonce does not meet network target")
	ErrBlockRejected       = errors.New("mined block rejected")
)

Functions

func NewHTTPHandler

func NewHTTPHandler(coordinator *Coordinator, config HTTPConfig) http.Handler

NewHTTPHandler returns the versioned nonce-only remote mining API.

func NewHTTPServer

func NewHTTPServer(address string, handler http.Handler) *http.Server

NewHTTPServer applies finite network timeouts suitable for a public API.

func ParseWork

func ParseWork(work Work, params *core.Params) (core.Header, *big.Int, error)

ParseWork validates and decodes a coordinator-owned work item.

Types

type Coordinator

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

Coordinator owns canonical templates and accepts nonce-only submissions.

func NewCoordinator

func NewCoordinator(chain *core.Chain, config CoordinatorConfig) (*Coordinator, error)

func (*Coordinator) Issue

func (c *Coordinator) Issue(address, worker string) (Work, error)

Issue builds a short-lived canonical block template paying address.

func (*Coordinator) Submit

func (c *Coordinator) Submit(jobID string, nonce uint64) (SubmitResult, error)

Submit reconstructs a coordinator-owned job with nonce and accepts a valid network block through the normal chain-validation path.

type CoordinatorConfig

type CoordinatorConfig struct {
	JobTTL  time.Duration
	MaxJobs int
	Tag     string
	Now     func() time.Time
}

CoordinatorConfig bounds the in-memory remote-solo job service.

type HTTPConfig

type HTTPConfig struct {
	MaxBodyBytes                  int64
	WorkRequestsPerMinute         int
	SubmitsPerMinute              int
	TrustProxyHeadersFromLoopback bool
	Now                           func() time.Time
}

HTTPConfig bounds requests to the public mining API.

type MineResult

type MineResult struct {
	Found  bool
	Nonce  uint64
	Hashes uint64
}

MineResult records a locally discovered network-winning nonce.

func MineWork

func MineWork(ctx context.Context, work Work, params *core.Params, workers int) (MineResult, error)

MineWork searches the nonce field of one coordinator-issued work item.

type RemoteAPIError

type RemoteAPIError struct {
	StatusCode int
	Code       string
}

func (*RemoteAPIError) Error

func (e *RemoteAPIError) Error() string

type RemoteClient

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

RemoteClient mines coordinator-owned jobs while keeping the payout address under the miner's control.

func NewRemoteClient

func NewRemoteClient(config RemoteClientConfig) (*RemoteClient, error)

func (*RemoteClient) MineOnce

func (c *RemoteClient) MineOnce(ctx context.Context) (MineResult, SubmitResult, error)

MineOnce requests one job, searches it until solved or expired, and submits only a network-winning nonce.

func (*RemoteClient) RequestWork

func (c *RemoteClient) RequestWork(ctx context.Context) (Work, error)

func (*RemoteClient) Run

func (c *RemoteClient) Run(ctx context.Context, accepted func(MineResult, SubmitResult)) error

Run continuously refreshes jobs. Stale and expired jobs are normal and are replaced without terminating the miner.

func (*RemoteClient) Submit

func (c *RemoteClient) Submit(ctx context.Context, jobID string, nonce uint64) (SubmitResult, error)

type RemoteClientConfig

type RemoteClientConfig struct {
	PoolURL           string
	Address           string
	Worker            string
	Params            *core.Params
	Workers           int
	AllowInsecureHTTP bool
	HTTPClient        *http.Client
}

type SubmitResult

type SubmitResult struct {
	SchemaVersion int    `json:"schema_version"`
	Network       string `json:"network"`
	Status        string `json:"status"`
	BlockID       string `json:"block_id"`
	Height        int64  `json:"height"`
}

SubmitResult describes one accepted network block.

type Work

type Work struct {
	SchemaVersion int       `json:"schema_version"`
	Network       string    `json:"network"`
	JobID         string    `json:"job_id"`
	Height        int64     `json:"height"`
	HeaderHex     string    `json:"header_hex"`
	TargetHex     string    `json:"target_hex"`
	ExpiresAt     time.Time `json:"expires_at"`
	ArgonMemKiB   uint32    `json:"argon_mem_kib"`
	ArgonTime     uint32    `json:"argon_time"`
}

Work is a canonical remote-solo mining job. The client may change only the nonce in the final eight bytes of HeaderHex.