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 ¶
- Constants
- Variables
- func AppDataDir(appName string, roaming bool) string
- func BigToCompact(n *big.Int) uint32
- func CalcWork(bits uint32) *big.Int
- func CompactToBig(compact uint32) *big.Int
- func CompactToBigWithDestination(compact uint32, destination *big.Int)
- func FastLog2Floor(n uint64) uint8
- func Hash160(buf []byte) []byte
- func NewTLSCertPair(organization string, validUntil time.Time, extraHosts []string) (cert, key []byte, err error)
- func SearchSlice(sliceLength int, searchFunc func(int) bool) (foundIndex int, ok bool)
- func ToCamelCase(str string) string
- type Address
- type AddressPubKeyHash
- func (a *AddressPubKeyHash) EncodeAddress() string
- func (a *AddressPubKeyHash) Hash160() *[ripemd160.Size]byte
- func (a *AddressPubKeyHash) IsForPrefix(prefix Bech32Prefix) bool
- func (a *AddressPubKeyHash) Prefix() Bech32Prefix
- func (a *AddressPubKeyHash) ScriptAddress() []byte
- func (a *AddressPubKeyHash) String() string
- type AddressScriptHash
- func (a *AddressScriptHash) EncodeAddress() string
- func (a *AddressScriptHash) Hash160() *[ripemd160.Size]byte
- func (a *AddressScriptHash) IsForPrefix(prefix Bech32Prefix) bool
- func (a *AddressScriptHash) Prefix() Bech32Prefix
- func (a *AddressScriptHash) ScriptAddress() []byte
- func (a *AddressScriptHash) String() string
- type Amount
- type AmountUnit
- type Bech32Prefix
- type Block
- func (b *Block) BlueScore() (uint64, error)
- func (b *Block) Bytes() ([]byte, error)
- func (b *Block) CoinbaseTransaction() *Tx
- func (b *Block) Hash() *daghash.Hash
- func (b *Block) IsGenesis() bool
- func (b *Block) MsgBlock() *appmessage.MsgBlock
- func (b *Block) Timestamp() mstime.Time
- func (b *Block) Transactions() []*Tx
- func (b *Block) Tx(txNum int) (*Tx, error)
- func (b *Block) TxHash(txNum int) (*daghash.Hash, error)
- func (b *Block) TxLoc() ([]appmessage.TxLoc, error)
- type OutOfRangeError
- type Tx
Examples ¶
Constants ¶
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 )
const (
// CoinbaseTransactionIndex is the index of the coinbase transaction in every block
CoinbaseTransactionIndex = 0
)
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
FastLog2Floor calculates and returns floor(log2(x)) in a constant 5 steps.
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 ¶
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 ¶
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 ¶
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 ¶
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) 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 ¶
NewBlockFromBytes returns a new instance of a kaspa block given the serialized bytes. See Block.
func NewBlockFromReader ¶
NewBlockFromReader returns a new instance of a kaspa block given a Reader to deserialize the block. See Block.
func (*Block) Bytes ¶
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 ¶
CoinbaseTransaction returns this block's coinbase transaction
func (*Block) 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) MsgBlock ¶
func (b *Block) MsgBlock() *appmessage.MsgBlock
MsgBlock returns the underlying appmessage.MsgBlock for the Block.
func (*Block) Transactions ¶
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 ¶
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 ¶
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.
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 ¶
NewTxFromBytes returns a new instance of a kaspa transaction given the serialized bytes. See Tx.
func NewTxFromReader ¶
NewTxFromReader returns a new instance of a kaspa transaction given a Reader to deserialize the transaction. See Tx.
func (*Tx) 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 ¶
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 ¶
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 ¶
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.
Source Files ¶
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. |