chainstate

package
v0.19.0 Latest Latest
Warning

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

 Go to latest Published: Mar 5, 2024 License: MIT Imports: 20 Imported by: 0

Documentation

Overview

Package chainstate is the on-chain data service abstraction layer

Index

Constants

View Source 
const (
	// FilterBloom is for bloom filters
	FilterBloom = "bloom"

	// FilterRegex is for regex filters
	FilterRegex = "regex"
)
View Source 
const (
	ProviderAll             = "all"             // All providers (used for errors etc)
	ProviderMinercraft      = "minercraft"      // Query & broadcast provider for mAPI (using given miners)
	ProviderBroadcastClient = "broadcastclient" // Query & broadcast provider for configured miners
	ProviderNone            = "none"            // No providers (used to indicate no providers)
)

List of providers

Variables

View Source 
var ErrInvalidRequirements = errors.New("requirements are invalid or missing")

ErrInvalidRequirements is when an invalid requirement was given

View Source 
var ErrInvalidTransactionHex = errors.New("invalid transaction hex")

ErrInvalidTransactionHex is when the transaction hex is missing or invalid

View Source 
var ErrInvalidTransactionID = errors.New("invalid transaction id")

ErrInvalidTransactionID is when the transaction id is missing or invalid

View Source 
var ErrMissingBroadcastMiners = errors.New("missing: broadcasting miners")

ErrMissingBroadcastMiners is when broadcasting miners are missing

View Source 
var ErrMissingQueryMiners = errors.New("missing: query miners")

ErrMissingQueryMiners is when query miners are missing

View Source 
var ErrTransactionIDMismatch = errors.New("result tx id did not match provided tx id")

ErrTransactionIDMismatch is when the returned tx does not match the expected given tx id

View Source 
var ErrTransactionNotFound = errors.New("transaction not found using all chain providers")

ErrTransactionNotFound is when a transaction was not found in any on-chain provider

View Source 
var MockDefaultFee = &utils.FeeUnit{
	Satoshis: 1,
	Bytes:    20,
}

MockDefaultFee is a mock default fee used for assertions

Functions

This section is empty.

Types

type BlockInfo 

type BlockInfo struct {
	Bits              string         `json:"bits"`
	ChainWork         string         `json:"chainwork"`
	CoinbaseTx        CoinbaseTxInfo `json:"coinbaseTx"`
	Confirmations     int64          `json:"confirmations"`
	Difficulty        float64        `json:"difficulty"`
	Hash              string         `json:"hash"`
	Height            int64          `json:"height"`
	MedianTime        int64          `json:"mediantime"`
	MerkleRoot        string         `json:"merkleroot"`
	Miner             string         `json:"Bmgpool"`
	NextBlockHash     string         `json:"nextblockhash"`
	Nonce             int64          `json:"nonce"`
	Pages             Page           `json:"pages"`
	PreviousBlockHash string         `json:"previousblockhash"`
	Size              int64          `json:"size"`
	Time              int64          `json:"time"`
	TotalFees         float64        `json:"totalFees"`
	Tx                []string       `json:"tx"`
	TxCount           int64          `json:"txcount"`
	Version           int64          `json:"version"`
	VersionHex        string         `json:"versionHex"`
}

BlockInfo is the response info about a returned block

type ChainService 

type ChainService interface {
	SupportedBroadcastFormats() HexFormatFlag
	Broadcast(ctx context.Context, id, txHex string, format HexFormatFlag, timeout time.Duration) (string, error)
	QueryTransaction(
		ctx context.Context, id string, requiredIn RequiredIn, timeout time.Duration,
	) (*TransactionInfo, error)
	QueryTransactionFastest(
		ctx context.Context, id string, requiredIn RequiredIn, timeout time.Duration,
	) (*TransactionInfo, error)
}

ChainService is the chain related methods

type Client 

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

Client is the client (configuration)

func (*Client) ActiveProvider 

func (c *Client) ActiveProvider() string

ActiveProvider returns a name of a provider based on config.

func (*Client) Broadcast 

func (c *Client) Broadcast(ctx context.Context, id, txHex string, format HexFormatFlag, timeout time.Duration) (string, error)

Broadcast will attempt to broadcast a transaction using the given providers

func (*Client) BroadcastClient 

func (c *Client) BroadcastClient() broadcast.Client

BroadcastClient will return the BroadcastClient client

func (*Client) Close 

func (c *Client) Close(ctx context.Context)

Close will close the client and any open connections

func (*Client) Debug 

func (c *Client) Debug(on bool)

Debug will set the debug flag

func (*Client) DebugLog 

func (c *Client) DebugLog(text string)

DebugLog will display verbose logs

func (*Client) FeeUnit 

func (c *Client) FeeUnit() *utils.FeeUnit

FeeUnit will return feeUnit

func (*Client) HTTPClient 

func (c *Client) HTTPClient() HTTPInterface

HTTPClient will return the HTTP client

func (*Client) IsDebug 

func (c *Client) IsDebug() bool

IsDebug will return if debugging is enabled

func (*Client) IsNewRelicEnabled 

func (c *Client) IsNewRelicEnabled() bool

IsNewRelicEnabled will return if new relic is enabled

func (*Client) Minercraft 

func (c *Client) Minercraft() minercraft.ClientInterface

Minercraft will return the Minercraft client

func (*Client) Network 

func (c *Client) Network() Network

Network will return the current network

func (*Client) QueryTimeout 

func (c *Client) QueryTimeout() time.Duration

QueryTimeout will return the query timeout

func (*Client) QueryTransaction 

func (c *Client) QueryTransaction(
	ctx context.Context, id string, requiredIn RequiredIn, timeout time.Duration,
) (transaction *TransactionInfo, err error)

QueryTransaction will get the transaction info from all providers returning the "first" valid result

Note: this is slow, but follows a specific order: mAPI -> WhatsOnChain

func (*Client) QueryTransactionFastest 

func (c *Client) QueryTransactionFastest(
	ctx context.Context, id string, requiredIn RequiredIn, timeout time.Duration,
) (*TransactionInfo, error)

QueryTransactionFastest will get the transaction info from ALL provider(s) returning the "fastest" valid result

Note: this is fast but could abuse each provider based on how excessive this method is used

func (*Client) SupportedBroadcastFormats added in v0.16.0 

func (c *Client) SupportedBroadcastFormats() HexFormatFlag

SupportedBroadcastFormats retuns supported formats based on active providers

func (*Client) VerifyMerkleRoots 

func (c *Client) VerifyMerkleRoots(ctx context.Context, merkleRoots []MerkleRootConfirmationRequestItem) error

VerifyMerkleRoots will try to verify merkle roots with all available providers When no error is returned, it means that the Block Headers Service client responded with state: Confirmed or UnableToVerify

type ClientInterface 

type ClientInterface interface {
	ChainService
	ProviderServices
	HeaderService
	Close(ctx context.Context)
	Debug(on bool)
	DebugLog(text string)
	HTTPClient() HTTPInterface
	IsDebug() bool
	IsNewRelicEnabled() bool
	Network() Network
	QueryTimeout() time.Duration
	FeeUnit() *utils.FeeUnit
}

ClientInterface is the chainstate client interface

func NewClient 

func NewClient(ctx context.Context, opts ...ClientOps) (ClientInterface, error)

NewClient creates a new client for all on-chain functionality

If no options are given, it will use the defaultClientOptions() ctx may contain a NewRelic txn (or one will be created)

type ClientOps 

type ClientOps func(c *clientOptions)

ClientOps allow functional options to be supplied that overwrite default client options.

func WithBroadcastClient 

func WithBroadcastClient(client broadcast.Client) ClientOps

WithBroadcastClient will set broadcast client APIs

func WithCallback 

func WithCallback(callbackURL, callbackAuthToken string) ClientOps

WithCallback will set broadcast callback settings

func WithConnectionToBlockHeaderService 

func WithConnectionToBlockHeaderService(url, authToken string) ClientOps

WithConnectionToBlockHeaderService will set Block Headers Service API settings.

func WithDebugging 

func WithDebugging() ClientOps

WithDebugging will enable debugging mode

func WithExcludedProviders 

func WithExcludedProviders(providers []string) ClientOps

WithExcludedProviders will set a list of excluded providers

func WithFeeQuotes 

func WithFeeQuotes(enabled bool) ClientOps

WithFeeQuotes will set minercraftFeeQuotes flag as true

func WithFeeUnit 

func WithFeeUnit(feeUnit *utils.FeeUnit) ClientOps

WithFeeUnit will set the fee unit

func WithHTTPClient 

func WithHTTPClient(client HTTPInterface) ClientOps

WithHTTPClient will set a custom HTTP client

func WithLogger 

func WithLogger(customLogger *zerolog.Logger) ClientOps

WithLogger will set a custom logger

func WithMAPI 

func WithMAPI() ClientOps

WithMAPI will specify mAPI as an API for minercraft client

func WithMetrics 

func WithMetrics(metrics *metrics.Metrics) ClientOps

WithMetrics will set metrics

func WithMinercraft 

func WithMinercraft(client minercraft.ClientInterface) ClientOps

WithMinercraft will set a custom Minercraft client

func WithMinercraftAPIs 

func WithMinercraftAPIs(apis []*minercraft.MinerAPIs) ClientOps

WithMinercraftAPIs will set miners APIs

func WithNetwork 

func WithNetwork(network Network) ClientOps

WithNetwork will set the network to use

func WithNewRelic 

func WithNewRelic() ClientOps

WithNewRelic will enable the NewRelic wrapper

func WithQueryTimeout 

func WithQueryTimeout(timeout time.Duration) ClientOps

WithQueryTimeout will set a different timeout for transaction querying

func WithUserAgent 

func WithUserAgent(agent string) ClientOps

WithUserAgent will set the custom user agent

type CoinbaseTxInfo 

type CoinbaseTxInfo struct {
	BlockHash     string     `json:"blockhash"`
	BlockTime     int64      `json:"blocktime"`
	Confirmations int64      `json:"confirmations"`
	Hash          string     `json:"hash"`
	Hex           string     `json:"hex"`
	LockTime      int64      `json:"locktime"`
	Size          int64      `json:"size"`
	Time          int64      `json:"time"`
	TxID          string     `json:"txid"`
	Version       int64      `json:"version"`
	Vin           []VinInfo  `json:"vin"`
	Vout          []VoutInfo `json:"vout"`
}

CoinbaseTxInfo is the coinbase tx info inside the BlockInfo

type HTTPInterface 

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

HTTPInterface is the HTTP client interface

type HeaderService 

type HeaderService interface {
	VerifyMerkleRoots(ctx context.Context, merkleRoots []MerkleRootConfirmationRequestItem) error
}

HeaderService is header services interface

type HexFormatFlag added in v0.16.0 

type HexFormatFlag byte

HexFormatFlag transaction hex format 

const (
	RawTx HexFormatFlag = 1 << iota // 1
	Ef
)

func (HexFormatFlag) Contains added in v0.16.0 

func (flag HexFormatFlag) Contains(other HexFormatFlag) bool

Contains checks if the flag contains specific bytes

type MerkleRootConfirmation 

type MerkleRootConfirmation struct {
	Hash         string                      `json:"blockHash"`
	BlockHeight  uint64                      `json:"blockHeight"`
	MerkleRoot   string                      `json:"merkleRoot"`
	Confirmation MerkleRootConfirmationState `json:"confirmation"`
}

MerkleRootConfirmation is a confirmation of merkle roots inclusion in the longest chain.

type MerkleRootConfirmationRequestItem 

type MerkleRootConfirmationRequestItem struct {
	MerkleRoot  string `json:"merkleRoot"`
	BlockHeight uint64 `json:"blockHeight"`
}

MerkleRootConfirmationRequestItem is a request type for verification of Merkle Roots inclusion in the longest chain.

type MerkleRootConfirmationState 

type MerkleRootConfirmationState string

MerkleRootConfirmationState represents the state of each Merkle Root verification process and can be one of three values: Confirmed, Invalid and UnableToVerify. 

const (
	// Confirmed state occurs when Merkle Root is found in the longest chain.
	Confirmed MerkleRootConfirmationState = "CONFIRMED"
	// Invalid state occurs when Merkle Root is not found in the longest chain.
	Invalid MerkleRootConfirmationState = "INVALID"
	// UnableToVerify state occurs when Block Header Service is behind in synchronization with the longest chain.
	UnableToVerify MerkleRootConfirmationState = "UNABLE_TO_VERIFY"
)

type MerkleRootsConfirmationsResponse 

type MerkleRootsConfirmationsResponse struct {
	ConfirmationState MerkleRootConfirmationState `json:"confirmationState"`
	Confirmations     []MerkleRootConfirmation    `json:"confirmations"`
}

MerkleRootsConfirmationsResponse is an API response for confirming merkle roots inclusion in the longest chain.

type MinerCraftBase 

type MinerCraftBase struct{}

MinerCraftBase is a mock implementation of the minercraft.MinerCraft interface.

func (*MinerCraftBase) APIType 

func (m *MinerCraftBase) APIType() minercraft.APIType

APIType will return the API type

func (*MinerCraftBase) AddMiner 

func (m *MinerCraftBase) AddMiner(miner minercraft.Miner, apis []minercraft.API) error

AddMiner adds a new miner to the list of miners.

func (*MinerCraftBase) BestQuote 

func (m *MinerCraftBase) BestQuote(context.Context, string, string) (*minercraft.FeeQuoteResponse, error)

BestQuote returns the best quote for the given fee type and amount.

func (*MinerCraftBase) FastestQuote 

func (m *MinerCraftBase) FastestQuote(context.Context, time.Duration) (*minercraft.FeeQuoteResponse, error)

FastestQuote returns the fastest quote for the given fee type and amount.

func (*MinerCraftBase) FeeQuote 

func (m *MinerCraftBase) FeeQuote(context.Context, *minercraft.Miner) (*minercraft.FeeQuoteResponse, error)

FeeQuote returns a fee quote for the given miner.

func (*MinerCraftBase) MinerAPIByMinerID 

func (m *MinerCraftBase) MinerAPIByMinerID(minerID string, apiType minercraft.APIType) (*minercraft.API, error)

MinerAPIByMinerID will return a miner's API given a miner id and API type

func (*MinerCraftBase) MinerAPIsByMinerID 

func (m *MinerCraftBase) MinerAPIsByMinerID(minerID string) *minercraft.MinerAPIs

MinerAPIsByMinerID will return a miner's APIs given a miner id

func (*MinerCraftBase) MinerByID 

func (m *MinerCraftBase) MinerByID(minerID string) *minercraft.Miner

MinerByID returns a miner by its ID.

func (*MinerCraftBase) MinerByName 

func (m *MinerCraftBase) MinerByName(name string) *minercraft.Miner

MinerByName returns a miner by its name.

func (*MinerCraftBase) MinerUpdateToken 

func (m *MinerCraftBase) MinerUpdateToken(name, token string, apiType minercraft.APIType)

MinerUpdateToken updates the token for the given miner.

func (*MinerCraftBase) Miners 

func (m *MinerCraftBase) Miners() []*minercraft.Miner

Miners returns all miners.

func (*MinerCraftBase) PolicyQuote 

func (m *MinerCraftBase) PolicyQuote(context.Context, *minercraft.Miner) (*minercraft.PolicyQuoteResponse, error)

PolicyQuote returns a policy quote for the given miner.

func (*MinerCraftBase) QueryTransaction 

func (m *MinerCraftBase) QueryTransaction(context.Context, *minercraft.Miner, string, ...minercraft.QueryTransactionOptFunc) (*minercraft.QueryTransactionResponse, error)

QueryTransaction returns a transaction for the given miner.

func (*MinerCraftBase) RemoveMiner 

func (m *MinerCraftBase) RemoveMiner(miner *minercraft.Miner) bool

RemoveMiner removes a miner from the list of miners.

func (*MinerCraftBase) SubmitTransaction 

func (m *MinerCraftBase) SubmitTransaction(context.Context, *minercraft.Miner, *minercraft.Transaction) (*minercraft.SubmitTransactionResponse, error)

SubmitTransaction submits a transaction to the given miner.

func (*MinerCraftBase) SubmitTransactions 

func (m *MinerCraftBase) SubmitTransactions(context.Context, *minercraft.Miner, []minercraft.Transaction) (*minercraft.SubmitTransactionsResponse, error)

SubmitTransactions submits transactions to the given miner.

func (*MinerCraftBase) UserAgent 

func (m *MinerCraftBase) UserAgent() string

UserAgent returns the user agent.

type Network 

type Network string

Network is the supported Bitcoin networks 

const (
	MainNet       Network = mainNet // Main public network
	StressTestNet Network = stn     // Stress Test Network (https://bitcoinscaling.io/)
	TestNet       Network = testNet // Test public network
)

Supported networks

func (Network) Alternate 

func (n Network) Alternate() string

Alternate is the alternate string version

func (Network) String 

func (n Network) String() string

String is the string version of network

type Page 

type Page struct {
	Size int64    `json:"size"`
	URI  []string `json:"uri"`
}

Page is used as a subtype for BlockInfo

type ProviderServices 

type ProviderServices interface {
	Minercraft() minercraft.ClientInterface
	BroadcastClient() broadcast.Client
}

ProviderServices is the chainstate providers interface

type RequiredIn 

type RequiredIn string

RequiredIn is the requirements for querying transaction information 

const (
	// RequiredInMempool is the transaction in mempool? (minimum requirement for a valid response)
	RequiredInMempool RequiredIn = requiredInMempool

	// RequiredOnChain is the transaction in on-chain? (minimum requirement for a valid response)
	RequiredOnChain RequiredIn = requiredOnChain
)

type ScriptPubKeyInfo 

type ScriptPubKeyInfo struct {
	Addresses   []string `json:"addresses"`
	Asm         string   `json:"asm"`
	Hex         string   `json:"hex"`
	IsTruncated bool     `json:"isTruncated"`
	OpReturn    string   `json:"-"` // todo: support this (can be an object of key/vals based on the op return data)
	ReqSigs     int64    `json:"reqSigs"`
	Type        string   `json:"type"`
}

ScriptPubKeyInfo is the scriptPubKey info inside the VoutInfo

type ScriptSigInfo 

type ScriptSigInfo struct {
	Asm string `json:"asm"`
	Hex string `json:"hex"`
}

ScriptSigInfo is the scriptSig info inside the VinInfo

type TransactionInfo 

type TransactionInfo struct {
	BlockHash     string             `json:"block_hash,omitempty"`    // mAPI
	BlockHeight   int64              `json:"block_height"`            // mAPI
	Confirmations int64              `json:"confirmations,omitempty"` // mAPI
	ID            string             `json:"id"`                      // Transaction ID (Hex)
	MinerID       string             `json:"miner_id,omitempty"`      // mAPI ONLY - miner_id found
	Provider      string             `json:"provider,omitempty"`      // Provider is our internal source
	MerkleProof   *bc.MerkleProof    `json:"merkle_proof,omitempty"`  // mAPI 1.5 ONLY
	BUMP          *bc.BUMP           `json:"bump,omitempty"`          // Arc
	TxStatus      broadcast.TxStatus `json:"tx_status,omitempty"`     // Arc ONLY
}

TransactionInfo is the universal information about the transaction found from a chain provider

func (*TransactionInfo) Valid 

func (t *TransactionInfo) Valid() bool

Valid validates TransactionInfo by checking if it contains BlockHash and MerkleProof (from mAPI) or BUMP (from Arc)

type TransactionType 

type TransactionType string

TransactionType tx types 

const Metanet TransactionType = "metanet"

Metanet type 

const PlanariaB TransactionType = "planaria-b"

PlanariaB type 

const PlanariaD TransactionType = "planaria-d"

PlanariaD type 

const PubKeyHash TransactionType = "pubkeyhash"

PubKeyHash type 

const RareCandyFrogCartel TransactionType = "rarecandy-frogcartel"

RareCandyFrogCartel type

type TxInfo 

type TxInfo struct {
	BlockHash     string     `json:"blockhash"`
	BlockHeight   int64      `json:"blockheight"`
	BlockTime     int64      `json:"blocktime"`
	Confirmations int64      `json:"confirmations"`
	Hash          string     `json:"hash"`
	Hex           string     `json:"hex"`
	LockTime      int64      `json:"locktime"`
	Size          int64      `json:"size"`
	Time          int64      `json:"time"`
	TxID          string     `json:"txid"`
	Version       int64      `json:"version"`
	Vin           []VinInfo  `json:"vin"`
	Vout          []VoutInfo `json:"vout"`

	Error string `json:"error"`
}

TxInfo is the response info about a returned tx

type VinInfo 

type VinInfo struct {
	Coinbase  string        `json:"coinbase"`
	ScriptSig ScriptSigInfo `json:"scriptSig"`
	Sequence  int64         `json:"sequence"`
	TxID      string        `json:"txid"`
	Vout      int64         `json:"vout"`
}

VinInfo is the vin info inside the CoinbaseTxInfo

type VoutInfo 

type VoutInfo struct {
	N            int64            `json:"n"`
	ScriptPubKey ScriptPubKeyInfo `json:"scriptPubKey"`
	Value        float64          `json:"value"`
}

VoutInfo is the vout info inside the CoinbaseTxInfo

Source Files

View all Source files

Directories

Path Synopsis
Package filters is used for various known TX filters and format detection
 Package filters is used for various known TX filters and format detection

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.