Alexander Theißen
d98a3c7942
* contracts: Remove types and storage from the public interface * contracts: Remove current_schedule() getter * contracts: Improve documentation * Update README.md * Fix integration test
Contract Module
The Contract module provides functionality for the runtime to deploy and execute WebAssembly smart-contracts.
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.
One gas is equivalent to one weight which is defined as one picosecond of execution time on the runtime's reference machine.
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
Those are documented in the reference documentation.
Usage
This module executes WebAssembly smart contracts. These can potentially be written in any language
that compiles to web assembly. However, using a language that specifically targets this module
will make things a lot easier. One such language is ink
which is an eDSL that enables
writing WebAssembly based smart contracts in the Rust programming language.
Debugging
Contracts can emit messages to the node console when run on a development chain through the
seal_println API. This is exposed in ink! via
ink_env::debug_println().
In order to see these messages the log level for the runtime::contracts target needs to be raised
to at least the info level which is the default. However, those messages are easy to overlook
because of the noise generated by block production. A good starting point for contract debugging
could be:
cargo run --release -- --dev --tmp -lerror,runtime::contracts
License: Apache-2.0