Merge pull request #296 from Concordium/forward-compatible

Forward-compatible Rust SDK

Author: limemloh

CHANGELOG.md

@@ -1,10 +1,88 @@
 ## Unreleased changes
+
 - Removed authorization from `TokenClient` validation.
 - Added `validate_mint`, `validate_burn`, `validate_allow_list_update`, `validate_deny_list_update` methods to `TokenClient`.
 - Added `update_token_info` method to `TokenClient`.
 - Added `Validation` as a separate enum for `TokenClient` operations.
 - Remove use of `CborTokenHolder` wrapper.
 
+- Introduce `ProtocolVersionInt` newtype, wrapping the `u64` representation of the `ProtocolVersion`. This type is forward-compatible, meaning future protocol versions can be represented using this type.
+- BREAKING: Change type `ProtocolVersion` to  `ProtocolVersionInt` for field `protocol_version` in the types listed below. Now introducing new protocol versions in `ProtocolVersion` does not result in RPC parsing errors, and consumers of this library can write more applications that are more forward-compatible.
+  - `BlockInfo`
+  - `ConsensusInfo`
+  - `CommonRewardData`
+- Introduce `Upward<A, R = ()>` for representing types, which might get extended in a future version of the Concordium Node API and allows the consumer of this library to decide how to handle some unknown future data, like new transaction types and chain events.
+- Use the `WasmVersionInt` defined in `concordium-base` for the wasm version (smart contract version) to make it forward-compatible.
+- Changed the `Indexer` module to use a new `OnFinalizationError` and the new result types `OnFinalizationResult`/`TraverseResult` when traversing and processing blocks. The indexer's errors/results can now represent the `Unknown` types as part of adding forward-compatibility.
+- BREAKING: Change types related to gRPC API responses to wrap `Upward` for values which might be extended in a future version of the API of the Concordium Node.
+
+  The changes are for:
+  - Type `BlockItemSummary` field `details`.
+  - Method `BlockItemSummary::affected_addresses` return value.
+  - Method `BlockItemSummary::affected_contracts` return value.
+  - Type `AccountTransactionDetails` field `effects`.
+  - Method `AccountTransactionDetails::transaction_type` return value.
+  - Method `Client::get_block_special_events` response stream items.
+  - Associated type `Indexer::Data` for `indexer::BlockEventsIndexer`.
+  - Method `Client::get_block_items` response stream items.
+  - Method `Client::get_finalized_block_item` return type.
+  - Type `PendingUpdate` field `effect`.
+  - Type `ViewError::QueryFailed`.
+  - Type `ContractInitError::Failed`.
+  - Type `ContractUpdateError::Failed`.
+  - Type `ContractInitHandle::Failed`.
+  - Type `Cis2DryRunError::NodeRejected`.
+  - Type `Cis2QueryError::NodeRejected`.
+  - Type `Cis3PermitDryRunError::NodeRejected`.
+  - Type `Cis3SupportsPermitError::NodeRejected`.
+  - Type `Cis4QueryError::NodeRejected`.
+  - Method `Cis4QueryError::is_contract_error` return value.
+  - Type `Cis4TransactionError::NodeRejected`.
+  - Type `ModuleDeployError::Failed`.
+  - Type `DryRunModuleDeployError::Failed`.
+  - Type `RejectedTransaction` field `reason`.
+  - Method `ContractClient::view<P, A, E>` require `E` to implement `From<v2::Upward<RejectReason>>`.
+  - Method `ContractClient::view_raw<A, E>` require `E` to implement `From<v2::Upward<RejectReason>>`.
+  - Method `ContractClient::invoke_raw<E>` require `E` to implement `From<v2::Upward<RejectReason>>`.
+  - Method `ContractClient::dry_run_update<P, E>` require `E` to implement `From<v2::Upward<RejectReason>>`.
+  - Method `ContractClient::dry_run_update<P, E>` require `E` to implement `From<v2::Upward<RejectReason>>`.
+  - Method `BlockItemSummary::is_rejected_account_transaction` return value.
+  - Method `BlockItemSummaryDetails::is_rejected` return value.
+  - Method `AccountTransactionEffects::is_rejected` return value.
+  - Type `AccountTransactionEffects` field `reject_reason`.
+  - Type `InvokeContractResult` field `reason`.
+  - Type `UpdateInstruction` field `payload` now needs to be decoded on-demand, ensuring errors due to new variants for `UpdatePayload` can be handled separately and the rest of `UpdateInstruction` can still be read.
+  - Type `UpdateDetails` field `payload` is wrapped.
+  - Method `UpdateDetails::update_type` return type is wrapped.
+  - Type `AccountTransactionEffects::BakerConfigured` field `data` from `Vec<BakerEvent>` to `Vec<Upward<BakerEvent>>`.
+  - Type `AccountTransactionEffects::DelegationConfigured` field `data` from `Vec<DelegationEvent>` to `Vec<Upward<DelegationEvent>>`.
+  - Type `InvokeContractResult` field `events` of `Success` variant is now `Vec<Upward<ContractTraceElement>>`.
+  - Type `InvokeInstanceSuccess` field `events` is now `Vec<Upward<ContractTraceElement>>`.
+  - Method `ContractUpdateBuilder::events` return type from `&[ContractTraceElement]` to `&[Upward<ContractTraceElement>]`.
+  - Associated type `Indexer::Data` for `AffectedContractIndexer` now wraps the affected contract addresses in `Upward`.
+  - Type `AccountTransactionEffects` field `effects` of `ContractUpdateIssued` variant is now `Vec<Upward<ContractTraceElement>>`.
+  - Method `BlockItemSummary::contract_update_logs` now wraps the iterator items in `Upward`.
+  - Method `BlockItemSummaryDetails::contract_update_logs` now wraps the iterator items in `Upward`.
+  - Method `AccountTransactionEffects::affected_addresses` now wraps the return type in `Upward`.
+  - Method `ExecutionTree::affected_addresses` now wraps the return type in `Upward`.
+  - Method `ExecutionTree::events` now wraps the `Iterator::Item` in `Upward`.
+  - Method `ExecutionTree::execution_tree` return type was changed from `Option<ExecutionTree>` to `Option<Upward<ExecutionTree>>`
+  - Method `ExecutionTree::contract_update` now wraps return type in `Upward`.
+  - Function `execution_tree` parameter changed from `Vec<Upward<ContractTraceElement>>` to `Vec<ContractTraceElement>`.
+  - Type `ExecutionTreeV0` field `rest` change from `Vec<TraceV0>` to `Vec<Upward<TraceV0>>`.
+  - Type `ExecutionTreeV1` field `events` change from `Vec<TraceV1>` to `Vec<Upward<TraceV1>>`.
+  - Type `NodeDetails` variant `Node` is now wrapped in `Upward`.
+  - Type `NodeInfo` field `details` is now wrapped in `Upward`.
+  - Type `Peer` field `consensus_info` is now wrapped in `Upward`.
+  - Type `PeerConsensusInfo::Node` unnamed field is now wrapped in `Upward`.
+  - Type `AccountInfo` field `account_stake` changes from `Option<AccountStakingInfo>` to `Option<Upward<AccountStakingInfo>>`.
+  - Type `Cooldown` field `status` is now wrapped in `Upward`.
+  - Type `BakerEvent::BakerSetOpenStatus` field `open_status` is now wrapped in `Upward`.
+  - Type `AccountInfo` field `account_credentials` change from `BTreeMap<CredentialIndex,Versioned<AccountCredentialWithoutProofs<ArCurve, AttributeKind>>>` to `BTreeMap<CredentialIndex,Versioned<Upward<AccountCredentialWithoutProofs<ArCurve, AttributeKind>>>>`.
+  - Type `BakerPoolInfo` moved from `concordium-base` to the `rust-sdk`.
+  - 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`.
+
 ## 7.0.0
 
 Adds support for integrating with Concordium nodes running protocol version 9.

concordium-base

@@ -4,6 +4,7 @@
 use clap::AppSettings;
 use concordium_rust_sdk::{
     common::types::Amount,
+    types::AccountStakingInfo,
     v2::{self, BlockIdentifier},
 };
 use futures::{Future, TryStreamExt};
@@ -107,11 +108,13 @@ async fn main() -> anyhow::Result<()> {
             let mut client = closure_client.clone();
             async move {
                 let info = client.get_account_info(&acc.into(), &block).await?.response;
-                let additional_stake = info
-                    .account_stake
-                    .map_or(Amount::zero(), |baker_delegator| {
-                        baker_delegator.staked_amount()
-                    });
+                let additional_stake =
+                    info.account_stake
+                        .map_or(Amount::zero(), |baker_delegator| {
+                            baker_delegator
+                                .as_ref()
+                                .map_or(Amount::zero(), AccountStakingInfo::staked_amount)
+                        });
                 let additional_liquid_amount = info.account_amount
                     - std::cmp::max(additional_stake, info.account_release_schedule.total);
                 Ok::<_, anyhow::Error>((

examples/balance-summary.rs

@@ -89,6 +89,9 @@ async fn main() -> anyhow::Result<()> {
             .await?
             .response
             .try_fold(0, |count, ev| async move {
+                let v2::Upward::Known(ev) = ev else {
+                    return Ok(count);
+                };
                 let add = match ev {
                     SpecialTransactionOutcome::PaydayFoundationReward { .. } => 1u32,
                     SpecialTransactionOutcome::PaydayAccountReward { .. } => 1u32,

examples/block-stats.rs

@@ -1,7 +1,9 @@
 //! Find when an account was created on the chain.
 //! That is, the block in which the account creation transaction is committed.
 use clap::AppSettings;
-use concordium_rust_sdk::{id::types::AccountAddress, types::BlockItemSummaryDetails, v2};
+use concordium_rust_sdk::{
+    id::types::AccountAddress, types::BlockItemSummaryDetails, v2, v2::upward::Upward,
+};
 use futures::stream::StreamExt;
 use structopt::StructOpt;
 
@@ -31,12 +33,12 @@ async fn main() -> anyhow::Result<()> {
         println!("Account not found.");
         return Ok(());
     };
-    println!("Account created in block {}.", bh);
+    println!("Account created in block {bh}.");
     let bi = client.get_block_info(&bh).await?.response;
     println!("Timestamp of this block {}.", bi.block_slot_time);
     let mut block_summary = client.get_block_transaction_events(&bh).await?.response;
     while let Some(summary) = block_summary.next().await.transpose()? {
-        if let BlockItemSummaryDetails::AccountCreation(ac) = &summary.details {
+        if let Upward::Known(BlockItemSummaryDetails::AccountCreation(ac)) = &summary.details {
             if ac.address == app.account {
                 println!("Created by transaction hash {}", summary.hash);
                 break;

examples/find-account.rs

@@ -7,7 +7,7 @@ use concordium_rust_sdk::{
     id,
     id::types::AccountAddress,
     types::{AccountStakingInfo, CredentialType},
-    v2::{self, BlockIdentifier},
+    v2::{self, upward::UnknownDataError, BlockIdentifier},
 };
 use futures::TryStreamExt;
 use serde::Serializer;
@@ -111,15 +111,14 @@ async fn main() -> anyhow::Result<()> {
         for res in futures::future::join_all(handles).await {
             let (acc, info) = res??;
             let is_baker = if let Some(account_stake) = info.account_stake {
-                match account_stake {
+                match account_stake.known_or_err()? {
                     AccountStakingInfo::Baker { staked_amount, .. } => {
                         num_bakers += 1;
                         total_staked_amount += staked_amount;
                         true
                     }
                     AccountStakingInfo::Delegated { staked_amount, .. } => {
                         total_delegated_amount += staked_amount;
-
                         false
                     }
                 }
@@ -129,18 +128,18 @@ async fn main() -> anyhow::Result<()> {
 
             total_amount += info.account_amount;
 
-            let acc_type =
-                info.account_credentials
-                    .get(&0.into())
-                    .map_or(CredentialType::Normal, |cdi| match cdi.value {
-                        id::types::AccountCredentialWithoutProofs::Initial { .. } => {
-                            num_initial += 1;
-                            CredentialType::Initial
-                        }
-                        id::types::AccountCredentialWithoutProofs::Normal { .. } => {
-                            CredentialType::Normal
-                        }
-                    });
+            let acc_type = info.account_credentials.get(&0.into()).map_or(
+                Ok::<_, UnknownDataError>(CredentialType::Normal),
+                |cdi| match cdi.value.as_ref().known_or_err()? {
+                    id::types::AccountCredentialWithoutProofs::Initial { .. } => {
+                        num_initial += 1;
+                        Ok(CredentialType::Initial)
+                    }
+                    id::types::AccountCredentialWithoutProofs::Normal { .. } => {
+                        Ok(CredentialType::Normal)
+                    }
+                },
+            )?;
 
             let row = Row {
                 address: acc,

examples/list-account-balances.rs

@@ -3,7 +3,7 @@ use clap::AppSettings;
 use concordium_rust_sdk::{
     indexer::{TransactionIndexer, TraverseConfig},
     types::{AbsoluteBlockHeight, BlockItemSummary, BlockItemSummaryDetails, CredentialType},
-    v2,
+    v2::{self, upward::Upward},
 };
 use structopt::StructOpt;
 
@@ -60,6 +60,9 @@ async fn main() -> anyhow::Result<()> {
             }
         }
         for BlockItemSummary { details, .. } in summaries {
+            let Upward::Known(details) = details else {
+                continue;
+            };
             match details {
                 BlockItemSummaryDetails::AccountTransaction(_) => {}
                 BlockItemSummaryDetails::AccountCreation(x) => {

examples/list-account-creations.rs

@@ -8,7 +8,7 @@ use concordium_rust_sdk::{
     types::{
         AbsoluteBlockHeight, AccountTransactionEffects, BlockItemSummaryDetails, TransactionType,
     },
-    v2,
+    v2::{self, upward::Upward},
 };
 use std::collections::HashSet;
 use structopt::StructOpt;
@@ -82,18 +82,24 @@ async fn main() -> anyhow::Result<()> {
             }
         }
         for bisummary in summary {
-            if let BlockItemSummaryDetails::AccountTransaction(at) = &bisummary.details {
-                if types.is_empty() || at.transaction_type().is_some_and(|tt| types.contains(&tt)) {
-                    let is_success = !matches!(&at.effects, AccountTransactionEffects::None { .. });
-                    let type_string = at
-                        .transaction_type()
-                        .map_or_else(|| "N/A".into(), |tt| tt.to_string());
-                    println!(
-                        "{}, {}, {}, {}, {}",
-                        bi.block_slot_time, bi.block_hash, bisummary.hash, is_success, type_string
-                    )
-                }
+            let Upward::Known(BlockItemSummaryDetails::AccountTransaction(at)) = &bisummary.details
+            else {
+                continue;
+            };
+            let Upward::Known(effects) = &at.effects else {
+                continue;
+            };
+            let Some(transaction_type) = effects.transaction_type() else {
+                continue;
+            };
+            if !types.is_empty() && !types.contains(&transaction_type) {
+                continue;
             }
+            let is_success = !matches!(effects, AccountTransactionEffects::None { .. });
+            println!(
+                "{}, {}, {}, {}, {}",
+                bi.block_slot_time, bi.block_hash, bisummary.hash, is_success, transaction_type
+            );
         }
     }
     Ok(())

examples/list-all-transactions.rs

@@ -1,7 +1,10 @@
 //! List initial accounts created between two given timestamps.
 use anyhow::Context;
 use clap::AppSettings;
-use concordium_rust_sdk::{types::AccountInfo, v2};
+use concordium_rust_sdk::{
+    types::AccountInfo,
+    v2::{self, upward},
+};
 use futures::TryStreamExt;
 use std::{collections::BTreeSet, io::Write, path::PathBuf};
 use structopt::StructOpt;
@@ -122,17 +125,18 @@ async fn main() -> anyhow::Result<()> {
         }
         for ainfo in futures::future::join_all(handles).await {
             let ainfo: AccountInfo = ainfo?.response;
-            let is_initial = ainfo
-                .account_credentials
-                .get(&0.into())
-                .is_some_and(|cdi| match &cdi.value {
+            let is_initial = if let Some(acred) = ainfo.account_credentials.get(&0.into()) {
+                match acred.value.as_ref().known_or_err()? {
                     concordium_rust_sdk::id::types::AccountCredentialWithoutProofs::Initial {
                         ..
-                    } => true,
+                    } => Ok::<_, upward::UnknownDataError>(true),
                     concordium_rust_sdk::id::types::AccountCredentialWithoutProofs::Normal {
                         ..
-                    } => false,
-                });
+                    } => Ok(false),
+                }
+            } else {
+                Ok(false)
+            }?;
             if is_initial && !start_block_accounts.contains(&ainfo.account_address) {
                 writeln!(&mut out, "{}", ainfo.account_address)?;
             }

examples/list-initial-accounts.rs

@@ -320,7 +320,7 @@ async fn send_and_wait(
     pv: ProtocolVersion,
 ) -> anyhow::Result<bool> {
     let ci = client.get_consensus_info().await?;
-    if ci.protocol_version == pv {
+    if ci.protocol_version == pv.into() {
         let submission_id = client
             .send_block_item(block_item)
             .await
@@ -341,7 +341,7 @@ async fn send_and_wait(
         loop {
             interval.tick().await;
             let ci = client.get_consensus_info().await?;
-            if ci.protocol_version > pv {
+            if ci.protocol_version > pv.into() {
                 break;
             }
         }