minercraft

package module
v0.9.2 Latest Latest
Warning

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

 Go to latest Published: Jun 12, 2023 License: MIT Imports: 17 Imported by: 1

README

go-minercraft

Interact with Bitcoin Miner APIs (unofficial Go library of Minercraft)

Release Build Status Report codecov Go mAPI mAPI
Mergify Status Gitpod Ready-to-Code


Table of Contents


Installation

go-minercraft requires a supported release of Go.

go get -u github.com/tonicpow/go-minercraft

Documentation

View the generated documentation

GoDoc

This package interacts with BSV miners using the Merchant API specification.

View documentation on hosting your own mAPI server.

Features
Library Deployment

goreleaser for easy binary or library deployment to GitHub and can be installed via: brew install goreleaser.

The .goreleaser.yml file is used to configure goreleaser.

Use make release-snap to create a snapshot version of the release, and finally make release to ship to production.

Makefile Commands

View all makefile commands

make help

List of all current commands:

all                   Runs multiple commands
clean                 Remove previous builds and any test cache data
clean-mods            Remove all the Go mod cache
coverage              Shows the test coverage
diff                  Show the git diff
generate              Runs the go generate command in the base of the repo
godocs                Sync the latest tag with GoDocs
help                  Show this help message
install               Install the application
install-go            Install the application (Using Native Go)
install-releaser      Install the GoReleaser application
lint                  Run the golangci-lint application (install if not found)
release               Full production release (creates release in Github)
release               Runs common.release then runs godocs
release-snap          Test the full release (build binaries)
release-test          Full production test release (everything except deploy)
replace-version       Replaces the version in HTML/JS (pre-deploy)
tag                   Generate a new tag and push (tag version=0.0.0)
tag-remove            Remove a tag if found (tag-remove version=0.0.0)
tag-update            Update an existing tag to current commit (tag-update version=0.0.0)
test                  Runs lint and ALL tests
test-ci               Runs all tests via CI (exports coverage)
test-ci-no-race       Runs all tests via CI (no race) (exports coverage)
test-ci-short         Runs unit tests via CI (exports coverage)
test-no-lint          Runs just tests
test-short            Runs vet, lint and tests (excludes integration tests)
test-unit             Runs tests and outputs coverage
uninstall             Uninstall the application (and remove files)
update-linter         Update the golangci-lint package (macOS only)
vet                   Run the Go vet application

Examples & Tests

All unit tests and examples run via GitHub Actions and uses Go version 1.19.x. View the configuration file.

Run all tests (including integration tests)

make test

Run tests (excluding integration tests)

make test-short

Benchmarks

Run the Go benchmarks:

make bench

Code Standards

Read more about this Go project's code standards.


Usage

View the examples


Maintainers

MrZ
MrZ

Contributing

View the contributing guidelines and please follow the code of conduct.

How can I help?

All kinds of contributions are welcome 🙌! The most basic way to show your support is to star 🌟 the project, or to raise issues 💬. You can also support this project by becoming a sponsor on GitHub 👏 or by making a bitcoin donation to ensure this journey continues indefinitely! 🚀

Stars

Credits

Unwriter & Interplanaria for their original contribution: Minercraft which was the inspiration for this library.

nChain & team for developing the brfc-merchant-api specifications.


License

License

Documentation

Overview

Package minercraft is an unofficial Go version of Unwriter's Minercraft

If you have any suggestions or comments, please feel free to open an issue on this GitHub repository!

By TonicPow Inc (https://tonicpow.com)

Index

Examples

Constants

View Source 
const (
	// MinerTaal is the name of the known miner for "Taal"
	MinerTaal = "Taal"

	// MinerMempool is the name of the known miner for "Mempool"
	MinerMempool = "Mempool"

	// MinerMatterpool is the name of the known miner for "Matterpool"
	MinerMatterpool = "Matterpool"

	// MinerGorillaPool is the name of the known miner for "GorillaPool"
	MinerGorillaPool = "GorillaPool"
)
View Source 
const (

	// FeeTypeData is the key corresponding to the data rate
	FeeTypeData = "data"

	// FeeTypeStandard is the key corresponding to the standard rate
	FeeTypeStandard = "standard"

	// FeeCategoryMining is the category corresponding to the mining rate
	FeeCategoryMining = "mining"

	// FeeCategoryRelay is the category corresponding to the relay rate
	FeeCategoryRelay = "relay"
)
View Source 
const KnownMiners = `` /* 778-byte string literal not displayed */

KnownMiners is a pre-filled list of known miners Any pre-filled tokens are for free use only update your custom token with client.MinerUpdateToken("name", "token")

View Source 
const (
	// MerkleFormatTSC can be set when calling SubmitTransaction to request a MerkleProof in TSC format.
	MerkleFormatTSC = "TSC"
)
View Source 
const QueryTransactionFailure = "failure"

QueryTransactionFailure is on failure

View Source 
const QueryTransactionInMempoolFailure = "Transaction in mempool but not yet in block"

QueryTransactionInMempoolFailure in mempool but not in a block yet

View Source 
const QueryTransactionSuccess = "success"

QueryTransactionSuccess is on success

Variables

This section is empty.

Functions

func IsRetryable added in v0.9.0 

func IsRetryable(err error) bool

IsRetryable can be passed an error to check if it is retryable

Types

type Callback added in v0.2.11 

type Callback struct {
	APIVersion      string `json:"apiVersion"`
	BlockHash       string `json:"blockHash"`
	BlockHeight     uint64 `json:"blockHeight"`
	CallbackPayload string `json:"callbackPayload"`
	CallbackReason  string `json:"callbackReason"`
	CallbackTxID    string `json:"callbackTxId"`
	MinerID         string `json:"minerId"`
	Timestamp       string `json:"timestamp"`
}

Callback is the body contents posted to the provided callback url from Merchant API

type Client 

type Client struct {
	Options *ClientOptions // Client options config
	// contains filtered or unexported fields
}

Client is the parent struct that contains the miner clients and list of miners to use

func (*Client) AddMiner 

func (c *Client) AddMiner(miner Miner) error

AddMiner will add a new miner to the list of miners

Example

ExampleClient_AddMiner example using AddMiner() 

client, err := NewClient(nil, nil, nil)
if err != nil {
	fmt.Printf("error occurred: %s", err.Error())
	return
}

// Add a miner
if err = client.AddMiner(Miner{Name: testMinerName, URL: testMinerURL}); err != nil {
	fmt.Printf("error occurred: %s", err.Error())
	return
}

// Get miner by name
fmt.Printf("created new miner named: %s", client.MinerByName(testMinerName).Name)

Output:

created new miner named: TestMiner

func (*Client) BestQuote 

func (c *Client) BestQuote(ctx context.Context, feeCategory, feeType string) (*FeeQuoteResponse, error)

BestQuote will check all known miners and compare rates, returning the best rate/quote

Note: this might return different results each time if miners have the same rates as it's a race condition on which results come back first

Example

ExampleClient_BestQuote example using BestQuote() 

// Create a client (using a test client vs NewClient())
client := newTestClient(&mockHTTPValidBestQuote{})

// Create a req
_, err := client.BestQuote(context.Background(), FeeCategoryMining, FeeTypeData)
if err != nil {
	fmt.Printf("error occurred: %s", err.Error())
	return
}

// Note: cannot show response since the miner might be different each time
fmt.Printf("got best quote!")

Output:

got best quote!

func (*Client) FastestQuote added in v0.0.4 

func (c *Client) FastestQuote(ctx context.Context, timeout time.Duration) (*FeeQuoteResponse, error)

FastestQuote will check all known miners and return the fastest quote response

Note: this might return different results each time if miners have the same rates as it's a race condition on which results come back first

Example

ExampleClient_FastestQuote example using FastestQuote() 

// Create a client (using a test client vs NewClient())
client := newTestClient(&mockHTTPValidFastestQuote{})

// Create a req
_, err := client.FastestQuote(context.Background(), defaultFastQuoteTimeout)
if err != nil {
	fmt.Printf("error occurred: %s", err.Error())
	return
}

// Note: cannot show response since the miner might be different each time
fmt.Printf("got fastest quote!")

Output:

got fastest quote!

func (*Client) FeeQuote 

func (c *Client) FeeQuote(ctx context.Context, miner *Miner) (*FeeQuoteResponse, error)

FeeQuote will fire a Merchant API request to retrieve the fees from a given miner

This endpoint is used to get the different fees quoted by a miner. It returns a JSONEnvelope with a payload that contains the fees charged by a specific BSV miner. The purpose of the envelope is to ensure strict consistency in the message content for the purpose of signing responses.

Specs: https://github.com/bitcoin-sv-specs/brfc-merchantapi#2-get-fee-quote

Example

ExampleClient_FeeQuote example using FeeQuote() 

// Create a client (using a test client vs NewClient())
client := newTestClient(&mockHTTPValidFeeQuote{})

// Create a req
response, err := client.FeeQuote(context.Background(), client.MinerByName(MinerTaal))
if err != nil {
	fmt.Printf("error occurred: %s", err.Error())
	return
}

fmt.Printf("got quote from: %s", response.Miner.Name)

Output:

got quote from: Taal

func (*Client) MinerByID 

func (c *Client) MinerByID(minerID string) *Miner

MinerByID will return a miner given a miner id

Example

ExampleClient_MinerByID example using MinerByID() 

client, err := NewClient(nil, nil, nil)
if err != nil {
	fmt.Printf("error occurred: %s", err.Error())
	return
}

// Add a miner
if err = client.AddMiner(Miner{Name: testMinerName, MinerID: testMinerID, URL: testMinerURL}); err != nil {
	fmt.Printf("error occurred: %s", err.Error())
	return
}

// Get miner by id
fmt.Printf("created new miner named: %s", client.MinerByID(testMinerID).Name)

Output:

created new miner named: TestMiner

func (*Client) MinerByName 

func (c *Client) MinerByName(name string) *Miner

MinerByName will return a miner given a name

Example

ExampleClient_MinerByName example using MinerByName() 

client, err := NewClient(nil, nil, nil)
if err != nil {
	fmt.Printf("error occurred: %s", err.Error())
	return
}

// Add a miner
if err = client.AddMiner(Miner{Name: testMinerName, URL: testMinerURL}); err != nil {
	fmt.Printf("error occurred: %s", err.Error())
	return
}

// Get miner by name
fmt.Printf("created new miner named: %s", client.MinerByName(testMinerName).Name)

Output:

created new miner named: TestMiner

func (*Client) MinerUpdateToken 

func (c *Client) MinerUpdateToken(name, token string)

MinerUpdateToken will find a miner by name and update the token

Example

ExampleClient_MinerUpdateToken example using MinerUpdateToken() 

client, err := NewClient(nil, nil, nil)
if err != nil {
	fmt.Printf("error occurred: %s", err.Error())
	return
}

// Update existing miner token
client.MinerUpdateToken(MinerTaal, "9999")

// Get miner by id
fmt.Printf("miner token found: %s", client.MinerByName(MinerTaal).Token)

Output:

miner token found: 9999

func (*Client) Miners 

func (c *Client) Miners() []*Miner

Miners will return the list of miners

func (*Client) PolicyQuote added in v0.4.0 

func (c *Client) PolicyQuote(ctx context.Context, miner *Miner) (*PolicyQuoteResponse, error)

PolicyQuote will fire a Merchant API request to retrieve the policy from a given miner

This endpoint is used to get the different policies quoted by a miner. It returns a JSONEnvelope with a payload that contains the policies used by a specific BSV miner. The purpose of the envelope is to ensure strict consistency in the message content for the purpose of signing responses. This is a superset of the fee quote service, as it also includes information on DSNT IP addresses and miner policies.

Specs: https://github.com/bitcoin-sv-specs/brfc-merchantapi#1-get-policy-quote

Example

ExampleClient_FeeQuote example using PolicyQuote() 

// Create a client (using a test client vs NewClient())
client := newTestClient(&mockHTTPValidPolicyQuote{})

// Create a req
response, err := client.PolicyQuote(context.Background(), client.MinerByName(MinerTaal))
if err != nil {
	fmt.Printf("error occurred: %s", err.Error())
	return
}

fmt.Printf("got quote from: %s", response.Miner.Name)

Output:

got quote from: Taal

func (*Client) QueryTransaction 

func (c *Client) QueryTransaction(ctx context.Context, miner *Miner, txID string, opts ...QueryTransactionOptFunc) (*QueryTransactionResponse, error)

QueryTransaction will fire a Merchant API request to check the status of a transaction

This endpoint is used to check the current status of a previously submitted transaction. It returns a JSONEnvelope with a payload that contains the transaction status. The purpose of the envelope is to ensure strict consistency in the message content for the purpose of signing responses.

You can provide optional arguments using the WithQuery... option functions, an example is shown: 

QueryTransaction(ctx, miner, abc123, WithQueryMerkleProof(), WithQueryTSCMerkleFormat())

This is backwards compatible with the previous non-optional version of this function and be called with 0 options: 

QueryTransaction(ctx, miner, abc123)

In this case the defaults are used which is to not request a proof. Specs: https://github.com/bitcoin-sv-specs/brfc-merchantapi#4-query-transaction-status

Example

ExampleClient_QueryTransaction example using QueryTransaction() 

// Create a client (using a test client vs NewClient())
client := newTestClient(&mockHTTPValidQuery{})

// Create a req
response, err := client.QueryTransaction(context.Background(), client.MinerByName(MinerTaal), testTx)
if err != nil {
	fmt.Printf("error occurred: %s", err.Error())
	return
}

fmt.Printf("got tx status %s from: %s", response.Query.ReturnResult, response.Miner.Name)

Output:

got tx status success from: Taal

func (*Client) RemoveMiner added in v0.2.0 

func (c *Client) RemoveMiner(miner *Miner) bool

RemoveMiner will remove a miner from the list

Example

ExampleClient_MinerUpdateToken example using RemoveMiner() 

client, err := NewClient(nil, nil, nil)
if err != nil {
	fmt.Printf("error occurred: %s", err.Error())
	return
}

// Update existing miner token
client.RemoveMiner(client.MinerByName(MinerTaal))

// Show response
fmt.Printf("total miners: %d", len(client.Miners()))

Output:

total miners: 3

func (*Client) SubmitTransaction 

func (c *Client) SubmitTransaction(ctx context.Context, miner *Miner, tx *Transaction) (*SubmitTransactionResponse, error)

SubmitTransaction will fire a Merchant API request to submit a given transaction

This endpoint is used to send a raw transaction to a miner for inclusion in the next block that the miner creates. It returns a JSONEnvelope with a payload that contains the response to the transaction submission. The purpose of the envelope is to ensure strict consistency in the message content for the purpose of signing responses.

Specs: https://github.com/bitcoin-sv-specs/brfc-merchantapi#3-submit-transaction

Example

ExampleClient_SubmitTransaction example using SubmitTransaction() 

// Create a client (using a test client vs NewClient())
client := newTestClient(&mockHTTPValidSubmission{})

tx := &Transaction{RawTx: submitTestExampleTx}

// Create a req
response, err := client.SubmitTransaction(context.Background(), client.MinerByName(MinerTaal), tx)
if err != nil {
	fmt.Printf("error occurred: %s", err.Error())
	return
}

fmt.Printf("submitted tx to: %s", response.Miner.Name)

Output:

submitted tx to: Taal

func (*Client) SubmitTransactions 

func (c *Client) SubmitTransactions(ctx context.Context, miner *Miner, txs []Transaction) (*SubmitTransactionsResponse, error)

SubmitTransactions is used for submitting batched transactions

Reference: https://github.com/bitcoin-sv-specs/brfc-merchantapi#5-submit-multiple-transactions

func (*Client) UserAgent added in v0.6.0 

func (c *Client) UserAgent() string

UserAgent will return the user agent

type ClientInterface added in v0.6.0 

type ClientInterface interface {
	MinerService
	QuoteService
	TransactionService
	UserAgent() string
}

ClientInterface is the MinerCraft client interface

func NewClient 

func NewClient(clientOptions *ClientOptions, customHTTPClient HTTPInterface,
	customMiners []*Miner) (client ClientInterface, err error)

NewClient creates a new client for requests

clientOptions: inject custom client options on load customHTTPClient: use your own custom HTTP client customMiners: use your own custom list of miners

Example

ExampleNewClient example using NewClient() 

client, err := NewClient(nil, nil, nil)
if err != nil {
	fmt.Printf("error occurred: %s", err.Error())
	return
}

fmt.Printf("created new client with %d default miners", len(client.Miners()))

Output:

created new client with 4 default miners

type ClientOptions 

type ClientOptions struct {
	BackOffExponentFactor          float64       `json:"back_off_exponent_factor"`
	BackOffInitialTimeout          time.Duration `json:"back_off_initial_timeout"`
	BackOffMaximumJitterInterval   time.Duration `json:"back_off_maximum_jitter_interval"`
	BackOffMaxTimeout              time.Duration `json:"back_off_max_timeout"`
	DialerKeepAlive                time.Duration `json:"dialer_keep_alive"`
	DialerTimeout                  time.Duration `json:"dialer_timeout"`
	RequestRetryCount              int           `json:"request_retry_count"`
	RequestTimeout                 time.Duration `json:"request_timeout"`
	TransportExpectContinueTimeout time.Duration `json:"transport_expect_continue_timeout"`
	TransportIdleTimeout           time.Duration `json:"transport_idle_timeout"`
	TransportMaxIdleConnections    int           `json:"transport_max_idle_connections"`
	TransportTLSHandshakeTimeout   time.Duration `json:"transport_tls_handshake_timeout"`
	UserAgent                      string        `json:"user_agent"`
}

ClientOptions holds all the configuration for connection, dialer and transport

func DefaultClientOptions 

func DefaultClientOptions() (clientOptions *ClientOptions)

DefaultClientOptions will return a ClientOptions struct with the default settings. Useful for starting with the default and then modifying as needed

Example

ExampleDefaultClientOptions example using DefaultClientOptions() 

options := DefaultClientOptions()
options.UserAgent = "Custom UserAgent v1.0"
client, err := NewClient(options, nil, nil)
if err != nil {
	fmt.Printf("error occurred: %s", err.Error())
	return
}

fmt.Printf("created new client with user agent: %s", client.UserAgent())

Output:

created new client with user agent: Custom UserAgent v1.0

type ConflictedWith added in v0.2.6 

type ConflictedWith struct {
	Hex  string `json:"hex"`
	Size int    `json:"size"`
	TxID string `json:"txid"`
}

ConflictedWith contains the information about the transactions that conflict with the transaction submitted to mAPI. A conflict could arise if multiple transactions attempt to spend the same UTXO (double spend).

type ErrRetryable added in v0.9.0 

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

ErrRetryable indicates a retryable error.

To check an error is a retryable error do: 

errors.Is(err, minercraft.Retryable)

func (ErrRetryable) As added in v0.9.0 

func (e ErrRetryable) As(target interface{}) bool

As will return true if the error can be cast to the target.

func (ErrRetryable) Error added in v0.9.0 

func (e ErrRetryable) Error() string

func (ErrRetryable) Is added in v0.9.0 

func (e ErrRetryable) Is(err error) bool

Is allows the underlying error to be checked that it is a certain error type.

func (ErrRetryable) IsRetryable added in v0.9.0 

func (e ErrRetryable) IsRetryable()

IsRetryable returns true denoting this is retryable.

type ErrorResponse added in v0.8.1 

type ErrorResponse struct {
	Type    string `json:"type"`
	Title   string `json:"title"`
	Status  int    `json:"status"`
	Detail  string `json:"detail"`
	TraceID string `json:"traceId"`
	// Errors will return a list of formatting errors in the case of a bad request
	// being sent to mAPI.
	Errors map[string][]string `json:"errors"`
}

ErrorResponse is the response returned from mAPI on error.

func (ErrorResponse) Error added in v0.9.0 

func (e ErrorResponse) Error() string

Error defines the ErrorResponse as an error, an error can be converted to it using the below: 

 var errResp ErrorResponse
 if errors.As(testErr, &errResp) {
	 // handle error
	 fmt.Println(errResp.Title)
 }

type FeePayload 

type FeePayload struct {
	Fees []*bt.Fee `json:"fees"`
	// contains filtered or unexported fields
}

FeePayload is the unmarshalled version of the payload envelope

func (*FeePayload) CalculateFee 

func (f *FeePayload) CalculateFee(feeCategory, feeType string, txBytes uint64) (uint64, error)

CalculateFee will return the fee for the given txBytes Type: "FeeTypeData" or "FeeTypeStandard" Category: "FeeCategoryMining" or "FeeCategoryRelay"

If no fee is found or fee is 0, returns 1 & error

Spec: https://github.com/bitcoin-sv-specs/brfc-misc/tree/master/feespec#deterministic-transaction-fee-calculation-dtfc

Example

ExampleFeePayload_CalculateFee example using CalculateFee() 

// Create a client (using a test client vs NewClient())
client := newTestClient(&mockHTTPValidBestQuote{})

// Create a req
response, err := client.BestQuote(context.Background(), FeeCategoryMining, FeeTypeData)
if err != nil {
	fmt.Printf("error occurred: %s", err.Error())
	return
}

// Calculate fee for tx
var fee uint64
fee, err = response.Quote.CalculateFee(FeeCategoryMining, FeeTypeData, 1000)
if err != nil {
	fmt.Printf("error occurred: %s", err.Error())
	return
}

// Note: cannot show response since the miner might be different each time
fmt.Printf("got best quote and fee for 1000 byte tx is: %d", fee)

Output:

got best quote and fee for 1000 byte tx is: 420

func (*FeePayload) GetFee added in v0.2.9 

func (f *FeePayload) GetFee(feeType string) *bt.Fee

GetFee will return the fee associated to the type (standard, data)

Example

ExampleFeePayload_GetFee example using GetFee() 

// Create a client (using a test client vs NewClient())
client := newTestClient(&mockHTTPValidBestQuote{})

// Create a req
response, err := client.BestQuote(context.Background(), FeeCategoryMining, FeeTypeData)
if err != nil {
	fmt.Printf("error occurred: %s", err.Error())
	return
}

// Get the fee
fee := response.Quote.GetFee(FeeTypeStandard)

fmt.Printf(
	"got best quote and fee for %d byte tx is %d sats",
	fee.MiningFee.Bytes, fee.MiningFee.Satoshis,
)

Output:

got best quote and fee for 1000 byte tx is 500 sats

type FeeQuoteResponse 

type FeeQuoteResponse struct {
	JSONEnvelope
	Quote *FeePayload `json:"quote"` // Custom field for unmarshalled payload data
}

FeeQuoteResponse is the raw response from the Merchant API request

Specs: https://github.com/bitcoin-sv-specs/brfc-merchantapi#2-get-fee-quote

type HTTPInterface added in v0.5.0 

type HTTPInterface interface {
	Do(req *http.Request) (*http.Response, error)
}

HTTPInterface is used for the http client (mocking heimdall)

type JSONEnvelope 

type JSONEnvelope struct {
	Miner     *Miner `json:"miner"`     // Custom field for our internal Miner configuration
	Validated bool   `json:"validated"` // Custom field if the signature has been validated
	envelope.JSONEnvelope
}

JSONEnvelope is a standard response from the Merchant API requests

This type wraps the go-bk JSONEnvelope which performs validation of the signatures (if we have any) and will return true / false if valid.

We wrap this, so we can append some additional miner info and a validated helper property to indicate if the envelope is or isn't valid. Consumers can also independently validate the envelope.

type Miner 

type Miner struct {
	MinerID string `json:"miner_id,omitempty"`
	Name    string `json:"name,omitempty"`
	Token   string `json:"token,omitempty"`
	URL     string `json:"url"`
}

Miner is a configuration per miner, including connection url, auth token, etc

func DefaultMiners added in v0.6.2 

func DefaultMiners() (miners []*Miner, err error)

DefaultMiners will parse the config JSON and return a list of miners

Example

ExampleDefaultMiners example using DefaultMiners() 

miners, _ := DefaultMiners()
fmt.Printf("total miners: %d", len(miners))

Output:

total miners: 4

func MinerByID added in v0.7.3 

func MinerByID(miners []*Miner, minerID string) *Miner

MinerByID will return a miner from a given set of miners

func MinerByName added in v0.7.3 

func MinerByName(miners []*Miner, minerName string) *Miner

MinerByName will return a miner from a given set of miners

type MinerService added in v0.6.1 

type MinerService interface {
	AddMiner(miner Miner) error
	MinerByID(minerID string) *Miner
	MinerByName(name string) *Miner
	Miners() []*Miner
	MinerUpdateToken(name, token string)
	RemoveMiner(miner *Miner) bool
}

MinerService is the MinerCraft miner related methods

type Policy added in v0.4.0 

type Policy struct {
	AcceptNonStdOutputs             bool         `json:"acceptnonstdoutputs"`
	DataCarrier                     bool         `json:"datacarrier"`
	DataCarrierSize                 uint32       `json:"datacarriersize"`
	LimitAncestorCount              uint32       `json:"limitancestorcount"`
	LimitCpfpGroupMembersCount      uint32       `json:"limitcpfpgroupmemberscount"`
	MaxNonStdTxValidationDuration   uint32       `json:"maxnonstdtxvalidationduration"`
	MaxScriptNumLengthPolicy        uint32       `json:"maxscriptnumlengthpolicy"`
	MaxScriptSizePolicy             uint32       `json:"maxscriptsizepolicy"`
	MaxStackMemoryUsagePolicy       uint64       `json:"maxstackmemoryusagepolicy"`
	MaxStdTxValidationDuration      uint32       `json:"maxstdtxvalidationduration"`
	MaxTxSizePolicy                 uint32       `json:"maxtxsizepolicy"`
	SkipScriptFlags                 []ScriptFlag `json:"skipscriptflags"`
	MaxConsolidationFactor          uint32       `json:"minconsolidationfactor"`
	MaxConsolidationInputScriptSize uint32       `json:"maxconsolidationinputscriptsize"`
	MinConfConsolidationInput       uint32       `json:"minconfconsolidationinput"`
	AcceptNonStdConsolidationInput  bool         `json:"acceptnonstdconsolidationinput"`
}

Policy is the struct of a policy (from policy quote response)

type PolicyCallback added in v0.4.0 

type PolicyCallback struct {
	IPAddress string `json:"ipAddress"`
}

PolicyCallback is the callback address

type PolicyPayload added in v0.4.0 

type PolicyPayload struct {
	FeePayload                   // Inherit the same structure as the fee payload
	Callbacks  []*PolicyCallback `json:"callbacks"` // IP addresses of double-spend notification servers such as mAPI reference implementation
	Policies   *Policy           `json:"policies"`  // values of miner policies as configured by the mAPI reference implementation administrator
}

PolicyPayload is the unmarshalled version of the payload envelope

type PolicyQuoteResponse added in v0.4.0 

type PolicyQuoteResponse struct {
	JSONEnvelope
	Quote *PolicyPayload `json:"quote"` // Custom field for unmarshalled payload data
}

PolicyQuoteResponse is the raw response from the Merchant API request

Specs: https://github.com/bitcoin-sv-specs/brfc-merchantapi#1-get-policy-quote

type QueryPayload 

type QueryPayload struct {
	APIVersion            string          `json:"apiVersion"`
	Timestamp             string          `json:"timestamp"`
	TxID                  string          `json:"txid"`
	ReturnResult          string          `json:"returnResult"`
	ResultDescription     string          `json:"resultDescription"`
	BlockHash             string          `json:"blockHash"`
	BlockHeight           int64           `json:"blockHeight"`
	MinerID               string          `json:"minerId"`
	Confirmations         int64           `json:"confirmations"`
	TxSecondMempoolExpiry int64           `json:"txSecondMempoolExpiry"`
	MerkleProof           *bc.MerkleProof `json:"merkleProof"`
}

QueryPayload is the unmarshalled version of the payload envelope

type QueryTransactionOptFunc added in v0.9.0 

type QueryTransactionOptFunc func(o *queryTransactionOpts)

QueryTransactionOptFunc defines an optional argument that can be passed to the QueryTransaction method.

func WithQueryMerkleFormat added in v0.9.0 

func WithQueryMerkleFormat(s string) QueryTransactionOptFunc

WithQueryMerkleFormat can be used to overwrite the default format of TSC with another value.

func WithQueryMerkleProof added in v0.9.0 

func WithQueryMerkleProof() QueryTransactionOptFunc

WithQueryMerkleProof will request that a merkle proof is returned in the query response.

func WithQueryTSCMerkleFormat added in v0.9.0 

func WithQueryTSCMerkleFormat() QueryTransactionOptFunc

WithQueryTSCMerkleFormat is the default option and doesn't need to be passed however can be added for code clarity.

func WithoutQueryMerkleProof added in v0.9.0 

func WithoutQueryMerkleProof() QueryTransactionOptFunc

WithoutQueryMerkleProof is the default option and doesn't need to be passed however can be added for code clarity.

type QueryTransactionResponse 

type QueryTransactionResponse struct {
	JSONEnvelope
	Query *QueryPayload `json:"query"` // Custom field for unmarshalled payload data
}

QueryTransactionResponse is the raw response from the Merchant API request

Specs: https://github.com/bitcoin-sv-specs/brfc-merchantapi#4-query-transaction-status

type QuoteService added in v0.6.1 

type QuoteService interface {
	BestQuote(ctx context.Context, feeCategory, feeType string) (*FeeQuoteResponse, error)
	FastestQuote(ctx context.Context, timeout time.Duration) (*FeeQuoteResponse, error)
	FeeQuote(ctx context.Context, miner *Miner) (*FeeQuoteResponse, error)
	PolicyQuote(ctx context.Context, miner *Miner) (*PolicyQuoteResponse, error)
}

QuoteService is the MinerCraft quote related requests

type RawSubmitTransactionsResponse added in v0.3.5 

type RawSubmitTransactionsResponse struct {
	Encoding  string `json:"encoding"`
	MimeType  string `json:"mimetype"`
	Payload   string `json:"payload"`
	PublicKey string `json:"publicKey"`
	Signature string `json:"signature"`
}

RawSubmitTransactionsResponse is the response returned from mapi where payload is a string.

type RequestResponse 

type RequestResponse struct {
	BodyContents []byte `json:"body_contents"` // Raw body response
	Error        error  `json:"error"`         // If an error occurs
	Method       string `json:"method"`        // Method is the HTTP method used
	PostData     string `json:"post_data"`     // PostData is the post data submitted if POST/PUT request
	StatusCode   int    `json:"status_code"`   // StatusCode is the last code from the request
	URL          string `json:"url"`           // URL is used for the request
}

RequestResponse is the response from a request

type Retryable added in v0.9.0 

type Retryable interface {
	// IsRetryable if a method has this method then it's a retryable error.
	IsRetryable()
}

Retryable can be implemented to identify a struct as retryable, in this case an error can be deemed retryable.

type ScriptFlag added in v0.4.0 

type ScriptFlag string

ScriptFlag is a flag used in the policy quote 

const (
	FlagCleanStack               ScriptFlag = "CLEANSTACK"
	FlagDerSig                   ScriptFlag = "DERSIG"
	FlagDiscourageUpgradableNops ScriptFlag = "DISCOURAGE_UPGRADABLE_NOPS"
	FlagMinimalData              ScriptFlag = "MINIMALDATA"
	FlagNullDummy                ScriptFlag = "NULLDUMMY"
)

All known script flags

type SubmissionPayload 

type SubmissionPayload struct {
	APIVersion                string            `json:"apiVersion"`
	ConflictedWith            []*ConflictedWith `json:"conflictedWith"`
	CurrentHighestBlockHash   string            `json:"currentHighestBlockHash"`
	CurrentHighestBlockHeight int64             `json:"currentHighestBlockHeight"`
	MinerID                   string            `json:"minerId"`
	ResultDescription         string            `json:"resultDescription"`
	ReturnResult              string            `json:"returnResult"`
	Timestamp                 string            `json:"timestamp"`
	TxID                      string            `json:"txid"`
	TxSecondMempoolExpiry     int64             `json:"txSecondMempoolExpiry"`
	// FailureRetryable if true indicates the tx can be resubmitted to mAPI.
	FailureRetryable bool `json:"failureRetryable"`
}

SubmissionPayload is the unmarshalled version of the payload envelope

type SubmitTransactionResponse 

type SubmitTransactionResponse struct {
	JSONEnvelope
	Results *SubmissionPayload `json:"results"` // Custom field for unmarshalled payload data
}

SubmitTransactionResponse is the raw response from the Merchant API request

Specs: https://github.com/bitcoin-sv-specs/brfc-merchantapi#3-submit-transaction

type SubmitTransactionsResponse 

type SubmitTransactionsResponse struct {
	Encoding  string     `json:"encoding"`
	MimeType  string     `json:"mimetype"`
	Payload   TxsPayload `json:"payload"`
	PublicKey string     `json:"publicKey"`
	Signature string     `json:"signature"`
}

SubmitTransactionsResponse is the formatted response which converts payload string to payloads.

type Transaction 

type Transaction struct {
	CallBackEncryption string `json:"callBackEncryption,omitempty"`
	CallBackToken      string `json:"callBackToken,omitempty"`
	CallBackURL        string `json:"callBackUrl,omitempty"`
	DsCheck            bool   `json:"dsCheck,omitempty"`
	MerkleFormat       string `json:"merkleFormat,omitempty"`
	MerkleProof        bool   `json:"merkleProof,omitempty"`
	RawTx              string `json:"rawtx"`
}

Transaction is the body contents in the "submit transaction" request

type TransactionService added in v0.6.1 

type TransactionService interface {
	QueryTransaction(ctx context.Context, miner *Miner, txID string, opts ...QueryTransactionOptFunc) (*QueryTransactionResponse, error)
	SubmitTransaction(ctx context.Context, miner *Miner, tx *Transaction) (*SubmitTransactionResponse, error)
	SubmitTransactions(ctx context.Context, miner *Miner, txs []Transaction) (*SubmitTransactionsResponse, error)
}

TransactionService is the MinerCraft transaction related methods

type Tx added in v0.3.5 

type Tx struct {
	ConflictedWith    []ConflictedWith `json:"conflictedWith,omitempty"`
	ResultDescription string           `json:"resultDescription"`
	ReturnResult      string           `json:"returnResult"`
	TxID              string           `json:"txid"`
	// FailureRetryable if true indicates the tx can be resubmitted to mAPI.
	FailureRetryable bool `json:"failureRetryable"`
}

Tx is the transaction format in the mapi txs response.

type TxsPayload added in v0.3.5 

type TxsPayload struct {
	APIVersion                string    `json:"apiVersion"`
	CurrentHighestBlockHash   string    `json:"currentHighestBlockHash"`
	CurrentHighestBlockHeight int       `json:"currentHighestBlockHeight"`
	FailureCount              int       `json:"failureCount"`
	MinerID                   string    `json:"minerId"`
	Timestamp                 time.Time `json:"timestamp"`
	Txs                       []Tx      `json:"txs"`
	TxSecondMempoolExpiry     int       `json:"txSecondMempoolExpiry"`
}

TxsPayload is the structure of the json payload string in the MapiResponse.

Source Files

View all Source files

Directories

Path Synopsis
examples
add_miner
best_quote
calculate_fee
custom_miners
fastest_quote
fee_quote
policy_quote
query_transaction
remove_miner
submit_transaction

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.