Documentation ¶
Overview ¶
Package privatebtc handles the creation of a Bitcoin private network using Docker.
The package defines a NodeService interface that can be implemented to use different Node Handlers. The package also defines a RPCClientFactory interface that can be implemented to use different Go Bitcoin RPC Clients. A chain reorganisation manager is implemented, it streamlines the process of creating chain reorganisations.
Index ¶
- Constants
- Variables
- func ReplaceTransactionDrainToAddress(ctx context.Context, client RPCClient, txID string, address string) (string, error)
- type Balance
- type ChainReorg
- func (c *ChainReorg) DisconnectNode(ctx context.Context) (Node, error)
- func (c *ChainReorg) MineBlocksOnDisconnectedNode(ctx context.Context, numBlocks int64) ([]string, error)
- func (c *ChainReorg) MineBlocksOnNetwork(ctx context.Context, numBlocks int64) ([]string, error)
- func (c *ChainReorg) ReconnectNode(ctx context.Context) error
- func (c *ChainReorg) SendTransactionOnDisconnectedNode(ctx context.Context, receiverAddress string, amount float64) (string, error)
- func (c *ChainReorg) SendTransactionOnNetwork(ctx context.Context, receiverAddress string, amount float64) (string, error)
- type ChainReorgManager
- type ChainReorgWithAssertion
- func (c *ChainReorgWithAssertion) DisconnectNode(ctx context.Context) (Node, error)
- func (c *ChainReorgWithAssertion) MineBlocksOnDisconnectedNode(ctx context.Context, numBlocks int64) ([]string, error)
- func (c *ChainReorgWithAssertion) MineBlocksOnNetwork(ctx context.Context, numBlocks int64) ([]string, error)
- func (c *ChainReorgWithAssertion) ReconnectNode(ctx context.Context) error
- func (c *ChainReorgWithAssertion) SendTransactionOnDisconnectedNode(ctx context.Context, receiverAddress string, amount float64) (string, error)
- func (c *ChainReorgWithAssertion) SendTransactionOnNetwork(ctx context.Context, receiverAddress string, amount float64) (string, error)
- type CreateNodeRequest
- type Node
- func (n Node) ConnectToNetwork(ctx context.Context) error
- func (n Node) DisconnectFromNetwork(ctx context.Context) error
- func (n Node) Fund(ctx context.Context) (string, error)
- func (n Node) ID() int
- func (n Node) IsTransactionInMempool(ctx context.Context, txHash string) (bool, error)
- func (n Node) Name() string
- func (n Node) NodeHandler() NodeHandler
- func (n Node) RPCClient() RPCClient
- type NodeHandler
- type NodeService
- type Nodes
- type Option
- type PrivateNetwork
- func (n *PrivateNetwork) Close() error
- func (n *PrivateNetwork) NewChainReorg(disconnectedNodeIndex int) (*ChainReorg, error)
- func (n *PrivateNetwork) NewChainReorgWithAssertion(disconnectedNodeIndex int) (*ChainReorgWithAssertion, error)
- func (n *PrivateNetwork) Nodes() Nodes
- func (n *PrivateNetwork) Start(ctx context.Context) error
- type RPCClient
- type RPCClientFactory
- type Transaction
- type TransactionVin
- type TransactionVout
- type UnexpectedPeerCountError
Constants ¶
const ( RPCRegtestDefaultPort = "18443" P2PRegtestDefaultPort = "18444" )
Default Bitcoin Core ports for regtest.
Variables ¶
var ( // ErrCannotConnectToDockerAPI is returned when the Docker Engine API cannot be reached. ErrCannotConnectToDockerAPI = errors.New("cannot connect to Docker Engine API") // ErrPeerNotFound is returned when a peer is not found in a node's peer info response. ErrPeerNotFound = errors.New("peer not found in node peer info response") // ErrChainReorgMustDisconnectNodeFirst is returned whenever a chain reorg action is attempted // without first disconnecting a node from the network. // nolint: revive // line too long ErrChainReorgMustDisconnectNodeFirst = errors.New("chain reorg: must disconnect node first") // ErrTimeoutAndChainsAreNotSynced is returned when a timeout occurs and the // chains are not synced. ErrTimeoutAndChainsAreNotSynced = errors.New("timeout and chains are not synced") // ErrChainsShouldNotBeSynced is returned when the chains should not be synced. ErrChainsShouldNotBeSynced = errors.New("chains should not be synced") // ErrTxNotFoundInMempool is returned when a transaction is not found in the mempool. ErrTxNotFoundInMempool = errors.New("tx not found in mempool") // ErrTxFoundInMempool is returned when a transaction is unexpectedly found in the mempool. ErrTxFoundInMempool = errors.New("tx found in mempool") // ErrNodeIndexOutOfRange is returned when a node index is out of range. ErrNodeIndexOutOfRange = errors.New("node index out of range") )
exported errors.
Functions ¶
func ReplaceTransactionDrainToAddress ¶
func ReplaceTransactionDrainToAddress( ctx context.Context, client RPCClient, txID string, address string, ) (string, error)
ReplaceTransactionDrainToAddress performs a replace by fee(RBF) for the given transaction id. The new transaction will drain the inputs of the old transaction to the given address while increasing the fee by 100%.
Types ¶
type ChainReorg ¶
type ChainReorg struct {
// contains filtered or unexported fields
}
ChainReorg represents a chain reorg manager.
func (*ChainReorg) DisconnectNode ¶
func (c *ChainReorg) DisconnectNode(ctx context.Context) (Node, error)
DisconnectNode disconnects a node from the network.
func (*ChainReorg) MineBlocksOnDisconnectedNode ¶
func (c *ChainReorg) MineBlocksOnDisconnectedNode( ctx context.Context, numBlocks int64, ) ([]string, error)
MineBlocksOnDisconnectedNode mines blocks on the disconnected node.
func (*ChainReorg) MineBlocksOnNetwork ¶
MineBlocksOnNetwork mines blocks on the network.
func (*ChainReorg) ReconnectNode ¶
func (c *ChainReorg) ReconnectNode(ctx context.Context) error
ReconnectNode reconnects the disconnected node to the network.
func (*ChainReorg) SendTransactionOnDisconnectedNode ¶
func (c *ChainReorg) SendTransactionOnDisconnectedNode( ctx context.Context, receiverAddress string, amount float64, ) (string, error)
SendTransactionOnDisconnectedNode sends a transaction on the disconnected node.
func (*ChainReorg) SendTransactionOnNetwork ¶
func (c *ChainReorg) SendTransactionOnNetwork( ctx context.Context, receiverAddress string, amount float64, ) (string, error)
SendTransactionOnNetwork sends a transaction on the network.
type ChainReorgManager ¶
type ChainReorgManager interface { DisconnectNode(ctx context.Context) (Node, error) SendTransactionOnNetwork( ctx context.Context, receiverAddress string, amount float64, ) (string, error) SendTransactionOnDisconnectedNode(ctx context.Context, receiverAddress string, amount float64) (string, error) MineBlocksOnNetwork(ctx context.Context, numBlocks int64) ([]string, error) MineBlocksOnDisconnectedNode(ctx context.Context, numBlocks int64) ([]string, error) ReconnectNode(ctx context.Context) error }
ChainReorgManager defines methods for handling a chain reorg. nolint: revive
type ChainReorgWithAssertion ¶
type ChainReorgWithAssertion struct {
*ChainReorg
}
ChainReorgWithAssertion represents a chain reorg manager with assertion.
func (*ChainReorgWithAssertion) DisconnectNode ¶
func (c *ChainReorgWithAssertion) DisconnectNode(ctx context.Context) (Node, error)
DisconnectNode disconnects a node from the network. It is expected that the node will have 0 peers after disconnecting.
func (*ChainReorgWithAssertion) MineBlocksOnDisconnectedNode ¶
func (c *ChainReorgWithAssertion) MineBlocksOnDisconnectedNode( ctx context.Context, numBlocks int64, ) ([]string, error)
MineBlocksOnDisconnectedNode mines blocks on the disconnected node. It is expected that the network nodes do not will not see the new blocks.
func (*ChainReorgWithAssertion) MineBlocksOnNetwork ¶
func (c *ChainReorgWithAssertion) MineBlocksOnNetwork( ctx context.Context, numBlocks int64, ) ([]string, error)
MineBlocksOnNetwork mines blocks on the network. It is expected that the disconnected node will not see the new blocks.
func (*ChainReorgWithAssertion) ReconnectNode ¶
func (c *ChainReorgWithAssertion) ReconnectNode(ctx context.Context) error
ReconnectNode reconnects the disconnected node to the network. It is expected that the disconnected node will reorg to the network chain.
func (*ChainReorgWithAssertion) SendTransactionOnDisconnectedNode ¶
func (c *ChainReorgWithAssertion) SendTransactionOnDisconnectedNode( ctx context.Context, receiverAddress string, amount float64, ) (string, error)
SendTransactionOnDisconnectedNode sends a transaction on the disconnected node. It is expected that the transaction is not in any network node mempool.
func (*ChainReorgWithAssertion) SendTransactionOnNetwork ¶
func (c *ChainReorgWithAssertion) SendTransactionOnNetwork( ctx context.Context, receiverAddress string, amount float64, ) (string, error)
SendTransactionOnNetwork sends a transaction on the network. It is expected that the transaction is in every node mempool except the disconnected node.
type CreateNodeRequest ¶
CreateNodeRequest is used to create a node.
type Node ¶
type Node struct {
// contains filtered or unexported fields
}
Node represents a node in the private network. It contains an RPC client and a Node Handler.
func (Node) ConnectToNetwork ¶
ConnectToNetwork connects the node to the network (the other nodes).
func (Node) DisconnectFromNetwork ¶
DisconnectFromNetwork disconnects the node from the network (the other nodes).
func (Node) Fund ¶
Fund is a helper function for funding a node. It generates a new address to the block and mines 101 blocks to it, returning the hash of the last block that was mined This method will fund the node wallet with 50 BTC.
func (Node) IsTransactionInMempool ¶
IsTransactionInMempool checks if a transaction is in the mempool of the node.
func (Node) NodeHandler ¶
func (n Node) NodeHandler() NodeHandler
NodeHandler returns the nodeHandler of the node.
type NodeHandler ¶
NodeHandler represents manager for a bitcoin node.
type NodeService ¶
type NodeService interface { CreateNodes( ctx context.Context, nodeRequests []CreateNodeRequest, ) ([]NodeHandler, error) }
NodeService is a service for creating Bitcoin Nodes.
type Nodes ¶
type Nodes []Node
Nodes is a slice of nodes.
func (Nodes) EnsureTransactionInEveryMempool ¶
EnsureTransactionInEveryMempool ensures that a transaction is in the mempool of every node. nolint: gocognit
func (Nodes) EnsureTransactionNotInAnyMempool ¶
EnsureTransactionNotInAnyMempool ensures that transaction is not in any mempool of the nodes.
type Option ¶
type Option interface {
// contains filtered or unexported methods
}
An Option configures a parameter for the Bitcoin Private Network. The functional options are implemented following uber guidelines. https://github.com/uber-go/guide/blob/master/style.md#functional-options
func WithBitcoinClientVersion ¶
WithBitcoinClientVersion configures the version of the bitcoin client to use.
func WithNodeNamePrefix ¶
WithNodeNamePrefix configures the prefix for the node names.
func WithRPCAuth ¶
WithRPCAuth configures the RPC authentication for the Bitcoin Private Network.
func WithSlogHandler ¶
WithSlogHandler configures the handler for the Bitcoin Private Network.
func WithTimeout ¶
WithTimeout configures the timeout for the docker operations.
func WithWallet ¶
WithWallet configures and creates a wallet for the nodes.
type PrivateNetwork ¶
type PrivateNetwork struct {
// contains filtered or unexported fields
}
PrivateNetwork is a Bitcoin private network.
func NewPrivateNetwork ¶
func NewPrivateNetwork( nodeService NodeService, rpcClientFactory RPCClientFactory, nodes int, opts ...Option, ) (*PrivateNetwork, error)
NewPrivateNetwork creates a new private network with the given number of nodes.
func (*PrivateNetwork) Close ¶
func (n *PrivateNetwork) Close() error
Close terminates all nodes in the private network.
func (*PrivateNetwork) NewChainReorg ¶
func (n *PrivateNetwork) NewChainReorg( disconnectedNodeIndex int, ) (*ChainReorg, error)
NewChainReorg creates a new chain reorg manager.
func (*PrivateNetwork) NewChainReorgWithAssertion ¶
func (n *PrivateNetwork) NewChainReorgWithAssertion( disconnectedNodeIndex int, ) (*ChainReorgWithAssertion, error)
NewChainReorgWithAssertion creates a new chain reorg manager with assertion.
func (*PrivateNetwork) Nodes ¶
func (n *PrivateNetwork) Nodes() Nodes
Nodes returns a copy of the nodes in the private network.
type RPCClient ¶
type RPCClient interface { // SendToAddress sends the given satoshi amount to the given address. SendToAddress(ctx context.Context, address string, amount float64) (txHash string, _ error) // SendCustomTransaction sends a custom transaction with the given inputs and amounts. SendCustomTransaction(ctx context.Context, inputs []TransactionVin, amounts map[string]float64) (txHash string, _ error) // GenerateToAddress generates the given number of blocks to the given address. GenerateToAddress(ctx context.Context, numBlocks int64, address string) (blockHashes []string, _ error) // GetConnectionCount returns the number of connections to other nodes. GetConnectionCount(ctx context.Context) (int, error) // AddPeer adds the given peer to the node. AddPeer(ctx context.Context, peer Node) error // RemovePeer removes the given peer from the node. RemovePeer(ctx context.Context, peer Node) error // CreateWallet creates a new wallet with the given name. CreateWallet(ctx context.Context, walletName string) error // GetRawMempool returns all transaction ids in memory pool GetRawMempool(ctx context.Context) ([]string, error) // GetBlockCount returns the number of blocks in the longest blockchain. GetBlockCount(ctx context.Context) (int, error) // GetNewAddress returns a new address for receiving payments. GetNewAddress(ctx context.Context, label string) (string, error) // GetBalance returns the total available balance. // From the Bitcoin Core RPC Docs: // The available balance is what the wallet considers currently spendable, and is // thus affected by options which limit spendability such as -spendzeroconfchange. GetBalance(ctx context.Context) (Balance, error) // GetTransaction returns the transaction with the given hash. GetTransaction(ctx context.Context, txHash string) (*Transaction, error) ListAddresses(ctx context.Context) ([]string, error) GetBestBlockHash(ctx context.Context) (string, error) GetCoinbaseValue(ctx context.Context) (int64, error) }
RPCClient is an interface for RPC clients. The methods are closely mapped to the bitcoin RPC API. nolint: interfacebloat, revive
type RPCClientFactory ¶
type RPCClientFactory interface {
NewRPCClient(hostRPCPort, rpcUser, rpcPass string) (RPCClient, error)
}
RPCClientFactory is an interface for RPC client factories. It is used to decouple the creation of the RPC Client from the actual implementation. We have to use the factory pattern because the RPC Clients are created dynamically for each node when the network is created.
type Transaction ¶
type Transaction struct { TxID string Hash string BlockHash string Vout []TransactionVout Vin []TransactionVin }
Transaction represents a BTC transaction.
func (Transaction) GetTransactionFee ¶
func (tx Transaction) GetTransactionFee(totalInputs float64) float64
GetTransactionFee returns the transaction fee.
func (Transaction) TotalInputsValue ¶
TotalInputsValue sums up the value of all inputs in the transaction by checking the value of the outputs that they spend from.
type TransactionVin ¶
TransactionVin represents a BTC transaction input.
type TransactionVout ¶
TransactionVout represents a BTC transaction output.
type UnexpectedPeerCountError ¶
type UnexpectedPeerCountError struct {
// contains filtered or unexported fields
}
UnexpectedPeerCountError is returned when a node has an unexpected number of peers.
func (*UnexpectedPeerCountError) Error ¶
func (e *UnexpectedPeerCountError) Error() string
Source Files ¶
Directories ¶
Path | Synopsis |
---|---|
Package btcsuite provides implementations of the privatebtc.RPCClientFactory and privatebtc.RPCClient interfaces using the https://github.com/ory/dockertest package.
|
Package btcsuite provides implementations of the privatebtc.RPCClientFactory and privatebtc.RPCClient interfaces using the https://github.com/ory/dockertest package. |
cmd
|
|
Package docker provides utility functions for checking the Docker environment.
|
Package docker provides utility functions for checking the Docker environment. |
dockertest
Package dockertest provides implementations of the privatebtc.NodeService and privatebtc.NodeHandler interfaces using the https://github.com/ory/dockertest package.
|
Package dockertest provides implementations of the privatebtc.NodeService and privatebtc.NodeHandler interfaces using the https://github.com/ory/dockertest package. |
testcontainers
Package testcontainers provides implementations of the privatebtc.NodeService and privatebtc.NodeHandler interfaces the using the https://github.com/testcontainers/testcontainers-go package.
|
Package testcontainers provides implementations of the privatebtc.NodeService and privatebtc.NodeHandler interfaces the using the https://github.com/testcontainers/testcontainers-go package. |
Package mock provides a mock implementation of the privatebtc package for testing purposes.
|
Package mock provides a mock implementation of the privatebtc package for testing purposes. |
Package tview provides a Terminal User Interface for the Bitcoin Private Network implemented in the privatebtc package using https://github.com/rivo/tview
|
Package tview provides a Terminal User Interface for the Bitcoin Private Network implemented in the privatebtc package using https://github.com/rivo/tview |