SGX Prover

This guide provides step-by-step instructions to set up the SGX prover for Surge using Docker. The SGX prover utilizes Intel's Software Guard Extensions (SGX) to create a secure environment for generating cryptographic proofs that validate Layer 2 blocks.

The SGX prover contains two components:

• sgx-reth prover - Rust SGX prover that generates proofs for the rollup
• sgx-geth (Gaiko) prover - Golang SGX prover that generates proofs for the rollup

Prerequisites

• Machine with SGX support
• Docker
• L1 Accounts with funds (one for the prover, one for prover registry)
• L1 RPC URL

1. Fetch Collateral Information

tip

You can skip this section if you have already set up the PCCS configuration before.

First, fetch the collateral information from Intel:

FMSPC="00906ED50000"

TCB_FILE="tcb.json"
QE_IDENTITY_FILE="qe_identity.json"

curl -X GET "https://api.trustedservices.intel.com/sgx/certification/v3/tcb?fmspc=${FMSPC}" > ${TCB_FILE}
curl -X GET "https://api.trustedservices.intel.com/sgx/certification/v3/qe/identity" > ${QE_IDENTITY_FILE}

jq '.tcbInfo.fmspc |= ascii_downcase' ${TCB_FILE} > temp.json && mv temp.json ${TCB_FILE}

2. Generating PCCS Certificates

tip

You can skip this section if you have already generated the PCCS configuration before.

Before running the Raiko Docker container, you need to fulfill some SGX-specific prerequisites, which include setting up the PCCS (Provisioning Certificate Caching Service) configuration. The PCCS service is responsible for retrieving PCK Certificates and other collaterals on-demand from the internet at runtime, and then caching them in a local database. The PCCS exposes similar HTTPS interfaces as Intel's Provisioning Certificate Service.

Begin the configuration process by generating an SSL certificate:

mkdir ~/.config
mkdir ~/.config/sgx-pccs
cd ~/.config/sgx-pccs
openssl genrsa -out private.pem 2048
chmod 644 private.pem  # Docker container needs access
openssl req -new -key private.pem -out csr.pem
openssl x509 -req -days 365 -in csr.pem -signkey private.pem -out file.crt
rm csr.pem

Download the configuration file:

curl -s https://raw.githubusercontent.com/taikoxyz/raiko/refs/heads/main/docs/default.json > ~/.config/sgx-pccs/default.json

Copy the default.json file to the .config/sgx-pccs directory you created earlier. The Raiko container will mount this as a volume. Open the file for editing and configure the following parameters as recommended by Intel's manual:

• ApiKey: The PCCS uses this API key to request collaterals from Intel's Provisioning Certificate Service. You need to subscribe first to obtain an API key. Use either the primary or secondary key obtained from subscribing to Intel PCS Service.

• UserTokenHash: SHA512 hash of the user token for the PCCS client to register a platform. The PCK Cert ID retrieval tool uses this token to send platform information to PCCS. Generate using: echo -n "user_password" | sha512sum | tr -d '[:space:]-'

• AdminTokenHash: SHA512 hash of the administrator token for manual refresh of cached artifacts. Generate using: echo -n "admin_password" | sha512sum | tr -d '[:space:]-'

• hosts: Replace with "0.0.0.0"

Ensure Docker can access the file by modifying its permissions:

chmod 644 default.json

3. Setup Chain Spec and Config

Both chain_spec_list.json and config.json files are placed in raiko/host/config/devnet for devnet and raiko/host/config/testnet for testnet. You can edit existing configs or create new ones based on your chain configuration.

tip

In Simple Surge Node, the surge-protocol-deployer.sh deployment script will generate chain_spec_list.json for you after the Running provers? (true/false) [default: false] prompt.

You just need to copy it from simple-surge-node/configs/chain_spec_list_default.json into your prover config folder (e.g., raiko/host/config/devnet/chain_spec_list.json).

Here are the most important parameters to check in config.json:

• address: The address of the prover server
• network: The network name of the L2
• concurrency_limit: The number of concurrent proving tasks the prover can handle. Note that this value should be set to the number of GPUs available on the prover machine.
• l1_network: The network name of the L1
• ballot_zk: Configuration for zk_any request
• ballot_sgx: Configuration for sgx_any request

This config.json file is used as the default proof request config, but clients can override it with specific values.

note

The chain_spec_list.json file is generated when deploying the protocol. You should copy it as-is. Don't change anything in this file unless you know what you're doing.

4. Configure Environment Variables

Copy the sample .env file:

cd raiko/docker
cp .env.sample .env

Edit the .env file and configure the following important variables:

• RAIKO_CONF_DIR - Directory where your Raiko configuration files are stored
• BASE_CONFIG_FILE - Base configuration file for Raiko inside $RAIKO_CONF_DIR
• BASE_CHAINSPEC_FILE - Base chainspec file for Raiko inside $RAIKO_CONF_DIR
• SGX_*_INSTANCE_ID - SGX Instance ID for specific hardfork
• SGXGETH_*_INSTANCE_ID - SGXGeth (Gaiko) Instance ID for specific hardfork
• RUST_LOG - Log level for Rust (info, debug, warn, error, or trace)

tip

You can leave RAIKO_CONF_DIR, BASE_CONFIG_FILE, and BASE_CHAINSPEC_FILE as default if you have placed your config files in raiko/host/config/devnet.

Environment variables SGX_*_INSTANCE_ID and SGXGETH_*_INSTANCE_ID will be generated for you in Simple Surge Node surge-protocol-deployer.sh deployment script after Running provers? (true/false) [default: false] prompt.

5. Build and Run the Prover

You have two options to run the prover:

• Use a pre-built image from Docker Hub
• Build the image yourself

Using Pre-built Image from Docker Hub

The docker-compose.yml file uses the latest Raiko SGX image from Docker Hub by default. Run the following commands:

cd docker # Navigate to the docker directory inside raiko
docker compose up init # Initialize the prover
docker compose up raiko -d --force-recreate # Run the prover in detached mode

tip

If you want to re-initialize the prover, keep in mind that you need to delete existing keys:

rm -r ~/.config/raiko/secrets

To use a specific version, update the image tag in the docker-compose.yml file. Check the Raiko repository for available releases. Update the image field in docker/docker-compose.yml for both raiko and init services.

For example, if the latest release is v1.8.5-surge:

services:
  init:
    image: nethermind.jfrog.io/core-oci-local-prod/raiko-sgx:v1.8.5-surge
    ...
  raiko:
    image: nethermind.jfrog.io/core-oci-local-prod/raiko-sgx:v1.8.5-surge
    ...

Build the Image Yourself

You may want to build the image yourself if you have made local changes to the Raiko codebase or want to use a specific commit.

To build the image from the raiko directory:

cd docker # Navigate to the docker directory inside raiko
docker compose up init --build # Build and Init the prover
docker compose up raiko -d --force-recreate --build # Build and Run the prover

tip

If you want to re-initialize the prover, keep in mind that you need to delete existing keys:

rm -r ~/.config/raiko/secrets

6. Verify the Prover is Running

Your SGX prover should now be operational. To verify it's running correctly, check the container logs:

docker logs -f raiko

note

If you encounter any issues while following these instructions, refer to the Raiko Docker and RA Documentation for additional guidance.

7. Next Steps

Next you can set up an SP1 & RISC Zero prover by following the instructions in the SP1 & RISC Zero Prover guide.

If you have already done it, the next step is to register your provers in the protocol. Follow the instructions in the Register Provers guide.