Merge pull request #5449 from ethereum-optimism/op-program-pre-image-oracles

op-program: pre-image oracle implementation

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/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)
+}