mirror of
https://github.com/ethereum/go-ethereum.git
synced 2026-02-26 15:47:21 +00:00
docs: add page on using geth as a library (#33825)
Adds a page describing how to use geth as a library
This commit is contained in:
Sina M
GitHub
parent
258c573ac2
commit
0252701b35
3 changed files with 143 additions and 2 deletions
139
docs/developers/geth-as-a-library.md
Normal file
139
docs/developers/geth-as-a-library.md
Normal file
|
|
@ -0,0 +1,139 @@
|
|||
---
|
||||
title: Geth as a Library
|
||||
description: Geth is not just a client. It is also a composable Go library for building custom Ethereum applications and infrastructure.
|
||||
---
|
||||
|
||||
Geth is commonly known as a command-line Ethereum client, but it is also a well-structured Go library that can be imported into any Go project. The library code (everything outside `cmd/`) is licensed under LGPL v3, deliberately chosen to allow third-party use as a library. This means developers can build custom Ethereum nodes, specialized tooling, or entirely new infrastructure on top of battle-tested code that has been securing Ethereum mainnet since 2015.
|
||||
|
||||
This page provides an overview of what's possible. Each section links to deeper documentation where available.
|
||||
|
||||
## How Geth is structured {#architecture}
|
||||
|
||||
Geth's architecture separates cleanly into a **node container** and the **services** that run inside it:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ node.Node (the container) │
|
||||
│ │
|
||||
│ ┌────────────┐ ┌────────────────────────┐ │
|
||||
│ │ RPC Server │ │ P2P Server │ │
|
||||
│ │ HTTP/WS/IPC│ │ devp2p, discovery │ │
|
||||
│ └────────────┘ └────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌────────────────────────────────────────┐ │
|
||||
│ │ Registered services (Lifecycle) │ │
|
||||
│ │ - eth.Ethereum (chain + EVM + txpool) │ │
|
||||
│ │ - Your custom services │ │
|
||||
│ └────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌────────────────────────────────────────┐ │
|
||||
│ │ Account Manager + Key Store │ │
|
||||
│ └────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
The [`node`](https://pkg.go.dev/github.com/ethereum/go-ethereum/node) package manages the lifecycle: RPC servers, peer-to-peer networking, data directory, and account management. Services register into the node and get started/stopped together with it. The standard `geth` binary is just one way to wire these pieces together. You can easily write your own.
|
||||
|
||||
## Building a custom node {#custom-node}
|
||||
|
||||
The `geth` binary at `cmd/geth/main.go` is roughly 200 lines of CLI glue. The core is simple: create a `node.Node`, register the Ethereum service, start the node. A minimal custom node looks like this:
|
||||
|
||||
```go
|
||||
package main
|
||||
|
||||
import (
|
||||
"log"
|
||||
|
||||
"github.com/ethereum/go-ethereum/eth"
|
||||
"github.com/ethereum/go-ethereum/eth/ethconfig"
|
||||
"github.com/ethereum/go-ethereum/node"
|
||||
)
|
||||
|
||||
func main() {
|
||||
// Configure and create the node
|
||||
stack, err := node.New(&node.Config{
|
||||
DataDir: "/tmp/my-ethereum-node",
|
||||
HTTPHost: "127.0.0.1",
|
||||
HTTPPort: 8545,
|
||||
HTTPModules: []string{"eth", "net", "web3"},
|
||||
})
|
||||
if err != nil {
|
||||
log.Fatalf("Failed to create node: %v", err)
|
||||
}
|
||||
defer stack.Close()
|
||||
|
||||
// Register the Ethereum protocol
|
||||
ethCfg := ethconfig.Defaults
|
||||
if _, err := eth.New(stack, ðCfg); err != nil {
|
||||
log.Fatalf("Failed to register Ethereum service: %v", err)
|
||||
}
|
||||
|
||||
// Start the node
|
||||
if err := stack.Start(); err != nil {
|
||||
log.Fatalf("Failed to start node: %v", err)
|
||||
}
|
||||
log.Println("Node running...")
|
||||
stack.Wait()
|
||||
}
|
||||
```
|
||||
|
||||
This gives you a fully functional Ethereum node — syncing, P2P networking, JSON-RPC — in under 30 lines of Go. From here you can customise every aspect: swap in a custom genesis, register additional services, add your own RPC endpoints, or change how blocks are processed.
|
||||
|
||||
## What you can customize {#what-you-can-customize}
|
||||
|
||||
The following areas are available for customization when building on Geth as a library. Each links to more detailed documentation where available.
|
||||
|
||||
### Custom RPC APIs
|
||||
|
||||
Register new JSON-RPC namespaces on the node with your own methods. Any Go struct with exported methods can become an RPC service:
|
||||
|
||||
```go
|
||||
stack.RegisterAPIs([]rpc.API{{
|
||||
Namespace: "myapp",
|
||||
Service: &MyCustomAPI{backend: ethBackend},
|
||||
}})
|
||||
```
|
||||
|
||||
Clients can then call `myapp_myMethod` via HTTP, WebSocket or IPC. Subscriptions (pub/sub over WebSocket) are also supported: just return an `rpc.Subscription` from your method.
|
||||
|
||||
See the [JSON-RPC docs](/docs/interacting-with-geth/rpc) for the full RPC system documentation.
|
||||
|
||||
### Simulated blockchain
|
||||
|
||||
The [`ethclient/simulated`](https://pkg.go.dev/github.com/ethereum/go-ethereum/ethclient/simulated) package provides a full in-memory Ethereum blockchain for testing. It supports the entire `ethclient` API and lets you mine blocks on demand — no networking, no disk, no consensus client needed.
|
||||
|
||||
### Contract bindings
|
||||
|
||||
The `abigen` tool generates type-safe Go bindings from Solidity contract ABIs, giving you native Go functions for every contract method. See [Go contract bindings](/docs/developers/dapp-developer/native-bindings) and [v2 bindings](/docs/developers/dapp-developer/native-bindings-v2).
|
||||
|
||||
### P2P networking
|
||||
|
||||
Custom devp2p protocols can be registered on the node alongside the standard Ethereum protocol. This enables building application-specific peer-to-peer communication on top of Geth's networking stack.
|
||||
|
||||
### Transaction pool
|
||||
|
||||
The transaction pool is configurable with settings for price limits, account slot limits, and global pool sizes via `txpool.Config`. This lets you tune mempool behaviour for your specific use case.
|
||||
|
||||
## Key packages at a glance {#packages}
|
||||
|
||||
| Package | Purpose |
|
||||
|---|---|
|
||||
| [`node`](https://pkg.go.dev/github.com/ethereum/go-ethereum/node) | Node container, lifecycle, RPC server |
|
||||
| [`eth`](https://pkg.go.dev/github.com/ethereum/go-ethereum/eth) | Full Ethereum service (chain, txpool, syncing) |
|
||||
| [`eth/ethconfig`](https://pkg.go.dev/github.com/ethereum/go-ethereum/eth/ethconfig) | Configuration for the Ethereum service |
|
||||
| [`ethclient`](https://pkg.go.dev/github.com/ethereum/go-ethereum/ethclient) | Go client for the Ethereum JSON-RPC API |
|
||||
| [`ethclient/simulated`](https://pkg.go.dev/github.com/ethereum/go-ethereum/ethclient/simulated) | In-memory simulated blockchain for testing |
|
||||
| [`rpc`](https://pkg.go.dev/github.com/ethereum/go-ethereum/rpc) | JSON-RPC server and client framework |
|
||||
| [`accounts/abi/bind`](https://pkg.go.dev/github.com/ethereum/go-ethereum/accounts/abi/bind) | Contract binding generation and interaction |
|
||||
| [`p2p`](https://pkg.go.dev/github.com/ethereum/go-ethereum/p2p) | Peer-to-peer networking (devp2p) |
|
||||
| [`core/txpool`](https://pkg.go.dev/github.com/ethereum/go-ethereum/core/txpool) | Transaction pool |
|
||||
|
||||
## Further reading {#further-reading}
|
||||
|
||||
- [Go API](/docs/developers/dapp-developer/native) — Programmatic access via `ethclient` and `gethclient`
|
||||
- [Go Account Management](/docs/developers/dapp-developer/native-accounts) — Key management from Go
|
||||
- [Go Contract Bindings](/docs/developers/dapp-developer/native-bindings) — Type-safe contract interaction
|
||||
- [Go Contract Bindings v2](/docs/developers/dapp-developer/native-bindings-v2) — Next-generation bindings
|
||||
- [Dev mode](/docs/developers/dapp-developer/dev-mode) — Local development networks
|
||||
- [EVM tracing](/docs/developers/evm-tracing) — Custom tracers and live tracing
|
||||
- [JSON-RPC](/docs/interacting-with-geth/rpc) — RPC server documentation
|
||||
|
|
@ -5,11 +5,11 @@ description: Documentation for Geth developers and dapp developers
|
|||
|
||||
Welcome to the Geth Developer docs!
|
||||
|
||||
This section includes information for builders. If you are building decentralized apps on top of Geth, head to the [Dapp developers](#dapp-developers) docs. If you are developing Geth itself, explore the [Geth developers](#geth-developers) docs.
|
||||
This section includes information for builders. If you want to use Geth as a library to build custom nodes or infrastructure, start with [Geth as a Library](/docs/developers/geth-as-a-library). If you are building decentralized apps on top of Geth, head to the [Dapp developers](#dapp-developers) docs. If you are developing Geth itself, explore the [Geth developers](#geth-developers) docs.
|
||||
|
||||
## Dapp developers {#dapp-developers}
|
||||
|
||||
Geth has many features that support dapp developers. There are many built-in tracers implemented in Go or Javascript that allow developers to monitor what is happening in Geth from inside an app, and users can build their own custom tracers too. Geth also includes a suite of tools for interacting with Ethereum smart contracts using Geth functions using Go functions inside Go native applications. There is also information for Geth mobile developers.
|
||||
Geth includes a suite of tools for building decentralized applications: a Go client for the JSON-RPC API, type-safe contract bindings, account management, and EVM tracing.
|
||||
|
||||
- [Dev mode](/docs/developers/dapp-developer/dev-mode)
|
||||
- [Go API](/docs/developers/dapp-developer/native)
|
||||
|
|
|
|||
|
|
@ -90,6 +90,8 @@
|
|||
items:
|
||||
- id: Introduction
|
||||
to: /docs/developers
|
||||
- id: Geth as a Library
|
||||
to: /docs/developers/geth-as-a-library
|
||||
- id: Dapp developers
|
||||
items:
|
||||
- id: Dev mode
|
||||
|
|
|
|||
Loading…
Reference in a new issue