From fb5c73136d54d316b0ef1bb1654cb79428222eee Mon Sep 17 00:00:00 2001 From: vms Date: Tue, 27 Jun 2023 11:23:35 +0300 Subject: [PATCH] add AquaVM update guide --- .../preparation_step/interpreter_versions.rs | 8 +++-- crates/air-lib/interpreter-data/src/lib.rs | 6 ++-- docs/update-guide.md | 34 +++++++++++++++++++ 3 files changed, 44 insertions(+), 4 deletions(-) create mode 100644 docs/update-guide.md diff --git a/air/src/preparation_step/interpreter_versions.rs b/air/src/preparation_step/interpreter_versions.rs index a8c04bb623..6ca6191777 100644 --- a/air/src/preparation_step/interpreter_versions.rs +++ b/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 = +/// Minimal supported interpreter version, should be updated according to +/// [./docs/update-guide.md] +static MINIMAL_INTERPRETER_VERSION: Lazy = 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 = 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. diff --git a/crates/air-lib/interpreter-data/src/lib.rs b/crates/air-lib/interpreter-data/src/lib.rs index 41378552ec..8cd2c48d81 100644 --- a/crates/air-lib/interpreter-data/src/lib.rs +++ b/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 = Lazy::new(|| { +/// Interpreter data version, more info in +/// [./docs/update-guide.md] +static INTERPRETER_DATA_VERSION: Lazy = 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) } diff --git a/docs/update-guide.md b/docs/update-guide.md new file mode 100644 index 0000000000..b066c631b7 --- /dev/null +++ b/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.