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 git.parallelcoin.io/dev/9/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 util.Amount)
  • func (cs *CoinSet) TotalValueAge() (valueAge int64)
• type Coins
• type MaxValueAgeCoinSelector
  • func (s MaxValueAgeCoinSelector) CoinSelect(targetValue util.Amount, coins []Coin) (Coins, error)
• type MinIndexCoinSelector
  • func (s MinIndexCoinSelector) CoinSelect(targetValue util.Amount, coins []Coin) (Coins, error)
• type MinNumberCoinSelector
  • func (s MinNumberCoinSelector) CoinSelect(targetValue util.Amount, coins []Coin) (Coins, error)
• type MinPriorityCoinSelector
  • func (s MinPriorityCoinSelector) CoinSelect(targetValue util.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() util.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() util.Amount
	PkScript() []byte
	NumConfs() int64
	ValueAge() int64
}

type CoinSelector

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

type CoinSet

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

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 util.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
}

type MaxValueAgeCoinSelector

type MaxValueAgeCoinSelector struct {
	MaxInputs       int
	MinChangeAmount util.Amount
}

func (MaxValueAgeCoinSelector) CoinSelect

func (s MaxValueAgeCoinSelector) CoinSelect(targetValue util.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 util.Amount
}

func (MinIndexCoinSelector) CoinSelect

func (s MinIndexCoinSelector) CoinSelect(targetValue util.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 util.Amount
}

func (MinNumberCoinSelector) CoinSelect

func (s MinNumberCoinSelector) CoinSelect(targetValue util.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        util.Amount
	MinAvgValueAgePerInput int64
}

func (MinPriorityCoinSelector) CoinSelect

func (s MinPriorityCoinSelector) CoinSelect(targetValue util.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         *util.Tx
	TxIndex    uint32
	TxNumConfs int64
}

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() util.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.