Add ProtocolStateVersionUpgrade service event (#464)

* add service event definition and doc

* move service event to version beacon

* add heartbeat/admin process for proto state version

accepting broken assets.go, will regenerate after cherry-pick is
complete

* add smoketest for setting protostate version

broken assets.go

* Apply suggestions from code review

* generate

broken assets.go

* update contract for cadence1

* update admin tx for cadence 1

* generate

* emit service event in governance transaction

Previously service events could only be emitted in the system chunk.
With onflow/flow-go#5828, we can directly emit
them in governance transactions.

* re-generate assets

* fix field reflection

* add context for where validation occurs and multiple emissions

* make generate

contracts/NodeVersionBeacon.cdc

@@ -18,6 +18,10 @@
 /// The contract itself can be used to query the current version and the next upcoming version.
 access(all) contract NodeVersionBeacon {
 
+    /// =========================
+    /// Execution State Versioning
+    /// =========================
+
     /// Struct representing software version as Semantic Version
     /// along with helper functions
     /// For reference, see https://semver.org/
@@ -134,10 +138,11 @@ access(all) contract NodeVersionBeacon {
         )
     }
 
-    /// Event emitted when the version table is updated.
-    /// It contains the current version and all the upcoming versions
-    /// sorted by block height.
-    /// The sequence increases by one each time an event is emitted.
+    /// A service event emitted when the version table is updated.
+    /// The version is the software version which must be used for executing a height range of blocks.
+    /// The version pertains to Execution and Verification Nodes.
+    /// The table contains the current version and all the upcoming versions sorted by block height.
+    /// The sequence increases by one each time an event is emitted. 
     /// It can be used to verify no events were missed.
     access(all) event VersionBeacon(
         versionBoundaries: [VersionBoundary],
@@ -280,6 +285,18 @@ access(all) contract NodeVersionBeacon {
 
             emit NodeVersionBoundaryFreezePeriodChanged(freezePeriod: newFreezePeriod)
         }
+
+        /// Emits the given protocol state version upgrade event.
+        /// If the version and active view are valid, this will cause the Protocol State
+        /// to upgrade its model version when the event is incorporated.
+        /// If either the version or active view are invalid, the service event will be
+        /// ignored and will have no effect. All validation is performed when the service
+        /// event is incorporated by the Protocol State.
+        /// It is safe to emit the same ProtocolStateVersionUpgrade event multiple times,
+        /// as only version upgrade will occur.
+        access(all) fun emitProtocolStateVersionUpgrade(newProtocolVersion: UInt64, activeView: UInt64) {
+            emit ProtocolStateVersionUpgrade(newProtocolVersion: newProtocolVersion, activeView: activeView)
+        }
     }
 
     /// Heartbeat resource that emits the version beacon event and keeps track of upcoming versions.
@@ -495,6 +512,17 @@ access(all) contract NodeVersionBeacon {
         return self.versionBoundaryBlockList[0]
     }
 
+    /// =========================
+    /// Protocol State Versioning
+    /// =========================
+
+    /// A service event which is emitted to indicate that the Protocol State version is being upgraded.
+    /// This acts as a signal to begin using the upgraded Protocol State version 
+    /// after this service event is sealed, and after view `activeView` is entered.
+    /// Nodes running a software version which does not support `newProtocolVersion`
+    /// will stop processing new blocks when they reach view `activeAtView`.
+    access(all) event ProtocolStateVersionUpgrade(newProtocolVersion: UInt64, activeView: UInt64)
+
     init(versionUpdateFreezePeriod: UInt64) {
         self.AdminStoragePath = /storage/NodeVersionBeaconAdmin
         self.HeartbeatStoragePath = /storage/NodeVersionBeaconHeartbeat