search

risc0 / zeth

A "Type 0" zkEVM. Prove validity of Ethereum blocks using RISC Zero's zkVM
Apache License 2.0
370 stars 67 forks source link

refactor: Unified zeth utility #72

Closed hashcashier closed 9 months ago

hashcashier commented 10 months ago

This PR integrates all features into a single CLI binary with a command based usage pattern. The task to be performed by the binary (preflight/exec/prove/verify) is now explicit in the command called rather than implied by the provided arguments.

zeth --help
Usage: zeth <COMMAND>

Commands:
  build    Build blocks natively outside the zkVM
  run      Run the block creation process inside the executor
  prove    Provably create blocks inside the zkVM
  verify   Verify a block creation receipt
  op-info  Output debug information about an optimism block
  help     Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

For every command, the --network parameter can be set to either ethereum or optimism for provable derivation of single blocks from either chain. This provides the basic functionality of the original main binary.

zeth build --help
Build blocks natively outside the zkVM

Usage: zeth build [OPTIONS] --block-number=<BLOCK_NUMBER>

Options:
  -w, --network=<NETWORK>            Network name (ethereum/optimism/optimism-derived) [default: ethereum]
  -e, --eth-rpc-url=<ETH_RPC_URL>    URL of the Ethereum RPC node
  -o, --op-rpc-url=<OP_RPC_URL>      URL of the Optimism RPC node
  -c, --cache[=<CACHE>]              Use a local directory as a cache for RPC calls. Accepts a custom directory. [default: host/testdata]
  -b, --block-number=<BLOCK_NUMBER>  Block number to begin from
  -n, --block-count=<BLOCK_COUNT>    Number of blocks to provably derive [default: 1]
  -m, --composition[=<COMPOSITION>]  Compose separate block derivation proofs together. Accepts a custom number of blocks to process per derivation call. (optimism-derived network only) [default: 1]
  -h, --help                         Print help

With --network=optimism-derived, the optimism blocks requested are derived using the data available on the ethereum chain. The number of sequential op blocks to derive is set through the --block-count parameter. The derivation proof creation method is done without proof composition by default, requiring the derivation to fit inside a single zkVM execution. 

zeth run --help  
Run the block creation process inside the executor

Usage: zeth run [OPTIONS] --block-number=<BLOCK_NUMBER>

Options:
  -w, --network=<NETWORK>            Network name (ethereum/optimism/optimism-derived) [default: ethereum]
  -e, --eth-rpc-url=<ETH_RPC_URL>    URL of the Ethereum RPC node
  -o, --op-rpc-url=<OP_RPC_URL>      URL of the Optimism RPC node
  -c, --cache[=<CACHE>]              Use a local directory as a cache for RPC calls. Accepts a custom directory. [default: host/testdata]
  -b, --block-number=<BLOCK_NUMBER>  Block number to begin from
  -n, --block-count=<BLOCK_COUNT>    Number of blocks to provably derive [default: 1]
  -l, --local-exec=<LOCAL_EXEC>      The maximum segment cycle count as a power of 2 [default: 20]
  -p, --profile                      Whether to profile the zkVM execution
  -h, --help                         Print help

The derivation proof can alternatively be created using proof composition by setting the --composition parameter to the number of op blocks per rolled up proof. However, the run command does not support this parameter because receipts are required for the proof composition. Consequently, one has to call the prove command in dev mode for the same functionality.

zeth prove --help
Provably create blocks inside the zkVM

Usage: zeth prove [OPTIONS] --block-number=<BLOCK_NUMBER>

Options:
  -w, --network=<NETWORK>            Network name (ethereum/optimism/optimism-derived) [default: ethereum]
  -e, --eth-rpc-url=<ETH_RPC_URL>    URL of the Ethereum RPC node
  -o, --op-rpc-url=<OP_RPC_URL>      URL of the Optimism RPC node
  -c, --cache[=<CACHE>]              Use a local directory as a cache for RPC calls. Accepts a custom directory. [default: host/testdata]
  -b, --block-number=<BLOCK_NUMBER>  Block number to begin from
  -n, --block-count=<BLOCK_COUNT>    Number of blocks to provably derive [default: 1]
  -l, --local-exec=<LOCAL_EXEC>      The maximum segment cycle count as a power of 2 [default: 20]
  -p, --profile                      Whether to profile the zkVM execution
  -m, --composition[=<COMPOSITION>]  Compose separate block derivation proofs together. Accepts a custom number of blocks to process per derivation call. (optimism-derived network only) [default: 1]
  -s, --submit-to-bonsai             Prove remotely using Bonsai
  -h, --help                         Print help

To verify existing receipts:

zeth verify --help
Verify a block creation receipt

Usage: zeth verify [OPTIONS] --block-number=<BLOCK_NUMBER>

Options:
  -w, --network=<NETWORK>
          Network name (ethereum/optimism/optimism-derived) [default: ethereum]
  -e, --eth-rpc-url=<ETH_RPC_URL>
          URL of the Ethereum RPC node
  -o, --op-rpc-url=<OP_RPC_URL>
          URL of the Optimism RPC node
  -c, --cache[=<CACHE>]
          Use a local directory as a cache for RPC calls. Accepts a custom directory. [default: host/testdata]
  -b, --block-number=<BLOCK_NUMBER>
          Block number to begin from
  -n, --block-count=<BLOCK_COUNT>
          Number of blocks to provably derive [default: 1]
  -r, --receipt-bonsai-uuid=<RECEIPT_BONSAI_UUID>
          Verify the receipt from the provided Bonsai Session UUID
  -h, --help
          Print help

Lastly, the op-info binary has also been integrated as a stand alone command:

zeth op-info --help
Output debug information about an optimism block

Usage: zeth op-info [OPTIONS] --block-number=<BLOCK_NUMBER>

Options:
  -w, --network=<NETWORK>            Network name (ethereum/optimism/optimism-derived) [default: ethereum]
  -e, --eth-rpc-url=<ETH_RPC_URL>    URL of the Ethereum RPC node
  -o, --op-rpc-url=<OP_RPC_URL>      URL of the Optimism RPC node
  -c, --cache[=<CACHE>]              Use a local directory as a cache for RPC calls. Accepts a custom directory. [default: host/testdata]
  -b, --block-number=<BLOCK_NUMBER>  Block number to begin from
  -n, --block-count=<BLOCK_COUNT>    Number of blocks to provably derive [default: 1]
  -h, --help                         Print help