fixup! feat: use collect mcycle root hashes API

Author: vfusco

pkg/emulator/machine.go

@@ -23,6 +23,7 @@ package emulator
 import "C"
 
 import (
+	"encoding/json"
 	"runtime"
 	"sync"
 	"unsafe"
@@ -33,6 +34,12 @@ const HashSize = C.sizeof_cm_hash
 // Common type aliases
 type Hash = [HashSize]byte
 
+// RevertUarchTail is the emulator-owned JSON array of base64-encoded state
+// hashes for the reset-delimited uarch period corresponding to a revert root.
+// It remains opaque so collector output can be passed back without decoding and
+// re-encoding every hash.
+type RevertUarchTail json.RawMessage
+
 // -----------------------------------------------------------------------------
 // Machine Methods
 // -----------------------------------------------------------------------------
@@ -365,24 +372,30 @@ func (m *Machine) Run(mcycleEnd uint64) (BreakReason, error) {
 }
 
 // collect_mcycle_root_hashes
-func (m *Machine) CollectMCycleRootHashes(mcycleEnd, log2McyclePeriod, mcyclePhase uint64, log2BundleMcycleCount int32, previousBackTree string) ([]byte, error) {
+func (m *Machine) CollectMCycleRootHashes(
+	mcycleEnd,
+	log2McyclePeriod,
+	mcyclePhase uint64,
+	log2BundleMcycleCount int32,
+	previousPartialBundle json.RawMessage,
+) ([]byte, error) {
 	var err error
 	var result []byte
 
 	m.callCAPI(func() {
 		var cResult *C.char
-		var previousBackTreeC *C.char
-		if previousBackTree != "" {
-			previousBackTreeC = C.CString(previousBackTree)
-			defer C.free(unsafe.Pointer(previousBackTreeC))
+		var previousPartialBundleC *C.char
+		if len(previousPartialBundle) > 0 {
+			previousPartialBundleC = C.CString(string(previousPartialBundle))
+			defer C.free(unsafe.Pointer(previousPartialBundleC))
 		}
 		err = newError(C.cm_collect_mcycle_root_hashes(
 			m.ptr,
 			C.uint64_t(mcycleEnd),
 			C.uint64_t(log2McyclePeriod),
 			C.uint64_t(mcyclePhase),
 			C.int32_t(log2BundleMcycleCount),
-			previousBackTreeC,
+			previousPartialBundleC,
 			&cResult))
 		result = []byte(C.GoString(cResult))
 	})
@@ -394,15 +407,19 @@ func (m *Machine) CollectMCycleRootHashes(mcycleEnd, log2McyclePeriod, mcyclePha
 }
 
 // collect_uarch_cycle_root_hashes
-func (m *Machine) CollectUarchCycleRootHashes(mcycleEnd uint64, log2BundleUarchCycleCount int32, revertUarchTail string) ([]byte, error) {
+func (m *Machine) CollectUarchCycleRootHashes(
+	mcycleEnd uint64,
+	log2BundleUarchCycleCount int32,
+	revertUarchTail RevertUarchTail,
+) ([]byte, error) {
 	var err error
 	var result []byte
 
 	m.callCAPI(func() {
 		var cResult *C.char
 		var revertUarchTailC *C.char
-		if revertUarchTail != "" {
-			revertUarchTailC = C.CString(revertUarchTail)
+		if len(revertUarchTail) > 0 {
+			revertUarchTailC = C.CString(string(revertUarchTail))
 			defer C.free(unsafe.Pointer(revertUarchTailC))
 		}
 		err = newError(C.cm_collect_uarch_cycle_root_hashes(

pkg/emulator/machine_test.go

@@ -0,0 +1,147 @@
+// (c) Cartesi and individual authors (see AUTHORS)
+// SPDX-License-Identifier: Apache-2.0 (see LICENSE)
+
+package emulator
+
+import (
+	"encoding/base64"
+	"encoding/binary"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+type mcycleRootHashesResult struct {
+	Hashes        []string        `json:"hashes"`
+	MCyclePhase   uint64          `json:"mcycle_phase"`
+	BreakReason   string          `json:"break_reason"`
+	PartialBundle json.RawMessage `json:"partial_bundle,omitempty"`
+}
+
+func createLoopMachine(t *testing.T) *Machine {
+	t.Helper()
+
+	const ramLength = 4096
+	image := make([]byte, ramLength)
+	// jal x0, 0 loops forever while allowing mcycle to advance predictably.
+	binary.LittleEndian.PutUint32(image, 0x0000006f)
+	imagePath := filepath.Join(t.TempDir(), "loop.bin")
+	require.NoError(t, os.WriteFile(imagePath, image, 0o600))
+
+	config, err := json.Marshal(map[string]any{
+		"ram": map[string]any{
+			"length": ramLength,
+			"backing_store": map[string]any{
+				"data_filename": imagePath,
+			},
+		},
+	})
+	require.NoError(t, err)
+
+	machine, err := CreateMachine(string(config), "", "")
+	require.NoError(t, err)
+	t.Cleanup(func() {
+		assert.NoError(t, machine.Destroy())
+		machine.Delete()
+	})
+	return machine
+}
+
+func collectMCycleRootHashes(
+	t *testing.T,
+	machine *Machine,
+	target,
+	log2Period,
+	phase uint64,
+	log2Bundle int32,
+	partialBundle json.RawMessage,
+) mcycleRootHashesResult {
+	t.Helper()
+
+	rawResult, err := machine.CollectMCycleRootHashes(target, log2Period, phase, log2Bundle, partialBundle)
+	require.NoError(t, err)
+	var result mcycleRootHashesResult
+	require.NoError(t, json.Unmarshal(rawResult, &result))
+	return result
+}
+
+func TestCollectMCycleRootHashes_PartitionedBundlingMatchesOneShot(t *testing.T) {
+	const (
+		mcycleStart = uint64(1)
+		mcycleEnd   = uint64(65)
+		log2Period  = uint64(2)
+		log2Bundle  = int32(2)
+	)
+	targets := []uint64{2, 7, 19, 34, mcycleEnd}
+
+	oneShotMachine := createLoopMachine(t)
+	partitionedMachine := createLoopMachine(t)
+	for _, machine := range []*Machine{oneShotMachine, partitionedMachine} {
+		breakReason, err := machine.Run(mcycleStart)
+		require.NoError(t, err)
+		require.Equal(t, BreakReasonReachedTargetMcycle, breakReason)
+	}
+
+	oneShot := collectMCycleRootHashes(
+		t,
+		oneShotMachine,
+		mcycleEnd,
+		log2Period,
+		mcycleStart%(uint64(1)<<log2Period),
+		log2Bundle,
+		nil,
+	)
+
+	partitioned := mcycleRootHashesResult{
+		MCyclePhase: mcycleStart % (uint64(1) << log2Period),
+	}
+	sawPartialBundle := false
+	for _, target := range targets {
+		result := collectMCycleRootHashes(
+			t,
+			partitionedMachine,
+			target,
+			log2Period,
+			partitioned.MCyclePhase,
+			log2Bundle,
+			partitioned.PartialBundle,
+		)
+		partitioned.Hashes = append(partitioned.Hashes, result.Hashes...)
+		partitioned.MCyclePhase = result.MCyclePhase
+		partitioned.BreakReason = result.BreakReason
+		partitioned.PartialBundle = result.PartialBundle
+		sawPartialBundle = sawPartialBundle || len(result.PartialBundle) > 0
+	}
+
+	require.True(t, sawPartialBundle, "test partitions must exercise partial-bundle continuation")
+	require.Equal(t, oneShot, partitioned)
+
+	oneShotRoot, err := oneShotMachine.GetRootHash()
+	require.NoError(t, err)
+	partitionedRoot, err := partitionedMachine.GetRootHash()
+	require.NoError(t, err)
+	require.Equal(t, oneShotRoot, partitionedRoot)
+}
+
+func TestCollectUarchCycleRootHashes_AcceptsOpaqueRevertTail(t *testing.T) {
+	machine := createLoopMachine(t)
+	zeroHash := Hash{}
+	encodedZeroHash := base64.StdEncoding.EncodeToString(zeroHash[:])
+	tail, err := json.Marshal([]string{encodedZeroHash, encodedZeroHash})
+	require.NoError(t, err)
+
+	rawResult, err := machine.CollectUarchCycleRootHashes(1, 0, RevertUarchTail(tail))
+	require.NoError(t, err)
+
+	var result struct {
+		Hashes      []string `json:"hashes"`
+		BreakReason string   `json:"break_reason"`
+	}
+	require.NoError(t, json.Unmarshal(rawResult, &result))
+	require.NotEmpty(t, result.Hashes)
+	require.Equal(t, "reached_target_mcycle", result.BreakReason)
+}

pkg/machine/backend.go

@@ -21,12 +21,12 @@ const (
 )
 
 type HashCollectorState struct {
-	Period     uint64
-	Phase      uint64
-	MaxHashes  uint64
-	BundleLog2 int32
-	Hashes     []Hash
-	BackTree   json.RawMessage
+	Period        uint64
+	Phase         uint64
+	MaxHashes     uint64
+	BundleLog2    int32
+	Hashes        []Hash
+	PartialBundle json.RawMessage
 }
 
 // This Backend interface covers the methods used from the emulator / remote machine server.
@@ -36,6 +36,9 @@ type Backend interface {
 	Store(directory string, timeout time.Duration) error
 
 	Run(mcycleEnd uint64, timeout time.Duration) (BreakReason, error)
+	// RunAndCollectRootHashes may advance the backend before returning an error.
+	// Callers must discard the backend after an error instead of retrying it with
+	// the previous HashCollectorState.
 	RunAndCollectRootHashes(mcycleEnd uint64, state *HashCollectorState, timeout time.Duration,
 	) (reason BreakReason, err error)
 

pkg/machine/libcartesi.go

@@ -29,7 +29,13 @@ type RemoteMachineInterface interface {
 	Delete()
 	ForkServer() (*emulator.RemoteMachine, string, uint32, error)
 	ShutdownServer() error
-	CollectMCycleRootHashes(mcycleEnd, log2McyclePeriod, mcyclePhase uint64, log2BundleMcycleCount int32, previousBackTree string) ([]byte, error)
+	CollectMCycleRootHashes(
+		mcycleEnd,
+		log2McyclePeriod,
+		mcyclePhase uint64,
+		log2BundleMcycleCount int32,
+		previousPartialBundle json.RawMessage,
+	) ([]byte, error)
 }
 
 type proofJson struct {
@@ -232,24 +238,24 @@ func (e *LibCartesiBackend) CmioRxBufferSize() uint64 {
 	return 1 << emulator.CmioRxBufferLog2Size
 }
 
-func decodeBreakReason(s string) BreakReason {
+func decodeBreakReason(s string) (BreakReason, error) {
 	switch s {
 	case "yielded_automatically":
-		return YieldedAutomatically
+		return YieldedAutomatically, nil
 	case "yielded_manually":
-		return YieldedManually
+		return YieldedManually, nil
 	case "yielded_softly":
-		return YieldedSoftly
+		return YieldedSoftly, nil
 	case "reached_target_mcycle":
-		return ReachedTargetMcycle
+		return ReachedTargetMcycle, nil
 	case "mcycle_overflow":
-		return McycleOverflow
+		return McycleOverflow, nil
 	case "halted":
-		return Halted
+		return Halted, nil
 	case "failed":
-		return Failed
+		return Failed, nil
 	default:
-		return Failed
+		return Failed, fmt.Errorf("unknown break reason %q", s)
 	}
 }
 
@@ -263,40 +269,61 @@ func (e *LibCartesiBackend) RunAndCollectRootHashes(
 		return Failed, errors.New("nil state")
 	}
 	if state.Period == 0 {
-		return Failed, errors.New("State.Period must be > 0")
+		return Failed, errors.New("state period must be greater than zero")
 	}
 	log2Period := uint64(bits.Len64(state.Period) - 1)
 	if uint64(1)<<log2Period != state.Period {
-		return Failed, fmt.Errorf("period must be a power of 2, got %v.", state.Period)
+		return Failed, fmt.Errorf("period must be a power of 2, got %v", state.Period)
+	}
+	if state.Phase >= state.Period {
+		return Failed, fmt.Errorf("phase must be less than period, got phase %v and period %v", state.Phase, state.Period)
 	}
 	if err := e.inner.SetTimeout(timeout.Milliseconds()); err != nil {
 		return Failed, fmt.Errorf("failed to set operation timeout: %w", err)
 	}
 
-	rawResult, err := e.inner.CollectMCycleRootHashes(mcycleEnd, log2Period, state.Phase, state.BundleLog2, "")
+	rawResult, err := e.inner.CollectMCycleRootHashes(
+		mcycleEnd,
+		log2Period,
+		state.Phase,
+		state.BundleLog2,
+		state.PartialBundle,
+	)
 	if err != nil {
 		return Failed, err
 	}
 	result := struct {
-		RootHashes  []string        `json:"hashes"`
-		MCyclePhase uint64          `json:"mcycle_phase"`
-		BreakReason string          `json:"break_reason"`
-		BackTree    json.RawMessage `json:"back_tree,omitempty"`
+		RootHashes    []string        `json:"hashes"`
+		MCyclePhase   uint64          `json:"mcycle_phase"`
+		BreakReason   string          `json:"break_reason"`
+		PartialBundle json.RawMessage `json:"partial_bundle,omitempty"`
 	}{}
 	err = json.Unmarshal(rawResult, &result)
 	if err != nil {
 		return Failed, fmt.Errorf("failed to unmarshal CollectMCycleRootHashes result: %w", err)
 	}
+	reason, err = decodeBreakReason(result.BreakReason)
+	if err != nil {
+		return Failed, fmt.Errorf("invalid CollectMCycleRootHashes result: %w", err)
+	}
+	if result.MCyclePhase >= state.Period {
+		return Failed, fmt.Errorf(
+			"invalid CollectMCycleRootHashes result: phase %v must be less than period %v",
+			result.MCyclePhase,
+			state.Period,
+		)
+	}
 
-	// convert from base64 and append to collector state
+	decodedHashes := make([]Hash, len(result.RootHashes))
 	for i, base64Hash := range result.RootHashes {
-		hash := Hash{}
-		if err := decodeB64To32(&hash, base64Hash); err != nil {
-			return Failed, fmt.Errorf("received an invalid hash during RunAndCollectRootHashes at index %v, with value: %v.", i, base64Hash)
+		if err := decodeB64To32(&decodedHashes[i], base64Hash); err != nil {
+			return Failed, fmt.Errorf("invalid collected hash at index %v: %w", i, err)
 		}
-		state.Hashes = append(state.Hashes, hash)
 	}
+
+	state.Hashes = append(state.Hashes, decodedHashes...)
 	state.Phase = result.MCyclePhase
-	state.BackTree = result.BackTree
-	return decodeBreakReason(result.BreakReason), nil
+	state.PartialBundle = result.PartialBundle
+
+	return reason, nil
 }