zk-eth-rng: Utilities for Randomness On Ethereum

This repository contains contracts, circuits, and scripts related to generating and providing randomness for Ethereum's execution layer.

Meant to accompany the eth-rng blog post.

Getting Started

To get started with this repo, you will need to have the following set up on your machine:

• Foundry to compile contracts and run Solidity tests
• Yarn and Node.js for running Typescript util scripts
• Circom to interact with our circuits

Setup

Circuit setup

cd circuits && yarn install

This automatically downloads a powers of tau file required for generating ZKPs. This download might take a while.

Script setup

cd scripts && yarn install

Directory Structure

The project is structured as a mixed Solidity, Circom, and Typescript workspace.

├── circuits  // <-- Circom source code
├── contracts // <-- Solidity source code
├── scripts   // <-- Block header & proof generation utils

Block Hash Oracle

• Blockhash oracle interface contract
• Blockhash opcode based oracle contract implementation, checkpointing block hashes via opcode lookup
• ZK circuit proving the parent blockhash of an already verified block via RLP deserialization, with script to aid proof generation and corresponding block hash oracle contract implementation
• Helper script to generate raw data used in the ZK circuit; example of consuming illustrated in ZKBlockhashOracleTest

To run Solidity tests:

cd contracts
forge test --match-contract "BlockhashOpcodeOracleTest|ZKBlockhashOracleTest"

To generate proof calldata for the ZK blockhash oracle contract:

# The circuit proves the parent hash of the specified BLOCK_NUM.
cd scripts
BLOCK_NUM=8150150 RPC_URL=https://ethereum-goerli-rpc.allthatnode.com ./run_single_block_zkp.sh

Randomness Interface and Provider

• Randomness provider interface
• RANDAO randomness provider implementation
• Helper scripts to generate properly formatted block data to fulfill randomness requests
• VDF reference implementation

To run Solidity tests:

cd contracts
forge test --match-contract "RANDAOOracleTest"

Optional: To generate new test data for the RANDAO-based randomness provider use the Typescript helper script:

cd scripts
yarn install
yarn ts-node generateBlockInfo.ts --blockNum 15539395 --rpc https://ethereum-mainnet-rpc.allthatnode.com

This will write a new JSON testdata file to contracts/testdata/blockheaderinfo. To include this block in the test, add the block number to the array similar to this example.

License

ZK related circuits & contracts and their tests are licensed under GPL 3.0 due to circom's license:

• singleBlockHeader.circom
• SingleBlockHeaderVerifier.sol
• ZKBlockhashOracle.sol

These contracts and their tests are licensed under MIT:

• IBlockhashOracle.sol
• BlockhashOpcodeOracle.sol
• IRandomnessProvider.sol
• RANDAOProvider.sol

All code under scripts is licensed under MIT.

Disclaimer

Contracts and circuits are unoptimized, unaudited, and experimental — use at your own risk! Issues and pull requests are welcome.