Initial public commit

.github/workflows/docker.yml

@@ -0,0 +1,30 @@
+name: docker
+
+permissions:
+  contents: read
+  packages: write
+
+on:
+  push:
+    branches: [ "master" ]
+    tags: [ v* ]
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Log in to GitHub Container Registry
+      uses: docker/login-action@v3
+      with:
+        registry: ghcr.io
+        username: ${{ github.actor }}
+        password: ${{ secrets.GITHUB_TOKEN }}
+
+    - name: Build the Docker image
+      run: docker build --build-arg GIT_TAG=${{ github.ref_name }} --build-arg GIT_COMMIT=$(git rev-parse HEAD) . -t ghcr.io/${{ github.repository_owner }}/vero:${{ github.ref_name }}
+
+    - name: Push the Docker image
+      run: docker push ghcr.io/${{ github.repository_owner }}/vero:${{ github.ref_name }}

.github/workflows/pre-commit.yml

@@ -0,0 +1,16 @@
+name: pre-commit
+
+on:
+  pull_request:
+    branches: [ "master" ]
+  push:
+    branches: [ "master" ]
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+    - uses: actions/setup-python@v3
+    - uses: pre-commit/[email protected]

.github/workflows/pytest.yml

@@ -0,0 +1,28 @@
+name: pytest
+
+on:
+  pull_request:
+    branches: [ "master" ]
+  push:
+    branches: [ "master" ]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python 3.12
+      uses: actions/setup-python@v3
+      with:
+        python-version: "3.12"
+    - name: Install dependencies
+      run: |
+        pip install --no-cache-dir uv==0.3.0
+        uv pip sync --system requirements.txt requirements-dev.txt
+    - name: Test with pytest
+      run: |
+        pytest --cov=src --cov-report=term-missing tests

.pre-commit-config.yaml

@@ -0,0 +1,30 @@
+repos:
+  # All files basic formatter
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: mixed-line-ending
+      - id: check-merge-conflict
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.6.1
+    hooks:
+      - id: ruff-format
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+        types_or: [python]
+        require_serial: true
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: 'v1.11.1'
+    hooks:
+    -   id: mypy
+        additional_dependencies: [types-pytz==2024.1.0.20240417]
+
+  - repo: https://github.com/hadolint/hadolint
+    rev: v2.12.0
+    hooks:
+      - id: hadolint-docker

CONTRIBUTING.md

@@ -0,0 +1,54 @@
+# Contributing
+
+Great to have you here as a future contributor!
+
+## Basic guidelines
+
+We try to adhere to the [Zen of Python](https://peps.python.org/pep-0020/),
+preferring simple code over complex code.
+Some of the code style and behavior is enforced using pre-commit
+hooks like `ruff` and `mypy`.
+
+### Simple changes
+
+Did you find a bug that is simple to fix? Or find a way to make something
+perform better with minimal changes?
+
+Feel free to create a PR right away, we love these kinds of PRs
+and will try to address them promptly!
+
+*Note on typo PRs: Due to people abusing PRs to public
+cryptocurrency-related repositories in the hopes of receiving
+airdrops, trivial typo PRs may not be merged at the discretion
+of the maintainers.*
+
+### Significant changes
+
+Vero's feature set and codebase have intentionally been kept to a minimum.
+This has two primary reasons - security and maintainability.
+
+For these reasons, large additions of code, complex changes, introductions
+of significant new features or introductions of new external dependencies
+may not be merged unless the advantages these changes bring are also
+significant.
+
+If you're considering working on a larger change that has not
+been discussed, please create an issue to discuss it before working on it.
+
+### Tests
+
+To run tests locally, install the dev requirements:
+
+```shell
+pip install -r requirements-dev.txt
+```
+
+Then run `pytest`.
+
+
+### Linting
+
+This repository uses pre-commit hooks for linting. In order
+to run these locally, first install pre-commit
+(`pip install pre-commit`).
+You should then be able to run `pre-commit run --all-files`.

Dockerfile

@@ -0,0 +1,40 @@
+ARG PYTHON_IMAGE_TAG="3.12-slim@sha256:105e9d85a67db1602e70fa2bbb49c1e66bae7e3bdcb6259344fe8ca116434f74"
+ARG VENV_LOCATION="/opt/venv"
+
+# Build image
+FROM docker.io/library/python:${PYTHON_IMAGE_TAG} as build
+
+WORKDIR /build
+
+RUN apt-get update && apt-get install --no-install-recommends -y git=1:2.39.2-1.1 && \
+   apt-get clean && rm -rf /var/lib/apt/lists/*
+
+ARG VENV_LOCATION
+ENV PATH="$VENV_LOCATION/bin:$PATH"
+RUN pip install --no-cache-dir uv==0.3.0 && uv venv ${VENV_LOCATION}
+COPY requirements.txt .
+RUN uv pip sync requirements.txt
+
+# App image
+FROM docker.io/library/python:${PYTHON_IMAGE_TAG}
+
+ARG VENV_LOCATION
+COPY --from=build $VENV_LOCATION $VENV_LOCATION
+ENV PATH="$VENV_LOCATION/bin:$PATH"
+
+WORKDIR /vero
+RUN groupadd -g 1000 vero && \
+    useradd --no-create-home --shell /bin/false -u 1000 -g vero vero && \
+    chown -R vero:vero /vero
+
+COPY src .
+
+EXPOSE 8000
+
+ARG GIT_TAG
+ARG GIT_COMMIT
+ENV GIT_TAG=$GIT_TAG
+ENV GIT_COMMIT=$GIT_COMMIT
+
+USER vero
+ENTRYPOINT ["python", "main.py"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Serenita
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,42 @@
+# Vero
+
+Vero is a multi-node validator client software
+implementation, targeting Ethereum and Gnosis Chain.
+
+Its most important goal is helping improve client diversity.
+
+## Documentation
+
+- [Why Vero?](./docs/why_vero.md)
+	- [Feature comparison](./docs/why_vero.md#feature-comparison)
+- [Compatibility](./docs/compatibility.md)
+- [Risks](./docs/risks.md)
+- [Running Vero](./docs/running_vero.md)
+	- [Using multiple beacon nodes](./docs/using_multiple_beacon_nodes.md)
+		- [Setup recommendations](./docs/using_multiple_beacon_nodes.md#setup-recommendations)
+	- [Slashing protection](./docs/slashing_protection.md)
+		- [Prevention](./docs/slashing_protection.md#prevention)
+		- [Detection](./docs/slashing_protection.md#detection)
+	- [Monitoring & Instrumentation](./docs/instrumentation.md)
+		- [Metrics](./docs/instrumentation.md#metrics)
+		- [Tracing](./docs/instrumentation.md#tracing)
+		- [Profiling](./docs/instrumentation.md#profiling)
+    - [CLI Reference](./docs/running_vero.md#cli-reference)
+
+## Contributing
+
+Contributions are welcome, see [CONTRIBUTING.md](./CONTRIBUTING.md)
+
+## Acknowledgements
+
+We'd like to acknowledge the work of all teams that helped shape Vero, including:
+
+- Ethereum and Gnosis Chain client teams, researchers and everyone else
+  working on these public goods
+- [@protolambda](https://github.com/protolambda) and his [Python SSZ implementation](https://github.com/protolambda/remerkleable)
+- [Kurtosis](https://github.com/kurtosis-tech/kurtosis)
+  and their contributions to
+  [ethereum-package](https://github.com/ethpandaops/ethereum-package)
+- The EF DevOps team and their continued work on amazing tooling like
+  [ethereum-package](https://github.com/ethpandaops/ethereum-package)
+  which helped thoroughly test Vero before launching it on testnet

compose-example.yaml

@@ -0,0 +1,10 @@
+services:
+  validator-client:
+    container_name: validator-client
+    image: ghcr.io/serenita-org/vero:master
+    command:
+      - "--remote-signer-url=http://remote-signer:9000"
+      - "--beacon-node-urls=http://beacon-node-1:1234,http://beacon-node-2:1234,http://beacon-node-3:1234"
+      - "--fee-recipient=0x0000000000000000000000000000000000000000"
+    volumes:
+      - "./data:/vero/data"

docs/README.md

@@ -0,0 +1,17 @@
+# Vero
+
+- [Why Vero?](./why_vero.md)
+	- [Feature comparison](./why_vero.md#feature-comparison)
+- [Compatibility](./compatibility.md)
+- [Risks](./risks.md)
+- [Running Vero](./running_vero.md)
+	- [Using multiple beacon nodes](./using_multiple_beacon_nodes.md)
+		- [Setup recommendations](./using_multiple_beacon_nodes.md#setup-recommendations)
+	- [Slashing protection](./slashing_protection.md)
+		- [Prevention](./slashing_protection.md#prevention)
+		- [Detection](./slashing_protection.md#detection)
+	- [Monitoring & Instrumentation](./instrumentation.md)
+		- [Metrics](./instrumentation.md#metrics)
+		- [Tracing](./instrumentation.md#tracing)
+		- [Profiling](./instrumentation.md#profiling)
+    - [CLI Reference](./running_vero.md#cli-reference)

docs/compatibility.md

@@ -0,0 +1,23 @@
+# Compatibility
+
+Vero regularly undergoes thorough testing against various CL and EL client combinations using [Kurtosis](https://github.com/kurtosis-tech/kurtosis) and the amazing [ethereum-package](https://github.com/ethpandaops/ethereum-package).
+
+It is currently compatible with all open-source Ethereum clients:
+
+|                | Compatible | Version  | Notes                                                                |
+|----------------|------------|----------|----------------------------------------------------------------------|
+| **Grandine**   | 🟡         | 0.4.0+   | Slashing SSE events not supported yet - slashing detection is slower |
+| **Lighthouse** | ✅          | v4.6.0+  |                                                                      |
+| **Lodestar**   | ✅          | v1.12.0+ |                                                                      |
+| **Nimbus**     | ✅          | v24.1.1+ |                                                                      |
+| **Prysm**      | ✅          | v4.2.0   |                                                                      |
+| **Teku**       | ✅          | 23.11.0+ |                                                                      |
+
+#### Legend
+✅ Everything works perfectly.
+
+🟡 Minor issues that do not prevent validator duties from working but they may not work ideally.
+
+🟠 Issues that may impact some validator duties occasionally.
+
+🔴 Major issues that prevent validator duties from being performed.

docs/instrumentation.md

@@ -0,0 +1,50 @@
+# Instrumentation
+
+## Metrics
+
+Vero exposes Prometheus metrics by default on the `/metrics` endpoint.
+
+This repository contains Grafana dashboards, see [grafana](../grafana). These provide an overview of performed duties, validator status, errors and connected beacon node scores.
+
+<p align="center">
+  <img alt="Overview" src="images/instrumentation/metrics_overview.png" width="80%" style="text-align: center">
+</p>
+
+<p align="center">
+  <img alt="Attestation Consensus" src="images/instrumentation/metrics_attestation_consensus.png" width="80%" style="text-align: center">
+</p>
+
+<p align="center">
+  <img alt="Duty Submission Time" src="images/instrumentation/metrics_duty_submission_time.png" width="80%" style="text-align: center">
+</p>
+
+## Tracing
+
+Vero can export tracing data to an OpenTelemetry-compatible endpoint using OpenTelemetry's SDK.
+
+Set the `OTEL_EXPORTER_OTLP_ENDPOINT` and `OTEL_EXPORTER_OTLP_PROTOCOL` (grpc) environment variables and tracing data will automatically be pushed to the specified endpoint.
+
+You may also set other OpenTelemetry-supported environment variables like `OTEL_TRACES_SAMPLER` or `OTEL_RESOURCE_ATTRIBUTES` . For a full list of supported variables refer to [https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/).
+
+### Examples
+
+#### Attestation
+
+![Attestation](images/instrumentation/tracing_attestation.png)
+
+#### Block Proposal
+
+![Block Proposal](images/instrumentation/tracing_block_proposal.png)
+
+## Profiling
+
+*(The latest Pyroscope SDK does not yet support Python 3.12 which Vero uses, therefore
+this form of instrumentation does not currently work.)*
+
+Vero supports continuous profiling using [Grafana Pyroscope's Python SDK](https://grafana.com/docs/pyroscope/latest/configure-client/language-sdks/python/). Profiling data is linked to traces, making it possible to inspect profiles for specific trace spans in Grafana using its ["Traces to profiles" feature](https://grafana.com/docs/pyroscope/latest/view-and-analyze-profile-data/profile-tracing/traces-to-profiles/).
+
+Set the `PYROSCOPE_SERVER_ADDRESS` environment variable and optionally add tags in the `PYROSCOPE_TAGS` environment variable in the following comma-separated format: `tag-name-1=tag-value-1,tag-name-2=tag-value-2`.
+
+<!-- TODO example image(s)-->
+
+Exporting profiling data is not recommended during normal usage and is mostly intended to be used to investigate performance issues.