forky

package module
v1.0.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 11, 2026 License: GPL-3.0 Imports: 12 Imported by: 0

README

Forky

Forky captures, stores and visualizes fork choice data from the Ethereum Beacon Chain. Forky is designed to provide a live view of the Ethereum network, along with historical access.

Live Versions

Mainnet

Hoodi

Holesky

Sepolia

Contents

Features

  • Web interface for viewing fork choice data
  • Configurable retention period
  • Prometheus metrics

Capturing

  • Ethereum Beacon Node
  • Xatu

Storing

  • Memory
  • Filesystem
  • S3

Indexing

  • Sqlite
  • Postgres

Usage

Forky requires a config file. An example file can be found here.

forky - fetches and serves Ethereum fork choice data

Usage:
  forky [flags]

Flags:
      --config string   config file (default is config.yaml) (default "config.yaml")
  -h, --help            help for forky

Getting Started

Download a release

Download the latest release from the Releases page. Extract and run with:

./forky --config your-config.yaml

Docker

Available as a docker image at ethpandaops/forky

Images
  • latest - distroless, multiarch
  • latest-debian - debian, multiarch
  • $version - distroless, multiarch, pinned to a release (i.e. 0.1.0)
  • $version-debian - debian, multiarch, pinned to a release (i.e. 0.1.0-debian)

Quick start

docker run -d  --name forky -v $HOST_DIR_CHANGE_ME/config.yaml:/opt/forky/config.yaml -p 9090:9090 -p 5555:5555 -it ethpandaops/forky:latest --config /opt/forky/config.yaml;
docker logs -f forky;

Kubernetes via Helm

Read more

helm repo add ethereum-helm-charts https://ethpandaops.github.io/ethereum-helm-charts

helm install forky ethereum-helm-charts/forky -f your_values.yaml

Building yourself

  1. Clone the repo 
    git clone https://github.com/ethpandaops/forky.git
  2. Change directories 
    cd ./forky
  3. Build the binary (embeds the web frontend; requires pnpm) 
    make build-web && make build
  4. Run the service 
    ./forky --config your_config.yaml

Contributing

Contributions are greatly appreciated! Pull requests will be reviewed and merged promptly if you're interested in improving the forky!

  1. Fork the project
  2. Create your feature branch:
    • git checkout -b feat/new-feature
  3. Commit your changes:
    • git commit -m 'feat(profit): new feature
  4. Push to the branch: -git push origin feat/new-feature
  5. Open a pull request

Running locally

Backend
go run ./cmd/forky --config your_config.yaml
Frontend

A frontend is provided in this project in ./web directory which needs to be built before it can be served by the server, eg. http://localhost:5555.

The frontend can be built with the following command;

# install node modules and build
make build-web

Building the frontend requires pnpm and NodeJS to be installed. For frontend development, pnpm --dir web dev starts a Vite dev server that proxies /api to a backend (see web/vite.config.ts).

Contact

Sam - @samcmau

Andrew - @savid

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Config 

type Config struct {
	ListenAddr string        `yaml:"listen_addr" default:":5555"`
	LogLevel   string        `yaml:"log_level" default:"warn"`
	Metrics    MetricsConfig `yaml:"metrics"`
	PProfAddr  *string       `yaml:"pprof_addr" default:":6060"`

	Forky *service.Config `yaml:"forky"`

	HTTP *api.Config `yaml:"http" default:"{}"`
}

func NewConfigFromYAML 

func NewConfigFromYAML(y []byte) (*Config, error)

func NewConfigFromYAMLFile 

func NewConfigFromYAMLFile(file string) (*Config, error)

func (*Config) Validate 

func (c *Config) Validate() error

type MetricsConfig 

type MetricsConfig struct {
	Enabled bool   `yaml:"enabled" default:"true"`
	Addr    string `yaml:"addr" default:":9090"`
}

type NotFoundRedirectRespWr 

type NotFoundRedirectRespWr struct {
	http.ResponseWriter
	// contains filtered or unexported fields
}

func (*NotFoundRedirectRespWr) Write 

func (w *NotFoundRedirectRespWr) Write(p []byte) (int, error)

func (*NotFoundRedirectRespWr) WriteHeader 

func (w *NotFoundRedirectRespWr) WriteHeader(status int)

type Server 

type Server struct {
	Cfg Config
	// contains filtered or unexported fields
}

Server is the main server for the forkchoice service. It glues together the service and the http api, while also providing metrics and static file serving.

func NewServer 

func NewServer(log *logrus.Logger, conf *Config) *Server

func (*Server) ServeMetrics 

func (s *Server) ServeMetrics(ctx context.Context) error

func (*Server) ServePProf 

func (s *Server) ServePProf(ctx context.Context) error

func (*Server) Start 

func (s *Server) Start(ctx context.Context) error

Source Files

View all Source files

Directories

Path Synopsis
api
Package api contains the OpenAPI specification and the generated server.
 Package api contains the OpenAPI specification and the generated server.
rest
Code generated by ogen, DO NOT EDIT.
 Code generated by ogen, DO NOT EDIT.
cmd
forky command
Command forky fetches and serves Ethereum fork choice data.
 Command forky fetches and serves Ethereum fork choice data.
internal
api
Package api implements the Forky HTTP API as defined by the OpenAPI spec at api/openapi.yaml.
 Package api implements the Forky HTTP API as defined by the OpenAPI spec at api/openapi.yaml.
db
ethereum
human
service
source
store
types
version
yaml
Package web provides the frontend filesystem.
 Package web provides the frontend filesystem.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.