Crate pallet_contracts

Contracts Pallet

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

• Config
• Call

Overview

This module extends accounts based on the [frame_support::traits::fungible] traits to have smart-contract functionality. It can be used with other modules that implement accounts based on the [frame_support::traits::fungible] traits. 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, and later retrievable via its hash. This means that multiple smart-contracts can be instantiated from the same hash, 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.

Weight

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

If the weight 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

• Pallet::instantiate_with_code - Deploys a new contract from the supplied Wasm binary, optionally transferring some balance. This instantiates a new smart contract account with the supplied code and calls its constructor to initialize the contract.
• Pallet::instantiate - The same as instantiate_with_code but instead of uploading new code an existing code_hash is supplied.
• Pallet::call - Makes a call to an account, optionally transferring some balance.
• Pallet::upload_code - Uploads new code without instantiating a contract from it.
• Pallet::remove_code - Removes the stored code and refunds the deposit to its owner. Only allowed to code owner.
• Pallet::set_code - Changes the code of an existing contract. Only allowed to Root origin.
• Pallet::migrate - Runs migration steps of current multi-block migration in priority, before [Hooks::on_idle][frame_support::traits::Hooks::on_idle] activates.

Usage

• ink! is language that enables writing Wasm-based smart contracts in plain Rust.

Re-exports

• pub use crate::debug::Tracing;
• pub use crate::migration::MigrateSequence;
• pub use crate::migration::Migration;
• pub use crate::migration::NoopMigration;
• pub use weights::WeightInfo;
• pub use crate::pallet::*;

Modules

• api_doc
  Documentation of the API (host functions) available to contracts.
• chain_extension
  A mechanism for runtime authors to augment the functionality of contracts.
• debug
• migration
  Multi-block Migration framework for pallet-contracts.
• pallet
  The pallet module in each FRAME pallet hosts the most important items needed to construct this pallet.
• test_utils
  Shared utilities for testing contracts. This is not part of the tests module because it is made public for other crates to use.
• weights
  Autogenerated weights for pallet_contracts

Macros

• build_runtime
• memory

Structs

• ApiVersion
  Defines the current version of the HostFn APIs. This is used to communicate the available APIs in pallet-contracts.
• CodeUploadReturnValue
  The result of successfully uploading a contract.
• ContractResult
  Result type of a bare_call or bare_instantiate call as well as ContractsApi::call and ContractsApi::instantiate.
• DefaultAddressGenerator
  Default address generator.
• Environment
  List of all runtime configurable types that are used in the communication between pallet-contracts and any given contract.
• EnvironmentType
  Wrapper around PhantomData to prevent it being filtered by scale-info.
• ExecReturnValue
  Output of a contract call or instantiation which ran to completion.
• Frame
  Represents one entry in the call stack.
• InstantiateReturnValue
  The result of a successful contract instantiation.
• InstructionWeights
  Gas metering of Wasm executed instructions is being done on the engine side. This struct holds a reference value used to gas units scaling between host and engine.
• Limits
  Describes the upper limits on various metrics.
• Schedule
  Definition of the cost schedule and other parameterizations for the wasm vm.

Enums

• Code
  Reference to an existing code hash or a new wasm module.
• CollectEvents
  Determines whether events should be collected during execution.
• ContractAccessError
  The possible errors that can happen querying the storage of a contract.
• DebugInfo
  Determines whether debug messages will be collected.
• Determinism
  Defines the required determinism level of a wasm blob when either running or uploading code.
• Origin
  The type of origins supported by the contracts pallet.
• StorageDeposit
  The amount of balance that was either charged or refunded in order to pay for storage.

Traits

• AddressGenerator
  Provides the contract address generation method.
• ContractsApi
  The API used to dry-run contract interactions.

Type Aliases

• CodeUploadResult
  Result type of a bare_code_upload call.
• ContractExecResult
  Result type of a bare_call call as well as ContractsApi::call.
• ContractInstantiateResult
  Result type of a bare_instantiate call as well as ContractsApi::instantiate.
• GetStorageResult
  Result type of a get_storage call.