fastabi

package module
v0.4.0 Latest Latest
Warning

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

 Go to latest Published: Jun 24, 2026 License: MIT Imports: 10 Imported by: 0

README

fastabi — ABI Codec for EVM

A high-performance ABI encoder/decoder for EVM chains. No go-ethereum dependency.

Features

  • ABIv2 — all Solidity types: uint8–uint256, int8–int256, address, bool, bytes, bytes32, string, arrays, nested tuples
  • Zero-alloc — pooled Decoder/Encoder via sync.Pool, no heap allocations per call after warm-up
  • U256 — wraps holiman/uint256 inline (no pointer, GC-friendly), with pooling for hot paths
  • Signature parser — ParseFunction("transfer(address,uint256)") → name + parameter types
  • Keccak256 — 4-byte selectors from function signatures
  • Wad math — WadMul, WadDiv, WadLn for DeFi fixed-point arithmetic

Quick Start

import "github.com/cryptoddev/fastabi"

// Encode a single uint256
data := fastabi.Encode1(fastabi.TUint256(), uint64(42))

// Decode
val, _ := fastabi.Decode1(fastabi.TUint256(), data)
u := val.(*fastabi.U256)

// Pooled low-level API for hot paths
enc := fastabi.GetEncoder()
defer fastabi.PutEncoder(enc)
enc.EncodeUint64(42)
data = enc.Bytes()

Types

Constructor Solidity Go Type
TUint<N>() uint8–uint256 uint64, *big.Int, *U256
TInt<N>() int8–int256 int64, *big.Int
TAddress() address [20]byte, Address
TBool() bool bool
TBytes() bytes []byte
TBytes32() bytes32/bytesN [32]byte
TString() string string
TArray(elem) type[] []any
TFixedArray(elem, n) type[n] []any
TTuple(...) (a,b,c) []any

Testing

go test ./...
go test -bench=. ./...

License

MIT

Documentation

Overview

Package fastabi provides low-level ABI encoding/decoding primitives for Ethereum.

Scope: Address, Hash, U256, Encoder, Decoder, ParamType, Kind. Domain types (Pool, Token, Edge, PoolUpdate, Opportunity, DEXType) live in internal/types — they are not part of this library.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BytesToHex 

func BytesToHex(b []byte) string

BytesToHex converts bytes to a hex string (without 0x prefix).

func Decode 

func Decode(ts []ParamType, data []byte) ([]any, error)

Decode generic ABI data into Go values.

func Decode1 

func Decode1(t ParamType, data []byte) (any, error)

Decode1 decodes a single value.

func DecodeSignature 

func DecodeSignature(sig string) ([32]byte, error)

DecodeSignature hashes a function/event signature string into a 32-byte topic0.

func Encode 

func Encode(ts []ParamType, vals []any) []byte

Encode generic ABI values. Returns ABI-encoded bytes. Each value must match the corresponding ParamType.

func Encode1 

func Encode1(t ParamType, val any) []byte

Encode1 encodes a single value.

func HexToBytes 

func HexToBytes(s string) ([]byte, error)

HexToBytes converts a hex string to bytes.

func IsWhitespace 

func IsWhitespace(s string) bool

IsWhitespace checks if a string is only whitespace.

func MustDecodeSignature 

func MustDecodeSignature(sig string) [32]byte

MustDecodeSignature hashes a signature string, panicking on error.

func PaddedLen 

func PaddedLen(n int) int

PaddedLen returns the smallest multiple of 32 >= n.

func ParamNames 

func ParamNames(ts []ParamType) []string

ParamNames extracts names from a ParamType tree.

func ParseHexByte 

func ParseHexByte(hi, lo byte) (byte, error)

ParseHexByte parses two hex characters into a byte.

func ParseHexUint64 

func ParseHexUint64(s string) (uint64, error)

ParseHexUint64 parses a hex string to uint64.

func PutDecoder 

func PutDecoder(d *Decoder)

PutDecoder returns a Decoder to the pool.

func PutEncoder 

func PutEncoder(e *Encoder)

PutEncoder returns an Encoder to the pool.

func PutU256 

func PutU256(u *U256)

PutU256 returns a U256 to the pool after zeroing it.

func RAYInt 

func RAYInt() *uint256.Int

RAYInt returns 1e27 as a read-only *uint256.Int. Do NOT mutate.

func ReadUint64At 

func ReadUint64At(data []byte, offset int) uint64

ReadUint64At reads a uint64 from the last 8 bytes of a 32-byte ABI word at the given offset.

Types

type Address 

type Address [20]byte

Address is a 20-byte Ethereum address.

func AddressFromUint64 

func AddressFromUint64(v uint64) Address

AddressFromUint64 creates an Address from a uint64 value (big-endian, right-aligned). Useful in tests and benchmarks to generate unique addresses cheaply.

func MustParseAddress 

func MustParseAddress(s string) Address

MustParseAddress parses an address or panics.

func ParseAddress 

func ParseAddress(s string) (Address, error)

ParseAddress parses an address from hex string.

func (Address) Bytes 

func (a Address) Bytes() []byte

Bytes returns the address as byte slice.

func (Address) Hex 

func (a Address) Hex() string

Hex returns the address as hex string with 0x prefix.

func (Address) IsZero 

func (a Address) IsZero() bool

IsZero returns true if address is all zeros.

func (Address) String 

func (a Address) String() string

String returns short hex representation.

type Decoder 

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

Decoder is a reusable ABI decoder for hot-path static types. Uses zero-copy SetData() and sync.Pool for minimal allocations.

func GetDecoder 

func GetDecoder() *Decoder

GetDecoder gets a Decoder from the pool.

func NewDecoder 

func NewDecoder() *Decoder

NewDecoder returns a pooled Decoder (alias for GetDecoder).

func (*Decoder) DecodeAddress 

func (d *Decoder) DecodeAddress() [20]byte

DecodeAddress decodes an Ethereum address from ABI slot.

func (*Decoder) DecodeBigInt 

func (d *Decoder) DecodeBigInt() *big.Int

DecodeBigInt decodes unsigned uint256 into big.Int.

func (*Decoder) DecodeBool 

func (d *Decoder) DecodeBool() bool

DecodeBool decodes bool from ABI slot.

func (*Decoder) DecodeBytes32 

func (d *Decoder) DecodeBytes32() [32]byte

DecodeBytes32 decodes bytes32 from ABI slot.

func (*Decoder) DecodeInt256 

func (d *Decoder) DecodeInt256() *big.Int

DecodeInt256 decodes signed int256 (two's complement).

func (*Decoder) DecodeUint8 

func (d *Decoder) DecodeUint8() uint8

DecodeUint8 decodes uint8 from ABI slot.

func (*Decoder) DecodeUint16 

func (d *Decoder) DecodeUint16() uint16

DecodeUint16 decodes uint16 from ABI slot.

func (*Decoder) DecodeUint32 

func (d *Decoder) DecodeUint32() uint32

DecodeUint32 decodes uint32 from ABI slot.

func (*Decoder) DecodeUint64 

func (d *Decoder) DecodeUint64() uint64

DecodeUint64 decodes uint64 from ABI slot.

func (*Decoder) DecodeUint256 

func (d *Decoder) DecodeUint256() *U256

DecodeUint256 decodes uint256 from a 32-byte ABI slot.

func (*Decoder) Len 

func (d *Decoder) Len() int

Len returns remaining bytes.

func (*Decoder) Offset 

func (d *Decoder) Offset() int

Offset returns the current read position.

func (*Decoder) Reset 

func (d *Decoder) Reset()

Reset resets the decoder state.

func (*Decoder) SetData 

func (d *Decoder) SetData(data []byte)

SetData uses zero-copy semantics. Caller must not mutate data while decoding.

func (*Decoder) Skip 

func (d *Decoder) Skip(n int) bool

Skip advances the offset by n bytes.

type Encoder 

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

Encoder is a reusable ABI encoder for hot-path static types. Uses sync.Pool for minimal allocations.

func GetEncoder 

func GetEncoder() *Encoder

GetEncoder gets an Encoder from the pool.

func NewEncoder 

func NewEncoder() *Encoder

NewEncoder returns a pooled Encoder (alias for GetEncoder).

func (*Encoder) Bytes 

func (e *Encoder) Bytes() []byte

Bytes returns the encoded bytes.

func (*Encoder) EncodeAddress 

func (e *Encoder) EncodeAddress(addr [20]byte) *Encoder

EncodeAddress encodes address into ABI slot.

func (*Encoder) EncodeBigInt 

func (e *Encoder) EncodeBigInt(v *big.Int) *Encoder

EncodeBigInt encodes signed int256.

func (*Encoder) EncodeBool 

func (e *Encoder) EncodeBool(v bool) *Encoder

EncodeBool encodes bool into ABI slot.

func (*Encoder) EncodeBytes32 

func (e *Encoder) EncodeBytes32(v [32]byte) *Encoder

EncodeBytes32 encodes bytes32 into ABI slot.

func (*Encoder) EncodeMethodID 

func (e *Encoder) EncodeMethodID(id MethodID) *Encoder

EncodeMethodID encodes a 4-byte method ID.

func (*Encoder) EncodeUint8 

func (e *Encoder) EncodeUint8(v uint8) *Encoder

EncodeUint8 encodes uint8 into ABI slot.

func (*Encoder) EncodeUint16 

func (e *Encoder) EncodeUint16(v uint16) *Encoder

EncodeUint16 encodes uint16 into ABI slot.

func (*Encoder) EncodeUint24 

func (e *Encoder) EncodeUint24(v uint32) *Encoder

EncodeUint24 encodes uint24 into ABI slot.

func (*Encoder) EncodeUint32 

func (e *Encoder) EncodeUint32(v uint32) *Encoder

EncodeUint32 encodes uint32 into ABI slot.

func (*Encoder) EncodeUint64 

func (e *Encoder) EncodeUint64(v uint64) *Encoder

EncodeUint64 encodes uint64 into ABI slot.

func (*Encoder) EncodeUint256 

func (e *Encoder) EncodeUint256(u *U256) *Encoder

EncodeUint256 encodes uint256 into ABI slot.

func (*Encoder) Hex 

func (e *Encoder) Hex() string

Hex returns the encoded bytes as a hex string with 0x prefix.

func (*Encoder) Reset 

func (e *Encoder) Reset()

Reset resets the encoder buffer.

type Hash 

type Hash [32]byte

Hash is a 32-byte Ethereum hash (transaction hash, block hash, topic, etc.).

func ParseHash 

func ParseHash(s string) (Hash, error)

ParseHash parses a hash from a hex string (with or without 0x prefix).

func (Hash) Bytes 

func (h Hash) Bytes() []byte

Bytes returns the hash as a byte slice.

func (Hash) Hex 

func (h Hash) Hex() string

Hex returns the hash as a hex string with 0x prefix.

func (Hash) IsZero 

func (h Hash) IsZero() bool

IsZero returns true if the hash is all zeros.

type Kind 

type Kind uint8

Kind represents an ABI parameter kind. 

const (
	KindUnknown Kind = iota
	KindUint8
	KindUint16
	KindUint24
	KindUint32
	KindUint64
	KindUint128
	KindUint256
	KindInt8
	KindInt16
	KindInt24
	KindInt32
	KindInt64
	KindInt128
	KindInt256
	KindAddress
	KindBool
	KindBytes32
	KindBytes
	KindString
	KindArray
	KindFixedArr
	KindTuple
)

func (Kind) String 

func (k Kind) String() string

type MethodID 

type MethodID [4]byte

MethodID is a 4-byte function selector.

type ParamType 

type ParamType struct {
	Kind    Kind
	Size    int        // bit-width for uint/int, length for fixedArray/fixedBytes
	Elem    *ParamType // element type for arrays
	TupleEl []ParamType
	Name    string // optional field name
}

ParamType describes a single ABI parameter.

func Named 

func Named(name string, t ParamType) ParamType

func ParseFunction 

func ParseFunction(sig string) (name string, inputs []ParamType, err error)

ParseFunction parses a function signature like "transfer(address,uint256)" or "balanceOf(address):(uint256)" and returns the function name and input types.

func ParseType 

func ParseType(s string) (ParamType, error)

ParseType parses a human-readable ABI type string into a ParamType. Examples: "uint256", "address", "(uint8,address,bytes)[]", "string", "bytes32[3]"

func ParseTypes 

func ParseTypes(s string) ([]ParamType, error)

ParseTypes parses a comma-separated list of types.

func TAddress 

func TAddress() ParamType

func TArray 

func TArray(elem ParamType) ParamType

func TBool 

func TBool() ParamType

func TBytes 

func TBytes() ParamType

func TBytes32 

func TBytes32() ParamType

func TFixedArray 

func TFixedArray(elem ParamType, n int) ParamType

func TInt8 

func TInt8() ParamType

func TInt16 

func TInt16() ParamType

func TInt24 

func TInt24() ParamType

func TInt32 

func TInt32() ParamType

func TInt64 

func TInt64() ParamType

func TInt128 

func TInt128() ParamType

func TInt256 

func TInt256() ParamType

func TString 

func TString() ParamType

func TTuple 

func TTuple(fields ...ParamType) ParamType

func TUint8 

func TUint8() ParamType

func TUint16 

func TUint16() ParamType

func TUint24 

func TUint24() ParamType

func TUint32 

func TUint32() ParamType

func TUint64 

func TUint64() ParamType

func TUint128 

func TUint128() ParamType

func TUint256 

func TUint256() ParamType

func (ParamType) GoType 

func (t ParamType) GoType() string

GoType returns a Go type string for the ParamType.

func (ParamType) IsDynamic 

func (t ParamType) IsDynamic() bool

IsDynamic returns true if the type requires dynamic encoding.

func (ParamType) Signature 

func (t ParamType) Signature() string

Signature returns the human-readable ABI signature.

func (ParamType) StaticSize 

func (t ParamType) StaticSize() int

StaticSize returns the byte size for static types, 0 for dynamic.

type U256 

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

U256 is a 256-bit unsigned integer for Ethereum-compatible operations. It embeds uint256.Int inline (32 bytes, no pointers) so structs containing U256 value fields (not pointers) are GC-friendly (noscan).

func GetU256 

func GetU256() *U256

GetU256 returns a zero-initialized U256 from the pool.

func HALF_WAD 

func HALF_WAD() *U256

HALF_WAD returns 5e17 as a read-only *U256. Do NOT mutate the returned value.

func IntToU256 

func IntToU256(v int64) *U256

IntToU256 converts int64 to U256.

func MaxU256 

func MaxU256() *U256

MaxU256 returns a new U256 with max value (2^256 - 1).

func NewU64 

func NewU64(v uint64) *U256

NewU64 creates a new U256 from uint64.

func NewU256 

func NewU256(v uint64) *U256

NewU256 creates a new U256 from uint64 (alias for NewU64).

func NewU256FromBig 

func NewU256FromBig(b *big.Int) *U256

NewU256FromBig creates U256 from big.Int.

func NewU256FromHex 

func NewU256FromHex(s string) (*U256, error)

NewU256FromHex creates U256 from hex string.

func WAD 

func WAD() *U256

WAD returns 1e18 as a read-only *U256. Do NOT mutate the returned value.

func WadDiv 

func WadDiv(a, b *U256) *U256

WadDiv performs wad division: (a * WAD + b/2) / b Uses reusable scratch buffers to avoid allocations in hot paths.

func WadLn 

func WadLn(x *U256) *U256

WadLn computes natural logarithm for WAD fixed-point numbers.

func WadMul 

func WadMul(a, b *U256) *U256

WadMul performs wad multiplication: (a * b + 0.5*WAD) / WAD Uses reusable scratch buffers to avoid allocations in hot paths.

func (*U256) Add 

func (u *U256) Add(b *U256) *U256

Add adds b to u and returns u (u = u + b).

func (*U256) Bytes 

func (u *U256) Bytes() []byte

Bytes returns the value as 32-byte big-endian array.

func (*U256) Bytes32 

func (u *U256) Bytes32() [32]byte

Bytes32 returns the value as [32]byte array.

func (*U256) Clone 

func (u *U256) Clone() *U256

Clone creates a deep copy of U256.

func (*U256) Cmp 

func (u *U256) Cmp(b *U256) int

Cmp compares two U256 values.

func (*U256) Div 

func (u *U256) Div(b *U256) *U256

Div divides u by b and returns u (u = u / b).

func (*U256) Eq 

func (u *U256) Eq(b *U256) bool

Eq returns true if u == b.

func (*U256) Gt 

func (u *U256) Gt(b *U256) bool

Gt returns true if u > b.

func (*U256) Hex 

func (u *U256) Hex() string

Hex returns the hex string representation (with 0x prefix).

func (*U256) Inner 

func (u *U256) Inner() *uint256.Int

Inner returns the internal uint256.Int for advanced operations.

func (*U256) IsPositive 

func (u *U256) IsPositive() bool

IsPositive returns true if value > 0.

func (*U256) IsZero 

func (u *U256) IsZero() bool

IsZero returns true if the value is zero.

func (*U256) Lt 

func (u *U256) Lt(b *U256) bool

Lt returns true if u < b.

func (*U256) Mul 

func (u *U256) Mul(b *U256) *U256

Mul multiplies u by b and returns u (u = u * b).

func (*U256) MulDiv 

func (u *U256) MulDiv(b, c *U256) *U256

MulDiv calculates (u * b) / c with full precision using scratch buffers.

func (*U256) MulDivRoundingUp 

func (u *U256) MulDivRoundingUp(b, c *U256) *U256

MulDivRoundingUp calculates (u * b) / c with rounding up using scratch buffers.

func (*U256) Rsh 

func (u *U256) Rsh(n uint) *U256

Rsh performs right shift on u by n bits (u = u >> n).

func (*U256) Set 

func (u *U256) Set(b *U256) *U256

Set copies value from another U256.

func (*U256) SetBytes 

func (u *U256) SetBytes(b []byte) *U256

SetBytes sets the value from big-endian bytes.

func (*U256) SetBytes32 

func (u *U256) SetBytes32(b [32]byte) *U256

SetBytes32 sets the value from [32]byte array.

func (*U256) SetUint64 

func (u *U256) SetUint64(v uint64) *U256

SetUint64 sets the value from uint64.

func (*U256) Sqrt 

func (u *U256) Sqrt() *U256

Sqrt calculates the integer square root.

func (*U256) String 

func (u *U256) String() string

String returns the decimal string representation.

func (*U256) Sub 

func (u *U256) Sub(b *U256) *U256

Sub subtracts b from u and returns u (u = u - b).

func (*U256) ToBig 

func (u *U256) ToBig() *big.Int

ToBig returns the value as big.Int.

func (*U256) ToUint64 

func (u *U256) ToUint64() uint64

ToUint64 returns the uint64 representation (truncates higher bits).

func (*U256) Uint64 

func (u *U256) Uint64() uint64

Uint64 returns the value as uint64 (truncates if overflow).

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.