go/consensus/cometbft/abci/system: Add results hash to system tx

The results hash was added to the 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/system: Add results hash to system tx
+
+The results hash was added to the 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"`
 }
 
 // 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/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"
@@ -33,10 +34,12 @@ func (mux *abciMux) prepareSystemTxs() ([][]byte, []*types.ResponseDeliverTx, er
 	if err != nil {
 		return nil, 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 {
@@ -97,7 +100,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")
 			}
@@ -129,9 +132,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)
@@ -171,3 +181,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.