util

package
v0.6.4-rc3 Latest Latest
Warning

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

Go to latest
Published: Aug 19, 2020 License: ISC Imports: 31 Imported by: 18

README

util

ISC License GoDoc

Package util provides kaspa-specific convenience functions and types.

Documentation

Overview

Package util provides kaspa-specific convenience functions and types.

Block Overview

A Block defines a kaspa 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.

Tx Overview

A Tx defines a kaspa transaction that provides more efficient manipulation of raw 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 kaspa address. While the most common type is a pay-to-pubkey-hash, kaspa already supports others and may well support more in the future. This package currently provides implementations for the pay-to-pubkey-hash, and pay-to-script-hash address types.

To decode/encode an address:

addrString := "kaspa:qqfgqp8l9l90zwetj84k2jcac2m8falvvyy8xjtnhd"
defaultPrefix := util.Bech32PrefixKaspa
addr, err := util.DecodeAddress(addrString, defaultPrefix)
if err != nil {
	fmt.Println(err)
	return
}
fmt.Println(addr.EncodeAddress())

Index

Examples

Constants

View Source
const (
	// SompiPerKaspa is the number of sompi in one kaspa (1 KAS).
	SompiPerKaspa = 100000000

	// MaxSompi is the maximum transaction amount allowed in sompi.
	MaxSompi = 21000000 * SompiPerKaspa
)
View Source
const (
	// CoinbaseTransactionIndex is the index of the coinbase transaction in every block
	CoinbaseTransactionIndex = 0
)
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 (
	// ErrChecksumMismatch describes an error where decoding failed due
	// to a bad checksum.
	ErrChecksumMismatch = errors.New("checksum mismatch")

	// ErrUnknownAddressType describes an error where an address can not
	// decoded as a specific address type due to the string encoding
	// begining with an identifier byte unknown to any standard or
	// registered (via dagconfig.Register) network.
	ErrUnknownAddressType = errors.New("unknown address type")
)

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 BigToCompact

func BigToCompact(n *big.Int) uint32

BigToCompact converts a whole number N to a compact representation using an unsigned 32-bit number. The compact representation only provides 23 bits of precision, so values larger than (2^23 - 1) only encode the most significant digits of the number. See CompactToBig for details.

Example

This example demonstrates how to convert a target difficulty into the compact "bits" in a block header which represent that target difficulty .

package main

import (
	"fmt"
	"math/big"

	"github.com/kaspanet/kaspad/util"
)

func main() {
	// Convert the target difficulty from block 300000 in the bitcoin
	// main chain to compact form.
	t := "0000000000000000896c00000000000000000000000000000000000000000000"
	targetDifficulty, success := new(big.Int).SetString(t, 16)
	if !success {
		fmt.Println("invalid target difficulty")
		return
	}
	bits := util.BigToCompact(targetDifficulty)

	fmt.Println(bits)

}
Output:

419465580

func CalcWork

func CalcWork(bits uint32) *big.Int

CalcWork calculates a work value from difficulty bits. Kaspa increases the difficulty for generating a block by decreasing the value which the generated hash must be less than. This difficulty target is stored in each block header using a compact representation as described in the documentation for CompactToBig. Since a lower target difficulty value equates to higher actual difficulty, the work value which will be accumulated must be the inverse of the difficulty. Also, in order to avoid potential division by zero and really small floating point numbers, the result adds 1 to the denominator and multiplies the numerator by 2^256.

func CompactToBig

func CompactToBig(compact uint32) *big.Int

CompactToBig converts a compact representation of a whole number N to an unsigned 32-bit number. The representation is similar to IEEE754 floating point numbers.

Like IEEE754 floating point, there are three basic components: the sign, the exponent, and the mantissa. They are broken out as follows:

  • the most significant 8 bits represent the unsigned base 256 exponent

  • bit 23 (the 24th bit) represents the sign bit

  • the least significant 23 bits represent the mantissa

    ------------------------------------------------- | Exponent | Sign | Mantissa | ------------------------------------------------- | 8 bits [31-24] | 1 bit [23] | 23 bits [22-00] | -------------------------------------------------

The formula to calculate N is:

N = (-1^sign) * mantissa * 256^(exponent-3)
Example

This example demonstrates how to convert the compact "bits" in a block header which represent the target difficulty to a big integer and display it using the typical hex notation.

package main

import (
	"fmt"

	"github.com/kaspanet/kaspad/util"
)

func main() {
	bits := uint32(419465580)
	targetDifficulty := util.CompactToBig(bits)

	// Display it in hex.
	fmt.Printf("%064x\n", targetDifficulty.Bytes())

}
Output:

0000000000000000896c00000000000000000000000000000000000000000000

func CompactToBigWithDestination

func CompactToBigWithDestination(compact uint32, destination *big.Int)

CompactToBigWithDestination is a version of CompactToBig that takes a destination parameter. This is useful for saving memory, as then the destination big.Int can be reused. See CompactToBig for further details.

func FastLog2Floor

func FastLog2Floor(n uint64) uint8

FastLog2Floor calculates and returns floor(log2(x)) in a constant 5 steps.

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.

func SearchSlice

func SearchSlice(sliceLength int, searchFunc func(int) bool) (foundIndex int, ok bool)

SearchSlice uses binary search to find and return the smallest index i in [0, n) at which f(i) is true, assuming that on the range [0, n), f(i) == true implies f(i+1) == true. That is, SearchSlice requires that f is false for some (possibly empty) prefix of the input range [0, n) and then true for the (possibly empty) remainder; SearchSlice returns the first true index. SearchSlice calls f(i) only for i in the range [0, n).

func ToCamelCase

func ToCamelCase(str string) string

ToCamelCase converts a camelCase-ish string into a typical JSON camelCase string. Example conversion: MyJSONVariable -> myJsonVariable

Types

type Address

type Address interface {
	// String returns the string encoding of the transaction output
	// destination.
	//
	// Please note that String differs subtly from EncodeAddress: String
	// will return the value as a string without any conversion, while
	// EncodeAddress may convert destination types (for example,
	// converting pubkeys to P2PKH addresses) before encoding as a
	// payment address string.
	String() string

	// EncodeAddress returns the string encoding of the payment address
	// associated with the Address value. See the comment on String
	// for how this method differs from String.
	EncodeAddress() string

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

	// Prefix returns the prefix for this address
	Prefix() Bech32Prefix

	// IsForPrefix returns whether or not the address is associated with the
	// passed kaspa network.
	IsForPrefix(prefix Bech32Prefix) 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, expectedPrefix Bech32Prefix) (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.

If any expectedPrefix except Bech32PrefixUnknown is passed, it is compared to the prefix extracted from the address, and if the two do not match - an error is returned

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, prefix Bech32Prefix) (*AddressPubKeyHash, error)

NewAddressPubKeyHash returns a new AddressPubKeyHash. pkHash mustbe 20 bytes.

func NewAddressPubKeyHashFromPublicKey

func NewAddressPubKeyHashFromPublicKey(publicKey []byte, prefix Bech32Prefix) (*AddressPubKeyHash, error)

NewAddressPubKeyHashFromPublicKey returns a new AddressPubKeyHash from given public key

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) Hash160

func (a *AddressPubKeyHash) Hash160() *[ripemd160.Size]byte

Hash160 returns the underlying array of the pubkey hash. This can be useful when an array is more appropiate than a slice (for example, when used as map keys).

func (*AddressPubKeyHash) IsForPrefix

func (a *AddressPubKeyHash) IsForPrefix(prefix Bech32Prefix) bool

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

func (*AddressPubKeyHash) Prefix

func (a *AddressPubKeyHash) Prefix() Bech32Prefix

Prefix returns the prefix for this address

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, prefix Bech32Prefix) (*AddressScriptHash, error)

NewAddressScriptHash returns a new AddressScriptHash.

func NewAddressScriptHashFromHash

func NewAddressScriptHashFromHash(scriptHash []byte, prefix Bech32Prefix) (*AddressScriptHash, error)

NewAddressScriptHashFromHash returns a new AddressScriptHash. scriptHash must be 20 bytes.

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) Hash160

func (a *AddressScriptHash) Hash160() *[ripemd160.Size]byte

Hash160 returns the underlying array of the script hash. This can be useful when an array is more appropiate than a slice (for example, when used as map keys).

func (*AddressScriptHash) IsForPrefix

func (a *AddressScriptHash) IsForPrefix(prefix Bech32Prefix) bool

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

func (*AddressScriptHash) Prefix

func (a *AddressScriptHash) Prefix() Bech32Prefix

Prefix returns the prefix for this address

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 Amount

type Amount uint64

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

Example
package main

import (
	"fmt"

	"github.com/kaspanet/kaspad/util"
)

func main() {

	a := util.Amount(0)
	fmt.Println("Zero Sompi:", a)

	a = util.Amount(1e8)
	fmt.Println("100,000,000 Sompi:", a)

	a = util.Amount(1e5)
	fmt.Println("100,000 Sompi:", a)
}
Output:

Zero Sompi: 0 KAS
100,000,000 Sompi: 1 KAS
100,000 Sompi: 0.001 KAS
Example (UnitConversions)
package main

import (
	"fmt"

	"github.com/kaspanet/kaspad/util"
)

func main() {
	amount := util.Amount(44433322211100)

	fmt.Println("Sompi to kKAS:", amount.Format(util.AmountKiloKAS))
	fmt.Println("Sompi to KAS:", amount)
	fmt.Println("Sompi to MilliKAS:", amount.Format(util.AmountMilliKAS))
	fmt.Println("Sompi to MicroKAS:", amount.Format(util.AmountMicroKAS))
	fmt.Println("Sompi to Sompi:", amount.Format(util.AmountSompi))

}
Output:

Sompi to kKAS: 444.333222111 kKAS
Sompi to KAS: 444333.222111 KAS
Sompi to MilliKAS: 444333222.111 mKAS
Sompi to MicroKAS: 444333222111 μKAS
Sompi to Sompi: 44433322211100 Sompi

func NewAmount

func NewAmount(f float64) (Amount, error)

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

NewAmount is for specifically for converting KAS to Sompi. For creating a new Amount with an int64 value which denotes a quantity of Sompi, do a simple type conversion from type int64 to Amount.

Example
package main

import (
	"fmt"
	"math"

	"github.com/kaspanet/kaspad/util"
)

func main() {
	amountOne, err := util.NewAmount(1)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(amountOne) //Output 1

	amountFraction, err := util.NewAmount(0.01234567)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(amountFraction) //Output 2

	amountZero, err := util.NewAmount(0)
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(amountZero) //Output 3

	amountNaN, err := util.NewAmount(math.NaN())
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(amountNaN) //Output 4

}
Output:

1 KAS
0.01234567 KAS
0 KAS
invalid kaspa amount

func (Amount) Format

func (a Amount) Format(u AmountUnit) string

Format formats a monetary amount counted in kaspa 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 "Sompi" 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 kaspa (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 AmountKAS.

func (Amount) ToKAS

func (a Amount) ToKAS() float64

ToKAS is the equivalent of calling ToUnit with AmountKAS.

func (Amount) ToUnit

func (a Amount) ToUnit(u AmountUnit) float64

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

type AmountUnit

type AmountUnit int

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

const (
	AmountMegaKAS  AmountUnit = 6
	AmountKiloKAS  AmountUnit = 3
	AmountKAS      AmountUnit = 0
	AmountMilliKAS AmountUnit = -3
	AmountMicroKAS AmountUnit = -6
	AmountSompi    AmountUnit = -8
)

These constants define various units used when describing a kaspa 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 "Sompi" for the base unit. For all unrecognized units, "1eN KAS" is returned, where N is the AmountUnit.

type Bech32Prefix

type Bech32Prefix int

Bech32Prefix is the human-readable prefix for a Bech32 address.

const (
	// Unknown/Erroneous prefix
	Bech32PrefixUnknown Bech32Prefix = iota

	// Prefix for the main network.
	Bech32PrefixKaspa

	// Prefix for the dev network.
	Bech32PrefixKaspaDev

	// Prefix for the regression test network.
	Bech32PrefixKaspaReg

	// Prefix for the test network.
	Bech32PrefixKaspaTest

	// Prefix for the simulation network.
	Bech32PrefixKaspaSim
)

Constants that define Bech32 address prefixes. Every network is assigned a unique prefix.

func ParsePrefix

func ParsePrefix(prefixString string) (Bech32Prefix, error)

ParsePrefix attempts to parse a Bech32 address prefix.

func (Bech32Prefix) String

func (prefix Bech32Prefix) String() string

Converts from Bech32 address prefixes to their string values

type Block

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

Block defines a kaspa 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 *appmessage.MsgBlock) *Block

NewBlock returns a new instance of a kaspa block given an underlying appmessage.MsgBlock. See Block.

func NewBlockFromBlockAndBytes

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

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

func NewBlockFromBytes

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

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

func NewBlockFromReader

func NewBlockFromReader(r io.Reader) (*Block, error)

NewBlockFromReader returns a new instance of a kaspa block given a Reader to deserialize the block. See Block.

func (*Block) BlueScore

func (b *Block) BlueScore() (uint64, error)

BlueScore returns this block's blue score.

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 appmessage.MsgBlock, however it caches the result so subsequent calls are more efficient.

func (*Block) CoinbaseTransaction

func (b *Block) CoinbaseTransaction() *Tx

CoinbaseTransaction returns this block's coinbase transaction

func (*Block) Hash

func (b *Block) Hash() *daghash.Hash

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

func (*Block) IsGenesis

func (b *Block) IsGenesis() bool

IsGenesis returns whether or not this block is the genesis block.

func (*Block) MsgBlock

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

MsgBlock returns the underlying appmessage.MsgBlock for the Block.

func (*Block) Timestamp

func (b *Block) Timestamp() mstime.Time

Timestamp returns this block's timestamp

func (*Block) Transactions

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

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

func (*Block) Tx

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

Tx returns a wrapped transaction (util.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 (appmessage.MsgTx) from the underlying appmessage.MsgBlock, however the wrapped transaction has some helpful properties such as caching the hash so subsequent calls are more efficient.

func (*Block) TxHash

func (b *Block) TxHash(txNum int) (*daghash.Hash, error)

TxHash 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 TxHash on the underlying appmessage.MsgTx, however it caches the result so subsequent calls are more efficient.

func (*Block) TxLoc

func (b *Block) TxLoc() ([]appmessage.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.

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 Tx

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

Tx defines a kaspa 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 *appmessage.MsgTx) *Tx

NewTx returns a new instance of a kaspa transaction given an underlying appmessage.MsgTx. See Tx.

func NewTxFromBytes

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

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

func NewTxFromReader

func NewTxFromReader(r io.Reader) (*Tx, error)

NewTxFromReader returns a new instance of a kaspa transaction given a Reader to deserialize the transaction. See Tx.

func (*Tx) Hash

func (t *Tx) Hash() *daghash.Hash

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

func (*Tx) ID

func (t *Tx) ID() *daghash.TxID

ID returns the id of the transaction. This is equivalent to calling TxID on the underlying appmessage.MsgTx, however it caches the result so subsequent calls are more efficient.

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) IsCoinBase

func (t *Tx) IsCoinBase() bool

IsCoinBase determines whether or not a transaction is a coinbase. A coinbase is a special transaction created by miners that has no inputs. This is represented in the block dag by a transaction with a single input that has a previous output transaction index set to the maximum value along with a zero hash.

func (*Tx) MsgTx

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

MsgTx returns the underlying appmessage.MsgTx for the transaction.

func (*Tx) SetIndex

func (t *Tx) SetIndex(index int)

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

Directories

Path Synopsis
Package bech32 provides a Go implementation of the bech32 format.
Package bech32 provides a Go implementation of the bech32 format.
Package daghash provides abstracted hash functionality.
Package daghash provides abstracted hash functionality.
Package txsort provides the transaction sorting compatible with BIP 69.
Package txsort provides the transaction sorting compatible with BIP 69.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL