FAQ — Concordium documentation

What are Solana programs called on Concordium?

Programs are called smart contracts on Concordium. See the comparison here.

What smart contract language is used on Concordium?

Smart contracts are deployed as Wasm modules on the Concordium chain. Like Solana, Concordium uses Rust to write and compile smart conracts. Rust currently has the best support to write and compile your smart contract into a Wasm module that then can be deployed to the Concordium chain.

How can I start with the Rust smart contract language?

Rust is a fast and memory-efficient language that is a popular smart contract language among different blockchain projects. There is plenty of literature to get started with Rust such as the Rust language book. You can find examples of smart contracts in the Concordium Rust smart contract repo.

Where can I find example smart contracts?

You can find examples of smart contracts in the Concordium Rust smart contract repo.

Where can I find a smart contract reference library similar to the GitHub repo from Solana Program Library?

You can find examples and standard implementations in the Concordium Rust smart contract repo.

Note

These contracts are not meant for production. They are used to illustrate how to use the standard library and the tooling Concordium provides. There is no claim that the logic of the contract is reasonable or safe.

Should I use V0 or V1 smart contracts?

Version 1 smart contracts have many improvements and features added compared to Version 0 smart contracts. Hence, V1 smart contracts are recommended over V0 smart contracts if you start a new project. Mainnet continues supporting V0 smart contracts due to backward compatibility.

How can I write a smart contract?

You can follow the chapter writing a smart contract in the piggy bank tutorial.

How can I test a smart contract?

You can follow the chapter testing a smart contract in the piggy bank tutorial.

Is there something similar to Solana’s Anchor framework for Concordium?

Yes. The Concordium standard library crate concordium-std provides a high-level interface for writing smart contracts in Rust. It includes convenient ways of working with the contract state, provides macros for exposing Rust functions as entrypoints, handles serialization, provides testing infrastructure, etc. Together with cargo-concordium it can be used to develop, test and build smart contracts.

You can follow the chapter writing a smart contract in the piggy bank tutorial to get started with using concordium-std.

How can I update account data?

Smart contract code cannot write data to user accounts or other smart contract state. Smart contracts manipulate their own state and call entrypoints of other contracts. See Onboarding for Solana developers for the details.

Is there something similar to native programs in Concordium?

No. Security-critical functionalities like cryptographic primitives, smart contract state management, etc. are implemented as Wasm host functions. The list of supported host functions is available in Contract host functions.

Separating these functionalities to host functions instead of having them as special smart contracts helps to rule out some vulnerabilities related to substituting native program addresses by users.

Can I build tests that print a table of content structure (a layered output similar to mocha and chai tests)?

Yes. You can use a similar pattern as shown below:

#[cfg(test)]
mod tests {
    mod func_a {
        #[test]
        fn correct_params_correct_result(){...}
        #[test]
        fn invalid_params_invalid_result(){...}
    }
}

The test cases are printed as follows:

running 2 tests
test tests::func_a::correct_params_correct_result ... ok
test tests::func_a::invalid_params_invalid_result ... ok

How are program addresses represented on Concordium?

In terms of naming, Concordium uses contract and account to refer to a similar Solana’s executable account (programs) and non-executable account, respectively. Note, however that the correspondense is not precise. See the overview of differences for more details.

The word address refers to either an account address or a contract address on Concordium. Contract addresses on Concordium are represented by an index and a subindex as seen below. When invoking the init function, a new smart contract instance is deployed and assigned the next index number in sequential order. The subindex is currently not in use and is always 0. There are plans to give the subindex meaning in the future.

You cannot send CCD to a contract address (or account address) before they have been deployed/initialized on the Concordium chain.

ContractAddress {
    index:    1234,
    subindex: 0,
};

How are wallet addresses represented on Concordium?

In terms of naming, Concordium uses contract and account to refer to a similar Solana’s executable account (programs) and non-executable account, respectively. Note, however that the correspondense is not precise. See the overview of differences for more details.

The word address refers to either an account address or a contract address on Concordium. Accounts on the chain are identified via an account address, which is a 32-byte sequence. The address is usually displayed in Base58Check encoding with version byte 1. An example of such an address is 3ZFGxLtnUUSJGW2WqjMh1DDjxyq5rnytCwkSqxFTpsWSFdQnNn.

On Concordium, accounts are deployed on-chain and their corresponding account address only exists from that point on. You cannot send CCD to an account address (or a smart contract address) before they have been deployed/initialized on the Concordium chain. When a smart contract tries to interact with an address that has not been deployed/initialized yet, the interaction fails.

Can I distinguish between contract and account addresses?

Yes. You can distinguish between the different types of addresses in smart contracts on the Concordium chain. Addresses are represented as an enum with two variants.

pub enum Address {
    Account(AccountAddress),
    Contract(ContractAddress),
}

Rust has a pattern matching that determines at runtime which variant of the enum Address is applicable, and then the appropriate code is executed. You can read more about pattern matching in the Rust language book.

For example, the below code prints out a different message depending on if the sender that invoked this smart contract function is a contract or an account.

match ctx.sender() {
    Address::Contract(contract_address) => { println!("This contract invoked the function: {:?}", contract_address) },
    Address::Account(account_address) => { println!("This account invoked the function: {:?}", account_address) },
};

Add the above pattern matching snippet to one of your Rust smart contract functions and write a test case that invokes that function. You can see the printout of the snippet by running the tests with the below command.

$cargo test -- --nocapture

How do I get the transaction sender address on Concordium?

The ctx.invoker() variable refers to the original account address (no contract address) that started the transaction while ctx.sender() refers to the immediate address (it could be an account or another contract address) that invokes the function entry point. A contract cannot start a transaction and that is why ctx.invoker() never returns a contract address.

How do I get the balance of the smart contract within the Rust code?

host.self_balance() returns the current balance of the smart contract. Upon entry to a smart contract function, the balance that is returned is the sum of the balance of the contract at the time of the invocation and the amount that is being transferred to the contract. Additional documentation can be found in the self_balance description of the concordium-std crate.

How do I get the address of the smart contract within the Rust code?

ctx.self_address() returns the address of the smart contract. Additional documentation can be found in the self_address description of the concordium standard crate.

Can I print values from the smart contract code or test cases?

Yes. You can use

println!("Printing output of f: {}, and g: {}", f(1,2,3), g("hi"));

or

println!("Printing debug value: {:?}", 12345);

for printing to stdout and

eprintln!("Printing output of f: {}, and g: {}", f(1,2,3), g("hi"));

or

eprintln!("Printing debug value: {:?}", 12345);

for printing to stderr.

Add one of the above lines of code to a Rust smart contract function or one of your test cases (Write a test case that invokes your Rust smart contract function if the printing statement is in the smart contract code). You can see the printout by running the tests with the below command.

$cargo test -- --nocapture

My transaction is rejected and I get an error code number. How can I interpret smart contract errors?

Error codes come from the concordium-std crate or are thrown by the smart contract itself.

Concordium-std crate errors

An example of a concordium-std crate error is shown below:

Error: Updating contract instance failed:
'smash' in 'PiggyBank' at {"index":12345,"subindex":0} failed with code -2147483636.

You can find the meaning of common error codes in this list. This error was thrown by the concordium-std crate. The error codes start from i32::MIN and go upwards. -2147483636 corresponds to NotPayableError. In contrast, error types of smart contracts start from -1 and go downwards.

Smart contract errors

An example of a smart contract error is shown below:

Error: Updating contract instance failed:
'smash' in 'PiggyBank' at {"index":12345,"subindex":0} failed with code -1.

You can find the meaning of the piggy bank error codes in this section. This error was thrown by the smart contract. The error codes start from -1 and go downwards. -1 is the first error code and corresponds to NotOwner. In contrast, errors from the concordium-std crate start from i32::MIN and go upwards.

Is there a smart contract code linter?

Yes. You can use the fmt and the cargo clippy linter tools as described in the README.

Are tests executed in parallel or sequentially?

Tests run in parallel by default with the following two commands

$cargo concordium test

$cargo test

You can use the below command for consecutive execution of the tests.

$cargo test -- --test-threads=1

How can I provide the input parameters as a JSON object and get the output parameters in a human-readable format when using the concordium-client? What is a smart contract schema?

A smart contract schema is a description of how to represent bytes in a more structured representation. It is used by external tools (such as the concordium-client) when displaying the return value of a receive function and for specifying the input parameters to a receive function using a structured representation, such as JSON.

The smart contract function needs to define a parameter and a return_value so that a schema can be generated for the input parameters and the output parameters, respectively.

#[receive(
    contract = "CIS2-wCCD",
    name = "balanceOf",
    parameter = "ContractBalanceOfQueryParams",
    return_value = "ContractBalanceOfQueryResponse"
)]
fn contract_balance_of(
    ctx: &ReceiveContext,
    host: &Host<StateImplementation>,
) -> ContractResult<ContractBalanceOfQueryResponse> { ... }

The schema can either be embedded into the smart contract or generated as a separate file.

Option 1 (Schema embedded into a smart contract)

$cargo concordium build --schema-embed

The shorter version of the above command is as follows:

$cargo concordium build -e

../../_images/onboarding_ethereum_developers_51.png

Option 2 (Schema as a separate file)

$cargo concordium build --schema-out ./schema.bin

The shorter version of the above command is as follows:

$cargo concordium build -s ./schema.bin

../../_images/onboarding_ethereum_developers_61.png

If the schema is a separate file, it needs to be provided with the --schema flag to the concordium-client.

When using the concordium-client to interact with smart contracts the input and output parameters can be either in human-readable format (with a schema) or in raw bytes (binary format).

Example 1 (Schema is provided as a separate file but the provided file with the flag `parameter-json` has a wrong JSON object)

If your JSON object that was provided with the --parameter-json flag is in the wrong format, you get an error message with additional information on what JSON object format is expected. This information can help you to create the correct JSON object.

../../_images/onboarding_ethereum_developers_71.png

Example 2 (Schema is embedded into the smart contract and the `parameter-json` flag provides the input parameters as a JSON object; the return value is displayed in a human-readable format due to the provided additional information in the schema)

../../_images/onboarding_ethereum_developers_81.png

Example 3 (Schema is provided as a separate file and the `parameter-json` flag provides the input parameters as a JSON object; the return value is displayed in a human-readable format due to the provided additional information in the schema)

../../_images/onboarding_ethereum_developers_91.png

Example 4 (No schema is provided and the `parameter-binary` flag provides the input parameters as a raw bytes string; the return value is displayed in raw bytes because no additional information is available on how to represent the bytes in a human-readable format)

../../_images/onboarding_ethereum_developers_101.png

How can I create the parameter data if I want to use binary input instead of a JSON input?

When using the concordium-client to interact with smart contracts the input and output parameters can be either in human-readable format (with a schema) or in raw bytes (binary format). If you want to use the binary format, the below command shows that a myInputParameters.bin file is required.

$concordium-client contract update <ContractIndex> --entrypoint <ContractEntryPoint> --parameter-binary myInputParameters.bin --sender <Account> --energy 12345678

You can create such a myInputParameters.bin file by adding the below lines to your test cases replacing the ExampleParams struct with your input parameter struct for that function.

let parameter = ExampleParams {
    example_key1: value1,
    example_key1: value2,
}
let parameter_bytes = to_bytes(&parameter);
std::fs::write("myInputParameters.bin", &parameter_bytes).expect("Failed to write parameter file");

When running the tests with the below command the myInputParameters.bin file is created in the current folder.

$cargo test

FAQ#

Concordium smart contracts#

Events#

Standards#

Deploying and initializing smart contracts#

Concordium tools#

Miscellaneous#