Merge branch 'develop' into aj/engine-genesis-difficulty

op-node/eth/receipts.go

+package eth
+
+import (
+	"fmt"
+	"math/big"
+
+	"github.com/ethereum/go-ethereum/common"
+	"github.com/ethereum/go-ethereum/common/hexutil"
+	"github.com/ethereum/go-ethereum/core/types"
+)
+
+// EncodeReceipts encodes a list of receipts into raw receipts. Some non-consensus meta-data may be lost.
+func EncodeReceipts(elems []*types.Receipt) ([]hexutil.Bytes, error) {
+	out := make([]hexutil.Bytes, len(elems))
+	for i, el := range elems {
+		dat, err := el.MarshalBinary()
+		if err != nil {
+			return nil, fmt.Errorf("failed to marshal receipt %d: %w", i, err)
+		}
+		out[i] = dat
+	}
+	return out, nil
+}
+
+// DecodeRawReceipts decodes receipts and adds additional blocks metadata.
+// The contract-deployment addresses are not set however (high cost, depends on nonce values, unused by op-node).
+func DecodeRawReceipts(block BlockID, rawReceipts []hexutil.Bytes, txHashes []common.Hash) ([]*types.Receipt, error) {
+	result := make([]*types.Receipt, len(rawReceipts))
+	totalIndex := uint(0)
+	prevCumulativeGasUsed := uint64(0)
+	for i, r := range rawReceipts {
+		var x types.Receipt
+		if err := x.UnmarshalBinary(r); err != nil {
+			return nil, fmt.Errorf("failed to decode receipt %d: %w", i, err)
+		}
+		x.TxHash = txHashes[i]
+		x.BlockHash = block.Hash
+		x.BlockNumber = new(big.Int).SetUint64(block.Number)
+		x.TransactionIndex = uint(i)
+		x.GasUsed = x.CumulativeGasUsed - prevCumulativeGasUsed
+		// contract address meta-data is not computed.
+		prevCumulativeGasUsed = x.CumulativeGasUsed
+		for _, l := range x.Logs {
+			l.BlockNumber = block.Number
+			l.TxHash = x.TxHash
+			l.TxIndex = uint(i)
+			l.BlockHash = block.Hash
+			l.Index = totalIndex
+			totalIndex += 1
+		}
+		result[i] = &x
+	}
+	return result, nil
+}

op-node/eth/transactions.go

+package eth
+
+import (
+	"fmt"
+
+	"github.com/ethereum/go-ethereum/common"
+	"github.com/ethereum/go-ethereum/common/hexutil"
+	"github.com/ethereum/go-ethereum/core/types"
+)
+
+// EncodeTransactions encodes a list of transactions into opaque transactions.
+func EncodeTransactions(elems []*types.Transaction) ([]hexutil.Bytes, error) {
+	out := make([]hexutil.Bytes, len(elems))
+	for i, el := range elems {
+		dat, err := el.MarshalBinary()
+		if err != nil {
+			return nil, fmt.Errorf("failed to marshal tx %d: %w", i, err)
+		}
+		out[i] = dat
+	}
+	return out, nil
+}
+
+// DecodeTransactions decodes a list of opaque transactions into transactions.
+func DecodeTransactions(data []hexutil.Bytes) ([]*types.Transaction, error) {
+	dest := make([]*types.Transaction, len(data))
+	for i := range dest {
+		var x types.Transaction
+		if err := x.UnmarshalBinary(data[i]); err != nil {
+			return nil, fmt.Errorf("failed to unmarshal tx %d: %w", i, err)
+		}
+		dest[i] = &x
+	}
+	return dest, nil
+}
+
+// TransactionsToHashes computes the transaction-hash for every transaction in the input.
+func TransactionsToHashes(elems []*types.Transaction) []common.Hash {
+	out := make([]common.Hash, len(elems))
+	for i, el := range elems {
+		out[i] = el.Hash()
+	}
+	return out
+}

op-node/sources/eth_client.go

@@ -356,10 +356,7 @@ func (s *EthClient) FetchReceipts(ctx context.Context, blockHash common.Hash) (e
 	if v, ok := s.receiptsCache.Get(blockHash); ok {
 		job = v.(*receiptsFetchingJob)
 	} else {
-		txHashes := make([]common.Hash, len(txs))
-		for i := 0; i < len(txs); i++ {
-			txHashes[i] = txs[i].Hash()
-		}
+		txHashes := eth.TransactionsToHashes(txs)
 		job = NewReceiptsFetchingJob(s, s.client, s.maxBatchSize, eth.ToBlockID(info), info.ReceiptHash(), txHashes)
 		s.receiptsCache.Add(blockHash, job)
 	}

op-node/sources/receipts.go

@@ -4,7 +4,6 @@ import (
 	"context"
 	"fmt"
 	"io"
-	"math/big"
 	"sync"
 
 	"github.com/ethereum/go-ethereum/common"
@@ -420,29 +419,7 @@ func (job *receiptsFetchingJob) runAltMethod(ctx context.Context, m ReceiptsFetc
 		err = job.client.CallContext(ctx, &rawReceipts, "debug_getRawReceipts", job.block.Hash)
 		if err == nil {
 			if len(rawReceipts) == len(job.txHashes) {
-				result = make([]*types.Receipt, len(rawReceipts))
-				totalIndex := uint(0)
-				prevCumulativeGasUsed := uint64(0)
-				for i, r := range rawReceipts {
-					var x types.Receipt
-					_ = x.UnmarshalBinary(r) // safe to ignore, we verify receipts against the receipts hash later
-					x.TxHash = job.txHashes[i]
-					x.BlockHash = job.block.Hash
-					x.BlockNumber = new(big.Int).SetUint64(job.block.Number)
-					x.TransactionIndex = uint(i)
-					x.GasUsed = x.CumulativeGasUsed - prevCumulativeGasUsed
-					// contract address meta-data is not computed.
-					prevCumulativeGasUsed = x.CumulativeGasUsed
-					for _, l := range x.Logs {
-						l.BlockNumber = job.block.Number
-						l.TxHash = x.TxHash
-						l.TxIndex = uint(i)
-						l.BlockHash = job.block.Hash
-						l.Index = totalIndex
-						totalIndex += 1
-					}
-					result[i] = &x
-				}
+				result, err = eth.DecodeRawReceipts(job.block, rawReceipts, job.txHashes)
 			} else {
 				err = fmt.Errorf("got %d raw receipts, but expected %d", len(rawReceipts), len(job.txHashes))
 			}

op-program/client/l1/hints.go

+package l1
+
+import (
+	"github.com/ethereum/go-ethereum/common"
+
+	"github.com/ethereum-optimism/optimism/op-program/preimage"
+)
+
+type BlockHeaderHint common.Hash
+
+var _ preimage.Hint = BlockHeaderHint{}
+
+func (l BlockHeaderHint) Hint() string {
+	return "l1-block-header " + (common.Hash)(l).String()
+}
+
+type TransactionsHint common.Hash
+
+var _ preimage.Hint = TransactionsHint{}
+
+func (l TransactionsHint) Hint() string {
+	return "l1-transactions " + (common.Hash)(l).String()
+}
+
+type ReceiptsHint common.Hash
+
+var _ preimage.Hint = ReceiptsHint{}
+
+func (l ReceiptsHint) Hint() string {
+	return "l1-receipts " + (common.Hash)(l).String()
+}

op-program/client/l1/oracle.go

 package l1
 
 import (
-	"github.com/ethereum-optimism/optimism/op-node/eth"
+	"fmt"
+
 	"github.com/ethereum/go-ethereum/common"
 	"github.com/ethereum/go-ethereum/core/types"
+	"github.com/ethereum/go-ethereum/rlp"
+
+	"github.com/ethereum-optimism/optimism/op-node/eth"
+	"github.com/ethereum-optimism/optimism/op-program/client/mpt"
+	"github.com/ethereum-optimism/optimism/op-program/preimage"
 )
 
 type Oracle interface {
@@ -16,3 +22,67 @@ type Oracle interface {
 	// ReceiptsByBlockHash retrieves the receipts from the block with the given hash.
 	ReceiptsByBlockHash(blockHash common.Hash) (eth.BlockInfo, types.Receipts)
 }
+
+// PreimageOracle implements Oracle using by interfacing with the pure preimage.Oracle
+// to fetch pre-images to decode into the requested data.
+type PreimageOracle struct {
+	oracle preimage.Oracle
+	hint   preimage.Hinter
+}
+
+var _ Oracle = (*PreimageOracle)(nil)
+
+func NewPreimageOracle(raw preimage.Oracle, hint preimage.Hinter) *PreimageOracle {
+	return &PreimageOracle{
+		oracle: raw,
+		hint:   hint,
+	}
+}
+
+func (p *PreimageOracle) headerByBlockHash(blockHash common.Hash) *types.Header {
+	p.hint.Hint(BlockHeaderHint(blockHash))
+	headerRlp := p.oracle.Get(preimage.Keccak256Key(blockHash))
+	var header types.Header
+	if err := rlp.DecodeBytes(headerRlp, &header); err != nil {
+		panic(fmt.Errorf("invalid block header %s: %w", blockHash, err))
+	}
+	return &header
+}
+
+func (p *PreimageOracle) HeaderByBlockHash(blockHash common.Hash) eth.BlockInfo {
+	return eth.HeaderBlockInfo(p.headerByBlockHash(blockHash))
+}
+
+func (p *PreimageOracle) TransactionsByBlockHash(blockHash common.Hash) (eth.BlockInfo, types.Transactions) {
+	header := p.headerByBlockHash(blockHash)
+	p.hint.Hint(TransactionsHint(blockHash))
+
+	opaqueTxs := mpt.ReadTrie(header.TxHash, func(key common.Hash) []byte {
+		return p.oracle.Get(preimage.Keccak256Key(key))
+	})
+
+	txs, err := eth.DecodeTransactions(opaqueTxs)
+	if err != nil {
+		panic(fmt.Errorf("failed to decode list of txs: %w", err))
+	}
+
+	return eth.HeaderBlockInfo(header), txs
+}
+
+func (p *PreimageOracle) ReceiptsByBlockHash(blockHash common.Hash) (eth.BlockInfo, types.Receipts) {
+	info, txs := p.TransactionsByBlockHash(blockHash)
+
+	p.hint.Hint(ReceiptsHint(blockHash))
+
+	opaqueReceipts := mpt.ReadTrie(info.ReceiptHash(), func(key common.Hash) []byte {
+		return p.oracle.Get(preimage.Keccak256Key(key))
+	})
+
+	txHashes := eth.TransactionsToHashes(txs)
+	receipts, err := eth.DecodeRawReceipts(eth.ToBlockID(info), opaqueReceipts, txHashes)
+	if err != nil {
+		panic(fmt.Errorf("bad receipts data for block %s: %w", blockHash, err))
+	}
+
+	return info, receipts
+}

op-program/client/l1/oracle_test.go

+package l1
+
+import (
+	"encoding/json"
+	"fmt"
+	"math/rand"
+	"testing"
+
+	"github.com/ethereum/go-ethereum/common"
+	"github.com/ethereum/go-ethereum/core/types"
+	"github.com/ethereum/go-ethereum/crypto"
+	"github.com/ethereum/go-ethereum/rlp"
+	"github.com/stretchr/testify/mock"
+	"github.com/stretchr/testify/require"
+
+	"github.com/ethereum-optimism/optimism/op-node/eth"
+	"github.com/ethereum-optimism/optimism/op-node/testutils"
+	"github.com/ethereum-optimism/optimism/op-program/client/mpt"
+	"github.com/ethereum-optimism/optimism/op-program/preimage"
+)
+
+// testBlock tests that the given block with receipts can be passed through the preimage oracle.
+func testBlock(t *testing.T, block *types.Block, receipts []*types.Receipt) {
+	// Prepare the pre-images
+	preimages := make(map[common.Hash][]byte)
+
+	hdrBytes, err := rlp.EncodeToBytes(block.Header())
+	require.NoError(t, err)
+	preimages[preimage.Keccak256Key(block.Hash()).PreimageKey()] = hdrBytes
+
+	opaqueTxs, err := eth.EncodeTransactions(block.Transactions())
+	require.NoError(t, err)
+	_, txsNodes := mpt.WriteTrie(opaqueTxs)
+	for _, p := range txsNodes {
+		preimages[preimage.Keccak256Key(crypto.Keccak256Hash(p)).PreimageKey()] = p
+	}
+
+	opaqueReceipts, err := eth.EncodeReceipts(receipts)
+	require.NoError(t, err)
+	_, receiptNodes := mpt.WriteTrie(opaqueReceipts)
+	for _, p := range receiptNodes {
+		preimages[preimage.Keccak256Key(crypto.Keccak256Hash(p)).PreimageKey()] = p
+	}
+
+	// Prepare a raw mock pre-image oracle that will serve the pre-image data and handle hints
+	var hints mock.Mock
+	po := &PreimageOracle{
+		oracle: preimage.OracleFn(func(key preimage.Key) []byte {
+			v, ok := preimages[key.PreimageKey()]
+			require.True(t, ok, "preimage must exist")
+			return v
+		}),
+		hint: preimage.HinterFn(func(v preimage.Hint) {
+			hints.MethodCalled("hint", v.Hint())
+		}),
+	}
+
+	// Check if block-headers work
+	hints.On("hint", BlockHeaderHint(block.Hash()).Hint()).Once().Return()
+	gotHeader := po.HeaderByBlockHash(block.Hash())
+	hints.AssertExpectations(t)
+
+	got, err := json.MarshalIndent(gotHeader, "  ", "  ")
+	require.NoError(t, err)
+	expected, err := json.MarshalIndent(block.Header(), "  ", "  ")
+	require.NoError(t, err)
+	require.Equal(t, expected, got, "expecting matching headers")
+
+	// Check if blocks with txs work
+	hints.On("hint", BlockHeaderHint(block.Hash()).Hint()).Once().Return()
+	hints.On("hint", TransactionsHint(block.Hash()).Hint()).Once().Return()
+	inf, gotTxs := po.TransactionsByBlockHash(block.Hash())
+	hints.AssertExpectations(t)
+
+	require.Equal(t, inf.Hash(), block.Hash())
+	expectedTxs := block.Transactions()
+	require.Equal(t, len(expectedTxs), len(gotTxs), "expecting equal tx list length")
+	for i, tx := range gotTxs {
+		require.Equalf(t, tx.Hash(), expectedTxs[i].Hash(), "expecting tx %d to match", i)
+	}
+
+	// Check if blocks with receipts work
+	hints.On("hint", BlockHeaderHint(block.Hash()).Hint()).Once().Return()
+	hints.On("hint", TransactionsHint(block.Hash()).Hint()).Once().Return()
+	hints.On("hint", ReceiptsHint(block.Hash()).Hint()).Once().Return()
+	inf, gotReceipts := po.ReceiptsByBlockHash(block.Hash())
+	hints.AssertExpectations(t)
+
+	require.Equal(t, inf.Hash(), block.Hash())
+	require.Equal(t, len(receipts), len(gotReceipts), "expecting equal tx list length")
+	for i, r := range gotReceipts {
+		require.Equalf(t, r.TxHash, expectedTxs[i].Hash(), "expecting receipt to match tx %d", i)
+	}
+}
+
+func TestPreimageOracleBlockByHash(t *testing.T) {
+	rng := rand.New(rand.NewSource(123))
+
+	for i := 0; i < 10; i++ {
+		block, receipts := testutils.RandomBlock(rng, 10)
+		t.Run(fmt.Sprintf("block_%d", i), func(t *testing.T) {
+			testBlock(t, block, receipts)
+		})
+	}
+}

op-program/client/l2/hints.go

+package l2
+
+import (
+	"github.com/ethereum/go-ethereum/common"
+
+	"github.com/ethereum-optimism/optimism/op-program/preimage"
+)
+
+type BlockHeaderHint common.Hash
+
+var _ preimage.Hint = BlockHeaderHint{}
+
+func (l BlockHeaderHint) Hint() string {
+	return "l2-block-header " + (common.Hash)(l).String()
+}
+
+type TransactionsHint common.Hash
+
+var _ preimage.Hint = TransactionsHint{}
+
+func (l TransactionsHint) Hint() string {
+	return "l2-transactions " + (common.Hash)(l).String()
+}
+
+type CodeHint common.Hash
+
+var _ preimage.Hint = CodeHint{}
+
+func (l CodeHint) Hint() string {
+	return "l2-code " + (common.Hash)(l).String()
+}
+
+type StateNodeHint common.Hash
+
+var _ preimage.Hint = StateNodeHint{}
+
+func (l StateNodeHint) Hint() string {
+	return "l2-state-node " + (common.Hash)(l).String()
+}

op-program/client/l2/oracle.go

 package l2
 
 import (
+	"fmt"
+
 	"github.com/ethereum/go-ethereum/common"
 	"github.com/ethereum/go-ethereum/core/types"
+	"github.com/ethereum/go-ethereum/rlp"
+
+	"github.com/ethereum-optimism/optimism/op-node/eth"
+	"github.com/ethereum-optimism/optimism/op-program/client/mpt"
+	"github.com/ethereum-optimism/optimism/op-program/preimage"
 )
 
 // StateOracle defines the high-level API used to retrieve L2 state data pre-images
@@ -26,3 +33,55 @@ type Oracle interface {
 	// BlockByHash retrieves the block with the given hash.
 	BlockByHash(blockHash common.Hash) *types.Block
 }
+
+// PreimageOracle implements Oracle using by interfacing with the pure preimage.Oracle
+// to fetch pre-images to decode into the requested data.
+type PreimageOracle struct {
+	oracle preimage.Oracle
+	hint   preimage.Hinter
+}
+
+var _ Oracle = (*PreimageOracle)(nil)
+
+func NewPreimageOracle(raw preimage.Oracle, hint preimage.Hinter) *PreimageOracle {
+	return &PreimageOracle{
+		oracle: raw,
+		hint:   hint,
+	}
+}
+
+func (p *PreimageOracle) headerByBlockHash(blockHash common.Hash) *types.Header {
+	p.hint.Hint(BlockHeaderHint(blockHash))
+	headerRlp := p.oracle.Get(preimage.Keccak256Key(blockHash))
+	var header types.Header
+	if err := rlp.DecodeBytes(headerRlp, &header); err != nil {
+		panic(fmt.Errorf("invalid block header %s: %w", blockHash, err))
+	}
+	return &header
+}
+
+func (p *PreimageOracle) BlockByHash(blockHash common.Hash) *types.Block {
+	header := p.headerByBlockHash(blockHash)
+	p.hint.Hint(TransactionsHint(blockHash))
+
+	opaqueTxs := mpt.ReadTrie(header.TxHash, func(key common.Hash) []byte {
+		return p.oracle.Get(preimage.Keccak256Key(key))
+	})
+
+	txs, err := eth.DecodeTransactions(opaqueTxs)
+	if err != nil {
+		panic(fmt.Errorf("failed to decode list of txs: %w", err))
+	}
+
+	return types.NewBlockWithHeader(header).WithBody(txs, nil)
+}
+
+func (p *PreimageOracle) NodeByHash(nodeHash common.Hash) []byte {
+	p.hint.Hint(StateNodeHint(nodeHash))
+	return p.oracle.Get(preimage.Keccak256Key(nodeHash))
+}
+
+func (p *PreimageOracle) CodeByHash(codeHash common.Hash) []byte {
+	p.hint.Hint(CodeHint(codeHash))
+	return p.oracle.Get(preimage.Keccak256Key(codeHash))
+}

op-program/client/l2/oracle_test.go

+package l2
+
+import (
+	"fmt"
+	"math/rand"
+	"testing"
+
+	"github.com/ethereum/go-ethereum/common"
+	"github.com/ethereum/go-ethereum/common/hexutil"
+	"github.com/ethereum/go-ethereum/core/types"
+	"github.com/ethereum/go-ethereum/crypto"
+	"github.com/ethereum/go-ethereum/rlp"
+	"github.com/stretchr/testify/mock"
+	"github.com/stretchr/testify/require"
+
+	"github.com/ethereum-optimism/optimism/op-node/eth"
+	"github.com/ethereum-optimism/optimism/op-node/testutils"
+	"github.com/ethereum-optimism/optimism/op-program/client/mpt"
+	"github.com/ethereum-optimism/optimism/op-program/preimage"
+)
+
+func mockPreimageOracle(t *testing.T) (po *PreimageOracle, hintsMock *mock.Mock, preimages map[common.Hash][]byte) {
+	// Prepare the pre-images
+	preimages = make(map[common.Hash][]byte)
+
+	hintsMock = new(mock.Mock)
+
+	po = &PreimageOracle{
+		oracle: preimage.OracleFn(func(key preimage.Key) []byte {
+			v, ok := preimages[key.PreimageKey()]
+			require.True(t, ok, "preimage must exist")
+			return v
+		}),
+		hint: preimage.HinterFn(func(v preimage.Hint) {
+			hintsMock.MethodCalled("hint", v.Hint())
+		}),
+	}
+
+	return po, hintsMock, preimages
+}
+
+// testBlock tests that the given block can be passed through the preimage oracle.
+func testBlock(t *testing.T, block *types.Block) {
+	po, hints, preimages := mockPreimageOracle(t)
+
+	hdrBytes, err := rlp.EncodeToBytes(block.Header())
+	require.NoError(t, err)
+	preimages[preimage.Keccak256Key(block.Hash()).PreimageKey()] = hdrBytes
+
+	opaqueTxs, err := eth.EncodeTransactions(block.Transactions())
+	require.NoError(t, err)
+	_, txsNodes := mpt.WriteTrie(opaqueTxs)
+	for _, p := range txsNodes {
+		preimages[preimage.Keccak256Key(crypto.Keccak256Hash(p)).PreimageKey()] = p
+	}
+
+	// Prepare a raw mock pre-image oracle that will serve the pre-image data and handle hints
+
+	// Check if blocks with txs work
+	hints.On("hint", BlockHeaderHint(block.Hash()).Hint()).Once().Return()
+	hints.On("hint", TransactionsHint(block.Hash()).Hint()).Once().Return()
+	gotBlock := po.BlockByHash(block.Hash())
+	hints.AssertExpectations(t)
+
+	require.Equal(t, gotBlock.Hash(), block.Hash())
+	expectedTxs := block.Transactions()
+	require.Equal(t, len(expectedTxs), len(gotBlock.Transactions()), "expecting equal tx list length")
+	for i, tx := range gotBlock.Transactions() {
+		require.Equalf(t, tx.Hash(), expectedTxs[i].Hash(), "expecting tx %d to match", i)
+	}
+}
+
+func TestPreimageOracleBlockByHash(t *testing.T) {
+	rng := rand.New(rand.NewSource(123))
+
+	for i := 0; i < 10; i++ {
+		block, _ := testutils.RandomBlock(rng, 10)
+		t.Run(fmt.Sprintf("block_%d", i), func(t *testing.T) {
+			testBlock(t, block)
+		})
+	}
+}
+
+func TestPreimageOracleNodeByHash(t *testing.T) {
+	rng := rand.New(rand.NewSource(123))
+
+	for i := 0; i < 10; i++ {
+		t.Run(fmt.Sprintf("node_%d", i), func(t *testing.T) {
+			po, hints, preimages := mockPreimageOracle(t)
+
+			node := make([]byte, 123)
+			rng.Read(node)
+
+			h := crypto.Keccak256Hash(node)
+			preimages[preimage.Keccak256Key(h).PreimageKey()] = node
+
+			hints.On("hint", StateNodeHint(h).Hint()).Once().Return()
+			gotNode := po.NodeByHash(h)
+			hints.AssertExpectations(t)
+			require.Equal(t, hexutil.Bytes(node), hexutil.Bytes(gotNode), "node matches")
+		})
+	}
+}
+
+func TestPreimageOracleCodeByHash(t *testing.T) {
+	rng := rand.New(rand.NewSource(123))
+
+	for i := 0; i < 10; i++ {
+		t.Run(fmt.Sprintf("code_%d", i), func(t *testing.T) {
+			po, hints, preimages := mockPreimageOracle(t)
+
+			node := make([]byte, 123)
+			rng.Read(node)
+
+			h := crypto.Keccak256Hash(node)
+			preimages[preimage.Keccak256Key(h).PreimageKey()] = node
+
+			hints.On("hint", CodeHint(h).Hint()).Once().Return()
+			gotNode := po.CodeByHash(h)
+			hints.AssertExpectations(t)
+			require.Equal(t, hexutil.Bytes(node), hexutil.Bytes(gotNode), "code matches")
+		})
+	}
+}

op-program/preimage/hints.go

+package preimage
+
+import (
+	"encoding/binary"
+	"fmt"
+	"io"
+)
+
+// HintWriter writes hints to an io.Writer (e.g. a special file descriptor, or a debug log),
+// for a pre-image oracle service to prepare specific pre-images.
+type HintWriter struct {
+	w io.Writer
+}
+
+var _ Hinter = (*HintWriter)(nil)
+
+func NewHintWriter(w io.Writer) *HintWriter {
+	return &HintWriter{w: w}
+}
+
+func (hw *HintWriter) Hint(v Hint) {
+	hint := v.Hint()
+	var hintBytes []byte
+	hintBytes = binary.BigEndian.AppendUint32(hintBytes, uint32(len(hint)))
+	hintBytes = append(hintBytes, []byte(hint)...)
+	hintBytes = append(hintBytes, 0) // to block writing on
+	_, err := hw.w.Write(hintBytes)
+	if err != nil {
+		panic(fmt.Errorf("failed to write pre-image hint: %w", err))
+	}
+}
+
+// HintReader reads the hints of HintWriter and passes them to a router for preparation of the requested pre-images.
+// Onchain the written hints are no-op.
+type HintReader struct {
+	r io.Reader
+}
+
+func NewHintReader(r io.Reader) *HintReader {
+	return &HintReader{r: r}
+}
+
+func (hr *HintReader) NextHint(router func(hint string) error) error {
+	var length uint32
+	if err := binary.Read(hr.r, binary.BigEndian, &length); err != nil {
+		if err == io.EOF {
+			return io.EOF
+		}
+		return fmt.Errorf("failed to read hint length prefix: %w", err)
+	}
+	payload := make([]byte, length)
+	if length > 0 {
+		if _, err := io.ReadFull(hr.r, payload); err != nil {
+			return fmt.Errorf("failed to read hint payload (length %d): %w", length, err)
+		}
+	}
+	if err := router(string(payload)); err != nil {
+		return fmt.Errorf("failed to handle hint: %w", err)
+	}
+	if _, err := hr.r.Read([]byte{0}); err != nil {
+		return fmt.Errorf("failed to read trailing no-op byte to unblock hint writer: %w", err)
+	}
+	return nil
+}

op-program/preimage/hints_test.go

+package preimage
+
+import (
+	"bytes"
+	"crypto/rand"
+	"io"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+type rawHint string
+
+func (rh rawHint) Hint() string {
+	return string(rh)
+}
+
+func TestHints(t *testing.T) {
+	// Note: pretty much every string is valid communication:
+	// length, payload, 0. Worst case you run out of data, or allocate too much.
+	testHint := func(hints ...string) {
+		var buf bytes.Buffer
+		hw := NewHintWriter(&buf)
+		for _, h := range hints {
+			hw.Hint(rawHint(h))
+		}
+		hr := NewHintReader(&buf)
+		var got []string
+		for i := 0; i < 100; i++ { // sanity limit
+			err := hr.NextHint(func(hint string) error {
+				got = append(got, hint)
+				return nil
+			})
+			if err == io.EOF {
+				break
+			}
+			require.NoError(t, err)
+		}
+		require.Equal(t, len(hints), len(got), "got all hints")
+		for i, h := range hints {
+			require.Equal(t, h, got[i], "hints match")
+		}
+	}
+
+	t.Run("empty hint", func(t *testing.T) {
+		testHint("")
+	})
+	t.Run("hello world", func(t *testing.T) {
+		testHint("hello world")
+	})
+	t.Run("zero byte", func(t *testing.T) {
+		testHint(string([]byte{0}))
+	})
+	t.Run("many zeroes", func(t *testing.T) {
+		testHint(string(make([]byte, 1000)))
+	})
+	t.Run("random data", func(t *testing.T) {
+		dat := make([]byte, 1000)
+		_, _ = rand.Read(dat[:])
+		testHint(string(dat))
+	})
+	t.Run("multiple hints", func(t *testing.T) {
+		testHint("give me header a", "also header b", "foo bar")
+	})
+	t.Run("unexpected EOF", func(t *testing.T) {
+		var buf bytes.Buffer
+		hw := NewHintWriter(&buf)
+		hw.Hint(rawHint("hello"))
+		_, _ = buf.Read(make([]byte, 1)) // read one byte so it falls short, see if it's detected
+		hr := NewHintReader(&buf)
+		err := hr.NextHint(func(hint string) error { return nil })
+		require.ErrorIs(t, err, io.ErrUnexpectedEOF)
+	})
+}

op-program/preimage/iface.go

+package preimage
+
+import (
+	"encoding/binary"
+
+	"github.com/ethereum/go-ethereum/common"
+)
+
+type Key interface {
+	// PreimageKey changes the Key commitment into a
+	// 32-byte type-prefixed preimage key.
+	PreimageKey() common.Hash
+}
+
+type Oracle interface {
+	// Get the full pre-image of a given pre-image key.
+	// This returns no error: the client state-transition
+	// is invalid if there is any missing pre-image data.
+	Get(key Key) []byte
+}
+
+type OracleFn func(key Key) []byte
+
+func (fn OracleFn) Get(key Key) []byte {
+	return fn(key)
+}
+
+// KeyType is the key-type of a pre-image, used to prefix the pre-image key with.
+type KeyType byte
+
+const (
+	// The zero key type is illegal to use, ensuring all keys are non-zero.
+	_ KeyType = 0
+	// LocalKeyType is for input-type pre-images, specific to the local program instance.
+	LocalKeyType KeyType = 1
+	// Keccak25Key6Type is for keccak256 pre-images, for any global shared pre-images.
+	Keccak25Key6Type KeyType = 2
+)
+
+// LocalIndexKey is a key local to the program, indexing a special program input.
+type LocalIndexKey uint64
+
+func (k LocalIndexKey) PreimageKey() (out common.Hash) {
+	out[0] = byte(LocalKeyType)
+	binary.BigEndian.PutUint64(out[24:], uint64(k))
+	return
+}
+
+// Keccak256Key wraps a keccak256 hash to use it as a typed pre-image key.
+type Keccak256Key common.Hash
+
+func (k Keccak256Key) PreimageKey() (out common.Hash) {
+	out = common.Hash(k)            // copy the keccak hash
+	out[0] = byte(Keccak25Key6Type) // apply prefix
+	return
+}
+
+// Hint is an interface to enable any program type to function as a hint,
+// when passed to the Hinter interface, returning a string representation
+// of what data the host should prepare pre-images for.
+type Hint interface {
+	Hint() string
+}
+
+// Hinter is an interface to write hints to the host.
+// This may be implemented as a no-op or logging hinter
+// if the program is executing in a read-only environment
+// where the host is expected to have all pre-images ready.
+type Hinter interface {
+	Hint(v Hint)
+}
+
+type HinterFn func(v Hint)
+
+func (fn HinterFn) Hint(v Hint) {
+	fn(v)
+}

op-program/preimage/oracle.go

+package preimage
+
+import (
+	"encoding/binary"
+	"fmt"
+	"io"
+
+	"github.com/ethereum/go-ethereum/common"
+)
+
+// OracleClient implements the Oracle by writing the pre-image key to the given stream,
+// and reading back a length-prefixed value.
+type OracleClient struct {
+	rw io.ReadWriter
+}
+
+func NewOracleClient(rw io.ReadWriter) *OracleClient {
+	return &OracleClient{rw: rw}
+}
+
+var _ Oracle = (*OracleClient)(nil)
+
+func (o *OracleClient) Get(key Key) []byte {
+	h := key.PreimageKey()
+	if _, err := o.rw.Write(h[:]); err != nil {
+		panic(fmt.Errorf("failed to write key %s (%T) to pre-image oracle: %w", key, key, err))
+	}
+
+	var length uint64
+	if err := binary.Read(o.rw, binary.BigEndian, &length); err != nil {
+		panic(fmt.Errorf("failed to read pre-image length of key %s (%T) from pre-image oracle: %w", key, key, err))
+	}
+	payload := make([]byte, length)
+	if _, err := io.ReadFull(o.rw, payload); err != nil {
+		panic(fmt.Errorf("failed to read pre-image payload (length %d) of key %s (%T) from pre-image oracle: %w", length, key, key, err))
+	}
+
+	return payload
+}
+
+// OracleServer serves the pre-image requests of the OracleClient, implementing the same protocol as the onchain VM.
+type OracleServer struct {
+	rw io.ReadWriter
+}
+
+func NewOracleServer(rw io.ReadWriter) *OracleServer {
+	return &OracleServer{rw: rw}
+}
+
+func (o *OracleServer) NextPreimageRequest(getPreimage func(key common.Hash) ([]byte, error)) error {
+	var key common.Hash
+	if _, err := io.ReadFull(o.rw, key[:]); err != nil {
+		if err == io.EOF {
+			return io.EOF
+		}
+		return fmt.Errorf("failed to read requested pre-image key: %w", err)
+	}
+	value, err := getPreimage(key)
+	if err != nil {
+		return fmt.Errorf("failed to serve pre-image %s request: %w", key, err)
+	}
+
+	if err := binary.Write(o.rw, binary.BigEndian, uint64(len(value))); err != nil {
+		return fmt.Errorf("failed to write length-prefix %d: %w", len(value), err)
+	}
+	if len(value) == 0 {
+		return nil
+	}
+	if _, err := o.rw.Write(value); err != nil {
+		return fmt.Errorf("failed to write pre-image value (%d long): %w", len(value), err)
+	}
+	return nil
+}

op-program/preimage/oracle_test.go

+package preimage
+
+import (
+	"bytes"
+	"crypto/rand"
+	"fmt"
+	"io"
+	"sync"
+	"testing"
+
+	"github.com/ethereum/go-ethereum/common"
+	"github.com/ethereum/go-ethereum/crypto"
+	"github.com/stretchr/testify/require"
+)
+
+type readWritePair struct {
+	io.Reader
+	io.Writer
+}
+
+func bidirectionalPipe() (a, b io.ReadWriter) {
+	ar, bw := io.Pipe()
+	br, aw := io.Pipe()
+	return readWritePair{Reader: ar, Writer: aw}, readWritePair{Reader: br, Writer: bw}
+}
+
+func TestOracle(t *testing.T) {
+	testPreimage := func(preimages ...[]byte) {
+		a, b := bidirectionalPipe()
+		cl := NewOracleClient(a)
+		srv := NewOracleServer(b)
+
+		preimageByHash := make(map[common.Hash][]byte)
+		for _, p := range preimages {
+			k := Keccak256Key(crypto.Keccak256Hash(p))
+			preimageByHash[k.PreimageKey()] = p
+		}
+		for _, p := range preimages {
+			k := Keccak256Key(crypto.Keccak256Hash(p))
+
+			var wg sync.WaitGroup
+			wg.Add(2)
+
+			go func(k Key, p []byte) {
+				result := cl.Get(k)
+				wg.Done()
+				expected := preimageByHash[k.PreimageKey()]
+				require.True(t, bytes.Equal(expected, result), "need correct preimage %x, got %x", expected, result)
+			}(k, p)
+
+			go func() {
+				err := srv.NextPreimageRequest(func(key common.Hash) ([]byte, error) {
+					dat, ok := preimageByHash[key]
+					if !ok {
+						return nil, fmt.Errorf("cannot find %s", key)
+					}
+					return dat, nil
+				})
+				wg.Done()
+				require.NoError(t, err)
+			}()
+			wg.Wait()
+		}
+	}
+	t.Run("empty preimage", func(t *testing.T) {
+		testPreimage([]byte{})
+	})
+	t.Run("nil preimage", func(t *testing.T) {
+		testPreimage(nil)
+	})
+	t.Run("zero", func(t *testing.T) {
+		testPreimage([]byte{0})
+	})
+	t.Run("multiple", func(t *testing.T) {
+		testPreimage([]byte("tx from alice"), []byte{0x13, 0x37}, []byte("tx from bob"))
+	})
+	t.Run("zeroes", func(t *testing.T) {
+		testPreimage(make([]byte, 1000))
+	})
+	t.Run("random", func(t *testing.T) {
+		dat := make([]byte, 1000)
+		_, _ = rand.Read(dat[:])
+		testPreimage(dat)
+	})
+}