Crate pallet_contracts

Contract Module

The Contract module provides functionality for the runtime to deploy and execute WebAssembly smart-contracts.

• contract::Trait
• Call

Overview

This module extends accounts based on the Currency trait to have smart-contract functionality. It can be used with other modules that implement accounts based on Currency. These "smart-contract accounts" have the ability to instantiate smart-contracts and make calls to other contract and non-contract accounts.

The smart-contract code is stored once in a code_cache, and later retrievable via its code_hash. This means that multiple smart-contracts can be instantiated from the same code_cache, without replicating the code each time.

When a smart-contract is called, its associated code is retrieved via the code hash and gets executed. This call can alter the storage entries of the smart-contract account, instantiate new smart-contracts, or call other smart-contracts.

Finally, when an account is reaped, its associated code and storage of the smart-contract account will also be deleted.

Gas

Senders must specify a gas limit with every call, as all instructions invoked by the smart-contract require gas. Unused gas is refunded after the call, regardless of the execution outcome.

If the gas limit is reached, then all calls and state changes (including balance transfers) are only reverted at the current call's contract level. For example, if contract A calls B and B runs out of gas mid-call, then all of B's calls are reverted. Assuming correct error handling by contract A, A's other calls and state changes still persist.

Notable Scenarios

Contract call failures are not always cascading. When failures occur in a sub-call, they do not "bubble up", and the call will only revert at the specific contract level. For example, if contract A calls contract B, and B fails, A can decide how to handle that failure, either proceeding or reverting A's changes.

Interface

Dispatchable functions

• put_code - Stores the given binary Wasm code into the chain's storage and returns its code_hash.
• instantiate - Deploys a new contract from the given code_hash, optionally transferring some balance. This instantiates a new smart contract account and calls its contract deploy handler to initialize the contract.
• call - Makes a call to an account, optionally transferring some balance.

Signed Extensions

The contracts module defines the following extension:

• CheckBlockGasLimit: Ensures that the transaction does not exceeds the block gas limit.

The signed extension needs to be added as signed extra to the transaction type to be used in the runtime.

Usage

The Contract module is a work in progress. The following examples show how this Contract module can be used to instantiate and call contracts.

• ink is an eDSL that enables writing WebAssembly based smart contracts in the Rust programming language. This is a work in progress.

Related Modules

• Balances

Macros

convert_args
define_func
gen_signature
gen_signature_dispatch
match_tokens	A simple utility macro that helps to match against a list of tokens.
register_func
try_or_exec_error	Evaluate an expression of type Result<_, &'static str> and either resolve to the value if Ok or wrap the error string into an ExecutionError with the provided buffer and return from the enclosing function. This macro is used instead of .map_err(..)? in order to avoid taking ownership of buffer unless there is an error.
unmarshall_then_body_then_marshall

Structs

AccountCounter	The subtrie counter.
CheckBlockGasLimit	SignedExtension that checks if a transaction would exhausts the block gas limit.
CodeStorage	A mapping between an original code hash and instrumented wasm code, ready for execution.
Config	In-memory cache of configuration values.
ContractInfoOf	The code associated with a given account.
DefaultBlockGasLimit	A reasonable default value for Trait::BlockGasLimit.
DefaultCallBaseFee	A reasonable default value for Trait::CallBaseFee.
DefaultContractFee	A reasonable default value for Trait::ContractFee.
DefaultDispatchFeeComputor	The default dispatch fee computor computes the fee in the same way that the implementation of ChargeTransactionPayment for the Balances module does. Note that this only takes a fixed fee based on size. Unlike the balances module, weight-fee is applied.
DefaultInstantiateBaseFee	A reasonable default value for Trait::InstantiateBaseFee.
DefaultInstantiationFee	A reasonable default value for [Trait::InstantiationFee].
DefaultMaxDepth	A reasonable default value for Trait::MaxDepth.
DefaultMaxValueSize	A reasonable default value for Trait::MaxValueSize.
DefaultRentByteFee	A reasonable default value for Trait::RentByteFee.
DefaultRentDepositOffset	A reasonable default value for Trait::RentDepositOffset.
DefaultSignedClaimHandicap	A reasonable default value for [Trait::SignedClaimedHandicap].
DefaultStorageSizeOffset	A reasonable default value for Trait::StorageSizeOffset.
DefaultSurchargeReward	A reasonable default value for Trait::SurchargeReward.
DefaultTombstoneDeposit	A reasonable default value for Trait::TombstoneDeposit.
DefaultTransactionBaseFee	A reasonable default value for Trait::TransactionBaseFee.
DefaultTransactionByteFee	A reasonable default value for Trait::TransactionByteFee.
DefaultTransferFee	A reasonable default value for [Trait::TransferFee].
ExecError	An error indicating some failure to execute a contract call or instantiation. This can include VM-specific errors during execution (eg. division by 0, OOB access, failure to satisfy some precondition of a system call, etc.) or errors with the orchestration (eg. out-of-gas errors, a non-existent destination contract, etc.).
ExecReturnValue	Output of a contract call or instantiation which ran to completion.
GasMeter
GenesisConfig	Genesis config for the module, allow to build genesis storage.
Module	Contracts module.
PristineCode	A mapping from an original code hash to the original code, untouched by instrumentation.
RawAliveContractInfo	Information for managing an account and its sub trie abstraction. This is the required info to cache for an account.
RawTombstoneContractInfo
Schedule	Definition of the cost schedule and other parameterizations for wasm vm.
SimpleAddressDeterminer	Simple contract address determiner.
TrieIdFromParentCounter	Get trie id from account_id.

Enums

Call	Dispatchable calls.
ContractInfo	Information for managing an account and its sub trie abstraction. This is the required info to cache for an account
Error	Error for the contracts module.
RawEvent	Events for this module.

Traits

ComputeDispatchFee	A function that returns the fee for dispatching a Call.
ContractAddressFor	A function that generates an AccountId for a contract upon instantiation.
Trait
TrieIdGenerator	Get a trie id (trie id must be unique and collision resistant depending upon its context). Note that it is different than encode because trie id should be collision resistant (being a proper unique identifier).

Type Definitions

AliveContractInfo
BalanceOf
CodeHash
Event	RawEvent specialized for the configuration Trait
ExecResult
Gas
NegativeImbalanceOf
StatusCode	A status code return to the source of a contract call or instantiation indicating success or failure. A code of 0 indicates success and that changes are applied. All other codes indicate failure and that changes are reverted. The particular code in the case of failure is opaque and may be interpreted by the calling contract.
TombstoneContractInfo
TrieId