The `go-ethereum` library is distributed as a collection of standard Go packages straight
from our GitHub repository. The packages can be used directly via the official Go toolkit,
without needing any third party tools. External dependencies are vendored locally into
`vendor`, ensuring both self-containment as well as code stability. If you reuse
`go-ethereum` in your own project, please follow these best practices and vendor it
yourself too to avoid any accidental API breakages!
The `go-ethereum` library is distributed as a collection of standard Go packages straight from go-ethereum's
GitHub repository. The packages can be used directly via the official Go toolkit, without needing any
third party tools.
The canonical import path for `go-ethereum` is `github.com/ethereum/go-ethereum`, with all
packages residing underneath. Although there are [quite a number][go-ethereum-dir] of
them, you'll only need to care about a limited subset, each of which will be properly
introduced in their relevant section.
The canonical import path for Geth is `github.com/ethereum/go-ethereum`, with all packages residing
underneath. Although there are [lots of them][go-ethereum-dir] most developers will only care about
a limited subset.
You can download all our packages via:
All the Geth packages can be downloaded using:
```
$ go get -d github.com/ethereum/go-ethereum/...
```
More Go API support for dapp developers can be found on the [Go Contract Bindings](/docs/dapp/native-bindings)
and [Go Account Management](/docs/dapp/native-accounts) pages.
## Tutorial
This section includes some basic usage examples for the `ethclient` and `gethclient` packages available as
part of the Go API. The `ethclient` package provides a client that implements the full Ethereum JSON-RPC API,
whereas `gethclient` offers the Geth-specific API.
### Instantiating a client
The client is an instance of the `Client` struct which has associated functions that wrap requests to the Ethereum
or Geth RPC API endpoints.
A client is instantiated by passing a raw url or path to an ipc file to the client's `Dial` function. In the following
code snippet the path to the ipc file for a local Geth node is provided to `ethclient.Dial()`.
```go
// create instance of ethclient and assign to cl
cl, err := ethclient.Dial("/tmp/geth.ipc")
if err != nil {
panic(err)
}
_ = cl
```
### Interacting with the client
The client can now be used to handle requests to the Geth node using the full JSON-RPC API. For example, the function
`BlockNumer()` wraps a call to the `eth_blockNumber` endpoint. The function `SendTransaction` wraps a call to
`eth_sendTransaction`. The full list of client methods can be found [here][ethclient-pkg].
Frequently, the functions take an instance of the `Context` type as their leading argument. This defines context about requests sent from the application such as deadlines, cancellation signals etc. More information on this can
be found in the [Go documentation](https://pkg.go.dev/golang.org/x/net/context). An empty context instance can be
created using `Context.Background()`.
### Querying client for data
A simple starting point is to fetch the chain ID from the client. This e.g. is needed when signing a transaction as is to be seen in the next section.
```go
chainid, err := cl.ChainID(context.Background())
if err != nil {
return err
}
```
Unlike `ChainID`, many functions require arguments other than context. The Go API takes in and returns high-level types which are used in Geth internals as well to simplify programming and remove the need for knowing how data needs to be formatted exactly as per the JSON-RPC API spec. For example to find out the nonce for an account at a given block the address needs to be provided as a `common.Address` type and the block number as a `*big.Int`:
Contracts emit events during execution which can be queried from the client. The parameters for the event one is interested in have to be filled out in the `ethereum.FilterQuery` object. This includes which event topics are of interested, from which contracts and during which range of blocks. The example below queries `Transfer` events of all ERC-20 tokens for the last 10 blocks:
Joseph Cook
3 years ago
committed by
GitHub
