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§
- We expose the
PublicKey
,SecretKey
, andSignature
from the third-partyed25519_dalek
crate here because these types appear in Concordium’s API.
Structs§
- An account.
- The most straighforward account access structure is a map of public keys with the account threshold.
- Address of an account, as raw bytes.
- The current public balances of an account.
- The account does not exist.
- All account keys indexed by credentials.
- A signature with account’s keys.
- The type of amounts on the chain
- The block time overflowed during a call to
Chain::tick_block_time
. - Represents the blockchain and supports a number of operations, including creating accounts, deploying modules, initializing contract, updating contracts and invoking contracts.
- A builder for the
Chain
. - A smart contract instance.
- Address of a contract.
- The contract instance does not exist.
- An event logged by a smart contract initialization.
- An error that occurred in
Chain::contract_init
. - Represents a successful initialization of a contract.
- An error that occurred during a
Chain::contract_update
orChain::contract_invoke
. - Represents a successful external contract invocation.
- Represents a successful contract update (or invocation).
- A smart contract module.
- A contract name. Expected format: “init_<contract_name>”.
- Index of the credential that is to be used.
- Public credential keys currently on the account, together with the threshold needed for a valid signature on a transaction.
- 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 of time in milliseconds.
- Channel builder.
- Energy measure.
- The entrypoint does not exist.
- An entrypoint name (borrowed version). Expected format: “<func_name>” where the name of the function consists solely of ASCII alphanumeric or punctuation characters.
- An exchange rate between two quantities. This is never 0, and the exchange rate should also never be infinite.
- 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
. - An error that occurred while executing a contract init or receive function.
- The address of an account on an external node.
- The contract address of an contract on an external node.
- The error returned when an external node has not been configured prior to using it.
- Information about an emitted host function call. This is the item returned by the
host_calls
iterator. - Data needed to initialize a smart contract.
- 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.
- Data needed to invoke an external smart contract instance.
- Index of an account key that is to be used.
- An error that occurred while deploying a
ContractModule
. - Represents a successful deployment of a
ContractModule
. - The contract module does not exist.
- The error produced when trying to parse a smart contract module.
- An error that can occur while loading a smart contract module.
- The error produced when trying to read a smart contract module from a file.
- A contract name (owned version). Expected format: “init_<contract_name>”.
- 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 theEntrypointName
type. - Parameter to the init function or entrypoint. Owned version.
- 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 theas_receive_name
method. - Parameter to the init function or entrypoint.
- A receive name. Expected format: “<contract_name>.<func_name>”.
- A signer with a number of keys, the amount of which affects the cost of transactions.
- Timestamp represented as milliseconds since unix epoch.
- A transfer from a contract to an account.
- Data needed to update a smart contract instance.
- A
Signer
cannot be created with0
keys.
Enums§
- Either an address of an account, or contract.
- Types of errors that can occur in
Chain::contract_init
. - The error kinds that can occur during
Chain::contract_update
orChain::contract_invoke
. - The error returned when external contract invocations fail.
- A successful contract invocation produces a sequence of effects on smart contracts and possibly accounts (if any contract transfers CCD to an account).
- The different types of debug output that can be printed by the
print_debug
method. - 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. - Either an external contract address or an external account address.
- Errors that occur while trying to communicate with an external node.
- The reason for why a contract initialization failed during execution.
- The reason for why a contract invocation failed during execution.
- The kind of errors that may occur during handling of contract
invoke
orupgrade
. - The specific kind of error that occurred while deploying a
ContractModule
. - The specific reason why loading a module failed.
- 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.
- Errors that occur while setting up the connection to an external node.
- Public AKA verification key for a given scheme. Only ed25519 is currently supported.
- Version of the module. This determines the chain API that the module can access.
Traits§
- A trait implemented by types which can extract debug information from contract receive entrypoint executions.
Functions§
- Dual to
to_bytes
. - Return whether execution is running under
cargo concordium test
with debugging enabled. - 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. - 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.
- Serialize the given value to a freshly allocated vector of bytes using the provided
Serial
instance.
Type Aliases§
- The minimum number of credentials that need to sign any transaction coming from an associated account.
- Hash of a block.
- A reference to a smart contract module deployed on the chain.
- The minimum number of signatures on a credential that need to sign any transaction coming from an associated account.
- Time at the beginning of the current slot, in miliseconds since unix epoch.