go/consensus/cometbft/abci: Add results hash to block metadata tx

The results hash was added to the block metadata system transaction so that
stateless clients can partially verify the latest block’s results.

Author: peternose

.changelog/6289.breaking.1.md

@@ -0,0 +1,4 @@
+go/consensus/cometbft/abci: Add results hash to block metadata tx
+
+The results hash was added to the block metadata system transaction so that
+stateless clients can partially verify the latest block’s results.

go/consensus/api/meta.go

@@ -25,13 +25,18 @@ type BlockMetadata struct {
 	StateRoot hash.Hash `json:"state_root"`
 	// EventsRoot is the root hash of all events emitted in the block.
 	EventsRoot []byte `json:"events_root"`
+	// ResultsHash is the hash of transaction results in the block.
+	ResultsHash []byte `json:"results_hash,omitempty"`
 }
 
 // ValidateBasic performs basic block metadata structure validation.
 func (bm *BlockMetadata) ValidateBasic() error {
 	if len(bm.EventsRoot) != 32 {
 		return fmt.Errorf("malformed events root")
 	}
+	if bm.ResultsHash != nil && len(bm.ResultsHash) != 32 {
+		return fmt.Errorf("malformed results hash")
+	}
 	return nil
 }
 

go/consensus/cometbft/abci/mux.go

@@ -433,8 +433,15 @@ func (mux *abciMux) PrepareProposal(req types.RequestPrepareProposal) types.Resp
 		return types.ResponsePrepareProposal{}
 	}
 
-	// Inject system transactions at the end of the block.
-	systemTxs, systemTxResults, err := mux.prepareSystemTxs()
+	// Inject system transactions and their results at the end of the block.
+	//
+	// It is important to inject the results first, so that the results hash
+	// in the block metadata transaction includes all results, including results
+	// from system transactions.
+	systemTxResults := mux.prepareSystemTxResults()
+	mux.state.proposal.resultsDeliverTx = append(mux.state.proposal.resultsDeliverTx, systemTxResults...)
+
+	systemTxs, err := mux.prepareSystemTxs()
 	if err != nil {
 		mux.logger.Error("failed to prepare system transactions",
 			"height", req.Height,
@@ -444,7 +451,6 @@ func (mux *abciMux) PrepareProposal(req types.RequestPrepareProposal) types.Resp
 		return types.ResponsePrepareProposal{}
 	}
 	txs = append(txs, systemTxs...)
-	mux.state.proposal.resultsDeliverTx = append(mux.state.proposal.resultsDeliverTx, systemTxResults...)
 
 	// Record proposal inputs so we can compare in ProcessProposal.
 	p := mux.state.proposal

go/consensus/cometbft/abci/system.go

@@ -6,6 +6,7 @@ import (
 	"fmt"
 
 	"github.com/cometbft/cometbft/abci/types"
+	cmttypes "github.com/cometbft/cometbft/types"
 
 	"github.com/oasisprotocol/oasis-core/go/common/cbor"
 	consensus "github.com/oasisprotocol/oasis-core/go/consensus/api"
@@ -16,47 +17,62 @@ import (
 	"github.com/oasisprotocol/oasis-core/go/upgrade/migrations"
 )
 
-// prepareSystemTxs prepares a list of system transactions to be included in a proposed block in
-// case where the node is currently the block proposer.
-func (mux *abciMux) prepareSystemTxs() ([][]byte, []*types.ResponseDeliverTx, error) {
-	var (
-		systemTxs       [][]byte
-		systemTxResults []*types.ResponseDeliverTx
-	)
+// prepareSystemTxs prepares a list of system transactions to be included
+// in a proposed block in case where the node is currently the block proposer.
+func (mux *abciMux) prepareSystemTxs() ([][]byte, error) {
+	blockMetaTx, err := mux.prepareBlockMetaTx()
+	if err != nil {
+		return nil, fmt.Errorf("failed to prepare block metadata transaction: %w", err)
+	}
+	return [][]byte{blockMetaTx}, nil
+}
+
+// prepareSystemTxResults prepares a list of system transaction results to be included
+// in a proposed block in case where the node is currently the block proposer.
+func (mux *abciMux) prepareSystemTxResults() []*types.ResponseDeliverTx {
+	blockMetaResults := mux.prepareBlockMetaTxResults()
+	return []*types.ResponseDeliverTx{blockMetaResults}
+}
 
-	// Append block metadata as a system transaction.
+// prepareBlockMetaTx prepares block metadata system transaction.
+func (mux *abciMux) prepareBlockMetaTx() ([]byte, error) {
 	stateRoot, err := mux.state.workingStateRoot()
 	if err != nil {
-		return nil, nil, fmt.Errorf("failed to compute working state root: %w", err)
+		return nil, fmt.Errorf("failed to compute working state root: %w", err)
 	}
 	eventsRoot, err := mux.computeEventsRoot()
 	if err != nil {
-		return nil, nil, fmt.Errorf("failed to compute events root: %w", err)
+		return nil, fmt.Errorf("failed to compute events root: %w", err)
 	}
+	resultsHash := mux.computeResultsHash()
 
 	blockMeta := consensus.NewBlockMetadataTx(&consensus.BlockMetadata{
-		StateRoot:  stateRoot,
-		EventsRoot: eventsRoot,
+		StateRoot:   stateRoot,
+		EventsRoot:  eventsRoot,
+		ResultsHash: resultsHash,
 	})
 	sigBlockMeta, err := transaction.Sign(mux.state.identity.ConsensusSigner, blockMeta)
 	if err != nil {
-		return nil, nil, fmt.Errorf("failed to sign block metadata transaction: %w", err)
+		return nil, fmt.Errorf("failed to sign block metadata transaction: %w", err)
 	}
 	sigBlockMetaRaw := cbor.Marshal(sigBlockMeta)
 	if l := len(sigBlockMetaRaw); l > consensus.BlockMetadataMaxSize {
 		mux.logger.Error("serialized block metadata larger than maximum allowed size",
 			"meta_size", l,
 			"max_meta_size", consensus.BlockMetadataMaxSize,
 		)
-		return nil, nil, fmt.Errorf("serialized block metadata would be oversized")
+		return nil, fmt.Errorf("serialized block metadata would be oversized")
 	}
-	systemTxs = append(systemTxs, sigBlockMetaRaw)
-	systemTxResults = append(systemTxResults, &types.ResponseDeliverTx{
+
+	return sigBlockMetaRaw, nil
+}
+
+// prepareBlockMetaTxResults prepares block metadata system transaction results.
+func (mux *abciMux) prepareBlockMetaTxResults() *types.ResponseDeliverTx {
+	return &types.ResponseDeliverTx{
 		Code: types.CodeTypeOK,
 		Data: cbor.Marshal(nil),
-	})
-
-	return systemTxs, systemTxResults, nil
+	}
 }
 
 // processSystemTx processes a system transaction in DeliverTx context.
@@ -102,7 +118,7 @@ func (mux *abciMux) validateSystemTxs() error {
 	for _, tx := range mux.state.blockCtx.SystemTransactions {
 		switch tx.Method {
 		case consensus.MethodMeta:
-			// Block metadata, verify state root.
+			// Decode block metadata.
 			if hasBlockMetadata {
 				return fmt.Errorf("duplicate block metadata in block")
 			}
@@ -134,9 +150,16 @@ func (mux *abciMux) validateSystemTxs() error {
 				return fmt.Errorf("invalid events root in block metadata (expected: %x got: %x)", eventsRoot, meta.EventsRoot)
 			}
 
+			// Verify results hash.
+			resultsHash := mux.computeResultsHash()
+			if !bytes.Equal(resultsHash, meta.ResultsHash) {
+				return fmt.Errorf("invalid results hash in block metadata (expected: %x got: %x)", resultsHash, meta.ResultsHash)
+			}
+
 			mux.logger.Debug("validated block metadata",
 				"state_root", meta.StateRoot,
 				"events_root", hex.EncodeToString(eventsRoot),
+				"results_hash", hex.EncodeToString(resultsHash),
 			)
 		default:
 			return fmt.Errorf("unknown system method: %s", tx.Method)
@@ -176,3 +199,10 @@ func (mux *abciMux) computeEventsRoot() ([]byte, error) {
 
 	return merkle.RootHash(events), nil
 }
+
+func (mux *abciMux) computeResultsHash() []byte {
+	if !mux.state.ConsensusParameters().IsFeatureVersion(migrations.Version256) {
+		return nil
+	}
+	return cmttypes.NewResults(mux.state.proposal.resultsDeliverTx).Hash()
+}

go/upgrade/migrations/consensus_256.go

@@ -16,6 +16,7 @@ import (
 //     are allowed to query runtime key shares.
 //   - An updated events root in the block metadata system transaction to capture all events
 //     emitted in the block.
+//   - A results hash in the block metadata system transaction.
 const Consensus256 = "consensus256"
 
 // Version256 is the Oasis Core 25.6 version.

runtime/src/consensus/mod.rs

@@ -49,4 +49,7 @@ pub struct BlockMetadata {
     pub state_root: Hash,
     // Root hash of all events emitted in the block.
     pub events_root: Vec<u8>,
+    // Hash of transaction results in the block.
+    #[cbor(optional)]
+    pub results_hash: Vec<u8>,
 }