Skip to content

Commit

Permalink
add more documentation and small refactor
Browse files Browse the repository at this point in the history
  • Loading branch information
@Alesfatalis
Alesfatalis committed Mar 24, 2024
1 parent 0e53e03 commit d86a373
Show file tree
Hide file tree
Showing 13 changed files with 176 additions and 97 deletions.
13 changes: 8 additions & 5 deletions address.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,26 +12,29 @@ import (
type networkPrefix uint8

const (
// MainnetPrefix is the network prefix used in mainnet address encoding.
// MainnetPrefix is the network prefix used in mainnet address encoding
MainnetPrefix networkPrefix = 0

// TestnetPrefix is the network prefix used in testnet address encoding.
// TestnetPrefix is the network prefix used in testnet address encoding
TestnetPrefix = 16
)

type addressTypePrefix uint8

const (
P2PkPrefix addressTypePrefix = 1
// P2PkPrefix 0x01 - Pay-to-PublicKey(P2PK) address
P2PkPrefix addressTypePrefix = 1
// Pay2ShPrefix 0x02 - Pay-to-Script-Hash(P2SH)
Pay2ShPrefix addressTypePrefix = 2
Pay2SPrefix addressTypePrefix = 3
// Pay2SPrefix 0x03 - Pay-to-Script(P2S)
Pay2SPrefix addressTypePrefix = 3
)

type Address interface {
// Base58 converts an Address to a base58 string using the provided networkPrefix.
Base58(prefix networkPrefix) string

// TypePrefix returns the networkPrefix for the address.
// TypePrefix returns the addressTypePrefix for the Address.
// 0x01 - Pay-to-PublicKey(P2PK) address.
// 0x02 - Pay-to-Script-Hash(P2SH).
// 0x03 - Pay-to-Script(P2S).
Expand Down
119 changes: 80 additions & 39 deletions box.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,15 +12,23 @@ import (
type nonMandatoryRegisterId uint8

const (
// R4 id for the non-mandatory R4 register
R4 nonMandatoryRegisterId = 4
// R5 id for the non-mandatory R5 register
R5 nonMandatoryRegisterId = 5
// R6 id for the non-mandatory R6 register
R6 nonMandatoryRegisterId = 6
// R7 id for the non-mandatory R7 register
R7 nonMandatoryRegisterId = 7
// R8 id for the non-mandatory R8 register
R8 nonMandatoryRegisterId = 8
// R9 id for the non-mandatory R9 register
R9 nonMandatoryRegisterId = 9
)

// BoxId (32-byte digest)
type BoxId interface {
// Base16 returns the BoxId as base16 encoded string
Base16() string
}

Expand Down Expand Up @@ -65,7 +73,9 @@ func finalizeBoxId(b *boxId) {
C.ergo_lib_box_id_delete(b.p)
}

// BoxValue in nanoERGs with bound checks
type BoxValue interface {
// Int64 returns BoxValue value as int64
Int64() int64
pointer() C.BoxValuePtr
}
Expand All @@ -79,6 +89,7 @@ func newBoxValue(b *boxValue) BoxValue {
return b
}

// NewBoxValue creates a BoxValue from int64
func NewBoxValue(value int64) (BoxValue, error) {
var p C.BoxValuePtr

Expand Down Expand Up @@ -106,7 +117,9 @@ func finalizeBoxValue(b *boxValue) {
C.ergo_lib_box_value_delete(b.p)
}

func GetSafeUserMinBoxValue() BoxValue {
// SafeUserMinBoxValue returns recommended (safe) minimal BoxValue to use in case box size estimation is unavailable.
// Allows box size upto 2777 bytes with current min box value per byte of 360 nanoERGs
func SafeUserMinBoxValue() BoxValue {
var p C.BoxValuePtr
C.ergo_lib_box_value_safe_user_min(&p)

Expand All @@ -115,11 +128,13 @@ func GetSafeUserMinBoxValue() BoxValue {
return newBoxValue(b)
}

func GetUnitsPerErgo() int64 {
// UnitsPerErgo returns number of units inside one ERGO (i.e. one ERG using nano ERG representation)
func UnitsPerErgo() int64 {
units := C.ergo_lib_box_value_units_per_ergo()
return int64(units)
}

// SumOfBoxValues creates a new BoxValue which is the sum of the arguments, throwing error if value is out of bounds
func SumOfBoxValues(boxValue0 BoxValue, boxValue1 BoxValue) (BoxValue, error) {
var p C.BoxValuePtr
errPtr := C.ergo_lib_box_value_sum_of(boxValue0.pointer(), boxValue1.pointer(), &p)
Expand All @@ -136,16 +151,16 @@ func SumOfBoxValues(boxValue0 BoxValue, boxValue1 BoxValue) (BoxValue, error) {
// BoxCandidate contains the same fields as Box except for transaction id and index, that will be calculated
// after full transaction formation. Use BoxCandidateBuilder to create an instance
type BoxCandidate interface {
// GetRegisterValue returns value (Constant) stored in the register or nil if the register is empty
GetRegisterValue(registerId nonMandatoryRegisterId) (Constant, error)
// GetCreationHeight returns the creation height of the BoxCandidate
GetCreationHeight() uint32
// GetTokens returns the ergo Tokens for the BoxCandidate
GetTokens() Tokens
// GetTree returns the ergo Tree for the BoxCandidate
GetTree() Tree
// GetBoxValue returns the BoxValue of the BoxCandidate
GetBoxValue() BoxValue
// RegisterValue returns value (Constant) stored in the register or nil if the register is empty
RegisterValue(registerId nonMandatoryRegisterId) (Constant, error)
// CreationHeight returns the creation height of the BoxCandidate
CreationHeight() uint32
// Tokens returns the ergo Tokens for the BoxCandidate
Tokens() Tokens
// Tree returns the ergo Tree for the BoxCandidate
Tree() Tree
// BoxValue returns the BoxValue of the BoxCandidate
BoxValue() BoxValue
pointer() C.ErgoBoxCandidatePtr
}

Expand All @@ -158,7 +173,7 @@ func newBoxCandidate(b *boxCandidate) BoxCandidate {
return b
}

func (b *boxCandidate) GetRegisterValue(registerId nonMandatoryRegisterId) (Constant, error) {
func (b *boxCandidate) RegisterValue(registerId nonMandatoryRegisterId) (Constant, error) {
var p C.ConstantPtr
rId := C.uchar(registerId)

Expand All @@ -175,12 +190,12 @@ func (b *boxCandidate) GetRegisterValue(registerId nonMandatoryRegisterId) (Cons
return nil, nil
}

func (b *boxCandidate) GetCreationHeight() uint32 {
func (b *boxCandidate) CreationHeight() uint32 {
height := C.ergo_lib_ergo_box_candidate_creation_height(b.p)
return uint32(height)
}

func (b *boxCandidate) GetTokens() Tokens {
func (b *boxCandidate) Tokens() Tokens {
var p C.TokensPtr

C.ergo_lib_ergo_box_candidate_tokens(b.p, &p)
Expand All @@ -190,7 +205,7 @@ func (b *boxCandidate) GetTokens() Tokens {
return newTokens(t)
}

func (b *boxCandidate) GetTree() Tree {
func (b *boxCandidate) Tree() Tree {
var p C.ErgoTreePtr

C.ergo_lib_ergo_box_candidate_ergo_tree(b.p, &p)
Expand All @@ -200,7 +215,7 @@ func (b *boxCandidate) GetTree() Tree {
return newTree(t)
}

func (b *boxCandidate) GetBoxValue() BoxValue {
func (b *boxCandidate) BoxValue() BoxValue {
var p C.BoxValuePtr

C.ergo_lib_ergo_box_candidate_box_value(b.p, &p)
Expand All @@ -221,18 +236,18 @@ func finalizeBoxCandidate(b *boxCandidate) {
// Box that is taking part in some transaction on the chain Differs with BoxCandidate
// by added transaction id and an index in the input of that transaction
type Box interface {
// GetBoxId returns the BoxId of the Box
GetBoxId() BoxId
// GetRegisterValue returns value (Constant) stored in the register or nil if the register is empty
GetRegisterValue(registerId nonMandatoryRegisterId) (Constant, error)
// GetCreationHeight returns the creation height of the Box
GetCreationHeight() uint32
// GetTokens returns the ergo Tokens for the Box
GetTokens() Tokens
// GetTree returns the ergo Tree for the Box
GetTree() Tree
// GetBoxValue returns the BoxValue of the Box
GetBoxValue() BoxValue
// BoxId returns the BoxId of the Box
BoxId() BoxId
// RegisterValue returns value (Constant) stored in the register or nil if the register is empty
RegisterValue(registerId nonMandatoryRegisterId) (Constant, error)
// CreationHeight returns the creation height of the Box
CreationHeight() uint32
// Tokens returns the ergo Tokens for the Box
Tokens() Tokens
// Tree returns the ergo Tree for the Box
Tree() Tree
// BoxValue returns the BoxValue of the Box
BoxValue() BoxValue
// Json returns json representation of Box as string (compatible with Ergo Node/Explorer API, numbers are encoded as numbers)
Json() (string, error)
// JsonEIP12 returns json representation of Box as string according to EIP-12 https://github.com/ergoplatform/eips/pull/23
Expand All @@ -249,6 +264,12 @@ func newBox(b *box) Box {
return b
}

// NewBox creates a new Box from provided parameters:
// boxValue - amount of money associated with the box
// creationHeight - height when a transaction containing the box is created.
// contract - guarding contract(Contract), which should be evaluated to true in order to open(spend) this box
// txId - transaction id in which this box was "created" (participated in outputs)
// index - index (in outputs) in the transaction
func NewBox(boxValue BoxValue, creationHeight uint32, contract Contract, txId TxId, index uint16, tokens Tokens) (Box, error) {
var p C.ErgoBoxPtr

Expand All @@ -263,6 +284,7 @@ func NewBox(boxValue BoxValue, creationHeight uint32, contract Contract, txId Tx
return newBox(b), nil
}

// NewBoxFromJson parse Box from JSON. Supports Ergo Node/Explorer API and box values and token amount encoded as strings.
func NewBoxFromJson(json string) (Box, error) {
boxJsonStr := C.CString(json)
defer C.free(unsafe.Pointer(boxJsonStr))
Expand All @@ -280,7 +302,7 @@ func NewBoxFromJson(json string) (Box, error) {
return newBox(b), nil
}

func (b *box) GetBoxId() BoxId {
func (b *box) BoxId() BoxId {
var p C.BoxIdPtr

C.ergo_lib_ergo_box_id(b.p, &p)
Expand All @@ -290,7 +312,7 @@ func (b *box) GetBoxId() BoxId {
return newBoxId(bi)
}

func (b *box) GetRegisterValue(registerId nonMandatoryRegisterId) (Constant, error) {
func (b *box) RegisterValue(registerId nonMandatoryRegisterId) (Constant, error) {
var p C.ConstantPtr
rId := C.uchar(registerId)

Expand All @@ -307,12 +329,12 @@ func (b *box) GetRegisterValue(registerId nonMandatoryRegisterId) (Constant, err
return nil, nil
}

func (b *box) GetCreationHeight() uint32 {
func (b *box) CreationHeight() uint32 {
height := C.ergo_lib_ergo_box_creation_height(b.p)
return uint32(height)
}

func (b *box) GetTokens() Tokens {
func (b *box) Tokens() Tokens {
var p C.TokensPtr
C.ergo_lib_ergo_box_tokens(b.p, &p)

Expand All @@ -321,7 +343,7 @@ func (b *box) GetTokens() Tokens {
return newTokens(t)
}

func (b *box) GetTree() Tree {
func (b *box) Tree() Tree {
var p C.ErgoTreePtr
C.ergo_lib_ergo_box_ergo_tree(b.p, &p)

Expand All @@ -330,7 +352,7 @@ func (b *box) GetTree() Tree {
return newTree(t)
}

func (b *box) GetBoxValue() BoxValue {
func (b *box) BoxValue() BoxValue {
var p C.BoxValuePtr
C.ergo_lib_ergo_box_value(b.p, &p)

Expand Down Expand Up @@ -379,9 +401,12 @@ func finalizeBox(b *box) {
C.ergo_lib_ergo_box_delete(b.p)
}

// BoxAssetsData is a pair of value and tokens for a box
type BoxAssetsData interface {
GetBoxValue() BoxValue
GetTokens() Tokens
// BoxValue returns the BoxValue of the BoxAssetsData
BoxValue() BoxValue
// Tokens returns the Tokens of the BoxAssetsData
Tokens() Tokens
pointer() C.ErgoBoxAssetsDataPtr
}

Expand All @@ -394,6 +419,7 @@ func newBoxAssetsData(b *boxAssetsData) BoxAssetsData {
return b
}

// NewBoxAssetsData creates a new BoxAssetsData from the supplied BoxValue and Tokens
func NewBoxAssetsData(boxValue BoxValue, tokens Tokens) BoxAssetsData {
var p C.ErgoBoxAssetsDataPtr
C.ergo_lib_ergo_box_assets_data_new(boxValue.pointer(), tokens.pointer(), &p)
Expand All @@ -403,7 +429,7 @@ func NewBoxAssetsData(boxValue BoxValue, tokens Tokens) BoxAssetsData {
return newBoxAssetsData(b)
}

func (b *boxAssetsData) GetBoxValue() BoxValue {
func (b *boxAssetsData) BoxValue() BoxValue {
var p C.BoxValuePtr
C.ergo_lib_ergo_box_assets_data_value(b.p, &p)

Expand All @@ -412,7 +438,7 @@ func (b *boxAssetsData) GetBoxValue() BoxValue {
return newBoxValue(bv)
}

func (b *boxAssetsData) GetTokens() Tokens {
func (b *boxAssetsData) Tokens() Tokens {
var p C.TokensPtr
C.ergo_lib_ergo_box_assets_data_tokens(b.p, &p)

Expand All @@ -429,9 +455,13 @@ func finalizeBoxAssetsData(b *boxAssetsData) {
C.ergo_lib_ergo_box_assets_data_delete(b.p)
}

// BoxAssetsDataList is an ordered collection of BoxAssetsData
type BoxAssetsDataList interface {
// Len returns the length of the collection
Len() uint32
// Get returns the BoxAssetsData at the provided index if it exists
Get(index uint32) (BoxAssetsData, error)
// Add adds provided BoxAssetsData to the end of the collection
Add(boxAssetsData BoxAssetsData)
}

Expand All @@ -444,6 +474,7 @@ func newBoxAssetsDataList(b *boxAssetsDataList) BoxAssetsDataList {
return b
}

// NewBoxAssetsDataList creates an empty BoxAssetsDataList
func NewBoxAssetsDataList() BoxAssetsDataList {
var p C.ErgoBoxAssetsDataListPtr
C.ergo_lib_ergo_box_assets_data_list_new(&p)
Expand Down Expand Up @@ -483,9 +514,13 @@ func finalizeBoxAssetsDataList(b *boxAssetsDataList) {
C.ergo_lib_ergo_box_assets_data_list_delete(b.p)
}

// BoxCandidates is an ordered collection of BoxCandidate
type BoxCandidates interface {
// Len returns the length of the collection
Len() uint32
// Get returns the BoxCandidate at the provided index if it exists
Get(index uint32) (BoxCandidate, error)
// Add adds provided BoxCandidate to the end of the collection
Add(boxCandidate BoxCandidate)
}

Expand All @@ -498,6 +533,7 @@ func newBoxCandidates(b *boxCandidates) BoxCandidates {
return b
}

// NewBoxCandidates creates an empty BoxCandidates collection
func NewBoxCandidates() BoxCandidates {
var p C.ErgoBoxCandidatesPtr
C.ergo_lib_ergo_box_candidates_new(&p)
Expand Down Expand Up @@ -537,9 +573,13 @@ func finalizeBoxCandidates(b *boxCandidates) {
C.ergo_lib_ergo_box_candidates_delete(b.p)
}

// Boxes an ordered collection of Box
type Boxes interface {
// Len returns the length of the collection
Len() uint32
// Get returns the Box at the provided index if it exists
Get(index uint32) (Box, error)
// Add adds provided Box to the end of the collection
Add(box Box)
}

Expand All @@ -552,6 +592,7 @@ func newBoxes(b *boxes) Boxes {
return b
}

// NewBoxes creates an empty Boxes collection
func NewBoxes() Boxes {
var p C.ErgoBoxesPtr
C.ergo_lib_ergo_boxes_new(&p)
Expand Down
Loading

0 comments on commit d86a373

Please sign in to comment.