axelar-cgp-sui

Module 0xb0::version_control

This module implements a custom version control scheme to maximize versioning customizability.

• Struct VersionControl
• Constants
• Function new
• Function allowed_functions
• Function push_back
• Function allow_function
• Function disallow_function
• Function check
• Function latest_version

use 0x1::ascii;
use 0x1::vector;
use 0x2::vec_set;

Struct VersionControl

The function names are stored as Strings. They are however input as vector for ease of instantiation.

struct VersionControl has copy, drop, store

Fields

allowed_functions: vector<vec_set::VecSet<ascii::String>>

Constants

#[error]
const EFunctionAlreadyAllowed: vector<u8> = b"trying to allow a function already allowed on the specified version";

#[error]
const EFunctionAlreadyDisallowed: vector<u8> = b"trying to disallow a function already disallowed on the specified version";

#[error]
const EFunctionNotSupported: vector<u8> = b"function is not supported in this version";

Function new

Create a new Version Control object by passing in the allowed_functions data. You are supposed to pass a vector of the bytes of the functions that are allowed per version. For example:

vector [
vector [ b"v0_function" ],
vector [ b"v0_function", b"v1_function"],
]

Would allow only v0_function to be called on version == 0, and both v0_function and v1_function to be called on version == 1. This is done to simplify the instantiation syntax of VersionControl.

public fun new(allowed_functions: vector<vector<ascii::String>>): version_control::VersionControl

Implementation

public fun new(allowed_functions: vector<vector<String>>): VersionControl {
    VersionControl {
        allowed_functions: allowed_functions.map!(
            |function_names| vec_set::from_keys(
                function_names,
            ),
        ),
    }
}

Function allowed_functions

This allowes for anyone to modify the raw data of allowed functions. Do not pass a mutable reference of your VersionControl to anyone you do not trust because they can modify it.

public fun allowed_functions(self: &mut version_control::VersionControl): &mut vector<vec_set::VecSet<ascii::String>>

Implementation

public fun allowed_functions(
    self: &mut VersionControl,
): &mut vector<VecSet<String>> {
    &mut self.allowed_functions
}

Function push_back

If a new version does not need to deprecate any old functions, you can use this to add the newly supported functions.

public fun push_back(self: &mut version_control::VersionControl, function_names: vector<ascii::String>)

Implementation

public fun push_back(
    self: &mut VersionControl,
    function_names: vector<String>,
) {
    self
        .allowed_functions
        .push_back(
            vec_set::from_keys(
                function_names,
            ),
        );
}

Function allow_function

public fun allow_function(self: &mut version_control::VersionControl, version: u64, function_name: ascii::String)

Implementation

public fun allow_function(
    self: &mut VersionControl,
    version: u64,
    function_name: String,
) {
    assert!(
        !self.allowed_functions[version].contains(&function_name),
        EFunctionAlreadyAllowed,
    );
    self.allowed_functions[version].insert(function_name);
}

Function disallow_function

public fun disallow_function(self: &mut version_control::VersionControl, version: u64, function_name: ascii::String)

Implementation

public fun disallow_function(
    self: &mut VersionControl,
    version: u64,
    function_name: String,
) {
    assert!(
        self.allowed_functions[version].contains(&function_name),
        EFunctionAlreadyDisallowed,
    );
    self.allowed_functions[version].remove(&function_name);
}

Function check

Call this at the begining of each version controlled function. For example

public fun do_something(data: &mut DataType) {
data.version_control.check(VERSION, b"do_something");
// do the thing.
}

public fun check(self: &version_control::VersionControl, version: u64, function: ascii::String)

Implementation

public fun check(self: &VersionControl, version: u64, function: String) {
    assert!(
        self.allowed_functions[version].contains(&function),
        EFunctionNotSupported,
    );
}

Function latest_version

Returns the latest valid index in allowed functions.

public fun latest_version(self: &version_control::VersionControl): u64

Implementation

public fun latest_version(self: &VersionControl): u64 {
    self.allowed_functions.length() - 1
}