Links

Contract Bindings

This page introduces the concept of server-side native dapps. Geth provides the tools required to generate Go language bindings to any Ethereum contract that is compile-time type safe, highly performant and can be generated completely automatically from a compiled contract.
Interacting with a contract on the Ethereum blockchain from Go is already possible via the RPC interfaces exposed by Ethereum clients. However, writing the boilerplate code that translates Go language constructs into RPC calls and back is time consuming and brittle - implementation bugs can only be detected during runtime and it’s almost impossible to evolve a contract as even a tiny change in Solidity is awkward to port over to Go. Therefore, Geth provides tools for easily converting contract code into Go code that can be used directly in Go applications.
This page provides an introduction to generating Go contract bindings and using them in a simple Go application.

Prerequisites

This page is fairly beginner-friendly and designed for people starting out with writing Go native dapps. The core concepts will be introduced gradually as a developer would encounter them. However, some basic familiarity with Ethereum, Solidity and Go is assumed.

What is an ABI?

Ethereum smart contracts have a schema that defines its functions and return types in the form of a JSON file. This JSON file is known as an Application Binary Interface, or ABI. The ABI acts as a specification for precisely how to encode data sent to a contract and how to decode the data the contract sends back. The ABI is the only essential piece of information required to generate Go bindings. Go developers can then use the bindings to interact with the contract from their Go application without having to deal directly with data encoding and decoding. An ABI is generated when a contract is compiled.

Abigen: Go binding generator

Geth includes a source code generator called abigen that can convert Ethereum ABI definitions into easy to use, type-safe Go packages. With a valid Go development environment set up and the go-ethereum repository checked out correctly, abigen can be built as follows:
$ cd $GOPATH/src/github.com/ethereum/go-ethereum
$ go build ./cmd/abigen

Generating the bindings

To demonstrate the binding generator a contract is required. The contract Storage.sol implements two very simple functions: store updates a user-defined uint256 to the contract’s storage, and retrieve displays the value stored in the contract to the user. The Solidity code is as follows:
// SPDX-License-Identifier: GPL-3.0
pragma solidity >0.7.0 < 0.9.0;
/**
* @title Storage
* @dev store or retrieve variable value
*/
contract Storage {
uint256 value;
function store(uint256 number) public{
value = number;
}
function retrieve() public view returns (uint256){
return value;
}
}
This contract can be pasted into a text file and saved as Storage.sol.
The following code snippet shows how an ABI can be generated for Storage.sol using the Solidity compiler solc.
solc --abi Storage.sol -o build
The ABI can also be generated in other ways such as using the compile commands in development frameworks such as Truffle, Hardhat and Brownie or in the online IDE Remix. ABIs for existing verified contracts can be downloaded from Etherscan.
The ABI for Storage.sol (Storage.abi) looks as follows:
[{"inputs":[],"name":"retrieve","outputs":[{"internalType":"uint256","name":"","type":"uint256"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"uint256","name":"number","type":"uint256"}],"name":"store","outputs":[],"stateMutability":"nonpayable","type":"function"}]
The contract binding can then be generated by passing the ABI to abigen as follows:
$ abigen --abi Storage.abi --pkg main --type Storage --out Storage.go
Where the flags are:
  • --abi: Mandatory path to the contract ABI to bind to
  • --pkg: Mandatory Go package name to place the Go code into
  • --type: Optional Go type name to assign to the binding struct
  • --out: Optional output path for the generated Go source file (not set = stdout)
This will generate a type-safe Go binding for the Storage contract. The generated code will look something like the snippet below, the full version of which can be viewed here.
// Code generated - DO NOT EDIT.
// This file is a generated binding and any manual changes will be lost.
package main
import (
"errors"
"math/big"
"strings"
ethereum "github.com/ethereum/go-ethereum"
"github.com/ethereum/go-ethereum/accounts/abi"
"github.com/ethereum/go-ethereum/accounts/abi/bind"
"github.com/ethereum/go-ethereum/common"
"github.com/ethereum/go-ethereum/core/types"
"github.com/ethereum/go-ethereum/event"
)
// Reference imports to suppress errors if they are not otherwise used.
var (
_ = errors.New
_ = big.NewInt
_ = strings.NewReader
_ = ethereum.NotFound
_ = bind.Bind
_ = common.Big1
_ = types.BloomLookup
_ = event.NewSubscription
)
// StorageMetaData contains all meta data concerning the Storage contract.
var StorageMetaData = &bind.MetaData{
ABI: "[{\"inputs\":[],\"name\":\"retrieve\",\"outputs\":[{\"internalType\":\"uint256\",\"name\":\"\",\"type\":\"uint256\"}],\"stateMutability\":\"view\",\"type\":\"function\"},{\"inputs\":[{\"internalType\":\"uint256\",\"name\":\"number\",\"type\":\"uint256\"}],\"name\":\"store\",\"outputs\":[],\"stateMutability\":\"nonpayable\",\"type\":\"function\"}]",
}
// StorageABI is the input ABI used to generate the binding from.
// Deprecated: Use StorageMetaData.ABI instead.
var StorageABI = StorageMetaData.ABI
// Storage is an auto generated Go binding around an Ethereum contract.
type Storage struct {
StorageCaller // Read-only binding to the contract
StorageTransactor // Write-only binding to the contract
StorageFilterer // Log filterer for contract events
}
...o
Storage.go contains all the bindings required to interact with Storage.sol from a Go application. However, this isn’t very useful unless the contract is actually deployed on Ethereum or one of Ethereum’s testnets. The following sections will demonstrate how to deploy the contract to an Ethereum testnet and interact with it using the Go bindings.

Deploying contracts to DeXit

In the previous section, the contract ABI was sufficient for generating the contract bindings from its ABI. However, deploying the contract requires some additional information in the form of the compiled bytecode.
The bytecode is obtained by running the compiler again but this passing the --bin flag, e.g.
solc --bin Storage.sol -o Storage.bin
Then abigen can be run again, this time passing Storage.bin:
$ abigen --abi Storage.abi --pkg main --type Storage --out Storage.go --bin Storage.bin
This will generate something similar to the bindings generated in the previous section. However, an additional DeployStorage function has been injected:
// DeployStorage deploys a new Ethereum contract, binding an instance of Storage to it.
func DeployStorage(auth *bind.TransactOpts, backend bind.ContractBackend) (common.Address, *types.Transaction, *Storage, error) {
parsed, err := StorageMetaData.GetAbi()
if err != nil {
return common.Address{}, nil, nil, err
}
if parsed == nil {
return common.Address{}, nil, nil, errors.New("GetABI returned nil")
}
address, tx, contract, err := bind.DeployContract(auth, *parsed, common.FromHex(StorageBin), backend)
if err != nil {
return common.Address{}, nil, nil, err
}
return address, tx, &Storage{StorageCaller: StorageCaller{contract: contract}, StorageTransactor: StorageTransactor{contract: contract}, StorageFilterer: StorageFilterer{contract: contract}}, nil
}
View the full file here.
The new DeployStorage() function can be used to deploy the contract to an Ethereum testnet from a Go application. To do this requires incorporating the bindings into a Go application that also handles account management, authorization and Ethereum backend to deploy the contract through. Specifically, this requires:
  1. 1.
    A running Geth node connected to an Ethereum testnet (recommended Goerli)
  2. 2.
    An account in the keystore prefunded with enough ETH to cover gas costs for deploying and interacting with the contract
Assuming these prerequisites exist, a new ethclient can be instantiated with the local Geth node’s ipc file, providing access to the testnet from the Go application. The key can be instantiated as a variable in the application by copying the JSON object from the keyfile in the keystore.
Putting it all together would result in:
package main
import (
"fmt"
"log"
"math/big"
"strings"
"time"
"github.com/ethereum/go-ethereum/accounts/abi/bind"
"github.com/ethereum/go-ethereum/ethclient"
)
const key = `<<json object from keystore>>`
func main() {
// Create an IPC based RPC connection to a remote node and an authorized transactor
conn, err := rpc.NewIPCClient("/home/go-ethereum/goerli/geth.ipc")
if err != nil {
log.Fatalf("Failed to connect to the Ethereum client: %v", err)
}
auth, err := bind.NewTransactor(strings.NewReader(key), "<<strong_password>>")
if err != nil {
log.Fatalf("Failed to create authorized transactor: %v", err)
}
// Deploy the contract passing the newly created `auth` and `conn` vars
address, tx, instance, err := DeployStorage(auth, conn), new(big.Int), "Storage contract in Go!", 0, "Go!")
if err != nil {
log.Fatalf("Failed to deploy new storage contract: %v", err)
}
fmt.Printf("Contract pending deploy: 0x%x\n", address)
fmt.Printf("Transaction waiting to be mined: 0x%x\n\n", tx.Hash())
time.Sleep(250 * time.Millisecond) // Allow it to be processed by the local node :P
// function call on `instance`. Retrieves pending name
name, err := instance.Name(&bind.CallOpts{Pending: true})
if err != nil {
log.Fatalf("Failed to retrieve pending name: %v", err)
}
fmt.Println("Pending name:", name)
}
Running this code requests the creation of a brand new Storage contract on the Goerli blockchain. The contract functions can be called while the contract is waiting to be mined.
Contract pending deploy: 0x46506d900559ad005feb4645dcbb2dbbf65e19cc
Transaction waiting to be mined: 0x6a81231874edd2461879b7280ddde1a857162a744e3658ca7ec276984802183b
Pending name: Storage contract in Go!
Once mined, the contract exists permanently at its deployment address and can now be interacted with from other applications without ever needing to be redeployed.
Note that DeployStorage returns four variables:
address: the deployment address of the contract
tx: the transaction hash that can be queried using Geth or a service like Etherscan
instance: an instance of the deployed contract whose functions can be called in the Go application
err: a variable that handles errors in case of a deployment failure
Accessing an Ethereum contract
To interact with a contract already deployed on the blockchain, the deployment address is required and a backend through which to access Ethereum must be defined. The binding generator provides an RPC backend out-of-the-box that can be used to attach to an existing Ethereum node via IPC, HTTP or WebSockets.
As in the previous section, a Geth node running on an Ethereum testnet (recommend Goerli) and an account with some test ETH to cover gas is required. The Storage.sol deployment address is also needed.
Again, an instance of ethclient can be created, passing the path to Geth’s ipc file. In the example below this backend is assigned to the variable conn.
// Create an IPC based RPC connection to a remote node
// NOTE update the path to the ipc file!
conn, err := ethclient.Dial("/home/go-ethereum/goerli/geth.ipc")
if err != nil {
log.Fatalf("Failed to connect to the Ethereum client: %v", err)
}
The functions available for interacting with the Storage contract are defined in Storage.go. To create a new instance of the contract in a Go application, the NewStorage() function can be used. The function is defined in Storage.go as follows:
// NewStorage creates a new instance of Storage, bound to a specific deployed contract.
func NewStorage(address common.Address, backend bind.ContractBackend) (*Storage, error) {
contract, err := bindStorage(address, backend, backend, backend)
if err != nil {
return nil, err
}
return &Storage{StorageCaller: StorageCaller{contract: contract}, StorageTransactor: StorageTransactor{contract: contract}, StorageFilterer: StorageFilterer{contract: contract}}, nil
}
NewStorage() takes two arguments: the deployment address and a backend (conn) and returns an instance of the deployed contract. In the example below, the instance is assigned to store.
package main
import (
"fmt"
"log"
"github.com/ethereum/go-ethereum/common"
"github.com/ethereum/go-ethereum/ethclient"
)
func main() {
// Create an IPC based RPC connection to a remote node
// NOTE update the path to the ipc file!
conn, err := ethclient.Dial("/home/go-ethereum/goerli/geth.ipc")
if err != nil {
log.Fatalf("Failed to connect to the Ethereum client: %v", err)
}
// Instantiate the contract and display its name
// NOTE update the deployment address!
store, err := NewStorage(common.HexToAddress("0x21e6fc92f93c8a1bb41e2be64b4e1f88a54d3576"), conn)
if err != nil {
log.Fatalf("Failed to instantiate Storage contract: %v", err)
}
The contract instance is then available to interact with in the Go application. To read a value from the blockchain, for example the value stored in the contract, the contract’s Retrieve() function can be called. Again, the function is defined in Storage.go as follows:
// Retrieve is a free data retrieval call binding the contract method 0x2e64cec1.
//
// Solidity: function retrieve() view returns(uint256)
func (_Storage *StorageCaller) Retrieve(opts *bind.CallOpts) (*big.Int, error) {
var out []interface{}
err := _Storage.contract.Call(opts, &out, "retrieve")
if err != nil {
return *new(*big.Int), err
}
out0 := *abi.ConvertType(out[0], new(*big.Int)).(**big.Int)
return out0, err
}
Note that the Retrieve() function requires a parameter to be passed, even though the original Solidity contract didn’t require any at all none. The parameter required is a *bind.CallOpts type, which can be used to fine tune the call. If no adjustments to the call are required, pass nil. Adjustments to the call include:
  • Pending: Whether to access pending contract state or the current stable one
  • GasLimit: Place a limit on the computing resources the call might consume
So to call the Retrieve() function in the Go application:
value, err := store.Retrieve(nil)
if err != nil {
log.Fatalf("Failed to retrieve value: %v", err)
}
fmt.Println("Value: ", value)
The output will be something like:
Value: 56
Last modified 8mo ago