btcutil

README

btcutil

Package btcutil provides bitcoin-specific convenience functions and types. 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.

This package was developed for btcd, an alternative full-node implementation of bitcoin which is under active development by Conformal. Although it was primarily written for btcd, this package has intentionally been designed so it can be used as a standalone package for any projects needing the functionality provided.

Installation and Updating

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

GPG Verification Key

All official release tags are signed by Conformal so users can ensure the code has not been tampered with and is coming from the btcsuite developers. To verify the signature perform the following:

• Download the public key from the Conformal website at https://opensource.conformal.com/GIT-GPG-KEY-conformal.txt

• Import the public key into your GPG keyring:

  gpg --import GIT-GPG-KEY-conformal.txt
  

• Verify the release tag with the following command where TAG_NAME is a placeholder for the specific tag:

  git tag -v TAG_NAME
  

License

Package btcutil is licensed under the copyfree ISC License.

Documentation

Overview

Package btcutil provides bitcoin-specific convenience functions and types.

Block Overview

A Block defines a bitcoin block that provides easier and more efficient manipulation of raw wire protocol blocks. It also memoizes hashes for the block and its transactions on their first access so subsequent accesses don't have to repeat the relatively expensive hashing operations.

Tx Overview

A Tx defines a bitcoin transaction that provides more efficient manipulation of raw wire protocol transactions. It memoizes the hash for the transaction on its first access so subsequent accesses don't have to repeat the relatively expensive hashing operations.

Address Overview

The Address interface provides an abstraction for a Bitcoin address. While the most common type is a pay-to-pubkey-hash, Bitcoin already supports others and may well support more in the future. This package currently provides implementations for the pay-to-pubkey, pay-to-pubkey-hash, and pay-to-script-hash address types.

To decode/encode an address:

// NOTE: The default network is only used for address types which do not
// already contain that information.  At this time, that is only
// pay-to-pubkey addresses.
addrString := "04678afdb0fe5548271967f1a67130b7105cd6a828e03909a67962" +
	"e0ea1f61deb649f6bc3f4cef38c4f35504e51ec112de5c384df7ba0b8d57" +
	"8a4c702b6bf11d5f"
defaultNet := &chaincfg.MainNetParams
addr, err := btcutil.DecodeAddress(addrString, defaultNet)
if err != nil {
	fmt.Println(err)
	return
}
fmt.Println(addr.EncodeAddress())

Index

• Constants
• func AppDataDir(appName string, roaming bool) string
• func Hash160(buf []byte) []byte
• func NewTLSCertPair(organization string, validUntil time.Time, extraHosts []string) (cert, key []byte, err error)
• type Amount
  • func NewAmount(f float64) (Amount, error)
  • func (a Amount) Format(u AmountUnit) string
  • func (a Amount) MulF64(f float64) Amount
  • func (a Amount) String() string
  • func (a Amount) ToBTC() float64
  • func (a Amount) ToUnit(u AmountUnit) float64
• type AmountUnit
  • func (u AmountUnit) String() string
• type BitcoinNet
  • func (n BitcoinNet) ToString() string
• type DNSSeed

Constants

const (
	// SatoshiPerBitcent is the number of satoshi in one bitcoin cent.
	SatoshiPerBitcent = 1e6

	// SatoshiPerBitcoin is the number of satoshi in one bitcoin (1 BTC).
	SatoshiPerBitcoin = 1e8

	// MaxSatoshi is the maximum transaction amount allowed in satoshi.
	MaxSatoshi = 21e6 * SatoshiPerBitcoin
)

Functions

func AppDataDir

func AppDataDir(appName string, roaming bool) string

AppDataDir returns an operating system specific directory to be used for storing application data for an application.

The appName parameter is the name of the application the data directory is being requested for. This function will prepend a period to the appName for POSIX style operating systems since that is standard practice. An empty appName or one with a single dot is treated as requesting the current directory so only "." will be returned. Further, the first character of appName will be made lowercase for POSIX style operating systems and uppercase for Mac and Windows since that is standard practice.

The roaming parameter only applies to Windows where it specifies the roaming application data profile (%APPDATA%) should be used instead of the local one (%LOCALAPPDATA%) that is used by default.

Example results:

dir := AppDataDir("myapp", false)
 POSIX (Linux/BSD): ~/.myapp
 Mac OS: $HOME/Library/Application Support/Myapp
 Windows: %LOCALAPPDATA%\Myapp
 Plan 9: $home/myapp

func Hash160

func Hash160(buf []byte) []byte

Hash160 calculates the hash ripemd160(sha256(b)).

func NewTLSCertPair

func NewTLSCertPair(organization string, validUntil time.Time, extraHosts []string) (cert, key []byte, err error)

NewTLSCertPair returns a new PEM-encoded x.509 certificate pair based on a 521-bit ECDSA private key. The machine's local interface addresses and all variants of IPv4 and IPv6 localhost are included as valid IP addresses.

Types

type Amount

type Amount int64

Amount represents the base bitcoin monetary unit (colloquially referred to as a `Satoshi'). A single Amount is equal to 1e-8 of a bitcoin.

func NewAmount

func NewAmount(f float64) (Amount, error)

NewAmount creates an Amount from a floating point value representing some value in bitcoin. NewAmount errors if f is NaN or +-Infinity, but does not check that the amount is within the total amount of bitcoin producible as f may not refer to an amount at a single moment in time.

NewAmount is for specifically for converting BTC to Satoshi. For creating a new Amount with an int64 value which denotes a quantity of Satoshi, do a simple type conversion from type int64 to Amount. See GoDoc for example: http://godoc.org/github.com/btcsuite/btcutil#example-Amount

func (Amount) Format

func (a Amount) Format(u AmountUnit) string

Format formats a monetary amount counted in bitcoin base units as a string for a given unit. The conversion will succeed for any unit, however, known units will be formated with an appended label describing the units with SI notation, or "Satoshi" for the base unit.

func (Amount) MulF64

func (a Amount) MulF64(f float64) Amount

MulF64 multiplies an Amount by a floating point value. While this is not an operation that must typically be done by a full node or wallet, it is useful for services that build on top of bitcoin (for example, calculating a fee by multiplying by a percentage).

func (Amount) String

func (a Amount) String() string

String is the equivalent of calling Format with AmountBTC.

func (Amount) ToBTC

func (a Amount) ToBTC() float64

ToBTC is the equivalent of calling ToUnit with AmountBTC.

func (Amount) ToUnit

func (a Amount) ToUnit(u AmountUnit) float64

ToUnit converts a monetary amount counted in bitcoin base units to a floating point value representing an amount of bitcoin.

type AmountUnit

type AmountUnit int

AmountUnit describes a method of converting an Amount to something other than the base unit of a bitcoin. The value of the AmountUnit is the exponent component of the decadic multiple to convert from an amount in bitcoin to an amount counted in units.

const (
	AmountMegaBTC  AmountUnit = 6
	AmountKiloBTC  AmountUnit = 3
	AmountBTC      AmountUnit = 0
	AmountMilliBTC AmountUnit = -3
	AmountMicroBTC AmountUnit = -6
	AmountSatoshi  AmountUnit = -8
)

These constants define various units used when describing a bitcoin monetary amount.

func (AmountUnit) String

func (u AmountUnit) String() string

String returns the unit as a string. For recognized units, the SI prefix is used, or "Satoshi" for the base unit. For all unrecognized units, "1eN BTC" is returned, where N is the AmountUnit.

type BitcoinNet

type BitcoinNet uint32

BitcoinNet represents which bitcoin network a msg belongs to.

const (
	MainNet  BitcoinNet = 0xd9b4bef9
	TestNet  BitcoinNet = 0xdab5bffa
	TestNet3 BitcoinNet = 0x0709110b
	SimNet   BitcoinNet = 0x12141c16
)

func (BitcoinNet) ToString

func (n BitcoinNet) ToString() string

type DNSSeed

type DNSSeed struct {
	Host         string
	HasFiltering bool
}