Documentation ¶
Overview ¶
Package w3 implements a blazing fast and modular Ethereum JSON RPC client with first-class ABI support.
Index ¶
- Variables
- func A(hexAddress string) common.Address
- func APtr(hexAddress string) *common.Address
- func B(hexBytes string) []byte
- func FromWei(wei *big.Int, decimals uint8) string
- func H(hexHash string) common.Hash
- func I(strInt string) *big.Int
- func Keccak(data []byte) common.Hashdeprecated
- type CallErrors
- type Client
- type Event
- type Func
- type Option
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( ErrInvalidABI = errors.New("w3: invalid ABI") ErrArgumentMismatch = errors.New("w3: argument mismatch") ErrReturnsMismatch = errors.New("w3: returns mismatch") ErrInvalidType = errors.New("w3: invalid type") ErrEvmRevert = errors.New("w3: evm reverted") )
var ( Big0 = big.NewInt(0) Big1 = big.NewInt(1) Big2 = big.NewInt(2) BigGwei = big.NewInt(1_000000000) BigEther = big.NewInt(1_000000000_000000000) )
Common big.Int's.
Functions ¶
func A ¶
A returns an address from a hexstring or panics if the hexstring does not represent a valid checksum encoded address.
Use common.HexToAddress to get the address from a hexstring without panicking.
func APtr ¶
APtr returns an address pointer from a hexstring or panics if the hexstring does not represent a valid checksum encoded address.
func B ¶
B returns a byte slice from a hexstring or panics if the hexstring does not represent a valid byte slice.
Use common.FromHex to get the byte slice from a hexstring without panicking.
func FromWei ¶
FromWei returns the given Wei as decimal with the given number of decimals.
Example ¶
package main import ( "fmt" "math/big" "github.com/lmittmann/w3" ) func main() { wei := big.NewInt(1_230000000_000000000) fmt.Printf("%s Ether\n", w3.FromWei(wei, 18)) }
Output: 1.23 Ether
func H ¶
H returns a hash from a hexstring or panics if the hexstring does not represent a valid hash.
Use common.HexToHash to get the hash from a hexstring without panicking.
func I ¶
I returns a big.Int from a hexstring or decimal number string (with optional unit) or panics if the parsing fails.
I supports the units "ether" or "eth" and "gwei" for decimal number strings. E.g.:
w3.I("1 ether") -> 1000000000000000000 w3.I("1.2 ether") -> 1200000000000000000
Fractional digits that exceed the units maximum number of fractional digits are ignored. E.g.:
w3.I("0.000000123456 gwei") -> 123
Example ¶
package main import ( "fmt" "github.com/lmittmann/w3" ) func main() { fmt.Printf("%v wei\n", w3.I("0x2b98d99b09e3c000")) fmt.Printf("%v wei\n", w3.I("3141500000000000000")) fmt.Printf("%v wei\n", w3.I("3.1415 ether")) fmt.Printf("%v wei\n", w3.I("31.415 gwei")) }
Output: 3141500000000000000 wei 3141500000000000000 wei 3141500000000000000 wei 31415000000 wei
func Keccak
deprecated
Keccak returns the Keccak256 hash of data. It is short for crypto.Keccak256Hash(…)
Deprecated: Use crypto.Keccak256Hash instead.
Types ¶
type CallErrors ¶ added in v0.10.0
type CallErrors []error
CallErrors is an error type that contains the errors of multiple calls. The length of the error slice is equal to the number of calls. Each error at a given index corresponds to the call at the same index. An error is nil if the corresponding call was successful.
func (CallErrors) Error ¶ added in v0.10.0
func (e CallErrors) Error() string
func (CallErrors) Is ¶ added in v0.10.0
func (e CallErrors) Is(target error) bool
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client represents a connection to an RPC endpoint.
func Dial ¶
Dial returns a new Client connected to the URL rawurl. An error is returned if the connection establishment fails.
The supported URL schemes are "http", "https", "ws" and "wss". If rawurl is a file name with no URL scheme, a local IPC socket connection is established.
Example ¶
package main import ( "fmt" "github.com/lmittmann/w3" ) func main() { client, err := w3.Dial("https://rpc.ankr.com/eth") if err != nil { fmt.Printf("Failed to connect to RPC endpoint: %v\n", err) return } defer client.Close() }
Output:
func MustDial ¶
MustDial is like Dial but panics if the connection establishment fails.
Example ¶
package main import ( "github.com/lmittmann/w3" ) func main() { client := w3.MustDial("https://rpc.ankr.com/eth") defer client.Close() }
Output:
func (*Client) Call ¶
Call is like Client.CallCtx with ctx equal to context.Background().
Example ¶
package main import ( "fmt" "math/big" "github.com/lmittmann/w3" "github.com/lmittmann/w3/module/eth" ) func main() { // Connect to RPC endpoint (or panic on error) and // close the connection when you are done. client := w3.MustDial("https://rpc.ankr.com/eth") defer client.Close() var ( addr = w3.A("0x000000000000000000000000000000000000dEaD") weth9 = w3.A("0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2") // Declare a Smart Contract function using Solidity syntax, // no "abigen" and ABI JSON file needed. balanceOf = w3.MustNewFunc("balanceOf(address)", "uint256") // Declare variables for the RPC responses. ethBalance big.Int weth9Balance big.Int ) // Do batch request (both RPC requests are send in the same // HTTP request). if err := client.Call( eth.Balance(addr, nil).Returns(ðBalance), eth.CallFunc(balanceOf, weth9, addr).Returns(&weth9Balance), ); err != nil { fmt.Printf("Request failed: %v\n", err) return } fmt.Printf("Combined balance: %v wei", new(big.Int).Add(ðBalance, &weth9Balance), ) }
Output:
Example (NonceAndBalance) ¶
package main import ( "fmt" "math/big" "github.com/lmittmann/w3" "github.com/lmittmann/w3/module/eth" ) func main() { client := w3.MustDial("https://rpc.ankr.com/eth") defer client.Close() var ( addr = w3.A("0x000000000000000000000000000000000000c0Fe") nonce uint64 balance big.Int ) if err := client.Call( eth.Nonce(addr, nil).Returns(&nonce), eth.Balance(addr, nil).Returns(&balance), ); err != nil { fmt.Printf("Request failed: %v\n", err) return } fmt.Printf("%s: Nonce: %d, Balance: ♦%s\n", addr, nonce, w3.FromWei(&balance, 18)) }
Output:
type Event ¶ added in v0.3.0
type Event struct { Signature string // Event signature Topic0 common.Hash // Hash of event signature (Topic 0) Args abi.Arguments // Arguments // contains filtered or unexported fields }
Event represents a Smart Contract event decoder.
func MustNewEvent ¶ added in v0.3.0
MustNewEvent is like NewEvent but panics if the signature parsing fails.
func NewEvent ¶ added in v0.3.0
NewEvent returns a new Smart Contract event log decoder from the given Solidity event signature.
An error is returned if the signature parsing fails.
func (*Event) DecodeArgs ¶ added in v0.3.0
DecodeArgs decodes the topics and data of the given log to the given args.
Example ¶
package main import ( "fmt" "math/big" "github.com/ethereum/go-ethereum/common" "github.com/ethereum/go-ethereum/core/types" "github.com/lmittmann/w3" ) func main() { var ( eventTransfer = w3.MustNewEvent("Transfer(address indexed from, address indexed to, uint256 value)") log = &types.Log{ Address: w3.A("0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"), Topics: []common.Hash{ w3.H("0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"), w3.H("0x000000000000000000000000000000000000000000000000000000000000c0fe"), w3.H("0x000000000000000000000000000000000000000000000000000000000000dead"), }, Data: w3.B("0x0000000000000000000000000000000000000000000000001111d67bb1bb0000"), } from common.Address to common.Address value big.Int ) if err := eventTransfer.DecodeArgs(log, &from, &to, &value); err != nil { fmt.Printf("Failed to decode event log: %v\n", err) return } fmt.Printf("Transferred %s WETH9 from %s to %s", w3.FromWei(&value, 18), from, to) }
Output: Transferred 1.23 WETH9 from 0x000000000000000000000000000000000000c0Fe to 0x000000000000000000000000000000000000dEaD
type Func ¶ added in v0.1.1
type Func struct { Signature string // Function signature Selector [4]byte // 4-byte selector Args abi.Arguments // Arguments (input) Returns abi.Arguments // Returns (output) // contains filtered or unexported fields }
Func represents a Smart Contract function ABI binding.
Func implements the w3types.Func interface.
func MustNewFunc ¶
MustNewFunc is like NewFunc but panics if the signature or returns parsing fails.
func NewFunc ¶
NewFunc returns a new Smart Contract function ABI binding from the given Solidity function signature and its returns.
An error is returned if the signature or returns parsing fails.
Example ¶
package main import ( "fmt" "math/big" "github.com/ethereum/go-ethereum/common" "github.com/lmittmann/w3" ) func main() { // ABI binding to the balanceOf function of an ERC20 Token. funcBalanceOf, _ := w3.NewFunc("balanceOf(address)", "uint256") // Optionally names can be specified for function arguments. This is // especially useful for more complex functions with many arguments. funcBalanceOf, _ = w3.NewFunc("balanceOf(address who)", "uint256 amount") // ABI-encode the functions args. input, _ := funcBalanceOf.EncodeArgs(w3.A("0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B")) fmt.Printf("balanceOf input: 0x%x\n", input) // ABI-decode the functions args from a given input. var ( who common.Address ) funcBalanceOf.DecodeArgs(input, &who) fmt.Printf("balanceOf args: %v\n", who) // ABI-decode the functions output. var ( output = w3.B("0x000000000000000000000000000000000000000000000000000000000000c0fe") amount = new(big.Int) ) funcBalanceOf.DecodeReturns(output, amount) fmt.Printf("balanceOf returns: %v\n", amount) }
Output: balanceOf input: 0x70a08231000000000000000000000000ab5801a7d398351b8be11c439e05c5b3259aec9b balanceOf args: 0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B balanceOf returns: 49406
func (*Func) DecodeArgs ¶ added in v0.1.1
DecodeArgs ABI-decodes the given input to the given args.
func (*Func) DecodeReturns ¶ added in v0.1.1
DecodeReturns ABI-decodes the given output to the given returns.
type Option ¶ added in v0.12.0
type Option func(*Client)
An Option configures a Client.
func WithRateLimiter ¶ added in v0.12.0
WithRateLimiter sets the rate limiter for the client. If perCall is true, the rate limiter is applied to each call. Otherwise, the rate limiter is applied to each request.
Example ¶
package main import ( "time" "github.com/lmittmann/w3" "golang.org/x/time/rate" ) func main() { // Limit the client to 30 requests per second and allow bursts of up to // 100 requests. client := w3.MustDial("https://rpc.ankr.com/eth", w3.WithRateLimiter(rate.NewLimiter(rate.Every(time.Second/30), 100), false), ) defer client.Close() }
Output:
Directories ¶
Path | Synopsis |
---|---|
abi
Package abi implements a Solidity ABI lexer and parser.
|
Package abi implements a Solidity ABI lexer and parser. |
module
|
|
debug
Package debug implements RPC API bindings for methods in the "debug" namespace.
|
Package debug implements RPC API bindings for methods in the "debug" namespace. |
eth
Package eth implements RPC API bindings for methods in the "eth" namespace.
|
Package eth implements RPC API bindings for methods in the "eth" namespace. |
web3
Package web3 implements RPC API bindings for methods in the "web3" namespace.
|
Package web3 implements RPC API bindings for methods in the "web3" namespace. |
Package rpctest provides utilities for testing RPC methods.
|
Package rpctest provides utilities for testing RPC methods. |
Package w3types implements common types.
|
Package w3types implements common types. |