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:

These contracts and their tests are licensed under MIT:

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.

paradigmxyz/zk-eth-rng

paradigmxyz

Reviews

Repository Details