Crate concordium_rust_sdk

Expand description

A library for interacting with the Concordium blockchain. The library is structured around multiple modules.

v2 contains the main entrypoint to the library. In particular it contains the Client struct which maintains a connection to the node, and supports queries and node manipulation. This client uses gRPC API version 2 of the Concordium node.
constants contains a number of constants and type definitions that are relevant when using the chain.
types contains most type definitions to model responses as well as types defining transactions. The latter are in a submodule types::transactions.

In addition to these, the library re-exports a number of core crates that implement the core cryptographic protocols of the Concordium blockchain.

id is the implementation of most of the protocols in the identity layer
common has some common type definitions, as well as traits and helpers for binary serialization
encrypted_transfers implements structures and zero knowledge proofs related to encrypted transfers. Note that this functionality has been deprecated in protocol version 7.
eddsa_ed25519 is a re-export of the signature scheme used for blocks and accounts on the Concordium blockchain.
aggregate_sig is a re-export of the BLS signature scheme, used by the validators. This is useful for constructing baker transactions.
ecvrf is a re-export of the implementation of the VRF function used to determine lottery winners in consensus.
concordium_base is a re-export as base. The main purpose of this is to enable the use of concordium_base_derive serialization macros.

§Migration guide: 7 to 8

The SDK major version 8 introduces a lot of minor breaking changes, all with common goal of improving forward-compatibility with Concordium Node API versions.

§Motivation

Up until this release, certain extensions to the Concordium Node API have resulted in the SDK failing to parse query responses with errors like ‘Unknown protocol version: x’ or ‘missing field in response’, resulting in the entire query to fail. This is the case even for the larger queries where the unknown/missing information is only a small part of the response preventing the application to access the entire response. Usually the fix was to update the SDK to a newer version which know how to parse the new information, but this imposes work for the ecosystem for every change in the API (usually part of protocol version updates).

This major release introduces Upward<A> a type wrapper representing information which might be extended in future version of the API, providing a variant representing unknown information such that queries can provide partial information. It makes potentially extended information explicit in the types and allows each application to decide how to handle the case of new unknown data on a case by case basis.

§Handling `Upward`

Several types and fields in the SDK are now wrapped in Upward and the wrapper provides several methods to ease the migration depending on the desired behavior of the application. For some situations unknown information should cause an error, where in other situations it is safe to ignore, and maybe logging warnings to be handled in a future iteration of the application.

if let Upward::Known(details) = block_item_summary.details {
    // Data is familiar so we handle details as usual.
} else {
    // Data is unknown to this SDK version, so we fallback to some other behavior.
}

To produce an error in the case of unknown data use known_or_err, converting Upward<A> into Result<A, UnknownDataError>.

let details = block_item_summary.details.known_or_err()?;

Alternatively known_or or similarly named variants can be used for directly mapping the unknown data case to an error.

let details = block_item_summary.details.known_or(MyError::UnknownData)?;

For the quick proof of concept application the value can be unwrapped using unwrap which triggers a panic when encountering unknown information, hence not recommended in production code.

§`ChainParameters`

The v2::ChainParameters enum has been replaced by types::chain_parameters::ChainParameters, which is 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 struct provides the level 2 keys and access structures. For signing chain updates, use construct_update_signer().

The ChainParameters::micro_ccd_per_energy() and ChainParameters::ccd_cost() functions were removed. Instead, use energy_rate() to obtain an EnergyRate, which encapsulates the micro_ccd_per_energy exchange rate. EnergyRate also provides 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.

Re-exports§

pub use concordium_base as base;

Modules§

aggregate_sig: Implementation of aggregate signatures specified in https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-bls-signature-04
cis0: This module contains types and functions for interacting with smart contracts following the CIS-0 specification.
cis2: This module contains types and functions for interacting with smart contracts following the CIS-2 specification.
cis3: This module contains types and functions for interacting with smart contracts following the CIS-3 specification.
cis4: This module contains types and functions for interacting with smart contracts following the CIS-4 specification.
common: Common types and operations used throughout the Concordium chain development.
constants: Various constants and types that apply to the chain.
contract_client: This module contains a generic client that provides conveniences for interacting with any smart contract instance, as well as for creating new ones.
ecvrf: Implementation of the verifiable random function as specified in https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-vrf-09.
eddsa_ed25519: A few helpers around the dalek ed25519 signature scheme.
encrypted_transfers: This library provides the API needed by the chain, the wallet, and the supporting tools to deal with encrypted amounts.
endpoints: Wrapper for the node’s GRPC API. The return values are parsed and wrapped in structured values.
id: This module and its submodules implement the Concordium identity layer, providing the core functionality for all entities involved (users, identity providers, and the chain).
indexer: Support for writing indexers using the Rust SDK.
protocol_level_tokens: Types and functions for working with Protocol Level Tokens (PLT).
signatures: Functionality for generating, and verifying account signatures.
smart_contracts: Functions and types related to smart contracts.
types: Type definitions used throughout the rest of the SDK.
v2: This module exposes Client which is a wrapper around the generated gRPC rust client, providing a more ergonomic interface than the generated client. See Client for documentation of how to use.
web3id: Functionality for retrieving, verifying, and registering web3id credentials.