Crate concordium_smart_contract_testing

Expand description

§Concordium Smart Contract Testing

This library supports writing integration tests in Rust for Concordium smart contracts.

To use the library, you must add it to your Cargo.toml file under the [dev-dependencies] section. The library requries the rust edition 2021 or greater.

[package]
# ...
edition = "2021"

[dev-dependencies]
concordium-smart-contract-testing = "4.0"

§Basic usage

use concordium_smart_contract_testing::*;

// Create a "chain" with default parameters.
let mut chain = Chain::new();

// Define an account address to be used.
const ACC: AccountAddress = AccountAddress([0;32]);

// Create an account with 10000 CCD in balance.
chain.create_account(Account::new(ACC, Amount::from_ccd(1000)));

// Deploy a smart contract module (built with [Cargo Concordium](https://developer.concordium.software/en/mainnet/smart-contracts/guides/setup-tools.html#cargo-concordium)).
let deployment = chain
    .module_deploy_v1(
        Signer::with_one_key(),
        ACC,
        module_load_v1("path/to/contract.wasm.v1").unwrap())
    .unwrap();

// Initialize a smart contract from the deployed module.
let initialization = chain
    .contract_init(
        Signer::with_one_key(), // Used for specifying the number of signatures.
        ACC, // Invoker account.
        Energy::from(10000), // Maximum energy allowed for initializing.
        InitContractPayload {
            mod_ref: deployment.module_reference, // Module to initialize from.
            init_name: OwnedContractName::new_unchecked("init_my_contract".into()), // Contract to init.
            param: OwnedParameter::from_serial(&"my_param").unwrap(), // Any type implementing [`Serial`] can be used.
            amount: Amount::zero(), // CCD to send the contract.
        }
    )
    .unwrap();

// Update the initialized contract.
let update = chain
    .contract_update(
        Signer::with_one_key(), // Used for specifying the number of signatures.
        ACC, // Invoker account.
        Address::Account(ACC), // Sender (can also be a contract).
        Energy::from(10000),  // Maximum energy allowed for the update.
        UpdateContractPayload {
            address: initialization.contract_address, // The contract to update.
            receive_name: OwnedReceiveName::new_unchecked("my_contract.my_entrypoint".into()), // The receive function to call.
            message: OwnedParameter::from_serial(&42u8).unwrap(), // The parameter sent to the contract.
            amount: Amount::from_ccd(100), // Sending the contract 100 CCD.
        }
    )
    .unwrap();

// Check the trace elements produced (updates, interrupts, resumes, transfers, etc.).
assert!(matches!(update.effective_trace_elements().collect::<Vec<_>>()[..], [ContractTraceElement::Updated{..}]));

// Check the return value.
assert_eq!(update.return_value, to_bytes(&84u8));

// Check the balances of both contracts and accounts.
assert_eq!(chain.contract_balance(initialization.contract_address), Some(Amount::from_ccd(100)));
assert_eq!(chain.account_balance_available(ACC), Some(
    Amount::from_ccd(1000)
    - Amount::from_ccd(100) // Amount sent to contract.
    - deployment.transaction_fee
    - initialization.transaction_fee
    - update.transaction_fee));

Modules§

ed25519: We expose the PublicKey, SecretKey, SigningKey and Signature from the third-party ed25519_dalek crate here because these types appear in Concordium’s API.

Structs§

Account: An account.
AccountAccessStructure: The most straighforward account access structure is a map of public keys with the account threshold.
AccountAddress: Address of an account, as raw bytes.
AccountBalance: The current public balances of an account.
AccountDoesNotExist: The account does not exist.
AccountKeys: All account keys indexed by credentials.
AccountSignatures: A signature with account’s keys.
Amount: The type of amounts on the chain.
BlockTimeOverflow: The block time overflowed during a call to Chain::tick_block_time.
Chain: Represents the blockchain and supports a number of operations, including creating accounts, deploying modules, initializing contract, updating contracts and invoking contracts.
ChainBuilder: A builder for the Chain.
Contract: A smart contract instance.
ContractAddress: Address of a contract.
ContractDoesNotExist: The contract instance does not exist.
ContractEvent: An event logged by a smart contract initialization.
ContractInitError: An error that occurred in Chain::contract_init.
ContractInitSuccess: Represents a successful initialization of a contract.
ContractInvokeError: An error that occurred during a Chain::contract_update or Chain::contract_invoke.
ContractInvokeExternalSuccess: Represents a successful external contract invocation.
ContractInvokeSuccess: Represents a successful contract update (or invocation).
ContractModule: A smart contract module.
ContractName: A contract name. Expected format: “init_<contract_name>”.
CredentialIndex: Index of the credential that is to be used.
CredentialPublicKeys: Public credential keys currently on the account, together with the threshold needed for a valid signature on a transaction.
DebugItem: Information about the collected debug output. This is the item returned by the debug_events iterator. It corresponds to a section of execution between interrupts.
Duration: Duration of time in milliseconds.
Endpoint: Channel builder.
Energy: Energy measure.
EntrypointDoesNotExist: The entrypoint does not exist.
EntrypointName: An entrypoint name (borrowed version). Expected format: “<func_name>” where the name of the function consists solely of ASCII alphanumeric or punctuation characters.
ExchangeRate: An exchange rate between two quantities. This is never 0, and the exchange rate should also never be infinite.
ExchangeRateError: The provided exchange rates are not valid. Meaning that they do not correspond to one energy costing less than u64::MAX / 100_000_000_000.
ExecutionError: An error that occurred while executing a contract init or receive function.
ExternalAccountAddress: The address of an account on an external node.
ExternalContractAddress: The contract address of an contract on an external node.
ExternalNodeNotConfigured: The error returned when an external node has not been configured prior to using it.
HostCallInfo: Information about an emitted host function call. This is the item returned by the host_calls iterator.
InitContractPayload: Data needed to initialize a smart contract.
InstanceUpdatedEvent: Data generated as part of updating a single contract instance. In general a single Update transaction will generate one or more of these events, together with possibly some transfers.
InvokeExternalContractPayload: Data needed to invoke an external smart contract instance.
KeyIndex: Index of an account key that is to be used.
ModuleDeployError: An error that occurred while deploying a ContractModule.
ModuleDeploySuccess: Represents a successful deployment of a ContractModule.
ModuleDoesNotExist: The contract module does not exist.
ModuleInvalidError: The error produced when trying to parse a smart contract module.
ModuleLoadError: An error that can occur while loading a smart contract module.
ModuleReadError: The error produced when trying to read a smart contract module from a file.
OwnedContractName: A contract name (owned version). Expected format: “init_<contract_name>”.
OwnedEntrypointName: An entrypoint name (owned version). Expected format: “<func_name>”. Most methods on this type are available via the as_entrypoint_name and the methods on the EntrypointName type.
OwnedParameter: Parameter to the init function or entrypoint. Owned version.
OwnedReceiveName: A receive name (owned version). Expected format: “<contract_name>.<func_name>”. Most methods are available only on the ReceiveName type, the intention is to access those via the as_receive_name method.
Parameter: Parameter to the init function or entrypoint.
ReceiveName: A receive name. Expected format: “<contract_name>.<func_name>”.
Signer: A signer with a number of keys, the amount of which affects the cost of transactions.
Timestamp: Timestamp represented as milliseconds since unix epoch.
Transfer: A transfer from a contract to an account.
UpdateContractPayload: Data needed to update a smart contract instance.
ZeroKeysError: A Signer cannot be created with 0 keys.

Enums§

Address: Either an address of an account, or contract.
ChainBuilderError
ContractInitErrorKind: Types of errors that can occur in Chain::contract_init.
ContractInvokeErrorKind: The error kinds that can occur during Chain::contract_update or Chain::contract_invoke.
ContractInvokeExternalError: The error returned when external contract invocations fail.
ContractTraceElement: A successful contract invocation produces a sequence of effects on smart contracts and possibly accounts (if any contract transfers CCD to an account).
DebugOutputKind: The different types of debug output that can be printed by the print_debug method.
DebugTraceElement: A wrapper for ContractTraceElement, which provides additional information for testing and debugging. Most notably, it contains trace elements for failures, which are normally discarded by the node.
ExternalAddress: Either an external contract address or an external account address.
ExternalNodeError: Errors that occur while trying to communicate with an external node.
InitExecutionError: The reason for why a contract initialization failed during execution.
InvokeExecutionError: The reason for why a contract invocation failed during execution.
InvokeFailure: The kind of errors that may occur during handling of contract invoke or upgrade.
ModuleDeployErrorKind: The specific kind of error that occurred while deploying a ContractModule.
ModuleLoadErrorKind: The specific reason why loading a module failed.
OutputModuleLoadError
RejectReason: A reason for why a transaction was rejected. Rejected means included in a block, but the desired action was not achieved. The only effect of a rejected transaction is payment.
SetupExternalNodeError: Errors that occur while setting up the connection to an external node.
VerifyKey: Public AKA verification key for a given scheme. Only ed25519 is currently supported.
WasmVersion: Version of the module. This determines the chain API that the module can access.

Constants§

CONTRACT_MODULE_OUTPUT_PATH_ENV_VAR: The name of the environment variable that holds the path to the contract module file. To load the module, use the module_load_output function.

Traits§

DebugInfoExt: A trait implemented by types which can extract debug information from contract receive entrypoint executions.

Functions§

from_bytes: Dual to to_bytes.
is_debug_enabled: Return whether execution is running under cargo concordium test with debugging enabled.
module_load_output: Load the current smart contract module output using the environment variable CARGO_CONCORDIUM_TEST_MODULE_OUTPUT_PATH which is set when running using cargo concordium test.
module_load_v1: Load a v1 wasm module as it is output from cargo concordium build, i.e. including the prefix of 4 version bytes and 4 module length bytes.
module_load_v1_raw: Load a raw wasm module, i.e. one without the prefix of 4 version bytes and 4 module length bytes. The module still has to be a valid V1 smart contract module.
to_bytes: Serialize the given value to a freshly allocated vector of bytes using the provided Serial instance.

Type Aliases§

AccountThreshold: The minimum number of credentials that need to sign any transaction coming from an associated account.
BlockHash: Hash of a block.
ModuleReference: A reference to a smart contract module deployed on the chain.
SignatureThreshold: The minimum number of signatures on a credential that need to sign any transaction coming from an associated account.
SlotTime: Time at the beginning of the current slot, in miliseconds since unix epoch.

Crate concordium_smart_contract_testingCopy item path