abi

Documentation

Overview

Package abi provides utilities for interacting with contracts. There are 2 primary functionalities: - encoding - decoding All specifications of encoding and decoding adheres to Solidity's ABI specs: https://docs.soliditylang.org/en/latest/abi-spec.html

Index

• Constants
• Variables
• func AbiEncode(functionSig string, functionInputs []string) (string, error)
• func ConvertAddress(value string) (string, error)
• func ConvertBool(value string) (string, error)
• func ConvertByteSize(value string, byteType string) (string, error)
• func ConvertBytes(value string) (string, error)
• func ConvertInt(value string) (string, error)
• func ConvertString(value string) (string, error)
• func ConvertUint(value string) (string, error)
• func ExtractFunctionNameAndFunctionArgs(input string) (string, error)
• func HashFunctionSelector(functionSig string) (string, error)
• func ValidateStringIsQuoted(s string) string
• type Array
• type EncodedItem
• type FunctionArgType
  • func (fat FunctionArgType) EncodeInput(object Object) (EncodedItem, error)
  • func (fat FunctionArgType) IsStaticType() bool
• type FunctionSignature
  • func GetFunctionSignatureObject(functionSig string) (FunctionSignature, error)
  • func (fs *FunctionSignature) Encode(functionArguments []string) (string, error)
• type FunctionTupleType
• type Object
• type Tuple

Constants

const PlaceholderPointerLength = 64

This is the place holder length of a dynamic type, which is 64 string characters (32 bytes). This place holder just points to the location of the actual value of the dynamic type.

Variables

var (
	FunctionSignatureParser = participle.MustBuild[FunctionSignature](
		participle.Lexer(funcSigLexer),
	)
)

var (
	ObjectParser = participle.MustBuild[Object](
		participle.Lexer(objectLexer),
	)
)

Functions

func AbiEncode

func AbiEncode(functionSig string, functionInputs []string) (string, error)

AbiEncode Takes a function signature and function inputs and returns the encoded byte calldata

func ConvertAddress

func ConvertAddress(value string) (string, error)

ConvertAddress converts an address input to the address encoding which is left padded with 0s until 32 bytes (or 64 characters for the string hex). Example: 0x00...00<address>

func ConvertBool

func ConvertBool(value string) (string, error)

ConvertBool converts a string representation of "true" or "false" into a 32 byte hex encoding (0 or 1), left padded with 0s

func ConvertByteSize

func ConvertByteSize(value string, byteType string) (string, error)

ConvertByteSize converts a hex value to bytes<size> Eg. "0x123456", bytes3 returns 0x0123450000000000000000000000000000000000000000000000000000000000

func ConvertBytes

func ConvertBytes(value string) (string, error)

ConvertBytes returns bytes length + bytes hex encoding NOTE: this is similar to ConvertString but `value` is expected to be a hex input already

func ConvertInt

func ConvertInt(value string) (string, error)

ConvertInt converts an int input to the 32 byte hex encoding, left padded with 0s

func ConvertString

func ConvertString(value string) (string, error)

ConvertString returns hex string length + string hex encoding

func ConvertUint

func ConvertUint(value string) (string, error)

ConvertUint converts a uint input to the 32 byte hex encoding, left padded with 0s

func ExtractFunctionNameAndFunctionArgs

func ExtractFunctionNameAndFunctionArgs(input string) (string, error)

ExtractFunctionNameAndFunctionArgs takes any form of function input and return the first parenthesis encountered. Example: Input: "someFuncName(uint256,(string,string)[][],(uint256,(bool,string)))(uint,string)" Returns: "someFuncName(uint256,(string,string)[][],(uint256,(bool,string)))"

func HashFunctionSelector

func HashFunctionSelector(functionSig string) (string, error)

HashFunctionSelector returns a function selectors keccak256 hashed encoding

func ValidateStringIsQuoted

func ValidateStringIsQuoted(s string) string

ValidateStringIsQuoted takes a string and validates that it's surrounded by quotations. Example: - `abc` returns `"abc"` - `"abc"` returns `"abc"`

Types

type Array

type Array struct {
	Elements []Object `parser:"@@ (',' @@)*"`
}

type EncodedItem

type EncodedItem struct {
	Head string
	Tail string
}

EncodedItem is a data structured used to represent the differences between static and dynamic types. Static types are encoded in-place (as a head) and dynamic types are encoded at a separately allocated location after the current block (i.e., tail). See more here: https://docs.soliditylang.org/en/latest/abi-spec.html#formal-specification-of-the-encoding

type FunctionArgType

type FunctionArgType struct {
	Type  string             `parser:"(@Ident"`
	Tuple *FunctionTupleType `parser:"| @@)"`
	Array []string           `parser:"@Bracket*"`
}

FunctionArgType represents a single argument which can be a base type, a tuple, or an array. At a high level, this lexer parses all types as (@Ident | @@)@Brackets, where: - @Ident is a base type - @@ is a recursive call to represent each item of the tuple - @Bracket indicates the nested level of the array

func (FunctionArgType) EncodeInput

func (fat FunctionArgType) EncodeInput(object Object) (EncodedItem, error)

EncodeInput encodes an object with the mapped function arg type.

func (FunctionArgType) IsStaticType

func (fat FunctionArgType) IsStaticType() bool

IsStaticType returns true if the function arg type is static. According to [solidity docs](https://docs.soliditylang.org/en/latest/abi-spec.html#formal-specification-of-the-encoding), ``` Definition: The following types are called “dynamic”: - bytes - string - T[] for any T - T[k] for any dynamic T and any k >= 0 - (T1,...,Tk) if Ti is dynamic for some 1 <= i <= k

All other types are called “static”. ```

so these are static: - uint<M>: unsigned integer type of M bits, 0 < M <= 256, M % 8 == 0. e.g. uint32, uint8, uint256. - int<M>: two’s complement signed integer type of M bits, 0 < M <= 256, M % 8 == 0 - bool: equivalent to uint8 restricted to the values 0 and 1 - address - bytes<M>: binary type of M bytes, 0 < M <= 32 - (T1,...,Tk) if Ti is static for all 1 <= i <= k - T[k] for any static T and any k >= 0

type FunctionSignature

type FunctionSignature struct {
	FunctionName string             `parser:"@Ident"`
	FunctionArgs []*FunctionArgType `parser:"'(' @@* ( ',' @@ )* ')'"`
}

FunctionSignature Parser FunctionSignature represents the overall structure of a function signature.

func GetFunctionSignatureObject

func GetFunctionSignatureObject(functionSig string) (FunctionSignature, error)

GetFunctionSignatureObject returns the FunctionSignature representation of a given function signature string

func (*FunctionSignature) Encode

func (fs *FunctionSignature) Encode(functionArguments []string) (string, error)

Encode returns the string encoding of an Object Example: functionSignature := `getMultipliedAndAddNumber((uint256,bool,string[]))` functionSignatureInputs := []string{`(200, true, ["a","b"])`}

This is the representation of the function signature:

FunctionSignature{
  FunctionName: "getMultipliedAndAddNumber",
  FunctionArgs: []*main.FunctionArgType{
    {
      Tuple: &main.FunctionTupleType{
        Elements: []*main.FunctionArgType{
          {
            Type: "uint256",
          },
          {
            Type: "bool",
          },
          {
            Type: "string",
            Array: []string{
              "[]",
            },
          },
        },
      },
    },
  },
}

This is the object input type representation of a function argument input

Object{
  Tuple: main.Tuple{
    Elements: []main.Object{
      {
        Val: "200",
      },
      {
        Val: "true",
      },
      {
        Array: main.Array{
          Elements: []main.Object{
            {
              Stringval: "\"a\"",
            },
            {
              Stringval: "\"b\"",
            },
          },
        },
      },
    },
  },
}

From there, we traverse the function signature AST and the parsed object to encode each item, respectively.

type FunctionTupleType

type FunctionTupleType struct {
	Elements []*FunctionArgType `parser:"('(' @@ ( ',' @@ )* ')')"`
}

FunctionTupleType represents a tuple in the signature.

type Object

type Object struct {
	Val       string `parser:"@Ident"`
	Stringval string `parser:"| @String"` // NOTE: Strictly string values must be around quotations: "
	Tuple     Tuple  `parser:"| @@"`
	Array     Array  `parser:"| '[' @@* ']'"`
}

Function Argument Input Object Parser Object represents one Function argument object This adheres to the available inputs that Solidity functions can accept such as:

type Tuple

type Tuple struct {
	Elements []Object `parser:"('(' @@ (',' @@)* ')')"`
}