Categorygithub.com/btcsuite/btcutilcoinset
package
1.0.2
Repository: https://github.com/btcsuite/btcutil.git
Documentation: pkg.go.dev
Versions
1
Dependencies
6
Dependents
16
Files
264 SLOC

# README

coinset

Build Status ISC License GoDoc

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.

# Functions

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

# Variables

ErrCoinsNoSelectionAvailable is returned when a CoinSelector believes there is no possible combination of coins which can meet the requirements provided to the selector.

# Structs

CoinSet is a utility struct for the modifications of a set of Coins that implements the Coins interface.
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.
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.
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.
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.
SimpleCoin defines a concrete instance of Coin that is backed by a btcutil.Tx, a specific outpoint index, and the number of confirmations that transaction has had.

# Interfaces

Coin represents a spendable transaction outpoint.
Coins represents a set of Coins.
CoinSelector is an interface that wraps the CoinSelect method.