util

package
v0.0.0-...-6e9d532 Latest Latest
Warning

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

 Go to latest Published: Aug 24, 2023 License: ISC Imports: 12 Imported by: 0

README

util

ISC License GoDoc

Package util provides c4ex-specific convenience functions and types.

Documentation

Overview

Package util provides c4ex-specific convenience functions and types.

Block Overview

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

To decode/encode an address: 

addrString := "c4ex:qqj9fg59mptxkr9j0y53j5mwurcmda5mtza9n6v9pm9uj8h0wgk6uma5pvumr"
defaultPrefix := util.Bech32PrefixC4ex
addr, err := util.DecodeAddress(addrString, defaultPrefix)
if err != nil {
	fmt.Println(err)
	return
}
fmt.Println(addr.EncodeAddress())

Index

Examples

Constants

View Source 
const PublicKeySize = 32

PublicKeySize is the public key size for a schnorr public key

View Source 
const PublicKeySizeECDSA = 33

PublicKeySizeECDSA is the public key size for an ECDSA public key

Variables

View Source 
var (
	// 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 AppDir 

func AppDir(appName string, roaming bool) string

AppDir 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 := AppDir("myapp", false)
 POSIX (Linux/BSD): ~/.myapp
 Mac OS: $HOME/Library/Application Support/Myapp
 Windows: %LOCALAPPDATA%\Myapp
 Plan 9: $home/myapp

func HashBlake2b 

func HashBlake2b(buf []byte) []byte

HashBlake2b calculates the hash blake2b(b).

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 P2PK 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 c4ex 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) 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 AddressPublicKey 

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

AddressPublicKey is an Address for a pay-to-pubkey (P2PK) transaction.

func NewAddressPublicKey 

func NewAddressPublicKey(publicKey []byte, prefix Bech32Prefix) (*AddressPublicKey, error)

NewAddressPublicKey returns a new AddressPublicKey. publicKey must be 32 bytes.

func (*AddressPublicKey) EncodeAddress 

func (a *AddressPublicKey) EncodeAddress() string

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

func (*AddressPublicKey) IsForPrefix 

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

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

func (*AddressPublicKey) Prefix 

func (a *AddressPublicKey) Prefix() Bech32Prefix

Prefix returns the prefix for this address

func (*AddressPublicKey) ScriptAddress 

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

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

func (*AddressPublicKey) String 

func (a *AddressPublicKey) String() string

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

type AddressPublicKeyECDSA 

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

AddressPublicKeyECDSA is an Address for a pay-to-pubkey (P2PK) ECDSA transaction.

func NewAddressPublicKeyECDSA 

func NewAddressPublicKeyECDSA(publicKey []byte, prefix Bech32Prefix) (*AddressPublicKeyECDSA, error)

NewAddressPublicKeyECDSA returns a new AddressPublicKeyECDSA. publicKey must be 33 bytes.

func (*AddressPublicKeyECDSA) EncodeAddress 

func (a *AddressPublicKeyECDSA) EncodeAddress() string

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

func (*AddressPublicKeyECDSA) IsForPrefix 

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

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

func (*AddressPublicKeyECDSA) Prefix 

func (a *AddressPublicKeyECDSA) Prefix() Bech32Prefix

Prefix returns the prefix for this address

func (*AddressPublicKeyECDSA) ScriptAddress 

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

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

func (*AddressPublicKeyECDSA) String 

func (a *AddressPublicKeyECDSA) String() string

String returns a human-readable string for the pay-to-pubkey 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-publicKey (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) HashBlake2b 

func (a *AddressScriptHash) HashBlake2b() *[blake2b.Size256]byte

HashBlake2b 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 c4ex 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 c4ex monetary unit (colloquially referred to as a `Sompi'). A single Amount is equal to 1e-8 of a c4ex.

Example 
package main

import (
	"fmt"

	"github.com/c4ei/c4exd/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 C4X
100,000,000 Sompi: 1 C4X
100,000 Sompi: 0.001 C4X
Example (UnitConversions) 
package main

import (
	"fmt"

	"github.com/c4ei/c4exd/util"
)

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

	fmt.Println("Sompi to kC4X:", amount.Format(util.AmountKiloC4X))
	fmt.Println("Sompi to C4X:", amount)
	fmt.Println("Sompi to MilliC4X:", amount.Format(util.AmountMilliC4X))
	fmt.Println("Sompi to MicroC4X:", amount.Format(util.AmountMicroC4X))
	fmt.Println("Sompi to Sompi:", amount.Format(util.AmountSompi))

}

Output:

Sompi to kC4X: 444.333222111 kC4X
Sompi to C4X: 444333.222111 C4X
Sompi to MilliC4X: 444333222.111 mC4X
Sompi to MicroC4X: 444333222111 μC4X
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 c4ex. NewAmount errors if f is NaN or +-Infinity, but does not check that the amount is within the total amount of c4ex producible as f may not refer to an amount at a single moment in time.

NewAmount is for specifically for converting C4X 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. TODO: Refactor NewAmount. When amounts are more than 1e9 C4X, the precision can be higher than one sompi (1e9 and 1e9+1e-8 will result as the same number)

Example 
package main

import (
	"fmt"
	"math"

	"github.com/c4ei/c4exd/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 C4X
0.01234567 C4X
0 C4X
invalid c4ex amount

func (Amount) Format 

func (a Amount) Format(u AmountUnit) string

Format formats a monetary amount counted in c4ex 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 c4ex (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 AmountC4X.

func (Amount) ToC4X 

func (a Amount) ToC4X() float64

ToC4X is the equivalent of calling ToUnit with AmountC4X.

func (Amount) ToUnit 

func (a Amount) ToUnit(u AmountUnit) float64

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

type AmountUnit 

type AmountUnit int

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

const (
	AmountMegaC4X  AmountUnit = 6
	AmountKiloC4X  AmountUnit = 3
	AmountC4X      AmountUnit = 0
	AmountMilliC4X AmountUnit = -3
	AmountMicroC4X AmountUnit = -6
	AmountSompi    AmountUnit = -8
)

These constants define various units used when describing a c4ex 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 C4X" 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.
	Bech32PrefixC4ex

	// Prefix for the dev network.
	Bech32PrefixC4exDev

	// Prefix for the test network.
	Bech32PrefixC4exTest

	// Prefix for the simulation network.
	Bech32PrefixC4exSim
)

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

Source Files

View all 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.

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.