Crate concordium_contracts_common

This library provides the core API that can be used to write smart contracts for the Concordium blockchain in the Rust programming language. It aims to provide safe wrappers around the core primitives exposed by the chain and accessible to smart contracts.

By default the library will be linked with the std crate, the rust standard library, however to minimize code size this library supports toggling compilation with the #![no_std] attribute via the feature std which is enabled by default.

To use this library without the std feature you have to disable it, which can be done, for example, as follows.

[dependencies.concordium-contracts-common]
default-features = false

In your project's Cargo.toml file.

Wasm32

This crate supports both compilation to x86 native code, as well as to the wasm32-unknown-unknown target. When there is a conflict, the preference should always be to make the wasm32-unknown-unknown the more efficient one.

concordium-std

The functionality in this library is re-exported via the concordium-std crate, which is intended as the entry-point for development of smart contracts in Rust. concordium-std adds a number of helper macros and traits on top of the basic functionality available here.

Features

This library supports two features, std and derive-serde. The former one is enabled by default, but the latter is disabled.

The derive-serde feature is intended to be used by off-chain tools to make it easier to test smart contracts, as well as to inter-operate with them once they are deployed. It can also be used in unit tests, since enabling this feature exposes additional trait implementations on the defined types.

The reason these trait implementations are not enabled by default is that they have non-trivial dependencies, which tends to increase compilation times, as well as code size, if used accidentally.

Traits

The main traits defined in this crate deal with binary serialization. The general principles behind serialization is to consistently use little-endian encoding. The native endianess of Wasm32 (when, e.g., reading from linear memory) is little endian, thus having serialization in little endian means as little overhead as possible.

The two core traits are Serial and Deserial. The rest are helper traits there for convenience.

In particular, the Get is noteworthy. It makes it possible to omit writing the type explicitly, if it is already clear from the context, allowing us to write, e.g.,

   let n = source.get()?;

instead of

   let n = u8::deserial(source)?;

The Get trait has a generic implementation in terms of Deserial, so only the latter should be implemented for new types.

Modules

attributes	Currently defined attributes possible in a policy.
schema	Types related to contract schemas. These are optional annotations in modules that allow the users of smart contracts to interact with them in a way that is better than constructing raw bytes as parameters.

Structs

AccountAddress	Address of an account, as raw bytes.
Amount	The type of amounts on the chain
AttributeTag	Tag of an attribute. See the module attributes for the currently supported attributes.
ChainMetadata	Chain metadata accessible to both receive and init methods.
ContractAddress	Address of a contract.
Cursor	Add offset tracking inside a data structure.
Duration	Duration of time in milliseconds.
ParseError	Zero-sized type to represent an error when reading bytes and deserializing.
Policy	Policy on the credential of the account.
Timestamp	Timestamp represented as milliseconds since unix epoch.

Enums

Address	Either an address of an account, or contract.
AmountParseError	An error indicating why parsing of an amount failed. Since amount parsing is typically a user-facing activity this is fairly precise, so we can notify the user why we failed, and what they can do to fix it.
ParseDurationError
SeekFrom	This is the equivalent to the SeekFrom type from the rust standard library, but reproduced here to avoid dependency on std::io.

Constants

ACCOUNT_ADDRESS_SIZE

Size of an account address when serialized in binary. NB: This is different from the Base58 representation.

Traits

Deserial	The Deserial trait provides a means of reading structures from byte-sinks (Read).
Get	A more convenient wrapper around Deserial that makes it easier to write deserialization code. It has a blanked implementation for any read and serialize pair. The key idea is that the type to deserialize is inferred from the context, enabling one to write, for example,
Read	The Read trait provides a means of reading from byte streams.
Seek	The Seek trait provides a cursor which can be moved within a stream of bytes. This is essentially a copy of std::io::Seek, but avoiding its dependency on std::io::Error, and the associated code size increase.
Serial	The Serial trait provides a means of writing structures into byte-sinks (Write).
Serialize	The Serialize trait provides a means of writing structures into byte-sinks (Write) or reading structures from byte sources (Read).
Write	The Write trait provides functionality for writing to byte streams.

Functions

deserial_map_no_length	Read a BTreeMap as a list of key-value pairs given some length. NB: This ensures there are no duplicates, hence the specialized type. Moreover this will only succeed if keys are listed in order.
deserial_map_no_length_no_order_check	Read a BTreeMap as a list of key-value pairs given some length. Slightly faster version of deserial_map_no_length as it is skipping the order checking
deserial_set_no_length	Read a BTreeSet as an list of keys, given some length. NB: This ensures there are no duplicates, hence the specialized type. Moreover this will only succeed if keys are listed in order.
deserial_set_no_length_no_order_check	Read a BTreeSet as an list of key-value pairs given some length. Slightly faster version of deserial_set_no_length as it is skipping the order checking. The only check that is made to the set is that there are no duplicates.
deserial_vector_no_length	Read a vector given a length.
from_bytes	Dual to to_bytes.
serial_map_no_length	Write a Map as a list of key-value pairs ordered by the key, without the length information.
serial_set_no_length	Write a BTreeSet as an ascending list of keys, without the length information.
serial_vector_no_length	Write a slice of elements, without including length information. This is intended to be used either when the length is statically known, or when the length is serialized independently as part of a bigger structure.
to_bytes	Serialize the given value to a freshly allocated vector of bytes using the provided Serial instance.

Type Definitions

AttributeValue	A borrowed attribute value. The slice will have at most 31 bytes. The meaning of the bytes is dependent on the type of the attribute.
BlockHeight	Height of the block. Height of the genesis block is 0, and otherwise it is always the case that a block has height one more than its parent.
FinalizedHeight	Finalized height. In the context of chain metadata this is the height of the block which is explicitly recorded as the last finalized block in the block under consideration.
IdentityProvider	Index of the identity provider on the chain. An identity provider with the given index will not be replaced, so this is a stable identifier.
OwnedAttributeValue	An owned counterpart of AttributeValue, more convenient for testing.
OwnedPolicy	A policy with a vector of attributes, fully allocated and owned. This is in contrast to a policy which is lazily read from a read source. The latter is useful for efficiency, this type is more useful for testing since the values are easier to construct.
ParseResult	A type alias used to indicate that the value is a result of parsing from binary via the Serial instance.
SlotNumber	Genesis block has slot number 0, and otherwise it is always the case that a parent of a block has a slot number strictly less than the block itself. However in contrast to BlockHeight, slot numbers are not strictly sequential, there will be gaps.
SlotTime	Time at the beginning of the current slot, in miliseconds since unix epoch.