add more comments

fvm/environment/minimum_required_version.go

@@ -27,28 +27,45 @@ func NewMinimumRequiredVersion(
 func (c minimumRequiredVersion) MinimumRequiredVersion() (string, error) {
 	executionParameters := c.txnPreparer.ExecutionParameters()
 
-	cadenceVersion := mapToCadenceVersion(executionParameters.ExecutionVersion, fvmToCadenceVersionMapping)
+	// map the minimum required flow-go version to a minimum required cadence version
+	cadenceVersion := mapToCadenceVersion(executionParameters.ExecutionVersion, minimumFvmToMinimumCadenceVersionMapping)
 
 	return cadenceVersion.String(), nil
 }
 
+// mapToCadenceVersion finds the entry in the versionMapping with the flow version that is closest to,
+// but not higher the given flowGoVersion than returns the cadence version for that entry.
+// the versionMapping is assumed to be sorted by flowGoVersion.
 func mapToCadenceVersion(flowGoVersion semver.Version, versionMapping []VersionMapEntry) semver.Version {
 	// return 0.0.0 if there is no mapping for the version
-	var cadenceVersion = semver.Version{}
-
-	greaterThanOrEqualTo := func(version semver.Version, versionToCompare semver.Version) bool {
-		return version.Compare(versionToCompare) >= 0
-	}
-
+	var closestEntry = VersionMapEntry{}
+
+	// example setup: flowGoVersion = 2.1
+	// versionMapping = [
+	// 	{FlowGoVersion: 1.0, CadenceVersion: 1.1},
+	// 	{FlowGoVersion: 2.0, CadenceVersion: 2.1},
+	// 	{FlowGoVersion: 2.1, CadenceVersion: 2.2},
+	// 	{FlowGoVersion: 3.0, CadenceVersion: 3.1},
+	// 	{FlowGoVersion: 4.0, CadenceVersion: 4.1},
+	// ]
 	for _, entry := range versionMapping {
-		if greaterThanOrEqualTo(flowGoVersion, entry.FlowGoVersion) {
-			cadenceVersion = entry.CadenceVersion
+		// loop 1: 2.1 >= 1.0 closest entry is 0
+		// loop 2: 2.1 >= 2.0 closest entry is 1
+		// loop 3: 2.1 >= 2.1 closest entry is 2
+		// loop 4: 2.1 < 3.0 we went too high: closest entry is 2 break
+		if versionGreaterThanOrEqualTo(flowGoVersion, entry.FlowGoVersion) {
+			closestEntry = entry
 		} else {
 			break
 		}
 	}
 
-	return cadenceVersion
+	// return the cadence version for the closest entry (2): 2.2
+	return closestEntry.CadenceVersion
+}
+
+func versionGreaterThanOrEqualTo(version semver.Version, other semver.Version) bool {
+	return version.Compare(other) >= 0
 }
 
 type VersionMapEntry struct {
@@ -60,7 +77,7 @@ type VersionMapEntry struct {
 // Entries are only needed for cadence versions where cadence intends to switch behaviour
 // based on the version.
 // This should be ordered in ascending order by FlowGoVersion.
-var fvmToCadenceVersionMapping = []VersionMapEntry{
+var minimumFvmToMinimumCadenceVersionMapping = []VersionMapEntry{
 	// Leaving this example in, so it's easier to understand
 	//{
 	//	FlowGoVersion:  *semver.New("0.37.0"),
@@ -69,7 +86,7 @@ var fvmToCadenceVersionMapping = []VersionMapEntry{
 }
 
 func SetFVMToCadenceVersionMappingForTestingOnly(mapping []VersionMapEntry) {
-	fvmToCadenceVersionMapping = mapping
+	minimumFvmToMinimumCadenceVersionMapping = mapping
 }
 
 var _ MinimumRequiredVersion = (*minimumRequiredVersion)(nil)

fvm/environment/minimum_required_version_test.go

@@ -8,31 +8,27 @@ import (
 )
 
 func Test_MapToCadenceVersion(t *testing.T) {
-	v0 := semver.Version{}
+	flowV0 := semver.Version{}
+	cadenceV0 := semver.Version{}
 	flowV1 := semver.Version{
-		Major:      1,
-		Minor:      2,
-		Patch:      3,
-		PreRelease: "rc.1",
+		Major: 0,
+		Minor: 37,
+		Patch: 0,
 	}
 	flowV2 := semver.Version{
-		Major:      2,
-		Minor:      2,
-		Patch:      3,
-		PreRelease: "rc.1",
+		Major: 0,
+		Minor: 37,
+		Patch: 30,
 	}
-
 	cadenceV1 := semver.Version{
-		Major:      2,
-		Minor:      1,
-		Patch:      3,
-		PreRelease: "rc.2",
+		Major: 1,
+		Minor: 0,
+		Patch: 0,
 	}
 	cadenceV2 := semver.Version{
-		Major:      12,
-		Minor:      0,
-		Patch:      0,
-		PreRelease: "",
+		Major: 1,
+		Minor: 1,
+		Patch: 0,
 	}
 
 	mapping := []VersionMapEntry{
@@ -58,13 +54,13 @@ func Test_MapToCadenceVersion(t *testing.T) {
 	}
 
 	t.Run("no mapping, v0", func(t *testing.T) {
-		version := mapToCadenceVersion(v0, nil)
+		version := mapToCadenceVersion(flowV0, nil)
 
-		require.Equal(t, v0, version)
+		require.Equal(t, cadenceV0, version)
 	})
 
 	t.Run("v0", func(t *testing.T) {
-		version := mapToCadenceVersion(v0, mappingWith2Versions)
+		version := mapToCadenceVersion(flowV0, mappingWith2Versions)
 
 		require.Equal(t, semver.Version{}, version)
 	})
@@ -75,7 +71,7 @@ func Test_MapToCadenceVersion(t *testing.T) {
 
 		version := mapToCadenceVersion(v, mappingWith2Versions)
 
-		require.Equal(t, v0, version)
+		require.Equal(t, cadenceV0, version)
 	})
 	t.Run("v1", func(t *testing.T) {
 		version := mapToCadenceVersion(flowV1, mappingWith2Versions)
@@ -122,7 +118,7 @@ func Test_MapToCadenceVersion(t *testing.T) {
 
 		version := mapToCadenceVersion(v, mapping)
 
-		require.Equal(t, v0, version)
+		require.Equal(t, cadenceV0, version)
 	})
 	t.Run("v1, single version in mapping", func(t *testing.T) {
 		version := mapToCadenceVersion(flowV1, mapping)