btcutil

package module
v0.0.0-...-60d4bed Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 19, 2014 License: ISC Imports: 25 Imported by: 0

README

btcutil

[Build Status] (https://travis-ci.org/conformal/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. Package btcutil is licensed under the liberal ISC license.

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.

Documentation

Full go doc style documentation for the project can be viewed online without installing this package by using the GoDoc site here: http://godoc.org/github.com/conformal/btcutil

You can also view the documentation locally once the package is installed with the godoc tool by running godoc -http=":6060" and pointing your browser to http://localhost:6060/pkg/github.com/conformal/btcutil

Installation

$ go get github.com/conformal/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 Conformal. 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 liberal 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.

Base58 Usage

To decode a base58 string: 

rawData := btcutil.Base58Decode(encodedData)

Similarly, to encode the same data: 

encodedData := btcutil.Base58Encode(rawData)

Index

Constants

View Source 
const (
	// MainNetAddr is the address identifier for MainNet
	MainNetAddr = 0x00

	// TestNetAddr is the address identifier for TestNet
	TestNetAddr = 0x6f

	// MainNetKey is the key identifier for MainNet
	MainNetKey = 0x80

	// TestNetKey is the key identifier for TestNet
	TestNetKey = 0xef

	// MainNetScriptHash is the script hash identifier for MainNet
	MainNetScriptHash = 0x05

	// TestNetScriptHash is the script hash identifier for TestNet
	TestNetScriptHash = 0xc4
)

Constants used to specify which network a payment address belongs to. Mainnet address cannot be used on the Testnet, and vice versa.

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

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

	// MaxSatoshi is the maximum transaction amount allowed in satoshi.
	MaxSatoshi int64 = 21e6 * SatoshiPerBitcoin
)
View Source 
const BlockHeightUnknown = int64(-1)

BlockHeightUnknown is the value returned for a block height that is unknown. This is typically because the block has not been inserted into the main chain yet.

View Source 
const TxIndexUnknown = -1

TxIndexUnknown is the value returned for a transaction index that is unknown. This is typically because the transaction has not been inserted into a block yet.

Variables

View Source 
var (
	// ErrUnknownNet describes an error where the Bitcoin network is
	// not recognized.
	ErrUnknownNet = errors.New("unrecognized bitcoin network")

	// ErrMalformedAddress describes an error where an address is improperly
	// formatted, either due to an incorrect length of the hashed pubkey or
	// a non-matching checksum.
	ErrMalformedAddress = errors.New("malformed address")

	// ErrMalformedPrivateKey describes an error where an address is
	// improperly formatted, either due to an incorrect length of the
	// private key or a non-matching checksum.
	ErrMalformedPrivateKey = errors.New("malformed private key")

	// ErrChecksumMismatch describes an error where decoding failed due
	// to a bad checksum.
	ErrChecksumMismatch = errors.New("checksum mismatch")

	// ErrUnknownIdentifier describes an error where decoding failed due
	// to an unknown magic byte identifier.
	ErrUnknownIdentifier = errors.New("unknown identifier byte")
)

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 Base58Decode 

func Base58Decode(b string) []byte

Base58Decode decodes a modified base58 string to a byte slice.

func Base58Encode 

func Base58Encode(b []byte) string

Base58Encode encodes a byte slice to a modified base58 string.

func DecodePrivateKey 

func DecodePrivateKey(wif string) ([]byte, btcwire.BitcoinNet, bool, error)

DecodePrivateKey takes a Wallet Import Format (WIF) string and decodes into a 32-byte private key.

func EncodePrivateKey 

func EncodePrivateKey(privKey []byte, net btcwire.BitcoinNet, compressed bool) (string, error)

EncodePrivateKey takes a 32-byte private key and encodes it into the Wallet Import Format (WIF).

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 Address 

type Address interface {
	// EncodeAddress returns the string encoding of the address.
	EncodeAddress() string

	// ScriptAddress returns the raw bytes of the address to be used
	// when inserting the address into a txout's script.
	ScriptAddress() []byte

	// IsForNet returns whether or not the address is associated with the
	// passed bitcoin network.
	IsForNet(btcwire.BitcoinNet) bool
}

Address is an interface type for any type of destination a transaction output may spend to. This includes pay-to-pubkey (P2PK), pay-to-pubkey-hash (P2PKH), and pay-to-script-hash (P2SH). Address is designed to be generic enough that other kinds of addresses may be added in the future without changing the decoding and encoding API.

func DecodeAddress 

func DecodeAddress(addr string, defaultNet btcwire.BitcoinNet) (Address, error)

DecodeAddress decodes the string encoding of an address and returns the Address if addr is a valid encoding for a known address type.

The bitcoin network the address is associated with is extracted if possible. When the address does not encode the network, such as in the case of a raw public key, the address will be associated with the passed defaultNet.

type AddressPubKey 

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

AddressPubKey is an Address for a pay-to-pubkey transaction.

func NewAddressPubKey 

func NewAddressPubKey(serializedPubKey []byte, net btcwire.BitcoinNet) (*AddressPubKey, error)

NewAddressPubKey returns a new AddressPubKey which represents a pay-to-pubkey address. The serializedPubKey parameter must be a valid pubkey and can be uncompressed, compressed, or hybrid. The net parameter must be btcwire.MainNet or btcwire.TestNet3.

func (*AddressPubKey) AddressPubKeyHash 

func (a *AddressPubKey) AddressPubKeyHash() *AddressPubKeyHash

AddressPubKeyHash returns the pay-to-pubkey address converted to a pay-to-pubkey-hash address. Note that the public key format (uncompressed, compressed, etc) will change the resulting address. This is expected since pay-to-pubkey-hash is a hash of the serialized public key which obviously differs with the format. At the time of this writing, most Bitcoin addresses are pay-to-pubkey-hash constructed from the uncompressed public key.

func (*AddressPubKey) EncodeAddress 

func (a *AddressPubKey) EncodeAddress() string

EncodeAddress returns the string encoding of the public key as a pay-to-pubkey-hash. Note that the public key format (uncompressed, compressed, etc) will change the resulting address. This is expected since pay-to-pubkey-hash is a hash of the serialized public key which obviously differs with the format. At the time of this writing, most Bitcoin addresses are pay-to-pubkey-hash constructed from the uncompressed public key.

Part of the Address interface.

func (*AddressPubKey) Format 

func (a *AddressPubKey) Format() PubKeyFormat

PubKeyFormat returns the format (uncompressed, compressed, etc) of the pay-to-pubkey address.

func (*AddressPubKey) IsForNet 

func (a *AddressPubKey) IsForNet(net btcwire.BitcoinNet) bool

IsForNet returns whether or not the pay-to-pubkey address is associated with the passed bitcoin network.

func (*AddressPubKey) ScriptAddress 

func (a *AddressPubKey) ScriptAddress() []byte

ScriptAddress returns the bytes to be included in a txout script to pay to a public key. Setting the public key format will affect the output of this function accordingly. Part of the Address interface.

func (*AddressPubKey) SetFormat 

func (a *AddressPubKey) SetFormat(pkFormat PubKeyFormat)

SetFormat sets the format (uncompressed, compressed, etc) of the pay-to-pubkey address.

func (*AddressPubKey) String 

func (a *AddressPubKey) String() string

String returns the hex-encoded human-readable string for the pay-to-pubkey address. This is not the same as calling EncodeAddress.

type AddressPubKeyHash 

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

AddressPubKeyHash is an Address for a pay-to-pubkey-hash (P2PKH) transaction.

func NewAddressPubKeyHash 

func NewAddressPubKeyHash(pkHash []byte, net btcwire.BitcoinNet) (*AddressPubKeyHash, error)

NewAddressPubKeyHash returns a new AddressPubKeyHash. pkHash must be 20 bytes and net must be btcwire.MainNet or btcwire.TestNet3.

func (*AddressPubKeyHash) EncodeAddress 

func (a *AddressPubKeyHash) EncodeAddress() string

EncodeAddress returns the string encoding of a pay-to-pubkey-hash address. Part of the Address interface.

func (*AddressPubKeyHash) IsForNet 

func (a *AddressPubKeyHash) IsForNet(net btcwire.BitcoinNet) bool

IsForNet returns whether or not the pay-to-pubkey-hash address is associated with the passed bitcoin network.

func (*AddressPubKeyHash) ScriptAddress 

func (a *AddressPubKeyHash) ScriptAddress() []byte

ScriptAddress returns the bytes to be included in a txout script to pay to a pubkey hash. Part of the Address interface.

func (*AddressPubKeyHash) String 

func (a *AddressPubKeyHash) String() string

String returns a human-readable string for the pay-to-pubkey-hash address. This is equivalent to calling EncodeAddress, but is provided so the type can be used as a fmt.Stringer.

type AddressScriptHash 

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

AddressScriptHash is an Address for a pay-to-script-hash (P2SH) transaction.

func NewAddressScriptHash 

func NewAddressScriptHash(serializedScript []byte, net btcwire.BitcoinNet) (*AddressScriptHash, error)

NewAddressScriptHash returns a new AddressScriptHash. net must be btcwire.MainNet or btcwire.TestNet3.

func NewAddressScriptHashFromHash 

func NewAddressScriptHashFromHash(scriptHash []byte, net btcwire.BitcoinNet) (*AddressScriptHash, error)

NewAddressScriptHashFromHash returns a new AddressScriptHash. scriptHash must be 20 bytes and net must be btcwire.MainNet or btcwire.TestNet3.

func (*AddressScriptHash) EncodeAddress 

func (a *AddressScriptHash) EncodeAddress() string

EncodeAddress returns the string encoding of a pay-to-script-hash address. Part of the Address interface.

func (*AddressScriptHash) IsForNet 

func (a *AddressScriptHash) IsForNet(net btcwire.BitcoinNet) bool

IsForNet returns whether or not the pay-to-script-hash address is associated with the passed bitcoin network.

func (*AddressScriptHash) ScriptAddress 

func (a *AddressScriptHash) ScriptAddress() []byte

ScriptAddress returns the bytes to be included in a txout script to pay to a script hash. Part of the Address interface.

func (*AddressScriptHash) String 

func (a *AddressScriptHash) String() string

String returns a human-readable string for the pay-to-script-hash address. This is equivalent to calling EncodeAddress, but is provided so the type can be used as a fmt.Stringer.

type Block 

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

Block defines a bitcoin block that provides easier and more efficient manipulation of raw 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.

func NewBlock 

func NewBlock(msgBlock *btcwire.MsgBlock) *Block

NewBlock returns a new instance of a bitcoin block given an underlying btcwire.MsgBlock. See Block.

func NewBlockFromBlockAndBytes 

func NewBlockFromBlockAndBytes(msgBlock *btcwire.MsgBlock, serializedBlock []byte) *Block

NewBlockFromBlockAndBytes returns a new instance of a bitcoin block given an underlying btcwire.MsgBlock and the serialized bytes for it. See Block.

func NewBlockFromBytes 

func NewBlockFromBytes(serializedBlock []byte) (*Block, error)

NewBlockFromBytes returns a new instance of a bitcoin block given the serialized bytes. See Block.

func (*Block) Bytes 

func (b *Block) Bytes() ([]byte, error)

Bytes returns the serialized bytes for the Block. This is equivalent to calling Serialize on the underlying btcwire.MsgBlock, however it caches the result so subsequent calls are more efficient.

func (*Block) Height 

func (b *Block) Height() int64

Height returns the saved height of the block in the block chain. This value will be BlockHeightUnknown if it hasn't already explicitly been set.

func (*Block) MsgBlock 

func (b *Block) MsgBlock() *btcwire.MsgBlock

MsgBlock returns the underlying btcwire.MsgBlock for the Block.

func (*Block) SetHeight 

func (b *Block) SetHeight(height int64)

SetHeight sets the height of the block in the block chain.

func (*Block) Sha 

func (b *Block) Sha() (*btcwire.ShaHash, error)

Sha returns the block identifier hash for the Block. This is equivalent to calling BlockSha on the underlying btcwire.MsgBlock, however it caches the result so subsequent calls are more efficient.

func (*Block) Transactions 

func (b *Block) Transactions() []*Tx

Transactions returns a slice of wrapped transactions (btcutil.Tx) for all transactions in the Block. This is nearly equivalent to accessing the raw transactions (btcwire.MsgTx) in the underlying btcwire.MsgBlock, however it instead provides easy access to wrapped versions (btcutil.Tx) of them.

func (*Block) Tx 

func (b *Block) Tx(txNum int) (*Tx, error)

Tx returns a wrapped transaction (btcutil.Tx) for the transaction at the specified index in the Block. The supplied index is 0 based. That is to say, the first transaction in the block is txNum 0. This is nearly equivalent to accessing the raw transaction (btcwire.MsgTx) from the underlying btcwire.MsgBlock, however the wrapped transaction has some helpful properties such as caching the hash so subsequent calls are more efficient.

func (*Block) TxLoc 

func (b *Block) TxLoc() ([]btcwire.TxLoc, error)

TxLoc returns the offsets and lengths of each transaction in a raw block. It is used to allow fast indexing into transactions within the raw byte stream.

func (*Block) TxSha 

func (b *Block) TxSha(txNum int) (*btcwire.ShaHash, error)

TxSha returns the hash for the requested transaction number in the Block. The supplied index is 0 based. That is to say, the first transaction in the block is txNum 0. This is equivalent to calling TxSha on the underlying btcwire.MsgTx, however it caches the result so subsequent calls are more efficient.

func (*Block) TxShas 

func (b *Block) TxShas() ([]*btcwire.ShaHash, error)

TxShas returns a slice of hashes for all transactions in the Block. This is equivalent to calling TxSha on each underlying btcwire.MsgTx, however it caches the result so subsequent calls are more efficient.

DEPRECATED - This function will be removed in the next version and should not be used. Instead, use Transactions() and .Sha() on each transaction.

type OutOfRangeError 

type OutOfRangeError string

OutOfRangeError describes an error due to accessing an element that is out of range.

func (OutOfRangeError) Error 

func (e OutOfRangeError) Error() string

Error satisfies the error interface and prints human-readable errors.

type PubKeyFormat 

type PubKeyFormat int

PubKeyFormat describes what format to use for a pay-to-pubkey address. 

const (
	// PKFUncompressed indicates the pay-to-pubkey address format is an
	// uncompressed public key.
	PKFUncompressed PubKeyFormat = iota

	// PKFCompressed indicates the pay-to-pubkey address format is a
	// compressed public key.
	PKFCompressed

	// PKFHybrid indicates the pay-to-pubkey address format is a hybrid
	// public key.
	PKFHybrid
)

type Tx 

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

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

func NewTx 

func NewTx(msgTx *btcwire.MsgTx) *Tx

NewTx returns a new instance of a bitcoin transaction given an underlying btcwire.MsgTx. See Tx.

func NewTxFromBytes 

func NewTxFromBytes(serializedTx []byte) (*Tx, error)

NewTxFromBytes returns a new instance of a bitcoin transaction given the serialized bytes. See Tx.

func (*Tx) Index 

func (t *Tx) Index() int

Index returns the saved index of the transaction within a block. This value will be TxIndexUnknown if it hasn't already explicitly been set.

func (*Tx) MsgTx 

func (t *Tx) MsgTx() *btcwire.MsgTx

MsgTx returns the underlying btcwire.MsgTx for the transaction.

func (*Tx) SetIndex 

func (t *Tx) SetIndex(index int)

SetIndex sets the index of the transaction in within a block.

func (*Tx) Sha 

func (t *Tx) Sha() *btcwire.ShaHash

Sha returns the hash of the transaction. This is equivalent to calling TxSha on the underlying btcwire.MsgTx, however it caches the result so subsequent calls are more efficient.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.