contributoor

README

contributoor

Contributoor is a lightweight service that runs alongside an Ethereum consensus client and collects data via the client's APIs. It's a streamlined, user-friendly extraction of the sentry service from ethpandaops/xatu.

📦 Installation

See the contributoor-installer repository for supported platforms and installation instructions.

🚀 Getting Started

Once installed, you can manage the Contributoor service using these commands:

contributoor start    # Start the service
contributoor stop     # Stop the service
contributoor status   # Check service status
contributoor restart  # Restart the service
contributoor config   # View/edit configuration
contributoor update   # Update the service to the latest version
contributoor logs     # Show logs

⚙️ Configuration

The contributoor-installer will generate a config.yaml file for you.

If you encounter configuration issues, you can:

1. Compare your config with the example below
2. Remove the config file and re-run contributoor install to generate a fresh one
3. Check the debug logs for detailed error messages

📄 View Example Config

# The address of your beacon node's HTTP API.
beaconNodeAddress: http://127.0.0.1:64692

# The address to serve metrics on (optional, disabled if empty).
metricsAddress: ":9090"

# The address to serve a health check on (optional, disabled if empty).
healthCheckAddress: ":9191"

# The log level (debug, info, warn, error).
logLevel: info

# The network name (NETWORK_NAME_MAINNET, NETWORK_NAME_SEPOLIA, NETWORK_NAME_HOLESKY).
networkName: NETWORK_NAME_MAINNET

# The output server configuration (credentials are base64 encoded and required if a pandaops server is used).
outputServer:
    address: xatu.primary.production.platform.ethpandaops.io:443
    credentials: <base64-encoded-value>
    tls: true

# The contributoor version to use.
version: 0.0.8

# The directory where contributoor stores its configuration and data.
contributoorDirectory: /Users/username/.contributoor

# The method to run contributoor (RUN_METHOD_DOCKER, RUN_METHOD_BINARY, RUN_METHOD_SYSTEMD).
runMethod: RUN_METHOD_DOCKER

Available CLI Flags

All configuration options can be overridden via CLI flags:

--config string                    # Config file path
--debug                           # Enable debug mode
--network string                  # Ethereum network name (mainnet, sepolia, holesky)
--beacon-node-address string      # Address of the beacon node API (e.g. http://localhost:5052)
--metrics-address string          # Address of the metrics server (e.g. :9091)
--health-check-address string     # Address of the health check server (e.g. :9191)
--log-level string               # Log level (debug, info, warn, error)
--username string                # Username for the output server
--password string                # Password for the output server
--output-server-address string    # Address of the output server (e.g. xatu.primary.production.platform.ethpandaops.io:443)
--output-server-tls string       # Enable TLS for the output server (true/false)
--contributoor-directory string   # Directory where contributoor stores configuration and data

Example with multiple flags:

go run ./cmd/sentry/main.go \
  --config ./config.yaml \
  --debug true \
  --network sepolia \
  --beacon-node-address http://localhost:5052 \
  --metrics-address localhost:9091 \
  --log-level debug

🔨 Development

Running Locally

To run Contributoor in development mode:

go run ./cmd/sentry/main.go --config /path/to/.contributoor/config.yaml --debug true

The config.yaml would have been generated for you by the installer.

Code Generation

Generate protocol buffers and other generated code:

go generate ./...
make proto

Testing

Run tests with race detection, coverage reporting, and view the coverage report:

go test -race -failfast -cover -coverpkg=./... -coverprofile=coverage.out ./... && go tool cover -html=coverage.out

📊 Share Your Node Data

Help improve Ethereum by contributing your node's data to our research. Data is published openly in a privacy-focused manner and used for research and analysis. Let us know if you're interested by completing this form.

🤝 Contributing Code

Contributoor is part of EthPandaOps' suite of tools for Ethereum network operations. Contributions are welcome! Please check our GitHub repository for more information.