Stratum

package module
v1.0.0 Latest Latest
Warning

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

 Go to latest Published: Oct 3, 2021 License: ISC Imports: 7 Imported by: 0

README

A Golang library for the Stratum Protocol

Stratum is how Bitcoin miners connect with mining pools.

See here for a description of Stratum and here for Stratum extensions. Extensions are necessary to support ASIC Boost.

Supported Methods

  • mining.configure
  • mining.authorize
  • mining.subscribe
  • mining.set_difficulty
  • mining.set_version_mask
  • mining.notify
  • mining.submit

Unsupported methods

  • mining.set_extranonce
  • mining.suggest_difficulty
  • mining.suggest_target
  • mining.get_transactions
  • client.get_version
  • client.reconnect
  • client.show_message

Method types

Some methods are client-to-server, others are server-to-client. Some methods require a response, others do not.

Client-to-server
method type
mining.configure request / response
mining.authorize request / response
mining.subscribe request / response
mining.submit request / response
mining.suggest_difficulty notification
mining.suggest_target notification
mining.get_transactions request / response
Server-to-client
method type
mining.set_difficulty notification
mining.set_version_mask notification
mining.notify notification
mining.set_extranonce notification
client.get_version request / response
client.reconnect notification
client.show_message notification

Message Formats

Stratum uses json. There are three message types: notification, request, and response.

Notification

Notification is for methods that don't require a response.

{
  method: string,        // one of the methods above
  params: [json...]      // array of json values
}
Request

Request is for methods that require a response.

{
  "id": integer or string, // a unique id
  "method": string,        // one of the methods above
  "params": [json...]      // array of json values
}
Response

Response is the response to requests.

{
  "id": integer or string,   // a unique id, must be the same as on the request
  "result": json,            // could be anything
  "error": null or [
    unsigned int,            // error code
    string                   // error message
  ]
}

Methods

mining.authorize

The first message that is sent in classic Stratum. For extended Stratum, mining.configure comes first and then mining.authorize.

mining.subscribe

Sent by the client after mining.authorize.

mining.set_difficulty

Sent by the server after responding to mining.subscribe and every time the difficulty changes.

mining.notify

Sent by the server whenever the block is updated. This happens periodically as the block is being built and when a new block is discovered.

mining.configure

The first message that is sent in extended Stratum. Necessary for ASICBoost. The client sends this to tell the server what extensions it supports.

mining.set_version_mask

Sent by the server to notify of a change in version mask. Requires the version-rolling extension.

mining.submit

Sent by the client when a new share is mined. Modified by version-rolling.

Documentation

Index

Constants

View Source 
const (
	Unknown = iota
	VersionRolling
	MinimumDifficulty
	SubscribeExtranonce
	Info
)

Variables

This section is empty.

Functions

func AuthorizeRequest 

func AuthorizeRequest(id MessageID, r AuthorizeParams) request

func AuthorizeResponse 

func AuthorizeResponse(id MessageID, b bool) response

func BooleanResponse 

func BooleanResponse(id MessageID, x bool) response

func ConfigureRequest 

func ConfigureRequest(id MessageID, p ConfigureParams) request

func ConfigureResponse 

func ConfigureResponse(id MessageID, r ConfigureResult) response

func EncodeExtension 

func EncodeExtension(m Extension) (string, error)

func EncodeMethod 

func EncodeMethod(m Method) (string, error)

func ErrorResponse 

func ErrorResponse(id MessageID, e Error) response

func Notification 

func Notification(m Method, params []interface{}) notification

func Notify 

func Notify(n NotifyParams) notification

func Request 

func Request(id MessageID, m Method, params []interface{}) request

func Response 

func Response(id MessageID, r interface{}) response

func SetDifficulty 

func SetDifficulty(d Difficulty) notification

func SetVersionMask 

func SetVersionMask(u uint32) notification

func Submit 

func Submit(id MessageID, share SubmitParams) request

func SubmitResponse 

func SubmitResponse(id MessageID, b bool) response

func SubscribeRequest 

func SubscribeRequest(id MessageID, r SubscribeParams) request

func SubscribeResponse 

func SubscribeResponse(m MessageID, r SubscribeResult) response

func ValidDifficulty 

func ValidDifficulty(u Difficulty) bool

Difficulty can be given as a uint or a float.

func ValidMessageID 

func ValidMessageID(id MessageID) bool

MessageIDs are allowed to be integers or strings.

Types

type AuthorizeParams 

type AuthorizeParams struct {
	Username string

	// Password is optional. Pools don't necessarily require a miner to log in to mine.
	Password *string
}

func (*AuthorizeParams) Read 

func (p *AuthorizeParams) Read(r *request) error

type AuthorizeResult 

type AuthorizeResult BooleanResult

type BooleanResult 

type BooleanResult struct {
	Result bool
}

func (*BooleanResult) Read 

func (b *BooleanResult) Read(r *response) error

type ConfigureParams 

type ConfigureParams struct {
	Supported  []string
	Parameters map[string]interface{}
}

func (*ConfigureParams) Add 

func (p *ConfigureParams) Add(z interface{}) error

func (*ConfigureParams) ReadInfo 

func (p *ConfigureParams) ReadInfo() *InfoConfigurationRequest

func (*ConfigureParams) ReadMinimumDifficulty 

func (p *ConfigureParams) ReadMinimumDifficulty() *MinimumDifficultyConfigurationRequest

func (*ConfigureParams) ReadSubscribeExtranonce 

func (p *ConfigureParams) ReadSubscribeExtranonce() *SubscribeExtranonceConfigurationRequest

func (*ConfigureParams) ReadVersionRolling 

func (p *ConfigureParams) ReadVersionRolling() *VersionRollingConfigurationRequest

type ConfigureResult 

type ConfigureResult map[string]interface{}

func (*ConfigureResult) Add 

func (p *ConfigureResult) Add(z interface{}) error

func (*ConfigureResult) ReadInfo 

func (p *ConfigureResult) ReadInfo() *InfoConfigurationResult

func (*ConfigureResult) ReadMinimumDifficulty 

func (p *ConfigureResult) ReadMinimumDifficulty() *MinimumDifficultyConfigurationResult

func (*ConfigureResult) ReadSubscribeExtranonce 

func (p *ConfigureResult) ReadSubscribeExtranonce() *SubscribeExtranonceConfigurationResult

func (*ConfigureResult) ReadVersionRolling 

func (p *ConfigureResult) ReadVersionRolling() *VersionRollingConfigurationResult

type Difficulty 

type Difficulty interface{}

type Error 

type Error struct {
	Code    ErrorCode
	Message string
}

Error is a 2-element json array.

type ErrorCode 

type ErrorCode uint32
const (
	None ErrorCode = iota
)

the Stratum protocol does not define any error codes. Each pool has its own set of errors, apparently. You can define your own.

type Extension 

type Extension uint8

func DecodeExtension 

func DecodeExtension(m string) (Extension, error)

type ID 

type ID uint32

A stratum session id is assigned by the mining pool to a miner and it is included in the coinbase script of the block that is produced. we also use ID for job ids.

type InfoConfigurationRequest 

type InfoConfigurationRequest struct {
	ConnectionURL *string
	HWVersion     *string
	SWVersion     *string
	HWID          *string
}

type InfoConfigurationResult 

type InfoConfigurationResult struct {
	Accepted bool
}

type MessageID 

type MessageID interface{}

MessageID is a unique identifier that is different for each notification and request / response.

type Method 

type Method uint8
const (
	Unset Method = iota
	MiningAuthorize
	MiningConfigure
	MiningSubscribe
	MiningNotify
	MiningSubmit
	MiningSetDifficulty
	MiningSetVersionMask
	MiningSetExtraNonce
	MiningSuggestDifficulty
	MiningSuggestTarget
	ClientGetVersion
	ClientReconnect
	ClientGetTransactions
	ClientShowMessage
)

func DecodeMethod 

func DecodeMethod(m string) (Method, error)

type MinimumDifficultyConfigurationRequest 

type MinimumDifficultyConfigurationRequest struct {
	Difficulty Difficulty
}

type MinimumDifficultyConfigurationResult 

type MinimumDifficultyConfigurationResult struct {
	Accepted bool
}

type NotifyParams 

type NotifyParams struct {
	JobID         ID
	Digest        []byte
	GenerationTX1 []byte
	GenerationTX2 []byte
	Path          [][]byte
	Version       uint32
	Target        []byte
	Timestamp     uint32
	Clean         bool
}

type SetDifficultyParams 

type SetDifficultyParams struct {
	Difficulty Difficulty
}

func (*SetDifficultyParams) Read 

func (p *SetDifficultyParams) Read(n *notification) error

type SetVersionMaskParams 

type SetVersionMaskParams struct {
	Mask uint32
}

type Share 

type Share struct {
	Name  WorkerName
	JobID ID
	work.Share
}

A share is the data returned by the worker in mining.submit.

type SubmitParams 

type SubmitParams Share

type SubmitResult 

type SubmitResult BooleanResult

type SubscribeExtranonceConfigurationRequest 

type SubscribeExtranonceConfigurationRequest struct{}

type SubscribeExtranonceConfigurationResult 

type SubscribeExtranonceConfigurationResult struct {
	Accepted bool
}

type SubscribeParams 

type SubscribeParams struct {
	UserAgent   string
	ExtraNonce1 *ID
}

func (*SubscribeParams) Read 

func (p *SubscribeParams) Read(r *request) error

type SubscribeResult 

type SubscribeResult struct {
	Subscriptions   []Subscription
	ExtraNonce1     ID
	ExtraNonce2Size uint32
}

func (*SubscribeResult) Read 

func (p *SubscribeResult) Read(r *response) error

type Subscription 

type Subscription struct {
	Method    Method
	SessionID ID
}

A Subscription is a 2-element json array containing a method and a session id.

type VersionRollingConfigurationRequest 

type VersionRollingConfigurationRequest struct {
	Mask        uint32
	MinBitCount byte
}

type VersionRollingConfigurationResult 

type VersionRollingConfigurationResult struct {
	Accepted bool
	Mask     uint32
}

type Worker 

type Worker struct {
	Name            WorkerName
	SessionID       ID
	ExtraNonce2Size uint32
	VersionMask     *uint32
}

Worker represents a miner who is doing work for the pool. This would be used in an implementation of a Stratum server and is not part of the Stratum protocol.

type WorkerName 

type WorkerName string

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.