chainstate

package
v0.15.0 Latest Latest
Warning

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

 Go to latest Published: Apr 2, 2024 License: Apache-2.0 Imports: 20 Imported by: 3

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 added in v0.5.13 

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 {
	Broadcast(ctx context.Context, id, txHex string, 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 added in v0.11.0 

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, timeout time.Duration) (string, error)

Broadcast will attempt to broadcast a transaction using the given providers

func (*Client) BroadcastClient added in v0.5.12 

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 added in v0.5.4 

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) VerifyMerkleRoots added in v0.5.17 

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 pulse 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 added in v0.5.12 

func WithBroadcastClient(client broadcast.Client) ClientOps

WithBroadcastClient will set broadcast client APIs

func WithCallback added in v0.14.4 

func WithCallback(callbackURL, callbackAuthToken string) ClientOps

WithCallback will set broadcast callback settings

func WithConnectionToPulse added in v0.5.17 

func WithConnectionToPulse(url, authToken string) ClientOps

WithConnectionToPulse will set pulse API settings.

func WithDebugging 

func WithDebugging() ClientOps

WithDebugging will enable debugging mode

func WithExcludedProviders added in v0.2.21 

func WithExcludedProviders(providers []string) ClientOps

WithExcludedProviders will set a list of excluded providers

func WithFeeQuotes added in v0.13.0 

func WithFeeQuotes(enabled bool) ClientOps

WithFeeQuotes will set minercraftFeeQuotes flag as true

func WithFeeUnit added in v0.13.0 

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 added in v0.5.8 

func WithMAPI() ClientOps

WithMAPI will specify mAPI as an API for minercraft client

func WithMetrics added in v0.14.4 

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 added in v0.5.8 

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 added in v0.2.14 

func WithUserAgent(agent string) ClientOps

WithUserAgent will set the custom user agent

type CoinbaseTxInfo added in v0.5.13 

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 added in v0.5.17 

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

HeaderService is header services interface

type MerkleRootConfirmation added in v0.5.17 

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 added in v0.6.0 

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 added in v0.6.0 

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 Pulse is behind in synchronization with the longest chain.
	UnableToVerify MerkleRootConfirmationState = "UNABLE_TO_VERIFY"
)

type MerkleRootsConfirmationsResponse added in v0.5.17 

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 added in v0.5.5 

type MinerCraftBase struct{}

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

func (*MinerCraftBase) APIType added in v0.5.8 

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

APIType will return the API type

func (*MinerCraftBase) AddMiner added in v0.5.5 

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

AddMiner adds a new miner to the list of miners.

func (*MinerCraftBase) BestQuote added in v0.5.5 

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 added in v0.5.5 

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 added in v0.5.5 

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

FeeQuote returns a fee quote for the given miner.

func (*MinerCraftBase) MinerAPIByMinerID added in v0.5.8 

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 added in v0.5.8 

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

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

func (*MinerCraftBase) MinerByID added in v0.5.5 

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

MinerByID returns a miner by its ID.

func (*MinerCraftBase) MinerByName added in v0.5.5 

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

MinerByName returns a miner by its name.

func (*MinerCraftBase) MinerUpdateToken added in v0.5.5 

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

MinerUpdateToken updates the token for the given miner.

func (*MinerCraftBase) Miners added in v0.5.5 

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

Miners returns all miners.

func (*MinerCraftBase) PolicyQuote added in v0.5.5 

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

PolicyQuote returns a policy quote for the given miner.

func (*MinerCraftBase) QueryTransaction added in v0.5.5 

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 added in v0.5.5 

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

RemoveMiner removes a miner from the list of miners.

func (*MinerCraftBase) SubmitTransaction added in v0.5.5 

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

SubmitTransaction submits a transaction to the given miner.

func (*MinerCraftBase) SubmitTransactions added in v0.5.5 

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

SubmitTransactions submits transactions to the given miner.

func (*MinerCraftBase) UserAgent added in v0.5.5 

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 added in v0.5.13 

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 added in v0.5.13 

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 added in v0.5.13 

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 added in v0.7.0 

func (t *TransactionInfo) Valid() bool

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

type TransactionType added in v0.2.14 

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 added in v0.4.7 

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 added in v0.5.13 

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 added in v0.5.13 

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.