abi

package
v0.5.0 Latest Latest
Warning

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

 Go to latest Published: Aug 22, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package abi provides Application Binary Interface (ABI) encoding and decoding functionality for Zenon Network embedded smart contracts.

The ABI package handles serialization and deserialization of contract calls, enabling interaction with protocol-level embedded contracts. This is primarily used internally by the embedded contract APIs but can be used directly for custom contract interactions.

Basic Concepts

Embedded contracts in Zenon Network use ABI encoding to:

  • Encode method calls into transaction data
  • Decode method parameters from transaction data
  • Serialize complex data structures

Contract Method Encoding

Encode a contract method call: 

// Define method parameters
params := []interface{}{
    "pillarName",
    big.NewInt(15000),
    types.ZnnTokenStandard,
}

// Encode method call
data, err := abi.EncodeMethod("Register", params...)
if err != nil {
    log.Fatal(err)
}

Contract Response Decoding

Decode contract response data: 

// Define expected return types
var result struct {
    Name   string
    Owner  types.Address
    Amount *big.Int
}

// Decode response
err := abi.DecodeResponse(responseData, &result)
if err != nil {
    log.Fatal(err)
}

Common Data Types

The ABI package handles encoding/decoding of:

  • Basic types: int8 through int256, uint8 through uint256, bool, string
  • Fixed bytes: bytes1 through bytes32
  • Big integers: *big.Int for large numbers
  • Addresses: types.Address
  • Token standards: types.ZenonTokenStandard
  • Hashes: types.Hash
  • Complex structures and arrays

Canonical Validation

Encoding requires exactly one value for each declared parameter. Signed and unsigned integers must fit their declared bit width, fixed-byte values must have exactly their declared length, and boolean inputs must have Go type bool. Decoding rejects integer words outside the declared width, non-zero fixed-byte padding, and boolean words other than canonical zero or one. These checks prevent silent truncation and ambiguous wire encodings before a contract call is sent.

Internal Usage

Most developers don't need to use the ABI package directly, as the embedded contract APIs handle encoding automatically: 

// High-level API (recommended)
template := client.PillarApi.Register(name, producerAddress, rewardAddress, ...)

// Under the hood, this uses:
// data := abi.EncodeMethod("Register", name, producerAddress, ...)
// template.Data = data

Advanced Usage

For custom contract interactions or debugging, you can use the ABI package directly: 

// Create custom contract call
contractAddress := types.ParseAddressPanic("z1qxemdeddedxxxxxxxxxxxxxxxxxxxxxxxxxxx")
data, _ := abi.EncodeMethod("CustomMethod", param1, param2)

template := &nom.AccountBlock{
    Address:       myAddress,
    ToAddress:     contractAddress,
    Data:          data,
    TokenStandard: types.ZnnTokenStandard,
    Amount:        big.NewInt(0),
}

For more information, see https://pkg.go.dev/github.com/0x3639/znn-sdk-go/abi

Index

Constants

View Source 
const (
	// MaxTypeNameLength is the longest type declaration GetType accepts.
	MaxTypeNameLength = 256
	// MaxArrayNesting is the maximum number of array dimensions GetType accepts.
	MaxArrayNesting = 8
	// MaxStaticArraySize is the largest static array dimension accepted.
	MaxStaticArraySize = 1 << 16
)

Limits applied by GetType to untrusted type declarations (CWE-674). Array parsing is recursive and re-slices the declaration at each dimension, so an unbounded declaration could force deep recursion and quadratic allocation.

View Source 
const (
	// EncodedSignLength is the length of the encoded function signature (4 bytes)
	EncodedSignLength = 4
)
View Source 
const (
	Int32Size = 32 // Size of encoded values in bytes
)

Constants

Variables

This section is empty.

Functions

func DecodeInt 

func DecodeInt(encoded []byte, offset int) (*big.Int, error)

DecodeInt decodes a signed integer from encoded bytes at offset

func DecodeList 

func DecodeList(params []Param, encoded []byte) ([]interface{}, error)

DecodeList decodes a list of encoded values according to parameter types

func DecodeUint 

func DecodeUint(encoded []byte, offset int) (*big.Int, error)

DecodeUint decodes an unsigned integer from encoded bytes at offset

func EncodeInt 

func EncodeInt(i int) []byte

EncodeInt encodes an int to 32 bytes

func EncodeIntBig 

func EncodeIntBig(bigInt *big.Int) []byte

EncodeIntBig encodes a big.Int to 32 bytes (signed, two's complement)

func EncodeUint 

func EncodeUint(i uint64) ([]byte, error)

EncodeUint encodes an unsigned int to 32 bytes

func EncodeUintBig 

func EncodeUintBig(bigInt *big.Int) ([]byte, error)

EncodeUintBig encodes a big.Int to 32 bytes (unsigned) Returns error if the value is negative

Types

type Abi 

type Abi struct {
	Entries []Entry
}

Abi represents a collection of ABI entries (functions, events)

func FromJson 

func FromJson(jsonStr string) (*Abi, error)

FromJson creates a new ABI container from JSON string

func NewAbi 

func NewAbi(entries []Entry) *Abi

NewAbi creates a new ABI container from a list of entries

func (*Abi) DecodeFunction 

func (a *Abi) DecodeFunction(encoded []byte) ([]interface{}, error)

DecodeFunction decodes a function call by matching signature

func (*Abi) EncodeFunction 

func (a *Abi) EncodeFunction(name string, args []interface{}) ([]byte, error)

EncodeFunction encodes a function call by name

type AbiFunction 

type AbiFunction struct {
	Entry
}

AbiFunction represents an ABI function entry

func NewAbiFunction 

func NewAbiFunction(name string, inputs []Param) *AbiFunction

NewAbiFunction creates a new ABI function

func (*AbiFunction) Decode 

func (af *AbiFunction) Decode(encoded []byte) ([]interface{}, error)

Decode decodes the encoded function call data (skipping the 4-byte signature)

func (*AbiFunction) Encode 

func (af *AbiFunction) Encode(args []interface{}) ([]byte, error)

Encode encodes the function call with signature and arguments

func (*AbiFunction) EncodeSignature 

func (af *AbiFunction) EncodeSignature() []byte

EncodeSignature returns the first 4 bytes of the signature hash

type AbiType 

type AbiType interface {
	GetName() string
	GetCanonicalName() string
	Encode(value interface{}) ([]byte, error)
	Decode(encoded []byte, offset int) (interface{}, error)
	GetFixedSize() int
	IsDynamicType() bool
}

AbiType is the interface that all ABI types must implement

func GetType 

func GetType(typeName string) (AbiType, error)

GetType creates an ABI type from a type name string

type AddressType 

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

AddressType represents Zenon address values (20 bytes, left-padded to 32)

func NewAddressType 

func NewAddressType() (*AddressType, error)

NewAddressType creates a new address type

func (*AddressType) Decode 

func (at *AddressType) Decode(encoded []byte, offset int) (interface{}, error)

Decode decodes an address value from encoded bytes at offset

func (*AddressType) Encode 

func (at *AddressType) Encode(value interface{}) ([]byte, error)

Encode encodes an address value to 32 bytes (20-byte address left-padded with 12 zero bytes)

func (*AddressType) GetCanonicalName 

func (bt *AddressType) GetCanonicalName() string

func (*AddressType) GetFixedSize 

func (bt *AddressType) GetFixedSize() int

func (*AddressType) GetName 

func (bt *AddressType) GetName() string

func (*AddressType) IsDynamicType 

func (bt *AddressType) IsDynamicType() bool

type ArrayType 

type ArrayType interface {
	AbiType
	GetElementType() AbiType
	EncodeTuple(values []interface{}) ([]byte, error)
	DecodeTuple(encoded []byte, origOffset int, length int) ([]interface{}, error)
	EncodeList(values []interface{}) ([]byte, error)
}

ArrayType is an interface for array types (static and dynamic)

type BoolType 

type BoolType struct {
	IntType
}

BoolType represents boolean values (encoded as uint256: 0 or 1)

func NewBoolType 

func NewBoolType() (*BoolType, error)

NewBoolType creates a new boolean type

func (*BoolType) Decode 

func (bt *BoolType) Decode(encoded []byte, offset int) (interface{}, error)

Decode decodes a canonical boolean word (0 = false, 1 = true)

func (*BoolType) Encode 

func (bt *BoolType) Encode(value interface{}) ([]byte, error)

Encode encodes a boolean value as 0 (false) or 1 (true)

func (*BoolType) GetFixedSize 

func (bt *BoolType) GetFixedSize() int

func (*BoolType) GetName 

func (bt *BoolType) GetName() string

func (*BoolType) IsDynamicType 

func (bt *BoolType) IsDynamicType() bool

type Bytes32Type 

type Bytes32Type = FixedBytesType

Bytes32Type is retained as an alias for compatibility with callers that used the original bytes32-only implementation. Use NewFixedBytesType for any bytes1 through bytes32 declaration.

func NewBytes32Type 

func NewBytes32Type(name string) (*Bytes32Type, error)

NewBytes32Type creates a fixed-byte ABI type.

This compatibility constructor historically accepted only "bytes32". It now delegates to NewFixedBytesType, so callers may use it with bytes1 through bytes32. Invalid names return an error.

type BytesType 

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

BytesType represents dynamic byte arrays (length-prefixed, padded to 32-byte multiples)

func NewBytesType 

func NewBytesType() (*BytesType, error)

NewBytesType creates a new bytes type

func (*BytesType) Decode 

func (bt *BytesType) Decode(encoded []byte, offset int) (interface{}, error)

Decode decodes dynamic bytes from encoded data at offset

func (*BytesType) Encode 

func (bt *BytesType) Encode(value interface{}) ([]byte, error)

Encode encodes dynamic bytes with length prefix and padding Format: [32 bytes: length][data padded to 32-byte multiple]

func (*BytesType) GetCanonicalName 

func (bt *BytesType) GetCanonicalName() string

func (*BytesType) GetFixedSize 

func (bt *BytesType) GetFixedSize() int

func (*BytesType) GetName 

func (bt *BytesType) GetName() string

func (*BytesType) IsDynamicType 

func (bt *BytesType) IsDynamicType() bool

IsDynamicType returns true for BytesType

type DynamicArrayType 

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

DynamicArrayType represents dynamic arrays like uint256[]

func NewDynamicArrayType 

func NewDynamicArrayType(typeName string) (*DynamicArrayType, error)

NewDynamicArrayType creates a new dynamic array type typeName should be in format "elementType[]" e.g. "uint256[]"

func (*DynamicArrayType) Decode 

func (dat *DynamicArrayType) Decode(encoded []byte, origOffset int) (interface{}, error)

func (*DynamicArrayType) DecodeTuple 

func (dat *DynamicArrayType) DecodeTuple(encoded []byte, origOffset int, length int) ([]interface{}, error)

DecodeTuple decodes array elements from a tuple encoding

func (*DynamicArrayType) Encode 

func (dat *DynamicArrayType) Encode(value interface{}) ([]byte, error)

Encode encodes a dynamic array

func (*DynamicArrayType) EncodeList 

func (dat *DynamicArrayType) EncodeList(values []interface{}) ([]byte, error)

EncodeList encodes a list of values as a dynamic array with length prefix

func (*DynamicArrayType) EncodeTuple 

func (dat *DynamicArrayType) EncodeTuple(values []interface{}) ([]byte, error)

EncodeTuple encodes array elements as a tuple

func (*DynamicArrayType) GetCanonicalName 

func (dat *DynamicArrayType) GetCanonicalName() string

GetCanonicalName returns the canonical type name

func (*DynamicArrayType) GetElementType 

func (dat *DynamicArrayType) GetElementType() AbiType

GetElementType returns the element type

func (*DynamicArrayType) GetFixedSize 

func (dat *DynamicArrayType) GetFixedSize() int

GetFixedSize returns 0 as dynamic arrays don't have a fixed size

func (*DynamicArrayType) GetName 

func (bt *DynamicArrayType) GetName() string

func (*DynamicArrayType) IsDynamicType 

func (dat *DynamicArrayType) IsDynamicType() bool

IsDynamicType returns true as dynamic arrays are dynamic types

type Entry 

type Entry struct {
	Name   string
	Inputs []Param
	Type   TypeEnum
}

Entry represents an ABI entry (function, event, etc.)

func NewEntry 

func NewEntry(name string, inputs []Param, entryType TypeEnum) *Entry

NewEntry creates a new ABI entry

func (*Entry) EncodeArguments 

func (e *Entry) EncodeArguments(args []interface{}) ([]byte, error)

EncodeArguments encodes function arguments with proper head/tail separation for dynamic types

func (*Entry) EncodeSignature 

func (e *Entry) EncodeSignature() []byte

EncodeSignature returns the full signature hash

func (*Entry) FingerprintSignature 

func (e *Entry) FingerprintSignature() []byte

FingerprintSignature returns the SHA3-256 hash of the signature

func (*Entry) FormatSignature 

func (e *Entry) FormatSignature() string

FormatSignature formats the entry signature as "name(type1,type2,...)"

type FixedBytesType added in v0.2.0 

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

FixedBytesType represents a fixed bytes1 through bytes32 ABI value.

Values must contain exactly the declared number of bytes. They are encoded left-aligned in a 32-byte ABI word with zero padding on the right.

func NewFixedBytesType added in v0.2.0 

func NewFixedBytesType(name string) (*FixedBytesType, error)

NewFixedBytesType creates a fixed bytes1 through bytes32 ABI type.

Parameters:

  • name: Canonical fixed-byte name, such as "bytes4" or "bytes32".

NewFixedBytesType returns the parsed type or an error when the width is missing, non-numeric, or outside the inclusive range 1 through 32.

Example: 

typeObject, err := NewFixedBytesType("bytes4")
encoded, err := typeObject.Encode([]byte{0xde, 0xad, 0xbe, 0xef})

Note: Fixed bytes are distinct from dynamic BytesType values and require an exact input length.

func (*FixedBytesType) Decode added in v0.2.0 

func (bt *FixedBytesType) Decode(encoded []byte, offset int) (interface{}, error)

Decode decodes a fixed byte value and rejects non-zero right padding.

func (*FixedBytesType) Encode added in v0.2.0 

func (bt *FixedBytesType) Encode(value interface{}) ([]byte, error)

Encode encodes an exact-length fixed byte value into one 32-byte ABI word.

func (*FixedBytesType) GetCanonicalName added in v0.2.0 

func (bt *FixedBytesType) GetCanonicalName() string

func (*FixedBytesType) GetFixedSize added in v0.2.0 

func (bt *FixedBytesType) GetFixedSize() int

func (*FixedBytesType) GetName added in v0.2.0 

func (bt *FixedBytesType) GetName() string

func (*FixedBytesType) IsDynamicType added in v0.2.0 

func (bt *FixedBytesType) IsDynamicType() bool

type FunctionType 

type FunctionType struct {
	Bytes32Type
}

FunctionType represents a 24-byte function selector (extends Bytes32Type)

func NewFunctionType 

func NewFunctionType() (*FunctionType, error)

NewFunctionType creates a new function type

func (*FunctionType) Decode 

func (ft *FunctionType) Decode(encoded []byte, offset int) (interface{}, error)

Decode is unimplemented for FunctionType

func (*FunctionType) Encode 

func (ft *FunctionType) Encode(value interface{}) ([]byte, error)

Encode encodes a 24-byte function selector The input must be exactly 24 bytes, which will be padded to 32 bytes

type HashType 

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

HashType represents hash values (32 bytes, no padding needed)

func NewHashType 

func NewHashType() (*HashType, error)

NewHashType creates a new hash type

func (*HashType) Decode 

func (ht *HashType) Decode(encoded []byte, offset int) (interface{}, error)

Decode decodes a hash value from encoded bytes at offset

func (*HashType) Encode 

func (ht *HashType) Encode(value interface{}) ([]byte, error)

Encode encodes a hash value to 32 bytes

func (*HashType) GetCanonicalName 

func (bt *HashType) GetCanonicalName() string

func (*HashType) GetFixedSize 

func (bt *HashType) GetFixedSize() int

func (*HashType) GetName 

func (bt *HashType) GetName() string

func (*HashType) IsDynamicType 

func (bt *HashType) IsDynamicType() bool

type IntType 

type IntType struct {
	NumericType
	// contains filtered or unexported fields
}

IntType represents signed integer types (int8 to int256)

func NewIntType 

func NewIntType(name string) (*IntType, error)

NewIntType creates a new signed integer type

func (*IntType) Decode 

func (it *IntType) Decode(encoded []byte, offset int) (interface{}, error)

Decode decodes a signed integer value

func (*IntType) Encode 

func (it *IntType) Encode(value interface{}) ([]byte, error)

Encode encodes a signed integer value

func (*IntType) GetCanonicalName 

func (it *IntType) GetCanonicalName() string

GetCanonicalName returns the canonical name (int defaults to int256)

func (*IntType) GetFixedSize 

func (bt *IntType) GetFixedSize() int

func (*IntType) GetName 

func (bt *IntType) GetName() string

func (*IntType) IsDynamicType 

func (bt *IntType) IsDynamicType() bool

type NumericType 

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

NumericType is the base for all numeric types (int, uint)

func (*NumericType) EncodeInternal 

func (nt *NumericType) EncodeInternal(value interface{}) (*big.Int, error)

EncodeInternal converts various value types to big.Int

func (*NumericType) GetCanonicalName 

func (bt *NumericType) GetCanonicalName() string

func (*NumericType) GetFixedSize 

func (bt *NumericType) GetFixedSize() int

func (*NumericType) GetName 

func (bt *NumericType) GetName() string

func (*NumericType) IsDynamicType 

func (bt *NumericType) IsDynamicType() bool

type Param 

type Param struct {
	Indexed bool
	Name    string
	Type    AbiType
}

Param represents a function parameter

func NewParam 

func NewParam(name string, typeName string) (*Param, error)

NewParam creates a new parameter

type StaticArrayType 

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

StaticArrayType represents fixed-size arrays like uint256[3]

func NewStaticArrayType 

func NewStaticArrayType(typeName string) (*StaticArrayType, error)

NewStaticArrayType creates a new static array type typeName should be in format "elementType[size]" e.g. "uint256[3]"

func (*StaticArrayType) Decode 

func (sat *StaticArrayType) Decode(encoded []byte, offset int) (interface{}, error)

Decode decodes a static array from encoded data

func (*StaticArrayType) DecodeTuple 

func (sat *StaticArrayType) DecodeTuple(encoded []byte, origOffset int, length int) ([]interface{}, error)

DecodeTuple decodes array elements from a tuple encoding

func (*StaticArrayType) Encode 

func (sat *StaticArrayType) Encode(value interface{}) ([]byte, error)

Encode encodes a static array

func (*StaticArrayType) EncodeList 

func (sat *StaticArrayType) EncodeList(values []interface{}) ([]byte, error)

EncodeList encodes a list of values as a static array

func (*StaticArrayType) EncodeTuple 

func (sat *StaticArrayType) EncodeTuple(values []interface{}) ([]byte, error)

EncodeTuple encodes array elements as a tuple

func (*StaticArrayType) GetCanonicalName 

func (sat *StaticArrayType) GetCanonicalName() string

GetCanonicalName returns the canonical type name

func (*StaticArrayType) GetElementType 

func (sat *StaticArrayType) GetElementType() AbiType

GetElementType returns the element type

func (*StaticArrayType) GetFixedSize 

func (sat *StaticArrayType) GetFixedSize() int

GetFixedSize returns the total size (element size * count)

func (*StaticArrayType) GetName 

func (bt *StaticArrayType) GetName() string

func (*StaticArrayType) IsDynamicType 

func (bt *StaticArrayType) IsDynamicType() bool

type StringType 

type StringType struct {
	BytesType
}

StringType represents UTF-8 encoded strings (extends BytesType)

func NewStringType 

func NewStringType() (*StringType, error)

NewStringType creates a new string type

func (*StringType) Decode 

func (st *StringType) Decode(encoded []byte, offset int) (interface{}, error)

Decode decodes a string from encoded bytes at offset

func (*StringType) Encode 

func (st *StringType) Encode(value interface{}) ([]byte, error)

Encode encodes a string as UTF-8 bytes using BytesType encoding

func (*StringType) GetCanonicalName 

func (bt *StringType) GetCanonicalName() string

func (*StringType) GetFixedSize 

func (st *StringType) GetFixedSize() int

GetFixedSize returns 0 as string is a dynamic type

func (*StringType) GetName 

func (bt *StringType) GetName() string

type TokenStandardType 

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

TokenStandardType represents Zenon token standard values (10 bytes, left-padded to 32)

func NewTokenStandardType 

func NewTokenStandardType() (*TokenStandardType, error)

NewTokenStandardType creates a new token standard type

func (*TokenStandardType) Decode 

func (tst *TokenStandardType) Decode(encoded []byte, offset int) (interface{}, error)

Decode decodes a token standard value from encoded bytes at offset

func (*TokenStandardType) Encode 

func (tst *TokenStandardType) Encode(value interface{}) ([]byte, error)

Encode encodes a token standard value to 32 bytes (10-byte ZTS left-padded with 22 zero bytes)

func (*TokenStandardType) GetCanonicalName 

func (bt *TokenStandardType) GetCanonicalName() string

func (*TokenStandardType) GetFixedSize 

func (bt *TokenStandardType) GetFixedSize() int

func (*TokenStandardType) GetName 

func (bt *TokenStandardType) GetName() string

func (*TokenStandardType) IsDynamicType 

func (bt *TokenStandardType) IsDynamicType() bool

type TypeEnum 

type TypeEnum int

TypeEnum represents the type of an ABI entry 

const (
	// Function represents a function entry
	Function TypeEnum = iota
)

func (TypeEnum) String 

func (te TypeEnum) String() string

type UnsignedIntType 

type UnsignedIntType struct {
	NumericType
	// contains filtered or unexported fields
}

UnsignedIntType represents unsigned integer types (uint8 to uint256)

func NewUnsignedIntType 

func NewUnsignedIntType(name string) (*UnsignedIntType, error)

NewUnsignedIntType creates a new unsigned integer type

func (*UnsignedIntType) Decode 

func (uit *UnsignedIntType) Decode(encoded []byte, offset int) (interface{}, error)

Decode decodes an unsigned integer value

func (*UnsignedIntType) Encode 

func (uit *UnsignedIntType) Encode(value interface{}) ([]byte, error)

Encode encodes an unsigned integer value

func (*UnsignedIntType) GetCanonicalName 

func (uit *UnsignedIntType) GetCanonicalName() string

GetCanonicalName returns the canonical name (uint defaults to uint256)

func (*UnsignedIntType) GetFixedSize 

func (bt *UnsignedIntType) GetFixedSize() int

func (*UnsignedIntType) GetName 

func (bt *UnsignedIntType) GetName() string

func (*UnsignedIntType) IsDynamicType 

func (bt *UnsignedIntType) IsDynamicType() bool

Source Files

View all Source files

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.