# The Signal: Ethereum + Wormhole Integration notes

The Signal: Ethereum (TSEth) produces proofs that can be used to update a local view of the beacon chain consensus state (finalized and justified checkpoints) by compressing the verification of attestations using the RISC Zero ZKVM.

This project is to implement a contract capable of processing these proofs to follow the beacon chain and store trusted block roots, and to also include a Wormhole message receiver by which the Wormhole guardian network can provide a second opinion on block roots.

Block roots that are verified both by the ZK proof and by the Wormhole guardians (2-of-2) can be considered safe to use by consumers.

## Existing Work

This design could be considered identical to the [Hashi bridge aggregator](https://github.com/gnosis/hashi) and we may chose to use that implementation with the existing [Wormhole adapter](https://github.com/gnosis/hashi/blob/main/packages/evm/contracts/adapters/Wormhole/WormholeAdapter.sol) and a new custom adapter for TSEth which would be similar to the [SP1Helios adapter](https://github.com/gnosis/hashi/blob/main/packages/evm/contracts/adapters/SP1Helios/SP1HeliosAdapter.sol).

## Consensus State

We define the consensus state as:

struct Checkpoint {
    uint64 epoch;
    bytes32 root; // beacon block root for epoch boundary block
}

struct ConsensusState {
    Checkpoint current_justified_checkpoint;
    Checkpoint finalized_checkpoint;
}

A TSEth proof is a way to verify transition from a trusted current state, `pre_state`, to a new state, `post_state`.

This transition will usually, but not always, transition the `current_justified_checkpoint` to become the `finalized_checkpoint` and introduce a new `justified_checkpoint`.

Once a new state is trusted its `finalized_checkpoint` field can safely be used as a root of trust for further proofs into the chain. For this reason the most recent consensus state must be stored in the contract. This will never need to be rolled back unless there is a liveness failure.

## RISC0 Receipts and Journal

In RISC0 the output from the ZKVM execution for a particular program a set of inputs is called a receipt. It is made up of two parts - `journal` and `seal`. The journal contains the public outputs of the program while the seal is opaque cryptographic material required to verify the execution.

To verify a proof requires the journal, seal, and imageID. The result is a confirmation that the program with a given image ID asserts that the given journal is correct. The inputs to the program are hidden by default unless explicitly added to the journal.

[Example of verifying a RISC0 proof](https://github.com/risc0/risc0-ethereum/blob/fbda42566f4b379e1d439b5b16ae017b02f5f588/examples/erc20-counter/contracts/src/Counter.sol#L55)

The journal for TSEth is ABI encoded and has the form

struct Journal {
    ConsensusState pre_state;
    ConsensusState post_state;
}

This will be available to the contract when verifying a state transition.

A (seal, imageID, journalHash) tuple can be verified by calling the RISC0 verifier singleton contract which is deployed on all major EVM chains.

- [Deployed RISC0 Verifier contracts](https://dev.risczero.com/api/blockchain-integration/contracts/verifier)
- [Example use in forge tests](https://github.com/risc0/risc0-ethereum/blob/main/examples/erc20-counter/contracts/test/Counter.t.sol)

## Timing Considerations

It is important to keep track of the timing between state transitions to ensure these are sufficiently close together such that there hasn't been enough time for a large number of validators to exit and be able to conduct a long-range attack. This is very similar to the notion of weak-subjectivity.

Following the analysis of https://notes.ethereum.org/@adiasg/weak-subjectvity-eth2 a delay in the order of several days should be acceptable. This should be configurable by the contract admin.

If an update is not received within the required time period the contract should freeze and require a restart from a new trusted consensus state.

## Loss of Liveness Considerations

TSEth can follow the beacon chain under normal conditions however there are some cases that it cannot. These include:

- A fork upgrade
- Reorg of a justified checkpoint
- Occurence of 2-finality (currently unsupported)
- Period of non-finalization longer than 4 epochs

There is no need to check for any of these as if they occur it will be impossible to produce a valid proof and the contract should time out.

## Contract Roles

Since a liveness failure can occur it is a requirement that the contract can recover. It should be possible for a particular role (which in practice would be a threshold multisig) to restart the contract from a new trusted consensus state and resume operation.

They should also be able to update the ImageID which corresponds to an upgrade of the ZKVM guest code.

At this time I don't know the exact requirements for these roles but I will try and clarify.

## Obtaining Proofs

As of the 15/7/2025 TSEth proofs will be generated by the Boundless network for the ethereum beacon chain. These will be visible on https://explorer.beboundless.xyz/orders. Image ID TBD.

[example order](https://explorer.beboundless.xyz/orders/0x2546c553d857d20658ece248f7c7d0861a240681243dfde7?tab=more-details) where you can see the raw data for the journal, seal, and image ID in the explorer.

## Wormhole Integration

Wormhole will be used to receive a second opinion on the (epoch, block_root) tuple that makes up a finalized checkpoint. By using a 2-of-2 we are protected from a failure in the ZK proof or a compromise of the Wormhole guardian set (additive security).

### Emitter

On the Ethereum mainnet side a contract can read the beacon roots via [EIP-4788](https://eips.ethereum.org/EIPS/eip-4788) and obtain trusted beacon roots in the execution for a given slot. These should be relayed to the Ethereum Wormhole core contract and sent as a multicast message. This should use the [lower level messaging SDK](https://wormhole.com/docs/products/messaging/guides/core-contracts/) and not the relayers since relayers cannot support multicast.

Building it this way allows for a single message to be consumed by multiple destination chains, same as the ZK proofs.

### Receiver

The receiver should contain a function that accepts a single encoded VAA. It should delegate to the local deployment of Wormhole core contract to call `parseAndVerifyVM` and then check that the emitter Chain ID and contract match what is expected.

Once these checks have passed the (slot, blockRoot) tuple can be consumed by the contract and used as an attestation to any (epoch, blockRoot) tuples attested to by a ZK proof

> **Notes on slot/epoch conversions**
> The beacon chain has what are called Epoch Boundary Blocks (EBBs). See the [beacon chain checkpoints section of this doc](https://ethos.dev/beacon-chain). Typically these are the blocks at the beginning of an epoch and so to get the slot number for a given epoch just multiply it by 32.
> Unfortunately this isn't always true due to skipped slots. If the first slot of an epoch is skipped then the EBB of that epoch is last block in the previous epoch. Fortunately the EIP-4788 contract uses the same logic so