Block Root Oracle Project

Implementation Plan

• Set up relevant structs for the checkpoints, validation process, and journal
• Set up admin role with RBAC configuration
• Constructor configuration for (1) initial checkpoint to verify from, (2) allowed time span since last transition, (3) trusted R0 verifier address, (4) ImageID
• Verification function using the R0 verifier, ImageID, journal and seal.
• Testing of admin functions
• Testing of Verification/transition function
• Integration of Wormhole
• Testing of Wormhole VAA
• Testing of Confirmation logic between Wormhole and RZ
• Testing BeaconEmitter
• Testing End-to-end from BeaconEmitter to Prover
• Interface and documentation
• Rename BoundlessReceiver references to BlockRootOracle in lieu of the incoming BoundlessTransceiver
• Complete documentation updates for all contracts

References

• https://hackmd.io/QSDlFbuKToScQ43jISuvFA
• Signal ZKVM Guest program: https://github.com/boundless-xyz/Signal-Ethereum
• Proofs: https://signal-proofs-v1-20250710153907748200000003.s3.us-west-2.amazonaws.com/v1/epoch/378541.json

Overview

The Block Root Oracle Project provides a secure system for managing and validating Ethereum beacon chain block roots with dual confirmation from both RISC Zero zero-knowledge proofs and Wormhole cross-chain messaging.

Key components:

• BlockRootOracle.sol: Main contract that manages beacon block roots with dual confirmation system
• BeaconEmitter.sol: Contract that emits beacon block roots via Wormhole messaging
• Beacon.sol: Library for interacting with Ethereum beacon chain data and block roots
• Dual Confirmation System: Combines RISC Zero proofs (Boundless) with Wormhole attestations for enhanced security

This project uses:

• Forge: Compile, test, fuzz, format, and deploy smart contracts
• Bun: Modern package management (instead of git submodules)
• Forge Std: Testing utilities and helpful contracts
• Solhint: Solidity linting

Development

Dependencies

This template uses Node.js packages instead of git submodules for better scalability. To add dependencies:

1. Install via package manager: bun install dependency-name
   • From GitHub: bun install github:username/repo-name
2. Add to remappings.txt: dependency-name=node_modules/dependency-name

OpenZeppelin Contracts comes pre-installed as an example.

Testing

Write tests by importing Test from forge-std. Access cheatcodes via the vm property. Example test in Foo.t.sol.

For detailed logs, use the -vvv flag and console.log.

Editor Support

• VSCode: Use with Solidity extension. Setup guide
• (Neo)Vim: Use lspconfig following these instructions

CI/CD

GitHub Actions automatically lint and test on push/PR to main. Configure in .github/workflows/ci.yml.

Usage

Common Commands

# Build
$ forge build

# Test
$ forge test
$ forge test --gas-report # CLI-based gas report
$ bun run test:coverage
$ bun run test:coverage:report  # Requires lcov: brew install lcov

# Linting & Formatting
$ bun run lint
$ forge fmt

# Deployment
$ forge script script/Deploy.s.sol --broadcast --fork-url http://localhost:8545 [--verify]
# NOTE: --verify will work iff the `etherscan` section in foundry.toml
# is specified for the dedicated rpc

# With wallet management:
$ forge script script/Deploy.s.sol --broadcast --fork-url http://localhost:8545 \
  --account <wallet-name> --froms <wallet-address> --sender <wallet-address>

Project Structure

├── .editorconfig
├── .gitignore
├── .solhint.json
├── AGENTS.md
├── foundry.toml
├── remappings.txt
└── README.md

Smart Contract Structure

src/
├── BlockRootOracle.sol          # Main contract for beacon block root management
├── BeaconEmitter.sol            # Contract for emitting beacon roots via Wormhole
├── tseth.sol                    # Core data structures (Checkpoint, ConsensusState)
├── interfaces/
│   └── IRiscZeroVerifier.sol    # Interface for RISC Zero verifier
└── lib/
    ├── Beacon.sol               # Beacon chain utilities
    ├── RiscZeroVerifier.sol     # RISC Zero verification structures
    └── Util.sol                 # Utility functions

Related Projects

• PaulRBerg/foundry-template
• foundry-rs/forge-template
• abigger87/femplate
• cleanunicorn/ethereum-smartcontract-template
• FrankieIsLost/forge-template

License

This project is licensed under MIT.