coinset

README

coinset

Package coinset provides bitcoin-specific convenience functions for selecting from and managing sets of unspent transaction outpoints (UTXOs).

A comprehensive suite of tests is provided to ensure proper functionality. See test_coverage.txt for the gocov coverage report. Alternatively, if you are running a POSIX OS, you can run the cov_report.sh script for a real-time report.

Installation and Updating

$ go get -u github.com/btcsuite/btcutil/coinset

Usage

Each unspent transaction outpoint is represented by the Coin interface. An example of a concrete type that implements Coin is coinset.SimpleCoin.

The typical use case for this library is for creating raw bitcoin transactions given a set of Coins that may be spent by the user, for example as below:

var unspentCoins = []coinset.Coin{ ... }

When the user needs to spend a certain amount, they will need to select a subset of these coins which contain at least that value. CoinSelector is an interface that represents types that implement coin selection algos, subject to various criteria. There are a few examples of CoinSelector's:

• MinIndexCoinSelector

• MinNumberCoinSelector

• MaxValueAgeCoinSelector

• MinPriorityCoinSelector

For example, if the user wishes to maximize the probability that their transaction is mined quickly, they could use the MaxValueAgeCoinSelector to select high priority coins, then also attach a relatively high fee.

selector := &coinset.MaxValueAgeCoinSelector{
    MaxInputs: 10,
    MinAmountChange: 10000,
}
selectedCoins, err := selector.CoinSelect(targetAmount + bigFee, unspentCoins)
if err != nil {
	return err
}
msgTx := coinset.NewMsgTxWithInputCoins(selectedCoins)
...

The user can then create the msgTx.TxOut's as required, then sign the transaction and transmit it to the network.

License

Package coinset is licensed under the copyfree ISC License.

Documentation

Index

• Variables
• func NewMsgTxWithInputCoins(txVersion int32, inputCoins Coins) *wire.MsgTx
• type Coin
• type CoinSelector
• type CoinSet
  • func NewCoinSet(coins []Coin) *CoinSet
  • func (cs *CoinSet) Coins() []Coin
  • func (cs *CoinSet) Num() int
  • func (cs *CoinSet) PopCoin() Coin
  • func (cs *CoinSet) PushCoin(c Coin)
  • func (cs *CoinSet) ShiftCoin() Coin
  • func (cs *CoinSet) TotalValue() (value bglutil.Amount)
  • func (cs *CoinSet) TotalValueAge() (valueAge int64)
• type Coins
• type MaxValueAgeCoinSelector
  • func (s MaxValueAgeCoinSelector) CoinSelect(targetValue bglutil.Amount, coins []Coin) (Coins, error)
• type MinIndexCoinSelector
  • func (s MinIndexCoinSelector) CoinSelect(targetValue bglutil.Amount, coins []Coin) (Coins, error)
• type MinNumberCoinSelector
  • func (s MinNumberCoinSelector) CoinSelect(targetValue bglutil.Amount, coins []Coin) (Coins, error)
• type MinPriorityCoinSelector
  • func (s MinPriorityCoinSelector) CoinSelect(targetValue bglutil.Amount, coins []Coin) (Coins, error)
• type SimpleCoin
  • func (c *SimpleCoin) Hash() *chainhash.Hash
  • func (c *SimpleCoin) Index() uint32
  • func (c *SimpleCoin) NumConfs() int64
  • func (c *SimpleCoin) PkScript() []byte
  • func (c *SimpleCoin) Value() bglutil.Amount
  • func (c *SimpleCoin) ValueAge() int64

Variables

var (
	// ErrCoinsNoSelectionAvailable is returned when a CoinSelector believes there is no
	// possible combination of coins which can meet the requirements provided to the selector.
	ErrCoinsNoSelectionAvailable = errors.New("no coin selection possible")
)

Functions

func NewMsgTxWithInputCoins

func NewMsgTxWithInputCoins(txVersion int32, inputCoins Coins) *wire.MsgTx

NewMsgTxWithInputCoins takes the coins in the CoinSet and makes them the inputs to a new wire.MsgTx which is returned.

Types

type Coin

type Coin interface {
	Hash() *chainhash.Hash
	Index() uint32
	Value() bglutil.Amount
	PkScript() []byte
	NumConfs() int64
	ValueAge() int64
}

Coin represents a spendable transaction outpoint

type CoinSelector

type CoinSelector interface {
	CoinSelect(targetValue bglutil.Amount, coins []Coin) (Coins, error)
}

CoinSelector is an interface that wraps the CoinSelect method.

CoinSelect will attempt to select a subset of the coins which has at least the targetValue amount. CoinSelect is not guaranteed to return a selection of coins even if the total value of coins given is greater than the target value.

The exact choice of coins in the subset will be implementation specific.

It is important to note that the Coins being used as inputs need to have a constant ValueAge() during the execution of CoinSelect.

type CoinSet

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

CoinSet is a utility struct for the modifications of a set of Coins that implements the Coins interface. To create a CoinSet, you must call NewCoinSet with nil for an empty set or a slice of coins as the initial contents.

It is important to note that the all the Coins being added or removed from a CoinSet must have a constant ValueAge() during the use of the CoinSet, otherwise the cached values will be incorrect.

func NewCoinSet

func NewCoinSet(coins []Coin) *CoinSet

NewCoinSet creates a CoinSet containing the coins provided. To create an empty CoinSet, you may pass null as the coins input parameter.

func (*CoinSet) Coins

func (cs *CoinSet) Coins() []Coin

Coins returns a new slice of the coins contained in the set.

func (*CoinSet) Num

func (cs *CoinSet) Num() int

Num returns the number of coins in the set

func (*CoinSet) PopCoin

func (cs *CoinSet) PopCoin() Coin

PopCoin removes the last coin on the list and returns it.

func (*CoinSet) PushCoin

func (cs *CoinSet) PushCoin(c Coin)

PushCoin adds a coin to the end of the list and updates the cached value amounts.

func (*CoinSet) ShiftCoin

func (cs *CoinSet) ShiftCoin() Coin

ShiftCoin removes the first coin on the list and returns it.

func (*CoinSet) TotalValue

func (cs *CoinSet) TotalValue() (value bglutil.Amount)

TotalValue returns the total value of the coins in the set.

func (*CoinSet) TotalValueAge

func (cs *CoinSet) TotalValueAge() (valueAge int64)

TotalValueAge returns the total value * number of confirmations

of the coins in the set.

type Coins

type Coins interface {
	Coins() []Coin
}

Coins represents a set of Coins

type MaxValueAgeCoinSelector

type MaxValueAgeCoinSelector struct {
	MaxInputs       int
	MinChangeAmount bglutil.Amount
}

MaxValueAgeCoinSelector is a CoinSelector that attempts to construct a selection of coins whose total value is at least targetValue that has as much input value-age as possible.

This would be useful in the case where you want to maximize likelihood of the inclusion of your transaction in the next mined block.

func (MaxValueAgeCoinSelector) CoinSelect

func (s MaxValueAgeCoinSelector) CoinSelect(targetValue bglutil.Amount, coins []Coin) (Coins, error)

CoinSelect will attempt to select coins using the algorithm described in the MaxValueAgeCoinSelector struct.

type MinIndexCoinSelector

type MinIndexCoinSelector struct {
	MaxInputs       int
	MinChangeAmount bglutil.Amount
}

MinIndexCoinSelector is a CoinSelector that attempts to construct a selection of coins whose total value is at least targetValue and prefers any number of lower indexes (as in the ordered array) over higher ones.

func (MinIndexCoinSelector) CoinSelect

func (s MinIndexCoinSelector) CoinSelect(targetValue bglutil.Amount, coins []Coin) (Coins, error)

CoinSelect will attempt to select coins using the algorithm described in the MinIndexCoinSelector struct.

type MinNumberCoinSelector

type MinNumberCoinSelector struct {
	MaxInputs       int
	MinChangeAmount bglutil.Amount
}

MinNumberCoinSelector is a CoinSelector that attempts to construct a selection of coins whose total value is at least targetValue that uses as few of the inputs as possible.

func (MinNumberCoinSelector) CoinSelect

func (s MinNumberCoinSelector) CoinSelect(targetValue bglutil.Amount, coins []Coin) (Coins, error)

CoinSelect will attempt to select coins using the algorithm described in the MinNumberCoinSelector struct.

type MinPriorityCoinSelector

type MinPriorityCoinSelector struct {
	MaxInputs              int
	MinChangeAmount        bglutil.Amount
	MinAvgValueAgePerInput int64
}

MinPriorityCoinSelector is a CoinSelector that attempts to construct a selection of coins whose total value is at least targetValue and whose average value-age per input is greater than MinAvgValueAgePerInput. If there is change, it must exceed MinChangeAmount to be a valid selection.

When possible, MinPriorityCoinSelector will attempt to reduce the average input priority over the threshold, but no guarantees will be made as to minimality of the selection. The selection below is almost certainly suboptimal.

func (MinPriorityCoinSelector) CoinSelect

func (s MinPriorityCoinSelector) CoinSelect(targetValue bglutil.Amount, coins []Coin) (Coins, error)

CoinSelect will attempt to select coins using the algorithm described in the MinPriorityCoinSelector struct.

type SimpleCoin

type SimpleCoin struct {
	Tx         *bglutil.Tx
	TxIndex    uint32
	TxNumConfs int64
}

SimpleCoin defines a concrete instance of Coin that is backed by a bglutil.Tx, a specific outpoint index, and the number of confirmations that transaction has had.

func (*SimpleCoin) Hash

func (c *SimpleCoin) Hash() *chainhash.Hash

Hash returns the hash value of the transaction on which the Coin is an output

func (*SimpleCoin) Index

func (c *SimpleCoin) Index() uint32

Index returns the index of the output on the transaction which the Coin represents

func (*SimpleCoin) NumConfs

func (c *SimpleCoin) NumConfs() int64

NumConfs returns the number of confirmations that the transaction the Coin references has had.

func (*SimpleCoin) PkScript

func (c *SimpleCoin) PkScript() []byte

PkScript returns the outpoint script of the Coin.

This can be used to determine what type of script the Coin uses and extract standard addresses if possible using txscript.ExtractPkScriptAddrs for example.

func (*SimpleCoin) Value

func (c *SimpleCoin) Value() bglutil.Amount

Value returns the value of the Coin

func (*SimpleCoin) ValueAge

func (c *SimpleCoin) ValueAge() int64

ValueAge returns the product of the value and the number of confirmations. This is used as an input to calculate the priority of the transaction.