Locally simulate contract functions

This guide is about how to locally simulate an invocation of some init or receive function from a Wasm smart contract module in a given context and state. This simulation is useful for inspecting a smart contract and the outcome in specific scenarios.

See also

For a guide on automated unit tests, see Unit test a contract in Rust.

Preparation

Make sure you have cargo-concordium installed, if not follow the guide Install tools for development. You will also need a smart contract module in Wasm to simulate.

Simulating instantiation

To simulate the instantiation of a smart contract instance using cargo-concordium, run the following command:

$cargo concordium run init --module contract.wasm \
                            --contract "my_contract" \
                            --context init-context.json \
                            --amount 123456.789 \
                            --parameter-bin parameter.bin \
                            --out-bin state.bin

init-context.json (used with the --context parameter) is a file that contains context information such as the current state of the chain, the sender of the transaction, and which account invoked this function. An example of this context could be:

{
    "metadata": {
        "slotTime": "2021-01-01T00:00:01Z"
    },
    "initOrigin": "3uxeCZwa3SxbksPWHwXWxCsaPucZdzNaXsRbkztqUUYRo1MnvF",
    "senderPolicies": [{
        "identityProvider": 1,
        "createdAt": "202012",
        "validTo": "202109"
    }]
}

See also

For a reference of the context see Simulation contexts.

Simulating updates

To simulate an update to a contract smart contract instance using cargo-concordium, run:

$cargo concordium run update --module contract.wasm \
                              --contract "my_contract" \
                              --func "some_receive" \
                              --context receive-context.json \
                              --amount 123456.789 \
                              --parameter-bin parameter.bin \
                              --state-bin state-in.bin \
                              --out-bin state-out.bin

receive-context.json (used with the --context parameter) is a file that contains context information such as the current state of the chain, the sender of the transaction, which account invoked this function, and which account or address that sent the current message. An example of this context could be:

{
    "metadata": {
        "slotTime": "2021-01-01T00:00:01Z"
    },
    "invoker": "3uxeCZwa3SxbksPWHwXWxCsaPucZdzNaXsRbkztqUUYRo1MnvF",
    "selfAddress": {"index": 0, "subindex": 0},
    "selfBalance": "0",
    "sender": {
        "type": "account",
        "address": "3uxeCZwa3SxbksPWHwXWxCsaPucZdzNaXsRbkztqUUYRo1MnvF"
    },
    "senderPolicies": [{
        "identityProvider": 1,
        "createdAt": "202012",
        "validTo": "202109"
    }],
    "owner": "3uxeCZwa3SxbksPWHwXWxCsaPucZdzNaXsRbkztqUUYRo1MnvF"
}

See also

For a reference of the context see Simulation contexts.

Support & Feedback

If you have questions or feedback, join us on Discourse, or contact us at support@concordium.software.