Setup rust PLT scheduler project and CI

Author: limemloh

.github/workflows/deployment-build-test.yaml

@@ -7,13 +7,13 @@ on:
     paths:
     - '.github/workflows/deployment-build-test.yaml'
     - 'concordium-base'
-    - 'deployment'
+    - 'plt-deployment-unit'
 
   pull_request:
     paths:
     - '.github/workflows/deployment-build-test.yaml'
     - 'concordium-base'
-    - 'deployment'
+    - 'plt-deployment-unit'
 env:
   CARGO_TERM_COLOR: always # implicitly adds '--color=always' to all cargo commands
 

.github/workflows/plt-scheduler-build-test.yaml

@@ -0,0 +1,52 @@
+name: PLT scheduler checks
+
+on:
+  push:
+    branches:
+    - main
+    paths:
+    - '.github/workflows/deployment-build-test.yaml'
+    - 'concordium-base'
+    - 'plt-deployment-unit'
+    - 'plt-scheduler'
+
+  pull_request:
+    paths:
+    - '.github/workflows/plt-scheduler-build-test.yaml'
+    - 'concordium-base'
+    - 'plt-deployment-unit'
+    - 'plt-scheduler'
+env:
+  CARGO_TERM_COLOR: always # implicitly adds '--color=always' to all cargo commands
+
+jobs:
+  rustfmt:
+    name: Check formatting
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+        with:
+          submodules: recursive
+      - name: Run rustfmt
+        working-directory: plt-scheduler
+        run: |
+          rustup component add rustfmt
+          cargo fmt -- --check
+
+  clippy_test:
+    name: Run Clippy and tests
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+      - name: Clippy
+        working-directory: plt-scheduler
+        run: |
+          rustup component add clippy
+          cargo clippy --all-targets --all-features --locked -- -D warnings
+      - name: Test
+        working-directory: plt-scheduler
+        run: cargo test --all-targets --all-features

plt-scheduler/Cargo.toml

@@ -0,0 +1,6 @@
+[package]
+name = "plt-scheduler"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]

plt-scheduler/README.md

@@ -0,0 +1,8 @@
+# concordium-node: Scheduler implementation for Protocol-level token (PLT)
+
+[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.0-4baaaa.svg)](https://github.com/Concordium/.github/blob/main/.github/CODE_OF_CONDUCT.md)
+![Build and test](https://github.com/Concordium/concordium-node/actions/workflows/plt-scheduler-build-test.yaml/badge.svg)
+
+This crate provides a scheduler (transaction execution) implementation for concordium-node, and currently only supports transactions related to Protocol-level Tokens.
+
+It is compiled as a native library and is used within the Haskell implemented scheduler found as part of [`concordium-consensus`](../concordium-consensus/README.md).

plt-scheduler/rust-toolchain.toml

@@ -0,0 +1,2 @@
+[toolchain]
+channel = "1.82"

plt-scheduler/src/lib.rs

@@ -0,0 +1,164 @@
+// Placeholder types to be defined or replaced with types from concordium-base.
+
+type MutableTokenState = ();
+type PLTConfiguration = ();
+type TokenRawAmount = ();
+type TokenAmountDelta = ();
+type TokenIndex = ();
+type AccountIndex = ();
+type TokenId = ();
+
+/// Operations on the state of a block in the chain.
+trait BlockStateOperations {
+    // Protocol-level token state query interface.
+
+    /// Get the [`TokenId`]s of all protocol-level tokens registered on the chain.
+    ///
+    /// If the protocol version does not support protocol-level tokens, this will return the empty
+    /// list.
+    fn get_plt_list(&self) -> impl std::iter::Iterator<Item = TokenId>;
+
+    /// Get the [`TokenIndex`] associated with a [`TokenId`] (if it exists).
+    ///
+    /// # Arguments
+    ///
+    /// - `token_index` The token index to update.
+    fn get_token_index(&self, token_id: TokenId) -> Option<TokenIndex>;
+
+    /// Convert a persistent state to a mutable one that can be updated by the scheduler.
+    ///
+    /// Updates to this state will only persist in the block state using [`BlockStateOperaionts::set_token_state`].
+    ///
+    /// # Arguments
+    ///
+    /// - `token_index` The index of the token to get the state from.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the token identified by `token_index` does not exist.
+    fn get_mutable_token_state(&self, token_index: TokenIndex) -> MutableTokenState;
+
+    /// Get the configuration of a protocol-level token.
+    ///
+    /// # Arguments
+    ///
+    /// - `token_index` The index of the token to get the config for.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the token identified by `token_index` does not exist.
+    fn get_token_configuration(&self, token_index: TokenIndex) -> PLTConfiguration;
+
+    /// Get the circulating supply of a protocol-level token.
+    ///
+    /// # Arguments
+    ///
+    /// - `token_index` The index of the token to get the circulating supply.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the token identified by `token_index` does not exist.
+    fn get_token_circulating_supply(&self, token_index: TokenIndex) -> TokenRawAmount;
+
+    /// Set the recorded total circulating supply for a protocol-level token.
+    ///
+    /// This should always be kept up-to-date with the total balance held in accounts.
+    ///
+    /// # Arguments
+    ///
+    /// - `token_index` The token index to update.
+    /// - `circulation_supply` The new total circulating supply for the token.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the token identified by `token_index` does not exist.
+    fn set_token_circulating_supply(
+        &mut self,
+        token_index: TokenIndex,
+        circulating_supply: TokenRawAmount,
+    );
+
+    /// Create a new token with the given configuration. The initial state will be empty
+    /// and the initial supply will be 0. Returns the token index and the updated state.
+    ///
+    /// # Arguments
+    ///
+    /// - `configuration` The configuration for the token.
+    ///
+    /// # Preconditions
+    ///
+    /// The caller must ensure the following conditions are true, and failing to do so results in
+    /// undefined behavior.
+    ///
+    /// - The `token_id` of the given configuration MUST NOT already be in use by a protocol-level
+    ///   token, i.e. `assert_eq!(s.get_token_index(configuration.token_id), None)`.
+    /// - The [`PLTConfiguration`] MUST be valid and in particular the 'governance_account_index'
+    ///   MUST reference a valid account.
+    fn create_token(&mut self, configuration: PLTConfiguration) -> TokenIndex;
+
+    /// Update the token balance of an account.
+    ///
+    /// # Arguments
+    ///
+    /// - `token_index` The token index to update.
+    /// - `account_index` The account to update.
+    /// - `amount_delta` The token balance delta.
+    ///
+    /// # Errors
+    ///
+    /// - [`OverflowError`] The update would overflow or underflow the token balance on the account.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the token identified by `token_index` does not exist.
+    fn update_token_account_balance(
+        &mut self,
+        token_index: TokenIndex,
+        account_index: AccountIndex,
+        amount_delta: TokenAmountDelta,
+    ) -> Result<(), OverflowError>;
+
+    /// Touch the token account. This initializes a token account state with a
+    /// balance of zero. This only affects an account if its state for the token
+    /// is empty.
+    ///
+    /// Returns `false`, if the account already contained a token account state.
+    ///
+    /// # Arguments
+    ///
+    /// - `token_index` The token index to update.
+    /// - `account_index` The account to update.
+    ///
+    /// # Panics
+    ///
+    /// Panics if:
+    ///
+    /// - the token identified by `token_index` does not exist.
+    /// - the account identified by `account_index` does not exist.
+    #[must_use]
+    fn touch_token_account(&mut self, token_index: TokenIndex, account_index: AccountIndex)
+        -> bool;
+
+    /// Increment the update sequence number for Protocol Level Tokens (PLT).
+    ///
+    /// Unlike the other chain updates this is a separate function, since there is no queue associated with PLTs.
+    fn increment_plt_update_sequence_number(&mut self);
+
+    /// Convert a mutable state to a persistent one and store it in the block state.
+    ///
+    /// To ensure this is future-proof, the mutable state should not be used after this call.
+    ///
+    /// # Arguments
+    ///
+    /// - `token_index` The token index to update.
+    /// - `mutable_token_state` The mutated state to set as the current token state.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the token identified by `token_index` does not exist.
+    fn set_token_state(&mut self, token_index: TokenIndex, mutable_token_state: MutableTokenState);
+}
+
+/// The computation resulted in overflow.
+#[derive(Debug)]
+pub struct OverflowError;