Merge branch 'develop' into refcell/challenger-bool-flag

cannon/mipsevm/evm_test.go

@@ -63,6 +63,8 @@ func TestEVM(t *testing.T) {
 			if strings.HasPrefix(f.Name(), "oracle") {
 				oracle = staticOracle(t, []byte("hello world"))
 			}
+			// Short-circuit early for exit_group.bin
+			exitGroup := f.Name() == "exit_group.bin"
 
 			env, evmState := NewEVMEnv(contracts, addrs)
 			env.Config.Tracer = tracer
@@ -83,6 +85,9 @@ func TestEVM(t *testing.T) {
 				if us.state.PC == endAddr {
 					break
 				}
+				if exitGroup && us.state.Exited {
+					break
+				}
 				insn := state.Memory.GetMemory(state.PC)
 				t.Logf("step: %4d pc: 0x%08x insn: 0x%08x", state.Step, state.PC, insn)
 
@@ -122,11 +127,17 @@ func TestEVM(t *testing.T) {
 				require.Equal(t, hexutil.Bytes(uniPost).String(), hexutil.Bytes(evmPost).String(),
 					"mipsevm produced different state than EVM")
 			}
-			require.Equal(t, uint32(endAddr), state.PC, "must reach end")
-			// inspect test result
-			done, result := state.Memory.GetMemory(baseAddrEnd+4), state.Memory.GetMemory(baseAddrEnd+8)
-			require.Equal(t, done, uint32(1), "must be done")
-			require.Equal(t, result, uint32(1), "must have success result")
+			if exitGroup {
+				require.NotEqual(t, uint32(endAddr), us.state.PC, "must not reach end")
+				require.True(t, us.state.Exited, "must set exited state")
+				require.Equal(t, uint8(1), us.state.ExitCode, "must exit with 1")
+			} else {
+				require.Equal(t, uint32(endAddr), state.PC, "must reach end")
+				// inspect test result
+				done, result := state.Memory.GetMemory(baseAddrEnd+4), state.Memory.GetMemory(baseAddrEnd+8)
+				require.Equal(t, done, uint32(1), "must be done")
+				require.Equal(t, result, uint32(1), "must have success result")
+			}
 		})
 	}
 }

cannon/mipsevm/open_mips_tests/test/brk.asm

+.section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+
+test:
+  li $v0, 4045
+  syscall
+  lui $t0, 0x4000
+  subu $v0, $v0, $t0
+  sltiu $v0, $v0, 1
+
+# save results
+  lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+  ori     $s0, 0xfff0
+  ori     $s1, $0, 1          # Prepare the 'done' status
+
+  sw      $v0, 8($s0)         # Set the test result
+  sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+  jr $ra
+  nop
+
+  .end test

cannon/mipsevm/open_mips_tests/test/clone.asm

+.section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+
+test:
+  li $v0, 4120
+  syscall
+  li $t0, 0x1
+  subu $v0, $v0, $t0
+  sltiu $v0, $v0, 1
+
+# save results
+  lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+  ori     $s0, 0xfff0
+  ori     $s1, $0, 1          # Prepare the 'done' status
+
+  sw      $v0, 8($s0)         # Set the test result
+  sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+  jr $ra
+  nop
+
+  .end test

cannon/mipsevm/open_mips_tests/test/exit_group.asm

+.section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+
+test:
+  li $a0, 1
+  li $v0, 4246
+  syscall
+
+  # Unreachable ....
+  # set test result to fail.
+  # Test runner should short-circuit before reaching this point.
+  li $v0, 0
+
+  # save results
+  lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+  ori     $s0, 0xfff0
+  ori     $s1, $0, 1          # Prepare the 'done' status
+
+  sw      $v0, 8($s0)         # Set the test result
+  sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+  jr $ra
+  nop
+
+  .end test

cannon/mipsevm/open_mips_tests/test/fcntl.asm

+.section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+
+test:
+  # fnctl(0, 3)
+  li $v0, 4055
+  li $a0, 0x0
+  li $a1, 0x3
+  syscall
+  sltiu $v0, $v0, 1
+
+# save results
+  lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+  ori     $s0, 0xfff0
+  ori     $s1, $0, 1          # Prepare the 'done' status
+
+  sw      $v0, 8($s0)         # Set the test result
+  sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+  jr $ra
+  nop
+
+  .end test

cannon/mipsevm/open_mips_tests/test/mmap.asm

+.section .test, "x"
+    .balign 4
+    .set    noreorder
+    .global test
+    .ent    test
+
+test:
+  li $v0, 4090
+  lui $a0, 0x3000
+  li $a1, 4096
+  syscall
+  lui $t0, 0x3000
+  subu $v0, $v0, $t0
+  sltiu $v0, $v0, 1
+
+ # save results
+  lui     $s0, 0xbfff         # Load the base address 0xbffffff0
+  ori     $s0, 0xfff0
+  ori     $s1, $0, 1          # Prepare the 'done' status
+
+  sw      $v0, 8($s0)         # Set the test result
+  sw      $s1, 4($s0)         # Set 'done'
+
+$done:
+  jr $ra
+  nop
+
+  .end test

cannon/mipsevm/open_mips_tests/test/oracle.asm

@@ -69,6 +69,10 @@ $readloop:
   addiu $t0, $t0, -1
   bnez $t0, $readloop
   nop
+# reading the pre-image stream at EOF should have no effect
+  li $a1, 0x31000008
+  li $v0, 4003
+  syscall
 
 # length at 0x31000000. We also check that the lower 32 bits are zero
   lui $s1, 0x3100

cannon/mipsevm/state_test.go

@@ -35,6 +35,9 @@ func TestState(t *testing.T) {
 			if strings.HasPrefix(f.Name(), "oracle") {
 				oracle = staticOracle(t, []byte("hello world"))
 			}
+			// Short-circuit early for exit_group.bin
+			exitGroup := f.Name() == "exit_group.bin"
+
 			// TODO: currently tests are compiled as flat binary objects
 			// We can use more standard tooling to compile them to ELF files and get remove maketests.py
 			fn := path.Join("open_mips_tests/test/bin", f.Name())
@@ -57,14 +60,24 @@ func TestState(t *testing.T) {
 				if us.state.PC == endAddr {
 					break
 				}
+				if exitGroup && us.state.Exited {
+					break
+				}
 				_, err := us.Step(false)
 				require.NoError(t, err)
 			}
-			require.Equal(t, uint32(endAddr), us.state.PC, "must reach end")
-			// inspect test result
-			done, result := state.Memory.GetMemory(baseAddrEnd+4), state.Memory.GetMemory(baseAddrEnd+8)
-			require.Equal(t, done, uint32(1), "must be done")
-			require.Equal(t, result, uint32(1), "must have success result")
+
+			if exitGroup {
+				require.NotEqual(t, uint32(endAddr), us.state.PC, "must not reach end")
+				require.True(t, us.state.Exited, "must set exited state")
+				require.Equal(t, uint8(1), us.state.ExitCode, "must exit with 1")
+			} else {
+				require.Equal(t, uint32(endAddr), us.state.PC, "must reach end")
+				done, result := state.Memory.GetMemory(baseAddrEnd+4), state.Memory.GetMemory(baseAddrEnd+8)
+				// inspect test result
+				require.Equal(t, done, uint32(1), "must be done")
+				require.Equal(t, result, uint32(1), "must have success result")
+			}
 		})
 	}
 }

docs/op-stack/src/docs/build/getting-started.md

@@ -30,7 +30,7 @@ You’ll need the following software installed to follow this tutorial:
 - [Git](https://git-scm.com/)
 - [Go](https://go.dev/)
 - [Node](https://nodejs.org/en/)
-- [Yarn](https://classic.yarnpkg.com/lang/en/docs/install/)
+- [Pnpm](https://classic.yarnpkg.com/lang/en/docs/install/)
 - [Foundry](https://github.com/foundry-rs/foundry#installation)
 - [Make](https://linux.die.net/man/1/make)
 - [jq](https://github.com/jqlang/jq)
@@ -44,7 +44,7 @@ This tutorial was checked on:
 | git, curl, jq, and make | OS default | `sudo apt install -y git curl make jq` |
 | Go       | 1.20       | `sudo apt update` <br> `wget https://go.dev/dl/go1.20.linux-amd64.tar.gz` <br> `tar xvzf go1.20.linux-amd64.tar.gz` <br> `sudo cp go/bin/go /usr/bin/go` <br> `sudo mv go /usr/lib` <br> `echo export GOROOT=/usr/lib/go >> ~/.bashrc`
 | Node     | 16.19.0    | `curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash -` <br> `sudo apt-get install -y nodejs npm`
-| yarn     | 1.22.19    | `sudo npm install -g yarn`
+| pnpm     | 8.5.6      | `sudo npm install -g pnpm`
 | Foundry  | 0.2.0      | `yarn install:foundry`
 
 ## Build the Source Code
@@ -69,14 +69,14 @@ We’re going to be spinning up an EVM Rollup from the OP Stack source code.  Yo
 1. Install required modules. This is a slow process, while it is running you can already start building `op-geth`, as shown below.
 
     ```bash
-    yarn install
+    pnpm install
     ```
 
 1. Build the various packages inside of the Optimism Monorepo.
 
     ```bash
     make op-node op-batcher op-proposer
-    yarn build
+    pnpm build
     ```
 
 ### Build op-geth
@@ -278,7 +278,7 @@ We’ve set up the L1 side of things, but now we need to set up the L2 side of t
 
     You should then see the `genesis.json` and `rollup.json` files inside the `op-node` package.
 
-1. Next, generate the `jwt.txt` file with the following command:
+ 1. Next, generate the `jwt.txt` file with the following command:
 
     ```bash
     openssl rand -hex 32 > jwt.txt
@@ -307,24 +307,6 @@ We’re almost ready to run our chain! Now we just need to run a few commands to
     mkdir datadir
     ```
 
-1. Put a password file into the data directory folder:
-
-    ```bash
-    echo "pwd" > datadir/password
-    ```
-
-1. Put the `Sequencer` private key into the data directory folder (don’t include a “0x” prefix):
-
-    ```bash
-    echo "<SEQUENCER KEY HERE>" > datadir/block-signer-key
-    ```
-
-1. Import the key into `op-geth`:
-
-    ```bash
-    ./build/bin/geth account import --datadir=datadir --password=datadir/password datadir/block-signer-key
-    ```
-
 1. Next we need to initialize `op-geth` with the genesis file we generated and copied earlier:
 
     ```bash
@@ -344,7 +326,6 @@ Set these environment variables for the configuration
 
 | Variable       | Value |
 | -------------- | -
-| `SEQ_ADDR`     | Address of the `Sequencer` account
 | `SEQ_KEY`      | Private key of the `Sequencer` account
 | `BATCHER_KEY`  | Private key of the `Batcher` accounts, which should have at least 1 ETH
 | `PROPOSER_KEY` | Private key of the `Proposer` account
@@ -360,32 +341,27 @@ Run `op-geth` with the following commands.
 cd ~/op-geth
 
 ./build/bin/geth \
-	--datadir ./datadir \
-	--http \
-	--http.corsdomain="*" \
-	--http.vhosts="*" \
-	--http.addr=0.0.0.0 \
-	--http.api=web3,debug,eth,txpool,net,engine \
-	--ws \
-	--ws.addr=0.0.0.0 \
-	--ws.port=8546 \
-	--ws.origins="*" \
-	--ws.api=debug,eth,txpool,net,engine \
-	--syncmode=full \
-	--gcmode=archive \
-	--nodiscover \
-	--maxpeers=0 \
-	--networkid=42069 \
-	--authrpc.vhosts="*" \
-	--authrpc.addr=0.0.0.0 \
-	--authrpc.port=8551 \
-	--authrpc.jwtsecret=./jwt.txt \
-	--rollup.disabletxpoolgossip=true \
-	--password=./datadir/password \
-	--allow-insecure-unlock \
-	--mine \
-	--miner.etherbase=$SEQ_ADDR \
-	--unlock=$SEQ_ADDR
+        --datadir ./datadir \
+        --http \
+        --http.corsdomain="*" \
+        --http.vhosts="*" \
+        --http.addr=0.0.0.0 \
+        --http.api=web3,debug,eth,txpool,net,engine \
+        --ws \
+        --ws.addr=0.0.0.0 \
+        --ws.port=8546 \
+        --ws.origins="*" \
+        --ws.api=debug,eth,txpool,net,engine \
+        --syncmode=full \
+        --gcmode=archive \
+        --nodiscover \
+        --maxpeers=0 \
+        --networkid=42069 \
+        --authrpc.vhosts="*" \
+        --authrpc.addr=0.0.0.0 \
+        --authrpc.port=8551 \
+        --authrpc.jwtsecret=./jwt.txt \
+        --rollup.disabletxpoolgossip=true
 ```
 
 And `op-geth` should be running! You should see some output, but you won’t see any blocks being created yet because `op-geth` is driven by the `op-node`. We’ll need to get that running next.
@@ -443,7 +419,7 @@ cd ~/optimism/op-node
 
 ./bin/op-node \
 	--l2=http://localhost:8551 \
-	--l2.jwt-secret=./jwt.txt \
+	--l2.jwt-secret=./jwt.txt \    
 	--sequencer.enabled \
 	--sequencer.l1-confs=3 \
 	--verifier.l1-confs=3 \

nx.json

@@ -7,7 +7,9 @@
     "nx.json": "*",
     "tsconfig.json": "*",
     ".foundryrc": "*",
-    ".nvmrc": "*"
+    "pnpm.lock.yaml": "*",
+    ".npmrc": "*",
+    ".nvmrc":  "*"
   },
   "tasksRunnerOptions": {
     "default": {

op-bindings/bindings/preimageoracle.go

@@ -31,7 +31,7 @@ var (
 // PreimageOracleMetaData contains all meta data concerning the PreimageOracle contract.
 var PreimageOracleMetaData = &bind.MetaData{
 	ABI: "[{\"inputs\":[{\"internalType\":\"uint256\",\"name\":\"partOffset\",\"type\":\"uint256\"},{\"internalType\":\"bytes32\",\"name\":\"key\",\"type\":\"bytes32\"},{\"internalType\":\"bytes32\",\"name\":\"part\",\"type\":\"bytes32\"},{\"internalType\":\"uint256\",\"name\":\"size\",\"type\":\"uint256\"}],\"name\":\"cheat\",\"outputs\":[],\"stateMutability\":\"nonpayable\",\"type\":\"function\"},{\"inputs\":[{\"internalType\":\"uint256\",\"name\":\"partOffset\",\"type\":\"uint256\"},{\"internalType\":\"bytes\",\"name\":\"preimage\",\"type\":\"bytes\"}],\"name\":\"loadKeccak256PreimagePart\",\"outputs\":[],\"stateMutability\":\"nonpayable\",\"type\":\"function\"},{\"inputs\":[{\"internalType\":\"bytes32\",\"name\":\"\",\"type\":\"bytes32\"}],\"name\":\"preimageLengths\",\"outputs\":[{\"internalType\":\"uint256\",\"name\":\"\",\"type\":\"uint256\"}],\"stateMutability\":\"view\",\"type\":\"function\"},{\"inputs\":[{\"internalType\":\"bytes32\",\"name\":\"\",\"type\":\"bytes32\"},{\"internalType\":\"uint256\",\"name\":\"\",\"type\":\"uint256\"}],\"name\":\"preimagePartOk\",\"outputs\":[{\"internalType\":\"bool\",\"name\":\"\",\"type\":\"bool\"}],\"stateMutability\":\"view\",\"type\":\"function\"},{\"inputs\":[{\"internalType\":\"bytes32\",\"name\":\"\",\"type\":\"bytes32\"},{\"internalType\":\"uint256\",\"name\":\"\",\"type\":\"uint256\"}],\"name\":\"preimageParts\",\"outputs\":[{\"internalType\":\"bytes32\",\"name\":\"\",\"type\":\"bytes32\"}],\"stateMutability\":\"view\",\"type\":\"function\"},{\"inputs\":[{\"internalType\":\"bytes32\",\"name\":\"key\",\"type\":\"bytes32\"},{\"internalType\":\"uint256\",\"name\":\"offset\",\"type\":\"uint256\"}],\"name\":\"readPreimage\",\"outputs\":[{\"internalType\":\"bytes32\",\"name\":\"dat\",\"type\":\"bytes32\"},{\"internalType\":\"uint256\",\"name\":\"datLen\",\"type\":\"uint256\"}],\"stateMutability\":\"view\",\"type\":\"function\"}]",
-	Bin: "0x608060405234801561001057600080fd5b50610509806100206000396000f3fe608060405234801561001057600080fd5b50600436106100725760003560e01c8063e159261111610050578063e15926111461011b578063fe4ac08e14610130578063fef2b4ed146101a557600080fd5b806361238bde146100775780638542cf50146100b5578063e03110e1146100f3575b600080fd5b6100a26100853660046103b5565b600160209081526000928352604080842090915290825290205481565b6040519081526020015b60405180910390f35b6100e36100c33660046103b5565b600260209081526000928352604080842090915290825290205460ff1681565b60405190151581526020016100ac565b6101066101013660046103b5565b6101c5565b604080519283526020830191909152016100ac565b61012e6101293660046103d7565b6102b6565b005b61012e61013e366004610453565b6000838152600260209081526040808320878452825280832080547fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff001660019081179091558684528252808320968352958152858220939093559283529082905291902055565b6100a26101b3366004610485565b60006020819052908152604090205481565b6000828152600260209081526040808320848452909152812054819060ff1661024e576040517f08c379a000000000000000000000000000000000000000000000000000000000815260206004820152601360248201527f707265696d616765206d75737420657869737400000000000000000000000000604482015260640160405180910390fd5b506000838152602081815260409091205461026a8160086104cd565b6102758560206104cd565b1061029357836102868260086104cd565b61029091906104e5565b91505b506000938452600160209081526040808620948652939052919092205492909150565b6044356000806008830186106102cb57600080fd5b60c083901b6080526088838682378087017ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff80151908490207effffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff167f02000000000000000000000000000000000000000000000000000000000000001760008181526002602090815260408083208b8452825280832080547fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff0016600190811790915584845282528083209a83529981528982209390935590815290819052959095209190915550505050565b600080604083850312156103c857600080fd5b50508035926020909101359150565b6000806000604084860312156103ec57600080fd5b83359250602084013567ffffffffffffffff8082111561040b57600080fd5b818601915086601f83011261041f57600080fd5b81358181111561042e57600080fd5b87602082850101111561044057600080fd5b6020830194508093505050509250925092565b6000806000806080858703121561046957600080fd5b5050823594602084013594506040840135936060013592509050565b60006020828403121561049757600080fd5b5035919050565b7f4e487b7100000000000000000000000000000000000000000000000000000000600052601160045260246000fd5b600082198211156104e0576104e061049e565b500190565b6000828210156104f7576104f761049e565b50039056fea164736f6c634300080f000a",
+	Bin: "0x608060405234801561001057600080fd5b5061050a806100206000396000f3fe608060405234801561001057600080fd5b50600436106100725760003560e01c8063e159261111610050578063e15926111461011b578063fe4ac08e14610130578063fef2b4ed146101a557600080fd5b806361238bde146100775780638542cf50146100b5578063e03110e1146100f3575b600080fd5b6100a26100853660046103b6565b600160209081526000928352604080842090915290825290205481565b6040519081526020015b60405180910390f35b6100e36100c33660046103b6565b600260209081526000928352604080842090915290825290205460ff1681565b60405190151581526020016100ac565b6101066101013660046103b6565b6101c5565b604080519283526020830191909152016100ac565b61012e6101293660046103d8565b6102b6565b005b61012e61013e366004610454565b6000838152600260209081526040808320878452825280832080547fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff001660019081179091558684528252808320968352958152858220939093559283529082905291902055565b6100a26101b3366004610486565b60006020819052908152604090205481565b6000828152600260209081526040808320848452909152812054819060ff1661024e576040517f08c379a000000000000000000000000000000000000000000000000000000000815260206004820152601360248201527f707265696d616765206d75737420657869737400000000000000000000000000604482015260640160405180910390fd5b506000838152602081815260409091205461026a8160086104ce565b6102758560206104ce565b1061029357836102868260086104ce565b61029091906104e6565b91505b506000938452600160209081526040808620948652939052919092205492909150565b604435600080600883018611156102cc57600080fd5b60c083901b6080526088838682378087017ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff80151908490207effffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff167f02000000000000000000000000000000000000000000000000000000000000001760008181526002602090815260408083208b8452825280832080547fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff0016600190811790915584845282528083209a83529981528982209390935590815290819052959095209190915550505050565b600080604083850312156103c957600080fd5b50508035926020909101359150565b6000806000604084860312156103ed57600080fd5b83359250602084013567ffffffffffffffff8082111561040c57600080fd5b818601915086601f83011261042057600080fd5b81358181111561042f57600080fd5b87602082850101111561044157600080fd5b6020830194508093505050509250925092565b6000806000806080858703121561046a57600080fd5b5050823594602084013594506040840135936060013592509050565b60006020828403121561049857600080fd5b5035919050565b7f4e487b7100000000000000000000000000000000000000000000000000000000600052601160045260246000fd5b600082198211156104e1576104e161049f565b500190565b6000828210156104f8576104f861049f565b50039056fea164736f6c634300080f000a",
 }
 
 // PreimageOracleABI is the input ABI used to generate the binding from.

ops/check-changed/main.py

@@ -3,6 +3,7 @@ import os
 import re
 import subprocess
 import sys
+import json
 
 from github import Github
 
@@ -13,9 +14,11 @@ REBUILD_ALL_PATTERNS = [
     r'ops/check-changed/.*',
     r'^go\.mod',
     r'^go\.sum',
-    r'^pnpm-lock\.yaml',
     r'ops/check-changed/.*'
 ]
+with open("../../nx.json") as file:
+    nx_json_data = json.load(file)
+REBUILD_ALL_PATTERNS += nx_json_data["implicitDependencies"].keys()
 
 WHITELISTED_BRANCHES = {
     'master',

packages/contracts-bedrock/contracts/cannon/MIPS.sol

 // SPDX-License-Identifier: MIT
 pragma solidity 0.7.6;
 
-interface IPreimageOracle {
-  function readPreimage(bytes32 key, uint256 offset) external view returns (bytes32 dat, uint256 datLen);
-}
+import { IPreimageOracle } from "./interfaces/IPreimageOracle.sol";
 
 // https://inst.eecs.berkeley.edu/~cs61c/resources/MIPS_Green_Sheet.pdf
 // https://uweb.engr.arizona.edu/~ece369/Resources/spim/MIPSReference.pdf

packages/contracts-bedrock/contracts/cannon/PreimageOracle.sol

@@ -46,8 +46,8 @@ contract PreimageOracle {
         assembly {
             // len(sig) + len(partOffset) + len(preimage offset) = 4 + 32 + 32 = 0x44
             size := calldataload(0x44)
-            // revert if part offset >= size+8 (i.e. parts must be within bounds)
-            if iszero(lt(partOffset, add(size, 8))) {
+            // revert if part offset > size+8 (i.e. parts must be within bounds)
+            if gt(partOffset, add(size, 8)) {
                 revert(0, 0)
             }
             // we leave solidity slots 0x40 and 0x60 untouched,

packages/contracts-bedrock/contracts/cannon/interfaces/IPreimageOracle.sol

+// SPDX-License-Identifier: MIT
+pragma solidity 0.7.6;
+
+/// @title IPreimageOracle
+/// @notice Interface for a preimage oracle.
+interface IPreimageOracle {
+    /// @notice Reads a preimage from the oracle.
+    /// @param _key The key of the preimage to read.
+    /// @param _offset The offset of the preimage to read.
+    /// @return dat_ The preimage data.
+    /// @return datLen_ The length of the preimage data.
+    function readPreimage(bytes32 _key, uint256 _offset)
+        external
+        view
+        returns (bytes32 dat_, uint256 datLen_);
+
+    /// @notice Computes and returns the key for a pre-image.
+    /// @param _preimage The pre-image.
+    /// @return key_ The pre-image key.
+    function computePreimageKey(bytes calldata _preimage) external pure returns (bytes32 key_);
+
+    /// @notice Prepares a preimage to be read by keccak256 key, starting at
+    ///         the given offset and up to 32 bytes (clipped at preimage length, if out of data).
+    /// @param _partOffset The offset of the preimage to read.
+    /// @param _preimage The preimage data.
+    function loadKeccak256PreimagePart(uint256 _partOffset, bytes calldata _preimage) external;
+}