Tracoor

Tracoor captures, stores and makes available beacon states, beacon blocks, execution debug traces, execution bad blocks and invalid gossiped verified blocks.

Live Versions

Mainnet

Hoodi

Holesky

Sepolia

Contents

• Features

• Usage
  • Server
  • Agent
• Getting Started
  • Download a release
  • Docker
    • Images
  • Kubernetes via Helm
  • Building yourself

• Contributing
  • Running locally
    • Backend
    • Frontend
• Contact

Features

• Web interface for viewing beacon states, execution block traces and invalid execution blocks
• Configurable retention period
• Prometheus metrics

Capturing

• Ethereum Beacon Node
• Ethereum Execution Node

Storing

• S3

Indexing

• Postgres

Usage

Tracoor has two components, a server and an agent. The server has a web interface and serves the data captured by the agent. The agent captures data from the Ethereum Beacon Node and Ethereum Execution Node.

Server

Tracoor server requires a config file. An example file can be found here.

Runs tracoor in Server mode, which means it will listen to gRPC requests from
	tracoor agent nodes and forward the data on to the configured sinks.

Usage:
  tracoor server [flags]

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

Promotion service (interesting states corpus)

The server can optionally run a promotion service that watches the short-retention capture buffer with hindsight and copies "interesting" consensus captures — as a replayable (parent post-state, block) pair plus a manifest.json — into a separate, global, append-only S3 bucket that outlives every devnet. Interesting means: slashings, exits, deposits, execution requests, missed-block runs, reorgs (both branches), fork boundaries, low sync participation, undecodable (brand-new) forks, plus a periodic baseline. Three per-network hourly rate budgets bound volume: a common one for repetitive symptoms, a separate one for rare events so they never compete with floods, and a deliberately generous one for reorgs. The service never deletes anything and keeps no persistent state.

Devnets are recreated under the same name constantly, so the service tracks each network's genesis validators root and rebuilds its cursor when the chain behind a name changes or loses height.

The corpus layout is self-describing:

v1/states/<sha256-of-raw-ssz>.ssz                       # uncompressed, content-addressed
v1/captures/<network>/<fork>/<capture_id>/input.ssz     # the SignedBeaconBlock, raw
v1/captures/<network>/<fork>/<capture_id>/manifest.json

See the services.promotion section of the example config. It is opt-in, requires the beacon state/block retention to exceed the configured processing lag, and requires a corpus store distinct from the capture buffer's.

Agent

Tracoor agent requires a config file. An example file can be found here.

Runs tracoor in agent mode, which means it will listen for events from
	an Ethereum beacon node and forward the data on to 	the configured sinks.

Usage:
  tracoor agent [flags]

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

Getting Started

Download a release

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

./tracoor --help

Docker

Available as a docker image at ethpandaops/tracoor

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 tracoor -v $HOST_DIR_CHANGE_ME/config.yaml:/opt/tracoor/config.yaml -p 9090:9090 -p 5555:5555 -it ethpandaops/tracoor:latest server --config /opt/tracoor/config.yaml;
docker logs -f tracoor;

Kubernetes via Helm

• tracoor-server
• tracoor-agent

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

# server
helm install tracoor ethereum-helm-charts/tracoor-server -f your_values.yaml

# agent
helm install tracoor ethereum-helm-charts/tracoor-agent -f your_values.yaml

Building yourself

1. Clone the repo

   go get github.com/ethpandaops/tracoor
   

2. Change directories

   cd ./tracoor
   

3. Build the binary

    go build -o tracoor .
   

4. Run the server

    ./tracoor server --config example_server_config.yaml
   

5. Run the agent

    ./tracoor agent --config example_agent_config.yaml
   

Contributing

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

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

Server

go run main.go server --config example_server_config.yaml

Agent

go run main.go agent --config example_agent_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 frontend requires npm and NodeJS to be installed.

Contact

Sam - @samcmau

Andrew - @savid