w3: Enhanced Ethereum Integration for Go

w3 is your toolbelt for integrating with Ethereum in Go. Closely linked to go‑ethereum, it provides an ergonomic wrapper for working with RPC, ABI's, and the EVM.

go get github.com/lmittmann/w3

At a Glance

• Use w3.Client to connect to an RPC endpoint. The client features batch request support for up to 80x faster requests and easy extendibility. learn more ↗
• Use w3vm.VM to simulate EVM execution with optional tracing and Mainnet state forking, or test Smart Contracts. learn more ↗
• Use w3.Func and w3.Event to create ABI bindings from Solidity function and event signatures. learn more ↗
• Use w3.A, w3.H, and many other utility functions to parse addresses, hashes, and other common types from strings. learn more ↗

Sponsors

Getting Started

RPC Client

w3.Client is a batch request focused RPC client that can be used to connect to an Ethereum node via HTTP, WebSocket, or IPC. Its modular API allows to create custom RPC method integrations that can be used alongside the common methods implemented by this package.

Example: Batch Request (Playground)

// 1. Connect to an RPC endpoint
client, err := w3.Dial("https://eth.llamarpc.com")
if err != nil {
    // handle error
}
defer client.Close()
// 2. Make a batch request var (     balance *big.Int     nonce   uint64 ) if err := client.Call(     eth.Balance(addr, nil).Returns(&balance),     eth.Nonce(addr, nil).Returns(&nonce), ); err != nil {     // handle error }

[!NOTE]

#### Why send batch requests?

Most of the time you need to call multiple RPC methods to get the data you need. When you make separate requests per RPC call you need a single round trip to the server for each call. This can be slow, especially for remote endpoints. Batching multiple RPC calls into a single request only requires a single round trip, and speeds up RPC calls significantly.

Error Handling

If one or more calls in a batch request fail, Client.Call returns an error of type w3.CallErrors.

Example: Check which RPC calls failed in a batch request (Playground)

var batchErr w3.CallErrors if err := client.Call(calls...); errors.As(err, &batchErr) {     // handle call errors } else if err != nil {     // handle other errors }

Learn More

• List of supported RPC methods
• Learn how to create custom RPC method bindings

VM

w3vm.VM is a high-level EVM environment with a simple but powerful API to simulate EVM execution, test Smart Contracts, or trace transactions. It supports Mainnet state forking via RPC and state caching for faster testing.

Example: Simulate an Uniswap v3 swap (Playground)

// 1. Create a VM that forks the Mainnet state from the latest block,
// disables the base fee, and has a fake WETH balance and approval for the router
vm, err := w3vm.New(
    w3vm.WithFork(client, nil),
    w3vm.WithNoBaseFee(),
    w3vm.WithState(w3types.State{
        addrWETH: {Storage: w3types.Storage{
            w3vm.WETHBalanceSlot(addrEOA):               common.BigToHash(w3.I("1 ether")),
            w3vm.WETHAllowanceSlot(addrEOA, addrRouter): common.BigToHash(w3.I("1 ether")),
        }},
    }),
)
if err != nil {
    // handle error
}
// 2. Simulate a Uniswap v3 swap receipt, err := vm.Apply(&w3types.Message{     From: addrEOA,     To:   &addrRouter,     Func: funcExactInput,     Args: []any{&ExactInputParams{         Path:             encodePath(addrWETH, 500, addrUNI),         Recipient:        addrEOA,         Deadline:         big.NewInt(time.Now().Unix()),         AmountIn:         w3.I("1 ether"),         AmountOutMinimum: w3.Big0,     }}, }) if err != nil {     // handle error }
// 3. Decode output amount var amountOut *big.Int if err := receipt.DecodeReturns(&amountOut); err != nil {     // handle error }

ABI Bindings

ABI bindings in w3 are specified for individual functions using Solidity syntax and are usable for any contract that supports that function.

Example: ABI binding for the ERC20 balanceOf function (Playground)

funcBalanceOf := w3.MustNewFunc("balanceOf(address)", "uint256")

Example: ABI binding for the Uniswap v4 swap function (Playground)

funcSwap := w3.MustNewFunc(swap(
    (address currency0, address currency1, uint24 fee, int24 tickSpacing, address hooks) key,
    (bool zeroForOne, int256 amountSpecified, uint160 sqrtPriceLimitX96) params,
    bytes hookData
), "int256 delta")

A Func can be used to

• encode arguments to the contracts input data (Func.EncodeArgs),
• decode arguments from the contracts input data (Func.DecodeArgs), and
• decode returns from the contracts output data (Func.DecodeReturns).

Utils

Static addresses, hashes, bytes or integers can be parsed from (hex-)strings with the following utility functions that panic if the string is not valid.

addr := w3.A("0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045")
hash := w3.H("0xd4e56740f876aef8c010b86a40d5f56745a118d0906a34e69aec8c0db1cb8fa3")
bytes := w3.B("0x27c5342c")
amount := w3.I("12.34 ether")

Use go-ethereum/common to parse strings that may not be valid instead.

RPC Methods

List of supported RPC methods for w3.Client.

eth

| Method | Go Code | :---------------------------------------- | :------- | eth_blockNumber | eth.BlockNumber().Returns(blockNumber **big.Int) | eth_call | eth.Call(msg w3types.Message, blockNumber big.Int, overrides w3types.State).Returns(output *[]byte)
eth.CallFunc(contract common.Address, f w3types.Func, args ...any).Returns(returns ...any) | eth_chainId | eth.ChainID().Returns(chainID *uint64) | eth_createAccessList | eth.AccessList(msg w3types.Message, blockNumber big.Int).Returns(resp **eth.AccessListResponse) | eth_estimateGas | eth.EstimateGas(msg w3types.Message, blockNumber big.Int).Returns(gas *uint64) | eth_gasPrice | eth.GasPrice().Returns(gasPrice **big.Int) | eth_maxPriorityFeePerGas | eth.GasTipCap().Returns(gasTipCap **big.Int) | eth_getBalance | eth.Balance(addr common.Address, blockNumber big.Int).Returns(balance *big.Int) | eth_getBlockByHash | eth.BlockByHash(hash common.Hash).Returns(block types.Block)
eth.HeaderByHash(hash common.Hash).Returns(header *types.Header) | eth_getBlockByNumber | eth.BlockByNumber(number big.Int).Returns(block types.Block)
eth.HeaderByNumber(number big.Int).Returns(header *types.Header) | eth_getBlockReceipts | eth.BlockReceipts(blockNumber big.Int).Returns(receipts types.Receipts) | eth_getBlockTransactionCountByHash | eth.BlockTxCountByHash(hash common.Hash).Returns(count *uint) | eth_getBlockTransactionCountByNumber | eth.BlockTxCountByNumber(number big.Int).Returns(count uint) | eth_getCode | eth.Code(addr common.Address, blockNumber big.Int).Returns(code []byte) | eth_getLogs | eth.Logs(q ethereum.FilterQuery).Returns(logs *[]types.Log) | eth_getStorageAt | eth.StorageAt(addr common.Address, slot common.Hash, blockNumber big.Int).Returns(storage common.Hash) | eth_getTransactionByHash | eth.Tx(hash common.Hash).Returns(tx **types.Transaction) | eth_getTransactionByBlockHashAndIndex | eth.TxByBlockHashAndIndex(blockHash common.Hash, index uint).Returns(tx **types.Transaction) | eth_getTransactionByBlockNumberAndIndex | eth.TxByBlockNumberAndIndex(blockNumber big.Int, index uint).Returns(tx *types.Transaction) | eth_getTransactionCount | eth.Nonce(addr common.Address, blockNumber big.Int).Returns(nonce uint) | eth_getTransactionReceipt | eth.TxReceipt(txHash common.Hash).Returns(receipt **types.Receipt) | eth_sendRawTransaction | eth.SendRawTx(rawTx []byte).Returns(hash common.Hash)
eth.SendTx(tx types.Transaction).Returns(hash *common.Hash) | eth_getUncleByBlockHashAndIndex | eth.UncleByBlockHashAndIndex(hash common.Hash, index uint).Returns(uncle **types.Header) | eth_getUncleByBlockNumberAndIndex | eth.UncleByBlockNumberAndIndex(number big.Int, index uint).Returns(uncle *types.Header) | eth_getUncleCountByBlockHash | eth.UncleCountByBlockHash(hash common.Hash).Returns(count *uint) | eth_getUncleCountByBlockNumber | eth.UncleCountByBlockNumber(number big.Int).Returns(count uint) | eth_syncing | eth.Syncing().Returns(syncing *bool)

debug

| Method | Go Code | :----------------------- | :------- | debug_traceCall | debug.TraceCall(msg w3types.Message, blockNumber big.Int, config debug.TraceConfig).Returns(trace debug.Trace)
debug.CallTraceCall(msg w3types.Message, blockNumber *big.Int, overrides w3types.State).Returns(trace debug.CallTrace) | debug_traceTransaction | debug.TraceTx(txHash common.Hash, config *debug.TraceConfig).Returns(trace debug.Trace)
debug.CallTraceTx(txHash common.Hash, overrides w3types.State).Returns(trace debug.CallTrace)

txpool

| Method | Go Code | :--------------------| :------- | txpool_content | txpool.Content().Returns(resp **txpool.ContentResponse) | txpool_contentFrom | txpool.ContentFrom(addr common.Address).Returns(resp **txpool.ContentFromResponse) | txpool_status | txpool.Status().Returns(resp **txpool.StatusResponse)

admin

| Method | Go Code | :------------------------ | :------- | admin_addPeer | admin.AddPeer(url enode.Node).Returns(resp bool) | admin_removePeer | admin.RemovePeer(url enode.Node).Returns(resp bool) | admin_addTrustedPeer | admin.AddTrustedPeer(url enode.Node).Returns(resp bool) | admin_removeTrustedPeer | admin.RemoveTrustedPeer(url enode.Node).Returns(resp bool) | admin_nodeInfo | admin.NodeInfo().Returns(resp **admin.NodeInfoResponse)

net

| Method | Go Code | :------------------- | :------- | net_listening | net.Listening().Returns(resp *bool) | net_peerCount | net.PeerCount().Returns(resp *int) | net_version | net.Version().Returns(resp *int)

web3

| Method | Go Code | :------------------- | :------- | web3_clientVersion | web3.ClientVersion().Returns(clientVersion *string)

Third Party RPC Method Packages

| Package | Description | :----------------------------------------------------------------------- | :----------- | github.com/lmittmann/flashbots | Package flashbots implements RPC API bindings for the Flashbots relay and mev-geth.

Custom RPC Method Bindings

Custom RPC method bindings can be created by implementing the w3types.RPCCaller interface.

Example: RPC binding for the Otterscan otsgetTransactionBySenderAndNonce method (Playground)

// TxBySenderAndNonceFactory requests the senders transaction hash by the nonce.
func TxBySenderAndNonceFactory(sender common.Address, nonce uint64) w3types.RPCCallerFactory[common.Hash] {
    return &getTransactionBySenderAndNonceFactory{
        sender: sender,
        nonce:  nonce,
    }
}
// getTransactionBySenderAndNonceFactory implements the w3types.RPCCaller and // w3types.RPCCallerFactory interfaces. It stores the method parameters and // the reference to the return value. type getTransactionBySenderAndNonceFactory struct {     // params     sender common.Address     nonce  uint64
// returns     returns *common.Hash }
// Returns sets the reference to the return value. func (f getTransactionBySenderAndNonceFactory) Returns(txHash common.Hash) w3types.RPCCaller {     f.returns = txHash     return f }
// CreateRequest creates a batch request element for the Otterscan getTransactionBySenderAndNonce method. func (f *getTransactionBySenderAndNonceFactory) CreateRequest() (rpc.BatchElem, error) {     return rpc.BatchElem{         Method: "ots_getTransactionBySenderAndNonce",         Args:   []any{f.sender, f.nonce},         Result: f.returns,     }, nil }
// HandleResponse handles the response of the Otterscan getTransactionBySenderAndNonce method. func (f *getTransactionBySenderAndNonceFactory) HandleResponse(elem rpc.BatchElem) error {     if err := elem.Error; err != nil {         return err     }     return nil }