stackitem

package
v0.96.1 Latest Latest
Warning

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

Go to latest
Published: Jul 23, 2021 License: MIT Imports: 17 Imported by: 53

Documentation

Index

Constants

View Source
const (
	// MaxBigIntegerSizeBits is the maximum size of BigInt item in bits.
	MaxBigIntegerSizeBits = 32 * 8
	// MaxSize is the maximum item size allowed in the VM.
	MaxSize = 1024 * 1024
	// MaxComparableNumOfItems is the maximum number of items that can be compared for structs.
	MaxComparableNumOfItems = MaxDeserialized
	// MaxClonableNumOfItems is the maximum number of items that can be cloned in structs.
	MaxClonableNumOfItems = MaxDeserialized
	// MaxByteArrayComparableSize is the maximum allowed length of ByteArray for Equals method.
	// It is set to be the maximum uint16 value.
	MaxByteArrayComparableSize = math.MaxUint16
	// MaxKeySize is the maximum size of map key.
	MaxKeySize = 64
)
View Source
const MaxAllowedInteger = 2<<53 - 1

MaxAllowedInteger is the maximum integer allowed to be encoded.

View Source
const MaxDeserialized = 2048

MaxDeserialized is the maximum number one deserialized item can contain (including itself).

View Source
const MaxJSONDepth = 10

MaxJSONDepth is the maximum allowed nesting level of encoded/decoded JSON.

Variables

View Source
var (
	// ErrInvalidConversion is returned on attempt to make an incorrect
	// conversion between item types.
	ErrInvalidConversion = errors.New("invalid conversion")

	// ErrTooBig is returned when item exceeds some size constraints like
	// maximum allowed integer value of number of elements in array. It
	// can also be returned by serialization functions if resulting
	// value exceeds MaxSize.
	ErrTooBig = errors.New("too big")
)
View Source
var ErrInvalidType = errors.New("invalid type")

ErrInvalidType is returned on attempts to deserialize some unknown item type.

View Source
var ErrInvalidValue = errors.New("invalid value")

ErrInvalidValue is returned when item value doesn't fit some constraints during serialization or deserialization.

View Source
var ErrRecursive = errors.New("recursive item")

ErrRecursive is returned on attempts to serialize some recursive stack item (like array including an item with reference to the same array).

View Source
var ErrTooDeep = errors.New("too deep")

ErrTooDeep is returned when JSON encoder/decoder goes beyond MaxJSONDepth in its processing.

View Source
var ErrUnserializable = errors.New("unserializable")

ErrUnserializable is returned on attempt to serialize some item that can't be serialized (like Interop item or Pointer).

Functions

func DeserializeConvertible added in v0.96.0

func DeserializeConvertible(data []byte, conv Convertible) error

DeserializeConvertible deserializes Convertible from a slice of bytes.

func EncodeBinary added in v0.95.4

func EncodeBinary(item Item, w *io.BinWriter)

EncodeBinary encodes given Item into the given BinWriter. It's similar to io.Serializable's EncodeBinary, but works with Item interface.

func EncodeBinaryProtected added in v0.95.4

func EncodeBinaryProtected(item Item, w *io.BinWriter)

EncodeBinaryProtected encodes given Item into the given BinWriter. It's similar to EncodeBinary but allows to encode interop items (only type, value is lost) and doesn't return any errors in w, instead if error (like recursive array) is encountered it just writes special InvalidT type of element to w.

func IsValidMapKey

func IsValidMapKey(key Item) error

IsValidMapKey checks whether it's possible to use given Item as a Map key.

func Serialize added in v0.95.4

func Serialize(item Item) ([]byte, error)

Serialize encodes given Item into the byte slice.

func SerializeConvertible added in v0.96.0

func SerializeConvertible(conv Convertible) ([]byte, error)

SerializeConvertible serializes Convertible into a slice of bytes.

func ToJSON

func ToJSON(item Item) ([]byte, error)

ToJSON encodes Item to JSON. It behaves as following:

ByteArray -> base64 string
BigInteger -> number
Bool -> bool
Null -> null
Array, Struct -> array
Map -> map with keys as UTF-8 bytes

func ToJSONWithTypes added in v0.91.0

func ToJSONWithTypes(item Item) ([]byte, error)

ToJSONWithTypes serializes any stackitem to JSON in a lossless way.

func ToString added in v0.91.0

func ToString(item Item) (string, error)

ToString converts Item to string if it is a valid UTF-8.

Types

type Array

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

Array represents a new Array object.

func NewArray

func NewArray(items []Item) *Array

NewArray returns a new Array object.

func (*Array) Append

func (i *Array) Append(item Item)

Append adds Item at the end of Array value.

func (*Array) Clear

func (i *Array) Clear()

Clear removes all elements from Array item value.

func (*Array) Convert

func (i *Array) Convert(typ Type) (Item, error)

Convert implements Item interface.

func (*Array) Dup

func (i *Array) Dup() Item

Dup implements Item interface.

func (*Array) Equals

func (i *Array) Equals(s Item) bool

Equals implements Item interface.

func (*Array) Len

func (i *Array) Len() int

Len returns length of Array value.

func (*Array) MarshalJSON

func (i *Array) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface.

func (*Array) Remove

func (i *Array) Remove(pos int)

Remove removes element at `pos` index from Array value. It will panics on bad index.

func (*Array) String

func (i *Array) String() string

func (*Array) TryBool added in v0.92.0

func (i *Array) TryBool() (bool, error)

TryBool implements Item interface.

func (*Array) TryBytes

func (i *Array) TryBytes() ([]byte, error)

TryBytes implements Item interface.

func (*Array) TryInteger

func (i *Array) TryInteger() (*big.Int, error)

TryInteger implements Item interface.

func (*Array) Type

func (i *Array) Type() Type

Type implements Item interface.

func (*Array) Value

func (i *Array) Value() interface{}

Value implements Item interface.

type BigInteger

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

BigInteger represents a big integer on the stack.

func NewBigInteger

func NewBigInteger(value *big.Int) *BigInteger

NewBigInteger returns an new BigInteger object.

func (*BigInteger) Bytes

func (i *BigInteger) Bytes() []byte

Bytes converts i to a slice of bytes.

func (*BigInteger) Convert

func (i *BigInteger) Convert(typ Type) (Item, error)

Convert implements Item interface.

func (*BigInteger) Dup

func (i *BigInteger) Dup() Item

Dup implements Item interface.

func (*BigInteger) Equals

func (i *BigInteger) Equals(s Item) bool

Equals implements Item interface.

func (*BigInteger) MarshalJSON

func (i *BigInteger) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface.

func (*BigInteger) String

func (i *BigInteger) String() string

func (*BigInteger) TryBool added in v0.92.0

func (i *BigInteger) TryBool() (bool, error)

TryBool implements Item interface.

func (*BigInteger) TryBytes

func (i *BigInteger) TryBytes() ([]byte, error)

TryBytes implements Item interface.

func (*BigInteger) TryInteger

func (i *BigInteger) TryInteger() (*big.Int, error)

TryInteger implements Item interface.

func (*BigInteger) Type

func (i *BigInteger) Type() Type

Type implements Item interface.

func (*BigInteger) Value

func (i *BigInteger) Value() interface{}

Value implements Item interface.

type Bool

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

Bool represents a boolean Item.

func NewBool

func NewBool(val bool) *Bool

NewBool returns an new Bool object.

func (*Bool) Bytes

func (i *Bool) Bytes() []byte

Bytes converts Bool to bytes.

func (*Bool) Convert

func (i *Bool) Convert(typ Type) (Item, error)

Convert implements Item interface.

func (*Bool) Dup

func (i *Bool) Dup() Item

Dup implements Item interface.

func (*Bool) Equals

func (i *Bool) Equals(s Item) bool

Equals implements Item interface.

func (*Bool) MarshalJSON

func (i *Bool) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface.

func (*Bool) String

func (i *Bool) String() string

func (*Bool) TryBool added in v0.92.0

func (i *Bool) TryBool() (bool, error)

TryBool implements Item interface.

func (*Bool) TryBytes

func (i *Bool) TryBytes() ([]byte, error)

TryBytes implements Item interface.

func (*Bool) TryInteger

func (i *Bool) TryInteger() (*big.Int, error)

TryInteger implements Item interface.

func (*Bool) Type

func (i *Bool) Type() Type

Type implements Item interface.

func (*Bool) Value

func (i *Bool) Value() interface{}

Value implements Item interface.

type Buffer

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

Buffer represents represents Buffer stack item.

func NewBuffer

func NewBuffer(b []byte) *Buffer

NewBuffer returns a new Buffer object.

func (*Buffer) Convert

func (i *Buffer) Convert(typ Type) (Item, error)

Convert implements Item interface.

func (*Buffer) Dup

func (i *Buffer) Dup() Item

Dup implements Item interface.

func (*Buffer) Equals

func (i *Buffer) Equals(s Item) bool

Equals implements Item interface.

func (*Buffer) Len

func (i *Buffer) Len() int

Len returns length of Buffer value.

func (*Buffer) MarshalJSON

func (i *Buffer) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface.

func (*Buffer) String

func (i *Buffer) String() string

String implements fmt.Stringer interface.

func (*Buffer) TryBool added in v0.92.0

func (i *Buffer) TryBool() (bool, error)

TryBool implements Item interface.

func (*Buffer) TryBytes

func (i *Buffer) TryBytes() ([]byte, error)

TryBytes implements Item interface.

func (*Buffer) TryInteger

func (i *Buffer) TryInteger() (*big.Int, error)

TryInteger implements Item interface.

func (*Buffer) Type

func (i *Buffer) Type() Type

Type implements Item interface.

func (*Buffer) Value

func (i *Buffer) Value() interface{}

Value implements Item interface.

type ByteArray

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

ByteArray represents a byte array on the stack.

func NewByteArray

func NewByteArray(b []byte) *ByteArray

NewByteArray returns an new ByteArray object.

func (*ByteArray) Convert

func (i *ByteArray) Convert(typ Type) (Item, error)

Convert implements Item interface.

func (*ByteArray) Dup

func (i *ByteArray) Dup() Item

Dup implements Item interface.

func (*ByteArray) Equals

func (i *ByteArray) Equals(s Item) bool

Equals implements Item interface.

func (*ByteArray) MarshalJSON

func (i *ByteArray) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface.

func (*ByteArray) String

func (i *ByteArray) String() string

func (*ByteArray) TryBool added in v0.92.0

func (i *ByteArray) TryBool() (bool, error)

TryBool implements Item interface.

func (*ByteArray) TryBytes

func (i *ByteArray) TryBytes() ([]byte, error)

TryBytes implements Item interface.

func (*ByteArray) TryInteger

func (i *ByteArray) TryInteger() (*big.Int, error)

TryInteger implements Item interface.

func (*ByteArray) Type

func (i *ByteArray) Type() Type

Type implements Item interface.

func (*ByteArray) Value

func (i *ByteArray) Value() interface{}

Value implements Item interface.

type Convertible added in v0.96.0

type Convertible interface {
	ToStackItem() (Item, error)
	FromStackItem(Item) error
}

Convertible is something that can be converted to/from Item.

type Interop

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

Interop represents interop data on the stack.

func NewInterop

func NewInterop(value interface{}) *Interop

NewInterop returns new Interop object.

func (*Interop) Convert

func (i *Interop) Convert(typ Type) (Item, error)

Convert implements Item interface.

func (*Interop) Dup

func (i *Interop) Dup() Item

Dup implements Item interface.

func (*Interop) Equals

func (i *Interop) Equals(s Item) bool

Equals implements Item interface.

func (*Interop) MarshalJSON

func (i *Interop) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface.

func (*Interop) String

func (i *Interop) String() string

String implements stringer interface.

func (*Interop) TryBool added in v0.92.0

func (i *Interop) TryBool() (bool, error)

TryBool implements Item interface.

func (*Interop) TryBytes

func (i *Interop) TryBytes() ([]byte, error)

TryBytes implements Item interface.

func (*Interop) TryInteger

func (i *Interop) TryInteger() (*big.Int, error)

TryInteger implements Item interface.

func (*Interop) Type

func (i *Interop) Type() Type

Type implements Item interface.

func (*Interop) Value

func (i *Interop) Value() interface{}

Value implements Item interface.

type Item

type Item interface {
	fmt.Stringer
	Value() interface{}
	// Dup duplicates current Item.
	Dup() Item
	// TryBool converts Item to a boolean value.
	TryBool() (bool, error)
	// TryBytes converts Item to a byte slice. If the underlying type is a
	// byte slice, it's returned as is without copying.
	TryBytes() ([]byte, error)
	// TryInteger converts Item to an integer.
	TryInteger() (*big.Int, error)
	// Equals checks if 2 StackItems are equal.
	Equals(s Item) bool
	// Type returns stack item type.
	Type() Type
	// Convert converts Item to another type.
	Convert(Type) (Item, error)
}

Item represents the "real" value that is pushed on the stack.

func DecodeBinary added in v0.95.4

func DecodeBinary(r *io.BinReader) Item

DecodeBinary decodes previously serialized Item from the given reader. It's similar to the io.Serializable's DecodeBinary(), but implemented as a function because Item itself is an interface. Caveat: always check reader's error value before using the returned Item.

func DecodeBinaryProtected added in v0.95.4

func DecodeBinaryProtected(r *io.BinReader) Item

DecodeBinaryProtected is similar to DecodeBinary but allows Interop and Invalid values to be present (making it symmetric to EncodeBinaryProtected).

func DeepCopy added in v0.91.0

func DeepCopy(item Item) Item

DeepCopy returns new deep copy of the provided item. Values of Interop items are not deeply copied. It does preserve duplicates only for non-primitive types.

func Deserialize added in v0.95.4

func Deserialize(data []byte) (Item, error)

Deserialize decodes Item from the given byte slice.

func FromJSON

func FromJSON(data []byte) (Item, error)

FromJSON decodes Item from JSON. It behaves as following:

string -> ByteArray from base64
number -> BigInteger
bool -> Bool
null -> Null
array -> Array
map -> Map, keys are UTF-8

func FromJSONWithTypes added in v0.91.0

func FromJSONWithTypes(data []byte) (Item, error)

FromJSONWithTypes deserializes an item from typed-json representation.

func Make

func Make(v interface{}) Item

Make tries to make appropriate stack item from provided value. It will panic if it's not possible.

type Map

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

Map represents Map object. It's ordered, so we use slice representation which should be fine for maps with less than 32 or so elements. Given that our VM has quite low limit of overall stack items, it should be good enough, but it can be extended with a real map for fast random access in the future if need be.

func NewMap

func NewMap() *Map

NewMap returns new Map object.

func NewMapWithValue

func NewMapWithValue(value []MapElement) *Map

NewMapWithValue returns new Map object filled with specified value.

func (*Map) Add

func (i *Map) Add(key, value Item)

Add adds key-value pair to the map.

func (*Map) Clear

func (i *Map) Clear()

Clear removes all elements from Map item value.

func (*Map) Convert

func (i *Map) Convert(typ Type) (Item, error)

Convert implements Item interface.

func (*Map) Drop

func (i *Map) Drop(index int)

Drop removes given index from the map (no bounds check done here).

func (*Map) Dup

func (i *Map) Dup() Item

Dup implements Item interface.

func (*Map) Equals

func (i *Map) Equals(s Item) bool

Equals implements Item interface.

func (*Map) Has

func (i *Map) Has(key Item) bool

Has checks if map has specified key.

func (*Map) Index

func (i *Map) Index(key Item) int

Index returns an index of the key in map.

func (*Map) Len

func (i *Map) Len() int

Len returns length of Map value.

func (*Map) String

func (i *Map) String() string

func (*Map) TryBool added in v0.92.0

func (i *Map) TryBool() (bool, error)

TryBool implements Item interface.

func (*Map) TryBytes

func (i *Map) TryBytes() ([]byte, error)

TryBytes implements Item interface.

func (*Map) TryInteger

func (i *Map) TryInteger() (*big.Int, error)

TryInteger implements Item interface.

func (*Map) Type

func (i *Map) Type() Type

Type implements Item interface.

func (*Map) Value

func (i *Map) Value() interface{}

Value implements Item interface.

type MapElement

type MapElement struct {
	Key   Item
	Value Item
}

MapElement is a key-value pair of StackItems.

type Null

type Null struct{}

Null represents null on the stack.

func (Null) Convert

func (i Null) Convert(typ Type) (Item, error)

Convert implements Item interface.

func (Null) Dup

func (i Null) Dup() Item

Dup implements Item interface. There is no need to perform a real copy here, as Null has no internal state.

func (Null) Equals

func (i Null) Equals(s Item) bool

Equals implements Item interface.

func (Null) String

func (i Null) String() string

String implements Item interface.

func (Null) TryBool added in v0.92.0

func (i Null) TryBool() (bool, error)

TryBool implements Item interface.

func (Null) TryBytes

func (i Null) TryBytes() ([]byte, error)

TryBytes implements Item interface.

func (Null) TryInteger

func (i Null) TryInteger() (*big.Int, error)

TryInteger implements Item interface.

func (Null) Type

func (i Null) Type() Type

Type implements Item interface.

func (Null) Value

func (i Null) Value() interface{}

Value implements Item interface.

type Pointer

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

Pointer represents VM-level instruction pointer.

func NewPointer

func NewPointer(pos int, script []byte) *Pointer

NewPointer returns new pointer on the specified position.

func NewPointerWithHash added in v0.92.0

func NewPointerWithHash(pos int, script []byte, h util.Uint160) *Pointer

NewPointerWithHash returns new pointer on the specified position of the specified script. It differs from NewPointer in that the script hash is being passed explicitly to save on hash calculcation. This hash is then being used for pointer comparisons.

func (*Pointer) Convert

func (p *Pointer) Convert(typ Type) (Item, error)

Convert implements Item interface.

func (*Pointer) Dup

func (p *Pointer) Dup() Item

Dup implements Item interface.

func (*Pointer) Equals

func (p *Pointer) Equals(s Item) bool

Equals implements Item interface.

func (*Pointer) Position

func (p *Pointer) Position() int

Position returns pointer item position.

func (*Pointer) ScriptHash

func (p *Pointer) ScriptHash() util.Uint160

ScriptHash returns pointer item hash.

func (*Pointer) String

func (p *Pointer) String() string

String implements Item interface.

func (*Pointer) TryBool added in v0.92.0

func (p *Pointer) TryBool() (bool, error)

TryBool implements Item interface.

func (*Pointer) TryBytes

func (p *Pointer) TryBytes() ([]byte, error)

TryBytes implements Item interface.

func (*Pointer) TryInteger

func (p *Pointer) TryInteger() (*big.Int, error)

TryInteger implements Item interface.

func (*Pointer) Type

func (p *Pointer) Type() Type

Type implements Item interface.

func (*Pointer) Value

func (p *Pointer) Value() interface{}

Value implements Item interface.

type Struct

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

Struct represents a struct on the stack.

func NewStruct

func NewStruct(items []Item) *Struct

NewStruct returns an new Struct object.

func (*Struct) Append

func (i *Struct) Append(item Item)

Append adds Item at the end of Struct value.

func (*Struct) Clear

func (i *Struct) Clear()

Clear removes all elements from Struct item value.

func (*Struct) Clone

func (i *Struct) Clone() (*Struct, error)

Clone returns a Struct with all Struct fields copied by value. Array fields are still copied by reference.

func (*Struct) Convert

func (i *Struct) Convert(typ Type) (Item, error)

Convert implements Item interface.

func (*Struct) Dup

func (i *Struct) Dup() Item

Dup implements Item interface.

func (*Struct) Equals

func (i *Struct) Equals(s Item) bool

Equals implements Item interface.

func (*Struct) Len

func (i *Struct) Len() int

Len returns length of Struct value.

func (*Struct) Remove

func (i *Struct) Remove(pos int)

Remove removes element at `pos` index from Struct value. It will panics on bad index.

func (*Struct) String

func (i *Struct) String() string

String implements Item interface.

func (*Struct) TryBool added in v0.92.0

func (i *Struct) TryBool() (bool, error)

TryBool implements Item interface.

func (*Struct) TryBytes

func (i *Struct) TryBytes() ([]byte, error)

TryBytes implements Item interface.

func (*Struct) TryInteger

func (i *Struct) TryInteger() (*big.Int, error)

TryInteger implements Item interface.

func (*Struct) Type

func (i *Struct) Type() Type

Type implements Item interface.

func (*Struct) Value

func (i *Struct) Value() interface{}

Value implements Item interface.

type Type

type Type byte

Type represents type of the stack item.

const (
	AnyT       Type = 0x00
	PointerT   Type = 0x10
	BooleanT   Type = 0x20
	IntegerT   Type = 0x21
	ByteArrayT Type = 0x28
	BufferT    Type = 0x30
	ArrayT     Type = 0x40
	StructT    Type = 0x41
	MapT       Type = 0x48
	InteropT   Type = 0x60
	InvalidT   Type = 0xFF
)

This block defines all known stack item types.

func FromString added in v0.91.0

func FromString(s string) (Type, error)

FromString returns stackitem type from string.

func (Type) IsValid

func (t Type) IsValid() bool

IsValid checks if s is a well defined stack item type.

func (Type) String

func (t Type) String() string

String implements fmt.Stringer interface.

Jump to

Keyboard shortcuts

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