Run Helios client inside oyster from altair checkpoint

Oyster
1

Helios Client Inside the Oyster

Helios: Helios converts an untrusted centralized RPC endpoint into a safe unmanipulable local RPC for its users.

Oyster: Oyster CVM(Confidential Virtual Machine) enable secure and private computation in untrusted environments. By leveraging hardware-based encryption and secure enclaves

Goal: To reliably sync from the Altair checkpoint using a light client inside an oyster enclave environment

This article explains our workflow and observations

What is the Helios Light Client?

Helios is a lightweight Ethereum client that:

  • Bootstraps from a trusted checkpoint and sync to latest checkpoint
  • Verifies state using cryptographic proofs
  • Allows applications to fetch verified Ethereum data directly

Running Helios inside a secure enclave adds:

  • Integrity: The host cannot tamper with the client
  • Confidentiality: Sensitive state remains sealed
  • Attestation: External applications can verify that the client is running a trusted binary

Our modification allows Helios to serve the latest checkpoint directly after syncing from any given post-Altair checkpoint

How to build and deploy

1. Clone the Helios Repository

clone the official repository:

git clone https://github.com/a16z/helios.git
cd helios

2. Remove the hickory-dns Feature

Remove the hickory-dns feature from Cargo.toml and its usage in the code, as it is incompatible with oyster. Additionally can modify the code to serve the latest saved checkpoint from helios

3. Prepare Docker Environment

Create a Dockerfile and docker-compose.yml to containerize Helios for deployment inside an Oyster enclave:

Dockerfile

FROM rust:latest AS builder

RUN apt-get update && apt-get install -y \
    build-essential \
    git \
    pkg-config \
    libssl-dev \
    curl \
    ca-certificates \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /helios

COPY . .

RUN cargo build --release 

FROM debian:trixie-slim

RUN apt-get update && apt-get install -y \
    ca-certificates \
    curl \
    jq \
    iproute2 \
    iptables \
    ipset \
    net-tools \
    && rm -rf /var/lib/apt/lists/*


COPY --from=builder /helios/target/release/helios /usr/local/bin/helios
ENV PATH="/usr/local/bin:${PATH}"
WORKDIR /app

ENTRYPOINT helios ethereum \
  --execution-rpc ${EXECUTION_RPC} \
  --consensus-rpc ${CONSENSUS_RPC} \
  -w ${CHECKPOINT_DIR:-checkpoint} \
  -b "0.0.0.0" \
  -p ${PORT}

To build and push the image

docker build -t username/image .
docker push username/image

docker-compose.yml:

services:
  helios:
    image: username/image
    init: true
    network_mode: host
    restart: unless-stopped
    environment:
      EXECUTION_RPC: <execution_rpc>
      CONSENSUS_RPC: <consensus_rpc>
      CHECKPOINT_DIR: checkpoint
      PORT: port

  • We used alchemy rpc’s as execution_rpc

  • We pointed the client to a consensus RPC with historical data (e.g. Chainstack).

  • We used the altair checkpoint to start the sync

4. Deploy Helios inside oyster

Install oyster_cvm

# for linux, amd64
sudo wget https://artifacts.marlin.org/oyster/binaries/oyster-cvm_latest_linux_amd64 -O /usr/local/bin/oyster-cvm && sudo chmod +x /usr/local/bin/oyster-cvm

# for linux, arm64
sudo wget https://artifacts.marlin.org/oyster/binaries/oyster-cvm_latest_linux_arm64 -O /usr/local/bin/oyster-cvm && sudo chmod +x /usr/local/bin/oyster-cvm

# for darwin, arm64 (M series Macs)
sudo wget https://artifacts.marlin.org/oyster/binaries/oyster-cvm_latest_darwin_arm64 -O /usr/local/bin/oyster-cvm && sudo chmod +x /usr/local/bin/oyster-cvm

Deploy on oyster

oyster-cvm deploy --wallet-private-key <key> --duration-in-minutes 15 --docker-compose docker-compose.yml

Results and Observations

  • Helios ran successfully inside the Oyster

  • Successfully synced from Altair checkpoint in 3 mins and saves the checkpoint of the latest finalized block

  • RPC queries from outside the enclave worked as expected.