concordium-base

This repository contains core Rust and Haskell libraries used by various components of the Concordium blockchain, as well as some tools used for testing and development.

Haskell modules

haskell-src

Contains the Haskell package concordium-base which contains

foreign imports of rust libraries that are needed in the rest of the project
basic type definitions, e.g., account address, block hash, with serializations and basic functionality. These are used consistently throughout the rest of the project.

haskell-tests

Unit tests of the concordium-base Haskell library.

haskell-bench

Benchmarks of some functions that are of interest. This is ad-hoc and functions are added there by need.

generate-update-keys

Is a utility for generating authorization keys for different kinds of updates. It is used for generating such keys for internal testing. The key generation it supports is not very secure.

genesis

Is a tool that takes all the parameters, accounts, and other data that goes into a genesis block, and combines them into a single file that is needed to start the node.

testdata

Contains auxiliary data files used by Haskell tests.

Rust modules

rust-src

Contains

definitions of some core datatypes, such as account addresses, hashes, as well as serialization and basic functionality.
implementations of all custom cryptographic protocols used by Concordium, e.g., custom sigma proofs, implementation of bulletproofs, and top-level functionality for anonymity revokers, identity providers, and the account holders.

This is the wrapper around the functionality in the id library that exports the functionality needed by the identity provider in the format that they need it. The library is currently tailored to be used from NodeJS.

idiss is an acronym, standing for "identity issuer".

identity-provider-service

Is a prototype implementation of a pure Rust identity provider we use for testing.

mobile_wallet

This contains thin wrappers around the wallet library that exposes the necessary functions in a format suitable for use from Android and iOS platforms, respectively.

rust-bins

Contains various utilities that are used for testing and prototyping. From key generation to generation to tools for analyzing the chain.

See documentation for

id-client (identity layer interactions for testing)
keygen tool key generation for identity providers and anonymity revokers
keygen genesis (this uses a different key generation procedure that allows key recovery from a seed phrase)

Build requirements.

In order to build the components in this repository you need

The cargo tool for building the Rust components. The currently supported version is 1.82. Others may work, but we do not regularly test with them. The easiest way to install it is via the rustup tool.
The Haskell Stack tool for building the Haskell components.
protoc >= 3.15 installed and on PATH.

Some Rust components may require additional dependencies, see mobile_wallet/README.md and idiss/README.md for details.

Contributing

Haskell workflow

We typically use stack to build, run, and test the code. In order to build the haskell libraries the rust dependencies must be pre-build, which is done automatically by the cabal setup script.

Code should be formatted using fourmolu version 0.13.1.0 and using the config fourmolu.yaml found in the project root. The CI is setup to ensure the code follows this style.

To check the formatting locally run the following command from the project root:

On unix-like systems:

$ fourmolu --mode check $(git ls-files '*.hs')

To format run the following command from the project root:

On unix-like systems:

$ fourmolu --mode inplace $(git ls-files '*.hs')

Lines should strive to be at most 100 characters, naming and code style should follow the scheme that already exists.

We do not use any linting tool on the CI. Running hlint might uncover common issues.

Rust workflow

We use stable version of rust, 1.82, to compile the code. The minimal supported rust version is 1.73.

The CI is configured to check two things

the clippy tool is run to check for common mistakes and issues. We try to have no clippy warnings. Sometimes what clippy thinks is not reasonable is necessary, in which case you should explicitly disable the warning on that site (a function or module), such as #[allow(clippy::too_many_arguments)], but that is a method of last resort. Try to resolve the issue in a different way first.
the rust fmt tool is run to check the formatting. Unfortunately the stable version of the tool is quite outdated, so we use a nightly version, which is updated a few times a year. Thus in order for the CI to pass you will need to install the relevant nightly version, see see the rustfmt job in the file .github/workflows/build-test-sources.yaml, look for nightly-...).

Overall workflow

The typical workflow should be the following.

make changes, commit and push on a separate branch
make a merge request to merge your branch into master. Assign somebody else with knowledge of the code to review the changes before they are merged.

Licenses

Most of the sources in this repository are licensed under MPL-2.0. Some Rust packages are licensed under APACHE-2.0. The license field in Cargo.toml package indicates which license the sources in that package are under.

Concordium/concordium-base