Documentation
¶
Overview ¶
Package abi implements the Ethereum ABI (Application Binary Interface).
The Ethereum ABI is strongly typed, known at compile time and static. This ABI will handle basic type casting; unsigned to signed and visa versa. It does not handle slice casting such as unsigned slice to signed slice. Bit size type casting is also handled. ints with a bit size of 32 will be properly cast to int256, etc.
Index ¶
- Constants
- Variables
- func ConvertType(in interface{}, proto interface{}) interface{}
- func MakeTopics(query ...[]interface{}) ([][]common.Hash, error)
- func ParseTopics(out interface{}, fields Arguments, topics []common.Hash) error
- func ParseTopicsIntoMap(out map[string]interface{}, fields Arguments, topics []common.Hash) error
- func ReadFixedBytes(t Type, word []byte) (interface{}, error)
- func ReadInteger(typ Type, b []byte) (interface{}, error)
- func ResolveNameConflict(rawName string, used func(string) bool) string
- func ToCamelCase(input string) string
- func UnpackRevert(data []byte) (string, error)
- type ABI
- func (abi *ABI) ErrorByID(sigdata [4]byte) (*Error, error)
- func (abi *ABI) EventByID(topic common.Hash) (*Event, error)
- func (abi *ABI) HasFallback() bool
- func (abi *ABI) HasReceive() bool
- func (abi *ABI) MethodById(sigdata []byte) (*Method, error)
- func (abi ABI) Pack(name string, args ...interface{}) ([]byte, error)
- func (abi *ABI) UnmarshalJSON(data []byte) error
- func (abi ABI) Unpack(name string, data []byte) ([]interface{}, error)
- func (abi ABI) UnpackIntoInterface(v interface{}, name string, data []byte) error
- func (abi ABI) UnpackIntoMap(v map[string]interface{}, name string, data []byte) (err error)
- type Argument
- type ArgumentMarshaling
- type Arguments
- func (arguments Arguments) Copy(v interface{}, values []interface{}) error
- func (arguments Arguments) NonIndexed() Arguments
- func (arguments Arguments) Pack(args ...interface{}) ([]byte, error)
- func (arguments Arguments) PackValues(args []interface{}) ([]byte, error)
- func (arguments Arguments) Unpack(data []byte) ([]interface{}, error)
- func (arguments Arguments) UnpackIntoMap(v map[string]interface{}, data []byte) error
- func (arguments Arguments) UnpackValues(data []byte) ([]interface{}, error)
- type Error
- type Event
- type FunctionType
- type Method
- type SelectorMarshaling
- type Type
Examples ¶
Constants ¶
const ( IntTy byte = iota UintTy BoolTy StringTy SliceTy ArrayTy TupleTy AddressTy FixedBytesTy BytesTy HashTy FixedPointTy FunctionTy )
Type enumerator
Variables ¶
var ( // MaxUint256 is the maximum value that can be represented by a uint256. MaxUint256 = new(big.Int).Sub(new(big.Int).Lsh(common.Big1, 256), common.Big1) // MaxInt256 is the maximum value that can be represented by a int256. MaxInt256 = new(big.Int).Sub(new(big.Int).Lsh(common.Big1, 255), common.Big1) )
Functions ¶
func ConvertType ¶ added in v1.9.23
func ConvertType(in interface{}, proto interface{}) interface{}
ConvertType converts an interface of a runtime type into a interface of the given type, e.g. turn this code:
var fields []reflect.StructField fields = append(fields, reflect.StructField{ Name: "X", Type: reflect.TypeOf(new(big.Int)), Tag: reflect.StructTag("json:\"" + "x" + "\""), }
into:
type TupleT struct { X *big.Int }
func MakeTopics ¶ added in v1.9.14
MakeTopics converts a filter query argument list into a filter topic set.
func ParseTopics ¶ added in v1.9.14
ParseTopics converts the indexed topic fields into actual log field values.
func ParseTopicsIntoMap ¶ added in v1.9.14
ParseTopicsIntoMap converts the indexed topic field-value pairs into map key-value pairs.
func ReadFixedBytes ¶ added in v1.9.10
ReadFixedBytes uses reflection to create a fixed array to be read from.
func ReadInteger ¶ added in v1.9.10
ReadInteger reads the integer based on its kind and returns the appropriate value.
func ResolveNameConflict ¶ added in v1.10.19
ResolveNameConflict returns the next available name for a given thing. This helper can be used for lots of purposes:
- In solidity function overloading is supported, this function can fix the name conflicts of overloaded functions.
- In golang binding generation, the parameter(in function, event, error, and struct definition) name will be converted to camelcase style which may eventually lead to name conflicts.
Name conflicts are mostly resolved by adding number suffix. e.g. if the abi contains Methods "send" and "send1", ResolveNameConflict would return "send2" for input "send".
func ToCamelCase ¶ added in v1.8.21
ToCamelCase converts an under-score string to a camel-case string
func UnpackRevert ¶ added in v1.9.14
UnpackRevert resolves the abi-encoded revert reason. According to the solidity spec https://solidity.readthedocs.io/en/latest/control-structures.html#revert, the provided revert reason is abi-encoded as if it were a call to a function `Error(string)`. So it's a special tool for it.
Types ¶
type ABI ¶
type ABI struct { Constructor Method Methods map[string]Method Events map[string]Event Errors map[string]Error // Additional "special" functions introduced in solidity v0.6.0. // It's separated from the original default fallback. Each contract // can only define one fallback and receive function. Fallback Method // Note it's also used to represent legacy fallback before v0.6.0 Receive Method }
The ABI holds information about a contract's context and available invokable methods. It will allow you to type check function calls and packs data accordingly.
func JSON ¶
JSON returns a parsed ABI interface and error if it failed.
Example ¶
const definition = `[{"constant":true,"inputs":[{"name":"","type":"address"}],"name":"isBar","outputs":[{"name":"","type":"bool"}],"type":"function"}]` abi, err := JSON(strings.NewReader(definition)) if err != nil { panic(err) } out, err := abi.Pack("isBar", common.HexToAddress("01")) if err != nil { panic(err) } fmt.Printf("%x\n", out)
Output: 1f2c40920000000000000000000000000000000000000000000000000000000000000001
func (*ABI) ErrorByID ¶ added in v1.12.0
ErrorByID looks up an error by the 4-byte id, returns nil if none found.
func (*ABI) EventByID ¶ added in v1.9.0
EventByID looks an event up by its topic hash in the ABI and returns nil if none found.
func (*ABI) HasFallback ¶ added in v1.9.13
HasFallback returns an indicator whether a fallback function is included.
func (*ABI) HasReceive ¶ added in v1.9.13
HasReceive returns an indicator whether a receive function is included.
func (*ABI) MethodById ¶ added in v1.8.0
MethodById looks up a method by the 4-byte id, returns nil if none found.
func (ABI) Pack ¶
Pack the given method name to conform the ABI. Method call's data will consist of method_id, args0, arg1, ... argN. Method id consists of 4 bytes and arguments are all 32 bytes. Method ids are created from the first 4 bytes of the hash of the methods string signature. (signature = baz(uint32,string32))
func (*ABI) UnmarshalJSON ¶
UnmarshalJSON implements json.Unmarshaler interface.
func (ABI) UnpackIntoInterface ¶ added in v1.9.23
UnpackIntoInterface unpacks the output in v according to the abi specification. It performs an additional copy. Please only use, if you want to unpack into a structure that does not strictly conform to the abi structure (e.g. has additional arguments)
type Argument ¶
Argument holds the name of the argument and the corresponding type. Types are used when packing and testing arguments.
func (*Argument) UnmarshalJSON ¶
UnmarshalJSON implements json.Unmarshaler interface.
type ArgumentMarshaling ¶ added in v1.8.21
type ArgumentMarshaling struct { Name string Type string InternalType string Components []ArgumentMarshaling Indexed bool }
type Arguments ¶ added in v1.8.0
type Arguments []Argument
func (Arguments) NonIndexed ¶ added in v1.8.2
NonIndexed returns the arguments with indexed arguments filtered out.
func (Arguments) PackValues ¶ added in v1.8.2
PackValues performs the operation Go format -> Hexdata. It is the semantic opposite of UnpackValues.
func (Arguments) UnpackIntoMap ¶ added in v1.9.0
UnpackIntoMap performs the operation hexdata -> mapping of argument name to argument value.
func (Arguments) UnpackValues ¶ added in v1.8.2
UnpackValues can be used to unpack ABI-encoded hexdata according to the ABI-specification, without supplying a struct to unpack into. Instead, this method returns a list containing the values. An atomic argument will be a list with one element.
type Error ¶ added in v1.10.10
type Error struct { Name string Inputs Arguments // Sig contains the string signature according to the ABI spec. // e.g. error foo(uint32 a, int b) = "foo(uint32,int256)" // Please note that "int" is substitute for its canonical representation "int256" Sig string // ID returns the canonical representation of the error's signature used by the // abi definition to identify event names and types. ID common.Hash // contains filtered or unexported fields }
type Event ¶ added in v1.4.0
type Event struct { // Name is the event name used for internal representation. It's derived from // the raw name and a suffix will be added in the case of event overloading. // // e.g. // These are two events that have the same name: // * foo(int,int) // * foo(uint,uint) // The event name of the first one will be resolved as foo while the second one // will be resolved as foo0. Name string // RawName is the raw event name parsed from ABI. RawName string Anonymous bool Inputs Arguments // Sig contains the string signature according to the ABI spec. // e.g. event foo(uint32 a, int b) = "foo(uint32,int256)" // Please note that "int" is substitute for its canonical representation "int256" Sig string // ID returns the canonical representation of the event's signature used by the // abi definition to identify event names and types. ID common.Hash // contains filtered or unexported fields }
Event is an event potentially triggered by the EVM's LOG mechanism. The Event holds type information (inputs) about the yielded output. Anonymous events don't get the signature canonical representation as the first LOG topic.
type FunctionType ¶ added in v1.9.14
type FunctionType int
FunctionType represents different types of functions a contract might have.
const ( // Constructor represents the constructor of the contract. // The constructor function is called while deploying a contract. Constructor FunctionType = iota // Fallback represents the fallback function. // This function is executed if no other function matches the given function // signature and no receive function is specified. Fallback // Receive represents the receive function. // This function is executed on plain Ether transfers. Receive // Function represents a normal function. Function )
type Method ¶
type Method struct { // Name is the method name used for internal representation. It's derived from // the raw name and a suffix will be added in the case of a function overload. // // e.g. // These are two functions that have the same name: // * foo(int,int) // * foo(uint,uint) // The method name of the first one will be resolved as foo while the second one // will be resolved as foo0. Name string RawName string // RawName is the raw method name parsed from ABI // Type indicates whether the method is a // special fallback introduced in solidity v0.6.0 Type FunctionType // StateMutability indicates the mutability state of method, // the default value is nonpayable. It can be empty if the abi // is generated by legacy compiler. StateMutability string // Legacy indicators generated by compiler before v0.6.0 Constant bool Payable bool Inputs Arguments Outputs Arguments // Sig returns the methods string signature according to the ABI spec. // e.g. function foo(uint32 a, int b) = "foo(uint32,int256)" // Please note that "int" is substitute for its canonical representation "int256" Sig string // ID returns the canonical representation of the method's signature used by the // abi definition to identify method names and types. ID []byte // contains filtered or unexported fields }
Method represents a callable given a `Name` and whether the method is a constant. If the method is `Const` no transaction needs to be created for this particular Method call. It can easily be simulated using a local VM. For example a `Balance()` method only needs to retrieve something from the storage and therefore requires no Tx to be sent to the network. A method such as `Transact` does require a Tx and thus will be flagged `false`. Input specifies the required input parameters for this gives method.
func NewMethod ¶ added in v1.9.14
func NewMethod(name string, rawName string, funType FunctionType, mutability string, isConst, isPayable bool, inputs Arguments, outputs Arguments) Method
NewMethod creates a new Method. A method should always be created using NewMethod. It also precomputes the sig representation and the string representation of the method.
func (Method) IsConstant ¶ added in v1.9.13
IsConstant returns the indicator whether the method is read-only.
type SelectorMarshaling ¶ added in v1.10.17
type SelectorMarshaling struct { Name string `json:"name"` Type string `json:"type"` Inputs []ArgumentMarshaling `json:"inputs"` }
func ParseSelector ¶ added in v1.10.17
func ParseSelector(unescapedSelector string) (SelectorMarshaling, error)
ParseSelector converts a method selector into a struct that can be JSON encoded and consumed by other functions in this package. Note, although uppercase letters are not part of the ABI spec, this function still accepts it as the general format is valid.
type Type ¶
type Type struct { Elem *Type Size int T byte // Our own type checking // Tuple relative fields TupleRawName string // Raw struct name defined in source code, may be empty. TupleElems []*Type // Type information of all tuple fields TupleRawNames []string // Raw field name of all tuple fields TupleType reflect.Type // Underlying struct of the tuple // contains filtered or unexported fields }
Type is the reflection of the supported argument type.
func NewType ¶
func NewType(t string, internalType string, components []ArgumentMarshaling) (typ Type, err error)
NewType creates a new reflection type of abi type given in t.