Revise chain parameters

CHANGELOG.md

@@ -84,6 +84,39 @@
   - Type `Event`/`BakerPoolInfo` field `open_status` is now wrapped in `Upward`.
   - Bubble `Upward` from new variants of `VerifyKey` to `Upward<AccountCredentialWithoutProofs<...>>` in `AccountInfo::account_credentials`.
 
+- BREAKING: Remove types associated with discontinued V1 API:
+  - `types::BlockSummary`;
+  - `types::UpdateKeysCollectionSkeleton` and `types::UpdateKeysCollection`;
+  - `types::ChainParametersV0`, `types::ChainParametersV1`, `types::ChainParametersV2`, `types::ChainParametersV3`, `types::ChainParametersFamily` and `types::ChainParameters`.
+  - `types::RewardParametersSkeleton` and `types::RewardParameters`;
+  - `types::ScheduledUpdate`;
+  - `types::UpdateQueue`;
+  - `types::PendingUpdatesV0`, `types::PendingUpdatesV1`, `types::PendingUpdatesFamily`, and `types::PendingUpdates`;
+  - `types::UpdatesSkeleton` and `types::Updates`;
+  - removed from `concordium_base`:
+    - `ChainParametersVersion0`, `ChainParametersVersion1`, `ChainParametersVersion2`, `ChainParametersVersion3`;
+    - `MintDistributionFamily`, `MintDistribution` (use `MintDistributionV0` or `MintDistributionV1` directly instead where needed);
+    - `GASRewardsFamily` and `GASRewardsFor` (use `GASRewards` and `GASRewardsV1` directly where needed);
+    - `AuthorizationsFamily` and `Authorizations` (use `AuthorizationsV0` and `AuthorizationsV1` directly where needed).
+
+- BREAKING: Remove `v2::ChainParametersV0`, `v2::ChainParametersV1`, `v2::ChainParametersV2` and `v2::ChainParametersV3`, replacing the enum `v2::ChainParameters` with a new struct with optional parameters.
+- A number of supporting types for `ChainParameters` are introduced. These have conversions that can be used to construct the payload types for updating the corresponding parameter sets.
+  - `v2::MintDistribution` (convertible to `types::MintDistributionV1`);
+  - `v2::TransactionFeeDistribution` (convertible to `types::TransactionFeeDistribution`);
+  - `v2::GasRewards` (convertible to `types::GASRewards` and `types::GASRewardsV1`);
+  - `v2::StakingParameters` (convertible to `types::PoolParameters`);
+  - `v2::Level2Keys` (provides `construct_update_signer`, convertible to `types::AuthorizationsV0` and `types::AuthorizationsV1`);
+  - `v2::UpdateKeys`;
+  - `v2::TimeoutParameters` (convertible to `types::TimeParameters`);
+  - `v2::CooldownParameters` (convertible to `types::CooldownParameters`);
+  - `v2::FinalizationCommitteeParameters` (convertible to `types::FinalizationCommitteeParameters`).
+- `v2::EnergyRate` with `ccd_cost` for computing Energy costs in CCD.
+- BREAKING: Changes to `v2::ChainParameters`:
+  - no longer provides `micro_cd_per_energy`, which is replaced by `energy_rate`;
+  - `ccd_cost` is removed, which should be replaced by calling `ccd_cost` on the energy rate instead;
+  - the `foundation_account` getter function is removed, and should be replaced by direct access to the `foundation_account` field;
+  - `common_update_keys` is removed, and instead `keys.level_2_keys` should be used, which can be used to construct an `UpdateSigner`, or converted to `types::AuthorizationsV0`.
+
 ## 7.0.0
 
 Adds support for integrating with Concordium nodes running protocol version 9.

examples/protocol-updates.rs

@@ -99,10 +99,19 @@ async fn main() -> anyhow::Result<()> {
         .context("Could not obtain chain parameters.")?
         .response;
 
+    let keys = summary
+        .keys
+        .level_2_keys
+        .context("No level 2 keys in chain parameters.")?;
+
     // find the key indices to sign with
-    let signer = summary
-        .common_update_keys()
-        .construct_update_signer(&summary.common_update_keys().protocol, kps)
+    let signer = keys
+        .construct_update_signer(
+            keys.protocol
+                .as_ref()
+                .context("Missing protocol update keys")?,
+            kps,
+        )
         .context("Could not construct signer.")?;
 
     let mut seq_number = client
@@ -134,21 +143,17 @@ async fn main() -> anyhow::Result<()> {
         specification_auxiliary_data: Vec::new(),
     };
 
+    let pool_parameters_keys = keys.pool_parameters.context("Missing pool parameters")?;
+
     let params_p4 = ProtocolUpdateDataP4 {
         update_default_commission_rate: CommissionRates {
             finalization: "1".parse().unwrap(),
             baking: "0.1".parse().unwrap(),
             transaction: "0.1".parse().unwrap(),
         },
         update_default_pool_state: OpenStatus::OpenForAll,
-        update_cooldown_parameters_access_structure: summary
-            .common_update_keys()
-            .pool_parameters
-            .clone(),
-        update_time_parameters_access_structure: summary
-            .common_update_keys()
-            .pool_parameters
-            .clone(),
+        update_cooldown_parameters_access_structure: pool_parameters_keys.clone(),
+        update_time_parameters_access_structure: pool_parameters_keys.clone(),
         update_cooldown_parameters: CooldownParameters {
             pool_owner_cooldown: 1800.into(),
             delegator_cooldown: 900.into(),

examples/update-exchange-rate.rs

@@ -52,10 +52,19 @@ async fn main() -> anyhow::Result<()> {
         .context("Could not obtain last finalized block's chain parameters")?
         .response;
 
+    let keys = summary
+        .keys
+        .level_2_keys
+        .context("No level 2 keys in chain parameters.")?;
+
     // find the key indices to sign with
-    let signer = summary
-        .common_update_keys()
-        .construct_update_signer(&summary.common_update_keys().micro_gtu_per_euro, kps)
+    let signer = keys
+        .construct_update_signer(
+            keys.micro_ccd_per_euro
+                .as_ref()
+                .context("Missing micro CCD per Euro update keys.")?,
+            kps,
+        )
         .context("Invalid keys supplied.")?;
 
     let seq_number = client

examples/update-validator-score-param.rs

@@ -54,10 +54,19 @@ async fn main() -> anyhow::Result<()> {
         .context("Could not obtain last finalized block's chain parameters")?
         .response;
 
+    let keys = summary
+        .keys
+        .level_2_keys
+        .context("No level 2 keys in chain parameters.")?;
+
     // find the key indices to sign with
-    let signer = summary
-        .common_update_keys()
-        .construct_update_signer(&summary.common_update_keys().micro_gtu_per_euro, kps)
+    let signer = keys
+        .construct_update_signer(
+            keys.micro_ccd_per_euro
+                .as_ref()
+                .context("Missing micro CCD per Euro update keys.")?,
+            kps,
+        )
         .context("Invalid keys supplied.")?;
 
     let seq_number = client

examples/v2_update_exchange_rate.rs

@@ -53,12 +53,18 @@ async fn main() -> anyhow::Result<()> {
         .await
         .context("Could not obtain chain parameters")?;
 
-    // find the key indices to sign with
-    let signer = params
+    let keys = params
         .response
-        .common_update_keys()
+        .keys
+        .level_2_keys
+        .context("No level 2 keys in chain parameters.")?;
+
+    // find the key indices to sign with
+    let signer = keys
         .construct_update_signer(
-            &params.response.common_update_keys().micro_gtu_per_euro,
+            keys.micro_ccd_per_euro
+                .as_ref()
+                .context("Missing uCCD:EUR exchange rate update keys.")?,
             kps,
         )
         .context("Invalid keys supplied.")?;
@@ -69,12 +75,10 @@ async fn main() -> anyhow::Result<()> {
         .response
         .micro_ccd_per_euro;
 
-    let exchange_rate = match &params.response {
-        v2::ChainParameters::V0(v0) => v0.micro_ccd_per_euro,
-        v2::ChainParameters::V1(v1) => v1.micro_ccd_per_euro,
-        v2::ChainParameters::V2(v2) => v2.micro_ccd_per_euro,
-        v2::ChainParameters::V3(v3) => v3.micro_ccd_per_euro,
-    };
+    let exchange_rate = params
+        .response
+        .micro_ccd_per_euro
+        .context("No exchange rate in chain parameters.")?;
 
     let effective_time = 0.into(); // immediate effect
     let timeout =

src/lib.md

@@ -64,3 +64,48 @@ For the quick proof of concept application the value can be unwrapped using [`un
 [`known_or_err`]: v2::Upward::known_or_err
 [`known_or`]: v2::Upward::known_or
 [`unwrap`]: v2::Upward::unwrap
+
+#### `ChainParameters`
+
+The [`ChainParameters`](v2::ChainParameters) type was revised from `enum` with multiple versions into a single `struct` with optional fields.
+Applications should no longer case on the version of the chain parameters, but can directly access the relevant parameters.
+Since parameters are added and removed across different protocol versions, each parameter is optional, even if it is present in all current protocol versions, in case it may be removed in a future protocol version.
+The prior functions on `ChainParameters` have been removed, and should be migrated as set out below.
+
+The `ChainParameters::common_update_keys()` function was removed.
+Instead `keys.level_2_keys : Option<Level2Keys>` should be used.
+The [`Level2Keys`](v2::Level2Keys) `struct` provides the level 2 keys and access structures.
+For signing chain updates, use [`construct_update_signer()`](v2::Level2Keys::construct_update_signer), for instance as:
+
+```rust,no_compile
+let params = client
+    .get_block_chain_parameters(&BlockIdentifier::LastFinal)
+    .await
+    .context("Could not obtain chain parameters")?;
+
+let keys = params
+    .response
+    .keys
+    .level_2_keys
+    .context("No level 2 keys in chain parameters.")?;
+
+let signer = keys
+    .construct_update_signer(
+        keys.micro_ccd_per_euro
+            .as_ref()
+            .context("Missing uCCD:EUR exchange rate update keys.")?,
+        kps,
+    )
+    .context("Invalid keys supplied.")?;
+
+let block_item: BlockItem<Payload> =
+    update::update(&signer, seq_number, effective_time, timeout, payload).into();
+```
+
+Constructing updates to the level 2 keys requires an [`AuthorizationsV1`](types::AuthorizationsV1) (or for old protocol versions, [`AuthorizationsV0`](types::AuthorizationsV0)) which can be obtained with `Level2Keys::try_into()`.
+
+The `ChainParameters::micro_ccd_per_energy()` and `ChainParameters::ccd_cost()` functions were removed.
+Instead, use [`energy_rate()`](v2::ChainParameters::energy_rate) to obtain an [`EnergyRate`](v2::EnergyRate), which encapsulates the [`micro_ccd_per_energy`](v2::EnergyRate::micro_ccd_per_energy) exchange rate.
+`EnergyRate` also provides [`ccd_cost()`](v2::EnergyRate::ccd_cost), which should be used in place of the former `ChainParameters::ccd_cost()`.
+
+Finally, the `ChainParameters::foundation_account()` getter function was removed, and should be replaced by directly accessing [`ChainParameters::foundation_account`](v2::ChainParameters::foundation_account).