Merge branch 'master' into chore/VM-307-add-canon-guided-topology-tests

air/src/preparation_step/interpreter_versions.rs

@@ -18,9 +18,13 @@ use once_cell::sync::Lazy;
 
 use std::str::FromStr;
 
-static MINIMAL_SUPPORTED_VERSION: Lazy<semver::Version> =
+/// Minimal supported interpreter version, should be updated according to
+/// [./docs/update-guide.md]
+static MINIMAL_INTERPRETER_VERSION: Lazy<semver::Version> =
     Lazy::new(|| semver::Version::from_str("0.40.0").expect("valid minimal supported version specified"));
 
+/// Current interpreter version, more info in
+/// [./docs/update-guide.md]
 static INTERPRETER_VERSION: Lazy<semver::Version> =
     Lazy::new(|| semver::Version::from_str(env!("CARGO_PKG_VERSION")).expect("invalid data format version specified"));
 
@@ -29,7 +33,7 @@ thread_local!(static _MINIMAL_SUPPORTED_VERSION_CHECK: &'static semver::Version
 
 /// Returns a minimal support version by this interpreter.
 pub fn min_supported_version() -> &'static semver::Version {
-    Lazy::force(&MINIMAL_SUPPORTED_VERSION)
+    Lazy::force(&MINIMAL_INTERPRETER_VERSION)
 }
 
 /// Returns a current interpreter version.

crates/air-lib/interpreter-data/src/lib.rs

@@ -47,11 +47,13 @@ use serde_json::Value as JValue;
 
 use std::str::FromStr;
 
-static DATA_FORMAT_VERSION: Lazy<semver::Version> = Lazy::new(|| {
+/// Interpreter data version, more info in
+/// [./docs/update-guide.md]
+static INTERPRETER_DATA_VERSION: Lazy<semver::Version> = Lazy::new(|| {
     semver::Version::from_str(env!("CARGO_PKG_VERSION"))
         .expect("invalid data format version specified")
 });
 
 pub fn data_version() -> &'static semver::Version {
-    Lazy::force(&DATA_FORMAT_VERSION)
+    Lazy::force(&INTERPRETER_DATA_VERSION)
 }

docs/update-guide.md

@@ -0,0 +1,34 @@
+# AquaVM update guide
+
+## AquaVM repo components
+
+Here is the list of main components crucial from the update point of view:
+
+[**AquaVM core**](./air) - the main part of AquaVM interpreter, e.g., it contains instruction implementation
+[**AVM client**](./avm/client) - an AquaVM launcher for browser and Node.js targets
+[**AVM server**](./avm/server) - an AquaVM launcher for server-side targets
+[**AIR parser**](./crates/trace-handler) - a parser of AIR code
+[**Interpreter data**](./crates/air-lib/interpreter-data) - contains definition of data that is passed between different AquaVM in so called particle
+[**Interpreter interface**](./crates/air-lib/interpreter-interface) - contains definition of AquaVM interface which is used by `AVM server` and test runners
+[**Interpreter signature**](./crates/air-lib/interpreter-signatures) - utility crate for signatures, e.g. contains methods for se/de
+[**Trace Handler**](./crates/air-lib/trace-handler) - crate intended to handle all interpreter data related stuff
+
+## AquaVM core updating policy
+
+There are three main variables in the code intended to set and check versions of the main AquaVM core components:
+
+### MINIMAL_INTERPRETER_VERSION
+
+This variable sets the minimal supported version of `AquaVM core`. This variable should be updated after every breaking change in `AquaVM core`, `AIR parser`, `Interpreter data`, `Interpreter signature`, `Trace Handler`, and maybe other crates that break an AIR script execution. Particle'll be rejected if it comes from a network containing a version less than the specified `MINIMAL_INTERPRETER_VERSION` with an error propagated to a host running this AquaVM (so, an error message won't be sent to a peer initiated this communication).
+
+### INTERPRETER_VERSION
+
+It represents the version of the current AquaVM instance, this variable is passed in interpreter data and compared with `MINIMAL_INTERPRETER_VERSION` at the preparation stage. It is updated automatically by `AquaVM core` version.
+
+### INTERPRETER_DATA_VERSION
+
+This variable represents the current version of an interpreter data format, it aims to create a more clear error message when a particle is rejected or is failed to deserialize after a breaking change.
+
+## AVM updating policy
+
+Both `AVM client` and `AVM server` versions should be updated simultaniously in case of breaking change in `AquaVM core` interface, e.g., when arguments are changes. Often they must be updated if `Interpreter interface` crate was changed, but they not need to be updated if `Interpreter data` or `AquaVM core` itself was changed.