cargo-concordium is a tool for building and testing smart contracts on the Concordium blockchain.
See developer documentation for guides on how to use the tool in detail.
This crate is a binary, and its versioning applies to the command-line API. There are no guarantees about internal crate API.
To start a new Concordium smart contract project, run the command:
cargo concordium init
This command will generate a new project from the templates in the template folder.
cargo concordium build -e --out contract.wasm.v1
will build a contract, embed the schema, and output the artifact to
contract.wasm.v1. This can be deployed to the chain or tested locally.
Since a contract running on the chain will typically not be able to recover from
panics, and error traces are not reported, it is useful not to bloat code size
with them. Setting panic=abort will make it so that the compiler will generate
simple Wasm traps on any panic that occurs. This option can be specified
either in .cargo/config or in the Cargo.toml file as
``` [profile.release]
panic = "abort" ```
The latter will only set this option in release builds, for debug builds use
``` [profile.dev]
panic = "abort" ``` instead.
Note that currently this is the default already for wasm32-unknown-unknown target.
An additional option that might be useful to minimize code size at the cost of some performance in some cases is ``` [profile.release]
rustc to optimize for small code size.opt-level = "s"
``
or evenopt-level = "z"`.
In some cases using opt-level=3 actually leads to smaller code sizes, presumably due to more inlining and dead code removal as a result.
The following are some example invocations of the cargo concordium binary's subcommand run.
shell
cargo concordium run init --context init-context.json --parameter parameter.bin --source ./simple_game.wasm --out state.bin --amount 123
with input files
json
{
"metadata": {
"slotNumber": 1,
"blockHeight": 1,
"finalizedHeight": 1,
"slotTime": "2021-01-01T00:00:01Z"
},
"initOrigin": "3uxeCZwa3SxbksPWHwXWxCsaPucZdzNaXsRbkztqUUYRo1MnvF"
}
and parameter.bin as
00001111aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
(as a text file without a newline).
shell
cargo concordium run receive --context receive-context.json --parameter parameter-receive.bin --source ./simple_game.wasm --state state-in.bin --amount 0 --name "receive_help_yourself" --balance 13 --out state-out.bin
where an example receive context is
json
{
"metadata": {
"slotNumber": 1,
"blockHeight": 1,
"finalizedHeight": 1,
"slotTime": "2021-01-01T00:00:01Z"
},
"invoker": "3uxeCZwa3SxbksPWHwXWxCsaPucZdzNaXsRbkztqUUYRo1MnvF",
"selfAddress": {"index": 0, "subindex": 0},
"selfBalance": 0,
"sender": {
"type": "Account",
"address": "3uxeCZwa3SxbksPWHwXWxCsaPucZdzNaXsRbkztqUUYRo1MnvF"
},
"owner": "3uxeCZwa3SxbksPWHwXWxCsaPucZdzNaXsRbkztqUUYRo1MnvF"
}
See --help or help option to cargo concordium run for an explanation of the options.
By default the compiled binary from a rust crate contains some information from the host machine, namely rust-related paths such as the path to .cargo. This can be seen by inspecting the produced binary:
Lets assume your username is tom and you have a smart contract foo located in your home folder, which you compiled in release-mode to WASM32.
By running the following command inside the foo folder, you will be able to see the paths included in the binary: strings target/wasm32-unknown-unknown/release/foo.wasm | grep tom
To remove the host information, the path prefixes can be remapped using a flag given to the compiler.
RUSTFLAGS=--remap-path-prefix=/home/tom=secret cargo build --release --target wasm32-unknown-unknown, where /home/tom is the prefix you want to change into secret.
The flag can be specified multiple times to remap multiple prefixes.
The flags can also be set permanently in the .cargo/config file in your crate, under the build section:
toml
[build]
rustflags = ["--remap-path-prefix=/home/tom=secret"]